cabloy 5.1.204 → 5.1.205

package/scripts/testClaimCleanup.ts

@@ -0,0 +1,375 @@
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, readdir, rm, unlink } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type {
+  TestClaimDatabase,
+  TestClaimManifest,
+  TestClaimRedis,
+} from '../vona/packages-vona/vona-core/src/lib/core/testClaim.ts';
+
+import {
+  assertTestClaimSafePath,
+  loadTestClaim,
+  TEST_CLAIM_DIRECTORY,
+  writeTestClaim,
+} from '../vona/packages-vona/vona-core/src/lib/core/testClaim.ts';
+import { assertTestRunOwner } from '../vona/packages-vona/vona-core/src/lib/core/testIsolation.ts';
+
+export interface TestClaimCleanupSession {
+  dropDatabase(database: TestClaimDatabase, name: string): Promise<void>;
+  clearRedis(resource: TestClaimRedis): Promise<void>;
+  close(): Promise<void>;
+}
+export interface TestClaimCleanupOptions {
+  projectPath?: string;
+  isInactive?: (
+    claim: TestClaimManifest,
+  ) => Promise<boolean | { inactive: boolean; reason?: string }>;
+  warn?: (message: string) => void;
+  prepare?: (claim: TestClaimManifest, claimPath: string) => Promise<TestClaimCleanupSession>;
+}
+export interface TestClaimReapOptions extends TestClaimCleanupOptions {
+  ttlSeconds?: number;
+  now?: number;
+}
+export interface TestClaimCleanupResult {
+  status: 'cleaned' | 'skipped' | 'failed';
+  reason?: string;
+}
+
+export function parseTestClaimTtlSeconds(
+  value: string | undefined = process.env.VONA_TEST_CLAIM_TTL_SECONDS,
+): number {
+  if (value === undefined) return 86400;
+  if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) <= 0) {
+    throw new Error('VONA_TEST_CLAIM_TTL_SECONDS must be a positive safe integer');
+  }
+  return Number(value);
+}
+
+async function assertSharedDirectory(directory: string, missingAllowed = true) {
+  assertTestClaimSafePath(directory, missingAllowed);
+  let stat;
+  try {
+    stat = await lstat(directory);
+  } catch (error) {
+    if (missingAllowed && (error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw error;
+  }
+  if (
+    !stat.isDirectory() ||
+    (stat.mode & 0o077) !== 0 ||
+    (process.getuid && stat.uid !== process.getuid())
+  ) {
+    throw new Error('Unsafe shared test claim directory');
+  }
+  return true;
+}
+async function exists(file: string) {
+  try {
+    await lstat(file);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw error;
+  }
+}
+async function validateLocalRoots(claim: TestClaimManifest) {
+  for (const local of claim.locals) {
+    assertTestClaimSafePath(local.path);
+    if (!(await exists(local.path))) continue;
+    if (local.stage === 'released') throw new Error('Released local test resource reappeared');
+    const marker = await lstat(path.join(local.path, '.vona-test-owner'));
+    if (marker.isSymbolicLink() || !marker.isFile() || marker.nlink !== 1)
+      throw new Error('Unsafe test owner marker');
+    assertTestRunOwner(local.path, claim.runId);
+  }
+}
+
+export async function cleanTestClaim(
+  claimPath: string,
+  options: TestClaimCleanupOptions = {},
+): Promise<TestClaimCleanupResult> {
+  claimPath = path.resolve(claimPath);
+  // An unsafe shared namespace is fatal to the invocation, not a skippable claim.
+  await assertSharedDirectory(path.dirname(claimPath), false);
+  const warn = options.warn ?? (() => {});
+  const skip = (reason: string): TestClaimCleanupResult => {
+    warn(`Retained test claim ${path.basename(claimPath)}: ${reason}`);
+    return { status: 'skipped', reason };
+  };
+  let claim: TestClaimManifest;
+  try {
+    claim = await loadTestClaim(claimPath);
+    if (options.projectPath && claim.projectPath !== path.resolve(options.projectPath))
+      return skip('checkout mismatch');
+  } catch {
+    return skip('malformed or unsafe manifest');
+  }
+  const lockPath = `${claimPath}.cleanup.lock`;
+  let lock;
+  try {
+    assertTestClaimSafePath(lockPath);
+    lock = await open(
+      lockPath,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+      0o600,
+    );
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'EEXIST')
+      return skip('cleanup lock present; inspect manually, age never permits takeover');
+    return skip('cannot acquire safe cleanup lock');
+  }
+  const token = randomBytes(24).toString('hex');
+  let session: TestClaimCleanupSession | undefined;
+  let sequenceStarted = false;
+  try {
+    await lock.writeFile(
+      `${JSON.stringify({ pid: process.pid, hostname: os.hostname(), startTime: String(Date.now() - process.uptime() * 1000), token })}\n`,
+    );
+    await lock.sync();
+    // Re-read after locking; the runner must have closed its single inventory broker.
+    claim = await loadTestClaim(claimPath);
+    await validateLocalRoots(claim);
+    if (claim.databases.length || claim.redis.length)
+      session = await (options.prepare ?? prepareCleanupProcess)(claim, claimPath);
+    if (!options.isInactive) return skip('process inactivity inspector unavailable');
+    const evidence = await options.isInactive(claim);
+    if (!(typeof evidence === 'boolean' ? evidence : evidence.inactive))
+      return skip('live or uncertain process ownership');
+    sequenceStarted = true;
+    claim.status = 'cleaning';
+    claim.cleanup.processes = true;
+    await writeTestClaim(claimPath, claim);
+    for (const db of claim.databases) {
+      for (const creation of db.creations) {
+        if (creation.stage === 'released') continue;
+        // SQLite files and sidecars are released with the entire marked data root,
+        // and must not be journaled as gone before that deletion completes.
+        if (db.endpoint.dialect === 'better-sqlite3') continue;
+        await session!.dropDatabase(db, creation.name);
+        creation.stage = 'released';
+        await writeTestClaim(claimPath, claim);
+      }
+    }
+    claim.cleanup.databases = claim.databases.every(database =>
+      database.creations.every(creation => creation.stage === 'released'),
+    );
+    await writeTestClaim(claimPath, claim);
+    for (const resource of claim.redis) {
+      if (resource.released) continue;
+      await session!.clearRedis(resource);
+      resource.released = true;
+      await writeTestClaim(claimPath, claim);
+    }
+    claim.cleanup.redis = true;
+    await writeTestClaim(claimPath, claim);
+    // No connections can outlive local deletion. A failed close retains the journal.
+    if (session) {
+      await session.close();
+      session = undefined;
+    }
+    for (const local of claim.locals) {
+      if (local.stage === 'released') continue;
+      assertTestClaimSafePath(local.path);
+      if (await exists(local.path)) {
+        assertTestRunOwner(local.path, claim.runId);
+        await rm(local.path, { recursive: true, force: false });
+      }
+      local.stage = 'released';
+      await writeTestClaim(claimPath, claim);
+    }
+    for (const database of claim.databases) {
+      if (database.endpoint.dialect === 'better-sqlite3') {
+        for (const creation of database.creations) creation.stage = 'released';
+      }
+    }
+    claim.cleanup.databases = true;
+    claim.cleanup.locals = true;
+    await writeTestClaim(claimPath, claim);
+    // Validate once more before releasing the inventory, always last.
+    await loadTestClaim(claimPath);
+    await unlink(claimPath);
+    return { status: 'cleaned' };
+  } catch {
+    const reason = sequenceStarted
+      ? 'cleanup failed; remaining resources journaled for retry'
+      : 'unsafe roots, configuration drift, or inspection failure';
+    warn(`Retained test claim ${path.basename(claimPath)}: ${reason}`);
+    return { status: sequenceStarted ? 'failed' : 'skipped', reason };
+  } finally {
+    if (session) await session.close().catch(() => {});
+    await lock.close();
+    // Do not remove a replacement lock. No automatic orphan-lock takeover.
+    try {
+      const handle = await open(lockPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+      try {
+        const value = JSON.parse(await handle.readFile('utf8'));
+        if (value.token === token) await unlink(lockPath);
+      } finally {
+        await handle.close();
+      }
+    } catch {
+      warn(`Retained cleanup lock ${path.basename(lockPath)}: manual inspection required`);
+    }
+  }
+}
+
+export async function reapExpiredTestClaims(
+  projectPath: string,
+  options: TestClaimReapOptions = {},
+): Promise<TestClaimCleanupResult[]> {
+  projectPath = path.resolve(projectPath);
+  const ttl = options.ttlSeconds ?? parseTestClaimTtlSeconds();
+  if (!Number.isSafeInteger(ttl) || ttl <= 0)
+    throw new Error('Test claim TTL must be a positive safe integer');
+  const now = options.now ?? Date.now();
+  if (!Number.isFinite(now)) throw new Error('Invalid test claim cleanup clock');
+  const warn = options.warn ?? (() => {});
+  const directory = path.join(projectPath, TEST_CLAIM_DIRECTORY);
+  // Legacy roots cannot prove remote ownership and are never adopted/deleted.
+  for (const item of await readdir(projectPath, { withFileTypes: true })) {
+    if (item.name.startsWith('.vona-test-claim-'))
+      warn(`Legacy inventory-less test claim retained: ${item.name}`);
+    const legacyRun = /^(?:\.vona-test-|\.app-test-)(\d{14}-[a-f0-9]{8})$/.exec(item.name);
+    if (legacyRun && !(await exists(path.join(directory, `${legacyRun[1]}.json`))))
+      warn(`Legacy inventory-less test root retained: ${item.name}`);
+  }
+  if (!(await assertSharedDirectory(directory))) return [];
+  const results: TestClaimCleanupResult[] = [];
+  for (const name of await readdir(directory)) {
+    if (name.endsWith('.cleanup.lock')) {
+      warn(`Cleanup lock retained for manual inspection: ${name}`);
+      continue;
+    }
+    if (!name.endsWith('.json')) continue;
+    const claimPath = path.join(directory, name);
+    let claim: TestClaimManifest;
+    try {
+      claim = await loadTestClaim(claimPath);
+    } catch {
+      warn(`Malformed or unsafe test claim retained: ${name}`);
+      results.push({ status: 'skipped', reason: 'malformed or unsafe manifest' });
+      continue;
+    }
+    if (claim.projectPath !== projectPath) {
+      warn(`Checkout-mismatched test claim retained: ${name}`);
+      continue;
+    }
+    if ((now - Date.parse(claim.createdAt)) / 1000 <= ttl) continue;
+    results.push(await cleanTestClaim(claimPath, { ...options, projectPath }));
+  }
+  return results;
+}
+
+export async function prepareCleanupProcess(
+  claim: TestClaimManifest,
+  claimPath: string,
+): Promise<TestClaimCleanupSession> {
+  const helper = fileURLToPath(
+    new URL(
+      '../vona/packages-cli/cli-set-api/src/lib/bean/toolsBin/testCleanupProcess.ts',
+      import.meta.url,
+    ),
+  );
+  // Config and credentials stay inside the child. Ignore stdout/stderr completely:
+  // source config and driver diagnostics must never become secret-bearing logs.
+  const child = spawn(process.execPath, [helper], {
+    cwd: claim.projectPath,
+    env: {
+      ...process.env,
+      VONA_TEST_RUN_ID: claim.runId,
+      META_MODE: 'test',
+      META_FLAVOR: 'normal',
+      APP_NAME: `cabtest${claim.runId}`,
+      SERVER_LISTEN_PORT: '1',
+    },
+    stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+  });
+  let nextId = 0;
+  let closed = false;
+  let exited = false;
+  const exitPromise = new Promise<void>(resolve => {
+    child.once('exit', () => {
+      exited = true;
+      resolve();
+    });
+    child.once('error', () => {
+      exited = true;
+      resolve();
+    });
+  });
+  const pending = new Map<
+    number,
+    { resolve: () => void; reject: (error: Error) => void; timer: ReturnType<typeof setTimeout> }
+  >();
+  const fail = () => {
+    for (const operation of pending.values()) {
+      clearTimeout(operation.timer);
+      operation.reject(new Error('Cleanup helper failed'));
+    }
+    pending.clear();
+  };
+  child.on('error', () => {
+    exited = true;
+    fail();
+  });
+  child.on('exit', fail);
+  child.on('message', (value: any) => {
+    if (!value || typeof value.id !== 'number' || typeof value.ok !== 'boolean') return;
+    const operation = pending.get(value.id);
+    if (!operation) return;
+    pending.delete(value.id);
+    clearTimeout(operation.timer);
+    if (value.ok) operation.resolve();
+    else operation.reject(new Error('Cleanup helper rejected operation'));
+  });
+  const request = (command: string, args: object = {}) =>
+    new Promise<void>((resolve, reject) => {
+      const id = ++nextId;
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error('Cleanup helper timed out'));
+        child.kill('SIGTERM');
+      }, 30000);
+      pending.set(id, { resolve, reject, timer });
+      child.send({ id, command, ...args }, error => {
+        if (error) fail();
+      });
+    });
+  const close = async () => {
+    if (closed) return;
+    closed = true;
+    try {
+      if (child.connected && !exited) await request('close');
+    } finally {
+      if (child.connected) child.disconnect();
+      if (!exited) child.kill('SIGTERM');
+      const timer = setTimeout(() => {
+        if (!exited) child.kill('SIGKILL');
+      }, 3000);
+      try {
+        await exitPromise;
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+  };
+  try {
+    await request('prepare', { claimPath });
+  } catch (error) {
+    await close().catch(() => {});
+    throw error;
+  }
+  return {
+    dropDatabase: (database, name) =>
+      request('database', { clientName: database.clientName, scope: database.scope, name }),
+    clearRedis: resource => request('redis', { clientName: resource.clientName }),
+    close,
+  };
+}

package/scripts/testClaimProcesses.test.ts

@@ -0,0 +1,106 @@
+import assert from 'node:assert/strict';
+import { hostname } from 'node:os';
+import { test } from 'node:test';
+
+import {
+  inspectTestProcess,
+  isTestClaimInactive,
+  parseTestProcesses,
+  waitForTestProcessGroupExit,
+} from './testClaimProcesses.ts';
+
+test('parses POSIX start identities and complete command arguments', () => {
+  const [process] = parseTestProcesses(
+    '  123  123 S Tue Oct 13 00:06:04 2026 /bin/node /path with spaces/test.ts\n',
+  );
+  assert.equal(process.pid, 123);
+  assert.equal(process.pgid, 123);
+  assert.equal(process.startTime, 'Tue Oct 13 00:06:04 2026');
+  assert.equal(process.args, '/bin/node /path with spaces/test.ts');
+  assert.throws(() => parseTestProcesses('unknown output'), /Cannot parse/);
+});
+
+test('inactivity fails closed for active, reused, pending and uninspectable processes', async () => {
+  const owner = { pid: 100, startTime: 'owner-start', host: hostname() };
+  const registered = {
+    id: 'browser',
+    role: 'browser',
+    stage: 'registered' as const,
+    pid: 200,
+    pgid: 200,
+    startTime: 'browser-start',
+    host: hostname(),
+    profilePath: '/owned/tmp/browser',
+  };
+  const claim = { owner, processes: [registered] };
+  const snapshot = (pid: number, pgid: number, args = 'node', startTime = 'reused-start') => ({
+    pid,
+    pgid,
+    args,
+    startTime,
+    host: hostname(),
+    state: 'S',
+  });
+  assert.equal((await isTestClaimInactive(claim, false, async () => [])).inactive, true);
+  for (const processes of [
+    [snapshot(100, 100)],
+    [snapshot(200, 300)],
+    [snapshot(201, 200)],
+    [snapshot(202, 202, 'browser --profile /owned/tmp/browser')],
+  ]) {
+    assert.equal((await isTestClaimInactive(claim, false, async () => processes)).inactive, false);
+  }
+  assert.equal(
+    (
+      await isTestClaimInactive(
+        { owner, processes: [{ id: 'pending', role: 'browser', stage: 'pending' }] },
+        false,
+        async () => [],
+      )
+    ).inactive,
+    false,
+  );
+  assert.equal(
+    (
+      await isTestClaimInactive(
+        { ...claim, owner: { ...owner, host: 'different-host' } },
+        false,
+        async () => [],
+      )
+    ).inactive,
+    false,
+  );
+  await assert.rejects(
+    isTestClaimInactive(claim, false, async () => {
+      throw new Error('inspection failed');
+    }),
+    /inspection failed/,
+  );
+  const current = { ...owner, pid: process.pid };
+  const currentSnapshot = snapshot(process.pid, process.pid, 'node', owner.startTime);
+  assert.equal(
+    (
+      await isTestClaimInactive({ owner: current, processes: [] }, true, async () => [
+        currentSnapshot,
+      ])
+    ).inactive,
+    true,
+  );
+  assert.equal(
+    (
+      await isTestClaimInactive({ owner: current, processes: [] }, false, async () => [
+        currentSnapshot,
+      ])
+    ).inactive,
+    false,
+  );
+});
+
+test('identifies the current process without publishing environment values', async () => {
+  const identity = await inspectTestProcess(process.pid);
+  assert.equal(identity.pid, process.pid);
+  assert.ok(identity.pgid > 0);
+  assert.ok(identity.startTime);
+  assert.ok(identity.host);
+  await assert.rejects(waitForTestProcessGroupExit(identity.pgid, 0), /did not drain/);
+});

package/scripts/testClaimProcesses.ts

@@ -0,0 +1,129 @@
+import { execFile } from 'node:child_process';
+import { hostname } from 'node:os';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export interface TestProcessIdentity {
+  pid: number;
+  pgid: number;
+  startTime: string;
+  host: string;
+}
+
+export interface TestProcessSnapshot extends TestProcessIdentity {
+  state: string;
+  args: string;
+}
+
+export function parseTestProcesses(output: string): TestProcessSnapshot[] {
+  const processes: TestProcessSnapshot[] = [];
+  for (const line of output.split('\n')) {
+    if (!line.trim()) continue;
+    const match =
+      /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(\S+\s+\S+\s+\d+\s+\d{2}:\d{2}:\d{2}\s+\d{4})\s+(.*)$/.exec(
+        line,
+      );
+    if (!match) throw new Error('Cannot parse isolated test process inspection');
+    processes.push({
+      pid: Number(match[1]),
+      pgid: Number(match[2]),
+      state: match[3],
+      startTime: match[4].replace(/\s+/g, ' '),
+      host: hostname(),
+      args: match[5],
+    });
+  }
+  return processes;
+}
+
+export async function inspectTestProcesses(): Promise<TestProcessSnapshot[]> {
+  if (process.platform === 'win32') {
+    throw new Error('Isolated test process inspection requires POSIX');
+  }
+  const { stdout } = await execFileAsync(
+    'ps',
+    ['-A', '-o', 'pid=', '-o', 'pgid=', '-o', 'state=', '-o', 'lstart=', '-o', 'args='],
+    { env: { ...process.env, LC_ALL: 'C' }, timeout: 5000, maxBuffer: 16 * 1024 * 1024 },
+  );
+  return parseTestProcesses(stdout);
+}
+
+export async function inspectTestProcess(pid: number): Promise<TestProcessSnapshot> {
+  const item = (await inspectTestProcesses()).find(
+    item => item.pid === pid && !item.state.startsWith('Z'),
+  );
+  if (!item) throw new Error('Cannot identify isolated test process');
+  return item;
+}
+
+export interface TestClaimProcessRecord {
+  id: string;
+  role: string;
+  stage: 'pending' | 'registered' | 'drained';
+  pid?: number;
+  pgid?: number;
+  startTime?: string;
+  host?: string;
+  profilePath?: string;
+}
+
+export async function isTestClaimInactive(
+  claim: {
+    owner: { pid: number; startTime: string; host?: string };
+    processes: TestClaimProcessRecord[];
+  },
+  allowCurrentOwner = false,
+  inspect: () => Promise<TestProcessSnapshot[]> = inspectTestProcesses,
+): Promise<{ inactive: boolean; reason?: string }> {
+  if (claim.owner.host !== hostname()) {
+    return { inactive: false, reason: 'claim belongs to another or unidentified host' };
+  }
+  const processes = (await inspect()).filter(item => !item.state.startsWith('Z'));
+  const owner = processes.find(item => item.pid === claim.owner.pid);
+  if (
+    owner &&
+    !(allowCurrentOwner && owner.pid === process.pid && owner.startTime === claim.owner.startTime)
+  ) {
+    return { inactive: false, reason: 'claim owner PID is still present' };
+  }
+  for (const registered of claim.processes) {
+    if (registered.stage === 'pending') {
+      return { inactive: false, reason: 'process launch registration is incomplete' };
+    }
+    if (
+      !registered.pid ||
+      !registered.pgid ||
+      !registered.startTime ||
+      registered.host !== hostname()
+    ) {
+      return {
+        inactive: false,
+        reason: 'process identity is incomplete or belongs to another host',
+      };
+    }
+    if (processes.some(item => item.pid === registered.pid || item.pgid === registered.pgid)) {
+      return { inactive: false, reason: 'registered process or group is still present' };
+    }
+    if (
+      registered.profilePath &&
+      processes.some(item => item.args.includes(registered.profilePath!))
+    ) {
+      return { inactive: false, reason: 'browser profile remains in use' };
+    }
+  }
+  return { inactive: true };
+}
+
+export async function waitForTestProcessGroupExit(pgid: number, timeoutMs = 10_000) {
+  if (!Number.isSafeInteger(pgid) || pgid <= 0) throw new Error('Invalid isolated process group');
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    const live = (await inspectTestProcesses()).some(
+      item => item.pgid === pgid && !item.state.startsWith('Z'),
+    );
+    if (!live) return;
+    if (Date.now() >= deadline) throw new Error('Isolated browser process group did not drain');
+    await new Promise(resolvePromise => setTimeout(resolvePromise, 100));
+  }
+}