@xemahq/repo-build-tooling 0.8.2 → 0.9.0

package/src/composed-image.mjs

@@ -0,0 +1,549 @@
+#!/usr/bin/env node
+// ═══════════════════════════════════════════════════════════════════════════
+// THE BUILD-TIME HALF OF A REPOSITORY'S COMPOSED-PROCESS IMAGE.
+//
+// A composed-process image is ONE image per build: every platform-scheduled
+// service of one repository at one commit, loaded by `@xemahq/xema-service-nest`'s
+// `xema-composed-process` host. Which members share a process is the
+// DEPLOYMENT's declaration, read at boot; this tool decides only what the image
+// CONTAINS, and proves at build time that it can carry it. The runtime half
+// (the host bin, `readServiceEntry`) stays in xema-service-nest; this half never
+// ships inside an image.
+//
+// Every producing repository runs the same steps, so they live here rather than
+// as a copy per repository. What differs per repository is passed in, never
+// assumed: where its biome manifests are (`--manifests`), which Dockerfile is its
+// canonical service Dockerfile (`--canonical-dockerfile`, optional), its
+// cross-repository input manifest (`--cross-repo-manifest`, optional), and the
+// repository a member's sealed subject names (`--build-source`, the `repo` of
+// its subjects in the edition's image lock).
+//
+// Commands (all relative to `--root`, default the current directory):
+//
+//   members --write | --check
+//            derive the member set and write / verify
+//            `<image-dir>/image-build-inputs.json` (its existence at a commit IS
+//            the repository's composed-process declaration).
+//   filters  print `--filter <package>...` for every member, so install and
+//            build cover exactly the members' closures.
+//   dirs     print every member's directory, one per line.
+//   pins <committed-lockfile>
+//            refuse a re-resolved lockfile that pins any registry package the
+//            committed one does not.
+//   index <commit> --build-source <repo>
+//            write the MEMBER INDEX (the kernel's `ComposedProcessMemberIndexSchema`)
+//            and the `xema-composed-process` link the image runs.
+//   load     evaluate every member's entry exactly as the host does
+//            (`readServiceEntry`) and refuse the image if any graph does not load.
+//   coordinate --image-name <name>
+//            the image's content tag (computed ONLY by the repository's own
+//            `xema-compute-image-tag`) and whether GHCR already serves it
+//            (`composed-image-coordinate.mjs`; environment-driven, GITHUB_OUTPUT).
+//   smoke-refusal <image> [--member <biomeId>/<componentKey>]x2
+//            boot the pushed image with a declaration the host must refuse
+//            (`smoke-refusal.mjs`).
+//   dockerfile --write|--check --tooling-version <x.y.z> --copy <dir>… --cache-id <id> --build-source <repo>
+//            render `<image-dir>/Dockerfile` from the package's template
+//            (`composed-image-dockerfile.mjs`).
+//
+// THE MEMBER SET IS DERIVED, NEVER CHOSEN. A component is a member when the
+// kernel would let it be one — `kind: service`, `scheduler: platform` (a worker,
+// a job or a runtime-scheduled service is never a member) — AND the image can run
+// it as it runs dedicated. Four derived facts keep a service out, each one a
+// property of the repository rather than an opinion:
+//
+//   entry-shape       its `src/main.ts` is not a top-level, single
+//                     `void bootstrapXemaService(…)` (the host's
+//                     `readServiceEntry` refuses any other shape by name).
+//   own-dockerfile    it builds from its OWN Dockerfile, which carries
+//                     image-level requirements this image does not provide.
+//   vendored-inputs   it bakes content from another repository (the
+//                     `--cross-repo-manifest`'s `inputs[].consumerService`).
+//   image-toolchain   the `--canonical-dockerfile` installs a verification
+//                     toolchain for it (`ARG SUPPLY_CHAIN_*_SERVICES="…"`).
+//
+// Every step REFUSES rather than skips: an image that silently lacked a member
+// would be refused by the host only when a deployment first composed it.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync, symlinkSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, posix, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
+import { composedCoordinate, emitCoordinate } from './composed-image-coordinate.mjs';
+import { syncComposedDockerfile } from './composed-image-dockerfile.mjs';
+import { runRefusalSmoke } from './smoke-refusal.mjs';
+
+export { COMPOSED_IMAGE_DIR };
+export const IMAGE_BUILD_INPUTS_FILE = 'image-build-inputs.json';
+export const MEMBER_INDEX_FILE = 'xema-composed-member-index.json';
+export const HOST_LINK = 'xema-composed-process';
+export const DEFAULT_MANIFEST_GLOBS = Object.freeze(['**/xema-biome.json']);
+
+const SDK = '@xemahq/xema-service-nest';
+const IDENTITY_PACKAGES = Object.freeze(['@nestjs/common', '@nestjs/core', '@nestjs/config', 'reflect-metadata', SDK]);
+const SUPPLY_CHAIN_ARG = /^ARG\s+(SUPPLY_CHAIN_[A-Z_]+_SERVICES)="([^"]*)"\s*$/gm;
+const COMMIT = /^[a-f0-9]{40}$/;
+
+export const ExclusionReason = Object.freeze({
+  EntryShape: 'entry-shape',
+  OwnDockerfile: 'own-dockerfile',
+  VendoredInputs: 'vendored-inputs',
+  ImageToolchain: 'image-toolchain',
+});
+
+// ── entry shape ─────────────────────────────────────────────────────────────
+
+/**
+ * JS/TS source with `//` and `/* *\/` comment bodies blanked, string and
+ * template literal bodies kept. Newlines survive, so `^`-anchored line tests
+ * still see each line at its own column.
+ */
+export function codeWithoutComments(source) {
+  if (typeof source !== 'string') throw new TypeError(`expected a string, got ${typeof source}`);
+  let out = '';
+  let state = 'code';
+  for (let i = 0; i < source.length; i += 1) {
+    const c = source[i];
+    const next = source[i + 1];
+    if (state === 'line') {
+      if (c === '\n') {
+        state = 'code';
+        out += c;
+      } else out += ' ';
+      continue;
+    }
+    if (state === 'block') {
+      if (c === '*' && next === '/') {
+        state = 'code';
+        out += '  ';
+        i += 1;
+      } else out += c === '\n' ? '\n' : ' ';
+      continue;
+    }
+    if (state === 'code') {
+      if (c === '/' && next === '/') {
+        state = 'line';
+        out += '  ';
+        i += 1;
+        continue;
+      }
+      if (c === '/' && next === '*') {
+        state = 'block';
+        out += '  ';
+        i += 1;
+        continue;
+      }
+      if (c === "'" || c === '"' || c === '`') state = c;
+      out += c;
+      continue;
+    }
+    // Inside a string or template literal.
+    out += c;
+    if (c === '\\') {
+      if (next !== undefined) out += next;
+      i += 1;
+    } else if (c === state) state = 'code';
+  }
+  return out;
+}
+
+/** Exactly one `bootstrapXemaService(` call, as a top-level `void bootstrapXemaService(` statement. */
+export function isComposableEntry(mainTs) {
+  const code = codeWithoutComments(mainTs);
+  const calls = code.match(/\bbootstrapXemaService\s*\(/g) ?? [];
+  return calls.length === 1 && /^void bootstrapXemaService\(/m.test(code);
+}
+
+// ── the member set ──────────────────────────────────────────────────────────
+
+function trackedManifests(root, manifestGlobs) {
+  if (!Array.isArray(manifestGlobs) || manifestGlobs.length === 0) {
+    throw new Error('manifestGlobs must name at least one glob');
+  }
+  const files = execFileSync('git', ['ls-files', '-z', '--', ...manifestGlobs.map((glob) => `:(glob)${glob}`)], {
+    cwd: root,
+    encoding: 'utf8',
+  })
+    .split('\0')
+    .filter(Boolean)
+    .sort();
+  if (files.length === 0) {
+    throw new Error(`no tracked biome manifest matches ${manifestGlobs.join(', ')} under ${root}`);
+  }
+  return files;
+}
+
+function supplyChainServices(root, canonicalDockerfile) {
+  if (canonicalDockerfile === undefined) return new Set();
+  const dockerfile = readFileSync(join(root, canonicalDockerfile), 'utf8');
+  const names = new Set();
+  let found = 0;
+  for (const match of dockerfile.matchAll(SUPPLY_CHAIN_ARG)) {
+    found += 1;
+    for (const name of match[2].split(/\s+/).filter(Boolean)) names.add(name);
+  }
+  if (found === 0) {
+    throw new Error(
+      `${canonicalDockerfile} declares no ARG SUPPLY_CHAIN_*_SERVICES="…" — the image-toolchain ` +
+        'exclusion cannot be derived from it; omit --canonical-dockerfile if this repository has none',
+    );
+  }
+  return names;
+}
+
+function vendoringServices(root, crossRepoManifest) {
+  if (crossRepoManifest === undefined) return new Set();
+  const path = join(root, crossRepoManifest);
+  if (!existsSync(path)) return new Set();
+  const manifest = JSON.parse(readFileSync(path, 'utf8'));
+  return new Set((manifest.inputs ?? []).map((input) => input.consumerService));
+}
+
+function sortKeys(record) {
+  return Object.fromEntries(Object.entries(record).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+
+/** Derive `{ members: { key: directory }, excluded: { key: reason } }` from the tracked biome manifests. */
+export function deriveComposedMembers({
+  root = process.cwd(),
+  manifestGlobs = DEFAULT_MANIFEST_GLOBS,
+  canonicalDockerfile,
+  crossRepoManifest,
+} = {}) {
+  const toolchain = supplyChainServices(root, canonicalDockerfile);
+  const vendoring = vendoringServices(root, crossRepoManifest);
+  const members = {};
+  const excluded = {};
+  for (const manifestPath of trackedManifests(root, manifestGlobs)) {
+    const manifest = JSON.parse(readFileSync(join(root, manifestPath), 'utf8'));
+    const biomeId = manifest.xema?.id;
+    if (typeof biomeId !== 'string' || biomeId.length === 0) throw new Error(`${manifestPath}: no biome id`);
+    for (const component of manifest.xema?.components ?? []) {
+      if (component.kind !== 'service' || component.scheduler !== 'platform') continue;
+      const artifactPath = component.artifact?.path;
+      if (typeof artifactPath !== 'string') {
+        throw new Error(`${manifestPath}: service "${component.key}" has no artifact.path`);
+      }
+      const directory = posix.normalize(posix.join(posix.dirname(manifestPath), artifactPath));
+      const key = `${biomeId}/${component.key}`;
+      const mainTs = join(root, directory, 'src', 'main.ts');
+      if (!existsSync(mainTs)) throw new Error(`${key}: ${directory}/src/main.ts does not exist`);
+      let reason;
+      if (existsSync(join(root, directory, 'Dockerfile'))) reason = ExclusionReason.OwnDockerfile;
+      else if (vendoring.has(component.key)) reason = ExclusionReason.VendoredInputs;
+      else if (toolchain.has(component.key)) reason = ExclusionReason.ImageToolchain;
+      else if (!isComposableEntry(readFileSync(mainTs, 'utf8'))) reason = ExclusionReason.EntryShape;
+      if (reason === undefined) members[key] = directory;
+      else excluded[key] = reason;
+    }
+  }
+  if (Object.keys(members).length === 0) {
+    throw new Error('no composable platform service found — an empty composed image is never correct');
+  }
+  return { members: sortKeys(members), excluded: sortKeys(excluded) };
+}
+
+/** The image's `image-build-inputs.json`: exactly `{ "workspacePackages": [<member directory>, …] }`. */
+export function renderImageBuildInputs({ members }) {
+  return `${JSON.stringify({ workspacePackages: [...new Set(Object.values(members))].sort() }, null, 2)}\n`;
+}
+
+/** `--write` writes the derived declaration; `--check` throws when the committed one differs. */
+export function syncImageBuildInputs({ mode, root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR, ...deriveOptions }) {
+  if (mode !== 'write' && mode !== 'check') throw new Error(`mode must be write or check, got "${mode}"`);
+  const derived = deriveComposedMembers({ root, ...deriveOptions });
+  const rendered = renderImageBuildInputs(derived);
+  const relativeTarget = posix.join(imageDir, IMAGE_BUILD_INPUTS_FILE);
+  const target = join(root, relativeTarget);
+  if (mode === 'write') writeFileSync(target, rendered);
+  else if ((existsSync(target) ? readFileSync(target, 'utf8') : '') !== rendered) {
+    throw new Error(
+      `${relativeTarget} is stale — the composed image would not carry exactly the composable services. ` +
+        'Run: xema-composed-image members --write (with the same options)',
+    );
+  }
+  return { ...derived, target: relativeTarget };
+}
+
+// ── the image build ─────────────────────────────────────────────────────────
+
+/** The `<biomeId>/<componentKey>` of the one service whose artifact is `directory`. */
+function memberKey(root, directory) {
+  for (let dir = dirname(directory); dir !== '.' && dir !== dirname(dir); dir = dirname(dir)) {
+    const manifestPath = join(root, dir, 'xema-biome.json');
+    if (!existsSync(manifestPath)) continue;
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    const matches = (manifest.xema?.components ?? []).filter(
+      (component) =>
+        component.kind === 'service' &&
+        typeof component.artifact?.path === 'string' &&
+        posix.normalize(posix.join(dir, component.artifact.path)) === directory,
+    );
+    if (matches.length !== 1) {
+      throw new Error(`${dir}/xema-biome.json declares ${matches.length} service(s) at ${directory}, not exactly one`);
+    }
+    return `${manifest.xema.id}/${matches[0].key}`;
+  }
+  throw new Error(`no biome manifest above ${directory}`);
+}
+
+/** `[key, directory]` for every member the committed declaration names. */
+export function readMembers({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR } = {}) {
+  const inputs = join(root, imageDir, IMAGE_BUILD_INPUTS_FILE);
+  const directories = JSON.parse(readFileSync(inputs, 'utf8')).workspacePackages ?? [];
+  if (directories.length === 0) throw new Error(`${inputs} declares no workspacePackages`);
+  return directories.map((directory) => [memberKey(root, directory), directory]);
+}
+
+function packageName(root, directory) {
+  const manifest = JSON.parse(readFileSync(join(root, directory, 'package.json'), 'utf8'));
+  if (typeof manifest.name !== 'string') throw new Error(`${directory}/package.json has no name`);
+  return manifest.name;
+}
+
+/** The pnpm `--filter <package>...` arguments covering every member's closure. */
+export function memberFilters(options = {}) {
+  const root = options.root ?? process.cwd();
+  return readMembers(options).map(([, directory]) => `--filter ${packageName(root, directory)}...`);
+}
+
+/** The registry packages (`name@version`) a v9 lockfile's `packages:` section pins. */
+export function registryPins(lockfilePath) {
+  const lines = readFileSync(lockfilePath, 'utf8').split('\n');
+  if (lines[0] !== "lockfileVersion: '9.0'") {
+    throw new Error(`${lockfilePath} is not a v9 lockfile (first line "${lines[0]}")`);
+  }
+  const start = lines.indexOf('packages:');
+  if (start === -1) throw new Error(`${lockfilePath} has no packages: section`);
+  const pins = new Set();
+  for (const line of lines.slice(start + 1)) {
+    if (/^\S/.test(line)) break;
+    const key = /^ {2}(\S.*):$/.exec(line)?.[1];
+    if (key === undefined) continue;
+    const unquoted = key.replace(/^'(.*)'$/, '$1');
+    // Workspace packages an injected install adds are `file:` entries, not registry pins.
+    if (!/@file:/.test(unquoted)) pins.add(unquoted);
+  }
+  return pins;
+}
+
+/** Refuse a re-resolved `<root>/pnpm-lock.yaml` that pins a registry package the committed lockfile does not. */
+export function assertPinsUnchanged({ root = process.cwd(), committedLockfile }) {
+  if (committedLockfile === undefined) throw new Error('pins needs the committed lockfile path');
+  const committed = registryPins(committedLockfile);
+  const added = [...registryPins(join(root, 'pnpm-lock.yaml'))].filter((pin) => !committed.has(pin));
+  if (added.length > 0) {
+    throw new Error(
+      `the injected re-resolution pinned registry package(s) the committed lockfile does not:\n${added
+        .map((pin) => `  - ${pin}`)
+        .join('\n')}`,
+    );
+  }
+  return committed.size;
+}
+
+function resolveFrom(root, directory, specifier) {
+  try {
+    return realpathSync(createRequire(join(root, directory, 'package.json')).resolve(specifier));
+  } catch (error) {
+    if (error?.code === 'MODULE_NOT_FOUND') return undefined;
+    throw error;
+  }
+}
+
+function packageRoot(file, name) {
+  for (let dir = dirname(file); dir !== dirname(dir); dir = dirname(dir)) {
+    const manifest = join(dir, 'package.json');
+    if (existsSync(manifest) && JSON.parse(readFileSync(manifest, 'utf8')).name === name) return dir;
+  }
+  throw new Error(`no ${name} package root above ${file}`);
+}
+
+/** Write the member index and the host link; returns the host bin path. */
+export function writeMemberIndex({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR, commit, buildSourceRepository }) {
+  if (!COMMIT.test(commit ?? '')) throw new Error(`index needs the exact 40-hex build commit, got "${commit}"`);
+  if (typeof buildSourceRepository !== 'string' || buildSourceRepository.length === 0) {
+    throw new Error("index needs --build-source: the repository its subjects name in the image lock (their 'repo')");
+  }
+  const members = readMembers({ root, imageDir });
+  const problems = [];
+  const entries = {};
+  const identity = new Map();
+  for (const [key, directory] of members) {
+    const entry = `${directory}/dist/main.js`;
+    if (!existsSync(join(root, entry))) problems.push(`${key}: built entry ${entry} does not exist`);
+    entries[key] = { entry };
+    for (const specifier of IDENTITY_PACKAGES) {
+      const resolved = resolveFrom(root, directory, specifier);
+      if (resolved === undefined) {
+        // A member that does not depend on a package shares nothing that could
+        // be a second copy — except the host itself, which every member needs.
+        if (specifier === SDK) problems.push(`${key}: does not resolve ${SDK}`);
+        continue;
+      }
+      const seen = identity.get(specifier);
+      if (seen === undefined) identity.set(specifier, { resolved, key });
+      else if (seen.resolved !== resolved) {
+        problems.push(`${key} resolves ${specifier} at ${resolved}, ${seen.key} at ${seen.resolved}`);
+      }
+    }
+  }
+  if (problems.length > 0) {
+    throw new Error(`the composed image cannot carry its members:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+  }
+  const document = { schemaVersion: 1, buildSource: { repository: buildSourceRepository, commit }, members: entries };
+  // Graded by the kernel's own schema, resolved through the members' module graph.
+  const { ComposedProcessMemberIndexSchema } = createRequire(join(root, members[0][1], 'package.json'))(
+    '@xemahq/contracts/process-topology',
+  );
+  ComposedProcessMemberIndexSchema.parse(document);
+  writeFileSync(join(root, MEMBER_INDEX_FILE), `${JSON.stringify(document, null, 2)}\n`);
+
+  const sdkRoot = packageRoot(identity.get(SDK).resolved, SDK);
+  const bin = JSON.parse(readFileSync(join(sdkRoot, 'package.json'), 'utf8')).bin?.[HOST_LINK];
+  if (typeof bin !== 'string') throw new Error(`${SDK} at ${sdkRoot} ships no "${HOST_LINK}" bin`);
+  // Relative to the REAL root: the SDK path is a realpath, and a root reached through a
+  // symlink (macOS /var, a bind mount) would otherwise yield a link that escapes it.
+  symlinkSync(relative(realpathSync(root), join(sdkRoot, bin)), join(root, HOST_LINK));
+  return { members: members.length, host: join(sdkRoot, bin) };
+}
+
+/** Every member's module graph loads, through the host's own entry reader. */
+export function loadMembers({ root = process.cwd(), imageDir = COMPOSED_IMAGE_DIR } = {}) {
+  const members = readMembers({ root, imageDir });
+  const problems = [];
+  for (const [key, directory] of members) {
+    try {
+      createRequire(join(root, directory, 'package.json'))(SDK).readServiceEntry(join(root, directory, 'dist', 'main.js'), {});
+    } catch (error) {
+      problems.push(`${key}: ${error?.message ?? String(error)}`);
+    }
+  }
+  if (problems.length > 0) {
+    throw new Error(
+      `${problems.length} of ${members.length} member(s) do not load:\n${problems.map((p) => `  - ${p}`).join('\n')}`,
+    );
+  }
+  return members.length;
+}
+
+// ── the bin ─────────────────────────────────────────────────────────────────
+
+const USAGE =
+  'usage: xema-composed-image <command> [--root <dir>] [--image-dir <dir>]\n' +
+  '  members --write|--check [--manifests <glob>]… [--canonical-dockerfile <path>] [--cross-repo-manifest <path>]\n' +
+  '  filters | dirs | pins <committed-lockfile> | index <commit> --build-source <repo> | load\n' +
+  '  coordinate --image-name <name>   (env: SHA REGISTRY REGISTRY_ORG REGISTRY_USER REGISTRY_TOKEN [TAG_ARGS_FILE])\n' +
+  '  smoke-refusal <image> [--member <biomeId>/<componentKey>]x2\n' +
+  '  dockerfile --write|--check --tooling-version <x.y.z> --copy <dir>… --cache-id <id> --build-source <repo>';
+
+const REPEATABLE = new Set(['manifests', 'copy', 'member']);
+const VALUED = new Set(['root', 'image-dir', 'manifests', 'canonical-dockerfile', 'cross-repo-manifest', 'build-source',
+  'image-name', 'tooling-version', 'cache-id', 'copy', 'member',
+]);
+
+export function parseArguments(argv) {
+  const positional = [];
+  const options = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--write' || arg === '--check') {
+      options.mode = arg.slice(2);
+      continue;
+    }
+    if (!arg.startsWith('--')) {
+      positional.push(arg);
+      continue;
+    }
+    const name = arg.slice(2);
+    const value = argv[i + 1];
+    if (!VALUED.has(name)) throw new Error(`unknown option ${arg}\n${USAGE}`);
+    if (value === undefined || value.startsWith('--')) throw new Error(`${arg} needs a value`);
+    i += 1;
+    if (REPEATABLE.has(name)) (options[name] ??= []).push(value);
+    else options[name] = value;
+  }
+  return { command: positional[0], argument: positional[1], options };
+}
+
+export function main(argv, { log = console.log, write = (text) => process.stdout.write(text) } = {}) {
+  const { command, argument, options } = parseArguments(argv);
+  const root = resolve(options.root ?? process.cwd());
+  const imageDir = options['image-dir'] ?? COMPOSED_IMAGE_DIR;
+  switch (command) {
+    case 'members': {
+      const result = syncImageBuildInputs({
+        mode: options.mode,
+        root,
+        imageDir,
+        manifestGlobs: options.manifests ?? DEFAULT_MANIFEST_GLOBS,
+        canonicalDockerfile: options['canonical-dockerfile'],
+        crossRepoManifest: options['cross-repo-manifest'],
+      });
+      for (const [key, reason] of Object.entries(result.excluded)) log(`  excluded ${key}: ${reason}`);
+      log(
+        `composed-process members: ${Object.keys(result.members).length} carried, ` +
+          `${Object.keys(result.excluded).length} excluded (${result.target} ${options.mode === 'write' ? 'written' : 'current'})`,
+      );
+      return;
+    }
+    case 'filters':
+      write(`${memberFilters({ root, imageDir }).join(' ')}\n`);
+      return;
+    case 'dirs':
+      write(`${readMembers({ root, imageDir }).map(([, directory]) => directory).join('\n')}\n`);
+      return;
+    case 'pins': {
+      const count = assertPinsUnchanged({ root, committedLockfile: argument });
+      log(`composed install: every registry pin is the committed lockfile's (${count})`);
+      return;
+    }
+    case 'index': {
+      const result = writeMemberIndex({ root, imageDir, commit: argument, buildSourceRepository: options['build-source'] });
+      log(`composed member index: ${result.members} member(s) at ${argument}; host ${result.host}`);
+      return;
+    }
+    case 'load':
+      log(`composed members: all ${loadMembers({ root, imageDir })} module graph(s) load`);
+      return;
+    case 'coordinate':
+      return composedCoordinate({ root, imageDir, imageName: options['image-name'] }).then((outputs) =>
+        emitCoordinate(outputs, { log }),
+      );
+    case 'smoke-refusal':
+      runRefusalSmoke({ image: argument, members: options.member, log, write });
+      return;
+    case 'dockerfile': {
+      const target = syncComposedDockerfile({
+        mode: options.mode,
+        root,
+        imageDir,
+        toolingVersion: options['tooling-version'],
+        copy: options.copy,
+        cacheId: options['cache-id'],
+        buildSource: options['build-source'],
+      });
+      log(`composed Dockerfile ${target} ${options.mode === 'write' ? 'written' : 'current'}`);
+      return;
+    }
+    default:
+      throw new Error(USAGE);
+  }
+}
+
+const invokedPath = process.argv[1] ? realpathSync(process.argv[1]) : undefined;
+if (invokedPath !== undefined && import.meta.url === pathToFileURL(invokedPath).href) {
+  try {
+    await main(process.argv.slice(2));
+    // A loaded member graph may hold handles its modules opened at evaluation;
+    // the verdict is in, so the step ends here rather than on their timers.
+    process.exit(0);
+  } catch (error) {
+    console.error(`xema-composed-image: ${error.message}`);
+    process.exit(1);
+  }
+}