@happier-dev/stack 0.1.0-preview.5.1

package/scripts/utils/cli/wizard.mjs

@@ -0,0 +1,139 @@
+import { createInterface } from 'node:readline/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { listWorktreeSpecs } from '../git/worktrees.mjs';
+import { sanitizeSlugPart } from '../git/refs.mjs';
+import { getDevRepoDir } from '../paths/paths.mjs';
+import { bold, cyan, dim, green } from '../ui/ansi.mjs';
+import { warn } from '../ui/layout.mjs';
+
+export function isTty() {
+  const nonInteractive = (process.env.HAPPIER_STACK_NON_INTERACTIVE ?? '').toString().trim().toLowerCase();
+  if (nonInteractive === '1' || nonInteractive === 'true' || nonInteractive === 'yes' || nonInteractive === 'y') {
+    return false;
+  }
+  if (process.env.HAPPIER_STACK_TEST_TTY === '1') {
+    return true;
+  }
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+export async function withRl(fn) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await fn(rl);
+  } finally {
+    rl.close();
+  }
+}
+
+export async function prompt(rl, question, { defaultValue = '' } = {}) {
+  const raw = (await rl.question(question)).trim();
+  return raw || defaultValue;
+}
+
+export async function promptSelect(rl, { title, options, defaultIndex = 0 }) {
+  if (!options.length) {
+    throw new Error('[wizard] no options to select from');
+  }
+  // eslint-disable-next-line no-console
+  console.log('');
+  // eslint-disable-next-line no-console
+  console.log(title);
+  for (let i = 0; i < options.length; i++) {
+    const isDefault = i === defaultIndex;
+    const suffix = isDefault ? ` ${dim('(default)')}` : '';
+    // eslint-disable-next-line no-console
+    console.log(`  ${i + 1}) ${options[i].label}${suffix}`);
+  }
+  const answer = (await rl.question(`Pick [1-${options.length}] (default: ${defaultIndex + 1}): `)).trim();
+  const token = answer.match(/\d+/)?.[0] ?? '';
+  let n = defaultIndex + 1;
+  if (token) {
+    const parsed = Number(token);
+    if (Number.isFinite(parsed)) {
+      // Heuristic: in some nested-readline situations (or odd terminals), single-digit input can get duplicated
+      // (e.g. "2" becomes "22"). If that happens and all digits are identical, treat it as the intended single digit.
+      if (
+        token.length > 1 &&
+        token.split('').every((c) => c === token[0]) &&
+        Number(token[0]) >= 1 &&
+        Number(token[0]) <= options.length
+      ) {
+        n = Number(token[0]);
+      } else {
+        n = parsed;
+      }
+    }
+  }
+  const idx = Math.max(1, Math.min(options.length, Number.isFinite(n) ? n : defaultIndex + 1)) - 1;
+  return options[idx].value;
+}
+
+export async function promptWorktreeSource({ rl, rootDir, component, stackName, createRemote = 'upstream', env = process.env, deps = {} }) {
+  const promptFn = deps.prompt ?? prompt;
+  const promptSelectFn = deps.promptSelect ?? promptSelect;
+  const listWorktreeSpecsFn = deps.listWorktreeSpecs ?? listWorktreeSpecs;
+
+  const devDir = getDevRepoDir(rootDir, env);
+  const hasDev = Boolean(devDir && existsSync(join(devDir, '.git')));
+
+  const baseOptions = [{ label: `default (${dim('repo checkout')})`, value: 'default' }];
+  if (hasDev) {
+    baseOptions.push({ label: `dev (${dim('dev checkout')})`, value: 'dev' });
+  }
+  baseOptions.push({ label: `pick existing worktree`, value: 'pick' });
+  baseOptions.push({ label: `create new worktree (${cyan(createRemote)}; ${green('recommended for PRs')})`, value: 'create' });
+
+  const kind = await promptSelectFn(rl, { title: `Select ${cyan('repo')}:`, options: baseOptions, defaultIndex: 0 });
+
+  if (kind === 'default') {
+    return 'default';
+  }
+  if (kind === 'dev') {
+    return 'dev';
+  }
+  if (kind === 'pick') {
+    const specs = await listWorktreeSpecsFn({ rootDir, component });
+    const all = [
+      ...(hasDev ? [{ label: `dev (${dim('dev checkout')})`, value: 'dev' }] : []),
+      ...specs.map((s) => ({ label: s, value: s })),
+    ];
+    if (!all.length) {
+      // eslint-disable-next-line no-console
+      console.log(dim(`[wizard] no worktrees found (using default repo checkout)`));
+      return 'default';
+    }
+    const picked = await promptSelectFn(rl, {
+      title: `${bold(`Available ${cyan('repo')} worktrees`)}\n${dim('Tip: use `hstack wt new ... --use` to create more worktrees.')}`,
+      options: all,
+      defaultIndex: 0,
+    });
+    return picked;
+  }
+
+  // eslint-disable-next-line no-console
+  console.log('');
+  // eslint-disable-next-line no-console
+  console.log(bold(`Create a new ${cyan('repo')} worktree`));
+  // eslint-disable-next-line no-console
+  console.log(dim(`This will create a worktree under ${cyan('local/')}${dim('<owner>/...')} based on ${createRemote}.`));
+  while (true) {
+    // eslint-disable-next-line no-await-in-loop
+    const raw = await promptFn(rl, `New worktree slug (example: my-feature): `, { defaultValue: '' });
+    const trimmed = String(raw ?? '').trim();
+    if (!trimmed) return 'default';
+
+    const normalized = sanitizeSlugPart(trimmed);
+    if (!normalized) {
+      // eslint-disable-next-line no-console
+      console.log(warn('Invalid worktree slug. Use letters/numbers and separators like "-" (example: my-feature).'));
+      continue;
+    }
+    if (normalized !== trimmed) {
+      // eslint-disable-next-line no-console
+      console.log(dim(`Normalized slug to ${cyan(normalized)}.`));
+    }
+    return { create: true, slug: normalized, remote: createRemote };
+  }
+}

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

@@ -0,0 +1,44 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { promptSelect } from './wizard.mjs';
+
+function mkRl(answer) {
+  return { question: async () => String(answer ?? '') };
+}
+
+test('promptSelect marks the default option in the rendered list', async (t) => {
+  const lines = [];
+  t.mock.method(console, 'log', (...args) => {
+    lines.push(args.map(String).join(' '));
+  });
+  const picked = await promptSelect(mkRl(''), {
+    title: 'Pick a value:',
+    options: [
+      { label: 'One', value: 'one' },
+      { label: 'Two', value: 'two' },
+      { label: 'Three', value: 'three' },
+    ],
+    defaultIndex: 1,
+  });
+  assert.equal(picked, 'two');
+
+  const rendered = lines.join('\n');
+  assert.match(rendered, /\b2\)\s+Two\b.*\(\s*default\s*\)/i);
+  assert.doesNotMatch(rendered, /\b1\)\s+One\b.*\(\s*default\s*\)/i);
+  assert.doesNotMatch(rendered, /\b3\)\s+Three\b.*\(\s*default\s*\)/i);
+});
+
+test('promptSelect accepts duplicated single-digit input (e.g. \"22\")', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  const picked = await promptSelect(mkRl('22'), {
+    title: 'Pick:',
+    options: [
+      { label: 'One', value: 'one' },
+      { label: 'Two', value: 'two' },
+      { label: 'Three', value: 'three' },
+    ],
+    defaultIndex: 0,
+  });
+  assert.equal(picked, 'two');
+});

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

@@ -0,0 +1,132 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { promptWorktreeSource } from './wizard.mjs';
+
+async function withTempRoot(t) {
+  const root = await mkdtemp(join(tmpdir(), 'hstack-wizard-'));
+  t.after(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+  return root;
+}
+
+test('promptWorktreeSource does not list worktrees unless user selects "pick"', async () => {
+  let listed = 0;
+  const listWorktreeSpecs = async () => {
+    listed++;
+    return ['pr/123'];
+  };
+
+  const promptSelect = async () => 'default';
+  const prompt = async () => '';
+
+  const res = await promptWorktreeSource({
+    rl: {},
+    rootDir: '/tmp',
+    component: 'happier-ui',
+    stackName: 'exp1',
+    createRemote: 'upstream',
+    deps: { listWorktreeSpecs, promptSelect, prompt },
+  });
+
+  assert.equal(res, 'default');
+  assert.equal(listed, 0);
+});
+
+test('promptWorktreeSource lists worktrees when user selects "pick"', async () => {
+  let listed = 0;
+  const listWorktreeSpecs = async () => {
+    listed++;
+    return ['pr/123', 'pr/456'];
+  };
+
+  let selectCount = 0;
+  const promptSelect = async (_rl, { title }) => {
+    selectCount++;
+    if (selectCount === 1) {
+      assert.ok(title.startsWith('Select '));
+      return 'pick';
+    }
+    assert.ok(title.startsWith('Available '));
+    return 'pr/456';
+  };
+  const prompt = async () => '';
+
+  const res = await promptWorktreeSource({
+    rl: {},
+    rootDir: '/tmp',
+    component: 'happier-ui',
+    stackName: 'exp1',
+    createRemote: 'upstream',
+    deps: { listWorktreeSpecs, promptSelect, prompt },
+  });
+
+  assert.equal(res, 'pr/456');
+  assert.equal(listed, 1);
+});
+
+test('promptWorktreeSource falls back to default when pick has no available repos', async (t) => {
+  const workspaceDir = await withTempRoot(t);
+  let selectCount = 0;
+  const res = await promptWorktreeSource({
+    rl: {},
+    rootDir: '/tmp',
+    component: 'happier-ui',
+    stackName: 'exp1',
+    createRemote: 'upstream',
+    env: { ...process.env, HAPPIER_STACK_WORKSPACE_DIR: workspaceDir },
+    deps: {
+      listWorktreeSpecs: async () => [],
+      promptSelect: async (_rl, { title }) => {
+        selectCount += 1;
+        if (selectCount === 1) {
+          assert.ok(title.startsWith('Select '));
+          return 'pick';
+        }
+        throw new Error('unexpected second selection when no repos are available');
+      },
+      prompt: async () => '',
+    },
+  });
+
+  assert.equal(res, 'default');
+  assert.equal(selectCount, 1);
+});
+
+test('promptWorktreeSource offers dev when dev checkout exists (even with no category worktrees)', async (t) => {
+  const workspaceDir = await withTempRoot(t);
+  await mkdir(join(workspaceDir, 'dev'), { recursive: true });
+  const devGitFile = join(workspaceDir, 'dev', '.git');
+  await writeFile(devGitFile, 'gitdir: /tmp/fake', { encoding: 'utf8' });
+
+  const listWorktreeSpecs = async () => [];
+
+  let selectCount = 0;
+  const promptSelect = async (_rl, { title, options }) => {
+    selectCount++;
+    if (selectCount === 1) {
+      assert.ok(title.startsWith('Select '));
+      return 'pick';
+    }
+    assert.ok(title.startsWith('Available '));
+    assert.ok(options.some((o) => o.value === 'dev'));
+    return 'dev';
+  };
+  const prompt = async () => '';
+
+  const res = await promptWorktreeSource({
+    rl: {},
+    rootDir: '/tmp',
+    component: 'happier-ui',
+    stackName: 'exp1',
+    createRemote: 'upstream',
+    env: { ...process.env, HAPPIER_STACK_WORKSPACE_DIR: workspaceDir },
+    deps: { listWorktreeSpecs, promptSelect, prompt },
+  });
+
+  assert.equal(res, 'dev');
+});

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

@@ -0,0 +1,33 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { promptWorktreeSource } from './wizard.mjs';
+
+function mkRl() {
+  return { question: async () => '' };
+}
+
+test('promptWorktreeSource normalizes create worktree slug and reprompts when it sanitizes to empty', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  let asks = 0;
+  const out = await promptWorktreeSource({
+    rl: mkRl(),
+    rootDir: '/tmp/hstack-root',
+    component: 'happier-ui',
+    stackName: 'exp-slug',
+    createRemote: 'upstream',
+    deps: {
+      promptSelect: async () => 'create',
+      listWorktreeSpecs: async () => [],
+      prompt: async (_rl, question, { defaultValue } = {}) => {
+        if (String(question).includes('New worktree slug')) {
+          asks += 1;
+          return asks === 1 ? '----' : 'My Feature';
+        }
+        return defaultValue ?? '';
+      },
+    },
+  });
+
+  assert.deepEqual(out, { create: true, slug: 'my-feature', remote: 'upstream' });
+});

package/scripts/utils/crypto/tokens.mjs

@@ -0,0 +1,14 @@
+import { randomBytes } from 'node:crypto';
+
+export function base64Url(buf) {
+  return Buffer.from(buf)
+    .toString('base64')
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replaceAll('=', '');
+}
+
+export function randomToken(lenBytes = 24) {
+  return base64Url(randomBytes(lenBytes));
+}
+

package/scripts/utils/dev/daemon.mjs

@@ -0,0 +1,232 @@
+import { join, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+
+import { ensureCliBuilt, ensureDepsInstalled } from '../proc/pm.mjs';
+import { watchDebounced } from '../proc/watch.mjs';
+import { getAccountCountForServerComponent, prepareDaemonAuthSeedIfNeeded } from '../stack/startup.mjs';
+import { startLocalDaemonWithAuth } from '../../daemon.mjs';
+
+export async function ensureDevCliReady(
+  { cliDir, buildCli, env = process.env },
+  { logger = console } = {}
+) {
+  await ensureDepsInstalled(cliDir, 'happier-cli', { env });
+  const distEntrypoint = join(cliDir, 'dist', 'index.mjs');
+
+  const keepExistingDistOnBuildFailure = (error) => {
+    if (!existsSync(distEntrypoint)) return null;
+    const msg = error instanceof Error ? error.stack || error.message : String(error);
+    logger.warn(
+      `[local] happier-cli build failed; keeping previous build output at ${distEntrypoint}.`
+    );
+    logger.warn(msg);
+    return { built: false, reason: 'build_failed_using_existing_dist' };
+  };
+
+  let res;
+  try {
+    res = await ensureCliBuilt(cliDir, { buildCli, env });
+  } catch (error) {
+    const fallback = keepExistingDistOnBuildFailure(error);
+    if (fallback) return fallback;
+    throw error;
+  }
+
+  // Fail closed: dev mode must never start the daemon without a usable happier-cli build output.
+  // Even if the user disabled CLI builds globally (or build mode is "never"), missing dist will
+  // cause an immediate MODULE_NOT_FOUND crash when spawning the daemon.
+  if (!existsSync(distEntrypoint)) {
+    // Last-chance recovery: force a build once.
+    try {
+      await ensureCliBuilt(cliDir, { buildCli: true, env });
+    } catch (error) {
+      const fallback = keepExistingDistOnBuildFailure(error);
+      if (fallback) return fallback;
+      throw error;
+    }
+    if (!existsSync(distEntrypoint)) {
+      throw new Error(
+        `[local] happier-cli build output is missing.\n` +
+          `Expected: ${distEntrypoint}\n` +
+          `Fix: run the component build directly and inspect its output:\n` +
+          `  cd "${cliDir}" && yarn build`
+      );
+    }
+  }
+
+  return res;
+}
+
+export async function prepareDaemonAuthSeed({
+  rootDir,
+  env,
+  stackName,
+  cliHomeDir,
+  startDaemon,
+  isInteractive,
+  serverComponentName,
+  serverDir,
+  serverEnv,
+  quiet = false,
+}) {
+  if (!startDaemon) return { ok: true, skipped: true, reason: 'no_daemon' };
+  const acct = await getAccountCountForServerComponent({
+    serverComponentName,
+    serverDir,
+    env: serverEnv,
+    // This probe is used only for auth seeding heuristics (and should never block stack startup).
+    // For server-light (embedded PGlite), avoid doing anything that could fight for the single-connection DB.
+    bestEffort: true,
+  });
+  return await prepareDaemonAuthSeedIfNeeded({
+    rootDir,
+    env,
+    stackName,
+    cliHomeDir,
+    startDaemon,
+    isInteractive,
+    accountCount: typeof acct.accountCount === 'number' ? acct.accountCount : null,
+    quiet,
+    // IMPORTANT: run auth seeding under the same env used for server probes (includes DATABASE_URL).
+    authEnv: serverEnv,
+  });
+}
+
+export async function startDevDaemon({
+  startDaemon,
+  cliBin,
+  cliHomeDir,
+  internalServerUrl,
+  publicServerUrl,
+  restart,
+  isShuttingDown,
+  env = process.env,
+  stackName = null,
+  cliIdentity = 'default',
+}, {
+  startLocalDaemonWithAuthImpl = startLocalDaemonWithAuth,
+} = {}) {
+  if (!startDaemon) return;
+
+  await startLocalDaemonWithAuthImpl({
+    cliBin,
+    cliHomeDir,
+    internalServerUrl,
+    publicServerUrl,
+    isShuttingDown,
+    forceRestart: Boolean(restart),
+    env,
+    stackName,
+    cliIdentity,
+  });
+}
+
+export function watchHappyCliAndRestartDaemon({
+  enabled,
+  startDaemon,
+  buildCli,
+  cliDir,
+  cliBin,
+  cliHomeDir,
+  internalServerUrl,
+  publicServerUrl,
+  isShuttingDown,
+  env = process.env,
+  stackName = null,
+  cliIdentity = 'default',
+}, {
+  watchDebouncedImpl = watchDebounced,
+  ensureCliBuiltImpl = ensureCliBuilt,
+  startLocalDaemonWithAuthImpl = startLocalDaemonWithAuth,
+  existsSyncImpl = existsSync,
+  logger = console,
+} = {}) {
+  if (!enabled || !startDaemon) return null;
+
+  let inFlight = false;
+  let pending = false;
+
+  // IMPORTANT:
+  // Watch only source/config paths, not build outputs. Watching the whole repo can
+  // trigger rebuild loops because `yarn build` writes to `dist/` (and may touch other
+  // generated files), which then retriggers the watcher.
+  const watchPaths = [
+    join(cliDir, 'src'),
+    join(cliDir, 'bin'),
+    join(cliDir, 'codex'),
+    join(cliDir, 'package.json'),
+    join(cliDir, 'tsconfig.json'),
+    join(cliDir, 'tsconfig.build.json'),
+    join(cliDir, 'pkgroll.config.mjs'),
+    join(cliDir, 'yarn.lock'),
+  ].filter((p) => existsSyncImpl(p));
+
+  return watchDebouncedImpl({
+    paths: (watchPaths.length ? watchPaths : [cliDir]).map((p) => resolve(p)),
+    debounceMs: 500,
+    onChange: async () => {
+      if (isShuttingDown?.()) return;
+      if (inFlight) {
+        pending = true;
+        return;
+      }
+      inFlight = true;
+      try {
+        do {
+          pending = false;
+          if (isShuttingDown?.()) return;
+
+          logger.log('[local] watch: happier-cli changed → rebuilding + restarting daemon...');
+          try {
+            await ensureCliBuiltImpl(cliDir, { buildCli });
+          } catch (e) {
+            // IMPORTANT:
+            // - A rebuild can legitimately fail while an agent is mid-edit (e.g. TS errors).
+            // - In that case we must NOT restart the daemon (we'd just restart into a broken build),
+            //   and we must NOT crash the parent dev process. Keep watching for the next change.
+            const msg = e instanceof Error ? e.stack || e.message : String(e);
+            logger.error('[local] watch: happier-cli rebuild failed; keeping daemon running (will retry on next change).');
+            logger.error(msg);
+            if (pending) continue;
+            break;
+          }
+
+          const distEntrypoint = join(cliDir, 'dist', 'index.mjs');
+          if (!existsSyncImpl(distEntrypoint)) {
+            logger.warn(
+              `[local] watch: happier-cli build did not produce ${distEntrypoint}; refusing to restart daemon to avoid downtime.`
+            );
+            if (pending) continue;
+            break;
+          }
+
+          try {
+            await startLocalDaemonWithAuthImpl({
+              cliBin,
+              cliHomeDir,
+              internalServerUrl,
+              publicServerUrl,
+              isShuttingDown,
+              forceRestart: true,
+              env,
+              stackName,
+              cliIdentity,
+            });
+          } catch (e) {
+            const msg = e instanceof Error ? e.stack || e.message : String(e);
+            logger.error('[local] watch: daemon restart failed; keeping dev runner alive (will retry on next change).');
+            logger.error(msg);
+            if (pending) continue;
+            break;
+          }
+        } while (pending);
+      } catch (e) {
+        const msg = e instanceof Error ? e.stack || e.message : String(e);
+        logger.error('[local] watch: unexpected watcher error (continuing):');
+        logger.error(msg);
+      } finally {
+        inFlight = false;
+      }
+    },
+  });
+}