@webpresso/agent-kit 0.21.4 → 0.23.0

package/dist/esm/hooks/pretool-guard/validators/path-contract.d.ts

@@ -11,5 +11,6 @@ export declare function getNonCanonicalPlanningPathViolation(filePath: string, b
  * accepted blueprints root layout (or the explicitly provided root).
  */
 export declare function isCanonicalBlueprintOverviewPath(filePath: string, blueprintsRoot?: string): boolean;
-export declare function getBlueprintPathViolation(filePath: string, blueprintsRoot?: string): string | null;
+export declare function isCanonicalBlueprintDocumentPath(filePath: string, blueprintsRoot?: string): boolean;
+export declare function getBlueprintPathViolation(filePath: string, blueprintsRoot?: string, cwd?: string): string | null;
 //# sourceMappingURL=path-contract.d.ts.map

package/dist/esm/hooks/pretool-guard/validators/path-contract.js

@@ -1,16 +1,10 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { BLUEPRINT_OVERVIEW_FILENAME, getBlueprintAlternateDocumentPath, isBlueprintSupportingMarkdownRelativePath, isBlueprintStatus, parseBlueprintDocumentRelativePath, } from '#utils/document-paths.js';
 export const BLUEPRINTS_ROOT = 'webpresso/blueprints';
 const DEFAULT_BLUEPRINTS_ROOT = 'blueprints';
 export const TECH_DEBT_ROOT = 'webpresso/tech-debt';
 const DEFAULT_TECH_DEBT_ROOT = 'tech-debt';
-const BLUEPRINT_STATUSES = new Set([
-    'draft',
-    'planned',
-    'parked',
-    'in-progress',
-    'completed',
-    'archived',
-]);
-const KEBAB_CASE_SEGMENT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 // Both canonical blueprint-root layouts accepted by default.
 const CANONICAL_BLUEPRINTS_ROOTS = [BLUEPRINTS_ROOT, DEFAULT_BLUEPRINTS_ROOT];
 const CANONICAL_TECH_DEBT_ROOTS = [TECH_DEBT_ROOT, DEFAULT_TECH_DEBT_ROOT];
@@ -20,6 +14,16 @@ function normalizePlanningPath(filePath) {
 function matchesRoot(normalized, root) {
     return normalized === root || normalized.startsWith(`${root}/`);
 }
+function stripBlueprintRoot(normalized, roots) {
+    for (const root of roots) {
+        if (normalized === root)
+            return { relativePath: '', root };
+        if (normalized.startsWith(`${root}/`)) {
+            return { relativePath: normalized.slice(root.length + 1), root };
+        }
+    }
+    return null;
+}
 /**
  * Returns true if the path is under any accepted blueprints root.
  * Pass `blueprintsRoot` to restrict to a single configured root.
@@ -66,39 +70,60 @@ export function getNonCanonicalPlanningPathViolation(filePath, blueprintsRoot, t
  * accepted blueprints root layout (or the explicitly provided root).
  */
 export function isCanonicalBlueprintOverviewPath(filePath, blueprintsRoot) {
+    const parsed = getCanonicalBlueprintDocument(filePath, blueprintsRoot);
+    return parsed?.shape === 'folder';
+}
+export function isCanonicalBlueprintDocumentPath(filePath, blueprintsRoot) {
+    return getCanonicalBlueprintDocument(filePath, blueprintsRoot) !== null;
+}
+function getCanonicalBlueprintDocument(filePath, blueprintsRoot) {
     const normalized = normalizePlanningPath(filePath);
     const roots = blueprintsRoot ? [blueprintsRoot] : CANONICAL_BLUEPRINTS_ROOTS;
-    return roots.some((root) => {
-        const rootParts = root.split('/');
-        const parts = normalized.split('/');
-        const n = rootParts.length;
-        return (parts.length === n + 3 &&
-            parts.slice(0, n).join('/') === root &&
-            BLUEPRINT_STATUSES.has(parts[n] ?? '') &&
-            KEBAB_CASE_SEGMENT.test(parts[n + 1] ?? '') &&
-            parts[n + 2] === '_overview.md');
-    });
+    const stripped = stripBlueprintRoot(normalized, roots);
+    return stripped ? parseBlueprintDocumentRelativePath(stripped.relativePath) : null;
 }
-export function getBlueprintPathViolation(filePath, blueprintsRoot) {
+export function getBlueprintPathViolation(filePath, blueprintsRoot, cwd = process.cwd()) {
     const normalized = normalizePlanningPath(filePath);
     if (!isBlueprintPath(normalized, blueprintsRoot))
         return null;
-    if (normalized.endsWith('/_overview.md') &&
-        !isCanonicalBlueprintOverviewPath(normalized, blueprintsRoot)) {
-        const root = blueprintsRoot ?? BLUEPRINTS_ROOT;
-        return `Blueprint overview files must live at ${root}/<status>/<slug>/_overview.md. Got: ${normalized}`;
-    }
     const roots = blueprintsRoot ? [blueprintsRoot] : CANONICAL_BLUEPRINTS_ROOTS;
-    for (const root of roots) {
-        const rootParts = root.split('/');
-        const parts = normalized.split('/');
-        const n = rootParts.length;
-        if (parts.length === n + 2 &&
-            parts.slice(0, n).join('/') === root &&
-            BLUEPRINT_STATUSES.has(parts[n] ?? '') &&
-            normalized.endsWith('.md')) {
-            return `Blueprint markdown files cannot live directly under a status directory. Move this file to ${root}/${parts[n]}/<slug>/_overview.md or place supporting docs inside ${root}/${parts[n]}/<slug>/. Got: ${normalized}`;
+    const stripped = stripBlueprintRoot(normalized, roots);
+    if (!stripped) {
+        return null;
+    }
+    const parsed = parseBlueprintDocumentRelativePath(stripped.relativePath);
+    if (parsed) {
+        const blueprintRoot = path.isAbsolute(filePath)
+            ? path.join(path.parse(filePath).root, stripped.root)
+            : path.join(cwd, stripped.root);
+        const currentPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, normalized);
+        const alternate = getBlueprintAlternateDocumentPath(blueprintRoot, currentPath);
+        if (alternate && existsSync(alternate)) {
+            return `Blueprint slug "${parsed.state}/${parsed.slug}" cannot exist in both flat and folder forms. Remove either ${path.relative(cwd, filePath).replace(/\\/g, '/')} or ${path.relative(cwd, alternate).replace(/\\/g, '/')}.`;
         }
+        return null;
+    }
+    const parts = stripped.relativePath.split('/').filter((segment) => segment.length > 0);
+    const [state, slug, doc] = parts;
+    const root = stripped.root;
+    if (parts.length === 2 &&
+        typeof doc === 'undefined' &&
+        typeof slug === 'string' &&
+        slug.endsWith('.md')) {
+        return `Blueprint markdown under ${root}/<status>/ must be either <slug>.md or <slug>/${BLUEPRINT_OVERVIEW_FILENAME}. Got: ${normalized}`;
+    }
+    if (parts.length === 3 && doc === BLUEPRINT_OVERVIEW_FILENAME) {
+        return `Blueprint overview files must live at ${root}/<status>/<slug>/${BLUEPRINT_OVERVIEW_FILENAME}. Got: ${normalized}`;
+    }
+    if (parts.length === 3 && isBlueprintSupportingMarkdownRelativePath(stripped.relativePath)) {
+        const canonicalOverviewPath = path.join(cwd, root, state ?? '', slug ?? '', BLUEPRINT_OVERVIEW_FILENAME);
+        if (!existsSync(canonicalOverviewPath)) {
+            return `Supporting blueprint markdown requires ${root}/${state}/${slug}/${BLUEPRINT_OVERVIEW_FILENAME}. Got: ${normalized}`;
+        }
+        return null;
+    }
+    if (parts.length >= 3 && isBlueprintStatus(state)) {
+        return `Blueprint markdown must use one of ${root}/<status>/<slug>.md or ${root}/<status>/<slug>/${BLUEPRINT_OVERVIEW_FILENAME}. Supporting markdown is only allowed beside ${BLUEPRINT_OVERVIEW_FILENAME}. Got: ${normalized}`;
     }
     return null;
 }

package/dist/esm/hooks/pretool-guard/validators/plan-frontmatter.js

@@ -1,6 +1,6 @@
 import jsYaml from 'js-yaml';
 import { getContent, getFilePath } from '#hooks/shared/types';
-import { getNonCanonicalPlanningPathViolation, isBlueprintPath } from './path-contract.js';
+import { getNonCanonicalPlanningPathViolation, isBlueprintPath, isCanonicalBlueprintDocumentPath, } from './path-contract.js';
 import { createSkipResult } from './skip-result.js';
 // Keep aligned with webpresso/blueprint planStatusSchema + plan type enum.
 const VALID_TYPES = ['blueprint', 'parent-roadmap'];
@@ -10,8 +10,8 @@ function shouldValidatePath(filePath) {
     const normalized = filePath.startsWith('/') ? filePath.slice(1) : filePath;
     const nonCanonicalPlanningPath = getNonCanonicalPlanningPathViolation(normalized);
     const currentPath = isBlueprintPath(normalized);
-    const isOverviewFile = normalized.endsWith('/README.md') || normalized.endsWith('/_overview.md');
-    return !nonCanonicalPlanningPath && currentPath && isOverviewFile;
+    const isCanonicalBlueprintDoc = isCanonicalBlueprintDocumentPath(normalized);
+    return !nonCanonicalPlanningPath && currentPath && isCanonicalBlueprintDoc;
 }
 export function extractFrontmatterBlock(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---/);

package/dist/esm/hooks/shared/routing-block.js

@@ -8,6 +8,7 @@ export const WP_ROUTING_BLOCK = `<wp_routing>
   <description>
     Use the wp_* MCP tools for all test, lint, typecheck, qa, audit, local CI act,
     and Cloudflare Worker tail operations.
+    If a wp_* MCP tool is stale or unavailable, use the matching wp CLI command.
     If context-mode plugin routing is present, let it own ctx_* data-processing nudges.
     These tools return structured, summary-first results and keep output concise.
   </description>
@@ -55,7 +56,7 @@ export const WP_ROUTING_BLOCK = `<wp_routing>
     <tool name="wp_test">
       <category>dev-workflow</category>
       <trigger>running tests, verifying test suite, check if tests pass</trigger>
-      <forbidden>just test, pnpm test, vitest</forbidden>
+      <forbidden>just test, pnpm test, vitest, npx vitest, npm exec -- vitest, yarn vitest, bunx vitest, node ./node_modules/vitest/vitest.mjs</forbidden>
     </tool>
     <tool name="wp_e2e">
       <category>dev-workflow</category>
@@ -65,12 +66,12 @@ export const WP_ROUTING_BLOCK = `<wp_routing>
     <tool name="wp_lint">
       <category>dev-workflow</category>
       <trigger>linting, code style checks, lint errors</trigger>
-      <forbidden>just lint, oxlint</forbidden>
+      <forbidden>just lint, oxlint, node ./node_modules/oxlint/bin/oxlint</forbidden>
     </tool>
     <tool name="wp_typecheck">
       <category>dev-workflow</category>
       <trigger>type checking, TypeScript errors, type errors</trigger>
-      <forbidden>tsc</forbidden>
+      <forbidden>tsc, node ./node_modules/typescript/bin/tsc</forbidden>
     </tool>
     <tool name="wp_qa">
       <category>dev-workflow</category>
@@ -102,6 +103,11 @@ export const WP_ROUTING_BLOCK = `<wp_routing>
     <rule>Context-mode owns ctx_* routing when that plugin is installed.</rule>
   </ownership_boundary>
 
+  <hook_diagnostics>
+    <rule>Prefer wp hook &lt;name&gt; over direct wp-&lt;hook-bin&gt; calls when a wp hook command exists.</rule>
+    <rule>Direct wp-* hook bins remain generated-hook runtime internals, not recommended agent diagnostics.</rule>
+  </hook_diagnostics>
+
   <package_guidance>
     <rule>Consumers add @webpresso/agent-kit and import config helpers through @webpresso/agent-kit/* subpath exports such as @webpresso/agent-kit/oxlint, @webpresso/agent-kit/vitest/node, @webpresso/agent-kit/test-preset, @webpresso/agent-kit/e2e-preset, @webpresso/agent-kit/tsconfig/base.json, @webpresso/agent-kit/docs-lint, @webpresso/agent-kit/stryker, @webpresso/agent-kit/launch, and @webpresso/agent-kit/workers-test.</rule>
     <rule>Do not recommend adding retired split agent config packages for consumer projects; keep wp_* MCP tool names and wp-* hook bin names unchanged.</rule>
@@ -114,9 +120,16 @@ export const WP_ROUTING_BLOCK = `<wp_routing>
     <command>just qa</command>
     <command>just lint-md</command>
     <command>vitest</command>
+    <command>npx vitest</command>
+    <command>npm exec -- vitest</command>
+    <command>yarn vitest</command>
+    <command>bunx vitest</command>
+    <command>node ./node_modules/vitest/vitest.mjs</command>
     <command>oxlint</command>
+    <command>node ./node_modules/oxlint/bin/oxlint</command>
     <command>markdownlint-cli2</command>
     <command>tsc</command>
+    <command>node ./node_modules/typescript/bin/tsc</command>
     <command>act</command>
     <command>vp exec act</command>
     <command>pnpm exec act</command>
@@ -133,7 +146,8 @@ export const WP_ROUTING_BLOCK = `<wp_routing>
   </output_format>
 
   <fallback>
-    When MCP tools are unavailable, use just recipes directly and keep output brief.
+    When MCP tools are unavailable or stale, use the matching wp CLI command and keep output brief.
+    Do not fall through to raw tool bins under node_modules when a wp wrapper exists.
     .omx is runtime/state only; it is not a direct hook surface.
   </fallback>
 </wp_routing>`;

package/dist/esm/hooks/shared/validators/blueprint.js

@@ -26,6 +26,9 @@ export function shouldSkipFile(filePath) {
     if (!filePath)
         return false;
     const normalized = filePath.startsWith('/') ? filePath.slice(1) : filePath;
+    if (normalized.startsWith('blueprints/') || normalized.startsWith('webpresso/blueprints/')) {
+        return false;
+    }
     return SKIP_PATTERNS.some((pattern) => pattern.test(normalized));
 }
 export function getSkipReason(filePath) {

package/dist/esm/hooks/stop/qa-changed-files.d.ts

@@ -11,4 +11,5 @@ export type StopHookResult = {
     systemMessage: string;
 };
 export declare function formatStopHookOutput(result: StopHookResult): string;
+export declare function main(): Promise<void>;
 //# sourceMappingURL=qa-changed-files.d.ts.map

package/dist/esm/hooks/stop/qa-changed-files.js

@@ -85,12 +85,15 @@ export function runQaChecks(qaFiles, projectDir) {
 export function formatStopHookOutput(result) {
     return JSON.stringify(result);
 }
-if (process.argv[1] &&
-    realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])) {
+export async function main() {
     runHook(
     // `Stop` is latency-sensitive and user-visible. Until webpresso grows a
     // deferred execution plane, broad typecheck/test sweeps stay off the hot
     // path instead of shelling synchronously at turn end.
     (_input) => null, formatStopHookOutput);
 }
+if (process.argv[1] &&
+    realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])) {
+    void main();
+}
 //# sourceMappingURL=qa-changed-files.js.map

package/dist/esm/lint/index.js

@@ -8,6 +8,7 @@
  */
 import { isRunFailure, runCommand } from '#mcp/tools/_shared/run-command';
 import { resolveProjectRoot } from '#mcp/tools/_shared/project-root';
+import { getManagedRunner } from '#tool-runtime';
 const DEFAULT_LINT_TIMEOUT_MS = 5 * 60 * 1_000;
 /**
  * Parse oxlint's `--format=json` output (ESLint-compatible array shape) into
@@ -92,7 +93,8 @@ export async function runLint(options = {}) {
     else {
         lintArgs.push('.');
     }
-    const vpOutcome = await runCommand('vp', lintArgs, runOptions);
+    const resolution = getManagedRunner('vp', { outputPolicy: 'structured' });
+    const vpOutcome = await runCommand(resolution.command, [...resolution.args, ...lintArgs], runOptions);
     if (isRunFailure(vpOutcome)) {
         return {
             passed: false,

package/dist/esm/mcp/auto-discover.d.ts

@@ -61,5 +61,7 @@ export interface ToolDescriptor {
 export interface ToolRegistrar {
     registerTool(name: string, description: string, jsonSchema: Record<string, unknown>, outputSchema: Record<string, unknown> | undefined, handler: ToolHandler, annotations?: ToolAnnotations): void;
 }
+export declare function registerToolDescriptor(server: ToolRegistrar, descriptor: ToolDescriptor): ToolDescriptor;
+export declare function registerToolDescriptors(server: ToolRegistrar, descriptors: readonly ToolDescriptor[]): ToolDescriptor[];
 export declare function discoverTools(server: ToolRegistrar, toolsDir: string): Promise<ToolDescriptor[]>;
 //# sourceMappingURL=auto-discover.d.ts.map

package/dist/esm/mcp/auto-discover.js

@@ -15,9 +15,20 @@ import { extname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
+export function registerToolDescriptor(server, descriptor) {
+    const jsonSchema = toJsonSchema(descriptor.inputSchema);
+    const outputSchema = descriptor.outputSchema ? toJsonSchema(descriptor.outputSchema) : undefined;
+    server.registerTool(descriptor.name, descriptor.description, jsonSchema, outputSchema, descriptor.handler, descriptor.annotations);
+    return descriptor;
+}
+export function registerToolDescriptors(server, descriptors) {
+    return descriptors.map((descriptor) => registerToolDescriptor(server, descriptor));
+}
 const SKIP_SUFFIXES = ['.test.ts', '.test.js', '.integration.test.ts', '.integration.test.js'];
 const SUPPORTED_EXTENSIONS = new Set(['.ts', '.js', '.mjs', '.cjs']);
 function shouldSkip(file) {
+    if (file.startsWith('_'))
+        return true;
     if (file.endsWith('.d.ts') || file.endsWith('.d.ts.map'))
         return true;
     if (file.endsWith('.js.map') || file.endsWith('.ts.map'))
@@ -82,7 +93,7 @@ function toJsonSchema(schema) {
 }
 export async function discoverTools(server, toolsDir) {
     const entries = await readdir(toolsDir, { withFileTypes: true });
-    const registered = [];
+    const loaded = [];
     for (const entry of entries) {
         if (!entry.isFile())
             continue;
@@ -98,11 +109,8 @@ export async function discoverTools(server, toolsDir) {
         if (typeof descriptor.name !== 'string' || typeof descriptor.handler !== 'function') {
             throw new Error(`Tool file ${fullPath} default export is malformed (missing name or handler)`);
         }
-        const jsonSchema = toJsonSchema(descriptor.inputSchema);
-        const outputSchema = descriptor.outputSchema ? toJsonSchema(descriptor.outputSchema) : undefined;
-        server.registerTool(descriptor.name, descriptor.description, jsonSchema, outputSchema, descriptor.handler, descriptor.annotations);
-        registered.push(descriptor);
+        loaded.push(descriptor);
     }
-    return registered;
+    return registerToolDescriptors(server, loaded);
 }
 //# sourceMappingURL=auto-discover.js.map