@everfir/az8-cli 0.1.1 → 0.2.0-preview.2

package/package.json

@@ -1,30 +1,46 @@
 {
   "name": "@everfir/az8-cli",
-  "version": "0.1.1",
-  "description": "Read-only Project Canvas inspection CLI for AZ8 Studio.",
+  "version": "0.2.0-preview.2",
+  "description": "Semantic Project Canvas client for AZ8 Studio agents.",
+  "license": "UNLICENSED",
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "CHANGELOG.md",
+    "RELEASE.md"
   ],
   "bin": {
     "az8": "dist/main.js"
   },
   "main": "./dist/main.js",
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "tag": "preview"
   },
   "scripts": {
-    "build": "rm -rf dist && esbuild src/main.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/main.js",
+    "build": "rm -rf dist && esbuild src/main.ts --bundle --platform=node --format=esm --target=node20 --banner:js='import { createRequire } from \"node:module\"; const require = createRequire(import.meta.url);' --outfile=dist/main.js",
     "dev": "tsx src/main.ts",
     "start": "node dist/main.js",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "biome check .",
-    "test": "tsx --test src/**/*.test.ts"
+    "prepack": "pnpm build",
+    "prepublishOnly": "pnpm release:check",
+    "release:check": "pnpm test && pnpm typecheck && node scripts/verify-package.js",
+    "release:pack": "node scripts/verify-package.js --output-dir ../../tmp/az8-cli-release --keep-install",
+    "release:smoke": "node scripts/smoke-test.js",
+    "test": "tsx --tsconfig tsconfig.test.json --test src/**/*.test.ts"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
+    "@workspace/account-profile": "workspace:*",
+    "@workspace/foundation-data": "workspace:*",
+    "@workspace/project-canvas-document": "workspace:*",
     "@workspace/project-canvas-runtime": "workspace:*",
+    "@workspace/project-content": "workspace:*",
+    "@workspace/project-management": "workspace:*",
     "@workspace/typescript-config": "workspace:*",
+    "@workspace/workflow-runtime": "workspace:*",
     "esbuild": "^0.27.7",
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
@@ -32,5 +48,8 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "dependencies": {
+    "file-type": "^21.3.4"
   }
 }

package/skills/az8-cli/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: az8-cli
+description: Use AZ8 CLI to safely select or create Projects, inspect and author Project Canvases, run generation workflows, transfer media, and participate as a persistent collaborative agent. Use whenever a task asks an agent to read, create, edit, organize, generate, upload, or download content in AZ8 Studio.
+---
+
+# Use AZ8 CLI
+
+Treat `az8` as a semantic AZ8 Studio client, not as a document editor or generic backend client.
+Follow this guide before the first Project Canvas action in a new environment. Query runtime
+capabilities instead of guessing operation names or input shapes.
+
+## Contract
+
+- Use only public `az8 projects` and `az8 canvas` commands. Never mutate backend records, Yjs,
+  Collaborative Document fields, Core Node payloads, or Project Content bindings directly.
+- Explicitly select `test` or `production`. Never infer authorization to write production data.
+- Read the relevant Canvas facts before planning a write. Submit one semantic Operation at a time.
+- Treat every accepted write as a blocker: wait for its terminal Receipt before issuing any later
+  query or Operation.
+- A sequence is ordered but not transactional. Stop immediately after the first failure or
+  indeterminate result; do not execute later steps.
+- Never automatically retry a write. Retry only bounded reads when the returned error says doing so
+  is safe. An idempotency key does not authorize blind replay.
+- Keep tokens in the process environment or an ignored env file. Never put a token in argv, an
+  stdio frame, a prompt, a log, or output.
+
+## Concepts
+
+- **Project** is the collaboration and permission boundary. Create, list, get, and rename Projects
+  through `az8 projects`.
+- **Project Canvas** is the synchronized creative surface inside one Project. A persistent client
+  has its own connection, lifecycle, projection, History, Receipt Log, and Awareness identity.
+- **View Node** is a Canvas placement: note, group, or resource target with position, size, parent,
+  stacking, Draft, and presentation state.
+- **Core Node** is immutable or server-owned creative content such as an image, video, or audio.
+  Resource View Nodes resolve Core Nodes through Project Content. Do not manufacture Core Nodes or
+  bindings.
+- **Project Content** is the authority that associates a View Node target with its effective Core
+  Node output. Assets are a separate organization of Core Nodes and are not implemented here.
+- **Workflow Definition** describes a generation capability and its current input contract.
+  **Workflow Run** is one server-side generation execution.
+- **Operation** is one validated business interaction. **Command** is its internal mutation
+  boundary and is never caller-accessible.
+- **Receipt** is the append-only record of one attempted Operation. It reports identity, ordering,
+  outcome, revisions, and optional usage. It is not Canvas History.
+- **History** contains reversible local interactions. Only Operations advertised as `undoable`
+  participate. A generation start is a History barrier and is not undone by `undo`.
+- **Awareness** is ephemeral presence, client name, and Attention Cursor information. It never
+  grants authority, changes persisted authorship, or proves a business result.
+- **Actor** is the authenticated account from `AZ8_TOKEN`. A client or awareness name cannot
+  impersonate another author.
+
+## Bootstrap
+
+1. Verify the installed client and explicitly choose an environment:
+
+   ```bash
+   az8 --version
+   export AZ8_ENVIRONMENT=test
+   export AZ8_TOKEN=...
+   ```
+
+   Prefer an ignored `.env.local` when the shell environment is not appropriate. Never print the
+   token to confirm it.
+
+2. Select an existing Project or create a bounded workspace:
+
+   ```bash
+   az8 projects list --scope owned
+   az8 projects get <project-id>
+   az8 projects create --name "Agent workspace"
+   ```
+
+   Retain the returned Project ID. Confirm the authenticated role before assuming write access.
+
+3. Discover the effective surface for that Project:
+
+   ```bash
+   az8 canvas query <project-id> capabilities.summary
+   az8 canvas query <project-id> capabilities.detail
+   az8 canvas query <project-id> canvas.summary
+   ```
+
+   `capabilities.summary` is the short menu. `capabilities.detail` is authoritative for exact JSON
+   Schema, `effect`, `history`, `completion`, and `retry`. Availability is filtered by the current
+   account, Project role, upstream services, and CLI version. Do not rely on remembered schemas.
+
+4. Use `canvas.detail` only when exact node geometry, Draft, status, or bindings are needed:
+
+   ```bash
+   az8 canvas query <project-id> canvas.detail --view-node-id <view-node-id>
+   ```
+
+5. Choose one-shot for independent tasks and persistent stdio for a collaborative session. Finish
+   by inspecting the affected View Nodes or Workflow Run rather than trusting visual assumptions.
+
+## Interaction modes
+
+Use one-shot commands for a self-contained query, write, upload, or download:
+
+```bash
+printf '%s\n' '{"text":"Idea","position":{"x":160,"y":160}}' |
+  az8 canvas operation <project-id> createNote --input-stdin --request-id create-note-1
+```
+
+- Supply Operation input through exactly one of `--input-stdin`, `--input-file`, or `--input-json`.
+- Give every write attempt a meaningful unique `--request-id` and retain its returned Receipt.
+- Each invocation opens, hydrates, executes, and closes a real Canvas client.
+- One-shot processes do not preserve local History, Receipt Log, Awareness, or request replay.
+  Therefore `undo`, `redo`, `receipts.summary`, and `receipt.detail` require persistent stdio.
+
+Use persistent stdio when multiple ordered interactions, live synchronization, History, Receipt
+lookup, observations, or human collaboration matter:
+
+```bash
+az8 canvas open <project-id> --write --format ndjson
+```
+
+1. Continuously drain stdout; it is an ordered NDJSON protocol stream and may apply backpressure.
+2. Read `hello`, select protocol `1.0`, then send `initialize` for the same Project ID.
+3. Wait for `ready` before any query or Operation.
+4. Keep exactly one reader for stdout. Parse each frame by `type`, `requestId`, and `streamSeq`.
+5. Use `compact` observations by default. Query `awareness.detail` when cursor context is needed;
+   cursor coordinates are intentionally not streamed.
+6. On an observation gap, query summary/detail and rebuild the local view.
+7. Send `shutdown` and wait for ordered completion. EOF or a signal is emergency cleanup, not a
+   cancellation or rollback mechanism.
+
+Protocol truth is written to stdout. stderr contains diagnostics only. Unknown optional fields are
+additive; ignore them. Do not treat a process exit code as the result of the last persistent request.
+
+## Canvas SOP
+
+1. Query `canvas.summary`; query selected details only as needed.
+2. Query `capabilities.detail` and validate the planned Operation input against its schema.
+3. Pick explicit absolute Canvas coordinates. Public move positions remain absolute even for group
+   children.
+4. Submit one Operation with a new request ID and wait for its terminal Receipt.
+5. Confirm the Receipt outcome and affected IDs, then query the changed View Node when subsequent
+   work depends on its exact state.
+6. Only then plan the next interaction.
+
+Common capabilities include notes, move/resize/rename, duplicate/remove, groups and stacking, Core
+Node placement, and media targets. The runtime catalog is authoritative. Group nodes cannot nest;
+stacking applies only among siblings. Unsupported World, Decoration, Asset, alignment, and automatic
+layout behavior must not be simulated through lower-level writes.
+
+Use `undo` or `redo` only in the same persistent session and only after checking History semantics
+in capability detail. Silent edits are valid Web-equivalent interactions but do not create History
+entries. Never use compensating low-level mutations to imitate undo.
+
+## Generation
+
+Generation is an explicit sequence, never one transaction:
+
+1. Create a target with `createMediaTarget` and retain its View Node ID.
+2. Call the read-only `planGeneration` Operation with the target, prompt, and any references. Use
+   `detail: "detail"` when configuration fields or dynamic enum options are needed.
+3. If the plan reports blocking issues, resolve them and plan again. Do not execute a non-ready
+   plan.
+4. Execute `plan.operations` exactly in order, one Operation at a time. Each step revalidates
+   current facts. Stop after the first non-success.
+5. `startGeneration` succeeds when the Workflow Run is accepted and immediate Canvas effects are
+   acknowledged. This completes the start interaction; it does not mean generation finished.
+6. Retain the Workflow Run ID. Use `waitWorkflowRun` when waiting is useful, or `getWorkflowRun`
+   later. An observation-window timeout while the authoritative Run remains pending/running is an
+   ordinary read outcome and does not cancel the Run or take a healthy context offline.
+7. On terminal success, query the target detail and resolve its current output Core Node through
+   Project Content before downloading or placing it elsewhere.
+
+Workflow Definitions change over time. Query `workflowDefinitions.summary`, then
+`workflowDefinition.detail` only when planning detail is insufficient. Never guess a Definition,
+configuration option, modality, cost, or media compatibility from its display name.
+
+The start Receipt may report `usage.credits.status` as `estimated`, `not-consumed`, or `unknown`.
+Estimated cost is informational, not final charged usage. There is no second confirmation. Never
+claim actual credit consumption from an estimate.
+
+## Media
+
+For a local image, video, or audio file, use the semantic upload wrapper:
+
+```bash
+az8 canvas upload <project-id> \
+  --file ./reference.png \
+  --idempotency-key reference-image-1 \
+  --name "Reference image" \
+  --position-x 640 --position-y 160
+```
+
+- Use a stable logical idempotency key for that exact file intent. Conflicting key reuse is an
+  error. Replay only after inspecting and reconciling the prior attempt.
+- Let the CLI inspect bytes, MIME, size, and checksum and let the server create the Core Node and
+  binding. Do not supply a claimed media type, upload URL, Core Node ID, or Project Content record.
+- A known failure may leave one inspectable `failed` View Node. An unknown response leaves it
+  `pending` and isolates the context; do not create a replacement until reconciliation.
+
+Use `importExternalMedia` only for a deliberate public HTTP(S) media URL. It references that URL; it
+does not upload bytes or add content to an Asset.
+
+Download only an effective View Node output or an explicit Core Node within the Project context:
+
+```bash
+az8 canvas download <project-id> --view-node-id <view-node-id> --output ./result.png
+```
+
+The destination must be explicit. Existing files are preserved unless `--overwrite` is explicitly
+chosen. Verify the returned absolute path, byte count, detected MIME, Core Node ID, and SHA-256.
+Never extract or reuse hidden media URLs as a general downloader.
+
+## Recovery
+
+Classify the outcome before deciding what to do:
+
+- **Succeeded:** accept only a terminal success result/Receipt, retain returned identities, and
+  inspect facts required by the next step.
+- **Definitive failure:** the Operation did not take its promised effect. Fix input, permissions, or
+  business state before making a new explicitly identified attempt.
+- **Indeterminate write:** acknowledgement, transport, backend response, or deadline was lost after
+  the write might have started. Assume neither success nor failure. Stop the sequence, take the
+  context offline, reconnect manually, inspect Canvas/Project Content/Workflow facts and Receipts,
+  then decide whether a new attempt is safe. Never automatically retry.
+- **Read failure:** retry only if capability/error metadata marks the read retryable, and keep the
+  retry bounded. A reconnect failure cancels queued unfinished work; it does not replay it.
+- **Workflow wait timeout:** if the Run is authoritatively still pending or running, treat this as
+  the end of one observation window. Continue other work or query later; do not cancel or restart.
+- **Caller cancellation:** cancellation is safe only before an Operation begins. Once a write has
+  attempted to start, interruption waits for its deadline and cannot roll it back. After uncertainty,
+  reconcile facts before acting.
+
+For one-shot Canvas commands, exit `0` means success, `1` means a definitive caller/business
+failure, and `2` means an indeterminate lifecycle or transport outcome. Media download may return
+`130` for caller cancellation. Always read the structured result; do not generalize these codes to
+Project commands or the lifetime of a persistent stdio process.
+
+## Safety
+
+Never:
+
+- write raw backend endpoints, Yjs maps, Collaborative Document paths, generic patches, Core Node
+  payloads, or Project Content bindings;
+- invent an Operation or input field absent from `capabilities.detail`;
+- execute writes concurrently, continue a planned sequence after a failure, or wrap multiple
+  Operations in assumed transaction semantics;
+- automatically retry a write, reuse a request ID for an unrelated attempt, or treat an idempotency
+  key as proof that blind replay is safe;
+- conclude that a timed-out write failed, conclude that an accepted Workflow Run completed, or
+  conclude that an Awareness event persisted data;
+- expose a token, presigned URL, permanent media URL, env-file contents, or private output in logs
+  or protocol payloads;
+- use awareness client names to impersonate persisted authors or treat Attention Cursor position as
+  authority;
+- use one-shot as if it retained History, Receipts, replay state, observations, or presence;
+- attempt Asset membership, arbitrary Core Node creation, 3D World editing, unsupported
+  Decoration, alignment, or automatic layout through lower-level access;
+- write production unless the user explicitly selected and authorized production for the concrete
+  action.
+
+## Completion
+
+Before reporting a task complete, verify all applicable facts:
+
+- The intended environment, Project ID, authenticated role, and installed CLI version are known.
+- Runtime capability discovery—not memory—authorized every Operation and input schema used.
+- Every write has its own request ID, terminal Receipt, and sequential position; no write was
+  automatically retried.
+- The first failure stopped the remaining sequence, and every indeterminate effect was reconciled
+  after explicit reconnect/inspection.
+- Created or edited View Nodes were checked at the detail level needed by downstream work.
+- Generation start and generation completion were reported as separate interactions; the target's
+  effective Core Node was resolved after completion.
+- Media transfers were verified by identities and checksums without exposing URLs or credentials.
+- Persistent stdio was shut down in order, or any abnormal termination and uncertain active write
+  was disclosed.
+- Deferred scopes were not approximated by bypassing the public semantic surface.
+
+When any item cannot be proven, report the uncertainty and the next safe read or reconciliation
+step instead of claiming completion.

package/skills/az8-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "AZ8 CLI"
+  short_description: "Safely create and collaborate in AZ8 Project Canvases"
+  default_prompt: "Use $az8-cli to create or edit an AZ8 Project Canvas safely."