skrypt-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 autodocs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+# skrypt
+
+AI-powered documentation generator with code examples.
+
+Scans your codebase, extracts API signatures, and generates beautiful documentation with working code examples.
+
+## Features
+
+- **Multi-language scanning**: TypeScript, Python, Go, Rust
+- **AI-generated docs**: Clear descriptions, parameters, return types
+- **Code examples**: Working examples in TypeScript and Python
+- **Topic organization**: Group elements by concept, not file
+- **MDX output**: Works with any doc platform
+- **Doc site template**: Beautiful, searchable documentation site
+
+## Installation
+
+```bash
+npm install -g skrypt
+```
+
+## Quick Start
+
+### 1. Initialize a documentation site
+
+```bash
+skrypt init my-docs
+cd my-docs
+npm install
+```
+
+### 2. Generate API documentation
+
+```bash
+skrypt generate ../my-project/src -o ./content/docs
+```
+
+### 3. Start the dev server
+
+```bash
+npm run dev
+```
+
+Open http://localhost:3000 to see your docs.
+
+## CLI Commands
+
+### `skrypt init [directory]`
+
+Initialize a new documentation site.
+
+```bash
+skrypt init my-docs --name "My API Docs"
+```
+
+Options:
+- `--name <name>` - Project name (default: "my-docs")
+
+### `skrypt generate <source>`
+
+Generate documentation from source code.
+
+```bash
+skrypt generate ./src -o ./docs
+
+# Multi-language examples
+skrypt generate ./src -o ./docs --multi-lang
+
+# Organize by topic
+skrypt generate ./src -o ./docs --by-topic
+```
+
+Options:
+- `-o, --output <dir>` - Output directory
+- `-c, --config <file>` - Config file path
+- `--provider <name>` - LLM provider (deepseek, openai, anthropic, google, ollama, openrouter)
+- `--model <name>` - LLM model name
+- `--multi-lang` - Generate TypeScript + Python examples
+- `--by-topic` - Organize by topic instead of file
+- `--dry-run` - Scan only, don't generate
+- `--public-only` - Only document exported/public APIs
+- `--exclude <patterns...>` - Exclude patterns (files or `name:pattern`)
+- `--llms-txt` - Generate llms.txt for Answer Engine Optimization
+- `--project-name <name>` - Project name for llms.txt header
+- `--openapi <file>` - Include OpenAPI spec for API Playground
+
+## Privacy Controls
+
+Prevent internal code from being documented:
+
+```bash
+# Only document exported APIs
+skrypt generate ./src --public-only
+
+# Exclude specific patterns
+skrypt generate ./src --exclude "**/internal/**" "name:_private*"
+```
+
+Create `.skryptignore` in your source directory:
+
+```gitignore
+# Exclude test files
+**/*.test.ts
+**/*.spec.ts
+
+# Exclude internal modules
+**/internal/**
+
+# Exclude by function name (regex supported)
+name:_privateHelper
+name:__internal.*
+```
+
+## Answer Engine Optimization (AEO)
+
+Generate `llms.txt` for AI search engines:
+
+```bash
+skrypt generate ./src --llms-txt --project-name "My API"
+```
+
+This creates:
+- `llms.txt` - Condensed API summary for LLMs
+- `llms-full.md` - Full API reference in LLM-friendly format
+
+## Configuration
+
+Create `.skrypt.yaml` in your project:
+
+```yaml
+version: 1
+
+source:
+  path: ./src
+  include: ["**/*.ts", "**/*.py"]
+  exclude: ["**/node_modules/**"]
+
+output:
+  path: ./docs
+  format: mdx
+
+llm:
+  provider: deepseek
+  model: deepseek-v3
+```
+
+## Doc Site Features
+
+The generated documentation site includes:
+
+- **Search**: Full-text search across all docs
+- **Syntax highlighting**: Beautiful code blocks with Shiki
+- **MDX components**: Cards, Tabs, CodeGroup, Callouts, Accordions, Steps
+- **Dark mode**: Automatic dark/light theme switching
+- **Responsive**: Works on all device sizes
+
+## MDX Components
+
+Use these components in your MDX files:
+
+```mdx
+<CardGroup cols={2}>
+  <Card title="Getting Started" icon="Zap" href="/docs/quickstart">
+    Get up and running in 5 minutes
+  </Card>
+</CardGroup>
+
+<Info title="Note">
+  Important information here.
+</Info>
+
+<CodeGroup>
+\`\`\`typescript
+const client = new Client()
+\`\`\`
+
+\`\`\`python
+client = Client()
+\`\`\`
+</CodeGroup>
+
+<Steps>
+  <Step title="Install">Install the package</Step>
+  <Step title="Configure">Set up your config</Step>
+</Steps>
+```
+
+## Environment Variables
+
+Set API keys for your LLM provider:
+
+```bash
+export DEEPSEEK_API_KEY=your-key
+export OPENAI_API_KEY=your-key
+export ANTHROPIC_API_KEY=your-key
+```
+
+## License
+
+MIT

package/dist/autofix/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Auto-fix Broken Code Examples
+ *
+ * Uses LLM to automatically fix code examples that fail validation.
+ * - Free tier: 3 fix attempts per example
+ * - Pro tier: 10 fix attempts per example
+ */
+import { LLMClient } from '../llm/index.js';
+export interface CodeExample {
+    code: string;
+    language: string;
+    context: string;
+}
+export interface FixResult {
+    success: boolean;
+    fixedCode: string;
+    iterations: number;
+    errors: string[];
+    explanation?: string;
+}
+export interface AutoFixOptions {
+    maxIterations?: number;
+    validateFn?: (code: string) => Promise<ValidationResult>;
+    language?: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    output?: string;
+}
+/**
+ * Auto-fix a code example using LLM
+ */
+export declare function autoFixExample(example: CodeExample, client: LLMClient, options?: AutoFixOptions): Promise<FixResult>;
+/**
+ * Batch auto-fix multiple examples
+ */
+export declare function autoFixBatch(examples: CodeExample[], client: LLMClient, options?: AutoFixOptions): Promise<Map<number, FixResult>>;
+/**
+ * Create a TypeScript validator using tsc
+ */
+export declare function createTypeScriptValidator(): (code: string) => Promise<ValidationResult>;
+/**
+ * Create a Python validator (requires python3 in PATH)
+ */
+export declare function createPythonValidator(): (code: string) => Promise<ValidationResult>;

package/dist/autofix/index.js

@@ -0,0 +1,240 @@
+/**
+ * Auto-fix Broken Code Examples
+ *
+ * Uses LLM to automatically fix code examples that fail validation.
+ * - Free tier: 3 fix attempts per example
+ * - Pro tier: 10 fix attempts per example
+ */
+/**
+ * Default TypeScript/JavaScript validator using eval
+ */
+async function defaultValidator(code) {
+    try {
+        // Basic syntax check - try to parse as function
+        new Function(code);
+        return { valid: true, errors: [] };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            valid: false,
+            errors: [message],
+        };
+    }
+}
+/**
+ * Auto-fix a code example using LLM
+ */
+export async function autoFixExample(example, client, options = {}) {
+    const maxIterations = options.maxIterations ?? 3;
+    const validateFn = options.validateFn ?? defaultValidator;
+    const language = options.language ?? example.language;
+    let currentCode = example.code;
+    const allErrors = [];
+    let iterations = 0;
+    // First, validate the original code
+    const initialValidation = await validateFn(currentCode);
+    if (initialValidation.valid) {
+        return {
+            success: true,
+            fixedCode: currentCode,
+            iterations: 0,
+            errors: [],
+            explanation: 'Original code is valid, no fixes needed.',
+        };
+    }
+    allErrors.push(...initialValidation.errors);
+    // Iterate until fixed or max iterations reached
+    while (iterations < maxIterations) {
+        iterations++;
+        const prompt = buildFixPrompt(currentCode, language, example.context, allErrors);
+        const response = await client.complete({
+            messages: [
+                { role: 'system', content: 'You are a code fixer. Return only the fixed code in a code block.' },
+                { role: 'user', content: prompt }
+            ],
+            temperature: 0,
+            maxTokens: 2048
+        });
+        // Extract code from response
+        const fixedCode = extractCode(response.content, language);
+        if (!fixedCode) {
+            allErrors.push(`Iteration ${iterations}: Could not extract code from LLM response`);
+            continue;
+        }
+        // Validate the fixed code
+        const validation = await validateFn(fixedCode);
+        if (validation.valid) {
+            return {
+                success: true,
+                fixedCode,
+                iterations,
+                errors: allErrors,
+                explanation: `Fixed after ${iterations} iteration(s).`,
+            };
+        }
+        // Add new errors and continue
+        allErrors.push(`Iteration ${iterations}: ${validation.errors.join(', ')}`);
+        currentCode = fixedCode;
+    }
+    return {
+        success: false,
+        fixedCode: currentCode,
+        iterations,
+        errors: allErrors,
+        explanation: `Could not fix code after ${maxIterations} iterations.`,
+    };
+}
+/**
+ * Build the LLM prompt for fixing code
+ */
+function buildFixPrompt(code, language, context, errors) {
+    return `You are a code fixer. Fix the following ${language} code example.
+
+## Context
+${context}
+
+## Current Code
+\`\`\`${language}
+${code}
+\`\`\`
+
+## Errors
+${errors.map((e, i) => `${i + 1}. ${e}`).join('\n')}
+
+## Instructions
+1. Analyze the errors and understand what's wrong
+2. Fix the code to make it work correctly
+3. Keep the fix minimal - don't change working parts
+4. Maintain the original intent and style
+5. Return ONLY the fixed code in a code block
+
+## Fixed Code
+`;
+}
+/**
+ * Extract code from LLM response
+ */
+function extractCode(response, language) {
+    // Try to find code block with language
+    const langRegex = new RegExp(`\`\`\`${language}\\n([\\s\\S]*?)\\n\`\`\``, 'i');
+    const langMatch = response.match(langRegex);
+    if (langMatch?.[1])
+        return langMatch[1].trim();
+    // Try generic code block
+    const genericMatch = response.match(/```\w*\n([\s\S]*?)\n```/);
+    if (genericMatch?.[1])
+        return genericMatch[1].trim();
+    // Try to find code without block
+    const lines = response.split('\n');
+    const codeLines = lines.filter(line => {
+        const trimmed = line.trim();
+        return trimmed && !trimmed.startsWith('#') && !trimmed.startsWith('//');
+    });
+    return codeLines.length > 0 ? codeLines.join('\n') : null;
+}
+/**
+ * Batch auto-fix multiple examples
+ */
+export async function autoFixBatch(examples, client, options = {}) {
+    const results = new Map();
+    for (let i = 0; i < examples.length; i++) {
+        const example = examples[i];
+        if (!example)
+            continue;
+        console.log(`  [${i + 1}/${examples.length}] Fixing ${example.language} example...`);
+        const result = await autoFixExample(example, client, options);
+        results.set(i, result);
+        if (result.success) {
+            console.log(`    ✓ Fixed in ${result.iterations} iteration(s)`);
+        }
+        else {
+            console.log(`    ✗ Could not fix after ${result.iterations} iteration(s)`);
+        }
+    }
+    return results;
+}
+/**
+ * Create a TypeScript validator using tsc
+ */
+export function createTypeScriptValidator() {
+    return async (code) => {
+        try {
+            const ts = await import('typescript');
+            const result = ts.transpileModule(code, {
+                compilerOptions: {
+                    module: ts.ModuleKind.ESNext,
+                    target: ts.ScriptTarget.ES2020,
+                    strict: true,
+                    noEmit: true,
+                },
+                reportDiagnostics: true,
+            });
+            if (result.diagnostics && result.diagnostics.length > 0) {
+                return {
+                    valid: false,
+                    errors: result.diagnostics.map(d => typeof d.messageText === 'string' ? d.messageText : d.messageText.messageText),
+                };
+            }
+            return { valid: true, errors: [] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                valid: false,
+                errors: [message],
+            };
+        }
+    };
+}
+/**
+ * Create a Python validator (requires python3 in PATH)
+ */
+export function createPythonValidator() {
+    return async (code) => {
+        try {
+            const { spawnSync } = await import('child_process');
+            const { writeFileSync, unlinkSync } = await import('fs');
+            const { join } = await import('path');
+            const { tmpdir } = await import('os');
+            const { randomUUID } = await import('crypto');
+            // Use crypto.randomUUID() to avoid timestamp collisions
+            const tempFile = join(tmpdir(), `autofix_${randomUUID()}.py`);
+            writeFileSync(tempFile, code);
+            try {
+                // Use spawnSync with array args to avoid command injection
+                const result = spawnSync('python3', ['-m', 'py_compile', tempFile], {
+                    encoding: 'utf-8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+                if (result.status !== 0) {
+                    throw { stderr: result.stderr, message: result.stderr };
+                }
+                return { valid: true, errors: [] };
+            }
+            catch (err) {
+                const errObj = err;
+                const message = errObj.stderr || errObj.message || String(err);
+                return {
+                    valid: false,
+                    errors: [message],
+                };
+            }
+            finally {
+                try {
+                    unlinkSync(tempFile);
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                valid: false,
+                errors: [message],
+            };
+        }
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { generateCommand } from './commands/generate.js';
+import { initCommand } from './commands/init.js';
+import { watchCommand } from './commands/watch.js';
+import { autofixCommand } from './commands/autofix.js';
+import { reviewPRCommand } from './commands/review-pr.js';
+const VERSION = '0.1.0';
+async function checkForUpdates() {
+    try {
+        const res = await fetch('https://registry.npmjs.org/skrypt-ai/latest', {
+            signal: AbortSignal.timeout(2000)
+        });
+        if (res.ok) {
+            const data = await res.json();
+            const latest = data.version;
+            if (latest && latest !== VERSION) {
+                console.log(`\n  Update available: ${VERSION} → ${latest}`);
+                console.log(`  Run: npm install -g skrypt-ai@latest\n`);
+            }
+        }
+    }
+    catch {
+        // Silently fail - don't block CLI
+    }
+}
+const program = new Command();
+program
+    .name('skrypt')
+    .description('AI-powered documentation generator with code examples')
+    .version(VERSION)
+    .hook('postAction', async () => {
+    await checkForUpdates();
+});
+program.addCommand(initCommand);
+program.addCommand(generateCommand);
+program.addCommand(watchCommand);
+program.addCommand(autofixCommand);
+program.addCommand(reviewPRCommand);
+program.parse();

package/dist/commands/autofix.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const autofixCommand: Command;

package/dist/commands/autofix.js

@@ -0,0 +1,143 @@
+import { Command } from 'commander';
+import { readFileSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+import { loadConfig, checkApiKey } from '../config/index.js';
+import { createLLMClient } from '../llm/index.js';
+import { autoFixExample, createTypeScriptValidator, createPythonValidator } from '../autofix/index.js';
+export const autofixCommand = new Command('autofix')
+    .description('Auto-fix broken code examples in documentation')
+    .argument('<file>', 'Documentation file to fix (markdown/mdx)')
+    .option('-c, --config <file>', 'Config file path')
+    .option('--provider <name>', 'LLM provider')
+    .option('--model <name>', 'LLM model')
+    .option('--max-iterations <n>', 'Max fix attempts per example', '3')
+    .option('--dry-run', 'Show fixes without writing')
+    .option('--language <lang>', 'Force language for validation')
+    .action(async (file, options) => {
+    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`);
+        process.exit(1);
+    }
+    const filePath = resolve(file);
+    console.log(`skrypt autofix`);
+    console.log(`  file: ${filePath}`);
+    console.log(`  provider: ${config.llm.provider}`);
+    console.log(`  max iterations: ${options.maxIterations}`);
+    console.log('');
+    // Read the file
+    let content;
+    try {
+        content = readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        const errObj = err;
+        if (errObj.code === 'ENOENT') {
+            console.error(`Error: File not found: ${filePath}`);
+        }
+        else if (errObj.code === 'EACCES') {
+            console.error(`Error: Permission denied: ${filePath}`);
+        }
+        else {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`Error: Could not read file: ${filePath} (${message})`);
+        }
+        process.exit(1);
+    }
+    // Find all 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: options.language || match[1] || 'javascript',
+            code,
+            index: match.index,
+        });
+    }
+    if (codeBlocks.length === 0) {
+        console.log('No code blocks found in file.');
+        process.exit(0);
+    }
+    console.log(`Found ${codeBlocks.length} code block(s)`);
+    console.log('');
+    const client = createLLMClient({
+        provider: config.llm.provider,
+        model: config.llm.model,
+        baseUrl: config.llm.baseUrl,
+    });
+    const maxIterations = parseInt(options.maxIterations);
+    // Create validators
+    const validators = {
+        javascript: createTypeScriptValidator(),
+        typescript: createTypeScriptValidator(),
+        ts: createTypeScriptValidator(),
+        js: createTypeScriptValidator(),
+        python: createPythonValidator(),
+        py: createPythonValidator(),
+    };
+    let fixedCount = 0;
+    let failedCount = 0;
+    let newContent = content;
+    for (let i = 0; i < codeBlocks.length; i++) {
+        const block = codeBlocks[i];
+        if (!block)
+            continue;
+        const validator = validators[block.language.toLowerCase()];
+        if (!validator) {
+            console.log(`[${i + 1}/${codeBlocks.length}] Skipping ${block.language} (no validator)`);
+            continue;
+        }
+        console.log(`[${i + 1}/${codeBlocks.length}] Checking ${block.language} example...`);
+        // First check if it's valid
+        const initial = await validator(block.code);
+        if (initial.valid) {
+            console.log(`  ✓ Already valid`);
+            continue;
+        }
+        console.log(`  ✗ Invalid: ${initial.errors[0]?.slice(0, 60)}...`);
+        console.log(`  → Attempting to fix...`);
+        const result = await autoFixExample({
+            code: block.code,
+            language: block.language,
+            context: `Code example from documentation file: ${file}`,
+        }, client, {
+            maxIterations,
+            validateFn: validator,
+            language: block.language,
+        });
+        if (result.success) {
+            console.log(`  ✓ Fixed in ${result.iterations} iteration(s)`);
+            fixedCount++;
+            // Replace in content
+            const newBlock = '```' + block.language + '\n' + result.fixedCode + '```';
+            newContent = newContent.replace(block.match, newBlock);
+        }
+        else {
+            console.log(`  ✗ Could not fix after ${result.iterations} iterations`);
+            failedCount++;
+        }
+    }
+    console.log('');
+    console.log('=== Summary ===');
+    console.log(`  Checked: ${codeBlocks.length}`);
+    console.log(`  Fixed:   ${fixedCount}`);
+    console.log(`  Failed:  ${failedCount}`);
+    if (fixedCount > 0 && !options.dryRun) {
+        writeFileSync(filePath, newContent);
+        console.log(`\nWrote fixes to ${filePath}`);
+    }
+    else if (fixedCount > 0 && options.dryRun) {
+        console.log(`\n[dry run - no changes written]`);
+    }
+    console.log('\nDone!');
+});

package/dist/commands/generate.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const generateCommand: Command;