skrypt-ai 0.4.2 → 0.6.0

package/dist/llm/index.js

@@ -9,6 +9,9 @@ export function createLLMClient(config) {
     // Get API key from environment
     const envKey = PROVIDER_ENV_KEYS[config.provider];
     const apiKey = envKey ? process.env[envKey] || '' : '';
+    if (!apiKey) {
+        console.warn(`Warning: ${envKey} is not set. LLM calls will fail.`);
+    }
     const clientConfig = {
         provider: config.provider,
         model: config.model,
@@ -43,176 +46,102 @@ export async function generateDocumentation(client, element, options) {
         temperature: 0,
         maxTokens: useMultiLang ? 4096 : 2048
     });
-    return useMultiLang
-        ? parseMultiLangResponse(response.content)
-        : parseDocResponse(response.content);
+    const usage = response.usage
+        ? { inputTokens: response.usage.inputTokens, outputTokens: response.usage.outputTokens }
+        : undefined;
+    const result = useMultiLang
+        ? parseMultiLangResponse(response.content, element.name)
+        : parseDocResponse(response.content, element.name);
+    return { ...result, usage };
 }
 // Phase 2: Multi-language system prompt
-const SYSTEM_PROMPT_MULTI_LANG = `You are an expert technical writer creating OUTCOMES-FOCUSED documentation with DUAL-LANGUAGE examples.
-
-Your goal: Help developers achieve their task FAST. Lead with "Use this to..." not "This function...".
-
-## Documentation Rules
-1. Do NOT include a heading with the function/class name - start directly with the use case
-2. Start with the PRIMARY USE CASE - what problem does this solve?
-3. Use a markdown table for parameters (Name | Type | Required | Description)
-4. Clearly document what is returned and when
-
-## Code Example Rules (CRITICAL)
-Generate TWO self-contained examples: TypeScript AND Python.
-
-Both examples MUST be:
-1. COMPLETELY SELF-CONTAINED - no external imports from the library
-2. EXECUTABLE standalone - inline all types and mock all functions
-3. Using realistic data (API keys, user IDs, etc.)
-4. Wrapped in try/except (Python) or try/catch (TypeScript)
-5. Showing environment variable usage
-6. Ending with print/console.log showing expected output
+const SYSTEM_PROMPT_MULTI_LANG = `You are an expert technical writer. Write like the best devtool docs (Stripe, Vercel, Shopify): lead with the outcome, explain why this exists, then get technical.
 
-## TypeScript Example Pattern
-\`\`\`typescript
-// Inline types
-type Config = { apiKey: string }
+## Writing Rules
 
-// Mock implementation
-function createTool(config: Config) {
-  return { execute: async (q: string) => ({ results: [q] }) }
-}
+1. **Opening sentence**: Start with "Use [name] to [outcome]." Tell the developer what this ENABLES them to do. NOT "This function takes X and returns Y."
 
-// Usage
-const tool = createTool({ apiKey: process.env.API_KEY || 'your-key' })
+2. **When to use this** (1-2 sentences): What scenario would make a developer reach for this? If it's a method on a class, how does it fit into the typical workflow with that class? Connect it to a real task.
 
-async function main() {
-  try {
-    const result = await tool.execute('query')
-    console.log('Result:', result)
-    // Output: { results: ['query'] }
-  } catch (error) {
-    console.error('Failed:', error)
-  }
-}
-main()
-\`\`\`
+3. **How it works** (1-3 sentences, only if the mechanism isn't obvious): Briefly explain the behavior. Skip this if the function name + params make it self-evident.
 
-## Python Example Pattern
-\`\`\`python
-import os
-from dataclasses import dataclass
-from typing import Optional, List, Dict, Any
+4. **Parameters**: Markdown table (Name | Type | Required | Description). Descriptions must explain IMPACT, not restate the type. Write "Maximum retry attempts before the request fails and throws" not "Number of retries." Write "Your Stripe secret key — find it at dashboard.stripe.com/apikeys" not "A string."
 
-# Inline types
-@dataclass
-class Config:
-    api_key: str
-    timeout: int = 30
+5. **Returns**: What you get back AND what to do with it next. "Returns the created user object. Pass user.id to subsequent API calls to act on behalf of this user."
 
-# Mock implementation
-class Tool:
-    def __init__(self, config: Config):
-        self.config = config
+6. **Heads up** (only if non-obvious): 1-2 bullet points about common mistakes or surprising behavior. Omit entirely if there's nothing surprising.
 
-    async def execute(self, query: str) -> Dict[str, Any]:
-        return {"results": [query]}
+Do NOT include a heading with the function/class name — start directly with the opening sentence.
+Do NOT write filler like "This is a powerful utility for..." — be direct.
+Do NOT just restate the function signature in prose — add information the signature doesn't convey.
 
-# Usage
-import asyncio
-
-async def main():
-    try:
-        tool = Tool(Config(api_key=os.getenv("API_KEY", "your-key")))
-        result = await tool.execute("query")
-        print(f"Result: {result}")
-        # Output: {'results': ['query']}
-    except Exception as e:
-        print(f"Failed: {e}")
+## Code Examples
+Generate TWO self-contained examples: TypeScript AND Python.
 
-asyncio.run(main())
-\`\`\`
+Both MUST be:
+- COMPLETELY SELF-CONTAINED — no imports from the library being documented. Inline types and mock implementations.
+- Using realistic data (real-looking API keys, user IDs, URLs)
+- Wrapped in try/catch (TS) or try/except (Python)
+- Ending with console.log/print showing expected output
+- Short and focused — demonstrate the ONE primary use case, not every parameter
 
 ## Output Format
 ---MARKDOWN---
-[Your markdown documentation with parameter table]
+[Documentation following the rules above]
 ---TYPESCRIPT---
-[Self-contained TypeScript example]
+[Self-contained TypeScript example — no markdown fences]
 ---PYTHON---
-[Self-contained Python example]
+[Self-contained Python example — no markdown fences]
 ---END---`;
-const SYSTEM_PROMPT = `You are an expert technical writer creating OUTCOMES-FOCUSED documentation.
+const SYSTEM_PROMPT = `You are an expert technical writer. Write like the best devtool docs (Stripe, Vercel, Shopify): lead with the outcome, explain why this exists, then get technical.
 
-Your goal: Help developers achieve their task FAST. Lead with "Use this to..." not "This function...".
+## Writing Rules
 
-## Documentation Rules
-1. Do NOT include a heading with the function/class name - start directly with the use case
-2. Start with the PRIMARY USE CASE - what problem does this solve?
-3. Use a markdown table for parameters (Name | Type | Required | Description)
-4. Clearly document what is returned and when
+1. **Opening sentence**: Start with "Use [name] to [outcome]." Tell the developer what this ENABLES them to do. NOT "This function takes X and returns Y."
 
-## Code Example Rules (CRITICAL)
-Your code examples MUST be COMPLETELY SELF-CONTAINED and EXECUTABLE:
+2. **When to use this** (1-2 sentences): What scenario would make a developer reach for this? If it's a method on a class, how does it fit into the typical workflow with that class? Connect it to a real task.
 
-1. NEVER import from the library being documented (e.g., "@supermemory/tools")
-2. Instead, INLINE any types or simple implementations needed
-3. Use realistic but simple data (real-looking API keys, user IDs, etc.)
-4. ALWAYS wrap async code in try/catch with meaningful error handling
-5. ALWAYS show environment variable usage: process.env.API_KEY || 'your-api-key'
-6. End with a console.log showing expected output
-7. Include a brief comment showing what output to expect
+3. **How it works** (1-3 sentences, only if the mechanism isn't obvious): Briefly explain the behavior. Skip this if the function name + params make it self-evident.
 
-## Self-Contained Example Pattern
-BAD (imports from library - will fail):
-\`\`\`typescript
-import { createTool } from '@mylib/tools'
-const tool = createTool('key')
-\`\`\`
+4. **Parameters**: Markdown table (Name | Type | Required | Description). Descriptions must explain IMPACT, not restate the type. Write "Maximum retry attempts before the request fails and throws" not "Number of retries." Write "Your Stripe secret key — find it at dashboard.stripe.com/apikeys" not "A string."
 
-GOOD (self-contained - will run):
-\`\`\`typescript
-// Define the types inline
-type ToolConfig = { apiKey: string; timeout?: number }
+5. **Returns**: What you get back AND what to do with it next. "Returns the created user object. Pass user.id to subsequent API calls to act on behalf of this user."
 
-// Simulate the function behavior
-function createTool(config: ToolConfig) {
-  return {
-    execute: async (query: string) => {
-      console.log(\`Searching for: \${query}\`)
-      return { results: ['result1', 'result2'] }
-    }
-  }
-}
+6. **Heads up** (only if non-obvious): 1-2 bullet points about common mistakes or surprising behavior. Omit entirely if there's nothing surprising.
 
-// Usage example
-const tool = createTool({
-  apiKey: process.env.MY_API_KEY || 'your-api-key-here'
-})
+Do NOT include a heading with the function/class name — start directly with the opening sentence.
+Do NOT write filler like "This is a powerful utility for..." — be direct.
+Do NOT just restate the function signature in prose — add information the signature doesn't convey.
 
-async function main() {
-  try {
-    const result = await tool.execute('my query')
-    console.log('Results:', result)
-    // Output: { results: ['result1', 'result2'] }
-  } catch (error) {
-    console.error('Failed:', error)
-  }
-}
-
-main()
-\`\`\`
+## Code Example
+Generate ONE self-contained, executable example:
+- Do NOT import from the library being documented — inline types and mock implementations
+- Use realistic data (real-looking API keys, user IDs, URLs)
+- Wrap async code in try/catch
+- End with console.log showing expected output
+- Short and focused — demonstrate the ONE primary use case
 
-Output format:
+## Output Format
 ---MARKDOWN---
-[Your markdown documentation with parameter table]
+[Documentation following the rules above]
 ---CODE---
-[Your SELF-CONTAINED, EXECUTABLE code example]
+[Self-contained example — no markdown fences]
 ---END---`;
 function buildDocPrompt(element, multiLanguage = false) {
-    let prompt = `Generate documentation for this ${element.kind}:\n\n`;
+    let prompt = '';
+    // Project context first — gives the LLM the "big picture" for better explanations
+    if (element.projectContext) {
+        prompt += `**Project context** (use this to explain WHY this ${element.kind} exists and how it fits in):\n`;
+        prompt += element.projectContext.slice(0, 1500) + '\n\n';
+    }
+    prompt += `Generate documentation for this ${element.kind}:\n\n`;
     prompt += `**Name:** ${element.name}\n`;
     prompt += `**Signature:** ${element.signature}\n`;
     if (element.parentClass) {
         prompt += `**Class:** ${element.parentClass}\n`;
     }
     if (element.packageName && element.packageName !== 'unknown') {
-        prompt += `**Package:** ${element.packageName} (DO NOT import from this - make example self-contained)\n`;
+        prompt += `**Package:** ${element.packageName} (DO NOT import from this — make example self-contained)\n`;
     }
     if (element.parameters.length > 0) {
         prompt += `\n**Parameters:**\n`;
@@ -232,21 +161,25 @@ function buildDocPrompt(element, multiLanguage = false) {
         prompt += `\n**Existing docstring:**\n${element.docstring}\n`;
     }
     if (element.sourceContext) {
-        prompt += `\n**Source context (for understanding, not for importing):**\n\`\`\`\n${element.sourceContext}\n\`\`\`\n`;
+        prompt += `\n**Source context (understand the code, but do NOT import from it):**\n\`\`\`\n${element.sourceContext}\n\`\`\`\n`;
     }
     if (element.imports && element.imports.length > 0) {
-        prompt += `\n**File imports (shows dependencies - your example should NOT use these):**\n`;
+        prompt += `\n**File imports (shows what this code depends on — do NOT use in examples):**\n`;
         prompt += element.imports.slice(0, 5).join('\n') + '\n';
     }
-    if (multiLanguage) {
-        prompt += `\n**IMPORTANT:** Generate BOTH TypeScript AND Python self-contained examples.`;
+    if (element.externalDocs) {
+        prompt += '\n**Third-party API reference (use for accurate API details):**\n';
+        prompt += element.externalDocs.slice(0, 3000) + '\n';
     }
-    else {
-        prompt += `\n**IMPORTANT:** Generate a SELF-CONTAINED example that runs without any external imports.`;
+    if (multiLanguage) {
+        prompt += `\nGenerate BOTH TypeScript AND Python self-contained examples.`;
     }
     return prompt;
 }
-function parseDocResponse(content) {
+function parseDocResponse(content, elementName) {
+    if (!content.includes('---MARKDOWN---')) {
+        console.warn(`  Warning: LLM response missing expected format for ${elementName ?? 'unknown'}`);
+    }
     // Extract markdown section
     const markdownMatch = content.match(/---MARKDOWN---\s*([\s\S]*?)\s*---CODE---/);
     const markdown = markdownMatch?.[1]?.trim() || content;
@@ -257,7 +190,10 @@ function parseDocResponse(content) {
     codeExample = codeExample.replace(/^```\w*\n?/, '').replace(/\n?```$/, '');
     return { markdown, codeExample, typescriptExample: codeExample };
 }
-function parseMultiLangResponse(content) {
+function parseMultiLangResponse(content, elementName) {
+    if (!content.includes('---MARKDOWN---')) {
+        console.warn(`  Warning: LLM response missing expected format for ${elementName ?? 'unknown'}`);
+    }
     // Extract markdown section
     const markdownMatch = content.match(/---MARKDOWN---\s*([\s\S]*?)\s*---TYPESCRIPT---/);
     const markdown = markdownMatch?.[1]?.trim() || '';
@@ -277,124 +213,3 @@ function parseMultiLangResponse(content) {
         pythonExample
     };
 }
-/**
- * Helper to fix a broken code sample with smart strategies
- */
-export async function fixCodeSample(client, code, error, context, iteration = 1) {
-    // Analyze error type to provide better fix guidance
-    const fixStrategy = analyzeErrorAndGetStrategy(error, code);
-    const response = await client.complete({
-        messages: [
-            {
-                role: 'system',
-                content: FIX_SYSTEM_PROMPT
-            },
-            {
-                role: 'user',
-                content: `Fix this code example. It must be COMPLETELY SELF-CONTAINED and runnable.
-
-**Current code:**
-\`\`\`
-${code}
-\`\`\`
-
-**Error:**
-${error}
-
-**Fix strategy:** ${fixStrategy}
-
-**Context:**
-${context}
-
-**Iteration ${iteration}:** ${iteration > 2 ? 'SIMPLIFY the example drastically - focus on demonstrating the concept, not real functionality.' : 'Make it self-contained.'}
-
-Return ONLY the fixed code, no explanations or markdown fences.`
-            }
-        ],
-        temperature: iteration > 3 ? 0.3 : 0, // Add creativity on later iterations
-        maxTokens: 1024
-    });
-    // Clean up any markdown fences
-    return response.content
-        .replace(/^```\w*\n?/, '')
-        .replace(/\n?```$/, '')
-        .trim();
-}
-const FIX_SYSTEM_PROMPT = `You are fixing a documentation code example to make it SELF-CONTAINED and RUNNABLE.
-
-## Fix Strategies by Error Type
-
-**Import/Module errors ("Cannot find module", "is not defined"):**
-- DO NOT try to fix the import
-- INLINE the type definitions
-- MOCK the function behavior with a simple implementation
-- Show what the function WOULD do conceptually
-
-**Type errors ("Type X is not assignable"):**
-- Define the type inline with \`type X = {...}\`
-- Use simpler types if complex ones cause issues
-
-**Runtime errors ("undefined is not a function", "Cannot read property"):**
-- Initialize all variables
-- Add null checks
-- Use optional chaining (?.)
-
-**Async errors ("await is only valid in async"):**
-- Wrap in async function
-- Add proper try/catch
-- Call the async function at the end
-
-## Example Fix Pattern
-If the error is "Cannot find module '@mylib/tools'":
-
-WRONG (trying to fix import):
-\`\`\`
-import { tool } from '@mylib/tools-v2' // Still fails
-\`\`\`
-
-RIGHT (inline everything):
-\`\`\`
-// Define types inline
-type ToolResult = { data: string[] }
-
-// Mock the tool behavior
-const tool = {
-  search: async (query: string): Promise<ToolResult> => {
-    // Simulated behavior
-    return { data: ['result1', 'result2'] }
-  }
-}
-
-// Usage
-async function main() {
-  const result = await tool.search('test')
-  console.log(result) // { data: ['result1', 'result2'] }
-}
-main()
-\`\`\`
-
-Return ONLY the fixed code.`;
-function analyzeErrorAndGetStrategy(error, _code) {
-    const errorLower = error.toLowerCase();
-    if (errorLower.includes('cannot find module') || errorLower.includes('module not found')) {
-        const importMatch = error.match(/['"]([^'"]+)['"]/)?.[1] || 'the library';
-        return `IMPORT ERROR: Cannot import from "${importMatch}". Remove ALL imports and inline types/mock functions instead.`;
-    }
-    if (errorLower.includes('is not defined') || errorLower.includes('is not a function')) {
-        const undefinedMatch = error.match(/(\w+) is not (defined|a function)/)?.[1];
-        return `UNDEFINED: "${undefinedMatch}" is not available. Define it inline or mock it.`;
-    }
-    if (errorLower.includes('type') && (errorLower.includes('assignable') || errorLower.includes('missing'))) {
-        return `TYPE ERROR: Type mismatch. Simplify types or define them inline with correct structure.`;
-    }
-    if (errorLower.includes('await') && errorLower.includes('async')) {
-        return `ASYNC ERROR: Wrap code in async function and call it: async function main() {...} main()`;
-    }
-    if (errorLower.includes('timeout') || errorLower.includes('timed out')) {
-        return `TIMEOUT: Code took too long. Remove any actual API calls or network requests. Use mock data.`;
-    }
-    if (errorLower.includes('syntaxerror') || errorLower.includes('unexpected token')) {
-        return `SYNTAX ERROR: Fix syntax issues. Check for missing brackets, quotes, or semicolons.`;
-    }
-    return `GENERAL: Make the code self-contained. Define all types inline, mock all external calls, use try/catch.`;
-}

package/dist/llm/openai-client.d.ts

@@ -9,6 +9,7 @@ export declare class OpenAICompatibleClient implements LLMClient {
     private client;
     private model;
     private maxRetries;
+    private apiKey;
     constructor(config: LLMClientConfig);
     isConfigured(): boolean;
     complete(request: CompletionRequest): Promise<CompletionResponse>;

package/dist/llm/openai-client.js

@@ -9,14 +9,19 @@ export class OpenAICompatibleClient {
     client;
     model;
     maxRetries;
+    apiKey;
     constructor(config) {
         this.provider = config.provider;
         this.model = config.model;
         this.maxRetries = config.maxRetries ?? 3;
         const baseURL = config.baseUrl || PROVIDER_BASE_URLS[config.provider];
         const extraHeaders = PROVIDER_EXTRA_HEADERS[config.provider] || {};
+        // Ollama doesn't need a real key; other providers get empty string
+        // (SDK validates on first request, not construction)
+        const effectiveKey = config.apiKey || (config.provider === 'ollama' ? 'ollama' : 'not-set');
+        this.apiKey = effectiveKey;
         this.client = new OpenAI({
-            apiKey: config.apiKey || 'ollama', // Ollama doesn't need a real key
+            apiKey: effectiveKey,
             baseURL,
             timeout: config.timeout ?? 60000,
             maxRetries: this.maxRetries,
@@ -24,7 +29,7 @@ export class OpenAICompatibleClient {
         });
     }
     isConfigured() {
-        return true; // OpenAI SDK handles validation
+        return this.apiKey !== '' && this.apiKey !== 'not-set';
     }
     async complete(request) {
         const model = request.model || this.model;

package/dist/plugins/index.js

@@ -23,6 +23,8 @@ export class PluginManager {
         if (!configFile)
             return;
         try {
+            console.log(`  Loading config: ${configFile}`);
+            console.warn('  ⚠ Plugin configs execute code — only load trusted files');
             const configUrl = pathToFileURL(configFile).href;
             const module = await import(configUrl);
             const config = module.default || module;
@@ -57,6 +59,11 @@ export class PluginManager {
         return null;
     }
     async loadPluginByName(name) {
+        // Validate plugin name — must be a valid npm package name, no path traversal
+        if (!/^(@[a-zA-Z0-9._-]+\/)?[a-zA-Z0-9._-]+$/.test(name)) {
+            console.warn(`Skipping plugin with invalid name: ${name}`);
+            return;
+        }
         // Try to load from node_modules
         try {
             const module = await import(name);

package/dist/qa/checks.d.ts

@@ -0,0 +1,10 @@
+import type { QAIssue } from './types.js';
+export declare function checkFrontmatter(filePath: string, content: string, relPath: string): QAIssue[];
+export declare function checkHeadings(content: string, relPath: string): QAIssue[];
+export declare function checkCodeBlocks(content: string, relPath: string): QAIssue[];
+export declare function checkComponents(content: string, relPath: string): QAIssue[];
+export declare function checkLinks(content: string, relPath: string, _allFiles: Set<string>): QAIssue[];
+export declare function checkSecurity(content: string, relPath: string): QAIssue[];
+export declare function checkContentQuality(content: string, relPath: string): QAIssue[];
+export declare function checkScreenshots(content: string, relPath: string, outputDir: string): QAIssue[];
+export declare function checkMdxSyntax(content: string, relPath: string): QAIssue[];