@starci/hfs 4.2.17 → 4.4.0

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/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
@@ -24,8 +25,12 @@ import { APP_SCOPE, SIDES, litePresenceOf, loadSlotManifest, resolveRepoDeclarat
 import { managedGroupOf } from '../runtime/scripts/hfs/edition-slots.mjs';
 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;
@@ -34,7 +39,7 @@ const APP_BINARY = 'starci app';
 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 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) {
@@ -47,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([
@@ -58,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.path === '.gitignore'
-      ? { ...target, template: 'app/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');
@@ -111,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'));
@@ -139,7 +163,9 @@ const SOURCE_SKIPPED = new Set(['node_modules', 'dist', 'coverage']);
 
 /**
  * The be source of the app at `root` the coverage components read: { files, read }, `files` be-relative posix paths of every `*.ts` file under
- * be/apps and be/src (build output and dependencies skipped) and `read` their text. An app with no be folder has no files.
+ * be/apps and be/src (build output and dependencies skipped) and `read` their text. `workPresent` records whether the optional
+ * lite brand tree exists, so sync can preserve its absence. `hasImage` identifies authored optional Dockerfiles without reading
+ * their content. An app with no be folder has no source files.
  */
 export function appSource(root) {
   const files = [];
@@ -152,7 +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') };
+  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) };
 }
 
 /**
@@ -183,7 +211,7 @@ export function jestCoverageSource(coverage) {
  * `docker:build:<app>` builds the image of one app (the exact command its Dockerfile header states, tag `<project>/<app>:dev`) and
  * `docker:build` builds every image, one after the other, never pushing.
  */
-export function appScripts(app) {
+export function appScripts(app, source) {
   const line = (name, command) => `${JSON.stringify(name)}: ${JSON.stringify(command)},`;
   const be = app.sides.be.apps;
   const fe = app.sides.fe.apps;
@@ -194,7 +222,7 @@ export function appScripts(app) {
   const workspace = entry => feAppPackageName(app.project, entry.name);
   // Both editions generate before they run (owner ruling 2026-10-13): the fe's GraphQL wire types, and under lite the Supabase types check.
   const dev = entry => `npm run codegen --silent && turbo run dev --filter=${workspace(entry)}`;
-  const images = imageEntries(app);
+  const images = imageEntries(app, source);
   const imageCommand = ({ side, entry }) => `docker build -f ${dockerfilePath(side, entry.name)} -t ${app.project}/${entry.name}:dev .`;
   return [
     ...(apis.length === 1 ? [line('dev:be', watch(apis[0]))] : apis.map(entry => line(`dev:be:${entry.name}`, watch(entry)))),
@@ -219,9 +247,10 @@ const opensPackages = side => (side.optionalSlots ?? []).some(id => id === 'repo
 /** 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 const STYLE_GLOB = '{apps,packages}/*/src/**/*.css';
 
-/** The images a declaration renders commands and CI entries for. Lite's default deployable is the back-end API image. */
-function imageEntries(app) {
-  return [...app.sides.be.apps.map(entry => ({ side: 'be', entry })), ...(app.edition === 'lite' ? [] : app.sides.fe.apps.map(entry => ({ side: 'fe', entry })))];
+/** Required app images plus lite front ends whose optional Dockerfile the source holds. */
+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 }))];
 }
 
 /**
@@ -229,9 +258,16 @@ function imageEntries(app) {
  * 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) {
+export function imageMatrix(app, source) {
   const entry = (side, item) => `          - name: ${item.name}\n            file: ${dockerfilePath(side, item.name)}`;
-  return imageEntries(app).map(image => entry(image.side, image.entry)).join('\n');
+  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' });
@@ -241,14 +277,14 @@ const IMAGE_TEMPLATE = Object.freeze({ api: 'be/image/api', worker: 'be/image/wo
  * 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
  * them and the be contracts only when the fe side reads them, so each COPY names a folder the app has.
  */
-export function imageFiles(app) {
+export function imageFiles(app, source) {
   const side = app.sides.fe;
   const inputs = [...(opensPackages(side) ? ['fe/packages'] : []), ...((side.reads ?? []).includes('be/contracts/') ? ['be/contracts'] : [])];
   const copyInputs = inputs.map(folder => `COPY ${folder} ${folder}\n`).join('');
   // The folders outside be/ that the back end declares it reads (the generated Supabase types of a lite back end, which an upgraded app keeps reading) are in every one of its images.
   const beFolders = (app.sides.be.reads ?? []).map(folder => folder.replace(/\/$/, ''));
   const copyBeInputs = beFolders.map(folder => `COPY ${folder} ${folder}\n`).join('');
-  const entries = imageEntries(app).map(({ side: which, entry: item }) => ({ side: which, item }));
+  const entries = imageEntries(app, source).map(({ side: which, entry: item }) => ({ side: which, item }));
   return entries.map(({ side: which, item }) => {
     const template = IMAGE_TEMPLATE[item.kind];
     const vars = { project: app.project, app: item.name, nodeImage: NODE_IMAGE, port: DEFAULT_PORT, copyInputs, copyBeInputs };
@@ -258,14 +294,18 @@ export function imageFiles(app) {
 
 /** 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),
+    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).
@@ -276,20 +316,23 @@ 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') : '',
     codecovComponents: scope === APP_SCOPE ? componentsYaml(coverageComponents(manifest, { ...source, apps: app.sides.be.apps, providers })) : '',
     tsconfigPaths: ['be/tsconfig.json', ...fe.apps.map(entry => `fe/apps/${entry.name}/tsconfig.json`), ...(packages ? ['fe/packages/*/tsconfig.json'] : [])].join(','),
     styleGlob: STYLE_GLOB,
-    imageMatrix: imageMatrix(app),
+    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 {
@@ -310,7 +353,9 @@ export function renderTargets(hfs, presets, { sonarKey, readTemplate = readBundl
   const hasTemplate = name => { try { return readTemplate(name) !== undefined; } catch { return false; } };
   return SCOPES.flatMap(scope => {
     const vars = variables(app, scope, presets, sonarKey, manifest, source);
-    return targetsOf(scope, { edition: app.edition, manifest, hasTemplate }).map(target => {
+    const targets = targetsOf(scope, { edition: app.edition, manifest, hasTemplate })
+      .filter(target => !(app.edition === 'lite' && source?.workPresent === false && target.path === '.starciwork/.gitignore'));
+    return targets.map(target => {
       const body = render(readTemplate(target.template), vars, readTemplate);
       const where = onSide(scope, target.path);
       if (target.mode === 'scripts') {
@@ -319,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) };
     });
   });
@@ -361,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)) {
@@ -368,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);
@@ -404,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 });
@@ -426,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);