stageflow 0.25.0 → 0.30.0

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>;

package/dist/git/exec.js

@@ -0,0 +1,135 @@
+import { execFile, execFileSync } from "node:child_process";
+import { classifyGitFailure, GitError, redactGitText, } from "./errors.js";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_BUFFER = 16 * 1024 * 1024;
+function buildEnv(extra) {
+    return {
+        ...process.env,
+        ...extra,
+        GIT_TERMINAL_PROMPT: "0",
+    };
+}
+function toErrorMessage(code) {
+    switch (code) {
+        case "auth_failed":
+            return "git authentication failed";
+        case "ref_not_found":
+            return "git ref not found";
+        case "repo_not_found":
+            return "git repository not found";
+        case "network":
+            return "git network error";
+        case "disk_full":
+            return "git disk full";
+        case "git_missing":
+            return "git binary not found";
+        case "timeout":
+            return "git command timed out";
+        default:
+            return "git command failed";
+    }
+}
+function fail(options) {
+    const stderr = redactGitText(options.stderrRaw, options.env);
+    const code = classifyGitFailure({
+        stderr: options.stderrRaw,
+        exitCode: options.exitCode,
+        errno: options.errno,
+        timedOut: options.timedOut,
+    });
+    throw new GitError(toErrorMessage(code), {
+        code,
+        argv: options.argv,
+        stderr,
+        exitCode: options.exitCode,
+    });
+}
+function normalizeStderr(stderr) {
+    if (Buffer.isBuffer(stderr))
+        return stderr.toString("utf8").trim();
+    if (typeof stderr === "string")
+        return stderr.trim();
+    return "";
+}
+export function runGitSync(options) {
+    const gitBin = options.gitBin ?? "git";
+    const argv = [gitBin, ...options.args];
+    const env = buildEnv(options.env);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    try {
+        const stdout = execFileSync(gitBin, options.args, {
+            cwd: options.cwd,
+            env,
+            encoding: "utf8",
+            timeout: timeoutMs,
+            maxBuffer: options.maxBuffer ?? DEFAULT_MAX_BUFFER,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return { stdout, stderr: "", exitCode: 0 };
+    }
+    catch (error) {
+        const err = error;
+        const timedOut = err.killed === true ||
+            err.signal === "SIGTERM" ||
+            (typeof err.message === "string" && /TIMEDOUT|timed out/i.test(err.message));
+        fail({
+            argv,
+            stderrRaw: normalizeStderr(err.stderr) || (timedOut ? "git command timed out" : err.message),
+            exitCode: typeof err.status === "number" ? err.status : null,
+            errno: err.code ?? null,
+            timedOut,
+            env,
+        });
+    }
+}
+export function runGit(options) {
+    const gitBin = options.gitBin ?? "git";
+    const argv = [gitBin, ...options.args];
+    const env = buildEnv(options.env);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return new Promise((resolve, reject) => {
+        execFile(gitBin, options.args, {
+            cwd: options.cwd,
+            env,
+            encoding: "utf8",
+            timeout: timeoutMs,
+            maxBuffer: options.maxBuffer ?? DEFAULT_MAX_BUFFER,
+            signal: options.signal,
+            killSignal: "SIGTERM",
+        }, (error, stdout, stderr) => {
+            if (!error) {
+                resolve({
+                    stdout: typeof stdout === "string" ? stdout : String(stdout ?? ""),
+                    stderr: normalizeStderr(stderr),
+                    exitCode: 0,
+                });
+                return;
+            }
+            const err = error;
+            const timedOut = err.killed === true ||
+                err.signal === "SIGTERM" ||
+                err.code === "ETIMEDOUT" ||
+                (typeof err.message === "string" && /TIMEDOUT|timed out/i.test(err.message));
+            const errno = typeof err.code === "string" ? err.code : null;
+            const exitCode = typeof err.status === "number"
+                ? err.status
+                : typeof err.code === "number"
+                    ? err.code
+                    : null;
+            try {
+                fail({
+                    argv,
+                    stderrRaw: normalizeStderr(stderr) ||
+                        (timedOut ? "git command timed out" : err.message),
+                    exitCode,
+                    errno,
+                    timedOut,
+                    env,
+                });
+            }
+            catch (gitError) {
+                reject(gitError);
+            }
+        });
+    });
+}

package/dist/git/operations.d.ts

@@ -0,0 +1,29 @@
+export type GitCallOptions = {
+    env?: NodeJS.ProcessEnv;
+    gitBin?: string;
+    signal?: AbortSignal;
+};
+export declare const BARE_ORIGIN_FETCH_HEADS = "+refs/heads/*:refs/remotes/origin/*";
+export declare const BARE_ORIGIN_FETCH_TAGS = "+refs/tags/*:refs/tags/*";
+export declare function configureBareOriginFetch(repoDir: string, opts?: GitCallOptions): Promise<void>;
+export declare function pruneNonStageflowLocalHeads(repoDir: string, opts?: GitCallOptions): Promise<void>;
+export declare function cloneBare(url: string, dest: string, opts?: GitCallOptions): Promise<void>;
+export declare function fetch(repoDir: string, refspecs?: string[], opts?: GitCallOptions): Promise<void>;
+export declare function remoteUpdate(repoDir: string, opts?: GitCallOptions): Promise<void>;
+export declare function resolveRef(repoDir: string, ref: string, opts?: GitCallOptions): Promise<string>;
+export declare function catFileCommit(repoDir: string, sha: string, opts?: GitCallOptions): Promise<boolean>;
+export declare function worktreeAdd(repoDir: string, input: {
+    worktreePath: string;
+    branch: string;
+    startPoint: string;
+}, opts?: GitCallOptions): Promise<void>;
+export declare function worktreeRemove(repoDir: string, worktreePath: string, opts?: GitCallOptions): Promise<void>;
+export declare function worktreePrune(repoDir: string, opts?: GitCallOptions): Promise<void>;
+export declare function deleteBranch(repoDir: string, branch: string, opts?: GitCallOptions): Promise<void>;
+export declare function revParse(repoDir: string, args: string[], opts?: GitCallOptions): Promise<string>;
+export declare function diff(repoDir: string, args?: string[], opts?: GitCallOptions): Promise<string>;
+export declare function statusPorcelain(repoDir: string, pathspec?: string, opts?: GitCallOptions): string;
+export declare function statusPorcelainZ(repoDir: string, opts?: GitCallOptions): Promise<string>;
+export declare function lsFilesOthersZ(repoDir: string, opts?: GitCallOptions): Promise<string>;
+export declare function checkRefFormat(branchName: string, opts?: GitCallOptions): Promise<boolean>;
+export declare function revParseSync(cwd: string, args: string[], opts?: GitCallOptions): string;