happy-stacks 0.1.0 → 0.2.0

package/scripts/utils/config.mjs

@@ -1,11 +1,20 @@
 import { join } from 'node:path';
 import { ensureEnvFileUpdated } from './env_file.mjs';
 import { getHappyStacksHomeDir, resolveStackEnvPath } from './paths.mjs';
+import { getCanonicalHomeDirFromEnv } from './canonical_home.mjs';
 
 export function getHomeEnvPath() {
   return join(getHappyStacksHomeDir(), '.env');
 }
 
+export function getCanonicalHomeDir() {
+  return getCanonicalHomeDirFromEnv(process.env);
+}
+
+export function getCanonicalHomeEnvPath() {
+  return join(getCanonicalHomeDir(), '.env');
+}
+
 export function getHomeEnvLocalPath() {
   return join(getHappyStacksHomeDir(), 'env.local');
 }
@@ -28,6 +37,10 @@ export async function ensureHomeEnvUpdated({ updates }) {
   await ensureEnvFileUpdated({ envPath: getHomeEnvPath(), updates });
 }
 
+export async function ensureCanonicalHomeEnvUpdated({ updates }) {
+  await ensureEnvFileUpdated({ envPath: getCanonicalHomeEnvPath(), updates });
+}
+
 export async function ensureHomeEnvLocalUpdated({ updates }) {
   await ensureEnvFileUpdated({ envPath: getHomeEnvLocalPath(), updates });
 }
@@ -37,4 +50,3 @@ export async function ensureUserConfigEnvUpdated({ cliRootDir, updates }) {
   await ensureEnvFileUpdated({ envPath, updates });
   return envPath;
 }
-

package/scripts/utils/dev_auth_key.mjs

@@ -0,0 +1,169 @@
+import { chmod, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { expandHome } from './canonical_home.mjs';
+
+export function resolveHappyStacksHomeDir(env = process.env) {
+  const fromEnv = (env.HAPPY_STACKS_HOME_DIR ?? env.HAPPY_LOCAL_HOME_DIR ?? '').toString().trim();
+  return fromEnv ? expandHome(fromEnv) : join(homedir(), '.happy-stacks');
+}
+
+export function getDevAuthKeyPath(env = process.env) {
+  return join(resolveHappyStacksHomeDir(env), 'keys', 'dev-auth.json');
+}
+
+function base64UrlToBytes(s) {
+  try {
+    const raw = String(s ?? '').trim();
+    if (!raw) return null;
+    const b64 = raw.replace(/-/g, '+').replace(/_/g, '/');
+    const pad = b64.length % 4 === 0 ? '' : '='.repeat(4 - (b64.length % 4));
+    return new Uint8Array(Buffer.from(b64 + pad, 'base64'));
+  } catch {
+    return null;
+  }
+}
+
+function bytesToBase64Url(bytes) {
+  const b64 = Buffer.from(bytes).toString('base64');
+  return b64.replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+
+// Base32 alphabet (RFC 4648)
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+
+function bytesToBase32(bytes) {
+  let result = '';
+  let buffer = 0;
+  let bufferLength = 0;
+
+  for (const byte of bytes) {
+    buffer = (buffer << 8) | byte;
+    bufferLength += 8;
+    while (bufferLength >= 5) {
+      bufferLength -= 5;
+      result += BASE32_ALPHABET[(buffer >> bufferLength) & 0x1f];
+    }
+  }
+  if (bufferLength > 0) {
+    result += BASE32_ALPHABET[(buffer << (5 - bufferLength)) & 0x1f];
+  }
+  return result;
+}
+
+function base32ToBytes(base32) {
+  let normalized = String(base32 ?? '')
+    .toUpperCase()
+    .replace(/0/g, 'O')
+    .replace(/1/g, 'I')
+    .replace(/8/g, 'B')
+    .replace(/9/g, 'G');
+  const cleaned = normalized.replace(/[^A-Z2-7]/g, '');
+  if (!cleaned) throw new Error('no valid base32 characters');
+
+  const bytes = [];
+  let buffer = 0;
+  let bufferLength = 0;
+  for (const char of cleaned) {
+    const value = BASE32_ALPHABET.indexOf(char);
+    if (value === -1) throw new Error('invalid base32 character');
+    buffer = (buffer << 5) | value;
+    bufferLength += 5;
+    if (bufferLength >= 8) {
+      bufferLength -= 8;
+      bytes.push((buffer >> bufferLength) & 0xff);
+    }
+  }
+  return new Uint8Array(bytes);
+}
+
+export function normalizeDevAuthKeyInputToBytes(input) {
+  const raw = String(input ?? '').trim();
+  if (!raw) return null;
+
+  // Match Happy UI behavior:
+  // - backup format is base32 and is long (usually grouped with '-' / spaces)
+  // - base64url is short (~43 chars) and may contain '-' / '_' legitimately
+  //
+  // Key point: avoid mis-parsing backup base32 as base64.
+  if (raw.length > 50) {
+    try {
+      const b32 = base32ToBytes(raw);
+      return b32.length === 32 ? b32 : null;
+    } catch {
+      return null;
+    }
+  }
+
+  const b64 = base64UrlToBytes(raw);
+  if (b64 && b64.length === 32) return b64;
+  try {
+    const b32 = base32ToBytes(raw);
+    return b32.length === 32 ? b32 : null;
+  } catch {
+    return null;
+  }
+}
+
+export function formatDevAuthKeyBackup(secretKeyBase64Url) {
+  const bytes = base64UrlToBytes(secretKeyBase64Url);
+  if (!bytes || bytes.length !== 32) throw new Error('invalid secret key (expected base64url 32 bytes)');
+  const base32 = bytesToBase32(bytes);
+  const groups = [];
+  for (let i = 0; i < base32.length; i += 5) groups.push(base32.slice(i, i + 5));
+  return groups.join('-');
+}
+
+export async function readDevAuthKey({ env = process.env } = {}) {
+  if ((env.HAPPY_STACKS_DEV_AUTH_SECRET_KEY ?? '').toString().trim()) {
+    const bytes = normalizeDevAuthKeyInputToBytes(env.HAPPY_STACKS_DEV_AUTH_SECRET_KEY);
+    if (!bytes) return { ok: false, error: 'invalid_env_key', source: 'env', secretKeyBase64Url: null, backup: null };
+    const base64url = bytesToBase64Url(bytes);
+    return { ok: true, source: 'env:HAPPY_STACKS_DEV_AUTH_SECRET_KEY', secretKeyBase64Url: base64url, backup: formatDevAuthKeyBackup(base64url) };
+  }
+
+  const path = getDevAuthKeyPath(env);
+  try {
+    if (!existsSync(path)) return { ok: true, source: `file:${path}`, secretKeyBase64Url: null, backup: null, path };
+    const raw = await readFile(path, 'utf-8');
+    const parsed = JSON.parse(raw);
+    const input = parsed?.secretKeyBase64Url ?? parsed?.secretKey ?? parsed?.key ?? null;
+    const bytes = normalizeDevAuthKeyInputToBytes(input);
+    if (!bytes) return { ok: false, error: 'invalid_file_key', source: `file:${path}`, secretKeyBase64Url: null, backup: null, path };
+    const base64url = bytesToBase64Url(bytes);
+    return { ok: true, source: `file:${path}`, secretKeyBase64Url: base64url, backup: formatDevAuthKeyBackup(base64url), path };
+  } catch (e) {
+    return { ok: false, error: 'failed_to_read', source: `file:${path}`, secretKeyBase64Url: null, backup: null, path, details: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+export async function writeDevAuthKey({ env = process.env, input } = {}) {
+  const bytes = normalizeDevAuthKeyInputToBytes(input);
+  if (!bytes || bytes.length !== 32) {
+    throw new Error('invalid secret key (expected 32 bytes; accept base64url or backup format)');
+  }
+  const secretKeyBase64Url = bytesToBase64Url(bytes);
+  const path = getDevAuthKeyPath(env);
+  await mkdir(dirname(path), { recursive: true });
+  const payload = {
+    v: 1,
+    createdAt: new Date().toISOString(),
+    secretKeyBase64Url,
+  };
+  await writeFile(path, JSON.stringify(payload, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+  await chmod(path, 0o600).catch(() => {});
+  return { ok: true, path, secretKeyBase64Url, backup: formatDevAuthKeyBackup(secretKeyBase64Url) };
+}
+
+export async function clearDevAuthKey({ env = process.env } = {}) {
+  const path = getDevAuthKeyPath(env);
+  try {
+    if (!existsSync(path)) return { ok: true, deleted: false, path };
+    await unlink(path);
+    return { ok: true, deleted: true, path };
+  } catch (e) {
+    return { ok: false, deleted: false, path, error: e instanceof Error ? e.message : String(e) };
+  }
+}

package/scripts/utils/dev_daemon.mjs

@@ -0,0 +1,104 @@
+import { resolve } from 'node:path';
+
+import { ensureCliBuilt, ensureDepsInstalled } from './pm.mjs';
+import { watchDebounced } from './watch.mjs';
+import { getAccountCountForServerComponent, prepareDaemonAuthSeedIfNeeded } from './stack_startup.mjs';
+import { startLocalDaemonWithAuth } from '../daemon.mjs';
+
+export async function ensureDevCliReady({ cliDir, buildCli }) {
+  await ensureDepsInstalled(cliDir, 'happy-cli');
+  return await ensureCliBuilt(cliDir, { buildCli });
+}
+
+export async function prepareDaemonAuthSeed({
+  rootDir,
+  env,
+  stackName,
+  cliHomeDir,
+  startDaemon,
+  isInteractive,
+  serverComponentName,
+  serverDir,
+  serverEnv,
+  quiet = false,
+}) {
+  if (!startDaemon) return { ok: true, skipped: true, reason: 'no_daemon' };
+  const acct = await getAccountCountForServerComponent({
+    serverComponentName,
+    serverDir,
+    env: serverEnv,
+    bestEffort: serverComponentName === 'happy-server',
+  });
+  return await prepareDaemonAuthSeedIfNeeded({
+    rootDir,
+    env,
+    stackName,
+    cliHomeDir,
+    startDaemon,
+    isInteractive,
+    accountCount: typeof acct.accountCount === 'number' ? acct.accountCount : null,
+    quiet,
+    // IMPORTANT: run auth seeding under the same env used for server probes (includes DATABASE_URL).
+    authEnv: serverEnv,
+  });
+}
+
+export async function startDevDaemon({
+  startDaemon,
+  cliBin,
+  cliHomeDir,
+  internalServerUrl,
+  publicServerUrl,
+  restart,
+  isShuttingDown,
+}) {
+  if (!startDaemon) return;
+  await startLocalDaemonWithAuth({
+    cliBin,
+    cliHomeDir,
+    internalServerUrl,
+    publicServerUrl,
+    isShuttingDown,
+    forceRestart: Boolean(restart),
+  });
+}
+
+export function watchHappyCliAndRestartDaemon({
+  enabled,
+  startDaemon,
+  buildCli,
+  cliDir,
+  cliBin,
+  cliHomeDir,
+  internalServerUrl,
+  publicServerUrl,
+  isShuttingDown,
+}) {
+  if (!enabled || !startDaemon) return null;
+
+  let inFlight = false;
+  return watchDebounced({
+    paths: [resolve(cliDir)],
+    debounceMs: 500,
+    onChange: async () => {
+      if (isShuttingDown?.()) return;
+      if (inFlight) return;
+      inFlight = true;
+      try {
+        // eslint-disable-next-line no-console
+        console.log('[local] watch: happy-cli changed → rebuilding + restarting daemon...');
+        await ensureCliBuilt(cliDir, { buildCli });
+        await startLocalDaemonWithAuth({
+          cliBin,
+          cliHomeDir,
+          internalServerUrl,
+          publicServerUrl,
+          isShuttingDown,
+          forceRestart: true,
+        });
+      } finally {
+        inFlight = false;
+      }
+    },
+  });
+}

package/scripts/utils/dev_expo_web.mjs

@@ -0,0 +1,112 @@
+import { ensureDepsInstalled, pmSpawnBin } from './pm.mjs';
+import { ensureExpoIsolationEnv, getExpoStatePaths, isStateProcessRunning, wantsExpoClearCache, writePidState } from './expo.mjs';
+import { pickDevMetroPort, resolveStackUiDevPortStart } from './dev_server.mjs';
+import { recordStackRuntimeUpdate } from './stack_runtime_state.mjs';
+import { killProcessGroupOwnedByStack } from './ownership.mjs';
+
+export async function startDevExpoWebUi({
+  startUi,
+  uiDir,
+  autostart,
+  baseEnv,
+  apiServerUrl,
+  restart,
+  stackMode,
+  runtimeStatePath,
+  stackName,
+  envPath,
+  children,
+  spawnOptions = {},
+}) {
+  if (!startUi) return { ok: true, skipped: true, reason: 'disabled' };
+
+  await ensureDepsInstalled(uiDir, 'happy');
+  const uiEnv = { ...baseEnv };
+  delete uiEnv.CI;
+  uiEnv.EXPO_PUBLIC_HAPPY_SERVER_URL = apiServerUrl;
+  uiEnv.EXPO_PUBLIC_DEBUG = uiEnv.EXPO_PUBLIC_DEBUG ?? '1';
+
+  // We own the browser opening behavior in Happy Stacks so we can reliably open the correct origin.
+  uiEnv.EXPO_NO_BROWSER = '1';
+  uiEnv.BROWSER = 'none';
+
+  const uiPaths = getExpoStatePaths({
+    baseDir: autostart.baseDir,
+    kind: 'ui-dev',
+    projectDir: uiDir,
+    stateFileName: 'ui.state.json',
+  });
+
+  await ensureExpoIsolationEnv({
+    env: uiEnv,
+    stateDir: uiPaths.stateDir,
+    expoHomeDir: uiPaths.expoHomeDir,
+    tmpDir: uiPaths.tmpDir,
+  });
+
+  const uiRunning = await isStateProcessRunning(uiPaths.statePath);
+  const uiAlreadyRunning = Boolean(uiRunning.running);
+
+  if (uiAlreadyRunning && !restart) {
+    const pid = Number(uiRunning.state?.pid);
+    const port = Number(uiRunning.state?.port);
+    if (stackMode && runtimeStatePath && Number.isFinite(pid) && pid > 1) {
+      await recordStackRuntimeUpdate(runtimeStatePath, {
+        processes: { expoWebPid: pid },
+        expo: { webPort: Number.isFinite(port) && port > 0 ? port : null },
+      }).catch(() => {});
+    }
+    return {
+      ok: true,
+      skipped: true,
+      reason: 'already_running',
+      pid: Number.isFinite(pid) ? pid : null,
+      port: Number.isFinite(port) ? port : null,
+    };
+  }
+
+  const strategy =
+    (baseEnv.HAPPY_STACKS_UI_DEV_PORT_STRATEGY ?? baseEnv.HAPPY_LOCAL_UI_DEV_PORT_STRATEGY ?? 'ephemeral').toString().trim() ||
+    'ephemeral';
+  const stable = strategy === 'stable';
+  const startPort = stackMode && stable ? resolveStackUiDevPortStart({ env: baseEnv, stackName }) : 8081;
+  const metroPort = await pickDevMetroPort({ startPort });
+  uiEnv.RCT_METRO_PORT = String(metroPort);
+
+  const uiArgs = ['start', '--web', '--port', String(metroPort)];
+  if (wantsExpoClearCache({ env: baseEnv })) {
+    uiArgs.push('--clear');
+  }
+
+  if (restart && uiRunning.state?.pid) {
+    const prevPid = Number(uiRunning.state.pid);
+    const res = await killProcessGroupOwnedByStack(prevPid, { stackName, envPath, label: 'expo-web', json: true });
+    if (!res.killed) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[local] ui: not stopping existing Expo pid=${prevPid} because it does not look stack-owned.\n` +
+          `[local] ui: continuing by starting a new Expo process on a free port.`
+      );
+    }
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(`[local] ui: starting Expo web (metro port=${metroPort})`);
+  const ui = await pmSpawnBin({ label: 'ui', dir: uiDir, bin: 'expo', args: uiArgs, env: uiEnv, options: spawnOptions });
+  children.push(ui);
+
+  if (stackMode && runtimeStatePath) {
+    await recordStackRuntimeUpdate(runtimeStatePath, {
+      processes: { expoWebPid: ui.pid },
+      expo: { webPort: metroPort },
+    }).catch(() => {});
+  }
+
+  try {
+    await writePidState(uiPaths.statePath, { pid: ui.pid, port: metroPort, uiDir, startedAt: new Date().toISOString() });
+  } catch {
+    // ignore
+  }
+
+  return { ok: true, skipped: false, pid: ui.pid, port: metroPort, proc: ui };
+}

package/scripts/utils/dev_server.mjs

@@ -0,0 +1,183 @@
+import { join, resolve } from 'node:path';
+
+import { ensureDepsInstalled, pmSpawnScript } from './pm.mjs';
+import { applyHappyServerMigrations, ensureHappyServerManagedInfra } from './happy_server_infra.mjs';
+import { waitForServerReady } from './server.mjs';
+import { isTcpPortFree, pickNextFreeTcpPort } from './ports.mjs';
+import { readStackRuntimeStateFile, recordStackRuntimeUpdate } from './stack_runtime_state.mjs';
+import { killProcessGroupOwnedByStack } from './ownership.mjs';
+import { watchDebounced } from './watch.mjs';
+
+function hashStringToInt(s) {
+  let h = 0;
+  const str = String(s ?? '');
+  for (let i = 0; i < str.length; i++) {
+    h = (h * 31 + str.charCodeAt(i)) >>> 0;
+  }
+  return h >>> 0;
+}
+
+export function resolveStackUiDevPortStart({ env = process.env, stackName }) {
+  const baseRaw = (env.HAPPY_STACKS_UI_DEV_PORT_BASE ?? env.HAPPY_LOCAL_UI_DEV_PORT_BASE ?? '8081').toString().trim();
+  const rangeRaw = (env.HAPPY_STACKS_UI_DEV_PORT_RANGE ?? env.HAPPY_LOCAL_UI_DEV_PORT_RANGE ?? '1000').toString().trim();
+  const base = Number(baseRaw);
+  const range = Number(rangeRaw);
+  const b = Number.isFinite(base) ? base : 8081;
+  const r = Number.isFinite(range) && range > 0 ? range : 1000;
+  return b + (hashStringToInt(stackName) % r);
+}
+
+export async function pickDevMetroPort({ startPort, reservedPorts = new Set(), host = '127.0.0.1' } = {}) {
+  const forcedRaw = (process.env.HAPPY_STACKS_UI_DEV_PORT ?? process.env.HAPPY_LOCAL_UI_DEV_PORT ?? '').toString().trim();
+  if (forcedRaw) {
+    const forced = Number(forcedRaw);
+    if (Number.isFinite(forced) && forced > 0) {
+      const ok = await isTcpPortFree(forced, { host });
+      if (ok) return forced;
+    }
+  }
+  return await pickNextFreeTcpPort(startPort, { reservedPorts, host });
+}
+
+export async function startDevServer({
+  serverComponentName,
+  serverDir,
+  autostart,
+  baseEnv,
+  serverPort,
+  internalServerUrl,
+  publicServerUrl,
+  envPath,
+  stackMode,
+  runtimeStatePath,
+  serverAlreadyRunning,
+  restart,
+  children,
+}) {
+  const serverEnv = {
+    ...baseEnv,
+    PORT: String(serverPort),
+    PUBLIC_URL: publicServerUrl,
+    // Avoid noisy failures if a previous run left the metrics port busy.
+    METRICS_ENABLED: baseEnv.METRICS_ENABLED ?? 'false',
+  };
+
+  if (serverComponentName === 'happy-server-light') {
+    const dataDir = baseEnv.HAPPY_SERVER_LIGHT_DATA_DIR?.trim()
+      ? baseEnv.HAPPY_SERVER_LIGHT_DATA_DIR.trim()
+      : join(autostart.baseDir, 'server-light');
+    serverEnv.HAPPY_SERVER_LIGHT_DATA_DIR = dataDir;
+    serverEnv.HAPPY_SERVER_LIGHT_FILES_DIR = baseEnv.HAPPY_SERVER_LIGHT_FILES_DIR?.trim()
+      ? baseEnv.HAPPY_SERVER_LIGHT_FILES_DIR.trim()
+      : join(dataDir, 'files');
+    serverEnv.DATABASE_URL = baseEnv.DATABASE_URL?.trim() ? baseEnv.DATABASE_URL.trim() : `file:${join(dataDir, 'happy-server-light.sqlite')}`;
+  }
+
+  if (serverComponentName === 'happy-server') {
+    const managed = (baseEnv.HAPPY_STACKS_MANAGED_INFRA ?? baseEnv.HAPPY_LOCAL_MANAGED_INFRA ?? '1') !== '0';
+    if (managed) {
+      const infra = await ensureHappyServerManagedInfra({
+        stackName: autostart.stackName,
+        baseDir: autostart.baseDir,
+        serverPort,
+        publicServerUrl,
+        envPath,
+        env: baseEnv,
+      });
+      Object.assign(serverEnv, infra.env);
+    }
+
+    const autoMigrate = (baseEnv.HAPPY_STACKS_PRISMA_MIGRATE ?? baseEnv.HAPPY_LOCAL_PRISMA_MIGRATE ?? '1') !== '0';
+    if (autoMigrate) {
+      await applyHappyServerMigrations({ serverDir, env: serverEnv });
+    }
+  }
+
+  // Ensure server deps exist before any Prisma/docker work.
+  await ensureDepsInstalled(serverDir, serverComponentName);
+
+  const prismaPush = (baseEnv.HAPPY_STACKS_PRISMA_PUSH ?? baseEnv.HAPPY_LOCAL_PRISMA_PUSH ?? '1').toString().trim() !== '0';
+  const serverScript =
+    serverComponentName === 'happy-server'
+      ? 'start'
+      : serverComponentName === 'happy-server-light' && !prismaPush
+        ? 'start'
+        : 'dev';
+
+  // Restart behavior (stack-safe): only kill when we can prove ownership via runtime state.
+  if (restart && stackMode && runtimeStatePath && serverAlreadyRunning) {
+    const st = await readStackRuntimeStateFile(runtimeStatePath);
+    const pid = Number(st?.processes?.serverPid);
+    if (pid > 1) {
+      const res = await killProcessGroupOwnedByStack(pid, { stackName: autostart.stackName, envPath, label: 'server', json: true });
+      if (!res.killed) {
+        // Fail-closed if the port is still occupied.
+        const free = await isTcpPortFree(serverPort, { host: '127.0.0.1' });
+        if (!free) {
+          throw new Error(
+            `[local] restart refused: server port ${serverPort} is occupied and the PID is not provably stack-owned.\n` +
+              `[local] Fix: run 'happys stack stop ${autostart.stackName}' then re-run, or re-run without --restart.`
+          );
+        }
+      }
+    }
+  }
+
+  if (serverAlreadyRunning && !restart) {
+    return { serverEnv, serverScript, serverProc: null };
+  }
+
+  const server = await pmSpawnScript({ label: 'server', dir: serverDir, script: serverScript, env: serverEnv });
+  children.push(server);
+  if (stackMode && runtimeStatePath) {
+    await recordStackRuntimeUpdate(runtimeStatePath, { processes: { serverPid: server.pid } }).catch(() => {});
+  }
+  await waitForServerReady(internalServerUrl);
+  return { serverEnv, serverScript, serverProc: server };
+}
+
+export function watchDevServerAndRestart({
+  enabled,
+  stackMode,
+  serverComponentName,
+  serverDir,
+  serverPort,
+  internalServerUrl,
+  serverScript,
+  serverEnv,
+  runtimeStatePath,
+  stackName,
+  envPath,
+  children,
+  serverProcRef,
+  isShuttingDown,
+}) {
+  if (!enabled) return null;
+
+  // Only watch full server by default; happy-server-light already has a good upstream dev loop.
+  if (serverComponentName !== 'happy-server') return null;
+
+  return watchDebounced({
+    paths: [resolve(serverDir)],
+    debounceMs: 600,
+    onChange: async () => {
+      if (isShuttingDown?.()) return;
+      const pid = Number(serverProcRef?.current?.pid);
+      if (!Number.isFinite(pid) || pid <= 1) return;
+
+      // eslint-disable-next-line no-console
+      console.log('[local] watch: server changed → restarting...');
+      await killProcessGroupOwnedByStack(pid, { stackName, envPath, label: 'server', json: false });
+
+      const next = await pmSpawnScript({ label: 'server', dir: serverDir, script: serverScript, env: serverEnv });
+      children.push(next);
+      serverProcRef.current = next;
+      if (stackMode && runtimeStatePath) {
+        await recordStackRuntimeUpdate(runtimeStatePath, { processes: { serverPid: next.pid } }).catch(() => {});
+      }
+      await waitForServerReady(internalServerUrl);
+      // eslint-disable-next-line no-console
+      console.log(`[local] watch: server restarted (pid=${next.pid}, port=${serverPort})`);
+    },
+  });
+}