bearings 0.3.4 → 0.5.0

package/dist/{chunk-GEIRG7UT.js → chunk-5D5YO3E3.js}

@@ -13,6 +13,23 @@ var STARTER_SKILL_NAMES = [
   "recording-decisions"
 ];
 var SKILLS = STARTER_SKILL_NAMES;
+var MANUAL_TESTPLAN_FILES = [
+  "SKILL.md"
+];
+var FORGE_A_SKILL_FILES = [
+  "SKILL.md",
+  "templates/guardrail.md",
+  "templates/probe-set.json"
+];
+var CHECKLIST_FILES = [
+  "SKILL.md",
+  "schema.reference.json",
+  "scripts/validate.mjs",
+  "scripts/build.mjs",
+  "previewer/index.html",
+  "previewer/viewer.css",
+  "previewer/viewer.js"
+];
 function starterSkillNameFromTarget(targetPath) {
   return STARTER_SKILL_NAMES.find((skillName) => targetPath === `.agents/skills/${skillName}/SKILL.md`);
 }
@@ -40,6 +57,21 @@ var SCAFFOLD = [
     template: `agents/skills/${skill}/SKILL.md`,
     target: `.agents/skills/${skill}/SKILL.md`,
     owner: "bearings"
+  })),
+  ...MANUAL_TESTPLAN_FILES.map((file) => ({
+    template: `agents/skills/manual-testplan/${file}`,
+    target: `.agents/skills/manual-testplan/${file}`,
+    owner: "bearings"
+  })),
+  ...FORGE_A_SKILL_FILES.map((file) => ({
+    template: `agents/skills/forge-a-skill/${file}`,
+    target: `.agents/skills/forge-a-skill/${file}`,
+    owner: "bearings"
+  })),
+  ...CHECKLIST_FILES.map((file) => ({
+    template: `agents/skills/checklist/${file}`,
+    target: `.agents/skills/checklist/${file}`,
+    owner: "bearings"
   }))
 ];
 
@@ -198,6 +230,24 @@ function validateSetupPending(value) {
     toVersion
   };
 }
+function validateMigrationReconciliation(value, index) {
+  const context = `migrationReconciliations[${index}]`;
+  if (!isPlainObject(value)) fail(`${context} must be an object`);
+  const { kind, source, target, backup, sourceHash, incomingHash } = value;
+  if (kind !== "testplan-collision" && kind !== "invalid-testplan") {
+    fail(`${context}.kind must be "testplan-collision" or "invalid-testplan"`);
+  }
+  if (!isSafeManifestPath(source)) fail(`${context}.source is unsafe: ${String(source)}`);
+  if (!isSafeManifestPath(backup)) fail(`${context}.backup is unsafe: ${String(backup)}`);
+  if (!isHash(sourceHash)) fail(`${context}.sourceHash must match sha256 format`);
+  if (kind === "testplan-collision") {
+    if (!isSafeManifestPath(target)) fail(`${context}.target is unsafe: ${String(target)}`);
+    if (!isHash(incomingHash)) fail(`${context}.incomingHash must match sha256 format`);
+    return { kind, source, target, backup, sourceHash, incomingHash };
+  }
+  if (target !== void 0 && !isSafeManifestPath(target)) fail(`${context}.target is unsafe: ${String(target)}`);
+  return { kind, source, ...target !== void 0 ? { target } : {}, backup, sourceHash };
+}
 function parseManifest(raw) {
   if (!isPlainObject(raw)) fail("manifest must be an object");
   const { version, bearingsVersion, harnesses, exposure, files } = raw;
@@ -213,13 +263,19 @@ function parseManifest(raw) {
   if (version === 2) {
     const validatedFiles = files.map((file, index) => validateFileV2(file, index));
     assertUniquePaths(validatedFiles.map((file) => file.path));
-    const { setupPending } = raw;
+    const { setupPending, migrationReconciliations } = raw;
+    if (migrationReconciliations !== void 0 && !Array.isArray(migrationReconciliations)) {
+      fail("migrationReconciliations must be an array");
+    }
     return {
       version: 2,
       bearingsVersion,
       harnesses,
       exposure,
       ...setupPending !== void 0 ? { setupPending: validateSetupPending(setupPending) } : {},
+      ...migrationReconciliations !== void 0 ? {
+        migrationReconciliations: migrationReconciliations.map(validateMigrationReconciliation)
+      } : {},
       files: validatedFiles
     };
   }
@@ -336,6 +392,7 @@ function renderUpdatePlan(input) {
   pushSection(lines, "Skipped", categories.skipped);
   pushSection(lines, "Removed", categories.removed);
   pushSection(lines, "Kept and untracked", categories.keptUntracked);
+  pushMigrationSections(lines, input.migrationActions ?? []);
   if (input.adapterActions.length) {
     lines.push("", `Adapter changes (${input.adapterActions.length}):`);
     for (const a of input.adapterActions) lines.push(`  ${a.kind} ${a.path}`);
@@ -360,6 +417,7 @@ function renderUpdateReport(input) {
   pushSection(lines, "Skipped", categories.skipped);
   pushSection(lines, "Removed", categories.removed);
   pushSection(lines, "Kept and untracked", categories.keptUntracked);
+  pushMigrationSections(lines, input.migrationActions ?? []);
   if (input.adapterActions.length) {
     lines.push("", `Adapter changes (${input.adapterActions.length}):`);
     for (const a of input.adapterActions) lines.push(`  ${a.kind} ${a.path}`);
@@ -382,6 +440,12 @@ function renderUpdateReport(input) {
   }
   return lines.join("\n");
 }
+function pushMigrationSections(lines, actions) {
+  pushSection(lines, "Migrated legacy test plans", actions.filter((action) => action.kind === "migrate-testplan").map((action) => `${action.source} -> ${action.target}`));
+  pushSection(lines, "Migration collisions backed up -> /setup-repo", actions.flatMap((action) => action.kind === "migrate-testplan" && action.backup !== void 0 ? [`${action.target} -> ${action.backup}`] : []));
+  pushSection(lines, "Invalid legacy test plans preserved -> /setup-repo", actions.filter((action) => action.kind === "preserve-invalid-testplan").map((action) => `${action.source} -> ${action.backup}`));
+  pushSection(lines, "Removed empty legacy plan directories", actions.filter((action) => action.kind === "remove-empty-testplan-dir").map((action) => action.path));
+}
 function renderVerifyReport(v) {
   const lines = [];
   for (const f of v.failures) lines.push(`FAIL ${f.code} ${f.path} \u2014 ${f.message}`);
@@ -393,7 +457,7 @@ ${v.failures.length} failure(s).` : "\nbearings verify: OK");
 
 // src/commands/init.ts
 import { lstat as lstat2, readdir as readdir2 } from "fs/promises";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 
 // src/scanner.ts
 import { access as access2, symlink, rm } from "fs/promises";
@@ -424,40 +488,78 @@ async function scan(repoDir) {
 }
 
 // src/generator.ts
-import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2, rename, access as access3 } from "fs/promises";
+import { mkdir as mkdir3, readFile as readFile2, writeFile as writeFile2, access as access4 } from "fs/promises";
+import { dirname as dirname3, join as join5 } from "path";
+
+// src/backup-path.ts
+import { access as access3, mkdir as mkdir2, open, rm as rm2 } from "fs/promises";
 import { dirname as dirname2, join as join4 } from "path";
+async function freeBackupPath(repoDir, target) {
+  let candidate = `${target}.bkp`;
+  for (let index = 1; await access3(join4(repoDir, candidate)).then(() => true, () => false); index++) {
+    candidate = `${target}.bkp.${index}`;
+  }
+  return candidate;
+}
+async function writeBackup(repoDir, target, content, options = {}) {
+  let candidate = options.path ?? `${target}.bkp`;
+  for (let index = 1; ; index++) {
+    await options.beforeCreate?.(candidate);
+    const absolute = join4(repoDir, candidate);
+    await mkdir2(dirname2(absolute), { recursive: true });
+    let handle;
+    try {
+      handle = await open(absolute, "wx");
+    } catch (error) {
+      if (!options.path && error.code === "EEXIST") {
+        candidate = `${target}.bkp.${index}`;
+        continue;
+      }
+      throw error;
+    }
+    try {
+      await handle.writeFile(content);
+      await handle.close();
+      return candidate;
+    } catch (error) {
+      await handle.close().catch(() => {
+      });
+      await rm2(absolute, { force: true }).catch(() => {
+      });
+      throw error;
+    }
+  }
+}
+
+// src/generator.ts
 async function exists2(p) {
   try {
-    await access3(p);
+    await access4(p);
     return true;
   } catch {
     return false;
   }
 }
-async function freeBackupPath(repoDir, target) {
-  let candidate = `${target}.bkp`;
-  for (let i = 1; await exists2(join4(repoDir, candidate)); i++) candidate = `${target}.bkp.${i}`;
-  return candidate;
-}
-async function generate(repoDir, bearingsVersion) {
+async function generate(repoDir, bearingsVersion, hooks = {}) {
   const priorState = await inspectManifest(repoDir);
   if (priorState.kind === "invalid") throw new Error(`Invalid manifest: ${priorState.message}`);
   const prior = priorState.kind === "valid" ? priorState.manifest.version === 1 ? await migrateV1(repoDir, priorState.manifest) : priorState.manifest : null;
   const result = { written: [], backedUp: [], skippedUnchanged: [], files: [] };
   for (const entry of SCAFFOLD) {
-    const abs = join4(repoDir, entry.target);
-    const templateContent = await readFile2(join4(templatesDir(), entry.template), "utf8");
+    const abs = join5(repoDir, entry.target);
+    const templateContent = await readFile2(join5(templatesDir(), entry.template), "utf8");
     const priorEntry = prior?.files.find((f) => f.path === entry.target);
     let backup;
     let currentContent;
     if (await exists2(abs)) {
-      currentContent = await readFile2(abs, "utf8");
+      const currentBytes = await readFile2(abs);
+      currentContent = currentBytes.toString("utf8");
       if (priorEntry && sha256(currentContent) === priorEntry.hash) {
         const skillName2 = starterSkillNameFromTarget(entry.target);
         if (skillName2) {
-          const baseline = join4(repoDir, skillBaselinePath(skillName2));
+          const baseline = join5(repoDir, skillBaselinePath(skillName2));
           if (!await exists2(baseline)) {
-            await mkdir2(dirname2(baseline), { recursive: true });
+            await mkdir3(dirname3(baseline), { recursive: true });
             await writeFile2(baseline, currentContent);
           }
         }
@@ -465,18 +567,19 @@ async function generate(repoDir, bearingsVersion) {
         result.files.push(priorEntry);
         continue;
       }
-      backup = await freeBackupPath(repoDir, entry.target);
-      await rename(abs, join4(repoDir, backup));
+      backup = await writeBackup(repoDir, entry.target, currentBytes, {
+        beforeCreate: hooks.beforeBackupCreate
+      });
       result.backedUp.push({ path: entry.target, backup });
     }
-    await mkdir2(dirname2(abs), { recursive: true });
+    await mkdir3(dirname3(abs), { recursive: true });
     await writeFile2(abs, templateContent);
     result.written.push(entry.target);
     const incomingHash = sha256(templateContent);
     const skillName = starterSkillNameFromTarget(entry.target);
     if (skillName) {
-      const baseline = join4(repoDir, skillBaselinePath(skillName));
-      await mkdir2(dirname2(baseline), { recursive: true });
+      const baseline = join5(repoDir, skillBaselinePath(skillName));
+      await mkdir3(dirname3(baseline), { recursive: true });
       await writeFile2(baseline, templateContent);
     }
     const reconciliation = backup && currentContent !== void 0 ? {
@@ -500,15 +603,15 @@ async function generate(repoDir, bearingsVersion) {
 }
 
 // src/adapters.ts
-import { mkdir as mkdir3, readdir, symlink as symlink2, lstat, readlink, rm as rm2, cp, readFile as readFile3 } from "fs/promises";
-import { join as join5 } from "path";
+import { mkdir as mkdir4, readdir, symlink as symlink2, lstat, readlink, rm as rm3, cp, readFile as readFile3 } from "fs/promises";
+import { join as join6 } from "path";
 var ADAPTER_KINDS = ["skills", "commands"];
 async function canonicalAdapterEntries(repoDir) {
   const entries = /* @__PURE__ */ new Map();
   for (const kind of ADAPTER_KINDS) {
-    const directory = join5(repoDir, ".agents", kind);
+    const directory = join6(repoDir, ".agents", kind);
     for (const name of await readdir(directory).catch(() => [])) {
-      entries.set(`${kind}/${name}`, join5(directory, name));
+      entries.set(`${kind}/${name}`, join6(directory, name));
     }
   }
   return entries;
@@ -528,7 +631,7 @@ async function entriesMatch(src, dst) {
     dstEntries.sort();
     for (let i = 0; i < srcEntries.length; i++) {
       if (srcEntries[i] !== dstEntries[i]) return false;
-      if (!await entriesMatch(join5(src, srcEntries[i]), join5(dst, dstEntries[i]))) return false;
+      if (!await entriesMatch(join6(src, srcEntries[i]), join6(dst, dstEntries[i]))) return false;
     }
     return true;
   }
@@ -540,30 +643,30 @@ async function entriesMatch(src, dst) {
 async function expose(repoDir, harness, mode) {
   const created = [];
   for (const kind of ADAPTER_KINDS) {
-    const srcDir = join5(repoDir, ".agents", kind);
+    const srcDir = join6(repoDir, ".agents", kind);
     let entries;
     try {
       entries = await readdir(srcDir);
     } catch {
       continue;
     }
-    const dstDir = join5(repoDir, `.${harness}`, kind);
-    await mkdir3(dstDir, { recursive: true });
+    const dstDir = join6(repoDir, `.${harness}`, kind);
+    await mkdir4(dstDir, { recursive: true });
     for (const name of entries) {
-      const dst = join5(dstDir, name);
-      const adapterPath = join5(`.${harness}`, kind, name);
-      const relTarget = join5("..", "..", ".agents", kind, name);
+      const dst = join6(dstDir, name);
+      const adapterPath = join6(`.${harness}`, kind, name);
+      const relTarget = join6("..", "..", ".agents", kind, name);
       const stat = await lstat(dst).catch(() => null);
       if (mode === "symlink") {
         if (stat?.isSymbolicLink() && await readlink(dst) === relTarget) continue;
         if (stat && !stat.isSymbolicLink()) throw new Error(`Refusing to replace existing adapter entry: ${adapterPath}`);
-        if (stat) await rm2(dst, { recursive: true });
+        if (stat) await rm3(dst, { recursive: true });
         await symlink2(relTarget, dst);
       } else {
-        const src = join5(srcDir, name);
+        const src = join6(srcDir, name);
         if (stat && await entriesMatch(src, dst)) continue;
         if (stat && !stat.isSymbolicLink()) throw new Error(`Refusing to replace existing adapter entry: ${adapterPath}`);
-        if (stat) await rm2(dst, { recursive: true });
+        if (stat) await rm3(dst, { recursive: true });
         await cp(src, dst, { recursive: true });
       }
       created.push(adapterPath);
@@ -595,14 +698,14 @@ async function plannedAdapterSources(repoDir) {
       const prefix = `.agents/${kind}/`;
       if (entry.target.startsWith(prefix)) {
         const name = entry.target.slice(prefix.length).split("/")[0];
-        sources[kind].set(name, join6(templatesDir(), "agents", kind, name));
+        sources[kind].set(name, join7(templatesDir(), "agents", kind, name));
       }
     }
   }
   for (const kind of KINDS) {
-    const srcDir = join6(repoDir, ".agents", kind);
+    const srcDir = join7(repoDir, ".agents", kind);
     for (const name of await readdir2(srcDir).catch(() => [])) {
-      if (!sources[kind].has(name)) sources[kind].set(name, join6(srcDir, name));
+      if (!sources[kind].has(name)) sources[kind].set(name, join7(srcDir, name));
     }
   }
   return sources;
@@ -612,8 +715,8 @@ async function preflightAdapterCollisions(repoDir, harnesses, exposure) {
   for (const h of harnesses) {
     for (const kind of KINDS) {
       for (const [name, source] of sources[kind]) {
-        const adapterPath = join6(`.${h}`, kind, name);
-        const target = join6(repoDir, adapterPath);
+        const adapterPath = join7(`.${h}`, kind, name);
+        const target = join7(repoDir, adapterPath);
         const stat = await lstat2(target).catch(() => null);
         if (!stat || stat.isSymbolicLink()) continue;
         if (exposure === "copy" && await entriesMatch(source, target)) continue;
@@ -680,7 +783,7 @@ async function runFreshInit(repoDir, flags, version) {
 async function runInit(repoDir, flags, version) {
   const state = await inspectManifest(repoDir);
   if (state.kind === "absent") return runFreshInit(repoDir, flags, version);
-  const { runUpdate } = await import("./update-XOUXGD2Z.js");
+  const { runUpdate } = await import("./update-QTWNGAGX.js");
   return runUpdate(repoDir, flags, version, state);
 }
 
@@ -694,6 +797,8 @@ export {
   sha256,
   inspectManifest,
   migrateV1,
+  freeBackupPath,
+  writeBackup,
   ADAPTER_KINDS,
   canonicalAdapterEntries,
   entriesMatch,

package/dist/cli.js

@@ -8,13 +8,13 @@ import {
   skillBaselinePath,
   starterSkillNameFromTarget,
   validateHarnesses
-} from "./chunk-GEIRG7UT.js";
+} from "./chunk-5D5YO3E3.js";
 
 // src/cli.ts
 import { Command } from "commander";
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
-import { dirname as dirname2, join as join2 } from "path";
+import { dirname as dirname2, join as join3 } from "path";
 
 // src/verifier.ts
 import { access, lstat, readFile, readdir, readlink, stat } from "fs/promises";
@@ -81,6 +81,17 @@ async function verify(repoDir) {
       }
     }
   }
+  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 = [];
@@ -150,9 +161,52 @@ async function runVerify(repoDir) {
   return v.failures.length ? 1 : 0;
 }
 
+// src/commands/checklist.ts
+import { spawn } from "child_process";
+import { access as access2 } from "fs/promises";
+import { join as join2 } 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];
+  return new Promise((resolve2, reject) => {
+    const child = spawnProcess(command, args, { detached: true, stdio: "ignore" });
+    child.once("error", reject);
+    child.once("spawn", () => resolve2());
+    child.unref();
+  });
+}
+async function runBuilder(builder, repoDir) {
+  return new Promise((resolve2, reject) => {
+    const child = spawn(process.execPath, [builder, repoDir], { cwd: repoDir, stdio: "inherit" });
+    child.once("error", reject);
+    child.once("exit", (code) => resolve2(code ?? 1));
+  });
+}
+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");
+  log(previewer);
+  try {
+    await Promise.all([
+      builder,
+      join2(bundle, "scripts/validate.mjs"),
+      previewer,
+      join2(bundle, "previewer/viewer.js"),
+      join2(bundle, "previewer/viewer.css")
+    ].map((path) => access2(path)));
+  } catch {
+    throw new Error("Checklist previewer is not installed. Run `bearings init` to update this repository.");
+  }
+  const buildCode = await runBuilder(builder, repoDir);
+  if (buildCode !== 0) return buildCode;
+  await open(previewer);
+  return 0;
+}
+
 // src/cli.ts
 var pkg = JSON.parse(
-  readFileSync(join2(dirname2(fileURLToPath(import.meta.url)), "../package.json"), "utf8")
+  readFileSync(join3(dirname2(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) => {
@@ -166,6 +220,9 @@ program.command("init").description("Scaffold the agent-friendly setup in the cu
 program.command("verify").description("Check the agent-friendly setup for drift and breakage").action(async () => {
   process.exitCode = await runVerify(process.cwd());
 });
+program.command("checklist").description("Build and open the checklist previewer").action(async () => {
+  process.exitCode = await runChecklist(process.cwd());
+});
 program.parseAsync().catch((error) => {
   console.error(error instanceof Error ? error.message : String(error));
   process.exit(1);