@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.
Files changed (70) hide show
  1. package/defaults/hum.json +14 -2
  2. package/defaults/roles/build.md +1 -1
  3. package/defaults/roles/fix.md +1 -1
  4. package/npm-shrinkwrap.json +3297 -0
  5. package/package.json +6 -2
  6. package/release.json +3 -0
  7. package/schema/hum.schema.json +251 -10
  8. package/scripts/eval.ts +21 -5
  9. package/src/adapter-api.ts +3 -1
  10. package/src/adapters/claude-bg.ts +2 -2
  11. package/src/adapters/claude-p.ts +44 -18
  12. package/src/adapters/contract.ts +12 -0
  13. package/src/adapters/fake.ts +5 -0
  14. package/src/adapters/git.ts +61 -9
  15. package/src/adapters/github-client.ts +15 -0
  16. package/src/adapters/github-commits.ts +84 -0
  17. package/src/adapters/github.ts +36 -4
  18. package/src/adapters/guard.ts +1 -0
  19. package/src/adapters/item-file.ts +1 -1
  20. package/src/adapters/markdown.ts +10 -1
  21. package/src/adapters/pull-requests.ts +8 -8
  22. package/src/adapters/registry.ts +5 -7
  23. package/src/adapters/roundup.ts +3 -0
  24. package/src/bytes.ts +1 -0
  25. package/src/cli/service.ts +176 -29
  26. package/src/cli/setup.ts +16 -7
  27. package/src/config/checks.ts +27 -43
  28. package/src/config/load.ts +2 -3
  29. package/src/config/machine.ts +29 -0
  30. package/src/config/migrate.ts +5 -2
  31. package/src/config/refusal.ts +9 -4
  32. package/src/config/schema.ts +86 -8
  33. package/src/config/wake-job.ts +78 -0
  34. package/src/decide/risk.ts +2 -2
  35. package/src/exec.ts +10 -0
  36. package/src/index.ts +1 -1
  37. package/src/loop/records.ts +8 -1
  38. package/src/measure/rate.ts +14 -0
  39. package/src/publish/bundle.ts +128 -0
  40. package/src/publish/handoff.ts +107 -0
  41. package/src/publish/handover.ts +182 -0
  42. package/src/publish/intents.ts +61 -0
  43. package/src/publish/publisher.ts +259 -0
  44. package/src/publish/wake.ts +78 -0
  45. package/src/service/ci-state.ts +99 -0
  46. package/src/service/plugins.ts +137 -0
  47. package/src/service/wake.ts +3 -1
  48. package/src/service/workflows.ts +261 -50
  49. package/src/setup/propose.ts +87 -3
  50. package/src/setup/prove.ts +3 -3
  51. package/src/setup/scan.ts +61 -5
  52. package/src/setup/tables.ts +18 -0
  53. package/src/setup/write.ts +52 -19
  54. package/src/state/items.ts +17 -8
  55. package/src/state/open.ts +20 -6
  56. package/src/state/records.ts +7 -0
  57. package/src/state/runs.ts +5 -0
  58. package/src/state/saved.ts +17 -2
  59. package/src/worker/base-check.ts +41 -13
  60. package/src/worker/checks.ts +3 -2
  61. package/src/worker/evidence.ts +72 -0
  62. package/src/worker/kind.ts +4 -7
  63. package/src/worker/land.ts +173 -81
  64. package/src/worker/merged.ts +20 -8
  65. package/src/worker/open.ts +33 -17
  66. package/src/worker/questions.ts +16 -8
  67. package/src/worker/signed-push.ts +167 -0
  68. package/src/worker/thin-path.ts +245 -133
  69. package/src/worker/worker.ts +50 -9
  70. package/surface.json +610 -76
@@ -23,7 +23,7 @@ const isOpenQuestion = (thread: readonly ThreadEntry[], text: string): boolean =
23
23
  return open !== undefined && visibleText(open.text) === text;
24
24
  };
25
25
 
26
- const keyOf = ({ item, queuedAt }: Pick<QueuedQuestion, "item" | "queuedAt">): string => `${item}@${queuedAt}`;
26
+ export const queuedKey = ({ item, queuedAt }: Pick<QueuedQuestion, "item" | "queuedAt">): string => `${item}@${queuedAt}`;
27
27
 
28
28
  /** How long an asked question is kept: long enough to count the day, and to read late answers to it. */
29
29
  const keptFor = ({ hum }: Config): number => Math.max(DAY_MS, hum.questionTimeoutHours * HOUR_MS);
@@ -51,7 +51,7 @@ export const queueQuestion = (ctx: Pick<QuestionContext, "state" | "config" | "n
51
51
  queuedAt: now(),
52
52
  };
53
53
 
54
- state.questions.put(keyOf(queued), queued);
54
+ state.questions.put(queuedKey(queued), queued);
55
55
  };
56
56
 
57
57
  const waitingOrder = (queue: readonly QueuedQuestion[]): QueuedQuestion[] => {
@@ -66,21 +66,29 @@ const waitingOrder = (queue: readonly QueuedQuestion[]): QueuedQuestion[] => {
66
66
  return ranked.sort(questionOrder).map(({ queued }) => queued);
67
67
  };
68
68
 
69
+ /** What the daily question cap has room for now: the questions asked and the follow-ups filed within the day take theirs, and older ones are dropped. */
70
+ export const roomToday = ({ state, config, now }: Pick<QuestionContext, "state" | "config" | "now">): number => {
71
+ for (const old of state.questions.list()) if (old.askedAt !== undefined && !isKept(old.askedAt, config, now())) state.questions.remove(queuedKey(old));
72
+
73
+ for (const old of state.followUps.list()) if (!isKept(old.at, config, now())) state.followUps.remove(old.item);
74
+
75
+ const asked = state.questions.list().flatMap(({ askedAt }) => (askedAt === undefined ? [] : [askedAt]));
76
+
77
+ return roomToAsk({ askedAt: [...asked, ...state.followUps.list().map(({ at }) => at)], cap: config.hum.dailyQuestionCap, now: now() });
78
+ };
79
+
69
80
  /** Asks the queued questions the daily cap has room for, first by the owner's priority label, then by how many items wait on it, then by age. */
70
81
  export const releaseQuestions = async (ctx: QuestionContext): Promise<string[]> => {
71
- const { state, config, workSource, questions, now } = ctx;
82
+ const { state, workSource, questions, now } = ctx;
83
+ const room = roomToday(ctx);
72
84
  const all = state.questions.list();
73
-
74
- for (const old of all) if (old.askedAt !== undefined && !isKept(old.askedAt, config, now())) state.questions.remove(keyOf(old));
75
-
76
- const room = roomToAsk({ askedAt: all.flatMap(({ askedAt }) => (askedAt === undefined ? [] : [askedAt])), cap: config.hum.dailyQuestionCap, now: now() });
77
85
  const released: string[] = [];
78
86
 
79
87
  for (const queued of waitingOrder(all.filter(isWaiting)).slice(0, room)) {
80
88
  const calls = onceCalls({ apiVersion: ADAPTER_API_VERSION, workSource, questions }, state.ops, { run: "ask", attempt: queued.queuedAt });
81
89
 
82
90
  await calls.questions?.ask(ItemId.parse(queued.item), { text: queued.text, options: queued.options, detail: queued.detail });
83
- state.questions.put(keyOf(queued), { ...queued, askedAt: now() });
91
+ state.questions.put(queuedKey(queued), { ...queued, askedAt: now() });
84
92
  released.push(queued.item);
85
93
  }
86
94
 
@@ -0,0 +1,167 @@
1
+ import { type Git, isAncestor, push, type PushOutcome } from "../adapters/git.ts";
2
+ import type { FileChanges, GitHubCommits } from "../adapters/github-commits.ts";
3
+ import type { PullRequests } from "../adapters/pull-requests.ts";
4
+
5
+ /** What a push reads: the clone's git, the base the change lands on, and the remote's rules and branches on GitHub. */
6
+ export type PushContext = {
7
+ readonly git: Git;
8
+ readonly base: string;
9
+ readonly pulls: PullRequests | undefined;
10
+ readonly commits: GitHubCommits | undefined;
11
+ };
12
+
13
+ /** A push that landed, at the commit the branch now holds. */
14
+ type Signed = { readonly kind: "pushed"; readonly sha: string } | Exclude<PushOutcome, { kind: "pushed" }>;
15
+
16
+ /** One object `git cat-file --batch` printed: `<oid> <type> <size>`, a newline, the bytes and a newline. */
17
+ const BATCH_HEADER = /^([0-9a-f]+) blob (\d+)$/;
18
+
19
+ const NEWLINE = 0x0a;
20
+
21
+ /** Each blob's bytes in base64 by its oid, from what `git cat-file --batch` printed; anything but a blob throws. */
22
+ const blobsOf = (batch: Buffer): ReadonlyMap<string, string> => {
23
+ const blobs = new Map<string, string>();
24
+
25
+ for (let at = 0; at < batch.length; ) {
26
+ const end = batch.indexOf(NEWLINE, at);
27
+ const header = batch.toString("utf8", at, end);
28
+ const [, oid, size] = BATCH_HEADER.exec(header) ?? [];
29
+
30
+ if (oid === undefined) throw new Error(`git cat-file --batch printed ${header}, not a blob`);
31
+
32
+ const stop = end + 1 + Number(size);
33
+
34
+ blobs.set(oid, batch.subarray(end + 1, stop).toString("base64"));
35
+ at = stop + 1;
36
+ }
37
+
38
+ return blobs;
39
+ };
40
+
41
+ /** The files `to` adds, changes and deletes against `from`, as GitHub's commit takes them, every blob read by one git process. */
42
+ const changesBetween = async (git: Git, from: string, to: string): Promise<FileChanges> => {
43
+ const fields = (await git.raw(["diff", "--raw", "--no-abbrev", "--no-renames", "-z", from, to])).split("\0").filter(Boolean);
44
+
45
+ const changed = fields.flatMap((meta, at) => {
46
+ const [, , , blob = "", status = ""] = meta.split(" ");
47
+
48
+ return at % 2 === 0 ? [{ blob, status, path: fields[at + 1] ?? "" }] : [];
49
+ });
50
+
51
+ const kept = changed.filter(({ status }) => status !== "D");
52
+ const blobs = kept.length === 0 ? new Map<string, string>() : blobsOf(await git.bytes(["cat-file", "--batch"], `${kept.map(({ blob }) => blob).join("\n")}\n`));
53
+
54
+ return {
55
+ additions: kept.map(({ path, blob }) => ({ path, contents: blobs.get(blob) ?? "" })),
56
+ deletions: changed.filter(({ status }) => status === "D").map(({ path }) => ({ path })),
57
+ };
58
+ };
59
+
60
+ /** The commit message: the newest commit's subject, and each commit's subject below it when several make the change. */
61
+ const messageOf = async (git: Git, from: string, to: string): Promise<{ readonly headline: string; readonly body: string }> => {
62
+ const subjects = (await git.raw(["log", "--reverse", "--format=%s", `${from}..${to}`])).split("\n").filter(Boolean);
63
+
64
+ return {
65
+ headline: (await git.raw(["log", "-1", "--format=%s", to])).trim(),
66
+ body: subjects.length > 1 ? subjects.map((subject) => `- ${subject}`).join("\n") : (await git.raw(["log", "-1", "--format=%b", to])).trim(),
67
+ };
68
+ };
69
+
70
+ /** Whether commits that reach the base must carry a signature GitHub verifies, as its rules say. */
71
+ export const signsCommits = async ({ pulls, base }: Pick<PushContext, "pulls" | "base">): Promise<boolean> => pulls !== undefined && (await pulls.rules(base)).requiresSignatures;
72
+
73
+ const requireCommits = ({ commits, base }: Pick<PushContext, "commits" | "base">): GitHubCommits => {
74
+ if (!commits) throw new Error(`${base} requires signed commits, and hum has no GitHub client to make them through`);
75
+
76
+ return commits;
77
+ };
78
+
79
+ /** The branch GitHub makes each commit on, so the branch itself moves only to a commit whose tree is checked. */
80
+ const scratchBranch = (branch: string): string => `${branch}-signing`;
81
+
82
+ /**
83
+ * Puts the tree of `from` on `branch` as one commit that GitHub makes on `parent`, and so signs. The branch must stand
84
+ * at `parent`, or not exist; with `replace`, a branch elsewhere is moved to the new commit. A commit through the API
85
+ * carries no file mode or link, so GitHub makes it on a scratch branch first, and a tree that comes back different
86
+ * throws before the branch moves.
87
+ */
88
+ export const commitSigned = async (ctx: PushContext, { from, parent, branch, replace }: { readonly from: string; readonly parent: string; readonly branch: string; readonly replace: boolean }): Promise<Signed> => {
89
+ const commits = requireCommits(ctx);
90
+ const remote = await commits.head(branch);
91
+
92
+ if (remote !== undefined && remote !== parent && !replace) return { kind: "conflict" };
93
+
94
+ const scratch = scratchBranch(branch);
95
+ const created = await commits.createBranch(scratch, parent);
96
+ const placed = created.kind === "conflict" ? await commits.moveBranch(scratch, parent, true) : created;
97
+
98
+ if (placed.kind !== "done") return placed;
99
+
100
+ try {
101
+ const made = await commits.commitOnBranch({ branch: scratch, expected: parent, ...(await messageOf(ctx.git, parent, from)), files: await changesBetween(ctx.git, parent, from) });
102
+
103
+ if (made.kind !== "done") return made;
104
+
105
+ const tree = (await ctx.git.raw(["rev-parse", `${from}^{tree}`])).trim();
106
+
107
+ if (made.value.tree !== tree) throw new Error(`GitHub's commit ${made.value.oid} holds another tree than ${from}, so ${branch} was left where it was: the change holds an executable bit, a link or a submodule, which a commit through GitHub's API cannot carry`);
108
+
109
+ const moved = remote === undefined ? await commits.createBranch(branch, made.value.oid) : await commits.moveBranch(branch, made.value.oid, remote !== parent);
110
+
111
+ return moved.kind === "done" ? { kind: "pushed", sha: made.value.oid } : moved;
112
+ } finally {
113
+ await commits.deleteBranch(scratch);
114
+ }
115
+ };
116
+
117
+ /**
118
+ * Pushes HEAD to the run branch. Where the base's rules ask for signed commits, GitHub makes one commit of the change,
119
+ * on the branch's own tip when HEAD grew from it, else on where HEAD left the base, and HEAD moves to it with its tree
120
+ * unchanged. Elsewhere git force-pushes.
121
+ */
122
+ export const pushRunBranch = async (ctx: PushContext, branch: string): Promise<PushOutcome> => {
123
+ const { git, base } = ctx;
124
+
125
+ if (!(await signsCommits(ctx))) return push(git, ["--force", "origin", `HEAD:refs/heads/${branch}`]);
126
+
127
+ const head = (await git.raw(["rev-parse", "HEAD"])).trim();
128
+ const remote = await requireCommits(ctx).head(branch);
129
+
130
+ if (remote === head) return { kind: "pushed" };
131
+
132
+ await git.raw(["fetch", "-q", "origin", base, ...(remote === undefined ? [] : [branch])]);
133
+
134
+ const grewFrom = remote !== undefined && (await isAncestor(git, { ancestor: remote, descendant: head }));
135
+ const parent = grewFrom ? remote : (await git.raw(["merge-base", head, `origin/${base}`])).trim();
136
+ const signed = await commitSigned(ctx, { from: head, parent, branch, replace: true });
137
+
138
+ if (signed.kind !== "pushed") return signed;
139
+
140
+ await git.raw(["fetch", "-q", "origin", branch]);
141
+ await git.raw(["reset", "-q", signed.sha]);
142
+
143
+ return { kind: "pushed" };
144
+ };
145
+
146
+ /** Moves the base to HEAD, as a fast-forward: through GitHub's API where the base's rules ask for signed commits, else with git. */
147
+ export const pushBase = async (ctx: PushContext): Promise<PushOutcome> => {
148
+ if (!(await signsCommits(ctx))) return push(ctx.git, ["origin", `HEAD:refs/heads/${ctx.base}`]);
149
+
150
+ const moved = await requireCommits(ctx).moveBranch(ctx.base, (await ctx.git.raw(["rev-parse", "HEAD"])).trim(), false);
151
+
152
+ return moved.kind === "done" ? { kind: "pushed" } : moved;
153
+ };
154
+
155
+ /** Pushes `<sha>:refs/heads/<branch>` refspecs of single commits, each signed by GitHub where the base's rules ask for it. */
156
+ export const pushCommits = async (ctx: PushContext, refspecs: readonly string[]): Promise<PushOutcome> => {
157
+ if (!(await signsCommits(ctx))) return push(ctx.git, ["origin", ...refspecs]);
158
+
159
+ for (const refspec of refspecs) {
160
+ const [from = "", to = ""] = refspec.split(":");
161
+ const signed = await commitSigned(ctx, { from, parent: (await ctx.git.raw(["rev-parse", `${from}^`])).trim(), branch: to.replace(/^refs\/heads\//, ""), replace: false });
162
+
163
+ if (signed.kind !== "pushed") return signed;
164
+ }
165
+
166
+ return { kind: "pushed" };
167
+ };