skrypt-ai 0.6.0 → 0.7.0

package/dist/config/loader.js

@@ -61,6 +61,7 @@ function mergeConfig(defaults, overrides) {
             ...defaults.source,
             ...overrides.source
         },
+        sources: overrides.sources,
         output: {
             ...defaults.output,
             ...overrides.output
@@ -74,10 +75,25 @@ function mergeConfig(defaults, overrides) {
 }
 export function validateConfig(config) {
     const errors = [];
-    if (config.version !== 1) {
+    if (config.version !== 1 && config.version !== 2) {
         errors.push(`Unsupported config version: ${config.version}`);
     }
-    if (!config.source.path) {
+    // Validate sources array if present (v2)
+    if (config.sources && config.sources.length > 0) {
+        const labels = new Set();
+        for (const entry of config.sources) {
+            if (!entry.path) {
+                errors.push('Each source entry must have a path');
+            }
+            if (entry.label) {
+                if (labels.has(entry.label)) {
+                    errors.push(`Duplicate source label: "${entry.label}"`);
+                }
+                labels.add(entry.label);
+            }
+        }
+    }
+    else if (!config.source.path) {
         errors.push('source.path is required');
     }
     if (!config.output.path) {
@@ -88,6 +104,26 @@ export function validateConfig(config) {
     }
     return errors;
 }
+/**
+ * Resolve v1 `source` or v2 `sources` into a normalized array of SourceEntry.
+ * Falls back to the single source config if no sources array is defined.
+ */
+export function resolveSourceEntries(config) {
+    if (config.sources && config.sources.length > 0) {
+        return config.sources.map(s => ({
+            path: s.path,
+            label: s.label,
+            include: s.include ?? config.source.include,
+            exclude: s.exclude ?? config.source.exclude,
+        }));
+    }
+    // Backwards compat: single source
+    return [{
+            path: config.source.path,
+            include: config.source.include,
+            exclude: config.source.exclude,
+        }];
+}
 export function checkApiKey(provider) {
     const envKey = PROVIDER_ENV_KEYS[provider];
     // Ollama doesn't need an API key

package/dist/config/types.d.ts

@@ -3,6 +3,12 @@ export interface SourceConfig {
     include?: string[];
     exclude?: string[];
 }
+export interface SourceEntry {
+    path: string;
+    label?: string;
+    include?: string[];
+    exclude?: string[];
+}
 export type LLMProvider = 'deepseek' | 'openai' | 'anthropic' | 'google' | 'ollama' | 'openrouter';
 export interface LLMConfig {
     provider: LLMProvider;
@@ -14,6 +20,7 @@ export declare const DEFAULT_MODELS: Record<LLMProvider, string>;
 export interface Config {
     version: number;
     source: SourceConfig;
+    sources?: SourceEntry[];
     output: {
         path: string;
         format: 'markdown' | 'mdx';

package/dist/generator/generator.js

@@ -68,7 +68,8 @@ export async function generateForElement(element, client, options, onProgress) {
     report('generating');
     try {
         const elementContext = buildElementContext(element, options.externalContext, options.projectContext);
-        const result = await generateDocumentation(client, elementContext, { multiLanguage: useMultiLang });
+        const errorContext = options.previousErrors?.get(element.name);
+        const result = await generateDocumentation(client, elementContext, { multiLanguage: useMultiLang, verify: options.verify, previousError: errorContext });
         report('done');
         return {
             element,

package/dist/generator/types.d.ts

@@ -33,6 +33,9 @@ export interface GenerationOptions {
     externalContext?: Map<string, string>;
     maxTokens?: number;
     projectContext?: string;
+    verify?: boolean;
+    /** Error context from previous verification failures, keyed by element name */
+    previousErrors?: Map<string, string>;
 }
 /**
  * Result of generating docs for a file

package/dist/generator/writer.js

@@ -13,36 +13,45 @@ export async function writeLlmsTxt(docs, outputDir, options = {}) {
     const description = options.description || 'API documentation generated by skrypt';
     let content = `# ${projectName}\n\n`;
     content += `> ${description}\n\n`;
-    // Group by file for organization
-    const byFile = new Map();
+    // Check if docs have source labels (multi-source mode)
+    const hasSourceLabels = docs.some(d => d.element.sourceLabel);
+    // Group by source label then by file
+    const bySource = new Map();
     for (const doc of docs) {
+        const sourceKey = doc.element.sourceLabel || '_default';
+        if (!bySource.has(sourceKey))
+            bySource.set(sourceKey, new Map());
+        const sourceMap = bySource.get(sourceKey);
         const file = basename(doc.element.filePath).replace(/\.[^.]+$/, '');
-        if (!byFile.has(file)) {
-            byFile.set(file, []);
-        }
-        const fileDocs = byFile.get(file);
-        if (fileDocs)
-            fileDocs.push(doc);
+        if (!sourceMap.has(file))
+            sourceMap.set(file, []);
+        sourceMap.get(file).push(doc);
     }
+    const totalModules = Array.from(bySource.values()).reduce((sum, m) => sum + m.size, 0);
     // Summary section
     content += `## Overview\n\n`;
-    content += `This project contains ${docs.length} documented API elements across ${byFile.size} modules.\n\n`;
+    content += `This project contains ${docs.length} documented API elements across ${totalModules} modules.\n\n`;
     // Quick reference
     content += `## Quick Reference\n\n`;
-    for (const [file, fileDocs] of byFile) {
-        content += `### ${file}\n\n`;
-        for (const doc of fileDocs) {
-            content += `- \`${doc.element.name}\`: ${doc.element.kind}`;
-            if (doc.markdown) {
-                // Extract first sentence as summary
-                const firstSentence = doc.markdown.split(/\.\s/)[0]?.slice(0, 100);
-                if (firstSentence) {
-                    content += ` - ${firstSentence}`;
+    for (const [sourceLabel, byFile] of bySource) {
+        if (hasSourceLabels && sourceLabel !== '_default') {
+            content += `### ${sourceLabel}\n\n`;
+        }
+        for (const [file, fileDocs] of byFile) {
+            content += `${hasSourceLabels ? '####' : '###'} ${file}\n\n`;
+            for (const doc of fileDocs) {
+                content += `- \`${doc.element.name}\`: ${doc.element.kind}`;
+                if (doc.markdown) {
+                    // Extract first sentence as summary
+                    const firstSentence = doc.markdown.split(/\.\s/)[0]?.slice(0, 100);
+                    if (firstSentence) {
+                        content += ` - ${firstSentence}`;
+                    }
                 }
+                content += '\n';
             }
             content += '\n';
         }
-        content += '\n';
     }
     // Detailed API section
     content += `## API Details\n\n`;
@@ -134,15 +143,38 @@ async function writeIndexFile(results, outputDir, sourceDir) {
     const totalElements = results.reduce((sum, r) => sum + r.docs.length, 0);
     content += '## Summary\n\n';
     content += `- **Total elements:** ${totalElements}\n\n`;
-    // File index
-    content += '## Files\n\n';
-    for (const result of results) {
-        if (result.docs.length === 0)
-            continue;
-        const relPath = relative(sourceDir, result.filePath);
-        const docFileName = relPath.replace(/\.[^.]+$/, '.md');
-        content += `- [${relPath}](./${docFileName})`;
-        content += ` (${result.docs.length} elements)\n`;
+    // Check if any docs have source labels
+    const hasLabels = results.some(r => r.docs.some(d => d.element.sourceLabel));
+    if (hasLabels) {
+        // Group by source label
+        const byLabel = new Map();
+        for (const result of results) {
+            if (result.docs.length === 0)
+                continue;
+            const label = result.docs[0]?.element.sourceLabel || 'Other';
+            if (!byLabel.has(label))
+                byLabel.set(label, []);
+            byLabel.get(label).push(result);
+        }
+        for (const [label, labelResults] of byLabel) {
+            content += `## ${label}\n\n`;
+            for (const result of labelResults) {
+                const relPath = relative(sourceDir, result.filePath);
+                const docFileName = relPath.replace(/\.[^.]+$/, '.md');
+                content += `- [${relPath}](./${docFileName}) (${result.docs.length} elements)\n`;
+            }
+            content += '\n';
+        }
+    }
+    else {
+        content += '## Files\n\n';
+        for (const result of results) {
+            if (result.docs.length === 0)
+                continue;
+            const relPath = relative(sourceDir, result.filePath);
+            const docFileName = relPath.replace(/\.[^.]+$/, '.md');
+            content += `- [${relPath}](./${docFileName}) (${result.docs.length} elements)\n`;
+        }
     }
     await writeFile(join(outputDir, 'README.md'), content, 'utf-8');
 }

package/dist/github/org-discovery.d.ts

@@ -0,0 +1,17 @@
+export interface DiscoveredRepo {
+    name: string;
+    full_name: string;
+    clone_url: string;
+    default_branch: string;
+    private: boolean;
+}
+/**
+ * Discover repositories in a GitHub organization.
+ * Returns up to MAX_REPOS repos sorted by most recently pushed.
+ */
+export declare function discoverOrgRepos(org: string, token: string): Promise<DiscoveredRepo[]>;
+/**
+ * Shallow clone a repository to a temporary directory.
+ * Uses spawnSync with array args to prevent shell injection.
+ */
+export declare function cloneRepoToTemp(repo: DiscoveredRepo, token: string): Promise<string>;

package/dist/github/org-discovery.js

@@ -0,0 +1,93 @@
+import { spawnSync } from 'child_process';
+import { mkdtempSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+const MAX_REPOS = 50;
+/**
+ * Discover repositories in a GitHub organization.
+ * Returns up to MAX_REPOS repos sorted by most recently pushed.
+ */
+export async function discoverOrgRepos(org, token) {
+    const repos = [];
+    let page = 1;
+    while (repos.length < MAX_REPOS) {
+        const url = `https://api.github.com/orgs/${encodeURIComponent(org)}/repos?per_page=100&sort=pushed&page=${page}`;
+        const response = await fetch(url, {
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'Accept': 'application/vnd.github.v3+json',
+                'User-Agent': 'Skrypt-CLI',
+            },
+        });
+        if (!response.ok) {
+            if (response.status === 404) {
+                throw new Error(`Organization "${org}" not found`);
+            }
+            if (response.status === 401 || response.status === 403) {
+                throw new Error('GitHub token does not have access to this organization');
+            }
+            throw new Error(`GitHub API error: ${response.status}`);
+        }
+        const data = await response.json();
+        if (data.length === 0)
+            break;
+        for (const repo of data) {
+            if (repos.length >= MAX_REPOS)
+                break;
+            // Skip archived and forked repos
+            if (repo.archived || repo.fork)
+                continue;
+            repos.push({
+                name: repo.name,
+                full_name: repo.full_name,
+                clone_url: repo.clone_url,
+                default_branch: repo.default_branch,
+                private: repo.private,
+            });
+        }
+        page++;
+    }
+    return repos;
+}
+/**
+ * Shallow clone a repository to a temporary directory.
+ * Uses spawnSync with array args to prevent shell injection.
+ */
+export async function cloneRepoToTemp(repo, token) {
+    const tempDir = mkdtempSync(join(tmpdir(), `skrypt-${repo.name}-`));
+    // Build authenticated clone URL
+    const cloneUrl = repo.clone_url.replace('https://', `https://x-access-token:${token}@`);
+    let result;
+    try {
+        result = spawnSync('git', [
+            'clone',
+            '--depth', '1',
+            '--single-branch',
+            '--branch', repo.default_branch,
+            cloneUrl,
+            tempDir,
+        ], {
+            stdio: 'pipe',
+            timeout: 60_000,
+        });
+    }
+    catch (err) {
+        // Clean up temp dir on spawn failure
+        try {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+        catch { /* ignore */ }
+        throw new Error(`Failed to clone ${repo.full_name}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    if (result.status !== 0) {
+        // Clean up temp dir on clone failure
+        try {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+        catch { /* ignore */ }
+        // Sanitize stderr to avoid leaking the token
+        const stderr = (result.stderr?.toString() || '').replace(/x-access-token:[^@]+@/g, 'x-access-token:***@');
+        throw new Error(`Failed to clone ${repo.full_name}: ${stderr}`);
+    }
+    return tempDir;
+}

package/dist/llm/index.d.ts

@@ -52,4 +52,6 @@ export interface GeneratedDocResult {
  */
 export declare function generateDocumentation(client: LLMClient, element: ElementContext, options?: {
     multiLanguage?: boolean;
+    verify?: boolean;
+    previousError?: string;
 }): Promise<GeneratedDocResult>;

package/dist/llm/index.js

@@ -31,7 +31,10 @@ export function createLLMClient(config) {
  */
 export async function generateDocumentation(client, element, options) {
     const useMultiLang = options?.multiLanguage ?? true;
-    const prompt = buildDocPrompt(element, useMultiLang);
+    let prompt = buildDocPrompt(element, useMultiLang, options?.verify);
+    if (options?.previousError) {
+        prompt += `\n\n⚠️ IMPORTANT: The previous code example for this element FAILED verification with the following error:\n\`\`\`\n${options.previousError}\n\`\`\`\nGenerate a DIFFERENT, working code example that avoids this error. Ensure the example is self-contained and runs without external dependencies unless specified.`;
+    }
     const response = await client.complete({
         messages: [
             {
@@ -127,7 +130,7 @@ Generate ONE self-contained, executable example:
 ---CODE---
 [Self-contained example — no markdown fences]
 ---END---`;
-function buildDocPrompt(element, multiLanguage = false) {
+function buildDocPrompt(element, multiLanguage = false, verify = false) {
     let prompt = '';
     // Project context first — gives the LLM the "big picture" for better explanations
     if (element.projectContext) {
@@ -174,6 +177,9 @@ function buildDocPrompt(element, multiLanguage = false) {
     if (multiLanguage) {
         prompt += `\nGenerate BOTH TypeScript AND Python self-contained examples.`;
     }
+    if (verify) {
+        prompt += `\n\nIMPORTANT: Include \`// Output: <expected>\` comments showing expected console output for every \`console.log\` call (or \`# Output: <expected>\` for Python \`print\` calls). These will be verified by running the code.`;
+    }
     return prompt;
 }
 function parseDocResponse(content, elementName) {

package/dist/next-actions/actions.d.ts

@@ -0,0 +1,2 @@
+import { ActionDefinition } from './types.js';
+export declare const ACTION_DEFINITIONS: ActionDefinition[];

package/dist/next-actions/actions.js

@@ -0,0 +1,190 @@
+import { existsSync } from 'fs';
+function noWorkflowFile() {
+    return !existsSync('.github/workflows/skrypt.yml') &&
+        !existsSync('.github/workflows/skrypt.yaml');
+}
+export const ACTION_DEFINITIONS = [
+    // ── After init ──────────────────────────────────────────────
+    {
+        id: 'gen-init',
+        afterCommands: ['init'],
+        category: 'workflow',
+        message: 'Generate docs from your source code',
+        command: 'skrypt generate ./src -o ./content/docs',
+        priority: 100,
+    },
+    // ── After generate ──────────────────────────────────────────
+    {
+        id: 'test-gen',
+        afterCommands: ['generate'],
+        category: 'workflow',
+        message: 'Verify code snippets execute correctly',
+        command: 'skrypt test ./docs',
+        priority: 100,
+    },
+    {
+        id: 'qa-gen',
+        afterCommands: ['generate'],
+        category: 'quality',
+        message: 'Run quality checks on generated docs',
+        command: 'skrypt qa ./docs',
+        priority: 80,
+    },
+    {
+        id: 'audit-gen',
+        afterCommands: ['generate'],
+        category: 'advanced',
+        message: 'Check documentation coverage',
+        command: 'skrypt audit ./src --docs ./docs',
+        priority: 50,
+    },
+    // ── After test ──────────────────────────────────────────────
+    {
+        id: 'audit-test',
+        afterCommands: ['test'],
+        category: 'advanced',
+        message: 'Check documentation coverage',
+        command: 'skrypt audit ./src --docs ./docs',
+        priority: 60,
+    },
+    // ── After qa ────────────────────────────────────────────────
+    {
+        id: 'heal-qa',
+        afterCommands: ['qa'],
+        category: 'quality',
+        message: 'Auto-fix QA issues',
+        command: 'skrypt heal',
+        priority: 90,
+    },
+    {
+        id: 'lint-qa',
+        afterCommands: ['qa'],
+        category: 'quality',
+        message: 'Lint markdown docs',
+        command: 'skrypt lint ./docs',
+        priority: 70,
+    },
+    {
+        id: 'security-qa',
+        afterCommands: ['qa'],
+        category: 'quality',
+        message: 'Check for security issues',
+        command: 'skrypt security ./docs',
+        priority: 60,
+    },
+    // ── After audit ─────────────────────────────────────────────
+    {
+        id: 'refresh-audit',
+        afterCommands: ['audit'],
+        category: 'advanced',
+        message: 'Update stale docs based on code changes',
+        command: 'skrypt refresh ./src --docs ./docs',
+        priority: 80,
+    },
+    {
+        id: 'review-audit',
+        afterCommands: ['audit'],
+        category: 'advanced',
+        message: 'Review docs quality with feedback',
+        command: 'skrypt review ./docs',
+        priority: 60,
+    },
+    // ── After refresh / review / heal / autofix ─────────────────
+    {
+        id: 'test-after-fix',
+        afterCommands: ['refresh', 'review', 'heal', 'autofix'],
+        category: 'workflow',
+        message: 'Verify updated docs pass tests',
+        command: 'skrypt test ./docs',
+        priority: 100,
+    },
+    // ── After deploy ────────────────────────────────────────────
+    {
+        id: 'watch-deploy',
+        afterCommands: ['deploy'],
+        category: 'workflow',
+        message: 'Watch for changes in development',
+        command: 'skrypt watch',
+        priority: 50,
+    },
+    // ── After import ────────────────────────────────────────────
+    {
+        id: 'qa-import',
+        afterCommands: ['import'],
+        category: 'quality',
+        message: 'Check imported docs quality',
+        command: 'skrypt qa ./docs',
+        priority: 90,
+    },
+    {
+        id: 'gen-import',
+        afterCommands: ['import'],
+        category: 'workflow',
+        message: 'Generate docs to fill gaps',
+        command: 'skrypt generate ./src -o ./content/docs',
+        priority: 70,
+    },
+    // ── After login ─────────────────────────────────────────────
+    {
+        id: 'pro-login',
+        afterCommands: ['login'],
+        category: 'workflow',
+        message: 'Unlock Pro: test, heal, autofix, refresh',
+        command: 'skrypt test ./docs',
+        priority: 100,
+    },
+    // ── After gh-action ─────────────────────────────────────────
+    {
+        id: 'push-ci',
+        afterCommands: ['gh-action'],
+        category: 'cicd',
+        message: 'Push to GitHub to trigger CI',
+        command: 'git push',
+        priority: 100,
+    },
+    // ── CI/CD setup (cross-command) ─────────────────────────────
+    {
+        id: 'ci-setup',
+        afterCommands: ['generate', 'test', 'deploy'],
+        category: 'cicd',
+        message: 'Set up GitHub Actions for CI',
+        command: 'skrypt gh-action',
+        priority: 70,
+        condition: noWorkflowFile,
+    },
+    // ── Deploy (cross-command) ──────────────────────────────────
+    {
+        id: 'deploy-docs',
+        afterCommands: ['generate', 'test', 'heal', 'review', 'refresh', 'autofix'],
+        category: 'workflow',
+        message: 'Deploy docs to skrypt.sh',
+        command: 'skrypt deploy',
+        priority: 40,
+    },
+    // ── After lint / check-links / security ─────────────────────
+    {
+        id: 'deploy-quality',
+        afterCommands: ['lint', 'check-links', 'security'],
+        category: 'workflow',
+        message: 'Deploy docs to skrypt.sh',
+        command: 'skrypt deploy',
+        priority: 40,
+    },
+    {
+        id: 'qa-quality',
+        afterCommands: ['lint', 'check-links', 'security'],
+        category: 'quality',
+        message: 'Run full quality checks',
+        command: 'skrypt qa ./docs',
+        priority: 60,
+    },
+    // ── After llms-txt ──────────────────────────────────────────
+    {
+        id: 'deploy-llms',
+        afterCommands: ['llms-txt'],
+        category: 'workflow',
+        message: 'Deploy docs with llms.txt',
+        command: 'skrypt deploy',
+        priority: 80,
+    },
+];

package/dist/next-actions/index.d.ts

@@ -0,0 +1,6 @@
+export { readPreferences, writePreferences, DEFAULT_PREFERENCES } from './state.js';
+export { getSuggestions, printSuggestions } from './suggest.js';
+export { runFirstTimeSetup } from './setup.js';
+export { ACTION_DEFINITIONS } from './actions.js';
+export type { NextActionPreferences, ProjectActionState, ActionDefinition, Suggestion } from './types.js';
+export declare function handlePostAction(commandName: string): Promise<void>;

package/dist/next-actions/index.js

@@ -0,0 +1,39 @@
+import { readPreferences, markCommandCompleted } from './state.js';
+import { getSuggestions, printSuggestions } from './suggest.js';
+import { runFirstTimeSetup } from './setup.js';
+export { readPreferences, writePreferences, DEFAULT_PREFERENCES } from './state.js';
+export { getSuggestions, printSuggestions } from './suggest.js';
+export { runFirstTimeSetup } from './setup.js';
+export { ACTION_DEFINITIONS } from './actions.js';
+const SKIP_COMMANDS = new Set(['config', 'mcp', 'whoami', 'version', 'logout']);
+export async function handlePostAction(commandName) {
+    try {
+        // Only in interactive mode
+        if (!process.stdin.isTTY)
+            return;
+        // Skip meta commands
+        if (SKIP_COMMANDS.has(commandName))
+            return;
+        let prefs = readPreferences();
+        // First-time setup
+        if (!prefs) {
+            try {
+                prefs = await runFirstTimeSetup();
+            }
+            catch {
+                // Non-interactive or error — skip silently
+                return;
+            }
+        }
+        if (!prefs.enabled)
+            return;
+        // Track this command
+        markCommandCompleted(commandName);
+        // Show suggestions
+        const suggestions = getSuggestions(commandName, prefs);
+        printSuggestions(suggestions);
+    }
+    catch {
+        // Never crash the CLI over suggestions
+    }
+}

package/dist/next-actions/setup.d.ts

@@ -0,0 +1,2 @@
+import { NextActionPreferences } from './types.js';
+export declare function runFirstTimeSetup(): Promise<NextActionPreferences>;