@starci/hfs 4.0.8 → 4.0.10

package/sync/index.mjs

@@ -1,4 +1,4 @@
-// hfs sync: render, verify and write the files an app cannot `extends`.
+// starci app sync: render, verify and write the files an app cannot `extends`.
 //
 // An app is one repository: its root holds the one package.json (all dependencies, all scripts), the lockfile, the hfs.json of
 // kind app, CI, the hooks, the formatter and Sonar configuration and .starciwork; its sides be/ and fe/ hold each side's tool
@@ -8,26 +8,32 @@
 // 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
-// exclusions and the one coverage scope (sonar.coverage.exclusions, its complement, and the codecov.yml paths alike), the jest
-// preset the app installs for its be side. `--check` compares the sha256 of the rendered content with the
+// exclusions, the jest preset the app installs for its be side and the one coverage scope derived from the slot manifest
+// (scripts/hfs/coverage-scope.mjs: the be/jest.config.js scope, sonar.coverage.exclusions and the codecov.yml paths and components). `--check` compares the sha256 of the rendered content with the
 // file on disk and fails on any drift; `--write` rewrites the drifted files. `.gitignore` is the one shared file: only the marked
 // block is managed and the app's own lines around it are left alone. The root package.json is managed by its `scripts` block
-// only (mode scripts, compared as parsed JSON): the rest of the file (dependencies, npm workspaces of fe/packages/*) is the app's.
+// only (mode scripts, compared as parsed JSON): the rest of the file (dependencies, the npm workspaces fe/apps/* and fe/packages/*,
+// HFS_MONO_WORKSPACES) is the app's. The fe side runs through turbo (turbo.json, app.task-graph): each fe app and package is a workspace.
 import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import fs from 'node:fs';
 import path from 'node:path';
 import { braceVariants } from '../runtime/scripts/lib/glob.mjs';
-import { APP_SCOPE, SIDES, loadSlotManifest, resolveRepoDeclaration } from '../runtime/scripts/hfs/slots.mjs';
+import { codecovPaths, coverageComponents, jestCoverage, sonarCoverageExclusions } from '../runtime/scripts/hfs/coverage-scope.mjs';
+import { APP_SCOPE, SIDES, litePresenceOf, loadSlotManifest, resolveRepoDeclaration, slotInEdition } from '../runtime/scripts/hfs/slots.mjs';
+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 { readDeclaredSonarKey } from './sonar-key.mjs';
 
 export const TEMPLATES_DIR = path.join(import.meta.dirname, '..', 'templates');
-export const NODE_MAJOR = 22;
+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 = '# >>> hfs sync (managed block; do not edit) >>>';
-export const BLOCK_END = '# <<< hfs sync <<<';
-const HEADER = scope => `# Generated by hfs sync (${scope === APP_SCOPE ? 'app root' : `${scope} side`}). Do not edit: run "npx hfs sync --write".`;
+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".`;
 
 export class SyncError extends Error {
   constructor(code, message) {
@@ -39,11 +45,11 @@ export class SyncError extends Error {
 // mode: file = whole file, block = the marked block inside a file the app also writes to, scripts = the `scripts` block of
 // 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' });
+const MODE_OF_GROUP = Object.freeze({ 'package-scripts': 'scripts', 'package-scripts-lite': 'scripts' });
 const LITERAL_FILE = /^[^*?<>{}[\]]+[^/*?<>{}[\]]$/;
 
 /** The targets no managedBy slot lists as a whole file (see the header of this module); both belong to the app root. */
-export const UNLISTED_TARGETS = Object.freeze([
+const UNLISTED_TARGETS = Object.freeze([
   { path: '.gitignore', template: 'app/gitignore', mode: 'block' },
   { path: '.starciwork/.gitignore', template: 'app/starciwork.gitignore', mode: 'file' },
 ].map(Object.freeze));
@@ -56,18 +62,27 @@ const onSide = (scope, file) => (scope === APP_SCOPE ? file : `${scope}/${file}`
  * 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, { manifest = loadSlotManifest(), hasTemplate = name => fs.existsSync(path.join(TEMPLATES_DIR, name)) } = {}) {
+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.managedBy === undefined || !slot.profiles.includes(scope)) continue;
-    for (const file of braceVariants(slot.path)) {
-      if (!LITERAL_FILE.test(file)) throw new SyncError('HFS_SYNC_MANIFEST_MANAGED', `slot ${slot.id} names managedBy but its path ${slot.path} is not a list of literal files (${file})`);
-      const template = [scope, 'common'].map(dir => templateName(dir, slot.managedBy, file)).find(hasTemplate);
-      if (!template) throw new SyncError('HFS_SYNC_TEMPLATE_MISSING', `slot ${slot.id} manages ${file} for ${scope}, but templates/{${scope},common}/${slot.managedBy} has no template for it`);
-      listed.push({ path: file, template, mode: MODE_OF_GROUP[slot.managedBy] ?? 'file', slot: slot.id });
+    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 });
     }
   }
-  return [...listed, ...(scope === APP_SCOPE ? UNLISTED_TARGETS.map(target => ({ ...target })) : [])];
+  const unlisted = scope === APP_SCOPE
+    ? UNLISTED_TARGETS.map(target => edition === 'lite' && target.path === '.gitignore'
+      ? { ...target, template: 'app/gitignore-lite' }
+      : { ...target })
+    : [];
+  return [...listed, ...unlisted];
 }
 
 const lf = text => text.replace(/\r\n/g, '\n');
@@ -75,7 +90,7 @@ export const hashOf = text => createHash('sha256').update(lf(text)).digest('hex'
 
 /**
  * The hfs.json sync reads: an app declaration valid for the manifest it pins (both sides, their apps, connections, optional slots,
- * reads). Sync never renders configs for a declaration the eslint canons and hfs check would refuse, so a pin bump cannot leave
+ * reads). Sync never renders configs for a declaration the eslint canons and starci app check would refuse, so a pin bump cannot leave
  * lint unable to start. Answers the resolved app.
  */
 export function validateHfs(hfs, manifest = loadSlotManifest()) {
@@ -99,11 +114,9 @@ export function render(text, vars, readTemplate = readBundled) {
   });
 }
 
-/**
- * What the app's sync reads from the jest preset it installs for its be side: the Sonar exclusions and the coverage sources
- * (`COVERAGE_SOURCES`, the globs jest collects coverage from): { sonarExclusions, coverageSources }.
- */
-export async function loadPresets(root) {
+/** What the app's sync reads from the jest preset it installs for its be side: the Sonar exclusions ({ sonarExclusions }); a lite app installs none. */
+export async function loadPresets(root, edition = 'full') {
+  if (edition === 'lite') return {};
   const name = '@starci/jest-preset';
   const require = createRequire(path.join(root, 'package.json'));
   let resolved;
@@ -112,110 +125,158 @@ export async function loadPresets(root) {
   } catch {
     throw new SyncError('HFS_SYNC_PRESET_MISSING', `${name} is not installed under ${root}; set it to the exact version in knowledge/hfs/canon-pins.yaml and reinstall`);
   }
-  const preset = require(resolved);
-  return { sonarExclusions: preset.sonarExclusions(), coverageSources: [...preset.COVERAGE_SOURCES] };
+  return { sonarExclusions: require(resolved).sonarExclusions() };
 }
 
 /** Where the be unit run writes the lcov report (jest `coverageDirectory` coverage under be/, reporter lcov), from the app root. */
-export const LCOV_REPORT = 'be/coverage/lcov.info';
+const LCOV_REPORT = 'be/coverage/lcov.info';
+
+const SOURCE_FILE = /\.[cm]?ts$/;
+const SOURCE_SKIPPED = new Set(['node_modules', 'dist', 'coverage']);
 
 /**
- * THE coverage scope of an app, from the app root: the preset's coverage sources on the be side (`be/src/**` + `/*.service.ts`).
- * It is the one source of the codecov.yml status paths and, through coverageExclusions, of Sonar's coverage scope, so the two
- * can never drift; fe/ is outside it (a front end has no tests).
+ * 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.
  */
-export function coverageScope(presets) {
-  const sources = presets?.coverageSources;
-  if (!Array.isArray(sources) || !sources.length) throw new SyncError('HFS_SYNC_PRESET_MISSING', '@starci/jest-preset gives no COVERAGE_SOURCES: the coverage scope cannot be rendered');
-  return sources.map(glob => `be/${glob}`);
+export function appSource(root) {
+  const files = [];
+  const walk = dir => {
+    let entries;
+    try { entries = fs.readdirSync(path.join(root, 'be', dir), { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const rel = `${dir}/${entry.name}`;
+      if (entry.isDirectory()) { if (!SOURCE_SKIPPED.has(entry.name)) walk(rel); } else if (SOURCE_FILE.test(entry.name)) files.push(rel);
+    }
+  };
+  for (const dir of ['apps', 'src']) walk(dir);
+  return { files: files.sort(), read: file => fs.readFileSync(path.join(root, 'be', file), 'utf8') };
 }
 
-const COVERED_SUFFIX = /\*\.([a-z][a-z0-9-]*)\.ts$/;
-const asGlob = (text) => String(text).replace(/<[^>]+>/g, '*');
-
 /**
- * Sonar's coverage scope of an app as `sonar.coverage.exclusions` globs: the COMPLEMENT of coverageScope. SonarQube has no
- * coverage inclusions and its globs have no negation, so every executable file that is not a coverage source is excluded:
- *   - every be source role of the slot manifest's closed suffix vocabulary (ruleParams.be.suffixes, R89) other than the
- *     roles the coverage sources name (`service`), as `be/**` + `/*.<role>.ts`;
- *   - every be file name outside that vocabulary a be slot declares (`main.ts`, `index.ts`, `connection.ts`, the migrations,
- *     the test world's files, dto/ and kit/ files), as `be/<slot path>/<name>` with each `<placeholder>` a `*`;
- *   - all of fe/ (a front end has no tests).
- * The result is sorted and has no duplicate. A coverage source that is not `<dir>/**` + `/*.<role>.ts` is refused: its
- * complement cannot be written in Sonar's globs.
+ * The Codecov `individual_components` entries of components [{ id, name, paths }]: one `component_id` block each, `prefix` ahead of every path
+ * (the app folder in the runtime repository) and `ids` mapping a component id to its name there.
  */
-export function coverageExclusions(presets, manifest = loadSlotManifest()) {
-  const covered = new Set(coverageScope(presets).map(glob => {
-    const role = COVERED_SUFFIX.exec(glob)?.[1];
-    if (!role) throw new SyncError('HFS_SYNC_COVERAGE_SCOPE', `coverage source ${glob} is not <dir>/**/*.<role>.ts: Sonar's coverage exclusions cannot express its complement`);
-    return role;
-  }));
-  const suffixes = manifest.ruleParams?.be?.suffixes ?? [];
-  const isRole = new RegExp(`\\.(?:${suffixes.map(s => s.replace(/[-]/g, '\\-')).join('|')})\\.ts$`);
-  const globs = new Set(suffixes.filter(role => !covered.has(role)).map(role => `be/**/*.${role}.ts`));
-  for (const slot of manifest.slots) {
-    if (!slot.profiles.includes('be') || slot.presence === 'forbidden') continue;
-    for (const entry of [...(slot.requires ?? []), ...(slot.allows ?? [])]) {
-      if (!/\.ts$/.test(entry) || entry.includes('<role>')) continue;
-      for (const name of braceVariants(entry)) {
-        if (isRole.test(asGlob(name).replace(/\*/g, 'x'))) continue;
-        for (const dir of braceVariants(slot.path)) globs.add(`be/${asGlob(dir)}${asGlob(name)}`.replace(/\/\/+/g, '/'));
-      }
-    }
-  }
-  globs.add('fe/**');
-  return [...globs].sort();
+export function componentsYaml(components, { prefix = '', ids = id => id } = {}) {
+  return components.map(component => [`    - component_id: ${ids(component.id)}`, `      name: ${ids(component.name)}`, '      paths:', ...component.paths.map(glob => `        - ${JSON.stringify(prefix + glob)}`)].join('\n')).join('\n');
+}
+
+/** The managed be/jest.config.js option text of a coverage scope { roots, roles, excludes }, laid out exactly as prettier lays it out (width 120, indent 4). */
+export function jestCoverageSource(coverage) {
+  const list = (key, items) => {
+    const one = `        ${key}: [${items.map(item => JSON.stringify(item)).join(', ')}],`;
+    return one.length <= 120 ? one : [`        ${key}: [`, ...items.map(item => `            ${JSON.stringify(item)},`), '        ],'].join('\n');
+  };
+  return ['{', list('roots', coverage.roots), list('roles', coverage.roles), list('excludes', coverage.excludes), '    }'].join('\n');
 }
 
 /**
- * The script lines the apps add to the root package.json, each ending with a comma (the template puts them mid-object). Every
- * script runs a side from the app root: a be script from be/ (`cd be && ...`, the folder its tsconfig and jest configuration
- * are relative to), an fe script from fe/. be: `dev:be` runs the one api app from source and restarts it on change (`dev:be:<app>`
- * each, with several), `start:<app>` runs a built api, worker or cli app, `migrate` the migrate app (`migrate:<app>` with several).
- * fe: `dev:fe` runs the one Next app in development (`dev:fe:<app>` each, with several), `start:<app>` serves a built one.
+ * The script lines the apps add to the root package.json, each ending with a comma (the template puts them mid-object). A be
+ * script runs from be/ (`cd be && ...`, the folder its tsconfig and jest configuration are relative to) or runs the built app; an
+ * fe script runs the fe app's workspace (@<project>/<app>): through turbo for dev (so the packages it imports are built first) and
+ * through npm `-w` for start. be: `dev:be` runs the one api app from source and restarts it on change (`dev:be:<app>` each, with
+ * several), `start:<app>` runs a built api or worker app, `cli` the built cli app (`npm run cli -- <group> <command>`) and, when the
+ * back end declares a connection, `migrate` its migrate command (`cli migrate run`). fe: `dev:fe` runs the one Next app in
+ * development (`dev:fe:<app>` each, with several), `start:<app>` serves a built one. Images:
+ * `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) {
   const line = (name, command) => `${JSON.stringify(name)}: ${JSON.stringify(command)},`;
   const be = app.sides.be.apps;
   const fe = app.sides.fe.apps;
   const apis = be.filter(entry => entry.kind === 'api');
-  const migrates = be.filter(entry => entry.kind === 'migrate');
+  const connections = app.sides.be.connections ?? [];
   const watch = entry => `cd be && ts-node-dev --respawn -r tsconfig-paths/register apps/${entry.name}/src/main.ts`;
+  const built = entry => `node be/dist/apps/${entry.name}/src/main.js`;
+  const workspace = entry => feAppPackageName(app.project, entry.name);
+  const dev = entry => `${app.edition === 'lite' ? '' : 'npm run codegen --silent && '}turbo run dev --filter=${workspace(entry)}`;
+  const images = imageEntries(app);
+  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)))),
-    ...(fe.length === 1 ? [line('dev:fe', `npm run codegen --silent && cd fe/apps/${fe[0].name} && next dev`)] : fe.map(entry => line(`dev:fe:${entry.name}`, `npm run codegen --silent && cd fe/apps/${entry.name} && next dev`))),
-    ...be.map(entry => line(entry.kind === 'migrate' ? (migrates.length === 1 ? 'migrate' : `migrate:${entry.name}`) : `start:${entry.name}`, `node be/dist/apps/${entry.name}/src/main.js`)),
-    ...fe.map(entry => line(`start:${entry.name}`, `cd fe/apps/${entry.name} && next start`)),
+    ...(fe.length === 1 ? [line('dev:fe', dev(fe[0]))] : fe.map(entry => line(`dev:fe:${entry.name}`, dev(entry)))),
+    ...be.flatMap(entry => {
+      if (entry.kind !== 'cli') return [line(`start:${entry.name}`, built(entry))];
+      return [line('cli', built(entry)), ...(connections.length ? [line('migrate', `${built(entry)} ${MIGRATE_COMMAND}`)] : [])];
+    }),
+    ...fe.map(entry => line(`start:${entry.name}`, `npm run start -w ${workspace(entry)}`)),
+    ...(app.edition !== 'lite' && app.optionalSlots.includes('app.browser') ? [line('test:browser', 'playwright test -c browser/playwright.config.ts')] : []),
+    line('docker:build', images.map(image => `npm run docker:build:${image.entry.name}`).join(' && ')),
+    ...images.map(image => line(`docker:build:${image.entry.name}`, imageCommand(image))),
   ].join('\n    ');
 }
 
+/** The cli command that migrates every connection (src/features/cli/migrate/subs/run.cli.ts). */
+const MIGRATE_COMMAND = 'migrate run';
+
 /** True when the fe side opts into a workspace package (repo.packages or any fe.package.* slot): the sources then include fe/packages/. */
-export const opensPackages = side => (side.optionalSlots ?? []).some(id => id === 'repo.packages' || String(id).startsWith('fe.package.'));
+const opensPackages = side => (side.optionalSlots ?? []).some(id => id === 'repo.packages' || String(id).startsWith('fe.package.'));
 
 /** 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 })))];
+}
+
+/**
+ * The build matrix of the images workflow: one entry per declared app (be then fe), 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) {
+  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');
+}
+
+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>
+ * 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) {
+  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('');
+  const entries = imageEntries(app).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 };
+    return { path: dockerfilePath(which, item.name), content: render(readBundled(`${template}/Dockerfile`), vars) };
+  });
+}
+
 /** Every value a template of `scope` can name, derived from hfs.json and the presets. */
-export function variables(app, scope, presets, sonarKey, manifest = loadSlotManifest()) {
+export function variables(app, scope, presets, sonarKey, manifest = loadSlotManifest(), source = { files: [], read: () => '' }) {
   const fe = app.sides.fe;
   const packages = opensPackages(fe);
-  const feApps = fe.apps.map(entry => `fe/apps/${entry.name}`);
-  const feTsconfigs = [...feApps.map(dir => `${dir}/tsconfig.json`), ...(packages ? ['fe/packages/*/tsconfig.json'] : [])];
+  const lite = app.edition === 'lite';
+  const providers = (app.sides.be.connections ?? []).map(connection => connection.provider);
   return {
     header: HEADER(scope),
+    appBinary: APP_BINARY,
     appScripts: appScripts(app),
-    buildFe: ['npm run codegen --silent', ...(packages ? ['npm run build --workspaces --if-present'] : []), fe.apps.map(entry => `(cd fe/apps/${entry.name} && next build)`).join(' && ')].join(' && '),
-    // The fe apps import the workspace packages from their dist/, so the packages are built before the apps are type-checked.
-    typecheck: ['npm run codegen --silent', 'tsc -p be/tsconfig.json', ...(packages ? ['npm run build --workspaces --if-present'] : []), ...feTsconfigs.filter(file => !file.includes('*')).map(file => `tsc -p ${file} --noEmit`), ...(packages ? ['npm run typecheck --workspaces --if-present'] : [])].join(' && '),
+    // turbo builds every fe app workspace; ^build (turbo.json) builds the packages each app imports first, and caches both.
+    buildFe: `${lite ? '' : '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).
+    typecheck: `${lite ? '' : 'npm run codegen --silent && '}tsc -p be/tsconfig.json && turbo run typecheck`,
+    lintPrefix: lite ? '' : 'npm run codegen --silent && ',
     nodeMajor: String(NODE_MAJOR),
     sonarKey: sonarKey ?? app.project,
-    sonarExclusions: [presets?.sonarExclusions, '**/.next/**', '**/node_modules/**', '**/src/messages/**'].filter(Boolean).join(','),
+    sonarExclusions: (lite ? ['**/.next/**', '**/node_modules/**', '**/src/messages/**', 'supabase/types/**'] : [presets?.sonarExclusions, '**/.next/**', '**/node_modules/**', '**/src/messages/**']).filter(Boolean).join(','),
     sonarSources: ['be/apps', 'be/src', 'fe/apps', ...(packages ? ['fe/packages'] : [])].join(','),
     lcovReport: LCOV_REPORT,
-    coverageExclusions: scope === APP_SCOPE ? coverageExclusions(presets, manifest).join(',') : '',
-    codecovPaths: scope === APP_SCOPE ? coverageScope(presets).map(glob => `          - ${JSON.stringify(glob)}`).join('\n') : '',
-    tsconfigPaths: ['be/tsconfig.json', ...feTsconfigs].join(','),
+    jestCoverage: !lite && scope === 'be' ? jestCoverageSource(jestCoverage(manifest, providers)) : '',
+    coverageExclusions: !lite && scope === APP_SCOPE ? sonarCoverageExclusions(manifest, providers).join(',') : '',
+    codecovPaths: !lite && scope === APP_SCOPE ? codecovPaths(manifest, providers).map(glob => `          - ${JSON.stringify(glob)}`).join('\n') : '',
+    codecovComponents: !lite && 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),
+    imageProject: app.project,
   };
 }
 
@@ -236,12 +297,12 @@ function parseScripts(text) {
  * its folder); a scripts target also carries `scripts`, the parsed block. `sonarKey` is the key the be side's stack declaration
  * names; without one the key is the project.
  */
-export function renderTargets(hfs, presets, { sonarKey, readTemplate = readBundled, manifest = loadSlotManifest() } = {}) {
+export function renderTargets(hfs, presets, { sonarKey, readTemplate = readBundled, manifest = loadSlotManifest(), source } = {}) {
   const app = validateHfs(hfs, manifest);
   const hasTemplate = name => { try { return readTemplate(name) !== undefined; } catch { return false; } };
   return SCOPES.flatMap(scope => {
-    const vars = variables(app, scope, presets, sonarKey, manifest);
-    return targetsOf(scope, { manifest, hasTemplate }).map(target => {
+    const vars = variables(app, scope, presets, sonarKey, manifest, source);
+    return targetsOf(scope, { edition: app.edition, manifest, hasTemplate }).map(target => {
       const body = render(readTemplate(target.template), vars, readTemplate);
       const where = onSide(scope, target.path);
       if (target.mode === 'scripts') {
@@ -318,41 +379,43 @@ export function writeTargets(root, targets) {
 }
 
 /** The hfs.json object of the app at `root` (validated), or a SyncError. */
-export function loadHfs(root) {
+export function loadHfs(root, manifest = loadSlotManifest()) {
   const file = path.join(root, 'hfs.json');
-  if (!fs.existsSync(file)) throw new SyncError('HFS_SYNC_HFS_INVALID', `${file} does not exist; hfs sync runs at the app root`);
+  if (!fs.existsSync(file)) throw new SyncError('HFS_SYNC_HFS_INVALID', `${file} does not exist; starci app sync runs at the app root`);
   let hfs;
   try {
     hfs = JSON.parse(fs.readFileSync(file, 'utf8'));
   } catch (error) {
     throw new SyncError('HFS_SYNC_HFS_INVALID', `${file} is not valid JSON: ${error.message}`);
   }
-  validateHfs(hfs);
+  validateHfs(hfs, manifest);
   return hfs;
 }
 
 /** The rendered targets of the app at `root`: its hfs.json, the Sonar key the be side's stack declaration names, the presets it installs. */
-export async function renderRepo(root, { presets, parseYaml } = {}) {
-  const hfs = loadHfs(root);
+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 }) };
+  return { hfs, targets: renderTargets(hfs, presets ?? await loadPresets(root, hfs.edition), { sonarKey, manifest, source: appSource(root) }) };
 }
 
-/** `hfs sync --check | --write [--root <dir>]` at the app root; returns the exit code (0 clean, 1 drift or error, 2 usage). */
+/** `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 } = {}) {
   const check = argv.includes('--check'), write = argv.includes('--write');
-  const rootAt = argv.indexOf('--root');
-  if ([check, write].filter(Boolean).length !== 1) {
-    out('usage: hfs sync (--check | --write) [--root <dir>]');
+  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)) {
+    out('usage: starci app sync (--check | --write) [--cwd <dir>]');
     return 2;
   }
-  const root = rootAt >= 0 ? path.resolve(cwd, argv[rootAt + 1] ?? '') : cwd;
+  const root = cwdAt >= 0 ? path.resolve(cwd, argv[cwdAt + 1]) : cwd;
   try {
     const { targets } = await renderRepo(root, { presets, parseYaml });
     if (write) {
       const written = writeTargets(root, targets);
       for (const file of written) out(`wrote ${file}`);
-      out(`hfs sync: ${written.length} written, ${targets.length - written.length} already in sync`);
+      out(`starci app sync: ${written.length} written, ${targets.length - written.length} already in sync`);
       return 0;
     }
     const results = checkTargets(root, targets);
@@ -362,7 +425,7 @@ export async function runSync(argv, { cwd = process.cwd(), out = line => process
       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(`hfs sync --check: ${results.length - bad.length} of ${results.length} in sync${bad.length ? '; run "npx hfs sync --write"' : ''}`);
+    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;
   } catch (error) {
     if (!(error instanceof SyncError)) throw error;

package/sync/managed.mjs

@@ -1,4 +1,4 @@
-// The managed-file findings of `hfs check` (BE-CONVENTION 1.17, 3.1 principle 4): the rendered set of `hfs sync`, compared
+// The managed-file findings of `starci app check`: the rendered set of `starci app sync`, compared
 // with the tracked repository, and the tool configuration nothing may add to it.
 //   HFS_MANAGED_FILE_DRIFT (R05)  a managed file that exists but differs from its render: tsconfig*.json (but see R22),
 //                                 jest.config.js (back end), .prettierrc, .prettierignore, husky hooks, both workflows and sonar
@@ -19,8 +19,12 @@
 //                                 configuration, and a package.json that carries a tool configuration key (`eslintConfig`, `stylelint`,
 //                                 `prettier`, `lint-staged`, `jest`). Forbidden tool-config files (.eslintrc*, .eslintignore, a second
 //                                 eslint.config.*) are refused by hfs-check through the slot manifest under the same code.
+//   HFS_COVERAGE_SCOPE_DRIFT (R204)
+//                                 a file that states the coverage scope no longer states what the slot manifest derives (the `coverage` field of
+//                                 knowledge/hfs/slots.yaml through scripts/hfs/coverage-scope.mjs): be/jest.config.js, codecov.yml, or the
+//                                 `sonar.coverage.exclusions` line of sonar-project.properties. The scope is never edited by hand.
 //   HFS_SONAR_CONFIG (R11)        sonar-project.properties differs from its render (the render names no host URL, sources and tests that
-//                                 do not overlap, the `sonar.exclusions` of the jest preset (a back end), the be lcov with the services as the coverage scope, the ESLint report and the
+//                                 do not overlap, the `sonar.exclusions` of the jest preset (a back end), the be lcov with the logic of be/src/modules as the coverage scope, the ESLint report and the
 //                                 HFS import files Sonar reads), or the stack declaration names a quality gate other than the one
 //                                 gate of knowledge/sonar-gate.yaml (bundled in the runtime copy). One edit is one finding.
 //   HFS_TS_STRICT (R22)           the root tsconfig.json drift (either profile), named by flag (ts-strict.mjs) instead of by hash.
@@ -28,12 +32,16 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { SyncError, checkTargets, renderRepo } from './index.mjs';
 import { parseYaml as bundledParseYaml } from '../runtime/engine/yaml.mjs';
-import { readDeclaredSonarGate } from './sonar-key.mjs';
+import { readDeclaredSonarGate, sonarGateName } from './sonar-key.mjs';
 import { TS_STRICT_FILE, tsStrictFindings } from './ts-strict.mjs';
 
 // The managed one-liners whose difference from the render is the proof that no rule is off, warned or redefined (R17).
 const ONE_LINER_FILES = new Set(['eslint.config.mjs', 'stylelint.config.mjs']);
 const SONAR_PROPERTIES_FILE = 'sonar-project.properties';
+// The files whose whole content is a statement of the coverage scope, and the one line of the Sonar file that is (R204).
+const COVERAGE_SCOPE_FILES = new Set(['be/jest.config.js', 'codecov.yml']);
+const SONAR_COVERAGE_LINE = 'sonar.coverage.exclusions=';
+const statesCoverageScope = result => COVERAGE_SCOPE_FILES.has(result.path) || (result.path === SONAR_PROPERTIES_FILE && String(result.difference?.expected ?? '').startsWith(SONAR_COVERAGE_LINE));
 const SONAR_GATE_FILE = new URL('../runtime/knowledge/sonar-gate.yaml', import.meta.url);
 const MAX_SCANNED_BYTES = 1024 * 1024;
 const RULE_FILE = /\.[cm]?[jt]s$/;
@@ -80,19 +88,19 @@ function driftFindings(repoRoot, targets) {
         continue;
       }
     }
-    const code = target.mode === 'block' ? 'HFS_GITIGNORE_BLOCK_DRIFT' : ONE_LINER_FILES.has(path.posix.basename(result.path)) ? 'HFS_RULE_OFF_WITHOUT_REPLACEMENT' : result.path === SONAR_PROPERTIES_FILE ? 'HFS_SONAR_CONFIG' : 'HFS_MANAGED_FILE_DRIFT';
+    const code = target.mode === 'block' ? 'HFS_GITIGNORE_BLOCK_DRIFT' : ONE_LINER_FILES.has(path.posix.basename(result.path)) ? 'HFS_RULE_OFF_WITHOUT_REPLACEMENT' : statesCoverageScope(result) ? 'HFS_COVERAGE_SCOPE_DRIFT' : result.path === SONAR_PROPERTIES_FILE ? 'HFS_SONAR_CONFIG' : 'HFS_MANAGED_FILE_DRIFT';
     const where = result.difference ? `; line ${result.difference.line} expected ${JSON.stringify(result.difference.expected)}, found ${JSON.stringify(result.difference.actual)}` : '';
-    const what = target.mode === 'block' ? `the managed block of ${result.path} is ${result.status === 'missing' ? 'missing' : 'not its render'}` : target.mode === 'scripts' ? 'the scripts block of package.json is not the rendered one' : `${result.path} is not its render${code === 'HFS_RULE_OFF_WITHOUT_REPLACEMENT' ? ', so a rule can be off or redefined in it' : ''}`;
-    findings.push({ code, level: 'error', path: result.path, mode: target.mode, expectedHash: result.expectedHash, ...(result.actualHash ? { actualHash: result.actualHash } : {}), message: `${what} (expected sha256 ${result.expectedHash.slice(0, 12)}${result.actualHash ? `, found ${result.actualHash.slice(0, 12)}` : ''}${where}); run "npx hfs sync --write"` });
+    const what = target.mode === 'block' ? `the managed block of ${result.path} is ${result.status === 'missing' ? 'missing' : 'not its render'}` : target.mode === 'scripts' ? 'the scripts block of package.json is not the rendered one' : `${result.path} is not its render${code === 'HFS_RULE_OFF_WITHOUT_REPLACEMENT' ? ', so a rule can be off or redefined in it' : code === 'HFS_COVERAGE_SCOPE_DRIFT' ? ', so it no longer states the coverage scope derived from the slot manifest' : ''}`;
+    findings.push({ code, level: 'error', path: result.path, mode: target.mode, expectedHash: result.expectedHash, ...(result.actualHash ? { actualHash: result.actualHash } : {}), message: `${what} (expected sha256 ${result.expectedHash.slice(0, 12)}${result.actualHash ? `, found ${result.actualHash.slice(0, 12)}` : ''}${where}); run "npx starci app sync --write"` });
   }
   return findings;
 }
 
 /** R11: the quality gate the be side's stack declaration names is the one gate of the bundled knowledge/sonar-gate.yaml. */
-function sonarGateFindings(repoRoot, parseYaml) {
+function sonarGateFindings(repoRoot, parseYaml, edition) {
   const declared = readDeclaredSonarGate(repoRoot, { parseYaml });
   if (declared === null) return [];
-  const gate = (parseYaml ?? bundledParseYaml)(fs.readFileSync(SONAR_GATE_FILE, 'utf8'))?.gate?.name;
+  const gate = sonarGateName((parseYaml ?? bundledParseYaml)(fs.readFileSync(SONAR_GATE_FILE, 'utf8')), edition);
   if (declared.qualityGate === gate) return [];
   return [{ code: 'HFS_SONAR_CONFIG', level: 'error', path: declared.file, message: `${declared.file} services.sonar.qualityGate is ${declared.qualityGate ?? 'absent'}; every product names the one gate ${gate} of knowledge/sonar-gate.yaml and states no threshold of its own` }];
 }
@@ -153,17 +161,17 @@ function flagFindings(repoRoot, tracked, managed) {
  * is unreadable has none: the slot check reports the declaration. A missing preset or an unreadable stack declaration is
  * a SyncError the caller reports as a refusal.
  */
-export async function managedFindings({ repoRoot, tracked, presets, parseYaml }) {
+export async function managedFindings({ repoRoot, tracked, presets, parseYaml, manifest }) {
   let rendered;
   try {
-    rendered = await renderRepo(repoRoot, { presets, parseYaml });
+    rendered = await renderRepo(repoRoot, { presets, parseYaml, ...(manifest ? { manifest } : {}) });
   } catch (error) {
     if (error instanceof SyncError && error.code === 'HFS_SYNC_HFS_INVALID') return [];
     throw error;
   }
   const { targets } = rendered;
   const findings = driftFindings(repoRoot, targets);
-  findings.push(...sonarGateFindings(repoRoot, parseYaml));
+  findings.push(...sonarGateFindings(repoRoot, parseYaml, rendered.hfs.edition ?? 'full'));
   findings.push(...ruleFileFindings(repoRoot, tracked));
   findings.push(...toolKeyFindings(repoRoot, tracked));
   findings.push(...flagFindings(repoRoot, tracked, new Set(targets.map(target => target.path))));

package/sync/sonar-key.mjs

@@ -52,3 +52,8 @@ export function readDeclaredSonarGate(root, { parseYaml } = {}) {
   if (!sonar || sonar.mode === 'disabled') return null;
   return { file: path.relative(root, file).split(path.sep).join('/'), qualityGate: typeof sonar.qualityGate === 'string' ? sonar.qualityGate : null };
 }
+
+/** The quality-gate name for an app edition from the one sonar-gate document. */
+export function sonarGateName(document, edition = 'full') {
+  return (edition === 'lite' ? document?.lite : document)?.gate?.name ?? null;
+}

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

@@ -3,18 +3,26 @@ name: ci
 
 on:
   push:
-    branches: [main]
-  pull_request:
+    tags: ["v*"]
+  workflow_dispatch:
 
 permissions:
   contents: read
 
+# One run per ref: a release tag is never cancelled by another run.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: false
+
 jobs:
   ci:
     runs-on: ubuntu-latest
+    # id-token: write lets the Codecov upload authenticate with GitHub's OIDC token: no repository secret, no silent skip.
+    permissions:
+      contents: read
+      id-token: write
     env:
       SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
-      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
@@ -32,9 +40,9 @@ jobs:
         run: npm test -- --ci
       - name: coverage upload
         uses: codecov/codecov-action@v5
-        if: ${{ !cancelled() && env.CODECOV_TOKEN != '' }}
+        if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') }}
         with:
-          token: ${{ env.CODECOV_TOKEN }}
+          use_oidc: true
           files: {{lcovReport}}
           disable_search: true
           fail_ci_if_error: true
@@ -42,12 +50,4 @@ jobs:
         run: npm run build:be
       - name: build fe
         run: npm run build:fe
-      - uses: SonarSource/sonarqube-scan-action@v7
-        if: ${{ !cancelled() && env.SONAR_TOKEN != '' }}
-        env:
-          SONAR_HOST_URL: ${{ vars.SONAR_HOST_URL }}
-      - uses: SonarSource/sonarqube-quality-gate-action@v1
-        if: ${{ !cancelled() && env.SONAR_TOKEN != '' }}
-        timeout-minutes: 10
-        env:
-          SONAR_HOST_URL: ${{ vars.SONAR_HOST_URL }}
+{{> app/ci-workflows/sonar-steps.yml}}