skrypt-ai 0.4.2 → 0.6.0

package/dist/commands/generate.js

@@ -6,6 +6,10 @@ import { DEFAULT_MODELS } from '../config/types.js';
 import { scanDirectory } from '../scanner/index.js';
 import { createLLMClient } from '../llm/index.js';
 import { generateForElements, groupDocsByFile, writeDocsToDirectory, writeDocsByTopic, writeLlmsTxt } from '../generator/index.js';
+import { showSecurityNotice } from '../auth/notices.js';
+import { runQA, printQAReport, fixQAIssues, printFixReport } from '../qa/index.js';
+import { extractDependencyIds, isChubInstalled, fetchContextHubDocs, exportToContextHub } from '../context-hub/index.js';
+import * as readline from 'readline';
 /**
  * Read .skryptignore patterns from source directory
  */
@@ -60,9 +64,23 @@ function shouldExcludeElement(element, patterns) {
         // Match by name
         if (pattern.startsWith('name:')) {
             const namePattern = pattern.slice(5);
-            if (element.name === namePattern || element.name.match(new RegExp(namePattern))) {
+            if (element.name === namePattern) {
                 return true;
             }
+            // Only use regex if the pattern contains regex metacharacters
+            // Reject patterns with nested quantifiers to prevent catastrophic backtracking (ReDoS)
+            if (/[*+?{}()|[\]\\^$.]/.test(namePattern)) {
+                if (/(\+|\*|\?)\{|\(\?[^:)]|\(\.[*+].*\)\+|\([^)]*[+*][^)]*\)[+*]/.test(namePattern)) {
+                    continue; // Skip patterns prone to catastrophic backtracking
+                }
+                try {
+                    if (new RegExp(namePattern).test(element.name))
+                        return true;
+                }
+                catch {
+                    // Invalid regex — treat as literal match (already checked above)
+                }
+            }
         }
         // Match by file path
         else if (pattern.includes('/') || pattern.includes('*')) {
@@ -112,6 +130,11 @@ export const generateCommand = new Command('generate')
         if (options.output)
             config.output.path = options.output;
         if (options.provider) {
+            const validProviders = ['deepseek', 'openai', 'anthropic', 'google', 'ollama', 'openrouter'];
+            if (!validProviders.includes(options.provider)) {
+                console.error(`Error: Unknown provider "${options.provider}". Valid: ${validProviders.join(', ')}`);
+                process.exit(1);
+            }
             config.llm.provider = options.provider;
             // Use provider's default model unless explicitly specified
             if (!options.model) {
@@ -137,6 +160,8 @@ export const generateCommand = new Command('generate')
                 process.exit(1);
             }
         }
+        // First-run security notice
+        showSecurityNotice();
         console.log('skrypt generate');
         console.log(`  source:   ${config.source.path}`);
         console.log(`  output:   ${config.output.path}`);
@@ -145,6 +170,20 @@ export const generateCommand = new Command('generate')
         if (config.llm.baseUrl) {
             console.log(`  base url: ${config.llm.baseUrl}`);
         }
+        // Routing transparency
+        const providerEnvKeys = {
+            openai: 'OPENAI_API_KEY',
+            anthropic: 'ANTHROPIC_API_KEY',
+            google: 'GOOGLE_API_KEY',
+            deepseek: 'DEEPSEEK_API_KEY',
+        };
+        const providerKey = providerEnvKeys[config.llm.provider];
+        if (providerKey && process.env[providerKey]) {
+            console.log(`  routing:  direct to ${config.llm.provider} (BYOK — your key never touches Skrypt)`);
+        }
+        else if (config.llm.provider !== 'ollama') {
+            console.log('  routing:  via Skrypt API proxy');
+        }
         console.log('');
         // Check source exists
         const sourcePath = resolve(config.source.path);
@@ -222,6 +261,53 @@ export const generateCommand = new Command('generate')
             console.log('\n[dry run - stopping before generation]');
             process.exit(0);
         }
+        // Auto-read project context from README for richer doc generation
+        let projectContext;
+        const readmeCandidates = ['README.md', 'README.mdx', 'readme.md', 'README.rst', 'README.txt'];
+        for (const candidate of readmeCandidates) {
+            const readmePath = join(sourcePath, candidate);
+            if (existsSync(readmePath)) {
+                try {
+                    const raw = readFileSync(readmePath, 'utf-8');
+                    // Take the first ~1500 chars (intro/description section, not the whole file)
+                    projectContext = raw.slice(0, 1500);
+                    console.log(`  Project context: loaded from ${candidate}`);
+                }
+                catch {
+                    // Skip if unreadable
+                }
+                break;
+            }
+        }
+        // Also check parent directory (common for monorepos where source is a subdirectory)
+        if (!projectContext) {
+            const parentReadme = join(sourcePath, '..', 'README.md');
+            if (existsSync(parentReadme)) {
+                try {
+                    projectContext = readFileSync(parentReadme, 'utf-8').slice(0, 1500);
+                    console.log('  Project context: loaded from parent README.md');
+                }
+                catch {
+                    // Skip
+                }
+            }
+        }
+        // Context Hub enrichment: fetch third-party API docs if chub is installed
+        let externalContext;
+        const allImports = [];
+        for (const el of allElements) {
+            if (el.imports?.length) {
+                allImports.push(...el.imports);
+            }
+        }
+        const chubIds = extractDependencyIds(allImports);
+        if (chubIds.length > 0 && isChubInstalled()) {
+            console.log(`\n  Context Hub: fetching docs for ${chubIds.length} dependencies...`);
+            externalContext = fetchContextHubDocs(chubIds);
+            if (externalContext.size > 0) {
+                console.log(`  Context Hub: enriching with ${externalContext.size} API references`);
+            }
+        }
         // Step 2: Generate docs
         console.log('\nStep 2: Generating documentation...');
         const client = createLLMClient({
@@ -236,6 +322,8 @@ export const generateCommand = new Command('generate')
         }
         const docs = await generateForElements(allElements, client, {
             multiLanguage,
+            externalContext,
+            projectContext,
             onProgress: (progress) => {
                 if (progress.element !== lastElement) {
                     if (lastElement)
@@ -292,13 +380,43 @@ export const generateCommand = new Command('generate')
                 console.log(`\n  Warning: OpenAPI spec not found: ${specPath}`);
             }
         }
-        // Generate llms.txt for AEO (Answer Engine Optimization)
-        if (options.llmsTxt) {
-            await writeLlmsTxt(docs, outputPath, {
-                projectName: options.projectName,
-                description: `API documentation for ${options.projectName || basename(sourcePath)}`
+        // Always generate llms.txt for AEO (Answer Engine Optimization)
+        await writeLlmsTxt(docs, outputPath, {
+            projectName: options.projectName,
+            description: `API documentation for ${options.projectName || basename(sourcePath)}`
+        });
+        console.log(`\n  Generated llms.txt and llms-full.md for AEO`);
+        // Step 4: Embedded QA (auto-fix then check)
+        console.log('\nStep 4: Running QA checks...');
+        const fixReport = fixQAIssues(outputPath);
+        printFixReport(fixReport);
+        const qaReport = runQA(outputPath);
+        printQAReport(qaReport);
+        // Context Hub export prompt (TTY only — skip in CI/piped mode)
+        if (process.stdin.isTTY) {
+            console.log('');
+            console.log('  Context Hub: Make your docs discoverable by AI coding agents.');
+            console.log('  Context Hub is a curated registry by Andrew Ng (7K+ stars)');
+            console.log('  https://github.com/andrewyng/context-hub');
+            console.log('');
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+            const answer = await new Promise((resolve) => {
+                rl.question('  Export for Context Hub? (y/N) ', (ans) => {
+                    rl.close();
+                    resolve(ans.trim().toLowerCase());
+                });
             });
-            console.log(`\n  Generated llms.txt and llms-full.md for AEO`);
+            if (answer === 'y' || answer === 'yes') {
+                const languages = multiLanguage ? ['typescript', 'python'] : ['typescript'];
+                const projName = options.projectName || basename(sourcePath);
+                const result = exportToContextHub(docs, outputPath, {
+                    projectName: projName,
+                    languages,
+                    description: `API documentation for ${projName}`,
+                });
+                console.log(`\n  Exported ${result.filesWritten} files to ${result.outputDir}`);
+                console.log('  See context-hub/README.md for submission instructions');
+            }
         }
         console.log('\n=== Summary ===');
         console.log(`  Total elements: ${totalDocs}`);

package/dist/commands/heal.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Self-healing command: skrypt heal
+ *
+ * Orchestrates 3 phases of documentation healing:
+ *   Phase 1: QA fixes (frontmatter, syntax, code blocks, security)
+ *   Phase 2: Code example fixes (LLM-powered)
+ *   Phase 3: Screenshot capture (headless browser)
+ */
+import { Command } from 'commander';
+export declare const healCommand: Command;

package/dist/commands/heal.js

@@ -0,0 +1,201 @@
+/**
+ * Self-healing command: skrypt heal
+ *
+ * Orchestrates 3 phases of documentation healing:
+ *   Phase 1: QA fixes (frontmatter, syntax, code blocks, security)
+ *   Phase 2: Code example fixes (LLM-powered)
+ *   Phase 3: Screenshot capture (headless browser)
+ */
+import { Command } from 'commander';
+import { resolve } from 'path';
+import { readFileSync, writeFileSync } from 'fs';
+import { requirePro } from '../auth/index.js';
+import { fixQAIssues, printFixReport, runQA, printQAReport } from '../qa/index.js';
+import { loadConfig, checkApiKey } from '../config/index.js';
+import { createLLMClient } from '../llm/index.js';
+import { autoFixExample, createTypeScriptValidator, createPythonValidator } from '../autofix/index.js';
+import { findMdxFiles } from '../utils/files.js';
+import { runCapture, printCaptureReport } from '../capture/index.js';
+export const healCommand = new Command('heal')
+    .description('Self-heal documentation: fix QA issues, broken code, and capture screenshots')
+    .argument('[docs-dir]', 'Documentation directory', '.')
+    .option('--base-url <url>', 'Base URL for screenshot capture', 'http://localhost:3000')
+    .option('--output <dir>', 'Screenshot output directory', 'public/screenshots')
+    .option('--viewport <size>', 'Viewport WxH', '1280x720')
+    .option('--dark', 'Also capture dark mode variants')
+    .option('--diff', 'Only re-capture changed screenshots')
+    .option('--screenshots', 'Run screenshot capture phase')
+    .option('--qa-only', 'Run only QA fix phase')
+    .option('--code-only', 'Run only code fix phase')
+    .option('--deep', 'Run all 3 phases')
+    .option('--dry-run', 'Show what would change without writing')
+    .option('--timeout <ms>', 'Page load timeout', '30000')
+    .option('--wait <ms>', 'Wait after page load', '1000')
+    .option('--device <name>', 'Emulate device (e.g. "iPhone 14")')
+    .option('--concurrency <n>', 'Parallel capture limit', '3')
+    .option('--provider <name>', 'LLM provider (for code fix phase)')
+    .option('--model <name>', 'LLM model (for code fix phase)')
+    .option('--max-iterations <n>', 'Max fix attempts per code example', '3')
+    .option('-c, --config <file>', 'Config file path')
+    .action(async (docsDir, options) => {
+    try {
+        // Pro feature
+        if (!await requirePro('heal')) {
+            process.exit(1);
+        }
+        const resolvedDir = resolve(docsDir);
+        const [vpWidth, vpHeight] = options.viewport.split('x').map(Number);
+        // Determine which phases to run
+        const hasPhaseFlag = options.qaOnly || options.codeOnly || options.screenshots;
+        const runPhase1 = options.deep || options.qaOnly || !hasPhaseFlag;
+        const runPhase2 = options.deep || options.codeOnly;
+        const runPhase3 = options.deep || options.screenshots;
+        console.log('skrypt heal');
+        console.log(`  directory: ${resolvedDir}`);
+        const phases = [];
+        if (runPhase1)
+            phases.push('QA fixes');
+        if (runPhase2)
+            phases.push('code fixes');
+        if (runPhase3)
+            phases.push('screenshots');
+        console.log(`  phases: ${phases.join(', ')}`);
+        if (options.dryRun)
+            console.log('  mode: dry run');
+        console.log('');
+        // ── Phase 1: QA Fixes ──
+        if (runPhase1) {
+            console.log('  ── Phase 1: QA Fixes ──');
+            if (options.dryRun) {
+                const qaReport = runQA(resolvedDir);
+                printQAReport(qaReport);
+            }
+            else {
+                const fixReport = fixQAIssues(resolvedDir);
+                printFixReport(fixReport);
+                if (fixReport.totalFixes > 0) {
+                    const qaReport = runQA(resolvedDir);
+                    printQAReport(qaReport);
+                }
+                else {
+                    console.log('  No QA issues to fix.');
+                }
+            }
+            console.log('');
+        }
+        // ── Phase 2: Code Fixes ──
+        if (runPhase2) {
+            console.log('  ── Phase 2: Code Fixes ──');
+            const config = loadConfig(options.config);
+            if (options.provider)
+                config.llm.provider = options.provider;
+            if (options.model)
+                config.llm.model = options.model;
+            const { ok, envKey } = checkApiKey(config.llm.provider);
+            if (!ok && envKey) {
+                console.error(`  Error: ${envKey} environment variable required for code fixes`);
+                console.error('  Skipping Phase 2.\n');
+            }
+            else {
+                const client = createLLMClient({
+                    provider: config.llm.provider,
+                    model: config.llm.model,
+                    baseUrl: config.llm.baseUrl,
+                });
+                const maxIterations = parseInt(options.maxIterations, 10) || 3;
+                const validators = {
+                    javascript: createTypeScriptValidator(),
+                    typescript: createTypeScriptValidator(),
+                    ts: createTypeScriptValidator(),
+                    js: createTypeScriptValidator(),
+                    python: createPythonValidator(),
+                    py: createPythonValidator(),
+                };
+                const docFiles = findMdxFiles(resolvedDir);
+                let totalFixed = 0;
+                let totalFailed = 0;
+                for (const filePath of docFiles) {
+                    let content;
+                    try {
+                        content = readFileSync(filePath, 'utf-8');
+                    }
+                    catch {
+                        continue;
+                    }
+                    // Find code blocks
+                    const codeBlockRegex = /```(\w+)?\n([\s\S]*?)```/g;
+                    const codeBlocks = [];
+                    let match;
+                    while ((match = codeBlockRegex.exec(content)) !== null) {
+                        const code = match[2];
+                        if (!code)
+                            continue;
+                        codeBlocks.push({
+                            match: match[0],
+                            language: match[1] || 'javascript',
+                            code,
+                        });
+                    }
+                    if (codeBlocks.length === 0)
+                        continue;
+                    let newContent = content;
+                    let fileFixed = 0;
+                    for (const block of codeBlocks) {
+                        const validator = validators[block.language.toLowerCase()];
+                        if (!validator)
+                            continue;
+                        const initial = await validator(block.code);
+                        if (initial.valid)
+                            continue;
+                        const result = await autoFixExample({ code: block.code, language: block.language, context: `Code example from ${filePath}` }, client, { maxIterations, validateFn: validator, language: block.language });
+                        if (result.success) {
+                            const newBlock = '```' + block.language + '\n' + result.fixedCode + '```';
+                            newContent = newContent.replace(block.match, newBlock);
+                            fileFixed++;
+                            totalFixed++;
+                        }
+                        else {
+                            totalFailed++;
+                        }
+                    }
+                    if (fileFixed > 0 && !options.dryRun) {
+                        writeFileSync(filePath, newContent, 'utf-8');
+                    }
+                }
+                if (totalFixed > 0 || totalFailed > 0) {
+                    console.log(`  Code fixes: ${totalFixed} fixed, ${totalFailed} failed`);
+                }
+                else {
+                    console.log('  All code examples are valid.');
+                }
+                if (options.dryRun && totalFixed > 0) {
+                    console.log('  [dry run — no changes written]');
+                }
+            }
+            console.log('');
+        }
+        // ── Phase 3: Screenshot Capture ──
+        if (runPhase3) {
+            console.log('  ── Phase 3: Screenshot Capture ──');
+            const captureOptions = {
+                baseUrl: options.baseUrl,
+                outputDir: options.output,
+                viewport: { width: vpWidth || 1280, height: vpHeight || 720 },
+                dark: options.dark || false,
+                diff: options.diff || false,
+                dryRun: options.dryRun || false,
+                timeout: parseInt(options.timeout, 10) || 30000,
+                wait: parseInt(options.wait, 10) || 1000,
+                device: options.device,
+                concurrency: parseInt(options.concurrency, 10) || 3,
+            };
+            const captureReport = await runCapture(resolvedDir, captureOptions);
+            printCaptureReport(captureReport);
+        }
+        console.log('Done!');
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+});