@ultimat3/cli 27.11.0 → 27.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "27.11.0",
+  "version": "27.12.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -39,33 +39,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "27.11.0",
-    "@ultimat3/admin": "27.11.0",
-    "@ultimat3/ai": "27.11.0",
-    "@ultimat3/auth": "27.11.0",
-    "@ultimat3/cache": "27.11.0",
-    "@ultimat3/core": "27.11.0",
-    "@ultimat3/db": "27.11.0",
-    "@ultimat3/entity": "27.11.0",
-    "@ultimat3/flags": "27.11.0",
-    "@ultimat3/http": "27.11.0",
-    "@ultimat3/i18n": "27.11.0",
-    "@ultimat3/jobs": "27.11.0",
-    "@ultimat3/mail": "27.11.0",
-    "@ultimat3/manifest": "27.11.0",
-    "@ultimat3/mcp": "27.11.0",
-    "@ultimat3/money": "27.11.0",
-    "@ultimat3/notify": "27.11.0",
-    "@ultimat3/policy": "27.11.0",
-    "@ultimat3/pwa": "27.11.0",
-    "@ultimat3/query": "27.11.0",
-    "@ultimat3/realtime": "27.11.0",
-    "@ultimat3/render": "27.11.0",
-    "@ultimat3/schema": "27.11.0",
-    "@ultimat3/seo": "27.11.0",
-    "@ultimat3/storage": "27.11.0",
-    "@ultimat3/testing": "27.11.0",
-    "@ultimat3/time": "27.11.0",
+    "@ultimat3/action": "27.12.0",
+    "@ultimat3/admin": "27.12.0",
+    "@ultimat3/ai": "27.12.0",
+    "@ultimat3/auth": "27.12.0",
+    "@ultimat3/cache": "27.12.0",
+    "@ultimat3/core": "27.12.0",
+    "@ultimat3/db": "27.12.0",
+    "@ultimat3/entity": "27.12.0",
+    "@ultimat3/flags": "27.12.0",
+    "@ultimat3/http": "27.12.0",
+    "@ultimat3/i18n": "27.12.0",
+    "@ultimat3/jobs": "27.12.0",
+    "@ultimat3/mail": "27.12.0",
+    "@ultimat3/manifest": "27.12.0",
+    "@ultimat3/mcp": "27.12.0",
+    "@ultimat3/money": "27.12.0",
+    "@ultimat3/notify": "27.12.0",
+    "@ultimat3/policy": "27.12.0",
+    "@ultimat3/pwa": "27.12.0",
+    "@ultimat3/query": "27.12.0",
+    "@ultimat3/realtime": "27.12.0",
+    "@ultimat3/render": "27.12.0",
+    "@ultimat3/schema": "27.12.0",
+    "@ultimat3/seo": "27.12.0",
+    "@ultimat3/storage": "27.12.0",
+    "@ultimat3/testing": "27.12.0",
+    "@ultimat3/time": "27.12.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/templates/github/ci.yml.ts

@@ -11,6 +11,7 @@
 
 import { REQUIRED_BUN } from '../../app-root';
 import type { GeneratedFile, NameSet } from '../naming';
+import { TEST_COMPOSE_PATH, TEST_ENV_PATH } from '../scaffold-test-services';
 import { IMAGE_WORKFLOW_PATH, imageWorkflow } from './image.yml';
 import { RUNS_ON } from './runner';
 
@@ -39,9 +40,9 @@ const ci = (app: NameSet): string => `name: ${CI_WORKFLOW_NAME}
 # \`.x/build-stats.json\`, so a run with no build reports X_BUDGET_UNMEASURED. Run \`x verify\` here
 # instead and this workflow is red for a reason that has nothing to do with the commit.
 #
-# No \`services:\` block, deliberately — \`bun run setup\` brings up embedded Postgres in-process,
-# so there is nothing to provision and nothing to wait on. Add one the day this app needs a real
-# server, beside the \`DATABASE_URL\` that selects it.
+# \`bun run setup\` brings up embedded Postgres in-process; the TEST services come from
+# \`docker/docker-compose.test.yml\` — Postgres 18, Redis, NATS and S3 in RAM, durability and logs
+# off — started by the same two lines a laptop runs, never a \`services:\` block that restates them.
 
 # EVERY push, not just the default branch's. \`x new\` runs a plain \`git init\` and takes whatever
 # \`init.defaultBranch\` this machine already agreed on, so a \`branches: [main]\` filter silently
@@ -90,6 +91,9 @@ jobs:
           restore-keys: bun-\${{ runner.os }}-
       # Two steps rather than one \`&&\`, so the log names which half failed and times each.
       - run: bun run setup
+      # \`--wait\` returns once every healthcheck passes; the env file points the suites at them.
+      - run: docker compose -f ${TEST_COMPOSE_PATH} up -d --wait
+      - run: cat ${TEST_ENV_PATH} >> "$GITHUB_ENV"
       - run: bun run check
 `;
 

package/src/templates/scaffold-container-compose.ts

@@ -81,11 +81,13 @@ x-run-once-probe: &run-once-probe
 
 services:
   db:
-    image: postgres:17-alpine
+    # Postgres 18 images keep the cluster under /var/lib/postgresql/18/docker, so the volume is the
+    # parent — mounted at .../data, as for 17, the image refuses to start.
+    image: postgres:18-alpine
     environment:
       POSTGRES_PASSWORD: \${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
       POSTGRES_DB: ${app.kebab}
-    volumes: ['pgdata:/var/lib/postgresql/data']
+    volumes: ['pgdata:/var/lib/postgresql']
     healthcheck:
       test: ['CMD-SHELL', 'pg_isready -U postgres']
       interval: 5s

package/src/templates/scaffold-docs.ts

@@ -11,6 +11,7 @@ import type { GeneratedFile, NameSet } from './naming';
 import { binFiles } from './scaffold-bin';
 import { claudeFiles } from './scaffold-claude';
 import { containerFiles } from './scaffold-container';
+import { testServicesFiles } from './scaffold-test-services';
 
 const agents = (app: NameSet): string => `# AGENTS.md
 
@@ -67,7 +68,14 @@ branch whose test cannot fail is worse than an uncovered one, because it reads a
 browser-only mount, a container entry point — carries its \`why\`, and is printed by \`x doctor\`.
 
 Every test the scaffold and the generators write is the idiom to copy. All of them run on the
-\`unit\` step — in process, on the in-memory driver, with no database, browser or server:
+\`unit\` step — in process, on the in-memory driver, with no database, browser or server.
+
+A suite that needs a real server reads it from \`docker/test-services.env\`: Postgres 18, Redis, NATS
+and S3 from \`docker/docker-compose.test.yml\`, in RAM, with durability and logging off — CI starts
+it before \`bun run check\`, a laptop with \`docker compose -f docker/docker-compose.test.yml up -d
+--wait\` then \`set -a; . docker/test-services.env; set +a\`. A resource a test opens is held with
+\`await using\` — \`await using db = await acquireWorkerDatabase()\` drops its database however
+the test ends:
 
 | What | How its test runs it | Copy from |
 |---|---|---|
@@ -136,6 +144,14 @@ bun run dev     # all roles in one process, embedded Postgres, /_x mounted
 bun run check   # the gate: a static build, then typecheck, lint, boundaries, tests, drift, budgets
 \`\`\`
 
+Tests against real servers — Postgres 18, Redis, NATS, S3, in RAM and silent, as CI runs them:
+
+\`\`\`sh
+docker compose -f docker/docker-compose.test.yml up -d --wait
+set -a; . docker/test-services.env; set +a
+bun run check
+\`\`\`
+
 \`packages/db/migrations\` starts empty and \`x db gen\` is its only writer — \`bun run setup\` runs
 \`x db gen "initial"\` for you on a fresh clone. Until it has, \`x verify\`'s \`drift\` step is red
 with \`X_DB_DRIFT\`, and that is the fix it names.
@@ -173,7 +189,7 @@ const composeDev = (
 # production topology is docker-compose.prod.yml, and it is a different file for a reason.
 services:
   db:
-    image: postgres:17-alpine
+    image: postgres:18-alpine
     environment:
       POSTGRES_PASSWORD: ${app.kebab}
       POSTGRES_DB: ${app.kebab}
@@ -214,6 +230,8 @@ export function docsFiles(app: NameSet): readonly GeneratedFile[] {
     // The scripts `bun run setup` and `bun run check` run — TypeScript, so one file per OS.
     ...binFiles(),
     { path: 'docker/docker-compose.dev.yml', contents: composeDev(app) },
+    // What the suites run against — in RAM, silent; ci.yml starts it before the gate.
+    ...testServicesFiles(app),
     // The harness half of the same job AGENTS.md does. It lands in the app's own repo rather than
     // in a global config, so it is visible in the scaffold's diff and deletable in one line.
     ...claudeFiles(app),

package/src/templates/scaffold-test-services.ts

@@ -0,0 +1,137 @@
+// The backing services a new app's suites run against: `docker/docker-compose.test.yml` and the
+// one env file that points the suites at it. In RAM, durability off, silent — the framework's own
+// `docker/docker-compose.test.yml`, cut to what an app has. Ports sit apart from the dev stack's
+// so both can run at once; `ci.yml` starts this file before `bun run check`.
+
+import type { GeneratedFile, NameSet } from './naming';
+
+export const TEST_COMPOSE_PATH = 'docker/docker-compose.test.yml';
+export const TEST_ENV_PATH = 'docker/test-services.env';
+
+/** Host ports, one place: the compose file publishes them and the env file names them. */
+export const TEST_PORTS = { postgres: 55432, redis: 56379, nats: 54222, s3: 59000 } as const;
+
+const composeTest = (
+  app: NameSet,
+): string => `# The services the test suites run against — in RAM, and silent.
+#
+#   docker compose -f ${TEST_COMPOSE_PATH} up -d --wait
+#   set -a; . ${TEST_ENV_PATH}; set +a
+#   bun run check
+#
+# \`--wait\` returns once every healthcheck passes. CI runs the same lines (.github/workflows/ci.yml).
+# None of it is required: with no TEST_* variable set the unit suite runs on the in-memory driver,
+# and a suite that needs a real server skips. Ports are the dev stack's plus 50000, so both run.
+#
+# Three rules, on every service:
+#
+#   * RAM. Data lives on a tmpfs: no block device written, nothing left behind by \`down\`.
+#   * NO DURABILITY. fsync, synchronous_commit and full_page_writes off, WAL minimal and no WAL
+#     senders; Redis keeps no RDB snapshot and no AOF. A test database that survives a crash is a
+#     database nobody asked for.
+#   * SILENT. Each server logs as little as it can be told to, and the log driver is \`none\`. To
+#     watch one that will not start, run it attached: \`docker compose -f ${TEST_COMPOSE_PATH} up postgres\`.
+#
+# Every port binds 127.0.0.1: the credentials are in this file.
+name: ${app.kebab}-test
+
+x-silent: &silent
+  logging: { driver: none }
+
+services:
+  # Postgres 18, the production major. \`initdb -c\` writes each setting into the new cluster;
+  # \`--no-sync\` is initdb's own fsync of a cluster on a tmpfs. Postgres 18 images keep the cluster
+  # under /var/lib/postgresql/18, so the tmpfs is the parent.
+  postgres:
+    <<: *silent
+    image: postgres:18-alpine
+    environment:
+      POSTGRES_USER: ${app.kebab}
+      POSTGRES_PASSWORD: ${app.kebab}-test
+      POSTGRES_DB: postgres
+      POSTGRES_INITDB_ARGS: >-
+        --no-sync
+        -c fsync=off
+        -c synchronous_commit=off
+        -c full_page_writes=off
+        -c wal_level=minimal
+        -c max_wal_senders=0
+        -c logging_collector=off
+        -c log_min_messages=fatal
+        -c log_statement=none
+        -c log_checkpoints=off
+        -c log_connections=off
+        -c log_disconnections=off
+    tmpfs: [/var/lib/postgresql]
+    ports: ['127.0.0.1:${TEST_PORTS.postgres}:5432']
+    healthcheck:
+      # TCP, never the socket: the entrypoint's temporary init server listens on the socket only.
+      test: ['CMD-SHELL', 'pg_isready -U ${app.kebab} -h 127.0.0.1 -p 5432']
+      interval: 1s
+      timeout: 3s
+      retries: 60
+
+  redis:
+    <<: *silent
+    image: redis:8-alpine
+    command: ['redis-server', '--save', '', '--appendonly', 'no', '--loglevel', 'warning']
+    tmpfs: [/data]
+    ports: ['127.0.0.1:${TEST_PORTS.redis}:6379']
+    healthcheck:
+      test: ['CMD', 'redis-cli', 'ping']
+      interval: 1s
+      timeout: 3s
+      retries: 30
+
+  # JetStream's store on the tmpfs; \`-l /dev/null\` is the only quiet a nats-server has.
+  nats:
+    <<: *silent
+    image: nats:2-alpine
+    command: ['-js', '-sd', '/data', '-m', '8222', '-l', '/dev/null']
+    tmpfs: [/data]
+    ports: ['127.0.0.1:${TEST_PORTS.nats}:4222']
+    healthcheck:
+      test: ['CMD', 'wget', '-q', '--spider', 'http://127.0.0.1:8222/healthz']
+      interval: 1s
+      timeout: 3s
+      retries: 30
+
+  # A directory under /data is a bucket, so the tmpfs mounted AT the bucket's path is the bootstrap.
+  s3:
+    <<: *silent
+    image: versity/versitygw:v1.8.0@sha256:30292fc2eeacc67a36993b01f7a7a5e3361a19cced0e80c1d71cfa2a4b0a2499
+    environment:
+      VGW_BACKEND: posix
+      VGW_BACKEND_ARG: /data
+      VGW_PORT: ':9000'
+      VGW_QUIET: 'true'
+      VGW_REGION: auto
+      ROOT_ACCESS_KEY: ${app.kebab}
+      ROOT_SECRET_KEY: ${app.kebab}-test
+    tmpfs: [/data/${app.kebab}-test]
+    ports: ['127.0.0.1:${TEST_PORTS.s3}:9000']
+    healthcheck:
+      test: ['CMD', 'nc', '-z', '127.0.0.1', '9000']
+      interval: 1s
+      timeout: 3s
+      retries: 30
+`;
+
+const testEnv = (
+  app: NameSet,
+): string => `# Where the suites find the services ${TEST_COMPOSE_PATH} starts — the one place these URLs are
+# written. A laptop sources it (\`set -a; . ${TEST_ENV_PATH}; set +a\`); CI appends it to $GITHUB_ENV.
+# TEST_DATABASE_URL is what @ultimat3/testing clones one database per test worker from.
+TEST_DATABASE_URL=postgres://${app.kebab}:${app.kebab}-test@127.0.0.1:${TEST_PORTS.postgres}/postgres
+TEST_REDIS_URL=redis://127.0.0.1:${TEST_PORTS.redis}
+TEST_NATS_URL=nats://127.0.0.1:${TEST_PORTS.nats}
+TEST_S3_URL=http://${app.kebab}:${app.kebab}-test@127.0.0.1:${TEST_PORTS.s3}/${app.kebab}-test
+`;
+
+/** The test stack and its env file. */
+export function testServicesFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: TEST_COMPOSE_PATH, contents: composeTest(app) },
+    { path: TEST_ENV_PATH, contents: testEnv(app) },
+  ];
+}