@dharta/cli 0.6.77 → 0.6.78

package/dist/completions.js

@@ -2,6 +2,12 @@
 // scripts generated statically by walking the commander program - no
 // runtime dependency, no shelling out. The output is a snapshot of this
 // CLI version's command surface; regenerate after updating.
+import { visibleSubcommands } from "./command-tree.js";
+// zsh looks up `_<command>` by convention and bash needs a legal shell
+// identifier, so non-word characters in the binary name become underscores.
+function completionFunctionName(bin) {
+    return `_${bin.replace(/[^A-Za-z0-9_]/g, "_")}`;
+}
 export function specFromCommand(cmd) {
     return {
         name: cmd.name(),
@@ -12,9 +18,7 @@ export function specFromCommand(cmd) {
             "--help",
         ],
         argChoices: cmd.registeredArguments.flatMap((a) => a.argChoices ?? []),
-        subs: cmd.commands
-            .filter((c) => !c._hidden)
-            .map((c) => specFromCommand(c)),
+        subs: visibleSubcommands(cmd).map((c) => specFromCommand(c)),
     };
 }
 // First sentence, single line. Shell-specific escaping happens when rendering
@@ -78,10 +82,15 @@ function escapeZshDescription(value) {
 export function bashCompletion(program) {
     const spec = specFromCommand(program);
     const entries = completionEntries(spec);
+    // The binary name comes from the program, never a literal: these scripts
+    // bound `karta` for the whole life of the renamed CLI, so `complete -F`
+    // attached to a command that no longer exists and completion was dead.
+    const bin = program.name();
+    const fn = completionFunctionName(bin);
     const lines = [
-        "# bash completion for karta - generated by `dharta completion bash`",
-        "# Load with: source <(dharta completion bash)  (or append to ~/.bash_completion)",
-        "_karta() {",
+        `# bash completion for ${bin} - generated by \`${bin} completion bash\``,
+        `# Load with: source <(${bin} completion bash)  (or append to ~/.bash_completion)`,
+        `${fn}() {`,
         '  local cur="${COMP_WORDS[COMP_CWORD]}"',
         '  local path="${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}"',
         '  local words=""',
@@ -90,18 +99,20 @@ export function bashCompletion(program) {
     for (const entry of entries) {
         lines.push(`    "${escapeBashCase(entry.path)}") words="${escapeBashCase(entry.words)}" ;;`);
     }
-    lines.push("  esac", '  COMPREPLY=( $(compgen -W "$words" -- "$cur") )', "}", "complete -F _karta karta");
+    lines.push("  esac", '  COMPREPLY=( $(compgen -W "$words" -- "$cur") )', "}", `complete -F ${fn} ${bin}`);
     return lines.join("\n");
 }
 export function zshCompletion(program) {
     const spec = specFromCommand(program);
     const entries = completionEntries(spec);
+    const bin = program.name();
+    const fn = completionFunctionName(bin);
     const lines = [
-        "#compdef karta",
-        "# zsh completion for karta - generated by `dharta completion zsh`",
-        "# Install: dharta completion zsh > ~/.zfunc/_dharta  (with fpath+=(~/.zfunc) before compinit)",
+        `#compdef ${bin}`,
+        `# zsh completion for ${bin} - generated by \`${bin} completion zsh\``,
+        `# Install: ${bin} completion zsh > ~/.zfunc/${fn}  (with fpath+=(~/.zfunc) before compinit)`,
         "",
-        "_karta() {",
+        `${fn}() {`,
         "  local -a reply",
         '  local path=""',
         "  if (( CURRENT > 2 )); then",
@@ -111,10 +122,10 @@ export function zshCompletion(program) {
     ];
     for (const entry of entries) {
         lines.push(`    ${zshCasePattern(entry.path)})`, entry.describedCommands
-            ? `      reply=( ${entry.describedCommands} ); _describe -t commands 'dharta command' reply`
+            ? `      reply=( ${entry.describedCommands} ); _describe -t commands '${bin} command' reply`
             : "      true", entry.words ? `      compadd -- ${entry.words}` : "      true", "      return", "      ;;");
     }
-    lines.push("  esac", "}", "", '_karta "$@"');
+    lines.push("  esac", "}", "", `${fn} "$@"`);
     return lines.join("\n");
 }
 //# sourceMappingURL=completions.js.map

package/dist/completions.js.map

@@ -1 +1 @@
-{"version":3,"file":"completions.js","sourceRoot":"","sources":["../src/completions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"completions.js","sourceRoot":"","sources":["../src/completions.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -1,3 +1,5 @@
+import { MAX_IDEMPOTENCY_KEY_LENGTH } from "@dharta/sdk";
+import { CliUsageError } from "./exit-codes.js";
 export interface Profile {
     api_key: string;
     base_url: string;
@@ -9,6 +11,15 @@ export interface Config {
     profiles: Record<string, Profile>;
 }
 export declare function setHomeForTesting(home: string | undefined): void;
+export declare function setRequestedProfile(name: string | undefined): void;
+export declare const MAX_OPERATION_SUFFIX_LENGTH = 55;
+export { MAX_IDEMPOTENCY_KEY_LENGTH };
+export declare const MAX_ROOT_IDEMPOTENCY_KEY_LENGTH: number;
+export declare function setRequestedIdempotencyKey(key: string | undefined): void;
+export declare function requestedIdempotencyKeyValue(): string | undefined;
+export declare function mintIdempotencyKey(operation: string): string;
+export declare function explicitProfileName(): string | undefined;
+export declare function requestedProfileName(): string | undefined;
 export declare function configPath(): string;
 declare const DEFAULT_BASE_URL = "https://dharta.ai";
 declare const DEFAULT_GIT_BASE_URL = "https://git.dharta.ai";
@@ -16,5 +27,6 @@ export declare function loadConfig(): Promise<Config | null>;
 export declare function saveProfile(name: string, profile: Profile): Promise<string>;
 export declare function removeProfile(name: string): Promise<boolean>;
 export declare function activeProfile(): Promise<Profile>;
+export declare function profileNotFoundError(name: string): CliUsageError;
 export declare function resolveBaseUrl(): Promise<string>;
 export { DEFAULT_BASE_URL, DEFAULT_GIT_BASE_URL };

package/dist/config.js

@@ -1,12 +1,109 @@
+import { randomUUID } from "node:crypto";
 import { promises as fs } from "node:fs";
 import { homedir } from "node:os";
 import * as path from "node:path";
 import TOML from "@iarna/toml";
+import { assertIdempotencyKey, MAX_IDEMPOTENCY_KEY_LENGTH } from "@dharta/sdk";
+import { CliUsageError } from "./exit-codes.js";
+import { normalizeNonBlank } from "./validators.js";
 // Allow tests to redirect HOME without setting process.env.HOME globally.
 let homeOverride;
 export function setHomeForTesting(home) {
     homeOverride = home;
 }
+// The profile named by the global `--profile` flag, recorded once per run by
+// the root preAction hook in cli.ts. Resolution order for every command is:
+// explicit --profile, then DHARTA_PROFILE, then the config's default_profile
+// (the aws --profile shape, RFC 0048 D2).
+let requestedProfile;
+export function setRequestedProfile(name) {
+    requestedProfile = name === undefined ? undefined : normalizeNonBlank(name, "--profile");
+}
+// The Idempotency-Key named by the global `--idempotency-key` flag, recorded
+// once per run by the same preAction hook. It rides here rather than in each
+// command because it is a property of the RUN, not of one call: a CI job that
+// reruns after an ambiguous failure has to present the key the first run used,
+// and every curated command mints a fresh one per process otherwise.
+//
+// What a key may contain is the SDK's rule (`assertIdempotencyKey`), written
+// down once in sdks/typescript/src/idempotency.ts and enforced by the client on
+// every key it is handed. The CLI checks it here as well, so a bad flag value is
+// a usage error before any request goes out rather than a failure part way
+// through a run.
+// A command that performs more than one mutation cannot send the root key on
+// both: the server binds a key to the first request it saw and answers the
+// second with a 422. Such a command derives one key per operation instead (see
+// mintIdempotencyKey), which keeps the writes apart from each other and stable
+// across reruns. The cap applies to the WHOLE header value, so the root has to
+// leave room for the longest suffix we append.
+export const MAX_OPERATION_SUFFIX_LENGTH = 55;
+export { MAX_IDEMPOTENCY_KEY_LENGTH };
+export const MAX_ROOT_IDEMPOTENCY_KEY_LENGTH = MAX_IDEMPOTENCY_KEY_LENGTH - MAX_OPERATION_SUFFIX_LENGTH;
+let requestedIdempotencyKey;
+export function setRequestedIdempotencyKey(key) {
+    if (key === undefined) {
+        requestedIdempotencyKey = undefined;
+        return;
+    }
+    const normalized = normalizeNonBlank(key, "--idempotency-key");
+    try {
+        assertIdempotencyKey(normalized, "--idempotency-key");
+    }
+    catch (error) {
+        // The SDK owns what a key may contain; the CLI owns what a rejected flag
+        // value exits with. Re-wrapping keeps both true and keeps the wording in
+        // one place.
+        throw new CliUsageError(error.message);
+    }
+    if (normalized.length > MAX_ROOT_IDEMPOTENCY_KEY_LENGTH) {
+        throw new CliUsageError(`--idempotency-key must be at most ${MAX_ROOT_IDEMPOTENCY_KEY_LENGTH} characters. ` +
+            `The server accepts ${MAX_IDEMPOTENCY_KEY_LENGTH}; the difference is reserved for the ` +
+            "per-operation suffix a multi-mutation command appends.");
+    }
+    requestedIdempotencyKey = normalized;
+}
+export function requestedIdempotencyKeyValue() {
+    return requestedIdempotencyKey;
+}
+// Dotted lowercase, so a derived key reads as `<root>.sessions.turn.2` and the
+// operation cannot smuggle in whitespace or a separator of its own.
+const IDEMPOTENCY_OPERATION_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+// The Idempotency-Key for ONE mutation. With no root key this is a fresh UUID,
+// which is what every command did before the flag existed. With a root key it
+// is `<root>.<operation>`: two mutations in the same run get different keys, and
+// the same mutation in a later run with the same root gets the same key, which
+// is what makes the rerun replay instead of repeating the work.
+//
+// `operation` is written by us, never by the caller, so a bad one is a
+// programming error and throws a plain Error (exit 1), not a usage error.
+export function mintIdempotencyKey(operation) {
+    if (!IDEMPOTENCY_OPERATION_PATTERN.test(operation)) {
+        throw new Error(`Idempotency operation ${JSON.stringify(operation)} is not a dotted lowercase token.`);
+    }
+    const suffix = `.${operation}`;
+    if (suffix.length > MAX_OPERATION_SUFFIX_LENGTH) {
+        throw new Error(`Idempotency operation ${JSON.stringify(operation)} exceeds the ` +
+            `${MAX_OPERATION_SUFFIX_LENGTH}-character reserve.`);
+    }
+    return requestedIdempotencyKey === undefined
+        ? randomUUID()
+        : `${requestedIdempotencyKey}${suffix}`;
+}
+// The profile named by the flag alone, ignoring DHARTA_PROFILE. An explicit
+// flag is a deliberate act and outranks an ambient credential in the
+// environment; the env var does not.
+export function explicitProfileName() {
+    return requestedProfile;
+}
+// The explicitly requested profile, or undefined to mean "the default one".
+// Commands that operate ON a profile (login, auth logout) read this rather
+// than the resolved name, so omitting the flag keeps their existing meaning.
+export function requestedProfileName() {
+    if (requestedProfile !== undefined)
+        return requestedProfile;
+    const fromEnv = process.env.DHARTA_PROFILE?.trim();
+    return fromEnv ? fromEnv : undefined;
+}
 export function configPath() {
     const home = homeOverride ?? process.env.HOME ?? homedir();
     return path.join(home, ".dharta", "config.toml");
@@ -67,13 +164,17 @@ export async function removeProfile(name) {
 }
 export async function activeProfile() {
     const cfg = await loadConfig();
+    const requested = requestedProfileName();
     if (!cfg) {
-        throw new Error("Not logged in. Run `dharta login` to store an API key in ~/.dharta/config.toml.");
+        throw new Error(`Not logged in. Run \`dharta login${requested ? ` --profile ${requested}` : ""}\` ` +
+            "to store an API key in ~/.dharta/config.toml.");
     }
-    const profile = cfg.profiles[cfg.default_profile];
+    const name = requested ?? cfg.default_profile;
+    const profile = cfg.profiles[name];
     if (!profile) {
-        throw new Error(`Default profile '${cfg.default_profile}' not found in ${configPath()}. ` +
-            "Run `dharta login` to recreate it.");
+        throw requested
+            ? profileNotFoundError(name)
+            : new CliUsageError(`Default profile '${name}' not found in ${configPath()}. Run \`dharta login\` to recreate it.`);
     }
     return {
         api_key: profile.api_key,
@@ -82,15 +183,28 @@ export async function activeProfile() {
         workspace_git_base_url: profile.workspace_git_base_url,
     };
 }
+// One message for "you named a profile that is not stored", shared by
+// activeProfile, `auth token`, and `auth logout` so the three agree on what
+// happened and on the exit code (2, a usage error).
+export function profileNotFoundError(name) {
+    return new CliUsageError(`Profile '${name}' not found in ${configPath()}. ` +
+        `Run \`dharta login --profile ${name}\` to create it, or \`dharta auth status\` to list profiles.`);
+}
 // Base URL for commands that work without a credential (init's template
-// fetch): env override, then the stored profile, then the default.
+// fetch): env override, then the stored profile, then the default. An explicit
+// --profile pins the host to that profile, the same rule buildContext applies.
 export async function resolveBaseUrl() {
-    if (process.env.DHARTA_BASE_URL)
+    const pinnedToProfile = explicitProfileName() !== undefined;
+    if (process.env.DHARTA_BASE_URL && !pinnedToProfile)
         return process.env.DHARTA_BASE_URL;
     try {
         return (await activeProfile()).base_url;
     }
-    catch {
+    catch (err) {
+        // A profile the user named and that does not exist is their mistake, not a
+        // missing credential: say so instead of quietly using the default host.
+        if (pinnedToProfile)
+            throw err;
         return DEFAULT_BASE_URL;
     }
 }

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,IAAI,MAAM,aAAa,CAAC;AA6B/B,0EAA0E;AAC1E,IAAI,YAAgC,CAAC;AAErC,MAAM,UAAU,iBAAiB,CAAC,IAAwB;IACxD,YAAY,GAAG,IAAI,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,MAAM,IAAI,GAAG,YAAY,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,EAAE,CAAC;IAC3D,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC;AACnD,CAAC;AAED,wEAAwE;AACxE,oEAAoE;AACpE,0BAA0B;AAC1B,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAC7C,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAErD,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,MAAM,CAAC,CAAC;QACpD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA+B,CAAC;QAC7D,IAAI,CAAC,MAAM,CAAC,eAAe,IAAI,CAAC,MAAM,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC7D,OAAO;YACL,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,QAAQ,EAAE,MAAM,CAAC,QAAQ;SAC1B,CAAC;IACJ,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAClE,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAY,EACZ,OAAgB;IAEhB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACvE,MAAM,QAAQ,GAAG,CAAC,MAAM,UAAU,EAAE,CAAC,IAAI;QACvC,eAAe,EAAE,IAAI;QACrB,QAAQ,EAAE,EAAE;KACb,CAAC;IACF,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;IAClC,QAAQ,CAAC,eAAe,GAAG,IAAI,CAAC;IAChC,MAAM,EAAE,CAAC,SAAS,CAChB,MAAM,EACN,IAAI,CAAC,SAAS,CAAC,QAAmC,CAAC,EACnD;QACE,IAAI,EAAE,KAAK;KACZ,CACF,CAAC;IACF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,oEAAoE;AACpE,qEAAqE;AACrE,oEAAoE;AACpE,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAY;IAC9C,MAAM,GAAG,GAAG,MAAM,UAAU,EAAE,CAAC;IAC/B,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9C,OAAO,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAE1B,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,EAAE,CAAC,EAAE,CAAC,UAAU,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,GAAG,CAAC,eAAe,KAAK,IAAI;QAAE,GAAG,CAAC,eAAe,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IACrE,MAAM,EAAE,CAAC,SAAS,CAChB,UAAU,EAAE,EACZ,IAAI,CAAC,SAAS,CAAC,GAA8B,CAAC,EAC9C,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAC;IACF,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa;IACjC,MAAM,GAAG,GAAG,MAAM,UAAU,EAAE,CAAC;IAC/B,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,iFAAiF,CAClF,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAClD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,oBAAoB,GAAG,CAAC,eAAe,kBAAkB,UAAU,EAAE,IAAI;YACvE,oCAAoC,CACvC,CAAC;IACJ,CAAC;IACD,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,gBAAgB;QAC9C,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,oBAAoB;QAC1D,sBAAsB,EAAE,OAAO,CAAC,sBAAsB;KACvD,CAAC;AACJ,CAAC;AAED,wEAAwE;AACxE,mEAAmE;AACnE,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IACpE,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,aAAa,EAAE,CAAC,CAAC,QAAQ,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,gBAAgB,CAAC;IAC1B,CAAC;AACH,CAAC;AAED,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/context.d.ts

@@ -5,10 +5,12 @@ export interface CliContext {
     baseUrl: string;
     apiKey: string;
     fetch?: typeof fetch;
+    idempotencyKey?: string;
 }
 export interface CtxOverrides {
     apiKey?: string;
     baseUrl?: string;
     fetch?: typeof fetch;
+    idempotencyKey?: string;
 }
 export declare function buildContext(over?: CtxOverrides): Promise<CliContext>;

package/dist/context.js

@@ -1,14 +1,21 @@
 import { Dharta, HttpClient } from "@dharta/sdk";
-import { activeProfile, DEFAULT_BASE_URL } from "./config.js";
+import { activeProfile, explicitProfileName, requestedIdempotencyKeyValue, DEFAULT_BASE_URL, } from "./config.js";
 import { cliFormatError, cliFormatNetworkError } from "./api-error.js";
 export async function buildContext(over = {}) {
     let apiKey = over.apiKey;
     let baseUrl = over.baseUrl;
-    // Env overrides config everywhere (the GH_TOKEN pattern, RFC 0013
-    // §2); explicit per-call overrides beat both. DHARTA_BASE_URL applies
-    // regardless of where the key came from, matching resolveBaseUrl.
-    baseUrl = baseUrl ?? process.env.DHARTA_BASE_URL;
-    if (!apiKey && process.env.DHARTA_API_KEY) {
+    // An explicit `--profile` outranks BOTH ambient settings: the key and the
+    // host are one credential. Without this, a shell that exports a key would
+    // silently send `--profile staging` at whatever org that key belongs to, and
+    // an exported DHARTA_BASE_URL would send the profile's key to a host it was
+    // never issued for. DHARTA_PROFILE does NOT get this treatment: two ambient
+    // settings, and the environment still wins.
+    const pinnedToProfile = explicitProfileName() !== undefined;
+    // Env overrides config everywhere (the GH_TOKEN pattern, RFC 0013 §2);
+    // explicit per-call overrides beat both.
+    if (!pinnedToProfile)
+        baseUrl = baseUrl ?? process.env.DHARTA_BASE_URL;
+    if (!apiKey && process.env.DHARTA_API_KEY && !pinnedToProfile) {
         apiKey = process.env.DHARTA_API_KEY;
     }
     if (!apiKey) {
@@ -19,12 +26,20 @@ export async function buildContext(over = {}) {
     if (!baseUrl)
         baseUrl = DEFAULT_BASE_URL;
     const fetchImpl = over.fetch;
+    // The global `--idempotency-key`, applied once here rather than threaded
+    // through every curated command. The client sends it on every request that
+    // does not name a key of its own, which is what makes a CI rerun after an
+    // ambiguous failure replay the first response instead of performing the
+    // mutation a second time. A command that writes more than once names a
+    // derived key per write, and those survive.
+    const idempotencyKey = over.idempotencyKey ?? requestedIdempotencyKeyValue();
     const sdk = new Dharta({
         apiKey,
         baseUrl,
         fetch: fetchImpl,
         formatError: cliFormatError,
         formatNetworkError: cliFormatNetworkError,
+        idempotencyKey,
     });
     const http = new HttpClient({
         apiKey,
@@ -32,7 +47,8 @@ export async function buildContext(over = {}) {
         fetch: fetchImpl,
         formatError: cliFormatError,
         formatNetworkError: cliFormatNetworkError,
+        idempotencyKey,
     });
-    return { sdk, http, baseUrl, apiKey, fetch: fetchImpl };
+    return { sdk, http, baseUrl, apiKey, fetch: fetchImpl, idempotencyKey };
 }
 //# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAsBvE,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAqB,EAAE;IAEvB,IAAI,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACzB,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC3B,kEAAkE;IAClE,sEAAsE;IACtE,kEAAkE;IAClE,OAAO,GAAG,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IACjD,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC;QAC1C,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IACtC,CAAC;IACD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,CAAC,GAAG,MAAM,aAAa,EAAE,CAAC;QAChC,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC;QACnB,OAAO,GAAG,OAAO,IAAI,CAAC,CAAC,QAAQ,CAAC;IAClC,CAAC;IACD,IAAI,CAAC,OAAO;QAAE,OAAO,GAAG,gBAAgB,CAAC;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC;IAC7B,MAAM,GAAG,GAAG,IAAI,MAAM,CAAC;QACrB,MAAM;QACN,OAAO;QACP,KAAK,EAAE,SAAS;QAChB,WAAW,EAAE,cAAc;QAC3B,kBAAkB,EAAE,qBAAqB;KAC1C,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC;QAC1B,MAAM;QACN,OAAO;QACP,KAAK,EAAE,SAAS;QAChB,WAAW,EAAE,cAAc;QAC3B,kBAAkB,EAAE,qBAAqB;KAC1C,CAAC,CAAC;IACH,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,4BAA4B,EAC5B,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AA6BvE,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAqB,EAAE;IAEvB,IAAI,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACzB,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC3B,0EAA0E;IAC1E,0EAA0E;IAC1E,6EAA6E;IAC7E,4EAA4E;IAC5E,4EAA4E;IAC5E,4CAA4C;IAC5C,MAAM,eAAe,GAAG,mBAAmB,EAAE,KAAK,SAAS,CAAC;IAC5D,uEAAuE;IACvE,yCAAyC;IACzC,IAAI,CAAC,eAAe;QAAE,OAAO,GAAG,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IACvE,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,eAAe,EAAE,CAAC;QAC9D,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IACtC,CAAC;IACD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,CAAC,GAAG,MAAM,aAAa,EAAE,CAAC;QAChC,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC;QACnB,OAAO,GAAG,OAAO,IAAI,CAAC,CAAC,QAAQ,CAAC;IAClC,CAAC;IACD,IAAI,CAAC,OAAO;QAAE,OAAO,GAAG,gBAAgB,CAAC;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC;IAC7B,yEAAyE;IACzE,2EAA2E;IAC3E,0EAA0E;IAC1E,wEAAwE;IACxE,uEAAuE;IACvE,4CAA4C;IAC5C,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,4BAA4B,EAAE,CAAC;IAC7E,MAAM,GAAG,GAAG,IAAI,MAAM,CAAC;QACrB,MAAM;QACN,OAAO;QACP,KAAK,EAAE,SAAS;QAChB,WAAW,EAAE,cAAc;QAC3B,kBAAkB,EAAE,qBAAqB;QACzC,cAAc;KACf,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC;QAC1B,MAAM;QACN,OAAO;QACP,KAAK,EAAE,SAAS;QAChB,WAAW,EAAE,cAAc;QAC3B,kBAAkB,EAAE,qBAAqB;QACzC,cAAc;KACf,CAAC,CAAC;IACH,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,CAAC;AAC1E,CAAC"}

package/dist/docs/cli-reference.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function renderCliReference(program: Command): string;

package/dist/docs/cli-reference.js

@@ -0,0 +1,191 @@
+// 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 { 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) {
+    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) {
+    const groups = new Map();
+    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, commands) {
+    const rows = commands.flatMap((cmd) => flatten(cmd)).map(renderRow);
+    return [
+        `## ${heading}`,
+        "",
+        "| Command | Arguments | Options | Description |",
+        "| --- | --- | --- | --- |",
+        ...rows,
+        "",
+    ].join("\n");
+}
+function flatten(cmd) {
+    return [cmd, ...visibleSubcommands(cmd).flatMap(flatten)];
+}
+function renderRow(cmd) {
+    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) {
+    const names = [];
+    let cursor = 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) {
+    return cmd.registeredArguments
+        .map((arg) => {
+        const name = `${arg.name()}${arg.variadic ? "..." : ""}`;
+        return arg.required ? `<${name}>` : `[${name}]`;
+    })
+        .join(" ");
+}
+function optionList(cmd) {
+    const flags = cmd.options
+        .filter((option) => !option.hidden && !GLOBAL_FLAGS.has(option.long ?? ""))
+        .map((option) => code(option.flags));
+    return flags.length > 0 ? flags.join(", ") : escapePipes("Global flags only");
+}
+function code(text) {
+    return text ? `\`${escapePipes(text)}\`` : "";
+}
+function prose(text) {
+    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) {
+    return text.replace(/\|/g, "\\|");
+}
+//# sourceMappingURL=cli-reference.js.map

package/dist/docs/cli-reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-reference.js","sourceRoot":"","sources":["../../src/docs/cli-reference.ts"],"names":[],"mappings":"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"}

package/dist/exit-codes.d.ts

@@ -0,0 +1,25 @@
+export declare const EXIT_SUCCESS = 0;
+export declare const EXIT_GENERAL = 1;
+export declare const EXIT_USAGE = 2;
+export declare const EXIT_NOT_AUTHENTICATED = 3;
+export declare const EXIT_FORBIDDEN = 4;
+export declare const EXIT_NOT_FOUND = 5;
+export declare const EXIT_VALIDATION = 6;
+export declare const EXIT_NETWORK = 7;
+export declare class CliUsageError extends Error {
+    constructor(message: string);
+}
+export declare class CliApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+export declare class CliNetworkError extends Error {
+    readonly url: string;
+    constructor(message: string, url: string);
+}
+export declare function isCommanderError(err: unknown): boolean;
+export declare function exitCodeForError(err: unknown): number;
+export declare function isInvalidIdempotencyKeyError(err: unknown): boolean;
+export declare function isNotAuthenticatedError(err: unknown): boolean;
+export declare function exitCodeForStatus(status: number): number;