@dharta/cli 0.6.77

package/src/commands/status.ts

@@ -0,0 +1,94 @@
+import * as path from "node:path";
+import type { CliContext } from "../context.js";
+import { findGitRoot, scanAgentFolders } from "../setup-scan.js";
+import { deriveSlug, validateAgentSelectorOptions } from "../agent.js";
+import { table } from "../output.js";
+
+// `dharta status` (CLI surface spec): the repo-wide "what's here" view - every
+// agent declared in this repo (resolved from the git root down, like `git
+// status`) joined to its live release on the active profile. Works before the
+// first deploy (the local columns come from dharta.toml; the remote ones fill
+// in once live). Absorbs the old `deploy list`. For one agent's detail, see
+// `dharta agent show`.
+
+export interface StatusRow {
+  name: string;
+  slug: string;
+  enabled: boolean; // deploy = true locally
+  deployMethod: "git" | "folder" | null;
+  liveVersion: number | null; // null = no active release on this profile
+  url: string | null; // live hosted page
+  remoteChecked: boolean; // false when status is local-only because auth is unavailable
+  remoteUnavailableReason: string | null;
+}
+
+interface AgentRemote {
+  // GET /api/agents/:slug reports only the active release as `live_version`
+  // (null before the first successful deploy). It does not expose the newest
+  // deployment attempt, so this command deliberately describes live state.
+  live_version: number | null;
+  agent_url: string;
+}
+
+export async function statusData(
+  ctx: CliContext | null,
+  opts: { dir?: string; authMessage?: string } = {},
+): Promise<StatusRow[]> {
+  validateAgentSelectorOptions(opts);
+  const dir = path.resolve(opts.dir ?? ".");
+  const gitRoot = findGitRoot(dir);
+  const folders = await scanAgentFolders(gitRoot ?? dir, { isGitRepo: !!gitRoot });
+
+  const rows: StatusRow[] = [];
+  for (const f of folders) {
+    if (!f.name) continue; // configured agents only (a dharta.toml with a name)
+    const slug = deriveSlug(f.name);
+    let remote: AgentRemote | null = null;
+    if (ctx) {
+      try {
+        remote = await ctx.http.request<AgentRemote>({
+          path: `/api/agents/${encodeURIComponent(slug)}`,
+        });
+      } catch (err) {
+        // 404 = not deployed on the active profile (not an error); anything else
+        // (auth, network) is real and must surface.
+        if ((err as { status?: number }).status !== 404) throw err;
+      }
+    }
+    rows.push({
+      name: f.name,
+      slug,
+      enabled: f.deployEnabled,
+      deployMethod: f.deployMethod ?? null,
+      liveVersion: remote?.live_version ?? null,
+      url: remote?.agent_url ?? null,
+      remoteChecked: !!ctx,
+      remoteUnavailableReason: ctx
+        ? null
+        : opts.authMessage ?? "Run `dharta login` to check live versions and URLs.",
+    });
+  }
+  return rows;
+}
+
+export async function status(ctx: CliContext | null, opts: { dir?: string; authMessage?: string } = {}): Promise<string> {
+  const rows = await statusData(ctx, opts);
+  if (rows.length === 0) {
+    return "No agents here (no dharta.toml with a name). Create one with `dharta create`, or run `dharta setup` inside an existing agent folder.";
+  }
+  const rendered = table(
+    rows.map((r) => ({
+      agent: r.name,
+      enabled: r.enabled ? "yes" : "no",
+      method: r.deployMethod ?? "-",
+      live:
+        r.liveVersion == null
+          ? "-"
+          : `v${r.liveVersion}`,
+      url: r.url ?? "-",
+    })),
+  );
+  if (ctx) return rendered;
+  const message = opts.authMessage ?? "Run `dharta login` to check live versions and URLs.";
+  return `${rendered}\n\nRemote live release unavailable: ${message}`;
+}

package/src/commands/update.ts

@@ -0,0 +1,157 @@
+// `dharta update` (RFC 0013 CLI-11): self-update on the STANDALONE
+// channel only - npm installs are updated by npm, and the two must
+// never fight over the same files. A standalone install is identified
+// by the `.dharta-standalone` marker the tarball build writes next to
+// the package root.
+
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { checkNpmLatestVersion } from "../version-check.js";
+
+// Where the standalone tarballs live; overridable for staging/self-host.
+export const DOWNLOAD_BASE =
+  process.env.DHARTA_CLI_DOWNLOAD_BASE ?? "https://cli.dharta.ai";
+
+export interface UpdateOptions {
+  installRoot?: string; // test seam (default: the package root)
+  currentVersion?: string;
+  fetchImpl?: typeof fetch;
+  latestUrl?: string;
+  platform?: string; // test seam (default: process.platform)
+  arch?: string; // test seam (default: process.arch)
+  log?: (line: string) => void;
+}
+
+export function packageRoot(): string {
+  // src/commands/update.ts -> dist/commands/update.js; the package
+  // root is two levels up either way.
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+}
+
+export async function installChannel(root: string): Promise<"standalone" | "npm"> {
+  try {
+    await fs.access(path.join(root, ".dharta-standalone"));
+    return "standalone";
+  } catch {
+    return "npm";
+  }
+}
+
+export function tarballName(platform: string, arch: string): string {
+  return `karta-${platform}-${arch}.tar.gz`;
+}
+
+export async function update(opts: UpdateOptions = {}): Promise<string> {
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const root = opts.installRoot ?? packageRoot();
+
+  if ((await installChannel(root)) === "npm") {
+    const version = await checkNpmLatestVersion({
+      root,
+      currentVersion: opts.currentVersion,
+      fetchImpl: opts.fetchImpl,
+      latestUrl: opts.latestUrl,
+    });
+    if (version.status === "current") return `karta is already current (${version.current}).`;
+    if (version.status === "ahead") {
+      return `dharta ${version.current} is newer than the latest published npm version (${version.latest}).`;
+    }
+    const suffix =
+      version.status === "outdated"
+        ? `\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" +
+      "    npm install -g @dharta/cli@latest" +
+      suffix
+    );
+  }
+
+  const platform = opts.platform ?? process.platform;
+  const arch = opts.arch ?? process.arch;
+  const url = `${DOWNLOAD_BASE.replace(/\/+$/, "")}/latest/${tarballName(platform, arch)}`;
+  const fetchImpl = (opts.fetchImpl ?? globalThis.fetch).bind(globalThis);
+
+  log(`Downloading ${url}…`);
+  const res = await fetchUpdate(url, fetchImpl);
+  if (!res.ok) {
+    throw new Error(
+      `Could not download the update (HTTP ${res.status} from ${url}). ` +
+        "Check your network, or reinstall with the install script.",
+    );
+  }
+  const bytes = Buffer.from(await res.arrayBuffer());
+
+  // Integrity: the build publishes a .sha256 sidecar next to every
+  // tarball; a mismatch means a truncated or tampered download and
+  // must never reach the extract step. A missing sidecar is tolerated
+  // (older releases) but logged.
+  const sumRes = await fetchImpl(`${url}.sha256`).catch(() => null);
+  if (sumRes?.ok) {
+    const expected = (await sumRes.text()).trim().split(/\s+/)[0];
+    const actual = createHash("sha256").update(bytes).digest("hex");
+    if (expected && expected !== actual) {
+      throw new Error(
+        "Update checksum mismatch - the download is corrupt or tampered. " +
+          "Nothing was changed; retry, or reinstall with the install script.",
+      );
+    }
+  } else {
+    log("No checksum published for this build - skipping verification.");
+  }
+
+  const staging = await fs.mkdtemp(path.join(os.tmpdir(), "dharta-update-"));
+  const tarball = path.join(staging, "update.tar.gz");
+  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 replaceContents(extracted, root);
+  await fs.rm(staging, { recursive: true, force: true });
+  return "Updated. Run `karta --version` to confirm.";
+}
+
+async function fetchUpdate(url: string, fetchImpl: typeof fetch): Promise<Response> {
+  try {
+    return await fetchImpl(url);
+  } catch (error) {
+    throw new Error(
+      `Could not download the update from ${url}: ${(error as Error).message}. ` +
+        "Check your network, or reinstall with the install script.",
+    );
+  }
+}
+
+async function replaceContents(from: string, to: string): Promise<void> {
+  for (const entry of await fs.readdir(from)) {
+    const target = path.join(to, entry);
+    await fs.rm(target, { recursive: true, force: true });
+    await fs.cp(path.join(from, entry), target, { recursive: true });
+  }
+}
+
+function untar(tarball: string, dest: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("tar", ["-xzf", tarball, "-C", dest], { stdio: "ignore" });
+    proc.on("error", () => reject(new Error("Could not extract the update (is `tar` installed?).")));
+    proc.on("close", (code) =>
+      code === 0
+        ? resolve()
+        : reject(
+            new Error(
+              `tar exited ${code} extracting the update. Re-run \`dharta update\`; ` +
+                "reinstall with the install script if it persists.",
+            ),
+          ),
+    );
+  });
+}

package/src/commands/usage.ts

@@ -0,0 +1,41 @@
+import type { CliContext } from "../context.js";
+
+export async function usageData(ctx: CliContext) {
+  return ctx.sdk.usage.summary();
+}
+
+export async function usage(ctx: CliContext): Promise<string> {
+  const summary = await usageData(ctx);
+  const t = summary.totals ?? {};
+  const lines: string[] = [];
+  lines.push("Usage totals:");
+  const entries = Object.entries(t).filter(([, v]) => v !== undefined);
+  if (entries.length === 0) {
+    lines.push("  no usage recorded yet");
+    lines.push("  Generate usage with: dharta send \"hello\" --agent <slug>");
+  }
+  for (const [k, v] of entries) {
+    if (v === undefined) continue;
+    lines.push(`  ${formatUsageKey(k)}: ${formatUsageValue(k, v)}`);
+  }
+  if (summary.budget) {
+    lines.push("");
+    lines.push("Budget:");
+    lines.push(`  period: ${summary.budget.period_start} → ${summary.budget.period_end}`);
+    const cap = summary.budget.monthly_cap_cents;
+    lines.push(`  monthly_cap: ${cap == null ? "unlimited" : formatCents(cap)}`);
+  }
+  return lines.join("\n");
+}
+
+function formatUsageKey(key: string): string {
+  return key.endsWith("_cents") ? key.slice(0, -"_cents".length) : key;
+}
+
+function formatUsageValue(key: string, value: number): string {
+  return key.endsWith("_cents") ? formatCents(value) : String(value);
+}
+
+function formatCents(cents: number): string {
+  return `$${(cents / 100).toFixed(2)}`;
+}

package/src/commands/webhooks.ts

@@ -0,0 +1,200 @@
+import { randomUUID } from "node:crypto";
+import type { CliContext } from "../context.js";
+import { WEBHOOK_EVENT_TYPES } from "@dharta/sdk";
+import { fmtTs, table } from "../output.js";
+import { closestChoice, normalizeNonBlank } from "../validators.js";
+
+export interface WebhookEndpoint {
+  id: string;
+  name: string;
+  url: string;
+  event_types: string[];
+  enabled: boolean;
+  disabled_at: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+interface ListEnvelope<T> {
+  data: T[];
+  event_types?: string[];
+}
+
+interface EndpointEnvelope {
+  webhook_endpoint: WebhookEndpoint;
+  secret?: string;
+}
+
+export interface WebhookOptions {
+  event?: string[];
+}
+
+export async function webhooksListData(ctx: CliContext): Promise<WebhookEndpoint[]> {
+  const res = await ctx.http.request<ListEnvelope<WebhookEndpoint>>({ path: "/api/webhook_endpoints" });
+  return res.data;
+}
+
+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,
+    name: endpoint.name,
+    url: endpoint.url,
+    state: endpoint.enabled ? "enabled" : "disabled",
+    events: endpoint.event_types.join(",") || "all",
+    created: fmtTs(endpoint.created_at),
+  })));
+}
+
+export async function webhooksCreateData(
+  ctx: CliContext,
+  name: string,
+  url: string,
+  opts: WebhookOptions,
+): Promise<EndpointEnvelope> {
+  validateWebhooksCreateInput(name, url, opts);
+  const normalizedName = normalizeRequired(name, "Webhook name");
+  const normalizedUrl = normalizeWebhookUrl(url);
+  return ctx.http.request<EndpointEnvelope>({
+    method: "POST",
+    path: "/api/webhook_endpoints",
+    headers: idempotencyHeader(),
+    body: { name: normalizedName, url: normalizedUrl, event_types: parseEvents(opts.event) },
+  });
+}
+
+export async function webhooksCreate(ctx: CliContext, name: string, url: string, opts: WebhookOptions): Promise<string> {
+  const res = await webhooksCreateData(ctx, name, url, opts);
+  return [
+    `Created webhook endpoint ${res.webhook_endpoint.id}.`,
+    "Secret (shown once - configure your verifier now):",
+    res.secret ?? "",
+  ].join("\n");
+}
+
+export async function webhooksUpdateData(
+  ctx: CliContext,
+  id: string,
+  opts: { name?: string; url?: string; event?: string[] },
+): Promise<EndpointEnvelope> {
+  validateWebhooksUpdateInput(id, opts);
+  const normalizedId = normalizeWebhookId(id);
+  const body: Record<string, unknown> = {};
+  if (opts.name !== undefined) body.name = normalizeRequired(opts.name, "Webhook name");
+  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.");
+  }
+  return ctx.http.request<EndpointEnvelope>({
+    method: "PATCH",
+    path: `/api/webhook_endpoints/${encodeURIComponent(normalizedId)}`,
+    headers: idempotencyHeader(),
+    body,
+  });
+}
+
+export async function webhooksUpdate(ctx: CliContext, id: string, opts: { name?: string; url?: string; event?: string[] }): Promise<string> {
+  const res = await webhooksUpdateData(ctx, id, opts);
+  return `Updated webhook endpoint ${res.webhook_endpoint.id}.`;
+}
+
+export function validateWebhooksCreateInput(name: string, url: string, opts: WebhookOptions): void {
+  normalizeRequired(name, "Webhook name");
+  normalizeWebhookUrl(url);
+  parseEvents(opts.event);
+}
+
+export function validateWebhooksUpdateInput(id: string, opts: { name?: string; url?: string; event?: string[] }): void {
+  normalizeWebhookId(id);
+  const hasName = opts.name !== undefined;
+  const hasUrl = opts.url !== undefined;
+  const hasEvent = opts.event !== undefined;
+  if (hasName) normalizeRequired(opts.name!, "Webhook name");
+  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.");
+  }
+}
+
+export async function webhooksEnableData(ctx: CliContext, id: string): Promise<EndpointEnvelope> {
+  const normalizedId = normalizeWebhookId(id);
+  return ctx.http.request<EndpointEnvelope>({
+    method: "POST",
+    path: `/api/webhook_endpoints/${encodeURIComponent(normalizedId)}/enable`,
+    headers: idempotencyHeader(),
+  });
+}
+
+export async function webhooksEnable(ctx: CliContext, id: string): Promise<string> {
+  const res = await webhooksEnableData(ctx, id);
+  return `Enabled webhook endpoint ${res.webhook_endpoint.id}.`;
+}
+
+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 };
+}
+
+export async function webhooksDelete(ctx: CliContext, id: string): Promise<string> {
+  const res = await webhooksDeleteData(ctx, id);
+  return `Deleted webhook endpoint ${res.id}.`;
+}
+
+export function parseEvents(input: string[] | undefined): string[] {
+  if (input === undefined) return [];
+  const events = input
+    .flatMap((value) => value.split(/[,\s]+/))
+    .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.");
+  }
+  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(
+      `Unknown --event ${unknown.join(", ")}. Allowed events: ${WEBHOOK_EVENT_TYPES.join(", ")}.` +
+        (suggestion ? ` Did you mean ${suggestion}?` : ""),
+    );
+  }
+  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.`);
+  }
+  return normalized;
+}
+
+function normalizeWebhookUrl(value: string): string {
+  const normalized = normalizeRequired(value, "Webhook URL");
+  let parsed: URL;
+  try {
+    parsed = new URL(normalized);
+  } catch {
+    throw new Error("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.");
+  }
+  return normalized;
+}
+
+function normalizeWebhookId(id: string): string {
+  return normalizeNonBlank(id, "Webhook endpoint id");
+}

package/src/commands/whoami.ts

@@ -0,0 +1,24 @@
+import type { CliContext } from "../context.js";
+import type { Me } from "./auth.js";
+import { formatApiKeyExpiry, formatScopes } from "./scopes.js";
+
+export interface WhoamiData extends Me {
+  host: string;
+}
+
+export async function whoamiData(ctx: CliContext): Promise<WhoamiData> {
+  const me = await ctx.http.request<Me>({ path: "/me" });
+  return { ...me, host: ctx.baseUrl };
+}
+
+export async function whoami(ctx: CliContext): Promise<string> {
+  const me = await whoamiData(ctx);
+  const lines = [
+    `Organization: ${me.organization.name} (${me.organization.slug})`,
+    `Key: ${me.api_key.name} · ${me.api_key.prefix}…`,
+    `Scopes: ${formatScopes(me.api_key.scopes)}`,
+    `Expiry: ${formatApiKeyExpiry(me.api_key.expires_at)}`,
+    `Host: ${me.host}`,
+  ];
+  return lines.join("\n");
+}

package/src/completions.ts

@@ -0,0 +1,168 @@
+// `dharta completion <bash|zsh>` (RFC 0013 CLI-12): shell completion
+// 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 type { Argument, Command, Option } from "commander";
+
+interface CommandSpec {
+  name: string;
+  aliases: string[];
+  description: string;
+  // Long option flags (--json, --dir, ...) plus --help.
+  options: string[];
+  // Positional-argument choices (e.g. completion's bash|zsh) - offered
+  // as completion words alongside the options.
+  argChoices: string[];
+  subs: CommandSpec[];
+}
+
+export function specFromCommand(cmd: Command): CommandSpec {
+  return {
+    name: cmd.name(),
+    aliases: commandAliases(cmd),
+    description: sanitize(cmd.description()),
+    options: [
+      ...cmd.options.filter((o: Option) => !o.hidden && o.long).map((o: Option) => o.long as string),
+      "--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)),
+  };
+}
+
+// First sentence, single line. Shell-specific escaping happens when rendering
+// so meaningful tokens like audit_log:export keep their punctuation.
+function sanitize(description: string): string {
+  const firstSentence = description.replace(/\s+/g, " ").trim().split(". ")[0];
+  return firstSentence.replace(/\.$/, "");
+}
+
+function words(spec: CommandSpec): string {
+  return [...subcommandWords(spec), ...spec.argChoices, ...spec.options].join(" ");
+}
+
+function subcommandWords(spec: CommandSpec): string[] {
+  return spec.subs.flatMap((sub) => commandNames(sub));
+}
+
+function commandNames(spec: CommandSpec): string[] {
+  return [spec.name, ...spec.aliases];
+}
+
+function commandAliases(cmd: Command): string[] {
+  const maybeAliases = (cmd as unknown as { aliases?: () => string[] }).aliases;
+  return typeof maybeAliases === "function" ? maybeAliases.call(cmd) : [];
+}
+
+interface CompletionEntry {
+  path: string;
+  words: string;
+  describedCommands: string;
+}
+
+function completionEntries(root: CommandSpec): CompletionEntry[] {
+  const entries: CompletionEntry[] = [];
+  const visit = (spec: CommandSpec, paths: string[]): void => {
+    for (const path of paths) {
+      entries.push({
+        path,
+        words: words(spec),
+        describedCommands: describedSubcommands(spec),
+      });
+    }
+
+    for (const child of spec.subs) {
+      const childPaths = expandPaths(paths, commandNames(child));
+      visit(child, childPaths);
+    }
+  };
+
+  visit(root, [""]);
+  return entries;
+}
+
+function expandPaths(prefixes: string[], names: string[]): string[] {
+  return prefixes.flatMap((prefix) => names.map((name) => (prefix ? `${prefix} ${name}` : name)));
+}
+
+function describedSubcommands(spec: CommandSpec): string {
+  return spec.subs.flatMap((sub) => [
+    `'${escapeZshDescription(sub.name)}:${escapeZshDescription(sub.description)}'`,
+    ...sub.aliases.map((alias) => `'${escapeZshDescription(alias)}:Alias of ${escapeZshDescription(sub.name)}'`),
+  ]).join(" ");
+}
+
+function escapeBashCase(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\$/g, "\\$").replace(/`/g, "\\`");
+}
+
+function escapeZshCase(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/ /g, "\\ ").replace(/\)/g, "\\)");
+}
+
+function zshCasePattern(value: string): string {
+  return value === "" ? '""' : escapeZshCase(value);
+}
+
+function escapeZshDescription(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/'/g, "'\\''").replace(/:/g, "\\:");
+}
+
+export function bashCompletion(program: Command): string {
+  const spec = specFromCommand(program);
+  const entries = completionEntries(spec);
+  const lines: string[] = [
+    "# bash completion for karta - generated by `dharta completion bash`",
+    "# Load with: source <(dharta completion bash)  (or append to ~/.bash_completion)",
+    "_karta() {",
+    '  local cur="${COMP_WORDS[COMP_CWORD]}"',
+    '  local path="${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}"',
+    '  local words=""',
+    '  case "$path" in',
+  ];
+  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",
+  );
+  return lines.join("\n");
+}
+
+export function zshCompletion(program: Command): string {
+  const spec = specFromCommand(program);
+  const entries = completionEntries(spec);
+
+  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)",
+    "",
+    "_karta() {",
+    "  local -a reply",
+    '  local path=""',
+    "  if (( CURRENT > 2 )); then",
+    '    path="${(j: :)words[2,$((CURRENT - 1))]}"',
+    "  fi",
+    '  case "$path" in',
+  ];
+  for (const entry of entries) {
+    lines.push(
+      `    ${zshCasePattern(entry.path)})`,
+      entry.describedCommands
+        ? `      reply=( ${entry.describedCommands} ); _describe -t commands 'dharta command' reply`
+        : "      true",
+      entry.words ? `      compadd -- ${entry.words}` : "      true",
+      "      return",
+      "      ;;",
+    );
+  }
+  lines.push("  esac", "}", "", '_karta "$@"');
+  return lines.join("\n");
+}