@happier-dev/stack 0.2.1-preview.1775586714.26562 → 0.2.12-preview.1

package/scripts/utils/server/server.mjs

@@ -1,38 +1,23 @@
 import { setTimeout as delay } from 'node:timers/promises';
 
+const DEFAULT_SERVER_MIGRATION_TIMEOUT_MS = 30 * 60_000;
+const MAX_SERVER_MIGRATION_TIMEOUT_MS = 24 * 60 * 60_000;
+
 function isCanonicalHappierHealthPayload(payload) {
   return payload?.service === 'happier-server' && payload?.status === 'ok';
 }
 
-function isServerStartupReadyHealthPayload(payload) {
+function isServerStartupHealthPayload(payload) {
   if (!payload || typeof payload !== 'object') return false;
   if (isCanonicalHappierHealthPayload(payload)) return true;
   return payload?.status === 'ok';
 }
 
-export function getServerComponentName({ kv } = {}) {
-  const fromArgRaw = kv?.get('--server')?.trim() ? kv.get('--server').trim() : '';
-  const fromEnvRaw = process.env.HAPPIER_STACK_SERVER_COMPONENT?.trim() ? process.env.HAPPIER_STACK_SERVER_COMPONENT.trim() : '';
-  const raw = fromArgRaw || fromEnvRaw || 'happier-server-light';
-  const v = raw.toLowerCase();
-  if (v === 'light' || v === 'server-light' || v === 'happier-server-light' || v === 'happy-server-light') {
-    return 'happier-server-light';
-  }
-  if (v === 'server' || v === 'full' || v === 'happier-server' || v === 'happy-server') {
-    return 'happier-server';
-  }
-  if (v === 'both') {
-    return 'both';
-  }
-  // Allow explicit component dir names (advanced).
-  return raw;
-}
-
-export async function fetchHappierHealth(baseUrl) {
+async function fetchHappierMonitoringEndpoint(baseUrl, endpoint) {
   const ctl = new AbortController();
   const t = setTimeout(() => ctl.abort(), 1500);
   try {
-    const url = baseUrl.replace(/\/+$/, '') + '/health';
+    const url = baseUrl.replace(/\/+$/, '') + endpoint;
     const res = await fetch(url, { method: 'GET', signal: ctl.signal });
     const text = await res.text();
     let json = null;
@@ -43,7 +28,7 @@ export async function fetchHappierHealth(baseUrl) {
     }
     return {
       ok: res.ok && isCanonicalHappierHealthPayload(json),
-      ready: res.ok && isServerStartupReadyHealthPayload(json),
+      ready: res.ok && isServerStartupHealthPayload(json),
       status: res.status,
       json,
       text,
@@ -55,6 +40,32 @@ export async function fetchHappierHealth(baseUrl) {
   }
 }
 
+export function getServerComponentName({ kv } = {}) {
+  const fromArgRaw = kv?.get('--server')?.trim() ? kv.get('--server').trim() : '';
+  const fromEnvRaw = process.env.HAPPIER_STACK_SERVER_COMPONENT?.trim() ? process.env.HAPPIER_STACK_SERVER_COMPONENT.trim() : '';
+  const raw = fromArgRaw || fromEnvRaw || 'happier-server-light';
+  const v = raw.toLowerCase();
+  if (v === 'light' || v === 'server-light' || v === 'happier-server-light' || v === 'happy-server-light') {
+    return 'happier-server-light';
+  }
+  if (v === 'server' || v === 'full' || v === 'happier-server' || v === 'happy-server') {
+    return 'happier-server';
+  }
+  if (v === 'both') {
+    return 'both';
+  }
+  // Allow explicit component dir names (advanced).
+  return raw;
+}
+
+export async function fetchHappierHealth(baseUrl) {
+  return await fetchHappierMonitoringEndpoint(baseUrl, '/health');
+}
+
+export async function fetchHappierReadiness(baseUrl) {
+  return await fetchHappierMonitoringEndpoint(baseUrl, '/ready');
+}
+
 export async function isHappierServerRunning(baseUrl) {
   const health = await fetchHappierHealth(baseUrl);
   return health.ok;
@@ -90,8 +101,100 @@ export function resolveServerReadyTimeoutMs({ serverComponentName = '', env = pr
   return serverComponentName === 'happier-server-light' ? 120_000 : 60_000;
 }
 
-export async function waitForServerReady(url, { timeoutMs = 60_000, intervalMs = 300, childProcess = null } = {}) {
-  const deadline = Date.now() + timeoutMs;
+export function resolveServerMigrationTimeoutMs({ env = process.env } = {}) {
+  const configured = Number.parseInt(String(env?.HAPPIER_STACK_SERVER_MIGRATION_TIMEOUT_MS ?? '').trim(), 10);
+  if (Number.isFinite(configured) && configured >= 1_000 && configured <= MAX_SERVER_MIGRATION_TIMEOUT_MS) {
+    return configured;
+  }
+  // Large SQLite schema changes can legitimately exceed ordinary startup readiness.
+  // Keep that lifetime finite by default while allowing operators to tune it for their database.
+  return DEFAULT_SERVER_MIGRATION_TIMEOUT_MS;
+}
+
+export function createServerReadinessDeadline({
+  readinessTimeoutMs,
+  migrationTimeoutMs,
+  nowImpl = Date.now,
+} = {}) {
+  const rawReadyMs = Number(readinessTimeoutMs);
+  const rawMigrationMs = Number(migrationTimeoutMs);
+  const readyMs = Number.isFinite(rawReadyMs) && rawReadyMs > 0 ? Math.trunc(rawReadyMs) : 60_000;
+  const migrationMs = Number.isFinite(rawMigrationMs) && rawMigrationMs > 0
+    ? Math.min(Math.trunc(rawMigrationMs), MAX_SERVER_MIGRATION_TIMEOUT_MS)
+    : DEFAULT_SERVER_MIGRATION_TIMEOUT_MS;
+  let phase = 'pending';
+  let deadlineMs = null;
+  let migrationStarted = false;
+  let migrationCompleted = false;
+  const now = () => {
+    const value = Number(nowImpl?.());
+    return Number.isFinite(value) ? value : Date.now();
+  };
+
+  const startReadiness = () => {
+    if (deadlineMs === null) {
+      phase = 'readiness';
+      deadlineMs = now() + readyMs;
+    }
+    return deadlineMs;
+  };
+
+  const observeSignal = (signal) => {
+    if (signal === 'migration_started' && !migrationStarted) {
+      migrationStarted = true;
+      phase = 'migration';
+      deadlineMs = now() + migrationMs;
+    } else if (signal === 'migration_completed' && migrationStarted && !migrationCompleted) {
+      migrationCompleted = true;
+      phase = 'readiness';
+      deadlineMs = now() + readyMs;
+    }
+    return signal;
+  };
+
+  return {
+    startReadiness,
+    observeSignal,
+    observeLine({ line } = {}) {
+      let signal = null;
+      try {
+        signal = JSON.parse(String(line ?? ''))?.happierStackTransition ?? null;
+      } catch {
+        return null;
+      }
+      return observeSignal(signal);
+    },
+    getDeadlineMs() {
+      return startReadiness();
+    },
+    getPhase() {
+      return phase;
+    },
+    extendCurrentPhase() {
+      deadlineMs = now() + (phase === 'migration' ? migrationMs : readyMs);
+      return deadlineMs;
+    },
+    isExpired() {
+      return now() >= startReadiness();
+    },
+  };
+}
+
+export async function waitForServerReady(url, {
+  timeoutMs = 60_000,
+  intervalMs = 300,
+  childProcess = null,
+  startupDeadline = null,
+  continueWhileChildAlive = process.env.HAPPIER_STACK_TUI === '1',
+  onTimeoutCheckpoint = ({ phase }) => {
+    console.warn(`[stack] server ${phase} is still in progress at ${url}; continuing to wait (TUI is attended)`);
+  },
+} = {}) {
+  const deadline = startupDeadline ?? createServerReadinessDeadline({
+    readinessTimeoutMs: timeoutMs,
+    migrationTimeoutMs: timeoutMs,
+  });
+  deadline.startReadiness();
   let earlyExitError = null;
   const onExit = (code, signal) => {
     earlyExitError = new Error(formatServerReadyEarlyExit(url, code, signal));
@@ -105,32 +208,36 @@ export async function waitForServerReady(url, { timeoutMs = 60_000, intervalMs =
   }
 
   try {
-    while (Date.now() < deadline) {
+    while (true) {
       if (earlyExitError) {
         throw earlyExitError;
       }
-      // Runtime-backed stacks and modern server builds expose readiness on /health even when
-      // the root route serves the app shell instead of the legacy welcome page.
-      // Prefer that contract, but keep the older root-page probe as a fallback for source/dev flows.
+      if (deadline.isExpired()) {
+        const childAlive = childProcess
+          && childProcess.exitCode == null
+          && childProcess.signalCode == null;
+        if (!continueWhileChildAlive || !childAlive) break;
+        onTimeoutCheckpoint?.({ phase: deadline.getPhase(), timeoutMs, url });
+        deadline.extendCurrentPhase();
+      }
+      // Runtime-backed stacks and modern server builds expose startup readiness on /ready.
+      // Promotion must not accept root-page liveness because the app shell can serve before DB readiness.
       // eslint-disable-next-line no-await-in-loop
-      const health = await fetchHappierHealth(url);
-      if (health.ready) {
-        return;
+      const readiness = await fetchHappierReadiness(url);
+      if (earlyExitError) {
+        throw earlyExitError;
       }
-      try {
-        const res = await fetch(url, { method: 'GET' });
-        const text = await res.text();
-        if (res.ok && text.includes('Welcome to Happier Server!')) {
-          return;
-        }
-      } catch {
-        // ignore
+      if (readiness.ready) {
+        return;
       }
       await delay(intervalMs);
     }
     if (earlyExitError) {
       throw earlyExitError;
     }
+    if (deadline.getPhase() === 'migration') {
+      throw new Error(`Server migration timed out before readiness at ${url}`);
+    }
     throw new Error(`Timed out waiting for server at ${url}`);
   } finally {
     if (childProcess && typeof childProcess.off === 'function') {

package/scripts/utils/server/server.test.mjs

@@ -4,8 +4,10 @@ import { createServer } from 'node:http';
 import { EventEmitter } from 'node:events';
 
 import {
+  createServerReadinessDeadline,
   fetchHappierHealth,
   isHappierServerRunning,
+  resolveServerMigrationTimeoutMs,
   resolveServerReadyTimeoutMs,
   waitForHappierHealthOk,
   waitForServerReady,
@@ -90,6 +92,31 @@ test('isHappierServerRunning rejects 200 JSON responses without Happier service
   }
 });
 
+test('isHappierServerRunning uses DB-free liveness when readiness is unavailable', async () => {
+  const fixture = await listenServer((req, res) => {
+    if (req.url === '/health') {
+      res.statusCode = 200;
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify({ status: 'ok', service: 'happier-server' }));
+      return;
+    }
+    if (req.url === '/ready') {
+      res.statusCode = 503;
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify({ status: 'error', service: 'happier-server' }));
+      return;
+    }
+    res.statusCode = 404;
+    res.end('not found');
+  });
+  try {
+    const running = await isHappierServerRunning(fixture.url);
+    assert.equal(running, true);
+  } finally {
+    await fixture.close();
+  }
+});
+
 test('waitForHappierHealthOk keeps waiting when /health returns unrelated 2xx responses', async () => {
   const fixture = await listenServer((req, res) => {
     if (req.url === '/health') {
@@ -109,10 +136,18 @@ test('waitForHappierHealthOk keeps waiting when /health returns unrelated 2xx re
   }
 });
 
-test('waitForServerReady accepts an extended timeout for delayed healthy startups', async () => {
+test('waitForServerReady polls /ready for delayed database-ready startups', async () => {
   let readyAt = 0;
+  const seenUrls = [];
   const fixture = await listenServer((req, res) => {
+    seenUrls.push(req.url);
     if (req.url === '/health') {
+      res.statusCode = 200;
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify({ status: 'ok', service: 'happier-server' }));
+      return;
+    }
+    if (req.url === '/ready') {
       if (!readyAt) readyAt = Date.now() + 120;
       if (Date.now() >= readyAt) {
         res.statusCode = 200;
@@ -129,24 +164,61 @@ test('waitForServerReady accepts an extended timeout for delayed healthy startup
   });
   try {
     await waitForServerReady(fixture.url, { timeoutMs: 400, intervalMs: 25 });
+    assert.ok(seenUrls.includes('/ready'), 'expected waitForServerReady to poll /ready');
   } finally {
     await fixture.close();
   }
 });
 
-test('waitForServerReady accepts generic ok health payloads for runtime startup readiness', async () => {
+test('waitForServerReady does not accept /health liveness while /ready is unavailable', async () => {
   const fixture = await listenServer((req, res) => {
     if (req.url === '/health') {
       res.statusCode = 200;
       res.setHeader('content-type', 'application/json');
-      res.end(JSON.stringify({ status: 'ok', marker: 'runtime-snapshot' }));
+      res.end(JSON.stringify({ status: 'ok', service: 'happier-server' }));
+      return;
+    }
+    if (req.url === '/ready') {
+      res.statusCode = 503;
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify({ status: 'error', service: 'happier-server', reason: 'db_error' }));
+      return;
+    }
+    res.statusCode = 404;
+    res.end('not found');
+  });
+  try {
+    await assert.rejects(
+      () => waitForServerReady(fixture.url, { timeoutMs: 80, intervalMs: 20 }),
+      /Timed out waiting for server/,
+    );
+  } finally {
+    await fixture.close();
+  }
+});
+
+test('waitForServerReady does not accept the root welcome page while /ready is unavailable', async () => {
+  const fixture = await listenServer((req, res) => {
+    if (req.url === '/ready') {
+      res.statusCode = 503;
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify({ status: 'error', service: 'happier-server', reason: 'db_error' }));
+      return;
+    }
+    if (req.url === '/') {
+      res.statusCode = 200;
+      res.setHeader('content-type', 'text/html');
+      res.end('<!doctype html><body>Welcome to Happier Server!</body>');
       return;
     }
     res.statusCode = 404;
     res.end('not found');
   });
   try {
-    await waitForServerReady(fixture.url, { timeoutMs: 200, intervalMs: 25 });
+    await assert.rejects(
+      () => waitForServerReady(fixture.url, { timeoutMs: 80, intervalMs: 20 }),
+      /Timed out waiting for server/,
+    );
   } finally {
     await fixture.close();
   }
@@ -170,6 +242,173 @@ test('waitForServerReady fails early when the child process exits before health
   );
 });
 
+test('waitForServerReady treats attended TUI deadlines as checkpoints while the child is alive', async () => {
+  const child = new EventEmitter();
+  child.exitCode = null;
+  child.signalCode = null;
+  let readyAt = 0;
+  let checkpoints = 0;
+  const fixture = await listenServer((_req, res) => {
+    if (!readyAt) readyAt = Date.now() + 120;
+    const ready = Date.now() >= readyAt;
+    res.statusCode = ready ? 200 : 503;
+    res.setHeader('content-type', 'application/json');
+    res.end(JSON.stringify(ready
+      ? { status: 'ok', service: 'happier-server' }
+      : { status: 'starting' }));
+  });
+
+  try {
+    await waitForServerReady(fixture.url, {
+      timeoutMs: 40,
+      intervalMs: 10,
+      childProcess: child,
+      continueWhileChildAlive: true,
+      onTimeoutCheckpoint: () => { checkpoints += 1; },
+    });
+    assert.equal(checkpoints >= 1, true);
+  } finally {
+    await fixture.close();
+  }
+});
+
+test('waitForServerReady rejects when the child exits during the successful readiness probe', async () => {
+  const child = new EventEmitter();
+  child.exitCode = null;
+  const fixture = await listenServer((req, res) => {
+    if (req.url !== '/ready') {
+      res.statusCode = 404;
+      res.end('not found');
+      return;
+    }
+    child.exitCode = 9;
+    child.emit('exit', 9, null);
+    res.statusCode = 200;
+    res.setHeader('content-type', 'application/json');
+    res.end(JSON.stringify({ status: 'ok', service: 'happier-server' }));
+  });
+
+  try {
+    await assert.rejects(
+      waitForServerReady(fixture.url, {
+        timeoutMs: 500,
+        intervalMs: 25,
+        childProcess: child,
+      }),
+      /exited before becoming ready/,
+    );
+  } finally {
+    await fixture.close();
+  }
+});
+
+test('migration start switches readiness waiting to the bounded migration deadline', async () => {
+  let readyAt = 0;
+  const fixture = await listenServer((req, res) => {
+    if (!readyAt) readyAt = Date.now() + 120;
+    if (Date.now() >= readyAt) {
+      res.statusCode = 200;
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify({ status: 'ok', service: 'happier-server' }));
+      return;
+    }
+    res.statusCode = 503;
+    res.end('migrating');
+  });
+  const startupDeadline = createServerReadinessDeadline({
+    readinessTimeoutMs: 50,
+    migrationTimeoutMs: 2_000,
+  });
+  startupDeadline.observeLine({
+    stream: 'stdout',
+    line: '{"happierStackTransition":"migration_started"}',
+  });
+
+  try {
+    await waitForServerReady(fixture.url, {
+      timeoutMs: 50,
+      intervalMs: 20,
+      startupDeadline,
+    });
+  } finally {
+    await fixture.close();
+  }
+});
+
+test('migration completion starts a fresh ordinary readiness deadline', async () => {
+  const fixture = await listenServer((_req, res) => {
+    res.statusCode = 503;
+    res.end('starting');
+  });
+  const startupDeadline = createServerReadinessDeadline({
+    readinessTimeoutMs: 50,
+    migrationTimeoutMs: 2_000,
+  });
+  startupDeadline.observeLine({ line: '{"happierStackTransition":"migration_started"}' });
+  setTimeout(() => {
+    startupDeadline.observeLine({ line: '{"happierStackTransition":"migration_completed"}' });
+  }, 30);
+  const startedAt = Date.now();
+
+  try {
+    await assert.rejects(
+      waitForServerReady(fixture.url, {
+        timeoutMs: 50,
+        intervalMs: 10,
+        startupDeadline,
+      }),
+      /Timed out waiting for server/,
+    );
+    assert.ok(Date.now() - startedAt < 1_000, 'completion must restore the short readiness deadline');
+  } finally {
+    await fixture.close();
+  }
+});
+
+test('migration deadline stays bounded and child early exit still wins', async () => {
+  const fixture = await listenServer((_req, res) => {
+    res.statusCode = 503;
+    res.end('migrating');
+  });
+  const boundedDeadline = createServerReadinessDeadline({
+    readinessTimeoutMs: 30,
+    migrationTimeoutMs: 70,
+  });
+  boundedDeadline.observeLine({ line: '{"happierStackTransition":"migration_started"}' });
+  try {
+    await assert.rejects(
+      waitForServerReady(fixture.url, {
+        timeoutMs: 30,
+        intervalMs: 10,
+        startupDeadline: boundedDeadline,
+      }),
+      /migration.*timed out|timed out.*migration/i,
+    );
+    const child = new EventEmitter();
+    child.exitCode = null;
+    const exitDeadline = createServerReadinessDeadline({
+      readinessTimeoutMs: 30,
+      migrationTimeoutMs: 500,
+    });
+    exitDeadline.observeLine({ line: '{"happierStackTransition":"migration_started"}' });
+    setTimeout(() => {
+      child.exitCode = 2;
+      child.emit('exit', 2, null);
+    }, 20);
+    await assert.rejects(
+      waitForServerReady(fixture.url, {
+        timeoutMs: 30,
+        intervalMs: 10,
+        childProcess: child,
+        startupDeadline: exitDeadline,
+      }),
+      /exited before becoming ready/,
+    );
+  } finally {
+    await fixture.close();
+  }
+});
+
 test('resolveServerReadyTimeoutMs prefers an explicit override and otherwise gives light server more time', () => {
   assert.equal(resolveServerReadyTimeoutMs({ serverComponentName: 'happier-server-light', env: {} }), 120_000);
   assert.equal(resolveServerReadyTimeoutMs({ serverComponentName: 'happier-server', env: {} }), 60_000);
@@ -180,4 +419,13 @@ test('resolveServerReadyTimeoutMs prefers an explicit override and otherwise giv
     }),
     90_000,
   );
+  assert.equal(resolveServerMigrationTimeoutMs({ env: {} }), 30 * 60_000);
+  assert.equal(
+    resolveServerMigrationTimeoutMs({ env: { HAPPIER_STACK_SERVER_MIGRATION_TIMEOUT_MS: '240000' } }),
+    240_000,
+  );
+  assert.equal(
+    resolveServerMigrationTimeoutMs({ env: { HAPPIER_STACK_SERVER_MIGRATION_TIMEOUT_MS: '86400001' } }),
+    30 * 60_000,
+  );
 });

package/scripts/utils/server/server_migrations.mjs

@@ -0,0 +1,17 @@
+import { pmExecBin } from '../proc/pm.mjs';
+import { normalizeDbProvider } from './effective_db_provider.mjs';
+
+export async function applyServerMigrations(
+  { serverDir, env, quiet = false, dbProvider },
+  { pmExecBinImpl = pmExecBin } = {},
+) {
+  const effectiveDbProvider = normalizeDbProvider(dbProvider);
+  if (!effectiveDbProvider) throw new Error(`Unsupported DB provider: ${String(dbProvider ?? '')}`);
+  await pmExecBinImpl({
+    dir: serverDir,
+    bin: 'migrate:deploy',
+    args: [],
+    env: { ...env, HAPPIER_DB_PROVIDER: effectiveDbProvider },
+    quiet,
+  });
+}

package/scripts/utils/server/shutdown_grace.mjs

@@ -0,0 +1,14 @@
+export const DEFAULT_SERVER_SHUTDOWN_DEADLINE_MS = 5_000;
+
+// Allow the server process to exit after its own forced-shutdown deadline before escalation.
+export const SERVER_PROCESS_EXIT_OVERHEAD_MS = 250;
+
+export function resolveServerShutdownGraceMs(env = process.env) {
+  const raw = String(env.HAPPIER_SERVER_SHUTDOWN_DEADLINE_MS ?? '').trim();
+  const parsed = raw ? Number.parseInt(raw, 10) : Number.NaN;
+  const shutdownDeadlineMs = Number.isFinite(parsed) && parsed > 0
+    ? parsed
+    : DEFAULT_SERVER_SHUTDOWN_DEADLINE_MS;
+
+  return shutdownDeadlineMs + SERVER_PROCESS_EXIT_OVERHEAD_MS;
+}

package/scripts/utils/server/shutdown_grace.test.mjs

@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  DEFAULT_SERVER_SHUTDOWN_DEADLINE_MS,
+  SERVER_PROCESS_EXIT_OVERHEAD_MS,
+  resolveServerShutdownGraceMs,
+} from './shutdown_grace.mjs';
+
+test('resolveServerShutdownGraceMs gives the server deadline plus bounded process-exit overhead', () => {
+  assert.equal(DEFAULT_SERVER_SHUTDOWN_DEADLINE_MS, 5_000);
+  assert.equal(SERVER_PROCESS_EXIT_OVERHEAD_MS, 250);
+  assert.equal(resolveServerShutdownGraceMs({}), 5_250);
+
+  assert.equal(
+    resolveServerShutdownGraceMs({ HAPPIER_SERVER_SHUTDOWN_DEADLINE_MS: ' 1200ms ' }),
+    1_450,
+  );
+});
+
+test('resolveServerShutdownGraceMs falls back for absent, invalid, and nonpositive deadlines', () => {
+  for (const configured of [undefined, '', '   ', 'not-a-number', '0', '-20']) {
+    const env = configured === undefined
+      ? {}
+      : { HAPPIER_SERVER_SHUTDOWN_DEADLINE_MS: configured };
+
+    assert.equal(resolveServerShutdownGraceMs(env), 5_250, `configured=${String(configured)}`);
+  }
+});

package/scripts/utils/server/source_server_workspace_deps.mjs

@@ -0,0 +1,27 @@
+import { ensureWorkspacePackagesBuiltForComponent, pmSpawnScript } from '../proc/pm.mjs';
+
+export async function ensureSourceServerWorkspacePackagesBuilt(
+  { runtimeBackedStart = false, serverDir, env = process.env, quiet = false } = {},
+  { ensureWorkspacePackagesBuiltForComponentImpl = ensureWorkspacePackagesBuiltForComponent } = {},
+) {
+  if (runtimeBackedStart) {
+    return { ran: false, reason: 'runtime-backed' };
+  }
+
+  const result = await ensureWorkspacePackagesBuiltForComponentImpl(serverDir, { quiet, env });
+  return { ran: true, reason: 'source-server', result };
+}
+
+export async function spawnSourceServerScript(
+  { label = 'server', serverDir, script, env = process.env, quiet = false } = {},
+  {
+    ensureWorkspacePackagesBuiltForComponentImpl = ensureWorkspacePackagesBuiltForComponent,
+    pmSpawnScriptImpl = pmSpawnScript,
+  } = {},
+) {
+  await ensureSourceServerWorkspacePackagesBuilt(
+    { runtimeBackedStart: false, serverDir, env, quiet },
+    { ensureWorkspacePackagesBuiltForComponentImpl },
+  );
+  return await pmSpawnScriptImpl({ label, dir: serverDir, script, env });
+}