dsh-browser-playwright-codex 0.5.3 → 0.5.4

package/CHANGELOG.md

@@ -3,6 +3,31 @@
 Bilingual by intent: the version headings and the summary of each release are given in both
 languages, the individual entries follow the language the surrounding code and docs use.
 
+## 0.5.4
+
+一句话摘要：**把第三方评审（2026-10-11，8.6/10）指出的"对外表述与现实脱节"修干净，并把这些说法变成守卫** —— 运行时行为零变化。但 README / SECURITY / NOTICE 是**随包发布**的，所以必须发一版：不发版，从 npm 装的用户看到的仍是那句"不在 npm 上"。
+
+### Fixed
+
+- **README 声称"这个包不在 npm 上"**（与同一文件里的 `# from npm` 自相矛盾）：包从 v0.5.1 起已在 npm 上。改为「From npm (published since v0.5.1)」并给出 npm 安装命令，仓库与本地 link 两种方式保留。
+- **NOTICE.md 的 7 个路径全部失效**（写成 `docs/PLUGIN-README.md`、`docs/DIALOG-POLICY.md` …，实际都在仓库根目录）：已按根相对路径改正。同一段里指向**上游文档**的 `docs/browser-safety.md` 保持原样 —— 那是给读者的来源索引，不是我们的文件。顺带修掉 `MODE-TRADE-OFFS.md` 里同类一处。
+- **README"安全一览"写死"2 Critical"**，而 dsh.so 当前扫描是 **1 Critical / 3 Warning / 22 Info**（v0.5.3、75 文件）：改为不含数字的说法。
+- **SECURITY.md §2 与表格按当前扫描重写**：Critical 就是 `browser_evaluate` 的动态求值（`src/session.ts` → `lib/session.js`，出厂关闭）、3 条 Warning、22 条 Info；v0.4.9 的 2/5/26 作为历史留在引用块里，并写明"以他们的报告为准"。
+- **SECURITY.md 里 `src/playwright.ts (~:2041)` 这类"文件名 + 行号"引用在 0.5.x 拆分后失效**（该文件现在 55 行）：改为模块名 —— 行号会漂，模块名不会。
+- **三份发帖草稿里的"2 个 Critical"**：去掉数字，改为"那个 Critical"。
+- **几处把上游文件写得像我们自己的**：`docs/articles/focus-stealing.md`、`patches/README.md`、`codex-rules.md` 里标明那是**上游仓库**的文件。
+- **README 增加 "Compatibility" 段**：写明构建与测试用的 DSH 版本是 `0.2.0-rc.1`、peer 范围故意留 `*`（换新版 harness 仍可安装）、升级后跑 `npm run doctor` 复核本插件导入的具名导出是否还在。
+
+### Added
+
+- **`tests/doc-reality.test.ts`（5 条守卫）**，把"文档对世界说的话"变成 CI 会拦的事实：
+  1. 现行文档不得声称"不在 npm 上"（CHANGELOG 是历史，跳过）；
+  2. README 必须给出 npm 安装路径（与第 1 条互为孪生）；
+  3. 反引号包着的仓库路径必须真的在那个位置（规则：该路径不存在、但同名文件在本仓库里存在才报 —— 不误伤上游引用；`./`、`../` 相对所在文档解析，其余相对仓库根）；
+  4. 文档里的「文件:行号」引用不得越界（行号 > 该文件现在的行数即报错 —— 正是 0.5.x 重构制造的那类腐烂）；
+  5. 带数字的 `N Critical` 只允许出现在 SECURITY.md（计数会变，其它文档一律用文字指过去）。
+  每条都做了"有牙复检"：把对应的旧文案塞回去，守卫立刻报红。
+
 ## 0.5.3
 
 一句话摘要：**源码按职责拆开、可维护性大幅提升，并修掉拆分过程中暴露的三处隐患** —— 对用户可见的行为零变化：工具面、配置接口、出厂默认值全部不动。本版同时修掉中文说明里一处会让人误判权限状态的过期说法。

package/README.md

@@ -31,16 +31,22 @@ dsh plugin --profile <name> add github:miqian-nomad/dsh-browser-playwright-codex
 - **强力工具默认关闭** — `browser_evaluate` / `browser_cdp` are **not registered at all** unless your
   deployment opts in; this package ships both off.
 
-**安全一览 / Security at a glance** — dsh.so's scanner reports *2 Critical* on this repository, and
-both findings **are** the implementation of `browser_evaluate`, which this package ships switched off.
-Every finding is explained gate by gate in [SECURITY.md](SECURITY.md), together with what the plugin
-can and cannot do with your logins (URL policy, CDP allow-list, dialog policy, no telemetry, and it
-never types passwords or 2FA codes).
+**安全一览 / Security at a glance** — dsh.so's scanner flags this repository's **one Critical finding**, and that finding **is** the
+implementation of `browser_evaluate` (its dynamic evaluation), which this package ships switched off.
+[SECURITY.md](SECURITY.md) maps every finding to the gate that contains it, and explains what the plugin
+can and cannot do with your logins (URL policy, CDP allow-list, dialog policy, no telemetry, and it never
+types passwords or 2FA codes). Counts move as the scanner and the code change — their own report is the
+live number.
 
 ## Install
 
-This package is **not on npm** — the repository is the distribution channel, so install it from GitHub
-(or link a checkout):
+From npm (published since v0.5.1 — [npmjs.com/package/dsh-browser-playwright-codex](https://www.npmjs.com/package/dsh-browser-playwright-codex)):
+
+```sh
+dsh plugin --profile <name> add dsh-browser-playwright-codex
+```
+
+Or straight from the repository / a checkout:
 
 ```sh
 dsh plugin --profile <name> add github:miqian-nomad/dsh-browser-playwright-codex
@@ -49,6 +55,10 @@ dsh plugin --profile <name> add github:miqian-nomad/dsh-browser-playwright-codex
 dsh plugin --profile <name> add link:<absolute path to this directory>
 ```
 
+**Compatibility.** Built and tested against DSH `0.2.0-rc.1` (`@deepseek-ai/*` peer ranges are deliberately
+`*` so a newer harness still installs). After a harness upgrade, `npm run doctor` re-checks that every named
+export this plugin imports still exists — that is the fast way to tell "the harness moved" from "the plugin broke".
+
 `lib/` ships in the repository (and there is deliberately no `prepare` hook), so a fresh clone loads
 without a build step — `npm run build` is only needed after editing `src/`.
 

package/SECURITY.md

@@ -4,7 +4,7 @@ This plugin drives a **real browser with your login state**. That is the point o
 the thing worth being careful about. This file answers the two questions a reader actually has:
 
 1. **What can it do to me?**
-2. **Why does dsh.so's scanner report "2 Critical"?**
+2. **Why does dsh.so's scanner report a Critical finding?**
 
 If you only read one line: **the two findings are the implementation of `browser_evaluate`, a tool
 this package ships switched off** — it is not registered at all until a deployment turns it on.
@@ -68,18 +68,22 @@ Nothing else.
 
 ---
 
-## 2. Why the scanner reports "2 Critical"
+## 2. What the scanner reports, and which gate contains it
 
-dsh.so runs `dsh-plugin-vet` over the whole repository. On v0.4.9 it reports **2 Critical, 5 Warning,
-26 Info** across 57 files — and it is **right about the capability**. Here is each one, with the gate
-that decides whether it is reachable at all.
+dsh.so runs `dsh-plugin-vet` over the whole repository. Their scan of **v0.5.3 (2026-10-11)** reports
+**1 Critical, 3 Warning, 22 Info** across 75 files — and it is **right about the capability**. Here is
+each one, with the gate that decides whether it is reachable at all.
+
+> For the record: their v0.4.9 scan — before this plugin was split into responsibility-scoped modules —
+> reported 2 Critical, 5 Warning, 26 Info across 57 files. Counts move as the scanner and the code
+> change; **their report is the live number**, and this table is a map, not a snapshot.
 
 | Level | Finding (as reported) | What it actually is | Reachable when |
 |---|---|---|---|
-| Critical | `new Function('return (' + expression + ')')` — `src/playwright.ts` (~:2041) and its `lib/` mirror | The body of **`browser_evaluate`**: it wraps your expression and runs it in the page. This is what "run JavaScript in the page" means; there is no way to implement it without dynamic evaluation. | Only when `allowEvaluate: true`. **The package ships `false`, so the tool is not registered.** |
-| Warning | `fs.writeFileSync` of a JSON blob (3 sites: `playwright.ts` ×2, `runtime-state.ts`) | Exporting the login state (`cookies` + `localStorage`) so a closed window can be reopened still logged in, and the small runtime state file behind the Settings switches. | Always — it is how login persistence works. The files live under your DSH home. |
+| Critical | `new Function('return (' + expression + ')')` — reported in `lib/session.js` (source: `src/session.ts`) | The body of **`browser_evaluate`**: it wraps your expression and runs it in the page. This is what "run JavaScript in the page" means; there is no way to implement it without dynamic evaluation. | Only when `allowEvaluate: true`. **The package ships `false`, so the tool is not registered.** |
+| Warning | `fs.writeFileSync` of a JSON blob (`lib/login-state.js`, `lib/runtime-state.js`) | Exporting the login state (`cookies` + `localStorage`) so a closed window can be reopened still logged in, and the small runtime state file behind the Settings switches. | Always — it is how login persistence works. The files live under your DSH home. |
 | Warning | HTTP request to a bare IP (`scripts/dsh-browser-verify.mjs`) | The acceptance suite starts a **local** `http.server` on `127.0.0.1` with a fixture page, so `npm run verify` needs no DSH and no internet. | Only when you run that script. |
-| Info ×26 | `localStorage` reads, `process.env` reads, dev-only probe scripts | Restoring login state; test hooks (`DSH_BROWSER_STATE_FILE`, `PLAYWRIGHT_DOWNLOAD_HOST`); and scripts under `scripts/analysis/` that the scanner itself marks *"Dev-only file — not executed at install/runtime"*. | — |
+| Info ×22 | `localStorage` reads, `process.env` reads, hardcoded `127.0.0.1`, dev-only probe scripts | Restoring login state; test hooks (`DSH_BROWSER_STATE_FILE`, `PLAYWRIGHT_DOWNLOAD_HOST`); and scripts under `scripts/analysis/` that the scanner itself marks *"Dev-only file — not executed at install/runtime"*. | — |
 
 Two honest notes:
 
@@ -87,8 +91,9 @@ Two honest notes:
   your deployment turns it on. A scanner that reads code cannot see a runtime gate.
 - We did **not** try to hide the finding (moving the call, obfuscating it, or suppressing the rule).
   That would be deceiving the tool that is trying to protect users, and it would make this file a lie.
-
----
+- Module names, not line numbers: this file used to cite a line number in `src/playwright.ts`, which the
+  0.5.x split made meaningless (the code lives in `src/session.ts` now, and that file is a 55-line
+  entry point). File names survive refactors; line numbers do not.
 
 ## 3. How to check all of this yourself
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-browser-playwright-codex",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Browser automation for DeepSeek Harness: fill in forms, scrape lists and work across tabs in real pages, using the logins you already have. Runs in a visible window that stays quiet when minimised, and stops for sign-ins, CAPTCHAs and native dialogs instead of confirming for you.",
   "license": "MIT",
   "type": "module",