@happier-dev/stack 0.1.0-preview.96.1 → 0.2.0-preview.1775370152.55749

package/scripts/utils/stack/stop.mjs

@@ -3,11 +3,12 @@ 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 { isPidAlive, killPid, 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 { deleteStackRuntimeStateFile, readStackRuntimeStateFile, recordStackRuntimeStopRequest } from './runtime_state.mjs';
+import { getProcessGroupId, getPsEnvLine, killPidOwnedByStack, killProcessGroupOwnedByStack, listPidsWithEnvNeedles } from '../proc/ownership.mjs';
+import { terminateProcessGroup } from '../proc/terminate.mjs';
 import { coercePort } from '../server/port.mjs';
 import { resolvePreferredStackDaemonStatePaths } from '../auth/credentials_paths.mjs';
 
@@ -17,13 +18,16 @@ function resolveServerComponentFromStackEnv(env) {
   return v === 'happier-server' ? 'happier-server' : 'happier-server-light';
 }
 
-async function daemonControlPost({ httpPort, path, body = {} }) {
+async function daemonControlPost({ httpPort, path, body = {}, controlToken = '' }) {
   const ctl = new AbortController();
   const t = setTimeout(() => ctl.abort(), 1500);
   try {
+    const headers = { 'content-type': 'application/json' };
+    const token = String(controlToken ?? '').trim();
+    if (token) headers['x-happier-daemon-token'] = token;
     const res = await fetch(`http://127.0.0.1:${httpPort}${path}`, {
       method: 'POST',
-      headers: { 'content-type': 'application/json' },
+      headers,
       body: JSON.stringify(body),
       signal: ctl.signal,
     });
@@ -53,6 +57,7 @@ async function stopDaemonTrackedSessions({ cliHomeDir, serverUrl, json }) {
 
   const httpPort = Number(state?.httpPort);
   const pid = Number(state?.pid);
+  const controlToken = String(state?.controlToken ?? '').trim();
   if (!Number.isFinite(httpPort) || httpPort <= 0) {
     return { ok: false, skipped: true, reason: 'missing_http_port', stoppedSessionIds: [] };
   }
@@ -65,7 +70,21 @@ async function stopDaemonTrackedSessions({ cliHomeDir, serverUrl, json }) {
     return { ok: true, skipped: true, reason: 'daemon_not_running', stoppedSessionIds: [] };
   }
 
-  const listed = await daemonControlPost({ httpPort, path: '/list' }).catch((e) => {
+  // Prefer a single /stop call with stopSessions, so the daemon can stop *all* tracked sessions
+  // (including PID-fallback sessions) in a centralized, versioned way.
+  const stopOk = await daemonControlPost({ httpPort, path: '/stop', body: { stopSessions: true }, controlToken })
+    .then(() => true)
+    .catch((e) => {
+      if (!json) console.warn(`[stack] failed to stop daemon with sessions: ${e instanceof Error ? e.message : String(e)}`);
+      return false;
+    });
+
+  if (stopOk) {
+    return { ok: true, skipped: false, stoppedSessionIds: [] };
+  }
+
+  // Back-compat fallback: older daemons may not support /stop with stopSessions.
+  const listed = await daemonControlPost({ httpPort, path: '/list', controlToken }).catch((e) => {
     if (!json) console.warn(`[stack] failed to list daemon sessions: ${e instanceof Error ? e.message : String(e)}`);
     return null;
   });
@@ -76,7 +95,7 @@ async function stopDaemonTrackedSessions({ cliHomeDir, serverUrl, json }) {
     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);
+    const res = await daemonControlPost({ httpPort, path: '/stop-session', body: { sessionId: sid }, controlToken }).catch(() => null);
     if (res?.success) {
       stoppedSessionIds.push(sid);
     }
@@ -152,11 +171,19 @@ export async function stopStackWithEnv({
   const cliDir = getComponentDir(rootDir, 'happier-cli', env);
   const cliBin = join(cliDir, 'bin', 'happier.mjs');
   const envPath = (env.HAPPIER_STACK_ENV_FILE ?? '').toString();
+  const selfPgid = await getProcessGroupId(process.pid);
 
   // 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 runtimeStatePath = join(baseDir, 'stack.runtime.json');
   const runtimeState = await readStackRuntimeStateFile(runtimeStatePath);
+  if (runtimeState) {
+    await recordStackRuntimeStopRequest(runtimeStatePath, {
+      signal: 'SIGTERM',
+      requestedBy: 'stack stop',
+      reason: persistentReason(aggressive, sweepOwned, autoSweep),
+    }).catch(() => {});
+  }
   const runnerPid = Number(runtimeState?.ownerPid);
   const processes = runtimeState?.processes && typeof runtimeState.processes === 'object' ? runtimeState.processes : {};
 
@@ -170,6 +197,39 @@ export async function stopStackWithEnv({
     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 });
+      continue;
+    }
+
+    // Back-compat for earlier "stackless" runs:
+    // Some repo-local runs started infra without HAPPIER_STACK_ENV_FILE/HAPPIER_HOME_DIR markers.
+    // For ephemeral stacks, allow stopping runtime-recorded PIDs when the process environment still
+    // proves the stack name, to avoid leaving orphaned servers/expo after quitting the TUI.
+    if (runtimeState?.ephemeral && res.reason === 'not_owned') {
+      // eslint-disable-next-line no-await-in-loop
+      const line = await getPsEnvLine(pid);
+      if (line && line.includes(`HAPPIER_STACK_STACK=${stackName}`)) {
+        // eslint-disable-next-line no-await-in-loop
+        const pgid = await getProcessGroupId(pid);
+        if (pgid) {
+          if (selfPgid && pgid === selfPgid) {
+            // Avoid killing the stop command / TUI manager itself when PGIDs are shared.
+            // eslint-disable-next-line no-await-in-loop
+            await killPid(pid);
+            killedProcessPids.push({ key, pid, reason: 'killed_ephemeral_runtime_pid_only_same_pgid', pgid });
+            continue;
+          }
+          // eslint-disable-next-line no-await-in-loop
+          const terminated = await terminateProcessGroup(pgid, { graceMs: 800, signal: 'SIGTERM' });
+          if (terminated.ok) {
+            killedProcessPids.push({ key, pid, reason: 'killed_ephemeral_runtime_pgid', pgid });
+            continue;
+          }
+        }
+        // Fallback: kill the pid directly.
+        // eslint-disable-next-line no-await-in-loop
+        await killPid(pid);
+        killedProcessPids.push({ key, pid, reason: 'killed_ephemeral_runtime_pid_only', pgid: pgid ?? null });
+      }
     }
   }
   actions.runner = { stopped: false, pid: Number.isFinite(runnerPid) ? runnerPid : null, reason: runtimeState ? 'not_running_or_not_owned' : 'missing_state' };
@@ -185,8 +245,13 @@ export async function stopStackWithEnv({
   }
 
   try {
-    await stopLocalDaemon({ cliBin, internalServerUrl, cliHomeDir });
-    actions.daemonStopped = true;
+    // If happier-cli isn't built yet (common in repo checkouts), running `happier.mjs` can fail noisily.
+    // Stopping stack infra should still work without the daemon stop step.
+    const cliDistIndex = join(cliDir, 'dist', 'index.mjs');
+    if (existsSync(cliDistIndex)) {
+      await stopLocalDaemon({ cliBin, internalServerUrl, cliHomeDir });
+      actions.daemonStopped = true;
+    }
   } catch (e) {
     actions.errors.push({ step: 'daemon', error: e instanceof Error ? e.message : String(e) });
   }
@@ -201,8 +266,15 @@ export async function stopStackWithEnv({
     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)) {
+  // Only delete runtime state if all runtime-tracked pids are confirmed stopped.
+  // This avoids losing the only reliable link between a stack and its infra pids.
+  const runtimeTrackedPids = [
+    runnerPid,
+    ...Object.values(processes).map((p) => Number(p)),
+  ]
+    .filter((p) => Number.isFinite(p) && p > 1);
+  const anyRuntimePidAlive = runtimeTrackedPids.some((p) => isPidAlive(p));
+  if (!anyRuntimePidAlive) {
     await deleteStackRuntimeStateFile(runtimeStatePath);
   }
 
@@ -269,6 +341,25 @@ export async function stopStackWithEnv({
       .filter((pid) => Number.isFinite(pid) && pid > 1);
 
     const swept = [];
+    const sweepPidDirect = async (pid, reason) => {
+      const pgid = await getProcessGroupId(pid);
+      if (pgid) {
+        if (selfPgid && pgid === selfPgid) {
+          await killPid(pid);
+          swept.push({ pid, reason: `${reason}_pid_only_same_pgid`, pgid });
+          return true;
+        }
+        const terminated = await terminateProcessGroup(pgid, { graceMs: 800, signal: 'SIGTERM' });
+        if (terminated.ok) {
+          swept.push({ pid, reason, pgid });
+          return true;
+        }
+      }
+      await killPid(pid);
+      swept.push({ pid, reason, pgid: pgid ?? null });
+      return true;
+    };
+
     for (const pid of Array.from(new Set(pids))) {
       if (!isPidAlive(pid)) continue;
       // eslint-disable-next-line no-await-in-loop
@@ -277,8 +368,36 @@ export async function stopStackWithEnv({
         swept.push({ pid, reason: res.reason, pgid: res.pgid ?? null });
       }
     }
+
+    // Repo-local fallback: older stackless runs may have omitted HAPPIER_STACK_ENV_FILE/HAPPIER_STACK_PROCESS_KIND markers.
+    // When runtime state is missing/stale, allow sweeping by the (stackName + repoDir) env needles for repo-local stacks.
+    // This is intentionally restricted to repo-local stack names to avoid killing unrelated long-lived processes.
+    const repoDir = String(env.HAPPIER_STACK_REPO_DIR ?? '').trim();
+    const isRepoLocalStack = stackName && stackName !== 'main' && String(stackName).startsWith('repo-');
+    if (autoSweepResolved && shouldAutoSweep && swept.length === 0 && isRepoLocalStack && repoDir) {
+      const repoLocal = await listPidsWithEnvNeedles([
+        `HAPPIER_STACK_STACK=${stackName}`,
+        `HAPPIER_STACK_REPO_DIR=${repoDir}`,
+      ]);
+      const repoLocalPids = repoLocal
+        .filter((pid) => pid !== process.pid)
+        .filter((pid) => Number.isFinite(pid) && pid > 1);
+      for (const pid of Array.from(new Set(repoLocalPids))) {
+        if (!isPidAlive(pid)) continue;
+        // eslint-disable-next-line no-await-in-loop
+        await sweepPidDirect(pid, 'killed_repo_local_stackless_sweep');
+      }
+    }
+
     actions.sweep = { pids: swept, auto: shouldAutoSweep && !sweepOwned };
   }
 
   return actions;
 }
+
+function persistentReason(aggressive, sweepOwned, autoSweep) {
+  if (aggressive) return 'explicit stack stop (aggressive)';
+  if (sweepOwned) return 'explicit stack stop (sweep-owned)';
+  if (autoSweep === false) return 'explicit stack stop (no-auto-sweep)';
+  return 'explicit stack stop';
+}

package/scripts/utils/stack/terminal_usage_instructions.mjs

@@ -0,0 +1,52 @@
+import { cmd, sectionTitle } from '../ui/layout.mjs';
+import { cyan, dim } from '../ui/ansi.mjs';
+
+export function renderTerminalUsageInstructions({
+  internalServerUrl,
+  cliHomeDir,
+  publicServerUrl,
+  activeServerId = '',
+  stackName = '',
+}) {
+  const serverUrl = String(internalServerUrl ?? '').trim();
+  const homeDir = String(cliHomeDir ?? '').trim();
+  const webappUrl = String(publicServerUrl ?? '').trim();
+  const scope = String(activeServerId ?? '').trim();
+  const stack = String(stackName ?? '').trim();
+  const stackWrapperCommand = stack ? `HAPPIER_STACK_STACK="${stack}" hstack happier` : 'hstack happier';
+
+  return [
+    '',
+    sectionTitle('Terminal usage'),
+    dim(`To run ${cyan('happier')} against this stack (and have sessions appear in the UI), use the stack-aware wrapper:`),
+    ...(stack ? [cmd(`export HAPPIER_STACK_STACK="${stack}"`)] : []),
+    cmd('hstack happier auth status --json'),
+    cmd('hstack happier'),
+    '',
+    dim('Low-level env fallback (if you need the raw CLI env directly):'),
+    cmd(`export HAPPIER_SERVER_URL="${serverUrl}"`),
+    cmd(`export HAPPIER_HOME_DIR="${homeDir}"`),
+    cmd(`export HAPPIER_WEBAPP_URL="${webappUrl}"`),
+    ...(scope ? [cmd(`export HAPPIER_ACTIVE_SERVER_ID="${scope}"`)] : []),
+    '',
+    dim('Sanity check (should be ok:true):'),
+    cmd(`${stackWrapperCommand} auth status --json`),
+    '',
+    dim('Then run:'),
+    cmd('hstack happier'),
+    '',
+    dim('One-liner (no exports):'),
+    cmd(
+      [
+        ...(stack ? [`HAPPIER_STACK_STACK="${stack}"`] : []),
+        `HAPPIER_SERVER_URL="${serverUrl}"`,
+        `HAPPIER_HOME_DIR="${homeDir}"`,
+        `HAPPIER_WEBAPP_URL="${webappUrl}"`,
+        ...(scope ? [`HAPPIER_ACTIVE_SERVER_ID="${scope}"`] : []),
+        'hstack happier',
+      ].join(' '),
+    ),
+    '',
+    dim('Note: keep HAPPIER_HOME_DIR as shown to use this stack/sandbox account and credentials if you bypass the wrapper.'),
+  ];
+}

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

@@ -0,0 +1,25 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { renderTerminalUsageInstructions } from './terminal_usage_instructions.mjs';
+
+test('renderTerminalUsageInstructions prints a runnable happier command and key env exports', () => {
+  const lines = renderTerminalUsageInstructions({
+    internalServerUrl: 'http://127.0.0.1:3014',
+    cliHomeDir: '/tmp/happier/stack/cli',
+    publicServerUrl: 'http://happier-pr.localhost:8084/?server=http%3A%2F%2Flocalhost%3A3014',
+    activeServerId: 'stack_pr-123__id_default',
+    stackName: 'pr-123',
+  });
+
+  const text = lines.join('\n');
+  assert.match(text, /Terminal usage/);
+  assert.match(text, /export HAPPIER_SERVER_URL="http:\/\/127\.0\.0\.1:3014"/);
+  assert.match(text, /export HAPPIER_HOME_DIR="\/tmp\/happier\/stack\/cli"/);
+  assert.match(text, /export HAPPIER_WEBAPP_URL="http:\/\/happier-pr\.localhost:8084/);
+  assert.match(text, /export HAPPIER_ACTIVE_SERVER_ID="stack_pr-123__id_default"/);
+  assert.match(text, /export HAPPIER_STACK_STACK="pr-123"/);
+  assert.match(text, /\bhstack happier auth status --json\b/);
+  assert.match(text, /\bThen run:\s*hstack happier\b/);
+  assert.match(text, /HAPPIER_STACK_STACK="pr-123".*hstack happier/);
+});

package/scripts/utils/tailscale/extract_https_url_from_status.mjs

@@ -0,0 +1,5 @@
+import { extractTailscaleServeHttpsUrl } from '@happier-dev/cli-common/tailscale';
+
+export function extractTailscaleHttpsUrlFromStatusText(statusText) {
+  return extractTailscaleServeHttpsUrl(String(statusText ?? ''));
+}

package/scripts/utils/tailscale/ip.mjs

@@ -4,63 +4,23 @@
  * Provides functions to detect the local Tailscale IPv4 address for port forwarding.
  */
 
+import { resolveTailscaleBin, sanitizeTailscaleEnv } from '@happier-dev/cli-common/tailscale';
 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
+ * Reuses the canonical shared Tailscale command resolution so the stack helper stays aligned
+ * with the rest of the app and honors the unified env overrides.
  */
-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
+export async function resolveTailscaleCmd({ env = process.env } = {}) {
   try {
-    const found = await resolveCommandPath('tailscale', { env: tailscaleEnv(), timeoutMs: TAILSCALE_TIMEOUT_MS });
-    if (found) return found;
+    return await resolveTailscaleBin({ env });
   } catch {
-    // ignore
+    return null;
   }
-
-  // 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;
 }
 
 /**
@@ -68,12 +28,13 @@ export async function resolveTailscaleCmd() {
  *
  * @returns {Promise<string | null>} The Tailscale IPv4 address, or null if unavailable.
  */
-export async function getTailscaleIpv4() {
-  const cmd = await resolveTailscaleCmd();
+export async function getTailscaleIpv4({ env = process.env } = {}) {
+  const tailscaleEnv = sanitizeTailscaleEnv(env);
+  const cmd = await resolveTailscaleCmd({ env: tailscaleEnv });
   if (!cmd) return null;
 
   const result = await runCaptureResult(cmd, ['ip', '-4'], {
-    env: tailscaleEnv(),
+    env: tailscaleEnv,
     timeoutMs: TAILSCALE_TIMEOUT_MS,
   });
 
@@ -91,8 +52,8 @@ export async function getTailscaleIpv4() {
  *
  * @returns {Promise<boolean>}
  */
-export async function isTailscaleAvailable() {
-  const ip = await getTailscaleIpv4();
+export async function isTailscaleAvailable({ env = process.env } = {}) {
+  const ip = await getTailscaleIpv4({ env });
   return Boolean(ip);
 }
 
@@ -101,13 +62,13 @@ export async function isTailscaleAvailable() {
  *
  * @returns {Promise<{ available: boolean, ip: string | null, error: string | null }>}
  */
-export async function getTailscaleStatus() {
-  const cmd = await resolveTailscaleCmd();
+export async function getTailscaleStatus({ env = process.env } = {}) {
+  const cmd = await resolveTailscaleCmd({ env });
   if (!cmd) {
     return { available: false, ip: null, error: 'tailscale CLI not found' };
   }
 
-  const ip = await getTailscaleIpv4();
+  const ip = await getTailscaleIpv4({ env });
   if (!ip) {
     return { available: false, ip: null, error: 'tailscale not connected or no IPv4 address' };
   }

package/scripts/utils/tailscale/ip.test.mjs

@@ -0,0 +1,37 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { resolveTailscaleCmd } from './ip.mjs';
+
+test('resolveTailscaleCmd prefers the unified Tailscale env override', async () => {
+  const tempRoot = mkdtempSync(join(tmpdir(), 'happier-stack-tailscale-ip-'));
+  const tailscaleBin = join(tempRoot, 'tailscale');
+
+  try {
+    writeFileSync(
+      tailscaleBin,
+      [
+        '#!/usr/bin/env node',
+        'process.exit(0);',
+        '',
+      ].join('\n'),
+    );
+    chmodSync(tailscaleBin, 0o755);
+
+    const resolved = await resolveTailscaleCmd({
+      env: {
+        PATH: join(tempRoot, 'missing-path'),
+        HOME: tempRoot,
+        HAPPIER_TAILSCALE_BIN: tailscaleBin,
+        HAPPIER_STACK_TAILSCALE_BIN: '/legacy/ignored-tail-scale',
+      },
+    });
+
+    assert.equal(resolved, tailscaleBin);
+  } finally {
+    rmSync(tempRoot, { recursive: true, force: true });
+  }
+});

package/scripts/utils/tauri/createStackTauriDevConfig.mjs

@@ -0,0 +1,34 @@
+import { buildStackTauriDevConfig } from './dev_runtime.mjs';
+
+export function createStackTauriDevConfig({
+  baseConfig = {},
+  env = process.env,
+  devUrl = 'http://localhost:8081',
+  enableDevtools = false,
+} = {}) {
+  const config = buildStackTauriDevConfig({
+    baseConfig,
+    overlayConfig: {},
+    devUrl,
+    env,
+  });
+
+  config.build.beforeDevCommand = '';
+  config.build.beforeBuildCommand = '';
+
+  if (config.bundle && typeof config.bundle === 'object') {
+    config.bundle = {
+      ...config.bundle,
+      createUpdaterArtifacts: false,
+    };
+  }
+
+  if (config.app?.windows?.length) {
+    config.app.windows = config.app.windows.map((windowConfig) => ({
+      ...windowConfig,
+      ...(enableDevtools ? { devtools: true } : {}),
+    }));
+  }
+
+  return config;
+}

package/scripts/utils/tauri/createStackTauriDevConfig.test.mjs

@@ -0,0 +1,39 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { createStackTauriDevConfig } from './createStackTauriDevConfig.mjs';
+
+test('createStackTauriDevConfig points Tauri dev at the existing Expo server and disables upstream prestart hooks', () => {
+  const config = createStackTauriDevConfig({
+    baseConfig: {
+      productName: 'Happier',
+      identifier: 'dev.happier.app',
+      build: {
+        devUrl: 'http://localhost:8081',
+        beforeDevCommand: 'yarn -s tauri:prepare:dev',
+        beforeBuildCommand: 'yarn -s tauri:prepare:build',
+      },
+      app: {
+        windows: [{ title: 'Happier' }],
+      },
+      bundle: {
+        createUpdaterArtifacts: true,
+      },
+    },
+    env: {
+      HAPPIER_STACK_TAURI_PRODUCT_NAME: 'Happier (Stack)',
+      HAPPIER_STACK_TAURI_IDENTIFIER: 'dev.happier.stack',
+    },
+    devUrl: 'http://127.0.0.1:4173',
+    enableDevtools: true,
+  });
+
+  assert.equal(config.build.devUrl, 'http://127.0.0.1:4173');
+  assert.equal(config.build.beforeDevCommand, '');
+  assert.equal(config.build.beforeBuildCommand, '');
+  assert.equal(config.productName, 'Happier (Stack)');
+  assert.equal(config.identifier, 'dev.happier.stack');
+  assert.equal(config.app.windows[0].title, 'Happier (Stack)');
+  assert.equal(config.app.windows[0].devtools, true);
+  assert.equal(config.bundle.createUpdaterArtifacts, false);
+});

package/scripts/utils/tauri/dev_runtime.mjs

@@ -0,0 +1,45 @@
+import { applyStackTauriOverrides } from './stack_overrides.mjs';
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function mergeTauriConfig(baseValue, overlayValue) {
+  if (Array.isArray(overlayValue)) {
+    return overlayValue.map((entry) => entry);
+  }
+  if (!isPlainObject(baseValue) || !isPlainObject(overlayValue)) {
+    return overlayValue === undefined ? baseValue : overlayValue;
+  }
+
+  const out = { ...baseValue };
+  for (const [key, value] of Object.entries(overlayValue)) {
+    out[key] = mergeTauriConfig(baseValue[key], value);
+  }
+  return out;
+}
+
+export function resolveStackTauriDevUrl({ runtimeState, defaultPort = 8081 } = {}) {
+  const expo = runtimeState && typeof runtimeState === 'object' ? runtimeState.expo : null;
+  const port = Number(expo?.webPort ?? expo?.port ?? defaultPort);
+  return `http://localhost:${Number.isFinite(port) && port > 0 ? Math.floor(port) : defaultPort}`;
+}
+
+export function buildStackTauriDevConfig({ baseConfig, overlayConfig, devUrl, env = process.env } = {}) {
+  const merged = mergeTauriConfig(baseConfig ?? {}, overlayConfig ?? {});
+  merged.build = {
+    ...(merged.build ?? {}),
+    devUrl: String(devUrl ?? '').trim() || 'http://localhost:8081',
+    beforeDevCommand: '',
+    beforeBuildCommand: '',
+  };
+  const hasExplicitStackOverride =
+    String(env?.HAPPIER_STACK_TAURI_IDENTIFIER ?? '').trim() !== ''
+    || String(env?.HAPPIER_STACK_TAURI_PRODUCT_NAME ?? '').trim() !== ''
+    || String(env?.HAPPIER_STACK_TAURI_CREATE_UPDATER_ARTIFACTS ?? '').trim() !== ''
+    || String(env?.TAURI_SIGNING_PRIVATE_KEY ?? '').trim() !== '';
+  if (hasExplicitStackOverride) {
+    applyStackTauriOverrides({ tauriConfig: merged, env });
+  }
+  return merged;
+}

package/scripts/utils/tauri/dev_runtime.test.mjs

@@ -0,0 +1,79 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildStackTauriDevConfig, resolveStackTauriDevUrl } from './dev_runtime.mjs';
+
+test('resolveStackTauriDevUrl prefers the stack expo web port', () => {
+  assert.equal(
+    resolveStackTauriDevUrl({
+      runtimeState: {
+        expo: { webPort: 19364 },
+      },
+    }),
+    'http://localhost:19364',
+  );
+});
+
+test('resolveStackTauriDevUrl falls back to the default Metro port', () => {
+  assert.equal(resolveStackTauriDevUrl({ runtimeState: null }), 'http://localhost:8081');
+});
+
+test('buildStackTauriDevConfig disables beforeDevCommand and points Tauri at the existing dev server', () => {
+  const config = buildStackTauriDevConfig({
+    baseConfig: {
+      productName: 'Happier',
+      identifier: 'dev.happier.app',
+      build: {
+        devUrl: 'http://localhost:8081',
+        beforeDevCommand: 'yarn -s tauri:prepare:dev',
+      },
+      bundle: {
+        externalBin: ['binaries/hsetup'],
+      },
+      app: {
+        windows: [{ title: 'Happier' }],
+      },
+    },
+    overlayConfig: {
+      productName: 'Happier (dev)',
+      identifier: 'dev.happier.app.publicdev',
+      app: {
+        windows: [{ title: 'Happier (dev)' }],
+      },
+    },
+    devUrl: 'http://localhost:19364',
+    env: {},
+  });
+
+  assert.equal(config.productName, 'Happier (dev)');
+  assert.equal(config.identifier, 'dev.happier.app.publicdev');
+  assert.equal(config.build.devUrl, 'http://localhost:19364');
+  assert.equal(config.build.beforeDevCommand, '');
+  assert.equal(config.build.beforeBuildCommand, '');
+  assert.deepEqual(config.bundle.externalBin, ['binaries/hsetup']);
+  assert.equal(config.app.windows[0]?.title, 'Happier (dev)');
+});
+
+test('buildStackTauriDevConfig applies explicit stack overrides after merging configs', () => {
+  const config = buildStackTauriDevConfig({
+    baseConfig: {
+      productName: 'Happier',
+      identifier: 'dev.happier.app',
+      build: {},
+      app: { windows: [{ title: 'Happier' }] },
+    },
+    overlayConfig: {
+      productName: 'Happier (dev)',
+      identifier: 'dev.happier.app.publicdev',
+    },
+    devUrl: 'http://localhost:18081',
+    env: {
+      HAPPIER_STACK_TAURI_PRODUCT_NAME: 'Happier (stack exp1)',
+      HAPPIER_STACK_TAURI_IDENTIFIER: 'com.happier.stack.exp1',
+    },
+  });
+
+  assert.equal(config.productName, 'Happier (stack exp1)');
+  assert.equal(config.identifier, 'com.happier.stack.exp1');
+  assert.equal(config.app.windows[0]?.title, 'Happier (stack exp1)');
+});