@samva/cli 0.1.0 → 0.1.2

package/AGENTS.md

@@ -10,5 +10,7 @@ loads the project's installed authoring toolchain so its compiler and editor ver
 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.
+`@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.

package/README.md

@@ -1,8 +1,9 @@
 # @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.
+The `samva` CLI sends and operates email from a terminal. The npm package includes
+the JavaScript implementation and selects a self-contained native executable when
+one is available. Template authoring commands run the project's `@samva/vite`
+toolchain under Node.js 22 or newer.
 
 ## Install
 
@@ -11,8 +12,10 @@ 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).
+The npm package prefers the matching macOS or Linux executable. If npm omits
+optional dependencies, the same command falls back to the packaged JavaScript
+implementation when Bun is installed. Compiled binaries are also available from
+[GitHub releases](https://github.com/AryaLabsHQ/samva/releases).
 
 ## Shell completions
 
@@ -70,7 +73,7 @@ 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`.
+the Portless API origin `https://api.samva.localhost`. `production` targets `https://api.samva.dev`.
 
 ## Common operations
 
@@ -100,6 +103,14 @@ samva messages events <message-id> --json
 
 # Inspect configuration and remote email state without mutating it.
 samva email doctor --json
+
+# Read and set organization open/click tracking defaults.
+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
 ```
 
 ## Template projects

package/bin/samva.cjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+const { spawn } = require("node:child_process");
+const { existsSync } = require("node:fs");
+const { dirname, join } = require("node:path");
+
+const forwardedSignals = ["SIGINT", "SIGTERM", "SIGHUP"];
+
+const run = (command, args) => {
+  const child = spawn(command, args, { stdio: "inherit" });
+  const forwarders = new Map();
+
+  for (const signal of forwardedSignals) {
+    const forward = () => child.kill(signal);
+    forwarders.set(signal, forward);
+    process.on(signal, forward);
+  }
+
+  child.on("error", (error) => {
+    if (error.code === "ENOENT" && command === "bun") {
+      console.error(
+        "samva: the native executable is unavailable and Bun is not installed; reinstall @samva/cli with optional dependencies or install Bun",
+      );
+    } else {
+      console.error(`samva: ${error.message}`);
+    }
+    process.exitCode = 1;
+  });
+
+  child.on("exit", (code, signal) => {
+    for (const [forwardedSignal, forward] of forwarders) {
+      process.removeListener(forwardedSignal, forward);
+    }
+    if (signal) process.kill(process.pid, signal);
+    else process.exitCode = code ?? 1;
+  });
+};
+
+const target = `${process.platform}-${process.arch}`;
+const packageName = `@samva/cli-${target}`;
+let nativeExecutable;
+
+// oxlint-disable-next-line samva/no-try-catch-or-throw -- CommonJS launcher probes an optional platform package before using the Bun fallback
+try {
+  const manifest = require.resolve(`${packageName}/package.json`, { paths: [__dirname] });
+  const candidate = join(dirname(manifest), "samva");
+  if (existsSync(candidate)) nativeExecutable = candidate;
+} catch {
+  // npm may omit optional dependencies. The JavaScript distribution below is
+  // the supported fallback rather than an installation-time failure.
+}
+
+if (nativeExecutable) {
+  run(nativeExecutable, process.argv.slice(2));
+} else {
+  run("bun", [join(__dirname, "..", "dist", "bin.mjs"), ...process.argv.slice(2)]);
+}