jules-orchestrator-kit 0.52.8 → 0.54.0

package/bin/init.js

@@ -8,6 +8,8 @@ import readline from "node:readline/promises";
 import zlib from "node:zlib";
 import crypto from "node:crypto";
 import { resolveProjectCommands } from "../scripts/command-resolver.mjs";
+import { KIT_VERSION } from "../src/version.mjs";
+import { detectStack } from "../src/config.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -52,7 +54,7 @@ Options:
   process.exit(0);
 }
 
-console.log("\n🚀 Initializing Google Jules Orchestration Kit...\n");
+console.log("\n🚀 Initializing agent orchestrator kit...\n");
 console.log(`📁 Target Directory: ${targetDir}`);
 if (isForce) console.log("⚠️ Force mode enabled (existing files will be overwritten).");
 
@@ -129,65 +131,62 @@ for (const item of scaffolded.created) {
 
 const agentDir = path.join(targetDir, ".agent");
 
-// Scaffold .agent/jules.yml
+// Scaffold the manifest pair.
+//
+// This entry point used to hand-roll a thinner `.agent/jules.yml` while
+// `agentctl init` wrote a `.agent/config.yml` the runtime actually reads, so
+// which of the two scaffolders you happened to run decided whether the
+// repository had a provider, a tier and a verification profile at all. Both
+// now go through `planInit`.
+const { planInit } = await import("../src/wizard-init.mjs");
+const initPlan = planInit(targetDir, {
+  testCmd: detected.testCmd,
+  buildCmd: detected.buildCmd,
+  lintCmd: detected.lintCmd,
+  baseBranch: answerBranchVal || process.env.BASE_BRANCH || undefined,
+});
+
+const configPath = path.join(agentDir, "config.yml");
+if (!fs.existsSync(configPath) || isForce) {
+  fs.writeFileSync(configPath, initPlan.configYaml, "utf-8");
+  console.log(`✅ Created: .agent/config.yml (provider: ${initPlan.provider}, profile: ${initPlan.profile})`);
+}
+
 const yamlConfigPath = path.join(agentDir, "jules.yml");
 if (!fs.existsSync(yamlConfigPath) || isForce) {
-  const yamlContent = `# Google Jules Repository Configuration (Version 2)
-version: 2
-test_cmd: "${detected.testCmd || "npm test"}"
-build_cmd: "${detected.buildCmd || "npm run build"}"
-forbidden_paths: [".github/**", "**/.env*", "**/*.pem", "**/lock-manager*"]
-`;
-  fs.writeFileSync(yamlConfigPath, yamlContent, "utf-8");
+  fs.writeFileSync(yamlConfigPath, initPlan.julesYaml, "utf-8");
   console.log("✅ Created: .agent/jules.yml");
 }
 
-// Scaffold .github/workflows/jules-audit.yml
-const githubWorkflowsDir = path.join(targetDir, ".github/workflows");
-const auditWfSource = path.join(kitRoot, ".github/workflows/jules-audit.yml");
-const auditWfTarget = path.join(githubWorkflowsDir, "jules-audit.yml");
-
-if (fs.existsSync(auditWfSource)) {
-  if (!fs.existsSync(githubWorkflowsDir)) {
-    fs.mkdirSync(githubWorkflowsDir, { recursive: true });
-  }
-  if (!fs.existsSync(auditWfTarget) || isForce) {
-    fs.copyFileSync(auditWfSource, auditWfTarget);
-    console.log("✅ Added GitHub Actions workflow: .github/workflows/jules-audit.yml");
-  }
+// 3b. Generate a CI gate workflow for *this* repository's stack.
+//
+// This used to copy the kit's own audit workflow verbatim: a nine-way Node
+// matrix running `npm install`, `npm test` and a script path that exists only
+// inside the kit. In a Rust, Python or Go repository it was red on the first
+// push for reasons that had nothing to do with that repository's code.
+const { writeCiWorkflow } = await import("../src/ci-templates.mjs");
+const ciRes = writeCiWorkflow(targetDir, {
+  target: "github",
+  force: isForce,
+  // `resolveProjectCommands` reports a human-readable source string; the CI
+  // generator needs the machine-readable stack id.
+  stack: detectStack(targetDir),
+  config: { baseBranch: answerBranchVal || process.env.BASE_BRANCH || "main" },
+  version: KIT_VERSION,
+});
+if (ciRes.ok && ciRes.written) {
+  console.log(`✅ Generated CI gate for '${ciRes.stack}': ${ciRes.file}`);
+} else if (ciRes.ok) {
+  console.log(`↩️  Kept existing ${ciRes.file} (use --force to regenerate)`);
 }
 
-// 4. Copy scripts/ directory with PER-FILE existence guard
-const targetScriptsDir = path.join(targetDir, "scripts");
-if (!fs.existsSync(targetScriptsDir)) {
-  fs.mkdirSync(targetScriptsDir, { recursive: true });
-}
-
-const sourceScriptsDir = path.join(kitRoot, "scripts");
-let copiedCount = 0;
-let skippedCount = 0;
-
-if (fs.existsSync(sourceScriptsDir)) {
-  const scriptFiles = fs.readdirSync(sourceScriptsDir);
-  const excludeFiles = new Set(["release.mjs"]);
-  scriptFiles.forEach((file) => {
-    if (excludeFiles.has(file)) return;
-    const srcFile = path.join(sourceScriptsDir, file);
-    const destFile = path.join(targetScriptsDir, file);
-    if (!fs.existsSync(destFile) || isForce) {
-      fs.copyFileSync(srcFile, destFile);
-      try {
-        fs.chmodSync(destFile, 0o755);
-      } catch (err) {
-        console.warn(`⚠️ Could not set executable permissions on ${file}:`, err.message);
-      }
-      copiedCount++;
-    } else {
-      skippedCount++;
-    }
-  });
-  console.log(`✅ Copied ${copiedCount} orchestration scripts to ./scripts/ (${skippedCount} skipped, use --force to overwrite)`);
-}
+// 4. The kit's own scripts/ directory is NOT copied here.
+//
+// It used to be — twenty orchestration scripts dropped into the target repo's
+// scripts/ folder, where they collided with the project's own files, aged
+// independently of the installed kit, and duplicated commands that `agentctl`
+// already exposes. Everything they did is reachable through the CLI, which is
+// what the injected package.json entries below point at.
 
 // 5. Optionally inject scripts into target package.json if present
 const targetPkgPath = path.join(targetDir, "package.json");
@@ -196,18 +195,22 @@ if (fs.existsSync(targetPkgPath) && targetDir !== kitRoot) {
     const pkg = JSON.parse(fs.readFileSync(targetPkgPath, "utf-8"));
     pkg.scripts = pkg.scripts || {};
     let updated = false;
-    const julesScripts = {
-      "jules:dispatch": "agentctl dispatch",
-      "jules:queue": "agentctl queue",
-      "jules:create": "agentctl task create",
-      "jules:status": "agentctl status",
-      "jules:audit": "agentctl gate",
-      "jules:scan": "agentctl scan",
-      "jules:swarm": "agentctl swarm",
-      "jules:nightly": "agentctl clean"
+    // Vendor-neutral names: these run `agentctl`, which dispatches to whichever
+    // provider the repository selected. `jules:*` entries from an older init are
+    // left in place — removing scripts a project may reference in CI is not
+    // this command's business.
+    const agentScripts = {
+      "agent:gate": "agentctl check",
+      "agent:dispatch": "agentctl dispatch",
+      "agent:queue": "agentctl queue",
+      "agent:create": "agentctl task create",
+      "agent:status": "agentctl status",
+      "agent:doctor": "agentctl doctor",
+      "agent:swarm": "agentctl swarm",
+      "agent:clean": "agentctl clean"
     };
 
-    for (const [key, val] of Object.entries(julesScripts)) {
+    for (const [key, val] of Object.entries(agentScripts)) {
       if (!pkg.scripts[key] || isForce) {
         pkg.scripts[key] = val;
         updated = true;
@@ -216,7 +219,7 @@ if (fs.existsSync(targetPkgPath) && targetDir !== kitRoot) {
 
     if (updated) {
       fs.writeFileSync(targetPkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
-      console.log("✅ Added Jules commands to package.json");
+      console.log("✅ Added agent:* commands to package.json");
     }
   } catch (err) {
     console.warn("⚠️ Failed to inject helper scripts into target package.json:", err.message);
@@ -229,7 +232,7 @@ if (scaffolded.gitignore.length > 0) {
   console.log(`✅ Added ${scaffolded.gitignore.length} runtime state entries to .gitignore`);
 }
 
-console.log("\n🎉 Google Jules Orchestration Kit successfully initialized!");
+console.log("\n🎉 Agent orchestrator kit initialized.");
 
 // 6. Generate Encoded Workspace Manifest (JULES_WEB_SETUP.md)
 const agentState = {
@@ -272,13 +275,23 @@ ${payloadToken}
 
 fs.writeFileSync(path.join(targetDir, ".agent", "JULES_WEB_SETUP.md"), setupMdContent, "utf-8");
 
-console.log("\n🔗 Google Jules Setup Complete");
-console.log("  Your local agent configurations are ready.");
-console.log(`  👉 Encoded Workspace Manifest: \x1b[36m${payloadToken}\x1b[0m`);
-console.log("\n  (A backup was written to .agent/JULES_WEB_SETUP.md)");
+// The encoded manifest is a Google Jules convenience — it pastes the detected
+// workspace into the Jules web UI. It is written unconditionally because it
+// costs nothing and a repository can change provider later, but it is only
+// *announced* when Jules is the provider this repo actually selected;
+// otherwise it is one more Google-specific string in the way of someone who
+// chose a different agent.
+if (initPlan.provider === "jules") {
+  console.log("\n🔗 Google Jules workspace manifest");
+  console.log(`  👉 Paste into the Jules web UI: \x1b[36m${payloadToken}\x1b[0m`);
+  console.log("  (A copy was written to .agent/JULES_WEB_SETUP.md)");
+} else {
+  console.log(`\n  Provider: ${initPlan.provider}. A Google Jules workspace manifest was also written to .agent/JULES_WEB_SETUP.md if you ever switch.`);
+}
 console.log("\nNext Steps:");
-console.log("  1. See official documentation at https://jules.google");
-console.log("  2. Set environment variables: JULES_REPO=\"owner/repo\"");
-console.log("  3. Scaffold a new task: npm run jules:create \"My Feature\"");
-console.log("  4. Dispatch the queue:  npm run jules:queue");
-console.log("  5. Run pre-merge audit: npm run jules:audit\n");
+console.log("  1. Pick a provider:      agentctl providers   (jules | claude-code | codex | gemini)");
+console.log("  2. Pick a gate depth:    agentctl profile --list   (minimal | standard | max)");
+console.log("  3. Scaffold a task:      agentctl task create");
+console.log("  4. Dispatch the queue:   agentctl queue");
+console.log("  5. Run the pre-merge gate: agentctl check\n");
+console.log("  Not sure? Run `agentctl` with no arguments — it reads the repo and names one step.\n");

package/index.mjs

@@ -36,6 +36,16 @@ export {
   parseRetryAfter,
 } from "./src/provider.mjs";
 export { resolveRoutedProvider } from "./src/router.mjs";
+export {
+  PROVIDER_DESCRIPTORS,
+  PROVIDER_PREFERENCE,
+  whichBinary,
+  probeProvider,
+  detectAvailableProviders,
+  suggestProvider,
+} from "./src/provider-readiness.mjs";
+export { ENV_ALIASES, applyEnvAliases, describeEnvVar } from "./src/env-aliases.mjs";
+export { PROFILE_NAMES, PROFILE_DESCRIPTIONS, buildProfileStages, describeProfilePlan } from "./src/profiles.mjs";
 export {
   detectPolyglotStack,
   resolveWorkspaceBoundary,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.52.8",
-  "description": "Zero-dependency safety gatekeeper, test oracle generator, and multi-agent coordination protocol for Google Jules (jules) autonomous agents.",
+  "version": "0.54.0",
+  "description": "Zero-dependency safety gatekeeper, test oracle generator, and multi-agent coordination protocol for autonomous coding agents — Google Jules, Claude Code, Codex and Gemini CLI.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/FullThrottle83/jules-orchestrator-kit.git"
@@ -63,6 +63,9 @@
   "keywords": [
     "jules",
     "google-jules",
+    "claude-code",
+    "codex",
+    "gemini-cli",
     "ai-agent",
     "orchestrator",
     "mcp",

package/scripts/jules-create.mjs

@@ -4,25 +4,14 @@
  * Quick task file creator for .agent/jules-queue/.
  */
 
-import { writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { getQueueDir } from "../src/state.mjs";
+import { runTaskCreateWizard } from "../src/wizard-task.mjs";
 
-const taskTitle = process.argv[2] || "New Task";
-const queueDir = getQueueDir();
-const safeTitle = taskTitle.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
-const filepath = join(queueDir, `TASK-${Date.now()}-${safeTitle}.md`);
-
-const boilerplate = `# ${taskTitle}
-
-## Objective
-[Describe task goal]
-`;
+const prompt = process.argv.slice(2).join(" ").trim();
 
 try {
-  writeFileSync(filepath, boilerplate, "utf-8");
-  console.log(`[Shim] Scaffolded new task: ${filepath}`);
+  const result = await runTaskCreateWizard(process.cwd(), prompt ? { prompt } : {});
+  console.log(`✅ Scaffolded task envelope: ${result.taskFile}`);
 } catch (err) {
-  console.error(`[Shim] Failed to create task: ${err.message}`);
+  console.error(`❌ Failed to create task: ${err.message}`);
   process.exit(1);
 }

package/scripts/jules-patch.mjs

@@ -4,20 +4,28 @@
  * Session patch fetching utility.
  */
 
-export async function fetchSessionPatch(sessionId, _options = {}) {
+import { extractSessionPatch } from "../src/session-ops.mjs";
+
+export async function fetchSessionPatch(sessionId, options = {}) {
   if (!sessionId || typeof sessionId !== "string") {
     throw new Error("Session ID is required.");
   }
-  return {
-    sessionId,
-    state: "COMPLETED",
-    title: "Patch Session",
-    hasPatch: false,
-    diff: "",
-  };
+  return await extractSessionPatch(sessionId, options);
 }
 
 if (process.argv[1] && process.argv[1].endsWith("jules-patch.mjs")) {
-  console.log("Patch fetch completed.");
-  process.exit(0);
+  const sessionId = process.argv[2];
+  if (!sessionId) {
+    console.error("Usage: node scripts/jules-patch.mjs <sessionId>");
+    process.exit(1);
+  }
+  fetchSessionPatch(sessionId)
+    .then((res) => {
+      console.log(`Patch fetch completed for ${sessionId}: ${res.patch ? "Patch found" : "No patch"}`);
+      process.exit(0);
+    })
+    .catch((err) => {
+      console.error(`Patch fetch failed: ${err.message}`);
+      process.exit(1);
+    });
 }

package/scripts/stale-base-check.mjs

@@ -8,7 +8,7 @@ const baseBranch = process.env.BASE_BRANCH || "main";
 
 try {
   const resolvedBase = resolveBase(root, baseBranch);
-  const behindStr = git(["rev-list", "--count", `${resolvedBase}..HEAD`], { cwd: root, ignoreError: true });
+  const behindStr = git(["rev-list", "--count", `HEAD..${resolvedBase}`], { cwd: root, ignoreError: true });
   const behindCount = parseInt(behindStr || "0", 10);
 
   console.log(`[stale-base-check] Branch HEAD is ${behindCount} commits behind ${resolvedBase} (max allowed: ${maxBehind}).`);

package/src/ci-templates.mjs

@@ -0,0 +1,199 @@
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+/**
+ * Generate a CI job that runs the kit's gate, with the toolchain the detected
+ * stack actually needs.
+ *
+ * `init` used to copy this repository's *own* audit workflow into whatever
+ * repository it was scaffolding: a nine-way Node matrix that ran `npm install`,
+ * `npm test` and a script path that only exists here. Dropped into a Rust or
+ * Python repository it was red on the first push, for reasons that had nothing
+ * to do with that repository's code. A generated workflow is the only kind that
+ * can be correct in a repository the kit has never seen.
+ */
+
+export const CI_TARGETS = ["github", "gitlab"];
+
+/**
+ * Toolchain setup per stack, expressed once and rendered per CI target.
+ *
+ * Node is installed unconditionally and is not in this table: `agentctl` is a
+ * Node CLI, so the runner needs it regardless of what the project is written
+ * in. These are the *additional* runtimes.
+ *
+ * Actions are referenced by major version tag rather than by commit SHA. A
+ * generated file is a starting point the repository owns from the moment it is
+ * written, and pinning a SHA the owner did not choose ages into a silent
+ * security debt they never agreed to — the header tells them to pin.
+ */
+const STACK_TOOLCHAINS = {
+  python: { label: "Python 3.x", gh: [{ name: "Set up Python", uses: "actions/setup-python@v5", with: { "python-version": "3.x" } }], gl: "python:3" },
+  django: { label: "Python 3.x", gh: [{ name: "Set up Python", uses: "actions/setup-python@v5", with: { "python-version": "3.x" } }], gl: "python:3" },
+  go: { label: "Go (stable)", gh: [{ name: "Set up Go", uses: "actions/setup-go@v5", with: { "go-version": "stable" } }], gl: "golang:latest" },
+  cargo: { label: "Rust (preinstalled on hosted runners)", gh: [], gl: "rust:latest" },
+  maven: { label: "Temurin JDK 21", gh: [{ name: "Set up Java", uses: "actions/setup-java@v4", with: { distribution: "temurin", "java-version": "21" } }], gl: "maven:3-eclipse-temurin-21" },
+  gradle: { label: "Temurin JDK 21", gh: [{ name: "Set up Java", uses: "actions/setup-java@v4", with: { distribution: "temurin", "java-version": "21" } }], gl: "gradle:jdk21" },
+  dotnet: { label: ".NET 8", gh: [{ name: "Set up .NET", uses: "actions/setup-dotnet@v4", with: { "dotnet-version": "8.0.x" } }], gl: "mcr.microsoft.com/dotnet/sdk:8.0" },
+  php: { label: "PHP (preinstalled on hosted runners)", gh: [], gl: "php:8" },
+  laravel: { label: "PHP (preinstalled on hosted runners)", gh: [], gl: "php:8" },
+  wordpress: { label: "PHP (preinstalled on hosted runners)", gh: [], gl: "php:8" },
+  bundler: { label: "Ruby (preinstalled on hosted runners)", gh: [], gl: "ruby:3" },
+  mix: { label: "Elixir — add your own setup step", gh: [], gl: "elixir:latest" },
+  bun: { label: "Bun", gh: [{ name: "Set up Bun", uses: "oven-sh/setup-bun@v2" }], gl: "oven/bun:latest" },
+  deno: { label: "Deno", gh: [{ name: "Set up Deno", uses: "denoland/setup-deno@v2", with: { "deno-version": "v2.x" } }], gl: "denoland/deno:latest" },
+  flutter: { label: "Flutter — add your own setup step", gh: [], gl: "ghcr.io/cirruslabs/flutter:stable" },
+  dart: { label: "Dart — add your own setup step", gh: [], gl: "dart:stable" },
+  swift: { label: "Swift — add your own setup step", gh: [], gl: "swift:latest" },
+  cmake: { label: "CMake/CTest (preinstalled on hosted runners)", gh: [], gl: "gcc:latest" },
+};
+
+/** Renders one GitHub Actions step block at four-space indentation. */
+function renderGhStep(step) {
+  const lines = [`      - name: ${step.name}`, `        uses: ${step.uses}`];
+  if (step.with) {
+    lines.push(`        with:`);
+    for (const [k, v] of Object.entries(step.with)) lines.push(`          ${k}: "${v}"`);
+  }
+  return lines.join("\n");
+}
+
+const HEADER = (stack, version) =>
+  `# Generated by jules-orchestrator-kit v${version} for a '${stack}' project.
+#
+# This file is yours now — edit it freely. Two things worth doing before you
+# rely on it:
+#   1. Pin each third-party action to a commit SHA (a tag can be moved).
+#   2. Check that the runtime versions below match what the project targets.
+#
+# Regenerate with: agentctl ci init --force
+`;
+
+/**
+ * @param {object} opts
+ * @param {string} opts.target - "github" | "gitlab"
+ * @param {{stack: string}} opts.stack - result of detectStack()
+ * @param {object} [opts.config] - loaded config, for base_branch
+ * @param {string} [opts.version]
+ * @returns {{ file: string, content: string, setupSummary: string }}
+ */
+export function buildCiWorkflow(opts = {}) {
+  const target = CI_TARGETS.includes(opts.target) ? opts.target : "github";
+  const stackId = opts.stack?.stack || "unknown";
+  const base = opts.config?.baseBranch || "main";
+  const version = opts.version || "0";
+  const toolchain = STACK_TOOLCHAINS[stackId] || null;
+  const setupSummary = toolchain ? toolchain.label : "Node only";
+
+  if (target === "gitlab") {
+    const image = toolchain?.gl || "node:20";
+    const needsNode = image !== "node:20" && !image.startsWith("node");
+    const content = `${HEADER(stackId, version)}
+agent-gate:
+  image: ${image}
+  stage: test
+  variables:
+    GIT_DEPTH: "0"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == "${base}"
+  script:${
+    needsNode
+      ? `
+    # agentctl is a Node CLI, so the image needs Node even when the project is not.
+    - command -v node >/dev/null 2>&1 || (apt-get update -qq && apt-get install -y -qq nodejs npm)`
+      : ""
+  }
+    - npx --yes jules-orchestrator-kit check --mode committed --base "origin/${base}"
+`;
+    return { file: ".gitlab-ci.agent-gate.yml", content, setupSummary };
+  }
+
+  const extraSteps = (toolchain?.gh || []).map(renderGhStep).join("\n");
+  const content = `${HEADER(stackId, version)}
+name: Agent Safety Gate
+
+on:
+  pull_request:
+    branches: [ ${base} ]
+  push:
+    branches: [ ${base} ]
+
+permissions:
+  contents: read
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          # The gate compares the branch against its merge base, which needs
+          # full history rather than the default single-commit fetch.
+          fetch-depth: 0
+          persist-credentials: false
+
+      # agentctl is a Node CLI: the runner needs Node whatever the project is
+      # written in.
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+${extraSteps ? extraSteps + "\n" : ""}
+      - name: Run agent safety gate
+        run: npx --yes jules-orchestrator-kit check --mode committed --base "origin/${base}"
+`;
+  return { file: ".github/workflows/agent-gate.yml", content, setupSummary };
+}
+
+/**
+ * Write the generated workflow, refusing to clobber an existing file unless
+ * asked.
+ *
+ * @param {string} root
+ * @param {object} [opts] - see {@link buildCiWorkflow}, plus `force` and `dryRun`
+ * @returns {{ ok: boolean, file?: string, written?: boolean, stack?: string, setupSummary?: string, content?: string, error?: string }}
+ */
+export function writeCiWorkflow(root, opts = {}) {
+  if (opts.target && !CI_TARGETS.includes(opts.target)) {
+    return { ok: false, error: `Unknown CI target '${opts.target}'. Choose one of: ${CI_TARGETS.join(", ")}` };
+  }
+
+  const built = buildCiWorkflow(opts);
+  const stackId = opts.stack?.stack || "unknown";
+  const abs = join(root, built.file);
+
+  if (opts.dryRun) {
+    return { ok: true, file: built.file, written: false, stack: stackId, setupSummary: built.setupSummary, content: built.content };
+  }
+
+  if (existsSync(abs) && !opts.force) {
+    let identical = false;
+    try {
+      identical = readFileSync(abs, "utf-8") === built.content;
+    } catch (_) {
+      // Unreadable target: treat as different so the caller is told to --force
+      // rather than being told nothing changed.
+    }
+    return {
+      ok: true,
+      file: built.file,
+      written: false,
+      identical,
+      stack: stackId,
+      setupSummary: built.setupSummary,
+      content: built.content,
+    };
+  }
+
+  try {
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, built.content, "utf-8");
+  } catch (err) {
+    return { ok: false, error: `Could not write ${built.file}: ${err.message}` };
+  }
+
+  return { ok: true, file: built.file, written: true, stack: stackId, setupSummary: built.setupSummary, content: built.content };
+}