skrypt-ai 0.5.0 → 0.6.1

package/dist/commands/deploy.js

@@ -1,6 +1,6 @@
 import { Command } from 'commander';
 import { spawnSync, spawn } from 'child_process';
-import { existsSync, readFileSync, statSync } from 'fs';
+import { existsSync, readFileSync, statSync, unlinkSync } from 'fs';
 import { resolve, join } from 'path';
 import { homedir } from 'os';
 import { createHash } from 'crypto';
@@ -81,8 +81,7 @@ async function buildSite(docsPath) {
     return new Promise((resolve, reject) => {
         const child = spawn('npm', ['run', 'build'], {
             cwd: docsPath,
-            stdio: ['inherit', 'pipe', 'pipe'],
-            shell: true
+            stdio: ['inherit', 'pipe', 'pipe']
         });
         child.stdout?.on('data', (data) => {
             process.stdout.write(`  ${data.toString().trim()}\n`);
@@ -208,113 +207,135 @@ export const deployCommand = new Command('deploy')
     .option('--project <slug>', 'Project slug (e.g., my-docs)')
     .option('--token <key>', 'API token (or set SKRYPT_API_KEY env var)')
     .action(async (directory, options) => {
-    const startTime = Date.now();
-    const docsPath = resolve(directory);
-    console.log('skrypt deploy');
-    console.log(`  directory: ${docsPath}`);
-    console.log('');
-    // Validate directory
-    if (!existsSync(docsPath)) {
-        console.error(`Error: Directory not found: ${docsPath}`);
-        process.exit(1);
-    }
-    // Check for package.json (Next.js project)
-    const packageJsonPath = join(docsPath, 'package.json');
-    if (!existsSync(packageJsonPath)) {
-        console.error('Error: No package.json found. Is this a Skrypt docs site?');
-        console.error('  Run: skrypt init <directory>');
-        process.exit(1);
-    }
-    // Get API token
-    const apiToken = getApiToken(options);
-    if (!apiToken) {
-        console.error('Error: No API token found.');
-        console.error('');
-        console.error('  Provide a token using one of:');
-        console.error('    --token <key>');
-        console.error('    SKRYPT_API_KEY environment variable');
-        console.error('    skrypt login');
-        console.error('');
-        process.exit(1);
-    }
-    // Get project slug
-    const projectSlug = getProjectSlug(options, docsPath);
-    if (!projectSlug) {
-        console.error('Error: No project slug found.');
-        console.error('');
-        console.error('  Provide a project slug using one of:');
-        console.error('    --project <slug>');
-        console.error('    "slug" field in docs.json');
-        console.error('');
-        process.exit(1);
-    }
-    console.log(`  project: ${projectSlug}`);
-    console.log('');
-    // Step 1: Build the site
-    console.log('Step 1: Building documentation site...');
-    let outDir;
+    let bundlePath;
     try {
-        outDir = await buildSite(docsPath);
-    }
-    catch (err) {
-        console.error('');
-        console.error(`Error: Build failed`);
-        if (err instanceof Error) {
-            console.error(`  ${err.message}`);
+        const startTime = Date.now();
+        const docsPath = resolve(directory);
+        console.log('skrypt deploy');
+        console.log(`  directory: ${docsPath}`);
+        console.log('');
+        // Validate directory
+        if (!existsSync(docsPath)) {
+            console.error(`Error: Directory not found: ${docsPath}`);
+            process.exit(1);
         }
-        process.exit(1);
-    }
-    // Check build output exists
-    if (!existsSync(outDir)) {
-        // Try .next/static for non-static export
-        const nextDir = join(docsPath, '.next');
-        if (existsSync(nextDir)) {
+        // Check for package.json (Next.js project)
+        const packageJsonPath = join(docsPath, 'package.json');
+        if (!existsSync(packageJsonPath)) {
+            console.error('Error: No package.json found. Is this a Skrypt docs site?');
+            console.error('  Run: skrypt init <directory>');
+            process.exit(1);
+        }
+        // Get API token
+        const apiToken = getApiToken(options);
+        if (!apiToken) {
+            console.error('Error: No API token found.');
+            console.error('');
+            console.error('  Provide a token using one of:');
+            console.error('    --token <key>');
+            console.error('    SKRYPT_API_KEY environment variable');
+            console.error('    skrypt login');
             console.error('');
-            console.error('Error: Static export not found.');
-            console.error('  Add to next.config.mjs: output: "export"');
             process.exit(1);
         }
-        console.error('');
-        console.error('Error: Build output not found.');
-        process.exit(1);
-    }
-    console.log('  Build completed successfully');
-    console.log('');
-    // Step 2: Bundle the output
-    console.log('Step 2: Creating deployment bundle...');
-    let bundlePath;
-    try {
-        bundlePath = await bundleOutput(outDir);
+        // Get project slug
+        const projectSlug = getProjectSlug(options, docsPath);
+        if (!projectSlug) {
+            console.error('Error: No project slug found.');
+            console.error('');
+            console.error('  Provide a project slug using one of:');
+            console.error('    --project <slug>');
+            console.error('    "slug" field in docs.json');
+            console.error('');
+            process.exit(1);
+        }
+        console.log(`  project: ${projectSlug}`);
+        console.log('');
+        // Step 1: Build the site
+        console.log('Step 1: Building documentation site...');
+        let outDir;
+        try {
+            outDir = await buildSite(docsPath);
+        }
+        catch (err) {
+            console.error('');
+            console.error(`Error: Build failed`);
+            if (err instanceof Error) {
+                console.error(`  ${err.message}`);
+            }
+            process.exit(1);
+        }
+        // Check build output exists
+        if (!existsSync(outDir)) {
+            // Try .next/static for non-static export
+            const nextDir = join(docsPath, '.next');
+            if (existsSync(nextDir)) {
+                console.error('');
+                console.error('Error: Static export not found.');
+                console.error('  Add to next.config.mjs: output: "export"');
+                process.exit(1);
+            }
+            console.error('');
+            console.error('Error: Build output not found.');
+            process.exit(1);
+        }
+        console.log('  Build completed successfully');
+        console.log('');
+        // Step 2: Bundle the output
+        console.log('Step 2: Creating deployment bundle...');
+        try {
+            bundlePath = await bundleOutput(outDir);
+        }
+        catch (err) {
+            console.error('');
+            console.error('Error: Failed to create bundle');
+            if (err instanceof Error) {
+                console.error(`  ${err.message}`);
+            }
+            process.exit(1);
+        }
+        console.log('');
+        // Step 3: Upload
+        console.log('Step 3: Deploying to Skrypt...');
+        const result = await uploadBundle(bundlePath, projectSlug, apiToken);
+        if (!result.success) {
+            console.error('');
+            console.error(`Error: Deployment failed`);
+            console.error(`  ${result.error}`);
+            // Clean up temp bundle
+            try {
+                unlinkSync(bundlePath);
+            }
+            catch { /* ignore cleanup errors */ }
+            process.exit(1);
+        }
+        // Clean up temp bundle
+        try {
+            unlinkSync(bundlePath);
+        }
+        catch { /* ignore cleanup errors */ }
+        // Success
+        const duration = Math.round((Date.now() - startTime) / 1000);
+        console.log('');
+        console.log('=== Deployment Successful ===');
+        console.log('');
+        console.log(`  URL: ${result.url}`);
+        if (result.customDomain) {
+            console.log(`  Custom domain: ${result.customDomain}`);
+        }
+        console.log(`  Duration: ${duration}s`);
+        console.log('');
+        console.log('Your documentation is now live!');
+        console.log('');
     }
     catch (err) {
-        console.error('');
-        console.error('Error: Failed to create bundle');
-        if (err instanceof Error) {
-            console.error(`  ${err.message}`);
+        if (bundlePath) {
+            try {
+                unlinkSync(bundlePath);
+            }
+            catch { /* ignore cleanup errors */ }
         }
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
         process.exit(1);
     }
-    console.log('');
-    // Step 3: Upload
-    console.log('Step 3: Deploying to Skrypt...');
-    const result = await uploadBundle(bundlePath, projectSlug, apiToken);
-    if (!result.success) {
-        console.error('');
-        console.error(`Error: Deployment failed`);
-        console.error(`  ${result.error}`);
-        process.exit(1);
-    }
-    // Success
-    const duration = Math.round((Date.now() - startTime) / 1000);
-    console.log('');
-    console.log('=== Deployment Successful ===');
-    console.log('');
-    console.log(`  URL: ${result.url}`);
-    if (result.customDomain) {
-        console.log(`  Custom domain: ${result.customDomain}`);
-    }
-    console.log(`  Duration: ${duration}s`);
-    console.log('');
-    console.log('Your documentation is now live!');
-    console.log('');
 });

package/dist/commands/generate.js

@@ -7,6 +7,9 @@ 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
  */
@@ -258,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({
@@ -272,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)
@@ -328,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);
+    }
+});