@starci/hfs 4.3.0 → 4.4.1

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

@@ -1,11 +1,144 @@
-# The stack declaration of the app, at the app root beside be/, fe/ and .starciwork (never under a side).
+# The app declares its topology before any owner provisions a deployment.
+# All-zero application digests are illustrative and must be replaced by verified release digests.
 schema: starci/application-stacks@1
+sources:
+  - repository: "{{project}}"
+backing:
+  primary:
+    provider: external-postgres
+    managed: true
+components:
+  core:
+    role: service
+    image: "{{project}}/core:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  app:
+    role: service
+    image: "{{project}}/app:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  landing:
+    role: service
+    image: "{{project}}/landing:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  ingress:
+    role: ingress
+    stateful: true
+    volumes: [ingress-data, ingress-config-data]
+    image: caddy:2.10.2@sha256:c3d7ee5d2b11f9dc54f947f68a734c84e9c9666c92c88a7f30b9cba5da182adb
+    purpose: The single public entry point; TLS state stays on its declared persistent volume.
+  postgres:
+    role: stateful
+    image: postgres:16@sha256:1a6ab3f5345eb6dbe04a1349529caabdb0ab09293a09590fad07b2246bfa4b54
+    purpose: The full development database; production uses an owner-provisioned external PostgreSQL connection.
+environments:
+  dev:
+    status: supported
+    runtime: docker-compose
+    composeFiles: [infra/compose/stack.yaml]
+    components:
+      core: { port: 3001 }
+      app: { port: 3000 }
+      landing: { port: 3002 }
+      postgres: { port: 5432 }
+    runbook: README.md
+    # Custody starts empty; add real sealed members after owner provisioning.
+    secrets: []
+  production:
+    status: supported
+    runtime: docker-swarm
+    composeFiles: [infra/swarm/stack.yaml]
+    components:
+      core: { port: 3001 }
+      app: { port: 3000 }
+      landing: { port: 3002 }
+      ingress: { httpPort: 80, httpsPort: 443 }
+    runbook: README.md
+    ingress:
+      component: ingress
+      hosts: ["{{project}}.example.invalid", "api.{{project}}.example.invalid", "www.{{project}}.example.invalid"]
+    dns:
+      - host: "{{project}}.example.invalid"
+        owner: Production operator
+        receipt: .starcistacks/production/infra/swarm/owner-actions.md#dns
+      - host: "api.{{project}}.example.invalid"
+        owner: Production operator
+        receipt: .starcistacks/production/infra/swarm/owner-actions.md#dns
+      - host: "www.{{project}}.example.invalid"
+        owner: Production operator
+        receipt: .starcistacks/production/infra/swarm/owner-actions.md#dns
+    tls:
+      owner: Production operator
+      receipt: .starcistacks/production/infra/swarm/owner-actions.md#tls
+    release:
+      imagesLock: .starcistacks/production/infra/swarm/releases/images.lock.yaml
+      pointer: .starcistacks/production/infra/swarm/releases/current.yaml
+      previous: .starcistacks/production/infra/swarm/releases/previous.yaml
+      healthAssertions: [API /health/live, API /health/ready, App /health/live, Landing /health/live, Signed-in GraphQL request over TLS]
+    backup:
+      - component: ingress
+        target: Owner-provisioned encrypted off-host storage for both ingress volumes
+        retention: Thirty daily snapshots
+        owner: Production operator
+        restoreProof: .starcistacks/production/infra/swarm/recovery/restore-proof.md
+      - component: primary
+        target: Provider recovery plus owner-provisioned encrypted off-host database exports
+        retention: Thirty daily exports
+        owner: Production operator
+        restoreProof: .starcistacks/production/infra/swarm/recovery/restore-proof.md
+    # Scaffolding seals generated placeholders to this app's own recipient; set real values before use.
+    secrets:
+      - name: primary-db-url
+        runtimeName: "{{project}}-production-primary-db-url-v1"
+        version: 1
+        where: secrets/primary-db-url
+        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.
+    # Add secrets.grants once the real sealed members exist under .starcistacks/production/secrets, and a backup block for stateful volumes.
+    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
+      # and `starci app sync` never rewrites it. While it is public, `starci app stack build --push` scans every image for secret material first.
+      registry:
+        host: ghcr.io
+        visibility: {{registryVisibility}}
+      images:
+        core:
+          app: core
+        app:
+          app: app
+        landing:
+          app: landing
+      volumes:
+        - {{project}}-production-ingress-data
+        - {{project}}-production-ingress-config-data
+      verify:
+        http:
+          - name: core liveness
+            url: "https://api.{{project}}.example.invalid/health/live"
+            status: 200
+            retry: true
+          - name: app liveness
+            url: "https://{{project}}.example.invalid/health/live"
+            status: 200
+            retry: true
+          - name: landing liveness
+            url: "https://www.{{project}}.example.invalid/health/live"
+            status: 200
+            retry: true
+k8s:
+  status: deferred
+  reason: This starter declares Docker Swarm production; no Kubernetes environment is provisioned.
 services:
   sonar:
     provider: sonarqube
     mode: local
     qualityGate: {{sonarGate}}
+    host: { local: http://127.0.0.1:9000 }
     stack:
       owner: host
       root: .claude/ext/sonar
       environment: dev
+      compose: compose.yaml
+    auth: token
+    ci: { wiring: optional-follow-up }
+    ownerAction:
+      needed: Provision the shared host Sonar project and its analysis credential through sealed custody.
+      reason: A fresh app declares its quality service without fabricating credentials or a successful analysis.

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

@@ -0,0 +1,16 @@
+# Development stack
+
+The development Docker Compose model contains the core API, the product and landing front ends, and a pinned local PostgreSQL database. Trust authentication is confined to this local, unpublished database.
+Starter release images and external secrets must be prepared before starting the container model. Local source development remains available through the app scripts.
+
+| Command | Operation |
+| --- | --- |
+| prepare | Build the app images and provide the local database connection through sealed custody. Materialize its real sealed member to the owner-controlled file `/run/starci-secrets/{{project}}/dev/primary-db-url`; Docker Compose mounts that file into the API. |
+| doctor | From this directory, run `docker compose config -f infra/compose/stack.yaml`. Confirm image, secret and database availability. |
+| up | Run `docker compose -f infra/compose/stack.yaml up -d` from this directory after preparation. |
+| status | Run `docker compose -f infra/compose/stack.yaml ps`. |
+| logs | Run `docker compose -f infra/compose/stack.yaml logs core`; never print mounted credentials. |
+| down | Run `docker compose -f infra/compose/stack.yaml down`. |
+| verification | Confirm the API `/health/live` and `/health/ready` endpoints, then run `npm run lint` from the app root. |
+
+Keep real sealed members under `.starcistacks/dev/secrets/*.enc`, add them to the manifest after sealing and inventory their key names in the environment record. The scaffold creates no fake secret or successful proof.

package/templates/app/skeleton/.starcistacks/dev/environment.json

@@ -0,0 +1,5 @@
+{
+  "environment": "dev",
+  "provider": "docker-compose",
+  "project": "{{project}}"
+}

package/templates/app/skeleton/.starcistacks/dev/infra/compose/stack.yaml

@@ -0,0 +1,71 @@
+# Rendered development model. App images and owner infrastructure must be provisioned before use.
+version: "3.8"
+services:
+  core:
+    image: "{{project}}/core:v0.0.0"
+    environment:
+      NODE_ENV: development
+      PORT: "3001"
+      HTTP_SECURITY_ALLOWED_ORIGINS: http://127.0.0.1:3000
+      PRIMARY_DB_URL_FILE: /run/secrets/primary-db-url
+    secrets:
+      - source: primary-db-url
+        target: primary-db-url
+    ports: ["3001:3001"]
+    networks: [app]
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3001/health/live').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 30s
+      timeout: 5s
+      start_period: 20s
+      retries: 3
+  app:
+    image: "{{project}}/app:v0.0.0"
+    environment:
+      NODE_ENV: development
+      PORT: "3000"
+      HOSTNAME: 0.0.0.0
+      NEXT_PUBLIC_SITE_URL: http://127.0.0.1:3000
+    ports: ["3000:3000"]
+    networks: [app]
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health/live').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 30s
+      timeout: 5s
+      start_period: 20s
+      retries: 3
+  landing:
+    image: "{{project}}/landing:v0.0.0"
+    environment:
+      NODE_ENV: development
+      PORT: "3002"
+      HOSTNAME: 0.0.0.0
+      NEXT_PUBLIC_APP_URL: http://127.0.0.1:3000
+    ports: ["3002:3002"]
+    networks: [app]
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3002/health/live').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 30s
+      timeout: 5s
+      start_period: 20s
+      retries: 3
+  postgres:
+    image: postgres:16@sha256:1a6ab3f5345eb6dbe04a1349529caabdb0ab09293a09590fad07b2246bfa4b54
+    environment:
+      POSTGRES_DB: "{{project}}"
+      POSTGRES_HOST_AUTH_METHOD: trust
+    volumes: [postgres-data:/var/lib/postgresql/data]
+    networks: [app]
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d {{project}}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+networks:
+  app:
+    driver: bridge
+secrets:
+  primary-db-url:
+    file: /run/starci-secrets/{{project}}/dev/primary-db-url
+volumes:
+  postgres-data:

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

@@ -0,0 +1,14 @@
+# Environment key roster
+
+This roster declares names only. Store credential values in sealed custody and materialize private KEY files outside the repository.
+
+| Key | Consumer |
+| --- | --- |
+| `PORT` | API listener |
+| `HTTP_SECURITY_ALLOWED_ORIGINS` | API origin allowlist |
+| `PRIMARY_DB_URL` | API and CLI primary database connection |
+| `NEXT_PUBLIC_SITE_URL` | Product front-end site URL |
+| `NEXT_PUBLIC_GRAPHQL_URL` | Product front-end GraphQL transport |
+| `NEXT_PUBLIC_APP_URL` | Landing front-end product link |
+
+Public front-end configuration is supplied at build time and stays outside sealed custody.

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

@@ -0,0 +1,37 @@
+# Production stack
+
+The tracked model declares Docker Swarm application services and one digest-pinned Caddy ingress.
+The production database is external PostgreSQL; the owner supplies its least-privilege connection through sealed custody.
+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 member with a placeholder value encrypted to this app's own recipient in `.sops.yaml`. Replace it with `starci app secret set production` using the matching host age identity in untracked local custody. Each Docker secret contains its corresponding key's real value; the API receives it through the 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. |
+| 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. |
+
+## Owner actions before the first release
+
+Every item is pending. Swarm initialization, provider URIs, DNS changes and key rotation are owner-run steps.
+
+| Area | Required owner action and evidence |
+| --- | --- |
+| 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 product, API and landing 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 external PostgreSQL and its least-privilege application role. Record the provider URI and recovery owner without copying credentials here. |
+| Secret custody | Replace the generated placeholder with the real value in the manifest's declared `.starcistacks/production/secrets/primary-db-url.enc`; record its key in `.starcistacks/production/runtime/env/KEYS.md`. The age identity stays only in the host's untracked `.claude/secret.env`. |
+| External secrets | Materialize the sealed members in owner custody and create `{{project}}-production-primary-db-url-v1`. 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 and GraphQL URLs. Public browser values stay outside sealed secret custody. |
+| Immutable release | Replace the illustrative all-zero application digests in the manifest, model and `.starcistacks/production/infra/swarm/releases/images.lock.yaml` with the verified release digests. Store each rendered release under `/srv/{{project}}/releases/<digest>`. Retain the last accepted record in `.starcistacks/production/infra/swarm/releases/previous.yaml`, then move the pointer and update `.starcistacks/production/infra/swarm/releases/current.yaml` after verification. |
+| Rollback | Retain the previous model and images, redeploy that model if convergence or health fails, and record the resulting convergence receipt. Database changes follow an expand/contract sequence. |
+| Backup | Provision the manifest's thirty daily encrypted off-host database exports and ingress-volume snapshots. Record the actual destination and encryption custody in `.starcistacks/production/infra/swarm/recovery/restore-proof.md`; the production operator owns both components. |
+| Restore proof | Perform a restore into isolated infrastructure, verify the restored database and ingress state, and attach a dated receipt with artifact digests to `.starcistacks/production/infra/swarm/recovery/restore-proof.md`. Its initial record is pending; no restore has been run by scaffolding. |
+
+No host scheduler is installed. Scheduled application work belongs to the back-end scheduler or an explicitly declared replicated job.

package/templates/app/skeleton/.starcistacks/production/environment.json

@@ -0,0 +1,5 @@
+{
+  "environment": "production",
+  "provider": "external-postgres",
+  "project": "{{project}}"
+}

package/templates/app/skeleton/.starcistacks/production/infra/swarm/Caddyfile

@@ -0,0 +1,15 @@
+{
+    admin 127.0.0.1:2019
+}
+
+{{project}}.example.invalid {
+    reverse_proxy app:3000
+}
+
+api.{{project}}.example.invalid {
+    reverse_proxy core:3001
+}
+
+www.{{project}}.example.invalid {
+    reverse_proxy landing:3002
+}

package/templates/app/skeleton/.starcistacks/production/infra/swarm/owner-actions.md

@@ -0,0 +1,11 @@
+# Production prerequisite record
+
+Status: pending owner execution. This record states intended configuration and contains no completed operational receipt.
+
+## DNS
+
+The production operator replaces `{{project}}.example.invalid`, `api.{{project}}.example.invalid` and `www.{{project}}.example.invalid` with owned public names, updates the manifest, Caddyfile and public configuration together, and publishes address records for the intended Swarm node. Record the provider, zone, actual hosts and dated DNS receipt here.
+
+## TLS
+
+The production operator provisions both external ingress volumes on the declared node and owns Caddy certificate issuance and renewal. After real DNS resolves, record a dated issuance receipt, persistent certificate custody and HTTPS verification for all three public hosts here.

package/templates/app/skeleton/.starcistacks/production/infra/swarm/recovery/restore-proof.md

@@ -0,0 +1,7 @@
+# Production recovery record
+
+Status: pending owner execution. No backup or restore has been run by scaffolding.
+
+The production operator owns recovery of the external PostgreSQL database and both external ingress volumes, `{{project}}-production-ingress-data` and `{{project}}-production-ingress-config-data`. Provision provider recovery and thirty daily encrypted off-host database exports. Retain thirty daily encrypted off-host snapshots for both ingress volumes.
+
+Before relying on the backup policy, restore a database backup and both volume snapshots into isolated infrastructure. Record the actual off-host destination, retention, encryption custody, backup artifact digests, restoration time and operator. Verify database connectivity and the API readiness endpoint, then verify the restored TLS and ingress configuration. Attach the dated result here without credentials.

package/templates/app/skeleton/.starcistacks/production/infra/swarm/releases/current.yaml

@@ -0,0 +1,6 @@
+schema: starci/release-pointer@1
+environment: production
+status: pending-owner-release
+release: null
+verification: null
+# Write a real /srv/{{project}}/releases/<digest> reference and dated health receipt only after verification.

package/templates/app/skeleton/.starcistacks/production/infra/swarm/releases/images.lock.yaml

@@ -0,0 +1,9 @@
+# Illustrative inventory only. Replace application digests with verified published images.
+schema: starci/images-lock@1
+environment: production
+status: pending-owner-release
+images:
+  core: "{{project}}/core:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  app: "{{project}}/app:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  landing: "{{project}}/landing:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  ingress: caddy:2.10.2@sha256:c3d7ee5d2b11f9dc54f947f68a734c84e9c9666c92c88a7f30b9cba5da182adb

package/templates/app/skeleton/.starcistacks/production/infra/swarm/releases/previous.yaml

@@ -0,0 +1,6 @@
+schema: starci/release-pointer@1
+environment: production
+status: no-previous-release
+release: null
+verification: null
+# Before moving current, retain the last accepted release here for rollback.

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

@@ -0,0 +1,142 @@
+# Rendered production model. All-zero app digests are illustrative; publish verified images before use.
+version: "3.8"
+services:
+  core:
+    image: "{{project}}/core:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
+    environment:
+      NODE_ENV: production
+      PORT: "3001"
+      HTTP_SECURITY_ALLOWED_ORIGINS: https://{{project}}.example.invalid
+      PRIMARY_DB_URL_FILE: /run/secrets/primary-db-url
+    secrets:
+      - source: primary-db-url
+        target: primary-db-url
+    networks: [app]
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3001/health/live').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 30s
+      timeout: 5s
+      start_period: 20s
+      retries: 3
+    deploy:
+      replicas: 1
+      placement:
+        constraints: ["node.labels.{{project}} == production"]
+      update_config:
+        parallelism: 1
+        order: start-first
+        failure_action: rollback
+        monitor: 30s
+      rollback_config:
+        parallelism: 1
+        order: stop-first
+      restart_policy:
+        condition: on-failure
+        delay: 5s
+  app:
+    image: "{{project}}/app:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
+    environment:
+      NODE_ENV: production
+      PORT: "3000"
+      HOSTNAME: 0.0.0.0
+      NEXT_PUBLIC_SITE_URL: https://{{project}}.example.invalid
+    networks: [app]
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health/live').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 30s
+      timeout: 5s
+      start_period: 20s
+      retries: 3
+    deploy:
+      replicas: 1
+      placement:
+        constraints: ["node.labels.{{project}} == production"]
+      update_config:
+        parallelism: 1
+        order: start-first
+        failure_action: rollback
+        monitor: 30s
+      rollback_config:
+        parallelism: 1
+        order: stop-first
+      restart_policy:
+        condition: on-failure
+        delay: 5s
+  landing:
+    image: "{{project}}/landing:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
+    environment:
+      NODE_ENV: production
+      PORT: "3002"
+      HOSTNAME: 0.0.0.0
+      NEXT_PUBLIC_APP_URL: https://{{project}}.example.invalid
+    networks: [app]
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3002/health/live').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 30s
+      timeout: 5s
+      start_period: 20s
+      retries: 3
+    deploy:
+      replicas: 1
+      placement:
+        constraints: ["node.labels.{{project}} == production"]
+      update_config:
+        parallelism: 1
+        order: start-first
+        failure_action: rollback
+        monitor: 30s
+      rollback_config:
+        parallelism: 1
+        order: stop-first
+      restart_policy:
+        condition: on-failure
+        delay: 5s
+  ingress:
+    image: caddy:2.10.2@sha256:c3d7ee5d2b11f9dc54f947f68a734c84e9c9666c92c88a7f30b9cba5da182adb
+    configs:
+      - source: ingress-config
+        target: /etc/caddy/Caddyfile
+    ports:
+      - { target: 80, published: 80, protocol: tcp, mode: ingress }
+      - { target: 443, published: 443, protocol: tcp, mode: ingress }
+    volumes:
+      - ingress-data:/data
+      - ingress-config-data:/config
+    networks: [app]
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:2019/config/"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+    deploy:
+      replicas: 1
+      placement:
+        constraints: ["node.labels.{{project}} == production"]
+      update_config:
+        parallelism: 1
+        order: stop-first
+        failure_action: rollback
+        monitor: 30s
+      rollback_config:
+        parallelism: 1
+        order: stop-first
+      restart_policy:
+        condition: on-failure
+        delay: 5s
+networks:
+  app:
+    driver: overlay
+secrets:
+  primary-db-url:
+    external: true
+    name: "{{project}}-production-primary-db-url-v1"
+configs:
+  ingress-config:
+    file: ./Caddyfile
+volumes:
+  ingress-data:
+    external: true
+    name: "{{project}}-production-ingress-data"
+  ingress-config-data:
+    external: true
+    name: "{{project}}-production-ingress-config-data"

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

@@ -0,0 +1,14 @@
+# Production environment key roster
+
+This inventory declares names, consumers and mounted file paths. Scaffolding seals a generated database placeholder to this app's own recipient. Replace it with the real credential before use; no successful deployment is claimed by scaffolding.
+
+| Key | Consumer |
+| --- | --- |
+| `PORT` | Core API listener |
+| `HTTP_SECURITY_ALLOWED_ORIGINS` | Core API origin allowlist |
+| `PRIMARY_DB_URL` | Core API and CLI primary database connection; the API reads `PRIMARY_DB_URL_FILE` at `/run/secrets/primary-db-url` |
+| `NEXT_PUBLIC_SITE_URL` | Product front-end site URL |
+| `NEXT_PUBLIC_GRAPHQL_URL` | Product front-end GraphQL transport |
+| `NEXT_PUBLIC_APP_URL` | Landing front-end product link |
+
+Public front-end configuration is supplied at build time and stays outside sealed custody. Replace the generated private placeholder only in `.starcistacks/production/secrets/primary-db-url.enc`, already declared by the manifest. The versioned external database secret is `{{project}}-production-primary-db-url-v1`.

package/templates/app/skeleton/README.md

@@ -1,19 +1,19 @@
 # {{project}}
 
-One StarCi app: its back end in be/, its front end in fe/, one install at the root.
+One StarCi app: its back end in `be/`, its front end in `fe/`, one install at the root.
 
 ## Overview
 
-The app starts with the core api app (be/apps/core) and the cli app (be/apps/cli) over one primary database, two Next apps (fe/apps/landing, the public front door, and fe/apps/app, the product) over the shared packages fe/packages/{{project}}-ui and fe/packages/{{project}}-i18n.
+The app starts with the core api app (`be/apps/core`) and the cli app (`be/apps/cli`) over one primary database, two Next apps (`fe/apps/landing`, the public front door, and `fe/apps/app`, the product) over the shared packages `fe/packages/{{project}}-ui` and `fe/packages/{{project}}-i18n`.
 
 ## Stack
 
-TypeScript everywhere; NestJS in be/, Next.js with next-intl in fe/; npm with one package.json and one lockfile at the root.
+TypeScript everywhere; NestJS in `be/`, Next.js with next-intl in `fe/`; npm with one `package.json` and one lockfile at the root.
 
 ## Repository layout
 
-- `be/`: the back end, `apps/<app>/src` composes `src/features` and `src/modules`; its tests live under `src/tests`.
-- `fe/`: the front end, one Next app per `apps/<app>` and the shared workspace packages under `packages/` (the ui drawings and the next-intl stack both apps call).
+- `be/`: the back end, `be/apps/<app>/src` composes `be/src/features` and `be/src/modules`; its tests live under `be/src/tests`.
+- `fe/`: the front end, one Next app per `fe/apps/<app>` and the shared workspace packages under `fe/packages/` (the ui drawings and the next-intl stack both apps call).
 - `scripts/`: the app's operational scripts; `hfs.json` declares both sides.
 
 ## Development
@@ -31,7 +31,7 @@ The core api app reads `PORT`, `HTTP_SECURITY_ALLOWED_ORIGINS` (comma-separated
 requests) and `PRIMARY_DB_URL` at boot; every door is closed until it is marked public or sign-in is designed. The cli app reads
 `PRIMARY_DB_URL`: `npm run migrate` applies the migrations of the primary database before the api starts, and
 `npm run cli -- seed run` runs the dev seeds of `.starcistacks/dev/seeds` (run both from the app root). The product app reads
-`NEXT_PUBLIC_SITE_URL` and `NEXT_PUBLIC_GRAPHQL_URL` (the back end it calls through `src/modules/api`, read once the first GraphQL operation exists), the landing `NEXT_PUBLIC_APP_URL` (the product app it hands the reader over to). A missing key stops the process with an error that names it.
+`NEXT_PUBLIC_SITE_URL` and `NEXT_PUBLIC_GRAPHQL_URL` (the back end it calls through `fe/apps/app/src/modules/api`, read once the first GraphQL operation exists), the landing `NEXT_PUBLIC_APP_URL` (the product app it hands the reader over to). A missing key stops the process with an error that names it.
 
 ## Work
 

package/templates/app/skeleton/scripts/codegen.mjs

@@ -1,7 +1,6 @@
 // codegen.mjs - the app's generated code, the one step behind `npm run codegen` (lint, typecheck, dev and build run it first).
 // The front end reads the back end's committed contracts in place (be/contracts/, hfs.json sides.fe.reads) and generates its
 // client from them into a gitignored __generated__/ folder. A new app has no contract yet, so there is nothing to generate.
-import fs from "node:fs"
-import path from "node:path"
+// {{> app/codegen-prelude.mjs.partial}}
 
 // {{> app/codegen-graphql.mjs.partial}}

package/templates/app/skeleton-lite/.editorconfig

@@ -0,0 +1,16 @@
+{{header}}
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{json,yml,yaml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

package/templates/app/skeleton-lite/.gitattributes

@@ -0,0 +1,8 @@
+{{header}}
+* text=auto eol=lf
+*.enc binary
+# Scripts and the deploy data are mounted into Linux containers: CRLF there fails (set: Illegal option -).
+*.sh text eol=lf
+*.mjs text eol=lf
+.starcistacks/** text eol=lf
+.starcistacks/**/*.enc binary

package/templates/app/skeleton-lite/.github/dependabot.yml

@@ -0,0 +1,17 @@
+{{header}}
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: docker
+    directories:
+      - /be/apps/*
+      - /fe/apps/*
+    schedule:
+      interval: weekly

package/templates/app/skeleton-lite/.nvmrc

@@ -0,0 +1 @@
+{{nodeMajor}}

package/templates/app/skeleton-lite/.sops.yaml

@@ -1,3 +1,4 @@
-# Lite secrets have encrypted twins only under .starcistacks/<environment>/secrets.
-# Run `starci app secret init` to set a project-owned age recipient before encrypting the first secret.
+# The runtime template tracks no sealed members or shared recipient.
+# Scaffolding configures this app's own age recipient and generates sealed placeholders.
+# The private identity lives only in untracked .claude/secret.env as SOPS_AGE_KEY.
 creation_rules: []