arkgate 4.8.19 → 4.8.21

package/bin/lib/start-install-recovery.mjs

@@ -0,0 +1,156 @@
+/**
+ * Classified next steps when start / start --apply package install fails.
+ *
+ * Callers render `formatStartPackageInstallFailure`. Classification, Age window,
+ * pin-aware npx, and AgeExclude-must-be-in-config stay behind this module.
+ */
+import { spawnSync } from 'node:child_process';
+import { arkPackageRecoveryCommand } from './package-manager.mjs';
+
+const AGE_MARK = /ERR_PNPM_NO_MATURE_MATCHING_VERSION|minimumReleaseAge/i;
+const AGE_EXCLUDE_LINE =
+  'To add it locally later: put arkgate on minimumReleaseAgeExclude in pnpm config or pnpm-workspace.yaml (a CLI flag is not enough), or wait until the release is old enough.';
+const BIN_NOTE =
+  '`arkgate-check` is a command in the arkgate package — not its own npm package.';
+
+/**
+ * @param {unknown} hostOutput
+ * @returns {string[]}
+ */
+function hostOutputTail(hostOutput) {
+  if (!hostOutput || !String(hostOutput).trim()) return [];
+  return String(hostOutput)
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim())
+    .slice(-6);
+}
+
+/**
+ * Exact npm version for `npx --package=arkgate@<pin>` when Age blocked add.
+ * @param {string|undefined} packageVersion
+ * @param {string|undefined} installCommand
+ * @returns {string|null}
+ */
+export function resolveStartInstallPackagePin(packageVersion, installCommand) {
+  const fromArg = String(packageVersion ?? '')
+    .trim()
+    .replace(/^arkgate@/i, '')
+    .replace(/^\^/, '')
+    .replace(/^v/i, '');
+  if (/^\d+\.\d+\.\d+/.test(fromArg)) return fromArg.match(/^\d+\.\d+\.\d+/)?.[0] ?? null;
+  const fromCmd = String(installCommand ?? '').match(/arkgate@\^?v?(\d+\.\d+\.\d+)/i);
+  return fromCmd?.[1] ?? null;
+}
+
+/**
+ * @typedef {{ kind: 'pnpm-age', ageWindow: string, headline: string }} PnpmAgeInstallFailure
+ * @typedef {{ kind: 'generic', hostTail: string[] }} GenericInstallFailure
+ * @typedef {PnpmAgeInstallFailure | GenericInstallFailure} ClassifiedStartInstallFailure
+ */
+
+/**
+ * Classify captured package-manager stdout+stderr. Age is one class.
+ * @param {unknown} hostOutput
+ * @returns {ClassifiedStartInstallFailure}
+ */
+export function classifyStartInstallFailure(hostOutput) {
+  const text = String(hostOutput ?? '');
+  if (AGE_MARK.test(text)) {
+    const days = text.match(/(\d+)\s*days?/i)?.[1];
+    const ageWindow = days ? `${days} days` : 'a cooling-off window';
+    const headline = days
+      ? `This repo waits before trusting new npm packages (pnpm Age — ${days} days).`
+      : 'This repo waits before trusting new npm packages (pnpm Age).';
+    return { kind: 'pnpm-age', ageWindow, headline };
+  }
+  return { kind: 'generic', hostTail: hostOutputTail(text) };
+}
+
+/**
+ * Plain Age headline, or null. Kept for the #268 one-liner tests.
+ * @param {unknown} hostOutput
+ * @returns {string|null}
+ */
+export function explainPnpmMaturityBlock(hostOutput) {
+  const classified = classifyStartInstallFailure(hostOutput);
+  return classified.kind === 'pnpm-age' ? classified.headline : null;
+}
+
+/**
+ * @typedef {{
+ *   kind: 'pnpm-age' | 'generic',
+ *   ageWindow?: string,
+ *   primaryCommand: string,
+ *   replayInstallCommand: string | null,
+ *   lines: string[],
+ * }} StartInstallRecovery
+ */
+
+/**
+ * Typed next-step for a failed start package install.
+ * Age never replays the doomed add; generic still names the exact command.
+ * @param {{
+ *   exitStatus: number,
+ *   installCommand: string,
+ *   hostOutput?: string,
+ *   packageVersion?: string,
+ * }} input
+ * @returns {StartInstallRecovery}
+ */
+export function startInstallRecovery(input) {
+  const exitStatus = input?.exitStatus ?? 1;
+  const installCommand = input?.installCommand ?? '';
+  const classified = classifyStartInstallFailure(input?.hostOutput);
+  const pin = resolveStartInstallPackagePin(input?.packageVersion, installCommand);
+  const honesty = `Package install failed (exit ${exitStatus}). Setup files are written; the local command is not installed yet.`;
+  if (classified.kind === 'pnpm-age') {
+    const doctor = arkPackageRecoveryCommand(
+      'arkgate-check',
+      '--doctor',
+      pin ? `arkgate@${pin}` : undefined
+    );
+    return {
+      kind: 'pnpm-age',
+      ageWindow: classified.ageWindow,
+      primaryCommand: doctor,
+      replayInstallCommand: null,
+      lines: [classified.headline, honesty, `  ${doctor}`, BIN_NOTE, AGE_EXCLUDE_LINE],
+    };
+  }
+  const doctor = arkPackageRecoveryCommand('arkgate-check', '--doctor');
+  return {
+    kind: 'generic',
+    primaryCommand: installCommand,
+    replayInstallCommand: installCommand,
+    lines: [...classified.hostTail, honesty, `  ${installCommand}`, `  ${doctor}`, BIN_NOTE],
+  };
+}
+
+/**
+ * Red next-step when post-apply package install fails.
+ * Host files may already be written; local bins may be missing.
+ * @param {{
+ *   exitStatus: number,
+ *   installCommand: string,
+ *   hostOutput?: string,
+ *   packageVersion?: string,
+ * }} input
+ */
+export function formatStartPackageInstallFailure(input) {
+  return startInstallRecovery(input).lines.join('\n');
+}
+
+/** Pipe the package manager so recovery can hide maturity internals. */
+export function runStartPackageInstall(command, commandArgs, cwd) {
+  const result = spawnSync(command, commandArgs, {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+  });
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}

package/bin/lib/start-preview.mjs

@@ -5,7 +5,6 @@ import os from 'node:os';
 import path from 'node:path';
 import {
   arkCommand,
-  arkPackageRecoveryCommand,
   buildArchitectureRecommendation,
   START_APPLY_REFUSE_FOOTER,
 } from '../ark-shared.mjs';
@@ -218,59 +217,6 @@ function commands(root, args, helpers) {
   return result;
 }
 
-/**
- * Plain one-liner for pnpm minimumReleaseAge / ERR_PNPM_NO_MATURE_MATCHING_VERSION.
- * Host dumps stay out of the recovery — stranger needs one next step.
- */
-export function explainPnpmMaturityBlock(hostOutput) {
-  const text = String(hostOutput ?? '');
-  if (!/ERR_PNPM_NO_MATURE_MATCHING_VERSION|minimumReleaseAge/i.test(text)) return null;
-  const days = text.match(/(\d+)\s*days?/i)?.[1];
-  const window = days ? `${days} days` : 'a cooling-off window';
-  return `This repo blocks packages younger than ${window} — pin an older release or exclude arkgate temporarily.`;
-}
-
-/** Pipe the package manager so recovery can hide maturity internals. */
-export function runStartPackageInstall(command, commandArgs, cwd) {
-  const result = spawnSync(command, commandArgs, {
-    cwd,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    encoding: 'utf8',
-  });
-  return {
-    status: result.status ?? 1,
-    stdout: result.stdout ?? '',
-    stderr: result.stderr ?? '',
-  };
-}
-
-/**
- * Red next-step when post-apply package install fails.
- * Host files may already be written; local bins may be missing.
- */
-export function formatStartPackageInstallFailure({ exitStatus, installCommand, hostOutput }) {
-  const doctor = arkPackageRecoveryCommand('arkgate-check', '--doctor');
-  const maturity = explainPnpmMaturityBlock(hostOutput);
-  const lines = [];
-  if (maturity) {
-    lines.push(maturity);
-  } else if (hostOutput && String(hostOutput).trim()) {
-    const tail = String(hostOutput)
-      .split('\n')
-      .map((line) => line.trimEnd())
-      .filter((line) => line.trim())
-      .slice(-6);
-    if (tail.length) lines.push(...tail);
-  }
-  lines.push(
-    `Package install failed (exit ${exitStatus}). Setup files are written; the local command is not installed yet.`,
-    `  ${installCommand}`,
-    `  ${doctor}`,
-    '`arkgate-check` is a command in the arkgate package — not its own npm package.'
-  );
-  return lines.join('\n');
-}
-
 /**
  * @param {object} preview
  * @param {{ applying?: boolean }} [options] when applying=true, do not claim “no files were changed”

package/bin/lib/upgrade-behavior-changes.mjs

@@ -0,0 +1,83 @@
+/**
+ * Per-version upgrade behavior changes.
+ *
+ * This table is the package source for migration notes. CHANGELOG.md must
+ * carry the same sentences (Unreleased / 4.8.21, including the 4.8.20
+ * coverage.symbol note). Post-upgrade verification prints these lines so an
+ * agent reads them before editing code.
+ *
+ * Shipped with the package (`bin/lib` is in the published `files` list).
+ */
+
+/** @typedef {{ version: string, note: string }} UpgradeBehaviorChange */
+
+/** @type {readonly UpgradeBehaviorChange[]} */
+export const UPGRADE_BEHAVIOR_CHANGES = Object.freeze([
+  Object.freeze({
+    version: '4.8.20',
+    note: 'coverage.symbol now requires a real declaration (some green repos turn red)',
+  }),
+  Object.freeze({
+    version: '4.8.21',
+    note: 'a bare mention of an invariant id no longer counts as coverage (only describe/it titles or declarations, incl. type/interface/enum)',
+  }),
+  Object.freeze({
+    version: '4.8.21',
+    note: "upgrade exit code 3 = applied but red. Scripts comparing against 1 must switch to 'non-zero'",
+  }),
+]);
+
+/**
+ * @param {string} version
+ * @returns {number[]}
+ */
+function versionParts(version) {
+  return String(version)
+    .replace(/^v/, '')
+    .split('.')
+    .map((part) => {
+      const match = /^(\d+)/.exec(part);
+      return match ? Number(match[1]) : 0;
+    });
+}
+
+/**
+ * @param {string} left
+ * @param {string} right
+ * @returns {-1|0|1}
+ */
+export function compareUpgradeVersions(left, right) {
+  const a = versionParts(left);
+  const b = versionParts(right);
+  const length = Math.max(a.length, b.length);
+  for (let index = 0; index < length; index += 1) {
+    const delta = (a[index] ?? 0) - (b[index] ?? 0);
+    if (delta !== 0) return delta < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * @param {UpgradeBehaviorChange} row
+ * @returns {string}
+ */
+export function formatBehaviorChange(row) {
+  return `${row.version}: ${row.note}`;
+}
+
+/**
+ * Lines from the shipped table.
+ * Omit `upTo` to return every note in this package (the post-upgrade default:
+ * the build that implements a note must show it, even before the version bump).
+ * Pass `upTo` to keep notes whose version is less than or equal to that release.
+ *
+ * @param {string} [upTo]
+ * @returns {string[]}
+ */
+export function behaviorChangeLines(upTo) {
+  const rows =
+    typeof upTo === 'string' && upTo.trim()
+      ? UPGRADE_BEHAVIOR_CHANGES.filter((row) => compareUpgradeVersions(row.version, upTo) <= 0)
+      : UPGRADE_BEHAVIOR_CHANGES;
+  return rows.map((row) => formatBehaviorChange(row));
+}

package/bin/lib/upgrade-command.mjs

@@ -10,6 +10,13 @@ import {
   formatPackageInstallDecisionHuman,
 } from '../ark-shared.mjs';
 import { describePackageVersionDualTruth } from './field-install.mjs';
+import {
+  exitCodeFor,
+  formatBlockedAssets,
+  formatPostUpgradeHuman,
+  runPostUpgradeVerification,
+  upgradeOutcome,
+} from './upgrade-outcome.mjs';
 import { __packageRoot } from './gate-files.mjs';
 import {
   applyManagedUpgrade,
@@ -316,15 +323,13 @@ export function buildUpgradeNextCommand(args, planDigest) {
   return arkCommand(args.root, 'arkgate', argsStr);
 }
 
-function verify(root, json, arkCheck, runArkCheck) {
-  const args = ['--root', root, '--config', 'ark.config.json', '--strict-merge'];
-  if (!json) return { exitCode: runArkCheck(args, { cwd: root }) };
-  const result = spawnSync(process.execPath, [arkCheck, ...args, '--json'], {
-    cwd: root,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    encoding: 'utf8',
-  });
-  return { exitCode: result.status ?? 1, stderr: result.stderr?.trim() || undefined };
+function stampBlockedNextCommands(plan, args) {
+  if ((plan?.summary?.blocked ?? 0) === 0) return plan;
+  const command = buildUpgradeNextCommand({ ...args, acceptConflicts: true }, plan.planDigest);
+  for (const asset of plan.assets ?? []) {
+    if (asset.blocked) asset.nextCommand = command;
+  }
+  return plan;
 }
 
 function runProjectLocalCli({ root, script, argv }) {
@@ -544,11 +549,14 @@ export function runUpgradeCommand(args, dependencies) {
     }).status ?? 1;
   }
 
-  const plan = planManagedUpgrade(root, {
-    tools: args.tools,
-    acceptConflicts: args.acceptConflicts,
-    refreshSkills: args.refreshSkills === true,
-  });
+  const plan = stampBlockedNextCommands(
+    planManagedUpgrade(root, {
+      tools: args.tools,
+      acceptConflicts: args.acceptConflicts,
+      refreshSkills: args.refreshSkills === true,
+    }),
+    args
+  );
   if (!args.apply) {
     const wouldWrite = plan.summary?.wouldWrite ?? 0;
     const blocked = plan.summary?.blocked ?? 0;
@@ -577,11 +585,14 @@ export function runUpgradeCommand(args, dependencies) {
       );
     } else {
       renderManagedUpgrade(plan, {
-        next: needsApply
-          ? args.install
-            ? `Update the package and recompute this preview with: ${command}`
-            : `Apply the exact preview with: ${command}`
-          : undefined,
+        next:
+          blocked > 0
+            ? undefined
+            : needsApply
+              ? args.install
+                ? `Update the package and recompute this preview with: ${command}`
+                : `Apply the exact preview with: ${command}`
+              : undefined,
         skillDrift,
         hostSelection: hostHonesty,
       });
@@ -600,54 +611,80 @@ export function runUpgradeCommand(args, dependencies) {
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     console.error(message);
-    return 2;
+    return exitCodeFor(upgradeOutcome({ error }));
   }
   if (applied.blocked) {
+    stampBlockedNextCommands(applied, args);
     const command = buildUpgradeNextCommand(
       { ...args, acceptConflicts: true },
       applied.planDigest
     );
+    const refusal = formatBlockedAssets(applied, { refused: true }).join('\n');
+    console.error(refusal);
     if (args.json) {
       console.log(
         managedUpgradeJson(applied, {
           blocked: true,
+          outcome: 'blocked',
           reasonCode: applied.reasonCode ?? 'managed-consent-required',
           nextCommand: command,
         })
       );
     } else {
-      renderManagedUpgrade(applied, {
-        next: 'Preview again with --accept-conflicts, then use that preview\'s exact next command.',
-      });
+      renderManagedUpgrade(applied, { refused: true });
     }
-    return 1;
+    return exitCodeFor(upgradeOutcome({ blocked: true }));
   }
   if (applied.nothingToApply && !applied.applied) {
-    if (args.json) console.log(JSON.stringify(applied, null, 2));
+    const idle = upgradeOutcome({ nothingToApply: true, applied: false });
+    if (args.json) console.log(JSON.stringify({ ...applied, outcome: idle.kind }, null, 2));
     else {
       renderManagedUpgrade(applied);
       console.log('No managed content writes pending.');
     }
-    return 0;
+    return exitCodeFor(idle);
   }
-  const verification = args.strict
-    ? { mode: 'strict-merge', ...verify(root, args.json, dependencies.arkCheck, dependencies.runArkCheck) }
-    : { mode: 'skipped', exitCode: 0 };
+  const postUpgrade = runPostUpgradeVerification(root, {
+    strict: args.strict,
+    arkCheck: dependencies.arkCheck,
+    packageVersion: dependencies.cliVersion,
+    ...(dependencies.checkResult ? { checkResult: dependencies.checkResult } : {}),
+    ...(typeof dependencies.spawnArchitectureCheck === 'function'
+      ? { checkResult: dependencies.spawnArchitectureCheck(root) }
+      : {}),
+  });
+  const outcome = upgradeOutcome({ applied: true, postUpgrade });
+  const verification = {
+    mode: postUpgrade.mode,
+    exitCode: postUpgrade.exitCode,
+    ...(postUpgrade.stderr ? { stderr: postUpgrade.stderr } : {}),
+  };
   const dualTruth = describePackageVersionDualTruth(root);
   const skillDrift = buildSkillDriftSummary(applied);
   const hostHonesty = buildHostSelectionHonesty(applied);
   // FX05: post-upgrade verification block (advisory, notAScore).
   const postUpgradeChecks = buildPostUpgradeChecks(root, {
     cliVersion: dependencies.cliVersion,
-    verification,
+    verification: {
+      ...verification,
+      verdict: postUpgrade.verdict,
+      failing: postUpgrade.failing,
+    },
     dualTruth,
   });
+  const postUpgradePayload = {
+    verdict: postUpgrade.verdict,
+    failing: postUpgrade.failing,
+    behaviorChanges: postUpgrade.behaviorChanges,
+  };
   if (args.json) {
     console.log(
       JSON.stringify(
         {
           ...applied,
+          outcome: outcome.kind,
           verification,
+          postUpgrade: postUpgradePayload,
           skillDrift,
           hostSelection: hostHonesty,
           postUpgradeChecks,
@@ -673,6 +710,7 @@ export function runUpgradeCommand(args, dependencies) {
     );
   } else {
     renderManagedUpgrade(applied, { skillDrift, hostSelection: hostHonesty });
+    for (const line of formatPostUpgradeHuman(postUpgrade)) console.log(line);
     if (!args.strict) console.log('Architecture verification skipped (--no-strict).');
     if (args.install === false || dualTruth.dualTruth) {
       console.log(
@@ -690,5 +728,5 @@ export function runUpgradeCommand(args, dependencies) {
       console.log(`  [note] mcp: ${postUpgradeChecks.mcpNote}`);
     }
   }
-  return verification.exitCode;
+  return exitCodeFor(outcome);
 }