happy-stacks 0.2.0 → 0.4.0

package/scripts/utils/server/validate.mjs

@@ -0,0 +1,88 @@
+import { readFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { getComponentsDir } from '../paths/paths.mjs';
+
+function isInside(path, dir) {
+  const p = resolve(path);
+  const d = resolve(dir);
+  return p === d || p.startsWith(d.endsWith(sep) ? d : d + sep);
+}
+
+export function detectServerComponentDirMismatch({ rootDir, serverComponentName, serverDir }) {
+  const componentsDir = getComponentsDir(rootDir);
+
+  const other = serverComponentName === 'happy-server-light' ? 'happy-server' : serverComponentName === 'happy-server' ? 'happy-server-light' : null;
+  if (!other) {
+    return null;
+  }
+
+  const otherRepo = resolve(componentsDir, other);
+  const otherWts = resolve(componentsDir, '.worktrees', other);
+
+  if (isInside(serverDir, otherRepo) || isInside(serverDir, otherWts)) {
+    return { expected: serverComponentName, actual: other, serverDir };
+  }
+
+  return null;
+}
+
+export function assertServerComponentDirMatches({ rootDir, serverComponentName, serverDir }) {
+  const mismatch = detectServerComponentDirMismatch({ rootDir, serverComponentName, serverDir });
+  if (!mismatch) {
+    return;
+  }
+
+  const hint =
+    mismatch.expected === 'happy-server-light'
+      ? 'Fix: either switch flavor (`happys srv use happy-server`) or switch the active checkout for happy-server-light (`happys wt use happy-server-light default` or a worktree under .worktrees/happy-server-light/).'
+      : 'Fix: either switch flavor (`happys srv use happy-server-light`) or switch the active checkout for happy-server (`happys wt use happy-server default` or a worktree under .worktrees/happy-server/).';
+
+  throw new Error(
+    `[server] server component dir mismatch:\n` +
+      `- selected flavor: ${mismatch.expected}\n` +
+      `- but HAPPY_STACKS_COMPONENT_DIR_* points inside: ${mismatch.actual}\n` +
+      `- path: ${mismatch.serverDir}\n` +
+      `${hint}`
+  );
+}
+
+function detectPrismaProvider(schemaText) {
+  // Best-effort parse of:
+  // datasource db { provider = "sqlite" ... }
+  const m = schemaText.match(/datasource\s+db\s*\{[\s\S]*?\bprovider\s*=\s*\"([a-zA-Z0-9_-]+)\"/m);
+  return m?.[1] ?? '';
+}
+
+export function assertServerPrismaProviderMatches({ serverComponentName, serverDir }) {
+  const schemaPath = join(serverDir, 'prisma', 'schema.prisma');
+  let schemaText = '';
+  try {
+    schemaText = readFileSync(schemaPath, 'utf-8');
+  } catch {
+    // If it doesn't exist, skip validation; not every server component necessarily uses Prisma.
+    return;
+  }
+
+  const provider = detectPrismaProvider(schemaText);
+  if (!provider) {
+    return;
+  }
+
+  if (serverComponentName === 'happy-server-light' && provider !== 'sqlite') {
+    throw new Error(
+      `[server] happy-server-light expects Prisma datasource provider \"sqlite\", but found \"${provider}\" in:\n` +
+        `- ${schemaPath}\n` +
+        `This usually means you're pointing happy-server-light at an upstream happy-server checkout/PR (Postgres).\n` +
+        `Fix: either switch server flavor to happy-server, or point happy-server-light at a fork checkout that keeps sqlite support.`
+    );
+  }
+
+  if (serverComponentName === 'happy-server' && provider === 'sqlite') {
+    throw new Error(
+      `[server] happy-server expects Prisma datasource provider \"postgresql\", but found \"sqlite\" in:\n` +
+        `- ${schemaPath}\n` +
+        `Fix: either switch server flavor to happy-server-light, or point happy-server at the full-server checkout.`
+    );
+  }
+}
+

package/scripts/utils/service/autostart_darwin.mjs

@@ -0,0 +1,182 @@
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+
+import { runCapture } from '../proc/proc.mjs';
+import { getDefaultAutostartPaths } from '../paths/paths.mjs';
+import { resolveInstalledCliRoot, resolveInstalledPath } from '../paths/runtime.mjs';
+import { getCanonicalHomeDir } from '../env/config.mjs';
+
+function plistPathForLabel(label) {
+  return join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
+}
+
+function splitPath(p) {
+  return String(p ?? '')
+    .split(':')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+export function buildLaunchdPath({ execPath = process.execPath, basePath = process.env.PATH } = {}) {
+  // launchd starts with a minimal environment; ensure common tool paths exist,
+  // and include the current Node binary directory so shell shims that exec `node`
+  // still work (e.g. nvm-managed installs).
+  const nodeDir = execPath ? dirname(execPath) : '';
+  const defaults = splitPath('/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin');
+  const fromNode = nodeDir ? [nodeDir] : [];
+  const fromEnv = splitPath(basePath);
+
+  const seen = new Set();
+  const out = [];
+  for (const part of [...fromNode, ...fromEnv, ...defaults]) {
+    if (seen.has(part)) continue;
+    seen.add(part);
+    out.push(part);
+  }
+  return out.join(':') || '/usr/bin:/bin:/usr/sbin:/sbin';
+}
+
+export function pickLaunchdProgramArgs({ rootDir, execPath = process.execPath } = {}) {
+  // Prefer the stable shim under the canonical home dir (used by selfhost installs).
+  // This keeps the LaunchAgent pointing at a stable path while allowing runtime updates.
+  const happysShim = join(getCanonicalHomeDir(), 'bin', 'happys');
+  if (existsSync(happysShim)) {
+    return [happysShim, 'start'];
+  }
+  // Fallback: call the Node entry directly (works in repo-only installs).
+  return [execPath, resolveInstalledPath(rootDir, 'bin/happys.mjs'), 'start'];
+}
+
+function xmlEscape(s) {
+  return String(s ?? '')
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}
+
+function plistXml({ label, programArgs, env = {}, stdoutPath, stderrPath, workingDirectory }) {
+  const envEntries = Object.entries(env ?? {}).filter(([k, v]) => String(k).trim() && String(v ?? '').trim());
+  const programArgsXml = programArgs.map((a) => `      <string>${xmlEscape(a)}</string>`).join('\n');
+  const envXml = envEntries
+    .map(([k, v]) => `      <key>${xmlEscape(k)}</key>\n      <string>${xmlEscape(v)}</string>`)
+    .join('\n');
+  const workingDirXml = workingDirectory
+    ? `\n    <key>WorkingDirectory</key>\n    <string>${xmlEscape(workingDirectory)}</string>\n`
+    : '\n';
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>${xmlEscape(label)}</string>
+
+    <key>ProgramArguments</key>
+    <array>
+${programArgsXml}
+    </array>
+
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+${workingDirXml}    <key>StandardOutPath</key>
+    <string>${xmlEscape(stdoutPath)}</string>
+    <key>StandardErrorPath</key>
+    <string>${xmlEscape(stderrPath)}</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+${envXml}
+    </dict>
+  </dict>
+</plist>
+`;
+}
+
+export async function ensureMacAutostartEnabled({ rootDir, label, env }) {
+  if (process.platform !== 'darwin') {
+    throw new Error('[local] macOS autostart is only supported on Darwin');
+  }
+  const l = String(label ?? '').trim();
+  if (!l) throw new Error('[local] missing launchd label');
+
+  const plistPath = plistPathForLabel(l);
+  const { stdoutPath, stderrPath } = getDefaultAutostartPaths();
+  await mkdir(dirname(plistPath), { recursive: true }).catch(() => {});
+  await mkdir(dirname(stdoutPath), { recursive: true }).catch(() => {});
+  await mkdir(dirname(stderrPath), { recursive: true }).catch(() => {});
+
+  const programArgs = pickLaunchdProgramArgs({ rootDir, execPath: process.execPath });
+  const mergedEnv = {
+    ...(env ?? {}),
+    // Ensure a reasonable PATH for subprocesses (git/docker/etc) in launchd’s minimal environment.
+    // Also ensure Node is on PATH for shell shims that exec `node` (common with nvm installs).
+    PATH: buildLaunchdPath({ execPath: process.execPath, basePath: process.env.PATH }),
+  };
+
+  const xml = plistXml({
+    label: l,
+    programArgs,
+    env: mergedEnv,
+    stdoutPath,
+    stderrPath,
+    workingDirectory: resolveInstalledCliRoot(rootDir),
+  });
+
+  const tmp = join(dirname(plistPath), `.tmp.${l}.${Date.now()}.plist`);
+  await writeFile(tmp, xml, 'utf-8');
+  await rename(tmp, plistPath);
+
+  // Best-effort load/enable; `scripts/service.mjs` has a more robust bootstrap fallback.
+  try {
+    await runCapture('launchctl', ['load', '-w', plistPath]);
+  } catch {
+    // ignore
+  }
+}
+
+export async function ensureMacAutostartDisabled({ label }) {
+  if (process.platform !== 'darwin') {
+    return;
+  }
+  const l = String(label ?? '').trim();
+  if (!l) return;
+  const plistPath = plistPathForLabel(l);
+
+  const uidRaw = Number(process.env.UID);
+  const uid = Number.isFinite(uidRaw) ? uidRaw : null;
+
+  try {
+    await runCapture('launchctl', ['unload', '-w', plistPath]);
+  } catch {
+    // ignore
+  }
+  try {
+    await runCapture('launchctl', ['unload', plistPath]);
+  } catch {
+    // ignore
+  }
+  if (uid != null) {
+    try {
+      await runCapture('launchctl', ['disable', `gui/${uid}/${l}`]);
+    } catch {
+      // ignore
+    }
+    try {
+      await runCapture('launchctl', ['bootout', `gui/${uid}`, plistPath]);
+    } catch {
+      // ignore
+    }
+  }
+  try {
+    await runCapture('launchctl', ['remove', l]);
+  } catch {
+    // ignore
+  }
+}
+

package/scripts/utils/service/autostart_darwin.test.mjs

@@ -0,0 +1,50 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { buildLaunchdPath, pickLaunchdProgramArgs } from './autostart_darwin.mjs';
+
+test('buildLaunchdPath includes node dir and common tool paths', () => {
+  const execPath = '/Users/me/.nvm/versions/node/v22.14.0/bin/node';
+  const p = buildLaunchdPath({ execPath, basePath: '' });
+
+  assert.ok(p.includes('/Users/me/.nvm/versions/node/v22.14.0/bin'), 'includes node dir');
+  assert.ok(p.includes('/usr/bin'), 'includes /usr/bin');
+  assert.ok(p.includes('/bin'), 'includes /bin');
+});
+
+test('pickLaunchdProgramArgs uses stable happys shim when present', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-home-'));
+  const shim = join(dir, 'bin', 'happys');
+  await mkdir(join(dir, 'bin'), { recursive: true });
+  await writeFile(shim, '#!/bin/sh\necho ok\n', { encoding: 'utf-8' });
+
+  // Temporarily point canonical home at our temp dir via env var used by getCanonicalHomeDirFromEnv().
+  const prev = process.env.HAPPY_STACKS_CANONICAL_HOME_DIR;
+  process.env.HAPPY_STACKS_CANONICAL_HOME_DIR = dir;
+  try {
+    const args = pickLaunchdProgramArgs({ rootDir: '/fake/root' });
+    assert.deepEqual(args, [shim, 'start']);
+  } finally {
+    if (prev == null) delete process.env.HAPPY_STACKS_CANONICAL_HOME_DIR;
+    else process.env.HAPPY_STACKS_CANONICAL_HOME_DIR = prev;
+  }
+});
+
+test('pickLaunchdProgramArgs falls back to node + happys.mjs when shim missing', () => {
+  const prev = process.env.HAPPY_STACKS_CANONICAL_HOME_DIR;
+  process.env.HAPPY_STACKS_CANONICAL_HOME_DIR = '/definitely-not-a-real-path';
+  try {
+    const execPath = '/usr/local/bin/node';
+    const args = pickLaunchdProgramArgs({ rootDir: '/cli/root', execPath });
+    assert.equal(args[0], execPath);
+    assert.ok(String(args[1]).endsWith('/bin/happys.mjs'));
+    assert.equal(args[2], 'start');
+  } finally {
+    if (prev == null) delete process.env.HAPPY_STACKS_CANONICAL_HOME_DIR;
+    else process.env.HAPPY_STACKS_CANONICAL_HOME_DIR = prev;
+  }
+});
+

package/scripts/utils/stack/context.mjs

@@ -0,0 +1,23 @@
+import { getStackName, resolveStackEnvPath } from '../paths/paths.mjs';
+import { getStackRuntimeStatePath } from './runtime_state.mjs';
+
+export function resolveStackContext({ env = process.env, autostart = null } = {}) {
+  const explicitStack = (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim();
+  const stackName = explicitStack || (autostart?.stackName ?? '') || getStackName(env);
+  const stackMode = Boolean(explicitStack);
+
+  const envPath =
+    (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString().trim() ||
+    resolveStackEnvPath(stackName, env).envPath;
+
+  const runtimeStatePath =
+    (env.HAPPY_STACKS_RUNTIME_STATE_PATH ?? env.HAPPY_LOCAL_RUNTIME_STATE_PATH ?? '').toString().trim() ||
+    getStackRuntimeStatePath(stackName);
+
+  const explicitEphemeral =
+    (env.HAPPY_STACKS_EPHEMERAL_PORTS ?? env.HAPPY_LOCAL_EPHEMERAL_PORTS ?? '').toString().trim() === '1';
+  const ephemeral = explicitEphemeral || (stackMode && stackName !== 'main');
+
+  return { stackMode, stackName, envPath, runtimeStatePath, ephemeral };
+}
+

package/scripts/utils/stack/dirs.mjs

@@ -0,0 +1,27 @@
+import { join } from 'node:path';
+
+import { expandHome } from '../paths/canonical_home.mjs';
+import { getDefaultAutostartPaths } from '../paths/paths.mjs';
+
+export function getCliHomeDirFromEnvOrDefault({ stackBaseDir, env }) {
+  const fromEnv = (env?.HAPPY_STACKS_CLI_HOME_DIR ?? env?.HAPPY_LOCAL_CLI_HOME_DIR ?? '').trim();
+  return fromEnv || join(stackBaseDir, 'cli');
+}
+
+export function getServerLightDataDirFromEnvOrDefault({ stackBaseDir, env }) {
+  const fromEnv = (env?.HAPPY_SERVER_LIGHT_DATA_DIR ?? '').trim();
+  return fromEnv || join(stackBaseDir, 'server-light');
+}
+
+export function resolveCliHomeDir(env = process.env) {
+  const fromExplicit = (env.HAPPY_HOME_DIR ?? '').trim();
+  if (fromExplicit) {
+    return expandHome(fromExplicit);
+  }
+  const fromStacks = (env.HAPPY_STACKS_CLI_HOME_DIR ?? env.HAPPY_LOCAL_CLI_HOME_DIR ?? '').trim();
+  if (fromStacks) {
+    return expandHome(fromStacks);
+  }
+  return join(getDefaultAutostartPaths().baseDir, 'cli');
+}
+

package/scripts/utils/stack/editor_workspace.mjs

@@ -0,0 +1,152 @@
+import { join, resolve } from 'node:path';
+import { writeFile } from 'node:fs/promises';
+
+import { expandHome } from '../paths/canonical_home.mjs';
+import { getComponentDir, getWorkspaceDir, resolveStackEnvPath } from '../paths/paths.mjs';
+import { ensureDir } from '../fs/ops.mjs';
+import { getEnvValueAny } from '../env/values.mjs';
+import { readEnvObjectFromFile } from '../env/read.mjs';
+import { resolveCommandPath } from '../proc/commands.mjs';
+import { run, runCapture } from '../proc/proc.mjs';
+import { getCliHomeDirFromEnvOrDefault } from './dirs.mjs';
+
+function resolveWorkspaceDirFromStackEnv({ rootDir, stackEnv }) {
+  const raw = getEnvValueAny(stackEnv, ['HAPPY_STACKS_WORKSPACE_DIR', 'HAPPY_LOCAL_WORKSPACE_DIR']);
+  if (!raw) {
+    return getWorkspaceDir(rootDir, stackEnv);
+  }
+  const expanded = expandHome(raw);
+  return expanded.startsWith('/') ? expanded : resolve(rootDir, expanded);
+}
+
+function resolveComponentDirFromStackEnv({ rootDir, stackEnv, keys, component }) {
+  const raw = getEnvValueAny(stackEnv, keys);
+  if (!raw) return getComponentDir(rootDir, component, stackEnv);
+  const expanded = expandHome(raw);
+  if (expanded.startsWith('/')) return expanded;
+  const workspaceDir = resolveWorkspaceDirFromStackEnv({ rootDir, stackEnv });
+  return resolve(workspaceDir, expanded);
+}
+
+export async function isCursorInstalled({ cwd, env } = {}) {
+  if (await resolveCommandPath('cursor', { cwd, env })) return true;
+  if (process.platform !== 'darwin') return false;
+  try {
+    await runCapture('open', ['-Ra', 'Cursor'], { cwd, env });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function openWorkspaceInEditor({ rootDir, editor, workspacePath }) {
+  if (editor === 'code') {
+    const codePath = await resolveCommandPath('code', { cwd: rootDir, env: process.env });
+    if (!codePath) {
+      throw new Error(
+        "[stack] VS Code CLI 'code' not found on PATH. In VS Code: Cmd+Shift+P → 'Shell Command: Install code command in PATH'."
+      );
+    }
+    await run(codePath, ['-n', workspacePath], { cwd: rootDir, env: process.env, stdio: 'inherit' });
+    return;
+  }
+
+  const cursorPath = await resolveCommandPath('cursor', { cwd: rootDir, env: process.env });
+  if (cursorPath) {
+    try {
+      await run(cursorPath, ['-n', workspacePath], { cwd: rootDir, env: process.env, stdio: 'inherit' });
+    } catch {
+      await run(cursorPath, [workspacePath], { cwd: rootDir, env: process.env, stdio: 'inherit' });
+    }
+    return;
+  }
+
+  if (process.platform === 'darwin') {
+    // Cursor installed but CLI missing is common on macOS.
+    await run('open', ['-na', 'Cursor', workspacePath], { cwd: rootDir, env: process.env, stdio: 'inherit' });
+    return;
+  }
+
+  throw new Error("[stack] Cursor CLI 'cursor' not found on PATH (and non-macOS fallback is unavailable).");
+}
+
+export async function writeStackCodeWorkspace({
+  rootDir,
+  stackName,
+  includeStackDir,
+  includeAllComponents,
+  includeCliHome,
+}) {
+  const { baseDir, envPath } = resolveStackEnvPath(stackName);
+  const stackEnv = await readEnvObjectFromFile(envPath);
+
+  const serverComponent =
+    getEnvValueAny(stackEnv, ['HAPPY_STACKS_SERVER_COMPONENT', 'HAPPY_LOCAL_SERVER_COMPONENT']) || 'happy-server-light';
+
+  const selectedComponents = includeAllComponents
+    ? ['happy', 'happy-cli', 'happy-server-light', 'happy-server']
+    : ['happy', 'happy-cli', serverComponent];
+
+  const componentSpecs = [
+    { component: 'happy', keys: ['HAPPY_STACKS_COMPONENT_DIR_HAPPY', 'HAPPY_LOCAL_COMPONENT_DIR_HAPPY'] },
+    { component: 'happy-cli', keys: ['HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI', 'HAPPY_LOCAL_COMPONENT_DIR_HAPPY_CLI'] },
+    {
+      component: 'happy-server-light',
+      keys: ['HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT', 'HAPPY_LOCAL_COMPONENT_DIR_HAPPY_SERVER_LIGHT'],
+    },
+    { component: 'happy-server', keys: ['HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER', 'HAPPY_LOCAL_COMPONENT_DIR_HAPPY_SERVER'] },
+  ];
+  const byName = new Map(componentSpecs.map((c) => [c.component, c.keys]));
+
+  const folders = [];
+  if (includeStackDir) {
+    folders.push({ name: `stack:${stackName}`, path: baseDir });
+  }
+  if (includeCliHome) {
+    const cliHomeDir = getCliHomeDirFromEnvOrDefault({ stackBaseDir: baseDir, env: stackEnv });
+    folders.push({ name: `cli:${stackName}`, path: expandHome(cliHomeDir) });
+  }
+  for (const component of selectedComponents) {
+    const keys = byName.get(component) ?? [];
+    const dir = resolveComponentDirFromStackEnv({ rootDir, stackEnv, keys, component });
+    folders.push({ name: component, path: dir });
+  }
+
+  // Deduplicate by path (can happen if multiple components are pointed at the same dir).
+  const uniqFolders = folders.filter((f, i, arr) => arr.findIndex((x) => x.path === f.path) === i);
+
+  await ensureDir(baseDir);
+  const workspacePath = join(baseDir, `stack.${stackName}.code-workspace`);
+  const payload = {
+    folders: uniqFolders,
+    settings: {
+      'search.exclude': {
+        '**/node_modules/**': true,
+        '**/.git/**': true,
+        '**/logs/**': true,
+        '**/cli/logs/**': true,
+      },
+      'files.watcherExclude': {
+        '**/node_modules/**': true,
+        '**/.git/**': true,
+        '**/logs/**': true,
+        '**/cli/logs/**': true,
+      },
+    },
+  };
+  await writeFile(workspacePath, JSON.stringify(payload, null, 2) + '\n', 'utf-8');
+
+  return {
+    workspacePath,
+    baseDir,
+    envPath,
+    serverComponent,
+    folders: uniqFolders,
+    flags: {
+      includeStackDir: Boolean(includeStackDir),
+      includeCliHome: Boolean(includeCliHome),
+      includeAllComponents: Boolean(includeAllComponents),
+    },
+  };
+}
+

package/scripts/utils/stack/names.mjs

@@ -0,0 +1,12 @@
+export function sanitizeStackName(raw, { fallback = 'stack', maxLen = 64 } = {}) {
+  const s = String(raw ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+/, '')
+    .replace(/-+$/, '');
+  const out = s || String(fallback ?? 'stack');
+  return Number.isFinite(maxLen) && maxLen > 0 ? out.slice(0, maxLen) : out;
+}
+

package/scripts/utils/stack/pr_stack_name.mjs

@@ -0,0 +1,16 @@
+import { parseGithubPullRequest } from '../git/refs.mjs';
+import { sanitizeStackName } from './names.mjs';
+
+export function inferPrStackBaseName({ happy, happyCli, server, serverLight, fallback = 'pr' }) {
+  const parts = [];
+  const hn = parseGithubPullRequest(happy)?.number ?? null;
+  const cn = parseGithubPullRequest(happyCli)?.number ?? null;
+  const sn = parseGithubPullRequest(server)?.number ?? null;
+  const sln = parseGithubPullRequest(serverLight)?.number ?? null;
+  if (hn) parts.push(`happy${hn}`);
+  if (cn) parts.push(`cli${cn}`);
+  if (sn) parts.push(`server${sn}`);
+  if (sln) parts.push(`light${sln}`);
+  return sanitizeStackName(parts.length ? `pr-${parts.join('-')}` : fallback, { fallback, maxLen: 64 });
+}
+

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
+  }
+}
+