@basou/cli 0.26.0 → 0.28.0

package/dist/index.js

@@ -3365,6 +3365,7 @@ async function assertWorkspaceInitialized7(basouRoot) {
 // src/commands/project.ts
 import {
   closeSync,
+  copyFileSync,
   existsSync,
   constants as fsConstants,
   ftruncateSync,
@@ -3385,10 +3386,12 @@ import { basename as basename4, dirname as dirname2, isAbsolute as isAbsolute3,
 import {
   appendBasouGitignore as appendBasouGitignore2,
   basouPaths as basouPaths10,
+  classifyRetrofit,
   createManifest as createManifest2,
   ensureBasouDirectory as ensureBasouDirectory2,
   GENERATED_END,
   GENERATED_START,
+  instructionMode,
   isGitNotFound,
   parseMarkers,
   pathBasename,
@@ -3505,6 +3508,17 @@ function registerProjectCommand(program2) {
   ).option("--apply", "Run every step in apply mode (default: dry-run preview)").option("-v, --verbose", "Show error causes").action(async (opts) => {
     await runProjectDerive(opts);
   });
+  project.command("retrofit").argument(
+    "<repo>",
+    "The declared roster repo whose hand-authored AGENTS.md to relocate (e.g. ../foo)"
+  ).description(
+    "Fold an existing repo's hand-authored AGENTS.md into the project topology: move the repo's regular-file `AGENTS.md` to the anchor canonical (`agents/<repo>/AGENTS.md`) and replace it with a symlink, so the prose lives at the single source of truth. Dry-run by default; pass --apply to relocate. The onboarding counterpart to `new` for a repo that already carries its own AGENTS.md \u2014 run it before `basou project derive`, which then adds the preset block, the CLAUDE.md / Copilot spokes, and the .gitignore. Non-destructive: it refuses when the destination canonical already exists (it never clobbers it), and skips a repo whose AGENTS.md is already a symlink or absent. The anchor (`.`) is refused"
+  ).option(
+    "--apply",
+    "Relocate the AGENTS.md to the canonical and recreate the symlink (default: dry-run preview)"
+  ).option("--json", "Output the result as JSON").option("-v, --verbose", "Show error causes").action(async (repo, opts) => {
+    await runProjectRetrofit(repo, opts);
+  });
 }
 async function runProjectCheck(options, ctx = {}) {
   try {
@@ -3767,7 +3781,8 @@ async function isTrackedByGit(repoRoot, relPath) {
 async function gatherRepoWiring(repositoryRoot, entry) {
   const base = {
     path: entry.path,
-    ...entry.visibility !== void 0 ? { visibility: entry.visibility } : {}
+    ...entry.visibility !== void 0 ? { visibility: entry.visibility } : {},
+    ...instructionMode(entry) === "self" ? { self: true } : {}
   };
   let real;
   try {
@@ -3850,6 +3865,13 @@ function renderProjectWiring(result) {
     for (const p of result.unknown) lines.push(`- ${p}`);
     lines.push("");
   }
+  if (result.self.length > 0) {
+    lines.push(
+      `## instructions: self (${result.self.length}) \u2014 committed instruction files are intentional (no leak risk)`
+    );
+    for (const p of result.self) lines.push(`- ${p}`);
+    lines.push("");
+  }
   if (result.incomplete.length > 0) {
     lines.push(
       `## Missing instruction files (${result.incomplete.length}) \u2014 to be filled by a later generation slice`
@@ -3878,7 +3900,8 @@ async function runProjectGitignore(options, ctx = {}) {
 function gatherRepoGitignore(repositoryRoot, entry) {
   const base = {
     path: entry.path,
-    ...entry.visibility !== void 0 ? { visibility: entry.visibility } : {}
+    ...entry.visibility !== void 0 ? { visibility: entry.visibility } : {},
+    ...instructionMode(entry) === "self" ? { self: true } : {}
   };
   let real;
   try {
@@ -3973,6 +3996,13 @@ function renderProjectGitignore(result) {
     for (const p of result.unknown) lines.push(`- ${p}`);
     lines.push("");
   }
+  if (result.self.length > 0) {
+    lines.push(
+      `## instructions: self (${result.self.length}) \u2014 skipped by design; their committed instruction files are shared, never gitignored`
+    );
+    for (const p of result.self) lines.push(`- ${p}`);
+    lines.push("");
+  }
   if (result.unreachable.length > 0) {
     lines.push(`## Unreachable (${result.unreachable.length}) \u2014 path unresolved / not a git repo`);
     for (const p of result.unreachable) lines.push(`- ${p}`);
@@ -3994,12 +4024,13 @@ async function runProjectSymlinks(options, ctx = {}) {
     process.exitCode = 1;
   }
 }
-function expectedSymlinkTargets(repoDirReal, canonicalFile) {
-  return [
-    { name: "AGENTS.md", target: relative2(repoDirReal, canonicalFile) },
+function expectedSymlinkTargets(repoDirReal, canonicalFile, mode = "hub") {
+  const spokes = [
     { name: "CLAUDE.md", target: CANONICAL_FILE },
     { name: ".github/copilot-instructions.md", target: `../${CANONICAL_FILE}` }
   ];
+  if (mode === "self") return spokes;
+  return [{ name: "AGENTS.md", target: relative2(repoDirReal, canonicalFile) }, ...spokes];
 }
 function inspectSymlink(filePath, expectedTarget) {
   let isLink;
@@ -4014,7 +4045,9 @@ function inspectSymlink(filePath, expectedTarget) {
   return actual === expectedTarget ? { state: "correct" } : { state: "mismatch", actualTarget: actual };
 }
 function gatherRepoSymlinks(repositoryRoot, anchorReal, entry) {
-  const base = { path: entry.path };
+  const mode = instructionMode(entry);
+  const isSelf = mode === "self";
+  const base = { path: entry.path, ...isSelf ? { self: true } : {} };
   let real;
   try {
     real = realpathSync(resolve7(repositoryRoot, entry.path));
@@ -4027,11 +4060,11 @@ function gatherRepoSymlinks(repositoryRoot, anchorReal, entry) {
   if (!existsSync(join7(real, ".git"))) {
     return { ...base, isAnchor: false, reachable: false, canonicalPresent: false, files: [] };
   }
-  const canonicalFile = join7(anchorReal, "agents", basename4(real), CANONICAL_FILE);
+  const canonicalFile = isSelf ? join7(real, CANONICAL_FILE) : join7(anchorReal, "agents", basename4(real), CANONICAL_FILE);
   if (!existsSync(canonicalFile)) {
     return { ...base, isAnchor: false, reachable: true, canonicalPresent: false, files: [] };
   }
-  const files = expectedSymlinkTargets(real, canonicalFile).map(
+  const files = expectedSymlinkTargets(real, canonicalFile, mode).map(
     (spec) => {
       const { state, actualTarget } = inspectSymlink(join7(real, spec.name), spec.target);
       return {
@@ -4184,6 +4217,13 @@ function renderProjectSymlinks(result) {
     for (const p of result.missingCanonical) lines.push(`- ${p}`);
     lines.push("");
   }
+  if (result.selfAgentsMissing.length > 0) {
+    lines.push(
+      `## AGENTS.md missing (${result.selfAgentsMissing.length}) \u2014 these \`instructions: self\` repos have no committed AGENTS.md yet; author it, then re-run to wire the spokes`
+    );
+    for (const p of result.selfAgentsMissing) lines.push(`- ${p}`);
+    lines.push("");
+  }
   if (result.unreachable.length > 0) {
     lines.push(`## Unreachable (${result.unreachable.length}) \u2014 path unresolved / not a git repo`);
     for (const p of result.unreachable) lines.push(`- ${p}`);
@@ -4534,6 +4574,9 @@ async function gatherRepoPreset(repositoryRoot, anchorReal, entry) {
     ...entry.language !== void 0 ? { language: entry.language } : {},
     ...entry.publishes !== void 0 ? { publishes: entry.publishes } : {}
   };
+  if (instructionMode(entry) === "self") {
+    return { ...declared, self: true, isAnchor: false, reachable: true, canonicalPresent: false };
+  }
   let real;
   try {
     real = realpathSync(resolve7(repositoryRoot, entry.path));
@@ -4741,6 +4784,13 @@ function renderProjectPreset(result) {
     for (const p of result.anchors) lines.push(`- ${p}`);
     lines.push("");
   }
+  if (result.self.length > 0) {
+    lines.push(
+      `## instructions: self (${result.self.length}) \u2014 hands-off; their hand-authored AGENTS.md is never written by basou`
+    );
+    for (const p of result.self) lines.push(`- ${p}`);
+    lines.push("");
+  }
   if (result.unreachable.length > 0) {
     lines.push(`## Unreachable (${result.unreachable.length}) \u2014 path unresolved / not a git repo`);
     for (const p of result.unreachable) lines.push(`- ${p}`);
@@ -4846,13 +4896,15 @@ function gatherRepoTeardown(repositoryRoot, manifest, target) {
   const targetAbs = resolve7(repositoryRoot, target);
   const canonicalName = basename4(repoReal ?? targetAbs);
   const roster = manifest.repos ?? [];
-  const inRoster = roster.some((r) => {
+  const declaredEntry = roster.find((r) => {
     try {
       return realpathSync(resolve7(repositoryRoot, r.path)) === (repoReal ?? "\0");
     } catch {
       return resolve7(repositoryRoot, r.path) === targetAbs;
     }
   });
+  const inRoster = declaredEntry !== void 0;
+  const isSelf = declaredEntry !== void 0 && instructionMode(declaredEntry) === "self";
   const cnFold = canonicalName.toLowerCase();
   const canonicalShared = roster.some((r) => {
     let rReal = null;
@@ -4874,6 +4926,16 @@ function gatherRepoTeardown(repositoryRoot, manifest, target) {
     if (repoReal !== void 0) {
       for (const spec of teardownExpectedTargets(repoReal, anchorReal, canonicalName)) {
         const { state, actualTarget } = inspectSymlink(join7(repoReal, spec.name), spec.target);
+        if (isSelf) {
+          if (state !== "missing")
+            items.push({
+              kind: "instruction-symlink",
+              label: spec.name,
+              state: "foreign",
+              note: "instructions: self \u2014 committed, left untouched"
+            });
+          continue;
+        }
         if (state === "correct")
           items.push({ kind: "instruction-symlink", label: spec.name, state: "removable" });
         else if (state === "mismatch")
@@ -5683,6 +5745,250 @@ async function doRunProjectDerive(options, ctx) {
     apply ? "\u2705 Ran every step (each is idempotent, so a partial apply recovers on re-run)." : "\u2139\uFE0F Dry-run preview. Pass --apply to write the changes, then re-run."
   );
 }
+async function runProjectRetrofit(repo, options, ctx = {}) {
+  try {
+    await doRunProjectRetrofit(repo, options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
+}
+function inspectAgentsState(filePath) {
+  let st;
+  try {
+    st = lstatSync(filePath);
+  } catch (error) {
+    if (hasErrorCode(error) && error.code === "ENOENT") return "absent";
+    return "blocked";
+  }
+  if (st.isSymbolicLink()) return "symlink";
+  return st.isFile() ? "regular-file" : "blocked";
+}
+function regularFileSpokes(repoReal) {
+  const out = [];
+  for (const spoke of ["CLAUDE.md", ".github/copilot-instructions.md"]) {
+    try {
+      const st = lstatSync(join7(repoReal, spoke));
+      if (!st.isSymbolicLink() && st.isFile()) out.push(spoke);
+    } catch {
+    }
+  }
+  return out;
+}
+function pathPresent(p) {
+  try {
+    lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function gatherRetrofit(repositoryRoot, anchorReal, roster, argPath, argAbs, argReal) {
+  const declaredEntry = roster.find((entry) => {
+    const entryAbs = resolve7(repositoryRoot, entry.path);
+    if (argReal !== void 0) {
+      try {
+        if (realpathSync(entryAbs) === argReal) return true;
+      } catch {
+      }
+    }
+    return entryAbs === argAbs;
+  });
+  const declared = declaredEntry !== void 0;
+  const self = declaredEntry !== void 0 && instructionMode(declaredEntry) === "self";
+  const displayRel = argReal !== void 0 ? relative2(anchorReal, argReal) : relative2(repositoryRoot, argAbs);
+  const path = displayRel === "" ? "." : displayRel;
+  const canonicalName = basename4(argReal ?? argAbs);
+  if (argReal === void 0) {
+    return {
+      path,
+      declared,
+      ...self ? { self: true } : {},
+      isAnchor: false,
+      reachable: false,
+      canonicalName,
+      agentsState: "absent",
+      canonicalExists: false,
+      regularSpokes: []
+    };
+  }
+  const isAnchor = argReal === anchorReal;
+  const reachable = existsSync(join7(argReal, ".git"));
+  const canonicalFile = join7(anchorReal, "agents", canonicalName, CANONICAL_FILE);
+  return {
+    path,
+    declared,
+    ...self ? { self: true } : {},
+    isAnchor,
+    reachable,
+    canonicalName,
+    agentsState: inspectAgentsState(join7(argReal, CANONICAL_FILE)),
+    canonicalExists: pathPresent(canonicalFile),
+    regularSpokes: regularFileSpokes(argReal)
+  };
+}
+function relocateAgentsFile(repoReal, canonicalFile) {
+  const agentsFile = join7(repoReal, CANONICAL_FILE);
+  try {
+    mkdirSync(dirname2(canonicalFile), { recursive: true });
+  } catch (error) {
+    return { ok: false, message: failureReason(error), partial: false };
+  }
+  try {
+    copyFileSync(agentsFile, canonicalFile, fsConstants.COPYFILE_EXCL);
+  } catch (error) {
+    const message = hasErrorCode(error) && error.code === "EEXIST" ? "canonical-exists" : failureReason(error);
+    return { ok: false, message, partial: false };
+  }
+  try {
+    unlinkSync(agentsFile);
+    symlinkSync(relative2(repoReal, canonicalFile), agentsFile);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, message: failureReason(error), partial: true };
+  }
+}
+async function doRunProjectRetrofit(repo, options, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveBasouRootForCommand(cwd, "project retrofit");
+  const paths = basouPaths10(repositoryRoot);
+  const manifest = await readManifest6(paths);
+  const roster = manifest.repos ?? [];
+  const anchorReal = realpathSync(repositoryRoot);
+  const argAbs = resolve7(repositoryRoot, repo);
+  let argReal;
+  try {
+    argReal = realpathSync(argAbs);
+  } catch {
+    argReal = void 0;
+  }
+  const facts = gatherRetrofit(repositoryRoot, anchorReal, roster, repo, argAbs, argReal);
+  const plan = classifyRetrofit(facts);
+  let applied = false;
+  let failure;
+  let partial = false;
+  if (options.apply === true && plan.action === "relocate" && argReal !== void 0) {
+    const canonicalFile = join7(anchorReal, "agents", plan.canonicalName, CANONICAL_FILE);
+    const res = relocateAgentsFile(argReal, canonicalFile);
+    if (res.ok) {
+      applied = true;
+    } else {
+      failure = res.message;
+      partial = res.partial;
+    }
+  }
+  const result = {
+    ...plan,
+    hasRoster: roster.length > 0,
+    applied,
+    ...failure !== void 0 ? { failure } : {},
+    ...partial ? { partial } : {}
+  };
+  if (options.json === true) {
+    console.log(JSON.stringify(result));
+  } else {
+    console.log(renderProjectRetrofit(result));
+  }
+  return result;
+}
+function appendSpokeChecklist(lines, spokes) {
+  if (spokes.length === 0) return;
+  lines.push(
+    `## Spoke files to reconcile (${spokes.length}) \u2014 regular files that would block clean wiring`
+  );
+  for (const s of spokes) {
+    lines.push(
+      `- ${s}: a regular file. If it duplicates AGENTS.md, remove it; if it carries unique content, merge it into AGENTS.md. Then run \`basou project symlinks\`.`
+    );
+  }
+  lines.push("");
+}
+function renderProjectRetrofit(result) {
+  const lines = [];
+  lines.push(
+    "# Retrofit an existing AGENTS.md into the project (relocate to the anchor canonical)"
+  );
+  lines.push("");
+  if (!result.hasRoster) {
+    lines.push(
+      "\u2139\uFE0F No repo roster declared (manifest `repos`). Declare the repo first with `basou project new` (or `basou project adopt`), then re-run."
+    );
+    return lines.join("\n");
+  }
+  const canonical2 = `agents/${result.canonicalName}/${CANONICAL_FILE}`;
+  if (result.action === "refuse") {
+    if (result.reason === "not-declared") {
+      lines.push(
+        `\u2139\uFE0F \`${result.path}\` is not declared in the roster (manifest \`repos\`). Add it first with \`basou project new\` / \`basou project adopt\`, then re-run.`
+      );
+    } else if (result.reason === "self") {
+      lines.push(
+        `\u2139\uFE0F \`${result.path}\` declares \`instructions: self\` \u2014 its \`${CANONICAL_FILE}\` is a hand-authored committed file that stays in the repo, so there is no anchor canonical to relocate it to. Retrofit does not apply (its CLAUDE.md / Copilot spokes are wired by \`basou project symlinks\`).`
+      );
+    } else if (result.reason === "anchor") {
+      lines.push(
+        `\u26A0\uFE0F \`${result.path}\` is the anchor (the project root). It owns its canonical directly \u2014 there is nothing to relocate.`
+      );
+    } else if (result.reason === "unreachable") {
+      lines.push(
+        `\u26A0\uFE0F \`${result.path}\` does not resolve to a git repository. There is nothing to retrofit.`
+      );
+    } else if (result.reason === "blocked") {
+      lines.push(
+        `\u26A0\uFE0F \`${result.path}/${CANONICAL_FILE}\` could not be inspected (a parent component is not a directory, a permission error, or the path is neither a regular file nor a symlink). Resolve it by hand, then re-run.`
+      );
+    } else if (result.reason === "canonical-exists") {
+      lines.push(
+        `\u26A0\uFE0F The destination canonical \`${canonical2}\` already exists. Not relocating, to avoid clobbering it. If the canonical is the source of truth, the repo's AGENTS.md is redundant (remove it, then run \`basou project symlinks\`); otherwise reconcile the two by hand.`
+      );
+    }
+    return lines.join("\n");
+  }
+  if (result.action === "skip") {
+    if (result.reason === "already-symlink") {
+      lines.push(
+        `\u2705 \`${result.path}/${CANONICAL_FILE}\` is already a symlink (already wired). Nothing to retrofit.`
+      );
+    } else {
+      lines.push(
+        `\u2139\uFE0F \`${result.path}\` has no regular-file \`${CANONICAL_FILE}\` to relocate. If it should have a canonical, run \`basou project derive\` to generate one from the manifest.`
+      );
+    }
+    lines.push("");
+    appendSpokeChecklist(lines, result.regularSpokes);
+    return lines.join("\n").trimEnd();
+  }
+  if (result.failure !== void 0) {
+    lines.push(
+      `Could not relocate \`${result.path}/${CANONICAL_FILE}\` to \`${canonical2}\`: ${result.failure}.`
+    );
+    if (result.partial === true) {
+      lines.push(
+        `The canonical \`${canonical2}\` was written, but \`${result.path}/${CANONICAL_FILE}\` may be absent. Run \`basou project symlinks --apply\` (or \`basou project derive --apply\`) to recreate the missing link, then verify.`
+      );
+    } else {
+      lines.push("Nothing was changed. Resolve the cause and re-run.");
+    }
+    return lines.join("\n");
+  }
+  if (result.applied) {
+    lines.push(
+      `\u2705 Relocated \`${result.path}/${CANONICAL_FILE}\` to \`${canonical2}\` and left a symlink in its place.`
+    );
+  } else {
+    lines.push(
+      `To relocate \`${result.path}/${CANONICAL_FILE}\` and replace it with a symlink (dry-run; pass --apply to write):`
+    );
+    lines.push(`    move    ${result.path}/${CANONICAL_FILE} -> ${canonical2}`);
+    lines.push(`    symlink ${result.path}/${CANONICAL_FILE} -> the canonical`);
+  }
+  lines.push("");
+  appendSpokeChecklist(lines, result.regularSpokes);
+  lines.push(
+    result.applied ? "Next: run `basou project derive --apply` to add the preset block, the CLAUDE.md / Copilot spokes, and the .gitignore." : "After applying, run `basou project derive --apply` to finish the wiring (preset block, CLAUDE.md / Copilot spokes, .gitignore)."
+  );
+  return lines.join("\n");
+}
 
 // src/commands/protocol.ts
 import { readFile as readFile4 } from "fs/promises";