@happier-dev/stack 0.1.0-preview.5.1

package/scripts/utils/stack/startup_server_light_legacy.test.mjs

@@ -0,0 +1,79 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ensureServerLightSchemaReady } from './startup.mjs';
+import { buildServerLightEnv, createServerLightFixture } from './startup_server_light_testkit.mjs';
+
+test('ensureServerLightSchemaReady bestEffort=true skips migrate:sqlite:deploy by default', async (t) => {
+  const { binDir, markerPath, root, serverDir } = await createServerLightFixture(t, {
+    prefix: 'hs-startup-light-best-effort-',
+    socketPort: 54323,
+  });
+  const env = buildServerLightEnv({ binDir, root });
+
+  const res = await ensureServerLightSchemaReady({ serverDir, env, bestEffort: true });
+  assert.equal(res.ok, true);
+  assert.equal(res.migrated, true);
+  assert.equal(res.accountCount, 0);
+  assert.equal(existsSync(markerPath), false, `expected bestEffort to skip migrate:sqlite:deploy (${markerPath})`);
+});
+
+test('ensureServerLightSchemaReady honors HAPPY_SERVER_LIGHT_DATA_DIR legacy fallback', async (t) => {
+  const { binDir, markerPath, root, serverDir } = await createServerLightFixture(t, {
+    prefix: 'hs-startup-light-legacy-data-dir-',
+    socketPort: 54324,
+  });
+
+  const dataDir = join(root, 'legacy-data');
+  const env = buildServerLightEnv({
+    binDir,
+    root,
+    extraEnv: {
+      HAPPIER_SERVER_LIGHT_DATA_DIR: undefined,
+      HAPPIER_SERVER_LIGHT_FILES_DIR: undefined,
+      HAPPIER_SERVER_LIGHT_DB_DIR: undefined,
+      HAPPY_SERVER_LIGHT_DATA_DIR: dataDir,
+      DATABASE_URL: undefined,
+    },
+  });
+
+  assert.equal(existsSync(dataDir), false);
+  assert.equal(Boolean(env.DATABASE_URL), false);
+
+  const res = await ensureServerLightSchemaReady({ serverDir, env });
+  assert.equal(res.ok, true);
+  assert.equal(existsSync(dataDir), true);
+  assert.equal(env.DATABASE_URL, `file:${join(dataDir, 'happier-server-light.sqlite')}`);
+  assert.equal(existsSync(markerPath), true, `expected migrate:sqlite:deploy to be invoked (${markerPath})`);
+});
+
+test('ensureServerLightSchemaReady falls back to HAPPY_SERVER_LIGHT_DATA_DIR when HAPPIER value is empty', async (t) => {
+  const { binDir, markerPath, root, serverDir } = await createServerLightFixture(t, {
+    prefix: 'hs-startup-light-empty-prefers-legacy-',
+    socketPort: 54325,
+  });
+
+  const dataDir = join(root, 'legacy-data-empty-fallback');
+  const env = buildServerLightEnv({
+    binDir,
+    root,
+    extraEnv: {
+      HAPPIER_SERVER_LIGHT_DATA_DIR: '',
+      HAPPIER_SERVER_LIGHT_FILES_DIR: '',
+      HAPPIER_SERVER_LIGHT_DB_DIR: '',
+      HAPPY_SERVER_LIGHT_DATA_DIR: dataDir,
+      DATABASE_URL: undefined,
+    },
+  });
+
+  assert.equal(existsSync(dataDir), false);
+  assert.equal(Boolean(env.DATABASE_URL), false);
+
+  const res = await ensureServerLightSchemaReady({ serverDir, env });
+  assert.equal(res.ok, true);
+  assert.equal(existsSync(dataDir), true);
+  assert.equal(env.DATABASE_URL, `file:${join(dataDir, 'happier-server-light.sqlite')}`);
+  assert.equal(existsSync(markerPath), true, `expected migrate:sqlite:deploy to be invoked (${markerPath})`);
+});

package/scripts/utils/stack/startup_server_light_testkit.mjs

@@ -0,0 +1,106 @@
+import { chmod, mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+async function writeJson(path, obj) {
+  await writeFile(path, JSON.stringify(obj, null, 2) + '\n', 'utf-8');
+}
+
+async function writeEsmPkg({ dir, name, body }) {
+  await mkdir(dir, { recursive: true });
+  await writeJson(join(dir, 'package.json'), { name, type: 'module', main: './index.js' });
+  await writeFile(join(dir, 'index.js'), body.trim() + '\n', 'utf-8');
+}
+
+async function seedServerLightProbeDeps({ serverDir, socketPort }) {
+  await mkdir(join(serverDir, 'node_modules'), { recursive: true });
+  await writeFile(join(serverDir, 'node_modules', '.yarn-integrity'), 'ok\n', 'utf-8');
+  await writeEsmPkg({
+    dir: join(serverDir, 'node_modules', '@electric-sql', 'pglite'),
+    name: '@electric-sql/pglite',
+    body: `
+export class PGlite {
+  constructor(_dir) { this.waitReady = Promise.resolve(); }
+  async close() {}
+}
+`,
+  });
+  await writeEsmPkg({
+    dir: join(serverDir, 'node_modules', '@electric-sql', 'pglite-socket'),
+    name: '@electric-sql/pglite-socket',
+    body: `
+export class PGLiteSocketServer {
+  constructor(_opts) {}
+  async start() {}
+  getServerConn() { return '127.0.0.1:${String(socketPort)}'; }
+  async stop() {}
+}
+`,
+  });
+  await writeEsmPkg({
+    dir: join(serverDir, 'node_modules', '@prisma', 'client'),
+    name: '@prisma/client',
+    body: `
+export class PrismaClient {
+  constructor() { this.account = { count: async () => 0 }; }
+  async $disconnect() {}
+}
+`,
+  });
+}
+
+async function writeYarnShim({ root, markerPath }) {
+  const binDir = join(root, 'bin');
+  await mkdir(binDir, { recursive: true });
+  const yarnPath = join(binDir, 'yarn');
+  await writeFile(
+    yarnPath,
+    [
+      '#!/usr/bin/env node',
+      "const fs = require('node:fs');",
+      'const args = process.argv.slice(2);',
+      "if (args.includes('--version')) { console.log('1.22.22'); process.exit(0); }",
+      `if (args[0] === '-s' && args[1] === 'migrate:sqlite:deploy') { fs.writeFileSync(${JSON.stringify(markerPath)}, 'ok\\n', 'utf-8'); process.exit(0); }`,
+      'process.exit(0);',
+    ].join('\n') + '\n',
+    'utf-8'
+  );
+  await chmod(yarnPath, 0o755);
+  return { binDir, yarnPath };
+}
+
+export async function createServerLightFixture(t, { prefix, socketPort }) {
+  const root = await mkdtemp(join(tmpdir(), prefix));
+  t.after(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const serverDir = join(root, 'server');
+  await mkdir(serverDir, { recursive: true });
+  await writeJson(join(serverDir, 'package.json'), { name: 'server', version: '0.0.0', type: 'module' });
+  await writeFile(join(serverDir, 'yarn.lock'), '# yarn\n', 'utf-8');
+  await seedServerLightProbeDeps({ serverDir, socketPort });
+
+  const markerPath = join(root, 'called-migrate-sqlite-deploy.txt');
+  const yarnShim = await writeYarnShim({ root, markerPath });
+
+  return {
+    binDir: yarnShim.binDir,
+    markerPath,
+    root,
+    serverDir,
+    yarnPath: yarnShim.yarnPath,
+  };
+}
+
+export function buildServerLightEnv({ binDir, root, extraEnv = {} }) {
+  const dataDir = join(root, 'data');
+  return {
+    ...process.env,
+    PATH: `${binDir}:${process.env.PATH ?? ''}`,
+    HAPPIER_SERVER_LIGHT_DATA_DIR: dataDir,
+    HAPPIER_SERVER_LIGHT_FILES_DIR: join(dataDir, 'files'),
+    HAPPIER_SERVER_LIGHT_DB_DIR: join(dataDir, 'pglite'),
+    ...extraEnv,
+  };
+}

package/scripts/utils/stack/stop.mjs

@@ -0,0 +1,284 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { getComponentDir } from '../paths/paths.mjs';
+import { isPidAlive, readPidState } from '../expo/expo.mjs';
+import { stopLocalDaemon } from '../../daemon.mjs';
+import { stopHappyServerManagedInfra } from '../server/infra/happy_server_infra.mjs';
+import { deleteStackRuntimeStateFile, getStackRuntimeStatePath, readStackRuntimeStateFile } from './runtime_state.mjs';
+import { killPidOwnedByStack, killProcessGroupOwnedByStack, listPidsWithEnvNeedles } from '../proc/ownership.mjs';
+import { coercePort } from '../server/port.mjs';
+import { resolvePreferredStackDaemonStatePaths } from '../auth/credentials_paths.mjs';
+
+function resolveServerComponentFromStackEnv(env) {
+  const v =
+    (env.HAPPIER_STACK_SERVER_COMPONENT ?? '').toString().trim() || 'happier-server-light';
+  return v === 'happier-server' ? 'happier-server' : 'happier-server-light';
+}
+
+async function daemonControlPost({ httpPort, path, body = {} }) {
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort(), 1500);
+  try {
+    const res = await fetch(`http://127.0.0.1:${httpPort}${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: ctl.signal,
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      throw new Error(`daemon control ${path} failed (http ${res.status}): ${text.trim()}`);
+    }
+    return text.trim() ? JSON.parse(text) : null;
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+async function stopDaemonTrackedSessions({ cliHomeDir, serverUrl, json }) {
+  // Read daemon state file written by happier-cli; needed to call control server (/list, /stop-session).
+  const { statePath } = resolvePreferredStackDaemonStatePaths({ cliHomeDir, serverUrl });
+  if (!existsSync(statePath)) {
+    return { ok: true, skipped: true, reason: 'missing_state', stoppedSessionIds: [] };
+  }
+
+  let state = null;
+  try {
+    state = JSON.parse(await readFile(statePath, 'utf-8'));
+  } catch {
+    return { ok: false, skipped: true, reason: 'bad_state', stoppedSessionIds: [] };
+  }
+
+  const httpPort = Number(state?.httpPort);
+  const pid = Number(state?.pid);
+  if (!Number.isFinite(httpPort) || httpPort <= 0) {
+    return { ok: false, skipped: true, reason: 'missing_http_port', stoppedSessionIds: [] };
+  }
+  if (!Number.isFinite(pid) || pid <= 1) {
+    return { ok: false, skipped: true, reason: 'missing_pid', stoppedSessionIds: [] };
+  }
+  try {
+    process.kill(pid, 0);
+  } catch {
+    return { ok: true, skipped: true, reason: 'daemon_not_running', stoppedSessionIds: [] };
+  }
+
+  const listed = await daemonControlPost({ httpPort, path: '/list' }).catch((e) => {
+    if (!json) console.warn(`[stack] failed to list daemon sessions: ${e instanceof Error ? e.message : String(e)}`);
+    return null;
+  });
+  const children = Array.isArray(listed?.children) ? listed.children : [];
+
+  const stoppedSessionIds = [];
+  for (const child of children) {
+    const sid = String(child?.happySessionId ?? '').trim();
+    if (!sid) continue;
+    // eslint-disable-next-line no-await-in-loop
+    const res = await daemonControlPost({ httpPort, path: '/stop-session', body: { sessionId: sid } }).catch(() => null);
+    if (res?.success) {
+      stoppedSessionIds.push(sid);
+    }
+  }
+
+  return { ok: true, skipped: false, stoppedSessionIds };
+}
+
+async function stopExpoStateDir({ stackName, baseDir, kind, stateFileName, envPath, json }) {
+  const root = join(baseDir, kind);
+  let entries = [];
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    entries = [];
+  }
+
+  const killed = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const statePath = join(root, e.name, stateFileName);
+    // eslint-disable-next-line no-await-in-loop
+    const state = await readPidState(statePath);
+    if (!state) continue;
+    const pid = Number(state.pid);
+
+    if (!Number.isFinite(pid) || pid <= 1) continue;
+    if (!isPidAlive(pid)) continue;
+
+    if (!json) {
+      // eslint-disable-next-line no-console
+      console.log(`[stack] stopping ${kind} (pid=${pid}) for ${stackName}`);
+    }
+    // eslint-disable-next-line no-await-in-loop
+    await killProcessGroupOwnedByStack(pid, { stackName, envPath, label: kind, json });
+    killed.push({ pid, port: null, statePath });
+  }
+  return killed;
+}
+
+export async function stopStackWithEnv({
+  rootDir,
+  stackName,
+  baseDir,
+  env,
+  json,
+  noDocker = false,
+  aggressive = false,
+  sweepOwned = false,
+  autoSweep = true,
+}) {
+  const actions = {
+    stackName,
+    baseDir,
+    aggressive,
+    sweepOwned,
+    runner: null,
+    daemonSessionsStopped: null,
+    daemonStopped: false,
+    killedPorts: [],
+    expoDev: [],
+    uiDev: [],
+    mobile: [],
+    infra: null,
+    errors: [],
+  };
+
+  const serverComponent = resolveServerComponentFromStackEnv(env);
+  const port = coercePort(env.HAPPIER_STACK_SERVER_PORT);
+  const backendPort = coercePort(env.HAPPIER_STACK_SERVER_BACKEND_PORT);
+  const internalServerUrl = port ? `http://127.0.0.1:${port}` : 'http://127.0.0.1:3005';
+  const cliHomeDir = (env.HAPPIER_STACK_CLI_HOME_DIR ?? join(baseDir, 'cli')).toString();
+  const cliDir = getComponentDir(rootDir, 'happier-cli', env);
+  const cliBin = join(cliDir, 'bin', 'happier.mjs');
+  const envPath = (env.HAPPIER_STACK_ENV_FILE ?? '').toString();
+
+  // Preferred: stop stack-started processes (by PID) recorded in stack.runtime.json.
+  // This is safer than killing whatever happens to listen on a port, and doesn't rely on the runner's shutdown handler.
+  const runtimeStatePath = getStackRuntimeStatePath(stackName);
+  const runtimeState = await readStackRuntimeStateFile(runtimeStatePath);
+  const runnerPid = Number(runtimeState?.ownerPid);
+  const processes = runtimeState?.processes && typeof runtimeState.processes === 'object' ? runtimeState.processes : {};
+
+  // Kill known child processes first (process groups), then stop daemon, then stop runner.
+  const killedProcessPids = [];
+  for (const [key, rawPid] of Object.entries(processes)) {
+    const pid = Number(rawPid);
+    if (!Number.isFinite(pid) || pid <= 1) continue;
+    if (!isPidAlive(pid)) continue;
+    // eslint-disable-next-line no-await-in-loop
+    const res = await killProcessGroupOwnedByStack(pid, { stackName, envPath, cliHomeDir, label: key, json });
+    if (res.killed) {
+      killedProcessPids.push({ key, pid, reason: res.reason, pgid: res.pgid ?? null });
+    }
+  }
+  actions.runner = { stopped: false, pid: Number.isFinite(runnerPid) ? runnerPid : null, reason: runtimeState ? 'not_running_or_not_owned' : 'missing_state' };
+  actions.killedPorts = actions.killedPorts ?? [];
+  actions.processes = { killed: killedProcessPids };
+
+  if (aggressive) {
+    try {
+      actions.daemonSessionsStopped = await stopDaemonTrackedSessions({ cliHomeDir, serverUrl: internalServerUrl, json });
+    } catch (e) {
+      actions.errors.push({ step: 'daemon-sessions', error: e instanceof Error ? e.message : String(e) });
+    }
+  }
+
+  try {
+    await stopLocalDaemon({ cliBin, internalServerUrl, cliHomeDir });
+    actions.daemonStopped = true;
+  } catch (e) {
+    actions.errors.push({ step: 'daemon', error: e instanceof Error ? e.message : String(e) });
+  }
+
+  // Now stop the runner PID last (if it exists). This should clean up any remaining state files it owns.
+  if (Number.isFinite(runnerPid) && runnerPid > 1 && isPidAlive(runnerPid)) {
+    if (!json) {
+      // eslint-disable-next-line no-console
+      console.log(`[stack] stopping runner (pid=${runnerPid}) for ${stackName}`);
+    }
+    const res = await killPidOwnedByStack(runnerPid, { stackName, envPath, cliHomeDir, label: 'runner', json });
+    actions.runner = { stopped: res.killed, pid: runnerPid, reason: res.reason };
+  }
+
+  // Only delete runtime state if the runner is confirmed stopped (or not running).
+  if (!isPidAlive(runnerPid)) {
+    await deleteStackRuntimeStateFile(runtimeStatePath);
+  }
+
+  try {
+    actions.expoDev = await stopExpoStateDir({ stackName, baseDir, kind: 'expo-dev', stateFileName: 'expo.state.json', envPath, json });
+  } catch (e) {
+    actions.errors.push({ step: 'expo-dev', error: e instanceof Error ? e.message : String(e) });
+  }
+  try {
+    // Legacy cleanups (best-effort): older runs used separate state dirs.
+    actions.uiDev = await stopExpoStateDir({ stackName, baseDir, kind: 'ui-dev', stateFileName: 'ui.state.json', envPath, json });
+    const killedDev = await stopExpoStateDir({ stackName, baseDir, kind: 'mobile-dev', stateFileName: 'mobile.state.json', envPath, json });
+    const killedLegacy = await stopExpoStateDir({ stackName, baseDir, kind: 'mobile', stateFileName: 'expo.state.json', envPath, json });
+    actions.mobile = [...killedDev, ...killedLegacy];
+  } catch (e) {
+    actions.errors.push({ step: 'expo-mobile', error: e instanceof Error ? e.message : String(e) });
+  }
+
+  // IMPORTANT:
+  // Never kill "whatever is listening on a port" in stack mode.
+  void backendPort;
+  void port;
+
+  const managed = (env.HAPPIER_STACK_MANAGED_INFRA ?? '1').toString().trim() !== '0';
+  if (!noDocker && serverComponent === 'happier-server' && managed) {
+    try {
+      actions.infra = await stopHappyServerManagedInfra({ stackName, baseDir, removeVolumes: false });
+    } catch (e) {
+      actions.errors.push({ step: 'infra', error: e instanceof Error ? e.message : String(e) });
+    }
+  } else {
+    actions.infra = { ok: true, skipped: true, reason: noDocker ? 'no_docker' : 'not_managed_or_not_happier_server' };
+  }
+
+  // Last resort: sweep any remaining processes that still carry this stack env file in their environment.
+  // IMPORTANT:
+  // This must NOT kill daemon-spawned sessions/LLM/agent processes. Those should survive infra restarts.
+  //
+  // We only target infra processes by requiring HAPPIER_STACK_PROCESS_KIND=infra in addition to the stack env file.
+  // We also exclude our own PID.
+  const autoSweepFromEnvRaw = (env?.HAPPIER_STACK_STOP_AUTO_SWEEP ?? '').toString().trim();
+  const autoSweepFromEnv = autoSweepFromEnvRaw ? autoSweepFromEnvRaw !== '0' : null;
+  const autoSweepResolved = typeof autoSweepFromEnv === 'boolean' ? autoSweepFromEnv : Boolean(autoSweep);
+
+  // If the runtime state exists but its owner PID is stale (e.g. runner was Ctrl+C'd),
+  // treat it like "missing" and fall back to a safe infra-only sweep.
+  const runtimeStateUsable = Boolean(runtimeState) && Number.isFinite(runnerPid) && runnerPid > 1 && isPidAlive(runnerPid);
+  const shouldAutoSweep = autoSweepResolved && envPath && !runtimeStateUsable;
+  if ((sweepOwned || shouldAutoSweep) && envPath) {
+    const envNeedle = `HAPPIER_STACK_ENV_FILE=${envPath}`;
+    const infraTagged = await listPidsWithEnvNeedles([envNeedle, 'HAPPIER_STACK_PROCESS_KIND=infra']);
+
+    // Compatibility sweep for older stacks: some long-running infra (notably server dev loops)
+    // may not have been started with HAPPIER_STACK_PROCESS_KIND=infra yet. We restrict this
+    // fallback to npm/yarn managed server processes to avoid touching daemon-spawned sessions.
+    const legacyServer = await listPidsWithEnvNeedles([
+      envNeedle,
+      'npm_lifecycle_event=',
+      'npm_package_name=@happier-dev/server',
+    ]);
+
+    const pids = [...new Set([...infraTagged, ...legacyServer])]
+      .filter((pid) => pid !== process.pid)
+      .filter((pid) => Number.isFinite(pid) && pid > 1);
+
+    const swept = [];
+    for (const pid of Array.from(new Set(pids))) {
+      if (!isPidAlive(pid)) continue;
+      // eslint-disable-next-line no-await-in-loop
+      const res = await killProcessGroupOwnedByStack(pid, { stackName, envPath, cliHomeDir, label: 'sweep', json });
+      if (res.killed) {
+        swept.push({ pid, reason: res.reason, pgid: res.pgid ?? null });
+      }
+    }
+    actions.sweep = { pids: swept, auto: shouldAutoSweep && !sweepOwned };
+  }
+
+  return actions;
+}

package/scripts/utils/stack_context.mjs

@@ -0,0 +1 @@
+export * from './stack/context.mjs';

package/scripts/utils/stack_runtime_state.mjs

@@ -0,0 +1 @@
+export * from './stack/runtime_state.mjs';

package/scripts/utils/stacks.mjs

@@ -0,0 +1 @@
+export * from './stack/stacks.mjs';

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. HAPPIER_STACK_TAILSCALE_BIN env override
+ * 2. PATH lookup
+ * 3. macOS app bundle paths
+ */
+export async function resolveTailscaleCmd() {
+  // Explicit override
+  if (process.env.HAPPIER_STACK_TAILSCALE_BIN?.trim()) {
+    return process.env.HAPPIER_STACK_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/tauri/stack_overrides.mjs

@@ -0,0 +1,22 @@
+function getTrimmedEnv(env, key) {
+  const raw = env?.[key];
+  if (raw === undefined || raw === null) return '';
+  return String(raw).trim();
+}
+
+export function applyStackTauriOverrides({ tauriConfig, env }) {
+  const identifierOverride = getTrimmedEnv(env, 'HAPPIER_STACK_TAURI_IDENTIFIER');
+  const productNameOverride = getTrimmedEnv(env, 'HAPPIER_STACK_TAURI_PRODUCT_NAME');
+
+  tauriConfig.identifier = identifierOverride || 'com.happier.stack';
+  tauriConfig.productName = productNameOverride || tauriConfig.productName || 'Happier';
+
+  if (tauriConfig.app?.windows?.length) {
+    tauriConfig.app.windows = tauriConfig.app.windows.map((w) => ({
+      ...w,
+      title: tauriConfig.productName ?? w.title,
+    }));
+  }
+
+  return tauriConfig;
+}

package/scripts/utils/test/collect_test_files.mjs

@@ -0,0 +1,29 @@
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+function matchesAnySuffix(name, suffixes = []) {
+  return suffixes.some((suffix) => name.endsWith(suffix));
+}
+
+export async function collectTestFiles({
+  dir,
+  includeSuffixes = ['.test.mjs'],
+  excludeSuffixes = [],
+} = {}) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await collectTestFiles({ dir: path, includeSuffixes, excludeSuffixes })));
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (!matchesAnySuffix(entry.name, includeSuffixes)) continue;
+    if (matchesAnySuffix(entry.name, excludeSuffixes)) continue;
+    files.push(path);
+  }
+  files.sort();
+  return files;
+}

package/scripts/utils/time/get_today_ymd.mjs

@@ -0,0 +1,7 @@
+export function getTodayYmd() {
+  const now = new Date();
+  const y = String(now.getFullYear());
+  const m = String(now.getMonth() + 1).padStart(2, '0');
+  const d = String(now.getDate()).padStart(2, '0');
+  return `${y}-${m}-${d}`;
+}