mandrel 1.62.0 → 1.64.0

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

@@ -286,7 +286,11 @@ export async function resolveFromPicker(ctx) {
 
   const normalized = choices.map(normalizePickerChoice);
   const rl = await ctx.getRl();
-  ctx.output.write(`${ctx.q.message}:\n`);
+  // The picker header uses `pickerMessage` when set, so a question can show
+  // list-oriented guidance here (e.g. "Select existing or press ENTER to create
+  // new one") while the manual-entry fall-through prompt (`askOnce`) uses the
+  // shorter `message` (e.g. "New GitHub repo name"). Falls back to `message`.
+  ctx.output.write(`${ctx.q.pickerMessage ?? ctx.q.message}:\n`);
   normalized.forEach((choice, index) => {
     ctx.output.write(`  ${index + 1}) ${choice.label}\n`);
   });

package/.agents/scripts/lib/detect-package-manager.js

@@ -1,11 +1,11 @@
 /**
  * detect-package-manager — shared lockfile-probe helper (Story #4048 B3).
  *
- * Five independent copies of this lockfile probe existed across the codebase:
+ * Several independent copies of this lockfile probe existed across the
+ * codebase before this consolidation:
  *   - `lib/cli/update.js#detectPackageManager`
  *   - `lib/bootstrap/project-bootstrap.js#detectPackageManager`
  *   - `lib/runtime-deps/preflight.js#detectPackageManager`
- *   - `lib/onboard/detect-stack.js#detectPackageManager`
  *   - `lib/worktree/node-modules-strategy.js#selectInstallCommand` (inline)
  *
  * This module is the single authoritative implementation. It uses the

package/.agents/scripts/lib/feedback-loop/graduator-core.js

@@ -238,183 +238,217 @@ export async function createFollowUpIssue({
  * @param {(record: object, finding: object) => object} [opts.spec.decorateRecord]
  * @returns {Promise<{ filed: object[], skipped: object[], errors: string[] }>}
  */
-export async function graduate({
+/**
+ * Validate the `graduate` preconditions (toggle, epicId, provider shape,
+ * currentRepo shape). Returns `null` when all preconditions pass, or a
+ * `{ skipped?, errors? }` partial-envelope the caller short-circuits on.
+ * Story #4075 — extracted from `graduate` so the orchestrating body holds
+ * no guard-chain branching.
+ */
+function checkGraduatePreconditions({
   epicId,
   provider,
-  config,
   currentRepo,
-  frameworkRepo,
-  gitRef = 'HEAD',
-  classifier = defaultClassifier,
-  ghPath = 'gh',
-  spawnImpl,
-  cwd,
-  logger,
+  config,
   spec,
 }) {
-  const envelope = { filed: [], skipped: [], errors: [] };
-  const decorate =
-    typeof spec.decorateRecord === 'function'
-      ? spec.decorateRecord
-      : (record) => record;
-
   if (!spec.isAutoFileEnabled(config)) {
-    envelope.skipped.push({ reason: 'toggle-disabled' });
-    return envelope;
+    return { skipped: [{ reason: 'toggle-disabled' }] };
   }
-
   if (!Number.isInteger(epicId) || epicId < 1) {
-    envelope.errors.push(`${spec.fnName}: missing or invalid epicId`);
-    return envelope;
+    return { errors: [`${spec.fnName}: missing or invalid epicId`] };
   }
   if (!provider || typeof provider.getTicketComments !== 'function') {
-    envelope.errors.push(`${spec.fnName}: provider lacks getTicketComments`);
-    return envelope;
+    return { errors: [`${spec.fnName}: provider lacks getTicketComments`] };
   }
   if (
     !currentRepo ||
     typeof currentRepo.owner !== 'string' ||
     typeof currentRepo.repo !== 'string'
   ) {
-    envelope.errors.push(`${spec.fnName}: missing currentRepo {owner,repo}`);
-    return envelope;
+    return { errors: [`${spec.fnName}: missing currentRepo {owner,repo}`] };
   }
+  return null;
+}
 
-  // 1. Read the structured comment off the Epic.
+/**
+ * Read the source structured comment off the Epic and parse its findings.
+ * Returns `{ findings }` on success, or `{ skipped?, errors? }` for the
+ * no-comment / parse-empty / fetch-error short-circuits. Story #4075 —
+ * extracted from `graduate`.
+ */
+async function loadGraduateFindings({ epicId, provider, spec }) {
   let comments;
   try {
     comments = await provider.getTicketComments(epicId);
   } catch (err) {
-    envelope.errors.push(
-      `getTicketComments failed for epic #${epicId}: ${err?.message ?? err}`,
-    );
-    return envelope;
-  }
-  if (!Array.isArray(comments) || comments.length === 0) {
-    envelope.skipped.push({ reason: spec.noCommentReason });
-    return envelope;
+    return {
+      errors: [
+        `getTicketComments failed for epic #${epicId}: ${err?.message ?? err}`,
+      ],
+    };
   }
-  const matched = comments.filter(
+  const matched = (Array.isArray(comments) ? comments : []).filter(
     (c) => typeof c?.body === 'string' && c.body.includes(spec.commentMarker),
   );
   if (matched.length === 0) {
-    envelope.skipped.push({ reason: spec.noCommentReason });
-    return envelope;
+    return { skipped: [{ reason: spec.noCommentReason }] };
   }
-  const sourceComment = matched[matched.length - 1];
-
-  // 2. Parse findings.
-  const findings = spec.parseFindings(sourceComment.body);
+  const findings = spec.parseFindings(matched[matched.length - 1].body);
   if (findings.length === 0) {
-    envelope.skipped.push({ reason: 'no-non-blocking-findings' });
-    return envelope;
+    return { skipped: [{ reason: 'no-non-blocking-findings' }] };
   }
+  return { findings };
+}
 
-  // 3. For each finding, route → idempotency probe → file.
-  for (const finding of findings) {
-    const exists = await probePathExists({
-      ref: gitRef,
-      path: finding.path,
-      spawnImpl,
-      cwd,
-    });
-    if (!exists) {
-      envelope.skipped.push(
-        decorate(
-          {
-            index: finding.index,
-            reason: 'file-removed',
-            path: finding.path,
-            severity: finding.severity,
-          },
-          finding,
-        ),
-      );
-      continue;
-    }
+/**
+ * Route a single finding (path-exists probe → repo routing → idempotency
+ * probe → file) and fold the outcome into the running envelope. Story #4075
+ * — extracted from `graduate`'s per-finding loop body.
+ */
+async function processGraduateFinding({
+  finding,
+  envelope,
+  decorate,
+  epicId,
+  currentRepo,
+  frameworkRepo,
+  classifier,
+  gitRef,
+  ghPath,
+  spawnImpl,
+  cwd,
+  logger,
+  spec,
+}) {
+  const skip = (reason) =>
+    envelope.skipped.push(
+      decorate(
+        {
+          index: finding.index,
+          reason,
+          path: finding.path,
+          severity: finding.severity,
+        },
+        finding,
+      ),
+    );
 
-    const source = classifier(finding.path, null);
-    const routedRepo =
-      source === 'framework' && frameworkRepo ? frameworkRepo : currentRepo;
+  const exists = await probePathExists({
+    ref: gitRef,
+    path: finding.path,
+    spawnImpl,
+    cwd,
+  });
+  if (!exists) return skip('file-removed');
 
-    const isCrossRepo =
-      routedRepo.owner !== currentRepo.owner ||
-      routedRepo.repo !== currentRepo.repo;
-    if (isCrossRepo) {
-      logger?.info?.(spec.buildCrossRepoLog({ finding, routedRepo, source }));
-      envelope.skipped.push(
-        decorate(
-          {
-            index: finding.index,
-            reason: 'cross-repo-deferred',
-            path: finding.path,
-            severity: finding.severity,
-          },
-          finding,
-        ),
-      );
-      continue;
-    }
+  const source = classifier(finding.path, null);
+  const routedRepo =
+    source === 'framework' && frameworkRepo ? frameworkRepo : currentRepo;
+  const isCrossRepo =
+    routedRepo.owner !== currentRepo.owner ||
+    routedRepo.repo !== currentRepo.repo;
+  if (isCrossRepo) {
+    logger?.info?.(spec.buildCrossRepoLog({ finding, routedRepo, source }));
+    return skip('cross-repo-deferred');
+  }
 
-    const idMarker = spec.buildIdempotencyMarker(epicId, finding.index);
-    const alreadyFiled = await probeMarkerExists({
-      marker: idMarker,
-      owner: routedRepo.owner,
-      repo: routedRepo.repo,
-      ghPath,
-      spawnImpl,
-      cwd,
-    });
-    if (alreadyFiled) {
-      envelope.skipped.push(
-        decorate(
-          {
-            index: finding.index,
-            reason: 'already-filed',
-            path: finding.path,
-            severity: finding.severity,
-          },
-          finding,
-        ),
-      );
-      continue;
-    }
+  const idMarker = spec.buildIdempotencyMarker(epicId, finding.index);
+  const alreadyFiled = await probeMarkerExists({
+    marker: idMarker,
+    owner: routedRepo.owner,
+    repo: routedRepo.repo,
+    ghPath,
+    spawnImpl,
+    cwd,
+  });
+  if (alreadyFiled) return skip('already-filed');
+
+  const { title, body, labels } = spec.buildFollowUp({
+    finding,
+    source,
+    epicId,
+    idMarker,
+  });
+  const created = await createFollowUpIssue({
+    owner: routedRepo.owner,
+    repo: routedRepo.repo,
+    title,
+    body,
+    labels,
+    ghPath,
+    spawnImpl,
+    cwd,
+  });
+  if (created.error) {
+    envelope.errors.push(
+      `finding ${finding.index} (${finding.path}): ${created.error}`,
+    );
+    return;
+  }
+  envelope.filed.push(
+    decorate(
+      {
+        index: finding.index,
+        severity: finding.severity,
+        path: finding.path,
+        source,
+        repo: `${routedRepo.owner}/${routedRepo.repo}`,
+        url: created.url,
+      },
+      finding,
+    ),
+  );
+}
+
+export async function graduate({
+  epicId,
+  provider,
+  config,
+  currentRepo,
+  frameworkRepo,
+  gitRef = 'HEAD',
+  classifier = defaultClassifier,
+  ghPath = 'gh',
+  spawnImpl,
+  cwd,
+  logger,
+  spec,
+}) {
+  const envelope = { filed: [], skipped: [], errors: [] };
+  const decorate =
+    typeof spec.decorateRecord === 'function'
+      ? spec.decorateRecord
+      : (record) => record;
 
-    const { title, body, labels } = spec.buildFollowUp({
+  const precondition = checkGraduatePreconditions({
+    epicId,
+    provider,
+    currentRepo,
+    config,
+    spec,
+  });
+  if (precondition) return { ...envelope, ...precondition };
+
+  const loaded = await loadGraduateFindings({ epicId, provider, spec });
+  if (!loaded.findings) return { ...envelope, ...loaded };
+
+  for (const finding of loaded.findings) {
+    await processGraduateFinding({
       finding,
-      source,
+      envelope,
+      decorate,
       epicId,
-      idMarker,
-    });
-    const created = await createFollowUpIssue({
-      owner: routedRepo.owner,
-      repo: routedRepo.repo,
-      title,
-      body,
-      labels,
+      currentRepo,
+      frameworkRepo,
+      classifier,
+      gitRef,
       ghPath,
       spawnImpl,
       cwd,
+      logger,
+      spec,
     });
-    if (created.error) {
-      envelope.errors.push(
-        `finding ${finding.index} (${finding.path}): ${created.error}`,
-      );
-      continue;
-    }
-    envelope.filed.push(
-      decorate(
-        {
-          index: finding.index,
-          severity: finding.severity,
-          path: finding.path,
-          source,
-          repo: `${routedRepo.owner}/${routedRepo.repo}`,
-          url: created.url,
-        },
-        finding,
-      ),
-    );
   }
 
   return envelope;

package/.agents/scripts/lib/onboard/init-tail.js

@@ -2,18 +2,17 @@
  * init-tail.js — post-bootstrap onboarding tail for `mandrel init`.
  *
  * Called by `mandrel init` after `bootstrap.js` completes successfully on
- * the "configure now" path. Sequences the four phases that walk an operator
+ * the "configure now" path. Sequences the three phases that walk an operator
  * from a freshly bootstrapped project to a ready-to-plan workspace:
  *
- *   Phase 1 — Detect the consumer stack (lib/onboard/detect-stack.js).
- *   Phase 2 — Offer to scaffold missing docsContextFiles (scaffold-docs.js).
- *   Phase 3 — Run `mandrel doctor` as a readiness gate.
- *   Phase 4 — Print the /plan handoff next-step text.
+ *   Phase 1 — Offer to scaffold missing docsContextFiles (scaffold-docs.js).
+ *   Phase 2 — Run `mandrel doctor` as a readiness gate.
+ *   Phase 3 — Print the /plan handoff next-step text.
  *
  * The whole tail is idempotent: re-running after an already-onboarded project
- * re-detects, re-checks, and re-offers scaffolding without duplicating stubs
- * (the scaffolder only writes genuinely absent files) and without modifying
- * anything (doctor is read-only).
+ * re-checks and re-offers scaffolding without duplicating stubs (the scaffolder
+ * only writes genuinely absent files) and without modifying anything (doctor is
+ * read-only).
  *
  * Injectable seams: `runDoctor`, `stdout`, `confirmScaffold`, and `isTTY`
  * allow the unit suite to drive every branch without real I/O.
@@ -22,10 +21,9 @@
  */
 
 import { spawnSync as defaultSpawnSync } from 'node:child_process';
-import fs from 'node:fs';
 import path from 'node:path';
+import readline from 'node:readline/promises';
 
-import { detectStack } from './detect-stack.js';
 import { STUB_MARKER, scaffoldDocs } from './scaffold-docs.js';
 
 // ---------------------------------------------------------------------------
@@ -38,7 +36,7 @@ import { STUB_MARKER, scaffoldDocs } from './scaffold-docs.js';
  * @type {string}
  */
 export const PLAN_HANDOFF_TEXT =
-  '\n✅  Mandrel is ready. Start your first Epic:\n\n' +
+  '\n✅  Mandrel is ready. Start your first project:\n\n' +
   '    /plan --idea "<one-line description of what you want to build>"\n\n' +
   'Or, if you already have a `type::epic` Issue open:\n\n' +
   '    /plan <epicId>\n';
@@ -47,24 +45,6 @@ export const PLAN_HANDOFF_TEXT =
 // Internal helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Format a stack-detection result as a human-readable report line.
- *
- * @param {{ packageManager: string|null, testRunner: string|null, primaryLanguage: string|null }} stack
- * @returns {string}
- */
-function formatStackReport(stack) {
-  const pm = stack.packageManager ?? '(unknown)';
-  const runner = stack.testRunner ?? '(unknown)';
-  const lang = stack.primaryLanguage ?? '(unknown)';
-  return (
-    '\n[init] Stack detection:\n' +
-    `  Package manager : ${pm}\n` +
-    `  Test runner     : ${runner}\n` +
-    `  Primary language: ${lang}\n`
-  );
-}
-
 /**
  * Format a list of missing docs as a human-readable report (no prompt).
  *
@@ -75,30 +55,54 @@ function formatMissingList(missing) {
   if (missing.length === 0) return '';
   const list = missing.map((f) => `  • ${f}`).join('\n');
   return (
-    '\n[init] The following docsContextFiles are missing — agents load\n' +
-    'these before every task:\n' +
+    '\n[Final Checks] The following docsContextFiles are missing,\n' +
+    'agents will load degraded context until you create them:\n' +
     `${list}\n`
   );
 }
 
 /** Prompt text shown only on a TTY when asking to scaffold. */
-const SCAFFOLD_PROMPT = '\nScaffold stubs now? [y/N]: ';
+const SCAFFOLD_PROMPT = '\nCreate placeholders? [Y/n]: ';
 
 /**
- * Synchronous y/N read from stdin (fd 0). Returns `false` on any read error
- * or when the user enters something other than `y` / `yes`.
+ * Async y/N read from stdin via `node:readline` (mirrors the prompt mechanism
+ * in `bootstrap.js`). Returns on Enter and never blocks waiting for EOF the way
+ * `fs.readFileSync(0)` did — that EOF-blocking read hung `mandrel init` on an
+ * interactive TTY. Yes is the default (`[Y/n]`): a bare Enter — or anything but
+ * an explicit `n`/`no` — resolves to `true` (create the placeholders), since the
+ * missing docs are known-needed and the stubs carry a `MANDREL:STUB` marker the
+ * `/plan` preflight still flags until they are fleshed out. A read error
+ * resolves to `false` so a genuine I/O failure never writes unattended. The
+ * prompt text is written by the caller via `stdout`, so the question string
+ * passed here is empty.
+ *
+ * `terminal: false` is **load-bearing**: with terminal mode on (the default
+ * when stdout is a TTY) readline emits cursor-control escapes
+ * (`\x1b[1G\x1b[0J`) that erase the `Create placeholders? [Y/n]:` prompt already
+ * written via the caller's `stdout`, leaving the operator staring at a blank,
+ * dead-looking line. Disabling terminal mode preserves the pre-written prompt
+ * and reads the line via the TTY's cooked-mode echo. `createInterface` is
+ * injectable so a test can assert this option is set (regression guard).
  *
- * @returns {boolean}
+ * @param {{ createInterface?: typeof readline.createInterface }} [opts]
+ * @returns {Promise<boolean>}
  */
-function syncConfirm() {
-  let answer = '';
+export async function readConfirm({
+  createInterface = readline.createInterface,
+} = {}) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false,
+  });
   try {
-    const buf = fs.readFileSync(0, 'utf8');
-    answer = buf.split('\n', 1)[0].trim().toLowerCase();
+    const answer = (await rl.question('')).trim().toLowerCase();
+    return answer !== 'n' && answer !== 'no';
   } catch {
-    answer = '';
+    return false;
+  } finally {
+    rl.close();
   }
-  return answer === 'y' || answer === 'yes';
 }
 
 // ---------------------------------------------------------------------------
@@ -119,14 +123,13 @@ function syncConfirm() {
  *   - Run `mandrel doctor`; injectable for tests.
  * @param {boolean} [opts.isTTY] - Whether stdin is a TTY (defaults to
  *   `Boolean(process.stdin.isTTY)`).
- * @returns {{
- *   stack: { packageManager: string|null, testRunner: string|null, primaryLanguage: string|null },
+ * @returns {Promise<{
  *   scaffoldResult: object,
  *   doctorStatus: number,
  *   ok: boolean,
- * }}
+ * }>}
  */
-export function runInitTail({
+export async function runInitTail({
   root,
   stdout = (s) => process.stdout.write(s),
   confirmScaffold,
@@ -140,7 +143,7 @@ export function runInitTail({
   // it. When using the default, auto-decline on non-TTY so the scaffolder
   // never writes unattended.
   const usingDefaultConfirm = confirmScaffold == null;
-  const confirmFn = confirmScaffold ?? (() => syncConfirm());
+  const confirmFn = confirmScaffold ?? readConfirm;
 
   // Default doctor runner — spawns `mandrel doctor` via the locally installed
   // bin; inherits stdio so the report streams to the terminal.
@@ -159,21 +162,12 @@ export function runInitTail({
 
   const doctorFn = runDoctor ?? defaultRunDoctor;
 
-  // --- Phase 1: Detect the stack -------------------------------------------
-  let stack;
-  try {
-    stack = detectStack(projectRoot);
-  } catch {
-    stack = { packageManager: null, testRunner: null, primaryLanguage: null };
-  }
-  stdout(formatStackReport(stack));
-
-  // --- Phase 2: Offer to scaffold missing docsContextFiles -----------------
+  // --- Phase 1: Offer to scaffold missing docsContextFiles -----------------
   const preview = scaffoldDocs({ root: projectRoot, write: false });
   let scaffoldResult = preview;
 
   if (preview.missing.length === 0) {
-    stdout('\n[init] All docsContextFiles are present.\n');
+    stdout('\n[Final Checks] All docsContextFiles are present.\n');
   } else {
     stdout(formatMissingList(preview.missing));
     // On non-TTY without an injected confirm, auto-decline so the scaffolder
@@ -181,38 +175,35 @@ export function runInitTail({
     // the prompt and consult the confirm function.
     const canPrompt = tty || !usingDefaultConfirm;
     if (canPrompt) stdout(SCAFFOLD_PROMPT);
-    const accepted = canPrompt ? confirmFn() : false;
+    const accepted = canPrompt ? await confirmFn() : false;
     if (accepted) {
       scaffoldResult = scaffoldDocs({ root: projectRoot, write: true });
       if (scaffoldResult.created.length > 0) {
         stdout(
-          `[init] Scaffolded ${scaffoldResult.created.length} stub(s). ` +
+          `[Final Checks] Scaffolded ${scaffoldResult.created.length} stub(s). ` +
             `Each carries a \`${STUB_MARKER}\` marker — replace placeholder ` +
             'content before planning.\n',
         );
       }
     } else {
-      stdout(
-        '[init] Scaffolding declined. docsContextFiles are still missing — ' +
-          'agents will load degraded context until you create them.\n',
-      );
+      stdout('[Final Checks] Placeholders declined.\n');
     }
   }
 
-  // --- Phase 3: Readiness gate (mandrel doctor) ----------------------------
-  stdout('\n[init] Running mandrel doctor…\n');
+  // --- Phase 2: Readiness gate (mandrel doctor) ----------------------------
+  stdout('\n[Final Checks] Final installation summary via mandrel doctor…\n');
   const doctorResult = doctorFn();
   const doctorStatus = doctorResult?.status ?? 1;
 
   if (doctorStatus !== 0) {
     stdout(
-      '\n[init] ❌  Doctor check failed. Resolve the remedies above and\n' +
+      '\n[Final Checks] ❌  Doctor check failed. Resolve the remedies above and\n' +
         'then re-run: mandrel init\n',
     );
-    return { stack, scaffoldResult, doctorStatus, ok: false };
+    return { scaffoldResult, doctorStatus, ok: false };
   }
 
-  // --- Phase 4: Handoff to /plan -------------------------------------------
+  // --- Phase 3: Handoff to /plan -------------------------------------------
   stdout(PLAN_HANDOFF_TEXT);
-  return { stack, scaffoldResult, doctorStatus, ok: true };
+  return { scaffoldResult, doctorStatus, ok: true };
 }