happy-stacks 0.3.0 → 0.5.0

package/scripts/utils/stack_context.mjs

@@ -0,0 +1,23 @@
+import { getStackName, resolveStackEnvPath } from './paths/paths.mjs';
+import { getStackRuntimeStatePath } from './stack_runtime_state.mjs';
+
+export function resolveStackContext({ env = process.env, autostart = null } = {}) {
+  const explicitStack = (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim();
+  const stackName = explicitStack || (autostart?.stackName ?? '') || getStackName(env);
+  const stackMode = Boolean(explicitStack);
+
+  const envPath =
+    (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString().trim() ||
+    resolveStackEnvPath(stackName, env).envPath;
+
+  const runtimeStatePath =
+    (env.HAPPY_STACKS_RUNTIME_STATE_PATH ?? env.HAPPY_LOCAL_RUNTIME_STATE_PATH ?? '').toString().trim() ||
+    getStackRuntimeStatePath(stackName);
+
+  const explicitEphemeral =
+    (env.HAPPY_STACKS_EPHEMERAL_PORTS ?? env.HAPPY_LOCAL_EPHEMERAL_PORTS ?? '').toString().trim() === '1';
+  const ephemeral = explicitEphemeral || (stackMode && stackName !== 'main');
+
+  return { stackMode, stackName, envPath, runtimeStatePath, ephemeral };
+}
+

package/scripts/utils/stack_runtime_state.mjs

@@ -0,0 +1,104 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { resolveStackEnvPath } from './paths/paths.mjs';
+
+export function getStackRuntimeStatePath(stackName) {
+  const { baseDir } = resolveStackEnvPath(stackName);
+  return join(baseDir, 'stack.runtime.json');
+}
+
+export function isPidAlive(pid) {
+  const n = Number(pid);
+  if (!Number.isFinite(n) || n <= 1) return false;
+  try {
+    process.kill(n, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readStackRuntimeStateFile(statePath) {
+  try {
+    if (!statePath || !existsSync(statePath)) return null;
+    const raw = await readFile(statePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeStackRuntimeStateFile(statePath, state) {
+  if (!statePath) {
+    throw new Error('[stack] missing runtime state path');
+  }
+  const dir = dirname(statePath);
+  await mkdir(dir, { recursive: true }).catch(() => {});
+  const tmp = join(dir, `.stack.runtime.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
+  await writeFile(tmp, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+  await rename(tmp, statePath);
+}
+
+function isPlainObject(v) {
+  return Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+}
+
+function deepMerge(a, b) {
+  if (!isPlainObject(a) || !isPlainObject(b)) {
+    return b;
+  }
+  const out = { ...a };
+  for (const [k, v] of Object.entries(b)) {
+    if (isPlainObject(out[k]) && isPlainObject(v)) {
+      out[k] = deepMerge(out[k], v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+export async function updateStackRuntimeStateFile(statePath, patch) {
+  const existing = (await readStackRuntimeStateFile(statePath)) ?? {};
+  const next = deepMerge(existing, patch ?? {});
+  await writeStackRuntimeStateFile(statePath, next);
+  return next;
+}
+
+export async function recordStackRuntimeStart(statePath, { stackName, script, ephemeral, ownerPid, ports } = {}) {
+  const now = new Date().toISOString();
+  const existing = (await readStackRuntimeStateFile(statePath)) ?? {};
+  const startedAt = typeof existing.startedAt === 'string' && existing.startedAt.trim() ? existing.startedAt : now;
+  const next = deepMerge(existing, {
+    version: 1,
+    stackName,
+    script,
+    ephemeral: Boolean(ephemeral),
+    ownerPid,
+    ports: ports ?? {},
+    startedAt,
+    updatedAt: now,
+  });
+  await writeStackRuntimeStateFile(statePath, next);
+  return next;
+}
+
+export async function recordStackRuntimeUpdate(statePath, patch = {}) {
+  return await updateStackRuntimeStateFile(statePath, {
+    ...(patch ?? {}),
+    updatedAt: new Date().toISOString(),
+  });
+}
+
+export async function deleteStackRuntimeStateFile(statePath) {
+  try {
+    if (!statePath || !existsSync(statePath)) return;
+    await unlink(statePath);
+  } catch {
+    // ignore
+  }
+}
+

package/scripts/utils/stacks.mjs

@@ -0,0 +1,38 @@
+import { readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { getLegacyStorageRoot, getStacksStorageRoot } from './paths/paths.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './env/sandbox.mjs';
+
+export async function listAllStackNames() {
+  const names = new Set(['main']);
+  const allowLegacy = !isSandboxed() || sandboxAllowsGlobalSideEffects();
+  const roots = [
+    // New layout: ~/.happy/stacks/<name>/env
+    getStacksStorageRoot(),
+    // Legacy layout: ~/.happy/local/stacks/<name>/env
+    ...(allowLegacy ? [join(getLegacyStorageRoot(), 'stacks')] : []),
+  ];
+
+  for (const root of roots) {
+    let entries = [];
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      entries = await readdir(root, { withFileTypes: true });
+    } catch {
+      entries = [];
+    }
+    for (const ent of entries) {
+      if (!ent.isDirectory()) continue;
+      const name = ent.name;
+      if (!name || name.startsWith('.')) continue;
+      const envPath = join(root, name, 'env');
+      if (existsSync(envPath)) {
+        names.add(name);
+      }
+    }
+  }
+
+  return Array.from(names).sort();
+}

package/scripts/utils/tailscale/ip.mjs

@@ -0,0 +1,116 @@
+/**
+ * Tailscale IP detection utilities.
+ *
+ * Provides functions to detect the local Tailscale IPv4 address for port forwarding.
+ */
+
+import { runCaptureResult } from '../proc/proc.mjs';
+import { resolveCommandPath } from '../proc/commands.mjs';
+import { access, constants } from 'node:fs/promises';
+
+const TAILSCALE_TIMEOUT_MS = 3000;
+
+/**
+ * Check if a path is executable.
+ */
+async function isExecutable(path) {
+  try {
+    await access(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Tailscale env: strip XPC_SERVICE_NAME which can cause hangs in LaunchAgent contexts.
+ */
+function tailscaleEnv() {
+  const env = { ...process.env };
+  delete env.XPC_SERVICE_NAME;
+  return env;
+}
+
+/**
+ * Resolve the tailscale CLI path.
+ *
+ * Priority:
+ * 1. HAPPY_LOCAL_TAILSCALE_BIN env override
+ * 2. PATH lookup
+ * 3. macOS app bundle paths
+ */
+export async function resolveTailscaleCmd() {
+  // Explicit override
+  if (process.env.HAPPY_LOCAL_TAILSCALE_BIN?.trim()) {
+    return process.env.HAPPY_LOCAL_TAILSCALE_BIN.trim();
+  }
+
+  // Try PATH first
+  try {
+    const found = await resolveCommandPath('tailscale', { env: tailscaleEnv(), timeoutMs: TAILSCALE_TIMEOUT_MS });
+    if (found) return found;
+  } catch {
+    // ignore
+  }
+
+  // macOS app bundle paths
+  const appCliPath = '/Applications/Tailscale.app/Contents/MacOS/tailscale';
+  if (await isExecutable(appCliPath)) return appCliPath;
+
+  const appPath = '/Applications/Tailscale.app/Contents/MacOS/Tailscale';
+  if (await isExecutable(appPath)) return appPath;
+
+  return null;
+}
+
+/**
+ * Get the local Tailscale IPv4 address.
+ *
+ * @returns {Promise<string | null>} The Tailscale IPv4 address, or null if unavailable.
+ */
+export async function getTailscaleIpv4() {
+  const cmd = await resolveTailscaleCmd();
+  if (!cmd) return null;
+
+  const result = await runCaptureResult(cmd, ['ip', '-4'], {
+    env: tailscaleEnv(),
+    timeoutMs: TAILSCALE_TIMEOUT_MS,
+  });
+
+  if (!result.ok) return null;
+
+  const ip = result.out.trim().split('\n')[0]?.trim();
+  // Validate IPv4 format (basic check)
+  if (!ip || !/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(ip)) return null;
+
+  return ip;
+}
+
+/**
+ * Check if Tailscale is available and connected.
+ *
+ * @returns {Promise<boolean>}
+ */
+export async function isTailscaleAvailable() {
+  const ip = await getTailscaleIpv4();
+  return Boolean(ip);
+}
+
+/**
+ * Get Tailscale status information.
+ *
+ * @returns {Promise<{ available: boolean, ip: string | null, error: string | null }>}
+ */
+export async function getTailscaleStatus() {
+  const cmd = await resolveTailscaleCmd();
+  if (!cmd) {
+    return { available: false, ip: null, error: 'tailscale CLI not found' };
+  }
+
+  const ip = await getTailscaleIpv4();
+  if (!ip) {
+    return { available: false, ip: null, error: 'tailscale not connected or no IPv4 address' };
+  }
+
+  return { available: true, ip, error: null };
+}

package/scripts/utils/ui/ansi.mjs

@@ -0,0 +1,39 @@
+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 wrap(code, s) {
+  return supportsAnsi() ? `\x1b[${code}m${s}\x1b[0m` : String(s);
+}
+
+export function ansiEnabled() {
+  return supportsAnsi();
+}
+
+export function bold(s) {
+  return wrap('1', s);
+}
+
+export function dim(s) {
+  return wrap('2', s);
+}
+
+export function red(s) {
+  return wrap('31', s);
+}
+
+export function green(s) {
+  return wrap('32', s);
+}
+
+export function yellow(s) {
+  return wrap('33', s);
+}
+
+export function cyan(s) {
+  return wrap('36', s);
+}
+

package/scripts/utils/ui/qr.mjs

@@ -0,0 +1,17 @@
+import qrcodeTerminal from 'qrcode-terminal';
+
+export async function renderQrAscii(text, { small = true } = {}) {
+  const qrText = String(text ?? '');
+  if (!qrText) return { ok: false, lines: [], error: 'empty QR payload' };
+  try {
+    const out = await new Promise((resolvePromise) => {
+      qrcodeTerminal.generate(qrText, { small: Boolean(small) }, (qr) => resolvePromise(String(qr ?? '')));
+    });
+    // Important: keep whitespace; scanners rely on quiet-zone padding.
+    const lines = String(out ?? '').replace(/\r/g, '').split('\n');
+    return { ok: true, lines, error: null };
+  } catch (e) {
+    return { ok: false, lines: [], error: e instanceof Error ? e.message : String(e) };
+  }
+}
+

package/scripts/utils/validate.mjs

@@ -0,0 +1,88 @@
+import { readFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { getComponentsDir } from './paths/paths.mjs';
+
+function isInside(path, dir) {
+  const p = resolve(path);
+  const d = resolve(dir);
+  return p === d || p.startsWith(d.endsWith(sep) ? d : d + sep);
+}
+
+export function detectServerComponentDirMismatch({ rootDir, serverComponentName, serverDir }) {
+  const componentsDir = getComponentsDir(rootDir);
+
+  const other = serverComponentName === 'happy-server-light' ? 'happy-server' : serverComponentName === 'happy-server' ? 'happy-server-light' : null;
+  if (!other) {
+    return null;
+  }
+
+  const otherRepo = resolve(componentsDir, other);
+  const otherWts = resolve(componentsDir, '.worktrees', other);
+
+  if (isInside(serverDir, otherRepo) || isInside(serverDir, otherWts)) {
+    return { expected: serverComponentName, actual: other, serverDir };
+  }
+
+  return null;
+}
+
+export function assertServerComponentDirMatches({ rootDir, serverComponentName, serverDir }) {
+  const mismatch = detectServerComponentDirMismatch({ rootDir, serverComponentName, serverDir });
+  if (!mismatch) {
+    return;
+  }
+
+  const hint =
+    mismatch.expected === 'happy-server-light'
+      ? 'Fix: either switch flavor (`happys srv use happy-server`) or switch the active checkout for happy-server-light (`happys wt use happy-server-light default` or a worktree under .worktrees/happy-server-light/).'
+      : 'Fix: either switch flavor (`happys srv use happy-server-light`) or switch the active checkout for happy-server (`happys wt use happy-server default` or a worktree under .worktrees/happy-server/).';
+
+  throw new Error(
+    `[server] server component dir mismatch:\n` +
+      `- selected flavor: ${mismatch.expected}\n` +
+      `- but HAPPY_STACKS_COMPONENT_DIR_* points inside: ${mismatch.actual}\n` +
+      `- path: ${mismatch.serverDir}\n` +
+      `${hint}`
+  );
+}
+
+function detectPrismaProvider(schemaText) {
+  // Best-effort parse of:
+  // datasource db { provider = "sqlite" ... }
+  const m = schemaText.match(/datasource\s+db\s*\{[\s\S]*?\bprovider\s*=\s*\"([a-zA-Z0-9_-]+)\"/m);
+  return m?.[1] ?? '';
+}
+
+export function assertServerPrismaProviderMatches({ serverComponentName, serverDir }) {
+  const schemaPath = join(serverDir, 'prisma', 'schema.prisma');
+  let schemaText = '';
+  try {
+    schemaText = readFileSync(schemaPath, 'utf-8');
+  } catch {
+    // If it doesn't exist, skip validation; not every server component necessarily uses Prisma.
+    return;
+  }
+
+  const provider = detectPrismaProvider(schemaText);
+  if (!provider) {
+    return;
+  }
+
+  if (serverComponentName === 'happy-server-light' && provider !== 'sqlite') {
+    throw new Error(
+      `[server] happy-server-light expects Prisma datasource provider \"sqlite\", but found \"${provider}\" in:\n` +
+        `- ${schemaPath}\n` +
+        `This usually means you're pointing happy-server-light at an upstream happy-server checkout/PR (Postgres).\n` +
+        `Fix: either switch server flavor to happy-server, or point happy-server-light at a fork checkout that keeps sqlite support.`
+    );
+  }
+
+  if (serverComponentName === 'happy-server' && provider === 'sqlite') {
+    throw new Error(
+      `[server] happy-server expects Prisma datasource provider \"postgresql\", but found \"sqlite\" in:\n` +
+        `- ${schemaPath}\n` +
+        `Fix: either switch server flavor to happy-server-light, or point happy-server at the full-server checkout.`
+    );
+  }
+}
+

package/scripts/where.mjs

@@ -26,8 +26,8 @@ async function main() {
   if (wantsHelp(argv, { flags }) || argv.includes('help')) {
     printResult({
       json,
-      data: { flags: ['--json'], commands: ['where', 'env'] },
-      text: ['[where] usage:', '  happys where [--json]', '  happys env [--json]'].join('\n'),
+      data: { flags: ['--json'], commands: ['where'] },
+      text: ['[where] usage:', '  happys where [--json]'].join('\n'),
     });
     return;
   }