stageflow 0.33.0 → 0.36.0

package/dist/browser/stageBrowserEnv.js

@@ -1,30 +1,70 @@
 import { mkdir, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { loadHostConfig } from "../config/hostConfig.js";
+import { browserHostForOwner, loadHostConfig } from "../config/hostConfig.js";
 import { stageDir } from "../runstore/paths.js";
 import { safeAudit } from "./auditSink.js";
 import { assertBrowserSitesAllowed } from "./sitePolicy.js";
 import { BROWSER_ENV_FILENAME, BROWSER_POLICY_FILENAME, } from "./browserHost.js";
 import { ensureRunProfileBrowser } from "./anchor.js";
 import { BROWSER_CLOSED_FILENAME, closeBrowserSession, defaultBrowserRunner, writeSessionOwner, } from "./browserTeardown.js";
-import { defaultDisplayProbe, loginPageUrl, noScreenError } from "./humanLogin.js";
+import { loginPageUrl } from "./humanLogin.js";
+import { persistStageHandoff, resolveStageHandoffCapabilities } from "./stageHandoff.js";
 import { ensureStageLoginCheck, OPEN_COMMAND_TIMEOUT_MS } from "./loginCheck.js";
 import { readPersistedBrowserEnv } from "./persistedEnv.js";
+import { createContainerBrowserHost } from "./containerBrowserHost.js";
+import { createDockerSandboxOrchestrator } from "./dockerSandboxOrchestrator.js";
+import { createVolumeProfileStore } from "./volumeProfileStore.js";
 import { createLocalBrowserHost } from "./localBrowserHost.js";
 import { createLocalProfileStore } from "./localProfileStore.js";
-import { LOCAL_BROWSER_SCOPE } from "./profileStore.js";
+import { localOwnerScope } from "./ownerScope.js";
 export { BROWSER_ENV_FILENAME };
 export async function readStagePersistedBrowserEnv(runDir, stageId) {
     return readPersistedBrowserEnv(path.join(stageDir(runDir, stageId), BROWSER_ENV_FILENAME));
 }
 let defaultSupport;
-export function defaultStageBrowserSupport() {
-    defaultSupport ??= {
-        host: createLocalBrowserHost(),
+export function hostLaunchOptions() {
+    const config = loadHostConfig();
+    return {
+        launchArgs: config.browserLaunchArgs,
+        ...(config.browserExecutablePath !== undefined
+            ? { executablePath: config.browserExecutablePath }
+            : {}),
+    };
+}
+function configuredBrowserSupport(liveView) {
+    const config = loadHostConfig();
+    if (browserHostForOwner(config, localOwnerScope()) === "container") {
+        const container = config.browserContainer;
+        return {
+            host: createContainerBrowserHost({
+                orchestrator: createDockerSandboxOrchestrator({
+                    image: container.image,
+                    shmSize: container.shmSize,
+                    memory: container.memory,
+                    pidsLimit: container.pidsLimit,
+                    user: "1000:1000",
+                }),
+                liveView,
+                local: hostLaunchOptions(),
+            }),
+            profiles: createVolumeProfileStore(),
+        };
+    }
+    return {
+        host: createLocalBrowserHost({ liveView, ...hostLaunchOptions() }),
         profiles: createLocalProfileStore(),
     };
+}
+export function defaultStageBrowserSupport() {
+    defaultSupport ??= configuredBrowserSupport("none");
     return defaultSupport;
 }
+let consoleSupport;
+/** Browser support for a process that serves the live view routes (`sf ui`, `sf mcp`). */
+export function consoleStageBrowserSupport() {
+    consoleSupport ??= configuredBrowserSupport("relay");
+    return consoleSupport;
+}
 /**
  * Computed once per stage and persisted in the run dir: agent-browser silently
  * relaunches the browser when a command's launch env differs from the daemon's,
@@ -34,11 +74,9 @@ export async function resolveStageBrowserEnv(support, input) {
     const { browser } = input;
     if (browser === undefined)
         return undefined;
-    if (input.humanLogin === true) {
-        const screen = (support.display ?? defaultDisplayProbe)();
-        if (!screen.hasDisplay)
-            throw noScreenError(screen.docker);
-    }
+    const capabilities = resolveStageHandoffCapabilities(support, {
+        ...(input.humanLogin === true ? { humanLogin: true } : {}),
+    });
     if ((browser.allow_domains?.length ?? 0) > 0 ||
         browser.check !== undefined ||
         browser.login_url !== undefined) {
@@ -46,10 +84,11 @@ export async function resolveStageBrowserEnv(support, input) {
     }
     const dir = stageDir(input.runDir, input.stageId);
     const file = path.join(dir, BROWSER_ENV_FILENAME);
-    // TODO(multi-tenant): open the profile in the run owner's scope, not the fixed local scope.
+    await mkdir(dir, { recursive: true });
+    await persistStageHandoff({ runDir: input.runDir, stageId: input.stageId }, capabilities);
     const profile = browser.profile !== undefined
         ? await support.profiles.open({
-            scope: LOCAL_BROWSER_SCOPE,
+            scope: input.scope,
             name: browser.profile,
         })
         : undefined;
@@ -97,10 +136,9 @@ export async function resolveStageBrowserEnv(support, input) {
     if (persisted === undefined) {
         await writeEnv(fresh);
         if (browser.profile !== undefined) {
-            // TODO(multi-tenant): audit the run owner's scope.
             await safeAudit(support.audit, {
                 event: "profile_used",
-                scope: LOCAL_BROWSER_SCOPE,
+                scope: input.scope,
                 profile: browser.profile,
                 runId: input.runId,
                 stageId: input.stageId,

package/dist/browser/stageHandoff.d.ts

@@ -0,0 +1,47 @@
+import type { StageBrowserConfig } from "../types/stage.js";
+import type { StageBrowserSupport } from "./browserHost.js";
+import { type GateHandoff, type HostGateContext } from "./gateHandoff.js";
+import { type BrowserHostCapabilities } from "./hostCapabilities.js";
+/** The slice of the host capability record a stage's handoff depends on; persisted per stage. */
+export type StageHandoffCapabilities = Pick<BrowserHostCapabilities, "display" | "liveView">;
+type HandoffInput = {
+    runDir: string;
+    runId: string;
+    stageId: string;
+};
+/**
+ * Probes the display, applies the host's capabilities, and rejects a human-login
+ * stage that has neither a screen nor a live view. Pure of disk writes.
+ */
+export declare function resolveStageHandoffCapabilities(support: StageBrowserSupport, options?: {
+    humanLogin?: boolean;
+}): StageHandoffCapabilities;
+export declare function persistStageHandoff(input: {
+    runDir: string;
+    stageId: string;
+}, capabilities: StageHandoffCapabilities): Promise<void>;
+/** Persisted capabilities of a stage; undefined when none were recorded (older runs, direct stage runs). */
+export declare function readStageHandoff(input: {
+    runDir: string;
+    stageId: string;
+}): Promise<StageHandoffCapabilities | undefined>;
+export declare function gateHandoffFor(context: {
+    runId: string;
+    stageId: string;
+    capabilities: StageHandoffCapabilities;
+}): GateHandoff | undefined;
+/** What the Host stamps on every gate of a browser stage; the agent cannot supply it. */
+export declare function hostGateContextFor(browser: StageBrowserConfig | undefined, context: {
+    runId: string;
+    stageId: string;
+    capabilities: StageHandoffCapabilities;
+}): HostGateContext | undefined;
+/** The handoff for a stage's gates and login prompt. `dirStageId` is the manifest id when it differs from the gate's stage id. */
+export declare function stageGateHandoff(input: HandoffInput & {
+    dirStageId?: string;
+}): Promise<GateHandoff | undefined>;
+/** Host-owned gate fields for a stage; undefined for a stage without a browser. */
+export declare function stageGateContext(input: HandoffInput & {
+    browser: StageBrowserConfig | undefined;
+}): Promise<HostGateContext | undefined>;
+export {};

package/dist/browser/stageHandoff.js

@@ -0,0 +1,101 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { stageDir } from "../runstore/paths.js";
+import { browserSite, } from "./gateHandoff.js";
+import { resolveBrowserHostCapabilities, } from "./hostCapabilities.js";
+import { defaultDisplayProbe, noScreenError } from "./humanLogin.js";
+const BROWSER_CAPABILITIES_FILENAME = "browser-capabilities.json";
+/**
+ * Probes the display, applies the host's capabilities, and rejects a human-login
+ * stage that has neither a screen nor a live view. Pure of disk writes.
+ */
+export function resolveStageHandoffCapabilities(support, options = {}) {
+    const capabilities = resolveBrowserHostCapabilities(support.host.capabilities);
+    const probe = support.display ?? defaultDisplayProbe;
+    if (support.host.capabilities === undefined) {
+        capabilities.display = probe().hasDisplay ? "local_window" : "headless_only";
+    }
+    else if (capabilities.display === "local_window" && support.display !== undefined && !support.display().hasDisplay) {
+        capabilities.display = "headless_only";
+    }
+    if (options.humanLogin === true &&
+        capabilities.display === "headless_only" &&
+        capabilities.liveView === "none") {
+        throw noScreenError(probe().docker);
+    }
+    if (options.humanLogin === true &&
+        capabilities.display !== "local_window" &&
+        capabilities.viewerInput === "view_only") {
+        throw new Error("A human login stage needs an interactive live view, but this browser host offers a view-only one (missing capability viewer_input: interactive).");
+    }
+    return { display: capabilities.display, liveView: capabilities.liveView };
+}
+export async function persistStageHandoff(input, capabilities) {
+    const dir = stageDir(input.runDir, input.stageId);
+    await mkdir(dir, { recursive: true });
+    await writeFile(path.join(dir, BROWSER_CAPABILITIES_FILENAME), `${JSON.stringify({ display: capabilities.display, liveView: capabilities.liveView })}\n`, { mode: 0o600 });
+}
+/** Persisted capabilities of a stage; undefined when none were recorded (older runs, direct stage runs). */
+export async function readStageHandoff(input) {
+    const file = path.join(stageDir(input.runDir, input.stageId), BROWSER_CAPABILITIES_FILENAME);
+    try {
+        const parsed = JSON.parse(await readFile(file, "utf8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const { display, liveView } = resolveBrowserHostCapabilities(parsed);
+            return { display, liveView };
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    return undefined;
+}
+export function gateHandoffFor(context) {
+    const { capabilities } = context;
+    if (capabilities.display === "local_window")
+        return { kind: "local_window" };
+    if (capabilities.liveView !== "none") {
+        return {
+            kind: "live_view",
+            url: `/api/runs/${encodeURIComponent(context.runId)}/stages/${encodeURIComponent(context.stageId)}/live-view`,
+        };
+    }
+    return undefined;
+}
+/** What the Host stamps on every gate of a browser stage; the agent cannot supply it. */
+export function hostGateContextFor(browser, context) {
+    if (browser === undefined)
+        return undefined;
+    const site = browserSite(browser);
+    const handoff = gateHandoffFor(context);
+    return {
+        ...(handoff !== undefined ? { handoff } : {}),
+        ...(site !== undefined ? { site } : {}),
+        ...(browser.profile !== undefined ? { profile: browser.profile } : {}),
+    };
+}
+// No record (older runs, direct stage runs) keeps its historical meaning: a local window.
+const LEGACY_CAPABILITIES = { display: "local_window", liveView: "none" };
+async function capabilitiesOf(input) {
+    return ((await readStageHandoff({ runDir: input.runDir, stageId: input.dirStageId ?? input.stageId })) ??
+        LEGACY_CAPABILITIES);
+}
+/** The handoff for a stage's gates and login prompt. `dirStageId` is the manifest id when it differs from the gate's stage id. */
+export async function stageGateHandoff(input) {
+    return gateHandoffFor({
+        runId: input.runId,
+        stageId: input.stageId,
+        capabilities: await capabilitiesOf(input),
+    });
+}
+/** Host-owned gate fields for a stage; undefined for a stage without a browser. */
+export async function stageGateContext(input) {
+    if (input.browser === undefined)
+        return undefined;
+    return hostGateContextFor(input.browser, {
+        runId: input.runId,
+        stageId: input.stageId,
+        capabilities: await capabilitiesOf(input),
+    });
+}

package/dist/browser/stageProfileLock.d.ts

@@ -2,6 +2,7 @@ import type { StageBrowserSupport } from "./browserHost.js";
 import type { ProfileLock, ProfileLockOwner, RunLiveness } from "./profileLock.js";
 export declare function stageProfileLock(support: StageBrowserSupport): ProfileLock;
 export type ProfileWaitInput = {
+    scope: string;
     profile: string;
     owner: ProfileLockOwner;
     isRunLive?: RunLiveness;

package/dist/browser/stageProfileLock.js

@@ -1,5 +1,4 @@
 import { createLocalProfileLock } from "./localProfileLock.js";
-import { LOCAL_BROWSER_SCOPE } from "./profileStore.js";
 const DEFAULT_LOCK_POLL_MS = 250;
 let defaultLock;
 export function stageProfileLock(support) {
@@ -14,8 +13,7 @@ export function stageProfileLock(support) {
  */
 export async function acquireStageProfile(support, input) {
     const locks = stageProfileLock(support);
-    // TODO(multi-tenant): take the scope from the run owner instead of the fixed local scope.
-    const key = { scope: LOCAL_BROWSER_SCOPE, name: input.profile };
+    const key = { scope: input.scope, name: input.profile };
     const pollMs = support.lockPollMs ?? DEFAULT_LOCK_POLL_MS;
     let announced;
     for (;;) {

package/dist/browser/volumeProfileStore.d.ts

@@ -0,0 +1,7 @@
+import { type ProfileStore } from "./profileStore.js";
+/**
+ * Profiles that live in a volume the sandbox orchestrator provisions. The handle
+ * carries a reference, never a folder; creating, sizing and removing the volume
+ * belong to the orchestrator, so `delete` only forgets the reference.
+ */
+export declare function createVolumeProfileStore(): ProfileStore;

package/dist/browser/volumeProfileStore.js

@@ -0,0 +1,35 @@
+import { validateProfileKey, validateProfileScope, } from "./profileStore.js";
+/**
+ * Profiles that live in a volume the sandbox orchestrator provisions. The handle
+ * carries a reference, never a folder; creating, sizing and removing the volume
+ * belong to the orchestrator, so `delete` only forgets the reference.
+ */
+export function createVolumeProfileStore() {
+    const scopes = new Map();
+    return {
+        async open(rawKey) {
+            const key = validateProfileKey(rawKey);
+            let profiles = scopes.get(key.scope);
+            if (!profiles) {
+                profiles = new Map();
+                scopes.set(key.scope, profiles);
+            }
+            let handle = profiles.get(key.name);
+            if (!handle) {
+                handle = { key, volumeRef: `${key.scope}/${key.name}` };
+                profiles.set(key.name, handle);
+            }
+            return handle;
+        },
+        async list(scope) {
+            return [...(scopes.get(validateProfileScope(scope))?.keys() ?? [])].sort();
+        },
+        async delete(rawKey) {
+            const key = validateProfileKey(rawKey);
+            scopes.get(key.scope)?.delete(key.name);
+        },
+        async deleteScope(scope) {
+            scopes.delete(validateProfileScope(scope));
+        },
+    };
+}

package/dist/channels/config.d.ts

@@ -0,0 +1,11 @@
+import type { ConnectionEntry, CredentialEntry } from "./types.js";
+export declare const CONNECTIONS_FILE_LIMIT_BYTES = 262144;
+export declare const MAX_CONNECTIONS = 100;
+export declare const MAX_CREDENTIALS = 20;
+export type ConnectionsFile = {
+    credentials: CredentialEntry[];
+    connections: ConnectionEntry[];
+};
+export declare function parseConnectionsYaml(text: string): ConnectionsFile;
+/** A missing file is an empty configuration. Any other fault stops startup instead of half-applying. */
+export declare function loadConnectionsFile(file: string): ConnectionsFile;

package/dist/channels/config.js

@@ -0,0 +1,95 @@
+import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
+import { parseDocument } from "yaml";
+import { z } from "zod";
+import { ChannelError } from "./errors.js";
+import { SECRET_REF_PATTERN } from "./secrets.js";
+export const CONNECTIONS_FILE_LIMIT_BYTES = 262144;
+export const MAX_CONNECTIONS = 100;
+export const MAX_CREDENTIALS = 20;
+const idSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/);
+const providerSchema = z.string().regex(/^[a-z][a-z0-9-]{0,63}$/);
+const secretRefSchema = z.string().regex(SECRET_REF_PATTERN);
+const secretFieldSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,63}$/);
+const secretsSchema = z.record(secretFieldSchema, secretRefSchema).default({});
+const credentialSchema = z.object({
+    id: idSchema,
+    provider: providerSchema,
+    secrets: secretsSchema,
+}).strict();
+const connectionSchema = z.object({
+    id: idSchema,
+    provider: providerSchema,
+    displayName: z.string().min(1).max(200).optional(),
+    enabled: z.boolean().default(true),
+    credential: idSchema.optional(),
+    config: z.record(z.string(), z.unknown()).default({}),
+    secrets: secretsSchema,
+}).strict();
+const fileSchema = z.object({
+    version: z.literal(1),
+    credentials: z.array(credentialSchema).max(MAX_CREDENTIALS).default([]),
+    connections: z.array(connectionSchema).max(MAX_CONNECTIONS).default([]),
+}).strict();
+export function parseConnectionsYaml(text) {
+    const document = parseDocument(text, { uniqueKeys: true, strict: true });
+    if (document.errors.length || document.warnings.length)
+        throw new ChannelError("CHANNEL_INVALID_INPUT");
+    let raw;
+    try {
+        raw = document.toJS({ maxAliasCount: 0 });
+    }
+    catch {
+        throw new ChannelError("CHANNEL_INVALID_INPUT");
+    }
+    const parsed = fileSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new ChannelError("CHANNEL_INVALID_INPUT");
+    assertUnique(parsed.data.credentials.map(entry => entry.id));
+    assertUnique(parsed.data.connections.map(entry => entry.id));
+    return {
+        credentials: parsed.data.credentials.map(entry => ({ ...entry, secrets: entry.secrets })),
+        connections: parsed.data.connections.map(entry => ({ ...entry, secrets: entry.secrets })),
+    };
+}
+function assertUnique(ids) {
+    if (new Set(ids).size !== ids.length)
+        throw new ChannelError("CHANNEL_INVALID_INPUT");
+}
+/** A missing file is an empty configuration. Any other fault stops startup instead of half-applying. */
+export function loadConnectionsFile(file) {
+    let descriptor;
+    try {
+        descriptor = openSync(file, constants.O_RDONLY | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { credentials: [], connections: [] };
+        throw new ChannelError("CHANNEL_STORAGE_FAILED");
+    }
+    try {
+        const stat = fstatSync(descriptor);
+        if (!stat.isFile())
+            throw new ChannelError("CHANNEL_INVALID_INPUT");
+        if (stat.size > CONNECTIONS_FILE_LIMIT_BYTES)
+            throw new ChannelError("CHANNEL_RESOURCE_LIMIT");
+        const bytes = Buffer.alloc(CONNECTIONS_FILE_LIMIT_BYTES + 1);
+        let length = 0;
+        while (length < bytes.length) {
+            const count = readSync(descriptor, bytes, length, bytes.length - length, null);
+            if (!count)
+                break;
+            length += count;
+        }
+        if (length > CONNECTIONS_FILE_LIMIT_BYTES)
+            throw new ChannelError("CHANNEL_RESOURCE_LIMIT");
+        return parseConnectionsYaml(bytes.toString("utf8", 0, length));
+    }
+    catch (error) {
+        if (error instanceof ChannelError)
+            throw error;
+        throw new ChannelError("CHANNEL_INVALID_INPUT");
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}

package/dist/channels/configWriter.d.ts

@@ -0,0 +1,40 @@
+import type { ConnectionEntry, CredentialEntry } from "./types.js";
+/** Plain-object form of an entry. Optional fields are omitted when unset. */
+export type ConnectionYamlEntry = {
+    id: string;
+    provider: string;
+    displayName?: string;
+    enabled?: boolean;
+    credential?: string;
+    config?: Record<string, unknown>;
+    secrets?: Record<string, string>;
+};
+export declare function toYamlEntry(entry: Pick<ConnectionEntry, "id" | "provider" | "enabled" | "config" | "secrets"> & {
+    displayName?: string;
+    credential?: string;
+}): ConnectionYamlEntry;
+/** Edits keep comments and key order that the user wrote. */
+export declare function addConnectionYaml(text: string, entry: ConnectionYamlEntry, credential?: {
+    id: string;
+    provider: string;
+    secrets: Record<string, string>;
+}): string;
+export type ConnectionPatch = {
+    displayName?: string | null;
+    enabled?: boolean;
+    config?: Record<string, unknown>;
+    secrets?: Record<string, string>;
+};
+export declare function updateConnectionYaml(text: string, id: string, patch: ConnectionPatch): string;
+/** Removes the entry and any credential that no remaining connection uses. Returns what was dropped. */
+export declare function removeConnectionYaml(text: string, id: string): {
+    text: string;
+    removedCredential?: string;
+};
+export declare function readConnectionsText(file: string): string;
+/**
+ * Replaces the file atomically. A bind-mounted file cannot be renamed over, so that case falls
+ * back to writing in place.
+ */
+export declare function writeConnectionsText(file: string, text: string): void;
+export type { CredentialEntry };

package/dist/channels/configWriter.js

@@ -0,0 +1,148 @@
+import { closeSync, constants, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import path from "node:path";
+import { isSeq, parseDocument } from "yaml";
+import { CONNECTIONS_FILE_LIMIT_BYTES } from "./config.js";
+import { ChannelError } from "./errors.js";
+export function toYamlEntry(entry) {
+    return {
+        id: entry.id,
+        provider: entry.provider,
+        ...(entry.displayName ? { displayName: entry.displayName } : {}),
+        ...(entry.enabled === false ? { enabled: false } : {}),
+        ...(entry.credential ? { credential: entry.credential } : {}),
+        ...(Object.keys(entry.config).length ? { config: entry.config } : {}),
+        ...(Object.keys(entry.secrets).length ? { secrets: entry.secrets } : {}),
+    };
+}
+function open(text) {
+    const source = text.trim().length ? text : "version: 1\n";
+    const document = parseDocument(source, { uniqueKeys: true, strict: true });
+    if (document.errors.length)
+        throw new ChannelError("CHANNEL_INVALID_INPUT");
+    return document;
+}
+function sequence(document, key) {
+    let seq = document.get(key, true);
+    if (!isSeq(seq)) {
+        document.set(key, document.createNode([]));
+        seq = document.get(key, true);
+    }
+    const result = seq;
+    result.flow = false;
+    return result;
+}
+function indexOf(seq, id) {
+    return seq.items.findIndex(item => item?.get?.("id") === id);
+}
+/** Edits keep comments and key order that the user wrote. */
+export function addConnectionYaml(text, entry, credential) {
+    const document = open(text);
+    if (credential) {
+        const credentials = sequence(document, "credentials");
+        if (indexOf(credentials, credential.id) < 0)
+            credentials.add(document.createNode({ id: credential.id, provider: credential.provider, secrets: credential.secrets }));
+    }
+    const connections = sequence(document, "connections");
+    if (indexOf(connections, entry.id) >= 0)
+        throw new ChannelError("CHANNEL_OPERATION_CONFLICT", false, { connectionId: entry.id });
+    connections.add(document.createNode(entry));
+    return document.toString();
+}
+export function updateConnectionYaml(text, id, patch) {
+    const document = open(text);
+    const connections = sequence(document, "connections");
+    const index = indexOf(connections, id);
+    if (index < 0)
+        throw new ChannelError("CHANNEL_NOT_FOUND", false, { connectionId: id });
+    const node = connections.items[index];
+    if (patch.displayName !== undefined) {
+        if (patch.displayName === null || patch.displayName === "")
+            node.delete("displayName");
+        else
+            node.set("displayName", patch.displayName);
+    }
+    if (patch.enabled !== undefined) {
+        if (patch.enabled)
+            node.delete("enabled");
+        else
+            node.set("enabled", false);
+    }
+    if (patch.config !== undefined) {
+        if (Object.keys(patch.config).length)
+            node.set("config", document.createNode(patch.config));
+        else
+            node.delete("config");
+    }
+    for (const [field, ref] of Object.entries(patch.secrets ?? {}))
+        node.setIn(["secrets", field], ref);
+    return document.toString();
+}
+/** Removes the entry and any credential that no remaining connection uses. Returns what was dropped. */
+export function removeConnectionYaml(text, id) {
+    const document = open(text);
+    const connections = sequence(document, "connections");
+    const index = indexOf(connections, id);
+    if (index < 0)
+        throw new ChannelError("CHANNEL_NOT_FOUND", false, { connectionId: id });
+    const credentialId = connections.items[index].get("credential");
+    connections.items.splice(index, 1);
+    let removedCredential;
+    if (typeof credentialId === "string") {
+        const stillUsed = connections.items.some(item => item.get("credential") === credentialId);
+        const credentials = document.get("credentials", true);
+        if (!stillUsed && isSeq(credentials)) {
+            const at = indexOf(credentials, credentialId);
+            if (at >= 0) {
+                credentials.items.splice(at, 1);
+                removedCredential = credentialId;
+            }
+        }
+    }
+    return { text: document.toString(), ...(removedCredential ? { removedCredential } : {}) };
+}
+export function readConnectionsText(file) {
+    if (!existsSync(file))
+        return "";
+    const text = readFileSync(file, "utf8");
+    if (Buffer.byteLength(text) > CONNECTIONS_FILE_LIMIT_BYTES)
+        throw new ChannelError("CHANNEL_RESOURCE_LIMIT");
+    return text;
+}
+/**
+ * Replaces the file atomically. A bind-mounted file cannot be renamed over, so that case falls
+ * back to writing in place.
+ */
+export function writeConnectionsText(file, text) {
+    if (Buffer.byteLength(text) > CONNECTIONS_FILE_LIMIT_BYTES)
+        throw new ChannelError("CHANNEL_RESOURCE_LIMIT");
+    try {
+        mkdirSync(path.dirname(file), { recursive: true });
+        const temporary = `${file}.${process.pid}.tmp`;
+        try {
+            writeFileSync(temporary, text, { mode: 0o644 });
+            renameSync(temporary, file);
+        }
+        catch (error) {
+            const code = error.code;
+            try {
+                unlinkSync(temporary);
+            }
+            catch { /* nothing to clean */ }
+            if (code !== "EBUSY" && code !== "EXDEV" && code !== "EPERM")
+                throw error;
+            const descriptor = openSync(file, constants.O_WRONLY | constants.O_TRUNC);
+            try {
+                writeSync(descriptor, text);
+                fsyncSync(descriptor);
+            }
+            finally {
+                closeSync(descriptor);
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof ChannelError)
+            throw error;
+        throw new ChannelError("CHANNEL_STORAGE_FAILED");
+    }
+}

package/dist/channels/connectionEdits.d.ts

@@ -0,0 +1,34 @@
+/** What the edit module needs from the secret store. `ChannelSecretStore` satisfies it. */
+export interface SecretWriter {
+    get(name: string): string | undefined;
+    set(name: string, value: string): void;
+    delete(name: string): void;
+    deleteWithPrefix(prefix: string): void;
+}
+export type ConnectionEdit = {
+    /** Secret store name to value. Written before the file so a reference never points at nothing. */
+    secrets?: Readonly<Record<string, string>>;
+    /** Pure transform of the file text. May name secret prefixes to drop once the edit has committed. */
+    rewrite(text: string): {
+        text: string;
+        dropSecretPrefixes?: readonly string[];
+    };
+};
+export type ConnectionEditsOptions = {
+    file: () => string;
+    store: SecretWriter;
+    /** Throws if the new text would not load. Runs before anything is written to the file. */
+    validate: (text: string) => void;
+};
+/**
+ * One atomic change to connections: secrets and file together. Either both change or neither
+ * does. A secret that already existed is restored to its previous value, not deleted, and a
+ * failure while writing, validating or saving leaves nothing half-applied. Dropping the secrets
+ * of a removed connection happens only after the file has been saved, and a failure there only
+ * leaves an orphaned secret behind, never a broken connection.
+ */
+export declare class ConnectionEdits {
+    private readonly options;
+    constructor(options: ConnectionEditsOptions);
+    apply(edit: ConnectionEdit): void;
+}