@happier-dev/stack 0.1.0-preview.74.1

package/scripts/stack/stack_daemon_command.mjs

@@ -0,0 +1,219 @@
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { findExistingStackCredentialPath } from '../utils/auth/credentials_paths.mjs';
+import { parseArgs } from '../utils/cli/args.mjs';
+import { printResult, wantsHelp } from '../utils/cli/cli.mjs';
+import { isTty, promptSelect, withRl } from '../utils/cli/wizard.mjs';
+import { daemonStatusSummary, startLocalDaemonWithAuth, stopLocalDaemon } from '../daemon.mjs';
+import { getComponentDir, resolveStackEnvPath } from '../utils/paths/paths.mjs';
+import { run } from '../utils/proc/proc.mjs';
+import { resolveServerPortFromEnv, resolveServerUrls } from '../utils/server/urls.mjs';
+import { parseCliIdentityOrThrow, resolveCliHomeDirForIdentity } from '../utils/stack/cli_identities.mjs';
+import { readStackRuntimeStateFile, isPidAlive } from '../utils/stack/runtime_state.mjs';
+import { withStackEnv } from './stack_environment.mjs';
+import { banner, cmd as cmdFmt, sectionTitle } from '../utils/ui/layout.mjs';
+import { cyan, green } from '../utils/ui/ansi.mjs';
+
+export async function runStackDaemonCommand({ rootDir, stackName, argv, json }) {
+  const { flags, kv } = parseArgs(argv);
+  const wantsHelpFlag = wantsHelp(argv, { flags });
+
+  const positionals = argv.filter((a) => a && a !== '--' && !a.startsWith('--'));
+  const action = (positionals[0] ?? 'status').toString().trim();
+  const identity = parseCliIdentityOrThrow((kv.get('--identity') ?? '').trim());
+  const noOpen = flags.has('--no-open') || flags.has('--no-browser') || flags.has('--no-browser-open');
+
+  if (wantsHelpFlag || !action || action === 'help') {
+    printResult({
+      json,
+      data: { ok: true, stackName, commands: ['start', 'stop', 'restart', 'status'], flags: ['--identity=<name>'] },
+      text: [
+        banner('stack daemon', { subtitle: `Manage the happier-cli daemon for stack ${cyan(stackName || 'main')}.` }),
+        '',
+        sectionTitle('usage:'),
+        `  ${cyan('hstack stack daemon')} <name> status [--identity=<name>] [--json]`,
+        `  ${cyan('hstack stack daemon')} <name> start [--identity=<name>] [--json]`,
+        `  ${cyan('hstack stack daemon')} <name> stop [--identity=<name>] [--json]`,
+        `  ${cyan('hstack stack daemon')} <name> restart [--identity=<name>] [--json]`,
+        '',
+        sectionTitle('example:'),
+        `  ${cmdFmt(`hstack stack daemon ${stackName || 'main'} restart`)}`,
+        `  ${cmdFmt(`hstack stack daemon ${stackName || 'main'} start --identity=account-b`)}`,
+      ].join('\n'),
+    });
+    return;
+  }
+
+  if (!['start', 'stop', 'restart', 'status'].includes(action)) {
+    printResult({
+      json,
+      data: { ok: false, error: 'invalid_daemon_subcommand', stackName, action },
+      text: [
+        `[stack] invalid daemon subcommand: ${action}`,
+        '',
+        'usage:',
+        '  hstack stack daemon <name> start|stop|restart|status [--json]',
+      ].join('\n'),
+    });
+    process.exit(1);
+  }
+
+  const res = await withStackEnv({
+    stackName,
+    fn: async ({ env }) => {
+      const cliDir = getComponentDir(rootDir, 'happier-cli', env);
+      const cliBin = join(cliDir, 'bin', 'happier.mjs');
+      const baseCliHomeDir = (env.HAPPIER_STACK_CLI_HOME_DIR ?? join(resolveStackEnvPath(stackName).baseDir, 'cli')).toString();
+      const cliHomeDir = resolveCliHomeDirForIdentity({ cliHomeDir: baseCliHomeDir, identity });
+
+      // Stack env files don't always include a server port; for running stacks, prefer runtime state.
+      // This avoids accidentally targeting the main stack default (3005) for stacks on other ports.
+      let runtimePort = null;
+      const runtimePath = (env.HAPPIER_STACK_RUNTIME_STATE_PATH ?? '').toString().trim();
+      if (runtimePath) {
+        const state = await readStackRuntimeStateFile(runtimePath).catch(() => null);
+        const candidate = Number(state?.ports?.server);
+        const serverPid = Number(state?.processes?.serverPid);
+        if (Number.isFinite(candidate) && candidate > 0 && isPidAlive(serverPid)) {
+          runtimePort = candidate;
+        }
+      }
+
+      const serverPort = runtimePort ?? resolveServerPortFromEnv({ env, defaultPort: 3005 });
+      const urls = await resolveServerUrls({ env, serverPort, allowEnable: false });
+      const internalServerUrl = urls.internalServerUrl;
+      const publicServerUrl = urls.publicServerUrl;
+      const envForIdentity = {
+        ...env,
+        HAPPIER_STACK_CLI_IDENTITY: identity,
+        ...(identity !== 'default'
+          ? {
+              HAPPIER_STACK_MIGRATE_CREDENTIALS: '0',
+              HAPPIER_STACK_AUTO_AUTH_SEED: '0',
+            }
+          : {}),
+      };
+      await mkdir(cliHomeDir, { recursive: true }).catch(() => {});
+
+      if (action === 'start' || action === 'restart') {
+        // UX: if this identity is not authenticated yet and we're in a real TTY, offer to run the
+        // guided login flow inline (instead of failing or asking for a second terminal).
+        //
+        // Important: never prompt in --json mode (automation must not hang).
+        const hasCreds = Boolean(findExistingStackCredentialPath({
+          cliHomeDir,
+          serverUrl: internalServerUrl,
+          env: envForIdentity,
+        }));
+
+        if (!hasCreds) {
+          if (json) {
+            const loginCmd = `hstack stack auth ${stackName} login${identity !== 'default' ? ` --identity=${identity} --no-open` : ''}`;
+            return { ok: false, action, error: 'auth_required', cliIdentity: identity, cliHomeDir, loginCmd };
+          }
+
+          if (isTty()) {
+            const choice = await withRl(async (rl) => {
+              return await promptSelect(rl, {
+                title:
+                  `Daemon identity "${identity}" is not authenticated yet.\n` +
+                  `Authenticate now? (recommended)\n`,
+                options: [
+                  { label: 'yes (run guided login now)', value: 'yes' },
+                  { label: 'no (show command and exit)', value: 'no' },
+                ],
+                defaultIndex: 0,
+              });
+            });
+
+            if (choice === 'yes') {
+              const authArgs = [
+                'login',
+                ...(identity !== 'default' ? [`--identity=${identity}`] : []),
+                ...(identity !== 'default' || noOpen ? ['--no-open'] : []),
+              ];
+              await run(process.execPath, [join(rootDir, 'scripts', 'auth.mjs'), ...authArgs], {
+                cwd: rootDir,
+                env: envForIdentity,
+                stdio: 'inherit',
+              });
+            } else {
+              const loginCmd = `hstack stack auth ${stackName} login${identity !== 'default' ? ` --identity=${identity} --no-open` : ''}`;
+              throw new Error(`[stack] daemon auth required. Run:\n${loginCmd}`);
+            }
+          }
+        }
+
+        await startLocalDaemonWithAuth({
+          cliBin,
+          cliHomeDir,
+          internalServerUrl,
+          publicServerUrl,
+          isShuttingDown: () => false,
+          forceRestart: action === 'restart',
+          env: envForIdentity,
+          stackName,
+          cliIdentity: identity,
+        });
+        const status = await daemonStatusSummary({
+          cliBin,
+          cliHomeDir,
+          internalServerUrl,
+          publicServerUrl,
+          env: envForIdentity,
+          stackName,
+          cliIdentity: identity,
+        });
+        return { ok: true, action, cliIdentity: identity, cliHomeDir, status: status.trim() };
+      }
+
+      if (action === 'stop') {
+        await stopLocalDaemon({
+          cliBin,
+          internalServerUrl,
+          publicServerUrl,
+          cliHomeDir,
+          env: envForIdentity,
+          stackName,
+          cliIdentity: identity,
+        });
+        const status = await daemonStatusSummary({
+          cliBin,
+          cliHomeDir,
+          internalServerUrl,
+          publicServerUrl,
+          env: envForIdentity,
+          stackName,
+          cliIdentity: identity,
+        }).catch(() => '');
+        return { ok: true, action, cliIdentity: identity, cliHomeDir, status: status.trim() || null };
+      }
+
+      const status = await daemonStatusSummary({
+        cliBin,
+        cliHomeDir,
+        internalServerUrl,
+        publicServerUrl,
+        env: envForIdentity,
+        stackName,
+        cliIdentity: identity,
+      });
+      return { ok: true, action, cliIdentity: identity, cliHomeDir, status: status.trim() };
+    },
+  });
+
+  if (json) {
+    printResult({ json, data: { stackName, ...res } });
+    return;
+  }
+
+  if (res?.status) {
+    console.log('');
+    console.log(sectionTitle('Daemon'));
+    console.log(res.status);
+    return;
+  }
+
+  console.log(`${green('✓')} daemon command completed`);
+}

package/scripts/stack/stack_delegated_help.mjs

@@ -0,0 +1,81 @@
+import { join } from 'node:path';
+
+import { run } from '../utils/proc/proc.mjs';
+import { printResult } from '../utils/cli/cli.mjs';
+import { resolveTopLevelNodeScriptFile } from './command_arguments.mjs';
+import { getStackHelpUsageLine } from './help_text.mjs';
+import { withStackEnv } from './stack_environment.mjs';
+import { stackExistsSync } from '../utils/stack/stacks.mjs';
+
+const DELEGATED_STACK_COMMANDS = new Set(['dev', 'start', 'build', 'typecheck', 'lint', 'test', 'review', 'doctor', 'mobile', 'mobile-dev-client']);
+
+function resolveStackOnlyFlags(command) {
+  if (command === 'build' || command === 'typecheck' || command === 'lint' || command === 'test' || command === 'review') {
+    return ['--repo=default|main|active|dev|<owner/...>|<path>', '--repo-dir=<path>'];
+  }
+  if (command === 'dev' || command === 'start') {
+    return ['--background', '--bg'];
+  }
+  return [];
+}
+
+export async function printDelegatedStackHelpIfAvailable({ rootDir, command, stackName, json }) {
+  const normalizedCommand = (command ?? '').toString().trim();
+  if (!normalizedCommand) return false;
+  if (!DELEGATED_STACK_COMMANDS.has(normalizedCommand)) return false;
+
+  const delegatedScript = resolveTopLevelNodeScriptFile(normalizedCommand);
+  if (!delegatedScript) return false;
+
+  const usageLine = getStackHelpUsageLine(normalizedCommand);
+  const stackOnlyFlags = resolveStackOnlyFlags(normalizedCommand);
+
+  if (json) {
+    printResult({
+      json,
+      data: {
+        ok: true,
+        cmd: normalizedCommand,
+        stackName: stackName || null,
+        usage: usageLine,
+        stackFlags: stackOnlyFlags,
+        delegatedHelp: delegatedScript,
+      },
+      text: null,
+    });
+    return true;
+  }
+
+  const headerLines = [
+    `[stack ${normalizedCommand}] usage:`,
+    ...(usageLine ? [`  ${usageLine}`] : []),
+    ...(stackOnlyFlags.length
+      ? [
+          '',
+          'stack-only flags:',
+          ...stackOnlyFlags.map((flag) => `  ${flag}`),
+        ]
+      : []),
+    '',
+    `${normalizedCommand} flags (delegated):`,
+    '',
+  ];
+  process.stdout.write(headerLines.join('\n') + '\n');
+
+  const runDelegatedHelp = async (env) => {
+    await run(process.execPath, [join(rootDir, 'scripts', delegatedScript), '--help'], { cwd: rootDir, env });
+  };
+
+  if (stackName && stackExistsSync(stackName)) {
+    await withStackEnv({
+      stackName,
+      fn: async ({ env }) => {
+        await runDelegatedHelp(env);
+      },
+    });
+    return true;
+  }
+
+  await runDelegatedHelp(process.env);
+  return true;
+}

package/scripts/stack/stack_environment.mjs

@@ -0,0 +1,151 @@
+import { writeFile } from 'node:fs/promises';
+import { ensureDir, readTextOrEmpty } from '../utils/fs/ops.mjs';
+import { parseEnvToObject } from '../utils/env/dotenv.mjs';
+import { getRepoDir, resolveStackEnvPath } from '../utils/paths/paths.mjs';
+import { stackExistsSync } from '../utils/stack/stacks.mjs';
+import { STACK_WRAPPER_PRESERVE_KEYS, scrubHappierStackEnv } from '../utils/env/scrub_env.mjs';
+import { applyStackActiveServerScopeEnv } from '../utils/auth/stable_scope_id.mjs';
+import { getStackRuntimeStatePath, isPidAlive, readStackRuntimeStateFile } from '../utils/stack/runtime_state.mjs';
+
+const readExistingEnv = readTextOrEmpty;
+const STACK_WRAPPER_CLEAR_UNPREFIXED_KEYS = [
+  'HAPPIER_SERVER_URL',
+  'HAPPIER_PUBLIC_SERVER_URL',
+  'HAPPIER_WEBAPP_URL',
+  'HAPPIER_HOME_DIR',
+];
+
+function stringifyEnv(env) {
+  const lines = [];
+  for (const [k, v] of Object.entries(env)) {
+    if (v == null) continue;
+    const s = String(v);
+    if (!s.trim()) continue;
+    // Keep it simple: no quoting/escaping beyond this.
+    lines.push(`${k}=${s}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+export function resolveDefaultRepoEnv({ rootDir }) {
+  // Stacks are pinned to an explicit repo checkout/worktree.
+  //
+  // Default: use the workspace clone (<workspace>/happier), regardless of any current
+  // one-off repo/worktree selection in the user's environment.
+  const repoDir = getRepoDir(rootDir, { ...process.env, HAPPIER_STACK_REPO_DIR: '' });
+  return { HAPPIER_STACK_REPO_DIR: repoDir };
+}
+
+export async function writeStackEnv({ stackName, env }) {
+  const stackDir = resolveStackEnvPath(stackName).baseDir;
+  await ensureDir(stackDir);
+  const envPath = resolveStackEnvPath(stackName).envPath;
+  const next = stringifyEnv(env);
+  const existing = await readExistingEnv(envPath);
+  if (existing !== next) {
+    await writeFile(envPath, next, 'utf-8');
+  }
+  return envPath;
+}
+
+export async function withStackEnv({ stackName, fn, extraEnv = {} }) {
+  const envPath = resolveStackEnvPath(stackName).envPath;
+  if (!stackExistsSync(stackName)) {
+    throw new Error(
+      `[stack] stack "${stackName}" does not exist yet.\n` +
+      `[stack] Create it first:\n` +
+      `  hstack stack new ${stackName}\n` +
+      `  # or:\n` +
+      `  hstack stack new ${stackName} --interactive\n`
+    );
+  }
+  // IMPORTANT: stack env file should be authoritative. If the user has HAPPIER_STACK_*
+  // exported in their shell, it would otherwise "win" because utils/env.mjs only sets
+  // env vars if they are missing/empty.
+  const cleaned = scrubHappierStackEnv(process.env, {
+    keepHappierStackKeys: STACK_WRAPPER_PRESERVE_KEYS,
+    clearUnprefixedKeys: STACK_WRAPPER_CLEAR_UNPREFIXED_KEYS,
+  });
+  const raw = await readExistingEnv(envPath);
+  const stackEnv = parseEnvToObject(raw);
+
+  const runtimeStatePath = getStackRuntimeStatePath(stackName);
+  const runtimeState = await readStackRuntimeStateFile(runtimeStatePath);
+
+  let env = {
+    ...cleaned,
+    HAPPIER_STACK_STACK: stackName,
+    HAPPIER_STACK_ENV_FILE: envPath,
+    // Expose runtime state path so scripts can find it if needed.
+    HAPPIER_STACK_RUNTIME_STATE_PATH: runtimeStatePath,
+    // Stack env is authoritative by default.
+    ...stackEnv,
+    // One-shot overrides (e.g. --repo=...) win over stack env file.
+    ...extraEnv,
+  };
+  env = applyStackActiveServerScopeEnv({
+    env,
+    stackName,
+    cliIdentity: (env.HAPPIER_STACK_CLI_IDENTITY ?? '').toString().trim() || 'default',
+  });
+
+  // Runtime-only port overlay (ephemeral stacks): prefer stack.runtime.json ports when the stack
+  // is still running, even if the original "owner" process is gone (common during dev restarts).
+  const ownerPid = Number(runtimeState?.ownerPid);
+  const processes = runtimeState?.processes && typeof runtimeState.processes === 'object' ? runtimeState.processes : {};
+  const serverPid = Number(processes.serverPid);
+  const expoPid = Number(processes.expoPid);
+  const daemonPid = Number(processes.daemonPid);
+  const shouldTrustRuntimePorts =
+    isPidAlive(ownerPid) ||
+    isPidAlive(serverPid) ||
+    isPidAlive(expoPid) ||
+    isPidAlive(daemonPid);
+
+  if (shouldTrustRuntimePorts) {
+    const ports = runtimeState?.ports && typeof runtimeState.ports === 'object' ? runtimeState.ports : {};
+    const applyPort = (suffix, value) => {
+      const n = Number(value);
+      if (!Number.isFinite(n) || n <= 0) return;
+      env[`HAPPIER_STACK_${suffix}`] = String(n);
+    };
+    applyPort('SERVER_PORT', ports.server);
+    applyPort('SERVER_BACKEND_PORT', ports.backend);
+    applyPort('PG_PORT', ports.pg);
+    applyPort('REDIS_PORT', ports.redis);
+    applyPort('MINIO_PORT', ports.minio);
+    applyPort('MINIO_CONSOLE_PORT', ports.minioConsole);
+
+    // Mark ephemeral mode for downstream helpers (e.g. infra should not persist ports).
+    if (runtimeState?.ephemeral) {
+      env.HAPPIER_STACK_EPHEMERAL_PORTS = '1';
+    }
+  }
+
+  return await fn({ env, envPath, stackEnv, runtimeStatePath, runtimeState });
+}
+
+export function parseServerComponentFromEnv(env) {
+  const v = (env.HAPPIER_STACK_SERVER_COMPONENT ?? '').toString().trim() || 'happier-server-light';
+  return v === 'happier-server' ? 'happier-server' : 'happier-server-light';
+}
+
+export async function readStackEnvObject(stackName) {
+  const envPath = resolveStackEnvPath(stackName).envPath;
+  const raw = await readExistingEnv(envPath);
+  const env = raw ? parseEnvToObject(raw) : {};
+  return { envPath, env };
+}
+
+export async function getRuntimePortExtraEnv(stackName) {
+  const runtimeStatePath = getStackRuntimeStatePath(stackName);
+  const runtimeState = await readStackRuntimeStateFile(runtimeStatePath);
+  const runtimePort = Number(runtimeState?.ports?.server);
+  return Number.isFinite(runtimePort) && runtimePort > 0
+    ? {
+        // Ephemeral stacks (PR stacks) store their chosen ports in stack.runtime.json, not the env file.
+        // Ensure stack-scoped commands that compute URLs don't fall back to 3005 (main default).
+        HAPPIER_STACK_SERVER_PORT: String(runtimePort),
+      }
+    : null;
+}

package/scripts/stack/stack_environment.sanitization.test.mjs

@@ -0,0 +1,75 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { withStackEnv } from './stack_environment.mjs';
+
+async function withTempStackEnvFixture(fn) {
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-stack-env-sanitize-'));
+  const storageDir = join(tmp, 'storage');
+  const stackName = 'sanitize';
+  const stackDir = join(storageDir, stackName);
+
+  await mkdir(stackDir, { recursive: true });
+  await writeFile(
+    join(stackDir, 'env'),
+    [
+      'HAPPIER_STACK_REPO_DIR=/tmp/happier',
+      `HAPPIER_STACK_CLI_HOME_DIR=${join(storageDir, stackName, 'cli')}`,
+      'HAPPIER_STACK_SERVER_PORT=3555',
+      '',
+    ].join('\n'),
+    'utf-8',
+  );
+
+  const previousStorageDir = process.env.HAPPIER_STACK_STORAGE_DIR;
+  process.env.HAPPIER_STACK_STORAGE_DIR = storageDir;
+
+  try {
+    await fn({ stackName, storageDir });
+  } finally {
+    if (typeof previousStorageDir === 'undefined') {
+      delete process.env.HAPPIER_STACK_STORAGE_DIR;
+    } else {
+      process.env.HAPPIER_STACK_STORAGE_DIR = previousStorageDir;
+    }
+    await rm(tmp, { recursive: true, force: true });
+  }
+}
+
+test('withStackEnv clears leaked unprefixed server/home env vars from caller scope', async () => {
+  await withTempStackEnvFixture(async ({ stackName }) => {
+    const previousServerUrl = process.env.HAPPIER_SERVER_URL;
+    const previousPublicServerUrl = process.env.HAPPIER_PUBLIC_SERVER_URL;
+    const previousWebappUrl = process.env.HAPPIER_WEBAPP_URL;
+    const previousHomeDir = process.env.HAPPIER_HOME_DIR;
+
+    process.env.HAPPIER_SERVER_URL = 'http://stale.localhost:9999';
+    process.env.HAPPIER_PUBLIC_SERVER_URL = 'http://stale.localhost:9999';
+    process.env.HAPPIER_WEBAPP_URL = 'http://stale.localhost:9999';
+    process.env.HAPPIER_HOME_DIR = '/tmp/stale-home';
+
+    try {
+      await withStackEnv({
+        stackName,
+        fn: async ({ env }) => {
+          assert.equal(env.HAPPIER_SERVER_URL, undefined);
+          assert.equal(env.HAPPIER_PUBLIC_SERVER_URL, undefined);
+          assert.equal(env.HAPPIER_WEBAPP_URL, undefined);
+          assert.equal(env.HAPPIER_HOME_DIR, undefined);
+        },
+      });
+    } finally {
+      if (typeof previousServerUrl === 'undefined') delete process.env.HAPPIER_SERVER_URL;
+      else process.env.HAPPIER_SERVER_URL = previousServerUrl;
+      if (typeof previousPublicServerUrl === 'undefined') delete process.env.HAPPIER_PUBLIC_SERVER_URL;
+      else process.env.HAPPIER_PUBLIC_SERVER_URL = previousPublicServerUrl;
+      if (typeof previousWebappUrl === 'undefined') delete process.env.HAPPIER_WEBAPP_URL;
+      else process.env.HAPPIER_WEBAPP_URL = previousWebappUrl;
+      if (typeof previousHomeDir === 'undefined') delete process.env.HAPPIER_HOME_DIR;
+      else process.env.HAPPIER_HOME_DIR = previousHomeDir;
+    }
+  });
+});

package/scripts/stack/stack_happier_passthrough_command.mjs

@@ -0,0 +1,63 @@
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+
+import { parseArgs } from '../utils/cli/args.mjs';
+import { applyStackActiveServerScopeEnv } from '../utils/auth/stable_scope_id.mjs';
+import { resolveStackEnvPath } from '../utils/paths/paths.mjs';
+import { parseCliIdentityOrThrow, resolveCliHomeDirForIdentity } from '../utils/stack/cli_identities.mjs';
+
+import { withStackEnv } from './stack_environment.mjs';
+
+export async function runStackHappierPassthroughCommand({ rootDir, stackName, passthrough }) {
+  const sepIdx = passthrough.indexOf('--');
+  const wrapperArgs = sepIdx === -1 ? passthrough : passthrough.slice(0, sepIdx);
+  const forwardedArgsRaw = sepIdx === -1 ? passthrough : passthrough.slice(sepIdx + 1);
+
+  const { kv } = parseArgs(wrapperArgs);
+  const identityRaw = (kv.get('--identity') ?? '').toString().trim();
+  const identity = identityRaw ? parseCliIdentityOrThrow(identityRaw) : null;
+
+  const forwardedArgs =
+    sepIdx === -1
+      ? forwardedArgsRaw.filter((arg) => !(identity && typeof arg === 'string' && arg.trim().startsWith('--identity=')))
+      : forwardedArgsRaw;
+
+  await withStackEnv({
+    stackName,
+    fn: async ({ env }) => {
+      const baseCliHomeDir = (env.HAPPIER_STACK_CLI_HOME_DIR ?? join(resolveStackEnvPath(stackName).baseDir, 'cli')).toString();
+      const cliHomeDirForIdentity = identity
+        ? resolveCliHomeDirForIdentity({ cliHomeDir: baseCliHomeDir, identity })
+        : baseCliHomeDir;
+
+      let envForHappy = identity
+        ? {
+            ...env,
+            HAPPIER_STACK_CLI_IDENTITY: identity,
+            HAPPIER_HOME_DIR: cliHomeDirForIdentity,
+            HAPPIER_STACK_CLI_HOME_DIR: cliHomeDirForIdentity,
+          }
+        : env;
+
+      envForHappy = applyStackActiveServerScopeEnv({
+        env: envForHappy,
+        stackName,
+        cliIdentity: identity || (envForHappy.HAPPIER_STACK_CLI_IDENTITY ?? '').toString().trim() || 'default',
+      });
+
+      const child = spawn(process.execPath, [join(rootDir, 'scripts', 'happier.mjs'), ...forwardedArgs], {
+        cwd: rootDir,
+        env: envForHappy,
+        stdio: 'inherit',
+        shell: false,
+      });
+
+      const exitCode = await new Promise((resolvePromise) => {
+        child.on('error', () => resolvePromise(1));
+        child.on('exit', (code) => resolvePromise(code ?? 1));
+      });
+
+      process.exit(exitCode);
+    },
+  });
+}