happy-stacks 0.0.0

package/scripts/doctor.mjs

@@ -0,0 +1,342 @@
+import './utils/env.mjs';
+import { parseArgs } from './utils/args.mjs';
+import { pathExists } from './utils/fs.mjs';
+import { runCapture } from './utils/proc.mjs';
+import { getComponentDir, getDefaultAutostartPaths, getHappyStacksHomeDir, getRootDir, getWorkspaceDir, resolveStackEnvPath } from './utils/paths.mjs';
+import { killPortListeners } from './utils/ports.mjs';
+import { getServerComponentName } from './utils/server.mjs';
+import { daemonStatusSummary } from './daemon.mjs';
+import { tailscaleServeStatus, resolvePublicServerUrl } from './tailscale.mjs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
+import { getRuntimeDir } from './utils/runtime.mjs';
+import { assertServerComponentDirMatches } from './utils/validate.mjs';
+
+/**
+ * Doctor script for common happy-stacks failure modes.
+ *
+ * Checks:
+ * - server port in use / server health
+ * - UI build directory existence
+ * - daemon status
+ * - tailscale serve status (if available)
+ * - launch agent status (macOS)
+ *
+ * Flags:
+ * - --fix : best-effort fixes (kill server port listener)
+ */
+
+async function fetchHealth(url) {
+  const tryGet = async (path) => {
+  try {
+      const res = await fetch(`${url}${path}`, { method: 'GET' });
+    const body = await res.text();
+    return { ok: res.ok, status: res.status, body: body.trim() };
+    } catch {
+    return { ok: false, status: null, body: null };
+  }
+  };
+
+  // Prefer /health when available, but fall back to / (matches waitForServerReady).
+  const health = await tryGet('/health');
+  if (health.ok) {
+    return health;
+  }
+  const root = await tryGet('/');
+  if (root.ok && root.body?.includes('Welcome to Happy Server!')) {
+    return root;
+  }
+  return health.ok ? health : root;
+}
+
+async function readJsonSafe(path) {
+  try {
+    const raw = await readFile(path, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function readPkgVersion(path) {
+  try {
+    const raw = await readFile(path, 'utf-8');
+    const pkg = JSON.parse(raw);
+    const v = String(pkg.version ?? '').trim();
+    return v || null;
+  } catch {
+    return null;
+  }
+}
+
+async function resolveSwiftbarPluginsDir() {
+  if (process.platform !== 'darwin') {
+    return null;
+  }
+  try {
+    const dir = (await runCapture('bash', [
+      '-lc',
+      'DIR="$(defaults read com.ameba.SwiftBar PluginDirectory 2>/dev/null)"; if [[ -n "$DIR" && -d "$DIR" ]]; then echo "$DIR"; exit 0; fi; D="$HOME/Library/Application Support/SwiftBar/Plugins"; if [[ -d "$D" ]]; then echo "$D"; exit 0; fi; echo ""',
+    ])).trim();
+    return dir || null;
+  } catch {
+    return null;
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags, kv } = parseArgs(argv);
+  const fix = flags.has('--fix');
+  const json = wantsJson(argv, { flags });
+
+  if (wantsHelp(argv, { flags })) {
+    printResult({
+      json,
+      data: { flags: ['--fix', '--server=happy-server|happy-server-light'], json: true },
+      text: [
+        '[doctor] usage:',
+        '  happys doctor [--fix] [--json]',
+        '  node scripts/doctor.mjs [--fix] [--server=happy-server|happy-server-light] [--json]',
+      ].join('\n'),
+    });
+    return;
+  }
+
+  const rootDir = getRootDir(import.meta.url);
+  const homeDir = getHappyStacksHomeDir();
+  const runtimeDir = getRuntimeDir();
+  const workspaceDir = getWorkspaceDir(rootDir);
+  const updateCachePath = join(homeDir, 'cache', 'update.json');
+  const runtimePkgJson = join(runtimeDir, 'node_modules', 'happy-stacks', 'package.json');
+  const runtimeVersion = await readPkgVersion(runtimePkgJson);
+  const updateCache = existsSync(updateCachePath) ? await readJsonSafe(updateCachePath) : null;
+
+  const serverPort = process.env.HAPPY_LOCAL_SERVER_PORT?.trim() ? Number(process.env.HAPPY_LOCAL_SERVER_PORT) : 3005;
+  const internalServerUrl = `http://127.0.0.1:${serverPort}`;
+
+  const defaultPublicUrl = `http://localhost:${serverPort}`;
+  const envPublicUrl = process.env.HAPPY_LOCAL_SERVER_URL?.trim() ? process.env.HAPPY_LOCAL_SERVER_URL.trim() : '';
+  const resolved = await resolvePublicServerUrl({
+    internalServerUrl,
+    defaultPublicUrl,
+    envPublicUrl,
+    allowEnable: false,
+  });
+  const publicServerUrl = resolved.publicServerUrl;
+
+  const cliHomeDir = process.env.HAPPY_LOCAL_CLI_HOME_DIR?.trim()
+    ? process.env.HAPPY_LOCAL_CLI_HOME_DIR.trim().replace(/^~(?=\/)/, homedir())
+    : join(getDefaultAutostartPaths().baseDir, 'cli');
+
+  const serveUi = (process.env.HAPPY_LOCAL_SERVE_UI ?? '1') !== '0';
+  const uiBuildDir = process.env.HAPPY_LOCAL_UI_BUILD_DIR?.trim()
+    ? process.env.HAPPY_LOCAL_UI_BUILD_DIR.trim()
+    : join(getDefaultAutostartPaths().baseDir, 'ui');
+
+  const serverComponentName = getServerComponentName({ kv });
+  if (serverComponentName === 'both') {
+    throw new Error(`[local] --server=both is not supported for doctor (pick one: happy-server-light or happy-server)`);
+  }
+
+  const serverDir = getComponentDir(rootDir, serverComponentName);
+  const cliDir = getComponentDir(rootDir, 'happy-cli');
+  const cliBin = join(cliDir, 'bin', 'happy.mjs');
+
+  assertServerComponentDirMatches({ rootDir, serverComponentName, serverDir });
+
+  const report = {
+    paths: {
+      rootDir,
+      homeDir,
+      runtimeDir,
+      workspaceDir,
+      updateCachePath,
+    },
+    runtime: {
+      installed: Boolean(runtimeVersion),
+      version: runtimeVersion,
+      packageJson: runtimePkgJson,
+      updateCache,
+    },
+    env: {
+      homeEnv: join(homeDir, '.env'),
+      homeLocal: join(homeDir, 'env.local'),
+      mainStackEnv: resolveStackEnvPath('main').envPath,
+      activeEnv: process.env.HAPPY_STACKS_ENV_FILE?.trim() || process.env.HAPPY_LOCAL_ENV_FILE?.trim() || null,
+    },
+    internalServerUrl,
+    publicServerUrl,
+    serverComponentName,
+    uiBuildDir,
+    cliHomeDir,
+    checks: {},
+  };
+  if (!json) {
+    console.log('🩺 happy-stacks doctor\n');
+    console.log(`- internal: ${internalServerUrl}`);
+    console.log(`- public:   ${publicServerUrl}`);
+    console.log(`- server:   ${serverComponentName}`);
+    console.log(`- uiBuild:  ${uiBuildDir}`);
+    console.log(`- cliHome:  ${cliHomeDir}`);
+    console.log(`- home:     ${homeDir}`);
+    console.log(`- runtime:  ${runtimeVersion ? `${runtimeDir} (${runtimeVersion})` : `${runtimeDir} (not installed)`}`);
+    console.log(`- workspace:${workspaceDir}`);
+    console.log('');
+  }
+
+  if (!(await pathExists(serverDir))) {
+    report.checks.serverDir = { ok: false, missing: serverDir };
+    if (!json) console.log(`❌ missing component: ${serverDir}`);
+  }
+  if (!(await pathExists(cliDir))) {
+    report.checks.cliDir = { ok: false, missing: cliDir };
+    if (!json) console.log(`❌ missing component: ${cliDir}`);
+  }
+
+  // Server health / port conflicts
+  const health = await fetchHealth(internalServerUrl);
+  if (health.ok) {
+    report.checks.serverHealth = { ok: true, status: health.status, body: health.body };
+    if (!json) console.log(`✅ server health: ${health.status} ${health.body}`);
+  } else {
+    report.checks.serverHealth = { ok: false };
+    if (!json) console.log(`❌ server health: unreachable (${internalServerUrl})`);
+    if (fix) {
+      if (!json) console.log(`↪ attempting fix: freeing tcp:${serverPort}`);
+      await killPortListeners(serverPort, { label: 'doctor' });
+    }
+  }
+
+  // UI build dir check
+  if (serveUi) {
+    if (serverComponentName !== 'happy-server-light') {
+      report.checks.uiServing = { ok: false, reason: `requires happy-server-light (current: ${serverComponentName})` };
+      if (!json) console.log(`ℹ️ ui serving requires happy-server-light (current: ${serverComponentName})`);
+    }
+    if (await pathExists(uiBuildDir)) {
+      report.checks.uiBuildDir = { ok: true, path: uiBuildDir };
+      if (!json) console.log('✅ ui build dir present');
+    } else {
+      report.checks.uiBuildDir = { ok: false, missing: uiBuildDir };
+      if (!json) console.log(`❌ ui build dir missing (${uiBuildDir}) → run: happys build`);
+    }
+  } else {
+    report.checks.uiServing = { ok: false, reason: 'disabled (HAPPY_LOCAL_SERVE_UI=0)' };
+    if (!json) console.log('ℹ️ ui serving disabled (HAPPY_LOCAL_SERVE_UI=0)');
+  }
+
+  // Daemon status
+  try {
+    const out = await daemonStatusSummary({
+      cliBin,
+      cliHomeDir,
+      internalServerUrl,
+      publicServerUrl,
+    });
+    const line = out.split('\n').find((l) => l.includes('Daemon is running'))?.trim();
+    report.checks.daemon = { ok: true, line: line || null };
+    if (!json) console.log(`✅ daemon: ${line ? line : 'status ok'}`);
+  } catch (e) {
+    const accessKeyPath = join(cliHomeDir, 'access.key');
+    const hasAccessKey = existsSync(accessKeyPath);
+    report.checks.daemon = { ok: false, hasAccessKey, accessKeyPath };
+    if (!json) {
+      console.log('❌ daemon: not running / status failed');
+      if (!hasAccessKey) {
+        const stackName = (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').trim() || 'main';
+        console.log(`  ↪ likely cause: missing credentials at ${accessKeyPath}`);
+        console.log(`  ↪ fix: authenticate for this stack:`);
+        console.log(`     ${stackName === 'main' ? 'happys auth login' : `happys stack auth ${stackName} login`}`);
+      }
+    }
+  }
+
+  // Tailscale Serve status (best-effort)
+  try {
+    const status = await tailscaleServeStatus();
+    const httpsLine = status.split('\n').find((l) => l.toLowerCase().includes('https://'))?.trim();
+    report.checks.tailscaleServe = { ok: true, httpsLine: httpsLine || null };
+    if (!json) console.log(`✅ tailscale serve: ${httpsLine ? httpsLine : 'configured'}`);
+  } catch {
+    report.checks.tailscaleServe = { ok: false };
+    if (!json) console.log('ℹ️ tailscale serve: unavailable (tailscale not installed / not running)');
+  }
+
+  // macOS LaunchAgent status
+  if (process.platform === 'darwin') {
+    try {
+      const list = await runCapture('launchctl', ['list']);
+      const { primaryLabel, legacyLabel } = getDefaultAutostartPaths();
+      const primaryLine = list.split('\n').find((l) => l.includes(primaryLabel))?.trim() || null;
+      const legacyLine = list.split('\n').find((l) => l.includes(legacyLabel))?.trim() || null;
+      const line = primaryLine || legacyLine;
+      report.checks.launchd = { ok: true, line: line || null };
+      if (!json) console.log(`✅ launchd: ${line ? line : 'not loaded'}`);
+    } catch {
+      report.checks.launchd = { ok: false };
+      if (!json) console.log('ℹ️ launchd: unable to query');
+    }
+  }
+
+  // SwiftBar plugin status (macOS)
+  if (process.platform === 'darwin') {
+    const pluginsDir = await resolveSwiftbarPluginsDir();
+    const pluginInstalled =
+      pluginsDir && existsSync(pluginsDir)
+        ? Boolean((await runCapture('bash', ['-lc', `ls -1 "${pluginsDir}"/happy-stacks.*.sh 2>/dev/null | head -n 1 || true`])).trim())
+        : false;
+    report.checks.swiftbar = { ok: true, pluginsDir, pluginInstalled };
+    if (!json) {
+      console.log(`✅ swiftbar: ${pluginInstalled ? 'plugin installed' : 'not installed'}`);
+    }
+  }
+
+  // happy wrapper
+  try {
+    const happyPath = (await runCapture('sh', ['-lc', 'command -v happy'])).trim();
+    if (happyPath) {
+      report.checks.happyOnPath = { ok: true, path: happyPath };
+      if (!json) console.log(`✅ happy on PATH: ${happyPath}`);
+    }
+  } catch {
+    report.checks.happyOnPath = { ok: false };
+    if (!json) console.log('ℹ️ happy on PATH: not found (run: happys init --install-path, or add ~/.happy-stacks/bin to PATH)');
+  }
+
+  // happys on PATH
+  try {
+    const happysPath = (await runCapture('sh', ['-lc', 'command -v happys'])).trim();
+    if (happysPath) {
+      report.checks.happysOnPath = { ok: true, path: happysPath };
+      if (!json) console.log(`✅ happys on PATH: ${happysPath}`);
+    }
+  } catch {
+    report.checks.happysOnPath = { ok: false };
+    if (!json) console.log('ℹ️ happys on PATH: not found (run: happys init --install-path, or add ~/.happy-stacks/bin to PATH)');
+  }
+
+  if (!json) {
+    if (!runtimeVersion) {
+      console.log('');
+      console.log('Tips:');
+      console.log('- Install a stable runtime (recommended for SwiftBar/services): happys self update');
+    }
+    if (!report.checks.happysOnPath?.ok) {
+      console.log('- Add shims to PATH: export PATH="$HOME/.happy-stacks/bin:$PATH" (or: happys init --install-path)');
+    }
+    console.log('');
+  }
+
+  if (json) {
+    printResult({ json, data: report });
+  }
+}
+
+main().catch((err) => {
+  console.error('[local] doctor failed:', err);
+  process.exit(1);
+});

package/scripts/happy.mjs

@@ -0,0 +1,79 @@
+import './utils/env.mjs';
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { parseArgs } from './utils/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
+import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths.mjs';
+
+function expandHome(p) {
+  return p.replace(/^~(?=\/)/, homedir());
+}
+
+function resolveCliHomeDir() {
+  const fromExplicit = (process.env.HAPPY_HOME_DIR ?? '').trim();
+  if (fromExplicit) {
+    return expandHome(fromExplicit);
+  }
+  const fromStacks = (process.env.HAPPY_STACKS_CLI_HOME_DIR ?? process.env.HAPPY_LOCAL_CLI_HOME_DIR ?? '').trim();
+  if (fromStacks) {
+    return expandHome(fromStacks);
+  }
+  return join(getDefaultAutostartPaths().baseDir, 'cli');
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+
+  if (wantsHelp(argv, { flags })) {
+    printResult({
+      json,
+      data: { passthrough: true },
+      text: [
+        '[happy] usage:',
+        '  happys happy <happy-cli args...>',
+        '',
+        'notes:',
+        '  - This runs the `happy-cli` component from your configured workspace/components.',
+        '  - It auto-fills HAPPY_HOME_DIR / HAPPY_SERVER_URL / HAPPY_WEBAPP_URL when missing.',
+      ].join('\n'),
+    });
+    return;
+  }
+
+  const rootDir = getRootDir(import.meta.url);
+
+  const portRaw = (process.env.HAPPY_STACKS_SERVER_PORT ?? process.env.HAPPY_LOCAL_SERVER_PORT ?? '').trim();
+  const port = portRaw ? Number(portRaw) : 3005;
+  const serverPort = Number.isFinite(port) ? port : 3005;
+
+  const internalServerUrl = `http://127.0.0.1:${serverPort}`;
+  const publicServerUrl = (process.env.HAPPY_STACKS_SERVER_URL ?? process.env.HAPPY_LOCAL_SERVER_URL ?? '').trim() || `http://localhost:${serverPort}`;
+
+  const cliHomeDir = resolveCliHomeDir();
+
+  const cliDir = getComponentDir(rootDir, 'happy-cli');
+  const entrypoint = join(cliDir, 'dist', 'index.mjs');
+  if (!existsSync(entrypoint)) {
+    throw new Error(`[happy] missing happy-cli build at: ${entrypoint}\nRun: happys bootstrap`);
+  }
+
+  const env = { ...process.env };
+  env.HAPPY_HOME_DIR = env.HAPPY_HOME_DIR || cliHomeDir;
+  env.HAPPY_SERVER_URL = env.HAPPY_SERVER_URL || internalServerUrl;
+  env.HAPPY_WEBAPP_URL = env.HAPPY_WEBAPP_URL || publicServerUrl;
+
+  execFileSync(process.execPath, ['--no-warnings', '--no-deprecation', entrypoint, ...argv], {
+    stdio: 'inherit',
+    env,
+  });
+}
+
+main().catch((err) => {
+  console.error('[happy] failed:', err);
+  process.exit(1);
+});
+

package/scripts/init.mjs

@@ -0,0 +1,232 @@
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { ensureHomeEnvUpdated } from './utils/config.mjs';
+
+function expandHome(p) {
+  return p.replace(/^~(?=\/)/, homedir());
+}
+
+function getCliRootDir() {
+  return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+
+function parseArgValue(argv, key) {
+  const long = `--${key}=`;
+  const hit = argv.find((a) => a.startsWith(long));
+  if (hit) return hit.slice(long.length);
+  const idx = argv.indexOf(`--${key}`);
+  if (idx >= 0 && argv[idx + 1]) return argv[idx + 1];
+  return null;
+}
+
+async function writeExecutable(path, contents) {
+  await writeFile(path, contents, { mode: 0o755 });
+}
+
+function escapeForDoubleQuotes(s) {
+  return String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+async function ensurePathInstalled({ homeDir }) {
+  const shell = (process.env.SHELL ?? '').toLowerCase();
+  const isDarwin = process.platform === 'darwin';
+
+  const zshrc = join(homedir(), '.zshrc');
+  const bashrc = join(homedir(), '.bashrc');
+  const bashProfile = join(homedir(), '.bash_profile');
+  const fishDir = join(homedir(), '.config', 'fish', 'conf.d');
+  const fishConf = join(fishDir, 'happy-stacks.fish');
+
+  const markerStart = '# >>> happy-stacks >>>';
+  const markerEnd = '# <<< happy-stacks <<<';
+
+  const lineSh = `export PATH="${escapeForDoubleQuotes(join(homeDir, 'bin'))}:$PATH"`;
+  const blockSh = `\n${markerStart}\n${lineSh}\n${markerEnd}\n`;
+
+  const lineFish = `set -gx PATH "${escapeForDoubleQuotes(join(homeDir, 'bin'))}" $PATH`;
+  const blockFish = `\n${markerStart}\n${lineFish}\n${markerEnd}\n`;
+
+  const writeIfMissing = async (path, block) => {
+    let existing = '';
+    try {
+      existing = await readFile(path, 'utf-8');
+    } catch {
+      existing = '';
+    }
+    if (existing.includes(markerStart) || existing.includes(lineSh) || existing.includes(lineFish)) {
+      return { updated: false, path };
+    }
+    await writeFile(path, existing.replace(/\s*$/, '') + block, 'utf-8');
+    return { updated: true, path };
+  };
+
+  if (shell.includes('fish')) {
+    await mkdir(fishDir, { recursive: true });
+    return await writeIfMissing(fishConf, blockFish);
+  }
+
+  if (shell.includes('bash')) {
+    // macOS interactive bash typically sources ~/.bash_profile; linux usually uses ~/.bashrc.
+    const target = isDarwin ? bashProfile : bashrc;
+    return await writeIfMissing(target, blockSh);
+  }
+
+  // Default to zsh on modern macOS; also fine for linux users.
+  return await writeIfMissing(zshrc, blockSh);
+}
+
+async function main() {
+  const rawArgv = process.argv.slice(2);
+  const sep = rawArgv.indexOf('--');
+  const argv = sep >= 0 ? rawArgv.slice(0, sep) : rawArgv;
+  const bootstrapArgsRaw = sep >= 0 ? rawArgv.slice(sep + 1) : [];
+  const bootstrapArgs = bootstrapArgsRaw[0] === '--' ? bootstrapArgsRaw.slice(1) : bootstrapArgsRaw;
+  if (argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') {
+    console.log([
+      '[init] usage:',
+      '  happys init [--home-dir=/path] [--workspace-dir=/path] [--runtime-dir=/path] [--install-path] [--no-runtime] [--no-bootstrap] [--] [bootstrap args...]',
+      '',
+      'notes:',
+      '  - writes ~/.happy-stacks/.env (stable pointer file)',
+      '  - default workspace: ~/.happy-stacks/workspace',
+      '  - default runtime: ~/.happy-stacks/runtime (recommended for services/SwiftBar)',
+      '  - optional: --install-path adds ~/.happy-stacks/bin to your shell PATH (idempotent)',
+      '  - by default, runs `happys bootstrap --interactive` at the end (TTY only)',
+    ].join('\n'));
+    return;
+  }
+
+  const cliRootDir = getCliRootDir();
+
+  const homeDirRaw = parseArgValue(argv, 'home-dir');
+  const homeDir = expandHome((homeDirRaw ?? '').trim() || (process.env.HAPPY_STACKS_HOME_DIR ?? '').trim() || join(homedir(), '.happy-stacks'));
+  process.env.HAPPY_STACKS_HOME_DIR = homeDir;
+
+  const workspaceDirRaw = parseArgValue(argv, 'workspace-dir');
+  const workspaceDir = expandHome((workspaceDirRaw ?? '').trim() || join(homeDir, 'workspace'));
+  process.env.HAPPY_STACKS_WORKSPACE_DIR = process.env.HAPPY_STACKS_WORKSPACE_DIR ?? workspaceDir;
+
+  const runtimeDirRaw = parseArgValue(argv, 'runtime-dir');
+  const runtimeDir = expandHome((runtimeDirRaw ?? '').trim() || (process.env.HAPPY_STACKS_RUNTIME_DIR ?? '').trim() || join(homeDir, 'runtime'));
+  process.env.HAPPY_STACKS_RUNTIME_DIR = process.env.HAPPY_STACKS_RUNTIME_DIR ?? runtimeDir;
+
+  const nodePath = process.execPath;
+
+  await mkdir(homeDir, { recursive: true });
+  await mkdir(workspaceDir, { recursive: true });
+  await mkdir(join(workspaceDir, 'components'), { recursive: true });
+  await mkdir(runtimeDir, { recursive: true });
+  await mkdir(join(homeDir, 'bin'), { recursive: true });
+
+  await ensureHomeEnvUpdated({
+    updates: [
+      { key: 'HAPPY_STACKS_HOME_DIR', value: homeDir },
+      { key: 'HAPPY_STACKS_WORKSPACE_DIR', value: workspaceDir },
+      { key: 'HAPPY_STACKS_RUNTIME_DIR', value: runtimeDir },
+      { key: 'HAPPY_STACKS_NODE', value: nodePath },
+    ],
+  });
+
+  const installRuntime = !argv.includes('--no-runtime');
+  if (installRuntime) {
+    const pkg = JSON.parse(await readFile(join(cliRootDir, 'package.json'), 'utf-8'));
+    const version = String(pkg.version ?? '').trim() || 'latest';
+    const spec = version === '0.0.0' ? 'happy-stacks@latest' : `happy-stacks@${version}`;
+
+    console.log(`[init] installing runtime into ${runtimeDir} (${spec})...`);
+    let res = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--silent', '--prefix', runtimeDir, spec], { stdio: 'inherit' });
+    if (res.status !== 0) {
+      // Pre-publish developer experience: if the package isn't on npm yet (E404),
+      // fall back to installing the local checkout into the runtime prefix.
+      console.log(`[init] runtime install failed; attempting local install from ${cliRootDir}...`);
+      res = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--silent', '--prefix', runtimeDir, cliRootDir], { stdio: 'inherit' });
+      if (res.status !== 0) {
+        process.exit(res.status ?? 1);
+      }
+    }
+  }
+
+  const happysShimPath = join(homeDir, 'bin', 'happys');
+  const happyShimPath = join(homeDir, 'bin', 'happy');
+  const shim = [
+    '#!/bin/bash',
+    'set -euo pipefail',
+    'HOME_DIR="${HAPPY_STACKS_HOME_DIR:-$HOME/.happy-stacks}"',
+    'ENV_FILE="$HOME_DIR/.env"',
+    'NODE_BIN=""',
+    'if [[ -f "$ENV_FILE" ]]; then',
+    '  NODE_BIN="$(grep -E \'^HAPPY_STACKS_NODE=\' "$ENV_FILE" | head -n 1 | sed \'s/^HAPPY_STACKS_NODE=//\')"',
+    'fi',
+    'if [[ -z "$NODE_BIN" ]]; then',
+    '  NODE_BIN="$(command -v node 2>/dev/null || true)"',
+    'fi',
+    'RUNTIME_DIR="${HAPPY_STACKS_RUNTIME_DIR:-$HOME_DIR/runtime}"',
+    'ENTRY="$RUNTIME_DIR/node_modules/happy-stacks/bin/happys.mjs"',
+    'if [[ -f "$ENTRY" ]]; then',
+    '  exec "$NODE_BIN" "$ENTRY" "$@"',
+    'fi',
+    'exec happys "$@"',
+    '',
+  ].join('\n');
+
+  await writeExecutable(happysShimPath, shim);
+  await writeExecutable(happyShimPath, `#!/bin/bash\nset -euo pipefail\nexec \"${happysShimPath}\" happy \"$@\"\n`);
+
+  if (argv.includes('--install-path')) {
+    const res = await ensurePathInstalled({ homeDir });
+    if (res.updated) {
+      console.log(`[init] added ${homeDir}/bin to PATH via ${res.path}`);
+    } else {
+      console.log(`[init] PATH already configured in ${res.path}`);
+    }
+  }
+
+  console.log('[init] complete');
+  console.log(`[init] home:      ${homeDir}`);
+  console.log(`[init] workspace:  ${workspaceDir}`);
+  console.log(`[init] shims:     ${homeDir}/bin`);
+  console.log('');
+
+  if (!argv.includes('--install-path')) {
+    console.log('[init] note: to use `happys` / `happy` from any terminal, add shims to PATH:');
+    console.log(`  export PATH="${homeDir}/bin:$PATH"`);
+    console.log('  (or re-run: happys init --install-path)');
+    console.log('');
+  } else {
+    console.log('[init] note: restart your terminal (or source your shell config) to pick up PATH changes.');
+    console.log('');
+  }
+
+  const wantBootstrap = !argv.includes('--no-bootstrap');
+  const isTty = process.stdout.isTTY && process.stdin.isTTY;
+  const shouldBootstrap = wantBootstrap;
+
+  if (shouldBootstrap) {
+    const nextArgs = [...bootstrapArgs];
+    if (isTty && !nextArgs.includes('--interactive') && !nextArgs.includes('-i')) {
+      nextArgs.unshift('--interactive');
+    }
+    console.log('[init] running bootstrap...');
+    const res = spawnSync(process.execPath, [join(cliRootDir, 'scripts', 'install.mjs'), ...nextArgs], {
+      stdio: 'inherit',
+      env: process.env,
+      cwd: cliRootDir,
+    });
+    if (res.status !== 0) {
+      process.exit(res.status ?? 1);
+    }
+    return;
+  }
+
+  console.log('[init] next steps:');
+  console.log(`  export PATH=\"${homeDir}/bin:$PATH\"`);
+  console.log('  happys bootstrap --interactive');
+}
+
+main().catch((err) => {
+  console.error('[init] failed:', err);
+  process.exit(1);
+});