@happier-dev/stack 0.1.0-preview.5.1

package/scripts/utils/stack/runtime_state.mjs

@@ -0,0 +1,88 @@
+import { existsSync } from 'node:fs';
+import { unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { resolveStackEnvPath } from '../paths/paths.mjs';
+import { readJsonIfExists, writeJsonAtomic } from '../fs/json.mjs';
+import { isPidAlive } from '../proc/pids.mjs';
+
+export { isPidAlive };
+
+export function getStackRuntimeStatePath(stackName) {
+  const { baseDir } = resolveStackEnvPath(stackName);
+  return join(baseDir, 'stack.runtime.json');
+}
+
+export async function readStackRuntimeStateFile(statePath) {
+  const parsed = await readJsonIfExists(statePath, { defaultValue: null });
+  return parsed && typeof parsed === 'object' ? parsed : null;
+}
+
+export async function writeStackRuntimeStateFile(statePath, state) {
+  if (!statePath) {
+    throw new Error('[stack] missing runtime state path');
+  }
+  await writeJsonAtomic(statePath, state);
+}
+
+function isPlainObject(v) {
+  return Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+}
+
+function deepMerge(a, b) {
+  if (!isPlainObject(a) || !isPlainObject(b)) {
+    return b;
+  }
+  const out = { ...a };
+  for (const [k, v] of Object.entries(b)) {
+    if (isPlainObject(out[k]) && isPlainObject(v)) {
+      out[k] = deepMerge(out[k], v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+export async function updateStackRuntimeStateFile(statePath, patch) {
+  const existing = (await readStackRuntimeStateFile(statePath)) ?? {};
+  const next = deepMerge(existing, patch ?? {});
+  await writeStackRuntimeStateFile(statePath, next);
+  return next;
+}
+
+export async function recordStackRuntimeStart(statePath, { stackName, script, ephemeral, ownerPid, ports, ...rest } = {}) {
+  const now = new Date().toISOString();
+  const existing = (await readStackRuntimeStateFile(statePath)) ?? {};
+  const startedAt = typeof existing.startedAt === 'string' && existing.startedAt.trim() ? existing.startedAt : now;
+  const next = deepMerge(existing, {
+    version: 1,
+    stackName,
+    script,
+    ephemeral: Boolean(ephemeral),
+    ownerPid,
+    ports: ports ?? {},
+    startedAt,
+    updatedAt: now,
+    ...(rest ?? {}),
+  });
+  await writeStackRuntimeStateFile(statePath, next);
+  return next;
+}
+
+export async function recordStackRuntimeUpdate(statePath, patch = {}) {
+  return await updateStackRuntimeStateFile(statePath, {
+    ...(patch ?? {}),
+    updatedAt: new Date().toISOString(),
+  });
+}
+
+export async function deleteStackRuntimeStateFile(statePath) {
+  try {
+    if (!statePath || !existsSync(statePath)) return;
+    await unlink(statePath);
+  } catch {
+    // ignore
+  }
+}
+

package/scripts/utils/stack/stacks.mjs

@@ -0,0 +1,40 @@
+import { readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { getStacksStorageRoot } from '../paths/paths.mjs';
+import { resolveStackEnvPath } from '../paths/paths.mjs';
+
+export async function listAllStackNames() {
+  const names = new Set(['main']);
+  const roots = [
+    getStacksStorageRoot(),
+  ];
+
+  for (const root of roots) {
+    let entries = [];
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      entries = await readdir(root, { withFileTypes: true });
+    } catch {
+      entries = [];
+    }
+    for (const ent of entries) {
+      if (!ent.isDirectory()) continue;
+      const name = ent.name;
+      if (!name || name.startsWith('.')) continue;
+      const envPath = join(root, name, 'env');
+      if (existsSync(envPath)) {
+        names.add(name);
+      }
+    }
+  }
+
+  return Array.from(names).sort();
+}
+
+export function stackExistsSync(stackName) {
+  const name = String(stackName ?? '').trim() || 'main';
+  if (name === 'main') return true;
+  return existsSync(resolveStackEnvPath(name).envPath);
+}

package/scripts/utils/stack/startup.mjs

@@ -0,0 +1,370 @@
+import { run, runCapture } from '../proc/proc.mjs';
+import { ensureDepsInstalled, pmExecBin } from '../proc/pm.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from '../env/sandbox.mjs';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import { resolvePrismaClientImportForDbProvider, resolvePrismaClientImportForServerComponent } from '../server/flavor_scripts.mjs';
+import { findAnyCredentialPathInCliHome } from '../auth/credentials_paths.mjs';
+
+function looksLikeMissingTableError(msg) {
+  const s = String(msg ?? '').toLowerCase();
+  return s.includes('does not exist') || s.includes('no such table');
+}
+
+function firstNonEmptyEnv(...values) {
+  for (const value of values) {
+    const normalized = String(value ?? '').trim();
+    if (normalized) return normalized;
+  }
+  return '';
+}
+
+function resolveLightDbProviderFromEnv(env) {
+  const raw = (env?.HAPPIER_DB_PROVIDER ?? env?.HAPPY_DB_PROVIDER ?? '').toString().trim().toLowerCase();
+  if (raw === 'pglite') return 'pglite';
+  return 'sqlite';
+}
+
+async function probeAccountCount({ serverComponentName, serverDir, env, lightDbProvider = 'sqlite' }) {
+  const probe =
+    serverComponentName === 'happier-server-light' && lightDbProvider === 'pglite'
+      ? `
+		let db;
+	  let pglite;
+	  let server;
+		try {
+	    const { PGlite } = await import('@electric-sql/pglite');
+	    const { PGLiteSocketServer } = await import('@electric-sql/pglite-socket');
+	    const { PrismaClient } = await import('@prisma/client');
+	    const dbDirPrimary = (process.env.HAPPIER_SERVER_LIGHT_DB_DIR ?? '').toString().trim();
+	    const dbDirLegacy = (process.env.HAPPY_SERVER_LIGHT_DB_DIR ?? '').toString().trim();
+	    const dbDir = dbDirPrimary || dbDirLegacy;
+	    if (!dbDir) throw new Error('Missing HAPPIER_SERVER_LIGHT_DB_DIR or HAPPY_SERVER_LIGHT_DB_DIR for pglite probe');
+	    pglite = new PGlite(dbDir);
+	    await pglite.waitReady;
+	    server = new PGLiteSocketServer({ db: pglite, host: '127.0.0.1', port: 0 });
+	    await server.start();
+	    const raw = server.getServerConn();
+	    const url = (() => {
+	      try {
+	        return new URL(raw);
+	      } catch {
+	        return new URL(\`postgresql://postgres@\${raw}/postgres?sslmode=disable\`);
+	      }
+	    })();
+	    url.searchParams.set('connection_limit', '1');
+	    process.env.DATABASE_URL = url.toString();
+		  db = new PrismaClient();
+		  const accountCount = await db.account.count();
+		  console.log(JSON.stringify({ accountCount }));
+		} catch (e) {
+		  console.log(
+		    JSON.stringify({
+		      error: {
+		        name: e?.name,
+		        message: e?.message,
+		        code: e?.code,
+		      },
+		    })
+		  );
+		} finally {
+		  try {
+		    await db?.$disconnect();
+		  } catch {
+		    // ignore
+		  }
+	    try {
+	      await server?.stop();
+	    } catch {}
+	    try {
+	      await pglite?.close();
+	    } catch {}
+		}
+		`.trim()
+      : serverComponentName === 'happier-server-light'
+      ? `
+	 	let db;
+		try {
+		  const { PrismaClient } = await import(${JSON.stringify(
+        resolvePrismaClientImportForDbProvider({ serverDir, provider: 'sqlite' })
+      )});
+      const dataDirPrimary = (process.env.HAPPIER_SERVER_LIGHT_DATA_DIR ?? '').toString().trim();
+      const dataDirLegacy = (process.env.HAPPY_SERVER_LIGHT_DATA_DIR ?? '').toString().trim();
+      const dataDir = dataDirPrimary || dataDirLegacy;
+      const fromEnv = (process.env.DATABASE_URL ?? '').toString().trim();
+      const url = fromEnv || (dataDir ? \`file:\${dataDir}/happier-server-light.sqlite\` : '');
+      if (!url) throw new Error('Missing DATABASE_URL and HAPPIER_SERVER_LIGHT_DATA_DIR or HAPPY_SERVER_LIGHT_DATA_DIR for sqlite probe');
+      process.env.DATABASE_URL = url;
+		  db = new PrismaClient();
+		  const accountCount = await db.account.count();
+		  console.log(JSON.stringify({ accountCount }));
+		} catch (e) {
+		  console.log(
+		    JSON.stringify({
+		      error: {
+		        name: e?.name,
+		        message: e?.message,
+		        code: e?.code,
+		      },
+		    })
+		  );
+		} finally {
+		  try {
+		    await db?.$disconnect();
+		  } catch {
+		    // ignore
+		  }
+		}
+		`.trim()
+      : `
+	 	let db;
+		try {
+		  const { PrismaClient } = await import(${JSON.stringify(
+	      resolvePrismaClientImportForServerComponent({ serverComponentName, serverDir })
+	    )});
+		  db = new PrismaClient();
+		  const accountCount = await db.account.count();
+		  console.log(JSON.stringify({ accountCount }));
+		} catch (e) {
+		  console.log(
+		    JSON.stringify({
+		      error: {
+		        name: e?.name,
+		        message: e?.message,
+		        code: e?.code,
+		      },
+		    })
+		  );
+		} finally {
+		  try {
+		    await db?.$disconnect();
+		  } catch {
+		    // ignore
+		  }
+		}
+		`.trim();
+
+  const out = await runCapture(process.execPath, ['--input-type=module', '-e', probe], { cwd: serverDir, env, timeoutMs: 15_000 });
+  const parsed = out.trim() ? JSON.parse(out.trim()) : {};
+  if (parsed?.error) {
+    const e = new Error(parsed.error.message || 'unknown prisma probe error');
+    if (typeof parsed.error.name === 'string' && parsed.error.name) e.name = parsed.error.name;
+    if (typeof parsed.error.code === 'string' && parsed.error.code) e.code = parsed.error.code;
+    throw e;
+  }
+  return Number(parsed.accountCount ?? 0);
+}
+
+export function resolveAutoCopyFromMainEnabled({ env, stackName, isInteractive }) {
+  // Sandboxes should be isolated by default.
+  // Auto auth seeding can copy credentials/account rows from another stack (global state),
+  // which breaks isolation and can confuse guided auth flows (setup-pr/review-pr).
+  if (isSandboxed() && !sandboxAllowsGlobalSideEffects()) {
+    return false;
+  }
+  const raw = (env.HAPPIER_STACK_AUTO_AUTH_SEED ?? '').toString().trim();
+  if (raw) return raw !== '0';
+
+  if (stackName === 'main') return false;
+
+  // Default:
+  // - always auto-seed in non-interactive contexts (agents/services)
+  // - in interactive shells, auto-seed only when the user explicitly configured a non-main seed stack
+  //   (this avoids silently spreading main identity for users who haven't opted in yet).
+  if (!isInteractive) return true;
+  const seed = (env.HAPPIER_STACK_AUTH_SEED_FROM ?? '').toString().trim();
+  return Boolean(seed && seed !== 'main');
+}
+
+export function resolveAuthSeedFromEnv(env) {
+  const seed = (env.HAPPIER_STACK_AUTH_SEED_FROM ?? '').toString().trim();
+  return seed || 'main';
+}
+
+export async function ensureServerLightSchemaReady({ serverDir, env, bestEffort = false }) {
+  await ensureDepsInstalled(serverDir, 'happier-server-light', { env });
+
+  const lightDbProvider = resolveLightDbProviderFromEnv(env);
+  const dataDir = firstNonEmptyEnv(env?.HAPPIER_SERVER_LIGHT_DATA_DIR, env?.HAPPY_SERVER_LIGHT_DATA_DIR);
+  const filesDir = firstNonEmptyEnv(env?.HAPPIER_SERVER_LIGHT_FILES_DIR, dataDir ? join(dataDir, 'files') : '');
+  const dbDir = firstNonEmptyEnv(env?.HAPPIER_SERVER_LIGHT_DB_DIR, env?.HAPPY_SERVER_LIGHT_DB_DIR, dataDir ? join(dataDir, 'pglite') : '');
+  if (dataDir) {
+    try {
+      await mkdir(dataDir, { recursive: true });
+    } catch {
+      // best-effort
+    }
+  }
+  if (filesDir) {
+    try {
+      await mkdir(filesDir, { recursive: true });
+    } catch {
+      // best-effort
+    }
+  }
+  if (dbDir) {
+    try {
+      await mkdir(dbDir, { recursive: true });
+      env.HAPPIER_SERVER_LIGHT_DB_DIR = env.HAPPIER_SERVER_LIGHT_DB_DIR ?? dbDir;
+      env.HAPPY_SERVER_LIGHT_DB_DIR = env.HAPPY_SERVER_LIGHT_DB_DIR ?? dbDir;
+    } catch {
+      // best-effort
+    }
+  }
+
+  if (
+    lightDbProvider === 'sqlite' &&
+    dataDir &&
+    !(env?.DATABASE_URL ?? '').toString().trim()
+  ) {
+    env.DATABASE_URL = `file:${join(dataDir, 'happier-server-light.sqlite')}`;
+  }
+
+  const probe = async () =>
+    await probeAccountCount({ serverComponentName: 'happier-server-light', serverDir, env, lightDbProvider });
+  // Apply provider-specific light migrations:
+  // - sqlite: prisma/sqlite/schema.prisma
+  // - pglite: embedded Postgres + pglite socket
+  //
+  // IMPORTANT:
+  // If the server is already running with pglite, it may hold the DB open (single-connection).
+  // When bestEffort=true (used for heuristics), skip migrations and only probe.
+  const migrateScript = lightDbProvider === 'pglite' ? 'migrate:light:deploy' : 'migrate:sqlite:deploy';
+  if (!bestEffort) {
+    await run('yarn', ['-s', migrateScript], { cwd: serverDir, env });
+  }
+
+  // 2) Probe account count (used for auth seeding heuristics).
+  try {
+    const accountCount = await probe();
+    return { ok: true, migrated: true, accountCount };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (looksLikeMissingTableError(msg)) {
+      if (bestEffort) {
+        return { ok: false, migrated: true, accountCount: null, error: 'server-light schema not ready (missing tables)' };
+      }
+      throw new Error(`[server-light] schema not ready after ${migrateScript} (missing tables).`);
+    }
+    if (bestEffort) {
+      return { ok: false, migrated: true, accountCount: null, error: msg };
+    }
+    throw e;
+  }
+}
+
+export async function ensureHappyServerSchemaReady({ serverDir, env }) {
+  await ensureDepsInstalled(serverDir, 'happier-server', { env });
+
+  try {
+    const accountCount = await probeAccountCount({ serverComponentName: 'happier-server', serverDir, env });
+    return { ok: true, migrated: false, accountCount };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (!looksLikeMissingTableError(msg)) {
+      throw e;
+    }
+    // If tables are missing, try migrations (safe for postgres). Then re-probe.
+    await pmExecBin({ dir: serverDir, bin: 'prisma', args: ['migrate', 'deploy'], env });
+    const accountCount = await probeAccountCount({ serverComponentName: 'happier-server', serverDir, env });
+    return { ok: true, migrated: true, accountCount };
+  }
+}
+
+export async function getAccountCountForServerComponent({ serverComponentName, serverDir, env, bestEffort = false }) {
+  if (serverComponentName === 'happier-server-light') {
+    try {
+      const ready = await ensureServerLightSchemaReady({ serverDir, env, bestEffort });
+      if (!ready?.ok) {
+        return { ok: false, accountCount: null, error: String(ready?.error ?? 'server-light schema probe failed') };
+      }
+      return { ok: true, accountCount: Number.isFinite(ready.accountCount) ? ready.accountCount : 0 };
+    } catch (e) {
+      if (!bestEffort) throw e;
+      return { ok: false, accountCount: null, error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+  if (serverComponentName === 'happier-server') {
+    try {
+      const ready = await ensureHappyServerSchemaReady({ serverDir, env });
+      return { ok: true, accountCount: Number.isFinite(ready.accountCount) ? ready.accountCount : 0 };
+    } catch (e) {
+      if (!bestEffort) throw e;
+      return { ok: false, accountCount: null, error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+  return { ok: false, accountCount: null, error: `unknown server component: ${serverComponentName}` };
+}
+
+export async function maybeAutoCopyAuthFromMainIfNeeded({
+  rootDir,
+  env,
+  enabled,
+  stackName,
+  cliHomeDir,
+  accountCount,
+  quiet = false,
+  authEnv = null,
+}) {
+  const hasAccessKey = Boolean(findAnyCredentialPathInCliHome({ cliHomeDir }));
+
+  // "Initialized" heuristic:
+  // - if we have credentials AND (when known) at least one Account row, we don't need to seed from main.
+  const hasAccounts = typeof accountCount === 'number' ? accountCount > 0 : null;
+  const needsSeed = !hasAccessKey || hasAccounts === false;
+
+  if (!enabled || !needsSeed) {
+    return { ok: true, skipped: true, reason: !enabled ? 'disabled' : 'already_initialized' };
+  }
+
+  const reason = !hasAccessKey ? 'missing_credentials' : 'no_accounts';
+  const fromStackName = resolveAuthSeedFromEnv(env);
+  const linkAuth =
+    (env.HAPPIER_STACK_AUTH_LINK ?? '').toString().trim() === '1' ||
+    (env.HAPPIER_STACK_AUTH_MODE ?? '').toString().trim() === 'link';
+  if (!quiet) {
+    console.log(`[local] auth: auto seed from ${fromStackName} for ${stackName} (${reason})`);
+  }
+
+  // Best-effort: copy credentials/master secret + seed accounts from the configured seed stack.
+  // Keep this non-fatal; the daemon will emit actionable errors if it still can't authenticate.
+  try {
+    const out = await runCapture(
+      process.execPath,
+      [`${rootDir}/scripts/auth.mjs`, 'copy-from', fromStackName, '--json', ...(linkAuth ? ['--link'] : [])],
+      {
+      cwd: rootDir,
+      env: authEnv && typeof authEnv === 'object' ? authEnv : env,
+      }
+    );
+    return { ok: true, skipped: false, reason, out: out.trim() ? JSON.parse(out) : null };
+  } catch (e) {
+    return { ok: false, skipped: false, reason, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+export async function prepareDaemonAuthSeedIfNeeded({
+  rootDir,
+  env,
+  stackName,
+  cliHomeDir,
+  startDaemon,
+  isInteractive,
+  accountCount,
+  quiet = false,
+  authEnv = null,
+}) {
+  if (!startDaemon) return { ok: true, skipped: true, reason: 'no_daemon' };
+  const enabled = resolveAutoCopyFromMainEnabled({ env, stackName, isInteractive });
+  return await maybeAutoCopyAuthFromMainIfNeeded({
+    rootDir,
+    env,
+    enabled,
+    stackName,
+    cliHomeDir,
+    accountCount,
+    quiet,
+    authEnv,
+  });
+}

package/scripts/utils/stack/startup_server_light_dirs.test.mjs

@@ -0,0 +1,119 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { chmod, mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+import { ensureServerLightSchemaReady } from './startup.mjs';
+
+async function writeJson(path, obj) {
+  await writeFile(path, JSON.stringify(obj, null, 2) + '\n', 'utf-8');
+}
+
+async function writeEsmPkg({ dir, name, body }) {
+  await mkdir(dir, { recursive: true });
+  await writeJson(join(dir, 'package.json'), { name, type: 'module', main: './index.js' });
+  await writeFile(join(dir, 'index.js'), body.trim() + '\n', 'utf-8');
+}
+
+async function writeServerLightProbeStubs(serverDir) {
+  const packages = [
+    {
+      path: join(serverDir, 'node_modules', '@electric-sql', 'pglite'),
+      name: '@electric-sql/pglite',
+      body: `
+export class PGlite {
+  constructor(_dir) { this.waitReady = Promise.resolve(); }
+  async close() {}
+}
+`,
+    },
+    {
+      path: join(serverDir, 'node_modules', '@electric-sql', 'pglite-socket'),
+      name: '@electric-sql/pglite-socket',
+      body: `
+export class PGLiteSocketServer {
+  constructor(_opts) {}
+  async start() {}
+  getServerConn() { return '127.0.0.1:54321'; }
+  async stop() {}
+}
+`,
+    },
+    {
+      path: join(serverDir, 'node_modules', '@prisma', 'client'),
+      name: '@prisma/client',
+      body: `
+export class PrismaClient {
+  constructor() { this.account = { count: async () => 0 }; }
+  async $disconnect() {}
+}
+`,
+    },
+  ];
+
+  for (const pkg of packages) {
+    await writeEsmPkg({ dir: pkg.path, name: pkg.name, body: pkg.body });
+  }
+}
+
+async function writeYarnVersionShim(binDir) {
+  const yarnPath = join(binDir, 'yarn');
+  await mkdir(binDir, { recursive: true });
+  await writeFile(
+    yarnPath,
+    [
+      '#!/usr/bin/env node',
+      "const args = process.argv.slice(2);",
+      "if (args.includes('--version')) { console.log('1.22.22'); process.exit(0); }",
+      'process.exit(0);',
+    ].join('\n') + '\n',
+    'utf-8'
+  );
+  await chmod(yarnPath, 0o755);
+}
+
+async function createServerLightProbeFixture(root) {
+  const serverDir = join(root, 'server');
+  await mkdir(serverDir, { recursive: true });
+  await writeJson(join(serverDir, 'package.json'), { name: 'server', version: '0.0.0', type: 'module' });
+  await writeFile(join(serverDir, 'yarn.lock'), '# yarn\n', 'utf-8');
+  await mkdir(join(serverDir, 'node_modules'), { recursive: true });
+  await writeFile(join(serverDir, 'node_modules', '.yarn-integrity'), 'ok\n', 'utf-8');
+  await writeServerLightProbeStubs(serverDir);
+
+  const binDir = join(root, 'bin');
+  await writeYarnVersionShim(binDir);
+  return { serverDir, binDir };
+}
+
+test('ensureServerLightSchemaReady creates light data dirs before probing', async (t) => {
+  const root = await mkdtemp(join(tmpdir(), 'hs-startup-light-dirs-'));
+  t.after(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const { serverDir, binDir } = await createServerLightProbeFixture(root);
+
+  const dataDir = join(root, 'data');
+  const filesDir = join(dataDir, 'files');
+  const dbDir = join(dataDir, 'pglite');
+  const env = {
+    ...process.env,
+    PATH: `${binDir}:${process.env.PATH ?? ''}`,
+    HAPPIER_SERVER_LIGHT_DATA_DIR: dataDir,
+    HAPPIER_SERVER_LIGHT_FILES_DIR: filesDir,
+    HAPPIER_SERVER_LIGHT_DB_DIR: dbDir,
+  };
+
+  assert.equal(existsSync(dataDir), false);
+  assert.equal(existsSync(filesDir), false);
+  assert.equal(existsSync(dbDir), false);
+
+  await ensureServerLightSchemaReady({ serverDir, env });
+
+  assert.equal(existsSync(dataDir), true);
+  assert.equal(existsSync(filesDir), true);
+  assert.equal(existsSync(dbDir), true);
+});

package/scripts/utils/stack/startup_server_light_generate.test.mjs

@@ -0,0 +1,20 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ensureServerLightSchemaReady } from './startup.mjs';
+import { buildServerLightEnv, createServerLightFixture } from './startup_server_light_testkit.mjs';
+
+test('ensureServerLightSchemaReady runs migrate:sqlite:deploy by default when not best-effort', async (t) => {
+  const { binDir, markerPath, root, serverDir } = await createServerLightFixture(t, {
+    prefix: 'hs-startup-light-migrate-',
+    socketPort: 54322,
+  });
+  const env = buildServerLightEnv({ binDir, root });
+  const res = await ensureServerLightSchemaReady({ serverDir, env });
+  assert.equal(res.ok, true);
+  assert.equal(res.migrated, true);
+  assert.equal(res.accountCount, 0);
+  assert.equal(existsSync(markerPath), true, `expected migrate:sqlite:deploy to be invoked (${markerPath})`);
+});