@starci/hfs 4.11.22 → 4.12.2

package/stack/cli.mjs

@@ -1,5 +1,14 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 // cli.mjs - `starci app stack <action>` for the Swarm deploy tooling: flags, dry run versus --execute, dispatch, text and --json output.
-//   starci app stack prepare|doctor|connect|disconnect|build-args|render|deploy|converge|verify|rollback|prune|backup|jobs|task --env <env> [flags]
+//   starci app stack <action> --env <env> [the action's FLAGS]     (only the READ_ONLY actions default --env to production)
+// Each action takes only its own flags: a flag of another action is a refusal, never ignored.
 // (up, down and status are the test-world verbs and are dispatched by packages/hfs/src/main.mjs.)
 // Every action module exports one async function (ctx, config, options) -> { ok, lines, data }; a refusal throws StackError.
 import path from 'node:path';
@@ -9,156 +18,204 @@ import { withDockerTransport } from './docker-transport.mjs';
 import { StackError, EXIT, refusal } from './errors.mjs';
 import { parseTargetBinding, bindStackTarget, nativeToolEnvironment } from './target-binding.mjs';
 import { oneCommand, prepareUrgentRelease } from './urgent-release.mjs';
-
 /** The actions that drive the docker CLI of the operator machine (pointed at the manager by docker-transport.mjs when the key is sealed). */
 const DOCKER_ACTIONS = new Set(['deploy', 'accept', 'converge', 'verify', 'rollback', 'prune']);
-
-export const ACTIONS = Object.freeze(['prepare', 'doctor', 'connect', 'disconnect', 'build-args', 'render', 'deploy', 'converge', 'verify', 'rollback', 'prune', 'backup', 'jobs', 'task', 'ingress', 'retire', 'build', 'accept']);
-
-const BOOLEAN = new Set(['--execute', '--json', '--swarm-state', '--init-swarm', '--owner-approved', '--fix-live-restore', '--skip-public', '--skip-internal', '--allow-unpinned', '--push', '--urgent', '--first-start']);
-const VALUE = new Set(['--env', '--image', '--source-sha', '--previous', '--out', '--release', '--since', '--timeout', '--retry', '--keep', '--app', '--ssh-cmd', '--extra-compose', '--project', '--target-binding', '--db-url-env', '--backup-out', '--db-service', '--reason', '--remote']);
-const REPEAT = new Set(['--image', '--keep', '--extra-compose', '--project']);
-
-/** Splits argv into { flags, positional }; an unknown flag or a flag without its value is a refusal. */
-function parseFlags(argv) {
-  const flags = {};
-  const positional = [];
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index];
-    if (BOOLEAN.has(arg)) flags[arg.slice(2)] = true;
-    else if (VALUE.has(arg)) {
-      const value = argv[index + 1];
-      if (value === undefined || value.startsWith('--')) throw refusal('STACK_USAGE', `${arg} needs a value`);
-      index += 1;
-      const key = arg.slice(2);
-      flags[key] = REPEAT.has(arg) ? [...(flags[key] ?? []), value] : value;
-    } else if (arg.startsWith('--')) throw refusal('STACK_USAGE', `unknown flag ${arg}`);
-    else positional.push(arg);
-  }
-  return { flags, positional };
+export const ACTIONS = Object.freeze(['prepare', 'connect', 'disconnect', 'build-args', 'render', 'deploy', 'converge', 'verify', 'rollback', 'prune', 'backup', 'jobs', 'task', 'ingress', 'retire', 'build', 'accept']);
+/** True when `value` names one action of `starci app stack`. */
+export const isAction = (value) => ACTIONS.includes(value);
+export const BOOLEAN = new Set(['--execute', '--json', '--swarm-state', '--init-swarm', '--owner-approved', '--fix-live-restore', '--skip-public', '--skip-internal', '--allow-unpinned', '--push', '--urgent', '--first-start']);
+export const VALUE = new Set(['--env', '--image', '--sha', '--previous', '--out', '--release', '--since', '--timeout', '--retry', '--keep', '--app', '--ssh-cmd', '--extra-compose', '--project', '--target-binding', '--db-url-env', '--backup-out', '--db-service', '--reason', '--remote']);
+export const REPEAT = new Set(['--image', '--keep', '--extra-compose', '--project']);
+/** `--ssh-cmd` replaces the configured alias for an action whose module (or the Docker transport) reaches the manager over SSH. */
+const SSH = ['--ssh-cmd'];
+/**
+ * The flags each action takes besides `--env` and `--json`: exactly the flags its OPTIONS entry below reads, plus `--ssh-cmd` where the
+ * action reaches the manager. Any other flag is refused with the action named, so `verify --execute` never reads as an effect.
+ */
+export const FLAGS = Object.freeze({
+    prepare: ['--execute', '--init-swarm', '--owner-approved', '--fix-live-restore', ...SSH],
+    connect: ['--execute'],
+    disconnect: ['--execute'],
+    'build-args': ['--app'],
+    render: ['--image', '--sha', '--previous', '--out', '--allow-unpinned', '--extra-compose'],
+    deploy: ['--image', '--sha', '--execute', '--out', '--timeout', '--retry', '--skip-public', '--target-binding', '--urgent', '--reason', '--remote', '--db-url-env', '--backup-out', '--first-start', '--db-service', ...SSH],
+    converge: ['--since', '--timeout', ...SSH],
+    verify: ['--retry', '--skip-public', '--skip-internal', '--target-binding', ...SSH],
+    rollback: ['--release', '--execute', '--timeout', ...SSH],
+    prune: ['--keep', '--execute', ...SSH],
+    backup: ['--swarm-state', '--execute', ...SSH],
+    jobs: ['--execute', ...SSH],
+    task: ['--execute', ...SSH],
+    ingress: ['--execute', ...SSH],
+    retire: ['--project', '--execute', ...SSH],
+    build: ['--push', '--execute'],
+    accept: ['--release', '--execute', '--retry', ...SSH],
+});
+/** The operands of the actions that take any, as the usage prints them. */
+export const OPERANDS = Object.freeze({ jobs: '<action> [<arg>...]', task: '<name> [<arg>...]', ingress: '<action> [<arg>...]' });
+/** The read-only actions, whose `--env` defaults to production. Every action with an effect names its environment, so none reaches production by omission. */
+export const READ_ONLY = Object.freeze(['build-args', 'render', 'verify']);
+/** Splits argv into { flags, positional }; an unknown flag, a flag of another action or a flag without its value is a refusal. */
+function parseFlags(action, argv) {
+    const own = new Set(['--env', '--json', ...FLAGS[action]]);
+    const flags = {};
+    const positional = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg.startsWith('--') && !BOOLEAN.has(arg) && !VALUE.has(arg))
+            throw refusal('STACK_USAGE', `unknown flag ${arg}`);
+        if (arg.startsWith('--') && !own.has(arg))
+            throw refusal('STACK_USAGE', `stack ${action} takes no ${arg}: its flags are ${[...own].join(', ')}`);
+        if (BOOLEAN.has(arg))
+            flags[arg.slice(2)] = true;
+        else if (VALUE.has(arg)) {
+            const value = argv[index + 1];
+            if (value === undefined || value.startsWith('--'))
+                throw refusal('STACK_USAGE', `${arg} needs a value`);
+            index += 1;
+            const key = arg.slice(2);
+            flags[key] = REPEAT.has(arg) ? [...(flags[key] ?? []), value] : value;
+        }
+        else
+            positional.push(arg);
+    }
+    return { flags: flags, positional }; // BOOLEAN, VALUE and REPEAT decide each flag's kind above
+}
+/** The flag combinations of deploy's two forms: the one-command urgent release (no --image, no --sha) and the image form, and the urgent floor's own flags. */
+function checkDeployForm(flags) {
+    if (!flags.urgent && (flags.reason || flags.remote))
+        throw refusal('STACK_USAGE', '--reason and --remote release HEAD in the one-command urgent deploy: add --urgent');
+    if (flags.reason || flags.remote) {
+        if (flags.sha || flags.image)
+            throw refusal('STACK_USAGE', '--reason and --remote belong to the one-command urgent deploy without --image and --sha; the image form deploys a commit whose urgent record was already pushed');
+    }
+    if (!flags.urgent && (flags['first-start'] || flags['db-service']))
+        throw refusal('STACK_USAGE', '--first-start and --db-service are the first start of an empty database under the urgent floor: add --urgent');
+    if (!flags.urgent && (flags['db-url-env'] || flags['backup-out']))
+        throw refusal('STACK_USAGE', '--db-url-env and --backup-out choose the urgent floor\'s database and backup folder: add --urgent');
 }
-
 /** `--image api=ghcr.io/o/x@sha256:...` (repeatable or comma separated) -> { api: 'ghcr.io/o/x@sha256:...' }. */
 function parseImages(values = []) {
-  const out = {};
-  for (const item of values.flatMap((value) => value.split(','))) {
-    const at = item.indexOf('=');
-    const service = item.slice(0, at);
-    if (at < 1 || at === item.length - 1 || Object.hasOwn(out, service)) throw refusal('STACK_USAGE', `--image takes <service>=<reference>, once per service (got ${service || item})`);
-    out[service] = item.slice(at + 1);
-  }
-  return out;
+    const out = {};
+    for (const item of values.flatMap((value) => value.split(','))) {
+        const at = item.indexOf('=');
+        const service = item.slice(0, at);
+        if (at < 1 || at === item.length - 1 || Object.hasOwn(out, service))
+            throw refusal('STACK_USAGE', `--image takes <service>=<reference>, once per service (got ${service || item})`);
+        out[service] = item.slice(at + 1);
+    }
+    return out;
 }
-
 const number = (flags, name) => {
-  if (flags[name] === undefined) return undefined;
-  const value = Number(flags[name]);
-  if (!Number.isFinite(value) || value < 0) throw refusal('STACK_USAGE', `--${name} must be a number of seconds`);
-  return value;
+    if (flags[name] === undefined)
+        return undefined;
+    const value = Number(flags[name]);
+    if (!Number.isFinite(value) || value < 0)
+        throw refusal('STACK_USAGE', `--${name} must be a number of seconds`);
+    return value;
 };
-
 /** The options object each action module receives, from the parsed flags. */
 const OPTIONS = {
-  prepare: ({ flags }) => ({ execute: flags.execute === true, initSwarm: flags['init-swarm'] === true, ownerApproved: flags['owner-approved'] === true, fixLiveRestore: flags['fix-live-restore'] === true }),
-  doctor: () => ({}),
-  connect: ({ flags }) => ({ execute: flags.execute === true }),
-  disconnect: ({ flags }) => ({ execute: flags.execute === true }),
-  'build-args': ({ flags }) => ({ app: flags.app }),
-  render: ({ flags, cwd }) => ({
-    images: parseImages(flags.image), sourceSha: flags['source-sha'], previous: flags.previous ?? null,
-    out: flags.out ? path.resolve(cwd, flags.out) : null, allowUnpinned: flags['allow-unpinned'] === true,
-    extraCompose: (flags['extra-compose'] ?? []).map((file) => path.resolve(cwd, file)),
-  }),
-  deploy: ({ flags, cwd }) => ({
-    images: parseImages(flags.image), sourceSha: flags['source-sha'], execute: flags.execute === true,
-    out: flags.out ? path.resolve(cwd, flags.out) : null, timeoutSeconds: number(flags, 'timeout'), retrySeconds: number(flags, 'retry'), skipPublic: flags['skip-public'] === true,
-    urgent: flags.urgent === true, dbUrlEnv: flags['db-url-env'], backupOut: flags['backup-out'] ? path.resolve(cwd, flags['backup-out']) : undefined,
-    firstStart: flags['first-start'] === true, dbService: flags['db-service'], reason: flags.reason, remote: flags.remote,
-  }),
-  converge: ({ flags }) => ({ since: flags.since, timeoutSeconds: number(flags, 'timeout') }),
-  verify: ({ flags }) => ({ retrySeconds: number(flags, 'retry'), skipPublic: flags['skip-public'] === true, skipInternal: flags['skip-internal'] === true }),
-  rollback: ({ flags }) => ({ release: flags.release ?? null, execute: flags.execute === true, timeoutSeconds: number(flags, 'timeout') }),
-  prune: ({ flags, cwd }) => ({ keepFiles: (flags.keep ?? []).map((file) => path.resolve(cwd, file)), execute: flags.execute === true }),
-  backup: ({ flags }) => ({ swarmState: flags['swarm-state'] === true, execute: flags.execute === true }),
-  ingress: ({ flags, positional }) => ({ action: positional[0], execute: flags.execute === true, args: positional.slice(1) }),
-  build: ({ flags }) => ({ push: flags.push === true, execute: flags.execute === true }),
-  accept: ({ flags }) => ({ release: flags.release ?? null, execute: flags.execute === true, retrySeconds: number(flags, 'retry') }),
-  retire: ({ flags }) => ({ projects: flags.project ?? [], execute: flags.execute === true }),
-  jobs: ({ flags, positional }) => ({ action: positional[0], args: positional.slice(1), execute: flags.execute === true }),
-  task: ({ flags, positional }) => ({ name: positional[0], args: positional.slice(1), execute: flags.execute === true }),
+    prepare: ({ flags }) => ({ execute: flags.execute === true, initSwarm: flags['init-swarm'] === true, ownerApproved: flags['owner-approved'] === true, fixLiveRestore: flags['fix-live-restore'] === true }),
+    connect: ({ flags }) => ({ execute: flags.execute === true }),
+    disconnect: ({ flags }) => ({ execute: flags.execute === true }),
+    'build-args': ({ flags }) => ({ app: flags.app }),
+    render: ({ flags, cwd }) => ({
+        images: parseImages(flags.image), sourceSha: flags.sha, previous: flags.previous ?? null,
+        out: flags.out ? path.resolve(cwd, flags.out) : null, allowUnpinned: flags['allow-unpinned'] === true,
+        extraCompose: (flags['extra-compose'] ?? []).map((file) => path.resolve(cwd, file)),
+    }),
+    deploy: ({ flags, cwd }) => ({
+        images: parseImages(flags.image), sourceSha: flags.sha, execute: flags.execute === true,
+        out: flags.out ? path.resolve(cwd, flags.out) : null, timeoutSeconds: number(flags, 'timeout'), retrySeconds: number(flags, 'retry'), skipPublic: flags['skip-public'] === true,
+        urgent: flags.urgent === true, dbUrlEnv: flags['db-url-env'], backupOut: flags['backup-out'] ? path.resolve(cwd, flags['backup-out']) : undefined,
+        firstStart: flags['first-start'] === true, dbService: flags['db-service'], reason: flags.reason, remote: flags.remote,
+    }),
+    converge: ({ flags }) => ({ since: flags.since, timeoutSeconds: number(flags, 'timeout') }),
+    verify: ({ flags }) => ({ retrySeconds: number(flags, 'retry'), skipPublic: flags['skip-public'] === true, skipInternal: flags['skip-internal'] === true }),
+    rollback: ({ flags }) => ({ release: flags.release ?? null, execute: flags.execute === true, timeoutSeconds: number(flags, 'timeout') }),
+    prune: ({ flags, cwd }) => ({ keepFiles: (flags.keep ?? []).map((file) => path.resolve(cwd, file)), execute: flags.execute === true }),
+    backup: ({ flags }) => ({ swarmState: flags['swarm-state'] === true, execute: flags.execute === true }),
+    ingress: ({ flags, positional }) => ({ action: positional[0], execute: flags.execute === true, args: positional.slice(1) }),
+    build: ({ flags }) => ({ push: flags.push === true, execute: flags.execute === true }),
+    accept: ({ flags }) => ({ release: flags.release ?? null, execute: flags.execute === true, retrySeconds: number(flags, 'retry') }),
+    retire: ({ flags }) => ({ projects: flags.project ?? [], execute: flags.execute === true }),
+    jobs: ({ flags, positional }) => ({ action: positional[0], args: positional.slice(1), execute: flags.execute === true }),
+    task: ({ flags, positional }) => ({ name: positional[0], args: positional.slice(1), execute: flags.execute === true }),
 };
-
 const MODULES = {
-  prepare: ['./prepare.mjs', 'prepareHost'], doctor: ['./prepare.mjs', 'doctorHost'],
-  connect: ['./remote.mjs', 'connectCi'], disconnect: ['./remote.mjs', 'disconnectCi'],
-  'build-args': ['./build-args.mjs', 'buildArgs'], render: ['./render.mjs', 'renderRelease'],
-  deploy: ['./deploy.mjs', 'deployRelease'], converge: ['./converge.mjs', 'convergeStack'],
-  verify: ['./verify.mjs', 'verifyStack'], rollback: ['./deploy.mjs', 'rollbackRelease'],
-  prune: ['./prune.mjs', 'pruneStack'], backup: ['./backup.mjs', 'backupVolumes'], jobs: ['./jobs.mjs', 'runJobs'], task: ['./task.mjs', 'runTask'],
-  ingress: ['./ingress.mjs', 'runIngress'],
-  retire: ['./retire.mjs', 'retireCompose'],
-  build: ['./build.mjs', 'buildImages'],
-  accept: ['./deploy.mjs', 'acceptRelease'],
+    prepare: ['./prepare.mjs', 'prepareHost'],
+    connect: ['./remote.mjs', 'connectCi'], disconnect: ['./remote.mjs', 'disconnectCi'],
+    'build-args': ['./build-args.mjs', 'buildArgs'], render: ['./render.mjs', 'renderRelease'],
+    deploy: ['./deploy.mjs', 'deployRelease'], converge: ['./converge.mjs', 'convergeStack'],
+    verify: ['./verify.mjs', 'verifyStack'], rollback: ['./deploy.mjs', 'rollbackRelease'],
+    prune: ['./prune.mjs', 'pruneStack'], backup: ['./backup.mjs', 'backupVolumes'], jobs: ['./jobs.mjs', 'runJobs'], task: ['./task.mjs', 'runTask'],
+    ingress: ['./ingress.mjs', 'runIngress'],
+    retire: ['./retire.mjs', 'retireCompose'],
+    build: ['./build.mjs', 'buildImages'],
+    accept: ['./deploy.mjs', 'acceptRelease'],
 };
-
 async function handlerOf(action, importer) {
-  const [file, name] = MODULES[action];
-  return (await importer(file))[name];
+    const [file, name] = MODULES[action];
+    return (await importer(file))[name]; // each MODULES entry names an exported action function
 }
-
 function print(ctx, action, flags, result) {
-  if (flags.json) ctx.stdout(`${JSON.stringify({ verb: action, ok: result.ok, ...result.data }, null, 2)}\n`);
-  else for (const line of result.lines ?? []) ctx.stdout(`${line}\n`);
+    if (flags.json)
+        ctx.stdout(`${JSON.stringify({ verb: action, ok: result.ok, ...result.data }, null, 2)}\n`);
+    else
+        for (const line of result.lines ?? [])
+            ctx.stdout(`${line}\n`);
 }
-
 function nativeToolContext(ctx, binding) {
-  if (!binding) return ctx;
-  return Object.create(ctx, { spawn: { value: (command, args, options = {}) => ctx.spawn(command, args,
-    { ...options, env: nativeToolEnvironment(options.env ?? ctx.env) }) } });
+    if (!binding)
+        return ctx;
+    return Object.create(ctx, { spawn: { value: (command, args, options = {}) => ctx.spawn(command, args, { ...options, env: nativeToolEnvironment(options.env ?? ctx.env) }) } });
 }
-
 /** Runs one action; returns the exit code. `io.importer` lets a spec load fake action modules. */
 export async function stackMain(argv, io = {}) {
-  const ctx = stackContext(io);
-  try {
-    const { flags, positional } = parseFlags(argv.slice(1));
-    const action = argv[0];
-    if (!ACTIONS.includes(action)) throw refusal('STACK_USAGE', `starci app stack takes ${[...ACTIONS, 'up', 'down', 'status'].join(', ')}`);
-    const binding = parseTargetBinding(flags['target-binding'], 'docker-swarm');
-    if (binding && (!['deploy', 'verify'].includes(action) || flags['ssh-cmd'] || flags['skip-public'] || flags['skip-internal']))
-      throw refusal('STACK_USAGE', 'the bound native consumer supports only complete deploy or verify');
-    const config = bindStackTarget(ctx, loadDeployConfig({ repoRoot: ctx.cwd, env: flags.env ?? 'production' }), binding);
-    if (action !== 'deploy' && (flags.urgent || flags['db-url-env'] || flags['backup-out'] || flags['first-start'] || flags['db-service'] || flags.reason || flags.remote)) throw refusal('STACK_USAGE', '--urgent, --db-url-env, --backup-out, --first-start, --db-service, --reason and --remote belong to deploy');
-    if (!flags.urgent && (flags.reason || flags.remote)) throw refusal('STACK_USAGE', '--reason and --remote release HEAD in the one-command urgent deploy: add --urgent');
-    if (!flags.urgent && (flags['first-start'] || flags['db-service'])) throw refusal('STACK_USAGE', '--first-start and --db-service are the first start of an empty database under the urgent floor: add --urgent');
-    if (action === 'deploy' && !flags.urgent && (flags['db-url-env'] || flags['backup-out'])) throw refusal('STACK_USAGE', '--db-url-env and --backup-out choose the urgent floor\'s database and backup folder: add --urgent');
-    let options = OPTIONS[action]({ flags, positional, cwd: ctx.cwd });
-    // The one-command urgent deploy releases HEAD and builds its images here, before the Docker transport reaches the server.
-    let prepared = null;
-    if (action === 'deploy' && oneCommand(options)) {
-      prepared = await prepareUrgentRelease(ctx, config, { ...options, role: io.harness?.role ?? ctx.env.STARCI_ROLE });
-      if (!prepared.images) {
-        print(ctx, action, flags, prepared);
-        return prepared.ok ? EXIT.ok : EXIT.failed;
-      }
-      options = { ...options, images: prepared.images, sourceSha: prepared.sourceSha };
+    const ctx = stackContext(io);
+    try {
+        const action = argv[0];
+        if (!isAction(action))
+            throw refusal('STACK_USAGE', `starci app stack takes ${[...ACTIONS, 'up', 'down', 'status'].join(', ')}`);
+        const { flags, positional } = parseFlags(action, argv.slice(1));
+        if (flags.env === undefined && !READ_ONLY.includes(action))
+            throw refusal('STACK_USAGE', `stack ${action} has an effect: name its environment with --env <env> (only ${READ_ONLY.join(', ')} default to production)`);
+        if (action === 'deploy')
+            checkDeployForm(flags);
+        const binding = parseTargetBinding(flags['target-binding'], 'docker-swarm');
+        if (binding && (flags['ssh-cmd'] || flags['skip-public'] || flags['skip-internal']))
+            throw refusal('STACK_USAGE', 'the bound native consumer supports only complete deploy or verify');
+        const config = bindStackTarget(ctx, loadDeployConfig({ repoRoot: ctx.cwd, env: flags.env ?? 'production' }), binding);
+        let options = OPTIONS[action]({ flags, positional, cwd: ctx.cwd });
+        // The one-command urgent deploy releases HEAD and builds its images here, before the Docker transport reaches the server.
+        let prepared = null;
+        if (action === 'deploy' && oneCommand(options)) { // OPTIONS.deploy builds the deploy options
+            prepared = await prepareUrgentRelease(ctx, config, { ...options, role: io.harness?.role ?? ctx.env.STARCI_ROLE });
+            if (!prepared.images) {
+                print(ctx, action, flags, prepared);
+                return prepared.ok ? EXIT.ok : EXIT.failed;
+            }
+            options = { ...options, images: prepared.images, sourceSha: prepared.sourceSha };
+        }
+        const handler = await handlerOf(action, io.importer ?? ((file) => import(__rewriteRelativeImportExtension(file))));
+        const sshCmd = flags['ssh-cmd'] ?? null;
+        const call = (context) => handler(context, config, { ...options, sshCmd });
+        const toolContext = nativeToolContext(ctx, binding);
+        const ran = DOCKER_ACTIONS.has(action) ? await withDockerTransport(toolContext, config, { sshCmd }, call) : await call(toolContext);
+        const result = prepared ? { ...ran, lines: [...prepared.lines, ...(ran.lines ?? [])] } : ran;
+        print(ctx, action, flags, result);
+        // A floor step of an urgent deploy that failed is a refusal with its own code (urgent-floor.mjs), printed after the lines that led to it.
+        if (result.refused) {
+            ctx.stderr(`starci app stack: ${result.refused.code}: ${result.refused.message}\n`);
+            return EXIT.refused;
+        }
+        return result.ok ? EXIT.ok : EXIT.failed;
     }
-    const handler = await handlerOf(action, io.importer ?? ((file) => import(file)));
-    const sshCmd = flags['ssh-cmd'] ?? null;
-    const call = (context) => handler(context, config, { ...options, sshCmd });
-    const toolContext = nativeToolContext(ctx, binding);
-    const ran = DOCKER_ACTIONS.has(action) ? await withDockerTransport(toolContext, config, { sshCmd }, call) : await call(toolContext);
-    const result = prepared ? { ...ran, lines: [...prepared.lines, ...(ran.lines ?? [])] } : ran;
-    print(ctx, action, flags, result);
-    // A floor step of an urgent deploy that failed is a refusal with its own code (urgent-floor.mjs), printed after the lines that led to it.
-    if (result.refused) {
-      ctx.stderr(`starci app stack: ${result.refused.code}: ${result.refused.message}\n`);
-      return EXIT.refused;
+    catch (error) {
+        if (!(error instanceof StackError))
+            throw error;
+        ctx.stderr(`starci app stack: ${error.message}\n`);
+        return error.exit;
     }
-    return result.ok ? EXIT.ok : EXIT.failed;
-  } catch (error) {
-    if (!(error instanceof StackError)) throw error;
-    ctx.stderr(`starci app stack: ${error.message}\n`);
-    return error.exit;
-  }
 }

package/stack/config.d.mts

@@ -0,0 +1,197 @@
+import { type SealedRoles } from '../runtime/scripts/hfs/stack-deploy-config.mjs';
+import type { TargetBinding } from './target-binding.mjs';
+/** The sealed SSH roles of `deploy.remote.sealed`: the member that holds each. */
+export type SealedRemote = SealedRoles;
+export interface DeployRemote {
+    host: string;
+    releasesBase: string | null;
+    sealed: SealedRemote | null;
+    serverRecipient: string | null;
+}
+export interface BuildArgsSealed {
+    member: string;
+    keys: string[];
+}
+export interface BuildArgsBlock {
+    values: Record<string, string>;
+    sealed: BuildArgsSealed | null;
+}
+export interface ImageEntry {
+    app: string;
+    buildArgs: BuildArgsBlock;
+}
+export interface SecretSource {
+    member: string;
+    keys: string[] | null;
+    required: boolean;
+    fill: boolean;
+}
+export interface SecretGrant {
+    service: string;
+    filePointers: boolean;
+    from: SecretSource[];
+}
+export interface SecretSetting {
+    member: string;
+    keys: string[];
+}
+export interface EnvironmentSetting {
+    key: string;
+    default: string | null;
+}
+export interface ServiceEnvironment {
+    files: string[];
+    values: Record<string, string>;
+    settings: Record<string, EnvironmentSetting>;
+}
+export interface ConfigEntry {
+    name: string;
+    file: string;
+    env: string;
+}
+export interface HttpCheck {
+    name: string;
+    url: string;
+    method: string;
+    body: unknown;
+    status: number;
+    json: Record<string, unknown> | null;
+    contains: unknown;
+    retry: boolean;
+}
+export interface ExecCheck {
+    name: string;
+    service: string;
+    command: string[];
+    stdout: string | null;
+}
+export interface JobsBlock {
+    service: string;
+    command: string[];
+}
+export interface TaskEntry {
+    service: string;
+    command: string[];
+    timeoutSeconds: number;
+}
+export interface BackupVolume {
+    name: string;
+    volume: string;
+}
+export interface BackupBlock {
+    image: string;
+    keepDays: number;
+    dir: string | null;
+    volumes: BackupVolume[];
+}
+export interface RegistryBlock {
+    host: string;
+    visibility: string;
+}
+export interface IngressLegacy {
+    dir: string;
+    dynamicDir: string;
+    container: string;
+}
+export interface IngressUpstream {
+    name: string;
+    hosts: string[];
+    container: string | null;
+    hostAddress: string | null;
+    port: number;
+    aliases: string[];
+    middlewares: string[];
+}
+export interface IngressVerify {
+    host: string;
+    path: string;
+    status: number | null;
+}
+export interface IngressRedirect {
+    host: string;
+    to: string;
+    status: number;
+}
+export interface IngressPublish {
+    file: string;
+    supersedes: string[];
+}
+export interface RehearsalPorts {
+    http: number;
+    https: number;
+}
+export interface IngressTakeover {
+    gateSeconds: number;
+    rehearsalPorts: RehearsalPorts;
+}
+/** The normalised `deploy.ingress` block (stack-ingress-config.mjs). */
+export interface IngressConfig {
+    name: string;
+    image: string | null;
+    args: string[] | null;
+    service: string;
+    network: string;
+    acmeVolume: string;
+    legacy: IngressLegacy;
+    upstreams: IngressUpstream[];
+    routes: string | null;
+    middlewares: Record<string, Record<string, unknown>>;
+    verify: IngressVerify[];
+    drop: string[];
+    redirects: IngressRedirect[];
+    backup: {
+        dir: string;
+    } | null;
+    publish: IngressPublish | null;
+    takeover: IngressTakeover;
+}
+/** The normalised `deploy` block of one environment (stack-deploy-config.mjs). */
+export interface DeployBlock {
+    stack: string;
+    remote: DeployRemote;
+    images: Record<string, ImageEntry>;
+    volumes: string[];
+    secrets: {
+        grants: SecretGrant[];
+        settings: SecretSetting[];
+    };
+    environment: Record<string, ServiceEnvironment>;
+    configs: ConfigEntry[];
+    passEnv: string[];
+    verify: {
+        http: HttpCheck[];
+        exec: ExecCheck[];
+    };
+    jobs: JobsBlock | null;
+    tasks: Record<string, TaskEntry>;
+    postDeploy: string[];
+    backup: BackupBlock | null;
+    ingress: IngressConfig | null;
+    registry: RegistryBlock;
+}
+/** The deploy configuration of one environment, with absolute paths. */
+export interface DeployConfig extends DeployBlock {
+    env: string;
+    project: string;
+    repoRoot: string;
+    envDir: string;
+    stackFile: string;
+    secretsDir: string;
+    members: Set<string>;
+    services: Set<string>;
+    /** Set by bindStackTarget when a native consumer bound the target. */
+    nativeTarget?: Readonly<TargetBinding> | undefined;
+}
+export declare const STACKS_DIR = ".starcistacks";
+export declare const STACKS_FILE = "application-stacks.yaml";
+/** Read a YAML input, refusing with a stack error naming its purpose when it is missing or invalid. */
+export declare const readYaml: (file: string, what: string) => any;
+/**
+ * The normalised deploy configuration of one environment, with absolute paths:
+ *   { env, project, stack, repoRoot, envDir, stackFile, secretsDir, members, services, ...deploy block }.
+ * Throws StackError (exit 2) naming every problem when the block is missing or invalid.
+ */
+export declare function loadDeployConfig({ repoRoot, env }: {
+    repoRoot: string;
+    env: string;
+}): DeployConfig;