@starci/hfs 4.7.18 → 4.7.19

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 4.7.19 - 2026-10-21
+- Changed: supersedes 4.7.18 (app lint broken: the canons' Sonar way block carries its own ignores, which `starci app lint` refused as an unsupported source scope, so it exited 2 without running ESLint and reported 0 findings); 4.7.18 is not used.
+- Fixed: `starci app lint` reads the canons' flat config as flat config defines it: global ignores prune the source walk and a block's own ignores narrow only that block, so the Sonar way block no longer makes the source scope unavailable (exit 2 without ESLint); a file is a source when some block's files match it and that block's ignores do not.
+- Fixed: the full scaffold's ui package pins react-dom at the react version beside react.
+- Fixed: the scaffolded `migrate-connections.client.spec.ts` mocks an applied migration with only its `name` (the `AppliedMigration` port), so the full scaffold typechecks again.
+- Added: `release.requireCi` (default false, owner ruling release-require-ci-per-project): `starci app release push` waits for the candidate CI only for an app that sets it true; with false it needs the annotated tag and the green L4 record, runs the dry run and pushes atomically, and the L4 record and the output state that CI was not required; canon pins follow the matching package cohort.
+
 ## 4.7.18 - 2026-10-21
 - Changed: supersedes 4.7.17, published from a lane whose history the owner refused (an unapproved allowlist entry) and therefore a superseded orphan that is not used; this version carries the same work plus the standalone scaffold fix.
 - Fixed: the managed CI's coverage job runs `starci app coverage verify <lcov>`, the coverage judgement alone over the merged report, instead of `npm run codegen && starci app check --coverage-from` (the whole app check the fast and lint jobs already ran); its default timeout is 15 minutes (`knowledge/hfs/ci-standard.yaml`). NIVO v0.3.0's coverage job took 18m43s of 20 and the tag run was cancelled.

package/lint/run.mjs

@@ -137,8 +137,35 @@ const onSide = (changed, side) => changed.filter((file) => file.startsWith(`${si
 const fileKey = (file) => process.platform === 'win32' ? path.resolve(file).toLowerCase() : path.resolve(file);
 const inside = (root, file) => { const rel = path.relative(root, file); return rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel); };
 
+/**
+ * The lint scope a flat config declares: `ignored(file)` for its global ignores (a block holding only `ignores` and `name`), which prune
+ * the walk, and `source(file)` for a file some block's `files` select while that block's own `ignores` do not (standard flat-config
+ * semantics: the Sonar-way block of the canons narrows itself to the scanned files). Negated or non-string selectors cannot prove a
+ * scope and are refused.
+ */
+export function canonScope(config) {
+  const blocks = [], ignored = [];
+  for (const block of config) {
+    if (!block || typeof block !== 'object') throw new Error('the installed canon returned an invalid config block');
+    for (const field of ['files', 'ignores']) {
+      if (block[field] === undefined) continue;
+      if (!Array.isArray(block[field]) || block[field].some((glob) => typeof glob !== 'string' || glob.startsWith('!'))) throw new Error(`unsupported canon ${field} selectors`);
+    }
+    const patterns = (globs) => (globs ?? []).flatMap((glob) => braceVariants(glob).map(globExpression));
+    const global = block.ignores !== undefined && Object.keys(block).every((key) => ['ignores', 'name'].includes(key));
+    if (global) ignored.push(...patterns(block.ignores));
+    else if (block.files !== undefined) blocks.push({ files: patterns(block.files), ignores: patterns(block.ignores) });
+  }
+  if (!blocks.length) throw new Error('the installed canon has no source selectors');
+  const matches = (list, file) => list.some((pattern) => pattern.test(file));
+  return {
+    ignored: (file) => matches(ignored, file),
+    source: (file) => blocks.some((block) => matches(block.files, file) && !matches(block.ignores, file)),
+  };
+}
+
 /** Read the installed canon's source selectors, then enumerate that scope; unavailable or unsupported selectors cannot prove coverage. */
-async function sourceFiles({ repoRoot, cwd, side, scope }) {
+async function sourceFiles({ repoRoot, cwd, side, scope: folderScope }) {
   const entry = createRequire(path.join(cwd, 'package.json')).resolve(`@starci/eslint-canon-${side}`);
   // The canon must be the app's own install: resolved inside the app root, or inside the app's node_modules when that folder is a link to the install
   // (the runtime's examples lint in a sealed copy whose node_modules links the example's own install, scripts/hfs/example-secrets.mjs).
@@ -149,30 +176,19 @@ async function sourceFiles({ repoRoot, cwd, side, scope }) {
   if (typeof factory !== 'function' || typeof canon.loadHfs !== 'function') throw new Error('the installed canon has no supported config factory');
   const config = await factory({ hfs: canon.loadHfs(pathToFileURL(path.join(cwd, 'eslint.config.mjs')).href) });
   if (!Array.isArray(config)) throw new Error('the installed canon did not return a flat config');
-  const selectors = [], ignored = [];
-  for (const block of config) {
-    if (!block || typeof block !== 'object') throw new Error('the installed canon returned an invalid config block');
-    for (const [field, target] of [['files', selectors], ['ignores', ignored]]) {
-      if (block[field] === undefined) continue;
-      if (!Array.isArray(block[field]) || block[field].some((glob) => typeof glob !== 'string' || glob.startsWith('!'))) throw new Error(`unsupported canon ${field} selectors`);
-      if (field === 'ignores' && Object.keys(block).some((key) => !['ignores', 'name'].includes(key))) throw new Error('unsupported non-global canon ignores');
-      target.push(...block[field].flatMap((glob) => braceVariants(glob).map(globExpression)));
-    }
-  }
-  if (!selectors.length) throw new Error('the installed canon has no source selectors');
-  const matches = (patterns, file) => patterns.some((pattern) => pattern.test(file));
+  const scope = canonScope(config);
   const files = [];
   const visit = (folder) => {
     for (const child of fs.readdirSync(path.join(cwd, folder), { withFileTypes: true })) {
       const file = posix(path.join(folder, child.name));
       // Ask the canon's global ignore patterns before entering output or installed-package trees.
-      if (matches(ignored, file) || matches(ignored, `${file}/__starci_scope_probe__`)) continue;
+      if (scope.ignored(file) || scope.ignored(`${file}/__starci_scope_probe__`)) continue;
       if (child.isSymbolicLink()) throw new Error(`cannot enumerate symlink ${file}`);
       if (child.isDirectory()) visit(file);
-      else if (child.isFile() && matches(selectors, file)) files.push(file);
+      else if (child.isFile() && scope.source(file)) files.push(file);
     }
   };
-  visit(scope ?? '');
+  visit(folderScope ?? '');
   return files.sort(byCodeUnit);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.7.18",
+  "version": "4.7.19",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/release/gate.mjs

@@ -16,7 +16,9 @@ import { sonarQualityGate } from './sonar-quality-gate.mjs';
 export const RELEASE_CODE = 'RELEASE_CONFIG_INVALID';
 const SONAR_UNREACHABLE = 'SONAR_UNREACHABLE';
 
-const FIELDS = new Set(['gates', 'tagPrefix', 'defaultBranch', 'tagMatchesVersion']);
+const FIELDS = new Set(['gates', 'tagPrefix', 'defaultBranch', 'tagMatchesVersion', 'requireCi']);
+/** The note a release that does not wait for CI carries in its L4 record and its push output (owner ruling release-require-ci-per-project). */
+export const CI_NOT_REQUIRED = 'CI not required by release.requireCi=false (owner ruling release-require-ci-per-project): the local release gate, this L4 record and the annotated tag, is the release proof';
 const GATE_FIELDS = new Set(['name', 'command', 'summary', 'env']);
 const GATE_NAME = /^[a-z][a-z0-9-]*$/u;
 const TOKEN = /^[A-Za-z0-9_@%+=:,./\\-]+$/u;
@@ -117,14 +119,17 @@ export function normalizeRelease(block, scripts = {}, services = {}, options = {
   const tagPrefix = raw.tagPrefix ?? 'v';
   const defaultBranch = raw.defaultBranch ?? 'main';
   const tagMatchesVersion = raw.tagMatchesVersion ?? false;
+  // The candidate CI of `release push` is an app's choice and off by default (owner ruling release-require-ci-per-project); the local gate never is.
+  const requireCi = raw.requireCi ?? false;
   if (typeof tagPrefix !== 'string' || !PREFIX.test(tagPrefix)) problems.push(`release.tagPrefix: must match ${PREFIX}`);
   if (!refName(defaultBranch)) problems.push(`release.defaultBranch: must match ${REF_NAME}`);
   if (typeof tagMatchesVersion !== 'boolean') problems.push('release.tagMatchesVersion: must be true or false');
+  if (typeof requireCi !== 'boolean') problems.push('release.requireCi: must be true or false');
   const quality = releaseServices(services, options);
   const audit = auditGate(quality.audit);
   const gates = raw.gates === undefined ? defaultGates(scripts, audit) : gatesOf(raw.gates, problems);
   if (raw.gates !== undefined && audit && !gates.some((gate) => gate.name === 'audit')) gates.push(audit);
-  return problems.length === 0 ? { config: { gates, tagPrefix, defaultBranch, tagMatchesVersion, services: quality } } : { problems };
+  return problems.length === 0 ? { config: { gates, tagPrefix, defaultBranch, tagMatchesVersion, requireCi, services: quality } } : { problems };
 }
 
 /* ---- git through the seam */
@@ -345,10 +350,11 @@ function assertUnmoved(ctx, head) {
   if (dirty.length > 0) throw failure('RELEASE_TREE_DIRTY', `the gates left ${dirty.length} changed or untracked path(s) (first: ${dirty[0].slice(0, 100)}): generated files differ from HEAD. Commit or ignore them properly, then rerun. No record.`);
 }
 
-function writeRecord(ctx, { head, tag, results, recordPath }) {
+function writeRecord(ctx, { head, tag, results, recordPath, requireCi }) {
   const record = {
     schema: 'starci-app-l4-record/1', head, tag, createdAt: new Date(ctx.now()).toISOString(), producedBy: 'starci app release gate',
     note: 'Required gates passed on a clean HEAD; optional provider skips are explicit and every entry links its log and sha256.',
+    ci: requireCi === true ? { required: true, note: 'starci app release push waits for the candidate CI of this sha (release.requireCi=true)' } : { required: false, note: CI_NOT_REQUIRED },
     gates: results,
   };
   fs.mkdirSync(path.dirname(recordPath), { recursive: true });
@@ -394,7 +400,7 @@ export async function releaseGate(ctx, config, options = {}) {
   const failed = results.filter((result) => !result.pass && !result.skipped);
   if (failed.length > 0) return { ok: false, lines: [...plan, ...report, `gate(s) red: ${failed.map((item) => item.name).join(', ')}. No L4 record, no tag.`], data: { ...base, executed: true, results } };
   assertUnmoved(ctx, facts.head);
-  writeRecord(ctx, { head: facts.head, tag: facts.chosen.tag, results, recordPath });
+  writeRecord(ctx, { head: facts.head, tag: facts.chosen.tag, results, recordPath, requireCi: config.requireCi });
   const created = facts.chosen.state !== 'on-head';
   if (created) git(ctx, ['tag', '-a', facts.chosen.tag, '-m', `release ${facts.chosen.tag}: required gates passed on ${facts.head.slice(0, 12)} (L4 record ${path.basename(recordPath)})`, facts.head]);
   const tagged = created ? `annotated tag ${facts.chosen.tag} created on ${facts.head.slice(0, 10)}` : `annotated tag ${facts.chosen.tag} already on ${facts.head.slice(0, 10)}`;

package/release/index.mjs

@@ -53,7 +53,7 @@ function readPackage(root) {
   try { return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')); } catch { throw refusal('RELEASE_PACKAGE_UNREADABLE', 'package.json is not readable JSON'); }
 }
 
-/** The normalised `release:` block (tolerant of absence) with the package version: { root, version, gates, tagPrefix, defaultBranch, tagMatchesVersion }. */
+/** The normalised `release:` block (tolerant of absence) with the package version: { root, version, gates, tagPrefix, defaultBranch, tagMatchesVersion, requireCi }. */
 function loadReleaseConfig(root) {
   const pkg = readPackage(root);
   if (typeof pkg.version !== 'string' || !VERSION.test(pkg.version)) throw refusal(RELEASE_CODE, 'package.json needs a version like 1.2.3 (the release tag derives from it)');

package/release/push.mjs

@@ -3,11 +3,13 @@
 // head and tag. `git push --dry-run --atomic` always runs first (the hook's verdict is the proof) and any failure refuses the push.
 // With --execute the exact sha first goes to its candidate ref refs/heads/release/candidate-<version> and the push waits for the ci.yml run of that sha
 // (candidate-ci.mjs, OWNER RULING candidate-ci 2026-10-18): only a green candidate (or the owner's sha-bound override record) moves the branch and the tag.
+// That wait runs only for an app that sets release.requireCi: true; the default false (owner ruling release-require-ci-per-project) pushes after the
+// local gate and the dry run alone and says so. The tag, the L4 record and the dry run are never skipped.
 import fs from 'node:fs';
 import path from 'node:path';
 import { firstLine } from '../stack/context.mjs';
 import { failure, refusal } from '../stack/errors.mjs';
-import { annotatedOnHead, git, refName, releaseDir } from './gate.mjs';
+import { CI_NOT_REQUIRED, annotatedOnHead, git, refName, releaseDir } from './gate.mjs';
 import { candidateRef, candidateStep } from './candidate-ci.mjs';
 
 const VERDICT = /RIGHTS_PUSH_NOT_RELEASE|pre-push|failed to push|Everything up|->/u;
@@ -98,8 +100,10 @@ export async function releasePush(ctx, config, options = {}) {
   const red = [];
   const refs = [...branchRefs(ctx, { head, remote, branch }, red).refs, ...tagRefs(ctx, { remote, tag: gate.tag }, red)];
   data.refs = refs;
-  const candidate = refs.length > 0 ? candidateRef(gate.tag, config.tagPrefix) : null;
+  const requireCi = config.requireCi === true;
+  const candidate = refs.length > 0 && requireCi ? candidateRef(gate.tag, config.tagPrefix) : null;
   if (candidate) out.push(`plan           git push ${remote} +${head.slice(0, 10)}:${candidate}, wait for its ci.yml run to be green, then git push --atomic ${remote} ${refs.join(' ')}`);
+  else if (refs.length > 0) out.push(`plan           git push --atomic ${remote} ${refs.join(' ')}`, `ci             ${CI_NOT_REQUIRED}`);
   else out.push(`plan           git push --atomic ${remote} (nothing)`);
   if (refs.length === 0 && red.length === 0) return { ok: true, lines: [...out, `already pushed: ${remote}/${branch} holds HEAD and ${gate.tag} is on ${remote}. Nothing to do.`], data };
   if (refs.length > 0) {
@@ -109,10 +113,12 @@ export async function releasePush(ctx, config, options = {}) {
   }
   if (red.length > 0) return refuse(out, red, data, options.execute === true ? 'nothing pushed.' : 'dry run: nothing pushed.');
   if (options.execute !== true) return { ok: true, lines: [...out, 'dry run: nothing pushed. ready; re-run with --execute.'], data };
-  const judged = await candidateStep(ctx, { head, tag: gate.tag, prefix: config.tagPrefix, remote, wait: options.candidateWait });
-  data.candidate = judged.data;
-  out.push(...judged.lines);
-  if (!judged.ok) return { ok: false, lines: [...out, `nothing pushed to ${branch} or ${gate.tag}.`], data };
+  if (requireCi) {
+    const judged = await candidateStep(ctx, { head, tag: gate.tag, prefix: config.tagPrefix, remote, wait: options.candidateWait });
+    data.candidate = judged.data;
+    out.push(...judged.lines);
+    if (!judged.ok) return { ok: false, lines: [...out, `nothing pushed to ${branch} or ${gate.tag}.`], data };
+  } else data.candidate = { required: false, note: CI_NOT_REQUIRED };
   const run = git(ctx, ['push', '--atomic', remote, ...refs], { allowFail: true });
   if (run.code !== 0) return { ok: false, lines: [...out, `push failed: ${firstLine(run.stderr)}`], data };
   return { ok: true, lines: [...out, `pushed to ${remote}: ${refs.join(' ')}`], data: { ...data, pushed: true } };

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.26
+    version: 3.4.27
     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.25
+    version: 8.4.26
     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.18
+    version: 1.7.19
     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.18
+    version: 4.7.19
     group: starci
     install: registry
     side: both

package/runtime/packages/cli/src/catalog.generated.mjs

@@ -1,7 +1,7 @@
 // GENERATED by scripts/cli/gen-catalog.mjs — do not edit
 export const CATALOG = {
   "schema": "starci/cli-catalog@1",
-  "hash": "2ad45b29a66fee7ac961e8546613e0455d23cc47e28a5070bd15b86154755dd8",
+  "hash": "fb2a551d3cb254cc42fa5c95dc1a32af973df14313385f03703bc209b2badb8a",
   "global": [
     {
       "name": "json",
@@ -1242,7 +1242,9 @@ export const CATALOG = {
             "OK passes; ERROR is red as RELEASE_SONAR_GATE_FAILED naming each failed condition, as is a FAILED or CANCELED task",
             "a task still running after 600 s is RELEASE_SONAR_GATE_TIMEOUT; no report-task, an HTTP error or no gate is RELEASE_SONAR_GATE_UNREADABLE",
             "OWNER RULING candidate-ci (2026-10-18): the gate no longer reads the default-branch CI; the verdict is the candidate run of the sha",
-            "push --execute sends HEAD to refs/heads/release/candidate-<version> first and waits for its ci.yml run (it triggers on release/candidate-*)",
+            "release.requireCi (default false, owner ruling release-require-ci-per-project) decides whether push waits for CI; the local gate is never skipped",
+            "requireCi false: push needs the tag and the green L4 record, runs the dry run, pushes atomically and states CI was not required",
+            "requireCi true: push --execute sends HEAD to refs/heads/release/candidate-<version> first and waits for its ci.yml run",
             "green moves the branch and the tag in one atomic push; red refuses RELEASE_CANDIDATE_CI_RED naming the failing jobs",
             "no run, or no end in time, refuses RELEASE_CANDIDATE_CI_TIMEOUT; unreadable GitHub refuses RELEASE_CI_UNKNOWN; nothing reaches the branch",
             "only the owner's starci release ci-override --sha <sha> --reason <text> record lets a red candidate through; there is no --no-ci-check flag",

package/scaffold/app.mjs

@@ -216,7 +216,7 @@ const LITE_FE_APP_DEPENDENCIES = Object.freeze({
  * ./routing, client-safe: the default locale a client boundary reads).
  */
 const FE_PACKAGES = Object.freeze({
-  ui: { exports: ['.'], dependencies: { '@heroui/react': null, '@starci/grammar': null, '@starci/heroicons': null, '@xyflow/react': null, 'next-intl': null, react: null } },
+  ui: { exports: ['.'], dependencies: { '@heroui/react': null, '@starci/grammar': null, '@starci/heroicons': null, '@xyflow/react': null, 'next-intl': null, react: null, 'react-dom': null } },
   i18n: { exports: ['.', './proxy', './routing'], dependencies: { next: null, 'next-intl': null, 'server-only': null } },
 });
 

package/templates/be/skeleton/src/modules/platform/database/migrate-connections.client.spec.ts

@@ -25,7 +25,7 @@ describe("migrateConnections", () => {
     it("runs the pending migrations of each connection in order and answers their names by connection", async () => {
         const client = await setup()
         const primary = mock<ConnectionSource>()
-        primary.runMigrations.mockResolvedValue([{ id: 1, timestamp: 1, name: "Init1" }])
+        primary.runMigrations.mockResolvedValue([{ name: "Init1" }])
         const archive = mock<ConnectionSource>()
         archive.runMigrations.mockResolvedValue([])
         const sources = new Map([