@fiodos/cli 0.1.0

package/src/llm.js

@@ -0,0 +1,144 @@
+/**
+ * Layer 3 — EXPLICIT LLM calls inside the pipeline.
+ *
+ * The static layers (1+2) extract facts; this layer makes judgment calls the
+ * code cannot express, and every call is LOGGED so the final report can show
+ * exactly which decisions came from the model vs from static analysis:
+ *
+ *   1. classifyApp        — app type vs the pattern catalog
+ *   2. curateActions      — which detected callables deserve agent exposure,
+ *                           category, sensitivity, parameters, label
+ *   3. writeRouteMeta     — intent ids, labels and example phrases for routes
+ *   4. patternGapFill     — given the matched pattern, propose what's missing
+ *
+ * Model: gpt-4o-mini via the OpenAI REST API (OPENAI_API_KEY env var).
+ */
+'use strict';
+
+const LLM_LOG = [];
+
+function getLog() {
+  return LLM_LOG;
+}
+
+async function callLLM(taskName, system, user, { maxTokens = 2000 } = {}) {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) throw new Error('OPENAI_API_KEY is required for the LLM layer');
+
+  const t0 = Date.now();
+  const res = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model: process.env.AUTO_MANIFEST_MODEL || 'gpt-4o-mini',
+      messages: [
+        { role: 'system', content: system },
+        { role: 'user', content: user },
+      ],
+      temperature: 0.2,
+      max_tokens: maxTokens,
+      response_format: { type: 'json_object' },
+    }),
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`LLM call '${taskName}' failed: ${res.status} ${body.slice(0, 300)}`);
+  }
+  const data = await res.json();
+  const content = data.choices?.[0]?.message?.content || '{}';
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    throw new Error(`LLM call '${taskName}' returned non-JSON output`);
+  }
+  LLM_LOG.push({
+    task: taskName,
+    ms: Date.now() - t0,
+    promptChars: system.length + user.length,
+    usage: data.usage || null,
+  });
+  return parsed;
+}
+
+/** 1. Classify the app against the available pattern catalog. */
+async function classifyApp(appSummary, patternSummaries) {
+  const system =
+    'You classify a mobile app into one of the available integration patterns, or "none". ' +
+    'Answer JSON: {"pattern": "<id-or-none>", "confidence": 0..1, "appKind": "<free text>", "reason": "<short>"}';
+  const user =
+    `Available patterns:\n${patternSummaries.map((p) => `- id=${p.id}: ${p.summary}`).join('\n')}\n\n` +
+    `App evidence (from static analysis):\n${JSON.stringify(appSummary, null, 1).slice(0, 4000)}`;
+  return callLLM('classifyApp', system, user, { maxTokens: 300 });
+}
+
+/**
+ * 2. Curate detected callables into agent actions.
+ * Batched: large candidate lists are processed in chunks so no candidate is
+ * silently dropped by prompt-size truncation.
+ */
+async function curateActions(appKind, candidates) {
+  const BATCH = 14;
+  const all = [];
+  for (let i = 0; i < candidates.length; i += BATCH) {
+    const chunk = candidates.slice(i, i + BATCH);
+    const res = await curateActionsBatch(appKind, chunk);
+    all.push(...(res.actions || []));
+  }
+  return { actions: all };
+}
+
+async function curateActionsBatch(appKind, candidates) {
+  const system =
+    'You design the action surface of an in-app voice agent. Input: callables detected by static ' +
+    'analysis of a mobile app (handlers, store actions, buttons, alerts). For EACH candidate decide:\n' +
+    '- expose: should the voice agent be able to trigger it? (skip pure-UI plumbing like toggling pickers, ' +
+    'rendering callbacks, backdrop handlers, text-input onChange)\n' +
+    '- intent: snake_case id; label: short human label (English); category: one of discovery|workout|history|account|navigation|other\n' +
+    '- requireConfirmation: true only for destructive/sensitive operations (deleting data, losing progress, signing out, spending money)\n' +
+    '- confirmationMessage: required question if requireConfirmation\n' +
+    '- parameters: object of {name:{type,required,description}} ONLY when the user must provide a value by voice (e.g. a search query)\n' +
+    '- requiresVisibleContent: true when the action operates on an item the user is looking at\n' +
+    '- examples: 3-4 natural English voice phrases\n' +
+    '- evidence_used: which input evidence justified your decision\n' +
+    'Be conservative: when a candidate looks like internal plumbing, expose=false. ' +
+    'Sign-in/sign-up/verification flows requiring typed credentials should be expose=false ' +
+    '(a voice agent cannot dictate passwords safely).\n' +
+    'Return a decision for EVERY candidate. "intent" MUST be a plain string.\n' +
+    'Answer JSON: {"actions": [{...candidate fields above, "source_name": "<input name>"}]}';
+  const user =
+    `App kind: ${appKind}\n\nCandidates (with static evidence):\n` +
+    JSON.stringify(candidates, null, 1).slice(0, 14000);
+  return callLLM('curateActions', system, user, { maxTokens: 4000 });
+}
+
+/** 3. Route intents, labels, examples. */
+async function writeRouteMeta(appKind, routes) {
+  const system =
+    'You name navigation intents for an in-app voice agent. For each route give: ' +
+    'intent (snake_case), label (short English), examples (3-4 natural English voice phrases). ' +
+    'Skip auth screens the agent should not navigate to mid-session if any seem like sign-in/sign-up (mark skip=true). ' +
+    'For dynamic routes ([param]) mark dynamic=true and skip=true (they need a runtime parameter the static manifest cannot provide). ' +
+    'Answer JSON: {"routes": [{"routePath": "...", "intent": "...", "label": "...", "examples": [...], "skip": false, "skipReason": ""}]}';
+  const user = `App kind: ${appKind}\n\nRoutes:\n${JSON.stringify(routes, null, 1)}`;
+  return callLLM('writeRouteMeta', system, user, { maxTokens: 2500 });
+}
+
+/** 4. Pattern gap-fill: what does the matched pattern expect that we missed? */
+async function patternGapFill(patternId, patternText, draftManifestSummary) {
+  const system =
+    'You compare a draft voice-agent manifest against an integration pattern document. ' +
+    'List actions/routes the pattern suggests SHOULD usually exist for this app type but are missing or ' +
+    'under-specified in the draft. Only suggest things genuinely implied by the pattern; do not invent. ' +
+    'Answer JSON: {"suggestions": [{"kind": "action"|"route", "intent": "...", "label": "...", "why": "...", ' +
+    '"confidence": 0..1}], "patternUseful": true|false, "notes": "<honest assessment of how much this pattern helped>"}';
+  const user =
+    `Pattern (${patternId}):\n${patternText.slice(0, 5000)}\n\nDraft manifest summary:\n` +
+    JSON.stringify(draftManifestSummary, null, 1).slice(0, 5000);
+  return callLLM('patternGapFill', system, user, { maxTokens: 1200 });
+}
+
+module.exports = { classifyApp, curateActions, writeRouteMeta, patternGapFill, getLog };

package/src/loadEnv.js

@@ -0,0 +1,81 @@
+/**
+ * Load KEY=VALUE pairs from local .env files into process.env.
+ * Does not overwrite variables already set in the shell.
+ *
+ * Search order (first found wins per key, later files only fill gaps):
+ *   1. tools/auto-manifest/.env
+ *   2. fyodos/backend/.env
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function parseEnvFile(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+  const out = {};
+  for (const line of fs.readFileSync(filePath, 'utf8').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+function applyEnv(parsed) {
+  for (const [key, value] of Object.entries(parsed)) {
+    if (process.env[key] === undefined || process.env[key] === '') {
+      process.env[key] = value;
+    }
+  }
+}
+
+/** Derive FYODOS_API_KEY from FYODOS_CLIENT_KEYS (api_key:client_id,...). */
+function deriveFiodosApiKey() {
+  if (process.env.FYODOS_API_KEY) return;
+  const raw = process.env.FYODOS_CLIENT_KEYS || '';
+  const first = raw.split(',')[0]?.trim();
+  if (!first || !first.includes(':')) return;
+  const [apiKey] = first.split(':');
+  if (apiKey) process.env.FYODOS_API_KEY = apiKey;
+}
+
+/** Prefer the target app's Fiodos API key from .env when publishing that app. */
+function loadAppEnv(appRoot) {
+  if (!appRoot) return;
+  const appEnv = parseEnvFile(path.join(appRoot, '.env'));
+  const appKey =
+    appEnv.VITE_FYODOS_API_KEY?.trim() ||
+    appEnv.NEXT_PUBLIC_FYODOS_API_KEY?.trim() ||
+    appEnv.EXPO_PUBLIC_FYODOS_API_KEY?.trim();
+  if (appKey) process.env.FYODOS_API_KEY = appKey;
+  const appUrl =
+    appEnv.VITE_FYODOS_API_URL?.trim() ||
+    appEnv.NEXT_PUBLIC_FYODOS_API_URL?.trim() ||
+    appEnv.EXPO_PUBLIC_FYODOS_API_URL?.trim();
+  if (appUrl) process.env.FYODOS_API_URL = appUrl;
+}
+
+function loadEnv() {
+  const root = path.join(__dirname, '..');
+  const files = [
+    path.join(root, '.env'),
+    path.join(root, '../../backend/.env'),
+  ];
+  for (const file of files) {
+    applyEnv(parseEnvFile(file));
+  }
+  deriveFiodosApiKey();
+}
+
+module.exports = { loadEnv, loadAppEnv };

package/src/patterns.js

@@ -0,0 +1,28 @@
+/**
+ * Layer 4 — pattern knowledge base.
+ *
+ * Loads patterns/*.md from the Fiodos monorepo, gives the LLM a summary list
+ * for classification, and (when a pattern matches) feeds the full pattern to
+ * the gap-fill step. With only 2-3 patterns today this layer is a seed: the
+ * mechanism works, the coverage will come with volume.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function loadPatterns(patternsDir) {
+  if (!fs.existsSync(patternsDir)) return [];
+  return fs
+    .readdirSync(patternsDir)
+    .filter((f) => f.endsWith('.md') && f !== 'README.md')
+    .map((f) => {
+      const text = fs.readFileSync(path.join(patternsDir, f), 'utf8');
+      const id = f.replace(/\.md$/, '');
+      // First heading line as summary
+      const firstLine = text.split('\n').find((l) => l.startsWith('#')) || id;
+      return { id, file: f, text, summary: firstLine.replace(/^#+\s*/, '') };
+    });
+}
+
+module.exports = { loadPatterns };

package/src/postWireTest.js

@@ -0,0 +1,91 @@
+/**
+ * postWireTest — verify the app still builds after Fiodos wired the handlers and
+ * (when needed) edited the user's own components. This is the safety net that
+ * lets wireHandlers REVERT instead of leaving a broken app.
+ *
+ * It runs the app's real build/typecheck (the strongest "didn't break" signal
+ * for a web project) with a timeout, and returns a structured result. It NEVER
+ * throws — a thrown/timed-out process is reported as a failed/untested stage so
+ * the caller can decide to revert.
+ *
+ * Contract:
+ *   runPostWireTest(appRoot, opts) -> {
+ *     ok: boolean,            // true only when the build/typecheck succeeded
+ *     stage: string,          // 'build' | 'typecheck' | 'skipped-no-deps' | 'timeout' | 'error'
+ *     command: string,        // what was run
+ *     output: string,         // tail of stdout+stderr (trimmed)
+ *   }
+ *
+ * When dependencies are not installed we cannot build; we return ok:true with
+ * stage 'skipped-no-deps' so the caller marks the wiring 'applied-untested'
+ * (a warning) rather than reverting a perfectly good wiring.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function readPkg(appRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(appRoot, 'package.json'), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/** Choose the lightest reliable "does it still compile" command for this app. */
+function chooseCommand(appRoot, pkg) {
+  const scripts = pkg.scripts || {};
+  // Prefer an explicit typecheck (fast, no bundling) when available.
+  for (const name of ['typecheck', 'type-check', 'check']) {
+    if (scripts[name]) return { stage: 'typecheck', args: ['run', name], label: `npm run ${name}` };
+  }
+  if (scripts.build) return { stage: 'build', args: ['run', 'build'], label: 'npm run build' };
+  // Fallback: bare tsc --noEmit when there is a tsconfig.
+  if (fs.existsSync(path.join(appRoot, 'tsconfig.json'))) {
+    return { stage: 'typecheck', args: ['exec', '--', 'tsc', '--noEmit'], label: 'npx tsc --noEmit' };
+  }
+  return null;
+}
+
+function tail(s, n = 60) {
+  const lines = String(s || '').split('\n');
+  return lines.slice(-n).join('\n').trim();
+}
+
+async function runPostWireTest(appRoot, opts = {}) {
+  const timeoutMs = opts.timeoutMs || 240000;
+  if (!fs.existsSync(path.join(appRoot, 'node_modules'))) {
+    return {
+      ok: true,
+      stage: 'skipped-no-deps',
+      command: '(none)',
+      output: 'node_modules ausente: no se pudo ejecutar el build (instala dependencias para verificarlo).',
+    };
+  }
+  const pkg = readPkg(appRoot);
+  const chosen = chooseCommand(appRoot, pkg);
+  if (!chosen) {
+    return { ok: true, stage: 'skipped-no-deps', command: '(none)', output: 'no hay script de build/typecheck.' };
+  }
+
+  const res = spawnSync('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,
+  });
+
+  if (res.error && res.error.code === 'ETIMEDOUT') {
+    return { ok: false, stage: 'timeout', command: chosen.label, output: `build excedió ${Math.round(timeoutMs / 1000)}s` };
+  }
+  if (res.error) {
+    return { ok: false, stage: 'error', command: chosen.label, output: String(res.error.message || res.error) };
+  }
+  const output = tail(`${res.stdout || ''}\n${res.stderr || ''}`);
+  return { ok: res.status === 0, stage: chosen.stage, command: chosen.label, output };
+}
+
+module.exports = { runPostWireTest, chooseCommand };

package/src/renderProbe.js

@@ -0,0 +1,333 @@
+/**
+ * renderProbe — REAL-EFFECT verification for component-local state.
+ *
+ * For actions whose state lives inside a component (React useState / Vue ref /
+ * Angular), "it compiles + the symbol exists" is NOT proof the action works. So
+ * here we actually MOUNT the user's real component in a headless DOM, invoke the
+ * generated handler/bridge with test params, and confirm the rendered UI changes
+ * as it should (the item appears, disappears, or the view mutates).
+ *
+ * Returns one of:
+ *   { status: 'effect-pass', detail }     mounted, invoked, UI changed as expected
+ *   { status: 'fail', detail }            mounted + invoked but NO/incorrect effect
+ *                                         (→ feeds the auto-correction loop)
+ *   { status: 'unverifiable', detail }    could not mount/seed reliably in headless
+ *                                         (honest: "review manually", never faked)
+ *
+ * Security: callers pass `sensitive` for requireConfirmation actions; those are
+ * NEVER executed here — we mount and confirm the wiring resolves, but do not fire
+ * the (possibly irreversible) effect.
+ *
+ * Standard per-framework tooling (resolved from the APP so versions match):
+ *   React  → react-dom/client + act, in jsdom
+ *   Vue    → vue (createApp) + @vue/compiler-sfc, in jsdom
+ *   Angular→ (headless TestBed is not reliable in a bare CLI; reported honestly
+ *            as unverifiable with the reason)
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SENTINEL = `FiodosProbe_${Math.random().toString(36).slice(2, 8)}`;
+const SEED_ID = 'fyodos-seed-id-1';
+
+function reqFrom(appRoot, mod) {
+  try { return require(path.join(appRoot, 'node_modules', mod)); } catch { return null; }
+}
+function loadEsbuild(appRoot) {
+  return reqFrom(appRoot, 'esbuild') || (() => { try { return require('esbuild'); } catch { return null; } })();
+}
+function loadJsdom() {
+  try { return require('jsdom'); } catch { return null; }
+}
+
+/** esbuild plugin that empties style/asset imports (works on old esbuild that
+ *  lacks the 'empty' loader). Side-effect CSS imports become no-ops. */
+function emptyAssetsPlugin() {
+  return {
+    name: 'fyodos-empty-assets',
+    setup(build) {
+      build.onLoad({ filter: /\.(css|scss|sass|less|styl|svg|png|jpe?g|gif|webp|avif|woff2?|ttf|eot|ico)$/ }, () => ({ contents: 'export default "";', loader: 'js' }));
+    },
+  };
+}
+
+/** Classify the action so we know what UI change to expect. */
+function actionKind(entry) {
+  const s = `${entry.intent || ''} ${entry.handler || ''} ${entry.label || ''}`.toLowerCase();
+  if (/\b(add|create|new|insert|append|save|submit)\b|add|create|new/.test(s)) return 'add';
+  if (/delete|remove|destroy|clear|trash/.test(s)) return 'delete';
+  if (/toggle|complete|done|check|mark|finish/.test(s)) return 'toggle';
+  if (/open|show|navigate|go|close|hide|view|select/.test(s)) return 'ui';
+  return 'other';
+}
+
+/** Build test params, putting a unique sentinel into the main text-like field. */
+function probeParams(entry, kind) {
+  const p = {};
+  for (const mp of entry.manifestParams || []) {
+    const n = (mp.name || '').toLowerCase();
+    if (/title|text|name|label|todo|task|note|desc|content|message/.test(n)) p[mp.name] = SENTINEL;
+    else if (/\bid\b|key|index/.test(n)) p[mp.name] = SEED_ID;
+    else if (/done|complete|check|status/.test(n)) p[mp.name] = true;
+    else if (/count|qty|amount|num/.test(n)) p[mp.name] = 1;
+    else p[mp.name] = SENTINEL;
+  }
+  return p;
+}
+
+/** localStorage keys the component hydrates from, so we can seed an item. */
+function detectStorageKeys(sources) {
+  const keys = new Set();
+  for (const s of sources || []) {
+    const re = /localStorage\.getItem\(\s*['"]([^'"]+)['"]/g;
+    let m;
+    while ((m = re.exec(s.content || ''))) keys.add(m[1]);
+  }
+  return [...keys];
+}
+
+/** Generic seed record covering the common todo/item field shapes. */
+function seedRecord() {
+  return { id: SEED_ID, title: SENTINEL, text: SENTINEL, name: SENTINEL, label: SENTINEL, completed: false, done: false };
+}
+
+// ── React ──────────────────────────────────────────────────────────────────────
+
+async function probeReactEffect(appRoot, entry, ctx) {
+  const esbuild = loadEsbuild(appRoot);
+  const jsdomMod = loadJsdom();
+  if (!esbuild || !jsdomMod) {
+    return { status: 'unverifiable', detail: `no se pudo montar el render headless (${!esbuild ? 'esbuild' : 'jsdom'} no disponible); cableado aplicado, efecto real no verificable automáticamente — probar a mano` };
+  }
+  const fyodosDirAbs = path.join(appRoot, ctx.fyodosDirRel);
+  const componentAbs = path.join(appRoot, entry.bridge.file);
+  const registryAbs = path.join(fyodosDirAbs, 'handlers.generated.js');
+  const entryRel = './' + path.relative(fyodosDirAbs, componentAbs).split(path.sep).join('/');
+
+  const harnessAbs = path.join(fyodosDirAbs, '__fyodos_probe_entry.jsx');
+  const outAbs = path.join(os.tmpdir(), `fyodos-probe-${Date.now()}.cjs`);
+  const harness =
+    `import * as Comp from '${entryRel}';\n` +
+    `import { fyodosGeneratedRegistries } from './handlers.generated';\n` +
+    `import * as ReactNS from 'react';\n` +
+    `import { createRoot } from 'react-dom/client';\n` +
+    `import { flushSync } from 'react-dom';\n` +
+    `export const probe = { React: ReactNS.default || ReactNS, createRoot, flushSync, Comp, registry: fyodosGeneratedRegistries };\n`;
+
+  let restore = () => {};
+  try {
+    fs.writeFileSync(harnessAbs, harness);
+    await esbuild.build({
+      entryPoints: [harnessAbs],
+      outfile: outAbs,
+      bundle: true,
+      format: 'cjs',
+      platform: 'node',
+      jsx: 'automatic',
+      jsxDev: false,
+      define: { 'process.env.NODE_ENV': '"development"' },
+      plugins: [emptyAssetsPlugin()],
+      logLevel: 'silent',
+      absWorkingDir: fyodosDirAbs,
+    });
+
+    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 Component = pickComponent(Comp);
+    if (!Component) return { status: 'unverifiable', detail: `no encontré un componente React montable exportado por '${entry.bridge.file}' — efecto real no verificable a mano` };
+
+    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();
+      flushSync(() => {});
+    } catch (err) {
+      return { status: 'unverifiable', detail: `el componente no se pudo renderizar en aislamiento (${short(err)}); efecto real no verificable automáticamente — probar a mano` };
+    }
+
+    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 (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: 'acción con confirmación: no se dispara su efecto en el render de prueba (seguridad); cableado verificado hasta el punto de confirmación' };
+    }
+
+    let invokeErr = null;
+    try { await handler(ctx.params); } catch (e) { invokeErr = e; }
+    await settle();
+    try { flushSync(() => {}); } catch {}
+    if (invokeErr) { try { root.unmount(); } catch {} return { status: 'fail', detail: `al invocar el handler la app real lanzó: ${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: `no se pudo preparar el render de prueba (${short(err)}); efecto real no verificable automáticamente — probar a mano` };
+  } finally {
+    try { fs.existsSync(harnessAbs) && fs.rmSync(harnessAbs); } catch {}
+    try { fs.existsSync(outAbs) && fs.rmSync(outAbs); } catch {}
+    try { restore(); } catch {}
+  }
+}
+
+/** Snapshot that also captures form-control state (checked/value), which React
+ *  sets as DOM properties and would NOT show up in innerHTML alone (e.g. toggles). */
+function captureSnapshot(container) {
+  let s = container.innerHTML;
+  try {
+    const inputs = container.querySelectorAll('input, textarea, select');
+    inputs.forEach((el, i) => { s += `|#${i}:${el.type || ''}:${el.checked ? '1' : '0'}:${el.value || ''}`; });
+  } catch { /* ignore */ }
+  return s;
+}
+
+function pickComponent(Comp) {
+  if (!Comp) return null;
+  if (typeof Comp.default === 'function') return Comp.default;
+  for (const v of Object.values(Comp)) {
+    if (typeof v === 'function' && /^[A-Z]/.test(v.name || '')) return v;
+  }
+  return null;
+}
+
+/** Decide pass/fail/unverifiable from the before/after DOM and the action kind. */
+function decide(kind, snap) {
+  const { beforeHTML, beforeText, afterHTML, afterText } = snap;
+  const htmlChanged = beforeHTML !== afterHTML;
+  const sentinelAppeared = !beforeText.includes(SENTINEL) && afterText.includes(SENTINEL);
+  const sentinelDisappeared = beforeText.includes(SENTINEL) && !afterText.includes(SENTINEL);
+
+  if (kind === 'add') {
+    if (sentinelAppeared) return { status: 'effect-pass', detail: `tras invocar la acción, "${SENTINEL}" aparece en la UI renderizada (el item se añadió de verdad)` };
+    if (htmlChanged) return { status: 'effect-pass', detail: 'la UI cambió tras invocar la acción (efecto observado en el render)' };
+    return { status: 'fail', detail: 'la acción se invocó pero la UI no cambió ni apareció el valor enviado (no produce su efecto)' };
+  }
+  if (kind === 'delete') {
+    if (sentinelDisappeared) return { status: 'effect-pass', detail: 'el item sembrado desapareció de la UI tras invocar la acción (se borró de verdad)' };
+    if (htmlChanged) return { status: 'effect-pass', detail: 'la UI cambió tras invocar la acción de borrado' };
+    return { status: 'unverifiable', detail: 'no se observó cambio al borrar (quizá no había item sembrado en aislamiento); cableado aplicado, efecto no confirmado — probar a mano' };
+  }
+  if (kind === 'toggle') {
+    if (htmlChanged) return { status: 'effect-pass', detail: 'la UI cambió tras invocar la acción (estado del item alternado)' };
+    return { status: 'unverifiable', detail: 'no se observó cambio al alternar (quizá sin item sembrado en aislamiento); cableado aplicado, efecto no confirmado — probar a mano' };
+  }
+  // ui / other
+  if (htmlChanged) return { status: 'effect-pass', detail: 'la UI del componente cambió tras invocar la acción' };
+  return { status: 'unverifiable', detail: 'la acción no produjo un cambio observable en el render aislado; cableado aplicado, efecto no confirmado — probar a mano' };
+}
+
+function short(err) {
+  return String((err && err.message) || err).split('\n')[0].slice(0, 200);
+}
+
+/**
+ * Install a jsdom-backed DOM on the global scope (saving anything we overwrite so
+ * we can restore it). Seeds localStorage keys with a sentinel record so delete/
+ * toggle actions have something to act on.
+ */
+function installDom(jsdomMod, { storageKeys = [], kind } = {}) {
+  const { JSDOM } = jsdomMod;
+  const dom = new JSDOM('<!doctype html><html><body></body></html>', { url: 'http://localhost/', pretendToBeVisual: true });
+  const { window } = dom;
+  // Seed storage BEFORE the component hydrates (only useful for delete/toggle).
+  if (kind === 'delete' || kind === 'toggle') {
+    for (const k of storageKeys.length ? storageKeys : ['ITEMS', 'todos', 'tasks']) {
+      try { window.localStorage.setItem(k, JSON.stringify([seedRecord()])); } catch {}
+    }
+  }
+  const values = {
+    window,
+    document: window.document,
+    navigator: window.navigator,
+    HTMLElement: window.HTMLElement,
+    Node: window.Node,
+    Element: window.Element,
+    Event: window.Event,
+    CustomEvent: window.CustomEvent,
+    getComputedStyle: window.getComputedStyle.bind(window),
+    requestAnimationFrame: (cb) => setTimeout(() => cb(Date.now()), 0),
+    cancelAnimationFrame: (id) => clearTimeout(id),
+    localStorage: window.localStorage,
+    sessionStorage: window.sessionStorage,
+    location: window.location,
+    history: window.history,
+    MutationObserver: window.MutationObserver,
+    SVGElement: window.SVGElement,
+    Text: window.Text,
+    Comment: window.Comment,
+    DocumentFragment: window.DocumentFragment,
+    NodeList: window.NodeList,
+    HTMLInputElement: window.HTMLInputElement,
+    HTMLTextAreaElement: window.HTMLTextAreaElement,
+    HTMLSelectElement: window.HTMLSelectElement,
+    DOMParser: window.DOMParser,
+    XMLSerializer: window.XMLSerializer,
+  };
+  const saved = {};
+  const savedDesc = {};
+  for (const k of Object.keys(values)) {
+    saved[k] = global[k];
+    savedDesc[k] = Object.getOwnPropertyDescriptor(global, k);
+    try {
+      global[k] = values[k];
+    } catch {
+      // Some globals (navigator in Node ≥21) are getter-only → redefine.
+      try { Object.defineProperty(global, k, { value: values[k], configurable: true, writable: true }); } catch { /* skip */ }
+    }
+  }
+  const savedAct = global.IS_REACT_ACT_ENVIRONMENT;
+  global.IS_REACT_ACT_ENVIRONMENT = false;
+  return () => {
+    for (const k of Object.keys(values)) {
+      try {
+        if (savedDesc[k]) Object.defineProperty(global, k, savedDesc[k]);
+        else if (saved[k] === undefined) delete global[k];
+        else global[k] = saved[k];
+      } catch { /* best effort */ }
+    }
+    global.IS_REACT_ACT_ENVIRONMENT = savedAct;
+    try { window.close(); } catch {}
+  };
+}
+
+// ── Public dispatch ──────────────────────────────────────────────────────────
+
+/**
+ * Verify component-local effect by rendering. `framework` selects the engine.
+ * `sources` are the project's source files (for storage-key detection, etc.).
+ */
+async function probeComponentEffect(appRoot, entry, opts = {}) {
+  const framework = (opts.framework || 'web').toLowerCase();
+  const kind = actionKind(entry);
+  const params = probeParams(entry, kind);
+  const storageKeys = detectStorageKeys(opts.sources);
+  const ctx = { fyodosDirRel: opts.fyodosDirRel || 'src/fyodos', framework, kind, params, storageKeys, sensitive: opts.sensitive || entry.requireConfirmation };
+
+  const withTimeout = (p) => Promise.race([
+    p,
+    new Promise((resolve) => setTimeout(() => resolve({ status: 'unverifiable', detail: 'el render de prueba excedió el tiempo límite (posible bucle/timer en el componente); efecto real no verificable automáticamente — probar a mano' }), opts.timeoutMs || 25000)),
+  ]);
+
+  if (framework.includes('react')) return withTimeout(probeReactEffect(appRoot, entry, ctx));
+  if (framework.includes('vue')) return withTimeout(require('./renderProbeVue').probeVueEffect(appRoot, entry, ctx));
+  if (framework.includes('angular')) {
+    return { status: 'unverifiable', detail: 'Angular: el render headless de componentes con TestBed no es fiable fuera de ng test; cableado aplicado y verificado por compilación, efecto real no verificable automáticamente aquí — probar con `ng test` o a mano' };
+  }
+  return { status: 'unverifiable', detail: `framework '${framework}' sin render-probe; efecto real no verificable automáticamente` };
+}
+
+module.exports = { probeComponentEffect, actionKind, decide, SENTINEL, SEED_ID, installDom, pickComponent, detectStorageKeys, probeParams, captureSnapshot, short, loadEsbuild, loadJsdom, reqFrom, emptyAssetsPlugin };