Files
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

6.6 KiB

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. 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

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

data/pageswiki-cli shell

Invoking without arguments also opens the shell when stdin is a terminal. The shell maintains a Semantic Path working directory:

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.

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. 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.