@starci/hfs 3.0.0 → 4.0.1

package/sync/index.mjs

@@ -1,29 +1,32 @@
-// hfs sync: render, verify and write the files a product repository cannot `extends`.
+// hfs sync: render, verify and write the files an app cannot `extends`.
 //
-// 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/<profile or common>/<managedBy>/<file path with each leading dot dropped>. Two targets are not whole files
-// of a managedBy slot and are listed in this module: the marked block of the shared .gitignore, and
-// .starciwork/.gitignore, which lives inside the .starciwork directory slot. Every file is rendered with the
-// repository's hfs.json (profile and apps) and, for the Sonar exclusions, the same jest preset a back end
-// repository installs. `--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 repository's own lines around it are left alone. A back end's package.json is managed by its `scripts`
-// block only (mode scripts, compared as parsed JSON): the rest of the file is the repository's.
+// 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
+// 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
+// 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, the jest preset the app installs for its be side. `--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.
 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 { loadSlotManifest, resolveRepoDeclaration } from '../runtime/scripts/lib/hfs-slots.mjs';
+import { APP_SCOPE, SIDES, loadSlotManifest, resolveRepoDeclaration } from '../runtime/scripts/lib/hfs-slots.mjs';
 import { readDeclaredSonarKey } from './sonar-key.mjs';
 
 export const TEMPLATES_DIR = path.join(import.meta.dirname, '..', 'templates');
 export const NODE_MAJOR = 22;
-export const PROFILES = Object.freeze(['be', 'fe']);
+/** 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 = profile => `# Generated by hfs sync (profile ${profile}). Do not edit: run "npx hfs sync --write".`;
+const HEADER = scope => `# Generated by hfs sync (${scope === APP_SCOPE ? 'app root' : `${scope} side`}). Do not edit: run "npx hfs sync --write".`;
 
 export class SyncError extends Error {
   constructor(code, message) {
@@ -32,69 +35,54 @@ export class SyncError extends Error {
   }
 }
 
-// mode: file = whole file, block = the marked block inside a file the repository 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.
+// 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 LITERAL_FILE = /^[^*?<>{}[\]]+[^/*?<>{}[\]]$/;
 
-/** The targets no managedBy slot lists as a whole file (see the header of this module). */
+/** 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([
-  { path: '.gitignore', template: { be: 'be/gitignore', fe: 'fe/gitignore' }, mode: 'block' },
-  { path: '.starciwork/.gitignore', template: { be: 'be/starciwork.gitignore' }, mode: 'file' },
+  { path: '.gitignore', template: 'app/gitignore', mode: 'block' },
+  { path: '.starciwork/.gitignore', template: 'app/starciwork.gitignore', mode: 'file' },
 ].map(Object.freeze));
 
-const templateName = (profile, group, file) => `${profile}/${group}/${file.split('/').map(segment => segment.replace(/^\./, '')).join('/')}`;
+const templateName = (scope, group, file) => `${scope}/${group}/${file.split('/').map(segment => segment.replace(/^\./, '')).join('/')}`;
+const onSide = (scope, file) => (scope === APP_SCOPE ? file : `${scope}/${file}`);
 
 /**
- * Every target of `profile`: the files the manifest's managedBy slots list, then the unlisted ones. A slot that names
- * managedBy lists literal files only, and each has a template under its profile or under common.
+ * 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(profile, { manifest = loadSlotManifest(), readTemplate = readBundled, hasTemplate = name => fs.existsSync(path.join(TEMPLATES_DIR, name)) } = {}) {
+export function targetsOf(scope, { 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(profile)) continue;
+    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 = [profile, '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 ${profile}, but templates/{${profile},common}/${slot.managedBy} has no template for it`);
+      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 });
     }
   }
-  return [...listed, ...UNLISTED_TARGETS.filter(target => target.template[profile]).map(target => ({ path: target.path, template: target.template[profile], mode: target.mode }))];
+  return [...listed, ...(scope === APP_SCOPE ? UNLISTED_TARGETS.map(target => ({ ...target })) : [])];
 }
 
-const KEBAB = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const lf = text => text.replace(/\r\n/g, '\n');
 export const hashOf = text => createHash('sha256').update(lf(text)).digest('hex');
 
-/** The hfs.json shape sync reads: the manifest major, profile, project and a non-empty apps list (a back end names each app's kind). */
+/**
+ * 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
+ * lint unable to start. Answers the resolved app.
+ */
 export function validateHfs(hfs, manifest = loadSlotManifest()) {
-  const bad = message => { throw new SyncError('HFS_SYNC_HFS_INVALID', message); };
-  if (!hfs || typeof hfs !== 'object') bad('hfs.json is not an object');
-  if (hfs.hfs !== manifest.major) bad(`hfs must be ${manifest.major}, the major of the slot manifest`);
-  if (!PROFILES.includes(hfs.profile)) bad(`profile must be one of ${PROFILES.join(', ')}`);
-  if (typeof hfs.project !== 'string' || !KEBAB.test(hfs.project)) bad('project must be a kebab-case name');
-  if (!Array.isArray(hfs.apps) || hfs.apps.length === 0) bad('apps must list at least one app');
-  if (hfs.stacks !== undefined) {
-    if (hfs.profile !== 'fe') bad('stacks is a front-end field: a back-end repository owns its own .starcistacks declaration');
-    if (typeof hfs.stacks !== 'string' || !hfs.stacks || path.isAbsolute(hfs.stacks)) bad('stacks must be a relative path to the sibling back-end repository that owns .starcistacks');
-  }
-  const seen = new Set();
-  for (const app of hfs.apps) {
-    if (!app || typeof app.name !== 'string' || !KEBAB.test(app.name)) bad('every app needs a kebab-case name');
-    if (seen.has(app.name)) bad(`app ${app.name} is listed twice`);
-    if (hfs.profile === 'be' && !manifest.appKinds.be.includes(app.kind)) bad(`app ${app.name} needs a kind, one of ${manifest.appKinds.be.join(', ')}`);
-    seen.add(app.name);
-  }
-  // The whole declaration must be valid for the manifest it pins (connections, optional slots, ...): sync never renders
-  // configs for a declaration the eslint canons and hfs check would refuse, so a pin bump cannot leave lint unable to start.
   try {
-    resolveRepoDeclaration(manifest, hfs);
+    return resolveRepoDeclaration(manifest, hfs);
   } catch (error) {
-    bad(`hfs.json is not a valid declaration for manifest ${manifest.version}: ${error.message}`);
+    throw new SyncError('HFS_SYNC_HFS_INVALID', `hfs.json is not a valid app declaration for manifest ${manifest.version}: ${error.message}`);
   }
-  return hfs;
 }
 
 function readBundled(name) {
@@ -110,9 +98,8 @@ export function render(text, vars, readTemplate = readBundled) {
   });
 }
 
-/** The Sonar exclusions from the jest preset a back end installs: { sonarExclusions }; a front end has no test runner and no preset: null. */
-export async function loadPresets(root, profile) {
-  if (profile === 'fe') return null;
+/** The Sonar exclusions from the jest preset the app installs for its be side: { sonarExclusions }. */
+export async function loadPresets(root) {
   const name = '@starci/jest-preset';
   const require = createRequire(path.join(root, 'package.json'));
   let resolved;
@@ -126,38 +113,50 @@ export async function loadPresets(root, profile) {
 }
 
 /**
- * The package.json script lines the apps add, each ending with a comma (the template puts them mid-object). A back end:
- * `start:<app>` runs a built api, worker or cli app, `migrate` the migrate app. A front end: `dev:<app>` and `start:<app>`
- * run the app's own script through its workspace path (the npm workspace of apps/<app>).
+ * 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.
  */
-export function appScripts(profile, apps) {
+export function appScripts(app) {
   const line = (name, command) => `${JSON.stringify(name)}: ${JSON.stringify(command)},`;
-  if (profile === 'fe') return apps.flatMap(app => [line(`dev:${app.name}`, `npm run dev --workspace apps/${app.name}`), line(`start:${app.name}`, `npm run start --workspace apps/${app.name}`)]).join('\n    ');
-  const migrates = apps.filter(app => app.kind === 'migrate');
-  return apps.map(app => {
-    const name = app.kind === 'migrate' ? (migrates.length === 1 ? 'migrate' : `migrate:${app.name}`) : `start:${app.name}`;
-    return line(name, `node dist/apps/${app.name}/src/main.js`);
-  }).join('\n    ');
+  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 watch = entry => `cd be && ts-node-dev --respawn -r tsconfig-paths/register apps/${entry.name}/src/main.ts`;
+  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 && next dev apps/${fe[0].name}`)] : fe.map(entry => line(`dev:fe:${entry.name}`, `npm run codegen --silent && cd fe && next dev apps/${entry.name}`))),
+    ...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 && next start apps/${entry.name}`)),
+  ].join('\n    ');
 }
 
-/** True when hfs.json opts into a workspace package (repo.packages or any fe.package.* slot): the sources then include packages/. */
-export const opensPackages = hfs => (hfs.optionalSlots ?? []).some(id => id === 'repo.packages' || String(id).startsWith('fe.package.'));
+/** 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.'));
 
-/** The stylesheets of a front end the CSS canon judges: every app and every workspace package (slot fe.route, 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';
 
-/** Every value a template can name, derived from hfs.json and the presets. */
-export function variables(hfs, presets, sonarKey) {
-  const packages = hfs.profile === 'fe' && opensPackages(hfs);
+/** Every value a template of `scope` can name, derived from hfs.json and the presets. */
+export function variables(app, scope, presets, sonarKey) {
+  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'] : [])];
   return {
-    header: HEADER(hfs.profile),
-    appScripts: appScripts(hfs.profile, hfs.apps),
-    profile: hfs.profile,
+    header: HEADER(scope),
+    appScripts: appScripts(app),
+    buildFe: ['npm run codegen --silent', ...(packages ? ['npm run build --workspaces --if-present'] : []), `cd fe && ${fe.apps.map(entry => `next build apps/${entry.name}`).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(' && '),
     nodeMajor: String(NODE_MAJOR),
-    sonarKey: sonarKey ?? `${hfs.project}-${hfs.profile === 'be' ? 'backend' : 'fe'}`,
-    sonarExclusions: presets?.sonarExclusions ?? '',
-    tsconfigPaths: [...hfs.apps.map(app => `apps/${app.name}/tsconfig.json`), ...(packages ? ['packages/*/tsconfig.json'] : [])].join(','),
-    sonarRoots: packages ? 'apps,packages' : 'apps',
+    sonarKey: sonarKey ?? app.project,
+    sonarExclusions: [presets?.sonarExclusions, '**/.next/**', '**/node_modules/**', '**/src/messages/**'].filter(Boolean).join(','),
+    sonarSources: ['be/apps', 'be/src', 'fe/apps', ...(packages ? ['fe/packages'] : [])].join(','),
+    tsconfigPaths: ['be/tsconfig.json', ...feTsconfigs].join(','),
     styleGlob: STYLE_GLOB,
   };
 }
@@ -175,23 +174,27 @@ function parseScripts(text) {
 }
 
 /**
- * The managed content of every target this profile owns: [{ path, mode, content, hash }] (a scripts target also carries
- * `scripts`, the parsed block). `sonarKey` is the key the repository's stack declaration names; without one the key is
- * derived from hfs.json.
+ * The managed content of every target of the app: [{ path, mode, content, hash, scope }], paths app-relative (a side's targets under
+ * 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() } = {}) {
-  validateHfs(hfs, manifest);
-  const vars = variables(hfs, presets, sonarKey);
-  return targetsOf(hfs.profile, { manifest, readTemplate, hasTemplate: name => { try { return readTemplate(name) !== undefined; } catch { return false; } } }).map(target => {
-    const body = render(readTemplate(target.template), vars, readTemplate);
-    if (target.mode === 'scripts') {
-      const scripts = parseScripts(body);
-      if (!scripts) throw new SyncError('HFS_SYNC_TEMPLATE_VARIABLE', `the rendered ${target.template} has no scripts object`);
-      const content = scriptsText(scripts);
-      return { path: target.path, mode: 'scripts', content, hash: hashOf(content), scripts };
-    }
-    const managed = target.mode === 'block' ? `${BLOCK_BEGIN}\n${body.replace(/\n*$/, '\n')}${BLOCK_END}\n` : body;
-    return { path: target.path, mode: target.mode, content: managed, hash: hashOf(managed) };
+  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);
+    return targetsOf(scope, { manifest, hasTemplate }).map(target => {
+      const body = render(readTemplate(target.template), vars, readTemplate);
+      const where = onSide(scope, target.path);
+      if (target.mode === 'scripts') {
+        const scripts = parseScripts(body);
+        if (!scripts) throw new SyncError('HFS_SYNC_TEMPLATE_VARIABLE', `the rendered ${target.template} has no scripts object`);
+        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;
+      return { path: where, scope, mode: target.mode, content: managed, hash: hashOf(managed) };
+    });
   });
 }
 
@@ -256,42 +259,37 @@ export function writeTargets(root, targets) {
   return written;
 }
 
+/** The hfs.json object of the app at `root` (validated), or a SyncError. */
 export function loadHfs(root) {
   const file = path.join(root, 'hfs.json');
-  if (!fs.existsSync(file)) throw new SyncError('HFS_SYNC_HFS_INVALID', `${file} does not exist`);
+  if (!fs.existsSync(file)) throw new SyncError('HFS_SYNC_HFS_INVALID', `${file} does not exist; hfs sync runs at the app root`);
+  let hfs;
   try {
-    return validateHfs(JSON.parse(fs.readFileSync(file, 'utf8')));
+    hfs = JSON.parse(fs.readFileSync(file, 'utf8'));
   } catch (error) {
-    if (error instanceof SyncError) throw error;
     throw new SyncError('HFS_SYNC_HFS_INVALID', `${file} is not valid JSON: ${error.message}`);
   }
+  validateHfs(hfs);
+  return hfs;
 }
 
-/** The rendered targets of the repository at `root`: its hfs.json, the Sonar key its stack declaration names, the presets it installs. */
+/** 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);
-  const sonarKey = await readDeclaredSonarKey(root, { parseYaml, stacks: hfs.stacks, fail: message => { throw new SyncError('HFS_SYNC_SONAR_KEY', message); } });
-  return { hfs, targets: renderTargets(hfs, presets ?? await loadPresets(root, hfs.profile), { sonarKey }) };
+  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 }) };
 }
 
-/** `hfs sync --check | --write [--root <dir>]`; returns the exit code (0 clean, 1 drift or error, 2 usage). */
+/** `hfs sync --check | --write [--root <dir>]` at the app root; returns the exit code (0 clean, 1 drift or error, 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'), init = argv.includes('--init');
+  const check = argv.includes('--check'), write = argv.includes('--write');
   const rootAt = argv.indexOf('--root');
-  if ([check, write, init].filter(Boolean).length !== 1) {
-    out('usage: hfs sync (--check | --write | --init) [--root <dir>]');
+  if ([check, write].filter(Boolean).length !== 1) {
+    out('usage: hfs sync (--check | --write) [--root <dir>]');
     return 2;
   }
   const root = rootAt >= 0 ? path.resolve(cwd, argv[rootAt + 1] ?? '') : cwd;
   try {
-    const hfs = loadHfs(root);
-    if (init) {
-      const { initSkeleton } = await import('./skeleton.mjs');
-      const { created, skipped } = initSkeleton(root, hfs);
-      for (const file of created) out(`created ${file}`);
-      out(`hfs sync --init: ${created.length} created, ${skipped.length} already exist and were left alone`);
-      return 0;
-    }
     const { targets } = await renderRepo(root, { presets, parseYaml });
     if (write) {
       const written = writeTargets(root, targets);

package/sync/managed.mjs

@@ -72,14 +72,15 @@ function driftFindings(repoRoot, targets) {
   for (const result of checkTargets(repoRoot, targets)) {
     const target = targets.find(candidate => candidate.path === result.path);
     if (!fs.existsSync(path.join(repoRoot, result.path)) || result.status === 'ok') continue;
-    if (result.path === TS_STRICT_FILE) {
-      const flags = tsStrictFindings(fs.readFileSync(path.join(repoRoot, result.path), 'utf8'), target.content);
+    // A side's tsconfig.json (be/tsconfig.json, fe/tsconfig.json: the side's own root) is judged by flag (R22).
+    if (target.scope !== 'app' && result.path === `${target.scope}/${TS_STRICT_FILE}`) {
+      const flags = tsStrictFindings(fs.readFileSync(path.join(repoRoot, result.path), 'utf8'), target.content, result.path);
       if (flags.length) {
         findings.push(...flags);
         continue;
       }
     }
-    const code = target.mode === 'block' ? 'HFS_GITIGNORE_BLOCK_DRIFT' : ONE_LINER_FILES.has(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' : 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"` });
@@ -87,9 +88,9 @@ function driftFindings(repoRoot, targets) {
   return findings;
 }
 
-/** R11: the quality gate the stack declaration names is the one gate of the bundled knowledge/sonar-gate.yaml. */
-function sonarGateFindings(repoRoot, hfs, parseYaml) {
-  const declared = readDeclaredSonarGate(repoRoot, { parseYaml, stacks: hfs.stacks });
+/** 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) {
+  const declared = readDeclaredSonarGate(repoRoot, { parseYaml });
   if (declared === null) return [];
   const gate = (parseYaml ?? bundledParseYaml)(fs.readFileSync(SONAR_GATE_FILE, 'utf8'))?.gate?.name;
   if (declared.qualityGate === gate) return [];
@@ -160,9 +161,9 @@ export async function managedFindings({ repoRoot, tracked, presets, parseYaml })
     if (error instanceof SyncError && error.code === 'HFS_SYNC_HFS_INVALID') return [];
     throw error;
   }
-  const { hfs, targets } = rendered;
+  const { targets } = rendered;
   const findings = driftFindings(repoRoot, targets);
-  findings.push(...sonarGateFindings(repoRoot, hfs, parseYaml));
+  findings.push(...sonarGateFindings(repoRoot, parseYaml));
   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

@@ -1,13 +1,16 @@
-// The Sonar project key of a repository: read from its stack declaration (.starcistacks/application-stacks.yaml,
-// services.sonar.projects[]) when one exists, so there is one source of the key. Only when no declaration names this
-// repository does sync derive `<project>-backend` / `<project>-fe`.
+// The Sonar project key of an app: read from its stack declaration (be/.starcistacks/application-stacks.yaml,
+// services.sonar.projects[]) when one names the app, so there is one source of the key. Only when no declaration names the app
+// does sync derive the key from the project name.
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseYaml as bundledParseYaml } from '../runtime/engine/yaml.mjs';
 
-export const DECLARATION = path.join('.starcistacks', 'application-stacks.yaml');
+/** The side folder that holds an app's stack declaration. */
+export const STACKS_SIDE = 'be';
+/** The stack declaration, app-relative. */
+export const DECLARATION = path.join(STACKS_SIDE, '.starcistacks', 'application-stacks.yaml');
 
-/** The repository name the declaration lists its projects under: package.json name, else the folder name. */
+/** The repository name the declaration lists its projects under: the app package.json name, else the folder name. */
 export function repositoryName(root) {
   try {
     const name = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name;
@@ -26,31 +29,26 @@ export function declaredSonarKeys(declaration, repository) {
 }
 
 /**
- * The declared key, or null when the repository has no declaration or the declaration names none for it.
- * `stacks` is hfs.json's optional path to the sibling repository that owns the declaration (a front-end repository has
- * none of its own); the key is still looked up under THIS repository's name. A `stacks` path with no declaration behind it
- * is refused, because the key would silently fall back to a derived one.
- * `parseYaml(text)` is injected; the default is the YAML parser bundled in this package (the package installs with no node_modules).
+ * The declared key of the app at `root`, or null when the app has no stack declaration or the declaration names none for it.
+ * Two keys for one app are refused through `fail`. `parseYaml(text)` is injected; the default is the YAML parser bundled in this
+ * package (the package installs with no node_modules).
  */
-export async function readDeclaredSonarKey(root, { parseYaml, fail, stacks }) {
-  const file = path.join(stacks === undefined ? root : path.resolve(root, stacks), DECLARATION);
-  if (!fs.existsSync(file)) {
-    if (stacks !== undefined) fail(`hfs.json stacks points at ${stacks}, which has no ${DECLARATION}`);
-    return null;
-  }
+export async function readDeclaredSonarKey(root, { parseYaml, fail }) {
+  const file = path.join(root, DECLARATION);
+  if (!fs.existsSync(file)) return null;
   const parse = parseYaml ?? bundledParseYaml;
   const keys = declaredSonarKeys(parse(fs.readFileSync(file, 'utf8')), repositoryName(root));
-  if (keys.length > 1) fail(`${DECLARATION} declares ${keys.length} Sonar projects for ${repositoryName(root)} (${keys.join(', ')}); one repository has one key`);
+  if (keys.length > 1) fail(`${DECLARATION.split(path.sep).join('/')} declares ${keys.length} Sonar projects for ${repositoryName(root)} (${keys.join(', ')}); one app has one key`);
   return keys[0] ?? null;
 }
 
 /**
- * The quality gate the declaration names for Sonar: `{ file, qualityGate }`, or null when there is no declaration, Sonar is
- * disabled in it, or it declares no Sonar service. The one gate is knowledge/sonar-gate.yaml; a repository names it and
- * never states thresholds of its own.
+ * The quality gate the declaration names for Sonar: `{ file, qualityGate }` (file app-relative), or null when there is no
+ * declaration, Sonar is disabled in it, or it declares no Sonar service. The one gate is knowledge/sonar-gate.yaml; an app names it
+ * and never states thresholds of its own.
  */
-export function readDeclaredSonarGate(root, { parseYaml, stacks } = {}) {
-  const file = path.join(stacks === undefined ? root : path.resolve(root, stacks), DECLARATION);
+export function readDeclaredSonarGate(root, { parseYaml } = {}) {
+  const file = path.join(root, DECLARATION);
   if (!fs.existsSync(file)) return null;
   const sonar = (parseYaml ?? bundledParseYaml)(fs.readFileSync(file, 'utf8'))?.services?.sonar;
   if (!sonar || sonar.mode === 'disabled') return null;

package/templates/{be → app}/ci-workflows/github/workflows/ci.yml

@@ -29,8 +29,10 @@ jobs:
         run: npm run typecheck
       - name: unit
         run: npm test -- --ci
-      - name: build
-        run: npm run build
+      - name: build be
+        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:

package/templates/app/gitignore

@@ -0,0 +1,6 @@
+{{> common/gitignore.base}}
+# be: the schema Nest writes when it boots GraphQL
+schema.gql
+# fe: Next build output and its generated type file
+.next/
+next-env.d.ts

package/templates/app/hooks/husky/pre-commit

@@ -0,0 +1,25 @@
+{{header}}
+# Commit gate: the secrets guard and work hygiene of the staged files, types, lint and format of the staged files of each side,
+# stylelint over the staged CSS of fe, the unit specs of be the staged files touch. Never integration, e2e or contract.
+npx hfs work-hygiene
+npm run typecheck
+be=$(git diff --cached --name-only --diff-filter=ACMR --relative=be -- '*.ts' '*.mts' '*.cts' '*.js' '*.mjs' '*.cjs' || true)
+if [ -n "$be" ]; then
+  (cd be && npx eslint $be)
+fi
+fe=$(git diff --cached --name-only --diff-filter=ACMR --relative=fe -- '*.ts' '*.tsx' '*.mts' '*.cts' '*.js' '*.jsx' '*.mjs' '*.cjs' || true)
+if [ -n "$fe" ]; then
+  (cd fe && npx eslint --max-warnings=0 --no-warn-ignored $fe)
+fi
+styles=$(git diff --cached --name-only --diff-filter=ACMR --relative=fe -- '*.css' || true)
+if [ -n "$styles" ]; then
+  (cd fe && npx stylelint $styles)
+fi
+formatted=$(git diff --cached --name-only --diff-filter=ACMR || true)
+if [ -n "$formatted" ]; then
+  npx prettier --check --ignore-unknown $formatted
+fi
+specs=$(git diff --cached --name-only --diff-filter=ACMR --relative=be -- '*.ts' | grep -v -E '(^|/)src/tests/(world|integration|e2e|contract)/|\.(integration|e2e|contract)-spec\.ts$' || true)
+if [ -n "$specs" ]; then
+  npm run test:affected -- --findRelatedTests $specs
+fi

package/templates/app/hooks/husky/pre-push

@@ -0,0 +1,7 @@
+{{header}}
+# Push gate: types, lint (one `hfs lint`: eslint per side, the app checks, stylelint over fe), format, the unit specs of be affected
+# since main. Never integration, e2e or contract.
+npm run typecheck
+npm run lint
+npm run format:check
+npm run test:affected -- --changedSince=origin/main

package/templates/app/package-scripts/package.json

@@ -0,0 +1,22 @@
+{
+  "scripts": {
+    "prepare": "husky",
+    {{appScripts}}
+    "build:be": "cd be && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "build:fe": "{{buildFe}}",
+    "codegen": "node scripts/codegen.mjs",
+    "typecheck": "{{typecheck}}",
+    "typecheck:tests": "tsc -p be/src/tests/tsconfig.json",
+    "lint": "npm run codegen --silent && hfs lint",
+    "lint:fix": "npm run codegen --silent && hfs lint --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "cd be && jest --selectProjects unit --coverage",
+    "test:affected": "cd be && jest --selectProjects unit --passWithNoTests",
+    "test:integration": "npm run typecheck:tests && cd be && jest --selectProjects integration",
+    "test:e2e": "npm run typecheck:tests && cd be && jest --selectProjects e2e",
+    "test:contract": "npm run typecheck:tests && cd be && jest --selectProjects contract",
+    "test:stack": "cd be && starci-test-stack",
+    "contract:emit": "hfs emit-contracts"
+  }
+}

package/templates/{be → app}/quality-config/sonar-project.properties

@@ -1,9 +1,10 @@
 {{header}}
 sonar.projectKey={{sonarKey}}
 sonar.sourceEncoding=UTF-8
-sonar.sources=apps,src
-sonar.tests=apps,src
+sonar.sources={{sonarSources}}
+sonar.tests=be/apps,be/src
 sonar.exclusions={{sonarExclusions}}
 sonar.test.inclusions=**/*.spec.ts
+sonar.typescript.tsconfigPaths={{tsconfigPaths}}
 sonar.externalIssuesReportPaths=reports/lint.sonar.json
 sonar.nodejs.maxspace=8192

package/templates/app/skeleton/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{json,yml,yaml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

package/templates/app/skeleton/.gitattributes

@@ -0,0 +1,2 @@
+* text=auto
+*.enc binary

package/templates/app/skeleton/.nvmrc

@@ -0,0 +1 @@
+22

package/templates/app/skeleton/.starciwork/features/index.yaml

@@ -0,0 +1,7 @@
+schema: work/catalog@1
+id: {{project}}
+description: Product catalog of the features directory. One entry per feature; every record of a feature lives under its directory.
+features:
+  - id: system-health
+    directory: features/system-health
+    description: The liveness probe the platform asks before it routes traffic to the app.

package/templates/app/skeleton/.starciwork/workspace.yaml

@@ -0,0 +1,9 @@
+schema: work/workspace@1
+id: {{project}}
+project: {{project}}
+description: The Work records of {{project}}, one StarCi app with its back end in be/ and its front end in fe/.
+repositories:
+  - role: be
+    name: be
+  - role: fe
+    name: fe