@starci/hfs 4.11.21 → 4.12.0

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

@@ -4,7 +4,7 @@
     "db:stop": "docker stop {{project}}-dev-db",
     "db:reset": "docker rm -f {{project}}-dev-db && docker volume rm {{project}}-dev-db-data && npm run db:create && npm run db:start",
     "db:new": "{{appBinary}} db new",
-    "db:push": "{{appBinary}} db migrate --url-env DATABASE_URL --execute",
-    "db:plan": "{{appBinary}} db plan --url-env DATABASE_URL",
-    "db:dump": "{{appBinary}} db dump --url-env DATABASE_URL --out ../{{project}}-db-backups",
+    "db:push": "{{appBinary}} db migrate --db-url-env DATABASE_URL --execute",
+    "db:plan": "{{appBinary}} db migrate --db-url-env DATABASE_URL",
+    "db:dump": "{{appBinary}} db dump --db-url-env DATABASE_URL --out ../{{project}}-db-backups",
     "db:lint": "{{appBinary}} check --fast",

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

@@ -8,7 +8,7 @@
     "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",
-    "test:stack": "starci app stack",
+    "test:world": "starci app world up",
     "contract:emit": "starci app emit"
   }
 }

package/templates/app/quality-config/sonar-project.properties

@@ -6,7 +6,7 @@ sonar.test.inclusions={{sonarTestInclusions}}
 sonar.typescript.tsconfigPaths={{tsconfigPaths}}
 sonar.externalIssuesReportPaths=reports/lint.sonar.json
 sonar.javascript.lcov.reportPaths={{lcovReport}}
-# starci:sonar-scope begin (generated by `starci app sonar --write` from contexts/hfs/slots.yaml; do not edit)
+# starci:sonar-scope begin (generated by `starci app sync --execute` from contexts/hfs/slots.yaml; do not edit)
 sonar.coverage.exclusions={{coverageExclusions}}
 sonar.cpd.exclusions={{cpdExclusions}}
 # starci:sonar-scope end

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

@@ -103,7 +103,7 @@ environments:
         where: secrets/primary-db-password
         recipientPolicy: This app's own age recipient configured in .sops.yaml
         keyCustody: SOPS_AGE_KEY in the host's untracked .claude/secret.env
-    # What `starci app stack` deploys (verbs: prepare, doctor, deploy, verify, rollback); names and shapes only, never a value.
+    # What `starci app stack` deploys (verbs: prepare, deploy, verify, rollback); names and shapes only, never a value.
     deploy:
       stack: {{project}}-production
       # The image registry. The canon scaffold writes `public` (the owner's default: images cost nothing there); the value belongs to the app from now on
@@ -189,7 +189,7 @@ services:
     projects: [{repository: "{{project}}", key: "{{project}}"}]
     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.
+      needed: Provision this app's Sonar host and project, then set SONAR_TOKEN with starci app ci secret set SONAR_TOKEN --execute and sync SONAR_HOST_URL.
       reason: A fresh app declares its quality service without fabricating credentials or a successful analysis.
   codecov:
     provider: codecov

package/templates/app/skeleton/.starcistacks/production/README.md

@@ -3,16 +3,16 @@
 The app and its dependencies run on Docker Swarm. The tracked model declares the application services, one digest-pinned Caddy ingress and one digest-pinned PostgreSQL service on an internal backing network, with its data on a named persistent volume and credentials supplied through mounted secrets. On the first boot of an empty data volume, PostgreSQL runs the mounted `.starcistacks/production/infra/swarm/postgres-init.sh` config to create the `app_be` role with access to this app's database and schema, without superuser, database-creation, role-creation, replication or RLS-bypass privileges. Existing data volumes skip initialization and retain their roles and credentials.
 The model is a deployment declaration. It contains no owner credentials, real DNS receipt, completed release or restore proof. The public records under `.starcistacks/production/infra/swarm/` mark those owner-run operations as pending. Its all-zero application image digests are illustrative and must be replaced before deployment.
 
-The runtime template tracks no encrypted members. Scaffolding generates the declared database connection, application password and PostgreSQL administrator password members with placeholder values encrypted to this app's own recipient in `.sops.yaml`. Replace them with `starci app secret set production` using the matching host age identity in untracked local custody. The sealed connection uses role `app_be`, database `{{project}}` and internal endpoint `postgres:5432`; its URI-encoded password matches the separate `primary-db-password` member. The administrator password is distinct. The API receives only its least-privilege connection; only PostgreSQL receives the two password files for initialization. The non-empty application password contains no line breaks. The service has no TTY: initialization creates the role without a password, then feeds the two `psql` `\password` prompts through stdin using Bash's builtin `printf`, so psql encrypts it before sending SQL. No password travels in an initialization command argument or a plaintext SQL statement.
+The runtime template tracks no encrypted members. Scaffolding generates the declared database connection, application password and PostgreSQL administrator password members with placeholder values encrypted to this app's own recipient in `.sops.yaml`. Replace them with `starci app secret set --env production` using the matching host age identity in untracked local custody. The sealed connection uses role `app_be`, database `{{project}}` and internal endpoint `postgres:5432`; its URI-encoded password matches the separate `primary-db-password` member. The administrator password is distinct. The API receives only its least-privilege connection; only PostgreSQL receives the two password files for initialization. The non-empty application password contains no line breaks. The service has no TTY: initialization creates the role without a password, then feeds the two `psql` `\password` prompts through stdin using Bash's builtin `printf`, so psql encrypts it before sending SQL. No password travels in an initialization command argument or a plaintext SQL statement.
 
 Bootstrap references reviewed 2026-10-25: the [official PostgreSQL image initialization and Docker secret contract](https://github.com/docker-library/docs/blob/master/postgres/README.md#initialization-scripts), [PostgreSQL 16 psql password handling and SQL interpolation](https://www.postgresql.org/docs/16/app-psql.html), and its [password command](https://github.com/postgres/postgres/blob/REL_16_STABLE/src/bin/psql/command.c) and [prompt stdin fallback](https://github.com/postgres/postgres/blob/REL_16_STABLE/src/common/sprompt.c). First-release verification must confirm fresh-volume initialization, `app_be` privileges, health-gated startup and unchanged credentials after data-volume reuse; this source template records no live verification result.
 
 | Command | Operation |
 | --- | --- |
 | prepare | Owner provisions the Swarm, node label and DNS, seals the matching application connection/password and distinct administrator password, then runs `starci app stack prepare --env production --execute` to create the missing external volumes (the one-time swarm initialization stays an owner-approved step: `--init-swarm` with `--execute`, after the owner's explicit approval). The single up path below starts PostgreSQL and initializes `app_be` automatically on a new empty data volume. Release images are built and pushed by the managed stack-deploy workflow. |
-| doctor | Run `starci app stack doctor --env production` (read-only): docker, swarm, volumes, services, secrets, configs and the release pointers on the intended manager. |
-| up | After preparation and review, run the manual stack-deploy workflow (Actions, deploy stack) on a release tag; it builds the images and runs `starci app stack deploy --env production --image <service>=<repository>@sha256:<digest> --source-sha <sha> --execute`. A dry run is `starci app stack render` or `deploy` without `--execute`. |
-| status | Run `starci app stack doctor --env production`, or `starci app stack converge --env production --since <ISO time>` to inspect desired and running replicas plus update state. |
+| doctor | Run `starci app stack prepare --env production` (a dry run, read-only): docker, swarm, volumes, services, secrets, configs and the release pointers on the intended manager. |
+| up | After preparation and review, run the manual stack-deploy workflow (Actions, deploy stack) on a release tag; it builds the images and runs `starci app stack deploy --env production --image <service>=<repository>@sha256:<digest> --sha <sha> --execute`. A dry run is `starci app stack render --env production` or `deploy --env production` without `--execute`. |
+| status | Run `starci app stack prepare --env production`, or `starci app stack converge --env production --since <ISO time>` to inspect desired and running replicas plus update state. |
 | logs | Run `docker service logs {{project}}-production_core` on the manager; never include secret values in a receipt. |
 | down | After the owner's removal decision, run `docker stack rm {{project}}-production`; persistent external volumes remain in owner custody. |
 | verification | Run `starci app stack verify --env production` (the journeys declared in `deploy.verify`); also confirm public TLS and a signed-in GraphQL request before moving the release pointer. |

package/templates/app/skeleton/.starcistacks/production/infra/swarm/stack.yaml

@@ -22,9 +22,10 @@ services:
         order: start-first
         failure_action: rollback
         monitor: 30s
+      # Stateless and served behind the ingress: roll back start-first so the serving task stays up until the old release is healthy.
       rollback_config:
         parallelism: 1
-        order: stop-first
+        order: start-first
       restart_policy:
         condition: on-failure
         delay: 5s
@@ -51,9 +52,10 @@ services:
         order: start-first
         failure_action: rollback
         monitor: 30s
+      # Stateless and served behind the ingress: roll back start-first so the serving task stays up until the old release is healthy.
       rollback_config:
         parallelism: 1
-        order: stop-first
+        order: start-first
       restart_policy:
         condition: on-failure
         delay: 5s
@@ -80,9 +82,10 @@ services:
         order: start-first
         failure_action: rollback
         monitor: 30s
+      # Stateless and served behind the ingress: roll back start-first so the serving task stays up until the old release is healthy.
       rollback_config:
         parallelism: 1
-        order: stop-first
+        order: start-first
       restart_policy:
         condition: on-failure
         delay: 5s
@@ -111,6 +114,7 @@ services:
         order: stop-first
         failure_action: rollback
         monitor: 30s
+      # The database owns a data volume and is single-writer: never run two at once, so rollback stays stop-first.
       rollback_config:
         parallelism: 1
         order: stop-first
@@ -143,6 +147,7 @@ services:
         order: stop-first
         failure_action: rollback
         monitor: 30s
+      # The ingress owns published ports and a certificate volume: never run two at once, so rollback stays stop-first.
       rollback_config:
         parallelism: 1
         order: stop-first

package/templates/app/skeleton/README.md

@@ -18,7 +18,7 @@ TypeScript everywhere; NestJS in `be/`, Next.js with next-intl in `fe/`; npm wit
 
 ## Status badges
 
-Declare `ci.github.repository` and `ci.github.defaultBranch` in `.starcistacks/application-stacks.yaml` (or set the GitHub `repository` URL in `package.json`), then run `npx starci app sync --write`. Sync inserts a managed badge block after the title; `npx starci app sync --check` verifies it.
+Declare `ci.github.repository` and `ci.github.defaultBranch` in `.starcistacks/application-stacks.yaml` (or set the GitHub `repository` URL in `package.json`), then run `npx starci app sync --execute`. Sync inserts a managed badge block after the title; `npx starci app sync` (the dry run) verifies it.
 
 ## Development
 

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

@@ -191,7 +191,7 @@ environments:
         where: secrets/storage-secret-access-key
         recipientPolicy: This app's own age recipient configured in .sops.yaml
         keyCustody: SOPS_AGE_KEY in the host's untracked .claude/secret.env
-    # What `starci app stack` deploys (verbs: prepare, doctor, deploy, verify, rollback); names and shapes only, never a value.
+    # What `starci app stack` deploys (verbs: prepare, deploy, verify, rollback); names and shapes only, never a value.
     # Add a backup block (digest-pinned tar helper image) once the stateful volumes are provisioned.
     deploy:
       stack: {{project}}-production
@@ -278,7 +278,7 @@ services:
     projects: [{repository: "{{project}}", key: "{{project}}"}]
     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.
+      needed: Provision this app's Sonar host and project, then set SONAR_TOKEN with starci app ci secret set SONAR_TOKEN --execute and sync SONAR_HOST_URL.
       reason: A fresh app declares its quality service without fabricating credentials or a successful analysis.
   codecov:
     provider: codecov

package/templates/app/skeleton-lite/.starcistacks/dev/README.md

@@ -3,7 +3,7 @@
 Every development dependency runs in Docker Linux containers. The `db` service (the official postgres image plus pgvector, built from `.starcistacks/images/db/Dockerfile`) starts with `npm run db:start` and takes the migrations with `npm run db:push`; storage is the S3-compatible MinIO the environment names. Every other declared dependency, such as Redis, starts through its managed `<dep>:create`, `<dep>:start` and `<dep>:stop` scripts or the declared container model; Compose is an implementation detail. The app services may run in the local Docker Swarm model or through a declared native development profile while dependencies stay in Docker.
 The application image references contain illustrative all-zero digests. Replace them with verified published release digests in the manifest, model and `.starcistacks/dev/infra/swarm/releases/images.lock.yaml` before starting the container model. Seal the local database connection and the integration credentials; a container cannot use the host's loopback address without owner-configured networking. Local source development remains available through the app scripts.
 
-The runtime template tracks no encrypted members. Scaffolding generates the six declared members with placeholder values encrypted to this app's own recipient in `.sops.yaml`. Replace those values with `starci app secret set dev` using the matching host age identity in untracked local custody. Existing generated envelopes are decryptable with that app identity and can be updated in place. Each Docker secret contains the corresponding key's real value, and the API receives it through its declared mounted file.
+The runtime template tracks no encrypted members. Scaffolding generates the six declared members with placeholder values encrypted to this app's own recipient in `.sops.yaml`. Replace those values with `starci app secret set --env dev` using the matching host age identity in untracked local custody. Existing generated envelopes are decryptable with that app identity and can be updated in place. Each Docker secret contains the corresponding key's real value, and the API receives it through its declared mounted file.
 
 | Command | Operation |
 | --- | --- |

package/templates/app/skeleton-lite/.starcistacks/dev/infra/swarm/stack.yaml

@@ -47,9 +47,10 @@ services:
         order: start-first
         failure_action: rollback
         monitor: 30s
+      # Stateless and served behind the ingress: roll back start-first so the serving task stays up until the old release is healthy.
       rollback_config:
         parallelism: 1
-        order: stop-first
+        order: start-first
       restart_policy:
         condition: on-failure
         delay: 5s
@@ -76,9 +77,10 @@ services:
         order: start-first
         failure_action: rollback
         monitor: 30s
+      # Stateless and served behind the ingress: roll back start-first so the serving task stays up until the old release is healthy.
       rollback_config:
         parallelism: 1
-        order: stop-first
+        order: start-first
       restart_policy:
         condition: on-failure
         delay: 5s
@@ -108,6 +110,7 @@ services:
         order: stop-first
         failure_action: rollback
         monitor: 30s
+      # The database owns a data volume and is single-writer: never run two at once, so rollback stays stop-first.
       rollback_config:
         parallelism: 1
         order: stop-first
@@ -139,6 +142,7 @@ services:
         order: stop-first
         failure_action: rollback
         monitor: 30s
+      # The ingress owns published ports and a certificate volume: never run two at once, so rollback stays stop-first.
       rollback_config:
         parallelism: 1
         order: stop-first

package/templates/app/skeleton-lite/.starcistacks/dev/runtime/env/KEYS.md

@@ -1,6 +1,6 @@
 # Environment key roster
 
-This roster declares names only. Scaffolding generates the six declared encrypted members with placeholder values encrypted to this app's own age recipient. Replace their values through `starci app secret set dev` before creating external secrets. The runtime template tracks no ciphertext; its specs generate members with ephemeral identities in disposable copies. Store product credential values in sealed custody and materialize private KEY files outside the repository.
+This roster declares names only. Scaffolding generates the six declared encrypted members with placeholder values encrypted to this app's own age recipient. Replace their values through `starci app secret set --env dev` before creating external secrets. The runtime template tracks no ciphertext; its specs generate members with ephemeral identities in disposable copies. Store product credential values in sealed custody and materialize private KEY files outside the repository.
 
 | Key | Consumer |
 | --- | --- |
@@ -15,13 +15,14 @@ This roster declares names only. Scaffolding generates the six declared encrypte
 | `AUTH_JWT_ISSUER` | API access-token issuer |
 | `AUTH_JWT_AUDIENCE` | API access-token audience |
 | `AUTH_JWT_KEY_ID` | API signing key id, published in the JWKS |
+| `AUTH_COOKIE_DOMAIN` | API cookie `Domain` (a bare domain such as `example.com`, no scheme or port); optional while the web and the API share one host, required when they are served on different hosts, because a host-only refresh cookie never reaches the web server's forwarded `Cookie` header |
 | `AUTH_JWT_PRIVATE_KEY` | API ES256 signing key; `.starcistacks/dev/secrets/auth-jwt-private-key.enc` maps to external `{{project}}-dev-auth-jwt-private-key-v1` and mounted `/run/secrets/auth-jwt-private-key` |
 | `STORAGE_ENDPOINT` | API S3-compatible storage endpoint |
 | `STORAGE_REGION` | API storage signing region |
 | `STORAGE_BUCKET` | API storage bucket |
 | `STORAGE_ACCESS_KEY_ID` | API storage credential; `.starcistacks/dev/secrets/storage-access-key-id.enc` maps to external `{{project}}-dev-storage-access-key-id-v1` and mounted `/run/secrets/storage-access-key-id` |
 | `STORAGE_SECRET_ACCESS_KEY` | API storage credential; `.starcistacks/dev/secrets/storage-secret-access-key.enc` maps to external `{{project}}-dev-storage-secret-access-key-v1` and mounted `/run/secrets/storage-secret-access-key` |
-| `DATABASE_URL` | `starci app db` verbs (migrate, dump, plan) and `contract:emit`, from the operator's environment |
+| `DATABASE_URL` | `starci app db` verbs (migrate, dump) and `contract:emit`, from the operator's environment |
 | `NEXT_PUBLIC_SITE_URL` | Front-end site URL |
 | `NEXT_PUBLIC_API_URL` | Front-end auth doors of the API |
 | `NEXT_PUBLIC_GRAPHQL_URL` | Front-end GraphQL transport |

package/templates/app/skeleton-lite/.starcistacks/production/README.md

@@ -5,14 +5,14 @@ The `db` service (the official postgres image plus pgvector, built from `.starci
 The model is a deployment declaration. It contains no owner credentials, real DNS receipt, completed release or restore proof. Public records under `.starcistacks/production/infra/swarm/` explicitly mark those owner-run operations as pending.
 Its application image references contain illustrative all-zero digests; they identify no published image and must be replaced before deployment.
 
-The runtime template tracks no encrypted members. Scaffolding generates the six declared members with placeholder values encrypted to this app's own recipient in `.sops.yaml`. Replace those values with `starci app secret set production` using the matching host age identity in untracked local custody. Existing generated envelopes are decryptable with that app identity and can be updated in place. Each Docker secret contains the corresponding key's real value, and the API receives it through its declared mounted file.
+The runtime template tracks no encrypted members. Scaffolding generates the six declared members with placeholder values encrypted to this app's own recipient in `.sops.yaml`. Replace those values with `starci app secret set --env production` using the matching host age identity in untracked local custody. Existing generated envelopes are decryptable with that app identity and can be updated in place. Each Docker secret contains the corresponding key's real value, and the API receives it through its declared mounted file.
 
 | Command | Operation |
 | --- | --- |
 | prepare | Owner provisions the Swarm, node label, database, DNS and real sealed secret members, then runs `starci app stack prepare --env production --execute` to create the missing external volumes (the one-time swarm initialization stays an owner-approved step: `--init-swarm` with `--execute`, after the owner's explicit approval). Release images are built and pushed by the managed the managed stack-deploy workflow. |
-| doctor | Run `starci app stack doctor --env production` (read-only): docker, swarm, volumes, services, secrets, configs and the release pointers on the intended manager. |
-| up | After preparation and review, run the manual stack-deploy workflow (Actions, deploy stack) on a release tag; it builds the images and runs `starci app stack deploy --env production --image <service>=<repository>@sha256:<digest> --source-sha <sha> --execute`. A dry run is `starci app stack render` or `deploy` without `--execute`. |
-| status | Run `starci app stack doctor --env production`, or `starci app stack converge --env production --since <ISO time>` to inspect desired and running replicas plus update state. |
+| doctor | Run `starci app stack prepare --env production` (a dry run, read-only): docker, swarm, volumes, services, secrets, configs and the release pointers on the intended manager. |
+| up | After preparation and review, run the manual stack-deploy workflow (Actions, deploy stack) on a release tag; it builds the images and runs `starci app stack deploy --env production --image <service>=<repository>@sha256:<digest> --sha <sha> --execute`. A dry run is `starci app stack render --env production` or `deploy --env production` without `--execute`. |
+| status | Run `starci app stack prepare --env production`, or `starci app stack converge --env production --since <ISO time>` to inspect desired and running replicas plus update state. |
 | logs | Run `docker service logs {{project}}-production_api` on the manager; never include secret values in a receipt. |
 | down | After the owner's removal decision, run `docker stack rm {{project}}-production`; persistent external volumes remain in owner custody. |
 | verification | Run `starci app stack verify --env production` (the journeys declared in `deploy.verify`); also confirm public TLS and a signed-in GraphQL request before moving the release pointer. |
@@ -26,7 +26,7 @@ Every item is pending. Swarm initialization, provider URIs, DNS changes and key
 | Swarm and placement | Initialize the intended manager; label the intended stateful node `{{project}}=production`. Only that node owns the external ingress volumes. |
 | DNS | Replace the reserved `example.invalid` hosts consistently in the manifest, Caddyfile and public configuration; publish address records for the web and API hosts and retain a provider receipt in `.starcistacks/production/infra/swarm/owner-actions.md`. |
 | TLS | Caddy issues certificates after real DNS resolves. Provision `{{project}}-production-ingress-data` and `{{project}}-production-ingress-config-data` on the selected node; retain an issuance and renewal receipt in `.starcistacks/production/infra/swarm/owner-actions.md`. |
-| Database | Provision `{{project}}-production-db-data` on the stateful node; after the first deploy create the app_be login through the baseline migration (`starci app db migrate --url-env DATABASE_URL --execute`). Record the recovery owner without copying credentials here. |
+| Database | Provision `{{project}}-production-db-data` on the stateful node; after the first deploy create the app_be login through the baseline migration (`starci app db migrate --db-url-env DATABASE_URL --execute`). Record the recovery owner without copying credentials here. |
 | Secret custody | Replace generated placeholder values with real values at the manifest's declared `.starcistacks/production/secrets/*.enc` paths; record their keys in `.starcistacks/production/runtime/env/KEYS.md`. The app's age identity stays only in the host's untracked `.claude/secret.env`. |
 | External secrets | Materialize the sealed members in owner custody and create the `{{project}}-production-<member>-v1` external secret of each declared member. The API reads mounted files; rotation creates new versioned names before updating the model. |
 | Public build configuration | Build the front end with its declared public site, API and GraphQL URLs. Public browser values stay outside sealed secret custody. |

package/templates/app/skeleton-lite/.starcistacks/production/infra/swarm/stack.yaml

@@ -14,6 +14,7 @@ services:
       AUTH_JWT_ISSUER: https://api.{{project}}.example.invalid
       AUTH_JWT_AUDIENCE: {{project}}
       AUTH_JWT_KEY_ID: production-1
+      AUTH_COOKIE_DOMAIN: {{project}}.example.invalid
       AUTH_JWT_PRIVATE_KEY_FILE: /run/secrets/auth-jwt-private-key
       STORAGE_ENDPOINT: https://storage.{{project}}.example.invalid
       STORAGE_REGION: us-east-1
@@ -47,9 +48,10 @@ services:
         order: start-first
         failure_action: rollback
         monitor: 30s
+      # Stateless and served behind the ingress: roll back start-first so the serving task stays up until the old release is healthy.
       rollback_config:
         parallelism: 1
-        order: stop-first
+        order: start-first
       restart_policy:
         condition: on-failure
         delay: 5s
@@ -76,9 +78,10 @@ services:
         order: start-first
         failure_action: rollback
         monitor: 30s
+      # Stateless and served behind the ingress: roll back start-first so the serving task stays up until the old release is healthy.
       rollback_config:
         parallelism: 1
-        order: stop-first
+        order: start-first
       restart_policy:
         condition: on-failure
         delay: 5s
@@ -108,6 +111,7 @@ services:
         order: stop-first
         failure_action: rollback
         monitor: 30s
+      # The database owns a data volume and is single-writer: never run two at once, so rollback stays stop-first.
       rollback_config:
         parallelism: 1
         order: stop-first
@@ -140,6 +144,7 @@ services:
         order: stop-first
         failure_action: rollback
         monitor: 30s
+      # The ingress owns published ports and a certificate volume: never run two at once, so rollback stays stop-first.
       rollback_config:
         parallelism: 1
         order: stop-first

package/templates/app/skeleton-lite/.starcistacks/production/runtime/env/KEYS.md

@@ -1,6 +1,6 @@
 # Production environment key roster
 
-This inventory declares names, consumers and mounted file paths. Scaffolding generates the six declared encrypted members with placeholder values encrypted to this app's own age recipient. Replace their values through `starci app secret set production` after owner provisioning and before creating external secrets. The runtime template tracks no ciphertext; its specs generate members with ephemeral identities in disposable copies. Scaffolding supplies no deployment credential or successful deployment.
+This inventory declares names, consumers and mounted file paths. Scaffolding generates the six declared encrypted members with placeholder values encrypted to this app's own age recipient. Replace their values through `starci app secret set --env production` after owner provisioning and before creating external secrets. The runtime template tracks no ciphertext; its specs generate members with ephemeral identities in disposable copies. Scaffolding supplies no deployment credential or successful deployment.
 
 | Key | Consumer |
 | --- | --- |
@@ -15,13 +15,14 @@ This inventory declares names, consumers and mounted file paths. Scaffolding gen
 | `AUTH_JWT_ISSUER` | API access-token issuer |
 | `AUTH_JWT_AUDIENCE` | API access-token audience |
 | `AUTH_JWT_KEY_ID` | API signing key id, published in the JWKS |
+| `AUTH_COOKIE_DOMAIN` | API cookie `Domain` (a bare domain such as `example.com`, no scheme or port); optional while the web and the API share one host, required when they are served on different hosts, because a host-only refresh cookie never reaches the web server's forwarded `Cookie` header |
 | `AUTH_JWT_PRIVATE_KEY` | API ES256 signing key; reads `AUTH_JWT_PRIVATE_KEY_FILE` at `/run/secrets/auth-jwt-private-key` |
 | `STORAGE_ENDPOINT` | API S3-compatible storage endpoint |
 | `STORAGE_REGION` | API storage signing region |
 | `STORAGE_BUCKET` | API storage bucket |
 | `STORAGE_ACCESS_KEY_ID` | API storage credential; reads `STORAGE_ACCESS_KEY_ID_FILE` at `/run/secrets/storage-access-key-id` |
 | `STORAGE_SECRET_ACCESS_KEY` | API storage credential; reads `STORAGE_SECRET_ACCESS_KEY_FILE` at `/run/secrets/storage-secret-access-key` |
-| `DATABASE_URL` | `starci app db` verbs (migrate, dump, plan) and `contract:emit`, from the operator's environment |
+| `DATABASE_URL` | `starci app db` verbs (migrate, dump) and `contract:emit`, from the operator's environment |
 | `NEXT_PUBLIC_SITE_URL` | Front-end site URL |
 | `NEXT_PUBLIC_API_URL` | Front-end auth doors of the API |
 | `NEXT_PUBLIC_GRAPHQL_URL` | Front-end GraphQL transport |

package/templates/app/skeleton-lite/README.md

@@ -20,7 +20,7 @@ TypeScript everywhere, NestJS in `be/`, Next.js with next-intl in `fe/`, Postgre
 
 ## Status badges
 
-Declare `ci.github.repository` and `ci.github.defaultBranch` in `.starcistacks/application-stacks.yaml` (or set the GitHub `repository` URL in `package.json`), then run `npx starci app sync --write`. Sync inserts a managed badge block after the title; `npx starci app sync --check` verifies it.
+Declare `ci.github.repository` and `ci.github.defaultBranch` in `.starcistacks/application-stacks.yaml` (or set the GitHub `repository` URL in `package.json`), then run `npx starci app sync --execute`. Sync inserts a managed badge block after the title; `npx starci app sync` (the dry run) verifies it.
 
 ## Development
 
@@ -36,7 +36,7 @@ npm run build:be
 npm run build:fe
 ```
 
-The API reads `PORT`, `HTTP_SECURITY_ALLOWED_ORIGINS`, `PRIMARY_DB_URL`, `PRIMARY_DB_SCHEMA`, the Google OAuth keys `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` and `GOOGLE_CALLBACK_URL`, its own token keys `AUTH_JWT_ISSUER`, `AUTH_JWT_AUDIENCE`, `AUTH_JWT_KEY_ID` and `AUTH_JWT_PRIVATE_KEY`, and the storage keys `STORAGE_ENDPOINT`, `STORAGE_REGION`, `STORAGE_BUCKET`, `STORAGE_ACCESS_KEY_ID` and `STORAGE_SECRET_ACCESS_KEY`. The database tooling reads `DATABASE_URL`. The web app reads `NEXT_PUBLIC_SITE_URL`, `NEXT_PUBLIC_API_URL`, and, once the first GraphQL operation exists, `NEXT_PUBLIC_GRAPHQL_URL`. Missing configuration stops the relevant process with a named error; no template supplies credential defaults.
+The API reads `PORT`, `HTTP_SECURITY_ALLOWED_ORIGINS`, `PRIMARY_DB_URL`, `PRIMARY_DB_SCHEMA`, the Google OAuth keys `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` and `GOOGLE_CALLBACK_URL`, its own token keys `AUTH_JWT_ISSUER`, `AUTH_JWT_AUDIENCE`, `AUTH_JWT_KEY_ID` and `AUTH_JWT_PRIVATE_KEY`, the optional `AUTH_COOKIE_DOMAIN` (a bare domain such as `example.com`; required when the web and the API are served on different hosts, so the refresh cookie reaches the web server), and the storage keys `STORAGE_ENDPOINT`, `STORAGE_REGION`, `STORAGE_BUCKET`, `STORAGE_ACCESS_KEY_ID` and `STORAGE_SECRET_ACCESS_KEY`. The database tooling reads `DATABASE_URL`. The web app reads `NEXT_PUBLIC_SITE_URL`, `NEXT_PUBLIC_API_URL`, and, once the first GraphQL operation exists, `NEXT_PUBLIC_GRAPHQL_URL`. Missing configuration stops the relevant process with a named error; no template supplies credential defaults.
 
 Production browser build values live in `.starcistacks/application-stacks.yaml` under `environments.production.deploy.images.web.buildArgs.values`. Before building deployment images, replace the placeholders with your site's and your API's public origins. These values reach every browser; every credential stays in sealed runtime custody.
 

package/templates/be/skeleton/apps/cli/src/compose/platform.ts

@@ -20,7 +20,7 @@ const primaryConnectionOf = (primary: DatabaseConnectionConfig): DatabaseConnect
 export const platformModules = (options: CliAppOptions): Array<DynamicModule> => [
     ClockModule.register({ isGlobal: true }),
     IdsModule.register({ isGlobal: true }),
-    LoggingModule.register({ isGlobal: true }),
+    LoggingModule.register({ isGlobal: true, info: "stderr" }),
     HttpModule.register({ isGlobal: true }),
     DatabaseModule.register({
         isGlobal: true,

package/templates/be/skeleton/apps/cli/src/main.ts

@@ -10,7 +10,7 @@ import { createCliAppOptions } from "./cli.options"
 
 /** The command line of the back end: reads the environment once and runs the command its arguments name (`cli migrate run`). */
 async function bootstrap(): Promise<void> {
-    const logger = createJsonLogger(new SystemClockService(), new SystemIds())
+    const logger = createJsonLogger(new SystemClockService(), new SystemIds(), { info: "stderr" })
     await CommandFactory.run(AppModule.register(createCliAppOptions(readCliEnv(EnvSource.fromProcess()))), {
         logger: createNestLogger(logger),
         errorHandler: (error: Error) => {
@@ -21,8 +21,10 @@ async function bootstrap(): Promise<void> {
 }
 
 bootstrap().catch((error: unknown) => {
-    createJsonLogger(new SystemClockService(), new SystemIds()).error(LoggingLogEvent.StartupFailed, error, {
-        service: "cli",
-    })
+    createJsonLogger(new SystemClockService(), new SystemIds(), { info: "stderr" }).error(
+        LoggingLogEvent.StartupFailed,
+        error,
+        { service: "cli" },
+    )
     process.exit(1)
 })

package/templates/be/skeleton/src/modules/platform/config/env-source.config.ts

@@ -4,6 +4,7 @@ import { ConfigError, ConfigErrorCode } from "./errors/config.error"
 const FILE_SUFFIX = "_FILE"
 const DURATION_UNITS: Readonly<Record<string, number>> = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }
 const DURATION_PATTERN = /^(\d+)(ms|s|m|h)?$/
+const BARE_DOMAIN_PATTERN = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,61}[a-z0-9]$/
 
 /** A secret value (password, token, connection string with credentials): never logged, serialized as a mask. */
 export class Secret {
@@ -52,6 +53,17 @@ export class EnvSource {
         return this.values[key] || undefined
     }
 
+    /**
+     * The declared value of an optional bare domain (`example.com`: labels of letters, digits and hyphens, a letter-led
+     * top level; no scheme, port, path, leading dot or IP), lower-cased, or undefined. Any other value is a boot failure.
+     */
+    optionalDomain(key: string): string | undefined {
+        const value = this.optional(key)?.toLowerCase()
+        if (value === undefined) return undefined
+        if (!BARE_DOMAIN_PATTERN.test(value)) throw new ConfigError({ code: ConfigErrorCode.KeyInvalid, params: { key } })
+        return value
+    }
+
     /** A required string. */
     string(key: string): string {
         const value = this.values[key]

package/templates/be/skeleton/src/modules/platform/database/abstract.entity.ts

@@ -0,0 +1,19 @@
+import { Column, PrimaryGeneratedColumn } from "typeorm"
+
+/** The timestamp columns every table of a migration carries: an entity extends this base instead of declaring them; it maps no table itself. */
+export abstract class AbstractEntity {
+    /** When the row was created; the database sets it. */
+    @Column({ name: "created_at", type: "timestamptz", insert: false, update: false })
+    createdAt!: Date
+
+    /** When the row last changed; the database trigger sets it. */
+    @Column({ name: "updated_at", type: "timestamptz", insert: false, update: false })
+    updatedAt!: Date
+}
+
+/** The timestamp columns plus the generated uuid key `id`: the base of a table keyed by one uuid; a composite-key table extends AbstractEntity. */
+export abstract class UuidAbstractEntity extends AbstractEntity {
+    /** The row id. */
+    @PrimaryGeneratedColumn("uuid", { name: "id" })
+    id!: string
+}

package/templates/be/skeleton/src/modules/platform/database/database.module.ts

@@ -19,6 +19,12 @@ const ENTITY_MANAGER_TOKENS: ReadonlyMap<string, EntityManagerToken> = new Map<s
     [PRIMARY_CONNECTION, PRIMARY_ENTITY_MANAGER],
 ])
 
+/**
+ * How long a connection waits for its database at boot: 10 attempts 3 s apart (about 30 s), so an app that starts beside the db
+ * service of its stack outlives the database's own start instead of exiting and rolling the release back.
+ */
+const CONNECT_RETRY = { retryAttempts: 10, retryDelay: 3000 } as const
+
 @Module({})
 /**
  * The database capability: opens one named TypeORM connection per entry of the options and provides its shared
@@ -54,7 +60,7 @@ export class DatabaseModule extends ConfigurableModuleClass {
                         url: connection.url.reveal(),
                         entities: [...connection.entities],
                         synchronize: false,
-                        retryAttempts: 2,
+                        ...CONNECT_RETRY,
                     }),
                 ),
             ],

package/templates/be/skeleton/src/modules/platform/logging/json-logger.service.spec.ts

@@ -144,6 +144,25 @@ describe("createJsonLogger", () => {
             `err:${JSON.stringify({ correlationId: "00000000-0000-4000-8000-000000000001", level: "warn", event: LoggingLogEvent.StartupFailed, time: "2026-05-06T07:08:09.000Z" })}\n`,
         ])
     })
+
+    it("sends info to stderr, leaving stdout untouched, when the info option is stderr", () => {
+        const lines: Array<string> = []
+        jest.spyOn(process.stdout, "write").mockImplementation((chunk) => lines.push(`out:${String(chunk)}`) > 0)
+        jest.spyOn(process.stderr, "write").mockImplementation((chunk) => lines.push(`err:${String(chunk)}`) > 0)
+        const logger = createJsonLogger(new FakeClock("2026-05-06T07:08:09.000Z"), fakeIds(), { info: "stderr" })
+        logger.info(LoggingLogEvent.ServerStarted)
+        logger.warn(LoggingLogEvent.StartupFailed)
+        expect(lines.map((line) => line.slice(0, 4))).toEqual(["err:", "err:"])
+    })
+
+    it("keeps info on stdout when the info option is stdout", () => {
+        const lines: Array<string> = []
+        jest.spyOn(process.stdout, "write").mockImplementation((chunk) => lines.push(`out:${String(chunk)}`) > 0)
+        createJsonLogger(new FakeClock("2026-05-06T07:08:09.000Z"), fakeIds(), { info: "stdout" }).info(
+            LoggingLogEvent.ServerStarted,
+        )
+        expect(lines.map((line) => line.slice(0, 4))).toEqual(["out:"])
+    })
 })
 
 describe("JsonLoggerService correlation", () => {

package/templates/be/skeleton/src/modules/platform/logging/json-logger.service.ts

@@ -5,6 +5,7 @@ import { InjectIds } from "@modules/platform/ids"
 import type { Ids } from "@modules/platform/ids"
 import { stampLogFields } from "./correlation.policy"
 import { InjectLogErr, InjectLogOut } from "./logging.decorators"
+import type { LoggingOptions } from "./logging.options"
 import type { LogFields, Logger } from "./logging.port"
 
 type Level = "info" | "warn" | "error"
@@ -50,6 +51,6 @@ export class JsonLoggerService implements Logger {
     }
 }
 
-/** Builds the JSON logger stamping lines with `clock` on stdout and stderr; main.ts uses it before the DI container exists. */
-export const createJsonLogger = (clock: Clock, ids: Ids): Logger =>
-    new JsonLoggerService(clock, process.stdout, process.stderr, ids)
+/** Builds the JSON logger stamping lines with `clock`: info on stdout (or stderr when `options.info` says so), warn and error on stderr; main.ts uses it before the DI container exists. */
+export const createJsonLogger = (clock: Clock, ids: Ids, options: LoggingOptions = {}): Logger =>
+    new JsonLoggerService(clock, options.info === "stderr" ? process.stderr : process.stdout, process.stderr, ids)

package/templates/be/skeleton/src/modules/platform/logging/logging.module.ts

@@ -25,7 +25,7 @@ export class LoggingModule extends ConfigurableModuleClass {
                 {
                     provide: LOGGER,
                     inject: [CLOCK, IDS],
-                    useFactory: (clock: Clock, ids: Ids) => createJsonLogger(clock, ids),
+                    useFactory: (clock: Clock, ids: Ids) => createJsonLogger(clock, ids, options),
                 },
             ],
             exports: [LOGGER, CORRELATION_IDS, CORRELATION_RUNNER],

package/templates/be/skeleton/src/modules/platform/logging/logging.options.ts

@@ -1,2 +1,5 @@
-/** The logging capability takes no options; the empty record keeps `isGlobal` assignable through the configurable module. */
-export type LoggingOptions = Record<never, never>
+/** Options of the logging capability. */
+export interface LoggingOptions {
+    /** The stream info lines go to: "stdout" (default) for servers, "stderr" for a CLI whose stdout carries only command output. Warn and error always go to stderr. */
+    readonly info?: "stdout" | "stderr"
+}

package/templates/be/skeleton-lite/apps/cli/src/compose/platform.ts

@@ -11,7 +11,7 @@ import type { CliAppOptions } from "../cli.options"
 export const platformModules = (options: CliAppOptions): Array<DynamicModule> => [
     ClockModule.register({ isGlobal: true }),
     IdsModule.register({ isGlobal: true }),
-    LoggingModule.register({ isGlobal: true }),
+    LoggingModule.register({ isGlobal: true, info: "stderr" }),
     HttpModule.register({ isGlobal: true }),
     DatabaseModule.register({ isGlobal: true, connections: options.connections, entities: PRIMARY_ENTITIES }),
 ]

package/templates/be/skeleton-lite/src/modules/integrations/passport/passport.config.spec.ts

@@ -0,0 +1,40 @@
+import { Test } from "@nestjs/testing"
+import { EnvSource } from "@modules/platform/config"
+import { parsePassportConfig } from "./passport.config"
+
+const CONFIG: unique symbol = Symbol("passport.config")
+
+const REQUIRED = {
+    GOOGLE_CLIENT_ID: "client",
+    GOOGLE_CLIENT_SECRET: "client-secret",
+    GOOGLE_CALLBACK_URL: "https://api.example.com/auth/google/callback",
+    AUTH_JWT_ISSUER: "https://api.example.com",
+    AUTH_JWT_AUDIENCE: "app",
+    AUTH_JWT_PRIVATE_KEY: "key",
+    AUTH_JWT_KEY_ID: "kid-1",
+}
+
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({ providers: [{ provide: CONFIG, useValue: { parsePassportConfig } }] }).compile()
+    return moduleRef.get<{ parsePassportConfig: typeof parsePassportConfig }>(CONFIG)
+}
+
+const parse = async (extra: Record<string, string>) => (await build()).parsePassportConfig(new EnvSource({ ...REQUIRED, ...extra }))
+
+describe("AUTH_COOKIE_DOMAIN", () => {
+    it("leaves the refresh cookie host-only when the key is not declared", async () => {
+        expect((await parse({})).refresh.cookieDomain).toBeUndefined()
+    })
+
+    it("reads a bare registrable domain", async () => {
+        expect((await parse({ AUTH_COOKIE_DOMAIN: "example.com" })).refresh.cookieDomain).toBe("example.com")
+        expect((await parse({ AUTH_COOKIE_DOMAIN: "Sub.Example.CO.uk" })).refresh.cookieDomain).toBe("sub.example.co.uk")
+    })
+
+    it.each(["https://example.com", "example.com:443", "example.com/path", ".example.com", "localhost", "127.0.0.1", "exa mple.com", "-a.example.com"])(
+        "refuses %s at boot, naming the key",
+        async (value) => {
+            await expect(parse({ AUTH_COOKIE_DOMAIN: value })).rejects.toMatchObject({ code: "CONFIG_KEY_INVALID", params: { key: "AUTH_COOKIE_DOMAIN" } })
+        },
+    )
+})

package/templates/be/skeleton-lite/src/modules/integrations/passport/passport.config.ts

@@ -19,5 +19,6 @@ export const parsePassportConfig = (env: EnvSource): PassportOptions => ({
         name: "refresh_token",
         path: "/auth/refresh",
         ttlSeconds: env.int("AUTH_REFRESH_TTL_SECONDS", 2_592_000),
+        cookieDomain: env.optionalDomain("AUTH_COOKIE_DOMAIN"),
     },
 })