@helmsmith/workbrokr 0.0.0-stage → 0.1.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/LICENSE +201 -0
- package/README.md +66 -2
- package/SKILL.md +56 -0
- package/bin/work.mjs +3 -0
- package/bin/workbrokr.mjs +3 -0
- package/dist/cli.js +2468 -0
- package/dist/cli.js.map +1 -0
- package/package.json +44 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright [yyyy] [name of copyright owner]
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
package/README.md
CHANGED
|
@@ -1,3 +1,67 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @helmsmith/workbrokr
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`work` starts, runs, finishes, expires, retires and audits **area-based work**: one git worktree per area of the application, branches named `<type>/<area>`, every effort synced from the latest base branch before it begins, slots and ports handed out by one machine-wide registry, a scoped Storybook (via [`@helmsmith/storybrokr`](../storybrokr)) for frontend work and the project's own stack for full-stack work. It is a CLI, an MCP server and a skill over the same functions, built on [`@helmsmith/workkit`](../../platform/core/workkit-lib).
|
|
4
|
+
|
|
5
|
+
It exists because creating worktrees and stacks was easy and nothing ever closed the loop: dozens of merged worktrees, slots claimed by several checkouts, stacks running unattended for days, work that lived only on one machine, and a stray command that dialled the human's database. `work` makes finishing, expiring and auditing as cheap as starting, and turns the rules that used to live in memory notes into refusals.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm i -g @helmsmith/workbrokr # provides `work` and `workbrokr`
|
|
11
|
+
npm i -g @helmsmith/storybrokr # only for --mode frontend
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Node 24 or newer. Manifests may be TypeScript (`helmsmith.config.ts`), ESM (`.mjs`) or JSON.
|
|
15
|
+
|
|
16
|
+
## Set a project up
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
cd <repo>
|
|
20
|
+
work init --project my-app --base-branch develop \
|
|
21
|
+
--service frontend=3000 --service backend=8443 --service postgres=5432 \
|
|
22
|
+
--storybook-host app-ui
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
This writes `helmsmith.config.mjs` (edit the service commands, the scope templates, the areas and the commons), claims the project's port ranges in the registry so two projects on one machine never collide, and installs the git hooks under `.helmsmith/hooks` (commit them; each clone runs `work hooks install` once to point `core.hooksPath` at them).
|
|
26
|
+
|
|
27
|
+
## Manifest reference
|
|
28
|
+
|
|
29
|
+
| Key | Meaning |
|
|
30
|
+
|---|---|
|
|
31
|
+
| `project` | lowercase name; the registry key |
|
|
32
|
+
| `baseBranch`, `protectedBranches` | efforts start from and sync with the base; commits on protected branches are refused (default: the base only) |
|
|
33
|
+
| `worktreeRoot` | where area worktrees live (`.claude/worktrees`); each area at `<root>/<area>` |
|
|
34
|
+
| `branch.types` | allowed branch types (`feature`, `chore`, `fix`) |
|
|
35
|
+
| `slots.count`, `slots.reserved` | how many slots; reserved ones (slot 0, the human's) are never leased |
|
|
36
|
+
| `ports.services.<name>.base` | the slot-0 port of each service; slot N uses `base + N`; the project claims `[base, base + count)` |
|
|
37
|
+
| `services.<name>.{start,stop,health,healthyCodes,reset,healthTimeoutMs}` | shell commands run in the worktree with `PORT_*`, `SLOT`, `LOG_DIR` in the environment; key order is start order; `health` is polled every second |
|
|
38
|
+
| `storybook.hostRoot` | the package whose `.storybook` storybrokr boots from |
|
|
39
|
+
| `logs.dir` | per-worktree log directory (`.logs`), one file per service plus `refresh.log` |
|
|
40
|
+
| `env.file`, `env.template` | the env file emitted per worktree from `${VAR}` placeholders (`SLOT`, `PORT_<SERVICE>`, `PORT_STORYBOOK`, `LOG_DIR`, `PROJECT`, `AREA`, `BRANCH`, `WORKTREE`) |
|
|
41
|
+
| `refresh[]` | `{ when: glob, run }` commands and `{ when, mark }` marks selected by the paths a sync changed; `{ always: true, run }` runs every time; the mark `db-reset` runs `services.postgres.reset` before a fullstack start |
|
|
42
|
+
| `scopes.frontend`, `scopes.backend` | glob templates with `{group}`, `{section}`, `{module}`; a frontend effort holds the first set, a fullstack effort both |
|
|
43
|
+
| `areas.<path>.{module,commons,extraScopes}` | leaves only (`shop/cart`, never `shop` and `shop/cart` together); `module` fills the backend templates; `commons` makes the area cross-cutting |
|
|
44
|
+
| `commons.<name>` | shared paths never held exclusively; a cross-cutting effort write-locks them briefly |
|
|
45
|
+
| `expiry.{slotHours,commonsHours,storybookHours}` | idle expiry per lease kind (12 / 4 / 2) |
|
|
46
|
+
| `archive.{paths,keepDays,keepPerArea}` | what `retire` copies out of the worktree into `.slot-archive/`, and for how long |
|
|
47
|
+
|
|
48
|
+
## Verbs
|
|
49
|
+
|
|
50
|
+
- `work start --area <area> --type <type> --mode <fullstack|frontend> [--story <path>] [--join] [--no-sync]`: guards (area, type, mode, one open effort per area, scope overlap), the worktree, the branch, sync (fast-forward or merge, never rebase; a conflict stops before any lease), refresh, leases, config, run, record.
|
|
51
|
+
- `work status`, `work env`: what is open and the variables it runs with.
|
|
52
|
+
- `work finish [--park]`: stop only the pids the lease recorded, bring the Storybook down, release leases, push, leave commons notices; the worktree and branch stay.
|
|
53
|
+
- `work reap [--dry-run]`: the same for expired leases, parking the effort.
|
|
54
|
+
- `work retire`: archive, remove the worktree, delete the local branches that are on origin. The only destructive verb; refuses unpushed work.
|
|
55
|
+
- `work audit`: dirty or unpushed worktrees, foreign checkouts, aging leases, drift, stale notices, archive size.
|
|
56
|
+
|
|
57
|
+
Exit codes: 0 ok, 2 refused (first stderr line is the reason; `--json` prints `{ code, message, details }`), 1 error. The registry is `$HELMSMITH_HOME/registry.json`, default `~/.cache/helmsmith`, written atomically under a lock.
|
|
58
|
+
|
|
59
|
+
## What this phase does not do yet
|
|
60
|
+
|
|
61
|
+
- Frontend mode does not lease a Storybook port: storybrokr allocates its own and the lease records the instance id and port.
|
|
62
|
+
- Impact notices are commons-based ("commons auth changed on fix/platform/auth"); an import-graph version is planned.
|
|
63
|
+
- The full-stack runner spawns the manifest's commands itself; `stackbrokr` (a daemon with the same manifest) replaces it in a later phase without changing the manifest.
|
|
64
|
+
|
|
65
|
+
## Security note
|
|
66
|
+
|
|
67
|
+
The hooks under `.helmsmith/hooks` are tracked files that run on every committer's machine, exactly like husky's. The protected-branch rule is enforced by the scripts themselves (the list is baked in at install time), so it holds in a GUI client or a shell without `workbrokr`; only the commons and scope checks need the binary and are skipped with a warning without it. Review changes to that directory as you would any executable.
|
package/SKILL.md
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: work
|
|
3
|
+
description: Start, run, finish and audit area-based work with `work` (@helmsmith/workbrokr). Fires when the user wants to begin an effort on a part of the application ("start work on applications", "new effort on org/team", "open the cart area"), needs a slot or a running stack for a worktree, asks which slot or worktree to use, wants to finish or park an effort, or asks to clean up, retire or audit worktrees and slots. One worktree per area, branches are <type>/<area>, every effort starts from the latest base branch, no work ever happens on develop. CLI (`work start|status|finish|reap|retire|audit|env`) and MCP tools (`work_start`, `work_status`, `work_finish`, `work_reap`, `work_audit`, `work_env`).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# work
|
|
7
|
+
|
|
8
|
+
`work` owns the lifecycle of a piece of work in a repo that has a `helmsmith.config.{ts,mjs,json}`: it creates or reuses the **area's** worktree on a `<type>/<area>` branch, syncs it from the base branch, refreshes it, leases what the mode needs (a **slot** for `fullstack`, a storybrokr instance for `frontend`), writes the per-worktree config, runs it, and later finishes, expires, retires and audits it. State lives in one registry under `~/.cache/helmsmith`.
|
|
9
|
+
|
|
10
|
+
## Rules an agent applies before calling it
|
|
11
|
+
|
|
12
|
+
- **Never commit on the base branch** (`develop` here) or on `stage`/`prod`: the hooks refuse, and the main checkout is a mirror. Work only inside the worktree `work start` prints.
|
|
13
|
+
- **Pick the area from the manifest** (`work status --json` lists them). Areas are leaves like `org/applications`; the branch becomes `feature|chore|fix/<area>`.
|
|
14
|
+
- **Pick the type by intent** (`feature` new behaviour, `fix` a defect, `chore` tooling/docs) and **the mode by what you must run**: `fullstack` when the backend or database is involved, `frontend` when a scoped Storybook is enough (add `--story <path>` to boot one).
|
|
15
|
+
- **Read refusals, do not bypass them.** Exit code 2 is a rule saying no; the first stderr line (or the JSON `code`) says which:
|
|
16
|
+
- `EFFORT_OPEN`: someone holds this area (the message names the session). Ask, wait, or `--join` to work in the same checkout on purpose.
|
|
17
|
+
- `SCOPE_CONFLICT`: another effort holds overlapping paths. Pick another area or wait for it to finish.
|
|
18
|
+
- `SYNC_CONFLICT`: the merge from the base branch conflicts. Resolve it in the worktree the message names, commit, rerun with `--no-sync`.
|
|
19
|
+
- `DIRTY_WORKTREE` on finish: commit, or `work finish --park` to commit as `wip(<area>)` and push.
|
|
20
|
+
- `COMMONS_LOCKED` at commit time: a cross-cutting effort owns that shared code for a few hours; wait or coordinate.
|
|
21
|
+
- **Subagents** spawned from the worktree work inside the same effort (same branch, same leases, same session). They must not create their own git worktrees (no `isolation: "worktree"`); a subagent that needs its own stack starts its own effort with `work start` or joins this one with `--join`.
|
|
22
|
+
- **Never run the project's tools from outside the worktree** and never bypass `make`/`work` to reach a port directly: slot 0's ports belong to the human.
|
|
23
|
+
|
|
24
|
+
## The loop
|
|
25
|
+
|
|
26
|
+
1. `work status --json` → what is open, by whom, and which areas exist.
|
|
27
|
+
2. `work start --area <area> --type <type> --mode <fullstack|frontend> [--story <path>] --json` → the effort record, the worktree path, the leases (ports under `leases[].ports`). `cd` into `effort.worktree`.
|
|
28
|
+
3. Work there. `work env --area <area>` prints `PORT_*`, `SLOT`, `LOG_DIR`, `MODE` when a tool needs them. Service logs are in `<worktree>/.logs/<service>.log`.
|
|
29
|
+
4. `work finish --area <area>` (or `--park`) when done: the runner stops, leases are released, the branch is pushed; the worktree and branch stay for the next effort. Open the PR from the branch.
|
|
30
|
+
5. `work retire --area <area>` only when an area is being removed for good (archives evidence first; refuses unpushed work).
|
|
31
|
+
6. `work reap` expires idle leases; `work audit --json` lists unsaved or unpushed work, stray worktrees, aging leases, drift and stale notices.
|
|
32
|
+
|
|
33
|
+
## Commands
|
|
34
|
+
|
|
35
|
+
| Command | Purpose |
|
|
36
|
+
|---|---|
|
|
37
|
+
| `work init --project <name> --service name=port… [--base-branch b] [--storybook-host dir] [--no-hooks] [--force]` | Write a starter manifest, claim the port ranges, install the hooks |
|
|
38
|
+
| `work hooks install [--project-root dir]` | Install the hooks in a clone whose manifest already exists |
|
|
39
|
+
| `work start --area a --type t --mode m [--story p] [--join] [--no-sync] [--json]` | Begin (or join) an effort |
|
|
40
|
+
| `work status [--area a] [--json]` | Efforts, leases, drift, notices |
|
|
41
|
+
| `work env (--area a \| --slot n) [--json]` | Slot-derived variables |
|
|
42
|
+
| `work finish --area a [--park] [--json]` | Stop, release, push |
|
|
43
|
+
| `work reap [--dry-run] [--json]` | Expire idle leases |
|
|
44
|
+
| `work retire --area a [--json]` | Archive and remove an area's worktree (destructive) |
|
|
45
|
+
| `work audit [--json]` | What would otherwise be forgotten |
|
|
46
|
+
| `work mcp` | MCP stdio server |
|
|
47
|
+
|
|
48
|
+
Every command takes `--project-root <dir>`; without it the repo is the main checkout of the current directory. Exit codes: 0 ok, 2 refused, 1 error.
|
|
49
|
+
|
|
50
|
+
## MCP tools
|
|
51
|
+
|
|
52
|
+
`work_start { area, type, mode, story?, join?, sync? }`, `work_status { area? }`, `work_finish { area, park? }`, `work_reap { dryRun? }`, `work_audit {}`, `work_env { area }`. Results are the same JSON the CLI's `--json` prints; failures set `isError` with `{ code, message, details? }`.
|
|
53
|
+
|
|
54
|
+
## Error codes
|
|
55
|
+
|
|
56
|
+
Refusals (exit 2): `MANIFEST_INVALID`, `AREA_UNKNOWN`, `TYPE_UNKNOWN`, `MODE_UNKNOWN`, `MAIN_CHECKOUT`, `PROTECTED_BRANCH`, `EFFORT_OPEN`, `EFFORT_NOT_FOUND`, `SCOPE_CONFLICT`, `COMMONS_LOCKED`, `NO_FREE_SLOT`, `LEASE_NOT_FOUND`, `PORT_RANGE_TAKEN`, `SYNC_CONFLICT`, `DIRTY_WORKTREE`, `UNPUSHED`. Faults (exit 1): `MANIFEST_NOT_FOUND`, `HEALTH_TIMEOUT` (the last probe output is attached), `SERVICE_FAILED`, `STORYBROKR_FAILED`, `GIT_FAILED`, `INTERNAL`.
|
package/bin/work.mjs
ADDED