@happier-dev/stack 0.1.0 → 0.2.0

package/scripts/setup_from_source_stable_branch_flag.test.mjs

@@ -0,0 +1,129 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runNodeCapture as runNode } from './testkit/stack_script_command_testkit.mjs';
+
+function resolveStackRootDir() {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  return dirname(scriptsDir);
+}
+
+async function writeJson(path, obj) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(obj, null, 2) + '\n', 'utf-8');
+}
+
+async function createLocalRepoFixture() {
+  const rootDir = resolveStackRootDir();
+  const baseDir = await mkdtemp(join(tmpdir(), 'hstack-stable-branch-'));
+  const sandboxDir = join(baseDir, 'sandbox');
+  const fakeRepoDir = join(baseDir, 'fake-repo');
+
+  await mkdir(sandboxDir, { recursive: true });
+  await mkdir(fakeRepoDir, { recursive: true });
+
+  // Minimal monorepo markers for isHappyMonorepoRoot().
+  await writeJson(join(fakeRepoDir, 'apps', 'ui', 'package.json'), { name: 'ui', private: true });
+  await writeJson(join(fakeRepoDir, 'apps', 'cli', 'package.json'), { name: 'cli', private: true });
+  await writeJson(join(fakeRepoDir, 'apps', 'server', 'package.json'), { name: 'server', private: true });
+
+  return { rootDir, baseDir, sandboxDir, fakeRepoDir };
+}
+
+test('hstack setup-from-source --stable-branch persists HAPPIER_STACK_STABLE_BRANCH', async () => {
+  const { rootDir, baseDir, sandboxDir, fakeRepoDir } = await createLocalRepoFixture();
+
+  // Pre-create the "local" stack so local-repo profile can reuse it without running stack creation.
+  const localStackEnvPath = join(sandboxDir, 'storage', 'local', 'env');
+  await mkdir(dirname(localStackEnvPath), { recursive: true });
+  await writeFile(localStackEnvPath, `HAPPIER_STACK_REPO_DIR=${fakeRepoDir}\n`, 'utf-8');
+
+  try {
+    const res = await runNode(
+      [
+        join(rootDir, 'bin', 'hstack.mjs'),
+        `--sandbox-dir=${sandboxDir}`,
+        'setup-from-source',
+        '--profile=local-repo',
+        `--repo-dir=${fakeRepoDir}`,
+        '--stable-branch=preview',
+        '--server=happier-server-light',
+        '--non-interactive',
+        '--no-auth',
+        '--no-tailscale',
+        '--no-autostart',
+        '--no-menubar',
+        '--no-start-now',
+      ],
+      { cwd: rootDir, env: { ...process.env, HAPPIER_STACK_TEST_TTY: '0' } }
+    );
+    assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+    const mainEnvPath = join(sandboxDir, 'storage', 'main', 'env');
+    const mainEnv = await readFile(mainEnvPath, 'utf-8');
+    assert.match(mainEnv, /^HAPPIER_STACK_STABLE_BRANCH=preview$/m);
+  } finally {
+    await rm(baseDir, { recursive: true, force: true });
+  }
+});
+
+test('hstack setup-from-source --stable-branch rejects whitespace', async () => {
+  const { rootDir, baseDir, sandboxDir, fakeRepoDir } = await createLocalRepoFixture();
+  try {
+    const res = await runNode(
+      [
+        join(rootDir, 'bin', 'hstack.mjs'),
+        `--sandbox-dir=${sandboxDir}`,
+        'setup-from-source',
+        '--profile=local-repo',
+        `--repo-dir=${fakeRepoDir}`,
+        '--stable-branch=bad branch',
+        '--server=happier-server-light',
+        '--non-interactive',
+        '--no-auth',
+        '--no-tailscale',
+        '--no-autostart',
+        '--no-menubar',
+        '--no-start-now',
+      ],
+      { cwd: rootDir, env: { ...process.env, HAPPIER_STACK_TEST_TTY: '0' } }
+    );
+    assert.notEqual(res.code, 0, `expected non-zero exit\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+    assert.match(res.stderr, /--stable-branch must not contain whitespace/);
+  } finally {
+    await rm(baseDir, { recursive: true, force: true });
+  }
+});
+
+test('hstack setup-from-source rejects conflicting --stable-branch and --branch', async () => {
+  const { rootDir, baseDir, sandboxDir, fakeRepoDir } = await createLocalRepoFixture();
+  try {
+    const res = await runNode(
+      [
+        join(rootDir, 'bin', 'hstack.mjs'),
+        `--sandbox-dir=${sandboxDir}`,
+        'setup-from-source',
+        '--profile=local-repo',
+        `--repo-dir=${fakeRepoDir}`,
+        '--stable-branch=preview',
+        '--branch=main',
+        '--server=happier-server-light',
+        '--non-interactive',
+        '--no-auth',
+        '--no-tailscale',
+        '--no-autostart',
+        '--no-menubar',
+        '--no-start-now',
+      ],
+      { cwd: rootDir, env: { ...process.env, HAPPIER_STACK_TEST_TTY: '0' } }
+    );
+    assert.notEqual(res.code, 0, `expected non-zero exit\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+    assert.match(res.stderr, /conflicting stable branch args/);
+  } finally {
+    await rm(baseDir, { recursive: true, force: true });
+  }
+});

package/scripts/setup_local_repo_profile.test.mjs

@@ -2,47 +2,15 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { basename, dirname, join } from 'node:path';
 import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
-import { spawn } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { fileURLToPath, pathToFileURL } 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,
-      });
-    });
-  });
-}
+import { ensureMinimalMonorepoLayout } from './testkit/core/minimal_monorepo_layout.mjs';
+import { runNodeCapture as runNode } from './testkit/core/run_node_capture.mjs';
 
 function toDataUrl(source) {
   return `data:text/javascript,${encodeURIComponent(source)}`;
 }
 
-async function writeHappyMonorepoStub({ repoDir }) {
-  await mkdir(join(repoDir, 'apps', 'ui'), { recursive: true });
-  await mkdir(join(repoDir, 'apps', 'cli'), { recursive: true });
-  await mkdir(join(repoDir, 'apps', 'server'), { recursive: true });
-  await writeFile(join(repoDir, 'apps', 'ui', 'package.json'), '{}\n', 'utf-8');
-  await writeFile(join(repoDir, 'apps', 'cli', 'package.json'), '{}\n', 'utf-8');
-  await writeFile(join(repoDir, 'apps', 'server', 'package.json'), '{}\n', 'utf-8');
-}
-
 test('hstack setup --profile=local-repo creates a dedicated stack without bootstrapping/cloning', async () => {
   const scriptsDir = dirname(fileURLToPath(import.meta.url));
   const rootDir = dirname(scriptsDir);
@@ -53,7 +21,7 @@ test('hstack setup --profile=local-repo creates a dedicated stack without bootst
   const registerPath = join(tmp, 'register.mjs');
 
   const repoDir = join(tmp, 'repo');
-  await writeHappyMonorepoStub({ repoDir });
+  await ensureMinimalMonorepoLayout(repoDir);
 
   const stubBySpecifier = {
     './utils/proc/proc.mjs': toDataUrl(`
@@ -175,4 +143,3 @@ export async function resolve(specifier, context, defaultResolve) {
     await rm(tmp, { recursive: true, force: true });
   }
 });
-

package/scripts/setup_pr.mjs

@@ -29,26 +29,28 @@ import { inferPrStackBaseName } from './utils/stack/pr_stack_name.mjs';
 import { bold, cyan, dim, green } from './utils/ui/ansi.mjs';
 
 function pickReviewerMobileSchemeEnv(env) {
-  // For review-pr flows, reviewers typically have the standard Happier dev build on their phone,
-  // so default to the canonical `happier://` scheme unless the user explicitly configured one.
+  // For review-pr flows, the mobile "dev-client" deep link must target a dev-client app install,
+  // not the production Happier app. Default to the dev-client scheme (see docs/mobile-ios.md).
   // If the user explicitly set a review-specific override, honor it.
   const reviewOverride = (env.HAPPIER_STACK_REVIEW_MOBILE_SCHEME ?? '').toString().trim();
   if (reviewOverride) {
     return { ...env, HAPPIER_STACK_MOBILE_SCHEME: reviewOverride };
   }
 
-  // In sandbox review flows, keep things predictable and avoid relying on any global per-machine overrides.
-  if (isSandboxed()) {
-    return { ...env, HAPPIER_STACK_MOBILE_SCHEME: 'happier' };
+  // If the user already configured a scheme, keep it.
+  const explicitMobile = (env.HAPPIER_STACK_MOBILE_SCHEME ?? '').toString().trim();
+  if (explicitMobile) return env;
+
+  const devClientScheme = (env.HAPPIER_STACK_DEV_CLIENT_SCHEME ?? '').toString().trim();
+  if (devClientScheme && !isSandboxed()) {
+    return { ...env, HAPPIER_STACK_MOBILE_SCHEME: devClientScheme };
   }
 
-  // Non-sandbox: keep existing behavior unless nothing is configured at all.
-  const explicit =
-    (env.HAPPIER_STACK_MOBILE_SCHEME ?? env.HAPPIER_STACK_DEV_CLIENT_SCHEME ?? '')
-      .toString()
-      .trim();
-  if (explicit) return env;
-  return { ...env, HAPPIER_STACK_MOBILE_SCHEME: 'happier' };
+  // Default to the dev-client scheme.
+  // Note: in sandbox mode, prefer a deterministic default and avoid reading host-machine config by default.
+  // If the user wants a specific scheme in sandbox mode, set HAPPIER_STACK_DEV_CLIENT_SCHEME or HAPPIER_STACK_REVIEW_MOBILE_SCHEME.
+  const fallback = isSandboxed() ? 'hstack-dev' : devClientScheme || 'hstack-dev';
+  return { ...env, HAPPIER_STACK_MOBILE_SCHEME: fallback };
 }
 
 async function printReviewerStackSummary({ rootDir, stackName, env, wantsMobile }) {
@@ -276,13 +278,22 @@ async function main() {
   // Determine server flavor for bootstrap and stack creation.
   const serverFlavorFromArg = (kv.get('--server-flavor') ?? '').trim().toLowerCase();
   const serverFromArg = (kv.get('--server') ?? '').trim();
+  const normalizedServerFromArg =
+    serverFromArg === 'happy-server'
+      ? 'happier-server'
+      : serverFromArg === 'happy-server-light'
+        ? 'happier-server-light'
+        : serverFromArg;
   const serverComponent =
     serverFlavorFromArg === 'full'
-      ? 'happy-server'
+      ? 'happier-server'
       : serverFlavorFromArg === 'light'
-        ? 'happy-server-light'
-        : serverFromArg || 'happy-server-light';
-  const bootstrapServer = serverComponent === 'happy-server' ? 'both' : 'happy-server-light';
+        ? 'happier-server-light'
+        : normalizedServerFromArg || 'happier-server-light';
+  if (serverComponent !== 'happier-server' && serverComponent !== 'happier-server-light') {
+    throw new Error(`[setup-pr] invalid --server: ${serverFromArg || serverComponent}`);
+  }
+  const bootstrapServer = serverComponent === 'happier-server' ? 'both' : 'happier-server-light';
 
   // Auth defaults (avoid prompts; setup-pr should be low-friction).
   // Note: these may be updated below (sandbox prompt), so keep them mutable.

package/scripts/setup_pr.mobile_scheme.test.mjs

@@ -0,0 +1,332 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+function runNode(args, { cwd, env }) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    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', rejectPromise);
+    proc.on('exit', (code, signal) => resolvePromise({ code: code ?? (signal ? 1 : 0), signal, stdout, stderr }));
+  });
+}
+
+function toDataUrl(source) {
+  return `data:text/javascript,${encodeURIComponent(source)}`;
+}
+
+async function readMarker(markerPath) {
+  const raw = await readFile(markerPath, 'utf-8');
+  return raw
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
+}
+
+test('setup-pr mobile in sandbox defaults to dev-client scheme (not happier://)', async (t) => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const rootDir = dirname(scriptsDir);
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-setup-pr-mobile-scheme-'));
+  t.after(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  const markerPath = join(tmp, 'markers.log');
+  const loaderPath = join(tmp, 'loader.mjs');
+  const registerPath = join(tmp, 'register-loader.mjs');
+  await writeFile(markerPath, '', 'utf-8');
+
+  const stubBySpecifier = {
+    './utils/cli/prereqs.mjs': toDataUrl(`
+export async function assertCliPrereqs() {}
+`),
+    './utils/auth/guided_pr_auth.mjs': toDataUrl(`
+export async function decidePrAuthPlan() {
+  return { mode: 'existing' };
+}
+`),
+    './utils/proc/proc.mjs': toDataUrl(`
+import { appendFileSync } from 'node:fs';
+const markerPath = process.env.HSTACK_SETUP_PR_MARKER;
+function mark(line) {
+  if (!markerPath) return;
+  appendFileSync(markerPath, String(line) + '\\n', 'utf-8');
+}
+export async function run(_cmd, args, { env } = {}) {
+  const script = String(args?.[0] ?? '').split(/[\\\\/]/).pop();
+  if (script === 'stack.mjs') {
+    mark('stack.mobileScheme=' + String(env?.HAPPIER_STACK_MOBILE_SCHEME ?? ''));
+    mark('stack.devClientScheme=' + String(env?.HAPPIER_STACK_DEV_CLIENT_SCHEME ?? ''));
+    mark('stack.reviewOverride=' + String(env?.HAPPIER_STACK_REVIEW_MOBILE_SCHEME ?? ''));
+    mark('stack.sandbox=' + String(env?.HAPPIER_STACK_SANDBOX_DIR ?? ''));
+  }
+  return { status: 0 };
+}
+export async function runCapture() {
+  return '';
+}
+export async function runCaptureResult() {
+  return { ok: true, status: 0, exitCode: 0, signal: null, out: '', err: '', durationMs: 0 };
+}
+export function spawnProc() {
+  return { pid: 123, stdout: null, stderr: null, on() {}, kill() {} };
+}
+export function killProcessTree() {}
+`),
+  };
+
+  const loaderSource = `
+const stubBySpecifier = ${JSON.stringify(stubBySpecifier)};
+export async function resolve(specifier, context, defaultResolve) {
+  const stub = stubBySpecifier[specifier];
+  if (stub) return { url: stub, shortCircuit: true };
+  return defaultResolve(specifier, context, defaultResolve);
+}
+`;
+  await writeFile(loaderPath, loaderSource, 'utf-8');
+  await writeFile(
+    registerPath,
+    [
+      `import { register } from 'node:module';`,
+      `register(${JSON.stringify(pathToFileURL(loaderPath).href)}, import.meta.url);`,
+      '',
+    ].join('\n'),
+    'utf-8'
+  );
+
+  const env = {
+    ...process.env,
+    HSTACK_SETUP_PR_MARKER: markerPath,
+    HAPPIER_STACK_SANDBOX_DIR: join(tmp, 'sandbox'),
+    HAPPIER_STACK_HOME_DIR: join(tmp, 'home'),
+    HAPPIER_STACK_STORAGE_DIR: join(tmp, 'storage'),
+    HAPPIER_STACK_WORKSPACE_DIR: join(tmp, 'workspace'),
+  };
+
+  const res = await runNode(
+    [
+      '--import',
+      registerPath,
+      join(rootDir, 'scripts', 'setup_pr.mjs'),
+      '--repo=123',
+      '--name=pr123',
+      '--dev',
+      '--no-seed-auth',
+      '--mobile',
+      '--json',
+    ],
+    { cwd: rootDir, env }
+  );
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const lines = await readMarker(markerPath);
+  const mobileScheme = lines.find((l) => l.startsWith('stack.mobileScheme=')) ?? '';
+  assert.equal(mobileScheme, 'stack.mobileScheme=hstack-dev');
+});
+
+test('setup-pr ignores HAPPIER_STACK_DEV_CLIENT_SCHEME in sandbox without review override', async (t) => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const rootDir = dirname(scriptsDir);
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-setup-pr-mobile-scheme-explicit-'));
+  t.after(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  const markerPath = join(tmp, 'markers.log');
+  const loaderPath = join(tmp, 'loader.mjs');
+  const registerPath = join(tmp, 'register-loader.mjs');
+  await writeFile(markerPath, '', 'utf-8');
+
+  const stubBySpecifier = {
+    './utils/cli/prereqs.mjs': toDataUrl(`
+export async function assertCliPrereqs() {}
+`),
+    './utils/auth/guided_pr_auth.mjs': toDataUrl(`
+export async function decidePrAuthPlan() {
+  return { mode: 'existing' };
+}
+`),
+    './utils/proc/proc.mjs': toDataUrl(`
+import { appendFileSync } from 'node:fs';
+const markerPath = process.env.HSTACK_SETUP_PR_MARKER;
+function mark(line) {
+  if (!markerPath) return;
+  appendFileSync(markerPath, String(line) + '\\n', 'utf-8');
+}
+export async function run(_cmd, args, { env } = {}) {
+  const script = String(args?.[0] ?? '').split(/[\\\\/]/).pop();
+  if (script === 'stack.mjs') {
+    mark('stack.mobileScheme=' + String(env?.HAPPIER_STACK_MOBILE_SCHEME ?? ''));
+    mark('stack.devClientScheme=' + String(env?.HAPPIER_STACK_DEV_CLIENT_SCHEME ?? ''));
+  }
+  return { status: 0 };
+}
+export async function runCapture() {
+  return '';
+}
+export async function runCaptureResult() {
+  return { ok: true, status: 0, exitCode: 0, signal: null, out: '', err: '', durationMs: 0 };
+}
+export function spawnProc() {
+  return { pid: 123, stdout: null, stderr: null, on() {}, kill() {} };
+}
+export function killProcessTree() {}
+`),
+  };
+
+  const loaderSource = `
+const stubBySpecifier = ${JSON.stringify(stubBySpecifier)};
+export async function resolve(specifier, context, defaultResolve) {
+  const stub = stubBySpecifier[specifier];
+  if (stub) return { url: stub, shortCircuit: true };
+  return defaultResolve(specifier, context, defaultResolve);
+}
+`;
+  await writeFile(loaderPath, loaderSource, 'utf-8');
+  await writeFile(
+    registerPath,
+    [
+      `import { register } from 'node:module';`,
+      `register(${JSON.stringify(pathToFileURL(loaderPath).href)}, import.meta.url);`,
+      '',
+    ].join('\n'),
+    'utf-8'
+  );
+
+  const env = {
+    ...process.env,
+    HSTACK_SETUP_PR_MARKER: markerPath,
+    HAPPIER_STACK_SANDBOX_DIR: join(tmp, 'sandbox'),
+    HAPPIER_STACK_HOME_DIR: join(tmp, 'home'),
+    HAPPIER_STACK_STORAGE_DIR: join(tmp, 'storage'),
+    HAPPIER_STACK_WORKSPACE_DIR: join(tmp, 'workspace'),
+    HAPPIER_STACK_DEV_CLIENT_SCHEME: 'happier-dev',
+  };
+
+  const res = await runNode(
+    [
+      '--import',
+      registerPath,
+      join(rootDir, 'scripts', 'setup_pr.mjs'),
+      '--repo=123',
+      '--name=pr123',
+      '--dev',
+      '--no-seed-auth',
+      '--mobile',
+      '--json',
+    ],
+    { cwd: rootDir, env }
+  );
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const lines = await readMarker(markerPath);
+  const mobileScheme = lines.find((l) => l.startsWith('stack.mobileScheme=')) ?? '';
+  assert.equal(mobileScheme, 'stack.mobileScheme=hstack-dev');
+});
+
+test('setup-pr honors HAPPIER_STACK_REVIEW_MOBILE_SCHEME in sandbox', async (t) => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const rootDir = dirname(scriptsDir);
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-setup-pr-mobile-scheme-review-'));
+  t.after(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  const markerPath = join(tmp, 'markers.log');
+  const loaderPath = join(tmp, 'loader.mjs');
+  const registerPath = join(tmp, 'register-loader.mjs');
+  await writeFile(markerPath, '', 'utf-8');
+
+  const stubBySpecifier = {
+    './utils/cli/prereqs.mjs': toDataUrl(`
+export async function assertCliPrereqs() {}
+`),
+    './utils/auth/guided_pr_auth.mjs': toDataUrl(`
+export async function decidePrAuthPlan() {
+  return { mode: 'existing' };
+}
+`),
+    './utils/proc/proc.mjs': toDataUrl(`
+import { appendFileSync } from 'node:fs';
+const markerPath = process.env.HSTACK_SETUP_PR_MARKER;
+function mark(line) {
+  if (!markerPath) return;
+  appendFileSync(markerPath, String(line) + '\\n', 'utf-8');
+}
+export async function run(_cmd, args, { env } = {}) {
+  const script = String(args?.[0] ?? '').split(/[\\\\/]/).pop();
+  if (script === 'stack.mjs') {
+    mark('stack.mobileScheme=' + String(env?.HAPPIER_STACK_MOBILE_SCHEME ?? ''));
+    mark('stack.reviewOverride=' + String(env?.HAPPIER_STACK_REVIEW_MOBILE_SCHEME ?? ''));
+  }
+  return { status: 0 };
+}
+export async function runCapture() {
+  return '';
+}
+export async function runCaptureResult() {
+  return { ok: true, status: 0, exitCode: 0, signal: null, out: '', err: '', durationMs: 0 };
+}
+export function spawnProc() {
+  return { pid: 123, stdout: null, stderr: null, on() {}, kill() {} };
+}
+export function killProcessTree() {}
+`),
+  };
+
+  const loaderSource = `
+const stubBySpecifier = ${JSON.stringify(stubBySpecifier)};
+export async function resolve(specifier, context, defaultResolve) {
+  const stub = stubBySpecifier[specifier];
+  if (stub) return { url: stub, shortCircuit: true };
+  return defaultResolve(specifier, context, defaultResolve);
+}
+`;
+  await writeFile(loaderPath, loaderSource, 'utf-8');
+  await writeFile(
+    registerPath,
+    [
+      `import { register } from 'node:module';`,
+      `register(${JSON.stringify(pathToFileURL(loaderPath).href)}, import.meta.url);`,
+      '',
+    ].join('\n'),
+    'utf-8'
+  );
+
+  const env = {
+    ...process.env,
+    HSTACK_SETUP_PR_MARKER: markerPath,
+    HAPPIER_STACK_SANDBOX_DIR: join(tmp, 'sandbox'),
+    HAPPIER_STACK_HOME_DIR: join(tmp, 'home'),
+    HAPPIER_STACK_STORAGE_DIR: join(tmp, 'storage'),
+    HAPPIER_STACK_WORKSPACE_DIR: join(tmp, 'workspace'),
+    HAPPIER_STACK_REVIEW_MOBILE_SCHEME: 'hstack-dev',
+  };
+
+  const res = await runNode(
+    [
+      '--import',
+      registerPath,
+      join(rootDir, 'scripts', 'setup_pr.mjs'),
+      '--repo=123',
+      '--name=pr123',
+      '--dev',
+      '--no-seed-auth',
+      '--mobile',
+      '--json',
+    ],
+    { cwd: rootDir, env }
+  );
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const lines = await readMarker(markerPath);
+  const mobileScheme = lines.find((l) => l.startsWith('stack.mobileScheme=')) ?? '';
+  assert.equal(mobileScheme, 'stack.mobileScheme=hstack-dev');
+});

package/scripts/setup_pr_orchestrated_auth_flow_util_import.test.mjs

@@ -47,6 +47,7 @@ function mark(line) {
 export async function run(_cmd, args, { env } = {}) {
   const script = String(args?.[0] ?? '').split(/[\\/]/).pop();
   mark('run:' + script + '|setupChild=' + String(env?.HAPPIER_STACK_SETUP_CHILD ?? '') + '|workspace=' + String(env?.HAPPIER_STACK_WORKSPACE_DIR ?? ''));
+  mark('runArgs:' + script + '|' + JSON.stringify((args ?? []).slice(1)));
   return { status: 0 };
 }
 `),
@@ -133,6 +134,13 @@ export async function resolve(specifier, context, defaultResolve) {
       /run:stack\.mjs\|setupChild=1\|workspace=/,
       `expected setup pr to propagate setup child env to initial stack creation\n${markerLog}`
     );
+
+    // Default server selection should match stack.mjs accepted values.
+    assert.match(
+      markerLog,
+      /runArgs:stack\.mjs\|\[\"pr\",\"pr123\",.*\"--server=happier-server-light\"/,
+      `expected setup pr to default to --server=happier-server-light\n${markerLog}`
+    );
   } finally {
     await rm(tmp, { recursive: true, force: true });
   }

package/scripts/stack/delegated_script_commands.mjs

@@ -3,11 +3,20 @@ import { run } from '../utils/proc/proc.mjs';
 import { listAllStackNames } from '../utils/stack/stacks.mjs';
 import { getRuntimePortExtraEnv, withStackEnv } from './stack_environment.mjs';
 
-export async function cmdService({ rootDir, stackName, svcCmd }) {
+export async function cmdService({ rootDir, stackName, svcCmd, args = [] }) {
   await withStackEnv({
     stackName,
     fn: async ({ env }) => {
-      await run(process.execPath, [join(rootDir, 'scripts', 'service.mjs'), svcCmd], { cwd: rootDir, env });
+      await run(process.execPath, [join(rootDir, 'scripts', 'service.mjs'), svcCmd, ...args], { cwd: rootDir, env });
+    },
+  });
+}
+
+export async function cmdRuntime({ rootDir, stackName, args = [] }) {
+  await withStackEnv({
+    stackName,
+    fn: async ({ env }) => {
+      await run(process.execPath, [join(rootDir, 'scripts', 'runtime_activate.mjs'), ...args], { cwd: rootDir, env });
     },
   });
 }

package/scripts/stack/help_text.mjs

@@ -16,13 +16,14 @@ const STACK_HELP_USAGE_LINES = [
   'hstack stack dev <name> [-- ...]',
   'hstack stack start <name> [-- ...]',
   'hstack stack build <name> [-- ...]',
+  'hstack stack runtime <name> activate [--web|--server|--daemon|--all] [--json]',
   'hstack stack review <name> [component...] [--reviewers=coderabbit,codex] [--base-remote=<remote>] [--base-branch=<branch>] [--base-ref=<ref>] [--chunks|--no-chunks] [--chunking=auto|head-slice|commit-window] [--chunk-max-files=N] [--json]',
   'hstack stack typecheck <name> [component...] [--json]',
   'hstack stack lint <name> [component...] [--json]',
   'hstack stack test <name> [component...] [--json]',
   'hstack stack doctor <name> [-- ...]',
   'hstack stack mobile <name> [-- ...]',
-  'hstack stack mobile:install <name> [--name="Happier (exp1)"] [--device=...] [--json]',
+  'hstack stack mobile:install <name> [--name="Happier (exp1)"] [--device=...] [--app-env=production|development] [--configuration=Debug|Release] [--json]',
   'hstack stack mobile-dev-client <name> --install [--device=...] [--clean] [--configuration=Debug|Release] [--json]',
   'hstack stack resume <name> <sessionId...> [--json]',
   'hstack stack stop <name> [--aggressive] [--sweep-owned] [--no-docker] [--json]',
@@ -32,7 +33,7 @@ const STACK_HELP_USAGE_LINES = [
   'hstack stack srv <name> -- status|use ...',
   'hstack stack wt <name> -- <wt args...>',
   'hstack stack tailscale:status|enable|disable|url <name> [-- ...]',
-  'hstack stack service <name> <install|uninstall|status|start|stop|restart|enable|disable|logs|tail>',
+  'hstack stack service <name> <install|uninstall|status|start|stop|restart|enable|disable|logs|tail> [-- ...]',
   'hstack stack service:* <name>   # legacy alias',
 ];
 
@@ -55,6 +56,7 @@ export const STACK_HELP_COMMANDS = [
   'dev',
   'start',
   'build',
+  'runtime',
   'review',
   'typecheck',
   'lint',