@samva/cli 0.1.2 → 0.2.0

package/AGENTS.md

@@ -4,13 +4,57 @@ 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 init` creates a project whose `devDependencies` include `@samva/markup`,
-`@samva/vite`, and Vite. Run `npm install` in that project before `samva templates push`; the CLI
-loads the project's installed authoring toolchain so its compiler and editor versions stay pinned
-by the project lockfile. Template authoring commands require Node.js 22 or newer; other CLI commands
-remain self-contained.
+`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
+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.
+
+`--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
+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 domain-authorized operations the hosted MCP tools reach, so both
+external transports complete one journey against one substrate. 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.
+
+`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
+reference is each template's current publication, so a generated file keeps sending the same
+message until it is regenerated; `--reference contract-latest` follows new publications while the
+input contract holds. `--check` writes nothing and exits `1` when the file no longer describes the
+catalog, naming what moved. A schema the generator cannot express as a checking type is refused
+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-local credential helper that exchanges Samva authorization for a one-hour,
+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.
+Run `bun install --frozen-lockfile` 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
+compiler and editor versions stay pinned by the project lockfile.
+Template authoring commands require Node.js 22 or newer; other CLI commands remain self-contained.
 
 `@samva/cli` ships the JavaScript implementation and its runtime dependencies. Its launcher prefers
 the matching platform-specific `@samva/cli-*` executable and falls back to the packaged JavaScript
 CLI through Bun when npm omits optional dependencies. Depend on `@samva/cli`, never a native
 artifact directly.
+
+## Command handler tracing
+
+Every `Command.withHandler` body uses `Effect.fnUntraced`, and that is the convention for the whole
+command surface rather than an omission at each site. A handler is the process: it runs once, prints,
+and exits, so a span would name the run instead of a step inside it, and the CLI installs no tracer
+to receive one. Reusable work that outlives a single call still carries a name, as
+`src/config/store.ts` does with `Effect.fn("CliConfig.writeConfig")` and
+`Effect.fn("CliConfig.writeCredentials")`.

package/README.md

@@ -115,24 +115,85 @@ samva email design push --dry-run
 
 ## Template projects
 
-Scaffold a project with the Samva TSX runtime, visual editor, and pinned authoring dependencies:
+Create a starter-backed project, or clone an existing template project. Samva creates the project
+identity and Artifact repository; Git owns the local checkout and synchronization:
 
 ```sh
-mkdir transactional-email && cd transactional-email
-samva templates init
-npm install
-npm run samva:dev
+samva templates init --name "Welcome email" --dir welcome-email
+# samva templates clone tmpl_abc123 --dir welcome-email
+cd welcome-email
+bun install --frozen-lockfile
+bun run dev
 ```
 
-The generated project lists `@samva/markup` and `@samva/vite` as development dependencies and Vite
-as the editor peer. The compiled CLI deliberately loads `@samva/vite/build` from the current
-project, so preview and push use the compiler version recorded in that project's lockfile.
+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
+`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 push --dir emails --dry-run
-samva templates push --dir emails
+samva templates check --dir emails
+samva templates check --json
+samva templates build --dir emails --out dist/templates.json
+samva templates check --watch
+samva templates check --watch --jsonl
+git add emails 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.
+
+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.
+
+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.
+
+`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`.
+
+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
+Artifact credential. `samva templates credential` is an internal helper command, not a general
+credential store. Local OAuth credentials remain in the OS keyring; `SAMVA_API_KEY` remains the
+automation path.
+
+`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 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
+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.
+
+`templates list`, `get`, `create`, `update`, and `remove` operate on template metadata. They do not
+replace the project repository, workspace, or native Git history.
+
 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
 HTML body. Only one body may come from stdin, so passing both `--text -` and `--html -` is rejected.