skrypt-ai 0.3.4 → 0.4.0

package/dist/commands/generate.js

@@ -102,219 +102,226 @@ export const generateCommand = new Command('generate')
     .option('--llms-txt', 'Generate llms.txt for Answer Engine Optimization (AEO)')
     .option('--project-name <name>', 'Project name for llms.txt header')
     .action(async (source, options) => {
-    const startTime = Date.now();
-    // Load config (file or defaults)
-    const config = loadConfig(options.config);
-    // CLI flags override config
-    if (source)
-        config.source.path = source;
-    if (options.output)
-        config.output.path = options.output;
-    if (options.provider) {
-        config.llm.provider = options.provider;
-        // Use provider's default model unless explicitly specified
-        if (!options.model) {
-            config.llm.model = DEFAULT_MODELS[config.llm.provider];
+    try {
+        const startTime = Date.now();
+        // Load config (file or defaults)
+        const config = loadConfig(options.config);
+        // CLI flags override config
+        if (source)
+            config.source.path = source;
+        if (options.output)
+            config.output.path = options.output;
+        if (options.provider) {
+            config.llm.provider = options.provider;
+            // Use provider's default model unless explicitly specified
+            if (!options.model) {
+                config.llm.model = DEFAULT_MODELS[config.llm.provider];
+            }
         }
-    }
-    if (options.model)
-        config.llm.model = options.model;
-    if (options.baseUrl)
-        config.llm.baseUrl = options.baseUrl;
-    // Validate
-    const errors = validateConfig(config);
-    if (errors.length > 0) {
-        console.error('Config errors:');
-        errors.forEach(e => console.error(`  - ${e}`));
-        process.exit(1);
-    }
-    // Check for API key (not needed for Ollama or dry-run)
-    if (!options.dryRun) {
-        const { ok, envKey } = checkApiKey(config.llm.provider);
-        if (!ok && envKey) {
-            console.error(`Error: ${envKey} environment variable required for ${config.llm.provider}`);
+        if (options.model)
+            config.llm.model = options.model;
+        if (options.baseUrl)
+            config.llm.baseUrl = options.baseUrl;
+        // Validate
+        const errors = validateConfig(config);
+        if (errors.length > 0) {
+            console.error('Config errors:');
+            errors.forEach(e => console.error(`  - ${e}`));
             process.exit(1);
         }
-    }
-    console.log('skrypt generate');
-    console.log(`  source:   ${config.source.path}`);
-    console.log(`  output:   ${config.output.path}`);
-    console.log(`  provider: ${config.llm.provider}`);
-    console.log(`  model:    ${config.llm.model}`);
-    if (config.llm.baseUrl) {
-        console.log(`  base url: ${config.llm.baseUrl}`);
-    }
-    console.log('');
-    // Check source exists
-    const sourcePath = resolve(config.source.path);
-    if (!existsSync(sourcePath)) {
-        console.error(`Error: Source directory not found: ${sourcePath}`);
-        process.exit(1);
-    }
-    // Step 1: Scan source code
-    console.log('Step 1: Scanning source code...');
-    const scanResult = await scanDirectory(sourcePath, {
-        include: config.source.include,
-        exclude: config.source.exclude,
-        onProgress: (current, total, file) => {
-            process.stdout.write(`\r  [${current}/${total}] ${file.slice(-50).padStart(50)}`);
+        // Check for API key (not needed for Ollama or dry-run)
+        if (!options.dryRun) {
+            const { ok, envKey } = checkApiKey(config.llm.provider);
+            if (!ok && envKey) {
+                console.error(`Error: ${envKey} environment variable required for ${config.llm.provider}`);
+                process.exit(1);
+            }
         }
-    });
-    console.log('');
-    if (scanResult.errors.length > 0) {
-        console.log('\n  Scan warnings:');
-        scanResult.errors.slice(0, 5).forEach(e => console.log(`    - ${e}`));
-        if (scanResult.errors.length > 5) {
-            console.log(`    ... and ${scanResult.errors.length - 5} more`);
+        console.log('skrypt generate');
+        console.log(`  source:   ${config.source.path}`);
+        console.log(`  output:   ${config.output.path}`);
+        console.log(`  provider: ${config.llm.provider}`);
+        console.log(`  model:    ${config.llm.model}`);
+        if (config.llm.baseUrl) {
+            console.log(`  base url: ${config.llm.baseUrl}`);
         }
-    }
-    console.log(`\n  Found ${scanResult.totalElements} API elements in ${scanResult.files.length} files`);
-    if (scanResult.totalElements === 0) {
-        console.log('  No API elements found. Nothing to generate.');
-        process.exit(0);
-    }
-    // Collect all elements
-    let allElements = [];
-    for (const file of scanResult.files) {
-        for (const el of file.elements) {
-            allElements.push(el);
+        console.log('');
+        // Check source exists
+        const sourcePath = resolve(config.source.path);
+        if (!existsSync(sourcePath)) {
+            console.error(`Error: Source directory not found: ${sourcePath}`);
+            process.exit(1);
         }
-    }
-    // Apply privacy filters
-    const initialCount = allElements.length;
-    // 1. --public-only: filter to exported/public APIs only
-    if (options.publicOnly) {
-        allElements = allElements.filter(el => el.isExported === true || el.isPublic === true);
-        console.log(`  --public-only: filtered to ${allElements.length} exported APIs`);
-    }
-    // 2. Load .skryptignore patterns
-    const ignorePatterns = readIgnorePatterns(sourcePath);
-    if (ignorePatterns.length > 0) {
-        console.log(`  .skryptignore: loaded ${ignorePatterns.length} patterns`);
-    }
-    // 3. Combine with --exclude patterns
-    const excludePatterns = [...ignorePatterns, ...(options.exclude || [])];
-    if (excludePatterns.length > 0) {
-        allElements = allElements.filter(el => !shouldExcludeElement(el, excludePatterns));
-        if (options.exclude?.length) {
-            console.log(`  --exclude: applied ${options.exclude.length} additional patterns`);
+        // Step 1: Scan source code
+        console.log('Step 1: Scanning source code...');
+        const scanResult = await scanDirectory(sourcePath, {
+            include: config.source.include,
+            exclude: config.source.exclude,
+            onProgress: (current, total, file) => {
+                process.stdout.write(`\r  [${current}/${total}] ${file.slice(-50).padStart(50)}`);
+            }
+        });
+        console.log('');
+        if (scanResult.errors.length > 0) {
+            console.log('\n  Scan warnings:');
+            scanResult.errors.slice(0, 5).forEach(e => console.log(`    - ${e}`));
+            if (scanResult.errors.length > 5) {
+                console.log(`    ... and ${scanResult.errors.length - 5} more`);
+            }
         }
-    }
-    if (initialCount !== allElements.length) {
-        console.log(`  Filtered: ${initialCount} -> ${allElements.length} elements`);
-    }
-    // Show summary by kind
-    const byKind = {};
-    for (const el of allElements) {
-        byKind[el.kind] = (byKind[el.kind] || 0) + 1;
-    }
-    const pluralize = (word, count) => {
-        if (count === 1)
-            return word;
-        if (word === 'class')
-            return 'classes';
-        return word + 's';
-    };
-    console.log('  ' + Object.entries(byKind).map(([k, v]) => `${v} ${pluralize(k, v)}`).join(', '));
-    // Dry run - stop here
-    if (options.dryRun) {
-        console.log('\n[dry run - stopping before generation]');
-        process.exit(0);
-    }
-    // Step 2: Generate docs
-    console.log('\nStep 2: Generating documentation...');
-    const client = createLLMClient({
-        provider: config.llm.provider,
-        model: config.llm.model,
-        baseUrl: config.llm.baseUrl
-    });
-    let lastElement = '';
-    const multiLanguage = options.multiLang ?? false;
-    if (multiLanguage) {
-        console.log('  mode: multi-language (TypeScript + Python)');
-    }
-    const docs = await generateForElements(allElements, client, {
-        multiLanguage,
-        onProgress: (progress) => {
-            if (progress.element !== lastElement) {
-                if (lastElement)
-                    console.log('');
-                lastElement = progress.element;
+        console.log(`\n  Found ${scanResult.totalElements} API elements in ${scanResult.files.length} files`);
+        if (scanResult.totalElements === 0) {
+            console.log('  No API elements found. Nothing to generate.');
+            process.exit(0);
+        }
+        // Collect all elements
+        let allElements = [];
+        for (const file of scanResult.files) {
+            for (const el of file.elements) {
+                allElements.push(el);
             }
-            process.stdout.write(`\r  [${progress.current}/${progress.total}] ${progress.element}: ${progress.status}`.padEnd(80));
         }
-    });
-    console.log('\n');
-    // Step 3: Write output
-    console.log('Step 3: Writing documentation...');
-    const outputPath = resolve(config.output.path);
-    let filesWritten;
-    let totalDocs;
-    if (options.byTopic) {
-        console.log('  mode: by-topic (grouped by concept)');
-        const result = await writeDocsByTopic(docs, outputPath);
-        filesWritten = result.filesWritten;
-        totalDocs = result.totalDocs;
-        console.log(`  topics: ${result.topics.map(t => t.name).join(', ')}`);
-    }
-    else {
-        // Default: file-based output
-        const fileResults = groupDocsByFile(docs);
-        const result = await writeDocsToDirectory(fileResults, outputPath, sourcePath);
-        filesWritten = result.filesWritten;
-        totalDocs = result.totalDocs;
-    }
-    const errorCount = docs.filter(d => d.error).length;
-    const duration = Math.round((Date.now() - startTime) / 1000);
-    console.log(`\n  Wrote ${filesWritten} documentation files to ${outputPath}`);
-    // Copy OpenAPI spec (provided or auto-detected)
-    let specPath = options.openapi ? resolve(options.openapi) : null;
-    // Auto-detect if not provided
-    if (!specPath) {
-        const detected = findOpenAPISpec(sourcePath);
-        if (detected) {
-            specPath = detected;
-            console.log(`\n  Auto-detected OpenAPI spec: ${basename(detected)}`);
+        // Apply privacy filters
+        const initialCount = allElements.length;
+        // 1. --public-only: filter to exported/public APIs only
+        if (options.publicOnly) {
+            allElements = allElements.filter(el => el.isExported === true || el.isPublic === true);
+            console.log(`  --public-only: filtered to ${allElements.length} exported APIs`);
         }
-    }
-    if (specPath) {
-        if (existsSync(specPath)) {
-            const specFilename = basename(specPath);
-            const contentDir = dirname(outputPath);
-            const destPath = resolve(contentDir, specFilename);
-            mkdirSync(dirname(destPath), { recursive: true });
-            copyFileSync(specPath, destPath);
-            console.log(`  Copied OpenAPI spec: ${specFilename} -> ${destPath}`);
-            console.log('  API Playground will be available at /reference');
+        // 2. Load .skryptignore patterns
+        const ignorePatterns = readIgnorePatterns(sourcePath);
+        if (ignorePatterns.length > 0) {
+            console.log(`  .skryptignore: loaded ${ignorePatterns.length} patterns`);
         }
-        else if (options.openapi) {
-            console.log(`\n  Warning: OpenAPI spec not found: ${specPath}`);
+        // 3. Combine with --exclude patterns
+        const excludePatterns = [...ignorePatterns, ...(options.exclude || [])];
+        if (excludePatterns.length > 0) {
+            allElements = allElements.filter(el => !shouldExcludeElement(el, excludePatterns));
+            if (options.exclude?.length) {
+                console.log(`  --exclude: applied ${options.exclude.length} additional patterns`);
+            }
         }
-    }
-    // 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)}`
+        if (initialCount !== allElements.length) {
+            console.log(`  Filtered: ${initialCount} -> ${allElements.length} elements`);
+        }
+        // Show summary by kind
+        const byKind = {};
+        for (const el of allElements) {
+            byKind[el.kind] = (byKind[el.kind] || 0) + 1;
+        }
+        const pluralize = (word, count) => {
+            if (count === 1)
+                return word;
+            if (word === 'class')
+                return 'classes';
+            return word + 's';
+        };
+        console.log('  ' + Object.entries(byKind).map(([k, v]) => `${v} ${pluralize(k, v)}`).join(', '));
+        // Dry run - stop here
+        if (options.dryRun) {
+            console.log('\n[dry run - stopping before generation]');
+            process.exit(0);
+        }
+        // Step 2: Generate docs
+        console.log('\nStep 2: Generating documentation...');
+        const client = createLLMClient({
+            provider: config.llm.provider,
+            model: config.llm.model,
+            baseUrl: config.llm.baseUrl
         });
-        console.log(`\n  Generated llms.txt and llms-full.md for AEO`);
-    }
-    console.log('\n=== Summary ===');
-    console.log(`  Total elements: ${totalDocs}`);
-    console.log(`  Generated:      ${totalDocs - errorCount}`);
-    if (errorCount > 0) {
-        console.log(`  Errors:         ${errorCount}`);
-    }
-    console.log(`  Duration:       ${duration}s`);
-    console.log(`  Output:         ${outputPath}`);
-    if (errorCount > 0) {
-        console.log('\n  Elements with errors:');
-        docs.filter(d => d.error).slice(0, 10).forEach(d => {
-            console.log(`    - ${d.element.name}: ${d.error?.slice(0, 50)}`);
+        let lastElement = '';
+        const multiLanguage = options.multiLang ?? false;
+        if (multiLanguage) {
+            console.log('  mode: multi-language (TypeScript + Python)');
+        }
+        const docs = await generateForElements(allElements, client, {
+            multiLanguage,
+            onProgress: (progress) => {
+                if (progress.element !== lastElement) {
+                    if (lastElement)
+                        console.log('');
+                    lastElement = progress.element;
+                }
+                process.stdout.write(`\r  [${progress.current}/${progress.total}] ${progress.element}: ${progress.status}`.padEnd(80));
+            }
         });
-        if (errorCount > 10) {
-            console.log(`    ... and ${errorCount - 10} more`);
+        console.log('\n');
+        // Step 3: Write output
+        console.log('Step 3: Writing documentation...');
+        const outputPath = resolve(config.output.path);
+        let filesWritten;
+        let totalDocs;
+        if (options.byTopic) {
+            console.log('  mode: by-topic (grouped by concept)');
+            const result = await writeDocsByTopic(docs, outputPath);
+            filesWritten = result.filesWritten;
+            totalDocs = result.totalDocs;
+            console.log(`  topics: ${result.topics.map(t => t.name).join(', ')}`);
+        }
+        else {
+            // Default: file-based output
+            const fileResults = groupDocsByFile(docs);
+            const result = await writeDocsToDirectory(fileResults, outputPath, sourcePath);
+            filesWritten = result.filesWritten;
+            totalDocs = result.totalDocs;
         }
+        const errorCount = docs.filter(d => d.error).length;
+        const duration = Math.round((Date.now() - startTime) / 1000);
+        console.log(`\n  Wrote ${filesWritten} documentation files to ${outputPath}`);
+        // Copy OpenAPI spec (provided or auto-detected)
+        let specPath = options.openapi ? resolve(options.openapi) : null;
+        // Auto-detect if not provided
+        if (!specPath) {
+            const detected = findOpenAPISpec(sourcePath);
+            if (detected) {
+                specPath = detected;
+                console.log(`\n  Auto-detected OpenAPI spec: ${basename(detected)}`);
+            }
+        }
+        if (specPath) {
+            if (existsSync(specPath)) {
+                const specFilename = basename(specPath);
+                const contentDir = dirname(outputPath);
+                const destPath = resolve(contentDir, specFilename);
+                mkdirSync(dirname(destPath), { recursive: true });
+                copyFileSync(specPath, destPath);
+                console.log(`  Copied OpenAPI spec: ${specFilename} -> ${destPath}`);
+                console.log('  API Playground will be available at /reference');
+            }
+            else if (options.openapi) {
+                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)}`
+            });
+            console.log(`\n  Generated llms.txt and llms-full.md for AEO`);
+        }
+        console.log('\n=== Summary ===');
+        console.log(`  Total elements: ${totalDocs}`);
+        console.log(`  Generated:      ${totalDocs - errorCount}`);
+        if (errorCount > 0) {
+            console.log(`  Errors:         ${errorCount}`);
+        }
+        console.log(`  Duration:       ${duration}s`);
+        console.log(`  Output:         ${outputPath}`);
+        if (errorCount > 0) {
+            console.log('\n  Elements with errors:');
+            docs.filter(d => d.error).slice(0, 10).forEach(d => {
+                console.log(`    - ${d.element.name}: ${d.error?.slice(0, 50)}`);
+            });
+            if (errorCount > 10) {
+                console.log(`    ... and ${errorCount - 10} more`);
+            }
+        }
+        console.log('\nDone!');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${message}`);
+        process.exit(1);
     }
-    console.log('\nDone!');
 });

package/dist/commands/i18n.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'fs';
-import { resolve, join, extname, relative } from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { resolve, join, relative } from 'path';
+import { findMdxFiles } from '../utils/files.js';
 const CONFIG_FILE = 'skrypt.i18n.json';
 function loadI18nConfig(docsPath) {
     const configPath = join(docsPath, CONFIG_FILE);
@@ -13,24 +14,6 @@ function saveI18nConfig(docsPath, config) {
     const configPath = join(docsPath, CONFIG_FILE);
     writeFileSync(configPath, JSON.stringify(config, null, 2));
 }
-function findMdxFiles(dir) {
-    const files = [];
-    function walk(currentDir) {
-        const entries = readdirSync(currentDir);
-        for (const entry of entries) {
-            const fullPath = join(currentDir, entry);
-            const stat = statSync(fullPath);
-            if (stat.isDirectory() && !entry.startsWith('.') && entry !== 'node_modules') {
-                walk(fullPath);
-            }
-            else if (stat.isFile() && (extname(entry) === '.mdx' || extname(entry) === '.md')) {
-                files.push(fullPath);
-            }
-        }
-    }
-    walk(dir);
-    return files;
-}
 export const i18nCommand = new Command('i18n')
     .description('Manage documentation translations');
 i18nCommand

package/dist/commands/init.js

@@ -9,49 +9,56 @@ export const initCommand = new Command('init')
     .argument('[directory]', 'Target directory', '.')
     .option('--name <name>', 'Project name', 'my-docs')
     .action(async (directory, options) => {
-    const targetDir = resolve(directory);
-    console.log('skrypt init');
-    console.log(`  directory: ${targetDir}`);
-    console.log(`  name:      ${options.name}`);
-    console.log('');
-    // Check if directory exists and is not empty
-    if (existsSync(targetDir)) {
-        const files = readdirSync(targetDir);
-        if (files.length > 0 && !files.every((f) => f.startsWith('.'))) {
-            console.error('Error: Target directory is not empty');
+    try {
+        const targetDir = resolve(directory);
+        console.log('skrypt init');
+        console.log(`  directory: ${targetDir}`);
+        console.log(`  name:      ${options.name}`);
+        console.log('');
+        // Check if directory exists and is not empty
+        if (existsSync(targetDir)) {
+            const files = readdirSync(targetDir);
+            if (files.length > 0 && !files.every((f) => f.startsWith('.'))) {
+                console.error('Error: Target directory is not empty');
+                process.exit(1);
+            }
+        }
+        // Create target directory
+        mkdirSync(targetDir, { recursive: true });
+        // Copy template (from dist/template/, one level up from dist/commands/)
+        const templateDir = join(__dirname, '..', 'template');
+        if (!existsSync(templateDir)) {
+            console.error('Error: Template not found. Please reinstall skrypt.');
             process.exit(1);
         }
+        console.log('Creating documentation site...');
+        cpSync(templateDir, targetDir, { recursive: true });
+        // Update package.json with project name
+        const packageJsonPath = join(targetDir, 'package.json');
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+        packageJson.name = options.name;
+        writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
+        // Update docs.json with project name
+        const docsJsonPath = join(targetDir, 'docs.json');
+        const docsJson = JSON.parse(readFileSync(docsJsonPath, 'utf-8'));
+        docsJson.name = options.name;
+        docsJson.description = `${options.name} documentation`;
+        writeFileSync(docsJsonPath, JSON.stringify(docsJson, null, 2));
+        console.log('');
+        console.log('Done! Next steps:');
+        console.log('');
+        console.log(`  cd ${directory === '.' ? '.' : directory}`);
+        console.log('  npm install');
+        console.log('  npm run dev');
+        console.log('');
+        console.log('Then open http://localhost:3000 to see your docs.');
+        console.log('');
+        console.log('To generate API documentation:');
+        console.log('  skrypt generate ./src -o ./content/docs');
     }
-    // Create target directory
-    mkdirSync(targetDir, { recursive: true });
-    // Copy template (from dist/template/, one level up from dist/commands/)
-    const templateDir = join(__dirname, '..', 'template');
-    if (!existsSync(templateDir)) {
-        console.error('Error: Template not found. Please reinstall skrypt.');
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${message}`);
         process.exit(1);
     }
-    console.log('Creating documentation site...');
-    cpSync(templateDir, targetDir, { recursive: true });
-    // Update package.json with project name
-    const packageJsonPath = join(targetDir, 'package.json');
-    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
-    packageJson.name = options.name;
-    writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
-    // Update docs.json with project name
-    const docsJsonPath = join(targetDir, 'docs.json');
-    const docsJson = JSON.parse(readFileSync(docsJsonPath, 'utf-8'));
-    docsJson.name = options.name;
-    docsJson.description = `${options.name} documentation`;
-    writeFileSync(docsJsonPath, JSON.stringify(docsJson, null, 2));
-    console.log('');
-    console.log('Done! Next steps:');
-    console.log('');
-    console.log(`  cd ${directory === '.' ? '.' : directory}`);
-    console.log('  npm install');
-    console.log('  npm run dev');
-    console.log('');
-    console.log('Then open http://localhost:3000 to see your docs.');
-    console.log('');
-    console.log('To generate API documentation:');
-    console.log('  skrypt generate ./src -o ./content/docs');
 });

package/dist/commands/lint.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
-import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
-import { resolve, join, extname } from 'path';
+import { existsSync, readFileSync, statSync } from 'fs';
+import { resolve } from 'path';
+import { findMdxFiles } from '../utils/files.js';
 const RULES = {
     'heading-structure': {
         description: 'Headings should follow proper hierarchy (h1 > h2 > h3)',
@@ -35,24 +36,6 @@ const RULES = {
         severity: 'warning',
     },
 };
-function findMdxFiles(dir) {
-    const files = [];
-    function walk(currentDir) {
-        const entries = readdirSync(currentDir);
-        for (const entry of entries) {
-            const fullPath = join(currentDir, entry);
-            const stat = statSync(fullPath);
-            if (stat.isDirectory() && !entry.startsWith('.') && entry !== 'node_modules') {
-                walk(fullPath);
-            }
-            else if (stat.isFile() && (extname(entry) === '.mdx' || extname(entry) === '.md')) {
-                files.push(fullPath);
-            }
-        }
-    }
-    walk(dir);
-    return files;
-}
 function lintFile(filePath) {
     const content = readFileSync(filePath, 'utf-8');
     const lines = content.split('\n');