@starci/hfs 4.7.27 → 4.7.29

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/sync/format.mjs

@@ -13,7 +13,7 @@ const IGNORE_FILE = '.prettierignore';
 const LOCKFILES = new Set(['package-lock.json']);
 
 /** The repository's own prettier, or a SyncError when it is not installed. */
-function loadPrettier(repoRoot) {
+export function loadPrettier(repoRoot) {
   const require = createRequire(path.join(repoRoot, 'package.json'));
   try {
     return require('prettier');

package/sync/hygiene.mjs

@@ -3,7 +3,9 @@
 // .starcistacks must not be a plaintext secret (only *.enc is sealed). It is also the secrets guard of the commit: every staged file, in
 // any tree, is read from the index and judged with the one secret judgement of `starci app check` (scripts/hfs/rules/secrets.mjs: a secret by
 // being, an .enc that is no sops envelope, a line that matches a secret pattern), so no plaintext secret reaches the history whatever
-// .gitignore says (`git add -f`, a path tracked before a rule tightened). There is no override. At an HFS app root (hfs.json) it also
+// .gitignore says (`git add -f`, a path tracked before a rule tightened). There is no override. It also
+// refuses every bypass marker the index holds (R303: an inline disable, a type-check escape, a skipped test, a failure swallowed in a hook or
+// workflow; scripts/lib/bypass-markers.mjs), so a bypass fails at the commit and not only at the release. At an HFS app root (hfs.json) it also
 // refuses a back-end logic file the index adds without its unit spec beside it (BE_UNIT_SPEC_NOT_STAGED,
 // scripts/hfs/rules/staged-specs.mjs over the coverage scope; a constants-only file has nothing to test), naming the file. The pre-commit hook judges the staged files;
 // scripts/gates/hfs-sync.mjs judges every tracked file.
@@ -17,6 +19,8 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { secretFileFindings } from '../runtime/scripts/hfs/rules/secrets.mjs';
 import { stagedSpecFindings } from '../runtime/scripts/hfs/rules/staged-specs.mjs';
+import { HFS_BYPASS_MARKER, bypassMessage } from '../runtime/scripts/hfs/rules/bypass-markers.mjs';
+import { bypassesIn } from '../runtime/scripts/lib/bypass-markers.mjs';
 import { loadSlotManifest } from '../runtime/scripts/hfs/slots.mjs';
 import { runGit } from '../runtime/scripts/api/git/lib.mjs';
 import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
@@ -48,7 +52,7 @@ function ignoredAmong(cwd, files) {
 }
 
 /** Violations among `files` (repository-relative, '/'-separated): [{ file, code, message }]. `ignored` is a Set of ignored paths. */
-function hygieneFindings(files, ignored) {
+export function hygieneFindings(files, ignored) {
   const findings = [];
   for (const file of files) {
     if (file.startsWith(WORK) && ignored.has(file)) {
@@ -104,12 +108,20 @@ function secretGuardFindings(cwd, files, alreadyRefused = new Set()) {
   });
 }
 
-/** Findings for `files`: the guarded trees, then the secret guard over every file. */
+/** The bypass markers (R303) of `files` read from the index: an inline disable, a type-check escape, a skipped test or a swallowed failure fails at the commit. */
+function bypassGuardFindings(cwd, files) {
+  return files.flatMap(file => {
+    const text = stagedText(cwd, file);
+    return text === null ? [] : bypassesIn(file, text).map(hit => ({ file, code: HFS_BYPASS_MARKER, message: bypassMessage(file, hit) }));
+  });
+}
+
+/** Findings for `files`: the guarded trees, then the secret guard and the bypass guard over every file. */
 export function judge(cwd, files) {
   const guarded = files.filter(GUARDED);
   const findings = hygieneFindings(guarded, ignoredAmong(cwd, guarded.filter(file => file.startsWith(WORK))));
   const refused = new Set(findings.filter(finding => finding.code === 'HFS_PLAINTEXT_SECRET').map(finding => finding.file));
-  return { checked: files.length, findings: [...findings, ...secretGuardFindings(cwd, files, refused)] };
+  return { checked: files.length, findings: [...findings, ...secretGuardFindings(cwd, files, refused), ...bypassGuardFindings(cwd, files)] };
 }
 
 // The scripts/housekeeping/ledger-hygiene.mjs of the checkout under judgment: the root git names for `cwd`, which carries

package/templates/app/hooks/husky/pre-commit

@@ -1,15 +1,16 @@
 {{header}}
-# Commit gate (L0 only): work hygiene and the secrets guard of the staged files, eslint of the staged files of each side,
-# stylelint over the staged CSS of fe, a prettier check of the staged files. Types and the targeted specs belong to the op gate.
-npx starci app hygiene
+# Commit gate (L0 only): work hygiene, the secrets guard and the bypass guard (no inline disable, type-check escape, skipped test or
+# swallowed failure: HFS_BYPASS_MARKER) of the staged files, managed files equal to their render, eslint of the staged files of each
+# side, stylelint over the staged CSS of fe, a prettier check of the staged files. Every step ends the hook when it fails: none can be
+# skipped. Types and the targeted specs belong to the op gate.
+npx starci app hygiene || exit $?
+npx starci app sync --check || exit $?
 # NUL-delimited paths keep filenames intact; bounded batches fit the Windows command line.
 git diff --cached --name-only --diff-filter=ACMR -z --relative=be -- '*.ts' '*.mts' '*.cts' '*.js' '*.mjs' '*.cjs' |
   xargs -0 -n 50 sh -c 'if [ "$#" -gt 0 ]; then cd be && npx eslint -- "$@"; fi' sh || exit $?
 git diff --cached --name-only --diff-filter=ACMR -z --relative=fe -- '*.ts' '*.tsx' '*.mts' '*.cts' '*.js' '*.jsx' '*.mjs' '*.cjs' |
   xargs -0 -n 50 sh -c 'if [ "$#" -gt 0 ]; then cd fe && npx eslint --max-warnings=0 --no-warn-ignored -- "$@"; fi' sh || exit $?
-styles=$(git diff --cached --name-only --diff-filter=ACMR --relative=fe -- '*.css') || exit $?
-if [ -n "$styles" ]; then
-  (cd fe && npx stylelint $styles)
-fi
+git diff --cached --name-only --diff-filter=ACMR -z --relative=fe -- '*.css' |
+  xargs -0 -n 50 sh -c 'if [ "$#" -gt 0 ]; then cd fe && npx stylelint "$@"; fi' sh || exit $?
 git diff --cached --name-only --diff-filter=ACMR -z |
   xargs -0 -n 50 sh -c 'if [ "$#" -gt 0 ]; then npx prettier --check --ignore-unknown -- "$@"; fi' sh || exit $?

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;
 }