@starci/hfs 4.3.0 → 4.4.0

package/stack/deploy.mjs

@@ -0,0 +1,301 @@
+// deploy.mjs - the whole release (deployRelease) and the redeploy of a stored release (rollbackRelease).
+// deploy: render, provision, store the release record, pre-pull, `docker stack deploy`, converge, verify, accept, prune. A failure at or
+// after the stack deploy redeploys the previous accepted release from its STORED bytes; a failure before it leaves the services untouched.
+// Without `execute` a deploy renders locally and prints the plan: NO remote call at all. A rollback cannot undo data effects.
+//
+// `deps` are the collaborators, all factories or functions with the signature of their module, defaulting to lazy dynamic imports so this
+// module never needs render.mjs / provision.mjs / remote.mjs at load time (the specs inject stubs):
+//   renderRelease, provisionRelease, convergeStack, verifyStack, pruneStack     (ctx, config, options) -> { ok, lines, data }
+//   releaseStore  (config, ssh) -> store          ssh  (ctx, config, { sshCmd }) -> runner(command, { input })
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { findInOrder } from '../runtime/scripts/lib/in-order.mjs';
+import { convergeStack } from './converge.mjs';
+import { describeClash, edgeCollisions, reconcileEdgeAliases } from './edge-alias.mjs';
+import { firstLine, tool } from './context.mjs';
+import { hasPlaceholderDigest, isReleaseId } from './digest.mjs';
+import { failure, refusal } from './errors.mjs';
+import { pruneStack } from './prune.mjs';
+import { parseYaml } from '../runtime/engine/yaml.mjs';
+import { createReleaseStore } from './release-store.mjs';
+import { verifyStack } from './verify.mjs';
+
+/** Loads `file` (relative to this module). Split out so a spec can load a real sibling module through `lazy`. */
+export const importModule = (file) => import(file);
+
+/** A function that imports `file` on first call and forwards its arguments to the export `name`. */
+export const lazy = (file, name) => async (...args) => (await importModule(file))[name](...args);
+
+export const DEFAULT_DEPS = Object.freeze({
+  renderRelease: lazy('./render.mjs', 'renderRelease'),
+  provisionRelease: lazy('./provision.mjs', 'provisionRelease'),
+  convergeStack,
+  reconcileEdge: reconcileEdgeAliases,
+  verifyStack,
+  pruneStack,
+  releaseStore: createReleaseStore,
+  ssh: lazy('./remote.mjs', 'ownerSshRunner'),
+});
+
+const IMAGE_LINE = /^[ \t]+image:[ \t]*(\S+)[ \t]*$/gmu;
+const QUOTE = /^["']|["']$/gu;
+const IMAGE_REF = /^[A-Za-z0-9][A-Za-z0-9./_:@-]*$/u;
+
+/** Every network alias the services of a rendered stack claim: [{ service, alias }]. */
+function stackAliases(bytes) {
+  const services = parseYaml(bytes)?.services ?? {};
+  return Object.entries(services).flatMap(([service, entry]) => Object.values(entry?.networks ?? {}).flatMap((network) => (network?.aliases ?? []).map((alias) => ({ service, alias }))));
+}
+
+/**
+ * A swarm service must never claim an alias that a live (compose) upstream of the declared ingress still answers to: on the shared overlay both would
+ * share the name and the old route would round-robin into the new service BEFORE the routes are published. Refused before anything is changed.
+ */
+function refuseSharedAliases(config, bytes) {
+  const live = new Map((config.ingress?.upstreams ?? []).filter((upstream) => upstream.container !== null).flatMap((upstream) => upstream.aliases.map((alias) => [alias, upstream.name])));
+  const clash = stackAliases(bytes).find(({ alias }) => live.has(alias));
+  if (clash) throw refusal('STACK_DEPLOY_ALIAS_SHARED', `service ${clash.service} claims the network alias ${clash.alias}, which the live upstream ${live.get(clash.alias)} of deploy.ingress.upstreams still answers to: give the swarm service its own alias (for example ${clash.alias}-swarm) and point the published routes at it; nothing was changed`);
+}
+
+/**
+ * Read-only preflight on the live edge networks: the implicit short name of a service (`api` for shop_api) must not equal a name another container or
+ * service of the same external network resolves (docker stack deploy adds it as an alias, and the other tenant's `http://api` would reach this stack).
+ */
+async function refuseEdgeCollisions(run, config, bytes) {
+  const { clashes } = await edgeCollisions(run, config, bytes);
+  if (clashes.length > 0) throw refusal('STACK_DEPLOY_ALIAS_SHARED', describeClash(clashes[0]));
+}
+
+/** The release id (first 16 hex of the sha256 of the rendered stack bytes) and the distinct images of a rendered release. */
+function inspectRendered(out, config) {
+  const bytes = fs.readFileSync(path.join(out, 'stack.yaml'), 'utf8');
+  refuseSharedAliases(config, bytes);
+  if (hasPlaceholderDigest(bytes)) throw refusal('STACK_DEPLOY_PLACEHOLDER', 'the rendered stack still carries a placeholder digest; nothing was changed');
+  const images = [...new Set([...bytes.matchAll(IMAGE_LINE)].map((match) => match[1].replaceAll(QUOTE, '')))];
+  const unsafe = images.find((image) => !IMAGE_REF.test(image));
+  if (unsafe) throw refusal('STACK_DEPLOY_IMAGE', `the rendered stack names an image that is not a plain reference (${unsafe}); nothing was changed`);
+  return { releaseId: createHash('sha256').update(bytes).digest('hex').slice(0, 16), images, bytes };
+}
+
+function renderOptions(options, out, previous) {
+  return { images: options.images ?? {}, sourceSha: options.sourceSha, previous, out, allowUnpinned: false, extraCompose: [] };
+}
+
+/** A step that returns { ok, lines } whatever happens: an exception becomes a failed step (used once the services may have changed). */
+async function attempt(action) {
+  try {
+    return await action();
+  } catch (error) {
+    return { ok: false, lines: [String(error.message)] };
+  }
+}
+
+/** `docker stack deploy` of a stored or rendered file. */
+function stackDeploy(ctx, config, file) {
+  const run = tool(ctx, 'docker', ['stack', 'deploy', '--prune', '--with-registry-auth', '--resolve-image', 'always', '--detach=true', '-c', file, config.stack]);
+  if (run.status !== 0) return { ok: false, lines: [`docker stack deploy failed: ${firstLine(run.stderr)}`] };
+  return { ok: true, lines: [`deploy: requested ${config.stack} from ${path.basename(path.dirname(file))}/${path.basename(file)}`] };
+}
+
+/** Runs [name, action] steps in order until one fails; records { step, ok } and collects the lines. Returns the failed step name or ''. */
+async function runSteps(plan, lines, steps) {
+  const failed = await findInOrder(plan, async ([step, action]) => {
+    const result = await attempt(action);
+    lines.push(...result.lines);
+    steps.push({ step, ok: result.ok });
+    return !result.ok;
+  });
+  return failed ? failed[0] : '';
+}
+
+const isoBefore = (ctx, seconds) => new Date(ctx.now() - seconds * 1000).toISOString();
+
+/** Opens the release store over the ssh runner of this invocation; the runner's cleanup is queued on `cleanups` (sealed session files). */
+async function openRunner(ctx, config, options, d, cleanups) {
+  const run = await d.ssh(ctx, config, { sshCmd: options.sshCmd ?? null });
+  cleanups.push(() => run.cleanup?.());
+  return run;
+}
+
+const openStore = async (ctx, config, options, d, cleanups) => d.releaseStore(config, await openRunner(ctx, config, options, d, cleanups));
+
+/** Redeploys a stored release after a failed deploy: fetch, stack deploy, converge. Returns the lines to print. */
+async function redeployStored(ctx, config, d, store, previous, out, steps) {
+  const dir = path.join(out, 'previous');
+  const lines = [`ROLLING BACK to the previous accepted release ${previous}`];
+  const failed = await runSteps([
+    ['rollback-fetch', async () => { await store.fetch(previous, dir); return { ok: true, lines: [] }; }],
+    ['rollback-deploy', () => stackDeploy(ctx, config, path.join(dir, 'stack.yaml'))],
+    ['rollback-edge', async () => d.reconcileEdge(ctx, config, path.join(dir, 'stack.yaml'))],
+    ['rollback-converge', () => d.convergeStack(ctx, config, { since: isoBefore(ctx, 30), timeoutSeconds: 600 })],
+  ], lines, steps);
+  lines.push(failed ? 'ROLLBACK DID NOT CONVERGE: follow the stack runbook, Rollback' : `rolled back to ${previous}`);
+  return { lines, ok: !failed };
+}
+
+/** After the accept: prune with both release records (non-fatal) and drop dangling images (failure ignored). */
+async function housekeeping(ctx, config, d, store, { previous, out }, lines) {
+  const outcome = await attempt(async () => {
+    const keepFiles = [path.join(out, 'release.json')];
+    if (previous) {
+      await store.fetch(previous, path.join(out, 'previous'));
+      keepFiles.push(path.join(out, 'previous', 'release.json'));
+    }
+    return d.pruneStack(ctx, config, { keepFiles, execute: true });
+  });
+  lines.push(...outcome.lines);
+  if (!outcome.ok) lines.push('prune failed (non-fatal; superseded objects stay until the next release)');
+  tool(ctx, 'docker', ['image', 'prune', '-f']);
+}
+
+function prePull(ctx, images) {
+  const lines = [];
+  for (const image of images) {
+    const run = tool(ctx, 'docker', ['pull', '--quiet', image]);
+    if (run.status !== 0) throw failure('STACK_DEPLOY_PULL', `docker pull ${image} failed: ${firstLine(run.stderr)}`);
+    lines.push(`pulled ${image}`);
+  }
+  return lines;
+}
+
+/** Everything before the stack deploy: any failure here leaves the services untouched. Returns { ok, lines, releaseId, images, previous }. */
+async function prepareRelease(ctx, config, options, d, out, cleanups) {
+  const run = await openRunner(ctx, config, options, d, cleanups);
+  const store = d.releaseStore(config, run);
+  const previous = await store.current();
+  const rendered = await d.renderRelease(ctx, config, renderOptions(options, out, previous || null));
+  const { releaseId, images, bytes } = inspectRendered(out, config);
+  await refuseEdgeCollisions(run, config, bytes);
+  const lines = [...(rendered.lines ?? [])];
+  const provisioned = await d.provisionRelease(ctx, config, { execute: true, out, releaseFile: path.join(out, 'release.json') });
+  lines.push(...(provisioned.lines ?? []));
+  if (provisioned.ok === false) return { ok: false, lines, releaseId, previous, store, stepsDone: [{ step: 'render', ok: true }, { step: 'provision', ok: false }] };
+  await store.store(out, releaseId);
+  lines.push(...prePull(ctx, images));
+  return { ok: true, lines, releaseId, previous, store, stepsDone: [{ step: 'render', ok: true }, { step: 'provision', ok: true }, { step: 'store', ok: true }, { step: 'pre-pull', ok: true }] };
+}
+
+async function deployExecute(ctx, config, options, d, out, cleanups) {
+  const prepared = await prepareRelease(ctx, config, options, d, out, cleanups);
+  const { releaseId, previous, store } = prepared;
+  const lines = [...prepared.lines];
+  const steps = [...prepared.stepsDone];
+  const data = { releaseId, previous: previous || null, steps, rolledBack: false };
+  if (!prepared.ok) return { ok: false, lines: [...lines, 'deploy not started; the services are untouched'], data };
+  const since = isoBefore(ctx, 60);
+  const { skipPublic } = options;
+  const failed = await runSteps([
+    ['deploy', () => stackDeploy(ctx, config, path.join(out, 'stack.yaml'))],
+    ['edge', async () => d.reconcileEdge(ctx, config, path.join(out, 'stack.yaml'))],
+    ['converge', () => d.convergeStack(ctx, config, { since, timeoutSeconds: options.timeoutSeconds })],
+    ['verify', () => d.verifyStack(ctx, config, { retrySeconds: options.retrySeconds, skipPublic: skipPublic === true, stackFile: path.join(out, 'stack.yaml') })],
+    ...(skipPublic ? [] : [['accept', async () => { await store.accept(releaseId); return { ok: true, lines: [`accepted release ${releaseId}`] }; }]]),
+  ], lines, steps);
+  if (!failed && skipPublic) {
+    data.pendingAccept = true;
+    return { ok: true, lines: [...lines, `deployed release ${releaseId}: converged and verified inside the stack; the public hosts were NOT checked and the release is NOT accepted yet`, `next: starci app stack ingress publish, then starci app stack accept --release ${releaseId} --execute`], data };
+  }
+  if (!failed) {
+    await housekeeping(ctx, config, d, store, { previous, out }, lines);
+    return { ok: true, lines: [...lines, `deployed release ${releaseId}`], data };
+  }
+  lines.push(`deploy failed at ${failed}`);
+  if (!previous) return { ok: false, lines: [...lines, 'no previous accepted release; services were rolled back by update_config where they had a previous spec'], data };
+  const back = await redeployStored(ctx, config, d, store, previous, out, steps);
+  data.rolledBack = back.ok;
+  return { ok: false, lines: [...lines, ...back.lines], data };
+}
+
+/**
+ * Deploys a release: `options` = { images, sourceSha, execute, out, timeoutSeconds, retrySeconds, skipPublic, sshCmd }.
+ * skipPublic (the first deploy into a shared ingress, whose public routes exist only after `ingress publish`): the verification checks only what runs
+ * inside the stack, and the release stays PENDING (stored and deployed, pointer not moved) until `acceptRelease` has verified it in full.
+ * Returns { ok, lines, data: { releaseId, previous, steps: [{ step, ok }], rolledBack } }.
+ */
+export async function deployRelease(ctx, config, options = {}, deps = {}) {
+  const d = { ...DEFAULT_DEPS, ...deps };
+  if (!options.sourceSha) throw refusal('STACK_DEPLOY_SOURCE_SHA', '--source-sha is required (the git commit being deployed)');
+  const made = options.out ? null : fs.mkdtempSync(path.join(os.tmpdir(), 'stack-release-'));
+  const out = options.out ?? made;
+  const cleanups = [];
+  try {
+    const rendered = await d.renderRelease(ctx, config, renderOptions(options, out, null));
+    const { releaseId } = inspectRendered(out, config);
+    if (options.execute !== true) {
+      const plan = options.skipPublic
+        ? `dry run: release ${releaseId} would be provisioned, stored, pre-pulled, deployed, converged and verified inside the stack (public hosts skipped); it would stay pending until ingress publish and stack accept`
+        : `dry run: release ${releaseId} would be provisioned, stored, pre-pulled, deployed, converged, verified, accepted`;
+      return { ok: true, lines: [...(rendered.lines ?? []), plan], data: { releaseId, steps: [{ step: 'render', ok: true }], executed: false } };
+    }
+    return await deployExecute(ctx, config, options, d, out, cleanups);
+  } finally {
+    cleanups.forEach((close) => close());
+    if (made) fs.rmSync(made, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Redeploys a stored release (default: the `previous` pointer): `options` = { release, execute, timeoutSeconds, sshCmd }.
+ * `release` is read from `options` only and must be null or 16 lowercase hex.
+ */
+export async function rollbackRelease(ctx, config, options = {}, deps = {}) {
+  const d = { ...DEFAULT_DEPS, ...deps };
+  const release = options.release ?? null;
+  if (release !== null && !isReleaseId(release)) throw refusal('STACK_RELEASE_ID', 'the release must be 16 lowercase hex characters');
+  const cleanups = [];
+  const store = await openStore(ctx, config, options, d, cleanups);
+  let dir = null;
+  try {
+    const target = release ?? await store.previous();
+    if (!target) throw refusal('STACK_ROLLBACK_NO_TARGET', 'no previous accepted release is recorded; name one with --release');
+    if (options.execute !== true) return { ok: true, lines: [`dry run: would redeploy release ${target}`], data: { release: target, executed: false } };
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-rollback-'));
+    const lines = [];
+    const steps = [];
+    const since = isoBefore(ctx, 30);
+    const failed = await runSteps([
+      ['fetch', async () => { await store.fetch(target, dir); return { ok: true, lines: [] }; }],
+      ['deploy', () => stackDeploy(ctx, config, path.join(dir, 'stack.yaml'))],
+      ['edge', async () => d.reconcileEdge(ctx, config, path.join(dir, 'stack.yaml'))],
+      ['converge', () => d.convergeStack(ctx, config, { since, timeoutSeconds: options.timeoutSeconds ?? 600 })],
+      ['verify', () => d.verifyStack(ctx, config, { retrySeconds: 180, stackFile: path.join(dir, 'stack.yaml') })],
+      ['accept', async () => { await store.accept(target); return { ok: true, lines: [] }; }],
+    ], lines, steps);
+    lines.push(failed ? `rollback to ${target} failed at ${failed}` : `rolled back to release ${target}; a rollback cannot undo data effects`);
+    return { ok: !failed, lines, data: { release: target, executed: true, steps } };
+  } finally {
+    if (dir) fs.rmSync(dir, { recursive: true, force: true });
+    cleanups.forEach((close) => close());
+  }
+}
+
+/**
+ * Accepts a release that a `skipPublic` deploy left pending: the FULL verification (public hosts and checks inside the stack) must pass first, then the
+ * pointer moves and the superseded secrets and configs are pruned. `options` = { release, execute, retrySeconds, sshCmd }.
+ */
+export async function acceptRelease(ctx, config, options = {}, deps = {}) {
+  const d = { ...DEFAULT_DEPS, ...deps };
+  const release = options.release ?? null;
+  if (!isReleaseId(release)) throw refusal('STACK_RELEASE_ID', 'accept needs --release <16 lowercase hex characters> (the id the deploy printed)');
+  const cleanups = [];
+  const store = await openStore(ctx, config, options, d, cleanups);
+  const out = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-accept-'));
+  try {
+    try { await store.fetch(release, out); } catch { throw refusal('STACK_ACCEPT_UNKNOWN', `release ${release} has no stored record on the manager`); }
+    const previous = await store.current();
+    if (previous === release) return { ok: true, lines: [`release ${release} is already the accepted release`], data: { release, accepted: true, executed: options.execute === true } };
+    if (options.execute !== true) return { ok: true, lines: [`dry run: would run the full verification (public hosts and checks inside the stack) and then accept release ${release}`], data: { release, accepted: false, executed: false } };
+    const verified = await d.verifyStack(ctx, config, { retrySeconds: options.retrySeconds, stackFile: path.join(out, 'stack.yaml') });
+    const lines = [...(verified.lines ?? [])];
+    if (!verified.ok) return { ok: false, lines: [...lines, `release ${release} is NOT accepted: the full verification failed`], data: { release, accepted: false, executed: true } };
+    await store.accept(release);
+    lines.push(`accepted release ${release}`);
+    await housekeeping(ctx, config, d, store, { previous: previous || null, out }, lines);
+    return { ok: true, lines, data: { release, accepted: true, executed: true } };
+  } finally {
+    fs.rmSync(out, { recursive: true, force: true });
+    cleanups.forEach((close) => close());
+  }
+}

package/stack/digest.mjs

@@ -0,0 +1,16 @@
+// digest.mjs - image reference and release identifier guards (the all-zero placeholder digest is never a real image).
+/** A registry image reference pinned by a real sha256 digest; the all-zero placeholder digest is refused. */
+export const DIGEST_REF = /^[a-z0-9./_-]+(?::[A-Za-z0-9._-]+)?@sha256:(?!0{64}$)[0-9a-f]{64}$/u;
+
+/** A release identifier: the first 16 hex characters of the release digest. */
+export const RELEASE_ID = /^[0-9a-f]{16}$/u;
+
+/** Detects an unreplaced image digest in an image reference or in rendered stack bytes. */
+export const hasPlaceholderDigest = (bytes) => /@sha256:0{64}(?![0-9a-f])/u.test(String(bytes));
+
+/** True for a pinned image reference; `allowUnpinned` (a local throwaway swarm) still refuses the placeholder digest. */
+export const isImageReference = (value, allowUnpinned = false) =>
+  typeof value === 'string' && value.length > 0 && !hasPlaceholderDigest(value) && (allowUnpinned || DIGEST_REF.test(value));
+
+/** True for 16 lowercase hex characters. */
+export const isReleaseId = (value) => typeof value === 'string' && RELEASE_ID.test(value);

package/stack/docker-transport.mjs

@@ -0,0 +1,53 @@
+// docker-transport.mjs - lets the verbs that drive the docker CLI (deploy, converge, verify, rollback, prune) reach the manager from an OPERATOR
+// machine. In CI `connect` writes the ssh config and DOCKER_HOST; on an operator machine the key lives in the sealed members, so the docker CLI
+// is run with a private HOME that holds an ssh config for the sealed session and DOCKER_HOST=ssh://<alias>. Only `docker` children that did not get
+// an explicit environment are affected (the minimal environment of `docker stack config` stays exactly as the render built it). The key lives in
+// a private temp directory that is overwritten and removed when the verb ends; it is never in argv, a line or an error.
+import fs from 'node:fs';
+import path from 'node:path';
+import { writePrivate } from './private-file.mjs';
+import { openSealedSession } from './remote.mjs';
+
+const ALIAS = 'stack-vps';
+const forward = (file) => file.replaceAll('\\', '/');
+
+/** True when the operator's docker CLI has to be pointed at the manager by this module. */
+function needed(ctx, config, sshCmd) {
+  if (sshCmd || ctx.env.DOCKER_HOST || ctx.env.GITHUB_ACTIONS === 'true' || ctx.env.STARCI_STACK_SEALED_SSH === '0') return false;
+  const { sealed } = config.remote;
+  if (!sealed) return false;
+  return [sealed.ops, sealed.sshKey, sealed.knownHosts].every((slug) => fs.existsSync(path.join(config.secretsDir, `${slug}.enc`)));
+}
+
+function sshConfig(session) {
+  const at = session.account.lastIndexOf('@');
+  return [
+    `Host ${ALIAS}`, `  HostName ${session.account.slice(at + 1)}`, `  User ${session.account.slice(0, at)}`,
+    `  IdentityFile ${forward(session.keyFile)}`, '  IdentitiesOnly yes', `  UserKnownHostsFile ${forward(session.knownFile)}`,
+    `  StrictHostKeyChecking ${session.strict}`, '  BatchMode yes', '  ConnectTimeout 20', '',
+  ].join('\n');
+}
+
+/** The environment of a docker child: a private HOME with the ssh config, DOCKER_HOST, and the operator's docker config (registry logins) kept. */
+function dockerEnvironment(ctx, session) {
+  const home = path.join(session.dir, 'home');
+  fs.mkdirSync(path.join(home, '.ssh'), { recursive: true });
+  writePrivate(ctx, path.join(home, '.ssh', 'config'), sshConfig(session));
+  const operatorHome = ctx.env.HOME ?? ctx.env.USERPROFILE ?? '';
+  const dockerConfig = ctx.env.DOCKER_CONFIG ?? (operatorHome ? path.join(operatorHome, '.docker') : undefined);
+  return { ...ctx.env, HOME: home, USERPROFILE: home, DOCKER_HOST: `ssh://${ALIAS}`, ...(dockerConfig ? { DOCKER_CONFIG: dockerConfig } : {}) };
+}
+
+/** Runs `body(ctx')` where ctx'.spawn points the docker CLI at the manager when this is an operator machine; otherwise `body(ctx)`. */
+export async function withDockerTransport(ctx, config, { sshCmd = null } = {}, body) {
+  if (!needed(ctx, config, sshCmd)) return body(ctx);
+  const session = openSealedSession(ctx, config);
+  const env = dockerEnvironment(ctx, session);
+  const spawn = (command, args, options = {}) => (command === 'docker' && options.env === undefined ? ctx.spawn(command, args, { ...options, env }) : ctx.spawn(command, args, options));
+  for (const note of session.notes) ctx.stderr(`${note}\n`);
+  try {
+    return await body(Object.create(ctx, { spawn: { value: spawn } }));
+  } finally {
+    session.cleanup();
+  }
+}

package/stack/edge-alias.mjs

@@ -0,0 +1,118 @@
+// edge-alias.mjs - the network aliases of a service on a SHARED EXTERNAL (edge) overlay network.
+// `docker stack deploy` adds the compose service name (`api`) as an implicit alias on EVERY network a service joins, whatever `aliases:` the compose
+// file lists. On a network that other tenants share, `api` then resolves to this stack's service too (the 2026-10-15 incident: tayson-web proxied
+// http://api:3074 and got shop_api for 17 hours). So an edge attachment must carry ONLY its declared aliases:
+//   edgeAttachments       the services of a rendered (or source) stack attached to an external network, with their declared aliases
+//   edgeCollisions        read-only preflight: does a short service name equal a name another container or service of that network resolves?
+//   reconcileEdgeAliases  after `docker stack deploy`: `service update --network-rm <edge>` then `--network-add name=<edge>,alias=<declared>`
+//   verifyEdgeAttachment  the service spec carries exactly the declared aliases (used by `stack verify`)
+// Docker is reached through the same seams as the neighbouring steps: ctx.spawn (the docker transport) for the deploy-time steps, and the ssh runner
+// with shell-quoted arguments for the read-only preflight.
+import fs from 'node:fs';
+import { parseYaml } from '../runtime/engine/yaml.mjs';
+import { toolOutput } from './context.mjs';
+import { refusal } from './errors.mjs';
+import { remoteDocker } from './remote.mjs';
+
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/u;
+const NETWORK_FORMAT = '{{json .}}';
+
+const networkMap = (value) => (Array.isArray(value) ? Object.fromEntries(value.map((name) => [name, null])) : value ?? {});
+const sameSet = (left, right) => [...new Set(left)].sort().join('\n') === [...new Set(right)].sort().join('\n');
+const show = (aliases) => `[${aliases.join(', ')}]`;
+
+/** [{ service, network, aliases }]: every service attached to an `external: true` network of the stack, with the aliases it declares. */
+export function edgeAttachments(bytes) {
+  const model = parseYaml(bytes) ?? {};
+  const external = new Map(Object.entries(model.networks ?? {}).filter(([, definition]) => definition?.external === true).map(([key, definition]) => [key, String(definition.name ?? key)]));
+  return Object.entries(model.services ?? {}).flatMap(([service, entry]) => Object.entries(networkMap(entry?.networks))
+    .filter(([key]) => external.has(key))
+    .map(([key, attachment]) => ({ service, network: external.get(key), aliases: (attachment?.aliases ?? []).map(String) })));
+}
+
+/** The attachments of the stack file `file`. */
+export const edgeAttachmentsOf = (file) => edgeAttachments(fs.readFileSync(file, 'utf8'));
+
+function safe(attachment) {
+  for (const name of [attachment.service, attachment.network, ...attachment.aliases]) {
+    if (!SAFE_NAME.test(name)) throw refusal('STACK_DEPLOY_EDGE_NAME', `the name ${JSON.stringify(name)} (service ${attachment.service}, network ${attachment.network}) is not a plain docker name`);
+  }
+}
+
+function parseJson(text) {
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+/** The names of the containers and services attached to the external network, read-only through the ssh runner (`docker network inspect`). */
+async function networkNames(run, network) {
+  const result = await remoteDocker(run, ['network', 'inspect', network, '--verbose', '--format', NETWORK_FORMAT]);
+  const model = result.status === 0 ? parseJson(result.stdout) : null;
+  if (model === null || typeof model !== 'object') throw refusal('STACK_DEPLOY_EDGE_UNREADABLE', `cannot read the external network ${network} (docker network inspect failed): the edge network must exist before a deploy; nothing was changed`);
+  return [...Object.values(model.Containers ?? {}).map((container) => String(container.Name)), ...Object.keys(model.Services ?? {})];
+}
+
+/**
+ * Read-only: for each external network of `bytes`, which implicit short service names (`api` for shop_api) another container or service of that
+ * network already resolves. Returns { networks, clashes: [{ service, alias, network, holder }] }; throws STACK_DEPLOY_EDGE_UNREADABLE when a
+ * network cannot be inspected. This stack's own services (`<stack>_*`) are not "others".
+ */
+export async function edgeCollisions(run, config, bytes) {
+  const attachments = edgeAttachments(bytes);
+  const networks = [...new Set(attachments.map((item) => item.network))];
+  const taken = await Promise.all(networks.map(async (network) => [network, (await networkNames(run, network)).filter((name) => !name.startsWith(`${config.stack}_`))]));
+  const clashes = taken.flatMap(([network, others]) => attachments
+    .filter((item) => item.network === network && others.includes(item.service))
+    .map((item) => ({ service: `${config.stack}_${item.service}`, alias: item.service, network, holder: item.service })));
+  return { networks, clashes };
+}
+
+/** The refusal text of one clash. */
+export const describeClash = (clash) => `service ${clash.service} would carry the implicit short-name alias ${clash.alias} on the external network ${clash.network}, which ${clash.holder} (another tenant) already resolves: rename the service or the other name; nothing was changed`;
+
+const docker = (ctx, args) => toolOutput(ctx, 'docker', args);
+
+const networkId = (ctx, network) => docker(ctx, ['network', 'inspect', network, '--format', '{{.Id}}']).trim();
+
+/** The edge entry of the service spec ({ Target, Aliases }) or null when the service is not attached. */
+function edgeEntry(ctx, service, id) {
+  const inspect = JSON.parse(docker(ctx, ['service', 'inspect', service, '--format', '{{json .}}']));
+  return (inspect.Spec?.TaskTemplate?.Networks ?? []).find((entry) => entry.Target === id) ?? null;
+}
+
+const aliasesOf = (entry) => (entry === null ? [] : entry.Aliases ?? []);
+
+/**
+ * After `docker stack deploy`: makes the edge attachment of every edge-attached service carry exactly its declared aliases. `docker service update`
+ * ignores a `--network-add` of an attached network, so the attachment is removed first and added again with the declared aliases. Idempotent (an exact
+ * attachment is left alone). Throws STACK_DEPLOY_EDGE_ALIAS when the aliases still differ afterwards. Returns { ok, lines }.
+ */
+export function reconcileEdgeAliases(ctx, config, file) {
+  const lines = [];
+  const ids = new Map();
+  for (const item of edgeAttachmentsOf(file)) {
+    safe(item);
+    const service = `${config.stack}_${item.service}`;
+    if (!ids.has(item.network)) ids.set(item.network, networkId(ctx, item.network));
+    const id = ids.get(item.network);
+    const before = edgeEntry(ctx, service, id);
+    if (before !== null && sameSet(aliasesOf(before), item.aliases)) {
+      lines.push(`edge: ${service} on ${item.network}: aliases ${show(item.aliases)} (already exact)`);
+      continue;
+    }
+    if (before !== null) docker(ctx, ['service', 'update', '--detach=true', '--network-rm', item.network, service]);
+    docker(ctx, ['service', 'update', '--detach=true', '--network-add', ['name=' + item.network, ...item.aliases.map((alias) => `alias=${alias}`)].join(','), service]);
+    const after = aliasesOf(edgeEntry(ctx, service, id));
+    if (!sameSet(after, item.aliases)) throw refusal('STACK_DEPLOY_EDGE_ALIAS', `${service} carries the aliases ${show(after)} on ${item.network} after the reconcile, declared ${show(item.aliases)}`);
+    lines.push(`edge: ${service} on ${item.network}: aliases ${show(aliasesOf(before))} -> ${show(item.aliases)}`);
+  }
+  return { ok: true, lines };
+}
+
+/** `stack verify`: throws when the service is not attached to the edge network or carries any alias other than the declared ones. */
+export function verifyEdgeAttachment(ctx, config, item) {
+  const service = `${config.stack}_${item.service}`;
+  const entry = edgeEntry(ctx, service, networkId(ctx, item.network));
+  if (entry === null) throw new Error(`${service} is not attached to ${item.network}`);
+  if (!sameSet(aliasesOf(entry), item.aliases)) throw new Error(`${service} carries the aliases ${show(aliasesOf(entry))} on ${item.network}, declared ${show(item.aliases)}`);
+  return `aliases ${show(item.aliases)}`;
+}

package/stack/errors.mjs

@@ -0,0 +1,21 @@
+// errors.mjs - the one error type of the stack tooling and its exit codes.
+export const EXIT = Object.freeze({ ok: 0, failed: 1, refused: 2, approval: 3 });
+
+/** A refusal or failure with a stable code; `exit` is the process exit code the CLI maps it to. */
+export class StackError extends Error {
+  constructor(code, message, exit = EXIT.refused) {
+    super(`${code}: ${message}`);
+    this.name = 'StackError';
+    this.code = code;
+    this.exit = exit;
+  }
+}
+
+/** A failed step (a check or an effect did not succeed): exit 1. */
+export const failure = (code, message) => new StackError(code, message, EXIT.failed);
+
+/** A refusal (bad usage, unsafe or unknown input, missing configuration): exit 2. */
+export const refusal = (code, message) => new StackError(code, message, EXIT.refused);
+
+/** The owner has not approved a one-time effect: exit 3. */
+export const approvalMissing = (code, message) => new StackError(code, message, EXIT.approval);