@avocadostudio-ai/orchestrator-core 0.1.0

package/dist/state/sqlite-store-singleton.d.ts

@@ -0,0 +1,31 @@
+import type { Logger } from "../logger.ts";
+import { SqliteStore } from "./sqlite-store.ts";
+export declare function resolveDbFile(): string;
+export declare function resolveJsonMigrationTtlDays(): number;
+export declare function resolveBackupLimit(): number;
+export declare function resolveBackupIntervalHours(): number;
+export declare function getStore(): SqliteStore;
+/** Close & clear the singleton. Intended for tests + graceful shutdown. */
+export declare function resetStore(): void;
+/**
+ * Rename `<path>` to `<path>.migrated-<iso-ts>` so it won't be re-imported.
+ * Returns the new path, or null on failure.
+ */
+export declare function archiveMigratedJson(jsonPath: string): Promise<string | null>;
+/**
+ * Delete `.migrated-*` sibling files older than `ttlDays` in the same dir.
+ * Silent on failures — cleanup is opportunistic.
+ */
+export declare function sweepStaleMigrations(jsonPath: string, ttlDays: number, logger: Logger): Promise<number>;
+/**
+ * If `jsonPath` exists and is non-empty, read + parse it and return the raw
+ * payload. Caller is responsible for applying it into Maps + DB.
+ */
+export declare function readLegacyJson<T>(jsonPath: string): Promise<T | null>;
+/**
+ * Run a `VACUUM INTO '<dbPath>.backup-<ts>'` snapshot and rotate off the
+ * oldest copies once more than `limit` accumulate. Opens a fresh short-lived
+ * connection so the live handle's prepared statements stay untouched.
+ * Silent on failures — backups are best-effort.
+ */
+export declare function runSqliteBackup(dbPath: string, limit: number, logger: Logger): Promise<string | null>;

package/dist/state/sqlite-store-singleton.js

@@ -0,0 +1,170 @@
+import { existsSync } from "node:fs";
+import { rename, readFile, readdir, stat, unlink } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import { SqliteStore } from "./sqlite-store.js";
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+export function resolveDbFile() {
+    const explicit = process.env.ORCHESTRATOR_DB_FILE;
+    // Treat unset AND empty-string as "use the default" — matches how users
+    // get `.env.example` (which has `ORCHESTRATOR_DB_FILE=` empty). Ephemeral
+    // mode is still reachable via DEMO_MODE=1, NODE_ENV=test, or setting the
+    // env var to the literal ":memory:".
+    if (explicit && explicit.length > 0)
+        return explicit;
+    if (process.env.DEMO_MODE === "1")
+        return ":memory:";
+    if (process.env.NODE_ENV === "test")
+        return ":memory:";
+    return resolve(process.cwd(), "../../.data/orchestrator.db");
+}
+export function resolveJsonMigrationTtlDays() {
+    const raw = Number(process.env.ORCHESTRATOR_JSON_MIGRATION_TTL_DAYS ?? 14);
+    return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : 14;
+}
+export function resolveBackupLimit() {
+    const raw = Number(process.env.ORCHESTRATOR_DB_BACKUP_LIMIT ?? 14);
+    return Number.isFinite(raw) && raw >= 1 ? Math.floor(raw) : 14;
+}
+export function resolveBackupIntervalHours() {
+    const raw = Number(process.env.ORCHESTRATOR_DB_BACKUP_INTERVAL_HOURS ?? 24);
+    return Number.isFinite(raw) && raw >= 1 ? Math.floor(raw) : 24;
+}
+// ---------------------------------------------------------------------------
+// Singleton access
+// ---------------------------------------------------------------------------
+let store = null;
+export function getStore() {
+    if (!store) {
+        store = new SqliteStore({ file: resolveDbFile() });
+    }
+    return store;
+}
+/** Close & clear the singleton. Intended for tests + graceful shutdown. */
+export function resetStore() {
+    if (store) {
+        try {
+            store.close();
+        }
+        catch { /* ignore */ }
+    }
+    store = null;
+}
+// ---------------------------------------------------------------------------
+// JSON migration helpers
+// ---------------------------------------------------------------------------
+/**
+ * Rename `<path>` to `<path>.migrated-<iso-ts>` so it won't be re-imported.
+ * Returns the new path, or null on failure.
+ */
+export async function archiveMigratedJson(jsonPath) {
+    try {
+        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const dest = `${jsonPath}.migrated-${stamp}`;
+        await rename(jsonPath, dest);
+        return dest;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Delete `.migrated-*` sibling files older than `ttlDays` in the same dir.
+ * Silent on failures — cleanup is opportunistic.
+ */
+export async function sweepStaleMigrations(jsonPath, ttlDays, logger) {
+    if (ttlDays <= 0)
+        return 0;
+    const dir = dirname(jsonPath);
+    const prefix = `${basename(jsonPath)}.migrated-`;
+    let removed = 0;
+    try {
+        const entries = await readdir(dir);
+        const cutoff = Date.now() - ttlDays * 24 * 60 * 60 * 1000;
+        for (const name of entries) {
+            if (!name.startsWith(prefix))
+                continue;
+            const full = resolve(dir, name);
+            try {
+                const st = await stat(full);
+                if (st.mtimeMs < cutoff) {
+                    await unlink(full);
+                    removed++;
+                    logger.info({ file: full, ttlDays }, "Removed stale migrated state file");
+                }
+            }
+            catch { /* ignore individual failures */ }
+        }
+    }
+    catch { /* dir missing — nothing to do */ }
+    return removed;
+}
+/**
+ * If `jsonPath` exists and is non-empty, read + parse it and return the raw
+ * payload. Caller is responsible for applying it into Maps + DB.
+ */
+export async function readLegacyJson(jsonPath) {
+    if (!existsSync(jsonPath))
+        return null;
+    try {
+        const raw = await readFile(jsonPath, "utf8");
+        if (raw.trim().length === 0)
+            return null;
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// SQLite binary backups — periodic full-DB copies via `VACUUM INTO` so that
+// if the live .db ever corrupts (WAL torn write, bit rot, accidental rm)
+// we have a recent known-good snapshot. Uses the same rolling-limit
+// discipline the old JSON backup path had.
+// ---------------------------------------------------------------------------
+/**
+ * Run a `VACUUM INTO '<dbPath>.backup-<ts>'` snapshot and rotate off the
+ * oldest copies once more than `limit` accumulate. Opens a fresh short-lived
+ * connection so the live handle's prepared statements stay untouched.
+ * Silent on failures — backups are best-effort.
+ */
+export async function runSqliteBackup(dbPath, limit, logger) {
+    if (dbPath === ":memory:")
+        return null;
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const backupPath = `${dbPath}.backup-${stamp}`;
+    try {
+        // Short-lived connection to the live DB, just to issue VACUUM INTO.
+        // better-sqlite3 is loaded lazily by the singleton; import locally to
+        // avoid a top-level dependency cycle with SqliteStore.
+        const { default: Database } = await import("better-sqlite3");
+        const db = new Database(dbPath, { readonly: false });
+        try {
+            db.prepare(`VACUUM INTO ?`).run(backupPath);
+        }
+        finally {
+            db.close();
+        }
+        logger.info({ file: backupPath }, "Wrote orchestrator SQLite backup");
+    }
+    catch (err) {
+        logger.error({ err, backupPath }, "Failed to write SQLite backup");
+        return null;
+    }
+    // Rotate — keep the newest `limit` by filename (ISO-timestamped, so
+    // lexical order == chronological order).
+    try {
+        const dir = dirname(dbPath);
+        const prefix = `${basename(dbPath)}.backup-`;
+        const entries = await readdir(dir);
+        const backups = entries.filter((n) => n.startsWith(prefix)).sort();
+        if (backups.length > limit) {
+            const toDelete = backups.slice(0, backups.length - limit);
+            await Promise.all(toDelete.map((name) => unlink(resolve(dir, name)).catch(() => { })));
+            logger.info({ removed: toDelete.length, kept: limit }, "Rotated old SQLite backups");
+        }
+    }
+    catch { /* ignore rotation failures */ }
+    return backupPath;
+}

package/dist/state/sqlite-store.d.ts

@@ -0,0 +1,135 @@
+import type { Database as BetterSqliteDatabase } from "better-sqlite3";
+import type { PageDoc, Operation, SiteConfig } from "@avocadostudio-ai/shared";
+export declare const HISTORY_DEPTH_CAP = 50;
+export declare const VERSION_LOG_CAP = 100;
+export declare const RECENT_EDITS_CAP = 10;
+export declare const CHAT_HISTORY_CAP = 6;
+export declare const PUBLISH_LOG_CAP = 200;
+export type PageKind = "draft" | "published";
+export type HistoryDirection = "undo" | "redo";
+export type RecentEditEntry = {
+    slug: string;
+    summary: string;
+    ops: Operation[];
+    at: string;
+};
+export type VersionLogEntry = {
+    version: number;
+    slug: string;
+    summary: string;
+    opTypes: string[];
+    opCount: number;
+    at: string;
+    source: "chat" | "direct" | "undo" | "redo" | "bootstrap" | "restore";
+    snapshot?: PageDoc | null;
+};
+export type ChatMessage = {
+    role: "user" | "assistant";
+    content: string;
+};
+export type IssueTouchedRow = {
+    slugs: string[];
+    updatedAt: string;
+};
+export type PublishLogStatus = "triggered" | "success" | "failed";
+export type PublishLogActor = {
+    kind: "user" | "agent" | "ci";
+    id?: string;
+};
+export type PublishLogDiffSummary = {
+    added: number;
+    removed: number;
+    changed: number;
+};
+export type PublishLogEntry = {
+    /** Stable id (UUID). Lets async status updates target a specific row. */
+    id: string;
+    /** Scoped session key (matches version_log keying). */
+    session: string;
+    siteId: string;
+    /** Publish target name, e.g. "site-contract" | "git" | "deploy-hook" | plugin. */
+    target: string;
+    status: PublishLogStatus;
+    /** ISO timestamp when the row was first inserted. */
+    at: string;
+    /** ISO timestamp of the most recent status mutation. */
+    updatedAt: string;
+    /** Human-readable summary, e.g. "Published Home, Pricing". */
+    summary: string;
+    pageCount: number;
+    /** Slugs included in this publish (small list — useful for the panel). */
+    slugs: string[];
+    /** Short commit SHA, when the target produced one. */
+    commit?: string;
+    deploymentId?: string;
+    deploymentUrl?: string;
+    /** Provider-specific deep link (e.g. Vercel inspect URL). */
+    inspectUrl?: string;
+    /** Present when status === "failed". */
+    error?: string;
+    /**
+     * Forward-compatibility slots — reserved but unpopulated today. They live in
+     * the JSON blob so adding values does not require a schema migration.
+     */
+    actor?: PublishLogActor;
+    diffSummary?: PublishLogDiffSummary;
+};
+export type SqliteStoreOptions = {
+    /** File path. Use ":memory:" for an ephemeral DB. */
+    file: string;
+    /** Disable WAL (e.g. in tests). Defaults to true for file-backed DBs. */
+    wal?: boolean;
+    /** Optional logger for one-shot messages (open/close/migrate). */
+    onLog?: (msg: string) => void;
+};
+export declare class SqliteStore {
+    readonly db: BetterSqliteDatabase;
+    private readonly stmt;
+    constructor(options: SqliteStoreOptions);
+    private ensureSchemaVersion;
+    private prepareAll;
+    setPage(session: string, page: PageDoc, kind?: PageKind): void;
+    getPage(session: string, slug: string, kind?: PageKind): PageDoc | null;
+    removePage(session: string, slug: string, kind?: PageKind): void;
+    listPages(session: string, kind?: PageKind): PageDoc[];
+    listDraftSessions(): string[];
+    pushHistory(session: string, slug: string, direction: HistoryDirection, snapshot: PageDoc | null): void;
+    popHistory(session: string, slug: string, direction: HistoryDirection): PageDoc | null | undefined;
+    clearHistory(session: string, slug: string, direction: HistoryDirection): void;
+    listHistory(session: string, slug: string, direction: HistoryDirection): (PageDoc | null)[];
+    getVersion(session: string): number;
+    setVersion(session: string, version: number): void;
+    bumpVersion(session: string): number;
+    pushVersionLog(session: string, entry: VersionLogEntry): void;
+    listVersionLog(session: string, slug?: string, limit?: number): VersionLogEntry[];
+    pushRecentEdit(session: string, entry: RecentEditEntry): void;
+    listRecentEdits(session: string): RecentEditEntry[];
+    pushChatMessage(session: string, role: ChatMessage["role"], content: string): void;
+    listChatHistory(session: string): ChatMessage[];
+    setSiteConfig(session: string, config: SiteConfig): void;
+    getSiteConfig(session: string): SiteConfig | null;
+    listSiteConfigs(): Array<{
+        session: string;
+        config: SiteConfig;
+    }>;
+    setIssueTouched(issueKey: string, row: IssueTouchedRow, cap?: number): void;
+    getIssueTouched(issueKey: string): IssueTouchedRow | null;
+    listIssueTouched(): Array<{
+        issueKey: string;
+        row: IssueTouchedRow;
+    }>;
+    pushPublishLog(entry: PublishLogEntry): void;
+    getPublishLogById(id: string): PublishLogEntry | null;
+    getPublishLogByDeploymentId(session: string, deploymentId: string): PublishLogEntry | null;
+    getMostRecentTriggeredPublishLog(session: string): PublishLogEntry | null;
+    /**
+     * Patch an existing publish-log row. Merges `patch` into the stored JSON,
+     * bumps `updatedAt`, and updates the hoisted `status` column. Returns the
+     * full updated entry, or null if the id was not found.
+     */
+    updatePublishLogById(id: string, patch: Partial<Omit<PublishLogEntry, "id" | "session" | "at">>): PublishLogEntry | null;
+    listPublishLog(session: string, limit?: number): PublishLogEntry[];
+    listPublishLogSessions(): string[];
+    transaction<T>(fn: () => T): T;
+    close(): void;
+}