@happier-dev/stack 0.2.1-preview.1775586714.26562 → 0.2.12-preview.1

package/scripts/utils/auth/daemon_gate.test.mjs

@@ -68,12 +68,13 @@ test('daemonStartGate allows daemon start when credentials exist', async (t) =>
 test('daemonStartGate resolves server-scoped credentials from env server url', async (t) => {
   const dir = await withTempRoot(t);
   const serverUrl = 'http://127.0.0.1:4010';
-  const paths = resolveStackCredentialPaths({ cliHomeDir: dir, serverUrl });
+  const env = { HAPPIER_SERVER_URL: serverUrl };
+  const paths = resolveStackCredentialPaths({ cliHomeDir: dir, serverUrl, env });
   await mkdir(join(dir, 'servers', paths.activeServerId), { recursive: true });
   await writeFile(paths.serverScopedPath, 'dummy', 'utf-8');
 
   const gate = daemonStartGate({
-    env: { HAPPIER_SERVER_URL: serverUrl },
+    env,
     cliHomeDir: dir,
   });
   assert.equal(gate.ok, true);

package/scripts/utils/auth/ensure_active_access_key_valid.mjs

@@ -1,9 +1,12 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { chmod, copyFile, mkdir } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { resolveStackCredentialPaths } from './credentials_paths.mjs';
 import { decodeJwtPayloadUnsafe } from './decode_jwt_payload_unsafe.mjs';
 
+const validationCache = new Map();
+
 function readAuthTokenFromCredentialPath(path) {
   const p = String(path ?? '').trim();
   if (!p || !existsSync(p)) return null;
@@ -24,6 +27,26 @@ function readAuthTokenFromCredentialPath(path) {
   }
 }
 
+function buildCredentialValidationCacheKey({ path, token, serverUrl }) {
+  const p = String(path ?? '').trim();
+  const t = String(token ?? '').trim();
+  const base = String(serverUrl ?? '').trim().replace(/\/+$/, '');
+  if (!p || !t || !base) return null;
+  try {
+    const stat = statSync(p);
+    const tokenHash = createHash('sha256').update(t).digest('hex');
+    return [
+      base,
+      p,
+      stat.size,
+      Number.isFinite(stat.mtimeMs) ? stat.mtimeMs : 0,
+      tokenHash,
+    ].join('\0');
+  } catch {
+    return null;
+  }
+}
+
 async function validateTokenAgainstServer({ token, serverUrl, timeoutMs }) {
   const t = String(token ?? '').trim();
   if (!t) return { ok: false, status: null };
@@ -50,7 +73,7 @@ async function validateTokenAgainstServer({ token, serverUrl, timeoutMs }) {
  * Ensures the active server-scoped `access.key` file is usable for API calls.
  *
  * Context:
- * - stack daemons often force a stable `HAPPIER_ACTIVE_SERVER_ID` (e.g. stack_<name>__id_default)
+ * - stack daemons may use a stable server profile id while older/auth-specific flows use a URL/profile id
  * - interactive logins may have written credentials under the url-hash server id (env_<hash>)
  * - if the stable-scoped credentials are missing or stale, the daemon will fail to register the machine (401)
  *
@@ -63,25 +86,25 @@ export async function ensureActiveAccessKeyValid({ cliHomeDir, serverUrl, env =
 
   const activePath = resolved.serverScopedPath;
   const activeToken = readAuthTokenFromCredentialPath(activePath);
+  const activeCacheKey = activeToken
+    ? buildCredentialValidationCacheKey({ path: activePath, token: activeToken, serverUrl })
+    : null;
   const allowAccountSwitch =
     (env.HAPPIER_STACK_AUTH_REPAIR_ALLOW_ACCOUNT_SWITCH ?? '').toString().trim() === '1';
   const activeSub = activeToken ? decodeJwtPayloadUnsafe(activeToken)?.sub ?? null : null;
   const activeValid = activeToken
-    ? await validateTokenAgainstServer({ token: activeToken, serverUrl, timeoutMs })
+    ? validationCache.get(activeCacheKey) ?? await validateTokenAgainstServer({ token: activeToken, serverUrl, timeoutMs })
     : { ok: false, status: null };
 
   if (activeValid.ok) {
+    if (activeCacheKey) validationCache.set(activeCacheKey, activeValid);
     return { kind: 'ok', activePath };
   }
 
-  const candidates = [resolved.urlHashServerScopedPath, resolved.legacyPath]
+  const candidates = [...resolved.credentialSourcePaths, resolved.legacyPath]
     .map((p) => String(p ?? '').trim())
     .filter(Boolean)
     .filter((p) => p !== activePath);
-  const hostPortPath = String(resolved.hostPortServerScopedPath ?? '').trim();
-  if (hostPortPath && hostPortPath !== activePath && !candidates.includes(hostPortPath)) {
-    candidates.unshift(hostPortPath);
-  }
 
   const validCandidates = [];
   for (const candidatePath of candidates) {

package/scripts/utils/auth/ensure_active_access_key_valid.test.mjs

@@ -47,7 +47,9 @@ function createTestJwt({ sub, jti }) {
 }
 
 async function withAuthServer({ goodToken }, fn) {
+  let requestCount = 0;
   const server = http.createServer((req, res) => {
+    requestCount += 1;
     if (!req.url || !req.method) {
       res.statusCode = 400;
       res.end();
@@ -74,7 +76,7 @@ async function withAuthServer({ goodToken }, fn) {
   const port = server.address().port;
   const serverUrl = `http://127.0.0.1:${port}`;
   try {
-    return await fn({ serverUrl });
+    return await fn({ serverUrl, getRequestCount: () => requestCount });
   } finally {
     await new Promise((resolve) => server.close(resolve));
   }
@@ -123,6 +125,78 @@ test('ensureActiveAccessKeyValid repairs server-scoped access key from host-port
   }
 });
 
+test('ensureActiveAccessKeyValid repairs a selected profile from the stable daemon lifecycle credential', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'happier-stack-cred-repair-lifecycle-'));
+  try {
+    await withAuthServer({ goodToken: 'good-token' }, async ({ serverUrl }) => {
+      const env = {
+        HAPPIER_ACTIVE_SERVER_ID: 'android-keyboard-qa',
+        HAPPIER_DAEMON_LIFECYCLE_SCOPE_ID: 'stack_repo-remote-dev__id_default',
+      };
+      const resolved = resolveStackCredentialPaths({ cliHomeDir: home, serverUrl, env });
+      const lifecycleCredentialPath = join(
+        home,
+        'servers',
+        env.HAPPIER_DAEMON_LIFECYCLE_SCOPE_ID,
+        'access.key',
+      );
+
+      assert.equal(existsSync(resolved.serverScopedPath), false);
+      writeAccessKeyFile(lifecycleCredentialPath, 'good-token');
+
+      const result = await ensureActiveAccessKeyValid({
+        cliHomeDir: home,
+        serverUrl,
+        env,
+        timeoutMs: 2_500,
+      });
+      assert.equal(result.kind, 'repaired');
+      assert.equal(result.sourcePath, lifecycleCredentialPath);
+      assert.equal(readTokenFromAccessKeyFile(resolved.serverScopedPath), 'good-token');
+    });
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('ensureActiveAccessKeyValid repairs the stable stack scope from a historical matching profile', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'happier-stack-cred-repair-matching-profile-'));
+  try {
+    await withAuthServer({ goodToken: 'good-token' }, async ({ serverUrl }) => {
+      const stableServerId = 'stack_repo-remote-dev__id_default';
+      const historicalServerId = new URL(serverUrl).host.replace(':', '-');
+      const env = {
+        HAPPIER_ACTIVE_SERVER_ID: stableServerId,
+        HAPPIER_STACK_STACK: 'repo-remote-dev',
+      };
+      writeFileSync(
+        join(home, 'settings.json'),
+        JSON.stringify({
+          schemaVersion: 6,
+          activeServerId: stableServerId,
+          servers: {
+            [stableServerId]: { id: stableServerId, serverUrl },
+            [historicalServerId]: { id: historicalServerId, serverUrl },
+          },
+        }),
+      );
+      const resolved = resolveStackCredentialPaths({ cliHomeDir: home, serverUrl, env });
+      const historicalCredentialPath = join(home, 'servers', historicalServerId, 'access.key');
+
+      assert.equal(resolved.aliasServerScopedPaths.includes(historicalCredentialPath), false);
+      assert.equal(resolved.credentialSourcePaths.includes(historicalCredentialPath), true);
+      writeAccessKeyFile(historicalCredentialPath, 'good-token');
+
+      const result = await ensureActiveAccessKeyValid({ cliHomeDir: home, serverUrl, env, timeoutMs: 2_500 });
+      assert.equal(result.kind, 'repaired');
+      assert.equal(result.sourcePath, historicalCredentialPath);
+      assert.equal(readTokenFromAccessKeyFile(resolved.serverScopedPath), 'good-token');
+    });
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
 test('ensureActiveAccessKeyValid does not overwrite an already-valid server-scoped access key', async () => {
   const home = mkdtempSync(join(tmpdir(), 'happier-stack-cred-keep-'));
   try {
@@ -143,6 +217,46 @@ test('ensureActiveAccessKeyValid does not overwrite an already-valid server-scop
   }
 });
 
+test('ensureActiveAccessKeyValid caches unchanged active credential validation', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'happier-stack-cred-cache-'));
+  try {
+    await withAuthServer({ goodToken: 'good-token' }, async ({ serverUrl, getRequestCount }) => {
+      const env = { HAPPIER_ACTIVE_SERVER_ID: 'stack_test__id_default' };
+      const resolved = resolveStackCredentialPaths({ cliHomeDir: home, serverUrl, env });
+      writeAccessKeyFile(resolved.serverScopedPath, 'good-token');
+
+      const first = await ensureActiveAccessKeyValid({ cliHomeDir: home, serverUrl, env, timeoutMs: 2_500 });
+      const second = await ensureActiveAccessKeyValid({ cliHomeDir: home, serverUrl, env, timeoutMs: 2_500 });
+
+      assert.equal(first.kind, 'ok');
+      assert.equal(second.kind, 'ok');
+      assert.equal(getRequestCount(), 1);
+    });
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('ensureActiveAccessKeyValid revalidates when active credential content changes', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'happier-stack-cred-cache-change-'));
+  try {
+    await withAuthServer({ goodToken: 'good-token-2' }, async ({ serverUrl, getRequestCount }) => {
+      const env = { HAPPIER_ACTIVE_SERVER_ID: 'stack_test__id_default' };
+      const resolved = resolveStackCredentialPaths({ cliHomeDir: home, serverUrl, env });
+      writeAccessKeyFile(resolved.serverScopedPath, 'good-token-1');
+      await ensureActiveAccessKeyValid({ cliHomeDir: home, serverUrl, env, timeoutMs: 2_500 });
+
+      writeAccessKeyFile(resolved.serverScopedPath, 'good-token-2');
+      const result = await ensureActiveAccessKeyValid({ cliHomeDir: home, serverUrl, env, timeoutMs: 2_500 });
+
+      assert.equal(result.kind, 'ok');
+      assert.equal(getRequestCount(), 2);
+    });
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
 test('ensureActiveAccessKeyValid seeds missing server-scoped access key from legacy access.key when legacy token is valid', async () => {
   const home = mkdtempSync(join(tmpdir(), 'happier-stack-cred-legacy-'));
   try {

package/scripts/utils/auth/orchestrated_stack_auth_flow.mjs

@@ -15,9 +15,13 @@ import {
   resolveStackWebappTargetForAuth,
   resolveStackAuthCliExecutable,
 } from './stack_guided_login.mjs';
-import { checkDaemonState, startLocalDaemonWithAuth } from '../../daemon.mjs';
+import { checkDaemonStatePingAware, startLocalDaemonWithAuth } from '../../daemon.mjs';
 import { isTty } from '../cli/wizard.mjs';
 import { resolveStackRuntimeLaunchContext } from '../../runtime/launch/resolveStackRuntimeLaunchContext.mjs';
+import {
+  resolveCliRuntimeLaunchProvenance,
+  resolveCliRuntimeLaunchSpec,
+} from '../../runtime/launch/resolveCliRuntimeLaunchSpec.mjs';
 
 function appendCauseText(baseMessage, cause) {
   const msg = String(baseMessage ?? '').trim();
@@ -143,6 +147,7 @@ async function tryStartStackUiInBackgroundForAuth({ rootDir, stackName, env = pr
         env: {
           ...process.env,
           ...(env ?? {}),
+          HAPPIER_STACK_SKIP_REFRESH_DEPS: '1',
           ...(useRuntimeStart ? {} : { HAPPIER_STACK_AUTH_FLOW: '1' }),
         },
       }
@@ -353,6 +358,20 @@ export async function startDaemonPostAuth({
   webappUrl = '',
 } = {}) {
   const name = String(stackName ?? '').trim() || 'main';
+  const runtimeStatePath = getStackRuntimeStatePath(name);
+  const runtimeState = await readStackRuntimeStateFile(runtimeStatePath).catch(() => null);
+  const lifecycleOwnerPid = Number(runtimeState?.ownerPid);
+  if (Number.isFinite(lifecycleOwnerPid) && lifecycleOwnerPid > 1 && isPidAlive(lifecycleOwnerPid)) {
+    const runtimePort = Number(runtimeState?.ports?.server);
+    return {
+      ok: true,
+      status: 'delegated_to_lifecycle_owner',
+      ownerPid: lifecycleOwnerPid,
+      ...(Number.isFinite(runtimePort) && runtimePort > 0
+        ? { internalServerUrl: `http://127.0.0.1:${runtimePort}` }
+        : {}),
+    };
+  }
   const serverPort = await resolveServerPortForPostAuthDaemonStart({ stackName: name, env });
 
   const { envPath, baseDir } = resolveStackEnvPath(name, env);
@@ -362,7 +381,13 @@ export async function startDaemonPostAuth({
   const cliHomeDir =
     (mergedEnv.HAPPIER_STACK_CLI_HOME_DIR ?? '').toString().trim() ||
     join(baseDir, 'cli');
-  const cliBin = await resolveStackAuthCliExecutable({ rootDir, env: mergedEnv });
+  const runtimeLaunchContext = await resolveStackRuntimeLaunchContext({ argv: [], env: mergedEnv });
+  const cliLaunchSpec = runtimeLaunchContext.snapshot
+    ? resolveCliRuntimeLaunchSpec({ snapshot: runtimeLaunchContext.snapshot })
+    : null;
+  const runtimeProvenance = resolveCliRuntimeLaunchProvenance(cliLaunchSpec);
+  const cliBin = cliLaunchSpec?.command
+    || await resolveStackAuthCliExecutable({ rootDir, env: mergedEnv });
 
   const internalServerUrl = `http://127.0.0.1:${serverPort}`;
   const explicitWebappUrl = String(webappUrl ?? '').trim();
@@ -376,19 +401,25 @@ export async function startDaemonPostAuth({
 
   await startLocalDaemonWithAuth({
     cliBin,
+    cliEntrypoint: cliLaunchSpec?.entrypoint ?? '',
+    cliNodeEntrypoint: cliLaunchSpec?.nodeEntrypoint ?? '',
+    cliCommand: cliLaunchSpec?.command ?? '',
+    cliCommandArgs: cliLaunchSpec?.args ?? [],
     cliHomeDir,
     internalServerUrl,
     publicServerUrl,
+    runtimeStatePath,
     isShuttingDown: () => false,
     forceRestart: Boolean(forceRestart),
     env: mergedEnv,
     stackName: name,
+    ...runtimeProvenance,
   });
 
   // Verify (best-effort): daemon wrote state.
   const deadline = Date.now() + 10_000;
   while (Date.now() < deadline) {
-    const s = checkDaemonState(cliHomeDir, { serverUrl: internalServerUrl, env: mergedEnv });
+    const s = await checkDaemonStatePingAware(cliHomeDir, { serverUrl: internalServerUrl, env: mergedEnv });
     if (s.status === 'running') {
       return {
         ok: true,

package/scripts/utils/auth/stable_scope_id.mjs

@@ -89,3 +89,14 @@ export function applyStackActiveServerScopeEnv({ env = process.env, stackName =
   base.HAPPIER_ACTIVE_SERVER_ID = activeServerId;
   return base;
 }
+
+export function applyStackDaemonLifecycleScopeEnv({ env = process.env, stackName = null, cliIdentity = null } = {}) {
+  const base = { ...(env ?? {}) };
+  const lifecycleScopeId = resolveStackActiveServerId({ env: base, stackName, cliIdentity });
+  if (!lifecycleScopeId) {
+    delete base.HAPPIER_DAEMON_LIFECYCLE_SCOPE_ID;
+    return base;
+  }
+  base.HAPPIER_DAEMON_LIFECYCLE_SCOPE_ID = lifecycleScopeId;
+  return base;
+}

package/scripts/utils/auth/stable_scope_id.test.mjs

@@ -3,6 +3,7 @@ import assert from 'node:assert/strict';
 
 import {
   applyStackActiveServerScopeEnv,
+  applyStackDaemonLifecycleScopeEnv,
   buildStackStableScopeId,
   resolveStackActiveServerId,
 } from './stable_scope_id.mjs';
@@ -49,3 +50,18 @@ test('applyStackActiveServerScopeEnv sets generated stable scope id by default',
   const next = applyStackActiveServerScopeEnv({ env, stackName: 'feature-123', cliIdentity: 'account-b' });
   assert.equal(next.HAPPIER_ACTIVE_SERVER_ID, 'stack_feature-123__id_account-b');
 });
+
+test('applyStackDaemonLifecycleScopeEnv keeps endpoint profile selection independent', () => {
+  const env = {
+    HAPPIER_ACTIVE_SERVER_ID: 'android-keyboard-qa',
+    HAPPIER_STACK_STACK: 'repo-remote-dev-d72117acdb',
+  };
+  const next = applyStackDaemonLifecycleScopeEnv({
+    env,
+    stackName: 'repo-remote-dev-d72117acdb',
+    cliIdentity: 'default',
+  });
+
+  assert.equal(next.HAPPIER_ACTIVE_SERVER_ID, 'android-keyboard-qa');
+  assert.equal(next.HAPPIER_DAEMON_LIFECYCLE_SCOPE_ID, 'stack_repo-remote-dev-d72117acdb__id_default');
+});

package/scripts/utils/auth/stack_guided_login.mjs

@@ -127,6 +127,27 @@ async function resolveExpoWebappUrlForAuth({ rootDir, stackName, timeoutMs }) {
   return '';
 }
 
+export async function resolveBestExpoWebappUrlForAuth({ rootDir, stackName, env = process.env, timeoutMs } = {}) {
+  void env;
+  const runtimeExpoUrl = await resolveRuntimeExpoWebappUrlForAuth({ stackName });
+  if (runtimeExpoUrl) {
+    return await preferStackLocalhostUrl(runtimeExpoUrl, { stackName });
+  }
+
+  const rawTimeout = Number(timeoutMs);
+  const resolvedTimeout = Number.isFinite(rawTimeout) && rawTimeout > 0 ? rawTimeout : 180_000;
+  const expoUrl = await resolveExpoWebappUrlForAuth({
+    rootDir,
+    stackName,
+    timeoutMs: resolvedTimeout,
+  });
+  if (!expoUrl) {
+    return '';
+  }
+
+  return await preferStackLocalhostUrl(expoUrl, { stackName });
+}
+
 async function fetchText(url, { timeoutMs = 2000 } = {}) {
   const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
   const timeout = setTimeout(() => controller?.abort(), timeoutMs);
@@ -335,18 +356,6 @@ async function resolveServerWebappUrlForAuth({ stackName, env = process.env }) {
 
 export async function resolveStackWebappTargetForAuth({ rootDir, stackName, env = process.env } = {}) {
   const runtimeLaunchContext = await resolveStackRuntimeLaunchContext({ argv: [], env });
-  if (runtimeLaunchContext.snapshot) {
-    const runtimeServerUrl = await resolveServerWebappUrlForAuth({ stackName, env });
-    if (runtimeServerUrl) {
-      return { webappUrl: runtimeServerUrl, kind: 'server' };
-    }
-  }
-
-  const runtimeExpoUrl = await resolveRuntimeExpoWebappUrlForAuth({ stackName });
-  if (runtimeExpoUrl) {
-    return { webappUrl: await preferStackLocalhostUrl(runtimeExpoUrl, { stackName }), kind: 'expo' };
-  }
-
   const authFlow =
     (env.HAPPIER_STACK_AUTH_FLOW ?? '').toString().trim() === '1' ||
     (env.HAPPIER_STACK_DAEMON_WAIT_FOR_AUTH ?? '').toString().trim() === '1';
@@ -354,13 +363,21 @@ export async function resolveStackWebappTargetForAuth({ rootDir, stackName, env
   const timeoutMsRaw =
     (env.HAPPIER_STACK_AUTH_UI_READY_TIMEOUT_MS ?? '180000').toString().trim();
   const timeoutMs = timeoutMsRaw ? Number(timeoutMsRaw) : 180_000;
-  const expoUrl = await resolveExpoWebappUrlForAuth({
+  const expoUrl = await resolveBestExpoWebappUrlForAuth({
     rootDir,
     stackName,
-    timeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 180_000,
+    env,
+    timeoutMs,
   });
   if (expoUrl) {
-    return { webappUrl: await preferStackLocalhostUrl(expoUrl, { stackName }), kind: 'expo' };
+    return { webappUrl: expoUrl, kind: 'expo' };
+  }
+
+  if (runtimeLaunchContext.snapshot) {
+    const runtimeServerUrl = await resolveServerWebappUrlForAuth({ stackName, env });
+    if (runtimeServerUrl) {
+      return { webappUrl: runtimeServerUrl, kind: 'server' };
+    }
   }
 
   if (authFlow) {

package/scripts/utils/cli/args.mjs

@@ -1,17 +1,43 @@
+import { gethstackSpaceSeparatedValueFlags } from './cli_registry.mjs';
+
+const SPACE_SEPARATED_VALUE_FLAGS = gethstackSpaceSeparatedValueFlags();
+
+function shouldConsumeNextTokenAsValue(flag, nextToken) {
+  if (!SPACE_SEPARATED_VALUE_FLAGS.has(flag)) return false;
+  if (typeof nextToken !== 'string' || nextToken.length === 0) return false;
+  return !nextToken.startsWith('-');
+}
+
 export function parseArgs(argv) {
   const flags = new Set();
   const kv = new Map();
-  for (const raw of argv) {
+  const args = Array.isArray(argv) ? argv.map(String) : [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const raw = args[index];
+    if (raw === '--') {
+      continue;
+    }
     if (!raw.startsWith('--')) {
       continue;
     }
-    const [k, v] = raw.split('=', 2);
-    if (v === undefined) {
-      flags.add(k);
-    } else {
-      kv.set(k, v);
+
+    const equalsIndex = raw.indexOf('=');
+    const key = equalsIndex < 0 ? raw : raw.slice(0, equalsIndex);
+    const value = equalsIndex < 0 ? undefined : raw.slice(equalsIndex + 1);
+    if (value === undefined) {
+      const next = args[index + 1];
+      if (shouldConsumeNextTokenAsValue(key, next)) {
+        kv.set(key, next);
+        index += 1;
+        continue;
+      }
+      flags.add(key);
+      continue;
     }
+
+    kv.set(key, value);
   }
+
   return { flags, kv };
 }
-

package/scripts/utils/cli/args.test.mjs

@@ -0,0 +1,51 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { parseArgs } from './args.mjs';
+
+test('parseArgs keeps boolean flags when followed by positionals', () => {
+  const { flags, kv } = parseArgs(['--json', 'ui']);
+
+  assert.equal(flags.has('--json'), true);
+  assert.equal(kv.has('--json'), false);
+});
+
+test('parseArgs ignores bare passthrough sentinel tokens', () => {
+  const { flags, kv } = parseArgs(['--', 'vitest', '--json']);
+
+  assert.equal(flags.has('--'), false);
+  assert.equal(kv.has('--'), false);
+  assert.equal(flags.has('--json'), true);
+});
+
+test('parseArgs consumes the next token only for contract-defined value flags', () => {
+  const { flags, kv } = parseArgs(['--mode', 'user', '--sandbox-dir', '/tmp/hstack']);
+
+  assert.equal(flags.has('--mode'), false);
+  assert.equal(kv.get('--mode'), 'user');
+  assert.equal(flags.has('--sandbox-dir'), false);
+  assert.equal(kv.get('--sandbox-dir'), '/tmp/hstack');
+});
+
+test('parseArgs does not infer next-token values for equals-only flags', () => {
+  const { flags, kv } = parseArgs(['--profile', 'selfhost']);
+
+  assert.equal(flags.has('--profile'), true);
+  assert.equal(kv.has('--profile'), false);
+});
+
+test('parseArgs preserves equals signs inside an inline value', () => {
+  const databaseUrl = 'postgresql://operator:secret@db.example/happier?sslmode=require&application_name=hstack';
+  const { kv } = parseArgs([`--database-url=${databaseUrl}`]);
+
+  assert.equal(kv.get('--database-url'), databaseUrl);
+});
+
+test('parseArgs does not let undocumented boolean-style flags swallow following positionals', () => {
+  for (const flag of ['--force', '--background', '--offline-ok', '--with-infra']) {
+    const { flags, kv } = parseArgs([flag, 'feature-123']);
+
+    assert.equal(flags.has(flag), true, `${flag} should remain a flag`);
+    assert.equal(kv.has(flag), false, `${flag} should not consume the following positional`);
+  }
+});

package/scripts/utils/cli/cli.mjs

@@ -12,13 +12,12 @@ export function wantsHelp(argv, { flags = null } = {}) {
   return argv.includes('--help') || argv.includes('-h');
 }
 
-export function printResult({ json, data, text }) {
+export function printResult({ json, data, text, output = process.stdout }) {
   if (json) {
-    process.stdout.write(JSON.stringify(data ?? null, null, 2) + '\n');
+    output.write(JSON.stringify(data ?? null, null, 2) + '\n');
     return;
   }
   if (text) {
-    process.stdout.write(text.endsWith('\n') ? text : text + '\n');
+    output.write(text.endsWith('\n') ? text : text + '\n');
   }
 }
-