@starci/hfs 4.11.21 → 4.12.0

package/stack/provision.mjs

@@ -7,84 +7,85 @@ import { firstLine, lines as splitLines, tool } from './context.mjs';
 import { failure, refusal } from './errors.mjs';
 import { isReleaseId } from './digest.mjs';
 import { configBytes, configObjects, loadSealed } from './sealed.mjs';
-
 const STALE = 'render the release again';
-
 function readRelease(options) {
-  if (options.release) return options.release;
-  if (!options.releaseFile) throw refusal('STACK_RELEASE_MISSING', 'provision needs a release record (release or releaseFile)');
-  try {
-    return JSON.parse(fs.readFileSync(options.releaseFile, 'utf8'));
-  } catch {
-    throw refusal('STACK_RELEASE_INVALID', `${options.releaseFile} is not a readable release record`);
-  }
+    if (options.release)
+        return options.release;
+    if (!options.releaseFile)
+        throw refusal('STACK_RELEASE_MISSING', 'provision needs a release record (release or releaseFile)');
+    try {
+        return JSON.parse(fs.readFileSync(options.releaseFile, 'utf8'));
+    }
+    catch {
+        throw refusal('STACK_RELEASE_INVALID', `${options.releaseFile} is not a readable release record`);
+    }
 }
-
 function releaseId(release) {
-  const id = String(release.releaseDigest).slice(0, 16);
-  if (!isReleaseId(id) || !Array.isArray(release.secrets) || !Array.isArray(release.configs)) throw refusal('STACK_RELEASE_INVALID', 'the release record has no valid releaseDigest, secrets and configs');
-  return id;
+    const id = String(release.releaseDigest).slice(0, 16);
+    if (!isReleaseId(id) || !Array.isArray(release.secrets) || !Array.isArray(release.configs))
+        throw refusal('STACK_RELEASE_INVALID', 'the release record has no valid releaseDigest, secrets and configs');
+    return id;
 }
-
 function existing(ctx, kind) {
-  const run = tool(ctx, 'docker', [kind, 'ls', '--format', '{{.Name}}']);
-  if (run.error || run.status !== 0) throw failure('STACK_PROVISION_FAILED', `docker ${kind} ls failed: ${run.error?.message ?? firstLine(run.stderr)}`);
-  return new Set(splitLines(run.stdout));
+    const run = tool(ctx, 'docker', [kind, 'ls', '--format', '{{.Name}}']);
+    if (run.error || run.status !== 0)
+        throw failure('STACK_PROVISION_FAILED', `docker ${kind} ls failed: ${run.error?.message ?? firstLine(run.stderr)}`);
+    return new Set(splitLines(run.stdout));
 }
-
 function createFailure(run, what, value) {
-  const text = run.error?.message ?? firstLine(run.stderr);
-  return failure('STACK_PROVISION_FAILED', `docker ${what} failed: ${value === undefined ? text : text.replaceAll(value, '[value]')}`);
+    const text = run.error?.message ?? firstLine(run.stderr);
+    return failure('STACK_PROVISION_FAILED', `docker ${what} failed: ${value === undefined ? text : text.replaceAll(value, '[value]')}`);
 }
-
 function create(ctx, kind, labels, name, input) {
-  const label = labels.flatMap((item) => ['--label', item]);
-  return tool(ctx, 'docker', [kind, 'create', ...label, name, '-'], { input });
+    const label = labels.flatMap((item) => ['--label', item]);
+    return tool(ctx, 'docker', [kind, 'create', ...label, name, '-'], { input });
 }
-
 function plan(ctx, config, release, sealed) {
-  const secrets = release.secrets.map((entry) => {
-    const secret = sealed.secrets[entry.key];
-    if (secret?.runtimeName !== entry.runtimeName) throw refusal('STACK_RELEASE_STALE', `the sealed custody no longer matches the release record for ${entry.key}; ${STALE}`);
-    return { key: entry.key, name: entry.runtimeName, value: secret.value };
-  });
-  const files = new Map(configObjects(config).map((object) => [object.name, object.file]));
-  const configs = release.configs.map((entry) => {
-    if (!files.has(entry.name)) throw refusal('STACK_RELEASE_STALE', `the config ${entry.name} does not match the committed files; ${STALE}`);
-    return { logical: entry.logical, name: entry.name, file: files.get(entry.name) };
-  });
-  const haveSecrets = existing(ctx, 'secret');
-  const haveConfigs = existing(ctx, 'config');
-  return {
-    secrets: secrets.filter((item) => !haveSecrets.has(item.name)),
-    kept: secrets.filter((item) => haveSecrets.has(item.name)).length,
-    configs: configs.filter((item) => !haveConfigs.has(item.name)),
-  };
+    const secrets = release.secrets.map((entry) => {
+        const secret = sealed.secrets[entry.key];
+        if (secret?.runtimeName !== entry.runtimeName)
+            throw refusal('STACK_RELEASE_STALE', `the sealed custody no longer matches the release record for ${entry.key}; ${STALE}`);
+        return { key: entry.key, name: entry.runtimeName, value: secret.value };
+    });
+    const files = new Map(configObjects(config).map((object) => [object.name, object.file]));
+    const configs = release.configs.map((entry) => {
+        const file = files.get(entry.name);
+        if (file === undefined)
+            throw refusal('STACK_RELEASE_STALE', `the config ${entry.name} does not match the committed files; ${STALE}`);
+        return { logical: entry.logical, name: entry.name, file };
+    });
+    const haveSecrets = existing(ctx, 'secret');
+    const haveConfigs = existing(ctx, 'config');
+    return {
+        secrets: secrets.filter((item) => !haveSecrets.has(item.name)),
+        kept: secrets.filter((item) => haveSecrets.has(item.name)).length,
+        configs: configs.filter((item) => !haveConfigs.has(item.name)),
+    };
 }
-
 function createAll(ctx, config, id, todo) {
-  const managed = `${config.stack}.managed=true`;
-  const tagged = `${config.stack}.release=${id}`;
-  for (const item of todo.secrets) {
-    const run = create(ctx, 'secret', [managed, `${config.stack}.key=${item.key}`, tagged], item.name, item.value);
-    if (run.error || run.status !== 0) throw createFailure(run, `secret create for ${item.key}`, item.value);
-  }
-  for (const item of todo.configs) {
-    const run = create(ctx, 'config', [managed, tagged], item.name, configBytes(item.file));
-    if (run.error || run.status !== 0) throw createFailure(run, `config create for ${item.logical}`);
-  }
+    const managed = `${config.stack}.managed=true`;
+    const tagged = `${config.stack}.release=${id}`;
+    for (const item of todo.secrets) {
+        const run = create(ctx, 'secret', [managed, `${config.stack}.key=${item.key}`, tagged], item.name, item.value);
+        if (run.error || run.status !== 0)
+            throw createFailure(run, `secret create for ${item.key}`, item.value);
+    }
+    for (const item of todo.configs) {
+        const run = create(ctx, 'config', [managed, tagged], item.name, configBytes(item.file));
+        if (run.error || run.status !== 0)
+            throw createFailure(run, `config create for ${item.logical}`);
+    }
 }
-
 /** Creates the missing secrets and configs of a release; without `execute` it only reports what it would create. */
 export async function provisionRelease(ctx, config, options = {}) {
-  const release = readRelease(options);
-  const id = releaseId(release);
-  const todo = plan(ctx, config, release, loadSealed(ctx, config));
-  const data = { created: todo.secrets.length, kept: todo.kept, configsCreated: todo.configs.length };
-  if (options.execute !== true) {
-    const keys = todo.secrets.map((item) => item.key).join(', ');
-    return { ok: true, lines: [`dry run: would create ${data.created} secrets (${keys}), ${data.configsCreated} configs; ${data.kept} kept`], data };
-  }
-  createAll(ctx, config, id, todo);
-  return { ok: true, lines: [`provision: secrets created ${data.created}, kept ${data.kept}; configs created ${data.configsCreated}`], data };
+    const release = readRelease(options);
+    const id = releaseId(release);
+    const todo = plan(ctx, config, release, loadSealed(ctx, config));
+    const data = { created: todo.secrets.length, kept: todo.kept, configsCreated: todo.configs.length };
+    if (options.execute !== true) {
+        const keys = todo.secrets.map((item) => item.key).join(', ');
+        return { ok: true, lines: [`dry run: would create ${data.created} secrets (${keys}), ${data.configsCreated} configs; ${data.kept} kept`], data };
+    }
+    createAll(ctx, config, id, todo);
+    return { ok: true, lines: [`provision: secrets created ${data.created}, kept ${data.kept}; configs created ${data.configsCreated}`], data };
 }

package/stack/prune.d.mts

@@ -0,0 +1,11 @@
+import type { DeployConfig } from './config.mjs';
+import type { StackContext } from './context.mjs';
+import type { ActionResult } from './remote.mjs';
+/**
+ * Prunes superseded managed secrets and configs. `keepFiles` are the release.json files to keep (at least one).
+ * Returns { ok, lines, data: { kept, candidates, removed, inUse } }.
+ */
+export declare function pruneStack(ctx: StackContext, config: DeployConfig, { keepFiles, execute }?: {
+    keepFiles?: string[];
+    execute?: boolean;
+}): Promise<ActionResult>;

package/stack/prune.mjs

@@ -4,43 +4,54 @@
 import fs from 'node:fs';
 import { firstLine, lines as splitLines, tool } from './context.mjs';
 import { failure, refusal } from './errors.mjs';
-
 const KINDS = ['secret', 'config'];
-
 /** The runtime names a kept release.json holds: secret runtimeNames and config names (names only, never values). */
 function keptNames(files) {
-  const keep = new Set();
-  for (const file of files) {
-    let release;
-    try { release = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { throw refusal('STACK_PRUNE_KEEP_INVALID', `${file} is not a readable release.json`); }
-    for (const secret of release.secrets ?? []) keep.add(secret.runtimeName);
-    for (const config of release.configs ?? []) keep.add(config.name);
-  }
-  return keep;
+    const keep = new Set();
+    for (const file of files) {
+        // reason: release.json parsed from disk; only the name fields are read
+        let release;
+        try {
+            release = JSON.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch {
+            throw refusal('STACK_PRUNE_KEEP_INVALID', `${file} is not a readable release.json`);
+        }
+        for (const secret of release.secrets ?? [])
+            keep.add(secret.runtimeName);
+        for (const config of release.configs ?? [])
+            keep.add(config.name);
+    }
+    return keep;
 }
-
 function managed(ctx, config, kind) {
-  const list = tool(ctx, 'docker', [kind, 'ls', '--filter', `label=${config.stack}.managed=true`, '--format', '{{.Name}}']);
-  if (list.status !== 0) throw failure('STACK_PRUNE_LIST', `docker ${kind} ls failed: ${firstLine(list.stderr)}`);
-  return splitLines(list.stdout);
+    const list = tool(ctx, 'docker', [kind, 'ls', '--filter', `label=${config.stack}.managed=true`, '--format', '{{.Name}}']);
+    if (list.status !== 0)
+        throw failure('STACK_PRUNE_LIST', `docker ${kind} ls failed: ${firstLine(list.stderr)}`);
+    return splitLines(list.stdout);
 }
-
 /**
  * Prunes superseded managed secrets and configs. `keepFiles` are the release.json files to keep (at least one).
  * Returns { ok, lines, data: { kept, candidates, removed, inUse } }.
  */
 export async function pruneStack(ctx, config, { keepFiles = [], execute = false } = {}) {
-  if (keepFiles.length === 0) throw refusal('STACK_PRUNE_NO_KEEP', 'prune needs --keep <release.json> (at least the accepted release)');
-  const keep = keptNames(keepFiles);
-  const out = { lines: [], removed: 0, inUse: 0, candidates: 0 };
-  for (const kind of KINDS) {
-    for (const name of managed(ctx, config, kind).filter((entry) => !keep.has(entry))) {
-      out.candidates += 1;
-      if (!execute) out.lines.push(`dry run: would remove ${kind} ${name}`);
-      else if (tool(ctx, 'docker', [kind, 'rm', name]).status === 0) out.removed += 1;
-      else { out.inUse += 1; out.lines.push(`${kind} ${name} is still in use; left alone`); }
+    if (keepFiles.length === 0)
+        throw refusal('STACK_PRUNE_NO_KEEP', 'prune needs --keep <release.json> (at least the accepted release)');
+    const keep = keptNames(keepFiles);
+    const out = { lines: [], removed: 0, inUse: 0, candidates: 0 };
+    for (const kind of KINDS) {
+        for (const name of managed(ctx, config, kind).filter((entry) => !keep.has(entry))) {
+            out.candidates += 1;
+            if (!execute)
+                out.lines.push(`dry run: would remove ${kind} ${name}`);
+            else if (tool(ctx, 'docker', [kind, 'rm', name]).status === 0)
+                out.removed += 1;
+            else {
+                out.inUse += 1;
+                out.lines.push(`${kind} ${name} is still in use; left alone`);
+            }
+        }
     }
-  }
-  out.lines.push(execute ? `prune: removed ${out.removed} superseded objects, ${out.inUse} still in use` : `dry run: ${out.candidates} superseded objects would be removed`);
-  return { ok: true, lines: out.lines, data: { kept: keep.size, candidates: out.candidates, removed: out.removed, inUse: out.inUse } };
+    out.lines.push(execute ? `prune: removed ${out.removed} superseded objects, ${out.inUse} still in use` : `dry run: ${out.candidates} superseded objects would be removed`);
+    return { ok: true, lines: out.lines, data: { kept: keep.size, candidates: out.candidates, removed: out.removed, inUse: out.inUse } };
 }

package/stack/release-store.d.mts

@@ -0,0 +1,28 @@
+import type { RemoteResult } from './remote.mjs';
+import type { DeployConfig } from './config.mjs';
+/** The ssh runner a store runs its commands through. */
+export type StoreSsh = (command: string, options: {
+    input?: string | undefined;
+}) => RemoteResult | Promise<RemoteResult>;
+/** One stored release and whether it is the current or the previous one. */
+export interface ReleaseEntry {
+    id: string;
+    current: boolean;
+    previous: boolean;
+}
+/** The release record protocol on the manager (see createReleaseStore). */
+export interface ReleaseStore {
+    store(dir: string, id: string): Promise<void>;
+    accept(id: string): Promise<void>;
+    current(): Promise<string>;
+    previous(): Promise<string>;
+    fetch(id: string, targetDir: string): Promise<string>;
+    list(): Promise<ReleaseEntry[]>;
+}
+/** Removes every carriage return: a snippet from a Windows checkout must never reach a remote shell with CRLF. */
+export declare const lfOnly: (text: unknown) => string;
+/**
+ * The release store of one stack. `ssh` is the runner; the returned API is async:
+ *   store(dir, id) accept(id) current() previous() fetch(id, targetDir) list()
+ */
+export declare function createReleaseStore(config: Pick<DeployConfig, 'remote' | 'stack'>, ssh: StoreSsh): ReleaseStore;

package/stack/release-store.mjs

@@ -9,84 +9,85 @@ import { firstLine, lines as splitLines } from './context.mjs';
 import { isReleaseId } from './digest.mjs';
 import { failure, refusal } from './errors.mjs';
 import { releaseListScript, releasePointerScript } from './remote.mjs';
-
 const BASE = /^\/[A-Za-z0-9._/-]+$/u;
 const FILES = ['stack.yaml', 'release.json'];
-
 /** Removes every carriage return: a snippet from a Windows checkout must never reach a remote shell with CRLF. */
 export const lfOnly = (text) => String(text).replaceAll('\r', '');
-
 const checkedId = (id) => {
-  if (!isReleaseId(id)) throw refusal('STACK_RELEASE_ID', 'a release id is exactly 16 lowercase hex characters');
-  return id;
+    if (!isReleaseId(id))
+        throw refusal('STACK_RELEASE_ID', 'a release id is exactly 16 lowercase hex characters');
+    return id;
 };
-
 const checkedBase = (config) => {
-  const base = config.remote?.releasesBase ?? `/srv/${config.stack}`;
-  if (!BASE.test(base) || base.split('/').includes('..')) throw refusal('STACK_RELEASE_BASE', `the releases base ${base} must be an absolute path without ..`);
-  return base;
+    const base = config.remote?.releasesBase ?? `/srv/${config.stack}`;
+    if (!BASE.test(base) || base.split('/').includes('..'))
+        throw refusal('STACK_RELEASE_BASE', `the releases base ${base} must be an absolute path without ..`);
+    return base;
 };
-
 /**
  * The release store of one stack. `ssh` is the runner; the returned API is async:
  *   store(dir, id) accept(id) current() previous() fetch(id, targetDir) list()
  */
 export function createReleaseStore(config, ssh) {
-  const base = checkedBase(config);
-  const dirOf = (id) => `${base}/releases/${checkedId(id)}`;
-
-  async function run(command, input) {
-    const answer = await ssh(lfOnly(command), { input });
-    if (answer.status !== 0) throw failure('STACK_RELEASE_SSH', `remote command failed: ${firstLine(answer.stderr)}`);
-    return answer.stdout;
-  }
-
-  function readLocal(dir, name) {
-    try { return fs.readFileSync(path.join(dir, name), 'utf8'); } catch { throw failure('STACK_RELEASE_STORE', `cannot read ${name} in ${dir}`); }
-  }
-
-  async function pointer(name) {
-    const out = await run(releasePointerScript(`"${base}"`, name));
-    const id = out.trim();
-    return isReleaseId(id) ? id : '';
-  }
-
-  return {
-    /** Uploads stack.yaml and release.json of a rendered release as text; read-only afterwards. */
-    async store(dir, id) {
-      const target = dirOf(id);
-      const contents = FILES.map((name) => [name, readLocal(dir, name)]);
-      const input = contents.map(([, text]) => Buffer.from(text, 'utf8').toString('base64')).join('\n') + '\n';
-      await run(`set -e; d="${target}"; if [ -d "$d" ]; then chmod -R u+w "$d"; else mkdir -p "$d"; fi; IFS= read -r stack; IFS= read -r release; printf '%s' "$stack" | base64 -d > "$d/stack.yaml"; printf '%s' "$release" | base64 -d > "$d/release.json"; chmod 440 "$d/stack.yaml" "$d/release.json"; chmod 550 "$d"`, input);
-    },
-    /** The release was verified: previous := current, current := id. */
-    async accept(id) {
-      checkedId(id);
-      await run(`set -e; cd "${base}"; test -d "releases/${id}"; if [ -L current ] && [ "$(basename "$(readlink current)")" != "${id}" ]; then ln -sfn "$(readlink current)" previous; fi; ln -sfn "releases/${id}" current.new; mv -Tf current.new current`);
-    },
-    /** The accepted release id, '' when none. */
-    current: () => pointer('current'),
-    /** The release accepted before the current one, '' when none. */
-    previous: () => pointer('previous'),
-    /** Downloads a stored release (both files) into `targetDir` for a rollback or an audit. */
-    async fetch(id, targetDir) {
-      const source = dirOf(id);
-      const out = await run(`set -e; for f in stack.yaml release.json; do test -r "${source}/$f"; base64 < "${source}/$f" | tr -d '\\n'; printf '\\n'; done`);
-      const frames = out.split('\n');
-      if (frames.length !== 3 || frames[2] !== '' || frames.slice(0, 2).some((frame) => !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(frame))) throw failure('STACK_RELEASE_SSH', 'invalid release response framing');
-      const files = FILES.map((name, index) => [name, Buffer.from(frames[index], 'base64').toString('utf8')]);
-      fs.mkdirSync(targetDir, { recursive: true });
-      for (const [name, text] of files) fs.writeFileSync(path.join(targetDir, name), text);
-      return targetDir;
-    },
-    /** The stored releases, newest first: [{ id, current, previous }]. */
-    async list() {
-      const response = await run(`${releasePointerScript(`"${base}"`, 'current')}; ${releasePointerScript(`"${base}"`, 'previous')}; ${releaseListScript(`"${base}"`)}`);
-      const [current, previous, ...entries] = response.split('\n');
-      const now = isReleaseId(current) ? current : '';
-      const before = isReleaseId(previous) ? previous : '';
-      const out = entries.join('\n');
-      return splitLines(out).filter(isReleaseId).map((id) => ({ id, current: id === now, previous: id === before }));
-    },
-  };
+    const base = checkedBase(config);
+    const dirOf = (id) => `${base}/releases/${checkedId(id)}`;
+    async function run(command, input) {
+        const answer = await ssh(lfOnly(command), { input });
+        if (answer.status !== 0)
+            throw failure('STACK_RELEASE_SSH', `remote command failed: ${firstLine(answer.stderr)}`);
+        return answer.stdout;
+    }
+    function readLocal(dir, name) {
+        try {
+            return fs.readFileSync(path.join(dir, name), 'utf8');
+        }
+        catch {
+            throw failure('STACK_RELEASE_STORE', `cannot read ${name} in ${dir}`);
+        }
+    }
+    async function pointer(name) {
+        const out = await run(releasePointerScript(`"${base}"`, name));
+        const id = out.trim();
+        return isReleaseId(id) ? id : '';
+    }
+    return {
+        /** Uploads stack.yaml and release.json of a rendered release as text; read-only afterwards. */
+        async store(dir, id) {
+            const target = dirOf(id);
+            const contents = FILES.map((name) => [name, readLocal(dir, name)]);
+            const input = contents.map(([, text]) => Buffer.from(text, 'utf8').toString('base64')).join('\n') + '\n';
+            await run(`set -e; d="${target}"; if [ -d "$d" ]; then chmod -R u+w "$d"; else mkdir -p "$d"; fi; IFS= read -r stack; IFS= read -r release; printf '%s' "$stack" | base64 -d > "$d/stack.yaml"; printf '%s' "$release" | base64 -d > "$d/release.json"; chmod 440 "$d/stack.yaml" "$d/release.json"; chmod 550 "$d"`, input);
+        },
+        /** The release was verified: previous := current, current := id. */
+        async accept(id) {
+            checkedId(id);
+            await run(`set -e; cd "${base}"; test -d "releases/${id}"; if [ -L current ] && [ "$(basename "$(readlink current)")" != "${id}" ]; then ln -sfn "$(readlink current)" previous; fi; ln -sfn "releases/${id}" current.new; mv -Tf current.new current`);
+        },
+        /** The accepted release id, '' when none. */
+        current: () => pointer('current'),
+        /** The release accepted before the current one, '' when none. */
+        previous: () => pointer('previous'),
+        /** Downloads a stored release (both files) into `targetDir` for a rollback or an audit. */
+        async fetch(id, targetDir) {
+            const source = dirOf(id);
+            const out = await run(`set -e; for f in stack.yaml release.json; do test -r "${source}/$f"; base64 < "${source}/$f" | tr -d '\\n'; printf '\\n'; done`);
+            const frames = out.split('\n');
+            if (frames.length !== 3 || frames[2] !== '' || frames.slice(0, 2).some((frame) => !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(frame)))
+                throw failure('STACK_RELEASE_SSH', 'invalid release response framing');
+            const files = FILES.map((name, index) => [name, Buffer.from(frames[index], 'base64').toString('utf8')]);
+            fs.mkdirSync(targetDir, { recursive: true });
+            for (const [name, text] of files)
+                fs.writeFileSync(path.join(targetDir, name), text);
+            return targetDir;
+        },
+        /** The stored releases, newest first: [{ id, current, previous }]. */
+        async list() {
+            const response = await run(`${releasePointerScript(`"${base}"`, 'current')}; ${releasePointerScript(`"${base}"`, 'previous')}; ${releaseListScript(`"${base}"`)}`);
+            const [current, previous, ...entries] = response.split('\n');
+            const now = isReleaseId(current) ? current : '';
+            const before = isReleaseId(previous) ? previous : '';
+            const out = entries.join('\n');
+            return splitLines(out).filter(isReleaseId).map((id) => ({ id, current: id === now, previous: id === before }));
+        },
+    };
 }

package/stack/remote.d.mts

@@ -0,0 +1,83 @@
+import type { DeployConfig } from './config.mjs';
+import type { StackContext } from './context.mjs';
+import type { RemoteArgv } from './ssh-session.mjs';
+/** The outcome of one remote command. */
+export interface RemoteResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+}
+/** `run(command, { input })`: runs one shell command on the manager (see the top of the file). */
+export interface Runner {
+    (command: string, options?: {
+        input?: string | undefined;
+    }): RemoteResult;
+    cleanup: () => unknown;
+    notes: string[];
+    argv: (command: string) => RemoteArgv;
+}
+/** Where a verb gets its runner: `deps.ssh` wins in specs. */
+export interface RunnerDeps {
+    ssh?: Runner | undefined;
+}
+/** The options every action receives from the CLI to reach the manager. */
+export interface SshOptions {
+    sshCmd?: string | null | undefined;
+}
+/** The shape every action returns: `{ ok, lines, data }`; `refused` is set by a failed floor step of an urgent deploy. */
+export interface ActionResult<D extends object = Record<string, unknown>> {
+    ok: boolean;
+    lines: string[];
+    data?: D | undefined;
+    refused?: {
+        code: string;
+        message: string;
+    } | undefined;
+}
+/** Removes every carriage return. */
+export declare const lfOnly: (text: unknown) => string;
+/** POSIX single-quote quoting; NUL and line breaks cannot be quoted safely and are refused. */
+export declare function shellQuote(value: unknown): string;
+/**
+ * The shell that prints the release the symlink `name` under `quotedBase` (an already-quoted directory) points at, one line; an absent link prints an
+ * empty line and succeeds. Only the absent link is expected: a `readlink` or `basename` that fails fails the script, and the caller reports it.
+ */
+export declare const releasePointerScript: (quotedBase: string, name: string) => string;
+/** The shell that lists the stored releases under `quotedBase`/releases, newest first; no releases directory prints nothing and succeeds, a failing `ls` fails the script. */
+export declare const releaseListScript: (quotedBase: string) => string;
+/** Runs `docker <args>` on the manager through `run` (every argument quoted). */
+export declare const remoteDocker: (run: (command: string) => RemoteResult, args: string[]) => RemoteResult;
+/**
+ * The key each sealed SSH member of `deploy.remote.sealed` holds (contexts/project/stacks.md PROJECT-STACKS-5): the one owner of
+ * these names. `sshKey` names the member whose `privateKey` is the PEM private key, `knownHosts` the member whose `knownHosts` is
+ * the pinned known_hosts text.
+ */
+export declare const SEALED_SSH_KEYS: Readonly<{
+    sshKey: "privateKey";
+    knownHosts: "knownHosts";
+}>;
+/** The files and facts of one owner-machine session. */
+export interface SealedSession {
+    account: string;
+    dir: string;
+    keyFile: string;
+    knownFile: string;
+    strict: string;
+    notes: string[];
+    cleanup: () => void;
+    port?: number;
+}
+/** The owner-machine session files: key and known_hosts in a private temp directory, removed (key overwritten) by cleanup(). */
+export declare function openSealedSession(ctx: StackContext, config: DeployConfig): SealedSession;
+/** The runner of a verb that opens it itself (deploy, rollback, accept): the owner-machine session is selected exactly as `withRunner` does. */
+export declare const ownerSshRunner: (ctx: StackContext, config: DeployConfig, options?: SshOptions) => Runner;
+/** Opens the runner (`deps.ssh` wins in specs), calls `body(run, notes)` and always cleans the session up. */
+export declare function withRunner<T>(ctx: StackContext, config: DeployConfig, options: SshOptions, deps: RunnerDeps, body: (run: Runner, notes: string[]) => T | Promise<T>): Promise<T>;
+/** CI transport: pinned key, known_hosts, ssh config block and DOCKER_HOST=ssh://<alias> in $GITHUB_ENV. */
+export declare function connectCi(ctx: StackContext, config: DeployConfig, { execute }?: {
+    execute?: boolean;
+}): Promise<ActionResult>;
+/** CI cleanup: closes the ssh control master (failure ignored) and removes the deploy key. */
+export declare function disconnectCi(ctx: StackContext, config: DeployConfig, { execute }?: {
+    execute?: boolean;
+}): Promise<ActionResult>;