stageflow 0.25.0 → 0.27.0

package/dist/diagnostics/checks.js

@@ -0,0 +1,135 @@
+import { accessSync, constants, writeFileSync, unlinkSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { globalStageflowHome } from "../project/globalHome.js";
+const execFileAsync = promisify(execFile);
+const READYZ_TTL_MS = 4_000;
+let readyzCache;
+export function resetReadyzCacheForTests() {
+    readyzCache = undefined;
+}
+export function livezBody() {
+    return { ok: true, status: "live" };
+}
+async function checkGitPresent() {
+    try {
+        await execFileAsync("git", ["--version"], {
+            timeout: 5_000,
+            windowsHide: true,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function probeGitVersion() {
+    try {
+        const { stdout } = await execFileAsync("git", ["--version"], {
+            timeout: 5_000,
+            windowsHide: true,
+        });
+        return stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function checkHomeWritable(home) {
+    try {
+        accessSync(home, constants.W_OK);
+        const probe = `${home}/.stageflow-write-probe-${process.pid}`;
+        writeFileSync(probe, "ok");
+        unlinkSync(probe);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function checkStoreOpenable(store) {
+    try {
+        await store.listRuns();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function checkMigrationsComplete(store) {
+    const connection = store.connection;
+    if (connection === undefined || typeof connection.pragma !== "function") {
+        return true;
+    }
+    try {
+        const version = connection.pragma("user_version", { simple: true });
+        return typeof version === "number" && version >= 0;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runReadyzChecks(options) {
+    const now = options.now ?? Date.now();
+    if (!options.bypassCache &&
+        readyzCache !== undefined &&
+        readyzCache.expiresAt > now) {
+        return readyzCache.result;
+    }
+    const home = options.homeDir ?? globalStageflowHome();
+    const checks = {
+        store_openable: await checkStoreOpenable(options.store),
+        home_writable: checkHomeWritable(home),
+        migrations_complete: checkMigrationsComplete(options.store),
+        git_present: await checkGitPresent(),
+    };
+    let code;
+    if (!checks.store_openable)
+        code = "store_not_openable";
+    else if (!checks.home_writable)
+        code = "home_not_writable";
+    else if (!checks.migrations_complete)
+        code = "migrations_incomplete";
+    else if (!checks.git_present)
+        code = "git_not_present";
+    const result = {
+        ready: code === undefined,
+        checks,
+        ...(code !== undefined ? { code } : {}),
+    };
+    readyzCache = { expiresAt: now + READYZ_TTL_MS, result };
+    return result;
+}
+export function readSchemaHealth(store) {
+    const connection = store.connection;
+    if (connection === undefined || typeof connection.pragma !== "function") {
+        return {
+            user_version: null,
+            schema_migrations: "unknown",
+            note: "Slot 1 schema reporting stub — store has no sqlite connection",
+        };
+    }
+    try {
+        const user_version = connection.pragma("user_version", {
+            simple: true,
+        });
+        let schema_migrations = "unknown";
+        if (typeof connection.prepare === "function") {
+            try {
+                connection.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'schema_migrations'`).get();
+                schema_migrations = "present";
+            }
+            catch {
+                schema_migrations = "absent";
+            }
+        }
+        return { user_version, schema_migrations };
+    }
+    catch {
+        return {
+            user_version: null,
+            schema_migrations: "unknown",
+            note: "Slot 1 schema reporting stub — pragma failed",
+        };
+    }
+}

package/dist/errors/codes.d.ts

@@ -0,0 +1,14 @@
+/** Stable network-facing error codes (snake_case). Keep strings unchanged once shipped. */
+export declare const BUSY_CAPACITY: "busy_capacity";
+export declare const BUSY_CHECKOUT: "busy_checkout";
+/** Per-caller concurrency quota: queued when under global capacity; reject when queue full. */
+export declare const BUSY_CALLER_QUOTA: "busy_caller_quota";
+export declare const ABORTED: "aborted";
+export declare const NETWORK_ERROR_CODES: readonly ["busy_capacity", "busy_checkout", "busy_caller_quota", "aborted", "unknown_project_root", "absolute_path_not_allowed", "path_outside_project_root", "catalog_root_unreadable", "ensure_project_not_allowed", "config_invalid", "config_unknown_key", "provider_not_configured", "a2a_configuration_error", "untrusted_config_origin", "command_not_on_path", "missing_tool", "tool_version_mismatch", "unknown_version", "secret_unavailable", "not_ready", "internal_error", "retry_in_progress", "hitl_not_retriable", "run_not_retryable", "stage_not_failed", "manual_recovery_required", "run_not_found", "stage_not_found", "artifact_not_found", "artifact_path_denied", "envelope_not_found", "insufficient_disk", "disk_check_failed", "shutting_down", "start.token_rejected", "inline_pipeline_too_large", "skills_invalid_name", "skills_invalid_path", "skills_missing_skill_md", "skills_payload_too_large", "pinned_sha_unavailable", "store_integrity_failed", "store_unsupported_filesystem", "tmpdir_unusable", "backup_insufficient_disk"];
+export type NetworkErrorCode = (typeof NETWORK_ERROR_CODES)[number] | string;
+export type NetworkErrorBody = {
+    code: NetworkErrorCode;
+    error: string;
+} & Record<string, unknown>;
+export declare function networkError(code: NetworkErrorCode, error: string, detail?: Record<string, unknown>): NetworkErrorBody;
+export declare function codeOrInternal(code: string | undefined): NetworkErrorCode;

package/dist/errors/codes.js

@@ -0,0 +1,59 @@
+/** Stable network-facing error codes (snake_case). Keep strings unchanged once shipped. */
+export const BUSY_CAPACITY = "busy_capacity";
+export const BUSY_CHECKOUT = "busy_checkout";
+/** Per-caller concurrency quota: queued when under global capacity; reject when queue full. */
+export const BUSY_CALLER_QUOTA = "busy_caller_quota";
+export const ABORTED = "aborted";
+export const NETWORK_ERROR_CODES = [
+    BUSY_CAPACITY,
+    BUSY_CHECKOUT,
+    BUSY_CALLER_QUOTA,
+    ABORTED,
+    "unknown_project_root",
+    "absolute_path_not_allowed",
+    "path_outside_project_root",
+    "catalog_root_unreadable",
+    "ensure_project_not_allowed",
+    "config_invalid",
+    "config_unknown_key",
+    "provider_not_configured",
+    "a2a_configuration_error",
+    "untrusted_config_origin",
+    "command_not_on_path",
+    "missing_tool",
+    "tool_version_mismatch",
+    "unknown_version",
+    "secret_unavailable",
+    "not_ready",
+    "internal_error",
+    "retry_in_progress",
+    "hitl_not_retriable",
+    "run_not_retryable",
+    "stage_not_failed",
+    "manual_recovery_required",
+    "run_not_found",
+    "stage_not_found",
+    "artifact_not_found",
+    "artifact_path_denied",
+    "envelope_not_found",
+    "insufficient_disk",
+    "disk_check_failed",
+    "shutting_down",
+    "start.token_rejected",
+    "inline_pipeline_too_large",
+    "skills_invalid_name",
+    "skills_invalid_path",
+    "skills_missing_skill_md",
+    "skills_payload_too_large",
+    "pinned_sha_unavailable",
+    "store_integrity_failed",
+    "store_unsupported_filesystem",
+    "tmpdir_unusable",
+    "backup_insufficient_disk",
+];
+export function networkError(code, error, detail) {
+    return { code, error, ...detail };
+}
+export function codeOrInternal(code) {
+    return code && code.length > 0 ? code : "internal_error";
+}

package/dist/git/cache.d.ts

@@ -0,0 +1,14 @@
+export declare function setBareCacheRemoteUrlOverrideForTests(override: ((repository: string) => string | undefined) | null): void;
+export declare function resetBareCacheStateForTests(): void;
+export declare function githubHttpsRemoteUrl(repository: string): string;
+export declare function bareCachePath(repository: string): string;
+export declare function remoteUrlForRepository(repository: string): string;
+export type EnsureBareCacheResult = {
+    cachePath: string;
+    fetched: boolean;
+};
+export type EnsureBareCacheOptions = {
+    env?: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+};
+export declare function ensureBareCache(repository: string, ref: string, options?: EnsureBareCacheOptions): Promise<EnsureBareCacheResult>;

package/dist/git/cache.js

@@ -0,0 +1,150 @@
+import { closeSync, existsSync, mkdirSync, openSync, statSync, unlinkSync, writeSync, } from "node:fs";
+import path from "node:path";
+import { ensureGlobalHome, globalStageflowHome } from "../project/globalHome.js";
+import { hostGitAskpassEnv } from "./credentials.js";
+import { catFileCommit, cloneBare, configureBareOriginFetch, pruneNonStageflowLocalHeads, remoteUpdate, } from "./operations.js";
+const FETCH_TIMEOUT_MS = 300_000;
+const LOCK_POLL_MS = 50;
+const FULL_SHA_RE = /^[0-9a-f]{40}$/i;
+const mutexTails = new Map();
+let remoteUrlOverride = null;
+export function setBareCacheRemoteUrlOverrideForTests(override) {
+    remoteUrlOverride = override;
+}
+export function resetBareCacheStateForTests() {
+    mutexTails.clear();
+    remoteUrlOverride = null;
+}
+export function githubHttpsRemoteUrl(repository) {
+    return `https://github.com/${repository}.git`;
+}
+export function bareCachePath(repository) {
+    const [owner, repo] = repository.split("/");
+    return path.join(globalStageflowHome(), "repos", "github.com", owner, `${repo}.git`);
+}
+export function remoteUrlForRepository(repository) {
+    const overridden = remoteUrlOverride?.(repository);
+    if (overridden)
+        return overridden;
+    return githubHttpsRemoteUrl(repository);
+}
+function isFullCommitSha(ref) {
+    return FULL_SHA_RE.test(ref);
+}
+function isFileUrl(url) {
+    return url.startsWith("file:");
+}
+function fetchLockPath(cachePath) {
+    if (existsSync(cachePath)) {
+        return path.join(cachePath, ".stageflow-fetch.lock");
+    }
+    return `${cachePath}.stageflow-fetch.lock`;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function withInProcessMutex(key, fn) {
+    const prev = mutexTails.get(key) ?? Promise.resolve();
+    let release;
+    const gate = new Promise((resolve) => {
+        release = resolve;
+    });
+    const tail = prev.then(() => gate);
+    mutexTails.set(key, tail);
+    await prev.catch(() => undefined);
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+        if (mutexTails.get(key) === tail) {
+            mutexTails.delete(key);
+        }
+    }
+}
+function tryReclaimStaleLock(lockPath, staleMs) {
+    try {
+        const st = statSync(lockPath);
+        if (Date.now() - st.mtimeMs > staleMs) {
+            unlinkSync(lockPath);
+        }
+    }
+    catch {
+        // gone or unreadable
+    }
+}
+async function acquireExclusiveLock(lockPath, staleMs) {
+    mkdirSync(path.dirname(lockPath), { recursive: true });
+    for (;;) {
+        try {
+            const fd = openSync(lockPath, "wx");
+            writeSync(fd, `${JSON.stringify({ pid: process.pid, startedAt: Date.now() })}\n`, 0, "utf8");
+            return fd;
+        }
+        catch (error) {
+            const err = error;
+            if (err.code !== "EEXIST")
+                throw error;
+            tryReclaimStaleLock(lockPath, staleMs);
+            await sleep(LOCK_POLL_MS);
+        }
+    }
+}
+function releaseExclusiveLock(fd, lockPath) {
+    try {
+        closeSync(fd);
+    }
+    catch {
+        // ignore
+    }
+    try {
+        unlinkSync(lockPath);
+    }
+    catch {
+        // ignore
+    }
+}
+async function withExclusiveLock(lockPath, staleMs, fn) {
+    const fd = await acquireExclusiveLock(lockPath, staleMs);
+    try {
+        return await fn();
+    }
+    finally {
+        releaseExclusiveLock(fd, lockPath);
+    }
+}
+export async function ensureBareCache(repository, ref, options) {
+    ensureGlobalHome();
+    const cachePath = bareCachePath(repository);
+    const url = remoteUrlForRepository(repository);
+    const requireToken = !isFileUrl(url);
+    return withInProcessMutex(cachePath, async () => {
+        const lockPath = fetchLockPath(cachePath);
+        return withExclusiveLock(lockPath, FETCH_TIMEOUT_MS, async () => {
+            const askpassEnv = hostGitAskpassEnv({
+                env: options?.env,
+                requireToken,
+            });
+            const gitEnv = { ...askpassEnv, ...options?.env };
+            const callOpts = { env: gitEnv, signal: options?.signal };
+            mkdirSync(path.dirname(cachePath), { recursive: true });
+            if (!existsSync(cachePath)) {
+                await cloneBare(url, cachePath, callOpts);
+                await remoteUpdate(cachePath, callOpts);
+                await pruneNonStageflowLocalHeads(cachePath, callOpts);
+                return { cachePath, fetched: true };
+            }
+            await configureBareOriginFetch(cachePath, callOpts);
+            if (isFullCommitSha(ref)) {
+                const present = await catFileCommit(cachePath, ref, callOpts);
+                if (present) {
+                    await pruneNonStageflowLocalHeads(cachePath, callOpts);
+                    return { cachePath, fetched: false };
+                }
+            }
+            await remoteUpdate(cachePath, callOpts);
+            await pruneNonStageflowLocalHeads(cachePath, callOpts);
+            return { cachePath, fetched: true };
+        });
+    });
+}

package/dist/git/credentials.d.ts

@@ -0,0 +1,9 @@
+export declare function readHostGithubToken(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function askpassHelperPath(home?: string): string;
+export declare function ensureAskpassHelper(home?: string): string;
+export type HostGitAskpassEnvOptions = {
+    env?: NodeJS.ProcessEnv;
+    requireToken?: boolean;
+    home?: string;
+};
+export declare function hostGitAskpassEnv(options?: HostGitAskpassEnvOptions): NodeJS.ProcessEnv;

package/dist/git/credentials.js

@@ -0,0 +1,88 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { GitError } from "./errors.js";
+import { ensureGlobalHome, globalStageflowHome } from "../project/globalHome.js";
+const ASKPASS_BASENAME = "git-askpass";
+const ASKPASS_SCRIPT = `#!/bin/sh
+prompt=\${1-}
+case "\$prompt" in
+  *Username*|*username*)
+    printf '%s\\n' 'x-access-token'
+    ;;
+  *)
+    token=\${GITHUB_TOKEN-}
+    if [ -z "\$token" ]; then
+      token=\${GH_TOKEN-}
+    fi
+    if [ -z "\$token" ] && [ -n "\${GITHUB_TOKEN_FILE-}" ] && [ -f "\$GITHUB_TOKEN_FILE" ]; then
+      token=\$(cat "\$GITHUB_TOKEN_FILE")
+    fi
+    if [ -z "\$token" ] && [ -n "\${GH_TOKEN_FILE-}" ] && [ -f "\$GH_TOKEN_FILE" ]; then
+      token=\$(cat "\$GH_TOKEN_FILE")
+    fi
+    printf '%s\\n' "\$token"
+    ;;
+esac
+`;
+export function readHostGithubToken(env = process.env) {
+    for (const key of ["GITHUB_TOKEN", "GH_TOKEN"]) {
+        const value = env[key]?.trim();
+        if (value)
+            return value;
+    }
+    for (const key of ["GITHUB_TOKEN_FILE", "GH_TOKEN_FILE"]) {
+        const file = env[key]?.trim();
+        if (!file)
+            continue;
+        try {
+            const value = readFileSync(file, "utf8").trim();
+            if (value)
+                return value;
+        }
+        catch {
+            // ignore unreadable files; fall through
+        }
+    }
+    return undefined;
+}
+export function askpassHelperPath(home = globalStageflowHome()) {
+    return path.join(home, ASKPASS_BASENAME);
+}
+export function ensureAskpassHelper(home) {
+    const resolvedHome = home ?? ensureGlobalHome();
+    mkdirSync(resolvedHome, { recursive: true });
+    const askpass = askpassHelperPath(resolvedHome);
+    if (!existsSync(askpass)) {
+        writeFileSync(askpass, ASKPASS_SCRIPT, { encoding: "utf8", mode: 0o700 });
+    }
+    try {
+        chmodSync(askpass, 0o700);
+    }
+    catch {
+        // best-effort on non-POSIX
+    }
+    return askpass;
+}
+export function hostGitAskpassEnv(options = {}) {
+    const sourceEnv = options.env ?? process.env;
+    const home = options.home ?? ensureGlobalHome();
+    const askpass = ensureAskpassHelper(home);
+    const token = readHostGithubToken(sourceEnv);
+    const requireToken = options.requireToken !== false;
+    if (requireToken && !token) {
+        throw new GitError("git authentication failed", {
+            code: "auth_failed",
+            argv: [],
+            stderr: "GITHUB_TOKEN (or GH_TOKEN / GITHUB_TOKEN_FILE / GH_TOKEN_FILE) is required for repository binding (clone/fetch and later push/PR). Set it on the Host process environment before start.",
+            exitCode: null,
+        });
+    }
+    const out = {
+        GIT_ASKPASS: askpass,
+        GIT_TERMINAL_PROMPT: "0",
+    };
+    if (token) {
+        out.GITHUB_TOKEN = token;
+    }
+    return out;
+}

package/dist/git/errors.d.ts

@@ -0,0 +1,20 @@
+export type GitErrorCode = "auth_failed" | "ref_not_found" | "repo_not_found" | "network" | "disk_full" | "git_missing" | "timeout" | "unknown";
+export declare class GitError extends Error {
+    readonly code: GitErrorCode;
+    readonly argv: string[];
+    readonly stderr: string;
+    readonly exitCode: number | null;
+    constructor(message: string, options: {
+        code: GitErrorCode;
+        argv: string[];
+        stderr: string;
+        exitCode: number | null;
+    });
+}
+export declare function redactGitText(text: string, env?: NodeJS.ProcessEnv): string;
+export declare function classifyGitFailure(input: {
+    stderr: string;
+    exitCode: number | null;
+    errno?: string | null;
+    timedOut?: boolean;
+}): GitErrorCode;

package/dist/git/errors.js

@@ -0,0 +1,94 @@
+export class GitError extends Error {
+    code;
+    argv;
+    stderr;
+    exitCode;
+    constructor(message, options) {
+        super(message);
+        this.name = "GitError";
+        this.code = options.code;
+        this.argv = options.argv;
+        this.stderr = options.stderr;
+        this.exitCode = options.exitCode;
+    }
+}
+const URL_CREDENTIALS = /:\/\/([^/\s]*?):([^/\s]*?)@/g;
+const TOKEN_PATTERNS = [
+    /\bghp_[A-Za-z0-9_]{20,}\b/g,
+    /\bgho_[A-Za-z0-9_]{20,}\b/g,
+    /\bghu_[A-Za-z0-9_]{20,}\b/g,
+    /\bghs_[A-Za-z0-9_]{20,}\b/g,
+    /\bghr_[A-Za-z0-9_]{20,}\b/g,
+    /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
+    /\bglpat-[A-Za-z0-9_\-]{20,}\b/g,
+    /\bxox[baprs]-[A-Za-z0-9\-]{10,}\b/g,
+    /\bBearer\s+[A-Za-z0-9\-._~+/]+=*/gi,
+];
+const ENV_SECRET_KEYS = [
+    "GITHUB_TOKEN",
+    "GH_TOKEN",
+    "GITHUB_TOKEN_FILE",
+    "GH_TOKEN_FILE",
+];
+export function redactGitText(text, env = process.env) {
+    let out = text.replace(URL_CREDENTIALS, "://$1:***@");
+    for (const pattern of TOKEN_PATTERNS) {
+        out = out.replace(pattern, "***");
+    }
+    for (const key of ENV_SECRET_KEYS) {
+        const value = env[key];
+        if (typeof value === "string" && value.length >= 8 && !key.endsWith("_FILE")) {
+            out = out.split(value).join("***");
+        }
+    }
+    return out;
+}
+export function classifyGitFailure(input) {
+    if (input.errno === "ENOENT")
+        return "git_missing";
+    if (input.timedOut)
+        return "timeout";
+    const stderr = input.stderr;
+    const lower = stderr.toLowerCase();
+    if (/authentication failed/i.test(stderr) ||
+        /could not read username/i.test(stderr) ||
+        /could not read password/i.test(stderr) ||
+        /invalid username or password/i.test(stderr) ||
+        /authentication required/i.test(stderr) ||
+        /access denied/i.test(stderr) ||
+        /terminal prompts disabled/i.test(stderr)) {
+        return "auth_failed";
+    }
+    // GitHub hides private repos behind "not found"; treat as auth-suspicion.
+    if (/remote:\s*repository not found/i.test(stderr) ||
+        (/repository ['`].*['`] not found/i.test(stderr) && /github\.com/i.test(stderr))) {
+        return "auth_failed";
+    }
+    if (/couldn't find remote ref/i.test(stderr) ||
+        /unknown revision/i.test(stderr) ||
+        /bad revision/i.test(stderr) ||
+        /invalid refspec/i.test(stderr) ||
+        /needed a single revision/i.test(stderr) ||
+        /not a valid object name/i.test(stderr) ||
+        /ambiguous argument .* unknown revision/i.test(stderr)) {
+        return "ref_not_found";
+    }
+    if (/does not appear to be a git repository/i.test(stderr) ||
+        /not a git repository/i.test(stderr) ||
+        /repository .* does not exist/i.test(stderr) ||
+        (/fatal: repository ['`].*['`] not found/i.test(stderr) && !/github\.com/i.test(stderr))) {
+        return "repo_not_found";
+    }
+    if (/could not resolve host/i.test(stderr) ||
+        /failed to connect/i.test(stderr) ||
+        /connection refused/i.test(stderr) ||
+        /network is unreachable/i.test(stderr) ||
+        /timed out/i.test(lower) ||
+        /unable to access/i.test(stderr)) {
+        return "network";
+    }
+    if (/no space left on device/i.test(stderr) || /disk quota exceeded/i.test(stderr)) {
+        return "disk_full";
+    }
+    return "unknown";
+}

package/dist/git/exec.d.ts

@@ -0,0 +1,16 @@
+export type RunGitOptions = {
+    args: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    maxBuffer?: number;
+    gitBin?: string;
+    signal?: AbortSignal;
+};
+export type RunGitResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+};
+export declare function runGitSync(options: RunGitOptions): RunGitResult;
+export declare function runGit(options: RunGitOptions): Promise<RunGitResult>;