@niwa-labs/pstack 0.0.0-stage → 0.0.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 +21 -0
- package/README.md +260 -2
- package/package.json +28 -4
- package/scripts/upstream-map.ts +90 -0
- package/src/author.ts +57 -0
- package/src/binding.ts +32 -0
- package/src/catalog.ts +86 -0
- package/src/composition.ts +66 -0
- package/src/index.ts +50 -0
- package/src/mapping/analyze.ts +223 -0
- package/src/mapping/assemble.ts +96 -0
- package/src/mapping/diff.ts +139 -0
- package/src/mapping/format.ts +67 -0
- package/src/mapping/git.ts +69 -0
- package/src/mapping/index.ts +18 -0
- package/src/mapping/maintain.ts +36 -0
- package/src/mapping/schema.ts +50 -0
- package/src/mapping/sources.ts +108 -0
- package/src/mapping/tool.ts +77 -0
- package/src/mapping/verify.ts +130 -0
- package/src/plugin.ts +136 -0
- package/src/policy.ts +115 -0
- package/src/ports.ts +184 -0
- package/src/pr-binding.ts +88 -0
- package/src/records.ts +61 -0
- package/src/roles.ts +49 -0
- package/src/trunk.ts +59 -0
- package/src/upstream-actions.ts +135 -0
- package/src/upstream-records.ts +71 -0
- package/src/upstream.ts +151 -0
- package/src/workflows/adapted.md +780 -0
- package/src/workflows/authoring-a-skill.ts +52 -0
- package/src/workflows/autonomous-run.ts +56 -0
- package/src/workflows/autopilot-full.ts +90 -0
- package/src/workflows/autopilot-stack.ts +125 -0
- package/src/workflows/babysit.ts +124 -0
- package/src/workflows/benny-reproduce.ts +122 -0
- package/src/workflows/benny-triage.ts +89 -0
- package/src/workflows/bug-fix.ts +54 -0
- package/src/workflows/entry.ts +130 -0
- package/src/workflows/eval.ts +63 -0
- package/src/workflows/feature.ts +54 -0
- package/src/workflows/hillclimb.ts +78 -0
- package/src/workflows/investigation.ts +41 -0
- package/src/workflows/lib/catalog.ts +45 -0
- package/src/workflows/lib/change.ts +70 -0
- package/src/workflows/lib/forensics.ts +37 -0
- package/src/workflows/lib/git.ts +30 -0
- package/src/workflows/lib/go.ts +58 -0
- package/src/workflows/lib/inputs.ts +34 -0
- package/src/workflows/lib/lane.ts +170 -0
- package/src/workflows/lib/measure.ts +34 -0
- package/src/workflows/lib/plan.ts +24 -0
- package/src/workflows/lib/script.ts +79 -0
- package/src/workflows/lib/ship.ts +110 -0
- package/src/workflows/lib/texts.ts +18 -0
- package/src/workflows/lib/trunk.ts +91 -0
- package/src/workflows/multi-phase-plan.ts +83 -0
- package/src/workflows/opening-a-pr.ts +62 -0
- package/src/workflows/pause-safely.ts +50 -0
- package/src/workflows/perf-issue.ts +87 -0
- package/src/workflows/prototype.ts +76 -0
- package/src/workflows/refactoring.ts +54 -0
- package/src/workflows/runtime-forensics.ts +26 -0
- package/src/workflows/scenarios.ts +380 -0
- package/src/workflows/session-pickup.ts +57 -0
- package/src/workflows/shipping.ts +63 -0
- package/src/workflows/suite.ts +129 -0
- package/src/workflows/texts/authoring-a-skill.json +5 -0
- package/src/workflows/texts/autonomous-run.json +5 -0
- package/src/workflows/texts/autopilot-full.json +5 -0
- package/src/workflows/texts/autopilot-stack.json +5 -0
- package/src/workflows/texts/babysit.json +5 -0
- package/src/workflows/texts/benny-reproduce.json +5 -0
- package/src/workflows/texts/benny-triage.json +5 -0
- package/src/workflows/texts/bug-fix.json +5 -0
- package/src/workflows/texts/bugbot-triage.json +5 -0
- package/src/workflows/texts/eval.json +5 -0
- package/src/workflows/texts/feature.json +5 -0
- package/src/workflows/texts/hillclimb.json +5 -0
- package/src/workflows/texts/investigation.json +5 -0
- package/src/workflows/texts/multi-phase-plan.json +5 -0
- package/src/workflows/texts/opening-a-pr.json +5 -0
- package/src/workflows/texts/pause-safely.json +5 -0
- package/src/workflows/texts/perf-issue.json +5 -0
- package/src/workflows/texts/prototype.json +5 -0
- package/src/workflows/texts/refactoring.json +5 -0
- package/src/workflows/texts/runtime-forensics.json +5 -0
- package/src/workflows/texts/session-pickup.json +5 -0
- package/src/workflows/texts/trace-forensics.json +5 -0
- package/src/workflows/texts/visual-parity.json +5 -0
- package/src/workflows/texts/worker.json +5 -0
- package/src/workflows/trace-forensics.ts +27 -0
- package/src/workflows/upstream-sync.ts +182 -0
- package/src/workflows/visual-parity.ts +52 -0
- package/src/workflows/worktree-cleanup.ts +57 -0
- package/test/author.test.ts +61 -0
- package/test/benny.test.ts +138 -0
- package/test/binding.test.ts +54 -0
- package/test/catalog-helpers.test.ts +49 -0
- package/test/closure.test.ts +45 -0
- package/test/composition.test.ts +23 -0
- package/test/eval.test.ts +23 -0
- package/test/lanes.test.ts +334 -0
- package/test/mapping-diff.test.ts +64 -0
- package/test/mapping-support.ts +110 -0
- package/test/mapping-texts.test.ts +106 -0
- package/test/mapping.test.ts +276 -0
- package/test/package-layout.ts +68 -0
- package/test/policy.test.ts +98 -0
- package/test/ports.test.ts +45 -0
- package/test/ports.ts +173 -0
- package/test/roles.test.ts +21 -0
- package/test/suite.test.ts +167 -0
- package/test/support.ts +541 -0
- package/test/texts.test.ts +174 -0
- package/test/tool.test.ts +48 -0
- package/test/trunk-helpers.test.ts +149 -0
- package/test/trunk.test.ts +24 -0
- package/test/upstream-sync.test.ts +246 -0
- package/test/upstream.test.ts +106 -0
- package/test/worktree-cleanup.test.ts +107 -0
- package/tsconfig.json +7 -0
- package/upstream/LICENSE +21 -0
- package/upstream/SOURCE.json +5 -0
- package/upstream/benny/FOR_AGENTS.md +89 -0
- package/upstream/benny/README.md +23 -0
- package/upstream/benny/skills/reproduce-and-fix-issues/SKILL.md +310 -0
- package/upstream/benny/skills/reproduce-and-fix-issues/references/control-adapter.md +169 -0
- package/upstream/benny/skills/reproduce-and-fix-issues/references/feature-map.example.md +205 -0
- package/upstream/benny/skills/reproduce-and-fix-issues/references/verify-existing-fix.md +93 -0
- package/upstream/benny/skills/setup-benny/SKILL.md +265 -0
- package/upstream/benny/skills/triage-issue-reports/SKILL.md +240 -0
- package/upstream/benny/skills/triage-issue-reports/references/routing.example.md +61 -0
- package/upstream/benny/templates/configuration.example.yaml +84 -0
- package/upstream/benny/templates/reproduce-automation-prompt.md +33 -0
- package/upstream/benny/templates/triage-automation-prompt.md +39 -0
- package/upstream/mapping.json +699 -0
- package/upstream/poteto-mode/SKILL.md +110 -0
- package/upstream/poteto-mode/playbooks/authoring-a-skill.md +12 -0
- package/upstream/poteto-mode/playbooks/autonomous-run.md +13 -0
- package/upstream/poteto-mode/playbooks/autopilot-full.md +25 -0
- package/upstream/poteto-mode/playbooks/autopilot-stack.md +8 -0
- package/upstream/poteto-mode/playbooks/babysit.md +10 -0
- package/upstream/poteto-mode/playbooks/bug-fix.md +15 -0
- package/upstream/poteto-mode/playbooks/eval.md +25 -0
- package/upstream/poteto-mode/playbooks/feature.md +21 -0
- package/upstream/poteto-mode/playbooks/hillclimb.md +21 -0
- package/upstream/poteto-mode/playbooks/investigation.md +14 -0
- package/upstream/poteto-mode/playbooks/multi-phase-plan.md +11 -0
- package/upstream/poteto-mode/playbooks/opening-a-pr.md +9 -0
- package/upstream/poteto-mode/playbooks/pause-safely.md +10 -0
- package/upstream/poteto-mode/playbooks/perf-issue.md +25 -0
- package/upstream/poteto-mode/playbooks/prototype.md +14 -0
- package/upstream/poteto-mode/playbooks/refactoring.md +16 -0
- package/upstream/poteto-mode/playbooks/runtime-forensics.md +11 -0
- package/upstream/poteto-mode/playbooks/session-pickup.md +11 -0
- package/upstream/poteto-mode/playbooks/shipping.md +12 -0
- package/upstream/poteto-mode/playbooks/trace-forensics.md +14 -0
- package/upstream/poteto-mode/playbooks/visual-parity.md +11 -0
- package/upstream/poteto-mode/playbooks/worktree-cleanup.md +12 -0
- package/upstream/poteto-mode/references/bugbot-triage.md +142 -0
- package/upstream/poteto-mode/worker.md +11 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Niwa Labs contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,261 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @niwa-labs/pstack
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Delivery playbooks run as niwa's built-in workflows: an entry that routes a request to the playbook it needs, one
|
|
4
|
+
workflow per upstream playbook, Benny for issue reports when he is enabled, and a suite that tries every new version
|
|
5
|
+
of them before the host runs it.
|
|
6
|
+
|
|
7
|
+
## Composition
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
import { addressingOf, pstack } from "@niwa-labs/pstack";
|
|
11
|
+
|
|
12
|
+
const base = defaultComposition({ home, harnesses, agents });
|
|
13
|
+
const beforeWorkflow = base.filter((part) => part.name !== "workflow");
|
|
14
|
+
const workflow = base.filter((part) => part.name === "workflow");
|
|
15
|
+
export default [
|
|
16
|
+
...beforeWorkflow,
|
|
17
|
+
...pstack({
|
|
18
|
+
bind: addressingOf(base),
|
|
19
|
+
forge: { servers: [{ host: "gitlab.example.com", url: "https://gitlab.example.com", token: secret("GITLAB_TOKEN") }] },
|
|
20
|
+
roles: {
|
|
21
|
+
lead: { harness: "claude" },
|
|
22
|
+
author: { harness: "codex", box: true },
|
|
23
|
+
reviewer: { harness: "claude" },
|
|
24
|
+
verifier: { harness: "pi", vendor: "minimax" },
|
|
25
|
+
judge: { harness: "pi", vendor: "glm" },
|
|
26
|
+
},
|
|
27
|
+
benny: {
|
|
28
|
+
repo: { host: "gitlab.example.com", path: "acme/billing", local: "/work/billing" },
|
|
29
|
+
// Your plugins that provide his three ports; see "Benny needs your plugins".
|
|
30
|
+
ports: [acmeTracker(), acmeChat(), acmeControl()],
|
|
31
|
+
},
|
|
32
|
+
}),
|
|
33
|
+
...workflow,
|
|
34
|
+
];
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`pstack()` installs forge, evidence, watch and plan, then the pstack plugin. The host provides the sessions and git
|
|
38
|
+
modules before it and the workflow module after it. `bind` is the binding of the host's sessions and agents modules
|
|
39
|
+
(`addressingOf`), so a session attests under one address for its whole life and an agent's session as the agent. Without
|
|
40
|
+
`benny`, none of the ports below is needed.
|
|
41
|
+
|
|
42
|
+
## Roles
|
|
43
|
+
|
|
44
|
+
- `lead` frames, routes and judges, read-only.
|
|
45
|
+
- `author` writes code. It carries `box: true`. The workflow checks the real worktree path before opening its author
|
|
46
|
+
session through the SDK. It grants that worktree's project writes and adds only the configured forge hosts covered by
|
|
47
|
+
the run's grant.
|
|
48
|
+
- `reviewer` judges review threads.
|
|
49
|
+
- `verifier` re-runs the gates and shows the behaviour live. It must run on another harness than the author, and it
|
|
50
|
+
attests its verdicts under its own name.
|
|
51
|
+
- `judge` grades an evaluation. It is of another vendor than the candidates.
|
|
52
|
+
|
|
53
|
+
## Playbooks
|
|
54
|
+
|
|
55
|
+
| Playbook | What it does |
|
|
56
|
+
|---|---|
|
|
57
|
+
| investigation | Answers a question about the code, with sources |
|
|
58
|
+
| trace-forensics, runtime-forensics | Hold hypotheses against a trace or runtime evidence, and name the cause one confirmed hypothesis leaves |
|
|
59
|
+
| bug-fix, feature, refactoring, perf-issue, visual-parity, authoring-a-skill | The lead frames the work, and an owner lane carries it to a verified pull request |
|
|
60
|
+
| hillclimb | One metric, one change at a time: kept when the measurement moved, reverted in full otherwise |
|
|
61
|
+
| autonomous-run | Iterates in a boxed worktree until a done predicate holds |
|
|
62
|
+
| prototype | Throwaway variants in scratch worktrees, and a recommendation |
|
|
63
|
+
| eval | Variants answer blind; a judge of another vendor grades them on a rubric they never see |
|
|
64
|
+
| multi-phase-plan | Writes the plan as a revision in niwa and asks the owner's go, attested node by node |
|
|
65
|
+
| autopilot-full | One owner lane per plan node, in parallel off trunk; the nodes land one at a time under the merge policy |
|
|
66
|
+
| autopilot-stack | The same, stacked where one node builds on another, without merging; it can carry a stack onto a new lower head |
|
|
67
|
+
| shipping | Lands a verified stack bottom up under the merge policy |
|
|
68
|
+
| opening-a-pr | Opens a ready pull request with the briefing upstream asks for |
|
|
69
|
+
| babysit | Conflicts, threads, then CI, in `check`, `threads-only` or `drive` mode; it never merges or rebases |
|
|
70
|
+
| pause-safely | A `wip:` commit and a resume note in the worktree the work is in |
|
|
71
|
+
| session-pickup | Where the work stands, from the plan and what was attested on it |
|
|
72
|
+
| worktree-cleanup | On a merge on the forge, removes the clean worktrees the merged head was built in |
|
|
73
|
+
| upstream-sync | Not a playbook: carries the map of the upstream snapshot to a new snapshot, below; gated like the playbooks |
|
|
74
|
+
|
|
75
|
+
The playbooks are upstream's text with niwa's wording where upstream names something a session does not have: Cursor's
|
|
76
|
+
skills and their principles, model slugs, `/loop`, `gh` and `origin`, `agent-transcripts/`. Scripts use `ask()` for
|
|
77
|
+
a typed one-shot answer and `session()` for a conversation with durable turns. Where a playbook shows the session tools
|
|
78
|
+
to a model, the model can open a helper with `session.start`, ask it with `session.ask` and close it with `session.end`.
|
|
79
|
+
The helper belongs to the same run and inherits its launch limits. Pull requests go through the forge module, workflows
|
|
80
|
+
and timers wake work, and `session.read` reads a session's history. Every such change
|
|
81
|
+
is an `adapted` entry of the map, or a `dropped` one with its reason, and `check` fails on any difference between a
|
|
82
|
+
text and upstream that the map does not say. Every session also gets the worker rules, which carry the goal, candor and
|
|
83
|
+
reply rules of upstream's operator skill. Benny's draft pull request is the one stated exception to the rule that a pull
|
|
84
|
+
request is opened ready.
|
|
85
|
+
|
|
86
|
+
A lane builds in a worktree off trunk with a boxed author. It opens the pull request only for the commit the author
|
|
87
|
+
made; a head on the forge that the author did not answer is a push the lane did not make. Verifiers that did not write
|
|
88
|
+
the code attest the `gates` and `live` verdicts on that head.
|
|
89
|
+
|
|
90
|
+
## The merge policy
|
|
91
|
+
|
|
92
|
+
A pull request lands only when all of these hold at its current head:
|
|
93
|
+
|
|
94
|
+
- the owner's go covers each plan node it delivers. A go is bound by digest to the plan's revision, the node and the
|
|
95
|
+
change, and only the owner or a run may give one. A revised plan needs a new go.
|
|
96
|
+
- the `gates` and `live` verdicts passed, from someone other than the patch's author;
|
|
97
|
+
- the pipeline of the head is green;
|
|
98
|
+
- the merge result of the pair the forge would merge now is green and attested with that pair of commits.
|
|
99
|
+
|
|
100
|
+
An authoring lane records its native author session and registered worktree for the exact repository, pull request
|
|
101
|
+
and head. Standalone shipping reads that receipt. A missing or ambiguous receipt, or an explicit author that
|
|
102
|
+
differs from it, stops shipping until the head has verified provenance.
|
|
103
|
+
|
|
104
|
+
Shipping reads the target branch tip from the forge and checks the latest pipelines of this merge request against
|
|
105
|
+
both commit IDs. GitLab's merge endpoint can condition on the source commit only. On GitLab even a verified pair
|
|
106
|
+
remains open for a separate landing decision. A capable forge must enforce both commit IDs in the merge operation.
|
|
107
|
+
|
|
108
|
+
## Candidates and the suite
|
|
109
|
+
|
|
110
|
+
Every built-in but the suite is offered gated, the upstream sync among them. A new version comes in as a candidate that the host neither installs nor
|
|
111
|
+
runs on events. Before any version was accepted, the candidate is shown and runs on nothing.
|
|
112
|
+
|
|
113
|
+
The suite (`pstack-suite`) is started by the owner on a fixture: a repository it may change, on a forge project it may
|
|
114
|
+
merge into. Niwa pins the offered set to the suite run, and each scenario starts its pinned version. When the suite exercises the
|
|
115
|
+
entry, Niwa uses the same set for the entry's child runs. An ordinary entry starts accepted playbooks. One scenario
|
|
116
|
+
hands its plan to the next. The sync's scenario seeds what it
|
|
117
|
+
needs itself, in worktrees of the fixture: a tiny upstream checkout, and a branch holding a tiny package folder whose map
|
|
118
|
+
covers its snapshot; upstream is reworded, and the scenario passes when the sync carries the map across and assembles
|
|
119
|
+
the texts. Only when every scenario passes
|
|
120
|
+
does it ask Niwa to promote the pinned candidates together. If another trial or a new offer changed the set, Niwa
|
|
121
|
+
leaves the accepted versions in place. On its own fixture's plans, the suite gives the go itself, as a run may.
|
|
122
|
+
|
|
123
|
+
## Benny
|
|
124
|
+
|
|
125
|
+
With `benny`, the plugin offers the agent `benny` to the agents module, an action `benny.report`, and two gated
|
|
126
|
+
automations. Every report is triaged as data: the triage session searches the issue tracker for it and files an issue
|
|
127
|
+
for a clear, new bug, and the workflow posts its verdict once, in the thread the report came in on. A report triaged as
|
|
128
|
+
a bug is reproduced twice through the product control before any code is touched, and then fixed in a draft pull
|
|
129
|
+
request, which is linked to its issue; the owner is told once how it ended. Benny never merges or deploys.
|
|
130
|
+
|
|
131
|
+
`benny.report` is for the report channel's plugin: it hands a report in with `source`, the channel's own address of the
|
|
132
|
+
report, which comes back to `benny.channel.reply` with the verdict. A report with no `source` is triaged and
|
|
133
|
+
reproduced all the same, and nothing is posted.
|
|
134
|
+
|
|
135
|
+
## Benny needs your plugins
|
|
136
|
+
|
|
137
|
+
Benny's tracker, chat and product are yours, not pstack's, so pstack ships three typed contracts and no
|
|
138
|
+
implementation of them. Each is a port: a plugin of yours offers it and registers the actions of its contract.
|
|
139
|
+
|
|
140
|
+
| Port | Offered at | Actions it provides |
|
|
141
|
+
|---|---|---|
|
|
142
|
+
| issue tracker | `BENNY_TRACKER` | `benny.tracker.find` (search by text, state and source), `benny.tracker.create` (title, body, source, labels), `benny.tracker.comment` (a recurrence note and a source on an existing issue), `benny.tracker.link-pr` (a pull request, by subject or url, on an issue) |
|
|
143
|
+
| report channel | `BENNY_CHANNEL` | `benny.channel.reply` (one reply in the thread of a report, by its `source`), `benny.channel.notify` (a status for the owner) |
|
|
144
|
+
| product control | `BENNY_CONTROL` | `benny.control.capabilities`, `bring-up`, `drive`, `inspect`, `screenshot`, `record`, `cleanup`: what upstream's control-adapter contract asks of the app it drives |
|
|
145
|
+
|
|
146
|
+
The channel also takes reports in: when one arrives, its plugin calls `benny.report` with the text, who wrote it and
|
|
147
|
+
its `source`. The control has no default for any project; the others have none either.
|
|
148
|
+
|
|
149
|
+
- The types are the action references `bennyTrackerFind`, `bennyChannelReply`, `bennyControlDrive` and the rest,
|
|
150
|
+
exported from `@niwa-labs/pstack` with their zod schemas. `action(ref, { ... })` builds the action from a
|
|
151
|
+
reference, so a provider and pstack check against one schema. The description of each reference says what the
|
|
152
|
+
action must and must not do: `inspect` is read-only, `drive` is a real user action and never an injected state,
|
|
153
|
+
`reply` posts in the report's thread and nowhere else, `create` makes an issue that links back to its source.
|
|
154
|
+
- A provider offers its port in its setup, with `api.offer(BENNY_TRACKER, { description })`. pstack reads the offers
|
|
155
|
+
when it is installed, so the providers are installed before it: list them in `benny.ports` and `pstack()` does so, or
|
|
156
|
+
install them yourself ahead of `...pstack()`. A host that lacks a port does not start: the error names each missing
|
|
157
|
+
port and says to install its provider before pstack.
|
|
158
|
+
- The triage session is shown `find`, `create` and `comment`; the reproduction session is shown the control actions.
|
|
159
|
+
The channel is never shown to a session: the workflow is the only poster.
|
|
160
|
+
- Install the providers only on a host that enables `benny`: without it pstack registers refusing stand-ins under the
|
|
161
|
+
same action names (the suite's grant has to name them), and a provider would clash with them.
|
|
162
|
+
|
|
163
|
+
A minimal tracker provider:
|
|
164
|
+
|
|
165
|
+
```ts
|
|
166
|
+
import { action } from "@niwa-labs/core";
|
|
167
|
+
import { plugin } from "@niwa-labs/plugin";
|
|
168
|
+
import { BENNY_TRACKER, bennyTrackerComment, bennyTrackerCreate, bennyTrackerFind, bennyTrackerLinkPr } from "@niwa-labs/pstack";
|
|
169
|
+
|
|
170
|
+
// `acme` is your tracker's own client; the plugin only maps it onto the contract.
|
|
171
|
+
export function acmeTracker() {
|
|
172
|
+
return plugin("acme-tracker", (api) => {
|
|
173
|
+
api.offer(BENNY_TRACKER, { description: "Acme's issue tracker" });
|
|
174
|
+
api.action(action(bennyTrackerFind, { recovery: "repeat", effect: "read", world: "external", run: async (input) => ({ items: await acme.search(input.text, input.state, input.source) }) }));
|
|
175
|
+
api.action(action(bennyTrackerCreate, { recovery: "do-not-repeat", effect: "write", world: "external", run: async (input) => await acme.create(input) }));
|
|
176
|
+
api.action(action(bennyTrackerComment, { recovery: "do-not-repeat", effect: "write", world: "external", run: async (input) => (await acme.comment(input), { ok: true as const }) }));
|
|
177
|
+
api.action(action(bennyTrackerLinkPr, { recovery: "do-not-repeat", effect: "write", world: "external", run: async (input) => (await acme.linkPr(input), { ok: true as const }) }));
|
|
178
|
+
});
|
|
179
|
+
}
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
The chat and the control are written the same way, with their own references. The tests of this package install
|
|
183
|
+
in-memory providers of the three ports (`test/ports.ts`) so the suite can run Benny; they are a stand-in, not a default.
|
|
184
|
+
|
|
185
|
+
## The upstream snapshot and its map
|
|
186
|
+
|
|
187
|
+
`upstream/` keeps the pstack plugin of [cursor/plugins](https://github.com/cursor/plugins) (MIT) at the commit in
|
|
188
|
+
`upstream/SOURCE.json`: the operator's skill, the worker rules, the playbooks, the references they name, and the Benny
|
|
189
|
+
pack. `upstream/mapping.json` records what became of it in pstack, an entry to a line:
|
|
190
|
+
|
|
191
|
+
```json
|
|
192
|
+
{"id":"bug-fix:03","upstream":{"commit":"<upstream commit>","file":"poteto-mode/playbooks/bug-fix.md","range":[476,892]},"ours":[{"commit":"<pstack commit>","file":"packages/pstack/src/workflows/lib/texts.ts","range":[120,610]}],"kind":"prompt"}
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
- A range is `[start, end)` in characters (UTF-16 code units, as `String.slice` counts), and no text is stored. The
|
|
196
|
+
upstream side names a file of the snapshot at a commit of upstream. Our side names a file of this repository, from
|
|
197
|
+
its root, at the pstack commit the range was recorded at.
|
|
198
|
+
- `kind` says what became of the block. `prompt`: it goes into a prompt as upstream wrote it. `adapted`: our own text
|
|
199
|
+
replaces it in a prompt (the text is in `src/workflows/adapted.md`, and the entry links to its range). `code`: code
|
|
200
|
+
of ours implements it. `dropped`: we do not take it, and `note` says why.
|
|
201
|
+
- The upstream side is covered almost entirely: the files of the snapshot are cut into blocks, and what is not taken is
|
|
202
|
+
`dropped`, which counts as covered. The target is 95% of upstream's characters. The two upstream ranges of one file at
|
|
203
|
+
one commit never overlap. Our side is not covered: `ours` only links a block to the code or text that implements or
|
|
204
|
+
carries it, so several entries may link to the same range, and code of ours with no entry is fine.
|
|
205
|
+
- The texts the scripts import, `src/workflows/texts/*.json`, are assembled from the map: the `prompt` blocks of a file
|
|
206
|
+
verbatim from the snapshot, the `adapted` ones from our text, in upstream's order. `dropped` blocks are in no prompt.
|
|
207
|
+
A text is the files it is made of, each cut at its last non-blank character and followed by one blank line, and that
|
|
208
|
+
glue is the only thing in it that is not a block. They are not edited by hand: `assemble` writes them.
|
|
209
|
+
- Nothing is edited in a prompt outside the map. A text equals upstream except exactly where an `adapted` entry puts our
|
|
210
|
+
wording in and a `dropped` entry takes a range out, so a file that goes into a text has no `code` block: a block that
|
|
211
|
+
code of ours implements and a prompt leaves out is `dropped`, and its note says where the code is. `check` reads the
|
|
212
|
+
texts as they are on disk and holds each to the map (see below).
|
|
213
|
+
|
|
214
|
+
The tool is `bun packages/pstack/scripts/upstream-map.ts`:
|
|
215
|
+
|
|
216
|
+
| Command | What it does |
|
|
217
|
+
|---|---|
|
|
218
|
+
| `check` | Validates the map and reports the coverage of upstream's characters, per file and in total, with the uncovered ranges. For each entry, on each side, it follows the range from the commit it was recorded at to the current one (upstream: to the snapshot's commit; ours: to `HEAD`, or the working tree with `--worktree`) and says unchanged (it only shifted), touched (with the old and the new text of the range) or gone. It also lists upstream text that is new and uncovered, and the texts' own problems (an edit by hand, a block left out as `code`, upstream text no entry accounts for, a text with no file or a file with no text), which it counts apart from the map's because they follow the map and lag it until `assemble`. It draws no conclusion. `--out <file>` writes the report as JSON, `--summary` prints the numbers. |
|
|
219
|
+
| `advance` | Records the entries that are unchanged at the current commits and positions. |
|
|
220
|
+
| `accept <id>...` | Records the named entries at the positions their ranges were carried to. |
|
|
221
|
+
| `assemble` | Writes the texts from the map; `--check` only compares. |
|
|
222
|
+
| `refresh <checkout> [<commit>]` | Takes a new snapshot of an upstream checkout at a commit of it, read through git: the checkout's working tree is not read and it is not written. The mapping stays. |
|
|
223
|
+
|
|
224
|
+
Ranges are carried by comparing the two texts by lines and then by the characters the changed lines share at their
|
|
225
|
+
start and end. `--upstream <checkout>` is needed only while the map has ranges at an upstream commit other than the
|
|
226
|
+
snapshot's.
|
|
227
|
+
|
|
228
|
+
### Updating upstream
|
|
229
|
+
|
|
230
|
+
Start `pstack-upstream-sync` with the path of an upstream checkout (and a commit of it, if not its HEAD, and the
|
|
231
|
+
`package` folder of the repository, `packages/pstack` by default). It is gated like the playbooks: a new version of it
|
|
232
|
+
comes in as a candidate and the suite tries it first. In a worktree of its own it takes the snapshot and commits it, then
|
|
233
|
+
loops: the tool measures the map, and an author boxed to the worktree works on what the report shows (maps uncovered
|
|
234
|
+
text, follows touched and gone entries into our code and texts, drops what is not taken with the reason). The author
|
|
235
|
+
edits files and answers the ids of the entries that are settled where the report carried them; the workflow commits
|
|
236
|
+
what it edited, records those entries and the unchanged ones, and measures again. It stops when the coverage is at least
|
|
237
|
+
95% (`min`) and no entry is touched or gone, or after `rounds` rounds, and says what is left. What would change what a
|
|
238
|
+
prompt or a workflow does is not the author's to decide: it goes to the owner as a question, and its answer is carried
|
|
239
|
+
out in a last round. The texts are then assembled from the map and committed, and the map is measured once more: the
|
|
240
|
+
texts lag the map until they are assembled, so they are held to it only then, and the run is `synced` only when the map
|
|
241
|
+
and the texts have no problem.
|
|
242
|
+
|
|
243
|
+
The tool and git run on the host, in the pstack plugin's actions (`pstack.upstream.refresh`, `measure`, `record`,
|
|
244
|
+
`assemble`, `commit` and `state`), never in `proc.run`: a real box reads only its own directory, so it can read neither
|
|
245
|
+
the upstream checkout nor the repository a worktree belongs to, and the boxed author cannot run git either. Each action
|
|
246
|
+
works only on one of niwa's worktrees, reads the checkout through git and never writes it, and writes inside the
|
|
247
|
+
worktree.
|
|
248
|
+
|
|
249
|
+
By hand, the same: `refresh`, then `check`, settle what it shows, `accept` or edit the entries, `advance`, `assemble`.
|
|
250
|
+
The tool reads and writes the package folder it is installed in.
|
|
251
|
+
|
|
252
|
+
## What niwa does not give yet
|
|
253
|
+
|
|
254
|
+
- A script's `uses` holds call rules only, so a run cannot hold the write and network rules of a box. The author's box
|
|
255
|
+
is a right of the pstack plugin.
|
|
256
|
+
- The git module's actions carry no target, so the entry's `git.*@{repo.local}` reaches none of them. The entry names
|
|
257
|
+
the worktree actions it calls untargeted.
|
|
258
|
+
- A real `proc.run` box reads only its own directory, and a niwa worktree's `.git` leads into the main repository, outside
|
|
259
|
+
it: git does not run in a worktree there at all (`rev-parse`, `status`, `show` and `commit` all fail as "not a git
|
|
260
|
+
repository"). The lanes read git through `proc.run`, so they work only where the box is not applied; the upstream sync
|
|
261
|
+
does its tool and git work on the host instead.
|
package/package.json
CHANGED
|
@@ -1,6 +1,30 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@niwa-labs/pstack",
|
|
3
|
-
"version": "0.0.0
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"license": "MIT",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"scripts": {
|
|
7
|
+
"upstream-map": "bun scripts/upstream-map.ts"
|
|
8
|
+
},
|
|
9
|
+
"exports": {
|
|
10
|
+
".": "./src/index.ts"
|
|
11
|
+
},
|
|
12
|
+
"dependencies": {
|
|
13
|
+
"@niwa-labs/core": "*",
|
|
14
|
+
"@niwa-labs/evidence": "*",
|
|
15
|
+
"@niwa-labs/flow": "*",
|
|
16
|
+
"@niwa-labs/flow-code": "*",
|
|
17
|
+
"@niwa-labs/flow-eval": "*",
|
|
18
|
+
"@niwa-labs/forge": "*",
|
|
19
|
+
"@niwa-labs/plan": "*",
|
|
20
|
+
"@niwa-labs/plugin": "*",
|
|
21
|
+
"@niwa-labs/script": "*",
|
|
22
|
+
"@niwa-labs/watch": "*",
|
|
23
|
+
"@niwa-labs/workflow": "*",
|
|
24
|
+
"zod": "^4.6.7"
|
|
25
|
+
},
|
|
26
|
+
"devDependencies": {
|
|
27
|
+
"@niwa-labs/sessions": "*",
|
|
28
|
+
"@niwa-labs/testing": "*"
|
|
29
|
+
}
|
|
30
|
+
}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
// Measure the mapping of the upstream snapshot: `bun packages/pstack/scripts/upstream-map.ts <command>`.
|
|
2
|
+
//
|
|
3
|
+
// check [--upstream <checkout>] [--head <rev> | --worktree] [--map <file>] [--out <file>] [--summary]
|
|
4
|
+
// validate the mapping, report coverage of the upstream text, and what became of each entry's ranges since
|
|
5
|
+
// the commits they were recorded at. Draws no conclusion. `--out` writes the whole report as JSON;
|
|
6
|
+
// `--summary` prints one line of JSON numbers instead of the text. A map that cannot be read at all is one
|
|
7
|
+
// problem, said in the same form. It also holds the texts the scripts import to the map, counted apart (`textProblems`):
|
|
8
|
+
// the exit is 1 whenever the map or a text has a problem.
|
|
9
|
+
// advance [--upstream <checkout>] [--head <rev>] record the unchanged entries at the current commits
|
|
10
|
+
// accept <id>... [--upstream <checkout>] [--head <rev>] record the named entries at the carried positions
|
|
11
|
+
// assemble [--check] write the texts the scripts import from the mapping; with `--check`, only compare them
|
|
12
|
+
// refresh <checkout> [<commit>] take a new snapshot of an upstream checkout, at a commit of it
|
|
13
|
+
//
|
|
14
|
+
// `--upstream` is needed only when the mapping has ranges at an upstream commit other than the snapshot's.
|
|
15
|
+
|
|
16
|
+
import { writeFileSync } from "node:fs";
|
|
17
|
+
import { resolve } from "node:path";
|
|
18
|
+
|
|
19
|
+
import { Git, WORKTREE, differingTexts, formatReport, openMap, recordMap, summaryOf, unreadable, writeAssembled } from "../src/mapping/index.ts";
|
|
20
|
+
import type { ToolContext } from "../src/mapping/index.ts";
|
|
21
|
+
import { PACKAGE_DIR, PACKAGE_PATHS, refreshUpstream } from "../src/upstream.ts";
|
|
22
|
+
|
|
23
|
+
const [command, ...rest] = process.argv.slice(2);
|
|
24
|
+
|
|
25
|
+
/** The value of a flag, and the arguments that are not flags. */
|
|
26
|
+
function parse(args: readonly string[], valued: readonly string[]): { flags: Map<string, string | true>; words: string[] } {
|
|
27
|
+
const flags = new Map<string, string | true>();
|
|
28
|
+
const words: string[] = [];
|
|
29
|
+
for (let i = 0; i < args.length; i += 1) {
|
|
30
|
+
const arg = args[i] as string;
|
|
31
|
+
if (!arg.startsWith("--")) words.push(arg);
|
|
32
|
+
else if (valued.includes(arg)) flags.set(arg, args[(i += 1)] ?? "");
|
|
33
|
+
else flags.set(arg, true);
|
|
34
|
+
}
|
|
35
|
+
return { flags, words };
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
const usage = (): never => {
|
|
39
|
+
console.error("usage: upstream-map check|advance|accept|assemble|refresh (see the head of this file)");
|
|
40
|
+
process.exit(2);
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
const { flags, words } = parse(rest, ["--upstream", "--head", "--out", "--map"]);
|
|
44
|
+
const text = (flag: string): string | undefined => {
|
|
45
|
+
const value = flags.get(flag);
|
|
46
|
+
return typeof value === "string" ? value : undefined;
|
|
47
|
+
};
|
|
48
|
+
const context = (): ToolContext => ({
|
|
49
|
+
paths: PACKAGE_PATHS,
|
|
50
|
+
root: new Git(PACKAGE_DIR).out(["rev-parse", "--show-toplevel"]).trim(),
|
|
51
|
+
...(text("--upstream") === undefined ? {} : { checkout: text("--upstream") as string }),
|
|
52
|
+
head: flags.has("--worktree") ? WORKTREE : (text("--head") ?? "HEAD"),
|
|
53
|
+
...(text("--map") === undefined ? {} : { map: text("--map") as string }),
|
|
54
|
+
});
|
|
55
|
+
|
|
56
|
+
if (command === "check") {
|
|
57
|
+
const out = text("--out");
|
|
58
|
+
let opened: ReturnType<typeof openMap>;
|
|
59
|
+
try {
|
|
60
|
+
opened = openMap(context());
|
|
61
|
+
} catch (error) {
|
|
62
|
+
// A map that cannot be read at all (bad JSON, a schema error, a commit that is not there) is a problem of the
|
|
63
|
+
// map, said as one: whoever reads the numbers gets a line to act on, not a crash.
|
|
64
|
+
const said = unreadable(error);
|
|
65
|
+
if (out !== undefined) writeFileSync(resolve(out), `${JSON.stringify({ error: said.error }, null, 2)}\n`);
|
|
66
|
+
console.log(flags.has("--summary") ? JSON.stringify(said) : `PROBLEMS 1\n the map could not be read: ${said.error}`);
|
|
67
|
+
process.exit(1);
|
|
68
|
+
}
|
|
69
|
+
const { report } = opened;
|
|
70
|
+
if (out !== undefined) writeFileSync(resolve(out), `${JSON.stringify(report, null, 2)}\n`);
|
|
71
|
+
console.log(flags.has("--summary") ? JSON.stringify(summaryOf(report)) : formatReport(report));
|
|
72
|
+
process.exit(report.problems.length === 0 && report.texts.length === 0 ? 0 : 1);
|
|
73
|
+
} else if (command === "advance" || command === "accept") {
|
|
74
|
+
const changed = recordMap(context(), command === "advance" ? "unchanged" : words);
|
|
75
|
+
console.log(`${command === "advance" ? "advanced" : "accepted"}: ${String(changed)} entries recorded`);
|
|
76
|
+
} else if (command === "assemble") {
|
|
77
|
+
if (flags.has("--check")) {
|
|
78
|
+
const wrong = differingTexts(context());
|
|
79
|
+
if (wrong.length > 0) {
|
|
80
|
+
console.error(`these texts differ from the mapping: ${wrong.join(", ")}`);
|
|
81
|
+
process.exit(1);
|
|
82
|
+
}
|
|
83
|
+
console.log("the texts match the mapping");
|
|
84
|
+
} else console.log(`${String(writeAssembled(context()))} texts written`);
|
|
85
|
+
} else if (command === "refresh") {
|
|
86
|
+
const [checkout, commit] = words;
|
|
87
|
+
if (checkout === undefined) usage();
|
|
88
|
+
const source = refreshUpstream(resolve(checkout as string), commit === undefined ? {} : { commit });
|
|
89
|
+
console.log(`snapshot taken at ${source.commit}`);
|
|
90
|
+
} else usage();
|
package/src/author.ts
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The author's box keeps its project writes in a worktree of niwa. The plugin checks the place and chooses the
|
|
3
|
+
* forge hosts its caller's grant covers.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import { existsSync, realpathSync } from "node:fs";
|
|
7
|
+
import { join, sep } from "node:path";
|
|
8
|
+
|
|
9
|
+
import { CatchableError } from "@niwa-labs/core";
|
|
10
|
+
|
|
11
|
+
import type { Roles } from "./roles.ts";
|
|
12
|
+
|
|
13
|
+
/** Why the author was not started. */
|
|
14
|
+
export type AuthorRefusalCode = "no-box" | "no-place" | "not-a-worktree";
|
|
15
|
+
|
|
16
|
+
/** The author was not started: a refusal the run may catch. */
|
|
17
|
+
export class AuthorRefusal extends CatchableError {
|
|
18
|
+
override name = "AuthorRefusal";
|
|
19
|
+
override readonly code: AuthorRefusalCode;
|
|
20
|
+
|
|
21
|
+
constructor(code: AuthorRefusalCode, message: string) {
|
|
22
|
+
super(message);
|
|
23
|
+
this.code = code;
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** The folder niwa's git module keeps its worktrees in. */
|
|
28
|
+
export const worktreesOf = (home: string): string => join(realpathSync(home), "worktrees");
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* The real path of a place a role works in, checked before anything is read or written there: it exists and is one of
|
|
32
|
+
* niwa's worktrees under `worktrees` (its real path, so a link cannot lead out). `who` names the role in the refusal.
|
|
33
|
+
*/
|
|
34
|
+
export function worktreePlace(who: string, place: string, worktrees: string): string {
|
|
35
|
+
if (place.trim() === "" || !existsSync(place)) throw new AuthorRefusal("no-place", `${who} has no place to work in: ${JSON.stringify(place)} is not there`);
|
|
36
|
+
const real = realpathSync(place);
|
|
37
|
+
const root = existsSync(worktrees) ? realpathSync(worktrees) : worktrees;
|
|
38
|
+
if (!real.startsWith(root + sep) || real.slice(root.length + 1).includes(sep)) {
|
|
39
|
+
throw new AuthorRefusal("not-a-worktree", `${who}'s place ${real} is not one of niwa's worktrees under ${root}`);
|
|
40
|
+
}
|
|
41
|
+
return real;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* The launch of the author's session: its project is the worktree and its box also reaches the given forges.
|
|
46
|
+
* Refused when the role carries no box or the place is outside `worktrees`.
|
|
47
|
+
*/
|
|
48
|
+
export function authorLaunch(
|
|
49
|
+
author: Roles["author"],
|
|
50
|
+
place: string,
|
|
51
|
+
worktrees: string,
|
|
52
|
+
forges: readonly string[],
|
|
53
|
+
): { place: string; box: { allow: Array<"project" | { net: string }> } } {
|
|
54
|
+
if ((author as { box?: unknown }).box !== true) throw new AuthorRefusal("no-box", "the author role carries no box, and an author writes only in a box");
|
|
55
|
+
const real = worktreePlace("the author", place, worktrees);
|
|
56
|
+
return { place: real, box: { allow: ["project", ...forges.map((net) => ({ net }))] } };
|
|
57
|
+
}
|
package/src/binding.ts
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Who an attestation is from. The merge policy refuses a verdict by the author of the patch, so the author must have
|
|
3
|
+
* one address for the life of its session: the principal of a session's token changes when the session is launched
|
|
4
|
+
* again under a new one, and an exclusion by principal would let the author's relaunched session count as someone
|
|
5
|
+
* else. The sessions module knows which session a token's mark names, and the agents module which agent a session
|
|
6
|
+
* works for; their bindings give that address, and evidence is given the result.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import { principalBinding } from "@niwa-labs/evidence";
|
|
10
|
+
import type { CallerBinding, Plugin } from "@niwa-labs/plugin";
|
|
11
|
+
|
|
12
|
+
/** A plugin that hands out a binding of its callers, as the sessions and agents modules do. */
|
|
13
|
+
export type Binding = Plugin & { bind(fallback?: CallerBinding): CallerBinding };
|
|
14
|
+
|
|
15
|
+
function bindingPlugin(plugins: readonly Plugin[], name: string): Binding | undefined {
|
|
16
|
+
const found = plugins.find((one) => String(one.name) === name);
|
|
17
|
+
return found !== undefined && typeof (found as Partial<Binding>).bind === "function" ? (found as Binding) : undefined;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* The binding evidence attests with on a host of these plugins: a session the agents module started for an agent
|
|
22
|
+
* attests as the agent, another session as itself (`session` with its harness and its own id), and every other caller
|
|
23
|
+
* as the evidence module would bind it, the owner as the owner and a run as `run:<id>`. A host with no sessions module
|
|
24
|
+
* is refused: its sessions could not be told apart across a relaunch.
|
|
25
|
+
*/
|
|
26
|
+
export function addressingOf(plugins: readonly Plugin[]): CallerBinding {
|
|
27
|
+
const sessions = bindingPlugin(plugins, "sessions");
|
|
28
|
+
if (sessions === undefined) throw new TypeError("pstack: the host has no sessions module to address the authors of verdicts by; install it before pstack");
|
|
29
|
+
const agents = bindingPlugin(plugins, "agents");
|
|
30
|
+
const bySession = sessions.bind(principalBinding);
|
|
31
|
+
return agents === undefined ? bySession : agents.bind(bySession);
|
|
32
|
+
}
|
package/src/catalog.ts
ADDED
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The built-in workflows pstack ships: the entry, one script per upstream playbook, the upstream sync, and the suite
|
|
3
|
+
* that tries a new set of them before the host runs it.
|
|
4
|
+
*
|
|
5
|
+
* Every script but the suite is gated: a new version of it comes in as a candidate, and the host runs it only once
|
|
6
|
+
* the suite has run its scenarios on the candidates and promoted the set. The suite itself is not gated, for it is
|
|
7
|
+
* what promotes.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { fileURLToPath } from "node:url";
|
|
11
|
+
|
|
12
|
+
/** One built-in, as pstack offers it to the workflow module. */
|
|
13
|
+
export interface Builtin {
|
|
14
|
+
/** Its name among pstack's built-ins: the playbook's name for a playbook. */
|
|
15
|
+
readonly name: string;
|
|
16
|
+
/** A few words on one line: what it is registered under. */
|
|
17
|
+
readonly description: string;
|
|
18
|
+
/** The record types its `on` names, other than script records. */
|
|
19
|
+
readonly triggers?: readonly string[];
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/** The folder of the scripts. */
|
|
23
|
+
const WORKFLOWS = new URL("./workflows/", import.meta.url);
|
|
24
|
+
|
|
25
|
+
/** The script of a built-in. */
|
|
26
|
+
export const scriptOf = (name: string): string => fileURLToPath(new URL(`${name}.ts`, WORKFLOWS));
|
|
27
|
+
|
|
28
|
+
/** The name of the entry. */
|
|
29
|
+
export const ENTRY = "entry";
|
|
30
|
+
|
|
31
|
+
/** The name of the suite. */
|
|
32
|
+
export const SUITE = "suite";
|
|
33
|
+
|
|
34
|
+
/** The playbooks, by the name of their upstream file. */
|
|
35
|
+
export const PLAYBOOKS: readonly Builtin[] = [
|
|
36
|
+
{ name: "authoring-a-skill", description: "Write or change a skill and carry it to a pull request" },
|
|
37
|
+
{ name: "autonomous-run", description: "Drive a change until its done predicate holds" },
|
|
38
|
+
{ name: "autopilot-full", description: "Carry a plan with the go to merged pull requests" },
|
|
39
|
+
{ name: "autopilot-stack", description: "Carry a plan to verified, stacked pull requests" },
|
|
40
|
+
{ name: "babysit", description: "Clear one pull request's conflicts, threads and CI" },
|
|
41
|
+
{ name: "bug-fix", description: "Find a bug's cause and carry its fix to a pull request" },
|
|
42
|
+
{ name: "eval", description: "Compare variants blind on a rubric they never see" },
|
|
43
|
+
{ name: "feature", description: "Design a feature and carry it to a verified pull request" },
|
|
44
|
+
{ name: "hillclimb", description: "Improve one metric an attempt at a time" },
|
|
45
|
+
{ name: "investigation", description: "Answer a question about the code with cited sources" },
|
|
46
|
+
{ name: "multi-phase-plan", description: "Write a plan of pull requests and ask the owner's go" },
|
|
47
|
+
{ name: "opening-a-pr", description: "Open a ready pull request for a published branch" },
|
|
48
|
+
{ name: "pause-safely", description: "Stop cleanly with a checkpoint to resume from" },
|
|
49
|
+
{ name: "perf-issue", description: "Measure a slow path, fix it, and measure the fix" },
|
|
50
|
+
{ name: "prototype", description: "Settle a design decision with throwaway variants" },
|
|
51
|
+
{ name: "refactoring", description: "Reshape code behind a pinned contract" },
|
|
52
|
+
{ name: "runtime-forensics", description: "Find the cause of a symptom from the program running" },
|
|
53
|
+
{ name: "session-pickup", description: "Pick up work from the trail niwa keeps of it" },
|
|
54
|
+
{ name: "shipping", description: "Land a verified stack bottom up under the merge policy" },
|
|
55
|
+
{ name: "trace-forensics", description: "Read a trace for the cause of a symptom" },
|
|
56
|
+
{ name: "visual-parity", description: "Match a surface to its reference and verify it live" },
|
|
57
|
+
{ name: "worktree-cleanup", description: "Remove the worktrees a merged pull request was built in", triggers: ["forge.pr.merged"] },
|
|
58
|
+
];
|
|
59
|
+
|
|
60
|
+
/** Benny's two automations, offered when Benny is enabled: triage every report, reproduce and fix a confirmed bug. */
|
|
61
|
+
export const BENNY: readonly Builtin[] = [
|
|
62
|
+
{ name: "benny-triage", description: "Triage an issue report handed to Benny", triggers: ["benny.reported"] },
|
|
63
|
+
{ name: "benny-reproduce", description: "Reproduce a confirmed bug and fix it in a draft request" },
|
|
64
|
+
];
|
|
65
|
+
|
|
66
|
+
/** The name of the upstream sync. */
|
|
67
|
+
export const SYNC = "upstream-sync";
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* The upstream sync: the owner starts it on a checkout of upstream, and it leaves commits on a branch. It is gated like
|
|
71
|
+
* the playbooks: the tool it runs and the author it prompts decide what a prompt becomes, so a new version of it comes
|
|
72
|
+
* in as a candidate and the suite tries it before the host runs it.
|
|
73
|
+
*/
|
|
74
|
+
export const SYNC_BUILTIN: Builtin = { name: SYNC, description: "Carry the upstream map to a new snapshot of upstream" };
|
|
75
|
+
|
|
76
|
+
/** The built-ins that come in as candidates: the entry, the playbooks and the upstream sync. */
|
|
77
|
+
export const GATED: readonly Builtin[] = [{ name: ENTRY, description: "Pick the playbook a request needs and run it" }, ...PLAYBOOKS, SYNC_BUILTIN];
|
|
78
|
+
|
|
79
|
+
/** The suite: it is what promotes, so it is not gated. */
|
|
80
|
+
export const SUITE_BUILTIN: Builtin = { name: SUITE, description: "Run the scenarios on candidate playbooks and promote them" };
|
|
81
|
+
|
|
82
|
+
/** The built-ins that are not gated. */
|
|
83
|
+
export const UNGATED: readonly Builtin[] = [SUITE_BUILTIN];
|
|
84
|
+
|
|
85
|
+
/** The gated built-ins a pstack plugin offers: Benny's too when he is enabled. */
|
|
86
|
+
export const gatedOf = (benny: boolean): readonly Builtin[] => (benny ? [...GATED, ...BENNY] : GATED);
|