@liustack/modlens 3.16.6 → 3.16.7

package/dsh/index.js

@@ -11,7 +11,9 @@
 // package.json `dsh.bundle` manifest). Providers, reuse grants, and guard
 // rules keep living in ~/.modlens/config.json, shared with every harness.
 import { spawn } from 'node:child_process'
-import { readFileSync } from 'node:fs'
+import { chmodSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const CLI_PATH = fileURLToPath(new URL('../dist/main.js', import.meta.url))
@@ -59,14 +61,29 @@ export function apply(ctx, config = {}) {
   // optional-inject form, so the route rides a scoped ctx.inject: the closure
   // runs when the service appears and never runs where it does not (headless
   // stays untouched, and the plugin itself never waits on it).
-  if (config.pasteToPath !== false && typeof ctx.inject === 'function') {
+  if (typeof ctx.inject === 'function') {
     ctx.inject(['webServer'], (scope) => {
-      try {
-        // scope carries webServer; the plugin's own ctx carries llm for the
-        // takeover verdicts.
-        registerPasteRoute(scope, ctx, ownProviders)
-      } catch (error) {
-        console.error(`[modlens] paste-to-path route skipped: ${error}`)
+      if (config.pasteToPath !== false) {
+        try {
+          // scope carries webServer; the plugin's own ctx carries llm for the
+          // takeover verdicts.
+          registerPasteRoute(scope, ctx, ownProviders)
+        } catch (error) {
+          console.error(`[modlens] paste-to-path route skipped: ${error}`)
+        }
+      }
+      // Same web server, a separate switch: turning paste-to-path off is a
+      // statement about how images enter, not about whether the engine can
+      // be configured. dsh's own settings surface renders a hardcoded set of
+      // cards and does not enumerate namespaces, so the card the browser half
+      // contributes talks to this route rather than to a settings schema
+      // (issue #39).
+      if (config.settingsCard !== false) {
+        try {
+          registerConfigRoute(scope)
+        } catch (error) {
+          console.error(`[modlens] settings card route skipped: ${error}`)
+        }
       }
     })
   }
@@ -850,3 +867,354 @@ function renderEvidence(value) {
   }
   return lines.join('\n')
 }
+
+// The engines a user can pick in the settings card, in the order the docs
+// introduce them. Kept to the names modlens itself uses so the card and
+// `modlens doctor` say the same words.
+const ENGINES = ['antigravity-cli', 'gemini-api', 'openai', 'anthropic', 'claude-cli']
+// The two CLI engines sign in through their own tool, so a key or an endpoint
+// would be a field with nothing behind it. Both still take a model.
+const KEYLESS_ENGINES = ['antigravity-cli', 'claude-cli']
+// Every accepted spelling, mirroring src/providers/index.ts. Settings saved
+// under an alias are the same engine's settings, and a provider pinned by an
+// alias is pinned to that engine: showing either as something else would put
+// the card at odds with what actually reads the images.
+const ENGINE_ALIASES = {
+  antigravity: 'antigravity-cli',
+  agy: 'antigravity-cli',
+  gemini: 'gemini-api',
+  'openai-compat': 'openai',
+  claude: 'anthropic',
+  'claude-code': 'claude-cli',
+}
+
+/** The canonical engine a stored name means, or '' when it names none. */
+function canonicalEngine(name) {
+  if (typeof name !== 'string') return ''
+  const trimmed = name.trim().toLowerCase()
+  if (ENGINES.includes(trimmed)) return trimmed
+  return ENGINE_ALIASES[trimmed] ?? ''
+}
+
+/** The config keys holding one engine's settings: its own, plus its aliases. */
+function settingsKeysFor(engine) {
+  const aliases = Object.keys(ENGINE_ALIASES).filter((alias) => ENGINE_ALIASES[alias] === engine)
+  return [...aliases, engine]
+}
+// Auto mode: the local harnesses whose logins a read may borrow. `claude`
+// absent counts as granted, since claude-cli predates the grant model.
+const REUSE_HARNESSES = ['claude', 'codex', 'opencode', 'pi', 'grok']
+
+/** ~/.modlens/config.json, the one file every harness shares. */
+function modlensConfigPath() {
+  return join(homedir(), '.modlens', 'config.json')
+}
+
+/**
+ * The shared config, or a thrown error. Only a missing file reads as empty:
+ * a file that exists but cannot be parsed or read is somebody's configuration,
+ * and a settings card that treated it as empty would overwrite it on the next
+ * save. The card shows the error instead.
+ */
+function readModlensConfig() {
+  let raw
+  try {
+    raw = readFileSync(modlensConfigPath(), 'utf8')
+  } catch (error) {
+    if (error?.code === 'ENOENT') return {}
+    throw new Error(`cannot read ${modlensConfigPath()}: ${error?.message ?? error}`)
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`${modlensConfigPath()} is not valid JSON: ${error?.message ?? error}`)
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${modlensConfigPath()} does not hold a JSON object`)
+  }
+  return parsed
+}
+
+/**
+ * What the card is allowed to know. Every engine's endpoint and model, plus
+ * whether a key is stored, and never the key itself: a browser that cannot
+ * read a secret cannot leak one, and cannot write it back either.
+ */
+function engineSummary(config = readModlensConfig()) {
+  const engines = {}
+  for (const name of ENGINES) {
+    // Alias first, canonical last: the canonical key wins on conflict, the
+    // same order resolveProviderSettings uses.
+    const settings = Object.assign({}, ...settingsKeysFor(name).map((key) => config.providers?.[key] ?? {}))
+    engines[name] = {
+      baseUrl: typeof settings.baseUrl === 'string' ? settings.baseUrl : '',
+      model: typeof settings.model === 'string' ? settings.model : '',
+      hasKey: typeof settings.apiKey === 'string' && settings.apiKey !== '',
+    }
+  }
+  const reuse = {}
+  for (const harness of REUSE_HARNESSES) {
+    const granted = config.reuse?.[harness]
+    reuse[harness] = typeof granted === 'boolean' ? granted : harness === 'claude'
+  }
+  // Three states, kept apart: pinned to an engine, pinned by one of its
+  // aliases (reported canonically), or not pinned at all, which is its own
+  // answer and means the failover chain decides. Collapsing the third into
+  // the first pins an engine the user never chose.
+  return {
+    provider: canonicalEngine(config.provider),
+    engines,
+    keyless: KEYLESS_ENGINES,
+    reuse,
+  }
+}
+
+/**
+ * Apply one card submission to the shared file. Only the named engine's own
+ * three fields are touched, so switching engines in the card cannot copy one
+ * engine's endpoint onto another. An absent or empty `apiKey` leaves the
+ * stored one alone: the card never receives a key, so it must never be able
+ * to clear one by submitting the blank field it was shown.
+ */
+function applyEngineSettings(patch) {
+  const config = readModlensConfig()
+  // The pin moves only when the card says it moved. A save that carried the
+  // currently displayed engine regardless turned "not pinned" into a pin on
+  // whatever happened to be shown, changing which engine reads every later
+  // image without the user asking for it.
+  if (patch?.provider !== undefined) {
+    if (patch.provider === '') {
+      delete config.provider
+    } else if (ENGINES.includes(patch.provider)) {
+      config.provider = patch.provider
+    } else {
+      throw new Error(`unknown engine: ${patch.provider}`)
+    }
+  }
+  // Engine fields are edited one engine at a time, named by `engine`. Absent
+  // means this save touched no engine settings, which is what a reuse-only
+  // save looks like.
+  const engine = patch?.engine
+  if (engine !== undefined) {
+    if (!ENGINES.includes(engine)) {
+      throw new Error(`unknown engine: ${engine}`)
+    }
+    config.providers = { ...config.providers }
+    // Write where this engine's settings already live, so a key saved under
+    // an alias is updated rather than shadowed by a second copy.
+    // Write where the read takes effect. settingsKeysFor merges aliases
+    // first and the canonical key last, so the canonical value wins; picking
+    // the first existing key instead wrote a new value underneath an older
+    // canonical one, which saved successfully and changed nothing. Both CLI
+    // spellings existing at once is ordinary: `config set gemini.apiKey`
+    // then `config set gemini-api.apiKey` leaves exactly that.
+    const holders = settingsKeysFor(engine).filter((key) => config.providers[key] !== undefined)
+    const target = holders.length > 0 ? holders[holders.length - 1] : engine
+    const settings = { ...config.providers[target] }
+    for (const field of ['baseUrl', 'model']) {
+      const value = typeof patch[field] === 'string' ? patch[field].trim() : ''
+      if (value === '') {
+        delete settings[field]
+      } else {
+        settings[field] = value
+      }
+    }
+    const apiKey = typeof patch.apiKey === 'string' ? patch.apiKey.trim() : ''
+    if (apiKey !== '') {
+      settings.apiKey = apiKey
+    }
+    config.providers[target] = settings
+  }
+  // Auto mode, when the card sent it: only the harnesses this build knows,
+  // only booleans, so an unexpected key cannot land in the shared file.
+  if (patch?.reuse !== null && typeof patch?.reuse === 'object') {
+    config.reuse = { ...config.reuse }
+    for (const harness of REUSE_HARNESSES) {
+      const granted = patch.reuse[harness]
+      if (typeof granted === 'boolean') {
+        config.reuse[harness] = granted
+      }
+    }
+  }
+  const file = modlensConfigPath()
+  // A symlink here would write through to wherever it points, so it is
+  // refused rather than followed: the CLI writes a real file, and anything
+  // else is a setup this card should not silently honor.
+  try {
+    if (lstatSync(file).isSymbolicLink()) {
+      throw new Error(`${file} is a symlink; edit the file it points at instead`)
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error
+  }
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 })
+  try {
+    chmodSync(file, 0o600)
+  } catch {
+    // Windows has no POSIX bits; the mode on the write above is all there is.
+  }
+}
+
+/**
+ * GET /modlens/config: the engine summary above. POST: one submission.
+ *
+ * The dsh web server listens on loopback, but a page in the same browser can
+ * still reach it, so a write requires a same-origin request: a cross-site POST
+ * could otherwise repoint someone's engine at an endpoint of its choosing.
+ * A read is refused the same way for symmetry, though it carries no secret.
+ */
+/**
+ * The self-check behind the card's auto-mode section: which local harnesses
+ * exist to be borrowed at all. `doctor --json` already probes them without
+ * network or quota, so the route spawns the CLI this package ships and lifts
+ * its reuse section. Cached briefly, since one probe can take a second and
+ * re-expanding the card should not re-pay it.
+ */
+const DISCOVERY_TTL_MS = 60_000
+let discoveryCache = null
+async function discoverReuse() {
+  if (discoveryCache !== null && Date.now() - discoveryCache.at < DISCOVERY_TTL_MS) {
+    return discoveryCache.value
+  }
+  try {
+    const { stdout, code } = await run(process.execPath, [CLI_PATH, 'doctor', '--json'], AbortSignal.timeout(30_000))
+    if (code !== 0) return null
+    const reuse = JSON.parse(stdout)?.reuse
+    if (!reuse || !Array.isArray(reuse.probes)) return null
+    // doctor names the harness claude-code; the grant key is claude.
+    const probes = reuse.probes.map((probe) => ({
+      harness: probe.harness === 'claude-code' ? 'claude' : probe.harness,
+      cliFound: probe.cliFound === true,
+      loggedIn: probe.loggedIn,
+      cliPath: typeof probe.cliPath === 'string' ? probe.cliPath : '',
+    }))
+    discoveryCache = { at: Date.now(), value: probes }
+    return probes
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Open the shared config file in whatever the OS considers its editor. The
+ * card's "open config file" link lands here: the path never has to be
+ * explained to the user, they just get the file. Created empty first when
+ * missing, so the editor has something to open.
+ */
+function openConfigFile() {
+  const file = modlensConfigPath()
+  try {
+    lstatSync(file)
+  } catch {
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, '{}\n', { mode: 0o600 })
+  }
+  const [command, args] =
+    process.platform === 'darwin'
+      ? ['open', [file]]
+      : process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', file]]
+        : ['xdg-open', [file]]
+  spawn(command, args, { detached: true, stdio: 'ignore' }).unref()
+}
+
+/** localhost, ::1, or anything in 127/8, matching dsh's own /api fence. */
+function isLoopbackHost(hostname) {
+  if (hostname === 'localhost' || hostname === '[::1]') return true
+  const parts = hostname.split('.')
+  return (
+    parts.length === 4 && parts[0] === '127' && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+  )
+}
+
+/**
+ * The same fence dsh puts in front of its own /api, for the same two
+ * confused-deputy paths. Host is the header DNS rebinding cannot forge, so it
+ * must name a loopback authority: a rebound page reaches this socket carrying
+ * its own domain there. Origin and Sec-Fetch-Site then rule out a cross-site
+ * page on the machine itself. A dsh serving a LAN address configures
+ * trustedHosts for /api; this route stays loopback-only, since nothing about
+ * editing an API key wants a wider door.
+ */
+function isTrustedRequest(req) {
+  const host = req.headers?.host
+  if (typeof host !== 'string' || host === '') return false
+  let hostUrl
+  try {
+    hostUrl = new URL(`http://${host}`)
+  } catch {
+    return false
+  }
+  if (!isLoopbackHost(hostUrl.hostname)) return false
+  if (req.headers?.['sec-fetch-site'] === 'cross-site') return false
+  const origin = req.headers?.origin
+  if (origin === undefined) return true
+  try {
+    return new URL(origin).host === hostUrl.host
+  } catch {
+    return false
+  }
+}
+
+function registerConfigRoute(ctx) {
+  ctx.webServer.register({
+    name: 'modlens-config',
+    kind: 'exact',
+    path: '/modlens/config',
+    handler: async (req, res) => {
+      const send = (status, body) => {
+        res.writeHead(status, { 'content-type': 'application/json' })
+        res.end(JSON.stringify(body))
+      }
+      if (!isTrustedRequest(req)) {
+        send(403, { error: 'request refused: this route answers same-origin loopback only' })
+        return
+      }
+      if (req.method === 'GET') {
+        try {
+          const summary = engineSummary()
+          const wantsDiscovery = new URL(req.url, 'http://localhost').searchParams.has('discover')
+          if (wantsDiscovery) {
+            // null when the probe failed: the card then falls back to the
+            // plain grant list rather than showing nothing.
+            summary.discovery = await discoverReuse()
+          }
+          send(200, summary)
+        } catch (error) {
+          send(409, { error: String(error?.message ?? error) })
+        }
+        return
+      }
+      if (req.method !== 'POST') {
+        res.writeHead(405).end()
+        return
+      }
+      try {
+        const chunks = []
+        let total = 0
+        for await (const chunk of req) {
+          total += chunk.length
+          if (total > 64 * 1024) {
+            send(413, { error: 'config payload too large' })
+            req.destroy()
+            return
+          }
+          chunks.push(chunk)
+        }
+        const patch = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+        // The card's "open config file" link: an action, not a setting.
+        if (patch?.open === true) {
+          openConfigFile()
+          send(200, { opened: true })
+          return
+        }
+        applyEngineSettings(patch)
+        send(200, engineSummary())
+      } catch (error) {
+        send(400, { error: String(error?.message ?? error) })
+      }
+    },
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@liustack/modlens",
-    "version": "3.16.6",
+    "version": "3.16.7",
     "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.6):
+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.7):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.16.6: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.16.6 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.16.6 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.16.7: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.16.7 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.16.7 <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/configure.md

@@ -93,9 +93,13 @@ Any free Google account works; no Google AI Pro needed. Sign-in cannot be automa
 
 ```bash
 modlens config set gemini-api.apiKey <key>
+# value omitted: a hidden prompt, so the key skips argv, shell history, and this chat
+modlens config set gemini-api.apiKey
 # or environment: export GEMINI_API_KEY=<key>
 ```
 
+Offer the hidden prompt first when the user is at their own terminal. Most users paste the key into the chat because it is convenient, and that works too: take it and store it. The prompt is for the ones who would rather not.
+
 Default model `gemini-3.6-flash` has vision on the free tier (about 10-15 requests/min, 1500/day). Free-tier data may be used by Google to improve products; mention this if the user handles sensitive images.
 
 ### openai (any OpenAI-compatible multimodal endpoint)

package/skills/modlens/references/configure.zh-CN.md

@@ -93,9 +93,13 @@ agy    # 用户需自己在浏览器完成登录，然后退出
 
 ```bash
 modlens config set gemini-api.apiKey <key>
+# 省略值：进入隐藏输入，密钥不进 argv、不进 shell 历史，也不进这段对话
+modlens config set gemini-api.apiKey
 # 或走环境变量：export GEMINI_API_KEY=<key>
 ```
 
+用户就在自己终端前时，先给隐藏输入这条。大多数人图方便还是会把 key 直接贴进对话，那也没问题：照收照存。隐藏输入是留给在乎的人的。
+
 默认模型 `gemini-3.6-flash` 在免费档就有视觉能力（约每分钟 10-15 次请求，每天 1500 次）。免费档的数据可能被 Google 用于改进产品，用户要处理敏感图片时请提醒这一点。
 
 ### openai（任意 OpenAI 兼容的多模态端点）

package/skills/modlens/references/onboard.md

@@ -27,7 +27,7 @@ Consent rules:
 - One question per decision, never a bundled yes. Reusing Codex and reusing pi credentials are two questions (or one question with independent options), not one.
 - Each question names the harness, whose quota it spends, and the accounting promise. Example wording: "Allow modlens to reuse your signed-in Codex CLI for image reads? Every reused read is labeled in the result so you always see whose quota was spent."
 - The do-nothing outcome must be safe and stated: "If you skip this, modlens just uses the engines you configure yourself."
-- If the user offers an API key, take exactly that key, and never go looking for keys they did not hand over.
+- When a key is needed, offer the clean path first, in one line: "Run `modlens config set gemini-api.apiKey` in your terminal and paste the key at the hidden prompt. It stays out of this chat and out of your shell history, and I never see it." Most users will paste the key into the chat anyway, because that is the convenient path, and that is fine: take exactly the key they hand over, use it, and never go looking for keys they did not. The offer is for the users who care, not a gate.
 
 ## 4. Apply only what was consented to
 

package/skills/modlens/references/runtime.md

@@ -8,7 +8,7 @@ shell syntax.
 
 ## Pinned version
 
-- Pinned CLI version: 3.16.6
+- Pinned CLI version: 3.16.7
 - 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.6'
+$Pinned = '3.16.7'
 # -------------------------------------------------------------------------------
 
 $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.6"
+PINNED="3.16.7"
 # -------------------------------------------------------------------------------
 
 NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"