@fiodos/cli 0.1.25 → 0.1.28

package/src/wireHandlers.js

@@ -98,6 +98,66 @@ function readFileSafe(appRoot, fileRel) {
   }
 }
 
+const SOURCE_EXTS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.vue', '.svelte'];
+
+/** Read tsconfig/jsconfig path aliases once per appRoot: [{ prefix, target }]. */
+const aliasCache = new Map();
+function readPathAliases(appRoot) {
+  if (aliasCache.has(appRoot)) return aliasCache.get(appRoot);
+  const aliases = [];
+  for (const cfgName of ['tsconfig.json', 'tsconfig.app.json', 'jsconfig.json']) {
+    try {
+      const raw = fs.readFileSync(path.join(appRoot, cfgName), 'utf8');
+      // Tolerant parse: strip comments and trailing commas (tsconfig is JSONC).
+      const cfg = JSON.parse(raw.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, '').replace(/,\s*([}\]])/g, '$1'));
+      const co = cfg.compilerOptions || {};
+      const baseUrl = co.baseUrl || '.';
+      for (const [key, targets] of Object.entries(co.paths || {})) {
+        const target = Array.isArray(targets) ? targets[0] : targets;
+        if (!target) continue;
+        aliases.push({
+          prefix: key.replace(/\*$/, ''),
+          target: normRel(path.join(baseUrl, String(target).replace(/\*$/, ''))),
+        });
+      }
+    } catch {
+      /* no config or unparsable — skip */
+    }
+  }
+  aliasCache.set(appRoot, aliases);
+  return aliases;
+}
+
+/**
+ * Resolve an AI-proposed import path to a REAL file, tolerating what a human
+ * would write: tsconfig path aliases ('@/context/AppProvider') and
+ * extensionless specifiers. Returns the resolved app-relative path (with
+ * extension) or null. Rejecting these outright un-wired real actions whose
+ * only "fault" was that the AI wrote the import the way the codebase does.
+ */
+function resolveSourceFile(appRoot, fromRel) {
+  const candidates = [normRel(fromRel)];
+  for (const { prefix, target } of readPathAliases(appRoot)) {
+    const f = candidates[0];
+    if (f === prefix.replace(/\/$/, '') || f.startsWith(prefix)) {
+      candidates.push(normRel(target + f.slice(prefix.length)));
+    }
+  }
+  for (const rel of candidates) {
+    const abs = path.join(appRoot, rel);
+    if (fs.existsSync(abs) && fs.statSync(abs).isFile()) return rel;
+    for (const ext of SOURCE_EXTS) {
+      if (fs.existsSync(`${abs}${ext}`)) return `${rel}${ext}`;
+    }
+    if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
+      for (const ext of SOURCE_EXTS) {
+        if (fs.existsSync(path.join(abs, `index${ext}`))) return normRel(path.join(rel, `index${ext}`));
+      }
+    }
+  }
+  return null;
+}
+
 /** Count non-overlapping occurrences of a literal substring. */
 function countOccurrences(haystack, needle) {
   if (!needle) return 0;
@@ -112,14 +172,15 @@ function countOccurrences(haystack, needle) {
 
 // ── Mechanical verification (the safety net for AI-proposed wiring) ─────────────
 
-/** True if `symbol` appears as a standalone identifier somewhere in the file. */
+/** True if `symbol` appears as a standalone identifier somewhere in the file.
+ * The file path tolerates aliases/extensionless specifiers (resolveSourceFile). */
 function fileHasSymbol(appRoot, fileRel, symbol) {
   if (!fileRel || !symbol) return false;
-  const abs = path.join(appRoot, normRel(fileRel));
-  if (!fs.existsSync(abs)) return false;
+  const resolved = resolveSourceFile(appRoot, fileRel);
+  if (!resolved) return false;
   let content;
   try {
-    content = fs.readFileSync(abs, 'utf8');
+    content = fs.readFileSync(path.join(appRoot, resolved), 'utf8');
   } catch {
     return false;
   }
@@ -419,11 +480,12 @@ function buildAiEntry({ appRoot, fyodosDirRel, base, aiW, manifestParams }) {
   const importedNames = new Set();
   for (const imp of rawImports) {
     const name = String((imp && imp.name) || '').trim();
-    const from = normRel(imp && imp.from);
+    const rawFrom = normRel(imp && imp.from);
     const kind = (imp && imp.kind) || 'named';
-    if (!name || !from) return { reason: 'an import proposed by the AI is incomplete (missing name/from)' };
-    if (!fs.existsSync(path.join(appRoot, from))) {
-      return { reason: `the proposed import points to a non-existent file: '${from}'` };
+    if (!name || !rawFrom) return { reason: 'an import proposed by the AI is incomplete (missing name/from)' };
+    const from = resolveSourceFile(appRoot, rawFrom);
+    if (!from) {
+      return { reason: `the proposed import points to a non-existent file: '${rawFrom}'` };
     }
     // For named imports the symbol must be present in that file; default/namespace
     // bind the module's default/whole export so only file existence is checked.
@@ -467,13 +529,79 @@ function buildAiEntry({ appRoot, fyodosDirRel, base, aiW, manifestParams }) {
   };
 }
 
+/**
+ * MECHANICAL ANCHOR RESCUE — the fix for the dominant wiring failure class
+ * ("the insertion point in '<file>' is ambiguous / not found").
+ *
+ * The AI's anchor only needs to locate the RIGHT COMPONENT SCOPE: the actual
+ * insertion goes before the nearest JSX `return` (see insertRegisterBlock), so
+ * when the AI picks a line that appears several times in a big file we do not
+ * have to give up. We derive a deterministic anchor ourselves: the line where
+ * one of the identifiers the `invoke` expression CALLS/READS is DECLARED
+ * (`const [x, setX] = useState(...)`, `function foo(`, `const foo =`, a class
+ * field, …). Declarations are unique per scope in real code, and anchoring on
+ * the declaration guarantees the registration lands in the scope where the
+ * symbol is visible. Correctness is still gated by the same compile-regression
+ * + effect-probe verification as every other wiring — this only replaces the
+ * "reject" with a better, mechanical candidate.
+ */
+function deriveBridgeAnchor(content, invoke) {
+  const src = stripLiterals(String(invoke || ''));
+  // Identifiers the invoke CALLS first (most specific), then everything it reads.
+  const ordered = [];
+  const pushId = (id) => {
+    if (!id || id === 'args' || id === 'this') return;
+    if (JS_KEYWORDS.has(id) || SAFE_GLOBALS.has(id)) return;
+    if (!ordered.includes(id)) ordered.push(id);
+  };
+  let m;
+  const callRe = /(?:^|[^.\w$])([A-Za-z_$][\w$]*)\s*\(/g;
+  while ((m = callRe.exec(src))) pushId(m[1]);
+  for (const id of freeIdentifiers(invoke)) pushId(id);
+
+  for (const id of ordered) {
+    // Full LINES that look like a declaration of `id` in the file.
+    const lineRe = new RegExp(
+      `^[ \\t]*(?:export\\s+)?(?:const|let|var|function|async\\s+function|private|public|protected|readonly)\\b[^\\n]*(?:^|[^.\\w$])${esc(id)}(?![\\w$])[^\\n]*$`,
+      'gm',
+    );
+    const decls = [];
+    while ((m = lineRe.exec(content))) decls.push(m[0]);
+    // Exactly ONE declaration line, and that line must be unique as a substring
+    // (so indexOf-based insertion is deterministic and idempotent).
+    if (decls.length === 1 && countOccurrences(content, decls[0]) === 1) {
+      return decls[0];
+    }
+  }
+  return null;
+}
+
+/**
+ * True when an anchor that appears several times is HARMLESS: every occurrence
+ * resolves to the same actual insertion point (the nearest JSX `return`), so
+ * the ambiguity cannot change where the registration lands.
+ */
+function ambiguousAnchorSameInsertion(content, anchor) {
+  const points = new Set();
+  let idx = content.indexOf(anchor);
+  while (idx !== -1) {
+    points.add(nearestJsxReturn(content, idx));
+    if (points.size > 1) return false;
+    idx = content.indexOf(anchor, idx + anchor.length);
+  }
+  // A single resolved point that exists (-1 = no JSX return found → not safe).
+  return points.size === 1 && !points.has(-1);
+}
+
 /**
  * Verify the AI's BRIDGE proposal for ONE action. A bridge edits the user's own
  * component (under consent) to register the live, in-scope function/instance so
  * the standalone registry can reach component-local state. The verifier confirms
  * the edit can be applied SAFELY and that nothing is fabricated:
- *   · the component file exists and the anchor line is present EXACTLY once
- *     (so the insertion point is unambiguous and idempotent),
+ *   · the component file exists and the anchor resolves to ONE unambiguous
+ *     insertion point — when the AI's anchor is missing/ambiguous, a mechanical
+ *     anchor is derived from the declaration of the invoked symbol (see
+ *     deriveBridgeAnchor) instead of giving up,
  *   · every requiredSymbol exists in the code,
  *   · `invoke` does not create a detached `new Service()` instance,
  *   · every identifier `invoke` reads is `args`/`this`, a safe global, an import
@@ -483,19 +611,43 @@ function buildAiEntry({ appRoot, fyodosDirRel, base, aiW, manifestParams }) {
 function buildAiBridgeEntry({ appRoot, fyodosDirRel, base, aiW }) {
   const b = aiW.bridge || {};
   const file = normRel(b.file);
-  const anchor = String(b.anchor || '').trim();
+  let anchor = String(b.anchor || '').trim();
   const invoke = String(b.invoke || '').trim();
   const why = aiW.bridgeReason ? ` (${aiW.bridgeReason})` : '';
 
   if (!file) return { reason: `the AI marked a bridge but did not indicate the component file${why}` };
-  const content = readFileSafe(appRoot, file);
-  if (content == null) return { reason: `could not read the component '${file}' to apply the bridge` };
+  const rawContent = readFileSafe(appRoot, file);
+  if (rawContent == null) return { reason: `could not read the component '${file}' to apply the bridge` };
   if (!invoke) return { reason: `the AI did not provide the bridge 'invoke' expression for '${file}'` };
-  if (!anchor) return { reason: `the AI did not provide an insertion anchor in '${file}'` };
-
-  const occ = countOccurrences(content, anchor);
-  if (occ === 0) return { reason: `no safe insertion point was found in '${file}' — wire this action manually` };
-  if (occ > 1) return { reason: `the insertion point in '${file}' is ambiguous — wire this action manually` };
+  // Anchor decisions must be made on the content the block will ACTUALLY be
+  // inserted into: applyComponentEdits strips our previous blocks first. On a
+  // re-run over an already-wired file, the old generated block contains the
+  // same invoke expressions, so counting occurrences on the raw file falsely
+  // flags unique anchors as "ambiguous" and un-wires working actions.
+  const content = stripFiodosBlocks(rawContent);
+
+  // Anchor resolution ladder: exact-unique AI anchor → harmless-ambiguous AI
+  // anchor → mechanically derived declaration anchor → review. The old behavior
+  // (reject on 0/>1 occurrences) left real, wireable actions "manual" whenever
+  // the AI picked a repeated line in a big file.
+  let anchorDerived = false;
+  const occ = anchor ? countOccurrences(content, anchor) : 0;
+  if (occ !== 1) {
+    const scope = b.scope === 'class-field' ? 'class-field' : 'statement';
+    if (occ > 1 && scope === 'statement' && ambiguousAnchorSameInsertion(content, anchor)) {
+      // Keep the AI anchor: every occurrence lands on the same insertion point.
+    } else {
+      const derived = deriveBridgeAnchor(content, invoke);
+      if (derived) {
+        anchor = derived;
+        anchorDerived = true;
+      } else if (!anchor || occ === 0) {
+        return { reason: `no safe insertion point was found in '${file}' — wire this action manually` };
+      } else {
+        return { reason: `the insertion point in '${file}' is ambiguous — wire this action manually` };
+      }
+    }
+  }
 
   // requiredSymbols must really exist.
   const required = Array.isArray(aiW.requiredSymbols) ? aiW.requiredSymbols : [];
@@ -520,10 +672,11 @@ function buildAiBridgeEntry({ appRoot, fyodosDirRel, base, aiW }) {
   const importedNames = new Set();
   for (const imp of Array.isArray(b.imports) ? b.imports : []) {
     const name = String((imp && imp.name) || '').trim();
-    const from = normRel(imp && imp.from);
+    const rawFrom = normRel(imp && imp.from);
     const kind = (imp && imp.kind) || 'named';
-    if (!name || !from) return { reason: 'a bridge import is incomplete (missing name/from)' };
-    if (!fs.existsSync(path.join(appRoot, from))) return { reason: `the bridge import points to a non-existent file: '${from}'` };
+    if (!name || !rawFrom) return { reason: 'a bridge import is incomplete (missing name/from)' };
+    const from = resolveSourceFile(appRoot, rawFrom);
+    if (!from) return { reason: `the bridge import points to a non-existent file: '${rawFrom}'` };
     if (kind === 'named' && !fileHasSymbol(appRoot, from, name)) return { reason: `named import '${name}' does not exist in '${from}'` };
     imports.push({ kind, name, importPath: relImport(path.dirname(file), from) });
     importedNames.add(name);
@@ -1111,10 +1264,31 @@ function buildHandlerDoc(plan, ctx = {}) {
 
 // ── Editing the user's own files (idempotent + reversible) ─────────────────────
 
-/** Remove any previously-inserted Fiodos blocks (idempotence across re-runs). */
+/**
+ * Header phrasings the CLI itself has ever written (current English + the
+ * localized parenthetical of older versions). Only blocks carrying one of
+ * these are OURS to strip.
+ */
+const GENERATED_HEADER_RE = /(generated by|auto-generado por|generado por)\s+Fiodos/i;
+
+/**
+ * Remove previously-inserted Fiodos blocks (idempotence across re-runs) —
+ * but ONLY the blocks this CLI generated. A developer can hand-write their
+ * own `FYODOS:BRIDGE` block (e.g. "manual wiring — logout") following our
+ * docs; that block is THEIR code and often the only user of an import
+ * (`useEffect`, a hook…). Stripping it orphans the import, the strict
+ * TypeScript check (noUnusedLocals) fails the candidate, and the whole
+ * wiring reverts — the exact failure that left navigate_section/logout
+ * unwired in production. Developer blocks are preserved verbatim.
+ */
 function stripFiodosBlocks(content) {
-  const re = new RegExp(`\\n?${esc(EDIT_START_PREFIX)}[^\\n]*[\\s\\S]*?${esc(EDIT_END)}\\n?`, 'g');
-  return content.replace(re, '\n');
+  const re = new RegExp(
+    `\\n?(${esc(EDIT_START_PREFIX)}[^\\n]*)[\\s\\S]*?${esc(EDIT_END)}\\n?`,
+    'g',
+  );
+  return content.replace(re, (block, headerLine) =>
+    GENERATED_HEADER_RE.test(headerLine) ? '\n' : block,
+  );
 }
 
 /** Insert an import block right after the file's last top-level import line. */
@@ -1330,20 +1504,32 @@ function pickRelevantFiles(files, evidence, candidate, intent) {
   return picked.length ? picked : files.slice(0, 4);
 }
 
-/** Write ONLY one entry (registry + bridge + its edit) for isolated verification. */
+/**
+ * Write ONLY one entry (registry + bridge + its edit) for isolated verification.
+ * Registry/bridge files from a PREVIOUS install are snapshotted and restored on
+ * revert instead of deleted: deleting them would break every OTHER file that
+ * still imports `../fyodos/bridge` from an earlier run, making all later
+ * verifications fail with a phantom "Cannot find module" (TS2307).
+ */
 function writeIsolated({ appRoot, fyodosDirAbs, entry, ts, esm, ext }) {
   const onePlan = { auto: [entry], review: [], manual: [], entries: [entry] };
   const registryAbs = path.join(fyodosDirAbs, `${REGISTRY_BASENAME}${ext}`);
   const bridgeAbs = path.join(fyodosDirAbs, `${BRIDGE_BASENAME}${ext}`);
-  const generated = [registryAbs];
+  const priorBackups = [];
+  const generated = [];
+  const snapshotOrCreate = (abs) => {
+    if (fs.existsSync(abs)) priorBackups.push({ file: abs, abs, original: fs.readFileSync(abs, 'utf8') });
+    else generated.push(abs);
+  };
+  snapshotOrCreate(registryAbs);
   if (entry.kind === 'bridge') {
+    snapshotOrCreate(bridgeAbs);
     fs.writeFileSync(bridgeAbs, buildBridgeModule({ ts, esm }));
-    generated.push(bridgeAbs);
   }
   fs.writeFileSync(registryAbs, buildRegistryModule(onePlan, { ts, esm }));
   const edits = planComponentEdits(appRoot, onePlan, { ts });
   const { backups } = applyComponentEdits(appRoot, edits);
-  return { backups, generated, touched: [...edits.map((e) => e.file), registryAbs, bridgeAbs] };
+  return { backups: [...backups, ...priorBackups], generated, touched: [...edits.map((e) => e.file), registryAbs, bridgeAbs] };
 }
 
 /**
@@ -1854,6 +2040,8 @@ module.exports = {
   findExportedFunction,
   findStoreMethod,
   mapParams,
+  deriveBridgeAnchor,
+  ambiguousAnchorSameInsertion,
   // shared with wireSession (same verification + injection machinery)
   fileHasSymbol,
   freeIdentifiers,