@webpresso/agent-kit 0.21.0

package/dist/esm/mcp/tools/audit.js

@@ -0,0 +1,345 @@
+/**
+ * `wp_audit` MCP tool.
+ *
+ * Wraps the existing `wp audit *` subcommands behind one MCP tool with a
+ * `kind` enum. Returns a structured `{passed, kind, details}` payload wrapped
+ * in MCP `text` content blocks.
+ *
+ * Most kinds dispatch directly to the library functions exported from
+ * `#audit/repo-guardrails`, `#audit/tech-debt`, and `../../vite/local`.
+ * The `tph` kind shells out to `bun` because the implementation is a
+ * Bun-native script (`src/audit/audit-tph.ts`).
+ *
+ * Audit failures (whether represented as `ok: false` from the library or
+ * as a thrown error) are caught and returned as `{passed: false, ...}`
+ * — the handler never throws out, so the MCP server stays responsive.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { z } from 'zod';
+import { resolvePackageAsset } from '#utils/package-assets';
+import { applyOutputTransform } from '#output-transforms/index';
+import { createSummaryOutputSchema, createSummaryResult } from './_shared/result.js';
+const KINDS = [
+    'tph',
+    'tph-e2e',
+    'agents',
+    'catalog-drift',
+    'package-surface',
+    'docs-frontmatter',
+    'blueprint-lifecycle',
+    'architecture-drift',
+    'absolute-path-policy',
+    'roadmap-links',
+    'bundle-budget',
+    'commit-message',
+    'tech-debt',
+    'hook-surface',
+    'ai-contracts',
+    'no-relative-package-scripts',
+];
+const inputSchema = z.object({
+    kind: z.enum(KINDS),
+    /** Working tree to run the audit against. Alias kept as `directory` for back-compat. */
+    cwd: z.string().optional(),
+    directory: z.string().optional(),
+    messageFile: z.string().optional(),
+});
+const repoAuditSchema = z.object({
+    ok: z.boolean(),
+    title: z.string().optional(),
+    checked: z.number().optional(),
+    violations: z
+        .array(z.object({
+        message: z.string(),
+        file: z.string().optional(),
+    }))
+        .optional(),
+});
+const outputSchema = createSummaryOutputSchema({
+    details: z.union([repoAuditSchema, z.object({ exitCode: z.number() }), z.string()]),
+}).extend({
+    kind: z.enum(KINDS),
+});
+function resolveAuditScript(name) {
+    // Source layout: `src/mcp/tools/audit.ts` → `../../audit/<name>`.
+    const fromSource = new URL(`../../audit/${name}`, import.meta.url);
+    if (existsSync(fromSource)) {
+        return fromSource.pathname;
+    }
+    return resolvePackageAsset(`src/audit/${name}`);
+}
+async function runScript(script) {
+    return new Promise((resolve) => {
+        const child = spawn('bun', [script], { stdio: 'pipe' });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (error) => resolve({ exitCode: 1, output: [stdout, stderr, error.message].filter(Boolean).join('') }));
+        child.on('close', (code) => resolve({ exitCode: code ?? 1, output: [stdout, stderr].filter(Boolean).join('') }));
+    });
+}
+function wrap(payload, options = {}) {
+    return createSummaryResult(payload, options);
+}
+function summarizeRepoAudit(kind, result) {
+    const violationCount = result.violations?.length ?? 0;
+    if (result.ok) {
+        const checked = typeof result.checked === 'number' ? ` (${result.checked} checked)` : '';
+        return `${kind} audit passed${checked}`;
+    }
+    return `${kind} audit failed with ${violationCount} violation${violationCount === 1 ? '' : 's'}`;
+}
+function summarizeExitCode(kind, exitCode) {
+    return exitCode === 0 ? `${kind} audit passed` : `${kind} audit failed (exit ${exitCode})`;
+}
+async function dispatch(input) {
+    const { kind } = input;
+    switch (kind) {
+        case 'catalog-drift': {
+            const { auditCatalogDrift } = await import('#audit/repo-guardrails');
+            const auditResult = auditCatalogDrift(input.cwd ?? input.directory ?? process.cwd());
+            return {
+                passed: auditResult.ok,
+                summary: summarizeRepoAudit(kind, auditResult),
+                kind,
+                details: auditResult,
+            };
+        }
+        case 'package-surface': {
+            const { auditPackageSurface } = await import('#audit/package-surface');
+            const auditResult = auditPackageSurface(input.cwd ?? input.directory ?? process.cwd());
+            return {
+                passed: auditResult.ok,
+                summary: summarizeRepoAudit(kind, auditResult),
+                kind,
+                details: auditResult,
+            };
+        }
+        case 'agents': {
+            const { auditAgents } = await import('#audit/agents');
+            const auditResult = auditAgents(input.cwd ?? input.directory ?? process.cwd());
+            return {
+                passed: auditResult.ok,
+                summary: summarizeRepoAudit(kind, auditResult),
+                kind,
+                details: auditResult,
+            };
+        }
+        case 'docs-frontmatter': {
+            const { auditDocsFrontmatter } = await import('#audit/repo-guardrails');
+            const auditResult = auditDocsFrontmatter(input.cwd ?? input.directory ?? process.cwd());
+            return {
+                passed: auditResult.ok,
+                summary: summarizeRepoAudit(kind, auditResult),
+                kind,
+                details: auditResult,
+            };
+        }
+        case 'blueprint-lifecycle': {
+            const { auditBlueprintLifecycle } = await import('#audit/repo-guardrails');
+            const auditResult = auditBlueprintLifecycle(input.cwd ?? input.directory ?? process.cwd());
+            return {
+                passed: auditResult.ok,
+                summary: summarizeRepoAudit(kind, auditResult),
+                kind,
+                details: auditResult,
+            };
+        }
+        case 'architecture-drift': {
+            const { auditArchitectureDrift } = await import('#audit/architecture-drift');
+            const auditResult = auditArchitectureDrift(input.cwd ?? input.directory ?? process.cwd());
+            return {
+                passed: auditResult.ok,
+                summary: summarizeRepoAudit(kind, auditResult),
+                kind,
+                details: auditResult,
+            };
+        }
+        case 'absolute-path-policy': {
+            const { auditAbsolutePathPolicy } = await import('#audit/absolute-path-policy');
+            const auditResult = auditAbsolutePathPolicy(input.cwd ?? input.directory ?? process.cwd());
+            return {
+                passed: auditResult.ok,
+                summary: summarizeRepoAudit(kind, auditResult),
+                kind,
+                details: auditResult,
+            };
+        }
+        case 'roadmap-links': {
+            const { auditRoadmapLinks } = await import('#audit/roadmap-links');
+            const auditResult = auditRoadmapLinks(input.cwd ?? input.directory ?? process.cwd());
+            return {
+                passed: auditResult.ok,
+                summary: summarizeRepoAudit(kind, auditResult),
+                kind,
+                details: auditResult,
+            };
+        }
+        case 'commit-message': {
+            const messageFile = input.messageFile ?? input.cwd ?? input.directory;
+            if (!messageFile) {
+                return {
+                    passed: false,
+                    summary: 'commit-message audit could not run: message file missing',
+                    kind,
+                    details: 'commit-message requires a message file via `messageFile` or `directory`.',
+                };
+            }
+            const { auditCommitMessageFile } = await import('#audit/repo-guardrails');
+            const auditResult = auditCommitMessageFile(messageFile);
+            return {
+                passed: auditResult.ok,
+                summary: summarizeRepoAudit(kind, auditResult),
+                kind,
+                details: auditResult,
+            };
+        }
+        case 'tech-debt': {
+            const { auditTechDebt } = await import('#audit/tech-debt');
+            const auditResult = auditTechDebt(input.cwd ?? input.directory ?? process.cwd());
+            return {
+                passed: auditResult.ok,
+                summary: summarizeRepoAudit(kind, auditResult),
+                kind,
+                details: auditResult,
+            };
+        }
+        case 'ai-contracts': {
+            const { auditAiContracts } = await import('#audit/ai-contracts');
+            const auditResult = auditAiContracts(input.cwd ?? input.directory ?? process.cwd());
+            return {
+                passed: auditResult.ok,
+                summary: summarizeRepoAudit(kind, auditResult),
+                kind,
+                details: auditResult,
+            };
+        }
+        case 'bundle-budget': {
+            const { runBundleBudgetCli } = await import('../../vite/local.js');
+            const args = input.directory ? [input.directory] : [];
+            const exitCode = await runBundleBudgetCli(args);
+            return {
+                passed: exitCode === 0,
+                summary: summarizeExitCode(kind, exitCode),
+                kind,
+                details: { exitCode },
+            };
+        }
+        case 'tph': {
+            const script = resolveAuditScript('audit-tph.ts');
+            const { exitCode, output } = await runScript(script);
+            return {
+                passed: exitCode === 0,
+                summary: summarizeExitCode(kind, exitCode),
+                kind,
+                details: { exitCode },
+                ...applyOutputTransform(output, { toolName: `wp_audit-${kind}` }),
+            };
+        }
+        case 'tph-e2e': {
+            const script = resolveAuditScript('audit-tph-e2e.ts');
+            const { exitCode, output } = await runScript(script);
+            return {
+                passed: exitCode === 0,
+                summary: summarizeExitCode(kind, exitCode),
+                kind,
+                details: { exitCode },
+                ...applyOutputTransform(output, { toolName: `wp_audit-${kind}` }),
+            };
+        }
+        case 'hook-surface': {
+            const { auditHookSurface } = await import('#audit/hook-surface');
+            const auditResult = auditHookSurface(input.cwd ?? input.directory);
+            return {
+                passed: auditResult.passed,
+                summary: auditResult.passed
+                    ? 'hook-surface audit passed'
+                    : `hook-surface audit failed with ${auditResult.details.violations.length} violation${auditResult.details.violations.length === 1 ? '' : 's'}`,
+                kind,
+                details: {
+                    ok: auditResult.details.ok,
+                    violations: auditResult.details.violations.map((v) => ({
+                        message: v.reason,
+                    })),
+                },
+            };
+        }
+        case 'no-relative-package-scripts': {
+            const { auditNoRelativePackageScripts } = await import('#audit/repo-guardrails');
+            const auditResult = auditNoRelativePackageScripts(input.cwd ?? input.directory ?? process.cwd());
+            return {
+                passed: auditResult.ok,
+                summary: auditResult.ok
+                    ? 'no-relative-package-scripts passed'
+                    : `no-relative-package-scripts failed: ${auditResult.violations.length} violation${auditResult.violations.length === 1 ? '' : 's'}`,
+                kind,
+                details: {
+                    ok: auditResult.ok,
+                    violations: auditResult.violations,
+                },
+            };
+        }
+        default: {
+            // Exhaustiveness check — z.enum should make this unreachable.
+            const _exhaustive = kind;
+            return {
+                passed: false,
+                summary: 'audit dispatch hit unreachable case',
+                kind: String(_exhaustive),
+                details: 'unreachable',
+            };
+        }
+    }
+}
+const tool = {
+    name: 'wp_audit',
+    description: 'Run a packaged repo audit. `kind` selects the audit (tph, tph-e2e, catalog-drift, docs-frontmatter, blueprint-lifecycle, architecture-drift, absolute-path-policy, roadmap-links, bundle-budget, commit-message, tech-debt, hook-surface, package-surface, no-relative-package-scripts). Returns {passed, kind, details}.',
+    inputSchema,
+    outputSchema,
+    annotations: {
+        title: 'Audit',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    handler: async (raw) => {
+        let input;
+        try {
+            input = inputSchema.parse(raw ?? {});
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const kind = raw &&
+                typeof raw === 'object' &&
+                'kind' in raw &&
+                typeof raw.kind === 'string'
+                ? raw.kind
+                : 'unknown';
+            // Schema validation failure — agent supplied bad input; isError lets
+            // it distinguish "audit ran and found issues" from "audit didn't run".
+            return wrap({ passed: false, summary: `Invalid wp_audit input for ${kind}`, kind, details: message }, { isError: true });
+        }
+        try {
+            const payload = await dispatch(input);
+            return wrap(payload);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return wrap({
+                passed: false,
+                summary: `${input.kind} audit crashed`,
+                kind: input.kind,
+                details: message,
+            }, { isError: true });
+        }
+    },
+};
+export default tool;
+//# sourceMappingURL=audit.js.map

package/dist/esm/mcp/tools/ci-act.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDescriptor } from '#mcp/auto-discover';
+declare const tool: ToolDescriptor;
+export default tool;
+//# sourceMappingURL=ci-act.d.ts.map

package/dist/esm/mcp/tools/ci-act.js

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+import { buildPublicCiActCommand, sanitizePublicCiActArgv } from '#ci/act-runner.js';
+import { runSecretGateCommand } from '#secret-gate/runner.js';
+import { clipRawOutput, createSummaryOutputSchema, createSummaryResult } from './_shared/result.js';
+import { redactText } from './_shared/redact.js';
+const inputSchema = z
+    .object({
+    cwd: z.string().optional(),
+    workflowPath: z.string(),
+    job: z.string().optional(),
+    eventName: z
+        .enum(['pull_request', 'push', 'workflow_dispatch'])
+        .optional()
+        .default('pull_request'),
+    eventPath: z.string().optional(),
+    envProfile: z.string().optional().default('secrets-only'),
+    timeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .max(5 * 60_000)
+        .optional()
+        .default(120_000),
+    containerArchitecture: z.string().optional(),
+    platformImage: z.string().optional().default('ghcr.io/catthehacker/ubuntu:full-latest'),
+    execute: z.boolean().optional().default(false),
+})
+    .strict();
+const outputSchema = createSummaryOutputSchema({
+    details: z.object({
+        command: z.object({ command: z.string(), args: z.array(z.string()) }),
+        envProfile: z.string(),
+    }),
+});
+function publicCommandDetails(input) {
+    const command = sanitizePublicCiActArgv(buildPublicCiActCommand(input));
+    return { command: command.command, args: [...command.args] };
+}
+const tool = {
+    name: 'wp_ci_act',
+    description: 'Run local GitHub Actions workflows through `act` via the public secret contract (`wp config secrets ...`, then `with-secrets -- act ...`).',
+    inputSchema,
+    outputSchema,
+    annotations: {
+        title: 'CI act',
+        destructiveHint: false,
+        openWorldHint: false,
+    },
+    handler: async (raw, extra) => {
+        const input = inputSchema.parse(raw ?? {});
+        const command = buildPublicCiActCommand(input);
+        if (!input.execute) {
+            return createSummaryResult({
+                passed: true,
+                summary: `ci-act dry-run prepared via env profile ${input.envProfile}`,
+                details: {
+                    command: publicCommandDetails(input),
+                    envProfile: input.envProfile,
+                },
+            });
+        }
+        const result = await runSecretGateCommand({
+            cwd: input.cwd,
+            envProfile: input.envProfile,
+            command: 'act',
+            args: command.actArgs,
+            timeoutMs: input.timeoutMs,
+            signal: extra?.signal,
+        });
+        const merged = [result.stdout, result.stderr].filter(Boolean).join('\n');
+        const redacted = redactText(merged);
+        const clipped = clipRawOutput(redacted, 4_000, { toolName: 'wp_ci_act' });
+        const toolExecutionFailed = result.timedOut || result.aborted;
+        return createSummaryResult({
+            passed: result.exitCode === 0,
+            summary: result.exitCode === 0
+                ? `ci-act finished successfully via env profile ${input.envProfile}`
+                : `ci-act failed with exit ${result.exitCode} via env profile ${input.envProfile}`,
+            exitCode: result.exitCode,
+            details: {
+                command: publicCommandDetails(input),
+                envProfile: input.envProfile,
+            },
+            ...clipped,
+            ...(result.timedOut ? { failures: [{ message: 'timed out while running act' }] } : {}),
+            ...(result.aborted ? { failures: [{ message: 'aborted by client signal' }] } : {}),
+        }, toolExecutionFailed ? { isError: true } : {});
+    },
+};
+export default tool;
+//# sourceMappingURL=ci-act.js.map

package/dist/esm/mcp/tools/e2e.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `wp_e2e` MCP tool.
+ *
+ * First-class E2E execution surface backed by the existing portable `wp e2e`
+ * planner and host-adapter architecture. This tool is suite-aware and should
+ * be used for E2E execution instead of overloading `wp_test`.
+ */
+import { z } from 'zod';
+import type { ToolDescriptor } from '#mcp/auto-discover';
+declare const inputSchema: z.ZodObject<{
+    cwd: z.ZodOptional<z.ZodString>;
+    suite: z.ZodOptional<z.ZodString>;
+    runner: z.ZodOptional<z.ZodEnum<{
+        command: "command";
+        playwright: "playwright";
+        vitest: "vitest";
+    }>>;
+    config: z.ZodOptional<z.ZodString>;
+    files: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    headed: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    debug: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    reuseReset: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    noSupervisor: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    workers: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    testList: z.ZodOptional<z.ZodString>;
+    passthrough: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type AkE2eInput = z.infer<typeof inputSchema>;
+declare const tool: ToolDescriptor;
+export default tool;
+//# sourceMappingURL=e2e.d.ts.map

package/dist/esm/mcp/tools/e2e.js

@@ -0,0 +1,116 @@
+/**
+ * `wp_e2e` MCP tool.
+ *
+ * First-class E2E execution surface backed by the existing portable `wp e2e`
+ * planner and host-adapter architecture. This tool is suite-aware and should
+ * be used for E2E execution instead of overloading `wp_test`.
+ */
+import { z } from 'zod';
+import {} from '#e2e';
+import { createE2eExecutionPlan, plannedGroupsToCommandConfigs, runCommandConfigs, } from '#e2e/execution';
+import { applyOutputTransform } from '#output-transforms/index';
+import { createSummaryOutputSchema, createSummaryResult } from './_shared/result.js';
+const inputSchema = z.object({
+    cwd: z.string().optional(),
+    suite: z.string().optional(),
+    runner: z.enum(['playwright', 'vitest', 'command']).optional(),
+    config: z.string().optional(),
+    files: z.array(z.string()).optional().default([]),
+    headed: z.boolean().optional().default(false),
+    debug: z.boolean().optional().default(false),
+    reuseReset: z.boolean().optional().default(false),
+    noSupervisor: z.boolean().optional().default(false),
+    workers: z.union([z.number(), z.string()]).optional(),
+    testList: z.string().optional(),
+    passthrough: z.array(z.string()).optional(),
+});
+const outputSchema = createSummaryOutputSchema({
+    counts: z.object({
+        suiteCount: z.number(),
+        commandCount: z.number(),
+    }),
+    details: z.object({
+        commands: z.array(z.object({
+            command: z.string(),
+            args: z.array(z.string()),
+            env: z.record(z.string(), z.string()).optional(),
+        })),
+        suiteIds: z.array(z.string()),
+        runnerSummary: z.record(z.string(), z.number()),
+    }),
+});
+function summarizeRunners(groups) {
+    const counts = new Map();
+    for (const group of groups) {
+        for (const run of group.runs) {
+            counts.set(run.runner, (counts.get(run.runner) ?? 0) + 1);
+        }
+    }
+    return Object.fromEntries([...counts.entries()].toSorted(([a], [b]) => a.localeCompare(b)));
+}
+function collectSuiteIds(groups) {
+    return [...new Set(groups.flatMap((group) => group.runs.map((run) => run.suiteId)))].toSorted();
+}
+function toSerializableCommands(commands) {
+    return commands.map((command) => ({
+        command: command.command,
+        args: [...command.args],
+        env: command.env,
+    }));
+}
+function summarizeRun(passed, exitCode, suiteIds, commandCount) {
+    const suiteLabel = `${suiteIds.length} suite${suiteIds.length === 1 ? '' : 's'}`;
+    const commandLabel = `${commandCount} command${commandCount === 1 ? '' : 's'}`;
+    if (passed) {
+        return `e2e passed: ${suiteLabel}, ${commandLabel}`;
+    }
+    return `e2e failed: ${suiteLabel}, ${commandLabel} (exit ${exitCode})`;
+}
+const tool = {
+    name: 'wp_e2e',
+    description: 'Run E2E execution through the portable webpresso planner. Suite-aware and host-adapter-aware; returns `{passed, exitCode, commands, output}` plus suite and runner summaries.',
+    inputSchema,
+    outputSchema,
+    annotations: {
+        title: 'E2E',
+        destructiveHint: false,
+        openWorldHint: false,
+    },
+    handler: async (raw, extra) => {
+        const input = inputSchema.parse(raw ?? {});
+        const groups = await createE2eExecutionPlan({
+            suite: input.suite,
+            runner: input.runner,
+            config: input.config,
+            files: input.files,
+            headed: input.headed,
+            debug: input.debug,
+            reuseReset: input.reuseReset,
+            noSupervisor: input.noSupervisor,
+            workers: input.workers,
+            testList: input.testList,
+            passthrough: input.passthrough,
+        }, input.cwd);
+        const commands = plannedGroupsToCommandConfigs(groups);
+        const result = await runCommandConfigs(commands, { signal: extra?.signal });
+        const suiteIds = collectSuiteIds(groups);
+        const payload = {
+            passed: result.passed,
+            summary: summarizeRun(result.passed, result.exitCode, suiteIds, commands.length),
+            exitCode: result.exitCode,
+            counts: {
+                suiteCount: suiteIds.length,
+                commandCount: commands.length,
+            },
+            details: {
+                commands: toSerializableCommands(commands),
+                suiteIds,
+                runnerSummary: summarizeRunners(groups),
+            },
+            ...applyOutputTransform(result.output, { toolName: 'wp_e2e' }),
+        };
+        return createSummaryResult(payload);
+    },
+};
+export default tool;
+//# sourceMappingURL=e2e.js.map

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

@@ -0,0 +1,27 @@
+/**
+ * `wp_format` MCP tool.
+ *
+ * Runs `oxfmt` on the resolved project root. By default writes fixes in
+ * place; pass `check: true` to verify formatting without writing (useful
+ * for CI / pre-commit). Returns the standard summary-first payload:
+ *
+ *   {
+ *     passed: boolean,
+ *     summary: string,
+ *     exitCode: number,
+ *     details: { spawnError?: string },
+ *   }
+ *
+ * No fallback — `oxfmt` must be on PATH. When missing, the tool returns
+ * `isError: true` with a clear install hint.
+ */
+import { z } from 'zod';
+import type { ToolDescriptor } from '#mcp/auto-discover';
+declare const inputSchema: z.ZodObject<{
+    check: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    cwd: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AkFormatInput = z.infer<typeof inputSchema>;
+declare const tool: ToolDescriptor;
+export default tool;
+//# sourceMappingURL=format.d.ts.map