Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming. Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
184 lines
6.3 KiB
Markdown
184 lines
6.3 KiB
Markdown
# Data CLI
|
|
|
|
`data/pageswiki-cli` is a local administrative data surface. It provides
|
|
rsync-like one-shot transfers and an interactive Semantic Path shell.
|
|
|
|
It accesses:
|
|
|
|
- metadata in `pages.db`;
|
|
- immutable payloads in `documents/sha256/`;
|
|
- mutable Asset HEAD metadata in `assets`.
|
|
|
|
The implementation uses Python's standard library only.
|
|
|
|
## Invocation modes
|
|
|
|
### One-shot
|
|
|
|
```bash
|
|
data/pageswiki-cli get path:/manual/start start.html
|
|
data/pageswiki-cli put start.html path:/manual/start
|
|
```
|
|
|
|
Transfers compare SHA-256 before writing. Identical content is reported as
|
|
`skipped` and does not create another Revision.
|
|
|
|
### Interactive shell
|
|
|
|
```bash
|
|
data/pageswiki-cli shell
|
|
```
|
|
|
|
Invoking without arguments also opens the shell when stdin is a terminal.
|
|
The shell maintains a Semantic Path working directory:
|
|
|
|
```text
|
|
pages:/> cd /manual
|
|
pages:/manual> ls
|
|
pages:/manual> view start
|
|
```
|
|
|
|
The shell uses `readline` when available:
|
|
|
|
- Up/Down traverse command history.
|
|
- Tab completes commands, Semantic Paths, UUIDs, Revisions, Assets, and local
|
|
transfer paths.
|
|
- History persists in `~/.pageswiki_history`, or the path specified by
|
|
`PAGESWIKI_HISTORY`.
|
|
|
|
## Commands
|
|
|
|
| Command | Behavior |
|
|
| --- | --- |
|
|
| `ls [PATH]` | List direct Semantic Path children |
|
|
| `cd PATH` | Change shell Semantic Path |
|
|
| `mv SOURCE DEST` | Move a Path and its descendants transactionally |
|
|
| `view [ADDRESS]` | Display metadata and send payload to `PAGER` on a TTY |
|
|
| `cat [ADDRESS]` | Write only the canonical payload to stdout |
|
|
| `edit [ADDRESS]` | Edit through `EDITOR` and write back changed content |
|
|
| `get ADDRESS [LOCAL]` | Download one payload |
|
|
| `put LOCAL ADDRESS` | Upload a Page Revision or update an Asset HEAD |
|
|
| `mget REMOTE_PATTERN [DIR]` | Download matching Semantic Paths |
|
|
| `mput LOCAL_GLOB REMOTE_DIR` | Upload matching local files |
|
|
| `revision [ADDRESS]` | List a Page's immutable Revision history |
|
|
| `diff REV REV` | Produce a unified Document diff |
|
|
| `restore REV` | Create a new Revision from an old Revision |
|
|
| `link ADDRESS PATH` | Add a Semantic Path projection |
|
|
| `unlink PATH [ADDRESS]` | Remove a Path projection only |
|
|
| `pwd` | Show the shell Semantic Path |
|
|
|
|
`put` and `mput` infer a Revision Content-Type from the local filename, with
|
|
the destination Semantic Path as a fallback. Markdown input is converted to
|
|
canonical HTML and loses only its `.md` / `.markdown` Semantic Path suffix.
|
|
Other extensions remain part of the Path. Binary payloads are stored as
|
|
immutable Documents and retain their original filename and Content-Type.
|
|
| `help` | Show usage |
|
|
| `exit`, `quit` | Leave the shell |
|
|
|
|
`get ADDRESS -` writes to stdout and `put - ADDRESS` reads from stdin.
|
|
Unlike `view`, `cat` never invokes a pager and is suitable for pipelines.
|
|
|
|
## Supported addresses
|
|
|
|
| Address | Meaning |
|
|
| --- | --- |
|
|
| `path:/...` | Mutable Semantic Path projection |
|
|
| `uuid:<uuid>` | Stable Page/Object identity |
|
|
| `rev:<uuid>` | Immutable Revision identity |
|
|
| `asset:<type>:<name>` | Mutable Asset HEAD |
|
|
|
|
A single address without a command retains the earlier inspection behavior.
|
|
|
|
## Write semantics
|
|
|
|
### Page `put`
|
|
|
|
1. Resolve `path:` or `uuid:`.
|
|
2. Create a Page UUID and Path binding if a Path does not exist.
|
|
3. Hash the input and atomically persist its immutable Document.
|
|
4. Compare with the newest Revision in `PAGESWIKI_LANG`.
|
|
5. Skip identical content or create a new Revision UUID.
|
|
|
|
Page payloads must be UTF-8. Binary data belongs in an `asset:` address.
|
|
|
|
### Asset `put`
|
|
|
|
1. Hash and atomically persist arbitrary bytes.
|
|
2. Create the Asset identity if absent.
|
|
3. Skip an identical HEAD or update `head_document_hash`.
|
|
|
|
### `edit`
|
|
|
|
1. Resolve the current canonical payload.
|
|
2. Write it to a private temporary file.
|
|
3. Invoke the command in `EDITOR`.
|
|
4. Apply Page or Asset `put` semantics when the editor exits successfully.
|
|
5. Skip unchanged content and remove the temporary file.
|
|
|
|
Immutable `rev:` addresses cannot be edited.
|
|
|
|
### `mv`
|
|
|
|
- Semantic root cannot be moved.
|
|
- A destination cannot be inside its source.
|
|
- Every destination is collision-checked before mutation.
|
|
- A unique temporary namespace avoids primary-key collisions.
|
|
- All Path updates commit in one SQLite transaction.
|
|
|
|
### `restore`
|
|
|
|
Restore never rewrites history. It reads the selected immutable Revision and
|
|
creates a new Revision on the same Page with the same language.
|
|
|
|
### `link` and `unlink`
|
|
|
|
These commands mutate reachability only. They never delete the Page,
|
|
Revisions, or Documents. An unlinked Page may become a zombie and remains
|
|
recoverable by UUID until garbage collection.
|
|
|
|
## Consistency and safety
|
|
|
|
- SQLite writes use explicit transactions and a busy timeout.
|
|
- The CLI initializes the additive `assets` table when absent; core schema
|
|
migrations remain owned by the server.
|
|
- Documents use temporary files, `fsync`, and atomic replacement.
|
|
- Payload hashes are verified on every read.
|
|
- Revision addresses reject writes.
|
|
- rsync-like transfers skip identical hashes.
|
|
- Missing canonical Documents may use the transitional SQLite body only when
|
|
its SHA-256 matches.
|
|
|
|
This CLI is a trusted local administrative interface and intentionally bypasses
|
|
future HTTP Capability evaluation. Filesystem and database permissions define
|
|
who may use it.
|
|
|
|
## Environment
|
|
|
|
| Variable | Meaning |
|
|
| --- | --- |
|
|
| `PAGESWIKI_DATA_DIR` | Directory containing `pages.db` and `documents/` |
|
|
| `PAGESWIKI_DB` | Explicit SQLite path |
|
|
| `PAGESWIKI_DOCUMENTS_DIR` | Explicit Document root |
|
|
| `PAGESWIKI_LANG` | Language used for selection and Page writes |
|
|
| `PAGER` | Pager invoked by `view` on an interactive terminal |
|
|
| `EDITOR` | Editor invoked by `edit` |
|
|
| `PAGESWIKI_HISTORY` | Interactive command-history file |
|
|
|
|
## Asset metadata
|
|
|
|
The normative Asset lifecycle and authorization model are defined in
|
|
[`asset-model.md`](asset-model.md). The CLI is a trusted local implementation
|
|
of HEAD reads and updates, not the public Asset API.
|
|
|
|
| Column | Meaning |
|
|
| --- | --- |
|
|
| `domain_uuid` | Domain containing the mutable Asset name |
|
|
| `address` | Canonical Domain-local `asset:` address |
|
|
| `object_uuid` | Stable owning Object UUID |
|
|
| `head_document_hash` | Current immutable Document snapshot |
|
|
| `created_at_ms` | Creation timestamp |
|
|
| `updated_at_ms` | HEAD update timestamp |
|
|
|
|
Administrator HTTP Asset mutation is available with Domain/Campus-admin checks
|
|
and ETag preconditions. The CLI remains the trusted local bulk interface.
|