dsh-moli 1.1.17 → 1.1.18

package/README.md

@@ -577,47 +577,6 @@ On the versions themselves: npm allows a version to be unpublished only briefly
 individually, so 1.1.11 and 1.1.12 remain installable but are marked deprecated and point here.
 `npm install dsh-moli` resolves to 1.1.13.
 
-## Releasing
-
-Publishing goes through GitHub Actions' OIDC identity, so **no npm token exists to expire**:
-
-```bash
-npm version patch          # or minor / major
-git push && git tag v1.1.6 && git push origin v1.1.6
-```
-
-`.github/workflows/publish.yml` checks that the tag matches `package.json`, runs the offline suites,
-and publishes. One-time setup on npmjs.com: **package → Settings → Trusted Publisher → GitHub
-Actions**, with user `27painter`, repository `dsh-moli`, workflow filename `publish.yml`, and the
-`npm publish` action allowed.
-
-**Do not publish with a stored token.** This machine was configured with a classic token that bypasses
-2FA, and npm is retiring those; when it was revoked, the publish failed with
-
-```
-E404 Not Found - PUT https://registry.npmjs.org/dsh-moli
-     The requested resource 'dsh-moli@1.1.5' could not be found or you do not have permission
-```
-
-which reads as a missing package and is actually an authorisation failure. Run
-`node scripts/preflight-publish.mjs` before any local publish: it reports whether the credential can
-authenticate and names that misleading 404 when it cannot.
-
-### Deprecating a version: do it on the website
-
-Publishing is scripted; deprecating deliberately is not. Use the package's page on npmjs.com —
-**package → Settings → Deprecate** — and name the versions and the reason.
-
-`npm deprecate dsh-moli@1.1.11 "…"` produces the same misleading failure as above when the local
-credential is dead, and there is a second reason not to reach for a token here. npm restricted
-2FA-bypass granular tokens from package-management operations on 31 July 2026, so the kind of token
-that used to make `deprecate` scriptable is being withdrawn, while `publish` has a supported
-token-free path through OIDC. A release process that needs a token only for the rare act of
-deprecating is a process that will be broken the next time it is needed, which is exactly what
-happened with 1.1.11 and 1.1.12.
-
-The 1.0.0 and 1.0.1 deprecations were done this way, from the website.
-
 ## License
 
 MIT. See [LICENSE](LICENSE).

package/README.zh.md

@@ -521,43 +521,6 @@ Chromium 后端、原始 CDP 逃生舱、按调用的 CDP 端点、持久化浏
 关于这两个版本本身：npm 只允许在很短的时间窗口内撤回发布，且无法单独撤回某一个版本，因此 1.1.11 与
 1.1.12 仍然可安装，但已被标记为废弃并指向这里。`npm install dsh-moli` 会安装到 1.1.13。
 
-## 发布
-
-发布走 GitHub Actions 的 OIDC 身份，**本机不存任何 npm token，因此没有会失效的凭据**：
-
-```bash
-npm version patch          # 或 minor / major
-git push && git tag v1.1.6 && git push origin v1.1.6
-```
-
-`.github/workflows/publish.yml` 会先校验 tag 与 `package.json` 版本一致、跑离线测试套件，然后发布。
-npmjs.com 上需要一次性配置：**package → Settings → Trusted Publisher → GitHub Actions**，用户
-`27painter`、仓库 `dsh-moli`、workflow 文件名 `publish.yml`，并允许 `npm publish` 动作。
-
-**不要再用本机存储的 token 发布。** 这台机器原先配的是一个绕过 2FA 的 classic token，npm 正在淘汰这类
-token；它被吊销后，发布会报：
-
-```
-E404 Not Found - PUT https://registry.npmjs.org/dsh-moli
-     The requested resource 'dsh-moli@1.1.5' could not be found or you do not have permission
-```
-
-**这看起来像"包不存在"，实际是认证失败。** 任何本地发布之前先跑
-`node scripts/preflight-publish.mjs`：它会告诉你凭据能否认证，不能时明确点出这个误导性的 404。
-
-### 废弃某个版本：去网站操作，别用命令行
-
-发布是脚本化的，**废弃则刻意不做成脚本**。用 npmjs.com 上的包页面——**package → Settings →
-Deprecate**——选版本、写理由。
-
-`npm deprecate dsh-moli@1.1.11 "…"` 在本机凭据失效时会给出上面那个同样误导的失败，而且这里还有第二个
-理由不要依赖 token：npm 在 **2026 年 7 月 31 日**起禁止 2FA-bypass 类型的 granular token 执行**包管理**
-操作，也就是说"以前能让 `deprecate` 脚本化"的那类凭据正在被取消；而 `publish` 有受支持的、免 token 的
-OIDC 路径。**一个只在"偶尔废弃版本"时才需要 token 的流程，注定在下次需要它时是坏的**——1.1.11 与 1.1.12
-遇到的正是这种情况。
-
-1.0.0 与 1.0.1 的废弃就是通过网站完成的。
-
 ## 许可
 
 MIT，见 [LICENSE](LICENSE)。

package/index.js

@@ -189,6 +189,7 @@ const FETCH_OUTPUT_SCHEMA = {
     sandboxTlsBlock: { type: 'boolean' },
     unreachable: { type: 'boolean' },
     possiblyUnreachable: { type: 'boolean' },
+    conditionTimedOut: { type: 'boolean' },
     note: { type: 'string' },
   },
 };
@@ -232,6 +233,10 @@ function renderFetch(_args, value) {
     if (value.sandboxTlsBlock === true) lines.push('Cause: the DSH sandbox blocks Schannel client credentials (HTTPS only).');
     if (value.unreachable === true) lines.push('Cause: the host did not answer; a local forward proxy is the usual fix on this network.');
     else if (value.possiblyUnreachable === true) lines.push('Cause: the host did not answer in time; it may be blocked, or the page may simply be slow.');
+    // A wait that never resolved is the one failure that is definitely not the
+    // network: the page arrived and was parsed. Saying so up front keeps the caller
+    // from spending their time on a proxy that was never the problem.
+    else if (value.conditionTimedOut === true) lines.push('Cause: the page loaded, but the wait condition never became true — this is not a network problem.');
     if (typeof value.hint === 'string' && value.hint !== '') lines.push(`Next: ${value.hint}`);
      // An HTTP error keeps its body under `failOnHttpError`. Reporting the failure
     // without the body would throw away the error page, which is the part worth

package/lib/moli.js

@@ -298,22 +298,44 @@ export function isSandboxTlsFailure(message) {
 }
 
 /**
- * Classify a transport failure as "the host never answered".
+ * Classify a transport failure: did the host never answer, or did a wait condition
+ * simply never become true?
  *
  * A blocked host fails at connect time (`Failed to connect`, reset, refused) or,
  * when the socket never opens, as a readiness timeout with nothing to show. A
  * readiness timeout can also mean a genuinely slow page, so that weaker case is
  * reported separately as {@link possiblyUnreachable}.
  *
+ * **But not every readiness timeout is about the network.** The engine reports the
+ * condition it was waiting for, and three of them mean the page was already there:
+ *
+ *     ... while waiting for a selector
+ *     ... while waiting for a script to become truthy
+ *     ... while waiting for a subresource response
+ *
+ * In those cases the document was fetched and parsed; what did not happen is the
+ * selector appearing, the script becoming true, or the matching response arriving.
+ * Telling the caller to retry or configure a proxy then sends them to look at their
+ * network for a problem that is in their selector -- measured: `waitSelector` on an
+ * element that is not on the page used to report "the host did not answer in time".
+ * A timeout "while waiting for response headers" is the opposite case and stays
+ * classified as possibly unreachable, because that one really is the server.
+ *
  * @param message - condensed stderr text.
- * @returns whether a connect-time failure was reported, and whether any timeout was.
+ * @returns `unreachable` (connect-time), `possiblyUnreachable` (network timeout), and
+ *   `conditionTimedOut` (a wait that the page itself never satisfied).
  */
 export function isUnreachableFailure(message) {
   const text = String(message);
   const connectFailure = /Failed to connect|Could not connect|Connection was reset|Connection refused/iu.test(text);
+  const anyTimeout = /Timeout was reached|readiness timed out/iu.test(text);
+  const conditionTimedOut = /readiness timed out .*?while waiting for (?:a selector|a script|a subresource response)/iu.test(text);
   return {
     unreachable: connectFailure,
-    possiblyUnreachable: connectFailure || /Timeout was reached|readiness timed out/iu.test(text),
+    // A condition timeout is not evidence about the network: the page arrived. Only
+    // the remaining timeouts are worth mentioning as a reachability possibility.
+    possiblyUnreachable: connectFailure || (anyTimeout && !conditionTimedOut),
+    conditionTimedOut,
   };
 }
 
@@ -609,7 +631,7 @@ export function runFetch(options) {
     // the socket never opens, as a readiness timeout with nothing to show. A
     // readiness timeout can also mean a genuinely slow page, so it is reported
     // as *possibly* unreachable and worded as a suggestion rather than a verdict.
-    const { unreachable, possiblyUnreachable } = isUnreachableFailure(stderr);
+    const { unreachable, possiblyUnreachable, conditionTimedOut } = isUnreachableFailure(stderr);
     // The engine reports a thrown expression as
     //   `Reason: JavaScript evaluation failed: TypeError: ... at <anonymous>:1:6`
     // which is a bug in the call, not an install or network problem. Falling
@@ -620,15 +642,27 @@ export function runFetch(options) {
     // status 1" leaves the caller to guess whether an image exists; the useful fact
     // is that it does not, and that a text dump would have captured this page.
     const binaryFailure = isBinary && httpStatusFrom(stderr) !== undefined;
+    // Name the wait that never resolved. "Retry or set a proxy" is actively
+    // misleading here: the page arrived, so the network is fine, and the caller
+    // would spend their time on the one part of the setup that is working.
+    const conditionHint = args.waitSelector !== undefined
+      ? `The selector ${JSON.stringify(args.waitSelector)} never matched. The page loaded, so this is not a network problem: check the spelling, and confirm the element is there with \`selector\` (it reports the match count, where a wait only times out) or \`dump\`.`
+      : args.waitScript !== undefined
+        ? 'The wait expression never became truthy. The page loaded, so this is not a network problem: check the expression against the page with `eval`, and remember it is polled rather than evaluated once.'
+        : (args.waitResponseUrl !== undefined || args.waitResponseJson !== undefined)
+          ? 'No response matching that condition arrived. The page loaded, so this is not a network problem: the request may never be made, or its payload may differ from what you matched on. Use `dump` with a short timeout to see what the page does, or an `eval` that inspects the fetch.'
+          : 'The wait condition never became true. The page loaded, so this is not a network problem: check the condition.';
     const hint = evalFailure
       ? 'The eval expression threw. Check that the page has reached the state you expect (`wait` or `waitSelector`), that the selector matches an element, and that the expression is valid JavaScript. The engine error names the type and position.'
       : binaryFailure
         ? 'The engine could not render this page, so no file was written. An HTTP error still produces a body for a text dump (markdown, html or json), so ask for one of those if you need to see what the server returned.'
         : sandboxTls
           ? 'The DSH file sandbox blocks Schannel client credentials, so moli cannot do TLS at low integrity. Retry the same call with sandbox_permissions "danger-full-access" (with a justification), use an http:// URL, or pass proxy to reach a local forward proxy.'
-          : possiblyUnreachable
-            ? 'The host did not answer in time. Reachability to some hosts varies on this network, so retrying may succeed; if a local forward proxy is available, setting the plugin config field `proxy` is the other option. A certificate problem would report a schannel error instead of a timeout.'
-            : 'Run moli_probe to confirm the install, then retry; use waitSelector or eval for a page that renders late.';
+          : conditionTimedOut
+            ? conditionHint
+            : possiblyUnreachable
+              ? 'The host did not answer in time. Reachability to some hosts varies on this network, so retrying may succeed; if a local forward proxy is available, setting the plugin config field `proxy` is the other option. A certificate problem would report a schannel error instead of a timeout.'
+              : 'Run moli_probe to confirm the install, then retry; use waitSelector or eval for a page that renders late.';
     const failureStatus = httpStatusFrom(stderr);
     return {
       ok: false,
@@ -638,6 +672,7 @@ export function runFetch(options) {
       sandboxTlsBlock: sandboxTls,
       unreachable,
       possiblyUnreachable,
+      ...(conditionTimedOut ? { conditionTimedOut: true } : {}),
       ...(evalFailure ? { evalFailed: true } : {}),
       hint,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-moli",
-  "version": "1.1.17",
+  "version": "1.1.18",
   "type": "module",
   "description": "DeepSeek Harness tools for the local Moli headless browser: rendered fetches, markdown, semantic trees, screenshots, and PDFs.",
   "license": "MIT",