@philogag/pi-tui-openspec-status 0.1.1 → 0.1.2
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/README.md +73 -99
- package/package.json +8 -7
package/README.md
CHANGED
|
@@ -1,112 +1,86 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @philogag/pi-tui-openspec-status
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
shows the current locked **openspec** change as a single status-bar line:
|
|
3
|
+
pi TUI 插件:在状态栏单行显示当前锁定的 **openspec** change 进度:
|
|
5
4
|
|
|
6
5
|
```
|
|
7
6
|
add-pi-tui-openspec-status (superpowers-bridge-cn) [P● D● S○ T○] Tasks: ███░░░░░░░ 2/7
|
|
8
7
|
```
|
|
9
8
|
|
|
10
|
-
##
|
|
9
|
+
## 安装
|
|
11
10
|
|
|
12
11
|
```bash
|
|
13
|
-
|
|
12
|
+
pi install npm:@philogag/pi-tui-openspec-status
|
|
14
13
|
```
|
|
15
14
|
|
|
16
|
-
|
|
17
|
-
|
|
15
|
+
- 安装后扩展自动启用,无需额外配置;用 `pi config` 可启用 / 禁用。
|
|
16
|
+
- 项目级安装加 `-l`(`pi install -l npm:@philogag/pi-tui-openspec-status`,写入 `.pi/settings.json`,可随仓库共享)。
|
|
17
|
+
- 卸载:`pi remove npm:@philogag/pi-tui-openspec-status`。
|
|
18
|
+
- 快速体验:`pi -e npm:@philogag/pi-tui-openspec-status`(仅本次运行,不写入配置)。
|
|
18
19
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
20
|
+
## 激活模式
|
|
21
|
+
|
|
22
|
+
本扩展**仅限 TUI**。工厂阶段拿不到 `ctx.mode`(第一个事件触发后才有),因此门控在 `session_start`(第一个事件)时执行:
|
|
23
|
+
|
|
24
|
+
| 模式 | 激活? | 说明 |
|
|
25
|
+
| -------- | ------ | ---------------------------------------- |
|
|
26
|
+
| `tui` | ✅ 是 | 正常交互操作 |
|
|
27
|
+
| `rpc` | ❌ 否 | 此处 `ctx.hasUI === true`,但模式检查排除它 |
|
|
28
|
+
| `json` | ❌ 否 | 无事件流输出 |
|
|
29
|
+
| `print` | ❌ 否 | `-p` 一次性模式 |
|
|
30
|
+
|
|
31
|
+
按 `pi.dev/docs/latest/extensions#ctx-mode`,`ctx.mode`(而非 `ctx.hasUI`)才是正确的 TUI 特性门控。`/tui-openspec-select` 命令(可能在没有先发生 `session_start` 的情况下运行)在渲染前会重新检查模式。
|
|
32
|
+
|
|
33
|
+
## 行为
|
|
34
|
+
|
|
35
|
+
- 当你(或 agent)执行**显式指定 change** 的 openspec 命令时——`new`、`status`、`apply`、`archive`、`verify`、`sync`、`instructions`、`show`、`validate`、`context`、`view`——或手动用 `/tui-openspec-select` 选择 change 后,状态行出现。
|
|
36
|
+
- 浏览类命令(`openspec list` / `openspec doctor`)会清空状态行。
|
|
37
|
+
- 每次匹配的 `bash` 工具调用后 500ms 刷新。
|
|
38
|
+
|
|
39
|
+
## 手动跟踪:`/tui-openspec-select`
|
|
40
|
+
|
|
41
|
+
TUI 模式下可用 `/tui-openspec-select` 命令手动控制状态栏:
|
|
42
|
+
|
|
43
|
+
- 打开交互选择器,列出所有**活跃** change(`openspec/changes/*/` 减去 `archive/`)加一个 `None` 选项。
|
|
44
|
+
- 手动选择 change 会**锁定**状态栏:之后 bash 的 `openspec` 命令不会切换它,除非你手动重新选择或选 `None`(手动覆盖自动)。
|
|
45
|
+
- 选 `None` 清除手动锁,恢复 bash 命令的自动跟踪。
|
|
46
|
+
- 取消选择器(Esc)不改变任何内容——当前跟踪状态保持不变。
|
|
47
|
+
- 归档手动跟踪的 change(如 `openspec archive <name>`)仍会照常自动清空状态栏。
|
|
48
|
+
|
|
49
|
+
## 锁定跨重启持久化
|
|
50
|
+
|
|
51
|
+
跟踪的 spec、worktree 和锁类型(手动 vs 自动)通过 `pi.appendEntry()`(自定义条目——绝不发给 LLM)持久化到会话文件。`session_start` 时——包括 `/resume`(pi 用新实例重载扩展)——读回最后一条匹配条目并重建状态栏:
|
|
52
|
+
|
|
53
|
+
- **手动**锁(`/tui-openspec-select`)恢复后保持固定,bash 的 openspec 命令不会切换它。
|
|
54
|
+
- **自动**锁(来自 bash `openspec` 命令)按自动语义恢复,后续 `openspec status --change X` 仍会更新跟踪的 spec。
|
|
55
|
+
- 清除(`None` / 归档自动解锁)会写入显式空快照,因此不会恢复过期锁。
|
|
56
|
+
|
|
57
|
+
这意味着状态栏在 `/resume` 和扩展重载后依然保留,而不是变空。
|
|
58
|
+
|
|
59
|
+
## Worktree 支持
|
|
60
|
+
|
|
61
|
+
当 `openspec` 在 git worktree 内调用时(如 `.worktrees/feat/openspec-status/`),扩展会同时读取主仓库和 worktree 的 `tasks.md`,按任务 ID 去重:
|
|
62
|
+
|
|
63
|
+
- 任一侧勾选即为"完成"。
|
|
64
|
+
- 总数为唯一任务 ID 的并集。
|
|
65
|
+
|
|
66
|
+
这防止了 worktree 领先于主仓库时进度条回退(常见的 SDD apply 场景)。
|
|
67
|
+
|
|
68
|
+
## 已知限制
|
|
69
|
+
|
|
70
|
+
- 只显示 schema 的外部产物(`proposal`、`design`、`specs`、`tasks`);规划阶段内部产物(`brainstorm`、`verify`、`retrospective`)隐藏。
|
|
71
|
+
- 需要 `openspec` CLI 在 `$PATH` 上。CLI 缺失时静默禁用扩展。
|
|
72
|
+
- 不渲染 widget、对话框或键盘快捷键——只有底部状态栏(`ctx.ui.setStatus`)。
|
|
73
|
+
- **非 TUI 模式(rpc/json/print)不激活**——设计如此。
|
|
74
|
+
|
|
75
|
+
## 开发
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
pnpm install # 安装依赖(弱依赖来自宿主 pi,devDeps 供本地构建)
|
|
79
|
+
pnpm --filter @philogag/pi-tui-openspec-status test # 测试
|
|
80
|
+
pnpm --filter @philogag/pi-tui-openspec-status typecheck
|
|
81
|
+
pnpm --filter @philogag/pi-tui-openspec-status build # 产出 dist/
|
|
23
82
|
```
|
|
24
83
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
(it's only available once the first event fires), so the gate runs at
|
|
29
|
-
`session_start` (the first event):
|
|
30
|
-
|
|
31
|
-
| Mode | Activates? | Notes |
|
|
32
|
-
|------------|------------|------------------------------------|
|
|
33
|
-
| `tui` | ✅ yes | Normal interactive operation |
|
|
34
|
-
| `rpc` | ❌ no | `ctx.hasUI === true` here too, but mode check excludes it |
|
|
35
|
-
| `json` | ❌ no | No event-stream output |
|
|
36
|
-
| `print` | ❌ no | `-p` one-shot mode |
|
|
37
|
-
|
|
38
|
-
Per `pi.dev/docs/latest/extensions#ctx-mode`, `ctx.mode` (not
|
|
39
|
-
`ctx.hasUI`) is the correct TUI feature gate. The `/tui-openspec-select`
|
|
40
|
-
command (which can run without a prior `session_start`) re-checks the
|
|
41
|
-
mode before rendering.
|
|
42
|
-
|
|
43
|
-
## Behavior
|
|
44
|
-
|
|
45
|
-
- The status line appears when you (or the agent) invoke an
|
|
46
|
-
openspec command that **explicitly names a change** —
|
|
47
|
-
`new`, `status`, `apply`, `archive`, `verify`, `sync`,
|
|
48
|
-
`instructions`, `show`, `validate`, `context`, `view` — **or** when
|
|
49
|
-
you manually select a change with `/tui-openspec-select`.
|
|
50
|
-
- Browsing commands like `openspec list` / `openspec doctor` clear the
|
|
51
|
-
status line.
|
|
52
|
-
- The line refreshes 500ms after each matching `bash` tool call.
|
|
53
|
-
|
|
54
|
-
## Manual tracking with `/tui-openspec-select`
|
|
55
|
-
|
|
56
|
-
In TUI mode you can take manual control of the status bar with the
|
|
57
|
-
`/tui-openspec-select` command:
|
|
58
|
-
|
|
59
|
-
- Opens an interactive picker listing every **active** change
|
|
60
|
-
(`openspec/changes/*/` minus `archive/`) plus a `None` option.
|
|
61
|
-
- Selecting a change manually **locks** the status bar to it: bash
|
|
62
|
-
`openspec` commands will NOT switch it away until you manually
|
|
63
|
-
re-select another change or pick `None` (manual overrides auto).
|
|
64
|
-
- Picking `None` clears the manual lock and restores automatic
|
|
65
|
-
tracking from bash commands.
|
|
66
|
-
- Cancelling the picker (Esc) changes nothing — the current tracking
|
|
67
|
-
state is left untouched.
|
|
68
|
-
- Archiving the manually tracked change (e.g. `openspec archive <name>`)
|
|
69
|
-
still auto-clears the status bar, as usual.
|
|
70
|
-
|
|
71
|
-
## Lock persistence across restarts
|
|
72
|
-
|
|
73
|
-
The tracked spec, worktree, and lock type (manual vs auto) are
|
|
74
|
-
persisted into the session file via `pi.appendEntry()` (custom entries
|
|
75
|
-
— never sent to the LLM). On `session_start` — including `/resume`,
|
|
76
|
-
where pi reloads the extension with a fresh instance — the last
|
|
77
|
-
matching entry is read back and the status bar is rebuilt:
|
|
78
|
-
|
|
79
|
-
- A **manual** lock (`/tui-openspec-select`) is restored pinned, so
|
|
80
|
-
bash openspec commands don't switch it away.
|
|
81
|
-
- An **auto** lock (from a bash `openspec` command) is restored with
|
|
82
|
-
its auto semantics, so a later `openspec status --change X` still
|
|
83
|
-
updates the tracked spec.
|
|
84
|
-
- Clearing (`None` / auto-unlock on archive) writes an explicit empty
|
|
85
|
-
snapshot, so a stale lock is never restored.
|
|
86
|
-
|
|
87
|
-
This means the status bar survives `/resume` and extension reloads
|
|
88
|
-
instead of going empty.
|
|
89
|
-
|
|
90
|
-
## Worktree support
|
|
91
|
-
|
|
92
|
-
When `openspec` is invoked inside a git worktree
|
|
93
|
-
(e.g. `.worktrees/feat/openspec-status/`), the extension reads
|
|
94
|
-
`tasks.md` from **both** the main repo and the worktree, then
|
|
95
|
-
deduplicates by task ID:
|
|
96
|
-
|
|
97
|
-
- A task is "done" if checked in either side.
|
|
98
|
-
- Total count is the union of unique task IDs.
|
|
99
|
-
|
|
100
|
-
This prevents the progress bar from regressing when the worktree is
|
|
101
|
-
ahead of the main repo (the common SDD apply scenario).
|
|
102
|
-
|
|
103
|
-
## Limitations
|
|
104
|
-
|
|
105
|
-
- Only the schema's external artifacts (`proposal`, `design`, `specs`,
|
|
106
|
-
`tasks`) appear; planning-phase internal artifacts
|
|
107
|
-
(`brainstorm`, `verify`, `retrospective`) are hidden.
|
|
108
|
-
- Requires the `openspec` CLI on `$PATH`. Missing CLI silently disables
|
|
109
|
-
the extension.
|
|
110
|
-
- Does **not** render widgets, dialogs, or keyboard shortcuts — only
|
|
111
|
-
the bottom status bar (`ctx.ui.setStatus`).
|
|
112
|
-
- **Does not activate in non-TUI modes** (rpc/json/print) — by design.
|
|
84
|
+
### 依赖说明
|
|
85
|
+
|
|
86
|
+
运行时依赖(`@earendil-works/pi-coding-agent` / `typebox`)声明为 **peerDependencies(弱依赖)**:宿主 pi 环境已内置这些包,插件不重复打包;`devDependencies` 中保留同名依赖供本地 typecheck / test。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@philogag/pi-tui-openspec-status",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "pi extension: single-line status bar tracking openspec status",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -22,16 +22,17 @@
|
|
|
22
22
|
],
|
|
23
23
|
"dependencies": {},
|
|
24
24
|
"peerDependencies": {
|
|
25
|
-
"@earendil-works/pi-
|
|
26
|
-
"@earendil-works/pi-
|
|
27
|
-
"
|
|
25
|
+
"@earendil-works/pi-ai": "*",
|
|
26
|
+
"@earendil-works/pi-coding-agent": "*",
|
|
27
|
+
"@earendil-works/pi-tui": "*",
|
|
28
|
+
"typebox": "*"
|
|
28
29
|
},
|
|
29
30
|
"devDependencies": {
|
|
30
31
|
"@earendil-works/pi-coding-agent": "^0.84.3",
|
|
31
|
-
"@earendil-works/pi-tui": "
|
|
32
|
-
"typebox": "
|
|
32
|
+
"@earendil-works/pi-tui": "^0.84.4",
|
|
33
|
+
"typebox": "^1.3.19",
|
|
33
34
|
"typescript": "^5.6.3",
|
|
34
|
-
"vitest": "
|
|
35
|
+
"vitest": "^4.1.11"
|
|
35
36
|
},
|
|
36
37
|
"repository": {
|
|
37
38
|
"type": "git",
|