@everfir/az8-cli 0.1.0 → 0.2.0-preview.1

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable AZ8 CLI changes are recorded here. The CLI package has its own linear version sequence;
+it does not inherit the Web application or monorepo root version.
+
+## 0.2.0-preview.1 - 2026-07-21
+
+First installable internal preview.
+
+### Added
+
+- Project list, detail, create, and rename commands.
+- Persistent NDJSON stdio Canvas client with lifecycle, awareness, observations, Receipts,
+  reconnect, explicit shutdown, backpressure, and authenticated actor identity.
+- One-shot wrappers over the same Canvas Client and semantic Operation Registry.
+- Note lifecycle, non-World hierarchy, History, summary/detail inspection, and Core Node placement.
+- Generation Planning, Draft editing, Visual References, Workflow start, status query, and bounded
+  wait semantics with credit-usage information.
+- Public media URL import and safe local image/video/audio upload and download.
+
+### Safety and compatibility
+
+- Canvas writes are available only through semantic Operations and Commands.
+- Writes are serialized, never automatically retried, and isolate the Canvas context after an
+  indeterminate result. Read retry remains bounded.
+- Tokens are accepted only through environment variables or env files and are redacted from
+  program interaction and diagnostics.
+- 3D World, Asset aggregate management, automatic layout, media replacement, and batch upload are
+  intentionally not part of this preview.

package/README.md

@@ -0,0 +1,330 @@
+# AZ8 CLI
+
+AZ8 CLI is a semantic Project Canvas client for agents. It does not import Web implementation code
+and does not expose raw backend, Yjs, or document mutation commands.
+
+## Install the internal preview
+
+AZ8 CLI requires Node.js 20 or newer. Install the preview channel from the configured npm registry:
+
+```bash
+npm install --global @everfir/az8-cli@preview
+az8 --version
+az8 help
+```
+
+For a supplied release artifact, install the exact immutable tarball instead:
+
+```bash
+npm install --global ./everfir-az8-cli-0.2.0-preview.1.tgz
+az8 --version
+```
+
+`az8 --version` must report the version selected for the agent environment. Preview releases do not
+replace npm's `latest` channel. Pin an exact version or tarball for reproducible agent runs.
+
+## Credentials and environment
+
+Use an ignored `.env.local` or process environment:
+
+```dotenv
+AZ8_TOKEN=...
+AZ8_ENVIRONMENT=test
+```
+
+`AZ8_ENVIRONMENT` accepts `test` or `production`. Command-line `--environment` overrides the env
+value. Tokens must not be passed through argv or stdio protocol payloads.
+
+## Project Management
+
+```bash
+az8 projects list --scope owned
+az8 projects get <project-id>
+az8 projects create --name "CLI iteration"
+az8 projects rename <project-id> --name "New name"
+```
+
+List output is compact and paginated with an opaque cursor. Get returns detail including the current
+collaboration route. Project writes never retry automatically; an uncertain response is reported as
+indeterminate.
+
+## First agent loop
+
+A new agent needs only the installed package, a token, and this document. Start by creating its own
+Project and retaining the returned `project.id`:
+
+```bash
+az8 projects create --name "Agent preview workspace"
+az8 canvas query <project-id> capabilities.summary
+printf '%s\n' '{"text":"Release smoke note","position":{"x":160,"y":160}}' \
+  | az8 canvas operation <project-id> createNote \
+      --input-stdin --request-id preview-note-1
+```
+
+For a long-lived collaborative context, start `az8 canvas open <project-id> --write --format ndjson`,
+read its `hello` frame, send the documented `initialize` request, and wait for `ready` before sending
+queries or Operations. Keep the process and stdin/stdout pipes alive to preserve awareness, local
+History, Receipts, observations, and request replay.
+
+For generation, create an image target and call `planGeneration` with the returned View Node and a
+prompt. Execute its returned `plan.operations` in order, stopping after the first failure. A
+successful `startGeneration` Receipt contains the Workflow Run identity; call `waitWorkflowRun`
+separately when a terminal output is required. Planning and starting are intentionally not one
+transaction.
+
+For media transfer, `canvas upload` places a verified local image/video/audio file through the
+server-owned Core Node path. After detail query resolves the target's `resolvedCoreNodeId`, `canvas
+download` saves that current output to a new local file. Both commands return structured metadata so
+the agent can verify identities, byte count, MIME, and SHA-256.
+
+## One-shot Canvas wrapper
+
+One-shot commands open a real Canvas client, complete synchronization and hydration, invoke the same
+query or Operation used by the persistent client, and close after the result is authoritative:
+
+```bash
+az8 canvas query <project-id> canvas.summary
+az8 canvas query <project-id> canvas.detail --view-node-id <view-node-id>
+printf '%s\n' '{"text":"idea","position":{"x":160,"y":160}}' \
+  | az8 canvas operation <project-id> createNote --input-stdin --request-id create-1
+az8 canvas operation <project-id> startGeneration \
+  --input-json '{"viewNodeId":"<target-id>"}'
+```
+
+Operation input is one JSON object supplied by exactly one of `--input-stdin`, `--input-file`, or
+`--input-json`; omitted input defaults to `{}`. Input is limited to one MiB. `--timeout-ms` controls
+the same Operation acknowledgement or domain observation window as persistent stdio, and
+`--client-name` changes only the ephemeral awareness display name.
+
+Success writes one `az8.canvas.one-shot.v1` JSON document to stdout and exits `0`. A definitive
+input, validation, permission, or business failure writes structured JSON to stderr and exits `1`.
+Connection loss, acknowledgement loss, timeout with unknown effects, or another indeterminate
+lifecycle outcome writes its Receipt or structured error to stderr and exits `2`; mutating
+Operations are never automatically retried.
+
+The wrapper adds no Canvas protocol or business logic. Its query and Operation paths share
+`CanvasClient`, Canvas Session, Operation Registry, domain validation, Commands, acknowledgement,
+and Receipt construction with persistent stdio. Consequently `startGeneration` returns after the Run
+start and immediate Canvas effects are acknowledged; waiting for generation remains a separate
+`waitWorkflowRun` call.
+
+Each one-shot invocation is a fresh runtime. It therefore does not expose `undo`, `redo`,
+`receipts.summary`, or `receipt.detail`: local Canvas History and the Receipt Log belong to one
+persistent process and are not fabricated across processes. `--request-id` labels the single
+attempt's returned Receipt, but initial one-shot commands do not promise cross-process request replay
+or durable idempotency. Use `canvas open` when an interaction requires History, Receipt lookup,
+observations, or a long-lived awareness identity.
+
+## Local media upload
+
+Upload one explicit local image, video, or audio file as a new Canvas resource:
+
+```bash
+az8 canvas upload <project-id> \
+  --file ./reference.png \
+  --idempotency-key reference-image-1 \
+  --name "Reference image" \
+  --position-x 640 --position-y 160
+```
+
+This is a convenience wrapper over the public `uploadMedia` Operation, not a separate backend
+shortcut. The wrapper resolves `--file` to the Operation's adapter-owned `source` reference; the
+environment-neutral Canvas Runtime never interprets a local path. The file must be a non-empty
+regular non-symlink file whose bytes identify it as image, video, or audio media. Content type,
+extension, MIME, byte count, and SHA-256 come from inspection rather than caller claims.
+
+The Operation follows Web's product sequence: create one undoable `pending` View Node, request a
+presigned upload, stream one credential-free PUT, call Project Content upload completion so the
+server creates the Core Node and binding, then silently mark the View Node `ready`. A known failure
+silently marks the same node `failed`. A lost presign, PUT, Project Content, or collaboration write
+response leaves it `pending`, returns an indeterminate Receipt, takes the Canvas context offline,
+and is never automatically retried.
+
+`--idempotency-key` is required and identifies the logical upload independently from the Operation
+Receipt's `--request-id`. Explicit replay with the same normalized file and key first reconciles
+Project Content through a deterministic, opaque intent fingerprint in its source identity; an
+existing binding returns without another upload, while conflicting key reuse fails. Results include
+View Node/Core Node identities and reproducible file metadata but never the presigned or permanent
+file URL. The wrapper uses the standard `az8.canvas.one-shot.v1` output and exit codes and defaults
+to a 300-second deadline. Batch upload, replacement, text-file import, and a durable local upload
+cache are outside the initial slice.
+
+## Local media download
+
+Download the current image, video, or audio represented by a View Node, or select an explicit Core
+Node within the Project context:
+
+```bash
+az8 canvas download <project-id> --view-node-id <view-node-id> --output ./result.png
+az8 canvas download <project-id> --core-node-id <core-node-id> --output ./result.mp4
+```
+
+Exactly one source selector and one explicit output path are required. A View Node resolves through
+its current Project Content output, including the compatible display-reference fallback; the CLI
+then reads that Core Node through the same public `getCoreNode` Operation. This command does not
+expose arbitrary URLs, mutate Canvas state, or add content to an Asset.
+
+The command opens and hydrates one real collaboration context to resolve the source, then closes it
+before transferring the media. The media request carries no AZ8 token or collaboration credential.
+The response streams into a mode-`0600` temporary file beside the destination, verifies byte count
+and image/video/audio type, computes SHA-256, and only then commits to the final path. Existing paths
+are rejected by default. `--overwrite` may atomically replace an existing regular file, but never a
+directory or symbolic link. A failed, interrupted, or timed-out transfer leaves no partial final
+file and preserves an existing destination.
+
+Success writes one `az8.canvas.media-download.v1` document with the absolute path, byte count,
+SHA-256, detected MIME/extension, response metadata, resolved Core Node identity, and whether a file
+was replaced. It deliberately omits the media URL. Exit `0` is success; exit `1` is a definitive
+source, HTTP 4xx, or local-path failure; exit `2` is a retryable connection, HTTP 429/5xx, transfer,
+integrity, or timeout failure; exit `130` is caller cancellation. Downloads are never automatically
+retried. After any non-success, the agent must decide whether a new invocation is safe.
+
+## Persistent Canvas client
+
+```bash
+az8 canvas open <project-id> --write --format ndjson
+```
+
+The process writes one `hello` frame, then waits for an `initialize` request on stdin:
+
+```json
+{"protocolVersion":"1.0","requestId":"init-1","type":"initialize","payload":{"projectId":"<project-id>","client":{"name":"my-agent"},"observationPreset":"compact"}}
+```
+
+Before readiness the client hydrates the current authenticated account profile. Canvas Operations use
+that immutable account id and display name for persisted creator data. The `client.name` supplied by
+`initialize` is awareness-only and cannot impersonate or rename the persisted author. Project owner
+metadata is likewise never treated as the current actor on shared Projects.
+
+After `ready`, requests use `query`, `configureObservations`, `operation`, `reconnect`, or `shutdown`.
+The public authoring surface includes the note lifecycle, non-World View Node hierarchy operations,
+and the Stage 3 Core Node creative loop. Hierarchy operations are `groupViewNodes`,
+`ungroupViewNode`, `moveViewNodes` with an optional `targetParentId`, and
+`updateViewNodeStacking`. Core Node operations are `getCoreNode`, `placeCoreNode`,
+`createMediaTarget`, `planGeneration`, `importExternalMedia`, `uploadMedia`, `editGenerationDraft`,
+`addVisualReference`, `removeVisualReference`, `startGeneration`, `getWorkflowRun`, and
+`waitWorkflowRun`. Capability detail is discoverable through `capabilities.detail`; callers should
+use it instead of hard-coding input schemas. Workflow Definitions are available through
+`workflowDefinitions.summary` and `workflowDefinition.detail` queries.
+
+Before editing a Draft, an agent can call the read-only `planGeneration` Operation for an existing
+media target. It recommends a Definition from the target and resolved Visual Reference modalities,
+constructs configuration defaults, validates required inputs, and returns compact alternatives plus
+an ordered semantic Operation sequence. Use `detail: "detail"` to include slot and configuration
+field metadata, including dynamic enum options. Planning never creates a Core Node or changes the
+Canvas; returned Operations still execute independently and stop at the first failure.
+
+```json
+{"protocolVersion":"1.0","requestId":"plan-1","type":"operation","payload":{"name":"planGeneration","input":{"targetViewNodeId":"<target-id>","prompt":"A quiet observatory","references":[{"viewNodeId":"<reference-id>"}],"detail":"detail"}}}
+```
+
+`editNoteContent`, `renameViewNode`, and `resizeViewNodes` match Web's silent History policy.
+`duplicateViewNodes` and `removeViewNodes` are undoable. Removal atomically cleans Draft references
+from surviving nodes. Duplication supports notes and non-World resource nodes; resource copies retain
+the currently displayed Project Content output without cloning a Core Node or creating Project
+Content. Grouping, ungrouping, reparenting, and stacking are also undoable. Their inputs use absolute
+canvas coordinates even though grouped children are persisted relative to their parent. Reparenting
+preserves absolute placement, expands a destination group when needed without shrinking it, and
+removes a source group only when the move leaves it empty. Group nodes cannot be nested, and stacking
+is scoped to siblings with the same parent. Decoration, Asset, and all World targets remain deferred.
+
+Example write:
+
+```json
+{"protocolVersion":"1.0","requestId":"create-1","type":"operation","payload":{"name":"createNote","input":{"text":"idea","position":{"x":160,"y":160}}}}
+```
+
+Example Stage 2 edits:
+
+```json
+{"protocolVersion":"1.0","requestId":"edit-1","type":"operation","payload":{"name":"editNoteContent","input":{"viewNodeId":"view_node_1","text":"revised idea"}}}
+{"protocolVersion":"1.0","requestId":"resize-1","type":"operation","payload":{"name":"resizeViewNodes","input":{"resizes":[{"viewNodeId":"view_node_1","size":{"width":420,"height":360}}]}}}
+{"protocolVersion":"1.0","requestId":"duplicate-1","type":"operation","payload":{"name":"duplicateViewNodes","input":{"viewNodeIds":["view_node_1"]}}}
+```
+
+Example hierarchy sequence (each successful write is one independent undoable interaction):
+
+```json
+{"protocolVersion":"1.0","requestId":"group-1","type":"operation","payload":{"name":"groupViewNodes","input":{"viewNodeIds":["view_node_1","view_node_2"],"name":"References"}}}
+{"protocolVersion":"1.0","requestId":"reparent-1","type":"operation","payload":{"name":"moveViewNodes","input":{"moves":[{"id":"view_node_3","position":{"x":640,"y":360},"targetParentId":"<group-id>"}]}}}
+{"protocolVersion":"1.0","requestId":"front-1","type":"operation","payload":{"name":"updateViewNodeStacking","input":{"viewNodeId":"view_node_3","direction":"front"}}}
+{"protocolVersion":"1.0","requestId":"ungroup-1","type":"operation","payload":{"name":"ungroupViewNode","input":{"groupViewNodeId":"<group-id>"}}}
+```
+
+Example Stage 3 generation sequence (each line is a separate ordered interaction):
+
+```json
+{"protocolVersion":"1.0","requestId":"target-1","type":"operation","payload":{"name":"createMediaTarget","input":{"contentType":"image"}}}
+{"protocolVersion":"1.0","requestId":"draft-1","type":"operation","payload":{"name":"editGenerationDraft","input":{"viewNodeId":"<target-id>","definitionId":"<definition-id>","prompt":"A quiet observatory","config":{"aspect_ratio":"16:9"}}}}
+{"protocolVersion":"1.0","requestId":"start-1","type":"operation","payload":{"name":"startGeneration","input":{"viewNodeId":"<target-id>"}}}
+{"protocolVersion":"1.0","requestId":"wait-1","type":"operation","payload":{"name":"waitWorkflowRun","input":{"workflowRunId":"<run-id>"},"timeoutMs":120000}}
+```
+
+Example public media URL import:
+
+```json
+{"protocolVersion":"1.0","requestId":"import-1","type":"operation","payload":{"name":"importExternalMedia","input":{"contentType":"image","idempotencyKey":"reference-image-1","url":"https://example.com/reference.png","name":"Reference image","position":{"x":640,"y":160}}}}
+```
+
+`idempotencyKey` is required. Repeating the same normalized input returns the existing View Node and
+Core Node without another write; reusing the key for different input fails. Image, video, and audio
+are supported. The URL is referenced directly—this operation neither uploads a file nor adds the
+Core Node to an Asset. Known failures leave one inspectable `failed` View Node that can be resumed by
+explicitly submitting the same input. An uncertain backend or collaboration outcome leaves the node
+`pending`, takes the context offline, and is never retried automatically.
+
+`startGeneration` succeeds when the server accepts the Workflow Run and the immediate Canvas facts
+are acknowledged. It first estimates the exact current Draft inputs, then materializes literal Core
+Nodes and starts with the estimate's cost and Definition version. This estimate is internal: there is
+no public estimate Operation, balance query, caller-supplied expected cost, or second confirmation.
+Waiting for a terminal result is deliberately a separate operation. Generation is a non-undoable
+Canvas History barrier. The CLI does not expose Assets, arbitrary Core Node creation, or 3D World
+operations.
+
+Initial connection and explicit reconnect recover every Workflow Run referenced by the Canvas
+pending set before reporting `ready`. Pending/running Runs receive one live subscription; Runs that
+completed while the CLI was offline refresh Project Content and clear their pending Canvas fact
+through a semantic Command. Status-stream read recovery is bounded. Exhaustion, or an indeterminate
+pending-fact cleanup acknowledgement, closes the Canvas context and requires explicit reconnect.
+Cleanup writes are not automatically retried.
+
+`waitWorkflowRun` uses `timeoutMs` as a caller-selected observation window. If that window expires
+while the Run is still authoritatively pending or running, the request fails ordinarily, the Canvas
+context remains ready, and lifecycle observation continues. This is distinct from a transport,
+backend-execution, or collaboration-acknowledgement deadline whose unknown outcome isolates the
+context as offline.
+
+The start Receipt has an extensible `usage.credits` object. `status: "estimated"` means the Workflow
+was accepted and `estimate.amount` is an estimate rather than authoritative charged usage;
+`"not-consumed"` means generation was definitely not started; and `"unknown"` means the start write
+lost its authoritative response and must be reconciled after reconnect. An available estimate also
+records its Definition identity and version. The CLI never converts an estimate into an actual-charge
+claim.
+
+Every output frame has `protocolVersion`, monotonic `streamSeq`, `type`, `payload`, and optional
+`requestId`. stdout contains protocol frames only; diagnostics use stderr. A write completes only
+after collaboration-server acknowledgement. A timeout or lost acknowledgement is indeterminate,
+moves the Canvas context offline, and requires explicit reconnect and inspection before any retry.
+
+## Preview acceptance checklist
+
+Before distributing a preview tarball, verify all of the following from its clean installation, not
+from TypeScript source:
+
+1. `az8 --version` matches the immutable package version and `az8 help` lists Project, persistent
+   Canvas, one-shot, upload, and download entry points.
+2. With no credential, an authenticated command fails without connecting and without printing a
+   token. With the test token, `projects create` returns a new Project owned by the authenticated
+   account.
+3. Persistent stdio reaches `ready`, accepts a summary query, creates a note whose Receipt records
+   the authenticated Actor, and completes an ordered shutdown.
+4. One-shot `createMediaTarget` plus `planGeneration` returns a ready semantic sequence; executing
+   that sequence starts one Workflow Run, and `waitWorkflowRun` or later `getWorkflowRun` observes
+   its authoritative state.
+5. Upload one small local media file, confirm immediate detail resolution to its Core Node, replay
+   the same idempotency key without another transfer, and download the resolved media to a fresh
+   destination whose SHA-256 is reported.
+6. Run repository `pnpm verify`, retain the tarball SHA-512, and record the tested environment. Never
+   perform these acceptance writes against production.
+
+Release and rollback commands are in `RELEASE.md`; package changes are in `CHANGELOG.md`.

package/RELEASE.md

@@ -0,0 +1,59 @@
+# AZ8 CLI preview release
+
+This package is an internal preview. `preview` is the release channel; it must not replace npm's
+`latest` tag until a separate stability decision is made.
+
+## Release gate
+
+From the repository root:
+
+```bash
+pnpm release:az8-cli
+pnpm release:pack:az8-cli
+```
+
+The first command runs CLI tests, type checking, builds a real npm tarball, installs that tarball in
+a clean temporary directory, and verifies the installed `az8` executable. The second preserves the
+verified tarball and clean installation under `tmp/az8-cli-release/` for live acceptance.
+
+Run the live smoke only against the test environment. It creates one Project unless `--project-id`
+reuses an explicit test Project, starts one image generation, and uploads one tiny PNG:
+
+```bash
+node apps/az8-cli/scripts/smoke-test.js \
+  --bin ./tmp/az8-cli-release/install/node_modules/.bin/az8 \
+  --env-file ./.env.local
+```
+
+The smoke report must show authenticated persistent stdio, ordered shutdown, a completed Workflow
+Run whose target resolves its output Core Node, upload replay without another transfer, and matching
+download SHA-256. `--skip-generation` is only for diagnosing unrelated media or transport checks;
+it cannot satisfy full release acceptance.
+
+Before publishing, also run the test-environment acceptance checklist in the packaged README and the
+repository-wide `pnpm verify`. Publishing is an external action and requires explicit operator
+authorization:
+
+```bash
+npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.2.0-preview.1.tgz --tag preview
+npm view @everfir/az8-cli dist-tags versions --json
+```
+
+Do not pass `--tag latest`. Do not publish from an unverified source directory.
+
+## Rollback
+
+Published versions are immutable. Rollback moves the `preview` tag to a previously verified version
+instead of unpublishing or overwriting a package:
+
+```bash
+npm dist-tag add @everfir/az8-cli@<previous-version> preview
+npm view @everfir/az8-cli dist-tags --json
+npm install --global @everfir/az8-cli@preview
+az8 --version
+```
+
+For tarball distribution, retain every verified `.tgz`; reinstall the previous tarball and confirm
+`az8 --version`. A rollback changes only the installed client. It never reverses already
+acknowledged Project or Canvas effects; agents must use semantic compensation or Canvas History for
+product data.