@starci/hfs 4.11.22 → 4.12.2

package/stack/digest.mjs

@@ -1,16 +1,11 @@
 // 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. */
 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));
-
+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.d.mts

@@ -0,0 +1,5 @@
+import type { DeployConfig } from './config.mjs';
+import type { StackContext } from './context.mjs';
+import type { SshOptions } from './remote.mjs';
+/** Runs `body(ctx')` where ctx'.spawn points the docker CLI at the manager when this is an operator machine; otherwise `body(ctx)`. */
+export declare function withDockerTransport<T>(ctx: StackContext, config: DeployConfig, { sshCmd }: SshOptions | undefined, body: (ctx: StackContext) => T | Promise<T>): Promise<T>;

package/stack/docker-transport.mjs

@@ -10,125 +10,133 @@ import { writePrivate } from './private-file.mjs';
 import { openSealedSession } from './remote.mjs';
 import { controlSettings, createSshSession, sessionDirectory } from './ssh-session.mjs';
 import { failure } from './errors.mjs';
-
 const ALIAS = 'stack-vps';
 const forward = (file) => file.replaceAll('\\', '/');
 const configPath = (file) => '"' + forward(file).replaceAll('"', '\\"') + '"';
 const controlLines = (controlPath) => controlSettings(configPath(controlPath)).map((setting) => `  ${setting.replace('=', ' ')}`);
-
 /** True when the operator's docker CLI has to be pointed at the manager by this module. */
 function needed(ctx, config, sshCmd) {
-  if (config.nativeTarget) return true;
-  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(memberFile(config.secretsDir, slug)));
+    if (config.nativeTarget)
+        return true;
+    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(memberFile(config.secretsDir, slug)));
 }
-
 function sshConfig(session, controlPath, windows) {
-  const at = session.account.lastIndexOf('@');
-  return [
-    `Host ${ALIAS}`, `  HostName ${session.account.slice(at + 1)}`, `  User ${session.account.slice(0, at)}`,
-    ...(session.port ? [`  Port ${session.port}`] : []),
-    `  IdentityFile ${configPath(session.keyFile)}`, '  IdentitiesOnly yes', `  UserKnownHostsFile ${configPath(session.knownFile)}`,
-    `  StrictHostKeyChecking ${session.strict}`, '  BatchMode yes', '  ConnectTimeout 20',
-    ...(windows ? [] : controlLines(controlPath)), '',
-  ].join('\n');
+    const at = session.account.lastIndexOf('@');
+    return [
+        `Host ${ALIAS}`, `  HostName ${session.account.slice(at + 1)}`, `  User ${session.account.slice(0, at)}`,
+        ...(session.port ? [`  Port ${session.port}`] : []),
+        `  IdentityFile ${configPath(session.keyFile)}`, '  IdentitiesOnly yes', `  UserKnownHostsFile ${configPath(session.knownFile)}`,
+        `  StrictHostKeyChecking ${session.strict}`, '  BatchMode yes', '  ConnectTimeout 20',
+        ...(windows ? [] : controlLines(controlPath)), '',
+    ].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, controlPath) {
-  const home = path.join(session.dir, 'home');
-  fs.mkdirSync(home, { recursive: true, mode: 0o700 });
-  fs.chmodSync(home, 0o700);
-  fs.mkdirSync(path.join(home, '.ssh'), { recursive: true, mode: 0o700 });
-  writePrivate(ctx, path.join(home, '.ssh', 'config'), sshConfig(session, controlPath, (ctx.platform ?? process.platform) === 'win32'));
-  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 } : {}) };
+    const home = path.join(session.dir, 'home');
+    fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+    fs.chmodSync(home, 0o700);
+    fs.mkdirSync(path.join(home, '.ssh'), { recursive: true, mode: 0o700 });
+    writePrivate(ctx, path.join(home, '.ssh', 'config'), sshConfig(session, controlPath, (ctx.platform ?? process.platform) === 'win32'));
+    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 } : {}) };
 }
-
 /** OpenSSH resolves its default config from the account database, so Docker needs a private PATH entry that supplies -F explicitly. */
 function privateSshEnvironment(ctx, env, dir, controlPath) {
-  if ((ctx.platform ?? process.platform) === 'win32') {
+    if ((ctx.platform ?? process.platform) === 'win32') {
+        const home = path.join(dir, 'home');
+        fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+        fs.chmodSync(home, 0o700);
+        const originalHome = env.HOME ?? env.USERPROFILE;
+        const dockerConfig = env.DOCKER_CONFIG ?? (originalHome ? path.join(originalHome, '.docker') : undefined);
+        return { env: { ...env, HOME: home, USERPROFILE: home, ...(dockerConfig ? { DOCKER_CONFIG: dockerConfig } : {}) }, executable: 'ssh' };
+    }
+    const originalHome = ctx.env.HOME;
     const home = path.join(dir, 'home');
-    fs.mkdirSync(home, { recursive: true, mode: 0o700 });
-    fs.chmodSync(home, 0o700);
-    const originalHome = env.HOME ?? env.USERPROFILE;
+    const config = path.join(home, '.ssh', 'config');
+    fs.mkdirSync(path.dirname(config), { recursive: true, mode: 0o700 });
+    if (!fs.existsSync(config)) {
+        const include = originalHome ? `Include ${configPath(path.join(originalHome, '.ssh', 'config'))}\n` : '';
+        writePrivate(ctx, config, ['Host *', ...controlLines(controlPath), 'Host *', include].join('\n'));
+    }
+    const executable = ctx.sshPath ?? findSsh(ctx.env.PATH);
+    const bin = path.join(home, 'bin');
+    fs.mkdirSync(bin, { mode: 0o700 });
+    const shim = path.join(bin, 'ssh');
+    writePrivate(ctx, shim, `#!/bin/sh\nexec ${posixQuote(executable)} -F ${posixQuote(config)} "$@"\n`);
+    fs.chmodSync(shim, 0o700);
     const dockerConfig = env.DOCKER_CONFIG ?? (originalHome ? path.join(originalHome, '.docker') : undefined);
-    return { env: { ...env, HOME: home, USERPROFILE: home, ...(dockerConfig ? { DOCKER_CONFIG: dockerConfig } : {}) }, executable: 'ssh' };
-  }
-  const originalHome = ctx.env.HOME;
-  const home = path.join(dir, 'home');
-  const config = path.join(home, '.ssh', 'config');
-  fs.mkdirSync(path.dirname(config), { recursive: true, mode: 0o700 });
-  if (!fs.existsSync(config)) {
-    const include = originalHome ? `Include ${configPath(path.join(originalHome, '.ssh', 'config'))}\n` : '';
-    writePrivate(ctx, config, ['Host *', ...controlLines(controlPath), 'Host *', include].join('\n'));
-  }
-  const executable = ctx.sshPath ?? findSsh(ctx.env.PATH);
-  const bin = path.join(home, 'bin');
-  fs.mkdirSync(bin, { mode: 0o700 });
-  const shim = path.join(bin, 'ssh');
-  writePrivate(ctx, shim, `#!/bin/sh\nexec ${posixQuote(executable)} -F ${posixQuote(config)} "$@"\n`);
-  fs.chmodSync(shim, 0o700);
-  const dockerConfig = env.DOCKER_CONFIG ?? (originalHome ? path.join(originalHome, '.docker') : undefined);
-  return { env: { ...env, HOME: home, PATH: `${bin}:${env.PATH ?? ctx.env.PATH ?? ''}`, ...(dockerConfig ? { DOCKER_CONFIG: dockerConfig } : {}) }, executable };
+    return { env: { ...env, HOME: home, PATH: `${bin}:${env.PATH ?? ctx.env.PATH ?? ''}`, ...(dockerConfig ? { DOCKER_CONFIG: dockerConfig } : {}) }, executable };
 }
-
 const posixQuote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
-
 function findSsh(searchPath = '') {
-  const executable = searchPath.split(':').map((dir) => path.join(dir, 'ssh')).find((file) => fs.existsSync(file));
-  if (!executable) throw failure('STACK_SSH_SESSION', 'cannot locate the SSH executable');
-  return path.resolve(executable);
+    const executable = searchPath.split(':').map((dir) => path.join(dir, 'ssh')).find((file) => fs.existsSync(file));
+    if (!executable)
+        throw failure('STACK_SSH_SESSION', 'cannot locate the SSH executable');
+    return path.resolve(executable);
 }
-
 /** 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 (sshCmd) return body(ctx);
-  const sealed = needed(ctx, config, sshCmd);
-  const alias = sealed ? ALIAS : sshAlias(ctx.env.DOCKER_HOST);
-  if (!alias) return body(ctx);
-  const session = sealed ? openSealedSession(ctx, config) : null;
-  const dir = session?.dir ?? sessionDirectory();
-  let connection;
-  let cleaned = false;
-  function cleanup() {
-    if (cleaned) return;
-    cleaned = true;
-    if (session) session.cleanup();
-    else fs.rmSync(dir, { recursive: true, force: true });
-  }
-  try {
-    const controlPath = forward(path.join(dir, 'home', 'cm'));
-    const baseEnv = session ? dockerEnvironment(ctx, session, controlPath) : ctx.env;
-    const { env, executable } = privateSshEnvironment(ctx, baseEnv, dir, controlPath);
-    const configFile = path.join(env.HOME ?? '', '.ssh', 'config');
-    const options = ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=20', ...(session?.port ? ['-p', String(session.port)] : [])];
-    const argv = session || executable !== 'ssh' ? [executable, ...options, '-F', configFile, '--', alias] : ['ssh', ...options, '--', alias];
-    connection = createSshSession(ctx, { argv, env, controlPath, cleanup });
-    const spawn = dockerSpawn(ctx, connection, env, alias);
-    for (const note of session?.notes ?? []) ctx.stderr(`${note}\n`);
-    return await body(Object.create(ctx, { spawn: { value: spawn }, stackSsh: { value: connection } }));
-  } finally {
-    try { await connection?.close(); } finally {
-      cleanup();
+    if (sshCmd)
+        return body(ctx);
+    const sealed = needed(ctx, config, sshCmd);
+    const alias = sealed ? ALIAS : sshAlias(ctx.env.DOCKER_HOST);
+    if (!alias)
+        return body(ctx);
+    const session = sealed ? openSealedSession(ctx, config) : null;
+    const dir = session?.dir ?? sessionDirectory();
+    let connection;
+    let cleaned = false;
+    function cleanup() {
+        if (cleaned)
+            return;
+        cleaned = true;
+        if (session)
+            session.cleanup();
+        else
+            fs.rmSync(dir, { recursive: true, force: true });
+    }
+    try {
+        const controlPath = forward(path.join(dir, 'home', 'cm'));
+        const baseEnv = session ? dockerEnvironment(ctx, session, controlPath) : ctx.env;
+        const { env, executable } = privateSshEnvironment(ctx, baseEnv, dir, controlPath);
+        const configFile = path.join(env.HOME ?? '', '.ssh', 'config');
+        const options = ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=20', ...(session?.port ? ['-p', String(session.port)] : [])];
+        const argv = session || executable !== 'ssh' ? [executable, ...options, '-F', configFile, '--', alias] : ['ssh', ...options, '--', alias];
+        connection = createSshSession(ctx, { argv, env, controlPath, cleanup });
+        const spawn = dockerSpawn(ctx, connection, env, alias);
+        for (const note of session?.notes ?? [])
+            ctx.stderr(`${note}\n`);
+        return await body(Object.create(ctx, { spawn: { value: spawn }, stackSsh: { value: connection } }));
+    }
+    finally {
+        try {
+            await connection?.close();
+        }
+        finally {
+            cleanup();
+        }
     }
-  }
 }
-
 /** Only SSH Docker endpoints belong to this connection; TCP, unix and explicitly supplied child environments keep their behavior. */
 function sshAlias(host) {
-  if (!host?.startsWith('ssh://')) return null;
-  const endpoint = new URL(host);
-  if (endpoint.port || endpoint.pathname && endpoint.pathname !== '/') return null;
-  return endpoint.username ? `${decodeURIComponent(endpoint.username)}@${endpoint.hostname}` : endpoint.hostname;
+    if (!host?.startsWith('ssh://'))
+        return null;
+    const endpoint = new URL(host);
+    if (endpoint.port || endpoint.pathname && endpoint.pathname !== '/')
+        return null;
+    return endpoint.username ? `${decodeURIComponent(endpoint.username)}@${endpoint.hostname}` : endpoint.hostname;
 }
-
 function dockerSpawn(ctx, connection, env, alias) {
-  return (command, args, options = {}) => {
-    if (command !== 'docker' || options.env !== undefined) return ctx.spawn(command, args, options);
-    return ctx.spawn(command, args, { ...options, env: { ...env, DOCKER_HOST: connection.dockerHost(alias) } });
-  };
+    const spawn = (command, args, options = {}) => {
+        if (command !== 'docker' || options.env !== undefined)
+            return ctx.spawn(command, args, options);
+        return ctx.spawn(command, args, { ...options, env: { ...env, DOCKER_HOST: connection.dockerHost(alias) } });
+    };
+    return spawn;
 }

package/stack/edge-alias.d.mts

@@ -0,0 +1,42 @@
+import type { DeployConfig } from './config.mjs';
+import type { StackContext } from './context.mjs';
+import type { Runner } from './remote.mjs';
+/** A service attached to an external (edge) network, with the aliases it declares. */
+export interface EdgeAttachment {
+    service: string;
+    network: string;
+    aliases: string[];
+}
+/** One implicit short-name alias that another tenant of the network already resolves. */
+export interface EdgeClash {
+    service: string;
+    alias: string;
+    network: string;
+    holder: string;
+}
+/** The attachments of the stack file `file`. */
+export declare const edgeAttachmentsOf: (file: string) => EdgeAttachment[];
+/**
+ * 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 declare function edgeCollisions(run: Runner, config: Pick<DeployConfig, 'stack'>, bytes: string): Promise<{
+    networks: string[];
+    clashes: EdgeClash[];
+}>;
+/** The refusal text of one clash. */
+export declare const describeClash: (clash: EdgeClash) => string;
+type DockerCtx = Pick<StackContext, 'spawn'>;
+/**
+ * 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 declare function reconcileEdgeAliases(ctx: DockerCtx, config: Pick<DeployConfig, 'stack'>, file: string): {
+    ok: boolean;
+    lines: string[];
+};
+/** `stack verify`: throws when the service is not attached to the edge network or carries any alias other than the declared ones. */
+export declare function verifyEdgeAttachment(ctx: DockerCtx, config: Pick<DeployConfig, 'stack'>, item: EdgeAttachment): string;
+export {};

package/stack/edge-alias.mjs

@@ -13,106 +13,108 @@ 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 .}}';
-
+// reason: a compose `networks:` value parsed from YAML, a list of names or a map of attachments
 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. */
 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) })));
+    // reason: a compose file parsed from YAML; networks and services are read defensively below
+    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`);
-  }
+    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; }
+    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 ?? {})];
+    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 };
+    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;
+    // reason: `docker service inspect` output, parsed JSON read defensively
+    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;
+    const lines = [];
+    const ids = new Map();
+    for (const item of edgeAttachmentsOf(file)) {
+        safe(item);
+        const service = `${config.stack}_${item.service}`;
+        let id = ids.get(item.network);
+        if (id === undefined) {
+            id = networkId(ctx, item.network);
+            ids.set(item.network, id);
+        }
+        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)}`);
     }
-    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 };
+    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)}`;
+    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.d.mts

@@ -0,0 +1,18 @@
+export declare const EXIT: Readonly<{
+    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 declare class StackError extends Error {
+    code: string;
+    exit: number;
+    constructor(code: string, message: string, exit?: number);
+}
+/** A failed step (a check or an effect did not succeed): exit 1. */
+export declare const failure: (code: string, message: string) => StackError;
+/** A refusal (bad usage, unsafe or unknown input, missing configuration): exit 2. */
+export declare const refusal: (code: string, message: string) => StackError;
+/** The owner has not approved a one-time effect: exit 3. */
+export declare const approvalMissing: (code: string, message: string) => StackError;

package/stack/errors.mjs

@@ -1,21 +1,19 @@
 // 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;
-  }
+    code;
+    exit;
+    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);

package/stack/image-scan.d.mts

@@ -0,0 +1,20 @@
+import type { StackContext } from './context.mjs';
+/** One finding: the rule and the place, never the matched text. */
+export interface Hit {
+    kind: string;
+    where: string;
+    why: string;
+}
+/** The result of scanning one image. */
+export interface ImageScan {
+    ok: boolean;
+    hits: Hit[];
+    errors: string[];
+}
+/**
+ * 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 declare function scanImage(ctx: StackContext, ref: string, { allowedArgs }: {
+    allowedArgs: string[];
+}): ImageScan;