@webpresso/agent-kit 0.21.0

package/dist/esm/e2e/suite-registry.d.ts

@@ -0,0 +1,9 @@
+import type { E2eSuiteDefinition, ResolvedE2eFile } from './types.js';
+export interface NormalizeE2ePathOptions {
+    extraRootPatterns?: readonly RegExp[];
+}
+export declare function defineE2eSuite<TSuite extends E2eSuiteDefinition>(suite: TSuite): TSuite;
+export declare function normalizeE2ePath(filePath: string, options?: NormalizeE2ePathOptions): string;
+export declare function resolveE2eSuiteId(name: string, suites: readonly E2eSuiteDefinition[]): string | null;
+export declare function resolveE2eSuiteForPath(filePath: string, suites: readonly E2eSuiteDefinition[], normalizeOptions?: NormalizeE2ePathOptions): ResolvedE2eFile | null;
+//# sourceMappingURL=suite-registry.d.ts.map

package/dist/esm/e2e/suite-registry.js

@@ -0,0 +1,30 @@
+const BUILTIN_ROOT_PATTERNS = [
+    /^(?:.*\/)?apps\/e2e\//u,
+    /^(?:.*\/)?apps\/web\/[^/]+\/e2e\//u,
+    /^(?:.*\/)?apps\/workers\/[^/]+\/e2e\//u,
+];
+export function defineE2eSuite(suite) {
+    return suite;
+}
+export function normalizeE2ePath(filePath, options = {}) {
+    const normalizedPath = filePath.replace(/\\/gu, '/').replace(/^\.\/+/u, '');
+    const patterns = options.extraRootPatterns
+        ? [...BUILTIN_ROOT_PATTERNS, ...options.extraRootPatterns]
+        : BUILTIN_ROOT_PATTERNS;
+    for (const pattern of patterns) {
+        const match = normalizedPath.match(pattern);
+        if (match?.index !== undefined) {
+            return normalizedPath.slice(match.index + match[0].length);
+        }
+    }
+    return normalizedPath;
+}
+export function resolveE2eSuiteId(name, suites) {
+    return suites.find((suite) => suite.id === name || suite.aliases?.includes(name))?.id ?? null;
+}
+export function resolveE2eSuiteForPath(filePath, suites, normalizeOptions) {
+    const normalizedPath = normalizeE2ePath(filePath, normalizeOptions);
+    const suite = suites.find((candidate) => candidate.fileMatchers.some((matcher) => normalizedPath.startsWith(matcher)));
+    return suite ? { normalizedPath, suiteId: suite.id } : null;
+}
+//# sourceMappingURL=suite-registry.js.map

package/dist/esm/e2e/types.d.ts

@@ -0,0 +1,81 @@
+export type E2eRunnerKind = 'playwright' | 'vitest' | 'command';
+export interface CommandConfig {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+export interface E2eStepDefinition {
+    runner: E2eRunnerKind;
+    logName: string;
+    configPath?: string;
+    fixedFiles?: readonly string[];
+    fixedArgs?: readonly string[];
+    commandArgs?: readonly string[];
+    supportsHeaded?: boolean;
+    supportsDebug?: boolean;
+    batchKey?: string;
+    envProfile?: string;
+    reportDir?: string;
+    env?: Record<string, string>;
+}
+export interface E2eSuiteDefinition {
+    id: string;
+    aliases?: readonly string[];
+    fileMatchers: readonly string[];
+    batchKey: string;
+    envProfile?: string;
+    steps: readonly E2eStepDefinition[];
+    env?: Record<string, string>;
+}
+export interface ResolvedE2eFile {
+    normalizedPath: string;
+    suiteId: string;
+}
+export interface E2eHostAdapter {
+    listSuites(): readonly E2eSuiteDefinition[];
+    resolveSuiteId(name: string): string | null;
+    resolveSuiteGroup?(name: string): readonly string[] | null;
+    normalizeFilePath(filePath: string): string;
+    resolveSuiteForFile(filePath: string): ResolvedE2eFile | null;
+    buildExecutionPlan?(request: E2eExecutionRequest): PlannedE2eRunGroup[];
+}
+export interface E2eCommandRequest {
+    files?: readonly string[];
+    headed?: boolean;
+    debug?: boolean;
+    reuseReset?: boolean;
+    noSupervisor?: boolean;
+    workers?: number | string;
+    testList?: string;
+    passthrough?: readonly string[];
+}
+export interface E2eExecutionRequest extends E2eCommandRequest {
+    suite?: string;
+    file?: readonly string[];
+}
+export interface E2eStepCommandOptions extends E2eCommandRequest {
+    step: E2eStepDefinition;
+}
+export interface E2eRunPlannerOptions extends E2eCommandRequest {
+    suite?: string;
+    file?: readonly string[];
+    hostAdapter: E2eHostAdapter;
+}
+export interface PlannedE2eRunStep {
+    suiteId: string;
+    batchKey: string;
+    envProfile?: string;
+    runner: E2eRunnerKind;
+    logName: string;
+    reportDir?: string;
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+export interface PlannedE2eRunGroup {
+    batchKey: string;
+    envProfile?: string;
+    runs: PlannedE2eRunStep[];
+    env?: Record<string, string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/e2e/types.js

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

package/dist/esm/format/errors.d.ts

@@ -0,0 +1,2 @@
+export declare function getErrorMessage(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/esm/format/errors.js

@@ -0,0 +1,15 @@
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/format/format.d.ts

@@ -0,0 +1,2 @@
+export declare function formatBytes(bytes: number): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/esm/format/format.js

@@ -0,0 +1,16 @@
+export function formatBytes(bytes) {
+    if (!Number.isFinite(bytes)) {
+        return '0 B';
+    }
+    const sign = bytes < 0 ? '-' : '';
+    let value = Math.abs(bytes);
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let unitIndex = 0;
+    while (value >= 1024 && unitIndex < units.length - 1) {
+        value /= 1024;
+        unitIndex += 1;
+    }
+    const formatted = unitIndex === 0 ? String(value) : value.toFixed(value >= 10 ? 1 : 2);
+    return `${sign}${formatted.replace(/\.0+$/, '')} ${units[unitIndex]}`;
+}
+//# sourceMappingURL=format.js.map

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

@@ -0,0 +1,35 @@
+/**
+ * Stable subpath export: `webpresso/format`.
+ *
+ * Wraps the `oxfmt` binary for repo formatting. Mirrors the `runLint` API
+ * shape so consumers can compose lint + format in the same pipeline. Unlike
+ * `runLint` there is NO fallback — `oxfmt` must be on PATH; if missing we
+ * surface a clear error naming the missing binary and the install command.
+ */
+export interface FormatResult {
+    readonly passed: boolean;
+    readonly exitCode: number;
+    readonly output: string;
+    readonly fixedFiles?: readonly string[];
+    readonly spawnError?: string;
+    readonly timedOut?: boolean;
+    readonly aborted?: boolean;
+}
+export interface RunFormatOptions {
+    /** Files or glob targets. When omitted, oxfmt's default discovery runs. */
+    readonly files?: readonly string[];
+    /** When true, only check (exit 1 on unformatted). When false/undefined, write fixes. */
+    readonly check?: boolean;
+    /** Override the resolved project root. */
+    readonly cwd?: string;
+    /** Hard cap on the spawned process. Defaults to 5 minutes. */
+    readonly timeoutMs?: number;
+    /** Optional cancellation signal propagated to the child process. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Run formatter and return a structured result. Throws a clear error when
+ * `oxfmt` is not on PATH (no silent fallback).
+ */
+export declare function runFormat(options?: RunFormatOptions): Promise<FormatResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/format/index.js

@@ -0,0 +1,67 @@
+/**
+ * Stable subpath export: `webpresso/format`.
+ *
+ * Wraps the `oxfmt` binary for repo formatting. Mirrors the `runLint` API
+ * shape so consumers can compose lint + format in the same pipeline. Unlike
+ * `runLint` there is NO fallback — `oxfmt` must be on PATH; if missing we
+ * surface a clear error naming the missing binary and the install command.
+ */
+import { isMissingBinary, isRunFailure, runCommand } from '#mcp/tools/_shared/run-command';
+import { resolveProjectRoot } from '#mcp/tools/_shared/project-root';
+const DEFAULT_FORMAT_TIMEOUT_MS = 5 * 60 * 1_000;
+/**
+ * Run formatter and return a structured result. Throws a clear error when
+ * `oxfmt` is not on PATH (no silent fallback).
+ */
+export async function runFormat(options = {}) {
+    const cwd = resolveProjectRoot(options.cwd ? { explicitCwd: options.cwd } : {});
+    const runOptions = {
+        timeoutMs: options.timeoutMs ?? DEFAULT_FORMAT_TIMEOUT_MS,
+        signal: options.signal,
+        cwd,
+    };
+    const args = [];
+    if (options.check)
+        args.push('--check');
+    else
+        args.push('--write');
+    // Explicit --ignore-path so oxfmt does not auto-pick `.prettierignore`.
+    // Repos often ship `.prettierignore` with `*` to disable IDE Prettier
+    // extensions (which would fight oxfmt). Without this flag oxfmt sees the
+    // catchall and skips everything. Honor only `.gitignore` plus the patterns
+    // declared in `.oxfmtrc.json#ignorePatterns`.
+    args.push('--ignore-path', '.gitignore');
+    if (options.files && options.files.length > 0)
+        args.push(...options.files);
+    const outcome = await runCommand('oxfmt', args, runOptions);
+    if (isRunFailure(outcome)) {
+        if (isMissingBinary(outcome)) {
+            throw new Error("oxfmt binary not found on PATH. Install it as a devDependency: 'vp install -D oxfmt'");
+        }
+        return {
+            passed: false,
+            exitCode: 1,
+            output: '',
+            spawnError: `oxfmt spawn failed: ${outcome.error.code ?? 'unknown'} ${outcome.error.message}`,
+        };
+    }
+    const output = [outcome.stdout, outcome.stderr].filter(Boolean).join('');
+    return {
+        passed: outcome.exitCode === 0,
+        exitCode: outcome.exitCode,
+        output,
+        fixedFiles: options.check ? undefined : parseFixedFiles(outcome.stdout),
+        timedOut: outcome.timedOut || undefined,
+        aborted: outcome.aborted || undefined,
+    };
+}
+/**
+ * Best-effort extraction of files oxfmt rewrote. oxfmt does not currently emit
+ * a structured list, so this returns an empty array unless a future version
+ * adds machine-readable output. Kept as an opt-in field so downstream callers
+ * can opt into richer reporting later without an API break.
+ */
+function parseFixedFiles(_stdout) {
+    return [];
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/hooks/check-dev-link/index.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env bun
+import { STATE_FILE_RELATIVE_PATH, type DevLinkState, readDevLinkState } from '#dev/dev-link-state';
+export interface DevLinkBreakage {
+    expected: string;
+    actual: string | null;
+    packageName: string;
+    projectDir: string;
+}
+export interface DetectOptions {
+    cwd?: string;
+}
+export declare function detectDevLinkBreakage(options?: DetectOptions): DevLinkBreakage | null;
+export declare function formatBreakageMessage(breakage: DevLinkBreakage): string;
+export declare function buildSessionStartEnvelope(message: string): string;
+export declare function buildOutput(cwd: string): string | null;
+export declare function main(): Promise<void>;
+export { STATE_FILE_RELATIVE_PATH, readDevLinkState };
+export type { DevLinkState };
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/hooks/check-dev-link/index.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env bun
+/**
+ * SessionStart hook: warn loud when webpresso dev-link is broken.
+ *
+ * Cross-runtime — emits the additionalContext envelope shared by Claude Code
+ * (docs.claude.com/en/docs/claude-code/hooks) and Codex CLI
+ * (developers.openai.com/codex/hooks). Both runtimes inject `additionalContext`
+ * into the session's developer context.
+ *
+ * Catches the rare path where `vp install --ignore-scripts` skipped the
+ * consumer's `wp-restore-dev-links` postinstall, leaving
+ * node_modules/webpresso pointed at the pnpm-store snapshot
+ * instead of the live source declared in `.webpresso/webpresso-dev-link.json`.
+ * Always exits 0; never blocks session start.
+ */
+import { readlinkSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { STATE_FILE_RELATIVE_PATH, readDevLinkState } from '#dev/dev-link-state';
+export function detectDevLinkBreakage(options = {}) {
+    const cwd = options.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+    const state = readDevLinkState(cwd);
+    if (state === null)
+        return null;
+    const target = join(cwd, 'node_modules', state.package);
+    let actual;
+    try {
+        actual = readlinkSync(target);
+    }
+    catch {
+        actual = null;
+    }
+    if (actual === state.linkedFrom)
+        return null;
+    return {
+        expected: state.linkedFrom,
+        actual,
+        packageName: state.package,
+        projectDir: cwd,
+    };
+}
+export function formatBreakageMessage(breakage) {
+    const actualLabel = breakage.actual ?? '<store snapshot>';
+    return [
+        `WARNING: ${breakage.packageName} dev-link is broken.`,
+        `State file (${STATE_FILE_RELATIVE_PATH}) says linkedFrom=${breakage.expected} but node_modules/${breakage.packageName} -> ${actualLabel}.`,
+        'Hooks will run STALE code.',
+        `Fix: run \`vp install\` (postinstall wp-restore-dev-links re-creates the symlink), or from the webpresso checkout: \`vp run dev:link --consumer ${breakage.projectDir}\`.`,
+    ].join(' ');
+}
+export function buildSessionStartEnvelope(message) {
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'SessionStart',
+            additionalContext: message,
+        },
+    });
+}
+export function buildOutput(cwd) {
+    const breakage = detectDevLinkBreakage({ cwd });
+    if (breakage === null)
+        return null;
+    return buildSessionStartEnvelope(formatBreakageMessage(breakage));
+}
+export async function main() {
+    // Drain stdin if attached — Claude Code and Codex both pipe the hook
+    // payload here. We don't read it (cwd is enough) but a closed stdin
+    // can break upstream pipes if the caller is still writing.
+    if (!process.stdin.isTTY) {
+        await new Promise((resolve) => {
+            process.stdin.on('data', () => undefined);
+            process.stdin.on('end', resolve);
+            process.stdin.on('error', resolve);
+        });
+    }
+    const out = buildOutput(process.cwd());
+    if (out !== null)
+        process.stdout.write(`${out}\n`);
+    process.exit(0);
+}
+if (process.argv[1] &&
+    realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])) {
+    void main();
+}
+// Re-export so tests can stub the state file path if needed in future.
+export { STATE_FILE_RELATIVE_PATH, readDevLinkState };
+//# sourceMappingURL=index.js.map

package/dist/esm/hooks/doctor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `wp hooks doctor` — post-install plugin health verification.
+ *
+ * Verifies the agent-kit plugin installation is healthy:
+ * - all hook bins exist
+ * - bins are executable (skip on win32)
+ * - bins respond to empty stdin with exit 0 + JSON
+ * - plugin.json exists and references only paths that exist
+ * - MCP server starts and responds to tools/list (soft-fail)
+ * - installed host CLIs (Codex/OpenCode/Claude) can see the expected surfaces
+ */
+export interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+export interface DoctorResult {
+    ok: boolean;
+    checks: DoctorCheck[];
+}
+type HostCheckMode = 'auto' | 'skip' | 'required';
+export interface RunHooksDoctorOptions {
+    skipMcp?: boolean;
+    hosts?: HostCheckMode;
+    hostNames?: Array<'codex' | 'opencode' | 'claude'>;
+    /** Override the working directory used to detect RTK marker files. Defaults to process.cwd(). */
+    cwd?: string;
+}
+export declare function findOwningPackageRoot(startDir: string): string | null;
+export declare function checkRtkOnPath(cwd?: string): Promise<DoctorCheck | null>;
+export declare function runHooksDoctor(opts?: RunHooksDoctorOptions): Promise<DoctorResult>;
+export declare function printHooksDoctor(opts?: RunHooksDoctorOptions): Promise<number>;
+export {};
+//# sourceMappingURL=doctor.d.ts.map