cabloy 5.1.210 → 5.1.211

package/scripts/generateOpenapiIsolated.ts

@@ -0,0 +1,91 @@
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  ROOT_DIR,
+  runIsolatedProcess,
+  withIsolatedVona,
+  withIsolatedRun,
+} from './runIsolatedTest.ts';
+
+const OPENAPI_VERSION = 'V31';
+const SOURCE_TIMEOUT_MS = 30_000;
+
+export function getOpenapiSource(port: number) {
+  return `http://127.0.0.1:${port}/swagger/json?version=${OPENAPI_VERSION}`;
+}
+
+export function getOpenapiGeneratorCommand(args: string[]) {
+  if (args.some(arg => /^--projectPath(?:=|$)/.test(arg))) {
+    throw new Error(
+      'Isolated OpenAPI generation uses the current Zova project; projectPath overrides are unsupported',
+    );
+  }
+  return {
+    command: process.execPath,
+    args: [
+      './zova/packages-cli/cli/src/bin/zova.ts',
+      '--projectPath=zova',
+      ':openapi:generate',
+      ...args,
+    ],
+    cwd: ROOT_DIR,
+  };
+}
+
+export async function validateOpenapiSource(source: string) {
+  let response: Response;
+  try {
+    response = await fetch(source, {
+      signal: AbortSignal.timeout(SOURCE_TIMEOUT_MS),
+      redirect: 'error',
+    });
+  } catch (error) {
+    throw new Error('Isolated OpenAPI source request failed', { cause: error });
+  }
+  if (!response.ok) {
+    throw new Error(`Isolated OpenAPI source returned HTTP ${response.status}`);
+  }
+  let document: unknown;
+  try {
+    document = await response.json();
+  } catch (error) {
+    throw new Error('Isolated OpenAPI source returned invalid JSON', { cause: error });
+  }
+  if (!document || typeof document !== 'object' || Array.isArray(document)) {
+    throw new Error('Isolated OpenAPI source returned an invalid document');
+  }
+  const record = document as Record<string, unknown>;
+  if (
+    (typeof record.openapi !== 'string' && typeof record.swagger !== 'string') ||
+    !record.paths ||
+    typeof record.paths !== 'object' ||
+    Array.isArray(record.paths)
+  ) {
+    throw new Error('Isolated OpenAPI source returned an invalid document');
+  }
+}
+
+export async function generateOpenapiIsolated(args: string[]) {
+  const command = getOpenapiGeneratorCommand(args);
+  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,
+      });
+    });
+  });
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  await generateOpenapiIsolated(process.argv.slice(2));
+}

package/scripts/runIsolatedTest.test.ts

@@ -38,6 +38,7 @@ import {
   runIsolatedTest,
   verifyReadyProof,
   waitForReady,
+  withIsolatedRun,
 } from './runIsolatedTest.ts';
 
 const isolationSource = resolve(
@@ -53,6 +54,10 @@ test('public test scripts delegate to the isolated runner without recursion', ()
   const working = JSON.parse(readFileSync(resolve(ROOT_DIR, 'vona/package.json'), 'utf8'));
   assert.equal(root.scripts.test, 'cd vona && npm run test');
   assert.equal(root.scripts['test:e2e'], 'node scripts/runIsolatedTest.ts e2e');
+  assert.equal(
+    root.scripts['contract:generate:isolated'],
+    'node scripts/generateOpenapiIsolated.ts',
+  );
   assert.equal(original.scripts.test, 'node ../scripts/runIsolatedTest.ts unit');
   assert.equal(original.scripts.cov, 'node ../scripts/runIsolatedTest.ts unit --coverage');
   assert.equal(working.scripts.test, original.scripts.test);
@@ -143,6 +148,91 @@ 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 });
+  }
+});
+
+test('readiness retries signed not-ready responses and rejects server exit or timeout', async () => {
+  const key = 'a'.repeat(64);
+  let requests = 0;
+  const listener = createServer((req, res) => {
+    requests++;
+    res.writeHead(requests === 1 ? 503 : 200, {
+      'content-type': 'application/json',
+      'x-vona-test-proof': createHmac('sha256', key)
+        .update(String(req.headers['x-vona-test-challenge']))
+        .digest('hex'),
+    });
+    res.end(JSON.stringify({ status: requests === 1 ? 'starting' : 'ok' }));
+  });
+  await new Promise<void>(resolve => listener.listen(0, '127.0.0.1', resolve));
+  const address = listener.address();
+  assert.ok(address && typeof address !== 'string');
+  const pending = { wait: () => new Promise(() => {}), stop: async () => undefined } as never;
+  try {
+    await waitForReady(address.port, pending, key, 2000);
+    assert.equal(requests, 2);
+    await assert.rejects(waitForReady(address.port, pending, key, 0), /did not become ready/);
+    await assert.rejects(
+      waitForReady(
+        address.port,
+        {
+          wait: async () => ({ type: 'drained', failed: true }),
+          stop: async () => ({ type: 'drained', failed: true }),
+        },
+        key,
+      ),
+      /exited before readiness/,
+    );
+  } finally {
+    await new Promise<void>((resolve, reject) =>
+      listener.close(error => (error ? reject(error) : resolve())),
+    );
+  }
+});
+
 test('allocates a loopback listener without a persistent reservation', async () => {
   const first = await allocateTestPort();
   assert.ok(first > 0 && first <= 65535);

package/scripts/runIsolatedTest.ts

@@ -44,7 +44,7 @@ export function createTestRunId(date = new Date()) {
 export async function reserveTestRun(
   vonaDir: string,
   runId: string,
-  kind: 'unit' | 'cov' | 'e2e' = 'unit',
+  kind: 'unit' | 'cov' | 'e2e' | 'contract' = 'unit',
 ) {
   const identity = await inspectTestProcess(process.pid);
   const { claimPath } = await createTestClaim(vonaDir, runId, kind, {
@@ -75,18 +75,18 @@ function toError(value: unknown) {
   return value instanceof Error ? value : new Error(String(value));
 }
 
-interface GuardianResult {
+export interface GuardianResult {
   type: 'drained';
   result?: { code: number | null; signal: NodeJS.Signals | null };
   failed: boolean;
 }
 
-interface OwnedProcess {
+export interface OwnedProcess {
   wait: () => Promise<GuardianResult>;
   stop: () => Promise<GuardianResult>;
 }
 
-async function startOwnedProcess(
+export async function startOwnedProcess(
   command: string,
   args: string[],
   cwd: string,
@@ -234,6 +234,89 @@ async function startOwnedProcess(
   return { wait, stop };
 }
 
+export function getIsolatedVonaCommand(port: number, env: NodeJS.ProcessEnv, readyKey: string) {
+  return {
+    command: process.execPath,
+    args: [
+      './packages-cli/cli/src/bin/vona.ts',
+      ':bin:dev',
+      '--workers=1',
+      '--flavor=normal',
+      '--mode=test',
+    ],
+    cwd: resolve(ROOT_DIR, 'vona'),
+    env: {
+      ...env,
+      VONA_TEST_READY_KEY: readyKey,
+      VONA_TEST_SERVER_ORIGIN: 'true',
+      SERVER_SERVE_PROTOCOL: 'http',
+      SERVER_SERVE_HOST: `127.0.0.1:${port}`,
+    },
+  };
+}
+
+export async function withIsolatedVona<T>(
+  port: number,
+  env: NodeJS.ProcessEnv,
+  callback: () => Promise<T>,
+  dependencies = { start: startOwnedProcess, ready: waitForReady },
+): Promise<T> {
+  const readyKey = randomBytes(32).toString('hex');
+  const command = getIsolatedVonaCommand(port, env, readyKey);
+  const server = await dependencies.start(command.command, command.args, command.cwd, command.env);
+  let stopping = false;
+  let exitedEarly = false;
+  void server.wait().then(
+    () => {
+      if (!stopping) exitedEarly = true;
+    },
+    () => {
+      if (!stopping) exitedEarly = true;
+    },
+  );
+  let interrupted = false;
+  const onInterrupt = () => {
+    interrupted = true;
+    void server.stop().catch(console.error);
+  };
+  process.on('SIGINT', onInterrupt);
+  process.on('SIGTERM', onInterrupt);
+  let operationError: Error | undefined;
+  let shutdownError: Error | undefined;
+  let result: T | undefined;
+  try {
+    await dependencies.ready(port, server, readyKey);
+    if (interrupted) throw new Error('Isolated Vona run interrupted');
+    result = await callback();
+  } catch (error) {
+    operationError = toError(error);
+  } finally {
+    stopping = true;
+    try {
+      const stopped = await server.stop();
+      if (stopped.failed || interrupted || exitedEarly || stopped.result?.code !== 0) {
+        shutdownError = new Error(
+          'Isolated Vona server did not stop cleanly, exited early, or run was interrupted',
+        );
+      }
+    } catch (error) {
+      shutdownError = toError(error);
+    } finally {
+      process.off('SIGINT', onInterrupt);
+      process.off('SIGTERM', onInterrupt);
+    }
+  }
+  if (operationError && shutdownError) {
+    throw new AggregateError(
+      [operationError, shutdownError],
+      'Isolated Vona operation and shutdown failed',
+    );
+  }
+  if (shutdownError) throw toError(shutdownError);
+  if (operationError) throw toError(operationError);
+  return result as T;
+}
+
 export async function runIsolatedProcess(
   command: string,
   args: string[],
@@ -265,11 +348,16 @@ export function verifyReadyProof(challenge: string, key: string, proof: string |
   return timingSafeEqual(expected, Buffer.from(proof, 'hex'));
 }
 
-export async function waitForReady(port: number, server: OwnedProcess, key: string) {
-  const deadline = Date.now() + 180_000;
+export async function waitForReady(
+  port: number,
+  server: OwnedProcess,
+  key: string,
+  timeoutMs = 180_000,
+) {
+  const deadline = Date.now() + timeoutMs;
   const url = `http://127.0.0.1:${port}/health/ready`;
   const exited = server.wait().then(() => {
-    throw new Error('Isolated E2E server exited before readiness');
+    throw new Error('Isolated Vona server exited before readiness');
   });
   while (Date.now() < deadline) {
     const challenge = randomBytes(16).toString('hex');
@@ -288,12 +376,12 @@ export async function waitForReady(port: number, server: OwnedProcess, key: stri
       continue;
     }
     if (!verifyReadyProof(challenge, key, response.headers.get('x-vona-test-proof'))) {
-      throw new Error('Isolated E2E listener does not belong to this test run');
+      throw new Error('Isolated Vona listener does not belong to this test run');
     }
     if (response.ok && ((await response.json()) as { status?: string }).status === 'ok') return;
     await Promise.race([new Promise(resolvePromise => setTimeout(resolvePromise, 200)), exited]);
   }
-  throw new Error('Isolated E2E server did not become ready with a valid ownership proof');
+  throw new Error('Isolated Vona server did not become ready with a valid ownership proof');
 }
 
 export function getUnitTestCommands(args: string[]) {
@@ -326,14 +414,24 @@ export function resolveCabloyEdition(rootDir = ROOT_DIR): 'basic' | 'start' {
   return hasBasic ? 'basic' : 'start';
 }
 
-export async function runIsolatedTest(kind: 'unit' | 'e2e', args: string[]) {
-  resolveCabloyEdition();
-  if (process.env.E2E_BASE_URL !== undefined) {
-    throw new Error(
-      'E2E_BASE_URL is unsupported; the E2E runner manages a local test-mode target.',
-    );
-  }
-  const vonaDir = resolve(ROOT_DIR, 'vona');
+export interface IsolatedRunContext {
+  runId: string;
+  vonaDir: string;
+  dataRoot: string;
+  generatedRoot: string;
+  port: number;
+  claimPath: string;
+  broker: Awaited<ReturnType<typeof startTestClaimBroker>>;
+  env: NodeJS.ProcessEnv;
+}
+
+export async function withIsolatedRun<T>(
+  kind: 'unit' | 'cov' | 'e2e' | 'contract',
+  callback: (context: IsolatedRunContext) => Promise<T>,
+  rootDir = ROOT_DIR,
+): Promise<T> {
+  resolveCabloyEdition(rootDir);
+  const vonaDir = resolve(rootDir, 'vona');
   await reapExpiredTestClaims(vonaDir, {
     ttlSeconds: parseTestClaimTtlSeconds(),
     now: Date.now(),
@@ -344,13 +442,10 @@ export async function runIsolatedTest(kind: 'unit' | 'e2e', args: string[]) {
   const dataRoot = resolve(vonaDir, `.app-test-${runId}`);
   const generatedRoot = resolve(vonaDir, `.vona-test-${runId}`);
   const port = await allocateTestPort();
-  const claimPath = await reserveTestRun(
-    vonaDir,
-    runId,
-    kind === 'unit' && args.includes('--coverage') ? 'cov' : kind,
-  );
+  const claimPath = await reserveTestRun(vonaDir, runId, kind);
   let broker: Awaited<ReturnType<typeof startTestClaimBroker>> | undefined;
   let completed = false;
+  let result: T | undefined;
   try {
     broker = await startTestClaimBroker(claimPath);
     createOwned(dataRoot, runId);
@@ -374,64 +469,16 @@ export async function runIsolatedTest(kind: 'unit' | 'e2e', args: string[]) {
       TMPDIR: resolve(dataRoot, 'tmp'),
     };
     await broker.update({ type: 'status', status: 'running' });
-    if (kind === 'unit') {
-      for (const { command, args: commandArgs, cwd } of getUnitTestCommands(args)) {
-        await runIsolatedProcess(command, commandArgs, cwd, env);
-      }
-    } else {
-      let e2eError: unknown;
-      const readyKey = randomBytes(32).toString('hex');
-      const server = await startOwnedProcess(
-        process.execPath,
-        [
-          './packages-cli/cli/src/bin/vona.ts',
-          ':bin:dev',
-          '--workers=1',
-          '--flavor=normal',
-          '--mode=test',
-        ],
-        resolve(ROOT_DIR, 'vona'),
-        {
-          ...env,
-          VONA_TEST_READY_KEY: readyKey,
-          VONA_TEST_SERVER_ORIGIN: 'true',
-          SERVER_SERVE_PROTOCOL: 'http',
-          SERVER_SERVE_HOST: `127.0.0.1:${port}`,
-        },
-      );
-      let interrupted = false;
-      let serverError: unknown;
-      const onInterrupt = () => {
-        interrupted = true;
-        void server.stop().catch(console.error);
-      };
-      process.on('SIGINT', onInterrupt);
-      process.on('SIGTERM', onInterrupt);
-      try {
-        await waitForReady(port, server, readyKey);
-        await runIsolatedProcess(
-          process.execPath,
-          ['repo-e2e/scripts/runE2e.ts', ...args],
-          ROOT_DIR,
-          env,
-        );
-      } catch (error) {
-        e2eError = error;
-      } finally {
-        process.off('SIGINT', onInterrupt);
-        process.off('SIGTERM', onInterrupt);
-        try {
-          const result = await server.stop();
-          if (result.failed || interrupted) {
-            serverError = new Error('Isolated E2E server did not stop cleanly');
-          }
-        } catch (error) {
-          serverError = error;
-        }
-      }
-      if (serverError) throw toError(serverError);
-      if (e2eError) throw toError(e2eError);
-    }
+    result = await callback({
+      runId,
+      vonaDir,
+      dataRoot,
+      generatedRoot,
+      port,
+      claimPath,
+      broker,
+      env,
+    });
     completed = true;
   } catch (error) {
     await broker?.update({ type: 'status', status: 'failed' }).catch(() => {
@@ -444,15 +491,43 @@ export async function runIsolatedTest(kind: 'unit' | 'e2e', args: string[]) {
     }
     await broker?.close();
   }
-  const result = await cleanTestClaim(claimPath, {
+  const cleanup = await cleanTestClaim(claimPath, {
     projectPath: vonaDir,
     isInactive: claim => isTestClaimInactive(claim, true),
     warn: message => console.error(message),
   });
-  if (result.status !== 'cleaned') {
+  if (cleanup.status !== 'cleaned') {
     console.error(`Isolated test claim retained for inspection: ${claimPath}`);
     throw new Error('Isolated test succeeded but resource cleanup did not complete');
   }
+  return result as T;
+}
+
+export async function runIsolatedTest(kind: 'unit' | 'e2e', args: string[]) {
+  if (process.env.E2E_BASE_URL !== undefined) {
+    throw new Error(
+      'E2E_BASE_URL is unsupported; the E2E runner manages a local test-mode target.',
+    );
+  }
+  await withIsolatedRun(
+    kind === 'unit' && args.includes('--coverage') ? 'cov' : kind,
+    async ({ env, port }) => {
+      if (kind === 'unit') {
+        for (const { command, args: commandArgs, cwd } of getUnitTestCommands(args)) {
+          await runIsolatedProcess(command, commandArgs, cwd, env);
+        }
+        return;
+      }
+      await withIsolatedVona(port, env, () =>
+        runIsolatedProcess(
+          process.execPath,
+          ['repo-e2e/scripts/runE2e.ts', ...args],
+          ROOT_DIR,
+          env,
+        ),
+      );
+    },
+  );
 }
 
 if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {

package/scripts/upgrade.test.ts

@@ -1,4 +1,5 @@
 import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
 import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, resolve } from 'node:path';
@@ -128,6 +129,118 @@ test('isolated dry-run reports changes without writing files or contacting npm',
   }
 });
 
+const isolatedContractCommand = 'node scripts/generateOpenapiIsolated.ts';
+
+function reconcileContract(project: string, source: string, dryRun = false): string {
+  const result = spawnSync(
+    process.execPath,
+    [
+      '--input-type=module',
+      '--eval',
+      `import { reconcileContractPackageJson } from ${JSON.stringify(new URL('./upgrade.ts', import.meta.url).href)};
+       reconcileContractPackageJson(${dryRun}, ${JSON.stringify(project)}, ${JSON.stringify(source)});`,
+    ],
+    { encoding: 'utf8' },
+  );
+  const output = `${result.stdout}${result.stderr}`;
+  assert.equal(result.status, 0, output);
+  return output;
+}
+
+function addIncomingContractCommand(source: string): void {
+  const pkg = readPackage(source);
+  pkg.scripts['contract:generate:isolated'] = isolatedContractCommand;
+  writeFile(source, 'package.json', `${JSON.stringify(pkg)}\n`);
+}
+
+test('adopts the missing isolated contract command without changing other package entries', () => {
+  const { project, source, dispose } = fixture();
+  try {
+    addIncomingContractCommand(source);
+    const before = readPackage(project);
+    assert.match(reconcileContract(project, source), /Added missing.*contract:generate:isolated/);
+    assert.deepEqual(readPackage(project), {
+      ...before,
+      scripts: { ...before.scripts, 'contract:generate:isolated': isolatedContractCommand },
+    });
+    const first = readFileSync(resolve(project, 'package.json'), 'utf-8');
+    assert.equal(reconcileContract(project, source), '');
+    assert.equal(readFileSync(resolve(project, 'package.json'), 'utf-8'), first);
+  } finally {
+    dispose();
+  }
+});
+
+test('isolated contract reconciliation creates a missing scripts object', () => {
+  const { project, source, dispose } = fixture();
+  try {
+    addIncomingContractCommand(source);
+    writeFile(project, 'package.json', '{"name":"project-owned"}\n');
+    reconcileContract(project, source);
+    assert.deepEqual(readPackage(project), {
+      name: 'project-owned',
+      scripts: { 'contract:generate:isolated': isolatedContractCommand },
+    });
+  } finally {
+    dispose();
+  }
+});
+
+test('isolated contract reconciliation visibly preserves customized values, including empty commands', () => {
+  const { project, source, dispose } = fixture();
+  try {
+    addIncomingContractCommand(source);
+    for (const command of ['node project-contract.ts', '']) {
+      const pkg = readPackage(project);
+      pkg.scripts['contract:generate:isolated'] = command;
+      const before = `${JSON.stringify(pkg)}\n`;
+      writeFile(project, 'package.json', before);
+      for (const dryRun of [false, true]) {
+        const output = reconcileContract(project, source, dryRun);
+        assert.match(output, /Preserved customized.*contract:generate:isolated/);
+        assert.ok(output.includes(isolatedContractCommand), output);
+        assert.equal(readFileSync(resolve(project, 'package.json'), 'utf-8'), before);
+      }
+    }
+  } finally {
+    dispose();
+  }
+});
+
+test('isolated contract dry-run reports adoption without writing and matching commands are a byte-preserving no-op', () => {
+  const { project, source, dispose } = fixture();
+  try {
+    addIncomingContractCommand(source);
+    const before = readFileSync(resolve(project, 'package.json'), 'utf-8');
+    assert.match(
+      reconcileContract(project, source, true),
+      /\[dry-run\] Add missing.*contract:generate:isolated/,
+    );
+    assert.equal(readFileSync(resolve(project, 'package.json'), 'utf-8'), before);
+
+    const pkg = readPackage(project);
+    pkg.scripts['contract:generate:isolated'] = isolatedContractCommand;
+    const matching = `${JSON.stringify(pkg)}\n`;
+    writeFile(project, 'package.json', matching);
+    assert.equal(reconcileContract(project, source), '');
+    assert.equal(reconcileContract(project, source, true), '');
+    assert.equal(readFileSync(resolve(project, 'package.json'), 'utf-8'), matching);
+  } finally {
+    dispose();
+  }
+});
+
+test('isolated contract reconciliation tolerates an older incoming package without the command', () => {
+  const { project, source, dispose } = fixture();
+  try {
+    const before = readFileSync(resolve(project, 'package.json'), 'utf-8');
+    assert.equal(reconcileContract(project, source), '');
+    assert.equal(readFileSync(resolve(project, 'package.json'), 'utf-8'), before);
+  } finally {
+    dispose();
+  }
+});
+
 test('Start edition is not reconciled by the Basic framework E2E upgrader', () => {
   const { project, source, dispose } = fixture();
   try {

package/scripts/upgrade.ts

@@ -322,6 +322,34 @@ function reconcileGovernancePackageJson(dryRun?: boolean): void {
   }
 }
 
+export function reconcileContractPackageJson(
+  dryRun?: boolean,
+  rootDir = ROOT_DIR,
+  tempDir = TEMP_DIR,
+): void {
+  const name = 'contract:generate:isolated';
+  const sourcePackage = readPackageJson(resolve(tempDir, 'package.json'));
+  const command = sourcePackage.scripts?.[name];
+  if (!command) return;
+
+  const projectPackagePath = resolve(rootDir, 'package.json');
+  const projectPackage = readPackageJson(projectPackagePath);
+  if (Object.hasOwn(projectPackage.scripts ?? {}, name)) {
+    if (projectPackage.scripts?.[name] !== command) {
+      log(`  Preserved customized package.json scripts.${name}; incoming command: ${command}`);
+    }
+    return;
+  }
+  if (dryRun) {
+    log(`  [dry-run] Add missing package.json scripts.${name} = ${command}`);
+    return;
+  }
+  projectPackage.scripts ??= {};
+  projectPackage.scripts[name] = command;
+  writeFileSync(projectPackagePath, `${JSON.stringify(projectPackage, null, 2)}\n`);
+  log(`  Added missing package.json scripts.${name}`);
+}
+
 function reconcileGovernanceAssets(dryRun?: boolean): void {
   const command = 'node repo-agent-governance/scripts/governance.mjs adopt --apply';
   if (dryRun) {
@@ -615,6 +643,10 @@ async function main(): Promise<void> {
     reconcileGovernanceAssets(dryRun);
     log('');
 
+    log('Reconciling missing contract-generation package entries...');
+    reconcileContractPackageJson(dryRun);
+    log('');
+
     // 5. Reconcile Cabloy Basic framework E2E manifest entries
     if (isCabloyBasic()) {
       log('Reconciling framework-owned E2E package entries...');