happy-stacks 0.1.0 → 0.2.0

package/scripts/ui_gateway.mjs

@@ -0,0 +1,248 @@
+import './utils/env.mjs';
+import http from 'node:http';
+import net from 'node:net';
+import { extname, resolve, sep } from 'node:path';
+import { readFile, stat } from 'node:fs/promises';
+
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+
+function usage() {
+  return [
+    '[ui-gateway] usage:',
+    '  node scripts/ui_gateway.mjs --port=<port> --backend-url=<url> --minio-port=<port> --bucket=<name> [--ui-dir=<path>] [--no-ui]',
+    '',
+    'Reverse-proxy gateway that can optionally serve the built Happy web UI at /.',
+    '',
+    'Always proxies:',
+    '- /v1/* and /health to backend-url',
+    '- /v1/updates websocket upgrades to backend-url (socket.io)',
+    '- /files/* to local Minio (http://127.0.0.1:<minio-port>/<bucket>/...)',
+  ].join('\n');
+}
+
+function normalizePublicPath(path) {
+  const p = String(path ?? '').replace(/\\/g, '/').replace(/^\/+/, '');
+  const parts = p.split('/').filter(Boolean);
+  if (parts.some((part) => part === '..')) {
+    throw new Error('Invalid path');
+  }
+  if (p.includes(':') || p.startsWith('/')) {
+    throw new Error('Invalid path');
+  }
+  return parts.join('/');
+}
+
+function contentTypeForExt(ext) {
+  const e = ext.toLowerCase();
+  if (e === '.html') return 'text/html; charset=utf-8';
+  if (e === '.js') return 'text/javascript; charset=utf-8';
+  if (e === '.css') return 'text/css; charset=utf-8';
+  if (e === '.json') return 'application/json; charset=utf-8';
+  if (e === '.svg') return 'image/svg+xml';
+  if (e === '.ico') return 'image/x-icon';
+  if (e === '.wasm') return 'application/wasm';
+  if (e === '.ttf') return 'font/ttf';
+  if (e === '.woff') return 'font/woff';
+  if (e === '.woff2') return 'font/woff2';
+  if (e === '.png') return 'image/png';
+  if (e === '.jpg' || e === '.jpeg') return 'image/jpeg';
+  if (e === '.webp') return 'image/webp';
+  if (e === '.gif') return 'image/gif';
+  return 'application/octet-stream';
+}
+
+async function sendUiFile({ uiRoot, relPath, res }) {
+  const candidate = resolve(uiRoot, relPath);
+  if (!(candidate === uiRoot || candidate.startsWith(uiRoot + sep))) {
+    res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end('Not found');
+    return;
+  }
+  const bytes = await readFile(candidate);
+  const ext = extname(candidate);
+  const isHtml = ext.toLowerCase() === '.html';
+  res.setHeader('content-type', contentTypeForExt(ext));
+  if (isHtml) {
+    res.setHeader('cache-control', 'no-cache');
+  } else {
+    res.setHeader('cache-control', 'public, max-age=31536000, immutable');
+  }
+  res.end(bytes);
+}
+
+async function sendIndex({ uiRoot, res }) {
+  const indexPath = resolve(uiRoot, 'index.html');
+  const html = (await readFile(indexPath, 'utf-8')) + '\n<!-- Welcome to Happy Server! -->\n';
+  res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-cache' });
+  res.end(html);
+}
+
+function proxyHttp({ target, req, res, rewritePath = (p) => p }) {
+  const url = new URL(target);
+  const method = req.method || 'GET';
+  const headers = { ...req.headers };
+  // Let Node compute correct host
+  delete headers.host;
+
+  const upstream = http.request(
+    {
+      protocol: url.protocol,
+      hostname: url.hostname,
+      port: url.port,
+      method,
+      path: rewritePath(req.url || '/'),
+      headers,
+    },
+    (up) => {
+      res.writeHead(up.statusCode || 502, up.headers);
+      up.pipe(res);
+    }
+  );
+  upstream.on('error', () => {
+    res.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end('Bad gateway');
+  });
+  req.pipe(upstream);
+}
+
+function proxyUpgrade({ target, req, socket, head }) {
+  const url = new URL(target);
+  const port = url.port ? Number(url.port) : url.protocol === 'https:' ? 443 : 80;
+
+  const upstream = net.connect(port, url.hostname, () => {
+    const lines = [`${req.method} ${req.url} HTTP/${req.httpVersion}`];
+    for (let i = 0; i < req.rawHeaders.length; i += 2) {
+      lines.push(`${req.rawHeaders[i]}: ${req.rawHeaders[i + 1]}`);
+    }
+    lines.push('', '');
+    upstream.write(lines.join('\r\n'));
+    if (head?.length) upstream.write(head);
+    socket.pipe(upstream).pipe(socket);
+  });
+  upstream.on('error', () => {
+    try {
+      socket.destroy();
+    } catch {
+      // ignore
+    }
+  });
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags, kv } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+  if (wantsHelp(argv, { flags })) {
+    printResult({ json, data: { ok: true }, text: usage() });
+    return;
+  }
+
+  const portRaw = (kv.get('--port') ?? '').trim();
+  const backendUrl = (kv.get('--backend-url') ?? '').trim();
+  const minioPortRaw = (kv.get('--minio-port') ?? '').trim();
+  const bucket = (kv.get('--bucket') ?? '').trim();
+  const serveUi = !flags.has('--no-ui') && (process.env.HAPPY_LOCAL_SERVE_UI ?? '1') !== '0';
+  const uiDir = serveUi ? (kv.get('--ui-dir') ?? '').trim() : '';
+
+  const port = portRaw ? Number(portRaw) : NaN;
+  const minioPort = minioPortRaw ? Number(minioPortRaw) : NaN;
+
+  if (!backendUrl || !bucket || !Number.isFinite(port) || port <= 0 || !Number.isFinite(minioPort) || minioPort <= 0) {
+    throw new Error(usage());
+  }
+
+  const uiRoot = uiDir ? resolve(uiDir) : '';
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      const url = req.url || '/';
+
+      // API + health proxy
+      if (url.startsWith('/v1/') || url === '/health' || url === '/metrics' || url.startsWith('/v2/')) {
+        proxyHttp({ target: backendUrl, req, res });
+        return;
+      }
+
+      // Public files proxy (Minio path-style)
+      if (url.startsWith('/files/')) {
+        proxyHttp({
+          target: `http://127.0.0.1:${minioPort}`,
+          req,
+          res,
+          rewritePath: (p) => {
+            const raw = p.replace(/^\/files\/?/, '');
+            const safe = normalizePublicPath(raw);
+            return `/${encodeURIComponent(bucket)}/${safe}`;
+          },
+        });
+        return;
+      }
+
+      // UI static
+      if (url === '/' || url === '/ui' || url === '/ui/') {
+        if (uiRoot) {
+          await sendIndex({ uiRoot, res });
+          return;
+        }
+        res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-cache' });
+        res.end('Welcome to Happy Server!');
+        return;
+      }
+      if (url.startsWith('/ui/')) {
+        res.writeHead(302, { location: '/' });
+        res.end();
+        return;
+      }
+
+      if (uiRoot) {
+        const rel = normalizePublicPath(decodeURIComponent(url));
+        const candidate = resolve(uiRoot, rel);
+        const exists = candidate === uiRoot || candidate.startsWith(uiRoot + sep) ? await stat(candidate).then(() => true).catch(() => false) : false;
+        if (exists) {
+          await sendUiFile({ uiRoot, relPath: rel, res });
+          return;
+        }
+
+        // SPA fallback
+        await sendIndex({ uiRoot, res });
+        return;
+      }
+
+      res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+      res.end('Not found');
+    } catch {
+      res.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' });
+      res.end('Internal error');
+    }
+  });
+
+  server.on('upgrade', (req, socket, head) => {
+    try {
+      const url = req.url || '';
+      // socket.io upgrades for realtime updates
+      if (url.startsWith('/v1/updates')) {
+        proxyUpgrade({ target: backendUrl, req, socket, head });
+        return;
+      }
+      socket.destroy();
+    } catch {
+      try {
+        socket.destroy();
+      } catch {
+        // ignore
+      }
+    }
+  });
+
+  await new Promise((resolvePromise) => server.listen({ port, host: '0.0.0.0' }, resolvePromise));
+  // eslint-disable-next-line no-console
+  console.log(`[ui-gateway] ready on http://127.0.0.1:${port}`);
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error(err);
+  process.exit(1);
+});
+

package/scripts/uninstall.mjs

@@ -2,18 +2,16 @@ import './utils/env.mjs';
 
 import { rm } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
-import { parseArgs } from './utils/args.mjs';
-import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
-import { getHappyStacksHomeDir, getRootDir } from './utils/paths.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { expandHome } from './utils/canonical_home.mjs';
+import { getHappyStacksHomeDir, getRootDir, getStacksStorageRoot } from './utils/paths.mjs';
 import { getRuntimeDir } from './utils/runtime.mjs';
-
-function expandHome(p) {
-  return p.replace(/^~(?=\/)/, homedir());
-}
+import { getCanonicalHomeEnvPath } from './utils/config.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
 
 function resolveWorkspaceDir({ rootDir, homeDir }) {
   // Uninstall should never default to deleting the repo root (getWorkspaceDir() can fall back to cliRootDir).
@@ -69,13 +67,14 @@ async function main() {
   if (wantsHelp(argv, { flags }) || argv.includes('help')) {
     printResult({
       json,
-      data: { flags: ['--remove-workspace', '--remove-stacks', '--yes'], json: true },
+      data: { flags: ['--remove-workspace', '--remove-stacks', '--yes', '--global'], json: true },
       text: [
         '[uninstall] usage:',
         '  happys uninstall [--json]   # dry-run',
         '  happys uninstall --yes [--json]',
         '  happys uninstall --remove-workspace --yes',
         '  happys uninstall --remove-stacks --yes',
+        '  happys uninstall --global --yes   # also remove global OS integrations (services/SwiftBar) even in sandbox mode',
         '',
         'notes:',
         '  - default removes: runtime, shims, cache, SwiftBar assets + plugin files, and LaunchAgent services',
@@ -93,11 +92,12 @@ async function main() {
   const yes = flags.has('--yes');
   const removeWorkspace = flags.has('--remove-workspace');
   const removeStacks = flags.has('--remove-stacks');
+  const allowGlobal = flags.has('--global') || sandboxAllowsGlobalSideEffects();
 
   const dryRun = !yes;
 
   // 1) Stop/uninstall services best-effort.
-  if (!dryRun) {
+  if (!dryRun && (!isSandboxed() || allowGlobal)) {
     try {
       spawnSync(process.execPath, [join(rootDir, 'scripts', 'service.mjs'), 'uninstall'], {
         stdio: json ? 'ignore' : 'inherit',
@@ -110,9 +110,15 @@ async function main() {
   }
 
   // 2) Remove SwiftBar plugin files best-effort.
-  const menubar = dryRun ? { ok: true, removed: 0, pluginsDir: resolveSwiftbarPluginsDir() } : await removeSwiftbarPluginFiles().catch(() => ({ ok: false, removed: 0, pluginsDir: null }));
+  const menubar =
+    isSandboxed() && !allowGlobal
+      ? { ok: true, removed: 0, pluginsDir: null, skipped: 'sandbox' }
+      : dryRun
+        ? { ok: true, removed: 0, pluginsDir: resolveSwiftbarPluginsDir() }
+        : await removeSwiftbarPluginFiles().catch(() => ({ ok: false, removed: 0, pluginsDir: null }));
 
   // 3) Remove home-managed runtime + shims + extras + cache + env pointers.
+  const canonicalEnv = getCanonicalHomeEnvPath();
   const toRemove = [
     join(homeDir, 'bin'),
     join(homeDir, 'runtime'),
@@ -120,6 +126,8 @@ async function main() {
     join(homeDir, 'cache'),
     join(homeDir, '.env'),
     join(homeDir, 'env.local'),
+    // Stable pointer file (can differ from homeDir for custom installs).
+    canonicalEnv,
   ];
   const removedPaths = [];
   for (const p of toRemove) {
@@ -148,7 +156,7 @@ async function main() {
 
   // 5) Optionally remove stacks data.
   if (removeStacks) {
-    const stacksRoot = join(homedir(), '.happy', 'stacks');
+    const stacksRoot = getStacksStorageRoot();
     if (existsSync(stacksRoot)) {
       if (!dryRun) {
         await rm(stacksRoot, { recursive: true, force: true });
@@ -177,7 +185,7 @@ async function main() {
       `[uninstall] removed: ${removedPaths.length ? removedPaths.join(', ') : '(nothing)'}`,
       menubar?.pluginsDir ? `[uninstall] SwiftBar plugins dir: ${menubar.pluginsDir}` : null,
       removeWorkspace ? `[uninstall] workspace removed: ${workspaceDir}` : `[uninstall] workspace kept: ${workspaceDir}`,
-      removeStacks ? `[uninstall] stacks removed: ~/.happy/stacks` : `[uninstall] stacks kept: ~/.happy/stacks`,
+      removeStacks ? `[uninstall] stacks removed: ${getStacksStorageRoot()}` : `[uninstall] stacks kept: ${getStacksStorageRoot()}`,
     ]
       .filter(Boolean)
       .join('\n'),

package/scripts/utils/auth_files.mjs

@@ -0,0 +1,58 @@
+import { chmod, copyFile, lstat, mkdir, symlink, unlink, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+async function ensureDir(p) {
+  await mkdir(p, { recursive: true });
+}
+
+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_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/browser.mjs

@@ -0,0 +1,22 @@
+import { runCapture } from './proc.mjs';
+
+export async function openUrlInBrowser(url, { timeoutMs = 5_000 } = {}) {
+  const u = String(url ?? '').trim();
+  if (!u) return { ok: false, error: 'missing_url' };
+
+  try {
+    if (process.platform === 'darwin') {
+      await runCapture('open', [u], { timeoutMs });
+      return { ok: true, method: 'open' };
+    }
+    if (process.platform === 'win32') {
+      // `start` is a cmd built-in; the empty title ("") is required so URLs with :// don't get treated as a title.
+      await runCapture('cmd', ['/c', 'start', '""', u], { timeoutMs });
+      return { ok: true, method: 'cmd-start' };
+    }
+    await runCapture('xdg-open', [u], { timeoutMs });
+    return { ok: true, method: 'xdg-open' };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}

package/scripts/utils/canonical_home.mjs

@@ -0,0 +1,20 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function expandHome(p) {
+  return String(p ?? '').replace(/^~(?=\/)/, homedir());
+}
+
+export function getCanonicalHomeDirFromEnv(env = process.env) {
+  const fromEnv = (
+    (env.HAPPY_STACKS_CANONICAL_HOME_DIR ?? '').trim() ||
+    (env.HAPPY_LOCAL_CANONICAL_HOME_DIR ?? '').trim() ||
+    ''
+  );
+  return fromEnv ? expandHome(fromEnv) : join(homedir(), '.happy-stacks');
+}
+
+export function getCanonicalHomeEnvPathFromEnv(env = process.env) {
+  return join(getCanonicalHomeDirFromEnv(env), '.env');
+}
+

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',
@@ -57,6 +74,13 @@ export function getHappysRegistry() {
       rootUsage: 'happys dev [-- ...]',
       description: 'Start local stack (dev)',
     },
+    {
+      name: 'stop',
+      kind: 'node',
+      scriptRelPath: 'scripts/stop.mjs',
+      rootUsage: 'happys stop [--except-stacks=main,exp1] [--yes] [--aggressive] [--no-docker] [--no-service] [--json]',
+      description: 'Stop stacks and related local processes',
+    },
     {
       name: 'build',
       kind: 'node',
@@ -64,6 +88,42 @@ 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'],
+      kind: 'node',
+      scriptRelPath: 'scripts/typecheck.mjs',
+      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',
+      scriptRelPath: 'scripts/migrate.mjs',
+      rootUsage: 'happys migrate light-to-server --from-stack=<name> --to-stack=<name> [--include-files] [--force] [--json]',
+      description: 'Migrate data between server flavors (experimental)',
+    },
     {
       name: 'mobile',
       kind: 'node',
@@ -78,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',
@@ -250,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}`),
     '',
@@ -260,3 +330,4 @@ export function renderHappysRootHelp() {
     '  happys help [command]',
   ].join('\n');
 }
+

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 '../worktrees.mjs';
 
 export function isTty() {
   return Boolean(process.stdin.isTTY && process.stdout.isTTY);