openprompt-lang 0.3.0 → 0.4.0

package/src/commands/integrate.js

@@ -0,0 +1,406 @@
+import { writeFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "fs"
+import { join } from "path"
+import chalk from "chalk"
+import inquirer from "inquirer"
+import { getLanguageIndex, getStructure } from "../utils/language-loader.js"
+
+const CURSOR_RULES_BASE = `// @generated by openPrompt-Lang integrate
+// This file configures Cursor AI behavior for this project.
+
+You are an expert TypeScript/React developer using openPrompt-Lang annotations.
+
+## Code Style
+- Use named exports, not default exports
+- Prefer arrow functions for components and hooks
+- Use TypeScript strict mode
+- No \`any\` types — use \`unknown\` + narrowing
+
+## Annotations
+- Every file must start with \`// @use(@kind, @props, @limit, @contract, @deps, @test)\`
+- Components: \`@kind(component)\` + \`@props({ ... })\`
+- Hooks: \`@kind(hook)\` + \`@contract(in: ... -> out: ... @error: ...)\`
+- Pages: \`@kind(page)\` + \`@compose(@subcomponent, @subcomponent)\`
+- Services: \`@kind(service)\` + \`@contract(in: ... -> out: ...)\`
+
+## Limits
+- Components: max 120 lines per file
+- Hooks: max 80 lines per file
+- Pages: max 200 lines per file
+- Extract reusable logic when limits are exceeded
+
+## Learning
+- When you encounter a bug, leave a comment with \`// @learn-error id=...\`
+- Reference templates: run \`npx openPrompt-Lang teach <template-id>\`
+- When in doubt, search the language module: \`npx openPrompt-Lang lang search <query>\`
+
+## Generated Files
+- Files matching \`*.template.*\`, \`*.test.*\`, and \`node_modules/*\` are off-limits for editing
+- Config files (\`prompt-lang.json\`, \`*.config.*\`) should not be modified by the AI
+`
+
+export async function integrate(options) {
+  const cwd = process.cwd()
+  console.log(chalk.cyan("\n🔌 openPrompt-Lang Editor Integration\n"))
+
+  // Detect existing config
+  const configPath = join(cwd, "prompt-lang.json")
+  let config = null
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, "utf-8"))
+      console.log(chalk.green(`  ✅ Found prompt-lang.json`))
+    } catch {
+      console.log(chalk.yellow(`  ⚠️  prompt-lang.json found but invalid — using defaults`))
+    }
+  } else {
+    console.log(chalk.yellow("  ⚠️  No prompt-lang.json found — using defaults"))
+  }
+
+  const langId = config?.lenguaje || options.lang || detectLanguageFromFiles(cwd)
+  const index = getLanguageIndex(langId)
+  const structure = getStructure(langId)
+
+  // Determine what to integrate
+  const targets = options.all
+    ? ["opencode", "cursor", "vscode"]
+    : await askIntegrationTargets(config, langId)
+
+  const results = []
+
+  if (targets.includes("opencode")) {
+    const r = await setupOpencode(cwd, config, langId, index)
+    results.push(r)
+  }
+
+  if (targets.includes("cursor")) {
+    const r = await setupCursor(cwd, config, langId, index)
+    results.push(r)
+  }
+
+  if (targets.includes("vscode")) {
+    const r = await setupVscode(cwd, config, langId)
+    results.push(r)
+  }
+
+  console.log(chalk.cyan("\n📋 Integration summary:\n"))
+  for (const r of results) {
+    const icon = r.status === "created" ? "✅" : r.status === "updated" ? "🔄" : "⏭️"
+    console.log(`  ${icon} ${r.file} ${r.status !== "skipped" ? "" : `(${r.reason})`}`)
+  }
+  console.log("")
+}
+
+// ─── Opencode integration ────────────────────────────────────────────────────
+
+async function setupOpencode(cwd, config, langId, index) {
+  const opencodeDir = join(cwd, ".opencode")
+  const configFile = join(opencodeDir, "opencode.json")
+  const agentDir = join(opencodeDir, "agent")
+
+  mkdirSync(opencodeDir, { recursive: true })
+  mkdirSync(agentDir, { recursive: true })
+
+  const opencodeConfig = {
+    $schema: "https://opencode.ai/config.json",
+    mcp: {
+      openPrompt: {
+        type: "local",
+        command: ["npx", "openprompt-lang", "mcp"],
+        enabled: true,
+      },
+    },
+    skills: {
+      paths: [".opencode/skills"],
+    },
+    default_agent: "openPrompt",
+    instructions: ["AGENTS.md"],
+  }
+
+  const wasExisting = existsSync(configFile)
+  writeFileSync(configFile, JSON.stringify(opencodeConfig, null, 2), "utf-8")
+  writeFileSync(
+    join(agentDir, "openPrompt.md"),
+    generateOpenPromptAgentMd(config, langId, index),
+    "utf-8"
+  )
+
+  // Generate skill for auto-detection
+  const skillsDir = join(opencodeDir, "skills", "openPrompt")
+  mkdirSync(skillsDir, { recursive: true })
+  writeFileSync(join(skillsDir, "SKILL.md"), generateSkillMd(config, langId, index), "utf-8")
+
+  return { file: ".opencode/opencode.json", status: wasExisting ? "updated" : "created" }
+}
+
+function getOpencodeRules(config, langId, index) {
+  const rules = [
+    "Always validate annotations with `openPrompt-Lang validate` before committing",
+    "Never edit `*.template.*` files directly",
+    "When refactoring, run `openPrompt-Lang extract` first to check for reusable patterns",
+  ]
+
+  if (config?.requirements?.auth && config.requirements.auth !== "none") {
+    rules.push(
+      `Auth provider is ${config.requirements.auth} — use the template \`npx openPrompt-Lang teach hook-useAuth --lang ${langId}\``
+    )
+  }
+
+  if (config?.ui?.style) {
+    rules.push(`UI library is ${config.ui.style} — prefer components from this library`)
+  }
+
+  if (index?.errorsLearned?.length > 0) {
+    rules.push(
+      `Module has ${index.errorsLearned.length} learned errors — run \`npx openPrompt-Lang qa-gen\` before deployment`
+    )
+  }
+
+  return rules
+}
+
+// ─── Cursor integration ──────────────────────────────────────────────────────
+
+async function setupCursor(cwd, config, langId, index) {
+  const cursorDir = join(cwd, ".cursor")
+  const rulesFile = join(cursorDir, "rules")
+
+  mkdirSync(cursorDir, { recursive: true })
+
+  const version = config?.version || "0.1.0"
+
+  let cursorConfig = {}
+  const cursorConfigFile = join(cursorDir, "config.json")
+  if (existsSync(cursorConfigFile)) {
+    try {
+      cursorConfig = JSON.parse(readFileSync(cursorConfigFile, "utf-8"))
+    } catch {}
+  }
+
+  cursorConfig = {
+    ...cursorConfig,
+    rules: CURSOR_RULES_BASE,
+    project: {
+      name: config?.name || cwd.split("/").pop(),
+      lenguaje: langId,
+      version,
+    },
+  }
+
+  writeFileSync(cursorConfigFile, JSON.stringify(cursorConfig, null, 2), "utf-8")
+  writeFileSync(rulesFile, CURSOR_RULES_BASE, "utf-8")
+
+  // Auto-generate .cursorrules at root
+  writeFileSync(join(cwd, ".cursorrules"), CURSOR_RULES_BASE, "utf-8")
+
+  return { file: ".cursor/ + .cursorrules", status: "created" }
+}
+
+// ─── VS Code integration ─────────────────────────────────────────────────────
+
+async function setupVscode(cwd, config, langId) {
+  const vscodeDir = join(cwd, ".vscode")
+  mkdirSync(vscodeDir, { recursive: true })
+
+  const settings = {
+    "typescript.preferences.importModuleSpecifier": "relative",
+    "typescript.preferences.quoteStyle": "double",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.fixAll": "explicit",
+      "source.organizeImports": "explicit",
+    },
+    "files.exclude": {
+      "**/.opencode": true,
+      "**/tsconfig.tsbuildinfo": true,
+    },
+    "typescript.tsdk": "node_modules/typescript/lib",
+  }
+
+  const extensions = {
+    recommendations: [
+      "dbaeumer.vscode-eslint",
+      "bradlc.vscode-tailwindcss",
+      "esbenp.prettier-vscode",
+    ],
+  }
+
+  writeFileSync(join(vscodeDir, "settings.json"), JSON.stringify(settings, null, 2), "utf-8")
+  writeFileSync(join(vscodeDir, "extensions.json"), JSON.stringify(extensions, null, 2), "utf-8")
+
+  return { file: ".vscode/settings.json", status: "created" }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function generateOpenPromptAgentMd(config, langId, index) {
+  const templates = index?.templates || []
+
+  return `---
+name: openPrompt
+description: Expert in openPrompt-Lang annotations, conventions, and AI-assisted development. Use when working with @kind, @contract, @props, @limit annotations or running openprompt-lang CLI commands.
+mode: primary
+permission:
+  edit: allow
+  bash:
+    git *: allow
+    npx openprompt-lang *: allow
+    npm *: allow
+    "*": ask
+---
+
+You are an expert in **openPrompt-Lang** — a framework of annotations for AI-assisted development.
+
+## Core Rules
+1. Every source file must declare annotations starting with \`@use()\` at the file top
+2. Validate before committing: run \`npx openprompt-lang validate\` to check annotation consistency
+3. Never edit \`*.template.*\` files directly — they are the language module's template library
+4. Use \`@learn-error\` when encountering bugs — document what you learn so future AI sessions benefit
+
+## Default Workflow (always follow this cycle)
+
+When working on ANY task, follow this sequence using MCP tools:
+
+\`\`\`
+Step 1: analyze_project → understand structure and health
+Step 2: validate         → find annotation errors
+Step 3: lint_file        → debug specific file errors
+Step 4: fix + @learn-error → document what you learned
+Step 5: generate_tests   → create regression tests
+Step 6: validate         → verify fix is clean
+\`\`\`
+
+### Workflow: Debugging annotation errors
+1. Call \`analyze_project\` to see the big picture
+2. Call \`validate\` to find all errors
+3. For each error file, call \`lint_file\` for details
+4. Fix the issue
+5. Add \`@learn-error\` annotation documenting the fix
+6. Call \`generate_tests\` to create regression tests
+7. Call \`validate\` again to verify
+
+### Workflow: Implementing a new component
+1. Call \`search_templates\` with the component type (e.g., "button")
+2. Call \`teach_template\` with the template ID + \`showCode: true\`
+3. Generate the component following the pattern
+4. Add appropriate \`@kind\`, \`@contract\`, etc. annotations
+5. Call \`validate\` before committing
+
+### Workflow: Onboarding to a new project
+1. Call \`analyze_project\` for structure overview
+2. Call \`validate\` to check health
+3. Read \`prompt-lang.json\` and \`AGENTS.md\` from the file system
+4. Call \`search_templates\` for relevant patterns
+5. Call \`teach_template\` to learn key patterns
+
+### Workflow: Starting a new project
+1. Call \`scaffold_project\` to create structure
+2. Call \`search_templates\` for each component you need
+3. Call \`teach_template\` to learn each pattern
+4. Implement following the patterns
+5. Call \`validate\` before committing
+
+## Available templates
+${templates.map((t) => `- \`${t.id}\`: ${t.description}${t.hasTeachMe ? " (with @teachMe)" : ""}`).join("\n")}
+
+## Rules
+${getOpencodeRules(config, langId, index)
+  .map((r) => `- ${r}`)
+  .join("\n")}
+`
+}
+
+function generateSkillMd(config, langId, index) {
+  const templates = index?.templates || []
+
+  return `---
+name: openprompt-lang
+description: |
+  Use ONLY when working with openPrompt-Lang annotations (@kind, @contract, @props, @limit, @use, @compose, @deps, @platform, @scope, @state, @forbidden, @pattern, @test, @meta, @learn-error, @goodPractice, @badPractice) or when running openprompt-lang CLI commands (validate, init, scaffold, teach, context, extract, integrate, qa-gen, ai-gen, suggest, wizard, figma, component, lang, mcp).
+---
+
+# openPrompt-Lang Framework
+
+## Overview
+openPrompt-Lang is an annotation-based framework for AI-assisted development.
+
+## Language Module
+**${config?.lenguaje || langId}** — ${index?.language || "Custom"}
+**Templates:** ${templates.length}
+**Learned errors:** ${index?.errorsLearned?.length || 0}
+
+## MCP Tools (available via Opencode)
+- **\`analyze_project\`** — FIRST tool on any unknown project. Returns config, file counts, annotation stats.
+- **\`validate\`** — PRE-COMMIT CHECK. Scan project for annotation errors.
+- **\`lint_file\`** — Debug a single file's annotations in detail.
+- **\`parse_code\`** — Validate annotation syntax inline during code generation.
+- **\`context\`** — Extract project structure with config summary.
+- **\`search_templates\`** — Find templates by keyword.
+- **\`teach_template\`** — Learn from a template (lesson, practices, code).
+- **\`generate_tests\`** — Generate regression tests from @learn-error annotations.
+- **\`scaffold_project\`** — Create project folder structure.
+
+## Default Workflow
+\`\`\`
+1. analyze_project → 2. validate → 3. lint_file → 4. fix + @learn-error → 5. generate_tests → 6. validate
+\`\`\`
+
+## CLI Commands
+- \`npx openprompt-lang validate [--fix]\` — Validate project structure and annotations
+- \`npx openprompt-lang teach <template-id>\` — Learn from a template
+- \`npx openprompt-lang qa-gen\` — Generate tests from learned errors
+- \`npx openprompt-lang lang search <query>\` — Search templates
+- \`npx openprompt-lang extract <dir>\` — Extract reusable components as templates
+- \`npx openprompt-lang context --output contexto.md\` — Extract project context for AI
+
+## Annotation Syntax
+\`\`\`typescript
+// @use(kind, contract, limit, deps)
+// @kind(hook)
+// @limit(lines: 80)
+// @contract(in: X -> out: Y @error: Z)
+\`\`\`
+
+## @learn-error Format
+\`\`\`typescript
+// @learn-error id=BUTTON-001 input='...' expected=200 actual=500 fix='...' category=validation
+\`\`\`
+`
+}
+
+async function askIntegrationTargets(config, langId) {
+  const { targets } = await inquirer.prompt([
+    {
+      type: "checkbox",
+      name: "targets",
+      message: "Which integrations do you need?",
+      choices: [
+        { name: "Opencode agent (.opencode/)", value: "opencode", checked: true },
+        { name: "Cursor rules (.cursor/ + .cursorrules)", value: "cursor", checked: true },
+        { name: "VS Code settings (.vscode/)", value: "vscode", checked: true },
+      ],
+    },
+  ])
+
+  if (targets.length === 0) {
+    console.log(chalk.yellow("\n  No integrations selected.\n"))
+    return null
+  }
+
+  return targets
+}
+
+function detectLanguageFromFiles(cwd) {
+  try {
+    const entries = readdirSync(cwd, { withFileTypes: true })
+
+    const hasVue = entries.some((e) => e.name.endsWith(".vue"))
+    const hasTsx = entries.some((e) => e.name.endsWith(".tsx"))
+    const hasPackageJson = entries.some((e) => e.name === "package.json")
+
+    if (hasVue) return "vue"
+    if (hasTsx || hasPackageJson) return "react"
+    return "react"
+  } catch {
+    return "react"
+  }
+}

package/src/commands/lang.js

@@ -0,0 +1,148 @@
+import chalk from "chalk"
+import {
+  getLanguages,
+  getLanguage,
+  getLanguageIndex,
+  searchTemplates,
+  getTemplateErrors,
+  getErrorsByTemplate,
+} from "../utils/language-loader.js"
+
+export async function langList() {
+  const langs = getLanguages(true)
+
+  if (langs.length === 0) {
+    console.log(chalk.yellow("\n  ⚠️  No language modules found in src/templates/langs/\n"))
+    return
+  }
+
+  console.log(chalk.cyan("\n📦 Available language modules:\n"))
+  for (const lang of langs) {
+    const index = getLanguageIndex(lang.id)
+    const templateCount = index?.templates?.length || 0
+    const hasTeachMe = index?.templates?.filter((t) => t.hasTeachMe).length || 0
+    const errorsCount = index?.errorsLearned?.length || 0
+
+    console.log(`  ${chalk.bold(lang.id)} — ${lang.name} v${lang.version}`)
+    console.log(`     📁 ${(lang.structure?.folders || []).length} folders`)
+    console.log(`     📄 ${templateCount} templates (${hasTeachMe} with @teachMe)`)
+    console.log(`     🐛 ${errorsCount} learned errors`)
+    console.log(`     🔌 ${(lang.extensions || []).length} extensions`)
+    console.log("")
+  }
+}
+
+export async function langIndex(langId, options) {
+  const lang = getLanguage(langId)
+  if (!lang) {
+    console.log(chalk.red(`\n❌ Language "${langId}" not found\n`))
+    return
+  }
+
+  const index = getLanguageIndex(langId)
+  if (!index) {
+    console.log(chalk.yellow(`\n  ⚠️  No INDEX.json for "${langId}"\n`))
+    return
+  }
+
+  console.log(chalk.cyan(`\n📚 ${lang.name} — Template Index\n`))
+
+  const category = options.category
+  let templates = index.templates || []
+
+  if (category) {
+    templates = templates.filter((t) => t.category === category)
+    const catInfo = index.categories?.[category]
+    if (catInfo) {
+      console.log(chalk.gray(`  Category: ${catInfo.name} — ${catInfo.description}\n`))
+    }
+  } else {
+    console.log(chalk.gray(`  Total: ${templates.length} templates\n`))
+  }
+
+  if (templates.length === 0) {
+    console.log(chalk.yellow("  No templates found.\n"))
+    return
+  }
+
+  // Group by category
+  const grouped = {}
+  for (const tmpl of templates) {
+    const cat = tmpl.category || "uncategorized"
+    if (!grouped[cat]) grouped[cat] = []
+    grouped[cat].push(tmpl)
+  }
+
+  for (const [cat, tmpls] of Object.entries(grouped)) {
+    const catInfo = index.categories?.[cat]
+    console.log(chalk.yellow.bold(`  ${catInfo?.name || cat}:\n`))
+    for (const tmpl of tmpls) {
+      const teachBadge = tmpl.hasTeachMe ? chalk.green(" [teach]") : ""
+      const darkBadge = tmpl.darkMode ? " 🌙" : ""
+      console.log(`    📦 ${chalk.bold(tmpl.id)}${teachBadge}${darkBadge}`)
+      console.log(`       ${tmpl.description}`)
+      if (tmpl.purposes?.length) console.log(`       purposes: ${tmpl.purposes.join(", ")}`)
+      if (tmpl.tags?.length) console.log(`       tags: ${chalk.gray(tmpl.tags.join(", "))}`)
+      console.log("")
+    }
+  }
+}
+
+export async function langSearch(query, options) {
+  if (!query) {
+    console.log(chalk.red("\n❌ Search query required\n"))
+    return
+  }
+
+  const results = searchTemplates(query, { language: options.lang })
+
+  if (results.length === 0) {
+    console.log(chalk.yellow(`\n  No results for "${query}"\n`))
+    return
+  }
+
+  console.log(chalk.cyan(`\n🔍 Search results for "${query}" (${results.length}):\n`))
+  for (const r of results) {
+    const teachBadge = r.hasTeachMe ? chalk.green(" [teach]") : ""
+    console.log(`  ${chalk.bold(r.id)}${teachBadge} — ${r.languageName}`)
+    console.log(`     ${r.description}`)
+    console.log(`     ${chalk.gray(r.category)} | deps: ${r.dependencies?.join(", ") || "none"}`)
+    console.log("")
+  }
+}
+
+export async function langErrors(langId, options) {
+  const lang = getLanguage(langId)
+  if (!lang) {
+    console.log(chalk.red(`\n❌ Language "${langId}" not found\n`))
+    return
+  }
+
+  const templateFilter = options.template
+
+  let errors
+  if (templateFilter) {
+    errors = getErrorsByTemplate(langId, templateFilter)
+  } else {
+    errors = getTemplateErrors(langId)
+  }
+
+  if (errors.length === 0) {
+    console.log(chalk.green(`\n  ✅ No learned errors for "${templateFilter || langId}"\n`))
+    return
+  }
+
+  console.log(
+    chalk.cyan(
+      `\n🐛 Learned errors${templateFilter ? ` for "${templateFilter}"` : ""} (${errors.length}):\n`
+    )
+  )
+  for (const err of errors) {
+    console.log(`  ${chalk.red("⚠️  " + err.id)} (${err.category})`)
+    console.log(`     template: ${err.template}`)
+    console.log(`     ${chalk.bold("Problem:")} ${err.problem}`)
+    console.log(`     ${chalk.bold("Fix:")}     ${err.solution}`)
+    console.log(`     ${chalk.gray(err.date)}`)
+    console.log("")
+  }
+}

package/src/commands/qa-gen.js

@@ -0,0 +1,139 @@
+import { join, relative } from "path"
+import { existsSync, mkdirSync, readFileSync } from "fs"
+import chalk from "chalk"
+import {
+  scanForLearnErrors,
+  parseLearnErrors,
+  persistErrors,
+  writeTestFile,
+  generateTests,
+} from "../utils/error-learner.js"
+import { getLanguageIndex, getTemplateErrors } from "../utils/language-loader.js"
+
+export async function qaGen(options) {
+  const cwd = process.cwd()
+  const langId = options.lang || "react"
+  const sourceDir = options.source ? join(cwd, options.source) : cwd
+  const outputDir = options.output ? join(cwd, options.output) : join(cwd, "src", "__tests__")
+
+  console.log(chalk.cyan("\n🧪 openPrompt-Lang QA Generator\n"))
+
+  // Phase 1: Scan source for @learn-error annotations
+  if (options.scan !== false) {
+    console.log(
+      chalk.blue(`  [1/3] Scanning ${relative(cwd, sourceDir)} for @learn-error annotations...`)
+    )
+    const foundErrors = scanForLearnErrors(sourceDir, langId)
+
+    if (foundErrors.length === 0) {
+      console.log(chalk.yellow("  No @learn-error annotations found in source.\n"))
+    } else {
+      console.log(chalk.green(`  Found ${foundErrors.length} @learn-error annotations:\n`))
+      for (const err of foundErrors) {
+        console.log(`     📍 ${chalk.bold(err.id)} — ${err.problem}`)
+        console.log(`        Fix: ${err.solution}`)
+        console.log(`        File: ${relative(cwd, err.sourceFile)}`)
+        console.log("")
+      }
+    }
+  }
+
+  // Phase 2: Generate tests from errors
+  console.log(chalk.blue("  [2/3] Generating tests from learned errors..."))
+
+  const index = getLanguageIndex(langId)
+  const storedErrors = index?.errorsLearned || []
+
+  if (storedErrors.length === 0) {
+    console.log(chalk.yellow("  No learned errors in language module INDEX.json.\n"))
+    console.log(
+      chalk.gray("  Tip: Add // @learn-error annotations to your code, then run this again.")
+    )
+    console.log(
+      chalk.gray(
+        "  Tip: Or add errors directly to src/templates/langs/<lang>/INDEX.json -> errorsLearned\n"
+      )
+    )
+    return
+  }
+
+  // Filter by template if specified
+  let errorsToTest = storedErrors
+  if (options.template) {
+    errorsToTest = storedErrors.filter((e) => e.template === options.template)
+    if (errorsToTest.length === 0) {
+      console.log(chalk.yellow(`  No errors found for template "${options.template}"\n`))
+      return
+    }
+  }
+
+  console.log(chalk.green(`  Using ${errorsToTest.length} learned errors from INDEX.json\n`))
+
+  for (const err of errorsToTest) {
+    console.log(`     🐛 ${chalk.bold(err.id)} (${err.category})`)
+    console.log(`        ${err.problem}`)
+    console.log(`        → ${err.solution}`)
+    console.log("")
+  }
+
+  // Phase 3: Write test file
+  if (!options.dryRun) {
+    console.log(chalk.blue(`  [3/3] Writing test file...`))
+
+    mkdirSync(outputDir, { recursive: true })
+    const outputFile = join(
+      outputDir,
+      options.template ? `${options.template}.qa.test.js` : "qa-learned.test.js"
+    )
+
+    writeTestFile(errorsToTest, outputFile, langId)
+    console.log(chalk.green(`  ✅ Generated: ${relative(cwd, outputFile)}\n`))
+    console.log(chalk.cyan(`  Run: npx vitest run ${relative(cwd, outputFile)}\n`))
+  } else {
+    console.log(chalk.gray("  (dry-run — no files written)\n"))
+    const testContent = generateTests(errorsToTest, langId)
+    console.log(chalk.gray("  Preview:\n"))
+    console.log(testContent.join("\n").slice(0, 500) + "...\n")
+  }
+}
+
+export function qaLearn(options) {
+  const langId = options.lang || "react"
+
+  // Parse @learn-error from a specific file
+  if (!options.file) {
+    console.log(chalk.red("\n❌ Specify a file with --file or pipe to learn from\n"))
+    return
+  }
+
+  const filePath = join(process.cwd(), options.file)
+
+  if (!existsSync(filePath)) {
+    console.log(chalk.red(`\n❌ File not found: ${options.file}\n`))
+    return
+  }
+
+  const content = readFileSync(filePath, "utf-8")
+  const errors = parseLearnErrors(content, filePath, langId)
+
+  if (errors.length === 0) {
+    console.log(chalk.yellow(`\n  No @learn-error annotations found in ${options.file}\n`))
+    console.log(
+      chalk.gray("  Format: // @learn-error id=X input='...' expected=N actual=N fix='...'\n")
+    )
+    return
+  }
+
+  console.log(chalk.cyan(`\n📝 Found ${errors.length} errors in ${options.file}\n`))
+
+  for (const err of errors) {
+    console.log(`  ${chalk.bold(err.id)}`)
+    console.log(`     Problem: ${err.problem}`)
+    console.log(`     Fix: ${err.solution}`)
+    console.log(`     Category: ${err.category}`)
+    console.log("")
+  }
+
+  const added = persistErrors(errors, langId)
+  console.log(chalk.green(`  ✅ ${added} new errors persisted to ${langId} module INDEX.json\n`))
+}