@starci/hfs 4.2.17 → 4.4.0

package/sync/stack-images.mjs

@@ -0,0 +1,127 @@
+// The Swarm deploy images an app declares, as the managed stack-deploy.yml workflow needs them.
+//
+// The workflow builds one image per `deploy.images` entry of .starcistacks/application-stacks.yaml and hands the pinned references to
+// `starci app stack deploy`. Sync renders that list into the workflow, so it reads the declaration here: the union over the declared
+// environments of `environments.<env>.deploy.images` (service -> { app, buildArgs }). Only names and the presence of build arguments are
+// read; the real validation of the block is stack-deploy-config.mjs (`starci app check`, rule R294). Everything this module returns is
+// pure text assembled from names that match the strict patterns below, so no free text reaches the rendered workflow.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseYaml as bundledParseYaml } from '../runtime/engine/yaml.mjs';
+import { DECLARATION } from './sonar-key.mjs';
+import { byCodeUnit } from '../report/order.mjs';
+
+const NAME = /^[a-z][a-z0-9-]*$/u;
+const KEY = /^[A-Z][A-Z0-9_]*$/u;
+const INDENT = ' '.repeat(6);
+const CONTINUE = '\\';
+const NO_IMAGES_MESSAGE = 'no image is declared: declare environments.<env>.deploy (with images) in .starcistacks/application-stacks.yaml before running this workflow';
+
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const hasBuildArgs = args => record(args) && (Object.keys(record(args.values) ? args.values : {}).length > 0 || record(args.sealed));
+
+function environmentImages(environment) {
+  const images = environment?.deploy?.images;
+  if (!record(images)) return [];
+  return Object.entries(images)
+    .filter(([service, entry]) => NAME.test(service) && record(entry) && NAME.test(String(entry.app)))
+    .map(([service, entry]) => ({ service, app: entry.app, buildArgs: hasBuildArgs(entry.buildArgs) }));
+}
+
+/**
+ * The images of a parsed declaration, [{ service, app, buildArgs }] sorted by service: the union over its environments (the first
+ * environment that names a service decides its app; a later one only adds build arguments). A declaration with no deploy block has none.
+ */
+export function declaredStackImages(declaration) {
+  const byService = new Map();
+  for (const environment of Object.values(record(declaration?.environments) ? declaration.environments : {})) {
+    for (const image of environmentImages(environment)) {
+      const known = byService.get(image.service);
+      byService.set(image.service, known ? { ...known, buildArgs: known.buildArgs || image.buildArgs } : image);
+    }
+  }
+  return [...byService.values()].sort((a, b) => byCodeUnit(a.service, b.service));
+}
+
+/** The host variables (names only) the declared environments interpolate into `docker stack config`: the union of `deploy.passEnv`. */
+export function declaredPassEnv(declaration) {
+  const names = Object.values(record(declaration?.environments) ? declaration.environments : {})
+    .flatMap(environment => (Array.isArray(environment?.deploy?.passEnv) ? environment.deploy.passEnv : []))
+    .filter(name => typeof name === 'string' && KEY.test(name));
+  return [...new Set(names)].sort(byCodeUnit);
+}
+
+/**
+ * What the managed workflow renders from the declaration of the app at `root`: { images, passEnv } (both empty when the app has no
+ * declaration, no deploy block or a declaration that does not parse; `starci app check` judges those). `parseYaml(text)` is injected.
+ */
+export function readDeclaredStack(root, { parseYaml = bundledParseYaml } = {}) {
+  const file = path.join(root, DECLARATION);
+  if (!fs.existsSync(file)) return { images: [], passEnv: [] };
+  let declaration;
+  try {
+    declaration = parseYaml(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return { images: [], passEnv: [] };
+  }
+  return { images: declaredStackImages(declaration), passEnv: declaredPassEnv(declaration) };
+}
+
+const envName = service => `IMAGE_${service.toUpperCase().replaceAll('-', '_')}`;
+/** Lines placed at the end of a template line: each one starts with a newline, so nothing declared leaves nothing, not even a blank line. */
+const block = (items, indent = INDENT) => items.map(item => `\n${indent}${item}`).join('');
+
+function buildArgsStep(image) {
+  return [
+    `- name: public build values of ${image.service}`,
+    `  id: args-${image.service}`,
+    '  env:',
+    '    SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}',
+    `  run: npx --no-install starci app stack build-args --env "$STACK_ENVIRONMENT" --app ${image.app}`,
+  ];
+}
+
+function buildPushStep(image, dockerfile) {
+  return [
+    `- name: build and push ${image.service}`,
+    `  id: build-${image.service}`,
+    '  uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2',
+    '  with:',
+    '    context: .',
+    `    file: ${dockerfile}`,
+    '    push: true',
+    '    provenance: false',
+    `    tags: \${{ steps.names.outputs.${image.service} }}:\${{ github.sha }}`,
+    ...(image.buildArgs ? [`    build-args: \${{ steps.args-${image.service}.outputs.args }}`] : []),
+    `    cache-from: type=gha,scope=${image.service}`,
+    `    cache-to: type=gha,scope=${image.service},mode=max`,
+  ];
+}
+
+/**
+ * The text blocks the stack-deploy.yml template places at the end of a line (each already indented for its position, every line led by
+ * a newline; empty when there is nothing to place):
+ *   stackGuard       the first step of the release job when the app declares no image (it fails with the reason)
+ *   stackNames       the `names` step lines assigning each image repository (ghcr.io/<lowercase owner>/<project>-<app>)
+ *   stackImageSteps  per image: the optional build-args step and the build-and-push step
+ *   stackImageEnv    the env entries of the deploy step: IMAGE_<SERVICE> = repository@digest
+ *   stackImageArgs   the `--image "<service>=$IMAGE_<SERVICE>" \` continuation lines of the deploy command
+ *   stackPassEnv     the env entries of the deploy step for the declared host variables (vars.<NAME>)
+ * `dockerfileOf(app)` names the Dockerfile of an app (the sync module knows the layout).
+ */
+export function stackWorkflowVariables({ images = [], passEnv = [] }, project, dockerfileOf) {
+  const guard = images.length ? '' : block([
+    '- name: require a declared image',
+    '  shell: bash',
+    `  run: 'echo "::error::${NO_IMAGES_MESSAGE}"; exit 1'`,
+  ]);
+  const names = images.map(image => `echo "${image.service}=ghcr.io/\${owner}/${project}-${image.app}" >> "$GITHUB_OUTPUT"`);
+  return {
+    stackGuard: guard,
+    stackNames: block(names, ' '.repeat(10)),
+    stackImageSteps: images.map(image => block([...(image.buildArgs ? buildArgsStep(image) : []), ...buildPushStep(image, dockerfileOf(image.app))])).join(''),
+    stackImageEnv: block(images.map(image => `${envName(image.service)}: \${{ steps.names.outputs.${image.service} }}@\${{ steps.build-${image.service}.outputs.digest }}`), ' '.repeat(10)),
+    stackImageArgs: block(images.map(image => `--image "${image.service}=$${envName(image.service)}" ${CONTINUE}`), ' '.repeat(12)),
+    stackPassEnv: block(passEnv.map(name => `${name}: \${{ vars.${name} }}`), ' '.repeat(10)),
+  };
+}

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

@@ -30,14 +30,18 @@ jobs:
           node-version: {{nodeMajor}}
           cache: npm
       - run: npm ci --ignore-scripts
+      - name: production dependency audit
+        run: npm audit --omit=dev --audit-level=high
       - name: lint
-        run: npm run lint -- --sonar reports/lint.sonar.json
+        run: {{ciLintSonar}}
       - name: format
         run: npm run format:check
       - name: typecheck
         run: npm run typecheck
       - name: unit
         run: npm test -- --ci
+      - name: coverage proof
+        run: {{ciCoverageProof}}
       - name: coverage upload
         uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5.5.5
         if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') }}

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

@@ -1,12 +1,11 @@
 {{header}}
-# Builds the image of every app on the release tag, so a Dockerfile that no longer builds fails the release (or a manual dispatch) that carries it.
+# Builds the image of every app on its release tag, so a Dockerfile that no longer builds fails that release.
 # It never pushes: publishing an image is the product's decision, not this file's.
 name: images
 
 on:
   push:
     tags: ["v*"]
-  workflow_dispatch:
 
 permissions:
   contents: read
@@ -26,12 +25,25 @@ jobs:
 {{imageMatrix}}
     steps:
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - name: release tag matches package version
+        run: node -e "const version=require('./package.json').version;if(process.env.GITHUB_REF_NAME!=='v'+version)process.exit(1)"
       - uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
       - uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
         with:
           context: .
           file: ${{ matrix.file }}
           push: false
-          tags: {{imageProject}}/${{ matrix.name }}:ci
+          tags: {{imageProject}}/${{ matrix.name }}:${{ github.ref_name }}
+          # OCI keeps the SBOM and provenance attestations without publishing to a registry.
+          outputs: type=oci,dest=${{ runner.temp }}/${{ matrix.name }}.oci.tar
+          sbom: true
+          provenance: mode=max
           cache-from: type=gha,scope=${{ matrix.name }}
           cache-to: type=gha,scope=${{ matrix.name }},mode=max
+      - name: retain image with SBOM and provenance
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: image-${{ matrix.name }}-${{ github.sha }}-${{ github.run_attempt }}
+          path: ${{ runner.temp }}/${{ matrix.name }}.oci.tar
+          if-no-files-found: error
+          compression-level: 0

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

@@ -0,0 +1,148 @@
+{{header}}
+# Deploys the app's Docker Swarm stack. This file only assembles arguments: the logic lives in the verbs connect, build-args, deploy,
+# rollback and disconnect of "starci app stack". It runs by hand only (Actions > deploy stack > Run workflow) from a release tag v*
+# whose version is the package.json version; it has no push or schedule trigger.
+# operation deploy    builds and pushes one image per environments.<env>.deploy.images entry of .starcistacks/application-stacks.yaml,
+#                     then deploys their immutable digests (render, provision, converge, verify, accept; a failure redeploys the previous release)
+# operation rollback  redeploys a stored release; "release" is 16 lowercase hex characters, empty means the previous accepted release
+# The environment input names a protected GitHub environment (required reviewers) that holds:
+#   vars    VPS_HOST, VPS_USER (the swarm manager); a variable named in deploy.passEnv, when the stack interpolates one
+#   secrets SOPS_AGE_KEY (the age identity of .sops.yaml), VPS_SSH_KEY (CI-only deploy key), VPS_KNOWN_HOSTS (pinned host keys)
+# Nothing else is a secret: images are pushed with the workflow token. Dispatch inputs reach scripts only through env.
+name: deploy stack
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Protected environment holding the VPS variables and the sealed custody under .starcistacks
+        required: true
+        type: environment
+      operation:
+        description: Deploy a new release or roll back to a stored one
+        required: true
+        type: choice
+        default: deploy
+        options:
+          - deploy
+          - rollback
+      release:
+        description: "Rollback only: release id (16 lowercase hex) to deploy again; empty means the previous accepted release"
+        required: false
+        type: string
+        default: ""
+
+permissions:
+  contents: read
+
+concurrency:
+  group: stack-${{ inputs.environment }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    if: ${{ inputs.operation == 'deploy' }}
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment }}
+    timeout-minutes: 60
+    permissions:
+      contents: read
+      packages: write
+    env:
+      STACK_ENVIRONMENT: ${{ inputs.environment }}
+      XDG_DATA_HOME: ${{ runner.temp }}/starci-data
+    steps:{{stackGuard}}
+      - name: require release tag
+        shell: bash
+        run: '[[ "$GITHUB_REF" == refs/tags/v* ]] || exit 1'
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - name: release tag matches package version
+        run: node -e "const version=require('./package.json').version;if(process.env.GITHUB_REF_NAME!=='v'+version)process.exit(1)"
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: {{nodeMajor}}
+          cache: npm
+      - run: npm ci --ignore-scripts
+      - name: install SOPS
+        uses: mdgreenwald/mozilla-sops-action@bb2d96a13ef438ad122e5827a57ebd75d6ff118d # v2.1.0
+        with:
+          version: v3.13.2
+      - name: image repositories
+        id: names
+        shell: bash
+        run: |
+          owner="${GITHUB_REPOSITORY_OWNER,,}"{{stackNames}}
+      - uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
+      - uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}{{stackImageSteps}}
+      - name: connect to the swarm manager
+        env:
+          VPS_SSH_KEY: ${{ secrets.VPS_SSH_KEY }}
+          VPS_KNOWN_HOSTS: ${{ secrets.VPS_KNOWN_HOSTS }}
+          VPS_HOST: ${{ vars.VPS_HOST }}
+          VPS_USER: ${{ vars.VPS_USER }}
+        run: npx --no-install starci app stack connect --env "$STACK_ENVIRONMENT" --execute
+      - name: deploy the release
+        env:
+          SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}{{stackImageEnv}}{{stackPassEnv}}
+        run: |
+          npx --no-install starci app stack deploy --env "$STACK_ENVIRONMENT" \{{stackImageArgs}}
+            --source-sha "$GITHUB_SHA" --execute
+      - name: disconnect from the swarm manager
+        if: ${{ always() }}
+        run: npx --no-install starci app stack disconnect --env "$STACK_ENVIRONMENT" --execute
+
+  rollback:
+    if: ${{ inputs.operation == 'rollback' }}
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment }}
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      packages: read
+    env:
+      STACK_ENVIRONMENT: ${{ inputs.environment }}
+      XDG_DATA_HOME: ${{ runner.temp }}/starci-data
+    steps:
+      - name: require release tag
+        shell: bash
+        run: '[[ "$GITHUB_REF" == refs/tags/v* ]] || exit 1'
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - name: release tag matches package version
+        run: node -e "const version=require('./package.json').version;if(process.env.GITHUB_REF_NAME!=='v'+version)process.exit(1)"
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: {{nodeMajor}}
+          cache: npm
+      - run: npm ci --ignore-scripts
+      - name: install SOPS
+        uses: mdgreenwald/mozilla-sops-action@bb2d96a13ef438ad122e5827a57ebd75d6ff118d # v2.1.0
+        with:
+          version: v3.13.2
+      - uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+      - name: connect to the swarm manager
+        env:
+          VPS_SSH_KEY: ${{ secrets.VPS_SSH_KEY }}
+          VPS_KNOWN_HOSTS: ${{ secrets.VPS_KNOWN_HOSTS }}
+          VPS_HOST: ${{ vars.VPS_HOST }}
+          VPS_USER: ${{ vars.VPS_USER }}
+        run: npx --no-install starci app stack connect --env "$STACK_ENVIRONMENT" --execute
+      - name: redeploy the stored release
+        env:
+          SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
+          RELEASE: ${{ inputs.release }}
+        shell: bash
+        run: |
+          release=()
+          [ -z "$RELEASE" ] || release=(--release "$RELEASE")
+          npx --no-install starci app stack rollback --env "$STACK_ENVIRONMENT" "${release[@]}" --execute
+      - name: disconnect from the swarm manager
+        if: ${{ always() }}
+        run: npx --no-install starci app stack disconnect --env "$STACK_ENVIRONMENT" --execute

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

@@ -30,18 +30,22 @@ jobs:
           node-version: {{nodeMajor}}
           cache: npm
       - run: npm ci --ignore-scripts
+      - name: production dependency audit
+        run: npm audit --omit=dev --audit-level=high
       - name: lint
         if: env.SONAR_TOKEN == ''
-        run: npm run lint
+        run: {{ciLint}}
       - name: lint with Sonar import
         if: env.SONAR_TOKEN != ''
-        run: npm run lint -- --sonar reports/lint.sonar.json
+        run: {{ciLintSonar}}
       - name: format
         run: npm run format:check
       - name: typecheck
         run: npm run typecheck
       - name: unit
         run: npm test -- --ci
+      - name: coverage proof
+        run: {{ciCoverageProof}}
       - name: coverage upload
         uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5.5.5
         if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') }}
@@ -55,7 +59,7 @@ jobs:
       - name: build fe
         run: npm run build:fe
       - name: database migration checks
-        run: npm run db:lint
+        run: {{ciDatabaseLint}}
 {{> app/ci-workflows/sonar-steps.yml}}
 
   db-types:

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

@@ -5,27 +5,59 @@ on:
   workflow_dispatch:
     inputs:
       environment:
-        description: GitHub environment whose Supabase secrets will be used
+        description: Protected environment with sealed Supabase custody under .starcistacks
         required: true
         type: environment
+      backup_receipt:
+        description: Tracked backup receipt path verified by the deployment owner before migration
+        required: true
+        type: string
 
 permissions:
   contents: read
 
+concurrency:
+  group: database-${{ inputs.environment }}
+  cancel-in-progress: false
+
 jobs:
   deploy:
     runs-on: ubuntu-latest
     environment: ${{ inputs.environment }}
     env:
-      SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
-      SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }}
-      SUPABASE_PROJECT_ID: ${{ secrets.SUPABASE_PROJECT_ID }}
+      STACK_ENVIRONMENT: ${{ inputs.environment }}
+      BACKUP_RECEIPT: ${{ inputs.backup_receipt }}
+      SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
+      XDG_DATA_HOME: ${{ runner.temp }}/starci-data
     steps:
+      - name: require release tag
+        shell: bash
+        run: '[[ "$GITHUB_REF" == refs/tags/v* ]] || exit 1'
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - name: release tag matches package version
+        run: node -e "const version=require('./package.json').version;if(process.env.GITHUB_REF_NAME!=='v'+version)process.exit(1)"
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: {{nodeMajor}}
           cache: npm
       - run: npm ci --ignore-scripts
-      - name: push migrations
-        run: npm run db:push
+      - name: install SOPS
+        uses: mdgreenwald/mozilla-sops-action@bb2d96a13ef438ad122e5827a57ebd75d6ff118d # v2.1.0
+        with:
+          version: v3.13.2
+      - name: materialize sealed custody and push migrations
+        shell: bash
+        run: |
+          set -euo pipefail
+          [[ "$STACK_ENVIRONMENT" =~ ^[a-z][a-z0-9-]*$ ]]
+          git ls-files --error-unmatch -- "$BACKUP_RECEIPT" > /dev/null
+          test -s "$BACKUP_RECEIPT"
+          secret_dir="$XDG_DATA_HOME/StarCi/secrets/{{project}}/$STACK_ENVIRONMENT"
+          trap 'rm -rf -- "$secret_dir"' EXIT
+          npx --no-install starci app secret materialize "$STACK_ENVIRONMENT"
+          export SUPABASE_ACCESS_TOKEN="$(cat "$secret_dir/SUPABASE_ACCESS_TOKEN")"
+          export SUPABASE_DB_PASSWORD="$(cat "$secret_dir/SUPABASE_DB_PASSWORD")"
+          project_id="$(cat "$secret_dir/SUPABASE_PROJECT_ID")"
+          npx --no-install supabase link --project-ref "$project_id"
+          npm run db:push -- --dry-run
+          npm run db:push

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

@@ -6,7 +6,6 @@ name: images
 on:
   push:
     tags: ["v*"]
-  workflow_dispatch:
 
 permissions:
   contents: read
@@ -26,12 +25,25 @@ jobs:
 {{imageMatrix}}
     steps:
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - name: release tag matches package version
+        run: node -e "const version=require('./package.json').version;if(process.env.GITHUB_REF_NAME!=='v'+version)process.exit(1)"
       - uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
       - uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
         with:
           context: .
           file: ${{ matrix.file }}
           push: false
-          tags: {{imageProject}}/${{ matrix.name }}:ci
+          tags: {{imageProject}}/${{ matrix.name }}:${{ github.ref_name }}
+          # OCI keeps the SBOM and provenance attestations without publishing to a registry.
+          outputs: type=oci,dest=${{ runner.temp }}/${{ matrix.name }}.oci.tar
+          sbom: true
+          provenance: mode=max
           cache-from: type=gha,scope=${{ matrix.name }}
           cache-to: type=gha,scope=${{ matrix.name }},mode=max
+      - name: retain image with SBOM and provenance
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: image-${{ matrix.name }}-${{ github.sha }}-${{ github.run_attempt }}
+          path: ${{ runner.temp }}/${{ matrix.name }}.oci.tar
+          if-no-files-found: error
+          compression-level: 0

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

@@ -0,0 +1,148 @@
+{{header}}
+# Deploys the app's Docker Swarm stack. This file only assembles arguments: the logic lives in the verbs connect, build-args, deploy,
+# rollback and disconnect of "starci app stack". It runs by hand only (Actions > deploy stack > Run workflow) from a release tag v*
+# whose version is the package.json version; it has no push or schedule trigger.
+# operation deploy    builds and pushes one image per environments.<env>.deploy.images entry of .starcistacks/application-stacks.yaml,
+#                     then deploys their immutable digests (render, provision, converge, verify, accept; a failure redeploys the previous release)
+# operation rollback  redeploys a stored release; "release" is 16 lowercase hex characters, empty means the previous accepted release
+# The environment input names a protected GitHub environment (required reviewers) that holds:
+#   vars    VPS_HOST, VPS_USER (the swarm manager); a variable named in deploy.passEnv, when the stack interpolates one
+#   secrets SOPS_AGE_KEY (the age identity of .sops.yaml), VPS_SSH_KEY (CI-only deploy key), VPS_KNOWN_HOSTS (pinned host keys)
+# Nothing else is a secret: images are pushed with the workflow token. Dispatch inputs reach scripts only through env.
+name: deploy stack
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Protected environment holding the VPS variables and the sealed custody under .starcistacks
+        required: true
+        type: environment
+      operation:
+        description: Deploy a new release or roll back to a stored one
+        required: true
+        type: choice
+        default: deploy
+        options:
+          - deploy
+          - rollback
+      release:
+        description: "Rollback only: release id (16 lowercase hex) to deploy again; empty means the previous accepted release"
+        required: false
+        type: string
+        default: ""
+
+permissions:
+  contents: read
+
+concurrency:
+  group: stack-${{ inputs.environment }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    if: ${{ inputs.operation == 'deploy' }}
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment }}
+    timeout-minutes: 60
+    permissions:
+      contents: read
+      packages: write
+    env:
+      STACK_ENVIRONMENT: ${{ inputs.environment }}
+      XDG_DATA_HOME: ${{ runner.temp }}/starci-data
+    steps:{{stackGuard}}
+      - name: require release tag
+        shell: bash
+        run: '[[ "$GITHUB_REF" == refs/tags/v* ]] || exit 1'
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - name: release tag matches package version
+        run: node -e "const version=require('./package.json').version;if(process.env.GITHUB_REF_NAME!=='v'+version)process.exit(1)"
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: {{nodeMajor}}
+          cache: npm
+      - run: npm ci --ignore-scripts
+      - name: install SOPS
+        uses: mdgreenwald/mozilla-sops-action@bb2d96a13ef438ad122e5827a57ebd75d6ff118d # v2.1.0
+        with:
+          version: v3.13.2
+      - name: image repositories
+        id: names
+        shell: bash
+        run: |
+          owner="${GITHUB_REPOSITORY_OWNER,,}"{{stackNames}}
+      - uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
+      - uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}{{stackImageSteps}}
+      - name: connect to the swarm manager
+        env:
+          VPS_SSH_KEY: ${{ secrets.VPS_SSH_KEY }}
+          VPS_KNOWN_HOSTS: ${{ secrets.VPS_KNOWN_HOSTS }}
+          VPS_HOST: ${{ vars.VPS_HOST }}
+          VPS_USER: ${{ vars.VPS_USER }}
+        run: npx --no-install starci app stack connect --env "$STACK_ENVIRONMENT" --execute
+      - name: deploy the release
+        env:
+          SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}{{stackImageEnv}}{{stackPassEnv}}
+        run: |
+          npx --no-install starci app stack deploy --env "$STACK_ENVIRONMENT" \{{stackImageArgs}}
+            --source-sha "$GITHUB_SHA" --execute
+      - name: disconnect from the swarm manager
+        if: ${{ always() }}
+        run: npx --no-install starci app stack disconnect --env "$STACK_ENVIRONMENT" --execute
+
+  rollback:
+    if: ${{ inputs.operation == 'rollback' }}
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment }}
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      packages: read
+    env:
+      STACK_ENVIRONMENT: ${{ inputs.environment }}
+      XDG_DATA_HOME: ${{ runner.temp }}/starci-data
+    steps:
+      - name: require release tag
+        shell: bash
+        run: '[[ "$GITHUB_REF" == refs/tags/v* ]] || exit 1'
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - name: release tag matches package version
+        run: node -e "const version=require('./package.json').version;if(process.env.GITHUB_REF_NAME!=='v'+version)process.exit(1)"
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: {{nodeMajor}}
+          cache: npm
+      - run: npm ci --ignore-scripts
+      - name: install SOPS
+        uses: mdgreenwald/mozilla-sops-action@bb2d96a13ef438ad122e5827a57ebd75d6ff118d # v2.1.0
+        with:
+          version: v3.13.2
+      - uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+      - name: connect to the swarm manager
+        env:
+          VPS_SSH_KEY: ${{ secrets.VPS_SSH_KEY }}
+          VPS_KNOWN_HOSTS: ${{ secrets.VPS_KNOWN_HOSTS }}
+          VPS_HOST: ${{ vars.VPS_HOST }}
+          VPS_USER: ${{ vars.VPS_USER }}
+        run: npx --no-install starci app stack connect --env "$STACK_ENVIRONMENT" --execute
+      - name: redeploy the stored release
+        env:
+          SOPS_AGE_KEY: ${{ secrets.SOPS_AGE_KEY }}
+          RELEASE: ${{ inputs.release }}
+        shell: bash
+        run: |
+          release=()
+          [ -z "$RELEASE" ] || release=(--release "$RELEASE")
+          npx --no-install starci app stack rollback --env "$STACK_ENVIRONMENT" "${release[@]}" --execute
+      - name: disconnect from the swarm manager
+        if: ${{ always() }}
+        run: npx --no-install starci app stack disconnect --env "$STACK_ENVIRONMENT" --execute

package/templates/app/codegen-graphql.mjs.partial

@@ -8,12 +8,12 @@ const posix = (file) => file.split(path.sep).join("/")
 const schemas = (fs.existsSync(CONTRACTS) ? fs.readdirSync(CONTRACTS) : [])
     .map((app) => path.join(CONTRACTS, app, "schema.graphql"))
     .filter((file) => fs.existsSync(file))
-    .sort()
+    .sort(byCodeUnit)
     .map(posix)
 const operationRoots = (fs.existsSync(FE_APPS) ? fs.readdirSync(FE_APPS) : [])
     .map((app) => path.join(FE_APPS, app, "src", "modules", "api", "graphql"))
     .filter((dir) => fs.existsSync(dir))
-    .sort()
+    .sort(byCodeUnit)
     .map(posix)
 if (schemas.length === 0 || operationRoots.length === 0) {
     process.stdout.write("codegen: no GraphQL contract under be/contracts yet\n")
@@ -31,4 +31,15 @@ if (schemas.length === 0 || operationRoots.length === 0) {
         ]),
     )
     await generate({ schema: schemas, generates, ignoreNoDocuments: true, silent: true }, true)
+    // Stamp only a successful generation, using the same sorted paths and LF-normalized schemas as R52.
+    const hash = createHash("sha256")
+    for (const schema of schemas) {
+        const source = fs.readFileSync(schema, "utf8").replaceAll("\r\n", "\n")
+        hash.update(`${schema}\0${source}\0`)
+    }
+    const digest = hash.digest("hex")
+    for (const root of operationRoots) {
+        const generated = `${root}/__generated__`
+        if (fs.existsSync(generated)) fs.writeFileSync(`${generated}/.schema-sha256`, `${digest}\n`)
+    }
 }