skrypt-ai 0.4.2 → 0.6.0

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

package/dist/capture/parser.js

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function parseScreenshotDirectives(content, filePath, baseUrl) {
+    const directives = [];
+    const lines = content.split('\n');
+    let inCodeBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        if (line.startsWith('```')) {
+            inCodeBlock = !inCodeBlock;
+            continue;
+        }
+        if (inCodeBlock)
+            continue;
+        // Match <Screenshot ...> or <Screenshot ... />
+        const tagMatches = line.matchAll(/<Screenshot\s+([^>]*?)\/?>/g);
+        for (const match of tagMatches) {
+            const propsStr = match[1];
+            if (!propsStr)
+                continue;
+            const url = extractProp(propsStr, 'url');
+            const alt = extractProp(propsStr, 'alt');
+            if (!url || !alt)
+                continue;
+            const selector = extractProp(propsStr, 'selector');
+            const caption = extractProp(propsStr, 'caption');
+            // Resolve relative URLs against baseUrl
+            let resolvedUrl;
+            if (url.startsWith('http://') || url.startsWith('https://')) {
+                resolvedUrl = url;
+            }
+            else {
+                // Ensure baseUrl doesn't have trailing slash for clean join
+                const base = baseUrl.replace(/\/+$/, '');
+                const path = url.startsWith('/') ? url : `/${url}`;
+                resolvedUrl = `${base}${path}`;
+            }
+            directives.push({
+                url: resolvedUrl,
+                selector: selector || undefined,
+                alt,
+                caption: caption || undefined,
+                sourceFile: filePath,
+                sourceLine: i + 1,
+            });
+        }
+    }
+    return directives;
+}
+/**
+ * Extract a prop value from a JSX props string.
+ * Handles both quoted values: prop="value" and prop='value'
+ * Also handles JSX expressions: prop={"value"} and prop={'value'}
+ */
+function extractProp(propsStr, propName) {
+    // Match prop="value" or prop='value'
+    const quoteRegex = new RegExp(`${propName}\\s*=\\s*["']([^"']*?)["']`);
+    const quoteMatch = propsStr.match(quoteRegex);
+    if (quoteMatch?.[1] !== undefined)
+        return quoteMatch[1];
+    // Match prop={"value"} or prop={'value'}
+    const jsxRegex = new RegExp(`${propName}\\s*=\\s*\\{\\s*["']([^"']*?)["']\\s*\\}`);
+    const jsxMatch = propsStr.match(jsxRegex);
+    if (jsxMatch?.[1] !== undefined)
+        return jsxMatch[1];
+    return null;
+}

package/dist/capture/types.d.ts

@@ -0,0 +1,57 @@
+export interface ScreenshotDirective {
+    url: string;
+    selector?: string;
+    alt: string;
+    caption?: string;
+    sourceFile: string;
+    sourceLine: number;
+}
+export interface ScreenshotResult {
+    directive: ScreenshotDirective;
+    filename: string;
+    darkFilename?: string;
+    status: 'captured' | 'unchanged' | 'failed';
+    error?: string;
+    hash?: string;
+    duration: number;
+}
+export interface CaptureReport {
+    directives: number;
+    captured: number;
+    unchanged: number;
+    failed: number;
+    duration: number;
+    results: ScreenshotResult[];
+}
+export interface ScreenshotManifest {
+    version: 1;
+    capturedAt: string;
+    baseUrl: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    screenshots: Record<string, {
+        url: string;
+        selector?: string;
+        filename: string;
+        darkFilename?: string;
+        capturedAt: string;
+        hash: string;
+    }>;
+}
+export interface CaptureOptions {
+    baseUrl: string;
+    outputDir: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    dark: boolean;
+    diff: boolean;
+    dryRun: boolean;
+    timeout: number;
+    wait: number;
+    device?: string;
+    concurrency: number;
+}

package/dist/capture/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -6,6 +6,7 @@ import { watchCommand } from './commands/watch.js';
 import { autofixCommand } from './commands/autofix.js';
 import { reviewPRCommand } from './commands/review-pr.js';
 import { lintCommand } from './commands/lint.js';
+import { qaCommand } from './commands/qa.js';
 import { checkLinksCommand } from './commands/check-links.js';
 import { mcpCommand } from './commands/mcp.js';
 import { versionCommand } from './commands/version.js';
@@ -18,6 +19,9 @@ import { loginCommand, logoutCommand, whoamiCommand } from './commands/login.js'
 import { cronCommand } from './commands/cron.js';
 import { deployCommand } from './commands/deploy.js';
 import { testCommand } from './commands/test.js';
+import { securityCommand } from './commands/security.js';
+import { importCommand } from './commands/import.js';
+import { healCommand } from './commands/heal.js';
 import { createRequire } from 'module';
 process.on('uncaughtException', (err) => {
     console.error('\x1b[31mFatal error:\x1b[0m', err.message);
@@ -33,6 +37,16 @@ process.on('unhandledRejection', (reason) => {
 });
 const require = createRequire(import.meta.url);
 const { version: VERSION } = require('../package.json');
+function semverNewer(latest, current) {
+    const parse = (v) => v.split('.').map(Number);
+    const [lMaj, lMin, lPatch] = parse(latest);
+    const [cMaj, cMin, cPatch] = parse(current);
+    if (lMaj !== cMaj)
+        return lMaj > cMaj;
+    if (lMin !== cMin)
+        return lMin > cMin;
+    return lPatch > cPatch;
+}
 async function checkForUpdates() {
     try {
         const res = await fetch('https://registry.npmjs.org/skrypt-ai/latest', {
@@ -41,9 +55,8 @@ async function checkForUpdates() {
         if (res.ok) {
             const data = await res.json();
             const version = data.version;
-            if (typeof version === 'string' && /^\d+\.\d+\.\d+/.test(version) && version !== VERSION) {
-                const latest = version;
-                console.log(`\n  Update available: ${VERSION} → ${latest}`);
+            if (typeof version === 'string' && /^\d+\.\d+\.\d+$/.test(version) && semverNewer(version, VERSION)) {
+                console.log(`\n  Update available: ${VERSION} → ${version}`);
                 console.log(`  Run: npm install -g skrypt-ai@latest\n`);
             }
         }
@@ -66,6 +79,7 @@ program.addCommand(watchCommand);
 program.addCommand(autofixCommand);
 program.addCommand(reviewPRCommand);
 program.addCommand(lintCommand);
+program.addCommand(qaCommand);
 program.addCommand(checkLinksCommand);
 program.addCommand(mcpCommand);
 program.addCommand(versionCommand);
@@ -80,4 +94,7 @@ program.addCommand(whoamiCommand);
 program.addCommand(cronCommand);
 program.addCommand(deployCommand);
 program.addCommand(testCommand);
+program.addCommand(securityCommand);
+program.addCommand(importCommand);
+program.addCommand(healCommand);
 program.parse();