@starci/hfs 4.12.2 → 4.13.2

package/sync/format.mjs

@@ -1,8 +1,12 @@
 // format.mjs - HFS_FORMAT (R19): Prettier is the only formatter, and every tracked file it formats is formatted.
 // The check is `prettier --check` over the tracked files through the repository's OWN prettier (resolved from the repository,
 // with the repository's prettier config and .prettierignore), so it judges what the repository's pre-commit and CI judge. A
-// repository with no installed prettier is a refusal (HFS_FORMAT_TOOL_MISSING), never a pass. It is slow and is not part of `--fast`.
+// repository with no installed prettier is a refusal (HFS_FORMAT_TOOL_MISSING), never a pass. Prettier runs in batches: the files are cut into
+// batches of FORMAT_BATCH, and a long list is spread over worker threads that each load the repository's prettier once (one process or one
+// config lookup per file was 16 of the 35 minutes of a full app check). Configuration is resolved once per directory, not once per file.
+import os from 'node:os';
 import { createRequire } from 'node:module';
+import { Worker } from 'node:worker_threads';
 import fs from 'node:fs';
 import path from 'node:path';
 import { SyncError } from './index.mjs';
@@ -20,14 +24,21 @@ export function loadPrettier(repoRoot) {
         throw new SyncError('HFS_FORMAT_TOOL_MISSING', `prettier is not installed under ${repoRoot}; install the version knowledge/hfs/canon-pins.yaml pins, so the format check judges what the repository's own gates judge`);
     }
 }
+/** Files per batch: one message to a worker, one progress step. */
+export const FORMAT_BATCH = 64;
+/** Fewer files than this run in this thread: starting workers would cost more than it saves. */
+const WORKER_MIN_FILES = 256;
+/** The formattable files of `files`: lockfiles are written by npm and never formatted. */
+export const formattable = (files) => files.filter((f) => !LOCKFILES.has(path.posix.basename(f)));
 /**
- * The HFS_FORMAT findings over the tracked `files` of `repoRoot`: one per file prettier would change, or cannot parse.
- * `prettier` is a seam for specs; the default is the repository's own.
+ * The HFS_FORMAT findings of one batch of `files`, in this thread. The ignore file is read by prettier once per call and the configuration is
+ * resolved with prettier's own cache, so a batch costs one lookup per directory.
  */
-export async function formatFindings({ repoRoot, files, prettier = loadPrettier(repoRoot) }) {
+export async function checkBatch({ repoRoot, files, prettier }) {
     const ignorePath = path.join(repoRoot, IGNORE_FILE);
+    const ignoreFile = fs.existsSync(ignorePath) ? ignorePath : undefined;
     const findings = [];
-    for (const file of files.filter((f) => !LOCKFILES.has(path.posix.basename(f)))) {
+    for (const file of formattable(files)) {
         const absolute = path.join(repoRoot, file);
         let text;
         try {
@@ -36,10 +47,10 @@ export async function formatFindings({ repoRoot, files, prettier = loadPrettier(
         catch {
             continue;
         }
-        const info = await prettier.getFileInfo(absolute, { ignorePath: fs.existsSync(ignorePath) ? ignorePath : undefined, resolveConfig: true });
+        const info = await prettier.getFileInfo(absolute, { ignorePath: ignoreFile, resolveConfig: true });
         if (info.ignored || !info.inferredParser)
             continue;
-        const options = (await prettier.resolveConfig(absolute, { editorconfig: true, useCache: false })) ?? {};
+        const options = (await prettier.resolveConfig(absolute, { editorconfig: true, useCache: true })) ?? {};
         try {
             if (!(await prettier.check(text, { ...options, filepath: absolute })))
                 findings.push({ code: FORMAT, level: 'error', path: file, message: `${file} is not formatted by prettier; run \`npm run format\`` });
@@ -50,3 +61,84 @@ export async function formatFindings({ repoRoot, files, prettier = loadPrettier(
     }
     return findings;
 }
+/** Cuts `files` into batches of `size`. */
+export function batches(files, size = FORMAT_BATCH) {
+    const out = [];
+    for (let i = 0; i < files.length; i += size)
+        out.push(files.slice(i, i + size));
+    return out;
+}
+/** How many worker threads a list of `count` files gets: none below WORKER_MIN_FILES, else up to the cores left over, at most 8. */
+export function workerCount(count, cores = os.availableParallelism()) {
+    if (count < WORKER_MIN_FILES)
+        return 0;
+    return Math.max(0, Math.min(8, cores - 1, Math.ceil(count / (FORMAT_BATCH * 2))));
+}
+function inWorkers({ repoRoot, files, workers, onProgress }) {
+    const queue = batches(files);
+    const findings = [];
+    let done = 0;
+    return new Promise((resolve, reject) => {
+        let running = 0;
+        let failed = false;
+        const pool = [];
+        const next = (worker) => {
+            const batch = queue.shift();
+            if (batch === undefined) {
+                void worker.terminate();
+                if (running === 0 && !failed)
+                    resolve(findings);
+                return;
+            }
+            running += 1;
+            worker.postMessage({ repoRoot, files: batch });
+        };
+        const fail = (error) => {
+            if (failed)
+                return;
+            failed = true;
+            for (const worker of pool)
+                void worker.terminate();
+            reject(error instanceof Error ? error : new Error(String(error)));
+        };
+        for (let i = 0; i < workers; i += 1) {
+            const worker = new Worker(new URL('./format-worker.mjs', import.meta.url));
+            pool.push(worker);
+            worker.on('message', (message) => {
+                if (message.error !== undefined) {
+                    fail(message.code === 'HFS_FORMAT_TOOL_MISSING' ? new SyncError('HFS_FORMAT_TOOL_MISSING', message.error) : new Error(message.error));
+                    return;
+                }
+                running -= 1;
+                findings.push(...(message.findings ?? []));
+                done += message.count ?? 0;
+                onProgress?.(done);
+                next(worker);
+            });
+            worker.on('error', fail);
+            next(worker);
+        }
+    });
+}
+/**
+ * The HFS_FORMAT findings over the tracked `files` of `repoRoot`: one per file prettier would change, or cannot parse, sorted by path.
+ * `prettier` is a seam for specs (and keeps the run in this thread); the default is the repository's own, in worker threads for a long list.
+ */
+export async function formatFindings({ repoRoot, files, prettier, onProgress }) {
+    const list = formattable(files);
+    const mine = prettier ?? loadPrettier(repoRoot);
+    const workers = prettier === undefined ? workerCount(list.length) : 0;
+    let findings;
+    if (workers > 0)
+        findings = await inWorkers({ repoRoot, files: list, workers, onProgress });
+    else {
+        findings = [];
+        let done = 0;
+        for (const batch of batches(list)) {
+            findings.push(...await checkBatch({ repoRoot, files: batch, prettier: mine }));
+            done += batch.length;
+            onProgress?.(done);
+        }
+    }
+    return findings.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}

package/sync/index.d.mts

@@ -1,6 +1,7 @@
 import { type RepoView } from '../runtime/scripts/hfs/slots.mjs';
 import type { AppRepo } from '../runtime/scripts/hfs/slot-app-view.mjs';
 import type { Slot, SlotManifest } from '../runtime/scripts/hfs/manifest-shape.mjs';
+import type { ImageApp } from './stack-images.mjs';
 export declare const TEMPLATES_DIR: string;
 /** The scopes a target is rendered for: the app root, then each side. */
 export declare const SCOPES: readonly string[];
@@ -180,12 +181,8 @@ export declare function jestCoverageSource(coverage: {
 export declare function appScripts(app: ResolvedApp, source: Partial<Pick<AppSourceFacts, 'hasImage'>> | undefined): string;
 /** The stylesheets of the fe side the CSS canon judges, relative to fe/: every app and every workspace package (slot fe.route, fe.package.*). */
 export declare const STYLE_GLOB = "{apps,packages}/*/src/**/*.css";
-/**
- * The build matrix of the images workflow: one entry per declared app (be then fe, then a lite app's db image), each with the image name and its Dockerfile. The workflow
- * runs on the release tag, so every image is built there; no path filter narrows it. A YAML block mapping per entry, indented for
- * `strategy.matrix.include`.
- */
-export declare function imageMatrix(app: ResolvedApp, source: Partial<Pick<AppSourceFacts, 'hasImage'>> | undefined): string;
+/** The apps images.yml builds (one matrix entry per declared app): name and Dockerfile, be then fe, then a lite app's db image. */
+export declare function imageApps(app: ResolvedApp, source: Partial<Pick<AppSourceFacts, 'hasImage'>> | undefined): ImageApp[];
 /**
  * The Dockerfile of every declared app, [{ path, content }] (app-relative): written once by starci app scaffold from templates/<side>/image/<kind>
  * and then the app's own, judged by the docker rules (R187-R191). A Next image copies the fe packages only when the fe side opts into

package/sync/index.mjs

@@ -335,15 +335,10 @@ function imageEntries(app, source) {
     const frontend = app.sides.fe.apps.filter(entry => app.edition !== 'lite' || source?.hasImage?.(dockerfilePath('fe', entry.name)));
     return [...app.sides.be.apps.map((entry) => ({ side: 'be', entry })), ...frontend.map((entry) => ({ side: 'fe', entry }))];
 }
-/**
- * The build matrix of the images workflow: one entry per declared app (be then fe, then a lite app's db image), each with the image name and its Dockerfile. The workflow
- * runs on the release tag, so every image is built there; no path filter narrows it. A YAML block mapping per entry, indented for
- * `strategy.matrix.include`.
- */
-export function imageMatrix(app, source) {
-    const entry = (side, item) => `          - name: ${item.name}\n            file: ${dockerfilePath(side, item.name)}`;
-    const db = app.edition === 'lite' ? [`          - name: ${DB_IMAGE_APP}\n            file: ${DB_DOCKERFILE}`] : [];
-    return [...imageEntries(app, source).map(image => entry(image.side, image.entry)), ...db].join('\n');
+/** The apps images.yml builds (one matrix entry per declared app): name and Dockerfile, be then fe, then a lite app's db image. */
+export function imageApps(app, source) {
+    const db = app.edition === 'lite' ? [{ name: DB_IMAGE_APP, file: DB_DOCKERFILE }] : [];
+    return [...imageEntries(app, source).map(image => ({ name: image.entry.name, file: dockerfilePath(image.side, image.entry.name) })), ...db];
 }
 /** The Dockerfile of the app a deploy image names (be first, then fe, then a lite app's db image); an app hfs.json does not declare cannot be built by the managed workflow. */
 function stackDockerfile(app, name) {
@@ -354,6 +349,12 @@ function stackDockerfile(app, name) {
         throw new SyncError('HFS_SYNC_STACK_IMAGE', `deploy.images names the app ${name}, which hfs.json does not declare under be or fe`);
     return dockerfilePath(side, name);
 }
+/** The apps images.yml builds; every deploy image must name one of them (an app hfs.json does not declare cannot be built by the managed workflow). */
+function deployableApps(app, source, stack) {
+    for (const image of stack.images)
+        stackDockerfile(app, image.app);
+    return imageApps(app, source);
+}
 const IMAGE_TEMPLATE = Object.freeze({ api: 'be/image/api', worker: 'be/image/worker', cli: 'be/image/cli', next: 'fe/image/next' });
 /**
  * The Dockerfile of every declared app, [{ path, content }] (app-relative): written once by starci app scaffold from templates/<side>/image/<kind>
@@ -427,9 +428,7 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
         styleGlob: STYLE_GLOB,
         grammarLintImport: grammarLint?.package ? `import { ${grammarLint.factory} } from "${grammarLint.package}"` : '',
         grammarLintExport: grammarLint?.package ? `export default [...starciFeConfig({ hfs }), ...${grammarLint.factory}({ hfs })]` : 'export default starciFeConfig({ hfs })',
-        imageMatrix: imageMatrix(app, source),
-        imageProject: app.project,
-        ...stackWorkflowVariables(stack, app.project, (name) => stackDockerfile(app, name)),
+        ...stackWorkflowVariables(stack, app.project, deployableApps(app, source, stack), String(NODE_MAJOR)),
     };
 }
 // The scripts of a package.json as one comparable text: a line per script, sorted by name (order is not drift).
@@ -600,6 +599,7 @@ const LITE_RETIRED_DIRS = Object.freeze(['supabase/types']);
 /** The files a lite app's sync retires, each with the reason the dry run prints. */
 const LITE_RETIRED_FILES = Object.freeze({
     [RETIRED_DB_DOCKERFILE]: `the db image moved to ${DB_DOCKERFILE} (ruling lite-db-image-in-stacks)`,
+    '.github/workflows/db-deploy.yml': 'the stack deploy migrates the database (a verified backup, the expand migrations before the services, the contract migrations after the accept; ruling app-cicd-auto-deploy)',
 });
 /** Why a retired file goes: a retired file's own reason, else the folder's. */
 const retiredReason = (file) => LITE_RETIRED_FILES[file] ?? 'the lite edition generates no database types';

package/sync/stack-images.d.mts

@@ -1,16 +1,26 @@
 type Declaration = any;
 type ParseYaml = (text: string) => Declaration;
-/** One image of the declaration: the service, its app and whether it carries build arguments. */
+/** One image of the declaration: the service, its app, whether it carries build arguments and whether those open a sealed member. */
 export interface StackImage {
     service: string;
     app: string;
     buildArgs: boolean;
+    sealed?: boolean;
 }
-/** What the managed workflows render from the declaration. */
+/** One environment that deploys: the deploy.auto, deploy.approval and deploy.platforms keys of its deploy block. */
+export interface DeployEnvironment {
+    name: string;
+    auto: boolean;
+    approval: 'none' | 'reviewers';
+    platforms: string[];
+}
+/** What the managed workflows render from the declaration. `environments` are the deploying ones in declared order; `imageCache` is ci.imageCache. */
 export interface DeclaredStack {
     images: StackImage[];
     passEnv: string[];
     imageEnvironments?: Record<string, string[]>;
+    environments?: DeployEnvironment[];
+    imageCache?: 'gha' | 'registry';
 }
 /**
  * What the managed workflows render from the declaration at `root`: { images, passEnv, imageEnvironments } (empty when the app has no
@@ -21,16 +31,21 @@ export declare function readDeclaredStack(root: string, { parseYaml }?: {
 }): DeclaredStack;
 /** Parsed declarations share the exact image, environment and pass-env projection used by sync. */
 export declare function declaredStack(declaration: Declaration): DeclaredStack;
+/** An app the images workflow builds: its Dockerfile. */
+export interface ImageApp {
+    name: string;
+    file: string;
+}
 /**
- * The text blocks the stack-deploy.yml template places at the end of a line (each already indented for its position, every line led by
- * a newline; empty when there is nothing to place):
- *   stackGuard       the first step of the release job when the app declares no image (it fails with the reason)
- *   stackNames       the `names` step lines assigning each image repository (ghcr.io/<lowercase owner>/<project>-<app>)
- *   stackImageSteps  per image: the optional build-args step and the build-and-push step
- *   stackImageEnv    the env entries of the deploy step: IMAGE_<SERVICE> = repository@digest
+ * The text blocks the managed workflows place at the end of a line or on a line of their own (empty when there is nothing to place):
+ *   stackGuard       the first step of the deploy job when the app declares no image (it fails with the reason)
+ *   stackImageList   the `<service> <app>` lines the image step of stack-deploy.yml reads (the registry holds sha-<sha> of each)
+ *   stackImageEnv    the env entries of the deploy step: IMAGE_<SERVICE> = repository@digest, from the image step
  *   stackImageArgs   the `--image "<service>=$IMAGE_<SERVICE>" \` continuation lines of the deploy command
  *   stackPassEnv     the env entries of the deploy step for the declared host variables (vars.<NAME>)
- * `dockerfileOf(app)` names the Dockerfile of an app (the sync module knows the layout).
+ *   imageJobs, imageWorkflowOutputs   the build and collect jobs and the output of images.yml
+ *   ciDeployJobs     the deploy jobs of ci.yml (one per environment with deploy.auto)
+ * `apps` are the apps images.yml builds, each with its Dockerfile (the sync module knows the layout).
  */
-export declare function stackWorkflowVariables({ images, passEnv, imageEnvironments: environments }: DeclaredStack, project: string, dockerfileOf: (app: string) => string): Record<string, string>;
+export declare function stackWorkflowVariables({ images, passEnv, imageEnvironments: environments, environments: deploying, imageCache }: DeclaredStack, project: string, apps?: readonly ImageApp[], nodeMajor?: string): Record<string, string>;
 export {};

package/sync/stack-images.mjs

@@ -17,13 +17,15 @@ const CONTINUE = '\\';
 const NO_IMAGES_MESSAGE = 'no image is declared: declare environments.<env>.deploy (with images) in .starcistacks/application-stacks.yaml before running this workflow';
 const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value); // reason: a YAML mapping
 const hasBuildArgs = (args) => record(args) && (Object.keys(record(args.values) ? args.values : {}).length > 0 || record(args.sealed));
+const PLATFORM = /^linux\/(?:amd64|arm64)$/u;
+const DEFAULT_PLATFORMS = ['linux/amd64'];
 function environmentImages(environment) {
     const images = environment?.deploy?.images;
     if (!record(images))
         return [];
     return Object.entries(images)
         .filter(([service, entry]) => NAME.test(service) && record(entry) && NAME.test(String(entry.app)))
-        .map(([service, entry]) => ({ service, app: entry.app, buildArgs: hasBuildArgs(entry.buildArgs) }));
+        .map(([service, entry]) => ({ service, app: entry.app, buildArgs: hasBuildArgs(entry.buildArgs), sealed: record(entry.buildArgs) && record(entry.buildArgs.sealed) }));
 }
 /**
  * The images of a parsed declaration, [{ service, app, buildArgs }] sorted by service: the union over its environments (the first
@@ -34,7 +36,7 @@ function declaredStackImages(declaration) {
     for (const environment of Object.values(record(declaration?.environments) ? declaration.environments : {})) {
         for (const image of environmentImages(environment)) {
             const known = byService.get(image.service);
-            byService.set(image.service, known ? { ...known, buildArgs: known.buildArgs || image.buildArgs } : image);
+            byService.set(image.service, known ? { ...known, buildArgs: known.buildArgs || image.buildArgs, sealed: Boolean(known.sealed || image.sealed) } : image);
         }
     }
     return [...byService.values()].sort((a, b) => byCodeUnit(a.service, b.service));
@@ -52,6 +54,16 @@ function imageEnvironments(declaration) {
         .filter(([name, environment]) => NAME.test(name) && environmentImages(environment).length > 0)
         .map(([name, environment]) => [name, environmentImages(environment).map(image => image.app)]));
 }
+/** The environments that carry a deploy block, in declared order, with the auto, approval and platforms keys (defaults: manual, no reviewers, linux/amd64). */
+function deployEnvironments(declaration) {
+    return Object.entries(record(declaration?.environments) ? declaration.environments : {})
+        .filter(([name, environment]) => NAME.test(name) && record(environment?.deploy))
+        .map(([name, environment]) => {
+        const deploy = environment.deploy;
+        const platforms = Array.isArray(deploy.platforms) ? deploy.platforms.filter((value) => typeof value === 'string' && PLATFORM.test(value)) : [];
+        return { name, auto: deploy.auto === true, approval: deploy.approval === 'reviewers' ? 'reviewers' : 'none', platforms: platforms.length ? platforms : DEFAULT_PLATFORMS };
+    });
+}
 /**
  * What the managed workflows render from the declaration at `root`: { images, passEnv, imageEnvironments } (empty when the app has no
  * declaration, no deploy block or a declaration that does not parse; `starci app check` judges those). `parseYaml(text)` is injected.
@@ -71,78 +83,227 @@ export function readDeclaredStack(root, { parseYaml = bundledParseYaml } = {}) {
 }
 /** Parsed declarations share the exact image, environment and pass-env projection used by sync. */
 export function declaredStack(declaration) {
-    return { images: declaredStackImages(declaration), passEnv: declaredPassEnv(declaration), imageEnvironments: imageEnvironments(declaration) };
+    const cache = declaration?.ci?.imageCache;
+    return { images: declaredStackImages(declaration), passEnv: declaredPassEnv(declaration), imageEnvironments: imageEnvironments(declaration), environments: deployEnvironments(declaration), imageCache: cache === 'registry' ? 'registry' : 'gha' };
 }
 const envName = (service) => `IMAGE_${service.toUpperCase().replaceAll('-', '_')}`;
 /** Lines placed at the end of a template line: each one starts with a newline, so nothing declared leaves nothing, not even a blank line. */
 const block = (items, indent = INDENT) => items.map(item => `\n${indent}${item}`).join('');
-function buildArgsStep(image) {
-    return [
-        `- name: public build values of ${image.service}`,
-        `  id: args-${image.service}`,
-        '  env:',
-        '    SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}',
-        `  run: npx --no-install starci app stack build-args --env "$STACK_ENVIRONMENT" --app ${image.app}`,
-    ];
+/** Lines of a block placed on a line of their own, each indented (an empty list is the empty string). */
+const lines = (items, indent) => items.map(item => (item === '' ? '' : `${indent}${item}`)).join('\n');
+const CHECKOUT = 'actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0';
+const SETUP_NODE = 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0';
+const SETUP_BUILDX = 'docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0';
+const SETUP_QEMU = 'docker/setup-qemu-action@29109295f81e9208d7d86ff1c6c12d2833863392 # v3.6.0';
+const DOCKER_LOGIN = 'docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0';
+const BUILD_PUSH = 'docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2';
+const INSTALL_SOPS = 'mdgreenwald/mozilla-sops-action@bb2d96a13ef438ad122e5827a57ebd75d6ff118d # v2.1.0';
+const TAG_MATCHES_VERSION = 'node -e "const version=require(\'./package.json\').version;if(process.env.GITHUB_REF_NAME!==\'v\'+version)process.exit(1)"';
+/**
+ * Which of the app's images need build values, and from where. The values of the release environment (the sole image environment, or production
+ * when several deploy images) are the ones an image is built with; an app that environment does not deploy keeps its Dockerfile defaults.
+ */
+function imagePlans(apps, { images, imageEnvironments: environments = {} }) {
+    const selected = new Set(environments[releaseEnvironment(environments)] ?? []);
+    return apps.map((app) => {
+        const own = images.filter(image => image.app === app.name);
+        const args = selected.has(app.name) && own.some(image => image.buildArgs);
+        return { ...app, deployed: own.length > 0, args, sealed: args && own.some(image => image.sealed === true), services: own.map(image => image.service) };
+    });
+}
+const matrixEntries = (plans) => plans.flatMap(plan => [`- name: ${plan.name}`, `  file: ${plan.file}`, `  deployed: ${plan.deployed}`, `  args: ${plan.args}`]);
+/** The platforms every deploying environment needs, the union in a stable order (default linux/amd64: the VPS's architecture). */
+function platformsOf(environments) {
+    const all = new Set(environments.flatMap(environment => environment.platforms));
+    return all.size ? [...all].sort(byCodeUnit) : DEFAULT_PLATFORMS;
+}
+function imageCacheLines(cache) {
+    if (cache === 'registry')
+        return [
+            'cache-from: type=registry,ref=${{ steps.names.outputs.repo }}:buildcache',
+            "cache-to: ${{ inputs.push && format('type=registry,ref={0}:buildcache,mode=max', steps.names.outputs.repo) || '' }}",
+        ];
+    return ['cache-from: type=gha,scope=${{ matrix.name }}', 'cache-to: type=gha,scope=${{ matrix.name }},mode=max'];
 }
-function buildPushStep(image, dockerfile) {
-    return [
-        `- name: build and push ${image.service}`,
-        `  id: build-${image.service}`,
-        '  uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2',
+/** One build job of images.yml: `image` builds with public values and no environment, `image-sealed` opens the sealed build values of the release environment. */
+function imageJob(id, plans, { project, nodeMajor, environment, platforms, cache }) {
+    const sealed = id === 'image-sealed';
+    const qemu = platforms.some(platform => platform !== 'linux/amd64');
+    const head = [
+        `${id}:`,
+        '  timeout-minutes: 30',
+        '  runs-on: ubuntu-latest',
+        ...(sealed ? ['  if: ${{ inputs.release }}', `  environment: ${environment}`] : []),
+        '  permissions:', '    contents: read', '    packages: write',
+        '  strategy:', '    fail-fast: false', '    matrix:', '      include:',
+        ...matrixEntries(plans).map(line => `        ${line}`),
+        '  steps:',
+    ];
+    const steps = [
+        `- uses: ${CHECKOUT}`,
+        '- name: release tag matches package version',
+        '  if: ${{ inputs.release }}',
+        '  shell: bash',
+        '  run: |',
+        '    [[ "$GITHUB_REF" == refs/tags/v* ]] || exit 1',
+        `    ${TAG_MATCHES_VERSION}`,
+        '- name: image repository',
+        '  id: names',
+        '  shell: bash',
+        '  run: |',
+        '    owner="${GITHUB_REPOSITORY_OWNER,,}"',
+        `    echo "repo=ghcr.io/\${owner}/${project}-\${{ matrix.name }}" >> "$GITHUB_OUTPUT"`,
+        ...(qemu ? [`- uses: ${SETUP_QEMU}`] : []),
+        `- uses: ${SETUP_BUILDX}`,
+        `- uses: ${DOCKER_LOGIN}`,
+        '  if: ${{ inputs.push }}',
+        '  with:', '    registry: ghcr.io', '    username: ${{ github.actor }}', '    password: ${{ github.token }}',
+        `- uses: ${SETUP_NODE}`,
+        '  if: ${{ matrix.args }}',
+        '  with:', `    node-version: ${nodeMajor}`, '    cache: npm',
+        '- run: npm ci --ignore-scripts',
+        '  if: ${{ matrix.args }}',
+        ...(sealed ? ['- name: install SOPS', '  if: ${{ matrix.args }}', `  uses: ${INSTALL_SOPS}`, '  with:', '    version: v3.13.2'] : []),
+        '- name: public build values',
+        '  id: args',
+        '  if: ${{ matrix.args }}',
+        '  env:',
+        ...(sealed ? ['    SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}'] : []),
+        '    IMAGE_APP: ${{ matrix.name }}',
+        `  run: npx --no-install starci app stack build-args --env ${environment} --app "$IMAGE_APP"`,
+        `- uses: ${BUILD_PUSH}`,
         '  with:',
         '    context: .',
-        `    file: ${dockerfile}`,
-        '    push: true',
-        '    provenance: false',
-        `    tags: \${{ steps.names.outputs.${image.service} }}:\${{ github.sha }}`,
-        ...(image.buildArgs ? [`    build-args: \${{ steps.args-${image.service}.outputs.args }}`] : []),
-        `    cache-from: type=gha,scope=${image.service}`,
-        `    cache-to: type=gha,scope=${image.service},mode=max`,
+        '    file: ${{ matrix.file }}',
+        '    build-args: ${{ steps.args.outputs.args }}',
+        `    platforms: ${platforms.join(',')}`,
+        '    push: ${{ inputs.push && matrix.deployed }}',
+        // Immutable and per commit; the release name v<version> is added below without a rebuild, so the digest the checks proved is the one that ships.
+        '    tags: ${{ steps.names.outputs.repo }}:sha-${{ github.sha }}',
+        // The SBOM and the provenance are attached to the pushed digest (OCI attestations); a build that is not pushed is only a proof that the Dockerfile builds.
+        '    sbom: true',
+        '    provenance: mode=max',
+        ...imageCacheLines(cache).map(line => `    ${line}`),
+        '- name: tag the release',
+        '  if: ${{ inputs.release && inputs.push && matrix.deployed }}',
+        '  shell: bash',
+        '  env:',
+        '    REPO: ${{ steps.names.outputs.repo }}',
+        '  run: docker buildx imagetools create --tag "$REPO:$GITHUB_REF_NAME" "$REPO:sha-$GITHUB_SHA"',
     ];
+    return lines([...head, ...steps.map(step => `    ${step}`)], '  ');
+}
+/** The collect job: the digests this run pushed under sha-<sha>, as the JSON the deploy takes. The images of sealed build values exist only on a release run. */
+function collectJob(plans, jobs, project) {
+    const waits = jobs.map(job => (job === 'image' ? "needs.image.result == 'success'" : "(needs.image-sealed.result == 'success' || needs.image-sealed.result == 'skipped')"));
+    const list = plans.filter(plan => plan.deployed).flatMap(plan => plan.services.map(service => `${service} ${plan.name} ${plan.sealed}`));
+    return lines([
+        'collect:',
+        `  needs: [${jobs.join(', ')}]`,
+        `  if: \${{ !cancelled() && inputs.push && ${waits.join(' && ')} }}`,
+        '  timeout-minutes: 10',
+        '  runs-on: ubuntu-latest',
+        '  permissions:', '    contents: read', '    packages: read',
+        '  outputs:', '    refs: ${{ steps.refs.outputs.refs }}',
+        '  steps:',
+        `    - uses: ${SETUP_BUILDX}`,
+        `    - uses: ${DOCKER_LOGIN}`,
+        '      with:', '        registry: ghcr.io', '        username: ${{ github.actor }}', '        password: ${{ github.token }}',
+        '    - name: pushed digests',
+        '      id: refs',
+        '      shell: bash',
+        '      env:', '        RELEASE: ${{ inputs.release }}',
+        '      run: |',
+        '        set -euo pipefail',
+        '        owner="${GITHUB_REPOSITORY_OWNER,,}"',
+        "        refs='{}'",
+        '        while read -r service app sealed; do',
+        '          if [[ "$sealed" == true && "$RELEASE" != true ]]; then continue; fi',
+        `          repo="ghcr.io/\${owner}/${project}-\${app}"`,
+        "          digest=$(docker buildx imagetools inspect \"$repo:sha-$GITHUB_SHA\" --format '{{json .Manifest}}' | jq -r .digest)",
+        '          [[ "$digest" =~ ^sha256:[0-9a-f]{64}$ ]] || { echo "::error::no pushed digest for the image of ${service}"; exit 1; }',
+        "          refs=$(jq -c --arg service \"$service\" --arg ref \"$repo@$digest\" '. + {($service): $ref}' <<<\"$refs\")",
+        "        done <<'LIST'",
+        ...list.map(entry => `        ${entry}`),
+        '        LIST',
+        '        echo "refs=$refs" >> "$GITHUB_OUTPUT"',
+    ], '  ');
 }
 /**
- * The text blocks the stack-deploy.yml template places at the end of a line (each already indented for its position, every line led by
- * a newline; empty when there is nothing to place):
- *   stackGuard       the first step of the release job when the app declares no image (it fails with the reason)
- *   stackNames       the `names` step lines assigning each image repository (ghcr.io/<lowercase owner>/<project>-<app>)
- *   stackImageSteps  per image: the optional build-args step and the build-and-push step
- *   stackImageEnv    the env entries of the deploy step: IMAGE_<SERVICE> = repository@digest
+ * The text blocks of images.yml, the reusable workflow ci.yml calls. imageJobs holds the build jobs (public values; sealed values bound to the
+ * release environment, release runs only) and the collect job when an image is deployed; imageWorkflowOutputs the `refs` output of the call.
+ */
+function imageWorkflowVariables(stack, project, apps, nodeMajor, environment) {
+    const plans = imagePlans(apps, stack);
+    const publicPlans = plans.filter(plan => !plan.sealed);
+    const sealedPlans = plans.filter(plan => plan.sealed);
+    const options = { project, nodeMajor, environment, platforms: platformsOf(stack.environments ?? []), cache: stack.imageCache ?? 'gha' };
+    const jobs = [...(publicPlans.length ? ['image'] : []), ...(sealedPlans.length ? ['image-sealed'] : [])];
+    const collect = plans.some(plan => plan.deployed) && jobs.length > 0;
+    return {
+        imageJobs: [
+            ...(publicPlans.length ? [imageJob('image', publicPlans, options)] : []),
+            ...(sealedPlans.length ? [imageJob('image-sealed', sealedPlans, options)] : []),
+            ...(collect ? [collectJob(plans, jobs, project)] : []),
+        ].join('\n\n'),
+        imageWorkflowOutputs: collect ? lines(['outputs:', '  refs:', '    description: JSON object, service -> repository@sha256:digest of the images this run pushed', '    value: ${{ jobs.collect.outputs.refs }}'], '    ') : '',
+        imagesCollected: collect ? 'true' : '',
+    };
+}
+/** The deploy jobs of ci.yml: one call of the reusable stack-deploy.yml per environment with deploy.auto, in declared order, each after the one before it. */
+function ciDeployVariables(stack, collected) {
+    const auto = (stack.environments ?? []).filter(environment => environment.auto);
+    const jobs = auto.map((environment, index) => {
+        const previous = index > 0 ? `, deploy-${auto[index - 1].name}` : '';
+        return lines([
+            `deploy-${environment.name}:`,
+            `  needs: [plan, verdict${collected ? ', images' : ''}${previous}]`,
+            "  if: ${{ needs.plan.outputs.release == 'true' }}",
+            '  permissions:', '    contents: read', '    packages: read', '    actions: read',
+            '  concurrency:', `    group: deploy-${environment.name}`, '    cancel-in-progress: false',
+            '  uses: ./.github/workflows/stack-deploy.yml',
+            '  with:',
+            `    environment: ${environment.name}`,
+            '    operation: deploy',
+            '    auto: true',
+            ...(collected ? ['    images: ${{ needs.images.outputs.refs }}'] : []),
+            '    ci_run: ${{ needs.plan.outputs.ci_run }}',
+        ], '  ');
+    });
+    return { ciDeployJobs: jobs.length ? `\n${jobs.join('\n\n')}\n` : '' };
+}
+/** The release environment: the sole image environment, or production when several deploy images. */
+function releaseEnvironment(environments) {
+    const names = Object.keys(environments);
+    return names.length > 1 ? 'production' : names[0] ?? 'production';
+}
+/**
+ * The text blocks the managed workflows place at the end of a line or on a line of their own (empty when there is nothing to place):
+ *   stackGuard       the first step of the deploy job when the app declares no image (it fails with the reason)
+ *   stackImageList   the `<service> <app>` lines the image step of stack-deploy.yml reads (the registry holds sha-<sha> of each)
+ *   stackImageEnv    the env entries of the deploy step: IMAGE_<SERVICE> = repository@digest, from the image step
  *   stackImageArgs   the `--image "<service>=$IMAGE_<SERVICE>" \` continuation lines of the deploy command
  *   stackPassEnv     the env entries of the deploy step for the declared host variables (vars.<NAME>)
- * `dockerfileOf(app)` names the Dockerfile of an app (the sync module knows the layout).
+ *   imageJobs, imageWorkflowOutputs   the build and collect jobs and the output of images.yml
+ *   ciDeployJobs     the deploy jobs of ci.yml (one per environment with deploy.auto)
+ * `apps` are the apps images.yml builds, each with its Dockerfile (the sync module knows the layout).
  */
-export function stackWorkflowVariables({ images = [], passEnv = [], imageEnvironments: environments = {} }, project, dockerfileOf) {
+export function stackWorkflowVariables({ images = [], passEnv = [], imageEnvironments: environments = {}, environments: deploying = [], imageCache = 'gha' }, project, apps = [], nodeMajor = '22') {
     const guard = images.length ? '' : block([
         '- name: require a declared image',
         '  shell: bash',
         `  run: 'echo "::error::${NO_IMAGES_MESSAGE}"; exit 1'`,
     ]);
-    const names = images.map(image => `echo "${image.service}=ghcr.io/\${owner}/${project}-${image.app}" >> "$GITHUB_OUTPUT"`);
+    const stack = { images, passEnv, imageEnvironments: environments, environments: deploying, imageCache };
+    const image = imageWorkflowVariables(stack, project, apps, nodeMajor, releaseEnvironment(environments));
     return {
-        ...releaseImageVariables(environments),
+        imageEnvironment: releaseEnvironment(environments),
+        ...image,
+        ...ciDeployVariables(stack, image.imagesCollected === 'true'),
         stackGuard: guard,
-        stackNames: block(names, ' '.repeat(10)),
-        stackImageSteps: images.map(image => block([...(image.buildArgs ? buildArgsStep(image) : []), ...buildPushStep(image, dockerfileOf(image.app))])).join(''),
-        stackImageEnv: block(images.map(image => `${envName(image.service)}: \${{ steps.names.outputs.${image.service} }}@\${{ steps.build-${image.service}.outputs.digest }}`), ' '.repeat(10)),
-        stackImageArgs: block(images.map(image => `--image "${image.service}=$${envName(image.service)}" ${CONTINUE}`), ' '.repeat(12)),
+        stackImageList: images.map(entry => `${entry.service} ${entry.app}`).join('\n          '),
+        stackImageEnv: block(images.map(entry => `${envName(entry.service)}: \${{ steps.images.outputs.${entry.service} }}`), ' '.repeat(10)),
+        stackImageArgs: block(images.map(entry => `--image "${entry.service}=$${envName(entry.service)}" ${CONTINUE}`), ' '.repeat(12)),
         stackPassEnv: block(passEnv.map(name => `${name}: \${{ vars.${name} }}`), ' '.repeat(10)),
     };
 }
-/** The matrix uses the deploy verb only for apps the selected environment deploys; undeployed images retain Dockerfile defaults. */
-function releaseImageVariables(environments) {
-    const names = Object.keys(environments);
-    const selectedApp = names.map(name => `(env.STACK_ENVIRONMENT == '${name}' && contains(fromJSON('${JSON.stringify(environments[name])}'), matrix.name))`).join(' || ') || 'false';
-    const multiple = names.length > 1;
-    const environment = multiple ? 'production' : names[0] ?? 'production';
-    return {
-        imageEnvironment: environment,
-        imageJobEnvironment: names.length ? `\n    environment: ${environment}` : '',
-        imageEnvironmentGuard: multiple ? block([
-            '- name: require a declared image environment',
-            `  if: \${{ !contains(fromJSON('${JSON.stringify(names)}'), env.STACK_ENVIRONMENT) }}`,
-            '  run: \'echo "::error::STACKS_DEPLOY_ENV_UNKNOWN: selected environment declares no deploy images"; exit 1\'',
-        ]) : '',
-        imageBuildArgsIf: `\${{ ${selectedApp} }}`,
-    };
-}