astrocode-workflow 0.4.0 → 0.4.2

package/dist/src/shared/paths.d.ts

@@ -0,0 +1,19 @@
+/** Normalize to posix-like separators for DB paths. */
+export declare function toPosix(p: string): string;
+export declare function ensureDir(p: string): void;
+export declare function joinRepo(root: string, ...parts: string[]): string;
+export type AstroPaths = {
+    repoRoot: string;
+    astroRoot: string;
+    dbPath: string;
+    runsDir: string;
+    specPath: string;
+    toolOutputDir: string;
+    configPathPreferred: string;
+    configPathFallback: string;
+};
+export declare function getAstroPaths(repoRoot: string, dbPathOverride?: string): AstroPaths;
+export declare function ensureAstroDirs(paths: AstroPaths): void;
+export declare function runDir(paths: AstroPaths, runId: string): string;
+export declare function stageDir(paths: AstroPaths, runId: string, stageKey: string): string;
+export declare function assertInsideAstro(repoRoot: string, filePath: string): void;

package/dist/src/shared/paths.js

@@ -0,0 +1,64 @@
+import path from "node:path";
+import fs from "node:fs";
+/** Normalize to posix-like separators for DB paths. */
+export function toPosix(p) {
+    return p.split(path.sep).join("/");
+}
+export function ensureDir(p) {
+    fs.mkdirSync(p, { recursive: true });
+}
+export function joinRepo(root, ...parts) {
+    return path.join(root, ...parts);
+}
+export function getAstroPaths(repoRoot, dbPathOverride) {
+    const astroRoot = joinRepo(repoRoot, ".astro");
+    const runsDir = joinRepo(repoRoot, ".astro", "runs");
+    const dbPath = dbPathOverride ? joinRepo(repoRoot, dbPathOverride) : joinRepo(repoRoot, ".astro", "astro.db");
+    const specPath = joinRepo(repoRoot, ".astro", "spec.md");
+    const toolOutputDir = joinRepo(repoRoot, ".astro", "tool_output");
+    return {
+        repoRoot,
+        astroRoot,
+        dbPath,
+        runsDir,
+        specPath,
+        toolOutputDir,
+        configPathPreferred: joinRepo(repoRoot, ".astro", "astrocode.config.jsonc"),
+        configPathFallback: joinRepo(repoRoot, "astrocode.config.jsonc"),
+    };
+}
+export function ensureAstroDirs(paths) {
+    ensureDir(paths.astroRoot);
+    ensureDir(paths.runsDir);
+    ensureDir(paths.toolOutputDir);
+}
+export function runDir(paths, runId) {
+    return joinRepo(paths.repoRoot, ".astro", "runs", runId);
+}
+export function stageDir(paths, runId, stageKey) {
+    return joinRepo(paths.repoRoot, ".astro", "runs", runId, stageKey);
+}
+export function assertInsideAstro(repoRoot, filePath) {
+    const absRepo = path.resolve(repoRoot);
+    const abs = path.resolve(filePath);
+    const astroRoot = path.resolve(path.join(repoRoot, ".astro"));
+    // Allow writing certain files in the repo root
+    const relPath = path.relative(repoRoot, filePath);
+    const allowedOutside = [
+        "stories.md",
+        "README.md",
+        "CHANGELOG.md",
+        "CONTRIBUTING.md",
+        "LICENSE",
+        ".gitignore"
+    ];
+    if (!abs.startsWith(astroRoot + path.sep) && abs !== astroRoot) {
+        // Check if it's an allowed file in repo root
+        if (!allowedOutside.includes(relPath)) {
+            throw new Error(`Refusing to write outside .astro: ${filePath} (relative: ${relPath}, astroRoot: ${astroRoot})`);
+        }
+    }
+    if (!abs.startsWith(absRepo + path.sep) && abs !== absRepo) {
+        throw new Error(`Refusing to write outside repo root: ${filePath}`);
+    }
+}

package/dist/src/shared/text.d.ts

@@ -0,0 +1,4 @@
+export declare function normalizeNewlines(s: string): string;
+export declare function clampLines(md: string, maxLines: number): string;
+export declare function clampChars(s: string, maxChars: number): string;
+export declare function stripCodeFences(md: string): string;

package/dist/src/shared/text.js

@@ -0,0 +1,19 @@
+export function normalizeNewlines(s) {
+    return s.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+export function clampLines(md, maxLines) {
+    const lines = normalizeNewlines(md).split("\n");
+    if (lines.length <= maxLines)
+        return md.trimEnd();
+    return lines.slice(0, maxLines).join("\n").trimEnd() + "\n…";
+}
+export function clampChars(s, maxChars) {
+    if (s.length <= maxChars)
+        return s;
+    return s.slice(0, maxChars) + "\n…(truncated)";
+}
+export function stripCodeFences(md) {
+    // Light helper: remove surrounding triple backticks if present
+    const m = md.match(/^```[a-zA-Z0-9_-]*\n([\s\S]*)\n```\s*$/);
+    return m ? m[1] : md;
+}

package/dist/src/shared/time.d.ts

@@ -0,0 +1 @@
+export declare function nowISO(): string;

package/dist/src/shared/time.js

@@ -0,0 +1,3 @@
+export function nowISO() {
+    return new Date().toISOString();
+}

package/dist/src/state/adapters/index.d.ts

@@ -0,0 +1,41 @@
+export interface DatabaseConnection {
+    pragma(sql: string): void;
+    exec(sql: string): void;
+    prepare(sql: string): Statement;
+    close(): void;
+}
+export interface Statement {
+    run(...params: any[]): {
+        changes: number;
+        lastInsertRowid: any;
+    };
+    get(...params: any[]): any;
+    all(...params: any[]): any[];
+}
+export interface DatabaseAdapter {
+    isAvailable(): boolean;
+    open(path: string, opts?: {
+        busyTimeoutMs?: number;
+    }): DatabaseConnection;
+}
+export declare class NullAdapter implements DatabaseAdapter {
+    isAvailable(): boolean;
+    open(path: string, opts?: {
+        busyTimeoutMs?: number;
+    }): DatabaseConnection;
+}
+export declare class BunSqliteAdapter implements DatabaseAdapter {
+    isAvailable(): boolean;
+    open(path: string, opts?: {
+        busyTimeoutMs?: number;
+    }): DatabaseConnection;
+}
+export declare class BetterSqliteAdapter implements DatabaseAdapter {
+    private Database;
+    constructor();
+    isAvailable(): boolean;
+    open(path: string, opts?: {
+        busyTimeoutMs?: number;
+    }): DatabaseConnection;
+}
+export declare function createDatabaseAdapter(): DatabaseAdapter;

package/dist/src/state/adapters/index.js

@@ -0,0 +1,115 @@
+// Null adapter for when no database driver is available
+export class NullAdapter {
+    isAvailable() {
+        return false;
+    }
+    open(path, opts) {
+        throw new Error("No SQLite driver available");
+    }
+}
+// Bun SQLite adapter - singleton pattern to avoid multiple initializations
+let bunDatabase = null;
+let bunDatabaseInitialized = false;
+function initializeBunDatabase() {
+    if (bunDatabaseInitialized) {
+        return bunDatabase;
+    }
+    bunDatabaseInitialized = true;
+    try {
+        const isBun = typeof globalThis.Bun !== 'undefined';
+        if (isBun) {
+            const { Database } = require('bun:sqlite');
+            bunDatabase = Database;
+        }
+    }
+    catch (e) {
+        // bun:sqlite not available
+    }
+    return bunDatabase;
+}
+// Bun SQLite adapter
+export class BunSqliteAdapter {
+    isAvailable() {
+        return !!initializeBunDatabase();
+    }
+    open(path, opts) {
+        const Database = initializeBunDatabase();
+        if (!Database) {
+            throw new Error("bun:sqlite not available");
+        }
+        const db = new Database(path);
+        // Configure database
+        if (opts?.busyTimeoutMs) {
+            db.exec(`PRAGMA busy_timeout = ${opts.busyTimeoutMs}`);
+        }
+        return {
+            pragma: (sql) => db.exec(`PRAGMA ${sql}`),
+            exec: (sql) => db.exec(sql),
+            prepare: (sql) => {
+                const stmt = db.prepare(sql);
+                return {
+                    run: (...params) => stmt.run(...params),
+                    get: (...params) => stmt.get(...params),
+                    all: (...params) => stmt.all(...params)
+                };
+            },
+            close: () => db.close()
+        };
+    }
+}
+// Better SQLite3 adapter
+export class BetterSqliteAdapter {
+    Database = null;
+    constructor() {
+        try {
+            this.Database = require("better-sqlite3");
+        }
+        catch (e) {
+            // better-sqlite3 not available
+        }
+    }
+    isAvailable() {
+        return !!this.Database;
+    }
+    open(path, opts) {
+        if (!this.Database) {
+            throw new Error("better-sqlite3 not available");
+        }
+        const db = new this.Database(path);
+        // Set busy timeout if specified
+        if (opts?.busyTimeoutMs) {
+            db.pragma(`busy_timeout = ${opts.busyTimeoutMs}`);
+        }
+        return {
+            pragma: (sql) => db.pragma(sql),
+            exec: (sql) => db.exec(sql),
+            prepare: (sql) => db.prepare(sql),
+            close: () => db.close()
+        };
+    }
+}
+// Factory function to create the appropriate adapter
+export function createDatabaseAdapter() {
+    const isBun = typeof globalThis.Bun !== 'undefined';
+    if (isBun) {
+        // Prefer bun:sqlite in Bun runtime
+        const bunAdapter = new BunSqliteAdapter();
+        if (bunAdapter.isAvailable())
+            return bunAdapter;
+        // Fallback to better-sqlite3
+        const betterAdapter = new BetterSqliteAdapter();
+        if (betterAdapter.isAvailable())
+            return betterAdapter;
+    }
+    else {
+        // Prefer better-sqlite3 in Node.js
+        const betterAdapter = new BetterSqliteAdapter();
+        if (betterAdapter.isAvailable())
+            return betterAdapter;
+        // Fallback to bun:sqlite (rare but possible)
+        const bunAdapter = new BunSqliteAdapter();
+        if (bunAdapter.isAvailable())
+            return bunAdapter;
+    }
+    return new NullAdapter();
+}

package/dist/src/state/db.d.ts

@@ -0,0 +1,16 @@
+import { DatabaseConnection } from "./adapters";
+export type SqliteDb = DatabaseConnection;
+export declare function openSqlite(dbPath: string, opts?: {
+    busyTimeoutMs?: number;
+}): SqliteDb;
+export declare function configurePragmas(db: SqliteDb, pragmas: Record<string, any>): void;
+/** BEGIN IMMEDIATE transaction helper (re-entrant). */
+export declare function withTx<T>(db: SqliteDb, fn: () => T, opts?: {
+    require?: boolean;
+    operation?: string;
+}): T;
+export declare function getSchemaVersion(db: SqliteDb): number;
+export declare function ensureSchema(db: SqliteDb, opts?: {
+    allowAutoMigrate?: boolean;
+    silent?: boolean;
+}): void;

package/dist/src/state/db.js

@@ -0,0 +1,225 @@
+// src/state/db.ts
+import fs from "node:fs";
+import path from "node:path";
+import { SCHEMA_SQL, SCHEMA_VERSION } from "./schema";
+import { nowISO } from "../shared/time";
+import { info, warn } from "../shared/log";
+import { createDatabaseAdapter } from "./adapters";
+import { recordTransaction } from "../shared/metrics";
+/** Ensure directory exists for a file path. */
+function ensureParentDir(filePath) {
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+}
+function tableExists(db, tableName) {
+    try {
+        const row = db
+            .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?")
+            .get(tableName);
+        return row?.name === tableName;
+    }
+    catch {
+        return false;
+    }
+}
+export function openSqlite(dbPath, opts) {
+    ensureParentDir(dbPath);
+    const adapter = createDatabaseAdapter();
+    if (!adapter.isAvailable()) {
+        throw new Error("No SQLite driver available (adapter unavailable).");
+    }
+    return adapter.open(dbPath, opts);
+}
+export function configurePragmas(db, pragmas) {
+    if (!pragmas || typeof pragmas !== "object")
+        return;
+    const known = new Set(["journal_mode", "synchronous", "foreign_keys", "temp_store"]);
+    for (const k of Object.keys(pragmas)) {
+        if (!known.has(k))
+            warn(`[Astrocode] Unknown pragma ignored: ${k}`);
+    }
+    if (pragmas.journal_mode)
+        db.pragma(`journal_mode = ${pragmas.journal_mode}`);
+    if (pragmas.synchronous)
+        db.pragma(`synchronous = ${pragmas.synchronous}`);
+    if (typeof pragmas.foreign_keys === "boolean")
+        db.pragma(`foreign_keys = ${pragmas.foreign_keys ? "ON" : "OFF"}`);
+    if (pragmas.temp_store)
+        db.pragma(`temp_store = ${pragmas.temp_store}`);
+}
+/**
+ * Re-entrant transaction helper.
+ *
+ * SQLite rejects BEGIN inside BEGIN. We use:
+ * - depth=0: BEGIN IMMEDIATE ... COMMIT/ROLLBACK
+ * - depth>0: SAVEPOINT sp_n ... RELEASE / ROLLBACK TO + RELEASE
+ *
+ * This allows callers to safely nest withTx across layers (tools -> workflow -> state machine)
+ * without "cannot start a transaction within a transaction".
+ */
+const TX_DEPTH = new WeakMap();
+function getDepth(db) {
+    return TX_DEPTH.get(db) ?? 0;
+}
+function setDepth(db, depth) {
+    if (depth <= 0)
+        TX_DEPTH.delete(db);
+    else
+        TX_DEPTH.set(db, depth);
+}
+function savepointName(depth) {
+    return `sp_${depth}`;
+}
+/** BEGIN IMMEDIATE transaction helper (re-entrant). */
+export function withTx(db, fn, opts) {
+    const adapter = createDatabaseAdapter();
+    const available = adapter.isAvailable();
+    if (!available) {
+        if (opts?.require)
+            throw new Error("Database adapter unavailable; transaction required.");
+        return fn();
+    }
+    const depth = getDepth(db);
+    const isNested = depth > 0;
+    const txRecorder = recordTransaction({ nestedDepth: depth, operation: opts?.operation });
+    if (depth === 0) {
+        const txStart = txRecorder.start();
+        db.exec("BEGIN IMMEDIATE");
+        setDepth(db, 1);
+        try {
+            const out = fn();
+            db.exec("COMMIT");
+            txRecorder.end(txStart, true);
+            return out;
+        }
+        catch (e) {
+            try {
+                db.exec("ROLLBACK");
+            }
+            catch {
+                // ignore
+            }
+            txRecorder.end(txStart, false);
+            throw e;
+        }
+        finally {
+            setDepth(db, 0);
+        }
+    }
+    // Nested: use SAVEPOINT
+    const nextDepth = depth + 1;
+    const sp = savepointName(nextDepth);
+    const txStart = txRecorder.start();
+    db.exec(`SAVEPOINT ${sp}`);
+    setDepth(db, nextDepth);
+    try {
+        const out = fn();
+        db.exec(`RELEASE SAVEPOINT ${sp}`);
+        txRecorder.end(txStart, true);
+        return out;
+    }
+    catch (e) {
+        try {
+            db.exec(`ROLLBACK TO SAVEPOINT ${sp}`);
+        }
+        catch {
+            // ignore
+        }
+        try {
+            db.exec(`RELEASE SAVEPOINT ${sp}`);
+        }
+        catch {
+            // ignore
+        }
+        txRecorder.end(txStart, false);
+        throw e;
+    }
+    finally {
+        setDepth(db, depth);
+    }
+}
+export function getSchemaVersion(db) {
+    try {
+        const row = db
+            .prepare("SELECT schema_version FROM repo_state WHERE id = 1")
+            .get();
+        return row?.schema_version ?? 0;
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (msg.includes("no such table"))
+            return 0;
+        throw new Error(`Failed to read schema version: ${msg}`);
+    }
+}
+function migrateStageRunsCreatedAt(db) {
+    // v2 requires stage_runs.created_at to be meaningful; never write ''.
+    // This migration is best-effort and does not assume constraint rewrite support.
+    try {
+        const cols = db.prepare("PRAGMA table_info(stage_runs)").all();
+        const hasCreatedAt = cols.some((c) => c.name === "created_at");
+        if (hasCreatedAt)
+            return;
+        // Add nullable column first (avoid poison defaults).
+        db.exec("ALTER TABLE stage_runs ADD COLUMN created_at TEXT");
+        const now = nowISO();
+        // Backfill using best available timestamp fields, falling back to now.
+        db.prepare(`
+      UPDATE stage_runs
+      SET created_at =
+        COALESCE(
+          NULLIF(created_at, ''),
+          NULLIF(updated_at, ''),
+          NULLIF(started_at, ''),
+          ?
+        )
+      WHERE created_at IS NULL OR created_at = ''
+    `).run(now);
+        info("[Astrocode] Added created_at column to stage_runs table (backfilled)");
+    }
+    catch (e) {
+        // Ignore: table may not exist yet, or migration already applied.
+    }
+}
+export function ensureSchema(db, opts) {
+    try {
+        return withTx(db, () => {
+            db.exec(SCHEMA_SQL);
+            // Deterministic assertions: if these fail, bootstrap is broken.
+            if (!tableExists(db, "repo_state"))
+                throw new Error("Schema missing required table repo_state after SCHEMA_SQL");
+            if (!tableExists(db, "story_keyseq"))
+                throw new Error("Schema missing required table story_keyseq after SCHEMA_SQL");
+            // Ensure required singleton rows exist.
+            db.prepare("INSERT OR IGNORE INTO story_keyseq (id, next_story_num) VALUES (1, 1)").run();
+            // Migrations for existing DBs.
+            migrateStageRunsCreatedAt(db);
+            const row = db
+                .prepare("SELECT schema_version FROM repo_state WHERE id = 1")
+                .get();
+            if (!row) {
+                const now = nowISO();
+                db.prepare("INSERT INTO repo_state (id, schema_version, created_at, updated_at) VALUES (1, ?, ?, ?)").run(SCHEMA_VERSION, now, now);
+                return;
+            }
+            const currentVersion = row.schema_version ?? 0;
+            if (currentVersion === SCHEMA_VERSION)
+                return;
+            if (currentVersion > SCHEMA_VERSION) {
+                // Newer schema - no action (policy enforcement elsewhere).
+                return;
+            }
+            if (currentVersion < SCHEMA_VERSION) {
+                if (opts?.allowAutoMigrate ?? true) {
+                    db.prepare("UPDATE repo_state SET schema_version = ?, updated_at = ? WHERE id = 1").run(SCHEMA_VERSION, nowISO());
+                }
+            }
+        }, { require: true });
+    }
+    catch (e) {
+        if (opts?.silent)
+            return;
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`Schema initialization failed: ${msg}`);
+    }
+}

package/dist/src/state/ids.d.ts

@@ -0,0 +1,8 @@
+export declare function newId(prefix: string): string;
+export declare function newRunId(): string;
+export declare function newStageRunId(): string;
+export declare function newArtifactId(): string;
+export declare function newToolRunId(): string;
+export declare function newEventId(): string;
+export declare function newSnapshotId(): string;
+export declare function newBatchId(): string;

package/dist/src/state/ids.js

@@ -0,0 +1,25 @@
+import { randomUUID } from "node:crypto";
+export function newId(prefix) {
+    return `${prefix}_${randomUUID()}`;
+}
+export function newRunId() {
+    return newId("run");
+}
+export function newStageRunId() {
+    return newId("stage");
+}
+export function newArtifactId() {
+    return newId("art");
+}
+export function newToolRunId() {
+    return newId("tool");
+}
+export function newEventId() {
+    return newId("evt");
+}
+export function newSnapshotId() {
+    return newId("snap");
+}
+export function newBatchId() {
+    return newId("batch");
+}

package/dist/src/state/repo-lock.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Acquire a repo-scoped lock with:
+ * - ✅ process-local caching + refcount (efficient repeated tool calls)
+ * - ✅ heartbeat lease + stale recovery
+ * - ✅ atomic create (`wx`) + portable replace fallback
+ * - ✅ dead PID eviction + stale eviction
+ * - ✅ no live takeover (even same session) to avoid concurrency stomps
+ * - ✅ ABA-safe release via lease_id fencing
+ * - ✅ exponential backoff + jitter to reduce FS churn
+ */
+export declare function acquireRepoLock(opts: {
+    lockPath: string;
+    repoRoot: string;
+    sessionId?: string;
+    owner?: string;
+    retryMs?: number;
+    pollMs?: number;
+    pollMaxMs?: number;
+    staleMs?: number;
+    heartbeatMs?: number;
+    minWriteMs?: number;
+}): Promise<{
+    release: () => void;
+}>;
+/**
+ * Helper wrapper: always releases lock.
+ */
+export declare function withRepoLock<T>(opts: {
+    lockPath: string;
+    repoRoot: string;
+    sessionId?: string;
+    owner?: string;
+    fn: () => Promise<T>;
+}): Promise<T>;
+/**
+ * Lock diagnostics and status information.
+ */
+export type LockStatus = {
+    exists: boolean;
+    path: string;
+    pid?: number;
+    pidAlive?: boolean;
+    instanceId?: string;
+    sessionId?: string;
+    owner?: string;
+    leaseId?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    ageMs?: number;
+    isStale?: boolean;
+    repoRoot?: string;
+    version?: number;
+};
+/**
+ * Get lock file status and diagnostics.
+ * Returns detailed information about the current lock state.
+ */
+export declare function getLockStatus(lockPath: string, staleMs?: number): LockStatus;
+/**
+ * Attempt to remove a lock file if it's safe to do so.
+ * Only removes locks with dead PIDs or stale timestamps.
+ * Returns true if lock was removed, false if lock is still held.
+ */
+export declare function tryRemoveStaleLock(lockPath: string, staleMs?: number): {
+    removed: boolean;
+    reason: string;
+};