@starci/hfs 4.7.28 → 4.7.29

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 4.7.29 - 2026-10-24
+- Added: a new full app ships its test world (`scaffold/test-world.mjs`, `templates/be/test-world/`): the `@starci/test-world` declaration under `be/src/tests/world/`, an integration spec of readiness over the real database and one e2e spec per api app, so the integration, e2e and contract rows of the release gate run real specs.
+- Added: `starci app upgrade [--plan]` on a full app without `be/src/tests/world/global-setup.ts` adds that world and the test devDependencies it lacks at canon pins, never overwriting a file (`HFS_UPGRADE_FILE_CONFLICT`); proven by `src/main.spec.mjs`.
+- Changed: the bundled canon pins select zod 4.6.7 (GHSA-mrhx-c7xc-m3w5 is fixed in 4.6.6), @starci/cli 1.7.29, @starci/eslint-canon-be 3.4.37 and @starci/eslint-canon-fe 8.4.36.
+
 ## 4.7.28 - 2026-10-23
 - Added: `scripts/lib/sonar-new-code.mjs` joins the bundled runtime copy (the New Code definition `starci sonar project ensure` sets), proven by `src/sonar-new-code.spec.mjs`.
 - Fixed: the bundled gate-loosening detector no longer reads a quoted operand of a printed message as a ban-list row, nor the upkeep of an exception list the check stops reading as enforcement lost (`src/bypass-detector.spec.mjs`).

package/README.md

@@ -61,6 +61,13 @@ unchanged lite tree through the full-edition view. The check is read-only; `--db
 comparison when the local stack is available. Applying `starci app upgrade --edition full` adds the full-only managed configuration,
 test layers and cli requirements without rewriting product code. Downgrade to lite is not supported.
 
+A new full app ships its test world (`scaffold/test-world.mjs`): the `@starci/test-world` declaration under `be/src/tests/world/`
+(the dev stack's Postgres per connection, the api apps, the cli app's migration runner as the migrate step), an integration spec of
+readiness over the real database and one e2e spec per api app booted over the migrated database, beside the contract spec of the
+be skeleton, so `test:integration`, `test:e2e` and `test:contract` of the release gate run real specs. On a full app that has no
+`be/src/tests/world/global-setup.ts`, `starci app upgrade [--plan]` adds those files and the test devDependencies it lacks; a world
+file that exists and differs refuses (`HFS_UPGRADE_FILE_CONFLICT`) and nothing is overwritten.
+
 ## Creating a service
 
 Every file of a spec-required role of `ruleParams.be.unitRoles` — a `*.service.ts`, a `*.cli.ts` of the cli feature root — owes exactly one colocated `<name>.<role>.spec.ts` (unit test standard), and any other file of a `ruleParams.be.logicRoles` role inside a `coverage: required` slot may carry one beside it. `starci app new` is the one way a service and its spec come into being together:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.7.28",
+  "version": "4.7.29",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -29,14 +29,14 @@ pins:
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.36
+    version: 3.4.37
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.4.35
+    version: 8.4.36
     group: starci
     install: registry
     side: fe
@@ -76,14 +76,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.7.28
+    version: 1.7.29
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.7.28
+    version: 4.7.29
     group: starci
     install: registry
     side: both
@@ -336,10 +336,10 @@ pins:
     side: fe
     why: 'the zod resolver of react-hook-form (fe-stack forms); version read from the starci-academy package-lock on 2026-10-13.'
   'zod':
-    version: 4.4.3
+    version: 4.6.7
     group: framework
     side: fe
-    why: 'the schema library of front-end forms and boundary parsing (fe-stack forms); version read from the starci-academy package-lock on 2026-10-13.'
+    why: 'the schema library of front-end forms and boundary parsing (fe-stack forms), also an npm override of every app root; 4.6.7 (the registry latest on 2026-10-24) closes GHSA-mrhx-c7xc-m3w5 (high, fixed in 4.6.6), which npm audit --audit-level=high reported against 4.4.3.'
   '@reduxjs/toolkit':
     version: 2.11.2
     group: framework

package/runtime/packages/cli/src/catalog.generated.mjs

@@ -1,7 +1,7 @@
 // GENERATED by scripts/cli/gen-catalog.mjs — do not edit
 export const CATALOG = {
   "schema": "starci/cli-catalog@1",
-  "hash": "466ffd40fe4a003c976ac306bcb14639b1b57c947112e7899ef717a819e571f5",
+  "hash": "9ff398eeddb22776cc36e38b7206c0bfe03d3dec2c1e42614fabe349241b53ed",
   "global": [
     {
       "name": "json",
@@ -1648,7 +1648,7 @@ export const CATALOG = {
           "runtimeSide": "host"
         },
         "upgrade": {
-          "summary": "upgrade a lite app to the full edition (--edition full); a full app is already current",
+          "summary": "upgrade a lite app to full (--edition full), or add the test world a full app lacks",
           "owner": "@starci/hfs",
           "flags": [
             {
@@ -1658,12 +1658,13 @@ export const CATALOG = {
             }
           ],
           "exit": {
-            "0": "already full",
+            "0": "upgraded, completed, or the full app is already complete",
             "2": "refusal or bad usage"
           },
           "json": "none",
           "examples": [
             "starci app upgrade",
+            "starci app upgrade --plan",
             "starci app upgrade --edition full --plan"
           ],
           "editions": [
@@ -1671,6 +1672,10 @@ export const CATALOG = {
             "lite"
           ],
           "impl": null,
+          "conventions": [
+            "a full app without be/src/tests/world/global-setup.ts gets the test world of a new full app and the test devDependencies it lacks",
+            "a world file that exists and differs refuses HFS_UPGRADE_FILE_CONFLICT; nothing is overwritten"
+          ],
           "runtimeSide": "host"
         }
       }
@@ -3204,6 +3209,11 @@ export const CATALOG = {
               "type": "string",
               "summary": "the optional commit body"
             },
+            {
+              "name": "body-file",
+              "type": "string",
+              "summary": "a file holding the commit body, or - for stdin; the way to pass a multi-line body"
+            },
             {
               "name": "paths",
               "type": "list",
@@ -3233,7 +3243,8 @@ export const CATALOG = {
           "json": "starci/git-commit@1",
           "examples": [
             "starci git commit --type fix --scope cli --summary \"handle an empty index\"",
-            "starci git commit --type docs --summary \"explain backup refs\" --paths docs/git-governance.md --dry-run"
+            "starci git commit --type docs --summary \"explain backup refs\" --paths docs/git-governance.md --dry-run",
+            "starci git commit --type fix --summary \"keep the body\" --body-file -"
           ],
           "editions": [
             "full"
@@ -3252,7 +3263,8 @@ export const CATALOG = {
           "conventions": [
             "subjects use `type(scope): summary`; types are feat, fix, refactor, test, docs, chore, land and release",
             "keep one logical change in each commit and pass explicit paths instead of staging unrelated work",
-            "hooks run the L0 checks; never bypass them and never amend a pushed or landed commit"
+            "hooks run the L0 checks; never bypass them and never amend a pushed or landed commit",
+            "a multi-line body goes through --body-file (a file, or - for stdin): a command-shell launcher such as the Windows cmd shim ends an argument at its first newline"
           ],
           "runtimeSide": "host"
         },

package/scaffold/app.mjs

@@ -21,6 +21,7 @@ import { dbTypesPath, generateDbTypes } from '../emit/db-types.mjs';
 import { TEMPLATES_DIR, appSource, imageFiles, render, renderTargets, writeTargets } from '../sync/index.mjs';
 import { ScaffoldError } from './service.mjs';
 import { SUPABASE_PORT_VARIABLES, supabasePortVars } from './supabase-ports.mjs';
+import { testWorldFiles } from './test-world.mjs';
 import { FE_APP_SCRIPTS, PACKAGE_MANAGER, WORKSPACES, WORKSPACE_LINT, feAppPackageName } from '../runtime/scripts/hfs/rules/monorepo.mjs';
 import { isLinkLike } from '../runtime/scripts/api/fs/is-link-like.mjs';
 import { unlinkOnly } from '../runtime/scripts/api/fs/lib.mjs';
@@ -685,6 +686,8 @@ export function scaffoldApp({ name, into, presets, edition = 'full', authCallbac
       { path: `fe/packages/${name}-${pkg}/tsconfig.build.json`, content: jsonText(fePackageBuildTsconfig()) },
     ])),
     ...['app', 'be', 'fe'].flatMap(scope => skeletonOf(scope, app, { sonarGate: sonarGateName(parseYaml(fs.readFileSync(SONAR_GATE_FILE, 'utf8')), app.edition), timestamp, registryVisibility, ...supabasePortVars(name) })),
+    // A full app has a test world (integration, e2e and contract are rows of its release gate); lite has none (ruling:R212/case-3, hosting amended by owner:lite-production-swarm).
+    ...(app.edition === 'lite' ? [] : testWorldFiles(app)),
   ];
   const writes = scaffoldWrites(root, original);
   try {

package/scaffold/service.mjs

@@ -38,7 +38,7 @@ const words = name => name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Z
 export const pascalOf = name => words(name).map(word => word[0].toUpperCase() + word.slice(1).toLowerCase()).join('');
 /** `InjectPrimaryEntityManager` -> `PRIMARY_ENTITY_MANAGER`. */
 const tokenNameOf = decorator => words(decorator.replace(/^Inject/, '')).map(word => word.toUpperCase()).join('_');
-const camelOf = name => { const pascal = pascalOf(name); return pascal[0].toLowerCase() + pascal.slice(1); };
+export const camelOf = name => { const pascal = pascalOf(name); return pascal[0].toLowerCase() + pascal.slice(1); };
 
 const SERVICE_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 

package/scaffold/test-world.mjs

@@ -0,0 +1,125 @@
+// test-world.mjs - the test world of a full app: the declaration of @starci/test-world under be/src/tests/world/ and one baseline
+// real spec per world layer, rendered from templates/be/test-world/ for the api apps and connections hfs.json declares.
+//
+// A full app's release gate runs integration, e2e and contract (the managed test:* scripts), and the jest preset gives those
+// projects only to an app that has be/src/tests/world/global-setup.ts. The scaffold writes these files into every new full app,
+// and `starci app upgrade` adds the missing ones to an existing full app (never overwriting a file the app already has):
+//   - world/: the declaration (stack .starcistacks/dev, Postgres per connection, the api apps, the cli app's migration runner as
+//     the migrate step, a platform base for modules worlds), its spec entry and the library's global setup and teardown;
+//   - integration/readiness/: the readiness probe over the real database, ready, refused while the database is cut, ready again;
+//   - e2e/system-health/<app>-serves-once-migrated: each api app booted over the migrated database and called over HTTP;
+//   - fixtures/persistence/migrations.sql.ts: the ledger reads the e2e asserts.
+// The contract layer is the app's own contract spec the be skeleton already ships (src/tests/contract/http-security/).
+import fs from 'node:fs';
+import path from 'node:path';
+import { TEMPLATES_DIR } from '../sync/index.mjs';
+import { ScaffoldError, camelOf, pascalOf } from './service.mjs';
+
+const TEMPLATE_DIR = path.join(TEMPLATES_DIR, 'be', 'test-world');
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/u;
+
+/** The file the jest preset reads to give an app its world projects; its presence means the app has a test world. */
+export const WORLD_MARKER = 'be/src/tests/world/global-setup.ts';
+
+const template = (file) => fs.readFileSync(path.join(TEMPLATE_DIR, ...file.split('/')), 'utf8').replace(/\r\n/g, '\n');
+
+/** A template with its `{{name}}` slots filled; every slot must have a value and every value must be used. */
+function fill(file, values) {
+  const used = new Set();
+  const text = template(file).replace(/\{\{([A-Za-z]+)\}\}/gu, (_, key) => {
+    if (!Object.hasOwn(values, key)) throw new ScaffoldError('HFS_SCAFFOLD_TEMPLATE_VARIABLE', `templates/be/test-world/${file} names {{${key}}}, which has no value`);
+    used.add(key);
+    return values[key];
+  });
+  const unused = Object.keys(values).filter((key) => !used.has(key));
+  if (unused.length) throw new ScaffoldError('HFS_SCAFFOLD_TEMPLATE_VARIABLE', `templates/be/test-world/${file} does not use ${unused.join(', ')}`);
+  return text;
+}
+
+/** `.name` for an identifier, `["name"]` otherwise: how a spec reads a record key. */
+const access = (name) => (IDENTIFIER.test(name) ? `.${name}` : `[${JSON.stringify(name)}]`);
+const constantOf = (name) => name.replace(/[^A-Za-z0-9]+/gu, '_').toUpperCase();
+const union = (names) => names.map((name) => JSON.stringify(name)).join(' | ');
+const migrationsConst = (connection) => `${constantOf(connection.name)}_APPLIED_MIGRATIONS`;
+
+/** The api apps and connections of a full declaration, refused when the world has nothing to boot or migrate. */
+function worldShape(app) {
+  const apis = app.sides.be.apps.filter((entry) => entry.kind === 'api');
+  const connections = app.sides.be.connections ?? [];
+  if (!apis.length) throw new ScaffoldError('HFS_SCAFFOLD_TEST_WORLD', 'the test world boots the api apps of hfs.json, and it declares none');
+  if (!connections.length) throw new ScaffoldError('HFS_SCAFFOLD_TEST_WORLD', 'the test world migrates the connections of hfs.json, and it declares none');
+  if (!app.sides.be.apps.some((entry) => entry.kind === 'cli' && entry.name === 'cli')) throw new ScaffoldError('HFS_SCAFFOLD_TEST_WORLD', 'the test world migrates through the cli app (be/apps/cli), and hfs.json declares none');
+  return { apis, connections };
+}
+
+function worldConfig({ apis, connections }) {
+  return fill('world/test-world.config.ts.tpl', {
+    appModuleImports: apis.map((api) => `import { AppModule as ${pascalOf(api.name)}App } from "../../../apps/${api.name}/src/app.module"`).join('\n'),
+    optionsImports: ['cliOptionsOf', ...apis.map((api) => `${camelOf(api.name)}OptionsOf`), 'migrateCli', 'platformBase'].sort().join(', '),
+    connectionDeclarations: connections.map((connection) => `{ name: ${JSON.stringify(connection.name)} }`).join(', '),
+    worldApps: apis.map((api) => `        ${IDENTIFIER.test(api.name) ? api.name : JSON.stringify(api.name)}: { module: ${pascalOf(api.name)}App, options: ${camelOf(api.name)}OptionsOf },`).join('\n'),
+  });
+}
+
+function worldOptions({ apis, connections }) {
+  const appOptions = apis.map((api) => [
+    '',
+    `/** The ${api.name} app, read the way its \`main.ts\` reads its environment, listening on the port the run reserved for it. */`,
+    `export const ${camelOf(api.name)}OptionsOf = (w: AppWiring): ${pascalOf(api.name)}Options =>`,
+    `    read${pascalOf(api.name)}Env(environmentOf(w, { PORT: String(w.apps${access(api.name)}.port) }))`,
+    '',
+  ].join('\n')).join('');
+  return fill('world/test-apps.options.ts.tpl', {
+    appEnvImports: apis.flatMap((api) => [
+      `import { read${pascalOf(api.name)}Env } from "../../../apps/${api.name}/src/${api.name}.env"`,
+      `import type { ${pascalOf(api.name)}Options } from "../../../apps/${api.name}/src/${api.name}.options"`,
+    ]).join('\n'),
+    appsUnion: union(apis.map((api) => api.name)),
+    connectionsUnion: union(connections.map((connection) => connection.name)),
+    environmentConnections: connections.map((connection) => `        ${connection.envPrefix}_URL: w.db${access(connection.name)}.url,`).join('\n'),
+    appOptions,
+  });
+}
+
+function migrationsFixture({ connections }) {
+  return fill('fixtures/migrations.sql.ts.tpl', {
+    migrationQueries: connections.map((connection) => [
+      '',
+      `/** The migrations the run applied to the ${connection.name} connection ($none), oldest first: the ledger the cli migrate step writes. */`,
+      `export const ${migrationsConst(connection)} = sql\`SELECT name FROM ${connection.name}_migrations ORDER BY id LIMIT 500\``,
+      '',
+    ].join('\n')).join(''),
+  });
+}
+
+/** The connection an api app's e2e reads back: the one it owns, else the first declared. */
+const connectionOf = (api, connections) => connections.find((connection) => connection.owner === api.name) ?? connections[0];
+
+function e2eSpec(api, connections) {
+  const connection = connectionOf(api, connections);
+  return fill('e2e/serves-once-migrated.e2e-spec.ts.tpl', {
+    app: api.name,
+    appAccess: access(api.name),
+    connection: connection.name,
+    connectionAccess: access(connection.name),
+    migrationsConst: migrationsConst(connection),
+  });
+}
+
+/**
+ * The test world files of the full app `app` (a resolved hfs declaration): [{ path, content }], app-relative, in a fixed order.
+ * Refused (HFS_SCAFFOLD_TEST_WORLD) when the declaration has no api app, no connection or no cli app to migrate through.
+ */
+export function testWorldFiles(app) {
+  const shape = worldShape(app);
+  return [
+    { path: 'be/src/tests/world/test-world.config.ts', content: worldConfig(shape) },
+    { path: 'be/src/tests/world/test-apps.options.ts', content: worldOptions(shape) },
+    { path: 'be/src/tests/world/use-test-world.ts', content: fill('world/use-test-world.ts.tpl', {}) },
+    { path: WORLD_MARKER, content: fill('world/global-setup.ts.tpl', {}) },
+    { path: 'be/src/tests/world/global-teardown.ts', content: fill('world/global-teardown.ts.tpl', {}) },
+    { path: 'be/src/tests/fixtures/persistence/migrations.sql.ts', content: migrationsFixture(shape) },
+    { path: 'be/src/tests/integration/readiness/readiness.integration-spec.ts', content: fill('integration/readiness.integration-spec.ts.tpl', {}) },
+    ...shape.apis.map((api) => ({ path: `be/src/tests/e2e/system-health/${api.name}-serves-once-migrated.e2e-spec.ts`, content: e2eSpec(api, shape.connections) })),
+  ];
+}

package/src/main.mjs

@@ -107,7 +107,7 @@ starci app db migrate [--execute] [--local | --linked | --url-env <NAME>] [--jso
 starci app db post-cutover [--execute] [--green-at <ISO> | --owner-confirms-old-app-gone] [--linked | --url-env <NAME>] [--json] [--cwd <dir>]
 starci app release gate [--execute] [--source <ref>] [--tag-prefix <prefix>] [--json] [--cwd <dir>]
 starci app release push [--execute] [--remote <name>] [--json] [--cwd <dir>]
-starci app upgrade --edition full [--plan] [--cwd <dir>]
+starci app upgrade [--edition full] [--plan] [--cwd <dir>]
 starci app stack <up|down|status> [--stack <dir>] [--services <list>] [--k3d] [--force] [--json] [--cwd <dir>]
 starci app stack <prepare|doctor|connect|disconnect|build-args|render|deploy|converge|verify|rollback|prune|backup|jobs> --env <env> [--execute] [--json] [--cwd <dir>]
 starci app explain <path> [--cwd <dir>] [--json]

package/templates/be/test-world/e2e/serves-once-migrated.e2e-spec.ts.tpl

@@ -0,0 +1,32 @@
+import { appliedMigrations, {{migrationsConst}} } from "../../fixtures/persistence/migrations.sql"
+import { useTestWorld } from "../../world/use-test-world"
+
+/**
+ * system-health: the real {{app}} app booted over the database the run migrated through the cli, called over HTTP. It answers
+ * liveness and readiness while its ledger holds the applied migrations; readiness answers 503 while the database is cut and
+ * liveness stays up.
+ */
+describe("system-health: the {{app}} app serves once its database is migrated (e2e)", () => {
+    const world = useTestWorld({ apps: ["{{app}}"] })
+
+    it("answers liveness and readiness over the migrated {{connection}} database", async () => {
+        const live = await world.apps{{appAccess}}.api.get("/health/live")
+        const ready = await world.apps{{appAccess}}.api.get("/health/ready")
+        const applied = await appliedMigrations(world.db{{connectionAccess}}, {{migrationsConst}})
+
+        expect(live.status).toBe(200)
+        expect(ready.status).toBe(200)
+        expect(ready.body).toEqual({ ok: true })
+        expect(applied.length).toBeGreaterThan(0)
+    })
+
+    it("answers 503 on readiness while the database is cut, and liveness stays up", async () => {
+        await world.interruptDatabase(async () => {
+            const ready = await world.apps{{appAccess}}.api.get("/health/ready")
+            const live = await world.apps{{appAccess}}.api.get("/health/live")
+
+            expect(ready.status).toBe(503)
+            expect(live.status).toBe(200)
+        })
+    })
+})

package/templates/be/test-world/fixtures/migrations.sql.ts.tpl

@@ -0,0 +1,14 @@
+import type { EntityManager } from "typeorm"
+import { sql } from "@modules/platform/database"
+
+/** One row of a connection's migration ledger: the name of a migration the cli migrate step applied. */
+export interface AppliedMigrationRow {
+    /** The migration class name. */
+    readonly name: string
+}
+{{migrationQueries}}
+/** Reads the ledger of one connection with one of the queries above. */
+export const appliedMigrations = (
+    manager: EntityManager,
+    query: ReturnType<typeof sql>,
+): Promise<ReadonlyArray<AppliedMigrationRow>> => manager.query(query)

package/templates/be/test-world/integration/readiness.integration-spec.ts.tpl

@@ -0,0 +1,28 @@
+import { HttpSecurityModule, ReadinessService } from "@modules/platform/http-security"
+import { httpSecurityOf } from "../../world/test-apps.options"
+import { useTestWorld } from "../../world/use-test-world"
+
+/**
+ * readiness: the required-dependency probe over the real primary database of the run, no HTTP door of ours. It answers ready
+ * while the database commits a transaction, refuses while the database is cut and answers ready again once it is back.
+ */
+describe("readiness: the required database (integration)", () => {
+    const world = useTestWorld({
+        modules: [(w) => HttpSecurityModule.register(httpSecurityOf(w))],
+    })
+
+    const readiness = (): ReadinessService => world.resolve(ReadinessService)
+
+    it("reports ready while the real primary database commits a transaction", async () => {
+        await expect(readiness().probeRequired()).resolves.toEqual({ ok: true })
+    })
+
+    it("refuses readiness while the database is cut, then reports ready again", async () => {
+        await world.interruptDatabase(async () => {
+            await expect(readiness().probeRequired()).rejects.toMatchObject({
+                code: "HTTP_SECURITY_REQUIRED_DEPENDENCY_UNAVAILABLE",
+            })
+        })
+        await expect(readiness().probeRequired()).resolves.toEqual({ ok: true })
+    })
+})

package/templates/be/test-world/world/global-setup.ts.tpl

@@ -0,0 +1 @@
+export { default } from "@starci/test-world/global-setup"

package/templates/be/test-world/world/global-teardown.ts.tpl

@@ -0,0 +1 @@
+export { default } from "@starci/test-world/global-teardown"

package/templates/be/test-world/world/test-apps.options.ts.tpl

@@ -0,0 +1,62 @@
+/**
+ * The typed options the test world hands to the real apps, the migrate step and the platform base of a modules world: what the
+ * `main.ts` of each app parses from the environment of a deployment, built from the wiring of the run. The databases are the real
+ * ones the library runs; the migrate step is the cli app's own migration runner, the one `cli migrate run` calls.
+ */
+import type { DynamicModule } from "@nestjs/common"
+import { NestFactory } from "@nestjs/core"
+import type { WorldWiring } from "@starci/test-world"
+import { ClockModule } from "@modules/platform/clock"
+import { EnvSource } from "@modules/platform/config"
+import { DatabaseModule, MigrationRunnerService } from "@modules/platform/database"
+import { parseHttpSecurityConfig } from "@modules/platform/http-security"
+import type { HttpSecurityOptions } from "@modules/platform/http-security"
+import { LoggingModule } from "@modules/platform/logging"
+import { RetryModule } from "@modules/platform/retry"
+import { AppModule as CliApp } from "../../../apps/cli/src/app.module"
+import { readCliEnv } from "../../../apps/cli/src/cli.env"
+import { createCliAppOptions } from "../../../apps/cli/src/cli.options"
+import type { CliAppOptions } from "../../../apps/cli/src/cli.options"
+{{appEnvImports}}
+
+/** The wiring of the world: its api apps and its database connections. */
+export type AppWiring = WorldWiring<{{appsUnion}}, {{connectionsUnion}}>
+
+/** The one browser origin the apps of the world accept. */
+export const ALLOWED_ORIGIN = "http://localhost:3000"
+
+/** The environment a deployment hands every app of the run: its mode, its origin allowlist and the URL of every connection. */
+const environmentOf = (w: AppWiring, extra: Readonly<Record<string, string>> = {}): EnvSource =>
+    new EnvSource({
+        NODE_ENV: "test",
+        HTTP_SECURITY_ALLOWED_ORIGINS: ALLOWED_ORIGIN,
+{{environmentConnections}}
+        ...extra,
+    })
+{{appOptions}}
+/** The origin allowlist and rate limits of the run, read the way the api apps read them. */
+export const httpSecurityOf = (w: AppWiring): HttpSecurityOptions => parseHttpSecurityConfig(environmentOf(w))
+
+/** The cli app over the run's databases, read the way its `main.ts` reads its environment. */
+export const cliOptionsOf = (w: AppWiring): CliAppOptions => createCliAppOptions(readCliEnv(environmentOf(w)))
+
+/** The migrate step of the run: the cli app composed over the run's databases, running the migrations of every connection. */
+export const migrateCli = async (options: CliAppOptions): Promise<void> => {
+    const cli = await NestFactory.createApplicationContext(CliApp.register(options), { logger: false })
+    try {
+        await cli.get(MigrationRunnerService).run()
+    } finally {
+        await cli.close()
+    }
+}
+
+/** The platform base of a modules world: the clock, the timer, the logger and the database over the run's connections. */
+export const platformBase = (w: AppWiring): ReadonlyArray<DynamicModule> => [
+    ClockModule.register({ isGlobal: true }),
+    RetryModule.register({ isGlobal: true }),
+    LoggingModule.register({ isGlobal: true }),
+    DatabaseModule.register({
+        isGlobal: true,
+        connections: [{ ...cliOptionsOf(w).database, entities: [], migrations: [] }],
+    }),
+]

package/templates/be/test-world/world/test-world.config.ts.tpl

@@ -0,0 +1,20 @@
+/**
+ * The declaration of the test world: selection and overrides only. The service list and the image versions come from the stack
+ * definition (`.starcistacks/dev`); the library runs the Postgres of every connection real behind toxiproxy, migrates it once per
+ * run through the cli app and boots the api apps in process.
+ */
+import { defineTestWorld } from "@starci/test-world"
+{{appModuleImports}}
+import { {{optionsImports}} } from "./test-apps.options"
+
+export const { useTestWorld, useSandbox } = defineTestWorld({
+    stack: ".starcistacks/dev",
+    stacks: {
+        postgresql: { connections: [{{connectionDeclarations}}] },
+    },
+    apps: {
+{{worldApps}}
+    },
+    migrate: { module: migrateCli, options: cliOptionsOf },
+    modules: { base: platformBase },
+})

package/templates/be/test-world/world/use-test-world.ts.tpl

@@ -0,0 +1,2 @@
+/** The entry every spec imports: the `useTestWorld` and `useSandbox` of the declaration in `test-world.config.ts`. */
+export { useSandbox, useTestWorld } from "./test-world.config"

package/upgrade/index.mjs

@@ -1,4 +1,6 @@
-// starci app upgrade --edition full: the additive edition migration from a lite app to the full HFS tree.
+// starci app upgrade --edition full: the additive edition migration from a lite app to the full HFS tree. On a full app,
+// `starci app upgrade` completes it instead: it adds the test world (scaffold/test-world.mjs) the app lacks, with the world's
+// devDependencies at canon pins, and never rewrites a file the app already has.
 //
 // The upgrade is deliberately assembled from the same full-edition render and scaffold templates as a new full app. It never
 // rewrites an existing product source file. A dry run returns the exact ordered operations; apply performs those operations and
@@ -14,6 +16,7 @@ import {
 } from "../runtime/scripts/hfs/slots.mjs";
 import { managedScriptNames } from "../runtime/scripts/hfs/architecture/managed-scripts.mjs";
 import { LOCK_STEP, npmLock, scaffoldWorkSeeds } from "../scaffold/app.mjs";
+import { WORLD_MARKER, testWorldFiles } from "../scaffold/test-world.mjs";
 import { byCodeUnit } from "../report/order.mjs";
 import {
   TEMPLATES_DIR,
@@ -306,13 +309,54 @@ function additionStep(root, file, authored) {
   return null;
 }
 
+/**
+ * The steps that complete an existing full app: every test world file it lacks when it has no world (an existing file that is not
+ * the scaffold's refuses, nothing is overwritten) and the full test toolchain devDependencies it lacks, at canon pins.
+ */
+function fullCompletion(root, declaration) {
+  const steps = [];
+  if (!fs.existsSync(path.join(root, ...WORLD_MARKER.split("/")))) {
+    for (const file of testWorldFiles(declaration)) {
+      const step = additionStep(root, file, new Map());
+      if (step) steps.push({ ...step, why: "Add the full test world and its baseline integration and e2e specs." });
+    }
+  }
+  const current = readJson(root, "package.json");
+  const missing = FULL_DEV_DEPENDENCIES.filter(
+    (name) => current.devDependencies?.[name] === undefined && current.dependencies?.[name] === undefined,
+  );
+  if (missing.length) {
+    const pins = parseYaml(fs.readFileSync(PINS_FILE, "utf8")).pins;
+    const added = pinnedPackage(root, pins).devDependencies;
+    const devDependencies = Object.fromEntries(
+      Object.entries({ ...current.devDependencies, ...Object.fromEntries(missing.map((name) => [name, added[name]])) })
+        .sort(([a], [b]) => a.localeCompare(b)),
+    );
+    steps.push({
+      op: "rewrite-managed",
+      path: "package.json",
+      why: `Add the test world toolchain the full app lacks (${missing.join(", ")}) at canon pins.`,
+      content: jsonText({ ...current, devDependencies }),
+      kind: "file",
+    });
+    steps.push({ op: "rewrite-managed", path: "package-lock.json", why: `Resolve the added pinned dependencies with ${LOCK_STEP}.`, kind: "lock" });
+  }
+  return { managed: [], steps, dependenciesChanged: missing.length > 0 };
+}
+
 async function model({ root, to, presets, manifest }) {
-  if (to !== "full")
+  if (to !== undefined && to !== "full")
     throw new UpgradeError(
       "HFS_UPGRADE_TARGET_INVALID",
       "upgrade supports only --edition full",
     );
   const declaration = loadHfs(root, manifest);
+  if (declaration?.edition !== "lite") return fullCompletion(root, declaration);
+  if (to === undefined)
+    throw new UpgradeError(
+      "HFS_UPGRADE_USAGE",
+      "a lite app upgrades with starci app upgrade --edition full",
+    );
   const hadCli = declaration.sides.be.apps.some(
     (app) => app.kind === "cli" && app.name === "cli",
   );
@@ -449,7 +493,7 @@ async function upgradeEdition({
       if (!locked.ok)
         throw new UpgradeError(
           "HFS_UPGRADE_LOCK_FAILED",
-          `\`${LOCK_STEP}\` could not resolve the upgraded lockfile (${locked.detail}); the lite app was restored`,
+          `\`${LOCK_STEP}\` could not resolve the upgraded lockfile (${locked.detail}); the app was restored`,
         );
     }
   } catch (error) {
@@ -474,11 +518,6 @@ function upgradeArguments(argv) {
     } else if (arg === "--plan") plan = true;
     else throw new UpgradeError("HFS_UPGRADE_USAGE", `unknown argument ${arg}`);
   }
-  if (to === undefined)
-    throw new UpgradeError(
-      "HFS_UPGRADE_USAGE",
-      "starci app upgrade needs --edition full",
-    );
   return { root, to, plan };
 }
 
@@ -491,7 +530,7 @@ export async function upgradeMain(
   const steps = await upgradeEdition({ root, to, plan, presets });
   for (const step of steps) stdout(`${step.op} ${step.path}: ${step.why}\n`);
   stdout(
-    `starci app upgrade --edition full${plan ? " --plan" : ""}: ${steps.length} step${steps.length === 1 ? "" : "s"} ${plan ? "planned; no file written" : "applied"}\n`,
+    `starci app upgrade${to ? ` --edition ${to}` : ""}${plan ? " --plan" : ""}: ${steps.length} step${steps.length === 1 ? "" : "s"} ${plan ? "planned; no file written" : "applied"}${steps.length === 0 ? " (the full app is complete)" : ""}\n`,
   );
   return 0;
 }