@starci/hfs 4.5.0 → 4.5.1

package/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 4.5.1 - 2026-10-18
+- Fixed: managed CI base refs, public build values, caching and timeouts; optional quality service handling, README formatting and Supabase migration-history parsing.
+
 ## 4.5.0 - 2026-10-17
 - Added: consumer-class CI declarations, `app ci` custody verbs and R296-R298; manifest-driven quality files and split cached CI with immutable action pins.
 - Added: release audit/local Sonar and main-CI protection; encrypted outside-repository DB dump and armed linked reset with backup/auth/storage validation.

package/package.json

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

package/release/gate.mjs

@@ -1,4 +1,4 @@
-// gate.mjs - `starci app release gate`: the honest release gate. It runs the app's own gates on a clean HEAD and ONLY when every one is green it
+// gate.mjs - `starci app release gate`: the honest release gate. It runs the app's own gates on a clean HEAD and when all required gates pass it
 // writes the L4 record <git-common-dir>/starci-release/<HEAD sha>.l4.json (head, tag, per-gate log path and sha256) and creates the annotated tag.
 // The canon pre-push hook lets main and v* tags through only for a HEAD with that tag and that record. Nothing is pushed here (see push.mjs).
 // The gate list comes from the optional `release:` block of .starcistacks/application-stacks.yaml, else from the app's managed package scripts.
@@ -13,6 +13,7 @@ import { failure, refusal } from '../stack/errors.mjs';
 import { latestDefaultBranchCi, requireGreenCi } from './ci-red.mjs';
 
 export const RELEASE_CODE = 'RELEASE_CONFIG_INVALID';
+const SONAR_UNREACHABLE = 'SONAR_UNREACHABLE';
 
 const FIELDS = new Set(['gates', 'tagPrefix', 'defaultBranch', 'tagMatchesVersion']);
 const GATE_FIELDS = new Set(['name', 'command', 'summary', 'env']);
@@ -63,14 +64,15 @@ function auditGate(audit) {
 
 /** A requested local Sonar scan uses only the declared host and token variable; the token never enters argv. */
 function sonarGate(services, env) {
-  const sonar = services?.sonar;
+  const configured = services?.sonar;
+  const sonar = configured?.provider === 'sonarcloud' ? { ...configured, host: 'https://sonarcloud.io' } : configured;
   const tokenName = sonar?.token;
   if (!sonar?.host || !ENV_KEY.test(tokenName) || !env[tokenName]) throw refusal('RELEASE_SONAR_UNAVAILABLE', 'declare an enabled services.sonar host and set its ci.token environment variable');
   const command = ['npx', '--yes', '@sonar/scan@4.3.0', `-Dsonar.host.url=${sonar.host}`];
   const organization = sonar.organization ?? (sonar.organizationVar ? env[sonar.organizationVar] : null);
   if (organization) command.push(`-Dsonar.organization=${organization}`);
   if (!command.every((word) => TOKEN.test(word))) throw refusal('RELEASE_SONAR_UNAVAILABLE', 'Sonar host and organization must be plain command arguments');
-  return { name: 'sonar', command, summary: null, env: { SONAR_TOKEN: env[tokenName] } };
+  return { name: 'sonar', command, summary: null, env: { SONAR_TOKEN: env[tokenName] }, provider: sonar };
 }
 
 function gateProblems(entry, at, seen) {
@@ -209,6 +211,32 @@ export function launch(argv, platform) {
   return [argv[0], argv.slice(1)];
 }
 
+/** Sonar availability is public and bounded; HTTP uses the existing injected fetch seam. */
+async function sonarAvailability(ctx, gate) {
+  const sonar = gate.provider;
+  if (!sonar) return null;
+  let up = false;
+  try {
+    const response = await ctx.fetch(sonar.host.replace(/\/$/u, '') + '/api/system/status', { signal: AbortSignal.timeout(10000) });
+    up = response.ok && (await response.json()).status === 'UP';
+  } catch { up = false; }
+  if (up) return null;
+  const detail = sonar.optional
+    ? `notice: sonar skipped: ${sonar.host} not reachable (services.sonar.optional)`
+    : `${SONAR_UNREACHABLE}: ${sonar.host} did not report UP within ten seconds`;
+  return { skipped: sonar.optional === true, pass: false, detail };
+}
+
+/** Unreachable optional providers remain explicit skipped rows, with a real log and no scan invocation. */
+async function runAvailableGate(ctx, gate, options) {
+  const availability = await sonarAvailability(ctx, gate);
+  if (!availability) return runGate(ctx, gate, options);
+  const log = path.join(options.dir, `${gate.name}.log`);
+  fs.writeFileSync(log, availability.detail + '\n');
+  return { name: gate.name, command: gate.command.join(' '), ...availability, seconds: 0,
+    summary: null, log: path.resolve(log), logSha256: sha256(log), env: Object.keys(gate.env) };
+}
+
 function runGate(ctx, gate, { dir, platform }) {
   const log = path.join(dir, `${gate.name}.log`);
   const started = ctx.now();
@@ -270,7 +298,7 @@ function inspect(ctx, config, options) {
 }
 
 function planLines(config, facts, dir, recordPath) {
-  const out = [`L4 record      ${recordPath}`, `logs           ${dir}`, '', 'gates (all must pass, in this order):'];
+  const out = [`L4 record      ${recordPath}`, `logs           ${dir}`, '', 'gates (required gates must pass, optional provider outages are skipped, in this order):'];
   for (const gate of config.gates) {
     const summary = gate.summary ? ` (summary: ${gate.summary})` : '';
     out.push(`  ${gate.name.padEnd(17)} ${gate.command.join(' ')}${summary}`);
@@ -289,28 +317,31 @@ function assertUnmoved(ctx, head) {
 function writeRecord(ctx, { head, tag, results, recordPath }) {
   const record = {
     schema: 'starci-app-l4-record/1', head, tag, createdAt: new Date(ctx.now()).toISOString(), producedBy: 'starci app release gate',
-    note: 'The full gates ran on a clean HEAD; every entry links the real log and its sha256.',
+    note: 'Required gates passed on a clean HEAD; optional provider skips are explicit and every entry links its log and sha256.',
     gates: results,
   };
   fs.mkdirSync(path.dirname(recordPath), { recursive: true });
   fs.writeFileSync(recordPath, `${JSON.stringify(record, null, 2)}\n`);
 }
 
-function runAll(ctx, config, { dir, platform }) {
-  fs.mkdirSync(dir, { recursive: true });
-  const results = [];
-  for (const gate of config.gates) {
-    const result = runGate(ctx, gate, { dir, platform });
-    results.push(result);
-    if (!result.pass) break;
-  }
-  return results;
+/** Gates run sequentially because each failure prevents subsequent commands and record creation. */
+async function runAll(ctx, config, options) {
+  fs.mkdirSync(options.dir, { recursive: true });
+  return config.gates.reduce(async (pending, gate) => {
+    const results = await pending;
+    if (results.some((result) => !result.pass && !result.skipped)) return results;
+    return [...results, await runAvailableGate(ctx, gate, options)];
+  }, Promise.resolve([]));
 }
 
-const summaryOf = (result) => `${result.pass ? 'PASS' : 'FAIL'} ${result.name} (${result.detail}, ${result.seconds}s) log ${result.log}`;
+function summaryOf(result) {
+  let status = result.pass ? 'PASS' : 'FAIL';
+  if (result.skipped) status = 'SKIPPED';
+  return `${status} ${result.name} (${result.detail}, ${result.seconds}s) log ${result.log}`;
+}
 
 /**
- * `starci app release gate`: dry run prints the preconditions, the gate list, the head and the tag; --execute runs every gate and, only if all are green,
+ * `starci app release gate`: dry run prints the preconditions, the gate list, the head and the tag; --execute runs every gate and, only if required gates pass,
  * writes the L4 record and creates the annotated tag. options: { execute, sonar, source, tagPrefix, platform }.
  */
 export async function releaseGate(ctx, config, options = {}) {
@@ -325,14 +356,14 @@ export async function releaseGate(ctx, config, options = {}) {
   const base = { head: facts.head, tag: facts.chosen.tag, record: recordPath, gates: config.gates.map((gate) => gate.name), ci: { state: ci.state, notices: ciLines } };
   if (facts.red.length > 0) return { ok: false, lines: [...plan, ...facts.red.map((item) => `RED: ${item}`), 'nothing was run.'], data: { ...base, red: facts.red, executed: false } };
   if (options.execute !== true) return { ok: true, lines: [...plan, '', 'dry run: no gate was run, nothing written. preconditions OK.'], data: { ...base, red: [], executed: false } };
-  const results = runAll(ctx, config, { dir, platform: options.platform ?? process.platform });
+  const results = await runAll(ctx, config, { dir, platform: options.platform ?? process.platform });
   const report = results.map(summaryOf);
-  const failed = results.filter((result) => !result.pass);
+  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 });
   const created = facts.chosen.state !== 'on-head';
-  if (created) git(ctx, ['tag', '-a', facts.chosen.tag, '-m', `release ${facts.chosen.tag}: gates green on ${facts.head.slice(0, 12)} (L4 record ${path.basename(recordPath)})`, facts.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)}`;
   return { ok: true, lines: [...plan, ...report, `L4 record written: ${recordPath}`, tagged], data: { ...base, executed: true, results, tagCreated: created } };
 }

package/release/push.mjs

@@ -14,7 +14,7 @@ function readRecord(file) {
 }
 
 const greenRecord = (record, head, tag) => record?.head === head && record?.tag === tag
-  && Array.isArray(record.gates) && record.gates.length > 0 && record.gates.every((gate) => gate?.pass === true);
+  && Array.isArray(record.gates) && record.gates.length > 0 && record.gates.every((gate) => gate?.pass === true || (gate?.name === 'sonar' && gate?.skipped === true));
 
 /** The release gate as the hook reads it: the annotated tag on HEAD whose L4 record names head and tag. Returns { tag } or { reason }. */
 function gateState(ctx, head, prefix) {

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.2
+    version: 3.4.3
     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.2
+    version: 8.4.3
     group: starci
     install: registry
     side: fe
@@ -62,7 +62,7 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.3.0
+    version: 2.3.1
     group: starci
     install: registry
     side: be
@@ -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.5.0
+    version: 1.5.1
     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.5.0
+    version: 4.5.1
     group: starci
     install: registry
     side: both

package/runtime/modules/schemas/application-stacks.schema.yaml

@@ -149,6 +149,9 @@ $defs:
       target: {type: number, minimum: 0, maximum: 100}
       components: {enum: [auto]}
       required: {type: boolean}
+      optional:
+        description: Skip an unreachable quality provider with a notice; SonarQube defaults true, SonarCloud and Codecov false.
+        type: boolean
       ecosystems: {type: array, items: {enum: [npm, docker, github-actions]}}
       schedule:
         type: object

package/runtime/scripts/hfs/ci-declaration.mjs

@@ -33,13 +33,13 @@ export function qualityServices(doc, { example = false } = {}) {
   const dependabot = services.dependabot ?? {}, audit = services.audit ?? {};
   return {
     sonar: !sonar || sonar.mode === 'disabled' ? null : {
-      provider: sonar.provider, mode: sonar.mode, host: sonar.host?.public || sonar.host?.local || null,
+      provider: sonar.provider, mode: sonar.mode, optional: sonar.optional ?? sonar.provider === 'sonarqube', host: sonar.host?.public || sonar.host?.local || null,
       organization: sonar.organization ?? null,
       organizationVar: sonar.ci?.organizationVar ?? (sonar.provider === 'sonarcloud' && (example || list(sonar.runtimeSecrets).length > 0) && !list(sonar.credentials).length ? 'SONAR_ORGANIZATION' : null), projectKey: sonar.projects?.[0]?.key ?? null,
       qualityGate: sonar.qualityGate ?? (example ? 'starci-quality-lite' : 'starci-quality'), wiring: sonar.ci?.wiring ?? 'required',
       token: sonar.ci?.token || nameOf(sonar.ci?.secrets?.[0]) || 'SONAR_TOKEN', hostVar: sonar.ci?.hostVar || 'SONAR_HOST_URL',
     },
-    codecov: { enabled: codecov.mode !== 'disabled', auth: codecov.auth ?? 'oidc', token: codecov.ci?.token ?? null,
+    codecov: { optional: codecov.optional ?? false, enabled: codecov.mode !== 'disabled', auth: codecov.auth ?? 'oidc', token: codecov.ci?.token ?? null,
       flag: codecov.flag ?? null, target: codecov.target ?? 100, components: codecov.components ?? 'auto', required: codecov.required ?? true, wiring: codecov.ci?.wiring ?? 'required' },
     dependabot: { ecosystems: [...(dependabot.ecosystems ?? ['npm', 'github-actions', 'docker'])],
       schedule: { interval: 'weekly', ...dependabot.schedule }, groups: { minorPatch: 'grouped', major: 'per-package', ...dependabot.groups },

package/sync/ci-commands.mjs

@@ -1,4 +1,7 @@
 import fs from 'node:fs';
+import { parseYaml } from '../runtime/engine/yaml.mjs';
+import { refusal } from '../stack/errors.mjs';
+import { byCodeUnit } from '../report/order.mjs';
 
 // One command vocabulary for managed CI rendering and the runtime coverage gate.
 const exampleCommand = (source, command) => source?.runtimeExample
@@ -9,56 +12,116 @@ const UPLOAD_ARTIFACT = 'actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f
 const DOWNLOAD_ARTIFACT = 'actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0';
 const SONAR_CONDITION = "${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') && env.SONAR_TOKEN != '' }}";
 
+/** Optional uploads require reachable upload and authentication endpoints without exposing identity tokens. */
+function codecovProbe(codecov, condition) {
+  if (!codecov.optional) return [];
+  return [
+    '      - name: Codecov availability',
+    '        id: codecov-availability',
+    `        if: ${condition}`,
+    '        env:',
+    `          CODECOV_AUTH: ${codecov.auth}`,
+    '        run: |',
+    "          node --input-type=module <<'NODE'",
+    "          import fs from 'node:fs';",
+    '          let available = false;',
+    '          try {',
+    "            const upload = await fetch('https://ingest.codecov.io/upload/v4', { signal: AbortSignal.timeout(10000) });",
+    '            available = upload.status < 500;',
+    "            if (available && process.env.CODECOV_AUTH === 'oidc') {",
+    "              const url = new URL(process.env.ACTIONS_ID_TOKEN_REQUEST_URL);",
+    "              url.searchParams.set('audience', 'https://codecov.io');",
+    "              const identity = await fetch(url, { headers: { Authorization: 'Bearer ' + process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN }, signal: AbortSignal.timeout(10000) });",
+    '              available = identity.ok && Boolean((await identity.json()).value);',
+    '            }',
+    '          } catch { available = false; }',
+    "          fs.appendFileSync(process.env.GITHUB_OUTPUT, 'up=' + available + '\\n');",
+    "          if (!available) console.log('::notice::codecov upload skipped: upload endpoint or OIDC token unavailable (services.codecov.optional)');",
+    '          NODE',
+  ];
+}
+
+/** Optional Sonar only runs analysis when the provider reports UP within ten seconds. */
+function sonarProbe(sonar) {
+  if (!sonar.optional) return [];
+  return [
+    '      - name: Sonar availability',
+    '        id: sonar-availability',
+    `        if: ${SONAR_CONDITION}`,
+    '        run: |',
+    `          if curl -fsS --max-time 10 "$SONAR_HOST_URL/api/system/status" | node -e "let s='';process.stdin.on('data',c=>s+=c);process.stdin.on('end',()=>{try{process.exit(JSON.parse(s).status==='UP'?0:1)}catch{process.exit(1)}})"; then`,
+    '            echo "up=true" >> "$GITHUB_OUTPUT"',
+    '          else',
+    '            echo "up=false" >> "$GITHUB_OUTPUT"',
+    '            echo "::notice::sonar skipped: $SONAR_HOST_URL not reachable (services.sonar.optional)"',
+    '          fi',
+  ];
+}
+
 /** Codecov reports missing coverage without failing twice; uploads retain the release-tag condition and required authentication. */
 function codecovSteps(lcovReport, codecov) {
   if (codecov.enabled === false || codecov.wiring === 'not-used') return [
     '      - name: coverage upload',
     '        run: echo "codecov disabled in .starcistacks/application-stacks.yaml"',
   ].join('\n');
+  const condition = `\${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') && hashFiles('${lcovReport}') != '' }}`;
+  const uploadCondition = codecov.optional ? condition.replace(' }}', " && steps.codecov-availability.outputs.up == 'true' }}") : condition;
   return [
     '      - name: coverage upload skipped',
     `        if: \${{ !cancelled() && hashFiles('${lcovReport}') == '' }}`,
     '        run: |',
     `          echo "::notice::codecov upload skipped: no coverage file at ${lcovReport} (the test step failed or produced none)"`,
     '          exit 0',
+    ...codecovProbe(codecov, condition),
     '      - name: coverage upload',
+    ...(codecov.optional ? ['        id: codecov-upload', '        continue-on-error: true'] : []),
     '        uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5.5.5',
-    `        if: \${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') && hashFiles('${lcovReport}') != '' }}`,
+    `        if: ${uploadCondition}`,
     '        with:',
     codecov.auth === 'token' ? `          token: \${{ secrets.${codecov.token} }}` : '          use_oidc: true',
     `          files: ${lcovReport}`,
     '          disable_search: true',
-    '          fail_ci_if_error: true',
+    `          fail_ci_if_error: ${!codecov.optional}`,
+    ...(codecov.optional ? [
+      '      - name: Codecov upload unavailable',
+      "        if: ${{ !cancelled() && steps.codecov-upload.outcome == 'failure' }}",
+      '        run: |',
+      '          echo "::notice::codecov upload skipped: upload unavailable (services.codecov.optional)"',
+    ] : []),
   ].join('\n');
 }
 
 /** Sonar consumes the test coverage and fast lint artifacts only on release tags with a configured token. */
 function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor) {
   if (!sonar) return '';
+  const condition = sonar.optional ? SONAR_CONDITION.replace(' }}', " && steps.sonar-availability.outputs.up == 'true' }}") : SONAR_CONDITION;
+  const host = sonar.provider === 'sonarcloud' ? 'https://sonarcloud.io' : `\${{ vars.${sonar.hostVar} }}`;
   const header = [
     '  sonar:',
     '    needs: [fast, test]',
+    '    timeout-minutes: 20',
     '    runs-on: ubuntu-latest',
     '    env:',
     `      SONAR_TOKEN: \${{ secrets.${sonar.token} }}`,
-    `      SONAR_HOST_URL: \${{ vars.${sonar.hostVar} }}`,
+    `      SONAR_HOST_URL: ${host}`,
     '    steps:',
   ].join('\n');
   const steps = [
+    ...sonarProbe(sonar),
     `      - uses: ${DOWNLOAD_ARTIFACT}`,
-    `        if: ${SONAR_CONDITION}`,
+    `        if: ${condition}`,
     '        with:',
     `          name: ${lcovArtifact}`,
     `          path: ${lcovReport.split('/').slice(0, -1).join('/') || '.'}`,
     `      - uses: ${DOWNLOAD_ARTIFACT}`,
-    `        if: ${SONAR_CONDITION}`,
+    `        if: ${condition}`,
     '        with:',
     '          name: sonar-lint',
     '          path: reports',
     '      - uses: SonarSource/sonarqube-scan-action@c7ee0f9df90b7aa20e8dcf9695dcfe2e7da5b4f2 # v7.2.1',
-    `        if: ${SONAR_CONDITION}`,
+    `        if: ${condition}`,
     '      - uses: SonarSource/sonarqube-quality-gate-action@7a5fffe8e523c40e0c740b6bc2712ab503e52efa # v1.2.1',
-    `        if: ${SONAR_CONDITION}`,
+    `        if: ${condition}`,
     '        timeout-minutes: 10',
   ].join('\n');
   // Variable strings are inserted after render() expands partials, so resolve Sonar's shared install partial before insertion.
@@ -71,6 +134,44 @@ function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor) {
     .trimEnd();
 }
 
+/** The app source reader is be-relative; the authored manifest lives one directory above that side. */
+function buildDeclaration(source) {
+  if (!source?.read) return {};
+  try {
+    return parseYaml(source.read('../.starcistacks/application-stacks.yaml')) ?? {};
+  } catch (error) {
+    if (error.code === 'ENOENT') return {};
+    throw error;
+  }
+}
+
+/** Static CI values are strings with valid environment names; expressions cannot turn public config into runtime secret reads. */
+function mergeBuildValues(values, entries) {
+  for (const [key, value] of Object.entries(entries ?? {})) {
+    if (!/^[A-Z][A-Z0-9_]*$/u.test(key) || typeof value !== 'string' || value.includes('${{')) {
+      throw refusal('STACK_BUILD_ARG_INVALID', 'CI build values must map environment names to literal strings');
+    }
+    if (values.has(key) && values.get(key) !== value) {
+      throw refusal('STACK_BUILD_ARG_INVALID', 'CI build values disagree for ' + key);
+    }
+    values.set(key, value);
+  }
+}
+
+/** CI builds render only plain values from the images.yml environment plus the explicit build-fe gate; sealed members stay unopened. */
+function buildEnv(source) {
+  const declaration = buildDeclaration(source);
+  const environments = Object.keys(source?.stack?.imageEnvironments ?? {});
+  const environment = environments.length > 1 ? 'production' : environments[0];
+  const images = declaration.environments?.[environment]?.deploy?.images ?? {};
+  const values = new Map();
+  for (const image of Object.values(images)) mergeBuildValues(values, image?.buildArgs?.values);
+  const gates = declaration.release?.gates ?? [];
+  for (const gate of gates.filter(entry => entry.name === 'build-fe')) mergeBuildValues(values, gate.env);
+  if (!values.size) return '';
+  return ['        env:', ...[...values.keys()].sort(byCodeUnit).map(key => '          ' + key + ': ' + JSON.stringify(values.get(key)))].join('\n');
+}
+
 /** An omitted quality declaration preserves hosted Sonar, required OIDC Codecov, and the high production dependency audit. */
 export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info', quality = undefined, { nodeMajor = '22' } = {}) {
   const configuredSonar = quality === undefined ? { token: 'SONAR_TOKEN', hostVar: 'SONAR_HOST_URL' } : quality.sonar;
@@ -79,6 +180,7 @@ export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info',
   const audit = quality?.audit ?? { level: 'high', omitDev: true };
   const lcovArtifact = 'coverage-lcov';
   return {
+    ciBuildEnv: buildEnv(source),
     ciLint: exampleCommand(source, 'npm run lint'),
     ciLintSonar: exampleCommand(source, 'npm run lint -- --sonar reports/lint.sonar.json'),
     ciCoverageProof: exampleCommand(source, 'npx starci app check --coverage-from ' + lcovReport),

package/sync/index.mjs

@@ -379,7 +379,8 @@ export function renderTargets(hfs, presets, { sonarKey, readTemplate = readBundl
         return { path: where, scope, mode: 'scripts', content, hash: hashOf(content), scripts };
       }
       const markers = target.markdown ? { begin: '<!-- >>> starci app sync (managed block; do not edit) >>> -->', end: '<!-- <<< starci app sync <<< -->' } : { begin: BLOCK_BEGIN, end: BLOCK_END };
-      const managed = target.mode === 'block' ? `${markers.begin}\n${trailingNewline(body)}${markers.end}\n` : body;
+      const spacing = target.markdown ? '\n' : '';
+      const managed = target.mode === 'block' ? `${markers.begin}\n${spacing}${trailingNewline(body)}${spacing}${markers.end}\n` : body;
       return { path: where, scope, mode: target.mode, markdown: target.markdown, markers, content: managed, hash: hashOf(managed) };
     });
   });

package/templates/app/ci-workflows/github/workflows/ci.yml

@@ -16,10 +16,12 @@ concurrency:
 
 jobs:
   fast:
+    timeout-minutes: 20
     runs-on: ubuntu-latest
 {{sonarEnv}}
     steps:
 {{> app/ci-workflows/install-steps.yml}}
+{{> app/ci-workflows/lint-base.yml}}
       - name: production dependency audit
         run: {{auditCommand}}
 {{ciLintSteps}}
@@ -29,6 +31,7 @@ jobs:
         run: npm run typecheck
 
   test:
+    timeout-minutes: 45
     runs-on: ubuntu-latest
     # Codecov OIDC authentication requires a job-scoped identity token.
     permissions:
@@ -36,8 +39,9 @@ jobs:
       id-token: write
     steps:
 {{> app/ci-workflows/install-steps.yml}}
+{{> app/ci-workflows/jest-cache.yml}}
       - name: unit
-        run: npm test -- --ci
+        run: npm test -- --ci --forceExit --cacheDirectory .jest-cache
       - name: coverage proof
         run: {{ciCoverageProof}}
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
@@ -48,6 +52,7 @@ jobs:
 {{codecovSteps}}
 
   build:
+    timeout-minutes: 30
     runs-on: ubuntu-latest
     steps:
 {{> app/ci-workflows/install-steps.yml}}
@@ -55,5 +60,6 @@ jobs:
         run: npm run build:be
       - name: build fe
         run: npm run build:fe
+{{ciBuildEnv}}
 
 {{sonarJob}}

package/templates/app/ci-workflows/github/workflows/e2e.yml

@@ -10,6 +10,7 @@ permissions:
 
 jobs:
   e2e:
+    timeout-minutes: 45
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0

package/templates/app/ci-workflows/github/workflows/images.yml

@@ -17,6 +17,7 @@ concurrency:
 
 jobs:
   image:
+    timeout-minutes: 30
     runs-on: ubuntu-latest{{imageJobEnvironment}}
     env:
       STACK_ENVIRONMENT: {{imageEnvironment}}

package/templates/app/ci-workflows/install-steps.yml

@@ -1,4 +1,6 @@
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          fetch-depth: 0
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: {{nodeMajor}}

package/templates/app/ci-workflows/jest-cache.yml

@@ -0,0 +1,8 @@
+      - name: Jest cache
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: .jest-cache
+          key: ${{ runner.os }}-node{{nodeMajor}}-jest-${{ hashFiles('package-lock.json') }}-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-node{{nodeMajor}}-jest-${{ hashFiles('package-lock.json') }}-
+            ${{ runner.os }}-node{{nodeMajor}}-jest-

package/templates/app/ci-workflows/lint-base.yml

@@ -0,0 +1,16 @@
+      - name: lint baseline
+        shell: bash
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+          BEFORE: ${{ github.event.before }}
+        run: |
+          base="origin/$DEFAULT_BRANCH"
+          if [[ "$GITHUB_EVENT_NAME" == pull_request ]]; then
+            base="origin/$BASE_BRANCH"
+          elif [[ "$GITHUB_REF" == refs/tags/* ]]; then
+            base=$(git describe --tags --abbrev=0 "$GITHUB_REF^" 2>/dev/null) || base="origin/$DEFAULT_BRANCH"
+          elif [[ "$GITHUB_EVENT_NAME" == push && -n "$BEFORE" && ! "$BEFORE" =~ ^0+$ ]]; then
+            base="$BEFORE"
+          fi
+          echo "STARCI_BASE_REF=$base" >> "$GITHUB_ENV"

package/templates/app/ci-workflows-lite/github/workflows/ci.yml

@@ -16,10 +16,12 @@ concurrency:
 
 jobs:
   fast:
+    timeout-minutes: 20
     runs-on: ubuntu-latest
 {{sonarEnv}}
     steps:
 {{> app/ci-workflows/install-steps.yml}}
+{{> app/ci-workflows/lint-base.yml}}
       - name: production dependency audit
         run: {{auditCommand}}
 {{ciLintSteps}}
@@ -29,6 +31,7 @@ jobs:
         run: npm run typecheck
 
   test:
+    timeout-minutes: 45
     runs-on: ubuntu-latest
     # Codecov OIDC authentication requires a job-scoped identity token.
     permissions:
@@ -36,8 +39,9 @@ jobs:
       id-token: write
     steps:
 {{> app/ci-workflows/install-steps.yml}}
+{{> app/ci-workflows/jest-cache.yml}}
       - name: unit
-        run: npm test -- --ci
+        run: npm test -- --ci --forceExit --cacheDirectory .jest-cache
       - name: coverage proof
         run: {{ciCoverageProof}}
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
@@ -48,6 +52,7 @@ jobs:
 {{codecovSteps}}
 
   build:
+    timeout-minutes: 30
     runs-on: ubuntu-latest
     steps:
 {{> app/ci-workflows/install-steps.yml}}
@@ -55,12 +60,14 @@ jobs:
         run: npm run build:be
       - name: build fe
         run: npm run build:fe
+{{ciBuildEnv}}
       - name: database migration checks
         run: {{ciDatabaseLint}}
 
 {{sonarJob}}
 
   db-types:
+    timeout-minutes: 30
     runs-on: ubuntu-latest
     steps:
 {{> app/ci-workflows/install-steps.yml}}

package/templates/app/ci-workflows-lite/github/workflows/db-deploy.yml

@@ -22,6 +22,7 @@ concurrency:
 
 jobs:
   deploy:
+    timeout-minutes: 30
     runs-on: ubuntu-latest
     environment: ${{ inputs.environment }}
     env:

package/templates/app/ci-workflows-lite/github/workflows/images.yml

@@ -17,6 +17,7 @@ concurrency:
 
 jobs:
   image:
+    timeout-minutes: 30
     runs-on: ubuntu-latest{{imageJobEnvironment}}
     env:
       STACK_ENVIRONMENT: {{imageEnvironment}}

package/templates/app/gitignore

@@ -1,4 +1,6 @@
 {{> common/gitignore.base}}
+# Jest transforms reused by the CI test job
+.jest-cache/
 # be: the schema Nest writes when it boots GraphQL
 schema.gql
 # fe: Next build output and its generated type file

package/templates/app/gitignore-lite

@@ -1,4 +1,6 @@
 {{> common/gitignore.base}}
+# Jest transforms reused by the CI test job
+.jest-cache/
 # Supabase CLI state is local Docker metadata, never application source.
 supabase/.temp/
 supabase/.branches/

package/templates/app/skeleton/.starcistacks/application-stacks.yaml

@@ -148,6 +148,7 @@ ci:
 services:
   sonar:
     provider: sonarqube
+    optional: true
     mode: local
     qualityGate: {{sonarGate}}
     host: {local: http://127.0.0.1:9000, public: "https://sonar.{{project}}.example.invalid"}

package/templates/app/skeleton-lite/.starcistacks/application-stacks.yaml

@@ -193,6 +193,7 @@ ci:
 services:
   sonar:
     provider: sonarqube
+    optional: true
     mode: local
     qualityGate: {{sonarGate}}
     host: {local: http://127.0.0.1:9000, public: "https://sonar.{{project}}.example.invalid"}

package/templates/app/upgrade-full/.starcistacks/application-stacks.yaml

@@ -43,6 +43,7 @@ ci:
 services:
   sonar:
     provider: sonarqube
+    optional: true
     mode: disabled
     reason: Enable the repository's Sonar service when a host and project token are provisioned.
     qualityGate: starci-quality