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 +35 -0
- package/README.md +27 -22
- package/docs/DESIGN.md +8 -8
- package/package.json +1 -1
- package/skill/SKILL.md +12 -8
- package/skill/references/ATTRIBUTION.md +10 -2
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.
|
|
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
|
-
###
|
|
27
|
+
### Upstream argv defect: fixed in Niubash 1.5.1
|
|
28
28
|
|
|
29
|
-
Niubash 1.5.0
|
|
30
|
-
[rubash#3511](https://github.com/unixwin/rubash/pull/3511)
|
|
31
|
-
double-quoted argument that
|
|
32
|
-
|
|
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
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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
|
|
40
|
-
|
|
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
|
|
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.
|
|
174
|
-
|
|
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` | **
|
|
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.
|
|
181
|
-
| `sed` | WinuxCmd 1.2.
|
|
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
|
|
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 |
|
|
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.
|
|
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
|
|
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.
|
|
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
|
-
|
|
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`
|
|
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
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
|
-
##
|
|
67
|
-
|
|
68
|
-
- Niubash 1.5.0 (rubash before `0ef814fb`)
|
|
69
|
-
|
|
70
|
-
instead of `'
|
|
71
|
-
`
|
|
72
|
-
|
|
73
|
-
|
|
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
|
|
32
|
-
|
|
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.
|