@samva/cli 0.1.0

package/AGENTS.md

@@ -0,0 +1,14 @@
+# Samva CLI consumer guide
+
+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.
+
+`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.
+
+The platform-specific `@samva/cli-*` packages are installer artifacts. Depend on `@samva/cli`, not
+on a native package directly.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arya Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,243 @@
+# @samva/cli
+
+The `samva` CLI sends and operates email from a terminal. Ordinary commands are
+self-contained and require neither Bun nor Node. Template authoring commands run
+the project's `@samva/vite` toolchain under Node.js 22 or newer.
+
+## Install
+
+```sh
+npm install -g @samva/cli
+samva --help
+```
+
+The npm package selects the matching macOS or Linux executable. Compiled
+binaries are also available from [GitHub releases](https://github.com/AryaLabsHQ/samva/releases).
+
+## Shell completions
+
+Generate a completion script from the installed CLI. Regenerate it after upgrading the CLI.
+
+```sh
+# Bash
+samva --completions bash >> ~/.bashrc
+
+# Zsh
+mkdir -p ~/.zsh/completions
+samva --completions zsh > ~/.zsh/completions/_samva
+# Add ~/.zsh/completions to fpath, then run `autoload -Uz compinit && compinit` in .zshrc.
+
+# Fish
+mkdir -p ~/.config/fish/completions
+samva --completions fish > ~/.config/fish/completions/samva.fish
+
+# sh is an alias for the Bash-compatible script
+samva --completions sh
+```
+
+## Authentication and execution context
+
+For agents and CI, set an organization-scoped API key:
+
+```sh
+export SAMVA_API_KEY="samva_sk_live_..."
+```
+
+For interactive use, sign in with OAuth and choose an organization:
+
+```sh
+samva login
+samva org list
+samva org use <slug>
+```
+
+`SAMVA_API_KEY` takes precedence over a stored OAuth credential. An API key is already scoped to
+one organization, so `--org` and `SAMVA_ORG` are rejected when it is set. With OAuth, organization
+selection resolves as `--org`, then `SAMVA_ORG`, then the selected profile's organization.
+
+`samva login` is interactive. In a non-TTY, use `SAMVA_API_KEY` for automation or explicitly choose
+the device flow with `samva login --no-browser`; `--no-input`, `--json`, and `--jsonl` reject login.
+If a stored OAuth record is malformed, run `samva logout` and then `samva login`; API-key calls do
+not read or decode stored OAuth credentials.
+
+Profiles hold non-secret target and organization settings. Credentials stay in the OS keyring.
+
+```sh
+samva profile create local --target local
+samva profile use local
+samva --profile local email doctor
+```
+
+The profile resolves as `--profile`, then `SAMVA_PROFILE`, then the active profile, then `default`.
+The API URL resolves as `--api-url`, then `SAMVA_API_URL`, then the profile target. `local` targets
+`http://127.0.0.1:8787`; `production` targets `https://api.samva.dev`.
+
+## Common operations
+
+```sh
+# Send an inline email. --to is repeatable.
+samva email send --to ada@example.com --subject "Hello" --text "Hi!"
+
+# Pipe the plain-text body from stdin.
+printf 'Hi from a pipeline' | samva email send \
+  --to ada@example.com --subject "Hello" --text -
+
+# Pipe a rendered HTML body from stdin.
+render-email | samva email send \
+  --to ada@example.com --subject "Hello" --html -
+
+# Render a published template.
+samva email send --to ada@example.com --template-slug welcome-email \
+  --template-data '{"name":"Ada"}'
+
+# Wait for delivery or a terminal delivery outcome.
+samva email send --to ada@example.com --subject "Hello" --text "Hi!" \
+  --wait --timeout 2m
+
+# Inspect a message and its events.
+samva messages get <message-id>
+samva messages events <message-id> --json
+
+# Inspect configuration and remote email state without mutating it.
+samva email doctor --json
+```
+
+## Template projects
+
+Scaffold a project with the Samva TSX runtime, visual editor, and pinned authoring dependencies:
+
+```sh
+mkdir transactional-email && cd transactional-email
+samva templates init
+npm install
+npm run samva: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.
+
+```sh
+samva templates push --dir emails --dry-run
+samva templates push --dir emails
+```
+
+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.
+Template sends use exactly one of `--template-id` or `--template-slug`, with optional
+`--template-data`, and omit `--subject`.
+
+`--wait` polls until the message is delivered or read, or reaches a terminal failure. It defaults
+to a two-minute timeout. `--timeout` is valid only with `--wait`, and `--wait` cannot combine with
+`--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.
+
+## Scheduling and campaigns
+
+```sh
+samva scheduled-messages create --to ada@example.com --template-slug welcome-email \
+  --template-data '{"name":"Ada"}' --at 2026-08-01T09:00:00Z \
+  --timezone America/New_York --idempotency-key welcome-ada
+samva scheduled-messages list --status pending
+samva scheduled-messages get <scheduled-message-id>
+samva scheduled-messages cancel <scheduled-message-id> --yes
+
+samva campaigns create --name "August launch" --template-slug august-launch \
+  --include-tags newsletter
+samva campaigns runs create <campaign-id> --at 2026-08-01T09:00:00Z \
+  --idempotency-key august-launch
+samva campaigns runs recipients <campaign-id> <run-id> --status failed
+```
+
+`--at` is an absolute ISO 8601 instant. `--timezone` is display and audit metadata for a
+scheduled message. Campaign definitions freeze after their first run. Cancelling a scheduled
+message or campaign run requires confirmation, and dispatch already in progress may still finish.
+
+## Automation contract
+
+Use `--dry-run` on supported mutations to validate input and preview the intended request. `email
+send --dry-run` does not use credentials or call the API. Other previews may read state when needed
+to show the resulting change. Destructive operations prompt in a TTY; automation must use `--yes`,
+or it fails without changing state. `--no-input` prevents prompts and browser launches.
+
+```sh
+# Review a request without authentication or an API call.
+samva email send --to ada@example.com --subject "Hello" --text "Hi!" --dry-run --json
+
+# Traverse every page as one JSON record per line.
+samva messages list --all --jsonl
+
+# Suppress successful human output.
+samva --quiet profile use local
+```
+
+`--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
+`--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
+`--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.
+
+Exit codes are stable for automation:
+
+|  Code | Meaning                                                                  |
+| ----: | ------------------------------------------------------------------------ |
+|   `0` | Success                                                                  |
+|   `1` | API, operational, or terminal delivery failure                           |
+|   `2` | Command syntax, validation, configuration, or confirmation failure       |
+|   `4` | Authentication or organization-context failure, incl. an expired session |
+| `124` | Wait or credential timeout                                               |
+| `130` | Interrupted with `SIGINT`                                                |
+| `143` | Terminated with `SIGTERM`                                                |
+
+When `--json` or `--jsonl` is set, failures are emitted as JSON diagnostics on stderr, while stdout
+remains a clean data stream. Lifecycle timeout, terminal delivery failure, and a later observation
+failure are the intentional exception: they first preserve the last authoritative Message in a
+result envelope with `partial:true` on stdout.
+
+`samva webhooks test` is another result-bearing failure: an endpoint timeout, transport failure, or
+non-2xx response preserves the complete test result on stdout, emits a typed diagnostic on stderr,
+and exits `1`. Unlike lifecycle polling, that result is complete and does not set `partial:true`.
+
+## Help and command map
+
+```sh
+samva --help
+samva help --json
+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`
+for flags and runnable examples.
+
+Test a configured webhook against its real endpoint with an optional JSON payload. `--data` accepts
+inline JSON or `@file`; omit it for Samva's default test event. `--dry-run` validates and previews
+the request without credentials, an API call, or an endpoint delivery.
+
+```sh
+samva webhooks test wep_abc123 --dry-run
+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, target, 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.
+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
+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.
+
+A command that needs a subcommand, such as a bare `samva` or a group like `samva email`, prints its
+help to stdout and exits `2`, so a script never mistakes a missing subcommand for success.

package/bin/samva

@@ -0,0 +1,3 @@
+#!/bin/sh
+echo "samva: native executable was not installed; reinstall @samva/cli with lifecycle scripts enabled" >&2
+exit 1

package/install.cjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+const { chmodSync, copyFileSync, renameSync, rmSync } = require("node:fs");
+const { dirname, join } = require("node:path");
+
+const target = `${process.platform}-${process.arch}`;
+const supported = new Set(["darwin-arm64", "darwin-x64", "linux-arm64", "linux-x64"]);
+
+if (!supported.has(target)) {
+  console.error(
+    `samva: unsupported platform ${target}; supported platforms are ${[...supported].join(", ")}`,
+  );
+  process.exit(1);
+}
+
+const packageName = `@samva/cli-${target}`;
+let manifest;
+// oxlint-disable-next-line samva/no-try-catch-or-throw -- install-time CommonJS boundary must report a missing optional platform package
+try {
+  manifest = require.resolve(`${packageName}/package.json`, { paths: [__dirname] });
+} catch {
+  console.error(
+    `samva: ${packageName} is missing; reinstall @samva/cli without omitting optional dependencies`,
+  );
+  process.exit(1);
+}
+
+const source = join(dirname(manifest), "samva");
+const destination = join(__dirname, "bin", "samva");
+const temporary = `${destination}.installing`;
+
+rmSync(temporary, { force: true });
+copyFileSync(source, temporary);
+chmodSync(temporary, 0o755);
+renameSync(temporary, destination);

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@samva/cli",
+  "version": "0.1.0",
+  "description": "Samva CLI — email and platform operations from your terminal",
+  "keywords": [
+    "cli",
+    "cpaas",
+    "email",
+    "messaging",
+    "samva"
+  ],
+  "homepage": "https://samva.dev",
+  "bugs": {
+    "url": "https://github.com/AryaLabsHQ/samva/issues"
+  },
+  "license": "MIT",
+  "author": "Arya Labs, Inc.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AryaLabsHQ/samva.git",
+    "directory": "apps/cli"
+  },
+  "bin": {
+    "samva": "./bin/samva"
+  },
+  "files": [
+    "bin/samva",
+    "install.cjs",
+    "package.json",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "samva": "bun src/bin.ts",
+    "build": "tsdown",
+    "build:release-artifacts": "bun run scripts/build-release-artifacts.ts",
+    "test:package": "vitest run --root ../.. --project cli apps/cli/tests/package-install.e2e.test.ts",
+    "test": "vitest run --root ../.. --project cli",
+    "typecheck": "tsgo --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform-bun": "4.0.0-beta.102",
+    "@samva/contracts": "0.0.0",
+    "@samva/core": "0.0.0",
+    "@samva/markup": "0.0.0",
+    "@samva/vite": "0.1.0",
+    "effect": "4.0.0-beta.102",
+    "samva": "0.0.1"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.0-beta.102",
+    "@types/node": "^26.1.1",
+    "tsdown": "^0.22.13",
+    "typescript": "^6.0.3",
+    "vite": "~8.2.0",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "vite": "^7.0.0 || ^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  }
+}