@starci/hfs 4.4.1 → 4.5.1

package/sync/ci-commands.mjs

@@ -1,13 +1,217 @@
+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
   ? 'node node_modules/@starci/hfs/runtime/scripts/hfs/example-secrets.mjs --run . -- ' + command
   : command;
 
-export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info') {
+const UPLOAD_ARTIFACT = 'actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2';
+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: ${uploadCondition}`,
+    '        with:',
+    codecov.auth === 'token' ? `          token: \${{ secrets.${codecov.token} }}` : '          use_oidc: true',
+    `          files: ${lcovReport}`,
+    '          disable_search: 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: ${host}`,
+    '    steps:',
+  ].join('\n');
+  const steps = [
+    ...sonarProbe(sonar),
+    `      - uses: ${DOWNLOAD_ARTIFACT}`,
+    `        if: ${condition}`,
+    '        with:',
+    `          name: ${lcovArtifact}`,
+    `          path: ${lcovReport.split('/').slice(0, -1).join('/') || '.'}`,
+    `      - uses: ${DOWNLOAD_ARTIFACT}`,
+    `        if: ${condition}`,
+    '        with:',
+    '          name: sonar-lint',
+    '          path: reports',
+    '      - uses: SonarSource/sonarqube-scan-action@c7ee0f9df90b7aa20e8dcf9695dcfe2e7da5b4f2 # v7.2.1',
+    `        if: ${condition}`,
+    '      - uses: SonarSource/sonarqube-quality-gate-action@7a5fffe8e523c40e0c740b6bc2712ab503e52efa # v1.2.1',
+    `        if: ${condition}`,
+    '        timeout-minutes: 10',
+  ].join('\n');
+  // Variable strings are inserted after render() expands partials, so resolve Sonar's shared install partial before insertion.
+  const read = name => fs.readFileSync(new URL('../templates/app/ci-workflows/' + name, import.meta.url), 'utf8').replaceAll('\r\n', '\n');
+  return read('sonar-steps.yml')
+    .replace('{{> app/ci-workflows/install-steps.yml}}', () => read('install-steps.yml').trimEnd())
+    .replaceAll('{{nodeMajor}}', nodeMajor)
+    .replace('{{sonarJobHeader}}', () => header)
+    .replace('{{sonarJobSteps}}', () => steps)
+    .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;
+  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';
   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),
     ciDatabaseLint: exampleCommand(source, 'npm run db:lint'),
+    auditCommand: `npm audit${audit.omitDev ? ' --omit=dev' : ''} --audit-level=${audit.level}`,
+    sonarTokenSecret: sonar?.token ?? 'SONAR_TOKEN',
+    sonarHostVar: sonar?.hostVar ?? 'SONAR_HOST_URL',
+    sonarEnv: sonar ? `    env:\n      SONAR_TOKEN: \${{ secrets.${sonar.token} }}` : '',
+    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',
+      ]),
+      ...(sonar ? [
+        '      - name: lint with Sonar import',
+        "        if: env.SONAR_TOKEN != ''",
+        `        run: ${exampleCommand(source, 'npm run lint -- --sonar reports/lint.sonar.json')}`,
+        '        env:',
+        '          NODE_OPTIONS: --max-old-space-size=6144',
+        `      - uses: ${UPLOAD_ARTIFACT}`,
+        "        if: always() && env.SONAR_TOKEN != '' && hashFiles('reports/lint.sonar.json') != ''",
+        '        with:',
+        '          name: sonar-lint',
+        '          path: reports/lint.sonar.json',
+      ] : []),
+    ].join('\n'),
+    codecovSteps: codecovSteps(lcovReport, codecov),
+    sonarJob: sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor),
+    lcovArtifact,
   };
 }

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,23 @@ 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 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) };
     });
   });
 }
 
 // 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 +413,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 +421,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 +439,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 +480,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,51 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  ci:
+  fast:
+    timeout-minutes: 20
     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}}
+{{> app/ci-workflows/lint-base.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:
+    timeout-minutes: 45
+    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}}
+{{> 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}}
-      - 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:
+    timeout-minutes: 30
+    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}}
+{{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