@liustack/modlens 2.8.0 → 3.1.0

package/skills/modlens/references/runtime.md

@@ -0,0 +1,95 @@
+# modlens runtime reference
+
+How the skill launches the `modlens` CLI, what version it pins, and how it
+diagnoses a machine where nothing can run. The launchers `scripts/run.sh`
+(macOS / Linux) and `scripts/run.ps1` (Windows) implement everything below and
+must stay byte-for-byte identical apart from their version constants and their
+shell syntax.
+
+## Pinned version
+
+- Pinned CLI version: 3.1.0
+- npm package: `@liustack/modlens`
+- CLI binary name: `modlens`
+
+The pinned version line above and the constants inside both launchers are
+stamped by `scripts/release.mjs` at release time from `package.json`. Do not
+edit them by hand. `scripts/stamp.test.mjs` fails the build if the three
+launcher/reference copies ever drift from `package.json`.
+
+## Resolution order
+
+Each call resolves a way to run the CLI, in this order:
+
+1. **A compatible `modlens` already on `PATH`** — run it directly, by name.
+2. **`npx` present** — `npx --yes --package @liustack/modlens@<pinned> modlens <args>`.
+3. **`bunx` present** — `bunx --bun @liustack/modlens@<pinned> <args>`.
+4. **A native artifact** — reserved for phase B. None is published yet, so this
+   branch reports `nativeArtifact.available: false` and moves on.
+5. **Nothing usable** — print a structured diagnosis and exit `78` (`EX_CONFIG`).
+
+The launcher forwards stdin, stdout, stderr, and the exit code unchanged, so the
+CLI's JSON output contract is identical however it was launched.
+
+## Compatibility rule
+
+A `modlens` found on `PATH` counts as compatible only when it is **the same
+major version as the pinned version and not older than it**. Same major keeps a
+user who already installed a matching CLI from being forced through an `npx`
+re-download (the "no regression" requirement in the design). Not-older refuses a
+stale global build that predates the version this skill was written against; in
+that case the launcher skips `PATH` and uses the pinned `npx` / `bunx` version
+instead.
+
+## Cache and permissions (phase B, not active yet)
+
+Phase A never downloads anything. When native artifacts land in phase B, the
+launchers will cache them per user, keyed by version, and launch them by
+absolute path:
+
+- macOS: `~/Library/Caches/liustack/modlens/<version>/`
+- Linux: `${XDG_CACHE_HOME:-$HOME/.cache}/liustack/modlens/<version>/`
+- Windows: `%LOCALAPPDATA%\liustack\modlens\<version>\`
+
+With these constraints: no `sudo` or admin rights, no system directories, no
+`PATH` edits, download to a temp file and verify SHA-256 before an atomic move,
+and keep no unverified executable on failure. Any download uses `curl` (on
+Windows, `curl.exe` written in full), which does not stamp quarantine or
+Mark-of-the-Web, and the launcher never removes a security marker a browser
+would have set.
+
+## Diagnostic fields
+
+`run.sh doctor --json` (and `run.ps1 doctor --json`) print this shape:
+
+- `tool`, `package`, `pinnedVersion` — what this skill targets.
+- `os`, `arch` — normalized host identity (`darwin` / `linux` / `windows`,
+  `arm64` / `x64`).
+- `checked.pathCli` — `{ present, path, version, compatible }` for a `modlens`
+  on `PATH`, with `compatible` applying the rule above.
+- `checked.npx`, `checked.bunx` — `{ present, path }` visibility of each runner.
+- `checked.node` — `{ present, version }`.
+- `nativeArtifact` — `{ available, note }`; `available` is `false` in phase A.
+- `selected` — the resolved path: `path`, `npx`, `bunx`, or `none`.
+- `nextSteps` — when `selected` is `none`, one or two plain-language actions for
+  the user (install Node 22.13+, or Bun); empty otherwise.
+- `cliDoctor` — when a CLI is resolvable, the CLI's own `doctor --json` report
+  (provider, config, and harness diagnosis) is nested here; `null` otherwise.
+
+`doctor` is offline and spends no quota: it inspects the local environment and,
+when it can, chains the CLI's own offline `doctor`. It makes no network request
+of its own.
+
+## Delivery form: local CLI, long term
+
+modlens stays a local CLI on purpose, and section 10 of the distribution design
+(move capabilities to a remote MCP when they need no local execution) does
+**not** apply to it. The reasons are the product itself: the vision-provider key
+is held on the user's machine, the quota billed is the user's own, and there is
+no central service in the middle. modlens also reads local files directly. Its
+`recover-paste` pulls pasted images out of the harness's own session storage on
+disk, which a remote service structurally cannot reach. A hosted MCP would move
+the key and the quota off the user's machine and still could not see those local
+files, which is the opposite of what this tool is for. Phase D may retire native
+artifacts for some future tool, but modlens keeps its local-CLI form for as long
+as those properties hold.

package/skills/modlens/scripts/run.ps1

@@ -0,0 +1,250 @@
+# modlens skill launcher (Windows, PowerShell 5.1 compatible).
+#
+# The Windows twin of run.sh: identical resolution order, identical diagnostic
+# fields, identical exit codes. One stable action for the agent ("run
+# modlens"); this script picks a working way to run it here.
+#
+# Invoke it per-process so no global policy is touched:
+#   powershell -ExecutionPolicy Bypass -File run.ps1 -q "test"
+#
+# Resolution order (kept identical in run.sh):
+#   1. A compatible modlens already on PATH  -> run it directly.
+#   2. npx present                             -> run the pinned npm version.
+#   3. bunx present                            -> run the pinned version via Bun.
+#   4. (phase B placeholder) a native artifact -> not published yet.
+#   5. Nothing usable                          -> structured diagnosis, exit 78.
+#
+# It never writes PATH, never needs admin rights, never fetches a second script,
+# and has no postinstall step.
+
+$ErrorActionPreference = 'Stop'
+
+# --- Version constants: stamped by scripts/release.mjs at release time. --------
+# Do not edit $Pinned by hand; scripts/stamp.test.mjs asserts it equals the
+# package.json version, and the release script rewrites it on every bump.
+$Package = '@liustack/modlens'
+$Bin = 'modlens'
+$Pinned = '3.1.0'
+# -------------------------------------------------------------------------------
+
+$NativeNote = 'no native artifact is published for this tool yet; phase A ships npm launch paths only'
+
+# Environment snapshot, filled by Collect and read by the emitters.
+$script:Arch = ''
+$script:CliPresent = $false
+$script:CliPath = $null
+$script:CliVer = $null
+$script:CliCompat = $false
+$script:NpxPresent = $false
+$script:NpxPath = $null
+$script:BunxPresent = $false
+$script:BunxPath = $null
+$script:NodePresent = $false
+$script:NodeVer = $null
+$script:Selected = 'none'
+
+# First "X.Y.Z" token printed by `$Bin --version`.
+function Get-CliVersion {
+    try { $out = & $Bin --version 2>$null } catch { return '' }
+    if (-not $out) { return '' }
+    $line = [string]($out | Select-Object -First 1)
+    $m = [regex]::Match($line, '[0-9]+\.[0-9]+\.[0-9]+')
+    if ($m.Success) { return $m.Value } else { return '' }
+}
+
+# Compatible = same major version as $Pinned AND not older than $Pinned.
+# Same major keeps a globally installed CLI usable without a forced re-download;
+# not-older refuses a stale build that predates the version this skill needs.
+function Test-Compatible {
+    param([string] $Ver)
+    $f = $Ver -split '\.'
+    $p = $Pinned -split '\.'
+    if ($f.Count -lt 3 -or $p.Count -lt 3) { return $false }
+    $fMaj = [int]$f[0]; $fMin = [int]$f[1]; $fPat = [int]$f[2]
+    $pMaj = [int]$p[0]; $pMin = [int]$p[1]; $pPat = [int]$p[2]
+    if ($fMaj -ne $pMaj) { return $false }
+    if ($fMin -gt $pMin) { return $true }
+    if ($fMin -lt $pMin) { return $false }
+    return ($fPat -ge $pPat)
+}
+
+# Return exactly one word: the chosen launch path.
+function Resolve-LaunchKind {
+    $cli = Get-Command $Bin -ErrorAction SilentlyContinue
+    if ($cli) {
+        $v = Get-CliVersion
+        if ($v -and (Test-Compatible $v)) { return 'path' }
+    }
+    if (Get-Command npx -ErrorAction SilentlyContinue) { return 'npx' }
+    if (Get-Command bunx -ErrorAction SilentlyContinue) { return 'bunx' }
+    # Phase B goes here: check a versioned user cache, then download and verify a
+    # native artifact into it. Any such download must use curl.exe (written in
+    # full so PowerShell 5.1 does not resolve `curl` to its Invoke-WebRequest
+    # alias), never Invoke-WebRequest, which stamps Mark-of-the-Web; see
+    # design.md 8.3.
+    return 'none'
+}
+
+# Run the resolved CLI and return its output (used to chain the CLI's own
+# doctor). Passes every argument through untouched.
+function Invoke-Cli {
+    param([string[]] $CliArgs)
+    switch ($script:Selected) {
+        'path' { & $Bin @CliArgs }
+        'npx' { & npx --yes --package "$Package@$Pinned" $Bin @CliArgs }
+        'bunx' { & bunx --bun "$Package@$Pinned" @CliArgs }
+    }
+}
+
+function Get-Arch {
+    switch ($env:PROCESSOR_ARCHITECTURE) {
+        'AMD64' { return 'x64' }
+        'ARM64' { return 'arm64' }
+        'x86' { return 'x86' }
+        default { return $env:PROCESSOR_ARCHITECTURE }
+    }
+}
+
+# Probe the environment once into the $script:* snapshot.
+function Collect {
+    $script:Arch = Get-Arch
+
+    $cli = Get-Command $Bin -ErrorAction SilentlyContinue
+    if ($cli) {
+        $script:CliPresent = $true
+        $script:CliPath = $cli.Source
+        $script:CliVer = Get-CliVersion
+        $script:CliCompat = [bool]($script:CliVer -and (Test-Compatible $script:CliVer))
+    }
+
+    $npx = Get-Command npx -ErrorAction SilentlyContinue
+    if ($npx) { $script:NpxPresent = $true; $script:NpxPath = $npx.Source }
+
+    $bunx = Get-Command bunx -ErrorAction SilentlyContinue
+    if ($bunx) { $script:BunxPresent = $true; $script:BunxPath = $bunx.Source }
+
+    $node = Get-Command node -ErrorAction SilentlyContinue
+    if ($node) {
+        $script:NodePresent = $true
+        try { $script:NodeVer = ((& node --version 2>$null) -replace '^v', '') } catch { $script:NodeVer = $null }
+    }
+
+    $script:Selected = Resolve-LaunchKind
+}
+
+# Assemble the structured diagnosis. $Chained, when a parsed object, becomes
+# cliDoctor; otherwise cliDoctor is null.
+function Build-DiagnosisJson {
+    param($Chained)
+    $checked = [ordered]@{
+        pathCli = [ordered]@{ present = $script:CliPresent; path = $script:CliPath; version = $script:CliVer; compatible = $script:CliCompat }
+        npx     = [ordered]@{ present = $script:NpxPresent; path = $script:NpxPath }
+        bunx    = [ordered]@{ present = $script:BunxPresent; path = $script:BunxPath }
+        node    = [ordered]@{ present = $script:NodePresent; version = $script:NodeVer }
+    }
+    $steps = @()
+    if ($script:Selected -eq 'none') {
+        $major = $Pinned.Split('.')[0]
+        $steps = @(
+            "Install Node 22.13+ from https://nodejs.org so npx can run $Package@$Pinned, then re-run this launcher.",
+            "No JavaScript runtime? Install Bun from https://bun.sh to use bunx, or put a compatible $Bin (major $major, at or above $Pinned) on PATH."
+        )
+    }
+    $obj = [ordered]@{
+        tool           = $Bin
+        package        = $Package
+        pinnedVersion  = $Pinned
+        os             = 'windows'
+        arch           = $script:Arch
+        checked        = $checked
+        nativeArtifact = [ordered]@{ available = $false; note = $NativeNote }
+        selected       = $script:Selected
+        nextSteps      = @($steps)
+        cliDoctor      = $Chained
+    }
+    return ($obj | ConvertTo-Json -Depth 20)
+}
+
+# Human-readable diagnosis for `doctor` without --json.
+function Write-DiagnosisText {
+    Write-Output "$Bin launcher diagnosis"
+    Write-Output ''
+    Write-Output ("  os / arch:      windows / {0}" -f $script:Arch)
+    Write-Output ("  pinned version: {0} ({1})" -f $Pinned, $Package)
+    if ($script:CliPresent) {
+        $verdict = if ($script:CliCompat) { 'compatible' } else { 'incompatible' }
+        Write-Output ("  {0} on PATH:  {1} (version {2}, {3})" -f $Bin, $script:CliPath, $script:CliVer, $verdict)
+    }
+    else {
+        Write-Output ("  {0} on PATH:  no" -f $Bin)
+    }
+    Write-Output ("  npx:            {0}" -f $(if ($script:NpxPresent) { $script:NpxPath } else { 'no' }))
+    Write-Output ("  bunx:           {0}" -f $(if ($script:BunxPresent) { $script:BunxPath } else { 'no' }))
+    Write-Output ("  node:           {0}" -f $(if ($script:NodePresent) { $script:NodeVer } else { 'no' }))
+    Write-Output ("  selected path:  {0}" -f $script:Selected)
+    if ($script:Selected -eq 'none') {
+        Write-Output ''
+        Write-Output ("No runtime can launch {0} here. {1}" -f $Bin, $NativeNote)
+        Write-Output 'Next steps:'
+        Write-Output '  - Install Node 22.13+ from https://nodejs.org, then re-run this launcher.'
+        Write-Output ("  - Or install Bun from https://bun.sh, or put a compatible {0} on PATH." -f $Bin)
+    }
+}
+
+# `doctor [--json] [extra...]`: launcher selection diagnosis. When a CLI is
+# resolvable, chain the CLI's own doctor so one call reports both layers. Extra
+# flags pass through to the chained CLI doctor.
+function Invoke-Doctor {
+    param([string[]] $DocArgs)
+    Collect
+    $json = $false
+    foreach ($a in $DocArgs) { if ($a -eq '--json') { $json = $true } }
+    if ($json) {
+        $chained = $null
+        if ($script:Selected -ne 'none') {
+            try {
+                $raw = (Invoke-Cli -CliArgs (@('doctor') + $DocArgs) 2>$null | Out-String).Trim()
+                if ($raw.StartsWith('{')) { $chained = ($raw | ConvertFrom-Json) }
+            }
+            catch { $chained = $null }
+        }
+        Write-Output (Build-DiagnosisJson $chained)
+    }
+    else {
+        Write-DiagnosisText
+        if ($script:Selected -ne 'none') {
+            Write-Output ''
+            Write-Output "--- $Bin doctor ---"
+            Invoke-Cli -CliArgs (@('doctor') + $DocArgs)
+        }
+    }
+}
+
+# Default action: forward every argument to the resolved CLI and exit with its
+# code. No usable runtime -> structured diagnosis on stderr, exit 78 (EX_CONFIG)
+# so the agent never mistakes the diagnosis for a result.
+function Invoke-Run {
+    param([string[]] $CliArgs)
+    $sel = Resolve-LaunchKind
+    switch ($sel) {
+        'path' { & $Bin @CliArgs; exit $LASTEXITCODE }
+        'npx' { & npx --yes --package "$Package@$Pinned" $Bin @CliArgs; exit $LASTEXITCODE }
+        'bunx' { & bunx --bun "$Package@$Pinned" @CliArgs; exit $LASTEXITCODE }
+        'none' {
+            Collect
+            [Console]::Error.WriteLine((Build-DiagnosisJson $null))
+            exit 78
+        }
+    }
+}
+
+$Command = ''
+if ($args.Count -ge 1) { $Command = [string]$args[0] }
+$Rest = @()
+if ($args.Count -gt 1) { $Rest = $args[1..($args.Count - 1)] }
+
+switch ($Command) {
+    'doctor' { Invoke-Doctor -DocArgs $Rest }
+    'where' { Collect; Write-Output $script:Selected }
+    default { Invoke-Run -CliArgs $args }
+}

package/skills/modlens/scripts/run.sh

@@ -0,0 +1,283 @@
+#!/bin/sh
+# modlens skill launcher (macOS / Linux).
+#
+# One stable action for the agent ("run modlens"); this script picks a working
+# way to run it in the current environment. Written to POSIX sh so it runs under
+# dash, busybox ash, and bash alike. Invoke it with `bash run.sh ...` (or plain
+# `sh run.sh ...`) so a lost execute bit after a file copy never matters.
+#
+# Resolution order (kept identical in run.ps1):
+#   1. A compatible modlens already on PATH  -> run it directly.
+#   2. npx present                             -> run the pinned npm version.
+#   3. bunx present                            -> run the pinned version via Bun.
+#   4. (phase B placeholder) a native artifact -> not published yet.
+#   5. Nothing usable                          -> structured diagnosis, exit 78.
+#
+# It never writes PATH, never needs admin rights, never fetches a second script,
+# and has no postinstall step.
+set -eu
+
+# --- Version constants: stamped by scripts/release.mjs at release time. --------
+# Do not edit PINNED by hand; scripts/stamp.test.mjs asserts it equals the
+# package.json version, and the release script rewrites it on every bump.
+PKG="@liustack/modlens"
+BIN="modlens"
+PINNED="3.1.0"
+# -------------------------------------------------------------------------------
+
+NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"
+
+# Split "X.Y.Z" (extra suffix ignored) into the globals _MAJ, _MIN, _PAT.
+# Any non-numeric component becomes 0 so integer tests below never abort.
+parse_semver() {
+  _raw="$1"
+  _MAJ="${_raw%%.*}"
+  _rest="${_raw#*.}"
+  if [ "$_rest" = "$_raw" ]; then
+    _MIN=0
+    _PAT=0
+  else
+    _MIN="${_rest%%.*}"
+    _rest2="${_rest#*.}"
+    if [ "$_rest2" = "$_rest" ]; then _PAT=0; else _PAT="${_rest2%%.*}"; fi
+  fi
+  case "$_MAJ" in '' | *[!0-9]*) _MAJ=0 ;; esac
+  case "$_MIN" in '' | *[!0-9]*) _MIN=0 ;; esac
+  case "$_PAT" in '' | *[!0-9]*) _PAT=0 ;; esac
+}
+
+# Compatible = same major version as PINNED AND not older than PINNED.
+# Same major keeps a globally installed CLI usable without a forced re-download;
+# not-older refuses a stale build that predates the version this skill needs.
+compatible() {
+  parse_semver "$1"
+  _f_maj=$_MAJ
+  _f_min=$_MIN
+  _f_pat=$_PAT
+  parse_semver "$PINNED"
+  [ "$_f_maj" = "$_MAJ" ] || return 1
+  if [ "$_f_min" -gt "$_MIN" ]; then return 0; fi
+  if [ "$_f_min" -lt "$_MIN" ]; then return 1; fi
+  [ "$_f_pat" -ge "$_PAT" ]
+}
+
+# First "X.Y.Z" token printed by `$BIN --version`.
+cli_version() {
+  "$BIN" --version 2>/dev/null | head -n 1 |
+    sed -n 's/.*\([0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*\).*/\1/p'
+}
+
+# Echo exactly one word: the chosen launch path.
+resolve() {
+  if command -v "$BIN" >/dev/null 2>&1; then
+    _v="$(cli_version)"
+    if [ -n "$_v" ] && compatible "$_v"; then
+      echo "path"
+      return
+    fi
+  fi
+  if command -v npx >/dev/null 2>&1; then
+    echo "npx"
+    return
+  fi
+  if command -v bunx >/dev/null 2>&1; then
+    echo "bunx"
+    return
+  fi
+  # Phase B goes here: check a versioned user cache, then download and verify a
+  # native artifact into it. Any such download must use curl (never a piped
+  # second script), which does not stamp quarantine / Mark-of-the-Web the way a
+  # browser does, matching design.md 8.3.
+  echo "none"
+}
+
+# Run the resolved CLI without exec, so its output can be captured (used to
+# chain the CLI's own doctor). Passes every argument through untouched.
+run_cli() {
+  case "$G_SEL" in
+    path) "$BIN" "$@" ;;
+    npx) npx --yes --package "$PKG@$PINNED" "$BIN" "$@" ;;
+    bunx) bunx --bun "$PKG@$PINNED" "$@" ;;
+  esac
+}
+
+detect_os() { uname -s 2>/dev/null | tr '[:upper:]' '[:lower:]'; }
+
+detect_arch() {
+  _a="$(uname -m 2>/dev/null)"
+  case "$_a" in
+    x86_64 | amd64) echo "x64" ;;
+    aarch64 | arm64) echo "arm64" ;;
+    *) echo "$_a" ;;
+  esac
+}
+
+# Escape a value for a JSON string literal (backslash and double quote).
+json_escape() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; }
+
+# Render "null" for an empty value, else an escaped JSON string.
+jstr() {
+  if [ -z "$1" ]; then printf 'null'; else printf '"%s"' "$(json_escape "$1")"; fi
+}
+
+# 1 -> true, anything else -> false.
+jbool() { if [ "$1" = "1" ]; then printf 'true'; else printf 'false'; fi; }
+
+# Probe the environment once into G_* globals shared by the emitters.
+collect() {
+  G_OS="$(detect_os)"
+  G_ARCH="$(detect_arch)"
+
+  G_CLI_PRESENT=0
+  G_CLI_PATH=""
+  G_CLI_VER=""
+  G_CLI_COMPAT=0
+  if command -v "$BIN" >/dev/null 2>&1; then
+    G_CLI_PRESENT=1
+    G_CLI_PATH="$(command -v "$BIN")"
+    G_CLI_VER="$(cli_version)"
+    if [ -n "$G_CLI_VER" ] && compatible "$G_CLI_VER"; then G_CLI_COMPAT=1; fi
+  fi
+
+  G_NPX_PRESENT=0
+  G_NPX_PATH=""
+  if command -v npx >/dev/null 2>&1; then
+    G_NPX_PRESENT=1
+    G_NPX_PATH="$(command -v npx)"
+  fi
+
+  G_BUNX_PRESENT=0
+  G_BUNX_PATH=""
+  if command -v bunx >/dev/null 2>&1; then
+    G_BUNX_PRESENT=1
+    G_BUNX_PATH="$(command -v bunx)"
+  fi
+
+  G_NODE_PRESENT=0
+  G_NODE_VER=""
+  if command -v node >/dev/null 2>&1; then
+    G_NODE_PRESENT=1
+    G_NODE_VER="$(node --version 2>/dev/null | sed 's/^v//')"
+  fi
+
+  G_SEL="$(resolve)"
+}
+
+# Build the nextSteps JSON array body (without the brackets) into G_NEXTSTEPS.
+compute_next_steps() {
+  if [ "$G_SEL" = "none" ]; then
+    _s1="Install Node 22.13+ from https://nodejs.org so npx can run $PKG@$PINNED, then re-run this launcher."
+    _s2="No JavaScript runtime? Install Bun from https://bun.sh to use bunx, or put a compatible $BIN (major ${PINNED%%.*}, at or above $PINNED) on PATH."
+    G_NEXTSTEPS="$(printf '"%s", "%s"' "$(json_escape "$_s1")" "$(json_escape "$_s2")")"
+  else
+    G_NEXTSTEPS=""
+  fi
+}
+
+# Emit the structured diagnosis. $1, when a JSON object, is embedded as cliDoctor.
+emit_json() {
+  _chained="${1:-}"
+  compute_next_steps
+  printf '{\n'
+  printf '  "tool": %s,\n' "$(jstr "$BIN")"
+  printf '  "package": %s,\n' "$(jstr "$PKG")"
+  printf '  "pinnedVersion": %s,\n' "$(jstr "$PINNED")"
+  printf '  "os": %s,\n' "$(jstr "$G_OS")"
+  printf '  "arch": %s,\n' "$(jstr "$G_ARCH")"
+  printf '  "checked": {\n'
+  printf '    "pathCli": { "present": %s, "path": %s, "version": %s, "compatible": %s },\n' \
+    "$(jbool "$G_CLI_PRESENT")" "$(jstr "$G_CLI_PATH")" "$(jstr "$G_CLI_VER")" "$(jbool "$G_CLI_COMPAT")"
+  printf '    "npx": { "present": %s, "path": %s },\n' "$(jbool "$G_NPX_PRESENT")" "$(jstr "$G_NPX_PATH")"
+  printf '    "bunx": { "present": %s, "path": %s },\n' "$(jbool "$G_BUNX_PRESENT")" "$(jstr "$G_BUNX_PATH")"
+  printf '    "node": { "present": %s, "version": %s }\n' "$(jbool "$G_NODE_PRESENT")" "$(jstr "$G_NODE_VER")"
+  printf '  },\n'
+  printf '  "nativeArtifact": { "available": false, "note": %s },\n' "$(jstr "$NATIVE_NOTE")"
+  printf '  "selected": %s,\n' "$(jstr "$G_SEL")"
+  printf '  "nextSteps": [%s],\n' "$G_NEXTSTEPS"
+  # First character of the captured output, via POSIX parameter expansion
+  # (cut -c1 would take the first char of every line, not of the whole string).
+  _first="${_chained%"${_chained#?}"}"
+  if [ -n "$_chained" ] && [ "$_first" = "{" ]; then
+    printf '  "cliDoctor": %s\n' "$_chained"
+  else
+    printf '  "cliDoctor": null\n'
+  fi
+  printf '}\n'
+}
+
+# Human-readable diagnosis for `doctor` without --json.
+emit_text() {
+  printf '%s launcher diagnosis\n\n' "$BIN"
+  printf '  os / arch:      %s / %s\n' "$G_OS" "$G_ARCH"
+  printf '  pinned version: %s (%s)\n' "$PINNED" "$PKG"
+  if [ "$G_CLI_PRESENT" = 1 ]; then
+    printf '  %s on PATH:  %s (version %s, %s)\n' "$BIN" "$G_CLI_PATH" \
+      "${G_CLI_VER:-unknown}" "$([ "$G_CLI_COMPAT" = 1 ] && echo compatible || echo incompatible)"
+  else
+    printf '  %s on PATH:  no\n' "$BIN"
+  fi
+  printf '  npx:            %s\n' "$([ "$G_NPX_PRESENT" = 1 ] && echo "$G_NPX_PATH" || echo no)"
+  printf '  bunx:           %s\n' "$([ "$G_BUNX_PRESENT" = 1 ] && echo "$G_BUNX_PATH" || echo no)"
+  printf '  node:           %s\n' "$([ "$G_NODE_PRESENT" = 1 ] && echo "${G_NODE_VER:-yes}" || echo no)"
+  printf '  selected path:  %s\n' "$G_SEL"
+  if [ "$G_SEL" = "none" ]; then
+    printf '\nNo runtime can launch %s here. %s\n' "$BIN" "$NATIVE_NOTE"
+    printf 'Next steps:\n'
+    printf '  - Install Node 22.13+ from https://nodejs.org, then re-run this launcher.\n'
+    printf '  - Or install Bun from https://bun.sh, or put a compatible %s on PATH.\n' "$BIN"
+  fi
+}
+
+# `doctor [--json] [extra...]`: launcher selection diagnosis. When a CLI is
+# resolvable, chain the CLI's own doctor (engine/config diagnosis) so one call
+# reports both layers. Extra flags pass through to the chained CLI doctor.
+doctor() {
+  collect
+  _json=0
+  for _a in "$@"; do
+    if [ "$_a" = "--json" ]; then _json=1; fi
+  done
+  if [ "$_json" = 1 ]; then
+    _chained=""
+    if [ "$G_SEL" != "none" ]; then
+      _chained="$(run_cli doctor "$@" 2>/dev/null)" || _chained=""
+    fi
+    emit_json "$_chained"
+  else
+    emit_text
+    if [ "$G_SEL" != "none" ]; then
+      printf '\n--- %s doctor ---\n' "$BIN"
+      run_cli doctor "$@" || true
+    fi
+  fi
+}
+
+# Default action: forward every argument to the resolved CLI, inheriting stdio
+# and exit code. No usable runtime -> structured diagnosis on stderr, exit 78
+# (EX_CONFIG) so the agent never mistakes the diagnosis for a result.
+run() {
+  _sel="$(resolve)"
+  case "$_sel" in
+    path) exec "$BIN" "$@" ;;
+    npx) exec npx --yes --package "$PKG@$PINNED" "$BIN" "$@" ;;
+    bunx) exec bunx --bun "$PKG@$PINNED" "$@" ;;
+    none)
+      collect
+      emit_json "" >&2
+      exit 78
+      ;;
+  esac
+}
+
+case "${1:-}" in
+  doctor)
+    shift
+    doctor "$@"
+    ;;
+  where)
+    resolve
+    ;;
+  *)
+    run "$@"
+    ;;
+esac