@mmerterden/multi-agent-pipeline 17.6.0 → 18.0.0

package/install/_unattended-profile.mjs

@@ -0,0 +1,113 @@
+/**
+ * _unattended-profile.mjs  -  the permission posture a machine with nobody at
+ * the keyboard needs, written only when asked for.
+ *
+ * autopilot spawns its child with `--permission-prompts none`. That stops Claude
+ * Code from ASKING; it grants nothing. The tools the child then calls still have
+ * to be allowed somewhere, and on a fresh machine they are not - so the run
+ * stops at the first tool call, silently, with no prompt anywhere for a person
+ * to answer. It looks exactly like a queue that has nothing to do.
+ *
+ * This is opt-in and always will be. A default install writes no permissions at
+ * all, because widening a permission set is not a thing an installer should do
+ * to somebody who only wanted the pipeline files copied. `--unattended` prints
+ * the full list and the reason for each line BEFORE writing anything, because
+ * "the installer changed my permissions" should never be something a person
+ * discovers afterwards.
+ *
+ * The entries are broad on purpose, and that breadth is the cost of unattended
+ * operation rather than an oversight. A pipeline run builds, tests, edits, and
+ * shells out to whatever the repo's own toolchain is; an allowlist narrow
+ * enough to be interesting would be one the first unfamiliar repo breaks. The
+ * honest framing is: this is a machine you have decided to let run on its own.
+ *
+ * @module install/_unattended-profile
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Tool name plus why an unattended run cannot proceed without it. The reason is
+ * printed, not just stored: a list of fifteen tool names with no reasons is a
+ * list nobody audits.
+ */
+export const UNATTENDED_ALLOW = [
+  ["Bash", "every build, test, git and gh call the pipeline makes"],
+  ["Edit", "Phase 3 cannot change a file without it"],
+  ["Write", "new files, and every artefact a phase leaves behind"],
+  ["Read", "reading the repo it was pointed at"],
+  ["Glob", "finding files by pattern instead of shelling out to find"],
+  ["Grep", "the same, for content"],
+  ["Agent", "Phase 1 and Phase 4 dispatch subagents"],
+  ["Skill", "the phase specs are skills"],
+  ["WebFetch", "issue and ticket bodies referenced by URL"],
+  ["TaskCreate", "the phase tracker's task list"],
+  ["TaskUpdate", "the same"],
+  ["TaskList", "the same"],
+  ["TaskGet", "the same"],
+];
+
+/**
+ * Render the profile for a human to read before it is applied.
+ *
+ * @param {string[]} already entries the settings file already carries
+ * @returns {string}
+ */
+export function describeUnattendedProfile(already = []) {
+  const lines = [
+    "  Unattended permission profile  -  these go into ~/.claude/settings.json",
+    "  under permissions.allow. Nothing is removed; existing entries are kept.",
+    "",
+  ];
+  for (const [tool, why] of UNATTENDED_ALLOW) {
+    const mark = already.includes(tool) ? "already there" : "will be added";
+    lines.push(`    ${tool.padEnd(12)} ${why}  (${mark})`);
+  }
+  lines.push("");
+  lines.push("  This is broad, and that breadth is what unattended operation costs: a run");
+  lines.push("  builds and tests whatever the target repo uses, so a narrow list is one the");
+  lines.push("  first unfamiliar repo stops at, with nobody there to answer.");
+  return lines.join("\n");
+}
+
+/**
+ * Merge the profile into settings.json. Additive only, and idempotent: running
+ * it twice changes nothing the second time, and an entry a person added by hand
+ * survives.
+ *
+ * @param {{home:string, dryRun?:boolean}} opts
+ * @returns {{path:string, added:string[], already:string[], written:boolean}}
+ */
+export function applyUnattendedProfile({ home, dryRun = false }) {
+  const path = join(home, ".claude", "settings.json");
+  let settings = {};
+  if (existsSync(path)) {
+    try {
+      settings = JSON.parse(readFileSync(path, "utf-8"));
+    } catch (err) {
+      // A settings file that does not parse is the user's, not ours to
+      // rewrite: overwriting it would lose whatever is in there.
+      throw new Error(`${path} is not valid JSON, so it will not be modified: ${err.message}`, {
+        cause: err,
+      });
+    }
+  }
+  const permissions = settings.permissions || {};
+  const allow = Array.isArray(permissions.allow) ? [...permissions.allow] : [];
+  const already = [];
+  const added = [];
+  for (const [tool] of UNATTENDED_ALLOW) {
+    if (allow.some((a) => String(a) === tool || String(a).startsWith(`${tool}(`)))
+      already.push(tool);
+    else {
+      allow.push(tool);
+      added.push(tool);
+    }
+  }
+  if (dryRun || !added.length) return { path, added, already, written: false };
+
+  settings.permissions = { ...permissions, allow };
+  writeFileSync(path, `${JSON.stringify(settings, null, 2)}\n`);
+  return { path, added, already, written: true };
+}

package/install/index.mjs

@@ -20,6 +20,7 @@ import { installCopilot } from "./copilot.mjs";
 import { installCodex } from "./codex.mjs";
 import { setDryRun, writeFile } from "./_common.mjs";
 import { sendInstallTelemetry } from "./_telemetry.mjs";
+import { applyUnattendedProfile, describeUnattendedProfile } from "./_unattended-profile.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /** Repository root (one level above install/). */
@@ -63,6 +64,7 @@ export async function runInstall(argv) {
     "--index-only",
     "--dry-run",
     "--prune-external",
+    "--unattended",
   ];
   const KNOWN_PREFIXES = ["--platform="];
   const unknown = flags.filter(
@@ -91,6 +93,7 @@ export async function runInstall(argv) {
   const useSymlinks = flags.includes("--link");
   const indexOnly = flags.includes("--index-only");
   const pruneExternal = flags.includes("--prune-external");
+  const unattended = flags.includes("--unattended");
   const platformFlag = parsePlatformFlag(flags);
 
   const installerCtx = {
@@ -117,12 +120,15 @@ export async function runInstall(argv) {
   writeVersionMarkers({ home: HOME, forClaude, forCopilot, forCodex });
 
   if (dryRun) {
+    if (unattended) applyUnattended({ home: HOME, forClaude, dryRun: true });
     console.log("");
     console.log("  Dry-run complete - nothing was written. Re-run without --dry-run to install.");
     console.log("");
     return;
   }
 
+  if (unattended) applyUnattended({ home: HOME, forClaude });
+
   printSummary({ forClaude, forCopilot, forCodex });
 
   // Fire-and-forget; install is already done.
@@ -135,6 +141,48 @@ export async function runInstall(argv) {
  *
  * @param {{home: string, forClaude: boolean, forCopilot: boolean, forCodex?: boolean}} opts
  */
+/**
+ * Print the unattended permission profile, then apply it. Printing first is the
+ * contract: an installer that widens a permission set has to say what it is
+ * about to allow while the person can still stop it, not report it afterwards.
+ *
+ * Claude Code only. The profile is a ~/.claude/settings.json shape, and writing
+ * it for a host that does not read that file would be a line in a report that
+ * nothing acts on.
+ *
+ * @param {{home:string, forClaude:boolean, dryRun?:boolean}} opts
+ */
+function applyUnattended({ home, forClaude, dryRun = false }) {
+  if (!forClaude) {
+    console.log("");
+    console.log("  --unattended applies to Claude Code only; nothing written.");
+    return;
+  }
+  let existing = [];
+  try {
+    const settings = JSON.parse(readFileSync(join(home, ".claude", "settings.json"), "utf-8"));
+    existing = (settings?.permissions?.allow ?? []).map(String);
+  } catch {
+    // No settings file yet, or one that does not parse. Either way there is
+    // nothing to mark as "already there"; applyUnattendedProfile decides what
+    // to do about the unparseable case.
+  }
+  console.log("");
+  console.log(describeUnattendedProfile(existing));
+  try {
+    const res = applyUnattendedProfile({ home, dryRun });
+    console.log("");
+    if (dryRun) console.log(`  (dry-run) would add ${res.added.length} entr(ies) to ${res.path}`);
+    else if (!res.added.length) console.log(`  nothing to add - ${res.path} already covers it`);
+    else console.log(`  added ${res.added.join(", ")} to ${res.path}`);
+  } catch (err) {
+    // A settings file we cannot parse is the user's, and rewriting it would
+    // lose whatever is in there. Refusing loudly beats a silent overwrite.
+    console.log("");
+    console.log(`  permission profile NOT written: ${err.message}`);
+  }
+}
+
 export function writeVersionMarkers({ home, forClaude, forCopilot, forCodex }) {
   let version;
   try {