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

package/scripts/provision/linux-ubuntu-provision.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Provision an Ubuntu machine with *dependencies only* so you can install/run Happier tools manually.
+# This script intentionally does NOT install Happier/hstack itself.
+#
+# Intended usage (inside a VM):
+#   curl -fsSL https://raw.githubusercontent.com/happier-dev/happier/main/apps/stack/scripts/provision/linux-ubuntu-provision.sh -o /tmp/linux-ubuntu-provision.sh \
+#     && chmod +x /tmp/linux-ubuntu-provision.sh \
+#     && /tmp/linux-ubuntu-provision.sh --profile=happier
+#
+# Profiles:
+# - happier   : build tools + Node + Corepack/Yarn (default)
+# - installer : minimal base tooling (curl/ca-certs) to test the official installer on a mostly-empty box
+# - bare      : do nothing (useful if you explicitly want an unprovisioned VM)
+#
+# Env overrides:
+# - HAPPIER_PROVISION_NODE_MAJOR (default: 24)
+# - HAPPIER_PROVISION_YARN_VERSION (default: 1.22.22)
+
+usage() {
+  cat <<'EOF'
+Usage:
+  ./linux-ubuntu-provision.sh [--profile=happier|installer|bare]
+
+Examples:
+  ./linux-ubuntu-provision.sh --profile=happier
+  ./linux-ubuntu-provision.sh --profile=installer
+  ./linux-ubuntu-provision.sh --profile=bare
+EOF
+}
+
+PROFILE="happier"
+for arg in "$@"; do
+  case "$arg" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --profile=*)
+      PROFILE="${arg#--profile=}"
+      ;;
+    *)
+      echo "[provision] unknown argument: ${arg}" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+require_cmd() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+as_root() {
+  if [[ "$(id -u)" == "0" ]]; then
+    "$@"
+    return
+  fi
+  if require_cmd sudo; then
+    sudo "$@"
+    return
+  fi
+  echo "[provision] missing sudo; re-run as root" >&2
+  exit 1
+}
+
+say() {
+  echo ""
+  echo "[provision] $*"
+}
+
+NODE_MAJOR="${HAPPIER_PROVISION_NODE_MAJOR:-24}"
+YARN_VERSION="${HAPPIER_PROVISION_YARN_VERSION:-1.22.22}"
+
+case "${PROFILE}" in
+  happier|installer|bare) ;;
+  *)
+    echo "[provision] invalid --profile: ${PROFILE}" >&2
+    usage >&2
+    exit 2
+    ;;
+esac
+
+if [[ "${PROFILE}" == "bare" ]]; then
+  say "profile=bare (no changes)"
+  echo ""
+  echo "[provision] done."
+  exit 0
+fi
+
+say "updating apt"
+as_root apt-get update -y
+
+if [[ "${PROFILE}" == "installer" ]]; then
+  say "installing minimal packages (installer profile)"
+  as_root apt-get install -y --no-install-recommends \
+    ca-certificates \
+    curl \
+    xz-utils
+  echo ""
+  echo "[provision] done."
+  echo ""
+  echo "Next (example):"
+  echo "  curl -fsSL https://happier.dev/install | bash"
+  exit 0
+fi
+
+say "installing base packages"
+as_root apt-get install -y --no-install-recommends \
+  ca-certificates \
+  curl \
+  git \
+  gnupg \
+  jq \
+  xz-utils \
+  build-essential \
+  python3
+
+if ! require_cmd node; then
+  say "installing Node.js (NodeSource ${NODE_MAJOR}.x)"
+  as_root bash -lc "curl -fsSL https://deb.nodesource.com/setup_${NODE_MAJOR}.x | bash -"
+  as_root apt-get install -y nodejs
+fi
+
+say "node: $(node --version)"
+
+if ! require_cmd corepack; then
+  echo "[provision] corepack not found (expected with Node >=16)." >&2
+  exit 1
+fi
+
+say "enabling Corepack shims (root)"
+as_root corepack enable
+
+say "preparing Yarn ${YARN_VERSION} (root; system cache)"
+as_root mkdir -p /usr/local/share/corepack
+as_root env COREPACK_HOME=/usr/local/share/corepack corepack prepare "yarn@${YARN_VERSION}" --activate
+
+say "yarn: $(yarn --version)"
+
+echo ""
+echo "[provision] done."
+echo ""
+echo "Next:"
+echo "  npx --yes -p @happier-dev/stack@latest hstack setup --profile=dev --bind=loopback"
+

package/scripts/provision/linux-ubuntu-provision.test.mjs

@@ -0,0 +1,163 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, writeFile, chmod, readFile } 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 readIfExists(path) {
+  try {
+    return await readFile(path, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+test('linux provision (happier profile) runs corepack enable as root', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'hstack-linux-provision-test-'));
+  const binDir = join(root, 'bin');
+  const logDir = join(root, 'logs');
+  const { mkdir } = await import('node:fs/promises');
+  await mkdir(binDir, { recursive: true });
+  await mkdir(logDir, { recursive: true });
+
+  const corepackLog = join(logDir, 'corepack.log');
+  const aptLog = join(logDir, 'apt.log');
+
+  const idPath = join(binDir, 'id');
+  await writeFile(
+    idPath,
+    ['#!/usr/bin/env bash', 'if [[ "${1:-}" == "-u" ]]; then echo 1000; else echo "uid=1000"; fi'].join('\n') + '\n',
+    'utf-8'
+  );
+  await chmod(idPath, 0o755);
+
+  const sudoPath = join(binDir, 'sudo');
+  await writeFile(
+    sudoPath,
+    ['#!/usr/bin/env bash', 'export RUN_AS_ROOT=1', 'exec "$@"'].join('\n') + '\n',
+    'utf-8'
+  );
+  await chmod(sudoPath, 0o755);
+
+  const aptPath = join(binDir, 'apt-get');
+  await writeFile(
+    aptPath,
+    [
+      '#!/usr/bin/env bash',
+      `echo "apt-get $*" >> ${JSON.stringify(aptLog)}`,
+      'exit 0',
+    ].join('\n') + '\n',
+    'utf-8'
+  );
+  await chmod(aptPath, 0o755);
+
+  const mkdirPath = join(binDir, 'mkdir');
+  await writeFile(
+    mkdirPath,
+    [
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      'for a in "$@"; do',
+      '  if [[ "$a" == "/usr/local/share/corepack" ]]; then',
+      '    exit 0',
+      '  fi',
+      'done',
+      'exec /bin/mkdir "$@"',
+    ].join('\n') + '\n',
+    'utf-8'
+  );
+  await chmod(mkdirPath, 0o755);
+
+  const nodePath = join(binDir, 'node');
+  await writeFile(nodePath, ['#!/usr/bin/env bash', 'echo "v24.0.0"'].join('\n') + '\n', 'utf-8');
+  await chmod(nodePath, 0o755);
+
+  const corepackPath = join(binDir, 'corepack');
+  await writeFile(
+    corepackPath,
+    [
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      'echo "corepack $* root=${RUN_AS_ROOT:-0}" >> ' + JSON.stringify(corepackLog),
+      'if [[ "${1:-}" == "enable" && "${RUN_AS_ROOT:-0}" != "1" ]]; then',
+      '  echo "enable must run as root" >&2',
+      '  exit 13',
+      'fi',
+      'exit 0',
+    ].join('\n') + '\n',
+    'utf-8'
+  );
+  await chmod(corepackPath, 0o755);
+
+  const yarnPath = join(binDir, 'yarn');
+  await writeFile(yarnPath, ['#!/usr/bin/env bash', 'echo "1.22.22"'].join('\n') + '\n', 'utf-8');
+  await chmod(yarnPath, 0o755);
+
+  const scriptPath = join(__dirname, 'linux-ubuntu-provision.sh');
+  const res = spawnSync('bash', [scriptPath, '--profile=happier'], {
+    cwd: root,
+    env: { ...process.env, PATH: `${binDir}:${process.env.PATH ?? ''}` },
+    encoding: 'utf-8',
+  });
+
+  assert.equal(res.status, 0, `expected exit 0\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const corepackOut = await readIfExists(corepackLog);
+  assert.match(corepackOut, /corepack enable root=1/, 'expected corepack enable to be invoked via sudo/as_root');
+  assert.ok(!corepackOut.includes('corepack enable root=0'), 'expected corepack enable not to run unprivileged');
+
+  const aptOut = await readIfExists(aptLog);
+  assert.match(aptOut, /apt-get update/, 'expected apt-get update to run');
+  assert.match(aptOut, /apt-get install/, 'expected apt-get install to run');
+});
+
+test('linux provision (installer profile) does not touch node/corepack', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'hstack-linux-provision-installer-test-'));
+  const binDir = join(root, 'bin');
+  const logDir = join(root, 'logs');
+  const { mkdir } = await import('node:fs/promises');
+  await mkdir(binDir, { recursive: true });
+  await mkdir(logDir, { recursive: true });
+
+  const corepackLog = join(logDir, 'corepack.log');
+
+  const idPath = join(binDir, 'id');
+  await writeFile(idPath, ['#!/usr/bin/env bash', 'echo 1000'].join('\n') + '\n', 'utf-8');
+  await chmod(idPath, 0o755);
+
+  const sudoPath = join(binDir, 'sudo');
+  await writeFile(sudoPath, ['#!/usr/bin/env bash', 'export RUN_AS_ROOT=1', 'exec "$@"'].join('\n') + '\n', 'utf-8');
+  await chmod(sudoPath, 0o755);
+
+  const aptPath = join(binDir, 'apt-get');
+  await writeFile(aptPath, ['#!/usr/bin/env bash', 'exit 0'].join('\n') + '\n', 'utf-8');
+  await chmod(aptPath, 0o755);
+
+  const corepackPath = join(binDir, 'corepack');
+  await writeFile(
+    corepackPath,
+    [
+      '#!/usr/bin/env bash',
+      `echo "corepack $*" >> ${JSON.stringify(corepackLog)}`,
+      'exit 0',
+    ].join('\n') + '\n',
+    'utf-8'
+  );
+  await chmod(corepackPath, 0o755);
+
+  const scriptPath = join(__dirname, 'linux-ubuntu-provision.sh');
+  const res = spawnSync('bash', [scriptPath, '--profile=installer'], {
+    cwd: root,
+    env: { ...process.env, PATH: `${binDir}:${process.env.PATH ?? ''}` },
+    encoding: 'utf-8',
+  });
+
+  assert.equal(res.status, 0, `expected exit 0\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+
+  const corepackOut = await readIfExists(corepackLog);
+  assert.equal(corepackOut.trim(), '', 'expected no corepack calls in installer profile');
+});

package/scripts/provision/macos-lima-hstack-smoke.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Automated Lima VM smoke test runner for hstack.
+#
+# Usage (macOS host):
+#   ./scripts/provision/macos-lima-hstack-smoke.sh [vm-name]
+#
+# Env:
+#   HSTACK_VERSION=latest            # @happier-dev/stack version to test (default: latest)
+#   HSTACK_SMOKE_KEEP=1              # keep sandbox dir in the VM (default: 0)
+#   HSTACK_RAW_BASE=...              # override raw github base (default: happier-dev/happier main)
+#   HSTACK_PROVISION_PROFILE=happier # guest provisioning profile (default: happier)
+#
+# This script:
+# - creates/configures a Lima VM (via macos-lima-vm.sh)
+# - provisions dependencies inside the VM (linux-ubuntu-provision.sh)
+# - runs a sandboxed `hstack` smoke test inside the VM (linux-ubuntu-hstack-smoke.sh)
+
+usage() {
+  cat <<'EOF'
+Usage:
+  ./scripts/provision/macos-lima-hstack-smoke.sh [vm-name]
+
+Examples:
+  ./scripts/provision/macos-lima-hstack-smoke.sh
+  HSTACK_VERSION=latest ./scripts/provision/macos-lima-hstack-smoke.sh happy-e2e
+EOF
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+if [[ "$(uname -s)" != "Darwin" ]]; then
+  echo "[lima-smoke] expected macOS (Darwin); got: $(uname -s)" >&2
+  exit 1
+fi
+
+if ! command -v limactl >/dev/null 2>&1; then
+  echo "[lima-smoke] limactl not found. Install Lima first (example: brew install lima)." >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+VM_NAME="${1:-happy-e2e}"
+
+HSTACK_VERSION="${HSTACK_VERSION:-latest}"
+HSTACK_SMOKE_KEEP="${HSTACK_SMOKE_KEEP:-0}"
+HSTACK_PROVISION_PROFILE="${HSTACK_PROVISION_PROFILE:-happier}"
+
+pick_raw_base() {
+  if [[ -n "${HSTACK_RAW_BASE:-}" ]]; then
+    echo "${HSTACK_RAW_BASE}"
+    return 0
+  fi
+  local candidates=(
+    "https://raw.githubusercontent.com/happier-dev/happier/main/apps/stack"
+  )
+  local c
+  for c in "${candidates[@]}"; do
+    if curl -fsSL "${c}/scripts/provision/linux-ubuntu-provision.sh" -o /dev/null >/dev/null 2>&1; then
+      echo "$c"
+      return 0
+    fi
+  done
+  return 1
+}
+
+HSTACK_RAW_BASE="$(pick_raw_base || true)"
+if [[ -z "${HSTACK_RAW_BASE}" ]]; then
+  echo "[lima-smoke] failed to auto-detect raw GitHub base URL for scripts." >&2
+  echo "[lima-smoke] Fix: set HSTACK_RAW_BASE=https://raw.githubusercontent.com/<org>/<repo>/<ref>/apps/stack" >&2
+  exit 1
+fi
+
+echo "[lima-smoke] vm: ${VM_NAME}"
+echo "[lima-smoke] @happier-dev/stack: ${HSTACK_VERSION}"
+echo "[lima-smoke] provision profile: ${HSTACK_PROVISION_PROFILE}"
+echo "[lima-smoke] raw base: ${HSTACK_RAW_BASE}"
+
+echo "[lima-smoke] ensure VM exists + port forwarding..."
+"${SCRIPT_DIR}/macos-lima-vm.sh" "${VM_NAME}"
+
+echo "[lima-smoke] running provisioning + smoke inside VM..."
+limactl shell "${VM_NAME}" -- bash -lc "
+  set -euo pipefail
+  echo '[vm] downloading provision + smoke scripts...'
+  curl -fsSL '${HSTACK_RAW_BASE}/scripts/provision/linux-ubuntu-provision.sh' -o /tmp/linux-ubuntu-provision.sh
+  chmod +x /tmp/linux-ubuntu-provision.sh
+  /tmp/linux-ubuntu-provision.sh --profile='${HSTACK_PROVISION_PROFILE}'
+
+  curl -fsSL '${HSTACK_RAW_BASE}/scripts/provision/linux-ubuntu-hstack-smoke.sh' -o /tmp/linux-ubuntu-hstack-smoke.sh
+  chmod +x /tmp/linux-ubuntu-hstack-smoke.sh
+
+  export HSTACK_VERSION='${HSTACK_VERSION}'
+  export HSTACK_SMOKE_KEEP='${HSTACK_SMOKE_KEEP}'
+  /tmp/linux-ubuntu-hstack-smoke.sh
+"
+
+echo ""
+echo "[lima-smoke] done."
+

package/scripts/provision/macos-lima-vm.sh

@@ -0,0 +1,257 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Create/configure a Lima VM for running Happier stack flows in a clean Linux environment,
+# while keeping Expo web URLs openable on the macOS host via localhost port forwarding
+# (required for WebCrypto/secure-context APIs).
+#
+# Usage (macOS host):
+#   ./scripts/provision/macos-lima-vm.sh [vm-name]
+#
+# Env overrides:
+# - LIMA_TEMPLATE (default: ubuntu-24.04)
+# - LIMA_MEMORY (default: 8GiB)
+# - LIMA_VM_TYPE (optional: vz|qemu|krunkit)
+# - HAPPIER_LIMA_STACK_PORT_RANGE (default: 13000-13999)
+# - HAPPIER_LIMA_EXPO_PORT_RANGE  (default: 18000-19099)
+
+usage() {
+  cat <<'EOF'
+Usage:
+  ./scripts/provision/macos-lima-vm.sh [vm-name]
+
+Examples:
+  ./scripts/provision/macos-lima-vm.sh
+  ./scripts/provision/macos-lima-vm.sh happy-e2e
+
+Notes:
+- Run on macOS (Darwin) host.
+- Configures localhost port forwarding so you can open http://localhost / http://*.localhost
+  in your macOS browser (required for WebCrypto APIs used by Expo web).
+EOF
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+if [[ "$(uname -s)" != "Darwin" ]]; then
+  echo "[lima] expected macOS (Darwin); got: $(uname -s)" >&2
+  exit 1
+fi
+
+if ! command -v limactl >/dev/null 2>&1; then
+  echo "[lima] limactl not found. Install Lima first (example: brew install lima)." >&2
+  exit 1
+fi
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "[lima] python3 not found. Install Python 3 to edit Lima YAML." >&2
+  exit 1
+fi
+
+VM_NAME="${1:-happy-test}"
+TEMPLATE="${LIMA_TEMPLATE:-ubuntu-24.04}"
+LIMA_MEMORY="${LIMA_MEMORY:-8GiB}"
+LIMA_VM_TYPE="${LIMA_VM_TYPE:-}" # optional: vz|qemu|krunkit (see: limactl create --list-drivers)
+
+STACK_PORT_RANGE="${HAPPIER_LIMA_STACK_PORT_RANGE:-13000-13999}"
+EXPO_PORT_RANGE="${HAPPIER_LIMA_EXPO_PORT_RANGE:-18000-19099}"
+
+TEMPLATE_LOCATOR="${TEMPLATE}"
+if [[ "${TEMPLATE_LOCATOR}" == template://* ]]; then
+  TEMPLATE_LOCATOR="template:${TEMPLATE_LOCATOR#template://}"
+elif [[ "${TEMPLATE_LOCATOR}" != template:* ]]; then
+  TEMPLATE_LOCATOR="template:${TEMPLATE_LOCATOR}"
+fi
+
+LIMA_HOME_DIR="${LIMA_HOME:-${HOME}/.lima}"
+export LIMA_HOME="${LIMA_HOME_DIR}"
+LIMA_DIR="${LIMA_HOME_DIR}/${VM_NAME}"
+LIMA_YAML="${LIMA_DIR}/lima.yaml"
+
+echo "[lima] vm: ${VM_NAME}"
+echo "[lima] template: ${TEMPLATE}"
+echo "[lima] memory: ${LIMA_MEMORY} (override with LIMA_MEMORY=...)"
+echo "[lima] stack ports: ${STACK_PORT_RANGE}"
+echo "[lima] expo ports:  ${EXPO_PORT_RANGE}"
+echo "[lima] LIMA_HOME: ${LIMA_HOME_DIR}"
+if [[ -n "${LIMA_VM_TYPE}" ]]; then
+  echo "[lima] vmType: ${LIMA_VM_TYPE}"
+fi
+
+if [[ ! -f "${LIMA_YAML}" ]]; then
+  echo "[lima] creating VM..."
+  if [[ "${LIMA_VM_TYPE}" == "qemu" ]]; then
+    if ! command -v qemu-system-aarch64 >/dev/null 2>&1; then
+      echo "[lima] qemu vmType requested but qemu-system-aarch64 is missing." >&2
+      echo "[lima] Fix: brew install qemu" >&2
+      exit 1
+    fi
+  fi
+
+  create_args=(create --name "${VM_NAME}" --tty=false)
+  if [[ -n "${LIMA_VM_TYPE}" ]]; then
+    create_args+=(--vm-type "${LIMA_VM_TYPE}")
+  fi
+  create_args+=("${TEMPLATE_LOCATOR}")
+  limactl "${create_args[@]}"
+fi
+
+if [[ ! -f "${LIMA_YAML}" ]]; then
+  echo "[lima] expected instance config at: ${LIMA_YAML}" >&2
+  exit 1
+fi
+
+echo "[lima] stopping VM (if running)..."
+limactl stop "${VM_NAME}" >/dev/null 2>&1 || true
+
+echo "[lima] configuring port forwarding (localhost)..."
+cp -a "${LIMA_YAML}" "${LIMA_YAML}.bak.$(date +%Y%m%d-%H%M%S)"
+
+VM_NAME="${VM_NAME}" \
+LIMA_YAML="${LIMA_YAML}" \
+LIMA_MEMORY="${LIMA_MEMORY}" \
+STACK_PORT_RANGE="${STACK_PORT_RANGE}" \
+EXPO_PORT_RANGE="${EXPO_PORT_RANGE}" \
+python3 - <<'PY'
+import os, re
+from pathlib import Path
+
+vm_name = os.environ["VM_NAME"]
+path = Path(os.environ["LIMA_YAML"])
+memory = os.environ.get("LIMA_MEMORY", "8GiB")
+
+def parse_range(s: str):
+  m = re.match(r"^\s*(\d+)\s*-\s*(\d+)\s*$", s or "")
+  if not m:
+    raise SystemExit(f"invalid port range: {s!r} (expected like 13000-13999)")
+  a = int(m.group(1))
+  b = int(m.group(2))
+  if a <= 0 or b <= 0 or b < a:
+    raise SystemExit(f"invalid port range: {s!r}")
+  return a, b
+
+stack_a, stack_b = parse_range(os.environ.get("STACK_PORT_RANGE", "13000-13999"))
+expo_a, expo_b = parse_range(os.environ.get("EXPO_PORT_RANGE", "18000-19099"))
+
+text = path.read_text(encoding="utf-8")
+
+MEM_MARK_BEGIN = "# --- happier vm sizing (managed) ---"
+MEM_MARK_END = "# --- /happier vm sizing ---"
+MARK_BEGIN = "# --- happier port forwards (managed) ---"
+MARK_END = "# --- /happier port forwards ---"
+
+entries = [
+  f"  - guestPortRange: [{stack_a}, {stack_b}]\n    hostPortRange:  [{stack_a}, {stack_b}]\n",
+  f"  - guestPortRange: [{expo_a}, {expo_b}]\n    hostPortRange:  [{expo_a}, {expo_b}]\n",
+]
+
+mem_block = (
+  f"\n{MEM_MARK_BEGIN}\n"
+  f'memory: "{memory}"\n'
+  f"{MEM_MARK_END}\n"
+)
+
+block_as_section = (
+  f"\n{MARK_BEGIN}\n"
+  "portForwards:\n"
+  + "".join(entries) +
+  f"{MARK_END}\n"
+)
+
+block_as_list_items = (
+  f"  {MARK_BEGIN}\n"
+  + "".join(entries) +
+  f"  {MARK_END}\n"
+)
+
+if MEM_MARK_BEGIN in text and MEM_MARK_END in text:
+  text = re.sub(
+    re.escape(MEM_MARK_BEGIN) + r"[\s\S]*?" + re.escape(MEM_MARK_END) + r"\n?",
+    mem_block.strip("\n") + "\n",
+    text,
+    flags=re.MULTILINE,
+  )
+else:
+  m = re.search(r"^memory:\s*.*$", text, flags=re.MULTILINE)
+  if m:
+    text = re.sub(r"^memory:\s*.*$", f'memory: "{memory}"', text, flags=re.MULTILINE)
+  else:
+    text = text.rstrip() + mem_block
+
+if MARK_BEGIN in text and MARK_END in text:
+  text = re.sub(
+    re.escape(MARK_BEGIN) + r"[\s\S]*?" + re.escape(MARK_END) + r"\n?",
+    block_as_section.strip("\n") + "\n",
+    text,
+    flags=re.MULTILINE,
+  )
+else:
+  m = re.search(r"^portForwards:\s*$", text, flags=re.MULTILINE)
+  if m:
+    insert_at = m.end()
+    text = text[:insert_at] + "\n" + block_as_list_items + text[insert_at:]
+  else:
+    text = text.rstrip() + block_as_section
+
+path.write_text(text, encoding="utf-8")
+print(f"[lima] updated {path} ({vm_name})")
+PY
+
+echo "[lima] starting VM..."
+limactl start "${VM_NAME}"
+
+echo ""
+echo "[lima] done."
+echo ""
+echo "What this script did:"
+echo "  - ensured the VM exists (${VM_NAME})"
+echo "  - set VM memory (${LIMA_MEMORY})"
+echo "  - configured localhost port forwarding:"
+echo "      - stack/server: ${STACK_PORT_RANGE}"
+echo "      - Expo (web):   ${EXPO_PORT_RANGE}"
+echo ""
+echo "Next step (enter the VM):"
+printf "  limactl shell %s\n" "${VM_NAME}"
+echo ""
+cat <<'EOF'
+Inside the VM: choose a provisioning profile (dependencies only)
+
+Profile `happier` (recommended for most manual testing):
+  - Installs: build tools + git + Node + Corepack/Yarn.
+  - Use when: you want to run `npx ... hstack ...` and iterate quickly without relying on the official installer.
+  - Run:
+      curl -fsSL https://raw.githubusercontent.com/happier-dev/happier/main/apps/stack/scripts/provision/linux-ubuntu-provision.sh -o /tmp/linux-ubuntu-provision.sh \
+        && chmod +x /tmp/linux-ubuntu-provision.sh \
+        && /tmp/linux-ubuntu-provision.sh --profile=happier
+
+Profile `installer` (clean-machine installer validation):
+  - Installs: minimal tooling only (curl/ca-certs/etc). DOES NOT install Node/Yarn.
+  - Use when: you want to validate the “fresh box” experience via the official installer.
+  - Run:
+      curl -fsSL https://raw.githubusercontent.com/happier-dev/happier/main/apps/stack/scripts/provision/linux-ubuntu-provision.sh -o /tmp/linux-ubuntu-provision.sh \
+        && chmod +x /tmp/linux-ubuntu-provision.sh \
+        && /tmp/linux-ubuntu-provision.sh --profile=installer
+      # Then run the official installer:
+      curl -fsSL https://happier.dev/install | bash
+
+Profile `bare` (no changes at all):
+  - Installs: nothing.
+  - Use when: you want a totally untouched VM and will install everything yourself (or validate your own bootstrap flow).
+  - Run:
+      /tmp/linux-ubuntu-provision.sh --profile=bare
+
+After provisioning (common next commands):
+  - Dev monorepo wizard (clones + bootstraps a workspace):
+      npx --yes -p @happier-dev/stack@latest hstack setup --profile=dev --bind=loopback
+  - Selfhost (lighter; good for quickly validating server/UI boot without auth):
+      npx --yes -p @happier-dev/stack@latest hstack setup --profile=selfhost --no-auth --no-tailscale --no-autostart --no-menubar --bind=loopback
+
+Tips:
+  - Open printed URLs on your macOS host via http://localhost:<port> or http://*.localhost:<port>.
+  - For `npx --yes -p @happier-dev/stack hstack tools review-pr ...` inside the VM, pass `--vm-ports` so stack ports land in the forwarded ranges.
+  - Override guest provision versions (profile=happier):
+      HAPPIER_PROVISION_NODE_MAJOR=24 HAPPIER_PROVISION_YARN_VERSION=1.22.22 /tmp/linux-ubuntu-provision.sh --profile=happier
+EOF