@fiodos/cli 0.1.7 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiodos/cli",
-  "version": "0.1.7",
+  "version": "0.1.10",
   "description": "Fiodos CLI — analyzes your app's source code and generates the in-app voice-agent manifest, then wires the orb. Powers `npx @fiodos/cli analyze`.",
   "type": "commonjs",
   "bin": {
@@ -21,7 +21,8 @@
   "dependencies": {
     "@fiodos/core": "^0.1.0",
     "esbuild": "^0.28.1",
-    "jsdom": "^24.0.0"
+    "jsdom": "^24.0.0",
+    "typescript": "^5.6.0"
   },
   "license": "SEE LICENSE IN LICENSE",
   "publishConfig": {

package/src/ast.js

@@ -20,8 +20,30 @@
 
 const fs = require('fs');
 const path = require('path');
-// Reuse the monorepo's TypeScript — real parser, real AST.
-const ts = require(path.join(__dirname, '../../../node_modules/typescript'));
+
+// Load the TypeScript compiler (real parser, real AST). `typescript` is a
+// declared dependency of this package, so when the CLI is installed from npm
+// (or run via `npx`) it resolves from the CLI's own node_modules. The monorepo
+// path is only a dev-time fallback for the hoisted workspace install.
+const ts = loadTypeScript();
+
+function loadTypeScript() {
+  try {
+    // Installed/npx case: resolves from @fiodos/cli's node_modules.
+    return require('typescript');
+  } catch {
+    // Monorepo dev fallback: TypeScript is hoisted to the repo root.
+    try {
+      return require(path.join(__dirname, '../../../node_modules/typescript'));
+    } catch (e) {
+      throw new Error(
+        'Fiodos CLI could not load its TypeScript dependency. This usually means ' +
+        'a corrupted install — try `npm cache clean --force` and re-run, or reinstall ' +
+        `@fiodos/cli. Original error: ${e.message}`,
+      );
+    }
+  }
+}
 
 function parseFile(filePath) {
   const text = fs.readFileSync(filePath, 'utf8');
@@ -73,8 +95,42 @@ function extractFromFile(filePath, appRoot) {
     imports: [],
     linkingCalls: [],
     defaultExportName: null,
+    // Internal navigation destinations referenced in this file (route strings):
+    // <Link href|to>, <a href>, router.push/replace, navigate(), redirect().
+    // Used by the surface-scoring layer to build the navigation reachability
+    // graph (which screens are reachable from the deployed entry). External
+    // links (http, mailto, tel, #anchors) are excluded.
+    navTargets: [],
+    // True when this file DEFINES the app's route table (react-router <Route>,
+    // createBrowserRouter, Angular RouterModule.forRoot/provideRouter, Vue
+    // createRouter). Such a file's links act as GLOBAL navigation (available
+    // from any screen), unlike a per-section sidebar.
+    routeHost: false,
+    // Soft signals that this file sits behind authentication (used ONLY to keep
+    // an orphaned cluster ACTIVE — never to disable). Identifiers/paths that
+    // commonly indicate an auth gate.
+    authSignals: [],
   };
 
+  // Collect an internal route string if it looks like an in-app path.
+  function pushNavTarget(value) {
+    if (!value || typeof value !== 'string') return;
+    const v = value.trim();
+    if (!v) return;
+    // Only same-app paths. Drop external/protocol/anchor/empty targets.
+    if (!v.startsWith('/')) return;
+    if (v.startsWith('//')) return; // protocol-relative external
+    out.navTargets.push(v);
+  }
+
+  // GATING constructs only (a redirect/block when unauthenticated) — NOT mere
+  // session reading (useUser/useSession): reading the user does not gate access,
+  // and counting it would wrongly protect public-but-orphaned pages from being
+  // disabled. Used solely to KEEP an orphaned cluster active (SaaS guard).
+  const AUTH_HINT_RE =
+    /(requireAuth|withAuth|ProtectedRoute|RequireAuth|AuthGuard|authGuard|ensureAuth|canActivate|redirectToLogin|RedirectToSignIn|SignedOut)/;
+  const AUTH_PATH_RE = /\/(login|signin|sign-in|sign_in)\b/i;
+
   function jsxAttr(attrs, names) {
     for (const attr of attrs.properties) {
       if (ts.isJsxAttribute(attr) && names.includes(attr.name.getText())) {
@@ -118,6 +174,10 @@ function extractFromFile(filePath, appRoot) {
         }
       }
       out.imports.push({ from: node.moduleSpecifier.text, names });
+      for (const n of names) {
+        if (AUTH_HINT_RE.test(n)) out.authSignals.push(n);
+      }
+      if (AUTH_PATH_RE.test(node.moduleSpecifier.text)) out.authSignals.push(node.moduleSpecifier.text);
     }
 
     // default export name (screen component)
@@ -157,6 +217,34 @@ function extractFromFile(filePath, appRoot) {
           }
         }
         out.navCalls.push({ verb, target, file: rel });
+        if (verb !== 'back' && verb !== 'goBack') pushNavTarget(target);
+      }
+
+      // Next.js / framework redirects: redirect('/x'), permanentRedirect('/x').
+      if (/^(redirect|permanentRedirect)$/.test(exprText) && node.arguments[0]) {
+        pushNavTarget(literalText(node.arguments[0]));
+      }
+      // react-router imperative: navigate('/x') / history.push('/x').
+      if (/(^|\.)navigate$/.test(exprText) && node.arguments[0]) {
+        pushNavTarget(literalText(node.arguments[0]));
+      }
+      // Bare push('/x') from a destructured useRouter()/useNavigate() hook.
+      if (exprText === 'push' && node.arguments[0]) {
+        pushNavTarget(literalText(node.arguments[0]));
+      }
+      // Route-table definitions → this file's links are GLOBAL navigation.
+      if (/^(createBrowserRouter|createHashRouter|createMemoryRouter|createRouter)$/.test(exprText)) {
+        out.routeHost = true;
+      }
+      if (/\.(forRoot|forChild)$/.test(exprText) || /^provideRouter$/.test(exprText)) {
+        out.routeHost = true;
+      }
+
+      // Auth gate by call: redirect('/login') etc. is captured above as a nav
+      // target; also flag it as an auth signal when the path looks like a gate.
+      if (/^(redirect|replace|push)$/.test(exprText.split('.').pop() || '') && node.arguments[0]) {
+        const t = literalText(node.arguments[0]);
+        if (t && AUTH_PATH_RE.test(t)) out.authSignals.push(t);
       }
 
       // Alert.alert(title, message?, buttons?)
@@ -217,6 +305,12 @@ function extractFromFile(filePath, appRoot) {
     if (ts.isJsxSelfClosingElement(node) || ts.isJsxOpeningElement(node)) {
       const tag = node.tagName.getText();
       const attrs = node.attributes;
+      // Any element carrying an internal route via href/to (next/link <Link>,
+      // <a href>, react-router <Link to>/<Navigate to>/<Redirect to>).
+      const linkTarget = jsxAttr(attrs, ['href', 'to']);
+      if (linkTarget) pushNavTarget(linkTarget);
+      // react-router <Route> table → global navigation host.
+      if (tag === 'Route') out.routeHost = true;
       if (/Button/i.test(tag) || tag === 'TouchableOpacity' || tag === 'Pressable') {
         const title = jsxAttr(attrs, ['title', 'label', 'accessibilityLabel']);
         const handler = jsxAttrHandlerName(attrs, ['onPress']);

package/src/graph.js

@@ -157,4 +157,4 @@ function mapScreens(routes, graph) {
   return { screens, stores };
 }
 
-module.exports = { buildGraph, mapScreens };
+module.exports = { buildGraph, mapScreens, closure };

package/src/index.js

@@ -96,6 +96,7 @@ const { verifyManifest } = require('./verify');
 const { wireWebOrb, reportWireResult } = require('./wireWeb');
 const { wireHandlers, reportHandlerResult } = require('./wireHandlers');
 const { offerWriteEnv, printEnvManualReminder } = require('./writeEnv');
+const { scoreSurface } = require('./scoreSurface');
 
 function arg(flag, fallback) {
   const i = process.argv.indexOf(flag);
@@ -161,24 +162,49 @@ async function withSpinner(label, work) {
   const orbFrames = ['◴', '◷', '◶', '◵'];
   const brailleFrames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
   const { blue, cyan, dim, reset } = fyodosTermColors();
+  let currentLabel = label;
   let frame = 0;
+  let id = null;
   const start = Date.now();
-  const tick = () => {
+
+  const render = () => {
     const sec = Math.floor((Date.now() - start) / 1000);
     const orb = orbFrames[frame % orbFrames.length];
     const tail = brailleFrames[frame % brailleFrames.length];
     const line =
-      `${cyan}${orb}${reset} ${blue}Fiodos${reset} ${dim}${tail}${reset}  ${label}… ${dim}${sec}s${reset}`;
+      `${cyan}${orb}${reset} ${blue}Fiodos${reset} ${dim}${tail}${reset}  ${currentLabel}… ${dim}${sec}s${reset}`;
     process.stderr.write(`\r\x1b[K${line}`);
     frame += 1;
   };
-  tick();
-  const id = setInterval(tick, 140);
+
+  const clearLine = () => process.stderr.write('\r\x1b[K');
+
+  const startSpinner = () => {
+    render();
+    id = setInterval(render, 140);
+  };
+
+  const pause = () => {
+    if (id) {
+      clearInterval(id);
+      id = null;
+      clearLine();
+    }
+  };
+
+  const resume = () => {
+    if (!id) startSpinner();
+  };
+
+  const setLabel = (next) => {
+    currentLabel = next;
+  };
+
+  startSpinner();
   try {
-    return await work();
+    return await work({ setLabel, pause, resume });
   } finally {
-    clearInterval(id);
-    process.stderr.write('\r\x1b[K');
+    pause();
   }
 }
 
@@ -297,10 +323,9 @@ async function main() {
     }
 
     // ── 3. AI reads the code ────────────────────────────────────────────────
-    logUser('Analyzing your project — may take 1–2 min');
     const { parsed, usage, costUSD, elapsedMs, promptChars, model: usedModel, analysisToken: token } =
       await withSpinner(
-        'Analyzing your project with AI',
+        'Analyzing your project — may take 1–2 min',
         () => analyzeWithAI({
           appMeta, files: included, omitted, staticRoutes: routes, model, platform,
           useProxy, apiKey, apiUrl,
@@ -355,6 +380,34 @@ async function main() {
   // the rest 'allow'. Closed-by-default still applies regardless of this hint.
   annotateExternalAgentRecommendations(manifest);
 
+  // ── 4c. Product-surface scoring (conservative, default-OFF for clear noise).
+  // Existence is already proven; this asks the SEPARATE question "is this part
+  // of the live product surface the orb should expose by default?". Routes/
+  // actions whose screens are UNREACHABLE by navigation from the deployed entry
+  // (orphans / dead code / a secondary app mirrored in the repo) AND not behind
+  // auth are annotated low-confidence and published DISABLED-by-default — never
+  // dropped (no new hallucination risk) and never empties an auth-gated app.
+  // Anything uncertain stays ACTIVE (fail towards including). The on/off lives
+  // in the workspace's disabled-intent sets (reused infra); the developer flips
+  // it in the dashboard. Web-first; other platforms are not scored yet.
+  let surface = { disabledRouteIntents: [], disabledActionIntents: [], stats: { applied: false } };
+  try {
+    surface = scoreSurface({ manifest, evidence, included, analysisRoot, platform });
+    for (const r of manifest.routes) {
+      const s = surface.routes && surface.routes[r.intent];
+      if (s) { r.surfaceConfidence = s.confidence; r.surfaceReason = s.reason; }
+    }
+    for (const a of manifest.actions) {
+      const s = surface.actions && surface.actions[a.intent];
+      if (s) { a.surfaceConfidence = s.confidence; a.surfaceReason = s.reason; }
+    }
+    logDev(`[surface] ${JSON.stringify(surface.stats)}`);
+  } catch (e) {
+    // Scoring is best-effort: a failure must never block publishing. Fail OPEN
+    // (everything stays active) — consistent with the "fail towards including".
+    logDev(`[surface] skipped: ${e.message}`);
+  }
+
   // ── 5. Final gate: the real @fiodos/core validator ─────────────────────────
   // Loaded as a package dependency (not a monorepo path) so it resolves when
   // the CLI is installed from npm.
@@ -373,14 +426,34 @@ async function main() {
   logDev(`[done] manifest: ${manifest.routes.length} routes, ${manifest.actions.length} actions`);
   logDev(`[done] output → ${outDir}`);
 
-  if (process.argv.includes('--publish')) {
-    loadAppEnv(analysisRoot);
-    await publishManifest(manifest, {
-      ...analysisMeta,
-      generatedAt: new Date().toISOString(),
-      routesIncluded: manifest.routes.length,
-      actionsIncluded: manifest.actions.length,
-    }, analysisToken);
+  const publishing = process.argv.includes('--publish');
+  const publishMeta = {
+    ...analysisMeta,
+    generatedAt: new Date().toISOString(),
+    routesIncluded: manifest.routes.length,
+    actionsIncluded: manifest.actions.length,
+    // Conservative default-OFF set for low-confidence (orphan) routes/actions.
+    // The backend applies these to the workspace's disabled-intent sets ONLY on
+    // the first publish / when the developer has not customized scope (no
+    // clobbering manual choices). Empty when scoring did not apply.
+    scopeDefaults: {
+      disabledRouteIntents: surface.disabledRouteIntents || [],
+      disabledActionIntents: surface.disabledActionIntents || [],
+    },
+  };
+
+  // Informative, non-blocking summary (the dashboard is where scope is managed).
+  const offR = (surface.disabledRouteIntents || []).length;
+  const offA = (surface.disabledActionIntents || []).length;
+  if (surface.stats && surface.stats.applied && (offR || offA)) {
+    const onR = manifest.routes.length - offR;
+    const onA = manifest.actions.length - offA;
+    logUser(`Main surface (active): ${onR} route(s), ${onA} action(s)`);
+    logUser(
+      `Detected but off by default: ${offR} route(s), ${offA} action(s) — ` +
+      `not reachable from your app's home (likely internal/secondary screens)`,
+    );
+    logUser('Review or re-enable any of them in your dashboard → Agent configuration');
   }
 
   // ── 6. Web: offer to wire the orb into the app (consent-based) ─────────────
@@ -392,38 +465,7 @@ async function main() {
     const assumeYes = process.argv.includes('--yes') || process.argv.includes('--wire-yes');
     const noWire = process.argv.includes('--no-wire');
     let envWriteResult = null;
-
-    // --no-orb-wire skips ONLY the orb mount (useful to test handler wiring in
-    // isolation without modifying the app's entrypoint / package.json).
-    if (!process.argv.includes('--no-orb-wire')) {
-      const result = await wireWebOrb(analysisRoot, {
-        apiUrl,
-        colors: fyodosTermColors(),
-        assumeYes,
-        noWire,
-        runTest: !process.argv.includes('--no-wire-test'),
-      });
-      reportWireResult(result, fyodosTermColors(), { quiet: !isVerbose() });
-      // Tell the dashboard the orb is wired — no need to boot localhost for the
-      // onboarding checker to complete.
-      if (
-        process.argv.includes('--publish') &&
-        apiKey &&
-        (result.status === 'added' || result.status === 'already')
-      ) {
-        await postOrbWired({ apiKey, apiUrl, file: result.file || '' });
-      }
-    }
-
-    // ── 7. Web: SECOND consent — connect detected actions to real app functions.
-    // The orb is mounted but the agent cannot DO anything until each manifest
-    // action is bridged to the function that performs it. We prepare that wiring,
-    // write a readable document into the project's Fiodos folder, and ask a
-    // separate, informed [yes/no] before touching anything. Security is enforced
-    // upstream by the engine, so generated handlers can never skip a confirmation.
     const { runPostWireTest } = require('./postWireTest');
-    // Corrector: when a wired action fails install-time verification, re-prompt the
-    // AI with the concrete error to fix THAT action. Disable with --no-self-correct.
     const selfCorrect = !process.argv.includes('--no-self-correct');
     const corrector = selfCorrect
       ? async (args) => {
@@ -431,7 +473,7 @@ async function main() {
           return fixed;
         }
       : null;
-    const handlerResult = await wireHandlers(analysisRoot, {
+    const handlerOpts = {
       manifest,
       evidence,
       wiring,
@@ -446,13 +488,54 @@ async function main() {
       corrector,
       files: included,
       maxAttempts: Number(process.env.FYODOS_WIRE_MAX_ATTEMPTS || 3),
-    });
-    reportHandlerResult(handlerResult, fyodosTermColors(), { quiet: !isVerbose() });
+    };
+
+    const runWebWire = async ({ setLabel, pause, resume }) => {
+      // --no-orb-wire skips ONLY the orb mount (useful to test handler wiring in
+      // isolation without modifying the app's entrypoint / package.json).
+      if (!process.argv.includes('--no-orb-wire')) {
+        setLabel('Mounting the orb in your app');
+        if (!assumeYes) pause();
+        const result = await wireWebOrb(analysisRoot, {
+          apiUrl,
+          colors: fyodosTermColors(),
+          assumeYes,
+          noWire,
+          runTest: !process.argv.includes('--no-wire-test'),
+        });
+        if (!assumeYes) resume();
+        reportWireResult(result, fyodosTermColors(), { quiet: !isVerbose() });
+        if (
+          publishing &&
+          apiKey &&
+          (result.status === 'added' || result.status === 'already')
+        ) {
+          await postOrbWired({ apiKey, apiUrl, file: result.file || '' });
+        }
+      }
+
+      setLabel('Wiring actions to your app');
+      if (!assumeYes) pause();
+      const handlerResult = await wireHandlers(analysisRoot, handlerOpts);
+      if (!assumeYes) resume();
+      reportHandlerResult(handlerResult, fyodosTermColors(), { quiet: !isVerbose() });
+    };
+
+    if (publishing) {
+      loadAppEnv(analysisRoot);
+      await withSpinner('Publishing to your project', async (spinner) => {
+        await publishManifest(manifest, publishMeta, analysisToken, { skipSuccessLog: true });
+        await runWebWire(spinner);
+      });
+      logUser('Published to your project');
+    } else {
+      await withSpinner('Mounting the orb in your app', runWebWire);
+    }
 
     // ── 8. API key in environment (LAST step — always asks; independent of --yes)
     // --yes only skips orb/handler prompts. --write-env-yes skips this one (CI).
     // If the developer declines, we show a copy-paste reminder here at the end.
-    if (process.argv.includes('--publish') && !process.argv.includes('--no-write-env')) {
+    if (publishing && !process.argv.includes('--no-write-env')) {
       try {
         envWriteResult = await offerWriteEnv({
           appRoot: analysisRoot,
@@ -473,6 +556,12 @@ async function main() {
         logDev(`[write-env] skipped: ${e.message}`);
       }
     }
+  } else if (publishing) {
+    loadAppEnv(analysisRoot);
+    await withSpinner('Publishing to your project', () =>
+      publishManifest(manifest, publishMeta, analysisToken, { skipSuccessLog: true }),
+    );
+    logUser('Published to your project');
   }
 }
 
@@ -693,7 +782,7 @@ function printQuotaBlocked(quota) {
   );
 }
 
-async function publishManifest(manifest, meta, analysisToken = null) {
+async function publishManifest(manifest, meta, analysisToken = null, opts = {}) {
   const { apiKey, apiUrl } = resolveApiTarget();
   if (!apiKey) {
     console.error(
@@ -726,7 +815,9 @@ async function publishManifest(manifest, meta, analysisToken = null) {
     process.exit(1);
   }
   const body = await res.json();
-  logUser('Published to your project');
+  if (!opts.skipSuccessLog) {
+    logUser('Published to your project');
+  }
   logDev(`[publish] OK — ${body.routes} routes, ${body.actions} actions received at ${body.receivedAt}`);
 
   // Self-check: confirm the orb will find this manifest (silent unless --verbose).

package/src/scoreSurface.js

@@ -0,0 +1,405 @@
+/**
+ * Surface scoring — "does this route/action belong to the product surface the
+ * developer wants the orb to expose?", separate from "does it exist in code?"
+ * (that is the verifier's job, untouched here).
+ *
+ * The existence verifier guarantees every route/action is backed by real code.
+ * But disorganized projects ship code that is NOT the live product surface:
+ * dead screens, work-in-progress, or a whole secondary app mirrored inside the
+ * web frontend (e.g. a marketing landing that also contains the full app under
+ * route groups). The orb should not offer those by default.
+ *
+ * PRINCIPLE (decided product policy): we cannot read the developer's INTENT
+ * from code alone (dead code and a brand-new feature look identical). So we
+ * make a CONSERVATIVE automatic guess and pair it with cheap confirmation:
+ *   - high confidence  → published ACTIVE (default-on).
+ *   - low  confidence  → published DISABLED-by-default (still present, the dev
+ *                        re-enables it in the dashboard with one click).
+ * We never DROP anything (no new hallucination risk) and we FAIL TOWARDS
+ * INCLUDING: anything uncertain stays ACTIVE. The only thing we turn off by
+ * default is what is CLEARLY not the product:
+ *   - a route whose screen is UNREACHABLE by navigation from the deployed
+ *     public entry (orphan), AND
+ *   - that shows NO sign of sitting behind authentication (so we never empty a
+ *     login-gated SaaS — the auth guard), AND
+ *   - only when the navigation graph is trustworthy enough to believe an orphan
+ *     really is an orphan (else we disable nothing).
+ *
+ * SIGNAL: navigation reachability from the deployed entry, computed over the
+ * project's import/navigation graph. Web-first (Next app/pages router, plus a
+ * generic SPA route-host fallback). For platforms where reachability cannot be
+ * computed confidently we return NO disables (fail towards including).
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { extractFromFile } = require('./ast');
+const { closure } = require('./graph');
+
+const EXTS = ['.tsx', '.ts', '.jsx', '.js'];
+
+/** Normalize an internal route string for matching (drop query/hash/trailing). */
+function normUrl(p) {
+  if (!p) return null;
+  let s = String(p).split('?')[0].split('#')[0].trim();
+  if (!s.startsWith('/')) return null;
+  if (s.length > 1) s = s.replace(/\/+$/, '');
+  // Collapse Next dynamic [param] / :param into a wildcard token for matching.
+  s = s.replace(/\[[^/\]]+\]/g, ':p').replace(/:[^/]+/g, ':p');
+  return s || '/';
+}
+
+function toPosix(p) {
+  return p.replace(/\\/g, '/');
+}
+
+/**
+ * Build an import graph over the ALREADY-COLLECTED files (not a fresh FS walk),
+ * so it sees the exact code the analysis saw and the correct app root. Reuses
+ * the extended AST extractor (navTargets / authSignals / routeHost).
+ *
+ * @returns {{ extracted: Map<string,object>, edges: Map<string,Set<string>>, absOf: Map<string,string> }}
+ *   extracted/edges are keyed by ABSOLUTE path; absOf maps rel → abs.
+ */
+function buildGraphFromFiles(included, analysisRoot) {
+  const absOf = new Map();
+  const absSet = new Set();
+  for (const f of included) {
+    const abs = path.resolve(analysisRoot, f.rel);
+    absOf.set(toPosix(f.rel), abs);
+    absSet.add(abs);
+  }
+
+  const extracted = new Map();
+  for (const f of included) {
+    const abs = path.resolve(analysisRoot, f.rel);
+    if (!EXTS.includes(path.extname(abs))) continue;
+    let ex;
+    try {
+      ex = extractFromFile(abs, analysisRoot);
+    } catch {
+      ex = { file: f.rel, imports: [], navTargets: [], authSignals: [], routeHost: false };
+    }
+    extracted.set(abs, ex);
+  }
+
+  const resolveImport = (fromAbs, spec) => {
+    let base = null;
+    if (spec.startsWith('.')) base = path.resolve(path.dirname(fromAbs), spec);
+    else if (spec.startsWith('@/')) base = path.join(analysisRoot, spec.slice(2));
+    else if (spec.startsWith('~/')) base = path.join(analysisRoot, spec.slice(2));
+    else return null; // bare package — out of scope
+    for (const ext of ['', ...EXTS]) {
+      if (absSet.has(base + ext)) return base + ext;
+    }
+    for (const ext of EXTS) {
+      const idx = path.join(base, 'index' + ext);
+      if (absSet.has(idx)) return idx;
+    }
+    return null;
+  };
+
+  const edges = new Map();
+  for (const [abs, ex] of extracted) {
+    const deps = new Set();
+    for (const imp of ex.imports || []) {
+      const r = resolveImport(abs, imp.from);
+      if (r) deps.add(r);
+    }
+    edges.set(abs, deps);
+  }
+
+  return { extracted, edges, absOf, absSet };
+}
+
+/**
+ * Map a deployed URL path → screen file (absolute), from the collected files.
+ * Handles Next App Router (app/.../page.*) and Pages Router (pages/...). Other
+ * frameworks rely on manifest evidence + the SPA route-host fallback instead.
+ */
+function buildWebRouteMap(included, analysisRoot) {
+  const map = new Map(); // normUrl -> absFile
+  const add = (url, abs) => {
+    const u = normUrl(url);
+    if (u && !map.has(u)) map.set(u, abs);
+  };
+
+  for (const f of included) {
+    const rel = toPosix(f.rel);
+    const abs = path.resolve(analysisRoot, f.rel);
+
+    // App Router: (src/)app/<segments>/page.ext  (also route.ts is NOT a screen)
+    let m = rel.match(/^(?:src\/)?app\/(.*\/)?page\.(?:tsx|ts|jsx|js)$/);
+    if (m) {
+      const segs = (m[1] || '')
+        .split('/')
+        .filter(Boolean)
+        .filter((s) => !(s.startsWith('(') && s.endsWith(')'))) // route groups
+        .filter((s) => !s.startsWith('@')); // parallel-route slots
+      add('/' + segs.join('/'), abs);
+      continue;
+    }
+
+    // Pages Router: (src/)pages/<path>.ext  (skip _app/_document/api)
+    m = rel.match(/^(?:src\/)?pages\/(.*)\.(?:tsx|ts|jsx|js)$/);
+    if (m) {
+      const p = m[1];
+      if (/^_(app|document|error)$/.test(p) || p.startsWith('api/')) continue;
+      const segs = p
+        .split('/')
+        .filter((s) => !(s.startsWith('(') && s.endsWith(')')));
+      let url = '/' + segs.join('/');
+      url = url.replace(/\/index$/, '') || '/';
+      add(url, abs);
+      continue;
+    }
+  }
+
+  return map;
+}
+
+/** Next App Router layout chain for a screen file: every ancestor layout.* up
+ *  to analysisRoot. From a screen the user CAN navigate via these (e.g. a
+ *  sidebar living in the segment layout). */
+function layoutChain(absFile, analysisRoot, absSet) {
+  const chain = [];
+  let dir = path.dirname(absFile);
+  const root = path.resolve(analysisRoot);
+  for (let i = 0; i < 24; i++) {
+    for (const ext of EXTS) {
+      const cand = path.join(dir, 'layout' + ext);
+      if (absSet.has(cand)) chain.push(cand);
+    }
+    if (dir === root || !dir.startsWith(root)) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return chain;
+}
+
+/** Detect the deployed public entry SCREEN file(s) from the filesystem. */
+function findEntryFiles(routeMap, extracted) {
+  const entries = new Set();
+  const home = routeMap.get('/');
+  if (home) entries.add(home);
+  return entries;
+}
+
+/** Union of navTargets found across a set of files' import closures (+ each
+ *  file's own targets). */
+function collectTargets(files, edges, extracted) {
+  const targets = [];
+  for (const f of files) {
+    for (const dep of closure(f, edges)) {
+      const ex = extracted.get(dep);
+      if (ex && ex.navTargets) targets.push(...ex.navTargets);
+    }
+  }
+  return targets;
+}
+
+function anyAuthSignal(files, edges, extracted) {
+  for (const f of files) {
+    for (const dep of closure(f, edges)) {
+      const ex = extracted.get(dep);
+      if (ex && ex.authSignals && ex.authSignals.length) return true;
+    }
+  }
+  return false;
+}
+
+/** A root middleware that redirects unauthenticated users gates the WHOLE app;
+ *  treat it as a global auth gate (never disable anything → SaaS guard). */
+function hasGlobalAuthGate(included, analysisRoot, extracted) {
+  for (const f of included) {
+    const rel = toPosix(f.rel);
+    if (!/^(?:src\/)?middleware\.(?:ts|js)$/.test(rel)) continue;
+    const abs = path.resolve(analysisRoot, f.rel);
+    const ex = extracted.get(abs);
+    if (ex && ex.authSignals && ex.authSignals.length) return true;
+    // Fallback: scan raw content for a login redirect (middleware is small).
+    if (/\/(login|signin|sign-in)\b/i.test(f.content) && /redirect|NextResponse/.test(f.content)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Score every route/action of a manifest by product-surface confidence and
+ * compute the conservative default-disabled sets.
+ *
+ * @param {object}   p
+ * @param {object}   p.manifest
+ * @param {object}   p.evidence   { routes: {intent:{file}}, actions: {intent:{file}} }
+ * @param {Array}    p.included   collected files [{rel, content}]
+ * @param {string}   p.analysisRoot
+ * @param {string}   p.platform
+ * @returns {{
+ *   routes: Object<string,{confidence:string,reason:string}>,
+ *   actions: Object<string,{confidence:string,reason:string}>,
+ *   disabledRouteIntents: string[],
+ *   disabledActionIntents: string[],
+ *   stats: object,
+ * }}
+ */
+function scoreSurface({ manifest, evidence = {}, included = [], analysisRoot, platform = 'web' }) {
+  const empty = {
+    routes: {},
+    actions: {},
+    disabledRouteIntents: [],
+    disabledActionIntents: [],
+    stats: { applied: false, reason: 'not-web' },
+  };
+
+  // Web-first. Other platforms: reachability is not computed confidently yet,
+  // so we return no disables (fail towards including). Honest limitation.
+  if (platform !== 'web') return empty;
+  if (!manifest || !Array.isArray(manifest.routes)) return empty;
+
+  const { extracted, edges, absSet } = buildGraphFromFiles(included, analysisRoot);
+  const routeMap = buildWebRouteMap(included, analysisRoot);
+
+  const evAbs = (rel) => {
+    if (!rel) return null;
+    const abs = path.resolve(analysisRoot, rel);
+    return absSet.has(abs) ? abs : null;
+  };
+  const routeEv = evidence.routes || {};
+  const actionEv = evidence.actions || {};
+
+  // Global auth gate (root middleware) → keep everything active.
+  const globalAuthGate = hasGlobalAuthGate(included, analysisRoot, extracted);
+
+  // Entry screen file(s). Without one we cannot judge orphans → disable nothing.
+  const entryFiles = findEntryFiles(routeMap, extracted);
+
+  // SPA route hosts (react-router/Angular/Vue): their links are GLOBAL nav.
+  const routeHostFiles = [];
+  for (const [abs, ex] of extracted) if (ex.routeHost) routeHostFiles.push(abs);
+
+  // Is the navigation graph trustworthy? (Enough resolvable internal links that
+  // an "orphan" is believable rather than just unparsed dynamic navigation.)
+  const allTargets = new Set();
+  for (const ex of extracted.values()) {
+    for (const t of ex.navTargets || []) {
+      const f = routeMap.get(normUrl(t));
+      if (f) allTargets.add(normUrl(t));
+    }
+  }
+  const trustworthy = allTargets.size >= 2;
+
+  const canScore = entryFiles.size > 0 && trustworthy && !globalAuthGate;
+
+  // BFS over screen files from the entry, following nav links found in each
+  // reached screen's closure AND its layout chain. SPA route-host links are
+  // seeded as globally available.
+  const reached = new Set(entryFiles);
+  const queue = [...entryFiles];
+  const seedTargets = (files) => {
+    for (const t of collectTargets(files, edges, extracted)) {
+      const f = routeMap.get(normUrl(t));
+      if (f && !reached.has(f)) {
+        reached.add(f);
+        queue.push(f);
+      }
+    }
+  };
+  // Global navigation from route hosts (SPA) is reachable from anywhere.
+  seedTargets(routeHostFiles);
+  while (queue.length) {
+    const f = queue.shift();
+    const shell = [f, ...layoutChain(f, analysisRoot, absSet)];
+    seedTargets(shell);
+  }
+
+  // Closure of everything reachable (for action membership): a non-screen file
+  // (service/store) is "on the product surface" if a reachable screen imports it.
+  const reachableClosure = new Set();
+  for (const f of reached) {
+    for (const dep of closure(f, edges)) reachableClosure.add(dep);
+    for (const lay of layoutChain(f, analysisRoot, absSet)) {
+      for (const dep of closure(lay, edges)) reachableClosure.add(dep);
+    }
+  }
+
+  const routes = {};
+  const disabledRouteIntents = [];
+  const entryUrls = new Set([...entryFiles].map(() => '/'));
+
+  for (const r of manifest.routes) {
+    const intent = r.intent;
+    if (!intent) continue;
+    if (r.route === 'BACK') {
+      routes[intent] = { confidence: 'high', reason: 'reachable' };
+      continue;
+    }
+    // Prefer the analyzer's evidence file; fall back to mapping the route URL to
+    // a screen file (web route maps), since route evidence is optional in web
+    // mode while action evidence is mandatory.
+    const ef = evAbs((routeEv[intent] || {}).file) || routeMap.get(normUrl(r.route)) || null;
+    const isEntry = (ef && entryFiles.has(ef)) || entryUrls.has(normUrl(r.route));
+    const reachable = ef && reached.has(ef);
+
+    if (reachable || isEntry) {
+      routes[intent] = { confidence: 'high', reason: 'reachable' };
+    } else if (!canScore || !ef) {
+      routes[intent] = { confidence: 'high', reason: 'unknown' };
+    } else if (anyAuthSignal([ef, ...layoutChain(ef, analysisRoot, absSet)], edges, extracted)) {
+      routes[intent] = { confidence: 'high', reason: 'behind-auth' };
+    } else {
+      routes[intent] = { confidence: 'low', reason: 'orphan' };
+      disabledRouteIntents.push(intent);
+    }
+  }
+
+  const actions = {};
+  const disabledActionIntents = [];
+  for (const a of manifest.actions || []) {
+    const intent = a.intent;
+    if (!intent) continue;
+    const ef = evAbs((actionEv[intent] || {}).file);
+    const onSurface = ef && reachableClosure.has(ef);
+
+    if (onSurface) {
+      actions[intent] = { confidence: 'high', reason: 'reachable' };
+    } else if (!canScore || !ef) {
+      actions[intent] = { confidence: 'high', reason: 'unknown' };
+    } else if (anyAuthSignal([ef, ...layoutChain(ef, analysisRoot, absSet)], edges, extracted)) {
+      actions[intent] = { confidence: 'high', reason: 'behind-auth' };
+    } else {
+      actions[intent] = { confidence: 'low', reason: 'orphan' };
+      disabledActionIntents.push(intent);
+    }
+  }
+
+  return {
+    routes,
+    actions,
+    disabledRouteIntents,
+    disabledActionIntents,
+    stats: {
+      applied: canScore,
+      reason: canScore
+        ? 'scored'
+        : globalAuthGate
+          ? 'global-auth-gate'
+          : entryFiles.size === 0
+            ? 'no-entry'
+            : !trustworthy
+              ? 'sparse-graph'
+              : 'unknown',
+      entryCount: entryFiles.size,
+      reachableScreens: reached.size,
+      resolvableTargets: allTargets.size,
+      trustworthy,
+      globalAuthGate,
+      routesDisabled: disabledRouteIntents.length,
+      actionsDisabled: disabledActionIntents.length,
+    },
+  };
+}
+
+module.exports = { scoreSurface, normUrl, buildWebRouteMap, buildGraphFromFiles };