@chernabog/sdk 0.7.0 → 0.8.1
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 +16 -12
- package/index.ts +5 -0
- package/package.json +8 -3
- package/src/ci.ts +82 -0
- package/src/comment.ts +1 -3
- package/src/default-prompts.ts +24 -1
- package/src/epic.ts +568 -0
- package/src/hybrid.ts +67 -53
- package/src/implement.ts +731 -149
- package/src/index.ts +15 -13
- package/src/plan-labels.ts +9 -0
- package/src/plan.ts +48 -39
- package/src/prompt.ts +1 -3
- package/src/pull-request.ts +234 -39
- package/src/review.ts +236 -56
- package/src/routing.ts +113 -0
- package/src/settings.ts +361 -0
- package/src/stack.ts +534 -0
- package/src/still-valid.ts +142 -0
- package/src/claims.ts +0 -169
- package/src/errors.ts +0 -222
- package/src/flow.ts +0 -325
- package/src/json.ts +0 -21
- package/src/markers.ts +0 -103
- package/src/paths.ts +0 -46
- package/src/roles.ts +0 -30
- package/src/services.ts +0 -505
- package/src/stage.ts +0 -25
package/README.md
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# @chernabog/sdk
|
|
2
2
|
|
|
3
|
-
The
|
|
3
|
+
The blocks Chernabog flows and steps are written from (`Implement`, `Review`, `Plan`, `Hybrid`, `Stack`, `PullRequest`, prompts), over [`@chernabog/core`](https://www.npmjs.com/package/@chernabog/core), which it re-exports, so a flow imports everything from this one package.
|
|
4
|
+
|
|
5
|
+
A repo lists it in `.chernabog/package.json`'s `dependencies`, at the version it chooses, and each snapshot of the repo's base branch installs it: two repos on different versions run side by side in one daemon. The `chernabog` binary supplies its own copies of `@chernabog/core` and `effect` at runtime, and runs this package when its peer range on `@chernabog/core` includes a core the binary provides. `chernabog recipes upgrade` moves a repo to the version released with its binary.
|
|
4
6
|
|
|
5
7
|
## Flows
|
|
6
8
|
|
|
@@ -30,16 +32,16 @@ export default defineFlow({
|
|
|
30
32
|
});
|
|
31
33
|
```
|
|
32
34
|
|
|
33
|
-
| Helper | What it does
|
|
34
|
-
| --------------------------------------- |
|
|
35
|
-
| `activity(name, effect, { success })` | One durable step. It runs once and its result is saved; a replay returns the saved result. Names are unique within a run, so a step in a loop carries its round: `fix-ci-2`.
|
|
36
|
-
| `step(name, input, { output })` | Runs `.chernabog/stages/<name>` in its own process, as an activity.
|
|
37
|
-
| `sleep(name, duration)` | A durable pause that survives restarts.
|
|
38
|
-
| `awaitSignal(signals, { id, timeout })` | Waits for one of the signals (which the trigger reports in `WorkItem.signals`) or the timeout, whichever comes first, and says which. A trigger can report an item with `wakeOnly` to wake a waiting run without starting a new one
|
|
39
|
-
| `renderPrompt(name, values)` | Fills `.chernabog/prompts/<name>.md`, or, for a flow imported from a recipe package (`FlowPackage`), the package's when the repo has none.
|
|
40
|
-
| `Skip`, `NeedsHuman` | End a run cleanly, or hand its item to a person.
|
|
35
|
+
| Helper | What it does |
|
|
36
|
+
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
37
|
+
| `activity(name, effect, { success })` | One durable step. It runs once and its result is saved; a replay returns the saved result. Names are unique within a run, so a step in a loop carries its round: `fix-ci-2`. |
|
|
38
|
+
| `step(name, input, { output })` | Runs `.chernabog/stages/<name>` in its own process, as an activity. |
|
|
39
|
+
| `sleep(name, duration)` | A durable pause that survives restarts. |
|
|
40
|
+
| `awaitSignal(signals, { id, timeout })` | Waits for one of the signals (which the trigger reports in `WorkItem.signals`) or the timeout, whichever comes first, and says which. A trigger can report an item with `wakeOnly` to wake a waiting run without starting a new one, or with `held: "<why>"` to start no run and show why in `chernabog status`. |
|
|
41
|
+
| `renderPrompt(name, values)` | Fills `.chernabog/prompts/<name>.md`, or, for a flow imported from a recipe package (`FlowPackage`), the package's when the repo has none. |
|
|
42
|
+
| `Skip`, `NeedsHuman` | End a run cleanly, or hand its item to a person. |
|
|
41
43
|
|
|
42
|
-
`Implement`, `Review` and `PullRequest` hold the building blocks of the review loop, each an activity a flow can reorder, leave out or wrap. `Hybrid` holds the blocks of the hybrid path, where a person works on an issue with the agent in an interactive session. `Plan` holds the blocks of the plan recipe, which turns a spec issue into an epic of sub-issues once a person approves the agent's plan. Chernabog's [recipes](https://dataquail.github.io/chernabog/recipes/) are complete flows written out from these blocks, which a repo bakes into its own `.chernabog/flows/`; they are published as [`@chernabog/recipes`](https://www.npmjs.com/package/@chernabog/recipes), whose source is [`packages/recipes/`](https://github.com/dataquail/chernabog/tree/main/packages/recipes).
|
|
44
|
+
`Implement`, `Review` and `PullRequest` hold the building blocks of the review loop, each an activity a flow can reorder, leave out or wrap. `Hybrid` holds the blocks of the hybrid path, where a person works on an issue with the agent in an interactive session. `Plan` holds the blocks of the plan recipe, which turns a spec issue into an epic of sub-issues once a person approves the agent's plan. `Stack` brings a layer of a stack of pull requests up to date with its base by merging, including once the layer below was squash-merged, and adjusts the layer to what moved in the session that wrote it. Chernabog's [recipes](https://dataquail.github.io/chernabog/recipes/) are complete flows written out from these blocks, which a repo bakes into its own `.chernabog/flows/`; they are published as [`@chernabog/recipes`](https://www.npmjs.com/package/@chernabog/recipes), whose source is [`packages/recipes/`](https://github.com/dataquail/chernabog/tree/main/packages/recipes).
|
|
43
45
|
|
|
44
46
|
A flow can also give `item: (key) => Effect<Option<WorkItem>>`, the work item for a key a person names that the trigger doesn't report, as `Hybrid.itemFor` finds the issue `chernabog start` names.
|
|
45
47
|
|
|
@@ -58,15 +60,17 @@ export default defineStage({
|
|
|
58
60
|
output: Schema.Struct({ issue: Schema.Number }),
|
|
59
61
|
run: () =>
|
|
60
62
|
Effect.gen(function* () {
|
|
61
|
-
const issue = yield* (yield* GitHub).
|
|
63
|
+
const [issue] = yield* (yield* GitHub).queuedIssuesLabelled("auto:eligible");
|
|
62
64
|
if (issue === undefined) return yield* new Skip({ reason: "nothing queued" });
|
|
63
|
-
return { issue };
|
|
65
|
+
return { issue: issue.number };
|
|
64
66
|
}),
|
|
65
67
|
});
|
|
66
68
|
```
|
|
67
69
|
|
|
68
70
|
## Services
|
|
69
71
|
|
|
72
|
+
The services are core's: each is a port the binary provides.
|
|
73
|
+
|
|
70
74
|
| Service | Covers |
|
|
71
75
|
| ----------------- | ---------------------------------------------------------------------------------------------------- |
|
|
72
76
|
| `Repo` | The repo's merged settings: slug, base branch, labels, limits, gates, notes |
|
package/index.ts
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
// The package's entry where a resolver ignores package.json: Bun's compiled
|
|
2
|
+
// binaries resolve a bare import to a package's root index file only, and the
|
|
3
|
+
// chernabog binary imports each repo's installed SDK that way. Everything
|
|
4
|
+
// else reads `exports`, which names the same module.
|
|
5
|
+
export * from "./src/index.ts";
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@chernabog/sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.1",
|
|
4
4
|
"license": "MIT",
|
|
5
|
-
"description": "
|
|
5
|
+
"description": "The blocks Chernabog flows are written from (Implement, Review, Plan, Hybrid, PullRequest, prompts), over @chernabog/core, which it re-exports",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
8
8
|
"url": "git+https://github.com/dataquail/chernabog.git",
|
|
@@ -13,11 +13,16 @@
|
|
|
13
13
|
".": "./src/index.ts"
|
|
14
14
|
},
|
|
15
15
|
"files": [
|
|
16
|
-
"src"
|
|
16
|
+
"src",
|
|
17
|
+
"index.ts"
|
|
17
18
|
],
|
|
18
19
|
"peerDependencies": {
|
|
20
|
+
"@chernabog/core": "^1.0.0",
|
|
19
21
|
"effect": "4.0.5"
|
|
20
22
|
},
|
|
23
|
+
"devDependencies": {
|
|
24
|
+
"@chernabog/core": "workspace:*"
|
|
25
|
+
},
|
|
21
26
|
"publishConfig": {
|
|
22
27
|
"access": "public"
|
|
23
28
|
}
|
package/src/ci.ts
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
// The CI gate: green, red or pending from the checks GitHub reports on a pull
|
|
2
|
+
// request's head (core's GitHub.ciChecks), by the flow's policy. GitHub only
|
|
3
|
+
// reports; which checks gate a merge is decided here, and a recipe sets it
|
|
4
|
+
// with `ciGates` and `ciOptionalFailures` (Settings.Ci).
|
|
5
|
+
|
|
6
|
+
import { type CiChecks, type CiState, GitHub } from "@chernabog/core";
|
|
7
|
+
import * as Arr from "effect/Array";
|
|
8
|
+
import * as Effect from "effect/Effect";
|
|
9
|
+
import * as Option from "effect/Option";
|
|
10
|
+
import * as Order from "effect/Order";
|
|
11
|
+
|
|
12
|
+
import * as Settings from "./settings.ts";
|
|
13
|
+
|
|
14
|
+
export type Policy = {
|
|
15
|
+
// The checks that must pass: the base branch's required ones (every check
|
|
16
|
+
// when it requires none, or GitHub won't say), or every check, required
|
|
17
|
+
// ones that haven't reported included.
|
|
18
|
+
readonly gates: "required" | "every";
|
|
19
|
+
// Whether a failing check that doesn't gate still makes CI red, so a fix
|
|
20
|
+
// can start before the slow checks finish, or is left alone.
|
|
21
|
+
readonly optionalFailures: "hold" | "ignore";
|
|
22
|
+
};
|
|
23
|
+
|
|
24
|
+
export const DEFAULT_POLICY: Policy = { gates: "required", optionalFailures: "hold" };
|
|
25
|
+
|
|
26
|
+
const sorted = (names: ReadonlyArray<string>) => Arr.sort(Arr.dedupe(names), Order.String);
|
|
27
|
+
|
|
28
|
+
// The checks' verdict: red when a check that counts failed, pending while a
|
|
29
|
+
// gating check hasn't passed (or none has reported at all), green otherwise.
|
|
30
|
+
export const verdict = (facts: CiChecks, policy: Policy): CiState => {
|
|
31
|
+
const reported = facts.checks.map((check) => check.name);
|
|
32
|
+
let gating = facts.required;
|
|
33
|
+
|
|
34
|
+
// Every check is at least the required ones, reported yet or not.
|
|
35
|
+
if (policy.gates === "every") {
|
|
36
|
+
gating = Arr.dedupe([...facts.required, ...reported]);
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
if (gating.length === 0) {
|
|
40
|
+
gating = reported;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
const counts = (name: string) => policy.optionalFailures === "hold" || gating.includes(name);
|
|
44
|
+
|
|
45
|
+
const failedChecks = sorted(
|
|
46
|
+
facts.checks.flatMap((check) => {
|
|
47
|
+
if (check.state === "failed" && counts(check.name)) {
|
|
48
|
+
return [check.name];
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
return [];
|
|
52
|
+
}),
|
|
53
|
+
);
|
|
54
|
+
|
|
55
|
+
const waitingOn = sorted(
|
|
56
|
+
gating.filter(
|
|
57
|
+
(name) => !facts.checks.some((check) => check.name === name && check.state !== "pending"),
|
|
58
|
+
),
|
|
59
|
+
);
|
|
60
|
+
|
|
61
|
+
let reading: CiState = { state: "green" };
|
|
62
|
+
|
|
63
|
+
if (failedChecks.length > 0) {
|
|
64
|
+
reading = { state: "red", failedChecks };
|
|
65
|
+
} else if (waitingOn.length > 0 || gating.length === 0) {
|
|
66
|
+
reading = { state: "pending", waitingOn };
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
return Option.match(facts.caveat, {
|
|
70
|
+
onNone: () => reading,
|
|
71
|
+
onSome: (caveat): CiState => ({ ...reading, caveat }),
|
|
72
|
+
});
|
|
73
|
+
};
|
|
74
|
+
|
|
75
|
+
// The pull request's CI, read now and decided by the flow's policy.
|
|
76
|
+
export const pullRequestState = (pullRequest: number) =>
|
|
77
|
+
Effect.gen(function* () {
|
|
78
|
+
const policy = yield* Settings.ciGate;
|
|
79
|
+
const facts = yield* GitHub.use((github) => github.ciChecks(pullRequest));
|
|
80
|
+
|
|
81
|
+
return verdict(facts, policy);
|
|
82
|
+
});
|
package/src/comment.ts
CHANGED
|
@@ -4,11 +4,9 @@
|
|
|
4
4
|
|
|
5
5
|
import { createHash } from "node:crypto";
|
|
6
6
|
|
|
7
|
+
import { activity, GitHub } from "@chernabog/core";
|
|
7
8
|
import * as Effect from "effect/Effect";
|
|
8
9
|
|
|
9
|
-
import { activity } from "./flow.ts";
|
|
10
|
-
import { GitHub } from "./services.ts";
|
|
11
|
-
|
|
12
10
|
export const commentStep = (kind: "issue" | "pr", number: number, body: string) =>
|
|
13
11
|
activity(
|
|
14
12
|
`comment-${kind}-${number}-${createHash("sha256").update(body).digest("hex").slice(0, 12)}`,
|
package/src/default-prompts.ts
CHANGED
|
@@ -44,7 +44,7 @@ You decided to address this review. You are back in the same worktree, on the sa
|
|
|
44
44
|
{{review}}
|
|
45
45
|
|
|
46
46
|
- Make each change the review asks for. Where you disagree, leave the code as it is and say why in \`summary\`; the reviewer reads it.
|
|
47
|
-
- Keep each commit to one change. Commit messages follow the repo's convention.
|
|
47
|
+
- Keep each commit to one change. Commit messages follow the repo's convention. Leave nothing uncommitted: Chernabog stops for a person if the worktree has changes left.
|
|
48
48
|
- The ground rules of your first task still hold: never push, never weaken a check to get green, and stop with \`needs-clarification\` only for the hard limits.
|
|
49
49
|
- \`summary\`: what you changed for each point, and which points you left and why.
|
|
50
50
|
`;
|
|
@@ -100,3 +100,26 @@ It checks the worktree is clean, keeps the draft, and prints an \`AskUserQuestio
|
|
|
100
100
|
|
|
101
101
|
A person merges it. If a review asks for changes, this session opens again, for the two of you to answer it.
|
|
102
102
|
`;
|
|
103
|
+
|
|
104
|
+
// Stack.refreshLayer, back in the author's session after the layer's base moved.
|
|
105
|
+
export const REFRESH = `# The base of pull request #{{pullRequest}} moved
|
|
106
|
+
|
|
107
|
+
\`{{base}}\`, the branch this pull request is built on, moved from \`{{oldBase}}\` to \`{{newBase}}\`, and Chernabog merged it into \`{{branch}}\`. You are back in the session that wrote this pull request, in the same worktree, unattended. Bring the pull request's own code up to date with what the base now has, commit, and give your final answer in the same format as before. Chernabog runs the local gate, pushes the branch and waits for CI.
|
|
108
|
+
|
|
109
|
+
{{merge}}
|
|
110
|
+
|
|
111
|
+
The base's change to the files this pull request changes too:
|
|
112
|
+
|
|
113
|
+
\`\`\`diff
|
|
114
|
+
{{diff}}
|
|
115
|
+
\`\`\`
|
|
116
|
+
|
|
117
|
+
The base's whole change is \`git diff {{oldBase}} {{newBase}}\`.
|
|
118
|
+
|
|
119
|
+
- Resolve each conflicted file so it keeps both sides' intent: this pull request's change, applied on top of what the base now has. Make sure no conflict markers are left, then commit the merge with \`git commit --no-edit\`.
|
|
120
|
+
- Adjust this pull request's own code to the base's change where it builds on what changed: a renamed or reshaped API, moved code, a behaviour it relies on. Where behaviour changes, write or update the test first, then the code.
|
|
121
|
+
- Change nothing the base's move doesn't require. When nothing needs adjusting, commit nothing and say so. Either way, leave nothing uncommitted: Chernabog stops for a person if the worktree has changes left.
|
|
122
|
+
- Keep each commit to one change. Commit messages follow the repo's convention.
|
|
123
|
+
- The ground rules of your first task still hold: never rebase, reset, amend, push or switch branches, never weaken a check to get green, and stop with \`needs-clarification\` only for the hard limits.
|
|
124
|
+
- \`summary\`: what you resolved and adjusted, and why, for the reviewer.
|
|
125
|
+
`;
|