@liustack/modlens 3.1.0 → 3.1.1

package/docs/security.md

@@ -20,7 +20,9 @@ ModLens invokes `agy` with `--dangerously-skip-permissions` because prompt mode
 
 The `claude-cli` provider runs with `--allowedTools Read` only, so it can read local files and nothing else.
 
-Both subprocess providers also run in a throwaway directory containing only the one image, created fresh per call and removed afterward. Text inside an image is untrusted, so an injection could otherwise steer a broadly-permissioned agent into reading files that sit next to the original. A directory of one removes that reach. Passing `--workdir` opts out and runs where you point it.
+Both subprocess providers also run in a throwaway directory created fresh per call and removed afterward. For a local image it holds a private copy of that one image and nothing else, and it is a real copy, never a hardlink, so a provider writing to its temp path cannot touch the original. For a remote image the directory is empty and the agent downloads into it. Without this, text inside an image could steer a broadly-permissioned agent into reading files next to the original, or whatever project the caller happened to be in. Passing `--workdir` opts out and runs where you point it.
+
+This is exposure reduction, not an OS sandbox: the agent can still read absolute paths, reach the network, and spawn processes. Treat it as a narrower default, not a security boundary. For images you do not trust, prefer an inline API provider (`-p gemini-api`), which hands the bytes to an HTTP endpoint and runs no local agent.
 
 ## Image content is untrusted input
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liustack/modlens",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
   "type": "module",
   "bin": {
@@ -54,7 +54,8 @@
     "node": ">=22.13"
   },
   "dependencies": {
-    "commander": "^13.1.0"
+    "commander": "^13.1.0",
+    "undici": "^8.10.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.7",

package/skills/modlens/SKILL.md

@@ -33,11 +33,11 @@ The launcher finds a working way to run modlens and forwards your arguments to i
 
 ### If you cannot run the launcher script
 
-Some harnesses forbid running scripts. Reason through the same order by hand and run the first line that works (the pinned version is 3.0.0):
+Some harnesses forbid running scripts. Reason through the same order by hand and run the first line that works (the pinned version is 3.1.1):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.0.0: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.0.0 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.0.0 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.1.1: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.1.1 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.1.1 <args>`.
 4. Otherwise none of these runtimes is here. Tell the user no JavaScript runtime was found and that installing Node 22.13+ (https://nodejs.org) or Bun (https://bun.sh) is the next step. Do not claim modlens itself failed.
 
 `references/runtime.md` documents the version pin, the compatibility rule, and the diagnostic fields.
@@ -84,9 +84,10 @@ Harnesses rarely hand you a clean path. First identify which harness you are in,
 
 **Claude Code, Pi, or OpenCode** (no path tag anywhere; the image reads as `[Unsupported Image]`, a bare `[Image #1]`, or an attachment you simply cannot see):
 
-- None of these harnesses writes pasted images to a regular temp file, but all of them persist user messages locally before any gateway strips them: Claude Code and Pi in session JSONL files (`~/.claude/projects/`, `~/.pi/agent/sessions/`), OpenCode in a SQLite database (`~/.local/share/opencode/opencode.db`, read via node:sqlite, needs Node 22.5+). Run `modlens recover-paste` from the project directory the conversation is happening in (add `--count <n>` for several images). It detects which harness it is running inside (process ancestry, then env fingerprints) and reads ONLY that harness's storage, so another tool's old sessions cannot leak in. In Claude Code it also targets your exact session automatically via the injected CLAUDE_CODE_SESSION_ID; `--session <id>` (e.g. from the ${CLAUDE_SESSION_ID} substitution) is only needed to override.
+- None of these harnesses writes pasted images to a regular temp file, but all of them persist user messages locally before any gateway strips them: Claude Code and Pi in session JSONL files (`~/.claude/projects/`, `~/.pi/agent/sessions/`), OpenCode in a SQLite database (`~/.local/share/opencode/opencode.db`, read via node:sqlite, needs Node 22.5+; Bun cannot load node:sqlite, so if the launcher resolved to bunx, OpenCode recovery needs a real Node install). Run `modlens recover-paste` from the project directory the conversation is happening in (add `--count <n>` for several images). It detects which harness it is running inside (process ancestry, then env fingerprints) and reads ONLY that harness's storage, so another tool's old sessions cannot leak in. In Claude Code it also targets your exact session automatically via the injected CLAUDE_CODE_SESSION_ID; `--session <id>` (e.g. from the ${CLAUDE_SESSION_ID} substitution) is only needed to override.
 - The output is JSON with real file paths, ordered oldest to newest, so the LAST path is the user's most recent paste. Analyze that one first. Entries carry `filename` (the original attachment name) when the harness stored one; if the user's message or an error mentions a filename, match on it.
 - Run every command yourself: `recover-paste`, then `modlens -i <path>` on the recovered file, then answer from the JSON. Never ask the user to run modlens or to relay paths.
+- When the analysis is done, delete the recovered files: they are private copies of the user's pasted images sitting in the temp dir, and nothing cleans them up until the OS does. Remove the recovery output directory (each entry's `path` sits inside it), unless the user asked to keep the files.
 - The output's `detected` field names the harness scope that was applied. If it is absent, detection failed and every store was scanned by newest-image timestamp: before describing anything, check that `harness` and `filename` match what you expect, force the scope with `--harness <claude-code|pi|opencode>` if they do not, and when in doubt ask the user for the file instead of describing the wrong image.
 - Recovery is scoped to this project: the harness's own record of its working directory is checked, not just the directory name, so images from a neighbouring project are never handed over. Recovered files are private to the user (0600).
 - If recovery fails (session storage is each harness's internals and may change), ask the user to drag the image file into the terminal or type its path.

package/skills/modlens/references/runtime.md

@@ -8,7 +8,7 @@ shell syntax.
 
 ## Pinned version
 
-- Pinned CLI version: 3.1.0
+- Pinned CLI version: 3.1.1
 - npm package: `@liustack/modlens`
 - CLI binary name: `modlens`
 
@@ -22,7 +22,7 @@ launcher/reference copies ever drift from `package.json`.
 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>`.
+2. **`npx` present, and `node` meets the CLI's 22.13 floor** — `npx --yes --package @liustack/modlens@<pinned> modlens <args>`. An npx sitting on an older node is skipped: it would select a path known to fail at run time.
 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.
@@ -43,7 +43,9 @@ instead.
 
 ## Cache and permissions (phase B, not active yet)
 
-Phase A never downloads anything. When native artifacts land in phase B, the
+Phase A ships no native artifact. The `npx` and `bunx` paths fetch the pinned
+npm package on first use and cache it (that is how those runners work); nothing
+else is ever downloaded. When native artifacts land in phase B, the
 launchers will cache them per user, keyed by version, and launch them by
 absolute path:
 
@@ -67,7 +69,9 @@ would have set.
   `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.npx` — `{ present, path, nodeMeetsFloor }`; `nodeMeetsFloor` is whether
+  the local node satisfies the CLI's 22.13 floor, required for the npx path.
+- `checked.bunx` — `{ present, path }`.
 - `checked.node` — `{ present, version }`.
 - `nativeArtifact` — `{ available, note }`; `available` is `false` in phase A.
 - `selected` — the resolved path: `path`, `npx`, `bunx`, or `none`.
@@ -76,9 +80,15 @@ would have set.
 - `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.
+`doctor` spends no quota. The launcher's own diagnosis is offline: it inspects
+the local environment and makes no network request of its own. Chaining the
+CLI's `doctor` through the npx or bunx path can download the pinned package the
+first time (that is how those runners work); after that it is served from the
+local cache.
+
+One capability note for the bunx path: Bun cannot load `node:sqlite`, which
+OpenCode paste recovery needs, so on a machine where the launcher resolved to
+bunx, `recover-paste` for OpenCode requires installing Node 22.13+ instead.
 
 ## Delivery form: local CLI, long term
 

package/skills/modlens/scripts/run.ps1

@@ -24,7 +24,7 @@ $ErrorActionPreference = 'Stop'
 # package.json version, and the release script rewrites it on every bump.
 $Package = '@liustack/modlens'
 $Bin = 'modlens'
-$Pinned = '3.1.0'
+$Pinned = '3.1.1'
 # -------------------------------------------------------------------------------
 
 $NativeNote = 'no native artifact is published for this tool yet; phase A ships npm launch paths only'
@@ -41,6 +41,7 @@ $script:BunxPresent = $false
 $script:BunxPath = $null
 $script:NodePresent = $false
 $script:NodeVer = $null
+$script:NodeFloorOk = $false
 $script:Selected = 'none'
 
 # First "X.Y.Z" token printed by `$Bin --version`.
@@ -68,6 +69,24 @@ function Test-Compatible {
     return ($fPat -ge $pPat)
 }
 
+# The npx path runs the CLI on this machine's node, so npx is only usable when
+# node itself meets the CLI's floor. An old node with a working npx used to be
+# selected anyway, a path known to fail at run time.
+$NodeFloor = '22.13.0'
+function Test-NodeMeetsFloor {
+    if (-not (Get-Command node -ErrorAction SilentlyContinue)) { return $false }
+    try { $nv = ((& node --version 2>$null) -replace '^v', '') } catch { return $false }
+    if (-not $nv) { return $false }
+    $n = $nv -split '\.'
+    $f = $NodeFloor -split '\.'
+    if ($n.Count -lt 2) { return $false }
+    $nMaj = [int]$n[0]; $nMin = [int]$n[1]
+    $fMaj = [int]$f[0]; $fMin = [int]$f[1]
+    if ($nMaj -gt $fMaj) { return $true }
+    if ($nMaj -lt $fMaj) { return $false }
+    return ($nMin -ge $fMin)
+}
+
 # Return exactly one word: the chosen launch path.
 function Resolve-LaunchKind {
     $cli = Get-Command $Bin -ErrorAction SilentlyContinue
@@ -75,7 +94,7 @@ function Resolve-LaunchKind {
         $v = Get-CliVersion
         if ($v -and (Test-Compatible $v)) { return 'path' }
     }
-    if (Get-Command npx -ErrorAction SilentlyContinue) { return 'npx' }
+    if ((Get-Command npx -ErrorAction SilentlyContinue) -and (Test-NodeMeetsFloor)) { 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
@@ -127,6 +146,7 @@ function Collect {
     if ($node) {
         $script:NodePresent = $true
         try { $script:NodeVer = ((& node --version 2>$null) -replace '^v', '') } catch { $script:NodeVer = $null }
+        $script:NodeFloorOk = Test-NodeMeetsFloor
     }
 
     $script:Selected = Resolve-LaunchKind
@@ -138,15 +158,19 @@ 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 }
+        npx     = [ordered]@{ present = $script:NpxPresent; path = $script:NpxPath; nodeMeetsFloor = $script:NodeFloorOk }
         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]
+        $first = "Install Node 22.13+ from https://nodejs.org so npx can run $Package@$Pinned, then re-run this launcher."
+        if ($script:NpxPresent -and (-not $script:NodeFloorOk)) {
+            $first = "npx is present but node $(if ($script:NodeVer) { $script:NodeVer } else { 'missing' }) is below the $NodeFloor floor this CLI needs. Upgrade Node at https://nodejs.org, then re-run this launcher."
+        }
         $steps = @(
-            "Install Node 22.13+ from https://nodejs.org so npx can run $Package@$Pinned, then re-run this launcher.",
+            $first,
             "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."
         )
     }
@@ -178,7 +202,12 @@ function Write-DiagnosisText {
     else {
         Write-Output ("  {0} on PATH:  no" -f $Bin)
     }
-    Write-Output ("  npx:            {0}" -f $(if ($script:NpxPresent) { $script:NpxPath } else { 'no' }))
+    $npxDesc = 'no'
+    if ($script:NpxPresent) {
+        if ($script:NodeFloorOk) { $npxDesc = $script:NpxPath }
+        else { $npxDesc = "$($script:NpxPath) (unusable: node $(if ($script:NodeVer) { $script:NodeVer } else { 'missing' }) is below $NodeFloor)" }
+    }
+    Write-Output ("  npx:            {0}" -f $npxDesc)
     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)

package/skills/modlens/scripts/run.sh

@@ -22,7 +22,7 @@ set -eu
 # package.json version, and the release script rewrites it on every bump.
 PKG="@liustack/modlens"
 BIN="modlens"
-PINNED="3.1.0"
+PINNED="3.1.1"
 # -------------------------------------------------------------------------------
 
 NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"
@@ -67,6 +67,23 @@ cli_version() {
     sed -n 's/.*\([0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*\).*/\1/p'
 }
 
+# The npx path runs the CLI on this machine's node, so npx is only usable when
+# node itself meets the CLI's floor. An old node with a working npx used to be
+# selected anyway, a path known to fail at run time.
+NODE_FLOOR="22.13.0"
+node_meets_floor() {
+  command -v node >/dev/null 2>&1 || return 1
+  _nv="$(node --version 2>/dev/null | sed 's/^v//')"
+  [ -n "$_nv" ] || return 1
+  parse_semver "$NODE_FLOOR"
+  _floor_maj="$_MAJ"
+  _floor_min="$_MIN"
+  parse_semver "$_nv"
+  if [ "$_MAJ" -gt "$_floor_maj" ]; then return 0; fi
+  if [ "$_MAJ" -lt "$_floor_maj" ]; then return 1; fi
+  [ "$_MIN" -ge "$_floor_min" ]
+}
+
 # Echo exactly one word: the chosen launch path.
 resolve() {
   if command -v "$BIN" >/dev/null 2>&1; then
@@ -76,7 +93,7 @@ resolve() {
       return
     fi
   fi
-  if command -v npx >/dev/null 2>&1; then
+  if command -v npx >/dev/null 2>&1 && node_meets_floor; then
     echo "npx"
     return
   fi
@@ -160,13 +177,20 @@ collect() {
     G_NODE_VER="$(node --version 2>/dev/null | sed 's/^v//')"
   fi
 
+  G_NODE_FLOOR_OK=0
+  if node_meets_floor; then G_NODE_FLOOR_OK=1; 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."
+    if [ "$G_NPX_PRESENT" = 1 ] && [ "$G_NODE_FLOOR_OK" = 0 ]; then
+      _s1="npx is present but node ${G_NODE_VER:-missing} is below the $NODE_FLOOR floor this CLI needs. Upgrade Node at https://nodejs.org, then re-run this launcher."
+    else
+      _s1="Install Node 22.13+ from https://nodejs.org so npx can run $PKG@$PINNED, then re-run this launcher."
+    fi
     _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
@@ -187,7 +211,7 @@ emit_json() {
   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 '    "npx": { "present": %s, "path": %s, "nodeMeetsFloor": %s },\n' "$(jbool "$G_NPX_PRESENT")" "$(jstr "$G_NPX_PATH")" "$(jbool "$G_NODE_FLOOR_OK")"
   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'
@@ -216,7 +240,15 @@ emit_text() {
   else
     printf '  %s on PATH:  no\n' "$BIN"
   fi
-  printf '  npx:            %s\n' "$([ "$G_NPX_PRESENT" = 1 ] && echo "$G_NPX_PATH" || echo no)"
+  _npx_desc="no"
+  if [ "$G_NPX_PRESENT" = 1 ]; then
+    if [ "$G_NODE_FLOOR_OK" = 1 ]; then
+      _npx_desc="$G_NPX_PATH"
+    else
+      _npx_desc="$G_NPX_PATH (unusable: node ${G_NODE_VER:-missing} is below $NODE_FLOOR)"
+    fi
+  fi
+  printf '  npx:            %s\n' "$_npx_desc"
   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"