@starci/hfs 4.7.27 → 4.7.29

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 4.7.29 - 2026-10-24
+- Added: a new full app ships its test world (`scaffold/test-world.mjs`, `templates/be/test-world/`): the `@starci/test-world` declaration under `be/src/tests/world/`, an integration spec of readiness over the real database and one e2e spec per api app, so the integration, e2e and contract rows of the release gate run real specs.
+- Added: `starci app upgrade [--plan]` on a full app without `be/src/tests/world/global-setup.ts` adds that world and the test devDependencies it lacks at canon pins, never overwriting a file (`HFS_UPGRADE_FILE_CONFLICT`); proven by `src/main.spec.mjs`.
+- Changed: the bundled canon pins select zod 4.6.7 (GHSA-mrhx-c7xc-m3w5 is fixed in 4.6.6), @starci/cli 1.7.29, @starci/eslint-canon-be 3.4.37 and @starci/eslint-canon-fe 8.4.36.
+
+## 4.7.28 - 2026-10-23
+- Added: `scripts/lib/sonar-new-code.mjs` joins the bundled runtime copy (the New Code definition `starci sonar project ensure` sets), proven by `src/sonar-new-code.spec.mjs`.
+- Fixed: the bundled gate-loosening detector no longer reads a quoted operand of a printed message as a ban-list row, nor the upkeep of an exception list the check stops reading as enforcement lost (`src/bypass-detector.spec.mjs`).
+- Added: `scripts/lib/provision-control-failure.mjs` joins the bundled runtime copy, proven by `src/provision-control-failure.spec.mjs`.
+- Changed: the bundled canon pins select @starci/cli 1.7.28, @starci/eslint-canon-be 3.4.36 and @starci/eslint-canon-fe 8.4.35.
+- Changed: no check keeps a list of exceptions. The JSON a tool requires is declared once by format (`scripts/lib/json-formats.mjs`, bundled), the failure-code scanner no longer counts a literal the code only reads (`scripts/lib/failure-code-reads.mjs`, bundled), and a rule is proven by a package spec unless every enforcer it has runs only inside the runtime (`RUNTIME_ONLY_ENFORCERS`); the catalog keys `specNa`, `exampleNa` and the unreachable witness are gone.
+- Added: the specs of the deleted runtime tests that prove bundled checkers, restored as package specs (`src/*.spec.mjs`, helpers in `src/helpers`, fixtures in `src/fixtures`), and fresh specs for R296-R301, the tree codes of R01/R03, R112 and R216.
+- Changed: `scripts/gates/sonar-gate.mjs` and `scripts/gates/starcistacks.mjs` joined the bundled runtime copy, and a few exports the specs read are exported again.
+- Changed: a red candidate CI never passes: `packages/hfs/release/candidate-ci.mjs` has no ci-override record any more (owner ruling 2026-10-22, a loosening is always red).
+- Added: R303 `HFS_BYPASS_MARKER` in `starci app check` and the bypass guard of `starci app hygiene` (staged files read from the index): an inline disable of any tool, a type-check escape, a Sonar or coverage ignore, a skipped or focused test and a failure swallowed in a hook or workflow are refused in a product repository, the front end included.
+- Changed: the managed `.husky/pre-commit` runs `starci app sync --check` and ends the hook when any step fails; the stylelint step can no longer be skipped by a failing run.
+
 ## 4.7.27 - 2026-10-23
 - Fixed: the bundled `scripts/lib/managed-json.mjs` passes each slot path to `braceVariants` through an arrow, so `flatMap` never hands it an index (Sonar S7727).
 - Changed: the bundled canon pins select @starci/cli 1.7.27, @starci/eslint-canon-be 3.4.34 and @starci/eslint-canon-fe 8.4.33.

package/README.md

@@ -61,6 +61,13 @@ unchanged lite tree through the full-edition view. The check is read-only; `--db
 comparison when the local stack is available. Applying `starci app upgrade --edition full` adds the full-only managed configuration,
 test layers and cli requirements without rewriting product code. Downgrade to lite is not supported.
 
+A new full app ships its test world (`scaffold/test-world.mjs`): the `@starci/test-world` declaration under `be/src/tests/world/`
+(the dev stack's Postgres per connection, the api apps, the cli app's migration runner as the migrate step), an integration spec of
+readiness over the real database and one e2e spec per api app booted over the migrated database, beside the contract spec of the
+be skeleton, so `test:integration`, `test:e2e` and `test:contract` of the release gate run real specs. On a full app that has no
+`be/src/tests/world/global-setup.ts`, `starci app upgrade [--plan]` adds those files and the test devDependencies it lacks; a world
+file that exists and differs refuses (`HFS_UPGRADE_FILE_CONFLICT`) and nothing is overwritten.
+
 ## Creating a service
 
 Every file of a spec-required role of `ruleParams.be.unitRoles` — a `*.service.ts`, a `*.cli.ts` of the cli feature root — owes exactly one colocated `<name>.<role>.spec.ts` (unit test standard), and any other file of a `ruleParams.be.logicRoles` role inside a `coverage: required` slot may carry one beside it. `starci app new` is the one way a service and its spec come into being together:
@@ -187,10 +194,9 @@ 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 `starci release sync-runtime`;
 `starci release sync-runtime --check` fails on a stale copy. Bump `version` here and in the pin when the behaviour changes.
 
-The examples gate `starci runtime check --only example-architecture` runs `starci app lint` of this CLI at the root of every `examples/*`
+The examples workflow (`.github/workflows/examples.yml`) runs `starci app lint` of this CLI at the root of every `examples/*`
 app with an `hfs.json` (each `examples/<app>` root) and fails on any finding or any tool that could not run;
-`starci app 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.
+`starci app check` alone would miss the machine's source rules, which the canons judge.
 
 ## Serving knowledge to other packages
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.7.27",
+  "version": "4.7.29",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",
@@ -15,6 +15,12 @@
     "smol-toml": "1.9.0"
   },
   "devDependencies": {
+    "@nestjs/common": "11.2.5",
+    "@nestjs/core": "11.2.5",
+    "@nestjs/testing": "11.2.5",
+    "prettier": "3.9.6",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2",
     "typescript": "5.9.3"
   },
   "files": [

package/release/candidate-ci.mjs

@@ -5,11 +5,8 @@
 //   red       RELEASE_CANDIDATE_CI_RED (a run or a job that concluded skipped is red, never a pass: owner ruling 2026-10-22, a skip is a loosening) with the run URL and the failing jobs and steps; nothing reaches the default branch. The candidate ref stays for diagnosis
 //   timeout   RELEASE_CANDIDATE_CI_TIMEOUT: no run listed within the grace (a queued run is listed), or it did not end within the wait
 //   unknown   RELEASE_CI_UNKNOWN: GitHub could not be read to the end; a release never proceeds blind
-// Emergency path (documented, owner-only): the owner's `starci release ci-override --sha <sha>` record for this exact sha
-// (<git common dir>/starci-release/<sha>.ci-override.json, schema starci/ci-override@1) lets a red candidate through, and the push says so.
+// There is no override: a red candidate never passes (owner ruling 2026-10-22: a loosening is always red).
 // Every process goes through ctx.spawn (git, gh); the wait through ctx.sleep and ctx.now.
-import fs from 'node:fs';
-import path from 'node:path';
 
 const CANDIDATE_PREFIX = 'refs/heads/release/candidate-';
 /** The wait of the candidate run: poll interval, the grace for a run to appear, the wait for it to end (an app's ci.yml jobs time out within 45 minutes). */
@@ -67,19 +64,6 @@ export function failingJobs(ctx, runRow) {
   });
 }
 
-/** Only a complete starci/ci-override@1 record for this exact commit can excuse a red candidate. */
-export function overrideOf(ctx, sha) {
-  if (!SHA.test(String(sha))) return null;
-  const common = run(ctx, 'git', ['rev-parse', '--git-common-dir']);
-  if (common.error || common.status !== 0 || !String(common.stdout ?? '').trim()) return null;
-  const file = path.join(path.resolve(ctx.cwd, String(common.stdout).trim()), 'starci-release', `${sha}.ci-override.json`);
-  try {
-    const record = JSON.parse(fs.readFileSync(file, 'utf8'));
-    if (record.schema !== 'starci/ci-override@1' || record.sha !== sha || typeof record.reason !== 'string' || !record.reason.trim() || typeof record.by !== 'string' || !record.by.trim() || typeof record.at !== 'string' || !Number.isFinite(Date.parse(record.at))) return null;
-    return record;
-  } catch { return null; }
-}
-
 /** Poll the candidate run of `sha` until green or red, or the grace (no run) or the wait passes: {state: green|red|timeout|unstarted|unknown, run}. */
 export async function waitForCandidate(ctx, sha, wait = CANDIDATE_WAIT) {
   const started = ctx.now();
@@ -96,8 +80,8 @@ export async function waitForCandidate(ctx, sha, wait = CANDIDATE_WAIT) {
 }
 
 /**
- * The candidate step of the push: push HEAD to the candidate ref (through the pre-push hook), wait for its CI. {ok, lines, data: {ref, state, run, failing, override}}.
- * ok only on green, or on red under the owner's override record for this exact sha.
+ * The candidate step of the push: push HEAD to the candidate ref (through the pre-push hook), wait for its CI. {ok, lines, data: {ref, state, run, failing}}.
+ * ok only on green.
  */
 export async function candidateStep(ctx, { head, tag, prefix, remote, wait = CANDIDATE_WAIT }) {
   const ref = candidateRef(tag, prefix);
@@ -110,9 +94,7 @@ export async function candidateStep(ctx, { head, tag, prefix, remote, wait = CAN
   if (seen.state === 'green') return { ok: true, lines: [...lines, `candidate CI   green${url}`], data: { ref, state: 'green', run: seen.run } };
   if (seen.state === 'red') {
     const failing = failingJobs(ctx, seen.run);
-    const record = overrideOf(ctx, head);
     const detail = failing.length ? failing.join('; ') : 'the failing jobs could not be read';
-    if (record) return { ok: true, lines: [...lines, `candidate CI   RED${url}; failing: ${detail}`, `RELEASE_CANDIDATE_CI_RED overridden by the owner (${record.by}): ${record.reason}`], data: { ref, state: 'red', run: seen.run, failing, override: { by: record.by, reason: record.reason, at: record.at } } };
     return { ok: false, lines: [...lines, `RELEASE_CANDIDATE_CI_RED: the ci.yml run of ${head.slice(0, 10)} on ${ref} is red${url}; failing: ${detail}. Nothing reached the default branch; the candidate ref stays for diagnosis`], data: { ref, state: 'red', run: seen.run, failing } };
   }
   if (seen.state === 'unstarted') return { ok: false, lines: [...lines, `RELEASE_CANDIDATE_CI_TIMEOUT: no ci.yml run started for ${head.slice(0, 10)} on ${ref} within ${wait.graceMinutes} minutes (does .github/workflows/ci.yml trigger on release/candidate-*? run starci app sync)`], data: { ref, state: 'unstarted' } };

package/runtime/engine/yaml.mjs

@@ -4,7 +4,7 @@
 // rather than importing node_modules; yaml is a devDependency and a direct import breaks that
 // install. tests/engine/yaml-vendored-parity.spec.mjs proves the vendored parseYaml/stringifyYaml behave
 // exactly like yaml@2.9.0 with these options for every tracked *.yaml/*.yml file (parsed values
-// deep-equal, stringify output byte-identical). License: engine/yaml-license.json.
+// deep-equal, stringify output byte-identical). License: engine/yaml-license.yaml.
 // Rebuild only when deliberately upgrading yaml. The entry source is:
 //   import * as YAML from 'yaml';
 //   export function parseYaml(source) {

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -29,14 +29,14 @@ pins:
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.34
+    version: 3.4.37
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.4.33
+    version: 8.4.36
     group: starci
     install: registry
     side: fe
@@ -76,14 +76,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.7.27
+    version: 1.7.29
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.7.27
+    version: 4.7.29
     group: starci
     install: registry
     side: both
@@ -336,10 +336,10 @@ pins:
     side: fe
     why: 'the zod resolver of react-hook-form (fe-stack forms); version read from the starci-academy package-lock on 2026-10-13.'
   'zod':
-    version: 4.4.3
+    version: 4.6.7
     group: framework
     side: fe
-    why: 'the schema library of front-end forms and boundary parsing (fe-stack forms); version read from the starci-academy package-lock on 2026-10-13.'
+    why: 'the schema library of front-end forms and boundary parsing (fe-stack forms), also an npm override of every app root; 4.6.7 (the registry latest on 2026-10-24) closes GHSA-mrhx-c7xc-m3w5 (high, fixed in 4.6.6), which npm audit --audit-level=high reported against 4.4.3.'
   '@reduxjs/toolkit':
     version: 2.11.2
     group: framework