@dharta/cli 0.6.77 → 0.6.78

package/src/harnesses.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import * as path from "node:path";
 import TOML from "@iarna/toml";
+import { CliUsageError } from "./exit-codes.js";
 import { closestChoice, normalizeNonBlank } from "./validators.js";
 
 export const HARNESS_TYPES = ["claude-code", "opencode", "deepagents", "goose", "codex-cli"] as const;
@@ -38,7 +39,7 @@ export function parseHarnessType(value: string | undefined, label = "--harness")
   const normalized = normalizeNonBlank(value, label);
   if ((HARNESS_TYPES as readonly string[]).includes(normalized)) return normalized as HarnessType;
   const suggestion = closestChoice(normalized, HARNESS_TYPES);
-  throw new Error(
+  throw new CliUsageError(
     `${label} must be one of ${HARNESS_TYPES.join(", ")}.` +
       (suggestion ? ` Did you mean ${suggestion}?` : ""),
   );

package/src/jq.ts

@@ -0,0 +1,109 @@
+// `--jq <expr>` (RFC 0048 P5): filter the JSON a command would print, without
+// making the user install jq. The filter runs in-process on a WebAssembly jq
+// (jq-wasm), so `dharta … --jq` behaves the same on a developer laptop, a
+// container, and the standalone tarball, and `dharta` keeps its single-binary
+// promise.
+//
+// Package choice: jq-wasm, pinned to 3.0.0-jq-1.8.2 (the current line). It is
+// the only maintained WebAssembly jq on npm that ships a prebuilt artifact - no
+// node-gyp, no emscripten toolchain, no postinstall script - with TypeScript
+// types and zero runtime dependencies. Its `engines.node >= 20` is below this
+// package's own floor, which commander 15 sets at 22.12.
+
+import { CliUsageError } from "./exit-codes.js";
+
+interface JqResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+// The input is handed over as JSON *text*, not as a live object: the binding
+// rejects a null or scalar argument, and `dharta api` can legitimately print
+// `null`, a number, or a bare string.
+type JqRaw = (input: string, query: string, flags?: string[]) => Promise<JqResult>;
+
+// -c only: one compact JSON value per line, so multiple results stay
+// one-per-line for `while read`.
+//
+// jq's own -r is deliberately NOT used. jq-wasm trims the whole of stdout, so
+// `--jq .v` over {"v":"  padded  "} would print `padded` and quietly lose the
+// value's own whitespace. Compact JSON never carries leading or trailing
+// whitespace, so the same trim is harmless here, and rawLine() below does what
+// -r does: a result that is a string prints without quotes, so
+// `--jq .name | xargs` works the way people expect from jq itself.
+const JQ_FLAGS = ["-c"];
+// jq's own exit code for a program that does not compile, as opposed to one
+// that compiles and then fails on the data (5) or hits a system error (2).
+const JQ_COMPILE_ERROR = 3;
+
+let expression: string | null = null;
+let jqRaw: JqRaw | null = null;
+
+export function jqExpression(): string | null {
+  return expression;
+}
+
+// Load jq and compile the expression BEFORE the command does its work. A
+// mistyped filter must not cost a mutation that then has nowhere to print.
+export async function armJqFilter(expr: string | undefined): Promise<void> {
+  expression = null;
+  jqRaw = null;
+  if (expr === undefined) return;
+
+  const query = expr.trim();
+  if (!query) {
+    throw new CliUsageError("--jq needs an expression, for example --jq '.data[].id'.");
+  }
+
+  jqRaw = await loadJqRaw();
+  const probe = await jqRaw("null", query, JQ_FLAGS);
+  if (probe.exitCode === JQ_COMPILE_ERROR) {
+    throw new CliUsageError(`--jq expression did not compile.\n${probe.stderr.trim()}`);
+  }
+  expression = query;
+}
+
+// Reset between runs. Tests drive the program repeatedly in one process, and a
+// leftover filter would silently rewrite the next command's output.
+export function disarmJqFilter(): void {
+  expression = null;
+  jqRaw = null;
+}
+
+export async function applyJqFilter(payload: unknown): Promise<string> {
+  if (expression === null || jqRaw === null) {
+    throw new Error("applyJqFilter called with no armed --jq expression.");
+  }
+  const result = await jqRaw(JSON.stringify(payload) ?? "null", expression, JQ_FLAGS);
+  if (result.exitCode !== 0) {
+    // Every non-zero exit here is the expression's fault given this payload
+    // (`.a.b` on a string, `.[0]` on an object), so it reads as a usage error.
+    throw new CliUsageError(`--jq failed on the response.\n${result.stderr.trim()}`);
+  }
+  // jq terminates every result with a newline; console.log adds its own.
+  const stdout = result.stdout.replace(/\n$/, "");
+  if (stdout === "") return "";
+  // One compact JSON value per line, so splitting on newlines is safe: a
+  // newline inside a string is escaped until rawLine() unescapes it.
+  return stdout.split("\n").map(rawLine).join("\n");
+}
+
+// What jq's -r does, done here so the library's trim cannot reach inside a
+// string. A line that is a JSON string prints as the string; anything else
+// (object, array, number, boolean, null) prints as it came out.
+function rawLine(line: string): string {
+  try {
+    const value: unknown = JSON.parse(line);
+    return typeof value === "string" ? value : line;
+  } catch {
+    return line;
+  }
+}
+
+// Imported lazily: the wasm build is about a megabyte, and a CLI run that never
+// passes --jq should never pay to load it.
+async function loadJqRaw(): Promise<JqRaw> {
+  const mod = (await import("jq-wasm")) as unknown as { raw: JqRaw };
+  return mod.raw;
+}

package/src/login-offer.ts

@@ -4,7 +4,7 @@
 // (which does need auth). --login forces it; otherwise we only prompt an
 // interactive terminal. It never blocks setup.
 
-import { activeProfile } from "./config.js";
+import { activeProfile, requestedProfileName } from "./config.js";
 import { login } from "./commands/login.js";
 
 export interface OfferLoginOptions {
@@ -35,7 +35,11 @@ export async function offerLogin(opts: OfferLoginOptions): Promise<OfferLoginOut
     return "skipped";
   }
 
-  await (opts.runLogin ?? (() => login({ log: opts.log }).then(() => undefined)))();
+  // The global --profile names the profile this writes, the same as a bare
+  // `dharta login`: `dharta setup --login --profile staging` must not store the
+  // key as `default`.
+  await (opts.runLogin ??
+    (() => login({ log: opts.log, profile: requestedProfileName() }).then(() => undefined)))();
   return "completed";
 }
 

package/src/manifest.ts

@@ -84,6 +84,30 @@ export function renderManifest(o: {
     '# setup = "scripts/setup.sh"',
     '# network = "full"',
     "",
+    "# --- Generative UI (RFC 0056) ----------------------------------------------",
+    "# Opt in to agent-driven UI in the embedded widget. No [genui] section = the",
+    "# agent answers in text only and pays no token cost for a catalog.",
+    "#   catalog_id - stable id for this agent's component catalog.",
+    "#   version    - bump when the catalog changes (integer >= 1; 1.0 is a float",
+    "#                and is rejected).",
+    "#   components - every component the agent may render, with its trust tier:",
+    "#                1 = a Dharta builtin, 2 = your JavaScript in a Web Worker,",
+    "#                3 = your HTML in a sandboxed iframe. Tiers 2-3 need a bundle.",
+    "#   bundle, bundle_sha256 - written by `dharta genui build`. Do not hand-edit",
+    "#                the digest; the deploy verifies it against the bundle bytes.",
+    "# Run `dharta genui build --help` for the source layout it compiles.",
+    "# [genui]",
+    '# catalog_id = "support-bot-ui"',
+    "# version = 1",
+    '# components = [{ name = "Card", tier = 1 }, { name = "Pentagraph", tier = 2 }]',
+    '# bundle = "genui/bundle.json"',
+    '# bundle_sha256 = "<64 hex characters>"',
+    "",
+    "# Build-time only, never part of the release contract: where",
+    "# `dharta genui build` reads component sources from.",
+    "# [genui.build]",
+    '# source = "genui/components"  # this is the default',
+    "",
   ].join("\n");
 }
 
@@ -119,6 +143,116 @@ export function patchScalar(src: string, key: string, literal: string): string {
   return (src.endsWith("\n") ? src : src + "\n") + line;
 }
 
+// Locate ONE `[table]`'s own lines: from its header to the next line that
+// starts a table. A multi-line inline array whose elements start a line with
+// `[` would end the region early; an edit built on that produces invalid TOML,
+// which the round-trip in `setGenuiBundleSha256` catches loudly rather than
+// writing out. `table` is always a literal we control ("genui").
+function tableRegion(lines: string[], table: string): { start: number; end: number } | null {
+  // `\r?` for the same reason assignmentPattern carries it: splitting a CRLF
+  // file on "\n" leaves the carriage return at the end of every line, and `.`
+  // never matches it, so `[genui] # comment\r` would not be recognized as a
+  // header and the whole table would read as absent.
+  const header = new RegExp(`^\\s*\\[\\s*${table}\\s*\\]\\s*(?:#.*?)?\\r?$`);
+  const start = lines.findIndex((line) => header.test(line));
+  if (start < 0) return null;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*\[/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return { start, end };
+}
+
+// Anchored to a line start, so a commented `# key = ...` is never matched. The
+// third group captures a CRLF file's carriage return, which lives at the end of
+// each line once the text is split on "\n" and would otherwise be swallowed by
+// the value group and dropped on replace, leaving one lone LF line in a CRLF
+// manifest.
+function assignmentPattern(key: string): RegExp {
+  return new RegExp(`^(\\s*${key}\\s*=)(.*?)(\\r?)$`);
+}
+
+/**
+ * The RAW right-hand side of `key` inside `[table]`, comment stripped, or null
+ * when the table or the key is not written in that plain form.
+ *
+ * Callers need the literal, not the parsed value, when TOML's type distinctions
+ * survive in Python and not in JavaScript: `version = 1.0` is a float to
+ * `tomllib` (and rejected by the data plane) but an indistinguishable `1` once
+ * `@iarna/toml` has handed it back as a JS number.
+ */
+export function tableScalarLiteral(src: string, table: string, key: string): string | null {
+  const lines = src.split("\n");
+  const region = tableRegion(lines, table);
+  if (!region) return null;
+  const assignment = assignmentPattern(key);
+  for (let i = region.start + 1; i < region.end; i++) {
+    const match = lines[i].match(assignment);
+    if (match) return match[2].replace(/\s+#.*$/, "").trim();
+  }
+  return null;
+}
+
+// The same surgical edit as patchScalar, but scoped to ONE [table]: replace the
+// key in place if the table already has it, else append it as the table's last
+// key. `patchScalar` cannot do this - it deliberately stops at the first table
+// header to keep top-level keys top-level.
+//
+// `table` and `key` are always literals we control ("genui", "bundle_sha256").
+export function patchTableScalar(
+  src: string,
+  table: string,
+  key: string,
+  literal: string,
+): string {
+  const lines = src.split("\n");
+  const region = tableRegion(lines, table);
+  if (!region) throw new Error(`No [${table}] table to patch.`);
+  const { start, end } = region;
+
+  const assignment = assignmentPattern(key);
+  for (let i = start + 1; i < end; i++) {
+    if (assignment.test(lines[i])) {
+      lines[i] = lines[i].replace(assignment, `$1 ${literal}$3`);
+      return lines.join("\n");
+    }
+  }
+  // Not present: insert straight after the table's last real line. Trailing
+  // blanks and comments are skipped because they usually introduce the NEXT
+  // table (`# --- Environment ---` above `[env]`), and a key wedged in there
+  // reads as if it belonged to that section.
+  let insert = end;
+  while (insert > start + 1) {
+    const previous = lines[insert - 1].trim();
+    if (previous !== "" && !previous.startsWith("#")) break;
+    insert--;
+  }
+  const eol = src.includes("\r\n") ? "\r" : "";
+  lines.splice(insert, 0, `${key} = ${literal}${eol}`);
+  return lines.join("\n");
+}
+
+// Record a freshly built RFC 0056 component bundle's digest in [genui],
+// preserving the manifest's comments and every other table. Round-trips through
+// the parser and re-reads the value, so an exotic layout that patchTableScalar
+// cannot edit correctly fails here instead of writing a manifest whose digest
+// silently does not match the bundle.
+export function setGenuiBundleSha256(src: string, digest: string): string {
+  const out = patchTableScalar(src, "genui", "bundle_sha256", JSON.stringify(digest));
+  const parsed = TOML.parse(out) as Record<string, unknown>; // throws on an invalid result
+  const genui = parsed.genui as Record<string, unknown> | undefined;
+  if (!genui || genui.bundle_sha256 !== digest) {
+    throw new Error(
+      "Could not record bundle_sha256 in the [genui] table of dharta.toml. " +
+        `Set \`bundle_sha256 = "${digest}"\` there by hand.`,
+    );
+  }
+  return out;
+}
+
 function hasTopLevelScalar(src: string, key: string): boolean {
   const tbl = src.search(/^\s*\[/m);
   const top = tbl >= 0 ? src.slice(0, tbl) : src;

package/src/model-auth.ts

@@ -0,0 +1,173 @@
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import type { ModelAuthCapability, ModelAuthReason } from "@dharta/contracts";
+import type { ModelConnectionProvider } from "@dharta/sdk";
+
+const require = createRequire(import.meta.url);
+const catalog = require("@dharta/contracts/model-auth-capabilities-v1.json") as {
+  capabilities: ModelAuthCapability[];
+};
+const reasonCatalog = require("@dharta/contracts/model-auth-reasons-v1.json") as {
+  reasons: ModelAuthReason[];
+};
+
+export const MODEL_AUTH_MISSING = modelAuthReason("model_auth_missing");
+export const MODEL_AUTH_CAPABILITY_DISABLED = modelAuthReason("model_auth_capability_disabled");
+
+export const DEV_MODEL_AUTH_VALUES = ["api-key", "claude"] as const;
+export type DevModelAuth = (typeof DEV_MODEL_AUTH_VALUES)[number];
+
+export const MODEL_CONNECTION_PROVIDERS = catalog.capabilities
+  .filter((capability) => capability.admission === "enabled" && capability.credential_kind === "api_key")
+  .map((capability) => capability.provider) as ModelConnectionProvider[];
+
+const CAPABILITY_IDS: Record<DevModelAuth, string> = {
+  "api-key": "anthropic_api_key",
+  claude: "anthropic_claude_local_subscription",
+};
+
+export interface ClaudeAuthStatus {
+  installed: boolean;
+  authenticated: boolean;
+  detail?: string;
+}
+
+export interface CommandStatus {
+  status: number | null;
+  stdout?: string;
+  stderr?: string;
+  error?: Error;
+}
+
+export type RunCommandStatus = (command: string, args: string[], env: NodeJS.ProcessEnv) => CommandStatus;
+
+const COPIED_PROVIDER_CREDENTIALS = ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"] as const;
+
+function withoutCopiedProviderCredentials(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const clean = { ...env };
+  for (const name of COPIED_PROVIDER_CREDENTIALS) delete clean[name];
+  return clean;
+}
+
+const runCommandStatus: RunCommandStatus = (command, args, env) => {
+  const result = spawnSync(command, args, { encoding: "utf8", env });
+  return {
+    status: result.status,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    error: result.error,
+  };
+};
+
+export function checkClaudeAuth(
+  env: NodeJS.ProcessEnv = process.env,
+  run: RunCommandStatus = runCommandStatus,
+): ClaudeAuthStatus {
+  const result = run("claude", ["auth", "status"], withoutCopiedProviderCredentials(env));
+  if (result.error && (result.error as NodeJS.ErrnoException).code === "ENOENT") {
+    return { installed: false, authenticated: false, detail: "Claude client is not installed or is not on PATH." };
+  }
+  const detail = (result.stderr || result.stdout || result.error?.message || "").trim() || undefined;
+  return { installed: true, authenticated: result.status === 0, detail };
+}
+
+export interface ResolvedDevModelAuth {
+  selection: DevModelAuth;
+  capability: ModelAuthCapability;
+  env: NodeJS.ProcessEnv;
+}
+
+export function resolveDevModelAuth(
+  requested: DevModelAuth | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+  run: RunCommandStatus = runCommandStatus,
+): ResolvedDevModelAuth {
+  const claude = requested === "api-key"
+    ? { installed: false, authenticated: false }
+    : checkClaudeAuth(env, run);
+  const apiKeyCapability = capabilityFor("api-key");
+  const claudeCapability = capabilityFor("claude");
+  const apiKeyPresent = Boolean(env.ANTHROPIC_API_KEY?.trim());
+  const apiKeyAvailable = apiKeyPresent && capabilityEnabled(apiKeyCapability, env);
+  const claudeAvailable = claude.authenticated && capabilityEnabled(claudeCapability, env);
+
+  let selection = requested;
+  if (!selection) {
+    const available: DevModelAuth[] = [];
+    if (apiKeyAvailable) available.push("api-key");
+    if (claudeAvailable) available.push("claude");
+    if (available.length > 1) {
+      throw new Error("Multiple Anthropic model authentication methods are ready. Choose one with `dharta dev --model-auth api-key` or `dharta dev --model-auth claude`.");
+    }
+    selection = available[0];
+  }
+
+  if (!selection) {
+    throw new Error(
+      `${MODEL_AUTH_MISSING}: No Anthropic model authentication is ready. Export ANTHROPIC_API_KEY and use \`--model-auth api-key\`, ` +
+        "or run `claude auth login` and use `--model-auth claude`.",
+    );
+  }
+  if (selection === "api-key" && !apiKeyPresent) {
+    throw new Error(`${MODEL_AUTH_MISSING}: \`--model-auth api-key\` requires ANTHROPIC_API_KEY in the dev environment.`);
+  }
+  if (selection === "claude" && !claude.authenticated) {
+    const prefix = claude.installed ? "Claude is not logged in." : "Claude client is not available.";
+    throw new Error(`${MODEL_AUTH_MISSING}: ${prefix} Run \`claude auth login\`, then retry \`dharta dev --model-auth claude\`.`);
+  }
+
+  const capability = selection === "api-key" ? apiKeyCapability : claudeCapability;
+  if (!capabilityEnabled(capability, env)) {
+    throw new Error(
+      `Model authentication capability ${capability.id} is disabled (${MODEL_AUTH_CAPABILITY_DISABLED}). ` +
+        `provider=${capability.provider}; credential-kind=${capability.credential_kind}; ` +
+        `funding=${capability.funding_source}; scope=${capability.execution_scopes.join(",") || "none"}.`,
+    );
+  }
+
+  const childEnv = { ...env };
+  delete childEnv.ANTHROPIC_AUTH_TOKEN;
+  delete childEnv.CLAUDE_CODE_OAUTH_TOKEN;
+  if (selection === "claude") delete childEnv.ANTHROPIC_API_KEY;
+  return { selection, capability, env: childEnv };
+}
+
+function capabilityEnabled(
+  capability: ModelAuthCapability,
+  env: NodeJS.ProcessEnv,
+): boolean {
+  return capability.admission === "enabled" && runtimeSwitchOpen(capability, env);
+}
+
+export function capabilityFor(selection: DevModelAuth): ModelAuthCapability {
+  const id = CAPABILITY_IDS[selection];
+  const capability = catalog.capabilities.find((entry) => entry.id === id);
+  if (!capability) throw new Error(`Model authentication catalog is missing capability ${id}.`);
+  return capability;
+}
+
+export function runtimeSwitchOpen(
+  capability: ModelAuthCapability,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  const key = `DHARTA_MODEL_AUTH_${capability.runtime_switch.toUpperCase()}_ENABLED`;
+  const raw = env[key];
+  if (raw === undefined) return true;
+  const value = raw.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(value)) return true;
+  if (["0", "false", "no", "off"].includes(value)) return false;
+  throw new Error(`${key} must be true or false.`);
+}
+
+function modelAuthReason(code: string): string {
+  const reason = reasonCatalog.reasons.find((entry) => entry.code === code);
+  if (!reason) throw new Error(`Model authentication reason catalog is missing ${code}.`);
+  return reason.code;
+}
+
+export function formatModelAuthCapability(capability: ModelAuthCapability): string {
+  return (
+    `provider=${capability.provider}; credential-kind=${capability.credential_kind}; ` +
+    `funding=${capability.funding_source}; scope=${capability.execution_scopes.join(",") || "none"}`
+  );
+}