@starci/hfs 4.12.2 → 4.13.0

package/stack/verify.mjs

@@ -1,10 +1,12 @@
 // verify.mjs - functional verification after convergence: the declared HTTP journeys (config.verify.http) and the declared checks inside a
 // running task (config.verify.exec). Probes are bounded and read-only; a POST body comes only from the declared config and nothing here
 // mutates business data. HTTP goes through ctx.fetch, docker through ctx.spawn, waits through ctx.sleep and time through ctx.now.
+import fs from 'node:fs';
 import { isDeepStrictEqual } from 'node:util';
 import { eachInOrder, repeatInOrder } from '../runtime/scripts/lib/in-order.mjs';
 import { lines as splitLines, tool } from './context.mjs';
 import { edgeAttachmentsOf, verifyEdgeAttachment } from './edge-alias.mjs';
+import { compareWithRelease, digestOf, observedServices, stackImages } from './status.mjs';
 const RETRY_MS = 6000;
 const HTTP_TIMEOUT_MS = 8000;
 function expect(condition, message) {
@@ -87,6 +89,28 @@ async function verifyEdge(ctx, config, results, file) {
     }
     await eachInOrder(attachments, (item) => runCheck(ctx, results, `edge aliases of ${item.service} on ${item.network} are exactly the declared ones`, () => verifyEdgeAttachment(ctx, config, item)));
 }
+/**
+ * Drift: when the stack file pins its images by digest (a rendered release), every service it names runs exactly that digest and none was rolled back by
+ * Swarm, so a release that Swarm quietly reverted never reads as verified. A stack file without pinned images (the source) has nothing to compare.
+ */
+async function verifyDrift(ctx, config, results, file) {
+    let stackYaml;
+    try {
+        stackYaml = fs.readFileSync(file, 'utf8');
+        if (!Object.values(stackImages(stackYaml)).some((image) => digestOf(image) !== null))
+            return;
+    }
+    catch (error) {
+        results.push({ name: 'drift: the stack file is readable', ok: false, detail: String(error.message) });
+        return;
+    }
+    await runCheck(ctx, results, 'drift: the services run the digests of the stack file', () => {
+        const live = observedServices(ctx, config);
+        const drift = compareWithRelease({ stackYaml, release: {} }, live).filter((entry) => entry.kind !== 'not in the release');
+        expect(drift.length === 0, drift.map((entry) => `${entry.service}: ${entry.kind}`).join('; '));
+        return `${live.length} service(s)`;
+    });
+}
 const verifyExec = (ctx, config, results) => eachInOrder([...new Set(config.verify.exec.map((check) => check.service))], (service) => verifyService(ctx, config, results, service));
 /**
  * Runs the declared verification. Returns { ok, lines, data: { checks: [{ name, ok }] } }; the lines read `PASS|FAIL  name  detail`.
@@ -99,6 +123,8 @@ export async function verifyStack(ctx, config, { retrySeconds = 180, skipPublic
         await eachInOrder(config.verify.http, (check) => runCheck(ctx, results, check.name, () => probeHttp(ctx, check), { retry: check.retry, retrySeconds }));
     if (!skipInternal && stackFile)
         await verifyEdge(ctx, config, results, stackFile);
+    if (!skipInternal && stackFile)
+        await verifyDrift(ctx, config, results, stackFile);
     if (!skipInternal)
         await verifyExec(ctx, config, results);
     return {

package/sync/ci-commands.mjs

@@ -9,8 +9,10 @@ const exampleCommand = (source, command) => source?.runtimeExample
     : command;
 const UPLOAD_ARTIFACT = 'actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2';
 const DOWNLOAD_ARTIFACT = 'actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0';
-const SONAR_CONDITION = "${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') }}";
-/** Codecov uploads on release tags with its required authentication; a missing report, an unavailable endpoint or a rejected upload fails the job. */
+// Sonar and the Codecov upload run on every full run (a release tag or a candidate), so a release is analysed before it ships; the plan job decides.
+const FULL_RUN = "needs.plan.outputs.full == 'true'";
+const SONAR_CONDITION = `\${{ !cancelled() && ${FULL_RUN} }}`;
+/** Codecov uploads on every full run with its required authentication; a missing report, an unavailable endpoint or a rejected upload fails the job. */
 function codecovSteps(lcovReport, codecov) {
     if (codecov.enabled === false || codecov.wiring === 'not-used')
         return [
@@ -20,7 +22,7 @@ function codecovSteps(lcovReport, codecov) {
     return [
         '      - name: coverage upload',
         '        uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5.5.5',
-        "        if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') }}",
+        `        if: ${SONAR_CONDITION}`,
         '        with:',
         codecov.auth === 'token' ? `          token: \${{ secrets.${codecov.token} }}` : '          use_oidc: true',
         `          files: ${lcovReport}`,
@@ -28,7 +30,7 @@ function codecovSteps(lcovReport, codecov) {
         '          fail_ci_if_error: true',
     ].join('\n');
 }
-/** Sonar is required: on release tags it consumes the test coverage and lint artifacts, and a missing token fails the job with a clear refusal. */
+/** Sonar is required: on every full run it consumes the test coverage and lint artifacts, and a missing token fails the job with a clear refusal. */
 function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout) {
     if (!sonar)
         return '';
@@ -36,7 +38,8 @@ function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout) {
     const host = sonar.provider === 'sonarcloud' ? 'https://sonarcloud.io' : `\${{ vars.${sonar.hostVar} }}`;
     const header = [
         '  sonar:',
-        '    needs: [lint, coverage]',
+        '    needs: [plan, lint, coverage]',
+        `    if: \${{ ${FULL_RUN} }}`,
         `    timeout-minutes: ${timeout}`,
         '    runs-on: ubuntu-latest',
         '    env:',
@@ -219,6 +222,8 @@ export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info',
             `          NODE_OPTIONS: ${settings.nodeOptions}`,
         ]).join('\n'),
         codecovSteps: codecovSteps(lcovReport, codecov),
+        verdictSonarNeed: sonar ? ', sonar' : '',
+        verdictSonarCheck: sonar ? `\n          if [[ "$FULL" == true && "$CHECKS" == true ]]; then expect sonar success; else expect sonar idle; fi` : '',
         sonarJob: sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, settings.timeoutSonar),
         lcovArtifact,
     };

package/sync/format-worker.d.mts

@@ -0,0 +1 @@
+export {};

package/sync/format-worker.mjs

@@ -0,0 +1,17 @@
+// format-worker.mts - a worker thread of sync/format.mts: loads the repository's own prettier once and checks the batches it is sent.
+import { parentPort } from 'node:worker_threads';
+import { checkBatch, loadPrettier } from './format.mjs';
+let loaded;
+parentPort?.on('message', (message) => {
+    void (async () => {
+        try {
+            if (loaded?.repoRoot !== message.repoRoot)
+                loaded = { repoRoot: message.repoRoot, prettier: loadPrettier(message.repoRoot) };
+            const findings = await checkBatch({ repoRoot: message.repoRoot, files: message.files, prettier: loaded.prettier });
+            parentPort?.postMessage({ findings, count: message.files.length });
+        }
+        catch (error) {
+            parentPort?.postMessage({ error: String(error.message ?? error), code: error.code });
+        }
+    })();
+});

package/sync/format.d.mts

@@ -27,12 +27,30 @@ export type FormatFinding = {
 };
 /** The repository's own prettier, or a SyncError when it is not installed. */
 export declare function loadPrettier(repoRoot: string): Prettier;
+/** Files per batch: one message to a worker, one progress step. */
+export declare const FORMAT_BATCH = 64;
+/** The formattable files of `files`: lockfiles are written by npm and never formatted. */
+export declare const formattable: (files: readonly string[]) => string[];
 /**
- * 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 declare function formatFindings({ repoRoot, files, prettier }: {
+export declare function checkBatch({ repoRoot, files, prettier }: {
+    repoRoot: string;
+    files: readonly string[];
+    prettier: Prettier;
+}): Promise<FormatFinding[]>;
+/** Cuts `files` into batches of `size`. */
+export declare function batches<T>(files: readonly T[], size?: number): T[][];
+/** 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 declare function workerCount(count: number, cores?: number): number;
+/**
+ * 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 declare function formatFindings({ repoRoot, files, prettier, onProgress }: {
     repoRoot: string;
     files: readonly string[];
     prettier?: Prettier | undefined;
+    onProgress?: ((done: number) => void) | undefined;
 }): Promise<FormatFinding[]>;

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 {};