Files
pages/docs/design/data-cli.md
T
Anya Tokugawa d5d21b7841
Build and publish container images / images (push) Successful in 9m34s
Release container images / release (push) Successful in 36s
Refactor architecture into eight components and consolidate reliability work
Extract Grammaratur, Dregarnuhr, Geduldh, Mestionora, Ordoschnellic, Schutzaria, Kunstzeal and Seheweit behind compatible application contracts.

Include accumulated editor resilience, navigation and theme UX, remote CLI, storage/schema and DR groundwork, tests and design/operations documentation.

Verified: uncached full Go suite; go vet ./...; race tests for all eight components; 11 targeted Chromium tests; Node suites; 19 Python CLI tests; reproducible editor build. No push, release tag or deployment in this checkpoint.
2026-11-01 15:23:31 +09:00

189 lines
6.6 KiB
Markdown

# Data CLI
Remote HTTP access is a separate subproject, `pages-cli`, with the `pages`
command (`pages-cli/pages`); see the
[remote CLI contract and usage](ja/remote-cli.md). This local tool retains its
trusted administrative database access and does not acquire Web credentials.
`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.