@happier-dev/stack 0.1.0-preview.5.1

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.HAPPIER_STACK_DEV_AUTH_SECRET_KEY ?? '').toString().trim()) {
+    const bytes = normalizeDevAuthKeyInputToBytes(env.HAPPIER_STACK_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:HAPPIER_STACK_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

@@ -0,0 +1,56 @@
+import { chmod, copyFile, lstat, symlink, unlink, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import { ensureDir } from '../fs/ops.mjs';
+
+export async function removeFileOrSymlinkIfExists(path) {
+  try {
+    const st = await lstat(path);
+    if (st.isDirectory()) {
+      throw new Error(`[auth] refusing to remove directory path: ${path}`);
+    }
+    await unlink(path);
+    return true;
+  } catch (e) {
+    if (e && typeof e === 'object' && 'code' in e && e.code === 'ENOENT') return false;
+    throw e;
+  }
+}
+
+export async function writeSecretFileIfMissing({ path, secret, force = false }) {
+  if (!force && existsSync(path)) return false;
+  if (force && existsSync(path)) {
+    await removeFileOrSymlinkIfExists(path);
+  }
+  await ensureDir(dirname(path));
+  await writeFile(path, secret, { encoding: 'utf-8', mode: 0o600 });
+  return true;
+}
+
+export async function copyFileIfMissing({ from, to, mode, force = false }) {
+  if (!force && existsSync(to)) return false;
+  if (!existsSync(from)) return false;
+  await ensureDir(dirname(to));
+  // IMPORTANT: if `to` is a symlink and we "overwrite" it, do NOT write through it to the symlink target.
+  if (force && existsSync(to)) {
+    await removeFileOrSymlinkIfExists(to);
+  }
+  await copyFile(from, to);
+  if (mode) {
+    await chmod(to, mode).catch(() => {});
+  }
+  return true;
+}
+
+export async function linkFileIfMissing({ from, to, force = false }) {
+  if (!force && existsSync(to)) return false;
+  if (!existsSync(from)) return false;
+  await ensureDir(dirname(to));
+  if (force && existsSync(to)) {
+    await removeFileOrSymlinkIfExists(to);
+  }
+  await symlink(from, to);
+  return true;
+}
+

package/scripts/utils/auth/guided_pr_auth.mjs

@@ -0,0 +1,86 @@
+import { isTty, promptSelect, withRl } from '../cli/wizard.mjs';
+import { detectSeedableAuthSources } from './sources.mjs';
+import { bold, cyan, dim, green } from '../ui/ansi.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 auth (${cyan(sources.join(' / '))})`,
+        value: 'seed',
+      });
+    }
+    opts.push({
+      label: defaultLoginNow ? `login now (${green('recommended')})` : 'login later',
+      value: 'login',
+    });
+    return await promptSelect(rl, {
+      title: `${bold('Authentication for this PR stack')}\n${dim('Choose whether to reuse existing credentials or do a fresh guided login.')}`,
+      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: `${bold('Which auth should we reuse?')}\n${dim('Pick the stack whose credentials should be shared into this PR stack.')}`,
+          options: sources.map((s) => ({ label: s, value: s })),
+          defaultIndex: 0,
+        });
+      });
+    }
+    const link = await withRl(async (rl) => {
+      return await promptSelect(rl, {
+        title: `${bold('Reuse mode')}\n${dim('Symlink stays up to date; copy is more isolated.')}`,
+        options: [
+          { label: `symlink (${green('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,56 @@
+import { prompt, withRl } from '../cli/wizard.mjs';
+import { openUrlInBrowser } from '../ui/browser.mjs';
+import { preferStackLocalhostUrl } from '../paths/localhost_host.mjs';
+import { bold, cyan, dim, green, yellow } from '../ui/ansi.mjs';
+
+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(`${cyan('Happier')} 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 Happier 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 Happier 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.`);
+  // eslint-disable-next-line no-console
+  console.log(dim(`Tip: if the page is blank, wait for the first build to finish, then retry.`));
+  // eslint-disable-next-line no-console
+  console.log(dim(`Tip: you can always re-run later with: ${yellow(`hstack stack auth ${stackName || 'main'} login`)}`));
+  await withRl(async (rl) => {
+    await prompt(rl, '', { defaultValue: '' });
+  });
+}

package/scripts/utils/auth/handy_master_secret.mjs

@@ -0,0 +1,42 @@
+import { join } from 'node:path';
+
+import { parseEnvToObject } from '../env/dotenv.mjs';
+import { resolveStackEnvPath } from '../paths/paths.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,
+} = {}) {
+  const name = String(stackName ?? '').trim() || 'main';
+
+  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, 'HAPPIER_STACK_HANDY_MASTER_SECRET_FILE');
+  if (secretFile) {
+    const secret = await readTextIfExists(secretFile);
+    if (secret) return { secret, source: secretFile };
+  }
+
+  const dataDir = getEnvValue(env, 'HAPPIER_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 };
+
+  return { secret: null, source: null };
+}

package/scripts/utils/auth/interactive_stack_auth.mjs

@@ -0,0 +1,70 @@
+import { isTty, promptSelect, withRl } from '../cli/wizard.mjs';
+import { detectSeedableAuthSources } from './sources.mjs';
+import { stackAuthCopyFrom } from './stack_guided_login.mjs';
+import { runOrchestratedGuidedAuthFlow } from './orchestrated_stack_auth_flow.mjs';
+import { bold, cyan, dim, green } from '../ui/ansi.mjs';
+import { findAnyCredentialPathInCliHome } from './credentials_paths.mjs';
+
+export function needsAuthSeed({ cliHomeDir, accountCount }) {
+  const hasAccessKey = Boolean(findAnyCredentialPathInCliHome({ cliHomeDir }));
+  const hasAccounts = typeof accountCount === 'number' ? accountCount > 0 : null;
+  return !hasAccessKey || hasAccounts === false;
+}
+
+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) {
+    choice = await withRl(async (rl) => {
+      const opts = [];
+      if (hasDevAuth) {
+        opts.push({ label: `reuse ${cyan('dev-auth')} (${green('recommended')}) — no re-login`, value: 'dev-auth' });
+      }
+      if (hasMain) {
+        opts.push({ label: `reuse ${cyan('main')} — fast, but shares identity with main`, value: 'main' });
+      }
+      opts.push({ label: `login now — guided browser flow`, value: 'login' });
+      return await promptSelect(rl, {
+        title: `${bold('Authentication required')}\n${dim(
+          `Stack ${cyan(stackName)} needs auth before the daemon can register a machine.`
+        )}`,
+        options: opts,
+        defaultIndex: 0,
+      });
+    });
+  }
+
+  if (choice === 'login') {
+    if (beforeLogin && typeof beforeLogin === 'function') {
+      await beforeLogin();
+    }
+    await runOrchestratedGuidedAuthFlow({
+      rootDir,
+      stackName,
+      env,
+      verbosity: 0,
+      json: false,
+    });
+    return { ok: true, skipped: false, mode: 'login' };
+  }
+
+  const from = String(choice);
+  await stackAuthCopyFrom({ rootDir, stackName, fromStackName: from, env, link: true });
+  return { ok: true, skipped: false, mode: 'seed', from, link: true };
+}

package/scripts/utils/auth/login_ux.mjs

@@ -0,0 +1,105 @@
+export function normalizeAuthLoginContext(raw) {
+  const v = String(raw ?? '')
+    .trim()
+    .toLowerCase();
+  if (v === 'selfhost' || v === 'self-host' || v === 'self_host') return 'selfhost';
+  if (v === 'dev' || v === 'developer' || v === 'development') return 'dev';
+  if (v === 'stack') return 'stack';
+  return 'generic';
+}
+
+import { bold, cyan, dim, green, yellow } from '../ui/ansi.mjs';
+import { buildConfigureServerLinks } from '@happier-dev/cli-common/links';
+
+export function printAuthLoginInstructions({
+  stackName,
+  context = 'generic',
+  webappUrl,
+  webappUrlSource,
+  internalServerUrl,
+  publicServerUrl,
+  rerunCmd,
+}) {
+  const ctx = normalizeAuthLoginContext(context);
+  const subtitle =
+    ctx === 'selfhost'
+      ? 'Self-host'
+      : ctx === 'dev'
+        ? 'Dev'
+        : ctx === 'stack'
+          ? `Stack: ${stackName || 'unknown'}`
+          : '';
+
+  // eslint-disable-next-line no-console
+  console.log('');
+  // eslint-disable-next-line no-console
+  console.log(bold(`${cyan('Happier')} login`));
+  if (subtitle) {
+    // eslint-disable-next-line no-console
+    console.log(dim(subtitle));
+  }
+  // eslint-disable-next-line no-console
+  console.log('');
+  // eslint-disable-next-line no-console
+  console.log(bold('What will happen:'));
+  // eslint-disable-next-line no-console
+  console.log(`- ${cyan('browser')}: we’ll open the Happier web app`);
+  // eslint-disable-next-line no-console
+  console.log(`- ${cyan('account')}: you’ll sign in (or create an account)`);
+  // eslint-disable-next-line no-console
+  console.log(`- ${cyan('connect')}: you’ll approve this terminal/machine connection`);
+  // eslint-disable-next-line no-console
+  console.log(`- ${cyan('finish')}: the CLI will complete automatically`);
+
+  if (webappUrl) {
+    // eslint-disable-next-line no-console
+    console.log('');
+    // eslint-disable-next-line no-console
+    console.log(`${dim('Web app:')}   ${cyan(webappUrl)}${webappUrlSource ? dim(` (${webappUrlSource})`) : ''}`);
+  }
+  if (internalServerUrl) {
+    // eslint-disable-next-line no-console
+    console.log(`${dim('Internal:')}  ${internalServerUrl}`);
+  }
+  if (publicServerUrl) {
+    // eslint-disable-next-line no-console
+    console.log(`${dim('Public:')}    ${publicServerUrl}`);
+  }
+
+  if (ctx === 'selfhost' && webappUrl && (publicServerUrl || internalServerUrl)) {
+    const serverUrl = publicServerUrl || internalServerUrl;
+    const links = buildConfigureServerLinks({ webappUrl, serverUrl });
+    // eslint-disable-next-line no-console
+    console.log('');
+    // eslint-disable-next-line no-console
+    console.log(bold('Step 0 — Configure your app/web (self-host only)'));
+    // eslint-disable-next-line no-console
+    console.log(dim('Open the link below, confirm, then sign in/create an account before approving the terminal connection.'));
+    // eslint-disable-next-line no-console
+    console.log('');
+    // eslint-disable-next-line no-console
+    console.log(`${dim('Web:')}   ${cyan(links.webUrl)}`);
+    // eslint-disable-next-line no-console
+    console.log(`${dim('Mobile:')} ${cyan(links.mobileUrl)}`);
+  }
+
+  if (ctx === 'selfhost') {
+    // eslint-disable-next-line no-console
+    console.log('');
+    // eslint-disable-next-line no-console
+    console.log(dim('Why this matters: login lets the daemon register this machine and enables sync across devices.'));
+  }
+
+  // eslint-disable-next-line no-console
+  console.log('');
+  // eslint-disable-next-line no-console
+  console.log(bold('Tips:'));
+  // eslint-disable-next-line no-console
+  console.log(`- If the page does not load, make sure the stack is running and reachable.`);
+  // eslint-disable-next-line no-console
+  console.log(`- If you see a blank page, wait for the first build (Expo/Metro) to finish.`);
+  // eslint-disable-next-line no-console
+  console.log(`- Re-run anytime: ${yellow(rerunCmd || 'hstack auth login')}`);
+  // eslint-disable-next-line no-console
+  console.log(`${green('✓')} You can safely close the browser when it finishes.`);
+}