@starci/hfs 4.11.21 → 4.12.0

package/stack/config.mjs

@@ -6,54 +6,68 @@ import path from 'node:path';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
 import { DEPLOY_CONFIG_CODE, NAME, normalizeDeploy } from '../runtime/scripts/hfs/stack-deploy-config.mjs';
 import { refusal } from './errors.mjs';
-
 export const STACKS_DIR = '.starcistacks';
 export const STACKS_FILE = 'application-stacks.yaml';
-
 /** Read a YAML input, refusing with a stack error naming its purpose when it is missing or invalid. */
+// reason: parsed YAML from disk, its shape is judged by the callers
 export const readYaml = (file, what) => {
-  let source;
-  try { source = fs.readFileSync(file, 'utf8'); } catch { throw refusal('STACKS_DEPLOY_FILE_MISSING', `${what} (${file}) is not readable`); }
-  try { return parseYaml(source); } catch { throw refusal('STACKS_DEPLOY_FILE_INVALID', `${what} is not valid YAML`); }
+    let source;
+    try {
+        source = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        throw refusal('STACKS_DEPLOY_FILE_MISSING', `${what} (${file}) is not readable`);
+    }
+    try {
+        return parseYaml(source);
+    }
+    catch {
+        throw refusal('STACKS_DEPLOY_FILE_INVALID', `${what} is not valid YAML`);
+    }
 };
-
 const projectOf = (repoRoot) => {
-  const doc = JSON.parse(fs.readFileSync(path.join(repoRoot, 'hfs.json'), 'utf8'));
-  return String(doc.project);
+    const doc = JSON.parse(fs.readFileSync(path.join(repoRoot, 'hfs.json'), 'utf8'));
+    return String(doc.project);
 };
-
 const sealedMembers = (secretsDir) => {
-  try { return new Set(fs.readdirSync(secretsDir).filter(isSealedName).map(memberOfName)); } catch { return new Set(); }
+    try {
+        return new Set(fs.readdirSync(secretsDir).filter(isSealedName).map(memberOfName));
+    }
+    catch {
+        return new Set();
+    }
 };
-
 const stackServices = (stackFile) => {
-  const model = readYaml(stackFile, 'the stack source');
-  return new Set(Object.keys(model?.services ?? {}));
+    const model = readYaml(stackFile, 'the stack source');
+    return new Set(Object.keys(model?.services ?? {}));
 };
-
 /**
  * The normalised deploy configuration of one environment, with absolute paths:
  *   { env, project, stack, repoRoot, envDir, stackFile, secretsDir, members, services, ...deploy block }.
  * Throws StackError (exit 2) naming every problem when the block is missing or invalid.
  */
 export function loadDeployConfig({ repoRoot, env }) {
-  if (!NAME.test(String(env))) throw refusal(DEPLOY_CONFIG_CODE, `--env ${env} must match ${NAME}`);
-  const declaration = readYaml(path.join(repoRoot, STACKS_DIR, STACKS_FILE), STACKS_FILE);
-  const environment = declaration?.environments?.[env];
-  if (!environment) throw refusal('STACKS_DEPLOY_ENV_UNKNOWN', `${STACKS_FILE} declares no environment ${env}`);
-  if (environment.runtime !== 'docker-swarm') throw refusal('STACKS_DEPLOY_NOT_SWARM', `environment ${env} runs ${environment.runtime}; stack deploy verbs need docker-swarm`);
-  if (environment.deploy === undefined) throw refusal('STACKS_DEPLOY_UNDECLARED', `environment ${env} has no deploy block in ${STACKS_FILE}`);
-  const envDir = path.join(repoRoot, STACKS_DIR, env);
-  const stackFile = path.join(envDir, String(environment.composeFiles?.[0] ?? ''));
-  const secretsDir = path.join(envDir, 'secrets');
-  const services = stackServices(stackFile);
-  const members = sealedMembers(secretsDir);
-  const probe = { exists: (rel) => fs.existsSync(path.join(envDir, rel)), services, members };
-  const project = projectOf(repoRoot);
-  const { config, problems } = normalizeDeploy(environment.deploy, { project, probe });
-  if (!config) {
-    const first = problems.slice(0, 6).map((item) => `${item.at}: ${item.message}`).join('; ');
-    throw refusal(DEPLOY_CONFIG_CODE, `${problems.length} problem${problems.length === 1 ? '' : 's'} in environments.${env}.deploy: ${first}`);
-  }
-  return { env, project, repoRoot, envDir, stackFile, secretsDir, members, services, ...config };
+    if (!NAME.test(String(env)))
+        throw refusal(DEPLOY_CONFIG_CODE, `--env ${env} must match ${NAME}`);
+    const declaration = readYaml(path.join(repoRoot, STACKS_DIR, STACKS_FILE), STACKS_FILE);
+    const environment = declaration?.environments?.[env];
+    if (!environment)
+        throw refusal('STACKS_DEPLOY_ENV_UNKNOWN', `${STACKS_FILE} declares no environment ${env}`);
+    if (environment.runtime !== 'docker-swarm')
+        throw refusal('STACKS_DEPLOY_NOT_SWARM', `environment ${env} runs ${environment.runtime}; stack deploy verbs need docker-swarm`);
+    if (environment.deploy === undefined)
+        throw refusal('STACKS_DEPLOY_UNDECLARED', `environment ${env} has no deploy block in ${STACKS_FILE}`);
+    const envDir = path.join(repoRoot, STACKS_DIR, env);
+    const stackFile = path.join(envDir, String(environment.composeFiles?.[0] ?? ''));
+    const secretsDir = path.join(envDir, 'secrets');
+    const services = stackServices(stackFile);
+    const members = sealedMembers(secretsDir);
+    const probe = { exists: (rel) => fs.existsSync(path.join(envDir, rel)), services, members };
+    const project = projectOf(repoRoot);
+    const { config, problems } = normalizeDeploy(environment.deploy, { project, probe });
+    if (!config) {
+        const first = problems.slice(0, 6).map((item) => `${item.at}: ${item.message}`).join('; ');
+        throw refusal(DEPLOY_CONFIG_CODE, `${problems.length} problem${problems.length === 1 ? '' : 's'} in environments.${env}.deploy: ${first}`);
+    }
+    return { env, project, repoRoot, envDir, stackFile, secretsDir, members, services, ...config };
 }

package/stack/context.d.mts

@@ -0,0 +1,122 @@
+import type { ChildProcess } from 'node:child_process';
+import type { SshConnection } from './ssh-session.mjs';
+import type { AgeHost } from '../runtime/scripts/hfs/secret-init.mjs';
+/** The result of one tool run. */
+export interface RunResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: NodeJS.ErrnoException | undefined;
+}
+/** The options of one tool run: `input` is written to stdin, `env` replaces the child environment, `background` returns the child. */
+export interface SpawnOptions {
+    input?: string | Buffer | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    cwd?: string | undefined;
+    background?: boolean | undefined;
+    timeout?: number | undefined;
+    [option: string]: unknown;
+}
+/** A background child; an asynchronous spawn failure is kept on `spawnError`. */
+export type BackgroundChild = ChildProcess & {
+    spawnError?: Error;
+};
+/** The spawn seam: never a shell; `{ background: true }` returns the owned child. */
+export interface Spawn {
+    (command: string, args: readonly string[], options: SpawnOptions & {
+        background: true;
+    }): BackgroundChild;
+    (command: string, args: readonly string[], options?: SpawnOptions): RunResult;
+}
+/** The progress sink of a verb that checks or changes the host: successes, failures and neutral notes. */
+export interface Report {
+    ok(text: string): void;
+    bad(text: string): void;
+    note(text: string): void;
+}
+/** One end of a pipe: the process whose stdout is streamed, or the one that receives it on stdin. */
+export interface PipeEnd {
+    command: string;
+    args: string[];
+    env?: NodeJS.ProcessEnv | undefined;
+    cwd?: string | undefined;
+}
+/** Exit codes of both ends of a pipe and the first stderr line of a failure. */
+export interface PipeResult {
+    source: number;
+    sink: number;
+    stderr: string;
+}
+/** The secret seam: decrypts the app's sops files. */
+export interface Sops {
+    decrypt(file: string, format?: string): Record<string, string>;
+    decryptBinary(file: string): string;
+    /** Wraps one sealed member again to its rule (server-key); the owner identity opens the data key only. */
+    updateKeys(file: string): void;
+    /** Refuses up front when the owner identity is unreachable (optional: a spec double has none). */
+    requireIdentity?(file: string): void;
+    /** Where the age identity was found; a seam without it (a spec double) decides for itself. */
+    identity?: {
+        source: string | null;
+        looked: string[];
+    } | undefined;
+}
+/** What a caller (or a spec) may inject into stackContext; every seam is optional and defaults to the real one. */
+export interface StackIo {
+    cwd?: string | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    spawn?: Spawn | undefined;
+    platform?: NodeJS.Platform | undefined;
+    username?: string | undefined;
+    sshPath?: string | undefined;
+    sleep?: ((ms: number) => Promise<void>) | undefined;
+    now?: (() => number) | undefined;
+    stdout?: ((text: string) => void) | undefined;
+    stderr?: ((text: string) => void) | undefined;
+    fetch?: typeof fetch | undefined;
+    pipe?: ((source: PipeEnd, sink: PipeEnd) => Promise<PipeResult>) | undefined;
+    sops?: Sops | undefined;
+    openSops?: (() => Sops) | undefined;
+    hostIdentity?: AgeHost | null | undefined;
+    harness?: {
+        role?: string | undefined;
+    } | undefined;
+    importer?: ((file: string) => Promise<Record<string, unknown>>) | undefined;
+}
+/** The context of one stack invocation (see stackContext). */
+export interface StackContext {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly spawn: Spawn;
+    readonly platform: NodeJS.Platform;
+    readonly username: string | undefined;
+    readonly sshPath: string | undefined;
+    readonly sleep: (ms: number) => Promise<void>;
+    readonly now: () => number;
+    readonly stdout: (text: string) => void;
+    readonly stderr: (text: string) => void;
+    readonly fetch: typeof fetch;
+    readonly pipe: (source: PipeEnd, sink: PipeEnd) => Promise<PipeResult>;
+    readonly sops: Sops;
+    /** The command-owned SSH connection, set by the Docker transport (docker-transport.mjs). */
+    readonly stackSsh?: SshConnection | undefined;
+}
+/**
+ * The context of one stack invocation.
+ *   cwd, env       the app root and the process environment
+ *   spawn          (command, args, { input, env, cwd }) -> { status, stdout, stderr, error }; never a shell
+ *                  { background: true } -> ChildProcess, owned and killed by the command session
+ *   platform       POSIX control master or win32 loopback tunnel; sshPath optionally selects the POSIX SSH executable
+ *   sleep, now     await sleep(ms); now() -> epoch ms
+ *   stdout, stderr text writers
+ *   fetch          the HTTP seam of verify (url, init) -> Response
+ *   pipe           (source, sink) -> Promise<{ source, sink, stderr }>: one process's stdout streamed into another's stdin (realPipe)
+ *   sops           the secret seam (decrypt(file, format) -> map; decryptBinary(file) -> text); `io.sops`, else on first use `io.openSops()` or the app's own sops/age tools with the age identity decryptionIdentity finds (`io.hostIdentity` the harness CLI's secret.env)
+ */
+export declare function stackContext(io?: StackIo): StackContext;
+/** Runs one tool; `env` replaces the child environment when given, `input` is written to its stdin. */
+export declare const tool: (ctx: Pick<StackContext, "spawn">, command: string, args: readonly string[], options?: SpawnOptions) => RunResult;
+/** Runs a tool and returns stdout, or throws the first stderr line. Used where a failure has no recovery. */
+export declare function toolOutput(ctx: Pick<StackContext, 'spawn'>, command: string, args: readonly string[], options?: SpawnOptions): string;
+export declare const firstLine: (text: unknown) => string;
+export declare const lines: (text: unknown) => string[];

package/stack/context.mjs

@@ -2,51 +2,49 @@
 // Production uses the real implementations; a spec injects fakes.
 import { spawn, spawnSync } from 'node:child_process';
 import { defaultSops } from '../runtime/scripts/hfs/secret-sops.mjs';
-
 const MAX_BUFFER = 1 << 24;
-
-const realSpawn = (command, args, options = {}) => {
-  if (options.background) {
-    const childOptions = { ...options };
-    delete childOptions.background;
-    const child = spawn(command, args, { stdio: 'ignore', windowsHide: true, ...childOptions });
-    child.on('error', (error) => { child.spawnError = error; });
-    return child;
-  }
-  const run = spawnSync(command, args, { encoding: 'utf8', maxBuffer: MAX_BUFFER, ...options });
-  return { status: run.status, stdout: run.stdout ?? '', stderr: run.stderr ?? '', error: run.error };
-};
-
+const realSpawn = ((command, args, options = {}) => {
+    if (options.background) {
+        const childOptions = { ...options };
+        delete childOptions.background;
+        const child = spawn(command, args, { stdio: 'ignore', windowsHide: true, ...childOptions });
+        child.on('error', (error) => { child.spawnError = error; });
+        return child;
+    }
+    const run = spawnSync(command, args, { encoding: 'utf8', maxBuffer: MAX_BUFFER, ...options });
+    return { status: run.status, stdout: run.stdout ?? '', stderr: run.stderr ?? '', error: run.error };
+});
 /** Bytes of a stream's stderr a pipe keeps, for the first line of a failure. */
 const STDERR_KEPT = 4096;
-
 /**
  * Streams `source`'s stdout into `sink`'s stdin, neither through a shell, and resolves { source, sink, stderr } (exit codes and
  * the first stderr line of a failure). The bytes pass through the OS pipe only: they are never collected, logged or written to disk.
  */
 const realPipe = (source, sink) => new Promise((resolve) => {
-  const options = (end, stdio) => ({ env: end.env, cwd: end.cwd, stdio, windowsHide: true });
-  const from = spawn(source.command, source.args, options(source, ['ignore', 'pipe', 'pipe']));
-  const to = spawn(sink.command, sink.args, options(sink, ['pipe', 'ignore', 'pipe']));
-  const codes = {};
-  let stderr = '';
-  const keep = (chunk) => { if (stderr.length < STDERR_KEPT) stderr += String(chunk).slice(0, STDERR_KEPT - stderr.length); };
-  from.stderr.on('data', keep);
-  to.stderr.on('data', keep);
-  to.stdin.on('error', () => {});
-  from.stdout.pipe(to.stdin);
-  const settle = (name) => (code) => {
-    codes[name] = code ?? 1;
-    if ('source' in codes && 'sink' in codes) resolve({ ...codes, stderr: stderr.trim().split(/\r?\n/u)[0] ?? '' });
-  };
-  from.on('error', () => { from.stdout.unpipe(to.stdin); to.stdin.end(); settle('source')(127); });
-  to.on('error', () => settle('sink')(127));
-  from.on('close', settle('source'));
-  to.on('close', settle('sink'));
+    const options = (end, stdio) => ({ env: end.env, cwd: end.cwd, stdio, windowsHide: true });
+    const from = spawn(source.command, source.args, options(source, ['ignore', 'pipe', 'pipe']));
+    const to = spawn(sink.command, sink.args, options(sink, ['pipe', 'ignore', 'pipe']));
+    const codes = {};
+    let stderr = '';
+    const keep = (chunk) => { if (stderr.length < STDERR_KEPT)
+        stderr += String(chunk).slice(0, STDERR_KEPT - stderr.length); };
+    from.stderr?.on('data', keep);
+    to.stderr?.on('data', keep);
+    to.stdin?.on('error', () => { });
+    if (from.stdout && to.stdin)
+        from.stdout.pipe(to.stdin);
+    const settle = (name) => (code) => {
+        codes[name] = code ?? 1;
+        if (codes.source !== undefined && codes.sink !== undefined)
+            resolve({ source: codes.source, sink: codes.sink, stderr: stderr.trim().split(/\r?\n/u)[0] ?? '' });
+    };
+    from.on('error', () => { if (from.stdout && to.stdin)
+        from.stdout.unpipe(to.stdin); to.stdin?.end(); settle('source')(127); });
+    to.on('error', () => settle('sink')(127));
+    from.on('close', settle('source'));
+    to.on('close', settle('sink'));
 });
-
 const realSleep = (ms) => new Promise((done) => { setTimeout(done, ms); });
-
 /**
  * The context of one stack invocation.
  *   cwd, env       the app root and the process environment
@@ -60,40 +58,40 @@ const realSleep = (ms) => new Promise((done) => { setTimeout(done, ms); });
  *   sops           the secret seam (decrypt(file, format) -> map; decryptBinary(file) -> text); `io.sops`, else on first use `io.openSops()` or the app's own sops/age tools with the age identity decryptionIdentity finds (`io.hostIdentity` the harness CLI's secret.env)
  */
 export function stackContext(io = {}) {
-  const cwd = io.cwd ?? process.cwd();
-  const env = io.env ?? process.env;
-  let sops = io.sops;
-  return Object.freeze({
-    cwd,
-    env,
-    spawn: io.spawn ?? realSpawn,
-    platform: io.platform ?? process.platform,
-    username: io.username,
-    sshPath: io.sshPath,
-    sleep: io.sleep ?? realSleep,
-    now: io.now ?? Date.now,
-    stdout: io.stdout ?? ((text) => process.stdout.write(text)),
-    stderr: io.stderr ?? ((text) => process.stderr.write(text)),
-    fetch: io.fetch ?? globalThis.fetch,
-    pipe: io.pipe ?? realPipe,
-    /** The secret seam: the app's own sops/age tools, created on first use so verbs that open no custody never need them. */
-    get sops() {
-      sops ??= io.openSops?.() ?? defaultSops(env, cwd, io.platform ?? process.platform, undefined, io.hostIdentity ?? null);
-      return sops;
-    },
-  });
+    const cwd = io.cwd ?? process.cwd();
+    const env = io.env ?? process.env;
+    let sops = io.sops;
+    return Object.freeze({
+        cwd,
+        env,
+        spawn: io.spawn ?? realSpawn,
+        platform: io.platform ?? process.platform,
+        username: io.username,
+        sshPath: io.sshPath,
+        sleep: io.sleep ?? realSleep,
+        now: io.now ?? Date.now,
+        stdout: io.stdout ?? ((text) => process.stdout.write(text)),
+        stderr: io.stderr ?? ((text) => process.stderr.write(text)),
+        fetch: io.fetch ?? globalThis.fetch,
+        pipe: io.pipe ?? realPipe,
+        /** The secret seam: the app's own sops/age tools, created on first use so verbs that open no custody never need them. */
+        get sops() {
+            const opened = sops ?? io.openSops?.() ?? defaultSops(env, cwd, io.platform ?? process.platform, undefined, io.hostIdentity ?? null);
+            sops = opened;
+            return opened;
+        },
+    });
 }
-
 /** Runs one tool; `env` replaces the child environment when given, `input` is written to its stdin. */
 export const tool = (ctx, command, args, options = {}) => ctx.spawn(command, args, options);
-
 /** Runs a tool and returns stdout, or throws the first stderr line. Used where a failure has no recovery. */
 export function toolOutput(ctx, command, args, options = {}) {
-  const run = tool(ctx, command, args, options);
-  if (run.error) throw new Error(`cannot run ${command} (${run.error.message})`);
-  if (run.status !== 0) throw new Error(`${command} ${args.slice(0, 2).join(' ')}: ${firstLine(run.stderr)}`);
-  return run.stdout;
+    const run = tool(ctx, command, args, options);
+    if (run.error)
+        throw new Error(`cannot run ${command} (${run.error.message})`);
+    if (run.status !== 0)
+        throw new Error(`${command} ${args.slice(0, 2).join(' ')}: ${firstLine(run.stderr)}`);
+    return run.stdout;
 }
-
-export const firstLine = (text) => String(text ?? '').trim().split(/\r?\n/u)[0];
+export const firstLine = (text) => String(text ?? '').trim().split(/\r?\n/u)[0] ?? '';
 export const lines = (text) => String(text ?? '').split(/\r?\n/u).filter(Boolean);

package/stack/converge.d.mts

@@ -0,0 +1,13 @@
+import type { DeployConfig } from './config.mjs';
+import type { StackContext } from './context.mjs';
+import type { ActionResult } from './remote.mjs';
+type Ctx = Pick<StackContext, 'spawn' | 'now' | 'sleep'>;
+/**
+ * Waits until the stack converged. `since` is the ISO instant the deploy began (required). Returns { ok, lines, data: { services, failed, pending } };
+ * on failure the lines name the service and the Swarm task error text.
+ */
+export declare function convergeStack(ctx: Ctx, config: DeployConfig, { since, timeoutSeconds }?: {
+    since?: string | undefined;
+    timeoutSeconds?: number | undefined;
+}): Promise<ActionResult>;
+export {};

package/stack/converge.mjs

@@ -7,101 +7,105 @@
 import { repeatInOrder } from '../runtime/scripts/lib/in-order.mjs';
 import { lines as splitLines, toolOutput } from './context.mjs';
 import { refusal } from './errors.mjs';
-
 const POLL_MS = 5000;
 const TAB = String.fromCodePoint(9);
 // The spec is JSON (it never holds a raw tab), so it is split off at the last tab; the error text before it may hold anything.
 const TASK_FORMAT = `{{.DesiredState}}|{{.Status.State}}|{{.Status.Timestamp}}|{{.Status.Err}}${TAB}{{json .Spec}}`;
-
 const docker = (ctx, args) => toolOutput(ctx, 'docker', args);
-
 /** The JSON text with object keys sorted at every depth, so two equal specs compare equal whatever the key order. */
 function canonical(value) {
-  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
-  if (value !== null && typeof value === 'object') return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
-  return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (value !== null && typeof value === 'object')
+        return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+    return JSON.stringify(value);
 }
-
 function sameSpec(taskSpec, template) {
-  try {
-    return template === undefined || canonical(JSON.parse(taskSpec)) === template;
-  } catch {
-    return true;
-  }
+    try {
+        return template === undefined || canonical(JSON.parse(taskSpec)) === template;
+    }
+    catch {
+        return true;
+    }
 }
-
 /** Failed or rejected tasks of the current spec created since the deploy began, and how many tasks run as desired. */
 function readTasks(ctx, name, sinceMs, template) {
-  const ids = splitLines(docker(ctx, ['service', 'ps', name, '--no-trunc', '-q']));
-  const rows = ids.length === 0 ? [] : splitLines(docker(ctx, ['inspect', '--type', 'task', '--format', TASK_FORMAT, ...ids]));
-  const out = { running: 0, failed: [] };
-  for (const row of rows) {
-    const cut = row.lastIndexOf(TAB);
-    const [wanted, state, timestamp, ...rest] = (cut < 0 ? row : row.slice(0, cut)).split('|');
-    if (wanted === 'running' && state === 'running') out.running += 1;
-    const current = cut < 0 || sameSpec(row.slice(cut + 1), template);
-    if ((state === 'failed' || state === 'rejected') && current && Date.parse(timestamp) >= sinceMs) out.failed.push(`${name}: task ${state}: ${rest.join('|')}`);
-  }
-  return out;
+    const ids = splitLines(docker(ctx, ['service', 'ps', name, '--no-trunc', '-q']));
+    const rows = ids.length === 0 ? [] : splitLines(docker(ctx, ['inspect', '--type', 'task', '--format', TASK_FORMAT, ...ids]));
+    const out = { running: 0, failed: [] };
+    for (const row of rows) {
+        const cut = row.lastIndexOf(TAB);
+        const [wanted, state, timestamp, ...rest] = (cut < 0 ? row : row.slice(0, cut)).split('|');
+        if (wanted === 'running' && state === 'running')
+            out.running += 1;
+        const current = cut < 0 || sameSpec(row.slice(cut + 1), template);
+        if ((state === 'failed' || state === 'rejected') && current && Date.parse(timestamp ?? '') >= sinceMs)
+            out.failed.push(`${name}: task ${state}: ${rest.join('|')}`);
+    }
+    return out;
 }
-
 /** One service: { pending, failed } lines. A rolled back or paused update since the deploy began fails it at once. */
 function observeService(ctx, name, sinceMs) {
-  const inspect = JSON.parse(docker(ctx, ['service', 'inspect', name, '--format', '{{json .}}']));
-  const desired = inspect.Spec?.Mode?.Replicated?.Replicas ?? 1;
-  const update = inspect.UpdateStatus;
-  const recentUpdate = Boolean(update) && (update.StartedAt ? Date.parse(update.StartedAt) : 0) >= sinceMs;
-  if (recentUpdate && /rollback|paused/u.test(update.State)) return { pending: [], failed: [`${name}: update ${update.State}: ${update.Message ?? ''}`] };
-  const pending = recentUpdate && update.State !== 'completed' ? [`${name}: update in progress (${update.State})`] : [];
-  const taskTemplate = inspect.Spec?.TaskTemplate;
-  const tasks = readTasks(ctx, name, sinceMs, taskTemplate === undefined ? undefined : canonical(taskTemplate));
-  if (tasks.running !== desired) pending.push(`${name}: ${tasks.running}/${desired} running`);
-  return { pending, failed: tasks.failed };
+    // reason: `docker service inspect` output, parsed JSON read defensively below
+    const inspect = JSON.parse(docker(ctx, ['service', 'inspect', name, '--format', '{{json .}}']));
+    const desired = inspect.Spec?.Mode?.Replicated?.Replicas ?? 1;
+    const update = inspect.UpdateStatus;
+    const recentUpdate = Boolean(update) && (update.StartedAt ? Date.parse(update.StartedAt) : 0) >= sinceMs;
+    if (recentUpdate && /rollback|paused/u.test(update.State))
+        return { pending: [], failed: [`${name}: update ${update.State}: ${update.Message ?? ''}`] };
+    const pending = recentUpdate && update.State !== 'completed' ? [`${name}: update in progress (${update.State})`] : [];
+    const taskTemplate = inspect.Spec?.TaskTemplate;
+    const tasks = readTasks(ctx, name, sinceMs, taskTemplate === undefined ? undefined : canonical(taskTemplate));
+    if (tasks.running !== desired)
+        pending.push(`${name}: ${tasks.running}/${desired} running`);
+    return { pending, failed: tasks.failed };
 }
-
 /** One observation over every service of the stack: { ok, pending, failed, services }. */
 function observe(ctx, config, sinceMs) {
-  const services = splitLines(docker(ctx, ['service', 'ls', '--filter', `label=com.docker.stack.namespace=${config.stack}`, '--format', '{{.Name}}']));
-  const result = { pending: services.length === 0 ? [`no service of stack ${config.stack} yet`] : [], failed: [], services };
-  for (const name of services) {
-    const found = observeService(ctx, name, sinceMs);
-    result.pending.push(...found.pending);
-    result.failed.push(...found.failed);
-  }
-  return { ...result, ok: result.pending.length === 0 && result.failed.length === 0 };
+    const services = splitLines(docker(ctx, ['service', 'ls', '--filter', `label=com.docker.stack.namespace=${config.stack}`, '--format', '{{.Name}}']));
+    const result = { pending: services.length === 0 ? [`no service of stack ${config.stack} yet`] : [], failed: [], services };
+    for (const name of services) {
+        const found = observeService(ctx, name, sinceMs);
+        result.pending.push(...found.pending);
+        result.failed.push(...found.failed);
+    }
+    return { ...result, ok: result.pending.length === 0 && result.failed.length === 0 };
 }
-
 /** The observation, or a pending line when docker failed (a thrown docker error is never a crash). */
 function tryObserve(ctx, config, sinceMs, previous) {
-  try {
-    return observe(ctx, config, sinceMs);
-  } catch (error) {
-    return { ok: false, pending: [String(error.message)], failed: [], services: previous.services };
-  }
+    try {
+        return observe(ctx, config, sinceMs);
+    }
+    catch (error) {
+        return { ok: false, pending: [String(error.message)], failed: [], services: previous.services };
+    }
 }
-
 const result = (ok, lines, last) => ({ ok, lines, data: { services: last.services, failed: last.failed, pending: last.pending } });
-
 /**
  * Waits until the stack converged. `since` is the ISO instant the deploy began (required). Returns { ok, lines, data: { services, failed, pending } };
  * on failure the lines name the service and the Swarm task error text.
  */
 export async function convergeStack(ctx, config, { since, timeoutSeconds = 600 } = {}) {
-  const sinceMs = Date.parse(since);
-  if (Number.isNaN(sinceMs)) throw refusal('STACK_CONVERGE_SINCE', '--since must be an ISO instant such as 2026-01-31T10:00:00Z');
-  const deadline = ctx.now() + timeoutSeconds * 1000;
-  let last = { pending: ['not observed'], failed: [], services: [] };
-  let stable = 0;
-  const outcome = await repeatInOrder(async () => {
-    if (ctx.now() >= deadline) return 'timeout';
-    last = tryObserve(ctx, config, sinceMs, last);
-    if (last.failed.length > 0) return 'failed';
-    stable = last.ok ? stable + 1 : 0;
-    if (stable >= 2) return 'converged';
-    await ctx.sleep(POLL_MS);
-    return undefined;
-  });
-  if (outcome === 'converged') return result(true, [`converge: ${last.services.join(', ')}: desired replicas running, no failed task`], last);
-  const reasons = [...last.failed, ...last.pending].map((line) => `  ${line}`);
-  return result(false, [`converge: ${last.failed.length > 0 ? 'FAILED' : 'TIMEOUT'}`, ...reasons], last);
+    const sinceMs = Date.parse(since ?? '');
+    if (Number.isNaN(sinceMs))
+        throw refusal('STACK_CONVERGE_SINCE', '--since must be an ISO instant such as 2026-01-31T10:00:00Z');
+    const deadline = ctx.now() + timeoutSeconds * 1000;
+    let last = { pending: ['not observed'], failed: [], services: [] };
+    let stable = 0;
+    const outcome = await repeatInOrder(async () => {
+        if (ctx.now() >= deadline)
+            return 'timeout';
+        last = tryObserve(ctx, config, sinceMs, last);
+        if (last.failed.length > 0)
+            return 'failed';
+        stable = last.ok ? stable + 1 : 0;
+        if (stable >= 2)
+            return 'converged';
+        await ctx.sleep(POLL_MS);
+        return undefined;
+    });
+    if (outcome === 'converged')
+        return result(true, [`converge: ${last.services.join(', ')}: desired replicas running, no failed task`], last);
+    const reasons = [...last.failed, ...last.pending].map((line) => `  ${line}`);
+    return result(false, [`converge: ${last.failed.length > 0 ? 'FAILED' : 'TIMEOUT'}`, ...reasons], last);
 }