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

package/scripts/dev.mjs

@@ -16,6 +16,8 @@ import { resolveStackContext } from './utils/stack/context.mjs';
 import { resolveServerPortFromEnv, resolveServerUrls } from './utils/server/urls.mjs';
 import { ensureDevCliReady, prepareDaemonAuthSeed, startDevDaemon, watchHappyCliAndRestartDaemon } from './utils/dev/daemon.mjs';
 import { startDevServer, watchDevServerAndRestart } from './utils/dev/server.mjs';
+import { resolveDevServerConnection } from './utils/dev/resolveDevServerConnection.mjs';
+import { resolveLocalServerPortForStack } from './utils/server/resolve_stack_server_port.mjs';
 import { ensureDevExpoServer, resolveExpoTailscaleEnabled } from './utils/dev/expo_dev.mjs';
 import { preferStackLocalhostUrl } from './utils/paths/localhost_host.mjs';
 import { openUrlInBrowser } from './utils/ui/browser.mjs';
@@ -47,12 +49,14 @@ async function main() {
   if (wantsHelp(argv, { flags })) {
     printResult({
       json,
-      data: {
-	        flags: [
-	          '--server=happier-server|happier-server-light',
-	          '--server-flavor=light|full',
-	          '--no-ui',
-	          '--no-daemon',
+	      data: {
+		        flags: [
+		          '--server=happier-server|happier-server-light',
+		          '--server-flavor=light|full',
+              '--server-url=http(s)://host[:port]',
+              '--no-server',
+		          '--no-ui',
+		          '--no-daemon',
           '--restart',
           '--watch',
           '--no-watch',
@@ -65,16 +69,17 @@ async function main() {
         ],
         json: true,
       },
-	      text: [
-	        '[dev] usage:',
-	        '  hstack dev [--server=happier-server|happier-server-light] [--server-flavor=light|full] [--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 --expo-tailscale # forward Expo to Tailscale interface for remote access',
-        '  hstack dev --bind=loopback  # prefer localhost-only URLs (not reachable from phones)',
-        '  note: --json prints the resolved config (dry-run) and exits.',
+		      text: [
+		        '[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 --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',
+	        '  note: --json prints the resolved config (dry-run) and exits.',
         '',
         'note:',
         '  If run from inside a repo checkout/worktree, that checkout is used for this run (without requiring `hstack wt use`).',
@@ -141,7 +146,13 @@ async function main() {
   const stackCtx = resolveStackContext({ env: baseEnv, autostart });
   const { stackMode, runtimeStatePath, stackName, envPath, ephemeral } = stackCtx;
 
-  const serverPort = resolveServerPortFromEnv({ env: baseEnv, defaultPort: 3005 });
+  const serverPort = await resolveLocalServerPortForStack({
+    env: baseEnv,
+    stackMode,
+    stackName,
+    runtimeStatePath,
+    defaultPort: 3005,
+  });
   // IMPORTANT:
   // - Only the main stack should ever auto-enable (or prefer) Tailscale Serve by default.
   // - Non-main stacks should default to localhost URLs unless the user explicitly configured a public URL
@@ -151,9 +162,17 @@ async function main() {
     stackName === 'main' ||
     (baseEnv.HAPPIER_STACK_TAILSCALE_SERVE ?? '0').toString().trim() === '1';
   const resolvedUrls = await resolveServerUrls({ env: baseEnv, serverPort, allowEnable: allowEnableTailscale });
-  const internalServerUrl = resolvedUrls.internalServerUrl;
-  let publicServerUrl = resolvedUrls.publicServerUrl;
-  if (stackMode && stackName !== 'main' && !resolvedUrls.envPublicUrl) {
+  const serverConnection = resolveDevServerConnection({
+    flags,
+    kv,
+    env: baseEnv,
+    resolvedLocalUrls: resolvedUrls,
+  });
+  const startServer = serverConnection.startServer;
+  const localInternalServerUrl = resolvedUrls.internalServerUrl;
+  const internalServerUrl = serverConnection.internalServerUrl;
+  let publicServerUrl = serverConnection.publicServerUrl;
+  if (startServer && stackMode && stackName !== 'main' && !resolvedUrls.envPublicUrl) {
     const src = String(resolvedUrls.publicServerUrlSource ?? '');
     const hasStackScopedTailscale = src.startsWith('tailscale-');
     if (!hasStackScopedTailscale) {
@@ -162,7 +181,8 @@ async function main() {
   }
   // Expo app config: this is what both web + native app use to reach the Happy server.
   // LAN rewrite (for dev-client) is centralized in ensureDevExpoServer.
-  const uiApiUrl = resolvedUrls.defaultPublicUrl;
+  const uiApiUrl = startServer ? resolvedUrls.defaultPublicUrl : serverConnection.uiApiUrl;
+  const serverConnectionSource = serverConnection.source;
   const restart = flags.has('--restart');
   const cliHomeDir = process.env.HAPPIER_STACK_CLI_HOME_DIR?.trim()
     ? expandHome(process.env.HAPPIER_STACK_CLI_HOME_DIR.trim())
@@ -180,6 +200,8 @@ async function main() {
         serverPort,
         internalServerUrl,
         publicServerUrl,
+        startServer,
+        serverConnectionSource,
         startUi,
         startMobile,
         startDaemon,
@@ -189,10 +211,11 @@ async function main() {
     return;
   }
 
-  assertServerComponentDirMatches({ rootDir, serverComponentName, serverDir });
-  assertServerPrismaProviderMatches({ serverComponentName, serverDir });
-
-  await requireDir(serverComponentName, serverDir);
+  if (startServer) {
+    assertServerComponentDirMatches({ rootDir, serverComponentName, serverDir });
+    assertServerPrismaProviderMatches({ serverComponentName, serverDir });
+    await requireDir(serverComponentName, serverDir);
+  }
   await requireDir('happier-ui', uiDir);
   await requireDir('happier-cli', cliDir);
 
@@ -210,7 +233,9 @@ async function main() {
     flags.has('--watch') || (!flags.has('--no-watch') && Boolean(process.stdin.isTTY && process.stdout.isTTY));
   const watchers = [];
 
-  const serverAlreadyRunning = await isHappierServerRunning(internalServerUrl);
+  const serverAlreadyRunning = startServer
+    ? await isHappierServerRunning(localInternalServerUrl)
+    : false;
   const daemonAlreadyRunning = startDaemon ? isDaemonRunning(cliHomeDir) : false;
 
   // Expo dev server state (worktree-scoped): single Expo process per stack/worktree.
@@ -224,10 +249,10 @@ async function main() {
   const expoRunning = startExpo ? await isStateProcessRunning(expoPaths.statePath) : { running: false, state: null };
   let expoAlreadyRunning = Boolean(expoRunning.running);
 
-  if (!restart && serverAlreadyRunning && (!startDaemon || daemonAlreadyRunning) && (!startExpo || expoAlreadyRunning)) {
+  if (!restart && (!startServer || serverAlreadyRunning) && (!startDaemon || daemonAlreadyRunning) && (!startExpo || expoAlreadyRunning)) {
     console.log(
       `${green('✓')} dev: already running ${dim('(')}` +
-        `${dim('server=')}${cyan(internalServerUrl)}` +
+        `${dim('server=')}${cyan(internalServerUrl)}${startServer ? '' : dim(' (external)')}` +
         `${startDaemon ? ` ${dim('daemon=')}${daemonAlreadyRunning ? green('running') : dim('stopped')}` : ''}` +
         `${startUi ? ` ${dim('ui=')}${expoAlreadyRunning ? green('running') : dim('stopped')}` : ''}` +
         `${startMobile ? ` ${dim('mobile=')}${expoAlreadyRunning ? green('running') : dim('stopped')}` : ''}` +
@@ -242,33 +267,37 @@ async function main() {
       script: 'dev.mjs',
       ephemeral,
       ownerPid: process.pid,
-      ports: { server: serverPort },
+      ports: startServer ? { server: serverPort } : {},
     }).catch(() => {});
   }
 
   // Start server (only if not already healthy)
   // NOTE: In stack mode we avoid killing arbitrary port listeners (fail-closed instead).
-  if ((!serverAlreadyRunning || restart) && !stackMode) {
+  if (startServer && (!serverAlreadyRunning || restart) && !stackMode) {
     await killPortListeners(serverPort, { label: 'server' });
   }
 
-  const { serverEnv, serverScript, serverProc } = await startDevServer({
-    serverComponentName,
-    serverDir,
-    autostart,
-    baseEnv,
-    serverPort,
-    internalServerUrl,
-    publicServerUrl,
-    envPath,
-    stackMode,
-    runtimeStatePath,
-    serverAlreadyRunning,
-    restart,
-    children,
-  });
+  const { serverEnv, serverScript, serverProc } = startServer
+    ? await startDevServer({
+        serverComponentName,
+        serverDir,
+        autostart,
+        baseEnv,
+        serverPort,
+        internalServerUrl: localInternalServerUrl,
+        publicServerUrl,
+        envPath,
+        stackMode,
+        runtimeStatePath,
+        serverAlreadyRunning,
+        restart,
+        children,
+      })
+    : { serverEnv: baseEnv, serverScript: null, serverProc: null };
 
-  if (!serverAlreadyRunning || restart) {
+  if (!startServer) {
+    console.log(`${green('✓')} server: external ${cyan(internalServerUrl)}`);
+  } else if (!serverAlreadyRunning || restart) {
     console.log(`${green('✓')} server: ready at ${cyan(internalServerUrl)}`);
   } else {
     console.log(`${green('✓')} server: already running at ${cyan(internalServerUrl)}`);
@@ -284,13 +313,16 @@ async function main() {
   // - Ensure schema exists (server-light: prisma migrate deploy; happier-server: migrate deploy if tables missing)
   // - Auto-seed from main only when needed (non-main + non-interactive default, and only if missing creds or 0 accounts)
   const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
-  const accountProbe = await getAccountCountForServerComponent({
-    serverComponentName,
-    serverDir,
-    env: serverEnv,
-    bestEffort: true,
-  });
-  const accountCount = typeof accountProbe.accountCount === 'number' ? accountProbe.accountCount : null;
+  const accountProbe = startServer
+    ? await getAccountCountForServerComponent({
+        serverComponentName,
+        serverDir,
+        env: serverEnv,
+        bestEffort: true,
+      })
+    : null;
+  const accountCount =
+    startServer && typeof accountProbe?.accountCount === 'number' ? accountProbe.accountCount : null;
   const autoSeedEnabled = resolveAutoCopyFromMainEnabled({ env: baseEnv, stackName, isInteractive });
 
   let expoResEarly = null;
@@ -298,46 +330,12 @@ async function main() {
     (baseEnv.HAPPIER_STACK_AUTH_FLOW ?? '').toString().trim() === '1' ||
     (baseEnv.HAPPIER_STACK_DAEMON_WAIT_FOR_AUTH ?? '').toString().trim() === '1';
 
-  // CRITICAL (review-pr / setup-pr guided login):
-  // In background/non-interactive runs, the daemon may block on auth. If we wait to start Expo web
-  // until after the daemon is authenticated, guided login will have no UI origin and will fall back
-  // to the server port (wrong). Start Expo web UI early when running an auth flow.
-  if (wantsAuthFlow && startUi && !expoResEarly) {
-    expoResEarly = await ensureDevExpoServer({
-      startUi,
-      startMobile,
-      uiDir,
-      autostart,
-      baseEnv,
-      apiServerUrl: uiApiUrl,
-      restart,
-      stackMode,
-      runtimeStatePath,
-      stackName,
-      envPath,
-      children,
-      spawnOptions: { stdio: ['ignore', 'ignore', 'ignore'] },
-      expoTailscale,
-    });
-  }
-  await maybeRunInteractiveStackAuthSetup({
-    rootDir,
-    // In dev mode, guided login must target the Expo web UI origin (not the server port).
-    // Mark this as an auth-flow so URL resolution fails closed if Expo isn't ready.
-    env: startUi ? { ...baseEnv, HAPPIER_STACK_AUTH_FLOW: '1' } : baseEnv,
-    stackName,
-    cliHomeDir,
-    accountCount,
-    isInteractive,
-    autoSeedEnabled,
-    beforeLogin: async () => {
-      if (!startUi) {
-        throw new Error(
-          `[local] auth: interactive login requires the web UI.\n` +
-            `Re-run without --no-ui, or set HAPPIER_WEBAPP_URL to a reachable Happier UI for this stack.`
-        );
-      }
-      if (expoResEarly) return;
+  if (startServer) {
+    // CRITICAL (review-pr / setup-pr guided login):
+    // In background/non-interactive runs, the daemon may block on auth. If we wait to start Expo web
+    // until after the daemon is authenticated, guided login will have no UI origin and will fall back
+    // to the server port (wrong). Start Expo web UI early when running an auth flow.
+    if (wantsAuthFlow && startUi && !expoResEarly) {
       expoResEarly = await ensureDevExpoServer({
         startUi,
         startMobile,
@@ -351,22 +349,58 @@ async function main() {
         stackName,
         envPath,
         children,
+        spawnOptions: { stdio: ['ignore', 'ignore', 'ignore'] },
         expoTailscale,
       });
-    },
-  });
-  await prepareDaemonAuthSeed({
-    rootDir,
-    env: baseEnv,
-    stackName,
-    cliHomeDir,
-    startDaemon,
-    isInteractive,
-    serverComponentName,
-    serverDir,
-    serverEnv,
-    quiet: false,
-  });
+    }
+    await maybeRunInteractiveStackAuthSetup({
+      rootDir,
+      // In dev mode, guided login must target the Expo web UI origin (not the server port).
+      // Mark this as an auth-flow so URL resolution fails closed if Expo isn't ready.
+      env: startUi ? { ...baseEnv, HAPPIER_STACK_AUTH_FLOW: '1' } : baseEnv,
+      stackName,
+      cliHomeDir,
+      accountCount,
+      isInteractive,
+      autoSeedEnabled,
+      beforeLogin: async () => {
+        if (!startUi) {
+          throw new Error(
+            `[local] auth: interactive login requires the web UI.\n` +
+              `Re-run without --no-ui, or set HAPPIER_WEBAPP_URL to a reachable Happier UI for this stack.`
+          );
+        }
+        if (expoResEarly) return;
+        expoResEarly = await ensureDevExpoServer({
+          startUi,
+          startMobile,
+          uiDir,
+          autostart,
+          baseEnv,
+          apiServerUrl: uiApiUrl,
+          restart,
+          stackMode,
+          runtimeStatePath,
+          stackName,
+          envPath,
+          children,
+          expoTailscale,
+        });
+      },
+    });
+    await prepareDaemonAuthSeed({
+      rootDir,
+      env: baseEnv,
+      stackName,
+      cliHomeDir,
+      startDaemon,
+      isInteractive,
+      serverComponentName,
+      serverDir,
+      serverEnv,
+      quiet: false,
+    });
+  }
 
   if (startDaemon) {
     const gate = daemonStartGate({ env: baseEnv, cliHomeDir, serverUrl: internalServerUrl });
@@ -412,7 +446,7 @@ async function main() {
   if (cliWatcher) watchers.push(cliWatcher);
 
   const serverProcRef = { current: serverProc };
-  if (stackMode && runtimeStatePath && !serverProcRef.current?.pid) {
+  if (startServer && stackMode && runtimeStatePath && !serverProcRef.current?.pid) {
     // If the server was already running when we started dev, `startDevServer` won't spawn a new process
     // (and therefore we don't have a ChildProcess handle). For safe watch/restart we need a PID.
     const state = await readStackRuntimeStateFile(runtimeStatePath);
@@ -422,7 +456,7 @@ async function main() {
     }
   }
   const serverWatcher = watchDevServerAndRestart({
-    enabled: watchEnabled && Boolean(serverProcRef.current?.pid),
+    enabled: startServer && watchEnabled && Boolean(serverProcRef.current?.pid),
     stackMode,
     serverComponentName,
     serverDir,
@@ -438,7 +472,7 @@ async function main() {
     isShuttingDown: () => shuttingDown,
   });
   if (serverWatcher) watchers.push(serverWatcher);
-  if (watchEnabled && stackMode && serverComponentName === 'happier-server' && !serverWatcher) {
+  if (startServer && watchEnabled && stackMode && serverComponentName === 'happier-server' && !serverWatcher) {
     console.warn(
       `[local] watch: server restart is disabled because the running server PID is unknown.\n` +
         `[local] watch: fix: re-run with --restart so hstack can (re)spawn the server and track its PID.`

package/scripts/dev_external_server_flags.test.mjs

@@ -0,0 +1,59 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+
+function runNode(args, { cwd, env }) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(process.execPath, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (d) => (stdout += String(d)));
+    proc.stderr.on('data', (d) => (stderr += String(d)));
+    proc.on('error', reject);
+    proc.on('exit', (code, signal) => resolve({ code: code ?? (signal ? 1 : 0), signal, stdout, stderr }));
+  });
+}
+
+test('dev --json reports local server mode by default', 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'], { 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.startServer, true);
+  assert.equal(parsed.serverConnectionSource, 'local');
+});
+
+test('dev --no-server --json fails without an external server URL', 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, '--no-server', '--json'], { cwd: repoRoot, env: process.env });
+  assert.equal(res.code, 1);
+  assert.match(res.stderr, /--no-server requires an external server URL/);
+});
+
+test('dev --server-url uses remote server 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', '--server-url=https://api.example.com'],
+    { 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.startServer, false);
+  assert.equal(parsed.serverConnectionSource, 'cli-arg');
+  assert.equal(parsed.internalServerUrl, 'https://api.example.com');
+  assert.equal(parsed.publicServerUrl, 'https://api.example.com');
+});

package/scripts/ghops.mjs

@@ -0,0 +1,80 @@
+import { spawnSync } from 'node:child_process';
+import { mkdirSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+
+function printHelp() {
+  process.stdout.write(`
+ghops: run GitHub CLI as the Happier bot
+
+Usage:
+  yarn ghops <gh-subcommand> [...args]
+
+Required:
+  HAPPIER_GITHUB_BOT_TOKEN   Fine-grained PAT for the bot account.
+
+Optional:
+  HAPPIER_GHOPS_GH_PATH      Path to the 'gh' executable (default: "gh")
+  HAPPIER_GHOPS_CONFIG_DIR   Override GH_CONFIG_DIR (default: <repo>/.happier/local/ghops/gh)
+
+Behavior:
+  - Forces GH_TOKEN from HAPPIER_GITHUB_BOT_TOKEN (no fallback to stored gh auth)
+  - Disables interactive prompts (GH_PROMPT_DISABLED=1)
+  - Uses an isolated GH_CONFIG_DIR by default
+
+Examples:
+  yarn ghops api user
+  yarn ghops api repos/happier-dev/happier/issues -f title="Bug" -f body="..."
+  yarn ghops issue create --repo happier-dev/happier --title "Bug" --body "..."
+  yarn ghops project item-add 1 --owner happier-dev --url https://github.com/happier-dev/happier/issues/43
+`.trimStart());
+}
+
+function resolveRepoRoot(cwd) {
+  const res = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' });
+  if (res.status !== 0) return resolve(cwd);
+  const out = String(res.stdout ?? '').trim();
+  return out ? resolve(out) : resolve(cwd);
+}
+
+function resolvePath(repoRoot, maybePath) {
+  const trimmed = String(maybePath ?? '').trim();
+  if (!trimmed) return null;
+  return isAbsolute(trimmed) ? trimmed : resolve(repoRoot, trimmed);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args.includes('--help') || args[0] === 'help') {
+    printHelp();
+    process.exit(0);
+  }
+
+  const token = String(process.env.HAPPIER_GITHUB_BOT_TOKEN ?? '').trim();
+  if (!token) {
+    process.stderr.write('[ghops] missing required env var: HAPPIER_GITHUB_BOT_TOKEN\n');
+    process.exit(2);
+  }
+
+  const ghPath = String(process.env.HAPPIER_GHOPS_GH_PATH ?? '').trim() || 'gh';
+  const repoRoot = resolveRepoRoot(process.cwd());
+  const configDir =
+    resolvePath(repoRoot, process.env.HAPPIER_GHOPS_CONFIG_DIR) ?? join(repoRoot, '.happier', 'local', 'ghops', 'gh');
+
+  mkdirSync(configDir, { recursive: true });
+
+  const env = {
+    ...process.env,
+    GH_TOKEN: token,
+    GH_PROMPT_DISABLED: '1',
+    GH_CONFIG_DIR: configDir,
+  };
+
+  const res = spawnSync(ghPath, args, { stdio: 'inherit', env });
+  if (res.error) {
+    process.stderr.write(`[ghops] failed to run gh (${ghPath}): ${String(res.error?.message ?? res.error)}\n`);
+    process.exit(1);
+  }
+  process.exit(res.status ?? 1);
+}
+
+main();

package/scripts/ghops.test.mjs

@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { chmodSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const ghopsPath = fileURLToPath(new URL('./ghops.mjs', import.meta.url));
+const repoRoot = resolve(fileURLToPath(new URL('../../../', import.meta.url)));
+
+function runGhop(args, env = {}) {
+  return spawnSync(process.execPath, [ghopsPath, ...args], {
+    cwd: repoRoot,
+    env: { ...process.env, ...env },
+    encoding: 'utf8',
+  });
+}
+
+test('prints help without requiring a token', () => {
+  const res = runGhop(['--help'], {
+    HAPPIER_GITHUB_BOT_TOKEN: '',
+    GH_TOKEN: '',
+    GITHUB_TOKEN: '',
+  });
+  assert.equal(res.status, 0);
+  assert.match(res.stdout, /HAPPIER_GITHUB_BOT_TOKEN/);
+  assert.doesNotMatch(res.stdout, /\.project\//);
+  assert.match(res.stdout, /\.happier\/local\/ghops\/gh/);
+});
+
+test('fails closed when token is missing', () => {
+  const res = runGhop(['api', 'user'], {
+    HAPPIER_GITHUB_BOT_TOKEN: '',
+    GH_TOKEN: '',
+    GITHUB_TOKEN: '',
+  });
+  assert.notEqual(res.status, 0);
+  assert.match(res.stderr, /HAPPIER_GITHUB_BOT_TOKEN/);
+});
+
+test('forwards args and forces gh auth via HAPPIER_GITHUB_BOT_TOKEN', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'ghops-test-'));
+  const fakeGh = join(dir, 'fake-gh');
+  const configDir = join(dir, 'gh-config');
+
+  writeFileSync(
+    fakeGh,
+    `#!/usr/bin/env node
+const payload = {
+  argv: process.argv.slice(2),
+  env: {
+    GH_TOKEN: process.env.GH_TOKEN ?? null,
+    GH_PROMPT_DISABLED: process.env.GH_PROMPT_DISABLED ?? null,
+    GH_CONFIG_DIR: process.env.GH_CONFIG_DIR ?? null,
+  },
+};
+process.stdout.write(JSON.stringify(payload));
+`,
+    'utf8',
+  );
+  chmodSync(fakeGh, 0o755);
+
+  const token = 'test-bot-token';
+  const res = runGhop(['api', 'repos/happier-dev/happier'], {
+    HAPPIER_GITHUB_BOT_TOKEN: token,
+    HAPPIER_GHOPS_GH_PATH: fakeGh,
+    HAPPIER_GHOPS_CONFIG_DIR: configDir,
+    GH_TOKEN: 'personal-token-should-not-be-used',
+  });
+
+  assert.equal(res.status, 0, res.stderr);
+  const out = JSON.parse(res.stdout);
+  assert.deepEqual(out.argv, ['api', 'repos/happier-dev/happier']);
+  assert.equal(out.env.GH_TOKEN, token);
+  assert.equal(out.env.GH_PROMPT_DISABLED, '1');
+  assert.equal(out.env.GH_CONFIG_DIR, configDir);
+});

package/scripts/init.mjs

@@ -313,11 +313,15 @@ async function main() {
     'set -euo pipefail',
     `CANONICAL_ENV="${canonicalEnvPath}"`,
     '',
+    // Preserve the caller's original working directory so the Node CLI can infer
+    // repo/worktree context even if this shim `cd`s into the workspace root.
+    'export HAPPIER_STACK_INVOKED_CWD="${HAPPIER_STACK_INVOKED_CWD:-$PWD}"',
+    '',
     '# Best-effort: if env vars are not exported (common under launchd/SwiftBar),',
     '# read the stable pointer file at CANONICAL_ENV to discover the real dirs.',
     'if [[ -f "$CANONICAL_ENV" ]]; then',
     '  if [[ -z "${HAPPIER_STACK_HOME_DIR:-}" ]]; then',
-    '    HAPPIER_STACK_HOME_DIR="$(grep -E \'^HAPPIER_STACK_HOME_DIR=\' "$CANONICAL_ENV" | head -n 1 | sed \'s/^HAPPIER_STACK_HOME_DIR=//\')" || true',
+      '    HAPPIER_STACK_HOME_DIR="$(grep -E \'^HAPPIER_STACK_HOME_DIR=\' "$CANONICAL_ENV" | head -n 1 | sed \'s/^HAPPIER_STACK_HOME_DIR=//\')" || true',
     '    export HAPPIER_STACK_HOME_DIR',
     '  fi',
     '  if [[ -z "${HAPPIER_STACK_WORKSPACE_DIR:-}" ]]; then',

package/scripts/init_shim_invoked_cwd.test.mjs

@@ -0,0 +1,51 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { dirname, join } from 'node:path';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+function runNode(args, { cwd, env }) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(process.execPath, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (d) => (stdout += String(d)));
+    proc.stderr.on('data', (d) => (stderr += String(d)));
+    proc.on('error', reject);
+    proc.on('exit', (code, signal) => resolve({ code: code ?? (signal ? 1 : 0), signal, stdout, stderr }));
+  });
+}
+
+test('hstack init shim preserves HAPPIER_STACK_INVOKED_CWD before changing directories', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const rootDir = dirname(scriptsDir);
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-init-shim-'));
+
+  const homeDir = join(tmp, 'home');
+  const canonicalHomeDir = join(tmp, 'canonical');
+  const workspaceDir = join(tmp, 'workspace');
+
+  try {
+    const res = await runNode(
+      [
+        join(rootDir, 'scripts', 'init.mjs'),
+        `--home-dir=${homeDir}`,
+        `--canonical-home-dir=${canonicalHomeDir}`,
+        `--workspace-dir=${workspaceDir}`,
+        '--no-runtime',
+        '--no-bootstrap',
+      ],
+      { cwd: rootDir, env: { ...process.env } }
+    );
+    assert.equal(res.code, 0, `expected init to exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+    const shimPath = join(homeDir, 'bin', 'hstack');
+    const shim = await readFile(shimPath, 'utf-8');
+    assert.match(shim, /HAPPIER_STACK_INVOKED_CWD/, 'expected shim to reference HAPPIER_STACK_INVOKED_CWD');
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+