skrypt-ai 0.3.3 → 0.4.0

package/dist/commands/mcp.js

@@ -1,26 +1,9 @@
 import { Command } from 'commander';
-import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'fs';
-import { resolve, join, extname, relative } from 'path';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { resolve, relative } from 'path';
+import { findMdxFiles } from '../utils/files.js';
 import { createServer } from 'http';
 import { requirePro } from '../auth/index.js';
-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 parseDocFile(filePath, basePath) {
     const content = readFileSync(filePath, 'utf-8');
     const relPath = relative(basePath, filePath);
@@ -166,116 +149,136 @@ export const mcpCommand = new Command('mcp')
     .option('-p, --port <port>', 'Server port', '3100')
     .option('-h, --host <host>', 'Server host', 'localhost')
     .option('-o, --output <file>', 'Output manifest to file instead of starting server')
+    .option('-t, --token <token>', 'Bearer token for authenticating MCP requests')
     .action(async (path, options) => {
-    // Pro feature - requires subscription
-    if (!await requirePro('mcp')) {
-        process.exit(1);
-    }
-    const targetPath = resolve(path);
-    if (!existsSync(targetPath)) {
-        console.error(`Error: Path not found: ${targetPath}`);
-        process.exit(1);
-    }
-    // Find and parse all docs
-    const files = findMdxFiles(targetPath);
-    if (files.length === 0) {
-        console.error('No .md or .mdx files found.');
-        process.exit(1);
-    }
-    const docs = files.map(f => parseDocFile(f, targetPath));
-    const projectName = targetPath.split('/').pop() || 'docs';
-    // Output mode: write manifest to file
-    if (options.output) {
-        const manifest = generateMcpManifest(docs, projectName);
-        const outputPath = resolve(options.output);
-        writeFileSync(outputPath, JSON.stringify(manifest, null, 2));
-        console.log(`MCP manifest written to ${outputPath}`);
-        process.exit(0);
-    }
-    // Server mode
-    const port = parseInt(options.port) || 3100;
-    const host = options.host || 'localhost';
-    console.log('skrypt mcp');
-    console.log(`  docs: ${files.length} files`);
-    console.log(`  server: http://${host}:${port}`);
-    console.log('');
-    const manifest = generateMcpManifest(docs, projectName);
-    const server = createServer((req, res) => {
-        const url = new URL(req.url || '/', `http://${host}:${port}`);
-        // CORS headers
-        res.setHeader('Access-Control-Allow-Origin', '*');
-        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
-        if (req.method === 'OPTIONS') {
-            res.writeHead(204);
-            res.end();
-            return;
+    try {
+        // Pro feature - requires subscription
+        if (!await requirePro('mcp')) {
+            process.exit(1);
+        }
+        const targetPath = resolve(path);
+        if (!existsSync(targetPath)) {
+            console.error(`Error: Path not found: ${targetPath}`);
+            process.exit(1);
+        }
+        // Find and parse all docs
+        const files = findMdxFiles(targetPath);
+        if (files.length === 0) {
+            console.error('No .md or .mdx files found.');
+            process.exit(1);
         }
-        // MCP manifest
-        if (url.pathname === '/' || url.pathname === '/manifest') {
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify(manifest, null, 2));
-            return;
+        const docs = files.map(f => parseDocFile(f, targetPath));
+        const projectName = targetPath.split('/').pop() || 'docs';
+        // Output mode: write manifest to file
+        if (options.output) {
+            const manifest = generateMcpManifest(docs, projectName);
+            const outputPath = resolve(options.output);
+            writeFileSync(outputPath, JSON.stringify(manifest, null, 2));
+            console.log(`MCP manifest written to ${outputPath}`);
+            process.exit(0);
         }
-        // List docs
-        if (url.pathname === '/docs' || url.pathname === '/list') {
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({
-                docs: docs.map(d => ({
+        // Server mode
+        const port = Number(options.port) || 3100;
+        const host = options.host || 'localhost';
+        console.log('skrypt mcp');
+        console.log(`  docs: ${files.length} files`);
+        console.log(`  server: http://${host}:${port}`);
+        if (!options.token) {
+            console.warn('Warning: MCP server running without authentication. Use --token to secure.');
+        }
+        console.log('');
+        const manifest = generateMcpManifest(docs, projectName);
+        const server = createServer((req, res) => {
+            const url = new URL(req.url || '/', `http://${host}:${port}`);
+            // CORS headers
+            res.setHeader('Access-Control-Allow-Origin', `http://localhost:${port}`);
+            res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+            res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+            if (req.method === 'OPTIONS') {
+                res.writeHead(204);
+                res.end();
+                return;
+            }
+            // Token authentication
+            if (options.token) {
+                const authHeader = req.headers['authorization'];
+                if (authHeader !== `Bearer ${options.token}`) {
+                    res.writeHead(401, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Unauthorized' }));
+                    return;
+                }
+            }
+            // MCP manifest
+            if (url.pathname === '/' || url.pathname === '/manifest') {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(manifest, null, 2));
+                return;
+            }
+            // List docs
+            if (url.pathname === '/docs' || url.pathname === '/list') {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    docs: docs.map(d => ({
+                        path: d.path,
+                        title: d.title,
+                        description: d.description,
+                    })),
+                }));
+                return;
+            }
+            // Get specific doc
+            if (url.pathname.startsWith('/doc/')) {
+                const docPath = decodeURIComponent(url.pathname.slice(5));
+                const doc = docs.find(d => d.path === docPath || d.path === docPath + '.mdx' || d.path === docPath + '.md');
+                if (doc) {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(doc));
+                    return;
+                }
+                res.writeHead(404, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Document not found' }));
+                return;
+            }
+            // Search docs
+            if (url.pathname === '/search') {
+                const query = url.searchParams.get('q')?.toLowerCase() || '';
+                const results = docs
+                    .filter(d => d.title.toLowerCase().includes(query) ||
+                    d.description.toLowerCase().includes(query) ||
+                    d.content.toLowerCase().includes(query))
+                    .map(d => ({
                     path: d.path,
                     title: d.title,
                     description: d.description,
-                })),
-            }));
-            return;
-        }
-        // Get specific doc
-        if (url.pathname.startsWith('/doc/')) {
-            const docPath = decodeURIComponent(url.pathname.slice(5));
-            const doc = docs.find(d => d.path === docPath || d.path === docPath + '.mdx' || d.path === docPath + '.md');
-            if (doc) {
+                    score: ((d.title.toLowerCase().includes(query) ? 10 : 0) +
+                        (d.description.toLowerCase().includes(query) ? 5 : 0) +
+                        (d.content.toLowerCase().includes(query) ? 1 : 0)),
+                }))
+                    .sort((a, b) => b.score - a.score)
+                    .slice(0, 10);
                 res.writeHead(200, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify(doc));
+                res.end(JSON.stringify({ query, results }));
                 return;
             }
+            // 404
             res.writeHead(404, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'Document not found' }));
-            return;
-        }
-        // Search docs
-        if (url.pathname === '/search') {
-            const query = url.searchParams.get('q')?.toLowerCase() || '';
-            const results = docs
-                .filter(d => d.title.toLowerCase().includes(query) ||
-                d.description.toLowerCase().includes(query) ||
-                d.content.toLowerCase().includes(query))
-                .map(d => ({
-                path: d.path,
-                title: d.title,
-                description: d.description,
-                score: ((d.title.toLowerCase().includes(query) ? 10 : 0) +
-                    (d.description.toLowerCase().includes(query) ? 5 : 0) +
-                    (d.content.toLowerCase().includes(query) ? 1 : 0)),
-            }))
-                .sort((a, b) => b.score - a.score)
-                .slice(0, 10);
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ query, results }));
-            return;
-        }
-        // 404
-        res.writeHead(404, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: 'Not found' }));
-    });
-    server.listen(port, host, () => {
-        console.log(`MCP server running at http://${host}:${port}`);
-        console.log('');
-        console.log('Endpoints:');
-        console.log(`  GET /           - MCP manifest`);
-        console.log(`  GET /docs       - List all documents`);
-        console.log(`  GET /doc/:path  - Get document content`);
-        console.log(`  GET /search?q=  - Search documents`);
-        console.log('');
-        console.log('Press Ctrl+C to stop');
-    });
+            res.end(JSON.stringify({ error: 'Not found' }));
+        });
+        server.listen(port, host, () => {
+            console.log(`MCP server running at http://${host}:${port}`);
+            console.log('');
+            console.log('Endpoints:');
+            console.log(`  GET /           - MCP manifest`);
+            console.log(`  GET /docs       - List all documents`);
+            console.log(`  GET /doc/:path  - Get document content`);
+            console.log(`  GET /search?q=  - Search documents`);
+            console.log('');
+            console.log('Press Ctrl+C to stop');
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${message}`);
+        process.exit(1);
+    }
 });

package/dist/commands/monitor.js

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { execSync } from 'child_process';
+import { execSync, spawnSync } from 'child_process';
 import { existsSync, writeFileSync, readdirSync, statSync, mkdirSync } from 'fs';
 import { resolve, join, dirname } from 'path';
 import { createLLMClient } from '../llm/index.js';
@@ -9,7 +9,14 @@ function getGitChanges(since, repoPath) {
     const changes = [];
     try {
         // Get list of changed files
-        const diffFiles = execSync(`git diff --name-status ${since}`, { cwd: repoPath, encoding: 'utf-8' }).trim();
+        const diffResult = spawnSync('git', ['diff', '--name-status', since], {
+            cwd: repoPath, encoding: 'utf-8'
+        });
+        if (diffResult.status !== 0) {
+            console.error('Failed to get git diff:', diffResult.stderr);
+            return [];
+        }
+        const diffFiles = diffResult.stdout.toString().trim();
         if (!diffFiles)
             return [];
         for (const line of diffFiles.split('\n')) {
@@ -22,7 +29,10 @@ function getGitChanges(since, repoPath) {
             // Get the actual diff
             let diff = '';
             try {
-                diff = execSync(`git diff ${since} -- "${file}"`, { cwd: repoPath, encoding: 'utf-8', maxBuffer: 1024 * 1024 }).slice(0, 5000); // Limit diff size
+                const fileDiffResult = spawnSync('git', ['diff', since, '--', file], {
+                    cwd: repoPath, encoding: 'utf-8', maxBuffer: 1024 * 1024
+                });
+                diff = fileDiffResult.stdout.toString().slice(0, 5000); // Limit diff size
             }
             catch {
                 // File might be binary or too large
@@ -178,114 +188,121 @@ export const monitorCommand = new Command('monitor')
     .option('--create-pr', 'Create a GitHub PR with changes')
     .option('--dry-run', 'Show what would be done without making changes')
     .action(async (repoPath, options) => {
-    // Pro feature - requires subscription
-    if (!await requirePro('monitor')) {
-        process.exit(1);
-    }
-    const resolvedPath = resolve(repoPath);
-    console.log('skrypt monitor');
-    console.log(`  repo: ${resolvedPath}`);
-    console.log(`  since: ${options.since}`);
-    console.log('');
-    // Load config
-    const config = loadConfig();
-    if (options.provider) {
-        config.llm.provider = options.provider;
-    }
-    // Check API key
-    const { ok, envKey } = checkApiKey(config.llm.provider);
-    if (!ok && envKey) {
-        console.error(`Error: ${envKey} required for ${config.llm.provider}`);
-        process.exit(1);
-    }
-    // Step 1: Get git changes
-    console.log('Step 1: Analyzing git changes...');
-    const changes = getGitChanges(options.since || 'HEAD~10', resolvedPath);
-    if (changes.length === 0) {
-        console.log('  No code changes found.');
-        process.exit(0);
-    }
-    const userFacing = changes.filter(c => c.isUserFacing);
-    console.log(`  Found ${changes.length} changed files (${userFacing.length} user-facing)`);
-    if (userFacing.length === 0) {
-        console.log('  No user-facing changes detected. No documentation updates needed.');
-        process.exit(0);
-    }
-    // Step 2: Find existing docs
-    console.log('\nStep 2: Scanning existing documentation...');
-    const docsPath = join(resolvedPath, 'docs');
-    const existingDocs = findExistingDocs(docsPath);
-    console.log(`  Found ${existingDocs.length} existing doc files`);
-    // Step 3: Analyze with AI
-    console.log('\nStep 3: Analyzing changes with AI...');
-    const client = createLLMClient({
-        provider: config.llm.provider,
-        model: config.llm.model,
-    });
-    const suggestions = await analyzeChangesWithAI(changes, existingDocs, client);
-    if (suggestions.length === 0) {
-        console.log('  No documentation updates suggested.');
-        process.exit(0);
-    }
-    console.log(`\n=== Documentation Suggestions (${suggestions.length}) ===\n`);
-    for (const s of suggestions) {
-        const icon = s.action === 'create' ? '➕' : s.action === 'update' ? '📝' : '🗑️';
-        const priority = s.priority === 'high' ? '🔴' : s.priority === 'medium' ? '🟡' : '🟢';
-        console.log(`${icon} ${priority} ${s.file}`);
-        console.log(`   Action: ${s.action.toUpperCase()}`);
-        console.log(`   Reason: ${s.reason}`);
+    try {
+        // Pro feature - requires subscription
+        if (!await requirePro('monitor')) {
+            process.exit(1);
+        }
+        const resolvedPath = resolve(repoPath);
+        console.log('skrypt monitor');
+        console.log(`  repo: ${resolvedPath}`);
+        console.log(`  since: ${options.since}`);
         console.log('');
-    }
-    // Output to file if requested
-    if (options.output) {
-        const outputPath = resolve(options.output);
-        writeFileSync(outputPath, JSON.stringify({ suggestions, changes: userFacing }, null, 2));
-        console.log(`Suggestions saved to: ${outputPath}`);
-    }
-    // Auto-fix if requested
-    if (options.autoFix && !options.dryRun) {
-        console.log('\n=== Auto-generating documentation ===\n');
-        for (const suggestion of suggestions.filter(s => s.action !== 'delete')) {
-            const change = changes.find(c => suggestion.reason.includes(c.file));
-            if (!change)
-                continue;
-            console.log(`Generating: ${suggestion.file}...`);
-            const content = await generateDocContent(suggestion, change, client);
-            if (content) {
-                const docPath = join(docsPath, suggestion.file);
-                mkdirSync(dirname(docPath), { recursive: true });
-                writeFileSync(docPath, content);
-                console.log(`  ✓ Written: ${docPath}`);
-            }
+        // Load config
+        const config = loadConfig();
+        if (options.provider) {
+            config.llm.provider = options.provider;
         }
-    }
-    // Create PR if requested
-    if (options.createPr && !options.dryRun) {
-        console.log('\n=== Creating GitHub PR ===\n');
-        try {
-            // Check if gh CLI is available
-            execSync('gh --version', { stdio: 'ignore' });
-            // Create branch
-            const branchName = `docs/auto-update-${Date.now()}`;
-            execSync(`git checkout -b ${branchName}`, { cwd: resolvedPath });
-            // Stage and commit
-            execSync('git add docs/', { cwd: resolvedPath });
-            execSync(`git commit -m "docs: auto-update documentation for recent changes"`, { cwd: resolvedPath });
-            // Push and create PR
-            execSync(`git push -u origin ${branchName}`, { cwd: resolvedPath });
-            const prUrl = execSync(`gh pr create --title "docs: Auto-update documentation" --body "This PR was automatically generated by Skrypt monitor.\n\n## Changes\n${suggestions.map(s => `- ${s.action}: ${s.file}`).join('\n')}"`, { cwd: resolvedPath, encoding: 'utf-8' }).trim();
-            console.log(`PR created: ${prUrl}`);
+        // Check API key
+        const { ok, envKey } = checkApiKey(config.llm.provider);
+        if (!ok && envKey) {
+            console.error(`Error: ${envKey} required for ${config.llm.provider}`);
+            process.exit(1);
+        }
+        // Step 1: Get git changes
+        console.log('Step 1: Analyzing git changes...');
+        const changes = getGitChanges(options.since || 'HEAD~10', resolvedPath);
+        if (changes.length === 0) {
+            console.log('  No code changes found.');
+            process.exit(0);
+        }
+        const userFacing = changes.filter(c => c.isUserFacing);
+        console.log(`  Found ${changes.length} changed files (${userFacing.length} user-facing)`);
+        if (userFacing.length === 0) {
+            console.log('  No user-facing changes detected. No documentation updates needed.');
+            process.exit(0);
+        }
+        // Step 2: Find existing docs
+        console.log('\nStep 2: Scanning existing documentation...');
+        const docsPath = join(resolvedPath, 'docs');
+        const existingDocs = findExistingDocs(docsPath);
+        console.log(`  Found ${existingDocs.length} existing doc files`);
+        // Step 3: Analyze with AI
+        console.log('\nStep 3: Analyzing changes with AI...');
+        const client = createLLMClient({
+            provider: config.llm.provider,
+            model: config.llm.model,
+        });
+        const suggestions = await analyzeChangesWithAI(changes, existingDocs, client);
+        if (suggestions.length === 0) {
+            console.log('  No documentation updates suggested.');
+            process.exit(0);
+        }
+        console.log(`\n=== Documentation Suggestions (${suggestions.length}) ===\n`);
+        for (const s of suggestions) {
+            const icon = s.action === 'create' ? '➕' : s.action === 'update' ? '📝' : '🗑️';
+            const priority = s.priority === 'high' ? '🔴' : s.priority === 'medium' ? '🟡' : '🟢';
+            console.log(`${icon} ${priority} ${s.file}`);
+            console.log(`   Action: ${s.action.toUpperCase()}`);
+            console.log(`   Reason: ${s.reason}`);
+            console.log('');
+        }
+        // Output to file if requested
+        if (options.output) {
+            const outputPath = resolve(options.output);
+            writeFileSync(outputPath, JSON.stringify({ suggestions, changes: userFacing }, null, 2));
+            console.log(`Suggestions saved to: ${outputPath}`);
         }
-        catch (err) {
-            console.error('Failed to create PR:', err);
+        // Auto-fix if requested
+        if (options.autoFix && !options.dryRun) {
+            console.log('\n=== Auto-generating documentation ===\n');
+            for (const suggestion of suggestions.filter(s => s.action !== 'delete')) {
+                const change = changes.find(c => suggestion.reason.includes(c.file));
+                if (!change)
+                    continue;
+                console.log(`Generating: ${suggestion.file}...`);
+                const content = await generateDocContent(suggestion, change, client);
+                if (content) {
+                    const docPath = join(docsPath, suggestion.file);
+                    mkdirSync(dirname(docPath), { recursive: true });
+                    writeFileSync(docPath, content);
+                    console.log(`  ✓ Written: ${docPath}`);
+                }
+            }
+        }
+        // Create PR if requested
+        if (options.createPr && !options.dryRun) {
+            console.log('\n=== Creating GitHub PR ===\n');
+            try {
+                // Check if gh CLI is available
+                execSync('gh --version', { stdio: 'ignore' });
+                // Create branch
+                const branchName = `docs/auto-update-${Date.now()}`;
+                execSync(`git checkout -b ${branchName}`, { cwd: resolvedPath });
+                // Stage and commit
+                execSync('git add docs/', { cwd: resolvedPath });
+                execSync(`git commit -m "docs: auto-update documentation for recent changes"`, { cwd: resolvedPath });
+                // Push and create PR
+                execSync(`git push -u origin ${branchName}`, { cwd: resolvedPath });
+                const prUrl = execSync(`gh pr create --title "docs: Auto-update documentation" --body "This PR was automatically generated by Skrypt monitor.\n\n## Changes\n${suggestions.map(s => `- ${s.action}: ${s.file}`).join('\n')}"`, { cwd: resolvedPath, encoding: 'utf-8' }).trim();
+                console.log(`PR created: ${prUrl}`);
+            }
+            catch (err) {
+                console.error('Failed to create PR:', err);
+            }
         }
+        // Summary
+        console.log('\n=== Summary ===');
+        console.log(`  Changes analyzed: ${changes.length}`);
+        console.log(`  User-facing: ${userFacing.length}`);
+        console.log(`  Suggestions: ${suggestions.length}`);
+        console.log(`    Create: ${suggestions.filter(s => s.action === 'create').length}`);
+        console.log(`    Update: ${suggestions.filter(s => s.action === 'update').length}`);
+        console.log(`    Delete: ${suggestions.filter(s => s.action === 'delete').length}`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${message}`);
+        process.exit(1);
     }
-    // Summary
-    console.log('\n=== Summary ===');
-    console.log(`  Changes analyzed: ${changes.length}`);
-    console.log(`  User-facing: ${userFacing.length}`);
-    console.log(`  Suggestions: ${suggestions.length}`);
-    console.log(`    Create: ${suggestions.filter(s => s.action === 'create').length}`);
-    console.log(`    Update: ${suggestions.filter(s => s.action === 'update').length}`);
-    console.log(`    Delete: ${suggestions.filter(s => s.action === 'delete').length}`);
 });

package/dist/commands/review-pr.js

@@ -8,7 +8,7 @@ export const reviewPRCommand = new Command('review-pr')
     .option('--token <token>', 'GitHub token (or use GITHUB_TOKEN env var)')
     .action(async (prUrl, options) => {
     // Parse PR URL
-    const urlMatch = prUrl.match(/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/);
+    const urlMatch = prUrl.match(/^https:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/);
     if (!urlMatch) {
         console.error('Error: Invalid PR URL format');
         console.error('Expected: https://github.com/owner/repo/pull/123');

package/dist/commands/sdk.js

@@ -115,7 +115,7 @@ async function parseOpenAPISpec(content) {
         // Try YAML - dynamic import to avoid require()
         try {
             const yaml = await import('js-yaml');
-            return yaml.load(content);
+            return yaml.load(content, { schema: yaml.JSON_SCHEMA });
         }
         catch {
             throw new Error('Failed to parse spec. For YAML files, install js-yaml: npm i js-yaml');

package/dist/config/loader.js

@@ -30,8 +30,27 @@ export function loadConfig(configPath) {
     return DEFAULT_CONFIG;
 }
 function parseConfigFile(filepath) {
-    const content = readFileSync(filepath, 'utf-8');
-    const parsed = yaml.load(content);
+    let content;
+    try {
+        content = readFileSync(filepath, 'utf-8');
+    }
+    catch (err) {
+        throw new Error(`Could not read config file: ${filepath}. ` +
+            (err instanceof Error ? err.message : String(err)));
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(content, { schema: yaml.JSON_SCHEMA });
+    }
+    catch (err) {
+        throw new Error(`Config file has invalid YAML: ${filepath}. ` +
+            `Please check the syntax and try again. ` +
+            (err instanceof Error ? err.message : String(err)));
+    }
+    if (parsed === null || parsed === undefined || typeof parsed !== 'object') {
+        throw new Error(`Config file is empty or not a valid YAML object: ${filepath}. ` +
+            `Run 'skrypt init' to generate a valid config.`);
+    }
     // Merge with defaults
     return mergeConfig(DEFAULT_CONFIG, parsed);
 }

package/dist/generator/organizer.d.ts

@@ -17,13 +17,16 @@ export declare function detectCrossReferences(docs: GeneratedDoc[]): CrossRefere
 export declare function getCrossRefsForElement(elementName: string, allRefs: CrossReference[]): CrossReference[];
 /**
  * Build navigation structure from topics
+ * @internal
  */
 export declare function buildNavigation(topics: Topic[]): NavigationItem[];
 /**
  * Generate a sidebar configuration (works with multiple doc platforms)
+ * @internal
  */
 export declare function generateSidebarConfig(topics: Topic[]): object;
 /**
  * Merge user config with defaults
+ * @internal
  */
 export declare function mergeTopicConfig(userConfig: Partial<TopicConfig>, defaults?: TopicConfig): TopicConfig;

package/dist/generator/organizer.js

@@ -1,3 +1,4 @@
+import { slugify } from '../utils/files.js';
 /**
  * Default topic configuration with common patterns
  */
@@ -173,6 +174,7 @@ export function getCrossRefsForElement(elementName, allRefs) {
 }
 /**
  * Build navigation structure from topics
+ * @internal
  */
 export function buildNavigation(topics) {
     return topics.map(topic => ({
@@ -186,6 +188,7 @@ export function buildNavigation(topics) {
 }
 /**
  * Generate a sidebar configuration (works with multiple doc platforms)
+ * @internal
  */
 export function generateSidebarConfig(topics) {
     return {
@@ -203,17 +206,9 @@ function titleCase(str) {
         .replace(/-/g, ' ')
         .replace(/\b\w/g, c => c.toUpperCase());
 }
-/**
- * Convert string to URL-safe slug
- */
-function slugify(str) {
-    return str
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-|-$/g, '');
-}
 /**
  * Merge user config with defaults
+ * @internal
  */
 export function mergeTopicConfig(userConfig, defaults = DEFAULT_TOPIC_CONFIG) {
     return {