@starci/hfs 4.7.23 → 4.7.24

package/sync/ci-commands.mjs

@@ -10,91 +10,30 @@ const exampleCommand = (source, command) => source?.runtimeExample
 
 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 != '' }}";
+const SONAR_CONDITION = "${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') }}";
 
-/** 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. */
+/** Codecov uploads on release tags with its required authentication; a missing report, an unavailable endpoint or a rejected upload fails the job. */
 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}`,
+    "        if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') }}",
     '        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)"',
-    ] : []),
+    '          fail_ci_if_error: true',
   ].join('\n');
 }
 
-/** Sonar consumes the test coverage and fast lint artifacts only on release tags with a configured token. */
+/** Sonar is required: on release tags it consumes the test coverage and lint artifacts, and a missing token fails the job with a clear refusal. */
 function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout) {
   if (!sonar) return '';
-  const condition = sonar.optional ? SONAR_CONDITION.replace(' }}', " && steps.sonar-availability.outputs.up == 'true' }}") : SONAR_CONDITION;
+  const condition = SONAR_CONDITION;
   const host = sonar.provider === 'sonarcloud' ? 'https://sonarcloud.io' : `\${{ vars.${sonar.hostVar} }}`;
   const header = [
     '  sonar:',
@@ -107,7 +46,10 @@ function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout) {
     '    steps:',
   ].join('\n');
   const steps = [
-    ...sonarProbe(sonar),
+    '      - name: Sonar token',
+    `        if: ${condition}`,
+    '        run: |',
+    `          if [ -z "$SONAR_TOKEN" ]; then echo "::error::SONAR_TOKEN is not set: Sonar is required, so a missing token fails this job (secret ${sonar.token})"; exit 1; fi`,
     `      - uses: ${DOWNLOAD_ARTIFACT}`,
     `        if: ${condition}`,
     '        with:',
@@ -208,12 +150,22 @@ function sonarMergeSteps(condition) {
 }
 
 const STANDARD = new URL('../runtime/knowledge/hfs/ci-standard.yaml', import.meta.url);
-/** The per-job settings of the managed CI: ci.jobs.<job>.timeoutMinutes and ci.jobs.test.shards of the manifest over the defaults of the CI standard. */
-function ciJobSettings(declaration) {
+/** jest --shard=i/N gives each shard ceil(specs / N) spec files in order, so shard N is empty unless (N - 1) * ceil(specs / N) < specs. */
+export function filledShards(specs, wanted) {
+  for (let shards = wanted; shards > 1; shards -= 1) if ((shards - 1) * Math.ceil(specs / shards) < specs) return shards;
+  return 1;
+}
+
+/** The unit specs of the be source: every *.spec.ts outside the test kind folders (src/tests/<kind>), the files the unit project runs. */
+const unitSpecCount = (source) => (source?.files ?? []).filter((file) => file.endsWith('.spec.ts') && !file.includes('/tests/')).length;
+
+/** The per-job settings of the managed CI: ci.jobs.<job>.timeoutMinutes and ci.jobs.test.shards of the manifest over the defaults of the CI standard, the shards capped at the count the unit specs fill (an empty shard would fail, never pass empty). */
+function ciJobSettings(declaration, source) {
   const { defaults, heap } = parseYaml(fs.readFileSync(STANDARD, 'utf8'));
   const jobs = declaration?.ci?.jobs ?? {};
   const timeout = (job) => String(jobs[job]?.timeoutMinutes ?? defaults.timeoutMinutes[job]);
-  const shards = Number(jobs.test?.shards ?? defaults.shards);
+  const wanted = Number(jobs.test?.shards ?? defaults.shards);
+  const shards = source?.files?.length ? filledShards(unitSpecCount(source), wanted) : wanted;
   return {
     nodeOptions: `--max-old-space-size=${heap.minMiB}`,
     timeoutFast: timeout('fast'), timeoutLint: timeout('lint'), timeoutTest: timeout('test'), timeoutCoverage: timeout('coverage'),
@@ -230,7 +182,7 @@ export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info',
   const audit = quality?.audit ?? { level: 'high', omitDev: true };
   const lcovArtifact = 'coverage-lcov';
   const build = frontendBuild(source, app);
-  const settings = ciJobSettings(buildDeclaration(source));
+  const settings = ciJobSettings(buildDeclaration(source), source);
   const side = '${{ matrix.side }}';
   return {
     ...settings,
@@ -247,28 +199,24 @@ export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info',
     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} }}` : '',
-    // One lint job per side (the lint matrix): with a Sonar token each side writes its own report, uploaded as sonar-lint-<side> and merged by the sonar job.
-    ciLintSteps: [
+    // One lint job per side (the lint matrix): with Sonar each side writes its own report, uploaded as sonar-lint-<side> and merged by the sonar job.
+    ciLintSteps: (sonar ? [
+      '      - name: lint with Sonar import',
+      `        run: ${exampleCommand(source, 'npm run lint -- --side ' + side + ' --sonar reports/lint.' + side + '.sonar.json')}`,
+      '        env:',
+      `          NODE_OPTIONS: ${settings.nodeOptions}`,
+      `      - uses: ${UPLOAD_ARTIFACT}`,
+      // Inside an if: expression the matrix value is an argument of format(), never a nested ${{ }} (actionlint: a nested expression makes the condition always true).
+      "        if: always() && hashFiles(format('reports/lint.{0}.sonar.json', matrix.side)) != ''",
+      '        with:',
+      `          name: sonar-lint-${side}`,
+      `          path: reports/lint.${side}.sonar.json`,
+    ] : [
       '      - name: lint',
-      ...(sonar ? ["        if: env.SONAR_TOKEN == ''"] : []),
       `        run: ${exampleCommand(source, 'npm run lint -- --side ' + side)}`,
       '        env:',
       `          NODE_OPTIONS: ${settings.nodeOptions}`,
-      ...(sonar ? [
-        '      - name: lint with Sonar import',
-        "        if: env.SONAR_TOKEN != ''",
-        `        run: ${exampleCommand(source, 'npm run lint -- --side ' + side + ' --sonar reports/lint.' + side + '.sonar.json')}`,
-        '        env:',
-        `          NODE_OPTIONS: ${settings.nodeOptions}`,
-        `      - uses: ${UPLOAD_ARTIFACT}`,
-        // Inside an if: expression the matrix value is an argument of format(), never a nested ${{ }} (actionlint: a nested expression makes the condition always true).
-        "        if: always() && env.SONAR_TOKEN != '' && hashFiles(format('reports/lint.{0}.sonar.json', matrix.side)) != ''",
-        '        with:',
-        `          name: sonar-lint-${side}`,
-        `          path: reports/lint.${side}.sonar.json`,
-      ] : []),
-    ].join('\n'),
+    ]).join('\n'),
     codecovSteps: codecovSteps(lcovReport, codecov),
     sonarJob: sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, settings.timeoutSonar),
     lcovArtifact,

package/sync/index.mjs

@@ -24,6 +24,7 @@ import { braceVariants } from '../runtime/scripts/lib/glob.mjs';
 import { codecovPaths, coverageComponents, jestCoverage, sonarCoverageExclusions } from '../runtime/scripts/hfs/coverage-scope.mjs';
 import { APP_SCOPE, SIDES, litePresenceOf, loadSlotManifest, resolveRepoDeclaration, slotInEdition } from '../runtime/scripts/hfs/slots.mjs';
 import { managedGroupOf } from '../runtime/scripts/hfs/edition-slots.mjs';
+import { declaredSlotEnabled } from '../runtime/scripts/hfs/declaration-slots.mjs';
 import { feAppPackageName } from '../runtime/scripts/hfs/rules/monorepo.mjs';
 import { DEFAULT_PORT, NODE_IMAGE, dockerfilePath } from '../runtime/scripts/hfs/rules/docker.mjs';
 import { isFile } from '../runtime/scripts/lib/fs-kind.mjs';
@@ -74,8 +75,10 @@ function managedTemplate(scope, group, file, hasTemplate) {
   return directories.map(dir => `${dir}/${group}/${file}`).find(name => hasTemplate(name));
 }
 
-function slotTargets(slot, scope, edition, manifest, hasTemplate) {
+function slotTargets(slot, scope, edition, manifest, hasTemplate, enabled) {
   if (!slot.profiles.includes(scope) || !slotInEdition(manifest, slot, edition)) return [];
+  // An opt-in slot is rendered only for a repository that enables it (app.browser-config with `browser: true`).
+  if (slot.presence === 'opt-in' && !enabled(slot)) return [];
   if (edition === 'lite' && litePresenceOf(slot, scope) === 'forbidden') return [];
   const group = managedGroupOf(slot, edition);
   if (group === undefined) return [];
@@ -100,10 +103,11 @@ function unlistedTargets(scope, edition) {
 /**
  * Every target of `scope` (app, be or fe), its path relative to that scope's folder: the files the manifest's managedBy slots
  * list, then (app root) the unlisted ones. A slot that names managedBy lists literal files only, and each has a template under
- * its scope or under common.
+ * its scope or under common. `enabled(slot)` decides an opt-in slot (renderTargets passes the declaration's); without it every slot
+ * counts, which is what an inventory of the templates needs.
  */
-export function targetsOf(scope, { edition = 'full', manifest = loadSlotManifest(), hasTemplate = name => fs.existsSync(path.join(TEMPLATES_DIR, name)) } = {}) {
-  const listed = manifest.slots.flatMap(slot => slotTargets(slot, scope, edition, manifest, hasTemplate));
+export function targetsOf(scope, { edition = 'full', manifest = loadSlotManifest(), hasTemplate = name => fs.existsSync(path.join(TEMPLATES_DIR, name)), enabled = () => true } = {}) {
+  const listed = manifest.slots.flatMap(slot => slotTargets(slot, scope, edition, manifest, hasTemplate, enabled));
   return [...listed, ...unlistedTargets(scope, edition)];
 }
 
@@ -389,7 +393,8 @@ 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 declaredTargets = targetsOf(scope, { edition: app.edition, manifest, hasTemplate });
+    const repo = scope === APP_SCOPE ? app : app.sides[scope];
+    const declaredTargets = targetsOf(scope, { edition: app.edition, manifest, hasTemplate, enabled: slot => declaredSlotEnabled(slot, repo) });
     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'));

package/templates/app/browser-config/browser/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@starci/tsconfig/e2e.json",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "types": ["node"]
+  },
+  "include": ["playwright.config.ts", "journeys/*.ts"]
+}

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

@@ -36,7 +36,6 @@ jobs:
   lint:
     timeout-minutes: {{timeoutLint}}
     runs-on: ubuntu-latest
-{{sonarEnv}}
     strategy:
       fail-fast: false
       matrix:
@@ -57,9 +56,9 @@ jobs:
 {{> app/ci-workflows/install-steps.yml}}
 {{> app/ci-workflows/jest-cache.yml}}
       # A shard (STARCI_COVERAGE_SHARD=1, the jest preset) measures only the files its specs load, without the per-file threshold, and writes istanbul
-      # JSON; the coverage job merges the shards by source location and proves 100 per file on the merged report. A small suite may leave a shard empty.
+      # JSON; the coverage job merges the shards by source location and proves 100 per file on the merged report. The shard count never exceeds what the unit specs fill.
       - name: unit
-        run: npm test -- --ci --forceExit --cacheDirectory .jest-cache --shard=${{ matrix.shard }}/{{testShardTotal}} --passWithNoTests --coverageThreshold={}
+        run: npm test -- --ci --forceExit --cacheDirectory .jest-cache --shard=${{ matrix.shard }}/{{testShardTotal}}
         env:
           STARCI_COVERAGE_SHARD: "1"
 {{> app/ci-workflows/jest-cache-save.yml}}

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

@@ -36,7 +36,6 @@ jobs:
   lint:
     timeout-minutes: {{timeoutLint}}
     runs-on: ubuntu-latest
-{{sonarEnv}}
     strategy:
       fail-fast: false
       matrix:
@@ -57,9 +56,9 @@ jobs:
 {{> app/ci-workflows/install-steps.yml}}
 {{> app/ci-workflows/jest-cache.yml}}
       # A shard (STARCI_COVERAGE_SHARD=1, the jest preset) measures only the files its specs load, without the per-file threshold, and writes istanbul
-      # JSON; the coverage job merges the shards by source location and proves 100 per file on the merged report. A small suite may leave a shard empty.
+      # JSON; the coverage job merges the shards by source location and proves 100 per file on the merged report. The shard count never exceeds what the unit specs fill.
       - name: unit
-        run: npm test -- --ci --forceExit --cacheDirectory .jest-cache --shard=${{ matrix.shard }}/{{testShardTotal}} --passWithNoTests --coverageThreshold={}
+        run: npm test -- --ci --forceExit --cacheDirectory .jest-cache --shard=${{ matrix.shard }}/{{testShardTotal}}
         env:
           STARCI_COVERAGE_SHARD: "1"
 {{> app/ci-workflows/jest-cache-save.yml}}

package/templates/app/hooks/husky/pre-push

@@ -21,8 +21,10 @@ refuse() {
 release_gate() {
   if [ -n "$gate" ]; then return 0; fi
   gate="no annotated tag v[0-9]* on HEAD $head"
-  for tag in $(git tag --points-at HEAD --list 'v[0-9]*' 2>/dev/null || true); do
-    if [ "$(git cat-file -t "refs/tags/$tag" 2>/dev/null || true)" != "tag" ]; then continue; fi
+  tags=$(git tag --points-at HEAD --list 'v[0-9]*' 2>/dev/null) || { gate="cannot list the tags of HEAD $head"; return 0; }
+  for tag in $tags; do
+    kind=$(git cat-file -t "refs/tags/$tag" 2>/dev/null) || continue
+    if [ "$kind" != "tag" ]; then continue; fi
     if [ ! -f "$record" ]; then gate="no L4 record $record"; continue; fi
     flat=$(tr -d ' \t\r\n' < "$record")
     case "$flat" in

package/templates/app/package-scripts/package.json

@@ -5,7 +5,6 @@
 {{> app/package-scripts/core.json}}
     "typecheck:tests": "tsc -p be/src/tests/tsconfig.json",
     "test": "cd be && jest --selectProjects unit --coverage",
-    "test:affected": "cd be && jest --selectProjects unit --passWithNoTests",
     "test:integration": "npm run typecheck:tests && cd be && jest --selectProjects integration",
     "test:e2e": "npm run typecheck:tests && cd be && jest --selectProjects e2e",
     "test:contract": "npm run typecheck:tests && cd be && jest --selectProjects contract",

package/templates/app/package-scripts-lite/package.json

@@ -5,7 +5,6 @@
 {{> app/package-scripts/core.json}}
     "typecheck:tests": "tsc -p be/src/tests/tsconfig.json",
     "test": "cd be && jest --selectProjects unit --coverage",
-    "test:affected": "cd be && jest --selectProjects unit --passWithNoTests",
     "test:integration": "npm run typecheck:tests && cd be && jest --selectProjects integration",
 {{> app/package-scripts/supabase.json}}
     "contract:emit": "{{appBinary}} emit"

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

@@ -137,18 +137,17 @@ k8s:
   reason: This starter declares Docker Swarm production; no Kubernetes environment is provisioned.
 ci:
   secrets:
-    - {name: SONAR_TOKEN, scope: repository, purpose: Sonar analysis token provisioned for this app, optional: true}
+    - {name: SONAR_TOKEN, scope: repository, purpose: Sonar analysis token provisioned for this app}
     - {name: SOPS_AGE_KEY, scope: environment, environment: production, purpose: Decrypt app members during deployment, optional: true}
     - {name: VPS_SSH_KEY, scope: environment, environment: production, purpose: Deployment SSH key, optional: true}
     - {name: VPS_KNOWN_HOSTS, scope: environment, environment: production, purpose: Pinned deployment SSH host keys, optional: true}
   vars:
-    - {name: SONAR_HOST_URL, scope: repository, value: "https://sonar.{{project}}.example.invalid", purpose: Documentation endpoint to replace with this app's public Sonar host, optional: true}
+    - {name: SONAR_HOST_URL, scope: repository, value: "https://sonar.{{project}}.example.invalid", purpose: Documentation endpoint to replace with this app's public Sonar host}
     - {name: VPS_HOST, scope: environment, environment: production, value: 203.0.113.10, purpose: Documentation deployment address to replace before use, optional: true}
     - {name: VPS_USER, scope: environment, environment: production, value: deploy, purpose: Documentation deployment user to replace before use, optional: true}
 services:
   sonar:
     provider: sonarqube
-    optional: true
     mode: local
     qualityGate: {{sonarGate}}
     host: {local: http://127.0.0.1:9000, public: "https://sonar.{{project}}.example.invalid"}
@@ -160,7 +159,7 @@ services:
     auth: token
     credentials: []
     projects: [{repository: "{{project}}", key: "{{project}}"}]
-    ci: {wiring: optional-follow-up, workflow: .github/workflows/ci.yml, token: SONAR_TOKEN, hostVar: SONAR_HOST_URL}
+    ci: {wiring: required, workflow: .github/workflows/ci.yml, token: SONAR_TOKEN, hostVar: SONAR_HOST_URL}
     ownerAction:
       needed: Provision this app's Sonar host and project, then set SONAR_TOKEN with starci app ci secret set and sync SONAR_HOST_URL.
       reason: A fresh app declares its quality service without fabricating credentials or a successful analysis.
@@ -172,7 +171,7 @@ services:
     target: 100
     components: auto
     required: true
-    ci: {wiring: optional-follow-up, workflow: .github/workflows/ci.yml}
+    ci: {wiring: required, workflow: .github/workflows/ci.yml}
     ownerAction: none
   dependabot:
     provider: github
@@ -199,5 +198,5 @@ services:
     host: {public: https://ghcr.io}
     auth: github-token
     projects: [{repository: "{{project}}", key: "{{project}}"}]
-    ci: {wiring: optional-follow-up}
+    ci: {wiring: required}
     ownerAction: none

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

@@ -182,18 +182,17 @@ k8s:
   reason: Lite production uses Docker Swarm with managed Supabase backing; Kubernetes belongs to a future full-edition deployment.
 ci:
   secrets:
-    - {name: SONAR_TOKEN, scope: repository, purpose: Sonar analysis token provisioned for this app, optional: true}
+    - {name: SONAR_TOKEN, scope: repository, purpose: Sonar analysis token provisioned for this app}
     - {name: SOPS_AGE_KEY, scope: environment, environment: production, purpose: Decrypt app members during deployment, optional: true}
     - {name: VPS_SSH_KEY, scope: environment, environment: production, purpose: Deployment SSH key, optional: true}
     - {name: VPS_KNOWN_HOSTS, scope: environment, environment: production, purpose: Pinned deployment SSH host keys, optional: true}
   vars:
-    - {name: SONAR_HOST_URL, scope: repository, value: "https://sonar.{{project}}.example.invalid", purpose: Documentation endpoint to replace with this app's public Sonar host, optional: true}
+    - {name: SONAR_HOST_URL, scope: repository, value: "https://sonar.{{project}}.example.invalid", purpose: Documentation endpoint to replace with this app's public Sonar host}
     - {name: VPS_HOST, scope: environment, environment: production, value: 203.0.113.10, purpose: Documentation deployment address to replace before use, optional: true}
     - {name: VPS_USER, scope: environment, environment: production, value: deploy, purpose: Documentation deployment user to replace before use, optional: true}
 services:
   sonar:
     provider: sonarqube
-    optional: true
     mode: local
     qualityGate: {{sonarGate}}
     host: {local: http://127.0.0.1:9000, public: "https://sonar.{{project}}.example.invalid"}
@@ -205,7 +204,7 @@ services:
     auth: token
     credentials: []
     projects: [{repository: "{{project}}", key: "{{project}}"}]
-    ci: {wiring: optional-follow-up, workflow: .github/workflows/ci.yml, token: SONAR_TOKEN, hostVar: SONAR_HOST_URL}
+    ci: {wiring: required, workflow: .github/workflows/ci.yml, token: SONAR_TOKEN, hostVar: SONAR_HOST_URL}
     ownerAction:
       needed: Provision this app's Sonar host and project, then set SONAR_TOKEN with starci app ci secret set and sync SONAR_HOST_URL.
       reason: A fresh app declares its quality service without fabricating credentials or a successful analysis.
@@ -217,7 +216,7 @@ services:
     target: 100
     components: auto
     required: true
-    ci: {wiring: optional-follow-up, workflow: .github/workflows/ci.yml}
+    ci: {wiring: required, workflow: .github/workflows/ci.yml}
     ownerAction: none
   dependabot:
     provider: github
@@ -244,5 +243,5 @@ services:
     host: {public: https://ghcr.io}
     auth: github-token
     projects: [{repository: "{{project}}", key: "{{project}}"}]
-    ci: {wiring: optional-follow-up}
+    ci: {wiring: required}
     ownerAction: none

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

@@ -32,24 +32,23 @@ k8s:
   reason: The upgrade establishes the full local stack first; deployment topology is selected separately.
 ci:
   secrets:
-    - {name: SONAR_TOKEN, scope: repository, purpose: Sonar analysis token provisioned for this app, optional: true}
+    - {name: SONAR_TOKEN, scope: repository, purpose: Sonar analysis token provisioned for this app}
     - {name: SOPS_AGE_KEY, scope: repository, purpose: Decrypt app members during deployment, optional: true}
     - {name: VPS_SSH_KEY, scope: repository, purpose: Deployment SSH key, optional: true}
     - {name: VPS_KNOWN_HOSTS, scope: repository, purpose: Pinned deployment SSH host keys, optional: true}
   vars:
-    - {name: SONAR_HOST_URL, scope: repository, value: "https://sonar.{{project}}.example.invalid", purpose: Documentation endpoint to replace with this app's public Sonar host, optional: true}
+    - {name: SONAR_HOST_URL, scope: repository, value: "https://sonar.{{project}}.example.invalid", purpose: Documentation endpoint to replace with this app's public Sonar host}
     - {name: VPS_HOST, scope: repository, value: 203.0.113.10, purpose: Documentation deployment address to replace before use, optional: true}
     - {name: VPS_USER, scope: repository, value: deploy, purpose: Documentation deployment user to replace before use, optional: true}
 services:
   sonar:
     provider: sonarqube
-    optional: true
     mode: disabled
     reason: Enable the repository's Sonar service when a host and project token are provisioned.
     qualityGate: starci-quality
     credentials: []
     projects: [{repository: "{{project}}", key: "{{project}}"}]
-    ci: {wiring: optional-follow-up, workflow: .github/workflows/ci.yml, token: SONAR_TOKEN, hostVar: SONAR_HOST_URL}
+    ci: {wiring: required, workflow: .github/workflows/ci.yml, token: SONAR_TOKEN, hostVar: SONAR_HOST_URL}
     ownerAction: none
   codecov:
     provider: codecov
@@ -59,7 +58,7 @@ services:
     target: 100
     components: auto
     required: true
-    ci: {wiring: optional-follow-up, workflow: .github/workflows/ci.yml}
+    ci: {wiring: required, workflow: .github/workflows/ci.yml}
     ownerAction: none
   dependabot:
     provider: github
@@ -86,5 +85,5 @@ services:
     host: {public: https://ghcr.io}
     auth: github-token
     projects: [{repository: "{{project}}", key: "{{project}}"}]
-    ci: {wiring: optional-follow-up}
+    ci: {wiring: required}
     ownerAction: none

package/templates/be/patterns/event-bus/platform/event-runner.service.spec.ts.tpl

@@ -13,6 +13,10 @@ import { readEnvelope } from "./event-envelope.policy"
 import { EventRunnerService } from "./event-runner.service"
 import type { EventSubscription, EventTransport, InboundMessage } from "./event-transport.port"
 
+/** Asymmetric matchers read as `unknown`: jest types them `any`, which may not flow into a property or a typed argument. */
+const anyOf = (type: unknown): unknown => expect.any(type)
+const objectLike = (shape: Record<string, unknown>): unknown => expect.objectContaining(shape)
+
 const AT = "2026-02-03T04:05:06.000Z"
 const NOW = new Date(AT).getTime()
 
@@ -169,7 +173,7 @@ describe("EventRunnerService", () => {
             await runner.receive(message({ value: JSON.stringify([1]) }))
 
             expect(handle).not.toHaveBeenCalled()
-            expect(logger.error).toHaveBeenCalledWith(EventBusLogEvent.MessageSkipped, expect.any(SyntaxError), {
+            expect(logger.error).toHaveBeenCalledWith(EventBusLogEvent.MessageSkipped, anyOf(SyntaxError), {
                 topic: "run-1.events.probe",
             })
             expect(logger.warn).toHaveBeenCalledTimes(1)
@@ -269,7 +273,7 @@ describe("EventRunnerService", () => {
             )
 
             expect(transport.wait).toHaveBeenCalledWith(800)
-            expect(handle).toHaveBeenCalledWith(expect.objectContaining({ attempt: 2 }))
+            expect(handle).toHaveBeenCalledWith(objectLike({ attempt: 2 }))
         })
 
         it("does not wait for a retry message whose backoff has passed", async () => {

package/templates/be/patterns/outbox/platform/outbox-relay.policy.spec.ts.tpl

@@ -9,6 +9,9 @@ import type { Logger } from "@modules/platform/logging"
 import { OutboxLogEvent } from "./outbox.log-events"
 import { OutboxRelayPolicy } from "./outbox-relay.policy"
 
+/** Asymmetric matchers read as `unknown`: jest types them `any`, which may not flow into a property or a typed argument. */
+const anyOf = (type: unknown): unknown => expect.any(type)
+
 interface Row {
     readonly id: string
 }
@@ -60,7 +63,7 @@ describe("OutboxRelayPolicy", () => {
             await expect(relay.relay()).resolves.toBe(2)
 
             expect(relay.deliver).toHaveBeenCalledWith(rows)
-            expect(relay.mark).toHaveBeenCalledWith(expect.any(Object), rows)
+            expect(relay.mark).toHaveBeenCalledWith(anyOf(Object), rows)
             expect(relay.mark).toHaveBeenCalledTimes(1)
             expect(first.commits).toBe(1)
             expect(second.commits).toBe(1)

package/templates/be/patterns/queues/platform/bullmq-queue-transport.client.spec.ts.tpl

@@ -7,6 +7,9 @@ import type { QueueOptions } from "./queue.options"
 import { ATTEMPTS, BACKOFF_MS, KEEP_COMPLETED_SECONDS } from "./queue.policy"
 import type { BullmqJob, BullmqQueue, BullmqWorker, QueueFactory } from "./queue-transport.port"
 
+/** Asymmetric matchers read as `unknown`: jest types them `any`, which may not flow into a property or a typed argument. */
+const anyOf = (type: unknown): unknown => expect.any(type)
+
 const options: QueueOptions = {
     redisHost: "redis.test",
     redisPort: 6380,
@@ -83,14 +86,14 @@ describe("BullmqQueueTransportClient", () => {
 
         await client.work(handler, 3)
 
-        expect(factory.worker).toHaveBeenCalledWith("orders", expect.any(Function), {
+        expect(factory.worker).toHaveBeenCalledWith("orders", anyOf(Function), {
             prefix: "spec.",
             connection: { host: "redis.test", port: 6380, db: 7, maxRetriesPerRequest: null },
             concurrency: 3,
         })
         const processor = factory.worker.mock.calls[0]?.[1]
         await processor?.(mock<BullmqJob>({ id: "job-1", data: { orderId: "order-1" }, attemptsMade: 2 }))
-        await processor?.(mock<BullmqJob>({ id: undefined, data: { orderId: "order-2" }, attemptsMade: 0 }))
+        await processor?.({ data: { orderId: "order-2" }, attemptsMade: 0 } satisfies BullmqJob)
 
         expect(handler.handle).toHaveBeenNthCalledWith(1, {
             id: "job-1",

package/templates/be/patterns/realtime/channel.websocket.module.ts.tpl

@@ -70,7 +70,7 @@ export class @@Channel@@WebsocketModule extends ConfigurableModuleClass implemen
     }
 
     private async authenticate(client: @@Channel@@Socket): Promise<void> {
-        client.data.principal = undefined
+        delete client.data.principal
         const token = client.handshake.auth.accessToken
         if (typeof token !== "string" || token.length === 0) throw new Error("Unauthorized")
         const verified = await this.verifyAccessToken(token)

package/templates/be/patterns/saga/saga.service.spec.ts.tpl

@@ -7,6 +7,9 @@ import { @@Step@@Compensation } from "./compensations/@@step@@.compensation"
 import { @@Saga@@SagaService } from "./@@saga@@.saga.service"
 import { @@Step@@Step } from "./steps/@@step@@.saga-step"
 
+/** Asymmetric matchers read as `unknown`: jest types them `any`, which may not flow into a property or a typed argument. */
+const anyOf = (type: unknown): unknown => expect.any(type)
+
 const build = async () => {
     const sagas = mock<SagaService>()
     const compensation = mock<@@Step@@Compensation>()
@@ -33,7 +36,7 @@ describe("@@Saga@@SagaService", () => {
                 saga: @@sagaUpper@@_SAGA,
                 correlationId: "x-1",
                 eventId: "e-1",
-                step: expect.any(@@Step@@Step),
+                step: anyOf(@@Step@@Step),
                 compensation,
             })
         })

package/templates/be/platform/errors-graphql/graphql-error.mapper.ts

@@ -16,16 +16,16 @@ export const formatGraphqlError = (
     if (error instanceof GraphQLError && error.originalError === undefined) {
         return {
             message: formatted.message,
-            locations: formatted.locations,
-            path: formatted.path,
+            ...(formatted.locations === undefined ? {} : { locations: formatted.locations }),
+            ...(formatted.path === undefined ? {} : { path: formatted.path }),
             extensions: { kind: "invalid" },
         }
     }
     const description = errors.describe(error instanceof GraphQLError ? error.originalError : error)
     return {
         message: description.code,
-        locations: formatted.locations,
-        path: formatted.path,
+        ...(formatted.locations === undefined ? {} : { locations: formatted.locations }),
+        ...(formatted.path === undefined ? {} : { path: formatted.path }),
         extensions: { code: description.code, kind: description.kind, params: description.params },
     }
 }

package/templates/be/platform/graphql/localize-errors.mapper.spec.ts

@@ -8,7 +8,7 @@ import type { GraphqlContext } from "./graphql.contracts"
 import { localizeError, localizeErrorsPlugin } from "./localize-errors.mapper"
 
 const singleResponse = (errors?: ReadonlyArray<GraphQLFormattedError>): GraphQLResponse =>
-    mock<GraphQLResponse>({ body: { kind: "single", singleResult: { errors } } })
+    mock<GraphQLResponse>({ body: { kind: "single", singleResult: errors === undefined ? {} : { errors } } })
 
 const requestContext = (
     response: GraphQLResponse,

package/templates/be/skeleton/src/modules/domain/identity/admission.policy.spec.ts

@@ -6,10 +6,14 @@ import { PublicReason } from "./identity.contracts"
 
 const ADMISSION: unique symbol = Symbol("identity.admission")
 
+/** A record is read as metadata whatever its fields: the admission under test is what judges the reason. */
+const isMetadata = (value: unknown): value is PublicMetadata => typeof value === "object" && value !== null
+
 const runtimeMetadata = (source: string): PublicMetadata => {
     try {
-        const metadata: PublicMetadata = JSON.parse(source)
-        return metadata
+        const parsed: unknown = JSON.parse(source)
+        if (!isMetadata(parsed)) throw new IdentityError({ code: IdentityErrorCode.Unauthenticated })
+        return parsed
     } catch (cause) {
         throw new IdentityError({ code: IdentityErrorCode.Unauthenticated, cause })
     }