pi-niubash-windows 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,41 @@ All notable changes to this project are documented here. The format follows
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to
5
5
  [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
+ ## [0.1.1] - 2026-11-22
8
+
9
+ Documentation-only release: no `src/`, `test/`, prompt-text or schema change, so 0.1.0 and 0.1.1
10
+ behave identically on the same host. The trigger was a Niubash 1.5.1 self-check that invalidated two
11
+ claims the docs still made.
12
+
13
+ ### Changed
14
+
15
+ - Niubash **1.5.1** is now the verified host (engine `rubash git 649b3be`, WinuxCmd **1.2.2**).
16
+ The requirements table asks for 1.5.1 or later and says 1.5.0 still works but carries the
17
+ pipeline argv defect.
18
+ - The rubash#3511 section became "fixed in Niubash 1.5.1" instead of a live workaround. Re-probed
19
+ byte-by-byte on 2026-11-22: backtick substitution, `$( )` substitution and both in one word all
20
+ deliver `it's now` to a piped native child, in `-c` and in `--ec`. The "assign to a variable
21
+ first" workaround is now scoped to 1.5.0 hosts only, and `niu --version` is named as the way to
22
+ tell which engine is installed. `skill/SKILL.md` and `docs/DESIGN.md` carry the same correction.
23
+ - `git` is no longer documented as unconditionally niugit. Niubash 1.5.1 keeps a directory your own
24
+ `PATH` already has ahead of the toolbelt, so on a host whose `PATH` starts with
25
+ `C:\Program Files\Git\cmd`, `git` is Git for Windows 2.56.0 and niugit must be called by full
26
+ path. `rg`, `ls`, `find`, `grep`, `awk` and `sed` still resolve to `winuxcmd`.
27
+ - `sed` is no longer described as reached "via a shell emulation": on WinuxCmd 1.2.2 both
28
+ `type sed` and `type -a sed` name the `winuxcmd` binary.
29
+ - `skill/references/ATTRIBUTION.md` records that the four snapshots are byte-identical to the
30
+ bundle embedded in Niubash 1.5.1 (same SHA256), so no reference needed re-capture; the only
31
+ upstream growth is the reference `SKILL.md`, which this package deliberately does not bundle.
32
+ - `docs/DESIGN.md` host facts, command-layer table and acceptance item 6 now match 1.5.1, and the
33
+ rubash#3511 risk row records the fix instead of a pending pin bump.
34
+
35
+ ### Not changed
36
+
37
+ - `src/`, `test/`, the tool description, guidelines and schema are identical to 0.1.0. The smoke
38
+ argv probe already took its strict branch (`["it's now"]`) on 1.5.1; retiring its remaining
39
+ U+0017 known-issue branch is a code change, left for a later patch so this release stays
40
+ documentation-only.
41
+
7
42
  ## [0.1.0] - 2026-11-14
8
43
 
9
44
  ### Added
package/README.md CHANGED
@@ -17,29 +17,29 @@ for Windows — and keeps Pi's built-in PowerShell tool untouched next to it.
17
17
  | Component | Version |
18
18
  |---|---|
19
19
  | Pi | `@earendil-works/pi-coding-agent` ≥ 1.5 |
20
- | Niubash | 1.5.0 or later (`niu.exe`, MIT, <https://unixwin.dev>) |
20
+ | Niubash | 1.5.1 or later (`niu.exe`, MIT, <https://unixwin.dev>). 1.5.0 still works but ships the pipeline argv defect described below |
21
21
  | OS | Windows 11 (verified on the maintainer's machine only; Windows 10 and other builds are untested — verify on your host). On non-Windows the extension is inert: no tool, no prompt rules |
22
22
  | Node (tests and local development) | ≥ 22.19 (the Pi SDK requires it) |
23
23
 
24
24
  `niu.exe` is resolved at extension load. If it is missing, the tool is still registered but every
25
25
  call returns an actionable error instead of failing silently.
26
26
 
27
- ### Known upstream issue: Niubash 1.5.0 pipeline argv
27
+ ### Upstream argv defect: fixed in Niubash 1.5.1
28
28
 
29
- Niubash 1.5.0 ships a `rubash` engine from before
30
- [rubash#3511](https://github.com/unixwin/rubash/pull/3511). When a pipeline member has a
31
- double-quoted argument that mixes a live command substitution with an apostrophe, the child
32
- receives U+0017 instead of `'`:
29
+ Niubash 1.5.0 shipped a `rubash` engine from before
30
+ [rubash#3511](https://github.com/unixwin/rubash/pull/3511): when a pipeline member had a
31
+ double-quoted argument that mixed a live command substitution with an apostrophe, the child
32
+ received U+0017 instead of `'`.
33
33
 
34
- ```bash
35
- node -e "process.stdout.write(process.argv[1])" "it's `echo now`" | cat # it\x17s now
36
- x=$(echo now); node -e "process.stdout.write(process.argv[1])" "it's $x" | cat # it's now
37
- ```
34
+ **Niubash 1.5.1 fixes it** (engine `rubash git 649b3be`). Re-probed byte-by-byte on 2026-11-22:
35
+ backtick substitution, `$( )` substitution and both in one word all deliver `it's now` to a piped
36
+ native child, and `niu --ec` behaves the same. Only a 1.5.0 host needs the workaround — compute the
37
+ substitution into a variable before the pipeline (`x=$(date); cmd "it's $x" | cat`); `--ec` does
38
+ not avoid it there. `niu --version` prints the pinned engine rev, so the installed host answers
39
+ this directly.
38
40
 
39
- The fix is merged upstream and ships with the next Niubash release whose
40
- `scripts/release/rubash-pin.json` includes `0ef814fb`. Until then, compute the substitution into a
41
- variable before the pipeline. `niu --ec` does **not** avoid it. The smoke test records the defect as
42
- a known issue and asserts strictly once the engine is fixed.
41
+ The smoke test asserts the fixed behaviour and only reports a known defect if the probe still sees
42
+ U+0017.
43
43
 
44
44
  ## Install
45
45
 
@@ -168,20 +168,25 @@ if (r.exit_code !== 0) throw new Error(r.output);
168
168
 
169
169
  ## Known differences inside the shell
170
170
 
171
- Niubash prepends four `winuxcmd` directories to `PATH` for the processes it spawns. That is by
171
+ Niubash injects four `winuxcmd` directories into `PATH` for the processes it spawns. That is by
172
172
  design (it is how the Unix toolbelt ships) but it means "the command you asked for" is not always
173
- the build you expected. The versions below were read on this review host; they follow the
174
- installed Niubash release and are deliberately not part of the model-facing text:
173
+ the build you expected. Since Niubash 1.5.1 the toolbelt no longer outranks a directory your own
174
+ `PATH` already has ahead of the system ones: on this review host `PATH` starts with
175
+ `C:\Program Files\Git\cmd`, so `git` is Git for Windows and niugit has to be named by full path.
176
+ The versions below were read on that host (Niubash 1.5.1); they follow the installed release and
177
+ are deliberately not part of the model-facing text:
175
178
 
176
179
  | Command | Inside `niubash` | Notes |
177
180
  |---|---|---|
178
- | `git` | **niugit 2.56.0** (`winuxcmd\usr\bin\git.exe`) | shares your global `.gitconfig`; commits are readable by stock Git |
181
+ | `git` | whatever `PATH` finds first — here **Git for Windows 2.56.0** (`C:\Program Files\Git\cmd`) | niugit **2.56.0.windows.4.niugit** ships at `winuxcmd\usr\bin\git.exe`; both read your global `.gitconfig` and their commits are mutually readable |
179
182
  | `rg` | **ripgrep 15.2.0** (`winuxcmd`) | same version and revision as the copy Pi manages |
180
- | `ls`, `find`, `grep`, `awk` | **WinuxCmd 1.2.1** applets | GNU-compatible implementations, not the Windows tools |
181
- | `sed` | WinuxCmd 1.2.1 via a shell emulation | `type sed` reports the emulation, `type -a sed` the `winuxcmd` binary |
183
+ | `ls`, `find`, `grep`, `awk` | **WinuxCmd 1.2.2** applets | GNU-compatible implementations, not the Windows tools |
184
+ | `sed` | WinuxCmd 1.2.2 | GNU-compatible applet; `type sed` and `type -a sed` both name the `winuxcmd` binary |
182
185
  | `tar` | **Windows' bsdtar** (`C:\Windows\System32\tar.exe`) | not a WinuxCmd applet; this host ships bsdtar 3.8.9 |
183
186
 
184
- Need the stock binary? Use the full path, e.g. `"/c/Program Files/Git/cmd/git.exe" status`.
187
+ Need the other build? Use the full path and `type -a <cmd>`, which lists every match in `PATH`
188
+ order: `"$LOCALAPPDATA/Programs/Niubash/winuxcmd/usr/bin/git.exe" status` runs niugit, and
189
+ `"/c/Program Files/Git/cmd/git.exe" status` runs stock Git.
185
190
  Nothing outside the shell changes: Pi's `grep` and `find` tools spawn their own managed
186
191
  `rg.exe` / `fd.exe` by absolute path, and `ls` / `read` / `edit` / `write` are pure Node `fs`.
187
192
 
@@ -233,7 +238,7 @@ installing or moving Niubash.
233
238
  | `... which is not a niu.exe file` | fix `PI_NIUBASH_PATH`; it must name `niu.exe` itself |
234
239
  | `PI_NIUBASH_PATH still contains an unexpanded %NAME% reference` | Pi does not expand `%LOCALAPPDATA%`-style variables; write the literal path (a leading `~` is expanded) |
235
240
  | Chinese output garbled | should not happen (Niubash sets the console to UTF-8); if it does, capture the command and report it |
236
- | `git` behaves unexpectedly | you are running niugit; call the stock binary by full path |
241
+ | `git` behaves unexpectedly | check `type -a git`: the first hit is whatever your `PATH` puts first (stock Git on this host, niugit when `winuxcmd` comes first); call the other build by full path |
237
242
  | Command hangs | no timeout is applied by default — retry with `timeout` (greater than 0) |
238
243
  | `Command line too long` | split the command, or write the script to a file and run the file |
239
244
  | Tool ran with the wrong cwd | the working directory comes from the session; check with `pwd` |
package/docs/DESIGN.md CHANGED
@@ -3,7 +3,7 @@
3
3
  - 状态:**已安装并验收**(P1–P5 完成;P5 安装于 2026-11-14 19:28;二轮复核与验收方法分别见仓库内的 `docs/REVIEW-R2.md`、`docs/ACCEPTANCE-METHOD.md`,这两份文件不随 npm 包发布)
4
4
  - 仓库:本仓库(本地检出;不记录本机绝对路径)
5
5
  - 目标宿主:Pi coding agent `@earendil-works/pi-coding-agent` **1.5.2**(本机经 `pi-web` 0.16.0 运行)
6
- - 目标 shell:Niubash **1.5.0**(本机复核时由 `PATH` 解析到 `niu.exe`;安装路径随主机不同)
6
+ - 目标 shell:Niubash **1.5.1**(engine `rubash git 649b3be`、`winuxcmd 1.2.2`;本机复核时由 `PATH` 解析到 `niu.exe`,安装路径随主机不同)
7
7
  - 上游资料:Niubash 发布包中的 skill bundle(`SKILL.md` 原始版 + `references/`);本仓库 `skill/` 为其 Pi 语境重写版
8
8
 
9
9
  面向使用者的安装/用法说明见 [`README.md`](../README.md);本文记录**为什么这样做**、已验证的宿主事实、冲突分析与验收口径。
@@ -30,7 +30,7 @@
30
30
 
31
31
  | 事实 | 证据 |
32
32
  |---|---|
33
- | `niu -c` 从 Node `spawn` 逐字传 argv | 引号 `a"b`、结尾反斜杠 `C:\dir\`、多行、heredoc、CJK 全部逐字正确 |
33
+ | `niu -c` 从 Node `spawn` 逐字传 argv | 引号 `a"b`、结尾反斜杠 `C:\dir\`、多行、heredoc、CJK 全部逐字正确;1.5.1 上管道成员的反引号/`$( )`/二者混合 + 撇号逐字节均为 `it's now`(rubash#3511 已修,1.5.0 会变 U+0017) |
34
34
  | 输出编码 | Niubash 为自身与子进程设置 UTF-8 代码页(65001);常规文本与 CJK 输出已验证。Pi 按 UTF-8 解码捕获字节,非法原始字节会被替换为 U+FFFD,因此不应用作文本通道传二进制 |
35
35
  | 退出码透传 | `exit 3`→3、`false`→1、命令未找到→127 |
36
36
  | 流式输出 | `echo a; sleep 0.4; echo b` 两段分别到达,可驱动 `onUpdate` |
@@ -39,7 +39,7 @@
39
39
  | 管道陷阱 | `createBashToolDefinition(cwd,{shellPath})` 会忽略 `shellPath`(内部先填了默认 `operations`)→ 必须显式传 `operations` |
40
40
  | 临时文件前缀 | 内置管道写死为 `pi-bash-*`(`createShellToolDefinition` 未导出,不 fork 内部实现) |
41
41
  | 编码 | 不需要 PowerShell 工具的 `[Console]::OutputEncoding` 前缀,Niubash 自己处理 |
42
- | 命令解析 | `git`→niugit 2.56.0(与系统 git 共用 gitconfig,提交哈希互通)、`rg`→winuxcmd ripgrep 15.2.0(与 Pi 托管 rg 同版本同 rev `e89fff89ac`、同 `+pcre2`)、`ls`/`find`/`grep`/`awk`→WinuxCmd 1.2.1、`sed`→WinuxCmd 1.2.1(shell 仿真)、`tar`→**系统 `C:\Windows\System32\tar.exe`(bsdtar 3.8.9,非 WinuxCmd)** |
42
+ | 命令解析 | 全部遵循 `PATH`:`git`→**宿主 Git for Windows 2.56.0**(本机 `PATH` 首项是 `C:\Program Files\Git\cmd`,1.5.1 不再把它挤到 toolbelt 之后;niugit 2.56.0.windows.4 仍在 `winuxcmd\usr\bin\git.exe`,全路径可调,两者共用 gitconfig、提交哈希互通)、`rg`→winuxcmd ripgrep 15.2.0(与 Pi 托管 rg 同版本同 rev `e89fff89ac`、同 `+pcre2`)、`ls`/`find`/`grep`/`awk`/`sed`→WinuxCmd 1.2.2、`tar`→**系统 `C:\Windows\System32\tar.exe`(bsdtar 3.8.9,非 WinuxCmd)** |
43
43
 
44
44
  ---
45
45
 
@@ -156,12 +156,12 @@ Niubash 只给**自己 spawn 的子进程**前置 `winuxcmd\{usr/local/bin, usr/
156
156
 
157
157
  | 命令 | Pi 外部(pwsh/系统) | niubash 内部 |
158
158
  |---|---|---|
159
- | `git` | `C:\Program Files\Git\cmd\git.exe` | niugit 2.56.0 |
159
+ | `git` | `C:\Program Files\Git\cmd\git.exe` | **同一份**系统 Git 2.56.0(1.5.1 保留宿主 `PATH` 前缀优先;niugit 2.56.0.windows.4 在 `winuxcmd\usr\bin\git.exe`,需全路径) |
160
160
  | `rg` | `.pi\agent\bin\rg.exe` 15.2.0 | winuxcmd ripgrep 15.2.0 |
161
- | `ls` `find` `grep` `sed` `awk` | 系统/自备 | WinuxCmd 1.2.1 applet(`sed` 为 shell 仿真) |
161
+ | `ls` `find` `grep` `sed` `awk` | 系统/自备 | WinuxCmd 1.2.2 applet(`sed` 由 winuxcmd 二进制直接承担,`type`/`type -a` 一致) |
162
162
  | `tar` | `C:\Windows\System32\tar.exe`(bsdtar 3.8.9) | 同一份系统 bsdtar(**不是** WinuxCmd applet) |
163
163
 
164
- 实测:niugit 与系统 git 共用同一份全局 gitconfig;niugit 提交 `b6292df` 可被系统 git 读到;两者 rg 同版本同 rev。真实影响仅为"模型以为在跑系统工具"。对策:description、guideline 3、skill 的路径契约与全路径逃生舱。
164
+ 实测(1.5.0 期):niugit 与系统 git 共用同一份全局 gitconfig;niugit 提交 `b6292df` 可被系统 git 读到;两者 rg 同版本同 rev。1.5.1 上 `git` 已回落到系统 Git,差异仅剩 `rg`/`ls` 等 applet。对策:description、guideline 3、skill 的路径契约与全路径逃生舱。
165
165
 
166
166
  ### 5.4 两个"看起来像冲突"但不是的点
167
167
 
@@ -282,7 +282,7 @@ pi-niubash-windows/
282
282
  3. `exit 3` → `isError`,`Command exited with code 3`
283
283
  4. `sleep 5` + `timeout: 1` → 超时错误;`taskkill` 异步,需用 `$$` / `$!` + 有界轮询确认进程消失(不得以“返回时计数 0”作同步断言)
284
284
  5. heredoc + 管道:`cat <<EOF | tr a-z A-Z` → `HELLO`
285
- 6. `git --version` → `2.56.0.windows.4.niugit`
285
+ 6. `git --version` → `2.56.0.windows.4`(宿主 `PATH` 前缀优先);`command -v git` 与 `type -a git` 的第一项须一致;niugit 需全路径 `"$LOCALAPPDATA/Programs/Niubash/winuxcmd/usr/bin/git.exe" --version` → `2.56.0.windows.4.niugit`
286
286
 
287
287
  **B. 共存**
288
288
 
@@ -319,7 +319,7 @@ pi-niubash-windows/
319
319
  | niugit/winuxcmd 抢占 `git`/`rg` | 模型误判工具版本 | description + guideline 3 + skill;全路径逃生舱;实测同 config、同 rg 版本 |
320
320
  | `createBashToolDefinition` 忽略 `shellPath` | 静默退回 Git Bash | 强制走 `operations: createLocalBashOperations({shellPath})`;smoke 断言 `command -v ls` 指向 winuxcmd |
321
321
  | 临时文件前缀固定 `pi-bash-` | 仅外观 | README 说明,不 fork 内部实现 |
322
- | `-c` 极端引号破例(已观测,rubash#3511) | 管道成员的“双引号参数 + 命令替换 + 撇号”会把 `'` 变成 U+0017,argv 静默篡改;`--ec` 同样复现 | 上游已修(`0ef814fb`,2026-11-14);等 Niubash bump `scripts/release/rubash-pin.json` 后发行;SKILL/README 记录触发面与“先赋值”绕法;smoke 的 known-issue 探针在修复后转严格断言 |
322
+ | `-c` 极端引号破例(rubash#3511,**1.5.1 已修**) | 1.5.0 上管道成员的“双引号参数 + 命令替换 + 撇号”会把 `'` 变成 U+0017,argv 静默篡改;`--ec` 同样复现 | 1.5.1(engine `rubash git 649b3be`)逐字节复核通过:反引号/`$( )`/混合三种载体均得 `it's now`;README/SKILL/DESIGN 已把 workaround 限定为“仅 1.5.0 宿主”;需求下限提到 1.5.1;smoke 探针现走严格分支(`["it's now"]`),仍保留 U+0017 的 known-issue 提示以覆盖旧宿主 |
323
323
  | niu 未安装/被卸载 | 工具不可用 | 降级 stub + 安装指引;`PI_NIUBASH_PATH` 可覆盖 |
324
324
  | pi-web 不支持热重载 | 改动后不生效 | 以新开会话为准 |
325
325
  | 无 PTY | `ssh -t`/`vim`/`tmux` 失效 | description 明示,交给 pwsh/WSL |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-niubash-windows",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Niubash (native Windows bash) as a Pi tool, coexisting with Pi's PowerShell tool.",
5
5
  "license": "MIT",
6
6
  "author": "qwased",
package/skill/SKILL.md CHANGED
@@ -63,14 +63,18 @@ variable: there is no `MSYS_NO_PATHCONV`-equivalent. Full table: `references/pat
63
63
  Slice `output` in the script when only a summary is needed; `truncated` does not reflect the
64
64
  2000-line / 50KB rule.
65
65
 
66
- ## Known upstream defects
67
-
68
- - Niubash 1.5.0 (rubash before `0ef814fb`) corrupts a pipeline member's argv: in a double-quoted
69
- word that mixes a live command substitution with an apostrophe, the child receives U+0017
70
- instead of `'`. Upstream fix: rubash#3511 (merged); it ships in the next Niubash release whose
71
- `scripts/release/rubash-pin.json` includes `0ef814fb`. Workaround: compute the substitution into
72
- a variable first, e.g. `x=$(date); cmd "it's $x" | cat`. `niu --ec` does not avoid it. Check the
73
- pinned engine with `niu --version` (it prints the rubash rev).
66
+ ## Upstream defects
67
+
68
+ - **Fixed in Niubash 1.5.1 — no workaround needed.** Niubash 1.5.0 (rubash before `0ef814fb`)
69
+ corrupted a pipeline member's argv: in a double-quoted word that mixed a live command
70
+ substitution with an apostrophe, the child received U+0017 instead of `'` (rubash#3511). The
71
+ 1.5.1 engine (`rubash git 649b3be`) delivers `it's now` through backtick substitution, `$( )`
72
+ and both in one word alike, in `-c` and in `--ec`. On a 1.5.0 host only, compute the
73
+ substitution into a variable first, e.g. `x=$(date); cmd "it's $x" | cat`. `niu --version` prints
74
+ the pinned engine rev, so the host itself answers which behaviour applies.
75
+ - Command resolution inside the shell follows `PATH`: Niubash keeps a directory your own `PATH`
76
+ already has ahead of the toolbelt, so `git` can be stock Git for Windows (niugit then lives at
77
+ `winuxcmd\usr\bin\git.exe`). `type -a <cmd>` lists every match; never assume the toolbelt won.
74
78
 
75
79
  ## Symptom → verify → reference
76
80
 
@@ -16,6 +16,11 @@ is noted below:
16
16
  in the `README.md` and `LICENSE` files of the installed Niubash 1.5.0 tree.
17
17
  - Snapshot: the skill bundle shipped with that install; the bundle files carry a
18
18
  2026-11-03 file timestamp, and the copies here were re-verified byte-for-byte on 2026-11-14.
19
+ - Re-verified against **Niubash 1.5.1** on 2026-11-22: the bundle embedded in the 1.5.1 binary
20
+ (`niu skill install --target dir:<tmp>`, bundle digest `2e02d497…`) yields the **same bytes** for
21
+ all four documents — every SHA256 in the table above still matches. Only the upstream
22
+ `SKILL.md` grew (13,427 bytes, adding a debugging section and engine-fix notes); it is not
23
+ bundled here, because `skill/SKILL.md` is the Pi-specific rewrite described at the bottom.
19
24
  - **Commit / tag: unknown.** The bundle carries no git metadata, so the exact upstream commit or
20
25
  release tag that produced these files cannot be verified from this copy. The Niubash version
21
26
  number is not a commit identifier; do not treat it as one.
@@ -28,5 +33,8 @@ is noted below:
28
33
  `skill/SKILL.md` is a Pi-specific rewrite and does not reproduce the upstream skill text
29
34
  wholesale; consult upstream for the canonical skill.
30
35
 
31
- When updating Niubash, diff these files against the new bundle, record the new hashes and the
32
- capture date, and refresh them rather than editing in place, so provenance stays verifiable.
36
+ When updating Niubash, diff these files against the new bundle (the binary can emit its own copy:
37
+ `niu skill install --target dir:<tmp>`), record the new hashes and the capture date, and refresh
38
+ them rather than editing in place, so provenance stays verifiable. A version bump with identical
39
+ bytes is worth recording explicitly — as done for 1.5.1 above — so a later reader does not assume
40
+ the snapshot is stale just because the host moved on.