dsh-win-pwsh7 0.2.5 → 0.2.6

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.2.6 — loads on DSH 0.2.2-rc.1 again
+
+- **The plugin had gone silently inert on the 0.2.2 desktop build.** 0.2.5 declared
+  `engines.dsh: ">=0.2.1-rc.3 <0.2.2-0"`. The loader skips a bundle whose range the running build
+  does not satisfy, prints nothing, and reports it only as an entry in `skippedBundles`, so on
+  DSH 0.2.2-rc.1 both tools, the guard, the page and the UTF-8 console bridge were absent. The
+  only visible trace was `patch: entry "win-pwsh7" not found` on every recomposition, because the
+  bundle patch that inserts that row never applied.
+- `engines.dsh` is now `>=0.2.1-rc.3 <0.3.0-0` and `dsh.verifiedAgainst` is `0.2.2-rc.1`. The
+  upper bound follows the **minor** line: DSH ships fixes as prereleases of the next patch, so a
+  bound on the next patch's prerelease is a bound on "the next DSH update".
+- `tools/check-host.mjs` now fails when the range ends at a patch prerelease
+  (`<X.Y.Z-0`) instead of `<X.<minor+1>.0-0`; the check was mutation-tested by restoring the old
+  range (red) and putting the new one back (green).
+- `tools/check-native-contracts.mjs` follows the 0.2.2 split of `dsh-tools`: it accepts
+  `checkGuards` (0.2.2) or `guardReason` (0.2.1), reads the `Error: <reason>` materialization from
+  `lib/pipeline.js` when that file exists, asserts the pre-execute waterfall still runs **before**
+  the guards, and drops `ToolRuntime.prepareExecution` (removed upstream; this plugin never used it).
+  Green on 0.2.2-rc.1 in 37 checks.
+- `docs/native-contracts.md` records the new baseline, the per-package delta from 0.2.1-rc.4 and
+  the new guard symbols. `dsh-tool-pwsh` is byte-identical; `dsh-pwsh-local` only adds
+  `PYTHONIOENCODING: utf-8`, so `ENCODING_PREAMBLE` still carries no `chcp` and the UTF-8 bridge
+  stays.
+- No tool, prompt, install, gate or page behavior changed.
+
 ## 0.2.5 — transitional Windows UTF-8 console bridge
 
 - Added `lib/utf8-console-bridge.js`, a removable layer that wraps the same `ctx.shell.execute`

package/README.en.md

@@ -18,7 +18,10 @@ default executor then chooses the runtime itself, and the plugin still never wri
 ## Verified environment
 
 - Windows 10/11.
-- Verified on DSH **0.2.1-rc.3** (see `dsh.verifiedAgainst` in `package.json`).
+- Verified on DSH **0.2.2-rc.1** (see `dsh.verifiedAgainst` in `package.json`).
+- Supported range: `>=0.2.1-rc.3 <0.3.0-0`. Ending the range at the next prerelease makes the
+  loader skip this bundle silently after every DSH patch release (no tools, no gate, no UTF-8
+  bridge), so the upper bound follows the **minor** line.
 - The script path needs Microsoft Store; the manual path only needs the Store page.
 - No administrator rights are required.
 
@@ -44,7 +47,7 @@ multi-session validation passed, so the switch is default-on again.
 ## Install this plugin
 
 ```powershell
-dsh plugin --profile desktop add github:XinSpark/dsh-win-pwsh7#v0.2.5
+dsh plugin --profile desktop add github:XinSpark/dsh-win-pwsh7#v0.2.6
 # or
 dsh plugin --profile desktop add dsh-win-pwsh7
 ```

package/README.md

@@ -13,7 +13,9 @@
 ## 验证环境
 
 - Windows 10/11。
-- 已在 DSH **0.2.1-rc.3** 上验证（见 `package.json` 的 `dsh.verifiedAgainst`）。
+- 已在 DSH **0.2.2-rc.1** 上验证（见 `package.json` 的 `dsh.verifiedAgainst`）。
+- 支持范围 `>=0.2.1-rc.3 <0.3.0-0`：收紧到"下一个预发布"会让 loader 在 DSH 每次小版本更新后**静默跳过**本插件
+  （不装、不报错、`pwsh` 失去 gate 和 UTF-8 过渡层），所以上界按**次版本**划。
 - 脚本安装需要 Microsoft Store 可用；手动安装只需要能打开 Store 页面。
 - 不需要管理员权限。
 
@@ -36,7 +38,7 @@
 
 ```powershell
 # 从 GitHub 安装（推荐锁定 tag）
-dsh plugin --profile desktop add github:XinSpark/dsh-win-pwsh7#v0.2.5
+dsh plugin --profile desktop add github:XinSpark/dsh-win-pwsh7#v0.2.6
 # 或 npm
 dsh plugin --profile desktop add dsh-win-pwsh7
 ```

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "dsh-win-pwsh7",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "type": "module",
   "description": "Detect and validate PowerShell 7 for the Harness pwsh tool on Windows, and install it on request through the Microsoft Store — scripted or manual — while the pwsh tool stays blocked until a PowerShell 7 runtime actually resolves.",
   "engines": {
-    "dsh": ">=0.2.1-rc.3 <0.2.2-0"
+    "dsh": ">=0.2.1-rc.3 <0.3.0-0"
   },
   "license": "MIT",
   "icon": "./icon.svg",
@@ -57,7 +57,7 @@
     "prepublishOnly": "npm run check"
   },
   "dsh": {
-    "verifiedAgainst": "0.2.1-rc.3",
+    "verifiedAgainst": "0.2.2-rc.1",
     "bundle": {
       "patch": "./cordis.patch.yml"
     },

package/tools/check-host.mjs

@@ -830,6 +830,27 @@ check('client copy: every t() key is defined in both dictionaries', () => {
   }
 })
 
+// --- Manifest: the DSH range must not end at the next prerelease ---------------------------
+//
+// 0.2.5 declared `>=0.2.1-rc.3 <0.2.2-0` and the desktop moved to 0.2.2-rc.1: the loader skips a
+// bundle whose `engines.dsh` the running build does not satisfy, prints nothing, and the whole
+// plugin disappears (no tools, no gate, no UTF-8 bridge) until a new release ships. DSH patches
+// arrive as prereleases, so a bound on the next patch's prerelease is a bound on "the next DSH
+// update". The range therefore ends at the next minor: `<X.<minor+1>.0-0`.
+
+check('engines.dsh ends at the next minor, not at the next prerelease', () => {
+  const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+  const [major, minor] = manifest.dsh.verifiedAgainst.split('.').map((part) => Number.parseInt(part, 10))
+  const terms = manifest.engines.dsh.trim().split(/\s+/u)
+  const upper = terms.find((term) => term.startsWith('<'))
+  assert.equal(
+    upper,
+    `<${major}.${minor + 1}.0-0`,
+    'a `<X.Y.Z-0` bound on the next patch prerelease makes the loader skip this bundle after the next DSH release',
+  )
+  assert.ok(terms.some((term) => term.startsWith('>=')), 'the range needs a lower bound')
+})
+
 // --- Verdict -----------------------------------------------------------------------------
 
 if (failures.length > 0) {

package/tools/check-native-contracts.mjs

@@ -72,6 +72,32 @@ function source(name) {
   throw new Error(`${name}: neither lib/types/index.js nor lib/index.js exists`)
 }
 
+/**
+ * Read one named file of an installed package, or '' when the build does not have it.
+ *
+ * A contract can move between files without being lost: 0.2.2 moved the tool pipeline out of
+ * `lib/index.js` into `lib/pipeline.js`. Reading a fixed list and joining what exists keeps the
+ * assertion on the behavior when the file split changes, instead of on a remembered path.
+ */
+function trySource(name, relative) {
+  try {
+    return readFileSync(join(packageDir(name), relative), 'utf8')
+  } catch {
+    return ''
+  }
+}
+
+/** The tool pipeline: one file up to 0.2.1, split into `lib/pipeline.js` from 0.2.2. */
+function pipeline() {
+  return ['lib/index.js', 'lib/pipeline.js'].map((relative) => trySource('dsh-tools', relative)).join('\n')
+}
+
+/** The single file that hosts the pre-execute waterfall in this build. */
+function pipelineFile() {
+  const split = trySource('dsh-tools', 'lib/pipeline.js')
+  return split === '' ? trySource('dsh-tools', 'lib/index.js') : split
+}
+
 let checks = 0
 /** One assertion with a stable label for the summary. */
 function check(label, assertion) {
@@ -109,11 +135,30 @@ async function run() {
 
   // ---- tool registry: guard is global, monotonic, and lands as an error --
   check('defineTool is exported', () => assert.equal(typeof tools.defineTool, 'function'))
-  for (const method of ['guard', 'guardReason', 'restrict', 'prepareExecution', 'execute']) {
+  for (const method of ['guard', 'restrict', 'execute']) {
     check(`ToolRuntime.${method} exists`, () => assert.equal(typeof tools.ToolRuntime.prototype[method], 'function'))
   }
-  check('guard denial is materialized as `Error: <reason>`', () => {
-    assert.match(source('dsh-tools'), /Error: \$\{denialReason\}/u)
+  // 0.2.1 read guards in `guardReason`; 0.2.2 renamed it `checkGuards` and moved the one who
+  // materializes the denial into `lib/pipeline.js`. The plugin only needs "guards are still read
+  // once, after pre-execute, and the reason reaches the model" — not a particular private name.
+  const GUARD_READERS = ['checkGuards', 'guardReason']
+  const guardReader = GUARD_READERS.find((name) => typeof tools.ToolRuntime.prototype[name] === 'function')
+  check('ToolRuntime reads its guards through one method', () => {
+    assert.ok(
+      guardReader !== undefined,
+      `neither ${GUARD_READERS.join(' nor ')} exists — the gate cannot tell whether guards still deny`,
+    )
+  })
+  check('a guard denial is materialized as `Error: <reason>`', () => {
+    assert.match(pipeline(), /Error: \$\{denialReason\}/u)
+    assert.ok(pipeline().includes(`.${guardReader}(`), `the denial pipeline never calls ${guardReader}`)
+  })
+  check('guards are read after the pre-execute waterfall', () => {
+    const text = pipelineFile()
+    const waterfall = text.search(/tools\/pre-execute/u)
+    const read = text.search(new RegExp(`${guardReader}\\(`, 'u'))
+    assert.ok(waterfall >= 0, 'the pre-execute waterfall is gone; the gate cannot be refreshed before a pwsh call')
+    assert.ok(read > waterfall, 'guards run before the pre-execute waterfall, so a stale reading would decide the call')
   })
   check('restrict refuses a plain-context caller', () => {
     assert.match(source('dsh-tools'), /tools\.restrict\(\) requires a scoped context/u)