@studio-foundation/engine 0.3.0-beta.1 → 0.3.0-beta.5

package/src/state/run-store.ts

@@ -1,362 +0,0 @@
-// Persistence layer for pipeline runs
-// Three implementations: InMemoryRunStore (tests), SQLiteRunStore (local), PgRunStore (postgres)
-
-import { createRequire } from 'node:module';
-import type { PipelineRun } from '@studio-foundation/contracts';
-
-export interface RunStore {
-  savePipelineRun(run: PipelineRun): void;
-  getPipelineRun(id: string): PipelineRun | null;
-  listPipelineRuns(options?: { limit?: number; status?: string }): PipelineRun[];
-  getLatestRun(pipelineName?: string): PipelineRun | null;
-  saveLogPath(runId: string, logPath: string): void;
-  getLogPath(runId: string): string | null;
-  close?(): void;
-}
-
-export interface AsyncRunStore {
-  savePipelineRun(run: PipelineRun): Promise<void>;
-  getPipelineRun(id: string): Promise<PipelineRun | null>;
-  listPipelineRuns(options?: { limit?: number; status?: string }): Promise<PipelineRun[]>;
-  getLatestRun(pipelineName?: string): Promise<PipelineRun | null>;
-  saveLogPath(runId: string, logPath: string): Promise<void>;
-  getLogPath(runId: string): Promise<string | null>;
-  close?(): Promise<void>;
-}
-
-export type AnyRunStore = RunStore | AsyncRunStore;
-
-// In-memory store for tests and simple usage
-export class InMemoryRunStore implements RunStore {
-  private runs: Map<string, PipelineRun> = new Map();
-  private logPaths: Map<string, string> = new Map();
-
-  savePipelineRun(run: PipelineRun): void {
-    this.runs.set(run.id, structuredClone(run));
-  }
-
-  getPipelineRun(id: string): PipelineRun | null {
-    const run = this.runs.get(id);
-    return run ? structuredClone(run) : null;
-  }
-
-  listPipelineRuns(options?: { limit?: number; status?: string }): PipelineRun[] {
-    let runs = Array.from(this.runs.values());
-
-    if (options?.status) {
-      runs = runs.filter(r => r.status === options.status);
-    }
-
-    // Sort by started_at descending
-    runs.sort((a, b) => b.started_at.localeCompare(a.started_at));
-
-    if (options?.limit) {
-      runs = runs.slice(0, options.limit);
-    }
-
-    return runs.map(r => structuredClone(r));
-  }
-
-  getLatestRun(pipelineName?: string): PipelineRun | null {
-    let runs = Array.from(this.runs.values());
-
-    if (pipelineName) {
-      runs = runs.filter(r => r.pipeline_name === pipelineName);
-    }
-
-    if (runs.length === 0) return null;
-
-    runs.sort((a, b) => b.started_at.localeCompare(a.started_at));
-    return structuredClone(runs[0]);
-  }
-
-  saveLogPath(runId: string, logPath: string): void {
-    this.logPaths.set(runId, logPath);
-  }
-
-  getLogPath(runId: string): string | null {
-    return this.logPaths.get(runId) ?? null;
-  }
-}
-
-// SQLite store for production persistence
-// Uses better-sqlite3 (synchronous, simple, no migrations)
-// Stores the entire PipelineRun as JSON in a single column — simple, queryable by status
-export class SQLiteRunStore implements RunStore {
-  private db: import('better-sqlite3').Database;
-
-  constructor(dbPath: string) {
-    const _require = createRequire(import.meta.url);
-    const Database = _require('better-sqlite3') as new (path: string) => import('better-sqlite3').Database;
-    this.db = new Database(dbPath);
-    this.db.pragma('journal_mode = WAL');
-    this.initSchema();
-  }
-
-  private initSchema(): void {
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS pipeline_runs (
-        id TEXT PRIMARY KEY,
-        pipeline_name TEXT NOT NULL,
-        status TEXT NOT NULL,
-        result TEXT NOT NULL,
-        started_at TEXT NOT NULL,
-        completed_at TEXT,
-        log_path TEXT,
-        created_at TEXT DEFAULT CURRENT_TIMESTAMP
-      );
-
-      CREATE INDEX IF NOT EXISTS idx_pipeline_runs_status
-        ON pipeline_runs(status);
-      CREATE INDEX IF NOT EXISTS idx_pipeline_runs_created
-        ON pipeline_runs(created_at DESC);
-    `);
-
-    // Migration: add log_path column to existing databases
-    try {
-      this.db.exec('ALTER TABLE pipeline_runs ADD COLUMN log_path TEXT');
-    } catch {
-      // Column already exists — ignore
-    }
-
-    // Migration: add parent_run_id column to existing databases
-    try {
-      this.db.exec('ALTER TABLE pipeline_runs ADD COLUMN parent_run_id TEXT');
-      this.db.exec('CREATE INDEX IF NOT EXISTS idx_pipeline_runs_parent ON pipeline_runs(parent_run_id)');
-    } catch {
-      // Column already exists — ignore
-    }
-  }
-
-  savePipelineRun(run: PipelineRun): void {
-    this.db.prepare(`
-      INSERT INTO pipeline_runs (id, pipeline_name, status, result, started_at, completed_at, parent_run_id)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
-      ON CONFLICT(id) DO UPDATE SET
-        pipeline_name = excluded.pipeline_name,
-        status        = excluded.status,
-        result        = excluded.result,
-        started_at    = excluded.started_at,
-        completed_at  = excluded.completed_at,
-        parent_run_id = excluded.parent_run_id
-    `).run(
-      run.id,
-      run.pipeline_name,
-      run.status,
-      JSON.stringify(run),
-      run.started_at,
-      run.completed_at ?? null,
-      run.parent_run_id ?? null,
-    );
-  }
-
-  getPipelineRun(id: string): PipelineRun | null {
-    const row = this.db.prepare('SELECT result FROM pipeline_runs WHERE id = ?').get(id) as
-      | { result: string }
-      | undefined;
-
-    if (!row) return null;
-    return JSON.parse(row.result) as PipelineRun;
-  }
-
-  listPipelineRuns(options?: { limit?: number; status?: string }): PipelineRun[] {
-    let sql = 'SELECT result FROM pipeline_runs';
-    const params: unknown[] = [];
-
-    if (options?.status) {
-      sql += ' WHERE status = ?';
-      params.push(options.status);
-    }
-
-    sql += ' ORDER BY created_at DESC';
-
-    if (options?.limit) {
-      sql += ' LIMIT ?';
-      params.push(options.limit);
-    }
-
-    const rows = this.db.prepare(sql).all(...params) as Array<{ result: string }>;
-    return rows.map(row => JSON.parse(row.result) as PipelineRun);
-  }
-
-  getLatestRun(pipelineName?: string): PipelineRun | null {
-    let sql = 'SELECT result FROM pipeline_runs';
-    const params: unknown[] = [];
-
-    if (pipelineName) {
-      sql += ' WHERE pipeline_name = ?';
-      params.push(pipelineName);
-    }
-
-    sql += ' ORDER BY created_at DESC LIMIT 1';
-
-    const row = this.db.prepare(sql).get(...params) as { result: string } | undefined;
-    if (!row) return null;
-    return JSON.parse(row.result) as PipelineRun;
-  }
-
-  saveLogPath(runId: string, logPath: string): void {
-    this.db.prepare('UPDATE pipeline_runs SET log_path = ? WHERE id = ?').run(logPath, runId);
-  }
-
-  getLogPath(runId: string): string | null {
-    const row = this.db.prepare('SELECT log_path FROM pipeline_runs WHERE id = ?').get(runId) as
-      | { log_path: string | null }
-      | undefined;
-    return row?.log_path ?? null;
-  }
-
-  close(): void {
-    this.db.close();
-  }
-}
-
-// PostgreSQL store — async implementation using raw pg (no Prisma)
-// Creates its own `studio_pipeline_runs` table on first use (like SQLiteRunStore does with initSchema).
-// Stores the entire PipelineRun as JSON in `result` — same pattern as SQLiteRunStore.
-// Uses table prefix `studio_` to avoid conflicts with the user app's own tables.
-export class PgRunStore implements AsyncRunStore {
-  private pool: import('pg').Pool;
-  private schemaReady: Promise<void> | null = null;
-
-  constructor(connectionString: string) {
-    const _require = createRequire(import.meta.url);
-    const { Pool } = _require('pg') as typeof import('pg');
-    this.pool = new Pool({ connectionString });
-  }
-
-  private ensureSchema(): Promise<void> {
-    if (!this.schemaReady) {
-      this.schemaReady = this.initSchema();
-    }
-    return this.schemaReady;
-  }
-
-  private async initSchema(): Promise<void> {
-    await this.pool.query(`
-      CREATE TABLE IF NOT EXISTS studio_pipeline_runs (
-        id            TEXT PRIMARY KEY,
-        pipeline_name TEXT NOT NULL,
-        status        TEXT NOT NULL,
-        result        TEXT NOT NULL,
-        started_at    TEXT NOT NULL,
-        completed_at  TEXT,
-        log_path      TEXT,
-        parent_run_id TEXT,
-        created_at    TIMESTAMPTZ DEFAULT NOW()
-      )
-    `);
-    await this.pool.query(`
-      CREATE INDEX IF NOT EXISTS idx_studio_pipeline_runs_status
-        ON studio_pipeline_runs(status)
-    `);
-    await this.pool.query(`
-      CREATE INDEX IF NOT EXISTS idx_studio_pipeline_runs_created
-        ON studio_pipeline_runs(created_at DESC)
-    `);
-    await this.pool.query(`
-      CREATE INDEX IF NOT EXISTS idx_studio_pipeline_runs_parent
-        ON studio_pipeline_runs(parent_run_id)
-    `);
-  }
-
-  async savePipelineRun(run: PipelineRun): Promise<void> {
-    await this.ensureSchema();
-    await this.pool.query(
-      `INSERT INTO studio_pipeline_runs
-         (id, pipeline_name, status, result, started_at, completed_at, parent_run_id)
-       VALUES ($1, $2, $3, $4, $5, $6, $7)
-       ON CONFLICT (id) DO UPDATE SET
-         pipeline_name = EXCLUDED.pipeline_name,
-         status        = EXCLUDED.status,
-         result        = EXCLUDED.result,
-         started_at    = EXCLUDED.started_at,
-         completed_at  = EXCLUDED.completed_at,
-         parent_run_id = EXCLUDED.parent_run_id`,
-      [
-        run.id,
-        run.pipeline_name,
-        run.status,
-        JSON.stringify(run),
-        run.started_at,
-        run.completed_at ?? null,
-        run.parent_run_id ?? null,
-      ]
-    );
-  }
-
-  async getPipelineRun(id: string): Promise<PipelineRun | null> {
-    await this.ensureSchema();
-    const res = await this.pool.query<{ result: string }>(
-      'SELECT result FROM studio_pipeline_runs WHERE id = $1',
-      [id]
-    );
-    if (res.rows.length === 0) return null;
-    return JSON.parse(res.rows[0].result) as PipelineRun;
-  }
-
-  async listPipelineRuns(options?: { limit?: number; status?: string }): Promise<PipelineRun[]> {
-    await this.ensureSchema();
-    const params: unknown[] = [];
-    let sql = 'SELECT result FROM studio_pipeline_runs';
-
-    if (options?.status) {
-      params.push(options.status);
-      sql += ` WHERE status = $${params.length}`;
-    }
-
-    sql += ' ORDER BY created_at DESC';
-
-    if (options?.limit) {
-      params.push(options.limit);
-      sql += ` LIMIT $${params.length}`;
-    }
-
-    const res = await this.pool.query<{ result: string }>(sql, params);
-    return res.rows.map((r) => JSON.parse(r.result) as PipelineRun);
-  }
-
-  async getLatestRun(pipelineName?: string): Promise<PipelineRun | null> {
-    await this.ensureSchema();
-    const params: unknown[] = [];
-    let sql = 'SELECT result FROM studio_pipeline_runs';
-
-    if (pipelineName) {
-      params.push(pipelineName);
-      sql += ` WHERE pipeline_name = $${params.length}`;
-    }
-
-    sql += ' ORDER BY created_at DESC LIMIT 1';
-
-    const res = await this.pool.query<{ result: string }>(sql, params);
-    if (res.rows.length === 0) return null;
-    return JSON.parse(res.rows[0].result) as PipelineRun;
-  }
-
-  async saveLogPath(runId: string, logPath: string): Promise<void> {
-    await this.ensureSchema();
-    await this.pool.query(
-      'UPDATE studio_pipeline_runs SET log_path = $1 WHERE id = $2',
-      [logPath, runId]
-    );
-  }
-
-  async getLogPath(runId: string): Promise<string | null> {
-    await this.ensureSchema();
-    const res = await this.pool.query<{ log_path: string | null }>(
-      'SELECT log_path FROM studio_pipeline_runs WHERE id = $1',
-      [runId]
-    );
-    return res.rows[0]?.log_path ?? null;
-  }
-
-  async close(): Promise<void> {
-    await this.pool.end();
-  }
-
-  /** Test-only: wipe table contents. Never call in production. */
-  async dangerouslyTruncateForTests(): Promise<void> {
-    await this.ensureSchema();
-    await this.pool.query('TRUNCATE TABLE studio_pipeline_runs');
-  }
-}

package/src/state/state-machine.ts

@@ -1,35 +0,0 @@
-// Stage lifecycle state machine
-// Keeps it simple: linear transitions, no DAG
-
-export type StageLifecycleState = 'pending' | 'running' | 'success' | 'failed' | 'skipped' | 'rejected' | 'cancelled';
-
-type StageEvent = 'start' | 'succeed' | 'fail' | 'skip' | 'reject' | 'cancel';
-
-const VALID_TRANSITIONS: Record<string, StageLifecycleState> = {
-  'pending:start': 'running',
-  'running:succeed': 'success',
-  'running:fail': 'failed',
-  'pending:skip': 'skipped',
-  'running:reject': 'rejected',
-  'running:cancel': 'cancelled',
-};
-
-export function isValidTransition(from: StageLifecycleState, to: StageLifecycleState): boolean {
-  for (const [key, target] of Object.entries(VALID_TRANSITIONS)) {
-    if (key.startsWith(`${from}:`) && target === to) {
-      return true;
-    }
-  }
-  return false;
-}
-
-export function transition(current: StageLifecycleState, event: StageEvent): StageLifecycleState {
-  const key = `${current}:${event}`;
-  const next = VALID_TRANSITIONS[key];
-
-  if (!next) {
-    throw new Error(`Invalid state transition: ${current} + ${event}`);
-  }
-
-  return next;
-}

package/src/state/status-derivation.ts

@@ -1,36 +0,0 @@
-// Derive stage status from ralph result
-// THIS IS THE CRITICAL FUNCTION
-//
-// In v7, each stage = 1 ralph call = 1 task.
-// This function maps ralph's result directly to stage status.
-//
-// This was the #1 bug in v6: stage status didn't match task status.
-// v7 fix: SIMPLE, DETERMINISTIC, NO MAGIC.
-
-import type { RalphResult } from '@studio-foundation/ralph';
-import type { StageStatus } from '@studio-foundation/contracts';
-
-/**
- * Derives stage status from ralph result.
- *
- * Rules (simple and exhaustive):
- * - ralph 'success' → stage 'success'
- * - ralph 'exhausted' → stage 'failed'
- * - anything else → error (should never happen)
- */
-export function deriveStageStatus(ralphResult: RalphResult<unknown>): StageStatus {
-  if (ralphResult.status === 'success') {
-    return 'success';
-  }
-
-  if (ralphResult.status === 'exhausted') {
-    return 'failed';
-  }
-
-  if (ralphResult.status === 'cancelled') {
-    return 'cancelled';
-  }
-
-  // Should never reach here if RalphResult types are exhaustive
-  throw new Error(`Unknown ralph status: ${JSON.stringify(ralphResult)}`);
-}

package/tests/context-pack-loader.test.ts

@@ -1,113 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import * as os from 'os';
-import { loadContextPacks } from '../src/pipeline/context-pack-loader.js';
-
-describe('loadContextPacks', () => {
-  let tmpDir: string;
-  let workspaceDir: string;
-
-  beforeEach(async () => {
-    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'studio-packs-'));
-    workspaceDir = path.join(tmpDir, 'workspace');
-    await fs.mkdir(path.join(tmpDir, 'context-packs'), { recursive: true });
-    await fs.mkdir(workspaceDir, { recursive: true });
-  });
-
-  afterEach(async () => {
-    await fs.rm(tmpDir, { recursive: true, force: true });
-  });
-
-  it('loads a pack with only inline sections', async () => {
-    await fs.writeFile(
-      path.join(tmpDir, 'context-packs', 'coding-standards.yaml'),
-      `name: Coding Standards\ndescription: Our standards\nversion: 1\ninline:\n  - title: "Naming"\n    content: "Use camelCase"\n  - title: "Errors"\n    content: "Always catch"`
-    );
-
-    const result = await loadContextPacks(['coding-standards'], tmpDir);
-
-    expect(result).toHaveLength(1);
-    expect(result[0].name).toBe('Coding Standards');
-    expect(result[0].description).toBe('Our standards');
-    expect(result[0].sections).toHaveLength(2);
-    expect(result[0].sections[0]).toEqual({ title: 'Naming', content: 'Use camelCase' });
-  });
-
-  it('loads a pack with file sections read from workspace', async () => {
-    await fs.writeFile(path.join(workspaceDir, 'STYLE.md'), '# Style Guide\nUse tabs.');
-    await fs.writeFile(
-      path.join(tmpDir, 'context-packs', 'style.yaml'),
-      `name: Style Guide\nversion: 1\nfiles:\n  - path: STYLE.md`
-    );
-
-    const result = await loadContextPacks(['style'], tmpDir, workspaceDir);
-
-    expect(result[0].sections).toHaveLength(1);
-    expect(result[0].sections[0].title).toBe('STYLE.md');
-    expect(result[0].sections[0].content).toContain('# Style Guide');
-  });
-
-  it('puts file sections before inline sections', async () => {
-    await fs.writeFile(path.join(workspaceDir, 'README.md'), 'Read me.');
-    await fs.writeFile(
-      path.join(tmpDir, 'context-packs', 'mixed.yaml'),
-      `name: Mixed\nversion: 1\nfiles:\n  - path: README.md\ninline:\n  - title: "Rule"\n    content: "Follow rules"`
-    );
-
-    const result = await loadContextPacks(['mixed'], tmpDir, workspaceDir);
-
-    expect(result[0].sections[0].title).toBe('README.md');
-    expect(result[0].sections[1].title).toBe('Rule');
-  });
-
-  it('throws a clear error when pack file does not exist', async () => {
-    await expect(
-      loadContextPacks(['nonexistent'], tmpDir)
-    ).rejects.toThrow(/context pack.*nonexistent.*not found/i);
-  });
-
-  it('throws a clear error when referenced workspace file does not exist', async () => {
-    await fs.writeFile(
-      path.join(tmpDir, 'context-packs', 'bad-pack.yaml'),
-      `name: Bad Pack\nversion: 1\nfiles:\n  - path: missing-file.md`
-    );
-
-    await expect(
-      loadContextPacks(['bad-pack'], tmpDir, workspaceDir)
-    ).rejects.toThrow(/file.*missing-file\.md.*not found/i);
-  });
-
-  it('throws when files[] referenced but workspacePath not provided', async () => {
-    await fs.writeFile(
-      path.join(tmpDir, 'context-packs', 'needs-ws.yaml'),
-      `name: Needs WS\nversion: 1\nfiles:\n  - path: some.md`
-    );
-
-    await expect(
-      loadContextPacks(['needs-ws'], tmpDir, undefined)
-    ).rejects.toThrow(/workspace.*not configured/i);
-  });
-
-  it('loads multiple packs preserving order', async () => {
-    await fs.writeFile(
-      path.join(tmpDir, 'context-packs', 'pack-a.yaml'),
-      `name: Pack A\nversion: 1\ninline:\n  - title: A\n    content: a`
-    );
-    await fs.writeFile(
-      path.join(tmpDir, 'context-packs', 'pack-b.yaml'),
-      `name: Pack B\nversion: 1\ninline:\n  - title: B\n    content: b`
-    );
-
-    const result = await loadContextPacks(['pack-a', 'pack-b'], tmpDir);
-
-    expect(result).toHaveLength(2);
-    expect(result[0].name).toBe('Pack A');
-    expect(result[1].name).toBe('Pack B');
-  });
-
-  it('returns empty array when packNames is empty', async () => {
-    const result = await loadContextPacks([], tmpDir);
-    expect(result).toEqual([]);
-  });
-});