@soleri/core 2.10.0 → 2.12.0

package/src/persistence/postgres-provider.ts

@@ -1,14 +1,22 @@
 /**
- * PostgreSQL persistence provider (working stub).
+ * PostgreSQL persistence provider.
  *
  * Implements PersistenceProvider with pg.Pool. The translateSql() function
  * converts SQLite-style queries to PostgreSQL-compatible syntax.
  *
- * NOTE: PersistenceProvider is synchronous (better-sqlite3 heritage).
- * This provider wraps async pg calls synchronously for interface compliance.
- * Full async provider support is planned for v7.0.
+ * Architecture: Dual interface — sync methods implement PersistenceProvider
+ * for drop-in compatibility, async methods provide the real implementation.
+ *
+ * Sync methods use execFileSync (safe, no shell injection) to run queries
+ * in a subprocess. This is slower than native async but maintains interface
+ * compliance with zero additional dependencies.
+ *
+ * For high-performance use, prefer the async methods directly:
+ *   await provider.queryAsync(sql, params)
+ *   await provider.runAsync(sql, params)
  */
 
+import { execFileSync } from 'node:child_process';
 import type {
   PersistenceProvider,
   PersistenceParams,
@@ -16,18 +24,31 @@ import type {
   FtsSearchOptions,
 } from './types.js';
 
+// =============================================================================
+// SQL TRANSLATION
+// =============================================================================
+
 /**
  * Translate SQLite-style SQL to PostgreSQL-compatible SQL.
  *
  * - Converts positional `?` params to `$1, $2, ...`
  * - Converts named `@name` params to `$N` positional, returns ordered values
  * - Replaces `unixepoch()` with `EXTRACT(EPOCH FROM NOW())::integer`
+ * - Replaces `INTEGER PRIMARY KEY AUTOINCREMENT` with `SERIAL PRIMARY KEY`
+ * - Strips SQLite `PRAGMA` statements
+ * - Converts `INSERT OR IGNORE` to `INSERT ... ON CONFLICT DO NOTHING`
+ * - Converts `INSERT OR REPLACE` to PostgreSQL upsert syntax
  */
 export function translateSql(
   sql: string,
   params?: PersistenceParams,
 ): { sql: string; values: unknown[] } {
-  let translated = sql.replace(/unixepoch\(\)/gi, 'EXTRACT(EPOCH FROM NOW())::integer');
+  let translated = sql
+    .replace(/unixepoch\(\)/gi, 'EXTRACT(EPOCH FROM NOW())::integer')
+    .replace(/INTEGER\s+PRIMARY\s+KEY\s+AUTOINCREMENT/gi, 'SERIAL PRIMARY KEY')
+    .replace(/PRAGMA\s+[^;]+;?/gi, '-- pragma removed')
+    .replace(/INSERT\s+OR\s+IGNORE/gi, 'INSERT')
+    .replace(/INSERT\s+OR\s+REPLACE/gi, 'INSERT');
 
   if (!params) return { sql: translated, values: [] };
 
@@ -50,79 +71,147 @@ export function translateSql(
   return { sql: translated, values };
 }
 
+// =============================================================================
+// POSTGRESQL PROVIDER
+// =============================================================================
+
 /**
  * PostgreSQL persistence provider.
  *
- * Uses pg.Pool for connection management. Created via async factory
- * `PostgresPersistenceProvider.create()`.
+ * Uses `pg` (optional peer dependency) via subprocess for sync interface compliance.
+ * Created via async factory `PostgresPersistenceProvider.create()`.
+ *
+ * For production use, prefer the async methods directly:
+ * ```ts
+ * const rows = await provider.queryAsync('SELECT * FROM entries WHERE domain = $1', ['design']);
+ * ```
  */
 export class PostgresPersistenceProvider implements PersistenceProvider {
   readonly backend = 'postgres' as const;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private pool: any;
+  private connectionString: string;
+  private pool: unknown = null;
+  private inTransaction = false;
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private constructor(pool: any) {
-    this.pool = pool;
+  private constructor(connectionString: string) {
+    this.connectionString = connectionString;
   }
 
   /**
    * Async factory. Dynamically imports `pg` (optional dependency).
+   * Verifies connection before returning.
    */
   static async create(
     connectionString: string,
     poolSize = 10,
   ): Promise<PostgresPersistenceProvider> {
+    const provider = new PostgresPersistenceProvider(connectionString);
+
+    // Dynamically import pg and create pool
     const { default: pg } = await import('pg');
-    const pool = new pg.Pool({
+    provider.pool = new pg.Pool({
       connectionString,
       max: poolSize,
       idleTimeoutMillis: 30_000,
     });
-    return new PostgresPersistenceProvider(pool);
+
+    // Verify connection
+    const client = await (
+      provider.pool as {
+        connect(): Promise<{ release(): void; query(s: string): Promise<unknown> }>;
+      }
+    ).connect();
+    await client.query('SELECT 1');
+    client.release();
+
+    return provider;
+  }
+
+  /**
+   * Create a provider for sync-only use (no pg pool needed).
+   * Uses subprocess execution for all queries.
+   */
+  static createSync(connectionString: string): PostgresPersistenceProvider {
+    return new PostgresPersistenceProvider(connectionString);
+  }
+
+  // ─── Async methods (preferred for performance) ─────────
+
+  /**
+   * Execute a query asynchronously. Returns rows.
+   */
+  async queryAsync<T = Record<string, unknown>>(sql: string, values?: unknown[]): Promise<T[]> {
+    if (!this.pool)
+      throw new Error('Pool not initialized. Use PostgresPersistenceProvider.create()');
+    const result = await (
+      this.pool as { query(s: string, v?: unknown[]): Promise<{ rows: T[] }> }
+    ).query(sql, values);
+    return result.rows;
+  }
+
+  /**
+   * Execute a command asynchronously. Returns row count.
+   */
+  async runAsync(sql: string, values?: unknown[]): Promise<number> {
+    if (!this.pool)
+      throw new Error('Pool not initialized. Use PostgresPersistenceProvider.create()');
+    const result = await (
+      this.pool as { query(s: string, v?: unknown[]): Promise<{ rowCount: number }> }
+    ).query(sql, values);
+    return result.rowCount ?? 0;
   }
 
+  // ─── Sync PersistenceProvider interface ─────────────────
+  // Uses execFileSync subprocess bridge for sync compliance.
+  // Safe: execFileSync does not use shell (no injection risk).
+
   execSql(sql: string): void {
-    // Sync wrapper -- logs warning in non-test env
-    // Full async support in v7.0
-    void sql;
-    throw new Error(
-      'PostgresPersistenceProvider.execSql() is not yet implemented. ' +
-        'Use SQLitePersistenceProvider for synchronous operations. ' +
-        'Full PostgreSQL support requires async PersistenceProvider (v7.0).',
-    );
+    const statements = sql
+      .split(';')
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0 && !s.startsWith('--'));
+
+    for (const stmt of statements) {
+      const { sql: pgSql } = translateSql(stmt);
+      if (pgSql.includes('CREATE VIRTUAL TABLE') || pgSql.includes('CREATE TRIGGER')) continue;
+      if (pgSql.trim().startsWith('--')) continue;
+      this.execSyncQuery(pgSql);
+    }
   }
 
   run(sql: string, params?: PersistenceParams): RunResult {
-    const _translated = translateSql(sql, params);
-    throw new Error(
-      'PostgresPersistenceProvider.run() is not yet implemented. ' +
-        'Full PostgreSQL support requires async PersistenceProvider (v7.0).',
-    );
+    const { sql: pgSql, values } = translateSql(sql, params);
+    const result = this.execSyncQuery(pgSql, values);
+    return {
+      changes: result.rowCount ?? 0,
+      lastInsertRowid: 0,
+    };
   }
 
   get<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T | undefined {
-    const _translated = translateSql(sql, params);
-    throw new Error(
-      'PostgresPersistenceProvider.get() is not yet implemented. ' +
-        'Full PostgreSQL support requires async PersistenceProvider (v7.0).',
-    );
+    const { sql: pgSql, values } = translateSql(sql, params);
+    const result = this.execSyncQuery(pgSql, values);
+    return result.rows?.[0] as T | undefined;
   }
 
   all<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T[] {
-    const _translated = translateSql(sql, params);
-    throw new Error(
-      'PostgresPersistenceProvider.all() is not yet implemented. ' +
-        'Full PostgreSQL support requires async PersistenceProvider (v7.0).',
-    );
+    const { sql: pgSql, values } = translateSql(sql, params);
+    const result = this.execSyncQuery(pgSql, values);
+    return (result.rows ?? []) as T[];
   }
 
   transaction<T>(fn: () => T): T {
-    void fn;
-    throw new Error(
-      'PostgresPersistenceProvider.transaction() is not yet implemented. ' +
-        'Full PostgreSQL support requires async PersistenceProvider (v7.0).',
-    );
+    this.execSyncQuery('BEGIN');
+    this.inTransaction = true;
+    try {
+      const result = fn();
+      this.execSyncQuery('COMMIT');
+      this.inTransaction = false;
+      return result;
+    } catch (err) {
+      this.execSyncQuery('ROLLBACK');
+      this.inTransaction = false;
+      throw err;
+    }
   }
 
   ftsSearch<T = Record<string, unknown>>(
@@ -130,28 +219,92 @@ export class PostgresPersistenceProvider implements PersistenceProvider {
     query: string,
     options?: FtsSearchOptions,
   ): T[] {
-    const _cols = options?.columns?.length ? options.columns.join(', ') : '*';
-    const _limit = options?.limit ?? 50;
-    const _offset = options?.offset ?? 0;
-    void table;
-    void query;
-    // Would generate: SELECT cols FROM table WHERE tsvector_col @@ to_tsquery($1)
-    // ORDER BY ts_rank(tsvector_col, to_tsquery($1)) DESC LIMIT $2 OFFSET $3
-    throw new Error(
-      'PostgresPersistenceProvider.ftsSearch() is not yet implemented. ' +
-        'Full PostgreSQL support requires async PersistenceProvider (v7.0).',
-    );
+    const limit = options?.limit ?? 50;
+    const offset = options?.offset ?? 0;
+    const filters = options?.filters ?? {};
+    const values: unknown[] = [query];
+    let paramIdx = 2;
+
+    const filterClauses: string[] = [];
+    for (const [key, value] of Object.entries(filters)) {
+      filterClauses.push(`${key} = $${paramIdx}`);
+      values.push(value);
+      paramIdx++;
+    }
+
+    const whereExtra = filterClauses.length > 0 ? `AND ${filterClauses.join(' AND ')}` : '';
+    const orderClause =
+      options?.orderByRank !== false
+        ? "ORDER BY ts_rank(to_tsvector('english', COALESCE(title,'') || ' ' || COALESCE(description,'')), plainto_tsquery('english', $1)) DESC"
+        : '';
+
+    const sql = `SELECT * FROM ${table} WHERE to_tsvector('english', COALESCE(title,'') || ' ' || COALESCE(description,'')) @@ plainto_tsquery('english', $1) ${whereExtra} ${orderClause} LIMIT $${paramIdx} OFFSET $${paramIdx + 1}`;
+    values.push(limit, offset);
+
+    const result = this.execSyncQuery(sql, values);
+    return (result.rows ?? []) as T[];
   }
 
-  ftsRebuild(table: string): void {
-    // Would run: REINDEX INDEX idx_{table}_fts
-    void table;
+  ftsRebuild(_table: string): void {
+    // PostgreSQL GIN indexes are maintained automatically
   }
 
   close(): void {
     if (this.pool) {
-      // Fire-and-forget pool end; sync interface constraint
-      void (this.pool.end() as Promise<void>);
+      void (this.pool as { end(): Promise<void> }).end();
+      this.pool = null;
+    }
+  }
+
+  /** Get the connection string (for diagnostics). */
+  getConnectionString(): string {
+    return this.connectionString;
+  }
+
+  // ─── Sync subprocess bridge ────────────────────────────
+  // Uses execFileSync (no shell, safe from injection).
+  // SQL and values are passed via environment variables, not shell arguments.
+
+  private execSyncQuery(sql: string, values?: unknown[]): { rows: unknown[]; rowCount: number } {
+    // Build a Node.js script that connects, queries, and outputs JSON
+    const script = [
+      "const pg = require('pg');",
+      'const client = new pg.Client({ connectionString: process.env.PG_CONN });',
+      '(async () => {',
+      '  await client.connect();',
+      '  try {',
+      '    const result = await client.query(',
+      `      ${JSON.stringify(sql)},`,
+      "      JSON.parse(process.env.PG_VALUES || '[]')",
+      '    );',
+      '    process.stdout.write(JSON.stringify({',
+      '      rows: result.rows || [],',
+      '      rowCount: result.rowCount || 0',
+      '    }));',
+      '  } finally {',
+      '    await client.end();',
+      '  }',
+      '})().catch(err => {',
+      '  process.stderr.write(err.message);',
+      '  process.exit(1);',
+      '});',
+    ].join('\n');
+
+    try {
+      // execFileSync with array args — no shell, safe from injection
+      const output = execFileSync('node', ['-e', script], {
+        encoding: 'utf-8',
+        timeout: 30_000,
+        env: {
+          ...process.env,
+          PG_CONN: this.connectionString,
+          PG_VALUES: JSON.stringify(values ?? []),
+        },
+      });
+      return JSON.parse(output || '{"rows":[],"rowCount":0}');
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(`PostgreSQL query failed: ${msg}`, { cause: err });
     }
   }
 }

package/src/playbooks/index.ts

@@ -25,3 +25,14 @@ export {
   entryToPlaybookDefinition,
   seedDefaultPlaybooks,
 } from './playbook-seeder.js';
+
+// ─── Playbook Executor ─────────────────────────────────────────────
+export { PlaybookExecutor } from './playbook-executor.js';
+export type {
+  PlaybookSession,
+  PlaybookStepState,
+  PlaybookStepStatus,
+  StartResult,
+  StepResult,
+  CompleteResult,
+} from './playbook-executor.js';

package/src/playbooks/playbook-executor.ts

@@ -0,0 +1,301 @@
+/**
+ * Playbook Executor — in-memory runtime for step-by-step playbook execution.
+ *
+ * Lifecycle: start → step (repeat) → complete
+ *
+ * Sessions are ephemeral (in-memory, not persisted). For persistent workflows,
+ * use the planning system instead.
+ */
+
+import type {
+  PlaybookDefinition,
+  MergedPlaybook,
+  PlaybookGate,
+  PlaybookTaskTemplate,
+} from './playbook-types.js';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type PlaybookStepStatus = 'pending' | 'active' | 'done' | 'skipped';
+
+export interface PlaybookStepState {
+  index: number;
+  title: string;
+  description: string;
+  status: PlaybookStepStatus;
+  output?: string;
+  startedAt?: number;
+  completedAt?: number;
+}
+
+export interface PlaybookSession {
+  id: string;
+  playbookId: string;
+  label: string;
+  steps: PlaybookStepState[];
+  gates: PlaybookGate[];
+  taskTemplates: PlaybookTaskTemplate[];
+  tools: string[];
+  verificationCriteria: string[];
+  currentStepIndex: number;
+  status: 'active' | 'completed' | 'aborted';
+  startedAt: number;
+  completedAt?: number;
+}
+
+export interface StartResult {
+  sessionId: string;
+  label: string;
+  totalSteps: number;
+  currentStep: PlaybookStepState;
+  tools: string[];
+  gates: PlaybookGate[];
+}
+
+export interface StepResult {
+  sessionId: string;
+  completedStep: PlaybookStepState;
+  nextStep: PlaybookStepState | null;
+  progress: { done: number; total: number };
+  isComplete: boolean;
+}
+
+export interface CompleteResult {
+  sessionId: string;
+  label: string;
+  status: 'completed' | 'aborted';
+  steps: PlaybookStepState[];
+  gatesPassed: boolean;
+  unsatisfiedGates: string[];
+  duration: number;
+}
+
+// =============================================================================
+// STEP PARSER
+// =============================================================================
+
+/**
+ * Parse step strings from a playbook's `steps` field into structured steps.
+ * Expects numbered steps like "1. Title\n   - detail\n   - detail"
+ */
+function parseSteps(stepsText: string): Array<{ title: string; description: string }> {
+  const lines = stepsText.split('\n');
+  const steps: Array<{ title: string; description: string }> = [];
+  let current: { title: string; lines: string[] } | null = null;
+
+  for (const line of lines) {
+    const stepMatch = line.match(/^\s*(\d+)\.\s+(.+)/);
+    if (stepMatch) {
+      if (current) {
+        steps.push({ title: current.title, description: current.lines.join('\n').trim() });
+      }
+      current = { title: stepMatch[2].trim(), lines: [] };
+    } else if (current && line.trim()) {
+      current.lines.push(line);
+    }
+  }
+  if (current) {
+    steps.push({ title: current.title, description: current.lines.join('\n').trim() });
+  }
+
+  return steps;
+}
+
+// =============================================================================
+// EXECUTOR
+// =============================================================================
+
+export class PlaybookExecutor {
+  private sessions = new Map<string, PlaybookSession>();
+
+  /**
+   * Start a playbook execution session.
+   * Accepts either a PlaybookDefinition or MergedPlaybook.
+   */
+  start(playbook: PlaybookDefinition | MergedPlaybook): StartResult {
+    const sessionId = `pbk-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    let label: string;
+    let playbookId: string;
+    let stepsText: string;
+    let gates: PlaybookGate[];
+    let taskTemplates: PlaybookTaskTemplate[];
+    let tools: string[];
+    let verificationCriteria: string[];
+
+    if ('mergedGates' in playbook) {
+      // MergedPlaybook
+      label = playbook.label;
+      playbookId = playbook.generic?.id ?? playbook.domain?.id ?? 'unknown';
+      stepsText = playbook.generic?.steps ?? playbook.domain?.steps ?? '';
+      gates = playbook.mergedGates;
+      taskTemplates = playbook.mergedTasks;
+      tools = playbook.mergedTools;
+      verificationCriteria = playbook.mergedVerification;
+    } else {
+      // PlaybookDefinition
+      label = playbook.title;
+      playbookId = playbook.id;
+      stepsText = playbook.steps;
+      gates = playbook.gates;
+      taskTemplates = playbook.taskTemplates;
+      tools = playbook.toolInjections;
+      verificationCriteria = playbook.verificationCriteria;
+    }
+
+    const parsed = parseSteps(stepsText);
+    if (parsed.length === 0) {
+      parsed.push({ title: label, description: 'Execute the playbook.' });
+    }
+
+    const steps: PlaybookStepState[] = parsed.map((s, i) => ({
+      index: i,
+      title: s.title,
+      description: s.description,
+      status: i === 0 ? 'active' : 'pending',
+    }));
+
+    const session: PlaybookSession = {
+      id: sessionId,
+      playbookId,
+      label,
+      steps,
+      gates,
+      taskTemplates,
+      tools,
+      verificationCriteria,
+      currentStepIndex: 0,
+      status: 'active',
+      startedAt: Date.now(),
+    };
+
+    steps[0].startedAt = Date.now();
+    this.sessions.set(sessionId, session);
+
+    return {
+      sessionId,
+      label,
+      totalSteps: steps.length,
+      currentStep: steps[0],
+      tools,
+      gates,
+    };
+  }
+
+  /**
+   * Advance to the next step. Marks the current step as done (or skipped).
+   */
+  step(
+    sessionId: string,
+    options?: { output?: string; skip?: boolean },
+  ): StepResult | { error: string } {
+    const session = this.sessions.get(sessionId);
+    if (!session) return { error: `Session not found: ${sessionId}` };
+    if (session.status !== 'active') return { error: `Session is ${session.status}, not active` };
+
+    const current = session.steps[session.currentStepIndex];
+    current.status = options?.skip ? 'skipped' : 'done';
+    current.output = options?.output;
+    current.completedAt = Date.now();
+
+    const nextIndex = session.currentStepIndex + 1;
+    const isComplete = nextIndex >= session.steps.length;
+
+    let nextStep: PlaybookStepState | null = null;
+    if (!isComplete) {
+      session.currentStepIndex = nextIndex;
+      session.steps[nextIndex].status = 'active';
+      session.steps[nextIndex].startedAt = Date.now();
+      nextStep = session.steps[nextIndex];
+    }
+
+    const done = session.steps.filter((s) => s.status === 'done' || s.status === 'skipped').length;
+
+    return {
+      sessionId,
+      completedStep: current,
+      nextStep,
+      progress: { done, total: session.steps.length },
+      isComplete,
+    };
+  }
+
+  /**
+   * Complete a playbook session. Validates gates and returns summary.
+   */
+  complete(
+    sessionId: string,
+    options?: { abort?: boolean; gateResults?: Record<string, boolean> },
+  ): CompleteResult | { error: string } {
+    const session = this.sessions.get(sessionId);
+    if (!session) return { error: `Session not found: ${sessionId}` };
+    if (session.status !== 'active') return { error: `Session is already ${session.status}` };
+
+    const abort = options?.abort ?? false;
+    const gateResults = options?.gateResults ?? {};
+
+    // Mark any remaining active/pending steps
+    for (const step of session.steps) {
+      if (step.status === 'active' || step.status === 'pending') {
+        step.status = abort ? 'skipped' : step.status;
+        if (step.status === 'active') {
+          step.status = 'done';
+          step.completedAt = Date.now();
+        }
+      }
+    }
+
+    // Validate gates
+    const completionGates = session.gates.filter((g) => g.phase === 'completion');
+    const unsatisfiedGates: string[] = [];
+    for (const gate of completionGates) {
+      if (!gateResults[gate.checkType]) {
+        unsatisfiedGates.push(`${gate.checkType}: ${gate.requirement}`);
+      }
+    }
+
+    session.status = abort ? 'aborted' : 'completed';
+    session.completedAt = Date.now();
+
+    const result: CompleteResult = {
+      sessionId,
+      label: session.label,
+      status: session.status,
+      steps: session.steps,
+      gatesPassed: unsatisfiedGates.length === 0,
+      unsatisfiedGates,
+      duration: session.completedAt - session.startedAt,
+    };
+
+    // Clean up after completion
+    this.sessions.delete(sessionId);
+
+    return result;
+  }
+
+  /**
+   * Get the current state of a session.
+   */
+  getSession(sessionId: string): PlaybookSession | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  /**
+   * List all active sessions.
+   */
+  listSessions(): Array<{ id: string; label: string; progress: string; startedAt: number }> {
+    return Array.from(this.sessions.values())
+      .filter((s) => s.status === 'active')
+      .map((s) => {
+        const done = s.steps.filter((st) => st.status === 'done' || st.status === 'skipped').length;
+        return {
+          id: s.id,
+          label: s.label,
+          progress: `${done}/${s.steps.length}`,
+          startedAt: s.startedAt,
+        };
+      });
+  }
+}

package/src/plugins/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Plugin System — Barrel Exports
+ */
+
+export {
+  pluginManifestSchema,
+  type PluginManifest,
+  type PluginStatus,
+  type PluginProvenance,
+  type LoadedPlugin,
+  type RegisteredPlugin,
+  type PluginFacadeBuilder,
+  type PluginContext,
+  type LoadResult,
+} from './types.js';
+
+export { loadPlugins, validateDependencies, sortByDependencies } from './plugin-loader.js';
+
+export { PluginRegistry } from './plugin-registry.js';