@starci/hfs 4.3.0 → 4.4.1

package/stack/task.mjs

@@ -0,0 +1,42 @@
+// task.mjs - `starci app stack task <name>`: runs ONE declared one-off command (deploy.tasks.<name>.command) inside the running task of
+// deploy.tasks.<name>.service on the manager, through the ssh runner, and relays its stdout. Which command runs is the app's declaration, never a
+// flag: the only argument is the task name. Without --execute a dry-run line says what would run. Output is relayed as the command prints it; this
+// module never reads or prints environment values.
+import { firstLine, lines as splitLines } from './context.mjs';
+import { failure, refusal } from './errors.mjs';
+import { remoteDocker, withRunner } from './remote.mjs';
+
+const TASK_NAME = /^[a-z][a-z0-9-]{0,40}$/u;
+
+function undeclared(config, why) {
+  const names = Object.keys(config.tasks ?? {});
+  const listing = names.length > 0 ? `declared tasks: ${names.join(', ')}` : 'the environment declares no deploy.tasks';
+  return refusal('STACK_TASK_UNDECLARED', `${why}; ${listing}`);
+}
+
+function runningTask(run, service) {
+  const result = remoteDocker(run, ['ps', '-q', '--filter', `label=com.docker.swarm.service.name=${service}`, '--filter', 'status=running']);
+  const task = result.status === 0 ? splitLines(result.stdout)[0] : undefined;
+  if (task) return task;
+  const reason = result.status === 0 ? 'none is running' : firstLine(result.stderr);
+  throw failure('STACK_TASK_NO_TASK', `no running task of service ${service} on the manager (${reason})`);
+}
+
+/** task: runs the declared one-off command `name`. */
+export async function runTask(ctx, config, { name, args = [], execute = false, sshCmd = null } = {}, deps = {}) {
+  if (name === undefined || !TASK_NAME.test(String(name)) || !Object.hasOwn(config.tasks ?? {}, name)) {
+    throw undeclared(config, name === undefined ? 'task takes the name of a declared task' : `no task named ${String(name).slice(0, 41)} is declared`);
+  }
+  if (args.length > 0) throw refusal('STACK_USAGE', 'task takes only the task name; the command is the app\'s declaration');
+  const declared = config.tasks[name];
+  if (!execute) {
+    return { ok: true, lines: [`dry run: would run task ${name} (${declared.command.join(' ')}) in the running ${declared.service} task (add --execute)`], data: { name, status: null } };
+  }
+  return withRunner(ctx, config, { sshCmd }, deps, (run, notes) => {
+    const task = runningTask(run, `${config.stack}_${declared.service}`);
+    const result = remoteDocker(run, ['exec', task, ...declared.command]);
+    const lines = [...notes, ...splitLines(result.stdout)];
+    if (result.status !== 0) lines.push(`FAIL  task ${name} exited ${result.status}: ${firstLine(result.stderr)}`);
+    return { ok: result.status === 0, lines, data: { name, status: result.status } };
+  });
+}

package/stack/verify.mjs

@@ -0,0 +1,99 @@
+// 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 { 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';
+
+const RETRY_MS = 6000;
+const HTTP_TIMEOUT_MS = 8000;
+
+const expect = (condition, message) => {
+  if (!condition) throw new Error(message);
+};
+
+/** Runs one check, retrying every 6 s up to `retrySeconds` when `retry` is set; records { name, ok, detail }. */
+async function runCheck(ctx, results, name, run, { retry = false, retrySeconds = 0 } = {}) {
+  const deadline = ctx.now() + (retry ? retrySeconds * 1000 : 0);
+  const outcome = await repeatInOrder(async () => {
+    try {
+      return { ok: true, detail: await run() };
+    } catch (error) {
+      if (ctx.now() >= deadline) return { ok: false, detail: String(error.message) };
+      await ctx.sleep(RETRY_MS);
+      return undefined;
+    }
+  });
+  results.push({ name, ...outcome });
+}
+
+function checkJson(text, expected) {
+  let body;
+  try { body = JSON.parse(text); } catch { throw new Error('body is not JSON'); }
+  for (const [key, value] of Object.entries(expected)) expect(isDeepStrictEqual(body?.[key], value), `body.${key} is not the declared value`);
+}
+
+/** One declared HTTP journey; throws a message when the answer is not the declared one. */
+async function probeHttp(ctx, check) {
+  const init = { method: check.method, signal: AbortSignal.timeout(HTTP_TIMEOUT_MS) };
+  if (check.body !== null) Object.assign(init, { body: check.body, headers: { 'content-type': 'application/json' } });
+  const response = await ctx.fetch(check.url, init);
+  expect(response.status === check.status, `HTTP ${response.status}`);
+  const text = check.json === null && check.contains === null ? '' : await response.text();
+  if (check.json !== null) checkJson(text, check.json);
+  if (check.contains !== null) expect(text.includes(check.contains), `no ${check.contains} in the answer`);
+  return String(response.status);
+}
+
+/** `docker exec` of a declared command in the running container; exit 0 and, when declared, stdout matching the regex. */
+function probeExec(ctx, container, check) {
+  const run = tool(ctx, 'docker', ['exec', container, ...check.command]);
+  expect(run.status === 0, `exit ${run.status}`);
+  if (check.stdout === null) return 'ok';
+  expect(new RegExp(check.stdout, 'u').test(run.stdout), `stdout does not match ${check.stdout}`);
+  return run.stdout.trim();
+}
+
+/** The running-task check of one service, then its declared commands (skipped when no task runs). */
+async function verifyService(ctx, config, results, service) {
+  const found = tool(ctx, 'docker', ['ps', '-q', '--filter', `label=com.docker.swarm.service.name=${config.stack}_${service}`, '--filter', 'status=running']);
+  const container = splitLines(found.stdout)[0];
+  await runCheck(ctx, results, `a ${service} task is running on this manager`, () => {
+    expect(container, `no running container of ${config.stack}_${service} on the daemon`);
+    return container.slice(0, 12);
+  });
+  if (!container) return;
+  await eachInOrder(config.verify.exec.filter((entry) => entry.service === service), (check) => runCheck(ctx, results, check.name, () => probeExec(ctx, container, check)));
+}
+
+/** Every edge-attached service carries exactly its declared aliases (never the implicit short name) on the shared external network. */
+async function verifyEdge(ctx, config, results, file) {
+  let attachments;
+  try {
+    attachments = edgeAttachmentsOf(file);
+  } catch (error) {
+    results.push({ name: 'edge aliases: the stack file is readable', ok: false, detail: String(error.message) });
+    return;
+  }
+  await eachInOrder(attachments, (item) => runCheck(ctx, results, `edge aliases of ${item.service} on ${item.network} are exactly the declared ones`, () => verifyEdgeAttachment(ctx, config, item)));
+}
+
+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`.
+ * `skipPublic` skips the HTTP journeys, `skipInternal` the checks inside a task. `stackFile` (default: the stack source) is read for the services
+ * attached to an external network: each must carry exactly its declared aliases, never the implicit short name.
+ */
+export async function verifyStack(ctx, config, { retrySeconds = 180, skipPublic = false, skipInternal = false, stackFile = config.stackFile } = {}) {
+  const results = [];
+  if (!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) await verifyExec(ctx, config, results);
+  return {
+    ok: results.every((entry) => entry.ok),
+    lines: results.map((entry) => `${entry.ok ? 'PASS' : 'FAIL'}  ${entry.name}  ${entry.detail}`),
+    data: { checks: results.map(({ name, ok }) => ({ name, ok })) },
+  };
+}

package/sync/ci-commands.mjs

@@ -0,0 +1,13 @@
+// One command vocabulary for managed CI rendering and the runtime coverage gate.
+const exampleCommand = (source, command) => source?.runtimeExample
+  ? 'node node_modules/@starci/hfs/runtime/scripts/hfs/example-secrets.mjs --run . -- ' + command
+  : command;
+
+export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info') {
+  return {
+    ciLint: exampleCommand(source, 'npm run lint'),
+    ciLintSonar: exampleCommand(source, 'npm run lint -- --sonar reports/lint.sonar.json'),
+    ciCoverageProof: exampleCommand(source, 'npx starci app check --coverage-from ' + lcovReport),
+    ciDatabaseLint: exampleCommand(source, 'npm run db:lint'),
+  };
+}

package/sync/format.mjs

@@ -13,7 +13,7 @@ const IGNORE_FILE = '.prettierignore';
 const LOCKFILES = new Set(['package-lock.json']);
 
 /** The repository's own prettier, or a SyncError when it is not installed. */
-export function loadPrettier(repoRoot) {
+function loadPrettier(repoRoot) {
   const require = createRequire(path.join(repoRoot, 'package.json'));
   try {
     return require('prettier');

package/sync/hygiene.mjs

@@ -43,7 +43,7 @@ function ignoredAmong(cwd, files) {
 }
 
 /** Violations among `files` (repository-relative, '/'-separated): [{ file, code, message }]. `ignored` is a Set of ignored paths. */
-export function hygieneFindings(files, ignored) {
+function hygieneFindings(files, ignored) {
   const findings = [];
   for (const file of files) {
     if (file.startsWith(WORK) && ignored.has(file)) {

package/sync/index.mjs

@@ -4,7 +4,8 @@
 // kind app, CI, the hooks, the formatter and Sonar configuration and .starciwork; its sides be/ and fe/ hold each side's tool
 // configuration. The managed set is read from the slot manifest (knowledge/hfs/slots.yaml): every slot that names `managedBy`
 // lists, in its `path`, the whole files sync renders, and `managedBy` names the template directory they are rendered from:
-// templates/<scope or common>/<managedBy>/<file path with each leading dot dropped>, the scope being app for a root slot and the
+// templates/<scope or common>/<managedBy>/<file path with each leading dot dropped>, with dotted skeleton paths tried when no
+// undotted template exists. The scope is app for a root slot and the
 // side (be, fe) for a side slot, whose files land under that side's folder. Two targets are not whole files of a managedBy slot
 // and are listed in this module: the marked block of the root .gitignore, and .starciwork/.gitignore, which lives inside the
 // .starciwork directory slot. Every file is rendered with the app's hfs.json (both sides and their apps) and, for the Sonar
@@ -26,16 +27,19 @@ import { feAppPackageName } from '../runtime/scripts/hfs/rules/monorepo.mjs';
 import { DEFAULT_PORT, NODE_IMAGE, dockerfilePath } from '../runtime/scripts/hfs/rules/docker.mjs';
 import { isFile } from '../runtime/scripts/lib/fs-kind.mjs';
 import { readDeclaredSonarKey } from './sonar-key.mjs';
+import { readDeclaredStack, stackWorkflowVariables } from './stack-images.mjs';
 import { byCodeUnit } from '../report/order.mjs';
+import { isRuntimeExampleApp } from '../runtime/scripts/lib/runtime-example.mjs';
+import { ciWorkflowCommands } from './ci-commands.mjs';
 
 export const TEMPLATES_DIR = path.join(import.meta.dirname, '..', 'templates');
 const NODE_MAJOR = 22;
 const APP_BINARY = 'starci app';
 /** The scopes a target is rendered for: the app root, then each side. */
 export const SCOPES = Object.freeze([APP_SCOPE, ...SIDES]);
-export const BLOCK_BEGIN = '# >>> starci app sync (managed block; do not edit) >>>';
-export const BLOCK_END = '# <<< starci app sync <<<';
-const HEADER = scope => `# Generated by ${APP_BINARY} sync (${scope === APP_SCOPE ? 'app root' : `${scope} side`}). Do not edit: run "npx ${APP_BINARY} sync --write".`;
+const BLOCK_BEGIN = '# >>> starci app sync (managed block; do not edit) >>>';
+const BLOCK_END = '# <<< starci app sync <<<';
+const HEADER = scope => `# Generated by ${APP_BINARY} sync (${scope === APP_SCOPE ? 'app root' : scope + ' side'}). Do not edit: run "npx ${APP_BINARY} sync --write".`;
 
 export class SyncError extends Error {
   constructor(code, message) {
@@ -48,7 +52,8 @@ export class SyncError extends Error {
 // package.json. A template that can hold a comment opens with {{header}}; a file whose exact content is specified (JSON, the
 // eslint one-liner) has no header.
 const MODE_OF_GROUP = Object.freeze({ 'package-scripts': 'scripts', 'package-scripts-lite': 'scripts' });
-const LITERAL_FILE = /^[^*?<>{}[\]]+[^/*?<>{}[\]]$/;
+const GLOB_CHARACTERS = new Set('*?<>{}[]');
+const literalFile = file => file.length >= 2 && !file.endsWith('/') && ![...file].some(character => GLOB_CHARACTERS.has(character));
 
 /** The targets no managedBy slot lists as a whole file (see the header of this module); both belong to the app root. */
 const UNLISTED_TARGETS = Object.freeze([
@@ -59,32 +64,44 @@ const UNLISTED_TARGETS = Object.freeze([
 const templateName = (scope, group, file) => `${scope}/${group}/${file.split('/').map(segment => segment.replace(/^\./, '')).join('/')}`;
 const onSide = (scope, file) => (scope === APP_SCOPE ? file : `${scope}/${file}`);
 
+function managedTemplate(scope, group, file, hasTemplate) {
+  const directories = [scope, 'common'];
+  const undotted = directories.map(dir => templateName(dir, group, file)).find(name => hasTemplate(name));
+  if (undotted || !['skeleton', 'skeleton-lite'].includes(group)) return undotted;
+  return directories.map(dir => `${dir}/${group}/${file}`).find(name => hasTemplate(name));
+}
+
+function slotTargets(slot, scope, edition, manifest, hasTemplate) {
+  if (!slot.profiles.includes(scope) || !slotInEdition(manifest, slot, edition)) return [];
+  if (edition === 'lite' && litePresenceOf(slot, scope) === 'forbidden') return [];
+  const group = managedGroupOf(slot, edition);
+  if (group === undefined) return [];
+  const effectivePath = edition === 'lite' ? (slot.lite?.path ?? slot.path) : slot.path;
+  return braceVariants(effectivePath).map(file => {
+    const managedKey = edition === 'lite' && slot.liteManagedBy !== undefined ? 'liteManagedBy' : 'managedBy';
+    if (!literalFile(file)) throw new SyncError('HFS_SYNC_MANIFEST_MANAGED', `slot ${slot.id} names ${managedKey} but its path ${effectivePath} is not a list of literal files (${file})`);
+    const template = managedTemplate(scope, group, file, hasTemplate);
+    if (!template) throw new SyncError('HFS_SYNC_TEMPLATE_MISSING', `slot ${slot.id} manages ${file} for ${scope}, but templates/{${scope},common}/${group} has no template for it`);
+    return { path: file, template, mode: MODE_OF_GROUP[group] ?? 'file', slot: slot.id };
+  });
+}
+
+function unlistedTargets(scope, edition) {
+  if (scope !== APP_SCOPE) return [];
+  return UNLISTED_TARGETS.map(target => {
+    if (edition !== 'lite') return { ...target };
+    return { ...target, template: target.path === '.gitignore' ? 'app/gitignore-lite' : 'app/starciwork.gitignore-lite' };
+  });
+}
+
 /**
  * Every target of `scope` (app, be or fe), its path relative to that scope's folder: the files the manifest's managedBy slots
  * list, then (app root) the unlisted ones. A slot that names managedBy lists literal files only, and each has a template under
  * its scope or under common.
  */
 export function targetsOf(scope, { edition = 'full', manifest = loadSlotManifest(), hasTemplate = name => fs.existsSync(path.join(TEMPLATES_DIR, name)) } = {}) {
-  const listed = [];
-  for (const slot of manifest.slots) {
-    if (!slot.profiles.includes(scope) || !slotInEdition(manifest, slot, edition)) continue;
-    if (edition === 'lite' && litePresenceOf(slot, scope) === 'forbidden') continue;
-    const group = managedGroupOf(slot, edition);
-    if (group === undefined) continue;
-    const effectivePath = edition === 'lite' ? (slot.lite?.path ?? slot.path) : slot.path;
-    for (const file of braceVariants(effectivePath)) {
-      if (!LITERAL_FILE.test(file)) throw new SyncError('HFS_SYNC_MANIFEST_MANAGED', `slot ${slot.id} names ${edition === 'lite' && slot.liteManagedBy !== undefined ? 'liteManagedBy' : 'managedBy'} but its path ${effectivePath} is not a list of literal files (${file})`);
-      const template = [scope, 'common'].map(dir => templateName(dir, group, file)).find(hasTemplate);
-      if (!template) throw new SyncError('HFS_SYNC_TEMPLATE_MISSING', `slot ${slot.id} manages ${file} for ${scope}, but templates/{${scope},common}/${group} has no template for it`);
-      listed.push({ path: file, template, mode: MODE_OF_GROUP[group] ?? 'file', slot: slot.id });
-    }
-  }
-  const unlisted = scope === APP_SCOPE
-    ? UNLISTED_TARGETS.map(target => edition === 'lite'
-      ? { ...target, template: target.path === '.gitignore' ? 'app/gitignore-lite' : 'app/starciwork.gitignore-lite' }
-      : { ...target })
-    : [];
-  return [...listed, ...unlisted];
+  const listed = manifest.slots.flatMap(slot => slotTargets(slot, scope, edition, manifest, hasTemplate));
+  return [...listed, ...unlistedTargets(scope, edition)];
 }
 
 const lf = text => text.replace(/\r\n/g, '\n');
@@ -112,14 +129,20 @@ function readBundled(name) {
  * so a JavaScript template stays valid source before rendering. An unknown name is an error, never an empty string.
  */
 export function render(text, vars, readTemplate = readBundled) {
-  const withPartials = text.replace(/^(?:\/\/ )?\{\{> ([\w./-]+)\}\}\n/gm, (_, name) => render(readTemplate(name), vars, readTemplate).replace(/\n*$/, '\n'));
+  const withPartials = text.replace(/^(?:\/\/ )?\{\{> ([\w./-]+)\}\}\n/gm, (_, name) => trailingNewline(render(readTemplate(name), vars, readTemplate)));
   return withPartials.replace(/\{\{([A-Za-z]\w*)\}\}/g, (_, key) => {
     if (!Object.hasOwn(vars, key)) throw new SyncError('HFS_SYNC_TEMPLATE_VARIABLE', `template names {{${key}}}, which sync does not provide`);
     return vars[key];
   });
 }
 
-/** What the app's sync reads from the jest preset it installs for its be side: the Sonar exclusions ({ sonarExclusions }); both editions install it (a lite back end keeps full's unit run, owner ruling 2026-10-12). */
+function trailingNewline(text) {
+  let end = text.length;
+  while (end > 0 && text[end - 1] === '\n') end -= 1;
+  return text.slice(0, end) + '\n';
+}
+
+/** What the app's sync reads from the jest preset it installs for its be side: the Sonar exclusions ({ sonarExclusions }); both editions install it (a lite back end keeps full's unit run, ruling:R212/case-1, amended by ruling:R212/case-4). */
 export async function loadPresets(root) {
   const name = '@starci/jest-preset';
   const require = createRequire(path.join(root, 'package.json'));
@@ -155,8 +178,9 @@ export function appSource(root) {
     }
   };
   for (const dir of ['apps', 'src']) walk(dir);
-  return { files: files.sort(byCodeUnit), read: file => fs.readFileSync(path.join(root, 'be', file), 'utf8'),
-    workPresent: fs.existsSync(path.join(root, '.starciwork')), hasImage: file => isFile(path.join(root, file), { followLinks: false }) };
+  return { runtimeExample: isRuntimeExampleApp(root), files: files.sort(byCodeUnit), read: file => fs.readFileSync(path.join(root, 'be', file), 'utf8'),
+    workPresent: fs.existsSync(path.join(root, '.starciwork')), hasImage: file => isFile(path.join(root, file), { followLinks: false }),
+    stack: readDeclaredStack(root) };
 }
 
 /**
@@ -239,6 +263,13 @@ export function imageMatrix(app, source) {
   return imageEntries(app, source).map(image => entry(image.side, image.entry)).join('\n');
 }
 
+/** The Dockerfile of the app a deploy image names (be first, then fe); an app hfs.json does not declare cannot be built by the managed workflow. */
+function stackDockerfile(app, name) {
+  const side = ['be', 'fe'].find(which => app.sides[which].apps.some(entry => entry.name === name));
+  if (!side) 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);
+}
+
 const IMAGE_TEMPLATE = Object.freeze({ api: 'be/image/api', worker: 'be/image/worker', cli: 'be/image/cli', next: 'fe/image/next' });
 
 /**
@@ -263,14 +294,18 @@ export function imageFiles(app, source) {
 
 /** Every value a template of `scope` can name, derived from hfs.json and the presets. */
 export function variables(app, scope, presets, sonarKey, manifest = loadSlotManifest(), source = { files: [], read: () => '' }) {
+  const stack = source.stack ?? { images: [], passEnv: [] };
   const fe = app.sides.fe;
   const packages = opensPackages(fe);
   const lite = app.edition === 'lite';
   const providers = (app.sides.be.connections ?? []).map(connection => connection.provider);
   return {
     header: HEADER(scope),
+    project: app.project,
     appBinary: APP_BINARY,
     appScripts: appScripts(app, source),
+    // A full upgrade keeps the app's declared Supabase connection and its local database commands.
+    supabaseScripts: providers.includes('supabase') ? render(readBundled('app/package-scripts/supabase.json'), { appBinary: APP_BINARY }) : '',
     // turbo builds every fe app workspace; ^build (turbo.json) builds the packages each app imports first, and caches both.
     buildFe: 'npm run codegen --silent && turbo run build --filter=./fe/apps/*',
     // The be side with its tsc; every fe workspace with its own typecheck script through turbo (the packages are built first: ^build).
@@ -281,7 +316,8 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
     sonarExclusions: [presets?.sonarExclusions, '**/.next/**', '**/node_modules/**', '**/src/messages/**', ...(lite ? ['supabase/types/**'] : [])].filter(Boolean).join(','),
     sonarSources: ['be/apps', 'be/src', 'fe/apps', ...(packages ? ['fe/packages'] : [])].join(','),
     lcovReport: LCOV_REPORT,
-    // The coverage scope is the same in both editions: lite measures exactly what full measures (owner ruling 2026-10-12).
+    ...ciWorkflowCommands(source, LCOV_REPORT),
+    // The coverage scope is the same in both editions: lite measures exactly what full measures (ruling:R212/case-1, amended by ruling:R212/case-4).
     jestCoverage: scope === 'be' ? jestCoverageSource(jestCoverage(manifest, providers)) : '',
     coverageExclusions: scope === APP_SCOPE ? sonarCoverageExclusions(manifest, providers).join(',') : '',
     codecovPaths: scope === APP_SCOPE ? codecovPaths(manifest, providers).map(glob => `          - ${JSON.stringify(glob)}`).join('\n') : '',
@@ -290,11 +326,13 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
     styleGlob: STYLE_GLOB,
     imageMatrix: imageMatrix(app, source),
     imageProject: app.project,
+    ...stackWorkflowVariables(stack, app.project, name => stackDockerfile(app, name)),
   };
 }
 
 // The scripts of a package.json as one comparable text: a line per script, sorted by name (order is not drift).
-const scriptsText = scripts => `${Object.keys(scripts).sort(byCodeUnit).map(name => `${name}: ${typeof scripts[name] === 'string' ? scripts[name] : JSON.stringify(scripts[name])}`).join('\n')}\n`;
+const scriptsText = scripts => Object.keys(scripts).sort(byCodeUnit)
+  .map(name => `${name}: ${typeof scripts[name] === 'string' ? scripts[name] : JSON.stringify(scripts[name])}`).join('\n') + '\n';
 
 function parseScripts(text) {
   try {
@@ -326,7 +364,7 @@ export function renderTargets(hfs, presets, { sonarKey, readTemplate = readBundl
         const content = scriptsText(scripts);
         return { path: where, scope, mode: 'scripts', content, hash: hashOf(content), scripts };
       }
-      const managed = target.mode === 'block' ? `${BLOCK_BEGIN}\n${body.replace(/\n*$/, '\n')}${BLOCK_END}\n` : body;
+      const managed = target.mode === 'block' ? `${BLOCK_BEGIN}\n${trailingNewline(body)}${BLOCK_END}\n` : body;
       return { path: where, scope, mode: target.mode, content: managed, hash: hashOf(managed) };
     });
   });
@@ -368,6 +406,21 @@ export function checkTargets(root, targets) {
 }
 
 /** Rewrite the missing or drifted targets; returns the paths written. */
+function writtenContent(target, existing) {
+  if (target.mode === 'scripts') {
+    let pkg = {};
+    if (existing) {
+      try { pkg = JSON.parse(existing); } catch { throw new SyncError('HFS_SYNC_HFS_INVALID', `${target.path} is not valid JSON; fix it by hand before sync can set its scripts`); }
+    }
+    return `${JSON.stringify({ ...pkg, scripts: target.scripts }, null, 2)}\n`;
+  }
+  if (target.mode === 'block' && existing) {
+    const current = managedPart('block', existing);
+    return current === null ? `${target.content}\n${existing}` : existing.replace(current, () => target.content);
+  }
+  return target.content;
+}
+
 export function writeTargets(root, targets) {
   const written = [];
   for (const result of checkTargets(root, targets)) {
@@ -375,17 +428,7 @@ export function writeTargets(root, targets) {
     const target = targets.find(candidate => candidate.path === result.path);
     const file = path.join(root, target.path);
     const existing = fs.existsSync(file) ? lf(fs.readFileSync(file, 'utf8')) : '';
-    let next = target.content;
-    if (target.mode === 'scripts') {
-      let pkg = {};
-      if (existing) {
-        try { pkg = JSON.parse(existing); } catch { throw new SyncError('HFS_SYNC_HFS_INVALID', `${target.path} is not valid JSON; fix it by hand before sync can set its scripts`); }
-      }
-      next = `${JSON.stringify({ ...pkg, scripts: target.scripts }, null, 2)}\n`;
-    } else if (target.mode === 'block' && existing) {
-      const current = managedPart('block', existing);
-      next = current === null ? `${target.content}\n${existing}` : existing.replace(current, () => target.content);
-    }
+    const next = writtenContent(target, existing);
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, next);
     written.push(target.path);
@@ -411,19 +454,40 @@ export function loadHfs(root, manifest = loadSlotManifest()) {
 export async function renderRepo(root, { presets, parseYaml, manifest = loadSlotManifest() } = {}) {
   const hfs = loadHfs(root, manifest);
   const sonarKey = await readDeclaredSonarKey(root, { parseYaml, fail: message => { throw new SyncError('HFS_SYNC_SONAR_KEY', message); } });
-  return { hfs, targets: renderTargets(hfs, presets ?? await loadPresets(root), { sonarKey, manifest, source: appSource(root) }) };
+  return { hfs, targets: renderTargets(hfs, presets ?? await loadPresets(root), { sonarKey, manifest, source: { ...appSource(root), stack: readDeclaredStack(root, { parseYaml }) } }) };
 }
 
 /** `starci app sync --check | --write [--cwd <dir>]` at the app root; returns 0 clean, 1 drift, 2 usage. */
-export async function runSync(argv, { cwd = process.cwd(), out = line => process.stdout.write(`${line}\n`), presets, parseYaml } = {}) {
+function syncOptions(argv) {
   const check = argv.includes('--check'), write = argv.includes('--write');
   const cwdAt = argv.indexOf('--cwd');
   const known = new Set(['--check', '--write', '--cwd']);
   const unknown = argv.find((arg, index) => !known.has(arg) && index !== cwdAt + 1);
   if ([check, write].filter(Boolean).length !== 1 || unknown !== undefined || (cwdAt >= 0 && argv[cwdAt + 1] === undefined)) {
+    return null;
+  }
+  return { write, cwdAt };
+}
+
+function reportSyncCheck(root, targets, out) {
+  const results = checkTargets(root, targets);
+  const bad = results.filter(item => item.status !== 'ok');
+  for (const result of bad) {
+    const found = result.actualHash ? `, found ${result.actualHash.slice(0, 12)}` : '';
+    const where = result.difference ? ` (line ${result.difference.line}: expected ${JSON.stringify(result.difference.expected)}, found ${JSON.stringify(result.difference.actual)})` : '';
+    out(`HFS_SYNC_DRIFT ${result.path}: ${result.status}, expected sha256 ${result.expectedHash.slice(0, 12)}${found}${where}`);
+  }
+  out(`starci app sync --check: ${results.length - bad.length} of ${results.length} in sync${bad.length ? '; run "npx starci app sync --write"' : ''}`);
+  return bad.length ? 1 : 0;
+}
+
+export async function runSync(argv, { cwd = process.cwd(), out = line => process.stdout.write(`${line}\n`), presets, parseYaml } = {}) {
+  const options = syncOptions(argv);
+  if (!options) {
     out('usage: starci app sync (--check | --write) [--cwd <dir>]');
     return 2;
   }
+  const { write, cwdAt } = options;
   const root = cwdAt >= 0 ? path.resolve(cwd, argv[cwdAt + 1]) : cwd;
   try {
     const { targets } = await renderRepo(root, { presets, parseYaml });
@@ -433,15 +497,7 @@ export async function runSync(argv, { cwd = process.cwd(), out = line => process
       out(`starci app sync: ${written.length} written, ${targets.length - written.length} already in sync`);
       return 0;
     }
-    const results = checkTargets(root, targets);
-    const bad = results.filter(item => item.status !== 'ok');
-    for (const result of bad) {
-      const found = result.actualHash ? `, found ${result.actualHash.slice(0, 12)}` : '';
-      const where = result.difference ? ` (line ${result.difference.line}: expected ${JSON.stringify(result.difference.expected)}, found ${JSON.stringify(result.difference.actual)})` : '';
-      out(`HFS_SYNC_DRIFT ${result.path}: ${result.status}, expected sha256 ${result.expectedHash.slice(0, 12)}${found}${where}`);
-    }
-    out(`starci app sync --check: ${results.length - bad.length} of ${results.length} in sync${bad.length ? '; run "npx starci app sync --write"' : ''}`);
-    return bad.length ? 1 : 0;
+    return reportSyncCheck(root, targets, out);
   } catch (error) {
     if (!(error instanceof SyncError)) throw error;
     out(error.message);

package/sync/stack-images.mjs

@@ -0,0 +1,127 @@
+// The Swarm deploy images an app declares, as the managed stack-deploy.yml workflow needs them.
+//
+// The workflow builds one image per `deploy.images` entry of .starcistacks/application-stacks.yaml and hands the pinned references to
+// `starci app stack deploy`. Sync renders that list into the workflow, so it reads the declaration here: the union over the declared
+// environments of `environments.<env>.deploy.images` (service -> { app, buildArgs }). Only names and the presence of build arguments are
+// read; the real validation of the block is stack-deploy-config.mjs (`starci app check`, rule R294). Everything this module returns is
+// pure text assembled from names that match the strict patterns below, so no free text reaches the rendered workflow.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseYaml as bundledParseYaml } from '../runtime/engine/yaml.mjs';
+import { DECLARATION } from './sonar-key.mjs';
+import { byCodeUnit } from '../report/order.mjs';
+
+const NAME = /^[a-z][a-z0-9-]*$/u;
+const KEY = /^[A-Z][A-Z0-9_]*$/u;
+const INDENT = ' '.repeat(6);
+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);
+const hasBuildArgs = args => record(args) && (Object.keys(record(args.values) ? args.values : {}).length > 0 || record(args.sealed));
+
+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) }));
+}
+
+/**
+ * The images of a parsed declaration, [{ service, app, buildArgs }] sorted by service: the union over its environments (the first
+ * environment that names a service decides its app; a later one only adds build arguments). A declaration with no deploy block has none.
+ */
+function declaredStackImages(declaration) {
+  const byService = new Map();
+  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);
+    }
+  }
+  return [...byService.values()].sort((a, b) => byCodeUnit(a.service, b.service));
+}
+
+/** The host variables (names only) the declared environments interpolate into `docker stack config`: the union of `deploy.passEnv`. */
+function declaredPassEnv(declaration) {
+  const names = Object.values(record(declaration?.environments) ? declaration.environments : {})
+    .flatMap(environment => (Array.isArray(environment?.deploy?.passEnv) ? environment.deploy.passEnv : []))
+    .filter(name => typeof name === 'string' && KEY.test(name));
+  return [...new Set(names)].sort(byCodeUnit);
+}
+
+/**
+ * What the managed workflow renders from the declaration of the app at `root`: { images, passEnv } (both 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.
+ */
+export function readDeclaredStack(root, { parseYaml = bundledParseYaml } = {}) {
+  const file = path.join(root, DECLARATION);
+  if (!fs.existsSync(file)) return { images: [], passEnv: [] };
+  let declaration;
+  try {
+    declaration = parseYaml(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return { images: [], passEnv: [] };
+  }
+  return { images: declaredStackImages(declaration), passEnv: declaredPassEnv(declaration) };
+}
+
+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}`,
+  ];
+}
+
+function buildPushStep(image, dockerfile) {
+  return [
+    `- name: build and push ${image.service}`,
+    `  id: build-${image.service}`,
+    '  uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2',
+    '  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`,
+  ];
+}
+
+/**
+ * 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
+ *   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).
+ */
+export function stackWorkflowVariables({ images = [], passEnv = [] }, project, dockerfileOf) {
+  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"`);
+  return {
+    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)),
+    stackPassEnv: block(passEnv.map(name => `${name}: \${{ vars.${name} }}`), ' '.repeat(10)),
+  };
+}

package/templates/app/ci-workflows/github/workflows/ci.yml

@@ -30,14 +30,18 @@ jobs:
           node-version: {{nodeMajor}}
           cache: npm
       - run: npm ci --ignore-scripts
+      - name: production dependency audit
+        run: npm audit --omit=dev --audit-level=high
       - name: lint
-        run: npm run lint -- --sonar reports/lint.sonar.json
+        run: {{ciLintSonar}}
       - name: format
         run: npm run format:check
       - name: typecheck
         run: npm run typecheck
       - name: unit
         run: npm test -- --ci
+      - name: coverage proof
+        run: {{ciCoverageProof}}
       - name: coverage upload
         uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5.5.5
         if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') }}