dsh-moli 1.0.5 → 1.1.0

package/README.md

@@ -58,17 +58,57 @@ dsh plugin --profile web add github:27painter/dsh-moli
 ```
 
 > [!IMPORTANT]
-> **This package is the plugin only — it does not include the Moli engine.** It is 26 kB of
-> JavaScript; `moli.exe` is a separate ~101 MB Rust binary with its own release process. Installing the
-> plugin does not install Moli, and `moli_fetch` reports that the engine is missing until you install
-> it.
+> **The npm package is the plugin only — it does not contain the Moli engine.**
 >
-> **There is no npm package for the engine.** The registry names `moli` and `moli-cli` belong to
+> The npm tarball is 26 kB: eight JavaScript and text files. `moli.exe` is a separate ~101 MB compiled
+> Rust binary, built and released by the Moli project on its own schedule.
+>
+> **Why it cannot be bundled:**
+>
+> - **Size.** The engine is roughly 4,000× the plugin. Every install and every plugin update would
+>   carry a browser.
+> - **Ownership.** Moli is `lexmount/moli` under its own MIT copyright. Redistributing its binary
+>   through this package would mean re-publishing someone else's artifact as our own.
+> - **Platforms.** The engine ships per OS and per architecture — Windows/Linux/macOS × x64/arm64.
+>   Bundling would pin one build into every user's install.
+> - **Versions.** The plugin must work with whatever Moli version a user has, including Moli releases
+>   that appear after the plugin was published. Bundling would lock the pair together.
+>
+> **There is no npm package for the engine either.** The registry names `moli` and `moli-cli` belong to
 > unrelated projects, and `@lexmount/moli` does not exist. Moli ships as prebuilt binaries on
 > [GitHub Releases](https://github.com/lexmount/moli/releases/latest) — do not install the engine by
 > guessing a package name.
 
-Either route ends the same way. Restart DSH, then check the engine and fetch a page:
+## The two situations after installing
+
+The two download routes above install the same thing. What differs is whether Moli is already on the
+machine — and that decides whether you are finished or have one more step.
+
+### Situation A — Moli is already installed: nothing else to do
+
+The plugin discovers `moli.exe` on its own and both tools work immediately. Just restart DSH and
+confirm:
+
+```
+moli_probe
+```
+
+If the reported version looks right, you are done.
+
+### Situation B — Moli is not installed yet: fetch the engine too
+
+`moli_fetch` will keep reporting a missing engine until you install one. Do that with either of:
+
+```
+moli_probe action=install          # let the plugin fetch it
+```
+
+```powershell
+# or run Moli's own installer yourself
+powershell -ExecutionPolicy ByPass -c "irm https://github.com/lexmount/moli/releases/latest/download/moli-installer.ps1 | iex"
+```
+
+Then confirm with `moli_probe` and fetch a page:
 
 ```
 moli_probe
@@ -215,6 +255,17 @@ capabilities always visible to the model.
    resolves against the plugin directory instead of the profile's `node_modules` and the plugin
    fails to load. This plugin imports only `node:` builtins and its own files.
 
+## Platform support
+
+Works on **Windows, Linux and macOS** (x64 / arm64).
+
+- **Windows** — the engine is located at the official installer paths (`%LOCALAPPDATA%\Moli\bin\moli.exe`,
+  `%USERPROFILE%\.local\bin\moli.exe`) with a recursive scan of `%LOCALAPPDATA%\Moli` as a fallback.
+  `moli_probe action=install` runs the official PowerShell installer.
+- **Linux / macOS** — the engine is found in the standard locations (`~/.local/bin/moli`,
+  `~/.local/share/moli/bin/moli`, `~/.local/share/moli/moli`, `~/.moli/bin/moli`) and on `$PATH`.
+  `moli_probe action=install` runs the official `moli-installer.sh` via `sh`.
+
 ## Configuration
 
 Override any field under the plugin's `config` entry in the profile patch layer. All are optional.
@@ -237,9 +288,14 @@ installation under a versioned subdirectory is still found.
 
 ## Known limitations
 
-- **Windows-only targeting.** Developed and tested on Windows; the executable discovery, the
-  file-descriptor workaround, and the Schannel notes are Windows-specific. Nothing prevents a
-  POSIX port, but it is untested.
+- **Linux and macOS are implemented but not tested by the author.** The POSIX paths were contributed
+  in [PR #1](https://github.com/27painter/dsh-moli/pull/1) and reviewed, but the person who maintains
+  this repository is a student with **no macOS or Linux machine**, so those code paths have never been
+  run against a real POSIX host. Windows is the only platform verified here: the executable discovery,
+  the file-descriptor workaround and the Schannel notes are Windows-specific observations.
+  **If something fails on Linux or macOS, please open an
+  [issue](https://github.com/27painter/dsh-moli/issues) with the error output** — that is the only way
+  these paths get fixed.
 - **Moli itself is not bundled.** Install it separately or let `moli_probe action=install` fetch it.
 - **Only `fetch` is wrapped.** `moli serve` (CDP/WebDriver server) and `moli import` (session
   import) are not exposed as tools yet.

package/README.zh.md

@@ -53,14 +53,53 @@ dsh plugin --profile web add github:27painter/dsh-moli
 ```
 
 > [!IMPORTANT]
-> **这个包只有插件，不含 Moli 引擎。** 它是 26 kB 的 JavaScript；`moli.exe` 是另一个约 101 MB 的 Rust
-> 二进制、有自己的发布流程。装插件**不会**顺带装上 Moli，在你装引擎之前 `moli_fetch` 会一直报"引擎缺失"。
+> **npm 包只有插件，不含 Moli 引擎。**
 >
-> **引擎没有 npm 包。** registry 上的 `moli` 和 `moli-cli` 属于无关项目，`@lexmount/moli` 并不存在。
-> Moli 以预编译二进制形式发布在
+> npm tarball 是 26 kB：八个 JavaScript 与文本文件。`moli.exe` 是另外的东西——约 101 MB 的 Rust 编译
+> 产物，由 Moli 项目按自己的节奏构建和发布。
+>
+> **为什么不能打包进来：**
+>
+> - **体积。** 引擎约为插件的 4,000 倍。每次安装、每次插件更新都要顺带搬运一个浏览器。
+> - **归属。** Moli 是 `lexmount/moli`，版权属于它自己的 MIT 署名。把它家的二进制经由本包再分发，等于
+>   把别人的产物当自己的发布。
+> - **平台。** 引擎按操作系统与架构分别发布——Windows/Linux/macOS × x64/arm64。打包进来等于把某一个
+>   构建方式钉死给所有用户。
+> - **版本。** 插件要能配合用户手上**任意** Moli 版本工作，包括插件发布之后才出现的 Moli 新版本。
+>   打包会把两者的版本绑死。
+>
+> **引擎同样没有 npm 包。** registry 上的 `moli` 和 `moli-cli` 属于无关项目，`@lexmount/moli` 并不
+> 存在。Moli 以预编译二进制形式发布在
 > [GitHub Releases](https://github.com/lexmount/moli/releases/latest)——**不要靠猜包名去装引擎**。
 
-两种方式都要重启 DSH，然后自检并抓一个页面：
+## 装好之后的两种情形
+
+上面两条下载路线装的是同一个东西。区别在于**你的机器上有没有 Moli**——这决定你是就此完事，还是还差一步。
+
+### 情形 A —— 已经装了 Moli：不用再做别的
+
+插件自己会找到 `moli.exe`，两个工具立即可用。重启 DSH 然后确认：
+
+```
+moli_probe
+```
+
+如果报出来的版本正常，就结束了。
+
+### 情形 B —— 还没装 Moli：把引擎也拉下来
+
+在你装上引擎之前，`moli_fetch` 会一直报"引擎缺失"。用下面任一种装上：
+
+```
+moli_probe action=install          # 让插件替你拉
+```
+
+```powershell
+# 或者自己跑 Moli 官方的安装器
+powershell -ExecutionPolicy ByPass -c "irm https://github.com/lexmount/moli/releases/latest/download/moli-installer.ps1 | iex"
+```
+
+然后用 `moli_probe` 确认并抓一个页面：
 
 ```
 moli_probe
@@ -197,6 +236,15 @@ Moli 仓库自带官方 agent skill：[`moli-webfetch`](https://github.com/lexmo
    导入（例如 `@deepseek-ai/schemastery`）都会解析到插件目录而非 profile 的 `node_modules`，导致
    插件加载失败。本插件只导入 `node:` 内置模块和自己的文件。
 
+## 平台支持
+
+支持 **Windows、Linux、macOS**（x64 / arm64）。
+
+- **Windows** —— 引擎在官方安装位置查找（`%LOCALAPPDATA%\Moli\bin\moli.exe` 与 `%USERPROFILE%\.local\bin\moli.exe`），
+  并以 `%LOCALAPPDATA%\Moli` 递归扫描兜底；`moli_probe action=install` 走官方 PowerShell 安装器。
+- **Linux / macOS** —— 引擎在标准位置（`~/.local/bin/moli`、`~/.local/share/moli/bin/moli`、
+  `~/.local/share/moli/moli`、`~/.moli/bin/moli`）与 `$PATH` 中查找；`moli_probe action=install` 通过 `sh` 执行官方 `moli-installer.sh`。
+
 ## 配置
 
 在 profile 的补丁层里覆盖 `config`，全部可选：
@@ -219,8 +267,12 @@ Moli 仓库自带官方 agent skill：[`moli-webfetch`](https://github.com/lexmo
 
 ## 已知限制
 
-- **面向 Windows。** 开发与验证都在 Windows 上；可执行文件探测、文件描述符绕坑、Schannel 说明都
-  与 Windows 相关。移植到 POSIX 没有障碍，但未经验证。
+- **Linux 与 macOS 已实现，但作者没有测过。** POSIX 相关代码来自
+  [PR #1](https://github.com/27painter/dsh-moli/pull/1)，已做代码审查，但本仓库维护者是一名**没有
+  macOS / Linux 电脑**的大学生，所以这些分支从未在真实的 POSIX 主机上运行过。这里唯一验证过的平台是
+  Windows：可执行文件探测、文件描述符绕坑与 Schannel 说明都是 Windows 上的观察。
+  **如果在 Linux 或 macOS 上出问题，请带上报错信息开
+  [issue](https://github.com/27painter/dsh-moli/issues)**——那是这些路径能被打通的唯一途径。
 - **不包含 Moli 本体。** 需自行安装，或让 `moli_probe action=install` 替你拉取。
 - **只封装了 `fetch`。** `moli serve`（CDP/WebDriver 服务器）与 `moli import`（会话导入）尚未做成工具。
 - **不支持单次取消。** 引擎是同步执行的，被中断的回合无法中途终止抓取；已在进行的调用会跑完并

package/index.js

@@ -1,4 +1,4 @@
-/** Host half of dsh-moli: expose the local `moli.exe` headless browser as callable tools. */
+/** Host half of dsh-moli: expose the local `moli` headless browser as callable tools. */
 import { MANUAL_INSTALL, installMoli } from './lib/install.js';
 import { findMoli, moliCandidates, probe, runFetch } from './lib/moli.js';
 
@@ -198,7 +198,7 @@ function renderProbe(_args, value) {
     return [{ type: 'text', text: lines.join('\n') }];
   }
   if (value.installed !== true) {
-    const lines = ['moli.exe was not found. Call moli_probe with action "install", or set the plugin config field `exePath`.'];
+    const lines = ['moli was not found. Call moli_probe with action "install", or set the plugin config field `exePath`.'];
     lines.push(`Manual install — PowerShell: ${MANUAL_INSTALL.powershell}`);
     lines.push(`Manual install — Linux/macOS: ${MANUAL_INSTALL.shell}`);
     return [{ type: 'text', text: lines.join('\n') }];
@@ -239,7 +239,7 @@ export function apply(ctx, config) {
   const insecureTls = options.insecureTls ?? DEFAULTS.insecureTls;
 
   if (cachedExe === undefined) {
-    ctx.logger?.warn?.('dsh-moli: moli.exe not found; moli_probe can install it, or set config.exePath');
+    ctx.logger?.warn?.('dsh-moli: moli not found; moli_probe can install it, or set config.exePath');
   }
 
   ctx.tools.register({
@@ -247,7 +247,7 @@ export function apply(ctx, config) {
     description: 'Fetch a URL with the local Moli headless browser: rendered HTML or Markdown, the semantic'
       + ' tree, a JSON envelope with status and final_url, a JavaScript expression result, a PNG screenshot, or a'
       + ' PDF. Use it for pages that need real rendering or JavaScript; prefer web_fetch for plain text. Screenshot'
-      + ' and pdf dumps require writeTo. If moli.exe is missing, run moli_probe with action "install" first.',
+      + ' and pdf dumps require writeTo. If moli is missing, run moli_probe with action "install" first.',
     parameters: FETCH_PARAMETERS,
     output: { schema: FETCH_OUTPUT_SCHEMA, render: renderFetch },
     isConcurrencySafe: args => args.writeTo === undefined || args.writeTo === '',
@@ -258,9 +258,9 @@ export function apply(ctx, config) {
         return {
           ok: false,
           url: args.url,
-          error: 'moli.exe was not found',
+          error: 'moli was not found',
           sandboxTlsBlock: false,
-          hint: 'Call moli_probe with action "install" to download it, or set the dsh-moli config field `exePath` to the absolute moli.exe path.',
+          hint: 'Call moli_probe with action "install" to download it, or set the dsh-moli config field `exePath` to the absolute moli path.',
           manualInstall: MANUAL_INSTALL,
         };
       }
@@ -279,7 +279,7 @@ export function apply(ctx, config) {
     description: 'Report the local Moli install: version, executable path, and whether HTTPS fetching works from'
       + ' this process. With action "install" it downloads and runs the official Moli installer instead, then'
       + ' reports the executable and the SHA256 of the installer it ran. Use "install" only when moli_fetch'
-      + ' reports that moli.exe is missing; it downloads and executes third-party code.',
+      + ' reports that moli is missing; it downloads and executes third-party code.',
     parameters: {
       type: 'object',
       additionalProperties: false,
@@ -321,7 +321,7 @@ export function apply(ctx, config) {
 
       const exe = engine();
       if (exe === undefined) {
-        return { installed: false, detail: 'moli.exe not found. Re-run with action "install" to download it.', manualInstall: MANUAL_INSTALL };
+        return { installed: false, detail: 'moli not found. Re-run with action "install" to download it.', manualInstall: MANUAL_INSTALL };
       }
       const result = probe(exe, 'https://example.com', insecureTls);
       return {
@@ -336,5 +336,5 @@ export function apply(ctx, config) {
     },
   });
 
-  ctx.logger?.info?.(`dsh-moli: registered moli_fetch and moli_probe (${cachedExe ?? 'moli.exe missing'})`);
+  ctx.logger?.info?.(`dsh-moli: registered moli_fetch and moli_probe (${cachedExe ?? 'moli missing'})`);
 }

package/lib/install.js

@@ -30,7 +30,9 @@ import { join } from 'node:path';
 import { findMoli, moliVersion } from './moli.js';
 
 /** Official installer for the latest release. */
-export const INSTALLER_URL = 'https://github.com/lexmount/moli/releases/latest/download/moli-installer.ps1';
+export const INSTALLER_URL = process.platform === 'win32'
+  ? 'https://github.com/lexmount/moli/releases/latest/download/moli-installer.ps1'
+  : 'https://github.com/lexmount/moli/releases/latest/download/moli-installer.sh';
 
 /** Moli's own README instructions, for the manual path. */
 export const MANUAL_INSTALL = {
@@ -136,7 +138,7 @@ export async function downloadInstaller(options) {
   const url = options.installerUrl ?? INSTALLER_URL;
   const configured = typeof options.proxy === 'string' && options.proxy.length > 0 ? options.proxy : undefined;
   const timeoutMs = options.timeoutMs ?? 60000;
-  const powershell = options.powershell ?? 'powershell.exe';
+  const powershell = options.powershell ?? (process.platform === 'win32' ? 'powershell.exe' : 'powershell');
 
   // Never hand a loopback URL to a proxy — with a stale system proxy setting the
   // request would go to a dead port and wait out the connect timeout. Windows
@@ -152,20 +154,22 @@ export async function downloadInstaller(options) {
     `${TLS_PRELUDE}${bypass} Invoke-WebRequest -UseBasicParsing ${extra} -Uri '${url}' -OutFile $env:MOLI_DL_TARGET -TimeoutSec ${String(Math.ceil(timeoutMs / 1000))}`,
   ];
 
-  const routes = [
-    {
-      method: 'Invoke-WebRequest (direct)',
-      command: powershell,
-      args: iwr(''),
-    },
-  ];
+  const routes = process.platform === 'win32'
+    ? [
+      {
+        method: 'Invoke-WebRequest (direct)',
+        command: powershell,
+        args: iwr(''),
+      },
+    ]
+    : [];
 
   // Only attempt proxy routes when something is actually listening there.
   let proxyAlive = false;
   if (configured !== undefined) {
     proxyAlive = await proxyListens(configured);
   }
-  if (configured !== undefined && proxyAlive) {
+  if (process.platform === 'win32' && configured !== undefined && proxyAlive) {
     routes.push({
       method: `Invoke-WebRequest (proxy ${configured})`,
       command: powershell,
@@ -173,14 +177,14 @@ export async function downloadInstaller(options) {
     });
   }
   routes.push({
-    method: 'curl.exe (direct)',
-    command: 'curl.exe',
+    method: 'curl (direct)',
+    command: process.platform === 'win32' ? 'curl.exe' : 'curl',
     args: ['-sSL', ...curlBypass, '--max-time', String(Math.ceil(timeoutMs / 1000)), '-o', target, url],
   });
   if (configured !== undefined && proxyAlive) {
     routes.push({
-      method: `curl.exe (proxy ${configured})`,
-      command: 'curl.exe',
+      method: `curl (proxy ${configured})`,
+      command: process.platform === 'win32' ? 'curl.exe' : 'curl',
       args: ['-sSL', ...curlBypass, '--max-time', String(Math.ceil(timeoutMs / 1000)), '--proxy', configured, '-o', target, url],
     });
   }
@@ -242,7 +246,7 @@ export async function downloadInstaller(options) {
 export async function installMoli(options = {}) {
   const timeoutMs = options.timeoutMs ?? 180000;
   const workDir = mkdtempSync(join(tmpdir(), 'dsh-moli-install-'));
-  const target = join(workDir, 'moli-installer.ps1');
+  const target = join(workDir, process.platform === 'win32' ? 'moli-installer.ps1' : 'moli-installer.sh');
   try {
     const download = await downloadInstaller({
       target,
@@ -279,9 +283,11 @@ export async function installMoli(options = {}) {
       }
     }
 
-    const run = spawnSync(options.powershell ?? 'powershell.exe',
-      ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', target],
-      { stdio: ['ignore', 'ignore', 'ignore'], timeout: timeoutMs, windowsHide: true });
+    const run = process.platform === 'win32'
+      ? spawnSync(options.powershell ?? 'powershell.exe',
+          ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', target],
+          { stdio: ['ignore', 'ignore', 'ignore'], timeout: timeoutMs, windowsHide: true })
+      : spawnSync('sh', [target], { stdio: ['ignore', 'ignore', 'ignore'], timeout: timeoutMs });
     const runFailed = run.error !== undefined && run.error !== null;
     const runStatus = runFailed ? null : (run.status ?? 0);
 
@@ -294,7 +300,7 @@ export async function installMoli(options = {}) {
         ok: false,
         error: runFailed
           ? `running the installer failed: ${run.error.message}`
-          : `the installer ${runStatus === 0 ? 'reported success' : `exited ${String(runStatus)}`}, but no working moli.exe was found afterwards`,
+          : `the installer ${runStatus === 0 ? 'reported success' : `exited ${String(runStatus)}`}, but no working moli binary was found afterwards`,
         installerSha256: download.sha256,
         installerBytes: download.bytes,
         method: download.method,

package/lib/moli.js

@@ -16,7 +16,7 @@
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { closeSync, existsSync, mkdtempSync, openSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 
 /** Output formats that are bytes, not text. */
@@ -42,27 +42,44 @@ const WAIT_STAGES = new Set(['domcontentloaded', 'load', 'networkidle', 'domstab
  * @returns candidate paths, in probe order.
  */
 export function moliCandidates(override) {
+  const isWin = process.platform === 'win32';
+  const home = process.env.HOME ?? homedir();
   const listed = [
     override,
     process.env.MOLI_BIN,
-    process.env.LOCALAPPDATA === undefined ? undefined : join(process.env.LOCALAPPDATA, 'Moli', 'bin', 'moli.exe'),
-    process.env.USERPROFILE === undefined ? undefined : join(process.env.USERPROFILE, '.local', 'bin', 'moli.exe'),
+    // Windows: official installer location.
+    isWin && process.env.LOCALAPPDATA !== undefined ? join(process.env.LOCALAPPDATA, 'Moli', 'bin', 'moli.exe') : undefined,
+    isWin && process.env.USERPROFILE !== undefined ? join(process.env.USERPROFILE, '.local', 'bin', 'moli.exe') : undefined,
+    // Linux/macOS: installer.sh default ~/.local/bin/moli, plus versioned/shared dirs.
+    !isWin ? join(home, '.local', 'bin', 'moli') : undefined,
+    !isWin ? join(home, '.local', 'share', 'moli', 'bin', 'moli') : undefined,
+    !isWin ? join(home, '.local', 'share', 'moli', 'moli') : undefined,
+    !isWin ? join(home, '.moli', 'bin', 'moli') : undefined,
   ].filter(candidate => typeof candidate === 'string' && candidate.length > 0);
 
   const discovered = [];
-  const root = process.env.LOCALAPPDATA === undefined ? undefined : join(process.env.LOCALAPPDATA, 'Moli');
-  if (root !== undefined && existsSync(root)) {
-    let entries = [];
-    try {
-      entries = readdirSync(root, { recursive: true, withFileTypes: true });
-    } catch {
-      entries = [];
-    }
-    for (const entry of entries) {
-      if (entry.isFile() && entry.name.toLowerCase() === 'moli.exe') {
-        discovered.push(join(entry.parentPath ?? root, entry.name));
+  if (isWin) {
+    const root = process.env.LOCALAPPDATA === undefined ? undefined : join(process.env.LOCALAPPDATA, 'Moli');
+    if (root !== undefined && existsSync(root)) {
+      let entries = [];
+      try {
+        entries = readdirSync(root, { recursive: true, withFileTypes: true });
+      } catch {
+        entries = [];
+      }
+      for (const entry of entries) {
+        if (entry.isFile() && entry.name.toLowerCase() === 'moli.exe') {
+          discovered.push(join(entry.parentPath ?? root, entry.name));
+        }
       }
     }
+  } else {
+    const seen = new Set(listed);
+    for (const dir of String(process.env.PATH ?? '').split(':')) {
+      if (dir === '') continue;
+      const candidate = join(dir, 'moli');
+      if (existsSync(candidate) && !seen.has(candidate)) discovered.push(candidate);
+    }
   }
   return [...listed, ...discovered];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-moli",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "type": "module",
   "description": "DeepSeek Harness tools for the local Moli headless browser: rendered fetches, markdown, semantic trees, screenshots, and PDFs.",
   "license": "MIT",
@@ -26,7 +26,7 @@
     "url": "https://github.com/27painter/dsh-moli/issues"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=20.12"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",