@samva/cli 0.7.0 → 0.8.0

package/AGENTS.md

@@ -2,13 +2,19 @@
 
 Use `samva --help` and `samva <command> --help` as the command contract. For automation, prefer
 `SAMVA_API_KEY`, `--json` for one bounded result, and `--jsonl` with `--all` for streamed lists.
-Machine-readable results go to stdout; warnings and typed errors go to stderr.
+Machine-readable results go to stdout; warnings and typed errors go to stderr. Error envelopes carry
+`schemaVersion`, `type`, `command`, `reason`, `message`, and optional `next`. For API failures,
+`reason` is the API `_tag`, `status` is the HTTP status, and `details` preserves the public error
+fields. Follow `next` and fix `details.fields` before retrying. API 401 and 403 exit with code `4`;
+other operational failures exit with code `1`. Human mode prints the same message and recovery step.
 
 `samva templates export --out <dir>` renders every local template's fixtures to HTML
 and text with the asset manifest, needing a Samva credential only to resolve a live `samva:brand`; `--asset-base <origin>` is for an
 export that will be delivered, which cannot carry a relative reference.
 `samva templates check --watch` is the continuous authoring gate. Human mode prints observations;
 machine watch output uses `--jsonl`. `--json` remains one-shot.
+`samva mailboxes events` is a stream: human mode prints one raw record per line, `--jsonl` one result
+envelope per event, `--quiet` nothing, and `--json` is refused (exit 2) with a pointer to `--jsonl`.
 
 The developer loop for a template project is `samva templates dev` (the local visual editor, no
 `vite.config.ts`), `check` (type-check, compile, and render every fixture), `render <template>
@@ -16,7 +22,8 @@ The developer loop for a template project is `samva templates dev` (the local vi
 and `snapshot <template> --fixture <name>` (desktop and mobile PNGs, light and dark, in
 `.samva/snapshots`, needing `playwright` in the project or a system Chrome). With `--json`, every
 finding carries `code`, `severity`, `message`, `file`, `line`/`column`, `range`, and, where the
-compiler has them, `fix` and a machine-applicable `edit`. Templates live in `templates/` and
+compiler has them, `fix`, a machine-applicable `edit`, and `upgrade`, the instructions for migrating
+a template written in a format the compiler rejects. Templates live in `templates/` and
 `emails/`; a template is a `.tsx` file that default-exports `defineTemplate`, and the compiler reads
 it without running it.
 
@@ -78,3 +85,26 @@ artifact directly.
 Keep Samva brand resolution in the CLI and pass `samvaBrandPlugin` to the project's authoring
 toolchain, so standalone `@samva/vite` stays independent of Samva authentication and storage.
 Standalone callers supply their own resolver. The README owns resolution order and configuration.
+
+`samva extensions` is the mailbox extension developer loop: `init` scaffolds an authoring project,
+`dev` handles mailbox events locally, `publish` records an immutable version, and `install` grants
+that version scoped mailbox permissions. Hosted extensions run on Samva; webhook extensions use
+the installation credentials returned once at install. Publishing and installation management
+require a person signed in with `samva login`. Local development with that login attributes tool
+calls to you, rather than to an installation. Read what exists with `list`, `versions <name>`,
+`version <name> <version>`, `installations`, `installation <id>`, `runs <id>` (outcomes only), and
+`run <id> <run-id>` (adds the handler's log lines); the list commands page with `--limit`,
+`--cursor`, and `--all --jsonl`.
+
+`samva mailboxes` reads and sends as a mailbox: `list` pages with `--limit`, `--cursor`, `--after`,
+and `--before`, `threads` searches, `read` prints a message (human output marks the body as
+untrusted email), and `send` and `reply` take `--idempotency-key` so a retry cannot send twice.
+Quarantine `list` pages the same way, bounded by `--after` and `--before` on when a message was
+held; `release` and `discard` take the held message's `id` and require a person signed in with
+`samva login`. `samva mailboxes events` reads the SDK event stream with reconnects off and prints
+one record per event, `{cursor, id, event}` (`--jsonl` wraps each in a result envelope, `--quiet`
+prints none, `--json` is refused). A drop or refusal ends the command with the server's `_tag` as
+the error `reason`, its `status` and `details`, and a `Try:` line; the last handled cursor, which
+`--cursor` resumes from, goes to stderr in human mode and into `details.lastCursor` otherwise.
+`samva extensions dev` follows the same output modes. 401 and 403 exit 4. An expired
+cursor exits 1 and the next step is to start without `--cursor`. Ctrl+C exits cleanly.

package/README.md

@@ -360,12 +360,14 @@ samva --quiet profile use acme
 `--json` writes one bounded, versioned result envelope to stdout:
 `{schemaVersion:1,type:"result",command,data}`. For resource lists, `--jsonl` writes one flat,
 independently parseable outer result envelope per resource. Errors use the corresponding
-`{schemaVersion:1,type:"error",command,reason,message,next?}` envelope on stderr and exit
-non-zero. `--json`, `--jsonl`, and `--quiet` are mutually exclusive; assignment forms such as
+`{schemaVersion:1,type:"error",command,reason,message,status?,details?,next?}` envelope on stderr and exit
+non-zero. API errors use their `_tag` as `reason`, their HTTP status as `status`, and their
+public fields as `details`. Fix `details.fields` and follow `next` before retrying. API 401 and 403
+exit with code `4`. Human mode prints the same message and a `Try:` line. `--json`, `--jsonl`, and `--quiet` are mutually exclusive; assignment forms such as
 `--json=true` are usage errors. `--quiet` suppresses successful output only. In machine modes,
 stdout contains only result data; warnings and errors go to stderr.
 
-Lists are paginated by default. Use `--page` and `--limit` for a bounded page. `--all` requires
+Lists are paginated by default. Use `--limit` for a bounded page and `--cursor` with the printed `nextCursor` for the next one. `--all` requires
 `--jsonl`, so an automated traversal stays streamable rather than producing an unbounded JSON
 document. `--all` changes traversal only: bounded and unbounded JSONL records have the same outer
 envelope, with the resource itself in `data`. Empty lists emit no records.