@moo.md/hum 0.2.0 → 0.4.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/defaults/hum.json +14 -2
- package/defaults/roles/build.md +1 -1
- package/defaults/roles/fix.md +1 -1
- package/npm-shrinkwrap.json +3297 -0
- package/package.json +6 -2
- package/release.json +3 -0
- package/schema/hum.schema.json +251 -10
- package/scripts/eval.ts +21 -5
- package/src/adapter-api.ts +3 -1
- package/src/adapters/claude-bg.ts +2 -2
- package/src/adapters/claude-p.ts +44 -18
- package/src/adapters/contract.ts +12 -0
- package/src/adapters/fake.ts +5 -0
- package/src/adapters/git.ts +61 -9
- package/src/adapters/github-client.ts +15 -0
- package/src/adapters/github-commits.ts +84 -0
- package/src/adapters/github.ts +36 -4
- package/src/adapters/guard.ts +1 -0
- package/src/adapters/item-file.ts +1 -1
- package/src/adapters/markdown.ts +10 -1
- package/src/adapters/pull-requests.ts +8 -8
- package/src/adapters/registry.ts +5 -7
- package/src/adapters/roundup.ts +3 -0
- package/src/bytes.ts +1 -0
- package/src/cli/service.ts +176 -29
- package/src/cli/setup.ts +16 -7
- package/src/config/checks.ts +27 -43
- package/src/config/load.ts +2 -3
- package/src/config/machine.ts +29 -0
- package/src/config/migrate.ts +5 -2
- package/src/config/refusal.ts +9 -4
- package/src/config/schema.ts +86 -8
- package/src/config/wake-job.ts +78 -0
- package/src/decide/risk.ts +2 -2
- package/src/exec.ts +10 -0
- package/src/index.ts +1 -1
- package/src/loop/records.ts +8 -1
- package/src/measure/rate.ts +14 -0
- package/src/publish/bundle.ts +128 -0
- package/src/publish/handoff.ts +107 -0
- package/src/publish/handover.ts +182 -0
- package/src/publish/intents.ts +61 -0
- package/src/publish/publisher.ts +259 -0
- package/src/publish/wake.ts +78 -0
- package/src/service/ci-state.ts +99 -0
- package/src/service/plugins.ts +137 -0
- package/src/service/wake.ts +3 -1
- package/src/service/workflows.ts +261 -50
- package/src/setup/propose.ts +87 -3
- package/src/setup/prove.ts +3 -3
- package/src/setup/scan.ts +61 -5
- package/src/setup/tables.ts +18 -0
- package/src/setup/write.ts +52 -19
- package/src/state/items.ts +17 -8
- package/src/state/open.ts +20 -6
- package/src/state/records.ts +7 -0
- package/src/state/runs.ts +5 -0
- package/src/state/saved.ts +17 -2
- package/src/worker/base-check.ts +41 -13
- package/src/worker/checks.ts +3 -2
- package/src/worker/evidence.ts +72 -0
- package/src/worker/kind.ts +4 -7
- package/src/worker/land.ts +173 -81
- package/src/worker/merged.ts +20 -8
- package/src/worker/open.ts +33 -17
- package/src/worker/questions.ts +16 -8
- package/src/worker/signed-push.ts +167 -0
- package/src/worker/thin-path.ts +245 -133
- package/src/worker/worker.ts +50 -9
- package/surface.json +610 -76
package/src/config/schema.ts
CHANGED
|
@@ -4,10 +4,10 @@ import { z } from "zod";
|
|
|
4
4
|
import shippedConfig from "../../defaults/hum.json" with { type: "json" };
|
|
5
5
|
|
|
6
6
|
/** The `hum.json` schema version this engine writes. */
|
|
7
|
-
export const SCHEMA_VERSION =
|
|
7
|
+
export const SCHEMA_VERSION = 2;
|
|
8
8
|
|
|
9
9
|
/** The schema versions this engine reads, each migrated up to `SCHEMA_VERSION` by `migrateConfig`. */
|
|
10
|
-
export const READABLE_SCHEMA_VERSIONS: readonly number[] = [1];
|
|
10
|
+
export const READABLE_SCHEMA_VERSIONS: readonly number[] = [1, 2];
|
|
11
11
|
|
|
12
12
|
/** Parts the engine ships; the owner adds roles, never these. */
|
|
13
13
|
export const FIXED_PARTS = [
|
|
@@ -23,6 +23,12 @@ export const FIXED_PARTS = [
|
|
|
23
23
|
] as const;
|
|
24
24
|
|
|
25
25
|
export const PURPOSES = ["plan", "build", "fix", "review"] as const;
|
|
26
|
+
|
|
27
|
+
/** The integration slots `hum.json` `integrations` names, each to an adapter. */
|
|
28
|
+
export const SLOTS = ["work-source", "questions", "answers", "release"] as const;
|
|
29
|
+
|
|
30
|
+
export type Slot = (typeof SLOTS)[number];
|
|
31
|
+
|
|
26
32
|
export const SIZES = ["small", "medium", "large"] as const;
|
|
27
33
|
const TIERS = ["light", "standard", "top"] as const;
|
|
28
34
|
export const EFFORTS = ["low", "medium", "high"] as const;
|
|
@@ -57,6 +63,10 @@ export const MERGE_METHODS = ["merge", "squash", "rebase"] as const;
|
|
|
57
63
|
|
|
58
64
|
export type MergeMethod = (typeof MERGE_METHODS)[number];
|
|
59
65
|
|
|
66
|
+
const CLAUDE_AUTHS = ["oauth-token", "env"] as const;
|
|
67
|
+
|
|
68
|
+
const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
|
|
69
|
+
|
|
60
70
|
/** Who reviews a change before it merges: no one, a fresh agent review run, or that run and then the owner. */
|
|
61
71
|
export const REVIEWS = ["none", "agent", "owner"] as const;
|
|
62
72
|
|
|
@@ -117,6 +127,40 @@ const backoff = z
|
|
|
117
127
|
|
|
118
128
|
const fraction = z.number().gt(0).lt(1);
|
|
119
129
|
|
|
130
|
+
/** A name GitHub stores a secret under: a workflow reads it as `secrets.<name>`, and GitHub keeps the `GITHUB_` prefix for its own. */
|
|
131
|
+
const secretName = z
|
|
132
|
+
.string()
|
|
133
|
+
.regex(ENV_NAME, "a secret's name is letters, digits and underscores, and starts with no digit")
|
|
134
|
+
.refine((secret) => !/^GITHUB_/i.test(secret), "a secret's name may not start with GITHUB_, which GitHub keeps for its own");
|
|
135
|
+
|
|
136
|
+
const runnerLabels = z.union([name, z.array(name).min(1)]);
|
|
137
|
+
|
|
138
|
+
/** What a job's `runs-on` holds: one label, every label the runner must carry, or a runner group with the labels wanted in it. */
|
|
139
|
+
const Runner = z.union([runnerLabels, z.strictObject({ group: name, labels: runnerLabels.optional() })]);
|
|
140
|
+
|
|
141
|
+
const envName = z.string().regex(ENV_NAME, "an env name is letters, digits and underscores, and starts with no digit");
|
|
142
|
+
|
|
143
|
+
/** A job's container: its image alone, or the image with what a workflow's `container` holds beside it, each as written there. */
|
|
144
|
+
const Container = z.union([
|
|
145
|
+
name,
|
|
146
|
+
z.strictObject({
|
|
147
|
+
image: name,
|
|
148
|
+
credentials: z.strictObject({ username: name, password: name }).optional(),
|
|
149
|
+
env: z.record(envName, z.string()).optional(),
|
|
150
|
+
ports: z.array(z.union([name, z.int().positive()])).optional(),
|
|
151
|
+
volumes: z.array(name).optional(),
|
|
152
|
+
options: name.optional(),
|
|
153
|
+
}),
|
|
154
|
+
]);
|
|
155
|
+
|
|
156
|
+
/** Where a CI run's GitHub token comes from: a secret that holds one, or a GitHub App that mints one per run from its client ID and private key. */
|
|
157
|
+
const PullRequestToken = z.discriminatedUnion("from", [
|
|
158
|
+
z.strictObject({ from: z.literal("secret"), secret: secretName }),
|
|
159
|
+
z.strictObject({ from: z.literal("app"), clientIdSecret: secretName, privateKeySecret: secretName }),
|
|
160
|
+
]);
|
|
161
|
+
|
|
162
|
+
export type PullRequestToken = z.infer<typeof PullRequestToken>;
|
|
163
|
+
|
|
120
164
|
const Launch = z.union([
|
|
121
165
|
z.strictObject({ glob: name, level: name, from: date, until: date }).refine(({ from, until }) => from < until, "a launch ends after it starts"),
|
|
122
166
|
z.strictObject({ glob: name, level: name, base: name }),
|
|
@@ -163,8 +207,29 @@ const Shipped = z.object({
|
|
|
163
207
|
itemReadsAtOnce: count.describe("Item files the markdown source reads at once; each read is a git process."),
|
|
164
208
|
restartBackoff: backoff.describe("The pause before the service's first restart of a crashed worker, doubled each crash up to the longest pause."),
|
|
165
209
|
restartDelaySeconds: seconds.describe("Seconds the service manager waits before it starts a failed start script again."),
|
|
166
|
-
|
|
167
|
-
|
|
210
|
+
pullRequestToken: PullRequestToken.describe(
|
|
211
|
+
"Where a CI run's GitHub token comes from: { from: 'secret', secret } names a repository secret that holds a fine-grained token; { from: 'app', clientIdSecret, privateKeySecret } names the two secrets a GitHub App mints a token from each run, with the workflow's own permissions. clientIdSecret holds the App's client ID or its older App ID: the action that mints the token reads either as the same input. A pull request opened with the workflow token starts no workflows, so its required checks never run; one opened with this token does. A CI run falls back to the workflow token while the secret is unset; a wake whose App secrets are unset stops with an error.",
|
|
212
|
+
),
|
|
213
|
+
ciWakeTimeoutMinutes: count.describe("Minutes the CI wake's work job, which runs the runs, may run before GitHub stops it; the two jobs that hold GitHub's token stop within its hour."),
|
|
214
|
+
ciOutboxMaxMegabytes: count.describe("Megabytes of a CI work job's outbox, its bundles and its state, past which publish refuses the whole wake before any write."),
|
|
215
|
+
ciUsageLimitMaxHours: count.describe("Hours from now past which publish cuts the reset time of a usage limit a CI work job reports, so no work job can hold hum's runs longer than Claude's own limit window."),
|
|
216
|
+
followUpsPerPass: count.describe("Follow-up items one pass may file; publish refuses a pass that files more, and each one it files counts against the daily question cap."),
|
|
217
|
+
publishTreeMaxMegabytes: count.describe("Megabytes of the tree a pass's branch holds, past which publish refuses the pass before it checks the branch out."),
|
|
218
|
+
ciMergeMarginMinutes: count.describe("Minutes of the GitHub App token's hour publish keeps in hand: past the rest, it saves a landing and leaves its merge to the next wake."),
|
|
219
|
+
ciRunner: Runner.describe(
|
|
220
|
+
"What each job of the CI wake runs on, as a workflow's runs-on holds it: one runner label, a list of labels the runner must carry all of, or { group, labels } for a runner group. On a public repo, a runner GitHub does not host keeps what a job leaves on it, and setup asks before it writes one.",
|
|
221
|
+
),
|
|
222
|
+
ciContainer: Container.nullable().describe(
|
|
223
|
+
"The container each job of the CI wake runs in: its image, or { image, credentials: { username, password }, env, ports, volumes, options } as a workflow's container holds them, or null to run on the runner itself. The image needs git, node and npm; a container that runs as root needs IS_SANDBOX=1 in ciEnv, or Claude Code refuses to skip its permission prompts.",
|
|
224
|
+
),
|
|
225
|
+
ciEnv: z
|
|
226
|
+
.record(envName, z.string())
|
|
227
|
+
.describe(
|
|
228
|
+
"Env the CI wake's jobs set, such as a gateway's settings; a value may be a workflow expression. A value that reads a secret reaches only the steps that run hum; every other value reaches every step, the installs too. A name the jobs set themselves, such as GH_TOKEN, is refused.",
|
|
229
|
+
),
|
|
230
|
+
ciClaudeAuth: z
|
|
231
|
+
.enum(CLAUDE_AUTHS)
|
|
232
|
+
.describe("How a CI run's Claude Code signs in: 'oauth-token' requires the CLAUDE_CODE_OAUTH_TOKEN secret, from `claude setup-token`; 'env' asks for no secret, and ciEnv carries the credentials, such as a gateway's settings."),
|
|
168
233
|
strictPaths: z.array(name).describe("Globs of data and secrets: a change touching one takes the strictest level."),
|
|
169
234
|
launches: z
|
|
170
235
|
.array(Launch)
|
|
@@ -221,7 +286,11 @@ const Shipped = z.object({
|
|
|
221
286
|
.describe(
|
|
222
287
|
"Prewarmed run slots on the Mac: worktrees of the owner's checkout that background runs work in, as many as 'runners'. 'pool' is the folder that holds them, relative to the checkout or absolute, and never inside .git, where Claude Code writes nothing; 'services' gives each slot its own services or one shared set with a database per slot; 'ports' starts each slot's block of ports; 'recipe' is the owner's own setup commands.",
|
|
223
288
|
),
|
|
224
|
-
ownerLogins: z
|
|
289
|
+
ownerLogins: z
|
|
290
|
+
.array(name)
|
|
291
|
+
.describe(
|
|
292
|
+
"GitHub logins whose pull request reviews and comments are the owner's review notes, and whose issue comments hum reads as replies. hum also reads the issue comments of the repo's owner, the owning organisation's members and invited collaborators, and reads no one else's.",
|
|
293
|
+
),
|
|
225
294
|
repeatAt: count.describe("Review notes stating one rule at which hum files a check item for it."),
|
|
226
295
|
repeatPrecision: fraction.describe("The lowest precision on labelled pairs at which a model's call that two notes state one rule files a check item; below it the pair waits as a possible repeat."),
|
|
227
296
|
tasteRules: z.array(name).describe("The owner's taste rules that have no deterministic check. Each pull request hum opens gets a comment saying whether its diff keeps each rule; the comment reports only and gates nothing."),
|
|
@@ -294,11 +363,11 @@ export const HumConfig = z.strictObject({
|
|
|
294
363
|
safety: z.record(z.string(), z.unknown()).optional(),
|
|
295
364
|
dailyQuestionCap: z.number().int().positive().optional(),
|
|
296
365
|
/** Adapter slot → adapter name. */
|
|
297
|
-
integrations: z.
|
|
366
|
+
integrations: z.partialRecord(z.enum(SLOTS), name).optional(),
|
|
298
367
|
/** The day `claude setup-token` made the CI token. Setup records it; the engine warns 30 days before the year ends. */
|
|
299
368
|
ciToken: z.strictObject({ setUp: z.iso.date() }).optional(),
|
|
300
369
|
/** No default: a commit is credited to whichever account lists its email, so only the owner's own is safe. */
|
|
301
|
-
commitIdentity: commitIdentity.describe("The owner's own name and email: the author and committer of every commit hum makes. Setup writes them from git config; hum ships none."),
|
|
370
|
+
commitIdentity: commitIdentity.describe("The owner's own name and email: the author and committer of every commit hum makes with git. Where the base requires signed commits, GitHub makes the commits and credits them to the account of the token hum writes with: the owner's own on a Mac; in CI, the GitHub App's bot or the account whose token pullRequestToken names. Setup writes them from git config; hum ships none."),
|
|
302
371
|
...withShippedDefaults(Shipped.shape),
|
|
303
372
|
});
|
|
304
373
|
|
|
@@ -417,7 +486,16 @@ export const OWNER_CHANGEABLE = {
|
|
|
417
486
|
"restart backoff": "restartBackoff",
|
|
418
487
|
"restart delay": "restartDelaySeconds",
|
|
419
488
|
"CI wake timeout": "ciWakeTimeoutMinutes",
|
|
420
|
-
"
|
|
489
|
+
"CI outbox cap": "ciOutboxMaxMegabytes",
|
|
490
|
+
"CI usage limit cap": "ciUsageLimitMaxHours",
|
|
491
|
+
"follow-ups per pass": "followUpsPerPass",
|
|
492
|
+
"publish tree cap": "publishTreeMaxMegabytes",
|
|
493
|
+
"CI merge margin": "ciMergeMarginMinutes",
|
|
494
|
+
"pull request token": "pullRequestToken",
|
|
495
|
+
"CI runner": "ciRunner",
|
|
496
|
+
"CI container": "ciContainer",
|
|
497
|
+
"CI env": "ciEnv",
|
|
498
|
+
"CI Claude auth": "ciClaudeAuth",
|
|
421
499
|
"data and secrets paths": "strictPaths",
|
|
422
500
|
"path rules": "paths",
|
|
423
501
|
launches: "launches",
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
import type { HumConfig } from "./schema.ts";
|
|
2
|
+
|
|
3
|
+
/** The secret Claude Code's OAuth token is stored in, under the env name Claude Code reads it from. */
|
|
4
|
+
export const CLAUDE_TOKEN = "CLAUDE_CODE_OAUTH_TOKEN";
|
|
5
|
+
|
|
6
|
+
/** The env the wake's jobs set themselves. */
|
|
7
|
+
export const WAKE_ENV = {
|
|
8
|
+
claudeToken: CLAUDE_TOKEN,
|
|
9
|
+
githubToken: "GH_TOKEN",
|
|
10
|
+
event: "HUM_EVENT",
|
|
11
|
+
/** Whether both of the App's secrets are set, because a step's `if` cannot read a secret. */
|
|
12
|
+
hasApp: "HUM_HAS_APP",
|
|
13
|
+
gitName: "HUM_GIT_NAME",
|
|
14
|
+
gitEmail: "HUM_GIT_EMAIL",
|
|
15
|
+
/** Set from env, so no shell expands the token's name before git runs the helper. */
|
|
16
|
+
gitCredentialHelper: "HUM_GIT_CREDENTIAL_HELPER",
|
|
17
|
+
/** Git's own name for the file `git config --global` writes: the job points it into the runner's temp folder. */
|
|
18
|
+
gitConfig: "GIT_CONFIG_GLOBAL",
|
|
19
|
+
/** What gather settled, from its job outputs, for the publish job. */
|
|
20
|
+
gathered: "HUM_GATHERED",
|
|
21
|
+
/** The workflow's own token, with which the publish job reads the outbox artifact's size before it downloads it. */
|
|
22
|
+
actionsToken: "HUM_ACTIONS_TOKEN",
|
|
23
|
+
} as const;
|
|
24
|
+
|
|
25
|
+
/** The env names the wake job sets itself, which `ciEnv` may not set. */
|
|
26
|
+
export const WAKE_OWN_ENV: ReadonlySet<string> = new Set(Object.values(WAKE_ENV));
|
|
27
|
+
|
|
28
|
+
/** The action that mints a GitHub App's token, named without its version. */
|
|
29
|
+
export const APP_TOKEN_ACTION = "actions/create-github-app-token";
|
|
30
|
+
|
|
31
|
+
/** GitHub's fixed life of an App's installation token. */
|
|
32
|
+
export const APP_TOKEN_MINUTES = 60;
|
|
33
|
+
|
|
34
|
+
/** The workflow files hum writes: the wake job, and one trigger per event that starts it. */
|
|
35
|
+
export const WORKFLOW_FILES = {
|
|
36
|
+
wake: "hum-wake.yml",
|
|
37
|
+
comment: "hum-comment.yml",
|
|
38
|
+
push: "hum-push.yml",
|
|
39
|
+
dispatch: "hum-dispatch.yml",
|
|
40
|
+
schedule: "hum-schedule.yml",
|
|
41
|
+
} as const;
|
|
42
|
+
|
|
43
|
+
/** The names of the workflow files hum writes. */
|
|
44
|
+
export const CI_WORKFLOW_FILES: ReadonlySet<string> = new Set(Object.values(WORKFLOW_FILES));
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* How GitHub relates a comment's author to the repo, for the people hum hears: the owner, a member of the owning
|
|
48
|
+
* organisation and an invited collaborator. Anyone else's comment starts no wake and is no reply.
|
|
49
|
+
*/
|
|
50
|
+
export const TRUSTED_ASSOCIATIONS = ["OWNER", "MEMBER", "COLLABORATOR"] as const;
|
|
51
|
+
|
|
52
|
+
/** What the wake job takes from the owner as written, where a workflow expression may sit: the runner, the container and env. */
|
|
53
|
+
export type WakeJobSetting = HumConfig["ciRunner"] | HumConfig["ciContainer"] | HumConfig["ciEnv"];
|
|
54
|
+
|
|
55
|
+
/** `secrets.NAME` or `secrets['NAME']`; the quote may follow a backslash, as it does in a setting's JSON. */
|
|
56
|
+
const NAMED_SECRET = /\bsecrets\s*(?:\.\s*|\[\s*\\?['"])([A-Za-z_][A-Za-z0-9_]*)/g;
|
|
57
|
+
|
|
58
|
+
/** The secrets the workflow expressions in the settings name. */
|
|
59
|
+
export const secretsNamed = (...settings: readonly WakeJobSetting[]): string[] => [...JSON.stringify(settings).matchAll(NAMED_SECRET)].flatMap(([, name]) => name ?? []);
|
|
60
|
+
|
|
61
|
+
/** Whether `text` reads the secrets context at all, named or whole. */
|
|
62
|
+
export const readsSecrets = (text: string): boolean => /\bsecrets\b/.test(text);
|
|
63
|
+
|
|
64
|
+
/** A workflow expression that reads a context the wake job lacks: it has no matrix, no earlier job, and takes no inputs. */
|
|
65
|
+
const FOREIGN_CONTEXT = /\$\{\{[^}]*\b(matrix|strategy|needs|steps|inputs)\s*[.[]/;
|
|
66
|
+
|
|
67
|
+
/** Whether a setting holds an expression that means nothing in the wake job, so a value copied from another job would break it. */
|
|
68
|
+
export const readsForeignContext = (setting: WakeJobSetting): boolean => FOREIGN_CONTEXT.test(JSON.stringify(setting));
|
|
69
|
+
|
|
70
|
+
type Runner = HumConfig["ciRunner"];
|
|
71
|
+
|
|
72
|
+
const isGroup = (runner: Runner): runner is Extract<Runner, { readonly group: string }> => runner instanceof Object && "group" in runner;
|
|
73
|
+
|
|
74
|
+
/** The labels of the runners GitHub hosts start with the system they run. */
|
|
75
|
+
const HOSTED_LABEL = /^(ubuntu|windows|macos)-/;
|
|
76
|
+
|
|
77
|
+
/** Whether GitHub hosts the runner: a fresh machine per job. A group, or any other label, may be a machine that outlives the job. */
|
|
78
|
+
export const isGitHubHosted = (runner: Runner): boolean => !isGroup(runner) && [runner].flat().every((label) => HOSTED_LABEL.test(label));
|
package/src/decide/risk.ts
CHANGED
|
@@ -2,8 +2,8 @@ import { quantile } from "simple-statistics";
|
|
|
2
2
|
import { z } from "zod";
|
|
3
3
|
import type { HumConfig, Launch, Level, PathRule } from "../config/schema.ts";
|
|
4
4
|
|
|
5
|
-
/** What only the owner changes: hum's own config, the owner's adapters
|
|
6
|
-
const OWN_PATHS = [".hum/**", "adapters/**", ".github/workflows/**"] as const;
|
|
5
|
+
/** What only the owner changes: hum's own config, the owner's adapters, the CI workflows, and Claude Code's project settings, whose plugins and hooks load in every run. */
|
|
6
|
+
const OWN_PATHS = [".hum/**", "adapters/**", ".github/workflows/**", ".claude/**"] as const;
|
|
7
7
|
|
|
8
8
|
/** What hum reads from a change's diff. */
|
|
9
9
|
export const Change = z
|
package/src/exec.ts
CHANGED
|
@@ -6,6 +6,16 @@ import { SECOND_MS } from "./time.ts";
|
|
|
6
6
|
/** A process environment: the root reads `process.env` once and hands it down. */
|
|
7
7
|
export type Env = Readonly<Record<string, string | undefined>>;
|
|
8
8
|
|
|
9
|
+
/** The GitHub tokens hum pushes and calls GitHub with. A comment can steer a run, and a run writes the code the checks run, so neither holds one. */
|
|
10
|
+
const GITHUB_TOKENS = ["GH_TOKEN", "GITHUB_TOKEN"] as const;
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* The environment as a run and the repo's checks get it: everything but the GitHub tokens, which only hum itself uses.
|
|
14
|
+
* tinyexec starts every child from `process.env` and lays this over it, so a token is kept out by naming it with no
|
|
15
|
+
* value, which the runtime drops; leaving the name out would let `process.env` put it back.
|
|
16
|
+
*/
|
|
17
|
+
export const withoutGitHubTokens = (env: Env) => ({ ...env, ...Object.fromEntries(GITHUB_TOKENS.map((name) => [name, undefined])) });
|
|
18
|
+
|
|
9
19
|
/** A command ran past its limit and was told to stop. */
|
|
10
20
|
export class CommandTimedOut extends Error {
|
|
11
21
|
override name = "CommandTimedOut";
|
package/src/index.ts
CHANGED
package/src/loop/records.ts
CHANGED
|
@@ -51,7 +51,14 @@ export const PossibleRepeat = z.object({ a: name, b: name, models: z.array(name)
|
|
|
51
51
|
export type PossibleRepeat = z.infer<typeof PossibleRepeat>;
|
|
52
52
|
|
|
53
53
|
/** A merged change: what the measure counts. */
|
|
54
|
-
export const Merge = z.object({
|
|
54
|
+
export const Merge = z.object({
|
|
55
|
+
item: name,
|
|
56
|
+
sha: name,
|
|
57
|
+
at: time,
|
|
58
|
+
paths: z.array(name),
|
|
59
|
+
/** The repo's checks have run on the base since it merged; a merge saved before hum checked the base counts as checked. */
|
|
60
|
+
baseChecked: z.boolean().default(true),
|
|
61
|
+
});
|
|
55
62
|
|
|
56
63
|
export type Merge = z.infer<typeof Merge>;
|
|
57
64
|
|
package/src/measure/rate.ts
CHANGED
|
@@ -1,2 +1,16 @@
|
|
|
1
|
+
import type { Boundary } from "../config/schema.ts";
|
|
2
|
+
|
|
1
3
|
/** The share of measured cases a model got right; none when nothing was measured, so no rate stands in for a measurement. */
|
|
2
4
|
export const rateOf = (right: number, measured: number): number | undefined => (measured === 0 ? undefined : right / measured);
|
|
5
|
+
|
|
6
|
+
const RATE_DIGITS = 2;
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* The owner's measured rates with one pooled rate set at `boundary`, under the model as the owner names it and under
|
|
10
|
+
* each model id that answered while it was measured. Trust compares the ids a call's answer names, which an alias
|
|
11
|
+
* such as `haiku` never is, and the pre-call checks read the name in the owner's settings.
|
|
12
|
+
*/
|
|
13
|
+
export const withRate = <M extends Partial<Record<Boundary, Readonly<Record<string, number>>>>>(measured: M, { boundary, model, answered, rate }: { readonly boundary: Boundary; readonly model: string; readonly answered: readonly string[]; readonly rate: number }): M => ({
|
|
14
|
+
...measured,
|
|
15
|
+
[boundary]: { ...measured[boundary], ...Object.fromEntries([model, ...answered].map((id) => [id, Number(rate.toFixed(RATE_DIGITS))])) },
|
|
16
|
+
});
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
import { type Git, type GitIdentity, PATCH } from "../adapters/git.ts";
|
|
2
|
+
|
|
3
|
+
/** Where publish keeps the refs it read from an outbox's bundle, apart from every ref of its own. */
|
|
4
|
+
export const OUTBOX_REFS = "refs/hum/outbox/";
|
|
5
|
+
|
|
6
|
+
/** The ref an item's evidence is kept on; its tip is one commit with no parent. */
|
|
7
|
+
export const EVIDENCE_REFS = "refs/hum/evidence/";
|
|
8
|
+
|
|
9
|
+
/** What publish trusts a bundle against: what gather handed on and the config at gather's base. */
|
|
10
|
+
export type BundleTrust = {
|
|
11
|
+
/** The base commit gather saw. */
|
|
12
|
+
readonly base: string;
|
|
13
|
+
/** The hum branch heads gather put in the inbox. */
|
|
14
|
+
readonly heads: readonly string[];
|
|
15
|
+
/** The owner's commitIdentity in the config at `base`. */
|
|
16
|
+
readonly identity: GitIdentity;
|
|
17
|
+
/** The branch prefixes hum writes, from the config at `base`: run branches and the owner's own. */
|
|
18
|
+
readonly branchPrefixes: readonly string[];
|
|
19
|
+
/** The base's rules require signed commits, so a branch goes through GitHub's API, which carries no file mode or link. */
|
|
20
|
+
readonly signs: boolean;
|
|
21
|
+
};
|
|
22
|
+
|
|
23
|
+
/** A bundle's refs as the work job named them, each at its tip. */
|
|
24
|
+
export type BundleRefs = ReadonlyMap<string, string>;
|
|
25
|
+
|
|
26
|
+
export type BundleCheck = { readonly ok: true; readonly refs: BundleRefs } | { readonly ok: false; readonly why: string };
|
|
27
|
+
|
|
28
|
+
const FIELD = "\u001f";
|
|
29
|
+
|
|
30
|
+
/** One new commit: its sha, its parents, its author and its committer. */
|
|
31
|
+
const COMMIT_FORMAT = ["%H", "%P", "%an", "%ae", "%cn", "%ce"].join("%x1f");
|
|
32
|
+
|
|
33
|
+
/** The one file mode GitHub's API writes. A link, a submodule or an executable bit comes back as another tree. */
|
|
34
|
+
const API_MODE = "100644";
|
|
35
|
+
|
|
36
|
+
const DELETED = "D";
|
|
37
|
+
|
|
38
|
+
const isAllowedRef = (ref: string, { branchPrefixes }: BundleTrust): boolean => ref.startsWith(EVIDENCE_REFS) || branchPrefixes.some((prefix) => ref.startsWith(`refs/heads/${prefix}`));
|
|
39
|
+
|
|
40
|
+
const refsOf = async (git: Git, bundle: string): Promise<Map<string, string>> =>
|
|
41
|
+
new Map(
|
|
42
|
+
(await git.raw(["bundle", "list-heads", bundle]))
|
|
43
|
+
.split("\n")
|
|
44
|
+
.filter(Boolean)
|
|
45
|
+
.map((line) => {
|
|
46
|
+
const [sha = "", ref = ""] = line.split(" ");
|
|
47
|
+
|
|
48
|
+
return [ref, sha] as const;
|
|
49
|
+
}),
|
|
50
|
+
);
|
|
51
|
+
|
|
52
|
+
type NewCommit = { readonly sha: string; readonly parents: readonly string[]; readonly author: string; readonly committer: string };
|
|
53
|
+
|
|
54
|
+
/** The commits the tips reach that neither gather's base nor an inbox head reaches. */
|
|
55
|
+
const newCommits = async (git: Git, tips: readonly string[], trust: BundleTrust): Promise<NewCommit[]> =>
|
|
56
|
+
(await git.raw(["log", `--format=${COMMIT_FORMAT}`, ...tips, "--not", trust.base, ...trust.heads]))
|
|
57
|
+
.split("\n")
|
|
58
|
+
.filter(Boolean)
|
|
59
|
+
.map((line) => {
|
|
60
|
+
const [sha = "", parents = "", authorName, authorEmail, committerName, committerEmail] = line.split(FIELD);
|
|
61
|
+
|
|
62
|
+
return { sha, parents: parents.split(" ").filter(Boolean), author: `${authorName} <${authorEmail}>`, committer: `${committerName} <${committerEmail}>` };
|
|
63
|
+
});
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* Why the commits break the owner's rules: each is by commitIdentity, and each parent is another new commit, gather's
|
|
67
|
+
* base or an inbox head. Only an evidence ref's tip has no parent. The identity check stops a commit made under the
|
|
68
|
+
* wrong name by mistake; a hostile work job writes any name it likes, so the walls against it are the ref check and
|
|
69
|
+
* publish placing the change from its own diff and config.
|
|
70
|
+
*/
|
|
71
|
+
const commitFault = (commits: readonly NewCommit[], evidenceTips: ReadonlySet<string>, trust: BundleTrust): string | undefined => {
|
|
72
|
+
const owner = `${trust.identity.name} <${trust.identity.email}>`;
|
|
73
|
+
const known = new Set([trust.base, ...trust.heads, ...commits.map(({ sha }) => sha)]);
|
|
74
|
+
|
|
75
|
+
for (const { sha, parents, author, committer } of commits) {
|
|
76
|
+
if (author !== owner || committer !== owner) return `commit ${sha} is by ${author}, committed by ${committer}, not by commitIdentity ${owner}`;
|
|
77
|
+
|
|
78
|
+
if (parents.length === 0 && !evidenceTips.has(sha)) return `commit ${sha} has no parent and is no evidence ref's tip`;
|
|
79
|
+
|
|
80
|
+
const stranger = parents.find((parent) => !known.has(parent));
|
|
81
|
+
|
|
82
|
+
if (stranger !== undefined) return `commit ${sha} grows from ${stranger}, which is neither the base gather saw nor a hum branch it handed on`;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
return undefined;
|
|
86
|
+
};
|
|
87
|
+
|
|
88
|
+
/** The first path a branch changes, against where it left gather's base, that GitHub's API cannot carry. */
|
|
89
|
+
const uncarried = async (git: Git, tip: string, base: string): Promise<string | undefined> => {
|
|
90
|
+
const from = (await git.raw(["merge-base", tip, base])).trim();
|
|
91
|
+
const fields = (await git.raw(["diff", "--raw", "--no-abbrev", "--no-renames", "-z", ...PATCH, from, tip])).split("\0").filter(Boolean);
|
|
92
|
+
|
|
93
|
+
return fields.flatMap((meta, at) => {
|
|
94
|
+
const [, mode = "", , , status = ""] = meta.split(" ");
|
|
95
|
+
|
|
96
|
+
return at % 2 === 0 && status !== DELETED && mode !== API_MODE ? [`${fields[at + 1] ?? ""} (mode ${mode})`] : [];
|
|
97
|
+
})[0];
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Reads an outbox's bundle into publish's repo under `OUTBOX_REFS` and checks it before any write: every ref is one
|
|
102
|
+
* hum writes, every object passes git's own check, every new commit is by commitIdentity and grows from gather's base
|
|
103
|
+
* or a hum branch it handed on, and on a base that requires signed commits no branch changes a mode GitHub's API
|
|
104
|
+
* cannot carry. The repo must already hold gather's base and heads.
|
|
105
|
+
*/
|
|
106
|
+
export const checkBundle = async (git: Git, bundle: string, trust: BundleTrust): Promise<BundleCheck> => {
|
|
107
|
+
const verified = await git.run(["bundle", "verify", "-q", bundle]);
|
|
108
|
+
|
|
109
|
+
if (verified.code !== 0) return { ok: false, why: `the bundle does not verify against what gather handed on: ${verified.stderr.trim()}` };
|
|
110
|
+
|
|
111
|
+
const refs = await refsOf(git, bundle);
|
|
112
|
+
const foreign = [...refs.keys()].find((ref) => !isAllowedRef(ref, trust));
|
|
113
|
+
|
|
114
|
+
if (foreign !== undefined) return { ok: false, why: `the bundle names ${foreign}, which is no ref hum writes` };
|
|
115
|
+
|
|
116
|
+
await git.raw(["-c", "transfer.fsckObjects=true", "fetch", "-q", "--no-tags", bundle, ...[...refs.keys()].map((ref) => `+${ref}:${OUTBOX_REFS}${ref.slice("refs/".length)}`)]);
|
|
117
|
+
|
|
118
|
+
const evidenceTips = new Set([...refs].flatMap(([ref, sha]) => (ref.startsWith(EVIDENCE_REFS) ? [sha] : [])));
|
|
119
|
+
const fault = commitFault(await newCommits(git, [...refs.values()], trust), evidenceTips, trust);
|
|
120
|
+
|
|
121
|
+
if (fault !== undefined) return { ok: false, why: fault };
|
|
122
|
+
|
|
123
|
+
const branches = [...refs].filter(([ref]) => !ref.startsWith(EVIDENCE_REFS));
|
|
124
|
+
const carried = trust.signs ? await Promise.all(branches.map(async ([ref, tip]) => ({ ref, path: await uncarried(git, tip, trust.base) }))) : [];
|
|
125
|
+
const refused = carried.find(({ path }) => path !== undefined);
|
|
126
|
+
|
|
127
|
+
return refused ? { ok: false, why: `${refused.ref} changes ${refused.path}, which a commit through GitHub's API cannot carry` } : { ok: true, refs };
|
|
128
|
+
};
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
import { copyFileSync, mkdirSync } from "node:fs";
|
|
2
|
+
import { dirname } from "node:path";
|
|
3
|
+
import { savedLimitUntil, settleLimit } from "../adapters/limit.ts";
|
|
4
|
+
import { nextStates, reachedFrom } from "../config/machine.ts";
|
|
5
|
+
import { type Config } from "../config/load.ts";
|
|
6
|
+
import { type Kind, OWNER_WAIT_TAG } from "../config/schema.ts";
|
|
7
|
+
import type { State } from "../state/open.ts";
|
|
8
|
+
import type { Spent } from "../state/saved.ts";
|
|
9
|
+
import { queuedKey } from "../worker/questions.ts";
|
|
10
|
+
import { OWNER_APPROVAL } from "../decide/merge.ts";
|
|
11
|
+
import { SNAPSHOT_CARDS } from "../state/items.ts";
|
|
12
|
+
|
|
13
|
+
/** Where publish found an item's saved machine state before the work job ran, and whether the owner had answered. */
|
|
14
|
+
export type InboxItem = {
|
|
15
|
+
readonly item: string;
|
|
16
|
+
readonly kind: Kind;
|
|
17
|
+
/** The machine's state in the inbox, or undefined when the item had none. */
|
|
18
|
+
readonly at: string | undefined;
|
|
19
|
+
/** The inbox thread holds the owner's answer to the wait the item is in. */
|
|
20
|
+
readonly answered: boolean;
|
|
21
|
+
};
|
|
22
|
+
|
|
23
|
+
const isOwnerWait = (kind: Kind, state: string): boolean => kind.machine.states[state]?.tags?.includes(OWNER_WAIT_TAG) ?? false;
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* The states one pass may carry an item to from where the inbox saved it: through every transition of its kind's
|
|
27
|
+
* machine, past the owner's wait it starts in only with the owner's answer, and never past another owner's wait.
|
|
28
|
+
*/
|
|
29
|
+
export const passReach = ({ kind, at, answered }: Omit<InboxItem, "item">): ReadonlySet<string> => {
|
|
30
|
+
const start = at ?? kind.machine.initial;
|
|
31
|
+
|
|
32
|
+
return reachedFrom(start, nextStates(kind), (state) => !isOwnerWait(kind, state) || (state === start && answered));
|
|
33
|
+
};
|
|
34
|
+
|
|
35
|
+
/** The rank of a kind's floor among the levels; a kind with no floor ranks lowest. */
|
|
36
|
+
const floorRank = (config: Config, kind: string): number => {
|
|
37
|
+
const floor = config.hum.kindFloors[kind];
|
|
38
|
+
|
|
39
|
+
return floor === undefined ? -1 : config.hum.levels.findIndex(({ name }) => name === floor);
|
|
40
|
+
};
|
|
41
|
+
|
|
42
|
+
/** Why a work job may not move an item from one kind to another: it names the kind the item has, or one whose risk floor is lower. */
|
|
43
|
+
export const kindMoveFault = (config: Config, { from, to }: { readonly from: string; readonly to: string }): string | undefined => {
|
|
44
|
+
if (to === from) return `it moves the item to ${to}, the kind it already has`;
|
|
45
|
+
|
|
46
|
+
return floorRank(config, to) < floorRank(config, from) ? `it moves the item from ${from} to ${to}, whose risk floor is lower` : undefined;
|
|
47
|
+
};
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* An item's spend as publish takes it from a work job: the total only rises, and the count toward the kind's cap
|
|
51
|
+
* starts afresh only where the owner answered.
|
|
52
|
+
*/
|
|
53
|
+
const raisedSpend = (held: Spent | undefined, worked: Spent, answered: boolean): Spent => {
|
|
54
|
+
const total = Math.max(held?.total ?? 0, worked.total);
|
|
55
|
+
const base = held?.base ?? 0;
|
|
56
|
+
|
|
57
|
+
return { item: worked.item, total, base: answered ? Math.min(Math.max(base, worked.base), total) : base };
|
|
58
|
+
};
|
|
59
|
+
|
|
60
|
+
/** The cards a work job raises on an item that publish shows: those of its saved state, never one with an action. */
|
|
61
|
+
const WORK_CARD_CODES: ReadonlySet<string> = new Set(Object.values(SNAPSHOT_CARDS));
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Takes into publish's state what a work job wrote for one item it ran, and nothing else: the item's machine state
|
|
65
|
+
* when it is one a pass can reach from the inbox's, its runs, its spend where it raises publish's, its plan, whose
|
|
66
|
+
* models land reads beside the ones the config gives the plan run, its pull request text, its proof,
|
|
67
|
+
* the questions it queued, never offering the owner's approval, its choices, its events, its saved state's cards with
|
|
68
|
+
* no action, and the usage limit cut to `usageLimitMaxMs` from now. Landings, verdicts, merges, learned rules, kinds,
|
|
69
|
+
* answers and op keys stay as publish has them. Returns why the machine state was refused, or nothing once all is taken.
|
|
70
|
+
*/
|
|
71
|
+
export const takeWorkRecords = (work: State, into: State, inbox: InboxItem, limits: { readonly now: number; readonly usageLimitMaxMs: number }): string | undefined => {
|
|
72
|
+
const { item, kind } = inbox;
|
|
73
|
+
const saved = work.items.saved().find(({ itemId }) => itemId === item);
|
|
74
|
+
|
|
75
|
+
if (saved !== undefined) {
|
|
76
|
+
if (saved.kind !== kind.machine.id || saved.machineVersion !== kind.machine.version) return `the work job saved ${item} under ${saved.kind}@${saved.machineVersion}, not ${kind.machine.id}@${kind.machine.version}`;
|
|
77
|
+
|
|
78
|
+
if (saved.state === undefined || !passReach(inbox).has(saved.state)) return `no pass takes ${item} from ${inbox.at ?? kind.machine.initial} to ${saved.state ?? "a nested state"}`;
|
|
79
|
+
|
|
80
|
+
mkdirSync(dirname(into.items.path(item)), { recursive: true });
|
|
81
|
+
copyFileSync(work.items.path(item), into.items.path(item));
|
|
82
|
+
} else into.items.remove(item);
|
|
83
|
+
|
|
84
|
+
for (const record of work.runs.list(item)) into.runs.keep(record);
|
|
85
|
+
|
|
86
|
+
const worked = work.spent.get(item);
|
|
87
|
+
|
|
88
|
+
if (worked !== undefined) into.spent.put(item, raisedSpend(into.spent.get(item), worked, inbox.answered));
|
|
89
|
+
|
|
90
|
+
work.plans.copyTo(into.plans, item);
|
|
91
|
+
work.pullRequests.copyTo(into.pullRequests, item);
|
|
92
|
+
work.proofs.copyTo(into.proofs, item);
|
|
93
|
+
|
|
94
|
+
for (const queued of work.questions.list().filter((queued) => queued.item === item && queued.askedAt === undefined)) into.questions.put(queuedKey(queued), { ...queued, options: queued.options?.filter((option) => option !== OWNER_APPROVAL) });
|
|
95
|
+
|
|
96
|
+
for (const choice of work.choices.list().filter((choice) => choice.item === item)) into.choices.put(`${item}@${choice.text}`, choice);
|
|
97
|
+
|
|
98
|
+
for (const event of work.events.list(item)) into.events.add(event);
|
|
99
|
+
|
|
100
|
+
for (const { code, cause, fix } of work.faults.list().filter((card) => card.item === item && WORK_CARD_CODES.has(card.code))) into.faults.raise({ code, item, cause, fix });
|
|
101
|
+
|
|
102
|
+
const until = savedLimitUntil(work);
|
|
103
|
+
|
|
104
|
+
if (until > 0) settleLimit(into, { kind: "limited", until: Math.min(until, limits.now + limits.usageLimitMaxMs) });
|
|
105
|
+
|
|
106
|
+
return undefined;
|
|
107
|
+
};
|