bearings 0.5.2 → 0.5.4

package/dist/cli.js

@@ -1,158 +1,20 @@
 #!/usr/bin/env node
 import {
   inspectManifest,
-  isStarterSkillTarget,
+  renderSetupScope,
   renderVerifyReport,
   runInit,
-  sha256,
-  skillBaselinePath,
-  starterSkillNameFromTarget,
-  validateHarnesses
-} from "./chunk-WYXKSCUW.js";
+  templatesDir,
+  validateHarnesses,
+  verify,
+  verifySetupOutcome
+} from "./chunk-MOZJECCW.js";
 
 // src/cli.ts
 import { Command } from "commander";
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
-import { dirname as dirname2, join as join3 } from "path";
-
-// src/verifier.ts
-import { access, lstat, readFile, readdir, readlink, stat } from "fs/promises";
-import { dirname, join, resolve } from "path";
-var KINDS = ["skills", "commands"];
-var PLACEHOLDER = /<agent:[^>\n]*>/;
-async function exists(p) {
-  try {
-    await access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function verify(repoDir) {
-  const failures = [];
-  const warnings = [];
-  const missingSkillBaselines = /* @__PURE__ */ new Set();
-  async function warnMissingSkillBaseline(baseline) {
-    if (missingSkillBaselines.has(baseline) || await exists(join(repoDir, baseline))) return;
-    missingSkillBaselines.add(baseline);
-    warnings.push({ code: "missing-skill-baseline", path: baseline, message: "run /setup-repo to repair skill baseline" });
-  }
-  const state = await inspectManifest(repoDir);
-  if (state.kind === "absent") {
-    return { failures: [{ code: "no-manifest", path: ".agents/bearings.json", message: "run bearings init first" }], warnings };
-  }
-  if (state.kind === "invalid") {
-    return { failures: [{ code: "invalid-manifest", path: ".agents/bearings.json", message: state.message }], warnings };
-  }
-  const m = state.manifest;
-  if ("setupPending" in m && m.setupPending) {
-    warnings.push({ code: "setup-pending", path: ".agents/bearings.json", message: "run /setup-repo to finish the pending update" });
-  }
-  for (const f of m.files) {
-    const retired = "retired" in f && f.retired === true;
-    if (!retired) {
-      const abs = join(repoDir, f.path);
-      if (!await exists(abs)) {
-        failures.push({ code: "missing-file", path: f.path, message: "managed file deleted" });
-      } else {
-        const content = await readFile(abs, "utf8");
-        if (f.owner === "agent" && PLACEHOLDER.test(content)) {
-          warnings.push({ code: "unfilled-placeholder", path: f.path, message: "run /setup-repo to fill" });
-        }
-      }
-    }
-    if (!retired && f.owner === "agent" && isStarterSkillTarget(f.path)) {
-      const skillName = starterSkillNameFromTarget(f.path);
-      await warnMissingSkillBaseline(skillBaselinePath(skillName));
-    }
-    if ("backup" in f && f.backup && await exists(join(repoDir, f.backup))) {
-      warnings.push({ code: "unreviewed-backup", path: f.backup, message: "review during /setup-repo, then delete" });
-    }
-    if ("reconciliations" in f && f.reconciliations) {
-      for (const r of f.reconciliations) {
-        if (r.reason === "skill-update") await warnMissingSkillBaseline(r.basePath);
-        if (await exists(join(repoDir, r.backup))) {
-          warnings.push({ code: "pending-reconciliation", path: r.backup, message: "review during /setup-repo, then delete" });
-        }
-        if (r.reason === "skill-update" && await exists(join(repoDir, r.incomingPath))) {
-          warnings.push({ code: "pending-reconciliation", path: r.incomingPath, message: "review during /setup-repo, then delete" });
-        }
-      }
-    }
-  }
-  if ("migrationReconciliations" in m && m.migrationReconciliations) {
-    for (const reconciliation of m.migrationReconciliations) {
-      if (await exists(join(repoDir, reconciliation.backup))) {
-        warnings.push({
-          code: "pending-reconciliation",
-          path: reconciliation.backup,
-          message: reconciliation.kind === "invalid-testplan" ? "repair with the checklist skill during /setup-repo, then delete" : "review during /setup-repo, then delete"
-        });
-      }
-    }
-  }
-  for (const kind of KINDS) {
-    const srcDir = join(repoDir, ".agents", kind);
-    let entries = [];
-    try {
-      entries = await readdir(srcDir);
-    } catch {
-    }
-    for (const h of m.harnesses) {
-      for (const name of entries) {
-        const exposurePath = join(`.${h}`, kind, name);
-        const dst = join(repoDir, `.${h}`, kind, name);
-        const l = await lstat(dst).catch(() => null);
-        if (!l) {
-          failures.push({ code: "missing-exposure", path: exposurePath, message: `not exposed to ${h}` });
-          continue;
-        }
-        if (l.isSymbolicLink()) {
-          if (!await stat(dst).catch(() => null)) {
-            failures.push({ code: "broken-symlink", path: exposurePath, message: "symlink target missing" });
-          } else {
-            const target = await readlink(dst);
-            if (resolve(dirname(dst), target) !== resolve(srcDir, name)) {
-              failures.push({ code: "missing-exposure", path: exposurePath, message: `not exposed to ${h}` });
-            }
-          }
-        } else if (m.exposure === "symlink") {
-          failures.push({ code: "missing-exposure", path: exposurePath, message: `not exposed to ${h}` });
-        } else {
-          const src = join(srcDir, name);
-          if (await copyDrifted(src, dst)) {
-            failures.push({ code: "copy-drift", path: exposurePath, message: "diverged from .agents source" });
-          }
-        }
-      }
-    }
-  }
-  return { failures, warnings };
-}
-async function copyDrifted(src, dst) {
-  const s = await stat(src);
-  if (s.isDirectory()) {
-    const [srcChildren, dstChildren] = await Promise.all([
-      readdir(src),
-      readdir(dst).catch(() => null)
-    ]);
-    if (dstChildren === null) return true;
-    const srcNames = new Set(srcChildren);
-    for (const child of dstChildren) {
-      if (!srcNames.has(child)) return true;
-    }
-    for (const child of srcChildren) {
-      if (await copyDrifted(join(src, child), join(dst, child))) return true;
-    }
-    return false;
-  }
-  const [a, b] = await Promise.all([
-    readFile(src, "utf8"),
-    readFile(dst, "utf8").catch(() => null)
-  ]);
-  return b === null || sha256(a) !== sha256(b);
-}
+import { dirname, join as join3, resolve } from "path";
 
 // src/commands/verify.ts
 async function runVerify(repoDir) {
@@ -163,8 +25,8 @@ async function runVerify(repoDir) {
 
 // src/commands/checklist.ts
 import { spawn } from "child_process";
-import { access as access2 } from "fs/promises";
-import { join as join2 } from "path";
+import { access } from "fs/promises";
+import { join } from "path";
 function openChecklist(path, platform = process.platform, spawnProcess = spawn) {
   const command = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
   const args = platform === "win32" ? ["/c", "start", "", path] : [path];
@@ -183,18 +45,18 @@ async function runBuilder(builder, repoDir) {
   });
 }
 async function runChecklist(repoDir, open = openChecklist, log = console.log) {
-  const bundle = join2(repoDir, ".agents/skills/checklist");
-  const builder = join2(bundle, "scripts/build.mjs");
-  const previewer = join2(bundle, "previewer/index.html");
+  const bundle = join(repoDir, ".agents/skills/checklist");
+  const builder = join(bundle, "scripts/build.mjs");
+  const previewer = join(bundle, "previewer/index.html");
   log(previewer);
   try {
     await Promise.all([
       builder,
-      join2(bundle, "scripts/validate.mjs"),
+      join(bundle, "scripts/validate.mjs"),
       previewer,
-      join2(bundle, "previewer/viewer.js"),
-      join2(bundle, "previewer/viewer.css")
-    ].map((path) => access2(path)));
+      join(bundle, "previewer/viewer.js"),
+      join(bundle, "previewer/viewer.css")
+    ].map((path) => access(path)));
   } catch {
     throw new Error("Checklist previewer is not installed. Run `bearings init` to update this repository.");
   }
@@ -204,18 +66,187 @@ async function runChecklist(repoDir, open = openChecklist, log = console.log) {
   return 0;
 }
 
+// src/commands/setup.ts
+import { readFile } from "fs/promises";
+import { join as join2 } from "path";
+
+// src/setup-launcher.ts
+import { spawn as spawn2 } from "child_process";
+function isKnownAgentContext(env = process.env) {
+  return Boolean(env.CLAUDE_CODE_CHILD_SESSION || env.OPENCODE_TERMINAL);
+}
+async function selectHarness(harnesses) {
+  const p = await import("@clack/prompts");
+  const selected = await p.select({
+    message: "Which harness should run guided setup?",
+    options: harnesses.map((value) => ({
+      value,
+      label: value === "claude" ? "Claude Code" : "OpenCode"
+    }))
+  });
+  return p.isCancel(selected) ? void 0 : selected;
+}
+async function runSetupSession(repoDir, prompt, options, deps = {}) {
+  const harnesses = [...new Set(options.harnesses)];
+  let harness = options.harness ?? (harnesses.length === 1 ? harnesses[0] : void 0);
+  const handoff = (message) => ({ status: "handoff", harness, message });
+  if (options.noAgent) return handoff("Agent launch disabled by --no-agent. Continue setup in your agent session.");
+  if (options.harness !== void 0 && (!["claude", "opencode"].includes(options.harness) || !harnesses.includes(options.harness))) {
+    return { status: "failed", message: `Harness ${options.harness} is not configured. Choose a configured harness: ${harnesses.join(", ") || "none"}.` };
+  }
+  if (!harnesses.length) return handoff("No harness is configured. Configure Claude Code or OpenCode with bearings init.");
+  if (options.yes) return handoff("Agent launch disabled by --yes. Run again without --yes in your terminal, or continue setup in your agent session.");
+  if (isKnownAgentContext(deps.env)) return handoff("Guided setup is already inside an agent session. Continue with the scoped task in this session.");
+  const terminal = deps.terminal ?? {
+    stdin: Boolean(process.stdin.isTTY),
+    stdout: Boolean(process.stdout.isTTY),
+    stderr: Boolean(process.stderr.isTTY)
+  };
+  if (!terminal.stdin || !terminal.stdout || !terminal.stderr) {
+    return handoff("Guided setup needs a user terminal for stdin, stdout, and stderr. Run again in your terminal, or continue setup in your agent session.");
+  }
+  try {
+    harness ??= await (deps.selectHarness ?? selectHarness)(harnesses);
+    if (!harness) return handoff("Harness selection cancelled. Continue setup in your agent session when ready.");
+    if (!harnesses.includes(harness) || !["claude", "opencode"].includes(harness)) {
+      return { status: "failed", message: "Select a configured Claude Code or OpenCode harness and retry." };
+    }
+    const selected = harness;
+    const args = selected === "claude" ? [prompt] : [repoDir, "--prompt", prompt];
+    return await new Promise((resolve2, reject) => {
+      const child = (deps.spawn ?? spawn2)(selected, args, { cwd: repoDir, stdio: "inherit", shell: false });
+      child.once("error", reject);
+      child.once("exit", (exitCode, signal) => resolve2({
+        status: exitCode === 0 && signal === null ? "exited" : "failed",
+        harness: selected,
+        exitCode,
+        signal,
+        message: exitCode === 0 && signal === null ? `${selected} session exited. Check pending setup work before reporting completion.` : `${selected} session stopped (${signal ?? `exit ${exitCode ?? "unknown"}`}). Check pending work and resume setup in your agent session.`
+      }));
+    });
+  } catch (error) {
+    const missing = error?.code === "ENOENT";
+    return {
+      status: "failed",
+      harness,
+      message: missing ? `Could not launch ${harness}: executable or repository directory not found. Check the repository path and install ${harness} on PATH, then retry or continue setup in your agent session.` : `Could not start ${harness ?? "guided setup"}: ${error instanceof Error ? error.message : String(error)}. Retry or continue setup in your agent session.`
+    };
+  }
+}
+
+// src/commands/setup.ts
+function quoteInvocationPart(value, platform) {
+  return platform === "win32" ? `'${value.replaceAll("'", "''")}'` : `'${value.replaceAll("'", "'\\''")}'`;
+}
+function renderSetupInvocation(invocation, platform = process.platform) {
+  return {
+    command: `${platform === "win32" ? "& " : ""}${invocation.map((part) => quoteInvocationPart(part, platform)).join(" ")}`,
+    shell: platform === "win32" ? "PowerShell" : "POSIX"
+  };
+}
+async function runSetup(repoDir, manifest, scope, options = {}, deps = {}) {
+  const original = structuredClone(manifest);
+  if (!original.setupPending?.tasks?.length) return { report: "", exitCode: 0 };
+  const { invocation, ...sessionOptions } = options;
+  const rendered = invocation?.length ? renderSetupInvocation(invocation, deps.platform) : { command: "npx bearings", shell: deps.platform === "win32" ? "PowerShell" : "POSIX" };
+  const command = rendered.command;
+  const resume = `Ask your current agent to run \`${command} init --no-agent\` and finish the returned task.`;
+  const initial = original.setupPending.kind === "init";
+  const recipePath = initial ? join2(templatesDir(), "initial-setup.md") : join2(repoDir, ".agents/commands/update-bearings-setup.md");
+  let recipe;
+  try {
+    recipe = await readFile(recipePath, "utf8").catch((error) => {
+      if (initial || error.code !== "ENOENT") throw error;
+      return readFile(join2(templatesDir(), "agents/commands/update-bearings-setup.md"), "utf8");
+    });
+  } catch {
+    return { report: `Setup pending: cannot read the setup recipe. ${resume}`, exitCode: 1 };
+  }
+  const commands = [
+    "## bearings Commands for This Task",
+    "Use these exact shell commands from the repository. They override generic recipe examples and select the initiating bearings executable.",
+    `Shell: ${rendered.shell}.`,
+    "This is the bearings setup workflow. When AGENTS.md is listed, remove obsolete Setup Required or Pending bearings Setup sections. Repository inspection needed for these tasks is permitted.",
+    `Resume: ${command} init --no-agent`,
+    `Complete: ${command} init --complete-setup`,
+    "Checkpoint selected tasks: append --setup-path <path...> to Complete.",
+    "Decline incoming skill templates: also append --keep-local <path...> for the scoped skill-update paths the developer chose to keep.",
+    "Quote each task path as a shell argument. A checkpoint completes only its selected paths; reread the remaining journal tasks."
+  ].join("\n");
+  const prompt = `${commands}
+
+${recipe.trim()}
+
+${scope.trim()}
+`;
+  const terminal = deps.terminal ?? {
+    stdin: Boolean(process.stdin.isTTY),
+    stdout: Boolean(process.stdout.isTTY),
+    stderr: Boolean(process.stderr.isTTY)
+  };
+  const env = deps.env ?? process.env;
+  const nested = isKnownAgentContext(env);
+  if (!options.noAgent && !options.yes && !nested && terminal.stdin && terminal.stdout && terminal.stderr && original.harnesses.length) {
+    const harness = options.harness ?? (original.harnesses.length === 1 ? original.harnesses[0] : void 0);
+    const openCode = harness === "opencode" || !harness && original.harnesses.includes("opencode");
+    (deps.log ?? console.log)(openCode ? "Guided setup: answer the harness prompts. In OpenCode, press Enter to submit the prepared task." : "Guided setup: answer the harness trust and permission prompts.");
+  }
+  const result = await (deps.runSession ?? runSetupSession)(repoDir, prompt, {
+    ...sessionOptions,
+    harnesses: original.harnesses
+  }, { terminal, ...deps.env ? { env } : {} });
+  if (result.status === "handoff") {
+    const printTask = options.noAgent || options.yes || nested || !terminal.stdin || !terminal.stdout || !terminal.stderr;
+    return {
+      report: printTask ? `Setup pending. Continue this task in your agent session:
+
+${prompt}` : `Setup pending. ${resume}`,
+      exitCode: 0
+    };
+  }
+  const current = await inspectManifest(repoDir);
+  const pending = current.kind === "valid" && current.manifest.version === 2 && current.manifest.setupPending;
+  if (result.status === "failed" && pending) {
+    return { report: `Setup pending. ${resume}`, exitCode: 1 };
+  }
+  try {
+    await verifySetupOutcome(repoDir, original);
+    return { report: "bearings setup complete.", exitCode: 0 };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return pending ? { report: `Setup pending. ${resume}`, exitCode: result.status === "failed" ? 1 : 0 } : { report: `Setup completion could not be verified: ${message}
+${resume}`, exitCode: 1 };
+  }
+}
+
 // src/cli.ts
 var pkg = JSON.parse(
-  readFileSync(join3(dirname2(fileURLToPath(import.meta.url)), "../package.json"), "utf8")
+  readFileSync(join3(dirname(fileURLToPath(import.meta.url)), "../package.json"), "utf8")
 );
 var program = new Command("bearings").version(pkg.version);
-program.command("init").description("Scaffold the agent-friendly setup in the current repository").option("--harness <name...>", "claude and/or opencode").option("--copy", "copy instead of symlink").option("-y, --yes", "accept defaults, no prompts").action(async (o) => {
-  const { report } = await runInit(process.cwd(), {
+program.command("init").description("Scaffold the agent-friendly setup in the current repository").option("--harness <name...>", "claude and/or opencode").option("--copy", "copy instead of symlink").option("-y, --yes", "accept defaults, no prompts").option("--no-agent", "print the scoped setup task without launching an agent").option("--setup-harness <name>", "run guided setup with one configured harness: claude or opencode").option("--complete-setup", "validate and finalize pending setup without launching an agent").option("--setup-path <path...>", "checkpoint only these pending paths (requires --complete-setup)").option("--keep-local <path...>", "decline incoming templates for these scoped skill updates (requires --complete-setup)").action(async (o) => {
+  if (!o.completeSetup && (o.setupPath || o.keepLocal)) {
+    throw new Error("--setup-path and --keep-local require --complete-setup.");
+  }
+  const harness = validateHarnesses(o.setupHarness === void 0 ? void 0 : [o.setupHarness])?.[0];
+  const { manifest, report } = await runInit(process.cwd(), {
     harnesses: validateHarnesses(o.harness),
     exposure: o.copy ? "copy" : void 0,
-    yes: o.yes
+    yes: o.yes,
+    completeSetup: o.completeSetup,
+    setupPaths: o.setupPath,
+    keepLocal: o.keepLocal
   }, pkg.version);
   console.log(report);
+  if (o.completeSetup || !manifest.setupPending?.tasks?.length) return;
+  const setup = await runSetup(process.cwd(), manifest, renderSetupScope(manifest), {
+    harness,
+    noAgent: o.agent === false,
+    yes: o.yes,
+    invocation: [process.execPath, resolve(process.argv[1])]
+  });
+  if (setup.report) console.log(setup.report);
+  process.exitCode = setup.exitCode;
 });
 program.command("verify").description("Check the agent-friendly setup for drift and breakage").action(async () => {
   process.exitCode = await runVerify(process.cwd());