@dharta/cli 0.6.77 → 0.6.78

package/src/commands/organization.ts

@@ -0,0 +1,153 @@
+// Organization-wide model settings (RFC 0070). These are the defaults every
+// agent inherits until it overrides them with `dharta agent model`.
+
+import type { CliContext } from "../context.js";
+import {
+  MODEL_SETTINGS_ENDPOINT_KINDS,
+  type ModelSettingsEndpointKind,
+  type OrganizationModelSettings,
+  type OrganizationModelSettingsUpdateParams,
+} from "@dharta/sdk";
+import { closestChoice, normalizeHttpUrl, normalizeNonBlank } from "../validators.js";
+import {
+  type ModelParameterOptions,
+  PLATFORM_CONNECTOR_SLUG,
+  formatModelParameters,
+  modelParameterOptionPresent,
+  modelParameterPatch,
+  normalizeModelParameterOptions,
+  normalizeModelReference,
+  parseConnectorOrder,
+  validateModelParameterOptions,
+} from "../model-settings.js";
+import { CliUsageError } from "../exit-codes.js";
+
+export interface OrgModelSetOptions extends ModelParameterOptions {
+  connector?: string;
+  modelRef?: string;
+  endpointUrl?: string;
+  endpointKind?: string;
+}
+
+export const ORG_ENDPOINT_KINDS = MODEL_SETTINGS_ENDPOINT_KINDS;
+
+export async function orgModelShowData(ctx: CliContext): Promise<OrganizationModelSettings> {
+  // Through the SDK resource, not a hand-built request (RFC 0048 D2).
+  return ctx.sdk.organization.modelSettings.get();
+}
+
+export async function orgModelShow(ctx: CliContext): Promise<string> {
+  return formatOrganizationModelSettings(await orgModelShowData(ctx));
+}
+
+export async function orgModelSetData(
+  ctx: CliContext,
+  opts: OrgModelSetOptions,
+): Promise<OrganizationModelSettings> {
+  const normalized = validateOrgModelSetOptions(opts);
+  const body: OrganizationModelSettingsUpdateParams = {};
+  if (normalized.connector !== undefined) {
+    body.connector_order = parseConnectorOrder(normalized.connector, "--connector");
+  }
+  if (normalized.modelRef !== undefined) {
+    body.model_reference = normalizeModelReference(normalized.modelRef, "--model-ref");
+  }
+  // An empty --endpoint-url clears the override, the same way the console's
+  // custom-endpoint form clears it. The kind is switched, never cleared: the
+  // column is NOT NULL, and clearing an override means clearing the URL.
+  if (normalized.endpointUrl !== undefined) {
+    body.provider_endpoint_url = normalized.endpointUrl === ""
+      ? ""
+      : normalizeEndpointUrl(normalized.endpointUrl);
+  }
+  if (normalized.endpointKind !== undefined) {
+    body.provider_endpoint_kind = normalizeEndpointKind(normalized.endpointKind);
+  }
+  const modelParameters = modelParameterPatch(normalized);
+  if (Object.keys(modelParameters).length > 0) body.model_parameters = modelParameters;
+  return ctx.sdk.organization.modelSettings.update(body);
+}
+
+export async function orgModelSet(ctx: CliContext, opts: OrgModelSetOptions): Promise<string> {
+  return formatOrganizationModelSettings(await orgModelSetData(ctx, opts));
+}
+
+export function validateOrgModelSetOptions(opts: OrgModelSetOptions): OrgModelSetOptions {
+  const normalized: OrgModelSetOptions = {
+    ...normalizeModelParameterOptions(opts),
+    // `--connector ""` and `--model-ref ""` are meaningful: an empty
+    // connector order falls back to the platform connector, and an empty
+    // model reference falls back to the connector default.
+    connector: opts.connector?.trim(),
+    modelRef: opts.modelRef?.trim(),
+    // `--endpoint-url ""` is meaningful too: it clears the override.
+    endpointUrl: opts.endpointUrl?.trim(),
+    endpointKind: opts.endpointKind?.trim(),
+  };
+  if (
+    normalized.connector === undefined &&
+    normalized.modelRef === undefined &&
+    normalized.endpointUrl === undefined &&
+    normalized.endpointKind === undefined &&
+    !modelParameterOptionPresent(normalized)
+  ) {
+    throw new CliUsageError(
+      "Pass at least one connector option, model reference option, endpoint option, or parameter option.",
+    );
+  }
+  if (normalized.connector !== undefined) parseConnectorOrder(normalized.connector, "--connector");
+  if (normalized.modelRef !== undefined) normalizeModelReference(normalized.modelRef, "--model-ref");
+  if (normalized.endpointUrl) normalizeEndpointUrl(normalized.endpointUrl);
+  if (normalized.endpointKind !== undefined) normalizeEndpointKind(normalized.endpointKind);
+  validateModelParameterOptions(normalized);
+  return normalized;
+}
+
+export function formatOrganizationModelSettings(settings: OrganizationModelSettings): string {
+  const order = settings.connector_order ?? [];
+  const parameters = formatModelParameters(settings.model_parameters);
+  return [
+    `Connector order: ${order.length > 0
+      ? order.join(", ")
+      : `unset (resolves to ${PLATFORM_CONNECTOR_SLUG}, the platform connector)`}`,
+    `Model reference: ${settings.model_reference || "unset (the connector default model is used)"}`,
+    `Model parameters: ${parameters || "none"}`,
+    `Custom endpoint: ${settings.provider_endpoint_url
+      ? `${settings.provider_endpoint_url} (${settings.provider_endpoint_kind})`
+      : "none (each connector calls its provider's standard API)"}`,
+    `Resolved model: ${formatResolved(settings)}`,
+  ].join("\n");
+}
+
+function normalizeEndpointUrl(value: string): string {
+  const normalized = normalizeHttpUrl(value, "--endpoint-url");
+  if (new URL(normalized).protocol !== "https:") {
+    throw new CliUsageError("--endpoint-url must use https. Pass an empty string to clear the override.");
+  }
+  return normalized;
+}
+
+function normalizeEndpointKind(value: string): ModelSettingsEndpointKind {
+  const normalized = normalizeNonBlank(value, "--endpoint-kind");
+  if ((ORG_ENDPOINT_KINDS as readonly string[]).includes(normalized)) {
+    return normalized as ModelSettingsEndpointKind;
+  }
+  const suggestion = closestChoice(normalized, ORG_ENDPOINT_KINDS);
+  throw new CliUsageError(
+    `Unknown --endpoint-kind ${normalized}. Allowed kinds: ${ORG_ENDPOINT_KINDS.join(", ")}.` +
+      (suggestion ? ` Did you mean ${suggestion}?` : ""),
+  );
+}
+
+// The SDK types `resolved` as a discriminated union, but this parses a server
+// response, so the field guards below stay: a partial payload prints what it
+// can rather than the string "undefined".
+function formatResolved(settings: OrganizationModelSettings): string {
+  const resolved = settings.resolved;
+  if (!resolved) return "unavailable";
+  if (resolved.error) return `unavailable (${resolved.error})`;
+  const model = resolved.model_id ?? "provider default";
+  const provider = resolved.provider ? `${resolved.provider}/` : "";
+  const connector = resolved.connector ? ` through connector ${resolved.connector}` : "";
+  return `${provider}${model}${connector}`;
+}

package/src/commands/parity.ts

@@ -6,7 +6,6 @@
 // parity of code + config, not infrastructure.
 
 import { promises as fs } from "node:fs";
-import { randomUUID } from "node:crypto";
 import * as os from "node:os";
 import * as path from "node:path";
 import { spawn } from "node:child_process";
@@ -36,7 +35,7 @@ export async function prepareReleaseDir(
   }
   const bytes = Buffer.from(await res.arrayBuffer());
 
-  const dir = await fs.mkdtemp(path.join(os.tmpdir(), `karta-${slug}-v${meta.version}-`));
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), `dharta-${slug}-v${meta.version}-`));
   const tarball = path.join(dir, "release.tar.gz");
   await fs.writeFile(tarball, bytes);
   await untar(tarball, dir);
@@ -57,7 +56,6 @@ export async function fetchRemoteEnv(
   }>({
     method: "POST",
     path: `/api/agents/${encodeURIComponent(slug)}/env/pull`,
-    headers: { "Idempotency-Key": randomUUID() },
     body: { include_secrets: !!opts.includeSecrets },
   });
 

package/src/commands/repos.ts

@@ -0,0 +1,23 @@
+import type { CliContext } from "../context.js";
+import type { SourceRepoDisconnectResult } from "@dharta/sdk";
+import { validateAgentSlug } from "../agent.js";
+
+export async function reposDisconnectGithubData(
+  ctx: CliContext,
+  slug: string,
+): Promise<SourceRepoDisconnectResult> {
+  // A source repo carries the same slug shape an agent does; it is provisioned
+  // from one.
+  return ctx.sdk.sourceRepos.disconnectGithub(validateAgentSlug(slug, "source repo slug"));
+}
+
+export async function reposDisconnectGithub(ctx: CliContext, slug: string): Promise<string> {
+  const res = await reposDisconnectGithubData(ctx, slug);
+  if (!res.changed) {
+    return `GitHub auto-deploy is already disconnected for ${res.source_repo.slug}.`;
+  }
+  return [
+    `Disconnected GitHub auto-deploy for ${res.github_repository}.`,
+    "Current releases remain live; per-agent Actions can deploy independently.",
+  ].join(" ");
+}

package/src/commands/rollback.ts

@@ -1,8 +1,8 @@
 // Re-deploy a previous release by pointer flip. (Forward deploys are
 // `dharta deploy` / `git push dharta`; this is the rollback-only path.)
 import type { CliContext } from "../context.js";
-import { randomUUID } from "node:crypto";
 import { validateAgentSlug } from "../agent.js";
+import { CliUsageError } from "../exit-codes.js";
 
 export interface RollbackResponse {
   agent: { id: string; slug: string; name: string };
@@ -20,7 +20,6 @@ export async function rollbackData(
   return ctx.http.request<RollbackResponse>({
     method: "POST",
     path: `/api/agents/${encodeURIComponent(normalizedSlug)}/rollback`,
-    headers: { "Idempotency-Key": randomUUID() },
     body: { to_version: normalizedVersion },
   });
 }
@@ -39,7 +38,7 @@ export async function rollback(
 
 function normalizeRollbackVersion(toVersion: number): number {
   if (!Number.isSafeInteger(toVersion) || toVersion <= 0) {
-    throw new Error("version must be a positive whole number.");
+    throw new CliUsageError("version must be a positive whole number.");
   }
   return toVersion;
 }

package/src/commands/schedules.ts

@@ -1,9 +1,10 @@
-import { randomUUID } from "node:crypto";
 import { inferAgentSlug, type AgentInferOptions } from "../agent.js";
+import { mintIdempotencyKey } from "../config.js";
 import type { CliContext } from "../context.js";
 import { parseDollarAmountToCents } from "../money.js";
 import { fmtTs, table } from "../output.js";
 import { normalizeNonBlank, normalizeTimezone, parsePositiveInteger, parseReleaseVersion } from "../validators.js";
+import { CliUsageError } from "../exit-codes.js";
 
 export interface Schedule {
   id: number;
@@ -76,20 +77,26 @@ export async function schedulesCreateData(
     initial_message: normalizeRequired(message, "--message"),
   };
   if (opts.budget !== undefined && opts.budgetCents !== undefined) {
-    throw new Error("Use either --budget or --budget-cents, not both.");
+    throw new CliUsageError("Use either --budget or --budget-cents, not both.");
   }
   if (opts.budget !== undefined) body.budget_cents = parseDollarAmountToCents(opts.budget, "--budget");
   if (opts.budgetCents !== undefined) body.budget_cents = parsePositiveWholeNumber(opts.budgetCents, "--budget-cents");
   if (opts.releaseVersion !== undefined) body.release_version = parseReleaseVersion(opts.releaseVersion, "--release-version");
   if (opts.endUserId !== undefined) body.end_user_id = normalizeRequired(opts.endUserId, "--end-user-id");
+  // `--run-now` makes this command write twice. Both writes derive a key from
+  // the caller's `--idempotency-key` rather than presenting it as given: the
+  // server binds a key to the request it first saw, so one key on both would
+  // answer the run with a 422 and leave a schedule behind that the failure
+  // message never mentions. Both derive whether or not `--run-now` was passed,
+  // so the key a write carries does not depend on a flag.
   const res = await ctx.http.request<ScheduleEnvelope>({
     method: "POST",
     path: `/api/agents/${encodeURIComponent(slug)}/schedules`,
-    headers: idempotencyHeader(),
+    idempotencyKey: mintIdempotencyKey("schedules.create"),
     body: { schedule: body },
   });
   if (opts.runNow) {
-    const run = await runScheduleNow(ctx, slug, String(res.schedule.id));
+    const run = await runScheduleNow(ctx, slug, String(res.schedule.id), mintIdempotencyKey("schedules.run"));
     return { slug, ...res, queued: run.queued ?? true };
   }
   return { slug, ...res };
@@ -106,7 +113,7 @@ export function validateSchedulesCreateInput(opts: ScheduleCreateOptions): void
     opts.message === undefined ? "--message <text>" : null,
   ].filter((flag): flag is string => flag !== null);
   if (missing.length > 0) {
-    throw new Error(
+    throw new CliUsageError(
       `Pass ${formatMissingFlags(missing)}. ` +
         "Usage: dharta schedules create --cron '0 9 * * *' --message 'Daily check-in'",
     );
@@ -117,7 +124,7 @@ export function validateSchedulesCreateInput(opts: ScheduleCreateOptions): void
   if (opts.timezone !== undefined) normalizeTimezone(opts.timezone, "--timezone");
   normalizeRequired(message, "--message");
   if (opts.budget !== undefined && opts.budgetCents !== undefined) {
-    throw new Error("Use either --budget or --budget-cents, not both.");
+    throw new CliUsageError("Use either --budget or --budget-cents, not both.");
   }
   if (opts.budget !== undefined) parseDollarAmountToCents(opts.budget, "--budget");
   if (opts.budgetCents !== undefined) parsePositiveWholeNumber(opts.budgetCents, "--budget-cents");
@@ -133,7 +140,7 @@ function validateCron(value: string): void {
   const cron = normalizeRequired(value, "--cron");
   const fields = cron.split(/\s+/);
   if (fields.length !== 5 || fields.some((field) => field.length === 0)) {
-    throw new Error("--cron must be a standard 5-field cron expression, e.g. '0 9 * * *'.");
+    throw new CliUsageError("--cron must be a standard 5-field cron expression, e.g. '0 9 * * *'.");
   }
   fields.forEach((field, index) => validateCronField(field, CRON_FIELD_SPECS[index]));
 }
@@ -164,7 +171,7 @@ function validateCronField(field: string, spec: CronFieldSpec): void {
     const [base, step, extra] = item.split("/");
     if (extra !== undefined || !base) throw unsupportedCronField(spec);
     if (step !== undefined && !/^[1-9]\d*$/.test(step)) {
-      throw new Error(`--cron ${spec.name} field step must be a positive whole number.`);
+      throw new CliUsageError(`--cron ${spec.name} field step must be a positive whole number.`);
     }
     if (base === "*") continue;
 
@@ -178,7 +185,7 @@ function validateCronField(field: string, spec: CronFieldSpec): void {
     const rangeStart = parseCronToken(start, spec);
     const rangeEnd = parseCronToken(end, spec);
     if (rangeStart > rangeEnd) {
-      throw new Error(`--cron ${spec.name} field range must start before it ends.`);
+      throw new CliUsageError(`--cron ${spec.name} field range must start before it ends.`);
     }
   }
 }
@@ -190,13 +197,15 @@ function parseCronToken(token: string, spec: CronFieldSpec): number {
   if (!/^\d+$/.test(token)) throw unsupportedCronField(spec);
   const parsed = Number(token);
   if (parsed < spec.min || parsed > spec.max) {
-    throw new Error(`--cron ${spec.name} field must be ${spec.min}-${spec.max}.`);
+    throw new CliUsageError(`--cron ${spec.name} field must be ${spec.min}-${spec.max}.`);
   }
   return parsed;
 }
 
 function unsupportedCronField(spec: CronFieldSpec): Error {
-  return new Error(`--cron ${spec.name} field is not supported. Use numbers, *, ranges, lists, and steps.`);
+  return new CliUsageError(
+    `--cron ${spec.name} field is not supported. Use numbers, *, ranges, lists, and steps.`,
+  );
 }
 
 export async function schedulesActionData(
@@ -212,7 +221,6 @@ export async function schedulesActionData(
     : await ctx.http.request<ScheduleEnvelope>({
       method: "POST",
       path: `/api/agents/${encodeURIComponent(slug)}/schedules/${encodeURIComponent(normalizedId)}/${action}`,
-      headers: idempotencyHeader(),
     });
   return { slug, ...res };
 }
@@ -238,7 +246,6 @@ export async function schedulesDeleteData(
   await ctx.http.request<void>({
     method: "DELETE",
     path: `/api/agents/${encodeURIComponent(slug)}/schedules/${encodeURIComponent(normalizedId)}`,
-    headers: idempotencyHeader(),
   });
   return { slug, id: normalizedId, deleted: true };
 }
@@ -250,10 +257,10 @@ export async function schedulesDelete(ctx: CliContext, id: string, opts: AgentIn
 
 function parsePositiveWholeNumber(value: string, flag: string): number {
   const normalized = value.trim();
-  if (!/^\d+$/.test(normalized)) throw new Error(`${flag} must be a whole number.`);
+  if (!/^\d+$/.test(normalized)) throw new CliUsageError(`${flag} must be a whole number.`);
   const parsed = Number(normalized);
   if (!Number.isSafeInteger(parsed) || parsed <= 0) {
-    throw new Error(`${flag} must be a positive whole number.`);
+    throw new CliUsageError(`${flag} must be a positive whole number.`);
   }
   return parsed;
 }
@@ -263,22 +270,26 @@ function formatBudget(cents: number | null): string {
   return `$${(cents / 100).toFixed(2)}`;
 }
 
-function idempotencyHeader(): Record<string, string> {
-  return { "Idempotency-Key": randomUUID() };
-}
-
-function runScheduleNow(ctx: CliContext, slug: string, id: string): Promise<ScheduleEnvelope> {
+// `idempotencyKey` is set only by the caller that writes more than once.
+// `dharta schedules run` writes once, so it leaves this undefined and the
+// client sends the caller's key exactly as given.
+function runScheduleNow(
+  ctx: CliContext,
+  slug: string,
+  id: string,
+  idempotencyKey?: string,
+): Promise<ScheduleEnvelope> {
   return ctx.http.request<ScheduleEnvelope>({
     method: "POST",
     path: `/api/agents/${encodeURIComponent(slug)}/schedules/${encodeURIComponent(id)}/run`,
-    headers: idempotencyHeader(),
+    idempotencyKey,
   });
 }
 
 function normalizeRequired(value: string, flag: string): string {
   const normalized = value.trim();
   if (!normalized) {
-    throw new Error(`${flag} cannot be blank.`);
+    throw new CliUsageError(`${flag} cannot be blank.`);
   }
   return normalized;
 }

package/src/commands/scopes.ts

@@ -4,12 +4,19 @@ export const SENSITIVE_API_KEY_SCOPES = new Set([
   "workspace_tokens:create",
   "workspace:read",
   "audit_log:export",
+  "fleet:subjects:read",
+  "fleet:subjects:write",
+  "fleet:operations:write",
   "members:invite",
   "members:write",
   "members:owner_role:write",
   "agents:delete",
   "keys:write",
-  "model_keys:write",
+  "model_connections:write",
+  "organization:support_access:write",
+  // A webhook destination is an egress trust root: any URL is accepted, and an
+  // endpoint with no event list receives every event type.
+  "webhooks:write",
 ]);
 
 export function formatScopes(scopes: readonly string[], separator = ", "): string {

package/src/commands/sessions.ts

@@ -6,13 +6,13 @@
 // org's transcript-access setting.
 
 import { HttpClient } from "@dharta/sdk";
-import { randomUUID } from "node:crypto";
 import type { CliContext } from "../context.js";
 import { cliFormatError, cliFormatNetworkError } from "../api-error.js";
 import { inferAgentSlug, type AgentInferOptions } from "../agent.js";
 import { runTurn, type TurnIo } from "./dev.js";
 import { table } from "../output.js";
 import { normalizeNonBlank, parsePositiveInteger } from "../validators.js";
+import { mintIdempotencyKey } from "../config.js";
 
 export interface SessionsOptions extends AgentInferOptions {
   fetchImpl?: typeof fetch;
@@ -50,12 +50,16 @@ async function agentApi(
   return {
     slug,
     agentUrl: shown.agent_url,
+    // The run-wide key rides along here exactly as it does on the control-plane
+    // client. It fills in for a write that names no key of its own; `send`
+    // names one per write, so both of its mutations keep theirs.
     http: new HttpClient({
       apiKey: ctx.apiKey,
       baseUrl: shown.agent_url,
       fetch: opts.fetchImpl,
       formatError: cliFormatError,
       formatNetworkError: cliFormatNetworkError,
+      idempotencyKey: ctx.idempotencyKey,
     }),
   };
 }
@@ -189,7 +193,7 @@ export async function run(
       method: "POST",
       path: "/v1/sessions",
       body: { metadata: { source: "dharta-run" } },
-      headers: { "Idempotency-Key": randomUUID() },
+      idempotencyKey: mintIdempotencyKey("sessions.create"),
     });
     sessionId = session.id;
   }
@@ -212,7 +216,9 @@ export async function run(
       return "n";
     },
   };
-  await runTurn(agentUrl, authedFetch, sessionId, normalizedMessage, io);
+  await runTurn(agentUrl, authedFetch, sessionId, normalizedMessage, io, {
+    operation: "sessions.turn",
+  });
   // The renderer appends one trailing newline to close the streamed line;
   // drop it from the returned/JSON payload so the reply is exactly the text.
   const replyText = reply.endsWith("\n") ? reply.slice(0, -1) : reply;

package/src/commands/setup.ts

@@ -7,6 +7,7 @@ import { deriveSlug, validateAgentName } from "../agent.js";
 import { defaultGitRunner, rejectOverlappingAgentRoots, type GitRunner } from "./deploy.js";
 import { closestChoice, normalizeNonBlank } from "../validators.js";
 import { DEFAULT_CREATE_HARNESS, hasAgentMarker } from "../harnesses.js";
+import { CliUsageError } from "../exit-codes.js";
 
 // `dharta setup [path]` (RFC 0024 DEP-4): the one front door. It scans the
 // repo for agent folders, lets you pick one, and writes its (self-
@@ -65,7 +66,7 @@ export async function setup(pathArg: string | undefined, opts: SetupOptions = {}
   const parsedMethod = parseMethod(opts.method); // validate configuration up front
   const forcedMethod = parsedMethod.method;
   const ci = parseCi(opts.ci) ?? parsedMethod.ci;
-  if (opts.enable && opts.disable) throw new Error("Use either --enable or --disable, not both.");
+  if (opts.enable && opts.disable) throw new CliUsageError("Use either --enable or --disable, not both.");
   if (opts.name !== undefined) validateAgentName(opts.name, "--name");
   // Resolve and validate an explicit target before setup can initialize git or
   // write anything. Besides avoiding a stray .git on typos, this establishes a
@@ -380,7 +381,7 @@ function parseMethod(raw: string | undefined): ParsedMethodInput {
   }
   if (!METHODS.includes(normalized as Method)) {
     const suggestion = closestChoice(normalized, METHOD_INPUTS);
-    throw new Error(
+    throw new CliUsageError(
       `Unknown --method '${normalized}'. Use git or folder.` +
         (suggestion ? ` Did you mean ${suggestion}?` : ""),
     );
@@ -393,7 +394,7 @@ function parseCi(raw: string | undefined): CiProvider | undefined {
   const normalized = normalizeNonBlank(raw, "--ci");
   if (!CI_PROVIDERS.includes(normalized as CiProvider)) {
     const suggestion = closestChoice(normalized, CI_PROVIDERS);
-    throw new Error(
+    throw new CliUsageError(
       `Unknown --ci '${normalized}'. Use github.` +
         (suggestion ? ` Did you mean ${suggestion}?` : ""),
     );
@@ -939,7 +940,7 @@ async function safeAtomicWriteFile(
   const parent = path.dirname(destination);
   const temporary = path.join(
     parent,
-    `.${path.basename(destination)}.karta-${process.pid}-${randomBytes(12).toString("hex")}.tmp`,
+    `.${path.basename(destination)}.dharta-${process.pid}-${randomBytes(12).toString("hex")}.tmp`,
   );
   const noFollow = constants.O_NOFOLLOW ?? 0;
   const flags = constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | noFollow;

package/src/commands/update.ts

@@ -16,6 +16,11 @@ import { checkNpmLatestVersion } from "../version-check.js";
 export const DOWNLOAD_BASE =
   process.env.DHARTA_CLI_DOWNLOAD_BASE ?? "https://cli.dharta.ai";
 
+// The marker packaging/build-standalone.sh writes into the tarball root. The
+// build derives it from package.json's `bin`; this is the one place the CLI
+// side states it, and packaging-parity.test.ts pins the two together.
+export const STANDALONE_MARKER = ".dharta-standalone";
+
 export interface UpdateOptions {
   installRoot?: string; // test seam (default: the package root)
   currentVersion?: string;
@@ -34,7 +39,7 @@ export function packageRoot(): string {
 
 export async function installChannel(root: string): Promise<"standalone" | "npm"> {
   try {
-    await fs.access(path.join(root, ".dharta-standalone"));
+    await fs.access(path.join(root, STANDALONE_MARKER));
     return "standalone";
   } catch {
     return "npm";
@@ -42,7 +47,7 @@ export async function installChannel(root: string): Promise<"standalone" | "npm"
 }
 
 export function tarballName(platform: string, arch: string): string {
-  return `karta-${platform}-${arch}.tar.gz`;
+  return `dharta-${platform}-${arch}.tar.gz`;
 }
 
 export async function update(opts: UpdateOptions = {}): Promise<string> {
@@ -56,7 +61,7 @@ export async function update(opts: UpdateOptions = {}): Promise<string> {
       fetchImpl: opts.fetchImpl,
       latestUrl: opts.latestUrl,
     });
-    if (version.status === "current") return `karta is already current (${version.current}).`;
+    if (version.status === "current") return `dharta is already current (${version.current}).`;
     if (version.status === "ahead") {
       return `dharta ${version.current} is newer than the latest published npm version (${version.latest}).`;
     }
@@ -65,7 +70,7 @@ export async function update(opts: UpdateOptions = {}): Promise<string> {
         ? `\nInstalled: ${version.current}\nLatest:    ${version.latest}`
         : `\nCould not check the latest npm version (${version.reason}).`;
     return (
-      "This karta was installed via npm - update it with:\n" +
+      "This dharta was installed via npm - update it with:\n" +
       "    npm install -g @dharta/cli@latest" +
       suffix
     );
@@ -106,18 +111,29 @@ export async function update(opts: UpdateOptions = {}): Promise<string> {
 
   const staging = await fs.mkdtemp(path.join(os.tmpdir(), "dharta-update-"));
   const tarball = path.join(staging, "update.tar.gz");
+  const unpacked = path.join(staging, "unpacked");
+  await fs.mkdir(unpacked);
   await fs.writeFile(tarball, bytes);
-  await untar(tarball, staging);
-
-  // The tarball contains a single karta/ directory; its contents
-  // replace the install root. Extract fully BEFORE touching the live
-  // install so a failed download never leaves a half-updated CLI.
-  const extracted = path.join(staging, "dharta");
-  await fs.access(path.join(extracted, ".dharta-standalone"));
+  await untar(tarball, unpacked);
+
+  // The tarball holds exactly one directory, named for the command it installs.
+  // Read that name off the payload rather than assuming it: assuming it is what
+  // broke this path through the rename, when the build started writing a
+  // directory this code was not looking for. Extract fully BEFORE touching the
+  // live install so a failed download never leaves a half-updated CLI.
+  const [entry, ...extra] = await fs.readdir(unpacked);
+  if (!entry || extra.length > 0) {
+    throw new Error(
+      "The downloaded update did not contain a single CLI directory. " +
+        "Nothing was changed; retry, or reinstall with the install script.",
+    );
+  }
+  const extracted = path.join(unpacked, entry);
+  await fs.access(path.join(extracted, STANDALONE_MARKER));
 
   await replaceContents(extracted, root);
   await fs.rm(staging, { recursive: true, force: true });
-  return "Updated. Run `karta --version` to confirm.";
+  return "Updated. Run `dharta --version` to confirm.";
 }
 
 async function fetchUpdate(url: string, fetchImpl: typeof fetch): Promise<Response> {