@happier-dev/stack 0.1.0-preview.5.1

package/scripts/tui_stopStackForTuiExit_no_autosweep.integration.test.mjs

@@ -0,0 +1,95 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { stopStackForTuiExit } from './utils/tui/cleanup.mjs';
+import { isAlive, spawnOwnedSleep, waitForProcessAlive, waitForProcessExit } from './testkit/stack_stop_sweeps_testkit.mjs';
+
+test('stopStackForTuiExit auto-sweeps infra when stack.runtime.json is missing (and does not kill session-like processes)', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const rootDir = dirname(scriptsDir);
+
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-tui-exit-stop-'));
+  const storageDir = join(tmp, 'storage');
+  await mkdir(storageDir, { recursive: true });
+  const env = { ...process.env, HAPPIER_STACK_STORAGE_DIR: storageDir };
+
+  /** @type {ReturnType<typeof spawnOwnedSleep> | null} */
+  let infra = null;
+  /** @type {ReturnType<typeof spawnOwnedSleep> | null} */
+  let sessionLike = null;
+  try {
+    const stackName = 'exp1';
+    const baseDir = join(storageDir, stackName);
+    const envPath = join(baseDir, 'env');
+    await mkdir(baseDir, { recursive: true });
+
+    const repoDir = dirname(rootDir);
+    await writeFile(
+      envPath,
+      [
+        `HAPPIER_STACK_STACK=${stackName}`,
+        `HAPPIER_STACK_SERVER_COMPONENT=happier-server-light`,
+        `HAPPIER_STACK_REPO_DIR=${repoDir}`,
+        `HAPPIER_STACK_CLI_HOME_DIR=${join(baseDir, 'cli')}`,
+        '',
+      ].join('\n'),
+      'utf-8'
+    );
+
+    infra = spawnOwnedSleep({
+      env: {
+        ...env,
+        HAPPIER_STACK_STACK: stackName,
+        HAPPIER_STACK_ENV_FILE: envPath,
+        HAPPIER_STACK_PROCESS_KIND: 'infra',
+      },
+    });
+    assert.ok(Number(infra.pid) > 1, 'expected infra child pid');
+    assert.ok(isAlive(infra.pid), 'expected infra child to be alive');
+
+    sessionLike = spawnOwnedSleep({
+      env: {
+        ...env,
+        HAPPIER_STACK_STACK: stackName,
+        HAPPIER_STACK_ENV_FILE: envPath,
+        HAPPIER_STACK_PROCESS_KIND: 'session',
+      },
+    });
+    assert.ok(Number(sessionLike.pid) > 1, 'expected session-like child pid');
+    assert.ok(isAlive(sessionLike.pid), 'expected session-like child to be alive');
+
+    await waitForProcessAlive({ pid: infra.pid, timeoutMs: 2_000, intervalMs: 25, label: 'infra process (pre-sweep)' });
+    await waitForProcessAlive({
+      pid: sessionLike.pid,
+      timeoutMs: 2_000,
+      intervalMs: 25,
+      label: 'session-like process (pre-sweep)',
+    });
+
+    const actions = await stopStackForTuiExit({ rootDir, stackName, env, json: true, noDocker: true });
+    assert.ok(actions?.sweep, 'expected stopStackForTuiExit to auto-sweep infra when runtime state is missing');
+
+    await waitForProcessExit({ pid: infra.pid, timeoutMs: 10_000, intervalMs: 50, label: 'infra process (post-sweep)' });
+    assert.ok(!isAlive(infra.pid), `expected infra pid ${infra.pid} to be stopped by sweep`);
+    assert.ok(isAlive(sessionLike.pid), `expected session-like pid ${sessionLike.pid} to still be alive`);
+  } finally {
+    for (const child of [infra, sessionLike]) {
+      const pid = child?.pid;
+      if (!pid || !isAlive(pid)) continue;
+      try {
+        process.kill(-pid, 'SIGKILL');
+      } catch {
+        // ignore
+      }
+    }
+    try {
+      await rm(tmp, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  }
+});

package/scripts/typecheck.mjs

@@ -0,0 +1,178 @@
+import './utils/env/env.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { getComponentDir, getRootDir } from './utils/paths/paths.mjs';
+import { ensureDepsInstalled } from './utils/proc/pm.mjs';
+import { pathExists } from './utils/fs/fs.mjs';
+import { run } from './utils/proc/proc.mjs';
+import { detectPackageManagerCmd, pickFirstScript, readPackageJsonScripts } from './utils/proc/package_scripts.mjs';
+import { getInvokedCwd, inferComponentFromCwd } from './utils/cli/cwd_scope.mjs';
+
+const VALID_TARGETS = ['ui', 'cli', 'server'];
+
+function targetFromLegacyComponent(component) {
+  const c = String(component ?? '').trim();
+  if (c === 'happier-ui') return 'ui';
+  if (c === 'happier-cli') return 'cli';
+  if (c === 'happier-server' || c === 'happier-server-light') return 'server';
+  return null;
+}
+
+function legacyComponentFromTarget(target) {
+  const t = String(target ?? '').trim();
+  if (t === 'ui') return 'happier-ui';
+  if (t === 'cli') return 'happier-cli';
+  if (t === 'server') return 'happier-server';
+  return null;
+}
+
+function normalizeTargetsOrThrow(rawTargets) {
+  const requested = Array.isArray(rawTargets) ? rawTargets.map((t) => String(t ?? '').trim()).filter(Boolean) : [];
+  if (!requested.length) return ['all'];
+
+  const mapped = requested
+    .map((t) => {
+      const lower = t.toLowerCase();
+      if (lower === 'all') return 'all';
+      if (VALID_TARGETS.includes(lower)) return lower;
+      const legacy = targetFromLegacyComponent(lower);
+      return legacy ?? null;
+    })
+    .filter(Boolean);
+
+  if (!mapped.length) return ['all'];
+  return mapped;
+}
+
+function pickTypecheckScript(scripts) {
+  const candidates = [
+    'typecheck',
+    'type-check',
+    'check-types',
+    'check:types',
+    'tsc',
+    'typescript',
+  ];
+  return pickFirstScript(scripts, candidates);
+}
+
+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: { targets: [...VALID_TARGETS, 'all'], flags: ['--json'] },
+      text: [
+        '[typecheck] usage:',
+        '  hstack typecheck [ui|cli|server|all] [--json]',
+        '',
+        'targets:',
+        `  ${[...VALID_TARGETS, 'all'].join(' | ')}`,
+        '',
+        'examples:',
+        '  hstack typecheck',
+        '  hstack typecheck ui',
+        '  hstack typecheck ui cli',
+        '',
+        'note:',
+        '  If run from inside a repo checkout/worktree and no targets are provided, defaults to the inferred app (ui/cli/server).',
+      ].join('\n'),
+    });
+    return;
+  }
+
+  const rootDir = getRootDir(import.meta.url);
+
+  const positionals = argv.filter((a) => !a.startsWith('--'));
+  const inferredLegacy =
+    positionals.length === 0
+      ? inferComponentFromCwd({
+          rootDir,
+          invokedCwd: getInvokedCwd(process.env),
+          components: ['happier-ui', 'happier-cli', 'happier-server'],
+        })
+      : null;
+  if (inferredLegacy) {
+    if (!(process.env.HAPPIER_STACK_REPO_DIR ?? '').toString().trim()) {
+      process.env.HAPPIER_STACK_REPO_DIR = inferredLegacy.repoDir;
+    }
+  }
+
+  const inferredTarget = inferredLegacy ? targetFromLegacyComponent(inferredLegacy.component) : null;
+  const requested = normalizeTargetsOrThrow(positionals.length ? positionals : inferredTarget ? [inferredTarget] : ['all']);
+  const wantAll = requested.includes('all');
+  const targets = wantAll ? VALID_TARGETS : requested;
+
+  const results = [];
+  for (const target of targets) {
+    if (!VALID_TARGETS.includes(target)) {
+      results.push({ target, ok: false, skipped: false, error: `unknown target (expected one of: ${[...VALID_TARGETS, 'all'].join(', ')})` });
+      continue;
+    }
+
+    const component = legacyComponentFromTarget(target);
+    const dir = getComponentDir(rootDir, component);
+    if (!(await pathExists(dir))) {
+      results.push({ target, ok: false, skipped: false, dir, error: `missing target dir: ${dir}` });
+      continue;
+    }
+
+    const scripts = await readPackageJsonScripts(dir);
+    if (!scripts) {
+      results.push({ target, ok: true, skipped: true, dir, reason: 'no package.json' });
+      continue;
+    }
+
+    const script = pickTypecheckScript(scripts);
+    if (!script) {
+      results.push({ target, ok: true, skipped: true, dir, reason: 'no typecheck script found in package.json' });
+      continue;
+    }
+
+    await ensureDepsInstalled(dir, target);
+    const pm = await detectPackageManagerCmd(dir);
+
+    try {
+      // eslint-disable-next-line no-console
+      console.log(`[typecheck] ${target}: running ${pm.name} ${script}`);
+      await run(pm.cmd, pm.argsForScript(script), { cwd: dir, env: process.env });
+      results.push({ target, ok: true, skipped: false, dir, pm: pm.name, script });
+    } catch (e) {
+      results.push({ target, ok: false, skipped: false, dir, pm: pm.name, script, error: String(e?.message ?? e) });
+    }
+  }
+
+  const ok = results.every((r) => r.ok);
+  if (json) {
+    printResult({ json, data: { ok, results } });
+    return;
+  }
+
+  const lines = ['[typecheck] results:'];
+  for (const r of results) {
+    if (r.ok && r.skipped) {
+      lines.push(`- ↪ ${r.target}: skipped (${r.reason})`);
+    } else if (r.ok) {
+      lines.push(`- ✅ ${r.target}: ok (${r.pm} ${r.script})`);
+    } else {
+      lines.push(`- ❌ ${r.target}: failed (${r.pm ?? 'unknown'} ${r.script ?? ''})`);
+      if (r.error) lines.push(`  - ${r.error}`);
+    }
+  }
+  if (!ok) {
+    lines.push('');
+    lines.push('[typecheck] failed');
+  }
+  printResult({ json: false, text: lines.join('\n') });
+  if (!ok) {
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('[typecheck] failed:', err);
+  process.exit(1);
+});

package/scripts/ui_gateway.mjs

@@ -0,0 +1,247 @@
+import './utils/env/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 Happier 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 Happier 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.HAPPIER_STACK_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 Happier 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

@@ -0,0 +1,179 @@
+import './utils/env/env.mjs';
+
+import { rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { expandHome } from './utils/paths/canonical_home.mjs';
+import { getHappyStacksHomeDir, getRootDir, getStacksStorageRoot } from './utils/paths/paths.mjs';
+import { getRuntimeDir } from './utils/paths/runtime.mjs';
+import { getCanonicalHomeEnvPath } from './utils/env/config.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
+import { removeSwiftbarPlugins, resolveSwiftbarPluginsDir } from './utils/menubar/swiftbar.mjs';
+import { banner, bullets, cmd, kv, sectionTitle } from './utils/ui/layout.mjs';
+import { cyan, dim, green, yellow } from './utils/ui/ansi.mjs';
+
+function resolveWorkspaceDir({ rootDir, homeDir }) {
+  // Uninstall should never default to deleting the repo root (getWorkspaceDir() can fall back to cliRootDir).
+  const fromEnv = (process.env.HAPPIER_STACK_WORKSPACE_DIR ?? '').trim();
+  if (fromEnv) {
+    return expandHome(fromEnv);
+  }
+  void rootDir;
+  return join(homeDir, 'workspace');
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+  if (wantsHelp(argv, { flags }) || argv.includes('help')) {
+    printResult({
+      json,
+      data: { flags: ['--remove-workspace', '--remove-stacks', '--yes', '--global'], json: true },
+      text: [
+        '[uninstall] usage:',
+        '  hstack uninstall [--json]   # dry-run',
+        '  hstack uninstall --yes [--json]',
+        '  hstack uninstall --remove-workspace --yes',
+        '  hstack uninstall --remove-stacks --yes',
+        '  hstack 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',
+        '  - stacks under ~/.happier/stacks are kept unless --remove-stacks is provided',
+      ].join('\n'),
+    });
+    return;
+  }
+
+  const rootDir = getRootDir(import.meta.url);
+  const homeDir = getHappyStacksHomeDir();
+  const runtimeDir = getRuntimeDir();
+  const workspaceDir = resolveWorkspaceDir({ rootDir, homeDir });
+
+  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;
+
+  if (!json) {
+    // eslint-disable-next-line no-console
+    console.log('');
+    // eslint-disable-next-line no-console
+    console.log(banner('uninstall', { subtitle: 'Remove hstack runtime + shims (and optionally workspace/stacks).' }));
+    // eslint-disable-next-line no-console
+    console.log('');
+  }
+
+  // 1) Stop/uninstall services best-effort.
+  if (!dryRun && (!isSandboxed() || allowGlobal)) {
+    try {
+      spawnSync(process.execPath, [join(rootDir, 'scripts', 'service.mjs'), 'uninstall'], {
+        stdio: json ? 'ignore' : 'inherit',
+        env: process.env,
+        cwd: rootDir,
+      });
+    } catch {
+      // ignore
+    }
+  }
+
+  // 2) Remove SwiftBar plugin files best-effort.
+  const menubar =
+    isSandboxed() && !allowGlobal
+      ? { ok: true, removed: false, pluginsDir: null, skipped: 'sandbox' }
+      : dryRun
+        ? { ok: true, removed: false, pluginsDir: resolveSwiftbarPluginsDir() }
+        : await removeSwiftbarPlugins().catch(() => ({ ok: false, removed: false, pluginsDir: null }));
+
+  // 3) Remove home-managed runtime + shims + extras + cache + env pointers.
+  const canonicalEnv = getCanonicalHomeEnvPath();
+  const toRemove = [
+    join(homeDir, 'bin'),
+    join(homeDir, 'runtime'),
+    join(homeDir, 'extras'),
+    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) {
+    try {
+      if (existsSync(p)) {
+        if (!dryRun) {
+          await rm(p, { recursive: true, force: true });
+        }
+        removedPaths.push(p);
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  // 4) Optionally remove workspace (repo clone + worktrees).
+  if (removeWorkspace) {
+    const ws = expandHome(workspaceDir);
+    if (existsSync(ws)) {
+      if (!dryRun) {
+        await rm(ws, { recursive: true, force: true });
+      }
+      removedPaths.push(ws);
+    }
+  }
+
+  // 5) Optionally remove stacks data.
+  if (removeStacks) {
+    const stacksRoot = getStacksStorageRoot();
+    if (existsSync(stacksRoot)) {
+      if (!dryRun) {
+        await rm(stacksRoot, { recursive: true, force: true });
+      }
+      removedPaths.push(stacksRoot);
+    }
+  }
+
+  printResult({
+    json,
+    data: {
+      ok: true,
+      homeDir,
+      runtimeDir,
+      workspaceDir,
+      removedPaths,
+      menubar,
+      removeWorkspace,
+      removeStacks,
+      dryRun,
+    },
+    text: [
+      dryRun ? `${yellow('!')} dry run (no changes made)` : `${green('✓')} complete`,
+      dryRun ? `${dim('Re-run with')} ${cmd('hstack uninstall --yes')} ${dim('to apply removals.')}` : null,
+      '',
+      sectionTitle('Plan'),
+      bullets([
+        kv('home:', cyan(homeDir)),
+        kv('workspace:', removeWorkspace ? `${cyan(workspaceDir)} ${dim('(will remove)')}` : `${cyan(workspaceDir)} ${dim('(keep)')}`),
+        kv('stacks:', removeStacks ? `${cyan(getStacksStorageRoot())} ${dim('(will remove)')}` : `${cyan(getStacksStorageRoot())} ${dim('(keep)')}`),
+        menubar?.pluginsDir ? kv('swiftbar:', `${menubar.pluginsDir}${menubar?.skipped ? ` ${dim('(skipped)')}` : ''}`) : null,
+      ].filter(Boolean)),
+      '',
+      sectionTitle('Removed'),
+      removedPaths.length ? bullets(removedPaths.map((p) => p)) : dim('(nothing)'),
+    ]
+      .filter(Boolean)
+      .join('\n'),
+  });
+}
+
+main().catch((err) => {
+  console.error('[uninstall] failed:', err);
+  process.exit(1);
+});