skrypt-ai 0.6.1 → 0.8.0

package/dist/template/src/middleware.ts

@@ -0,0 +1,101 @@
+import { NextRequest, NextResponse } from 'next/server'
+
+/**
+ * Content negotiation middleware for AI agents.
+ *
+ * When agents send `Accept: text/markdown`, rewrite to the markdown route handler.
+ * Also handles `.md` URL suffix for explicit markdown requests.
+ * Adds Link + X-Llms-Txt discovery headers to all responses.
+ */
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl
+
+  // Skip non-doc paths: API routes, static assets, internal Next.js paths
+  if (
+    pathname.startsWith('/api/') ||
+    pathname.startsWith('/_next/') ||
+    pathname.startsWith('/reference') ||
+    pathname === '/robots.txt' ||
+    pathname === '/sitemap.xml' ||
+    pathname === '/llms.txt' ||
+    pathname === '/llms-full.md' ||
+    pathname === '/favicon.ico' ||
+    /\.(ico|png|jpg|jpeg|gif|svg|webp|woff2?|ttf|css|js|map)$/.test(pathname)
+  ) {
+    return addDiscoveryHeaders(NextResponse.next(), request)
+  }
+
+  // Handle .md URL suffix: /docs/getting-started.md → serve markdown for /docs/getting-started
+  if (pathname.endsWith('.md') && pathname.startsWith('/docs/')) {
+    const cleanPath = pathname.slice(0, -3) // strip .md
+    const slug = cleanPath.replace(/^\/docs\/?/, '')
+    if (slug) {
+      const url = request.nextUrl.clone()
+      url.pathname = `/md/${slug}`
+      return addDiscoveryHeaders(NextResponse.rewrite(url), request)
+    }
+  }
+
+  // Content negotiation: detect Accept: text/markdown
+  const accept = request.headers.get('accept') || ''
+  if (prefersMarkdown(accept) && pathname.startsWith('/docs/')) {
+    const slug = pathname.replace(/^\/docs\/?/, '')
+    if (slug) {
+      const url = request.nextUrl.clone()
+      url.pathname = `/md/${slug}`
+      return addDiscoveryHeaders(NextResponse.rewrite(url), request)
+    }
+  }
+
+  return addDiscoveryHeaders(NextResponse.next(), request)
+}
+
+/**
+ * Check if the Accept header prefers text/markdown over text/html.
+ * Handles quality values: text/markdown;q=1.0, text/html;q=0.9
+ */
+function prefersMarkdown(accept: string): boolean {
+  if (!accept) return false
+
+  const lower = accept.toLowerCase()
+
+  // Quick check: if text/markdown appears at all
+  if (!lower.includes('text/markdown')) return false
+
+  // Parse quality values
+  let mdQuality = 0
+  let htmlQuality = 0
+
+  for (const part of lower.split(',')) {
+    const trimmed = part.trim()
+    const qMatch = trimmed.match(/;q=([0-9.]+)/)
+    const quality = qMatch ? Math.min(parseFloat(qMatch[1]) || 0, 1.0) : 1.0
+
+    if (trimmed.startsWith('text/markdown')) {
+      mdQuality = quality
+    } else if (trimmed.startsWith('text/html')) {
+      htmlQuality = quality
+    }
+  }
+
+  return mdQuality > 0 && mdQuality >= htmlQuality
+}
+
+/**
+ * Add agent discovery headers to every response.
+ * - Link: points agents to llms.txt
+ * - X-Llms-Txt: explicit pointer for agent tooling
+ */
+function addDiscoveryHeaders(response: NextResponse, request: NextRequest): NextResponse {
+  const origin = request.nextUrl.origin
+  response.headers.set('Link', `<${origin}/llms.txt>; rel="help", <${origin}/llms-full.md>; rel="help"`)
+  response.headers.set('X-Llms-Txt', `${origin}/llms.txt`)
+  return response
+}
+
+export const config = {
+  matcher: [
+    // Match all paths except static files
+    '/((?!_next/static|_next/image).*)',
+  ],
+}

package/dist/template/src/styles/globals.css

@@ -58,10 +58,10 @@
   --color-border: rgba(3, 7, 18, 0.1);
   --color-border-strong: rgba(3, 7, 18, 0.15);
 
-  /* Code */
-  --color-code-bg: #ffffff;
+  /* Code — high-contrast, matching Mintlify/Stripe/Vercel standards */
+  --color-code-bg: #fafafa;
   --color-code-border: rgba(3, 7, 18, 0.1);
-  --color-code-text: #1f2937;
+  --color-code-text: #1a1a2e;
 
   /* Layout */
   --sidebar-width: 264px;
@@ -80,14 +80,14 @@
     --color-bg: #0f1117;
     --color-bg-secondary: #1a1d27;
     --color-bg-tertiary: #252833;
-    --color-text: #e0e2e6;
-    --color-text-secondary: #b0b4bc;
+    --color-text: #e4e5e9;
+    --color-text-secondary: #b4b8c1;
     --color-text-tertiary: #6b7280;
     --color-border: rgba(255, 255, 255, 0.07);
     --color-border-strong: rgba(255, 255, 255, 0.12);
-    --color-code-bg: #0b0c0e;
-    --color-code-border: rgba(255, 255, 255, 0.1);
-    --color-code-text: #e0e2e6;
+    --color-code-bg: #0a0a0c;
+    --color-code-border: rgba(255, 255, 255, 0.08);
+    --color-code-text: #e8eaed;
   }
 }
 
@@ -95,14 +95,14 @@
   --color-bg: #0f1117;
   --color-bg-secondary: #1a1d27;
   --color-bg-tertiary: #252833;
-  --color-text: #e0e2e6;
-  --color-text-secondary: #b0b4bc;
+  --color-text: #e4e5e9;
+  --color-text-secondary: #b4b8c1;
   --color-text-tertiary: #6b7280;
   --color-border: rgba(255, 255, 255, 0.07);
   --color-border-strong: rgba(255, 255, 255, 0.12);
-  --color-code-bg: #0b0c0e;
-  --color-code-border: rgba(255, 255, 255, 0.1);
-  --color-code-text: #e0e2e6;
+  --color-code-bg: #0a0a0c;
+  --color-code-border: rgba(255, 255, 255, 0.08);
+  --color-code-text: #e8eaed;
 }
 
 /* Error page icon — dark mode overrides (avoids Tailwind dark: variant mismatch) */
@@ -205,33 +205,41 @@ pre {
   background-color: var(--color-code-bg) !important;
 }
 
+/* Ensure Shiki syntax tokens render at full opacity — never washed out */
+.shiki code {
+  color: var(--color-code-text);
+}
+.shiki .line span {
+  opacity: 1 !important;
+}
+
 code {
-  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+  font-family: var(--font-mono, ui-monospace), SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
   font-size: 0.875em;
   font-variant-ligatures: none;
 }
 
-/* Inline code — Mintlify style */
+/* Inline code — high contrast, Mintlify/Stripe style */
 :not(pre) > code {
   background-color: var(--color-gray-100);
   padding: 0.125rem 0.5rem;
   border-radius: 0.375rem;
   font-size: 0.875em;
   line-height: 1.5;
-  color: var(--color-gray-600);
+  color: var(--color-gray-800);
   overflow-wrap: break-word;
   word-break: break-word;
 }
 
 :root.dark :not(pre) > code {
-  background-color: rgba(255, 255, 255, 0.05);
-  color: var(--color-gray-200);
+  background-color: rgba(255, 255, 255, 0.08);
+  color: #e0e2e6;
 }
 
 @media (prefers-color-scheme: dark) {
   :root:not(.light) :not(pre) > code {
-    background-color: rgba(255, 255, 255, 0.05);
-    color: var(--color-gray-200);
+    background-color: rgba(255, 255, 255, 0.08);
+    color: #e0e2e6;
   }
 }
 

package/dist/testing/comparator.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Compare actual output against expected output
+ */
+export declare function compareOutput(actual: string, expected: string, mode?: 'exact' | 'contains'): {
+    match: boolean;
+    diff: string;
+};

package/dist/testing/comparator.js

@@ -0,0 +1,77 @@
+/**
+ * Compare actual output against expected output
+ */
+export function compareOutput(actual, expected, mode = 'exact') {
+    const normalizedActual = normalize(actual);
+    const normalizedExpected = normalize(expected);
+    if (mode === 'contains') {
+        const match = normalizedActual.includes(normalizedExpected);
+        if (match) {
+            return { match: true, diff: '' };
+        }
+        return {
+            match: false,
+            diff: buildDiff(normalizedExpected, normalizedActual, 'contains'),
+        };
+    }
+    // Exact mode
+    if (normalizedActual === normalizedExpected) {
+        return { match: true, diff: '' };
+    }
+    return {
+        match: false,
+        diff: buildDiff(normalizedExpected, normalizedActual, 'exact'),
+    };
+}
+/**
+ * Normalize output for comparison: trim whitespace, normalize line endings
+ */
+function normalize(s) {
+    return s
+        .replace(/\r\n/g, '\n')
+        .replace(/\r/g, '\n')
+        .trim();
+}
+/**
+ * Build a unified-style diff for display
+ */
+function buildDiff(expected, actual, mode) {
+    const expectedLines = expected.split('\n');
+    const actualLines = actual.split('\n');
+    const lines = [];
+    if (mode === 'contains') {
+        lines.push('--- expected (contains) ---');
+        lines.push('+++ actual +++');
+        lines.push('');
+        for (const line of expectedLines) {
+            lines.push(`- ${line}`);
+        }
+        lines.push('---');
+        for (const line of actualLines) {
+            lines.push(`+ ${line}`);
+        }
+        return lines.join('\n');
+    }
+    lines.push('--- expected ---');
+    lines.push('+++ actual +++');
+    lines.push('');
+    const maxLen = Math.max(expectedLines.length, actualLines.length);
+    for (let i = 0; i < maxLen; i++) {
+        const exp = expectedLines[i];
+        const act = actualLines[i];
+        if (exp === undefined) {
+            lines.push(`+ ${act}`);
+        }
+        else if (act === undefined) {
+            lines.push(`- ${exp}`);
+        }
+        else if (exp !== act) {
+            lines.push(`- ${exp}`);
+            lines.push(`+ ${act}`);
+        }
+        else {
+            lines.push(`  ${exp}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/testing/docker.d.ts

@@ -0,0 +1,21 @@
+import { ExtractedSnippet, TestResult, DockerEnvironment, RunnerConfig } from './types.js';
+/**
+ * Available Docker environments for multi-env testing
+ */
+export declare const DOCKER_ENVIRONMENTS: DockerEnvironment[];
+/**
+ * Check if Docker is available on this machine
+ */
+export declare function isDockerAvailable(): boolean;
+/**
+ * Parse a comma-separated environments string into DockerEnvironment objects
+ */
+export declare function parseEnvironments(envString: string): DockerEnvironment[];
+/**
+ * Get compatible Docker environments for a given language
+ */
+export declare function getCompatibleEnvironments(language: string, environments: DockerEnvironment[]): DockerEnvironment[];
+/**
+ * Run a snippet in a Docker container
+ */
+export declare function runInDocker(snippet: ExtractedSnippet, environment: DockerEnvironment, config: RunnerConfig): Promise<TestResult>;

package/dist/testing/docker.js

@@ -0,0 +1,234 @@
+import { spawnSync, spawn } from 'child_process';
+import { writeFileSync, mkdirSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { randomUUID } from 'crypto';
+import { compareOutput } from './comparator.js';
+import { checkRequiredEnv } from './env.js';
+/**
+ * Available Docker environments for multi-env testing
+ */
+export const DOCKER_ENVIRONMENTS = [
+    { name: 'node-20', image: 'node:20-slim', command: 'node', languages: ['typescript', 'ts', 'javascript', 'js'] },
+    { name: 'node-18', image: 'node:18-slim', command: 'node', languages: ['typescript', 'ts', 'javascript', 'js'] },
+    { name: 'python-3.12', image: 'python:3.12-slim', command: 'python3', languages: ['python', 'py'] },
+    { name: 'python-3.10', image: 'python:3.10-slim', command: 'python3', languages: ['python', 'py'] },
+    { name: 'bun', image: 'oven/bun:latest', command: 'bun', languages: ['typescript', 'ts', 'javascript', 'js'] },
+    { name: 'deno', image: 'denoland/deno:latest', command: 'deno', languages: ['typescript', 'ts', 'javascript', 'js'] },
+];
+/**
+ * Check if Docker is available on this machine
+ */
+export function isDockerAvailable() {
+    try {
+        const result = spawnSync('docker', ['info'], {
+            stdio: 'pipe',
+            timeout: 5000,
+        });
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Parse a comma-separated environments string into DockerEnvironment objects
+ */
+export function parseEnvironments(envString) {
+    const names = envString.split(',').map(s => s.trim()).filter(Boolean);
+    const envs = [];
+    for (const name of names) {
+        const env = DOCKER_ENVIRONMENTS.find(e => e.name === name);
+        if (env) {
+            envs.push(env);
+        }
+        else {
+            console.warn(`  Warning: Unknown environment "${name}". Available: ${DOCKER_ENVIRONMENTS.map(e => e.name).join(', ')}`);
+        }
+    }
+    return envs;
+}
+/**
+ * Get compatible Docker environments for a given language
+ */
+export function getCompatibleEnvironments(language, environments) {
+    return environments.filter(env => env.languages.includes(language));
+}
+/**
+ * Run a snippet in a Docker container
+ */
+export async function runInDocker(snippet, environment, config) {
+    const startTime = Date.now();
+    const envLabel = `docker:${environment.name}`;
+    // Check for skip directive
+    if (snippet.skipReason) {
+        return {
+            snippet,
+            status: 'skip',
+            stdout: '',
+            stderr: `Skipped: ${snippet.skipReason}`,
+            exitCode: 0,
+            duration: 0,
+            environment: envLabel,
+        };
+    }
+    // Check required env vars
+    if (snippet.requiredEnv && snippet.requiredEnv.length > 0) {
+        const { ok, missing } = checkRequiredEnv(snippet.requiredEnv, config.envVars);
+        if (!ok) {
+            return {
+                snippet,
+                status: 'skip',
+                stdout: '',
+                stderr: `Missing required env vars: ${missing.join(', ')}`,
+                exitCode: 0,
+                duration: 0,
+                environment: envLabel,
+            };
+        }
+    }
+    const tempDir = join(tmpdir(), `skrypt-docker-${randomUUID()}`);
+    mkdirSync(tempDir, { recursive: true });
+    try {
+        const isTS = ['typescript', 'ts'].includes(snippet.language);
+        const isPy = ['python', 'py'].includes(snippet.language);
+        let filename;
+        let containerCmd;
+        if (isPy) {
+            filename = 'test.py';
+            containerCmd = ['python3', `/work/${filename}`];
+        }
+        else if (isTS && environment.name === 'bun') {
+            filename = 'test.ts';
+            containerCmd = ['bun', 'run', `/work/${filename}`];
+        }
+        else if (isTS && environment.name === 'deno') {
+            filename = 'test.ts';
+            containerCmd = ['deno', 'run', '--allow-all', `/work/${filename}`];
+        }
+        else if (isTS) {
+            // Node needs tsx for TypeScript
+            filename = 'test.ts';
+            containerCmd = ['npx', '-y', 'tsx', `/work/${filename}`];
+        }
+        else {
+            filename = 'test.js';
+            containerCmd = ['node', `/work/${filename}`];
+        }
+        writeFileSync(join(tempDir, filename), snippet.code);
+        // Build Docker args
+        const dockerArgs = ['run', '--rm', '-v', `${tempDir}:/work`, '-w', '/work'];
+        // Inject env vars
+        for (const [key, value] of Object.entries(config.envVars)) {
+            dockerArgs.push('-e', `${key}=${value}`);
+        }
+        dockerArgs.push(environment.image, ...containerCmd);
+        const result = await executeDocker(dockerArgs, config.timeout);
+        const duration = Date.now() - startTime;
+        // Check output if expected
+        if (snippet.expectedOutput !== undefined) {
+            const comparison = compareOutput(result.stdout, snippet.expectedOutput, snippet.expectedOutputMode || 'exact');
+            if (!comparison.match) {
+                return {
+                    snippet,
+                    status: 'output_mismatch',
+                    stdout: result.stdout,
+                    stderr: result.stderr,
+                    exitCode: result.exitCode,
+                    duration,
+                    environment: envLabel,
+                    outputMatch: false,
+                    diff: comparison.diff,
+                };
+            }
+            return {
+                snippet,
+                status: result.exitCode === 0 ? 'pass' : 'fail',
+                stdout: result.stdout,
+                stderr: result.stderr,
+                exitCode: result.exitCode,
+                duration,
+                environment: envLabel,
+                outputMatch: true,
+            };
+        }
+        return {
+            snippet,
+            status: result.timedOut ? 'timeout' : (result.exitCode === 0 ? 'pass' : 'fail'),
+            stdout: result.stdout,
+            stderr: result.timedOut
+                ? `Timeout: execution exceeded ${config.timeout}ms`
+                : result.stderr,
+            exitCode: result.exitCode,
+            duration,
+            environment: envLabel,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            snippet,
+            status: 'fail',
+            stdout: '',
+            stderr: message,
+            exitCode: 1,
+            duration: Date.now() - startTime,
+            environment: envLabel,
+        };
+    }
+    finally {
+        try {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+}
+function executeDocker(args, timeoutMs) {
+    return new Promise((resolve) => {
+        const proc = spawn('docker', args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        const MAX_BUFFER = 1024 * 1024; // 1MB cap to prevent OOM
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            proc.kill('SIGKILL');
+        }, timeoutMs);
+        proc.stdout?.on('data', (data) => {
+            if (stdout.length < MAX_BUFFER) {
+                stdout += data.toString();
+                if (stdout.length > MAX_BUFFER)
+                    stdout = stdout.slice(0, MAX_BUFFER);
+            }
+        });
+        proc.stderr?.on('data', (data) => {
+            if (stderr.length < MAX_BUFFER) {
+                stderr += data.toString();
+                if (stderr.length > MAX_BUFFER)
+                    stderr = stderr.slice(0, MAX_BUFFER);
+            }
+        });
+        proc.on('close', (code) => {
+            clearTimeout(timeout);
+            resolve({
+                exitCode: timedOut ? 1 : (code ?? 1),
+                stdout,
+                stderr,
+                timedOut,
+            });
+        });
+        proc.on('error', (err) => {
+            clearTimeout(timeout);
+            resolve({
+                exitCode: 1,
+                stdout,
+                stderr: err.message,
+                timedOut: false,
+            });
+        });
+    });
+}

package/dist/testing/env.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Load environment variables from a .env file
+ */
+export declare function loadEnvFile(envFilePath: string): Record<string, string>;
+/**
+ * Build a clean environment for snippet execution.
+ * Only passes PATH, HOME, and explicitly injected vars.
+ */
+export declare function buildCleanEnv(injectedVars: Record<string, string>): Record<string, string>;
+/**
+ * Check if all required env vars are present
+ */
+export declare function checkRequiredEnv(required: string[], available: Record<string, string>): {
+    ok: boolean;
+    missing: string[];
+};

package/dist/testing/env.js

@@ -0,0 +1,58 @@
+import { readFileSync, existsSync } from 'fs';
+/**
+ * Load environment variables from a .env file
+ */
+export function loadEnvFile(envFilePath) {
+    if (!existsSync(envFilePath)) {
+        throw new Error(`Env file not found: ${envFilePath}`);
+    }
+    const content = readFileSync(envFilePath, 'utf-8');
+    const vars = {};
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eqIdx = trimmed.indexOf('=');
+        if (eqIdx === -1)
+            continue;
+        const key = trimmed.substring(0, eqIdx).trim();
+        let value = trimmed.substring(eqIdx + 1).trim();
+        // Strip surrounding quotes
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        vars[key] = value;
+    }
+    return vars;
+}
+/**
+ * Build a clean environment for snippet execution.
+ * Only passes PATH, HOME, and explicitly injected vars.
+ */
+export function buildCleanEnv(injectedVars) {
+    const clean = {
+        NODE_NO_WARNINGS: '1',
+    };
+    // Carry over PATH so runtimes can be found
+    if (process.env.PATH) {
+        clean.PATH = process.env.PATH;
+    }
+    // HOME / USERPROFILE for tools that need it
+    if (process.env.HOME) {
+        clean.HOME = process.env.HOME;
+    }
+    if (process.env.USERPROFILE) {
+        clean.USERPROFILE = process.env.USERPROFILE;
+    }
+    // Inject user-provided vars (API keys, etc.)
+    Object.assign(clean, injectedVars);
+    return clean;
+}
+/**
+ * Check if all required env vars are present
+ */
+export function checkRequiredEnv(required, available) {
+    const missing = required.filter(key => !available[key]);
+    return { ok: missing.length === 0, missing };
+}

package/dist/testing/extractor.d.ts

@@ -0,0 +1,9 @@
+import { ExtractedSnippet } from './types.js';
+/**
+ * Find all .md/.mdx files in a directory recursively
+ */
+export declare function findDocFiles(dir: string): string[];
+/**
+ * Extract code blocks from a markdown/MDX file
+ */
+export declare function extractSnippets(filePath: string, languageFilter?: string): ExtractedSnippet[];