happy-stacks 0.0.0

package/extras/swiftbar/wt-pr.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+set -euo pipefail
+
+# Create a PR worktree (optionally scoped to a stack).
+#
+# Usage:
+#   ./wt-pr.sh <component> [stackName]
+#
+# Examples:
+#   ./wt-pr.sh happy
+#   ./wt-pr.sh happy-cli exp1
+#
+# Notes:
+# - Uses an AppleScript prompt so it works well from SwiftBar without needing Terminal input.
+# - Defaults to using the chosen remote's PR head ref and uses --use so the component becomes active.
+
+COMPONENT="${1:-}"
+STACK_NAME="${2:-}"
+
+HAPPY_STACKS_HOME_DIR="${HAPPY_STACKS_HOME_DIR:-$HOME/.happy-stacks}"
+HAPPY_LOCAL_DIR="${HAPPY_LOCAL_DIR:-$HAPPY_STACKS_HOME_DIR}"
+
+HAPPYS="$HAPPY_LOCAL_DIR/extras/swiftbar/pnpm.sh"
+if [[ ! -x "$HAPPYS" ]]; then
+  HAPPYS="$(command -v happys 2>/dev/null || true)"
+fi
+if [[ -z "$HAPPYS" ]]; then
+  echo "happys not found (run: happys init)" >&2
+  exit 1
+fi
+
+if ! command -v osascript >/dev/null 2>&1; then
+  echo "osascript not available" >&2
+  exit 1
+fi
+
+if [[ "$COMPONENT" == "_prompt_" ]]; then
+  COMPONENT=""
+fi
+
+if [[ -z "$COMPONENT" ]]; then
+  COMPONENT="$(osascript <<'APPLESCRIPT'
+tell application "System Events"
+  activate
+  set theChoice to choose from list {"happy", "happy-cli", "happy-server-light", "happy-server"} with title "Happy Stacks — Component" with prompt "Choose component:" default items {"happy"}
+  if theChoice is false then
+    return ""
+  end if
+  return item 1 of theChoice
+end tell
+APPLESCRIPT
+)" || true
+  COMPONENT="$(echo "${COMPONENT:-}" | tr -d '\r' | xargs || true)"
+  if [[ -z "$COMPONENT" ]]; then
+    echo "cancelled" >&2
+    exit 0
+  fi
+fi
+
+PR_INPUT="$(osascript <<'APPLESCRIPT'
+tell application "System Events"
+  activate
+  set theDialogText to text returned of (display dialog "PR URL or number:" default answer "" with title "Happy Stacks — PR worktree")
+  return theDialogText
+end tell
+APPLESCRIPT
+)" || true
+
+PR_INPUT="$(echo "${PR_INPUT:-}" | tr -d '\r' | xargs || true)"
+if [[ -z "$PR_INPUT" ]]; then
+  echo "cancelled" >&2
+  exit 0
+fi
+
+REMOTE_CHOICE="$(osascript <<'APPLESCRIPT'
+tell application "System Events"
+  activate
+  set theChoice to button returned of (display dialog "Remote to fetch PR from:" with title "Happy Stacks — PR remote" buttons {"upstream", "origin"} default button "upstream")
+  return theChoice
+end tell
+APPLESCRIPT
+)" || true
+
+REMOTE_CHOICE="$(echo "${REMOTE_CHOICE:-upstream}" | tr -d '\r' | xargs || true)"
+if [[ -z "$REMOTE_CHOICE" ]]; then
+  REMOTE_CHOICE="upstream"
+fi
+
+if [[ -n "$STACK_NAME" && "$STACK_NAME" != "main" ]]; then
+  "$HAPPYS" stack wt "$STACK_NAME" -- pr "$COMPONENT" "$PR_INPUT" --remote="$REMOTE_CHOICE" --use
+else
+  "$HAPPYS" wt pr "$COMPONENT" "$PR_INPUT" --remote="$REMOTE_CHOICE" --use
+fi
+
+echo "ok"

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "happy-stacks",
+  "type": "module",
+  "version": "0.0.0",
+  "packageManager": "pnpm@10.18.3",
+  "bin": {
+    "happys": "./bin/happys.mjs",
+    "happy-stacks": "./bin/happys.mjs"
+  },
+  "files": [
+    "bin/",
+    "docs/",
+    "extras/",
+    "scripts/"
+  ],
+  "scripts": {
+    "init": "node ./scripts/init.mjs",
+    "uninstall": "node ./scripts/uninstall.mjs",
+    "where": "node ./scripts/where.mjs",
+    "self": "node ./scripts/self.mjs",
+    "bootstrap": "node ./scripts/install.mjs",
+    "build": "node ./scripts/build.mjs",
+    "start": "node ./scripts/run.mjs",
+    "dev": "node ./scripts/dev.mjs",
+    "happy": "node ./scripts/happy.mjs",
+    "wt": "node ./scripts/worktrees.mjs",
+    "srv": "node ./scripts/server_flavor.mjs",
+    "server-flavor": "node ./scripts/server_flavor.mjs",
+    "stack": "node ./scripts/stack.mjs",
+    "mobile": "node ./scripts/mobile.mjs",
+    "mobile:prebuild": "node ./scripts/mobile.mjs --prebuild --clean --no-metro",
+    "mobile:ios": "node ./scripts/mobile.mjs --run-ios --no-metro",
+    "mobile:ios:release": "node ./scripts/mobile.mjs --run-ios --no-metro --configuration=Release",
+    "mobile:install": "node ./scripts/mobile.mjs --run-ios --no-metro --configuration=Release",
+    "mobile:devices": "xcrun xcdevice list",
+    "cli:link": "node ./scripts/cli-link.mjs",
+    "auth": "node ./scripts/auth.mjs",
+    "service:status": "node ./scripts/service.mjs status",
+    "service:start": "node ./scripts/service.mjs start",
+    "service:stop": "node ./scripts/service.mjs stop",
+    "service:restart": "node ./scripts/service.mjs restart",
+    "service:enable": "node ./scripts/service.mjs enable",
+    "service:disable": "node ./scripts/service.mjs disable",
+    "service:install": "node ./scripts/service.mjs install",
+    "service:uninstall": "node ./scripts/service.mjs uninstall",
+    "tailscale:status": "node ./scripts/tailscale.mjs status",
+    "tailscale:url": "node ./scripts/tailscale.mjs url",
+    "tailscale:enable": "node ./scripts/tailscale.mjs enable",
+    "tailscale:disable": "node ./scripts/tailscale.mjs disable",
+    "stack:doctor": "node ./scripts/doctor.mjs",
+    "stack:fix": "node ./scripts/doctor.mjs --fix",
+    "logs": "node ./scripts/service.mjs logs",
+    "logs:tail": "node ./scripts/service.mjs tail",
+    "menubar:install": "node ./scripts/menubar.mjs install",
+    "menubar:uninstall": "node ./scripts/menubar.mjs uninstall",
+    "menubar:open": "bash -lc 'DIR=\"$(defaults read com.ameba.SwiftBar PluginDirectory 2>/dev/null)\"; if [[ -z \"$DIR\" ]]; then DIR=\"$HOME/Library/Application Support/SwiftBar/Plugins\"; fi; open \"$DIR\"'"
+  }
+}

package/scripts/auth.mjs

@@ -0,0 +1,272 @@
+import './utils/env.mjs';
+import { parseArgs } from './utils/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
+import { getComponentDir, getDefaultAutostartPaths, getRootDir, getStackName } from './utils/paths.mjs';
+import { resolvePublicServerUrl } from './tailscale.mjs';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { spawn } from 'node:child_process';
+
+function getInternalServerUrl() {
+  const portRaw = (process.env.HAPPY_LOCAL_SERVER_PORT ?? process.env.HAPPY_STACKS_SERVER_PORT ?? '').trim();
+  const port = portRaw ? Number(portRaw) : 3005;
+  const n = Number.isFinite(port) ? port : 3005;
+  return { port: n, url: `http://127.0.0.1:${n}` };
+}
+
+function expandTilde(p) {
+  return p.replace(/^~(?=\/)/, homedir());
+}
+
+function resolveCliHomeDir() {
+  const fromEnv = (process.env.HAPPY_LOCAL_CLI_HOME_DIR ?? process.env.HAPPY_STACKS_CLI_HOME_DIR ?? '').trim();
+  if (fromEnv) {
+    return expandTilde(fromEnv);
+  }
+  return join(getDefaultAutostartPaths().baseDir, 'cli');
+}
+
+function fileHasContent(path) {
+  try {
+    if (!existsSync(path)) return false;
+    return readFileSync(path, 'utf-8').trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function checkDaemonState(cliHomeDir) {
+  const statePath = join(cliHomeDir, 'daemon.state.json');
+  const lockPath = join(cliHomeDir, 'daemon.state.json.lock');
+
+  const alive = (pid) => {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  if (existsSync(statePath)) {
+    try {
+      const state = JSON.parse(readFileSync(statePath, 'utf-8'));
+      const pid = Number(state?.pid);
+      if (Number.isFinite(pid) && pid > 0) {
+        return alive(pid) ? { status: 'running', pid } : { status: 'stale_state', pid };
+      }
+      return { status: 'bad_state' };
+    } catch {
+      return { status: 'bad_state' };
+    }
+  }
+
+  if (existsSync(lockPath)) {
+    try {
+      const pid = Number(readFileSync(lockPath, 'utf-8').trim());
+      if (Number.isFinite(pid) && pid > 0) {
+        return alive(pid) ? { status: 'starting', pid } : { status: 'stale_lock', pid };
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  return { status: 'stopped' };
+}
+
+async function fetchHealth(internalServerUrl) {
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort(), 1500);
+  try {
+    const res = await fetch(`${internalServerUrl}/health`, { method: 'GET', signal: ctl.signal });
+    const body = (await res.text()).trim();
+    return { ok: res.ok, status: res.status, body };
+  } catch {
+    return { ok: false, status: null, body: null };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+function authLoginSuggestion(stackName) {
+  return stackName === 'main' ? 'happys auth login' : `happys stack auth ${stackName} login`;
+}
+
+async function cmdStatus({ json }) {
+  const rootDir = getRootDir(import.meta.url);
+  const stackName = getStackName();
+
+  const { port, url: internalServerUrl } = getInternalServerUrl();
+  const defaultPublicUrl = `http://localhost:${port}`;
+  const envPublicUrl = (process.env.HAPPY_LOCAL_SERVER_URL ?? process.env.HAPPY_STACKS_SERVER_URL ?? '').trim();
+  const { publicServerUrl } = await resolvePublicServerUrl({
+    internalServerUrl,
+    defaultPublicUrl,
+    envPublicUrl,
+    allowEnable: false,
+  });
+
+  const cliHomeDir = resolveCliHomeDir();
+  const accessKeyPath = join(cliHomeDir, 'access.key');
+  const settingsPath = join(cliHomeDir, 'settings.json');
+
+  const auth = {
+    ok: fileHasContent(accessKeyPath),
+    accessKeyPath,
+    hasAccessKey: fileHasContent(accessKeyPath),
+    settingsPath,
+    hasSettings: fileHasContent(settingsPath),
+  };
+
+  const daemon = checkDaemonState(cliHomeDir);
+  const health = await fetchHealth(internalServerUrl);
+
+  const out = {
+    stackName,
+    internalServerUrl,
+    publicServerUrl,
+    cliHomeDir,
+    auth,
+    daemon,
+    serverHealth: health,
+    cliBin: join(getComponentDir(rootDir, 'happy-cli'), 'bin', 'happy.mjs'),
+  };
+
+  if (json) {
+    printResult({ json, data: out });
+    return;
+  }
+
+  const authLine = auth.ok ? '✅ auth: ok' : '❌ auth: required';
+  const daemonLine =
+    daemon.status === 'running'
+      ? `✅ daemon: running (pid=${daemon.pid})`
+      : daemon.status === 'starting'
+        ? `⏳ daemon: starting (pid=${daemon.pid})`
+        : daemon.status === 'stale_state'
+          ? `⚠️ daemon: stale state file (pid=${daemon.pid} not running)`
+          : daemon.status === 'stale_lock'
+            ? `⚠️ daemon: stale lock file (pid=${daemon.pid} not running)`
+            : daemon.status === 'bad_state'
+              ? '⚠️ daemon: unreadable state'
+              : '❌ daemon: not running';
+
+  const serverLine = health.ok ? `✅ server: healthy (${health.status})` : `⚠️ server: unreachable (${internalServerUrl})`;
+
+  console.log(`[auth] stack: ${stackName}`);
+  console.log(`[auth] urls: internal=${internalServerUrl} public=${publicServerUrl}`);
+  console.log(`[auth] cli:  ${cliHomeDir}`);
+  console.log('');
+  console.log(authLine);
+  if (!auth.ok) {
+    console.log(`  ↪ run: ${authLoginSuggestion(stackName)}`);
+  }
+  console.log(daemonLine);
+  console.log(serverLine);
+  if (auth.ok && daemon.status !== 'running') {
+    console.log(`  ↪ auth is OK; this looks like a daemon/runtime issue. Try: happys doctor`);
+  }
+}
+
+async function cmdLogin({ argv, json }) {
+  const rootDir = getRootDir(import.meta.url);
+  const stackName = getStackName();
+
+  const { port, url: internalServerUrl } = getInternalServerUrl();
+  const defaultPublicUrl = `http://localhost:${port}`;
+  const envPublicUrl = (process.env.HAPPY_LOCAL_SERVER_URL ?? process.env.HAPPY_STACKS_SERVER_URL ?? '').trim();
+  const { publicServerUrl } = await resolvePublicServerUrl({
+    internalServerUrl,
+    defaultPublicUrl,
+    envPublicUrl,
+    allowEnable: false,
+  });
+
+  const cliHomeDir = resolveCliHomeDir();
+  const cliBin = join(getComponentDir(rootDir, 'happy-cli'), 'bin', 'happy.mjs');
+
+  const force = !argv.includes('--no-force');
+  const wantPrint = argv.includes('--print');
+
+  const nodeArgs = [cliBin, 'auth', 'login'];
+  if (force || argv.includes('--force')) {
+    nodeArgs.push('--force');
+  }
+
+  const env = {
+    ...process.env,
+    HAPPY_HOME_DIR: cliHomeDir,
+    HAPPY_SERVER_URL: internalServerUrl,
+    HAPPY_WEBAPP_URL: publicServerUrl,
+  };
+
+  if (wantPrint) {
+    const cmd = `HAPPY_HOME_DIR="${cliHomeDir}" HAPPY_SERVER_URL="${internalServerUrl}" HAPPY_WEBAPP_URL="${publicServerUrl}" node "${cliBin}" auth login${nodeArgs.includes('--force') ? ' --force' : ''}`;
+    if (json) {
+      printResult({ json, data: { ok: true, stackName, cmd } });
+    } else {
+      console.log(cmd);
+    }
+    return;
+  }
+
+  if (!json) {
+    console.log(`[auth] stack: ${stackName}`);
+    console.log(`[auth] launching login...`);
+  }
+
+  const child = spawn(process.execPath, nodeArgs, {
+    cwd: rootDir,
+    env,
+    stdio: 'inherit',
+  });
+
+  await new Promise((resolve) => child.on('exit', resolve));
+  if (json) {
+    printResult({ json, data: { ok: child.exitCode === 0, exitCode: child.exitCode } });
+  } else if (child.exitCode && child.exitCode !== 0) {
+    process.exit(child.exitCode);
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+
+  const cmd = argv.find((a) => !a.startsWith('--')) || 'status';
+  if (wantsHelp(argv, { flags }) || cmd === 'help') {
+    printResult({
+      json,
+      data: { commands: ['status', 'login'], stackScoped: 'happys stack auth <name> status|login' },
+      text: [
+        '[auth] usage:',
+        '  happys auth status [--json]',
+        '  happys auth login [--force] [--print] [--json]',
+        '',
+        'stack-scoped:',
+        '  happys stack auth <name> status [--json]',
+        '  happys stack auth <name> login [--force] [--print] [--json]',
+      ].join('\n'),
+    });
+    return;
+  }
+
+  if (cmd === 'status') {
+    await cmdStatus({ json });
+    return;
+  }
+  if (cmd === 'login') {
+    await cmdLogin({ argv, json });
+    return;
+  }
+
+  throw new Error(`[auth] unknown command: ${cmd}`);
+}
+
+main().catch((err) => {
+  console.error('[auth] failed:', err);
+  process.exit(1);
+});

package/scripts/build.mjs

@@ -0,0 +1,204 @@
+import './utils/env.mjs';
+import { parseArgs } from './utils/args.mjs';
+import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths.mjs';
+import { ensureDepsInstalled, pmExecBin, requireDir } from './utils/pm.mjs';
+import { dirname, join } from 'node:path';
+import { readFile, rm, mkdir, writeFile } from 'node:fs/promises';
+import { tailscaleServeHttpsUrl } from './tailscale.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
+
+/**
+ * Build a lightweight static web UI bundle (no Expo dev server).
+ *
+ * Output directory default: ~/.happy/stacks/main/ui (legacy: ~/.happy/local/ui)
+ * Server will serve it at / when HAPPY_SERVER_LIGHT_UI_DIR is set.
+ * (Legacy /ui paths are redirected to /.)
+ */
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+  if (wantsHelp(argv, { flags })) {
+    printResult({
+      json,
+      data: { flags: ['--tauri', '--no-tauri'], json: true },
+      text: [
+        '[build] usage:',
+        '  happys build [--tauri] [--json]',
+        '  (legacy in a cloned repo): pnpm build [-- --tauri] [--json]',
+        '  node scripts/build.mjs [--tauri|--no-tauri] [--json]',
+      ].join('\n'),
+    });
+    return;
+  }
+  const rootDir = getRootDir(import.meta.url);
+  const uiDir = getComponentDir(rootDir, 'happy');
+  await requireDir('happy', uiDir);
+
+  const serverPort = process.env.HAPPY_LOCAL_SERVER_PORT
+    ? parseInt(process.env.HAPPY_LOCAL_SERVER_PORT, 10)
+    : 3005;
+
+  // For Tauri builds we embed an explicit API base URL (tauri:// origins cannot use window.location.origin).
+  const internalServerUrl = `http://127.0.0.1:${serverPort}`;
+
+  const outDir = process.env.HAPPY_LOCAL_UI_BUILD_DIR?.trim()
+    ? process.env.HAPPY_LOCAL_UI_BUILD_DIR.trim()
+    : join(getDefaultAutostartPaths().baseDir, 'ui');
+
+  // UI is served at root; /ui redirects to /.
+
+  await ensureDepsInstalled(uiDir, 'happy');
+
+  // Clean output to avoid stale assets.
+  await rm(outDir, { recursive: true, force: true });
+  await mkdir(outDir, { recursive: true });
+
+  console.log(`[local] exporting web UI to ${outDir}...`);
+
+  // Build for root hosting (the server redirects /ui -> /).
+  const env = {
+    ...process.env,
+    NODE_ENV: 'production',
+    EXPO_PUBLIC_DEBUG: '0',
+    // Leave empty for web export so the app uses window.location.origin at runtime.
+    // (Important for Tailscale: a phone loading `http://100.x.y.z:3005` must not call `http://localhost:3005`.)
+    EXPO_PUBLIC_HAPPY_SERVER_URL: '',
+  };
+
+  // Expo CLI is available via node_modules/.bin once dependencies are installed.
+  await pmExecBin({ dir: uiDir, bin: 'expo', args: ['export', '--platform', 'web', '--output-dir', outDir], env });
+
+  if (json) {
+    printResult({ json, data: { ok: true, outDir, tauriBuilt: false } });
+  } else {
+  console.log('[local] UI build complete');
+  }
+
+  //
+  // Tauri build (optional)
+  //
+  // Default: do NOT build Tauri (it's slow and requires extra toolchain).
+  // Enable explicitly with:
+  // - `happys build -- --tauri`, or
+  // - `HAPPY_LOCAL_BUILD_TAURI=1`
+  const envBuildTauri = (process.env.HAPPY_LOCAL_BUILD_TAURI ?? '').trim();
+  const buildTauriFromEnv = envBuildTauri !== '' ? envBuildTauri !== '0' : false;
+  const buildTauri = !flags.has('--no-tauri') && (flags.has('--tauri') || buildTauriFromEnv);
+  if (!buildTauri) {
+    return;
+  }
+
+  // Default to debug builds for local development so devtools are available.
+  const tauriDebug = (process.env.HAPPY_LOCAL_TAURI_DEBUG ?? '1') === '1';
+
+  // Choose the API endpoint the Tauri app should use.
+  //
+  // Priority:
+  // 1) HAPPY_LOCAL_TAURI_SERVER_URL (explicit override)
+  // 2) If available, a Tailscale Serve https://*.ts.net URL (portable across machines on the same tailnet)
+  // 3) Fallback to internal loopback (same-machine)
+  const tauriServerUrlOverride = process.env.HAPPY_LOCAL_TAURI_SERVER_URL?.trim()
+    ? process.env.HAPPY_LOCAL_TAURI_SERVER_URL.trim()
+    : '';
+  const preferTailscale = (process.env.HAPPY_LOCAL_TAURI_PREFER_TAILSCALE ?? '1') !== '0';
+  const tailscaleUrl = preferTailscale ? await tailscaleServeHttpsUrl() : null;
+  const tauriServerUrl = tauriServerUrlOverride || tailscaleUrl || internalServerUrl;
+
+  const tauriDistDir = process.env.HAPPY_LOCAL_TAURI_UI_DIR?.trim()
+    ? process.env.HAPPY_LOCAL_TAURI_UI_DIR.trim()
+    : join(uiDir, 'dist');
+
+  await rm(tauriDistDir, { recursive: true, force: true });
+  await mkdir(tauriDistDir, { recursive: true });
+
+  console.log(`[local] exporting web UI for Tauri to ${tauriDistDir}...`);
+
+  const tauriEnv = {
+    ...process.env,
+    NODE_ENV: 'production',
+    EXPO_PUBLIC_DEBUG: '0',
+    // In Tauri, window.location.origin is a tauri:// origin, so we must hardcode the API base.
+    EXPO_PUBLIC_HAPPY_SERVER_URL: tauriServerUrl,
+    // Some parts of the app use EXPO_PUBLIC_SERVER_URL; keep them aligned.
+    EXPO_PUBLIC_SERVER_URL: tauriServerUrl,
+    // For the Tauri bundle we want root-relative assets (no /ui baseUrl), so do not set EXPO_PUBLIC_WEB_BASE_URL
+  };
+  delete tauriEnv.EXPO_PUBLIC_WEB_BASE_URL;
+
+  await pmExecBin({
+    dir: uiDir,
+    bin: 'expo',
+    // Important: clear bundler cache so EXPO_PUBLIC_* inlining doesn't reuse
+    // the previous (web) export's transform results.
+    args: ['export', '--platform', 'web', '--output-dir', tauriDistDir, '-c'],
+    env: tauriEnv,
+  });
+
+  // Build the Tauri app using a generated config that skips upstream beforeBuildCommand (which uses yarn).
+  const tauriConfigPath = join(uiDir, 'src-tauri', 'tauri.conf.json');
+  const tauriConfigRaw = await readFile(tauriConfigPath, 'utf-8');
+  const tauriConfig = JSON.parse(tauriConfigRaw);
+  tauriConfig.build = tauriConfig.build ?? {};
+  // Prefer the upstream relative dist dir when possible (less surprising for Tauri tooling).
+  tauriConfig.build.frontendDist = tauriDistDir === join(uiDir, 'dist') ? '../dist' : tauriDistDir;
+  tauriConfig.build.beforeBuildCommand = null;
+  tauriConfig.build.beforeDevCommand = null;
+
+  // Build a separate "local" app so it doesn't reuse previous storage (server URL, auth, etc).
+  // This avoids needing any changes in the Happy source code to override a previously saved server.
+  tauriConfig.identifier = process.env.HAPPY_LOCAL_TAURI_IDENTIFIER?.trim()
+    ? process.env.HAPPY_LOCAL_TAURI_IDENTIFIER.trim()
+    : 'com.happy.stacks';
+  tauriConfig.productName = process.env.HAPPY_LOCAL_TAURI_PRODUCT_NAME?.trim()
+    ? process.env.HAPPY_LOCAL_TAURI_PRODUCT_NAME.trim()
+    : 'Happy Stacks';
+  if (tauriConfig.app?.windows?.length) {
+    tauriConfig.app.windows = tauriConfig.app.windows.map((w) => ({
+      ...w,
+      title: tauriConfig.productName ?? w.title,
+    }));
+  }
+
+  if (tauriDebug) {
+    // Enable devtools in debug builds (useful for troubleshooting connectivity).
+    tauriConfig.app = tauriConfig.app ?? {};
+    tauriConfig.app.windows = Array.isArray(tauriConfig.app.windows) ? tauriConfig.app.windows : [];
+    if (tauriConfig.app.windows.length > 0) {
+      tauriConfig.app.windows = tauriConfig.app.windows.map((w) => ({ ...w, devtools: true }));
+    }
+  }
+
+  const generatedConfigPath = join(getDefaultAutostartPaths().baseDir, 'tauri.conf.happy-stacks.json');
+  await mkdir(dirname(generatedConfigPath), { recursive: true });
+  await writeFile(generatedConfigPath, JSON.stringify(tauriConfig, null, 2), 'utf-8');
+
+  console.log('[local] building Tauri app...');
+  const cargoTargetDir = join(getDefaultAutostartPaths().baseDir, 'tauri-target');
+  await mkdir(cargoTargetDir, { recursive: true });
+
+  const tauriBuildEnv = {
+    ...process.env,
+    // Fixes builds after moving the repo by isolating cargo outputs from old absolute paths.
+    CARGO_TARGET_DIR: cargoTargetDir,
+    // Newer Tauri CLI parses CI as a boolean; many environments set CI=1 which fails.
+    CI: 'false',
+  };
+
+  const tauriArgs = ['build', '--config', generatedConfigPath];
+  if (tauriDebug) {
+    tauriArgs.push('--debug');
+  }
+  await pmExecBin({ dir: uiDir, bin: 'tauri', args: tauriArgs, env: tauriBuildEnv });
+  if (json) {
+    printResult({ json, data: { ok: true, outDir, tauriBuilt: true, tauriServerUrl } });
+  } else {
+  console.log('[local] Tauri build complete');
+  }
+}
+
+main().catch((err) => {
+  console.error('[local] build failed:', err);
+  process.exit(1);
+});

package/scripts/cli-link.mjs

@@ -0,0 +1,58 @@
+import './utils/env.mjs';
+import { parseArgs } from './utils/args.mjs';
+import { getComponentDir, getRootDir } from './utils/paths.mjs';
+import { ensureCliBuilt, ensureHappyCliLocalNpmLinked } from './utils/pm.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
+
+/**
+ * Link the local Happy CLI wrapper into your PATH.
+ *
+ * This is intentionally extracted so you can re-run linking without doing a full `happys bootstrap`.
+ *
+ * What it does:
+ * - optionally builds `components/happy-cli` (controlled by env/flags)
+ * - installs `happy`/`happys` shims under `~/.happy-stacks/bin` (recommended over `npm link`)
+ *
+ * Env:
+ * - HAPPY_LOCAL_CLI_BUILD=0 to skip building happy-cli
+ * - HAPPY_LOCAL_NPM_LINK=0 to skip shim installation
+ *
+ * Flags:
+ * - --no-build: skip building happy-cli
+ * - --no-link: skip shim installation
+ */
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+  if (wantsHelp(argv, { flags })) {
+    printResult({
+      json,
+      data: { flags: ['--no-build', '--no-link'], json: true },
+      text: [
+        '[cli-link] usage:',
+        '  happys cli:link [--no-build] [--no-link] [--json]',
+        '  (legacy in a cloned repo): pnpm cli:link [-- --no-build] [--json]',
+        '  node scripts/cli-link.mjs [--no-build] [--no-link] [--json]',
+      ].join('\n'),
+    });
+    return;
+  }
+
+  const rootDir = getRootDir(import.meta.url);
+  const cliDir = getComponentDir(rootDir, 'happy-cli');
+
+  const buildCli = !flags.has('--no-build') && (process.env.HAPPY_LOCAL_CLI_BUILD ?? '1') !== '0';
+  const npmLinkCli = !flags.has('--no-link') && (process.env.HAPPY_LOCAL_NPM_LINK ?? '1') !== '0';
+
+  await ensureCliBuilt(cliDir, { buildCli });
+  await ensureHappyCliLocalNpmLinked(rootDir, { npmLinkCli });
+
+  printResult({ json, data: { ok: true, buildCli, npmLinkCli }, text: '[local] cli link complete' });
+}
+
+main().catch((err) => {
+  console.error('[local] cli link failed:', err);
+  process.exit(1);
+});