@webpresso/agent-kit 0.21.0

package/dist/esm/blueprint/utils/archive.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Archive Operations
+ *
+ * Validates that all tasks in a plan are complete and updates status in place.
+ */
+import type { Blueprint } from '#core/parser';
+export interface IncompleteTask {
+    id: string;
+    title: string;
+    status: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    incompleteTasks?: IncompleteTask[];
+    message?: string;
+}
+/**
+ * Validates that all tasks in a plan are complete.
+ *
+ * A task is considered complete when:
+ * - status === 'done'
+ * - All acceptance criteria checkboxes are checked
+ *
+ * @param plan - The plan to validate
+ * @returns Validation result with details of incomplete tasks
+ *
+ * @example
+ * ```typescript
+ * const result = validateAllTasksDone(plan)
+ * if (!result.valid) {
+ *   console.error(result.message)
+ *   console.log('Incomplete tasks:', result.incompleteTasks)
+ * }
+ * ```
+ */
+export declare function validateAllTasksDone(plan: Blueprint): ValidationResult;
+/**
+ * Result of an archive operation.
+ */
+export interface ArchiveResult {
+    success: boolean;
+    newPath?: string;
+    error?: string;
+}
+/**
+ * Archives a plan by updating its status to completed in-place.
+ *
+ * This function:
+ * 1. Validates all tasks are done (unless force = true)
+ * 2. Updates frontmatter status to 'completed'
+ * 3. Returns new path on success
+ *
+ * @param slug - Plan slug (e.g., 'my-plan')
+ * @param projectPath - Root path of the project
+ * @param force - Skip validation and force archive
+ * @returns Archive result with success status and new path or error
+ *
+ * @example
+ * ```typescript
+ * const result = await archiveBlueprint('my-plan', '/path/to/project')
+ * if (result.success) {
+ *   console.log('Archived to:', result.newPath)
+ * } else {
+ *   console.error('Error:', result.error)
+ * }
+ * ```
+ */
+export declare function archiveBlueprint(slug: string, projectPath: string, force?: boolean): Promise<ArchiveResult>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/esm/blueprint/utils/archive.js

@@ -0,0 +1,209 @@
+/**
+ * Archive Operations
+ *
+ * Validates that all tasks in a plan are complete and updates status in place.
+ */
+import { access, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseBlueprint } from '#core/parser';
+import { resolveBlueprintRoot } from './blueprint-root.js';
+/**
+ * Validates that all tasks in a plan are complete.
+ *
+ * A task is considered complete when:
+ * - status === 'done'
+ * - All acceptance criteria checkboxes are checked
+ *
+ * @param plan - The plan to validate
+ * @returns Validation result with details of incomplete tasks
+ *
+ * @example
+ * ```typescript
+ * const result = validateAllTasksDone(plan)
+ * if (!result.valid) {
+ *   console.error(result.message)
+ *   console.log('Incomplete tasks:', result.incompleteTasks)
+ * }
+ * ```
+ */
+export function validateAllTasksDone(plan) {
+    const incompleteTasks = findIncompleteTasks(plan.tasks);
+    if (!incompleteTasks.length) {
+        return { valid: true };
+    }
+    return {
+        valid: false,
+        incompleteTasks,
+        message: formatErrorMessage(incompleteTasks),
+    };
+}
+/**
+ * Finds all incomplete tasks in a plan.
+ *
+ * @param tasks - Array of tasks to check
+ * @returns Array of incomplete tasks
+ */
+function findIncompleteTasks(tasks) {
+    return tasks
+        .filter((task) => !isTaskComplete(task))
+        .map((task) => ({
+        id: task.id,
+        title: task.title,
+        status: task.status,
+    }));
+}
+/**
+ * Checks if a task is complete.
+ *
+ * @param task - Task to check
+ * @returns True if task is complete
+ */
+function isTaskComplete(task) {
+    // Task must have status 'done'
+    if (task.status !== 'done') {
+        return false;
+    }
+    // All acceptance criteria checkboxes must be checked
+    const { total, checked } = task.acceptanceCriteria;
+    if (total > 0 && checked !== total) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Formats error message for incomplete tasks.
+ *
+ * @param incompleteTasks - Array of incomplete tasks
+ * @returns Formatted error message
+ */
+function formatErrorMessage(incompleteTasks) {
+    const count = incompleteTasks.length;
+    const taskList = incompleteTasks.map((task) => `Task ${task.id} (${task.status})`).join(', ');
+    return `${count} task${count === 1 ? '' : 's'} incomplete: ${taskList}`;
+}
+/**
+ * Archives a plan by updating its status to completed in-place.
+ *
+ * This function:
+ * 1. Validates all tasks are done (unless force = true)
+ * 2. Updates frontmatter status to 'completed'
+ * 3. Returns new path on success
+ *
+ * @param slug - Plan slug (e.g., 'my-plan')
+ * @param projectPath - Root path of the project
+ * @param force - Skip validation and force archive
+ * @returns Archive result with success status and new path or error
+ *
+ * @example
+ * ```typescript
+ * const result = await archiveBlueprint('my-plan', '/path/to/project')
+ * if (result.success) {
+ *   console.log('Archived to:', result.newPath)
+ * } else {
+ *   console.error('Error:', result.error)
+ * }
+ * ```
+ */
+export async function archiveBlueprint(slug, projectPath, force = false) {
+    // Check if already completed (before checking existence)
+    if (isAlreadyCompleted(slug)) {
+        return { success: false, error: 'Plan is already completed' };
+    }
+    const paths = buildPlanPaths(projectPath, slug);
+    // Check if plan exists
+    const planExists = await checkPlanExists(paths.sourcePath);
+    if (!planExists) {
+        return { success: false, error: `Plan not found: ${slug}` };
+    }
+    // Read plan and validate tasks (unless force)
+    if (!force) {
+        const validationError = await validatePlanTasks(paths.sourcePath, slug);
+        if (validationError) {
+            return { success: false, error: validationError };
+        }
+    }
+    // Update frontmatter status
+    const updateError = await updateBlueprintStatus(paths.sourcePath);
+    if (updateError) {
+        return { success: false, error: updateError };
+    }
+    return { success: true, newPath: paths.targetDir };
+}
+/**
+ * Builds source and target paths for archival.
+ *
+ * @param projectPath - Root path of the project
+ * @param slug - Plan slug
+ * @returns Path information
+ */
+function buildPlanPaths(projectPath, slug) {
+    const plansDir = resolveBlueprintRoot(projectPath);
+    const sourcePath = path.join(plansDir, slug, '_overview.md');
+    const sourceDir = path.dirname(sourcePath);
+    const targetDir = sourceDir;
+    return { sourcePath, sourceDir, targetDir, planName: slug };
+}
+/**
+ * Extracts plan name from slug (removes status prefix).
+ *
+ * @param slug - Plan slug
+ * @returns Plan name
+ */
+/**
+ * Checks if plan is already in completed/ folder.
+ *
+ * @param slug - Plan slug
+ * @returns True if already completed
+ */
+function isAlreadyCompleted(slug) {
+    return slug.startsWith('completed/');
+}
+/**
+ * Checks if plan file exists.
+ *
+ * @param sourcePath - Path to plan file
+ * @returns True if exists
+ */
+async function checkPlanExists(sourcePath) {
+    try {
+        await access(sourcePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validates plan tasks are complete.
+ *
+ * @param sourcePath - Path to plan file
+ * @param slug - Plan slug
+ * @returns Error message if validation fails, undefined otherwise
+ */
+async function validatePlanTasks(sourcePath, slug) {
+    const content = await readFile(sourcePath, 'utf-8');
+    const plan = parseBlueprint(content, slug);
+    const result = validateAllTasksDone(plan);
+    if (!result.valid) {
+        return result.message;
+    }
+    return undefined;
+}
+/**
+ * Updates plan status to completed in frontmatter.
+ *
+ * @param sourcePath - Path to plan file
+ * @returns Error message if update fails, undefined otherwise
+ */
+async function updateBlueprintStatus(sourcePath) {
+    try {
+        const content = await readFile(sourcePath, 'utf-8');
+        const updated = content.replace(/^status:\s*\S+/m, 'status: completed');
+        await writeFile(sourcePath, updated, 'utf-8');
+        return undefined;
+    }
+    catch (error) {
+        return `Failed to update status: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}
+//# sourceMappingURL=archive.js.map

package/dist/esm/blueprint/utils/blueprint-root.d.ts

@@ -0,0 +1,9 @@
+interface ResolveConsumerRootOptions {
+    defaultDir: string;
+    webpressoDir: string;
+    projectPath?: string;
+}
+export declare function resolveConsumerRoot({ defaultDir, webpressoDir, projectPath, }: ResolveConsumerRootOptions): string;
+export declare function resolveBlueprintRoot(projectPath?: string): string;
+export {};
+//# sourceMappingURL=blueprint-root.d.ts.map

package/dist/esm/blueprint/utils/blueprint-root.js

@@ -0,0 +1,77 @@
+/**
+ * Resolves the blueprints directory for a consumer repo.
+ *
+ * Checks in priority order:
+ *   0. `.webpressorc.json#blueprintsDir`     — explicit config override
+ *   1. `<projectPath>/blueprints/`           — generic consumer layout
+ *   2. `<projectPath>/webpresso/blueprints/` — webpresso legacy fallback
+ *
+ * Fresh generic repos default to `<projectPath>/blueprints/` when a normal
+ * project marker is present. Historical empty fixtures and Webpresso roots keep
+ * the legacy fallback so older callers that mkdir after service construction
+ * still work.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+const WEBPRESSO_CONFIG_PATH = 'webpresso/config.yaml';
+const WEBPRESSO_BLUEPRINTS_DIR = 'webpresso/blueprints';
+const DEFAULT_BLUEPRINTS_DIR = 'blueprints';
+const GENERIC_PROJECT_MARKERS = [
+    '.webpressorc.json',
+    'pnpm-workspace.yaml',
+    'package.json',
+];
+function readConfiguredBlueprintsDir(projectPath) {
+    try {
+        const raw = readFileSync(path.join(projectPath, '.webpressorc.json'), 'utf-8');
+        const v = JSON.parse(raw).blueprintsDir;
+        return typeof v === 'string' && v.trim() ? v.trim() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function hasWebpressoProjectMarker(projectPath) {
+    return existsSync(path.join(projectPath, WEBPRESSO_CONFIG_PATH));
+}
+function hasGenericProjectMarker(projectPath) {
+    return GENERIC_PROJECT_MARKERS.some((marker) => existsSync(path.join(projectPath, marker)));
+}
+export function resolveConsumerRoot({ defaultDir, webpressoDir, projectPath, }) {
+    if (projectPath === undefined) {
+        if (hasWebpressoProjectMarker(process.cwd()) && existsSync(path.resolve(webpressoDir))) {
+            return webpressoDir;
+        }
+        if (existsSync(path.resolve(defaultDir)))
+            return defaultDir;
+        if (existsSync(path.resolve(webpressoDir)))
+            return webpressoDir;
+        return webpressoDir;
+    }
+    const webpressoPath = path.join(projectPath, webpressoDir);
+    if (hasWebpressoProjectMarker(projectPath) && existsSync(webpressoPath)) {
+        return webpressoPath;
+    }
+    const genericPath = path.join(projectPath, defaultDir);
+    if (existsSync(genericPath))
+        return genericPath;
+    if (existsSync(webpressoPath))
+        return webpressoPath;
+    if (hasGenericProjectMarker(projectPath) && !hasWebpressoProjectMarker(projectPath)) {
+        return genericPath;
+    }
+    return webpressoPath;
+}
+export function resolveBlueprintRoot(projectPath) {
+    if (projectPath !== undefined) {
+        const configured = readConfiguredBlueprintsDir(projectPath);
+        if (configured)
+            return path.join(projectPath, configured);
+    }
+    return resolveConsumerRoot({
+        defaultDir: DEFAULT_BLUEPRINTS_DIR,
+        webpressoDir: WEBPRESSO_BLUEPRINTS_DIR,
+        projectPath,
+    });
+}
+//# sourceMappingURL=blueprint-root.js.map

package/dist/esm/blueprint/utils/conflict.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Conflict Resolution Policy Module
+ *
+ * Implements last-write-wins conflict resolution with audit trail
+ * for git-storage operations. Critical for handling concurrent writes
+ * from multiple agents or users.
+ */
+/**
+ * Represents a single write attempt to a file
+ */
+export interface WriteInfo {
+    /** Content being written */
+    content: string;
+    /** Timestamp of the write */
+    timestamp: Date;
+    /** Author/actor performing the write */
+    author: string;
+}
+/**
+ * Represents a conflict for a single file
+ */
+export interface ConflictInfo {
+    /** Path of the conflicting file */
+    filePath: string;
+    /** All competing writes to this file */
+    writes: WriteInfo[];
+}
+/**
+ * Result of resolving a single conflict
+ */
+export interface ResolvedConflict {
+    /** Path of the resolved file */
+    filePath: string;
+    /** Content that won the conflict */
+    winningContent: string;
+    /** Author whose write won */
+    winningAuthor: string;
+    /** Timestamp of the winning write */
+    winningTimestamp: Date;
+    /** All writes that lost the conflict */
+    losingWrites: WriteInfo[];
+}
+/**
+ * Result of conflict resolution for multiple files
+ */
+export interface ConflictResolution {
+    /** All resolved conflicts */
+    resolved: ResolvedConflict[];
+    /** Total number of conflicts processed */
+    totalConflicts: number;
+    /** Number of conflicts successfully resolved */
+    resolvedCount: number;
+}
+/**
+ * Audit entry for a conflict resolution
+ */
+export interface ConflictAuditEntry {
+    /** Timestamp when resolution occurred */
+    timestamp: Date;
+    /** Path of the conflicting file */
+    filePath: string;
+    /** The winning write */
+    winner: WriteInfo;
+    /** All losing writes */
+    losers: WriteInfo[];
+    /** Reason for the resolution decision */
+    reason: string;
+    /** Optional project identifier */
+    projectId?: string;
+}
+/**
+ * Configuration for the ConflictResolver
+ */
+export interface ConflictResolverConfig {
+    /** Project identifier for audit entries */
+    projectId?: string;
+}
+/**
+ * ConflictResolver
+ *
+ * Implements last-write-wins conflict resolution strategy.
+ * All resolutions are recorded in an audit log for debugging
+ * and accountability.
+ */
+export declare class ConflictResolver {
+    private readonly auditLog;
+    private readonly projectId?;
+    constructor(config?: ConflictResolverConfig);
+    /**
+     * Resolve conflicts using last-write-wins strategy
+     *
+     * For each conflict, the write with the latest timestamp wins.
+     * All resolutions are recorded in the audit log.
+     *
+     * @param conflicts - Array of conflicts to resolve
+     * @returns Resolution result with all resolved conflicts
+     */
+    resolve(conflicts: ConflictInfo[]): ConflictResolution;
+    /**
+     * Get the complete audit log of all conflict resolutions
+     *
+     * @returns Array of all audit entries
+     */
+    getAuditLog(): ConflictAuditEntry[];
+    /**
+     * Clear the audit log
+     */
+    clearAuditLog(): void;
+    /**
+     * Resolve a single conflict using last-write-wins
+     */
+    private resolveSingleConflict;
+    /**
+     * Record an audit entry for a resolution
+     */
+    private recordAuditEntry;
+}
+/**
+ * Factory function to create a ConflictResolver
+ *
+ * @param config - Optional configuration
+ * @returns New ConflictResolver instance
+ */
+export declare function createConflictResolver(config?: ConflictResolverConfig): ConflictResolver;
+//# sourceMappingURL=conflict.d.ts.map

package/dist/esm/blueprint/utils/conflict.js

@@ -0,0 +1,111 @@
+/**
+ * Conflict Resolution Policy Module
+ *
+ * Implements last-write-wins conflict resolution with audit trail
+ * for git-storage operations. Critical for handling concurrent writes
+ * from multiple agents or users.
+ */
+/**
+ * ConflictResolver
+ *
+ * Implements last-write-wins conflict resolution strategy.
+ * All resolutions are recorded in an audit log for debugging
+ * and accountability.
+ */
+export class ConflictResolver {
+    auditLog = [];
+    projectId;
+    constructor(config = {}) {
+        this.projectId = config.projectId;
+    }
+    /**
+     * Resolve conflicts using last-write-wins strategy
+     *
+     * For each conflict, the write with the latest timestamp wins.
+     * All resolutions are recorded in the audit log.
+     *
+     * @param conflicts - Array of conflicts to resolve
+     * @returns Resolution result with all resolved conflicts
+     */
+    resolve(conflicts) {
+        const resolved = [];
+        for (const conflict of conflicts) {
+            const resolution = this.resolveSingleConflict(conflict);
+            if (resolution) {
+                resolved.push(resolution);
+                this.recordAuditEntry(conflict.filePath, resolution);
+            }
+        }
+        return {
+            resolved,
+            totalConflicts: conflicts.length,
+            resolvedCount: resolved.length,
+        };
+    }
+    /**
+     * Get the complete audit log of all conflict resolutions
+     *
+     * @returns Array of all audit entries
+     */
+    getAuditLog() {
+        return [...this.auditLog];
+    }
+    /**
+     * Clear the audit log
+     */
+    clearAuditLog() {
+        this.auditLog.length = 0;
+    }
+    /**
+     * Resolve a single conflict using last-write-wins
+     */
+    resolveSingleConflict(conflict) {
+        if (!conflict.writes.length) {
+            return null;
+        }
+        // Sort by timestamp descending (newest first)
+        const sortedWrites = [...conflict.writes].toSorted((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
+        const winner = sortedWrites[0];
+        if (!winner) {
+            return null;
+        }
+        const losers = sortedWrites.slice(1);
+        return {
+            filePath: conflict.filePath,
+            winningContent: winner.content,
+            winningAuthor: winner.author,
+            winningTimestamp: winner.timestamp,
+            losingWrites: losers,
+        };
+    }
+    /**
+     * Record an audit entry for a resolution
+     */
+    recordAuditEntry(filePath, resolution) {
+        const entry = {
+            timestamp: new Date(),
+            filePath,
+            winner: {
+                content: resolution.winningContent,
+                timestamp: resolution.winningTimestamp,
+                author: resolution.winningAuthor,
+            },
+            losers: resolution.losingWrites,
+            reason: 'last-write-wins: timestamp comparison',
+        };
+        if (this.projectId) {
+            entry.projectId = this.projectId;
+        }
+        this.auditLog.push(entry);
+    }
+}
+/**
+ * Factory function to create a ConflictResolver
+ *
+ * @param config - Optional configuration
+ * @returns New ConflictResolver instance
+ */
+export function createConflictResolver(config) {
+    return new ConflictResolver(config);
+}
+//# sourceMappingURL=conflict.js.map

package/dist/esm/blueprint/utils/decision-trace-artifacts.d.ts

@@ -0,0 +1,16 @@
+export interface DecisionTraceArtifact {
+    timestamp: string;
+    source_kind: string;
+    source_id: string;
+    trace_type: string;
+    subject_kind: string;
+    subject_id: string;
+    context: Record<string, unknown>;
+    decision: string;
+    outcome: string;
+    evidence: Record<string, unknown>;
+    status: string;
+}
+export declare function emitTraceArtifact(projectRoot: string, artifact: DecisionTraceArtifact): string;
+export declare function generateBlueprintLifecycleTrace(blueprintSlug: string, action: string, details: Record<string, unknown>): DecisionTraceArtifact;
+//# sourceMappingURL=decision-trace-artifacts.d.ts.map

package/dist/esm/blueprint/utils/decision-trace-artifacts.js

@@ -0,0 +1,37 @@
+/**
+ * Persists decision-trace artifacts to the repo's `.webpresso/decision-traces/`
+ * directory. Used by BlueprintService to record lifecycle events.
+ *
+ * Inlined so this package has no external runtime dependencies.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+function sanitizeTimestamp(isoTimestamp) {
+    return isoTimestamp.replaceAll(':', '-');
+}
+export function emitTraceArtifact(projectRoot, artifact) {
+    const traceDir = join(projectRoot, '.webpresso', 'decision-traces');
+    if (!existsSync(traceDir)) {
+        mkdirSync(traceDir, { recursive: true });
+    }
+    const filename = `${sanitizeTimestamp(artifact.timestamp)}-${artifact.source_kind}.json`;
+    const filePath = join(traceDir, filename);
+    writeFileSync(filePath, JSON.stringify(artifact, null, 2), 'utf-8');
+    return filePath;
+}
+export function generateBlueprintLifecycleTrace(blueprintSlug, action, details) {
+    return {
+        timestamp: new Date().toISOString(),
+        source_kind: 'blueprint_lifecycle',
+        source_id: `blueprint-${blueprintSlug}-${Date.now()}`,
+        trace_type: action,
+        subject_kind: 'blueprint',
+        subject_id: blueprintSlug,
+        context: details,
+        decision: action,
+        outcome: 'success',
+        evidence: {},
+        status: 'success',
+    };
+}
+//# sourceMappingURL=decision-trace-artifacts.js.map

package/dist/esm/blueprint/utils/errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Error types for plan operations.
+ */
+/**
+ * Error thrown when a plan is not found.
+ * Includes structured data for fuzzy matching and helpful error messages.
+ */
+export declare class BlueprintNotFoundError extends Error {
+    readonly searchedPath: string;
+    readonly availableSlugs: readonly string[];
+    readonly requestedSlug: string;
+    constructor(slug: string, searchedPath: string, availableSlugs: readonly string[]);
+}
+//# sourceMappingURL=errors.d.ts.map