@fiodos/cli 0.1.26 → 0.1.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiodos/cli",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "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": {

package/src/index.js

@@ -175,6 +175,11 @@ function logUser(line) {
   console.log(`${cyan}◉${reset} ${blue}Fiodos${reset} · ${line}`);
 }
 
+/** Human-readable pointer to the per-run change registry written in the repo. */
+function changeLogUserMessage(paths) {
+  return `We saved a summary of every file we changed — see ${paths.mdRel} (past runs in .fyodos/changes/)`;
+}
+
 /**
  * Ask the developer to confirm before the analysis runs. `yes` continues; any
  * other answer (or `no`) cancels instantly — the command ends without analyzing.
@@ -925,7 +930,7 @@ async function main() {
           envResult: envWriteResult,
         });
         const paths = writeChangeRegistry(analysisRoot, record);
-        logUser(`Change log: ${paths.mdRel} (history in .fyodos/changes/)`);
+        logUser(changeLogUserMessage(paths));
       } catch (e) {
         logDev(`[change-registry] could not write: ${e.message}`);
       }
@@ -973,7 +978,36 @@ async function main() {
     });
     logUser('Published to your project');
     if (orbWireResult && (orbWireResult.status === 'added' || orbWireResult.status === 'already')) {
-      logUser('Commit & push this theme repo — Shopify\u2019s GitHub sync deploys the orb to your live store.');
+      logUser('Commit & push this theme repo.');
+      // Shopify's GitHub sync only auto-updates the storefront when the
+      // CONNECTED theme is already the LIVE one. A brand-new theme connected
+      // from GitHub stays a draft until published ONCE by hand — every push
+      // after that keeps it live automatically. Without this line the orb can
+      // be fully wired and pushed and still never appear to real customers,
+      // with nothing in the CLI output explaining why.
+      logUser(
+        'If this is already your LIVE theme, that push alone puts the orb on your store. ' +
+        'If it\u2019s still a DRAFT (check the Shopify admin theme badge), publish it ONCE — ' +
+        'Online Store \u2192 Themes \u2192 \u22ef \u2192 Publish \u2014 then every future push stays live automatically.',
+      );
+      // New/trial Shopify stores are password-protected by default, and a
+      // password-protected storefront renders layout/password.liquid INSTEAD
+      // of layout/theme.liquid on every page — so without also wiring that
+      // layout (done above when the theme has one) the orb would be
+      // correctly installed and published yet invisible behind the password
+      // gate. Surfacing this explicitly since it is the #1 "installed
+      // correctly but nothing shows up" report on a fresh store.
+      if (orbWireResult.password) {
+        logUser(
+          orbWireResult.password.status === 'failed'
+            ? `Heads up: your store looks password-protected but the orb could not be added to ${orbWireResult.password.file} (${orbWireResult.password.reason}) — it will be invisible until you remove the password or fix that layout.`
+            : 'Your theme has a password page (layout/password.liquid) — the orb is embedded there too, so it still shows up while your store is password-protected.',
+        );
+      } else {
+        logUser(
+          'Heads up: if your store is still password-protected (common on new/trial stores) and your theme has NO separate layout/password.liquid, the orb won\u2019t show on the password page — remove the password (Online Store \u2192 Preferences) to test, or check under a real domain/plan.',
+        );
+      }
     }
 
     if (!noWire) {
@@ -985,7 +1019,7 @@ async function main() {
           orbResult: orbWireResult,
         });
         const paths = writeChangeRegistry(analysisRoot, record);
-        logUser(`Change log: ${paths.mdRel} (history in .fyodos/changes/)`);
+        logUser(changeLogUserMessage(paths));
       } catch (e) {
         logDev(`[change-registry] could not write: ${e.message}`);
       }
@@ -1108,7 +1142,7 @@ async function main() {
           envResult: envWriteResult,
         });
         const paths = writeChangeRegistry(analysisRoot, record);
-        logUser(`Change log: ${paths.mdRel} (history in .fyodos/changes/)`);
+        logUser(changeLogUserMessage(paths));
       } catch (e) {
         logDev(`[change-registry] could not write: ${e.message}`);
       }
@@ -1187,7 +1221,7 @@ async function main() {
           envResult: envWriteResult,
         });
         const paths = writeChangeRegistry(analysisRoot, record);
-        logUser(`Change log: ${paths.mdRel} (history in .fyodos/changes/)`);
+        logUser(changeLogUserMessage(paths));
       } catch (e) {
         logDev(`[change-registry] could not write: ${e.message}`);
       }

package/src/postWireTest.js

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

package/src/shopifyTheme.js

@@ -240,19 +240,16 @@ function escapeRe(s) {
 }
 
 /**
- * Inject (or refresh) the snippet in layout/theme.liquid, right before
+ * Inject (or refresh) the snippet into ONE liquid layout file, right before
  * </body>. Idempotent via the FYODOS:ORB markers: an existing block is
  * replaced in place, so re-running the CLI updates the snippet instead of
- * duplicating it. Returns { status: 'added'|'already'|'skipped'|'failed',
- * file, reason? }.
+ * duplicating it. Returns { status: 'added'|'already'|'skipped'|'failed'|
+ * 'not-found', file, reason?, refreshed? }.
  */
-function wireShopifyTheme(appRoot, { apiKey, apiUrl, noWire = false } = {}) {
-  const relFile = path.join('layout', 'theme.liquid');
-  const file = path.join(appRoot, relFile);
+function injectSnippetInLayout(file, relFile, snippet, { noWire = false } = {}) {
   if (!fs.existsSync(file)) {
-    return { status: 'failed', file: relFile, reason: 'layout/theme.liquid not found' };
+    return { status: 'not-found', file: relFile };
   }
-  const snippet = buildShopifySnippet({ apiKey, apiUrl });
   const source = fs.readFileSync(file, 'utf8');
 
   const markerRe = new RegExp(`${escapeRe(ORB_START)}[\\s\\S]*?${escapeRe(ORB_END)}`);
@@ -273,6 +270,41 @@ function wireShopifyTheme(appRoot, { apiKey, apiUrl, noWire = false } = {}) {
   return { status: 'added', file: relFile };
 }
 
+/**
+ * Wire the theme's layout(s). layout/theme.liquid is the one every storefront
+ * page uses and is REQUIRED. layout/password.liquid — when the theme ships
+ * one (Dawn, Horizon and most modern themes do) — is a SEPARATE layout Shopify
+ * renders INSTEAD of theme.liquid on every page while the store has password
+ * protection active (the default on every new/trial store, and very common on
+ * dev stores used to test an install). Without wiring it too, the orb is
+ * correctly embedded and published yet invisible to anyone hitting the
+ * password gate — "installed correctly but nothing shows up". Best-effort:
+ * its absence is normal (older/simpler themes have none) and never fails the
+ * install.
+ *
+ * Returns { status, file, reason?, refreshed?, password: {status, file,...} }
+ * — `password` mirrors the same shape for layout/password.liquid, or null
+ * when that file does not exist in this theme.
+ */
+function wireShopifyTheme(appRoot, { apiKey, apiUrl, noWire = false } = {}) {
+  const snippet = buildShopifySnippet({ apiKey, apiUrl });
+
+  const themeRelFile = path.join('layout', 'theme.liquid');
+  const themeFile = path.join(appRoot, themeRelFile);
+  if (!fs.existsSync(themeFile)) {
+    return { status: 'failed', file: themeRelFile, reason: 'layout/theme.liquid not found', password: null };
+  }
+  const themeResult = injectSnippetInLayout(themeFile, themeRelFile, snippet, { noWire });
+
+  const passwordRelFile = path.join('layout', 'password.liquid');
+  const passwordFile = path.join(appRoot, passwordRelFile);
+  const passwordResult = fs.existsSync(passwordFile)
+    ? injectSnippetInLayout(passwordFile, passwordRelFile, snippet, { noWire })
+    : null;
+
+  return { ...themeResult, password: passwordResult };
+}
+
 function reportShopifyWire(result, colors = {}, { quiet = false } = {}) {
   const { blue = '', cyan = '', reset = '' } = colors;
   const say = (line) => console.error(`${cyan}◉${reset} ${blue}Fiodos${reset} · ${line}`);
@@ -285,6 +317,13 @@ function reportShopifyWire(result, colors = {}, { quiet = false } = {}) {
   } else if (!quiet) {
     say(`orb embed skipped (${result.reason || result.status})`);
   }
+
+  const pw = result.password;
+  if (pw && (pw.status === 'added' || pw.status === 'already')) {
+    say(`orb also embedded in ${pw.file} — keeps working while your store is password-protected`);
+  } else if (pw && pw.status === 'failed') {
+    say(`could not embed the orb in ${pw.file}: ${pw.reason} — the orb won't show while your store is password-protected`);
+  }
 }
 
 module.exports = {

package/src/verifyWire.js

@@ -52,8 +52,16 @@ function normErr(line) {
  * really broken), as opposed to a style violation? These mean the safety net
  * MUST act: the action does not actually work.
  */
+// "Declared but never used" (TS6133/6192/6196/6198/6199/6205) is a STRICTNESS
+// gate (noUnusedLocals), never broken code. It also appears as an ARTIFACT of
+// per-action isolated verification: wiring one bridge action alone leaves the
+// sibling symbols of the same destructuring temporarily unused, which used to
+// fail every action in that file (the navigate_section/logout production bug).
+const UNUSED_CODE_TS_RE = /error\s+TS6(?:133|192|196|198|199|205)\b/i;
+
 function isRealCompileError(line) {
   const l = String(line);
+  if (UNUSED_CODE_TS_RE.test(l)) return false;
   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);
 }
 
@@ -66,6 +74,8 @@ function isRealCompileError(line) {
 function isLintError(line) {
   const l = String(line);
   if (isRealCompileError(l)) return false;
+  // Unused-symbol strictness (see UNUSED_CODE_TS_RE) is style, not brokenness.
+  if (UNUSED_CODE_TS_RE.test(l)) return true;
   // 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.

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.
@@ -554,9 +616,15 @@ function buildAiBridgeEntry({ appRoot, fyodosDirRel, base, aiW }) {
   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}'` };
+  // 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
@@ -604,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);
@@ -1195,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. */
@@ -1414,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] };
 }
 
 /**