mandrel 1.57.0

package/.agents/scripts/lib/bootstrap/manifest.js

@@ -0,0 +1,272 @@
+/**
+ * bootstrap/manifest — single mutation-manifest source for the
+ * consent-first phased install (Story #3521, Feature #3515, Epic #3438).
+ *
+ * `buildMutationManifest(ctx)` enumerates every mutation the bootstrap
+ * pipeline can perform as a flat, declarative array. Each entry carries the
+ * five fields the consent-first install screen needs to preview a change
+ * before any write lands:
+ *
+ *   - `phaseGroup` — one of the four independently-approvable groups
+ *     (`ide-wiring`, `repo-config`, `github-admin`, `quality-gates`).
+ *   - `target`     — the file path or remote resource the mutation touches.
+ *   - `action`     — the verb describing the mutation (`create`, `merge`,
+ *     `update`, `run`, `configure`).
+ *   - `detail`     — a one-line operator-facing description of the change.
+ *   - `reversible` — whether the operator can trivially undo the change
+ *     (e.g. delete a created file) vs. a remote-admin mutation that is not
+ *     a simple local revert.
+ *
+ * The manifest is the SINGLE source of truth: `applyProjectBootstrap`'s
+ * no-write preview is derived from `buildMutationManifest` so the preview
+ * the operator approves and the execution that follows enumerate the exact
+ * same set of mutations. There is no second, drift-prone list.
+ *
+ * The manifest describes *intended* mutations deterministically from the
+ * project root; it does not read or mutate any file. Whether a given
+ * mutation is a no-op on a particular clone (the file already carries the
+ * wiring) is decided at execution time by the idempotent `ensure*` steps —
+ * the manifest always lists the full surface so the preview is complete.
+ *
+ * @module bootstrap/manifest
+ */
+
+import path from 'node:path';
+
+/**
+ * The four independently-approvable phase groups. The consent-first install
+ * flow gates each group behind its own opt-in, so every manifest entry MUST
+ * carry exactly one of these values.
+ *
+ * @type {Readonly<{ IDE_WIRING: 'ide-wiring', REPO_CONFIG: 'repo-config',
+ *   GITHUB_ADMIN: 'github-admin', QUALITY_GATES: 'quality-gates' }>}
+ */
+export const PHASE_GROUPS = Object.freeze({
+  IDE_WIRING: 'ide-wiring',
+  REPO_CONFIG: 'repo-config',
+  GITHUB_ADMIN: 'github-admin',
+  QUALITY_GATES: 'quality-gates',
+});
+
+/**
+ * Frozen set of valid `phaseGroup` values, for validation and the
+ * acceptance check. Derived from `PHASE_GROUPS` so the two never drift.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const PHASE_GROUP_VALUES = Object.freeze(
+  new Set(Object.values(PHASE_GROUPS)),
+);
+
+/**
+ * The five required fields on every manifest entry. Exported so tests and
+ * downstream renderers can assert entry shape without re-declaring the list.
+ *
+ * @type {readonly string[]}
+ */
+export const MANIFEST_ENTRY_FIELDS = Object.freeze([
+  'phaseGroup',
+  'target',
+  'action',
+  'detail',
+  'reversible',
+]);
+
+/**
+ * @typedef {object} MutationManifestEntry
+ * @property {'ide-wiring'|'repo-config'|'github-admin'|'quality-gates'} phaseGroup
+ *   — the independently-approvable group this mutation belongs to.
+ * @property {string} target  — file path (relative to project root) or a
+ *   remote-resource identifier the mutation touches.
+ * @property {string} action  — verb describing the mutation.
+ * @property {string} detail  — one-line operator-facing description.
+ * @property {boolean} reversible — true when the operator can trivially
+ *   undo the change locally; false for remote-admin mutations.
+ */
+
+/**
+ * Build the consent-first mutation manifest for a project root.
+ *
+ * Returns a flat array of {@link MutationManifestEntry} objects covering
+ * every mutation the bootstrap pipeline performs, partitioned across the
+ * four {@link PHASE_GROUPS}. File targets are project-root-relative
+ * forward-slash POSIX paths so the preview renders identically on every
+ * platform; remote targets are scoped to the resolved `owner/repo` slug.
+ *
+ * The `github-admin` group is omitted when `ctx.skipGithub` is set, and the
+ * `quality-gates` group is omitted when `ctx.skipQuality` is set, so the
+ * preview reflects the same flags the executing pipeline honours.
+ *
+ * @param {object} [ctx]
+ * @param {{ owner?: string, repo?: string }} [ctx.answers] — scopes the
+ *   `github-admin` targets to the `owner/repo` slug.
+ * @param {boolean} [ctx.skipGithub] — omit the `github-admin` group.
+ * @param {boolean} [ctx.skipQuality] — omit the `quality-gates` group.
+ * @returns {MutationManifestEntry[]}
+ */
+export function buildMutationManifest(ctx = {}) {
+  const rel = (...parts) => path.posix.join(...parts);
+
+  const entries = [];
+
+  // --- ide-wiring -------------------------------------------------------
+  // Claude Code / IDE integration: the system-prompt import, the
+  // UserPromptSubmit sync hook, the generated flat command surface, and the
+  // .gitignore entry that keeps the generated tree out of git.
+  entries.push(
+    {
+      phaseGroup: PHASE_GROUPS.IDE_WIRING,
+      target: rel('CLAUDE.md'),
+      action: 'merge',
+      detail:
+        'Wire the @.agents/instructions.md system-prompt import so Claude Code hydrates the framework on cold start.',
+      reversible: true,
+    },
+    {
+      phaseGroup: PHASE_GROUPS.IDE_WIRING,
+      target: rel('.claude', 'settings.json'),
+      action: 'merge',
+      detail:
+        'Add the UserPromptSubmit re-sync hook so the /<command> tree stays current.',
+      reversible: true,
+    },
+    {
+      phaseGroup: PHASE_GROUPS.IDE_WIRING,
+      target: rel('.claude', 'commands'),
+      action: 'run',
+      detail:
+        'Generate the flat command surface (/<name>) from .agents/workflows/.',
+      reversible: true,
+    },
+    {
+      phaseGroup: PHASE_GROUPS.IDE_WIRING,
+      target: rel('.gitignore'),
+      action: 'merge',
+      detail:
+        'Ignore .claude/commands/ (generated), .mcp.json + .env (carry secrets), and the per-clone install ledger.',
+      reversible: true,
+    },
+  );
+
+  // --- repo-config ------------------------------------------------------
+  // Local repository configuration files the bootstrap seeds or extends.
+  entries.push(
+    {
+      phaseGroup: PHASE_GROUPS.REPO_CONFIG,
+      target: rel('package.json'),
+      action: 'merge',
+      detail:
+        'Seed/merge the sync:commands, prepare, and bootstrap npm scripts.',
+      reversible: true,
+    },
+    {
+      phaseGroup: PHASE_GROUPS.REPO_CONFIG,
+      target: rel('.agentrc.json'),
+      action: 'create',
+      detail:
+        'Seed .agentrc.json from the bundled starter with the operator-supplied owner/repo/handle/base-branch.',
+      reversible: true,
+    },
+  );
+
+  // --- quality-gates ----------------------------------------------------
+  // Stabilized quality-gate surface (husky pre-commit, quality npm
+  // scripts, .agentrc quality defaults).
+  if (!ctx.skipQuality) {
+    entries.push(
+      {
+        phaseGroup: PHASE_GROUPS.QUALITY_GATES,
+        target: rel('.husky', 'pre-commit'),
+        action: 'configure',
+        detail:
+          'Install the quality:preview pre-commit hook that blocks MI/CRAP drift at commit time.',
+        reversible: true,
+      },
+      {
+        phaseGroup: PHASE_GROUPS.QUALITY_GATES,
+        target: rel('package.json'),
+        action: 'merge',
+        detail: 'Add the quality:preview and quality:watch npm scripts.',
+        reversible: true,
+      },
+      {
+        phaseGroup: PHASE_GROUPS.QUALITY_GATES,
+        target: rel('.agentrc.json'),
+        action: 'merge',
+        detail:
+          'Seed delivery.quality coding-guardrails and auto-refresh defaults.',
+        reversible: true,
+      },
+    );
+  }
+
+  // --- github-admin -----------------------------------------------------
+  // Remote GitHub configuration. These are NOT trivially reversible local
+  // edits — they mutate remote repo/org admin state.
+  if (!ctx.skipGithub) {
+    const repoSlug =
+      ctx.answers?.owner && ctx.answers?.repo
+        ? `${ctx.answers.owner}/${ctx.answers.repo}`
+        : 'the GitHub repository';
+    entries.push(
+      {
+        phaseGroup: PHASE_GROUPS.GITHUB_ADMIN,
+        target: `${repoSlug} labels`,
+        action: 'create',
+        detail:
+          'Create the framework ticket-lifecycle labels (type::*, agent::*, meta::*, …).',
+        reversible: false,
+      },
+      {
+        phaseGroup: PHASE_GROUPS.GITHUB_ADMIN,
+        target: `${repoSlug} Projects V2`,
+        action: 'configure',
+        detail:
+          'Create/adopt the Projects V2 board, status field, and saved views.',
+        reversible: false,
+      },
+      {
+        phaseGroup: PHASE_GROUPS.GITHUB_ADMIN,
+        target: `${repoSlug} branch protection`,
+        action: 'configure',
+        detail:
+          'Apply the required-status-check branch-protection rule to the base branch.',
+        reversible: false,
+      },
+      {
+        phaseGroup: PHASE_GROUPS.GITHUB_ADMIN,
+        target: `${repoSlug} merge methods`,
+        action: 'configure',
+        detail:
+          'Set the allowed pull-request merge methods to the framework stance.',
+        reversible: false,
+      },
+    );
+  }
+
+  return entries;
+}
+
+/**
+ * Render the manifest as a no-write preview report grouped by phase group.
+ * Pure helper — derives entirely from {@link buildMutationManifest}, so the
+ * preview and the executing pipeline enumerate one identical source.
+ *
+ * The returned shape is `{ preview: true, groups: { <phaseGroup>: entry[] },
+ * entries: entry[] }`: callers that want the flat list read `entries`, and
+ * the consent-first screen reads `groups` to render one approvable section
+ * per phase group (only groups with at least one entry appear).
+ *
+ * @param {object} [ctx] — same context as {@link buildMutationManifest}.
+ * @returns {{ preview: true, groups: Record<string, MutationManifestEntry[]>,
+ *   entries: MutationManifestEntry[] }}
+ */
+export function previewMutationManifest(ctx = {}) {
+  const entries = buildMutationManifest(ctx);
+  const groups = {};
+  for (const entry of entries) {
+    if (!groups[entry.phaseGroup]) groups[entry.phaseGroup] = [];
+    groups[entry.phaseGroup].push(entry);
+  }
+  return { preview: true, groups, entries };
+}

package/.agents/scripts/lib/bootstrap/merge-methods.js

@@ -0,0 +1,108 @@
+/**
+ * bootstrap/merge-methods — Epic #1235 Story 5
+ *
+ * Promotes the framework's hands-off-pipeline merge stance to the
+ * consumer repo:
+ *   - allow_squash_merge: true   — single commit per PR; clean history.
+ *   - allow_rebase_merge: false  — no rebase-merge (status checks would
+ *                                  need to be re-run per commit).
+ *   - allow_merge_commit: false  — no merge commits cluttering the
+ *                                  default branch.
+ *   - allow_auto_merge: true     — required for the auto-merge label
+ *                                  feature Story 1 delivered.
+ *   - delete_branch_on_merge: true — head branches are throwaway.
+ *
+ * Behaviour rules
+ * ---------------
+ * No drift (live settings already match the target): no-op, returns
+ * `{ status: 'unchanged' }`.
+ *
+ * Drift (any field differs from the target stance): routes the proposed
+ * payload through `hitlConfirm`. On approval, PATCH is issued. On
+ * decline or non-TTY (the gate returns false), the module returns
+ * `{ status: 'skipped', reason: 'hitl-declined' }` without writing.
+ */
+
+export const TARGET_MERGE_METHODS = Object.freeze({
+  allow_squash_merge: true,
+  allow_rebase_merge: false,
+  allow_merge_commit: false,
+  allow_auto_merge: true,
+  delete_branch_on_merge: true,
+});
+
+/**
+ * Compute the drift between `current` (sparse) and the merged
+ * (defaults+settings) target. Returns null when nothing diverges so the
+ * caller can short-circuit before prompting HITL.
+ */
+export function diffMergeMethods(current, target) {
+  const diff = {};
+  for (const key of Object.keys(target)) {
+    const live = current?.[key];
+    if (live !== target[key]) {
+      diff[key] = { current: live ?? null, proposed: target[key] };
+    }
+  }
+  return Object.keys(diff).length > 0 ? diff : null;
+}
+
+/**
+ * @param {object} args
+ * @param {object} args.provider - Provider exposing `getMergeMethods()` /
+ *   `setMergeMethods(settings)`.
+ * @param {object} [args.settings] - The resolved settings bag. Reads
+ *   `github.mergeMethods` and merges over framework defaults.
+ * @param {(args:{summary:string, current:object, proposed:object})=>Promise<boolean>}
+ *   [args.hitlConfirm] - HITL gate. Defaults to "abort on diverge".
+ * @param {(msg:string)=>void} [args.log] - Logger sink.
+ */
+export async function applyMergeMethods({
+  provider,
+  settings,
+  hitlConfirm,
+  log = () => {},
+}) {
+  // Merge methods live under `github.mergeMethods`.
+  const override = settings?.github?.mergeMethods ?? {};
+  const target = { ...TARGET_MERGE_METHODS, ...override };
+
+  let current = {};
+  try {
+    current = (await provider.getMergeMethods()) ?? {};
+  } catch (err) {
+    log(`[bootstrap] Merge methods: read failed — ${err.message}.`);
+    return { status: 'failed', reason: err.message };
+  }
+
+  const diff = diffMergeMethods(current, target);
+  if (!diff) {
+    log('[bootstrap] Merge methods: already at target stance (no-op).');
+    return { status: 'unchanged' };
+  }
+
+  const approved =
+    typeof hitlConfirm === 'function'
+      ? await hitlConfirm({
+          summary:
+            'Repo merge-method settings diverge from the framework hands-off-pipeline stance.',
+          current,
+          proposed: target,
+        })
+      : false;
+  if (!approved) {
+    log(
+      '[bootstrap] Merge methods: drift detected; HITL declined / non-TTY — leaving operator settings untouched.',
+    );
+    return { status: 'skipped', reason: 'hitl-declined', diff };
+  }
+
+  try {
+    const result = await provider.setMergeMethods(target);
+    log(`[bootstrap] Merge methods: patched (${result.patched.join(', ')}).`);
+    return { status: 'patched', ...result, diff };
+  } catch (err) {
+    log(`[bootstrap] Merge methods: PATCH failed — ${err.message}.`);
+    return { status: 'failed', reason: err.message };
+  }
+}

package/.agents/scripts/lib/bootstrap/preflight.js

@@ -0,0 +1,195 @@
+/**
+ * bootstrap/preflight — unified prerequisite preflight (Story #3375).
+ *
+ * Aggregates the cold-start prerequisite checks into a single
+ * fail-before-mutate gate that `bootstrap.js` runs as the FIRST pipeline
+ * phase, ahead of any project-side or GitHub-side mutation:
+ *
+ *   - Node version  — reuses `checkNodeVersion` from `project-bootstrap.js`.
+ *   - git available — `git --version` resolves on PATH.
+ *   - inside-work-tree — `git rev-parse --is-inside-work-tree` is true.
+ *   - gh CLI + auth — reuses `preflightGh` from `gh-preflight.js`; skipped
+ *     entirely when `skipGithub` is true.
+ *
+ * `runPreflight({ skipGithub })` returns `{ ok, checks }` where `ok` is
+ * false when any check failed. Every failing check carries a `remedy`
+ * string so the CLI can print actionable next steps before halting.
+ *
+ * The runner seams (`nodeCheck`, `gitRunner`, `gh`) default to the real
+ * implementations and are injectable so the unit test can drive every
+ * branch without spawning real child processes.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { checkProjectScopes, preflightGh } from './gh-preflight.js';
+import { checkNodeVersion } from './project-bootstrap.js';
+
+const GIT_INSTALL_HINT =
+  'Install git: https://git-scm.com/downloads — then re-run this command.';
+const GIT_WORKTREE_HINT =
+  'Run this command from inside a git repository (run `git init` or `cd` into your project clone), then re-run.';
+const NODE_REMEDY = (result) =>
+  `Node ${result.version} is below required ${result.required}. Upgrade Node (https://nodejs.org/) and re-run this command.`;
+
+/**
+ * Default git runner: synchronously execs `git <args>` and returns the
+ * normalized `{ status, stdout, stderr, error }` shape. Extracted so the
+ * preflight tests can inject a stub without spawning a real child process.
+ *
+ * @param {string[]} args
+ * @returns {{ status: number|null, stdout: string, stderr: string,
+ *             error?: NodeJS.ErrnoException }}
+ */
+function defaultGitRunner(args) {
+  const result = spawnSync('git', args, { encoding: 'utf8' });
+  return {
+    status: result.status,
+    stdout: typeof result.stdout === 'string' ? result.stdout : '',
+    stderr: typeof result.stderr === 'string' ? result.stderr : '',
+    error: result.error,
+  };
+}
+
+/**
+ * Probe Node version via the injected `nodeCheck` seam (defaults to
+ * `checkNodeVersion`). Returns a check record.
+ *
+ * @param {() => { ok: boolean, version: string, required: string }} nodeCheck
+ * @returns {{ name: string, ok: boolean, remedy?: string }}
+ */
+function checkNode(nodeCheck) {
+  const result = nodeCheck();
+  if (result.ok) return { name: 'node', ok: true };
+  return { name: 'node', ok: false, remedy: NODE_REMEDY(result) };
+}
+
+/**
+ * Probe `git --version` for availability on PATH.
+ *
+ * @param {(args: string[]) => { status: number|null, stdout: string,
+ *   stderr: string, error?: NodeJS.ErrnoException }} gitRunner
+ * @returns {{ name: string, ok: boolean, remedy?: string }}
+ */
+function checkGitAvailable(gitRunner) {
+  const result = gitRunner(['--version']);
+  if (result.error?.code === 'ENOENT') {
+    return { name: 'git', ok: false, remedy: GIT_INSTALL_HINT };
+  }
+  if (result.status !== 0) {
+    const snippet = (result.stderr || '').trim().slice(0, 200);
+    return {
+      name: 'git',
+      ok: false,
+      remedy: `git --version failed (exit ${result.status})${
+        snippet ? `: ${snippet}` : ''
+      }. ${GIT_INSTALL_HINT}`,
+    };
+  }
+  return { name: 'git', ok: true };
+}
+
+/**
+ * Probe `git rev-parse --is-inside-work-tree` to confirm the command is
+ * running inside a git work tree.
+ *
+ * @param {(args: string[]) => { status: number|null, stdout: string,
+ *   stderr: string, error?: NodeJS.ErrnoException }} gitRunner
+ * @returns {{ name: string, ok: boolean, remedy?: string }}
+ */
+function checkInsideWorkTree(gitRunner) {
+  const result = gitRunner(['rev-parse', '--is-inside-work-tree']);
+  if (result.status === 0 && result.stdout.trim() === 'true') {
+    return { name: 'git-work-tree', ok: true };
+  }
+  return { name: 'git-work-tree', ok: false, remedy: GIT_WORKTREE_HINT };
+}
+
+/**
+ * Probe the `gh` CLI + auth via the injected `gh` seam (defaults to
+ * `preflightGh`). Maps the typed errors `preflightGh` throws into a
+ * single failing check carrying the error message as the remedy.
+ *
+ * @param {(opts?: object) => Promise<{ version: string }>} gh
+ * @returns {Promise<{ name: string, ok: boolean, remedy?: string }>}
+ */
+async function checkGh(gh) {
+  try {
+    await gh();
+    return { name: 'gh', ok: true };
+  } catch (err) {
+    return { name: 'gh', ok: false, remedy: err.message };
+  }
+}
+
+/**
+ * Run every prerequisite check and aggregate them into a single result.
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.skipGithub=false] — when true, skip the `gh` CLI
+ *   + auth check (the Node and git checks always run).
+ * @param {boolean} [opts.requireWorkTree=true] — when true (the default,
+ *   used by `bootstrap.js`), being outside a git work tree FAILS the gate.
+ *   When false (`bootstrap-new.js`), the work-tree probe is informational:
+ *   it never fails the gate and its result is reported via the returned
+ *   `gitInitialized` flag so later steps can fill in the missing git state.
+ * @param {boolean} [opts.checkProjectScope=false] — when true (and
+ *   `skipGithub` is false), also verify the `gh` token carries the
+ *   `project` scope needed to read/modify GitHub Projects V2.
+ * @param {() => { ok: boolean, version: string, required: string }}
+ *   [opts.nodeCheck] — Node-version seam (defaults to `checkNodeVersion`).
+ * @param {(args: string[]) => object} [opts.gitRunner] — git runner seam
+ *   (defaults to a real `spawnSync('git', …)`).
+ * @param {(opts?: object) => Promise<{ version: string }>} [opts.gh] —
+ *   `gh` preflight seam (defaults to `preflightGh`).
+ * @param {() => Promise<{ name: string, ok: boolean, remedy?: string }>}
+ *   [opts.projectScope] — project-scope seam (defaults to
+ *   `checkProjectScopes`).
+ * @returns {Promise<{ ok: boolean, gitInitialized: boolean,
+ *   checks: Array<{ name: string, ok: boolean, remedy?: string }> }>}
+ */
+export async function runPreflight(opts = {}) {
+  const skipGithub = Boolean(opts.skipGithub);
+  const requireWorkTree = opts.requireWorkTree !== false;
+  const checkProjectScope = Boolean(opts.checkProjectScope);
+  const nodeCheck = opts.nodeCheck ?? checkNodeVersion;
+  const gitRunner = opts.gitRunner ?? defaultGitRunner;
+  const gh = opts.gh ?? preflightGh;
+  const projectScope = opts.projectScope ?? checkProjectScopes;
+
+  const checks = [checkNode(nodeCheck)];
+
+  const gitAvailable = checkGitAvailable(gitRunner);
+  checks.push(gitAvailable);
+  // The inside-work-tree probe only makes sense when git itself resolved;
+  // if git is missing the rev-parse error is redundant noise.
+  let gitInitialized = false;
+  if (gitAvailable.ok) {
+    const workTree = checkInsideWorkTree(gitRunner);
+    gitInitialized = workTree.ok;
+    if (requireWorkTree) {
+      checks.push(workTree);
+    } else {
+      // Non-fatal detection: record whether we are inside a git repo but
+      // never fail the gate on it — `bootstrap-new.js` can run pre-init and
+      // collect the remote/branch/owner in later steps.
+      checks.push({
+        name: 'git-work-tree',
+        ok: true,
+        gitInitialized,
+        detail: gitInitialized
+          ? 'inside a git work tree'
+          : 'not a git repo yet — will be collected in later steps',
+      });
+    }
+  }
+
+  if (!skipGithub) {
+    checks.push(await checkGh(gh));
+    if (checkProjectScope) {
+      checks.push(await projectScope());
+    }
+  }
+
+  const ok = checks.every((c) => c.ok);
+  return { ok, gitInitialized, checks };
+}