@starci/hfs 1.0.0

package/runtime/scripts/lib/path-key.mjs

@@ -0,0 +1,15 @@
+// path-key.mjs — spelling and comparing paths the way this host's filesystem does.
+import path from 'node:path';
+
+const WIN = process.platform === 'win32';
+
+/** `p` with every backslash turned into a forward slash; null and undefined read as ''. */
+export const slash = (p) => String(p ?? '').replaceAll('\\', '/');
+/** A relative path in git's spelling: forward slashes, no leading './'. */
+export const posixPath = (p) => slash(p).replace(/^\.\//, '');
+/** `p` case-folded where the filesystem ignores case (Windows). */
+export const foldCase = (p) => (WIN ? p.toLowerCase() : p);
+/** Whether two spellings name the same path on this host's filesystem. */
+export const samePath = (a, b) => foldCase(a) === foldCase(b);
+/** A path's comparable identity: absolute, forward slashes, no trailing slash, case-folded on Windows. */
+export const pathKey = (p) => foldCase(slash(path.resolve(p)).replace(/\/+$/, ''));

package/sync/cli.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// Entry for the sync-side commands: `sync` and `work-hygiene`. The @starci/hfs bin delegates here.
+import { pathToFileURL } from 'node:url';
+import { runSync } from './index.mjs';
+import { runWorkHygiene } from './hygiene.mjs';
+
+export async function main(argv) {
+  const [command, ...rest] = argv;
+  if (command === 'sync') return runSync(rest);
+  if (command === 'work-hygiene') return runWorkHygiene();
+  process.stdout.write('usage: hfs sync (--check | --write | --init) [--root <dir>] | hfs work-hygiene\n');
+  return 2;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) process.exitCode = await main(process.argv.slice(2));

package/sync/hygiene.mjs

@@ -0,0 +1,92 @@
+// hfs work-hygiene: the guard for the two trees a back end tracks besides source. A file under .starciwork must be
+// product content (the .starciwork/.gitignore allowlist admits it, so agent output is refused), and a file under
+// .starcistacks must not be a plaintext secret (only *.enc is sealed). The pre-commit hook judges the staged files;
+// scripts/checks/check-hfs-sync.mjs judges every tracked file.
+//
+// When this package runs from inside its own runtime checkout (packages/hfs lives 3 directories under the repo
+// root), it also reports the state-root ledger findings of scripts/lib/hk-orphan-ledgers.mjs: LEDGER_ORPHAN_STATE_ROOT
+// and LEDGER_LEGACY_WORK_SQLITE (COOK-BRIEF F4 handover, incident 2026-09-30). Installed standalone in a product
+// repository with no such checkout, that section is silently absent — never a crash, never a false negative claimed.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PLAINTEXT_NAME = /(^|\/)(\.env(\..*)?|[^/]*\.(pem|key|identity|age))$/;
+const GUARDED = file => file.startsWith('.starciwork/') || file.startsWith('.starcistacks/');
+
+/** The subset of `files` git ignores (as if untracked), asked in one call: a Set of paths. */
+export function ignoredAmong(cwd, files) {
+  if (files.length === 0) return new Set();
+  try {
+    const out = execFileSync('git', ['check-ignore', '--no-index', '-z', '--stdin'], { cwd, input: files.join('\0'), encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    return new Set(out.split('\0').filter(Boolean));
+  } catch (error) {
+    if (error.status === 1) return new Set();
+    throw error;
+  }
+}
+
+/** Violations among `files` (repository-relative, '/'-separated): [{ file, code, message }]. `ignored` is a Set of ignored paths. */
+export function hygieneFindings(files, ignored) {
+  const findings = [];
+  for (const file of files) {
+    if (file.startsWith('.starciwork/') && ignored.has(file)) {
+      findings.push({ file, code: 'HFS_WORK_AGENT_DATA', message: 'is agent output, which .starciwork/.gitignore refuses; keep it in the scratchpad or the blob store' });
+    }
+    if (file.startsWith('.starcistacks/') && !file.endsWith('.enc') && !file.endsWith('.env.example')) {
+      if (file.includes('/secrets/')) findings.push({ file, code: 'HFS_STACKS_PLAINTEXT', message: 'sits under secrets/ but is not sealed; only <slug>.enc may be tracked' });
+      else if (PLAINTEXT_NAME.test(file)) findings.push({ file, code: 'HFS_STACKS_PLAINTEXT', message: 'is a plaintext secret; seal it to .starcistacks/<env>/secrets/<slug>.enc' });
+    }
+  }
+  return findings;
+}
+
+const gitList = (cwd, args) => execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }).split('\0').filter(Boolean);
+
+/** Files staged for the next commit (added, copied, modified, renamed). */
+export const stagedFiles = cwd => gitList(cwd, ['diff', '--cached', '--name-only', '--diff-filter=ACMR', '-z']);
+
+/** Every tracked file. */
+export const trackedFiles = cwd => gitList(cwd, ['ls-files', '-z']);
+
+/** Findings for `files` after keeping only the guarded trees. */
+export function judge(cwd, files) {
+  const guarded = files.filter(GUARDED);
+  return { checked: guarded.length, findings: hygieneFindings(guarded, ignoredAmong(cwd, guarded.filter(file => file.startsWith('.starciwork/')))) };
+}
+
+// The sibling scripts/checks/ledger-hygiene.mjs, 3 directories up from this file when it runs inside its own full
+// runtime checkout (packages/hfs/sync/ -> ../../.. is the repo root, the same computation
+// packages/hfs/scripts/sync-runtime.mjs uses). Installed standalone (no such checkout), it does not exist and this
+// section is silently absent — never a crash, never a false claim about a store this install cannot see.
+const RUNTIME_LEDGER_HYGIENE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'scripts', 'checks', 'ledger-hygiene.mjs');
+
+/**
+ * The state-root ledger findings (LEDGER_ORPHAN_STATE_ROOT, LEDGER_LEGACY_WORK_SQLITE) as {code, file, message}
+ * entries, when this install can reach the sibling runtime script; [] otherwise. Never throws: a report failure is
+ * one HFS_LEDGER_HYGIENE_UNAVAILABLE finding, not a crash of `hfs work-hygiene`.
+ */
+export async function ledgerHygieneFindings() {
+  if (!fs.existsSync(RUNTIME_LEDGER_HYGIENE)) return [];
+  try {
+    const { ledgerHygieneReport } = await import(pathToFileURL(RUNTIME_LEDGER_HYGIENE).href);
+    const report = await ledgerHygieneReport({ apply: false });
+    return [
+      ...report.orphans.map(o => ({ code: o.code, file: o.ledgerId, message: `ledger ${o.name ?? o.ledgerId} - ${o.reason}; source roots: ${o.sourceRoots.join(', ') || '(none)'}` })),
+      ...report.legacy.map(l => ({ code: l.code, file: l.repoRoot, message: `${l.files.length} legacy file(s) still in the repo: ${l.files.join(', ')}` })),
+    ];
+  } catch (error) {
+    return [{ code: 'HFS_LEDGER_HYGIENE_UNAVAILABLE', file: RUNTIME_LEDGER_HYGIENE, message: `could not run: ${String(error?.message ?? error).slice(0, 200)}` }];
+  }
+}
+
+/** `hfs work-hygiene`: checks the staged files, plus the state-root ledger findings when reachable; returns the exit code. */
+export async function runWorkHygiene({ cwd = process.cwd(), out = line => process.stdout.write(`${line}\n`), files } = {}) {
+  const { checked, findings } = judge(cwd, files ?? stagedFiles(cwd));
+  const ledgerFindings = await ledgerHygieneFindings();
+  const all = [...findings, ...ledgerFindings];
+  for (const finding of all) out(`${finding.code} ${finding.file} ${finding.message}`);
+  out(`hfs work-hygiene: ${checked} staged file(s) checked, ${findings.length} finding(s), ${ledgerFindings.length} ledger finding(s)`);
+  return all.length ? 1 : 0;
+}

package/sync/index.mjs

@@ -0,0 +1,224 @@
+// hfs sync: render, verify and write the files a product repository cannot `extends`.
+//
+// The generated set (target table below) is husky, both GitHub workflows, .gitignore, sonar-project.properties,
+// codecov.yml and, for a back end, .starciwork/.gitignore. Every file is rendered from templates/ with the
+// repository's hfs.json (profile and apps) and, for the coverage denominators, the same jest/vitest preset the
+// 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.
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+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']);
+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".\n`;
+
+export class SyncError extends Error {
+  constructor(code, message) {
+    super(`${code}: ${message}`);
+    this.code = code;
+  }
+}
+
+// mode: file = whole file, block = the marked block inside a file the repository also writes to.
+// header: whether the generated-by comment leads the content (.starciwork/.gitignore is byte-exact instead).
+export const TARGETS = Object.freeze([
+  { path: '.husky/pre-commit', template: { be: 'be/pre-commit', fe: 'fe/pre-commit' }, mode: 'file', header: true },
+  { path: '.husky/pre-push', template: { be: 'common/pre-push', fe: 'common/pre-push' }, mode: 'file', header: true },
+  { path: '.github/workflows/ci.yml', template: { be: 'common/ci.yml', fe: 'common/ci.yml' }, mode: 'file', header: true },
+  { path: '.github/workflows/e2e.yml', template: { be: 'be/e2e.yml', fe: 'fe/e2e.yml' }, mode: 'file', header: true },
+  { path: '.gitignore', template: { be: 'be/gitignore', fe: 'fe/gitignore' }, mode: 'block', header: false },
+  { path: 'sonar-project.properties', template: { be: 'be/sonar-project.properties', fe: 'fe/sonar-project.properties' }, mode: 'file', header: true },
+  { path: 'codecov.yml', template: { be: 'common/codecov.yml', fe: 'common/codecov.yml' }, mode: 'file', header: true },
+  { path: '.starciwork/.gitignore', template: { be: 'be/starciwork.gitignore' }, mode: 'file', header: false },
+].map(Object.freeze));
+
+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: hfs 2, profile, project and a non-empty apps list. */
+export function validateHfs(hfs) {
+  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 !== 2) bad('hfs must be 2');
+  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`);
+    seen.add(app.name);
+  }
+  return hfs;
+}
+
+function readBundled(name) {
+  return lf(fs.readFileSync(path.join(TEMPLATES_DIR, name), 'utf8'));
+}
+
+/** Fill `{{name}}` from vars and expand `{{> partial}}` lines. 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'));
+  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];
+  });
+}
+
+/** Coverage denominators from the preset the repository installs: { sonarExclusions, sonarCoverageExclusions }. */
+export async function loadPresets(root, profile) {
+  const name = profile === 'be' ? '@starci/jest-preset' : '@starci/vitest-preset';
+  const require = createRequire(path.join(root, 'package.json'));
+  let resolved;
+  try {
+    resolved = require.resolve(name);
+  } 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 = profile === 'be' ? require(resolved) : await import(pathToFileURL(resolved).href);
+  return { sonarExclusions: preset.sonarExclusions(), sonarCoverageExclusions: preset.sonarCoverageExclusions() };
+}
+
+/** Every value a template can name, derived from hfs.json and the presets. */
+export function variables(hfs, presets, sonarKey) {
+  const globs = [...presets.sonarExclusions.split(','), ...presets.sonarCoverageExclusions.split(',')];
+  return {
+    profile: hfs.profile,
+    nodeMajor: String(NODE_MAJOR),
+    sonarKey: sonarKey ?? `${hfs.project}-${hfs.profile === 'be' ? 'backend' : 'fe'}`,
+    sonarExclusions: presets.sonarExclusions,
+    sonarCoverageExclusions: presets.sonarCoverageExclusions,
+    codecovIgnore: globs.map(glob => JSON.stringify(glob)).join('\n  - '),
+    tsconfigPaths: hfs.apps.map(app => `apps/${app.name}/tsconfig.json`).join(','),
+  };
+}
+
+/** The managed content of every target this profile owns: [{ path, mode, content, hash }]. */
+/** `sonarKey` is the key the repository's stack declaration names; without one the key is derived from hfs.json. */
+export function renderTargets(hfs, presets, { sonarKey, readTemplate = readBundled } = {}) {
+  validateHfs(hfs);
+  const vars = variables(hfs, presets, sonarKey);
+  return TARGETS.filter(target => target.template[hfs.profile]).map(target => {
+    const body = render(readTemplate(target.template[hfs.profile]), vars, readTemplate);
+    const content = target.header ? HEADER(hfs.profile) + body : body;
+    const managed = target.mode === 'block' ? `${BLOCK_BEGIN}\n${content.replace(/\n*$/, '\n')}${BLOCK_END}\n` : content;
+    return { path: target.path, mode: target.mode, content: managed, hash: hashOf(managed) };
+  });
+}
+
+// The part of a file sync manages: all of it, or the marked block.
+function managedPart(mode, text) {
+  if (mode === 'file') return text;
+  const start = text.indexOf(BLOCK_BEGIN);
+  const end = text.indexOf(BLOCK_END);
+  if (start < 0 || end < start) return null;
+  const stop = text.indexOf('\n', end);
+  return text.slice(start, stop < 0 ? text.length : stop + 1);
+}
+
+function firstDifference(expected, actual) {
+  const want = expected.split('\n'), have = actual.split('\n');
+  for (let index = 0; index < Math.max(want.length, have.length); index += 1) {
+    if (want[index] !== have[index]) return { line: index + 1, expected: want[index] ?? '(end of file)', actual: have[index] ?? '(end of file)' };
+  }
+  return null;
+}
+
+/** Compare every rendered target with the disk: [{ path, status: ok | missing | drift, expectedHash, actualHash?, difference? }]. */
+export function checkTargets(root, targets) {
+  return targets.map(target => {
+    const file = path.join(root, target.path);
+    if (!fs.existsSync(file)) return { path: target.path, status: 'missing', expectedHash: target.hash };
+    const part = managedPart(target.mode, lf(fs.readFileSync(file, 'utf8')));
+    if (part === null) return { path: target.path, status: 'missing', expectedHash: target.hash };
+    const actualHash = hashOf(part);
+    if (actualHash === target.hash) return { path: target.path, status: 'ok', expectedHash: target.hash, actualHash };
+    return { path: target.path, status: 'drift', expectedHash: target.hash, actualHash, difference: firstDifference(target.content, part) };
+  });
+}
+
+/** Rewrite the missing or drifted targets; returns the paths written. */
+export function writeTargets(root, targets) {
+  const written = [];
+  for (const result of checkTargets(root, targets)) {
+    if (result.status === 'ok') continue;
+    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 === 'block' && existing) {
+      const current = managedPart('block', existing);
+      next = current === null ? `${target.content}\n${existing}` : existing.replace(current, () => target.content);
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, next);
+    written.push(target.path);
+  }
+  return written;
+}
+
+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`);
+  try {
+    return validateHfs(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}`);
+  }
+}
+
+/** `hfs sync --check | --write [--root <dir>]`; 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 rootAt = argv.indexOf('--root');
+  if ([check, write, init].filter(Boolean).length !== 1) {
+    out('usage: hfs sync (--check | --write | --init) [--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 sonarKey = await readDeclaredSonarKey(root, { parseYaml, stacks: hfs.stacks, fail: message => { throw new SyncError('HFS_SYNC_SONAR_KEY', message); } });
+    const targets = renderTargets(hfs, presets ?? await loadPresets(root, hfs.profile), { sonarKey });
+    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`);
+      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(`hfs sync --check: ${results.length - bad.length} of ${results.length} in sync${bad.length ? '; run "npx hfs sync --write"' : ''}`);
+    return bad.length ? 1 : 0;
+  } catch (error) {
+    if (!(error instanceof SyncError)) throw error;
+    out(error.message);
+    return 1;
+  }
+}

package/sync/skeleton.mjs

@@ -0,0 +1,54 @@
+// hfs sync --init: the first source tree of a new repository (entrypoint, platform config/logging/errors, the health
+// endpoint; for a front end the next-intl [locale] shell with vi default, as-needed prefix and proxy.ts).
+// Unlike the managed files it is written once and never overwritten: an existing file is skipped, so re-running --init
+// on a repository that already grew its own source changes nothing.
+import fs from 'node:fs';
+import path from 'node:path';
+import { TEMPLATES_DIR, SyncError, render, validateHfs } from './index.mjs';
+
+const APP_DIR = '__app__';
+const pascal = name => name.split('-').map(part => part[0].toUpperCase() + part.slice(1)).join('');
+
+function listFiles(dir, base = dir) {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap(entry => {
+    const full = path.join(dir, entry.name);
+    return entry.isDirectory() ? listFiles(full, base) : [path.relative(base, full).split(path.sep).join('/')];
+  });
+}
+
+/** The apps that get a skeleton: a back end's `api` apps, every front-end app. */
+export const skeletonApps = hfs => hfs.apps.filter(app => hfs.profile === 'fe' || app.kind === 'api');
+
+/** Every skeleton file for this repository: [{ path, content }], the shared ones once and the per-app ones per app. */
+export function skeletonFiles(hfs, dir = path.join(TEMPLATES_DIR, hfs.profile, 'skeleton')) {
+  validateHfs(hfs);
+  if (!fs.existsSync(dir)) throw new SyncError('HFS_SYNC_SKELETON_MISSING', `no skeleton templates for profile ${hfs.profile}`);
+  const files = [];
+  for (const rel of listFiles(dir)) {
+    const source = fs.readFileSync(path.join(dir, rel), 'utf8').replace(/\r\n/g, '\n');
+    if (!rel.includes(APP_DIR)) {
+      files.push({ path: rel, content: render(source, {}) });
+      continue;
+    }
+    for (const app of skeletonApps(hfs)) {
+      files.push({ path: rel.split(APP_DIR).join(app.name), content: render(source, { app: app.name, appPascal: pascal(app.name) }) });
+    }
+  }
+  return files;
+}
+
+/** Writes the skeleton under `root`, skipping every file that exists: { created, skipped } path lists. */
+export function initSkeleton(root, hfs) {
+  const created = [], skipped = [];
+  for (const file of skeletonFiles(hfs)) {
+    const target = path.join(root, file.path);
+    if (fs.existsSync(target)) {
+      skipped.push(file.path);
+      continue;
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, file.content);
+    created.push(file.path);
+  }
+  return { created, skipped };
+}

package/sync/sonar-key.mjs

@@ -0,0 +1,45 @@
+// 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`.
+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 repository name the declaration lists its projects under: 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;
+    if (typeof name === 'string' && name) return name;
+  } catch {
+    // no readable package.json: the folder name stands in
+  }
+  return path.basename(path.resolve(root));
+}
+
+/** The keys services.sonar declares for `repository` in a parsed declaration (empty when it declares none). */
+export function declaredSonarKeys(declaration, repository) {
+  const projects = declaration?.services?.sonar?.projects;
+  if (!Array.isArray(projects)) return [];
+  return projects.filter(project => project?.repository === repository && typeof project.key === 'string' && project.key).map(project => project.key);
+}
+
+/**
+ * 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).
+ */
+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;
+  }
+  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`);
+  return keys[0] ?? null;
+}

package/templates/be/e2e.yml

@@ -0,0 +1,21 @@
+# End-to-end runs are manual: nothing triggers this workflow but a person dispatching it.
+name: e2e
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: {{nodeMajor}}
+          cache: npm
+      - run: npm ci
+      - name: e2e
+        run: npm run test:e2e

package/templates/be/gitignore

@@ -0,0 +1,2 @@
+{{> common/gitignore.base}}
+schema.gql

package/templates/be/pre-commit

@@ -0,0 +1,8 @@
+# Commit gate: staged lint, types, the unit specs the staged files touch, work hygiene. Never e2e.
+npx lint-staged
+npm run typecheck
+staged=$(git diff --cached --name-only --diff-filter=ACMR -- '*.ts' '*.tsx' | grep -v -E '(^|/)e2e/|\.e2e-spec\.ts$' || true)
+if [ -n "$staged" ]; then
+  npx jest --selectProjects unit --passWithNoTests --findRelatedTests $staged
+fi
+npx hfs work-hygiene

package/templates/be/skeleton/apps/__app__/src/__app__.composition.spec.ts

@@ -0,0 +1,31 @@
+import { INestApplication } from "@nestjs/common"
+import { Test } from "@nestjs/testing"
+import request from "supertest"
+import { SERVER_OPTIONS } from "@modules/platform/config"
+import { Logger } from "@modules/platform/logging"
+import { AppModule } from "./app.module"
+
+describe("{{app}} composition", () => {
+    let app: INestApplication
+
+    beforeAll(async () => {
+        const moduleRef = await Test.createTestingModule({ imports: [AppModule.register({ server: { port: 3000 } })] }).compile()
+        app = moduleRef.createNestApplication()
+        await app.init()
+    })
+
+    afterAll(async () => {
+        await app.close()
+    })
+
+    it("boots the real AppModule and resolves its providers", () => {
+        expect(app.get(Logger)).toBeInstanceOf(Logger)
+        expect(app.get(SERVER_OPTIONS)).toEqual({ port: 3000 })
+    })
+
+    it("answers GET /health/live with the { status, info, error, details } shape", async () => {
+        const response = await request(app.getHttpServer()).get("/health/live")
+        expect(response.status).toBe(200)
+        expect(response.body).toEqual({ status: "ok", info: {}, error: {}, details: {} })
+    })
+})

package/templates/be/skeleton/apps/__app__/src/__app__.options.ts

@@ -0,0 +1,7 @@
+import type { ServerOptions } from "@modules/platform/config"
+
+/** Everything the {{app}} app needs from its environment, parsed once by `main.ts` and handed to `AppModule.register`. */
+export interface {{appPascal}}Options {
+    /** The HTTP listener. */
+    readonly server: ServerOptions
+}

package/templates/be/skeleton/apps/__app__/src/app.module.ts

@@ -0,0 +1,23 @@
+import { DynamicModule, Module } from "@nestjs/common"
+import { APP_FILTER } from "@nestjs/core"
+import { SystemHealthModule } from "@features/system-health"
+import { SERVER_OPTIONS } from "@modules/platform/config"
+import { ErrorFilter } from "@modules/platform/errors"
+import { LoggingModule } from "@modules/platform/logging"
+import type { {{appPascal}}Options } from "./{{app}}.options"
+
+/** Composition root of the {{app}} app: the features it runs, the platform it needs and its one error filter. */
+@Module({})
+export class AppModule {
+    /** Builds the module from options parsed once at boot; nothing here reads the environment. */
+    static register(options: {{appPascal}}Options): DynamicModule {
+        return {
+            module: AppModule,
+            imports: [LoggingModule, SystemHealthModule],
+            providers: [
+                { provide: SERVER_OPTIONS, useValue: options.server },
+                { provide: APP_FILTER, useClass: ErrorFilter },
+            ],
+        }
+    }
+}

package/templates/be/skeleton/apps/__app__/src/main.ts

@@ -0,0 +1,20 @@
+import { NestFactory } from "@nestjs/core"
+import { EnvSource, parseServerConfig } from "@modules/platform/config"
+import { createJsonLogger, LogId } from "@modules/platform/logging"
+import { AppModule } from "./app.module"
+import type { {{appPascal}}Options } from "./{{app}}.options"
+
+/** Reads the environment once, composes the app from the parsed options and serves until a shutdown signal. */
+const bootstrap = async (): Promise<void> => {
+    const env = EnvSource.fromProcess()
+    const options: {{appPascal}}Options = { server: parseServerConfig(env) }
+    const app = await NestFactory.create(AppModule.register(options))
+    app.enableShutdownHooks()
+    await app.listen(options.server.port)
+}
+
+const logger = createJsonLogger()
+bootstrap().catch((cause: unknown) => {
+    logger.error(LogId.StartupFailed, { failure: cause instanceof Error ? { name: cause.name, message: cause.message } : { name: typeof cause } })
+    process.exitCode = 1
+})

package/templates/be/skeleton/src/features/system-health/index.ts

@@ -0,0 +1 @@
+export { SystemHealthModule } from "./system-health.module"

package/templates/be/skeleton/src/features/system-health/system-health.module.ts

@@ -0,0 +1,6 @@
+import { Module } from "@nestjs/common"
+import { SystemHealthHttpModule } from "./transport/http/system-health-http.module"
+
+/** Application module of the health feature: process-local liveness now, readiness with the design that declares dependencies. */
+@Module({ imports: [SystemHealthHttpModule] })
+export class SystemHealthModule {}

package/templates/be/skeleton/src/features/system-health/transport/http/live.controller.spec.ts

@@ -0,0 +1,13 @@
+import { HealthCheckService } from "@nestjs/terminus"
+import { mock } from "@starci/jest-preset/mock"
+import { LiveController } from "./live.controller"
+
+describe("LiveController", () => {
+    it("runs Terminus with no indicator, so liveness never depends on a dependency", async () => {
+        const health = mock<HealthCheckService>()
+        const result = { status: "ok" as const, info: {}, error: {}, details: {} }
+        health.check.mockResolvedValue(result)
+        await expect(new LiveController(health).live()).resolves.toEqual(result)
+        expect(health.check).toHaveBeenCalledWith([])
+    })
+})

package/templates/be/skeleton/src/features/system-health/transport/http/live.controller.ts

@@ -0,0 +1,18 @@
+import { Controller, Get } from "@nestjs/common"
+import { HealthCheck, HealthCheckResult, HealthCheckService } from "@nestjs/terminus"
+
+/** Liveness probe: answers `{ status, info, error, details }` from process-local state and never touches a dependency. */
+@Controller("health")
+export class LiveController {
+    constructor(
+        /** Terminus executor; it runs no indicator, so a dependency outage never restarts the process. */
+        private readonly health: HealthCheckService,
+    ) {}
+
+    /** Reports the process alive while its event loop still answers requests. */
+    @Get("live")
+    @HealthCheck()
+    live(): Promise<HealthCheckResult> {
+        return this.health.check([])
+    }
+}

package/templates/be/skeleton/src/features/system-health/transport/http/system-health-http.module.ts

@@ -0,0 +1,10 @@
+import { Module } from "@nestjs/common"
+import { TerminusModule } from "@nestjs/terminus"
+import { LiveController } from "./live.controller"
+
+/** The HTTP transport of the health feature. */
+@Module({
+    imports: [TerminusModule],
+    controllers: [LiveController],
+})
+export class SystemHealthHttpModule {}