@deneb-ui/cli 2.0.40 → 2.0.42

package/bin/index.js

@@ -1021,6 +1021,8 @@ if (command === 'init') {
   let explain = false;
   let legacy = false;
   let telemetry = 'off';
+  let aiEnabled = false;
+  let aiDryRun = false;
   for (let i = 0; i < commandArgs.length; i++) {
     const arg = commandArgs[i];
     if (arg === '--recipe' || arg === '-r') {
@@ -1033,6 +1035,11 @@ if (command === 'init') {
       explain = true;
     } else if (arg === '--legacy') {
       legacy = true;
+    } else if (arg === '--ai') {
+      aiEnabled = true;
+    } else if (arg === '--ai-dry-run') {
+      aiEnabled = true;
+      aiDryRun = true;
     } else if (arg === '--telemetry' && commandArgs[i + 1]) {
       telemetry = commandArgs[++i];
     } else if (arg.startsWith('--telemetry=')) {
@@ -1041,7 +1048,7 @@ if (command === 'init') {
       targetInput = arg;
     }
   }
-  initProject(targetInput, { recipeName, dryRun, explain, legacy, telemetry });
+  initProject(targetInput, { recipeName, dryRun, explain, legacy, telemetry, aiEnabled, aiDryRun });
 } else if (command === 'create') {
   createTemplate(commandArgs[0]);
 } else if (command === 'add') {
@@ -1108,7 +1115,7 @@ if (command === 'init') {
 
 Core Commands:
   init              Deneb ARC: convert an existing React/Next.js app into a Fivora-editable storefront
-                    flags: --dry-run  --explain  --recipe <name>  --legacy  --telemetry off|anonymous|enhanced
+                    flags: --dry-run  --explain  --recipe <name>  --legacy  --ai  --ai-dry-run  --telemetry off|anonymous|enhanced
   doctor            Run comprehensive environment, manifest, visual editing AST & asset diagnostic checks (flags: --fix, --json)
   save-recipe       Learn and save calibrated fixes & schemas into reusable recipe bank (e.g. deneb save-recipe . shoes-store)
   learn             Alias for save-recipe
@@ -1136,6 +1143,8 @@ Examples:
   deneb init --recipe electronics
   deneb init --recipe cosmetics
   deneb init --legacy
+  deneb init --ai
+  deneb init --ai-dry-run
   deneb fonts list
   deneb fonts install .
   deneb fonts install . --font inter --font playfair-display

package/package.json

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

package/src/arc/ai-agent.cjs

@@ -0,0 +1,328 @@
+'use strict';
+
+/**
+ * Deneb ARC — AI Agent
+ *
+ * OpenAI API integration with self-healing validation loop.
+ * Generates editable wrapper components for unknown UI components
+ * and validates them through ARC's strict pipeline before accepting.
+ *
+ * Default engine: GPT-4o-mini (configurable via OPENAI_CONTENT_MODEL).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseSource } = require('./ast.cjs');
+const { buildComponentPrompt, buildFixPrompt, buildDocsPrompt } = require('./ai-prompts.cjs');
+
+const MAX_RETRIES = 3;
+
+/**
+ * Load AI configuration from environment variables.
+ * Call loadEnv() before using this if .env is not loaded yet.
+ */
+function getAiConfig() {
+  return {
+    apiKey: process.env.OPENAI_API_KEY || '',
+    model: process.env.OPENAI_CONTENT_MODEL || 'gpt-4o-mini',
+    maxTokens: parseInt(process.env.OPENAI_MAX_OUTPUT_TOKENS || '4000', 10),
+    timeoutMs: parseInt(process.env.OPENAI_CONTENT_TIMEOUT_MS || '120000', 10),
+  };
+}
+
+/**
+ * Load .env file purely locally.
+ * Searches upward from targetDir or process.cwd(), supporting local .env and .env.local files.
+ * Eliminates the need for any global system configuration.
+ *
+ * @param {string} [startDir] - Starting directory (defaults to process.cwd())
+ */
+function loadEnv(startDir) {
+  const checked = new Set();
+  const candidates = [];
+
+  let curr = path.resolve(startDir || process.cwd());
+  for (let i = 0; i < 5; i++) {
+    candidates.push(path.join(curr, '.env'));
+    candidates.push(path.join(curr, '.env.local'));
+    candidates.push(path.join(curr, 'core', '.env'));
+    const parent = path.dirname(curr);
+    if (parent === curr) break;
+    curr = parent;
+  }
+
+  candidates.push(path.resolve(__dirname, '..', '..', '..', '..', '.env'));
+  candidates.push(path.resolve(__dirname, '..', '..', '.env'));
+
+  for (const envPath of candidates) {
+    if (!checked.has(envPath) && fs.existsSync(envPath)) {
+      try {
+        require('dotenv').config({ path: envPath });
+      } catch {
+        // dotenv not available — env vars must be set manually
+      }
+      return;
+    }
+    checked.add(envPath);
+  }
+}
+
+/**
+ * Check if the AI agent is properly configured and ready to use.
+ * @returns {{ ready: boolean, reason?: string }}
+ */
+function checkAiReady() {
+  loadEnv();
+  const config = getAiConfig();
+  if (!config.apiKey) {
+    return { ready: false, reason: 'OPENAI_API_KEY not set. Create a .env file (see .env.example) or set the environment variable.' };
+  }
+  if (!config.apiKey.startsWith('sk-')) {
+    return { ready: false, reason: 'OPENAI_API_KEY does not look valid (should start with sk-).' };
+  }
+  return { ready: true };
+}
+
+/**
+ * Call the OpenAI Chat Completions API.
+ *
+ * Uses native fetch (Node 18+) — no external HTTP library needed.
+ *
+ * @param {string} prompt - The user prompt
+ * @param {object} [opts] - Optional overrides
+ * @returns {Promise<{ content: string, inputTokens: number, outputTokens: number }>}
+ */
+async function callOpenAI(prompt, opts = {}) {
+  const config = getAiConfig();
+  const model = opts.model || config.model;
+  const maxTokens = opts.maxTokens || config.maxTokens;
+  const timeoutMs = opts.timeoutMs || config.timeoutMs;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch('https://api.openai.com/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${config.apiKey}`,
+      },
+      body: JSON.stringify({
+        model,
+        messages: [
+          { role: 'system', content: 'You are a senior React/TypeScript developer specializing in the DENEB UI framework. Output only raw code — no markdown, no explanations.' },
+          { role: 'user', content: prompt },
+        ],
+        max_tokens: maxTokens,
+        temperature: 0.2,
+      }),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => '');
+      throw new Error(`OpenAI API error ${response.status}: ${errorBody.slice(0, 200)}`);
+    }
+
+    const data = await response.json();
+    const choice = data.choices?.[0];
+    if (!choice || !choice.message?.content) {
+      throw new Error('OpenAI returned empty response — no content in choices[0].message');
+    }
+
+    let content = choice.message.content.trim();
+    // Strip markdown fences if the model wraps output despite instructions
+    content = content.replace(/^```(?:tsx?|jsx?|typescript|javascript)?\s*\n?/i, '').replace(/\n?```\s*$/i, '').trim();
+
+    return {
+      content,
+      inputTokens: data.usage?.prompt_tokens || 0,
+      outputTokens: data.usage?.completion_tokens || 0,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Validate generated component code using ARC's validators.
+ *
+ * @param {string} code - The generated TypeScript/JSX code
+ * @param {string} filename - Virtual filename for error messages
+ * @returns {{ passed: boolean, errors: string[] }}
+ */
+function validateGeneratedCode(code, filename) {
+  const errors = [];
+
+  // 1. AST syntax check
+  try {
+    parseSource(code, filename);
+  } catch (err) {
+    errors.push(`AST syntax error: ${err.message}`);
+  }
+
+  // 2. Must have data-preview-field-path markers
+  if (!code.includes('data-preview-field-path')) {
+    errors.push('Missing data-preview-field-path markers — the component has no editable fields.');
+  }
+
+  // 3. Must have data-preview-item-path on the root wrapper
+  if (!code.includes('data-preview-item-path')) {
+    errors.push('Missing data-preview-item-path on root wrapper element.');
+  }
+
+  // 4. Must have proper TypeScript exports
+  if (!code.includes('export function') && !code.includes('export const')) {
+    errors.push('Missing named export — component must use `export function Editable...()`.');
+  }
+
+  // 5. Must have TypeScript interface
+  if (!code.includes('export interface')) {
+    errors.push('Missing exported TypeScript interface for component props.');
+  }
+
+  // 6. Must import EditableText or EditableImage (at least one)
+  if (!code.includes("from './EditableText'") && !code.includes("from './EditableImage'")) {
+    errors.push('Must import at least EditableText or EditableImage from relative path.');
+  }
+
+  // 7. Must NOT have default export (Deneb convention)
+  if (/export\s+default\s+/m.test(code)) {
+    errors.push('Must NOT use default export — use named export only (Deneb convention).');
+  }
+
+  // 8. Check for forbidden patterns
+  if (code.includes('useState') || code.includes('useEffect') || code.includes('useContext')) {
+    errors.push('Must NOT import React hooks (useState, useEffect, useContext). Component must be stateless.');
+  }
+
+  if (code.includes('useSiteData')) {
+    errors.push('Must NOT import useSiteData directly. The wrapper uses EditableText/EditableImage primitives instead.');
+  }
+
+  return {
+    passed: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Extract the list of editable field paths from generated component code.
+ *
+ * @param {string} code - The generated component code
+ * @returns {string[]} Array of field path patterns found
+ */
+function extractFieldPaths(code) {
+  const matches = code.matchAll(/data-preview-field-path=\{[`"']([^`"']+)[`"']\}/g);
+  const paths = new Set();
+  for (const m of matches) {
+    // Normalize template literal patterns like `${itemPath}.name`
+    const path = m[1].replace(/\$\{[^}]+\}/g, '*');
+    paths.add(path);
+  }
+  return [...paths];
+}
+
+/**
+ * Main AI adaptation function with self-healing validation loop.
+ *
+ * @param {string} sourceCode - The unknown component's source code
+ * @param {string} componentName - The component name (e.g. "Carousel")
+ * @param {object} profile - ARC project profile
+ * @param {object} [callbacks] - Optional progress callbacks
+ * @param {function} [callbacks.onAttempt] - Called at start of each attempt: (attemptNum, maxRetries)
+ * @param {function} [callbacks.onValidationFail] - Called when validation fails: (errors, attemptNum)
+ * @param {function} [callbacks.onSuccess] - Called on success: (attemptNum)
+ * @returns {Promise<{ success: boolean, code?: string, fields?: string[], attempts: number, totalInputTokens: number, totalOutputTokens: number, error?: string }>}
+ */
+async function adaptComponent(sourceCode, componentName, profile, callbacks = {}) {
+  let totalInputTokens = 0;
+  let totalOutputTokens = 0;
+
+  // Generate initial code
+  const prompt = buildComponentPrompt(sourceCode, componentName, profile);
+  let lastCode = '';
+  let lastErrors = [];
+
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    if (callbacks.onAttempt) callbacks.onAttempt(attempt, MAX_RETRIES);
+
+    try {
+      let result;
+      if (attempt === 1) {
+        result = await callOpenAI(prompt);
+      } else {
+        const fixPrompt = buildFixPrompt(lastCode, lastErrors.join('\n'), attempt);
+        result = await callOpenAI(fixPrompt);
+      }
+
+      totalInputTokens += result.inputTokens;
+      totalOutputTokens += result.outputTokens;
+      lastCode = result.content;
+
+      // Validate the generated code
+      const filename = `Editable${componentName}.tsx`;
+      const validation = validateGeneratedCode(lastCode, filename);
+
+      if (validation.passed) {
+        if (callbacks.onSuccess) callbacks.onSuccess(attempt);
+        return {
+          success: true,
+          code: lastCode,
+          fields: extractFieldPaths(lastCode),
+          attempts: attempt,
+          totalInputTokens,
+          totalOutputTokens,
+        };
+      }
+
+      // Validation failed — prepare for retry
+      lastErrors = validation.errors;
+      if (callbacks.onValidationFail) callbacks.onValidationFail(validation.errors, attempt);
+    } catch (err) {
+      lastErrors = [err.message];
+      if (callbacks.onValidationFail) callbacks.onValidationFail([err.message], attempt);
+    }
+  }
+
+  // All retries exhausted
+  return {
+    success: false,
+    attempts: MAX_RETRIES,
+    totalInputTokens,
+    totalOutputTokens,
+    error: `Failed after ${MAX_RETRIES} attempts. Last errors:\n${lastErrors.join('\n')}`,
+  };
+}
+
+/**
+ * Generate documentation page for a successfully adapted component.
+ *
+ * @param {string} componentName - e.g. "Carousel"
+ * @param {string} componentCode - The validated Editable*.tsx source
+ * @param {string[]} editableFields - List of field paths
+ * @returns {Promise<{ success: boolean, code?: string, error?: string }>}
+ */
+async function generateDocsPage(componentName, componentCode, editableFields) {
+  const prompt = buildDocsPrompt(componentName, componentCode, editableFields);
+
+  try {
+    const result = await callOpenAI(prompt);
+    return { success: true, code: result.content };
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
+}
+
+module.exports = {
+  loadEnv,
+  checkAiReady,
+  getAiConfig,
+  callOpenAI,
+  validateGeneratedCode,
+  extractFieldPaths,
+  adaptComponent,
+  generateDocsPage,
+  MAX_RETRIES,
+};

package/src/arc/ai-prompts.cjs

@@ -0,0 +1,214 @@
+'use strict';
+
+/**
+ * Deneb ARC — AI Prompt Templates
+ *
+ * Carefully engineered prompt templates that teach GPT-4o-mini the exact
+ * Deneb editable component conventions. Uses a real EditableServiceCard
+ * as a reference pattern so the AI learns the correct structure.
+ */
+
+// ─── Reference component (shortened for token efficiency) ────────
+const REFERENCE_COMPONENT = `
+import React from 'react';
+import { EditableText } from './EditableText';
+import { EditableImage } from './EditableImage';
+
+export interface ServiceItem {
+  id?: string | number;
+  name?: string;
+  title?: string;
+  price?: string | number;
+  description?: string;
+  imageUrl?: string;
+  image?: string;
+  features?: unknown[];
+  [key: string]: unknown;
+}
+
+export interface EditableServiceCardProps extends React.HTMLAttributes<HTMLElement> {
+  itemPath: string;
+  service: ServiceItem;
+  imageFallback?: string;
+  as?: React.ElementType;
+  align?: 'left' | 'center' | 'right';
+  showPrice?: boolean;
+}
+
+export function EditableServiceCard({
+  itemPath,
+  service,
+  imageFallback = '/placeholder.svg',
+  as: Component = 'article',
+  align = 'left',
+  showPrice = true,
+  className = '',
+  style,
+  children,
+  ...props
+}: EditableServiceCardProps) {
+  const name = String(service?.name || service?.title || '');
+  const description = String(service?.description || '');
+  const imageUrl = String(service?.imageUrl || service?.image || '');
+
+  return (
+    <Component
+      data-preview-item-path={itemPath}
+      className={\`editable-service-card \${className}\`.trim()}
+      style={{ textAlign: align, ...style }}
+      {...(props as any)}
+    >
+      <div className="service-card-image-wrap">
+        <EditableImage
+          id={\`\${itemPath}.imageUrl\`}
+          data-preview-field-path={\`\${itemPath}.imageUrl\`}
+          src={imageUrl}
+          fallbackSrc={imageFallback}
+          alt={name}
+          className="service-card-image"
+        />
+      </div>
+      <div className="service-card-body">
+        <EditableText
+          as="h2"
+          id={\`\${itemPath}.name\`}
+          data-preview-field-path={\`\${itemPath}.name\`}
+          defaultValue={name}
+          className="service-card-title"
+        />
+        <EditableText
+          as="p"
+          id={\`\${itemPath}.description\`}
+          data-preview-field-path={\`\${itemPath}.description\`}
+          defaultValue={description}
+          className="service-card-description"
+        />
+        {children}
+      </div>
+    </Component>
+  );
+}
+`.trim();
+
+/**
+ * Build the main component generation prompt.
+ *
+ * @param {string} sourceCode - The unknown component's source code
+ * @param {string} componentName - The component's name (e.g. "Carousel")
+ * @param {object} profile - ARC project profile (framework, libraries, etc.)
+ * @returns {string} The complete prompt for OpenAI
+ */
+function buildComponentPrompt(sourceCode, componentName, profile) {
+  return `You are an expert React/TypeScript developer working on the DENEB UI framework.
+Your task is to create an editable wrapper component for an existing component.
+
+## RULES (MANDATORY — violating any rule means the output is rejected):
+
+1. **Import only from relative paths**: Use \`./EditableText\` and \`./EditableImage\` (these are the ONLY two Deneb primitives you may use).
+2. **Every user-visible text** must be wrapped in \`<EditableText>\` with:
+   - \`as\` prop matching the original HTML tag (h1, h2, p, span, etc.)
+   - \`id={\`\${itemPath}.fieldName\`}\`
+   - \`data-preview-field-path={\`\${itemPath}.fieldName\`}\`
+   - \`defaultValue={value}\`
+3. **Every user-visible image** must use \`<EditableImage>\` with:
+   - \`id={\`\${itemPath}.fieldName\`}\`
+   - \`data-preview-field-path={\`\${itemPath}.fieldName\`}\`
+   - \`src={value}\`
+   - \`fallbackSrc={imageFallback}\`
+4. **Lists/arrays** must have \`data-preview-list-path\` on the container and \`data-preview-item-path\` on each item.
+5. **Root wrapper** must have \`data-preview-item-path={itemPath}\`.
+6. **Export a TypeScript interface** named \`Editable${componentName}Props\` extending \`React.HTMLAttributes<HTMLElement>\`.
+7. **Export a named function** (not default export) named \`Editable${componentName}\`.
+8. **Preserve all original CSS classes and styling** — do NOT remove or change className values.
+9. **Props must include**: \`itemPath: string\` (required), data object, \`as?: React.ElementType\`, \`className?\`, \`style?\`, \`children?\`.
+10. **Use \`'use strict'\` is NOT needed** — this is a .tsx file.
+11. **Do NOT import React hooks** like useState, useEffect, useContext. The component must be stateless.
+12. **Do NOT import useSiteData** — the wrapper component does not need it directly.
+
+## REFERENCE PATTERN (follow this structure exactly):
+
+\`\`\`tsx
+${REFERENCE_COMPONENT}
+\`\`\`
+
+## SOURCE COMPONENT TO ADAPT:
+
+Component name: ${componentName}
+Framework: ${profile.framework || 'nextjs'}
+Libraries: ${(profile.componentLibraries || []).join(', ') || 'none detected'}
+
+\`\`\`tsx
+${sourceCode}
+\`\`\`
+
+## YOUR OUTPUT:
+
+Generate ONLY the complete TypeScript (.tsx) file content for \`Editable${componentName}.tsx\`.
+Do NOT include markdown fences, explanations, or comments outside the code.
+Output the raw TypeScript code directly.`;
+}
+
+/**
+ * Build the error-fix prompt when the validator rejects AI-generated code.
+ *
+ * @param {string} previousCode - The code that failed validation
+ * @param {string} errorMessage - The exact validator error
+ * @param {number} attempt - Current attempt number
+ * @returns {string} The fix prompt
+ */
+function buildFixPrompt(previousCode, errorMessage, attempt) {
+  return `The DENEB ARC validator REJECTED your generated component (attempt ${attempt}/3).
+
+## EXACT ERROR:
+${errorMessage}
+
+## YOUR PREVIOUS CODE:
+\`\`\`tsx
+${previousCode}
+\`\`\`
+
+## INSTRUCTIONS:
+1. Fix ONLY the specific error described above.
+2. Do NOT change anything else — preserve all existing field paths, markers, and class names.
+3. Output the COMPLETE corrected .tsx file (not a diff, not a snippet — the full file).
+4. Do NOT include markdown fences or explanations. Output raw TypeScript code only.`;
+}
+
+/**
+ * Build the docs page generation prompt.
+ *
+ * @param {string} componentName - e.g. "Carousel"
+ * @param {string} componentCode - The validated EditableCarousel.tsx source
+ * @param {string[]} editableFields - List of field paths discovered
+ * @returns {string} The docs prompt
+ */
+function buildDocsPrompt(componentName, componentCode, editableFields) {
+  return `Generate a Next.js documentation page for the DENEB UI component "Editable${componentName}".
+
+## COMPONENT CODE:
+\`\`\`tsx
+${componentCode}
+\`\`\`
+
+## EDITABLE FIELDS:
+${editableFields.map((f) => `- ${f}`).join('\n')}
+
+## OUTPUT FORMAT:
+Generate a React component that exports a default function named \`Editable${componentName}DocsPage\`.
+It should render:
+1. A title section with the component name
+2. A description paragraph explaining what the component does
+3. A props table showing all available props with their types and defaults
+4. A usage example code block
+5. A list of editable field paths
+
+Use plain HTML/JSX with className for styling. Do NOT import any external UI libraries.
+Output raw TSX code only — no markdown fences or explanations.`;
+}
+
+module.exports = {
+  REFERENCE_COMPONENT,
+  buildComponentPrompt,
+  buildFixPrompt,
+  buildDocsPrompt,
+};