@happier-dev/stack 0.1.0-preview.74.1

package/scripts/orchestrated_stack_auth_flow_resolve_port.test.mjs

@@ -0,0 +1,98 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { resolveServerPortForPostAuthDaemonStart } from './utils/auth/orchestrated_stack_auth_flow.mjs';
+
+test('resolveServerPortForPostAuthDaemonStart falls back to env HAPPIER_STACK_SERVER_PORT when runtime is missing it', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-auth-flow-port-'));
+  const storageDir = join(tmp, 'storage');
+  const stackName = 'main';
+  const baseDir = join(storageDir, stackName);
+  await mkdir(baseDir, { recursive: true });
+
+  await writeFile(join(baseDir, 'stack.runtime.json'), JSON.stringify({ version: 1, stackName, ports: {} }) + '\n', 'utf-8');
+
+  const prev = process.env.HAPPIER_STACK_STORAGE_DIR;
+  process.env.HAPPIER_STACK_STORAGE_DIR = storageDir;
+  try {
+    const port = await resolveServerPortForPostAuthDaemonStart({
+      stackName,
+      env: { ...process.env, HAPPIER_STACK_SERVER_PORT: '4123' },
+    });
+    assert.equal(port, 4123);
+  } finally {
+    if (typeof prev === 'undefined') delete process.env.HAPPIER_STACK_STORAGE_DIR;
+    else process.env.HAPPIER_STACK_STORAGE_DIR = prev;
+    try {
+      await rm(tmp, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  }
+});
+
+test('resolveServerPortForPostAuthDaemonStart throws when runtime and env ports are both unusable', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-auth-flow-port-invalid-'));
+  const storageDir = join(tmp, 'storage');
+  const stackName = 'main';
+  const baseDir = join(storageDir, stackName);
+  await mkdir(baseDir, { recursive: true });
+
+  await writeFile(join(baseDir, 'stack.runtime.json'), JSON.stringify({ version: 1, stackName, ports: {} }) + '\n', 'utf-8');
+
+  const prev = process.env.HAPPIER_STACK_STORAGE_DIR;
+  process.env.HAPPIER_STACK_STORAGE_DIR = storageDir;
+  try {
+    await assert.rejects(
+      () =>
+        resolveServerPortForPostAuthDaemonStart({
+          stackName,
+          env: { ...process.env, HAPPIER_STACK_SERVER_PORT: 'not-a-port' },
+        }),
+      /could not resolve server port/i
+    );
+  } finally {
+    if (typeof prev === 'undefined') delete process.env.HAPPIER_STACK_STORAGE_DIR;
+    else process.env.HAPPIER_STACK_STORAGE_DIR = prev;
+    try {
+      await rm(tmp, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  }
+});
+
+test('resolveServerPortForPostAuthDaemonStart ignores runtime port when runtime owner pid is stale', async () => {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-auth-flow-port-stale-owner-'));
+  const storageDir = join(tmp, 'storage');
+  const stackName = 'main';
+  const baseDir = join(storageDir, stackName);
+  await mkdir(baseDir, { recursive: true });
+
+  await writeFile(
+    join(baseDir, 'stack.runtime.json'),
+    JSON.stringify({ version: 1, stackName, ownerPid: 999_999_999, ports: { server: 4555 } }) + '\n',
+    'utf-8'
+  );
+
+  const prev = process.env.HAPPIER_STACK_STORAGE_DIR;
+  process.env.HAPPIER_STACK_STORAGE_DIR = storageDir;
+  try {
+    const port = await resolveServerPortForPostAuthDaemonStart({
+      stackName,
+      env: { ...process.env, HAPPIER_STACK_SERVER_PORT: '4222' },
+    });
+    assert.equal(port, 4222);
+  } finally {
+    if (typeof prev === 'undefined') delete process.env.HAPPIER_STACK_STORAGE_DIR;
+    else process.env.HAPPIER_STACK_STORAGE_DIR = prev;
+    try {
+      await rm(tmp, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  }
+});

package/scripts/orchestrated_stack_auth_flow_webapp_url.test.mjs

@@ -0,0 +1,119 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+function runNode(args, { cwd, env }) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(process.execPath, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (d) => (stdout += String(d)));
+    proc.stderr.on('data', (d) => (stderr += String(d)));
+    proc.on('error', reject);
+    proc.on('exit', (code, signal) => resolve({ code: code ?? (signal ? 1 : 0), signal, stdout, stderr }));
+  });
+}
+
+function toDataUrl(source) {
+  return `data:text/javascript,${encodeURIComponent(source)}`;
+}
+
+test('startDaemonPostAuth passes webapp URL to daemon env (never internal API URL)', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const rootDir = dirname(scriptsDir);
+
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-auth-flow-webapp-url-'));
+  try {
+    const stackName = 'main';
+    const storageDir = join(tmp, 'storage');
+    const stackDir = join(storageDir, stackName);
+    const envPath = join(stackDir, 'env');
+    const markerPath = join(tmp, 'daemon-input.json');
+
+    await mkdir(stackDir, { recursive: true });
+    await writeFile(
+      envPath,
+      ['HAPPIER_STACK_STACK=main', 'HAPPIER_WEBAPP_URL=http://localhost:3010', ''].join('\n'),
+      'utf-8'
+    );
+    await writeFile(
+      join(stackDir, 'stack.runtime.json'),
+      JSON.stringify({ version: 1, stackName, ownerPid: process.pid, ports: { server: 4102 } }, null, 2),
+      'utf-8'
+    );
+
+    const loaderPath = join(tmp, 'loader.mjs');
+    const registerPath = join(tmp, 'register-loader.mjs');
+    const runnerPath = join(tmp, 'runner.mjs');
+
+    const stubBySpecifier = {
+      '../../daemon.mjs': toDataUrl(`
+import { writeFileSync } from 'node:fs';
+export async function startLocalDaemonWithAuth(input) {
+  const marker = process.env.HSTACK_AUTH_FLOW_DAEMON_MARKER;
+  if (marker) writeFileSync(marker, JSON.stringify(input), 'utf-8');
+}
+export function checkDaemonState() {
+  return { status: 'running', pid: 12345 };
+}
+`),
+    };
+
+    await writeFile(
+      loaderPath,
+      `
+const stubBySpecifier = ${JSON.stringify(stubBySpecifier)};
+export async function resolve(specifier, context, defaultResolve) {
+  const stub = stubBySpecifier[specifier];
+  if (stub) return { url: stub, shortCircuit: true };
+  return defaultResolve(specifier, context, defaultResolve);
+}
+`,
+      'utf-8'
+    );
+    await writeFile(
+      registerPath,
+      `import { register } from 'node:module';
+register(${JSON.stringify(pathToFileURL(loaderPath).href)}, import.meta.url);
+`,
+      'utf-8'
+    );
+
+    await writeFile(
+      runnerPath,
+      `
+import { startDaemonPostAuth } from ${JSON.stringify(pathToFileURL(join(scriptsDir, 'utils', 'auth', 'orchestrated_stack_auth_flow.mjs')).href)};
+await startDaemonPostAuth({
+  rootDir: ${JSON.stringify(rootDir)},
+  stackName: 'main',
+  env: process.env,
+  forceRestart: true,
+});
+`,
+      'utf-8'
+    );
+
+    const env = {
+      ...process.env,
+      HAPPIER_STACK_STORAGE_DIR: storageDir,
+      HAPPIER_STACK_STACK: stackName,
+      HAPPIER_STACK_ENV_FILE: envPath,
+      HAPPIER_STACK_SERVER_PORT: '4102',
+      HSTACK_AUTH_FLOW_DAEMON_MARKER: markerPath,
+    };
+    const res = await runNode(['--import', registerPath, runnerPath], { cwd: rootDir, env });
+    assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+    const markerRaw = await readFile(markerPath, 'utf-8');
+    const marker = JSON.parse(markerRaw);
+    assert.equal(marker.internalServerUrl, 'http://127.0.0.1:4102');
+    assert.equal(marker.publicServerUrl, 'http://localhost:3010');
+    assert.notEqual(marker.publicServerUrl, marker.internalServerUrl);
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});

package/scripts/pack.mjs

@@ -0,0 +1,257 @@
+import './utils/env/env.mjs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { getComponentDir, getRootDir } from './utils/paths/paths.mjs';
+import { runCapture } from './utils/proc/proc.mjs';
+import { pathExists } from './utils/fs/fs.mjs';
+
+const VALID_TARGETS = ['cli', 'server', 'ui'];
+
+function targetFromLegacyComponent(component) {
+  const c = String(component ?? '').trim();
+  if (c === 'happy') return 'ui';
+  if (c === 'happy-cli') return 'cli';
+  if (c === 'happy-server' || c === 'happy-server-light') return 'server';
+  return null;
+}
+
+function legacyComponentFromTarget(target) {
+  const t = String(target ?? '').trim();
+  if (t === 'ui') return 'happy';
+  if (t === 'cli') return 'happy-cli';
+  if (t === 'server') return 'happy-server';
+  return null;
+}
+
+export async function findMonorepoRoot(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 12; i++) {
+    const pkg = join(dir, 'package.json');
+    const lock = join(dir, 'yarn.lock');
+    if ((await pathExists(pkg)) && (await pathExists(lock))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
+export async function resolvePackDirForComponent({ component, componentDir, explicitDir }) {
+  if (explicitDir) return explicitDir;
+
+  // In the monorepo, stacks often point the active repo dir at the monorepo root.
+  // For packing/publishing we want the actual workspace package dir.
+  const monorepoRoot = await findMonorepoRoot(componentDir);
+  if (monorepoRoot) {
+    try {
+      const rootPkg = await readJson(join(monorepoRoot, 'package.json'));
+      const name = String(rootPkg?.name ?? '').trim();
+      if (name === 'monorepo') {
+        if (component === 'happy-cli') return join(monorepoRoot, 'apps', 'cli');
+        if (component === 'happy-server') return join(monorepoRoot, 'apps', 'server');
+        if (component === 'happy') return join(monorepoRoot, 'apps', 'ui');
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  return componentDir;
+}
+
+async function copyDir(src, dest) {
+  // Node 22 supports recursive copy via `cp` in fs/promises, but this repo has its own fs utils;
+  // keep it simple using `cp -R` through the existing proc runner.
+  // Using external `cp` keeps this fast and avoids re-implementing copy logic.
+  await runCapture('cp', ['-R', src, dest], { cwd: '/', env: process.env });
+}
+
+async function createPackSandbox({ monorepoRoot, packageRelDir }) {
+  const sandboxRoot = await mkdtemp(join(tmpdir(), 'hstack-pack-'));
+
+  // Minimal monorepo layout needed for pack steps that reference workspace deps:
+  // - root package.json + yarn.lock (for repo root detection)
+  // - target package dir (e.g. apps/cli)
+  // - bundled deps sources (packages/*)
+  const filesToCopy = [
+    'package.json',
+    'yarn.lock',
+  ];
+  for (const f of filesToCopy) {
+    await copyDir(join(monorepoRoot, f), join(sandboxRoot, f));
+  }
+
+  const dirsToCopy = [
+    packageRelDir,
+    'packages/agents',
+    'packages/cli-common',
+    'packages/protocol',
+  ];
+  for (const d of dirsToCopy) {
+    const src = join(monorepoRoot, d);
+    if (!(await pathExists(src))) {
+      throw new Error(`[pack] missing required directory for packing sandbox: ${src}`);
+    }
+    const destParent = dirname(join(sandboxRoot, d));
+    await runCapture('mkdir', ['-p', destParent], { cwd: '/', env: process.env });
+    await copyDir(src, join(sandboxRoot, d));
+  }
+
+  return sandboxRoot;
+}
+
+export function analyzeTarList(paths) {
+  const hasAgents = paths.some((p) => p.startsWith('package/node_modules/@happier-dev/agents/'));
+  const hasCliCommon = paths.some((p) => p.startsWith('package/node_modules/@happier-dev/cli-common/'));
+  const hasProtocol = paths.some((p) => p.startsWith('package/node_modules/@happier-dev/protocol/'));
+  return { hasAgents, hasCliCommon, hasProtocol };
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags, kv } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+
+  if (wantsHelp(argv, { flags })) {
+    printResult({
+      json,
+      data: { targets: [...VALID_TARGETS, '--dir=/abs/path'], flags: ['--json'] },
+      text: [
+        '[pack] usage:',
+        '  hstack pack cli [--json]',
+        '  hstack pack server [--json]',
+        '  hstack pack ui [--json]',
+        '  hstack pack --dir=/abs/path/to/apps/cli [--json]',
+        '',
+        'notes:',
+        '- packs in a temporary sandbox to avoid dirtying the worktree',
+        '- can validate bundledDependencies output by inspecting the generated tarball (best-effort)',
+      ].join('\n'),
+    });
+    return;
+  }
+
+  const positionals = argv.filter((a) => !a.startsWith('--'));
+  const explicitDir = (kv.get('--dir') ?? '').toString().trim();
+  const raw =
+    explicitDir
+      ? null
+      : positionals.length === 1
+        ? positionals[0]
+        : null;
+
+  if (!explicitDir && !raw) {
+    throw new Error('[pack] missing target (expected: hstack pack cli|server|ui | --dir=...)');
+  }
+
+  const target = raw
+    ? (VALID_TARGETS.includes(String(raw).trim().toLowerCase()) ? String(raw).trim().toLowerCase() : targetFromLegacyComponent(raw))
+    : null;
+  if (raw && !target) {
+    throw new Error(`[pack] unknown target: ${raw} (expected one of: ${VALID_TARGETS.join(', ')})`);
+  }
+
+  const rootDir = getRootDir(import.meta.url);
+  const component = target ? legacyComponentFromTarget(target) : null;
+  const componentDir = component ? getComponentDir(rootDir, component) : '';
+  const packDir = await resolvePackDirForComponent({
+    component: component ?? 'happy-cli',
+    componentDir,
+    explicitDir: explicitDir ? resolve(explicitDir) : null,
+  });
+
+  if (!(await pathExists(packDir))) {
+    throw new Error(`[pack] missing pack dir: ${packDir}`);
+  }
+  const st = await stat(packDir);
+  if (!st.isDirectory()) {
+    throw new Error(`[pack] pack dir is not a directory: ${packDir}`);
+  }
+
+  const monorepoRoot = await findMonorepoRoot(packDir);
+  if (!monorepoRoot) {
+    throw new Error(`[pack] could not locate monorepo root (package.json + yarn.lock) from: ${packDir}`);
+  }
+  const packageRelDir = relative(monorepoRoot, packDir).split(sep).join('/');
+  if (!(packageRelDir.startsWith('apps/') || packageRelDir.startsWith('packages/'))) {
+    throw new Error(`[pack] expected pack dir to be under monorepo apps/ or packages/: ${packDir}`);
+  }
+
+  const sandboxRoot = await createPackSandbox({ monorepoRoot, packageRelDir });
+  const sandboxPackDir = join(sandboxRoot, packageRelDir);
+
+  try {
+    // 1) dry run: helps catch issues without producing a tarball
+    const dryRunOut = await runCapture('npm', ['pack', '--dry-run'], { cwd: sandboxPackDir, env: process.env });
+
+    // 2) real pack: create tarball and inspect contents
+    const tarballNameRaw = (await runCapture('npm', ['pack'], { cwd: sandboxPackDir, env: process.env })).trim();
+    const tarballName = tarballNameRaw.split('\n').filter(Boolean).slice(-1)[0] ?? '';
+    if (!tarballName) {
+      throw new Error('[pack] npm pack did not produce a tarball name');
+    }
+    const tarballPath = join(sandboxPackDir, tarballName);
+    const tarListRaw = await runCapture('tar', ['-tf', tarballPath], { cwd: sandboxPackDir, env: process.env });
+    const tarPaths = tarListRaw.split('\n').map((l) => l.trim()).filter(Boolean);
+    const { hasAgents, hasCliCommon, hasProtocol } = analyzeTarList(tarPaths);
+
+    // Only enforce bundled deps for CLI by default; other packages may intentionally not bundle.
+    const shouldEnforceBundledDeps = target === 'cli';
+    const ok = shouldEnforceBundledDeps ? hasAgents && hasCliCommon && hasProtocol : true;
+    const data = {
+      ok,
+      packDir,
+      sandboxRoot,
+      tarball: { name: basename(tarballPath) },
+      bundled: { agents: hasAgents, cliCommon: hasCliCommon, protocol: hasProtocol },
+      enforcement: { bundledDeps: shouldEnforceBundledDeps },
+      dryRun: { ok: true, output: json ? undefined : dryRunOut },
+    };
+
+    if (json) {
+      printResult({ json, data });
+      return;
+    }
+
+    const lines = [
+      `[pack] dir: ${packDir}`,
+      `[pack] tarball: ${basename(tarballPath)} (generated in a temp sandbox)`,
+      `[pack] bundledDependencies (best-effort):`,
+      `- @happier-dev/agents:   ${hasAgents ? '✅ present' : shouldEnforceBundledDeps ? '❌ missing' : '↪ not required'}`,
+      `- @happier-dev/cli-common: ${hasCliCommon ? '✅ present' : shouldEnforceBundledDeps ? '❌ missing' : '↪ not required'}`,
+      `- @happier-dev/protocol: ${hasProtocol ? '✅ present' : shouldEnforceBundledDeps ? '❌ missing' : '↪ not required'}`,
+    ];
+    if (!ok) {
+      lines.push('', '[pack] NOTE: missing bundled deps in tarball; publish would likely break for npm consumers.');
+    }
+    // eslint-disable-next-line no-console
+    console.log(lines.join('\n'));
+  } finally {
+    // Always clean the sandbox to avoid filling tmp.
+    await rm(sandboxRoot, { recursive: true, force: true });
+  }
+}
+
+const invokedAsMain = (() => {
+  const argv1 = process.argv[1];
+  if (!argv1) return false;
+  // `argv[1]` can be a relative path.
+  return resolve(argv1) === resolve(fileURLToPath(import.meta.url));
+})();
+
+if (invokedAsMain) {
+  main().catch((error) => {
+    const msg = error instanceof Error ? error.message : String(error);
+    // eslint-disable-next-line no-console
+    console.error(msg);
+    process.exit(1);
+  });
+}

package/scripts/pack.test.mjs

@@ -0,0 +1,68 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, writeFile, mkdir, rm } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { analyzeTarList, findMonorepoRoot, resolvePackDirForComponent } from './pack.mjs';
+
+test('analyzeTarList detects bundled workspace deps in tar listing', () => {
+  const { hasAgents, hasCliCommon, hasProtocol } = analyzeTarList([
+    'package/dist/index.mjs',
+    'package/node_modules/@happier-dev/agents/package.json',
+    'package/node_modules/@happier-dev/agents/dist/index.js',
+    'package/node_modules/@happier-dev/cli-common/package.json',
+    'package/node_modules/@happier-dev/protocol/package.json',
+  ]);
+  assert.equal(hasAgents, true);
+  assert.equal(hasCliCommon, true);
+  assert.equal(hasProtocol, true);
+});
+
+test('findMonorepoRoot finds nearest package.json + yarn.lock', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'pack-test-'));
+  try {
+    await writeFile(join(root, 'package.json'), JSON.stringify({ name: 'monorepo' }));
+    await writeFile(join(root, 'yarn.lock'), '# lock');
+    await mkdir(join(root, 'packages', 'happy-cli'), { recursive: true });
+
+    const nested = join(root, 'packages', 'happy-cli');
+    const found = await findMonorepoRoot(nested);
+    assert.equal(found, root);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('resolvePackDirForComponent maps monorepo root to apps/cli', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'pack-test-'));
+  try {
+    await writeFile(join(root, 'package.json'), JSON.stringify({ name: 'monorepo' }));
+    await writeFile(join(root, 'yarn.lock'), '# lock');
+    await mkdir(join(root, 'apps', 'cli'), { recursive: true });
+
+    const resolved = await resolvePackDirForComponent({
+      component: 'happy-cli',
+      componentDir: root,
+      explicitDir: null,
+    });
+    assert.equal(resolve(resolved), resolve(join(root, 'apps', 'cli')));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('resolvePackDirForComponent prefers explicitDir override', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'pack-test-explicit-'));
+  try {
+    const explicit = join(root, 'custom-pack-dir');
+    await mkdir(explicit, { recursive: true });
+    const resolved = await resolvePackDirForComponent({
+      component: 'happy-cli',
+      componentDir: root,
+      explicitDir: explicit,
+    });
+    assert.equal(resolve(resolved), resolve(explicit));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/scripts/pglite_lock.integration.test.mjs

@@ -0,0 +1,152 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { acquirePgliteDirLock } from './utils/pglite_lock.mjs';
+
+function lockPathForDbDir(dbDir) {
+  return join(dirname(dbDir), '.happier.pglite.lock');
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitForPidExit(pid, { timeoutMs = 5_000, pollMs = 25 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isPidAlive(pid)) return true;
+    // eslint-disable-next-line no-await-in-loop
+    await sleep(pollMs);
+  }
+  return !isPidAlive(pid);
+}
+
+async function terminateChildProcessAndWait(child, { timeoutMs = 5_000 } = {}) {
+  const pid = Number(child?.pid);
+  if (!Number.isFinite(pid) || pid <= 1) return;
+  if (!isPidAlive(pid)) return;
+
+  try {
+    child.kill('SIGTERM');
+  } catch {
+    // ignore
+  }
+  if (await waitForPidExit(pid, { timeoutMs: Math.floor(timeoutMs / 2), pollMs: 25 })) return;
+
+  try {
+    child.kill('SIGKILL');
+  } catch {
+    // ignore
+  }
+  const exited = await waitForPidExit(pid, { timeoutMs: Math.floor(timeoutMs / 2), pollMs: 25 });
+  assert.equal(exited, true, `expected child pid ${pid} to exit after termination`);
+}
+
+test('acquirePgliteDirLock creates and releases lock', async (t) => {
+  const base = await mkdtemp(join(tmpdir(), 'happier-pglite-lock-'));
+  t.after(async () => {
+    await rm(base, { recursive: true, force: true });
+  });
+  const dbDir = join(base, 'pglite');
+  const lockPath = lockPathForDbDir(dbDir);
+
+  const release = await acquirePgliteDirLock(dbDir, { purpose: 'test' });
+  const raw = await readFile(lockPath, 'utf-8');
+  const json = JSON.parse(raw);
+  assert.equal(json.pid, process.pid);
+  assert.equal(json.purpose, 'test');
+  assert.equal(json.psEnvLine, undefined);
+  assert.ok(typeof json.pidStartTime === 'string' && json.pidStartTime.length > 0);
+
+  await release();
+  await assert.rejects(() => readFile(lockPath, 'utf-8'), /no such file|ENOENT/i);
+});
+
+test('acquirePgliteDirLock replaces stale lock (dead pid)', async (t) => {
+  const base = await mkdtemp(join(tmpdir(), 'happier-pglite-lock-stale-'));
+  t.after(async () => {
+    await rm(base, { recursive: true, force: true });
+  });
+  const dbDir = join(base, 'pglite');
+  const lockPath = lockPathForDbDir(dbDir);
+
+  await writeFile(
+    lockPath,
+    JSON.stringify({ pid: 999999, createdAt: new Date().toISOString(), purpose: 'stale', dbDir }) + '\n',
+    'utf-8'
+  );
+
+  const release = await acquirePgliteDirLock(dbDir, { purpose: 'fresh' });
+  const raw = await readFile(lockPath, 'utf-8');
+  const json = JSON.parse(raw);
+  assert.equal(json.pid, process.pid);
+  assert.equal(json.purpose, 'fresh');
+  await release();
+});
+
+test('acquirePgliteDirLock fails closed when lock pid is alive', async (t) => {
+  const base = await mkdtemp(join(tmpdir(), 'happier-pglite-lock-live-'));
+  t.after(async () => {
+    await rm(base, { recursive: true, force: true });
+  });
+  const dbDir = join(base, 'pglite');
+  const lockPath = lockPathForDbDir(dbDir);
+
+  const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { stdio: 'ignore' });
+  assert.ok(child.pid && child.pid > 1);
+
+  try {
+    await writeFile(
+      lockPath,
+      JSON.stringify({ pid: child.pid, createdAt: new Date().toISOString(), purpose: 'live', dbDir }) + '\n',
+      'utf-8'
+    );
+
+    await assert.rejects(() => acquirePgliteDirLock(dbDir, { purpose: 'should-fail' }), /in use by pid=/i);
+  } finally {
+    await terminateChildProcessAndWait(child);
+  }
+});
+
+test('acquirePgliteDirLock replaces lock when pid is alive but the start-time fingerprint mismatches', async (t) => {
+  const base = await mkdtemp(join(tmpdir(), 'happier-pglite-lock-mismatch-'));
+  t.after(async () => {
+    await rm(base, { recursive: true, force: true });
+  });
+  const dbDir = join(base, 'pglite');
+  const lockPath = lockPathForDbDir(dbDir);
+
+  const originalCreatedAt = '2000-01-01T00:00:00.000Z';
+  await writeFile(
+    lockPath,
+    JSON.stringify({
+      pid: process.pid,
+      createdAt: originalCreatedAt,
+      purpose: 'mismatch',
+      dbDir,
+      pidStartTime: 'Mon Jan 01 00:00:00 1990',
+    }) + '\n',
+    'utf-8'
+  );
+
+  const release = await acquirePgliteDirLock(dbDir, { purpose: 'fresh' });
+  const raw = await readFile(lockPath, 'utf-8');
+  const json = JSON.parse(raw);
+  assert.equal(json.pid, process.pid);
+  assert.equal(json.purpose, 'fresh');
+  assert.notEqual(json.createdAt, originalCreatedAt);
+
+  await release();
+});