@starci/hfs 4.0.8 → 4.0.10

package/runtime/scripts/hfs/rules/kinds.mjs

@@ -0,0 +1,84 @@
+// kinds.mjs - the trigger kinds a back end uses are declared, whole and generated only when used (hfs.json sides.be.kinds).
+//   BE_KIND_DECLARATION   `sides.be.kinds` lists exactly the kinds the features hold: a kind in use that is not declared, a declared kind with no
+//                         feature, a declared kind whose patterns (ruleParams.be.kindPatterns) are not all in `sides.be.patterns`, and a declared
+//                         kind whose platform capabilities (the tier-platform slots that name those patterns) are not tracked are each a finding;
+//   BE_KIND_EMPTY         a kind folder `be/src/features/<kind>/` holds only instance folders `<kind>/<x>/`, and each instance holds source: a file
+//                         directly in the kind folder (a `.gitkeep`) or an instance with no TypeScript file is a finding.
+// A kind is a folder name of `be/src/features/` read from `triggerKinds` of the slot manifest (api features live in `features/api/<feature>/`);
+// `features/cli/` is the one cli feature root (its module and group folders), so it is in use as soon as it holds a file.
+import { loadSlotManifest, ruleParams } from '../slots.mjs';
+import { found } from './read.mjs';
+
+const KIND_DECLARATION = 'BE_KIND_DECLARATION';
+const KIND_EMPTY = 'BE_KIND_EMPTY';
+
+const FEATURES = 'be/src/features/';
+const CLI = 'cli';
+
+let memo;
+/** The manifest facts the rules read: the trigger kinds, the patterns each kind needs, and the platform capability folders of each pattern. */
+const facts = () => {
+  if (memo) return memo;
+  const manifest = loadSlotManifest();
+  const platform = new Map();
+  for (const slot of manifest.slots) {
+    if (slot.pattern === undefined || slot.tier !== 'platform' || !slot.profiles.includes('be')) continue;
+    const folder = /^src\/modules\/platform\/([a-z][a-z0-9-]*)\/$/.exec(slot.path);
+    if (!folder) continue;
+    if (!platform.has(slot.pattern)) platform.set(slot.pattern, []);
+    platform.get(slot.pattern).push(folder[1]);
+  }
+  memo = { triggerKinds: manifest.triggerKinds ?? [], kindPatterns: ruleParams(manifest, 'be').kindPatterns, platform };
+  return memo;
+};
+
+/** Findings of BE_KIND_DECLARATION and BE_KIND_EMPTY. */
+export function kindFindings({ files, repo }) {
+  const be = repo.sides?.be;
+  if (!be) return [];
+  const { triggerKinds, kindPatterns, platform } = facts();
+  const kindFolders = new Set(triggerKinds);
+  const findings = [];
+  const instances = new Map();
+  const sources = new Map();
+  const roots = new Set();
+  const tracked = new Set(files);
+  for (const file of files) {
+    if (!file.startsWith(FEATURES)) continue;
+    const rest = file.slice(FEATURES.length).split('/');
+    if (rest.length < 2) continue;
+    const [first, second] = rest;
+    if (!kindFolders.has(first)) continue;
+    if (first === CLI) { roots.add(CLI); continue; }
+    if (rest.length === 2) {
+      findings.push(found(KIND_EMPTY, file, `${file} sits directly in the kind folder ${FEATURES}${first}/, which holds only instance folders (${first}/<name>/); an empty kind folder is never kept: run \`starci app add\` to create the first member.`, { kind: first }));
+      continue;
+    }
+    if (!instances.has(first)) instances.set(first, new Set());
+    instances.get(first).add(second);
+    const key = `${first}/${second}`;
+    sources.set(key, (sources.get(key) ?? 0) + (/\.[cm]?tsx?$/.test(file) ? 1 : 0));
+  }
+  for (const [key, count] of sources) {
+    if (count === 0) findings.push(found(KIND_EMPTY, `${FEATURES}${key}/`, `${FEATURES}${key}/ holds no TypeScript source: a kind member without code is an empty folder; add its files with \`starci app add\` or remove the folder.`, { kind: key.split('/')[0] }));
+  }
+  const present = new Set([...instances.keys(), ...roots]);
+  const declared = new Set(be.kinds ?? []);
+  const patterns = new Set(be.patterns ?? []);
+  for (const kind of [...present].sort()) {
+    if (!declared.has(kind)) findings.push(found(KIND_DECLARATION, 'hfs.json', `hfs.json sides.be.kinds does not declare the kind \`${kind}\`, which ${FEATURES}${kind}/ uses; declare every kind in use (\`starci app add\` registers it).`, { kind }));
+  }
+  for (const kind of [...declared].sort()) {
+    if (!present.has(kind)) {
+      findings.push(found(KIND_DECLARATION, 'hfs.json', `hfs.json sides.be.kinds declares \`${kind}\` but no feature of that kind exists; a kind is declared only when it is used, so remove it or add its first member with \`starci app add\`.`, { kind }));
+      continue;
+    }
+    for (const pattern of kindPatterns[kind] ?? []) {
+      if (!patterns.has(pattern)) findings.push(found(KIND_DECLARATION, 'hfs.json', `the kind \`${kind}\` needs the pattern \`${pattern}\`, which hfs.json sides.be.patterns does not declare.`, { kind, pattern }));
+      for (const capability of platform.get(pattern) ?? []) {
+        if (!tracked.has(`be/src/modules/platform/${capability}/index.ts`)) findings.push(found(KIND_DECLARATION, `be/src/modules/platform/${capability}/`, `the kind \`${kind}\` needs the platform capability \`${capability}\` (pattern ${pattern}), which is not tracked at be/src/modules/platform/${capability}/; \`starci app add\` generates it with the first member of the kind.`, { kind, pattern, capability }));
+      }
+    }
+  }
+  return findings;
+}

package/runtime/scripts/hfs/rules/lint-suppression.mjs

@@ -7,7 +7,7 @@
 // Comment-level suppression (`eslint-disable`) is the lint rule `no-inline-suppression`'s (R18).
 import { found, readJson, readText } from './read.mjs';
 
-export const LINT_SUPPRESSION_FILE = 'HFS_LINT_SUPPRESSION_FILE';
+const LINT_SUPPRESSION_FILE = 'HFS_LINT_SUPPRESSION_FILE';
 const SUPPRESSION_FILE = /(?:^|\/)eslint[.-]suppressions[^/]*$/;
 const SUPPRESSION_SCRIPT_NAME = /(?:^|:)suppressions$/;
 const SUPPRESSION_FLAG = /--(?:suppressions-location|suppress-all|suppress-rule|prune-suppressions)\b/;

package/runtime/scripts/hfs/rules/monorepo.mjs

@@ -0,0 +1,179 @@
+// monorepo.mjs - every product is a monorepo, even a single app: the app root holds one package.json and lockfile whose npm
+// workspaces are the fe apps and packages (turbo runs their tasks), and the back end is a Nest monorepo of be/apps/<app>.
+//   HFS_MONO_WORKSPACES          the root package.json: `workspaces` exactly fe/apps/* and fe/packages/*, `packageManager` npm at an
+//                                exact version, turbo a root devDependency (its version is the canon pin); turbo.json is app.task-graph
+//   HFS_MONO_FE_WORKSPACE        every fe app's package.json is @<project>/<app>, private, with exactly the workspace scripts; every
+//                                fe package's package.json is private with build and typecheck scripts and the workspace lint
+//   HFS_MONO_NEST_PROJECTS       be/nest-cli.json is `monorepo: true`, its root an api app, and one project per declared be app
+//   HFS_MONO_WORKSPACE_DEP       a package an fe workspace imports is declared in that workspace's package.json (a sibling workspace
+//                                package at "*"); the root package.json never declares a workspace package
+// The imports are read with TypeScript's own pre-processor (import, export-from, require and import() specifiers), and a
+// workspace's path aliases come from its tsconfig.json as TypeScript resolves it: no specifier is matched by a regular expression.
+import fs from 'node:fs';
+import { isBuiltin } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../../lib/package-at.mjs';
+import { found, readJson, readText } from './read.mjs';
+
+const MONO_WORKSPACES = 'HFS_MONO_WORKSPACES';
+const MONO_FE_WORKSPACE = 'HFS_MONO_FE_WORKSPACE';
+const MONO_NEST_PROJECTS = 'HFS_MONO_NEST_PROJECTS';
+const MONO_WORKSPACE_DEP = 'HFS_MONO_WORKSPACE_DEP';
+
+/** The npm workspaces of every app, in this order. */
+export const WORKSPACES = Object.freeze(['fe/apps/*', 'fe/packages/*']);
+/** The lint script of every fe workspace: the one lint of the app, scoped to the workspace. */
+export const WORKSPACE_LINT = 'starci app lint --workspace .';
+/** The scripts of every fe app workspace, exactly: turbo runs build, dev, lint and typecheck; start serves a build. */
+export const FE_APP_SCRIPTS = Object.freeze({ build: 'next build', dev: 'next dev', lint: WORKSPACE_LINT, start: 'next start', typecheck: 'tsc --noEmit' });
+/** The scripts every fe package workspace has (its build and typecheck commands are its own; its lint is the workspace lint). */
+const FE_PACKAGE_SCRIPTS = Object.freeze(['build', 'typecheck', 'lint']);
+/** The package manager every app root declares (turbo reads it to parse the lockfile); the starci app scaffold writes it. */
+export const PACKAGE_MANAGER = 'npm@11.6.2';
+/** The npm name of an fe app workspace. */
+export const feAppPackageName = (project, app) => `@${project}/${app}`;
+
+const MANIFEST = 'package.json';
+const NEST_CLI = 'be/nest-cli.json';
+const PACKAGE_MANAGER_FORM = /^npm@\d+\.\d+\.\d+$/;
+const DEP_SECTIONS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+const SOURCE = /\.(?:[cm]?[jt]sx?)$/;
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+const declaredIn = (pkg) => new Set(DEP_SECTIONS.flatMap((section) => Object.keys(pkg?.[section] ?? {})));
+const sameList = (a, b) => Array.isArray(a) && a.length === b.length && a.every((item, i) => item === b[i]);
+
+/** The workspace folders the tracked tree holds: fe/apps/<x> and fe/packages/<x> that track a package.json. */
+function workspacesOf(files) {
+  const folders = new Set();
+  for (const file of files) {
+    const parts = file.split('/');
+    if (parts.length === 4 && parts[0] === 'fe' && (parts[1] === 'apps' || parts[1] === 'packages') && parts[3] === MANIFEST) folders.add(parts.slice(0, 3).join('/'));
+  }
+  return [...folders].sort();
+}
+
+/** R143: the root package.json declares the workspaces, the package manager and turbo. */
+function rootFindings(repoRoot) {
+  const pkg = readJson(repoRoot, MANIFEST);
+  if (!pkg) return [];
+  const findings = [];
+  if (!sameList(pkg.workspaces, WORKSPACES)) findings.push(found(MONO_WORKSPACES, MANIFEST, `${MANIFEST} declares workspaces ${JSON.stringify(pkg.workspaces ?? null)}; every app is a monorepo whose npm workspaces are exactly ${JSON.stringify(WORKSPACES)} (each fe app and package has its own package.json; be has none).`, { workspaces: pkg.workspaces ?? null }));
+  if (!PACKAGE_MANAGER_FORM.test(String(pkg.packageManager ?? ''))) findings.push(found(MONO_WORKSPACES, MANIFEST, `${MANIFEST} declares packageManager ${JSON.stringify(pkg.packageManager ?? null)}; turbo needs \`npm@<exact version>\` there.`, { packageManager: pkg.packageManager ?? null }));
+  if (typeof pkg.devDependencies?.turbo !== 'string') findings.push(found(MONO_WORKSPACES, MANIFEST, `${MANIFEST} does not declare turbo in its devDependencies; the turbo task graph (turbo.json) runs build, dev, lint and typecheck over the fe workspaces.`, { missing: 'turbo' }));
+  return findings;
+}
+
+/** R144: the manifest of each fe workspace. */
+function workspaceManifestFindings(repoRoot, project, workspaces) {
+  const findings = [];
+  for (const folder of workspaces) {
+    const file = `${folder}/${MANIFEST}`;
+    const pkg = readJson(repoRoot, file);
+    if (!pkg) { findings.push(found(MONO_FE_WORKSPACE, file, `${file} is not readable JSON; an fe workspace has a package.json.`)); continue; }
+    const name = folder.split('/')[2];
+    if (pkg.private !== true) findings.push(found(MONO_FE_WORKSPACE, file, `${file} is not \`"private": true\`; a workspace of the app is never published.`));
+    const scripts = pkg.scripts ?? {};
+    if (folder.startsWith('fe/apps/')) {
+      const expected = feAppPackageName(project, name);
+      if (pkg.name !== expected) findings.push(found(MONO_FE_WORKSPACE, file, `${file} is named ${JSON.stringify(pkg.name ?? null)}; the fe app ${name} is the workspace ${expected}.`, { expected }));
+      const want = Object.keys(FE_APP_SCRIPTS).sort();
+      const off = [...new Set([...want, ...Object.keys(scripts)])].sort().filter((key) => scripts[key] !== FE_APP_SCRIPTS[key]);
+      if (off.length) findings.push(found(MONO_FE_WORKSPACE, file, `${file} has scripts ${JSON.stringify(scripts)}; an fe app workspace has exactly ${JSON.stringify(FE_APP_SCRIPTS)} (turbo runs build, dev, lint and typecheck; differs at ${off.join(', ')}).`, { scripts: off }));
+    } else {
+      const missing = FE_PACKAGE_SCRIPTS.filter((key) => typeof scripts[key] !== 'string' || !scripts[key]);
+      if (missing.length) findings.push(found(MONO_FE_WORKSPACE, file, `${file} has no ${missing.join(', ')} script; an fe package workspace builds, type-checks and lints (turbo builds it before the apps that import it).`, { scripts: missing }));
+      else if (scripts.lint !== WORKSPACE_LINT) findings.push(found(MONO_FE_WORKSPACE, file, `${file} lints with ${JSON.stringify(scripts.lint)}; a workspace lints with ${JSON.stringify(WORKSPACE_LINT)}, the one lint of the app scoped to it.`, { scripts: ['lint'] }));
+    }
+  }
+  return findings;
+}
+
+/** R145: be/nest-cli.json is the Nest monorepo of exactly the declared be apps. */
+function nestFindings(repoRoot, files, beApps) {
+  if (!files.includes(NEST_CLI)) return [];
+  const cli = readJson(repoRoot, NEST_CLI);
+  if (!cli) return [found(MONO_NEST_PROJECTS, NEST_CLI, `${NEST_CLI} is not readable JSON.`)];
+  const findings = [];
+  if (cli.monorepo !== true) findings.push(found(MONO_NEST_PROJECTS, NEST_CLI, `${NEST_CLI} is not \`"monorepo": true\`; the back end is a Nest monorepo of be/apps/<app>, even with one service.`));
+  const declared = beApps.map((app) => app.name).sort();
+  const projects = Object.keys(cli.projects ?? {}).sort();
+  if (!sameList(projects, declared)) findings.push(found(MONO_NEST_PROJECTS, NEST_CLI, `${NEST_CLI} has projects ${JSON.stringify(projects)}, but hfs.json declares the be apps ${JSON.stringify(declared)}; one project per declared app, no other.`, { projects, declared }));
+  for (const name of projects.filter((project) => declared.includes(project))) {
+    const project = cli.projects[name] ?? {};
+    if (project.type !== 'application' || project.root !== `apps/${name}` || project.sourceRoot !== `apps/${name}/src`) findings.push(found(MONO_NEST_PROJECTS, NEST_CLI, `${NEST_CLI} project ${name} is ${JSON.stringify({ type: project.type, root: project.root, sourceRoot: project.sourceRoot })}; it is {"type":"application","root":"apps/${name}","sourceRoot":"apps/${name}/src"}.`, { project: name }));
+  }
+  const apis = beApps.filter((app) => app.kind === 'api').map((app) => app.name);
+  const rootApp = /^apps\/([^/]+)$/.exec(String(cli.root ?? ''))?.[1];
+  if (!apis.includes(rootApp) || cli.sourceRoot !== `apps/${rootApp}/src`) findings.push(found(MONO_NEST_PROJECTS, NEST_CLI, `${NEST_CLI} has root ${JSON.stringify(cli.root ?? null)} and sourceRoot ${JSON.stringify(cli.sourceRoot ?? null)}; the default project is an api app (${apis.join(', ') || 'none declared'}): root apps/<api>, sourceRoot apps/<api>/src.`, { root: cli.root ?? null }));
+  return findings;
+}
+
+/** The TypeScript compiler of the app (else of the runtime), or null. */
+const typescriptFor = (repoRoot) => loadTypescript(repoRoot, HERE);
+
+/** The path-alias patterns of a workspace (its tsconfig.json as TypeScript resolves it, `extends` included): [{ prefix, exact }]. */
+function aliasesOf(ts, dir) {
+  const file = path.join(dir, 'tsconfig.json');
+  if (!fs.existsSync(file)) return [];
+  const read = ts.readConfigFile(file, ts.sys.readFile);
+  if (read.error) return [];
+  const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dir);
+  return Object.keys(parsed.options.paths ?? {}).map((key) => (key.endsWith('*') ? { prefix: key.slice(0, -1), exact: false } : { prefix: key, exact: true }));
+}
+
+/** The npm package a bare module specifier names (`next/link` is next, `@scope/name/sub` is @scope/name). */
+const packageOf = (specifier) => {
+  const parts = specifier.split('/');
+  return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+};
+
+/** R146: what each fe workspace imports, it declares; the root declares no workspace package. */
+function workspaceDepFindings(repoRoot, files, workspaces) {
+  const findings = [];
+  const names = new Map(workspaces.map((folder) => [readJson(repoRoot, `${folder}/${MANIFEST}`)?.name, folder]).filter(([name]) => typeof name === 'string'));
+  const root = readJson(repoRoot, MANIFEST);
+  for (const name of declaredIn(root)) if (names.has(name)) findings.push(found(MONO_WORKSPACE_DEP, MANIFEST, `${MANIFEST} declares the workspace package ${name} (${names.get(name)}); the root never depends on a workspace: the fe workspace that imports it declares it.`, { dependency: name }));
+  if (!workspaces.length) return findings;
+  const ts = typescriptFor(repoRoot);
+  if (!ts) return [...findings, found(MONO_WORKSPACE_DEP, MANIFEST, 'the fe workspaces cannot be judged: no TypeScript resolves from the app; install the app\'s dependencies.', { missing: ['typescript'] })];
+  for (const folder of workspaces) {
+    const manifest = `${folder}/${MANIFEST}`;
+    const pkg = readJson(repoRoot, manifest);
+    if (!pkg) continue;
+    const declared = declaredIn(pkg);
+    const aliases = aliasesOf(ts, path.join(repoRoot, folder));
+    const isAlias = (specifier) => aliases.some((alias) => (alias.exact ? specifier === alias.prefix : specifier.startsWith(alias.prefix)));
+    const missing = new Map();
+    for (const file of files) {
+      if (!file.startsWith(`${folder}/`) || !SOURCE.test(file) || file.endsWith('.d.ts')) continue;
+      const text = readText(repoRoot, file);
+      if (text === null) continue;
+      for (const { fileName: specifier } of ts.preProcessFile(text, true, true).importedFiles) {
+        if (specifier.startsWith('.') || specifier.startsWith('/') || isBuiltin(specifier) || isAlias(specifier)) continue;
+        const name = packageOf(specifier);
+        if (declared.has(name) || name === pkg.name) continue;
+        if (!missing.has(name)) missing.set(name, file);
+      }
+    }
+    for (const [name, file] of [...missing].sort()) {
+      const sibling = names.get(name);
+      findings.push(found(MONO_WORKSPACE_DEP, manifest, `${file} imports ${name}, which ${manifest} does not declare; ${sibling ? `declare the workspace package ${name} as "*"` : `declare ${name} in the dependencies of ${manifest} (one version across the workspace, R14)`}.`, { dependency: name, importedBy: file }));
+    }
+  }
+  return findings;
+}
+
+/** The findings of the monorepo rules over the tracked paths `files` (app-relative) of the app at `repoRoot`. */
+export function monorepoFindings({ repoRoot, files, repo }) {
+  if (!repo?.sides) return [];
+  const workspaces = workspacesOf(files);
+  const beApps = repo.sides.be.apps;
+  return [
+    ...rootFindings(repoRoot),
+    ...workspaceManifestFindings(repoRoot, repo.project, workspaces),
+    ...nestFindings(repoRoot, files, beApps),
+    ...workspaceDepFindings(repoRoot, files, workspaces),
+  ];
+}

package/runtime/scripts/hfs/rules/peer-integrations.mjs

@@ -8,19 +8,19 @@ import fs from 'node:fs';
 import { parseYaml } from '../../../engine/yaml.mjs';
 import { found, readJson } from './read.mjs';
 
-export const PEER_INTEGRATION_MISSING = 'HFS_PEER_INTEGRATION_MISSING';
+const PEER_INTEGRATION_MISSING = 'HFS_PEER_INTEGRATION_MISSING';
 const MANIFEST = 'package.json';
 const CATALOG_FILE = new URL('../../../knowledge/hfs/peer-integrations.yaml', import.meta.url);
 
 /** The pairs of the catalog: [{ id, when: [{ package, major? }], requires, why }]. */
-export function peerIntegrationPairs() {
+function peerIntegrationPairs() {
   const catalog = parseYaml(fs.readFileSync(CATALOG_FILE, 'utf8'));
   if (catalog?.schema !== 'starci/hfs-peer-integrations@1' || !Array.isArray(catalog.pairs)) throw new Error('knowledge/hfs/peer-integrations.yaml is not a starci/hfs-peer-integrations@1 catalog');
   return catalog.pairs;
 }
 
 /** The major a dependency spec allows (`11.2.5`, `^11.0.0`, `~11.1`, `>=11 <12`), or null when the spec names none (a tag, a link, `*`). */
-export function majorOf(spec) {
+function majorOf(spec) {
   const match = /^\s*(?:[\^~]|>=?|=)?\s*v?(\d+)(?:\.|\s|$)/.exec(String(spec));
   return match ? Number(match[1]) : null;
 }

package/runtime/scripts/hfs/rules/pipeline.mjs

@@ -1,19 +1,18 @@
-// pipeline.mjs - HFS_CI_MISSING_CANON (R13): CI runs the pinned `hfs lint`; pre-push runs typecheck and lint.
-//   .github/workflows/ci.yml   a `run:` step that runs `hfs lint` (the one lint entry: eslint, the repository check, stylelint): `npx hfs lint`,
-//                              `npx @starci/hfs[@<version>] lint`, or `npm run <script>` of the root package.json whose command runs `hfs lint`
-//                              (`npm run lint`, arguments after `--` allowed); a version named in the step is the @starci/hfs pin of
+// pipeline.mjs - HFS_CI_MISSING_CANON (R13): CI runs the pinned `starci app lint`.
+//   .github/workflows/ci.yml   a `run:` step that runs the one lint entry: `starci app lint`,
+//                              `npx @starci/cli[@<version>] app lint`, or `npm run <script>` whose command runs `starci app lint`
+//                              (`npm run lint`, arguments after `--` allowed); a version named in the step is the @starci/cli pin of
 //                              canon-pins.yaml (an installed one is pinned by the pin check, R15)
-//   .husky/pre-push            `npm run typecheck` and `npm run lint`, each on a line of its own
+//   (the push hook is no lint or typecheck step: it checks the release gate, scripts/hfs/runtime-rules/hook-shape.mjs keeps its shape)
 // A missing file is the slot manifest's finding (HFS_SLOT_REQUIRED_MISSING); a file that is present and lacks the step is this rule's.
 // The redirect of `core.hooksPath` away from husky is the architecture machine's (HFS_HOOKS_PATH_REDIRECTED).
 import { found, readJson, readText } from './read.mjs';
 
-export const CI_MISSING_CANON = 'HFS_CI_MISSING_CANON';
-export const CI_FILE = '.github/workflows/ci.yml';
-export const PRE_PUSH_FILE = '.husky/pre-push';
-export const hfsPackage = '@starci/hfs';
+const CI_MISSING_CANON = 'HFS_CI_MISSING_CANON';
+const CI_FILE = '.github/workflows/ci.yml';
+const hfsPackage = '@starci/cli';
 const RUN_LINE = /^\s*(?:-\s+)?run:\s*(.+?)\s*$/;
-const HFS_LINT = /^(?:npx\s+(?:--no-install\s+|-y\s+)?)?(?:@starci\/hfs|hfs)(?:@(\S+))?\s+lint(\s.*)?$/;
+const HFS_LINT = /^(?:npx\s+(?:--no-install\s+|-y\s+)?)?(?:@starci\/cli(?:@(\S+))?|starci)\s+app\s+lint(\s.*)?$/;
 const NPM_RUN = /^npm run ([\w:.-]+)(?:\s+--\s+(.*))?$/;
 
 const commandsOf = (text) => text.split(/\r?\n/).map((line) => RUN_LINE.exec(line)?.[1]).filter(Boolean).map((command) => command.replace(/^["']|["']$/g, ''));
@@ -24,8 +23,6 @@ function expanded(command, scripts) {
   return run && typeof scripts[run[1]] === 'string' ? `${scripts[run[1]]}${run[2] ? ` ${run[2]}` : ''}` : command;
 }
 
-const runsStep = (lines, step) => lines.some((line) => new RegExp(`^npm run ${step}(\\s|$)`).test(line));
-
 /** The findings of R13 over the repository at `repoRoot`; `pins` is the parsed canon-pins.yaml pin map. */
 export function pipelineFindings({ repoRoot, files, pins }) {
   const findings = [];
@@ -34,16 +31,9 @@ export function pipelineFindings({ repoRoot, files, pins }) {
   if (ci !== null) {
     const scripts = readJson(repoRoot, 'package.json')?.scripts ?? {};
     const lints = commandsOf(ci).flatMap((command) => expanded(command, scripts).split(/\s*&&\s*/)).map((command) => HFS_LINT.exec(command)).filter(Boolean);
-    if (!lints.length) findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} has no step that runs \`hfs lint\` (\`npm run lint\`, or \`npx hfs lint\`); CI runs the one lint entry, which includes the repository check`, { step: 'hfs lint' }));
+    if (!lints.length) findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} has no step that runs \`starci app lint\` (directly or through \`npm run lint\`); CI runs the one lint entry, which includes the repository check`, { step: 'starci app lint' }));
     else if (pinned && !lints.some((match) => match[1] === undefined || match[1] === pinned)) {
-      findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} runs hfs lint at ${lints[0][1]}, but ${hfsPackage} is pinned at ${pinned}; run the pinned version`, { step: 'hfs lint', pinned }));
-    }
-  }
-  const prePush = files.includes(PRE_PUSH_FILE) ? readText(repoRoot, PRE_PUSH_FILE) : null;
-  if (prePush !== null) {
-    const lines = prePush.split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith('#'));
-    for (const step of ['typecheck', 'lint']) {
-      if (!runsStep(lines, step)) findings.push(found(CI_MISSING_CANON, PRE_PUSH_FILE, `${PRE_PUSH_FILE} does not run \`npm run ${step}\`; pre-push runs typecheck and lint`, { step }));
+      findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} runs starci app lint at ${lints[0][1]}, but ${hfsPackage} is pinned at ${pinned}; run the pinned version`, { step: 'starci app lint', pinned }));
     }
   }
   return findings;

package/runtime/scripts/hfs/rules/proof-commands.mjs

@@ -1,7 +1,7 @@
 // proof-commands.mjs - HFS_PROOF_COMMAND_FILE_MISSING (R105): a proof command a `.starciwork` record names runs files that exist.
 // A record's `requiresProof.<kind>.command` is "the exact command that satisfies this kind, runnable as written" (work-implementation
 // schema); a command that names a spec, a script or a config the repository does not hold cannot be run as written, and a record that
-// keeps one goes quietly false (nivo-backend, 2026-09-30: `node --test scripts/provision-keycloak.spec.mjs` after the script was deleted).
+// keeps one goes quietly false (a product repo once kept `node --test <repo>/scripts/provision-keycloak.spec.mjs` after the script was deleted).
 // Every argument of the command that is a repository-relative file path (an extension, no glob, no variable, not absolute, not a `..`
 // path into another repository) must be a tracked file or an existing one; a path an ignored slot owns (dist/, coverage/) is a build
 // product and is not judged. One finding per record, kind and missing path. The `.starciwork` of an app sits at the app root, and a
@@ -13,7 +13,7 @@ import path from 'node:path';
 import { parseYaml } from '../../../engine/yaml.mjs';
 import { found, readText } from './read.mjs';
 
-export const PROOF_COMMAND_FILE_MISSING = 'HFS_PROOF_COMMAND_FILE_MISSING';
+const PROOF_COMMAND_FILE_MISSING = 'HFS_PROOF_COMMAND_FILE_MISSING';
 const RECORD = /^\.starciwork\/.+\.ya?ml$/;
 const FILE_ARGUMENT = /^(?:\.\/)?[\w@][\w@.\-[\]()]*(?:\/[\w@.\-[\]()]+)*\.[A-Za-z][A-Za-z0-9]{0,7}$/;
 const PATH_SEPARATOR = /\//;

package/runtime/scripts/hfs/rules/read.mjs

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 /** Files above this size are not read by a tree check (a tracked binary or a generated dump is no source of these laws). */
-export const MAX_READ_BYTES = 1024 * 1024;
+const MAX_READ_BYTES = 1024 * 1024;
 
 /** The text of `rel` under `repoRoot`, or null when it is absent, unreadable, over MAX_READ_BYTES or binary. */
 export function readText(repoRoot, rel) {

package/runtime/scripts/hfs/rules/repo-local-checks.mjs

@@ -9,7 +9,7 @@
 // included (HFS_RULE_OFF_WITHOUT_REPLACEMENT, R17). This rule adds the forbidden roles by name: what a check or a rule file is called.
 import { found, readJson } from './read.mjs';
 
-export const REPO_LOCAL_CHECK = 'HFS_REPO_LOCAL_CHECK';
+const REPO_LOCAL_CHECK = 'HFS_REPO_LOCAL_CHECK';
 const LOCAL_RULE_FILE = /(?:^|\/)(?:eslint-local-rules|eslint-plugin|eslint-local-plugin)[^/]*(?:\/|$)|(?:^|\/)(?:eslint-rules|lint-rules)\//;
 const CHECK_SCRIPT = /(?:^|\/)(?:scripts|tools)\/check-[^/]+$/;
 const RUNS_CHECK = /(?:^|[\s&|;(])(?:\.\/)?(?:scripts|tools)\/check-[^\s&|;)]+/;
@@ -20,7 +20,7 @@ export function repoLocalCheckFindings({ repoRoot, files }) {
   for (const file of files) {
     if (file.includes('node_modules/')) continue;
     if (LOCAL_RULE_FILE.test(file)) findings.push(found(REPO_LOCAL_CHECK, file, `${file} is a local lint rule or plugin; a repository keeps no rule of its own: the rule is proposed to the canon (@starci/eslint-canon-*) in the .claude runtime`));
-    else if (CHECK_SCRIPT.test(file)) findings.push(found(REPO_LOCAL_CHECK, file, `${file} is a check kept in the repository; every check lives in the .claude runtime (hfs check, the canons), so a repository has none to keep`));
+    else if (CHECK_SCRIPT.test(file)) findings.push(found(REPO_LOCAL_CHECK, file, `${file} is a check kept in the repository; every check lives in the .claude runtime (starci app check, the canons), so a repository has none to keep`));
     else if (file === 'package.json' || file.endsWith('/package.json')) {
       const pkg = readJson(repoRoot, file);
       for (const [name, command] of Object.entries(pkg?.scripts ?? {})) {

package/runtime/scripts/hfs/rules/saga.mjs

@@ -0,0 +1,170 @@
+// saga.mjs - the saga pattern of a product that declares `patterns: ["saga"]` in hfs.json (R169 to R173). A saga is a feature of the saga kind
+//   be/src/features/saga/<saga>/
+//     <saga>.saga.service.ts              the orchestrator: the list of its steps and compensations (a service, unit-tested beside it)
+//     <saga>.saga-state.ts                the persisted state of a run, typed with its `status` and its `version` fence
+//     steps/<step>.saga-step.ts                one step, dispatching one command, naming the event it puts on the wire
+//     compensations/<step>.compensation.ts  the compensation of that step, naming the failure event that triggers it
+//   be/src/features/saga/<saga>/transport/message/<event>.consumer.ts   the consumers that advance it, through the inbox
+//   be/contracts/<service>/events.json   every event, a compensating one declaring `compensates: "<step event>"`
+// Five tree checks (the slot manifest owns the paths: an undeclared saga folder is HFS_SLOT_NOT_ENABLED):
+//   R169 BE_SAGA_STEP_COMPENSATION  every step has a compensation of the same name and the other way round, and the orchestrator imports them all;
+//   R170 BE_SAGA_STATE_VERSIONED    every orchestrator has its `.saga-state.ts` whose exported state type carries `status` and a numeric `version`,
+//                                   and imports the fenced store of `platform/saga`;
+//   R171 BE_SAGA_EVENT_CONTRACT     a step and a compensation each name their event (`readonly event = "<name>"`), both are in a contract, and the
+//                                   contract of the compensation's event says it compensates the step's event;
+//   R172 BE_SAGA_CONSUMER_DEDUPE    a consumer of a saga feature passes the id of the delivery (`message.eventId`) on to the command, so the inbox can dedupe it;
+//   R173 BE_SAGA_E2E_MISSING        every compensation path has an e2e spec through the world that names its event and injects a failure
+//                                   (an outage of an infra service, an app or a fake: `during`, `cut`, `latency`, `failNext`, `interruptDatabase`).
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../../lib/package-at.mjs';
+import { found, readJson, readText } from './read.mjs';
+
+const SAGA_STEP_COMPENSATION = 'BE_SAGA_STEP_COMPENSATION';
+const SAGA_STATE_VERSIONED = 'BE_SAGA_STATE_VERSIONED';
+const SAGA_EVENT_CONTRACT = 'BE_SAGA_EVENT_CONTRACT';
+const SAGA_CONSUMER_DEDUPE = 'BE_SAGA_CONSUMER_DEDUPE';
+const SAGA_E2E_MISSING = 'BE_SAGA_E2E_MISSING';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SAGA_FILE = /^be\/src\/features\/saga\/([^/]+)\/(?:(?:steps|compensations)\/)?[^/]+\.(?:saga\.service|saga-state|saga-step|compensation)\.ts$/;
+const ORCHESTRATOR = /^be\/src\/features\/saga\/([^/]+)\/([^/]+)\.saga\.service\.ts$/;
+const STATE = /^be\/src\/features\/saga\/([^/]+)\/([^/]+)\.saga-state\.ts$/;
+const STEP = /^be\/src\/features\/saga\/([^/]+)\/steps\/([^/]+)\.saga-step\.ts$/;
+const COMPENSATION = /^be\/src\/features\/saga\/([^/]+)\/compensations\/([^/]+)\.compensation\.ts$/;
+const CONSUMER = /^be\/src\/features\/saga\/([^/]+)\/transport\/message\/[^/]+\.consumer\.ts$/;
+const E2E_SPEC = /^be\/src\/tests\/e2e\/[^/]+\/[^/]+\.e2e-spec\.ts$/;
+const CONTRACT = /^be\/contracts\/[^/]+\/events\.json$/;
+const USE_TEST_WORLD = /\buseTestWorld\s*\(/;
+const INJECTION = /\.(?:during|cut|latency|failNext|interruptDatabase)\s*\(/;
+const STORE_MODULE = /(?:^|\/)platform\/saga$/;
+
+/** The TypeScript compiler of the app (else of the runtime), or null. */
+const typescriptFor = (repoRoot) => loadTypescript(repoRoot, HERE);
+
+const parse = (ts, text) => ts.createSourceFile('saga.ts', text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+
+/** The module specifiers a source file imports or re-exports. */
+function specifiersOf(ts, sourceFile) {
+  const out = [];
+  for (const statement of sourceFile.statements) {
+    if ((ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) && statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)) out.push(statement.moduleSpecifier.text);
+  }
+  return out;
+}
+
+/** The string literal of the class property `event` (`readonly event = "order.placed"`), or null. */
+function eventOf(ts, sourceFile) {
+  let name = null;
+  const visit = (node) => {
+    if (ts.isPropertyDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === 'event' && node.initializer && ts.isStringLiteralLike(node.initializer)) name = node.initializer.text;
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return name;
+}
+
+/** Whether an exported interface or type alias of the file declares `status` and a `version: number` member. */
+function statesVersion(ts, sourceFile) {
+  let versioned = false;
+  const memberNames = (members) => new Map(members.filter((member) => ts.isPropertySignature(member) && ts.isIdentifier(member.name)).map((member) => [member.name.text, member.type]));
+  for (const statement of sourceFile.statements) {
+    if (!statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue;
+    const members = ts.isInterfaceDeclaration(statement) ? statement.members : ts.isTypeAliasDeclaration(statement) && ts.isTypeLiteralNode(statement.type) ? statement.type.members : null;
+    if (members === null) continue;
+    const named = memberNames(members);
+    if (named.has('status') && named.get('version')?.kind === ts.SyntaxKind.NumberKeyword) versioned = true;
+  }
+  return versioned;
+}
+
+/** Whether a source text reads `.eventId` of something (the id of the delivery travels on). */
+function readsEventId(ts, sourceFile) {
+  let read = false;
+  const visit = (node) => {
+    if (ts.isPropertyAccessExpression(node) && node.name.text === 'eventId') read = true;
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return read;
+}
+
+/** The sagas of the app: every folder of the saga kind (`be/src/features/saga/<saga>/`). */
+const featuresOf = (files) => [...new Set(files.map((file) => SAGA_FILE.exec(file)?.[1]).filter((feature) => feature !== undefined))].sort();
+
+/** Findings of R169 to R173 over the tracked paths `files` of the app at `repoRoot`. */
+export function sagaFindings({ repoRoot, files }) {
+  const features = featuresOf(files);
+  if (features.length === 0) return [];
+  const ts = typescriptFor(repoRoot);
+  if (ts === null) return [];
+  const findings = [];
+  const events = new Map();
+  for (const contract of files.filter((file) => CONTRACT.test(file))) {
+    for (const [name, event] of Object.entries(readJson(repoRoot, contract)?.events ?? {})) events.set(name, { contract, ...event });
+  }
+  const specs = files.filter((file) => E2E_SPEC.test(file)).map((file) => ({ file, text: readText(repoRoot, file) ?? '' })).filter(({ text }) => USE_TEST_WORLD.test(text));
+  const compensationPaths = [];
+  for (const feature of features) {
+    const under = (pattern) => files.filter((file) => pattern.test(file) && pattern.exec(file)[1] === feature);
+    const steps = new Map(under(STEP).map((file) => [STEP.exec(file)[2], file]));
+    const compensations = new Map(under(COMPENSATION).map((file) => [COMPENSATION.exec(file)[2], file]));
+    const orchestrators = under(ORCHESTRATOR);
+    const states = new Map(under(STATE).map((file) => [STATE.exec(file)[2], file]));
+    const folder = `be/src/features/saga/${feature}/`;
+    // R169
+    for (const [stem, file] of steps) if (!compensations.has(stem)) findings.push(found(SAGA_STEP_COMPENSATION, file, `${file} is a saga step with no compensation: add ${folder}compensations/${stem}.compensation.ts, the command that undoes it; every forward step of a saga has one.`, { step: stem }));
+    for (const [stem, file] of compensations) if (!steps.has(stem)) findings.push(found(SAGA_STEP_COMPENSATION, file, `${file} is a compensation of no step: ${folder}steps/${stem}.saga-step.ts does not exist; a compensation undoes the step of the same name.`, { step: stem }));
+    if (orchestrators.length === 0 && (steps.size > 0 || compensations.size > 0)) findings.push(found(SAGA_STEP_COMPENSATION, folder, `${folder} holds steps or compensations but no orchestrator: add <saga>.saga.service.ts, the list of the steps and their compensations.`));
+    for (const orchestrator of orchestrators) {
+      const text = readText(repoRoot, orchestrator);
+      if (text === null) continue;
+      const sourceFile = parse(ts, text);
+      const imported = specifiersOf(ts, sourceFile).map((specifier) => path.posix.normalize(path.posix.join(path.posix.dirname(orchestrator), specifier)));
+      for (const file of [...steps.values(), ...compensations.values()]) {
+        if (!imported.includes(file.replace(/\.ts$/, ''))) findings.push(found(SAGA_STEP_COMPENSATION, orchestrator, `${orchestrator} does not list ${file}: the orchestrator imports every step and every compensation of its saga, so a step nobody runs cannot hide.`, { step: file }));
+      }
+      // R170
+      const stem = ORCHESTRATOR.exec(orchestrator)[2];
+      const stateFile = states.get(stem);
+      if (stateFile === undefined) findings.push(found(SAGA_STATE_VERSIONED, orchestrator, `${orchestrator} has no ${folder}${stem}.saga-state.ts: the persisted state of a run is typed there, with its status and its version fence.`, { saga: stem }));
+      if (!specifiersOf(ts, sourceFile).some((specifier) => STORE_MODULE.test(specifier))) findings.push(found(SAGA_STATE_VERSIONED, orchestrator, `${orchestrator} does not use the fenced store of platform/saga: a run is persisted and moved only through it (every transition names the version it read), never by a write of its own.`, { saga: stem }));
+    }
+    for (const [stem, file] of states) {
+      const text = readText(repoRoot, file);
+      if (text !== null && !statesVersion(ts, parse(ts, text))) findings.push(found(SAGA_STATE_VERSIONED, file, `${file} exports no state type with a \`status\` and a \`version: number\`; a saga run is persisted with a version, the fence that stops a zombie delivery from moving it twice.`, { saga: stem }));
+    }
+    // R171
+    const eventOfFile = new Map();
+    for (const [kind, map] of [['step', steps], ['compensation', compensations]]) {
+      for (const [stem, file] of map) {
+        const text = readText(repoRoot, file);
+        const name = text === null ? null : eventOf(ts, parse(ts, text));
+        eventOfFile.set(`${kind}:${stem}`, name);
+        if (name === null) findings.push(found(SAGA_EVENT_CONTRACT, file, `${file} names no event: a ${kind} of a saga declares \`readonly event = "<name>"\`, the event of the contract it ${kind === 'step' ? 'puts on the wire' : 'answers'}.`, { step: stem }));
+        else if (!events.has(name)) findings.push(found(SAGA_EVENT_CONTRACT, file, `${file} names the event "${name}", which no be/contracts/<service>/events.json declares; every event of a saga is in a vendored contract.`, { step: stem, event: name }));
+      }
+    }
+    for (const [stem, file] of compensations) {
+      const compensationEvent = eventOfFile.get(`compensation:${stem}`);
+      const stepEvent = eventOfFile.get(`step:${stem}`);
+      if (compensationEvent && stepEvent && events.has(compensationEvent) && events.get(compensationEvent).compensates !== stepEvent) {
+        findings.push(found(SAGA_EVENT_CONTRACT, file, `${file}: the contract of "${compensationEvent}" (${events.get(compensationEvent).contract}) does not declare \`compensates: "${stepEvent}"\`; the failure event of a compensation says which step's event it undoes.`, { step: stem, event: compensationEvent }));
+      }
+      if (compensationEvent) compensationPaths.push({ file, stem, event: compensationEvent });
+    }
+    // R172
+    for (const file of under(CONSUMER)) {
+      const text = readText(repoRoot, file);
+      if (text !== null && !readsEventId(ts, parse(ts, text))) findings.push(found(SAGA_CONSUMER_DEDUPE, file, `${file} is a consumer of the saga ${feature} but never passes the id of the delivery on (\`message.eventId\`); the saga takes every event through the inbox, so the consumer hands the id to its command.`, { feature }));
+    }
+  }
+  // R173
+  for (const { file, stem, event } of compensationPaths) {
+    const named = specs.filter(({ text }) => text.includes(event));
+    const expected = `be/src/tests/e2e/<area>/<name>.e2e-spec.ts`;
+    if (named.length === 0) findings.push(found(SAGA_E2E_MISSING, file, `${file}: the compensation path of "${event}" has no e2e spec; add ${expected}, which boots the apps with useTestWorld, drives the failure and reads the compensated state back.`, { step: stem, event }));
+    else if (!named.some(({ text }) => INJECTION.test(text))) findings.push(found(SAGA_E2E_MISSING, named[0].file, `${named[0].file} names "${event}" but injects no failure; the compensation path is proven with a fault through the world (an outage of an infra service or an app with \`during\`, \`cut\`, \`latency\`, a fake's \`failNext\`, \`interruptDatabase\`), not only the happy flow.`, { step: stem, event }));
+  }
+  return findings;
+}

package/runtime/scripts/hfs/rules/secrets.mjs

@@ -6,10 +6,10 @@
 //   - a line of any other tracked text file that matches a secret pattern.
 // A finding names the file, the line and the pattern, never the value.
 import { FORBIDDEN_FILES, secretHits } from '../../lib/secret-patterns.mjs';
-import { isSopsEnvelope } from '../../lib/test-secrets.mjs';
+import { isSopsEnvelope } from '../../lib/sops-envelope.mjs';
 import { found, readText } from './read.mjs';
 
-export const PLAINTEXT_SECRET = 'HFS_PLAINTEXT_SECRET';
+const PLAINTEXT_SECRET = 'HFS_PLAINTEXT_SECRET';
 /** Files whose lines are not secrets: a lockfile carries integrity hashes, never a credential. */
 const NOT_SCANNED = /(^|\/)package-lock\.json$/;
 
@@ -19,7 +19,7 @@ export const slotOwnsSecrets = (slot) => slot?.rules?.includes(PLAINTEXT_SECRET)
 /**
  * The findings of R06 for one tracked file that no forbidden slot claims: a secret by being (an env file, a key file), an `.enc` that is
  * no sops envelope, or a line that matches a secret pattern. `text` is the file's text, or null when it cannot be read (binary, too
- * large, absent). The whole-tree check reads the work tree and the commit hook (`hfs work-hygiene`) reads the staged blob: one judgement.
+ * large, absent). The whole-tree check reads the work tree and the commit hook (`starci app hygiene`) reads the staged blob: one judgement.
  */
 export function secretFileFindings({ file, text }) {
   const being = FORBIDDEN_FILES.find((rule) => rule.test(file));