@webpresso/agent-kit 0.21.0

package/dist/esm/quality-engine/workspace-config.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Workspace Configuration
+ *
+ * Single source of truth for workspace path patterns and path-based checks.
+ * Consolidates duplicated patterns from typecheck.ts, qa.ts, test.ts, and pre-commit hook.
+ *
+ * @module
+ */
+/**
+ * Patterns to extract package paths from file paths.
+ * Used by typecheck, qa, and lint commands to scope checks to affected packages.
+ *
+ * Previously duplicated in:
+ * - apps/cli2/src/commands/typecheck.ts (PACKAGE_PATTERNS)
+ * - apps/cli2/src/commands/qa.ts (PACKAGE_PATTERNS)
+ */
+export declare const PACKAGE_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
+/**
+ * Extract the package path from a file path.
+ */
+export declare function extractPackagePath(filePath: string): string | null;
+/**
+ * Detect which project root a file belongs to based on its path.
+ * Uses PACKAGE_PATTERNS to auto-detect — all packages with # support work automatically.
+ */
+export declare function detectProjectRoot(filePath: string): string | undefined;
+/**
+ * Configuration for a path-based check.
+ * Used by pre-commit hook to run targeted tests when specific files change.
+ *
+ * Previously in: .husky/pre-commit (PATH_CHECKS array with § delimiter - fragile!)
+ */
+export interface PathCheck {
+    /** Regex pattern to match staged file paths */
+    pattern: RegExp;
+    /** Emoji for display */
+    emoji: string;
+    /** Human-readable name */
+    name: string;
+    /** Command to execute (use 'just' commands) */
+    command: string;
+    /** Optional setup command (run in background before tests) */
+    setupCommand?: string;
+    /** Optional health check URL for setup verification */
+    healthUrl?: string;
+}
+/**
+ * Path-based checks configuration.
+ * When staged files match the pattern, the corresponding command runs.
+ *
+ * Note: All commands should use 'just' (Just-First principle).
+ */
+export declare const PATH_CHECKS: PathCheck[];
+/**
+ * Validate a path check configuration.
+ * Returns error message if invalid, undefined if valid.
+ */
+export declare function validatePathCheck(check: PathCheck): string | undefined;
+/**
+ * Validate all path checks.
+ * Throws if any check is invalid.
+ */
+export declare function validateAllPathChecks(): void;
+/**
+ * Find matched path checks for a list of files.
+ */
+export declare function getMatchedPathChecks(files: string[]): PathCheck[];
+//# sourceMappingURL=workspace-config.d.ts.map

package/dist/esm/quality-engine/workspace-config.js

@@ -0,0 +1,131 @@
+/**
+ * Workspace Configuration
+ *
+ * Single source of truth for workspace path patterns and path-based checks.
+ * Consolidates duplicated patterns from typecheck.ts, qa.ts, test.ts, and pre-commit hook.
+ *
+ * @module
+ */
+// =============================================================================
+// Package Path Patterns
+// =============================================================================
+/**
+ * Patterns to extract package paths from file paths.
+ * Used by typecheck, qa, and lint commands to scope checks to affected packages.
+ *
+ * Previously duplicated in:
+ * - apps/cli2/src/commands/typecheck.ts (PACKAGE_PATTERNS)
+ * - apps/cli2/src/commands/qa.ts (PACKAGE_PATTERNS)
+ */
+export const PACKAGE_PATTERNS = [
+    /^(packages\/[^/]+\/[^/]+)/, // packages/foundation/config, packages/core/database, etc.
+    /^(apps\/web\/[^/]+)/,
+    /^(apps\/workers\/[^/]+)/,
+    /^(apps\/containers\/[^/]+)/,
+    /^(infra)(?:\/|$)/, // Match 'infra' only when followed by / or end of string
+    /^(apps\/[^/]+)/, // Catch-all for other top-level apps (app-core, desktop, etc.)
+];
+/**
+ * Extract the package path from a file path.
+ */
+export function extractPackagePath(filePath) {
+    // Remove leading ./ if present
+    const normalized = filePath.replace(/^\.\//, '');
+    for (const pattern of PACKAGE_PATTERNS) {
+        const match = normalized.match(pattern);
+        if (match?.[1])
+            return match[1];
+    }
+    return null;
+}
+// =============================================================================
+// Project Root Detection (Vitest)
+// =============================================================================
+/**
+ * Detect which project root a file belongs to based on its path.
+ * Uses PACKAGE_PATTERNS to auto-detect — all packages with # support work automatically.
+ */
+export function detectProjectRoot(filePath) {
+    return extractPackagePath(filePath) ?? undefined;
+}
+/**
+ * Path-based checks configuration.
+ * When staged files match the pattern, the corresponding command runs.
+ *
+ * Note: All commands should use 'just' (Just-First principle).
+ */
+export const PATH_CHECKS = [
+    {
+        pattern: /^apps\/workers\/chef\//,
+        emoji: '🍳',
+        name: 'Chef',
+        command: 'just test --package chef',
+    },
+    {
+        pattern: /^apps\/web\/platform-web\/app\/(components|routes)\/.*\.tsx$/,
+        emoji: '♿',
+        name: 'Platform Web A11y',
+        command: 'just test --package platform-web -- -t Accessibility',
+    },
+    {
+        pattern: /^apps\/web\/admin-web\/app\/(components|routes)\/.*\.tsx$/,
+        emoji: '♿',
+        name: 'Admin Web A11y',
+        command: 'just test --package admin-web -- -t Accessibility',
+    },
+    {
+        pattern: /^apps\/web\/website\/app\/(components|routes)\/.*\.tsx$/,
+        emoji: '♿',
+        name: 'Website A11y',
+        command: 'just test --package website -- -t Accessibility',
+    },
+];
+/**
+ * Validate a path check configuration.
+ * Returns error message if invalid, undefined if valid.
+ */
+export function validatePathCheck(check) {
+    if (!check.pattern) {
+        return 'Missing pattern';
+    }
+    if (!check.name) {
+        return 'Missing name';
+    }
+    if (!check.command) {
+        return 'Missing command';
+    }
+    if (check.healthUrl && !check.healthUrl.startsWith('http')) {
+        return `Invalid health URL: ${check.healthUrl}`;
+    }
+    return undefined;
+}
+/**
+ * Validate all path checks.
+ * Throws if any check is invalid.
+ */
+export function validateAllPathChecks() {
+    for (const check of PATH_CHECKS) {
+        const error = validatePathCheck(check);
+        if (error) {
+            throw new Error(`Invalid PATH_CHECK '${check.name}': ${error}`);
+        }
+    }
+}
+/**
+ * Find matched path checks for a list of files.
+ */
+export function getMatchedPathChecks(files) {
+    const matched = [];
+    const seen = new Set();
+    for (const check of PATH_CHECKS) {
+        for (const file of files) {
+            if (check.pattern.test(file) && !seen.has(check.name)) {
+                matched.push(check);
+                seen.add(check.name);
+                break;
+            }
+        }
+    }
+    return matched;
+}
+//# sourceMappingURL=workspace-config.js.map

package/dist/esm/runners/claude-subagent/index.d.ts

@@ -0,0 +1,11 @@
+import type { Runner, RunnerContext, RunnerExecution, RunnerTask } from '#runners/types';
+import type { SubagentFn } from './types.js';
+export declare class ClaudeSubagentRunner implements Runner {
+    readonly id = "claude-subagent";
+    readonly version: string;
+    readonly capabilities: readonly string[];
+    private readonly subagentFn;
+    constructor(version: string, subagentFn?: SubagentFn);
+    prepare(task: RunnerTask, ctx: RunnerContext): RunnerExecution;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/runners/claude-subagent/index.js

@@ -0,0 +1,114 @@
+// ---------------------------------------------------------------------------
+// Stub default subagent — replaced in Wave 4 (Task 4.1)
+// ---------------------------------------------------------------------------
+const notImplemented = (_prompt, _opts) => {
+    return Promise.reject(new Error('not implemented — inject subagentFn'));
+};
+// ---------------------------------------------------------------------------
+// ClaudeSubagentExecution — live execution handle
+// ---------------------------------------------------------------------------
+class ClaudeSubagentExecution {
+    handle;
+    task;
+    ctx;
+    subagentFn;
+    collectedEvents = [];
+    status = 'running';
+    constructor(handle, task, ctx, subagentFn) {
+        this.handle = handle;
+        this.task = task;
+        this.ctx = ctx;
+        this.subagentFn = subagentFn;
+    }
+    async *run(signal) {
+        if (signal?.aborted === true) {
+            const event = {
+                type: 'cancelled',
+                ts: new Date().toISOString(),
+                handle: this.handle,
+            };
+            this.collectedEvents.push(event);
+            this.status = 'cancelled';
+            yield event;
+            return;
+        }
+        const startedEvent = {
+            type: 'started',
+            ts: new Date().toISOString(),
+            handle: this.handle,
+        };
+        this.collectedEvents.push(startedEvent);
+        yield startedEvent;
+        try {
+            const output = await this.subagentFn(this.task.description, {
+                cwd: this.ctx.cwd,
+                env: this.ctx.env,
+                signal,
+            });
+            for (const line of output.split('\n')) {
+                if (line.length === 0) {
+                    continue;
+                }
+                const stdoutEvent = {
+                    type: 'stdout',
+                    ts: new Date().toISOString(),
+                    handle: this.handle,
+                    line,
+                };
+                this.collectedEvents.push(stdoutEvent);
+                yield stdoutEvent;
+            }
+            const completedEvent = {
+                type: 'completed',
+                ts: new Date().toISOString(),
+                handle: this.handle,
+                exitCode: 0,
+            };
+            this.collectedEvents.push(completedEvent);
+            this.status = 'completed';
+            yield completedEvent;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const failedEvent = {
+                type: 'failed',
+                ts: new Date().toISOString(),
+                handle: this.handle,
+                error: message,
+            };
+            this.collectedEvents.push(failedEvent);
+            this.status = 'failed';
+            yield failedEvent;
+        }
+    }
+    snapshot() {
+        return {
+            handle: this.handle,
+            status: this.status,
+            events: [...this.collectedEvents],
+        };
+    }
+    async teardown() {
+        // Idempotent — nothing to clean up for the subagent-based runner.
+        // Called once or multiple times; both are safe.
+    }
+}
+// ---------------------------------------------------------------------------
+// ClaudeSubagentRunner — factory
+// ---------------------------------------------------------------------------
+export class ClaudeSubagentRunner {
+    id = 'claude-subagent';
+    version;
+    capabilities;
+    subagentFn;
+    constructor(version, subagentFn = notImplemented) {
+        this.version = version;
+        this.capabilities = ['read', 'workspace-write'];
+        this.subagentFn = subagentFn;
+    }
+    prepare(task, ctx) {
+        const handle = crypto.randomUUID();
+        return new ClaudeSubagentExecution(handle, task, ctx, this.subagentFn);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/runners/claude-subagent/types.d.ts

@@ -0,0 +1,7 @@
+export interface SubagentOptions {
+    readonly cwd: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly signal?: AbortSignal;
+}
+export type SubagentFn = (prompt: string, opts: SubagentOptions) => Promise<string>;
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/runners/claude-subagent/types.js

@@ -0,0 +1,5 @@
+// ---------------------------------------------------------------------------
+// SubagentOptions — options forwarded to the subagent invocation
+// ---------------------------------------------------------------------------
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/runners/codex-exec/index.d.ts

@@ -0,0 +1,16 @@
+import type { SpawnSyncOptionsWithBufferEncoding, SpawnSyncReturns } from 'node:child_process';
+import type { Runner, RunnerContext, RunnerExecution, RunnerTask } from '#runners/types';
+type SpawnFn = (command: string, args: readonly string[], options: SpawnSyncOptionsWithBufferEncoding) => SpawnSyncReturns<Buffer>;
+export interface CodexExecRunnerOptions {
+    readonly spawn?: SpawnFn;
+}
+export declare class CodexExecRunner implements Runner {
+    readonly id = "codex-exec";
+    readonly version = "1.0.0";
+    readonly capabilities: readonly string[];
+    private readonly _spawn;
+    constructor(options?: CodexExecRunnerOptions);
+    prepare(task: RunnerTask, ctx: RunnerContext): RunnerExecution;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/runners/codex-exec/index.js

@@ -0,0 +1,105 @@
+import { spawnSync } from 'node:child_process';
+// ---------------------------------------------------------------------------
+// CodexExecExecution
+// ---------------------------------------------------------------------------
+class CodexExecExecution {
+    handle;
+    _task;
+    _ctx;
+    _spawn;
+    _status = 'running';
+    _events = [];
+    constructor(handle, task, ctx, spawnFn) {
+        this.handle = handle;
+        this._task = task;
+        this._ctx = ctx;
+        this._spawn = spawnFn;
+    }
+    async *run(signal) {
+        const ts = () => new Date().toISOString();
+        const startedEvent = { type: 'started', ts: ts(), handle: this.handle };
+        this._events.push(startedEvent);
+        yield startedEvent;
+        if (signal?.aborted === true) {
+            const cancelledEvent = { type: 'cancelled', ts: ts(), handle: this.handle };
+            this._events.push(cancelledEvent);
+            this._status = 'cancelled';
+            yield cancelledEvent;
+            return;
+        }
+        const result = this._spawn('codex', ['exec', this._task.description, '-s', 'read-only', '-C', this._ctx.cwd], {
+            encoding: 'buffer',
+        });
+        const stdoutStr = result.stdout.toString('utf8');
+        for (const line of splitLines(stdoutStr)) {
+            const evt = { type: 'stdout', ts: ts(), handle: this.handle, line };
+            this._events.push(evt);
+            yield evt;
+        }
+        const stderrStr = result.stderr.toString('utf8');
+        for (const line of splitLines(stderrStr)) {
+            const evt = { type: 'stderr', ts: ts(), handle: this.handle, line };
+            this._events.push(evt);
+            yield evt;
+        }
+        if (result.status === 0) {
+            const completedEvent = {
+                type: 'completed',
+                ts: ts(),
+                handle: this.handle,
+                exitCode: 0,
+            };
+            this._events.push(completedEvent);
+            this._status = 'completed';
+            yield completedEvent;
+        }
+        else {
+            const exitCode = result.status ?? 1;
+            const failedEvent = {
+                type: 'failed',
+                ts: ts(),
+                handle: this.handle,
+                error: `codex exited with code ${exitCode}`,
+            };
+            this._events.push(failedEvent);
+            this._status = 'failed';
+            yield failedEvent;
+        }
+    }
+    snapshot() {
+        return {
+            handle: this.handle,
+            status: this._status,
+            events: [...this._events],
+        };
+    }
+    async teardown() {
+        // Idempotent no-op in v1.0 (spawnSync is synchronous; no process to kill)
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function splitLines(text) {
+    return text.split('\n').filter((line) => line.length > 0);
+}
+// ---------------------------------------------------------------------------
+// CodexExecRunner
+// ---------------------------------------------------------------------------
+export class CodexExecRunner {
+    id = 'codex-exec';
+    version = '1.0.0';
+    capabilities = ['read-only'];
+    _spawn;
+    constructor(options = {}) {
+        this._spawn = options.spawn ?? spawnSync;
+    }
+    prepare(task, ctx) {
+        if (task.permissions === 'workspace-write') {
+            throw new Error('codex-exec backend only supports read-only tasks in v1.0 alpha. See tech-debt item h-002 for workspace-write support.');
+        }
+        const handle = crypto.randomUUID();
+        return new CodexExecExecution(handle, task, ctx, this._spawn);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/runners/index.d.ts

@@ -0,0 +1,3 @@
+export { runnerEventSchema } from './types.js';
+export type { Runner, RunnerContext, RunnerEvent, RunnerExecution, RunnerSnapshot, RunnerTask, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/runners/index.js

@@ -0,0 +1,2 @@
+export { runnerEventSchema } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/runners/local-worktree/index.d.ts

@@ -0,0 +1,19 @@
+import type { SpawnSyncReturns } from 'node:child_process';
+import type { Runner, RunnerContext, RunnerExecution, RunnerTask } from '#runners/types';
+type SpawnSyncFn = (command: string, args: readonly string[], options?: {
+    cwd?: string;
+}) => SpawnSyncReturns<Buffer>;
+interface LocalWorktreeRunnerOptions {
+    /** Injected for testing; defaults to Node's spawnSync. */
+    readonly spawnSync?: SpawnSyncFn;
+}
+export declare class LocalWorktreeRunner implements Runner {
+    readonly id = "local-worktree";
+    readonly version = "0.1.0";
+    readonly capabilities: readonly string[];
+    private readonly spawnSync;
+    constructor(opts?: LocalWorktreeRunnerOptions);
+    prepare(task: RunnerTask, ctx: RunnerContext): RunnerExecution;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/runners/local-worktree/index.js

@@ -0,0 +1,85 @@
+import { spawnSync as nodeSpawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { generateWorktreePath } from './path.js';
+// ---------------------------------------------------------------------------
+// LocalWorktreeExecution
+// ---------------------------------------------------------------------------
+class LocalWorktreeExecution {
+    handle;
+    worktreePath;
+    spawnSync;
+    cwd;
+    events = [];
+    worktreeCreated = false;
+    tornDown = false;
+    constructor(handle, worktreePath, cwd, spawnFn) {
+        this.handle = handle;
+        this.worktreePath = worktreePath;
+        this.cwd = cwd;
+        this.spawnSync = spawnFn;
+    }
+    async *run(_signal) {
+        const ts = new Date().toISOString();
+        const started = { type: 'started', ts, handle: this.handle };
+        this.events.push(started);
+        yield started;
+        const result = this.spawnSync('git', ['worktree', 'add', this.worktreePath], { cwd: this.cwd });
+        if (result.status !== 0) {
+            const stderr = result.stderr instanceof Buffer ? result.stderr.toString() : String(result.stderr);
+            const failed = {
+                type: 'failed',
+                ts: new Date().toISOString(),
+                handle: this.handle,
+                error: stderr || 'git worktree add failed',
+            };
+            this.events.push(failed);
+            yield failed;
+            return;
+        }
+        this.worktreeCreated = true;
+        const completed = {
+            type: 'completed',
+            ts: new Date().toISOString(),
+            handle: this.handle,
+            exitCode: 0,
+        };
+        this.events.push(completed);
+        yield completed;
+    }
+    snapshot() {
+        const last = this.events[this.events.length - 1];
+        const status = last?.type === 'completed'
+            ? 'completed'
+            : last?.type === 'failed'
+                ? 'failed'
+                : last?.type === 'cancelled'
+                    ? 'cancelled'
+                    : 'running';
+        return { handle: this.handle, status, events: [...this.events] };
+    }
+    async teardown() {
+        if (this.tornDown || !this.worktreeCreated) {
+            return;
+        }
+        this.tornDown = true;
+        this.spawnSync('git', ['worktree', 'remove', '--force', this.worktreePath], { cwd: this.cwd });
+    }
+}
+// ---------------------------------------------------------------------------
+// LocalWorktreeRunner
+// ---------------------------------------------------------------------------
+export class LocalWorktreeRunner {
+    id = 'local-worktree';
+    version = '0.1.0';
+    capabilities = ['worktree'];
+    spawnSync;
+    constructor(opts = {}) {
+        this.spawnSync = opts.spawnSync ?? nodeSpawnSync;
+    }
+    prepare(task, ctx) {
+        const handle = randomUUID();
+        const worktreePath = generateWorktreePath(ctx.cwd, task.id);
+        return new LocalWorktreeExecution(handle, worktreePath, ctx.cwd, this.spawnSync);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/runners/local-worktree/path.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Generates a unique worktree path for the given task.
+ *
+ * Two calls with the same taskId return different paths because a UUID is
+ * appended, making each invocation distinct.
+ *
+ * @returns `<baseDir>/.wp-worktrees/<taskId>-<uuid>`
+ */
+export declare function generateWorktreePath(baseDir: string, taskId: string): string;
+//# sourceMappingURL=path.d.ts.map

package/dist/esm/runners/local-worktree/path.js

@@ -0,0 +1,14 @@
+import { join } from 'node:path';
+/**
+ * Generates a unique worktree path for the given task.
+ *
+ * Two calls with the same taskId return different paths because a UUID is
+ * appended, making each invocation distinct.
+ *
+ * @returns `<baseDir>/.wp-worktrees/<taskId>-<uuid>`
+ */
+export function generateWorktreePath(baseDir, taskId) {
+    const uuid = crypto.randomUUID();
+    return join(baseDir, '.wp-worktrees', `${taskId}-${uuid}`);
+}
+//# sourceMappingURL=path.js.map

package/dist/esm/runners/select.d.ts

@@ -0,0 +1,12 @@
+import type { RunnerTask } from '#runners/types';
+export type RunnerId = 'claude-subagent' | 'codex-exec' | 'local-worktree';
+export interface SelectRunnerOptions {
+    /** From --runner CLI flag */
+    runner?: string;
+    /** Injectable for tests; defaults to process.env */
+    env?: Readonly<Record<string, string>>;
+    /** Injectable: checks if cmd is on PATH. Defaults to real `which` via spawnSync. */
+    which?: (cmd: string) => boolean;
+}
+export declare function selectRunner(task: RunnerTask, opts?: SelectRunnerOptions): RunnerId;
+//# sourceMappingURL=select.d.ts.map

package/dist/esm/runners/select.js

@@ -0,0 +1,38 @@
+import { spawnSync } from 'node:child_process';
+function defaultWhich(cmd) {
+    const result = spawnSync('which', [cmd], { encoding: 'utf8' });
+    return result.status === 0;
+}
+function detect(env, which) {
+    const isClaudeEnv = env['CLAUDE_CODE'] !== undefined || env['ANTHROPIC_API_KEY'] !== undefined;
+    if (isClaudeEnv && !which('codex')) {
+        return 'claude-subagent';
+    }
+    if (which('codex')) {
+        return 'codex-exec';
+    }
+    return 'local-worktree';
+}
+function assertAllowed(candidate, task) {
+    const { runners } = task;
+    if (runners === undefined || runners.length === 0) {
+        return;
+    }
+    if (!runners.includes(candidate)) {
+        throw new Error(`Runner ${candidate} not in task's allowed runners: ${runners.join(', ')}`);
+    }
+}
+export function selectRunner(task, opts) {
+    const env = opts?.env ?? process.env;
+    const which = opts?.which ?? defaultWhich;
+    let candidate;
+    if (opts?.runner !== undefined) {
+        candidate = opts.runner;
+    }
+    else {
+        candidate = detect(env, which);
+    }
+    assertAllowed(candidate, task);
+    return candidate;
+}
+//# sourceMappingURL=select.js.map