@webpresso/agent-kit 0.21.0

package/dist/esm/blueprint/test-utils/blueprint-mocks.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared test utilities for blueprint mocking
+ */
+import type { Blueprint, Task } from '#core/parser';
+export interface MockBlueprintOptions {
+    slug?: string;
+    name?: string;
+    type?: Blueprint['type'];
+    status?: string;
+    complexity?: string;
+    lastUpdated?: string;
+    tasks?: Task[];
+    phases?: Blueprint['phases'];
+    raw?: string;
+}
+export interface MockTaskOptions {
+    id?: string;
+    title?: string;
+    status?: Task['status'];
+    depends?: string[];
+    acceptanceCriteria?: Task['acceptanceCriteria'];
+}
+/**
+ * Create a mock Plan with sensible defaults
+ */
+export declare function createMockBlueprint(options?: MockBlueprintOptions): Blueprint;
+/**
+ * Create a mock Task with sensible defaults
+ */
+export declare function createMockTask(options?: MockTaskOptions): Task;
+//# sourceMappingURL=blueprint-mocks.d.ts.map

package/dist/esm/blueprint/test-utils/blueprint-mocks.js

@@ -0,0 +1,63 @@
+/**
+ * Shared test utilities for blueprint mocking
+ */
+/**
+ * Create a mock Plan with sensible defaults
+ */
+export function createMockBlueprint(options = {}) {
+    const defaultTask = createMockTask();
+    const tasks = options.tasks ?? [defaultTask];
+    const blueprintName = options.name ?? options.slug ?? 'test-plan';
+    return {
+        name: blueprintName,
+        type: options.type ?? 'blueprint',
+        title: options.name ?? options.slug ?? 'Test Plan',
+        status: options.status ?? 'in-progress',
+        complexity: options.complexity ?? 'S',
+        lastUpdated: options.lastUpdated ?? '2026-01-01',
+        tasks,
+        phases: options.phases ?? [],
+        raw: options.raw ?? createDefaultRawMarkdown(blueprintName, tasks),
+    };
+}
+/**
+ * Create a mock Task with sensible defaults
+ */
+export function createMockTask(options = {}) {
+    return {
+        id: options.id ?? '1.1',
+        title: options.title ?? 'Test Task',
+        status: options.status ?? 'todo',
+        depends: options.depends,
+        stepType: 'implement',
+        acceptanceCriteria: options.acceptanceCriteria ?? {
+            total: 2,
+            checked: 0,
+        },
+    };
+}
+/**
+ * Helper: Generate default raw markdown for a plan
+ */
+function createDefaultRawMarkdown(name, tasks) {
+    const taskSections = tasks
+        .map((task) => `#### Task ${task.id}: ${task.title}\n\n` +
+        `- [${task.acceptanceCriteria.checked > 0 ? 'x' : ' '}] First criterion\n` +
+        `- [${task.acceptanceCriteria.checked > 1 ? 'x' : ' '}] Second criterion\n`)
+        .join('\n');
+    return `---
+ type: blueprint
+ status: in-progress
+ complexity: S
+ last_updated: 2026-01-01
+ created: 2026-01-01
+ ---
+ 
+ # ${name}
+ 
+ ## Phase 1: Foundation [Complexity: S]
+ 
+ ${taskSections}
+ `;
+}
+//# sourceMappingURL=blueprint-mocks.js.map

package/dist/esm/blueprint/tracked-document/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tracked Document Domain Logic
+ *
+ * Base schemas, types, and utilities for tracked documents (Blueprints, TechDebt).
+ * Tracked documents are markdown files with YAML frontmatter that track status over time.
+ *
+ * This provides the foundation layer that specific document types (Blueprint, TechDebt)
+ * extend with their own fields and behavior.
+ */
+export * from './schema.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/blueprint/tracked-document/index.js

@@ -0,0 +1,11 @@
+/**
+ * Tracked Document Domain Logic
+ *
+ * Base schemas, types, and utilities for tracked documents (Blueprints, TechDebt).
+ * Tracked documents are markdown files with YAML frontmatter that track status over time.
+ *
+ * This provides the foundation layer that specific document types (Blueprint, TechDebt)
+ * extend with their own fields and behavior.
+ */
+export * from './schema.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/blueprint/tracked-document/parser.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Tracked Document Parser Utilities
+ *
+ * Pure functions for parsing markdown documents with checkbox-based task tracking.
+ * Shared across Blueprint and TechDebt parsers.
+ *
+ * Git-Native SSoT: Checkbox state derives status, no external state.
+ */
+import type { BlueprintTaskStatus } from '#core/schema';
+/**
+ * Checkbox status with derived task state
+ */
+export interface CheckboxStatus {
+    total: number;
+    checked: number;
+    status: BlueprintTaskStatus;
+}
+/**
+ * Acceptance criteria tracking
+ */
+export interface AcceptanceCriteria {
+    total: number;
+    checked: number;
+}
+/**
+ * Extract checkbox status from a markdown section and derive task state.
+ *
+ * Status derivation rules (Git-Native SSoT):
+ * - 0 checkboxes = pending (no acceptance criteria defined yet)
+ * - all checked = completed
+ * - some checked = running
+ * - none checked = pending
+ *
+ * @param section - Markdown section containing checkboxes
+ * @returns Checkbox counts and derived status
+ *
+ * @example
+ * ```typescript
+ * const section = `
+ * #### Task 1.1: Setup
+ * - [x] Install dependencies
+ * - [ ] Configure environment
+ * `
+ * const { total, checked, status } = extractCheckboxStatus(section)
+ * // { total: 2, checked: 1, status: 'running' }
+ * ```
+ */
+export declare function extractCheckboxStatus(section: string): CheckboxStatus;
+/**
+ * Extract acceptance criteria (checkbox counts only, without status)
+ *
+ * @param section - Markdown section containing checkboxes
+ * @returns Checkbox counts
+ */
+export declare function extractAcceptanceCriteria(section: string): AcceptanceCriteria;
+/**
+ * Extract dependency task IDs from a "Depends:" metadata line
+ *
+ * Supports multiple formats:
+ * - "Task 1.1, Task 1.2" (explicit prefix each)
+ * - "Tasks 1.1, 1.2, 1.3" (plural prefix, bare IDs after)
+ * - "1.1, 1.2" (bare IDs)
+ * - "None" (returns empty array)
+ *
+ * @param section - Markdown section containing metadata
+ * @returns Array of task IDs (e.g., ["1.1", "1.2"])
+ *
+ * @example
+ * ```typescript
+ * const section = "**Depends:** Tasks 1.1, 1.2"
+ * extractDepends(section) // ["1.1", "1.2"]
+ * ```
+ */
+export declare function extractDepends(section: string): string[];
+/**
+ * Extract blocked reason from a "Blocked:" metadata line
+ *
+ * @param section - Markdown section containing metadata
+ * @returns Blocked reason text, or undefined if not blocked
+ *
+ * @example
+ * ```typescript
+ * const section = "**Blocked:** Waiting for API approval"
+ * extractBlocked(section) // "Waiting for API approval"
+ * ```
+ */
+export declare function extractBlocked(section: string): string | undefined;
+/**
+ * Find the end index of a task section.
+ *
+ * Task section ends at the next task header OR at a major section delimiter (## or ---).
+ * This prevents including checkboxes from other sections like Success Criteria.
+ *
+ * @param content - Full markdown content
+ * @param taskStart - Start index of current task
+ * @param nextTaskIndex - Start index of next task (or content.length)
+ * @returns End index of task section
+ */
+export declare function findTaskSectionEnd(content: string, taskStart: number, nextTaskIndex: number): number;
+/**
+ * Extract plain text description from a task section.
+ *
+ * Excludes:
+ * - Task header line
+ * - Metadata lines (Depends, Blocked, Status)
+ * - Checklist items
+ * - Leading empty lines
+ *
+ * @param section - Task section content
+ * @returns Description text, or undefined if no description
+ */
+export declare function extractTaskDescription(section: string): string | undefined;
+//# sourceMappingURL=parser.d.ts.map

package/dist/esm/blueprint/tracked-document/parser.js

@@ -0,0 +1,197 @@
+/**
+ * Tracked Document Parser Utilities
+ *
+ * Pure functions for parsing markdown documents with checkbox-based task tracking.
+ * Shared across Blueprint and TechDebt parsers.
+ *
+ * Git-Native SSoT: Checkbox state derives status, no external state.
+ */
+import { isTaskHeaderLine } from '#markdown/task-heading';
+/**
+ * Extract checkbox status from a markdown section and derive task state.
+ *
+ * Status derivation rules (Git-Native SSoT):
+ * - 0 checkboxes = pending (no acceptance criteria defined yet)
+ * - all checked = completed
+ * - some checked = running
+ * - none checked = pending
+ *
+ * @param section - Markdown section containing checkboxes
+ * @returns Checkbox counts and derived status
+ *
+ * @example
+ * ```typescript
+ * const section = `
+ * #### Task 1.1: Setup
+ * - [x] Install dependencies
+ * - [ ] Configure environment
+ * `
+ * const { total, checked, status } = extractCheckboxStatus(section)
+ * // { total: 2, checked: 1, status: 'running' }
+ * ```
+ */
+export function extractCheckboxStatus(section) {
+    const checkboxRegex = /^- \[([ x])\]/gm;
+    const matches = Array.from(section.matchAll(checkboxRegex));
+    const total = matches.length;
+    const checked = matches.filter((m) => m[1] === 'x').length;
+    // Derive status from checkbox state (Git-Native SSoT)
+    let status = 'todo';
+    if (total > 0) {
+        if (checked === total) {
+            status = 'done';
+        }
+        else if (checked > 0) {
+            status = 'in_progress';
+        }
+    }
+    return { total, checked, status };
+}
+/**
+ * Extract acceptance criteria (checkbox counts only, without status)
+ *
+ * @param section - Markdown section containing checkboxes
+ * @returns Checkbox counts
+ */
+export function extractAcceptanceCriteria(section) {
+    const { total, checked } = extractCheckboxStatus(section);
+    return { total, checked };
+}
+/**
+ * Extract dependency task IDs from a "Depends:" metadata line
+ *
+ * Supports multiple formats:
+ * - "Task 1.1, Task 1.2" (explicit prefix each)
+ * - "Tasks 1.1, 1.2, 1.3" (plural prefix, bare IDs after)
+ * - "1.1, 1.2" (bare IDs)
+ * - "None" (returns empty array)
+ *
+ * @param section - Markdown section containing metadata
+ * @returns Array of task IDs (e.g., ["1.1", "1.2"])
+ *
+ * @example
+ * ```typescript
+ * const section = "**Depends:** Tasks 1.1, 1.2"
+ * extractDepends(section) // ["1.1", "1.2"]
+ * ```
+ */
+export function extractDepends(section) {
+    const dependsMatch = section.match(/\*\*Depends:\*\*\s*(.+)/i);
+    if (!dependsMatch?.[1])
+        return [];
+    const dependsText = dependsMatch[1].trim();
+    if (dependsText.toLowerCase() === 'none')
+        return [];
+    // Extract task IDs from various formats
+    const taskIdRegex = /(?:Tasks?\s+)?(\d+(?:\.\d+)+)/gi;
+    const ids = Array.from(dependsText.matchAll(taskIdRegex), (m) => m[1] ?? '');
+    return ids.filter((id) => id !== '');
+}
+/**
+ * Extract blocked reason from a "Blocked:" metadata line
+ *
+ * @param section - Markdown section containing metadata
+ * @returns Blocked reason text, or undefined if not blocked
+ *
+ * @example
+ * ```typescript
+ * const section = "**Blocked:** Waiting for API approval"
+ * extractBlocked(section) // "Waiting for API approval"
+ * ```
+ */
+export function extractBlocked(section) {
+    const blockedMatch = section.match(/\*\*Blocked:\*\*\s*(.+)/i);
+    if (!blockedMatch?.[1])
+        return undefined;
+    const blockedText = blockedMatch[1].trim();
+    // Handle missing/empty reason gracefully
+    if (blockedText === '' || blockedText.toLowerCase() === 'none') {
+        return undefined;
+    }
+    return blockedText;
+}
+/**
+ * Find the end index of a task section.
+ *
+ * Task section ends at the next task header OR at a major section delimiter (## or ---).
+ * This prevents including checkboxes from other sections like Success Criteria.
+ *
+ * @param content - Full markdown content
+ * @param taskStart - Start index of current task
+ * @param nextTaskIndex - Start index of next task (or content.length)
+ * @returns End index of task section
+ */
+export function findTaskSectionEnd(content, taskStart, nextTaskIndex) {
+    const contentAfterTask = content.slice(taskStart);
+    const sectionDelimiterMatch = contentAfterTask.match(/\n(?:##\s|---\n)/);
+    const sectionDelimiterIndex = sectionDelimiterMatch
+        ? taskStart + (sectionDelimiterMatch.index ?? content.length) + 1
+        : content.length;
+    return Math.min(nextTaskIndex, sectionDelimiterIndex);
+}
+/**
+ * Extract plain text description from a task section.
+ *
+ * Excludes:
+ * - Task header line
+ * - Metadata lines (Depends, Blocked, Status)
+ * - Checklist items
+ * - Leading empty lines
+ *
+ * @param section - Task section content
+ * @returns Description text, or undefined if no description
+ */
+export function extractTaskDescription(section) {
+    const lines = section.split('\n');
+    const descriptionLines = [];
+    let inDescription = false;
+    for (const line of lines) {
+        // Skip task header
+        if (isTaskHeader(line)) {
+            inDescription = true;
+            continue;
+        }
+        // Skip lines until we're in description
+        if (shouldSkipLine(line, inDescription, descriptionLines.length)) {
+            continue;
+        }
+        descriptionLines.push(line);
+    }
+    const description = descriptionLines.join('\n').trim();
+    return description.length > 0 ? description : undefined;
+}
+/**
+ * Check if line is a task header using the shared strict blueprint grammar.
+ */
+function isTaskHeader(line) {
+    return isTaskHeaderLine(line);
+}
+/**
+ * Check if line is a metadata field (Depends, Blocked, Status)
+ */
+function isMetadataLine(line) {
+    return /^\*\*(Depends|Blocked|Status):\*\*/i.test(line);
+}
+/**
+ * Check if line is a checklist item
+ */
+function isChecklistItem(line) {
+    return /^-\s*\[([ x])\]/.test(line);
+}
+/**
+ * Determine if a line should be skipped during description extraction
+ */
+function shouldSkipLine(line, inDescription, collectedCount) {
+    if (isTaskHeader(line))
+        return true;
+    if (isMetadataLine(line))
+        return true;
+    if (isChecklistItem(line))
+        return true;
+    if (!inDescription)
+        return true;
+    if (line.trim() === '' && collectedCount === 0)
+        return true;
+    return false;
+}
+//# sourceMappingURL=parser.js.map

package/dist/esm/blueprint/tracked-document/query-types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Generic Query Types for Tracked Documents
+ *
+ * These types provide generic filter/sort base types that can be used
+ * across different tracked document implementations (blueprints, etc).
+ */
+/**
+ * Freshness score for a tracked document.
+ * Indicates how recently the document has been updated relative to its status.
+ */
+export interface FreshnessScore {
+    /** Numeric score from 0.0 (critical) to 1.0 (fresh) */
+    score: number;
+    /** Number of days since the last update */
+    daysSinceUpdate: number;
+    /** Categorical freshness status */
+    status: 'fresh' | 'aging' | 'stale' | 'critical';
+}
+/**
+ * Sort direction for query results.
+ */
+export type SortDirection = 'asc' | 'desc';
+/**
+ * Base sort options structure.
+ * Specific implementations should extend this with their own sort fields.
+ */
+export interface BaseSortOptions<TField extends string> {
+    /** Field to sort by */
+    field: TField;
+    /** Sort direction (ascending or descending) */
+    direction: SortDirection;
+}
+/**
+ * Base query filters structure.
+ * Specific implementations should extend this with their own filter fields.
+ */
+export interface BaseQueryFilters {
+    /** Filter for stale documents only */
+    stale?: boolean;
+    /** Custom staleness threshold in days (overrides default) */
+    staleDays?: number;
+}
+//# sourceMappingURL=query-types.d.ts.map

package/dist/esm/blueprint/tracked-document/query-types.js

@@ -0,0 +1,8 @@
+/**
+ * Generic Query Types for Tracked Documents
+ *
+ * These types provide generic filter/sort base types that can be used
+ * across different tracked document implementations (blueprints, etc).
+ */
+export {};
+//# sourceMappingURL=query-types.js.map

package/dist/esm/blueprint/tracked-document/schema.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Base Zod schema for tracked documents (Blueprints, TechDebt, etc.)
+ *
+ * This schema defines shared structure and validation rules for all tracked document types.
+ * Tracked documents are markdown files with YAML frontmatter that track status over time.
+ *
+ * Using Zod provides:
+ * - Type-safe validation with automatic TypeScript inference
+ * - Detailed error messages for invalid frontmatter
+ * - Declarative schema definition
+ * - Foundation for discriminated unions when multiple document types exist
+ */
+import { z } from 'zod';
+/**
+ * Valid tracked document status values (aligned with blueprint lifecycle).
+ */
+export declare const trackedDocumentStatusSchema: z.ZodEnum<{
+    completed: "completed";
+    draft: "draft";
+    planned: "planned";
+    "in-progress": "in-progress";
+    parked: "parked";
+    archived: "archived";
+}>;
+export type TrackedDocumentStatus = z.infer<typeof trackedDocumentStatusSchema>;
+/**
+ * Blueprint slug - kebab-case identifier for a blueprint
+ * Used to prevent accidental mixing of different document slug types
+ * @example "implement-auth-flow"
+ */
+export declare const BlueprintSlug: z.core.$ZodBranded<z.ZodString, "BlueprintSlug", "out">;
+export type BlueprintSlug = z.infer<typeof BlueprintSlug>;
+/**
+ * TechDebt slug - kebab-case identifier for a tech debt item
+ * Used to prevent accidental mixing of different document slug types
+ * @example "refactor-payment-service"
+ */
+export declare const TechDebtSlug: z.core.$ZodBranded<z.ZodString, "TechDebtSlug", "out">;
+export type TechDebtSlug = z.infer<typeof TechDebtSlug>;
+/**
+ * Shared frontmatter fields for all tracked documents
+ *
+ * Required fields:
+ * - type: Document type discriminator (e.g., 'blueprint', 'tech-debt')
+ * - status: Current document status
+ *
+ * Optional fields:
+ * - last_updated: Date document was last modified (YYYY-MM-DD)
+ * - created: Date document was created (YYYY-MM-DD)
+ */
+export declare const trackedDocumentFrontmatterSchema: z.ZodObject<{
+    type: z.ZodString;
+    status: z.ZodEnum<{
+        completed: "completed";
+        draft: "draft";
+        planned: "planned";
+        "in-progress": "in-progress";
+        parked: "parked";
+        archived: "archived";
+    }>;
+    last_updated: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodDate]>>;
+    created: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodDate]>>;
+}, z.core.$strip>;
+export type TrackedDocumentFrontmatter = z.infer<typeof trackedDocumentFrontmatterSchema>;
+/**
+ * Discriminated union of all tracked document types
+ *
+ * Currently only includes Blueprint type. When TechDebt schema is added,
+ * this will become a true discriminated union:
+ *
+ * @example
+ * export const trackedDocumentSchema = z.discriminatedUnion('type', [
+ *   blueprintFrontmatterSchema,
+ *   techDebtFrontmatterSchema,
+ * ])
+ *
+ * This allows type-safe parsing where the 'type' field determines
+ * which schema variant is used for validation.
+ */
+//# sourceMappingURL=schema.d.ts.map

package/dist/esm/blueprint/tracked-document/schema.js

@@ -0,0 +1,89 @@
+/**
+ * Base Zod schema for tracked documents (Blueprints, TechDebt, etc.)
+ *
+ * This schema defines shared structure and validation rules for all tracked document types.
+ * Tracked documents are markdown files with YAML frontmatter that track status over time.
+ *
+ * Using Zod provides:
+ * - Type-safe validation with automatic TypeScript inference
+ * - Detailed error messages for invalid frontmatter
+ * - Declarative schema definition
+ * - Foundation for discriminated unions when multiple document types exist
+ */
+import { z } from 'zod';
+// =============================================================================
+// Shared Status Enum
+// =============================================================================
+/**
+ * Valid tracked document status values (aligned with blueprint lifecycle).
+ */
+export const trackedDocumentStatusSchema = z.enum([
+    'draft',
+    'planned',
+    'parked',
+    'in-progress',
+    'completed',
+    'archived',
+]);
+// =============================================================================
+// Branded Slug Types (Nominal Typing)
+// =============================================================================
+/**
+ * Blueprint slug - kebab-case identifier for a blueprint
+ * Used to prevent accidental mixing of different document slug types
+ * @example "implement-auth-flow"
+ */
+export const BlueprintSlug = z
+    .string()
+    .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, 'Must be kebab-case')
+    .brand();
+/**
+ * TechDebt slug - kebab-case identifier for a tech debt item
+ * Used to prevent accidental mixing of different document slug types
+ * @example "refactor-payment-service"
+ */
+export const TechDebtSlug = z
+    .string()
+    .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, 'Must be kebab-case')
+    .brand();
+// =============================================================================
+// Base Frontmatter Schema
+// =============================================================================
+/**
+ * Shared frontmatter fields for all tracked documents
+ *
+ * Required fields:
+ * - type: Document type discriminator (e.g., 'blueprint', 'tech-debt')
+ * - status: Current document status
+ *
+ * Optional fields:
+ * - last_updated: Date document was last modified (YYYY-MM-DD)
+ * - created: Date document was created (YYYY-MM-DD)
+ */
+export const trackedDocumentFrontmatterSchema = z.object({
+    type: z.string(), // Will be discriminated by specific document types
+    status: trackedDocumentStatusSchema,
+    last_updated: z.union([z.string(), z.date()]).optional(),
+    created: z.union([z.string(), z.date()]).optional(),
+});
+// =============================================================================
+// Discriminated Union Foundation
+// =============================================================================
+/**
+ * Discriminated union of all tracked document types
+ *
+ * Currently only includes Blueprint type. When TechDebt schema is added,
+ * this will become a true discriminated union:
+ *
+ * @example
+ * export const trackedDocumentSchema = z.discriminatedUnion('type', [
+ *   blueprintFrontmatterSchema,
+ *   techDebtFrontmatterSchema,
+ * ])
+ *
+ * This allows type-safe parsing where the 'type' field determines
+ * which schema variant is used for validation.
+ */
+// Note: The discriminated union will be completed when TechDebt schema exists.
+// For now, this file provides the foundation and shared types.
+//# sourceMappingURL=schema.js.map

package/dist/esm/blueprint/types/execution-backend.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+/**
+ * Canonical execution backend schema for Blueprint-backed execution.
+ *
+ * Single source of truth — re-exported by:
+ *   - src/blueprint/execution/types.ts
+ *   - src/blueprint/core/schema.ts
+ */
+export declare const executionBackendSchema: z.ZodEnum<{
+    "omx-team": "omx-team";
+    "omx-pll-interactive": "omx-pll-interactive";
+    "claude-subagent": "claude-subagent";
+    "codex-exec": "codex-exec";
+    "local-worktree": "local-worktree";
+}>;
+export type BlueprintExecutionBackend = z.infer<typeof executionBackendSchema>;
+//# sourceMappingURL=execution-backend.d.ts.map

package/dist/esm/blueprint/types/execution-backend.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+/**
+ * Canonical execution backend schema for Blueprint-backed execution.
+ *
+ * Single source of truth — re-exported by:
+ *   - src/blueprint/execution/types.ts
+ *   - src/blueprint/core/schema.ts
+ */
+export const executionBackendSchema = z.enum([
+    'omx-team',
+    'omx-pll-interactive',
+    'claude-subagent',
+    'codex-exec',
+    'local-worktree',
+]);
+//# sourceMappingURL=execution-backend.js.map