@starci/hfs 4.6.0 → 4.7.0

package/scaffold/app.mjs

@@ -300,9 +300,10 @@ export function peerDependencies(pkg, pins, pairs = parseYaml(fs.readFileSync(PE
 /**
  * The fe-stack core packages one version of which the whole install resolves (npm `overrides`, at their canon pins): a
  * transitive dependency otherwise brings its own (zustand 4 under @xyflow/react, dayjs under typeorm, a hoisted newer zod
- * that breaks the zodResolver types), and @xyflow/react itself stays the grammar's one version.
+ * that breaks the zodResolver types), and @xyflow/react itself stays the grammar's one version. @graphql-tools/utils is the one security override: @nestjs/graphql 13.x
+ * pulls <=12.0.0 (GHSA-7mx3-vvmw-hjmv), and the pin's fixed 12.x closes the advisory until @nestjs/graphql 14 is adopted (then drop it; canon-pins.yaml says why).
  */
-const ROOT_OVERRIDES = Object.freeze(['@xyflow/react', 'dayjs', 'zod', 'zustand']);
+const ROOT_OVERRIDES = Object.freeze(['@graphql-tools/utils', '@xyflow/react', 'dayjs', 'zod', 'zustand']);
 
 /**
  * The root package.json of a new app, the monorepo root: name, workspaces, npm, its edition's dependencies with their runtime

package/src/main.mjs

@@ -29,6 +29,7 @@
 //   starci app sync (--check | --write) [--cwd <dir>]  the managed files of the root (scripts, husky, CI, .gitignore block, sonar, prettier) and
 //                                            of each side (tsconfig, eslint, jest, stylelint); sync/cli.mjs
 //   starci app hygiene                             the pre-commit guard: staged .starciwork and .starcistacks paths, and the secrets guard over every staged file (read from the index); sync/cli.mjs
+//   starci app coverage merge --out <lcov> <lcov-or-dir>...  the lcov reports of the sharded unit run merged into one (coverage/cli.mjs; the managed CI coverage job)
 //   starci app new service <dir> <name> [--inject <Decorator>=<module>:<Type> | <Class>=<module>]... [--cwd <dir>]
 //                                            a back-end `<name>.service.ts` and its `<name>.service.spec.ts` skeleton (scaffold/service.mjs; <dir> is
 //                                            relative to be/): the spec is built
@@ -89,7 +90,7 @@ import { dbPostCutoverMain } from '../db/post-cutover.mjs';
 import { dbDumpMain } from '../db/dump.mjs';
 import { dbResetMain } from '../db/reset.mjs';
 
-export const VERBS = Object.freeze(['scaffold', 'add', 'lint', 'sync', 'check', 'upgrade', 'stack', 'release', 'explain', 'emit', 'new', 'secret', 'ci', 'db', 'hygiene']);
+export const VERBS = Object.freeze(['scaffold', 'add', 'lint', 'sync', 'check', 'upgrade', 'stack', 'release', 'explain', 'emit', 'new', 'secret', 'ci', 'db', 'hygiene', 'coverage']);
 const DATABASE_VERBS = new Map([['baseline', dbBaselineMain], ['restamp', dbRestampMain], ['plan', dbPlanMain], ['migrate', dbMigrateMain], ['post-cutover', dbPostCutoverMain], ['dump', dbDumpMain], ['reset', dbResetMain]]);
 
 const USAGE = `starci app scaffold <name> [--into <dir>] [--edition full|lite] [--registry-visibility public|private] [--cwd <dir>]
@@ -128,6 +129,7 @@ starci app ci var set <NAME> [--env E] [--value v] [--repo owner/name] [--cwd <d
 starci app ci var sync [--execute] [--repo owner/name] [--cwd <dir>]
 starci app ci verify [--json] [--repo owner/name] [--cwd <dir>]
 starci app hygiene [--cwd <dir>]
+starci app coverage merge --out <lcov> <lcov-or-dir>... [--cwd <dir>]
 `;
 const PER_CODE_LIMIT = 25;
 const VALUE_FLAGS = new Set(['--base', '--inject', '--into', '--event', '--from', '--service', '--connection', '--owner', '--failed', '--done', '--coverage-from', '--registry-visibility']);
@@ -419,7 +421,7 @@ async function stackAppMain(argv, { cwd, edition, stackMain, stdout: out, stderr
   return run(argv, { cwd, out, err });
 }
 
-const DIRECT_VERBS = new Map([['ci', async (argv, io) => (await import('../ci/cli.mjs')).ciMain(argv, io)], ['lint', lintMain], ['secret', secretMain], ['db', databaseMain], ['upgrade', upgradeAppMain], ['stack', stackAppMain], ['release', releaseMain]]);
+const DIRECT_VERBS = new Map([['ci', async (argv, io) => (await import('../ci/cli.mjs')).ciMain(argv, io)], ['lint', lintMain], ['secret', secretMain], ['db', databaseMain], ['upgrade', upgradeAppMain], ['stack', stackAppMain], ['release', releaseMain], ['coverage', async (argv, io) => (await import('../coverage/cli.mjs')).coverageMain(argv, io)]]);
 const PARSED_VERBS = new Map([['check', checkMain], ['emit', emitMain], ['new', newMain], ['add', addMain], ['scaffold', scaffoldMain], ['explain', explainMain]]);
 
 function dispatchMain(verb, argv, io) {

package/sync/ci-commands.mjs

@@ -92,14 +92,14 @@ function codecovSteps(lcovReport, codecov) {
 }
 
 /** Sonar consumes the test coverage and fast lint artifacts only on release tags with a configured token. */
-function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor) {
+function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout) {
   if (!sonar) return '';
   const condition = sonar.optional ? SONAR_CONDITION.replace(' }}', " && steps.sonar-availability.outputs.up == 'true' }}") : SONAR_CONDITION;
   const host = sonar.provider === 'sonarcloud' ? 'https://sonarcloud.io' : `\${{ vars.${sonar.hostVar} }}`;
   const header = [
     '  sonar:',
-    '    needs: [fast, test]',
-    '    timeout-minutes: 20',
+    '    needs: [lint, coverage]',
+    `    timeout-minutes: ${timeout}`,
     '    runs-on: ubuntu-latest',
     '    env:',
     `      SONAR_TOKEN: \${{ secrets.${sonar.token} }}`,
@@ -116,8 +116,10 @@ function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor) {
     `      - uses: ${DOWNLOAD_ARTIFACT}`,
     `        if: ${condition}`,
     '        with:',
-    '          name: sonar-lint',
+    '          pattern: sonar-lint-*',
     '          path: reports',
+    '          merge-multiple: true',
+    ...sonarMergeSteps(condition),
     '      - uses: SonarSource/sonarqube-scan-action@c7ee0f9df90b7aa20e8dcf9695dcfe2e7da5b4f2 # v7.2.1',
     `        if: ${condition}`,
     '      - uses: SonarSource/sonarqube-quality-gate-action@7a5fffe8e523c40e0c740b6bc2712ab503e52efa # v1.2.1',
@@ -187,11 +189,11 @@ function frontendBuild(source, app) {
   return { env: singleEnv, steps };
 }
 
-/** Side lint reports join into the single Sonar artifact even when one side could not write its report. */
-function sonarMergeSteps() {
+/** The per-side lint reports (one artifact per lint matrix side) join into the one reports/lint.sonar.json the Sonar import reads, even when one side wrote none. */
+function sonarMergeSteps(condition) {
   return [
     '      - name: merge Sonar lint reports',
-    "        if: always() && env.SONAR_TOKEN != ''",
+    `        if: ${condition}`,
     '        run: |',
     "          node --input-type=module <<'NODE'",
     "          import fs from 'node:fs';",
@@ -205,6 +207,20 @@ function sonarMergeSteps() {
   ];
 }
 
+const STANDARD = new URL('../runtime/knowledge/hfs/ci-standard.yaml', import.meta.url);
+/** The per-job settings of the managed CI: ci.jobs.<job>.timeoutMinutes and ci.jobs.test.shards of the manifest over the defaults of the CI standard. */
+function ciJobSettings(declaration) {
+  const defaults = parseYaml(fs.readFileSync(STANDARD, 'utf8')).defaults;
+  const jobs = declaration?.ci?.jobs ?? {};
+  const timeout = (job) => String(jobs[job]?.timeoutMinutes ?? defaults.timeoutMinutes[job]);
+  const shards = Number(jobs.test?.shards ?? defaults.shards);
+  return {
+    timeoutFast: timeout('fast'), timeoutLint: timeout('lint'), timeoutTest: timeout('test'), timeoutCoverage: timeout('coverage'),
+    timeoutBuild: timeout('build'), timeoutSonar: timeout('sonar'), timeoutDbTypes: timeout('db-types'),
+    testShards: `[${Array.from({ length: shards }, (_, index) => index + 1).join(', ')}]`, testShardTotal: String(shards),
+  };
+}
+
 /** An omitted quality declaration preserves hosted Sonar, required OIDC Codecov, and the high production dependency audit. */
 export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info', quality = undefined, { nodeMajor = '22', app } = {}) {
   const configuredSonar = quality === undefined ? { token: 'SONAR_TOKEN', hostVar: 'SONAR_HOST_URL' } : quality.sonar;
@@ -213,7 +229,11 @@ 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 side = '${{ matrix.side }}';
   return {
+    ...settings,
+    lcovShardsDir: lcovReport.split('/').slice(0, -1).concat('shards').join('/'),
     ciBuildEnv: build.env,
     ciBuildSteps: build.steps,
     ciLint: exampleCommand(source, 'npm run lint'),
@@ -224,32 +244,28 @@ export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info',
     sonarTokenSecret: sonar?.token ?? 'SONAR_TOKEN',
     sonarHostVar: sonar?.hostVar ?? 'SONAR_HOST_URL',
     sonarEnv: sonar ? `    env:\n      SONAR_TOKEN: \${{ secrets.${sonar.token} }}` : '',
+    // One lint job per side (the lint matrix): with a Sonar token each side writes its own report, uploaded as sonar-lint-<side> and merged by the sonar job.
     ciLintSteps: [
-      ...['be', 'fe'].flatMap((side) => [
-        '      - name: lint ' + side,
-        ...(sonar ? ["        if: env.SONAR_TOKEN == ''"] : []),
-        `        run: ${exampleCommand(source, 'npm run lint -- --side ' + side)}`,
+      '      - name: lint',
+      ...(sonar ? ["        if: env.SONAR_TOKEN == ''"] : []),
+      `        run: ${exampleCommand(source, 'npm run lint -- --side ' + side)}`,
+      '        env:',
+      '          NODE_OPTIONS: --max-old-space-size=6144',
+      ...(sonar ? [
+        '      - name: lint with Sonar import',
+        "        if: env.SONAR_TOKEN != ''",
+        `        run: ${exampleCommand(source, 'npm run lint -- --side ' + side + ' --sonar reports/lint.' + side + '.sonar.json')}`,
         '        env:',
         '          NODE_OPTIONS: --max-old-space-size=6144',
-      ]),
-      ...(sonar ? [
-        ...['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') != ''",
+        `        if: always() && env.SONAR_TOKEN != '' && hashFiles('reports/lint.${side}.sonar.json') != ''`,
         '        with:',
-        '          name: sonar-lint',
-        '          path: reports/lint.sonar.json',
+        `          name: sonar-lint-${side}`,
+        `          path: reports/lint.${side}.sonar.json`,
       ] : []),
     ].join('\n'),
     codecovSteps: codecovSteps(lcovReport, codecov),
-    sonarJob: sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor),
+    sonarJob: sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, settings.timeoutSonar),
     lcovArtifact,
   };
 }

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -4,6 +4,8 @@
 #   refs/backup/*                  allowed: the coordinator backup namespace
 #   refs/heads/main, refs/tags/v*  allowed only when HEAD carries an annotated tag v[0-9]* and the release cut recorded the
 #                                  full suite of HEAD: <git common dir>/starci-release/<HEAD sha>.l4.json names that head and tag
+#   refs/heads/release/candidate-* the release candidate (starci app release push sends the release sha there first and moves main
+#                                  and the tag only when its ci.yml run is green): allowed under the same release gate, never deleted
 #   any other ref, a delete        refused
 common=$(git rev-parse --git-common-dir)
 case "$common" in /* | [A-Za-z]:*) ;; *) common="$(pwd)/$common" ;; esac
@@ -12,7 +14,7 @@ record="$common/starci-release/$head.l4.json"
 status=0
 gate=""
 refuse() {
-  echo "RIGHTS_PUSH_NOT_RELEASE: $1 - the allowed path is the release cut (main and v* tags) or refs/backup/* (backups)" >&2
+  echo "RIGHTS_PUSH_NOT_RELEASE: $1 - the allowed path is the release cut (main, v* tags and the release/candidate-* ref) or refs/backup/* (backups)" >&2
   status=1
 }
 # gate: the verdict of the release gate for HEAD, computed once: "ok" or the reason it is closed.
@@ -33,7 +35,7 @@ release_gate() {
 while read -r local_ref local_sha remote_ref remote_sha; do
   case "$remote_ref" in
     refs/backup/*) ;;
-    refs/heads/main | refs/tags/v*)
+    refs/heads/main | refs/tags/v* | refs/heads/release/candidate-*)
       case "$local_sha" in
         *[!0]*) ;;
         *) refuse "refusing to delete $remote_ref"; continue ;;

package/release/ci-red.mjs

@@ -1,102 +0,0 @@
-// ci-red.mjs - the latest completed default-branch CI is a release precondition; unreadable GitHub warns, a red run needs the owner's SHA-bound override.
-import fs from 'node:fs';
-import path from 'node:path';
-import { refusal } from '../stack/errors.mjs';
-
-const FIELDS = 'databaseId,headSha,status,conclusion,url,event,createdAt';
-const SHA = /^[a-f0-9]{40}$/u;
-const RED = new Set(['failure', 'cancelled', 'timed_out', 'startup_failure', 'action_required']);
-
-/** Every process uses the supplied seam; an unavailable executable is an unreadable result. */
-function run(spawn, cwd, command, args) {
-  try { return spawn(command, args, { cwd }); } catch { return { status: null }; }
-}
-
-function runsOf(result) {
-  if (result.error || result.status !== 0) return null;
-  try {
-    const rows = JSON.parse(result.stdout);
-    return Array.isArray(rows) ? rows : null;
-  } catch { return null; }
-}
-
-/** Resolve each available default-branch reference once, including HEAD in detached release worktrees. */
-function referenceTips(spawn, cwd, defaultBranch) {
-  const refs = [`origin/${defaultBranch}`, defaultBranch, 'HEAD'];
-  return refs.flatMap((name) => {
-    const result = run(spawn, cwd, 'git', ['rev-parse', '--verify', '--quiet', `${name}^{commit}`]);
-    const tip = String(result.stdout ?? '').trim();
-    return !result.error && result.status === 0 && SHA.test(tip) ? [{ name, tip }] : [];
-  });
-}
-
-/** Equality proves reachability directly; ancestry is unknown only when every available probe errors. */
-function pushAncestry(spawn, cwd, row, refs) {
-  if (refs.some((ref) => ref.tip === row.headSha)) return { candidate: true, unknown: false };
-  let known = false;
-  for (const ref of refs) {
-    const result = run(spawn, cwd, 'git', ['merge-base', '--is-ancestor', row.headSha, ref.tip]);
-    if (!result.error && result.status === 0) return { candidate: true, unknown: false };
-    if (!result.error && result.status === 1) known = true;
-  }
-  return { candidate: false, unknown: !known };
-}
-
-/** Branch rows remain candidates; push rows must reach a resolved reference, and each databaseId counts once. */
-function candidateRuns(spawn, cwd, branch, pushes, refs) {
-  const candidates = branch.filter((row) => row && SHA.test(row.headSha));
-  let ancestryUnknown = refs.length === 0;
-  for (const row of pushes) {
-    if (!row || !SHA.test(row.headSha) || row.event !== 'push') continue;
-    const ancestry = pushAncestry(spawn, cwd, row, refs);
-    if (ancestry.candidate) candidates.push(row);
-    if (ancestry.unknown) ancestryUnknown = true;
-  }
-  const unique = new Map();
-  for (const row of candidates) if (!unique.has(row.databaseId)) unique.set(row.databaseId, row);
-  return { candidates: [...unique.values()], ancestryUnknown };
-}
-
-/** Reads branch runs plus push/tag runs whose commits are reachable from the default branch; the newest completed run decides, even if a newer run is pending. */
-export function latestDefaultBranchCi({ spawn, cwd, defaultBranch = 'main' }) {
-  const refs = referenceTips(spawn, cwd, defaultBranch);
-  const unknown = (why) => ({ state: 'unknown', why: `${why} (refs: ${refs.map((ref) => ref.name).join(', ') || 'none'})` });
-  const args = ['run', 'list', '--workflow', 'ci.yml'];
-  const tail = ['--limit', '20', '--json', FIELDS];
-  const branch = runsOf(run(spawn, cwd, 'gh', [...args, '--branch', defaultBranch, ...tail]));
-  if (!branch) return unknown('gh branch runs unavailable (missing gh, authentication, or unreadable response)');
-  const pushes = runsOf(run(spawn, cwd, 'gh', [...args, '--event', 'push', ...tail]));
-  if (!pushes) return unknown('gh push runs unavailable (missing gh, authentication, or unreadable response)');
-  const { candidates, ancestryUnknown } = candidateRuns(spawn, cwd, branch, pushes, refs);
-  const completed = candidates.filter((row) => row.status === 'completed' && Number.isFinite(Date.parse(row.createdAt)));
-  completed.sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt) || Number(b.databaseId) - Number(a.databaseId));
-  const latest = completed[0];
-  if (!latest) return unknown(ancestryUnknown ? 'cannot establish push run ancestry on the default branch' : 'no completed CI run on the default branch');
-  if (latest.conclusion === 'success') return { state: 'green', run: latest };
-  if (RED.has(latest.conclusion)) return { state: 'red', run: latest };
-  return { ...unknown('latest completed CI run has no success or red conclusion'), run: latest };
-}
-
-/** Only a complete starci/ci-override@1 record for this exact commit can excuse a red run. */
-function overrideOf(ctx, sha) {
-  const common = run(ctx.spawn, ctx.cwd, 'git', ['rev-parse', '--git-common-dir']);
-  if (common.error || common.status !== 0 || !String(common.stdout ?? '').trim()) return null;
-  const file = path.join(path.resolve(ctx.cwd, String(common.stdout).trim()), 'starci-release', `${sha}.ci-override.json`);
-  try {
-    const record = JSON.parse(fs.readFileSync(file, 'utf8'));
-    if (record.schema !== 'starci/ci-override@1' || record.sha !== sha || typeof record.reason !== 'string' || !record.reason.trim() || typeof record.by !== 'string' || !record.by.trim() || typeof record.at !== 'string' || !Number.isFinite(Date.parse(record.at))) return null;
-    return record;
-  } catch { return null; }
-}
-
-/** Warns on unknown CI and refuses red CI unless the owner left a valid override beside the release records. */
-export function requireGreenCi(ctx, ci) {
-  if (ci.state === 'unknown') {
-    ctx.stderr(`RELEASE_CI_UNKNOWN: ${ci.why}\n`);
-    return [];
-  }
-  if (ci.state !== 'red') return [];
-  const record = overrideOf(ctx, ci.run.headSha);
-  if (record) return [`RELEASE_CI_RED overridden by the owner: ${record.reason}`];
-  throw refusal('RELEASE_CI_RED', `CI run ${ci.run.url} for ${ci.run.headSha} concluded ${ci.run.conclusion}; the owner must use starci release ci-override --sha ${ci.run.headSha} --reason <text>`);
-}