@samva/cli 0.4.0 → 0.5.0

package/AGENTS.md

@@ -4,12 +4,22 @@ 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
+`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
@@ -51,7 +61,7 @@ Install from the project's lockfile (`bun install --frozen-lockfile` or `npm ci`
 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. A project holds several emails: `samva templates add
-<emails/x.tsx>` registers another entry under its `defineEmail` id, `samva templates publish --all`
+<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.

package/README.md

@@ -139,19 +139,24 @@ 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
@@ -161,34 +166,41 @@ A project holds as many emails as you need, sharing its components, theme, and l
 another entry, register it, then publish every entry at one commit:
 
 ```sh
-samva templates add emails/reset.tsx
-git add emails && git commit -m "feat: add password reset" && git push origin main
+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 `defineEmail` id as the template's handle; pass `--slug` and `--name` to
+`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 `defineEmail` files that are not registered. Rerunning it after a partial failure is safe.
+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.
 
-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.
-
-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.
+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. 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`.
+`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
@@ -202,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
@@ -357,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.