skrypt-ai 0.6.1 → 0.8.0

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/llm/proxy-client.d.ts

@@ -0,0 +1,32 @@
+import { LLMClient, CompletionRequest, CompletionResponse } from './types.js';
+/**
+ * LLM client that routes requests through Skrypt's proxy API.
+ * Used when the user doesn't have their own API key but has a Skrypt account.
+ */
+export declare class ProxyClient implements LLMClient {
+    provider: "openai";
+    private apiKey;
+    private sessionId;
+    private timeout;
+    constructor(config: {
+        apiKey: string;
+        sessionId: string;
+        timeout?: number;
+    });
+    complete(request: CompletionRequest): Promise<CompletionResponse>;
+    isConfigured(): boolean;
+}
+/**
+ * Start a proxy generation session.
+ * Returns sessionId + remaining generations info.
+ */
+export declare function startProxySession(apiKey: string): Promise<{
+    sessionId: string;
+    plan: 'free' | 'pro';
+    remaining: number;
+    used: number;
+}>;
+/**
+ * Complete a proxy generation session (increments monthly usage counter).
+ */
+export declare function completeProxySession(apiKey: string, sessionId: string): Promise<void>;

package/dist/llm/proxy-client.js

@@ -0,0 +1,103 @@
+const API_BASE = process.env.SKRYPT_API_URL || 'https://app.skrypt.sh';
+/**
+ * LLM client that routes requests through Skrypt's proxy API.
+ * Used when the user doesn't have their own API key but has a Skrypt account.
+ */
+export class ProxyClient {
+    provider = 'openai'; // Proxy decides which model to use
+    apiKey;
+    sessionId;
+    timeout;
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.sessionId = config.sessionId;
+        this.timeout = config.timeout ?? 120_000;
+    }
+    async complete(request) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(`${API_BASE}/api/proxy/generate`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    sessionId: this.sessionId,
+                    messages: request.messages,
+                    temperature: request.temperature ?? 0,
+                    maxTokens: request.maxTokens ?? 4096,
+                }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+                throw new Error(error.error || `Proxy request failed: ${response.status}`);
+            }
+            const data = await response.json();
+            return {
+                content: data.content,
+                model: data.model,
+                usage: {
+                    inputTokens: data.usage.inputTokens,
+                    outputTokens: data.usage.outputTokens,
+                    totalTokens: data.usage.totalTokens,
+                },
+                finishReason: data.finishReason || 'stop',
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    isConfigured() {
+        return !!this.apiKey && !!this.sessionId;
+    }
+}
+/**
+ * Start a proxy generation session.
+ * Returns sessionId + remaining generations info.
+ */
+export async function startProxySession(apiKey) {
+    const response = await fetch(`${API_BASE}/api/proxy/generate/start`, {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${apiKey}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({}),
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+        const errData = error;
+        if (response.status === 429) {
+            throw new Error(`Monthly generation limit reached (${errData.used}/${errData.limit}). ` +
+                `Upgrade to Pro: ${errData.upgrade || 'https://skrypt.sh/pro'}`);
+        }
+        throw new Error(errData.error || `Failed to start session: ${response.status}`);
+    }
+    return await response.json();
+}
+/**
+ * Complete a proxy generation session (increments monthly usage counter).
+ */
+export async function completeProxySession(apiKey, sessionId) {
+    try {
+        const response = await fetch(`${API_BASE}/api/proxy/generate/complete`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ sessionId }),
+        });
+        if (!response.ok) {
+            console.warn('Warning: Failed to complete generation session');
+        }
+    }
+    catch {
+        // Non-critical — network error, server down, etc.
+        console.warn('Warning: Failed to complete generation session');
+    }
+}

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>;

package/dist/next-actions/setup.js

@@ -0,0 +1,72 @@
+import * as readline from 'readline';
+import { writePreferences, DEFAULT_PREFERENCES } from './state.js';
+function ask(rl, question) {
+    return new Promise((resolve, reject) => {
+        rl.question(question, answer => resolve(answer.trim()));
+        rl.once('close', () => reject(new Error('EOF')));
+    });
+}
+export async function runFirstTimeSetup() {
+    console.log('');
+    console.log('  \x1b[36m─────────────────────────────────────\x1b[0m');
+    console.log('');
+    console.log('  Skrypt can suggest next steps after each command.');
+    console.log('');
+    console.log('  1) All suggestions (recommended)');
+    console.log('  2) Workflow only (generate \u2192 test \u2192 deploy)');
+    console.log('  3) Customize');
+    console.log('  4) Disable');
+    console.log('');
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const choice = await ask(rl, '  Choice [1]: ');
+        const selected = choice || '1';
+        let prefs;
+        if (selected === '4') {
+            prefs = {
+                enabled: false,
+                categories: { workflow: false, quality: false, cicd: false, advanced: false },
+            };
+        }
+        else if (selected === '2') {
+            prefs = {
+                enabled: true,
+                categories: { workflow: true, quality: false, cicd: false, advanced: false },
+            };
+        }
+        else if (selected === '3') {
+            console.log('');
+            const w = await ask(rl, '  Workflow (generate, test, deploy)? [Y/n] ');
+            const q = await ask(rl, '  Quality (qa, lint, security)? [Y/n] ');
+            const c = await ask(rl, '  CI/CD (GitHub Actions, deploy)? [Y/n] ');
+            const a = await ask(rl, '  Advanced (audit, refresh, review)? [Y/n] ');
+            prefs = {
+                enabled: true,
+                categories: {
+                    workflow: w.toLowerCase() !== 'n',
+                    quality: q.toLowerCase() !== 'n',
+                    cicd: c.toLowerCase() !== 'n',
+                    advanced: a.toLowerCase() !== 'n',
+                },
+            };
+        }
+        else {
+            prefs = { ...DEFAULT_PREFERENCES };
+        }
+        writePreferences(prefs);
+        console.log('');
+        if (prefs.enabled) {
+            console.log('  \x1b[32mSaved!\x1b[0m Change anytime with: skrypt config --suggestions');
+        }
+        else {
+            console.log('  Suggestions disabled. Re-enable with: skrypt config --suggestions');
+        }
+        return prefs;
+    }
+    finally {
+        rl.close();
+    }
+}

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

@@ -0,0 +1,7 @@
+import { NextActionPreferences, ProjectActionState } from './types.js';
+export declare const DEFAULT_PREFERENCES: NextActionPreferences;
+export declare function readPreferences(): NextActionPreferences | null;
+export declare function writePreferences(prefs: NextActionPreferences): void;
+export declare function readProjectState(): ProjectActionState;
+export declare function writeProjectState(state: ProjectActionState): void;
+export declare function markCommandCompleted(commandName: string): void;

package/dist/next-actions/state.js

@@ -0,0 +1,68 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { createHash } from 'crypto';
+function skryptHome() {
+    return join(homedir(), '.skrypt');
+}
+function preferencesFile() {
+    return join(skryptHome(), 'preferences.json');
+}
+function projectsDir() {
+    return join(skryptHome(), 'projects');
+}
+export const DEFAULT_PREFERENCES = {
+    enabled: true,
+    categories: {
+        workflow: true,
+        quality: true,
+        cicd: true,
+        advanced: true,
+    },
+};
+function projectHash() {
+    return createHash('sha256').update(process.cwd()).digest('hex').slice(0, 12);
+}
+function projectStatePath() {
+    return join(projectsDir(), `${projectHash()}.json`);
+}
+export function readPreferences() {
+    try {
+        const path = preferencesFile();
+        if (!existsSync(path))
+            return null;
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function writePreferences(prefs) {
+    const home = skryptHome();
+    mkdirSync(home, { recursive: true });
+    writeFileSync(preferencesFile(), JSON.stringify(prefs, null, 2), { mode: 0o600 });
+}
+export function readProjectState() {
+    try {
+        const path = projectStatePath();
+        if (!existsSync(path)) {
+            return { completedCommands: [], lastUpdated: '' };
+        }
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return { completedCommands: [], lastUpdated: '' };
+    }
+}
+export function writeProjectState(state) {
+    mkdirSync(projectsDir(), { recursive: true });
+    state.lastUpdated = new Date().toISOString();
+    writeFileSync(projectStatePath(), JSON.stringify(state, null, 2), { mode: 0o600 });
+}
+export function markCommandCompleted(commandName) {
+    const state = readProjectState();
+    if (!state.completedCommands.includes(commandName)) {
+        state.completedCommands.push(commandName);
+    }
+    writeProjectState(state);
+}