@samva/cli 0.22.0 → 0.22.1

package/AGENTS.md

@@ -1,6 +1,8 @@
 # Samva CLI consumer guide
 
-Use `samva --help` and `samva <command> --help` as the command contract. For automation, prefer
+Use `samva --help` and `samva <command> --help` as the command contract. `--help --json` (or
+`--jsonl`) prints that contract as one result envelope: `data` carries `description`, `usage`,
+`flags`, `globalFlags`, `args`, `subcommands`, and `examples`. 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. Error envelopes carry
 `schemaVersion`, `type`, `command`, `reason`, `message`, and optional `next`. For API failures,

package/dist/bin.mjs

@@ -677,6 +677,7 @@ var identity = (a) => a;
 var constant = (value) => () => value;
 var constTrue = /* @__PURE__ */ constant(true);
 var constFalse = /* @__PURE__ */ constant(false);
+var constNull = /* @__PURE__ */ constant(null);
 var constUndefined = /* @__PURE__ */ constant(undefined);
 var constVoid = constUndefined;
 function pipe(a, ...args) {
@@ -2012,6 +2013,7 @@ var getOrElse = /* @__PURE__ */ dual(2, (self, onNone) => isNone2(self) ? onNone
 var orElse = /* @__PURE__ */ dual(2, (self, that) => isNone2(self) ? that() : self);
 var fromNullishOr = (a) => a == null ? none2() : some2(a);
 var fromUndefinedOr = (a) => a === undefined ? none2() : some2(a);
+var getOrNull = /* @__PURE__ */ getOrElse(constNull);
 var getOrUndefined = /* @__PURE__ */ getOrElse(constUndefined);
 var liftThrowable = (f) => (...a) => {
   try {
@@ -4139,10 +4141,6 @@ var ignore = /* @__PURE__ */ dual((args) => isEffect(args[0]), (self, options) =
     onSuccess: (_) => void_
   });
 });
-var option = (self) => match5(self, {
-  onFailure: none2,
-  onSuccess: some2
-});
 var result = (self) => matchEager(self, {
   onFailure: fail2,
   onSuccess: succeed2
@@ -5744,10 +5742,10 @@ var flatMap3 = flatMap2;
 var andThen2 = andThen;
 var tap2 = tap;
 var result2 = result;
-var option2 = option;
 var exit2 = exit;
 var map7 = map5;
 var as2 = as;
+var asSome2 = asSome;
 var asVoid2 = asVoid;
 var catch_2 = catch_;
 var catchTag2 = catchTag;
@@ -14278,7 +14276,7 @@ var layer12 = /* @__PURE__ */ layer.pipe(/* @__PURE__ */ provideMerge(/* @__PURE
 // package.json
 var package_default = {
   name: "@samva/cli",
-  version: "0.22.0",
+  version: "0.22.1",
   description: "Samva CLI \u2014 email and platform operations from your terminal",
   keywords: [
     "cli",
@@ -14321,7 +14319,7 @@ var package_default = {
     "build:release-artifacts": "bun run scripts/build-release-artifacts.ts",
     test: "vitest run --root ../.. --project cli",
     "test:package": "vitest run --root ../.. --project cli packages/cli/tests/package-install.e2e.test.ts",
-    typecheck: "tsc --noEmit && tsc --noEmit -p tests/consumer/tsconfig.json && tsc --noEmit -p tests/consumer/tsconfig.default.json"
+    typecheck: "tsc-rs --noEmit && tsc-rs --noEmit -p tests/consumer/tsconfig.json && tsc-rs --noEmit -p tests/consumer/tsconfig.default.json"
   },
   devDependencies: {
     "@effect/platform-bun": "catalog:effect",
@@ -14334,16 +14332,16 @@ var package_default = {
     "@types/node": "catalog:",
     "better-auth": "catalog:",
     effect: "catalog:effect",
-    samva: "workspace:0.23.0",
-    typescript: "catalog:",
+    samva: "workspace:0.23.1",
+    "tsc-rs": "catalog:",
     vite: "~8.3.0",
     vitest: "catalog:"
   },
   optionalDependencies: {
-    "@samva/cli-darwin-arm64": "workspace:0.22.0",
-    "@samva/cli-darwin-x64": "workspace:0.22.0",
-    "@samva/cli-linux-arm64": "workspace:0.22.0",
-    "@samva/cli-linux-x64": "workspace:0.22.0"
+    "@samva/cli-darwin-arm64": "workspace:0.22.1",
+    "@samva/cli-darwin-x64": "workspace:0.22.1",
+    "@samva/cli-linux-arm64": "workspace:0.22.1",
+    "@samva/cli-linux-x64": "workspace:0.22.1"
   },
   engines: {
     node: ">=18"
@@ -15841,7 +15839,7 @@ var map10 = /* @__PURE__ */ dual(2, (self, f) => {
 var withDefault3 = /* @__PURE__ */ dual(2, (self, defaultValue) => {
   return make28((provider, pathPrefix) => mapEager2(evaluateAt(self, provider, pathPrefix), (resolution) => isFailure2(resolution) ? succeed2(defaultValue) : resolution));
 });
-var option3 = (self) => self.pipe(map10(some2), withDefault3(none2()));
+var option2 = (self) => self.pipe(map10(some2), withDefault3(none2()));
 var isSourceError = (u) => isTagged(u, "SourceError");
 var cursorToString = () => "<configuration>";
 var mapReasons = (f) => (self) => catchCause2(self, (cause) => failCause3(fromReasons(cause.reasons.map(f))));
@@ -25566,7 +25564,7 @@ var __exportAll = (all, no_symbols) => {
 };
 
 // ../sdk/dist/package.js
-var version = "0.23.0";
+var version = "0.23.1";
 
 // ../sdk/dist/client-attribution.js
 var SDK_VERSION = version;
@@ -67306,7 +67304,7 @@ var reconnectNotice = (output, reconnect) => {
 };
 var tailEvents = (options) => gen2(function* () {
   const provider = yield* getClientProvider;
-  const override = yield* option3(String5("SAMVA_EVENTS_URL"));
+  const override = yield* option2(String5("SAMVA_EVENTS_URL"));
   const eventsUrl = getOrUndefined(override);
   yield* untilInterrupted((interrupted) => provider.provide(events3({
     cursor: options.cursor,
@@ -79974,7 +79972,7 @@ var observeTemplateCheck = (dir, tsconfig, build) => gen2(function* () {
       problems: typeProblems
     }
   });
-  const attempted = typeProblems.length > 0 ? yield* option2(build()) : some2(yield* build());
+  const attempted = typeProblems.length > 0 ? yield* build().pipe(asSome2, catchTag2("SamvaCliError", () => succeed6(none2()))) : some2(yield* build());
   if (isNone2(attempted))
     return typeFailure();
   const built = attempted.value;
@@ -79986,7 +79984,15 @@ var observeTemplateCheck = (dir, tsconfig, build) => gen2(function* () {
   const ok = typeProblems.length === 0 && isSuccessfulBuild(built);
   const compilerVersion = built.compilerVersion;
   const warnings = compatibilityFindings(built, "warning");
-  const message = ok ? `TypeScript v${typecheck.version} \xB7 compiler ${compilerVersion} \xB7 ${built.files.length} template(s) compiled \xB7 ${warnings.length} compatibility warning(s)` : typeProblems.length > 0 ? `TypeScript check failed (${typeProblems.length} problem(s)); template check found ${problems.length - typeProblems.length} more.` : built.files.length === 0 ? NO_TEMPLATES(dir) : `Template check failed (${problems.length} problem(s)).`;
+  const failureMessage = () => {
+    if (typeProblems.length > 0) {
+      return `TypeScript check failed (${typeProblems.length} problem(s)); template check found ${problems.length - typeProblems.length} more.`;
+    }
+    if (built.files.length === 0)
+      return NO_TEMPLATES(dir);
+    return `Template check failed (${problems.length} problem(s)).`;
+  };
+  const message = ok ? `TypeScript v${typecheck.version} \xB7 compiler ${compilerVersion} \xB7 ${built.files.length} template(s) compiled \xB7 ${warnings.length} compatibility warning(s)` : failureMessage();
   return {
     ok,
     message,
@@ -81290,11 +81296,11 @@ var rotate3 = make29("rotate-secret", {
   const client = yield* getClientProvider;
   const data = yield* regenerateSecret({ id }).pipe(client.provide, mapError2((error) => toCliApiError("Could not rotate webhook secret", error)));
   const warning = `Read this signing secret again with samva webhooks secret ${id}. The previous secret remains valid for 24 hours.`;
-  const secret = value2(data.secret);
+  const signingSecret = value2(data.secret);
   if (json)
-    return yield* printJson({ secret, warning });
+    return yield* printJson({ secret: signingSecret, warning });
   yield* error(`WARNING: ${warning}`);
-  yield* log(secret);
+  yield* log(signingSecret);
 }).pipe(json ? provideService2(MinimumLogLevel2, "None") : identity)));
 var create17 = make29("create", {
   data: String9("data").pipe(withDescription2("Webhook JSON: name, url, eventTypes, and optional retry settings")),
@@ -81314,16 +81320,17 @@ var create17 = make29("create", {
   const client = yield* getClientProvider;
   const result = yield* create16(payload).pipe(client.provide, mapError2((error) => toCliApiError("Could not create webhook", error)));
   const warning = `Read this signing secret again with samva webhooks secret ${result.endpoint.id}.`;
-  const secret = value2(result.secret);
-  if (json)
-    return yield* printJson({ endpoint: result.endpoint, secret, warning });
+  const signingSecret = value2(result.secret);
+  if (json) {
+    return yield* printJson({ endpoint: result.endpoint, secret: signingSecret, warning });
+  }
   yield* error(`WARNING: ${warning}`);
   yield* printFields([
     ["ID", result.endpoint.id],
     ["Name", result.endpoint.name],
     ["Status", result.endpoint.status],
     ["URL", result.endpoint.url],
-    ["Signing secret", secret]
+    ["Signing secret", signingSecret]
   ]);
 }).pipe(json ? provideService2(MinimumLogLevel2, "None") : identity)));
 var update15 = make29("update", {
@@ -81454,6 +81461,40 @@ var cli = make29("samva").pipe(withDescription3(`Samva \u2014 email and platform
   }
 ]), withSubcommands([...rootCommands, helpCommand]), withGlobalFlags(globalFlags));
 
+// src/lib/help-json.ts
+var description = (value) => getOrNull(value);
+var flag = (doc) => ({
+  name: doc.name,
+  aliases: doc.aliases,
+  type: doc.type,
+  description: description(doc.description),
+  required: doc.required
+});
+var helpDocJson = (doc) => ({
+  schemaVersion: 1,
+  description: doc.description,
+  usage: doc.usage,
+  flags: doc.flags.map(flag),
+  globalFlags: (doc.globalFlags ?? []).map(flag),
+  args: (doc.args ?? []).map((arg) => ({
+    name: arg.name,
+    type: arg.type,
+    description: description(arg.description),
+    required: arg.required,
+    variadic: arg.variadic
+  })),
+  subcommands: (doc.subcommands ?? []).flatMap((group) => group.commands.map((command) => ({
+    name: command.name,
+    alias: command.alias ?? null,
+    description: command.shortDescription ?? command.description,
+    group: group.group ?? null
+  }))),
+  examples: (doc.examples ?? []).map((example) => ({
+    command: example.command,
+    description: example.description ?? null
+  }))
+});
+
 // src/bin.ts
 var argv = process.argv.slice(2);
 var outputMode = outputModeFromArgv(argv);
@@ -81479,7 +81520,7 @@ var rootMachineHelp = (() => {
   }
   return { requested, command: undefined };
 })();
-var isRootMachineHelp = machineMode && rootMachineHelp.requested && rootMachineHelp.command === undefined;
+var helpRequested = processArgs.some((token) => token === "--help" || token === "-h");
 var isUnknownRootMachineHelp = machineMode && rootMachineHelp.requested && rootMachineHelp.command !== undefined && !isKnownRootCommand(rootMachineHelp.command);
 var cliLogger = make30(({ logLevel, message }) => {
   const text = (Array.isArray(message) ? message : [message]).map(String).join(" ");
@@ -81505,11 +81546,21 @@ var isBareHelp = (error) => error instanceof ShowHelp && error.errors.length ===
 var formatter = {
   ...defaultFormatter2(),
   formatError: () => "",
-  formatErrors: () => ""
+  formatErrors: () => "",
+  ...machineMode && helpRequested ? {
+    formatHelpDoc: (doc) => JSON.stringify(helpDocJson(doc))
+  } : {}
 };
 var flushSuccessfulResults = (state, partial = false) => gen2(function* () {
-  if (outputMode === "quiet" || outputMode === "jsonl")
+  if (outputMode === "quiet")
+    return;
+  if (outputMode === "jsonl") {
+    if (helpRequested && state.lines.length === 1) {
+      yield* writeOutput(process.stdout, `${JSON.stringify(resultEnvelope(commandNameFromArgv(argv), JSON.parse(state.lines[0])))}
+`);
+    }
     return;
+  }
   if (outputMode === "human") {
     if (state.lines.length > 0) {
       yield* writeOutput(process.stdout, `${state.lines.join(`
@@ -81611,12 +81662,7 @@ Try: ${next}`}`);
   }
   yield* printJsonError(error2, message);
 });
-var runMachineHelp = gen2(function* () {
-  const payload = resultEnvelope(commandNameFromArgv(argv), helpManifest);
-  yield* writeOutput(process.stdout, `${JSON.stringify(payload, null, outputMode === "jsonl" ? undefined : 2)}
-`);
-});
-var program = (isRootMachineHelp ? validateProcessArgs(argv).pipe(flatMap3(() => runMachineHelp)) : isUnknownRootMachineHelp ? validateProcessArgs(argv).pipe(flatMap3(() => new CliUsageError({
+var program = (isUnknownRootMachineHelp ? validateProcessArgs(argv).pipe(flatMap3(() => new CliUsageError({
   code: "unknown_subcommand",
   message: `Unknown subcommand ${JSON.stringify(rootMachineHelp.command)} for samva.`
 }))) : withStdoutBuffer(validateProcessArgs(argv).pipe(flatMap3(() => run5(cli, { version: package_default.version }))))).pipe(provide4(mergeAll2(layer14([cliLogger]), layer12, layer13(formatter), layer17)), matchEffect3({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samva/cli",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "Samva CLI — email and platform operations from your terminal",
   "keywords": [
     "cli",
@@ -43,29 +43,29 @@
     "build:release-artifacts": "bun run scripts/build-release-artifacts.ts",
     "test": "vitest run --root ../.. --project cli",
     "test:package": "vitest run --root ../.. --project cli packages/cli/tests/package-install.e2e.test.ts",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p tests/consumer/tsconfig.json && tsc --noEmit -p tests/consumer/tsconfig.default.json"
+    "typecheck": "tsc-rs --noEmit && tsc-rs --noEmit -p tests/consumer/tsconfig.json && tsc-rs --noEmit -p tests/consumer/tsconfig.default.json"
   },
   "devDependencies": {
     "@effect/platform-bun": "4.0.4",
     "@effect/vitest": "4.0.4",
     "@samva/contracts": "0.0.0",
     "@samva/core": "0.0.0",
-    "@samva/mailbox": "0.5.4",
+    "@samva/mailbox": "0.5.5",
     "@samva/markup": "0.17.3",
     "@samva/vite": "0.17.3",
     "@types/node": "^26.6.2",
     "better-auth": "1.7.5",
     "effect": "4.0.4",
-    "samva": "0.23.0",
-    "typescript": "^7.0.2",
+    "samva": "0.23.1",
+    "tsc-rs": "0.7.0",
     "vite": "~8.3.0",
     "vitest": "^5.0.3"
   },
   "optionalDependencies": {
-    "@samva/cli-darwin-arm64": "0.22.0",
-    "@samva/cli-darwin-x64": "0.22.0",
-    "@samva/cli-linux-arm64": "0.22.0",
-    "@samva/cli-linux-x64": "0.22.0"
+    "@samva/cli-darwin-arm64": "0.22.1",
+    "@samva/cli-darwin-x64": "0.22.1",
+    "@samva/cli-linux-arm64": "0.22.1",
+    "@samva/cli-linux-x64": "0.22.1"
   },
   "engines": {
     "node": ">=18"