@fiodos/cli 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiodos/cli",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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": {
@@ -19,7 +19,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@fiodos/core": "^0.1.1",
+    "@fiodos/core": "^0.1.2",
     "esbuild": "^0.28.1",
     "jsdom": "^24.0.0",
     "typescript": "^5.6.0"

package/src/aiAnalyze.js

@@ -103,6 +103,15 @@ const PLATFORM_GUIDES = {
       'Web actions come in TWO kinds, BOTH first-class — detect both:\n' +
       '  (1) FUNCTION actions (kind "function"): functions wired to UI — handlers inside components, store/context actions (Zustand, Redux, React Context), or service functions. Set "handler" to that real function name exactly. INCLUDE common web product actions you might be tempted to skip: switching language/locale (e.g. setLang/setLocale/i18n.changeLanguage), toggling theme, submitting a contact/newsletter/search form. (Still skip pure micro-plumbing like opening a dropdown or controlled input onChange.)\n' +
       '  (2) LINK actions (kind "link"): the core actions of marketing/landing pages, which are NAVIGATION not function calls — download/get-the-app buttons (App Store / Google Play / direct download), "contact us" / email / phone links, social links, and in-page jumps to a section (anchor hrefs like #pricing). For these set kind "link" and navTarget to the EXACT href string in the code; do NOT set handler. A list of detected link elements on the product-surface pages is provided below — turn the meaningful ones into link actions (group obvious duplicates, e.g. several App Store buttons → one "download on the App Store").\n' +
+      'VITAL WEB SECTIONS — almost every website exposes a small set of high-value, low-risk destinations that users very commonly ask for. Before finishing, actively SCAN the code and the detected-links list for these and INCLUDE the ones that genuinely exist (each as a link action when it is a navigation/href, or a function action when it is a real handler). Do NOT invent any that are not in the code — but do not overlook them either, because these are exactly what users ask the assistant for:\n' +
+      '    • Contact / get in touch (mailto:, tel:, a /contact page or #contact anchor, a contact form)\n' +
+      '    • Help / support / FAQ / docs (a help center link, support email, /faq or /help)\n' +
+      '    • Social media profiles (links to Instagram, X/Twitter, LinkedIn, YouTube, TikTok, GitHub, etc. — one action per network)\n' +
+      '    • Download / get the app (store or direct-download links)\n' +
+      '    • Change language / locale (a language switcher link or a setLang/i18n handler)\n' +
+      '    • Legal (privacy policy, terms of service, cookies)\n' +
+      '    • Pricing / plans, and newsletter/subscribe, when present.\n' +
+      'These vital sections apply to EVERY web product, not any specific one — treat them as a standing checklist for all websites.\n' +
       'CRITICAL: the manifest is for THIS web deployment only — do NOT include routes or actions from mobile/native code that is not in the file list (even if you infer it exists elsewhere in the monorepo).',
   },
   mobile: {

package/src/index.js

@@ -506,6 +506,11 @@ async function main() {
     };
 
     const runWebWire = async ({ setLabel, pause, resume }) => {
+      // Emit a report on its OWN clean line: pause the live spinner (clears its
+      // line), print, then resume. Without this, a log written while the spinner
+      // is ticking gets glued onto the spinner line ("…10sFiodos · …").
+      const report = (fn) => { pause(); fn(); 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')) {
@@ -519,13 +524,20 @@ async function main() {
           runTest: !process.argv.includes('--no-wire-test'),
         });
         if (!assumeYes) resume();
-        reportWireResult(result, fyodosTermColors(), { quiet: !isVerbose() });
+        report(() => reportWireResult(result, fyodosTermColors(), { quiet: !isVerbose() }));
         if (
           publishing &&
           apiKey &&
           (result.status === 'added' || result.status === 'already')
         ) {
-          await postOrbWired({ apiKey, apiUrl, file: result.file || '' });
+          // Records the install proof so the dashboard onboarding orb check can
+          // complete without booting the app. If the backend can't record it
+          // (e.g. an outdated deployment without the endpoint), keep it as a
+          // dev-only trace — it is not actionable noise for the end developer.
+          const proof = await postOrbWired({ apiKey, apiUrl, file: result.file || '' });
+          if (proof && proof.ok === false && proof.reason !== 'no-api-key') {
+            logDev(`[orb-wired] install proof not recorded (status=${proof.status || proof.reason}); dashboard check will rely on a runtime ping`);
+          }
         }
       }
 
@@ -533,7 +545,7 @@ async function main() {
       if (!assumeYes) pause();
       const handlerResult = await wireHandlers(analysisRoot, handlerOpts);
       if (!assumeYes) resume();
-      reportHandlerResult(handlerResult, fyodosTermColors(), { quiet: !isVerbose() });
+      report(() => reportHandlerResult(handlerResult, fyodosTermColors(), { quiet: !isVerbose() }));
     };
 
     if (publishing) {
@@ -846,7 +858,7 @@ async function publishManifest(manifest, meta, analysisToken = null, opts = {})
  * already succeeded); a failed re-fetch is surfaced as an actionable warning.
  */
 async function postOrbWired({ apiKey, apiUrl, file }) {
-  if (!apiKey) return;
+  if (!apiKey) return { ok: false, reason: 'no-api-key' };
   try {
     const res = await fetch(`${apiUrl}/v1/developer/orb-wired`, {
       method: 'POST',
@@ -855,11 +867,13 @@ async function postOrbWired({ apiKey, apiUrl, file }) {
     });
     if (res.ok) {
       logDev(`[orb-wired] install proof recorded (${file || 'web'})`);
-    } else {
-      logDev(`[orb-wired] could not record install proof: HTTP ${res.status}`);
+      return { ok: true };
     }
+    logDev(`[orb-wired] could not record install proof: HTTP ${res.status}`);
+    return { ok: false, status: res.status };
   } catch (e) {
     logDev(`[orb-wired] skipped: ${e.message || e}`);
+    return { ok: false, reason: e.message || String(e) };
   }
 }
 async function verifyOrbCanFetch({ apiKey, apiUrl }) {

package/src/postWireTest.js

@@ -24,7 +24,56 @@
 
 const fs = require('fs');
 const path = require('path');
-const { spawnSync } = require('child_process');
+const { spawn } = require('child_process');
+
+/**
+ * Run a command WITHOUT blocking Node's event loop (unlike spawnSync). This
+ * matters for the live terminal spinner: spawnSync freezes the whole process
+ * while the build runs, so the elapsed-seconds counter appears to jump in big
+ * steps ("stuck"). With async spawn the loop stays free and the counter ticks
+ * every second. Resolves to a spawnSync-shaped result { status, stdout, stderr,
+ * error } and never rejects.
+ */
+function runAsync(cmd, args, opts = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, args, { ...opts, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (error) {
+      resolve({ status: null, stdout: '', stderr: '', error });
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    const max = opts.maxBuffer || 64 * 1024 * 1024;
+    // Bound total captured output (the way maxBuffer would) without throwing.
+    child.stdout.on('data', (c) => { if (stdout.length + stderr.length < max) stdout += c.toString(); });
+    child.stderr.on('data', (c) => { if (stdout.length + stderr.length < max) stderr += c.toString(); });
+
+    let timedOut = false;
+    let timer = null;
+    if (opts.timeout) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        try { child.kill('SIGKILL'); } catch { /* ignore */ }
+      }, opts.timeout);
+    }
+    child.on('error', (error) => {
+      if (timer) clearTimeout(timer);
+      resolve({ status: null, stdout, stderr, error });
+    });
+    child.on('close', (code) => {
+      if (timer) clearTimeout(timer);
+      if (timedOut) {
+        const error = new Error('ETIMEDOUT');
+        error.code = 'ETIMEDOUT';
+        resolve({ status: null, stdout, stderr, error });
+        return;
+      }
+      resolve({ status: code, stdout, stderr, error: null });
+    });
+  });
+}
 
 function readPkg(appRoot) {
   try {
@@ -70,9 +119,8 @@ async function runPostWireTest(appRoot, opts = {}) {
     return { ok: true, stage: 'skipped-no-deps', command: '(none)', output: 'no build/typecheck script.' };
   }
 
-  const res = spawnSync('npm', chosen.args, {
+  const res = await runAsync('npm', chosen.args, {
     cwd: appRoot,
-    encoding: 'utf8',
     timeout: timeoutMs,
     env: { ...process.env, CI: '1', NODE_ENV: process.env.NODE_ENV || 'production' },
     maxBuffer: 64 * 1024 * 1024,

package/src/renderProbe.js

@@ -48,6 +48,46 @@ function isVerboseProbe() {
   return process.argv.includes('--verbose') || process.argv.includes('-v') || process.argv.includes('--debug');
 }
 
+/**
+ * Render-probe teardown guard.
+ *
+ * The probe mounts the user's real React component in jsdom, then unmounts and
+ * tears the DOM down. React 18 schedules passive-effect cleanup ASYNCHRONOUSLY
+ * (a scheduler timer/microtask). If any cleanup fires AFTER we removed the
+ * jsdom globals, React throws "The `document` global was defined when React was
+ * initialized, but is not defined anymore". On Node ≥ 21/25 that async throw is
+ * an uncaughtException that kills the ENTIRE CLI — long after the probe returned
+ * (e.g. while the CLI is awaiting the ".env" prompt). The probe is an OPTIONAL
+ * effect check; it must never crash an otherwise-successful install.
+ *
+ * We install (once) a narrow process-level filter that swallows ONLY this jsdom/
+ * React teardown error class and lets every other error crash as usual.
+ */
+let teardownGuardInstalled = false;
+function isProbeTeardownError(err) {
+  const msg = String((err && (err.stack || err.message)) || err || '');
+  return (
+    /`document` global was defined when React was initialized/.test(msg) ||
+    /\bdocument is not defined\b/.test(msg) ||
+    /Cannot read properties of (?:null|undefined) \(reading '(?:document|ownerDocument|defaultView|createElement|body)'\)/.test(msg) ||
+    (/jsdom/i.test(msg) && /not defined|closed|null/i.test(msg))
+  );
+}
+function installProbeTeardownGuard() {
+  if (teardownGuardInstalled) return;
+  teardownGuardInstalled = true;
+  process.on('uncaughtException', (err) => {
+    if (isProbeTeardownError(err)) return; // late probe passive-effect cleanup — safe to drop
+    // Not ours: preserve Node's default fail-fast behavior for real errors.
+    console.error(err && err.stack ? err.stack : err);
+    process.exit(1);
+  });
+  process.on('unhandledRejection', (reason) => {
+    if (isProbeTeardownError(reason)) return;
+    throw reason;
+  });
+}
+
 /**
  * Capture (swallow) noisy global console output during a probe — React error
  * boundary logs ("The above error occurred in <X>", "Consider adding an error
@@ -150,8 +190,18 @@ async function probeReactEffect(appRoot, entry, ctx) {
     `import { flushSync } from 'react-dom';\n` +
     `export const probe = { React: ReactNS.default || ReactNS, createRoot, flushSync, Comp, registry: fyodosGeneratedRegistries };\n`;
 
+  // A late React passive-effect cleanup that fires after we tear down jsdom must
+  // never crash the CLI (see installProbeTeardownGuard).
+  installProbeTeardownGuard();
+
   let restore = () => {};
   let cap = { restore() {} };
+  // Hoisted so the finally block can drain React (synchronously unmount + settle)
+  // BEFORE the DOM globals are removed — the only reliable way to stop React from
+  // running cleanup against a closed jsdom.
+  let root = null;
+  let flushSync = null;
+  const settle = () => new Promise((r) => setTimeout(r, 0));
   try {
     fs.writeFileSync(harnessAbs, harness);
     await esbuild.build({
@@ -173,14 +223,13 @@ async function probeReactEffect(appRoot, entry, ctx) {
     restore = installDom(jsdomMod, { storageKeys: ctx.storageKeys, kind: ctx.kind });
     delete require.cache[outAbs];
     const mod = require(outAbs);
-    const { React, createRoot, flushSync, Comp, registry } = mod.probe;
+    const { React, createRoot, Comp, registry } = mod.probe;
+    flushSync = mod.probe.flushSync;
     const Component = pickComponent(Comp);
     if (!Component) return { status: 'unverifiable', detail: `did not find a mountable React component exported by '${entry.bridge.file}' — real effect not verifiable, test by hand` };
 
     const container = document.createElement('div');
     document.body.appendChild(container);
-    let root;
-    const settle = () => new Promise((r) => setTimeout(r, 0));
     try {
       flushSync(() => { root = createRoot(container); root.render(React.createElement(Component)); });
       await settle();
@@ -192,12 +241,11 @@ async function probeReactEffect(appRoot, entry, ctx) {
     const beforeHTML = captureSnapshot(container);
     const beforeText = container.textContent || '';
     const handler = registry.handlers[entry.handler];
-    if (typeof handler !== 'function') { try { root.unmount(); } catch {} return { status: 'fail', detail: `el registro no expone el handler '${entry.handler}'` }; }
+    if (typeof handler !== 'function') return { status: 'fail', detail: `el registro no expone el handler '${entry.handler}'` };
 
     if (ctx.sensitive) {
       // Do NOT fire the effect; we proved it mounts and the handler resolves to a
       // live bridge function. Verify the bridge has the method, nothing more.
-      try { root.unmount(); } catch {}
       return { status: 'unverifiable', detail: 'confirmation action: its effect is not fired in the test render (security); wiring verified up to the confirmation point' };
     }
 
@@ -205,15 +253,25 @@ async function probeReactEffect(appRoot, entry, ctx) {
     try { await handler(ctx.params); } catch (e) { invokeErr = e; }
     await settle();
     try { flushSync(() => {}); } catch {}
-    if (invokeErr) { try { root.unmount(); } catch {} return { status: 'fail', detail: `invoking the handler, the real app threw: ${short(invokeErr)}` }; }
+    if (invokeErr) return { status: 'fail', detail: `invoking the handler, the real app threw: ${short(invokeErr)}` };
 
     const afterHTML = captureSnapshot(container);
     const afterText = container.textContent || '';
-    try { root.unmount(); } catch {}
     return decide(ctx.kind, { beforeHTML, beforeText, afterHTML, afterText });
   } catch (err) {
     return { status: 'unverifiable', detail: `could not prepare the test render (${short(err)}); real effect not automatically verifiable — test by hand` };
   } finally {
+    // Drain React WHILE the DOM is still alive: a synchronous unmount runs every
+    // pending passive-effect cleanup now, so nothing fires after we remove the
+    // jsdom globals below. Two settle ticks flush the scheduler's macro/microtasks.
+    try {
+      if (root) {
+        if (flushSync) flushSync(() => { try { root.unmount(); } catch { /* ignore */ } });
+        else { try { root.unmount(); } catch { /* ignore */ } }
+        await settle();
+        await settle();
+      }
+    } catch { /* ignore */ }
     try { cap.restore(); } catch {}
     try { fs.existsSync(harnessAbs) && fs.rmSync(harnessAbs); } catch {}
     try { fs.existsSync(outAbs) && fs.rmSync(outAbs); } catch {}
@@ -357,6 +415,9 @@ function installDom(jsdomMod, { storageKeys = [], kind } = {}) {
  * `sources` are the project's source files (for storage-key detection, etc.).
  */
 async function probeComponentEffect(appRoot, entry, opts = {}) {
+  // Defense-in-depth: a late headless-render teardown error (React/Vue passive
+  // cleanup firing after jsdom is closed) must never crash the CLI.
+  installProbeTeardownGuard();
   const framework = (opts.framework || 'web').toLowerCase();
   const kind = actionKind(entry);
   const params = probeParams(entry, kind);
@@ -376,4 +437,4 @@ async function probeComponentEffect(appRoot, entry, opts = {}) {
   return { status: 'unverifiable', detail: `framework '${framework}' has no render-probe; real effect not automatically verifiable` };
 }
 
-module.exports = { probeComponentEffect, actionKind, decide, SENTINEL, SEED_ID, installDom, pickComponent, detectStorageKeys, probeParams, captureSnapshot, short, loadEsbuild, loadJsdom, reqFrom, emptyAssetsPlugin, captureConsole, isVerboseProbe };
+module.exports = { probeComponentEffect, actionKind, decide, SENTINEL, SEED_ID, installDom, pickComponent, detectStorageKeys, probeParams, captureSnapshot, short, loadEsbuild, loadJsdom, reqFrom, emptyAssetsPlugin, captureConsole, isVerboseProbe, installProbeTeardownGuard, isProbeTeardownError };

package/src/verifyWire.js

@@ -47,11 +47,57 @@ function normErr(line) {
     .trim();
 }
 
+/**
+ * Is this output line a GENUINE compile/type/syntax failure (i.e. the code is
+ * really broken), as opposed to a style violation? These mean the safety net
+ * MUST act: the action does not actually work.
+ */
+function isRealCompileError(line) {
+  const l = String(line);
+  return /error\s+TS\d+|Type error:|Cannot find (?:module|name)|is not assignable|does not exist on type|has no exported member|Module not found|SyntaxError|Unexpected (?:token|keyword|reserved word)|Expression expected|Parsing error/i.test(l);
+}
+
+/**
+ * Is this output line a pure ESLint/style complaint? These do NOT mean the code
+ * is broken — they mean it breaks the PROJECT's style rules. We neutralize those
+ * on our own generated files and fence our injected blocks, so honestly they
+ * should never reach here; when one does, we still treat it as non-broken code.
+ */
+function isLintError(line) {
+  const l = String(line);
+  if (isRealCompileError(l)) return false;
+  // Reference to a known ESLint rule namespace / a bare `no-*` rule.
+  if (/@typescript-eslint\/|react-hooks\/|jsx-a11y\/|@next\/next\/|\bimport\/[a-z-]+|\breact\/[a-z-]+|prettier\/|\bno-[a-z][a-z-]+\b/.test(l)) return true;
+  // ESLint compact format "12:5  Error  message  rule" without a TS error code.
+  if (/^\s*\d+:\d+\s+(?:error|warning)\b/i.test(l) && !/TS\d+/.test(l)) return true;
+  return false;
+}
+
+/**
+ * Split error lines into { real, lint, unknown }. Unknown lines (an "Error" we
+ * cannot confidently classify) are treated as REAL by callers — we fail safe
+ * toward "the code might be broken", never toward shipping a red build.
+ */
+function classifyErrorLines(lines) {
+  const real = [];
+  const lint = [];
+  const unknown = [];
+  for (const l of lines || []) {
+    if (isRealCompileError(l)) real.push(l);
+    else if (isLintError(l)) lint.push(l);
+    else unknown.push(l);
+  }
+  return { real, lint, unknown };
+}
+
 /**
  * Did applying THIS action introduce a NEW build problem? Compare position-
  * normalized error lines after vs. baseline. Any error that is new (not present
  * in baseline) AND references a file we touched or our generated modules is
- * attributed to this action. Returns { ok, newErrors: string[] }.
+ * attributed to this action.
+ * Returns { ok, newErrors, realErrors, lintErrors }: `ok` is false on a genuine
+ * regression; `realErrors`/`lintErrors` classify the attributed lines so callers
+ * can tell "code is broken" (revert) from "style rule tripped" (style only).
  */
 function compileRegressed(baselineOutput, afterOutput, touchedFiles) {
   const before = new Set(extractErrorLines(baselineOutput).map(normErr));
@@ -61,12 +107,19 @@ function compileRegressed(baselineOutput, afterOutput, touchedFiles) {
   const ours = fresh.filter(
     (l) => /handlers\.generated|fyodos[\\/]bridge|FYODOS/i.test(l) || touched.some((t) => t && l.includes(t)),
   );
-  if (ours.length) return { ok: false, newErrors: ours };
+  if (ours.length) {
+    const { real, lint, unknown } = classifyErrorLines(ours);
+    return { ok: false, newErrors: ours, realErrors: [...real, ...unknown], lintErrors: lint };
+  }
   // Only when the app built cleanly before (no baseline errors) do we treat any
   // unattributable fresh error as a regression. If it was already broken, an
   // unattributable error is almost certainly pre-existing → don't blame ourselves.
-  if (fresh.length && !before.size) return { ok: false, newErrors: fresh.slice(0, 8) };
-  return { ok: true, newErrors: [] };
+  if (fresh.length && !before.size) {
+    const slice = fresh.slice(0, 8);
+    const { real, lint, unknown } = classifyErrorLines(slice);
+    return { ok: false, newErrors: slice, realErrors: [...real, ...unknown], lintErrors: lint };
+  }
+  return { ok: true, newErrors: [], realErrors: [], lintErrors: [] };
 }
 
 // ── Effect probe (in-process, real instance) ─────────────────────────────────────
@@ -212,4 +265,7 @@ async function probeEffect(appRoot, entry, opts = {}) {
   return { status: 'skipped', detail: 'module target not safely simulable in-process; verified by compilation' };
 }
 
-module.exports = { probeEffect, compileRegressed, extractErrorLines, readDexieStores };
+module.exports = {
+  probeEffect, compileRegressed, extractErrorLines, readDexieStores,
+  classifyErrorLines, isRealCompileError, isLintError,
+};

package/src/wireHandlers.js

@@ -40,7 +40,7 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
-const { probeEffect, compileRegressed } = require('./verifyWire');
+const { probeEffect, compileRegressed, classifyErrorLines } = require('./verifyWire');
 
 const DOC_BASENAME = 'FYODOS_HANDLERS.md';
 const REGISTRY_BASENAME = 'handlers.generated';
@@ -52,6 +52,31 @@ const GENERATED_MARKER = 'GENERATED by Fiodos — handler wiring';
 const EDIT_START = '// FYODOS:BRIDGE:START (auto-generado por Fiodos — seguro de eliminar)';
 const EDIT_END = '// FYODOS:BRIDGE:END';
 
+// Directives that make OUR generated files (handlers.generated, bridge) invisible
+// to the PROJECT's strict lint/typecheck. These files are ours, not the
+// developer's source, so they must not be judged by the project's STYLE rules: a
+// single `no-explicit-any` / `no-unused-vars` from ESLint, or an `exactOptional`
+// nit from a strict tsconfig, would otherwise fail `next build` and force a full
+// revert even though the code runs fine. We neutralize STYLE, never behavior —
+// if the REAL build (after this) still fails, that is a genuine error and the
+// safety net still reverts. `@ts-nocheck` MUST be in the leading comments.
+// ORDER MATTERS: `/* eslint-disable */` MUST be the very first line so it also
+// covers the `@ts-nocheck` line below — otherwise `@typescript-eslint/ban-ts-comment`
+// fires on `@ts-nocheck` itself (it is linted before a later disable takes effect).
+// TypeScript still honors `@ts-nocheck` when it sits in the leading comments, even
+// after another comment, so this ordering keeps BOTH the linter and tsc quiet.
+const GENERATED_FILE_DIRECTIVES =
+  '/* eslint-disable */\n' +
+  '// @ts-nocheck\n' +
+  '// biome-ignore-all\n';
+// Same idea for the few lines we inject INTO the user's own files: we cannot
+// disable type-checking on their file, so the injected code is written clean (no
+// explicit `any`, no unused params — see planComponentEdits), and we additionally
+// fence it from ESLint with a scoped disable/enable pair so no project style rule
+// can turn our insertion into a build-breaking error.
+const INJECT_ESLINT_DISABLE = '/* eslint-disable */';
+const INJECT_ESLINT_ENABLE = '/* eslint-enable */';
+
 function esc(name) {
   return String(name).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -767,6 +792,7 @@ function buildRegistryModule(plan, opts = {}) {
     : `const ${REGISTRY_EXPORT}${ts ? ': FiodosRegistries' : ''} = {`;
 
   const body =
+    `${GENERATED_FILE_DIRECTIVES}` +
     `${header}\n` +
     `${importLines.join('\n')}\n\n` +
     (typeDefs ? `${typeDefs}\n` : '') +
@@ -794,6 +820,7 @@ function buildBridgeModule(opts = {}) {
   const ts = opts.ts !== false;
   const esm = opts.esm !== false;
   const header =
+    `${GENERATED_FILE_DIRECTIVES}` +
     `/**\n` +
     ` * ${GENERATED_MARKER} (bridge holder).\n` +
     ` * Do not edit by hand. Your component registers its real functions here and the\n` +
@@ -870,11 +897,19 @@ function planComponentEdits(appRoot, plan, opts = {}) {
       }
     }
 
-    const argType = ts ? ': any' : '';
     const classField = entries.some((e) => e.bridge.scope === 'class-field');
     const methods = entries.map((e) => {
       const inv = e.bridge.invoke;
-      return `  ${JSON.stringify(e.bridge.method)}: (args${argType}) => (${inv}),`;
+      // This code lands in the USER's file, so it cannot carry `@ts-nocheck`; it
+      // must be lint- and type-clean by construction:
+      //  · NO explicit `any` annotation — the param type comes contextually from
+      //    registerFiodosBridge's signature, so there is no `no-explicit-any` and
+      //    no implicit-any either.
+      //  · OMIT the param entirely when the invocation never reads it, so strict
+      //    `no-unused-vars` cannot fire (TS allows callbacks with fewer params).
+      const usesArgs = /\bargs\b/.test(inv);
+      const param = usesArgs ? 'args' : '';
+      return `  ${JSON.stringify(e.bridge.method)}: (${param}) => (${inv}),`;
     });
 
     // Imports: registerFiodosBridge + any extra the invokes need (deduped).
@@ -897,7 +932,10 @@ function planComponentEdits(appRoot, plan, opts = {}) {
     const registerCall = classField
       ? `private __fyodosBridge = registerFiodosBridge({\n${methods.join('\n')}\n});`
       : `registerFiodosBridge({\n${methods.join('\n')}\n});`;
-    const registerBlock = `${EDIT_START}\n${registerCall}\n${EDIT_END}`;
+    // Fence our insertion from the project's ESLint config (style rules only — the
+    // code itself is clean and type-checked). `@ts-nocheck` can't be scoped to a
+    // block inside the user's file, so type-correctness is guaranteed by codegen.
+    const registerBlock = `${EDIT_START}\n${INJECT_ESLINT_DISABLE}\n${registerCall}\n${INJECT_ESLINT_ENABLE}\n${EDIT_END}`;
 
     // Match the anchor's leading indentation so the inserted block stays tidy.
     const lineStart = content.lastIndexOf('\n', bestIdx) + 1;
@@ -907,7 +945,7 @@ function planComponentEdits(appRoot, plan, opts = {}) {
       file,
       anchor,
       scope: classField ? 'class-field' : 'statement',
-      importBlock: `${EDIT_START}\n${importLines.join('\n')}\n${EDIT_END}`,
+      importBlock: `${EDIT_START}\n${INJECT_ESLINT_DISABLE}\n${importLines.join('\n')}\n${INJECT_ESLINT_ENABLE}\n${EDIT_END}`,
       registerBlock: registerBlock.split('\n').map((l) => (l ? indent + l : l)).join('\n'),
       intents: entries.map((e) => e.intent),
     });
@@ -1248,6 +1286,35 @@ function applyComponentEdits(appRoot, edits) {
   return { backups, edited };
 }
 
+/**
+ * Map regression error lines back to the specific entries that caused them, so
+ * we can revert ONLY the offending actions instead of the whole batch:
+ *   · BRIDGE entries → the error references the user file we edited (by basename).
+ *   · MODULE entries → the error sits in handlers.generated and mentions the
+ *     intent / handler / call expression of that entry.
+ * Returns a Set of culprit intents. Empty means "could not isolate" (the caller
+ * then falls back to a full revert rather than guessing).
+ */
+function attributeCulprits(entries, errorLines) {
+  const culprits = new Set();
+  const lines = (errorLines || []).map(String);
+  if (!lines.length) return culprits;
+  for (const e of entries || []) {
+    const intent = e.intent;
+    if (e.kind === 'bridge') {
+      const base = path.basename(normRel(e.bridge && e.bridge.file));
+      if (base && lines.some((l) => l.includes(base))) culprits.add(intent);
+    } else {
+      const tokens = [intent, e.handler, e.callExpr].filter(Boolean).map(String);
+      const inRegistry = lines.some(
+        (l) => /handlers\.generated/i.test(l) && tokens.some((t) => t && l.includes(t)),
+      );
+      if (inRegistry) culprits.add(intent);
+    }
+  }
+  return culprits;
+}
+
 /** Restore files to their pre-edit content and delete generated files. */
 function revertAll(backups, generatedFiles) {
   for (const b of backups || []) {
@@ -1398,7 +1465,13 @@ async function runAutoCorrectionLoop(ctx) {
         try {
           const after = await testRunner(appRoot, { framework });
           const reg = compileRegressed(baseline.output, after.output, iso.touched);
-          if (!reg.ok) { ok = false; lastError = `compilation: ${reg.newErrors.join(' | ').slice(0, 600)}`; }
+          // Only a GENUINE compile/type error means the action is broken. A pure
+          // ESLint/style complaint is neutralized in what we actually write (our
+          // files carry @ts-nocheck + eslint-disable; injected blocks are fenced),
+          // so it must not drop the action nor burn an AI-correction attempt.
+          if (!reg.ok && reg.realErrors && reg.realErrors.length) {
+            ok = false; lastError = `compilation: ${reg.realErrors.join(' | ').slice(0, 600)}`;
+          }
           if (ok) {
             const eff = await probeEffect(appRoot, entry, { fyodosDirRel, framework, sources: files, sensitive: entry.requireConfirmation });
             if (eff.status === 'fail') { ok = false; stage = 'effect'; lastError = `effect: ${eff.detail}`; }
@@ -1638,16 +1711,83 @@ async function wireHandlers(appRoot, opts = {}) {
     }
 
     // Final combined build (each action passed in isolation; confirm the union).
-    let test;
-    try {
-      test = await testRunner(appRoot, { framework });
-    } catch (err) {
-      test = { ok: false, stage: 'runner', output: err && err.message };
-    }
-    const reg = compileRegressed((baseline && baseline.output) || '', (test && test.output) || '',
-      [...finalEdits.map((e) => e.file), 'handlers.generated', 'bridge']);
-    const combinedRegression = !reg.ok && baseline && baseline.ok;
+    const touchedForReg = () => [...finalEdits.map((e) => e.file), 'handlers.generated', 'bridge'];
+    const runBuild = async () => {
+      try {
+        return await testRunner(appRoot, { framework });
+      } catch (err) {
+        return { ok: false, stage: 'runner', output: err && err.message };
+      }
+    };
+    let test = await runBuild();
+    let reg = compileRegressed((baseline && baseline.output) || '', (test && test.output) || '', touchedForReg());
+    let combinedRegression = !reg.ok && baseline && baseline.ok;
+
+    // PARTIAL DEGRADATION: if the union regressed, don't nuke the whole batch.
+    // Attribute the NEW errors to the specific entries that caused them, revert
+    // only those, and rebuild once with the survivors. The dev loses the
+    // problematic action(s), never the rest. We attribute on the full error set
+    // (real + lint): a non-zero build is unacceptable to ship regardless of the
+    // cause, but we record WHY each culprit fell (broken code vs. a style rule
+    // our fence could not silence) for an honest report.
+    let degraded = null;
     if (combinedRegression && revertOnFailure) {
+      const culprits = attributeCulprits(finalAuto, reg.newErrors);
+      const survivors = finalAuto.filter((e) => !culprits.has(e.intent));
+      if (culprits.size && survivors.length && survivors.length < finalAuto.length) {
+        const { real, lint } = classifyErrorLines(reg.newErrors);
+        const culpritEntries = finalAuto.filter((e) => culprits.has(e.intent));
+        // Revert everything, then re-apply ONLY the survivors and rebuild once.
+        revertAll(backups, generatedFiles);
+        const survivorPlan = { auto: survivors, review: droppedReview, manual: droppedReview, entries: [...survivors, ...droppedReview] };
+        const survivorEdits = planComponentEdits(appRoot, survivorPlan, { ts });
+        const survivorHasBridge = survivors.some((e) => e.kind === 'bridge');
+        const survivorGenerated = [registryAbs];
+        let survivorBackups = [];
+        try {
+          if (survivorHasBridge) {
+            fs.writeFileSync(bridgeAbs, buildBridgeModule({ ts, esm }));
+            survivorGenerated.push(bridgeAbs);
+          }
+          fs.writeFileSync(registryAbs, buildRegistryModule(survivorPlan, { ts, esm }));
+          ({ backups: survivorBackups } = applyComponentEdits(appRoot, survivorEdits));
+        } catch (err) {
+          revertAll(survivorBackups, survivorGenerated);
+          return { status: 'failed', docPath: docAbs, error: err, plan: finalPlan, verification: loop.attemptsLog };
+        }
+        const survivorTest = await runBuild();
+        const survivorReg = compileRegressed((baseline && baseline.output) || '', (survivorTest && survivorTest.output) || '', [...survivorEdits.map((e) => e.file), 'handlers.generated', 'bridge']);
+        if (survivorReg.ok || !(baseline && baseline.ok)) {
+          // Survivors build clean → keep them; report the dropped culprits.
+          degraded = culpritEntries.map((e) => ({
+            ...e, confidence: 'review',
+            reason: `wired clean in isolation but broke the combined build${lint.length && !real.length ? ' (project style rule our fence could not silence)' : ''}; reverted to keep the rest building`,
+          }));
+          const mergedReview = [...droppedReview, ...degraded];
+          const keptPlan = { auto: survivors, review: mergedReview, manual: mergedReview, entries: [...survivors, ...mergedReview] };
+          fs.writeFileSync(docAbs, buildHandlerDoc(keptPlan, {
+            appName: appName || path.basename(appRoot),
+            framework, registryRel, bridgeRel, edits: survivorEdits, mountSnippet,
+            verification: loop.attemptsLog,
+          }));
+          return {
+            status: 'applied', partial: true, docPath: docAbs, registryFile: registryAbs, registryRel,
+            bridgeFile: survivorHasBridge ? bridgeAbs : null, mountSnippet,
+            autoCount: survivors.length, manualCount: mergedReview.length,
+            editedFiles: survivorEdits.map((e) => e.file), plan: keptPlan,
+            verification: loop.attemptsLog, dropped: [...loop.dropped, ...degraded],
+            degraded, baseline, test: survivorTest,
+            preexistingFailure: baseline && baseline.ok === false && baseline.stage !== 'skipped-no-deps',
+          };
+        }
+        // Even the survivors regressed → fall through to a full revert (already reverted).
+        revertAll(survivorBackups, survivorGenerated);
+        return {
+          status: 'reverted', docPath: docAbs, plan: finalPlan, test: survivorTest,
+          verification: loop.attemptsLog, dropped: loop.dropped, baseline,
+        };
+      }
+      // Could not isolate a culprit → conservative full revert.
       revertAll(backups, generatedFiles);
       return {
         status: 'reverted', docPath: docAbs, plan: finalPlan, test,
@@ -1733,11 +1873,21 @@ function reportHandlerResult(result, colors = {}, opts = {}) {
   switch (result.status) {
     case 'applied':
     case 'applied-untested':
+      if (result.partial && Array.isArray(result.degraded) && result.degraded.length) {
+        // Partial degradation: most actions are wired; only the few that broke the
+        // combined build were rolled back so the rest (and the build) stay green.
+        const names = result.degraded.map((d) => `'${d.intent}'`).join(', ');
+        console.error(`${tag} · ${dim || ''}Wired ${result.autoCount} action(s). ${result.degraded.length} (${names}) wired clean alone but broke the combined build, so only those were reverted — the rest are live. See the document to apply them by hand.${reset || ''}`);
+        return;
+      }
       if (quiet) return;
       break;
     case 'reverted':
-      console.error(`${tag} · ✗ Post-wiring build check failed (${result.test && result.test.stage}) — reverted all changes, your app is untouched.`);
-      console.error(`${tag} · ${dim || ''}Details in the document; nothing was modified in your code.${reset || ''}`);
+      // Not a fatal error: the manifest is published and the orb + link actions
+      // work. Only the OPTIONAL in-code wiring for function actions was rolled
+      // back because the project's build did not pass with it — so we leave the
+      // code untouched and document how to wire it by hand. Keep the tone calm.
+      console.error(`${tag} · ${dim || ''}Voice actions are published and the orb is live. The optional in-code wiring for function actions was skipped (your build didn't pass with it), so your code was left untouched — see the document to apply it by hand.${reset || ''}`);
       break;
     case 'manual-only':
       if (quiet) return;