@fiodos/cli 0.1.32 → 0.1.34

package/package.json

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

@@ -102,7 +102,7 @@ const {
 const { wireReactNativeOrb, reportReactNativeWire, connectRnSession } = require('./wireReactNative');
 const {
   isShopifyThemeRoot, fetchStorefrontSnapshot, wireShopifyTheme, reportShopifyWire,
-  normalizeStoreDomain,
+  normalizeStoreDomain, enforceShopifyGuaranteedExecutions,
 } = require('./shopifyTheme');
 const { wireFlutterOrb, writeFlutterEnv, reportFlutterWire } = require('./wireFlutter');
 const { wireHandlers, reportHandlerResult } = require('./wireHandlers');
@@ -539,6 +539,18 @@ async function main() {
       `actions=${(proposed.actions || []).length} in ${(elapsedMs / 1000).toFixed(1)}s`);
     logDev(`[ai] tokens in=${usage.prompt_tokens} out=${usage.completion_tokens} cost=$${costUSD.toFixed(4)}`);
 
+    // ── 3b. Shopify platform guarantee (BEFORE verification) ────────────────
+    // The five universal commerce actions carry platform-constant execution
+    // templates; never trust the AI to have reproduced them. Enforcing them
+    // here means verification's structural check always passes for the
+    // guaranteed set and a Shopify manifest can never publish inert.
+    if (platform === 'shopify') {
+      const repairedIntents = enforceShopifyGuaranteedExecutions(proposed);
+      if (repairedIntents.length) {
+        logDev(`[shopify] canonical execution enforced on: ${repairedIntents.join(', ')}`);
+      }
+    }
+
     // ── 4. Mechanical verification of the AI's claims ───────────────────────
     // Actions are always verified against real code. Routes are verified only
     // when there is filesystem ground truth (mobile); for web they are kept as

package/src/shopifyTheme.js

@@ -35,6 +35,109 @@ const ORB_END = '<!-- FYODOS:ORB:END -->';
 /** Repo-relative folder of the synthetic storefront snapshot files. */
 const SNAPSHOT_DIR = '_fyodos/storefront';
 
+/**
+ * Canonical mechanics of the five guaranteed Shopify commerce actions.
+ *
+ * These execution templates are PLATFORM CONSTANTS (identical on every
+ * Shopify store), yet the analysis prompt asks the AI to reproduce them
+ * verbatim — and models sometimes omit or mangle the `execution` block. A
+ * manifest published without it is silently dead: the embed registers zero
+ * handlers and the orb promises cart actions it can never run (observed in
+ * production). `enforceShopifyGuaranteedExecutions` overwrites the MECHANICS
+ * (execution/parameters) of any action matching intent+handler while leaving
+ * the AI's personalized prose (labels, descriptions, examples) untouched.
+ * The backend applies the same guarantee at publish/serve time
+ * (backend/clients/shopify_guarantees.py) — keep both in sync.
+ */
+const SHOPIFY_GUARANTEED_ACTIONS = {
+  search_products: {
+    handler: 'shopifySearchProducts',
+    parameters: { query: { type: 'string', required: true } },
+    execution: {
+      kind: 'http',
+      method: 'GET',
+      url: '{baseUrl}/search/suggest.json?q={query}&resources[type]=product&resources[limit]=8',
+    },
+  },
+  get_product_details: {
+    handler: 'shopifyGetProductDetails',
+    parameters: { handle: { type: 'string', required: true } },
+    execution: { kind: 'http', method: 'GET', url: '{baseUrl}/products/{handle}.js' },
+  },
+  add_to_cart: {
+    handler: 'shopifyAddToCart',
+    parameters: {
+      variantId: { type: 'number', required: true },
+      quantity: { type: 'number', required: true },
+    },
+    execution: {
+      kind: 'http',
+      method: 'POST',
+      url: '{baseUrl}/cart/add.js',
+      headers: { 'Content-Type': 'application/json' },
+      body: { id: '{variantId}', quantity: '{quantity}' },
+    },
+  },
+  get_cart: {
+    handler: 'shopifyGetCart',
+    parameters: {},
+    execution: { kind: 'http', method: 'GET', url: '{baseUrl}/cart.js' },
+  },
+  // variantId-based on purpose (cart/change.js accepts a variant id as `id`):
+  // the theme snippet's cart screen context hands the agent variantIds, so
+  // the action contract must accept exactly what the agent can see.
+  update_cart_item: {
+    handler: 'shopifyUpdateCartItem',
+    parameters: {
+      variantId: { type: 'number', required: true },
+      quantity: { type: 'number', required: true },
+    },
+    execution: {
+      kind: 'http',
+      method: 'POST',
+      url: '{baseUrl}/cart/change.js',
+      headers: { 'Content-Type': 'application/json' },
+      body: { id: '{variantId}', quantity: '{quantity}' },
+    },
+  },
+};
+
+/**
+ * Enforce the canonical execution/parameters on every guaranteed commerce
+ * action of a Shopify manifest, in place. Prose fields are never touched;
+ * per-parameter descriptions written by the AI survive when the parameter
+ * survives. Returns the intents that were repaired (for logging).
+ */
+function enforceShopifyGuaranteedExecutions(manifest) {
+  const repaired = [];
+  if (!manifest || !Array.isArray(manifest.actions)) return repaired;
+  for (const action of manifest.actions) {
+    if (!action || typeof action !== 'object' || action.kind === 'link') continue;
+    const spec = SHOPIFY_GUARANTEED_ACTIONS[String(action.intent || '').trim()];
+    if (!spec || String(action.handler || '').trim() !== spec.handler) continue;
+
+    const params = {};
+    const prior = (action.parameters && typeof action.parameters === 'object') ? action.parameters : {};
+    for (const [name, shape] of Object.entries(spec.parameters)) {
+      params[name] = { ...shape };
+      const priorShape = prior[name];
+      if (priorShape && typeof priorShape.description === 'string') {
+        params[name].description = priorShape.description;
+      }
+    }
+
+    const already =
+      JSON.stringify(action.execution || null) === JSON.stringify(spec.execution) &&
+      JSON.stringify(Object.keys(prior).sort()) === JSON.stringify(Object.keys(spec.parameters).sort());
+    if (already) continue;
+
+    action.execution = JSON.parse(JSON.stringify(spec.execution));
+    action.parameters = params;
+    repaired.push(action.intent);
+  }
+  return repaired;
+}
+
 /** A Shopify theme repo is unmistakable: layout/theme.liquid is the layout
  *  every Online Store 2.0 theme must have, plus templates/ or sections/. */
 function isShopifyThemeRoot(appRoot) {
@@ -108,6 +211,10 @@ function universalSurfaceDoc(storeDomain) {
     universalRoutes: ['/', '/collections/all', '/search', '/cart'],
     universalActions: [
       { intent: 'search_products', handler: 'shopifySearchProducts', api: '{baseUrl}/search/suggest.json' },
+      // The search→cart bridge: suggest.json returns product ids/handles but
+      // NEVER variant ids, and cart/add.js only accepts variant ids. This
+      // endpoint (universal on every store) turns a handle into its variants.
+      { intent: 'get_product_details', handler: 'shopifyGetProductDetails', api: '{baseUrl}/products/{handle}.js' },
       { intent: 'add_to_cart', handler: 'shopifyAddToCart', api: '{baseUrl}/cart/add.js' },
       { intent: 'get_cart', handler: 'shopifyGetCart', api: '{baseUrl}/cart.js' },
       { intent: 'update_cart_item', handler: 'shopifyUpdateCartItem', api: '{baseUrl}/cart/change.js' },
@@ -354,6 +461,7 @@ function reportShopifyWire(result, colors = {}, { quiet = false } = {}) {
 }
 
 module.exports = {
+  enforceShopifyGuaranteedExecutions,
   isShopifyThemeRoot,
   readThemeMeta,
   fetchStorefrontSnapshot,

package/src/verify.js

@@ -298,6 +298,18 @@ function verifyManifest(manifest, evidence, sentFiles, staticRoutes, opts = {})
       });
       continue;
     }
+    // Shopify function action WITHOUT an execution block: nothing can ever run
+    // it (storefronts have no wireable code; the embed builds handlers ONLY
+    // from execution specs). Publishing it would make the orb promise an
+    // action that silently dies — drop it honestly. The guaranteed commerce
+    // set never lands here: its canonical execution is enforced pre-verify.
+    if (isShopify && action.kind !== 'link') {
+      provenance.actions.push({
+        intent: action.intent, included: false,
+        reason: 'shopify function action without a declarative execution block — nothing could ever run it — DROPPED',
+      });
+      continue;
+    }
     if (isShopify && action.kind === 'link' && String(action.navTarget || '').trim() === '/checkout') {
       action.handler = '';
       actions.push(action);

package/src/wireHandlers.js

@@ -445,6 +445,41 @@ function relImport(fromDirRel, toFileRel) {
   return rel;
 }
 
+/**
+ * PARAMETER CONTRACT check shared by both wiring strategies: every
+ * `<receiver>.<name>` / `<receiver>['<name>']` the expression reads must be a
+ * parameter the manifest declares for this action. The executor builds that
+ * object exclusively from the manifest parameters, so any other name is
+ * ALWAYS undefined at runtime — the action then "succeeds" while silently
+ * doing the wrong thing (e.g. an invoke reading `args.voiceMode` when the
+ * manifest declares 'mode': every call fell back to a default value). It
+ * compiles clean, so only this check can catch it.
+ */
+function checkParamContract(expr, receiver, manifestParams) {
+  const declared = new Set((manifestParams || []).map((p) => p.name));
+  const refs = new Set();
+  let m;
+  const dotRe = new RegExp(`\\b${receiver}\\.([A-Za-z_$][\\w$]*)`, 'g');
+  while ((m = dotRe.exec(expr))) refs.add(m[1]);
+  const bracketRe = new RegExp(`\\b${receiver}\\[\\s*['"]([^'"]+)['"]\\s*\\]`, 'g');
+  while ((m = bracketRe.exec(expr))) refs.add(m[1]);
+  for (const ref of refs) {
+    if (!declared.has(ref)) {
+      const hint = declared.size
+        ? `the manifest declares: ${[...declared].map((n) => `'${n}'`).join(', ')}`
+        : 'the manifest declares NO parameters for this action';
+      return {
+        ok: false,
+        reason:
+          `the wiring reads '${receiver}.${ref}', but ${hint} — '${receiver}' only ever carries the ` +
+          'declared manifest parameters, so that value would always be undefined at runtime. ' +
+          'Use the declared parameter name(s) exactly.',
+      };
+    }
+  }
+  return { ok: true };
+}
+
 /**
  * Turn the AI's proposed wiring for ONE action into a verified `auto` entry, or
  * return { reason } when the proposal cannot be safely trusted. This is the
@@ -518,6 +553,14 @@ function buildAiEntry({ appRoot, fyodosDirRel, base, aiW, manifestParams }) {
     };
   }
 
+  // 5) PARAMETER CONTRACT (same guarantee as the bridge strategy): every
+  //    `params.<name>` / `params['<name>']` the call reads must be a parameter
+  //    the manifest declares for this action — anything else is ALWAYS
+  //    undefined at runtime and produces a silent wrong-value execution that
+  //    compiles clean and "succeeds".
+  const paramContract = checkParamContract(call, 'params', manifestParams);
+  if (!paramContract.ok) return { reason: paramContract.reason };
+
   return {
     ...base,
     confidence: 'auto',
@@ -703,6 +746,11 @@ function buildAiBridgeEntry({ appRoot, fyodosDirRel, base, aiW }) {
     };
   }
 
+  // PARAMETER CONTRACT: every `args.<name>` the invoke reads must be a
+  // parameter the manifest declares for THIS action (see checkParamContract).
+  const paramContract = checkParamContract(invoke, 'args', base.manifestParams);
+  if (!paramContract.ok) return { reason: paramContract.reason };
+
   // Verify extra imports the invoke needs.
   const imports = [];
   const importedNames = new Set();
@@ -1345,6 +1393,44 @@ function stripFiodosBlocks(content) {
   );
 }
 
+/**
+ * Sweep GENERATED bridge blocks left behind in files this run does NOT wire.
+ *
+ * applyComponentEdits strips old blocks only in the files it edits THIS run,
+ * so when a re-analysis moves an action's wiring to a different component the
+ * previous component keeps a stale registerFiodosBridge() block: a duplicate
+ * registration for the same key whose argument contract may no longer match —
+ * whichever component mounts last silently wins (the select_voice_mode
+ * production bug: two components registered the key, one reading args.mode
+ * and the other args.voiceMode, and the action "ran" without doing anything).
+ *
+ * Only blocks carrying the generated header are removed; developer-authored
+ * FYODOS:BRIDGE blocks are preserved verbatim (same rule as
+ * stripFiodosBlocks). Returns backups compatible with revertAll so a combined
+ * build regression restores the swept files too.
+ */
+function sweepStaleGeneratedBlocks(appRoot, files, editedFiles) {
+  const edited = new Set((editedFiles || []).map((f) => normRel(f)));
+  const backups = [];
+  for (const f of files || []) {
+    const rel = normRel(f && f.rel);
+    if (!rel || edited.has(rel)) continue;
+    const abs = path.join(appRoot, rel);
+    let original;
+    try {
+      original = fs.readFileSync(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    if (!original.includes(EDIT_START_PREFIX)) continue;
+    const swept = stripFiodosBlocks(original);
+    if (swept === original) continue;
+    backups.push({ file: rel, abs, original });
+    fs.writeFileSync(abs, swept);
+  }
+  return backups;
+}
+
 /** Insert an import block right after the file's last top-level import statement.
  *  Matches the WHOLE statement through its module string — a per-line regex put
  *  the block INSIDE multi-line imports (`import {\n  a,\n} from 'x';`), corrupting
@@ -1926,6 +2012,7 @@ async function wireHandlers(appRoot, opts = {}) {
       }
       fs.writeFileSync(registryAbs, buildRegistryModule(finalPlan, { ts, esm }));
       ({ backups } = applyComponentEdits(appRoot, finalEdits));
+      backups.push(...sweepStaleGeneratedBlocks(appRoot, files, finalEdits.map((e) => e.file)));
     } catch (err) {
       revertAll(backups, generatedFiles);
       return { status: 'failed', docPath: docAbs, error: err, plan: finalPlan, verification: loop.attemptsLog };
@@ -1972,6 +2059,9 @@ async function wireHandlers(appRoot, opts = {}) {
           }
           fs.writeFileSync(registryAbs, buildRegistryModule(survivorPlan, { ts, esm }));
           ({ backups: survivorBackups } = applyComponentEdits(appRoot, survivorEdits));
+          survivorBackups.push(
+            ...sweepStaleGeneratedBlocks(appRoot, files, survivorEdits.map((e) => e.file)),
+          );
         } catch (err) {
           revertAll(survivorBackups, survivorGenerated);
           return { status: 'failed', docPath: docAbs, error: err, plan: finalPlan, verification: loop.attemptsLog };
@@ -2041,6 +2131,7 @@ async function wireHandlers(appRoot, opts = {}) {
       throw new Error('post-write verification failed');
     }
     ({ backups } = applyComponentEdits(appRoot, componentEdits));
+    backups.push(...sweepStaleGeneratedBlocks(appRoot, files, componentEdits.map((e) => e.file)));
   } catch (err) {
     revertAll(backups, generatedFiles);
     return { status: 'failed', docPath: docAbs, error: err, plan };
@@ -2138,6 +2229,8 @@ module.exports = {
   planComponentEdits,
   applyComponentEdits,
   stripFiodosBlocks,
+  sweepStaleGeneratedBlocks,
+  checkParamContract,
   revertAll,
   runAutoCorrectionLoop,
   writeIsolated,