@liustack/modlens 3.16.1 → 3.16.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 3.16.2 - 2026-08-14
+
+- **The claude-cli provider starts on Windows ([#31](https://github.com/liustack/modlens/issues/31)).** npm installs every JS CLI as a trio, and both ways of reaching it failed: the bare name found none of them (ENOENT, reported as "not installed" next to a `claude --version` that worked fine), and handing spawn the `.cmd` hit Node's post-CVE refusal to run batch files without a shell (EINVAL). Wrapping it in `cmd.exe` turned out to be a trap, since a cmd command line cannot carry a raw newline and our provider arguments are whole multi-line vision prompts, so a wrapped prompt truncates at its first line break and the rest is read as a second command. modlens instead reads the shim, takes the Node entry it points at, and spawns Node on it directly: no shell, no escaping, and the child is the real provider, so a timeout's SIGTERM lands on it rather than an intermediate. The reading is conservative by construction. Every line of the shim must be accounted for, the interpreter is read rather than inferred (cmd-shim will happily generate a python shim for a file named `.js`), and a shim carrying anything this cannot reproduce faithfully, an environment assignment, cmd control syntax, an argument whose quoting it cannot prove, is declined and left to a spawn error that names the provider, the command, and the real error code. Nine rounds of independent review shaped that boundary, each round adding a shape it had to refuse rather than guess at. Thanks to @zhang66633 for a report that arrived with both failure modes already isolated.
+- **The install procedure knows about dsh ([#32](https://github.com/liustack/modlens/issues/32)).** INSTALL.md, the file an agent is pointed at, never mentioned dsh once, so an agent told to install modlens followed the skill procedure to its end and left the user without the `read_image` tool and without the `(modlens vision)` entries they were looking for. It now opens with a dsh branch: install the plugin, skip the skill copy, keep the same engine configuration.
+- **`doctor` says when an installed skill copy has fallen behind ([#33](https://github.com/liustack/modlens/issues/33)).** A skill is installed by copying it, and a copy keeps the version it was stamped with, so one machine ran 3.8.0 for eight releases and hit bugs that were long fixed. doctor now reads the pin out of every installed copy it can find and compares it against the version of the CLI reporting, which differ exactly when it matters, since the dsh plugin and an `@latest` run are both current. Still offline: two local file reads, no registry call. Thanks to @Ztyss for a report that had already verified the release stamping, leaving the update story as the real gap.
+
 ## 3.16.1 - 2026-08-14
 
 - **OpenChamber (OpenCode's desktop UI) is detected, and Windows detection got quieter and sharper ([#30](https://github.com/liustack/modlens/issues/30)).** Three stacked Windows gaps from one runtime-confirmed report. The env-fingerprint fallback never checked the markers opencode servers inject (`OPENCODE`, `OPENCODE_PID`, `OPENCODE_BINARY`), so OpenChamber read as "none detected" and `recover-paste` never auto-ran, while the pasted bytes sat recoverable in the opencode database the whole time; the fingerprint now resolves to `opencode`, placed before Claude Code's so nested setups pick the innermost input box. The `ps` ancestry probe now runs only off Windows: MSYS machines carry a `ps` that exists but rejects `-Ao`, and a failed child's stderr printed into every `doctor` run (the docs always said Windows skips ancestry, now the code agrees). And `findOnPath` tries the PATHEXT extensions before the bare name, so the POSIX `sh` shim npm installs next to `opencode.cmd` no longer shadows the executable into a `spawnSync ENOENT`. Thanks to @IA20201 for a report with the evidence already attached: observed env markers, doctor output, and the exact database row.

package/README.md

@@ -159,10 +159,10 @@ ModLens does not accept pull requests. The project is maintained by a single aut
 This project runs on LIUSTACK Skills: `shaping` before you build, `coding` while you build, `dig` when it breaks, `snapshot` when you hand off. Lighter than Superpowers, and stronger.
 
 ```bash
-npx -y skills add liustack/liustack -g
+npx -y skills add liustack/vibemaster -g
 ```
 
-⭐ If it helps, star [ModLens](https://github.com/liustack/modlens) and [liustack](https://github.com/liustack/liustack). Stars are how the next developer finds them.
+⭐ If it helps, star [ModLens](https://github.com/liustack/modlens) and [VibeMaster](https://github.com/liustack/vibemaster). Stars are how the next developer finds them.
 
 ## Star History
 

package/dist/main.js

@@ -1687,6 +1687,215 @@ function providerChain(kind, config2, env = process.env) {
   }
   return names.filter((name) => providerAvailable(name, config2, env)).map((name) => resolveProvider(name));
 }
+function tokenizeCmdLine(line) {
+  const pattern = /(?:"[^"]*"|[^\s"])+/g;
+  const args = line.match(pattern) ?? [];
+  if (line.replace(pattern, "").trim() !== "") {
+    return null;
+  }
+  return args.map((raw, index) => {
+    const text = index === 0 ? raw.replace(/^@/, "") : raw;
+    const whole = /^"([^"]*)"$/.exec(text);
+    return whole ? { value: whole[1], quoted: true } : { value: text, quoted: false };
+  });
+}
+function expandShimPath(token, shimDir) {
+  const relative = /^%~?dp0%?\\?(.*)$/i.exec(token);
+  if (relative) {
+    return path.win32.join(shimDir, relative[1]);
+  }
+  if (path.win32.isAbsolute(token)) {
+    return token;
+  }
+  return null;
+}
+const CMD_SYNTAX = /"|%~?\d/;
+const CMD_CONTROL = /[\^&|<>()]/;
+function literalToken(token, shimDir) {
+  const text = token.value;
+  if (CMD_SYNTAX.test(text) || !token.quoted && CMD_CONTROL.test(text)) {
+    return null;
+  }
+  const substituted = text.replace(/%dp0%|%~dp0/gi, `${shimDir}\\`);
+  if (substituted.includes("%")) {
+    return null;
+  }
+  return /^(%dp0%|%~dp0)/i.test(text) ? path.win32.normalize(substituted) : substituted;
+}
+function isNodeInterpreter(token) {
+  return /^node(\.exe)?$/i.test(path.win32.basename(token));
+}
+function carriesForeignEnv(content) {
+  const setRe = /^\s*@?SET\s+"?([A-Za-z_][A-Za-z0-9_]*)=/gim;
+  let match;
+  while ((match = setRe.exec(content)) !== null) {
+    const name = match[1].toLowerCase();
+    if (name !== "dp0" && name !== "_prog" && name !== "pathext") {
+      return true;
+    }
+  }
+  return false;
+}
+function progIsNode(content, shimDir) {
+  const progRe = /^\s*@?SET\s+"?_prog=([^"\r\n]*)"?/gim;
+  const values = [];
+  let match;
+  while ((match = progRe.exec(content)) !== null) {
+    values.push(match[1].trim());
+  }
+  if (values.length === 0) {
+    return { ok: false };
+  }
+  let absolute;
+  for (const value of values) {
+    const expanded = expandShimPath(value, shimDir) ?? value;
+    if (!isNodeInterpreter(expanded)) {
+      return { ok: false };
+    }
+    if (path.win32.isAbsolute(value)) {
+      absolute = value;
+    }
+  }
+  return { ok: true, ...absolute ? { absolute } : {} };
+}
+const STRUCTURAL_LINE = [
+  /^\s*$/,
+  /^\s*@?ECHO\s+off\s*$/i,
+  /^\s*@?SETLOCAL\s*$/i,
+  /^\s*@?ENDLOCAL\s*$/i,
+  /^\s*GOTO\s+\S+\s*$/i,
+  /^\s*:\S+\s*$/,
+  /^\s*EXIT\s+\/b\s*$/i,
+  /^\s*CALL\s+:\S+\s*$/i,
+  /^\s*@?SET\s+dp0=%~dp0\s*$/i,
+  /^\s*@?SET\s+"?_prog=[^"\r\n]*"?\s*$/i,
+  /^\s*@?SET\s+PATHEXT=%PATHEXT:[^%]*%\s*$/i,
+  /^\s*@?IF\s+EXIST\s+"[^"]*"\s*\(\s*$/i,
+  /^\s*\)\s*ELSE\s*\(\s*$/i,
+  /^\s*\)\s*$/
+];
+function parseCmdShimTarget(cmdPath, content) {
+  const shimDir = path.win32.dirname(cmdPath);
+  if (carriesForeignEnv(content)) {
+    return null;
+  }
+  const lines = content.split(/\r?\n/);
+  const executionLines = [];
+  for (const line of lines) {
+    if (STRUCTURAL_LINE.some((pattern) => pattern.test(line))) {
+      continue;
+    }
+    if (!line.includes("%*")) {
+      return null;
+    }
+    executionLines.push(line);
+  }
+  if (executionLines.length === 0) {
+    return null;
+  }
+  let agreed = null;
+  for (const line of executionLines) {
+    const parsed = parseExecutionLine(line, content, shimDir);
+    if (!parsed) {
+      return null;
+    }
+    if (agreed && !sameTarget(agreed, parsed)) {
+      return null;
+    }
+    agreed ??= parsed;
+  }
+  return agreed;
+}
+function sameTarget(a, b) {
+  return a.nodeExec === b.nodeExec && a.args.length === b.args.length && a.args.every((value, index) => value === b.args[index]);
+}
+function parseExecutionLine(line, content, shimDir) {
+  {
+    const tokens = tokenizeCmdLine(line);
+    if (!tokens) {
+      return null;
+    }
+    const forwardIndex = tokens.findIndex((token) => !token.quoted && token.value === "%*");
+    if (forwardIndex < 2 || forwardIndex !== tokens.length - 1) {
+      return null;
+    }
+    const runTokens = tokens.slice(0, forwardIndex);
+    const lastAmp = runTokens.reduce(
+      (found, token, index) => !token.quoted && token.value === "&" ? index : found,
+      -1
+    );
+    let words = lastAmp >= 0 ? runTokens.slice(lastAmp + 1) : runTokens;
+    if (words.length < 2) {
+      return null;
+    }
+    let nodeExec;
+    if (/^-S(\.exe)?$/i.test(path.win32.basename(words[0].value))) {
+      words = words.slice(1);
+    }
+    const interpreter = words[0].value;
+    if (interpreter === "%_prog%") {
+      const prog = progIsNode(content, shimDir);
+      if (!prog.ok) {
+        return null;
+      }
+      nodeExec = prog.absolute;
+    } else {
+      const expanded = expandShimPath(interpreter, shimDir) ?? interpreter;
+      if (!isNodeInterpreter(expanded)) {
+        return null;
+      }
+      if (path.win32.isAbsolute(interpreter)) {
+        nodeExec = interpreter;
+      }
+    }
+    const args = [];
+    let expandable = true;
+    for (const word of words.slice(1)) {
+      const expanded = literalToken(word, shimDir);
+      if (expanded === null) {
+        expandable = false;
+        break;
+      }
+      args.push(expanded);
+    }
+    if (!expandable || args.length === 0) {
+      return null;
+    }
+    return { args, ...nodeExec ? { nodeExec } : {} };
+  }
+}
+const REAL_DEPS = {
+  platform: process.platform,
+  readFileSync: (p) => fs.readFileSync(p, "utf-8"),
+  resolveOnPath: findOnPath,
+  execPath: process.execPath
+};
+function resolveSpawnPlan(command, args, env = process.env, deps = REAL_DEPS) {
+  if (deps.platform !== "win32") {
+    return { command, args };
+  }
+  let resolved = command;
+  if (!command.includes("/") && !command.includes("\\")) {
+    resolved = deps.resolveOnPath(command, env) ?? command;
+  }
+  if (!/\.(cmd|bat)$/i.test(path.win32.basename(resolved))) {
+    return { command: resolved, args };
+  }
+  let content;
+  try {
+    content = deps.readFileSync(resolved);
+  } catch {
+    return { command: resolved, args };
+  }
+  const target = parseCmdShimTarget(resolved, content);
+  if (!target) {
+    return { command: resolved, args };
+  }
+  return {
+    command: target.nodeExec ?? deps.execPath,
+    args: [...target.args, ...args]
+  };
+}
 const VISION_MODEL_PATTERNS = [
   "claude-*",
   "gpt-4o*",
@@ -1723,7 +1932,12 @@ function isVisionModel(modelId) {
 const DEFAULT_TTL_MS = 6 * 60 * 60 * 1e3;
 const CLI_TIMEOUT_MS = 1e4;
 function defaultRunCli(bin, args, timeoutMs) {
-  return execFileSync(bin, args, { encoding: "utf-8", timeout: timeoutMs, stdio: "pipe" });
+  const plan = resolveSpawnPlan(bin, args);
+  return execFileSync(plan.command, plan.args, {
+    encoding: "utf-8",
+    timeout: timeoutMs,
+    stdio: "pipe"
+  });
 }
 function timed(run) {
   const start = Date.now();
@@ -2295,11 +2509,19 @@ function piRoutes(home, env, targets = DEFAULT_TARGETS) {
 }
 function fetchPiKey(piPath, modelId, provider, timeoutMs) {
   try {
-    const key = execFileSync(
-      piPath,
-      ["auth", "print-api-key", "--model", modelId, "--provider", provider],
-      { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], timeout: timeoutMs }
-    ).trim();
+    const plan = resolveSpawnPlan(piPath, [
+      "auth",
+      "print-api-key",
+      "--model",
+      modelId,
+      "--provider",
+      provider
+    ]);
+    const key = execFileSync(plan.command, plan.args, {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: timeoutMs
+    }).trim();
     if (!key) {
       throw new Error("empty");
     }
@@ -2605,7 +2827,8 @@ function emptyWorkdir() {
 function runCommand(providerName, invocation, timeoutMs, describeFailure) {
   const runStartedAt = Date.now();
   return new Promise((resolve, reject) => {
-    const child = spawn(invocation.command, invocation.args, {
+    const plan = resolveSpawnPlan(invocation.command, invocation.args);
+    const child = spawn(plan.command, plan.args, {
       cwd: invocation.cwd,
       stdio: ["ignore", "pipe", "pipe"]
     });
@@ -2681,16 +2904,21 @@ function runCommand(providerName, invocation, timeoutMs, describeFailure) {
       clearTimeout(timer);
       clearTimeout(drainTimer);
       clearTimeout(killTimer);
-      if (error.code === "ENOENT") {
+      const code = error.code;
+      if (code === "ENOENT") {
         const missingCwd = !fs.existsSync(invocation.cwd);
         reject(
           new Error(
-            missingCwd ? `Working directory does not exist: ${invocation.cwd}` : `Provider CLI not found: ${invocation.command}. Install it and sign in first.`
+            missingCwd ? `Working directory does not exist: ${invocation.cwd}` : `Provider CLI not found: ${invocation.command} (spawn ENOENT). Install it and sign in first.`
           )
         );
         return;
       }
-      reject(error);
+      reject(
+        new Error(
+          `${providerName} provider could not start \`${invocation.command}\`: ${error.message}`
+        )
+      );
     });
     child.on("exit", (code) => {
       exitCode = code;
@@ -3351,6 +3579,43 @@ function runGuard(guards, options) {
   }
   return evaluateGuard(guards, detectActiveModel(options));
 }
+const SKILL_DIRS = [
+  ["claude-code", ".claude/skills"],
+  ["codex", ".codex/skills"],
+  ["pi/opencode", ".agents/skills"],
+  ["dsh", ".dsh/skills"]
+];
+function isOlder(pinned, current) {
+  const parse = (v) => v.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const [pa, pb, pc] = parse(pinned);
+  const [ca, cb, cc] = parse(current);
+  if (pa !== ca) return pa < ca;
+  if (pb !== cb) return pb < cb;
+  return pc < cc;
+}
+function readPinnedVersion(launcher) {
+  return /^PINNED="([^"]+)"/m.exec(launcher)?.[1] ?? null;
+}
+function findSkillInstalls(currentVersion, home = os.homedir(), skillName = "modlens") {
+  const installs = [];
+  for (const [harness, relative] of SKILL_DIRS) {
+    const launcher = path.join(home, relative, skillName, "scripts", "run.sh");
+    let text;
+    try {
+      text = fs.readFileSync(launcher, "utf-8");
+    } catch {
+      continue;
+    }
+    const pinned = readPinnedVersion(text);
+    installs.push({
+      harness,
+      path: launcher,
+      pinned,
+      outdated: pinned !== null && isOlder(pinned, currentVersion)
+    });
+  }
+  return installs;
+}
 const MIN_NODE = "22.19";
 function versionParts(version) {
   const match = /(\d+)\.(\d+)/.exec(version.replace(/^v/, ""));
@@ -3499,6 +3764,7 @@ function buildDoctorReport(input) {
       remote: composeChain("remote", input.config, reuseOptions).map(chainEntryName)
     },
     harness: { detected: harnessDetection.harness, source: harnessDetection.source },
+    skillInstalls: input.version ? findSkillInstalls(input.version, input.home) : [],
     guard: {
       rules: denyPatterns(input.config.guards).length,
       allowRules: allowPatterns(input.config.guards).length,
@@ -3563,6 +3829,18 @@ function renderDoctorReport(report) {
     report.harness.detected ? `  ${report.harness.detected} (via ${report.harness.source})` : `  none detected (${report.harness.source})`
   );
   lines.push("");
+  if (report.skillInstalls.length > 0) {
+    lines.push("Installed skill copies (a copy keeps its install-time version)");
+    for (const install of report.skillInstalls) {
+      const state = install.pinned === null ? "no pin found" : `pins ${install.pinned}`;
+      lines.push(`  ${install.harness}: ${state}${install.outdated ? "  [outdated]" : ""}`);
+    }
+    if (report.skillInstalls.some((install) => install.outdated)) {
+      lines.push("  Refresh an outdated copy by re-running the install: it overwrites in");
+      lines.push("  place. See https://github.com/liustack/modlens/blob/main/INSTALL.md");
+    }
+    lines.push("");
+  }
   lines.push("Guard (should the vision engine run for the active model?)");
   lines.push(
     `  rules: ${report.guard.rules} deny pattern(s), ${report.guard.allowRules} allow pattern(s)${report.guard.allowRules > 0 ? " (allowlist mode)" : ""}, denyWhenUnknown: ${report.guard.denyWhenUnknown}`
@@ -3794,7 +4072,7 @@ function parsePositiveInt(raw, flag) {
   }
   return Number.parseInt(raw, 10);
 }
-program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.16.1");
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("3.16.2");
 program.command("analyze", { isDefault: true }).description("Analyze an image into structured JSON evidence (default command)").requiredOption("-i, --input <path|url>", "Input image path or https URL").option("-o, --output <path>", "Write result JSON to a file").option("-m, --model <name>", "Provider model name").option("-p, --provider <name>", `Vision provider (${listProviders().join(", ")})`).option("--prompt <text>", "Extra focus for this image").option("--timeout <ms>", "Provider timeout in milliseconds", "180000").option("--provider-bin <path>", "Provider binary path (default: agy)").option("--workdir <path>", "Working directory for the provider").option(
   "--extra-body <json>",
   `JSON merged into the API request body, e.g. '{"thinking":{"type":"disabled"}}'`
@@ -3901,7 +4179,10 @@ program.command("doctor").description(
       config: loadConfigFile(),
       env: process.env,
       providerFlag: options.provider,
-      configPath: CONFIG_PATH
+      configPath: CONFIG_PATH,
+      // Lets doctor name an installed skill copy that is older than
+      // the CLI reporting on it (issue #33).
+      version: "3.16.2"
     });
     const output = options.json ? JSON.stringify(report, null, 2) : renderDoctorReport(report);
     process.stdout.write(`${output}

package/docs/troubleshooting.md

@@ -47,10 +47,10 @@ Wait for the reset, or move to `gemini-api`, which has its own budget. Parallel
 ## Provider CLI not found
 
 ```
-Provider CLI not found: agy. Install it and sign in first.
+Provider CLI not found: agy (spawn ENOENT). Install it and sign in first.
 ```
 
-The binary is not on PATH, or `--provider-bin` points somewhere wrong.
+The binary is not on PATH, or `--provider-bin` points somewhere wrong. A different spawn-level failure (`... could not start \`claude\`: spawn EACCES`) keeps its real error code so the cause is nameable. On Windows the npm-installed CLIs are `.cmd` shims; modlens resolves them through PATHEXT and runs their real Node entry directly, so neither the bare name (ENOENT) nor the `.cmd` (EINVAL) trips it up.
 
 ```
 Working directory does not exist: /some/path

package/docs/troubleshooting.zh-CN.md

@@ -47,10 +47,10 @@ agy's free tier is one weekly bucket shared by the desktop app, the CLI, and the
 ## 找不到 provider CLI
 
 ```
-Provider CLI not found: agy. Install it and sign in first.
+Provider CLI not found: agy (spawn ENOENT). Install it and sign in first.
 ```
 
-二进制不在 PATH 上，或者 `--provider-bin` 指错了地方。
+二进制不在 PATH 上，或者 `--provider-bin` 指错了地方。其他 spawn 级失败（`... could not start \`claude\`: spawn EACCES`）会保留真实错误码，方便定位。Windows 上 npm 装的 CLI 是 `.cmd` shim，modlens 通过 PATHEXT 解析并直接运行它背后的 Node 入口，所以裸名（ENOENT）和 `.cmd`（EINVAL）都不会卡住它。
 
 ```
 Working directory does not exist: /some/path

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@liustack/modlens",
-    "version": "3.16.1",
+    "version": "3.16.2",
     "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
     "type": "module",
     "bin": {

package/skills/modlens/SKILL.md

@@ -20,11 +20,11 @@ powershell -ExecutionPolicy Bypass -File <skill-dir>\scripts\run.ps1 <args>
 
 It resolves a working runtime (PATH `modlens`, then `npx`, then `bunx`) and forwards your arguments unchanged. Exit 78 means no runtime: relay the `nextSteps` from its stderr JSON instead of retrying.
 
-If your harness forbids running scripts, reason through the same order by hand and run the first line that works (the pinned version is 3.16.1):
+If your harness forbids running scripts, reason through the same order by hand and run the first line that works (the pinned version is 3.16.2):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.16.1: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.16.1 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.16.1 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.16.2: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.16.2 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.16.2 <args>`.
 4. Otherwise tell the user no JavaScript runtime was found and that installing Node 22.19+ (https://nodejs.org) or Bun (https://bun.sh) is the next step. Do not claim modlens itself failed.
 
 `references/runtime.md` documents the pin and the diagnostic fields.

package/skills/modlens/references/runtime.md

@@ -8,7 +8,7 @@ shell syntax.
 
 ## Pinned version
 
-- Pinned CLI version: 3.16.1
+- Pinned CLI version: 3.16.2
 - npm package: `@liustack/modlens`
 - CLI binary name: `modlens`
 

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.16.1'
+$Pinned = '3.16.2'
 # -------------------------------------------------------------------------------
 
 $NativeNote = 'no native artifact is published for this tool yet; phase A ships npm launch paths only'

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.16.1"
+PINNED="3.16.2"
 # -------------------------------------------------------------------------------
 
 NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"