stageflow 0.25.0 → 0.30.0

package/dist/runstore/diskUsage.js

@@ -0,0 +1,214 @@
+import { readdir, stat, statfs } from "node:fs/promises";
+import path from "node:path";
+const BLOCK_SIZE = 512;
+const STATE_DB_NAMES = ["state.db", "state.db-wal", "state.db-shm"];
+export const DISK_WARN_LOG_PREFIX = "stageflow.disk_warn";
+let walkCallCount = 0;
+let freeSpaceReaderOverride = null;
+export function getDiskUsageWalkCallCount() {
+    return walkCallCount;
+}
+export function resetDiskUsageWalkCallCount() {
+    walkCallCount = 0;
+}
+export function setFreeSpaceReaderForTests(reader) {
+    freeSpaceReaderOverride = reader;
+}
+function allocatedBytes(st) {
+    return st.blocks * BLOCK_SIZE;
+}
+async function pathExists(target) {
+    try {
+        await stat(target);
+        return true;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+/** Walk `rootPath` summing `stat().blocks * 512`. Missing path → 0. */
+export async function diskUsageOf(rootPath) {
+    walkCallCount += 1;
+    if (!(await pathExists(rootPath)))
+        return 0;
+    let total = 0;
+    async function walk(current) {
+        let st;
+        try {
+            st = await stat(current);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return;
+            throw err;
+        }
+        total += allocatedBytes(st);
+        if (!st.isDirectory())
+            return;
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return;
+            throw err;
+        }
+        for (const entry of entries) {
+            await walk(path.join(current, entry.name));
+        }
+    }
+    await walk(rootPath);
+    return total;
+}
+export async function readFilesystemSize(rootPath) {
+    if (freeSpaceReaderOverride !== null) {
+        return freeSpaceReaderOverride(rootPath);
+    }
+    let target = path.resolve(rootPath);
+    for (;;) {
+        try {
+            const fsStats = await statfs(target);
+            const blockSize = fsStats.bsize;
+            return {
+                freeBytes: fsStats.bavail * blockSize,
+                totalBytes: fsStats.blocks * blockSize,
+            };
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+            const parent = path.dirname(target);
+            if (parent === target)
+                throw err;
+            target = parent;
+        }
+    }
+}
+async function usageOfMissingOk(target) {
+    try {
+        return await diskUsageOf(target);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return 0;
+        throw err;
+    }
+}
+async function stateDbBytes(durableRoot) {
+    let total = 0;
+    for (const name of STATE_DB_NAMES) {
+        const filePath = path.join(durableRoot, name);
+        try {
+            const st = await stat(filePath);
+            if (st.isFile()) {
+                walkCallCount += 1;
+                total += allocatedBytes(st);
+            }
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw err;
+        }
+    }
+    return total;
+}
+/** Category breakdown for the durable root, reusing `diskUsageOf` for directory trees. */
+export async function durableRootDiskBreakdown(durableRoot, options) {
+    const freeSpace = options?.freeSpace ?? readFilesystemSize;
+    const [runs_bytes, worktrees_bytes, repos_bytes, state_db_bytes, a2a_artifacts_bytes, cache_bytes, size] = await Promise.all([
+        usageOfMissingOk(path.join(durableRoot, "runs")),
+        usageOfMissingOk(path.join(durableRoot, "worktrees")),
+        usageOfMissingOk(path.join(durableRoot, "repos")),
+        stateDbBytes(durableRoot),
+        usageOfMissingOk(path.join(durableRoot, "a2a-artifacts")),
+        usageOfMissingOk(path.join(durableRoot, "cache")),
+        freeSpace(durableRoot),
+    ]);
+    return {
+        runs_bytes,
+        worktrees_bytes,
+        repos_bytes,
+        state_db_bytes,
+        a2a_artifacts_bytes,
+        cache_bytes,
+        free_bytes: size.freeBytes,
+    };
+}
+/**
+ * Parse `STAGEFLOW_DISK_WARN_BYTES` / floor-style env: integer bytes or `N%` of filesystem.
+ * Empty / unset / invalid → undefined (no threshold).
+ */
+export function parseDiskBytesThreshold(raw, filesystemTotalBytes) {
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed === "")
+        return undefined;
+    if (trimmed.endsWith("%")) {
+        const pct = Number.parseFloat(trimmed.slice(0, -1));
+        if (!Number.isFinite(pct) || pct < 0 || pct > 100)
+            return undefined;
+        if (!Number.isFinite(filesystemTotalBytes) || filesystemTotalBytes < 0) {
+            return undefined;
+        }
+        return Math.floor((filesystemTotalBytes * pct) / 100);
+    }
+    const n = Number.parseInt(trimmed, 10);
+    if (!Number.isFinite(n) || n < 0)
+        return undefined;
+    return n;
+}
+const DEFAULT_MIN_FREE_DISK_BYTES = 2 * 1024 * 1024 * 1024;
+/**
+ * Resolve `STAGEFLOW_MIN_FREE_DISK_BYTES`: bytes or `%` of filesystem.
+ * Unset / empty / invalid → `max(2 GiB, 10% of filesystemTotalBytes)`.
+ */
+export function resolveMinFreeDiskFloor(raw, filesystemTotalBytes) {
+    const parsed = parseDiskBytesThreshold(raw, filesystemTotalBytes);
+    if (parsed !== undefined)
+        return parsed;
+    const total = Number.isFinite(filesystemTotalBytes) && filesystemTotalBytes > 0
+        ? filesystemTotalBytes
+        : 0;
+    const tenPercent = Math.floor(total * 0.1);
+    return Math.max(DEFAULT_MIN_FREE_DISK_BYTES, tenPercent);
+}
+/**
+ * One named warning when free space is below `STAGEFLOW_DISK_WARN_BYTES`. Never throws.
+ * @returns true when a warning line was emitted
+ */
+export async function warnDurableRootDiskIfNeeded(durableRoot, options) {
+    try {
+        const env = options?.env ?? process.env;
+        const raw = env.STAGEFLOW_DISK_WARN_BYTES;
+        if (raw === undefined || raw.trim() === "")
+            return false;
+        const freeSpace = options?.freeSpace ?? readFilesystemSize;
+        const size = await freeSpace(durableRoot);
+        const threshold = parseDiskBytesThreshold(raw, size.totalBytes);
+        if (threshold === undefined)
+            return false;
+        if (size.freeBytes >= threshold)
+            return false;
+        const log = options?.log ?? ((line) => console.warn(line));
+        log(`${DISK_WARN_LOG_PREFIX}: durable root free space ${size.freeBytes} bytes is below threshold ${threshold} bytes (${raw.trim()}); run sf runs gc`);
+        return true;
+    }
+    catch (err) {
+        const log = options?.log ?? ((line) => console.warn(line));
+        log(`${DISK_WARN_LOG_PREFIX}: free-space measurement failed: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
+/** Measure one run workspace and persist `disk_bytes` / `disk_measured_at`. */
+export async function refreshRunDiskUsage(store, runId, options) {
+    const workspaceDir = store.getWorkspaceDir(runId);
+    const bytes = await diskUsageOf(workspaceDir);
+    const measuredAt = (options?.now ?? new Date()).toISOString();
+    await store.setRunDiskUsage(runId, bytes, measuredAt);
+    return bytes;
+}

package/dist/runstore/exportRunPayload.d.ts

@@ -0,0 +1,8 @@
+import { type RunProjection } from "../projection/projectRun.js";
+import type { RunDetail } from "./port.js";
+import { type RunManifest } from "./runManifest.js";
+export type RunExportPayload = RunProjection & {
+    run_manifest: RunManifest | null;
+};
+export declare function buildRunExportPayload(detail: RunDetail): RunExportPayload;
+export declare function runDetailWithRedactedManifest(detail: RunDetail): RunDetail;

package/dist/runstore/exportRunPayload.js

@@ -0,0 +1,23 @@
+import { projectRun } from "../projection/projectRun.js";
+import { redactRunManifestForRead, } from "./runManifest.js";
+import { getNamedSecrets } from "../logging/namedSecrets.js";
+export function buildRunExportPayload(detail) {
+    return {
+        ...projectRun(detail),
+        run_manifest: redactRunManifestForRead(detail.run_manifest, {
+            namedSecrets: getNamedSecrets(),
+        }),
+    };
+}
+export function runDetailWithRedactedManifest(detail) {
+    const run_manifest = redactRunManifestForRead(detail.run_manifest, {
+        namedSecrets: getNamedSecrets(),
+    });
+    if (run_manifest === null) {
+        if (detail.run_manifest === undefined)
+            return detail;
+        const { run_manifest: _drop, ...rest } = detail;
+        return rest;
+    }
+    return { ...detail, run_manifest };
+}

package/dist/runstore/normalizeCatalogPath.d.ts

@@ -1 +1,2 @@
 export declare function normalizeCatalogPath(raw: string): string;
+export declare function normalizeProjectRoot(raw: string): string;

package/dist/runstore/normalizeCatalogPath.js

@@ -1,4 +1,14 @@
+import { realpathSync } from "node:fs";
 import path from "node:path";
 export function normalizeCatalogPath(raw) {
     return path.resolve(raw);
 }
+export function normalizeProjectRoot(raw) {
+    const resolved = path.resolve(raw);
+    try {
+        return realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}

package/dist/runstore/paths.d.ts

@@ -1,6 +1,11 @@
 export declare function newRunId(): string;
 /** Root for factory state under a project: `<rootDir>/.stageflow`. */
 export declare function storeRootFor(rootDir: string): string;
+export declare function isGlobalStageflowHome(rootDir: string): boolean;
+/** Project store root or the durable home when `rootDir` is the global home. */
+export declare function resolveStoreRoot(rootDir: string): string;
+export declare const NESTED_GLOBAL_STORE_CONFLICT = "Cannot open the global store: flat state.db has no runs table while nested .stageflow/state.db still holds run data. Resolve the conflict manually.";
+export declare function flattenNestedGlobalStore(home: string): void;
 export declare function migrateLegacyStoreRoot(rootDir: string): void;
 export declare function runsDir(storeRoot: string): string;
 export declare function runWorkspaceDir(storeRoot: string, runId: string): string;

package/dist/runstore/paths.js

@@ -1,6 +1,8 @@
 import { randomBytes } from "node:crypto";
-import { readdirSync, renameSync, rmdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, renameSync, rmdirSync, statSync, } from "node:fs";
 import path from "node:path";
+import Database from "better-sqlite3";
+import { globalStageflowHome } from "../project/globalHome.js";
 import { guardStageId } from "./workspaceLayout.js";
 export function newRunId() {
     const stamp = new Date().toISOString().replace(/[:.]/g, "-");
@@ -10,6 +12,148 @@ export function newRunId() {
 export function storeRootFor(rootDir) {
     return path.join(rootDir, ".stageflow");
 }
+export function isGlobalStageflowHome(rootDir) {
+    return path.resolve(rootDir) === globalStageflowHome();
+}
+/** Project store root or the durable home when `rootDir` is the global home. */
+export function resolveStoreRoot(rootDir) {
+    if (isGlobalStageflowHome(rootDir)) {
+        return globalStageflowHome();
+    }
+    return storeRootFor(rootDir);
+}
+const NESTED_GLOBAL_STORE_DIR = ".stageflow";
+const STATE_DB_BASENAME = "state.db";
+const STATE_DB_SIDECARS = ["state.db-wal", "state.db-shm"];
+const NESTED_STORE_MOVE_DIRS = ["runs", "a2a-artifacts"];
+export const NESTED_GLOBAL_STORE_CONFLICT = "Cannot open the global store: flat state.db has no runs table while nested .stageflow/state.db still holds run data. Resolve the conflict manually.";
+function sqliteHasRunsTable(dbPath) {
+    if (!existsSync(dbPath)) {
+        return false;
+    }
+    let db;
+    try {
+        db = new Database(dbPath, { readonly: true, fileMustExist: true });
+        const row = db
+            .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'runs'")
+            .get();
+        return row !== undefined;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        db?.close();
+    }
+}
+function assertNoNestedGlobalStoreConflict(home) {
+    const flatDb = path.join(home, STATE_DB_BASENAME);
+    const nestedDb = path.join(home, NESTED_GLOBAL_STORE_DIR, STATE_DB_BASENAME);
+    if (!existsSync(flatDb) || !existsSync(nestedDb)) {
+        return;
+    }
+    if (!sqliteHasRunsTable(flatDb) && sqliteHasRunsTable(nestedDb)) {
+        throw new Error(NESTED_GLOBAL_STORE_CONFLICT);
+    }
+}
+function renameIfExists(from, to) {
+    if (!existsSync(from) || existsSync(to)) {
+        return;
+    }
+    renameSync(from, to);
+}
+function rollbackStateDbSet(home, nested, moved) {
+    for (const name of [...moved].reverse()) {
+        const from = path.join(home, name);
+        const to = path.join(nested, name);
+        if (existsSync(from) && !existsSync(to)) {
+            renameSync(from, to);
+        }
+    }
+}
+function moveStateDbSet(home, nested) {
+    const flatMain = path.join(home, STATE_DB_BASENAME);
+    const nestedMain = path.join(nested, STATE_DB_BASENAME);
+    const flatHasMain = existsSync(flatMain);
+    const nestedHasMain = existsSync(nestedMain);
+    if (flatHasMain && nestedHasMain) {
+        return;
+    }
+    if (flatHasMain && !nestedHasMain) {
+        for (const sidecar of STATE_DB_SIDECARS) {
+            renameIfExists(path.join(nested, sidecar), path.join(home, sidecar));
+        }
+        return;
+    }
+    if (!flatHasMain && nestedHasMain) {
+        const names = [STATE_DB_BASENAME, ...STATE_DB_SIDECARS];
+        const moved = [];
+        try {
+            for (const name of names) {
+                const from = path.join(nested, name);
+                const to = path.join(home, name);
+                if (existsSync(from) && !existsSync(to)) {
+                    renameSync(from, to);
+                    moved.push(name);
+                }
+            }
+        }
+        catch (err) {
+            rollbackStateDbSet(home, nested, moved);
+            throw err;
+        }
+    }
+}
+function flatStorePathAbsent(home, name) {
+    const target = path.join(home, name);
+    const state = directoryState(target);
+    return state === "missing";
+}
+function moveNestedStoreDirs(home, nested) {
+    for (const dirName of NESTED_STORE_MOVE_DIRS) {
+        const from = path.join(nested, dirName);
+        const to = path.join(home, dirName);
+        if (directoryState(from) === "missing") {
+            continue;
+        }
+        if (!flatStorePathAbsent(home, dirName)) {
+            continue;
+        }
+        renameSync(from, to);
+    }
+}
+function removeNestedGlobalStoreDirIfEmpty(home) {
+    const nested = path.join(home, NESTED_GLOBAL_STORE_DIR);
+    const state = directoryState(nested);
+    if (state === "missing" || state === "other") {
+        return;
+    }
+    const inventory = [
+        STATE_DB_BASENAME,
+        ...STATE_DB_SIDECARS,
+        ...NESTED_STORE_MOVE_DIRS,
+    ];
+    for (const name of inventory) {
+        if (existsSync(path.join(nested, name))) {
+            return;
+        }
+    }
+    if (state === "empty") {
+        rmdirSync(nested);
+    }
+}
+export function flattenNestedGlobalStore(home) {
+    const nested = path.join(home, NESTED_GLOBAL_STORE_DIR);
+    const nestedState = directoryState(nested);
+    if (nestedState === "missing" || nestedState === "other") {
+        assertNoNestedGlobalStoreConflict(home);
+        return;
+    }
+    assertNoNestedGlobalStoreConflict(home);
+    moveStateDbSet(home, nested);
+    moveNestedStoreDirs(home, nested);
+    removeNestedGlobalStoreDirIfEmpty(home);
+}
 function directoryState(dirPath) {
     try {
         const st = statSync(dirPath);