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

package/scripts/dev.mjs

@@ -1,6 +1,7 @@
 import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
 import { killProcessTree } from './utils/proc/proc.mjs';
+import { spawnProc } from './utils/proc/proc.mjs';
 import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths/paths.mjs';
 import { killPortListeners } from './utils/net/ports.mjs';
 import { getServerComponentName, isHappierServerRunning } from './utils/server/server.mjs';
@@ -29,11 +30,16 @@ import { getInvokedCwd, inferComponentFromCwd } from './utils/cli/cwd_scope.mjs'
 import { daemonStartGate, formatDaemonAuthRequiredError } from './utils/auth/daemon_gate.mjs';
 import { applyBindModeToEnv, resolveBindModeFromArgs } from './utils/net/bind_mode.mjs';
 import { cmd, sectionTitle } from './utils/ui/layout.mjs';
+import { renderTerminalUsageInstructions } from './utils/stack/terminal_usage_instructions.mjs';
+import { resolveStackActiveServerId } from './utils/auth/stable_scope_id.mjs';
 import { cyan, dim, green } from './utils/ui/ansi.mjs';
 import { isSandboxed } from './utils/env/sandbox.mjs';
 import { installExitCleanup } from './utils/proc/exit_cleanup.mjs';
 import { expandHome } from './utils/paths/canonical_home.mjs';
 import { buildConfigureServerLinks } from '@happier-dev/cli-common/links';
+import { spawnStackOwnerDeathWatchdog } from './utils/stack/owner_death_watchdog.mjs';
+import { resolveTauriPaneInvocation } from './utils/tui/tauri_mode.mjs';
+import { resolveReactNativeDevtoolsUrl } from './utils/dev/react_native_devtools.mjs';
 
  /**
   * Dev mode stack:
@@ -46,6 +52,9 @@ async function main() {
   const argv = process.argv.slice(2);
   const { flags, kv } = parseArgs(argv);
   const json = wantsJson(argv, { flags });
+  if (flags.has('--runtime') || flags.has('--source')) {
+    throw new Error('[dev] hstack dev does not support runtime mode flags. Use hstack start for runtime snapshots.');
+  }
   if (wantsHelp(argv, { flags })) {
     printResult({
       json,
@@ -62,6 +71,9 @@ async function main() {
           '--no-watch',
           '--no-browser',
           '--mobile',
+          '--rn-devtools',
+          '--react-native-devtools',
+          '--tauri',
           '--expo-tailscale',
           '--bind=loopback|lan',
           '--loopback',
@@ -73,9 +85,11 @@ async function main() {
 		        '[dev] usage:',
 		        '  hstack dev [--server=happier-server|happier-server-light] [--server-flavor=light|full] [--server-url=<http(s)://...>] [--no-server] [--restart] [--json]',
 		        '  hstack dev --watch         # rebuild/restart happier-cli daemon on file changes (TTY default)',
-		        '  hstack dev --no-watch      # disable watch mode (always disabled in non-interactive mode)',
-		        '  hstack dev --no-browser    # do not open the UI in your browser automatically',
-		        '  hstack dev --mobile        # also start Expo dev-client Metro for mobile',
+	        '  hstack dev --no-watch      # disable watch mode (always disabled in non-interactive mode)',
+	        '  hstack dev --no-browser    # do not open the UI in your browser automatically',
+	        '  hstack dev --mobile        # also start Expo dev-client Metro for mobile',
+	        '  hstack dev --rn-devtools   # open React Native DevTools (Metro debugger UI) in your browser',
+	        '  hstack dev --tauri         # start the desktop Tauri shell against this stack',
 	        '  hstack dev --expo-tailscale # forward Expo to Tailscale interface for remote access',
 	        '  hstack dev --bind=loopback  # prefer localhost-only URLs (not reachable from phones)',
 	        '  hstack dev --no-server --server-url=https://api.example.com',
@@ -86,6 +100,7 @@ async function main() {
         '',
         'env:',
         '  HAPPIER_STACK_EXPO_TAILSCALE=1   # enable Expo Tailscale forwarding via env var',
+        '  HAPPIER_STACK_EXPO_MAX_OLD_SPACE_SIZE_MB=8192  # default: 8192 (8GB) heap for the Expo/Metro Node process',
       ].join('\n'),
     });
     return;
@@ -130,12 +145,18 @@ async function main() {
 	    throw new Error(`[local] --server=both is not supported for dev (pick one: happier-server-light or happier-server)`);
 	  }
 
+  const startTauri = flags.has('--tauri') || flags.has('--with-tauri');
   const startUi = !flags.has('--no-ui');
   const startDaemon = !flags.has('--no-daemon');
   const startMobile = flags.has('--mobile') || flags.has('--with-mobile');
-  const noBrowser = flags.has('--no-browser') || (process.env.HAPPIER_STACK_NO_BROWSER ?? '').toString().trim() === '1';
+  const openReactNativeDevtools = flags.has('--rn-devtools') || flags.has('--react-native-devtools');
+  const noBrowser = startTauri || flags.has('--no-browser') || (process.env.HAPPIER_STACK_NO_BROWSER ?? '').toString().trim() === '1';
   const expoTailscale = flags.has('--expo-tailscale') || resolveExpoTailscaleEnabled({ env: process.env });
 
+  if (startTauri && !startUi) {
+    throw new Error('[local] --tauri requires the ui');
+  }
+
 	  const serverDir = getComponentDir(rootDir, serverComponentName);
 	  const uiDir = getComponentDir(rootDir, 'happier-ui');
 	  const cliDir = getComponentDir(rootDir, 'happier-cli');
@@ -204,7 +225,9 @@ async function main() {
         serverConnectionSource,
         startUi,
         startMobile,
+        startTauri,
         startDaemon,
+        openReactNativeDevtools,
         cliHomeDir,
       },
     });
@@ -236,7 +259,9 @@ async function main() {
   const serverAlreadyRunning = startServer
     ? await isHappierServerRunning(localInternalServerUrl)
     : false;
-  const daemonAlreadyRunning = startDaemon ? isDaemonRunning(cliHomeDir) : false;
+  const daemonAlreadyRunning = startDaemon
+    ? isDaemonRunning(cliHomeDir, { serverUrl: internalServerUrl, env: baseEnv })
+    : false;
 
   // Expo dev server state (worktree-scoped): single Expo process per stack/worktree.
   const startExpo = startUi || startMobile;
@@ -269,6 +294,15 @@ async function main() {
       ownerPid: process.pid,
       ports: startServer ? { server: serverPort } : {},
     }).catch(() => {});
+    spawnStackOwnerDeathWatchdog({
+      rootDir,
+      stackName,
+      baseDir: autostart.baseDir,
+      envPath,
+      runtimeStatePath,
+      ownerPid: process.pid,
+      env: baseEnv,
+    });
   }
 
   // Start server (only if not already healthy)
@@ -302,12 +336,15 @@ async function main() {
   } else {
     console.log(`${green('✓')} server: already running at ${cyan(internalServerUrl)}`);
   }
-  console.log('');
-  console.log(sectionTitle('Terminal usage'));
-  console.log(dim(`To run ${cyan('happier')} against this stack (and have sessions appear in the UI), export:`));
-  console.log(cmd(`export HAPPIER_SERVER_URL="${internalServerUrl}"`));
-  console.log(cmd(`export HAPPIER_HOME_DIR="${cliHomeDir}"`));
-  console.log(cmd(`export HAPPIER_WEBAPP_URL="${publicServerUrl}"`));
+  console.log(
+    renderTerminalUsageInstructions({
+      internalServerUrl,
+      cliHomeDir,
+      publicServerUrl,
+      activeServerId: resolveStackActiveServerId({ env: baseEnv, stackName }),
+      stackName,
+    }).join('\n'),
+  );
 
   // Reliability before daemon start:
   // - Ensure schema exists (server-light: prisma migrate deploy; happier-server: migrate deploy if tables missing)
@@ -422,6 +459,7 @@ async function main() {
         cliHomeDir,
         internalServerUrl,
         publicServerUrl,
+        runtimeStatePath,
         restart,
         isShuttingDown: () => shuttingDown,
         env: baseEnv,
@@ -439,6 +477,7 @@ async function main() {
     cliHomeDir,
     internalServerUrl,
     publicServerUrl,
+    runtimeStatePath,
     isShuttingDown: () => shuttingDown,
     env: baseEnv,
     stackName,
@@ -524,11 +563,40 @@ async function main() {
     }
   }
 
+  if (openReactNativeDevtools && expoRes?.port) {
+    const metroOriginRaw = `http://localhost:${expoRes.port}`;
+    const metroOrigin = await preferStackLocalhostUrl(metroOriginRaw, { stackName });
+    const devtoolsUrl = resolveReactNativeDevtoolsUrl({ metroUrl: metroOrigin, env: baseEnv });
+    if (devtoolsUrl) {
+      console.log(`[local] rn-devtools: open ${devtoolsUrl}`);
+      const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+      const shouldOpen = isInteractive && !noBrowser;
+      if (shouldOpen) {
+        await waitForHttpOk(devtoolsUrl, { timeoutMs: 30_000 }).catch(() => {});
+        const res = await openUrlInBrowser(devtoolsUrl);
+        if (!res.ok) {
+          console.warn(`[local] rn-devtools: failed to open browser automatically (${res.error}).`);
+        }
+      }
+    }
+  }
+
   if (startMobile && expoRes?.port) {
     const metroUrl = await preferStackLocalhostUrl(`http://localhost:${expoRes.port}`, { stackName });
     console.log(`[local] mobile: metro ${metroUrl}`);
   }
 
+  if (startTauri) {
+    const invocation = resolveTauriPaneInvocation({ rootDir, env: baseEnv });
+    const tauri = spawnProc('tauri', invocation.command, invocation.args, baseEnv, {
+      cwd: invocation.cwd,
+      ...(process.platform === 'win32'
+        ? { windowsHide: true, windowsVerbatimArguments: invocation.windowsVerbatimArguments }
+        : {}),
+    });
+    children.push(tauri);
+  }
+
   // Show Tailscale URL if forwarder is running
   if (expoRes?.tailscale?.ok && expoRes.tailscale.tailscaleIp && expoRes.port) {
     console.log(`[local] expo tailscale: http://${expoRes.tailscale.tailscaleIp}:${expoRes.port}`);
@@ -550,7 +618,7 @@ async function main() {
     }
 
     if (startDaemon) {
-      await stopLocalDaemon({ cliBin, internalServerUrl, cliHomeDir });
+      await stopLocalDaemon({ cliBin, internalServerUrl, cliHomeDir, runtimeStatePath });
     }
 
     for (const child of children) {

package/scripts/dev_external_server_flags.test.mjs

@@ -57,3 +57,19 @@ test('dev --server-url uses remote server mode', async () => {
   assert.equal(parsed.internalServerUrl, 'https://api.example.com');
   assert.equal(parsed.publicServerUrl, 'https://api.example.com');
 });
+
+test('dev --tauri --json reports desktop tauri mode', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const packageRoot = dirname(scriptsDir); // apps/stack
+  const repoRoot = dirname(dirname(packageRoot)); // repo root
+  const devScript = join(packageRoot, 'scripts', 'dev.mjs');
+
+  const res = await runNode(
+    [devScript, '--json', '--tauri'],
+    { cwd: repoRoot, env: process.env }
+  );
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  const parsed = JSON.parse(res.stdout);
+  assert.equal(parsed.startTauri, true);
+  assert.equal(parsed.startUi, true);
+});

package/scripts/dev_rn_devtools_flag.test.mjs

@@ -0,0 +1,24 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runNode } from './testkit/runtime_snapshot_testkit.mjs';
+
+function stackRootDirFromMeta(metaUrl) {
+  const scriptsDir = dirname(fileURLToPath(metaUrl));
+  return dirname(scriptsDir);
+}
+
+test('hstack dev --json reports React Native DevTools open when requested', async () => {
+  const rootDir = stackRootDirFromMeta(import.meta.url);
+  const res = await runNode([join(rootDir, 'scripts', 'dev.mjs'), '--json', '--rn-devtools', '--no-daemon', '--no-server', '--server-url=https://api.example.com'], {
+    cwd: rootDir,
+    env: process.env,
+  });
+
+  assert.equal(res.code, 0, `stdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  const parsed = JSON.parse(res.stdout);
+  assert.equal(parsed.openReactNativeDevtools, true);
+});
+

package/scripts/dev_runtime_mode_reject.test.mjs

@@ -0,0 +1,22 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runNode } from './testkit/runtime_snapshot_testkit.mjs';
+
+function stackRootDirFromMeta(metaUrl) {
+  const scriptsDir = dirname(fileURLToPath(metaUrl));
+  return dirname(scriptsDir);
+}
+
+test('hstack dev rejects runtime mode flags', async () => {
+  const rootDir = stackRootDirFromMeta(import.meta.url);
+  const res = await runNode([join(rootDir, 'scripts', 'dev.mjs'), '--runtime'], {
+    cwd: rootDir,
+    env: process.env,
+  });
+
+  assert.equal(res.code, 1, `stdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  assert.match(res.stderr + res.stdout, /does not support runtime mode/i);
+});

package/scripts/dev_tauri_flag.test.mjs

@@ -0,0 +1,35 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runNode } from './testkit/runtime_snapshot_testkit.mjs';
+
+function stackRootDirFromMeta(metaUrl) {
+  const scriptsDir = dirname(fileURLToPath(metaUrl));
+  return dirname(scriptsDir);
+}
+
+test('hstack dev --json reports tauri startup when requested', async () => {
+  const rootDir = stackRootDirFromMeta(import.meta.url);
+  const res = await runNode([join(rootDir, 'scripts', 'dev.mjs'), '--json', '--tauri', '--server-url=https://api.example.com', '--no-daemon'], {
+    cwd: rootDir,
+    env: process.env,
+  });
+
+  assert.equal(res.code, 0, `stdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  const parsed = JSON.parse(res.stdout);
+  assert.equal(parsed.startTauri, true);
+  assert.equal(parsed.startUi, true);
+});
+
+test('hstack dev rejects --tauri when ui is disabled', async () => {
+  const rootDir = stackRootDirFromMeta(import.meta.url);
+  const res = await runNode([join(rootDir, 'scripts', 'dev.mjs'), '--tauri', '--no-ui', '--server-url=https://api.example.com', '--no-daemon'], {
+    cwd: rootDir,
+    env: process.env,
+  });
+
+  assert.equal(res.code, 1, `stdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  assert.match(res.stderr + res.stdout, /--tauri requires the ui/i);
+});

package/scripts/doctor.mjs

@@ -23,6 +23,8 @@ import { banner, bullets, cmd, kv, sectionTitle } from './utils/ui/layout.mjs';
 import { cyan, dim, green, red, yellow } from './utils/ui/ansi.mjs';
 import { detectSwiftbarPluginInstalled } from './utils/menubar/swiftbar.mjs';
 import { expandHome } from './utils/paths/canonical_home.mjs';
+import { resolveStackRuntimeLaunchContext } from './runtime/launch/resolveStackRuntimeLaunchContext.mjs';
+import { inspectActiveRuntimeSnapshot } from './runtime/launch/inspectActiveRuntimeSnapshot.mjs';
 
 /**
  * Doctor script for common happy-stacks failure modes.
@@ -103,6 +105,9 @@ async function main() {
   const autostart = getDefaultAutostartPaths();
   const stackCtx = resolveStackContext({ env: process.env, autostart });
   const stackMode = stackCtx.stackMode;
+  const runtimeLaunchContext = await resolveStackRuntimeLaunchContext({ argv, env: process.env });
+  const runtimeInspection = await inspectActiveRuntimeSnapshot({ stackBaseDir: runtimeLaunchContext.stackBaseDir });
+  const runtimeSnapshot = runtimeLaunchContext.snapshot;
 
   const serverPort = resolveServerPortFromEnv({ defaultPort: 3005 });
   const resolvedUrls = await resolveServerUrls({ serverPort, allowEnable: false });
@@ -114,9 +119,12 @@ async function main() {
     : join(autostart.baseDir, 'cli');
 
   const serveUi = (process.env.HAPPIER_STACK_SERVE_UI ?? '1') !== '0';
-  const uiBuildDir = process.env.HAPPIER_STACK_UI_BUILD_DIR?.trim()
+  const sourceUiBuildDir = process.env.HAPPIER_STACK_UI_BUILD_DIR?.trim()
     ? process.env.HAPPIER_STACK_UI_BUILD_DIR.trim()
     : join(autostart.baseDir, 'ui');
+  const uiBuildDir = runtimeSnapshot
+    ? join(runtimeSnapshot.launchPath ?? runtimeSnapshot.snapshotPath, 'ui')
+    : sourceUiBuildDir;
 
 	  const serverComponentName = getServerComponentName({ kv: argsKv });
 	  if (serverComponentName === 'both') {
@@ -142,6 +150,13 @@ async function main() {
       version: runtimeVersion,
       packageJson: runtimePkgJson,
       updateCache,
+      mode: runtimeLaunchContext.runtimeMode.mode,
+      activeSnapshotId: runtimeInspection.activeSnapshotId,
+      snapshotPath: runtimeInspection.snapshotPath,
+      sourceFingerprint: runtimeInspection.sourceFingerprint,
+      valid: runtimeInspection.valid,
+      errors: runtimeInspection.errors,
+      components: runtimeInspection.manifest?.components ?? null,
     },
     env: {
       homeEnv: join(homeDir, '.env'),
@@ -169,6 +184,7 @@ async function main() {
       kv('cliHome:', cliHomeDir),
       kv('home:', homeDir),
       kv('runtime:', runtimeVersion ? `${runtimeDir} (${runtimeVersion})` : `${runtimeDir} (${yellow('not installed')})`),
+      kv('stackRuntime:', runtimeSnapshot?.snapshotId ? `${runtimeSnapshot.snapshotId} (${runtimeLaunchContext.runtimeMode.mode})` : `(${dim(runtimeLaunchContext.runtimeMode.mode)})`),
       kv('workspace:', workspaceDir),
     ]));
     console.log('');

package/scripts/doctor_runtime_snapshot.test.mjs

@@ -0,0 +1,68 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { createRuntimeSnapshotFixture, runNode } from './testkit/runtime_snapshot_testkit.mjs';
+
+function stackRootDirFromMeta(metaUrl) {
+  const scriptsDir = dirname(fileURLToPath(metaUrl));
+  return dirname(scriptsDir);
+}
+
+test('doctor --json reports the active runtime snapshot', async (t) => {
+  const rootDir = stackRootDirFromMeta(import.meta.url);
+  const fixture = await createRuntimeSnapshotFixture(t);
+
+  const env = {
+    ...process.env,
+    HAPPIER_STACK_STACK: fixture.stackName,
+    HAPPIER_STACK_STORAGE_DIR: fixture.storageDir,
+    HAPPIER_STACK_ENV_FILE: join(fixture.stackDir, 'env'),
+    HAPPIER_STACK_REPO_DIR: rootDir,
+    HAPPIER_STACK_RUNTIME_MODE: 'prefer',
+  };
+
+  const res = await runNode([join(rootDir, 'scripts', 'doctor.mjs'), '--json'], { cwd: rootDir, env });
+  assert.equal(res.code, 0, `stderr:\n${res.stderr}\nstdout:\n${res.stdout}`);
+  const parsed = JSON.parse(res.stdout);
+  assert.equal(parsed.runtime.activeSnapshotId, 'snap-1');
+  assert.equal(parsed.runtime.snapshotPath, fixture.snapshotDir);
+  assert.equal(parsed.runtime.mode, 'prefer');
+  assert.equal(parsed.uiBuildDir, join(fixture.stackDir, 'runtime', 'current', 'ui'));
+  assert.equal(parsed.checks.uiBuildDir?.ok, true);
+  assert.equal(parsed.checks.uiBuildDir?.path, join(fixture.stackDir, 'runtime', 'current', 'ui'));
+});
+
+test('doctor --json reports invalid active runtime snapshots even in prefer mode', async (t) => {
+  const rootDir = stackRootDirFromMeta(import.meta.url);
+  const fixture = await createRuntimeSnapshotFixture(t);
+  await writeFile(
+    join(fixture.stackDir, 'runtime', 'current.json'),
+    JSON.stringify({
+      version: 1,
+      snapshotId: 'snap-1',
+      snapshotPath: join(fixture.root, 'escaped-runtime'),
+      sourceFingerprint: 'src-1',
+    }, null, 2) + '\n',
+    'utf-8',
+  );
+
+  const env = {
+    ...process.env,
+    HAPPIER_STACK_STACK: fixture.stackName,
+    HAPPIER_STACK_STORAGE_DIR: fixture.storageDir,
+    HAPPIER_STACK_ENV_FILE: join(fixture.stackDir, 'env'),
+    HAPPIER_STACK_REPO_DIR: rootDir,
+    HAPPIER_STACK_RUNTIME_MODE: 'prefer',
+  };
+
+  const res = await runNode([join(rootDir, 'scripts', 'doctor.mjs'), '--json'], { cwd: rootDir, env });
+  assert.equal(res.code, 0, `stderr:\n${res.stderr}\nstdout:\n${res.stdout}`);
+  const parsed = JSON.parse(res.stdout);
+  assert.equal(parsed.runtime.activeSnapshotId, 'snap-1');
+  assert.equal(parsed.runtime.snapshotPath, join(fixture.root, 'escaped-runtime'));
+  assert.equal(parsed.runtime.valid, false);
+  assert.match(parsed.runtime.errors.join('\n'), /outside the stack runtime builds dir/i);
+});