@deneb-ui/cli 2.0.66 → 2.0.68

package/bin/index.js

@@ -3,6 +3,83 @@
 const path = require('node:path');
 const fs = require('node:fs');
 const { spawnSync } = require('node:child_process');
+const readline = require('node:readline');
+const crypto = require('node:crypto');
+
+// SHA-256 hash of default key ("lvuchami") — prevents plain text exposure in repository
+const DENEB_AI_DEFAULT_KEY_HASH = '6f791210e05b535d0e48e260273b3ddb511aefb63ad2a2a35b838a80a6127588';
+
+/**
+ * Validates AI access key against either:
+ * 1. Environment variable DENEB_AI_KEY (configurable by team / CI)
+ * 2. Cryptographic SHA-256 hash of default key
+ * @param {string} inputKey
+ * @returns {boolean}
+ */
+function verifyAiAccessKey(inputKey) {
+  if (!inputKey || typeof inputKey !== 'string') return false;
+  const clean = inputKey.trim();
+  if (process.env.DENEB_AI_KEY && clean === process.env.DENEB_AI_KEY.trim()) {
+    return true;
+  }
+  const hash = crypto.createHash('sha256').update(clean).digest('hex');
+  return hash === DENEB_AI_DEFAULT_KEY_HASH;
+}
+
+/**
+ * Prompt the user with a question and return their answer.
+ * @param {string} query - The question to display
+ * @returns {Promise<string>}
+ */
+function askQuestion(query) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(query, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * Prompt the user for a password with masked input (shows * for each character).
+ * @param {string} query - The prompt to display
+ * @returns {Promise<string>}
+ */
+function askPassword(query) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    process.stdout.write(query);
+    const stdin = process.stdin;
+    const wasRaw = stdin.isRaw;
+    if (stdin.isTTY) stdin.setRawMode(true);
+    let pwd = '';
+    const onData = (ch) => {
+      const c = ch.toString();
+      if (c === '\n' || c === '\r') {
+        if (stdin.isTTY) stdin.setRawMode(wasRaw || false);
+        stdin.removeListener('data', onData);
+        process.stdout.write('\n');
+        rl.close();
+        resolve(pwd);
+      } else if (c === '\x7f' || c === '\b') {
+        if (pwd.length > 0) {
+          pwd = pwd.slice(0, -1);
+          process.stdout.write('\r' + query + '*'.repeat(pwd.length) + ' \b');
+        }
+      } else if (c === '\x03') {
+        if (stdin.isTTY) stdin.setRawMode(wasRaw || false);
+        rl.close();
+        process.exit(0);
+      } else {
+        pwd += c;
+        process.stdout.write('*');
+      }
+    };
+    stdin.resume();
+    stdin.on('data', onData);
+  });
+}
 
 const args = process.argv.slice(2);
 
@@ -623,6 +700,26 @@ function getComponentRegistry(importPkg) {
       component: 'DenebAction',
       code: `'use client';\n\nimport { DenebAction, type DenebActionProps } from '${importPkg}';\n\nexport { DenebAction, type DenebActionProps };\n`,
     },
+    'product-card': {
+      file: 'ProductCard.tsx',
+      component: 'EditableProductCard',
+      code: `'use client';\n\nimport { EditableProductCard, type EditableProductCardProps, type ProductItem } from '${importPkg}';\n\nexport function ProductCard(props: EditableProductCardProps) {\n  return <EditableProductCard {...props} />;\n}\n\nexport { EditableProductCard, type EditableProductCardProps, type ProductItem };\n`,
+    },
+    'product-grid': {
+      file: 'ProductGrid.tsx',
+      component: 'EditableProductGrid',
+      code: `'use client';\n\nimport { EditableProductGrid, ProductGrid, type EditableProductGridProps } from '${importPkg}';\n\nexport { EditableProductGrid, ProductGrid, type EditableProductGridProps };\n`,
+    },
+    'product-detail': {
+      file: 'ProductDetail.tsx',
+      component: 'PlatformProductDetail',
+      code: `'use client';\n\nimport { PlatformProductDetail, usePlatformProductDetail, platformProductDetailHref, type PlatformProductDetailProps } from '${importPkg}';\n\nexport function ProductDetail(props: PlatformProductDetailProps) {\n  return <PlatformProductDetail {...props} />;\n}\n\nexport { PlatformProductDetail, usePlatformProductDetail, platformProductDetailHref, type PlatformProductDetailProps };\n`,
+    },
+    'platform-product-detail': {
+      file: 'PlatformProductDetail.tsx',
+      component: 'PlatformProductDetail',
+      code: `'use client';\n\nimport { PlatformProductDetail, usePlatformProductDetail, platformProductDetailHref, type PlatformProductDetailProps } from '${importPkg}';\n\nexport { PlatformProductDetail, usePlatformProductDetail, platformProductDetailHref, type PlatformProductDetailProps };\n`,
+    },
   };
 }
 
@@ -683,6 +780,83 @@ async function initProject(targetInput, options = {}) {
     console.error(`\x1b[33m⚠ Note:\x1b[0m Automated conversion encountered an issue: ${err.message}. Falling back to default generation.`);
   }
 
+  // ── AI-Guided Semantic Analysis (interactive prompt) ──
+  // Only show prompt when: not already in AI mode, not a dry run, and running in an interactive terminal
+  if (!options.aiEnabled && !options.dryRun && process.stdin.isTTY) {
+    console.log('');
+    const aiAnswer = await askQuestion(
+      '\x1b[36m?\x1b[0m Would you like to interact with AI for advanced semantic analysis? \x1b[90m(y/N)\x1b[0m '
+    );
+
+    if (aiAnswer.toLowerCase() === 'y' || aiAnswer.toLowerCase() === 'yes') {
+      let isAuthorized = false;
+
+      // Check if DENEB_AI_KEY is already set in environment / .env
+      if (process.env.DENEB_AI_KEY && verifyAiAccessKey(process.env.DENEB_AI_KEY)) {
+        console.log('\x1b[32m✔ AI access key detected from environment (DENEB_AI_KEY).\x1b[0m');
+        isAuthorized = true;
+      } else {
+        const password = await askPassword('\x1b[36m\u{1F511}\x1b[0m Enter AI access key: ');
+        if (verifyAiAccessKey(password)) {
+          isAuthorized = true;
+        }
+      }
+
+      if (isAuthorized) {
+        console.log('\n\x1b[32m✔ Access granted.\x1b[0m Activating AI-guided semantic analysis...\n');
+
+        // Pre-flight check for OpenAI API configuration readiness
+        try {
+          const { loadEnv, checkAiReady } = require('../src/arc/ai-agent.cjs');
+          loadEnv(targetDir);
+          const aiCheck = checkAiReady();
+          if (!aiCheck.ready) {
+            console.log(`\x1b[33m⚠ Note:\x1b[0m ${aiCheck.reason}`);
+            console.log('\x1b[90mEnsure OPENAI_API_KEY is configured in your .env file or environment.\x1b[0m\n');
+          }
+        } catch {
+          // non-blocking pre-check
+        }
+
+        try {
+          const { runDenebArc } = require('../src/arc/index.cjs');
+          const aiResult = await runDenebArc(targetDir, projectName, {
+            ...options,
+            detectedPages,
+            aiEnabled: true,
+          });
+          if (aiResult) conversionRes = aiResult;
+          console.log('\x1b[32m✔ AI-guided refactoring complete.\x1b[0m');
+
+          // Interactive Recipe Learning
+          if (process.stdin.isTTY) {
+            console.log('');
+            const saveRecipeAnswer = await askQuestion(
+              '\x1b[36m?\x1b[0m Would you like to learn & save these converted patterns as a reusable storefront recipe? \x1b[90m(y/N)\x1b[0m '
+            );
+            if (saveRecipeAnswer.toLowerCase() === 'y' || saveRecipeAnswer.toLowerCase() === 'yes') {
+              try {
+                const { saveRecipeFromProject } = require('../src/tools/recipe-engine.cjs');
+                const saveRes = saveRecipeFromProject(targetDir, projectName);
+                console.log(`\x1b[32m✔ Recipe saved successfully:\x1b[0m \x1b[1m${saveRes.recipe.name}\x1b[0m`);
+                console.log(`  Saved to CLI recipe bank: \x1b[90m${saveRes.globalDest}\x1b[0m`);
+              } catch (recErr) {
+                console.log(`\x1b[33m⚠ Could not save recipe:\x1b[0m ${recErr.message}`);
+              }
+            }
+          }
+        } catch (aiErr) {
+          console.error(`\x1b[33m⚠ AI refactoring encountered an issue:\x1b[0m ${aiErr.message}`);
+          console.log('\x1b[90mContinuing with standard ARC results...\x1b[0m');
+        }
+      } else {
+        console.log('\n\x1b[31m✖ Invalid access key.\x1b[0m Continuing with standard ARC results...\n');
+      }
+    } else {
+      console.log('\x1b[90m⏩ Skipping AI analysis. Using standard ARC results.\x1b[0m');
+    }
+  }
+
   if (options.dryRun) {
     return conversionRes;
   }
@@ -712,6 +886,52 @@ async function initProject(targetInput, options = {}) {
     console.log(`\x1b[32m✔ Created\x1b[0m ${relSiteData} (merchant & editable site data)`);
   }
 
+  // 4.5. Stable Live Product Detail Route (/products/detail) for Static Export
+  const hasProductCatalog =
+    Boolean(manifestObj?.editorSchema?.sections?.some((s) => s.path === 'products' || s.path?.startsWith('products['))) ||
+    Boolean(fs.existsSync(siteDataPath) && fs.readFileSync(siteDataPath, 'utf8').includes('"products"')) ||
+    detectedPages.some((p) => p.route === '/products' || p.route?.startsWith('/products'));
+
+  if (hasNext && hasProductCatalog) {
+    const appDir = fs.existsSync(path.join(targetDir, 'src', 'app'))
+      ? path.join(targetDir, 'src', 'app')
+      : fs.existsSync(path.join(targetDir, 'app'))
+        ? path.join(targetDir, 'app')
+        : null;
+
+    if (appDir) {
+      const detailDir = path.join(appDir, 'products', 'detail');
+      const detailPage = path.join(detailDir, 'page.tsx');
+      const detailPageJs = path.join(detailDir, 'page.jsx');
+      const hasDetailPage = fs.existsSync(detailPage) || fs.existsSync(detailPageJs);
+
+      if (!hasDetailPage) {
+        fs.mkdirSync(detailDir, { recursive: true });
+        const detailCode = `'use client';\n\nimport React from 'react';\nimport { PlatformProductDetail } from '@deneb-ui/ui';\n\nexport default function ProductDetailPage() {\n  return <PlatformProductDetail backHref="/" />;\n}\n`;
+        fs.writeFileSync(detailPage, detailCode, 'utf8');
+        console.log(`\x1b[32m✔ Scaffolded\x1b[0m ${path.relative(targetDir, detailPage)} (stable live catalog detail route)`);
+      }
+
+      // Ensure /products/detail is registered in manifest pages[]
+      if (fs.existsSync(manifestPath)) {
+        try {
+          const currentManifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+          currentManifest.pages = Array.isArray(currentManifest.pages) ? currentManifest.pages : [];
+          const hasDetailInPages = currentManifest.pages.some((p) => p.route === '/products/detail' || p.id === 'product-detail');
+          if (!hasDetailInPages) {
+            currentManifest.pages.push({
+              id: 'product-detail',
+              label: 'Product Detail',
+              route: '/products/detail',
+            });
+            fs.writeFileSync(manifestPath, JSON.stringify(currentManifest, null, 2) + '\n');
+            console.log(`\x1b[32m✔ Registered\x1b[0m /products/detail in fivora-template.json`);
+          }
+        } catch {}
+      }
+    }
+  }
+
   // 4. Update package.json scripts
   pkg.scripts = pkg.scripts || {};
   const scriptsToAdd = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deneb-ui/cli",
-  "version": "2.0.66",
+  "version": "2.0.68",
   "description": "Official DENEB CLI — scaffold, convert, validate, and package Fivora-ready storefront templates.",
   "bin": {
     "deneb": "bin/index.js",
@@ -49,7 +49,7 @@
   "license": "MIT",
   "dependencies": {
     "@babel/parser": "^7.28.0",
-    "@deneb-ui/core": "^2.0.66",
+    "@deneb-ui/core": "^2.0.68",
     "@octokit/rest": "^22.0.1",
     "adm-zip": "^0.6.0",
     "dotenv": "^17.4.2",

package/src/arc/__tests__/arc.test.cjs

@@ -1423,4 +1423,53 @@ test('empty-state source audit flags gated preview markers', () => {
   assert.ok(errors.some((error) => error.includes('gated behind')));
 });
 
+test('healLegacyProductDetailLinks rewrites /products/${id} to platformProductDetailHref', () => {
+  const { parseSource, printSource } = require('../ast.cjs');
+  const { healLegacyProductDetailLinks } = require('../transformer.cjs');
+  const code = `
+export function ProductCard({ product }: { product: { id: string } }) {
+  return (
+    <a href={\`/products/\${product.id}\`}>
+      <span>View</span>
+    </a>
+  );
+}
+`;
+  const ast = parseSource(code, 'ProductCard.tsx');
+  const healed = healLegacyProductDetailLinks(ast);
+  assert.equal(healed, 1);
+  const out = printSource(ast);
+  assert.match(out, /platformProductDetailHref\(product\.id\)/);
+  assert.match(out, /from ['"]@deneb-ui\/ui['"]/);
+});
+
+test('saveRecipeFromProject learns calibrated fixes and registers live product detail route', () => {
+  const { saveRecipeFromProject, getRecipeByName } = require('../../tools/recipe-engine.cjs');
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deneb-recipe-test-'));
+  fs.writeFileSync(
+    path.join(tmpDir, 'fivora-template.json'),
+    JSON.stringify({
+      manifestVersion: 2,
+      name: 'Test Store',
+      pages: [{ id: 'home', route: '/' }, { id: 'products', route: '/products' }],
+      editorSchema: { version: 1, sections: [] },
+    })
+  );
+  const saveRes = saveRecipeFromProject(tmpDir, 'unit-test-store');
+  assert.equal(saveRes.recipe.name, 'unit-test-store');
+  assert.equal(saveRes.recipe.productDetailRules.detailRoute, '/products/detail');
+  assert.ok(saveRes.recipe.pages.some((p) => p.route === '/products/detail'));
+
+  const loaded = getRecipeByName('unit-test-store', tmpDir);
+  assert.ok(loaded);
+  assert.equal(loaded.name, 'unit-test-store');
+
+  // Clean up test artifacts
+  try {
+    if (fs.existsSync(saveRes.globalDest)) fs.unlinkSync(saveRes.globalDest);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  } catch {}
+});
+
+
 

package/src/arc/transformer.cjs

@@ -810,6 +810,7 @@ function applyFilePlan(filePlan, profile) {
   healBroadContainerMarkers(ast);
   healEmptyStateConditionals(ast);
   healHiddenPreviewMarkers(ast);
+  healLegacyProductDetailLinks(ast);
 
   // Page keys are stamped in a separate route-driven pass so App Router and
   // Pages Router projects are handled by the same logic.
@@ -1366,6 +1367,54 @@ function healHiddenPreviewMarkers(ast) {
   return healed;
 }
 
+function healLegacyProductDetailLinks(ast) {
+  let healed = 0;
+  let needsImport = false;
+
+  recast.types.visit(ast, {
+    visitJSXAttribute(pathNode) {
+      const attr = pathNode.node;
+      if (attr.name && attr.name.name === 'href' && attr.value) {
+        if (attr.value.type === 'JSXExpressionContainer' && attr.value.expression) {
+          const expr = attr.value.expression;
+          if (expr.type === 'TemplateLiteral') {
+            const quasis = expr.quasis || [];
+            if (quasis.length >= 1 && typeof quasis[0].value.raw === 'string' && quasis[0].value.raw.startsWith('/products/')) {
+              const arg = expr.expressions && expr.expressions[0];
+              if (arg) {
+                attr.value.expression = b.callExpression(
+                  b.identifier('platformProductDetailHref'),
+                  [arg]
+                );
+                healed++;
+                needsImport = true;
+              }
+            }
+          } else if (
+            expr.type === 'BinaryExpression' &&
+            expr.operator === '+' &&
+            expr.left &&
+            (expr.left.value === '/products/' || expr.left.value === '/products')
+          ) {
+            attr.value.expression = b.callExpression(
+              b.identifier('platformProductDetailHref'),
+              [expr.right]
+            );
+            healed++;
+            needsImport = true;
+          }
+        }
+      }
+      this.traverse(pathNode);
+    },
+  });
+
+  if (needsImport) {
+    ensureImport(ast, '@deneb-ui/ui', ['platformProductDetailHref']);
+  }
+  return healed;
+}
+
 module.exports = {
   applyFilePlan,
   instrumentLayoutSource,
@@ -1380,4 +1429,6 @@ module.exports = {
   healBroadContainerMarkers,
   healEmptyStateConditionals,
   healHiddenPreviewMarkers,
+  healLegacyProductDetailLinks,
 };
+

package/src/tools/deneb-doctor.cjs

@@ -176,7 +176,7 @@ function runDoctor(targetDirInput = '.', options = {}) {
   // =========================================================================
   // SUITE 1: System & Runtime Environment
   // =========================================================================
-  if (!isJson) console.log('\x1b[1m[1/6] System & Runtime Environment:\x1b[0m');
+  if (!isJson) console.log('\x1b[1m[1/7] System & Runtime Environment:\x1b[0m');
   const suite1 = 'System & Runtime';
 
   const nodeVersion = process.version;
@@ -198,7 +198,7 @@ function runDoctor(targetDirInput = '.', options = {}) {
   // =========================================================================
   // SUITE 2: Project Dependencies & Package Configuration
   // =========================================================================
-  if (!isJson) console.log('\n\x1b[1m[2/6] Project Package Configuration:\x1b[0m');
+  if (!isJson) console.log('\n\x1b[1m[2/7] Project Package Configuration:\x1b[0m');
   const suite2 = 'Package Configuration';
 
   const pkgPath = path.join(targetDir, 'package.json');
@@ -296,7 +296,7 @@ function runDoctor(targetDirInput = '.', options = {}) {
   // =========================================================================
   // SUITE 3: Next.js Static Export & Asset Optimization Architecture
   // =========================================================================
-  if (!isJson) console.log('\n\x1b[1m[3/6] Static Export & Asset Optimization:\x1b[0m');
+  if (!isJson) console.log('\n\x1b[1m[3/7] Static Export & Asset Optimization:\x1b[0m');
   const suite3 = 'Static Export Architecture';
 
   const nextConfigFiles = ['next.config.ts', 'next.config.mjs', 'next.config.js'];
@@ -341,7 +341,7 @@ function runDoctor(targetDirInput = '.', options = {}) {
   // =========================================================================
   // SUITE 4: Fivora Manifest v2 & Route Coherence
   // =========================================================================
-  if (!isJson) console.log('\n\x1b[1m[4/6] Fivora Manifest v2 & Route Architecture:\x1b[0m');
+  if (!isJson) console.log('\n\x1b[1m[4/7] Fivora Manifest v2 & Route Architecture:\x1b[0m');
   const suite4 = 'Manifest & Route Architecture';
 
   const manifestPath = path.join(targetDir, 'fivora-template.json');
@@ -403,7 +403,7 @@ function runDoctor(targetDirInput = '.', options = {}) {
   // =========================================================================
   // SUITE 5: AST Visual Editing Contract & Field Path Integrity
   // =========================================================================
-  if (!isJson) console.log('\n\x1b[1m[5/6] Visual Editing Contract & AST Integrity:\x1b[0m');
+  if (!isJson) console.log('\n\x1b[1m[5/7] Visual Editing Contract & AST Integrity:\x1b[0m');
   const suite5 = 'AST Visual Editing Contract';
 
   const siteDataPath = path.join(targetDir, 'src', 'data', 'site-data.json');
@@ -851,7 +851,7 @@ function runDoctor(targetDirInput = '.', options = {}) {
     addCheck(suite5, 'warn', 'Review Star Rating Editability', `${unannotatedStarCount} component(s) with unannotated star icons or ${missingRatingSchemaCount} review schema(s) missing rating field. Run with --fix to register.`, { code: 'DNB-REV-010' });
   }
 
-  if (!isJson) console.log('\n\x1b[1m[6/6] Multi-Niche Architecture & Asset Security:\x1b[0m');
+  if (!isJson) console.log('\n\x1b[1m[6/7] Multi-Niche Architecture & Asset Security:\x1b[0m');
   const suite6 = 'Niche Architecture & Security';
 
   // Niche match analysis
@@ -916,6 +916,124 @@ function runDoctor(targetDirInput = '.', options = {}) {
     addCheck(suite6, 'warn', 'Asset Optimization Preflight', `${largeAssets.length} large asset(s) detected (> 4MB)`, { code: 'DNB-AST-003' }) //, `${largeAssets.length} large asset(s) detected (> 4MB): ${largeAssets.map((a) => `${a.file} (${a.sizeMB}MB)`).join(', ')}`);
   }
 
+  // =========================================================================
+  // SUITE 7: Live Product Detail & Static Export Architecture
+  // =========================================================================
+  if (!isJson) console.log('\n\x1b[1m[7/7] Live Product Detail & Static Export Architecture:\x1b[0m');
+  const suite7 = 'Live Product Detail & Static Export';
+
+  const hasCatalogReference =
+    Boolean(manifestData?.editorSchema?.sections?.some((s) => s.path === 'products' || s.path?.startsWith('products['))) ||
+    Boolean(siteData?.content && hasFieldPath(siteData.content, 'products')) ||
+    (Array.isArray(manifestData?.pages) && manifestData.pages.some((p) => p.route === '/products' || p.route?.startsWith('/products')));
+
+  // Check 1: Dynamic build-time /products/${...} links vs platformProductDetailHref (DNB-PRD-001)
+  let legacyProductLinkCount = 0;
+  for (const file of sourceFiles) {
+    let c = fs.readFileSync(file, 'utf-8');
+    const legacyPatterns = [
+      /\/products\/\$\{[^}]+\}/g,
+      /['"`]\/products\/['"`]\s*\+\s*(?:encodeURIComponent\s*\()?[^),\s]+/g,
+    ];
+    let fileModified = false;
+    for (const pattern of legacyPatterns) {
+      const matches = [...c.matchAll(pattern)];
+      if (matches.length > 0) {
+        legacyProductLinkCount += matches.length;
+        if (shouldFix) {
+          c = c.replace(
+            /(?:href=\{`\/products\/\$\{(.*?)\}`\}|href=\{['"]\/products\/['"]\s*\+\s*(?:encodeURIComponent\s*\()?(.*?)\)?\})/g,
+            'href={platformProductDetailHref($1$2)}'
+          );
+          if (!c.includes('platformProductDetailHref')) {
+            if (/^['"]use client['"];?\r?\n/i.test(c)) {
+              c = c.replace(/^(['"]use client['"];?\r?\n)/i, `$1import { platformProductDetailHref } from '@deneb-ui/ui';\n`);
+            } else {
+              c = `import { platformProductDetailHref } from '@deneb-ui/ui';\n` + c;
+            }
+          }
+          fileModified = true;
+        }
+      }
+    }
+    if (shouldFix && fileModified) {
+      fs.writeFileSync(file, c, 'utf8');
+    }
+  }
+
+  if (legacyProductLinkCount === 0) {
+    addCheck(suite7, 'pass', 'Live Product Detail Links', 'Zero legacy /products/${id} links; product links use platformProductDetailHref()', { code: 'DNB-PRD-001' });
+  } else if (shouldFix) {
+    addCheck(suite7, 'fixed', 'Live Product Detail Links', `Converted ${legacyProductLinkCount} legacy product link(s) to platformProductDetailHref()`, { code: 'DNB-PRD-001' });
+  } else {
+    addCheck(suite7, 'err', 'Live Product Detail Links', `${legacyProductLinkCount} build-time /products/:id URL(s) detected. Fivora requires platformProductDetailHref() for static exports. Run with --fix to repair.`, { code: 'DNB-PRD-001' });
+  }
+
+  // Check 2: Stable client product detail route at /products/detail/page.tsx (DNB-PRD-002)
+  const appDir = fs.existsSync(path.join(targetDir, 'src', 'app'))
+    ? path.join(targetDir, 'src', 'app')
+    : fs.existsSync(path.join(targetDir, 'app'))
+      ? path.join(targetDir, 'app')
+      : null;
+
+  let detailPageExists = false;
+  let detailPageUsesPlatform = false;
+  let detailPagePath = null;
+
+  if (appDir) {
+    const candidates = [
+      path.join(appDir, 'products', 'detail', 'page.tsx'),
+      path.join(appDir, 'products', 'detail', 'page.jsx'),
+      path.join(appDir, 'products', 'detail', 'page.js'),
+    ];
+    detailPagePath = candidates[0];
+    for (const cand of candidates) {
+      if (fs.existsSync(cand)) {
+        detailPageExists = true;
+        detailPagePath = cand;
+        const code = fs.readFileSync(cand, 'utf8');
+        if (code.includes('PlatformProductDetail') || code.includes('usePlatformProductDetail')) {
+          detailPageUsesPlatform = true;
+        }
+        break;
+      }
+    }
+  }
+
+  if (!hasCatalogReference) {
+    addCheck(suite7, 'pass', 'Stable Product Detail Route', 'Non-catalog template (product detail route not required)', { code: 'DNB-PRD-002' });
+  } else if (detailPageExists && detailPageUsesPlatform) {
+    addCheck(suite7, 'pass', 'Stable Product Detail Route', `Stable client detail route verified at ${path.relative(targetDir, detailPagePath)} using PlatformProductDetail`, { code: 'DNB-PRD-002' });
+  } else if (shouldFix && appDir) {
+    const detailDir = path.dirname(detailPagePath);
+    fs.mkdirSync(detailDir, { recursive: true });
+    const detailContent = `'use client';\n\nimport React from 'react';\nimport { PlatformProductDetail } from '@deneb-ui/ui';\n\nexport default function ProductDetailPage() {\n  return <PlatformProductDetail backHref="/" />;\n}\n`;
+    fs.writeFileSync(detailPagePath, detailContent, 'utf8');
+    addCheck(suite7, 'fixed', 'Stable Product Detail Route', `Scaffolded stable client route at ${path.relative(targetDir, detailPagePath)} with PlatformProductDetail`, { code: 'DNB-PRD-002' });
+  } else {
+    addCheck(suite7, 'err', 'Stable Product Detail Route', `Missing stable client route src/app/products/detail/page.tsx (Required by Fivora static export catalog contract). Run with --fix to scaffold.`, { code: 'DNB-PRD-002' });
+  }
+
+  // Check 3: Manifest registration for /products/detail (DNB-PRD-003)
+  if (hasCatalogReference && manifestData) {
+    const pages = Array.isArray(manifestData.pages) ? manifestData.pages : [];
+    const hasDetailRoute = pages.some((p) => p.route === '/products/detail' || p.id === 'product-detail');
+    if (hasDetailRoute) {
+      addCheck(suite7, 'pass', 'Detail Route Manifest Registration', 'Route /products/detail declared in fivora-template.json pages', { code: 'DNB-PRD-003' });
+    } else if (shouldFix) {
+      manifestData.pages = pages;
+      manifestData.pages.push({
+        id: 'product-detail',
+        label: 'Product Detail',
+        route: '/products/detail',
+      });
+      fs.writeFileSync(manifestPath, JSON.stringify(manifestData, null, 2) + '\n', 'utf8');
+      addCheck(suite7, 'fixed', 'Detail Route Manifest Registration', 'Added /products/detail to fivora-template.json pages', { code: 'DNB-PRD-003' });
+    } else {
+      addCheck(suite7, 'warn', 'Detail Route Manifest Registration', 'Manifest pages array missing /products/detail route. Run with --fix to add.', { code: 'DNB-PRD-003' });
+    }
+  }
+
   // =========================================================================
   // SUMMARY REPORT
   // =========================================================================

package/src/tools/recipe-engine.cjs

@@ -138,7 +138,9 @@ function saveRecipeFromProject(projectDir, recipeName = 'custom-storefront', opt
     productDetailRules: {
       enabled: true,
       sectionPath: 'product',
-      sampleRoute: '/products/vanta-aero-x',
+      detailRoute: '/products/detail',
+      sampleRoute: '/products/detail',
+      usePlatformDetail: true,
       galleryWithBasePath: true,
       noStaticOnEditableAncestors: true,
     },
@@ -155,7 +157,18 @@ function saveRecipeFromProject(projectDir, recipeName = 'custom-storefront', opt
       platforms: ['instagram', 'facebook', 'twitter', 'tiktok', 'youtube', 'linkedin'],
       targetPath: 'common.footer',
     },
-    pages: manifest.pages || [],
+    pages: (() => {
+      const existingPages = Array.isArray(manifest.pages) ? [...manifest.pages] : [];
+      const hasDetail = existingPages.some((p) => p.route === '/products/detail' || p.id === 'product-detail');
+      if (!hasDetail && existingPages.some((p) => (p.route || '').includes('/product'))) {
+        existingPages.push({
+          id: 'product-detail',
+          label: 'Live Product Detail',
+          route: '/products/detail',
+        });
+      }
+      return existingPages;
+    })(),
     sections: (manifest.editorSchema?.sections || []).map((s) => ({
       ...s,
       path: s.path || s.id,