stageflow 0.25.0 → 0.30.0

package/dist/preflight/toolchain.d.ts

@@ -0,0 +1,45 @@
+import type { ToolRequirement } from "../config/toolRequires.js";
+export declare const DEFAULT_TOOLCHAIN_MANIFEST_PATH = "/etc/stageflow/toolchain.json";
+export declare const TOOLCHAIN_MANIFEST_ENV = "STAGEFLOW_TOOLCHAIN_MANIFEST";
+export type ToolchainManifestEntry = {
+    path: string;
+    version: string;
+};
+export type ToolchainManifest = {
+    tools: Record<string, ToolchainManifestEntry>;
+};
+export type ToolchainCheckStatus = "ok" | "missing_tool" | "tool_version_mismatch" | "unknown_version";
+export type ToolchainCheck = {
+    tool: string;
+    required?: string;
+    found?: string;
+    path?: string;
+    status: ToolchainCheckStatus;
+    origin: "manifest" | "path" | "none";
+};
+export type ToolchainCheckResult = {
+    ok: boolean;
+    checks: ToolchainCheck[];
+};
+export type ToolchainHealthMap = Record<string, string>;
+export declare function resolveToolchainManifestPath(env?: NodeJS.ProcessEnv): string;
+export declare function loadToolchainManifest(manifestPath?: string): ToolchainManifest | undefined;
+/** Build the curated stage env PATH (Slot 6 allowlist) for preflight checks. */
+export declare function curatedStageEnv(hostEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function toolchainHealthMap(options?: {
+    manifest?: ToolchainManifest;
+    env?: NodeJS.ProcessEnv;
+}): ToolchainHealthMap;
+export type CheckToolchainOptions = {
+    /** Injected manifest (tests); when omitted, load from disk. */
+    manifest?: ToolchainManifest | null;
+    env?: NodeJS.ProcessEnv;
+    /** When true, unknown_version is a failing status. */
+    strict?: boolean;
+    /** Fail start/doctor when mismatch/missing; unknown_version fails only if strict. */
+    failOnUnknownVersion?: boolean;
+};
+export declare function checkToolchainRequirements(requirements: readonly ToolRequirement[], options?: CheckToolchainOptions): ToolchainCheckResult;
+export declare function firstFailingToolchainCode(result: ToolchainCheckResult, options?: {
+    strict?: boolean;
+}): "missing_tool" | "tool_version_mismatch" | "unknown_version" | undefined;

package/dist/preflight/toolchain.js

@@ -0,0 +1,219 @@
+import { accessSync, constants, existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import semver from "semver";
+import { resolveCommandOnPath } from "./mcpCommands.js";
+import { buildStageEnvironment } from "../runtime/stageEnvironment.js";
+export const DEFAULT_TOOLCHAIN_MANIFEST_PATH = "/etc/stageflow/toolchain.json";
+export const TOOLCHAIN_MANIFEST_ENV = "STAGEFLOW_TOOLCHAIN_MANIFEST";
+export function resolveToolchainManifestPath(env = process.env) {
+    const fromEnv = env[TOOLCHAIN_MANIFEST_ENV]?.trim();
+    if (fromEnv)
+        return fromEnv;
+    return DEFAULT_TOOLCHAIN_MANIFEST_PATH;
+}
+export function loadToolchainManifest(manifestPath = resolveToolchainManifestPath()) {
+    if (!existsSync(manifestPath))
+        return undefined;
+    try {
+        const raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+        if (typeof raw !== "object" ||
+            raw === null ||
+            Array.isArray(raw) ||
+            typeof raw.tools !== "object" ||
+            raw.tools === null ||
+            Array.isArray(raw.tools)) {
+            return undefined;
+        }
+        const tools = {};
+        for (const [name, entry] of Object.entries(raw.tools)) {
+            if (typeof entry !== "object" ||
+                entry === null ||
+                Array.isArray(entry) ||
+                typeof entry.path !== "string" ||
+                typeof entry.version !== "string") {
+                continue;
+            }
+            tools[name] = {
+                path: entry.path,
+                version: entry.version,
+            };
+        }
+        return { tools };
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseVersionFromOutput(output) {
+    const coerced = semver.coerce(output, { loose: true });
+    return coerced?.version;
+}
+function probeToolVersion(commandPath, env) {
+    const result = spawnSync(commandPath, ["--version"], {
+        encoding: "utf8",
+        env,
+        timeout: 5_000,
+    });
+    const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`.trim();
+    if (!output)
+        return { parsable: false };
+    const version = parseVersionFromOutput(output);
+    if (version === undefined)
+        return { parsable: false };
+    return { version, parsable: true };
+}
+function resolveToolFromPath(tool, env) {
+    const resolved = resolveCommandOnPath(tool, env);
+    if (resolved === undefined)
+        return undefined;
+    try {
+        accessSync(resolved, constants.X_OK);
+    }
+    catch {
+        return undefined;
+    }
+    const probed = probeToolVersion(resolved, env);
+    return { path: resolved, version: probed.version, parsable: probed.parsable };
+}
+/** Build the curated stage env PATH (Slot 6 allowlist) for preflight checks. */
+export function curatedStageEnv(hostEnv = process.env) {
+    const built = buildStageEnvironment({ hostEnv });
+    return { ...built.env };
+}
+export function toolchainHealthMap(options) {
+    const env = options?.env ?? process.env;
+    const manifest = options?.manifest ?? loadToolchainManifest(resolveToolchainManifestPath(env));
+    const map = {};
+    if (manifest) {
+        for (const [name, entry] of Object.entries(manifest.tools)) {
+            map[name] = entry.version;
+        }
+    }
+    for (const name of ["node", "git", "bash"]) {
+        if (map[name] !== undefined)
+            continue;
+        if (name === "node") {
+            map.node = process.versions.node;
+            continue;
+        }
+        const live = resolveToolFromPath(name, curatedStageEnv(env));
+        if (live?.version)
+            map[name] = live.version;
+    }
+    return map;
+}
+export function checkToolchainRequirements(requirements, options = {}) {
+    const hostEnv = options.env ?? process.env;
+    const stageEnv = curatedStageEnv(hostEnv);
+    const failOnUnknown = options.failOnUnknownVersion === true || options.strict === true;
+    let manifest;
+    if (options.manifest === null) {
+        manifest = undefined;
+    }
+    else if (options.manifest !== undefined) {
+        manifest = options.manifest;
+    }
+    else {
+        manifest = loadToolchainManifest(resolveToolchainManifestPath(hostEnv));
+    }
+    const checks = [];
+    for (const req of requirements) {
+        const fromManifest = manifest?.tools[req.tool];
+        let foundPath;
+        let foundVersion;
+        let origin = "none";
+        let parsable = false;
+        if (fromManifest) {
+            foundPath = fromManifest.path;
+            foundVersion = fromManifest.version;
+            origin = "manifest";
+            parsable = Boolean(semver.valid(fromManifest.version));
+            if (!parsable) {
+                const coerced = semver.coerce(fromManifest.version, { loose: true });
+                if (coerced) {
+                    foundVersion = coerced.version;
+                    parsable = true;
+                }
+            }
+        }
+        else {
+            const live = resolveToolFromPath(req.tool, stageEnv);
+            if (live) {
+                foundPath = live.path;
+                foundVersion = live.version;
+                origin = "path";
+                parsable = live.parsable;
+            }
+        }
+        if (foundPath === undefined) {
+            checks.push({
+                tool: req.tool,
+                required: req.version,
+                status: "missing_tool",
+                origin: "none",
+            });
+            continue;
+        }
+        if (req.version === undefined) {
+            checks.push({
+                tool: req.tool,
+                found: foundVersion,
+                path: foundPath,
+                status: "ok",
+                origin,
+            });
+            continue;
+        }
+        if (!parsable || foundVersion === undefined) {
+            checks.push({
+                tool: req.tool,
+                required: req.version,
+                found: foundVersion,
+                path: foundPath,
+                status: "unknown_version",
+                origin,
+            });
+            continue;
+        }
+        if (!semver.satisfies(foundVersion, req.version)) {
+            checks.push({
+                tool: req.tool,
+                required: req.version,
+                found: foundVersion,
+                path: foundPath,
+                status: "tool_version_mismatch",
+                origin,
+            });
+            continue;
+        }
+        checks.push({
+            tool: req.tool,
+            required: req.version,
+            found: foundVersion,
+            path: foundPath,
+            status: "ok",
+            origin,
+        });
+    }
+    const ok = !checks.some((c) => {
+        if (c.status === "missing_tool" || c.status === "tool_version_mismatch") {
+            return true;
+        }
+        if (c.status === "unknown_version")
+            return failOnUnknown;
+        return false;
+    });
+    return { ok, checks };
+}
+export function firstFailingToolchainCode(result, options = {}) {
+    for (const check of result.checks) {
+        if (check.status === "missing_tool")
+            return "missing_tool";
+        if (check.status === "tool_version_mismatch")
+            return "tool_version_mismatch";
+        if (check.status === "unknown_version" && options.strict) {
+            return "unknown_version";
+        }
+    }
+    return undefined;
+}

package/dist/project/findManifestRoot.d.ts

@@ -0,0 +1,3 @@
+/** Walk up from `startDir` for the nearest `stageflow.yaml`, independent of git. */
+export declare function findManifestRoot(startDir: string): string | null;
+export declare function clearFindManifestRootCacheForTests(): void;

package/dist/project/findManifestRoot.js

@@ -0,0 +1,35 @@
+import { existsSync, realpathSync } from "node:fs";
+import path from "node:path";
+const cache = new Map();
+function normalizeRoot(dir) {
+    try {
+        return realpathSync(path.resolve(dir));
+    }
+    catch {
+        return path.resolve(dir);
+    }
+}
+/** Walk up from `startDir` for the nearest `stageflow.yaml`, independent of git. */
+export function findManifestRoot(startDir) {
+    const normalized = path.resolve(startDir);
+    if (cache.has(normalized)) {
+        return cache.get(normalized) ?? null;
+    }
+    let dir = normalized;
+    let result = null;
+    for (;;) {
+        if (existsSync(path.join(dir, "stageflow.yaml"))) {
+            result = normalizeRoot(dir);
+            break;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    cache.set(normalized, result);
+    return result;
+}
+export function clearFindManifestRootCacheForTests() {
+    cache.clear();
+}

package/dist/project/findProjectRoot.js

@@ -1,6 +1,6 @@
 import { existsSync, realpathSync } from "node:fs";
-import { execFileSync } from "node:child_process";
 import path from "node:path";
+import { runGitSync } from "../git/exec.js";
 const cache = new Map();
 function normalizeRoot(dir) {
     try {
@@ -17,10 +17,9 @@ export function findProjectRoot(startDir) {
     }
     let result = null;
     try {
-        const stdout = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+        const { stdout } = runGitSync({
             cwd: normalized,
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
+            args: ["rev-parse", "--show-toplevel"],
         });
         const trimmed = stdout.trim();
         if (trimmed.length > 0) {

package/dist/project/globalHome.d.ts

@@ -1,2 +1,9 @@
+export type StageflowHomeErrorCode = "stageflow_home_not_writable";
+export declare class StageflowHomeError extends Error {
+    readonly code: StageflowHomeErrorCode;
+    constructor(message: string, code: StageflowHomeErrorCode);
+}
+export declare function resetGlobalStageflowHomeForTests(): void;
 export declare function globalStageflowHome(): string;
+export declare function assertStageflowHomeWritable(): void;
 export declare function ensureGlobalHome(): string;

package/dist/project/globalHome.js

@@ -1,10 +1,71 @@
-import { chmodSync, mkdirSync } from "node:fs";
+import { accessSync, chmodSync, constants, mkdirSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+export class StageflowHomeError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "StageflowHomeError";
+        this.code = code;
+    }
+}
+let memoizedHome;
+export function resetGlobalStageflowHomeForTests() {
+    memoizedHome = undefined;
+}
+function resolveStageflowHomeFromEnv() {
+    const raw = process.env.STAGEFLOW_HOME?.trim();
+    if (!raw) {
+        return path.join(os.homedir(), ".stageflow");
+    }
+    if (path.isAbsolute(raw)) {
+        return path.resolve(raw);
+    }
+    return path.resolve(process.cwd(), raw);
+}
 export function globalStageflowHome() {
-    return path.join(os.homedir(), ".stageflow");
+    if (memoizedHome === undefined) {
+        memoizedHome = resolveStageflowHomeFromEnv();
+        process.env.STAGEFLOW_HOME = memoizedHome;
+    }
+    return memoizedHome;
+}
+function stageflowHomeNotWritableMessage(resolvedPath) {
+    const uid = process.getuid?.() ?? 0;
+    const gid = process.getgid?.() ?? 0;
+    return `STAGEFLOW_HOME is not writable (${resolvedPath}). Running as uid=${uid} gid=${gid}. Try: sudo chown -R ${uid}:${gid} ${resolvedPath}`;
+}
+function isStageflowHomeWritable(home) {
+    try {
+        accessSync(home, constants.W_OK);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            const parent = path.dirname(home);
+            if (parent === home) {
+                return false;
+            }
+            try {
+                accessSync(parent, constants.W_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        return false;
+    }
+}
+export function assertStageflowHomeWritable() {
+    const home = globalStageflowHome();
+    if (!isStageflowHomeWritable(home)) {
+        throw new StageflowHomeError(stageflowHomeNotWritableMessage(home), "stageflow_home_not_writable");
+    }
 }
 export function ensureGlobalHome() {
+    assertStageflowHomeWritable();
     const globalHome = globalStageflowHome();
     mkdirSync(globalHome, { recursive: true });
     const agentDir = path.join(globalHome, "agent");

package/dist/project/resolveProjectContext.js

@@ -1,11 +1,11 @@
 import os from "node:os";
 import path from "node:path";
 import { findProjectRoot } from "./findProjectRoot.js";
-import { ensureGlobalHome, globalStageflowHome } from "./globalHome.js";
+import { globalStageflowHome } from "./globalHome.js";
 export function resolveProjectContext(invocationCwd) {
     const resolvedInvocation = path.resolve(invocationCwd);
     const gitRoot = findProjectRoot(resolvedInvocation);
-    const globalHome = ensureGlobalHome();
+    const globalHome = globalStageflowHome();
     if (gitRoot !== null) {
         return {
             invocationCwd: resolvedInvocation,

package/dist/project/resolveStageflowContext.d.ts

@@ -8,4 +8,11 @@ export type StageflowContext = ProjectContext & {
     manifestIssues: LoadIssue[];
 };
 export declare function projectContextFromStageflow(ctx: StageflowContext): ProjectContext;
+/**
+ * Project root resolution is keyed off the nearest `stageflow.yaml`, not git:
+ * a manifest defines a project on its own, the same way a `package.json`
+ * does for npm. Git is checked independently (`isGitProject`) for callers
+ * that need it for execution (checkout/worktrees), not as a precondition
+ * for finding or reading the catalog.
+ */
 export declare function resolveStageflowContext(invocationCwd: string): Promise<StageflowContext>;

package/dist/project/resolveStageflowContext.js

@@ -2,8 +2,9 @@ import { access } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { loadStageflowManifestOutcome, manifestPathForProject, } from "../config/loadStageflowManifest.js";
+import { findManifestRoot } from "./findManifestRoot.js";
 import { findProjectRoot } from "./findProjectRoot.js";
-import { ensureGlobalHome } from "./globalHome.js";
+import { globalStageflowHome } from "./globalHome.js";
 export function projectContextFromStageflow(ctx) {
     return {
         invocationCwd: ctx.invocationCwd,
@@ -12,55 +13,70 @@ export function projectContextFromStageflow(ctx) {
         isGitProject: ctx.isGitProject,
     };
 }
+/**
+ * Project root resolution is keyed off the nearest `stageflow.yaml`, not git:
+ * a manifest defines a project on its own, the same way a `package.json`
+ * does for npm. Git is checked independently (`isGitProject`) for callers
+ * that need it for execution (checkout/worktrees), not as a precondition
+ * for finding or reading the catalog.
+ */
 export async function resolveStageflowContext(invocationCwd) {
     const resolvedInvocation = path.resolve(invocationCwd);
-    const gitRoot = findProjectRoot(resolvedInvocation);
-    const globalHome = ensureGlobalHome();
-    if (gitRoot === null) {
+    const globalHome = globalStageflowHome();
+    const manifestRoot = findManifestRoot(resolvedInvocation);
+    if (manifestRoot !== null) {
+        const isGitProject = findProjectRoot(manifestRoot) !== null;
+        const manifestPath = manifestPathForProject(manifestRoot);
+        try {
+            await access(manifestPath);
+        }
+        catch {
+            return resolveWithoutManifest(resolvedInvocation, globalHome);
+        }
+        const outcome = await loadStageflowManifestOutcome(manifestRoot);
+        if (!outcome.ok) {
+            return {
+                invocationCwd: resolvedInvocation,
+                projectRoot: manifestRoot,
+                globalHome,
+                isGitProject,
+                manifest: null,
+                manifestStatus: "invalid",
+                manifestIssues: outcome.issues,
+            };
+        }
         return {
             invocationCwd: resolvedInvocation,
-            projectRoot: os.homedir(),
+            projectRoot: manifestRoot,
             globalHome,
-            isGitProject: false,
-            manifest: null,
-            manifestStatus: "not_git",
+            isGitProject,
+            manifest: outcome.value,
+            manifestStatus: "ok",
             manifestIssues: [],
         };
     }
-    const manifestPath = manifestPathForProject(gitRoot);
-    try {
-        await access(manifestPath);
-    }
-    catch {
+    return resolveWithoutManifest(resolvedInvocation, globalHome);
+}
+function resolveWithoutManifest(resolvedInvocation, globalHome) {
+    const gitRoot = findProjectRoot(resolvedInvocation);
+    if (gitRoot === null) {
         return {
             invocationCwd: resolvedInvocation,
-            projectRoot: gitRoot,
+            projectRoot: os.homedir(),
             globalHome,
-            isGitProject: true,
+            isGitProject: false,
             manifest: null,
-            manifestStatus: "missing",
+            manifestStatus: "not_git",
             manifestIssues: [],
         };
     }
-    const outcome = await loadStageflowManifestOutcome(gitRoot);
-    if (!outcome.ok) {
-        return {
-            invocationCwd: resolvedInvocation,
-            projectRoot: gitRoot,
-            globalHome,
-            isGitProject: true,
-            manifest: null,
-            manifestStatus: "invalid",
-            manifestIssues: outcome.issues,
-        };
-    }
     return {
         invocationCwd: resolvedInvocation,
         projectRoot: gitRoot,
         globalHome,
         isGitProject: true,
-        manifest: outcome.value,
-        manifestStatus: "ok",
+        manifest: null,
+        manifestStatus: "missing",
         manifestIssues: [],
     };
 }

package/dist/projection/projectRun.d.ts

@@ -1,4 +1,4 @@
-import type { FeedbackLoopHistory, FeedbackLoopRecord, RunDetail, StageSnapshot } from "../runstore/port.js";
+import type { FeedbackLoopHistory, FeedbackLoopRecord, RunBindingDetail, RunDetail, StageSnapshot } from "../runstore/port.js";
 import type { PipelineTrackProjection, RunSummary } from "../runstore/port.js";
 import type { AskOperatorPrompt } from "../tools/askOperator.js";
 import type { StageEnvelope } from "../types/envelope.js";
@@ -29,6 +29,7 @@ export type RunProjection = {
     status: RunDetail["status"];
     created_at: string;
     updated_at?: string;
+    binding: RunBindingDetail;
     stages: StageProjection[];
     pipeline_track: PipelineTrackProjection;
     waiting_stage_id?: RunSummary["waiting_stage_id"];

package/dist/projection/projectRun.js

@@ -13,6 +13,7 @@ export function projectRun(detail) {
         status: detail.status,
         created_at: detail.created_at,
         updated_at: detail.updated_at,
+        binding: detail.binding,
         pipeline_track: detail.pipeline_track,
         ...(detail.waiting_stage_id !== undefined
             ? { waiting_stage_id: detail.waiting_stage_id }

package/dist/runstore/assertTmpdir.d.ts

@@ -0,0 +1 @@
+export declare function assertTmpdirUsable(env?: NodeJS.ProcessEnv): string;

package/dist/runstore/assertTmpdir.js

@@ -0,0 +1,25 @@
+import { accessSync, constants, mkdirSync } from "node:fs";
+import path from "node:path";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { StoreOpenError } from "./sqlite/storeOpenError.js";
+export function assertTmpdirUsable(env = process.env) {
+    let raw = env.TMPDIR ?? env.TMP ?? env.TEMP;
+    if (raw === undefined || raw.trim() === "") {
+        const soft = path.join(globalStageflowHome(), "tmp");
+        process.env.TMPDIR = soft;
+        raw = soft;
+    }
+    const dir = raw.trim();
+    try {
+        mkdirSync(dir, { recursive: true });
+        accessSync(dir, constants.W_OK);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new StoreOpenError(`tmpdir_unusable: TMPDIR=${dir} is not writable (${message})`, "tmpdir_unusable", { path: dir });
+    }
+    if (env.SQLITE_TMPDIR === undefined || env.SQLITE_TMPDIR.trim() === "") {
+        process.env.SQLITE_TMPDIR = dir;
+    }
+    return dir;
+}

package/dist/runstore/backup.d.ts

@@ -0,0 +1,52 @@
+import { createReadStream } from "node:fs";
+import type { RunStore } from "./port.js";
+export type BackupErrorCode = "backup_insufficient_disk" | "backup_verify_failed" | "backup_out_denied" | "backup_cross_device" | "backup_fingerprint_skew";
+export declare class BackupError extends Error {
+    readonly code: BackupErrorCode;
+    readonly detail?: Record<string, unknown>;
+    constructor(message: string, code: BackupErrorCode, detail?: Record<string, unknown>);
+}
+export type BackupContentsFlag = "state.db" | "settings.json" | "agent/auth.json" | "a2a-artifacts" | "manifest.json";
+export type BackupManifest = {
+    created_at: string;
+    stageflow_version: string;
+    schema_version: number;
+    contents: BackupContentsFlag[];
+    db_only: boolean;
+    credentials_included: boolean;
+    a2a_artifacts_included: boolean;
+    settings_fingerprint_before: string | null;
+    settings_fingerprint_after: string | null;
+    auth_fingerprint_before: string | null;
+    auth_fingerprint_after: string | null;
+    fingerprint_skew: boolean;
+    secret_warning: string;
+};
+export type BackupResult = {
+    path: string;
+    bytes: number;
+    sha256: string;
+    schema_version: number;
+    stageflow_version: string;
+    created_at: string;
+    contents: BackupContentsFlag[];
+};
+export type CreateBackupOptions = {
+    store: RunStore;
+    homeDir?: string;
+    outPath?: string;
+    dbOnly?: boolean;
+    noCredentials?: boolean;
+    includeA2aArtifacts?: boolean;
+    freeSpace?: (rootPath: string) => Promise<{
+        freeBytes: number;
+    }>;
+    now?: () => Date;
+};
+export declare function backupsDir(homeDir?: string): string;
+export declare function defaultBackupOutPath(homeDir?: string, now?: Date, dbOnly?: boolean): string;
+export declare function assertBackupOutPathAllowed(outPath: string, homeDir?: string): string;
+export declare function verifyDbSnapshot(snapshotPath: string, expectedUserVersion: number): void;
+export declare function createBackup(options: CreateBackupOptions): Promise<BackupResult>;
+export declare function resolveBackupDownloadPath(name: string, homeDir?: string): Promise<string>;
+export declare function openBackupReadStream(filePath: string): ReturnType<typeof createReadStream>;