@starci/hfs 4.5.0 → 4.6.0

package/runtime/scripts/hfs/rules/secrets.mjs

@@ -7,7 +7,7 @@
 // A finding names the file, the line and the pattern, never the value.
 import fs from 'node:fs';
 import path from 'node:path';
-import { FORBIDDEN_FILES, secretHits } from '../../lib/secret-patterns.mjs';
+import { FORBIDDEN_FILES, secretHitsInFile } from '../../lib/secret-patterns.mjs';
 import { isSopsEnvelope } from '../../lib/sops-envelope.mjs';
 import { found, readText } from './read.mjs';
 
@@ -34,20 +34,17 @@ export function untrackedSecretFindings({ repoRoot, files, repo }) {
  * no sops envelope, or a line that matches a secret pattern. `text` is the file's text, or null when it cannot be read (binary, too
  * large, absent). The whole-tree check reads the work tree and the commit hook (`starci app hygiene`) reads the staged blob: one judgement.
  */
-export function secretFileFindings({ file, text }) {
+export function secretFileFindings({ file, text, manifestText }) {
   const being = FORBIDDEN_FILES.find((rule) => rule.test(file));
   if (being) return [found(PLAINTEXT_SECRET, file, `${file} is a plaintext secret by being (${being.name}); a secret is committed only as a sops envelope at .starcistacks/<env>/secrets/<slug>.enc`, { pattern: being.name })];
   if (text === null || text === undefined || NOT_SCANNED.test(file)) return [];
   if (file.endsWith('.enc')) return isSopsEnvelope(text) ? [] : [found(PLAINTEXT_SECRET, file, `${file} is named like a sealed secret but is not a sops envelope; encrypt the value with sops and commit only the envelope`, { pattern: 'sops-not-envelope' })];
   const findings = [];
-  const lines = text.split(/\r?\n/);
   const seen = new Set();
-  for (const [index, line] of lines.entries()) {
-    for (const pattern of secretHits(file, line)) {
-      if (seen.has(pattern)) continue;
-      seen.add(pattern);
-      findings.push(found(PLAINTEXT_SECRET, file, `${file}:${index + 1} holds a plaintext secret (${pattern}); seal it with sops at .starcistacks/<env>/secrets/<slug>.enc and read it by *_FILE`, { line: index + 1, pattern }));
-    }
+  for (const { line, pattern } of secretHitsInFile(file, text, { manifestText })) {
+    if (seen.has(pattern)) continue;
+    seen.add(pattern);
+    findings.push(found(PLAINTEXT_SECRET, file, `${file}:${line} holds a plaintext secret (${pattern}); seal it with sops at .starcistacks/<env>/secrets/<slug>.enc and read it by *_FILE`, { line, pattern }));
   }
   return findings;
 }
@@ -62,7 +59,8 @@ export function secretFindings({ repoRoot, files, resolver }) {
       findings.push(found(PLAINTEXT_SECRET, file, `${file} is a plaintext secret file tracked in ${slot.slot}${destination}`, { slot: slot.slot, goesTo: slot.goesTo }));
       continue;
     }
-    findings.push(...secretFileFindings({ file, text: readText(repoRoot, file) }));
+    const manifestText = /(?:^|\/)README\.md$/.test(file) ? readText(repoRoot, path.posix.join(path.posix.dirname(file), '.starcistacks/application-stacks.yaml')) : undefined;
+    findings.push(...secretFileFindings({ file, text: readText(repoRoot, file), manifestText }));
   }
   return findings;
 }

package/runtime/scripts/lib/secret-patterns.mjs

@@ -1,3 +1,5 @@
+import { parseYaml } from '../../engine/yaml.mjs';
+
 // secret-patterns.mjs — the one list of secret shapes the runtime refuses to carry: the push secret scan
 // (scripts/supervisor/push-mains.mjs scanDiff) refuses an outgoing range that adds one, and the typed-log
 // redaction (scripts/kernel/typed-logs.mjs redactText) blanks the value before a log row is stored.
@@ -102,3 +104,78 @@ export function secretHits(file, text) {
   }
   return names;
 }
+
+const BADGE_BEGIN = '<!-- >>> starci app sync (managed block; do not edit) >>> -->';
+const BADGE_END = '<!-- <<< starci app sync <<< -->';
+
+/** Provider-shaped credentials remain refused even where the keyword heuristic admits public badge tokens. */
+function blankBadgeValue(value) {
+  return secretHits('badge.mjs', value).length ? value : ' '.repeat(value.length);
+}
+
+/** Only scalar values at the two block-mapping service paths qualify; every other YAML substring remains scanned. */
+function manifestBadgeText(text) {
+  try { parseYaml(text); } catch { return text; }
+  const parents = [];
+  return text.split('\n').map(line => {
+    if (/^\s*(?:#.*)?$/.test(line)) return line;
+    const indent = /^ */.exec(line)[0].length;
+    while (parents.length && parents.at(-1).indent >= indent) parents.pop();
+    const match = /^( *)(?:([A-Za-z0-9_-]+)|"([A-Za-z0-9_-]+)"|'([A-Za-z0-9_-]+)'):(.*)$/.exec(line);
+    if (!match) { parents.push({ indent, key: null }); return line; }
+    match[5] = match[5].trimStart();
+    const key = match[2] ?? match[3] ?? match[4];
+    const keys = [...parents.map(parent => parent.key), key].join('.');
+    const container = /^(?:#.*)?$/.test(match[5].trim());
+    const nestedScalar = parents.some(parent => parent.container === false);
+    parents.push({ indent, key, container });
+    if (nestedScalar) return line;
+    if (!['services.codecov.badgeToken', 'services.sonar.badgeToken'].includes(keys)) return line;
+    const scalar = /^(?:"([A-Za-z0-9_-]{6,128})"|'([A-Za-z0-9_-]{6,128})'|([A-Za-z0-9_-]{6,128}))(?=\s*(?:#|$))/.exec(match[5]);
+    if (!scalar) return line;
+    const start = line.length - match[5].length;
+    return line.slice(0, start) + blankBadgeValue(scalar[0]) + match[5].slice(scalar[0].length);
+  }).join('\n');
+}
+
+/** Unreadable manifests admit only the default badge hosts; readable Sonar declarations select their own hosts. */
+function badgeHosts(manifestText) {
+  const hosts = new Set(['codecov.io']);
+  let doc;
+  try { doc = parseYaml(manifestText); } catch { hosts.add('sonarcloud.io'); return hosts; }
+  const sonar = doc?.services?.sonar;
+  if (sonar?.provider === 'sonarcloud') hosts.add('sonarcloud.io');
+  else for (const host of [sonar?.host?.public, sonar?.host?.local]) {
+    try { hosts.add(new URL(host).host); } catch { /* Invalid hosts admit nothing. */ }
+  }
+  return hosts;
+}
+
+/** Only token query values in managed Markdown badge images on declared hosts are blanked; links and other parameters remain scanned. */
+function readmeBadgeText(text, manifestText) {
+  const begin = text.indexOf(BADGE_BEGIN), end = text.indexOf(BADGE_END, begin + BADGE_BEGIN.length);
+  if (begin < 0 || end < 0) return text;
+  const hosts = badgeHosts(manifestText);
+  const start = begin + BADGE_BEGIN.length;
+  const block = text.slice(start, end).replace(/!\[[^\]\n]*\]\((https?:\/\/[^\s)]+)\)/g, (image, address) => {
+    let url;
+    try { url = new URL(address); } catch { return image; }
+    if (!hosts.has(url.host) || url.username || url.password) return image;
+    const badgePath = url.host === 'codecov.io' ? /\/graph\/badge\.svg$/.test(url.pathname) : url.pathname === '/api/project_badges/measure';
+    if (!badgePath) return image;
+    const fragment = address.indexOf('#');
+    const queryEnd = fragment < 0 ? address.length : fragment;
+    const safe = address.slice(0, queryEnd).replace(/([?&]token=)([^&#)\s]*)/g, (_, prefix, value) => prefix + blankBadgeValue(value));
+    return image.replace(address, () => safe + address.slice(queryEnd));
+  });
+  return text.slice(0, start) + block + text.slice(end);
+}
+
+/** Whole-file secret judgement exempts only declared public badge values and preserves original line numbers and every provider shape. */
+export function secretHitsInFile(file, fullText, { manifestText } = {}) {
+  const normalized = file.replace(/\\/g, '/');
+  let text = fullText;
+  if (/(?:^|\/)\.starcistacks\/application-stacks\.yaml$/.test(normalized)) text = manifestBadgeText(text);
+  if (/(?:^|\/)README\.md$/.test(normalized)) text = readmeBadgeText(text, manifestText);
+  return text.split(/\r?\n/).flatMap((line, index) => secretHits(file, line).map(pattern => ({ line: index + 1, pattern })));
+}

package/scaffold/app.mjs

@@ -222,7 +222,7 @@ const FE_PACKAGES = Object.freeze({
 const PACKAGE_WORKSPACE_SCRIPTS = Object.freeze({ build: 'tsc -p tsconfig.build.json', lint: WORKSPACE_LINT, typecheck: 'tsc --noEmit -p tsconfig.json' });
 
 /** The app hfs.json of a new app called `name`; full remains the byte-for-byte default declaration. */
-const starterDeclaration = (name, manifest = loadSlotManifest(), edition = 'full') => ({
+export const starterDeclaration = (name, manifest = loadSlotManifest(), edition = 'full') => ({
   hfs: manifest.major,
   kind: 'app',
   ...(edition === 'full' ? {} : { edition }),
@@ -493,7 +493,7 @@ export function scaffoldWorkSeeds(project) {
  * be side (once per product app of the fe side, coreFeApps), the be `apps/cli/` folder once when the cli app is declared, an fe `apps/<name>/` folder
  * once for the declared fe app <name> (none other), `__project__` in a path replaced by the project name.
  */
-function skeletonOf(scope, app, vars) {
+export function skeletonOf(scope, app, vars) {
   const files = app.edition === 'lite'
     ? [...skeletonDirectory(scope, 'skeleton', app, vars, rel => liteBaseFile(scope, rel)), ...skeletonDirectory(scope, 'skeleton-lite', app, vars, rel => liteOverlayFile(scope, rel))]
     : skeletonDirectory(scope, 'skeleton', app, vars);

package/sync/ci-commands.mjs

@@ -1,4 +1,7 @@
 import fs from 'node:fs';
+import { parseYaml } from '../runtime/engine/yaml.mjs';
+import { refusal } from '../stack/errors.mjs';
+import { byCodeUnit } from '../report/order.mjs';
 
 // One command vocabulary for managed CI rendering and the runtime coverage gate.
 const exampleCommand = (source, command) => source?.runtimeExample
@@ -9,56 +12,116 @@ const UPLOAD_ARTIFACT = 'actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f
 const DOWNLOAD_ARTIFACT = 'actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0';
 const SONAR_CONDITION = "${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') && env.SONAR_TOKEN != '' }}";
 
+/** Optional uploads require reachable upload and authentication endpoints without exposing identity tokens. */
+function codecovProbe(codecov, condition) {
+  if (!codecov.optional) return [];
+  return [
+    '      - name: Codecov availability',
+    '        id: codecov-availability',
+    `        if: ${condition}`,
+    '        env:',
+    `          CODECOV_AUTH: ${codecov.auth}`,
+    '        run: |',
+    "          node --input-type=module <<'NODE'",
+    "          import fs from 'node:fs';",
+    '          let available = false;',
+    '          try {',
+    "            const upload = await fetch('https://ingest.codecov.io/upload/v4', { signal: AbortSignal.timeout(10000) });",
+    '            available = upload.status < 500;',
+    "            if (available && process.env.CODECOV_AUTH === 'oidc') {",
+    "              const url = new URL(process.env.ACTIONS_ID_TOKEN_REQUEST_URL);",
+    "              url.searchParams.set('audience', 'https://codecov.io');",
+    "              const identity = await fetch(url, { headers: { Authorization: 'Bearer ' + process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN }, signal: AbortSignal.timeout(10000) });",
+    '              available = identity.ok && Boolean((await identity.json()).value);',
+    '            }',
+    '          } catch { available = false; }',
+    "          fs.appendFileSync(process.env.GITHUB_OUTPUT, 'up=' + available + '\\n');",
+    "          if (!available) console.log('::notice::codecov upload skipped: upload endpoint or OIDC token unavailable (services.codecov.optional)');",
+    '          NODE',
+  ];
+}
+
+/** Optional Sonar only runs analysis when the provider reports UP within ten seconds. */
+function sonarProbe(sonar) {
+  if (!sonar.optional) return [];
+  return [
+    '      - name: Sonar availability',
+    '        id: sonar-availability',
+    `        if: ${SONAR_CONDITION}`,
+    '        run: |',
+    `          if curl -fsS --max-time 10 "$SONAR_HOST_URL/api/system/status" | node -e "let s='';process.stdin.on('data',c=>s+=c);process.stdin.on('end',()=>{try{process.exit(JSON.parse(s).status==='UP'?0:1)}catch{process.exit(1)}})"; then`,
+    '            echo "up=true" >> "$GITHUB_OUTPUT"',
+    '          else',
+    '            echo "up=false" >> "$GITHUB_OUTPUT"',
+    '            echo "::notice::sonar skipped: $SONAR_HOST_URL not reachable (services.sonar.optional)"',
+    '          fi',
+  ];
+}
+
 /** Codecov reports missing coverage without failing twice; uploads retain the release-tag condition and required authentication. */
 function codecovSteps(lcovReport, codecov) {
   if (codecov.enabled === false || codecov.wiring === 'not-used') return [
     '      - name: coverage upload',
     '        run: echo "codecov disabled in .starcistacks/application-stacks.yaml"',
   ].join('\n');
+  const condition = `\${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') && hashFiles('${lcovReport}') != '' }}`;
+  const uploadCondition = codecov.optional ? condition.replace(' }}', " && steps.codecov-availability.outputs.up == 'true' }}") : condition;
   return [
     '      - name: coverage upload skipped',
     `        if: \${{ !cancelled() && hashFiles('${lcovReport}') == '' }}`,
     '        run: |',
     `          echo "::notice::codecov upload skipped: no coverage file at ${lcovReport} (the test step failed or produced none)"`,
     '          exit 0',
+    ...codecovProbe(codecov, condition),
     '      - name: coverage upload',
+    ...(codecov.optional ? ['        id: codecov-upload', '        continue-on-error: true'] : []),
     '        uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5.5.5',
-    `        if: \${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') && hashFiles('${lcovReport}') != '' }}`,
+    `        if: ${uploadCondition}`,
     '        with:',
     codecov.auth === 'token' ? `          token: \${{ secrets.${codecov.token} }}` : '          use_oidc: true',
     `          files: ${lcovReport}`,
     '          disable_search: true',
-    '          fail_ci_if_error: true',
+    `          fail_ci_if_error: ${!codecov.optional}`,
+    ...(codecov.optional ? [
+      '      - name: Codecov upload unavailable',
+      "        if: ${{ !cancelled() && steps.codecov-upload.outcome == 'failure' }}",
+      '        run: |',
+      '          echo "::notice::codecov upload skipped: upload unavailable (services.codecov.optional)"',
+    ] : []),
   ].join('\n');
 }
 
 /** Sonar consumes the test coverage and fast lint artifacts only on release tags with a configured token. */
 function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor) {
   if (!sonar) return '';
+  const condition = sonar.optional ? SONAR_CONDITION.replace(' }}', " && steps.sonar-availability.outputs.up == 'true' }}") : SONAR_CONDITION;
+  const host = sonar.provider === 'sonarcloud' ? 'https://sonarcloud.io' : `\${{ vars.${sonar.hostVar} }}`;
   const header = [
     '  sonar:',
     '    needs: [fast, test]',
+    '    timeout-minutes: 20',
     '    runs-on: ubuntu-latest',
     '    env:',
     `      SONAR_TOKEN: \${{ secrets.${sonar.token} }}`,
-    `      SONAR_HOST_URL: \${{ vars.${sonar.hostVar} }}`,
+    `      SONAR_HOST_URL: ${host}`,
     '    steps:',
   ].join('\n');
   const steps = [
+    ...sonarProbe(sonar),
     `      - uses: ${DOWNLOAD_ARTIFACT}`,
-    `        if: ${SONAR_CONDITION}`,
+    `        if: ${condition}`,
     '        with:',
     `          name: ${lcovArtifact}`,
     `          path: ${lcovReport.split('/').slice(0, -1).join('/') || '.'}`,
     `      - uses: ${DOWNLOAD_ARTIFACT}`,
-    `        if: ${SONAR_CONDITION}`,
+    `        if: ${condition}`,
     '        with:',
     '          name: sonar-lint',
     '          path: reports',
     '      - uses: SonarSource/sonarqube-scan-action@c7ee0f9df90b7aa20e8dcf9695dcfe2e7da5b4f2 # v7.2.1',
-    `        if: ${SONAR_CONDITION}`,
+    `        if: ${condition}`,
     '      - uses: SonarSource/sonarqube-quality-gate-action@7a5fffe8e523c40e0c740b6bc2712ab503e52efa # v1.2.1',
-    `        if: ${SONAR_CONDITION}`,
+    `        if: ${condition}`,
     '        timeout-minutes: 10',
   ].join('\n');
   // Variable strings are inserted after render() expands partials, so resolve Sonar's shared install partial before insertion.
@@ -68,17 +131,91 @@ 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. */
+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);
+  }
+}
+
+/** 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 = 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 ?? [];
+  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 };
+}
+
+/** Side lint reports join into the single Sonar artifact even when one side could not write its report. */
+function sonarMergeSteps() {
+  return [
+    '      - name: merge Sonar lint reports',
+    "        if: always() && env.SONAR_TOKEN != ''",
+    '        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',
+  ];
 }
 
 /** 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);
   return {
+    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),
@@ -96,11 +233,14 @@ export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info',
         '          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',
+        ...['be', 'fe'].flatMap((side) => [
+          '      - name: lint ' + side + ' with Sonar import',
+          "        if: env.SONAR_TOKEN != ''",
+          `        run: ${exampleCommand(source, 'npm run lint -- --side ' + side + ' --sonar reports/lint.' + side + '.sonar.json')}`,
+          '        env:',
+          '          NODE_OPTIONS: --max-old-space-size=6144',
+        ]),
+        ...sonarMergeSteps(),
         `      - uses: ${UPLOAD_ARTIFACT}`,
         "        if: always() && env.SONAR_TOKEN != '' && hashFiles('reports/lint.sonar.json') != ''",
         '        with:',

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

@@ -16,10 +16,12 @@ concurrency:
 
 jobs:
   fast:
+    timeout-minutes: 20
     runs-on: ubuntu-latest
 {{sonarEnv}}
     steps:
 {{> app/ci-workflows/install-steps.yml}}
+{{> app/ci-workflows/lint-base.yml}}
       - name: production dependency audit
         run: {{auditCommand}}
 {{ciLintSteps}}
@@ -29,6 +31,7 @@ jobs:
         run: npm run typecheck
 
   test:
+    timeout-minutes: 45
     runs-on: ubuntu-latest
     # Codecov OIDC authentication requires a job-scoped identity token.
     permissions:
@@ -36,10 +39,13 @@ jobs:
       id-token: write
     steps:
 {{> app/ci-workflows/install-steps.yml}}
+{{> app/ci-workflows/jest-cache.yml}}
       - name: unit
-        run: npm test -- --ci
+        run: npm test -- --ci --forceExit --cacheDirectory .jest-cache
       - name: coverage proof
         run: {{ciCoverageProof}}
+        env:
+          NODE_OPTIONS: --max-old-space-size=6144
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         if: always() && hashFiles('{{lcovReport}}') != ''
         with:
@@ -48,12 +54,12 @@ jobs:
 {{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
+{{ciBuildSteps}}
 
 {{sonarJob}}