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.
189 lines
6.6 KiB
Markdown
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.
|