@dharta/cli 0.6.77 → 0.6.78

package/src/docs/cli-reference.ts

@@ -0,0 +1,206 @@
+// The public CLI reference (apps/docs-site/cli/reference.mdx) is generated from
+// the command tree, not written by hand (RFC 0048 P5). A hand-maintained page
+// is a second copy of the command surface, and the old one had drifted: it
+// never listed `files` or `artifact`, and it still told readers to run
+// `karta --help`.
+//
+// `npm run docs:cli` rewrites the page. A vitest gate renders the same text in
+// memory and fails when the committed file differs, so a new command cannot
+// ship undocumented.
+
+import type { Argument, Command, Option } from "commander";
+
+import { visibleSubcommands } from "../command-tree.js";
+
+// Flags registered on every node by cli.ts. They belong in one section, not in
+// every row of every table.
+const GLOBAL_FLAGS = new Set([
+  "--json",
+  "--jq",
+  "--profile",
+  "--idempotency-key",
+  "--help",
+  "--version",
+]);
+
+const FRONT_MATTER = `---
+title: CLI command reference
+sidebarTitle: Command reference
+description: "Every dharta CLI command, grouped the way \`dharta --help\` groups them, with arguments, options, global flags, and exit codes."
+---`;
+
+const INTRO = `{/* Generated by \`npm run docs:cli\` in sdks/typescript-cli. Do not edit by hand. */}
+
+The fastest local reference is always:
+
+\`\`\`bash
+dharta --help
+dharta <command> --help
+\`\`\`
+
+The groups below are the groups \`dharta --help\` prints. Commands that take a
+positional agent slug infer it from the current folder when you leave it out.`;
+
+const GLOBAL_FLAGS_SECTION = `## Global flags
+
+These work on every command, wherever you put them on the line.
+
+| Flag | Purpose |
+| --- | --- |
+| \`--json\` | Print the result as JSON on stdout. Progress narration goes to stderr, so stdout stays parseable. Stream commands (\`dev\`, \`logs\`, \`completion\`, and git-mode \`deploy\`) reject it instead of ignoring it. |
+| \`--jq <expr>\` | Filter the JSON result through a built-in jq. Implies \`--json\`. Each result prints on its own line, compact; a result that is a string prints without quotes, so \`--jq .name\` pipes cleanly. A filter that matches nothing prints nothing. Rejected wherever \`--json\` is rejected. |
+| \`--profile <name>\` | Use a named profile from \`~/.dharta/config.toml\`. Resolution order is \`--profile\`, then \`DHARTA_PROFILE\`, then the config's default profile. \`dharta login --profile <name>\` creates one; \`dharta auth logout --profile <name>\` removes it. |
+| \`--idempotency-key <key>\` | Send this \`Idempotency-Key\` on every request the command makes, instead of the fresh one each mutation mints. Give a CI job a key it can reuse and a rerun after an ambiguous failure replays the first response, including a secret that is otherwise shown once. Printable ASCII with no spaces, at most 200 characters; the SDK enforces the same shape on every key it is handed, up to the API's 255. |
+
+### Reusing an idempotency key
+
+A mutation that times out may or may not have been performed, and without a key
+you have no way to find out but to look. Every \`dharta\` mutation mints a fresh
+key per process, which protects one run from itself but cannot help a second
+run: to the platform, the retry is a new request.
+
+Pin the key to the job, not to the process:
+
+\`\`\`bash
+dharta keys create ci-release --scope releases:write \\
+  --idempotency-key "release-$GITHUB_RUN_ID"
+\`\`\`
+
+Rerun that step with the same \`GITHUB_RUN_ID\` and you get the first run's
+response back, secret included, instead of a second key.
+
+Four rules come with it:
+
+- **One key per command.** The platform binds a key to the request it first saw
+  and answers a different request under the same key with \`422\`. Two commands
+  sharing one key collide, so give each mutating step its own.
+- **A command that writes more than once splits the key for you.** \`dharta
+  send\` opens a session and then runs a turn; \`dharta schedules create
+  --run-now\` creates a schedule and then queues a run of it; \`dharta dev\`
+  runs a turn per prompt. Each write gets a suffix naming its operation, so the
+  wire carries \`<key>.sessions.create\` and \`<key>.sessions.turn\`, or
+  \`<key>.schedules.create\` and \`<key>.schedules.run\`. The writes never
+  collide with each other, and a rerun under the same key replays every one of
+  them instead of opening a second session, creating a second schedule, or
+  paying for a second inference. That is why the key is capped at 200 rather
+  than the platform's 255 - the rest is reserved for the suffix. A command that
+  writes once sends your key exactly as you typed it.
+- **Retry \`5xx\` and \`429\` with the same key.** Those answers are never
+  stored, so reusing the key re-drives the work rather than replaying a failure.
+- **A command with nothing to protect refuses the flag.** \`dharta login\`,
+  \`create\`, \`setup\`, \`genui\`, \`artifact\`, \`doctor\`,
+  \`update\`, \`completion\`, \`auth token\` and \`auth logout\` perform
+  no mutation the key could cover. Some of them do call Dharta - \`login\`
+  reads \`/me\`, \`create\` fetches the template list - but none of them
+  writes. Passing the key there exits 2 rather than being quietly dropped.
+  Read-only commands do accept it, because they are steps in a run that writes
+  and the header is ignored server-side.
+
+## Exit codes
+
+Scripts can branch on the exit code instead of parsing messages.
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success. |
+| 1 | General failure. |
+| 2 | Usage error: an unknown flag, a bad value, a missing argument, or an unknown profile. |
+| 3 | Not authenticated. No credential is stored, or the API answered 401. |
+| 4 | Forbidden. The API answered 403, usually a missing scope on the key. |
+| 5 | Not found. The API answered 404. |
+| 6 | Validation failure. The API answered 409 or 422. |
+| 7 | The API host could not be reached. |
+
+\`dharta doctor\` is the exception: it exits 1 when a local check fails, which is
+a report, not an error.`;
+
+export function renderCliReference(program: Command): string {
+  const sections = groupCommands(program).map(([group, commands]) => renderGroup(group, commands));
+  return [FRONT_MATTER, "", INTRO, "", ...sections, GLOBAL_FLAGS_SECTION, ""].join("\n");
+}
+
+// Group heading -> the top-level commands in it, in tree order. Commander
+// stores the heading with a trailing colon ("Management:"); the page uses it as
+// a title, so the colon comes off.
+function groupCommands(program: Command): Array<[string, Command[]]> {
+  const groups = new Map<string, Command[]>();
+  for (const cmd of visibleSubcommands(program)) {
+    const heading = cmd.helpGroup().replace(/:$/, "");
+    if (!heading) {
+      throw new Error(`\`dharta ${cmd.name()}\` has no help group, so it has nowhere to go in the reference.`);
+    }
+    const bucket = groups.get(heading);
+    if (bucket) bucket.push(cmd);
+    else groups.set(heading, [cmd]);
+  }
+  return [...groups.entries()];
+}
+
+function renderGroup(heading: string, commands: Command[]): string {
+  const rows = commands.flatMap((cmd) => flatten(cmd)).map(renderRow);
+  return [
+    `## ${heading}`,
+    "",
+    "| Command | Arguments | Options | Description |",
+    "| --- | --- | --- | --- |",
+    ...rows,
+    "",
+  ].join("\n");
+}
+
+function flatten(cmd: Command): Command[] {
+  return [cmd, ...visibleSubcommands(cmd).flatMap(flatten)];
+}
+
+function renderRow(cmd: Command): string {
+  return `| ${code(commandPath(cmd))} | ${code(argumentList(cmd))} | ${optionList(cmd)} | ${prose(cmd.description())} |`;
+}
+
+// `dharta send|run`, matching how commander prints an aliased command.
+function commandPath(cmd: Command): string {
+  const names: string[] = [];
+  let cursor: Command | null = cmd;
+  while (cursor) {
+    const aliases = cursor.aliases();
+    names.unshift(cursor === cmd && aliases.length > 0 ? [cursor.name(), ...aliases].join("|") : cursor.name());
+    cursor = cursor.parent;
+  }
+  return names.join(" ");
+}
+
+function argumentList(cmd: Command): string {
+  return cmd.registeredArguments
+    .map((arg: Argument) => {
+      const name = `${arg.name()}${arg.variadic ? "..." : ""}`;
+      return arg.required ? `<${name}>` : `[${name}]`;
+    })
+    .join(" ");
+}
+
+function optionList(cmd: Command): string {
+  const flags = cmd.options
+    .filter((option: Option) => !option.hidden && !GLOBAL_FLAGS.has(option.long ?? ""))
+    .map((option: Option) => code(option.flags));
+  return flags.length > 0 ? flags.join(", ") : escapePipes("Global flags only");
+}
+
+function code(text: string): string {
+  return text ? `\`${escapePipes(text)}\`` : "";
+}
+
+function prose(text: string): string {
+  const collapsed = text.replace(/\s+/g, " ").trim();
+  // MDX parses `<` as JSX and `{` as an expression, but not inside an inline
+  // code span - and escaping inside one would print the entity. Split on code
+  // spans and escape only the prose between them.
+  const escaped = collapsed
+    .split(/(`[^`]*`)/)
+    .map((part) => (part.startsWith("`") ? part : part.replace(/</g, "&lt;").replace(/\{/g, "&#123;")))
+    .join("");
+  return escapePipes(escaped);
+}
+
+// A bare `|` would end the table cell, including inside a code span.
+function escapePipes(text: string): string {
+  return text.replace(/\|/g, "\\|");
+}

package/src/exit-codes.ts

@@ -0,0 +1,122 @@
+// Exit-code taxonomy (RFC 0048 D1/P5). A script that pipes `dharta` needs to
+// branch on *why* a command failed without parsing English, so every failure
+// maps to one of these codes. The numbers are a public contract: change a
+// meaning and every caller's `if [ $? -eq 4 ]` silently means something else.
+//
+// `dharta doctor` is the one exception: it reports an unhealthy local setup
+// with its own exit 1 without throwing, so it never reaches this map.
+
+import { INVALID_IDEMPOTENCY_KEY_CODE } from "@dharta/sdk";
+
+export const EXIT_SUCCESS = 0;
+export const EXIT_GENERAL = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_NOT_AUTHENTICATED = 3;
+export const EXIT_FORBIDDEN = 4;
+export const EXIT_NOT_FOUND = 5;
+export const EXIT_VALIDATION = 6;
+export const EXIT_NETWORK = 7;
+
+// A wrong invocation: an unknown flag, a bad choice, a missing argument, a
+// profile that is not in the config file. Commander raises its own version of
+// this; throw CliUsageError for the ones the CLI detects itself.
+//
+// The line, applied across every curated command (RFC 0048 P9): a throw that
+// rejects a value the caller TYPED is a usage error. A throw that reports the
+// state of the world - a file that is not there, a server too old to answer, a
+// build that failed - is a plain Error and exits 1. `test/usage-exit-code.test.ts`
+// holds both halves: a table exercising each validator, and a source scan that
+// makes a new plain Error in a command module argue for itself.
+export class CliUsageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CliUsageError";
+  }
+}
+
+// The control plane answered with a non-2xx status.
+export class CliApiError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+
+  constructor(message: string, status: number, body: unknown) {
+    super(message);
+    this.name = "CliApiError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+// The control plane could not be reached at all (DNS, refused connection, TLS).
+// Distinct from CliApiError: retrying may help, and no request was authorized.
+export class CliNetworkError extends Error {
+  readonly url: string;
+
+  constructor(message: string, url: string) {
+    super(message);
+    this.name = "CliNetworkError";
+    this.url = url;
+  }
+}
+
+// Commander's own failures. `commander.helpDisplayed` and `commander.version`
+// are successful runs that unwind through the same catch, so they keep their
+// own exit code (0); everything else commander raises is a usage error.
+interface CommanderErrorShape {
+  code?: unknown;
+  exitCode?: unknown;
+}
+
+export function isCommanderError(err: unknown): boolean {
+  const code = (err as CommanderErrorShape | null)?.code;
+  return typeof code === "string" && code.startsWith("commander.");
+}
+
+export function exitCodeForError(err: unknown): number {
+  if (isCommanderError(err)) {
+    const exitCode = (err as CommanderErrorShape).exitCode;
+    return exitCode === 0 ? EXIT_SUCCESS : EXIT_USAGE;
+  }
+  if (err instanceof CliUsageError) return EXIT_USAGE;
+  // The SDK rejects a malformed Idempotency-Key wherever it was supplied,
+  // including a header a caller wrote by hand with `dharta api -H`, which never
+  // passes through a CLI validator. It is still a value the caller typed, so it
+  // gets the code every other rejected value gets. Matched on the stable `code`
+  // rather than the class, so a duplicated SDK install cannot break it.
+  if (isInvalidIdempotencyKeyError(err)) return EXIT_USAGE;
+  if (err instanceof CliNetworkError) return EXIT_NETWORK;
+
+  const status = (err as { status?: unknown } | null)?.status;
+  if (typeof status === "number") return exitCodeForStatus(status);
+  if (isNotAuthenticatedError(err)) return EXIT_NOT_AUTHENTICATED;
+  return EXIT_GENERAL;
+}
+
+// `Not logged in.` is raised locally when no credential is stored, before any
+// request goes out. It is the same condition a 401 reports, so it gets the same
+// exit code - otherwise `dharta whoami` means one thing logged out and another
+// with a revoked key. Commands that fall back when unauthenticated test the
+// same predicate, so the two readings cannot drift apart.
+export function isInvalidIdempotencyKeyError(err: unknown): boolean {
+  return (err as { code?: unknown } | null)?.code === INVALID_IDEMPOTENCY_KEY_CODE;
+}
+
+export function isNotAuthenticatedError(err: unknown): boolean {
+  return err instanceof Error && /^Not logged in\b/.test(err.message);
+}
+
+export function exitCodeForStatus(status: number): number {
+  switch (status) {
+    case 401:
+      return EXIT_NOT_AUTHENTICATED;
+    case 403:
+      return EXIT_FORBIDDEN;
+    case 404:
+      return EXIT_NOT_FOUND;
+    case 409:
+    case 422:
+      return EXIT_VALIDATION;
+    default:
+      return EXIT_GENERAL;
+  }
+}