@promptwheel/core 0.6.0

package/dist/critic/shared.js

@@ -0,0 +1,204 @@
+/**
+ * Critic Scoring — pure algorithms for retry guidance.
+ *
+ * When QA fails or a plan is rejected, these functions analyze structured
+ * learnings to build targeted guidance for the retry prompt.
+ *
+ * No I/O — callers provide learnings and failure context.
+ */
+// ---------------------------------------------------------------------------
+// Scoring
+// ---------------------------------------------------------------------------
+/**
+ * Compute retry risk based on learnings overlap with the failing ticket.
+ */
+export function computeRetryRisk(ticketPaths, ticketCommands, learnings, failureContext) {
+    const signals = [];
+    let score = failureContext.attempt * 20;
+    const pathSet = new Set(ticketPaths.map(p => p.replace(/\/?\*\*?$/, '')));
+    for (const l of learnings) {
+        if (!l.structured)
+            continue;
+        const sk = l.structured;
+        // Fragile path overlap
+        if (sk.fragile_paths) {
+            for (const fp of sk.fragile_paths) {
+                if (pathSet.has(fp) || [...pathSet].some(p => fp.startsWith(p + '/') || p.startsWith(fp + '/'))) {
+                    score += 15;
+                    signals.push(`Fragile: ${fp}`);
+                    break;
+                }
+            }
+        }
+        // Error signature match
+        if (sk.failure_context?.error_signature && failureContext.error_output) {
+            if (failureContext.error_output.includes(sk.failure_context.error_signature) ||
+                sk.failure_context.error_signature.includes(failureContext.error_output.slice(0, 80))) {
+                score += 20;
+                signals.push(`Known error: ${sk.failure_context.error_signature.slice(0, 60)}`);
+            }
+        }
+        // Cochange files not in allowed paths
+        if (sk.cochange_files) {
+            for (const cf of sk.cochange_files) {
+                const cfClean = cf.replace(/\/?\*\*?$/, '');
+                if (!pathSet.has(cfClean) && ![...pathSet].some(p => cfClean.startsWith(p + '/'))) {
+                    score += 10;
+                    signals.push(`Missing cochange: ${cf}`);
+                    break;
+                }
+            }
+        }
+    }
+    score = Math.min(100, score);
+    const level = score < 30 ? 'low' : score <= 60 ? 'medium' : 'high';
+    return { score, level, signals };
+}
+/**
+ * Generate ranked strategies for a retry based on learnings.
+ * Returns top 3 by confidence.
+ */
+export function scoreStrategies(ticketPaths, failureContext, learnings) {
+    const strategies = [];
+    const pathSet = new Set(ticketPaths.map(p => p.replace(/\/?\*\*?$/, '')));
+    for (const l of learnings) {
+        if (!l.structured)
+            continue;
+        const sk = l.structured;
+        // "Apply known fix" — if a learning has fix_applied
+        if (sk.failure_context?.fix_applied) {
+            strategies.push({
+                label: 'Apply known fix',
+                instruction: sk.failure_context.fix_applied,
+                confidence: l.weight,
+            });
+        }
+        // "Include cochange files" — if cochange_files overlap
+        if (sk.cochange_files) {
+            const missing = sk.cochange_files.filter(cf => {
+                const cfClean = cf.replace(/\/?\*\*?$/, '');
+                return !pathSet.has(cfClean) && ![...pathSet].some(p => cfClean.startsWith(p + '/'));
+            });
+            if (missing.length > 0) {
+                strategies.push({
+                    label: 'Include cochange files',
+                    instruction: `${missing.join(', ')} often change together with the ticket files`,
+                    confidence: Math.round(l.weight * 0.8),
+                });
+            }
+        }
+        // "Avoid antipattern" — if antipattern learning matches
+        if (sk.pattern_type === 'antipattern') {
+            strategies.push({
+                label: 'Avoid antipattern',
+                instruction: l.text,
+                confidence: Math.round(l.weight * 0.7),
+            });
+        }
+    }
+    // "Different approach" fallback on attempt >= 2
+    if (failureContext.attempt >= 2) {
+        strategies.push({
+            label: 'Different approach',
+            instruction: 'The previous approach failed. Try a fundamentally different implementation strategy.',
+            confidence: 30,
+        });
+    }
+    // Deduplicate by label (keep highest confidence)
+    const best = new Map();
+    for (const s of strategies) {
+        const existing = best.get(s.label);
+        if (!existing || s.confidence > existing.confidence) {
+            best.set(s.label, s);
+        }
+    }
+    return [...best.values()]
+        .sort((a, b) => b.confidence - a.confidence)
+        .slice(0, 3);
+}
+// ---------------------------------------------------------------------------
+// Block builders
+// ---------------------------------------------------------------------------
+/**
+ * Build a critic review block for QA retry prompts.
+ * Returns empty string if risk is low and no high-confidence strategies exist.
+ */
+export function buildCriticBlock(failureContext, risk, strategies, _learnings) {
+    // Skip prompt bloat when risk is low and no strategies are confident
+    if (risk.level === 'low' && !strategies.some(s => s.confidence > 50)) {
+        return '';
+    }
+    const lines = [
+        '<critic-review>',
+        `## Retry Guidance (attempt ${failureContext.attempt}/${failureContext.max_attempts})`,
+        '',
+        '### What Went Wrong',
+    ];
+    for (const cmd of failureContext.failed_commands) {
+        lines.push(`- Failed: \`${cmd}\``);
+    }
+    if (failureContext.error_output) {
+        const truncated = failureContext.error_output.slice(0, 200);
+        lines.push(`- Error: ${truncated}`);
+    }
+    lines.push('');
+    lines.push(`### Risk: ${risk.level.toUpperCase()} (score: ${risk.score})`);
+    for (const sig of risk.signals) {
+        lines.push(`- ${sig}`);
+    }
+    if (strategies.length > 0) {
+        lines.push('');
+        lines.push('### Recommended Approach');
+        for (const s of strategies) {
+            lines.push(`${s.confidence}. [${s.confidence}] ${s.label}: ${s.instruction}`);
+        }
+    }
+    lines.push('</critic-review>');
+    return lines.join('\n');
+}
+/**
+ * Build a critic block for plan rejection retries.
+ * Returns empty string if no actionable guidance exists.
+ */
+export function buildPlanRejectionCriticBlock(context, learnings, ticketPaths) {
+    const pathSet = new Set(ticketPaths.map(p => p.replace(/\/?\*\*?$/, '')));
+    const relevantLearnings = learnings.filter(l => {
+        if (!l.structured)
+            return false;
+        if (l.source.type !== 'plan_rejection' && l.source.type !== 'scope_violation')
+            return false;
+        // Check path overlap
+        for (const tag of l.tags) {
+            if (tag.startsWith('path:')) {
+                const lPath = tag.slice(5);
+                if (pathSet.has(lPath) || [...pathSet].some(p => lPath.startsWith(p + '/') || p.startsWith(lPath + '/'))) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    });
+    if (relevantLearnings.length === 0 && !context.rejection_reason) {
+        return '';
+    }
+    const lines = [
+        '<critic-review>',
+        `## Plan Revision Guidance (attempt ${context.attempt}/${context.max_attempts})`,
+        '',
+        `### Rejection Reason`,
+        context.rejection_reason,
+        '',
+    ];
+    if (relevantLearnings.length > 0) {
+        lines.push('### Previous Plan Rejections in These Files');
+        for (const l of relevantLearnings.slice(0, 3)) {
+            lines.push(`- ${l.text}`);
+            if (l.structured?.root_cause) {
+                lines.push(`  Cause: ${l.structured.root_cause}`);
+            }
+        }
+    }
+    lines.push('</critic-review>');
+    return lines.join('\n');
+}
+//# sourceMappingURL=shared.js.map

package/dist/critic/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/critic/shared.ts"],"names":[],"mappings":"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"}

package/dist/db/adapter.d.ts

@@ -0,0 +1,191 @@
+/**
+ * DatabaseAdapter - Abstract interface for database operations
+ *
+ * This interface allows PromptWheel to work with different database backends:
+ * - PostgreSQL (for teams/cloud)
+ * - SQLite (for individual developers, zero-config)
+ *
+ * Implementations must handle:
+ * - Connection management
+ * - Query execution with parameterized queries
+ * - Transaction support
+ * - Schema migrations
+ */
+/**
+ * Result of a database query
+ */
+export interface QueryResult<T = Record<string, unknown>> {
+    /** Array of rows returned by the query */
+    rows: T[];
+    /** Number of rows affected (for INSERT/UPDATE/DELETE) */
+    rowCount: number | null;
+    /** Column metadata (optional, Postgres-specific) */
+    fields?: Array<{
+        name: string;
+        dataTypeID?: number;
+    }>;
+}
+/**
+ * Transaction client interface
+ * Passed to transaction callbacks to execute queries within the transaction
+ */
+export interface TransactionClient {
+    /**
+     * Execute a query within the transaction
+     */
+    query<T = Record<string, unknown>>(text: string, params?: unknown[]): Promise<QueryResult<T>>;
+}
+/**
+ * Migration definition
+ */
+export interface Migration {
+    /** Unique migration identifier (e.g., "001_initial") */
+    id: string;
+    /** SQL to apply the migration */
+    up: string;
+    /** SQL to rollback the migration (optional) */
+    down?: string;
+    /** Checksum for integrity validation */
+    checksum: string;
+}
+/**
+ * Migration result
+ */
+export interface MigrationResult {
+    /** Migrations that were applied */
+    applied: string[];
+    /** Migrations that were skipped (already applied) */
+    skipped: string[];
+    /** Whether this was a dry run */
+    dryRun: boolean;
+}
+/**
+ * Query logging configuration
+ */
+export interface QueryLogConfig {
+    /** Log all queries (verbose) */
+    logAll: boolean;
+    /** Log queries slower than this threshold (ms) */
+    slowQueryThresholdMs: number;
+    /** Log query parameters (may expose sensitive data) */
+    logParams: boolean;
+}
+/**
+ * Query statistics for monitoring
+ */
+export interface QueryStats {
+    totalQueries: number;
+    totalErrors: number;
+    totalDurationMs: number;
+    byType: Record<string, {
+        count: number;
+        errors: number;
+        durationMs: number;
+    }>;
+}
+/**
+ * Database adapter interface
+ *
+ * All database operations in PromptWheel go through this interface,
+ * allowing seamless switching between backends.
+ */
+export interface DatabaseAdapter {
+    /**
+     * Adapter name for logging/debugging
+     */
+    readonly name: string;
+    /**
+     * Whether the adapter is connected
+     */
+    readonly connected: boolean;
+    /**
+     * Execute a parameterized query
+     *
+     * @param text - SQL query with $1, $2, etc. placeholders
+     * @param params - Parameter values
+     * @returns Query result with rows and metadata
+     *
+     * @example
+     * const result = await adapter.query<UserRow>(
+     *   'SELECT * FROM users WHERE id = $1',
+     *   [userId]
+     * );
+     */
+    query<T = Record<string, unknown>>(text: string, params?: unknown[]): Promise<QueryResult<T>>;
+    /**
+     * Execute a function within a database transaction
+     *
+     * The transaction is automatically committed on success,
+     * or rolled back on error.
+     *
+     * @param fn - Function to execute within the transaction
+     * @returns Result of the function
+     *
+     * @example
+     * await adapter.withTransaction(async (tx) => {
+     *   await tx.query('INSERT INTO orders ...', [...]);
+     *   await tx.query('UPDATE inventory ...', [...]);
+     * });
+     */
+    withTransaction<T>(fn: (client: TransactionClient) => Promise<T>): Promise<T>;
+    /**
+     * Run pending migrations
+     *
+     * @param options - Migration options
+     * @returns Migration result
+     */
+    migrate(options?: {
+        dryRun?: boolean;
+        target?: string;
+        verbose?: boolean;
+    }): Promise<MigrationResult>;
+    /**
+     * Close the database connection
+     *
+     * Should be called when shutting down the application.
+     */
+    close(): Promise<void>;
+    /**
+     * Configure query logging
+     */
+    configureLogging?(config: Partial<QueryLogConfig>): void;
+    /**
+     * Get query statistics
+     */
+    getStats?(): Readonly<QueryStats>;
+    /**
+     * Reset query statistics
+     */
+    resetStats?(): void;
+}
+/**
+ * Factory function type for creating database adapters
+ */
+export type DatabaseAdapterFactory = (config: DatabaseConfig) => Promise<DatabaseAdapter>;
+/**
+ * Database configuration
+ */
+export interface DatabaseConfig {
+    /** Connection URL (postgres://, sqlite://, or file path) */
+    url: string;
+    /** Maximum connections in pool (Postgres) */
+    maxConnections?: number;
+    /** Idle timeout in ms */
+    idleTimeoutMs?: number;
+    /** Connection timeout in ms */
+    connectionTimeoutMs?: number;
+    /** Enable WAL mode (SQLite) */
+    walMode?: boolean;
+}
+/**
+ * Detect database type from URL
+ */
+export declare function detectDatabaseType(url: string): 'postgres' | 'sqlite' | 'unknown';
+/**
+ * Default database URL based on environment
+ *
+ * - If DATABASE_URL is set, use it (Postgres)
+ * - Otherwise, default to SQLite at ~/.promptwheel/data.db
+ */
+export declare function getDefaultDatabaseUrl(): string;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/db/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/db/adapter.ts"],"names":[],"mappings":"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"}

package/dist/db/adapter.js

@@ -0,0 +1,40 @@
+/**
+ * DatabaseAdapter - Abstract interface for database operations
+ *
+ * This interface allows PromptWheel to work with different database backends:
+ * - PostgreSQL (for teams/cloud)
+ * - SQLite (for individual developers, zero-config)
+ *
+ * Implementations must handle:
+ * - Connection management
+ * - Query execution with parameterized queries
+ * - Transaction support
+ * - Schema migrations
+ */
+/**
+ * Detect database type from URL
+ */
+export function detectDatabaseType(url) {
+    if (url.startsWith('postgres://') || url.startsWith('postgresql://')) {
+        return 'postgres';
+    }
+    if (url.startsWith('sqlite://') || url.startsWith('file:') || url.endsWith('.db') || url.endsWith('.sqlite')) {
+        return 'sqlite';
+    }
+    return 'unknown';
+}
+/**
+ * Default database URL based on environment
+ *
+ * - If DATABASE_URL is set, use it (Postgres)
+ * - Otherwise, default to SQLite at ~/.promptwheel/data.db
+ */
+export function getDefaultDatabaseUrl() {
+    if (process.env.DATABASE_URL) {
+        return process.env.DATABASE_URL;
+    }
+    // Default to SQLite for zero-config mode
+    const home = process.env.HOME || process.env.USERPROFILE || '.';
+    return `${home}/.promptwheel/data.db`;
+}
+//# sourceMappingURL=adapter.js.map

package/dist/db/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../src/db/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAwLH;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,IAAI,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACrE,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,IAAI,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7G,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB;IACnC,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC;QAC7B,OAAO,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IAClC,CAAC;IAED,yCAAyC;IACzC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC;IAChE,OAAO,GAAG,IAAI,uBAAuB,CAAC;AACxC,CAAC"}

package/dist/db/contract.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Database Adapter Contract Tests
+ *
+ * This module exports a test harness that validates any DatabaseAdapter
+ * implementation behaves correctly. Run these tests against both SQLite
+ * and Postgres adapters to ensure consistent behavior.
+ *
+ * Usage:
+ *   import { runAdapterContract } from '@promptwheel/core/db/contract';
+ *   import { createSQLiteAdapter } from '@promptwheel/sqlite';
+ *
+ *   describe('SQLite Adapter', () => {
+ *     runAdapterContract(() => createSQLiteAdapter({ url: ':memory:' }));
+ *   });
+ */
+import type { DatabaseAdapter } from './adapter.js';
+/**
+ * Test result
+ */
+export interface ContractTestResult {
+    name: string;
+    passed: boolean;
+    error?: string;
+    durationMs: number;
+}
+/**
+ * Contract test suite result
+ */
+export interface ContractSuiteResult {
+    adapter: string;
+    total: number;
+    passed: number;
+    failed: number;
+    results: ContractTestResult[];
+}
+/**
+ * Run the adapter contract test suite
+ *
+ * @param createAdapter - Factory function to create a fresh adapter for each test
+ * @returns Test results
+ */
+export declare function runAdapterContract(createAdapter: () => Promise<DatabaseAdapter>): Promise<ContractSuiteResult>;
+/**
+ * Format contract test results for console output
+ */
+export declare function formatContractResults(suite: ContractSuiteResult): string;
+//# sourceMappingURL=contract.d.ts.map

package/dist/db/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/db/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAWpD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,kBAAkB,EAAE,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,aAAa,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,GAC5C,OAAO,CAAC,mBAAmB,CAAC,CAwR9B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAmBxE"}