@happier-dev/stack 0.1.0 → 0.2.0

package/scripts/provision/macos-lima-hstack-repeat-validation.test.mjs

@@ -0,0 +1,369 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, writeFile, chmod } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+async function fileExists(path) {
+  try {
+    await readFile(path, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+test('macos lima repeat-validation wrapper records per-run artifacts for repeated smoke runs', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'hstack-macos-lima-repeat-'));
+  const binDir = join(root, 'bin');
+  const homeDir = join(root, 'home');
+  const reportDir = join(root, 'reports');
+  const logDir = join(root, 'logs');
+  const limaHome = join(homeDir, '.lima');
+
+  await mkdir(binDir, { recursive: true });
+  await mkdir(homeDir, { recursive: true });
+  await mkdir(reportDir, { recursive: true });
+  await mkdir(logDir, { recursive: true });
+
+  const limactlLog = join(logDir, 'limactl.log');
+  const curlLog = join(logDir, 'curl.log');
+
+  const unamePath = join(binDir, 'uname');
+  await writeFile(unamePath, ['#!/usr/bin/env bash', 'echo Darwin'].join('\n') + '\n', 'utf8');
+  await chmod(unamePath, 0o755);
+
+  const curlPath = join(binDir, 'curl');
+  await writeFile(
+    curlPath,
+    [
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      `echo "curl $*" >> ${JSON.stringify(curlLog)}`,
+      'out=""',
+      'url=""',
+      'while [[ $# -gt 0 ]]; do',
+      '  case "$1" in',
+      '    -o)',
+      '      out="$2"',
+      '      shift 2',
+      '      continue',
+      '      ;;',
+      '    -f|-fs|-fsS|-fsSL|-s|-S|-L)',
+      '      shift',
+      '      continue',
+      '      ;;',
+      '    *)',
+      '      url="$1"',
+      '      shift',
+      '      continue',
+      '      ;;',
+      '  esac',
+      'done',
+      'if [[ -z "$out" ]]; then',
+      '  echo "missing -o output path" >&2',
+      '  exit 2',
+      'fi',
+      'case "$url" in',
+      '  *linux-ubuntu-provision.sh)',
+      '    cat >"$out" <<\'EOF\'',
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      'echo "provision $* profile=${1:-}"',
+      'EOF',
+      '    ;;',
+      '  *linux-ubuntu-hstack-smoke.sh)',
+      '    cat >"$out" <<\'EOF\'',
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      'mkdir -p "${HSTACK_SMOKE_DIR:?}"',
+      'printf "%s\\n" "${HSTACK_SMOKE_DIR}" >> "${HSTACK_SMOKE_DIR}/guest-smoke-dir.log"',
+      'printf "%s\\n" "${HSTACK_SMOKE_KEEP:-}" >> "${HSTACK_SMOKE_DIR}/guest-smoke-keep.log"',
+      'printf "%s\\n" "${HSTACK_VERSION:-}" >> "${HSTACK_SMOKE_DIR}/guest-version.log"',
+      'touch "${HSTACK_SMOKE_DIR}/smoke-ok"',
+      'echo "smoke ok: ${HSTACK_SMOKE_DIR}"',
+      'EOF',
+      '    ;;',
+      '  *)',
+      '    echo "unexpected url: $url" >&2',
+      '    exit 3',
+      '    ;;',
+      'esac',
+      'chmod +x "$out"',
+      'exit 0',
+    ].join('\n') + '\n',
+    'utf8'
+  );
+  await chmod(curlPath, 0o755);
+
+  const limactlPath = join(binDir, 'limactl');
+  await writeFile(
+    limactlPath,
+    [
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      `echo "limactl $*" >> ${JSON.stringify(limactlLog)}`,
+      'cmd="${1:-}"',
+      'shift || true',
+      'case "$cmd" in',
+      '  create)',
+      '    name=""',
+      '    while [[ $# -gt 0 ]]; do',
+      '      if [[ "$1" == "--name" ]]; then',
+      '        name="$2"',
+      '        shift 2',
+      '        continue',
+      '      fi',
+      '      shift || true',
+      '    done',
+      '    mkdir -p "${LIMA_HOME:-$HOME/.lima}/${name}"',
+      '    printf "%s\\n" "memory: \\"4GiB\\"" > "${LIMA_HOME:-$HOME/.lima}/${name}/lima.yaml"',
+      '    exit 0',
+      '    ;;',
+      '  stop|start)',
+      '    exit 0',
+      '    ;;',
+      '  shell)',
+      '    while [[ $# -gt 0 && "$1" != "--" ]]; do',
+      '      shift',
+      '    done',
+      '    if [[ "${1:-}" == "--" ]]; then',
+      '      shift',
+      '    fi',
+      '    if [[ "${1:-}" == "env" ]]; then',
+      '      shift',
+      '      while [[ $# -gt 0 && "$1" == *=* ]]; do',
+      '        export "$1"',
+      '        shift',
+      '      done',
+      '      if [[ "${1:-}" == "bash" && "${2:-}" == "-lc" ]]; then',
+      '        shift 2',
+      '        exec bash -c "${1:-}"',
+      '      fi',
+      '    fi',
+      '    exec "$@"',
+      '    ;;',
+      '  *)',
+      '    exit 0',
+      '    ;;',
+      'esac',
+    ].join('\n') + '\n',
+    'utf8'
+  );
+  await chmod(limactlPath, 0o755);
+
+  const scriptPath = join(__dirname, 'macos-lima-hstack-repeat-validation.sh');
+  const env = {
+    ...process.env,
+    HOME: homeDir,
+    LIMA_HOME: limaHome,
+    PATH: `${binDir}:${process.env.PATH ?? ''}`,
+    HSTACK_RAW_BASE: 'https://example.test/apps/stack',
+    HSTACK_VERSION: '0.9.0-test',
+    HSTACK_REPEAT_COUNT: '2',
+    HSTACK_REPEAT_OUTPUT_DIR: reportDir,
+    HSTACK_PROVISION_PROFILE: 'happier',
+  };
+
+  const res = spawnSync('bash', [scriptPath, 'happy-repeat'], {
+    cwd: root,
+    env,
+    encoding: 'utf8',
+  });
+
+  assert.equal(res.status, 0, `expected exit 0\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const summaryPath = join(reportDir, 'summary.json');
+  assert.equal(await fileExists(summaryPath), true, 'expected summary.json to be written');
+
+  const summary = JSON.parse(await readFile(summaryPath, 'utf8'));
+  assert.equal(summary.kind, 'lima_repeat_validation');
+  assert.equal(summary.vmName, 'happy-repeat');
+  assert.equal(summary.repeatCount, 2);
+  assert.equal(summary.status, 0);
+  assert.equal(summary.failureStage, null);
+  assert.equal(summary.failureReason, null);
+  assert.equal(summary.runs.length, 2);
+  assert.notEqual(summary.runs[0].guestSmokeDir, summary.runs[1].guestSmokeDir);
+
+  for (const run of summary.runs) {
+    assert.equal(await fileExists(run.logPath), true, `expected guest log at ${run.logPath}`);
+    assert.equal(await fileExists(run.metaPath), true, `expected run metadata at ${run.metaPath}`);
+    const meta = JSON.parse(await readFile(run.metaPath, 'utf8'));
+    assert.equal(meta.status, 0);
+    assert.equal(await fileExists(join(run.guestSmokeDir, 'smoke-ok')), true, 'expected smoke marker in preserved guest dir');
+  }
+
+  const limactlOut = await readFile(limactlLog, 'utf8');
+  assert.match(limactlOut, /limactl create --name happy-repeat/);
+  assert.equal((limactlOut.match(/limactl shell/g) ?? []).length, 2, 'expected two guest shell invocations');
+});
+
+test('macos lima repeat-validation wrapper writes summary.json with failureReason when a run fails', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'hstack-macos-lima-repeat-fail-'));
+  const binDir = join(root, 'bin');
+  const homeDir = join(root, 'home');
+  const reportDir = join(root, 'reports');
+  const logDir = join(root, 'logs');
+  const limaHome = join(homeDir, '.lima');
+
+  await mkdir(binDir, { recursive: true });
+  await mkdir(homeDir, { recursive: true });
+  await mkdir(reportDir, { recursive: true });
+  await mkdir(logDir, { recursive: true });
+
+  const limactlLog = join(logDir, 'limactl.log');
+  const curlLog = join(logDir, 'curl.log');
+
+  const unamePath = join(binDir, 'uname');
+  await writeFile(unamePath, ['#!/usr/bin/env bash', 'echo Darwin'].join('\n') + '\n', 'utf8');
+  await chmod(unamePath, 0o755);
+
+  const curlPath = join(binDir, 'curl');
+  await writeFile(
+    curlPath,
+    [
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      `echo "curl $*" >> ${JSON.stringify(curlLog)}`,
+      'out=""',
+      'url=""',
+      'while [[ $# -gt 0 ]]; do',
+      '  case "$1" in',
+      '    -o)',
+      '      out="$2"',
+      '      shift 2',
+      '      continue',
+      '      ;;',
+      '    -f|-fs|-fsS|-fsSL|-s|-S|-L)',
+      '      shift',
+      '      continue',
+      '      ;;',
+      '    *)',
+      '      url="$1"',
+      '      shift',
+      '      continue',
+      '      ;;',
+      '  esac',
+      'done',
+      'if [[ -z "$out" ]]; then',
+      '  echo "missing -o output path" >&2',
+      '  exit 2',
+      'fi',
+      'case "$url" in',
+      '  *linux-ubuntu-provision.sh)',
+      '    cat >"$out" <<\'EOF\'',
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      'echo "provision $* profile=${1:-}"',
+      'EOF',
+      '    ;;',
+      '  *linux-ubuntu-hstack-smoke.sh)',
+      '    cat >"$out" <<\'EOF\'',
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      'mkdir -p "${HSTACK_SMOKE_DIR:?}"',
+      'touch "${HSTACK_SMOKE_DIR}/smoke-ok"',
+      'echo "smoke ok: ${HSTACK_SMOKE_DIR}"',
+      'EOF',
+      '    ;;',
+      '  *)',
+      '    echo "unexpected url: $url" >&2',
+      '    exit 3',
+      '    ;;',
+      'esac',
+      'chmod +x "$out"',
+      'exit 0',
+    ].join('\n') + '\n',
+    'utf8',
+  );
+  await chmod(curlPath, 0o755);
+
+  const limactlPath = join(binDir, 'limactl');
+  await writeFile(
+    limactlPath,
+    [
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      `echo "limactl $*" >> ${JSON.stringify(limactlLog)}`,
+      'cmd="${1:-}"',
+      'shift || true',
+      'case "$cmd" in',
+      '  create)',
+      '    name=""',
+      '    while [[ $# -gt 0 ]]; do',
+      '      if [[ "$1" == "--name" ]]; then',
+      '        name="$2"',
+      '        shift 2',
+      '        continue',
+      '      fi',
+      '      shift || true',
+      '    done',
+      '    mkdir -p "${LIMA_HOME:-$HOME/.lima}/${name}"',
+      '    printf "%s\\n" "memory: \\"4GiB\\"" > "${LIMA_HOME:-$HOME/.lima}/${name}/lima.yaml"',
+      '    exit 0',
+      '    ;;',
+      '  stop|start)',
+      '    exit 0',
+      '    ;;',
+      '  shell)',
+      '    # Fail closed on the second run by inspecting the injected HSTACK_SMOKE_DIR.',
+      '    while [[ $# -gt 0 && "$1" != "--" ]]; do shift; done',
+      '    if [[ "${1:-}" == "--" ]]; then shift; fi',
+      '    if [[ "${1:-}" == "env" ]]; then',
+      '      shift',
+      '      while [[ $# -gt 0 && "$1" == *=* ]]; do',
+      '        export "$1"',
+      '        shift',
+      '      done',
+      '      if [[ "${HSTACK_SMOKE_DIR:-}" == *"-02" ]]; then',
+      '        echo "forced failure for run 02" >&2',
+      '        exit 42',
+      '      fi',
+      '    fi',
+      '    exec "$@"',
+      '    ;;',
+      '  *)',
+      '    exit 0',
+      '    ;;',
+      'esac',
+    ].join('\n') + '\n',
+    'utf8',
+  );
+  await chmod(limactlPath, 0o755);
+
+  const scriptPath = join(__dirname, 'macos-lima-hstack-repeat-validation.sh');
+  const env = {
+    ...process.env,
+    HOME: homeDir,
+    LIMA_HOME: limaHome,
+    PATH: `${binDir}:${process.env.PATH ?? ''}`,
+    HSTACK_RAW_BASE: 'https://example.test/apps/stack',
+    HSTACK_VERSION: '0.9.0-test',
+    HSTACK_REPEAT_COUNT: '2',
+    HSTACK_REPEAT_OUTPUT_DIR: reportDir,
+    HSTACK_PROVISION_PROFILE: 'happier',
+  };
+
+  const res = spawnSync('bash', [scriptPath, 'happy-repeat'], {
+    cwd: root,
+    env,
+    encoding: 'utf8',
+  });
+
+  assert.equal(res.status, 42, `expected exit 42\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const summaryPath = join(reportDir, 'summary.json');
+  assert.equal(await fileExists(summaryPath), true, 'expected summary.json to be written even on failure');
+  const summary = JSON.parse(await readFile(summaryPath, 'utf8'));
+  assert.equal(summary.kind, 'lima_repeat_validation');
+  assert.equal(summary.status, 42);
+  assert.equal(summary.failureStage, 'guest_smoke');
+  assert.ok(typeof summary.failureReason === 'string' && summary.failureReason.length > 0);
+  assert.equal(summary.runs.length, 2);
+  assert.equal(summary.runs[1].status, 42);
+});

package/scripts/provision/playwright-wsrepl-matrix-url.test.mjs

@@ -0,0 +1,143 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+async function loadQaUrlModule() {
+  const repoRoot = resolve(join(__dirname, '../../../../'));
+  const modPath = resolve(join(repoRoot, 'scripts/qa/resolveQaUiUrl.mjs'));
+  return import(pathToFileURL(modPath).href);
+}
+
+test('qa wsrepl url helper resolves stack runtime ports using a loopback 127.0.0.1 server url', async () => {
+  const qa = await loadQaUrlModule();
+  assert.equal(typeof qa.resolveQaUiUrl, 'function', 'expected resolveQaUiUrl.mjs to export resolveQaUiUrl');
+
+  const root = await mkdtemp(join(tmpdir(), 'qa-wsrepl-uiurl-'));
+  const runtimePath = resolve(join(root, 'stack.runtime.json'));
+  await writeFile(
+    runtimePath,
+    JSON.stringify({ ports: { server: 53288 }, expo: { webPort: 19364 } }) + '\n',
+    'utf8',
+  );
+
+  const prev = process.env.HAPPIER_QA_STACK_RUNTIME_JSON_PATH;
+  process.env.HAPPIER_QA_STACK_RUNTIME_JSON_PATH = runtimePath;
+  try {
+    const out = qa.resolveQaUiUrl();
+    const parsed = new URL(out);
+    assert.equal(parsed.origin, 'http://127.0.0.1:19364');
+    assert.equal(parsed.searchParams.get('server'), 'http://127.0.0.1:53288');
+  } finally {
+    if (prev === undefined) delete process.env.HAPPIER_QA_STACK_RUNTIME_JSON_PATH;
+    else process.env.HAPPIER_QA_STACK_RUNTIME_JSON_PATH = prev;
+  }
+});
+
+test('qa wsrepl url helper can auto-detect the newest stack.runtime.json when stack name and explicit runtime path are unset', async () => {
+  const qa = await loadQaUrlModule();
+
+  const root = await mkdtemp(join(tmpdir(), 'qa-wsrepl-uiurl-autodetect-'));
+  const stacksDir = resolve(join(root, 'stacks'));
+  await mkdir(stacksDir, { recursive: true });
+
+  const stackA = join(stacksDir, 'stack-a');
+  const stackB = join(stacksDir, 'stack-b');
+  await mkdir(stackA, { recursive: true });
+  await mkdir(stackB, { recursive: true });
+
+  await writeFile(
+    join(stackA, 'stack.runtime.json'),
+    JSON.stringify({ ports: { server: 40001 }, expo: { webPort: 40002 }, updatedAt: '2026-03-22T00:00:00.000Z' }) + '\n',
+    'utf8',
+  );
+  await writeFile(
+    join(stackB, 'stack.runtime.json'),
+    JSON.stringify({ ports: { server: 50001 }, expo: { webPort: 50002 }, updatedAt: '2026-03-23T00:00:00.000Z' }) + '\n',
+    'utf8',
+  );
+
+  const prevStacksDir = process.env.HAPPIER_QA_STACKS_DIR;
+  const prevRuntimePath = process.env.HAPPIER_QA_STACK_RUNTIME_JSON_PATH;
+  const prevStackName = process.env.HAPPIER_QA_STACK_NAME;
+  delete process.env.HAPPIER_QA_STACK_RUNTIME_JSON_PATH;
+  delete process.env.HAPPIER_QA_STACK_NAME;
+  process.env.HAPPIER_QA_STACKS_DIR = stacksDir;
+
+  try {
+    const out = qa.resolveQaUiUrl();
+    const parsed = new URL(out);
+    assert.equal(parsed.origin, 'http://127.0.0.1:50002');
+    assert.equal(parsed.searchParams.get('server'), 'http://127.0.0.1:50001');
+  } finally {
+    if (prevStacksDir === undefined) delete process.env.HAPPIER_QA_STACKS_DIR;
+    else process.env.HAPPIER_QA_STACKS_DIR = prevStacksDir;
+    if (prevRuntimePath === undefined) delete process.env.HAPPIER_QA_STACK_RUNTIME_JSON_PATH;
+    else process.env.HAPPIER_QA_STACK_RUNTIME_JSON_PATH = prevRuntimePath;
+    if (prevStackName === undefined) delete process.env.HAPPIER_QA_STACK_NAME;
+    else process.env.HAPPIER_QA_STACK_NAME = prevStackName;
+  }
+});
+
+test('qa wsrepl url helper preserves server query param by default', async () => {
+  const qa = await loadQaUrlModule();
+  assert.equal(typeof qa.withQaUiBase, 'function', 'expected resolveQaUiUrl.mjs to export withQaUiBase');
+
+  const base = 'http://localhost:19364/?server=http%3A%2F%2F127.0.0.1%3A53288&happier_hmr=0';
+  const next = qa.withQaUiBase(base, '/session/sess_123/info');
+
+  const parsed = new URL(next);
+  assert.equal(parsed.pathname, '/session/sess_123/info');
+  assert.equal(parsed.searchParams.get('server'), 'http://127.0.0.1:53288');
+  assert.equal(parsed.searchParams.get('happier_hmr'), '0');
+});
+
+test('qa wsrepl url helper can strip server query param when requested', async () => {
+  const qa = await loadQaUrlModule();
+  assert.equal(typeof qa.withQaUiBase, 'function', 'expected resolveQaUiUrl.mjs to export withQaUiBase');
+
+  const base = 'http://localhost:19364/?server=http%3A%2F%2F127.0.0.1%3A53288&happier_hmr=0';
+  const next = qa.withQaUiBase(base, '/session/sess_123/info', { stripServerParam: true });
+
+  const parsed = new URL(next);
+  assert.equal(parsed.pathname, '/session/sess_123/info');
+  assert.equal(parsed.searchParams.get('server'), null);
+  assert.equal(parsed.searchParams.get('happier_hmr'), '0');
+});
+
+test('qa wsrepl url helper can force happier_hmr=0', async () => {
+  const qa = await loadQaUrlModule();
+  assert.equal(
+    typeof qa.ensureQaUiUrlHasHmrDisabled,
+    'function',
+    'expected resolveQaUiUrl.mjs to export ensureQaUiUrlHasHmrDisabled',
+  );
+
+  const base = 'http://localhost:19364/?server=http%3A%2F%2F127.0.0.1%3A53288';
+  const next = qa.ensureQaUiUrlHasHmrDisabled(base);
+  const parsed = new URL(next);
+  assert.equal(parsed.searchParams.get('server'), 'http://127.0.0.1:53288');
+  assert.equal(parsed.searchParams.get('happier_hmr'), '0');
+});
+
+test('qa wsrepl url helper can match a path suffix', async () => {
+  const qa = await loadQaUrlModule();
+  assert.equal(
+    typeof qa.isQaUiUrlPathSuffix,
+    'function',
+    'expected resolveQaUiUrl.mjs to export isQaUiUrlPathSuffix',
+  );
+
+  assert.equal(
+    qa.isQaUiUrlPathSuffix('http://localhost:19364/session/abc/info?server=http%3A%2F%2F127.0.0.1%3A53288', '/session/abc/info'),
+    true,
+  );
+  assert.equal(
+    qa.isQaUiUrlPathSuffix('http://localhost:19364/new?server=http%3A%2F%2F127.0.0.1%3A53288', '/session/abc/info'),
+    false,
+  );
+});

package/scripts/provision/resolveStackAuthPaths.test.mjs

@@ -0,0 +1,68 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  resolveQaStackName,
+  resolveServerPortFromUiUrl,
+  resolveStackCliAccessKeyCandidates,
+  resolveStackNameFromServerPort,
+} from '../../../../scripts/qa/resolveStackAuthPaths.mjs';
+
+test('resolveServerPortFromUiUrl extracts server port from server= query param', () => {
+  const uiUrl = 'http://localhost:19364/?server=http%3A%2F%2Flocalhost%3A53288&happier_hmr=0';
+  assert.equal(resolveServerPortFromUiUrl(uiUrl), 53288);
+});
+
+test('resolveQaStackName prefers explicit stack name', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'hstack-resolve-stack-auth-explicit-'));
+  const homeDir = join(root, 'home');
+  await mkdir(homeDir, { recursive: true });
+
+  const uiUrl = 'http://localhost:19364/?server=http%3A%2F%2Flocalhost%3A53288';
+  const stackName = resolveQaStackName({ uiUrl, explicitStackName: 'explicit-stack', homeDir });
+  assert.equal(stackName, 'explicit-stack');
+});
+
+test('resolveQaStackName selects newest stack runtime matching server port', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'hstack-resolve-stack-auth-'));
+  const homeDir = join(root, 'home');
+  const stacksRoot = join(homeDir, '.happier', 'stacks');
+
+  const stackOld = join(stacksRoot, 'stack-old');
+  const stackNew = join(stacksRoot, 'stack-new');
+  await mkdir(stackOld, { recursive: true });
+  await mkdir(stackNew, { recursive: true });
+
+  await writeFile(
+    join(stackOld, 'stack.runtime.json'),
+    JSON.stringify({ ports: { server: 53288 }, updatedAt: '2026-03-23T10:00:00.000Z' }, null, 2) + '\n',
+    'utf8',
+  );
+  await writeFile(
+    join(stackNew, 'stack.runtime.json'),
+    JSON.stringify({ runtime: { ports: { server: 53288 } }, updatedAt: '2026-03-23T12:00:00.000Z' }, null, 2) + '\n',
+    'utf8',
+  );
+
+  const uiUrl = 'http://localhost:19364/?server=http%3A%2F%2Flocalhost%3A53288&happier_hmr=0';
+  assert.equal(resolveQaStackName({ uiUrl, explicitStackName: '', homeDir }), 'stack-new');
+  assert.equal(resolveStackNameFromServerPort({ serverPort: 53288, homeDir }), 'stack-new');
+});
+
+test('resolveStackCliAccessKeyCandidates returns deterministic access.key candidates under cli root', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'hstack-resolve-stack-auth-access-key-'));
+  const homeDir = join(root, 'home');
+  const stackName = 'stack-test';
+
+  const cliRoot = join(homeDir, '.happier', 'stacks', stackName, 'cli');
+  await mkdir(join(cliRoot, 'servers', 'server_a'), { recursive: true });
+  await mkdir(join(cliRoot, 'servers', 'server_b'), { recursive: true });
+
+  const candidates = resolveStackCliAccessKeyCandidates({ stackName, homeDir });
+  assert.equal(candidates[0], join(cliRoot, 'access.key'));
+  assert.ok(candidates.includes(join(cliRoot, 'servers', 'server_a', 'access.key')));
+  assert.ok(candidates.includes(join(cliRoot, 'servers', 'server_b', 'access.key')));
+});

package/scripts/provision/wsreplMatrixCredentials.test.mjs

@@ -0,0 +1,44 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import crypto from 'node:crypto';
+
+import {
+  buildServerProfilesSeedEntries,
+  buildTokenStorageCredentialKeys,
+} from '../../../../scripts/qa/wsreplMatrixCredentials.mjs';
+
+function sha256Base64Url(value) {
+  const hash = crypto.createHash('sha256').update(String(value ?? ''), 'utf8').digest();
+  return hash.toString('base64url');
+}
+
+test('buildTokenStorageCredentialKeys covers TokenStorage primary + legacy scopes for localhost', () => {
+  const serverUrl = 'http://localhost:53288';
+  const keys = buildTokenStorageCredentialKeys({ serverUrl, stackName: 'repo-dev-a1cc5e0671' });
+
+  assert.ok(keys.includes('auth_credentials__srv_default'));
+  assert.ok(keys.includes('auth_credentials__srv_localhost-53288'));
+  // TokenStorage scope tokens are sanitized (non [a-z0-9._-] -> '_' and collapsed), so `__id_default`
+  // becomes `_id_default`.
+  assert.ok(keys.includes('auth_credentials__srv_stack_repo-dev-a1cc5e0671_id_default'));
+
+  assert.ok(keys.includes(`auth_credentials__srv_${sha256Base64Url('http://localhost:53288')}`));
+  // TokenStorage still probes a legacy hash scope that treats 127.0.0.1 distinct from localhost.
+  assert.ok(keys.includes(`auth_credentials__srv_${sha256Base64Url('http://127.0.0.1:53288')}`));
+});
+
+test('buildServerProfilesSeedEntries seeds MMKV server-profiles state and tab-scoped activeServerId', () => {
+  const serverUrl = 'http://127.0.0.1:53288';
+  const seeded = buildServerProfilesSeedEntries({ serverUrl, nowMs: 1234 });
+
+  assert.equal(seeded.serverId, '127.0.0.1-53288');
+  assert.deepEqual(seeded.sessionStorageEntries, [['activeServerId', '127.0.0.1-53288']]);
+
+  const storageEntry = seeded.localStorageEntries.find(([k]) => k.endsWith('\\server-state-v1')) ?? null;
+  assert.ok(storageEntry, 'expected a server-state-v1 entry under mmkv.server-profiles');
+  const [, value] = storageEntry;
+  const parsed = JSON.parse(value);
+  assert.equal(parsed.activeServerId, '127.0.0.1-53288');
+  assert.equal(parsed.activeServerIdIsExplicit, true);
+  assert.equal(parsed.servers['127.0.0.1-53288'].serverUrl, 'http://127.0.0.1:53288');
+});

package/scripts/release.mjs

@@ -1,7 +1,14 @@
 import { spawnSync } from "node:child_process";
+import { resolveCommandInvocation } from "./utils/process/resolveCommandInvocation.mjs";
 
 function run(cmd, args) {
-  const result = spawnSync(cmd, args, { stdio: "inherit" });
+  const invocation = resolveCommandInvocation({ command: cmd, args, env: process.env });
+  const result = spawnSync(invocation.command, invocation.args, {
+    stdio: "inherit",
+    ...(process.platform === "win32"
+      ? { windowsHide: true, windowsVerbatimArguments: invocation.windowsVerbatimArguments }
+      : null),
+  });
   if (result.error) throw result.error;
   if (typeof result.status === "number" && result.status !== 0) process.exit(result.status);
 }
@@ -26,7 +33,13 @@ const bump = args.find((a) => ["patch", "minor", "major"].includes(a));
 if (!bump) usageAndExit();
 
 // Ensure we're authenticated before doing anything that creates a version commit/tag.
-const whoami = spawnSync("npm", ["whoami"], { stdio: "ignore" });
+const whoamiInvocation = resolveCommandInvocation({ command: "npm", args: ["whoami"], env: process.env });
+const whoami = spawnSync(whoamiInvocation.command, whoamiInvocation.args, {
+  stdio: "ignore",
+  ...(process.platform === "win32"
+    ? { windowsHide: true, windowsVerbatimArguments: whoamiInvocation.windowsVerbatimArguments }
+    : null),
+});
 if (typeof whoami.status === "number" && whoami.status !== 0) {
   run("npm", ["login"]);
 }