@happier-dev/stack 0.1.0-preview.5.1

package/scripts/utils/paths/paths.mjs

@@ -0,0 +1,302 @@
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve, win32 } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
+
+import { expandHome } from './canonical_home.mjs';
+
+const PRIMARY_APP_SLUG = 'happier-stack';
+const PRIMARY_LABEL_BASE = 'dev.happier.stack';
+const PRIMARY_STORAGE_ROOT = join(homedir(), '.happier', 'stacks');
+const PRIMARY_HOME_DIR = join(homedir(), '.happier-stack');
+
+// Happier monorepo layouts (historical + in-flight refactors):
+//
+// Newer (apps/):
+// - apps/ui      (Happier UI)
+// - apps/cli     (CLI + daemon)
+// - apps/server  (server)
+//
+// Legacy (packages/):
+// - packages/app    (Happier UI)
+// - packages/cli    (CLI + daemon)
+// - packages/server (server)
+const HAPPY_MONOREPO_COMPONENTS = new Set(['happier-ui', 'happier-cli', 'happier-server', 'happier-server-light']);
+
+const HAPPY_MONOREPO_LAYOUTS = {
+  apps: {
+    id: 'apps',
+    // Minimum files that identify this layout.
+    markers: [
+      ['apps', 'ui', 'package.json'],
+      ['apps', 'cli', 'package.json'],
+      ['apps', 'server', 'package.json'],
+    ],
+    subdirByComponent: {
+      'happier-ui': 'apps/ui',
+      'happier-cli': 'apps/cli',
+      'happier-server': 'apps/server',
+      // Server flavors share a single server package in the monorepo.
+      'happier-server-light': 'apps/server',
+    },
+  },
+  packages: {
+    id: 'packages',
+    markers: [
+      ['packages', 'app', 'package.json'],
+      ['packages', 'cli', 'package.json'],
+      ['packages', 'server', 'package.json'],
+    ],
+    subdirByComponent: {
+      'happier-ui': 'packages/app',
+      'happier-cli': 'packages/cli',
+      'happier-server': 'packages/server',
+      'happier-server-light': 'packages/server',
+    },
+  },
+};
+
+export function isWin32ShapedAbsolutePath(p) {
+  const s = String(p ?? '').trim();
+  if (!s) return false;
+  // IMPORTANT: `path.win32.isAbsolute('/foo') === true`, so do not use it directly here.
+  // We only want to treat *Windows-shaped* absolute paths as win32:
+  // - Drive paths: C:\... or C:/...
+  // - UNC paths: \\server\share\...
+  // - Device namespace: \\?\...
+  // - Current-drive rooted: \foo\bar
+  if (/^[a-zA-Z]:[\\/]/.test(s)) return true;
+  if (s.startsWith('\\\\?\\')) return true;
+  if (s.startsWith('\\\\')) return true;
+  if (s.startsWith('\\')) return true;
+  return false;
+}
+
+function joinPath(root, ...parts) {
+  return isWin32ShapedAbsolutePath(root) ? win32.join(root, ...parts) : join(root, ...parts);
+}
+
+function resolvePath(p) {
+  const s = String(p ?? '').trim();
+  if (!s) return '';
+  return isWin32ShapedAbsolutePath(s) ? win32.resolve(s) : resolve(s);
+}
+
+function dirnamePath(p) {
+  const s = String(p ?? '').trim();
+  if (!s) return '';
+  return isWin32ShapedAbsolutePath(s) ? win32.dirname(s) : dirname(s);
+}
+
+function detectHappyMonorepoLayout(monorepoRoot) {
+  const root = String(monorepoRoot ?? '').trim();
+  if (!root) return '';
+  try {
+    const hasAll = (markers) => markers.every((m) => existsSync(joinPath(root, ...m)));
+    if (hasAll(HAPPY_MONOREPO_LAYOUTS.apps.markers)) return HAPPY_MONOREPO_LAYOUTS.apps.id;
+    if (hasAll(HAPPY_MONOREPO_LAYOUTS.packages.markers)) return HAPPY_MONOREPO_LAYOUTS.packages.id;
+    return '';
+  } catch {
+    return '';
+  }
+}
+
+export function getRootDir(importMetaUrl) {
+  return dirname(dirname(fileURLToPath(importMetaUrl)));
+}
+
+export function getHappyStacksHomeDir(env = process.env) {
+  const fromEnv = (env.HAPPIER_STACK_HOME_DIR ?? '').trim();
+  if (fromEnv) {
+    return expandHome(fromEnv);
+  }
+  return PRIMARY_HOME_DIR;
+}
+
+export function getWorkspaceDir(cliRootDir = null, env = process.env) {
+  const fromEnv = (env.HAPPIER_STACK_WORKSPACE_DIR ?? '').trim();
+  if (fromEnv) {
+    return expandHome(fromEnv);
+  }
+  const homeDir = getHappyStacksHomeDir();
+  return join(homeDir, 'workspace');
+}
+
+export function getRepoDir(rootDir, env = process.env) {
+  const fromEnv = normalizePathForEnv(rootDir, env.HAPPIER_STACK_REPO_DIR, env);
+  const workspaceDir = getWorkspaceDir(rootDir, env);
+  const fallback = join(workspaceDir, 'main');
+
+  // Prefer explicitly configured repo dir (if set).
+  const candidate = fromEnv || fallback;
+  if (!candidate) return fallback;
+
+  // Accept any nested path inside the monorepo (e.g. apps/ui) and normalize to a package dir
+  // for monorepo-aware components below.
+  const root = coerceHappyMonorepoRootFromPath(candidate);
+  return root || candidate;
+}
+
+export function getDevRepoDir(rootDir, env = process.env) {
+  // The "dev" checkout is a first-class worktree created by `hstack setup --profile=dev`.
+  // It is not treated as the default repo dir (that is always <workspace>/main).
+  const workspaceDir = getWorkspaceDir(rootDir, env);
+  return join(workspaceDir, 'dev');
+}
+
+function normalizePathForEnv(rootDir, raw, env = process.env) {
+  const trimmed = (raw ?? '').trim();
+  if (!trimmed) {
+    return '';
+  }
+  const expanded = expandHome(trimmed);
+  // If the path is relative, treat it as relative to the workspace root (default: repo root).
+  const workspaceDir = getWorkspaceDir(rootDir, env);
+  const abs = isAbsolute(expanded) || isWin32ShapedAbsolutePath(expanded);
+  return abs ? expanded : resolve(workspaceDir, expanded);
+}
+
+export function isHappyMonorepoComponentName(name) {
+  return HAPPY_MONOREPO_COMPONENTS.has(String(name ?? '').trim());
+}
+
+export function happyMonorepoSubdirForComponent(name, { monorepoRoot = '' } = {}) {
+  const n = String(name ?? '').trim();
+  if (!n || !isHappyMonorepoComponentName(n)) return null;
+
+  const root = String(monorepoRoot ?? '').trim();
+  const layout = root ? detectHappyMonorepoLayout(root) : '';
+  if (layout === HAPPY_MONOREPO_LAYOUTS.apps.id) {
+    return HAPPY_MONOREPO_LAYOUTS.apps.subdirByComponent[n] ?? null;
+  }
+  if (layout === HAPPY_MONOREPO_LAYOUTS.packages.id) {
+    return HAPPY_MONOREPO_LAYOUTS.packages.subdirByComponent[n] ?? null;
+  }
+  // Best-effort fallback: keep a stable mapping even when layout can't be detected.
+  return HAPPY_MONOREPO_LAYOUTS.apps.subdirByComponent[n] ?? HAPPY_MONOREPO_LAYOUTS.packages.subdirByComponent[n] ?? null;
+}
+
+export function isHappyMonorepoRoot(dir) {
+  const d = String(dir ?? '').trim();
+  if (!d) return false;
+  return Boolean(detectHappyMonorepoLayout(d));
+}
+
+export function coerceHappyMonorepoRootFromPath(path) {
+  const p = String(path ?? '').trim();
+  if (!p) return null;
+  let cur = resolvePath(p);
+  while (true) {
+    if (isHappyMonorepoRoot(cur)) return cur;
+    const parent = dirnamePath(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+}
+
+function resolveHappyMonorepoPackageDir({ monorepoRoot, component }) {
+  const sub = happyMonorepoSubdirForComponent(component, { monorepoRoot });
+  if (!sub) return null;
+  return joinPath(monorepoRoot, sub);
+}
+
+export function getComponentRepoDir(rootDir, name, env = process.env) {
+  // Happier-only: all services are inside the single monorepo repo root.
+  void name;
+  return getRepoDir(rootDir, env);
+}
+
+export function getComponentDir(rootDir, name, env = process.env) {
+  const n = String(name ?? '').trim();
+
+  // Monorepo-only default:
+  // If no explicit per-component override is set, always resolve monorepo package dirs from the repo dir
+  // (default: <workspace>/main).
+  if (isHappyMonorepoComponentName(n)) {
+    const repoRoot = getRepoDir(rootDir, env);
+    const pkg = resolveHappyMonorepoPackageDir({ monorepoRoot: repoRoot, component: n });
+    if (pkg) return pkg;
+    return repoRoot;
+  }
+  // Unknown logical component: resolve to repo root.
+  return getRepoDir(rootDir, env);
+}
+
+export function getStackName(env = process.env) {
+  return env.HAPPIER_STACK_STACK?.trim() ? env.HAPPIER_STACK_STACK.trim() : 'main';
+}
+
+export function getStackLabel(stackName = null, env = process.env) {
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
+  return name === 'main' ? PRIMARY_LABEL_BASE : `${PRIMARY_LABEL_BASE}.${name}`;
+}
+
+export function getStacksStorageRoot(env = process.env) {
+  const fromEnv = (env.HAPPIER_STACK_STORAGE_DIR ?? '').trim();
+  if (fromEnv) {
+    return expandHome(fromEnv);
+  }
+  return PRIMARY_STORAGE_ROOT;
+}
+
+export function resolveStackBaseDir(stackName = null, env = process.env) {
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
+  return { baseDir: join(getStacksStorageRoot(env), name), isLegacy: false };
+}
+
+export function resolveStackEnvPath(stackName = null, env = process.env) {
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
+  const { baseDir } = resolveStackBaseDir(name, env);
+  return { envPath: join(baseDir, 'env'), isLegacy: false, baseDir };
+}
+
+export function getDefaultAutostartPaths(env = process.env) {
+  const stackName = getStackName(env);
+  const { baseDir, isLegacy } = resolveStackBaseDir(stackName, env);
+  const logsDir = join(baseDir, 'logs');
+
+  const label = getStackLabel(stackName, env);
+  const plistPath = join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
+  const stdoutPath = join(logsDir, `${PRIMARY_APP_SLUG}.out.log`);
+  const stderrPath = join(logsDir, `${PRIMARY_APP_SLUG}.err.log`);
+
+  // Linux (systemd --user) uses the same label convention as LaunchAgents.
+  const systemdUnitName = `${label}.service`;
+  const systemdUnitPath = join(homedir(), '.config', 'systemd', 'user', systemdUnitName);
+
+  return {
+    baseDir,
+    logsDir,
+    stackName,
+    isLegacy,
+
+    label,
+    plistPath,
+    systemdUnitName,
+    systemdUnitPath,
+    stdoutPath,
+    stderrPath,
+  };
+}
+
+export function getSystemdUnitInfo({ env = process.env, mode = 'user' } = {}) {
+  const m = String(mode ?? '').trim().toLowerCase() === 'system' ? 'system' : 'user';
+  const { label, systemdUnitName, systemdUnitPath } = getDefaultAutostartPaths(env);
+  void label;
+  if (m === 'system') {
+    return {
+      mode: 'system',
+      unitName: systemdUnitName,
+      unitPath: join('/etc/systemd/system', systemdUnitName),
+      systemctlArgsPrefix: [],
+      journalctlArgsPrefix: [],
+    };
+  }
+  return {
+    mode: 'user',
+    unitName: systemdUnitName,
+    unitPath: systemdUnitPath,
+    systemctlArgsPrefix: ['--user'],
+    journalctlArgsPrefix: ['--user'],
+  };
+}

package/scripts/utils/paths/paths_env_win32.test.mjs

@@ -0,0 +1,36 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { getRepoDir, isWin32ShapedAbsolutePath } from './paths.mjs';
+
+test('getRepoDir treats win32 absolute paths as absolute (does not resolve under workspace)', () => {
+  const rootDir = '/tmp/happier-stack-root';
+  const env = {
+    HAPPIER_STACK_WORKSPACE_DIR: '/tmp/happier-stack-workspace',
+    HAPPIER_STACK_REPO_DIR: 'C:\\happier\\workspace\\main',
+  };
+  assert.equal(getRepoDir(rootDir, env), 'C:\\happier\\workspace\\main');
+});
+
+test('isWin32ShapedAbsolutePath recognizes win32 absolute forms and rejects relative paths', () => {
+  assert.equal(isWin32ShapedAbsolutePath('C:\\foo\\bar'), true);
+  assert.equal(isWin32ShapedAbsolutePath('C:/foo/bar'), true);
+  assert.equal(isWin32ShapedAbsolutePath('\\\\server\\share\\path'), true);
+  assert.equal(isWin32ShapedAbsolutePath('\\\\?\\C:\\foo\\bar'), true);
+  assert.equal(isWin32ShapedAbsolutePath('\\foo\\bar'), true);
+
+  assert.equal(isWin32ShapedAbsolutePath('foo/bar'), false);
+  assert.equal(isWin32ShapedAbsolutePath('./x'), false);
+  assert.equal(isWin32ShapedAbsolutePath('~/x'), false);
+  assert.equal(isWin32ShapedAbsolutePath('/tmp/x'), false);
+  assert.equal(isWin32ShapedAbsolutePath('   '), false);
+});
+
+test('getRepoDir treats current-drive rooted win32 paths as absolute', () => {
+  const rootDir = '/tmp/happier-stack-root';
+  const env = {
+    HAPPIER_STACK_WORKSPACE_DIR: '/tmp/happier-stack-workspace',
+    HAPPIER_STACK_REPO_DIR: '\\happier\\workspace\\main',
+  };
+  assert.equal(getRepoDir(rootDir, env), '\\happier\\workspace\\main');
+});

package/scripts/utils/paths/paths_monorepo.test.mjs

@@ -0,0 +1,58 @@
+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 { getComponentDir, getComponentRepoDir } from './paths.mjs';
+
+async function withTempRoot(t) {
+  const dir = await mkdtemp(join(tmpdir(), 'happier-stacks-paths-monorepo-'));
+  t.after(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+  return dir;
+}
+
+async function writeHappyMonorepoStub({ rootDir }) {
+  const monoRoot = join(rootDir, 'main');
+  await mkdir(join(monoRoot, 'apps', 'ui'), { recursive: true });
+  await mkdir(join(monoRoot, 'apps', 'cli'), { recursive: true });
+  await mkdir(join(monoRoot, 'apps', 'server'), { recursive: true });
+  await writeFile(join(monoRoot, 'apps', 'ui', 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(monoRoot, 'apps', 'cli', 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(monoRoot, 'apps', 'server', 'package.json'), '{}\n', 'utf-8');
+  return monoRoot;
+}
+
+test('getComponentDir derives monorepo component package dirs from workspace/main', async (t) => {
+  const rootDir = await withTempRoot(t);
+  const env = { HAPPIER_STACK_WORKSPACE_DIR: rootDir };
+
+  const monoRoot = await writeHappyMonorepoStub({ rootDir });
+  assert.equal(getComponentDir(rootDir, 'happier-ui', env), join(monoRoot, 'apps', 'ui'));
+  assert.equal(getComponentDir(rootDir, 'happier-cli', env), join(monoRoot, 'apps', 'cli'));
+  assert.equal(getComponentDir(rootDir, 'happier-server', env), join(monoRoot, 'apps', 'server'));
+  assert.equal(getComponentDir(rootDir, 'happier-server-light', env), join(monoRoot, 'apps', 'server'));
+});
+
+test('getComponentRepoDir returns the shared monorepo root for monorepo components', async (t) => {
+  const rootDir = await withTempRoot(t);
+  const env = { HAPPIER_STACK_WORKSPACE_DIR: rootDir };
+
+  const monoRoot = await writeHappyMonorepoStub({ rootDir });
+  assert.equal(getComponentRepoDir(rootDir, 'happier-ui', env), monoRoot);
+  assert.equal(getComponentRepoDir(rootDir, 'happier-cli', env), monoRoot);
+  assert.equal(getComponentRepoDir(rootDir, 'happier-server', env), monoRoot);
+  assert.equal(getComponentRepoDir(rootDir, 'happier-server-light', env), monoRoot);
+});
+
+test('getComponentDir normalizes HAPPIER_STACK_REPO_DIR that points inside the monorepo', async (t) => {
+  const rootDir = await withTempRoot(t);
+  const env = { HAPPIER_STACK_WORKSPACE_DIR: rootDir };
+
+  const monoRoot = await writeHappyMonorepoStub({ rootDir });
+
+  env.HAPPIER_STACK_REPO_DIR = join(monoRoot, 'apps', 'cli', 'src');
+  assert.equal(getComponentDir(rootDir, 'happier-cli', env), join(monoRoot, 'apps', 'cli'));
+});

package/scripts/utils/paths/paths_server_flavors.test.mjs

@@ -0,0 +1,50 @@
+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 { getComponentDir } from './paths.mjs';
+
+async function withTempRoot(t) {
+  const rootDir = await mkdtemp(join(tmpdir(), 'happier-stack-paths-server-flavors-'));
+  t.after(async () => {
+    await rm(rootDir, { recursive: true, force: true });
+  });
+  return rootDir;
+}
+
+async function createMonorepoServerFixture({ rootDir, includeSqliteSchema }) {
+  const repoRoot = join(rootDir, 'main');
+  const serverDir = join(repoRoot, 'apps', 'server');
+  await mkdir(serverDir, { recursive: true });
+
+  // Monorepo markers (layout detection).
+  await mkdir(join(repoRoot, 'apps', 'ui'), { recursive: true });
+  await mkdir(join(repoRoot, 'apps', 'cli'), { recursive: true });
+  await writeFile(join(repoRoot, 'apps', 'ui', 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(repoRoot, 'apps', 'cli', 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(repoRoot, 'apps', 'server', 'package.json'), '{}\n', 'utf-8');
+
+  if (includeSqliteSchema) {
+    await mkdir(join(serverDir, 'prisma', 'sqlite'), { recursive: true });
+    await writeFile(join(serverDir, 'prisma', 'sqlite', 'schema.prisma'), 'datasource db { provider = "sqlite" }\n', 'utf-8');
+  }
+
+  return { repoRoot, serverDir };
+}
+
+test('getComponentDir prefers happier-server for happier-server-light when unified schema exists', async (t) => {
+  const rootDir = await withTempRoot(t);
+  const env = { HAPPIER_STACK_WORKSPACE_DIR: rootDir };
+  const { serverDir } = await createMonorepoServerFixture({ rootDir, includeSqliteSchema: true });
+
+  assert.equal(getComponentDir(rootDir, 'happier-server-light', env), serverDir);
+});
+
+test('getComponentDir resolves happier-server-light to the monorepo server package dir', async (t) => {
+  const rootDir = await withTempRoot(t);
+  const env = { HAPPIER_STACK_WORKSPACE_DIR: rootDir };
+  const { serverDir } = await createMonorepoServerFixture({ rootDir, includeSqliteSchema: false });
+  assert.equal(getComponentDir(rootDir, 'happier-server-light', env), serverDir);
+});

package/scripts/utils/paths/runtime.mjs

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { expandHome } from './canonical_home.mjs';
+
+function resolveInvokerPackageName(cliRootDir) {
+  try {
+    const raw = readFileSync(join(cliRootDir, 'package.json'), 'utf-8');
+    const pkg = JSON.parse(raw);
+    const name = String(pkg?.name ?? '').trim();
+    return name || null;
+  } catch {
+    return null;
+  }
+}
+
+export function getRuntimeDir() {
+  const fromEnv = (process.env.HAPPIER_STACK_RUNTIME_DIR ?? '').trim();
+  if (fromEnv) {
+    return expandHome(fromEnv);
+  }
+  const homeDir = (process.env.HAPPIER_STACK_HOME_DIR ?? '').trim()
+    ? expandHome(process.env.HAPPIER_STACK_HOME_DIR.trim())
+    : join(homedir(), '.happier-stack');
+  return join(homeDir, 'runtime');
+}
+
+export function resolveInstalledCliRoot(cliRootDir) {
+  const runtimeDir = getRuntimeDir();
+  const pkgName = resolveInvokerPackageName(cliRootDir);
+  const runtimePkgRoot = pkgName ? join(runtimeDir, 'node_modules', ...pkgName.split('/')) : null;
+  if (runtimePkgRoot && existsSync(runtimePkgRoot)) {
+    return runtimePkgRoot;
+  }
+  return cliRootDir;
+}
+
+export function resolveInstalledPath(cliRootDir, relativePath) {
+  return join(resolveInstalledCliRoot(cliRootDir), relativePath);
+}

package/scripts/utils/pglite_lock.mjs

@@ -0,0 +1,107 @@
+import { existsSync } from 'node:fs';
+import { open, readFile, unlink } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { isPidAlive } from './proc/pids.mjs';
+import { getPidStartTime } from './proc/ownership.mjs';
+
+function lockPathForDbDir(dbDir) {
+  return join(dirname(dbDir), '.happier.pglite.lock');
+}
+
+function safeParseJson(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function readLock(lockPath) {
+  try {
+    if (!existsSync(lockPath)) return null;
+    const raw = await readFile(lockPath, 'utf-8');
+    const parsed = safeParseJson(raw);
+    if (!parsed || typeof parsed !== 'object') return { invalid: true };
+    return parsed;
+  } catch {
+    return { invalid: true };
+  }
+}
+
+async function removeLock(lockPath) {
+  try {
+    await unlink(lockPath);
+  } catch {
+    // ignore
+  }
+}
+
+export async function acquirePgliteDirLock(dbDir, { purpose = 'unknown' } = {}) {
+  const resolvedDbDir = resolve(String(dbDir ?? ''));
+  if (!resolvedDbDir) throw new Error('Missing dbDir');
+  const lockPath = lockPathForDbDir(resolvedDbDir);
+
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      const handle = await open(lockPath, 'wx', 0o600);
+      try {
+        const payload = {
+          pid: process.pid,
+          createdAt: new Date().toISOString(),
+          purpose,
+          dbDir: resolvedDbDir,
+          pidStartTime: await getPidStartTime(process.pid),
+        };
+        await handle.writeFile(JSON.stringify(payload, null, 2) + '\n', 'utf-8');
+      } finally {
+        await handle.close();
+      }
+
+      return async function release() {
+        const existing = await readLock(lockPath);
+        const pid = Number(existing?.pid);
+        if (Number.isFinite(pid) && pid === process.pid) {
+          await removeLock(lockPath);
+        }
+      };
+    } catch (e) {
+      if (!e || typeof e !== 'object' || !('code' in e) || e.code !== 'EEXIST') {
+        throw e;
+      }
+
+      const existing = await readLock(lockPath);
+      const existingPid = Number(existing?.pid);
+      const existingDbDir = existing?.dbDir ? resolve(String(existing.dbDir)) : '';
+      const looksInvalid = Boolean(existing?.invalid);
+      const pidAlive = Number.isFinite(existingPid) && isPidAlive(existingPid);
+      const stale = await (async () => {
+        if (looksInvalid) return true;
+        if (!pidAlive) return true;
+        const expectedStartTime = typeof existing?.pidStartTime === 'string' ? existing.pidStartTime.trim() : '';
+        if (!expectedStartTime) return false;
+        const currentStartTime = await getPidStartTime(existingPid);
+        // Fail-open for fingerprint lookup errors: do not break lock acquisition.
+        if (!currentStartTime) return false;
+        return currentStartTime.trim() !== expectedStartTime;
+      })();
+
+      if (stale) {
+        await removeLock(lockPath);
+        continue;
+      }
+
+      // Fail closed: if another live process owns the lock, refuse to proceed.
+      // Even if dbDir mismatches, this lock still indicates the parent dir is in use.
+      const meta = [
+        existing?.purpose ? `purpose=${existing.purpose}` : '',
+        existing?.createdAt ? `createdAt=${existing.createdAt}` : '',
+        existingDbDir ? `dbDir=${existingDbDir}` : '',
+      ]
+        .filter(Boolean)
+        .join(' ');
+      throw new Error(`pglite db dir is in use by pid=${existingPid}${meta ? ` (${meta})` : ''}`);
+    }
+  }
+
+  throw new Error('Failed to acquire pglite lock after retries');
+}

package/scripts/utils/proc/commands.mjs

@@ -0,0 +1,33 @@
+import { runCapture } from './proc.mjs';
+
+export async function resolveCommandPath(cmd, { cwd, env, timeoutMs } = {}) {
+  const c = String(cmd ?? '').trim();
+  if (!c) return '';
+
+  try {
+    if (process.platform === 'win32') {
+      const out = (await runCapture('where', [c], { cwd, env, timeoutMs })).trim();
+      const first = out.split(/\r?\n/).map((s) => s.trim()).find(Boolean) || '';
+      return first;
+    }
+    return (
+      await runCapture('sh', ['-lc', `command -v "${c}" 2>/dev/null || true`], { cwd, env, timeoutMs })
+    ).trim();
+  } catch {
+    return '';
+  }
+}
+
+export async function runCaptureIfCommandExists(cmd, args, { cwd, env, timeoutMs } = {}) {
+  const resolved = await resolveCommandPath(cmd, { cwd, env, timeoutMs });
+  if (!resolved) return '';
+  try {
+    return await runCapture(resolved, args, { cwd, env, timeoutMs });
+  } catch {
+    return '';
+  }
+}
+
+export async function commandExists(cmd, { cwd, env, timeoutMs } = {}) {
+  return Boolean(await resolveCommandPath(cmd, { cwd, env, timeoutMs }));
+}

package/scripts/utils/proc/exit_cleanup.mjs

@@ -0,0 +1,57 @@
+import { killProcessTree } from './proc.mjs';
+
+function normalizeChildren(children) {
+  if (!Array.isArray(children)) return [];
+  return children.filter((c) => c && typeof c === 'object' && 'pid' in c && Number(c.pid) > 1);
+}
+
+export function installExitCleanup({ label = 'local', children } = {}) {
+  const childrenRef = children;
+  let cleaned = false;
+
+  const cleanupSync = () => {
+    if (cleaned) return;
+    cleaned = true;
+    const tracked = normalizeChildren(childrenRef);
+    for (const child of tracked) {
+      try {
+        killProcessTree(child, 'SIGTERM');
+      } catch {
+        // Best-effort cleanup; keep going.
+      }
+    }
+    // SIGKILL follows immediately as best-effort escalation.
+    // For graceful shutdown (with time for handlers to run), callers should invoke cleanup manually.
+    for (const child of tracked) {
+      try {
+        killProcessTree(child, 'SIGKILL');
+      } catch {
+        // Best-effort cleanup; keep going.
+      }
+    }
+  };
+
+  const fatalSync = (err) => {
+    try {
+      const msg = err instanceof Error ? err.stack || err.message : String(err);
+      // eslint-disable-next-line no-console
+      console.error(`[${label}] fatal: ${msg}`);
+    } catch {
+      // ignore
+    }
+    cleanupSync();
+    try {
+      process.exitCode = 1;
+      // Ensure we actually terminate; some Node configs do not exit on unhandled rejections.
+      process.exit(1);
+    } catch {
+      // ignore
+    }
+  };
+
+  process.once('exit', cleanupSync);
+  process.once('uncaughtException', fatalSync);
+  process.once('unhandledRejection', fatalSync);
+
+  return cleanupSync;
+}