@fiodos/cli 0.1.25 → 0.1.28

package/src/index.js

@@ -97,11 +97,16 @@ const { verifyManifest } = require('./verify');
 const {
   wireWebOrb, reportWireResult, connectOrbRegistries, reportRegistriesResult,
   connectOrbSession, reportSessionConnectResult,
+  connectOrbScreen, reportScreenConnectResult,
 } = require('./wireWeb');
 const { wireReactNativeOrb, reportReactNativeWire, connectRnSession } = require('./wireReactNative');
+const {
+  isShopifyThemeRoot, fetchStorefrontSnapshot, wireShopifyTheme, reportShopifyWire,
+} = require('./shopifyTheme');
 const { wireFlutterOrb, writeFlutterEnv, reportFlutterWire } = require('./wireFlutter');
 const { wireHandlers, reportHandlerResult } = require('./wireHandlers');
 const { wireSession, reportSessionResult } = require('./wireSession');
+const { wireScreen, reportScreenResult } = require('./wireScreen');
 const { offerWriteEnv, printEnvManualReminder } = require('./writeEnv');
 const { scoreSurface, computeSurface } = require('./scoreSurface');
 const { buildRunRecord, writeChangeRegistry } = require('./changeRegistry');
@@ -117,6 +122,8 @@ function arg(flag, fallback) {
 const VALUE_FLAGS = new Set([
   '--out', '--model', '--max-input-tokens', '--platform', '--api-key', '--api-url',
   '--spec', '--analysis-root',
+  // shopify (theme repo mode): the store's public domain for the catalog snapshot
+  '--store',
   // from-odata (closed-software mode)
   '--app-id', '--app-name', '--app-description', '--auth-ref', '--entities',
 ]);
@@ -168,6 +175,11 @@ function logUser(line) {
   console.log(`${cyan}◉${reset} ${blue}Fiodos${reset} · ${line}`);
 }
 
+/** Human-readable pointer to the per-run change registry written in the repo. */
+function changeLogUserMessage(paths) {
+  return `We saved a summary of every file we changed — see ${paths.mdRel} (past runs in .fyodos/changes/)`;
+}
+
 /**
  * Ask the developer to confirm before the analysis runs. `yes` continues; any
  * other answer (or `no`) cancels instantly — the command ends without analyzing.
@@ -192,9 +204,11 @@ function askProceed() {
   });
 }
 
-/** Spinner copy: "website" for web targets, "app" for mobile/native. */
+/** Spinner copy: "website" for web targets, "store" for Shopify, "app" for mobile/native. */
 function surfaceNoun(platform) {
-  return platform === 'web' ? 'website' : 'app';
+  if (platform === 'web') return 'website';
+  if (platform === 'shopify') return 'store';
+  return 'app';
 }
 
 function orbMountSpinnerLabel(platform) {
@@ -293,6 +307,20 @@ async function main() {
     }
   }
 
+  // ── Rewire-only mode: `fiodos rewire <dir>` or `fiodos <dir> --wire-only` ──
+  // Re-runs ONLY the handler wiring (verify → correct → retry, same loop as the
+  // install) from the saved artifacts of the LAST analysis. No re-analysis, no
+  // quota, no manifest publish — the repair path when some action ended up
+  // "manual" (Context/dashboard point developers here).
+  {
+    const pos = positionalArgs();
+    if (pos[0] === 'rewire' || process.argv.includes('--wire-only')) {
+      const target = pos[0] === 'rewire' ? pos[1] || '.' : pos[0] || '.';
+      await runRewireOnly(target);
+      return;
+    }
+  }
+
   // Consent gate: confirm before doing anything. `yes` continues; `no` (or any
   // other answer) cancels instantly — no analysis is run, the command just ends.
   const proceed = await askProceed();
@@ -329,7 +357,7 @@ async function main() {
   fs.mkdirSync(outDir, { recursive: true });
 
   const platformArg = (arg('--platform', '') || '').toLowerCase();
-  const KNOWN_PLATFORMS = ['web', 'mobile', 'flutter', 'ios', 'android'];
+  const KNOWN_PLATFORMS = ['web', 'mobile', 'flutter', 'ios', 'android', 'shopify'];
   const forcedPlatform = KNOWN_PLATFORMS.includes(platformArg) ? platformArg : null;
 
   // ── 1. Static route scan (cheap facts; also the route verifier's ground truth)
@@ -369,6 +397,24 @@ async function main() {
 
   // ── 2. Collect source files (rule-based, budget-aware) ────────────────────
   const { included, omitted, estimatedTokens } = collectFiles(analysisRoot, { maxInputTokens, platform });
+
+  // Shopify: the theme alone doesn't say WHAT the store sells. Fetch a PUBLIC
+  // storefront snapshot (collections + product sample) from the store's own
+  // endpoints and include it as synthetic FILE blocks (_fyodos/storefront/*)
+  // so the analysis personalizes routes/bubbles/examples to the REAL catalog
+  // — and so evidence verification has concrete files to point at. Fail-open:
+  // an unreachable store still gets the universal surface file.
+  if (platform === 'shopify') {
+    const storeDomain = arg('--store', process.env.FYODOS_SHOPIFY_STORE || '');
+    if (!storeDomain) {
+      logUser('Tip: add --store your-store.com so the analysis reads your live catalog (collections & products).');
+    }
+    const snapshot = await withSpinner('Reading your store\u2019s public catalog', () =>
+      fetchStorefrontSnapshot(storeDomain, { log: logDev }),
+    );
+    included.push(...snapshot.files);
+  }
+
   fs.writeFileSync(path.join(outDir, 'files-sent.json'), JSON.stringify({
     included: included.map((f) => f.rel),
     omitted,
@@ -398,6 +444,10 @@ async function main() {
   // The AI's "session" block: WHERE the app's auth/session state lives, so the
   // orb's isAuthenticated/getUserId are wired automatically (no manual step).
   let sessionWiring = null;
+  // The AI's "screen" block: whether screens are URL-driven or CLIENT STATE,
+  // and where that state lives — so the orb knows which screen the user is on
+  // even when the URL never changes (see wireScreen.js).
+  let screenWiring = null;
   let analysisMeta = { engine: 'auto-manifest-v3-ai-first', model: null, costUSD: 0 };
   // Signed proof returned by the hosted-analysis proxy: it tells the publish
   // step the quota was already consumed at /v1/developer/analyze (no double
@@ -461,6 +511,7 @@ async function main() {
     evidence = parsed.evidence || {};
     wiring = parsed.wiring || {};
     sessionWiring = parsed.session || null;
+    screenWiring = parsed.screen || null;
     // Only meaningful when the developer passed --spec; the backend sanitizes
     // (context fields only, real intents only) before touching any override.
     specResets = (userSpec && parsed.specResets && typeof parsed.specResets === 'object')
@@ -475,7 +526,7 @@ async function main() {
     // Actions are always verified against real code. Routes are verified only
     // when there is filesystem ground truth (mobile); for web they are kept as
     // AI-proposed and flagged unverified in provenance.
-    ({ manifest, provenance } = verifyManifest(proposed, evidence, included, routes, { verifyRoutes }));
+    ({ manifest, provenance } = verifyManifest(proposed, evidence, included, routes, { verifyRoutes, platform }));
     ensureBackRoute(manifest, provenance);
     const droppedActions = provenance.actions.filter((a) => !a.included).length;
     const droppedRoutes = provenance.routes.filter((r) => !r.included).length;
@@ -484,7 +535,7 @@ async function main() {
     logUser('Analysis complete');
 
     fs.writeFileSync(path.join(outDir, 'evidence.json'), JSON.stringify({
-      evidence, wiring, session: sessionWiring, uncertain: parsed.uncertain || [],
+      evidence, wiring, session: sessionWiring, screen: screenWiring, uncertain: parsed.uncertain || [],
     }, null, 2));
     fs.writeFileSync(path.join(outDir, 'usage.json'), JSON.stringify({
       model, elapsedMs, usage,
@@ -618,6 +669,7 @@ async function main() {
     let handlerWireResult = null;
     let registryWireResult = null;
     let sessionWireResult = null;
+    let screenWireResult = null;
     const { runPostWireTest } = require('./postWireTest');
     const selfCorrect = !process.argv.includes('--no-self-correct');
     // Corrections follow the same key model as the analysis: hosted (proxy)
@@ -765,6 +817,46 @@ async function main() {
         }
       }
 
+      // Fourth pass — SCREEN-TRUTH wiring. For apps whose screens are CLIENT
+      // STATE (a section switcher) instead of URLs, connect the active-screen
+      // state to the orb so it truly knows where the user is: per-screen
+      // bubble, "you are already there" detection and screen-scoped context.
+      // Same consent/verification/revert model as session wiring.
+      if (screenWiring && !process.argv.includes('--no-orb-wire')) {
+        const handlerDeclined =
+          handlerResult &&
+          (handlerResult.status === 'declined' || handlerResult.status === 'declined-noninteractive');
+        if (!handlerDeclined) {
+          const handlerConsented =
+            handlerResult &&
+            (handlerResult.status === 'applied' || handlerResult.status === 'applied-untested');
+          const screenResult = await wireScreen(analysisRoot, {
+            screen: screenWiring,
+            colors: fyodosTermColors(),
+            quiet: !isVerbose(),
+            assumeYes: assumeYes || Boolean(handlerConsented),
+            noWire,
+            framework: 'web',
+            appName: manifest.appName,
+            runTest: !process.argv.includes('--no-wire-test'),
+            testRunner: runPostWireTest,
+          });
+          screenWireResult = screenResult;
+          report(() => reportScreenResult(screenResult, fyodosTermColors(), { quiet: !isVerbose() }));
+          if (
+            orbMounted &&
+            (screenResult.status === 'applied' || screenResult.status === 'applied-untested')
+          ) {
+            const connectedScreen = connectOrbScreen(analysisRoot, {
+              screenFileAbs: screenResult.screenFile,
+            });
+            report(() =>
+              reportScreenConnectResult(connectedScreen, fyodosTermColors(), { quiet: !isVerbose() }),
+            );
+          }
+        }
+      }
+
       // Finalize the install proof: now that the (slow) action wiring is done,
       // tell the dashboard the terminal status so its "actions connected" tick
       // turns green for real — never before wiring actually finished. Only do
@@ -779,6 +871,7 @@ async function main() {
           actionsStatus: status,
           actionsTotal: total,
           actionsDone: done,
+          actions: actionsDetailFromHandlerResult(manifest, handlerResult),
         });
       }
     };
@@ -833,10 +926,100 @@ async function main() {
           handlerResult: handlerWireResult,
           registryResult: registryWireResult,
           sessionResult: sessionWireResult,
+          screenResult: screenWireResult,
           envResult: envWriteResult,
         });
         const paths = writeChangeRegistry(analysisRoot, record);
-        logUser(`Change log: ${paths.mdRel} (history in .fyodos/changes/)`);
+        logUser(changeLogUserMessage(paths));
+      } catch (e) {
+        logDev(`[change-registry] could not write: ${e.message}`);
+      }
+    }
+  } else if (platform === 'shopify' && publishing) {
+    // ── Shopify: publish + embed the orb in layout/theme.liquid ───────────────
+    // No code wiring: the manifest's commerce actions carry declarative
+    // `execution` blocks that the embed turns into handlers at runtime
+    // (buildApiActionRegistries, {baseUrl} → the store's own origin). The one
+    // edit is the theme.liquid snippet (idempotent markers); Shopify's GitHub
+    // sync deploys it when the developer pushes.
+    loadAppEnv(analysisRoot);
+    const { apiKey, apiUrl } = resolveApiTarget();
+    const noWire = process.argv.includes('--no-wire');
+    let orbWireResult = null;
+
+    await withSpinner('Publishing to your project', async ({ setLabel, pause, resume }) => {
+      await publishManifest(manifest, publishMeta, analysisToken, { skipSuccessLog: true });
+      if (!noWire && !process.argv.includes('--no-orb-wire')) {
+        setLabel(orbMountSpinnerLabel(platform));
+        orbWireResult = wireShopifyTheme(analysisRoot, { apiKey, apiUrl, noWire });
+        pause();
+        reportShopifyWire(orbWireResult, fyodosTermColors(), { quiet: !isVerbose() });
+        resume();
+        // Install proof only when the snippet is genuinely in the theme. All
+        // actions are execution-declared (nothing left to wire), so the
+        // terminal status is 'done' immediately — the dashboard tick then
+        // waits only for the runtime heartbeat once the theme is pushed.
+        if (
+          apiKey &&
+          (orbWireResult.status === 'added' || orbWireResult.status === 'already')
+        ) {
+          const proof = await postOrbWired({
+            apiKey,
+            apiUrl,
+            file: orbWireResult.file || '',
+            platform: 'shopify',
+            actionsStatus: 'done',
+          });
+          if (proof && proof.ok === false && proof.reason !== 'no-api-key') {
+            logDev(`[orb-wired] shopify install proof not recorded (${proof.status || proof.reason}); dashboard will rely on the runtime ping`);
+          }
+        }
+      }
+    });
+    logUser('Published to your project');
+    if (orbWireResult && (orbWireResult.status === 'added' || orbWireResult.status === 'already')) {
+      logUser('Commit & push this theme repo.');
+      // Shopify's GitHub sync only auto-updates the storefront when the
+      // CONNECTED theme is already the LIVE one. A brand-new theme connected
+      // from GitHub stays a draft until published ONCE by hand — every push
+      // after that keeps it live automatically. Without this line the orb can
+      // be fully wired and pushed and still never appear to real customers,
+      // with nothing in the CLI output explaining why.
+      logUser(
+        'If this is already your LIVE theme, that push alone puts the orb on your store. ' +
+        'If it\u2019s still a DRAFT (check the Shopify admin theme badge), publish it ONCE — ' +
+        'Online Store \u2192 Themes \u2192 \u22ef \u2192 Publish \u2014 then every future push stays live automatically.',
+      );
+      // New/trial Shopify stores are password-protected by default, and a
+      // password-protected storefront renders layout/password.liquid INSTEAD
+      // of layout/theme.liquid on every page — so without also wiring that
+      // layout (done above when the theme has one) the orb would be
+      // correctly installed and published yet invisible behind the password
+      // gate. Surfacing this explicitly since it is the #1 "installed
+      // correctly but nothing shows up" report on a fresh store.
+      if (orbWireResult.password) {
+        logUser(
+          orbWireResult.password.status === 'failed'
+            ? `Heads up: your store looks password-protected but the orb could not be added to ${orbWireResult.password.file} (${orbWireResult.password.reason}) — it will be invisible until you remove the password or fix that layout.`
+            : 'Your theme has a password page (layout/password.liquid) — the orb is embedded there too, so it still shows up while your store is password-protected.',
+        );
+      } else {
+        logUser(
+          'Heads up: if your store is still password-protected (common on new/trial stores) and your theme has NO separate layout/password.liquid, the orb won\u2019t show on the password page — remove the password (Online Store \u2192 Preferences) to test, or check under a real domain/plan.',
+        );
+      }
+    }
+
+    if (!noWire) {
+      try {
+        const record = buildRunRecord(analysisRoot, {
+          appName: manifest.appName,
+          manifest,
+          publishMeta,
+          orbResult: orbWireResult,
+        });
+        const paths = writeChangeRegistry(analysisRoot, record);
+        logUser(changeLogUserMessage(paths));
       } catch (e) {
         logDev(`[change-registry] could not write: ${e.message}`);
       }
@@ -959,7 +1142,7 @@ async function main() {
           envResult: envWriteResult,
         });
         const paths = writeChangeRegistry(analysisRoot, record);
-        logUser(`Change log: ${paths.mdRel} (history in .fyodos/changes/)`);
+        logUser(changeLogUserMessage(paths));
       } catch (e) {
         logDev(`[change-registry] could not write: ${e.message}`);
       }
@@ -1038,7 +1221,7 @@ async function main() {
           envResult: envWriteResult,
         });
         const paths = writeChangeRegistry(analysisRoot, record);
-        logUser(`Change log: ${paths.mdRel} (history in .fyodos/changes/)`);
+        logUser(changeLogUserMessage(paths));
       } catch (e) {
         logDev(`[change-registry] could not write: ${e.message}`);
       }
@@ -1131,6 +1314,9 @@ function detectPlatform(appRoot, appDir) {
     return found;
   };
 
+  // Shopify theme repos (GitHub-synced Liquid themes) are unmistakable and
+  // have no package.json framework signal — check them first.
+  if (isShopifyThemeRoot(appRoot)) return 'shopify';
   if (has('pubspec.yaml')) return 'flutter';
   if (has('Package.swift') || hasAnyExt('.xcodeproj') || (has('Sources') && hasAnyExt('.swift'))) return 'ios';
   if ((has('settings.gradle.kts') || has('settings.gradle') || has('build.gradle.kts') || has('build.gradle')) && hasAnyExt('.kt')) {
@@ -1563,6 +1749,7 @@ async function postOrbWired({
   actionsStatus = 'pending',
   actionsTotal = 0,
   actionsDone = 0,
+  actions = null,
 }) {
   if (!apiKey) return { ok: false, reason: 'no-api-key' };
   try {
@@ -1575,6 +1762,11 @@ async function postOrbWired({
         actionsStatus,
         actionsTotal,
         actionsDone,
+        // Per-action wiring detail (intent/status/reason). Powers the backend's
+        // "wired or nonexistent" invariant (unwired actions never reach the
+        // agent prompt) and the dashboard/Context wiring diagnosis. Older
+        // backends ignore the extra field.
+        ...(Array.isArray(actions) ? { actions } : {}),
       }),
     });
     if (res.ok) {
@@ -1589,6 +1781,210 @@ async function postOrbWired({
   }
 }
 
+/**
+ * Rewire-only mode (`fiodos rewire <dir>` / `--wire-only`): re-run JUST the
+ * handler wiring from the saved artifacts of the last analysis (manifest.json +
+ * evidence.json in the analysis output dir). The full verify→diagnose→correct→
+ * retry loop runs again — including AI corrections — so an action that fell to
+ * "manual" in the install gets fresh attempts WITHOUT a re-analysis (no quota,
+ * no manifest publish, no orb re-mount). Ends by re-posting the per-action
+ * wiring status so the dashboard/Context see the repaired state.
+ */
+async function runRewireOnly(target) {
+  const inputRoot = path.resolve(target || '.');
+  const safeName = path.basename(inputRoot).replace(/[^a-z0-9_-]/gi, '_') || 'app';
+  const outDir = arg('--out', path.join(os.tmpdir(), 'fiodos', 'analysis', safeName));
+
+  const manifestPath = path.join(outDir, 'manifest.json');
+  const evidencePath = path.join(outDir, 'evidence.json');
+  if (!fs.existsSync(manifestPath) || !fs.existsSync(evidencePath)) {
+    logUser('No saved analysis found for this project — run a full analysis first:');
+    logUser(`  npx fiodos analyze ${target || '.'} --publish`);
+    logUser(`(looked in ${outDir}; pass --out <dir> if you analyzed with a custom output dir)`);
+    process.exitCode = 1;
+    return;
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const ev = JSON.parse(fs.readFileSync(evidencePath, 'utf8'));
+  const evidence = ev.evidence || {};
+  const wiring = ev.wiring || {};
+
+  const scope = resolveAnalysisRoot(inputRoot, 'web');
+  const analysisRoot = scope.root;
+  loadAppEnv(analysisRoot);
+  const { apiKey, apiUrl } = resolveApiTarget();
+  const model = resolveModel(arg('--model', '') || DEFAULT_MODEL);
+  const assumeYes = process.argv.includes('--yes') || process.argv.includes('--wire-yes');
+  const { runPostWireTest } = require('./postWireTest');
+  const { included } = collectFiles(analysisRoot, { maxInputTokens: Number(arg('--max-input-tokens', '150000')), platform: 'web' });
+
+  const selfCorrect = !process.argv.includes('--no-self-correct');
+  const correctorUseProxy = !process.argv.includes('--own-ai-key');
+  const corrector = selfCorrect
+    ? async (args) => {
+        const { wiring: fixed } = await correctActionWiring({
+          ...args, model, platform: 'web', useProxy: correctorUseProxy, apiKey, apiUrl,
+        });
+        return fixed;
+      }
+    : null;
+
+  logUser(`Rewiring actions from the saved analysis (${manifest.actions.length} action(s), no re-analysis)…`);
+  let handlerResult = null;
+  await withSpinner(wiringSpinnerLabel('web'), async ({ pause, resume }) => {
+    if (!assumeYes) pause();
+    handlerResult = await wireHandlers(analysisRoot, {
+      manifest,
+      evidence,
+      wiring,
+      appName: manifest.appName,
+      colors: fyodosTermColors(),
+      assumeYes,
+      noWire: false,
+      quiet: !isVerbose(),
+      runTest: !process.argv.includes('--no-wire-test'),
+      revertOnFailure: true,
+      testRunner: runPostWireTest,
+      corrector,
+      files: included,
+      maxAttempts: Number(process.env.FYODOS_WIRE_MAX_ATTEMPTS || 3),
+    });
+    if (!assumeYes) resume();
+    pause();
+    reportHandlerResult(handlerResult, fyodosTermColors(), { quiet: !isVerbose() });
+    resume();
+
+    const handlerApplied =
+      handlerResult &&
+      (handlerResult.status === 'applied' || handlerResult.status === 'applied-untested') &&
+      (handlerResult.autoCount || 0) > 0 &&
+      handlerResult.registryFile;
+    if (handlerApplied) {
+      const connected = connectOrbRegistries(analysisRoot, {
+        registryFileAbs: handlerResult.registryFile,
+      });
+      pause();
+      reportRegistriesResult(connected, fyodosTermColors(), { quiet: !isVerbose() });
+      resume();
+    }
+  });
+
+  // Session + screen wiring also replay from the saved analysis (same consent
+  // model as the main flow: an APPLIED handler wiring proves the "yes").
+  const handlerConsented =
+    handlerResult &&
+    (handlerResult.status === 'applied' || handlerResult.status === 'applied-untested');
+  if (ev.session) {
+    const sessionResult = await wireSession(analysisRoot, {
+      session: ev.session,
+      colors: fyodosTermColors(),
+      quiet: !isVerbose(),
+      assumeYes: assumeYes || Boolean(handlerConsented),
+      framework: 'web',
+      appName: manifest.appName,
+      runTest: !process.argv.includes('--no-wire-test'),
+      testRunner: runPostWireTest,
+    });
+    reportSessionResult(sessionResult, fyodosTermColors(), { quiet: !isVerbose() });
+    if (sessionResult.status === 'applied' || sessionResult.status === 'applied-untested') {
+      const connectedSession = connectOrbSession(analysisRoot, {
+        sessionFileAbs: sessionResult.sessionFile,
+      });
+      reportSessionConnectResult(connectedSession, fyodosTermColors(), { quiet: !isVerbose() });
+    }
+  }
+  if (ev.screen) {
+    const screenResult = await wireScreen(analysisRoot, {
+      screen: ev.screen,
+      colors: fyodosTermColors(),
+      quiet: !isVerbose(),
+      assumeYes: assumeYes || Boolean(handlerConsented),
+      framework: 'web',
+      appName: manifest.appName,
+      runTest: !process.argv.includes('--no-wire-test'),
+      testRunner: runPostWireTest,
+    });
+    reportScreenResult(screenResult, fyodosTermColors(), { quiet: !isVerbose() });
+    if (screenResult.status === 'applied' || screenResult.status === 'applied-untested') {
+      const connectedScreen = connectOrbScreen(analysisRoot, {
+        screenFileAbs: screenResult.screenFile,
+      });
+      reportScreenConnectResult(connectedScreen, fyodosTermColors(), { quiet: !isVerbose() });
+    }
+  }
+
+  if (apiKey && handlerResult) {
+    const { status, total, done } = actionsWiredFromHandlerResult(handlerResult);
+    await postOrbWired({
+      apiKey,
+      apiUrl,
+      file: (handlerResult.registryRel || ''),
+      actionsStatus: status,
+      actionsTotal: total,
+      actionsDone: done,
+      actions: actionsDetailFromHandlerResult(manifest, handlerResult),
+    });
+  }
+  const wired = (handlerResult && handlerResult.autoCount) || 0;
+  const manual = (handlerResult && handlerResult.manualCount) || 0;
+  logUser(`Rewire finished: ${wired} action(s) wired, ${manual} still need attention.`);
+}
+
+/**
+ * Per-action wiring detail for the backend (POST /v1/developer/orb-wired).
+ * One entry per manifest action:
+ *   { intent, handler, status: 'wired'|'manual'|'link', reason?, attempts? }
+ * 'wired'  → verified and installed (the action really runs);
+ * 'manual' → could not be wired/verified — the backend EXCLUDES it from the
+ *            agent surface ("wired or nonexistent" invariant) and the
+ *            dashboard/Context can show and repair it;
+ * 'link'   → navigation/link action, needs no handler (always available).
+ * Returns null when wiring did not actually run (declined/skipped): with no
+ * verdict the backend must not filter anything.
+ */
+function actionsDetailFromHandlerResult(manifest, handlerResult) {
+  const r = handlerResult || {};
+  const ranStatuses = new Set(['applied', 'applied-untested', 'manual-only', 'reverted', 'failed']);
+  if (!ranStatuses.has(r.status)) return null;
+  const plan = r.plan || {};
+  const autoByIntent = new Map((plan.auto || []).map((e) => [e.intent, e]));
+  const reviewByIntent = new Map((plan.review || plan.manual || []).map((e) => [e.intent, e]));
+  const verifByIntent = new Map((r.verification || []).map((v) => [v.intent, v]));
+  const wholesaleFailed = r.status === 'reverted' || r.status === 'failed';
+
+  const detail = [];
+  for (const a of (manifest && manifest.actions) || []) {
+    const intent = a.intent;
+    if (a.kind === 'link') {
+      detail.push({ intent, handler: '', status: 'link' });
+      continue;
+    }
+    const verif = verifByIntent.get(intent);
+    if (!wholesaleFailed && autoByIntent.has(intent)) {
+      detail.push({
+        intent,
+        handler: a.handler || intent,
+        status: 'wired',
+        ...(verif && verif.level ? { level: verif.level } : {}),
+        ...(verif && verif.attempts ? { attempts: verif.attempts } : {}),
+      });
+      continue;
+    }
+    const rev = reviewByIntent.get(intent);
+    const reason = wholesaleFailed
+      ? `wiring ${r.status}: the combined install did not pass the build safety net`
+      : String((rev && rev.reason) || (verif && verif.error) || 'could not be wired automatically');
+    detail.push({
+      intent,
+      handler: a.handler || intent,
+      status: 'manual',
+      reason: reason.split('|')[0].replace(/\s+/g, ' ').trim().slice(0, 300),
+      ...(verif && verif.attempts ? { attempts: verif.attempts } : {}),
+    });
+  }
+  return detail;
+}
+
 // Map a wireHandlers() result to the terminal action-wiring status the backend
 // records, plus how many actions ended up wired. Drives the onboarding's third
 // "actions connected" tick so it only goes green once wiring truly finished.

package/src/postWireTest.js

@@ -127,6 +127,13 @@ function summarizeBuildOutput(raw, maxLines = 4) {
   return picked.slice(0, maxLines).join('\n').trim();
 }
 
+/** Does this output contain a signal that the CODE is broken (vs npm/env noise)? */
+function looksLikeCompileFailure(output) {
+  return /error\s+TS\d+|Type error:|Module not found|Can't resolve|Failed to compile|SyntaxError|Parsing error|Cannot find (?:module|name)/i.test(
+    String(output || ''),
+  );
+}
+
 async function runPostWireTest(appRoot, opts = {}) {
   const timeoutMs = opts.timeoutMs || 240000;
   if (!fs.existsSync(path.join(appRoot, 'node_modules'))) {
@@ -143,12 +150,26 @@ async function runPostWireTest(appRoot, opts = {}) {
     return { ok: true, stage: 'skipped-no-deps', command: '(none)', output: 'no build/typecheck script.' };
   }
 
-  const res = await runAsync('npm', chosen.args, {
-    cwd: appRoot,
-    timeout: timeoutMs,
-    env: { ...process.env, CI: '1', NODE_ENV: process.env.NODE_ENV || 'production' },
-    maxBuffer: 64 * 1024 * 1024,
-  });
+  const runOnce = () =>
+    runAsync('npm', chosen.args, {
+      cwd: appRoot,
+      timeout: timeoutMs,
+      env: { ...process.env, CI: '1', NODE_ENV: process.env.NODE_ENV || 'production' },
+      maxBuffer: 64 * 1024 * 1024,
+    });
+
+  let res = await runOnce();
+  // A spawn-level or npm-level failure with ZERO compile diagnostics is
+  // environment noise (npm cache contention, a concurrent process touching
+  // package.json, transient ENOENT), not broken code. Blaming the action for
+  // it drops perfectly good wiring, so retry once before judging.
+  const npmLevelFailure =
+    (res.error && res.error.code !== 'ETIMEDOUT') ||
+    (res.status !== 0 && res.status !== null && !looksLikeCompileFailure(`${res.stdout}\n${res.stderr}`));
+  if (npmLevelFailure) {
+    await new Promise((r) => setTimeout(r, 1500));
+    res = await runOnce();
+  }
 
   if (res.error && res.error.code === 'ETIMEDOUT') {
     return { ok: false, stage: 'timeout', command: chosen.label, output: `build exceeded ${Math.round(timeoutMs / 1000)}s` };