@starci/hfs 3.0.0 → 4.0.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 4.0.1 - 2026-10-01
+
+- Fixed: `hfs scaffold app` no longer writes a hand-made lockfile. The 4.0.0 stub held only the root entry, so `npm ci` in a new app failed with EUSAGE ("package.json and package-lock.json are not in sync"). Once the files are written, the scaffold runs `npm install --package-lock-only --ignore-scripts --no-audit --no-fund` in the new app root (registry or npm cache; no node_modules, no scripts), so the lockfile resolves every dependency of the root and its workspaces and `npm ci` accepts it. If npm cannot resolve it, the scaffold exits 2 with `HFS_SCAFFOLD_LOCK_FAILED`, names the step and removes the app it began: no stub lock and no app without a lock is left. There is no switch to skip the step.
+- Fixed (false positive): R14 `HFS_DEP_VERSION_SKEW` does not report a bundled copy in the lockfile (`inBundle`, a package's bundleDependencies, e.g. the tslib inside `@tailwindcss/oxide-wasm32-wasi`): it ships inside its parent's tarball and nothing in the app can move it. A fresh scaffold's real lock has one.
+
+## 4.0.0 - 2026-10-01
+
+- Added: the scaffolded root `package.json` (and its lockfile root entry) pins `@starci/test-world` from `knowledge/hfs/canon-pins.yaml` (1.0.0), the package whose `starci-test-stack` bin the managed `test:stack` script runs.
+- Changed: R47 `test-world-files` reads `test-world.config.ts` in the shape `@starci/test-world` defines and in its one named form `export const { useTestWorld, useSandbox } = defineTestWorld({ ... })` (the form R89 allows): `stack` names the environment, a stack service is faked only by its own `stacks` entry `{ fakedBy, reason }`, and a `fakes` entry of the declaration that fakes a stack service is refused like a `fakes/<provider>/` folder. A config with no readable named declaration (a default export included) is refused. The top-level `fakedBy` and the `stacks` list of environment names are no longer read.
+- New (lane SHAPE): `HFS_PEER_INTEGRATION_MISSING` (R111). The app root package.json that depends on every package of a pair of `knowledge/hfs/peer-integrations.yaml` (at the named major) declares the pair's peer in its dependencies; the first pair is `@nestjs/apollo` on `@nestjs/platform-express` 11, which requires `@as-integrations/express5`.
+- Changed (lane SHAPE): `HFS_PROOF_COMMAND_FILE_MISSING` (R105) judges the records naming a side (`repository: be` or `fe`) from the app root, where their proof commands run; a record naming another repository is still not judged.
+- Changed (lane SHAPE): the managed `typecheck` script of an app with fe packages runs `npm run build --workspaces --if-present` before it type-checks the fe apps, which import the packages from `dist/`.
+- Changed (lane SHAPE): `hfs scaffold app` writes `.starciwork/workspace.yaml` with the repositories `[{role: be, name: be}, {role: fe, name: fe}]`, the form of the examples.
+- Fixed (lane SHAPE): slot be.tests.world allows `fakes/<provider>/server.ts`, so `BE_SOURCE_FORM` reads the fake server of a provider as its role instead of refusing the path `test-world-files` accepts.
+- Breaking: the app monorepo standard. A product is ONE app repository `<app>/`: the root holds the one `package.json` (every dependency of both sides and every script; npm workspaces only for `fe/packages/*`), the one lockfile and `node_modules`, `hfs.json` of kind `app`, README, CI, `.husky`, `scripts/` and `.starciwork`; `be/` and `fe/` hold what the old back-end and front-end repository roots held except `package.json` and the lockfile. `hfs.json` is `{ "hfs": 2, "kind": "app", "project", "sides": { "be": { "apps", "optionalSlots", "connections" }, "fe": { "apps", "optionalSlots", "reads": ["be/contracts/"] } } }` (manifest major 2). The standalone `be` and `fe` repository kinds (`profile`, `stacks`) are deleted, with no alias.
+- Breaking: `hfs init` is deleted; `hfs scaffold app <name> [--into <dir>]` writes the root, the `be/` and `fe/` skeletons and the app hfs.json, and refuses an existing directory. The fresh app lints clean (0 findings): the be skeleton is default-deny (throttler, CSRF origin guard, AuthGuard of `domain/identity`), carries the required platform capabilities (config, logging, errors, primitives, clock, i18n, cqrs, http-security) and the health feature; the fe skeleton mounts one pages feature per route slot, drawn with `@starci/grammar`.
+- Breaking: `hfs lint`, `hfs check` and `hfs sync` run at the app root. The lint runs ESLint once per side (be/ with the BE canon, fe/ with the FE canon, each from its side folder with its one-line config), stylelint over fe/, the root checks once and the side checks and the architecture machine per side ("side view": each side judged with its folder as the root), and writes one `starci/lint@1` report and one Sonar import with app-relative paths. `--changed` keeps working with app-relative files. `hfs sync` renders the root files (package.json scripts `dev:be`, `dev:fe`, `build:be`, `build:fe`, `start:<app>`, `migrate`, `lint`, `test*`, `codegen`, `contract:emit`, `typecheck`, the hooks, CI, Sonar, prettier, the .gitignore block) and each side's managed files.
+- Breaking: the front end reads `be/contracts/` in place for its codegen (`sides.fe.reads`); the front-end contract copy and its `HFS_CONTRACT_SNAPSHOT_DRIFT` hash comparison are gone.
+- Changed: one version per dependency in the one package.json: a conflict between the sides takes its canon pin, otherwise the higher version, pinned in `knowledge/hfs/canon-pins.yaml` with a why (`graphql` 16.14.2).
+- Changed: a side finding names every path from the app root, in its message as in its path (`fe/apps/web/...`, `be/src/...`), in `hfs check` and in the ESLint and stylelint findings of `hfs lint`.
+- Fixed: the architecture machine gives each file to the deepest tsconfig project that holds it, so a route file importing its feature through the app alias `@/` mounts its owner (`FE_ROUTE_FILES_THIN` reported "0 feature owners"); the skeleton route slots import through the alias. A route file binding a declaration to a Next.js segment export (`generateMetadata`, ...) is not `HFS_ALIAS_REEXPORT`.
+
 ## 3.0.0 - 2026-10-01
 
 - Breaking: one entry, `hfs lint`. It runs the repository's eslint, the `hfs check` repository pass and, for a front end, stylelint, and writes one `starci/lint@1` report; `--sonar <file>` writes the single Sonar import (engines starci-hfs, eslint and stylelint in one document); `--changed <files...> --format json` is the land-gate shape. `hfs report`, `hfs check --sonar` and the managed scripts `lint:check`, `lint:report`, `hfs:check` and `hfs:report` are deleted; the managed `lint` script is `hfs lint`, and CI, hooks and the Sonar template read `reports/lint.sonar.json`.

package/README.md

@@ -1,15 +1,17 @@
 # @starci/hfs
 
-The HFS command line of a StarCi product repository. It is installed from the npm registry at the exact version in `knowledge/hfs/canon-pins.yaml` (see [`packages/README.md`](../README.md)),
+The HFS command line of a StarCi app: the one repository of a product, `<app>/` with its root (the one `package.json`, lockfile and `node_modules`, `hfs.json` of kind `app`, CI, hooks, `.starciwork`) and its two sides `be/` and `fe/`. It is installed from the npm registry at the exact version in `knowledge/hfs/canon-pins.yaml` (see [`packages/README.md`](../README.md)),
 and it is self-contained: `runtime/` carries the slot manifest, the canon pins, the Vietnamese why
 catalog slice, the loader and the architecture machine with every file it imports, so it runs where there is no runtime
-checkout. The machine loads `typescript` from the repository it checks (never its own copy), so run `npm ci` first.
+checkout. The machine loads `typescript` from the app it checks (never its own copy), so run `npm ci` first.
+
+Every command runs at the app root. A side is judged with its folder as the root it was when products were split in two repositories (the "side view" of `scripts/lib/hfs-slots.mjs`): the root slots (`app.*`) are judged once, the `be.*` slots under `be/` and the `fe.*` slots under `fe/`, and nothing crosses sides except `sides.fe.reads` (`be/contracts/`, the input of the front end's codegen). Every finding path is app-relative (`be/src/...`, `fe/apps/...`).
 
 ```sh
-npx hfs lint    [--repo <dir>] [--changed <file>...] [--fix] [--format text|json] [--sonar <file>] [--stylelint <glob>]   # THE lint entry (`npm run lint`): exit 0 clean, 1 findings, 2 a tool could not run
+npx hfs lint    [--repo <dir>] [--changed <file>...] [--fix] [--format text|json] [--sonar <file>] [--stylelint <glob>]   # THE lint entry (`npm run lint`): ESLint over be/ with the BE canon and over fe/ with the FE canon, stylelint over fe/, the hfs checks; exit 0 clean, 1 findings, 2 a tool could not run
 npx hfs check   [--repo <dir>] [--json] [--fast] [--base <ref>]   # the repository pass alone (what `hfs lint` runs for the findings that have no TypeScript file); exit 1 on any error-level finding
-npx hfs init    [--repo <dir>] [--stdout]     # write a starter hfs.json (never overwrites); --stdout only prints
-npx hfs emit-contracts [--repo <dir>]         # write contracts/<app>/schema.graphql of every api app that serves GraphQL and contracts/<app>/openapi.json of every api app with a typed operation table (the managed script contract:emit)
+npx hfs scaffold app <name> [--into <dir>]   # a new app <dir>/<name>/: the root, be/ and fe/ skeletons and the app hfs.json; refuses an existing directory
+npx hfs emit-contracts [--repo <dir>]         # write be/contracts/<app>/schema.graphql of every api app that serves GraphQL and be/contracts/<app>/openapi.json of every api app with a typed operation table (the managed script contract:emit)
 npx hfs explain <path> [--repo <dir>] [--json]
 npx hfs sync (--check | --write) [--root <dir>]   # generated files: the managedBy slots of slots.yaml, the .gitignore block (sync/, templates/)
 npx hfs work-hygiene                              # pre-commit guard: staged .starciwork / .starcistacks paths, and the secrets guard over every staged file (read from the index)
@@ -26,8 +28,8 @@ Only `*.service.ts` files are unit-tested (unit test standard), each with exactl
 
 The spec skeleton is `Test.createTestingModule({ providers: [Service, { provide: TOKEN, useValue: double }, ...] }).compile()` and `moduleRef.get(Service)`, with one provider per constructor dependency and nothing else, every double imported from `@starci/jest-preset` (the root), and one placeholder `it` per public method. The double of a token comes from `ruleParams.be.specDoubles` of the slot manifest, the table the lint law `spec-infra-double-from-kit` holds a spec to (`*_ENTITY_MANAGER` -> `mockEntityManager()`, `CLOCK` -> `new FakeClock(...)`, `OUTBOX` -> `recordingOutbox()`, `CACHE` -> `fakeCache(clock)`, lock, lease, fence and hold -> `fakeLock(clock)`, ids -> `fakeIds()`, `*_OPTIONS` -> a literal to fill in, everything else and every class -> `mock<T>()`), so the skeleton satisfies the law by construction: no cast, no `new` of the service, no ambient clock. A back end only (a front end has no services); the files are written for prettier (print width 120).
 
-`hfs check` reads the repository's `hfs.json` and the tracked paths (`git ls-files`), checks the work tree, and then runs the
-whole architecture machine over the repository. Every finding carries a why code and its Vietnamese text
+`hfs check` reads the app's `hfs.json` and the tracked paths (`git ls-files`), checks the work tree (the root rules once, the side rules per side), and then runs the
+whole architecture machine over each side folder. Every finding carries a why code and its Vietnamese text
 (`modules/kernel/failure-codes.yaml`).
 
 Its own checks (`scripts/lib/hfs-check.mjs`, `scripts/lib/hfs-rules/`; the rendered-file checks (`sync/managed.mjs`) and the prettier check (`sync/format.mjs`) live in `sync/` because they read the templates and the repository's own install, and reach `hfs check` as `extraFindings`; the jest / vitest preset the coverage exclusions come from and prettier are read from the repository's `node_modules`, so run `npm ci` first):
@@ -55,12 +57,13 @@ Its own checks (`scripts/lib/hfs-check.mjs`, `scripts/lib/hfs-rules/`; the rende
 | `HFS_STACKS_SHAPE` | error | a `.starcistacks` path outside the standard shape (a sealed file outside `<env>/secrets/`, `runtime/files/`, root `DESIGN.md` or `k8s/`), a local Sonar not owned by the host, a service still rooted at `.stacks` (R10) |
 | `HFS_CI_MISSING_CANON` | error | `ci.yml` without a `run:` step of `hfs lint` (`npm run lint`, or `npx hfs lint` at the pinned version), or `.husky/pre-push` without `npm run typecheck` and `npm run lint` (R13) |
 | `HFS_DEP_VERSION_SKEW` | error | a dependency at two specs across the root and workspace `package.json` files, a dependency declared at another version than the root `overrides` pin, or a nested copy of a declared dependency in `package-lock.json` (R14) |
-| `HFS_CONTRACT_SNAPSHOT_DRIFT` | error / info | a back end serving GraphQL without `contracts/<app>/schema.graphql`, a front-end contract copy that differs by hash from the sibling back end named by `hfs.json` `stacks` (info when the sibling is not checked out) (R23) |
+| `HFS_CONTRACT_SNAPSHOT_DRIFT` | error | a back-end api app serving GraphQL without `be/contracts/<app>/schema.graphql` (R23); the front end reads that snapshot in place, so there is no copy to drift |
 | `BE_TEST_TOPOLOGY` | error | a `*.test.*` file, a `testing/` folder, a second jest configuration or a `jest` key in `package.json` (R47; `int-spec`, `harness-spec` and the retired test folders are the machine's `HFS_TEST_KIND_RETIRED`) |
 | `BE_SPEC_PLACEMENT` | error | a `*.spec.*`, `*.test.*` or `*-spec.*` file outside the four test layers, `scripts/` and `tools/` included (R102) |
 | `HFS_REPO_LOCAL_CHECK` | error | a `check-*` file in `scripts/` or `tools/`, an `eslint-local-rules*` file or local eslint plugin, or a script that runs a local check (R103) |
 | `HFS_LINT_SUPPRESSION_FILE` | error | an `eslint.suppressions*` file, a `lint:suppressions` script, an eslint suppress flag or a suppressions config (R104) |
 | `HFS_PROOF_COMMAND_FILE_MISSING` | error | a `.starciwork` `requiresProof.<kind>.command` that runs a file the repository does not hold (R105) |
+| `HFS_PEER_INTEGRATION_MISSING` | error | the app root `package.json` depends on a driver integration (a pair of `knowledge/hfs/peer-integrations.yaml`) without its runtime peer, e.g. `@nestjs/apollo` on `@nestjs/platform-express` 11 without `@as-integrations/express5` (R111) |
 | `FE_WIRE_GENERATED` | error | a contract copy with no `codegen` script wired before `build` and `typecheck`, or generated types older than the copy (R52) |
 | `FE_I18N_PLACEMENT` | error | no `next-intl`, no `src/proxy.ts`, a `middleware.ts`, a route file outside `[locale]`, no `vi.json` catalog (R59) |
 | `FE_I18N_CATALOG` | error | a locale catalog lacking a key another locale has (R60) |
@@ -74,9 +77,8 @@ Its own checks (`scripts/lib/hfs-check.mjs`, `scripts/lib/hfs-rules/`; the rende
 The managed files are judged by `sync/managed.mjs` and `sync/ts-strict.mjs` (the package renders the templates; the runtime copy does not). The list of managed
 files is the `managedBy` slots of `slots.yaml`; `hfs sync --write` renders them and `hfs check` compares them, so a hand edit and a forgotten `sync` are the same finding.
 Each finding is reported once: the eslint and stylelint one-liners under R17, `tsconfig.json` under R22 when it names a flag, a workflow or hook that lost a canon step under R13 (or R19 for the format step), everything else under R05.
-A front end is rendered by the same mechanism as a back end: `tsconfig.json`, `eslint.config.mjs`, `stylelint.config.mjs`, `.prettierrc`, `.prettierignore`, the hooks, the workflow, the Sonar file
-and the `scripts` block (`lint` is the one lint gate, `hfs lint`: ESLint over the repository, the repository check and, for a front end, stylelint; `lint:fix` is the same with `--fix`; a front end has no test script, no test configuration and no e2e or coverage file: it has no tests, and `FE_NO_TESTS` (R97) refuses any spec, e2e file, test tool, test script or test dependency, `scripts/` included). `turbo.json` stays the repository's own
-(`fe.tool-config-repo`): it carries the repository's task graph, which no preset can render.
+The root and both sides are rendered by the one mechanism. The root: `package.json` `scripts` (`dev:be`, `dev:fe`, `build:be`, `build:fe`, `start:<app>`, `lint`, `lint:fix`, `test`, `test:integration`, `test:e2e`, `test:contract`, `test:stack`, `codegen`, `contract:emit`, `migrate`, `typecheck`, ...; a be script runs from `be/`, where its tsconfig and jest configuration are), `.prettierrc`, `.prettierignore`, the `.husky` hooks, the CI workflows, the Sonar file and the `.gitignore` block. A side: its `tsconfig.json` (resolving `@starci/tsconfig` from the root `node_modules`), its `eslint.config.mjs` one-liner, and for be `tsconfig.build.json`, `src/tests/tsconfig.json` and `jest.config.js`, for fe `stylelint.config.mjs`. `lint` is the one lint gate, `hfs lint`: ESLint over each side with its canon, the app check and stylelint over fe; `lint:fix` is the same with `--fix`. The front end has no test script, no test configuration and no e2e or coverage file: it has no tests, and `FE_NO_TESTS` (R97) refuses any spec, e2e file, test tool or test script under `fe/`. `turbo.json` stays the app's own
+(`fe.tool-config-repo`): it carries the task graph, which no preset can render.
 
 The architecture machine (`scripts/checks/architecture.mjs` of the runtime, the same code bundled here): tiers and import
 direction, owner public API, cycles, module registration and composition, clones, dead exports, required files,
@@ -90,26 +92,26 @@ of the changed source files without clones and dead exports, and no file-system
 checks still cover the whole tree. With no merge-base `--fast` is a refusal (exit 2) that names the fix, never a silent full
 pass.
 
-Exit codes: 0 clean, 1 an error finding, 2 a refusal (not a Git work tree, bad flag, `--fast` with no merge-base). The command never writes to the repository
-except `hfs init`, which writes `hfs.json` only when none exists.
+Exit codes: 0 clean, 1 an error finding, 2 a refusal (not a Git work tree, bad flag, `--fast` with no merge-base). `hfs check` and `hfs lint` never write to the app
+(`hfs lint --fix` lets ESLint and stylelint fix in place).
 
 ## Sonar
 
-One mechanism, the same for a back end and a front end: every finding of the canon is imported into Sonar, and the quality gate
-fails while any is open. Nothing is configured per repository; the pieces are managed files (`hfs sync`) and this package.
+One mechanism for both sides: every finding of the canon is imported into Sonar, and the quality gate
+fails while any is open. Nothing is configured per app; the pieces are managed files (`hfs sync`) and this package.
 
-One entry, one report, one file: `npm run lint` is `hfs lint`; `npm run lint -- --sonar reports/lint.sonar.json` writes the ONE Sonar file, read through `sonar.externalIssuesReportPaths`. It carries three engines: `starci-hfs` (the repository findings of `hfs check`, rule id = the finding code), `eslint` (the BE and FE canon plugins alike, rule id = the ESLint rule) and, for a front end, `stylelint` (rule id = the stylelint rule). `hfs lint --format json` prints the same findings as the one report `starci/lint@1` (`{ schema, ok, changed, counts.error, engines, errors[], findings[{ engine, rule, code, severity, path, line, column, message }] }`); `--changed <files...>` restricts ESLint and stylelint to those files and keeps of the repository findings the ones on a listed file or on no file. The exit code is 0 clean, 1 findings, 2 a tool could not run (a missing ESLint install is never a pass).
+One entry, one report, one file: `npm run lint` is `hfs lint`; `npm run lint -- --sonar reports/lint.sonar.json` writes the ONE Sonar file, read through `sonar.externalIssuesReportPaths`. It carries three engines: `starci-hfs` (the repository findings of `hfs check`, rule id = the finding code), `eslint` (the BE and FE canon plugins alike, rule id = the ESLint rule) and `stylelint` over fe (rule id = the stylelint rule). `hfs lint --format json` prints the same findings as the one report `starci/lint@1` (`{ schema, ok, changed, counts.error, engines, errors[], findings[{ engine, rule, code, severity, path, line, column, message }] }`); `--changed <files...>` restricts ESLint and stylelint to those files and keeps of the repository findings the ones on a listed file or on no file. The exit code is 0 clean, 1 findings, 2 a tool could not run (a missing ESLint install is never a pass).
 
 `--sonar` writes the findings as a Generic Issue Import document (SonarQube 10.3+ format: `{ rules, issues }`) before the verdict, so a
 failing lint still leaves its report. A rule's name and description are the catalog's English title and Vietnamese title, meaning and next step;
 impacts are HIGH (maintainability). `info` findings (the soft-size backlog) are report-only and not imported. The output is sorted, so two runs
 over one tree are byte-identical. Sonar drops an issue on a file it does not index (a tracked source file or stylesheet under `sonar.sources`), so the ONE placement rule of the three engines files a finding on
 any other path (hfs.json, a workflow, a config file, `e2e/`, a package the sources do not list) and a finding with no path on the first source file, its message starting with the real path.
-Sonar's own ESLint import (`sonar.eslint.reportPaths`) is not used: it drops those issues silently. A front end's `sonar.sources` and `sonar.tests` are `apps`, plus `packages` when hfs.json opts into `repo.packages` or an `fe.package.*` slot.
+Sonar's own ESLint import (`sonar.eslint.reportPaths`) is not used: it drops those issues silently. `sonar.sources` lists `be/apps`, `be/src` and `fe/apps` (plus `fe/packages` when the front end opts into an `fe.package.*` slot); `sonar.tests` is the back end's.
 
 The managed `sonar-project.properties` carries `sonar.externalIssuesReportPaths` (`reports/lint.sonar.json` only) and no `sonar.host.url` (the host is
 `SONAR_HOST_URL`); the managed CI workflow produces the report and runs the scan and the gate action with `!cancelled()`, so a failed lint step still
-reaches Sonar while the job stays failed. There is no `continue-on-error`. Both profiles run `npm run lint -- --sonar reports/lint.sonar.json` once, before the scan. The duplicate-block threshold (`ruleParams.<profile>.duplicateBlock`) has no Sonar property for TypeScript (SonarJS detects
+reaches Sonar while the job stays failed. There is no `continue-on-error`. CI runs `npm run lint -- --sonar reports/lint.sonar.json` once at the app root, before the scan. The duplicate-block threshold (`ruleParams.<side>.duplicateBlock`) has no Sonar property for TypeScript (SonarJS detects
 clones with its own token rule), so the machine enforces it (R21) and its findings are imported like every other.
 
 The gate is `knowledge/sonar-gate.yaml`, the one declaration: the new-code conditions (duplication, blocker and critical issues, hotspots; no coverage condition) and an `overall` part (0 open issues on the whole code,
@@ -117,7 +119,7 @@ duplicated lines density, cognitive complexity through the S3776 rule). A SonarQ
 open issue, imported or native; that is stricter than the three imports alone and is intended. `hfs check` reports `HFS_SONAR_CONFIG` (R11) when the
 properties file is not its render or the stack declaration names another gate. R20 and R21 have their Sonar enforcers as conditions of that file.
 
-Sonar does not depend on coverage: the managed properties file has no `sonar.*.lcov.reportPaths` and no `sonar.coverage.*`, the gate has no coverage condition, and the managed CI workflow uploads no coverage anywhere (no Codecov). A back end's unit coverage is the runner's: the managed `test` script is `jest --selectProjects unit --coverage`, which fails below the per-file 100 threshold on `src/**/*.service.ts`.
+Sonar does not depend on coverage: the managed properties file has no `sonar.*.lcov.reportPaths` and no `sonar.coverage.*`, the gate has no coverage condition, and the managed CI workflow uploads no coverage anywhere (no Codecov). The back end's unit coverage is the runner's: the managed `test` script is `jest --selectProjects unit --coverage`, which fails below the per-file 100 threshold on `src/**/*.service.ts`.
 
 ## Maintaining the bundle
 
@@ -128,8 +130,10 @@ derived from the machine's rule id lists). After changing any of those files, `k
 `knowledge/hfs/canon-pins.yaml`, `knowledge/patterns/fe/folder.yaml` or the catalog entries of those codes, run `node packages/hfs/scripts/sync-runtime.mjs`;
 `tests/hfs-cli.spec.mjs` fails on a stale copy. Bump `version` here and in the pin when the behaviour changes.
 
-The examples gate `node scripts/checks/check-example-architecture.mjs` runs this CLI (full check) on every `examples/*` directory
-with an `hfs.json` and fails on any error-level finding (it is heavy: run it once, by hand).
+The examples gate `node scripts/checks/check-example-architecture.mjs` runs `hfs lint` of this CLI at the root of every `examples/*`
+app with an `hfs.json` (`examples/todo-app`, `examples/ecommerce-app`) and fails on any finding or any tool that could not run;
+`hfs check` alone would miss the machine's source rules, which the canons judge. It is heavy: run it once, by hand, after `npm ci`
+in each app.
 
 ## Serving knowledge to other packages
 

package/bin/hfs.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-// hfs - the HFS command line of a StarCi product repository.
+// hfs - the HFS command line of a StarCi app: one repository, `<app>/`, with one package.json, lockfile and node_modules at its root
+// and two sides, be/ and fe/, declared by the one hfs.json of kind app. Every verb runs at the app root.
 //   hfs check   [--repo <dir>] [--json] [--fast] [--base <ref>]
 //                                            every tracked path has a slot; required files exist; nothing forbidden or
 //                                            tracked-that-must-be-ignored; pins match; every managed file equals its render
@@ -13,43 +14,47 @@
 //                                            --fast: only what changed since the merge-base with origin/main (else main; --base
 //                                            overrides it); the machine
 //                                            runs on those owners without clones and dead exports. No merge-base is a refusal
-//                                            (exit 2), never a silent full pass. Exit 1 on any error-level finding.
-//   hfs init    [--repo <dir>] [--stdout]   write a starter hfs.json by detecting the profile and the apps.
-//   hfs lint    [--repo <dir>] [--changed <file>...] [--fix] [--format text|json] [--sonar <file>] [--stylelint <glob>]
-//                                            the ONE lint entry (npm run lint): ESLint (canon per-file rules and the project-graph rules)
-//                                            plus this check's repository findings plus stylelint, as one starci/lint@1 report; --sonar writes
-//                                            the one Sonar import file. Exit 0 clean, 1 findings, 2 a tool could not run (lint/run.mjs).
+//                                            (exit 2), never a silent full pass. Exit 1 on any error-level finding. The root checks run once and
+//                                            the side checks and the machine once per side, the side folder as their root; every path is app-relative.
+//   hfs lint    [--repo <dir>] [--changed <file>...] [--fix] [--format text|json] [--sonar <file>]
+//                                            the ONE lint entry (npm run lint): ESLint per side with that side's canon config (per-file rules and
+//                                            the project-graph rules), this check's findings, and stylelint over the fe side, as one starci/lint@1
+//                                            report; --sonar writes the one Sonar import file. Exit 0 clean, 1 findings, 2 a tool could not run (lint/run.mjs).
+//   hfs scaffold app <name> [--into <dir>]  a new app <dir>/<name>/: the root (hfs.json, package.json, managed files, .starciwork) and the
+//                                            be/ and fe/ skeletons (scaffold/app.mjs). Refuses an existing directory.
 //   hfs explain <path> [--repo <dir>] [--json]   which slot owns the path, its tier, allowed imports, required tests.
-//   hfs emit-contracts [--repo <dir>]      write contracts/<app>/schema.graphql of every api app that serves GraphQL (emit/contracts.mjs):
+//   hfs emit-contracts [--repo <dir>]      write be/contracts/<app>/schema.graphql of every api app that serves GraphQL (emit/contracts.mjs):
 //                                            printSchema(lexicographicSortSchema) of the resolvers the app root composes; no env, no database, no network.
-//   hfs sync (--check | --write) [--root <dir>]  the generated files (husky, CI, .gitignore block, sonar); sync/cli.mjs
+//   hfs sync (--check | --write) [--root <dir>]  the managed files of the root (scripts, husky, CI, .gitignore block, sonar, prettier) and
+//                                            of each side (tsconfig, eslint, jest, stylelint); sync/cli.mjs
 //   hfs work-hygiene                              the pre-commit guard: staged .starciwork and .starcistacks paths, and the secrets guard over every staged file (read from the index); sync/cli.mjs
 //   hfs new service <dir> <name> [--inject <Decorator>=<module>:<Type> | <Class>=<module>]... [--repo <dir>]
-//                                            a back-end `<name>.service.ts` and its `<name>.service.spec.ts` skeleton (scaffold/service.mjs): the spec is built
+//                                            a back-end `<name>.service.ts` and its `<name>.service.spec.ts` skeleton (scaffold/service.mjs; <dir> is
+//                                            relative to be/): the spec is built
 //                                            with Test.createTestingModule, one provider per constructor dependency (kit doubles from @starci/jest-preset),
 //                                            one placeholder it per public method. Never overwrites a file.
 //   hfs new spec <file>.service.ts [--repo <dir>]  the spec skeleton of an existing service, read from its constructor with the repository's TypeScript
-// Every finding names a why code and carries its Vietnamese text. The command reads the repository, never writes to it
-// (init writes hfs.json only, and only when none exists). Exit codes: 0 clean, 1 error findings, 2 a refusal or bad usage.
-import fs from 'node:fs';
+// Every finding names a why code and carries its Vietnamese text. check, lint and explain read the app, never write to it. Exit codes:
+// 0 clean, 1 error findings, 2 a refusal or bad usage.
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isMain } from '../runtime/scripts/checks/common.mjs';
-import { checkRepository, explainPath, initRepo, trackedFiles } from '../runtime/scripts/lib/hfs-check.mjs';
-import { HfsSlotsError } from '../runtime/scripts/lib/hfs-slots.mjs';
+import { checkRepository, explainPath, trackedFiles } from '../runtime/scripts/lib/hfs-check.mjs';
+import { HfsSlotsError, loadSlotManifest, readRepoDeclaration } from '../runtime/scripts/lib/hfs-slots.mjs';
 import { formatFindings } from '../sync/format.mjs';
 import { main as syncMain } from '../sync/cli.mjs';
-import { SyncError } from '../sync/index.mjs';
+import { SyncError, loadPresets } from '../sync/index.mjs';
 import { managedFindings } from '../sync/managed.mjs';
 import { emitContracts } from '../emit/contracts.mjs';
 import { ScaffoldError, newService, newSpec } from '../scaffold/service.mjs';
+import { scaffoldApp } from '../scaffold/app.mjs';
 import { contractEmitFindings } from '../runtime/scripts/lib/hfs-rules/contract.mjs';
 import { lintRepository, parseLintArgs, printLintText } from '../lint/run.mjs';
 import { writeReport } from '../report/sonar.mjs';
 
 const USAGE = `hfs check [--repo <dir>] [--json] [--fast] [--base <ref>]
-hfs lint [--repo <dir>] [--changed <file>...] [--fix] [--format text|json] [--sonar <file>] [--stylelint <glob>]
-hfs init [--repo <dir>] [--stdout]
+hfs lint [--repo <dir>] [--changed <file>...] [--fix] [--format text|json] [--sonar <file>]
+hfs scaffold app <name> [--into <dir>]
 hfs emit-contracts [--repo <dir>]
 hfs explain <path> [--repo <dir>] [--json]
 hfs sync (--check | --write) [--root <dir>]
@@ -58,10 +63,10 @@ hfs new service <dir> <name> [--inject <Decorator>=<module>:<Type> | <Class>=<mo
 hfs new spec <file>.service.ts [--repo <dir>]
 `;
 const PER_CODE_LIMIT = 25;
-const VALUE_FLAGS = new Set(['--repo', '--base', '--inject']);
+const VALUE_FLAGS = new Set(['--repo', '--base', '--inject', '--into']);
 /** Flags that may repeat: their values are collected in order. */
 const LIST_FLAGS = new Set(['--inject']);
-const BOOL_FLAGS = new Set(['--json', '--stdout', '--fast']);
+const BOOL_FLAGS = new Set(['--json', '--fast']);
 
 function parse(argv) {
   const opts = { positional: [] };
@@ -114,20 +119,25 @@ function printExplain(e, out) {
   if (e.code) out(`  ${e.code}: ${e.titleVi}\n  ${e.whyVi}\n`);
 }
 
-/** The repository pass: slots, managed files, formatter, contract snapshots and the architecture machine's check surface. `only` limits the formatter to those files. */
+/**
+ * The app pass: slots, managed files, formatter, contract snapshots and the architecture machine's check surface, root and sides.
+ * `only` limits the formatter to those (app-relative) files.
+ */
 async function runCheck({ repoRoot, fast = false, base, only, presets, prettier }) {
   const tracked = trackedFiles(repoRoot);
-  // Managed files, the .gitignore block and sonar against their render (R04, R05, R11, ...), and prettier through the repository's own install (R19, never under --fast).
+  // Managed files of the root and both sides, the .gitignore block and sonar against their render (R04, R05, R11, ...), and prettier
+  // through the app's own install (R19, never under --fast).
   const extraFindings = [...await managedFindings({ repoRoot, tracked, presets }), ...(fast ? [] : await formatFindings({ repoRoot, files: only ?? tracked, prettier }))];
-  // R23 against the app itself (full pass only): the committed snapshots equal what `emit-contracts` writes now.
+  // R23 against the be side itself (full pass only): the committed snapshots equal what `emit-contracts` writes now.
   let contracts = null;
-  let declared = null;
-  try { declared = JSON.parse(fs.readFileSync(path.join(repoRoot, 'hfs.json'), 'utf8')); } catch { /* checkRepository reports the unreadable declaration */ }
-  if (declared?.profile === 'be') {
+  let be = null;
+  try { be = readRepoDeclaration(loadSlotManifest(), repoRoot).sides?.be ?? null; } catch { /* checkRepository reports the unreadable declaration */ }
+  if (be) {
     if (fast) contracts = { status: 'skipped', reason: '--fast does not emit the apps' };
     else {
-      const emitted = contractEmitFindings({ repoRoot, files: tracked, repo: declared, emit: emitContracts });
-      extraFindings.push(...emitted.findings);
+      const files = tracked.filter((file) => file.startsWith('be/')).map((file) => file.slice('be/'.length));
+      const emitted = contractEmitFindings({ repoRoot: path.join(repoRoot, 'be'), files, repo: be, emit: emitContracts });
+      extraFindings.push(...emitted.findings.map((finding) => ({ ...finding, side: 'be', path: `be/${finding.path}` })));
       contracts = { status: 'checked', apps: emitted.apps };
     }
   }
@@ -136,7 +146,7 @@ async function runCheck({ repoRoot, fast = false, base, only, presets, prettier
   return result;
 }
 
-/** `hfs lint`: ESLint, the repository checks and (front end) stylelint as one report; see lint/run.mjs. */
+/** `hfs lint`: ESLint per side, the app checks and stylelint over the fe side as one report; see lint/run.mjs. */
 async function lintMain(argv, { stdout, presets, prettier }) {
   const opts = parseLintArgs(argv);
   const repoRoot = path.resolve(opts.repo ?? process.cwd());
@@ -150,10 +160,20 @@ async function lintMain(argv, { stdout, presets, prettier }) {
   return exit;
 }
 
+/**
+ * The jest preset a new app renders its Sonar exclusions from: the one installed beside this @starci/hfs (`npx -p @starci/hfs -p
+ * @starci/jest-preset hfs scaffold app <name>`, or an install that holds both). None is a refusal, never a render without it.
+ */
+async function scaffoldPresets() {
+  try { return await loadPresets(path.dirname(fileURLToPath(import.meta.url))); } catch (error) {
+    throw new SyncError('HFS_SYNC_PRESET_MISSING', `${error.message.replace(/^[A-Z_]+: /, '')}; run hfs scaffold with @starci/jest-preset installed beside @starci/hfs (npx -p @starci/hfs -p @starci/jest-preset hfs scaffold app <name>)`);
+  }
+}
+
 /** `presets` and `prettier` are test seams: the Sonar exclusions sync would load from the repository's installed preset, and the repository's own prettier. */
 export async function main(argv, { stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier } = {}) {
   const [verb, ...rest] = argv;
-  if (!['check', 'lint', 'init', 'explain', 'sync', 'work-hygiene', 'emit-contracts', 'new'].includes(verb)) { stderr(USAGE); return 2; }
+  if (!['check', 'lint', 'scaffold', 'explain', 'sync', 'work-hygiene', 'emit-contracts', 'new'].includes(verb)) { stderr(USAGE); return 2; }
   try {
     if (verb === 'sync' || verb === 'work-hygiene') return await syncMain(argv);
     if (verb === 'lint') return await lintMain(rest, { stdout, presets, prettier });
@@ -168,9 +188,10 @@ export async function main(argv, { stdout = (s) => process.stdout.write(s), stde
     }
     if (verb === 'emit-contracts') {
       if (opts.positional.length) throw new Error('hfs emit-contracts takes no path');
-      const declaration = JSON.parse(fs.readFileSync(path.join(repoRoot, 'hfs.json'), 'utf8'));
-      const { written, skipped, standIns } = emitContracts({ repoRoot, declaration });
-      for (const file of written) stdout(`wrote ${file}
+      const be = readRepoDeclaration(loadSlotManifest(), repoRoot).sides?.be;
+      if (!be) throw new Error('hfs emit-contracts runs at the app root (the folder of hfs.json)');
+      const { written, skipped, standIns } = emitContracts({ repoRoot: path.join(repoRoot, 'be'), declaration: be });
+      for (const file of written) stdout(`wrote be/${file}
 `);
       stdout(`hfs emit-contracts: ${written.length} written${skipped.length ? `, ${skipped.join(', ')} serve no GraphQL` : ''}
 `);
@@ -190,10 +211,11 @@ export async function main(argv, { stdout = (s) => process.stdout.write(s), stde
 `);
       return 0;
     }
-    if (verb === 'init') {
-      if (opts.positional.length) throw new Error('hfs init takes no path');
-      const result = initRepo({ repoRoot, write: !opts.stdout });
-      if (opts.stdout) stdout(result.text); else stdout(`hfs init: wrote ${result.file} (${result.declaration.profile}, ${result.declaration.apps.map((a) => `${a.name}:${a.kind}`).join(', ')})\n`);
+    if (verb === 'scaffold') {
+      const [kind, name, ...extra] = opts.positional;
+      if (kind !== 'app' || !name || extra.length || opts.repo !== undefined) throw new Error('hfs scaffold takes `app <name> [--into <dir>]`');
+      const { root: created, files } = scaffoldApp({ name, into: path.resolve(opts.into ?? process.cwd()), presets: presets ?? await scaffoldPresets() });
+      stdout(`hfs scaffold app: created ${created} (${files.length} files); next: npm ci, then npm run lint\n`);
       return 0;
     }
     if (opts.positional.length !== 1) throw new Error('hfs explain takes exactly one path');

package/lint/run.mjs

@@ -1,36 +1,41 @@
-// hfs lint - the ONE lint entry and the ONE report of a StarCi repository.
+// hfs lint - the ONE lint entry and the ONE report of a StarCi app.
 //
-//   hfs lint [--repo <dir>] [--changed <file>...] [--fix] [--format text|json] [--sonar <file>] [--stylelint <glob>]
+//   hfs lint [--repo <dir>] [--changed <file>...] [--fix] [--format text|json] [--sonar <file>]
 //
-// It runs, over the repository (or over the files named by --changed):
-//   1. ESLint through the repository's own install and eslint.config.mjs (the canon plugin: the per-file rules and the project-graph
-//      rules of the architecture machine, findings on the line of the offending TypeScript file);
-//   2. `hfs check` for what has no TypeScript file to sit on (the tree, managed files, pins, CI, contracts, docs, .starciwork);
-//   3. stylelint when --stylelint names the style glob (front ends).
-// Their findings become one list of one shape (`starci/lint@1`). `--format json` prints that report on stdout; `--sonar <file>` writes the
-// same findings as THE Sonar Generic Issue Import file (engine ids starci-hfs, eslint, stylelint in one document); the exit code is the
-// land-gate input: 0 no finding, 1 at least one, 2 a tool could not run (never a pass).
-// --changed restricts ESLint and stylelint to the listed files and keeps of the repository findings only those on a listed file or on no file.
+// It runs at the app root (the folder of hfs.json), over the app (or over the app-relative files named by --changed):
+//   1. ESLint once per side, from the side folder, through the app's own install and that side's eslint.config.mjs (be/ the be canon,
+//      fe/ the fe canon: the per-file rules and the project-graph rules of the architecture machine, findings on the line of the
+//      offending TypeScript file); each side lints only its own files, so the be rules never see fe/ and the fe rules never see be/;
+//   2. `hfs check` for what has no TypeScript file to sit on (the tree, managed files, pins, CI, contracts, docs, .starciwork), root and sides;
+//   3. stylelint over the fe side's stylesheets (sync STYLE_GLOB), from fe/ with its stylelint.config.mjs.
+// Their findings become one list of one shape (`starci/lint@1`), every path app-relative. `--format json` prints that report on stdout;
+// `--sonar <file>` writes the same findings as THE Sonar Generic Issue Import file (engine ids starci-hfs, eslint, stylelint in one
+// document); the exit code is the land-gate input: 0 no finding, 1 at least one, 2 a tool could not run (never a pass).
+// --changed restricts ESLint and stylelint to the listed files and keeps of the app findings only those on a listed file or on no file.
 import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import { linterReport, mergeReports, sonarReport, sourceRootsOf } from '../report/sonar.mjs';
+import { SIDES, appRelativeMessages, loadSlotManifest, readRepoDeclaration } from '../runtime/scripts/lib/hfs-slots.mjs';
+import { STYLE_GLOB } from '../sync/index.mjs';
 
 export const LINT_SCHEMA = 'starci/lint@1';
+/** The side whose stylesheets stylelint judges. */
+const STYLE_SIDE = 'fe';
 const CODE_PREFIX = /^\[([A-Z][A-Z0-9_]+)\] /;
 const posix = (file) => String(file).replace(/\\/g, '/').replace(/^\.\//, '');
 
 /** The flags of `hfs lint`; `--changed` takes every argument up to the next flag. */
 export function parseLintArgs(argv) {
-  const opts = { changed: null, fix: false, format: 'text', repo: undefined, sonar: undefined, stylelint: undefined };
+  const opts = { changed: null, fix: false, format: 'text', repo: undefined, sonar: undefined };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--changed') {
       opts.changed = [];
       while (i + 1 < argv.length && !argv[i + 1].startsWith('--')) opts.changed.push(posix(argv[++i]));
     } else if (arg === '--fix') opts.fix = true;
-    else if (['--format', '--repo', '--sonar', '--stylelint'].includes(arg)) {
+    else if (['--format', '--repo', '--sonar'].includes(arg)) {
       if (argv[i + 1] === undefined) throw new Error(`${arg} needs a value`);
       opts[arg.slice(2)] = argv[++i];
     } else throw new Error(`unknown argument ${arg}`);
@@ -39,39 +44,43 @@ export function parseLintArgs(argv) {
   return opts;
 }
 
-/** A linter's json results through the repository's own install: `{ results }` or `{ error }`. */
-function runLinter({ repoRoot, pkg, bin, args }) {
+/** A linter's json results through the app's own install, run from `cwd` (a side folder): `{ results }` or `{ error }`. */
+function runLinter({ cwd, pkg, bin, args }) {
   let entry;
   try {
-    const manifest = createRequire(path.join(repoRoot, 'package.json')).resolve(`${pkg}/package.json`);
+    const manifest = createRequire(path.join(cwd, 'package.json')).resolve(`${pkg}/package.json`);
     const declared = JSON.parse(fs.readFileSync(manifest, 'utf8')).bin;
     entry = path.join(path.dirname(manifest), typeof declared === 'string' ? declared : declared[bin]);
   } catch {
-    return { error: `${pkg} is not installed under ${repoRoot}` };
+    return { error: `${pkg} is not installed for ${cwd}` };
   }
-  const run = spawnSync(process.execPath, [entry, ...args], { cwd: repoRoot, encoding: 'utf8', maxBuffer: 512 * 1024 * 1024 });
-  // The linters exit 1 when they found something; no json at all means they could not run.
+  const run = spawnSync(process.execPath, [entry, ...args], { cwd, encoding: 'utf8', maxBuffer: 512 * 1024 * 1024 });
+  // The linters exit 1 when they found something; no json at all means they could not run. ESLint prints its report on stdout,
+  // stylelint (16 and later) its formatter output on stderr.
   let results;
-  try { results = JSON.parse(run.stdout); } catch { return { error: `${pkg} produced no json report (exit ${run.status}): ${String(run.stderr || run.stdout).trim().split('\n')[0]}` }; }
+  try { results = JSON.parse(run.stdout.trim() || run.stderr); } catch { return { error: `${pkg} produced no json report in ${path.basename(cwd)}/ (exit ${run.status}): ${String(run.stderr || run.stdout).trim().split('\n')[0]}` }; }
   if (!Array.isArray(results)) return { error: `${pkg} produced a report that is not a result list` };
   return { results };
 }
 
-const eslintFindings = (results, repoRoot) => results.flatMap((result) => (result.messages ?? []).map((message) => ({
+const eslintFindings = (results, appRoot) => results.flatMap((result) => (result.messages ?? []).map((message) => ({
   engine: 'eslint', rule: message.ruleId ?? 'eslint-error', code: CODE_PREFIX.exec(message.message ?? '')?.[1] ?? null, severity: 'error',
-  path: posix(path.relative(repoRoot, result.filePath)), line: message.line ?? null, column: message.column ?? null, message: message.message,
+  path: posix(path.relative(appRoot, result.filePath)), line: message.line ?? null, column: message.column ?? null, message: message.message,
 })));
 
-const stylelintFindings = (results, repoRoot) => results.flatMap((result) => (result.warnings ?? []).map((warning) => ({
+const stylelintFindings = (results, appRoot) => results.flatMap((result) => (result.warnings ?? []).map((warning) => ({
   engine: 'stylelint', rule: warning.rule || 'stylelint-error', code: null, severity: 'error',
-  path: posix(path.relative(repoRoot, result.source)), line: warning.line ?? null, column: warning.column ?? null, message: warning.text,
+  path: posix(path.relative(appRoot, result.source)), line: warning.line ?? null, column: warning.column ?? null, message: warning.text,
 })));
 
 const byLocation = (a, b) => `${a.path ?? ''}:${String(a.line ?? 0).padStart(7, '0')}:${a.rule}`.localeCompare(`${b.path ?? ''}:${String(b.line ?? 0).padStart(7, '0')}:${b.rule}`);
 
+/** The files of `changed` (app-relative) below `side`/, relative to the side folder. */
+const onSide = (changed, side) => changed.filter((file) => file.startsWith(`${side}/`)).map((file) => file.slice(side.length + 1));
+
 /**
- * Run the whole lint of a repository. `hfsCheck(repoRoot)` returns the `hfs check` result (`{ findings, tracked }`); the CLI injects it.
- * Returns `{ report, sonar, exit }`; `sonar` is the merged Generic Issue Import document.
+ * Run the whole lint of the app at `repoRoot`. `hfsCheck(repoRoot)` returns the `hfs check` result (`{ findings, tracked }`); the CLI
+ * injects it. Returns `{ report, sonar, exit }`; `sonar` is the merged Generic Issue Import document.
  */
 export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles = () => [] }) {
   const changed = opts.changed === null ? null : new Set(opts.changed);
@@ -81,26 +90,48 @@ export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles =
   const raw = { eslint: [], stylelint: [] };
   const engines = {};
 
-  const sources = existing.filter((file) => /\.(?:[cm]?[jt]sx?)$/.test(file));
-  if (changed === null || sources.length) {
-    const linted = runLinter({ repoRoot, pkg: 'eslint', bin: 'eslint', args: ['--format', 'json', ...(opts.fix ? ['--fix'] : []), ...(changed ? sources : ['.'])] });
+  let app = null;
+  try { app = readRepoDeclaration(loadSlotManifest(), repoRoot); } catch (error) { errors.push(`hfs lint runs at the app root: ${String(error?.message ?? error)}`); }
+  if (app && !app.sides) { errors.push(`${repoRoot} is the ${app.side} side of an app; hfs lint runs at the app root, the folder of hfs.json`); app = null; }
+
+  // 1. ESLint, once per side, from the side folder with that side's config.
+  engines.eslint = { sides: {} };
+  for (const side of app ? SIDES : []) {
+    const sources = onSide(existing, side).filter((file) => /\.(?:[cm]?[jt]sx?)$/.test(file));
+    if (changed !== null && !sources.length) { engines.eslint.sides[side] = { files: 0, skipped: 'no changed source file' }; continue; }
+    const linted = runLinter({ cwd: path.join(repoRoot, side), pkg: 'eslint', bin: 'eslint', args: ['--format', 'json', ...(opts.fix ? ['--fix'] : []), ...(changed ? sources : ['.'])] });
     if (linted.error) errors.push(linted.error);
-    else { raw.eslint = linted.results; findings.push(...eslintFindings(linted.results, repoRoot)); }
-    engines.eslint = { files: changed ? sources.length : null };
-  } else engines.eslint = { files: 0, skipped: 'no changed source file' };
+    else {
+      // The side canon names side-relative paths in its messages; the report names every path from the app root.
+      const appRelative = appRelativeMessages(side, path.join(repoRoot, side));
+      for (const result of linted.results) for (const message of result.messages ?? []) message.message = appRelative(message.message);
+      raw.eslint.push(...linted.results);
+      findings.push(...eslintFindings(linted.results, repoRoot));
+    }
+    engines.eslint.sides[side] = { files: linted.results?.length ?? 0 };
+  }
 
-  if (opts.stylelint !== undefined) {
-    const styles = existing.filter((file) => file.endsWith('.css'));
+  // 3. stylelint over the fe side's stylesheets.
+  if (app) {
+    const styles = onSide(existing, STYLE_SIDE).filter((file) => file.endsWith('.css'));
     if (changed === null || styles.length) {
-      const linted = runLinter({ repoRoot, pkg: 'stylelint', bin: 'stylelint', args: [...(changed ? styles : [opts.stylelint]), '--formatter', 'json', ...(opts.fix ? ['--fix'] : [])] });
+      const linted = runLinter({ cwd: path.join(repoRoot, STYLE_SIDE), pkg: 'stylelint', bin: 'stylelint', args: [...(changed ? styles : [STYLE_GLOB]), '--formatter', 'json', ...(opts.fix ? ['--fix'] : [])] });
       if (linted.error) errors.push(linted.error);
-      else { raw.stylelint = linted.results; findings.push(...stylelintFindings(linted.results, repoRoot)); }
+      else {
+        const appRelative = appRelativeMessages(STYLE_SIDE, path.join(repoRoot, STYLE_SIDE));
+        for (const result of linted.results) for (const warning of result.warnings ?? []) warning.text = appRelative(warning.text);
+        raw.stylelint = linted.results;
+        findings.push(...stylelintFindings(linted.results, repoRoot));
+      }
     }
-    engines.stylelint = { files: changed ? styles.length : null };
+    engines.stylelint = { side: STYLE_SIDE, files: raw.stylelint.length };
   }
 
+  // 2. The app check: root and sides.
   let checked = { findings: [] };
-  try { checked = await hfsCheck(repoRoot); } catch (error) { errors.push(`hfs check could not run: ${String(error?.message ?? error)}`); }
+  if (app) {
+    try { checked = await hfsCheck(repoRoot); } catch (error) { errors.push(`hfs check could not run: ${String(error?.message ?? error)}`); }
+  }
   const repoErrors = checked.findings.filter((finding) => finding.level === 'error');
   const kept = changed === null ? repoErrors : repoErrors.filter((finding) => !finding.path || changed.has(posix(finding.path)));
   for (const finding of kept) {
@@ -116,7 +147,7 @@ export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles =
   const sonar = mergeReports([
     sonarReport(kept, { sourceRoots, tracked }),
     linterReport('eslint', raw.eslint, { root: repoRoot, sourceRoots, tracked }),
-    ...(opts.stylelint !== undefined ? [linterReport('stylelint', raw.stylelint, { root: repoRoot, sourceRoots, tracked })] : []),
+    linterReport('stylelint', raw.stylelint, { root: repoRoot, sourceRoots, tracked }),
   ]);
   const report = { schema: LINT_SCHEMA, ok: findings.length === 0 && errors.length === 0, repoRoot, changed: changed ? [...changed].sort() : null, counts: { error: findings.length }, engines, errors, findings };
   return { report, sonar, exit: errors.length ? 2 : findings.length ? 1 : 0 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@starci/hfs",
-  "version": "3.0.0",
-  "description": "The HFS command line of a StarCi product repository: hfs check, init, explain, sync and work-hygiene. Self-contained: it carries the runtime files it reads.",
+  "version": "4.0.1",
+  "description": "The HFS command line of a StarCi app (one repository: the root, be/ and fe/): hfs lint, check, scaffold app, explain, sync and work-hygiene. Self-contained: it carries the runtime files it reads.",
   "type": "module",
   "license": "UNLICENSED",
   "private": false,

package/runtime/engine/admission.mjs

@@ -72,9 +72,9 @@ const leasePath=resourceKey=>String(resourceKey??'').startsWith(PATH_LEASE_PREFI
  * The spelling two lease paths are compared in. The same file must compare equal however a workflow
  * spelled it (nivo wf-nivo-fe-debt-mug06w7h inc-52a4a5ee5b12: `apps/app/src/messages/vi.json` bare for
  * the fe repository vs `nivo-fe/apps/app/src/messages` repository-prefixed never overlapped). `canonicalOf`
- * (scripts/kernel/lease-canon.mjs) resolves a path to its repository-qualified form
- * `repository:<role>/<path>` — for a held row through its holder job, so a lease taken before
- * canonical keys existed still conflicts; paths on Windows compare case-insensitively, as its file
+ * (scripts/kernel/lease-canon.mjs) resolves a path to its app-relative form in a bound app
+ * (be/<path>, fe/<path>) — for a held row through its holder job, so every spelling of one file
+ * compares as one key; paths on Windows compare case-insensitively, as its file
  * systems do.
  */
 export const leaseCompareForm=(leasePathValue,{canonicalOf=null,row=null,platform=process.platform}={})=>{

package/runtime/engine/ledger-db.mjs

@@ -54,7 +54,7 @@ export const JOB_ARTIFACT_ROLES=Object.freeze(['check-output','check-stdout','ch
   'direction','prompt','render','redline','critique','capture','dom','screenshot','video','trace','uat-run','metrics','salvage','scan','other']);
 
 export const LEDGER_SCHEMA='starci/runtime@1';
-export const LEDGER_VERSION=4;
+export const LEDGER_VERSION=5;
 
 const need=(ok,message,code)=>{if(!ok)throw Object.assign(Error(message),code?{code}:{});};
 const json=value=>value===undefined||value===null?null:JSON.stringify(value);
@@ -127,7 +127,7 @@ const INIT_SQL_FILE=new URL('./migrations/runtime/0001-init.sql',import.meta.url
 const INIT_SQL=fs.readFileSync(INIT_SQL_FILE,'utf8');
 const INIT_SQL_SHA=sha256(INIT_SQL);
 /** Forward migrations after 0001-init, in order; each bumps user_version to its `version` (migrateLedger). */
-const FORWARD_MIGRATIONS=Object.freeze([{version:3,name:'0003-usage-unavailable'},{version:4,name:'0004-attempt-why'}]);
+const FORWARD_MIGRATIONS=Object.freeze([{version:3,name:'0003-usage-unavailable'},{version:4,name:'0004-attempt-why'},{version:5,name:'0005-ended-workflow-views'}]);
 export const LEDGER_BUSY_TIMEOUT_MS=15000;
 /**
  * Writer pragmas. wal_autocheckpoint=0 on EVERY connection except the one checkpointer (openLedger({checkpointer:true}),