@starci/hfs 4.4.1 → 4.5.0

package/sync/index.mjs

@@ -7,11 +7,11 @@
 // templates/<scope or common>/<managedBy>/<file path with each leading dot dropped>, with dotted skeleton paths tried when no
 // undotted template exists. The scope is app for a root slot and the
 // side (be, fe) for a side slot, whose files land under that side's folder. Two targets are not whole files of a managedBy slot
-// and are listed in this module: the marked block of the root .gitignore, and .starciwork/.gitignore, which lives inside the
+// and are listed in this module: the marked blocks of the root .gitignore and README.md, and .starciwork/.gitignore, which lives inside the
 // .starciwork directory slot. Every file is rendered with the app's hfs.json (both sides and their apps) and, for the Sonar
 // exclusions, the jest preset the app installs for its be side and the one coverage scope derived from the slot manifest
 // (scripts/hfs/coverage-scope.mjs: the be/jest.config.js scope, sonar.coverage.exclusions and the codecov.yml paths and components). `--check` compares the sha256 of the rendered content with the
-// file on disk and fails on any drift; `--write` rewrites the drifted files. `.gitignore` is the one shared file: only the marked
+// file on disk and fails on any drift; `--write` rewrites the drifted files. `.gitignore` and README.md are shared files: only the marked
 // block is managed and the app's own lines around it are left alone. The root package.json is managed by its `scripts` block
 // only (mode scripts, compared as parsed JSON): the rest of the file (dependencies, the npm workspaces fe/apps/* and fe/packages/*,
 // HFS_MONO_WORKSPACES) is the app's. The fe side runs through turbo (turbo.json, app.task-graph): each fe app and package is a workspace.
@@ -31,6 +31,8 @@ import { readDeclaredStack, stackWorkflowVariables } from './stack-images.mjs';
 import { byCodeUnit } from '../report/order.mjs';
 import { isRuntimeExampleApp } from '../runtime/scripts/lib/runtime-example.mjs';
 import { ciWorkflowCommands } from './ci-commands.mjs';
+import { dependabotUpdates, hasDeclaredServices, readDeclaredQuality, readDeclaredBadges, sonarHostLine } from './quality-services.mjs';
+import { qualityServices } from '../runtime/scripts/hfs/ci-declaration.mjs';
 
 export const TEMPLATES_DIR = path.join(import.meta.dirname, '..', 'templates');
 const NODE_MAJOR = 22;
@@ -167,7 +169,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) {
+export function appSource(root, { parseYaml } = {}) {
   const files = [];
   const walk = dir => {
     let entries;
@@ -180,7 +182,9 @@ export function appSource(root) {
   for (const dir of ['apps', 'src']) walk(dir);
   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) };
+    stack: readDeclaredStack(root, { parseYaml }), quality: readDeclaredQuality(root, { parseYaml }),
+    badges: readDeclaredBadges(root, { parseYaml }),
+    qualityDeclared: hasDeclaredServices(root, { parseYaml }) };
 }
 
 /**
@@ -299,8 +303,10 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
   const packages = opensPackages(fe);
   const lite = app.edition === 'lite';
   const providers = (app.sides.be.connections ?? []).map(connection => connection.provider);
+  const quality = source.quality ?? qualityServices({});
   return {
     header: HEADER(scope),
+    readmeBadges: source.badges ?? '',
     project: app.project,
     appBinary: APP_BINARY,
     appScripts: appScripts(app, source),
@@ -313,15 +319,18 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
     lintPrefix: 'npm run codegen --silent && ',
     nodeMajor: String(NODE_MAJOR),
     sonarKey: sonarKey ?? app.project,
+    sonarHostLine: sonarHostLine(quality.sonar),
     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),
+    ...ciWorkflowCommands(source, LCOV_REPORT, source.qualityDeclared === false ? undefined : source.quality),
     // 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(',') : '',
     codecovPaths: scope === APP_SCOPE ? codecovPaths(manifest, providers).map(glob => `          - ${JSON.stringify(glob)}`).join('\n') : '',
     codecovComponents: scope === APP_SCOPE ? componentsYaml(coverageComponents(manifest, { ...source, apps: app.sides.be.apps, providers })) : '',
+    codecovTarget: quality.codecov.target,
+    dependabotUpdates: dependabotUpdates(quality.dependabot),
     tsconfigPaths: ['be/tsconfig.json', ...fe.apps.map(entry => `fe/apps/${entry.name}/tsconfig.json`), ...(packages ? ['fe/packages/*/tsconfig.json'] : [])].join(','),
     styleGlob: STYLE_GLOB,
     imageMatrix: imageMatrix(app, source),
@@ -353,10 +362,15 @@ export function renderTargets(hfs, presets, { sonarKey, readTemplate = readBundl
   const hasTemplate = name => { try { return readTemplate(name) !== undefined; } catch { return false; } };
   return SCOPES.flatMap(scope => {
     const vars = variables(app, scope, presets, sonarKey, manifest, source);
-    const targets = targetsOf(scope, { edition: app.edition, manifest, hasTemplate })
+    const declaredTargets = targetsOf(scope, { edition: app.edition, manifest, hasTemplate });
+    if (scope === APP_SCOPE && source?.badges) declaredTargets.push({ path: 'README.md', mode: 'block', markdown: true, template: 'app/readme-badges/README.md' });
+    const targets = declaredTargets
       .filter(target => !(app.edition === 'lite' && source?.workPresent === false && target.path === '.starciwork/.gitignore'));
     return targets.map(target => {
-      const body = render(readTemplate(target.template), vars, readTemplate);
+      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 where = onSide(scope, target.path);
       if (target.mode === 'scripts') {
         const scripts = parseScripts(body);
@@ -364,21 +378,22 @@ export function renderTargets(hfs, presets, { sonarKey, readTemplate = readBundl
         const content = scriptsText(scripts);
         return { path: where, scope, mode: 'scripts', content, hash: hashOf(content), scripts };
       }
-      const managed = target.mode === 'block' ? `${BLOCK_BEGIN}\n${trailingNewline(body)}${BLOCK_END}\n` : body;
-      return { path: where, scope, mode: target.mode, content: managed, hash: hashOf(managed) };
+      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;
+      return { path: where, scope, mode: target.mode, markdown: target.markdown, markers, content: managed, hash: hashOf(managed) };
     });
   });
 }
 
 // The part of a file sync manages: all of it, the marked block, or the scripts block as text.
-function managedPart(mode, text) {
+function managedPart(mode, text, markers = { begin: BLOCK_BEGIN, end: BLOCK_END }) {
   if (mode === 'file') return text;
   if (mode === 'scripts') {
     const scripts = parseScripts(text);
     return scripts ? scriptsText(scripts) : null;
   }
-  const start = text.indexOf(BLOCK_BEGIN);
-  const end = text.indexOf(BLOCK_END);
+  const start = text.indexOf(markers.begin);
+  const end = text.indexOf(markers.end);
   if (start < 0 || end < start) return null;
   const stop = text.indexOf('\n', end);
   return text.slice(start, stop < 0 ? text.length : stop + 1);
@@ -397,7 +412,7 @@ export function checkTargets(root, targets) {
   return targets.map(target => {
     const file = path.join(root, target.path);
     if (!fs.existsSync(file)) return { path: target.path, status: 'missing', expectedHash: target.hash };
-    const part = managedPart(target.mode, lf(fs.readFileSync(file, 'utf8')));
+    const part = managedPart(target.mode, lf(fs.readFileSync(file, 'utf8')), target.markers);
     if (part === null) return { path: target.path, status: 'missing', expectedHash: target.hash };
     const actualHash = hashOf(part);
     if (actualHash === target.hash) return { path: target.path, status: 'ok', expectedHash: target.hash, actualHash };
@@ -405,6 +420,14 @@ export function checkTargets(root, targets) {
   });
 }
 
+function insertAfterTitle(existing, content) {
+  const title = /^# [^\n]*(?:\n|$)/m.exec(existing);
+  if (!title) return `${content}\n${existing}`;
+  const end = title.index + title[0].length;
+  const heading = trailingNewline(existing.slice(0, end));
+  return `${heading}\n${content}${existing.slice(end)}`;
+}
+
 /** Rewrite the missing or drifted targets; returns the paths written. */
 function writtenContent(target, existing) {
   if (target.mode === 'scripts') {
@@ -415,8 +438,10 @@ function writtenContent(target, existing) {
     return `${JSON.stringify({ ...pkg, scripts: target.scripts }, null, 2)}\n`;
   }
   if (target.mode === 'block' && existing) {
-    const current = managedPart('block', existing);
-    return current === null ? `${target.content}\n${existing}` : existing.replace(current, () => target.content);
+    const current = managedPart('block', existing, target.markers);
+    if (current !== null) return existing.replace(current, () => target.content);
+    if (target.markdown) return insertAfterTitle(existing, target.content);
+    return `${target.content}\n${existing}`;
   }
   return target.content;
 }
@@ -454,7 +479,7 @@ export function loadHfs(root, manifest = loadSlotManifest()) {
 export async function renderRepo(root, { presets, parseYaml, 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), stack: readDeclaredStack(root, { parseYaml }) } }) };
+  return { hfs, targets: renderTargets(hfs, presets ?? await loadPresets(root), { sonarKey, manifest, source: appSource(root, { parseYaml }) }) };
 }
 
 /** `starci app sync --check | --write [--cwd <dir>]` at the app root; returns 0 clean, 1 drift, 2 usage. */

package/sync/quality-services.mjs

@@ -0,0 +1,61 @@
+import fs from 'node:fs';
+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 { DECLARATION } from './sonar-key.mjs';
+
+/** Apps without any service block retain the legacy CI defaults until they declare their services. */
+export function hasDeclaredServices(root, { parseYaml = bundledParseYaml } = {}) {
+  try {
+    const doc = parseYaml(fs.readFileSync(path.join(root, DECLARATION), 'utf8'));
+    return Object.keys(doc?.services ?? {}).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Missing or unreadable manifests preserve the shared quality defaults; example apps use the runtime example policy. */
+export function readDeclaredQuality(root, { parseYaml = bundledParseYaml } = {}) {
+  try {
+    const doc = parseYaml(fs.readFileSync(path.join(root, DECLARATION), 'utf8'));
+    return qualityServices(doc, { example: isRuntimeExampleApp(root) });
+  } catch {
+    return qualityServices({});
+  }
+}
+
+/** SonarCloud names its organization and public host; SonarQube uses the manifest host. */
+export function sonarHostLine(sonar) {
+  if (!sonar) return '';
+  if (sonar.provider === 'sonarcloud') return [sonar.organization ? `sonar.organization=${sonar.organization}` : '', 'sonar.host.url=https://sonarcloud.io'].filter(Boolean).join('\n');
+  return sonar.host ? `sonar.host.url=${sonar.host}` : '';
+}
+
+/** 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 => [
+    `  - package-ecosystem: ${ecosystem}`,
+    ...(ecosystem === 'docker' ? ['    directories:', '      - /be/apps/*', '      - /fe/apps/*'] : ['    directory: /']),
+    '    schedule:',
+    `      interval: ${dependabot.schedule.interval}`,
+    ...(dependabot.schedule.day ? [`      day: ${dependabot.schedule.day}`] : []),
+    ...(dependabot.schedule.time ? [`      time: ${JSON.stringify(dependabot.schedule.time)}`] : []),
+    '    groups:',
+    ...(ecosystem === 'github-actions' ? ['      actions:', '        patterns: ["*"]'] : [
+      ...(dependabot.groups.minorPatch === 'grouped' ? ['      minor-and-patch:', '        update-types: [minor, patch]'] : []),
+      ...(dependabot.security === 'immediate' ? ['      security:', '        applies-to: security-updates', '        patterns: ["*"]', '        update-types: [minor, patch]'] : []),
+    ]),
+    ...(ecosystem === 'npm' && dependabot.ignore.length ? ['    ignore:', ...dependabot.ignore.map(name => `      - dependency-name: ${JSON.stringify(name)}`)] : []),
+  ].join('\n')).join('\n');
+}
+
+/** README badges use only public manifest fields and the package repository fallback. */
+export function readDeclaredBadges(root, { parseYaml = bundledParseYaml } = {}) {
+  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) });
+}

package/sync/readme-badges.mjs

@@ -0,0 +1,44 @@
+import { qualityServices } from '../runtime/scripts/hfs/ci-declaration.mjs';
+
+/** Package repository fallbacks must name a GitHub HTTPS or Git transport URL. */
+function githubRepository(repository) {
+  const url = typeof repository === 'string' ? repository : repository?.url;
+  const match = /^(?:git\+)?https:\/\/github\.com\/([^/]+\/[^/#?]+)|^git@github\.com:([^/]+\/[^/#?]+)/.exec(url ?? '');
+  return (match?.[1] ?? match?.[2] ?? '').replace(/\.git$/, '');
+}
+
+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. */
+export function renderReadmeBadges(doc, { repository, example = false } = {}) {
+  const github = doc?.ci?.github ?? {};
+  const repo = github.repository ?? githubRepository(repository);
+  if (!repo) return '';
+  const branch = encodeURIComponent(github.defaultBranch ?? 'main');
+  const workflow = encodeURIComponent(github.workflow ?? 'ci.yml');
+  const base = `https://github.com/${repo}`;
+  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)}` : '';
+    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);
+  if (sonar) lines.push(sonar);
+  if (quality.dependabot.ecosystems.length) {
+    const updates = `${base}/actions/workflows/dependabot/dependabot-updates`;
+    lines.push(badge('Dependabot', `${updates}/badge.svg`, updates));
+  }
+  return lines.join('\n');
+}
+
+/** Runtime examples use the organization-qualified key passed by examples.yml; products declare their complete project key. */
+function sonarBadge(doc, sonar, example) {
+  if (!sonar?.projectKey) return '';
+  const host = sonar.provider === 'sonarcloud' ? 'https://sonarcloud.io' : sonar.host?.replace(/\/$/, '');
+  if (!host) return '';
+  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}`);
+}

package/sync/stack-images.mjs

@@ -51,8 +51,15 @@ function declaredPassEnv(declaration) {
   return [...new Set(names)].sort(byCodeUnit);
 }
 
+/** Release builds select the sole image environment, or production when several environments deploy images. */
+function imageEnvironments(declaration) {
+  return Object.fromEntries(Object.entries(declaration?.environments ?? {})
+    .filter(([name, environment]) => NAME.test(name) && environmentImages(environment).length > 0)
+    .map(([name, environment]) => [name, environmentImages(environment).map(image => image.app)]));
+}
+
 /**
- * What the managed workflow renders from the declaration of the app at `root`: { images, passEnv } (both empty when the app has no
+ * What the managed workflows render from the declaration at `root`: { images, passEnv, imageEnvironments } (empty when the app has no
  * declaration, no deploy block or a declaration that does not parse; `starci app check` judges those). `parseYaml(text)` is injected.
  */
 export function readDeclaredStack(root, { parseYaml = bundledParseYaml } = {}) {
@@ -64,7 +71,7 @@ export function readDeclaredStack(root, { parseYaml = bundledParseYaml } = {}) {
   } catch {
     return { images: [], passEnv: [] };
   }
-  return { images: declaredStackImages(declaration), passEnv: declaredPassEnv(declaration) };
+  return { images: declaredStackImages(declaration), passEnv: declaredPassEnv(declaration), imageEnvironments: imageEnvironments(declaration) };
 }
 
 const envName = service => `IMAGE_${service.toUpperCase().replaceAll('-', '_')}`;
@@ -109,7 +116,7 @@ function buildPushStep(image, dockerfile) {
  *   stackPassEnv     the env entries of the deploy step for the declared host variables (vars.<NAME>)
  * `dockerfileOf(app)` names the Dockerfile of an app (the sync module knows the layout).
  */
-export function stackWorkflowVariables({ images = [], passEnv = [] }, project, dockerfileOf) {
+export function stackWorkflowVariables({ images = [], passEnv = [], imageEnvironments: environments = {} }, project, dockerfileOf) {
   const guard = images.length ? '' : block([
     '- name: require a declared image',
     '  shell: bash',
@@ -117,6 +124,7 @@ export function stackWorkflowVariables({ images = [], passEnv = [] }, project, d
   ]);
   const names = images.map(image => `echo "${image.service}=ghcr.io/\${owner}/${project}-${image.app}" >> "$GITHUB_OUTPUT"`);
   return {
+    ...releaseImageVariables(environments),
     stackGuard: guard,
     stackNames: block(names, ' '.repeat(10)),
     stackImageSteps: images.map(image => block([...(image.buildArgs ? buildArgsStep(image) : []), ...buildPushStep(image, dockerfileOf(image.app))])).join(''),
@@ -125,3 +133,21 @@ export function stackWorkflowVariables({ images = [], passEnv = [] }, project, d
     stackPassEnv: block(passEnv.map(name => `${name}: \${{ vars.${name} }}`), ' '.repeat(10)),
   };
 }
+
+/** The matrix uses the deploy verb only for apps the selected environment deploys; undeployed images retain Dockerfile defaults. */
+function releaseImageVariables(environments) {
+  const names = Object.keys(environments);
+  const selectedApp = names.map(name => `(env.STACK_ENVIRONMENT == '${name}' && contains(fromJSON('${JSON.stringify(environments[name])}'), matrix.name))`).join(' || ') || 'false';
+  const multiple = names.length > 1;
+  const environment = multiple ? 'production' : names[0] ?? 'production';
+  return {
+    imageEnvironment: environment,
+    imageJobEnvironment: names.length ? `\n    environment: ${environment}` : '',
+    imageEnvironmentGuard: multiple ? block([
+      '- name: require a declared image environment',
+      `  if: \${{ !contains(fromJSON('${JSON.stringify(names)}'), env.STACK_ENVIRONMENT) }}`,
+      '  run: \'echo "::error::STACKS_DEPLOY_ENV_UNKNOWN: selected environment declares no deploy images"; exit 1\'',
+    ]) : '',
+    imageBuildArgsIf: `\${{ ${selectedApp} }}`,
+  };
+}

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

@@ -15,43 +15,45 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  ci:
+  fast:
     runs-on: ubuntu-latest
-    # id-token: write lets the Codecov upload authenticate with GitHub's OIDC token: no repository secret, no silent skip.
-    permissions:
-      contents: read
-      id-token: write
-    env:
-      SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+{{sonarEnv}}
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
-        with:
-          node-version: {{nodeMajor}}
-          cache: npm
-      - run: npm ci --ignore-scripts
+{{> app/ci-workflows/install-steps.yml}}
       - name: production dependency audit
-        run: npm audit --omit=dev --audit-level=high
-      - name: lint
-        run: {{ciLintSonar}}
+        run: {{auditCommand}}
+{{ciLintSteps}}
       - name: format
         run: npm run format:check
       - name: typecheck
         run: npm run typecheck
+
+  test:
+    runs-on: ubuntu-latest
+    # Codecov OIDC authentication requires a job-scoped identity token.
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+{{> app/ci-workflows/install-steps.yml}}
       - name: unit
         run: npm test -- --ci
       - name: coverage proof
         run: {{ciCoverageProof}}
-      - name: coverage upload
-        uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5.5.5
-        if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') }}
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: always() && hashFiles('{{lcovReport}}') != ''
         with:
-          use_oidc: true
-          files: {{lcovReport}}
-          disable_search: true
-          fail_ci_if_error: true
+          name: {{lcovArtifact}}
+          path: {{lcovReport}}
+{{codecovSteps}}
+
+  build:
+    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
-{{> app/ci-workflows/sonar-steps.yml}}
+
+{{sonarJob}}

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

@@ -17,21 +17,43 @@ concurrency:
 
 jobs:
   image:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-latest{{imageJobEnvironment}}
+    env:
+      STACK_ENVIRONMENT: {{imageEnvironment}}
     strategy:
       fail-fast: false
       matrix:
         include:
 {{imageMatrix}}
-    steps:
+    steps:{{imageEnvironmentGuard}}
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
       - name: release tag matches package version
         run: node -e "const version=require('./package.json').version;if(process.env.GITHUB_REF_NAME!=='v'+version)process.exit(1)"
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        if: {{imageBuildArgsIf}}
+        with:
+          node-version: {{nodeMajor}}
+          cache: npm
+      - run: npm ci --ignore-scripts
+        if: {{imageBuildArgsIf}}
+      - name: install SOPS
+        if: {{imageBuildArgsIf}}
+        uses: mdgreenwald/mozilla-sops-action@bb2d96a13ef438ad122e5827a57ebd75d6ff118d # v2.1.0
+        with:
+          version: v3.13.2
+      - name: public build values
+        id: args
+        if: {{imageBuildArgsIf}}
+        env:
+          SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
+          IMAGE_APP: ${{ matrix.name }}
+        run: npx --no-install starci app stack build-args --env "$STACK_ENVIRONMENT" --app "$IMAGE_APP"
       - uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
       - uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
         with:
           context: .
           file: ${{ matrix.file }}
+          build-args: ${{ steps.args.outputs.args }}
           push: false
           tags: {{imageProject}}/${{ matrix.name }}:${{ github.ref_name }}
           # OCI keeps the SBOM and provenance attestations without publishing to a registry.

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

@@ -50,7 +50,6 @@ jobs:
       packages: write
     env:
       STACK_ENVIRONMENT: ${{ inputs.environment }}
-      XDG_DATA_HOME: ${{ runner.temp }}/starci-data
     steps:{{stackGuard}}
       - name: require release tag
         shell: bash
@@ -80,6 +79,7 @@ jobs:
           password: ${{ github.token }}{{stackImageSteps}}
       - name: connect to the swarm manager
         env:
+          XDG_DATA_HOME: ${{ runner.temp }}/starci-data
           VPS_SSH_KEY: ${{ secrets.VPS_SSH_KEY }}
           VPS_KNOWN_HOSTS: ${{ secrets.VPS_KNOWN_HOSTS }}
           VPS_HOST: ${{ vars.VPS_HOST }}
@@ -87,11 +87,14 @@ jobs:
         run: npx --no-install starci app stack connect --env "$STACK_ENVIRONMENT" --execute
       - name: deploy the release
         env:
+          XDG_DATA_HOME: ${{ runner.temp }}/starci-data
           SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}{{stackImageEnv}}{{stackPassEnv}}
         run: |
           npx --no-install starci app stack deploy --env "$STACK_ENVIRONMENT" \{{stackImageArgs}}
             --source-sha "$GITHUB_SHA" --execute
       - name: disconnect from the swarm manager
+        env:
+          XDG_DATA_HOME: ${{ runner.temp }}/starci-data
         if: ${{ always() }}
         run: npx --no-install starci app stack disconnect --env "$STACK_ENVIRONMENT" --execute
 
@@ -105,7 +108,6 @@ jobs:
       packages: read
     env:
       STACK_ENVIRONMENT: ${{ inputs.environment }}
-      XDG_DATA_HOME: ${{ runner.temp }}/starci-data
     steps:
       - name: require release tag
         shell: bash
@@ -129,6 +131,7 @@ jobs:
           password: ${{ github.token }}
       - name: connect to the swarm manager
         env:
+          XDG_DATA_HOME: ${{ runner.temp }}/starci-data
           VPS_SSH_KEY: ${{ secrets.VPS_SSH_KEY }}
           VPS_KNOWN_HOSTS: ${{ secrets.VPS_KNOWN_HOSTS }}
           VPS_HOST: ${{ vars.VPS_HOST }}
@@ -136,6 +139,7 @@ jobs:
         run: npx --no-install starci app stack connect --env "$STACK_ENVIRONMENT" --execute
       - name: redeploy the stored release
         env:
+          XDG_DATA_HOME: ${{ runner.temp }}/starci-data
           SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
           RELEASE: ${{ inputs.release }}
         shell: bash
@@ -144,5 +148,7 @@ jobs:
           [ -z "$RELEASE" ] || release=(--release "$RELEASE")
           npx --no-install starci app stack rollback --env "$STACK_ENVIRONMENT" "${release[@]}" --execute
       - name: disconnect from the swarm manager
+        env:
+          XDG_DATA_HOME: ${{ runner.temp }}/starci-data
         if: ${{ always() }}
         run: npx --no-install starci app stack disconnect --env "$STACK_ENVIRONMENT" --execute

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

@@ -0,0 +1,21 @@
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: {{nodeMajor}}
+          cache: npm
+      - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        id: deps
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node{{nodeMajor}}-modules-${{ hashFiles('package-lock.json') }}
+      - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: |
+            .turbo
+            fe/apps/*/.next/cache
+          key: ${{ runner.os }}-node{{nodeMajor}}-build-${{ hashFiles('package-lock.json') }}-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-node{{nodeMajor}}-build-${{ hashFiles('package-lock.json') }}-
+            ${{ runner.os }}-node{{nodeMajor}}-build-
+      - run: npm ci --ignore-scripts
+        if: steps.deps.outputs.cache-hit != 'true'

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

@@ -1,9 +1,3 @@
-      - uses: SonarSource/sonarqube-scan-action@c7ee0f9df90b7aa20e8dcf9695dcfe2e7da5b4f2 # v7.2.1
-        if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') && env.SONAR_TOKEN != '' }}
-        env:
-          SONAR_HOST_URL: ${{ vars.SONAR_HOST_URL }}
-      - uses: SonarSource/sonarqube-quality-gate-action@7a5fffe8e523c40e0c740b6bc2712ab503e52efa # v1.2.1
-        if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') && env.SONAR_TOKEN != '' }}
-        timeout-minutes: 10
-        env:
-          SONAR_HOST_URL: ${{ vars.SONAR_HOST_URL }}
+{{sonarJobHeader}}
+{{> app/ci-workflows/install-steps.yml}}
+{{sonarJobSteps}}

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

@@ -9,68 +9,61 @@ on:
 permissions:
   contents: read
 
-# One run per ref.
+# One run per ref: a release tag is never cancelled by another run.
 concurrency:
   group: ci-${{ github.ref }}
   cancel-in-progress: false
 
 jobs:
-  ci:
+  fast:
     runs-on: ubuntu-latest
-    # id-token: write lets the Codecov upload authenticate with GitHub's OIDC token: no repository secret, no silent skip.
-    permissions:
-      contents: read
-      id-token: write
-    env:
-      SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+{{sonarEnv}}
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
-        with:
-          node-version: {{nodeMajor}}
-          cache: npm
-      - run: npm ci --ignore-scripts
+{{> app/ci-workflows/install-steps.yml}}
       - name: production dependency audit
-        run: npm audit --omit=dev --audit-level=high
-      - name: lint
-        if: env.SONAR_TOKEN == ''
-        run: {{ciLint}}
-      - name: lint with Sonar import
-        if: env.SONAR_TOKEN != ''
-        run: {{ciLintSonar}}
+        run: {{auditCommand}}
+{{ciLintSteps}}
       - name: format
         run: npm run format:check
       - name: typecheck
         run: npm run typecheck
+
+  test:
+    runs-on: ubuntu-latest
+    # Codecov OIDC authentication requires a job-scoped identity token.
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+{{> app/ci-workflows/install-steps.yml}}
       - name: unit
         run: npm test -- --ci
       - name: coverage proof
         run: {{ciCoverageProof}}
-      - name: coverage upload
-        uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5.5.5
-        if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') }}
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: always() && hashFiles('{{lcovReport}}') != ''
         with:
-          use_oidc: true
-          files: {{lcovReport}}
-          disable_search: true
-          fail_ci_if_error: true
+          name: {{lcovArtifact}}
+          path: {{lcovReport}}
+{{codecovSteps}}
+
+  build:
+    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
       - name: database migration checks
         run: {{ciDatabaseLint}}
-{{> app/ci-workflows/sonar-steps.yml}}
+
+{{sonarJob}}
 
   db-types:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
-        with:
-          node-version: {{nodeMajor}}
-          cache: npm
-      - run: npm ci --ignore-scripts
+{{> app/ci-workflows/install-steps.yml}}
       - name: start Supabase
         run: npm run db:start
       - name: apply migrations