@open-mercato/starter 0.6.5

package/README.md

@@ -0,0 +1,46 @@
+# @open-mercato/starter
+
+The central, cross-platform way to stand up an Open Mercato dev environment. One command, idempotent, platform-aware:
+
+```bash
+# Anywhere (clones the repo if you are not inside one):
+npx @open-mercato/starter
+
+# Inside a clone:
+yarn om                 # alias for node packages/starter/bin/om-start.mjs
+```
+
+No Node yet? The package ships pre-Node bootstraps that install a **portable, checksum-verified Node 24 without admin rights**, then run the CLI:
+
+- **Windows**: double-click `packages\starter\platform\start.cmd`, or `irm https://raw.githubusercontent.com/open-mercato/open-mercato/main/packages/starter/platform/start.ps1 | iex`
+- **macOS/Linux**: `./packages/starter/platform/start.sh`, or `curl -fsSL https://raw.githubusercontent.com/open-mercato/open-mercato/main/packages/starter/platform/start.sh | bash`
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `up` (default) | Idempotent converge + start: toolchain → container-runtime gate → corporate TLS trust → `.env`/secrets → `yarn install` → infra containers → database → supervised dev runtime. Re-running is always safe; completed steps are skipped. |
+| `up --detach` | Same, but the dev runtime keeps running in the background (pidfile-managed). |
+| `up --mode docker` | Everything containerized (for machines where host Node workloads are not allowed). Mode is remembered. |
+| `stop` | Stop the dev runtime and the infra containers (`--keep-infra`, `--volumes --yes`). |
+| `status` | Processes, containers, health, URLs. |
+| `logs [--follow]` | Tail the newest dev log. |
+| `doctor` | Read-only audit with per-item remediation and a **"hand this to IT" sheet** for admin-gated items. |
+| `reset` | Destructive cleanup (containers, volumes, starter state) — asks first. |
+| `infra up\|down` | Just the infra containers. |
+
+Useful flags: `--non-interactive`, `--skip-llm-prompt`, `--skip-db`, `--no-infra`, `--rebuild`, `--clean`, `--profile <name>`, `-- <args for yarn dev>`.
+
+`up --clean` forces a full re-converge: it clears the completed-step markers (install, build, migrations) and rebuilds the OpenCode service image, without touching any data — the one-time database seed stays done, and `reset` remains the destructive variant. Conversely, a plain `up` now also skips the database step entirely when the database is initialized and no `Migration*.ts` file changed since the last run (new migrations are detected by fingerprint and applied automatically).
+
+## Design rules
+
+- **Node stdlib only, no build step.** The CLI must run from a fresh clone before any `yarn install` — that is what makes it usable behind broken proxies.
+- **Install nothing system-level.** WSL2, Docker Desktop, and Rancher Desktop are detected and *proposed* (with exact commands and an IT handout), never installed. The starter installs only what it fully owns: portable Node (platform scripts), yarn via corepack, env files, CA bundles, repo state.
+- **Corporate TLS interception is a first-class citizen.** `up` probes real egress hosts, captures the interception CA (wire + Windows certificate store + vendor bundles like Netskope's), and provisions one PEM bundle everywhere: `NODE_EXTRA_CA_CERTS` + `--use-system-ca` for host tooling, `docker/certs/` + `docker/opencode/certs/` for image builds and container egress, a Rancher Desktop provisioning script for engine pulls. Prefer handing the starter your official bundle via `starters/company/config.mjs`.
+- **Probes use `127.0.0.1`, never `localhost`** (Windows resolves `localhost` to `::1` first).
+- **The clone's vendored starter wins.** `npx` defers to `packages/starter` inside the repo it operates on, so the starter version always matches the compose files it drives.
+
+## Company tailoring
+
+Organizations customize behavior (mirrors, CA bundles, extra checks/steps, env defaults) via `starters/company/config.mjs` in the repo — see `starters/company/README.md`. The package stays generic; the repo carries the policy.

package/bin/om-start.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// Central entry for every way of starting Open Mercato:
+//   npx @open-mercato/starter [command]   — anywhere; clones first if needed
+//   yarn om [command]                     — inside a clone
+//   packages/starter/platform/start.*     — pre-Node bootstrap wrappers
+//
+// This bin only solves "where is the repo?" (cloning when necessary) and
+// version skew (a clone's own vendored starter wins over the npx copy), then
+// defers every real decision to src/cli.mjs. Node stdlib only — it must run
+// on a fresh clone before any yarn install.
+import { spawn, spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { resolveRepoRoot } from '../src/compose.mjs'
+
+const REPO_URL = 'https://github.com/open-mercato/open-mercato.git'
+
+function extractBootstrapFlag(args, flag) {
+  const index = args.indexOf(flag)
+  if (index === -1 || index + 1 >= args.length) return null
+  const value = args[index + 1]
+  args.splice(index, 2)
+  return value
+}
+
+async function ensureRepo(args) {
+  const found = resolveRepoRoot()
+  if (found) return found
+
+  const dir = extractBootstrapFlag(args, '--dir') ?? path.join(process.cwd(), 'open-mercato')
+  const branch = extractBootstrapFlag(args, '--branch') ?? 'main'
+  if (fs.existsSync(path.join(dir, '.git'))) {
+    return resolveRepoRoot(dir)
+  }
+  const git = spawnSync('git', ['--version'], { stdio: 'ignore' })
+  if (git.error || git.status !== 0) {
+    console.error('❌ No Open Mercato checkout found here and git is not installed.')
+    console.error('   Install git, or clone manually and re-run this command inside the clone:')
+    console.error(`     git clone ${REPO_URL}`)
+    process.exit(2)
+  }
+  console.log(`No checkout found — cloning open-mercato (${branch}) into ${dir} ...`)
+  const clone = spawnSync('git', ['clone', '--branch', branch, REPO_URL, dir], { stdio: 'inherit' })
+  if (clone.status !== 0) {
+    console.error('❌ git clone failed. Behind a corporate proxy? Configure git first (ask IT for the proxy address):')
+    console.error('     git config --global http.proxy http://proxy.example.com:8080')
+    console.error('   On Windows also:  git config --global http.sslBackend schannel')
+    process.exit(clone.status ?? 1)
+  }
+  return resolveRepoRoot(dir)
+}
+
+async function main() {
+  const args = process.argv.slice(2)
+  const repoRoot = await ensureRepo(args)
+  if (!repoRoot) {
+    console.error('❌ Could not locate an Open Mercato repo root.')
+    process.exit(2)
+  }
+  process.chdir(repoRoot)
+
+  // Prefer the repo's own vendored starter (gradlew pattern): the clone knows
+  // which starter version matches its compose files and runtime contract.
+  const selfDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+  const vendored = path.join(repoRoot, 'packages', 'starter', 'bin', 'om-start.mjs')
+  if (fs.existsSync(vendored) && path.resolve(selfDir, 'bin', 'om-start.mjs') !== path.resolve(vendored)) {
+    const child = spawn(process.execPath, [vendored, ...args], { stdio: 'inherit', cwd: repoRoot })
+    child.on('close', (code) => process.exit(code ?? 0))
+    return
+  }
+
+  process.argv = [process.argv[0], process.argv[1], ...args]
+  await import('../src/cli.mjs')
+}
+
+await main()

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@open-mercato/starter",
+  "version": "0.6.5",
+  "description": "One-command, cross-platform bootstrap for Open Mercato dev environments: prerequisite doctor, corporate TLS trust, idempotent setup steps, and a supervised hybrid or fully containerized stack.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "om-start": "./bin/om-start.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "platform",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "test": "echo \"tested from the repo root jest suite\" && exit 0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-mercato/open-mercato",
+    "directory": "packages/starter"
+  }
+}

package/platform/start.cmd

@@ -0,0 +1,24 @@
+@echo off
+rem Open Mercato starter — double-click entry for Windows.
+rem Runs the PowerShell bootstrap next to this file, which guarantees Node 24
+rem (portable, no admin) and hands off to the cross-platform starter CLI.
+title Open Mercato Starter
+setlocal
+rem UTF-8 console first: cmd.exe decodes batch files with the code page it
+rem started with, and Yarn Berry's temp .cmd wrappers embed UTF-8 paths —
+rem OEM code pages mangle non-ASCII checkout paths into MODULE_NOT_FOUND.
+chcp 65001 >nul
+set "PS1=%~dp0start.ps1"
+if not exist "%PS1%" (
+  echo start.ps1 was not found next to this launcher.
+  pause
+  exit /b 1
+)
+powershell -NoProfile -ExecutionPolicy Bypass -File "%PS1%" %*
+set "RC=%ERRORLEVEL%"
+if not "%RC%"=="0" (
+  echo.
+  echo The starter exited with code %RC%. Review the messages above.
+  pause
+)
+endlocal & exit /b %RC%

package/platform/start.ps1

@@ -0,0 +1,174 @@
+# Open Mercato starter — Windows bootstrap.
+#
+# The only job of this script is to guarantee Node 24 — WITHOUT admin rights,
+# WITHOUT winget, and without touching machine state — then hand off to the
+# cross-platform starter CLI (packages/starter/bin/om-start.mjs), which does
+# everything else (doctor, corporate TLS trust, env/secrets, install, infra
+# containers, database, supervised dev runtime).
+#
+# Managed-device design notes:
+#   * Node is installed as a portable ZIP under %LOCALAPPDATA%\OpenMercato —
+#     no elevation, no MSI, no PATH pollution beyond this session.
+#   * Downloads go through Invoke-WebRequest (schannel), which trusts the
+#     Windows certificate store — GPO-deployed corporate interception CAs work
+#     out of the box.
+#   * The script avoids .NET static calls where possible and degrades with a
+#     clear message under AppLocker/WDAC Constrained Language Mode.
+#   * WSL2 / Docker Desktop / Rancher Desktop are NEVER installed here — the
+#     CLI detects and proposes them with an IT handout (doctor command).
+#
+# Inside a clone:  .\packages\starter\platform\start.ps1 [command] [flags]
+# Standalone:      irm https://raw.githubusercontent.com/open-mercato/open-mercato/main/packages/starter/platform/start.ps1 | iex
+#
+# Env: OM_NODE_DIST_MIRROR — base URL mirroring https://nodejs.org/dist.
+
+$ErrorActionPreference = 'Stop'
+
+# UTF-8 console first: cmd.exe decodes batch files with the code page captured
+# at its start, and Yarn Berry's temp .cmd wrappers embed absolute UTF-8 paths.
+# Under an OEM code page a non-ASCII checkout path (e.g. C:\Users\Michał) turns
+# into mojibake and installs/builds die with MODULE_NOT_FOUND. chcp.com is a
+# plain executable, so this stays Constrained-Language-Mode safe.
+try { & "$env:SystemRoot\System32\chcp.com" 65001 | Out-Null } catch { }
+
+$NodeMajor = 24
+$NodeDistBase = if ($env:OM_NODE_DIST_MIRROR) { $env:OM_NODE_DIST_MIRROR.TrimEnd('/') } else { 'https://nodejs.org/dist' }
+
+function Write-Info([string]$Message) { Write-Host "[starter] $Message" -ForegroundColor Cyan }
+function Write-Warn([string]$Message) { Write-Host "[starter] $Message" -ForegroundColor Yellow }
+function Fail([string]$Message) { Write-Host "[starter] $Message" -ForegroundColor Red; exit 1 }
+
+# Two-tone Open Mercato wordmark (7-bit ASCII — safe on conhost/OEM code pages).
+$LogoLeft = @(
+  '  ___  ____  _____ _   _ ',
+  ' / _ \|  _ \| ____| \ | |',
+  '| | | | |_) |  _| |  \| |',
+  '| |_| |  __/| |___| |\  |',
+  ' \___/|_|   |_____|_| \_|'
+)
+$LogoRight = @(
+  ' __  __ _____ ____   ____    _  _____ ___',
+  '|  \/  | ____|  _ \ / ___|  / \|_   _/ _ \',
+  '| |\/| |  _| | |_) | |     / _ \ | || | | |',
+  '| |  | | |___|  _ <| |___ / ___ \| || |_| |',
+  '|_|  |_|_____|_| \_\\____/_/   \_\_| \___/'
+)
+Write-Host ''
+for ($i = 0; $i -lt $LogoLeft.Count; $i++) {
+  Write-Host ("   {0}" -f $LogoLeft[$i]) -ForegroundColor DarkCyan -NoNewline
+  Write-Host ("  {0}" -f $LogoRight[$i]) -ForegroundColor Cyan
+}
+Write-Host ''
+Write-Host "   platform bootstrap - guarantees Node $NodeMajor (no admin), then hands off to the starter CLI" -ForegroundColor DarkGray
+Write-Host ''
+
+# Constrained Language Mode (AppLocker/WDAC): everything below sticks to
+# cmdlets and core types, but surface the state early so failures make sense.
+$languageMode = $ExecutionContext.SessionState.LanguageMode
+if ("$languageMode" -ne 'FullLanguage') {
+  Write-Warn "PowerShell runs in $languageMode (AppLocker/WDAC policy). Continuing with cmdlet-only operations; if this script is blocked, ask IT to allow it or run from an exempted path."
+}
+
+# PS 5.1 defaults can lack TLS 1.2 on older builds; a .NET static call is
+# blocked under CLM, so guard it — Windows 10/11 22H2 negotiate TLS 1.2 anyway.
+try { [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 } catch { }
+
+function Get-NodeMajor {
+  # Scoped EAP: under 'Stop', PS 5.1 turns node's stderr (e.g. a NODE_OPTIONS
+  # warning inherited from the environment) into a terminating error once
+  # 2>$null wraps it — which would misreport a working Node as missing.
+  try {
+    $previousPreference = $ErrorActionPreference
+    $ErrorActionPreference = 'Continue'
+    try {
+      $version = (& node -v) 2>$null
+    } finally {
+      $ErrorActionPreference = $previousPreference
+    }
+    if ("$version" -match 'v(\d+)\.') { return [int]$Matches[1] }
+  } catch { }
+  return 0
+}
+
+function Find-PortableNode {
+  $portableRoot = Join-Path $env:LOCALAPPDATA 'OpenMercato\node'
+  if (-not (Test-Path $portableRoot)) { return $null }
+  $candidate = Get-ChildItem -Path $portableRoot -Directory -Filter "node-v$NodeMajor.*" -ErrorAction SilentlyContinue |
+    Sort-Object Name -Descending | Select-Object -First 1
+  if ($candidate -and (Test-Path (Join-Path $candidate.FullName 'node.exe'))) { return $candidate.FullName }
+  return $null
+}
+
+function Install-PortableNode {
+  $arch = if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64') { 'arm64' } else { 'x64' }
+  Write-Info "Resolving latest Node $NodeMajor release ..."
+  $index = Invoke-RestMethod -Uri "$NodeDistBase/index.json" -UseBasicParsing
+  $release = $index | Where-Object { $_.version -match "^v$NodeMajor\." } | Select-Object -First 1
+  if (-not $release) { Fail "Could not resolve a Node $NodeMajor version from $NodeDistBase. Behind a proxy? Set HTTPS_PROXY, or point OM_NODE_DIST_MIRROR at an internal mirror." }
+  $version = $release.version
+  $zipName = "node-$version-win-$arch.zip"
+  $portableRoot = Join-Path $env:LOCALAPPDATA 'OpenMercato\node'
+  $tempDir = Join-Path $env:TEMP "open-mercato-starter"
+  New-Item -ItemType Directory -Force -Path $portableRoot | Out-Null
+  New-Item -ItemType Directory -Force -Path $tempDir | Out-Null
+  $zipPath = Join-Path $tempDir $zipName
+
+  Write-Info "Downloading $zipName (no admin required) ..."
+  Invoke-WebRequest -Uri "$NodeDistBase/$version/$zipName" -OutFile $zipPath -UseBasicParsing
+
+  Write-Info 'Verifying checksum ...'
+  $shasums = (Invoke-WebRequest -Uri "$NodeDistBase/$version/SHASUMS256.txt" -UseBasicParsing).Content
+  $expectedLine = $shasums -split "`n" | Where-Object { $_ -match [regex]::Escape($zipName) } | Select-Object -First 1
+  if (-not $expectedLine) { Fail "SHASUMS256.txt has no entry for $zipName." }
+  $expected = ($expectedLine -split '\s+')[0].Trim().ToLowerInvariant()
+  $actual = (Get-FileHash -Path $zipPath -Algorithm SHA256).Hash.ToLowerInvariant()
+  if ($expected -ne $actual) { Fail "Checksum verification FAILED for $zipName (expected $expected, got $actual). Refusing to continue." }
+
+  Write-Info "Extracting to $portableRoot ..."
+  Expand-Archive -Path $zipPath -DestinationPath $portableRoot -Force
+  Remove-Item $zipPath -Force -ErrorAction SilentlyContinue
+
+  $installed = Find-PortableNode
+  if (-not $installed) { Fail 'Portable Node extraction failed.' }
+  return $installed
+}
+
+if ((Get-NodeMajor) -ne $NodeMajor) {
+  $portable = Find-PortableNode
+  if (-not $portable) { $portable = Install-PortableNode }
+  $env:Path = "$portable;$env:Path"
+  Write-Warn "Using portable Node from $portable (PATH updated for this session)."
+  Write-Warn "Persist it for your own shells:  setx PATH `"$portable;%PATH%`""
+}
+if ((Get-NodeMajor) -ne $NodeMajor) { Fail "Node $NodeMajor is required (found: $(try { & node -v } catch { 'none' }))." }
+Write-Info "Node $(& node -v) ready"
+
+# Locate the repo: walk up from this script first (in-clone use), then from
+# the working directory (irm-standalone use).
+function Find-RepoRoot([string]$StartDir) {
+  $dir = $StartDir
+  while ($dir -and (Test-Path $dir)) {
+    if (Test-Path (Join-Path $dir 'starters\docker\compose.infra.yml')) { return $dir }
+    $parent = Split-Path -Parent $dir
+    if (-not $parent -or $parent -eq $dir) { return $null }
+    $dir = $parent
+  }
+  return $null
+}
+
+$repoRoot = $null
+if ($PSScriptRoot) { $repoRoot = Find-RepoRoot $PSScriptRoot }
+if (-not $repoRoot) { $repoRoot = Find-RepoRoot (Get-Location).Path }
+
+if ($repoRoot) {
+  & node (Join-Path $repoRoot 'packages\starter\bin\om-start.mjs') @args
+  exit $LASTEXITCODE
+}
+
+# Standalone: no clone yet — npx fetches the published starter, which clones
+# and continues. --use-system-ca keeps npm's TLS working behind corporate
+# interception (the GPO-deployed CA lives in the Windows store).
+Write-Info 'No checkout found — bootstrapping via npx @open-mercato/starter ...'
+$env:NODE_OPTIONS = "$($env:NODE_OPTIONS) --use-system-ca".Trim()
+& npx --yes '@open-mercato/starter' @args
+exit $LASTEXITCODE

package/platform/start.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# Open Mercato starter — macOS/Linux bootstrap.
+#
+# The only job of this script is to guarantee Node 24, then hand off to the
+# cross-platform starter CLI (packages/starter/bin/om-start.mjs), which does
+# everything else: doctor, corporate TLS trust, env/secrets, install, infra
+# containers, database, and the supervised dev runtime.
+#
+# Inside a clone:   ./packages/starter/platform/start.sh [command] [flags]
+# Standalone:       curl -fsSL https://raw.githubusercontent.com/open-mercato/open-mercato/main/packages/starter/platform/start.sh | bash
+#
+# Env: OM_NODE_DIST_MIRROR — base URL mirroring https://nodejs.org/dist for
+# proxy-blocked networks (defaults to the official CDN).
+set -euo pipefail
+
+NODE_MAJOR=24
+NODE_DIST_BASE="${OM_NODE_DIST_MIRROR:-https://nodejs.org/dist}"
+
+log()  { printf '\033[36m[starter]\033[0m %s\n' "$*"; }
+warn() { printf '\033[33m[starter]\033[0m %s\n' "$*" >&2; }
+fail() { printf '\033[31m[starter]\033[0m %s\n' "$*" >&2; exit 1; }
+
+# Two-tone Open Mercato wordmark (7-bit ASCII — safe on any terminal).
+if [ -t 1 ]; then
+  printf '\n'
+  printf '\033[2;36m   ___  ____  _____ _   _ \033[0m\033[36m  __  __ _____ ____   ____    _  _____ ___\033[0m\n'
+  printf '\033[2;36m  / _ \\|  _ \\| ____| \\ | |\033[0m\033[36m |  \\/  | ____|  _ \\ / ___|  / \\|_   _/ _ \\\033[0m\n'
+  printf '\033[2;36m | | | | |_) |  _| |  \\| |\033[0m\033[36m | |\\/| |  _| | |_) | |     / _ \\ | || | | |\033[0m\n'
+  printf '\033[2;36m | |_| |  __/| |___| |\\  |\033[0m\033[36m | |  | | |___|  _ <| |___ / ___ \\| || |_| |\033[0m\n'
+  printf '\033[2;36m  \\___/|_|   |_____|_| \\_|\033[0m\033[36m |_|  |_|_____|_| \\_\\\\____/_/   \\_\\_| \\___/\033[0m\n'
+  printf '\n   \033[2mplatform bootstrap - guarantees Node %s, then hands off to the starter CLI\033[0m\n\n' "$NODE_MAJOR"
+fi
+
+OS="$(uname -s)"
+case "$OS" in
+  Darwin|Linux) ;;
+  *) fail "Unsupported OS: $OS. On Windows run packages\\starter\\platform\\start.cmd instead." ;;
+esac
+
+ARCH="$(uname -m)"
+case "$ARCH" in
+  x86_64|amd64) NODE_ARCH="x64" ;;
+  arm64|aarch64) NODE_ARCH="arm64" ;;
+  *) fail "Unsupported CPU architecture: $ARCH" ;;
+esac
+
+node_major() { command -v node >/dev/null 2>&1 && node -p 'process.versions.node.split(".")[0]' 2>/dev/null || echo 0; }
+
+install_node() {
+  if [ "$OS" = "Darwin" ] && command -v brew >/dev/null 2>&1; then
+    log "Installing Node $NODE_MAJOR via Homebrew ..."
+    brew install "node@$NODE_MAJOR"
+    BREW_NODE="$(brew --prefix "node@$NODE_MAJOR")/bin"
+    export PATH="$BREW_NODE:$PATH"
+    warn "Added $BREW_NODE to PATH for this session — persist it in your shell profile."
+    return
+  fi
+  # Distro-agnostic official tarball into the user's home — no sudo, checksum
+  # verified. curl uses the system trust store, so a corporate CA deployed by
+  # IT is honored automatically.
+  NODE_PREFIX="$HOME/.local/share/open-mercato/node"
+  OS_SLUG=$([ "$OS" = "Darwin" ] && echo darwin || echo linux)
+  log "Resolving latest Node $NODE_MAJOR release ..."
+  NODE_VERSION="$(curl -fsSL "$NODE_DIST_BASE/index.json" | grep -o "\"v$NODE_MAJOR\.[0-9]*\.[0-9]*\"" | head -1 | tr -d '"')"
+  [ -n "$NODE_VERSION" ] || fail "Could not resolve a Node $NODE_MAJOR version from $NODE_DIST_BASE. Behind a proxy? Set HTTPS_PROXY, or point OM_NODE_DIST_MIRROR at an internal mirror."
+  TARBALL="node-$NODE_VERSION-$OS_SLUG-$NODE_ARCH.tar.gz"
+  TMP_DIR="$(mktemp -d)"
+  trap 'rm -rf "$TMP_DIR"' EXIT
+  log "Downloading $TARBALL ..."
+  curl -fsSL "$NODE_DIST_BASE/$NODE_VERSION/$TARBALL" -o "$TMP_DIR/$TARBALL"
+  curl -fsSL "$NODE_DIST_BASE/$NODE_VERSION/SHASUMS256.txt" -o "$TMP_DIR/SHASUMS256.txt"
+  (cd "$TMP_DIR" && { command -v sha256sum >/dev/null 2>&1 && grep " $TARBALL\$" SHASUMS256.txt | sha256sum -c - ; } || { command -v shasum >/dev/null 2>&1 && grep " $TARBALL\$" SHASUMS256.txt | shasum -a 256 -c - ; }) \
+    || fail "Checksum verification failed for $TARBALL."
+  mkdir -p "$NODE_PREFIX"
+  tar -xzf "$TMP_DIR/$TARBALL" -C "$NODE_PREFIX" --strip-components=1
+  export PATH="$NODE_PREFIX/bin:$PATH"
+  warn "Installed Node $NODE_VERSION to $NODE_PREFIX (PATH updated for this session)."
+  warn "Persist it:  export PATH=\"$NODE_PREFIX/bin:\$PATH\""
+}
+
+if [ "$(node_major)" -ne "$NODE_MAJOR" ]; then
+  install_node
+fi
+[ "$(node_major)" -eq "$NODE_MAJOR" ] || fail "Node $NODE_MAJOR is required (found $(node -v 2>/dev/null || echo none))."
+log "Node $(node -v) ready"
+
+# Locate the repo: walk up from this script first (in-clone use), then from
+# the working directory (curl-standalone use).
+find_root_from() {
+  local dir="$1"
+  while [ "$dir" != "/" ]; do
+    if [ -f "$dir/starters/docker/compose.infra.yml" ]; then
+      printf '%s' "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" 2>/dev/null && pwd || pwd)"
+REPO_ROOT="$(find_root_from "$SCRIPT_DIR" || find_root_from "$PWD" || true)"
+
+if [ -n "${REPO_ROOT:-}" ]; then
+  exec node "$REPO_ROOT/packages/starter/bin/om-start.mjs" "$@"
+fi
+
+# Standalone: no clone yet — npx fetches the published starter, which clones
+# and continues. --use-system-ca keeps this working behind corporate TLS
+# interception when the CA is in the system store.
+log "No checkout found — bootstrapping via npx @open-mercato/starter ..."
+NODE_OPTIONS="${NODE_OPTIONS:-} --use-system-ca" exec npx --yes @open-mercato/starter "$@"