@happier-dev/stack 0.1.0-preview.74.1

package/scripts/utils/cli/cwd_scope.test.mjs

@@ -0,0 +1,154 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, realpath, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { getInvokedCwd, inferComponentFromCwd } from './cwd_scope.mjs';
+
+async function withTempRoot(t) {
+  const dir = await mkdtemp(join(tmpdir(), 'happier-stacks-cwd-scope-'));
+  t.after(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+  return dir;
+}
+
+async function createMonorepoCheckout({ rootDir, checkoutPath }) {
+  const repoRoot = join(rootDir, checkoutPath);
+  await mkdir(join(repoRoot, 'apps', 'ui'), { recursive: true });
+  await mkdir(join(repoRoot, 'apps', 'cli', 'src'), { recursive: true });
+  await mkdir(join(repoRoot, 'apps', 'server'), { recursive: true });
+  await writeFile(join(repoRoot, 'apps', 'ui', 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(repoRoot, 'apps', 'cli', 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(repoRoot, 'apps', 'server', 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(repoRoot, '.git'), 'gitdir: /tmp/fake\n', 'utf-8');
+  return repoRoot;
+}
+
+function workspaceEnv(rootDir) {
+  return { ...process.env, HAPPIER_STACK_WORKSPACE_DIR: rootDir };
+}
+
+function withMockedProcessCwd(t, value) {
+  if (t.mock?.method) {
+    t.mock.method(process, 'cwd', () => value);
+    return;
+  }
+  const prevCwd = process.cwd;
+  process.cwd = () => value;
+  t.after(() => {
+    process.cwd = prevCwd;
+  });
+}
+
+test('inferComponentFromCwd resolves the stable monorepo checkout under <workspace>/main', async (t) => {
+  const rootDir = await withTempRoot(t);
+  const repoRoot = await createMonorepoCheckout({ rootDir, checkoutPath: 'main' });
+  const inferred = inferComponentFromCwd({
+    rootDir,
+    invokedCwd: join(repoRoot, 'apps', 'ui'),
+    components: ['happier-ui', 'happier-cli'],
+    env: workspaceEnv(rootDir),
+  });
+  assert.deepEqual(inferred, { component: 'happier-ui', repoDir: repoRoot });
+});
+
+test('inferComponentFromCwd resolves happier monorepo subpackages under <workspace>/main', async (t) => {
+  const rootDir = await withTempRoot(t);
+  const repoRoot = await createMonorepoCheckout({ rootDir, checkoutPath: 'main' });
+  const inferred = inferComponentFromCwd({
+    rootDir,
+    invokedCwd: join(repoRoot, 'apps', 'cli', 'src'),
+    components: ['happier-ui', 'happier-cli', 'happier-server'],
+    env: workspaceEnv(rootDir),
+  });
+  assert.deepEqual(inferred, { component: 'happier-cli', repoDir: repoRoot });
+});
+
+test('inferComponentFromCwd resolves happier monorepo worktree roots under <workspace>/pr', async (t) => {
+  const rootDir = await withTempRoot(t);
+  const repoRoot = await createMonorepoCheckout({ rootDir, checkoutPath: join('pr', '123-fix') });
+  await mkdir(join(repoRoot, 'apps', 'cli', 'nested'), { recursive: true });
+  const inferred = inferComponentFromCwd({
+    rootDir,
+    invokedCwd: join(repoRoot, 'apps', 'cli', 'nested'),
+    components: ['happier-ui', 'happier-cli', 'happier-server'],
+    env: workspaceEnv(rootDir),
+  });
+  assert.deepEqual(inferred, { component: 'happier-cli', repoDir: repoRoot });
+});
+
+test('inferComponentFromCwd returns null outside known component roots', async (t) => {
+  const rootDir = await withTempRoot(t);
+  const invokedCwd = join(rootDir, 'somewhere', 'else');
+  await mkdir(invokedCwd, { recursive: true });
+  const inferred = inferComponentFromCwd({
+    rootDir,
+    invokedCwd,
+    components: ['happier-ui'],
+    env: workspaceEnv(rootDir),
+  });
+  assert.equal(inferred, null);
+});
+
+test('inferComponentFromCwd uses the provided env (does not depend on process.env)', async (t) => {
+  const rootDir = await withTempRoot(t);
+  const repoRoot = await createMonorepoCheckout({ rootDir, checkoutPath: 'main' });
+  const inferred = inferComponentFromCwd({
+    rootDir,
+    invokedCwd: join(repoRoot, 'apps', 'ui'),
+    components: ['happier-ui'],
+    env: workspaceEnv(rootDir),
+  });
+  assert.deepEqual(inferred, { component: 'happier-ui', repoDir: repoRoot });
+});
+
+test('getInvokedCwd falls back to process.cwd() when PWD is not set (Windows)', async (t) => {
+  const dir = await withTempRoot(t);
+  const expected = await realpath(dir).catch(() => dir);
+  withMockedProcessCwd(t, dir);
+
+  const actual = await realpath(getInvokedCwd({})).catch(() => getInvokedCwd({}));
+  assert.equal(actual, expected);
+});
+
+test('getInvokedCwd prefers OLDPWD when it looks like the real repo/worktree root', async (t) => {
+  const rootDir = await withTempRoot(t);
+  const oldPwd = join(rootDir, 'dev');
+  const pwd = join(rootDir, 'main');
+  await mkdir(oldPwd, { recursive: true });
+  await mkdir(pwd, { recursive: true });
+  await writeFile(join(oldPwd, '.git'), 'gitdir: /tmp/fake\n', 'utf-8');
+
+  withMockedProcessCwd(t, pwd);
+  const actual = getInvokedCwd({ PWD: pwd, OLDPWD: oldPwd });
+  assert.equal(actual, oldPwd);
+});
+
+test('getInvokedCwd prefers PWD when both PWD and OLDPWD look like repo/worktree roots', async (t) => {
+  const rootDir = await withTempRoot(t);
+  const oldPwd = join(rootDir, 'dev');
+  const pwd = join(rootDir, 'main');
+  await mkdir(oldPwd, { recursive: true });
+  await mkdir(pwd, { recursive: true });
+  await writeFile(join(oldPwd, '.git'), 'gitdir: /tmp/fake\n', 'utf-8');
+  await writeFile(join(pwd, '.git'), 'gitdir: /tmp/fake\n', 'utf-8');
+
+  withMockedProcessCwd(t, pwd);
+  const actual = getInvokedCwd({ PWD: pwd, OLDPWD: oldPwd });
+  assert.equal(actual, pwd);
+});
+
+test('getInvokedCwd falls back to OLDPWD when PWD does not look like a checkout/worktree root', async (t) => {
+  const rootDir = await withTempRoot(t);
+  const oldPwd = join(rootDir, 'dev');
+  const pwd = join(rootDir, 'not-a-worktree');
+  await mkdir(oldPwd, { recursive: true });
+  await mkdir(pwd, { recursive: true });
+  await writeFile(join(oldPwd, '.git'), 'gitdir: /tmp/fake\n', 'utf-8');
+
+  withMockedProcessCwd(t, pwd);
+  const actual = getInvokedCwd({ PWD: pwd, OLDPWD: oldPwd });
+  assert.equal(actual, oldPwd);
+});

package/scripts/utils/cli/flags.mjs

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

package/scripts/utils/cli/log_forwarder.mjs

@@ -0,0 +1,157 @@
+import { createReadStream, existsSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+
+function splitLines(s) {
+  return String(s ?? '').split(/\r?\n/);
+}
+
+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 dim(s) {
+  return supportsAnsi() ? `\x1b[2m${s}\x1b[0m` : String(s);
+}
+
+/**
+ * Lightweight file log forwarder (tail-like) with pause/resume.
+ *
+ * - Always advances the file offset (prevents backpressure issues).
+ * - While paused, it buffers the last N lines and prints them once resumed.
+ */
+export function createFileLogForwarder({
+  path,
+  enabled = true,
+  pollMs = 200,
+  maxBytesPerTick = 256 * 1024,
+  bufferedLinesWhilePaused = 120,
+  startFromEnd = true,
+  label = 'logs',
+} = {}) {
+  const p = String(path ?? '').trim();
+  if (!enabled || !p) {
+    return {
+      ok: false,
+      start: async () => {},
+      stop: async () => {},
+      pause: () => {},
+      resume: () => {},
+      isPaused: () => false,
+      path: p,
+    };
+  }
+
+  let running = false;
+  let paused = false;
+  let offset = 0;
+  let partial = '';
+  let buffered = [];
+
+  const pushBufferedLine = (line) => {
+    if (!line) return;
+    buffered.push(line);
+    if (buffered.length > bufferedLinesWhilePaused) {
+      buffered = buffered.slice(buffered.length - bufferedLinesWhilePaused);
+    }
+  };
+
+  const flushBuffered = () => {
+    if (!buffered.length) return;
+    // eslint-disable-next-line no-console
+    console.log(dim(`[${label}] (showing last ${buffered.length} lines while paused)`));
+    for (const l of buffered) {
+      // eslint-disable-next-line no-console
+      console.log(l);
+    }
+    buffered = [];
+  };
+
+  const readNewBytes = async () => {
+    if (!existsSync(p)) return;
+    let st = null;
+    try {
+      st = await stat(p);
+    } catch {
+      return;
+    }
+    const size = Number(st?.size ?? 0);
+    if (!Number.isFinite(size) || size <= 0) return;
+    if (size < offset) {
+      // truncated/rotated
+      offset = 0;
+    }
+    if (size === offset) return;
+
+    const end = Math.min(size, offset + maxBytesPerTick);
+    const start = offset;
+    offset = end;
+
+    await new Promise((resolvePromise) => {
+      const chunks = [];
+      const stream = createReadStream(p, { start, end: end - 1 });
+      stream.on('data', (d) => chunks.push(Buffer.from(d)));
+      stream.on('error', () => resolvePromise());
+      stream.on('close', () => {
+        const text = partial + Buffer.concat(chunks).toString('utf-8');
+        const lines = splitLines(text);
+        partial = lines.pop() ?? '';
+        for (const line of lines) {
+          if (paused) {
+            pushBufferedLine(line);
+          } else {
+            // eslint-disable-next-line no-console
+            console.log(line);
+          }
+        }
+        resolvePromise();
+      });
+    });
+  };
+
+  const loop = async () => {
+    while (running) {
+      // eslint-disable-next-line no-await-in-loop
+      await readNewBytes();
+      // eslint-disable-next-line no-await-in-loop
+      await delay(pollMs);
+    }
+  };
+
+  return {
+    ok: true,
+    path: p,
+    start: async () => {
+      if (running) return;
+      running = true;
+      // By default, start at end (don't replay historical logs).
+      if (startFromEnd) {
+        try {
+          const st = await stat(p);
+          offset = Number(st?.size ?? 0) || 0;
+        } catch {
+          offset = 0;
+        }
+      } else {
+        offset = 0;
+      }
+      void loop();
+    },
+    stop: async () => {
+      running = false;
+    },
+    pause: () => {
+      paused = true;
+      buffered = [];
+    },
+    resume: () => {
+      paused = false;
+      flushBuffered();
+    },
+    isPaused: () => paused,
+  };
+}
+

package/scripts/utils/cli/normalize.mjs

@@ -0,0 +1,16 @@
+export function normalizeProfile(raw) {
+  const v = (raw ?? '').trim().toLowerCase();
+  if (!v) return '';
+  if (v === 'selfhost' || v === 'self-host' || v === 'self_host' || v === 'host') return 'selfhost';
+  if (v === 'dev' || v === 'developer' || v === 'develop' || v === 'development') return 'dev';
+  return '';
+}
+
+export function normalizeServerComponent(raw) {
+  const v = (raw ?? '').trim().toLowerCase();
+  if (!v) return '';
+  // Prefer Happier component IDs; accept legacy Happy IDs for backward compatibility.
+  if (v === 'light' || v === 'server-light' || v === 'happier-server-light' || v === 'happy-server-light') return 'happier-server-light';
+  if (v === 'server' || v === 'full' || v === 'happier-server' || v === 'happy-server') return 'happier-server';
+  return '';
+}

package/scripts/utils/cli/prereqs.mjs

@@ -0,0 +1,103 @@
+import { commandExists } from '../proc/commands.mjs';
+
+function formatMissingTool({ name, why, install }) {
+  return [`- ${name}: ${why}`, ...(install?.length ? install.map((l) => `  ${l}`) : [])].join('\n');
+}
+
+export async function assertCliPrereqs({
+  git = false,
+  yarn = false,
+  codex = false,
+  coderabbit = false,
+  augment = false,
+  claude = false,
+} = {}) {
+  const missing = [];
+
+  if (git) {
+    const hasGit = await commandExists('git');
+    if (!hasGit) {
+      const install =
+        process.platform === 'darwin'
+          ? ['Install Xcode Command Line Tools: `xcode-select --install`', 'Or install Git via Homebrew: `brew install git`']
+          : ['Install Git using your package manager (e.g. `apt install git`, `dnf install git`)'];
+      missing.push({
+        name: 'git',
+        why: 'required for cloning + updating PR worktrees',
+        install,
+      });
+    }
+  }
+
+  if (yarn) {
+    const hasYarn = await commandExists('yarn');
+    if (!hasYarn) {
+      missing.push({
+        name: 'yarn',
+        why: 'required to install dependencies',
+        install: [
+          'Enable Corepack (recommended): `corepack enable`',
+          'Or install Yarn: `npm install -g yarn`',
+        ],
+      });
+    }
+  }
+
+  if (codex) {
+    const hasCodex = await commandExists('codex');
+    if (!hasCodex) {
+      missing.push({
+        name: 'codex',
+        why: 'required to run Codex review',
+        install: [
+          'Install Codex CLI and ensure `codex` is on PATH',
+          'If using a managed install, ensure your PATH includes the Codex binary',
+        ],
+      });
+    }
+  }
+
+  if (coderabbit) {
+    const hasCodeRabbit = await commandExists('coderabbit');
+    if (!hasCodeRabbit) {
+      missing.push({
+        name: 'coderabbit',
+        why: 'required to run CodeRabbit CLI review',
+        install: [
+          'Install CodeRabbit CLI: `curl -fsSL https://cli.coderabbit.ai/install.sh | sh`',
+          'Then authenticate: `coderabbit auth login`',
+        ],
+      });
+    }
+  }
+
+  if (augment) {
+    const hasAuggie = await commandExists('auggie');
+    if (!hasAuggie) {
+      missing.push({
+        name: 'auggie',
+        why: 'required to run Augment (Auggie) review',
+        install: ['Install Auggie CLI: `npm install -g @augmentcode/auggie`', 'Then authenticate: `auggie login`'],
+      });
+    }
+  }
+
+  if (claude) {
+    const hasClaude = await commandExists('claude');
+    if (!hasClaude) {
+      missing.push({
+        name: 'claude',
+        why: 'required to run Claude Code review',
+        install: ['Install Claude Code CLI and ensure `claude` is on PATH', 'Then authenticate (if needed) with your Claude setup'],
+      });
+    }
+  }
+
+  if (!missing.length) return;
+
+  throw new Error(
+    `[prereqs] missing required tools:\n` +
+      `${missing.map(formatMissingTool).join('\n')}\n\n` +
+      `[prereqs] After installing, re-run the command.`
+  );
+}

package/scripts/utils/cli/prereqs.test.mjs

@@ -0,0 +1,33 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { chmod, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { assertCliPrereqs } from './prereqs.mjs';
+
+test('assertCliPrereqs({yarn:true}) accepts yarn', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'hs-prereqs-yarn-'));
+  const oldPath = process.env.PATH;
+  try {
+    const yarnBin = join(root, 'yarn');
+    await writeFile(yarnBin, '#!/bin/sh\nexit 0\n', 'utf-8');
+    await chmod(yarnBin, 0o755);
+    process.env.PATH = `/bin:${root}`;
+
+    await assertCliPrereqs({ yarn: true });
+  } finally {
+    process.env.PATH = oldPath;
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('assertCliPrereqs({yarn:true}) throws when yarn is unavailable', async () => {
+  const oldPath = process.env.PATH;
+  try {
+    process.env.PATH = '/bin';
+    await assert.rejects(() => assertCliPrereqs({ yarn: true }), /yarn/i);
+  } finally {
+    process.env.PATH = oldPath;
+  }
+});

package/scripts/utils/cli/progress.mjs

@@ -0,0 +1,141 @@
+import { spawn } from 'node:child_process';
+import { createWriteStream } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { ansiEnabled, cyan, dim, green, red, yellow } from '../ui/ansi.mjs';
+ 
+function isTty() {
+  return Boolean(process.stdout.isTTY && process.stderr.isTTY);
+}
+ 
+function spinnerFrames() {
+  return ['|', '/', '-', '\\'];
+}
+ 
+function colorResult(result) {
+  if (!ansiEnabled()) return String(result);
+  const r = String(result);
+  if (r === '✓') return green(r);
+  if (r === 'x' || r === '✗') return red(r);
+  if (r === '!') return yellow(r);
+  return r;
+}
+
+function colorSpinner(frame) {
+  if (!ansiEnabled()) return String(frame);
+  return cyan(String(frame));
+}
+
+export function createStepPrinter({ enabled = true } = {}) {
+  const tty = enabled && isTty();
+  const frames = spinnerFrames();
+  let timer = null;
+  let idx = 0;
+  let currentLine = '';
+ 
+  const write = (s) => process.stdout.write(s);
+ 
+  const start = (label) => {
+    if (!tty) {
+      write(`- [${dim('..')}] ${label}\n`);
+      return;
+    }
+    currentLine = `- [${colorSpinner(frames[idx % frames.length])}] ${label}`;
+    write(currentLine);
+    timer = setInterval(() => {
+      idx++;
+      const next = `- [${colorSpinner(frames[idx % frames.length])}] ${label}`;
+      const pad = currentLine.length > next.length ? ' '.repeat(currentLine.length - next.length) : '';
+      currentLine = next;
+      write(`\r${next}${pad}`);
+    }, 120);
+  };
+ 
+  const stop = (result, label) => {
+    if (timer) clearInterval(timer);
+    timer = null;
+    if (!tty) {
+      write(`- [${colorResult(result)}] ${label}\n`);
+      return;
+    }
+    const out = `- [${colorResult(result)}] ${label}`;
+    const pad = currentLine.length > out.length ? ' '.repeat(currentLine.length - out.length) : '';
+    currentLine = '';
+    write(`\r${out}${pad}\n`);
+  };
+ 
+  const info = (line) => {
+    write(`${line}\n`);
+  };
+ 
+  return { start, stop, info };
+}
+ 
+export async function runCommandLogged({
+  label,
+  cmd,
+  args,
+  cwd,
+  env,
+  logPath,
+  showSteps = true,
+  quiet = true,
+}) {
+  const steps = createStepPrinter({ enabled: showSteps });
+  if (quiet) {
+    await mkdir(dirname(logPath), { recursive: true }).catch(() => {});
+  }
+ 
+  steps.start(label);
+ 
+  const child = spawn(cmd, args, {
+    cwd,
+    env,
+    stdio: quiet ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+    shell: false,
+  });
+ 
+  let stdout = '';
+  let stderr = '';
+  let logStream = null;
+  if (quiet) {
+    logStream = createWriteStream(logPath, { flags: 'a' });
+    child.stdout?.on('data', (d) => {
+      const s = d.toString();
+      stdout += s;
+      logStream?.write(s);
+    });
+    child.stderr?.on('data', (d) => {
+      const s = d.toString();
+      stderr += s;
+      logStream?.write(s);
+    });
+  }
+ 
+  const res = await new Promise((resolvePromise, rejectPromise) => {
+    child.on('error', rejectPromise);
+    child.on('close', (code, signal) => resolvePromise({ code: code ?? 1, signal: signal ?? null }));
+  });
+ 
+  try {
+    logStream?.end();
+  } catch {
+    // ignore
+  }
+ 
+  if (res.code === 0) {
+    steps.stop('✓', label);
+    return { ok: true, code: 0, stdout, stderr, logPath };
+  }
+ 
+  steps.stop('x', label);
+  const err = new Error(`${cmd} failed (code=${res.code}${res.signal ? `, sig=${res.signal}` : ''})`);
+  err.code = 'EEXIT';
+  err.exitCode = res.code;
+  err.signal = res.signal;
+  err.stdout = stdout;
+  err.stderr = stderr;
+  err.logPath = logPath;
+  throw err;
+}
+

package/scripts/utils/cli/smoke_help.mjs

@@ -0,0 +1,44 @@
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+import { gethstackRegistry } from './cli_registry.mjs';
+
+function cliRootDir() {
+  // scripts/utils/cli/* -> scripts/utils -> scripts -> repo root
+  return dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))));
+}
+
+function runOrThrow(label, args) {
+  const root = cliRootDir();
+  const bin = join(root, 'bin', 'hstack.mjs');
+  const res = spawnSync(process.execPath, [bin, ...args], { stdio: 'inherit', cwd: root, env: process.env });
+  if (res.status !== 0) {
+    throw new Error(`[smoke_help] failed (${label}): node bin/hstack.mjs ${args.join(' ')}`);
+  }
+}
+
+function visibleCommands() {
+  const { commands } = gethstackRegistry();
+  return commands.filter((c) => !c.hidden).map((c) => c.name);
+}
+
+async function main() {
+  const cmds = visibleCommands();
+  for (const c of cmds) {
+    runOrThrow(`${c} --help`, [c, '--help']);
+  }
+
+  // Also validate delegation path for a few key groups.
+  for (const c of ['wt', 'stack', 'srv', 'service', 'tailscale', 'self', 'menubar', 'completion', 'where', 'init', 'uninstall']) {
+    runOrThrow(`help ${c}`, ['help', c]);
+  }
+
+  process.stdout.write('[smoke_help] ok\n');
+}
+
+main().catch((err) => {
+  process.stderr.write(String(err?.message ?? err) + '\n');
+  process.exit(1);
+});

package/scripts/utils/cli/verbosity.mjs

@@ -0,0 +1,11 @@
+export function getVerbosityLevel(env = process.env) {
+  const raw = (env.HAPPIER_STACK_VERBOSE ?? '').toString().trim();
+  if (!raw) return 0;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return 1;
+  return Math.max(0, Math.min(3, Math.floor(n)));
+}
+
+export function isVerbose(env = process.env) {
+  return getVerbosityLevel(env) > 0;
+}