cabloy 5.1.219 → 5.1.220

package/.cabloy-version

@@ -1 +1 @@
-5.1.219
+5.1.220

package/.github/workflows/create-cabloy.yml

@@ -97,7 +97,7 @@ jobs:
           if (Test-Path $log) { Get-Content $log }
           throw 'Redis did not become ready'
       - name: create project
-        run: npm create cabloy cabloy-app
+        run: npm create cabloy@latest cabloy-app
       - name: verify project initialization
         working-directory: cabloy-app
         run: >-

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 5.1.220
+
+### Features
+
+- Add request boundary lifecycle support and diagnostic suppression.
+
+### Improvements
+
+- Speed up REST declaration builds with oxc.
+- Enhance the REST build process.
+- Update setup documentation to use `npm create cabloy@latest`.
+
 ## 5.1.219
 
 ### Improvements

package/README.md

@@ -27,7 +27,7 @@ Learn more about [Vona + Zova Integration](https://cabloy.com/fullstack/vona-zov
 Create a new Cabloy Basic project:
 
 ```bash
-npm create cabloy
+npm create cabloy@latest
 ```
 
 For Cabloy Start, clone the [Cabloy Start repository](https://github.com/cabloy/cabloy-start) and run `npm run init` from its root. See the [Fullstack Quickstart](https://cabloy.com/fullstack/quickstart) for prerequisites and development commands.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.219",
+  "version": "5.1.220",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/repo-docs/fullstack/quickstart.md

@@ -21,7 +21,7 @@ Before creating a new Cabloy project, make sure your environment has:
 ## 2. Create a new project
 
 ```bash
-npm create cabloy
+npm create cabloy@latest
 ```
 
 The generated project includes `repo-agent-governance/` plus committed adapters for Claude Code, Codex, and Cursor. This path creates a Cabloy Basic project baseline. Open it in a supported coding agent and start with the project-specific guidance; regenerate adapters from the canonical governance source rather than editing generated files directly.
@@ -52,13 +52,13 @@ npm create cabloy
 #### Windows Command Prompt
 
 ```cmd
-set pnpm_config_minimum_release_age=0 && npm create cabloy
+set pnpm_config_minimum_release_age=0 && npm create cabloy@latest
 ```
 
 #### macOS / Linux
 
 ```bash
-pnpm_config_minimum_release_age=0 npm create cabloy
+pnpm_config_minimum_release_age=0 npm create cabloy@latest
 ```
 
 ## 3. Start Vona integrated SSR

package/repo-docs/reference/repo-scripts.md

@@ -82,6 +82,18 @@ A process-list match or a free port alone is not proof of either a conflict or s
 
 `npm run contract:generate:isolated -- <module-name>` starts a fresh test-mode Vona service on a run-owned loopback port, verifies its signed readiness response, fetches the Swagger document, and invokes the existing Zova OpenAPI generator without Playwright. The run owns its disposable test resources and claim-backed local roots; successful runs clean them after the service drains, while failures retain the claim and evidence for inspection. The generated SDK files under `zova/src/**` remain shared checkout output, so serialize concurrent generation for the same workspace/module and do not treat this command as an automatic rollback boundary.
 
+For an explicitly authorized contract-generation run that must not reap historical claims, Cabloy Basic and Cabloy Start support this opt-in form:
+
+```bash
+npm run contract:generate:isolated -- <module-name> --skip-expired-claim-reaping
+```
+
+The wrapper consumes this standalone flag rather than forwarding it to Zova; `--skip-expired-claim-reaping=...` is rejected. Without the flag, contract generation retains normal historical-claim reaping. Unit, coverage and E2E defaults are unchanged; the runner rejects their use of this opt-out.
+
+The opt-in lane requires strict freshness after application configuration and before module loading: run-owned public/runtime/SQLite directories must be absent or empty, shared and static-isolate database namespaces must be absent, and persistent Redis namespaces must be empty. Read-only discovery failures or preexisting resources fail closed rather than authorizing deletion. Startup requires per-application freshness proof to bypass normal test clearing; database preparation rechecks the namespace, never drops existing databases in this lane, and reuses only a database creation recorded by that application.
+
+This still loads environment configuration, initializes newly allocated test databases and Redis/runtime resources, and runs normal module seeds. Successful runs clean only their inventoried current-run resources after verified shutdown; failed runs retain their claim/resources, without automatic generation retry or fallback. Generated consumers remain shared checkout writes. Freshness is a snapshot, **not an exclusive lease**, zero-mutation mode, network sandbox, blanket log-redaction guarantee, or authorization to contact a Provider. Independently configured external resources and Provider operations retain their separate ownership and approval requirements. This shared flag does not extend Basic's separately scoped Windows verification to Start.
+
 For Vona integrated SSR, the allocated E2E origin is supplied to Zova at runtime as server `SSR_API_BASE_URL` and browser `API_BASE_URL`. Do not edit Zova `.env` files or rebuild solely to match the test port. The current root `npm run test:e2e` consumes prebuilt frontend artifacts; refresh affected SSR/REST output and synchronize dependencies when their inputs change. See [Runtime API origins in Vona integrated SSR](/fullstack/ssr-entry-modes#runtime-api-origins-in-vona-integrated-ssr) for configuration overrides and scope.
 
 For deliberate **dev-mode** database preparation, `npm run db:reset` is a separate, destructive command: in a single process, it clears validated application-owned Redis keys, drops and recreates managed disposable development databases, reruns migrations and instance initialization, then runs module `seed()` hooks. It requires `database.testDatabase: true` in the dev configuration and a connection outside the disposable database. Ordinary `npm run dev` and `npm run dev:one` only reuse existing managed databases; if any required target is missing, startup fails promptly with an instruction to run `npm run db:reset`. They do not create databases, perform creation-time Redis cleanup, or seed. Never run `db:reset` against development data you need to retain. Upgrades do not reset existing development data or repeat its seeds. See [Development database preparation](#development-database-preparation) and [Migration and Changes](/backend/migration-and-changes#local-development-workflow).

package/scripts/generateOpenapiIsolated.test.ts

@@ -9,10 +9,35 @@ import type { GuardianResult, OwnedProcess } from './runIsolatedTest.ts';
 import {
   getOpenapiGeneratorCommand,
   getOpenapiSource,
+  parseIsolatedOpenapiArgs,
   validateOpenapiSource,
 } from './generateOpenapiIsolated.ts';
 import { getIsolatedVonaCommand, ROOT_DIR, withIsolatedVona } from './runIsolatedTest.ts';
 
+test('contract reaping opt-out is explicit and removed from generator arguments', () => {
+  const original = ['training-student', '--skip-expired-claim-reaping', '--nometadata'];
+  const parsed = parseIsolatedOpenapiArgs(original);
+  assert.deepEqual(parsed, {
+    generatorArgs: ['training-student', '--nometadata'],
+    skipExpiredClaimReaping: true,
+  });
+  assert.deepEqual(original, ['training-student', '--skip-expired-claim-reaping', '--nometadata']);
+  assert.equal(
+    getOpenapiGeneratorCommand(parsed.generatorArgs).args.includes('--skip-expired-claim-reaping'),
+    false,
+  );
+  assert.deepEqual(parseIsolatedOpenapiArgs(['training-student']), {
+    generatorArgs: ['training-student'],
+    skipExpiredClaimReaping: false,
+  });
+  for (const value of ['true', 'false', '']) {
+    assert.throws(
+      () => parseIsolatedOpenapiArgs([`--skip-expired-claim-reaping=${value}`]),
+      /standalone flag/,
+    );
+  }
+});
+
 test('builds the isolated Swagger source from the allocated port', () => {
   assert.equal(getOpenapiSource(7123), 'http://127.0.0.1:7123/swagger/json?version=V31');
 });

package/scripts/generateOpenapiIsolated.ts

@@ -15,6 +15,17 @@ export function getOpenapiSource(port: number) {
   return `http://127.0.0.1:${port}/swagger/json?version=${OPENAPI_VERSION}`;
 }
 
+export function parseIsolatedOpenapiArgs(args: string[]) {
+  const flag = '--skip-expired-claim-reaping';
+  if (args.some(arg => arg.startsWith(`${flag}=`))) {
+    throw new Error(`${flag} is a standalone flag`);
+  }
+  return {
+    generatorArgs: args.filter(arg => arg !== flag),
+    skipExpiredClaimReaping: args.includes(flag),
+  };
+}
+
 export function getOpenapiGeneratorCommand(args: string[]) {
   if (args.some(arg => /^--projectPath(?:=|$)/.test(arg))) {
     throw new Error(
@@ -67,23 +78,29 @@ export async function validateOpenapiSource(source: string) {
 }
 
 export async function generateOpenapiIsolated(args: string[]) {
-  const command = getOpenapiGeneratorCommand(args);
+  const { generatorArgs, skipExpiredClaimReaping } = parseIsolatedOpenapiArgs(args);
+  const command = getOpenapiGeneratorCommand(generatorArgs);
   if (process.env.E2E_BASE_URL !== undefined) {
     throw new Error(
       'E2E_BASE_URL is unsupported; isolated OpenAPI generation manages a local test-mode target.',
     );
   }
-  return await withIsolatedRun('contract', async ({ env, port }) => {
-    const source = getOpenapiSource(port);
-    await withIsolatedVona(port, env, async () => {
-      await validateOpenapiSource(source);
-      await runIsolatedProcess(command.command, command.args, command.cwd, {
-        ...env,
-        OPENAPI_SOURCE_URL: source,
-        VONA_TEST_READY_KEY: undefined,
+  return await withIsolatedRun(
+    'contract',
+    async ({ env, port }) => {
+      const source = getOpenapiSource(port);
+      await withIsolatedVona(port, env, async () => {
+        await validateOpenapiSource(source);
+        await runIsolatedProcess(command.command, command.args, command.cwd, {
+          ...env,
+          OPENAPI_SOURCE_URL: source,
+          VONA_TEST_READY_KEY: undefined,
+        });
       });
-    });
-  });
+    },
+    ROOT_DIR,
+    { skipExpiredClaimReaping },
+  );
 }
 
 if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {

package/scripts/runIsolatedTest.test.ts

@@ -33,6 +33,7 @@ import {
   createTestRunId,
   getUnitTestCommands,
   reserveTestRun,
+  reapBeforeIsolatedRun,
   resolveNpmCli,
   resolveCabloyEdition,
   ROOT_DIR,
@@ -51,6 +52,97 @@ const isolationSource = resolve(
   'vona/packages-vona/vona-core/src/lib/core/testIsolation.ts',
 );
 
+test('claim reaping defaults remain enabled and contract opt-out never calls the reaper', async () => {
+  const calls: string[] = [];
+  const reap = async (projectPath: string) => {
+    calls.push(projectPath);
+    return [];
+  };
+  for (const kind of ['unit', 'cov', 'e2e', 'contract'] as const) {
+    await reapBeforeIsolatedRun(kind, '/synthetic/vona', {}, reap);
+  }
+  assert.deepEqual(calls, [
+    '/synthetic/vona',
+    '/synthetic/vona',
+    '/synthetic/vona',
+    '/synthetic/vona',
+  ]);
+  await reapBeforeIsolatedRun(
+    'contract',
+    '/synthetic/vona',
+    { skipExpiredClaimReaping: true },
+    async () => {
+      throw new Error('historical reaper must not run');
+    },
+  );
+  for (const kind of ['unit', 'cov', 'e2e'] as const) {
+    await assert.rejects(
+      reapBeforeIsolatedRun(kind, '/synthetic/vona', { skipExpiredClaimReaping: true }, reap),
+      /supported only for contract generation/,
+    );
+  }
+  assert.equal(calls.length, 4);
+});
+
+test('public test entrypoints reject contract-only flags before claim reaping', () => {
+  const runnerUrl = new URL('./runIsolatedTest.ts', import.meta.url).href;
+  const source = `
+    import assert from 'node:assert/strict';
+    import { registerHooks } from 'node:module';
+    globalThis.cleanupCalls = [];
+    registerHooks({ resolve(specifier, context, nextResolve) {
+      if (context.parentURL === ${JSON.stringify(runnerUrl)} && specifier === './testClaimCleanup.ts') {
+        const source = \`
+          export function parseTestClaimTtlSeconds() { return 1; }
+          export async function reapExpiredTestClaims() {
+            globalThis.cleanupCalls.push('reap');
+            throw new Error('unexpected claim reaping');
+          }
+          export async function cleanTestClaim() {
+            globalThis.cleanupCalls.push('clean');
+            throw new Error('unexpected claim cleanup');
+          }
+        \`;
+        return { url: 'data:text/javascript,' + encodeURIComponent(source), shortCircuit: true };
+      }
+      return nextResolve(specifier, context);
+    } });
+    const { runIsolatedTest } = await import(${JSON.stringify(runnerUrl)});
+    for (const [kind, args] of [['unit', []], ['unit', ['--coverage']], ['e2e', []]]) {
+      for (const suffix of ['', '=true', '=false', '=']) {
+        await assert.rejects(
+          runIsolatedTest(kind, [...args, '--skip-expired-claim-reaping' + suffix]),
+          /--skip-expired-claim-reaping is supported only for contract generation/,
+        );
+        assert.deepEqual(globalThis.cleanupCalls, []);
+      }
+    }
+    await assert.rejects(runIsolatedTest('unit', []), /unexpected claim reaping/);
+    assert.deepEqual(globalThis.cleanupCalls, ['reap']);
+  `;
+  const result = spawnSync(process.execPath, ['--input-type=module', '-e', source], {
+    cwd: ROOT_DIR,
+    env: { ...process.env, E2E_BASE_URL: undefined },
+    encoding: 'utf8',
+    timeout: 10_000,
+  });
+  assert.equal(result.error, undefined);
+  assert.equal(result.status, 0, result.stderr);
+});
+
+test('claim reaping errors propagate without retries', async () => {
+  const error = new Error('synthetic reaper failure');
+  let calls = 0;
+  await assert.rejects(
+    reapBeforeIsolatedRun('contract', '/synthetic/vona', {}, async () => {
+      calls++;
+      throw error;
+    }),
+    value => value === error,
+  );
+  assert.equal(calls, 1);
+});
+
 test('public test scripts delegate to the isolated runner without recursion', () => {
   const root = JSON.parse(readFileSync(resolve(ROOT_DIR, 'package.json'), 'utf8'));
   const original = JSON.parse(
@@ -223,51 +315,71 @@ test('creates exclusive manifest claims and refuses stale or symlinked roots', a
   }
 });
 
-test('contract runs clean owned roots on success and retain failed-run evidence', async () => {
-  const root = mkdtempSync(join(realpathSync(tmpdir()), 'cabloy-contract-run-'));
-  mkdirSync(join(root, 'vona'));
-  writeFileSync(join(root, '__CABLOY_BASIC__'), '');
-  let claimPath = '';
-  let dataRoot = '';
-  let generatedRoot = '';
-  try {
-    assert.equal(
-      await withIsolatedRun(
-        'contract',
-        async context => {
-          ({ claimPath, dataRoot, generatedRoot } = context);
-          assert.equal((await loadTestClaim(claimPath)).kind, 'contract');
-          assert.equal(context.env.META_MODE, 'test');
-          assert.equal(context.env.VONA_DB_RESET, undefined);
-          assert.equal(context.env.VONA_TEST_READY_KEY, undefined);
-          assert.ok(existsSync(join(dataRoot, '.vona-test-owner')));
-          return 'generated';
-        },
-        root,
-      ),
-      'generated',
-    );
-    assert.equal(existsSync(claimPath), false);
-    assert.equal(existsSync(dataRoot), false);
-    assert.equal(existsSync(generatedRoot), false);
-    await assert.rejects(
-      withIsolatedRun(
-        'contract',
-        async context => {
-          ({ claimPath, dataRoot, generatedRoot } = context);
-          throw new Error('generator failed');
-        },
-        root,
-      ),
-      /generator failed/,
-    );
-    assert.equal((await loadTestClaim(claimPath)).status, 'failed');
-    assert.equal(existsSync(dataRoot), true);
-    assert.equal(existsSync(generatedRoot), true);
-  } finally {
-    rmSync(root, { recursive: true, force: true });
-  }
-});
+for (const marker of ['__CABLOY_BASIC__', '__CABLOY_START__']) {
+  test(
+    `contract runs clean owned roots on success and retain failed-run evidence for ${marker}`,
+    { concurrency: false },
+    async () => {
+      const root = mkdtempSync(join(realpathSync(tmpdir()), 'cabloy-contract-run-'));
+      mkdirSync(join(root, 'vona'));
+      writeFileSync(join(root, marker), '');
+      let claimPath = '';
+      let dataRoot = '';
+      let generatedRoot = '';
+      const previous = process.env.VONA_TEST_REQUIRE_FRESH_RESOURCES;
+      try {
+        process.env.VONA_TEST_REQUIRE_FRESH_RESOURCES = 'true';
+        await withIsolatedRun(
+          'contract',
+          async context => {
+            assert.equal(context.env.VONA_TEST_REQUIRE_FRESH_RESOURCES, undefined);
+          },
+          root,
+        );
+        assert.equal(
+          await withIsolatedRun(
+            'contract',
+            async context => {
+              ({ claimPath, dataRoot, generatedRoot } = context);
+              assert.equal((await loadTestClaim(claimPath)).kind, 'contract');
+              assert.equal(context.env.META_MODE, 'test');
+              assert.equal(context.env.VONA_DB_RESET, undefined);
+              assert.equal(context.env.VONA_TEST_READY_KEY, undefined);
+              assert.equal(context.env.VONA_TEST_REQUIRE_FRESH_RESOURCES, 'true');
+              assert.ok(existsSync(join(dataRoot, '.vona-test-owner')));
+              return 'generated';
+            },
+            root,
+            { skipExpiredClaimReaping: true },
+          ),
+          'generated',
+        );
+        assert.equal(existsSync(claimPath), false);
+        assert.equal(existsSync(dataRoot), false);
+        assert.equal(existsSync(generatedRoot), false);
+        await assert.rejects(
+          withIsolatedRun(
+            'contract',
+            async context => {
+              ({ claimPath, dataRoot, generatedRoot } = context);
+              throw new Error('generator failed');
+            },
+            root,
+            { skipExpiredClaimReaping: true },
+          ),
+          /generator failed/,
+        );
+        assert.equal((await loadTestClaim(claimPath)).status, 'failed');
+        assert.equal(existsSync(dataRoot), true);
+        assert.equal(existsSync(generatedRoot), true);
+      } finally {
+        if (previous === undefined) delete process.env.VONA_TEST_REQUIRE_FRESH_RESOURCES;
+        else process.env.VONA_TEST_REQUIRE_FRESH_RESOURCES = previous;
+        rmSync(root, { recursive: true, force: true });
+      }
+    },
+  );
+}
 
 test('readiness retries signed not-ready responses and rejects server exit or timeout', async () => {
   const key = 'a'.repeat(64);

package/scripts/runIsolatedTest.ts

@@ -546,19 +546,39 @@ export interface IsolatedRunContext {
   env: NodeJS.ProcessEnv;
 }
 
+export interface IsolatedRunOptions {
+  skipExpiredClaimReaping?: boolean;
+}
+
+export async function reapBeforeIsolatedRun(
+  kind: 'unit' | 'cov' | 'e2e' | 'contract',
+  vonaDir: string,
+  options: IsolatedRunOptions = {},
+  reap: typeof reapExpiredTestClaims = reapExpiredTestClaims,
+): Promise<void> {
+  if (options.skipExpiredClaimReaping) {
+    if (kind !== 'contract') {
+      throw new Error('Skipping expired claim reaping is supported only for contract generation');
+    }
+    return;
+  }
+  await reap(vonaDir, {
+    ttlSeconds: parseTestClaimTtlSeconds(),
+    now: Date.now(),
+    isInactive: claim => isTestClaimInactive(claim),
+    warn: message => console.error(message),
+  });
+}
+
 export async function withIsolatedRun<T>(
   kind: 'unit' | 'cov' | 'e2e' | 'contract',
   callback: (context: IsolatedRunContext) => Promise<T>,
   rootDir = ROOT_DIR,
+  options: IsolatedRunOptions = {},
 ): Promise<T> {
   resolveCabloyEdition(rootDir);
   const vonaDir = resolve(rootDir, 'vona');
-  await reapExpiredTestClaims(vonaDir, {
-    ttlSeconds: parseTestClaimTtlSeconds(),
-    now: Date.now(),
-    isInactive: claim => isTestClaimInactive(claim),
-    warn: message => console.error(message),
-  });
+  await reapBeforeIsolatedRun(kind, vonaDir, options);
   const runId = createTestRunId();
   const dataRoot = resolve(vonaDir, `.app-test-${runId}`);
   const generatedRoot = resolve(vonaDir, `.vona-test-${runId}`);
@@ -580,6 +600,7 @@ export async function withIsolatedRun<T>(
       META_MODE: 'test',
       VONA_DB_RESET: undefined,
       VONA_TEST_RUN_ID: runId,
+      VONA_TEST_REQUIRE_FRESH_RESOURCES: options.skipExpiredClaimReaping ? 'true' : undefined,
       VONA_TEST_READY_KEY: undefined,
       VONA_TEST_SERVER_ORIGIN: undefined,
       APP_NAME: `cabtest${runId}`,
@@ -631,6 +652,9 @@ export async function withIsolatedRun<T>(
 }
 
 export async function runIsolatedTest(kind: 'unit' | 'e2e', args: string[]) {
+  if (args.some(arg => /^--skip-expired-claim-reaping(?:=|$)/.test(arg))) {
+    throw new Error('--skip-expired-claim-reaping is supported only for contract generation');
+  }
   if (process.env.E2E_BASE_URL !== undefined) {
     throw new Error(
       'E2E_BASE_URL is unsupported; the E2E runner manages a local test-mode target.',