@basou/cli 0.26.0 → 0.27.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,6 +3386,7 @@ 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,
@@ -3505,6 +3507,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 {
@@ -5683,6 +5696,242 @@ 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 declared = roster.some((entry) => {
+    const entryAbs = resolve7(repositoryRoot, entry.path);
+    if (argReal !== void 0) {
+      try {
+        if (realpathSync(entryAbs) === argReal) return true;
+      } catch {
+      }
+    }
+    return entryAbs === argAbs;
+  });
+  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,
+      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,
+    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 === "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";