@dharta/cli 0.6.77

package/src/config.ts

@@ -0,0 +1,143 @@
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import * as path from "node:path";
+import TOML from "@iarna/toml";
+
+// 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
+// model; the CLI talks to two of them:
+//   base_url      - the control API (Bearer dh_live_): login, projects,
+//                   templates, rollback. The Rails app - dharta.ai today,
+//                   console.dharta.ai after the HOST-3 cutover.
+//   git_base_url  - the hosted git server (Basic + API key): where
+//                   `dharta deploy` points the remote and which host the
+//                   credential helper answers for.
+// The agent host (agent.dharta.ai, the consumer endpoint) is never
+// configured here: `dharta open` reads the project's agent_url from the
+// control plane, and `dharta dev` serves the same protocol locally.
+export interface Profile {
+  api_key: string;
+  base_url: string;
+  git_base_url?: string;
+  // RFC 0043 D8: the data-plane git host this profile clones karta workspaces from
+  // (learned from /me at login). Distinct from git_base_url (the RFC 0011 push host) -
+  // the clone bytes flow straight from the data plane, never through the control plane.
+  workspace_git_base_url?: string;
+}
+
+export interface Config {
+  default_profile: string;
+  profiles: Record<string, Profile>;
+}
+
+// Allow tests to redirect HOME without setting process.env.HOME globally.
+let homeOverride: string | undefined;
+
+export function setHomeForTesting(home: string | undefined): void {
+  homeOverride = home;
+}
+
+export function configPath(): string {
+  const home = homeOverride ?? process.env.HOME ?? homedir();
+  return path.join(home, ".dharta", "config.toml");
+}
+
+// NOT api.dharta.ai: that name resolves to the data plane (the RFC 0011
+// as-built base-URL confusion this constant fixes). The control API
+// lives on the Rails app.
+const DEFAULT_BASE_URL = "https://dharta.ai";
+const DEFAULT_GIT_BASE_URL = "https://git.dharta.ai";
+
+export async function loadConfig(): Promise<Config | null> {
+  try {
+    const raw = await fs.readFile(configPath(), "utf8");
+    const parsed = TOML.parse(raw) as unknown as Partial<Config>;
+    if (!parsed.default_profile || !parsed.profiles) return null;
+    return {
+      default_profile: parsed.default_profile,
+      profiles: parsed.profiles,
+    };
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+export async function saveProfile(
+  name: string,
+  profile: Profile,
+): Promise<string> {
+  const target = configPath();
+  await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+  const existing = (await loadConfig()) ?? {
+    default_profile: name,
+    profiles: {},
+  };
+  existing.profiles[name] = profile;
+  existing.default_profile = name;
+  await fs.writeFile(
+    target,
+    TOML.stringify(existing as unknown as TOML.JsonMap),
+    {
+      mode: 0o600,
+    },
+  );
+  return target;
+}
+
+// Remove a stored profile (auth logout). Returns false if it didn't
+// exist. If the default profile was removed, the first remaining one
+// becomes the default; the file is deleted when no profiles remain.
+export async function removeProfile(name: string): Promise<boolean> {
+  const cfg = await loadConfig();
+  if (!cfg || !cfg.profiles[name]) return false;
+  delete cfg.profiles[name];
+
+  const remaining = Object.keys(cfg.profiles);
+  if (remaining.length === 0) {
+    await fs.rm(configPath(), { force: true });
+    return true;
+  }
+  if (cfg.default_profile === name) cfg.default_profile = remaining[0];
+  await fs.writeFile(
+    configPath(),
+    TOML.stringify(cfg as unknown as TOML.JsonMap),
+    { mode: 0o600 },
+  );
+  return true;
+}
+
+export async function activeProfile(): Promise<Profile> {
+  const cfg = await loadConfig();
+  if (!cfg) {
+    throw new Error(
+      "Not logged in. Run `dharta login` to store an API key in ~/.dharta/config.toml.",
+    );
+  }
+  const profile = cfg.profiles[cfg.default_profile];
+  if (!profile) {
+    throw new Error(
+      `Default profile '${cfg.default_profile}' not found in ${configPath()}. ` +
+        "Run `dharta login` to recreate it.",
+    );
+  }
+  return {
+    api_key: profile.api_key,
+    base_url: profile.base_url || DEFAULT_BASE_URL,
+    git_base_url: profile.git_base_url || DEFAULT_GIT_BASE_URL,
+    workspace_git_base_url: profile.workspace_git_base_url,
+  };
+}
+
+// Base URL for commands that work without a credential (init's template
+// fetch): env override, then the stored profile, then the default.
+export async function resolveBaseUrl(): Promise<string> {
+  if (process.env.DHARTA_BASE_URL) return process.env.DHARTA_BASE_URL;
+  try {
+    return (await activeProfile()).base_url;
+  } catch {
+    return DEFAULT_BASE_URL;
+  }
+}
+
+export { DEFAULT_BASE_URL, DEFAULT_GIT_BASE_URL };

package/src/context.ts

@@ -0,0 +1,59 @@
+import { Dharta, HttpClient } from "@dharta/sdk";
+import { activeProfile, DEFAULT_BASE_URL } from "./config.js";
+import { cliFormatError, cliFormatNetworkError } from "./api-error.js";
+
+export interface CliContext {
+  sdk: Dharta;
+  http: HttpClient;
+  baseUrl: string;
+  // Exposed for `dharta deploy`, which hands the key to git's
+  // credential helper via the child process env.
+  apiKey: string;
+  // The resolved fetch impl (a test stub, or undefined = global fetch). Exposed so
+  // `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;
+}
+
+// Allow tests to inject a stub fetch + base config without touching disk.
+export interface CtxOverrides {
+  apiKey?: string;
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+
+export async function buildContext(
+  over: CtxOverrides = {},
+): 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) {
+    apiKey = process.env.DHARTA_API_KEY;
+  }
+  if (!apiKey) {
+    const p = await activeProfile();
+    apiKey = p.api_key;
+    baseUrl = baseUrl ?? p.base_url;
+  }
+  if (!baseUrl) baseUrl = DEFAULT_BASE_URL;
+  const fetchImpl = over.fetch;
+  const sdk = new Dharta({
+    apiKey,
+    baseUrl,
+    fetch: fetchImpl,
+    formatError: cliFormatError,
+    formatNetworkError: cliFormatNetworkError,
+  });
+  const http = new HttpClient({
+    apiKey,
+    baseUrl,
+    fetch: fetchImpl,
+    formatError: cliFormatError,
+    formatNetworkError: cliFormatNetworkError,
+  });
+  return { sdk, http, baseUrl, apiKey, fetch: fetchImpl };
+}

package/src/device-flow.ts

@@ -0,0 +1,174 @@
+// RFC 8628 device-flow client for `dharta login` (RFC 0013 CLI-1).
+// Mints a code pair on the control plane, shows the user code, opens the
+// approve page, and polls the token endpoint until the browser approval
+// mints a named CLI credential.
+
+import { openBrowser } from "./browser.js";
+
+export interface DeviceFlowOptions {
+  baseUrl: string;
+  clientName?: string;
+  fetchImpl?: typeof fetch;
+  log?: (line: string) => void;
+  openBrowser?: (url: string) => Promise<boolean>;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+interface MintResponse {
+  device_code: string;
+  user_code: string;
+  verification_uri: string;
+  verification_uri_complete?: string;
+  expires_in: number;
+  interval?: number;
+}
+
+const EXPIRED_MESSAGE =
+  "The login code expired before it was approved. Run `dharta login` again.";
+// Consecutive network failures tolerated before giving up — the
+// approval window is minutes long, so one wifi blip must not abort it.
+const MAX_CONSECUTIVE_NETWORK_FAILURES = 5;
+
+// Resolves to the freshly minted API key (dh_live_…).
+export async function deviceFlowLogin(opts: DeviceFlowOptions): Promise<string> {
+  const fetchImpl = (opts.fetchImpl ?? globalThis.fetch).bind(globalThis);
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const sleep =
+    opts.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const base = opts.baseUrl.replace(/\/+$/, "");
+
+  let mintRes: Response;
+  try {
+    mintRes = await fetchImpl(`${base}/cli/device_authorizations`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "application/json" },
+      body: JSON.stringify({ client_name: opts.clientName }),
+    });
+  } catch (error) {
+    throw new Error(
+      `Could not start the login: could not reach ${base} (${formatCause(error)}). ` +
+        "Check your network and try `dharta login` again.",
+    );
+  }
+  if (!mintRes.ok) {
+    throw new Error(
+      `Could not start the login (${mintRes.status} from ${base}). ` +
+        "Check your network and try `dharta login` again.",
+    );
+  }
+  let mint: MintResponse;
+  try {
+    mint = (await mintRes.json()) as MintResponse;
+  } catch (error) {
+    throw new Error(
+      `Could not start the login: ${base} returned invalid JSON (${formatCause(error)}). ` +
+        "Check DHARTA_BASE_URL or try `dharta login` again.",
+    );
+  }
+  if (
+    typeof mint.device_code !== "string" ||
+    typeof mint.user_code !== "string" ||
+    typeof mint.verification_uri !== "string" ||
+    typeof mint.expires_in !== "number"
+  ) {
+    throw new Error(
+      `Could not start the login: ${base} returned an incomplete device login response. ` +
+        "Check DHARTA_BASE_URL or try `dharta login` again.",
+    );
+  }
+
+  const approveUrl = mint.verification_uri_complete ?? mint.verification_uri;
+  log(`! First, verify this code in your browser: ${mint.user_code}`);
+
+  const opened = await (opts.openBrowser ?? openBrowser)(approveUrl);
+  log(
+    opened
+      ? `Opening ${approveUrl} in your browser…`
+      : `Open this URL to approve: ${approveUrl}`,
+  );
+  log("Waiting for approval…");
+
+  // RFC 8628: interval is optional, default 5s. Guard against a
+  // missing/garbage value — setTimeout(NaN) fires immediately and
+  // would hot-loop the poll.
+  let intervalMs = Math.max(Number(mint.interval) || 5, 1) * 1000;
+  const deadline = Date.now() + mint.expires_in * 1000;
+  let networkFailures = 0;
+
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+
+    let res: Response;
+    try {
+      res = await fetchImpl(`${base}/cli/device_authorizations/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({ device_code: mint.device_code }),
+      });
+    } catch {
+      // Transient network failure mid-poll: keep waiting, the
+      // deadline bounds the loop.
+      networkFailures += 1;
+      if (networkFailures >= MAX_CONSECUTIVE_NETWORK_FAILURES) {
+        throw new Error(
+          `Lost the connection to ${base} while waiting for approval. ` +
+            "Check your network and run `dharta login` again.",
+        );
+      }
+      continue;
+    }
+    networkFailures = 0;
+
+    if (res.ok) {
+      let token: string | undefined;
+      try {
+        token = ((await res.json()) as { access_token?: string }).access_token;
+      } catch {
+        // fall through to the throw below
+      }
+      if (!token) {
+        throw new Error(
+          "The server approved the login but returned no token. Run `dharta login` again.",
+        );
+      }
+      return token;
+    }
+
+    if (res.status === 429) {
+      // Rate-limited (Rack::Attack): back off like slow_down rather
+      // than keeping the cadence that tripped the limit.
+      await res.text().catch(() => {});
+      intervalMs += 5000;
+      continue;
+    }
+
+    let error = "";
+    try {
+      error = ((await res.json()) as { error?: string }).error ?? "";
+    } catch {
+      // non-JSON error body: fall through to the unknown-error throw
+    }
+
+    switch (error) {
+      case "authorization_pending":
+        continue;
+      case "slow_down":
+        intervalMs += 5000; // RFC 8628 §3.5: back off by 5s on slow_down
+        continue;
+      case "expired_token":
+        throw new Error(EXPIRED_MESSAGE);
+      case "access_denied":
+        throw new Error("The login request was denied in the browser.");
+      default:
+        throw new Error(
+          `Login failed (${error || `HTTP ${res.status}`}). Run \`dharta login\` again.`,
+        );
+    }
+  }
+
+  throw new Error(EXPIRED_MESSAGE);
+}
+
+function formatCause(error: unknown): string {
+  return error instanceof Error && error.message ? error.message : String(error);
+}

package/src/harness-preflight.ts

@@ -0,0 +1,293 @@
+// RFC 0035 D7: an advisory, client-side pre-flight for a dharta.toml [harness]
+// version declaration. Release acceptance on the control plane is authoritative;
+// this check is stale-able (the catalog is CDN-cached) and bypassable (the API
+// and old CLIs exist), so a green pre-flight is not a guarantee. Its only job is
+// fast LOCAL feedback before a deploy round-trips:
+//
+//   - block a version pin the platform can't honour (exit non-zero, like the
+//     server would, but instantly and with the supported list), and
+//   - surface a local-vs-cloud version gap so the developer deploys knowingly.
+//
+// Resolution rule A (locked): a range like "2" resolves to the LATEST matching
+// supported version for everyone and for CI - deterministic, the same on every
+// machine. The locally-installed build never changes what deploys; it only
+// *guides* an optional parity pin. So this pre-flight warns on a gap and offers
+// the closest version to pin, but the deploy target itself stays deterministic.
+//
+// It must never block a deploy on its own failure: any error reaching the
+// catalog, parsing, or probing the local binary degrades to "proceed" and lets
+// the authoritative server have the final word. The two deliberate aborts are an
+// unsatisfiable pin and a developer answering "no" to the gap prompt.
+
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import * as readline from "node:readline";
+import TOML from "@iarna/toml";
+import { sniffHarnessType } from "./harnesses.js";
+import { whichAll } from "./runtime.js";
+
+export interface CatalogVersion {
+  version: string;
+  status: string;
+}
+export interface CatalogHarness {
+  id: string;
+  name: string;
+  default_version?: string | null;
+  versions: CatalogVersion[];
+}
+
+// The binary whose `--version` reports the locally-installed harness build. Only
+// types we can probe are listed; an unlisted type yields a null local version
+// (the pin is still validated against the catalog, just no gap warning).
+const LOCAL_BIN: Record<string, string> = {
+  "claude-code": "claude",
+  opencode: "opencode",
+};
+
+export interface PreflightDeps {
+  dir: string;
+  baseUrl: string;
+  log: (line: string) => void;
+  // Injectable seams so unit tests never touch the network, a real binary, or a
+  // TTY. Defaults wire the real implementations.
+  fetchImpl?: typeof fetch;
+  detectLocalVersion?: (type: string) => Promise<string | null>;
+  confirm?: (question: string) => Promise<boolean>;
+}
+
+// `dharta.toml`'s [harness] table, shape-mirrored from the data plane's
+// parse_harness_table (spec.py): an optional type + optional string version.
+interface HarnessTable {
+  type?: string;
+  version?: string;
+}
+
+// Read [harness] from dir/dharta.toml. Returns null when there's no manifest, no
+// [harness] table, or the file can't be parsed - all "nothing to check" cases.
+async function readHarnessTable(dir: string): Promise<HarnessTable | null> {
+  const path = join(dir, "dharta.toml");
+  if (!existsSync(path)) return null;
+  let parsed: unknown;
+  try {
+    parsed = TOML.parse(await readFile(path, "utf8"));
+  } catch {
+    return null; // a malformed manifest fails loudly at the server; not our job
+  }
+  const table = (parsed as Record<string, unknown>).harness;
+  if (table === null || typeof table !== "object") return null;
+  const t = table as Record<string, unknown>;
+  return {
+    type: typeof t.type === "string" && t.type.trim() ? t.type.trim() : undefined,
+    version: typeof t.version === "string" && t.version.trim() ? t.version.trim() : undefined,
+  };
+}
+
+// Back-compat type sniff, mirroring the data plane's sniff_harness_type: a tree
+// is claude-code only when it carries Claude config and NOT OpenCode config;
+// anything else (incl. a bare folder) is the opencode default. Used only when
+// [harness] declares a version but omits the type.
+export function sniffType(dir: string): string {
+  return sniffHarnessType(dir);
+}
+
+// Compare two dotted numeric versions; positive when a > b. Pads the shorter
+// with zeros and compares segment-by-segment (Gem::Version-style, the server's
+// ordering). Non-numeric segments compare as 0 - claude-code/opencode versions
+// are plain numerics, and a malformed entry shouldn't crash the advisory path.
+export function compareVersions(a: string, b: string): number {
+  const pa = a.split(".");
+  const pb = b.split(".");
+  const n = Math.max(pa.length, pb.length);
+  for (let i = 0; i < n; i++) {
+    const da = Number.parseInt(pa[i] ?? "0", 10) || 0;
+    const db = Number.parseInt(pb[i] ?? "0", 10) || 0;
+    if (da !== db) return da - db;
+  }
+  return 0;
+}
+
+// True when `version`'s dot segments start with all of `prefix`'s segments
+// ("2" matches 2.x.x; "2.1" matches 2.1.x; an exact string also matches). Mirrors
+// HarnessVersion.version_has_prefix? - a plain string prefix would wrongly match
+// "20.x" for "2"; segment compare won't.
+export function versionHasPrefix(version: string, prefix: string): boolean {
+  const v = version.split(".");
+  const p = prefix.split(".");
+  if (p.length === 0 || p.length > v.length) return false;
+  return p.every((seg, i) => v[i] === seg);
+}
+
+// Advisory mirror of Harness#resolve_version (rule A): blank -> the default (if
+// supported), exact -> that version, prefix -> the LATEST matching. Returns null
+// when nothing matches, exactly when the server would fail acceptance.
+export function resolvePreview(
+  constraint: string | undefined,
+  supported: string[],
+  defaultVersion?: string | null,
+): string | null {
+  if (!constraint) {
+    return defaultVersion && supported.includes(defaultVersion) ? defaultVersion : null;
+  }
+  if (supported.includes(constraint)) return constraint;
+  const matching = supported.filter((v) => versionHasPrefix(v, constraint));
+  if (matching.length === 0) return null;
+  return matching.slice().sort((a, b) => compareVersions(b, a))[0];
+}
+
+// The supported version closest to the local build, to offer as a parity pin:
+// the longest shared leading-segment prefix with `local` (stay in the same
+// major.minor line), tie-broken by the latest within that line. Null when
+// there's no local build or no supported versions.
+export function closestForParity(local: string | null, supported: string[]): string | null {
+  if (!local || supported.length === 0) return null;
+  const lp = local.split(".");
+  const shared = (v: string): number => {
+    const vp = v.split(".");
+    let n = 0;
+    while (n < lp.length && n < vp.length && lp[n] === vp[n]) n++;
+    return n;
+  };
+  const maxShared = Math.max(...supported.map(shared));
+  return supported
+    .filter((v) => shared(v) === maxShared)
+    .sort((a, b) => compareVersions(b, a))[0];
+}
+
+// Fetch the public harness catalog (GET /harnesses.json). Returns null on any
+// failure - the pre-flight then proceeds and the server decides.
+async function fetchCatalog(
+  baseUrl: string,
+  fetchImpl: typeof fetch,
+): Promise<CatalogHarness[] | null> {
+  try {
+    const res = await fetchImpl(`${baseUrl.replace(/\/$/, "")}/harnesses.json`);
+    if (!res.ok) return null;
+    const body = (await res.json()) as { harnesses?: CatalogHarness[] };
+    return Array.isArray(body.harnesses) ? body.harnesses : null;
+  } catch {
+    return null;
+  }
+}
+
+// Probe the locally-installed harness build via `<bin> --version`, returning the
+// first dotted-numeric token (e.g. "2.1.190" from "2.1.190 (Claude Code)") or
+// null when the binary isn't on PATH or doesn't answer. Best-effort: any failure
+// is a null, never a throw.
+async function detectLocalVersionDefault(type: string): Promise<string | null> {
+  const bin = LOCAL_BIN[type];
+  if (!bin) return null;
+  if ((await whichAll(bin)).length === 0) return null;
+  const out = await runVersion(bin);
+  const match = out?.match(/\d+(?:\.\d+)+/);
+  return match ? match[0] : null;
+}
+
+function runVersion(bin: string): Promise<string | null> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (v: string | null) => {
+      if (!settled) {
+        settled = true;
+        resolve(v);
+      }
+    };
+    try {
+      const proc = spawn(bin, ["--version"], { stdio: ["ignore", "pipe", "ignore"] });
+      const out: Buffer[] = [];
+      proc.stdout?.on("data", (c) => out.push(c));
+      proc.on("error", () => done(null));
+      proc.on("close", () => done(Buffer.concat(out).toString().trim() || null));
+      // A hung binary must not hang the deploy.
+      const timer = setTimeout(() => {
+        proc.kill();
+        done(null);
+      }, 4000);
+      timer.unref?.();
+    } catch {
+      done(null);
+    }
+  });
+}
+
+// TTY-aware [Y/n] confirm, default yes. Non-interactive (no TTY, or piped stdin
+// in CI) auto-confirms so a deploy pipeline never hangs waiting on input - the
+// gap was already printed, so it's surfaced either way.
+function confirmTTYDefault(question: string): Promise<boolean> {
+  if (!process.stdin.isTTY) return Promise.resolve(true);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      const a = answer.trim().toLowerCase();
+      resolve(a === "" || a === "y" || a === "yes");
+    });
+  });
+}
+
+// Right-pad a label so the values line up in the printed table.
+function row(label: string, value: string): string {
+  return `  ${label.padEnd(24)}${value}`;
+}
+
+// Run the pre-flight. Resolves normally to let the deploy proceed; throws to
+// abort it (an unsatisfiable pin, or a declined gap prompt). Activates only when
+// [harness] declares a version - an omitted version is always the curated
+// default, so there's nothing to validate and the post-deploy echo shows what
+// was frozen.
+export async function harnessPreflight(deps: PreflightDeps): Promise<void> {
+  const table = await readHarnessTable(deps.dir);
+  if (!table?.version) return; // no declared constraint -> nothing to check
+
+  const type = table.type ?? sniffType(deps.dir);
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const catalog = await fetchCatalog(deps.baseUrl, fetchImpl);
+  if (!catalog) return; // catalog unreachable -> defer to the authoritative server
+
+  const harness = catalog.find((h) => h.id === type);
+  if (!harness) return; // unknown to the advisory catalog -> let the server judge
+  const supported = harness.versions.filter((v) => v.status === "supported").map((v) => v.version);
+
+  const detect = deps.detectLocalVersion ?? detectLocalVersionDefault;
+  const local = await detect(type).catch(() => null);
+  const localLabel = local ?? "not detected";
+
+  const resolved = resolvePreview(table.version, supported, harness.default_version);
+
+  if (resolved === null) {
+    // The pin matches no supported version. Block - the platform can't run a
+    // version it doesn't have - with the supported list so the fix is obvious.
+    const supportedLabel = supported.length ? supported.join(", ") : "(none published)";
+    throw new Error(
+      `Harness version pre-flight failed.\n` +
+        row(`Local ${type}:`, localLabel) + "\n" +
+        row("dharta.toml version:", table.version) + "\n" +
+        row("Supported on Dharta:", supportedLabel) + "\n\n" +
+        `  No Dharta-supported ${type} version matches "${table.version}". ` +
+        `Update or clear the version in [harness] in dharta.toml, then re-deploy.`,
+    );
+  }
+
+  if (local && local !== resolved) {
+    // The deploy target is deterministic (rule A: latest matching); the local
+    // build just differs. Surface the gap and the closest version to pin for
+    // parity, then let the developer decide.
+    const closest = closestForParity(local, supported);
+    deps.log(`⚠ Your local ${type} build differs from the deploy target.`);
+    deps.log(row(`Local ${type}:`, local));
+    deps.log(row("dharta.toml version:", `${table.version}  (deploys as ${resolved})`));
+    if (closest && closest !== resolved) {
+      deps.log(row("Closest to your local:", `${closest}  (pin it in [harness] for parity)`));
+    }
+    const confirm = deps.confirm ?? confirmTTYDefault;
+    const proceed = await confirm(`  Deploy on ${type} ${resolved} anyway? [Y/n] `);
+    if (!proceed) {
+      throw new Error(
+        `Deploy cancelled - local ${type} ${local} differs from the deploy target ${resolved}. ` +
+          `Pin a version in [harness] in dharta.toml, or re-run to accept the difference.`,
+      );
+    }
+  }
+}