@senad-d/branchme 0.1.9 → 0.2.0
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 +5 -4
- package/README.md +45 -9
- package/SECURITY.md +29 -5
- package/docs/PROJECT_DEFINITION_BRIEF.md +29 -12
- package/docs/SMOKE_TEST.md +9 -8
- package/docs/STRUCTURE.md +22 -15
- package/docs/TUI_CAPTURE.md +34 -26
- package/package.json +2 -2
- package/src/commands/branchme-command.ts +9 -1
- package/src/constants.ts +4 -0
- package/src/git-retirement.ts +681 -0
- package/src/git.ts +158 -0
- package/src/tools/branchme-tools.ts +53 -0
- package/src/types.ts +76 -0
- package/src/ui/branchme-panel.ts +7 -4
package/docs/TUI_CAPTURE.md
CHANGED
|
@@ -37,13 +37,21 @@ Commands only show info; BranchMe tools perform actions.
|
|
|
37
37
|
- It never fetches or pushes; a conflict is automatically aborted after paths are captured and restoration is verified.
|
|
38
38
|
- BranchMe does not resolve semantic conflicts; handle them in a separate developer workflow.
|
|
39
39
|
|
|
40
|
+
## Branch retirement
|
|
41
|
+
|
|
42
|
+
- `remove_worktree` and `retire_branch` are separate: removal retains the branch; retirement later deletes only the exact local branch ref.
|
|
43
|
+
- `retire_branch` requires the exact local branch, its full expected `HEAD`, and an exact local target for ancestry verification.
|
|
44
|
+
- Any registered worktree occupancy rejects retirement; remove an occupying linked worktree separately first.
|
|
45
|
+
- Merged retirement uses `force: false`; unmerged retirement requires explicit authorization with `force: true` and may make commits unreachable.
|
|
46
|
+
- It never directly deletes a remote or remote-tracking branch.
|
|
47
|
+
|
|
40
48
|
## Worktree handoff
|
|
41
49
|
|
|
42
50
|
- `list_worktrees` — inspect the main and linked worktrees in the current repository.
|
|
43
51
|
- `create_worktree` — create a linked worktree and return a ready handoff with an absolute `handoff.cwd`.
|
|
44
52
|
- A separate orchestrator starts the next Pi session or subagent in `handoff.cwd`.
|
|
45
53
|
- `remove_worktree` — remove a verified clean linked worktree while retaining its local branch.
|
|
46
|
-
- BranchMe does not change cwd, start Pi, copy `.env
|
|
54
|
+
- BranchMe does not change cwd, start Pi, or copy `.env`; `remove_worktree` never removes its retained branch automatically.
|
|
47
55
|
|
|
48
56
|
## Requirements
|
|
49
57
|
|
|
@@ -90,26 +98,26 @@ Width: 40
|
|
|
90
98
|
╰──────────────────────────────────────╯
|
|
91
99
|
```
|
|
92
100
|
|
|
93
|
-
## Panel: Narrow mode:
|
|
101
|
+
## Panel: Narrow mode: Lifecycle selected
|
|
94
102
|
|
|
95
103
|
Width: 40
|
|
96
104
|
|
|
97
105
|
```text
|
|
98
|
-
╭ BranchMe
|
|
106
|
+
╭ BranchMe ───────────────── Lifecycle ╮
|
|
99
107
|
│current repo only • informational │
|
|
100
108
|
│ ↑↓ section • q quit • /branchme help │
|
|
101
109
|
├──────────────────────────────────────┤
|
|
102
|
-
│
|
|
110
|
+
│ LIFECYCLE │
|
|
103
111
|
│ integrate_branch -> exact local sou…│
|
|
104
112
|
│ control target -> checked out + c…│
|
|
105
|
-
│ remote effects -> never fetch or …│
|
|
106
113
|
│ conflict -> automatic verif…│
|
|
107
114
|
│ semantic intent -> separate develo…│
|
|
108
|
-
│
|
|
109
|
-
│
|
|
110
|
-
│
|
|
115
|
+
│ remove_worktree -> separate; branc…│
|
|
116
|
+
│ retire_branch -> leased local re…│
|
|
117
|
+
│ retirement guard -> unoccupied + ta…│
|
|
118
|
+
│ remote effects -> never delete re…│
|
|
111
119
|
├──────────────────────────────────────┤
|
|
112
|
-
│ 3/4 •
|
|
120
|
+
│ 3/4 • lifecycle • integrate → remove…│
|
|
113
121
|
╰──────────────────────────────────────╯
|
|
114
122
|
```
|
|
115
123
|
|
|
@@ -123,7 +131,7 @@ Width: 80
|
|
|
123
131
|
├─────────────────────┬────────────────────────────────────────────────────────┤
|
|
124
132
|
│▶ Status │ STATUS │
|
|
125
133
|
│ Workflow │ Current branch: feature/current │
|
|
126
|
-
│
|
|
134
|
+
│ Lifecycle │ GitHub repository: senad-d/branchme │
|
|
127
135
|
│ Worktrees │ GitHub token: present │
|
|
128
136
|
│ │ │
|
|
129
137
|
│ │ │
|
|
@@ -145,7 +153,7 @@ Width: 80
|
|
|
145
153
|
├─────────────────────┬────────────────────────────────────────────────────────┤
|
|
146
154
|
│ Status │ WORKFLOW │
|
|
147
155
|
│▶ Workflow │ branch_status -> inspect │
|
|
148
|
-
│
|
|
156
|
+
│ Lifecycle │ change_branch -> existing local │
|
|
149
157
|
│ Worktrees │ fetch_branch -> upstream remote │
|
|
150
158
|
│ │ pull_branch -> fast-forward │
|
|
151
159
|
│ │ rebase_branch -> onto upstream │
|
|
@@ -157,25 +165,25 @@ Width: 80
|
|
|
157
165
|
╰──────────────────────────────────────────────────────────────────────────────╯
|
|
158
166
|
```
|
|
159
167
|
|
|
160
|
-
## Panel: Wide mode:
|
|
168
|
+
## Panel: Wide mode: Lifecycle selected
|
|
161
169
|
|
|
162
170
|
Width: 80
|
|
163
171
|
|
|
164
172
|
```text
|
|
165
|
-
╭ BranchMe
|
|
173
|
+
╭ BranchMe ───────────────────────────────────────────────────────── Lifecycle ╮
|
|
166
174
|
│ ↑↓ section • q quit • /branchme help │
|
|
167
175
|
├─────────────────────┬────────────────────────────────────────────────────────┤
|
|
168
|
-
│ Status │
|
|
176
|
+
│ Status │ LIFECYCLE │
|
|
169
177
|
│ Workflow │ integrate_branch -> exact local source -> target │
|
|
170
|
-
│▶
|
|
171
|
-
│ Worktrees │
|
|
172
|
-
│ │ conflict -> automatic verified abort │
|
|
178
|
+
│▶ Lifecycle │ control target -> checked out + clean │
|
|
179
|
+
│ Worktrees │ conflict -> automatic verified abort │
|
|
173
180
|
│ │ semantic intent -> separate developer workflow │
|
|
174
|
-
│ │
|
|
175
|
-
│ │
|
|
176
|
-
│ │
|
|
181
|
+
│ │ remove_worktree -> separate; branch retained │
|
|
182
|
+
│ │ retire_branch -> leased local ref deletion │
|
|
183
|
+
│ │ retirement guard -> unoccupied + target ancestry │
|
|
184
|
+
│ │ remote effects -> never delete remote refs │
|
|
177
185
|
├─────────────────────┴────────────────────────────────────────────────────────┤
|
|
178
|
-
│ 3/4 •
|
|
186
|
+
│ 3/4 • lifecycle • integrate → remove worktree separately → retire local ref │
|
|
179
187
|
╰──────────────────────────────────────────────────────────────────────────────╯
|
|
180
188
|
```
|
|
181
189
|
|
|
@@ -189,7 +197,7 @@ Width: 80
|
|
|
189
197
|
├─────────────────────┬────────────────────────────────────────────────────────┤
|
|
190
198
|
│ Status │ WORKTREES │
|
|
191
199
|
│ Workflow │ list_worktrees -> inspect inventory │
|
|
192
|
-
│
|
|
200
|
+
│ Lifecycle │ create_worktree -> ready handoff.cwd │
|
|
193
201
|
│▶ Worktrees │ remove_worktree -> clean linked; branch retained │
|
|
194
202
|
│ │ │
|
|
195
203
|
│ │ │
|
|
@@ -211,7 +219,7 @@ Width: 112
|
|
|
211
219
|
├──────────────────────┬───────────────────────────────────────────────────────────────────────┤
|
|
212
220
|
│▶ Status │ STATUS │
|
|
213
221
|
│ Workflow │ Current branch: main │
|
|
214
|
-
│
|
|
222
|
+
│ Lifecycle │ GitHub repository: senad-d/BranchMe │
|
|
215
223
|
│ Worktrees │ GitHub token: not set │
|
|
216
224
|
│ │ │
|
|
217
225
|
│ │ │
|
|
@@ -256,7 +264,7 @@ Width: 80
|
|
|
256
264
|
├─────────────────────┬────────────────────────────────────────────────────────┤
|
|
257
265
|
│▶ Status │ STATUS │
|
|
258
266
|
│ Workflow │ Current branch: main │
|
|
259
|
-
│
|
|
267
|
+
│ Lifecycle │ GitHub repository: warning: Repository boundary misma…│
|
|
260
268
|
│ Worktrees │ GitHub token: present │
|
|
261
269
|
│ │ │
|
|
262
270
|
│ │ │
|
|
@@ -278,7 +286,7 @@ Width: 72
|
|
|
278
286
|
├───────────────────┬──────────────────────────────────────────────────┤
|
|
279
287
|
│▶ Status │ STATUS │
|
|
280
288
|
│ Workflow │ Current branch: main │
|
|
281
|
-
│
|
|
289
|
+
│ Lifecycle │ GitHub repository: senad-d/branchme │
|
|
282
290
|
│ Worktrees │ GitHub token: warning: Unable to read .env…│
|
|
283
291
|
│ │ │
|
|
284
292
|
│ │ │
|
|
@@ -300,7 +308,7 @@ Width: 72
|
|
|
300
308
|
├───────────────────┬──────────────────────────────────────────────────┤
|
|
301
309
|
│▶ Status │ STATUS │
|
|
302
310
|
│ Workflow │ Current branch: feature/super-long-branch-na…│
|
|
303
|
-
│
|
|
311
|
+
│ Lifecycle │ GitHub repository: very-long-owner-name/very-lo…│
|
|
304
312
|
│ Worktrees │ GitHub token: present │
|
|
305
313
|
│ │ │
|
|
306
314
|
│ │ │
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@senad-d/branchme",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"type": "module",
|
|
5
|
-
"description": "Pi extension for verified current-repository Git branch, worktree, integration, push, and pull request workflows.",
|
|
5
|
+
"description": "Pi extension for verified current-repository Git branch, worktree, integration, retirement, push, and pull request workflows.",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"author": "Senad Dizdarević <112484166+senad-d@users.noreply.github.com>",
|
|
8
8
|
"repository": {
|
|
@@ -46,13 +46,21 @@ export function getBranchMeHelpText(): string {
|
|
|
46
46
|
"- It never fetches or pushes; a conflict is automatically aborted after paths are captured and restoration is verified.",
|
|
47
47
|
"- BranchMe does not resolve semantic conflicts; handle them in a separate developer workflow.",
|
|
48
48
|
"",
|
|
49
|
+
"## Branch retirement",
|
|
50
|
+
"",
|
|
51
|
+
"- `remove_worktree` and `retire_branch` are separate: removal retains the branch; retirement later deletes only the exact local branch ref.",
|
|
52
|
+
"- `retire_branch` requires the exact local branch, its full expected `HEAD`, and an exact local target for ancestry verification.",
|
|
53
|
+
"- Any registered worktree occupancy rejects retirement; remove an occupying linked worktree separately first.",
|
|
54
|
+
"- Merged retirement uses `force: false`; unmerged retirement requires explicit authorization with `force: true` and may make commits unreachable.",
|
|
55
|
+
"- It never directly deletes a remote or remote-tracking branch.",
|
|
56
|
+
"",
|
|
49
57
|
"## Worktree handoff",
|
|
50
58
|
"",
|
|
51
59
|
"- `list_worktrees` — inspect the main and linked worktrees in the current repository.",
|
|
52
60
|
"- `create_worktree` — create a linked worktree and return a ready handoff with an absolute `handoff.cwd`.",
|
|
53
61
|
"- A separate orchestrator starts the next Pi session or subagent in `handoff.cwd`.",
|
|
54
62
|
"- `remove_worktree` — remove a verified clean linked worktree while retaining its local branch.",
|
|
55
|
-
"- BranchMe does not change cwd, start Pi, copy `.env
|
|
63
|
+
"- BranchMe does not change cwd, start Pi, or copy `.env`; `remove_worktree` never removes its retained branch automatically.",
|
|
56
64
|
"",
|
|
57
65
|
"## Requirements",
|
|
58
66
|
"",
|
package/src/constants.ts
CHANGED
|
@@ -13,6 +13,7 @@ export const LIST_WORKTREES_TOOL_NAME = "list_worktrees";
|
|
|
13
13
|
export const CREATE_WORKTREE_TOOL_NAME = "create_worktree";
|
|
14
14
|
export const REMOVE_WORKTREE_TOOL_NAME = "remove_worktree";
|
|
15
15
|
export const INTEGRATE_BRANCH_TOOL_NAME = "integrate_branch";
|
|
16
|
+
export const RETIRE_BRANCH_TOOL_NAME = "retire_branch";
|
|
16
17
|
export const PULL_REQUEST_AUTOFILL_ENV_NAME = "BRANCHME_PR_AUTOFILL";
|
|
17
18
|
|
|
18
19
|
export const BRANCHME_TOOL_NAMES = [
|
|
@@ -23,6 +24,7 @@ export const BRANCHME_TOOL_NAMES = [
|
|
|
23
24
|
PULL_BRANCH_TOOL_NAME,
|
|
24
25
|
REBASE_BRANCH_TOOL_NAME,
|
|
25
26
|
INTEGRATE_BRANCH_TOOL_NAME,
|
|
27
|
+
RETIRE_BRANCH_TOOL_NAME,
|
|
26
28
|
PUSH_BRANCH_TOOL_NAME,
|
|
27
29
|
PULL_REQUEST_TOOL_NAME,
|
|
28
30
|
LIST_WORKTREES_TOOL_NAME,
|
|
@@ -38,6 +40,7 @@ export const GIT_REBASE_TIMEOUT_MS = 120_000;
|
|
|
38
40
|
export const GIT_PUSH_TIMEOUT_MS = 120_000;
|
|
39
41
|
export const GIT_WORKTREE_MUTATION_TIMEOUT_MS = 120_000;
|
|
40
42
|
export const GIT_INTEGRATION_TIMEOUT_MS = 120_000;
|
|
43
|
+
export const GIT_RETIREMENT_MUTATION_TIMEOUT_MS = 30_000;
|
|
41
44
|
export const GITHUB_RELATED_PR_TIMEOUT_MS = 4_000;
|
|
42
45
|
|
|
43
46
|
export const GIT_CONTEXT_RECENT_COMMIT_LIMIT = 5;
|
|
@@ -55,6 +58,7 @@ export const GIT_INTEGRATION_CONFLICT_RAW_OUTPUT_LIMIT_BYTES = 128 * 1024;
|
|
|
55
58
|
export const GIT_INTEGRATION_CONFLICT_ENTRY_LIMIT = 100;
|
|
56
59
|
export const GIT_INTEGRATION_CONFLICT_PATH_LIMIT_CHARS = 4_096;
|
|
57
60
|
export const GIT_INTEGRATION_SUMMARY_LIMIT_CHARS = 4_000;
|
|
61
|
+
export const GIT_RETIREMENT_SUMMARY_LIMIT_CHARS = 4_000;
|
|
58
62
|
|
|
59
63
|
export const GITHUB_API_BASE_URL = "https://api.github.com";
|
|
60
64
|
export const GITHUB_API_VERSION = "2022-11-28";
|