@starci/hfs 4.5.1 → 4.7.0

package/sync/ci-commands.mjs

@@ -92,14 +92,14 @@ function codecovSteps(lcovReport, codecov) {
 }
 
 /** Sonar consumes the test coverage and fast lint artifacts only on release tags with a configured token. */
-function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor) {
+function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout) {
   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',
+    '    needs: [lint, coverage]',
+    `    timeout-minutes: ${timeout}`,
     '    runs-on: ubuntu-latest',
     '    env:',
     `      SONAR_TOKEN: \${{ secrets.${sonar.token} }}`,
@@ -116,8 +116,10 @@ function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor) {
     `      - uses: ${DOWNLOAD_ARTIFACT}`,
     `        if: ${condition}`,
     '        with:',
-    '          name: sonar-lint',
+    '          pattern: sonar-lint-*',
     '          path: reports',
+    '          merge-multiple: true',
+    ...sonarMergeSteps(condition),
     '      - uses: SonarSource/sonarqube-scan-action@c7ee0f9df90b7aa20e8dcf9695dcfe2e7da5b4f2 # v7.2.1',
     `        if: ${condition}`,
     '      - uses: SonarSource/sonarqube-quality-gate-action@7a5fffe8e523c40e0c740b6bc2712ab503e52efa # v1.2.1',
@@ -131,7 +133,7 @@ function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor) {
     .replaceAll('{{nodeMajor}}', nodeMajor)
     .replace('{{sonarJobHeader}}', () => header)
     .replace('{{sonarJobSteps}}', () => steps)
-    .trimEnd();
+    .trimEnd() + '\n';
 }
 
 /** The app source reader is be-relative; the authored manifest lives one directory above that side. */
@@ -158,29 +160,82 @@ function mergeBuildValues(values, entries) {
   }
 }
 
-/** CI builds render only plain values from the images.yml environment plus the explicit build-fe gate; sealed members stay unopened. */
-function buildEnv(source) {
+/** Image values own their keys; the build-fe gate supplies only missing keys, and sealed members stay unopened. */
+function imageBuildEnv(image, gates) {
+  const values = new Map();
+  mergeBuildValues(values, image?.buildArgs?.values);
+  const fallback = new Map();
+  for (const gate of gates.filter(entry => entry.name === 'build-fe')) mergeBuildValues(fallback, gate.env);
+  for (const [key, value] of fallback) if (!values.has(key)) values.set(key, value);
+  if (!values.size) return '';
+  return ['        env:', ...[...values.keys()].sort(byCodeUnit).map(key => '          ' + key + ': ' + JSON.stringify(values.get(key)))].join('\n');
+}
+
+/** Multiple deployed front ends build separately through the installed turbo (a run step has no node_modules/.bin on PATH), so each fe/apps/<app> and its dependencies see its own public values. */
+function frontendBuild(source, app) {
   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 images = Object.values(declaration.environments?.[environment]?.deploy?.images ?? {});
+  const frontend = images.filter(image => app?.sides.fe.apps.some(entry => entry.name === image.app));
   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');
+  const singleEnv = imageBuildEnv(frontend[0], gates);
+  if (frontend.length <= 1) return { env: singleEnv, steps: ['      - name: build fe', '        run: npm run build:fe', singleEnv].filter(Boolean).join('\n') };
+  const steps = frontend.map(image => [
+    '      - name: build fe ' + image.app,
+    '        run: npm run codegen --silent && npx --no-install turbo run build --filter=./fe/apps/' + image.app,
+    imageBuildEnv(image, gates),
+  ].filter(Boolean).join('\n')).join('\n');
+  return { env: singleEnv, steps };
+}
+
+/** The per-side lint reports (one artifact per lint matrix side) join into the one reports/lint.sonar.json the Sonar import reads, even when one side wrote none. */
+function sonarMergeSteps(condition) {
+  return [
+    '      - name: merge Sonar lint reports',
+    `        if: ${condition}`,
+    '        run: |',
+    "          node --input-type=module <<'NODE'",
+    "          import fs from 'node:fs';",
+    "          const files = ['reports/lint.be.sonar.json', 'reports/lint.fe.sonar.json'];",
+    "          const reports = files.filter(file => fs.existsSync(file)).map(file => JSON.parse(fs.readFileSync(file, 'utf8')));",
+    '          const rules = [...new Map(reports.flatMap(report => report.rules).map(rule => [rule.id, rule])).values()];',
+    '          const issues = reports.flatMap(report => report.issues);',
+    "          fs.mkdirSync('reports', { recursive: true });",
+    "          fs.writeFileSync('reports/lint.sonar.json', JSON.stringify({ rules, issues }, null, 2) + '\\n');",
+    '          NODE',
+  ];
+}
+
+const STANDARD = new URL('../runtime/knowledge/hfs/ci-standard.yaml', import.meta.url);
+/** The per-job settings of the managed CI: ci.jobs.<job>.timeoutMinutes and ci.jobs.test.shards of the manifest over the defaults of the CI standard. */
+function ciJobSettings(declaration) {
+  const defaults = parseYaml(fs.readFileSync(STANDARD, 'utf8')).defaults;
+  const jobs = declaration?.ci?.jobs ?? {};
+  const timeout = (job) => String(jobs[job]?.timeoutMinutes ?? defaults.timeoutMinutes[job]);
+  const shards = Number(jobs.test?.shards ?? defaults.shards);
+  return {
+    timeoutFast: timeout('fast'), timeoutLint: timeout('lint'), timeoutTest: timeout('test'), timeoutCoverage: timeout('coverage'),
+    timeoutBuild: timeout('build'), timeoutSonar: timeout('sonar'), timeoutDbTypes: timeout('db-types'),
+    testShards: `[${Array.from({ length: shards }, (_, index) => index + 1).join(', ')}]`, testShardTotal: String(shards),
+  };
 }
 
 /** 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' } = {}) {
+export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info', quality = undefined, { nodeMajor = '22', app } = {}) {
   const configuredSonar = quality === undefined ? { token: 'SONAR_TOKEN', hostVar: 'SONAR_HOST_URL' } : quality.sonar;
   const sonar = configuredSonar?.wiring === 'not-used' || configuredSonar?.mode === 'disabled' ? null : configuredSonar;
   const codecov = quality?.codecov ?? { enabled: true, auth: 'oidc' };
   const audit = quality?.audit ?? { level: 'high', omitDev: true };
   const lcovArtifact = 'coverage-lcov';
+  const build = frontendBuild(source, app);
+  const settings = ciJobSettings(buildDeclaration(source));
+  const side = '${{ matrix.side }}';
   return {
-    ciBuildEnv: buildEnv(source),
+    ...settings,
+    lcovShardsDir: lcovReport.split('/').slice(0, -1).concat('shards').join('/'),
+    ciBuildEnv: build.env,
+    ciBuildSteps: build.steps,
     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),
@@ -189,29 +244,28 @@ export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info',
     sonarTokenSecret: sonar?.token ?? 'SONAR_TOKEN',
     sonarHostVar: sonar?.hostVar ?? 'SONAR_HOST_URL',
     sonarEnv: sonar ? `    env:\n      SONAR_TOKEN: \${{ secrets.${sonar.token} }}` : '',
+    // One lint job per side (the lint matrix): with a Sonar token each side writes its own report, uploaded as sonar-lint-<side> and merged by the sonar job.
     ciLintSteps: [
-      ...['be', 'fe'].flatMap((side) => [
-        '      - name: lint ' + side,
-        ...(sonar ? ["        if: env.SONAR_TOKEN == ''"] : []),
-        `        run: ${exampleCommand(source, 'npm run lint -- --side ' + side)}`,
-        '        env:',
-        '          NODE_OPTIONS: --max-old-space-size=6144',
-      ]),
+      '      - name: lint',
+      ...(sonar ? ["        if: env.SONAR_TOKEN == ''"] : []),
+      `        run: ${exampleCommand(source, 'npm run lint -- --side ' + side)}`,
+      '        env:',
+      '          NODE_OPTIONS: --max-old-space-size=6144',
       ...(sonar ? [
         '      - name: lint with Sonar import',
         "        if: env.SONAR_TOKEN != ''",
-        `        run: ${exampleCommand(source, 'npm run lint -- --sonar reports/lint.sonar.json')}`,
+        `        run: ${exampleCommand(source, 'npm run lint -- --side ' + side + ' --sonar reports/lint.' + side + '.sonar.json')}`,
         '        env:',
         '          NODE_OPTIONS: --max-old-space-size=6144',
         `      - uses: ${UPLOAD_ARTIFACT}`,
-        "        if: always() && env.SONAR_TOKEN != '' && hashFiles('reports/lint.sonar.json') != ''",
+        `        if: always() && env.SONAR_TOKEN != '' && hashFiles('reports/lint.${side}.sonar.json') != ''`,
         '        with:',
-        '          name: sonar-lint',
-        '          path: reports/lint.sonar.json',
+        `          name: sonar-lint-${side}`,
+        `          path: reports/lint.${side}.sonar.json`,
       ] : []),
     ].join('\n'),
     codecovSteps: codecovSteps(lcovReport, codecov),
-    sonarJob: sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor),
+    sonarJob: sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, settings.timeoutSonar),
     lcovArtifact,
   };
 }

package/sync/hygiene.mjs

@@ -79,7 +79,10 @@ function stagedText(cwd, file) {
 
 /** The secret findings of `files` read from the index, as {file, code, message}; a file the name check already refused is not reported twice. */
 function secretGuardFindings(cwd, files, alreadyRefused = new Set()) {
-  return files.filter(file => !alreadyRefused.has(file)).flatMap(file => secretFileFindings({ file, text: stagedText(cwd, file) }).map(finding => ({ file, code: finding.code, message: finding.message })));
+  return files.filter(file => !alreadyRefused.has(file)).flatMap(file => {
+    const manifestText = /(?:^|\/)README\.md$/.test(file) ? stagedText(cwd, path.posix.join(path.posix.dirname(file), '.starcistacks/application-stacks.yaml')) ?? undefined : undefined;
+    return secretFileFindings({ file, text: stagedText(cwd, file), manifestText }).map(finding => ({ file, code: finding.code, message: finding.message }));
+  });
 }
 
 /** Findings for `files`: the guarded trees, then the secret guard over every file. */

package/sync/index.mjs

@@ -128,11 +128,12 @@ function readBundled(name) {
 
 /**
  * Fill `{{name}}` from vars and expand `{{> partial}}` lines. A partial line may be written as a line comment (`// {{> partial}}`)
- * so a JavaScript template stays valid source before rendering. An unknown name is an error, never an empty string.
+ * so a JavaScript template stays valid source before rendering. Empty variable-only lines disappear; an unknown name is an error.
  */
 export function render(text, vars, readTemplate = readBundled) {
   const withPartials = text.replace(/^(?:\/\/ )?\{\{> ([\w./-]+)\}\}\n/gm, (_, name) => trailingNewline(render(readTemplate(name), vars, readTemplate)));
-  return withPartials.replace(/\{\{([A-Za-z]\w*)\}\}/g, (_, key) => {
+  const presentLines = withPartials.replace(/^[ \t]*\{\{([A-Za-z]\w*)\}\}[ \t]*(?:\n|$)/gm, (line, key) => vars[key] === '' ? '' : line);
+  return presentLines.replace(/\{\{([A-Za-z]\w*)\}\}/g, (_, key) => {
     if (!Object.hasOwn(vars, key)) throw new SyncError('HFS_SYNC_TEMPLATE_VARIABLE', `template names {{${key}}}, which sync does not provide`);
     return vars[key];
   });
@@ -169,7 +170,7 @@ const SOURCE_SKIPPED = new Set(['node_modules', 'dist', 'coverage']);
  * lite brand tree exists, so sync can preserve its absence. `hasImage` identifies authored optional Dockerfiles without reading
  * their content. An app with no be folder has no source files.
  */
-export function appSource(root, { parseYaml } = {}) {
+export function appSource(root, { parseYaml, notices } = {}) {
   const files = [];
   const walk = dir => {
     let entries;
@@ -183,7 +184,7 @@ export function appSource(root, { parseYaml } = {}) {
   return { runtimeExample: isRuntimeExampleApp(root), files: files.sort(byCodeUnit), read: file => fs.readFileSync(path.join(root, 'be', file), 'utf8'),
     workPresent: fs.existsSync(path.join(root, '.starciwork')), hasImage: file => isFile(path.join(root, file), { followLinks: false }),
     stack: readDeclaredStack(root, { parseYaml }), quality: readDeclaredQuality(root, { parseYaml }),
-    badges: readDeclaredBadges(root, { parseYaml }),
+    badges: readDeclaredBadges(root, { parseYaml, notices }),
     qualityDeclared: hasDeclaredServices(root, { parseYaml }) };
 }
 
@@ -323,7 +324,7 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
     sonarExclusions: [presets?.sonarExclusions, '**/.next/**', '**/node_modules/**', '**/src/messages/**', ...(lite ? ['supabase/types/**'] : [])].filter(Boolean).join(','),
     sonarSources: ['be/apps', 'be/src', 'fe/apps', ...(packages ? ['fe/packages'] : [])].join(','),
     lcovReport: LCOV_REPORT,
-    ...ciWorkflowCommands(source, LCOV_REPORT, source.qualityDeclared === false ? undefined : source.quality),
+    ...ciWorkflowCommands(source, LCOV_REPORT, source.qualityDeclared === false ? undefined : source.quality, { app }),
     // The coverage scope is the same in both editions: lite measures exactly what full measures (ruling:R212/case-1, amended by ruling:R212/case-4).
     jestCoverage: scope === 'be' ? jestCoverageSource(jestCoverage(manifest, providers)) : '',
     coverageExclusions: scope === APP_SCOPE ? sonarCoverageExclusions(manifest, providers).join(',') : '',
@@ -370,7 +371,7 @@ export function renderTargets(hfs, presets, { sonarKey, readTemplate = readBundl
       const template = target.path === 'codecov.yml' && source?.quality?.codecov.enabled === false
         ? '{{header}}\n# Codecov is disabled in the manifest.\ncodecov:\n  require_ci_to_pass: false\n'
         : readTemplate(target.template);
-      const body = render(template, vars, readTemplate);
+      const body = trailingNewline(render(template, vars, readTemplate));
       const where = onSide(scope, target.path);
       if (target.mode === 'scripts') {
         const scripts = parseScripts(body);
@@ -429,8 +430,8 @@ function insertAfterTitle(existing, content) {
   return `${heading}\n${content}${existing.slice(end)}`;
 }
 
-/** Rewrite the missing or drifted targets; returns the paths written. */
-function writtenContent(target, existing) {
+/** Apply exactly one target to its whole file while preserving content outside the managed block or scripts. */
+export function writtenContent(target, existing) {
   if (target.mode === 'scripts') {
     let pkg = {};
     if (existing) {
@@ -477,10 +478,10 @@ export function loadHfs(root, manifest = loadSlotManifest()) {
 }
 
 /** The rendered targets of the app at `root`: its hfs.json, the Sonar key the be side's stack declaration names, the presets it installs. */
-export async function renderRepo(root, { presets, parseYaml, manifest = loadSlotManifest() } = {}) {
+export async function renderRepo(root, { presets, parseYaml, notices, manifest = loadSlotManifest() } = {}) {
   const hfs = loadHfs(root, manifest);
   const sonarKey = await readDeclaredSonarKey(root, { parseYaml, fail: message => { throw new SyncError('HFS_SYNC_SONAR_KEY', message); } });
-  return { hfs, targets: renderTargets(hfs, presets ?? await loadPresets(root), { sonarKey, manifest, source: appSource(root, { parseYaml }) }) };
+  return { hfs, targets: renderTargets(hfs, presets ?? await loadPresets(root), { sonarKey, manifest, source: appSource(root, { parseYaml, notices }) }) };
 }
 
 /** `starci app sync --check | --write [--cwd <dir>]` at the app root; returns 0 clean, 1 drift, 2 usage. */
@@ -516,7 +517,9 @@ export async function runSync(argv, { cwd = process.cwd(), out = line => process
   const { write, cwdAt } = options;
   const root = cwdAt >= 0 ? path.resolve(cwd, argv[cwdAt + 1]) : cwd;
   try {
-    const { targets } = await renderRepo(root, { presets, parseYaml });
+    const notices = [];
+    const { targets } = await renderRepo(root, { presets, parseYaml, notices });
+    if (targets.some(target => target.path === 'README.md')) for (const notice of new Set(notices)) out(notice);
     if (write) {
       const written = writeTargets(root, targets);
       for (const file of written) out(`wrote ${file}`);

package/sync/quality-services.mjs

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { parseYaml as bundledParseYaml } from '../runtime/engine/yaml.mjs';
 import { qualityServices } from '../runtime/scripts/hfs/ci-declaration.mjs';
 import { isRuntimeExampleApp } from '../runtime/scripts/lib/runtime-example.mjs';
-import { renderReadmeBadges } from './readme-badges.mjs';
+import { badgeTokenNotices, renderReadmeBadges } from './readme-badges.mjs';
 import { DECLARATION } from './sonar-key.mjs';
 
 /** Apps without any service block retain the legacy CI defaults until they declare their services. */
@@ -35,8 +35,8 @@ export function sonarHostLine(sonar) {
 
 /** Dependabot groups minor and patch updates while majors remain per package; security updates have their own immediate group. */
 export function dependabotUpdates(dependabot) {
-  if (!dependabot.ecosystems.length) return '  []';
-  return dependabot.ecosystems.map(ecosystem => [
+  if (!dependabot.ecosystems.length) return ' []';
+  return '\n' + dependabot.ecosystems.map(ecosystem => [
     `  - package-ecosystem: ${ecosystem}`,
     ...(ecosystem === 'docker' ? ['    directories:', '      - /be/apps/*', '      - /fe/apps/*'] : ['    directory: /']),
     '    schedule:',
@@ -53,9 +53,11 @@ export function dependabotUpdates(dependabot) {
 }
 
 /** README badges use only public manifest fields and the package repository fallback. */
-export function readDeclaredBadges(root, { parseYaml = bundledParseYaml } = {}) {
+export function readDeclaredBadges(root, { parseYaml = bundledParseYaml, notices } = {}) {
   let doc = {}, pkg = {};
   try { doc = parseYaml(fs.readFileSync(path.join(root, DECLARATION), 'utf8')); } catch { /* No declaration. */ }
   try { pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')); } catch { /* No repository fallback. */ }
-  return renderReadmeBadges(doc, { repository: pkg.repository, example: isRuntimeExampleApp(root) });
+  const options = { repository: pkg.repository, example: isRuntimeExampleApp(root) };
+  notices?.push(...badgeTokenNotices(doc, options));
+  return renderReadmeBadges(doc, options);
 }

package/sync/readme-badges.mjs

@@ -7,6 +7,9 @@ function githubRepository(repository) {
   return (match?.[1] ?? match?.[2] ?? '').replace(/\.git$/, '');
 }
 
+/** Notice code (never an error) of a private repository badge rendered without its read-only badge token. */
+const BADGE_TOKEN_NOTICE = 'README_BADGE_TOKEN_MISSING';
+
 const badge = (name, image, link) => `[![${name}](${image})](${link})`;
 
 /** Render live CI, coverage, quality gate and Dependabot badges only when a GitHub repository is declared or inferable; no network is used. */
@@ -20,7 +23,10 @@ export function renderReadmeBadges(doc, { repository, example = false } = {}) {
   const quality = qualityServices(doc, { example });
   const lines = [badge('CI', `${base}/actions/workflows/${workflow}/badge.svg?branch=${branch}`, `${base}/actions/workflows/${workflow}`)];
   if (quality.codecov.enabled) {
-    const flag = quality.codecov.flag ? `?flag=${encodeURIComponent(quality.codecov.flag)}` : '';
+    const params = [];
+    if (quality.codecov.flag) params.push(`flag=${encodeURIComponent(quality.codecov.flag)}`);
+    if (doc?.services?.codecov?.badgeToken) params.push(`token=${encodeURIComponent(doc.services.codecov.badgeToken)}`);
+    const flag = params.length ? `?${params.join('&')}` : '';
     lines.push(badge('Codecov', `https://codecov.io/gh/${repo}/branch/${branch}/graph/badge.svg${flag}`, `https://codecov.io/gh/${repo}`));
   }
   const sonar = sonarBadge(doc, quality.sonar, example);
@@ -40,5 +46,15 @@ function sonarBadge(doc, sonar, example) {
   const organization = sonar.organization ?? doc?.ci?.vars?.find(entry => entry.name === sonar.organizationVar)?.value;
   const prefix = example && organization ? `${organization}_` : '';
   const key = encodeURIComponent(prefix + sonar.projectKey);
-  return badge('Quality Gate', `${host}/api/project_badges/measure?project=${key}&metric=alert_status`, `${host}/dashboard?id=${key}`);
+  const token = doc?.services?.sonar?.badgeToken ? `&token=${encodeURIComponent(doc.services.sonar.badgeToken)}` : '';
+  return badge('Quality Gate', `${host}/api/project_badges/measure?project=${key}&metric=alert_status${token}`, `${host}/dashboard?id=${key}`);
+}
+
+/** Private repositories need public-safe badge tokens only for badges the renderer actually emits; examples never receive notices. */
+export function badgeTokenNotices(doc, { example = false, repository } = {}) {
+  if (example || doc?.ci?.github?.visibility !== 'private') return [];
+  const rendered = renderReadmeBadges(doc, { example, repository });
+  return [['codecov', 'Codecov', 'Codecov'], ['sonar', 'Sonar', 'Quality Gate']]
+    .filter(([id, , label]) => !doc?.services?.[id]?.badgeToken && rendered.includes(`[![${label}](`))
+    .map(([id, name]) => `${BADGE_TOKEN_NOTICE} notice: the ${name} badge of a private repository renders "unknown" without services.${id}.badgeToken (a read-only badge token, not a CI secret)`);
 }

package/sync/stack-images.mjs

@@ -71,6 +71,11 @@ export function readDeclaredStack(root, { parseYaml = bundledParseYaml } = {}) {
   } catch {
     return { images: [], passEnv: [] };
   }
+  return declaredStack(declaration);
+}
+
+/** Parsed declarations share the exact image, environment and pass-env projection used by sync. */
+export function declaredStack(declaration) {
   return { images: declaredStackImages(declaration), passEnv: declaredPassEnv(declaration), imageEnvironments: imageEnvironments(declaration) };
 }
 

package/templates/app/ci-workflows/build-cache-save.yml

@@ -0,0 +1,8 @@
+      - name: build cache save
+        if: always()
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: |
+            .turbo
+            fe/apps/*/.next/cache
+          key: ${{ runner.os }}-node{{nodeMajor}}-build-${{ hashFiles('package-lock.json') }}-${{ github.run_id }}

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

@@ -1,8 +1,10 @@
 {{header}}
 name: ci
 
+# The release candidate ref first (starci app release push waits for this run of the release sha before the branch and the tag move), then the tag.
 on:
   push:
+    branches: ["release/candidate-*"]
     tags: ["v*"]
   workflow_dispatch:
 
@@ -14,24 +16,58 @@ concurrency:
   group: ci-${{ github.ref }}
   cancel-in-progress: false
 
+# The job shape of the StarCi CI standard (knowledge/hfs/ci-standard.yaml): fast, lint per side, the unit run in shards, one coverage merge, build,
+# and sonar. Timeouts and the shard count come from ci.jobs of .starcistacks/application-stacks.yaml (defaults in the standard).
 jobs:
   fast:
-    timeout-minutes: 20
+    timeout-minutes: {{timeoutFast}}
     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}}
       - name: format
         run: npm run format:check
       - name: typecheck
         run: npm run typecheck
 
+  lint:
+    timeout-minutes: {{timeoutLint}}
+    runs-on: ubuntu-latest
+{{sonarEnv}}
+    strategy:
+      fail-fast: false
+      matrix:
+        side: [be, fe]
+    steps:
+{{> app/ci-workflows/install-steps.yml}}
+{{> app/ci-workflows/lint-base.yml}}
+{{ciLintSteps}}
+
   test:
-    timeout-minutes: 45
+    timeout-minutes: {{timeoutTest}}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: {{testShards}}
+    steps:
+{{> app/ci-workflows/install-steps.yml}}
+{{> app/ci-workflows/jest-cache.yml}}
+      # Each shard measures without the per-file threshold (a shard loads only its share of the specs, and a small suite may leave a shard empty);
+      # the coverage job proves 100 per file on the merged report.
+      - name: unit
+        run: npm test -- --ci --forceExit --cacheDirectory .jest-cache --shard=${{ matrix.shard }}/{{testShardTotal}} --passWithNoTests --coverageThreshold={}
+{{> app/ci-workflows/jest-cache-save.yml}}
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: always() && hashFiles('{{lcovReport}}') != ''
+        with:
+          name: coverage-shard-${{ matrix.shard }}
+          path: {{lcovReport}}
+
+  coverage:
+    needs: test
+    timeout-minutes: {{timeoutCoverage}}
     runs-on: ubuntu-latest
     # Codecov OIDC authentication requires a job-scoped identity token.
     permissions:
@@ -39,11 +75,16 @@ jobs:
       id-token: write
     steps:
 {{> app/ci-workflows/install-steps.yml}}
-{{> app/ci-workflows/jest-cache.yml}}
-      - name: unit
-        run: npm test -- --ci --forceExit --cacheDirectory .jest-cache
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          pattern: coverage-shard-*
+          path: {{lcovShardsDir}}
+      - name: merge coverage
+        run: npx starci app coverage merge --out {{lcovReport}} {{lcovShardsDir}}
       - name: coverage proof
         run: {{ciCoverageProof}}
+        env:
+          NODE_OPTIONS: --max-old-space-size=6144
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         if: always() && hashFiles('{{lcovReport}}') != ''
         with:
@@ -52,14 +93,13 @@ jobs:
 {{codecovSteps}}
 
   build:
-    timeout-minutes: 30
+    timeout-minutes: {{timeoutBuild}}
     runs-on: ubuntu-latest
     steps:
 {{> app/ci-workflows/install-steps.yml}}
       - name: build be
         run: npm run build:be
-      - name: build fe
-        run: npm run build:fe
-{{ciBuildEnv}}
+{{ciBuildSteps}}
+{{> app/ci-workflows/build-cache-save.yml}}
 
 {{sonarJob}}

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

@@ -10,12 +10,13 @@
         with:
           path: node_modules
           key: ${{ runner.os }}-node{{nodeMajor}}-modules-${{ hashFiles('package-lock.json') }}
-      - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+      # The build cache is restored in every job and saved by the build job always (build-cache-save.yml), keyed by the lockfile and the run.
+      - uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
         with:
           path: |
             .turbo
             fe/apps/*/.next/cache
-          key: ${{ runner.os }}-node{{nodeMajor}}-build-${{ hashFiles('package-lock.json') }}-${{ github.sha }}
+          key: ${{ runner.os }}-node{{nodeMajor}}-build-${{ hashFiles('package-lock.json') }}-${{ github.run_id }}
           restore-keys: |
             ${{ runner.os }}-node{{nodeMajor}}-build-${{ hashFiles('package-lock.json') }}-
             ${{ runner.os }}-node{{nodeMajor}}-build-

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

@@ -0,0 +1,6 @@
+      - name: Jest cache save
+        if: always()
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: .jest-cache
+          key: ${{ runner.os }}-node{{nodeMajor}}-jest-${{ hashFiles('package-lock.json') }}-shard${{ matrix.shard }}-${{ github.run_id }}

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

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

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

@@ -1,8 +1,10 @@
 {{header}}
 name: ci
 
+# The release candidate ref first (starci app release push waits for this run of the release sha before the branch and the tag move), then the tag.
 on:
   push:
+    branches: ["release/candidate-*"]
     tags: ["v*"]
   workflow_dispatch:
 
@@ -14,24 +16,58 @@ concurrency:
   group: ci-${{ github.ref }}
   cancel-in-progress: false
 
+# The job shape of the StarCi CI standard (knowledge/hfs/ci-standard.yaml): fast, lint per side, the unit run in shards, one coverage merge, build,
+# sonar, and the database types of the lite edition. Timeouts and the shard count come from ci.jobs of .starcistacks/application-stacks.yaml (defaults in the standard).
 jobs:
   fast:
-    timeout-minutes: 20
+    timeout-minutes: {{timeoutFast}}
     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}}
       - name: format
         run: npm run format:check
       - name: typecheck
         run: npm run typecheck
 
+  lint:
+    timeout-minutes: {{timeoutLint}}
+    runs-on: ubuntu-latest
+{{sonarEnv}}
+    strategy:
+      fail-fast: false
+      matrix:
+        side: [be, fe]
+    steps:
+{{> app/ci-workflows/install-steps.yml}}
+{{> app/ci-workflows/lint-base.yml}}
+{{ciLintSteps}}
+
   test:
-    timeout-minutes: 45
+    timeout-minutes: {{timeoutTest}}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: {{testShards}}
+    steps:
+{{> app/ci-workflows/install-steps.yml}}
+{{> app/ci-workflows/jest-cache.yml}}
+      # Each shard measures without the per-file threshold (a shard loads only its share of the specs, and a small suite may leave a shard empty);
+      # the coverage job proves 100 per file on the merged report.
+      - name: unit
+        run: npm test -- --ci --forceExit --cacheDirectory .jest-cache --shard=${{ matrix.shard }}/{{testShardTotal}} --passWithNoTests --coverageThreshold={}
+{{> app/ci-workflows/jest-cache-save.yml}}
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: always() && hashFiles('{{lcovReport}}') != ''
+        with:
+          name: coverage-shard-${{ matrix.shard }}
+          path: {{lcovReport}}
+
+  coverage:
+    needs: test
+    timeout-minutes: {{timeoutCoverage}}
     runs-on: ubuntu-latest
     # Codecov OIDC authentication requires a job-scoped identity token.
     permissions:
@@ -39,11 +75,16 @@ jobs:
       id-token: write
     steps:
 {{> app/ci-workflows/install-steps.yml}}
-{{> app/ci-workflows/jest-cache.yml}}
-      - name: unit
-        run: npm test -- --ci --forceExit --cacheDirectory .jest-cache
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          pattern: coverage-shard-*
+          path: {{lcovShardsDir}}
+      - name: merge coverage
+        run: npx starci app coverage merge --out {{lcovReport}} {{lcovShardsDir}}
       - name: coverage proof
         run: {{ciCoverageProof}}
+        env:
+          NODE_OPTIONS: --max-old-space-size=6144
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         if: always() && hashFiles('{{lcovReport}}') != ''
         with:
@@ -52,22 +93,20 @@ jobs:
 {{codecovSteps}}
 
   build:
-    timeout-minutes: 30
+    timeout-minutes: {{timeoutBuild}}
     runs-on: ubuntu-latest
     steps:
 {{> app/ci-workflows/install-steps.yml}}
       - name: build be
         run: npm run build:be
-      - name: build fe
-        run: npm run build:fe
-{{ciBuildEnv}}
+{{ciBuildSteps}}
+{{> app/ci-workflows/build-cache-save.yml}}
       - name: database migration checks
         run: {{ciDatabaseLint}}
 
 {{sonarJob}}
-
   db-types:
-    timeout-minutes: 30
+    timeout-minutes: {{timeoutDbTypes}}
     runs-on: ubuntu-latest
     steps:
 {{> app/ci-workflows/install-steps.yml}}