skrypt-ai 0.5.0 → 0.6.0

package/dist/auth/index.js

@@ -121,7 +121,14 @@ export async function checkPlan(apiKey) {
         if (typeof data.valid !== 'boolean' || typeof data.email !== 'string') {
             return { valid: false, plan: 'free', email: '', error: 'Invalid API response' };
         }
-        return data;
+        const plan = data.plan === 'pro' ? 'pro' : 'free';
+        return {
+            valid: data.valid,
+            plan,
+            email: data.email,
+            expiresAt: typeof data.expiresAt === 'string' ? data.expiresAt : undefined,
+            error: typeof data.error === 'string' ? data.error : undefined,
+        };
     }
     catch {
         return { valid: false, plan: 'free', email: '', error: 'Failed to connect to API' };

package/dist/autofix/index.d.ts

@@ -32,10 +32,6 @@ export interface ValidationResult {
  * 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
  */

package/dist/autofix/index.js

@@ -152,27 +152,6 @@ function extractCode(response, language) {
         return null;
     return joined;
 }
-/**
- * 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
  */

package/dist/capture/browser.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Playwright wrapper for screenshot capture.
+ *
+ * Dynamically imports Playwright (optional dependency).
+ * Only allows localhost URLs by default for security.
+ */
+import type { ScreenshotDirective, ScreenshotResult, CaptureOptions } from './types.js';
+/**
+ * Capture screenshots for a batch of directives.
+ */
+export declare function captureScreenshots(directives: ScreenshotDirective[], options: CaptureOptions): Promise<ScreenshotResult[]>;

package/dist/capture/browser.js

@@ -0,0 +1,173 @@
+/**
+ * Playwright wrapper for screenshot capture.
+ *
+ * Dynamically imports Playwright (optional dependency).
+ * Only allows localhost URLs by default for security.
+ */
+import { screenshotFilename, darkVariantFilename } from './naming.js';
+import { computeHash } from './diff.js';
+const ALLOWED_HOSTS = new Set(['localhost', '127.0.0.1', '::1']);
+/**
+ * Dynamically import Playwright. Exits with clear instructions if not installed.
+ */
+async function ensurePlaywright() {
+    try {
+        // Dynamic import — playwright is optional
+        const mod = await Function('return import("playwright")')();
+        return mod;
+    }
+    catch {
+        throw new Error('Playwright is required for screenshot capture. Install it: npx playwright install chromium');
+    }
+}
+/**
+ * Validate that a URL is on an allowed host (localhost by default).
+ */
+function validateUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return { valid: ALLOWED_HOSTS.has(parsed.hostname), host: parsed.hostname };
+    }
+    catch {
+        return { valid: false, host: '' };
+    }
+}
+/**
+ * Capture screenshots for a batch of directives.
+ */
+export async function captureScreenshots(directives, options) {
+    const pw = await ensurePlaywright();
+    const results = [];
+    const browser = await pw.chromium.launch({ headless: true });
+    try {
+        // Process with concurrency limit
+        const chunks = [];
+        for (let i = 0; i < directives.length; i += options.concurrency) {
+            chunks.push(directives.slice(i, i + options.concurrency));
+        }
+        for (const chunk of chunks) {
+            const chunkResults = await Promise.all(chunk.map(directive => captureOne(browser, directive, options, pw)));
+            results.push(...chunkResults);
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    return results;
+}
+/**
+ * Capture a single screenshot.
+ */
+async function captureOne(browser, directive, options, pw) {
+    const start = Date.now();
+    const filename = screenshotFilename(directive.url, directive.selector);
+    // Security check
+    const { valid, host } = validateUrl(directive.url);
+    if (!valid) {
+        return {
+            directive,
+            filename,
+            status: 'failed',
+            error: `URL host "${host}" not allowed. Only localhost, 127.0.0.1, and ::1 are permitted.`,
+            duration: Date.now() - start,
+        };
+    }
+    // Build context options
+    const contextOpts = {
+        viewport: options.viewport,
+    };
+    // Device emulation
+    if (options.device) {
+        const device = pw.devices[options.device];
+        if (device) {
+            contextOpts.viewport = device.viewport;
+            contextOpts.userAgent = device.userAgent;
+            contextOpts.deviceScaleFactor = device.deviceScaleFactor;
+            contextOpts.isMobile = device.isMobile;
+            contextOpts.hasTouch = device.hasTouch;
+        }
+    }
+    const context = await browser.newContext(contextOpts);
+    const page = await context.newPage();
+    try {
+        // Navigate
+        await page.goto(directive.url, {
+            waitUntil: 'networkidle',
+            timeout: options.timeout,
+        });
+        // Wait for settle time
+        await page.waitForTimeout(options.wait);
+        // Capture light mode screenshot
+        let buffer;
+        if (directive.selector) {
+            const locator = page.locator(directive.selector);
+            const visible = await locator.isVisible();
+            if (!visible) {
+                return {
+                    directive,
+                    filename,
+                    status: 'failed',
+                    error: `Selector "${directive.selector}" not found or not visible on ${directive.url}`,
+                    duration: Date.now() - start,
+                };
+            }
+            buffer = await locator.screenshot({ type: 'png' });
+        }
+        else {
+            buffer = await page.screenshot({ fullPage: true, type: 'png' });
+        }
+        const hash = computeHash(buffer);
+        const result = {
+            directive,
+            filename,
+            status: 'captured',
+            hash,
+            duration: Date.now() - start,
+        };
+        // Dark mode capture
+        if (options.dark) {
+            try {
+                await page.emulateMedia({ colorScheme: 'dark' });
+                await page.evaluate(() => {
+                    document.documentElement.classList.add('dark');
+                });
+                await page.waitForTimeout(500);
+                let darkBuffer;
+                if (directive.selector) {
+                    darkBuffer = await page.locator(directive.selector).screenshot({ type: 'png' });
+                }
+                else {
+                    darkBuffer = await page.screenshot({ fullPage: true, type: 'png' });
+                }
+                result.darkFilename = darkVariantFilename(filename);
+                result._buffers = {
+                    light: buffer,
+                    dark: darkBuffer,
+                };
+            }
+            catch {
+                // Dark mode capture failed — continue with light only
+            }
+        }
+        // Store light buffer for the orchestrator
+        if (!result._buffers) {
+            ;
+            result._buffer = buffer;
+        }
+        return result;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            directive,
+            filename,
+            status: 'failed',
+            error: message,
+            duration: Date.now() - start,
+        };
+    }
+    finally {
+        await page.close();
+        await context.close();
+    }
+}

package/dist/capture/diff.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Hash-based change detection for screenshots.
+ *
+ * Stores SHA-256 hashes in .skrypt/screenshot-hashes.json (project root).
+ * Used with --diff flag to skip re-capturing unchanged screenshots.
+ */
+export type HashStore = Record<string, string>;
+/**
+ * Compute SHA-256 hash of a buffer.
+ */
+export declare function computeHash(buffer: Buffer): string;
+/**
+ * Load the hash store from .skrypt/screenshot-hashes.json in the project directory.
+ */
+export declare function loadHashStore(projectDir: string): HashStore;
+/**
+ * Save the hash store to .skrypt/screenshot-hashes.json in the project directory.
+ */
+export declare function saveHashStore(projectDir: string, store: HashStore): void;
+/**
+ * Check if a screenshot has changed based on its hash.
+ */
+export declare function hasChanged(filename: string, newHash: string, store: HashStore): boolean;

package/dist/capture/diff.js

@@ -0,0 +1,52 @@
+/**
+ * Hash-based change detection for screenshots.
+ *
+ * Stores SHA-256 hashes in .skrypt/screenshot-hashes.json (project root).
+ * Used with --diff flag to skip re-capturing unchanged screenshots.
+ */
+import { createHash } from 'crypto';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+const HASH_FILE = 'screenshot-hashes.json';
+const STORE_DIR = '.skrypt';
+/**
+ * Compute SHA-256 hash of a buffer.
+ */
+export function computeHash(buffer) {
+    return createHash('sha256').update(buffer).digest('hex');
+}
+/**
+ * Load the hash store from .skrypt/screenshot-hashes.json in the project directory.
+ */
+export function loadHashStore(projectDir) {
+    const storePath = join(projectDir, STORE_DIR, HASH_FILE);
+    if (!existsSync(storePath)) {
+        return {};
+    }
+    try {
+        const content = readFileSync(storePath, 'utf-8');
+        const parsed = JSON.parse(content);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Save the hash store to .skrypt/screenshot-hashes.json in the project directory.
+ */
+export function saveHashStore(projectDir, store) {
+    const storeDir = join(projectDir, STORE_DIR);
+    mkdirSync(storeDir, { recursive: true });
+    const storePath = join(storeDir, HASH_FILE);
+    writeFileSync(storePath, JSON.stringify(store, null, 2), 'utf-8');
+}
+/**
+ * Check if a screenshot has changed based on its hash.
+ */
+export function hasChanged(filename, newHash, store) {
+    return store[filename] !== newHash;
+}

package/dist/capture/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Screenshot capture orchestrator.
+ *
+ * Coordinates MDX parsing, browser capture, diff detection, and file output.
+ */
+import type { CaptureOptions, CaptureReport } from './types.js';
+export type { CaptureOptions, CaptureReport } from './types.js';
+/**
+ * Run the screenshot capture pipeline.
+ *
+ * 1. Find all MDX files in docsDir
+ * 2. Parse <Screenshot> directives from each
+ * 3. Validate base URL reachability
+ * 4. Capture screenshots via headless browser
+ * 5. Compare hashes for --diff mode
+ * 6. Write changed files to outputDir
+ * 7. Write manifest and hash store
+ */
+export declare function runCapture(docsDir: string, options: CaptureOptions): Promise<CaptureReport>;
+/**
+ * Print a capture report to stdout.
+ */
+export declare function printCaptureReport(report: CaptureReport): void;

package/dist/capture/index.js

@@ -0,0 +1,210 @@
+/**
+ * Screenshot capture orchestrator.
+ *
+ * Coordinates MDX parsing, browser capture, diff detection, and file output.
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, resolve } from 'path';
+import { findMdxFiles } from '../utils/files.js';
+import { parseScreenshotDirectives } from './parser.js';
+import { captureScreenshots } from './browser.js';
+import { loadHashStore, saveHashStore, computeHash, hasChanged } from './diff.js';
+/**
+ * Run the screenshot capture pipeline.
+ *
+ * 1. Find all MDX files in docsDir
+ * 2. Parse <Screenshot> directives from each
+ * 3. Validate base URL reachability
+ * 4. Capture screenshots via headless browser
+ * 5. Compare hashes for --diff mode
+ * 6. Write changed files to outputDir
+ * 7. Write manifest and hash store
+ */
+export async function runCapture(docsDir, options) {
+    const startTime = Date.now();
+    const resolvedDocsDir = resolve(docsDir);
+    const resolvedOutputDir = resolve(options.outputDir);
+    // 1. Find MDX files
+    const mdxFiles = findMdxFiles(resolvedDocsDir);
+    // 2. Parse directives
+    const allDirectives = mdxFiles.flatMap(filePath => {
+        const content = readFileSync(filePath, 'utf-8');
+        return parseScreenshotDirectives(content, filePath, options.baseUrl);
+    });
+    if (allDirectives.length === 0) {
+        return {
+            directives: 0,
+            captured: 0,
+            unchanged: 0,
+            failed: 0,
+            duration: Date.now() - startTime,
+            results: [],
+        };
+    }
+    // 3. Dry run
+    if (options.dryRun) {
+        console.log(`\n  Found ${allDirectives.length} screenshot directive(s):`);
+        for (const d of allDirectives) {
+            const sel = d.selector ? ` (${d.selector})` : ' (full page)';
+            console.log(`    ${d.url}${sel} → ${d.alt}`);
+        }
+        console.log('\n  [dry run — no files written]\n');
+        return {
+            directives: allDirectives.length,
+            captured: 0,
+            unchanged: 0,
+            failed: 0,
+            duration: Date.now() - startTime,
+            results: [],
+        };
+    }
+    // 4. Validate base URL reachability
+    try {
+        const response = await fetch(options.baseUrl, {
+            method: 'HEAD',
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!response.ok) {
+            console.error(`\n  Base URL ${options.baseUrl} returned ${response.status}`);
+            console.error('  Make sure your dev server is running.\n');
+            return {
+                directives: allDirectives.length,
+                captured: 0,
+                unchanged: 0,
+                failed: allDirectives.length,
+                duration: Date.now() - startTime,
+                results: [],
+            };
+        }
+    }
+    catch {
+        console.error(`\n  Cannot reach ${options.baseUrl}`);
+        console.error('  Start your dev server first, then run heal again.\n');
+        return {
+            directives: allDirectives.length,
+            captured: 0,
+            unchanged: 0,
+            failed: allDirectives.length,
+            duration: Date.now() - startTime,
+            results: [],
+        };
+    }
+    // 5. Load hash store for diff mode
+    const projectDir = resolvedDocsDir;
+    const hashStore = options.diff ? loadHashStore(projectDir) : {};
+    // 6. Capture all screenshots
+    console.log(`\n  Capturing ${allDirectives.length} screenshot(s)...`);
+    const results = await captureScreenshots(allDirectives, options);
+    // 7. Process results — write files, check diffs
+    mkdirSync(resolvedOutputDir, { recursive: true });
+    let captured = 0;
+    let unchanged = 0;
+    let failed = 0;
+    const newHashStore = { ...hashStore };
+    const manifestEntries = {};
+    for (const result of results) {
+        if (result.status === 'failed') {
+            failed++;
+            continue;
+        }
+        const lightBuffer = getBuffer(result, 'light');
+        if (!lightBuffer) {
+            failed++;
+            result.status = 'failed';
+            result.error = 'No screenshot data captured';
+            continue;
+        }
+        const hash = computeHash(lightBuffer);
+        // Diff check
+        if (options.diff && !hasChanged(result.filename, hash, hashStore)) {
+            unchanged++;
+            result.status = 'unchanged';
+            continue;
+        }
+        // Write light screenshot
+        const outputPath = join(resolvedOutputDir, result.filename);
+        writeFileSync(outputPath, lightBuffer);
+        newHashStore[result.filename] = hash;
+        captured++;
+        // Write dark variant if present
+        if (result.darkFilename) {
+            const darkBuffer = getBuffer(result, 'dark');
+            if (darkBuffer) {
+                const darkPath = join(resolvedOutputDir, result.darkFilename);
+                writeFileSync(darkPath, darkBuffer);
+                newHashStore[result.darkFilename] = computeHash(darkBuffer);
+            }
+        }
+        // Build manifest entry
+        manifestEntries[result.filename] = {
+            url: result.directive.url,
+            selector: result.directive.selector,
+            filename: result.filename,
+            darkFilename: result.darkFilename,
+            capturedAt: new Date().toISOString(),
+            hash,
+        };
+    }
+    // 8. Write manifest
+    const manifest = {
+        version: 1,
+        capturedAt: new Date().toISOString(),
+        baseUrl: options.baseUrl,
+        viewport: options.viewport,
+        screenshots: manifestEntries,
+    };
+    writeFileSync(join(resolvedOutputDir, '_manifest.json'), JSON.stringify(manifest, null, 2), 'utf-8');
+    // 9. Save hash store
+    if (options.diff) {
+        saveHashStore(projectDir, newHashStore);
+    }
+    return {
+        directives: allDirectives.length,
+        captured,
+        unchanged,
+        failed,
+        duration: Date.now() - startTime,
+        results,
+    };
+}
+/**
+ * Extract buffer from result (stored as internal _buffer or _buffers property).
+ */
+function getBuffer(result, variant) {
+    const r = result;
+    if (r._buffers) {
+        return variant === 'light' ? r._buffers.light : r._buffers.dark;
+    }
+    if (variant === 'light' && r._buffer) {
+        return r._buffer;
+    }
+    return null;
+}
+/**
+ * Print a capture report to stdout.
+ */
+export function printCaptureReport(report) {
+    if (report.directives === 0) {
+        console.log('\n  No <Screenshot> directives found in docs.\n');
+        return;
+    }
+    const parts = [];
+    if (report.captured > 0)
+        parts.push(`${report.captured} captured`);
+    if (report.unchanged > 0)
+        parts.push(`${report.unchanged} unchanged`);
+    if (report.failed > 0)
+        parts.push(`${report.failed} failed`);
+    console.log(`\n  Screenshots: ${parts.join(', ')} (${report.duration}ms)`);
+    // Show failures
+    const failures = report.results.filter(r => r.status === 'failed');
+    for (const f of failures) {
+        const loc = f.directive.selector
+            ? `${f.directive.url} (${f.directive.selector})`
+            : f.directive.url;
+        console.log(`    ✗ ${loc}: ${f.error}`);
+    }
+    if (report.captured > 0) {
+        console.log('');
+    }
+}

package/dist/capture/naming.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Deterministic screenshot filename generation.
+ *
+ * Derives stable, human-readable filenames from URL + optional CSS selector.
+ *
+ * Examples:
+ *   /dashboard + .billing-panel  → dashboard--billing-panel.png
+ *   /settings/account + #profile → settings-account--profile.png
+ *   /dashboard (no selector)     → dashboard.png
+ */
+export declare function screenshotFilename(url: string, selector?: string): string;
+/**
+ * Dark mode variant filename.
+ * dashboard.png → dashboard-dark.png
+ * dashboard--panel.png → dashboard--panel-dark.png
+ */
+export declare function darkVariantFilename(filename: string): string;

package/dist/capture/naming.js

@@ -0,0 +1,45 @@
+/**
+ * Deterministic screenshot filename generation.
+ *
+ * Derives stable, human-readable filenames from URL + optional CSS selector.
+ *
+ * Examples:
+ *   /dashboard + .billing-panel  → dashboard--billing-panel.png
+ *   /settings/account + #profile → settings-account--profile.png
+ *   /dashboard (no selector)     → dashboard.png
+ */
+export function screenshotFilename(url, selector) {
+    // Extract pathname from full URL or use as-is if just a path
+    let pathname;
+    try {
+        pathname = new URL(url).pathname;
+    }
+    catch {
+        pathname = url;
+    }
+    // Strip leading /
+    let slug = pathname.replace(/^\/+/, '');
+    // Replace / with -
+    slug = slug.replace(/\//g, '-');
+    // If empty (root path), use "index"
+    if (!slug)
+        slug = 'index';
+    // Sanitize: only keep alphanumeric and hyphens
+    slug = slug.replace(/[^a-zA-Z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+    if (selector) {
+        // Strip CSS selector prefix (. or #)
+        let selectorSlug = selector.replace(/^[.#]/, '');
+        // Sanitize selector the same way
+        selectorSlug = selectorSlug.replace(/[^a-zA-Z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+        slug = `${slug}--${selectorSlug}`;
+    }
+    return `${slug}.png`;
+}
+/**
+ * Dark mode variant filename.
+ * dashboard.png → dashboard-dark.png
+ * dashboard--panel.png → dashboard--panel-dark.png
+ */
+export function darkVariantFilename(filename) {
+    return filename.replace(/\.png$/, '-dark.png');
+}

package/dist/capture/parser.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Extract <Screenshot> directives from MDX files.
+ *
+ * Scans MDX content for <Screenshot> tags outside code blocks.
+ * Uses the same code-block-aware scanning pattern as src/qa/checks.ts.
+ */
+import type { ScreenshotDirective } from './types.js';
+/**
+ * Parse all <Screenshot> directives from MDX content.
+ *
+ * Supports both self-closing (<Screenshot ... />) and open/close tags.
+ * Extracts url, selector, alt, caption props via regex.
+ * Resolves relative URLs against baseUrl.
+ */
+export declare function parseScreenshotDirectives(content: string, filePath: string, baseUrl: string): ScreenshotDirective[];