pier-setup 0.1.2 → 0.1.4
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 +77 -89
- package/package.json +1 -1
- package/README.en.md +0 -154
package/README.md
CHANGED
|
@@ -1,143 +1,131 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
# pier · pi × herdr
|
|
3
|
+
# pier · pi × herdr workspace fusion
|
|
4
4
|
|
|
5
|
-
**
|
|
5
|
+
**English** · [中文](README_ZH.md)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
**pier** = **pi** × h**erdr** (a pier/dock — where things moor, dock, and fan out).
|
|
8
|
+
|
|
9
|
+
[pi](https://pi.dev/) (`@earendil-works/pi-coding-agent`) is the coding-agent carrier; [herdr](https://herdr.dev/) is a terminal workspace manager. pier adds the two capabilities pi deliberately leaves out — a **todo list loop** and **interactive subagents** — and gives them the herdr pane/tab layer as their visual and interactive substrate.
|
|
8
10
|
|
|
9
11
|
</div>
|
|
10
12
|
|
|
11
13
|
---
|
|
12
14
|
|
|
13
|
-
##
|
|
15
|
+
## What it is
|
|
14
16
|
|
|
15
|
-
pier
|
|
17
|
+
pier ships as **two halves**, installed separately:
|
|
16
18
|
|
|
17
|
-
|
|
|
19
|
+
| Half | Package | Role |
|
|
18
20
|
|---|---|---|
|
|
19
|
-
| **pi
|
|
20
|
-
| **herdr
|
|
21
|
+
| **pi extension** | `packages/pier-ext` (npm: [`pi-pier`](https://www.npmjs.com/package/pi-pier), [pi.dev gallery](https://pi.dev/packages/pi-pier)) | Injects `todo_write` / `subagent` / `list_agents` / `send_message` / `interrupt_agent` tools into a pi session, and reports pane state over the herdr socket API |
|
|
22
|
+
| **herdr plugin** | `packages/pier-workbench` (`pier.workbench`) | Workspace bootstrap, blocked human-gate notifications, focus heat layout (focused pane grows in place) |
|
|
21
23
|
|
|
22
|
-
###
|
|
24
|
+
### Highlights
|
|
23
25
|
|
|
24
|
-
- **
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
-
|
|
29
|
-
-
|
|
30
|
-
-
|
|
26
|
+
- **Todo loop**: `todo_write` with full-replace semantics, session JSONL as source of truth, correct branch rollback; live pane-title projection `▶i ○p ■b ✓c (N/M) · current task`; TUI widget is an activity-anchored window (the in_progress entry and its surrounding context stay visible as work moves down the list); `/todos` command (including unblock)
|
|
27
|
+
- **Todo anti-freeze**: an all-completed list unchanged for ≥6 turns flips the read hook from recitation to a rewrite warning; after ≥1h it archives — first offering one rewrite window with old entries as reference, then (if ignored) a final notice that clears the list (rm persisted to JSONL; the empty guard takes over — multi-step work must re-track); `/todos` still shows history, session JSONL untouched
|
|
28
|
+
- **Interactive subagents**: every subagent = an isolated pi session in its own pane (separate context window); **a human can enter that pane and talk to it directly** (fix bugs, take over, answer ask_user_question)
|
|
29
|
+
- **Soft write-locks**: per-pane lock tokens on write paths; cross-pane conflicts warn or block
|
|
30
|
+
- **Role profiles**: built-in `master` / `worker-default`; custom roles as `.pi-herdr/roles/<name>.json`; toolset converges per role (deny rules are not bypassable)
|
|
31
|
+
- **Human gate**: subagent `ask_user_question` → sidebar blocked marker + notification; manual takeover (ESC-interrupt then typing) is heuristically detected so the master pauses/returns management automatically
|
|
32
|
+
- **Focus heat layout**: focused pane grows in place (0.72 target); blocked / ask / working / idle sized by weight; surplus panes collapse to title strips
|
|
33
|
+
- **Long-task lifecycle (01a03c0d review)**: observation timeout is now an inactivity budget (working slices renew it — healthy >10min tasks are no longer killed); follow_up messages deliver via steer at tool-call gaps (supplementary contracts arrive in seconds, not after the whole run); GC waits for the settlement notice to be delivered before closing panes; takeover detection attributes recent machine injections first; ledger rows carry a `via` tag, closed rows inherit their outcome, zombie running rows are swept on startup; SUBS snapshots are hash-gated. Tunables: `PI_HERDR_SUBAGENT_TIMEOUT_MS` (inactivity seconds), `PI_HERDR_INJECT_GRACE_MS`, `PI_HERDR_OBSERVE_MS`
|
|
34
|
+
- **Settlement notice folding**: subagent settlements no longer flood back when a long main run ends — they inject at turn gaps, up to 3 shown, the rest folded with pointers
|
|
31
35
|
|
|
32
|
-
##
|
|
36
|
+
## Installation
|
|
33
37
|
|
|
34
|
-
###
|
|
38
|
+
### Requirements
|
|
35
39
|
|
|
36
40
|
- Node ≥ 22
|
|
37
|
-
- pi ≥ 0.84
|
|
38
|
-
- herdr ≥ 0.8.0
|
|
41
|
+
- pi ≥ 0.84 (`@earendil-works/pi-coding-agent`)
|
|
42
|
+
- herdr ≥ 0.8.0 (macOS / Linux / Windows; Windows is preview beta)
|
|
39
43
|
|
|
40
|
-
###
|
|
44
|
+
### One-shot install (recommended)
|
|
41
45
|
|
|
42
|
-
|
|
46
|
+
No clone needed — run the npm package directly:
|
|
43
47
|
|
|
44
48
|
```sh
|
|
45
|
-
npx pier-setup #
|
|
46
|
-
npm i -g pier-setup #
|
|
49
|
+
npx pier-setup # user mode: pi install npm:pi-pier + herdr plugin install + auto-generated bootstrap config
|
|
50
|
+
npm i -g pier-setup # or install globally, then just run pier-setup
|
|
47
51
|
```
|
|
48
52
|
|
|
49
|
-
|
|
53
|
+
Dev mode still requires cloning the repo:
|
|
50
54
|
|
|
51
55
|
```sh
|
|
52
56
|
git clone https://github.com/July24/pier && cd pier
|
|
53
|
-
node install.mjs install --dev #
|
|
57
|
+
node install.mjs install --dev # local-path pi install + herdr plugin link; code changes are live
|
|
54
58
|
```
|
|
55
59
|
|
|
56
|
-
|
|
57
|
-
|
|
60
|
+
The script verifies the environment (node / pi / herdr versions), probes pi's node
|
|
61
|
+
and cli.js absolute paths, generates boot-config.json (user mode stores it in the
|
|
62
|
+
herdr plugin config dir, so reinstalls don't lose it), and registers both halves.
|
|
58
63
|
|
|
59
|
-
|
|
60
|
-
|
|
64
|
+
Other commands: `pier-setup update` (uninstall + reinstall, re-probes paths),
|
|
65
|
+
`pier-setup uninstall --purge`. Override the distribution specs with
|
|
66
|
+
`--pi-spec=` / `--herdr-spec=` (npm publishing or forks).
|
|
61
67
|
|
|
62
|
-
###
|
|
68
|
+
### Manual install (equivalent steps)
|
|
63
69
|
|
|
64
70
|
```sh
|
|
65
|
-
# pi
|
|
66
|
-
pi install npm:pi-pier #
|
|
67
|
-
pi install git:github.com/July24/pier #
|
|
68
|
-
pi install ./packages/pier-ext #
|
|
69
|
-
|
|
70
|
-
# herdr
|
|
71
|
-
herdr plugin install July24/pier/packages/pier-workbench --yes #
|
|
72
|
-
herdr plugin link ./packages/pier-workbench #
|
|
71
|
+
# pi extension (any one; npm source = recommended user mode, git source = latest main, local path = dev mode)
|
|
72
|
+
pi install npm:pi-pier # user mode (npm release, auto-listed on the pi.dev/packages gallery)
|
|
73
|
+
pi install git:github.com/July24/pier # user mode (tracks main)
|
|
74
|
+
pi install ./packages/pier-ext # development
|
|
75
|
+
|
|
76
|
+
# herdr plugin
|
|
77
|
+
herdr plugin install July24/pier/packages/pier-workbench --yes # user mode (reinstall = update)
|
|
78
|
+
herdr plugin link ./packages/pier-workbench # development
|
|
73
79
|
```
|
|
74
80
|
|
|
75
|
-
|
|
81
|
+
The extension degrades gracefully outside a herdr environment (see Scope below).
|
|
76
82
|
|
|
77
|
-
###
|
|
83
|
+
### Scope (only the herdr × pi intersection is affected)
|
|
78
84
|
|
|
79
|
-
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
+
- **pi outside herdr**: the extension degrades — reporting is free, workbench tools
|
|
86
|
+
(`subagent`, terminal family) return a clear "requires a herdr-managed pane" error;
|
|
87
|
+
`todo_write` / `ask_user_question` stay available (session JSONL is the authority,
|
|
88
|
+
no herdr dependency).
|
|
89
|
+
- **other agents inside herdr (claude code / codex etc.)**: tabs without a pi pane
|
|
90
|
+
are excluded from heat reflow; blocked notifications are pi-only; master-tab
|
|
91
|
+
auto-bootstrap can be disabled with `autoBootstrap: false` in boot-config.
|
|
85
92
|
|
|
86
|
-
###
|
|
93
|
+
### Bootstrap config (workbench half)
|
|
87
94
|
|
|
88
|
-
|
|
89
|
-
`packages/pier-workbench/scripts/boot-config.example.json
|
|
90
|
-
|
|
95
|
+
Master-tab bootstrap needs local node / pi paths: `pier-setup` generates
|
|
96
|
+
them automatically; manually, copy `packages/pier-workbench/scripts/boot-config.example.json`
|
|
97
|
+
(placeholders for both macOS and Windows). User mode reads it from
|
|
98
|
+
`herdr plugin config-dir pier.workbench`; dev mode from `packages/pier-workbench/scripts/boot-config.json`.
|
|
91
99
|
|
|
92
|
-
###
|
|
100
|
+
### Usage
|
|
93
101
|
|
|
94
|
-
1.
|
|
95
|
-
2.
|
|
96
|
-
3.
|
|
97
|
-
4.
|
|
102
|
+
1. Run pi inside a herdr workspace pane (`pi` in the pane); the extension detects `HERDR_ENV` and starts reporting
|
|
103
|
+
2. The model can call `todo_write` (live pane-title projection), `subagent` (foreground / parallel / background), `list_agents` / `send_message` / `interrupt_agent`
|
|
104
|
+
3. Every subagent = its own pane (observable, enterable, blocked notifies)
|
|
105
|
+
4. Restart recovery: herdr session restore rebuilds panes automatically (subagent rpc session files are reported); resume the parent pi session with `/resume`
|
|
98
106
|
|
|
99
|
-
##
|
|
107
|
+
## Repository layout
|
|
100
108
|
|
|
101
109
|
```
|
|
102
110
|
packages/
|
|
103
|
-
pier-ext/ # pi
|
|
104
|
-
pier-workbench/ # herdr
|
|
105
|
-
docs/ #
|
|
111
|
+
pier-ext/ # pi extension (npm: pi-pier): todo/subagent tools, herdr client, vocab authority, skill
|
|
112
|
+
pier-workbench/ # herdr plugin (pier.workbench): workspace bootstrap + blocked notify + heat layout
|
|
113
|
+
docs/ # install guide, role profile docs, sidebar role config
|
|
106
114
|
```
|
|
107
115
|
|
|
108
|
-
##
|
|
116
|
+
## Testing
|
|
109
117
|
|
|
110
118
|
```sh
|
|
111
119
|
npm install --ignore-scripts
|
|
112
|
-
npm test # node --test
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
## 发版流程（tag → npm 自动发布）
|
|
116
|
-
|
|
117
|
-
发版时**三处版本号必须一致**（由 `.githooks/pre-push` 守卫，不一致会拒绝 push tag）：
|
|
118
|
-
|
|
119
|
-
| 位置 | 对应 npm 包 |
|
|
120
|
-
|---|---|
|
|
121
|
-
| git tag（兼容 `v0.2.0` / `0.2.0`） | 触发发布 |
|
|
122
|
-
| `packages/pier-ext/package.json` 的 `version` | `pi-pier` |
|
|
123
|
-
| 根 `package.json` 的 `version` | `pier-setup` |
|
|
124
|
-
|
|
125
|
-
```sh
|
|
126
|
-
# 1. 同时修改两处 version → 目标版本（必须大于 npm 已有版本）
|
|
127
|
-
# 2. 提交后打同名 tag 并推送：
|
|
128
|
-
git commit -am "release: 0.2.0"
|
|
129
|
-
git tag 0.2.0
|
|
130
|
-
git push && git push --tags # GitHub Actions 自动跑测试并经 Trusted Publishing 发布到 npm
|
|
120
|
+
npm test # node --test, 278 unit tests (planner / todo replay / anti-freeze staleness / session tail / GC / lifecycle)
|
|
131
121
|
```
|
|
132
122
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
## 设计原则
|
|
123
|
+
## Design principles
|
|
136
124
|
|
|
137
|
-
-
|
|
138
|
-
-
|
|
139
|
-
-
|
|
140
|
-
-
|
|
125
|
+
- **Session JSONL is the single source of truth**: todos, delegations, and registries replay from session branches — restart and branch switches stay correct
|
|
126
|
+
- **Event-driven, never poll**: state arrives via herdr event subscriptions (`pane.agent_status_changed` / `pane.closed`); one snapshot is taken only when an event fires
|
|
127
|
+
- **Zero position migration**: the herdr BSP layout topology is fixed at creation; pier only adjusts split ratios — panes never move, they size by priority
|
|
128
|
+
- **Best-effort projection layer**: reporting failures are silent and never block the pi main flow
|
|
141
129
|
|
|
142
130
|
## License
|
|
143
131
|
|
|
@@ -145,6 +133,6 @@ MIT
|
|
|
145
133
|
|
|
146
134
|
---
|
|
147
135
|
|
|
148
|
-
> 💡
|
|
136
|
+
> 💡 **For contributors**: `.gitignore` is deliberately **not committed** to this repository (ignore rules are per-environment). Maintain your own rules based on `README.md` / `README_ZH.md`; `packages/pier-workbench/scripts/boot-config.json` is also machine-local (see the `.example.json` template).
|
|
149
137
|
>
|
|
150
|
-
>
|
|
138
|
+
> **Naming convention**: the brand is **pier** (repo/packages/plugin); runtime protocol identifiers keep the **`pi-herdr`** prefix (`.pi-herdr/roles/` dir, `pi-herdr.subs` session custom entries, `~/.pi/agent/herdr-pi/roles/` user dir) — they persist with user sessions/config files, renaming would break existing data, so they are the compatibility layer.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pier-setup",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.4",
|
|
4
4
|
"description": "One-shot installer for pier: registers the pi-pier extension with pi and the pier.workbench plugin with herdr (install / uninstall / update)",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
package/README.en.md
DELETED
|
@@ -1,154 +0,0 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
# pier · pi × herdr workspace fusion
|
|
4
|
-
|
|
5
|
-
**pier** = **pi** × h**erdr** (a pier/dock — where things moor, dock, and fan out).
|
|
6
|
-
|
|
7
|
-
[pi](https://pi.dev/) (`@earendil-works/pi-coding-agent`) is the coding-agent carrier; [herdr](https://herdr.dev/) is a terminal workspace manager. pier adds the two capabilities pi deliberately leaves out — a **todo list loop** and **interactive subagents** — and gives them the herdr pane/tab layer as their visual and interactive substrate.
|
|
8
|
-
|
|
9
|
-
</div>
|
|
10
|
-
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
## What it is
|
|
14
|
-
|
|
15
|
-
pier ships as **two halves**, installed separately:
|
|
16
|
-
|
|
17
|
-
| Half | Package | Role |
|
|
18
|
-
|---|---|---|
|
|
19
|
-
| **pi extension** | `packages/pier-ext` (npm: [`pi-pier`](https://www.npmjs.com/package/pi-pier), [pi.dev gallery](https://pi.dev/packages/pi-pier)) | Injects `todo_write` / `subagent` / `list_agents` / `send_message` / `interrupt_agent` tools into a pi session, and reports pane state over the herdr socket API |
|
|
20
|
-
| **herdr plugin** | `packages/pier-workbench` (`pier.workbench`) | Workspace bootstrap, blocked human-gate notifications, focus heat layout (focused pane grows in place) |
|
|
21
|
-
|
|
22
|
-
### Highlights
|
|
23
|
-
|
|
24
|
-
- **Todo loop**: `todo_write` with full-replace semantics, session JSONL as source of truth, correct branch rollback; live pane-title projection `▶i ○p ■b ✓c (N/M) · current task`; `/todos` command (including unblock)
|
|
25
|
-
- **Interactive subagents**: every subagent = an isolated pi session in its own pane (separate context window); **a human can enter that pane and talk to it directly** (fix bugs, take over, answer ask_user_question)
|
|
26
|
-
- **Soft write-locks**: per-pane lock tokens on write paths; cross-pane conflicts warn or block
|
|
27
|
-
- **Role profiles**: built-in `master` / `worker-default`; custom roles as `.pi-herdr/roles/<name>.json`; toolset converges per role (deny rules are not bypassable)
|
|
28
|
-
- **Human gate**: subagent `ask_user_question` → sidebar blocked marker + notification; manual takeover (ESC-interrupt then typing) is heuristically detected so the master pauses/returns management automatically
|
|
29
|
-
- **Focus heat layout**: focused pane grows in place (0.72 target); blocked / ask / working / idle sized by weight; surplus panes collapse to title strips
|
|
30
|
-
- **Settlement notice folding**: subagent settlements no longer flood back when a long main run ends — they inject at turn gaps, up to 3 shown, the rest folded with pointers
|
|
31
|
-
|
|
32
|
-
## Installation
|
|
33
|
-
|
|
34
|
-
### Requirements
|
|
35
|
-
|
|
36
|
-
- Node ≥ 22
|
|
37
|
-
- pi ≥ 0.84 (`@earendil-works/pi-coding-agent`)
|
|
38
|
-
- herdr ≥ 0.8.0 (macOS / Linux / Windows; Windows is preview beta)
|
|
39
|
-
|
|
40
|
-
### One-shot install (recommended)
|
|
41
|
-
|
|
42
|
-
No clone needed — run the npm package directly:
|
|
43
|
-
|
|
44
|
-
```sh
|
|
45
|
-
npx pier-setup # user mode: pi install npm:pi-pier + herdr plugin install + auto-generated bootstrap config
|
|
46
|
-
npm i -g pier-setup # or install globally, then just run pier-setup
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
Dev mode still requires cloning the repo:
|
|
50
|
-
|
|
51
|
-
```sh
|
|
52
|
-
git clone https://github.com/July24/pier && cd pier
|
|
53
|
-
node install.mjs install --dev # local-path pi install + herdr plugin link; code changes are live
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
The script verifies the environment (node / pi / herdr versions), probes pi's node
|
|
57
|
-
and cli.js absolute paths, generates boot-config.json (user mode stores it in the
|
|
58
|
-
herdr plugin config dir, so reinstalls don't lose it), and registers both halves.
|
|
59
|
-
|
|
60
|
-
Other commands: `pier-setup update` (uninstall + reinstall, re-probes paths),
|
|
61
|
-
`pier-setup uninstall --purge`. Override the distribution specs with
|
|
62
|
-
`--pi-spec=` / `--herdr-spec=` (npm publishing or forks).
|
|
63
|
-
|
|
64
|
-
### Manual install (equivalent steps)
|
|
65
|
-
|
|
66
|
-
```sh
|
|
67
|
-
# pi extension (any one; npm source = recommended user mode, git source = latest main, local path = dev mode)
|
|
68
|
-
pi install npm:pi-pier # user mode (npm release, auto-listed on the pi.dev/packages gallery)
|
|
69
|
-
pi install git:github.com/July24/pier # user mode (tracks main)
|
|
70
|
-
pi install ./packages/pier-ext # development
|
|
71
|
-
|
|
72
|
-
# herdr plugin
|
|
73
|
-
herdr plugin install July24/pier/packages/pier-workbench --yes # user mode (reinstall = update)
|
|
74
|
-
herdr plugin link ./packages/pier-workbench # development
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
The extension degrades gracefully outside a herdr environment (see Scope below).
|
|
78
|
-
|
|
79
|
-
### Scope (only the herdr × pi intersection is affected)
|
|
80
|
-
|
|
81
|
-
- **pi outside herdr**: the extension degrades — reporting is free, workbench tools
|
|
82
|
-
(`subagent`, terminal family) return a clear "requires a herdr-managed pane" error;
|
|
83
|
-
`todo_write` / `ask_user_question` stay available (session JSONL is the authority,
|
|
84
|
-
no herdr dependency).
|
|
85
|
-
- **other agents inside herdr (claude code / codex etc.)**: tabs without a pi pane
|
|
86
|
-
are excluded from heat reflow; blocked notifications are pi-only; master-tab
|
|
87
|
-
auto-bootstrap can be disabled with `autoBootstrap: false` in boot-config.
|
|
88
|
-
|
|
89
|
-
### Bootstrap config (workbench half)
|
|
90
|
-
|
|
91
|
-
Master-tab bootstrap needs local node / pi paths: `pier-setup` generates
|
|
92
|
-
them automatically; manually, copy `packages/pier-workbench/scripts/boot-config.example.json`
|
|
93
|
-
(placeholders for both macOS and Windows). User mode reads it from
|
|
94
|
-
`herdr plugin config-dir pier.workbench`; dev mode from `packages/pier-workbench/scripts/boot-config.json`.
|
|
95
|
-
|
|
96
|
-
### Usage
|
|
97
|
-
|
|
98
|
-
1. Run pi inside a herdr workspace pane (`pi` in the pane); the extension detects `HERDR_ENV` and starts reporting
|
|
99
|
-
2. The model can call `todo_write` (live pane-title projection), `subagent` (foreground / parallel / background), `list_agents` / `send_message` / `interrupt_agent`
|
|
100
|
-
3. Every subagent = its own pane (observable, enterable, blocked notifies)
|
|
101
|
-
4. Restart recovery: herdr session restore rebuilds panes automatically (subagent rpc session files are reported); resume the parent pi session with `/resume`
|
|
102
|
-
|
|
103
|
-
## Repository layout
|
|
104
|
-
|
|
105
|
-
```
|
|
106
|
-
packages/
|
|
107
|
-
pier-ext/ # pi extension (npm: pi-pier): todo/subagent tools, herdr client, vocab authority, skill
|
|
108
|
-
pier-workbench/ # herdr plugin (pier.workbench): workspace bootstrap + blocked notify + heat layout
|
|
109
|
-
docs/ # install guide, role profile docs, sidebar role config
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
## Testing
|
|
113
|
-
|
|
114
|
-
```sh
|
|
115
|
-
npm install --ignore-scripts
|
|
116
|
-
npm test # node --test, 244 unit tests (planner / todo replay / session tail / GC / lifecycle)
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
## Release process (tag → auto-publish to npm)
|
|
120
|
-
|
|
121
|
-
Three version numbers must stay in sync when releasing (enforced by `.githooks/pre-push`; mismatched pushes are rejected):
|
|
122
|
-
|
|
123
|
-
| Location | npm package |
|
|
124
|
-
|---|---|
|
|
125
|
-
| git tag (`v0.2.0` or `0.2.0`) | release trigger |
|
|
126
|
-
| `packages/pier-ext/package.json` `version` | `pi-pier` |
|
|
127
|
-
| root `package.json` `version` | `pier-setup` |
|
|
128
|
-
|
|
129
|
-
```sh
|
|
130
|
-
# 1. Bump both versions to the target (must be greater than anything already on npm)
|
|
131
|
-
# 2. Commit, then tag with the same number and push:
|
|
132
|
-
git commit -am "release: 0.2.0"
|
|
133
|
-
git tag 0.2.0
|
|
134
|
-
git push && git push --tags # GitHub Actions runs tests and publishes via Trusted Publishing
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
> Hook setup: run once after cloning — `git config core.hooksPath .githooks` (the npm prepare script does this automatically on `npm install`). Versions only go up: npm rejects re-publishing the same version, and old tag names cannot be reused.
|
|
138
|
-
|
|
139
|
-
## Design principles
|
|
140
|
-
|
|
141
|
-
- **Session JSONL is the single source of truth**: todos, delegations, and registries replay from session branches — restart and branch switches stay correct
|
|
142
|
-
- **Event-driven, never poll**: state arrives via herdr event subscriptions (`pane.agent_status_changed` / `pane.closed`); one snapshot is taken only when an event fires
|
|
143
|
-
- **Zero position migration**: the herdr BSP layout topology is fixed at creation; pier only adjusts split ratios — panes never move, they size by priority
|
|
144
|
-
- **Best-effort projection layer**: reporting failures are silent and never block the pi main flow
|
|
145
|
-
|
|
146
|
-
## License
|
|
147
|
-
|
|
148
|
-
MIT
|
|
149
|
-
|
|
150
|
-
---
|
|
151
|
-
|
|
152
|
-
> 💡 **For contributors**: `.gitignore` is deliberately **not committed** to this repository (ignore rules are per-environment). Maintain your own rules based on `README.md` / `README.en.md`; `packages/pier-workbench/scripts/boot-config.json` is also machine-local (see the `.example.json` template).
|
|
153
|
-
>
|
|
154
|
-
> **Naming convention**: the brand is **pier** (repo/packages/plugin); runtime protocol identifiers keep the **`pi-herdr`** prefix (`.pi-herdr/roles/` dir, `pi-herdr.subs` session custom entries, `~/.pi/agent/herdr-pi/roles/` user dir) — they persist with user sessions/config files, renaming would break existing data, so they are the compatibility layer.
|