@samva/cli 0.3.2 → 0.5.0

package/AGENTS.md

@@ -4,26 +4,45 @@ Use `samva --help` and `samva <command> --help` as the command contract. For aut
 `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.
 
-`samva templates export --dir <dir> --out <dir>` renders every local template's fixtures to HTML
-and text with the asset manifest, using no Samva credential; `--asset-base <origin>` is for an
+`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.
 
+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>
+--fixture <name>` (subject, preheader, and plain-text body; `--format html`, `--channel sms|whatsapp`),
+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
+`emails/`; a template is a `.tsx` file that default-exports `defineTemplate`, and the compiler reads
+it without running it.
+
 `--publication-id` and `--input-contract-id` on `email send`, `scheduled-messages create`, and
 `campaigns create`/`update` choose which publication a template send renders: one exact publication,
 or the newest publication that still validates input identically. They are mutually exclusive and
 each requires `--template-id`, because a reference is a statement about one template's history.
 
-`samva templates workspace <open|diff|patch|check|fixture|save|history|publish>` is the
+`samva templates workspace <open|diff|patch|add-asset|check|fixture|save|history|publish>` is the
 hosted project workspace over the CLI, for a caller with no clone: an agent in a sandbox, a CI job,
 a script. It reaches the same operations the hosted MCP tools reach, so an agent can start a journey in one
-and finish it in the other. Every subcommand prints its complete
+and finish it in the other; `add-asset` alone has no MCP twin, because a chat client holds no file
+bytes to send. Every subcommand prints its complete
 result as JSON because these outputs — revisions, digests, diagnostics — are inputs to the next
 call. `open` returns the revision every other subcommand is fenced to; a workspace that moved refuses
 them, and reopening is the recovery. A source that does not build is a successful call carrying a
-null declaration and located findings, not a failed one. The Git commands remain the way to author a
-project you have cloned.
+null declaration and located findings, not a failed one. `add-asset <template-id> <file>` writes one
+image or font as unsaved bytes at `assets/<file name>` unless `--path` names another project path;
+`--replace` is required to change a path that already holds a file. The Git commands remain the way
+to author a project you have cloned.
+
+`samva brands pull [slug]` writes the brand snapshot `.samva/brands/<slug>.json` that `@samva/vite`
+resolves `samva:brand` from offline; bare `pull` snapshots the default brand, and `theme.css` is
+never written. Keep `.samva` gitignored. `samva brands push <file>` validates brand CSS locally,
+exits `1` with located findings when it is outside the brand grammar, and otherwise replaces the
+CSS of the brand `--brand <slug>` names, or of the default brand. `--dry-run` validates offline.
 
 `samva templates types --out <file>` writes one TypeScript module from the authenticated template
 catalog: the input each published template accepts, and the reference a send carries. The default
@@ -34,14 +53,17 @@ catalog, naming what moved. A schema the generator cannot express as a checking
 with the template and the JSON pointer rather than generated as `unknown`.
 
 `samva templates init --name <name>` creates a starter-backed Artifact project and clones its Git
-repository. `samva templates clone <template-id>` clones an existing project. Both configure a
+repository. `samva templates clone <project-or-template-id>` clones an existing project. Both configure a
 repository-local credential helper that exchanges Samva authorization for a short-lived,
 repository-scoped credential; the token is never stored in the remote URL or Git config. Normal
 `git fetch`, `git pull`, `git add`, `git commit`, and `git push` remain the synchronization commands.
 Install from the project's lockfile (`bun install --frozen-lockfile` or `npm ci`) before `samva templates check` or `samva templates build`, then
 publish a clean, pushed commit with `samva templates publish`. Publish checks that the selected
 commit is an ancestor of the fetched `origin/<default-branch>` and creates an immutable receipt; it
-does not push or rewrite history. The CLI loads the project's installed authoring toolchain so its
+does not push or rewrite history. A project holds several emails: `samva templates add
+<templates/x.tsx>` registers another entry under its `defineTemplate` id, `samva templates publish --all`
+publishes every active entry at one commit and exits non-zero if any failed, and `samva templates
+move <old> <new>` follows a `git mv`. The CLI loads the project's installed authoring toolchain so its
 compiler and editor versions stay pinned by the project lockfile.
 Template authoring commands run that toolchain under Node.js and name the Node.js version they need
 when it is missing; other CLI commands are self-contained.

package/README.md

@@ -108,9 +108,6 @@ samva email doctor --json
 samva email tracking defaults get
 samva email tracking defaults set --opens on --clicks off
 
-# Pull and push the organization email design kit as Tailwind `@theme` CSS.
-samva email design pull
-samva email design push --dry-run
 ```
 
 ## DKIM rotation
@@ -135,52 +132,81 @@ identity and Artifact repository; Git owns the local checkout and synchronizatio
 
 ```sh
 samva templates init --name "Welcome email" --dir welcome-email
-# samva templates clone tmpl_abc123 --dir welcome-email
+# samva templates clone tproj_abc123 --dir welcome-email
 cd welcome-email
 bun install --frozen-lockfile
 bun run dev
 ```
 
 The starter repository contains `@samva/markup`, `@samva/vite`, Vite, the project theme, and its
-lockfile. The CLI deliberately loads `@samva/vite/build` from the current project, so local preview,
-check, and build use the compiler version recorded in that lockfile. The clone has a normal HTTPS
+lockfile. The CLI deliberately loads `@samva/vite` from the current project, so local preview,
+check, render, and build use the compiler version recorded in that lockfile. A project without
+`@samva/markup`, `@samva/vite`, and `vite` fails with the install command
+(`npm install --save-dev @samva/markup @samva/vite vite`). The clone has a normal HTTPS
 `origin`; its repository-local credential helper obtains a one-hour, repository-scoped Artifact
 credential from Samva when Git needs one. The credential is not written to the remote URL or Git
 configuration.
 
 ```sh
-samva templates check --dir emails
+samva templates dev
+samva templates check
 samva templates check --json
-samva templates build --dir emails --out dist/templates.json
+samva templates render welcome --fixture default
+samva templates snapshot welcome --fixture default
+samva templates build --out dist/templates.json
 samva templates check --watch
 samva templates check --watch --jsonl
-git add emails theme.css
+git add templates theme.css
 git commit -m "feat: update welcome email"
 git push origin main
 samva templates publish --commit HEAD --json
 ```
 
-Email entries default-export `defineEmail` with an input schema and declared fixtures. `check`
-typechecks the project and renders every fixture; `build` writes those rendered fixtures, the input
-schema, and the compiled executable module graph. Helper modules without a default export are not
-templates, and every email definition must have a unique id. SMS and WhatsApp retain their
-structured-channel compiler.
+A project holds as many emails as you need, sharing its components, theme, and lockfile. Write
+another entry, register it, then publish every entry at one commit:
 
-The JSON file written by `build` uses `schemaVersion: 2`: email previews have `kind: "email"` and
-contain actual fixture outputs; structured previews have `kind: "structured"`. Email source in the
-artifact is authored TSX. The CLI's stdout envelope remains version 1.
+```sh
+samva templates add templates/reset.tsx
+git add templates && git commit -m "feat: add password reset" && git push origin main
+samva templates publish --all
+```
+
+`add` uses the entry's `defineTemplate` id as the template's handle; pass `--slug` and `--name` to
+choose others or to register an entry before the file exists. `publish --all` publishes every
+active template in the project, reports each result, exits non-zero when any entry failed, and
+lists `defineTemplate` files under `templates/` or `emails/` that are not registered. Rerunning it after a partial failure is safe.
+After `git mv`, `samva templates move <old-path> <new-path>` points the template at the new file
+and keeps its id, handle, and publications.
+
+Templates live in `templates/`, and `emails/` is also recognized; every authoring command scans
+whichever exist, and `--dir <dir>` scans only that one. A template is a `.tsx` file that
+default-exports `defineTemplate` with an input schema, declared fixtures, and an `email`, `sms`, or
+`whatsapp` body. The compiler reads the file without running it, so top-level code in a template
+does not execute. `check` type-checks the project, compiles every template, and renders every
+fixture through every channel the template declares; `build` writes those rendered fixtures, each
+template's input schema, and its compiled IR. Modules without a template default export are
+helpers, and every template needs a unique id.
+
+The JSON file written by `build` uses `schemaVersion: 3`. Its `result` is the `@samva/vite/build`
+result: `files[]`, one per template entry, each with `ok`, `diagnostics`, and a `template` carrying
+`template` (the id), `channels`, `source`, `inputSchema`, `ir`, `fixtures[]` (each with its `email`
+subject, preheader, HTML and text, its `sms` text, or its `whatsapp` message), and `compatibility`
+findings. The former `preview.kind` `"email"` and `"structured"` shapes no longer exist. The CLI's
+stdout envelope remains version 1.
 
 For imported email assets, pass their actual serving base to `check` or `build`, for example
 `samva templates build --out dist/templates.json --asset-base https://cdn.example.com/email`.
 These commands require an HTTPS base for delivery; they do not invent a URL or upload assets.
-`templates export --dir emails --out dist/email` remains the way to write a local HTML/text export
-with relative asset URLs.
+`templates export --out dist/email` remains the way to write a local HTML/text export
+with relative asset URLs, plus `<fixture>.sms.txt` and `<fixture>.whatsapp.json` for those channels.
+Like `check` and `build`, it treats the current directory as the project: its `theme.css` themes
+the export and `samva:brand` resolves live or from `.samva/brands`.
 
 `git fetch`, `git pull`, `git add`, `git commit`, and `git push` are ordinary Git operations. The
 CLI's `init` and `clone` commands configure the repository-local helper; `publish` does not push
 for you. It accepts a clean commit that is reachable from the fetched `origin/<default-branch>`
-and publishes that exact commit and entry path. Use `--template-id` and `--entry` when publishing
-from a checkout that was not created by `samva templates init` or `clone`.
+and publishes that exact commit. A clone records its project in `samva.projectId`; pass
+`--project-id` from a checkout that `samva templates init` or `clone` did not create.
 
 The helper is invoked by Git using its credential protocol. It accepts only an HTTPS host and path
 matching the project's repository, then exchanges the current Samva credential for a read or write
@@ -188,14 +214,47 @@ Artifact credential. `samva templates credential` is an internal helper command,
 credential store. Local OAuth credentials remain in the OS keyring; `SAMVA_API_KEY` remains the
 automation path.
 
+`samva templates dev [--dir <dir>] [--port <n>] [--host <name>] [--open]` starts the local visual
+editor from the project's `@samva/vite/dev` under Node.js, with no `vite.config.ts`. It prints the
+editor URL and runs until interrupted; `SIGINT` and `SIGTERM` close the server.
+
 `samva templates check` runs the project's TypeScript configuration, then uses the project's
-`@samva/vite/build` to evaluate default exports, emit SML, compile channel artifacts, and report
-phase/provenance diagnostics plus email-client compatibility findings. It writes no files and exits
-non-zero on TypeScript, discovery, module, theme, emit, compile, or breaking compatibility errors.
-`--watch` reuses one Vite evaluator across template, dependency, discovery, and theme changes.
-Human mode prints each observation; machine watch mode requires `--jsonl`. `--json` remains a
-bounded one-shot result. `SIGINT` and `SIGTERM` close the watcher and keep the CLI's documented
-interrupt exit codes.
+`@samva/vite/build` to compile every template, render every fixture, and report located findings
+plus email-client compatibility findings. It writes no files and exits non-zero on TypeScript,
+compile, fixture, or breaking compatibility errors. `--watch` reuses one compiler session across
+template, dependency, and theme changes. Human mode prints each observation; machine watch mode
+requires `--jsonl`. `--json` remains a bounded one-shot result. `SIGINT` and `SIGTERM` close the
+watcher and keep the CLI's documented interrupt exit codes.
+
+Every finding in `check --json` (`problems[]`), `build --json`, `render --json`, and `export --json`
+has the same fields: `code`, `severity`, `message`, `file`, `line` and `column` when located,
+`range` (the located extent), `fix` (what to write instead) when the compiler has one, and `edit`
+(a machine-applicable change) when it offers one; `check` and `build` add `phase`, and a finding
+tied to one fixture names it in `fixture`. Human output prints
+`file:line:column severity code: message` and the fix beneath it. `check --json` also carries
+`warnings[]` for compile warnings and `compatibility` for client findings.
+
+`samva templates render <template> --fixture <name>` renders one fixture of a local template
+through the project's `@samva/vite/render`. `<template>` is a template id or its `.tsx` path.
+`--channel email|sms|whatsapp` picks the body (default `email`), `--locale` and `--time-zone`
+set formatter locale and IANA zone, `--asset-base` and `--offline` behave as for `check`, and
+`--dir` narrows discovery. The default output is the subject, preheader, and plain-text body;
+`--format html` prints the HTML and `--format json` (or `--json`) prints
+`{ action: "templates.render", ok, template, fixture, subject, preheader?, html, text, diagnostics }`
+(an SMS render carries `channel` and `text`; a WhatsApp render carries `channel` and `message`).
+`--out <file>` writes the selected format to a file. A template or fixture that does not exist, or
+a template that does not compile, exits `1` with located findings; an unknown name lists the valid
+ones.
+
+`samva templates snapshot <template> --fixture <name>` renders the email and screenshots it in a
+headless browser at `desktop` (1280px) and `mobile` (390px) widths, in `light` and `dark` color
+schemes, as full-page PNGs at `<out>/<template>-<fixture>-<viewport>-<scheme>.png` (default
+`--out .samva/snapshots`). `--viewport desktop,mobile` and `--scheme light,dark` narrow the set.
+`--json` prints `{ action: "templates.snapshot", ok, template, fixture, browser, out, files: [{ viewport,
+scheme, width, path }] }`. The browser is the `playwright` (or `playwright-core`) your project
+installs; without it, a system Google Chrome or Chromium, found in the usual locations or at
+`SAMVA_CHROME`. With neither the command fails and names both remedies. Screenshots emulate the
+color scheme; they do not reproduce a particular mail client's rendering.
 
 `samva templates build` runs the same compiler gate and writes the complete compiled result as a
 versioned JSON artifact for package and deployment pipelines. Its terminal/JSON result stays
@@ -203,11 +262,12 @@ bounded and reports only the destination, compiler version, and file count.
 
 `samva templates publish` resolves the requested revision to an exact commit, verifies the working
 tree is clean and the commit is an ancestor of the fetched `origin` default branch, then creates an
-immutable publication receipt for the project's configured TSX entry. It does not rewrite Git
-history or alter the working tree.
+immutable publication receipt for each selected entry: the named entry, every active entry with
+`--all`, or the project's only entry. It does not rewrite Git history or alter the working tree.
 
 `templates list`, `get`, `create`, `update`, and `remove` operate on template metadata. They do not
-replace the project repository, workspace, or native Git history.
+replace the project repository, workspace, or native Git history. `remove` deactivates a template;
+its file and publications remain.
 
 Inline email requires `--subject` and exactly one body source: `--html` or `--text`. Pass `-` as
 the value to read that body from stdin: `--text -` reads a plain-text body and `--html -` reads an
@@ -220,6 +280,33 @@ to a two-minute timeout. `--timeout` is valid only with `--wait`, and `--wait` c
 `--dry-run`, since a dry run makes no API call and has nothing to wait on. A timeout or terminal
 delivery failure returns non-zero after printing the last message state.
 
+## Brands
+
+A template reaches its organization's brand with `@import "samva:brand";` (the default brand) or
+`"samva:brand/<slug>"` in `theme.css`. The brand lives in Samva, not in the project, and these
+commands work with it:
+
+```sh
+samva brands list
+samva brands get acme --json
+samva brands pull              # the default brand
+samva brands pull acme
+samva brands push brand.css --brand acme --dry-run
+samva brands push brand.css    # updates the default brand
+```
+
+`samva brands pull [slug]` writes `.samva/brands/<slug>.json` in the project (`--project <dir>`,
+default the current directory). `@samva/vite` resolves `samva:brand` from that snapshot when it
+cannot reach the live brand, so builds and previews work offline. Pull never touches `theme.css`;
+keep `.samva` in `.gitignore`, because the API owns the brand.
+
+`samva brands push <file>` validates the file against the brand CSS grammar before uploading:
+`@theme` variables, one dark-mode `@theme` of colors, and `@font-face` rules with https WOFF2
+sources. CSS outside it exits `1` with every finding located at `file:line:column`, and nothing is
+uploaded. `--brand <slug>` names the brand to replace; without it, push updates the organization's
+default brand. `--dry-run` validates without credentials or an API call. Published templates keep
+the brand they were built against until they are republished.
+
 ## Scheduling and campaigns
 
 ```sh
@@ -302,7 +389,7 @@ samva email send --help
 ```
 
 Released top-level commands are `login`, `logout`, `org`, `email`, `messages`, `campaigns`,
-`scheduled-messages`, `templates`, `webhooks`, `profile`, and `help`. Use `samva <command> --help`
+`scheduled-messages`, `templates`, `brands`, `webhooks`, `profile`, and `help`. Use `samva <command> --help`
 for flags and runnable examples.
 
 Test a configured webhook against its real endpoint with an optional JSON payload. `--data` accepts
@@ -315,14 +402,16 @@ samva webhooks test wep_abc123 --data '{"event":"webhook.test"}' --json
 samva webhooks test wep_abc123 --data @payload.json --json
 ```
 
-`samva email doctor` reports resolved profile, API URL, auth source, organization access,
-sending domains, senders, and domain-verification readback. It is read-only and does not inspect
-receiving configuration, verify DNS, send an email, replay fixtures, or check provider readiness.
+`samva email doctor` reports resolved profile, API URL, auth source, organization access, the send
+review decision, sendable domain and verified sender counts, and domain-verification readback.
+`readyToSend` is true when a production send would be admitted and at least one domain or sender can
+carry it. It is read-only and does not inspect receiving configuration, check DNS itself, send an
+email, or replay fixtures.
 Use `samva email receiving status <domain-id>` to read a domain's receiving prerequisite status.
 `samva email receiving enable <domain-id> ...` acts by default; its `--dry-run` is offline and does
 not require credentials or call the API. Each check is `passed`, `failed`, or
 `unavailable`. A `failed` check carries the underlying error detail; `unavailable`, such as no
-sending domain configured yet, is informational. The command always prints the full report, then
+sending domain yet or a review in progress, is informational; a rejected review fails. The command always prints the full report, then
 exits `1` if any check failed and `0` otherwise. The `--json` result's `data` adds an aggregate
 `ok` boolean, and human output marks checks with `✓`, `!`, and `✗` respectively.