@dharta/cli 0.6.77 → 0.6.78

package/src/commands/webhooks.ts

@@ -1,11 +1,14 @@
-import { randomUUID } from "node:crypto";
 import type { CliContext } from "../context.js";
-import { WEBHOOK_EVENT_TYPES } from "@dharta/sdk";
+import { WEBHOOK_EVENT_TYPES, type WebhookDelivery } from "@dharta/sdk";
 import { fmtTs, table } from "../output.js";
 import { closestChoice, normalizeNonBlank } from "../validators.js";
+import { CliUsageError } from "../exit-codes.js";
 
+// The shape `Api::WebhookEndpointsController#serialize` returns. `id` is the
+// integer primary key; it read `string` here, in the SDK types and in the
+// OpenAPI document, and the controller has always emitted a number.
 export interface WebhookEndpoint {
-  id: string;
+  id: number;
   name: string;
   url: string;
   event_types: string[];
@@ -38,7 +41,7 @@ export async function webhooksList(ctx: CliContext): Promise<string> {
   const data = await webhooksListData(ctx);
   if (data.length === 0) return "No webhook endpoints. Create one with: dharta webhooks create <name> <url>";
   return table(data.map((endpoint) => ({
-    id: endpoint.id,
+    id: String(endpoint.id),
     name: endpoint.name,
     url: endpoint.url,
     state: endpoint.enabled ? "enabled" : "disabled",
@@ -59,7 +62,6 @@ export async function webhooksCreateData(
   return ctx.http.request<EndpointEnvelope>({
     method: "POST",
     path: "/api/webhook_endpoints",
-    headers: idempotencyHeader(),
     body: { name: normalizedName, url: normalizedUrl, event_types: parseEvents(opts.event) },
   });
 }
@@ -85,12 +87,11 @@ export async function webhooksUpdateData(
   if (opts.url !== undefined) body.url = normalizeWebhookUrl(opts.url);
   if (opts.event !== undefined) body.event_types = parseEvents(opts.event);
   if (Object.keys(body).length === 0) {
-    throw new Error("Pass at least one update option: --name, --url, or --event.");
+    throw new CliUsageError("Pass at least one update option: --name, --url, or --event.");
   }
   return ctx.http.request<EndpointEnvelope>({
     method: "PATCH",
     path: `/api/webhook_endpoints/${encodeURIComponent(normalizedId)}`,
-    headers: idempotencyHeader(),
     body,
   });
 }
@@ -115,7 +116,7 @@ export function validateWebhooksUpdateInput(id: string, opts: { name?: string; u
   if (hasUrl) normalizeWebhookUrl(opts.url!);
   if (hasEvent) parseEvents(opts.event);
   if (!hasName && !hasUrl && !hasEvent) {
-    throw new Error("Pass at least one update option: --name, --url, or --event.");
+    throw new CliUsageError("Pass at least one update option: --name, --url, or --event.");
   }
 }
 
@@ -124,7 +125,6 @@ export async function webhooksEnableData(ctx: CliContext, id: string): Promise<E
   return ctx.http.request<EndpointEnvelope>({
     method: "POST",
     path: `/api/webhook_endpoints/${encodeURIComponent(normalizedId)}/enable`,
-    headers: idempotencyHeader(),
   });
 }
 
@@ -133,12 +133,27 @@ export async function webhooksEnable(ctx: CliContext, id: string): Promise<strin
   return `Enabled webhook endpoint ${res.webhook_endpoint.id}.`;
 }
 
+// Queues one probe through the production delivery path: the same delivery
+// row, the same signature, the same retry schedule. The answer is the QUEUED
+// delivery, not its outcome - read that from `dharta webhooks list` and the
+// deliveries the endpoint records.
+export async function webhooksTestData(ctx: CliContext, id: string): Promise<WebhookDelivery> {
+  return ctx.sdk.webhookEndpoints.test(normalizeWebhookId(id));
+}
+
+export async function webhooksTest(ctx: CliContext, id: string): Promise<string> {
+  const delivery = await webhooksTestData(ctx, id);
+  return (
+    `Queued ${delivery.event_type} delivery ${delivery.id} (event ${delivery.event_id}) ` +
+    "to the endpoint. Its outcome lands on the delivery record, not here."
+  );
+}
+
 export async function webhooksDeleteData(ctx: CliContext, id: string): Promise<{ id: string; deleted: boolean }> {
   const normalizedId = normalizeWebhookId(id);
   await ctx.http.request<void>({
     method: "DELETE",
     path: `/api/webhook_endpoints/${encodeURIComponent(normalizedId)}`,
-    headers: idempotencyHeader(),
   });
   return { id: normalizedId, deleted: true };
 }
@@ -155,13 +170,13 @@ export function parseEvents(input: string[] | undefined): string[] {
     .map((value) => value.trim())
     .filter(Boolean);
   if (events.length === 0) {
-    throw new Error("--event must include at least one event type, e.g. --event turn.completed.");
+    throw new CliUsageError("--event must include at least one event type, e.g. --event turn.completed.");
   }
   const allowed = new Set<string>(WEBHOOK_EVENT_TYPES);
   const unknown = events.filter((event) => !allowed.has(event));
   if (unknown.length > 0) {
     const suggestion = unknown.length === 1 ? closestChoice(unknown[0]!, WEBHOOK_EVENT_TYPES) : null;
-    throw new Error(
+    throw new CliUsageError(
       `Unknown --event ${unknown.join(", ")}. Allowed events: ${WEBHOOK_EVENT_TYPES.join(", ")}.` +
         (suggestion ? ` Did you mean ${suggestion}?` : ""),
     );
@@ -169,14 +184,10 @@ export function parseEvents(input: string[] | undefined): string[] {
   return events;
 }
 
-function idempotencyHeader(): Record<string, string> {
-  return { "Idempotency-Key": randomUUID() };
-}
-
 function normalizeRequired(value: string, label: string): string {
   const normalized = value.trim();
   if (!normalized) {
-    throw new Error(`${label} cannot be blank.`);
+    throw new CliUsageError(`${label} cannot be blank.`);
   }
   return normalized;
 }
@@ -187,10 +198,10 @@ function normalizeWebhookUrl(value: string): string {
   try {
     parsed = new URL(normalized);
   } catch {
-    throw new Error("Webhook URL must be an absolute http(s) URL.");
+    throw new CliUsageError("Webhook URL must be an absolute http(s) URL.");
   }
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    throw new Error("Webhook URL must be an absolute http(s) URL.");
+    throw new CliUsageError("Webhook URL must be an absolute http(s) URL.");
   }
   return normalized;
 }

package/src/completions.ts

@@ -4,6 +4,7 @@
 // CLI version's command surface; regenerate after updating.
 
 import type { Argument, Command, Option } from "commander";
+import { visibleSubcommands } from "./command-tree.js";
 
 interface CommandSpec {
   name: string;
@@ -17,6 +18,12 @@ interface CommandSpec {
   subs: CommandSpec[];
 }
 
+// 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: string): string {
+  return `_${bin.replace(/[^A-Za-z0-9_]/g, "_")}`;
+}
+
 export function specFromCommand(cmd: Command): CommandSpec {
   return {
     name: cmd.name(),
@@ -27,9 +34,7 @@ export function specFromCommand(cmd: Command): CommandSpec {
       "--help",
     ],
     argChoices: cmd.registeredArguments.flatMap((a: Argument) => a.argChoices ?? []),
-    subs: cmd.commands
-      .filter((c) => !(c as unknown as { _hidden?: boolean })._hidden)
-      .map((c) => specFromCommand(c as Command)),
+    subs: visibleSubcommands(cmd).map((c) => specFromCommand(c)),
   };
 }
 
@@ -114,10 +119,15 @@ function escapeZshDescription(value: string): string {
 export function bashCompletion(program: Command): string {
   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: string[] = [
-    "# 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=""',
@@ -130,7 +140,7 @@ export function bashCompletion(program: Command): string {
     "  esac",
     '  COMPREPLY=( $(compgen -W "$words" -- "$cur") )',
     "}",
-    "complete -F _karta karta",
+    `complete -F ${fn} ${bin}`,
   );
   return lines.join("\n");
 }
@@ -138,13 +148,15 @@ export function bashCompletion(program: Command): string {
 export function zshCompletion(program: Command): string {
   const spec = specFromCommand(program);
   const entries = completionEntries(spec);
+  const bin = program.name();
+  const fn = completionFunctionName(bin);
 
   const lines: string[] = [
-    "#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",
@@ -156,13 +168,13 @@ export function zshCompletion(program: Command): string {
     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");
 }

package/src/config.ts

@@ -1,7 +1,11 @@
+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";
 
 // One host schema (RFC 0013 CLI-7, executing RFC 0011 HOST-5's CLI
 // note). D11's coordinate system has three hosts, each with one auth
@@ -37,6 +41,115 @@ export function setHomeForTesting(home: string | undefined): void {
   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: string | undefined;
+
+export function setRequestedProfile(name: string | undefined): void {
+  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: string | undefined;
+
+export function setRequestedIdempotencyKey(key: string | undefined): void {
+  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 as 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(): string | undefined {
+  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: string): string {
+  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(): string | undefined {
+  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(): string | undefined {
+  if (requestedProfile !== undefined) return requestedProfile;
+  const fromEnv = process.env.DHARTA_PROFILE?.trim();
+  return fromEnv ? fromEnv : undefined;
+}
+
 export function configPath(): string {
   const home = homeOverride ?? process.env.HOME ?? homedir();
   return path.join(home, ".dharta", "config.toml");
@@ -109,17 +222,21 @@ export async function removeProfile(name: string): Promise<boolean> {
 
 export async function activeProfile(): Promise<Profile> {
   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.",
+      `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,
@@ -129,13 +246,28 @@ export async function activeProfile(): Promise<Profile> {
   };
 }
 
+// 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: string): CliUsageError {
+  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(): Promise<string> {
-  if (process.env.DHARTA_BASE_URL) return 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/src/context.ts

@@ -1,5 +1,10 @@
 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 interface CliContext {
@@ -13,6 +18,10 @@ export interface CliContext {
   // `dharta files` can build a second HttpClient for the DATA-PLANE files host (a
   // different origin than the control-plane base_url) while staying testable.
   fetch?: typeof fetch;
+  // The run-wide `--idempotency-key`, already resolved. A command that builds a
+  // second control-plane client hands it over so the flag reaches that client's
+  // writes too; the two clients then behave identically.
+  idempotencyKey?: string;
 }
 
 // Allow tests to inject a stub fetch + base config without touching disk.
@@ -20,6 +29,9 @@ export interface CtxOverrides {
   apiKey?: string;
   baseUrl?: string;
   fetch?: typeof fetch;
+  // Normally read off the global `--idempotency-key` flag. Tests that never go
+  // through the program's preAction hook pass it here.
+  idempotencyKey?: string;
 }
 
 export async function buildContext(
@@ -27,11 +39,17 @@ export async function buildContext(
 ): Promise<CliContext> {
   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) {
@@ -41,12 +59,20 @@ export async function buildContext(
   }
   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,
@@ -54,6 +80,7 @@ export async function buildContext(
     fetch: fetchImpl,
     formatError: cliFormatError,
     formatNetworkError: cliFormatNetworkError,
+    idempotencyKey,
   });
-  return { sdk, http, baseUrl, apiKey, fetch: fetchImpl };
+  return { sdk, http, baseUrl, apiKey, fetch: fetchImpl, idempotencyKey };
 }