@starci/hfs 4.11.22 → 4.12.0

package/stack/image-scan.mjs

@@ -9,16 +9,15 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { firstLine, lines as splitLines, tool } from './context.mjs';
-
 const SECRET_PATTERNS = [
-  ['a private key block', /-----BEGIN (?:[A-Z]+ )*PRIVATE KEY-----/u],
-  ['an age secret key', /AGE-SECRET-KEY-1[0-9A-Z]{20,}/u],
-  ['a sealed secret envelope', /ENC\[AES256_GCM,/u],
-  ['sops metadata', /"sops"\s*:\s*\{|^sops:\s*$/mu],
-  ['a GitHub token', /\bgh[pousr]_[A-Za-z0-9]{30,}\b/u],
-  ['an AWS access key id', /\bAKIA[0-9A-Z]{16}\b/u],
-  ['a Slack token', /\bxox[abprs]-[A-Za-z0-9-]{10,}/u],
-  ['a live API key', /\b(?:sk|rk)_live_[A-Za-z0-9]{16,}/u],
+    ['a private key block', /-----BEGIN (?:[A-Z]+ )*PRIVATE KEY-----/u],
+    ['an age secret key', /AGE-SECRET-KEY-1[0-9A-Z]{20,}/u],
+    ['a sealed secret envelope', /ENC\[AES256_GCM,/u],
+    ['sops metadata', /"sops"\s*:\s*\{|^sops:\s*$/mu],
+    ['a GitHub token', /\bgh[pousr]_[A-Za-z0-9]{30,}\b/u],
+    ['an AWS access key id', /\bAKIA[0-9A-Z]{16}\b/u],
+    ['a Slack token', /\bxox[abprs]-[A-Za-z0-9-]{10,}/u],
+    ['a live API key', /\b(?:sk|rk)_live_[A-Za-z0-9]{16,}/u],
 ];
 const SECRET_NAME = /(?:SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE|CREDENTIAL|API_?KEY|ACCESS_?KEY)/iu;
 const SECRET_FILE = /(?:^|\/)(?:\.env(?!\.(?:example|sample|template)$)[^/]*|secrets?\.env|id_(?:rsa|dsa|ecdsa|ed25519)|[^/]+\.(?:pem|key|p12|pfx|jks|enc)|\.npmrc|\.netrc|\.git-credentials|\.sops\.yaml|keys\.txt)$/u;
@@ -29,124 +28,138 @@ const MAX_TEXT_BYTES = 128 * 1024;
 const BLOCK = 512;
 const BUILD_ARG_PREFIX = /^\|\d+ ((?:[A-Za-z_][A-Za-z0-9_]*=\S*\s?)+)/u;
 const ARG_INSTRUCTION = /\bARG\s+([A-Za-z_][A-Za-z0-9_]*)/gu;
-
 const cleanName = (name) => name.replace(/^\.?\//u, '').replace(/\/$/u, '');
 const secretPatternIn = (text) => SECRET_PATTERNS.find(([, pattern]) => pattern.test(text))?.[0] ?? null;
-
 /** Reads one NUL-terminated field of a tar header. */
 const field = (header, from, length) => header.toString('utf8', from, from + length).replace(/\0.*$/su, '');
-
 function sizeOf(header) {
-  if (header[124] & 0x80) {
-    let value = 0;
-    for (let index = 125; index < 136; index += 1) value = (value * 256) + header[index];
-    return value;
-  }
-  return Number.parseInt(field(header, 124, 12).trim() || '0', 8);
+    if ((header[124] ?? 0) & 0x80) {
+        let value = 0;
+        for (let index = 125; index < 136; index += 1)
+            value = (value * 256) + (header[index] ?? 0);
+        return value;
+    }
+    return Number.parseInt(field(header, 124, 12).trim() || '0', 8);
 }
-
 const paxPath = (body) => body.toString('utf8').split('\n').map((record) => /^\d+ path=(.*)$/u.exec(record)).find(Boolean)?.[1] ?? null;
-
 /**
  * Walks a tar file by header: calls visit({ name, type, size, read }) for every entry (`read()` returns the content, called only for files worth
  * reading). Handles ustar prefixes, GNU long names (L) and PAX paths (x). Content is never loaded unless the visitor asks for it.
  */
 function walkTar(file, visit) {
-  const fd = fs.openSync(file, 'r');
-  try {
-    const header = Buffer.alloc(BLOCK);
-    let position = 0;
-    let pending = null;
-    for (;;) {
-      if (fs.readSync(fd, header, 0, BLOCK, position) < BLOCK || header.every((byte) => byte === 0)) return;
-      const size = sizeOf(header);
-      const type = String.fromCharCode(header[156] || 48);
-      const prefix = field(header, 345, 155);
-      const own = field(header, 0, 100);
-      const contentAt = position + BLOCK;
-      const read = () => { const body = Buffer.alloc(size); fs.readSync(fd, body, 0, size, contentAt); return body; };
-      if (type === 'L' || type === 'x') {
-        const body = read();
-        pending = type === 'L' ? body.toString('utf8').replace(/\0.*$/su, '') : paxPath(body) ?? pending;
-      } else {
-        visit({ name: cleanName(pending ?? (prefix ? `${prefix}/${own}` : own)), type, size, read });
-        pending = null;
-      }
-      position = contentAt + (Math.ceil(size / BLOCK) * BLOCK);
+    const fd = fs.openSync(file, 'r');
+    try {
+        const header = Buffer.alloc(BLOCK);
+        let position = 0;
+        let pending = null;
+        for (;;) {
+            if (fs.readSync(fd, header, 0, BLOCK, position) < BLOCK || header.every((byte) => byte === 0))
+                return;
+            const size = sizeOf(header);
+            const type = String.fromCharCode(header[156] || 48);
+            const prefix = field(header, 345, 155);
+            const own = field(header, 0, 100);
+            const contentAt = position + BLOCK;
+            const read = () => { const body = Buffer.alloc(size); fs.readSync(fd, body, 0, size, contentAt); return body; };
+            if (type === 'L' || type === 'x') {
+                const body = read();
+                pending = type === 'L' ? body.toString('utf8').replace(/\0.*$/su, '') : paxPath(body) ?? pending;
+            }
+            else {
+                visit({ name: cleanName(pending ?? (prefix ? `${prefix}/${own}` : own)), type, size, read });
+                pending = null;
+            }
+            position = contentAt + (Math.ceil(size / BLOCK) * BLOCK);
+        }
+    }
+    finally {
+        fs.closeSync(fd);
     }
-  } finally {
-    fs.closeSync(fd);
-  }
 }
-
 function historyHits(historyText, allowedArgs) {
-  const hits = [];
-  splitLines(historyText).forEach((line, index) => {
-    const found = secretPatternIn(line);
-    if (found) hits.push({ kind: 'history', where: `history line ${index + 1}`, why: found });
-    const names = [...(BUILD_ARG_PREFIX.exec(line)?.[1].trim().split(/\s+/u).map((pair) => pair.split('=')[0]) ?? []), ...[...line.matchAll(ARG_INSTRUCTION)].map((match) => match[1])];
-    for (const name of new Set(names)) if (!allowedArgs.has(name)) hits.push({ kind: 'build-arg', where: `history line ${index + 1}`, why: `build argument ${name} is not on the public build-args list` });
-  });
-  return hits;
+    const hits = [];
+    splitLines(historyText).forEach((line, index) => {
+        const found = secretPatternIn(line);
+        if (found)
+            hits.push({ kind: 'history', where: `history line ${index + 1}`, why: found });
+        const names = [...(BUILD_ARG_PREFIX.exec(line)?.[1]?.trim().split(/\s+/u).map((pair) => pair.split('=')[0]) ?? []), ...[...line.matchAll(ARG_INSTRUCTION)].map((match) => match[1])];
+        for (const name of new Set(names))
+            if (!allowedArgs.has(name))
+                hits.push({ kind: 'build-arg', where: `history line ${index + 1}`, why: `build argument ${name} is not on the public build-args list` });
+    });
+    return hits;
 }
-
 function environmentHits(envJson) {
-  let values = [];
-  try { values = JSON.parse(envJson); } catch { values = []; }
-  return (Array.isArray(values) ? values : []).flatMap((entry) => {
-    const at = String(entry).indexOf('=');
-    const name = String(entry).slice(0, at);
-    const value = String(entry).slice(at + 1);
-    const found = secretPatternIn(value);
-    if (found) return [{ kind: 'env', where: `environment variable ${name}`, why: found }];
-    return SECRET_NAME.test(name) && value !== '' ? [{ kind: 'env', where: `environment variable ${name}`, why: 'a variable named like a secret holds a value' }] : [];
-  });
+    let values = [];
+    try {
+        values = JSON.parse(envJson);
+    }
+    catch {
+        values = [];
+    }
+    return (Array.isArray(values) ? values : []).flatMap((entry) => {
+        const at = String(entry).indexOf('=');
+        const name = String(entry).slice(0, at);
+        const value = String(entry).slice(at + 1);
+        const found = secretPatternIn(value);
+        if (found)
+            return [{ kind: 'env', where: `environment variable ${name}`, why: found }];
+        return SECRET_NAME.test(name) && value !== '' ? [{ kind: 'env', where: `environment variable ${name}`, why: 'a variable named like a secret holds a value' }] : [];
+    });
 }
-
 function fileHits(tarFile) {
-  const hits = [];
-  walkTar(tarFile, ({ name, type, size, read }) => {
-    if (!['0', '7'].includes(type) || LIBRARY_DIR.test(name)) return;
-    if (SECRET_FILE.test(name)) hits.push({ kind: 'file', where: name, why: 'a file named like secret material' });
-    else if (TEXT_FILE.test(name) && size > 0 && size <= MAX_TEXT_BYTES) {
-      const found = secretPatternIn(read().toString('utf8'));
-      if (found) hits.push({ kind: 'content', where: name, why: found });
-    }
-  });
-  return hits;
+    const hits = [];
+    walkTar(tarFile, ({ name, type, size, read }) => {
+        if (!['0', '7'].includes(type) || LIBRARY_DIR.test(name))
+            return;
+        if (SECRET_FILE.test(name))
+            hits.push({ kind: 'file', where: name, why: 'a file named like secret material' });
+        else if (TEXT_FILE.test(name) && size > 0 && size <= MAX_TEXT_BYTES) {
+            const found = secretPatternIn(read().toString('utf8'));
+            if (found)
+                hits.push({ kind: 'content', where: name, why: found });
+        }
+    });
+    return hits;
 }
-
 /** The filesystem of the image as a tar file (create, export to a file, remove), or an error line. */
 function exportFilesystem(ctx, ref, directory) {
-  const created = tool(ctx, 'docker', ['create', ref]);
-  const id = firstLine(created.stdout);
-  if (created.status !== 0 || id === '') return { error: `docker create failed: ${firstLine(created.stderr)}` };
-  const tarFile = path.join(directory, 'filesystem.tar');
-  const exported = tool(ctx, 'docker', ['export', '-o', tarFile, id]);
-  tool(ctx, 'docker', ['rm', '-f', id]);
-  return exported.status === 0 ? { tarFile } : { error: `docker export failed: ${firstLine(exported.stderr)}` };
+    const created = tool(ctx, 'docker', ['create', ref]);
+    const id = firstLine(created.stdout);
+    if (created.status !== 0 || id === '')
+        return { error: `docker create failed: ${firstLine(created.stderr)}` };
+    const tarFile = path.join(directory, 'filesystem.tar');
+    const exported = tool(ctx, 'docker', ['export', '-o', tarFile, id]);
+    tool(ctx, 'docker', ['rm', '-f', id]);
+    return exported.status === 0 ? { tarFile } : { error: `docker export failed: ${firstLine(exported.stderr)}` };
 }
-
 /**
  * Scans a built image. `allowedArgs` = the names of the public build arguments that were passed. Returns { ok, hits, errors }:
  * errors are scan steps that could not run (the push is refused too: an unscanned public image is not pushed).
  */
 export function scanImage(ctx, ref, { allowedArgs }) {
-  const hits = [];
-  const errors = [];
-  const history = tool(ctx, 'docker', ['history', '--no-trunc', '--format', '{{.CreatedBy}}', ref]);
-  if (history.status === 0) hits.push(...historyHits(history.stdout, new Set(allowedArgs)));
-  else errors.push(`docker history failed: ${firstLine(history.stderr)}`);
-  const environment = tool(ctx, 'docker', ['inspect', '--format', '{{json .Config.Env}}', ref]);
-  if (environment.status === 0) hits.push(...environmentHits(environment.stdout));
-  else errors.push(`docker inspect failed: ${firstLine(environment.stderr)}`);
-  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-scan-'));
-  try {
-    const exported = exportFilesystem(ctx, ref, directory);
-    if (exported.error) errors.push(exported.error);
-    else hits.push(...fileHits(exported.tarFile));
-  } finally {
-    fs.rmSync(directory, { recursive: true, force: true });
-  }
-  return { ok: hits.length === 0 && errors.length === 0, hits, errors };
+    const hits = [];
+    const errors = [];
+    const history = tool(ctx, 'docker', ['history', '--no-trunc', '--format', '{{.CreatedBy}}', ref]);
+    if (history.status === 0)
+        hits.push(...historyHits(history.stdout, new Set(allowedArgs)));
+    else
+        errors.push(`docker history failed: ${firstLine(history.stderr)}`);
+    const environment = tool(ctx, 'docker', ['inspect', '--format', '{{json .Config.Env}}', ref]);
+    if (environment.status === 0)
+        hits.push(...environmentHits(environment.stdout));
+    else
+        errors.push(`docker inspect failed: ${firstLine(environment.stderr)}`);
+    const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-scan-'));
+    try {
+        const exported = exportFilesystem(ctx, ref, directory);
+        if (exported.tarFile === undefined)
+            errors.push(exported.error);
+        else
+            hits.push(...fileHits(exported.tarFile));
+    }
+    finally {
+        fs.rmSync(directory, { recursive: true, force: true });
+    }
+    return { ok: hits.length === 0 && errors.length === 0, hits, errors };
 }

package/stack/ingress-create.d.mts

@@ -0,0 +1,4 @@
+import type { IngressConfig } from './config.mjs';
+import type { ActionResult, Runner } from './remote.mjs';
+/** `ingress create`: dry run unless execute. Returns { ok, lines, data }. */
+export declare function createIngress(run: Runner, ingress: IngressConfig, execute: boolean): ActionResult;

package/stack/ingress-create.mjs

@@ -1,114 +1,110 @@
-// ingress-create.mjs - `starci app stack ingress create`: deploys the SHARED ingress as its own swarm stack with ZERO replicas, so the service exists
-// (rehearse and takeover need it) while nothing binds a port and the live edge is untouched. The stack is rendered from the deploy block:
-// the pinned image, the whole legacy dynamic directory bind-mounted read-only, the persisted certificates volume, the attachable overlay (external),
-// host-mode 80/443 (they bind only when a task starts) and no ACME email. The static arguments are the declared `ingress.args` or, byte for byte, the
-// ones the live edge container runs with (read-only inspect), so the new proxy behaves exactly like the old one. It refuses to start a task.
 import { refusal } from './errors.mjs';
 import { remoteDocker, shellQuote } from './remote.mjs';
-
 const ACME_EMAIL = /acme\.email=(.+)$/iu;
 const SERVICE_NETWORK = 'edge';
-
-const parse = (text) => { try { return JSON.parse(text); } catch { return null; } };
+const parse = (text) => { try {
+    return JSON.parse(text);
+}
+catch {
+    return null;
+} };
 const asArray = (value) => (Array.isArray(value) ? value : []);
-
 /** The static arguments and the two mount targets of the live edge container (inspect formats read Args and Mounts only, never the environment). */
 function readLegacy(run, ingress) {
-  const container = ingress.legacy.container;
-  const args = parse(remoteDocker(run, ['inspect', '--format', '{{json .Args}}', container]).stdout);
-  const mounts = asArray(parse(remoteDocker(run, ['inspect', '--format', '{{json .Mounts}}', container]).stdout));
-  const target = (match) => mounts.find(match)?.Destination;
-  return {
-    args: ingress.args ?? asArray(args).filter((arg) => typeof arg === 'string'),
-    dynamicTarget: target((mount) => mount.Source === ingress.legacy.dynamicDir),
-    acmeTarget: target((mount) => mount.Name === ingress.acmeVolume),
-  };
+    const container = ingress.legacy.container;
+    const args = parse(remoteDocker(run, ['inspect', '--format', '{{json .Args}}', container]).stdout);
+    const mounts = asArray(parse(remoteDocker(run, ['inspect', '--format', '{{json .Mounts}}', container]).stdout)); // docker inspect output
+    const target = (match) => mounts.find(match)?.Destination;
+    return {
+        args: ingress.args ?? asArray(args).filter((arg) => typeof arg === 'string'),
+        dynamicTarget: target((mount) => mount.Source === ingress.legacy.dynamicDir),
+        acmeTarget: target((mount) => mount.Name === ingress.acmeVolume),
+    };
 }
-
 /** The stack model (compose spec as JSON, which is valid YAML). */
 function stackModel(ingress, { args, dynamicTarget, acmeTarget }) {
-  const ports = [80, 443].map((port) => ({ target: port, published: port, protocol: 'tcp', mode: 'host' }));
-  return {
-    services: {
-      [ingress.service]: {
-        image: ingress.image,
-        command: args,
-        ports,
-        volumes: [
-          { type: 'bind', source: ingress.legacy.dynamicDir, target: dynamicTarget, read_only: true },
-          { type: 'volume', source: 'acme', target: acmeTarget },
-        ],
-        networks: [SERVICE_NETWORK],
-        logging: { driver: 'json-file', options: { 'max-size': '10m', 'max-file': '5' } },
-        deploy: {
-          replicas: 0,
-          placement: { constraints: ['node.role == manager'] },
-          update_config: { order: 'stop-first', failure_action: 'rollback' },
-          restart_policy: { condition: 'any' },
+    const ports = [80, 443].map((port) => ({ target: port, published: port, protocol: 'tcp', mode: 'host' }));
+    return {
+        services: {
+            [ingress.service]: {
+                image: ingress.image,
+                command: args,
+                ports,
+                volumes: [
+                    { type: 'bind', source: ingress.legacy.dynamicDir, target: dynamicTarget, read_only: true },
+                    { type: 'volume', source: 'acme', target: acmeTarget },
+                ],
+                networks: [SERVICE_NETWORK],
+                logging: { driver: 'json-file', options: { 'max-size': '10m', 'max-file': '5' } },
+                deploy: {
+                    replicas: 0,
+                    placement: { constraints: ['node.role == manager'] },
+                    update_config: { order: 'stop-first', failure_action: 'rollback' },
+                    restart_policy: { condition: 'any' },
+                },
+            },
         },
-      },
-    },
-    networks: { [SERVICE_NETWORK]: { external: true, name: ingress.network } },
-    volumes: { acme: { external: true, name: ingress.acmeVolume } },
-  };
+        networks: { [SERVICE_NETWORK]: { external: true, name: ingress.network } },
+        volumes: { acme: { external: true, name: ingress.acmeVolume } },
+    };
 }
-
 /** The guard that no task can start from this model. */
 function refuseRunning(model) {
-  for (const [name, service] of Object.entries(model.services)) {
-    if (service.deploy?.replicas !== 0) throw refusal('STACK_INGRESS_WOULD_START', `the ingress service ${name} would start a task; create deploys it with replicas 0 only`);
-  }
+    for (const [name, service] of Object.entries(model.services)) {
+        if (service.deploy?.replicas !== 0)
+            throw refusal('STACK_INGRESS_WOULD_START', `the ingress service ${name} would start a task; create deploys it with replicas 0 only`);
+    }
 }
-
 function emailProblem(args) {
-  const configured = args.map((arg) => ACME_EMAIL.exec(arg)).find((match) => match !== null);
-  return configured ? 'the arguments set an ACME email; a new email registers a new ACME account: leave it unset at takeover' : null;
+    const configured = args.map((arg) => ACME_EMAIL.exec(arg)).find((match) => match !== null);
+    return configured ? 'the arguments set an ACME email; a new email registers a new ACME account: leave it unset at takeover' : null;
 }
-
 const swarmActive = (run) => remoteDocker(run, ['info', '--format', '{{.Swarm.LocalNodeState}} {{.Swarm.ControlAvailable}}']).stdout.trim() === 'active true';
 const overlayAttachable = (run, network) => remoteDocker(run, ['network', 'inspect', '--format', '{{.Driver}} {{.Attachable}}', network]).stdout.trim() === 'overlay true';
 const volumePresent = (run, volume) => remoteDocker(run, ['volume', 'inspect', volume]).status === 0;
-
 /** Replica state of the service: { exists, desired }. */
 function serviceState(run, name) {
-  const listed = remoteDocker(run, ['service', 'ls', '--filter', `name=${name}`, '--format', '{{.Name}} {{.Replicas}}']);
-  const row = String(listed.stdout).split('\n').map((line) => line.trim().split(' ')).find(([found]) => found === name);
-  if (listed.status !== 0 || !row) return { exists: false, desired: 0 };
-  return { exists: true, desired: Number(String(row[1]).split('/')[1]) };
+    const listed = remoteDocker(run, ['service', 'ls', '--filter', `name=${name}`, '--format', '{{.Name}} {{.Replicas}}']);
+    const row = String(listed.stdout).split('\n').map((line) => line.trim().split(' ')).find(([found]) => found === name);
+    if (listed.status !== 0 || !row)
+        return { exists: false, desired: 0 };
+    return { exists: true, desired: Number(String(row[1]).split('/')[1]) };
 }
-
 function checks(run, ingress, legacy, service) {
-  const directory = run(`test -d ${shellQuote(ingress.legacy.dynamicDir)}`).status === 0;
-  return [
-    ['an image is declared (deploy.ingress.image, pinned by digest)', typeof ingress.image === 'string', 'declare deploy.ingress.image'],
-    ['static arguments known (declared, or read from the live edge)', legacy.args.length > 0, `cannot read the arguments of ${ingress.legacy.container}`],
-    ['no ACME email configured', emailProblem(legacy.args) === null, emailProblem(legacy.args)],
-    ['dynamic directory and certificates mounts found on the live edge', typeof legacy.dynamicTarget === 'string' && typeof legacy.acmeTarget === 'string', 'the live edge container does not mount the dynamic directory and the certificates volume'],
-    ['swarm active (manager)', swarmActive(run), 'this host is not an active swarm manager'],
-    [`network ${ingress.network} is an attachable overlay`, overlayAttachable(run, ingress.network), 'run "starci app stack ingress attach --execute" first'],
-    [`certificates volume ${ingress.acmeVolume} present`, volumePresent(run, ingress.acmeVolume), 'the persisted certificates volume is missing'],
-    [`dynamic directory ${ingress.legacy.dynamicDir} present`, directory, 'the dynamic directory is missing'],
-    [`service ${ingress.name}_${ingress.service} is not running a task`, service.desired === 0, `it already runs ${service.desired} replica(s): use takeover or scale it by hand`],
-  ].map(([name, ok, detail]) => ({ name, ok, detail }));
+    const directory = run(`test -d ${shellQuote(ingress.legacy.dynamicDir)}`).status === 0;
+    const rows = [
+        ['an image is declared (deploy.ingress.image, pinned by digest)', typeof ingress.image === 'string', 'declare deploy.ingress.image'],
+        ['static arguments known (declared, or read from the live edge)', legacy.args.length > 0, `cannot read the arguments of ${ingress.legacy.container}`],
+        ['no ACME email configured', emailProblem(legacy.args) === null, emailProblem(legacy.args)],
+        ['dynamic directory and certificates mounts found on the live edge', typeof legacy.dynamicTarget === 'string' && typeof legacy.acmeTarget === 'string', 'the live edge container does not mount the dynamic directory and the certificates volume'],
+        ['swarm active (manager)', swarmActive(run), 'this host is not an active swarm manager'],
+        [`network ${ingress.network} is an attachable overlay`, overlayAttachable(run, ingress.network), 'run "starci app stack ingress attach --env <env> --execute" first'],
+        [`certificates volume ${ingress.acmeVolume} present`, volumePresent(run, ingress.acmeVolume), 'the persisted certificates volume is missing'],
+        [`dynamic directory ${ingress.legacy.dynamicDir} present`, directory, 'the dynamic directory is missing'],
+        [`service ${ingress.name}_${ingress.service} is not running a task`, service.desired === 0, `it already runs ${service.desired} replica(s): use takeover or scale it by hand`],
+    ];
+    return rows.map(([name, ok, detail]) => ({ name, ok, detail }));
 }
-
 /** `ingress create`: dry run unless execute. Returns { ok, lines, data }. */
 export function createIngress(run, ingress, execute) {
-  const legacy = readLegacy(run, ingress);
-  const stack = `${ingress.name}_${ingress.service}`;
-  const results = checks(run, ingress, legacy, serviceState(run, stack));
-  const lines = results.map((item) => (item.ok ? `precondition ok: ${item.name}` : `precondition FAILED: ${item.name} (${item.detail})`));
-  if (results.some((item) => !item.ok)) return { ok: false, lines: [...lines, 'create refused: nothing was changed'], data: { steps: [] } };
-  const model = stackModel(ingress, legacy);
-  refuseRunning(model);
-  const summary = `stack ${ingress.name}: service ${ingress.service} image ${ingress.image}, ${legacy.args.length} static argument(s), host-mode 80/443, replicas 0`;
-  if (!execute) return { ok: true, lines: [...lines, `dry run: would deploy ${summary}`], data: { steps: [] } };
-  const deployed = run(['docker', ...['stack', 'deploy', '--detach=true', '-c', '-', ingress.name].map(shellQuote)].join(' '), { input: JSON.stringify(model) });
-  if (deployed.status !== 0) return { ok: false, lines: [...lines, `docker stack deploy failed: ${String(deployed.stderr).trim().split('\n')[0]}`], data: { steps: [{ step: 'deploy', ok: false }] } };
-  const tasks = remoteDocker(run, ['service', 'ps', stack, '--filter', 'desired-state=running', '-q']).stdout.trim();
-  if (tasks !== '') {
-    remoteDocker(run, ['service', 'scale', `${stack}=0`]);
-    return { ok: false, lines: [...lines, 'REFUSED: a task of the ingress service started; it was scaled back to 0'], data: { steps: [{ step: 'deploy', ok: true }, { step: 'no-task', ok: false }] } };
-  }
-  return { ok: true, lines: [...lines, `deployed ${summary}; no task runs and no port is bound`], data: { steps: [{ step: 'deploy', ok: true }, { step: 'no-task', ok: true }] } };
+    const legacy = readLegacy(run, ingress);
+    const stack = `${ingress.name}_${ingress.service}`;
+    const results = checks(run, ingress, legacy, serviceState(run, stack));
+    const lines = results.map((item) => (item.ok ? `precondition ok: ${item.name}` : `precondition FAILED: ${item.name} (${item.detail})`));
+    if (results.some((item) => !item.ok))
+        return { ok: false, lines: [...lines, 'create refused: nothing was changed'], data: { steps: [] } };
+    const model = stackModel(ingress, legacy);
+    refuseRunning(model);
+    const summary = `stack ${ingress.name}: service ${ingress.service} image ${ingress.image}, ${legacy.args.length} static argument(s), host-mode 80/443, replicas 0`;
+    if (!execute)
+        return { ok: true, lines: [...lines, `dry run: would deploy ${summary}`], data: { steps: [] } };
+    const deployed = run(['docker', ...['stack', 'deploy', '--detach=true', '-c', '-', ingress.name].map(shellQuote)].join(' '), { input: JSON.stringify(model) });
+    if (deployed.status !== 0)
+        return { ok: false, lines: [...lines, `docker stack deploy failed: ${String(deployed.stderr).trim().split('\n')[0]}`], data: { steps: [{ step: 'deploy', ok: false }] } };
+    const tasks = remoteDocker(run, ['service', 'ps', stack, '--filter', 'desired-state=running', '-q']).stdout.trim();
+    if (tasks !== '') {
+        remoteDocker(run, ['service', 'scale', `${stack}=0`]);
+        return { ok: false, lines: [...lines, 'REFUSED: a task of the ingress service started; it was scaled back to 0'], data: { steps: [{ step: 'deploy', ok: true }, { step: 'no-task', ok: false }] } };
+    }
+    return { ok: true, lines: [...lines, `deployed ${summary}; no task runs and no port is bound`], data: { steps: [{ step: 'deploy', ok: true }, { step: 'no-task', ok: true }] } };
 }

package/stack/ingress-publish.d.mts

@@ -0,0 +1,6 @@
+import type { DeployConfig, IngressConfig } from './config.mjs';
+import type { StackContext } from './context.mjs';
+import type { PublishKit } from './ingress.mjs';
+import type { ActionResult, Runner } from './remote.mjs';
+/** `ingress publish`: see the top of the file. `kit` carries the shared probe helpers of ingress.mjs. */
+export declare function publishIngress(ctx: StackContext, run: Runner, config: DeployConfig, ingress: IngressConfig, execute: boolean, kit: PublishKit): Promise<ActionResult>;