@happier-dev/stack 0.1.0-preview.5.1

package/scripts/utils/tui/cleanup.mjs

@@ -0,0 +1,38 @@
+import { readFile } from 'node:fs/promises';
+
+import { parseEnvToObject } from '../env/dotenv.mjs';
+import { resolveStackEnvPath } from '../paths/paths.mjs';
+import { stopStackWithEnv } from '../stack/stop.mjs';
+
+async function readEnvObject(envPath) {
+  try {
+    const raw = await readFile(envPath, 'utf-8');
+    return parseEnvToObject(raw);
+  } catch {
+    return {};
+  }
+}
+
+export async function stopStackForTuiExit({ rootDir, stackName, json = false, noDocker = false, env: outerEnv = process.env }) {
+  const { envPath, baseDir } = resolveStackEnvPath(stackName, outerEnv);
+  const stackEnv = await readEnvObject(envPath);
+
+  const env = {
+    ...(outerEnv ?? process.env),
+    ...stackEnv,
+    HAPPIER_STACK_STACK: stackName,
+    HAPPIER_STACK_ENV_FILE: envPath,
+  };
+
+  return await stopStackWithEnv({
+    rootDir,
+    stackName,
+    baseDir,
+    env,
+    json,
+    noDocker,
+    aggressive: false,
+    sweepOwned: false,
+    autoSweep: true,
+  });
+}

package/scripts/utils/ui/ansi.mjs

@@ -0,0 +1,47 @@
+function supportsAnsi() {
+  if (!process.stdout.isTTY) return false;
+  if (process.env.NO_COLOR) return false;
+  if ((process.env.TERM ?? '').toLowerCase() === 'dumb') return false;
+  return true;
+}
+
+function wrap(code, s) {
+  return supportsAnsi() ? `\x1b[${code}m${s}\x1b[0m` : String(s);
+}
+
+export function ansiEnabled() {
+  return supportsAnsi();
+}
+
+export function bold(s) {
+  return wrap('1', s);
+}
+
+export function dim(s) {
+  return wrap('2', s);
+}
+
+export function red(s) {
+  return wrap('31', s);
+}
+
+export function green(s) {
+  return wrap('32', s);
+}
+
+export function yellow(s) {
+  return wrap('33', s);
+}
+
+export function blue(s) {
+  return wrap('34', s);
+}
+
+export function magenta(s) {
+  return wrap('35', s);
+}
+
+export function cyan(s) {
+  return wrap('36', s);
+}
+

package/scripts/utils/ui/browser.mjs

@@ -0,0 +1,31 @@
+import { runCapture } from '../proc/proc.mjs';
+
+function isTruthyEnvValue(value) {
+  const raw = String(value ?? '').trim().toLowerCase();
+  if (!raw) return false;
+  return raw !== '0' && raw !== 'false';
+}
+
+export async function openUrlInBrowser(url, { timeoutMs = 5_000 } = {}) {
+  const u = String(url ?? '').trim();
+  if (!u) return { ok: false, error: 'missing_url' };
+  if (isTruthyEnvValue(process.env.HAPPIER_NO_BROWSER_OPEN) || isTruthyEnvValue(process.env.HAPPIER_STACK_NO_BROWSER)) {
+    return { ok: false, error: 'browser_open_disabled' };
+  }
+
+  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/ui/browser.test.mjs

@@ -0,0 +1,56 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, writeFile, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+function readTextOrEmpty(path) {
+  return readFile(path, 'utf-8').catch(() => '');
+}
+
+test('openUrlInBrowser respects HAPPIER_NO_BROWSER_OPEN and does not invoke OS opener', async (t) => {
+  if (process.platform === 'win32') {
+    t.skip('uses shell shims tailored for POSIX openers');
+    return;
+  }
+
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-browser-open-'));
+  const scriptDir = dirname(fileURLToPath(import.meta.url));
+  const pathSep = process.platform === 'win32' ? ';' : ':';
+  const openLogPath = join(tmp, 'open.log');
+
+  try {
+    const shim = '#!/usr/bin/env bash\nprintf "%s\\n" "$@" >> "$OPEN_LOG"\n';
+    await writeFile(join(tmp, 'open'), shim, { mode: 0o755 });
+    await writeFile(join(tmp, 'xdg-open'), shim, { mode: 0o755 });
+
+    const child = spawnSync(
+      process.execPath,
+      [
+        '--input-type=module',
+        '-e',
+        "import { openUrlInBrowser } from './browser.mjs'; const res = await openUrlInBrowser('http://localhost:54545'); process.stdout.write(JSON.stringify(res));",
+      ],
+      {
+        cwd: scriptDir,
+        env: {
+          ...process.env,
+          PATH: `${tmp}${pathSep}${process.env.PATH ?? ''}`,
+          OPEN_LOG: openLogPath,
+          HAPPIER_NO_BROWSER_OPEN: '1',
+        },
+      },
+    );
+
+    assert.equal(child.status, 0, `stdout:\n${child.stdout}\nstderr:\n${child.stderr}`);
+    const stdoutText = String(child.stdout ?? '').trim();
+    const parsed = JSON.parse(stdoutText || '{}');
+    assert.equal(parsed.ok, false, `expected openUrlInBrowser to skip open\nstdout:\n${child.stdout}`);
+    const logContents = await readTextOrEmpty(openLogPath);
+    assert.equal(logContents.trim(), '', `expected no OS opener invocations\nlog:\n${logContents}`);
+  } finally {
+    await rm(tmp, { recursive: true, force: true }).catch(() => {});
+  }
+});

package/scripts/utils/ui/clipboard.mjs

@@ -0,0 +1,38 @@
+import { commandExists } from '../proc/commands.mjs';
+import { run } from '../proc/proc.mjs';
+
+export async function clipboardAvailable() {
+  if (process.platform === 'darwin') {
+    return await commandExists('pbcopy');
+  }
+  if (process.platform === 'linux') {
+    return (await commandExists('wl-copy')) || (await commandExists('xclip'));
+  }
+  return false;
+}
+
+export async function copyTextToClipboard(text) {
+  const s = String(text ?? '');
+  if (!s) return { ok: false, reason: 'empty' };
+
+  if (process.platform === 'darwin') {
+    if (!(await commandExists('pbcopy'))) return { ok: false, reason: 'pbcopy not found' };
+    await run('pbcopy', [], { input: s });
+    return { ok: true };
+  }
+
+  if (process.platform === 'linux') {
+    if (await commandExists('wl-copy')) {
+      await run('wl-copy', [], { input: s });
+      return { ok: true };
+    }
+    if (await commandExists('xclip')) {
+      await run('xclip', ['-selection', 'clipboard'], { input: s });
+      return { ok: true };
+    }
+    return { ok: false, reason: 'no clipboard tool found' };
+  }
+
+  return { ok: false, reason: `unsupported platform: ${process.platform}` };
+}
+

package/scripts/utils/ui/layout.mjs

@@ -0,0 +1,44 @@
+import { ansiEnabled, bold, cyan, dim, green, red, yellow } from './ansi.mjs';
+
+function icon(s) {
+  // Keep icons TTY-friendly; avoid icons when color is disabled to reduce noise in logs.
+  return ansiEnabled() ? String(s) : '';
+}
+
+export function cmd(s) {
+  return yellow(String(s));
+}
+
+export function ok(s) {
+  return `${green('✓')}${s ? ` ${s}` : ''}`;
+}
+
+export function warn(s) {
+  return `${yellow('!')}${s ? ` ${s}` : ''}`;
+}
+
+export function fail(s) {
+  return `${red('x')}${s ? ` ${s}` : ''}`;
+}
+
+export function kv(label, value) {
+  return `${dim(label)} ${value}`;
+}
+
+export function sectionTitle(title) {
+  return bold(String(title));
+}
+
+export function banner(title, { subtitle = '', prefix = '✨', suffix = '✨' } = {}) {
+  const pre = icon(prefix);
+  const suf = icon(suffix);
+  const t = `${pre ? `${pre} ` : ''}${cyan(title)}${suf ? ` ${suf}` : ''}`;
+  const lines = [bold(t)];
+  if (subtitle) lines.push(dim(subtitle));
+  return lines.join('\n');
+}
+
+export function bullets(lines) {
+  return (lines ?? []).map((l) => `- ${l}`).join('\n');
+}
+

package/scripts/utils/ui/qr.mjs

@@ -0,0 +1,17 @@
+import qrcodeTerminal from 'qrcode-terminal';
+
+export async function renderQrAscii(text, { small = true } = {}) {
+  const qrText = String(text ?? '');
+  if (!qrText) return { ok: false, lines: [], error: 'empty QR payload' };
+  try {
+    const out = await new Promise((resolvePromise) => {
+      qrcodeTerminal.generate(qrText, { small: Boolean(small) }, (qr) => resolvePromise(String(qr ?? '')));
+    });
+    // Important: keep whitespace; scanners rely on quiet-zone padding.
+    const lines = String(out ?? '').replace(/\r/g, '').split('\n');
+    return { ok: true, lines, error: null };
+  } catch (e) {
+    return { ok: false, lines: [], error: e instanceof Error ? e.message : String(e) };
+  }
+}
+

package/scripts/utils/ui/terminal_launcher.mjs

@@ -0,0 +1,129 @@
+import { commandExists } from '../proc/commands.mjs';
+import { run } from '../proc/proc.mjs';
+import { chmod, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+function hasGuiSession(env = process.env) {
+  if (process.platform === 'darwin') return true;
+  if (process.platform === 'linux') {
+    const display = String(env.DISPLAY ?? '').trim();
+    const wayland = String(env.WAYLAND_DISPLAY ?? '').trim();
+    return Boolean(display || wayland);
+  }
+  return false;
+}
+
+async function pickLinuxTerminalCmd() {
+  // Best-effort: pick the first terminal emulator we can find.
+  const candidates = [
+    'x-terminal-emulator', // Debian/Ubuntu alternatives
+    'gnome-terminal',
+    'konsole',
+    'xfce4-terminal',
+    'kitty',
+    'wezterm',
+    'alacritty',
+    'xterm',
+  ];
+  for (const c of candidates) {
+    // eslint-disable-next-line no-await-in-loop
+    if (await commandExists(c)) return c;
+  }
+  return '';
+}
+
+function linuxTerminalArgs(cmd, scriptPath) {
+  // Keep this conservative and use `bash` explicitly.
+  switch (cmd) {
+    case 'gnome-terminal':
+      return ['--', 'bash', scriptPath];
+    case 'konsole':
+      return ['-e', 'bash', scriptPath];
+    case 'xfce4-terminal':
+      return ['--disable-server', '--command', `bash "${scriptPath.replace(/"/g, '\\"')}"`];
+    case 'wezterm':
+      return ['start', '--', 'bash', scriptPath];
+    case 'alacritty':
+      return ['-e', 'bash', scriptPath];
+    case 'kitty':
+      return ['bash', scriptPath];
+    case 'xterm':
+      return ['-e', 'bash', scriptPath];
+    case 'x-terminal-emulator':
+      return ['-e', 'bash', scriptPath];
+    default:
+      return ['-e', 'bash', scriptPath];
+  }
+}
+
+function escapeAppleScriptString(s) {
+  return String(s ?? '')
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n');
+}
+
+export async function canLaunchNewTerminal({ env } = {}) {
+  const e = env ?? process.env;
+  if (!hasGuiSession(e)) return { ok: false, reason: 'no GUI session detected' };
+  if (process.platform === 'darwin') {
+    const hasOsascript = await commandExists('osascript', { env: e });
+    if (!hasOsascript) return { ok: false, reason: 'osascript not found' };
+    return { ok: true, kind: 'darwin-terminal' };
+  }
+  if (process.platform === 'linux') {
+    const term = await pickLinuxTerminalCmd();
+    if (!term) return { ok: false, reason: 'no terminal emulator found' };
+    return { ok: true, kind: 'linux-terminal', terminalCmd: term };
+  }
+  return { ok: false, reason: `unsupported platform: ${process.platform}` };
+}
+
+export async function launchScriptInNewTerminal({ scriptText, title, env } = {}) {
+  const e = env ?? process.env;
+  const support = await canLaunchNewTerminal({ env: e });
+  if (!support.ok) return { ok: false, reason: support.reason };
+
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-llm-'));
+  const scriptPath = join(dir, 'run.sh');
+  const text = [
+    String(scriptText ?? '').trimEnd(),
+    '',
+    // Self-cleanup best-effort.
+    'rm -f "$0" >/dev/null 2>&1 || true',
+    'rmdir "$(dirname "$0")" >/dev/null 2>&1 || true',
+    '',
+  ].join('\n');
+
+  await writeFile(scriptPath, text, 'utf-8');
+  await chmod(scriptPath, 0o755);
+
+  try {
+    if (support.kind === 'darwin-terminal') {
+      const banner = title ? `echo ${JSON.stringify(String(title))}; echo; ` : '';
+      const cmd = `${banner}bash "${scriptPath}"`;
+      const as = [
+        'tell application "Terminal"',
+        'activate',
+        `do script "${escapeAppleScriptString(cmd)}"`,
+        'end tell',
+      ].join('\n');
+      await run('osascript', ['-e', as], { env: e });
+      return { ok: true, launched: true };
+    }
+
+    if (support.kind === 'linux-terminal') {
+      const args = linuxTerminalArgs(support.terminalCmd, scriptPath);
+      await run(support.terminalCmd, args, { env: e });
+      return { ok: true, launched: true, terminalCmd: support.terminalCmd };
+    }
+
+    return { ok: false, reason: 'unknown terminal kind' };
+  } catch (err) {
+    // Cleanup, since the script didn't launch.
+    await rm(dir, { recursive: true, force: true }).catch(() => {});
+    return { ok: false, reason: String(err?.message ?? err ?? 'launch failed') };
+  }
+}
+

package/scripts/utils/ui/text.mjs

@@ -0,0 +1,16 @@
+export function stripAnsi(s) {
+  // eslint-disable-next-line no-control-regex
+  return String(s ?? '').replace(/\x1b\[[0-9;]*[A-Za-z]/g, '');
+}
+
+export function padRight(s, n) {
+  const str = String(s ?? '');
+  if (str.length >= n) return str.slice(0, n);
+  return str + ' '.repeat(n - str.length);
+}
+
+export function parsePrefixedLabel(line) {
+  const m = String(line ?? '').match(/^\[([^\]]+)\]\s*/);
+  return m ? m[1] : null;
+}
+

package/scripts/utils/update/auto_update_notice.mjs

@@ -0,0 +1,93 @@
+import { join } from 'node:path';
+
+import {
+  acquireSingleFlightLock,
+  formatUpdateNotice,
+  readUpdateCache,
+  shouldNotifyUpdate,
+  spawnDetachedNode,
+  writeUpdateCache,
+} from '@happier-dev/cli-common/update';
+
+const DEFAULT_CHECK_LOCK_TTL_MS = 2 * 60 * 1000;
+const DEFAULT_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+function parseEnabledFlag(raw, { defaultValue = true } = {}) {
+  const v = String(raw ?? '').trim().toLowerCase();
+  if (!v) return defaultValue;
+  if (v === '0' || v === 'false' || v === 'no' || v === 'off') return false;
+  return true;
+}
+
+function parsePositiveMs(raw, fallback) {
+  const v = String(raw ?? '').trim();
+  if (!v) return fallback;
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+export function maybeAutoUpdateNotice({
+  cliRootDir,
+  cmd,
+  homeDir,
+  isTTY,
+  env,
+  nowMs,
+  spawnDetached = spawnDetachedNode,
+  log = console.error,
+}) {
+  const enabled = parseEnabledFlag(env.HAPPIER_STACK_UPDATE_CHECK, { defaultValue: true });
+  if (!enabled) return;
+  if (!isTTY) return;
+  if (env.HAPPIER_STACK_UPDATE_CHECK_SPAWNED === '1') return;
+  if (cmd === 'self' || cmd === 'help' || cmd === '--help' || cmd === '-h') return;
+
+  const cachePath = join(homeDir, 'cache', 'update.json');
+
+  const intervalMs = parsePositiveMs(env.HAPPIER_STACK_UPDATE_CHECK_INTERVAL_MS, DEFAULT_INTERVAL_MS);
+  const notifyIntervalMs = parsePositiveMs(env.HAPPIER_STACK_UPDATE_NOTIFY_INTERVAL_MS, DEFAULT_INTERVAL_MS);
+
+  const cached = readUpdateCache(cachePath);
+
+  const now = nowMs ?? Date.now();
+  const checkedAt = typeof cached?.checkedAt === 'number' ? cached.checkedAt : 0;
+  const shouldCheck = !checkedAt || (now - checkedAt > intervalMs);
+
+  const shouldNotify = shouldNotifyUpdate({
+    isTTY,
+    cmd,
+    updateAvailable: Boolean(cached?.updateAvailable),
+    latest: cached?.latest ?? null,
+    notifiedAt: cached?.notifiedAt ?? null,
+    notifyIntervalMs,
+    nowMs: now,
+  });
+
+  if (shouldNotify) {
+    const from = cached?.current ? cached.current : 'current';
+    const to = cached?.latest ?? 'latest';
+    log(formatUpdateNotice({ toolName: 'hstack', from, to, updateCommand: 'hstack self update' }));
+    writeUpdateCache(cachePath, {
+      checkedAt: cached?.checkedAt ?? null,
+      latest: cached?.latest ?? null,
+      current: cached?.current ?? null,
+      runtimeVersion: cached?.runtimeVersion ?? null,
+      invokerVersion: cached?.invokerVersion ?? null,
+      updateAvailable: Boolean(cached?.updateAvailable),
+      notifiedAt: now,
+    });
+  }
+
+  if (!shouldCheck) return;
+
+  const lockTtlMs = parsePositiveMs(env.HAPPIER_STACK_UPDATE_CHECK_LOCK_TTL_MS, DEFAULT_CHECK_LOCK_TTL_MS);
+  const lockPath = join(homeDir, 'cache', 'update.check.lock.json');
+  if (!acquireSingleFlightLock({ lockPath, nowMs: now, ttlMs: lockTtlMs, pid: process.pid })) return;
+
+  spawnDetached({
+    script: join(cliRootDir, 'scripts', 'self.mjs'),
+    args: ['check', '--quiet'],
+    cwd: cliRootDir,
+    env: { ...env, HAPPIER_STACK_UPDATE_CHECK_SPAWNED: '1' },
+  });
+}

package/scripts/utils/validate.mjs

@@ -0,0 +1,5 @@
+export {
+  detectServerComponentDirMismatch,
+  assertServerComponentDirMatches,
+  assertServerPrismaProviderMatches,
+} from './server/validate.mjs';

package/scripts/where.mjs

@@ -0,0 +1,138 @@
+import './utils/env/env.mjs';
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { parseArgs } from './utils/cli/args.mjs';
+import { expandHome } from './utils/paths/canonical_home.mjs';
+import { getComponentDir, getDevRepoDir, getHappyStacksHomeDir, getRepoDir, getRootDir, getStackLabel, getStackName, getWorkspaceDir, resolveStackEnvPath } from './utils/paths/paths.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { getRuntimeDir } from './utils/paths/runtime.mjs';
+import { getCanonicalHomeDir, getCanonicalHomeEnvPath } from './utils/env/config.mjs';
+import { getSandboxDir } from './utils/env/sandbox.mjs';
+import { banner, bullets, kv, sectionTitle } from './utils/ui/layout.mjs';
+import { cyan, dim } from './utils/ui/ansi.mjs';
+import { WORKTREE_CATEGORIES, getWorktreeCategoryRoot } from './utils/git/worktrees.mjs';
+
+function getHomeEnvPaths() {
+  const homeDir = getHappyStacksHomeDir();
+  return {
+    homeEnv: join(homeDir, '.env'),
+    homeLocal: join(homeDir, 'env.local'),
+  };
+}
+
+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: ['--json'], commands: ['where'] },
+      text: ['[where] usage:', '  hstack where [--json]'].join('\n'),
+    });
+    return;
+  }
+
+  const rootDir = getRootDir(import.meta.url);
+  const homeDir = getHappyStacksHomeDir();
+  const canonicalHomeDir = getCanonicalHomeDir();
+  const canonicalEnv = getCanonicalHomeEnvPath();
+  const sandboxDir = getSandboxDir();
+  const runtimeDir = getRuntimeDir();
+  const workspaceDir = getWorkspaceDir(rootDir);
+  const repoDir = getRepoDir(rootDir);
+  const worktreeCategoryDirs = Object.fromEntries(
+    WORKTREE_CATEGORIES.map((c) => [c, getWorktreeCategoryRoot(rootDir, c, process.env)])
+  );
+  const mainDir = getRepoDir(rootDir, { ...process.env, HAPPIER_STACK_REPO_DIR: '' });
+  const devDir = getDevRepoDir(rootDir, process.env);
+
+  const stackName = getStackName();
+  const stackLabel = getStackLabel(stackName);
+  const resolvedMainEnv = resolveStackEnvPath('main');
+  const resolvedActiveEnv = process.env.HAPPIER_STACK_ENV_FILE?.trim()
+    ? { envPath: expandHome(process.env.HAPPIER_STACK_ENV_FILE.trim()) }
+    : null;
+
+  const { homeEnv, homeLocal } = getHomeEnvPaths();
+  const updateCachePath = join(homeDir, 'cache', 'update.json');
+
+  const packageNames = ['happier-ui', 'happier-cli', 'happier-server'];
+  const packageDirs = Object.fromEntries(packageNames.map((name) => [name, getComponentDir(rootDir, name)]));
+
+  printResult({
+    json,
+    data: {
+      ok: true,
+      rootDir,
+      sandbox: sandboxDir ? { enabled: true, dir: sandboxDir } : { enabled: false },
+      homeDir,
+      canonicalHomeDir,
+      runtimeDir,
+      workspaceDir,
+      repoDir,
+      checkouts: { main: mainDir, dev: devDir },
+      worktrees: worktreeCategoryDirs,
+      stack: { name: stackName, label: stackLabel },
+      envFiles: {
+        canonical: { path: canonicalEnv, exists: existsSync(canonicalEnv) },
+        homeEnv: { path: homeEnv, exists: existsSync(homeEnv) },
+        homeLocal: { path: homeLocal, exists: existsSync(homeLocal) },
+        active: resolvedActiveEnv ? { path: resolvedActiveEnv.envPath, exists: existsSync(resolvedActiveEnv.envPath) } : null,
+        main: { path: resolvedMainEnv.envPath, exists: existsSync(resolvedMainEnv.envPath) },
+      },
+      packages: packageDirs,
+      update: {
+        enabled: (process.env.HAPPIER_STACK_UPDATE_CHECK ?? '1') !== '0',
+        cachePath: updateCachePath,
+        cacheExists: existsSync(updateCachePath),
+      },
+    },
+    text: [
+      '',
+      banner('where', { subtitle: 'Resolved paths and env sources.' }),
+      '',
+      sectionTitle('Paths'),
+      bullets([
+        kv('root:', rootDir),
+        sandboxDir ? kv('sandbox:', sandboxDir) : null,
+        kv('canonical:', canonicalHomeDir),
+        kv('home:', homeDir),
+        kv('runtime:', runtimeDir),
+        kv('workspace:', workspaceDir),
+        kv('repo:', repoDir),
+        kv('main:', mainDir),
+        kv('dev:', devDir),
+        kv('pr:', worktreeCategoryDirs.pr),
+        kv('local:', worktreeCategoryDirs.local),
+        kv('tmp:', worktreeCategoryDirs.tmp),
+      ].filter(Boolean)),
+      '',
+      sectionTitle('Active stack'),
+      bullets([kv('stack:', `${cyan(stackName)} (${stackLabel})`)]),
+      '',
+      sectionTitle('Env files'),
+      bullets([
+        kv('canonical pointer:', existsSync(canonicalEnv) ? canonicalEnv : `${canonicalEnv} ${dim('(missing)')}`),
+        kv('home defaults:', existsSync(homeEnv) ? homeEnv : `${homeEnv} ${dim('(missing)')}`),
+        kv('home overrides:', existsSync(homeLocal) ? homeLocal : `${homeLocal} ${dim('(missing)')}`),
+        kv('active:', resolvedActiveEnv?.envPath ? resolvedActiveEnv.envPath : dim('(none)')),
+        kv('main:', resolvedMainEnv.envPath),
+      ]),
+      '',
+      sectionTitle('Repo packages'),
+      bullets(packageNames.map((n) => kv(n + ':', packageDirs[n]))),
+      '',
+      sectionTitle('Update'),
+      bullets([kv('cache:', updateCachePath)]),
+      '',
+    ].join('\n'),
+  });
+}
+
+main().catch((err) => {
+  console.error('[where] failed:', err);
+  process.exit(1);
+});