stageflow 0.25.0 → 0.30.0

package/dist/cli/doctorCommand.js

@@ -0,0 +1,453 @@
+import { accessSync, constants } from "node:fs";
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { getCredentialSourceSettings } from "../agent/providerAuth.js";
+import { probeGitVersion, runReadyzChecks, } from "../diagnostics/checks.js";
+import { findMissingMcpCommands } from "../preflight/mcpCommands.js";
+import { assertBashAvailable } from "../preflight/bash.js";
+import { warnMissingCaPaths } from "../preflight/tls.js";
+import { runPipelinePreflight, } from "../preflight/pipelinePreflight.js";
+import { loadPipelineOutcome } from "../config/loadPipeline.js";
+import { MCP_CATALOG_FILENAME } from "../config/resolveStageMcpServers.js";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { createRunStore } from "../runstore/createStore.js";
+import { readFilesystemSize, resolveMinFreeDiskFloor, } from "../runstore/diskUsage.js";
+import { runStoreIntegrityCheck } from "../runstore/sqlite/applyStorePragmas.js";
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+const PROVIDER_KEY_RE = /^STAGEFLOW_PROVIDER_([A-Za-z0-9_]+)_API_KEY$/;
+const PROVIDER_FILE_RE = /^STAGEFLOW_PROVIDER_([A-Za-z0-9_]+)_API_KEY_FILE$/;
+function mapReadyzChecks(result, home) {
+    const out = [];
+    const { checks } = result;
+    if (checks.store_openable) {
+        out.push({
+            id: "store_openable",
+            status: "pass",
+            message: "Run store is openable",
+        });
+    }
+    else {
+        out.push({
+            id: "store_openable",
+            status: "fail",
+            code: "store_not_openable",
+            message: "Run store could not be opened or queried",
+        });
+    }
+    if (checks.home_writable) {
+        out.push({
+            id: "home_writable",
+            status: "pass",
+            message: `${home} is writable`,
+        });
+    }
+    else {
+        const uid = process.getuid?.() ?? 0;
+        const gid = process.getgid?.() ?? 0;
+        out.push({
+            id: "home_writable",
+            status: "fail",
+            code: "home_not_writable",
+            message: `STAGEFLOW_HOME is not writable (${home}). Running as uid=${uid} gid=${gid}. Try: sudo chown -R ${uid}:${gid} ${home}`,
+        });
+    }
+    if (checks.migrations_complete) {
+        out.push({
+            id: "migrations_complete",
+            status: "pass",
+            message: "Store migrations are complete",
+        });
+    }
+    else {
+        out.push({
+            id: "migrations_complete",
+            status: "fail",
+            code: "migrations_incomplete",
+            message: "Store schema migrations are incomplete",
+        });
+    }
+    return out;
+}
+function storeIntegrityDoctorCheck(store) {
+    const connection = store.connection;
+    if (connection === undefined || typeof connection.pragma !== "function") {
+        return {
+            id: "store_integrity",
+            status: "skipped",
+            message: "Store has no sqlite connection for integrity_check",
+        };
+    }
+    const outcome = runStoreIntegrityCheck({
+        pragma: (source, options) => connection.pragma(source, options),
+    });
+    if (outcome.ok) {
+        return {
+            id: "store_integrity",
+            status: "pass",
+            message: "PRAGMA integrity_check passed",
+        };
+    }
+    return {
+        id: "store_integrity",
+        status: "fail",
+        code: "store_integrity_failed",
+        message: `store_integrity_failed: integrity_check returned ${outcome.detail}. Refuse to serve; restore with sf restore.`,
+    };
+}
+async function gitDoctorCheck(gitPresent) {
+    if (!gitPresent) {
+        return {
+            id: "git",
+            status: "fail",
+            code: "git_not_present",
+            message: "git was not found on PATH",
+        };
+    }
+    const version = await probeGitVersion();
+    return {
+        id: "git",
+        status: "pass",
+        message: version ?? "git is present",
+    };
+}
+function bashCheck() {
+    try {
+        const bashPath = assertBashAvailable();
+        return { id: "bash", status: "pass", message: `bash at ${bashPath}` };
+    }
+    catch (err) {
+        return {
+            id: "bash",
+            status: "fail",
+            code: "bash_not_found",
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function nodeVersionCheck() {
+    const major = Number(process.versions.node.split(".")[0]);
+    if (major >= 20) {
+        return {
+            id: "node",
+            status: "pass",
+            message: `Node ${process.version}`,
+        };
+    }
+    return {
+        id: "node",
+        status: "warn",
+        message: `Node ${process.version}; engines floor may differ from Pi/better-sqlite3 (not bumping engines.node)`,
+    };
+}
+function discoverProviderEnvIds(env) {
+    const byLower = new Set();
+    for (const key of Object.keys(env)) {
+        let envId;
+        const plain = key.match(PROVIDER_KEY_RE);
+        if (plain)
+            envId = plain[1];
+        else {
+            const file = key.match(PROVIDER_FILE_RE);
+            if (file)
+                envId = file[1];
+        }
+        if (envId === undefined)
+            continue;
+        byLower.add(envId.toLowerCase().replace(/_/g, "-"));
+    }
+    return [...byLower].sort();
+}
+function credentialsCheck(cwd, env) {
+    const providerIds = discoverProviderEnvIds(env);
+    let sourceNote = "";
+    try {
+        const settings = getCredentialSourceSettings(cwd);
+        const source = settings.credentialSource ?? settings.binding.source;
+        sourceNote = `; credentialSource=${source}`;
+    }
+    catch {
+        /* ignore settings read failures */
+    }
+    if (providerIds.length === 0) {
+        return {
+            id: "credentials",
+            status: "warn",
+            message: `No STAGEFLOW_PROVIDER_*_API_KEY set${sourceNote}`,
+        };
+    }
+    return {
+        id: "credentials",
+        status: "pass",
+        message: `Provider credentials in env: ${providerIds.join(", ")}${sourceNote}`,
+    };
+}
+function tlsCheck(env) {
+    const missing = warnMissingCaPaths(env);
+    if (missing.length === 0) {
+        const configured = ["NODE_EXTRA_CA_CERTS", "SSL_CERT_FILE", "SSL_CERT_DIR"].filter((name) => Boolean(env[name]?.trim()));
+        if (configured.length === 0) {
+            return {
+                id: "tls_ca_paths",
+                status: "skipped",
+                message: "No NODE_EXTRA_CA_CERTS / SSL_CERT_FILE / SSL_CERT_DIR set",
+            };
+        }
+        return {
+            id: "tls_ca_paths",
+            status: "pass",
+            message: `CA paths exist: ${configured.join(", ")}`,
+        };
+    }
+    return {
+        id: "tls_ca_paths",
+        status: "warn",
+        code: "ca_path_missing",
+        message: missing
+            .map((w) => `${w.name}=${w.path} does not exist`)
+            .join("; "),
+    };
+}
+async function freeDiskCheck(home, env) {
+    try {
+        const size = await readFilesystemSize(home);
+        const floor = resolveMinFreeDiskFloor(env.STAGEFLOW_MIN_FREE_DISK_BYTES, size.totalBytes);
+        const freeGiB = (size.freeBytes / (1024 * 1024 * 1024)).toFixed(2);
+        if (size.freeBytes < floor) {
+            return {
+                id: "free_disk",
+                status: "warn",
+                code: "insufficient_disk",
+                message: `${home} has ${freeGiB} GiB free (below floor ${floor} bytes)`,
+            };
+        }
+        return {
+            id: "free_disk",
+            status: "pass",
+            message: `${home} has ${freeGiB} GiB free`,
+        };
+    }
+    catch (err) {
+        return {
+            id: "free_disk",
+            status: "warn",
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+async function mcpCommandsCheck(cwd) {
+    const mcpPath = path.join(cwd, MCP_CATALOG_FILENAME);
+    try {
+        accessSync(mcpPath, constants.R_OK);
+    }
+    catch {
+        return [
+            {
+                id: "mcp_commands",
+                status: "skipped",
+                message: `No ${MCP_CATALOG_FILENAME} in ${cwd}`,
+            },
+        ];
+    }
+    try {
+        const raw = JSON.parse(await readFile(mcpPath, "utf8"));
+        const missing = findMissingMcpCommands(raw.mcpServers ?? {});
+        if (missing.length === 0) {
+            return [
+                {
+                    id: "mcp_commands",
+                    status: "pass",
+                    message: "All .mcp.json commands found on PATH",
+                },
+            ];
+        }
+        return missing.map((m) => ({
+            id: `mcp_command:${m.serverName}`,
+            status: "warn",
+            code: "command_not_on_path",
+            message: `MCP server "${m.serverName}" command "${m.command}" is not on PATH`,
+        }));
+    }
+    catch (err) {
+        return [
+            {
+                id: "mcp_commands",
+                status: "warn",
+                message: err instanceof Error ? err.message : String(err),
+            },
+        ];
+    }
+}
+function preflightToDoctorChecks(preflight, strict) {
+    return preflight.checks.map((c, i) => {
+        const id = c.kind === "toolchain"
+            ? `toolchain:${c.tool ?? i}`
+            : c.kind === "secret"
+                ? `secret:${c.secret ?? i}`
+                : `mcp:${c.server ?? c.stageId ?? i}`;
+        let status = "pass";
+        if (c.status === "ok") {
+            status = "pass";
+        }
+        else if (c.status === "unknown_version" && !strict) {
+            status = "warn";
+        }
+        else {
+            status = "fail";
+        }
+        return {
+            id,
+            status,
+            code: c.status === "ok" ? undefined : c.status,
+            message: c.message ??
+                (c.kind === "toolchain"
+                    ? `${c.tool}: ${c.status}${c.required ? ` (required ${c.required})` : ""}${c.found ? `; found ${c.found}` : ""}`
+                    : c.status),
+        };
+    });
+}
+export async function runDoctorChecks(options) {
+    const cwd = options?.cwd ?? process.cwd();
+    const home = options?.homeDir ?? globalStageflowHome();
+    const env = options?.env ?? process.env;
+    const strict = options?.strict === true;
+    const checks = [];
+    let store = options?.store;
+    let closeStore = false;
+    if (store === undefined) {
+        try {
+            store = createRunStore({ rootDir: home, openerMode: "migrate" });
+            closeStore = true;
+        }
+        catch (err) {
+            checks.push({
+                id: "store_openable",
+                status: "fail",
+                code: "store_not_openable",
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    if (store !== undefined) {
+        const readyz = await runReadyzChecks({
+            store,
+            homeDir: home,
+            bypassCache: true,
+        });
+        checks.push(...mapReadyzChecks(readyz, home));
+        checks.push(storeIntegrityDoctorCheck(store));
+        checks.push(await gitDoctorCheck(readyz.checks.git_present));
+    }
+    checks.push(bashCheck());
+    checks.push(nodeVersionCheck());
+    checks.push(credentialsCheck(cwd, env));
+    checks.push(tlsCheck(env));
+    checks.push(await freeDiskCheck(home, env));
+    checks.push(...(await mcpCommandsCheck(cwd)));
+    let preflight;
+    if (options?.pipeline !== undefined) {
+        const outcome = await loadPipelineOutcome(options.pipeline, { cwd });
+        if (!outcome.ok) {
+            checks.push({
+                id: "pipeline_load",
+                status: "fail",
+                code: outcome.issues[0]?.code ?? "pipeline.load_error",
+                message: outcome.issues[0]?.message ?? "Failed to load pipeline",
+            });
+        }
+        else {
+            preflight = await runPipelinePreflight(outcome.value, {
+                projectRoot: cwd,
+                hostEnv: env,
+                strict,
+            });
+            checks.push(...preflightToDoctorChecks(preflight, strict));
+        }
+    }
+    if (closeStore && store !== undefined) {
+        try {
+            await store.close();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    const ok = !checks.some((c) => c.status === "fail");
+    return { ok, checks, ...(preflight !== undefined ? { preflight } : {}) };
+}
+function parseDoctorArgs(args) {
+    let help = false;
+    let json = false;
+    let strict = false;
+    let pipeline;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg === "--strict") {
+            strict = true;
+        }
+        else if (arg === "--pipeline") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --pipeline");
+            }
+            pipeline = value;
+        }
+        else if (arg.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+    }
+    return { help, json, strict, pipeline };
+}
+export async function runDoctorCommand(args, options = {}) {
+    const out = { ...defaultIo, ...options.io };
+    const runChecks = options.runChecks ?? runDoctorChecks;
+    try {
+        const parsed = parseDoctorArgs(args);
+        if (parsed.help) {
+            out.error(DOCTOR_USAGE);
+            return 0;
+        }
+        const result = await runChecks({
+            cwd: options.cwd,
+            pipeline: parsed.pipeline,
+            strict: parsed.strict,
+        });
+        if (parsed.json) {
+            out.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            for (const check of result.checks) {
+                out.log(`[${check.status}] ${check.id}: ${check.message}`);
+            }
+            if (!result.ok) {
+                out.error("sf doctor reported failures. Do not use doctor as a container HEALTHCHECK; use GET /livez.");
+            }
+        }
+        return result.ok ? 0 : 1;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        out.error(DOCTOR_USAGE);
+        return 1;
+    }
+}
+export const DOCTOR_USAGE = `Usage:
+  sf doctor [--json] [--pipeline <path>] [--strict]
+
+Run Host preflight checks (shared /readyz store/home/migrations/git, full PRAGMA integrity_check, plus bash, Node, credentials, TLS CA paths, free disk, MCP commands).
+With --pipeline, also checks pipeline requires:/secrets:/mcp against the toolchain manifest and curated stage env.
+--strict treats unknown_version as failure (default: warn/pass).
+Do not use sf doctor as a container HEALTHCHECK — use GET /livez instead.
+`;

package/dist/cli/envelopeCommand.js

@@ -2,7 +2,8 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { buildHandoffDeliverable, isHandoffSkipped, } from "./handoffFormat.js";
 import { globalStageflowHome } from "../project/globalHome.js";
-import { createRunStore } from "../runstore/createStore.js";
+import { createRunStoreAfterHostEnsure, } from "../runstore/createStore.js";
+import { ensureGlobalService, } from "../server/ensureGlobalService.js";
 export const ENVELOPE_USAGE = `Usage:
   sf envelope get --run <runId> --stage <stageId> [--json] [--from <sf-run.json>] [--detect-stage <id>] [--format envelope|handoff]`;
 const defaultIo = {
@@ -224,7 +225,13 @@ export async function runEnvelopeCommand(args, options = {}) {
         out.error(ENVELOPE_USAGE);
         return 1;
     }
-    const store = createRunStore({ rootDir: globalStageflowHome() });
+    const opened = await createRunStoreAfterHostEnsure({ rootDir: globalStageflowHome() }, () => ensureGlobalService());
+    if (!opened.ok) {
+        out.error(opened.message);
+        out.error(ENVELOPE_USAGE);
+        return 1;
+    }
+    const store = opened.store;
     let runContext;
     try {
         runContext = resolveRunContext(parsed, cwd, store);

package/dist/cli/exportAllCommand.d.ts

@@ -0,0 +1,55 @@
+import { projectRun } from "../projection/projectRun.js";
+import type { ListRunsFilter } from "../runstore/port.js";
+export declare const EXPORT_ALL_USAGE = "Usage:\n  sf export --all [--status <status>] [--since <iso>] [--pipeline <id-or-path>] [--out <file>]\n\nStreams whole-instance NDJSON (header + one projectRun line per run, including\nnon-terminal). Not a backup \u2014 restore does not accept export streams.";
+export type ExportAllCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export type ExportHeader = {
+    type: "stageflow_export";
+    version: 1;
+    stageflow_version: string;
+    created_at: string;
+    filter?: ListRunsFilter;
+};
+export type ExportPipelineSource = {
+    kind: "path";
+    path: string;
+    pipeline: null;
+} | {
+    kind: "inline";
+    pipeline: unknown;
+} | {
+    kind: "unavailable";
+    pipeline: null;
+    note: string;
+};
+export type ExportRunLine = {
+    type: "projectRun";
+    run: ReturnType<typeof projectRun> & {
+        pipeline_source: ExportPipelineSource;
+    };
+};
+export declare function buildExportHeader(filter?: ListRunsFilter, now?: Date): ExportHeader;
+export declare function resolveExportPipelineSource(options: {
+    pipelineSource?: "inline" | "path";
+    pipelinePath?: string;
+    pipelineBody?: string | null;
+}): ExportPipelineSource;
+export declare function projectRunForExport(detail: Parameters<typeof projectRun>[0], pipelineBody?: string | null): ExportRunLine["run"];
+export declare function assertExportOutPathAllowed(outPath: string, homeDir?: string, cwd?: string): string;
+export declare function iterateExportNdjson(options: {
+    store: {
+        listRuns: (filter?: ListRunsFilter) => Promise<Array<{
+            run_id: string;
+        }>>;
+        readRun: (runId: string) => Promise<Parameters<typeof projectRun>[0]>;
+        readPipelineBody: (runId: string) => Promise<string | null>;
+    };
+    filter?: ListRunsFilter;
+    now?: Date;
+}): AsyncGenerator<string>;
+export declare function runExportAllCommand(args: string[], options?: {
+    cwd?: string;
+    io?: Partial<ExportAllCommandIo>;
+}): Promise<number>;