stageflow 0.25.0 → 0.30.0

package/dist/operatorAgent/proposals.js

@@ -0,0 +1,144 @@
+import { readDraftFromContext } from "./draftContext.js";
+const UNDO_CONFLICT_NOTICE = "Undo blocked: the draft changed after this mutation. Ask the agent to reverse the change instead of rejecting.";
+export function draftFingerprint(draft) {
+    return JSON.stringify(draft);
+}
+export function formatArtifact(value) {
+    return JSON.stringify(value, null, 2);
+}
+function stageIds(draft) {
+    return draft.pipeline.stages.map((stage, index) => typeof stage.id === "string" && stage.id ? stage.id : `stage-${index}`);
+}
+export function diffDraftPackages(before, after) {
+    const diffs = [];
+    const pipelinePath = `${after.pipeline.id || before.pipeline.id || "pipeline"}.pipeline.yaml`;
+    if (JSON.stringify(before.pipeline) !== JSON.stringify(after.pipeline)) {
+        diffs.push({
+            path: pipelinePath,
+            kind: "modified",
+            before: formatArtifact(before.pipeline),
+            after: formatArtifact(after.pipeline),
+        });
+    }
+    const beforeStages = new Map((before.stages ?? []).map((s) => [s.path, s]));
+    const afterStages = new Map((after.stages ?? []).map((s) => [s.path, s]));
+    for (const [path, art] of afterStages) {
+        const prev = beforeStages.get(path);
+        if (!prev) {
+            diffs.push({
+                path,
+                kind: "added",
+                after: formatArtifact(art.body),
+            });
+        }
+        else if (JSON.stringify(prev.body) !== JSON.stringify(art.body)) {
+            diffs.push({
+                path,
+                kind: "modified",
+                before: formatArtifact(prev.body),
+                after: formatArtifact(art.body),
+            });
+        }
+    }
+    for (const [path, art] of beforeStages) {
+        if (!afterStages.has(path)) {
+            diffs.push({
+                path,
+                kind: "removed",
+                before: formatArtifact(art.body),
+            });
+        }
+    }
+    const beforeTask = before.task
+        ? formatArtifact({ filename: before.task.filename, body: before.task.body })
+        : null;
+    const afterTask = after.task
+        ? formatArtifact({ filename: after.task.filename, body: after.task.body })
+        : null;
+    if (beforeTask !== afterTask) {
+        const path = after.task?.filename ?? before.task?.filename ?? "task.task.yaml";
+        if (!beforeTask && afterTask) {
+            diffs.push({ path, kind: "added", after: afterTask });
+        }
+        else if (beforeTask && !afterTask) {
+            diffs.push({ path, kind: "removed", before: beforeTask });
+        }
+        else {
+            diffs.push({
+                path,
+                kind: "modified",
+                before: beforeTask ?? undefined,
+                after: afterTask ?? undefined,
+            });
+        }
+    }
+    return diffs;
+}
+export function affectedStageIds(before, after) {
+    const beforeSet = new Set(stageIds(before));
+    const afterSet = new Set(stageIds(after));
+    const ids = new Set();
+    for (const id of afterSet) {
+        if (!beforeSet.has(id))
+            ids.add(id);
+    }
+    for (const id of beforeSet) {
+        if (!afterSet.has(id))
+            ids.add(id);
+    }
+    const beforeByPath = new Map((before.stages ?? []).map((s) => [s.path, s]));
+    for (const art of after.stages ?? []) {
+        const prev = beforeByPath.get(art.path);
+        if (!prev || JSON.stringify(prev.body) !== JSON.stringify(art.body)) {
+            const id = typeof art.body.id === "string" && art.body.id
+                ? art.body.id
+                : undefined;
+            if (id)
+                ids.add(id);
+        }
+    }
+    for (const art of before.stages ?? []) {
+        if (!(after.stages ?? []).some((s) => s.path === art.path)) {
+            const id = typeof art.body.id === "string" && art.body.id
+                ? art.body.id
+                : undefined;
+            if (id)
+                ids.add(id);
+        }
+    }
+    for (let i = 0; i < after.pipeline.stages.length; i += 1) {
+        const a = after.pipeline.stages[i];
+        const b = before.pipeline.stages[i];
+        const id = typeof a.id === "string" && a.id ? a.id : `stage-${i}`;
+        if (!b || JSON.stringify(a) !== JSON.stringify(b)) {
+            ids.add(id);
+        }
+    }
+    return [...ids];
+}
+export function enrichProposal(proposal, currentContext) {
+    const baseDraft = readDraftFromContext(proposal.baseContext ?? currentContext);
+    const nextDraft = readDraftFromContext(proposal.nextContext);
+    const baseContext = proposal.baseContext ??
+        { draft: baseDraft };
+    return {
+        ...proposal,
+        baseContext,
+        baseFingerprint: proposal.baseFingerprint ?? draftFingerprint(baseDraft),
+        appliedFingerprint: proposal.appliedFingerprint ?? draftFingerprint(nextDraft),
+        artifacts: proposal.artifacts ?? diffDraftPackages(baseDraft, nextDraft),
+        affectedStageIds: proposal.affectedStageIds ?? affectedStageIds(baseDraft, nextDraft),
+    };
+}
+/** True when the live draft no longer matches the post-apply fingerprint. */
+export function isMutationConflict(mutation, currentContext) {
+    const current = draftFingerprint(readDraftFromContext(currentContext));
+    if (mutation.appliedFingerprint) {
+        return mutation.appliedFingerprint !== current;
+    }
+    const next = draftFingerprint(readDraftFromContext(mutation.nextContext));
+    return next !== current;
+}
+export const UNDO_MUTATION_CONFLICT_NOTICE = UNDO_CONFLICT_NOTICE;
+/** @deprecated Prefer UNDO_MUTATION_CONFLICT_NOTICE — kept for callers mid-migration. */
+export const STALE_PROPOSAL_NOTICE = UNDO_CONFLICT_NOTICE;

package/dist/operatorAgent/types.d.ts

@@ -0,0 +1,128 @@
+import type { DraftPackage } from "../config/draftPackage.js";
+import type { ValidationResult } from "../config/validateCatalog.js";
+import type { AcceptProposalResult, ProposalArtifactDiff, UndoMutationResult } from "./proposals.js";
+export type OperatorAgentToolResult = {
+    ok: boolean;
+    content: unknown;
+    error?: string;
+};
+export type OperatorAgentToolHandler = (args: Record<string, unknown>, ctx: OperatorAgentToolContext) => Promise<OperatorAgentToolResult> | OperatorAgentToolResult;
+export type OperatorAgentTool = {
+    name: string;
+    description: string;
+    handler: OperatorAgentToolHandler;
+};
+export type OperatorAgentToolContext = {
+    getContext(): unknown;
+    setContext(next: unknown): void;
+    /** Apply mutation immediately and record an undo receipt. */
+    emitProposal(proposal: OperatorAgentProposal): void;
+};
+export type OperatorAgentProposal = {
+    /** Mutation id (Accept confirms; Reject / undoMutation soft-undos). */
+    id: string;
+    summary: string;
+    /** Context after the mutation (already applied to the session). */
+    nextContext: unknown;
+    /** Context snapshot before the mutation (restore target for undo). */
+    baseContext?: unknown;
+    /** Fingerprint of the draft before apply. */
+    baseFingerprint?: string;
+    /** Fingerprint of the draft immediately after apply — undo requires a match. */
+    appliedFingerprint?: string;
+    artifacts?: ProposalArtifactDiff[];
+    affectedStageIds?: string[];
+};
+export type OperatorAgentContextAdapter = {
+    serialize(context: unknown): unknown;
+    applyProposal(context: unknown, proposal: OperatorAgentProposal): unknown;
+};
+export type OperatorAgentProfile = {
+    id: string;
+    title: string;
+    playbook: string;
+    tools: OperatorAgentTool[];
+    contextAdapter: OperatorAgentContextAdapter;
+    greeting?: string;
+};
+export type OperatorAgentSessionEvent = {
+    type: "message";
+    role: "assistant" | "user" | "system";
+    text: string;
+} | {
+    type: "proposal";
+    proposal: OperatorAgentProposal;
+} | {
+    type: "tool_result";
+    name: string;
+    result: OperatorAgentToolResult;
+} | {
+    type: "validation";
+    result: ValidationResult;
+} | {
+    type: "error";
+    message: string;
+};
+export type WorkshopToolActivityUpdate = {
+    id: string;
+    name: string;
+    status: "running" | "complete" | "error";
+    target?: string;
+    errorMessage?: string;
+    draft?: DraftPackage;
+    /** Build the turn is editing. Absent when the chat is unlinked. */
+    buildId?: string;
+};
+export type OperatorAgentSession = {
+    readonly profileId: string;
+    readonly profileTitle: string;
+    getContext(): unknown;
+    setContext(next: unknown): void;
+    /** Latest undoable mutation (Accept-card payload), or null. */
+    getPendingProposal(): OperatorAgentProposal | null;
+    getMutation(mutationId: string): OperatorAgentProposal | null;
+    /**
+     * Seed backend from prior transcript after process restart (KTD7).
+     * No-op for fake / models without prepareRestart.
+     */
+    prepareRestart?(transcript: readonly {
+        role: string;
+        text: string;
+    }[]): Promise<void>;
+    send(message: string, options?: {
+        onDelta?: (text: string) => void;
+        onActivity?: (update: WorkshopToolActivityUpdate) => void;
+        modelId?: string;
+    }): Promise<OperatorAgentSessionEvent[]>;
+    /** Interrupt the in-flight prompt. Resolves when the backend is idle. */
+    abort(): Promise<void>;
+    /** Confirm mutation (soft UX); draft already applied — does not re-apply. */
+    acceptProposal(proposalId?: string): AcceptProposalResult;
+    /** Soft-undo the mutation when the applied fingerprint still matches. */
+    rejectProposal(proposalId?: string): UndoMutationResult;
+    undoMutation(mutationId?: string): UndoMutationResult;
+    close(): void;
+};
+export type OperatorAgentHost = {
+    registerProfile(profile: OperatorAgentProfile): void;
+    getProfile(id: string): OperatorAgentProfile | undefined;
+    listProfiles(): OperatorAgentProfile[];
+    openSession(input: {
+        profileId: string;
+        context: unknown;
+    }): OperatorAgentSession;
+};
+export type WorkshopDraftContext = {
+    draft: DraftPackage;
+    destination?: {
+        directory: string;
+        pipelineFilename?: string;
+    };
+    /** Catalog write root for the save tool (usually the operator project). */
+    projectRoot?: string;
+    /** Workshop chat session that owns this host context. */
+    chatSessionId?: string;
+    /** Build this turn is editing. Absent when that chat is unlinked. */
+    buildId?: string;
+};
+export type { AcceptProposalResult, ProposalArtifactDiff, UndoMutationResult };

package/dist/operatorAgent/types.js

@@ -0,0 +1 @@
+export {};

package/dist/package-meta.d.ts

@@ -1,2 +1,3 @@
 export declare const PACKAGE_NAME = "stageflow";
-export declare const PACKAGE_VERSION = "0.25.0";
+export declare const PACKAGE_VERSION = "0.30.0";
+export declare const BUILD_SHA: string;

package/dist/package-meta.js

@@ -1,2 +1,3 @@
 export const PACKAGE_NAME = "stageflow";
-export const PACKAGE_VERSION = "0.25.0";
+export const PACKAGE_VERSION = "0.30.0";
+export const BUILD_SHA = process.env.STAGEFLOW_BUILD_SHA ?? "unknown";

package/dist/preflight/bash.d.ts

@@ -0,0 +1,8 @@
+export type BashPreflightErrorCode = "bash_not_found";
+export declare class BashPreflightError extends Error {
+    readonly code: BashPreflightErrorCode;
+    constructor(message: string, code?: BashPreflightErrorCode);
+}
+/** Resolve `bash` on PATH (never hardcode /bin/bash). */
+export declare function resolveBashPath(env?: NodeJS.ProcessEnv): string;
+export declare function assertBashAvailable(env?: NodeJS.ProcessEnv): string;

package/dist/preflight/bash.js

@@ -0,0 +1,34 @@
+import { accessSync, constants } from "node:fs";
+import path from "node:path";
+export class BashPreflightError extends Error {
+    code;
+    constructor(message, code = "bash_not_found") {
+        super(message);
+        this.name = "BashPreflightError";
+        this.code = code;
+    }
+}
+function isExecutable(filePath) {
+    try {
+        accessSync(filePath, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve `bash` on PATH (never hardcode /bin/bash). */
+export function resolveBashPath(env = process.env) {
+    const pathValue = env.PATH ?? "";
+    const parts = pathValue.split(path.delimiter).filter((p) => p.length > 0);
+    for (const dir of parts) {
+        const candidate = path.join(dir, "bash");
+        if (isExecutable(candidate)) {
+            return candidate;
+        }
+    }
+    throw new BashPreflightError('bash was not found on PATH; Stageflow verify requires bash (install bash or fix PATH)', "bash_not_found");
+}
+export function assertBashAvailable(env = process.env) {
+    return resolveBashPath(env);
+}

package/dist/preflight/claudeRoot.d.ts

@@ -0,0 +1,11 @@
+export type ClaudeRootErrorCode = "claude_as_root";
+export declare class ClaudeRootError extends Error {
+    readonly code: ClaudeRootErrorCode;
+    readonly euid: number;
+    constructor(euid: number);
+}
+export declare function isEffectiveRoot(geteuid?: (() => number) | undefined): boolean;
+export declare function assertClaudeNotRoot(options: {
+    backendId: string | undefined;
+    geteuid?: (() => number) | undefined;
+}): void;

package/dist/preflight/claudeRoot.js

@@ -0,0 +1,23 @@
+export class ClaudeRootError extends Error {
+    code = "claude_as_root";
+    euid;
+    constructor(euid) {
+        super(`Claude backend cannot run as root (euid=${euid}). Use a non-root USER or docker --user.`);
+        this.name = "ClaudeRootError";
+        this.euid = euid;
+    }
+}
+export function isEffectiveRoot(geteuid = process.geteuid) {
+    if (typeof geteuid !== "function")
+        return false;
+    return geteuid() === 0;
+}
+export function assertClaudeNotRoot(options) {
+    if (options.backendId !== "claude")
+        return;
+    const geteuid = options.geteuid ?? process.geteuid;
+    if (isEffectiveRoot(geteuid)) {
+        const euid = typeof geteuid === "function" ? geteuid() : 0;
+        throw new ClaudeRootError(euid);
+    }
+}

package/dist/preflight/mcpCommands.d.ts

@@ -0,0 +1,8 @@
+export type McpCommandMissing = {
+    command: string;
+    serverName: string;
+};
+export declare function resolveCommandOnPath(command: string, env?: NodeJS.ProcessEnv): string | undefined;
+export declare function findMissingMcpCommands(servers: Record<string, {
+    command?: string;
+}>, env?: NodeJS.ProcessEnv): McpCommandMissing[];

package/dist/preflight/mcpCommands.js

@@ -0,0 +1,36 @@
+import { accessSync, constants } from "node:fs";
+import path from "node:path";
+export function resolveCommandOnPath(command, env = process.env) {
+    if (command.includes("/") || command.includes("\\")) {
+        try {
+            accessSync(command, constants.X_OK);
+            return command;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const pathValue = env.PATH ?? "";
+    for (const dir of pathValue.split(path.delimiter).filter(Boolean)) {
+        const candidate = path.join(dir, command);
+        try {
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // continue
+        }
+    }
+    return undefined;
+}
+export function findMissingMcpCommands(servers, env = process.env) {
+    const missing = [];
+    for (const [serverName, server] of Object.entries(servers)) {
+        if (!server.command)
+            continue;
+        if (resolveCommandOnPath(server.command, env) === undefined) {
+            missing.push({ command: server.command, serverName });
+        }
+    }
+    return missing;
+}

package/dist/preflight/pipelinePreflight.d.ts

@@ -0,0 +1,40 @@
+import type { LoadedPipeline } from "../types/pipeline.js";
+import { type ToolRequirement } from "../config/toolRequires.js";
+import { type CheckToolchainOptions, type ToolchainCheckResult } from "./toolchain.js";
+export type PreflightCheckKind = "toolchain" | "secret" | "mcp";
+export type PreflightItem = {
+    kind: PreflightCheckKind;
+    status: "ok" | "missing_tool" | "tool_version_mismatch" | "unknown_version" | "secret_unavailable" | "stage.unknown_secret" | "stage.denied_secret" | "unresolved_var" | "missing_catalog" | "unknown_server" | "invalid_config" | "untrusted_config_origin";
+    tool?: string;
+    required?: string;
+    found?: string;
+    path?: string;
+    secret?: string;
+    stageId?: string;
+    server?: string;
+    message?: string;
+};
+export type PipelinePreflightResult = {
+    ok: boolean;
+    checks: PreflightItem[];
+    requirements: ToolRequirement[];
+    toolchain: ToolchainCheckResult;
+};
+export declare function checkStageSecretsPresence(loaded: LoadedPipeline, hostEnv?: NodeJS.ProcessEnv): PreflightItem[];
+export declare function checkStageMcpResolution(loaded: LoadedPipeline, options: {
+    projectRoot: string;
+    hostEnv?: NodeJS.ProcessEnv;
+}): Promise<PreflightItem[]>;
+export declare function runPipelinePreflight(loaded: LoadedPipeline, options: {
+    projectRoot: string;
+    hostEnv?: NodeJS.ProcessEnv;
+    toolchain?: CheckToolchainOptions;
+    /** When true (doctor --strict / explicit), unknown_version fails. */
+    strict?: boolean;
+    /** start_run: unknown_version passes; missing/mismatch fail. */
+    forStart?: boolean;
+}): Promise<PipelinePreflightResult>;
+export declare function preflightFailureCode(result: PipelinePreflightResult, options?: {
+    strict?: boolean;
+    forStart?: boolean;
+}): string | undefined;

package/dist/preflight/pipelinePreflight.js

@@ -0,0 +1,192 @@
+import { collectEffectiveRequires, } from "../config/toolRequires.js";
+import { resolveStageMcpServers, StageMcpError, } from "../config/resolveStageMcpServers.js";
+import { assertSecretPresent, loadSecretRegistry, SecretUnavailableError, } from "../runtime/stageSecrets.js";
+import { isForeverDeniedSecret } from "../runtime/stageEnvironment.js";
+import { checkToolchainRequirements, curatedStageEnv, } from "./toolchain.js";
+function toolchainItems(checks) {
+    return checks.map((c) => ({
+        kind: "toolchain",
+        status: c.status,
+        tool: c.tool,
+        required: c.required,
+        found: c.found,
+        path: c.path,
+    }));
+}
+export function checkStageSecretsPresence(loaded, hostEnv = process.env) {
+    const registry = loadSecretRegistry(hostEnv);
+    const items = [];
+    for (const stage of loaded.stages) {
+        for (const decl of stage.secrets ?? []) {
+            if (isForeverDeniedSecret(decl.name)) {
+                items.push({
+                    kind: "secret",
+                    status: "stage.denied_secret",
+                    secret: decl.name,
+                    stageId: stage.id,
+                    message: `secret "${decl.name}" is permanently denied`,
+                });
+                continue;
+            }
+            try {
+                assertSecretPresent(decl.name, registry, hostEnv);
+                items.push({
+                    kind: "secret",
+                    status: "ok",
+                    secret: decl.name,
+                    stageId: stage.id,
+                });
+            }
+            catch (err) {
+                if (err instanceof SecretUnavailableError) {
+                    items.push({
+                        kind: "secret",
+                        status: "secret_unavailable",
+                        secret: decl.name,
+                        stageId: stage.id,
+                        message: err.message,
+                    });
+                    continue;
+                }
+                const message = err instanceof Error ? err.message : String(err);
+                if (message.startsWith("stage.unknown_secret")) {
+                    items.push({
+                        kind: "secret",
+                        status: "stage.unknown_secret",
+                        secret: decl.name,
+                        stageId: stage.id,
+                        message: `unknown secret "${decl.name}" is not in the Host secret registry`,
+                    });
+                    continue;
+                }
+                items.push({
+                    kind: "secret",
+                    status: "secret_unavailable",
+                    secret: decl.name,
+                    stageId: stage.id,
+                    message,
+                });
+            }
+        }
+    }
+    return items;
+}
+export async function checkStageMcpResolution(loaded, options) {
+    const hostEnv = options.hostEnv ?? process.env;
+    const stageEnv = { ...curatedStageEnv(hostEnv) };
+    const registry = loadSecretRegistry(hostEnv);
+    for (const stage of loaded.stages) {
+        for (const decl of stage.secrets ?? []) {
+            try {
+                assertSecretPresent(decl.name, registry, hostEnv);
+                const entry = registry.get(decl.name);
+                if (entry?.kind === "env") {
+                    const plain = hostEnv[decl.name];
+                    const fileKey = `${decl.name}_FILE`;
+                    const filePath = hostEnv[fileKey];
+                    if (plain !== undefined && plain.length > 0) {
+                        stageEnv[decl.name] = plain;
+                    }
+                    else if (filePath !== undefined && filePath.length > 0) {
+                        try {
+                            const { readFileSync } = await import("node:fs");
+                            stageEnv[decl.name] = readFileSync(filePath, "utf8").replace(/\r?\n$/, "");
+                        }
+                        catch {
+                            /* presence already checked */
+                        }
+                    }
+                }
+            }
+            catch {
+                /* secret presence reported separately */
+            }
+        }
+    }
+    const items = [];
+    for (const stage of loaded.stages) {
+        const allowlist = stage.mcp ?? [];
+        if (allowlist.length === 0)
+            continue;
+        try {
+            await resolveStageMcpServers({
+                projectRoot: options.projectRoot,
+                allowlist,
+                env: stageEnv,
+                stageId: stage.id,
+            });
+            for (const server of allowlist) {
+                items.push({
+                    kind: "mcp",
+                    status: "ok",
+                    server,
+                    stageId: stage.id,
+                });
+            }
+        }
+        catch (err) {
+            if (err instanceof StageMcpError) {
+                items.push({
+                    kind: "mcp",
+                    status: err.code,
+                    stageId: stage.id,
+                    message: err.message,
+                });
+                continue;
+            }
+            items.push({
+                kind: "mcp",
+                status: "invalid_config",
+                stageId: stage.id,
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return items;
+}
+export async function runPipelinePreflight(loaded, options) {
+    const hostEnv = options.hostEnv ?? process.env;
+    const strict = options.strict === true;
+    const forStart = options.forStart === true;
+    const reqOutcome = collectEffectiveRequires({
+        pipelineRequires: loaded.pipeline.requires,
+        stageRequires: loaded.stages.map((s) => s.requires),
+        pipelineId: loaded.pipeline.id,
+    });
+    const requirements = reqOutcome.ok ? reqOutcome.value : [];
+    const toolchain = checkToolchainRequirements(requirements, {
+        ...options.toolchain,
+        env: hostEnv,
+        strict: forStart ? false : strict,
+        failOnUnknownVersion: forStart ? false : strict,
+    });
+    const secretChecks = checkStageSecretsPresence(loaded, hostEnv);
+    const mcpChecks = await checkStageMcpResolution(loaded, {
+        projectRoot: options.projectRoot,
+        hostEnv,
+    });
+    const checks = [
+        ...toolchainItems(toolchain.checks),
+        ...secretChecks,
+        ...mcpChecks,
+    ];
+    const ok = toolchain.ok &&
+        !secretChecks.some((c) => c.status !== "ok") &&
+        !mcpChecks.some((c) => c.status !== "ok");
+    return { ok, checks, requirements, toolchain };
+}
+export function preflightFailureCode(result, options = {}) {
+    for (const check of result.checks) {
+        if (check.status === "ok")
+            continue;
+        if (check.status === "unknown_version") {
+            if (options.forStart)
+                continue;
+            if (!options.strict)
+                continue;
+            return "unknown_version";
+        }
+        return check.status;
+    }
+    return undefined;
+}

package/dist/preflight/tls.d.ts

@@ -0,0 +1,6 @@
+export declare const CA_ENV_VARS: readonly ["NODE_EXTRA_CA_CERTS", "SSL_CERT_FILE", "SSL_CERT_DIR"];
+export type CaPathWarning = {
+    name: (typeof CA_ENV_VARS)[number];
+    path: string;
+};
+export declare function warnMissingCaPaths(env?: NodeJS.ProcessEnv): CaPathWarning[];

package/dist/preflight/tls.js

@@ -0,0 +1,18 @@
+import { existsSync } from "node:fs";
+export const CA_ENV_VARS = [
+    "NODE_EXTRA_CA_CERTS",
+    "SSL_CERT_FILE",
+    "SSL_CERT_DIR",
+];
+export function warnMissingCaPaths(env = process.env) {
+    const warnings = [];
+    for (const name of CA_ENV_VARS) {
+        const value = env[name]?.trim();
+        if (!value)
+            continue;
+        if (!existsSync(value)) {
+            warnings.push({ name, path: value });
+        }
+    }
+    return warnings;
+}