happy-stacks 0.2.0 → 0.4.0

package/scripts/uninstall.mjs

@@ -1,4 +1,4 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 
 import { rm } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
@@ -7,11 +7,11 @@ 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/canonical_home.mjs';
-import { getHappyStacksHomeDir, getRootDir, getStacksStorageRoot } from './utils/paths.mjs';
-import { getRuntimeDir } from './utils/runtime.mjs';
-import { getCanonicalHomeEnvPath } from './utils/config.mjs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.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';
 
 function resolveWorkspaceDir({ rootDir, homeDir }) {
   // Uninstall should never default to deleting the repo root (getWorkspaceDir() can fall back to cliRootDir).

package/scripts/utils/auth/daemon_gate.mjs

@@ -0,0 +1,55 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Shared policy for when the stack runner should start the Happy daemon.
+ *
+ * In `setup-pr` / `review-pr` guided login flows we intentionally start server+UI first,
+ * then guide authentication, then start daemon post-auth. Starting the daemon before
+ * credentials exist can strand it in its own auth flow (lock held, no machine registration),
+ * which leads to "no machines" in the UI.
+ */
+
+export function credentialsPathForCliHomeDir(cliHomeDir) {
+  return join(String(cliHomeDir ?? ''), 'access.key');
+}
+
+export function hasStackCredentials({ cliHomeDir }) {
+  if (!cliHomeDir) return false;
+  return existsSync(credentialsPathForCliHomeDir(cliHomeDir));
+}
+
+export function isAuthFlowEnabled(env) {
+  const v = (env?.HAPPY_STACKS_AUTH_FLOW ?? env?.HAPPY_LOCAL_AUTH_FLOW ?? '').toString().trim();
+  return v === '1' || v.toLowerCase() === 'true';
+}
+
+/**
+ * Returns { ok: boolean, reason: string } where ok=true means it's safe to start the daemon now.
+ * When ok=false, callers should either:
+ * - run interactive auth first (TTY), or
+ * - skip daemon start without error in orchestrated auth flows, or
+ * - fail closed in non-interactive contexts.
+ */
+export function daemonStartGate({ env, cliHomeDir }) {
+  if (hasStackCredentials({ cliHomeDir })) {
+    return { ok: true, reason: 'credentials_present' };
+  }
+  if (isAuthFlowEnabled(env)) {
+    // Orchestrated auth flow (setup-pr/review-pr): keep server/UI up and let the orchestrator
+    // run guided login; starting the daemon now is counterproductive.
+    return { ok: false, reason: 'auth_flow_missing_credentials' };
+  }
+  return { ok: false, reason: 'missing_credentials' };
+}
+
+export function formatDaemonAuthRequiredError({ stackName, cliHomeDir }) {
+  const name = (stackName ?? '').toString().trim() || 'main';
+  const path = credentialsPathForCliHomeDir(cliHomeDir);
+  return (
+    `[local] daemon auth required: credentials not found for stack "${name}".\n` +
+    `[local] expected: ${path}\n` +
+    `[local] fix: run \`happy auth login\` (stack-scoped), or re-run with UI enabled to complete guided login.`
+  );
+}
+

package/scripts/utils/auth/daemon_gate.test.mjs

@@ -0,0 +1,37 @@
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { daemonStartGate, hasStackCredentials } from './daemon_gate.mjs';
+
+test('hasStackCredentials detects access.key', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-daemon-gate-'));
+  assert.equal(hasStackCredentials({ cliHomeDir: dir }), false);
+  await writeFile(join(dir, 'access.key'), 'dummy', 'utf-8');
+  assert.equal(hasStackCredentials({ cliHomeDir: dir }), true);
+});
+
+test('daemonStartGate blocks daemon start in auth flow when missing credentials', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-daemon-gate-'));
+  const gate = daemonStartGate({ env: { HAPPY_STACKS_AUTH_FLOW: '1' }, cliHomeDir: dir });
+  assert.equal(gate.ok, false);
+  assert.equal(gate.reason, 'auth_flow_missing_credentials');
+});
+
+test('daemonStartGate blocks daemon start when missing credentials (non-auth flow)', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-daemon-gate-'));
+  const gate = daemonStartGate({ env: {}, cliHomeDir: dir });
+  assert.equal(gate.ok, false);
+  assert.equal(gate.reason, 'missing_credentials');
+});
+
+test('daemonStartGate allows daemon start when credentials exist', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-daemon-gate-'));
+  await writeFile(join(dir, 'access.key'), 'dummy', 'utf-8');
+  const gate = daemonStartGate({ env: {}, cliHomeDir: dir });
+  assert.equal(gate.ok, true);
+  assert.equal(gate.reason, 'credentials_present');
+});
+

package/scripts/utils/auth/dev_key.mjs

@@ -0,0 +1,163 @@
+import { chmod, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { getHappyStacksHomeDir } from '../paths/paths.mjs';
+
+export function getDevAuthKeyPath(env = process.env) {
+  return join(getHappyStacksHomeDir(env), 'keys', 'dev-auth.json');
+}
+
+function base64UrlToBytes(s) {
+  try {
+    const raw = String(s ?? '').trim();
+    if (!raw) return null;
+    const b64 = raw.replace(/-/g, '+').replace(/_/g, '/');
+    const pad = b64.length % 4 === 0 ? '' : '='.repeat(4 - (b64.length % 4));
+    return new Uint8Array(Buffer.from(b64 + pad, 'base64'));
+  } catch {
+    return null;
+  }
+}
+
+function bytesToBase64Url(bytes) {
+  const b64 = Buffer.from(bytes).toString('base64');
+  return b64.replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+
+// Base32 alphabet (RFC 4648)
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+
+function bytesToBase32(bytes) {
+  let result = '';
+  let buffer = 0;
+  let bufferLength = 0;
+
+  for (const byte of bytes) {
+    buffer = (buffer << 8) | byte;
+    bufferLength += 8;
+    while (bufferLength >= 5) {
+      bufferLength -= 5;
+      result += BASE32_ALPHABET[(buffer >> bufferLength) & 0x1f];
+    }
+  }
+  if (bufferLength > 0) {
+    result += BASE32_ALPHABET[(buffer << (5 - bufferLength)) & 0x1f];
+  }
+  return result;
+}
+
+function base32ToBytes(base32) {
+  let normalized = String(base32 ?? '')
+    .toUpperCase()
+    .replace(/0/g, 'O')
+    .replace(/1/g, 'I')
+    .replace(/8/g, 'B')
+    .replace(/9/g, 'G');
+  const cleaned = normalized.replace(/[^A-Z2-7]/g, '');
+  if (!cleaned) throw new Error('no valid base32 characters');
+
+  const bytes = [];
+  let buffer = 0;
+  let bufferLength = 0;
+  for (const char of cleaned) {
+    const value = BASE32_ALPHABET.indexOf(char);
+    if (value === -1) throw new Error('invalid base32 character');
+    buffer = (buffer << 5) | value;
+    bufferLength += 5;
+    if (bufferLength >= 8) {
+      bufferLength -= 8;
+      bytes.push((buffer >> bufferLength) & 0xff);
+    }
+  }
+  return new Uint8Array(bytes);
+}
+
+export function normalizeDevAuthKeyInputToBytes(input) {
+  const raw = String(input ?? '').trim();
+  if (!raw) return null;
+
+  // Match Happy UI behavior:
+  // - backup format is base32 and is long (usually grouped with '-' / spaces)
+  // - base64url is short (~43 chars) and may contain '-' / '_' legitimately
+  //
+  // Key point: avoid mis-parsing backup base32 as base64.
+  if (raw.length > 50) {
+    try {
+      const b32 = base32ToBytes(raw);
+      return b32.length === 32 ? b32 : null;
+    } catch {
+      return null;
+    }
+  }
+
+  const b64 = base64UrlToBytes(raw);
+  if (b64 && b64.length === 32) return b64;
+  try {
+    const b32 = base32ToBytes(raw);
+    return b32.length === 32 ? b32 : null;
+  } catch {
+    return null;
+  }
+}
+
+export function formatDevAuthKeyBackup(secretKeyBase64Url) {
+  const bytes = base64UrlToBytes(secretKeyBase64Url);
+  if (!bytes || bytes.length !== 32) throw new Error('invalid secret key (expected base64url 32 bytes)');
+  const base32 = bytesToBase32(bytes);
+  const groups = [];
+  for (let i = 0; i < base32.length; i += 5) groups.push(base32.slice(i, i + 5));
+  return groups.join('-');
+}
+
+export async function readDevAuthKey({ env = process.env } = {}) {
+  if ((env.HAPPY_STACKS_DEV_AUTH_SECRET_KEY ?? '').toString().trim()) {
+    const bytes = normalizeDevAuthKeyInputToBytes(env.HAPPY_STACKS_DEV_AUTH_SECRET_KEY);
+    if (!bytes) return { ok: false, error: 'invalid_env_key', source: 'env', secretKeyBase64Url: null, backup: null };
+    const base64url = bytesToBase64Url(bytes);
+    return { ok: true, source: 'env:HAPPY_STACKS_DEV_AUTH_SECRET_KEY', secretKeyBase64Url: base64url, backup: formatDevAuthKeyBackup(base64url) };
+  }
+
+  const path = getDevAuthKeyPath(env);
+  try {
+    if (!existsSync(path)) return { ok: true, source: `file:${path}`, secretKeyBase64Url: null, backup: null, path };
+    const raw = await readFile(path, 'utf-8');
+    const parsed = JSON.parse(raw);
+    const input = parsed?.secretKeyBase64Url ?? parsed?.secretKey ?? parsed?.key ?? null;
+    const bytes = normalizeDevAuthKeyInputToBytes(input);
+    if (!bytes) return { ok: false, error: 'invalid_file_key', source: `file:${path}`, secretKeyBase64Url: null, backup: null, path };
+    const base64url = bytesToBase64Url(bytes);
+    return { ok: true, source: `file:${path}`, secretKeyBase64Url: base64url, backup: formatDevAuthKeyBackup(base64url), path };
+  } catch (e) {
+    return { ok: false, error: 'failed_to_read', source: `file:${path}`, secretKeyBase64Url: null, backup: null, path, details: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+export async function writeDevAuthKey({ env = process.env, input } = {}) {
+  const bytes = normalizeDevAuthKeyInputToBytes(input);
+  if (!bytes || bytes.length !== 32) {
+    throw new Error('invalid secret key (expected 32 bytes; accept base64url or backup format)');
+  }
+  const secretKeyBase64Url = bytesToBase64Url(bytes);
+  const path = getDevAuthKeyPath(env);
+  await mkdir(dirname(path), { recursive: true });
+  const payload = {
+    v: 1,
+    createdAt: new Date().toISOString(),
+    secretKeyBase64Url,
+  };
+  await writeFile(path, JSON.stringify(payload, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+  await chmod(path, 0o600).catch(() => {});
+  return { ok: true, path, secretKeyBase64Url, backup: formatDevAuthKeyBackup(secretKeyBase64Url) };
+}
+
+export async function clearDevAuthKey({ env = process.env } = {}) {
+  const path = getDevAuthKeyPath(env);
+  try {
+    if (!existsSync(path)) return { ok: true, deleted: false, path };
+    await unlink(path);
+    return { ok: true, deleted: true, path };
+  } catch (e) {
+    return { ok: false, deleted: false, path, error: e instanceof Error ? e.message : String(e) };
+  }
+}

package/scripts/utils/{auth_files.mjs → auth/files.mjs}

@@ -1,10 +1,8 @@
-import { chmod, copyFile, lstat, mkdir, symlink, unlink, writeFile } from 'node:fs/promises';
+import { chmod, copyFile, lstat, symlink, unlink, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname } from 'node:path';
 
-async function ensureDir(p) {
-  await mkdir(p, { recursive: true });
-}
+import { ensureDir } from '../fs/ops.mjs';
 
 export async function removeFileOrSymlinkIfExists(path) {
   try {

package/scripts/utils/auth/guided_pr_auth.mjs

@@ -0,0 +1,79 @@
+import { isTty, promptSelect, withRl } from '../cli/wizard.mjs';
+import { detectSeedableAuthSources } from './sources.mjs';
+
+/**
+ * Decide how a PR review stack should authenticate.
+ *
+ * This deliberately does NOT offer "legacy ~/.happy" sources:
+ * for production/remote Happy installs we cannot reliably seed local DB Account rows, so it leads to broken stacks.
+ */
+export async function decidePrAuthPlan({
+  interactive = isTty(),
+  seedAuthFlag = null,
+  explicitFrom = '',
+  defaultLoginNow = true,
+} = {}) {
+  if (seedAuthFlag === false) return { mode: 'login', loginNow: defaultLoginNow };
+  if (seedAuthFlag === true) {
+    // Caller must supply from; if not, pick best available.
+    const sources = detectSeedableAuthSources();
+    const from = explicitFrom || sources[0] || 'main';
+    return { mode: 'seed', from, link: true };
+  }
+  if (explicitFrom) {
+    return { mode: 'seed', from: explicitFrom, link: true };
+  }
+
+  const sources = detectSeedableAuthSources();
+  if (!interactive) {
+    // Non-interactive default: prefer seeding only if explicitly configured elsewhere.
+    // setup-pr will handle its own defaults.
+    return { mode: 'auto', sources };
+  }
+
+  // If there's nothing to reuse, don't ask a pointless question.
+  if (!sources.length) {
+    return { mode: 'login', loginNow: defaultLoginNow, reason: 'no_seed_sources' };
+  }
+
+  // Interactive prompt: keep it simple for reviewers.
+  const choice = await withRl(async (rl) => {
+    const opts = [];
+    if (sources.length) {
+      opts.push({ label: `reuse existing Happy Stacks auth (${sources.join(' / ')})`, value: 'seed' });
+    }
+    opts.push({ label: defaultLoginNow ? 'login now (recommended)' : 'login later', value: 'login' });
+    return await promptSelect(rl, {
+      title: 'Authentication for this PR stack:',
+      options: opts,
+      defaultIndex: 0,
+    });
+  });
+
+  if (choice === 'seed' && sources.length) {
+    let from = sources[0];
+    if (sources.length > 1) {
+      from = await withRl(async (rl) => {
+        return await promptSelect(rl, {
+          title: 'Which existing auth should we reuse?',
+          options: sources.map((s) => ({ label: s, value: s })),
+          defaultIndex: 0,
+        });
+      });
+    }
+    const link = await withRl(async (rl) => {
+      return await promptSelect(rl, {
+        title: 'When reusing, symlink or copy credentials?',
+        options: [
+          { label: 'symlink (recommended) — stays up to date', value: true },
+          { label: 'copy — more isolated per stack', value: false },
+        ],
+        defaultIndex: 0,
+      });
+    });
+    return { mode: 'seed', from: String(from), link: Boolean(link) };
+  }
+
+  return { mode: 'login', loginNow: defaultLoginNow };
+}
+

package/scripts/utils/auth/guided_stack_web_login.mjs

@@ -0,0 +1,75 @@
+import { prompt, withRl } from '../cli/wizard.mjs';
+import { openUrlInBrowser } from '../ui/browser.mjs';
+import { preferStackLocalhostUrl } from '../paths/localhost_host.mjs';
+
+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 bold(s) {
+  return supportsAnsi() ? `\x1b[1m${s}\x1b[0m` : String(s);
+}
+
+function dim(s) {
+  return supportsAnsi() ? `\x1b[2m${s}\x1b[0m` : String(s);
+}
+
+function cyan(s) {
+  return supportsAnsi() ? `\x1b[36m${s}\x1b[0m` : String(s);
+}
+
+function green(s) {
+  return supportsAnsi() ? `\x1b[32m${s}\x1b[0m` : String(s);
+}
+
+export async function guidedStackWebSignupThenLogin({ webappUrl, stackName }) {
+  const url = await preferStackLocalhostUrl(webappUrl, { stackName });
+
+  // eslint-disable-next-line no-console
+  console.log('');
+  // eslint-disable-next-line no-console
+  console.log(bold('Happy login'));
+
+  // Step 1/2
+  // eslint-disable-next-line no-console
+  console.log(dim('Step 1/2 — open the web app'));
+  // eslint-disable-next-line no-console
+  console.log(`We’ll open the Happy web app so you can ${bold('create an account')} (or ${bold('log in')}).`);
+  if (url) {
+    // eslint-disable-next-line no-console
+    console.log(`${dim('URL:')} ${cyan(url)}`);
+  }
+  // eslint-disable-next-line no-console
+  console.log('');
+  // eslint-disable-next-line no-console
+  console.log(`${bold('Press Enter')} to open it in your browser.`);
+  await withRl(async (rl) => {
+    await prompt(rl, '', { defaultValue: '' });
+  });
+  if (url) {
+    await openUrlInBrowser(url);
+  }
+  // eslint-disable-next-line no-console
+  console.log(green('✓ Browser opened'));
+
+  // Step 2/2
+  // eslint-disable-next-line no-console
+  console.log('');
+  // eslint-disable-next-line no-console
+  console.log(dim('Step 2/2 — connect this terminal'));
+  // eslint-disable-next-line no-console
+  console.log(`Next, we’ll connect ${bold('this terminal')} to your Happy account.`);
+  // eslint-disable-next-line no-console
+  console.log(`When prompted, choose: ${bold('Web Browser')} ${dim('(press 2)')}.`);
+  // eslint-disable-next-line no-console
+  console.log('');
+  // eslint-disable-next-line no-console
+  console.log(`After you’ve created/logged in in the browser, ${bold('press Enter')} to continue.`);
+  await withRl(async (rl) => {
+    await prompt(rl, '', { defaultValue: '' });
+  });
+}
+

package/scripts/utils/auth/handy_master_secret.mjs

@@ -0,0 +1,68 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { parseEnvToObject } from '../env/dotenv.mjs';
+import { resolveStackEnvPath } from '../paths/paths.mjs';
+import { getLegacyHappyBaseDir, isLegacyAuthSourceName } from './sources.mjs';
+import { getEnvValue } from '../env/values.mjs';
+import { readTextIfExists } from '../fs/ops.mjs';
+import { stackExistsSync } from '../stack/stacks.mjs';
+
+export async function resolveHandyMasterSecretFromStack({
+  stackName,
+  requireStackExists = false,
+  allowLegacyAuthSource = true,
+  allowLegacyMainFallback = true,
+} = {}) {
+  const name = String(stackName ?? '').trim() || 'main';
+
+  if (isLegacyAuthSourceName(name)) {
+    if (!allowLegacyAuthSource) {
+      throw new Error(
+        '[auth] legacy auth source is disabled in sandbox mode.\n' +
+          'Reason: it reads from ~/.happy (global user state).\n' +
+          'If you really want this, set: HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1'
+      );
+    }
+    const baseDir = getLegacyHappyBaseDir();
+    const legacySecretPath = join(baseDir, 'server-light', 'handy-master-secret.txt');
+    const secret = await readTextIfExists(legacySecretPath);
+    return secret ? { secret, source: legacySecretPath } : { secret: null, source: null };
+  }
+
+  if (requireStackExists && !stackExistsSync(name)) {
+    throw new Error(`[auth] cannot copy auth: source stack "${name}" does not exist`);
+  }
+
+  const resolved = resolveStackEnvPath(name);
+  const sourceBaseDir = resolved.baseDir;
+  const sourceEnvPath = resolved.envPath;
+  const raw = await readTextIfExists(sourceEnvPath);
+  const env = raw ? parseEnvToObject(raw) : {};
+
+  const inline = getEnvValue(env, 'HANDY_MASTER_SECRET');
+  if (inline) {
+    return { secret: inline, source: `${sourceEnvPath} (HANDY_MASTER_SECRET)` };
+  }
+
+  const secretFile = getEnvValue(env, 'HAPPY_STACKS_HANDY_MASTER_SECRET_FILE');
+  if (secretFile) {
+    const secret = await readTextIfExists(secretFile);
+    if (secret) return { secret, source: secretFile };
+  }
+
+  const dataDir = getEnvValue(env, 'HAPPY_SERVER_LIGHT_DATA_DIR') || join(sourceBaseDir, 'server-light');
+  const secretPath = join(dataDir, 'handy-master-secret.txt');
+  const secret = await readTextIfExists(secretPath);
+  if (secret) return { secret, source: secretPath };
+
+  // Last-resort legacy: if main has never been migrated to stack dirs.
+  if (name === 'main' && allowLegacyMainFallback) {
+    const legacy = join(homedir(), '.happy', 'server-light', 'handy-master-secret.txt');
+    const legacySecret = await readTextIfExists(legacy);
+    if (legacySecret) return { secret: legacySecret, source: legacy };
+  }
+
+  return { secret: null, source: null };
+}
+

package/scripts/utils/auth/interactive_stack_auth.mjs

@@ -0,0 +1,72 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { isTty, prompt, withRl } from '../cli/wizard.mjs';
+import { detectSeedableAuthSources } from './sources.mjs';
+import { guidedStackAuthLoginNow, stackAuthCopyFrom } from './stack_guided_login.mjs';
+
+export function needsAuthSeed({ cliHomeDir, accountCount }) {
+  const accessKeyPath = join(cliHomeDir, 'access.key');
+  const hasAccessKey = existsSync(accessKeyPath);
+  const hasAccounts = typeof accountCount === 'number' ? accountCount > 0 : null;
+  return !hasAccessKey || hasAccounts === false;
+}
+
+function normalizeChoice(raw) {
+  const s = String(raw ?? '').trim().toLowerCase();
+  if (!s) return '';
+  return s[0];
+}
+
+export async function maybeRunInteractiveStackAuthSetup({
+  rootDir,
+  env = process.env,
+  stackName,
+  cliHomeDir,
+  accountCount,
+  isInteractive = isTty(),
+  autoSeedEnabled = false,
+  beforeLogin = null,
+} = {}) {
+  if (!isInteractive) return { ok: true, skipped: true, reason: 'non_interactive' };
+  if (autoSeedEnabled) return { ok: true, skipped: true, reason: 'auto_seed_enabled' };
+  if (!needsAuthSeed({ cliHomeDir, accountCount })) return { ok: true, skipped: true, reason: 'already_initialized' };
+
+  const sources = detectSeedableAuthSources().filter((s) => s && s !== stackName);
+  const hasDevAuth = sources.includes('dev-auth');
+  const hasMain = sources.includes('main');
+
+  let choice = 'login';
+  if (hasDevAuth || hasMain) {
+    const defaultLetter = hasDevAuth ? 'Y' : hasMain ? 'M' : 'N';
+    const promptLine =
+      `[local] auth: stack "${stackName}" needs authentication.\n` +
+      `[local] Choose one:\n` +
+      (hasDevAuth ? `  - Y: copy from dev-auth\n` : '') +
+      (hasMain ? `  - M: copy from main\n` : '') +
+      `  - N: login now\n`;
+
+    // eslint-disable-next-line no-console
+    console.log(promptLine);
+    const answer = await withRl(async (rl) => {
+      return await prompt(rl, `Pick [Y/M/N] (default: ${defaultLetter}): `, { defaultValue: defaultLetter });
+    });
+    const c = normalizeChoice(answer);
+    if (c === 'y' && hasDevAuth) choice = 'dev-auth';
+    else if (c === 'm' && hasMain) choice = 'main';
+    else if (c === 'n') choice = 'login';
+    else choice = hasDevAuth ? 'dev-auth' : hasMain ? 'main' : 'login';
+  }
+
+  if (choice === 'login') {
+    if (beforeLogin && typeof beforeLogin === 'function') {
+      await beforeLogin();
+    }
+    await guidedStackAuthLoginNow({ rootDir, stackName, env });
+    return { ok: true, skipped: false, mode: 'login' };
+  }
+
+  await stackAuthCopyFrom({ rootDir, stackName, fromStackName: String(choice), env, link: true });
+  return { ok: true, skipped: false, mode: 'seed', from: String(choice), link: true };
+}
+

package/scripts/utils/{auth_login_ux.mjs → auth/login_ux.mjs}

@@ -8,6 +8,21 @@ export function normalizeAuthLoginContext(raw) {
   return 'generic';
 }
 
+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 bold(s) {
+  return supportsAnsi() ? `\x1b[1m${s}\x1b[0m` : String(s);
+}
+
+function dim(s) {
+  return supportsAnsi() ? `\x1b[2m${s}\x1b[0m` : String(s);
+}
+
 export function printAuthLoginInstructions({
   stackName,
   context = 'generic',
@@ -18,23 +33,27 @@ export function printAuthLoginInstructions({
   rerunCmd,
 }) {
   const ctx = normalizeAuthLoginContext(context);
-  const title =
+  const subtitle =
     ctx === 'selfhost'
-      ? '[auth] login (self-host)'
+      ? 'Self-host'
       : ctx === 'dev'
-        ? '[auth] login (dev)'
+        ? 'Dev'
         : ctx === 'stack'
-          ? `[auth] login (stack=${stackName || 'unknown'})`
-          : '[auth] login';
+          ? `Stack: ${stackName || 'unknown'}`
+          : '';
 
   // eslint-disable-next-line no-console
   console.log('');
   // eslint-disable-next-line no-console
-  console.log(title);
+  console.log(bold('Happy login'));
+  if (subtitle) {
+    // eslint-disable-next-line no-console
+    console.log(dim(subtitle));
+  }
   // eslint-disable-next-line no-console
-  console.log('[auth] steps:');
+  console.log('Steps:');
   // eslint-disable-next-line no-console
-  console.log('  1) A browser window will open for authentication');
+  console.log('  1) A browser window will open');
   // eslint-disable-next-line no-console
   console.log('  2) Sign in (or create an account if this is your first time)');
   // eslint-disable-next-line no-console
@@ -46,28 +65,28 @@ export function printAuthLoginInstructions({
     // eslint-disable-next-line no-console
     console.log('');
     // eslint-disable-next-line no-console
-    console.log(`[auth] webapp:   ${webappUrl}${webappUrlSource ? ` (${webappUrlSource})` : ''}`);
+    console.log(`Web app:   ${webappUrl}${webappUrlSource ? ` (${webappUrlSource})` : ''}`);
   }
   if (internalServerUrl) {
     // eslint-disable-next-line no-console
-    console.log(`[auth] internal: ${internalServerUrl}`);
+    console.log(`Internal:  ${internalServerUrl}`);
   }
   if (publicServerUrl) {
     // eslint-disable-next-line no-console
-    console.log(`[auth] public:   ${publicServerUrl}`);
+    console.log(`Public:    ${publicServerUrl}`);
   }
 
   if (ctx === 'selfhost') {
     // eslint-disable-next-line no-console
     console.log('');
     // eslint-disable-next-line no-console
-    console.log('[auth] note: this is required so the daemon can register this machine and sync sessions across devices.');
+    console.log(dim('Note: this is required so the daemon can register this machine and sync sessions across devices.'));
   }
 
   // eslint-disable-next-line no-console
   console.log('');
   // eslint-disable-next-line no-console
-  console.log('[auth] tips:');
+  console.log('Tips:');
   // eslint-disable-next-line no-console
   console.log('- If the browser page does not load, make sure Happy is running and reachable.');
   // eslint-disable-next-line no-console