@dharta/cli 0.6.77

package/src/harnesses.ts

@@ -0,0 +1,117 @@
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+import TOML from "@iarna/toml";
+import { closestChoice, normalizeNonBlank } from "./validators.js";
+
+export const HARNESS_TYPES = ["claude-code", "opencode", "deepagents", "goose", "codex-cli"] as const;
+export type HarnessType = (typeof HARNESS_TYPES)[number];
+
+export const DEFAULT_CREATE_HARNESS: HarnessType = "claude-code";
+
+const HARNESS_MARKERS: Record<HarnessType, string[]> = {
+  "claude-code": [".claude", "CLAUDE.md"],
+  opencode: [".opencode/opencode.jsonc", ".opencode/agents"],
+  deepagents: [".deepagents", ".deepagents/agents"],
+  goose: [".goose", ".goose/agents"],
+  "codex-cli": [".codex/config.toml", ".codex/agents"],
+};
+
+const NATIVE_TEMPLATE_MARKER: Partial<Record<HarnessType, { path: string; content: string }>> = {
+  opencode: { path: ".opencode/opencode.jsonc", content: "{}\n" },
+  deepagents: { path: ".deepagents/dharta.jsonc", content: "{}\n" },
+  goose: { path: ".goose/dharta.jsonc", content: "{}\n" },
+  "codex-cli": { path: ".codex/config.toml", content: "# Codex project config for this Dharta agent.\n" },
+};
+
+export const AGENT_MARKERS = [
+  "dharta.toml",
+  "CLAUDE.md",
+  ".claude",
+  ".opencode",
+  ".deepagents",
+  ".goose",
+  ".codex",
+] as const;
+
+export function parseHarnessType(value: string | undefined, label = "--harness"): HarnessType | undefined {
+  if (value === undefined) return undefined;
+  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(
+    `${label} must be one of ${HARNESS_TYPES.join(", ")}.` +
+      (suggestion ? ` Did you mean ${suggestion}?` : ""),
+  );
+}
+
+export function nativeInstructionFile(harness: HarnessType): "CLAUDE.md" | "AGENTS.md" {
+  return harness === "claude-code" ? "CLAUDE.md" : "AGENTS.md";
+}
+
+export function translateTemplateFilesForHarness(
+  files: Record<string, string>,
+  harness: HarnessType,
+): Record<string, string> {
+  if (harness === "claude-code") return { ...files };
+
+  const translated: Record<string, string> = {};
+  for (const [rel, content] of Object.entries(files)) {
+    if (rel !== "CLAUDE.md") translated[rel] = content;
+  }
+  if (translated["AGENTS.md"] === undefined && files["CLAUDE.md"] !== undefined) {
+    translated["AGENTS.md"] = files["CLAUDE.md"];
+  }
+  const marker = NATIVE_TEMPLATE_MARKER[harness];
+  if (marker && translated[marker.path] === undefined) {
+    translated[marker.path] = marker.content;
+  }
+  return translated;
+}
+
+export function hasAgentMarker(dir: string): boolean {
+  return AGENT_MARKERS.some((marker) => existsSync(path.join(dir, marker)));
+}
+
+export function markerFolderRel(filePath: string): string | null {
+  const parts = filePath.split(/[\\/]+/).filter(Boolean);
+  if (parts.includes("node_modules")) return null;
+  const last = parts.at(-1);
+  if (last === "dharta.toml" || last === "CLAUDE.md") {
+    return parts.slice(0, -1).join(path.sep) || ".";
+  }
+  for (const marker of [".claude", ".opencode", ".deepagents", ".goose", ".codex"]) {
+    const index = parts.indexOf(marker);
+    if (index >= 0) return parts.slice(0, index).join(path.sep) || ".";
+  }
+  return null;
+}
+
+export function sniffHarnessType(dir: string): HarnessType {
+  if (presentIn(dir, "opencode")) return "opencode";
+  if (presentIn(dir, "deepagents")) return "deepagents";
+  if (presentIn(dir, "goose")) return "goose";
+  if (presentIn(dir, "claude-code")) return "claude-code";
+  if (presentIn(dir, "codex-cli")) return "codex-cli";
+  return "opencode";
+}
+
+export function readDeclaredHarnessType(manifestText: string): HarnessType | undefined {
+  let parsed: unknown;
+  try {
+    parsed = TOML.parse(manifestText);
+  } catch {
+    return undefined;
+  }
+  const table = (parsed as Record<string, unknown>).harness;
+  if (table === null || typeof table !== "object") return undefined;
+  const type = (table as Record<string, unknown>).type;
+  try {
+    return typeof type === "string" ? parseHarnessType(type, "[harness] type") : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function presentIn(dir: string, harness: HarnessType): boolean {
+  return HARNESS_MARKERS[harness].some((marker) => existsSync(path.join(dir, marker)));
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { main } from "./cli.js";
+export { buildContext } from "./context.js";
+export type { CliContext, CtxOverrides } from "./context.js";

package/src/login-offer.ts

@@ -0,0 +1,49 @@
+// RFC 0024 DEP-9 / D5: `dharta setup` is fully functional logged-out - it
+// writes local config only and reads no logged-in state. If you are not
+// logged in, it offers login ONCE at the end as the bridge to `dharta deploy`
+// (which does need auth). --login forces it; otherwise we only prompt an
+// interactive terminal. It never blocks setup.
+
+import { activeProfile } from "./config.js";
+import { login } from "./commands/login.js";
+
+export interface OfferLoginOptions {
+  force?: boolean; // --login
+  ask?: (q: string) => Promise<string>; // present only in an interactive TTY
+  log: (line: string) => void;
+  // seams (tests)
+  isLoggedIn?: () => Promise<boolean>;
+  runLogin?: () => Promise<void>;
+}
+
+export type OfferLoginOutcome = "logged-in" | "skipped" | "completed";
+
+export async function offerLogin(opts: OfferLoginOptions): Promise<OfferLoginOutcome> {
+  // Non-interactive and not forced: stay silent (don't even read the config).
+  if (!opts.force && !opts.ask) return "skipped";
+
+  const loggedIn = opts.isLoggedIn ?? defaultIsLoggedIn;
+  if (await loggedIn()) return "logged-in";
+
+  let go = opts.force ?? false;
+  if (!go && opts.ask) {
+    const a = (await opts.ask("You are not logged into Dharta. Log in now? (optional) [y/N]  ")).trim().toLowerCase();
+    go = a === "y" || a === "yes";
+  }
+  if (!go) {
+    opts.log("Setup is complete. You're not logged in - run `dharta login`, then `dharta deploy`.");
+    return "skipped";
+  }
+
+  await (opts.runLogin ?? (() => login({ log: opts.log }).then(() => undefined)))();
+  return "completed";
+}
+
+async function defaultIsLoggedIn(): Promise<boolean> {
+  try {
+    await activeProfile();
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/manifest.ts

@@ -0,0 +1,153 @@
+import TOML from "@iarna/toml";
+import { DEFAULT_CREATE_HARNESS, type HarnessType } from "./harnesses.js";
+
+export type DeployMethod = "git" | "folder";
+
+const DEPLOY_METHOD_PLACEHOLDER = '# deploy_method = "git" # set by `dharta setup`';
+
+// The scaffolded dharta.toml is self-documenting (RFC 0024 DEP-1/DEP-4):
+// every field is commented with its purpose and its alternatives, which
+// is the whole DX fix. TOML.stringify drops comments, so a fresh manifest
+// is written from this string template, and an edit to an existing one is
+// a surgical top-level-scalar patch that leaves the comments and [tables]
+// intact.
+
+export function renderManifest(o: {
+  name: string;
+  deploy: boolean;
+  deployMethod?: DeployMethod;
+  harness?: HarnessType;
+  harnessVersion?: string;
+}): string {
+  const harness = o.harness ?? DEFAULT_CREATE_HARNESS;
+  const versionExample = harnessVersionExample(harness);
+  const versionLine = o.harnessVersion
+    ? `version = ${JSON.stringify(o.harnessVersion)}`
+    : `# version = ${JSON.stringify(versionExample)}`;
+  return [
+    "# --- Identity -------------------------------------------------------------",
+    "# Display name (1-100 characters). Dharta derives the deploy slug from this",
+    "# name (for example, Support Bot -> support-bot); that slug must be unique",
+    "# within your org. Changing the name so its slug changes targets a different agent.",
+    "# Each deploy creates a new immutable release; earlier releases remain available.",
+    `name = ${JSON.stringify(o.name)}`,
+    "",
+    "# Deploy gate. Only agents with deploy = true ship on `dharta deploy` /",
+    "# `git push dharta`. Absent or false = configured but not deployed.",
+    `deploy = ${o.deploy}`,
+    "",
+    "# How this agent is deployed. `git` pushes the containing repo while",
+    "# selecting this folder; `folder` uploads this folder directly.",
+    o.deployMethod
+      ? `deploy_method = ${JSON.stringify(o.deployMethod)}`
+      : DEPLOY_METHOD_PLACEHOLDER,
+    "",
+    "# --- Build ----------------------------------------------------------------",
+    "# OMIT this whole section for a harness-only agent (for example CLAUDE.md,",
+    "# AGENTS.md + .opencode/, .deepagents/, .goose/, or .codex/) - Dharta serves it as-is,",
+    "# no build step.",
+    '#   "python" - Python project; Dharta builds it (set entry_point below)',
+    '#   "node"   - Node project; Dharta builds it',
+    '# buildpack = "python"',
+    "",
+    '# Import path "module:attribute" to your app object. Required ONLY when',
+    "# buildpack is set; omit for harness-only agents.",
+    '# entry_point = "app:app"',
+    "",
+    "# --- Harness ---------------------------------------------------------------",
+    "# The agent runtime this agent runs on. `type` is fixed for the life of the",
+    "# agent (switching harness = a new agent). Supported types today:",
+    "# claude-code, opencode, deepagents, goose, codex-cli.",
+    "# `version` is optional: a range resolves to the latest matching version Dharta",
+    "# supports at deploy time; omit it for the curated default; pin an exact",
+    "# version only when you need determinism (`dharta deploy` checks it).",
+    "[harness]",
+    `type = ${JSON.stringify(harness)}`,
+    versionLine,
+    "",
+    "# --- Environment (declare-or-bind) -----------------------------------------",
+    "# Names this agent needs. Bind locally in .env, in prod via `dharta env set`.",
+    "# A required var with no prod binding fails the build.",
+    "[env]",
+    '# SUPPORT_DB_URL = { required = false, description = "Support database DSN" }',
+    "",
+    "# --- Environment setup -----------------------------------------------------",
+    "# A Bash setup script run once per cold start, before the agent, to install",
+    "# what the base image lacks. Use user-space installs: `pip install` and",
+    "# `npm i -g` are auto-configured (pip --user) to persist under ~/.local, so",
+    "# no --user flag is needed. apt/system packages are NOT available",
+    "# here (they need a custom image - a higher tier). The script is validated at",
+    "# deploy (`bash -n`); a syntax error fails the deploy, not your users.",
+    "#   network: none | trusted | full (default) | custom. Only `full` is enforced",
+    "#   today (every agent has open egress); the others arrive with a later phase.",
+    "# [environment]",
+    '# setup = "scripts/setup.sh"',
+    '# network = "full"',
+    "",
+  ].join("\n");
+}
+
+function harnessVersionExample(harness: HarnessType): string {
+  switch (harness) {
+    case "claude-code":
+      return "2";
+    case "opencode":
+      return "1";
+    case "deepagents":
+      return "0.1.28";
+    case "goose":
+      return "1.39.0";
+    case "codex-cli":
+      return "0.133.0";
+  }
+}
+
+// Flip or insert a top-level scalar WITHOUT disturbing comments or
+// [tables]: replace it in place if present (anchored to a line, so a
+// commented `# name = ...` is never matched), else insert before the
+// first table so it stays a top-level key rather than nesting under a
+// section. `key` is always a literal we control
+// ("name"/"deploy"/"deploy_method").
+export function patchScalar(src: string, key: string, literal: string): string {
+  const re = new RegExp(`^(\\s*${key}\\s*=).*$`, "m");
+  const tbl = src.search(/^\s*\[/m);
+  const top = tbl >= 0 ? src.slice(0, tbl) : src;
+  const rest = tbl >= 0 ? src.slice(tbl) : "";
+  if (re.test(top)) return top.replace(re, `$1 ${literal}`) + rest;
+  const line = `${key} = ${literal}\n`;
+  if (tbl >= 0) return src.slice(0, tbl) + line + src.slice(tbl);
+  return (src.endsWith("\n") ? src : src + "\n") + line;
+}
+
+function hasTopLevelScalar(src: string, key: string): boolean {
+  const tbl = src.search(/^\s*\[/m);
+  const top = tbl >= 0 ? src.slice(0, tbl) : src;
+  return new RegExp(`^\\s*${key}\\s*=`, "m").test(top);
+}
+
+// Set identity/deploy configuration on an existing manifest, preserving its
+// comments and tables, then round-trip through the parser so a broken edit
+// fails loud instead of writing an invalid manifest.
+export function patchManifest(
+  src: string,
+  o: { name?: string; deploy?: boolean; deployMethod?: DeployMethod },
+): string {
+  let out = src;
+  if (o.name !== undefined) out = patchScalar(out, "name", JSON.stringify(o.name));
+  if (o.deploy !== undefined) out = patchScalar(out, "deploy", String(o.deploy));
+  if (o.deployMethod !== undefined) {
+    const literal = JSON.stringify(o.deployMethod);
+    // `dharta create` leaves this decision visibly unset for setup. Activate
+    // that generated placeholder in place so the field stays next to its
+    // explanation; arbitrary user comments remain untouched.
+    if (hasTopLevelScalar(out, "deploy_method")) {
+      out = patchScalar(out, "deploy_method", literal);
+    } else if (out.includes(DEPLOY_METHOD_PLACEHOLDER)) {
+      out = out.replace(DEPLOY_METHOD_PLACEHOLDER, `deploy_method = ${literal}`);
+    } else {
+      out = patchScalar(out, "deploy_method", literal);
+    }
+  }
+  TOML.parse(out); // throws on an invalid result
+  return out;
+}

package/src/money.ts

@@ -0,0 +1,15 @@
+export function parseDollarAmountToCents(value: string, flag: string): number {
+  const trimmed = value.trim();
+  const match = trimmed.match(/^(?:(\d+)(?:\.(\d{1,2}))?|\.(\d{1,2}))$/);
+  if (!match) throw amountError(flag);
+
+  const dollars = match[1] ? Number(match[1]) : 0;
+  const centsPart = match[2] ?? match[3] ?? "";
+  const cents = dollars * 100 + Number(centsPart.padEnd(2, "0"));
+  if (!Number.isSafeInteger(cents) || cents <= 0) throw amountError(flag);
+  return cents;
+}
+
+function amountError(flag: string): Error {
+  return new Error(`${flag} must be a dollar amount greater than 0 with at most two decimal places.`);
+}

package/src/output.ts

@@ -0,0 +1,22 @@
+// Output helpers. Tiny on purpose — the CLI's UX is "narrate one line
+// per row + occasional table"; pulling in cli-table or chalk costs
+// more than it buys at this scale.
+
+export function table(rows: Array<Record<string, string>>): string {
+  if (rows.length === 0) return "";
+  const cols = Object.keys(rows[0]);
+  const widths = cols.map((c) =>
+    Math.max(c.length, ...rows.map((r) => (r[c] ?? "").length)),
+  );
+  const pad = (s: string, w: number) => s + " ".repeat(Math.max(0, w - s.length));
+  const header = cols.map((c, i) => pad(c, widths[i])).join("  ");
+  const divider = widths.map((w) => "-".repeat(w)).join("  ");
+  const body = rows
+    .map((r) => cols.map((c, i) => pad(r[c] ?? "", widths[i])).join("  "))
+    .join("\n");
+  return `${header}\n${divider}\n${body}`;
+}
+
+export function fmtTs(ts: string | null | undefined): string {
+  return ts ?? "—";
+}

package/src/runtime.ts

@@ -0,0 +1,127 @@
+// Runtime bootstrap for `dharta dev` (RFC 0013 CLI-3, decision D2): the
+// harness-adapter kernel lives in the Python `dharta-runtime` package,
+// single-sourced with production. The CLI resolves it via uv with a
+// version pin that ships inside each CLI release, so CLI and runtime
+// version as a pair. DHARTA_RUNTIME is the escape hatch (point it at a
+// checkout or an executable). Zero Python is ever visible on the happy
+// path; every failure prints the one remedial command.
+
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { spawn } from "node:child_process";
+
+// Ships with the CLI release; bump together with dharta-runtime.
+export const DHARTA_RUNTIME_PIN = "0.6.77";
+
+export const UV_INSTALL_HINT =
+  "Install uv first:  curl -LsSf https://astral.sh/uv/install.sh | sh  (or: brew install uv)\n" +
+  "Then re-run dharta dev. To use a local checkout instead, set DHARTA_RUNTIME=/path/to/dharta-runtime.";
+
+export interface RuntimeCommand {
+  // argv prefix that launches dharta-runtime; callers append subcommand
+  // args (e.g. ["serve", "--port", "4001"]).
+  command: string[];
+  source: "env-executable" | "env-checkout" | "uv";
+  description: string;
+}
+
+export interface RuntimeResolveOptions {
+  env?: NodeJS.ProcessEnv;
+  commandExists?: (cmd: string) => Promise<boolean>;
+}
+
+// Resolve how to launch dharta-runtime. Throws with remedial guidance —
+// never a stack trace — when the bootstrap can't work.
+export async function resolveRuntime(
+  opts: RuntimeResolveOptions = {},
+): Promise<RuntimeCommand> {
+  const env = opts.env ?? process.env;
+  const exists = opts.commandExists ?? commandOnPath;
+
+  const override = env.DHARTA_RUNTIME;
+  if (override) {
+    const stat = await fs.stat(override).catch(() => null);
+    if (!stat) {
+      throw new Error(
+        `DHARTA_RUNTIME points at ${override}, which does not exist. ` +
+          "Unset it to use the pinned runtime, or point it at a dharta-runtime checkout or executable.",
+      );
+    }
+    if (stat.isDirectory()) {
+      if (!(await exists("uv"))) {
+        throw new Error(`DHARTA_RUNTIME is a checkout, which needs uv to run.\n${UV_INSTALL_HINT}`);
+      }
+      return {
+        command: ["uv", "run", "--project", override, "dharta-runtime"],
+        source: "env-checkout",
+        description: `checkout at ${override} (DHARTA_RUNTIME)`,
+      };
+    }
+    return {
+      command: [override],
+      source: "env-executable",
+      description: `executable ${override} (DHARTA_RUNTIME)`,
+    };
+  }
+
+  // Check for the binary we actually launch (uvx ships with uv, but a
+  // partial install would otherwise surface as a raw spawn ENOENT).
+  if (!(await exists("uvx"))) {
+    throw new Error(`dharta dev needs uv to bootstrap the agent runtime.\n${UV_INSTALL_HINT}`);
+  }
+  return {
+    // uvx resolves and caches the pinned package on first use — the
+    // "install" step the user never sees.
+    command: ["uvx", "--from", `dharta-runtime==${DHARTA_RUNTIME_PIN}`, "dharta-runtime"],
+    source: "uv",
+    description: `dharta-runtime ${DHARTA_RUNTIME_PIN} via uv`,
+  };
+}
+
+// `which`-equivalent: scan PATH for an executable, returning every hit
+// in order. Used both for uv detection and the doctor's PATH-shadow
+// check (a stale pip-installed `dharta` shadowing this CLI). On Windows
+// the PATHEXT suffixes apply and the executable bit is meaningless.
+export async function whichAll(
+  cmd: string,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<string[]> {
+  const dirs = (env.PATH ?? "").split(path.delimiter).filter(Boolean);
+  const win = process.platform === "win32";
+  const suffixes = win
+    ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").map((s) => s.toLowerCase())
+    : [""];
+  const hits: string[] = [];
+  for (const dir of dirs) {
+    for (const suffix of suffixes) {
+      const candidate = path.join(dir, cmd + suffix);
+      try {
+        await fs.access(candidate, win ? fs.constants.F_OK : fs.constants.X_OK);
+        hits.push(candidate);
+        break;
+      } catch {
+        // not here
+      }
+    }
+  }
+  return hits;
+}
+
+async function commandOnPath(cmd: string): Promise<boolean> {
+  return (await whichAll(cmd)).length > 0;
+}
+
+// Spawn the runtime with the resolved command + args, inheriting stdio
+// by default. The error path names the escape hatch.
+export function spawnRuntime(
+  runtime: RuntimeCommand,
+  args: string[],
+  options: { cwd?: string; env?: NodeJS.ProcessEnv; stdio?: "inherit" | "pipe" } = {},
+): ReturnType<typeof spawn> {
+  const [cmd, ...prefix] = runtime.command;
+  return spawn(cmd, [...prefix, ...args], {
+    cwd: options.cwd,
+    env: options.env ?? process.env,
+    stdio: options.stdio ?? "inherit",
+  });
+}

package/src/scaffold.ts

@@ -0,0 +1,102 @@
+// Template scaffolding, extracted from the old `dharta init` (RFC 0024 DEP-4c,
+// B.1): `dharta setup` reuses this to lay down a starter agent in a brand-new
+// folder. Unlike init it does NOT git-init or commit (setup prompts for git,
+// `dharta deploy` makes the first commit), does NOT require an empty directory
+// (setup configures folders that may already have files), never clobbers an
+// existing file, and skips dharta.toml - setup writes the self-documenting one.
+
+import { existsSync, promises as fs } from "node:fs";
+import * as path from "node:path";
+import { resolveTemplates } from "./templates.js";
+import { closestChoice, normalizeNonBlank } from "./validators.js";
+import {
+  DEFAULT_CREATE_HARNESS,
+  nativeInstructionFile,
+  translateTemplateFilesForHarness,
+  type HarnessType,
+} from "./harnesses.js";
+
+export interface ScaffoldOptions {
+  template?: string; // default "blank"
+  harness?: HarnessType; // default "claude-code"
+  baseUrl: string;
+  fetchImpl?: typeof fetch;
+  log?: (line: string) => void;
+}
+
+export interface ScaffoldResult {
+  template: string;
+  harness: HarnessType;
+  instructionFile: "CLAUDE.md" | "AGENTS.md";
+  files: string[]; // newly written, relative to target
+  source: "control-plane" | "bundled";
+}
+
+export async function scaffoldTemplate(target: string, opts: ScaffoldOptions): Promise<ScaffoldResult> {
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const templateKey = opts.template === undefined ? "blank" : normalizeNonBlank(opts.template, "--template");
+  const harness = opts.harness ?? DEFAULT_CREATE_HARNESS;
+
+  const resolved = await resolveTemplates(opts.baseUrl, opts.fetchImpl);
+  if (resolved.source === "bundled") {
+    log("Could not reach the template service - using the bundled template set.");
+  }
+
+  const template = resolved.templates.find((t) => t.key === templateKey);
+  if (!template) {
+    const keys = resolved.templates.map((t) => t.key);
+    const suggestion = closestChoice(templateKey, keys);
+    throw new Error(
+      `Unknown template '${templateKey}'. Available: ${keys.join(", ")}.` +
+        (suggestion ? ` Did you mean ${suggestion}?` : ""),
+    );
+  }
+
+  await fs.mkdir(target, { recursive: true });
+  const written: string[] = [];
+  const files = translateTemplateFilesForHarness(template.files, harness);
+  for (const [rel, content] of Object.entries(files)) {
+    if (rel === "dharta.toml") continue; // setup owns identity (the commented manifest)
+    // Template files come from server JSON - never let a hostile path
+    // (../..) or non-string content escape the target directory.
+    const dest = path.resolve(target, rel);
+    if (dest !== target && !dest.startsWith(target + path.sep)) {
+      throw new Error(
+        `Template file path escapes the target directory: ${rel}. ` +
+          "Re-run with a bundled template (--template blank) and report this.",
+      );
+    }
+    if (typeof content !== "string") {
+      throw new Error(`Template file ${rel} has non-text content. Re-run with --template blank and report this.`);
+    }
+    if (existsSync(dest)) continue; // never clobber the user's own file
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    await fs.writeFile(dest, content);
+    written.push(rel);
+  }
+
+  // .env binds the [env] declarations locally and must never be committed.
+  await ensureGitignoreHasDotEnv(target);
+
+  return {
+    template: template.key,
+    harness,
+    instructionFile: nativeInstructionFile(harness),
+    files: written,
+    source: resolved.source,
+  };
+}
+
+async function ensureGitignoreHasDotEnv(target: string): Promise<void> {
+  const file = path.join(target, ".gitignore");
+  let existing = "";
+  try {
+    existing = await fs.readFile(file, "utf8");
+  } catch {
+    // no .gitignore yet
+  }
+  const lines = existing.split("\n").map((l) => l.trim());
+  if (lines.includes(".env")) return;
+  const next = existing.length > 0 && !existing.endsWith("\n") ? `${existing}\n.env\n` : `${existing}.env\n`;
+  await fs.writeFile(file, next);
+}