@webpresso/agent-kit 0.21.0

package/dist/esm/config/workers-test/execution-context.js

@@ -0,0 +1,22 @@
+import { vi } from 'vitest';
+// ============================================================================
+// Mock Factories
+// ============================================================================
+/**
+ * Creates a mock ExecutionContext for worker tests.
+ *
+ * @example
+ * ```typescript
+ * const ctx = createMockExecutionContext()
+ * const response = await app.fetch(request, env, ctx)
+ * expect(ctx.waitUntil).not.toHaveBeenCalled()
+ * ```
+ */
+export function createMockExecutionContext() {
+    return {
+        waitUntil: vi.fn(),
+        passThroughOnException: vi.fn(),
+        props: {},
+    };
+}
+//# sourceMappingURL=execution-context.js.map

package/dist/esm/config/workers-test/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @webpresso/agent-kit/workers-test
+ *
+ * Production-ready Cloudflare Workers test mocks.
+ * Drop in BaseWorkerEnv, ExecutionContext, Hyperdrive, and Durable Object mocks
+ * for any Cloudflare Workers project without recreating them per-app.
+ */
+export type { BaseWorkerEnv } from './env.js';
+export { createMockEnv, createMockHyperdrive, createMockDurableObjectNamespace } from './env.js';
+export type { MockExecutionContext } from './execution-context.js';
+export { createMockExecutionContext } from './execution-context.js';
+export { MockDurableObject, MockContainer, createCloudflareRuntimeMocks, } from './durable-objects.js';
+export { createAuthenticatedRequest, createUnauthenticatedRequest, createCorsRequest, } from './requests.js';
+export type { WorkerTestOptions } from './setup.js';
+export { setupWorkerTest, suppressConsole } from './setup.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/config/workers-test/index.js

@@ -0,0 +1,15 @@
+/**
+ * @webpresso/agent-kit/workers-test
+ *
+ * Production-ready Cloudflare Workers test mocks.
+ * Drop in BaseWorkerEnv, ExecutionContext, Hyperdrive, and Durable Object mocks
+ * for any Cloudflare Workers project without recreating them per-app.
+ */
+export { createMockEnv, createMockHyperdrive, createMockDurableObjectNamespace } from './env.js';
+export { createMockExecutionContext } from './execution-context.js';
+// Durable Objects and Containers
+export { MockDurableObject, MockContainer, createCloudflareRuntimeMocks, } from './durable-objects.js';
+// Request helpers
+export { createAuthenticatedRequest, createUnauthenticatedRequest, createCorsRequest, } from './requests.js';
+export { setupWorkerTest, suppressConsole } from './setup.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/config/workers-test/requests.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Creates an authenticated request with session cookie.
+ *
+ * @param path - Request path (e.g., '/graphql')
+ * @param options - Additional request options (method, headers, body)
+ * @param baseUrl - Base URL for the request (default: https://api.test)
+ * @returns Request object with authentication headers
+ *
+ * @example
+ * ```typescript
+ * const request = createAuthenticatedRequest('/api/users', { method: 'POST', body: JSON.stringify(data) })
+ * ```
+ */
+export declare function createAuthenticatedRequest(path: string, options?: RequestInit, baseUrl?: string): Request;
+/**
+ * Creates an unauthenticated request (no session cookie).
+ *
+ * @param path - Request path (e.g., '/health')
+ * @param options - Additional request options
+ * @param baseUrl - Base URL for the request (default: https://api.test)
+ * @returns Request object without authentication
+ *
+ * @example
+ * ```typescript
+ * const request = createUnauthenticatedRequest('/health')
+ * ```
+ */
+export declare function createUnauthenticatedRequest(path: string, options?: RequestInit, baseUrl?: string): Request;
+/**
+ * Creates a request with custom origin for CORS testing.
+ *
+ * @param path - Request path
+ * @param origin - Origin header value
+ * @param options - Additional request options
+ * @param baseUrl - Base URL for the request (default: https://api.test)
+ * @returns Request object with Origin header
+ *
+ * @example
+ * ```typescript
+ * const request = createCorsRequest('/api/data', 'https://example.com')
+ * ```
+ */
+export declare function createCorsRequest(path: string, origin: string, options?: RequestInit, baseUrl?: string): Request;
+//# sourceMappingURL=requests.d.ts.map

package/dist/esm/config/workers-test/requests.js

@@ -0,0 +1,71 @@
+// ============================================================================
+// Request Helpers
+// ============================================================================
+/**
+ * Creates an authenticated request with session cookie.
+ *
+ * @param path - Request path (e.g., '/graphql')
+ * @param options - Additional request options (method, headers, body)
+ * @param baseUrl - Base URL for the request (default: https://api.test)
+ * @returns Request object with authentication headers
+ *
+ * @example
+ * ```typescript
+ * const request = createAuthenticatedRequest('/api/users', { method: 'POST', body: JSON.stringify(data) })
+ * ```
+ */
+export function createAuthenticatedRequest(path, options = {}, baseUrl = 'https://api.test') {
+    const { headers: optionHeaders, ...restOptions } = options;
+    return new Request(`${baseUrl}${path}`, {
+        ...restOptions,
+        headers: {
+            Cookie: 'session=mock-session-token',
+            ...optionHeaders,
+        },
+    });
+}
+/**
+ * Creates an unauthenticated request (no session cookie).
+ *
+ * @param path - Request path (e.g., '/health')
+ * @param options - Additional request options
+ * @param baseUrl - Base URL for the request (default: https://api.test)
+ * @returns Request object without authentication
+ *
+ * @example
+ * ```typescript
+ * const request = createUnauthenticatedRequest('/health')
+ * ```
+ */
+export function createUnauthenticatedRequest(path, options = {}, baseUrl = 'https://api.test') {
+    return new Request(`${baseUrl}${path}`, {
+        headers: {
+            ...options.headers,
+        },
+        ...options,
+    });
+}
+/**
+ * Creates a request with custom origin for CORS testing.
+ *
+ * @param path - Request path
+ * @param origin - Origin header value
+ * @param options - Additional request options
+ * @param baseUrl - Base URL for the request (default: https://api.test)
+ * @returns Request object with Origin header
+ *
+ * @example
+ * ```typescript
+ * const request = createCorsRequest('/api/data', 'https://example.com')
+ * ```
+ */
+export function createCorsRequest(path, origin, options = {}, baseUrl = 'https://api.test') {
+    return new Request(`${baseUrl}${path}`, {
+        headers: {
+            Origin: origin,
+            ...options.headers,
+        },
+        ...options,
+    });
+}
+//# sourceMappingURL=requests.js.map

package/dist/esm/config/workers-test/setup.d.ts

@@ -0,0 +1,63 @@
+import type { BaseWorkerEnv } from './env.js';
+import type { MockExecutionContext } from './execution-context.js';
+import { createMockExecutionContext } from './execution-context.js';
+import { createCloudflareRuntimeMocks } from './durable-objects.js';
+import { createAuthenticatedRequest, createUnauthenticatedRequest, createCorsRequest } from './requests.js';
+/**
+ * Options for configuring the worker test environment
+ */
+export interface WorkerTestOptions {
+    /** Enable Cloudflare Workers runtime mocking (DurableObject, Container) (default: true) */
+    mockCloudflareRuntime?: boolean;
+}
+/**
+ * Sets up common worker test environment with mocks.
+ * Call this in beforeEach() or at the top of your test file with vi.mock().
+ *
+ * @param envOverrides - Partial environment overrides
+ * @param options - Configuration for which mocks to enable
+ * @returns Object with mock instances for use in tests
+ *
+ * @example
+ * ```typescript
+ * const { mockEnv, mockCtx } = setupWorkerTest()
+ *
+ * beforeEach(() => {
+ *   vi.clearAllMocks()
+ * })
+ *
+ * it('should handle request', async () => {
+ *   const request = createAuthenticatedRequest('/api/test')
+ *   const response = await app.fetch(request, mockEnv, mockCtx)
+ *   expect(response.status).toBe(200)
+ * })
+ * ```
+ */
+export declare function setupWorkerTest<T extends BaseWorkerEnv>(envOverrides?: Partial<T>, options?: WorkerTestOptions): {
+    mocks: {
+        cloudflareRuntime: ReturnType<typeof createCloudflareRuntimeMocks> | null;
+    };
+    mockEnv: T;
+    mockCtx: MockExecutionContext;
+    createAuthenticatedRequest: typeof createAuthenticatedRequest;
+    createUnauthenticatedRequest: typeof createUnauthenticatedRequest;
+    createCorsRequest: typeof createCorsRequest;
+    createMockExecutionContext: typeof createMockExecutionContext;
+    clearAllMocks: () => void;
+};
+/**
+ * Suppress console output during tests.
+ * Call restore() in afterEach to restore console methods.
+ *
+ * @returns Object with restore function to restore console methods
+ *
+ * @example
+ * ```typescript
+ * const consoleControl = suppressConsole()
+ * afterEach(() => consoleControl.restore())
+ * ```
+ */
+export declare function suppressConsole(): {
+    restore: () => void;
+};
+//# sourceMappingURL=setup.d.ts.map

package/dist/esm/config/workers-test/setup.js

@@ -0,0 +1,86 @@
+import { vi } from 'vitest';
+import { createMockEnv } from './env.js';
+import { createMockExecutionContext } from './execution-context.js';
+import { createCloudflareRuntimeMocks } from './durable-objects.js';
+import { createAuthenticatedRequest, createUnauthenticatedRequest, createCorsRequest, } from './requests.js';
+// ============================================================================
+// Test Setup Function
+// ============================================================================
+/**
+ * Sets up common worker test environment with mocks.
+ * Call this in beforeEach() or at the top of your test file with vi.mock().
+ *
+ * @param envOverrides - Partial environment overrides
+ * @param options - Configuration for which mocks to enable
+ * @returns Object with mock instances for use in tests
+ *
+ * @example
+ * ```typescript
+ * const { mockEnv, mockCtx } = setupWorkerTest()
+ *
+ * beforeEach(() => {
+ *   vi.clearAllMocks()
+ * })
+ *
+ * it('should handle request', async () => {
+ *   const request = createAuthenticatedRequest('/api/test')
+ *   const response = await app.fetch(request, mockEnv, mockCtx)
+ *   expect(response.status).toBe(200)
+ * })
+ * ```
+ */
+export function setupWorkerTest(envOverrides = {}, options = {}) {
+    const { mockCloudflareRuntime = true } = options;
+    const mocks = {
+        cloudflareRuntime: mockCloudflareRuntime ? createCloudflareRuntimeMocks() : null,
+    };
+    const mockEnv = createMockEnv(envOverrides);
+    const mockCtx = createMockExecutionContext();
+    return {
+        mocks,
+        mockEnv,
+        mockCtx,
+        createAuthenticatedRequest,
+        createUnauthenticatedRequest,
+        createCorsRequest,
+        createMockExecutionContext,
+        clearAllMocks: () => vi.clearAllMocks(),
+    };
+}
+// ============================================================================
+// Console Mocking Helpers
+// ============================================================================
+/**
+ * Suppress console output during tests.
+ * Call restore() in afterEach to restore console methods.
+ *
+ * @returns Object with restore function to restore console methods
+ *
+ * @example
+ * ```typescript
+ * const consoleControl = suppressConsole()
+ * afterEach(() => consoleControl.restore())
+ * ```
+ */
+export function suppressConsole() {
+    const originalLog = console.log;
+    const originalError = console.error;
+    const originalWarn = console.warn;
+    vi.spyOn(console, 'log').mockImplementation(() => {
+        // Intentionally empty - suppressing console output
+    });
+    vi.spyOn(console, 'error').mockImplementation(() => {
+        // Intentionally empty - suppressing console output
+    });
+    vi.spyOn(console, 'warn').mockImplementation(() => {
+        // Intentionally empty - suppressing console output
+    });
+    return {
+        restore: () => {
+            console.log = originalLog;
+            console.error = originalError;
+            console.warn = originalWarn;
+        },
+    };
+}
+//# sourceMappingURL=setup.js.map

package/dist/esm/content/audit.d.ts

@@ -0,0 +1,20 @@
+import { type ContentKind } from './loader.js';
+export interface AuditFinding {
+    readonly severity: 'error' | 'warning';
+    readonly kind: ContentKind;
+    readonly slug: string;
+    readonly filePath: string;
+    readonly message: string;
+}
+export interface AuditResult {
+    readonly findings: readonly AuditFinding[];
+    readonly passed: boolean;
+}
+export interface AuditOptions {
+    readonly catalogDir: string;
+    readonly consumerRoot?: string;
+    readonly kind: ContentKind;
+    readonly staleReviewDays?: number;
+}
+export declare function auditContent(options: AuditOptions): AuditResult;
+//# sourceMappingURL=audit.d.ts.map

package/dist/esm/content/audit.js

@@ -0,0 +1,164 @@
+/**
+ * Shared audit runner for consumer-rule + consumer-skill content.
+ *
+ * Single entry point parameterized by `kind`. Performs:
+ *   1. Frontmatter schema validation (rule or skill schema by kind).
+ *   2. Filename / dir name vs. frontmatter slug consistency.
+ *   3. Duplicate slug detection within consumer-source records.
+ *   4. Catalog ↔ consumer slug collisions (hard fail per locked decision #3).
+ *   5. `related` ref resolution against the union of canonical + consumer
+ *      slugs across both kinds.
+ *   6. `last_reviewed` staleness (>= staleReviewDays) → warning.
+ *
+ * Wave 0 left `record.parsedFrontmatter` as `unknown`; this audit is the first
+ * caller to wire the schemas to the loader output.
+ */
+import { basename, dirname } from 'node:path';
+import { z } from 'zod';
+import { loadContent } from './loader.js';
+import { ruleFrontmatterSchema, skillFrontmatterSchema, } from './schema.js';
+const DEFAULT_STALE_DAYS = 180;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+function schemaFor(kind) {
+    return (kind === 'rule' ? ruleFrontmatterSchema : skillFrontmatterSchema);
+}
+function diskSlug(record) {
+    if (record.kind === 'rule') {
+        return basename(record.filePath).replace(/\.md$/, '');
+    }
+    // skill: SKILL.md sits inside <slug>/ — use the parent dir name
+    return basename(dirname(record.filePath));
+}
+export function auditContent(options) {
+    const { catalogDir, consumerRoot, kind, staleReviewDays = DEFAULT_STALE_DAYS } = options;
+    // Always load both kinds so `related` cross-kind refs resolve. We filter
+    // findings to the requested kind below.
+    const { records, collisions } = loadContent({ catalogDir, consumerRoot });
+    const findings = [];
+    // Build the universe of known slugs across both kinds + sources for `related`.
+    const knownSlugs = new Set();
+    for (const r of records)
+        knownSlugs.add(r.slug);
+    const schema = schemaFor(kind);
+    const recordsOfKind = records.filter((r) => r.kind === kind);
+    // Schema-validation scope:
+    //  - rules: validate both catalog and consumer entries (same content schema
+    //    end-to-end; catalog promotions and consumer-authored rules share shape).
+    //  - skills: validate only consumer entries. Catalog skills follow the
+    //    upstream Anthropic SKILL format (`name`/`description`), not the
+    //    consumer-content schema. Forcing the consumer schema on catalog skills
+    //    would flood the audit with false positives that the catalog can never
+    //    satisfy without abandoning the upstream format.
+    const recordsToValidate = kind === 'skill' ? recordsOfKind.filter((r) => r.source === 'consumer') : recordsOfKind;
+    // Track parsed frontmatter for each record we successfully validate.
+    const parsedByRecord = new Map();
+    for (const record of recordsToValidate) {
+        const parseResult = schema.safeParse(record.rawFrontmatter);
+        if (!parseResult.success) {
+            for (const issue of parseResult.error.issues) {
+                const fieldPath = issue.path.length > 0 ? ` (${issue.path.join('.')})` : '';
+                findings.push({
+                    severity: 'error',
+                    kind: record.kind,
+                    slug: record.slug,
+                    filePath: record.filePath,
+                    message: `Schema validation failed${fieldPath}: ${issue.message}`,
+                });
+            }
+            continue;
+        }
+        parsedByRecord.set(record, parseResult.data);
+    }
+    // Check 2: filename / dir vs. frontmatter slug.
+    for (const [record, fm] of parsedByRecord) {
+        const onDisk = diskSlug(record);
+        if (fm.slug !== onDisk) {
+            const what = record.kind === 'rule' ? 'filename stem' : 'directory name';
+            findings.push({
+                severity: 'error',
+                kind: record.kind,
+                slug: record.slug,
+                filePath: record.filePath,
+                message: `Frontmatter slug "${fm.slug}" does not match ${what} "${onDisk}"`,
+            });
+        }
+    }
+    // Check 3: duplicate consumer-source slug within the audited kind. Dedup on
+    // the union of disk slug and parsed frontmatter slug — either flavor of
+    // collision is a problem.
+    const consumerByEffectiveSlug = new Map();
+    for (const record of recordsOfKind) {
+        if (record.source !== 'consumer')
+            continue;
+        const fm = parsedByRecord.get(record);
+        const effective = fm?.slug ?? record.slug;
+        const list = consumerByEffectiveSlug.get(effective) ?? [];
+        list.push(record);
+        consumerByEffectiveSlug.set(effective, list);
+    }
+    for (const [slug, dupes] of consumerByEffectiveSlug) {
+        if (dupes.length < 2)
+            continue;
+        for (const dup of dupes) {
+            findings.push({
+                severity: 'error',
+                kind,
+                slug,
+                filePath: dup.filePath,
+                message: `Duplicate consumer slug "${slug}" — also defined in ${dupes
+                    .filter((d) => d !== dup)
+                    .map((d) => d.filePath)
+                    .join(', ')}`,
+            });
+        }
+    }
+    // Check 4: catalog collisions (loader-supplied), filtered to this kind.
+    for (const collision of collisions) {
+        if (collision.kind !== kind)
+            continue;
+        findings.push({
+            severity: 'error',
+            kind: collision.kind,
+            slug: collision.slug,
+            filePath: collision.consumer,
+            message: `Catalog collision: consumer slug "${collision.slug}" shadows canonical at ` +
+                `${collision.canonical}. Rename the consumer entry.`,
+        });
+    }
+    // Check 5: broken `related` refs.
+    for (const [record, fm] of parsedByRecord) {
+        for (const ref of fm.related ?? []) {
+            if (knownSlugs.has(ref))
+                continue;
+            findings.push({
+                severity: 'error',
+                kind: record.kind,
+                slug: record.slug,
+                filePath: record.filePath,
+                message: `Broken \`related\` ref: "${ref}" does not resolve to any known rule or skill`,
+            });
+        }
+    }
+    // Check 6: stale last_reviewed (warning).
+    const todayStr = new Date().toISOString().slice(0, 10);
+    const todayMs = Date.parse(`${todayStr}T00:00:00Z`);
+    for (const [record, fm] of parsedByRecord) {
+        const reviewedMs = Date.parse(`${fm.last_reviewed}T00:00:00Z`);
+        if (Number.isNaN(reviewedMs))
+            continue;
+        const ageDays = (todayMs - reviewedMs) / MS_PER_DAY;
+        if (ageDays >= staleReviewDays) {
+            findings.push({
+                severity: 'warning',
+                kind: record.kind,
+                slug: record.slug,
+                filePath: record.filePath,
+                message: `last_reviewed ${fm.last_reviewed} is ${Math.floor(ageDays)} days old ` +
+                    `(threshold: ${staleReviewDays})`,
+            });
+        }
+    }
+    const passed = !findings.some((f) => f.severity === 'error');
+    return { findings, passed };
+}
+//# sourceMappingURL=audit.js.map

package/dist/esm/content/dispatch.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared CLI dispatch for `wp rule` and `wp skill` subcommands.
+ *
+ * Subcommands handled here are kind-agnostic — `new | list | show |
+ * deprecate`. Per-kind additions (e.g. `wp skill install`) are implemented
+ * in the thin command shims, not here.
+ */
+import { type ContentKind, type ContentSource } from './loader.js';
+export type ContentSubcommand = 'new' | 'list' | 'show' | 'deprecate';
+export interface DispatchOptions {
+    cwd: string;
+    catalogDir: string;
+    source?: ContentSource;
+    status?: 'active' | 'deprecated';
+    scope?: string;
+    title?: string;
+    reason?: string;
+    dryRun?: boolean;
+}
+export interface DispatchInput {
+    kind: ContentKind;
+    sub: ContentSubcommand;
+    args: readonly string[];
+    options: DispatchOptions;
+}
+export interface DispatchResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export declare function dispatchContent(input: DispatchInput): Promise<DispatchResult>;
+//# sourceMappingURL=dispatch.d.ts.map