happy-stacks 0.1.2 → 0.3.0

package/scripts/utils/auth/dev_key.mjs

@@ -0,0 +1,163 @@
+import { chmod, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { getHappyStacksHomeDir } from '../paths/paths.mjs';
+
+export function getDevAuthKeyPath(env = process.env) {
+  return join(getHappyStacksHomeDir(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/auth/files.mjs

@@ -0,0 +1,56 @@
+import { chmod, copyFile, lstat, symlink, unlink, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import { ensureDir } from '../fs/ops.mjs';
+
+export async function removeFileOrSymlinkIfExists(path) {
+  try {
+    const st = await lstat(path);
+    if (st.isDirectory()) {
+      throw new Error(`[auth] refusing to remove directory path: ${path}`);
+    }
+    await unlink(path);
+    return true;
+  } catch (e) {
+    if (e && typeof e === 'object' && 'code' in e && e.code === 'ENOENT') return false;
+    throw e;
+  }
+}
+
+export async function writeSecretFileIfMissing({ path, secret, force = false }) {
+  if (!force && existsSync(path)) return false;
+  if (force && existsSync(path)) {
+    await removeFileOrSymlinkIfExists(path);
+  }
+  await ensureDir(dirname(path));
+  await writeFile(path, secret, { encoding: 'utf-8', mode: 0o600 });
+  return true;
+}
+
+export async function copyFileIfMissing({ from, to, mode, force = false }) {
+  if (!force && existsSync(to)) return false;
+  if (!existsSync(from)) return false;
+  await ensureDir(dirname(to));
+  // IMPORTANT: if `to` is a symlink and we "overwrite" it, do NOT write through it to the symlink target.
+  if (force && existsSync(to)) {
+    await removeFileOrSymlinkIfExists(to);
+  }
+  await copyFile(from, to);
+  if (mode) {
+    await chmod(to, mode).catch(() => {});
+  }
+  return true;
+}
+
+export async function linkFileIfMissing({ from, to, force = false }) {
+  if (!force && existsSync(to)) return false;
+  if (!existsSync(from)) return false;
+  await ensureDir(dirname(to));
+  if (force && existsSync(to)) {
+    await removeFileOrSymlinkIfExists(to);
+  }
+  await symlink(from, to);
+  return true;
+}
+

package/scripts/utils/auth/handy_master_secret.mjs

@@ -0,0 +1,68 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { parseEnvToObject } from '../env/dotenv.mjs';
+import { resolveStackEnvPath } from '../paths/paths.mjs';
+import { getLegacyHappyBaseDir, isLegacyAuthSourceName } from './sources.mjs';
+import { getEnvValue } from '../env/values.mjs';
+import { readTextIfExists } from '../fs/ops.mjs';
+import { stackExistsSync } from '../stack/stacks.mjs';
+
+export async function resolveHandyMasterSecretFromStack({
+  stackName,
+  requireStackExists = false,
+  allowLegacyAuthSource = true,
+  allowLegacyMainFallback = true,
+} = {}) {
+  const name = String(stackName ?? '').trim() || 'main';
+
+  if (isLegacyAuthSourceName(name)) {
+    if (!allowLegacyAuthSource) {
+      throw new Error(
+        '[auth] legacy auth source is disabled in sandbox mode.\n' +
+          'Reason: it reads from ~/.happy (global user state).\n' +
+          'If you really want this, set: HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1'
+      );
+    }
+    const baseDir = getLegacyHappyBaseDir();
+    const legacySecretPath = join(baseDir, 'server-light', 'handy-master-secret.txt');
+    const secret = await readTextIfExists(legacySecretPath);
+    return secret ? { secret, source: legacySecretPath } : { secret: null, source: null };
+  }
+
+  if (requireStackExists && !stackExistsSync(name)) {
+    throw new Error(`[auth] cannot copy auth: source stack "${name}" does not exist`);
+  }
+
+  const resolved = resolveStackEnvPath(name);
+  const sourceBaseDir = resolved.baseDir;
+  const sourceEnvPath = resolved.envPath;
+  const raw = await readTextIfExists(sourceEnvPath);
+  const env = raw ? parseEnvToObject(raw) : {};
+
+  const inline = getEnvValue(env, 'HANDY_MASTER_SECRET');
+  if (inline) {
+    return { secret: inline, source: `${sourceEnvPath} (HANDY_MASTER_SECRET)` };
+  }
+
+  const secretFile = getEnvValue(env, 'HAPPY_STACKS_HANDY_MASTER_SECRET_FILE');
+  if (secretFile) {
+    const secret = await readTextIfExists(secretFile);
+    if (secret) return { secret, source: secretFile };
+  }
+
+  const dataDir = getEnvValue(env, 'HAPPY_SERVER_LIGHT_DATA_DIR') || join(sourceBaseDir, 'server-light');
+  const secretPath = join(dataDir, 'handy-master-secret.txt');
+  const secret = await readTextIfExists(secretPath);
+  if (secret) return { secret, source: secretPath };
+
+  // Last-resort legacy: if main has never been migrated to stack dirs.
+  if (name === 'main' && allowLegacyMainFallback) {
+    const legacy = join(homedir(), '.happy', 'server-light', 'handy-master-secret.txt');
+    const legacySecret = await readTextIfExists(legacy);
+    if (legacySecret) return { secret: legacySecret, source: legacy };
+  }
+
+  return { secret: null, source: null };
+}
+

package/scripts/utils/auth/login_ux.mjs

@@ -0,0 +1,76 @@
+export function normalizeAuthLoginContext(raw) {
+  const v = String(raw ?? '')
+    .trim()
+    .toLowerCase();
+  if (v === 'selfhost' || v === 'self-host' || v === 'self_host') return 'selfhost';
+  if (v === 'dev' || v === 'developer' || v === 'development') return 'dev';
+  if (v === 'stack') return 'stack';
+  return 'generic';
+}
+
+export function printAuthLoginInstructions({
+  stackName,
+  context = 'generic',
+  webappUrl,
+  webappUrlSource,
+  internalServerUrl,
+  publicServerUrl,
+  rerunCmd,
+}) {
+  const ctx = normalizeAuthLoginContext(context);
+  const title =
+    ctx === 'selfhost'
+      ? '[auth] login (self-host)'
+      : ctx === 'dev'
+        ? '[auth] login (dev)'
+        : ctx === 'stack'
+          ? `[auth] login (stack=${stackName || 'unknown'})`
+          : '[auth] login';
+
+  // eslint-disable-next-line no-console
+  console.log('');
+  // eslint-disable-next-line no-console
+  console.log(title);
+  // eslint-disable-next-line no-console
+  console.log('[auth] steps:');
+  // eslint-disable-next-line no-console
+  console.log('  1) A browser window will open for authentication');
+  // eslint-disable-next-line no-console
+  console.log('  2) Sign in (or create an account if this is your first time)');
+  // eslint-disable-next-line no-console
+  console.log('  3) Approve this terminal/machine connection');
+  // eslint-disable-next-line no-console
+  console.log('  4) Return here — the CLI will finish automatically');
+
+  if (webappUrl) {
+    // eslint-disable-next-line no-console
+    console.log('');
+    // eslint-disable-next-line no-console
+    console.log(`[auth] webapp:   ${webappUrl}${webappUrlSource ? ` (${webappUrlSource})` : ''}`);
+  }
+  if (internalServerUrl) {
+    // eslint-disable-next-line no-console
+    console.log(`[auth] internal: ${internalServerUrl}`);
+  }
+  if (publicServerUrl) {
+    // eslint-disable-next-line no-console
+    console.log(`[auth] public:   ${publicServerUrl}`);
+  }
+
+  if (ctx === 'selfhost') {
+    // eslint-disable-next-line no-console
+    console.log('');
+    // eslint-disable-next-line no-console
+    console.log('[auth] note: this is required so the daemon can register this machine and sync sessions across devices.');
+  }
+
+  // eslint-disable-next-line no-console
+  console.log('');
+  // eslint-disable-next-line no-console
+  console.log('[auth] tips:');
+  // eslint-disable-next-line no-console
+  console.log('- If the browser page does not load, make sure Happy is running and reachable.');
+  // eslint-disable-next-line no-console
+  console.log(`- Re-run anytime: ${rerunCmd || 'happys auth login'}`);
+}
+

package/scripts/utils/auth/sources.mjs

@@ -0,0 +1,12 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function isLegacyAuthSourceName(name) {
+  const s = String(name ?? '').trim().toLowerCase();
+  return s === 'legacy' || s === 'system' || s === 'local-install';
+}
+
+export function getLegacyHappyBaseDir() {
+  return join(homedir(), '.happy');
+}
+

package/scripts/utils/{cli_registry.mjs → cli/cli_registry.mjs}

@@ -20,6 +20,22 @@ export function getHappysRegistry() {
       rootUsage:
         'happys init [--home-dir=PATH] [--workspace-dir=PATH] [--runtime-dir=PATH] [--install-path] [--no-runtime] [--no-bootstrap] [--] [bootstrap args...]',
       description: 'Initialize ~/.happy-stacks (runtime + shims)',
+      hidden: true,
+    },
+    {
+      name: 'setup',
+      kind: 'node',
+      scriptRelPath: 'scripts/setup.mjs',
+      rootUsage: 'happys setup [--profile=selfhost|dev] [--json]',
+      description: 'Guided setup (selfhost or dev)',
+    },
+    {
+      name: 'setup-pr',
+      aliases: ['setupPR', 'setuppr'],
+      kind: 'node',
+      scriptRelPath: 'scripts/setup_pr.mjs',
+      rootUsage: 'happys setup-pr --happy=<pr-url|number> [--happy-cli=<pr-url|number>] [--dev]',
+      description: 'One-shot: set up + run a PR stack (maintainer-friendly)',
     },
     {
       name: 'uninstall',
@@ -42,6 +58,7 @@ export function getHappysRegistry() {
       scriptRelPath: 'scripts/install.mjs',
       rootUsage: 'happys bootstrap [-- ...]',
       description: 'Clone/install components and deps',
+      hidden: true,
     },
     {
       name: 'start',
@@ -71,6 +88,13 @@ export function getHappysRegistry() {
       rootUsage: 'happys build [-- ...]',
       description: 'Build UI bundle',
     },
+    {
+      name: 'lint',
+      kind: 'node',
+      scriptRelPath: 'scripts/lint.mjs',
+      rootUsage: 'happys lint [component...] [--json]',
+      description: 'Run linters for components',
+    },
     {
       name: 'typecheck',
       aliases: ['type-check', 'check-types'],
@@ -79,6 +103,20 @@ export function getHappysRegistry() {
       rootUsage: 'happys typecheck [component...] [--json]',
       description: 'Run TypeScript typechecks for components',
     },
+    {
+      name: 'test',
+      kind: 'node',
+      scriptRelPath: 'scripts/test.mjs',
+      rootUsage: 'happys test [component...] [--json]',
+      description: 'Run tests for components',
+    },
+    {
+      name: 'edison',
+      kind: 'node',
+      scriptRelPath: 'scripts/edison.mjs',
+      rootUsage: 'happys edison [--stack=<name>] -- <edison args...>',
+      description: 'Run Edison with Happy Stacks integration',
+    },
     {
       name: 'migrate',
       kind: 'node',
@@ -100,6 +138,13 @@ export function getHappysRegistry() {
       rootUsage: 'happys doctor [--fix] [--json]',
       description: 'Diagnose/fix local setup',
     },
+    {
+      name: 'tui',
+      kind: 'node',
+      scriptRelPath: 'scripts/tui.mjs',
+      rootUsage: 'happys tui <happys args...> [--json]',
+      description: 'Run happys commands in a split-pane TUI',
+    },
     {
       name: 'self',
       kind: 'node',
@@ -272,6 +317,9 @@ export function renderHappysRootHelp() {
   return [
     'happys - Happy Stacks CLI',
     '',
+    'global flags:',
+    '  --sandbox-dir PATH   Run fully isolated under PATH (no writes to your real ~/.happy-stacks or ~/.happy/stacks)',
+    '',
     'usage:',
     ...usageLines.map((l) => `  ${l}`),
     '',

package/scripts/utils/cli/flags.mjs

@@ -0,0 +1,17 @@
+export function boolFromFlags({ flags, onFlag, offFlag, defaultValue }) {
+  if (flags.has(offFlag)) return false;
+  if (flags.has(onFlag)) return true;
+  return defaultValue;
+}
+
+export function boolFromFlagsOrKv({ flags, kv, onFlag, offFlag, key, defaultValue }) {
+  if (flags.has(offFlag)) return false;
+  if (flags.has(onFlag)) return true;
+  if (key && kv.has(key)) {
+    const raw = String(kv.get(key) ?? '').trim().toLowerCase();
+    if (raw === '1' || raw === 'true' || raw === 'yes' || raw === 'y') return true;
+    if (raw === '0' || raw === 'false' || raw === 'no' || raw === 'n') return false;
+  }
+  return defaultValue;
+}
+

package/scripts/utils/cli/normalize.mjs

@@ -0,0 +1,16 @@
+export function normalizeProfile(raw) {
+  const v = (raw ?? '').trim().toLowerCase();
+  if (!v) return '';
+  if (v === 'selfhost' || v === 'self-host' || v === 'self_host' || v === 'host') return 'selfhost';
+  if (v === 'dev' || v === 'developer' || v === 'develop' || v === 'development') return 'dev';
+  return '';
+}
+
+export function normalizeServerComponent(raw) {
+  const v = (raw ?? '').trim().toLowerCase();
+  if (!v) return '';
+  if (v === 'light' || v === 'server-light' || v === 'happy-server-light') return 'happy-server-light';
+  if (v === 'server' || v === 'full' || v === 'happy-server') return 'happy-server';
+  return '';
+}
+

package/scripts/utils/{smoke_help.mjs → cli/smoke_help.mjs}

@@ -6,8 +6,8 @@ import { dirname } from 'node:path';
 import { getHappysRegistry } from './cli_registry.mjs';
 
 function cliRootDir() {
-  // scripts/utils/* -> scripts -> repo root
-  return dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+  // scripts/utils/cli/* -> scripts/utils -> scripts -> repo root
+  return dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))));
 }
 
 function runOrThrow(label, args) {

package/scripts/utils/{wizard.mjs → cli/wizard.mjs}

@@ -1,5 +1,5 @@
 import { createInterface } from 'node:readline/promises';
-import { listWorktreeSpecs } from './worktrees.mjs';
+import { listWorktreeSpecs } from '../git/worktrees.mjs';
 
 export function isTty() {
   return Boolean(process.stdin.isTTY && process.stdout.isTTY);

package/scripts/utils/crypto/tokens.mjs

@@ -0,0 +1,14 @@
+import { randomBytes } from 'node:crypto';
+
+export function base64Url(buf) {
+  return Buffer.from(buf)
+    .toString('base64')
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replaceAll('=', '');
+}
+
+export function randomToken(lenBytes = 24) {
+  return base64Url(randomBytes(lenBytes));
+}
+

package/scripts/utils/dev/daemon.mjs

@@ -0,0 +1,104 @@
+import { resolve } from 'node:path';
+
+import { ensureCliBuilt, ensureDepsInstalled } from '../proc/pm.mjs';
+import { watchDebounced } from '../proc/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;
+      }
+    },
+  });
+}