@samva/cli 0.3.1 → 0.4.0

package/AGENTS.md

@@ -5,7 +5,7 @@ Use `samva --help` and `samva <command> --help` as the command contract. For aut
 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
+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.
@@ -15,15 +15,24 @@ machine watch output uses `--jsonl`. `--json` remains one-shot.
 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 +43,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
+<emails/x.tsx>` registers another entry under its `defineEmail` 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,7 +132,7 @@ 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
@@ -160,6 +157,22 @@ git push origin main
 samva templates publish --commit HEAD --json
 ```
 
+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:
+
+```sh
+samva templates add emails/reset.tsx
+git add emails && 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
+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.
+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
@@ -174,13 +187,14 @@ For imported email assets, pass their actual serving base to `check` or `build`,
 `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.
+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`.
 
 `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
@@ -203,11 +217,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 +235,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 +344,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

package/bin/samva.cjs

@@ -53,5 +53,5 @@ try {
 if (nativeExecutable) {
   run(nativeExecutable, process.argv.slice(2));
 } else {
-  run("bun", [join(__dirname, "..", "dist", "bin.mjs"), ...process.argv.slice(2)]);
+  run("bun", ["--no-env-file", join(__dirname, "..", "dist", "bin.mjs"), ...process.argv.slice(2)]);
 }