stageflow 0.25.0 → 0.30.0

package/dist/cli/browserCommand.js

@@ -0,0 +1,472 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { localAuditLogPath } from "../browser/auditSink.js";
+import { closeBrowserSession, defaultBrowserRunner } from "../browser/browserTeardown.js";
+import { defaultDisplayProbe, noScreenError } from "../browser/humanLogin.js";
+import { createLocalBrowserHost } from "../browser/localBrowserHost.js";
+import { createLocalProfileLock } from "../browser/localProfileLock.js";
+import { createLocalProfileStore } from "../browser/localProfileStore.js";
+import { matchLoginState, runLoginCheck } from "../browser/loginCheck.js";
+// TODO(multi-tenant): every `sf browser` command below uses the fixed local scope.
+// In a hosted service the scope must come from the signed-in user. Search for LOCAL_BROWSER_SCOPE in this file.
+import { InvalidProfileKeyError, LOCAL_BROWSER_SCOPE, validateProfileName, } from "../browser/profileStore.js";
+import { cliRunLive, createRunLiveness } from "../browser/runLiveness.js";
+import { loadHostConfig } from "../config/hostConfig.js";
+import { BlockedSiteError, hostOf, isBlockedHost } from "../browser/sitePolicy.js";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { createRunStore, storeNeedsHostMigration } from "../runstore/createStore.js";
+import { resolveStoreRoot } from "../runstore/paths.js";
+export const BROWSER_USAGE = `Usage:
+  sf browser profiles [--json]
+  sf browser status <name> [--json]
+  sf browser check <name> --url <url> --logged-in <glob> [--logged-out <glob>]... [--headless] [--json]
+  sf browser login <name> --url <login-url> --logged-in <glob> [--timeout-sec <n>] [--json]
+  sf browser clear <name> [--yes] [--json]
+
+Manage saved browser logins (profiles) on this computer. Output never shows profile paths or cookie values.
+Exit codes: 0 ok / logged in; 1 error; 2 profile in use by a live run; 3 logged out; 4 unknown; 5 login not completed (timeout or window closed); 130 interrupted.`;
+export const BROWSER_EXIT = {
+    ok: 0,
+    error: 1,
+    busy: 2,
+    loggedOut: 3,
+    unknown: 4,
+    notCompleted: 5,
+    interrupted: 130,
+};
+const DEFAULT_LOGIN_TIMEOUT_SEC = 300;
+const LOGIN_POLL_MS = 1000;
+const LOGIN_CLOSED_AFTER_FAILED_READS = 3;
+const STAGE_ID = "browser-cli";
+class CliError extends Error {
+    code;
+    exit;
+    constructor(message, code, exit) {
+        super(message);
+        this.code = code;
+        this.exit = exit;
+    }
+}
+function defaultIsRunLive() {
+    let inner;
+    return async (runId) => {
+        const cli = cliRunLive(runId);
+        if (cli !== undefined)
+            return cli;
+        try {
+            const home = globalStageflowHome();
+            if (!existsSync(path.join(resolveStoreRoot(home), "state.db")))
+                return false;
+            if (storeNeedsHostMigration(home))
+                return true;
+            inner ??= createRunLiveness(createRunStore({ rootDir: home, openerMode: "assert" }));
+            return await inner(runId);
+        }
+        catch {
+            return true;
+        }
+    };
+}
+function defaultSessionOpen(env) {
+    const dir = env.AGENT_BROWSER_SOCKET_DIR;
+    const session = env.AGENT_BROWSER_SESSION;
+    if (!dir || !session)
+        return false;
+    if (existsSync(path.join(dir, `${session}.sock`)))
+        return true;
+    try {
+        const pid = Number.parseInt(readFileSync(path.join(dir, `${session}.pid`), "utf8").trim(), 10);
+        if (!Number.isInteger(pid) || pid <= 0)
+            return false;
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function defaultAuditLastUsed() {
+    const out = {};
+    let text;
+    try {
+        text = readFileSync(localAuditLogPath(), "utf8");
+    }
+    catch {
+        return out;
+    }
+    for (const line of text.split("\n")) {
+        if (line.length === 0)
+            continue;
+        try {
+            const rec = JSON.parse(line);
+            if (rec.event === "profile_used" &&
+                rec.scope === LOCAL_BROWSER_SCOPE &&
+                typeof rec.profile === "string" &&
+                typeof rec.at === "string" &&
+                (out[rec.profile] === undefined || rec.at > out[rec.profile])) {
+                out[rec.profile] = rec.at;
+            }
+        }
+        catch {
+            // skip bad line
+        }
+    }
+    return out;
+}
+async function defaultConfirm(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await new Promise((resolve) => rl.question(`${question} [y/N] `, resolve));
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+function defaultDeps() {
+    const isRunLive = defaultIsRunLive();
+    return {
+        log: (line) => console.log(line),
+        error: (line) => console.error(line),
+        store: createLocalProfileStore(),
+        host: createLocalBrowserHost(),
+        locks: createLocalProfileLock({ isRunLive }),
+        runner: defaultBrowserRunner,
+        display: () => defaultDisplayProbe(),
+        isRunLive,
+        sessionOpen: defaultSessionOpen,
+        auditLastUsed: defaultAuditLastUsed,
+        confirm: defaultConfirm,
+        interactive: Boolean(process.stdin.isTTY),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    };
+}
+function parse(args) {
+    const out = { help: false, json: false, loggedOut: [], headless: false, yes: false };
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        out.help = true;
+        return out;
+    }
+    out.sub = args[0];
+    if (!["profiles", "status", "check", "login", "clear"].includes(out.sub)) {
+        throw new Error(`Unknown browser subcommand: ${out.sub}`);
+    }
+    const value = (i, flag) => {
+        const v = args[i];
+        if (v === undefined || v.length === 0 || v.startsWith("--")) {
+            throw new Error(`Missing value for ${flag}`);
+        }
+        return v;
+    };
+    for (let i = 1; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--help" || a === "-h")
+            out.help = true;
+        else if (a === "--json")
+            out.json = true;
+        else if (a === "--headless")
+            out.headless = true;
+        else if (a === "--yes" || a === "-y")
+            out.yes = true;
+        else if (a === "--url")
+            out.url = value(++i, a);
+        else if (a === "--logged-in")
+            out.loggedIn = value(++i, a);
+        else if (a === "--logged-out")
+            out.loggedOut.push(value(++i, a));
+        else if (a === "--timeout-sec") {
+            const n = Number(value(++i, a));
+            if (!Number.isFinite(n) || n <= 0)
+                throw new Error(`Invalid --timeout-sec: ${args[i]}`);
+            out.timeoutSec = n;
+        }
+        else if (a.startsWith("-"))
+            throw new Error(`Unknown flag: ${a}`);
+        else if (out.name === undefined && out.sub !== "profiles")
+            out.name = a;
+        else
+            throw new Error(`Unexpected argument: ${a}`);
+    }
+    return out;
+}
+function requireName(p) {
+    if (p.name === undefined)
+        throw new Error(`sf browser ${p.sub} needs a profile name`);
+    return validateProfileName(p.name);
+}
+function newOwner() {
+    return { runId: `cli-${process.pid}-${randomBytes(4).toString("hex")}`, stageId: STAGE_ID };
+}
+async function withProfile(deps, name, fn, options) {
+    const names = await deps.store.list(LOCAL_BROWSER_SCOPE);
+    if (!options.create && !names.includes(name)) {
+        throw new CliError(`Profile "${name}" does not exist. Create it with sf browser login.`, "not_found", BROWSER_EXIT.error);
+    }
+    const owner = newOwner();
+    const got = await deps.locks.acquire({ scope: LOCAL_BROWSER_SCOPE, name }, owner);
+    if (got.status === "queued") {
+        throw new CliError(`Profile "${name}" is in use by run ${got.holder.runId}${got.holder.stageId !== undefined ? ` stage ${got.holder.stageId}` : ""}. Try again when it finishes.`, "profile_busy", BROWSER_EXIT.busy);
+    }
+    try {
+        const handle = await deps.store.open({ scope: LOCAL_BROWSER_SCOPE, name });
+        return await fn(handle);
+    }
+    finally {
+        await got.release().catch(() => undefined);
+    }
+}
+async function envFor(deps, handle, browser, humanLogin = false) {
+    return deps.host.profileBrowserEnv({
+        runId: newOwner().runId,
+        browser,
+        profile: handle,
+        ...(humanLogin ? { humanLogin: true } : {}),
+    });
+}
+function emit(deps, json, doc, text) {
+    if (json)
+        deps.log(JSON.stringify(doc, null, 2));
+    else
+        for (const line of text)
+            deps.log(line);
+}
+function closeOpts(deps) {
+    return {
+        runner: deps.runner,
+        ...(deps.closeWaitMs !== undefined ? { closeWaitMs: deps.closeWaitMs } : {}),
+    };
+}
+async function profilesCmd(deps, p) {
+    const names = await deps.store.list(LOCAL_BROWSER_SCOPE);
+    const audited = await deps.auditLastUsed().catch(() => ({}));
+    const profiles = [];
+    for (const name of names) {
+        let last = audited[name];
+        try {
+            const handle = await deps.store.open({ scope: LOCAL_BROWSER_SCOPE, name });
+            const iso = (await stat(handle.profileDir)).mtime.toISOString();
+            if (last === undefined || iso > last)
+                last = iso;
+        }
+        catch {
+            // store without a real folder
+        }
+        profiles.push({ name, last_used: last ?? null });
+    }
+    emit(deps, p.json, { profiles }, profiles.length === 0
+        ? []
+        : profiles.map((x) => `${x.name}\t${x.last_used ?? "never"}`));
+    return BROWSER_EXIT.ok;
+}
+async function statusCmd(deps, p) {
+    const name = requireName(p);
+    const exists = (await deps.store.list(LOCAL_BROWSER_SCOPE)).includes(name);
+    let lock = null;
+    const holder = await deps.locks.holder({ scope: LOCAL_BROWSER_SCOPE, name });
+    if (holder !== undefined) {
+        lock = {
+            run_id: holder.runId,
+            stage_id: holder.stageId ?? null,
+            live: await deps.isRunLive(holder.runId).catch(() => true),
+        };
+    }
+    let sessionOpen = false;
+    if (exists) {
+        const handle = await deps.store.open({ scope: LOCAL_BROWSER_SCOPE, name });
+        sessionOpen = deps.sessionOpen(await envFor(deps, handle, { profile: name }));
+    }
+    const doc = { name, exists, locked: lock !== null, lock, session_open: sessionOpen };
+    emit(deps, p.json, doc, [
+        `profile: ${name}`,
+        `exists: ${exists ? "yes" : "no"}`,
+        lock === null
+            ? "lock: free"
+            : `lock: held by run ${lock.run_id}${lock.stage_id !== null ? ` stage ${lock.stage_id}` : ""}${lock.live ? "" : " (stale)"}`,
+        `browser session: ${sessionOpen ? "open" : "closed"}`,
+    ]);
+    return BROWSER_EXIT.ok;
+}
+function assertUrlAllowed(deps, url) {
+    const host = hostOf(url);
+    if (host === undefined)
+        return;
+    const blocked = deps.blockedSites ?? loadHostConfig().browserBlockedSites;
+    if (isBlockedHost(host, blocked) !== undefined) {
+        throw new BlockedSiteError(`sf browser: --url "${host}" is blocked by Host policy (browser.blocked_sites)`);
+    }
+}
+async function checkCmd(deps, p) {
+    const name = requireName(p);
+    if (p.url === undefined || p.loggedIn === undefined) {
+        throw new Error("sf browser check needs --url and --logged-in");
+    }
+    assertUrlAllowed(deps, p.url);
+    const check = {
+        url: p.url,
+        logged_in_url: p.loggedIn,
+        ...(p.loggedOut.length > 0 ? { logged_out_url: p.loggedOut } : {}),
+    };
+    return withProfile(deps, name, async (handle) => {
+        const env = await envFor(deps, handle, { profile: name, headed: !p.headless, check });
+        try {
+            const result = await runLoginCheck(env, check, deps.runner, deps.loginCheck);
+            emit(deps, p.json, { logged_in: result.logged_in, url: result.url, state: result.state }, [
+                `state: ${result.state}`,
+                `logged_in: ${result.logged_in === null ? "unknown" : result.logged_in}`,
+                `url: ${result.url}`,
+            ]);
+            return result.state === "logged_in"
+                ? BROWSER_EXIT.ok
+                : result.state === "logged_out"
+                    ? BROWSER_EXIT.loggedOut
+                    : BROWSER_EXIT.unknown;
+        }
+        finally {
+            await closeBrowserSession(env, closeOpts(deps)).catch(() => undefined);
+        }
+    }, { create: false });
+}
+async function loginCmd(deps, p) {
+    const name = requireName(p);
+    if (p.url === undefined || p.loggedIn === undefined) {
+        throw new Error("sf browser login needs --url and --logged-in");
+    }
+    assertUrlAllowed(deps, p.url);
+    const screen = deps.display();
+    if (!screen.hasDisplay)
+        throw noScreenError(screen.docker);
+    let signal = deps.signal;
+    if (signal === undefined) {
+        const controller = new AbortController();
+        process.once("SIGINT", () => controller.abort());
+        signal = controller.signal;
+    }
+    const timeoutMs = (p.timeoutSec ?? DEFAULT_LOGIN_TIMEOUT_SEC) * 1000;
+    const pollMs = deps.loginPollMs ?? LOGIN_POLL_MS;
+    return withProfile(deps, name, async (handle) => {
+        const env = await envFor(deps, handle, { profile: name, headed: true }, true);
+        let status = "timeout";
+        let url = "";
+        try {
+            const opened = await deps.runner(["open", p.url], env);
+            if (opened.code !== 0)
+                throw new CliError(`Could not open ${p.url}`, "open_failed", BROWSER_EXIT.error);
+            if (!p.json)
+                deps.error("Log in in the browser window. Waiting for the login to finish (Ctrl-C to stop).");
+            const deadline = Date.now() + timeoutMs;
+            let failedReads = 0;
+            for (;;) {
+                if (signal.aborted) {
+                    status = "interrupted";
+                    break;
+                }
+                const got = await deps.runner(["get", "url"], env).catch(() => ({ code: 1, stdout: "" }));
+                if (got.code === 0) {
+                    failedReads = 0;
+                    url = (got.stdout ?? "").trim();
+                    if (matchLoginState({ finalUrl: url, check: { logged_in_url: p.loggedIn } }).state === "logged_in") {
+                        status = "logged_in";
+                        break;
+                    }
+                }
+                else if (++failedReads >= LOGIN_CLOSED_AFTER_FAILED_READS) {
+                    status = "closed";
+                    break;
+                }
+                if (Date.now() >= deadline)
+                    break;
+                await deps.sleep(pollMs);
+            }
+        }
+        finally {
+            await closeBrowserSession(env, closeOpts(deps)).catch(() => undefined);
+        }
+        const doc = { logged_in: status === "logged_in", url, state: status };
+        emit(deps, p.json, doc, [
+            status === "logged_in"
+                ? `Logged in. Profile "${name}" is saved.`
+                : status === "interrupted"
+                    ? "Stopped before login finished."
+                    : status === "closed"
+                        ? "The browser window was closed before login finished."
+                        : "Timed out before login finished.",
+        ]);
+        return status === "logged_in"
+            ? BROWSER_EXIT.ok
+            : status === "interrupted"
+                ? BROWSER_EXIT.interrupted
+                : BROWSER_EXIT.notCompleted;
+    }, { create: true });
+}
+async function clearCmd(deps, p) {
+    const name = requireName(p);
+    if (!(await deps.store.list(LOCAL_BROWSER_SCOPE)).includes(name)) {
+        throw new CliError(`Profile "${name}" does not exist.`, "not_found", BROWSER_EXIT.error);
+    }
+    if (!p.yes) {
+        if (!deps.interactive) {
+            throw new CliError(`Refusing to delete profile "${name}" without confirmation. Pass --yes.`, "confirmation_required", BROWSER_EXIT.error);
+        }
+        if (!(await deps.confirm(`Delete browser profile "${name}" and its saved logins?`))) {
+            emit(deps, p.json, { cleared: false, name }, ["Cancelled."]);
+            return BROWSER_EXIT.error;
+        }
+    }
+    return withProfile(deps, name, async (handle) => {
+        const env = await envFor(deps, handle, { profile: name });
+        await closeBrowserSession(env, closeOpts(deps)).catch(() => undefined);
+        await deps.store.delete({ scope: LOCAL_BROWSER_SCOPE, name });
+        emit(deps, p.json, { cleared: true, name }, [`Cleared profile "${name}".`]);
+        return BROWSER_EXIT.ok;
+    }, { create: false });
+}
+export async function runBrowserCommand(args, deps) {
+    let json = args.includes("--json");
+    const io = deps?.log !== undefined && deps?.error !== undefined
+        ? { log: deps.log, error: deps.error }
+        : { log: (l) => console.log(l), error: (l) => console.error(l) };
+    let parsed;
+    try {
+        parsed = parse(args);
+        json = parsed.json;
+    }
+    catch (err) {
+        io.error(err.message);
+        io.error(BROWSER_USAGE);
+        return BROWSER_EXIT.error;
+    }
+    if (parsed.help) {
+        io.log(BROWSER_USAGE);
+        return BROWSER_EXIT.ok;
+    }
+    const resolved = { ...defaultDeps(), ...deps };
+    try {
+        switch (parsed.sub) {
+            case "profiles":
+                return await profilesCmd(resolved, parsed);
+            case "status":
+                return await statusCmd(resolved, parsed);
+            case "check":
+                return await checkCmd(resolved, parsed);
+            case "login":
+                return await loginCmd(resolved, parsed);
+            default:
+                return await clearCmd(resolved, parsed);
+        }
+    }
+    catch (err) {
+        const cli = err instanceof CliError ? err : undefined;
+        const code = cli?.code ?? (err instanceof InvalidProfileKeyError || err instanceof BlockedSiteError
+            ? err.code
+            : "error");
+        const message = err.message;
+        if (json)
+            resolved.log(JSON.stringify({ error: message, code }, null, 2));
+        else
+            resolved.error(message);
+        return cli?.exit ?? BROWSER_EXIT.error;
+    }
+}

package/dist/cli/debugRunCommand.d.ts

@@ -0,0 +1,10 @@
+export declare const DEBUG_RUN_USAGE = "Usage:\n  sf debug-run <runId> [--out <file>]";
+export type DebugRunCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function runDebugRunCommand(args: string[], options?: {
+    cwd?: string;
+    projectRoot?: string;
+    io?: Partial<DebugRunCommandIo>;
+}): Promise<number>;

package/dist/cli/debugRunCommand.js

@@ -0,0 +1,109 @@
+import { writeFileSync } from "node:fs";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { createRunStoreAfterHostEnsure } from "../runstore/createStore.js";
+import { buildDebugBundle } from "../runstore/debugBundle.js";
+import { ensureGlobalService } from "../server/ensureGlobalService.js";
+import { resolveSafeOutPath } from "./resolveSafeOutPath.js";
+export const DEBUG_RUN_USAGE = `Usage:
+  sf debug-run <runId> [--out <file>]`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+function parseDebugRunArgs(args) {
+    if (args.length === 0) {
+        return { help: false };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true };
+    }
+    let runId;
+    let outPath;
+    let help = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--out") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --out");
+            }
+            outPath = value;
+        }
+        else if (arg.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else if (runId === undefined) {
+            runId = arg;
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+    }
+    return { help, runId, outPath };
+}
+const DEBUGABLE_STATUSES = new Set([
+    "running",
+    "succeeded",
+    "failed",
+    "cancelled",
+    "queued",
+    "created",
+]);
+function assertRunDebugable(status, runId) {
+    if (DEBUGABLE_STATUSES.has(status)) {
+        return;
+    }
+    throw new Error(`run cannot be debugged: ${runId} (status: ${status})`);
+}
+export async function runDebugRunCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const out = { ...defaultIo, ...options.io };
+    let parsed;
+    try {
+        parsed = parseDebugRunArgs(args);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        out.error(DEBUG_RUN_USAGE);
+        return 1;
+    }
+    if (parsed.help) {
+        out.error(DEBUG_RUN_USAGE);
+        return 0;
+    }
+    if (!parsed.runId) {
+        out.error("Missing <runId>");
+        out.error(DEBUG_RUN_USAGE);
+        return 1;
+    }
+    const opened = await createRunStoreAfterHostEnsure({ rootDir: globalStageflowHome() }, () => ensureGlobalService());
+    if (!opened.ok) {
+        out.error(opened.message);
+        return 1;
+    }
+    const store = opened.store;
+    try {
+        const detail = await store.readRun(parsed.runId);
+        assertRunDebugable(detail.status, parsed.runId);
+        const bundle = await buildDebugBundle(store, parsed.runId);
+        const json = JSON.stringify(bundle, null, 2);
+        if (parsed.outPath !== undefined) {
+            const target = resolveSafeOutPath(parsed.outPath, cwd);
+            writeFileSync(target, json, "utf8");
+            out.error(`Wrote ${target}`);
+        }
+        else {
+            out.log(json);
+        }
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        return 1;
+    }
+}

package/dist/cli/doctorCommand.d.ts

@@ -0,0 +1,32 @@
+import { type PipelinePreflightResult } from "../preflight/pipelinePreflight.js";
+import type { RunStore } from "../runstore/port.js";
+export type DoctorCheckStatus = "pass" | "warn" | "fail" | "skipped";
+export type DoctorCheck = {
+    id: string;
+    status: DoctorCheckStatus;
+    message: string;
+    code?: string;
+};
+export type DoctorResult = {
+    ok: boolean;
+    checks: DoctorCheck[];
+    preflight?: PipelinePreflightResult;
+};
+export type DoctorCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function runDoctorChecks(options?: {
+    cwd?: string;
+    homeDir?: string;
+    store?: RunStore;
+    env?: NodeJS.ProcessEnv;
+    pipeline?: string;
+    strict?: boolean;
+}): Promise<DoctorResult>;
+export declare function runDoctorCommand(args: string[], options?: {
+    cwd?: string;
+    io?: Partial<DoctorCommandIo>;
+    runChecks?: typeof runDoctorChecks;
+}): Promise<number>;
+export declare const DOCTOR_USAGE = "Usage:\n  sf doctor [--json] [--pipeline <path>] [--strict]\n\nRun Host preflight checks (shared /readyz store/home/migrations/git, full PRAGMA integrity_check, plus bash, Node, credentials, TLS CA paths, free disk, MCP commands).\nWith --pipeline, also checks pipeline requires:/secrets:/mcp against the toolchain manifest and curated stage env.\n--strict treats unknown_version as failure (default: warn/pass).\nDo not use sf doctor as a container HEALTHCHECK \u2014 use GET /livez instead.\n";