stageflow 0.23.0 → 0.27.0

package/dist/git/operations.js

@@ -0,0 +1,153 @@
+import { GitError } from "./errors.js";
+import { runGit, runGitSync } from "./exec.js";
+const TIMEOUT = {
+    resolve: 30_000,
+    worktree: 120_000,
+    fetch: 300_000,
+    clone: 900_000,
+    default: 30_000,
+};
+const FULL_SHA_RE = /^[0-9a-f]{40}$/i;
+function baseOpts(cwd, args, timeoutMs, opts) {
+    return {
+        cwd,
+        args,
+        timeoutMs,
+        env: opts?.env,
+        gitBin: opts?.gitBin,
+        signal: opts?.signal,
+    };
+}
+export const BARE_ORIGIN_FETCH_HEADS = "+refs/heads/*:refs/remotes/origin/*";
+export const BARE_ORIGIN_FETCH_TAGS = "+refs/tags/*:refs/tags/*";
+export async function configureBareOriginFetch(repoDir, opts) {
+    try {
+        await runGit(baseOpts(repoDir, ["config", "--unset", "remote.origin.mirror"], TIMEOUT.default, opts));
+    }
+    catch {
+        // unset fails when the key is absent
+    }
+    try {
+        await runGit(baseOpts(repoDir, ["config", "--unset-all", "remote.origin.fetch"], TIMEOUT.default, opts));
+    }
+    catch {
+        // unset-all fails when the key is absent
+    }
+    await runGit(baseOpts(repoDir, ["config", "--add", "remote.origin.fetch", BARE_ORIGIN_FETCH_HEADS], TIMEOUT.default, opts));
+    await runGit(baseOpts(repoDir, ["config", "--add", "remote.origin.fetch", BARE_ORIGIN_FETCH_TAGS], TIMEOUT.default, opts));
+}
+export async function pruneNonStageflowLocalHeads(repoDir, opts) {
+    const listed = await runGit(baseOpts(repoDir, ["for-each-ref", "--format=%(refname)", "refs/heads/"], TIMEOUT.default, opts));
+    const refs = listed.stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    for (const ref of refs) {
+        if (ref === "refs/heads/stageflow" || ref.startsWith("refs/heads/stageflow/")) {
+            continue;
+        }
+        try {
+            await runGit(baseOpts(repoDir, ["update-ref", "-d", ref], TIMEOUT.default, opts));
+        }
+        catch {
+            // best-effort prune under heal lock
+        }
+    }
+}
+export async function cloneBare(url, dest, opts) {
+    await runGit(baseOpts(undefined, ["clone", "--bare", url, dest], TIMEOUT.clone, opts));
+    await configureBareOriginFetch(dest, opts);
+}
+export async function fetch(repoDir, refspecs = [], opts) {
+    await runGit(baseOpts(repoDir, ["fetch", "--prune", "origin", ...refspecs], TIMEOUT.fetch, opts));
+}
+export async function remoteUpdate(repoDir, opts) {
+    await runGit(baseOpts(repoDir, ["remote", "update", "--prune"], TIMEOUT.fetch, opts));
+}
+async function revParseCommit(repoDir, ref, opts) {
+    const result = await runGit(baseOpts(repoDir, ["rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`], TIMEOUT.resolve, opts));
+    return result.stdout.trim();
+}
+async function tryRevParseCommit(repoDir, ref, opts) {
+    try {
+        return await revParseCommit(repoDir, ref, opts);
+    }
+    catch (err) {
+        if (err instanceof GitError && err.code === "ref_not_found") {
+            return null;
+        }
+        throw err;
+    }
+}
+export async function resolveRef(repoDir, ref, opts) {
+    if (FULL_SHA_RE.test(ref) || ref.startsWith("refs/")) {
+        return revParseCommit(repoDir, ref, opts);
+    }
+    const candidates = [
+        `refs/remotes/origin/${ref}`,
+        `origin/${ref}`,
+        `refs/tags/${ref}`,
+    ];
+    for (const candidate of candidates) {
+        const sha = await tryRevParseCommit(repoDir, candidate, opts);
+        if (sha !== null)
+            return sha;
+    }
+    return revParseCommit(repoDir, candidates[0], opts);
+}
+export async function catFileCommit(repoDir, sha, opts) {
+    try {
+        await runGit(baseOpts(repoDir, ["cat-file", "-e", `${sha}^{commit}`], TIMEOUT.resolve, opts));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function worktreeAdd(repoDir, input, opts) {
+    await runGit(baseOpts(repoDir, ["worktree", "add", "-b", input.branch, input.worktreePath, input.startPoint], TIMEOUT.worktree, opts));
+}
+export async function worktreeRemove(repoDir, worktreePath, opts) {
+    await runGit(baseOpts(repoDir, ["worktree", "remove", "--force", worktreePath], TIMEOUT.worktree, opts));
+}
+export async function worktreePrune(repoDir, opts) {
+    await runGit(baseOpts(repoDir, ["worktree", "prune"], TIMEOUT.worktree, opts));
+}
+export async function deleteBranch(repoDir, branch, opts) {
+    await runGit(baseOpts(repoDir, ["branch", "-D", branch], TIMEOUT.default, opts));
+}
+export async function revParse(repoDir, args, opts) {
+    const result = await runGit(baseOpts(repoDir, ["rev-parse", ...args], TIMEOUT.resolve, opts));
+    return result.stdout.trim();
+}
+export async function diff(repoDir, args = [], opts) {
+    const result = await runGit(baseOpts(repoDir, ["diff", ...args], TIMEOUT.default, opts));
+    return result.stdout;
+}
+export function statusPorcelain(repoDir, pathspec, opts) {
+    const args = ["status", "--porcelain"];
+    if (pathspec !== undefined) {
+        args.push("--", pathspec);
+    }
+    return runGitSync(baseOpts(repoDir, args, TIMEOUT.default, opts)).stdout;
+}
+export async function statusPorcelainZ(repoDir, opts) {
+    const result = await runGit(baseOpts(repoDir, ["status", "--porcelain=v1", "-z", "--untracked-files=all"], TIMEOUT.default, opts));
+    return result.stdout;
+}
+export async function lsFilesOthersZ(repoDir, opts) {
+    const result = await runGit(baseOpts(repoDir, ["ls-files", "--others", "--exclude-standard", "-z"], TIMEOUT.default, opts));
+    return result.stdout;
+}
+export async function checkRefFormat(branchName, opts) {
+    try {
+        await runGit(baseOpts(undefined, ["check-ref-format", "--branch", branchName], TIMEOUT.resolve, opts));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function revParseSync(cwd, args, opts) {
+    return runGitSync(baseOpts(cwd, ["rev-parse", ...args], TIMEOUT.resolve, opts)).stdout.trim();
+}

package/dist/git/version.d.ts

@@ -0,0 +1 @@
+export declare function gitVersion(gitBin?: string): Promise<string>;

package/dist/git/version.js

@@ -0,0 +1,10 @@
+import { runGit } from "./exec.js";
+export async function gitVersion(gitBin = "git") {
+    const result = await runGit({
+        gitBin,
+        args: ["version"],
+        timeoutMs: 5_000,
+    });
+    const match = result.stdout.match(/git version\s+(\S+)/i);
+    return match?.[1] ?? result.stdout.trim();
+}

package/dist/logging/audit.d.ts

@@ -0,0 +1,16 @@
+import type { Logger } from "./logger.js";
+import type { CallerSurface } from "../server/requestAuthContext.js";
+export type AuditOutcome = "ok" | "error";
+export type AuditRecord = {
+    caller_id: string | null;
+    surface: CallerSurface;
+    action: string;
+    target_run_id?: string;
+    outcome: AuditOutcome;
+    error_code?: string;
+};
+/**
+ * Append-only mutating-call audit on the Slot 4 JSON logger.
+ * Allowlisted fields only — never Authorization, pipeline_body, or skills.
+ */
+export declare function writeAudit(log: Logger, record: AuditRecord): void;

package/dist/logging/audit.js

@@ -0,0 +1,19 @@
+/**
+ * Append-only mutating-call audit on the Slot 4 JSON logger.
+ * Allowlisted fields only — never Authorization, pipeline_body, or skills.
+ */
+export function writeAudit(log, record) {
+    const fields = {
+        caller_id: record.caller_id,
+        surface: record.surface,
+        action: record.action,
+        outcome: record.outcome,
+    };
+    if (record.target_run_id !== undefined) {
+        fields.target_run_id = record.target_run_id;
+    }
+    if (record.error_code !== undefined) {
+        fields.error_code = record.error_code;
+    }
+    log.info("audit", `${record.action} ${record.outcome}`, fields);
+}

package/dist/logging/commonWords.d.ts

@@ -0,0 +1,2 @@
+/** Common words that must not be value-redacted even if length ≥ 8. */
+export declare const COMMON_WORDS: ReadonlySet<string>;

package/dist/logging/commonWords.js

@@ -0,0 +1,13 @@
+/** Common words that must not be value-redacted even if length ≥ 8. */
+export const COMMON_WORDS = new Set([
+    "password",
+    "username",
+    "localhost",
+    "127.0.0.1",
+    "true",
+    "false",
+    "undefined",
+    "development",
+    "production",
+    "staging",
+]);

package/dist/logging/logger.d.ts

@@ -0,0 +1,49 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export type LogFormat = "json" | "pretty";
+export type LoggerBindings = {
+    component?: string;
+    run_id?: string;
+    stage_id?: string;
+    attempt?: number;
+};
+export type LogFields = Record<string, unknown>;
+export type LogRecord = {
+    ts: string;
+    level: LogLevel;
+    event: string;
+    msg: string;
+    component?: string;
+    run_id?: string;
+    stage_id?: string;
+    attempt?: number;
+    truncated?: boolean;
+    original_bytes?: number;
+} & LogFields;
+export type Logger = {
+    debug(event: string, msg: string, fields?: LogFields): void;
+    info(event: string, msg: string, fields?: LogFields): void;
+    warn(event: string, msg: string, fields?: LogFields): void;
+    error(event: string, msg: string, fields?: LogFields): void;
+    child(bindings: LoggerBindings): Logger;
+};
+export declare const LOG_FORMAT_ENV = "STAGEFLOW_LOG_FORMAT";
+export declare const LOG_LEVEL_ENV = "STAGEFLOW_LOG_LEVEL";
+export declare const LOG_MAX_LINE_BYTES_ENV = "STAGEFLOW_LOG_MAX_LINE_BYTES";
+export declare const DEFAULT_LOG_LEVEL: LogLevel;
+export declare const DEFAULT_LOG_MAX_LINE_BYTES = 8192;
+export type CreateLoggerOptions = {
+    env?: Record<string, string | undefined>;
+    stdoutIsTTY?: boolean;
+    format?: LogFormat;
+    level?: LogLevel;
+    maxLineBytes?: number;
+    knownSecrets?: readonly string[];
+    bindings?: LoggerBindings;
+    write?: (line: string) => void;
+    now?: () => Date;
+};
+export declare function resolveLogFormat(env?: Record<string, string | undefined>, stdoutIsTTY?: boolean): LogFormat;
+export declare function resolveLogLevel(env?: Record<string, string | undefined>): LogLevel;
+export declare function resolveLogMaxLineBytes(env?: Record<string, string | undefined>): number;
+export declare function createLogger(options?: CreateLoggerOptions): Logger;
+export declare const logger: Logger;

package/dist/logging/logger.js

@@ -0,0 +1,193 @@
+import { redact } from "./redact.js";
+import { getNamedSecrets } from "./namedSecrets.js";
+export const LOG_FORMAT_ENV = "STAGEFLOW_LOG_FORMAT";
+export const LOG_LEVEL_ENV = "STAGEFLOW_LOG_LEVEL";
+export const LOG_MAX_LINE_BYTES_ENV = "STAGEFLOW_LOG_MAX_LINE_BYTES";
+export const DEFAULT_LOG_LEVEL = "info";
+export const DEFAULT_LOG_MAX_LINE_BYTES = 8192;
+const LEVEL_RANK = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+export function resolveLogFormat(env = process.env, stdoutIsTTY = Boolean(process.stdout.isTTY)) {
+    const raw = env[LOG_FORMAT_ENV]?.trim().toLowerCase();
+    if (raw === "json" || raw === "pretty")
+        return raw;
+    return stdoutIsTTY ? "pretty" : "json";
+}
+export function resolveLogLevel(env = process.env) {
+    const raw = env[LOG_LEVEL_ENV]?.trim().toLowerCase();
+    if (raw === "debug" || raw === "info" || raw === "warn" || raw === "error") {
+        return raw;
+    }
+    return DEFAULT_LOG_LEVEL;
+}
+export function resolveLogMaxLineBytes(env = process.env) {
+    const raw = env[LOG_MAX_LINE_BYTES_ENV];
+    if (raw === undefined || raw.trim() === "")
+        return DEFAULT_LOG_MAX_LINE_BYTES;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 64)
+        return DEFAULT_LOG_MAX_LINE_BYTES;
+    return n;
+}
+function formatPretty(record) {
+    const parts = [
+        record.ts,
+        record.level.toUpperCase(),
+        record.component !== undefined ? `[${record.component}]` : undefined,
+        `${record.event}:`,
+        record.msg,
+    ].filter((part) => part !== undefined && part !== "");
+    const correlation = [];
+    if (record.run_id !== undefined)
+        correlation.push(`run_id=${record.run_id}`);
+    if (record.stage_id !== undefined) {
+        correlation.push(`stage_id=${record.stage_id}`);
+    }
+    if (record.attempt !== undefined) {
+        correlation.push(`attempt=${record.attempt}`);
+    }
+    if (record.truncated === true)
+        correlation.push("truncated=true");
+    const reserved = new Set([
+        "ts",
+        "level",
+        "event",
+        "msg",
+        "component",
+        "run_id",
+        "stage_id",
+        "attempt",
+        "truncated",
+        "original_bytes",
+    ]);
+    for (const [key, value] of Object.entries(record)) {
+        if (reserved.has(key))
+            continue;
+        if (value === undefined)
+            continue;
+        correlation.push(`${key}=${typeof value === "string" ? value : JSON.stringify(value)}`);
+    }
+    return correlation.length > 0
+        ? `${parts.join(" ")} ${correlation.join(" ")}`
+        : parts.join(" ");
+}
+function serializeRecord(record, format, maxLineBytes) {
+    if (format === "pretty") {
+        let line = formatPretty(record);
+        const bytes = Buffer.byteLength(line, "utf8");
+        if (bytes <= maxLineBytes)
+            return line;
+        const overhead = bytes - Buffer.byteLength(record.msg, "utf8");
+        const msgBudget = Math.max(0, maxLineBytes - overhead - 1);
+        const truncatedMsg = Buffer.from(record.msg, "utf8")
+            .subarray(0, msgBudget)
+            .toString("utf8");
+        return formatPretty({
+            ...record,
+            msg: truncatedMsg,
+            truncated: true,
+            original_bytes: bytes,
+        });
+    }
+    let payload = { ...record };
+    let line = JSON.stringify(payload);
+    let bytes = Buffer.byteLength(line, "utf8");
+    if (bytes <= maxLineBytes)
+        return line;
+    const originalBytes = bytes;
+    let lo = 0;
+    let hi = Buffer.byteLength(record.msg, "utf8");
+    let bestMsg = "";
+    while (lo <= hi) {
+        const mid = Math.floor((lo + hi) / 2);
+        const candidateMsg = Buffer.from(record.msg, "utf8")
+            .subarray(0, mid)
+            .toString("utf8");
+        payload = {
+            ...record,
+            msg: candidateMsg,
+            truncated: true,
+            original_bytes: originalBytes,
+        };
+        line = JSON.stringify(payload);
+        bytes = Buffer.byteLength(line, "utf8");
+        if (bytes <= maxLineBytes) {
+            bestMsg = candidateMsg;
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return JSON.stringify({
+        ...record,
+        msg: bestMsg,
+        truncated: true,
+        original_bytes: originalBytes,
+    });
+}
+export function createLogger(options = {}) {
+    const env = options.env ?? process.env;
+    const format = options.format ??
+        resolveLogFormat(env, options.stdoutIsTTY ?? Boolean(process.stdout.isTTY));
+    const level = options.level ?? resolveLogLevel(env);
+    const maxLineBytes = options.maxLineBytes ?? resolveLogMaxLineBytes(env);
+    const knownSecrets = options.knownSecrets ?? [];
+    const bindings = options.bindings ?? {};
+    const write = options.write ??
+        ((line) => {
+            process.stdout.write(`${line}\n`);
+        });
+    const now = options.now ?? (() => new Date());
+    const emit = (recordLevel, event, msg, fields) => {
+        if (LEVEL_RANK[recordLevel] < LEVEL_RANK[level])
+            return;
+        const record = {
+            ts: now().toISOString(),
+            level: recordLevel,
+            event,
+            msg,
+            ...bindings,
+            ...fields,
+        };
+        const redacted = redact(record, {
+            knownSecrets,
+            namedSecrets: getNamedSecrets(),
+        });
+        write(serializeRecord(redacted, format, maxLineBytes));
+    };
+    const logger = {
+        debug(event, msg, fields) {
+            emit("debug", event, msg, fields);
+        },
+        info(event, msg, fields) {
+            emit("info", event, msg, fields);
+        },
+        warn(event, msg, fields) {
+            emit("warn", event, msg, fields);
+        },
+        error(event, msg, fields) {
+            emit("error", event, msg, fields);
+        },
+        child(childBindings) {
+            return createLogger({
+                env,
+                format,
+                level,
+                maxLineBytes,
+                knownSecrets,
+                write,
+                now,
+                bindings: { ...bindings, ...childBindings },
+            });
+        },
+    };
+    return logger;
+}
+export const logger = createLogger({
+    bindings: { component: "host" },
+});

package/dist/logging/namedSecrets.d.ts

@@ -0,0 +1,6 @@
+import type { NamedSecret } from "../logging/redact.js";
+export declare const REDACTION_SECRETS_FILENAME = "redaction-secrets.json";
+export declare function registerNamedSecrets(secrets: readonly NamedSecret[]): void;
+export declare function clearNamedSecretsForTests(): void;
+export declare function getNamedSecrets(): readonly NamedSecret[];
+export declare function loadNamedSecretsFromAttemptDir(attemptDir: string): void;

package/dist/logging/namedSecrets.js

@@ -0,0 +1,58 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+let registry = [];
+export const REDACTION_SECRETS_FILENAME = "redaction-secrets.json";
+export function registerNamedSecrets(secrets) {
+    const next = [...registry];
+    for (const secret of secrets) {
+        const idx = next.findIndex((s) => s.name === secret.name);
+        if (idx >= 0)
+            next[idx] = secret;
+        else
+            next.push(secret);
+    }
+    registry = next;
+}
+export function clearNamedSecretsForTests() {
+    registry = [];
+}
+export function getNamedSecrets() {
+    return registry;
+}
+export function loadNamedSecretsFromAttemptDir(attemptDir) {
+    const filePath = path.join(attemptDir, REDACTION_SECRETS_FILENAME);
+    let raw;
+    try {
+        raw = readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return;
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return;
+    }
+    if (!Array.isArray(parsed))
+        return;
+    const secrets = [];
+    for (const item of parsed) {
+        if (item !== null &&
+            typeof item === "object" &&
+            typeof item.name === "string" &&
+            typeof item.value === "string") {
+            secrets.push({
+                name: item.name,
+                value: item.value,
+            });
+        }
+    }
+    if (secrets.length > 0) {
+        registerNamedSecrets(secrets);
+    }
+}

package/dist/logging/redact.d.ts

@@ -0,0 +1,13 @@
+export type NamedSecret = {
+    name: string;
+    value: string;
+};
+export type RedactOptions = {
+    patterns?: RegExp[];
+    knownSecrets?: readonly string[];
+    namedSecrets?: readonly NamedSecret[];
+};
+export declare function shouldRegisterValue(value: string): boolean;
+export declare function redactString(text: string, options?: RedactOptions): string;
+export declare function redact<T extends Record<string, unknown>>(record: T, options?: RedactOptions): T;
+export declare function stripUrlUserinfo(url: string): string;

package/dist/logging/redact.js

@@ -0,0 +1,88 @@
+import { COMMON_WORDS } from "./commonWords.js";
+const SECRET_PATTERNS = [
+    /\bsk-[A-Za-z0-9_-]{16,}\b/g,
+    /\bghp_[A-Za-z0-9]{20,}\b/g,
+    /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
+    /\bBearer\s+[A-Za-z0-9\-._~+/]+=*/gi,
+    /\b[A-Za-z_]*KEY[A-Za-z_]*\s*[:=]\s*['"]?[A-Za-z0-9+/_-]{16,}['"]?/gi,
+];
+const REDACTED = "[redacted]";
+export function shouldRegisterValue(value) {
+    if (value.length < 8)
+        return false;
+    const lower = value.toLowerCase();
+    if (COMMON_WORDS.has(lower))
+        return false;
+    return true;
+}
+function markerFor(name) {
+    return name !== undefined && name.length > 0
+        ? `[redacted:${name}]`
+        : REDACTED;
+}
+function replaceAll(haystack, needle, replacement) {
+    if (needle.length === 0 || !haystack.includes(needle))
+        return haystack;
+    return haystack.split(needle).join(replacement);
+}
+function scrubString(value, patterns, knownSecrets, namedSecrets) {
+    let out = value;
+    for (const pattern of patterns) {
+        out = out.replace(pattern, REDACTED);
+    }
+    for (const named of namedSecrets) {
+        if (!shouldRegisterValue(named.value))
+            continue;
+        const marker = markerFor(named.name);
+        out = replaceAll(out, named.value, marker);
+        out = replaceAll(out, Buffer.from(named.value, "utf8").toString("base64"), marker);
+        out = replaceAll(out, encodeURIComponent(named.value), marker);
+    }
+    for (const secret of knownSecrets) {
+        if (secret.length === 0)
+            continue;
+        if (!out.includes(secret))
+            continue;
+        out = replaceAll(out, secret, REDACTED);
+    }
+    return out;
+}
+function scrubValue(value, patterns, knownSecrets, namedSecrets) {
+    if (typeof value === "string") {
+        return scrubString(value, patterns, knownSecrets, namedSecrets);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => scrubValue(item, patterns, knownSecrets, namedSecrets));
+    }
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [key, child] of Object.entries(value)) {
+            out[key] = scrubValue(child, patterns, knownSecrets, namedSecrets);
+        }
+        return out;
+    }
+    return value;
+}
+export function redactString(text, options = {}) {
+    return scrubString(text, options.patterns ?? SECRET_PATTERNS, options.knownSecrets ?? [], options.namedSecrets ?? []);
+}
+export function redact(record, options = {}) {
+    const patterns = options.patterns ?? SECRET_PATTERNS;
+    const knownSecrets = options.knownSecrets ?? [];
+    const namedSecrets = options.namedSecrets ?? [];
+    return scrubValue(record, patterns, knownSecrets, namedSecrets);
+}
+export function stripUrlUserinfo(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.username || parsed.password) {
+            parsed.username = "";
+            parsed.password = "";
+            return parsed.toString();
+        }
+        return url;
+    }
+    catch {
+        return url.replace(/\/\/([^/@]+)@/g, "//");
+    }
+}