@wix/pathgrade 0.29.0

package/dist/providers/mcp-config.js

@@ -0,0 +1,55 @@
+import fs from 'fs-extra';
+import * as path from 'path';
+const MCP_CONFIG_FILENAME = '.pathgrade-mcp.json';
+export async function writeMcpConfig(workspacePath, mcp) {
+    if (!mcp)
+        return { mcpConfigPath: undefined };
+    const mcpConfigPath = MCP_CONFIG_FILENAME;
+    if ('configFile' in mcp) {
+        const mcpSrc = path.resolve(mcp.configFile);
+        if (!await fs.pathExists(mcpSrc)) {
+            throw new Error(`MCP config file not found: ${mcpSrc}`);
+        }
+        await fs.copy(mcpSrc, path.join(workspacePath, mcpConfigPath));
+    }
+    else if ('mock' in mcp) {
+        const mocks = Array.isArray(mcp.mock) ? mcp.mock : [mcp.mock];
+        const seen = new Set();
+        for (const mock of mocks) {
+            if (seen.has(mock.config.name)) {
+                throw new Error(`Duplicate mock MCP server name: "${mock.config.name}"`);
+            }
+            seen.add(mock.config.name);
+        }
+        const mcpServers = {};
+        for (const mock of mocks) {
+            const sanitizedName = mock.config.name.replace(/[^a-zA-Z0-9-]/g, '-');
+            const fixturePath = path.join(workspacePath, `.pathgrade-mcp-mock-${sanitizedName}.json`);
+            await fs.writeJson(fixturePath, mock.config, { spaces: 2 });
+            const mockServerScript = path.resolve(import.meta.dirname, '../mcp-mock-server.js');
+            mcpServers[mock.config.name] = {
+                command: 'node',
+                args: [mockServerScript, fixturePath],
+            };
+        }
+        await fs.writeJson(path.join(workspacePath, mcpConfigPath), { mcpServers }, { spaces: 2 });
+    }
+    return { mcpConfigPath };
+}
+/**
+ * Read the JSON `writeMcpConfig` writes into `<workspace>/.pathgrade-mcp.json`
+ * and return the inner `mcpServers` object the Claude SDK driver hands to
+ * `Options.mcpServers`. Returns `undefined` when the file is absent (the
+ * "no MCP" path through the driver — the fixture didn't declare an `mcp` spec).
+ *
+ * The on-disk path is preserved because the Cursor agent driver still
+ * consumes it via `mcpConfigPath` (`src/agents/cursor.ts`) — Claude moves to
+ * the object form, Cursor stays on the file.
+ */
+export async function loadMcpServersForSdk(workspacePath) {
+    const configPath = path.join(workspacePath, MCP_CONFIG_FILENAME);
+    if (!(await fs.pathExists(configPath)))
+        return undefined;
+    const parsed = (await fs.readJson(configPath));
+    return parsed.mcpServers;
+}

package/dist/providers/sandbox-exec.d.ts

@@ -0,0 +1,8 @@
+import type { CommandResult } from '../types.js';
+export interface ExecContext {
+    cwd: string;
+    env: Record<string, string>;
+}
+export declare function sandboxExec(command: string, ctx: ExecContext, opts?: {
+    signal?: AbortSignal;
+}): Promise<CommandResult>;

package/dist/providers/sandbox-exec.js

@@ -0,0 +1,82 @@
+import { spawn } from 'child_process';
+export function sandboxExec(command, ctx, opts) {
+    return new Promise((resolve) => {
+        const child = spawn(command, {
+            shell: true,
+            detached: process.platform !== 'win32',
+            cwd: ctx.cwd,
+            env: { ...ctx.env },
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        let killTimer;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (killTimer)
+                clearTimeout(killTimer);
+            if (opts?.signal && abortHandler) {
+                opts.signal.removeEventListener('abort', abortHandler);
+            }
+            resolve(result);
+        };
+        const abortHandler = () => {
+            if (settled)
+                return;
+            try {
+                if (process.platform !== 'win32' && child.pid) {
+                    process.kill(-child.pid, 'SIGTERM');
+                }
+                else {
+                    child.kill('SIGTERM');
+                }
+            }
+            catch {
+                child.kill('SIGTERM');
+            }
+            killTimer = setTimeout(() => {
+                try {
+                    if (process.platform !== 'win32' && child.pid) {
+                        process.kill(-child.pid, 'SIGKILL');
+                    }
+                    else if (!child.killed) {
+                        child.kill('SIGKILL');
+                    }
+                }
+                catch {
+                    if (!child.killed)
+                        child.kill('SIGKILL');
+                }
+            }, 250);
+        };
+        if (opts?.signal) {
+            if (opts.signal.aborted) {
+                abortHandler();
+            }
+            else {
+                opts.signal.addEventListener('abort', abortHandler, { once: true });
+            }
+        }
+        child.stdout.on('data', (data) => { stdout += data.toString(); });
+        child.stderr.on('data', (data) => { stderr += data.toString(); });
+        child.on('close', (code, signal) => {
+            finish({
+                stdout,
+                stderr,
+                exitCode: code ?? (opts?.signal?.aborted ? 124 : 1),
+                timedOut: opts?.signal?.aborted || undefined,
+                killed: signal != null || undefined,
+            });
+        });
+        child.on('error', () => {
+            finish({
+                stdout,
+                stderr,
+                exitCode: opts?.signal?.aborted ? 124 : 1,
+                timedOut: opts?.signal?.aborted || undefined,
+            });
+        });
+    });
+}

package/dist/providers/sandbox.d.ts

@@ -0,0 +1,22 @@
+export interface SandboxConfig {
+    agent: import('../sdk/types.js').AgentName;
+    workspace?: string;
+    skillDir?: string;
+    copyFromHome?: string[];
+    env?: Record<string, string>;
+    mcp?: import('./mcp-config.js').McpSpec;
+    /**
+     * Glob patterns to ignore when copying workspace and skill directories.
+     * Replaces the default ignore list entirely. Pass `[]` to disable filtering.
+     * When omitted, DEFAULT_COPY_IGNORE is used.
+     */
+    copyIgnore?: string[];
+}
+export interface Sandbox {
+    rootDir: string;
+    workspacePath: string;
+    homePath: string;
+    env: Record<string, string>;
+}
+export declare const SAFE_HOST_VARS: string[];
+export declare function createSandbox(spec: SandboxConfig): Promise<Sandbox>;

package/dist/providers/sandbox.js

@@ -0,0 +1,158 @@
+import fs from 'fs-extra';
+import * as path from 'path';
+import * as os from 'os';
+import { DEFAULT_COPY_IGNORE, createCopyFilter } from './copy-filter.js';
+export const SAFE_HOST_VARS = [
+    'PATH', 'SHELL', 'LANG', 'LC_ALL', 'LC_CTYPE', 'TERM', 'USER', 'LOGNAME',
+];
+export async function createSandbox(spec) {
+    const rootDir = path.join(os.tmpdir(), `pathgrade-${Math.random().toString(36).substring(7)}`);
+    const workspacePath = path.join(rootDir, 'workspace');
+    const homePath = path.join(rootDir, 'home');
+    const tmpPath = path.join(rootDir, 'tmp');
+    await fs.ensureDir(workspacePath);
+    await fs.ensureDir(homePath);
+    await fs.ensureDir(tmpPath);
+    // Build copy filter for workspace and skill directories
+    const ignorePatterns = spec.copyIgnore !== undefined ? spec.copyIgnore : DEFAULT_COPY_IGNORE;
+    const copyFilter = createCopyFilter(ignorePatterns);
+    // Copy fixture directory contents into workspace
+    if (spec.workspace) {
+        const fixturePath = path.resolve(spec.workspace);
+        if (await fs.pathExists(fixturePath)) {
+            await fs.copy(fixturePath, workspacePath, { filter: copyFilter });
+        }
+    }
+    // Stage skill to both discovery paths so either convention resolves
+    if (spec.skillDir) {
+        const skillPath = path.resolve(spec.skillDir);
+        const skillName = path.basename(skillPath);
+        const skillFilter = (src) => {
+            const rel = path.relative(skillPath, src);
+            if (rel === 'test' || rel.startsWith(`test${path.sep}`)) {
+                return false;
+            }
+            return copyFilter(src);
+        };
+        const claudeDir = path.join(workspacePath, '.claude', 'skills', skillName);
+        const agentsDir = path.join(workspacePath, '.agents', 'skills', skillName);
+        const primaryDir = spec.agent === 'claude' ? claudeDir : agentsDir;
+        const secondaryDir = spec.agent === 'claude' ? agentsDir : claudeDir;
+        await fs.copy(skillPath, primaryDir, { filter: skillFilter });
+        await fs.copy(skillPath, secondaryDir, { filter: skillFilter });
+        // Verified against cursor-agent 2026.04.17-787b533: the rule loader
+        // reads SKILL.md body from the .mdc file directly; a plain pointer
+        // ("see .agents/skills/<name>/SKILL.md") is not honored, so inline
+        // the content. Emitted unconditionally across all agents — harness-
+        // idempotent, same posture as the .claude/.agents dual-stage above.
+        await stageCursorRule(workspacePath, skillName, skillPath);
+    }
+    // Copy specified paths from real host HOME into sandbox HOME
+    if (spec.copyFromHome) {
+        const realHome = os.homedir();
+        for (const relPath of spec.copyFromHome) {
+            const srcPath = path.join(realHome, relPath);
+            if (await fs.pathExists(srcPath)) {
+                const destPath = path.join(homePath, relPath);
+                await fs.ensureDir(path.dirname(destPath));
+                await fs.copy(srcPath, destPath);
+            }
+        }
+    }
+    // Create HOME → workspace symlinks for skill directories that exist
+    const skillSymlinks = [
+        ['.agents', 'skills'],
+        ['.claude', 'skills'],
+    ];
+    for (const segments of skillSymlinks) {
+        const wsSkillDir = path.join(workspacePath, ...segments);
+        if (await fs.pathExists(wsSkillDir)) {
+            const homeSkillDir = path.join(homePath, ...segments);
+            await fs.ensureDir(path.dirname(homeSkillDir));
+            await fs.symlink(wsSkillDir, homeSkillDir);
+        }
+    }
+    // Build env: safe host vars, then sandbox defaults, then explicit overrides.
+    // API keys are NOT forwarded here — resolveCredentials() handles credentials
+    // per-agent so Claude CLI can use native OAuth when no key is needed.
+    const env = {};
+    for (const key of SAFE_HOST_VARS) {
+        if (process.env[key])
+            env[key] = process.env[key];
+    }
+    env.HOME = homePath;
+    env.TMPDIR = tmpPath;
+    env.TMP = tmpPath;
+    env.TEMP = tmpPath;
+    // Explicit overrides take precedence
+    if (spec.env) {
+        Object.assign(env, spec.env);
+    }
+    return {
+        rootDir,
+        workspacePath,
+        homePath,
+        env,
+    };
+}
+const FRONTMATTER_DELIM = /^---\s*$/;
+async function stageCursorRule(workspacePath, skillName, skillPath) {
+    const skillMdPath = path.join(skillPath, 'SKILL.md');
+    if (!(await fs.pathExists(skillMdPath)))
+        return;
+    const raw = await fs.readFile(skillMdPath, 'utf8');
+    const parsed = splitFrontmatter(raw);
+    const description = parsed.frontmatter.description ?? deriveFallbackDescription(parsed.body, skillName);
+    const mdc = [
+        '---',
+        `description: ${escapeYamlScalar(description)}`,
+        'alwaysApply: true',
+        '---',
+        '',
+        parsed.body.trimStart(),
+    ].join('\n');
+    const rulesDir = path.join(workspacePath, '.cursor', 'rules');
+    await fs.ensureDir(rulesDir);
+    await fs.writeFile(path.join(rulesDir, `${skillName}.mdc`), mdc, 'utf8');
+}
+function splitFrontmatter(raw) {
+    const lines = raw.split('\n');
+    if (lines.length === 0 || !FRONTMATTER_DELIM.test(lines[0])) {
+        return { frontmatter: {}, body: raw };
+    }
+    const endIdx = lines.slice(1).findIndex((line) => FRONTMATTER_DELIM.test(line));
+    if (endIdx === -1) {
+        return { frontmatter: {}, body: raw };
+    }
+    const frontmatterLines = lines.slice(1, endIdx + 1);
+    const bodyLines = lines.slice(endIdx + 2);
+    const frontmatter = {};
+    for (const line of frontmatterLines) {
+        const match = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
+        if (match) {
+            frontmatter[match[1]] = match[2].replace(/^['"]|['"]$/g, '').trim();
+        }
+    }
+    return { frontmatter, body: bodyLines.join('\n') };
+}
+function deriveFallbackDescription(body, skillName) {
+    for (const line of body.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        if (trimmed.startsWith('#')) {
+            const headingText = trimmed.replace(/^#+\s*/, '').trim();
+            if (headingText)
+                return headingText;
+        }
+        return trimmed;
+    }
+    return `Skill ${skillName}`;
+}
+function escapeYamlScalar(value) {
+    const single = value.replace(/[\r\n]+/g, ' ').trim();
+    if (/[:#&*!|>'"%@`]/.test(single) || single !== value) {
+        return `"${single.replace(/"/g, '\\"')}"`;
+    }
+    return single;
+}

package/dist/providers/sandboxed-claude-spawn.d.ts

@@ -0,0 +1,24 @@
+import type { SpawnOptions as SdkSpawnOptions, SpawnedProcess } from '@anthropic-ai/claude-agent-sdk';
+/** Injected child_process spawn delegate. Real callers pass node's
+ *  `child_process.spawn`; tests pass a recorder. */
+export type ChildSpawnFn = (command: string, args: string[], opts: {
+    cwd?: string;
+    env: NodeJS.ProcessEnv;
+    signal: AbortSignal;
+}) => SpawnedProcess;
+export interface SandboxedClaudeSpawnDeps {
+    /** Host platform. macOS branches on this when `sandboxProfile` is set. */
+    platform: NodeJS.Platform;
+    /** Host process env to filter through `SAFE_HOST_VARS`. */
+    hostEnv: NodeJS.ProcessEnv;
+    /** Spawner. Defaults to `child_process.spawn`. */
+    spawn?: ChildSpawnFn;
+    /**
+     * Inline macOS sandbox-exec profile. When set on darwin, argv is wrapped
+     * with `sandbox-exec -p <profile> --`. When unset (today's posture),
+     * argv passes through untouched.
+     */
+    sandboxProfile?: string;
+}
+export type SandboxedClaudeSpawn = (opts: SdkSpawnOptions) => SpawnedProcess;
+export declare function createSandboxedClaudeSpawn(deps: SandboxedClaudeSpawnDeps): SandboxedClaudeSpawn;

package/dist/providers/sandboxed-claude-spawn.js

@@ -0,0 +1,57 @@
+/**
+ * Adapts the Claude Agent SDK's `spawnClaudeCodeProcess` hook into pathgrade's
+ * sandbox model. Knows nothing about Claude, the SDK, or evals — it just
+ * receives a `SpawnOptions` and returns a `SpawnedProcess`.
+ *
+ * Two enforcement points:
+ *
+ *   1. Subprocess env. The host's ambient env is intersected with
+ *      `SAFE_HOST_VARS` (`PATH`, `SHELL`, `LANG`, ...) and the SDK-supplied
+ *      `Options.env` is layered on top. Anything else stays out — the
+ *      `Options.env` declaration in the driver is the single typed channel
+ *      for whatever the SDK subprocess intentionally needs (auth, scratch
+ *      config dir, etc.).
+ *
+ *   2. Argv. macOS optionally wraps with `sandbox-exec -p <profile> --` when
+ *      a profile is supplied; non-darwin always passes through. Today no
+ *      profile is staged, so production usage is passthrough on every
+ *      platform — the seam exists for the wrap preserved from the pre-SDK
+ *      driver.
+ */
+import { spawn as nodeSpawn } from 'child_process';
+import { SAFE_HOST_VARS } from './sandbox.js';
+export function createSandboxedClaudeSpawn(deps) {
+    const spawn = deps.spawn ?? nodeSpawn;
+    return (sdkOpts) => {
+        const env = buildSubprocessEnv(deps.hostEnv, sdkOpts.env);
+        const { command, args } = buildArgv(deps.platform, deps.sandboxProfile, sdkOpts.command, sdkOpts.args);
+        return spawn(command, args, {
+            cwd: sdkOpts.cwd,
+            env,
+            signal: sdkOpts.signal,
+        });
+    };
+}
+function buildSubprocessEnv(hostEnv, sdkEnv) {
+    const env = {};
+    for (const key of SAFE_HOST_VARS) {
+        const value = hostEnv[key];
+        if (value !== undefined)
+            env[key] = value;
+    }
+    for (const [key, value] of Object.entries(sdkEnv)) {
+        if (value === undefined)
+            continue;
+        env[key] = value;
+    }
+    return env;
+}
+function buildArgv(platform, sandboxProfile, command, args) {
+    if (platform === 'darwin' && sandboxProfile !== undefined) {
+        return {
+            command: 'sandbox-exec',
+            args: ['-p', sandboxProfile, '--', command, ...args],
+        };
+    }
+    return { command, args };
+}

package/dist/providers/workspace.d.ts

@@ -0,0 +1,15 @@
+import { type SandboxConfig } from './sandbox.js';
+import type { CommandResult } from '../types.js';
+export type { McpSpec } from './mcp-config.js';
+export interface Workspace {
+    readonly path: string;
+    readonly mcpConfigPath: string | undefined;
+    readonly env: Record<string, string>;
+    readonly setupCommands: string[];
+    exec(command: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<CommandResult>;
+    dispose(): Promise<void>;
+}
+export declare function linkPathsFromHostHome(pathsToLink: string[], sandboxHomePath: string): Promise<void>;
+export declare function prepareWorkspace(spec: SandboxConfig): Promise<Workspace>;

package/dist/providers/workspace.js

@@ -0,0 +1,73 @@
+import fs from 'fs-extra';
+import * as os from 'os';
+import * as path from 'path';
+import { createSandbox } from './sandbox.js';
+import { writeMcpConfig } from './mcp-config.js';
+import { sandboxExec } from './sandbox-exec.js';
+import { resolveCredentials } from './credentials.js';
+async function copyPathsFromHostHome(pathsToCopy, sandboxHomePath) {
+    const realHome = os.homedir();
+    for (const relPath of pathsToCopy) {
+        const srcPath = path.join(realHome, relPath);
+        if (!await fs.pathExists(srcPath))
+            continue;
+        const destPath = path.join(sandboxHomePath, relPath);
+        await fs.ensureDir(path.dirname(destPath));
+        await fs.copy(srcPath, destPath);
+    }
+}
+export async function linkPathsFromHostHome(pathsToLink, sandboxHomePath) {
+    const realHome = os.homedir();
+    for (const relPath of pathsToLink) {
+        const srcPath = path.join(realHome, relPath);
+        if (!await fs.pathExists(srcPath))
+            continue;
+        const destPath = path.join(sandboxHomePath, relPath);
+        await fs.ensureDir(path.dirname(destPath));
+        await fs.symlink(srcPath, destPath);
+    }
+}
+export async function prepareWorkspace(spec) {
+    const { mcp, ...sandboxSpec } = spec;
+    const sandbox = await createSandbox(sandboxSpec);
+    const { workspacePath, homePath, env: sandboxEnv, rootDir } = sandbox;
+    try {
+        // Resolve credentials: pass user's original env (not sandboxEnv) so
+        // the resolver can distinguish explicit user intent from auto-resolved values.
+        const creds = await resolveCredentials(spec.agent, spec.env ?? {});
+        Object.assign(sandboxEnv, creds.env);
+        await copyPathsFromHostHome(creds.copyFromHome, homePath);
+        await linkPathsFromHostHome(creds.linkFromHome ?? [], homePath);
+        const { mcpConfigPath } = await writeMcpConfig(workspacePath, mcp);
+        let disposed = false;
+        return {
+            path: workspacePath,
+            mcpConfigPath,
+            env: sandboxEnv,
+            setupCommands: creds.setupCommands,
+            exec: (command, opts) => sandboxExec(command, { cwd: workspacePath, env: sandboxEnv }, opts),
+            async dispose() {
+                if (disposed)
+                    return;
+                disposed = true;
+                for (let attempt = 0; attempt < 4; attempt++) {
+                    try {
+                        await fs.remove(rootDir);
+                        return;
+                    }
+                    catch (error) {
+                        const code = error.code;
+                        const retryable = code === 'ENOTEMPTY' || code === 'EBUSY' || code === 'EPERM';
+                        if (!retryable || attempt === 3)
+                            throw error;
+                        await new Promise((r) => setTimeout(r, 50 * (attempt + 1)));
+                    }
+                }
+            },
+        };
+    }
+    catch (error) {
+        await fs.remove(rootDir).catch(() => { });
+        throw error;
+    }
+}

package/dist/reporters/browser.d.ts

@@ -0,0 +1,2 @@
+import * as http from 'http';
+export declare function runBrowserPreview(resultsDir: string, port?: number): Promise<http.Server>;

package/dist/reporters/browser.js

@@ -0,0 +1,85 @@
+import * as http from 'http';
+import fs from 'fs-extra';
+import * as path from 'path';
+import { loadReports } from './loader.js';
+export function runBrowserPreview(resultsDir, port = 3847) {
+    const resolved = path.resolve(resultsDir);
+    const htmlPath = path.join(import.meta.dirname, '..', 'viewer.html');
+    const server = http.createServer(async (req, res) => {
+        const url = new URL(req.url || '/', `http://localhost:${port}`);
+        if (url.pathname === '/api/reports') {
+            const reports = await loadReports(resolved, { skipTraces: true });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(reports));
+        }
+        else if (url.pathname === '/api/report') {
+            const file = url.searchParams.get('file');
+            if (!file) {
+                res.writeHead(400);
+                res.end('Missing file param');
+                return;
+            }
+            const filePath = path.resolve(resolved, file);
+            if (!filePath.startsWith(resolved + path.sep) && filePath !== resolved) {
+                res.writeHead(403);
+                res.end('Forbidden');
+                return;
+            }
+            if (req.method === 'DELETE') {
+                if (await fs.pathExists(filePath)) {
+                    await fs.remove(filePath);
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ deleted: file }));
+                }
+                else {
+                    res.writeHead(404);
+                    res.end('Not found');
+                }
+            }
+            else {
+                if (await fs.pathExists(filePath)) {
+                    const raw = await fs.readJSON(filePath);
+                    const groupIdx = parseInt(url.searchParams.get('group') || '0', 10);
+                    let report = raw;
+                    if (raw.version && Array.isArray(raw.groups)) {
+                        report = { timestamp: raw.timestamp, ...raw.groups[groupIdx] };
+                    }
+                    // Merge trace data (session_log, conversation) back into trials
+                    if (report.trace_file) {
+                        const tracePath = path.resolve(resolved, report.trace_file);
+                        if (await fs.pathExists(tracePath)) {
+                            const traceTrials = await fs.readJSON(tracePath);
+                            if (Array.isArray(traceTrials) && Array.isArray(report.trials)) {
+                                report.trials = report.trials.map((t, i) => ({
+                                    ...t,
+                                    ...traceTrials[i],
+                                }));
+                            }
+                        }
+                    }
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(report));
+                }
+                else {
+                    res.writeHead(404);
+                    res.end('Not found');
+                }
+            }
+        }
+        else {
+            const html = await fs.readFile(htmlPath, 'utf-8');
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end(html);
+        }
+    });
+    return new Promise((resolve) => {
+        server.listen(port, () => {
+            const addr = server.address();
+            const actualPort = typeof addr === 'object' && addr ? addr.port : port;
+            console.log(`\npathgrade preview`);
+            console.log(`\n  url       http://localhost:${actualPort}`);
+            console.log(`  results   ${resolved}\n`);
+            resolve(server);
+        });
+    });
+}

package/dist/reporters/cli.d.ts

@@ -0,0 +1,2 @@
+import type { PreviewOptions } from '../commands/preview.js';
+export declare function runCliPreview(resultsDir: string, opts?: PreviewOptions): Promise<void>;