@happier-dev/stack 0.1.0-preview.74.1

package/scripts/testkit/monorepo_port_testkit.mjs

@@ -0,0 +1,157 @@
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+
+import { run, runCapture } from '../utils/proc/proc.mjs';
+
+export async function withTempRoot(t) {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-monorepo-port-'));
+  t.after(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+  return dir;
+}
+
+export function gitEnv() {
+  const clean = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (k.startsWith('HAPPIER_STACK_')) continue;
+    clean[k] = v;
+  }
+  return {
+    ...clean,
+    GIT_AUTHOR_NAME: 'Test',
+    GIT_AUTHOR_EMAIL: 'test@example.com',
+    GIT_COMMITTER_NAME: 'Test',
+    GIT_COMMITTER_EMAIL: 'test@example.com',
+  };
+}
+
+export async function initMonorepoStub({ dir, env, seed = {}, layout = 'packages' }) {
+  await mkdir(dir, { recursive: true });
+  await run('git', ['init', '-q'], { cwd: dir, env });
+  await run('git', ['checkout', '-q', '-b', 'main'], { cwd: dir, env });
+
+  void layout;
+  await mkdir(join(dir, 'apps', 'ui'), { recursive: true });
+  await mkdir(join(dir, 'apps', 'cli'), { recursive: true });
+  await mkdir(join(dir, 'apps', 'server'), { recursive: true });
+  await writeFile(join(dir, 'apps', 'ui', 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(dir, 'apps', 'cli', 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(dir, 'apps', 'server', 'package.json'), '{}\n', 'utf-8');
+  for (const [rel, content] of Object.entries(seed)) {
+    // eslint-disable-next-line no-await-in-loop
+    await mkdir(join(dir, rel.split('/').slice(0, -1).join('/')), { recursive: true });
+    // eslint-disable-next-line no-await-in-loop
+    await writeFile(join(dir, rel), content, 'utf-8');
+  }
+  await run('git', ['add', '.'], { cwd: dir, env });
+  await run('git', ['commit', '-q', '-m', 'chore: init monorepo'], { cwd: dir, env });
+}
+
+export async function initSplitRepoStub({ dir, env, name, seed = {} }) {
+  await mkdir(dir, { recursive: true });
+  await run('git', ['init', '-q'], { cwd: dir, env });
+  await run('git', ['checkout', '-q', '-b', 'main'], { cwd: dir, env });
+  await writeFile(join(dir, 'package.json'), '{}\n', 'utf-8');
+  for (const [rel, content] of Object.entries(seed)) {
+    // eslint-disable-next-line no-await-in-loop
+    await mkdir(join(dir, rel.split('/').slice(0, -1).join('/')), { recursive: true });
+    // eslint-disable-next-line no-await-in-loop
+    await writeFile(join(dir, rel), content, 'utf-8');
+  }
+  await run('git', ['add', '.'], { cwd: dir, env });
+  await run('git', ['commit', '-q', '-m', `chore: init ${name}`], { cwd: dir, env });
+  return (await runCapture('git', ['rev-parse', 'HEAD'], { cwd: dir, env })).trim();
+}
+
+function withTimeout(task, { timeoutMs, message }) {
+  return Promise.race([
+    task,
+    new Promise((_, reject) => {
+      const timer = setTimeout(() => {
+        clearTimeout(timer);
+        reject(new Error(message));
+      }, timeoutMs);
+    }),
+  ]);
+}
+
+export function spawnNodeWithCapture(command, args, { cwd, env, stdio = ['pipe', 'pipe', 'pipe'] } = {}) {
+  const child = spawn(command, args, { cwd, env, stdio });
+  let stdout = '';
+  let stderr = '';
+  const outputWaiters = new Set();
+
+  const notify = () => {
+    for (const waiter of outputWaiters) waiter();
+  };
+
+  child.stdout?.on('data', (d) => {
+    stdout += d.toString();
+    notify();
+  });
+  child.stderr?.on('data', (d) => {
+    stderr += d.toString();
+    notify();
+  });
+
+  const getOutput = () => ({ stdout, stderr, combined: `${stdout}\n${stderr}` });
+
+  const waitForText = async (needle, timeoutMs = 10_000) => {
+    if (getOutput().combined.includes(needle)) return;
+    await withTimeout(
+      new Promise((resolve) => {
+        const check = () => {
+          if (getOutput().combined.includes(needle)) {
+            outputWaiters.delete(check);
+            resolve();
+          }
+        };
+        outputWaiters.add(check);
+      }),
+      {
+        timeoutMs,
+        message: `timeout waiting for text: ${needle}\nstdout:\n${stdout}\nstderr:\n${stderr}`,
+      }
+    );
+  };
+
+  const waitForExit = async (timeoutMs = 20_000) => {
+    if (child.exitCode != null) {
+      return { code: child.exitCode, signal: child.signalCode, ...getOutput() };
+    }
+    await withTimeout(
+      new Promise((resolve) => {
+        child.once('exit', resolve);
+      }),
+      {
+        timeoutMs,
+        message: `timeout waiting for process exit\nstdout:\n${stdout}\nstderr:\n${stderr}`,
+      }
+    );
+    return { code: child.exitCode, signal: child.signalCode, ...getOutput() };
+  };
+
+  const sendLine = (line = '') => {
+    child.stdin?.write(String(line) + '\n');
+  };
+
+  const kill = (signal = 'SIGKILL') => {
+    try {
+      child.kill(signal);
+    } catch {
+      // ignore
+    }
+  };
+
+  return {
+    child,
+    waitForText,
+    waitForExit,
+    sendLine,
+    kill,
+    getOutput,
+  };
+}

package/scripts/testkit/stack_archive_command_testkit.mjs

@@ -0,0 +1,55 @@
+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 { runCommandCapture } from './stack_script_command_testkit.mjs';
+
+async function runGitOk(args, { cwd, env }) {
+  const res = await runCommandCapture('git', args, { cwd, env });
+  assert.equal(res.code, 0, `expected git exit 0 for git ${args.join(' ')}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  return res;
+}
+
+export async function createStackArchiveFixture(t, { stackName = 'exp-test', worktreeSlug = 'archived-by-stack' } = {}) {
+  const tmp = await mkdtemp(join(tmpdir(), 'happy-stacks-stack-archive-'));
+  t.after(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  const storageDir = join(tmp, 'storage');
+  const homeDir = join(tmp, 'home');
+  const workspaceDir = join(tmp, 'workspace');
+  const repoDir = join(workspaceDir, 'main');
+  const worktreeDir = join(workspaceDir, 'pr', worktreeSlug);
+  const baseEnv = {
+    ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('HAPPIER_STACK_'))),
+    GIT_TERMINAL_PROMPT: '0',
+    HAPPIER_STACK_HOME_DIR: homeDir,
+    HAPPIER_STACK_STORAGE_DIR: storageDir,
+    HAPPIER_STACK_WORKSPACE_DIR: workspaceDir,
+  };
+
+  await mkdir(repoDir, { recursive: true });
+  await runGitOk(['init', '-b', 'main'], { cwd: repoDir, env: baseEnv });
+  await runGitOk(['config', 'user.name', 'Test'], { cwd: repoDir, env: baseEnv });
+  await runGitOk(['config', 'user.email', 'test@example.com'], { cwd: repoDir, env: baseEnv });
+  await writeFile(join(repoDir, 'README.md'), 'hello\n', 'utf-8');
+  await runGitOk(['add', 'README.md'], { cwd: repoDir, env: baseEnv });
+  await runGitOk(['commit', '-m', 'init'], { cwd: repoDir, env: baseEnv });
+
+  await mkdir(dirname(worktreeDir), { recursive: true });
+  await runGitOk(['worktree', 'add', '-b', `pr/${worktreeSlug}`, worktreeDir, 'main'], { cwd: repoDir, env: baseEnv });
+  await writeFile(join(worktreeDir, 'untracked.txt'), 'untracked\n', 'utf-8');
+
+  const envPath = join(storageDir, stackName, 'env');
+  await mkdir(dirname(envPath), { recursive: true });
+  await writeFile(envPath, [`HAPPIER_STACK_STACK=${stackName}`, `HAPPIER_STACK_REPO_DIR=${worktreeDir}`, ''].join('\n'), 'utf-8');
+
+  return {
+    stackName,
+    storageDir,
+    workspaceDir,
+    worktreeDir,
+    baseEnv,
+  };
+}

package/scripts/testkit/stack_new_monorepo_testkit.mjs

@@ -0,0 +1,83 @@
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runNodeCapture } from './stack_script_command_testkit.mjs';
+
+export async function setupStackNewMonorepoFixture({
+  importMetaUrl,
+  t,
+  tmpPrefix = 'hstack-stack-new-monorepo-',
+} = {}) {
+  const scriptsDir = dirname(fileURLToPath(importMetaUrl));
+  const rootDir = dirname(scriptsDir);
+  const tmp = await mkdtemp(join(tmpdir(), tmpPrefix));
+
+  const workspaceDir = join(tmp, 'workspace');
+  const storageDir = join(tmp, 'storage');
+  const homeDir = join(tmp, 'home');
+  const sandboxDir = join(tmp, 'sandbox');
+
+  const cleanup = async () => {
+    await rm(tmp, { recursive: true, force: true }).catch(() => {});
+  };
+  if (t?.after) t.after(cleanup);
+
+  const baseEnv = {
+    ...process.env,
+    HAPPIER_STACK_HOME_DIR: homeDir,
+    HAPPIER_STACK_WORKSPACE_DIR: workspaceDir,
+    HAPPIER_STACK_STORAGE_DIR: storageDir,
+    HAPPIER_STACK_SANDBOX_DIR: sandboxDir,
+  };
+
+  async function createMonorepoCheckout(relativePath, { includeServerPrisma = false } = {}) {
+    const monorepoRoot = join(workspaceDir, relativePath);
+    await mkdir(join(monorepoRoot, 'apps', 'ui'), { recursive: true });
+    await mkdir(join(monorepoRoot, 'apps', 'cli'), { recursive: true });
+    await mkdir(join(monorepoRoot, 'apps', 'server'), { recursive: true });
+    await writeFile(join(monorepoRoot, 'apps', 'ui', 'package.json'), '{}\n', 'utf-8');
+    await writeFile(join(monorepoRoot, 'apps', 'cli', 'package.json'), '{}\n', 'utf-8');
+    await writeFile(join(monorepoRoot, 'apps', 'server', 'package.json'), '{}\n', 'utf-8');
+    if (includeServerPrisma) {
+      await mkdir(join(monorepoRoot, 'apps', 'server', 'prisma', 'sqlite'), { recursive: true });
+      await writeFile(
+        join(monorepoRoot, 'apps', 'server', 'prisma', 'schema.prisma'),
+        'datasource db { provider = "postgresql" }\n',
+        'utf-8'
+      );
+      await writeFile(
+        join(monorepoRoot, 'apps', 'server', 'prisma', 'sqlite', 'schema.prisma'),
+        'datasource db { provider = "sqlite" }\n',
+        'utf-8'
+      );
+    }
+    return monorepoRoot;
+  }
+
+  async function runStackNew(args) {
+    return await runNodeCapture([join(rootDir, 'scripts', 'stack.mjs'), 'new', ...args], {
+      cwd: rootDir,
+      env: baseEnv,
+    });
+  }
+
+  async function readStackEnv(stackName) {
+    return await readFile(join(storageDir, stackName, 'env'), 'utf-8');
+  }
+
+  return {
+    rootDir,
+    tmp,
+    workspaceDir,
+    storageDir,
+    homeDir,
+    sandboxDir,
+    baseEnv,
+    cleanup,
+    createMonorepoCheckout,
+    runStackNew,
+    readStackEnv,
+  };
+}

package/scripts/testkit/stack_script_command_testkit.mjs

@@ -0,0 +1,27 @@
+import { spawn } from 'node:child_process';
+
+function toSpawnEnv(env, { sanitizeEnv = true } = {}) {
+  if (!sanitizeEnv) return env;
+  const cleanEnv = {};
+  for (const [key, value] of Object.entries(env ?? {})) {
+    if (value == null) continue;
+    cleanEnv[key] = String(value);
+  }
+  return cleanEnv;
+}
+
+export function runCommandCapture(command, args, { cwd, env = process.env, stdio = ['ignore', 'pipe', 'pipe'], sanitizeEnv = true } = {}) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(command, args, { cwd, env: toSpawnEnv(env, { sanitizeEnv }), stdio });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout?.on('data', (d) => (stdout += String(d)));
+    proc.stderr?.on('data', (d) => (stderr += String(d)));
+    proc.on('error', reject);
+    proc.on('exit', (code, signal) => resolve({ code: code ?? (signal ? 1 : 0), signal, stdout, stderr }));
+  });
+}
+
+export function runNodeCapture(args, options = {}) {
+  return runCommandCapture(process.execPath, args, options);
+}

package/scripts/testkit/stack_stop_sweeps_testkit.mjs

@@ -0,0 +1,172 @@
+import { spawn } from 'node:child_process';
+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 { runNodeCapture } from './stack_script_command_testkit.mjs';
+
+function toSpawnEnv(env) {
+  const runtimeKeep = ['PATH', 'HOME', 'TMPDIR', 'TMP', 'TEMP', 'SHELL', 'USER', 'LOGNAME', 'LANG', 'LC_ALL', 'TERM'];
+  const ownershipFirst = ['HAPPIER_STACK_STACK', 'HAPPIER_STACK_ENV_FILE', 'HAPPIER_STACK_PROCESS_KIND', 'npm_lifecycle_event', 'npm_package_name'];
+  const cleanEnv = {};
+  for (const key of runtimeKeep) {
+    const value = env?.[key];
+    if (value == null) continue;
+    cleanEnv[key] = String(value);
+  }
+  for (const key of ownershipFirst) {
+    const value = env?.[key];
+    if (value == null) continue;
+    cleanEnv[key] = String(value);
+  }
+  for (const [key, value] of Object.entries(env ?? {})) {
+    if (key in cleanEnv) continue;
+    if (value == null) continue;
+    if (!key.startsWith('HAPPIER_') && !key.startsWith('npm_')) continue;
+    cleanEnv[key] = String(value);
+  }
+  return cleanEnv;
+}
+
+export function spawnOwnedSleep({ env }) {
+  const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], {
+    env: toSpawnEnv(env),
+    stdio: 'ignore',
+    detached: true,
+  });
+  child.unref();
+  return child;
+}
+
+export function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function waitForProcessAlive({
+  pid,
+  timeoutMs = 2_000,
+  intervalMs = 25,
+  label = 'process',
+} = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (isAlive(pid)) return;
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  throw new Error(`[test] timeout waiting for ${label} pid=${pid} to be alive (${timeoutMs}ms)`);
+}
+
+export async function waitForProcessExit({
+  pid,
+  timeoutMs = 20_000,
+  intervalMs = 50,
+  label = 'process',
+} = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isAlive(pid)) return;
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  throw new Error(`[test] timeout waiting for ${label} pid=${pid} to exit (${timeoutMs}ms)`);
+}
+
+function terminateTrackedProcess(pid) {
+  if (!pid) return;
+  // Prefer killing the full process group when available; fall back to direct pid kill.
+  // This keeps cleanup portable across platforms where negative pid group targeting may fail.
+  try {
+    process.kill(-pid, 'SIGKILL');
+  } catch {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      // ignore
+    }
+  }
+}
+
+export async function setupStackStopSweepFixture({
+  importMetaUrl,
+  t,
+  tmpPrefix = 'hstack-stack-stop-sweep-',
+  stackName = 'exp1',
+} = {}) {
+  const scriptsDir = dirname(fileURLToPath(importMetaUrl));
+  const rootDir = dirname(scriptsDir);
+  const tmp = await mkdtemp(join(tmpdir(), tmpPrefix));
+  const homeDir = join(tmp, 'home');
+  const storageDir = join(tmp, 'storage');
+  const workspaceDir = join(tmp, 'workspace');
+  const repoDir = join(workspaceDir, 'main');
+  const baseDir = join(storageDir, stackName);
+  const envPath = join(baseDir, 'env');
+
+  await mkdir(homeDir, { recursive: true });
+  await mkdir(storageDir, { recursive: true });
+  await mkdir(repoDir, { recursive: true });
+  await mkdir(baseDir, { recursive: true });
+
+  await writeFile(
+    envPath,
+    [
+      `HAPPIER_STACK_STACK=${stackName}`,
+      'HAPPIER_STACK_SERVER_COMPONENT=happier-server-light',
+      `HAPPIER_STACK_UI_BUILD_DIR=${join(baseDir, 'ui')}`,
+      `HAPPIER_STACK_CLI_HOME_DIR=${join(baseDir, 'cli')}`,
+      `HAPPIER_STACK_REPO_DIR=${repoDir}`,
+      '',
+    ].join('\n'),
+    'utf-8'
+  );
+
+  const trackedChildren = [];
+  const trackChild = (child) => {
+    trackedChildren.push(child);
+    return child;
+  };
+
+  const cleanup = async () => {
+    for (const child of trackedChildren) {
+      if (!child?.pid) continue;
+      terminateTrackedProcess(child.pid);
+    }
+    await rm(tmp, { recursive: true, force: true }).catch(() => {});
+  };
+  if (t?.after) t.after(cleanup);
+
+  const baseEnv = {
+    ...process.env,
+    HAPPIER_STACK_HOME_DIR: homeDir,
+    HAPPIER_STACK_STORAGE_DIR: storageDir,
+    HAPPIER_STACK_WORKSPACE_DIR: workspaceDir,
+  };
+
+  async function runStackStop(extraArgs = []) {
+    return await runNodeCapture([join(rootDir, 'scripts', 'stack.mjs'), 'stop', stackName, ...extraArgs], {
+      cwd: rootDir,
+      env: baseEnv,
+    });
+  }
+
+  return {
+    rootDir,
+    tmp,
+    stackName,
+    homeDir,
+    storageDir,
+    workspaceDir,
+    repoDir,
+    baseDir,
+    envPath,
+    baseEnv,
+    trackChild,
+    runStackStop,
+    cleanup,
+  };
+}

package/scripts/testkit/worktrees_monorepo_testkit.mjs

@@ -0,0 +1,53 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export function runNode(args, { cwd, env }) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(process.execPath, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (d) => (stdout += String(d)));
+    proc.stderr.on('data', (d) => (stderr += String(d)));
+    proc.on('error', reject);
+    proc.on('close', (code, signal) => {
+      const resolvedCode = code ?? (signal ? 1 : 0);
+      const signalSuffix = signal ? `\nprocess terminated by signal: ${signal}` : '';
+      resolve({ code: resolvedCode, stdout, stderr: `${stderr}${signalSuffix}` });
+    });
+  });
+}
+
+export function createMonorepoWorktreeEnv({ homeDir, workspaceDir, sandboxDir, extraEnv = {} }) {
+  return {
+    ...process.env,
+    HAPPIER_STACK_HOME_DIR: homeDir,
+    HAPPIER_STACK_WORKSPACE_DIR: workspaceDir,
+    HAPPIER_STACK_OWNER: 'test',
+    HAPPIER_STACK_SANDBOX_DIR: sandboxDir,
+    ...extraEnv,
+  };
+}
+
+export async function createMonorepoWorktreeFixture(t, { prefix }) {
+  const tmp = await mkdtemp(join(tmpdir(), prefix));
+  t.after(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  const workspaceDir = join(tmp, 'workspace');
+  const homeDir = join(tmp, 'home');
+  const sandboxDir = join(tmp, 'sandbox');
+  const monoRoot = join(workspaceDir, 'tmp', 'test', 'mono-wt');
+
+  await mkdir(join(monoRoot, 'apps', 'ui'), { recursive: true });
+  await mkdir(join(monoRoot, 'apps', 'cli'), { recursive: true });
+  await mkdir(join(monoRoot, 'apps', 'server'), { recursive: true });
+  await writeFile(join(monoRoot, '.git'), 'gitdir: dummy\n', 'utf-8');
+  await writeFile(join(monoRoot, 'apps', 'ui', 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(monoRoot, 'apps', 'cli', 'package.json'), '{}\n', 'utf-8');
+  await writeFile(join(monoRoot, 'apps', 'server', 'package.json'), '{}\n', 'utf-8');
+
+  return { homeDir, monoRoot, sandboxDir, tmp, workspaceDir };
+}

package/scripts/tools.mjs

@@ -0,0 +1,70 @@
+import './utils/env/env.mjs';
+import { join } from 'node:path';
+
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { getRootDir } from './utils/paths/paths.mjs';
+import { run } from './utils/proc/proc.mjs';
+
+const TOOL_SCRIPTS = {
+  'setup-pr': 'scripts/setup_pr.mjs',
+  setuppr: 'scripts/setup_pr.mjs',
+  setupPR: 'scripts/setup_pr.mjs',
+
+  'review-pr': 'scripts/review_pr.mjs',
+  reviewpr: 'scripts/review_pr.mjs',
+  reviewPR: 'scripts/review_pr.mjs',
+
+  import: 'scripts/import.mjs',
+  review: 'scripts/review.mjs',
+  edison: 'scripts/edison.mjs',
+};
+
+async function main() {
+  const rootDir = getRootDir(import.meta.url);
+  const argv = process.argv.slice(2);
+  const { flags } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+
+  const positionals = argv.filter((a) => !a.startsWith('--'));
+  const cmd = (positionals[0] ?? '').trim();
+
+  const scriptRel = TOOL_SCRIPTS[cmd];
+
+  // If the user asked for help for a specific tool, delegate to that tool's script.
+  if (wantsHelp(argv, { flags }) && scriptRel && cmd && cmd !== 'help') {
+    const idx = argv.indexOf(cmd);
+    const forwarded = idx === -1 ? argv.slice(1) : [...argv.slice(0, idx), ...argv.slice(idx + 1)];
+    await run(process.execPath, [join(rootDir, scriptRel), ...forwarded], { cwd: rootDir, env: process.env });
+    return;
+  }
+
+  if (wantsHelp(argv, { flags }) || !cmd || cmd === 'help') {
+    printResult({
+      json,
+      data: { commands: ['setup-pr', 'review-pr', 'import', 'review', 'edison'] },
+      text: [
+        '[tools] usage:',
+        '  hstack tools setup-pr --repo=<pr-url|number> [--dev|--start] [--json] [-- ...]',
+        '  hstack tools review-pr --repo=<pr-url|number> [--dev|--start] [--json] [-- ...]',
+        '  hstack tools import [--json]',
+        '  hstack tools review [ui|cli|server|all] [--json]',
+        '  hstack tools edison [--stack=<name>] -- <edison args...>',
+      ].join('\n'),
+    });
+    return;
+  }
+
+  if (!scriptRel) {
+    throw new Error(`[tools] unknown tool: ${cmd}`);
+  }
+
+  const idx = argv.indexOf(cmd);
+  const forwarded = idx === -1 ? argv.slice(1) : [...argv.slice(0, idx), ...argv.slice(idx + 1)];
+  await run(process.execPath, [join(rootDir, scriptRel), ...forwarded], { cwd: rootDir, env: process.env });
+}
+
+main().catch((err) => {
+  console.error('[tools] failed:', err);
+  process.exit(1);
+});