@moo.md/hum 0.1.0 → 0.3.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 (112) hide show
  1. package/defaults/hum.json +9 -2
  2. package/package.json +2 -2
  3. package/schema/hum.schema.json +208 -7
  4. package/scripts/eval.ts +88 -50
  5. package/src/adapter-api.ts +46 -14
  6. package/src/adapters/admit.ts +2 -2
  7. package/src/adapters/argument.ts +1 -1
  8. package/src/adapters/claim.ts +18 -15
  9. package/src/adapters/claude-bg.ts +50 -27
  10. package/src/adapters/claude-p.ts +18 -23
  11. package/src/adapters/contract.ts +22 -10
  12. package/src/adapters/each-call.ts +9 -0
  13. package/src/adapters/fake.ts +6 -6
  14. package/src/adapters/git.ts +10 -18
  15. package/src/adapters/github-client.ts +102 -0
  16. package/src/adapters/github.ts +61 -146
  17. package/src/adapters/guard.ts +20 -9
  18. package/src/adapters/history.ts +12 -15
  19. package/src/adapters/item-file.ts +1 -1
  20. package/src/adapters/markdown.ts +49 -42
  21. package/src/adapters/marked.ts +6 -12
  22. package/src/adapters/model-call.ts +4 -4
  23. package/src/adapters/once.ts +5 -5
  24. package/src/adapters/owner-commit.ts +13 -11
  25. package/src/adapters/pull-requests.ts +11 -13
  26. package/src/adapters/registry.ts +9 -8
  27. package/src/adapters/roundup.ts +27 -35
  28. package/src/adapters/serial.ts +4 -5
  29. package/src/adapters/transcript.ts +13 -8
  30. package/src/cli/main.ts +1 -0
  31. package/src/cli/ops.ts +32 -14
  32. package/src/cli/service.ts +14 -8
  33. package/src/cli/setup.ts +22 -7
  34. package/src/cli/shared-watch.ts +3 -3
  35. package/src/config/checks.ts +27 -18
  36. package/src/config/machine.ts +5 -7
  37. package/src/config/migrate.ts +5 -2
  38. package/src/config/refusal.ts +15 -2
  39. package/src/config/schema.ts +74 -12
  40. package/src/config/settings.ts +17 -2
  41. package/src/config/state-map.ts +5 -3
  42. package/src/config/wake-job.ts +74 -0
  43. package/src/decide/alignment.ts +4 -4
  44. package/src/decide/answer.ts +24 -22
  45. package/src/decide/kind.ts +1 -6
  46. package/src/decide/labels.ts +9 -9
  47. package/src/decide/merge.ts +6 -7
  48. package/src/decide/prose.ts +4 -4
  49. package/src/decide/question.ts +23 -20
  50. package/src/decide/review.ts +4 -2
  51. package/src/decide/risk.ts +25 -19
  52. package/src/decide/taste.ts +3 -3
  53. package/src/exec.ts +4 -3
  54. package/src/index.ts +14 -13
  55. package/src/loop/check-item.ts +3 -3
  56. package/src/loop/ci.ts +1 -1
  57. package/src/loop/github.ts +2 -2
  58. package/src/loop/groups.ts +13 -6
  59. package/src/loop/memory.ts +40 -28
  60. package/src/loop/notes.ts +5 -5
  61. package/src/loop/pair.ts +1 -1
  62. package/src/loop/pass.ts +18 -12
  63. package/src/loop/proof.ts +9 -7
  64. package/src/loop/prove-item.ts +1 -1
  65. package/src/loop/records.ts +12 -13
  66. package/src/loop/signals.ts +6 -6
  67. package/src/measure/inputs.ts +1 -1
  68. package/src/measure/measure.ts +4 -4
  69. package/src/measure/rate.ts +2 -0
  70. package/src/service/ci-tick.ts +2 -2
  71. package/src/service/supervise.ts +3 -2
  72. package/src/service/token.ts +3 -3
  73. package/src/service/wake.ts +2 -2
  74. package/src/service/workflows.ts +165 -48
  75. package/src/setup/propose.ts +78 -7
  76. package/src/setup/prove.ts +18 -12
  77. package/src/setup/scan.ts +91 -28
  78. package/src/setup/shipped.ts +8 -2
  79. package/src/setup/tables.ts +22 -3
  80. package/src/setup/waits.ts +9 -11
  81. package/src/setup/write.ts +67 -27
  82. package/src/slots/pool.ts +32 -24
  83. package/src/state/events.ts +1 -1
  84. package/src/state/faults.ts +13 -5
  85. package/src/state/format.ts +2 -2
  86. package/src/state/items.ts +9 -10
  87. package/src/state/open.ts +2 -2
  88. package/src/state/ops.ts +16 -10
  89. package/src/state/records.ts +5 -5
  90. package/src/state/runs.ts +33 -26
  91. package/src/state/saved.ts +44 -32
  92. package/src/status/file.ts +20 -1
  93. package/src/status/format.ts +47 -57
  94. package/src/status/sections.ts +2 -2
  95. package/src/worker/alignment-report.ts +4 -5
  96. package/src/worker/answers.ts +26 -24
  97. package/src/worker/base-check.ts +2 -2
  98. package/src/worker/kind.ts +23 -19
  99. package/src/worker/land.ts +114 -126
  100. package/src/worker/merged.ts +9 -7
  101. package/src/worker/open.ts +14 -12
  102. package/src/worker/prose-run.ts +3 -3
  103. package/src/worker/questions.ts +15 -12
  104. package/src/worker/scheduler.ts +4 -4
  105. package/src/worker/signature.ts +3 -3
  106. package/src/worker/tally.ts +0 -2
  107. package/src/worker/taste.ts +6 -15
  108. package/src/worker/thin-path.ts +148 -121
  109. package/src/worker/thread.ts +25 -0
  110. package/src/worker/worker.ts +77 -47
  111. package/surface.json +1091 -2251
  112. package/src/slots/scan.ts +0 -26
package/src/loop/pass.ts CHANGED
@@ -4,9 +4,9 @@ import type { Config } from "../config/load.ts";
4
4
  import type { PastChange } from "../decide/labels.ts";
5
5
  import type { State } from "../state/open.ts";
6
6
  import { checkNameOf, fileChecks, filedFrom } from "./check-item.ts";
7
- import { type CiLogs, logNames } from "./ci.ts";
7
+ import { type CiLogs, doesLogName } from "./ci.ts";
8
8
  import { type Proposer, groupNotes } from "./groups.ts";
9
- import { parseMemory, renderMemory, withoutCovered } from "./memory.ts";
9
+ import { withoutCovered } from "./memory.ts";
10
10
  import { breakNotes, ownerNotes, planChangingNotes, type RawComment, saveNotes } from "./notes.ts";
11
11
  import { type RepeatGroup, type ReviewNote, noteKey } from "./records.ts";
12
12
 
@@ -42,7 +42,7 @@ const unappliedCard = (state: State) => (extension: string, signals: readonly st
42
42
  };
43
43
 
44
44
  /** Step 1: the owner's notes from each source, saved once. Returns the ones this pass added. */
45
- export const collectNotes = async ({ state, config, comments, history, hunkOf }: LoopPass): Promise<ReviewNote[]> =>
45
+ const collectNotes = async ({ state, config, comments, history, hunkOf }: LoopPass): Promise<ReviewNote[]> =>
46
46
  saveNotes(state, [
47
47
  ...ownerNotes(await comments(sinceOfLastComment(state)), config.hum.ownerLogins),
48
48
  ...planChangingNotes(state.answers.list()),
@@ -51,15 +51,19 @@ export const collectNotes = async ({ state, config, comments, history, hunkOf }:
51
51
 
52
52
  /** Step 6: a landed check item whose name the next CI run's log shows. */
53
53
  export const confirmChecks = async ({ state, ciLogs, now }: Pick<LoopPass, "state" | "ciLogs" | "now">): Promise<void> => {
54
- for (const group of state.repeats.list()) {
54
+ const unconfirmed = state.repeats.list().flatMap((group) => {
55
55
  const merge = group.item === undefined ? undefined : state.merges.get(group.item);
56
56
 
57
- if (group.checked || !merge) continue;
57
+ return group.checked || !merge ? [] : [{ group, merge }];
58
+ });
58
59
 
59
- const logs = await ciLogs(merge.at);
60
+ await Promise.all(
61
+ unconfirmed.map(async ({ group, merge }) => {
62
+ const logs = await ciLogs(merge.at);
60
63
 
61
- if (logs.some((log) => logNames(log, group.key))) state.repeats.put(group.key, { ...group, checked: { at: now(), check: checkNameOf(group.key) } });
62
- }
64
+ if (logs.some((log) => doesLogName(log, group.key))) state.repeats.put(group.key, { ...group, checked: { at: now(), check: checkNameOf(group.key) } });
65
+ }),
66
+ );
63
67
  };
64
68
 
65
69
  const missesOf = (state: State, group: RepeatGroup): ReviewNote[] =>
@@ -69,11 +73,13 @@ const missesOf = (state: State, group: RepeatGroup): ReviewNote[] =>
69
73
  export const closeLoop = async ({ state, workSource, memoryPath }: Pick<LoopPass, "state" | "workSource" | "memoryPath">): Promise<void> => {
70
74
  const covered = new Set(state.repeats.list().flatMap((group) => (group.checked ? group.notes : [])));
71
75
 
72
- if (memoryPath !== undefined && covered.size > 0 && existsSync(memoryPath)) {
73
- const held = parseMemory(readFileSync(memoryPath, "utf8"));
74
- const kept = withoutCovered(held, covered);
76
+ const hasEntriesToDrop = memoryPath !== undefined && covered.size > 0 && existsSync(memoryPath);
77
+
78
+ if (hasEntriesToDrop) {
79
+ const text = readFileSync(memoryPath, "utf8");
80
+ const kept = withoutCovered(text, covered);
75
81
 
76
- if (kept.length < held.length) writeFileSync(memoryPath, renderMemory(kept));
82
+ if (kept !== text) writeFileSync(memoryPath, kept);
77
83
  }
78
84
 
79
85
  for (const group of state.repeats.list()) {
package/src/loop/proof.ts CHANGED
@@ -19,14 +19,15 @@ export type ProofOptions = {
19
19
  readonly now: () => number;
20
20
  };
21
21
 
22
- export type ProofResult = {
23
- readonly passed: boolean;
24
- readonly reason?: string;
22
+ /** What a proof cost. */
23
+ type ProofCost = {
25
24
  /** Worktrees made: one per note commit and one for the head. */
26
25
  readonly worktrees: number;
27
26
  readonly ms: number;
28
27
  };
29
28
 
29
+ export type ProofResult = ProofCost & ({ readonly passed: true } | { readonly passed: false; readonly reason: string });
30
+
30
31
  const isCommit = async (git: Git, sha: string): Promise<boolean> => (await git.run(["cat-file", "-e", `${sha}^{commit}`])).code === 0;
31
32
 
32
33
  /** The files the check item adds or changes against the base. */
@@ -56,13 +57,14 @@ export const proveCheck = async ({ git, head, base, notes, checks, timeoutMs, no
56
57
  const started = now();
57
58
  let worktrees = 0;
58
59
 
59
- const done = (reason?: string): ProofResult => ({ passed: reason === undefined, reason, worktrees, ms: now() - started });
60
+ const cost = (): ProofCost => ({ worktrees, ms: now() - started });
61
+ const failed = (reason: string): ProofResult => ({ passed: false, reason, ...cost() });
60
62
 
61
63
  const files = await checkFiles(git, base, head);
62
64
  const commits = [...new Set(notes.map(({ change }) => change))];
63
65
  const provable = (await Promise.all(commits.map(async (sha) => ((await isCommit(git, sha)) ? [sha] : [])))).flat();
64
66
 
65
- if (provable.length === 0) return done("no note points at a commit the check can run on");
67
+ if (provable.length === 0) return failed("no note points at a commit the check can run on");
66
68
 
67
69
  for (const sha of provable) {
68
70
  const failure = await inWorktreeAt(git, sha, async (folder) => {
@@ -72,7 +74,7 @@ export const proveCheck = async ({ git, head, base, notes, checks, timeoutMs, no
72
74
  return runChecks(checks, folder, { timeoutMs });
73
75
  });
74
76
 
75
- if (failure === undefined) return done(`the check passes on ${sha}, the commit a note points at`);
77
+ if (failure === undefined) return failed(`the check passes on ${sha}, the commit a note points at`);
76
78
  }
77
79
 
78
80
  const failure = await inWorktreeAt(git, head, async (folder) => {
@@ -81,5 +83,5 @@ export const proveCheck = async ({ git, head, base, notes, checks, timeoutMs, no
81
83
  return runChecks(checks, folder, { timeoutMs });
82
84
  });
83
85
 
84
- return failure === undefined ? done() : done(`the checks fail on the check item's own commit: ${failure.slice(0, 300)}`);
86
+ return failure === undefined ? { passed: true, ...cost() } : failed(`the checks fail on the check item's own commit: ${failure.slice(0, 300)}`);
85
87
  };
@@ -27,7 +27,7 @@ export const proveCheckItem = async ({ state, config, git, item, base, checks, n
27
27
  const head = (await git.raw(["rev-parse", "HEAD"])).trim();
28
28
  const proof = await proveCheck({ git, head, base: `origin/${base}`, notes, checks, timeoutMs: checksTimeoutMs(config.hum), now });
29
29
 
30
- state.proofs.put(item, { item, at: now(), passed: proof.passed, reason: proof.reason, worktrees: proof.worktrees, ms: proof.ms });
30
+ state.proofs.put(item, { item, at: now(), ...proof });
31
31
 
32
32
  return proof;
33
33
  };
@@ -4,12 +4,12 @@ const name = z.string().min(1);
4
4
  const time = z.int().nonnegative();
5
5
 
6
6
  /** Where a review note comes from. */
7
- export const NOTE_SOURCES = ["review-comment", "review-body", "plan-answer", "revert", "fix"] as const;
7
+ const NOTE_SOURCES = ["review-comment", "review-body", "plan-answer", "revert", "fix"] as const;
8
8
 
9
9
  export type NoteSource = (typeof NOTE_SOURCES)[number];
10
10
 
11
11
  /** One correction the owner made to hum's work, saved before anything acts on it and keyed by its source and source id. */
12
- export const ReviewNote = z.strictObject({
12
+ export const ReviewNote = z.object({
13
13
  source: z.enum(NOTE_SOURCES),
14
14
  sourceId: name,
15
15
  /** What the note is about: the commit a comment sits on, the change a revert or fix names, or the item a plan answer corrected. */
@@ -30,7 +30,7 @@ export type ReviewNote = z.infer<typeof ReviewNote>;
30
30
  export const noteKey = ({ source, sourceId }: Pick<ReviewNote, "source" | "sourceId">): string => `${source}:${sourceId}`;
31
31
 
32
32
  /** Notes that state one rule. The key is its first note's, so a later note joins instead of starting another group. */
33
- export const RepeatGroup = z.strictObject({
33
+ export const RepeatGroup = z.object({
34
34
  key: name,
35
35
  notes: z.array(name),
36
36
  /** The check item filed for the group. */
@@ -38,7 +38,7 @@ export const RepeatGroup = z.strictObject({
38
38
  /** Notes already added to the item's thread. */
39
39
  commented: z.array(name),
40
40
  /** The check landed and CI ran it. */
41
- checked: z.strictObject({ at: time, check: name }).optional(),
41
+ checked: z.object({ at: time, check: name }).optional(),
42
42
  /** Notes that came after the check ran in CI. */
43
43
  misses: z.array(name),
44
44
  });
@@ -46,30 +46,29 @@ export const RepeatGroup = z.strictObject({
46
46
  export type RepeatGroup = z.infer<typeof RepeatGroup>;
47
47
 
48
48
  /** Two notes only a model found alike, waiting for its precision to reach the owner's bar. */
49
- export const PossibleRepeat = z.strictObject({ a: name, b: name, models: z.array(name), at: time });
49
+ export const PossibleRepeat = z.object({ a: name, b: name, models: z.array(name), at: time });
50
50
 
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.strictObject({ item: name, sha: name, at: time, paths: z.array(name) });
54
+ export const Merge = z.object({ item: name, sha: name, at: time, paths: z.array(name) });
55
55
 
56
56
  export type Merge = z.infer<typeof Merge>;
57
57
 
58
58
  /** A test of the base that failed after an item's change merged. */
59
- export const Break = z.strictObject({ item: name, sha: name, at: time, paths: z.array(name), level: name, failure: z.string(), onBreak: z.enum(["follow-up", "block"]), followUp: name });
59
+ export const Break = z.object({ item: name, sha: name, at: time, paths: z.array(name), level: name, failure: z.string(), onBreak: z.enum(["follow-up", "block"]), followUp: name });
60
60
 
61
61
  export type Break = z.infer<typeof Break>;
62
62
 
63
- /** What proving a check cost: the commits it ran on, and the time it took. */
64
- export const Proof = z.strictObject({
63
+ const proofFields = {
65
64
  item: name,
66
65
  at: time,
67
- passed: z.boolean(),
68
- /** Why it failed, when it did. */
69
- reason: z.string().optional(),
70
66
  /** Worktrees made: one per note commit and one for the check's own head. */
71
67
  worktrees: z.int().nonnegative(),
72
68
  ms: z.int().nonnegative(),
73
- });
69
+ };
70
+
71
+ /** What proving a check cost: the commits it ran on, and the time it took; a failed proof says why. */
72
+ export const Proof = z.discriminatedUnion("passed", [z.object({ ...proofFields, passed: z.literal(true) }), z.object({ ...proofFields, passed: z.literal(false), reason: z.string() })]);
74
73
 
75
74
  export type Proof = z.infer<typeof Proof>;
@@ -48,7 +48,7 @@ const codePatternOf = (hunk: string): string =>
48
48
  .replace(/\s+/g, "");
49
49
 
50
50
  /** The glob that holds a file's folder and kind: its siblings of the same extension. */
51
- export const globOf = (file: string): string => `${dirname(file)}/*${extname(file)}`;
51
+ const globOf = (file: string): string => `${dirname(file)}/*${extname(file)}`;
52
52
 
53
53
  const parsedOf = (note: ReviewNote): { identifiers: Set<string>; declared: Set<string> } | undefined => {
54
54
  if (note.hunk === "") return { identifiers: new Set(), declared: new Set() };
@@ -91,7 +91,7 @@ export const prepare = (note: ReviewNote): Prepared => {
91
91
  };
92
92
  };
93
93
 
94
- const shares = <T>(a: Set<T> | undefined, b: Set<T> | undefined): boolean => a !== undefined && b !== undefined && [...a].some((found) => b.has(found));
94
+ const doShare = <T>(a: Set<T> | undefined, b: Set<T> | undefined): boolean => a !== undefined && b !== undefined && [...a].some((found) => b.has(found));
95
95
 
96
96
  /** Two notes on one change are about one hunk; only notes across changes repeat. */
97
97
  const isAnotherChange = (a: Prepared, b: Prepared): boolean => a.note.change !== b.note.change;
@@ -106,11 +106,11 @@ type Signal = {
106
106
  };
107
107
 
108
108
  /** The deterministic signals, checked in order. */
109
- export const SIGNALS: readonly Signal[] = [
109
+ const SIGNALS: readonly Signal[] = [
110
110
  { name: "same-text", parsed: false, pairs: (a, b) => a.text === b.text },
111
- { name: "same-code", parsed: false, pairs: (a, b) => shares(a.suggestions, b.suggestions) || shares(a.spans, b.spans) },
112
- { name: "shared-identifier", parsed: true, pairs: (a, b) => isAnotherChange(a, b) && shares(a.named, b.named) },
113
- { name: "same-glob-symbol", parsed: true, pairs: (a, b) => isAnotherChange(a, b) && a.glob !== undefined && a.glob === b.glob && shares(a.declared, b.declared) },
111
+ { name: "same-code", parsed: false, pairs: (a, b) => doShare(a.suggestions, b.suggestions) || doShare(a.spans, b.spans) },
112
+ { name: "shared-identifier", parsed: true, pairs: (a, b) => isAnotherChange(a, b) && doShare(a.named, b.named) },
113
+ { name: "same-glob-symbol", parsed: true, pairs: (a, b) => isAnotherChange(a, b) && a.glob !== undefined && a.glob === b.glob && doShare(a.declared, b.declared) },
114
114
  {
115
115
  name: "same-code-pattern",
116
116
  parsed: false,
@@ -1,10 +1,10 @@
1
1
  import type { State } from "../state/open.ts";
2
2
  import type { Counted } from "./measure.ts";
3
3
 
4
- /** Spent records of work outside any item carry this prefix. */
5
4
  /** The prefix of the op key every question to the owner is written under. */
6
5
  const QUESTION_OP = "question:";
7
6
 
7
+ /** Spent records of work outside any item carry this prefix. */
8
8
  export const LOOP_SPEND_PREFIX = "loop:";
9
9
 
10
10
  /** Reads what each item cost from what the engine saved: notes, question events and the item's token total. */
@@ -6,7 +6,7 @@ export type MergedChange = Counted & { readonly item: string; readonly at: numbe
6
6
  /** An item that never merged. Its cost counts all the same, so dropping work never lowers a number. */
7
7
  export type AbandonedItem = Counted & { readonly item: string; readonly since: number; readonly paths: readonly string[] };
8
8
 
9
- export type PerMerge = { readonly merges: number; readonly abandoned: number; readonly notes: number; readonly questions: number; readonly tokens: number };
9
+ type PerMerge = { readonly merges: number; readonly abandoned: number; readonly notes: number; readonly questions: number; readonly tokens: number };
10
10
 
11
11
  export type MeasureInput = {
12
12
  readonly merged: readonly MergedChange[];
@@ -47,7 +47,7 @@ const abandonedSince = (abandoned: readonly AbandonedItem[], inWindow: readonly
47
47
  return abandoned.filter(({ since }) => since >= start);
48
48
  };
49
49
 
50
- const touches = (glob: string, paths: readonly string[]): boolean => paths.some((path) => new Bun.Glob(glob).match(path));
50
+ const doesTouch = (glob: string, paths: readonly string[]): boolean => paths.some((path) => new Bun.Glob(glob).match(path));
51
51
 
52
52
  /**
53
53
  * The three numbers per merged change over the last `window` merged changes, and over each path's own last
@@ -59,9 +59,9 @@ export const measureOf = ({ merged, abandoned, loopTokens, window, globs }: Meas
59
59
  if (recent.length === 0) return undefined;
60
60
 
61
61
  const byPath = globs.flatMap((glob) => {
62
- const onPath = newestFirst(merged.filter(({ paths }) => touches(glob, paths)), window);
62
+ const onPath = newestFirst(merged.filter(({ paths }) => doesTouch(glob, paths)), window);
63
63
 
64
- return onPath.length === 0 ? [] : [{ glob, ...perMerge(onPath, abandonedSince(abandoned, onPath).filter(({ paths }) => touches(glob, paths)), 0) }];
64
+ return onPath.length === 0 ? [] : [{ glob, ...perMerge(onPath, abandonedSince(abandoned, onPath).filter(({ paths }) => doesTouch(glob, paths)), 0) }];
65
65
  });
66
66
 
67
67
  return { window, ...perMerge(recent, abandonedSince(abandoned, recent), loopTokens), byPath };
@@ -0,0 +1,2 @@
1
+ /** The share of measured cases a model got right; none when nothing was measured, so no rate stands in for a measurement. */
2
+ export const rateOf = (right: number, measured: number): number | undefined => (measured === 0 ? undefined : right / measured);
@@ -5,7 +5,7 @@ import { SECOND_MS } from "../time.ts";
5
5
  export const CI_TICK_REF = "refs/hum/ticks/ci";
6
6
 
7
7
  /** The scheduled workflow records its tick as an empty commit dated now, force-pushed to `CI_TICK_REF`. */
8
- export const recordCiTick = async (repo: string, remote: string, at: number, identity: GitIdentity, timeoutMs: number): Promise<void> => {
8
+ export const recordCiTick = async ({ repo, remote, at, identity, timeoutMs }: { readonly repo: string; readonly remote: string; readonly at: number; readonly identity: GitIdentity; readonly timeoutMs: number }): Promise<void> => {
9
9
  const when = `${Math.floor(at / SECOND_MS)} +0000`;
10
10
  const git = gitIn(repo, { identity, timeoutMs, env: { GIT_AUTHOR_DATE: when, GIT_COMMITTER_DATE: when } });
11
11
  const tree = (await git.raw(["hash-object", "-w", "-t", "tree", "/dev/null"])).trim();
@@ -15,7 +15,7 @@ export const recordCiTick = async (repo: string, remote: string, at: number, ide
15
15
  };
16
16
 
17
17
  /** The time of the last recorded tick, or undefined when the scheduled workflow has never run or the remote cannot be read. */
18
- export const readCiTick = async (repo: string, remote: string, timeoutMs: number): Promise<number | undefined> => {
18
+ export const readCiTick = async ({ repo, remote, timeoutMs }: { readonly repo: string; readonly remote: string; readonly timeoutMs: number }): Promise<number | undefined> => {
19
19
  const git = gitIn(repo, { timeoutMs });
20
20
 
21
21
  const fetched = await git.raw(["fetch", "--quiet", "--no-tags", remote, `+${CI_TICK_REF}:${CI_TICK_REF}`]).then(() => true, whenGitFailed(false));
@@ -41,7 +41,7 @@ type Card = ReturnType<(typeof CARD_KINDS)["workerSilent"]> | undefined;
41
41
 
42
42
  /** Shows `card` as the only worker-down card, or none; the status file is written here because no worker is there to write it. */
43
43
  const showWorkerDown = ({ faults, statusPath }: Supervision["state"], card: Card, now: number): void => {
44
- faults.clear(CARD_CODES.workerDown);
44
+ faults.clear({ code: CARD_CODES.workerDown });
45
45
 
46
46
  if (card) faults.raise(card);
47
47
 
@@ -62,7 +62,8 @@ const silenceOf = (quietSince: number, beat: { readonly time: number; readonly i
62
62
  return { quietSince: lastSeen, silentMs, isSilent: silentMs >= o.workerDownTicks * (beat?.intervalMs ?? o.intervalMs) };
63
63
  };
64
64
 
65
- const backoffFor = (crashes: number, { backoffMs, maxBackoffMs }: Pick<Supervision, "backoffMs" | "maxBackoffMs">): number => Math.min(backoffMs * 2 ** (crashes - 1), maxBackoffMs);
65
+ /** The pause before a restart once `crashes` crashes sit inside the window. */
66
+ export const backoffFor = (crashes: number, { backoffMs, maxBackoffMs }: Pick<Supervision, "backoffMs" | "maxBackoffMs">): number => Math.min(backoffMs * 2 ** (crashes - 1), maxBackoffMs);
66
67
 
67
68
  /**
68
69
  * The start script as a machine. It runs the worker and starts it again when it exits, looks at the heartbeat once
@@ -9,13 +9,13 @@ export const TOKEN_LIFE_DAYS = 365;
9
9
  export const UNAUTHORIZED = /API Error: 401|Failed to authenticate/i;
10
10
 
11
11
  /** One card on the first 401. Items wait where they are until the token is renewed. */
12
- export const rejectedToken = (faults: Faults, said: string) => faults.raise(CARD_KINDS.tokenRejected({ said }));
12
+ export const raiseRejectedToken = (faults: Faults, said: string) => faults.raise(CARD_KINDS.tokenRejected({ said }));
13
13
 
14
14
  /** One card from `warnDays` before the token's year ends; it clears when `setUp` moves to a later day. */
15
- export const checkTokenAge = (faults: Faults, setUp: string, now: number, warnDays: number): void => {
15
+ export const checkTokenAge = (faults: Faults, { setUp, now, warnDays }: { readonly setUp: string; readonly now: number; readonly warnDays: number }): void => {
16
16
  const expires = Date.parse(setUp) + TOKEN_LIFE_DAYS * DAY_MS;
17
17
 
18
- if (now < expires - warnDays * DAY_MS) return faults.clear(CARD_CODES.tokenExpiring);
18
+ if (now < expires - warnDays * DAY_MS) return faults.clear({ code: CARD_CODES.tokenExpiring });
19
19
 
20
20
  faults.raise(CARD_KINDS.tokenExpiring({ setUp, validUntil: new Date(expires).toISOString().slice(0, 10) }));
21
21
  };
@@ -23,8 +23,8 @@ const line = (card: Card): string => `${card.cause} ${card.fix}`;
23
23
  * Shows the cards where a CI job's reader looks: one error annotation each, and the job's step summary when the
24
24
  * runner gives one. The job's status file dies with the job, so this is the only place CI shows a card.
25
25
  */
26
- export const reportCards = async (cards: readonly Card[]): Promise<void> => {
26
+ export const reportCards = async (cards: readonly Card[], { hasStepSummary }: { readonly hasStepSummary: boolean }): Promise<void> => {
27
27
  for (const card of cards) core.error(line(card), { title: `hum ${card.code}` });
28
28
 
29
- if (process.env.GITHUB_STEP_SUMMARY && cards.length > 0) await core.summary.addHeading("hum", 2).addList(cards.map((card) => `${card.code}: ${line(card)}`)).write();
29
+ if (hasStepSummary && cards.length > 0) await core.summary.addHeading("hum", 2).addList(cards.map((card) => `${card.code}: ${line(card)}`)).write();
30
30
  };
@@ -1,31 +1,42 @@
1
- import { stringify } from "yaml";
1
+ import { Document, visit } from "yaml";
2
2
  import { CLAUDE_FLOOR } from "../adapters/claude-p.ts";
3
- import type { HumConfig } from "../config/schema.ts";
3
+ import type { HumConfig, PullRequestToken } from "../config/schema.ts";
4
+ import { APP_TOKEN_ACTION, CLAUDE_TOKEN, readsSecrets, secretsNamed, TRUSTED_ASSOCIATIONS, WAKE_ENV as ENV, WORKFLOW_FILES } from "../config/wake-job.ts";
4
5
 
5
6
  /** The settings the workflows are built from. */
6
- export type WorkflowSettings = Pick<HumConfig, "runBranchPrefix" | "itemsDir" | "ciSchedule" | "commitIdentity" | "ciWakeTimeoutMinutes" | "pullRequestTokenSecret">;
7
-
8
- export const WAKE_FILE = "hum-wake.yml";
7
+ export type WorkflowSettings = Pick<
8
+ HumConfig,
9
+ "runBranchPrefix" | "itemsDir" | "ciSchedule" | "commitIdentity" | "ciWakeTimeoutMinutes" | "pullRequestToken" | "ciRunner" | "ciContainer" | "ciEnv" | "ciClaudeAuth"
10
+ >;
9
11
 
10
12
  /** The type of the `repository_dispatch` event a tracker's webhook sends. */
11
- export const DISPATCH_EVENT = "hum-wake";
12
-
13
- const WAKE_PATH = `./.github/workflows/${WAKE_FILE}`;
13
+ const DISPATCH_EVENT = "hum-wake";
14
14
 
15
- const TOKEN_SECRET = "CLAUDE_CODE_OAUTH_TOKEN";
15
+ const WAKE_PATH = `./.github/workflows/${WORKFLOW_FILES.wake}`;
16
16
 
17
17
  const HOPE_MARKETPLACE = "saadshahd/moo.md";
18
18
 
19
19
  /** The Bun that builds the workflows is the one the owner's repo runs, so CI installs with the same lockfile reader. */
20
20
  const BUN_VERSION = Bun.version;
21
21
 
22
- const ACTIONS = { checkout: "actions/checkout@v4", setupBun: "oven-sh/setup-bun@v2" } as const;
22
+ /**
23
+ * Each action the workflows run, at the one commit its release is. A tag can move to code that then holds the App's
24
+ * private key and every secret of the job; a commit cannot. The release rides beside the commit as a comment.
25
+ */
26
+ const ACTIONS = {
27
+ checkout: { uses: "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1", release: "v7.0.1" },
28
+ appToken: { uses: `${APP_TOKEN_ACTION}@64ab729a6294000f5aa4a4bc0b73d1f32bc45510`, release: "v3.3.0" },
29
+ } as const;
30
+
31
+ const RELEASE_OF: ReadonlyMap<string, string> = new Map(Object.values(ACTIONS).map(({ uses, release }) => [uses, release]));
23
32
 
24
33
  const PERMISSIONS = { contents: "write", issues: "write", "pull-requests": "write" } as const;
25
34
 
26
35
  /** One wake at a time: a second event waits for the first run instead of racing it. */
27
36
  const CONCURRENCY = { group: "hum-wake", "cancel-in-progress": false } as const;
28
37
 
38
+ const APP_TOKEN_STEP = "app-token";
39
+
29
40
  /** The events a trigger workflow starts on. */
30
41
  type TriggerEvents = {
31
42
  readonly issue_comment?: { readonly types: readonly string[] };
@@ -46,52 +57,158 @@ const trigger = (name: string, on: TriggerEvents, job: TriggerJob = {}) => ({
46
57
  jobs: { wake: { ...job, uses: WAKE_PATH, secrets: "inherit" } },
47
58
  });
48
59
 
60
+ const secret = (name: string): string => `\${{ secrets.${name} }}`;
61
+
62
+ /** The inputs that give an App's token the workflow's own permissions, each written out as the action names it. */
63
+ const APP_TOKEN_PERMISSIONS = {
64
+ "permission-contents": PERMISSIONS.contents,
65
+ "permission-issues": PERMISSIONS.issues,
66
+ "permission-pull-requests": PERMISSIONS["pull-requests"],
67
+ } as const;
68
+
69
+ /** Where the job keeps what would else be machine-wide: a runner GitHub does not host keeps its home folder between jobs, and empties its temp folder after each. */
70
+ const JOB_TOOLS = "$RUNNER_TEMP/hum-tools";
71
+
72
+ /** Later steps read git's global config from the job's temp folder and find the job's own tools first on PATH. */
73
+ const JOB_PATHS_STEP = {
74
+ run: `echo "${ENV.gitConfig}=$RUNNER_TEMP/hum-gitconfig" >> "$GITHUB_ENV"
75
+ echo "${JOB_TOOLS}/bin" >> "$GITHUB_PATH"
76
+ `,
77
+ } as const;
78
+
79
+ /** The YAML writer leaves out a key whose value is undefined, so a job that runs on the runner itself has no `container`. */
80
+ const NO_KEY = undefined;
81
+
82
+ const OPTIONAL_SECRET = { required: false } as const;
83
+
84
+ /** The secrets the owner's settings name. A called workflow reads only the secrets it declares, so each is declared, and none is required. */
85
+ const ownerSecrets = ({ ciRunner, ciContainer, ciEnv }: Pick<WorkflowSettings, "ciRunner" | "ciContainer" | "ciEnv">) =>
86
+ Object.fromEntries(secretsNamed(ciRunner, ciContainer, ciEnv).map((name) => [name, OPTIONAL_SECRET]));
87
+
88
+ /** `ciEnv` split by reach: a value that reads a secret goes to the step that runs hum alone, so no install step holds it. */
89
+ const envByReach = (ciEnv: WorkflowSettings["ciEnv"]) => ({
90
+ everyStep: Object.fromEntries(Object.entries(ciEnv).filter(([, value]) => !readsSecrets(value))),
91
+ humStep: Object.fromEntries(Object.entries(ciEnv).filter(([, value]) => readsSecrets(value))),
92
+ });
93
+
94
+ /** The secret and env Claude Code signs in with: the OAuth token, or none where `ciEnv` carries the credentials. */
95
+ const CLAUDE_SIGN_IN = {
96
+ "oauth-token": { secrets: { [CLAUDE_TOKEN]: { required: true } }, env: { [CLAUDE_TOKEN]: secret(CLAUDE_TOKEN) } },
97
+ env: { secrets: {}, env: {} },
98
+ } as const satisfies Record<HumConfig["ciClaudeAuth"], { readonly secrets: object; readonly env: object }>;
99
+
49
100
  /**
50
- * The job every wake runs. A run clones the repo again into a temp folder, so the git credentials and identity are
51
- * global: the checkout's own are local to its workspace. A run that needs the owner has pushed its run branch, asked
52
- * on the item and ended; the owner's answer starts a fresh run on that branch, so no session, artifact or approval
53
- * is kept between runs.
101
+ * The secrets a wake's GitHub token comes from, the env and steps that turn them into it, and the expression that
102
+ * holds it. An App's token is minted with the workflow token's permissions, so both hold the same rights.
54
103
  */
55
- const wake = ({ commitIdentity, ciWakeTimeoutMinutes, pullRequestTokenSecret }: WorkflowSettings) => ({
56
- name: "hum wake",
57
- on: { workflow_call: { secrets: { [TOKEN_SECRET]: { required: true }, [pullRequestTokenSecret]: { required: false } } } },
58
- permissions: PERMISSIONS,
59
- jobs: {
60
- wake: {
61
- "runs-on": "ubuntu-latest",
62
- "timeout-minutes": ciWakeTimeoutMinutes,
63
- env: {
64
- [TOKEN_SECRET]: `\${{ secrets.${TOKEN_SECRET} }}`,
65
- GH_TOKEN: `\${{ secrets.${pullRequestTokenSecret} || github.token }}`,
66
- HUM_EVENT: "${{ github.event_name }}",
67
- },
68
- steps: [
69
- { uses: ACTIONS.checkout, with: { "fetch-depth": 0 } },
70
- { uses: ACTIONS.setupBun, with: { "bun-version": BUN_VERSION } },
71
- { run: "bun install --frozen-lockfile" },
72
- { run: `npm install --global @anthropic-ai/claude-code@${CLAUDE_FLOOR}` },
73
- { run: `claude plugin marketplace add ${HOPE_MARKETPLACE}\nclaude plugin install hope@moo.md\n` },
74
- { run: "gh auth setup-git" },
75
- {
76
- run: 'git config --global user.name "$HUM_GIT_NAME"\ngit config --global user.email "$HUM_GIT_EMAIL"\n',
77
- env: { HUM_GIT_NAME: commitIdentity.name, HUM_GIT_EMAIL: commitIdentity.email },
78
- },
79
- { run: './node_modules/.bin/hum wake --event "$HUM_EVENT"' },
80
- ],
81
- },
104
+ const githubToken = (source: PullRequestToken) =>
105
+ source.from === "secret"
106
+ ? { secrets: { [source.secret]: OPTIONAL_SECRET }, env: {}, steps: [], token: `\${{ secrets.${source.secret} || github.token }}` }
107
+ : {
108
+ secrets: { [source.clientIdSecret]: OPTIONAL_SECRET, [source.privateKeySecret]: OPTIONAL_SECRET },
109
+ env: { [ENV.hasApp]: `\${{ secrets.${source.clientIdSecret} != '' }}` },
110
+ steps: [
111
+ {
112
+ id: APP_TOKEN_STEP,
113
+ if: `env.${ENV.hasApp} == 'true'`,
114
+ uses: ACTIONS.appToken.uses,
115
+ with: {
116
+ "client-id": secret(source.clientIdSecret),
117
+ "private-key": secret(source.privateKeySecret),
118
+ ...APP_TOKEN_PERMISSIONS,
119
+ },
120
+ },
121
+ ],
122
+ token: `\${{ steps.${APP_TOKEN_STEP}.outputs.token || github.token }}`,
123
+ };
124
+
125
+ /**
126
+ * A run clones the repo again into a temp folder, so the git identity and credentials are global: the checkout's own
127
+ * are local to its workspace. Global here is the job's own file, which `JOB_PATHS_STEP` names, so no other job on the
128
+ * machine commits as hum. The credential helper hands git the token in the env when git asks, so git needs no `gh`,
129
+ * which a job container may lack. In a job container the runner's user may own the checkout while the steps run as
130
+ * root, and git refuses a repo another user owns until it is trusted.
131
+ */
132
+ const gitSetup = ({ name, email }: HumConfig["commitIdentity"]) => ({
133
+ run: `git config --global user.name "$${ENV.gitName}"
134
+ git config --global user.email "$${ENV.gitEmail}"
135
+ git config --global credential.https://github.com.helper "$${ENV.gitCredentialHelper}"
136
+ git config --global --add safe.directory "$GITHUB_WORKSPACE"
137
+ `,
138
+ env: {
139
+ [ENV.gitName]: name,
140
+ [ENV.gitEmail]: email,
141
+ [ENV.gitCredentialHelper]: `!f() { if [ "$1" = get ]; then echo username=x-access-token; echo "password=$${ENV.githubToken}"; fi; }; f`,
82
142
  },
83
143
  });
84
144
 
145
+ /**
146
+ * The job every wake runs. A run that needs the owner has pushed its run branch, asked on the item and ended; the
147
+ * owner's answer starts a fresh run on that branch, so no session, artifact or approval is kept between runs. Bun and
148
+ * Claude Code install through npm into the job's temp folder, so the job needs only git, node and npm from its runner
149
+ * or container, and leaves nothing on a machine that outlives it. The Claude sign-in, the GitHub token and every
150
+ * `ciEnv` value that reads a secret reach the last step alone. An App's token lasts an hour, so it is minted last.
151
+ */
152
+ const wake = ({ commitIdentity, ciWakeTimeoutMinutes, pullRequestToken, ciRunner, ciContainer, ciEnv, ciClaudeAuth }: WorkflowSettings) => {
153
+ const claude = CLAUDE_SIGN_IN[ciClaudeAuth];
154
+ const github = githubToken(pullRequestToken);
155
+ const env = envByReach(ciEnv);
156
+
157
+ return {
158
+ name: "hum wake",
159
+ on: { workflow_call: { secrets: { ...ownerSecrets({ ciRunner, ciContainer, ciEnv }), ...claude.secrets, ...github.secrets } } },
160
+ permissions: PERMISSIONS,
161
+ jobs: {
162
+ wake: {
163
+ "runs-on": ciRunner,
164
+ container: ciContainer ?? NO_KEY,
165
+ "timeout-minutes": ciWakeTimeoutMinutes,
166
+ env: { ...env.everyStep, ...github.env, [ENV.event]: "${{ github.event_name }}" },
167
+ steps: [
168
+ { uses: ACTIONS.checkout.uses, with: { "fetch-depth": 0 } },
169
+ JOB_PATHS_STEP,
170
+ { run: `npm install --global --prefix "${JOB_TOOLS}" bun@${BUN_VERSION} @anthropic-ai/claude-code@${CLAUDE_FLOOR}` },
171
+ { run: "bun install --frozen-lockfile" },
172
+ { run: `claude plugin marketplace add ${HOPE_MARKETPLACE}\nclaude plugin install hope@moo.md\n` },
173
+ gitSetup(commitIdentity),
174
+ ...github.steps,
175
+ { run: `./node_modules/.bin/hum wake --event "$${ENV.event}"`, env: { ...env.humStep, ...claude.env, [ENV.githubToken]: github.token } },
176
+ ],
177
+ },
178
+ },
179
+ };
180
+ };
181
+
182
+ /** A comment wakes hum only when a person the repo trusts wrote it: on a public repo anyone may comment, and a wake holds every secret. */
183
+ const TRUSTED_COMMENT = `github.event.comment.user.type != 'Bot' && contains(fromJSON('${JSON.stringify(TRUSTED_ASSOCIATIONS)}'), github.event.comment.author_association)`;
184
+
185
+ type Workflow = ReturnType<typeof wake> | ReturnType<typeof trigger>;
186
+
187
+ /** A workflow as YAML, each pinned action followed by its release as a comment, and a value two keys share written out under both. */
188
+ const render = (workflow: Workflow): string => {
189
+ const document = new Document(workflow, { aliasDuplicateObjects: false });
190
+
191
+ visit(document, {
192
+ Scalar: (_key, node) => {
193
+ const release = RELEASE_OF.get(String(node.value));
194
+
195
+ if (release !== undefined) node.comment = ` ${release}`;
196
+ },
197
+ });
198
+
199
+ return document.toString({ lineWidth: 0 });
200
+ };
201
+
85
202
  const WORKFLOWS = {
86
- [WAKE_FILE]: wake,
87
- "hum-comment.yml": () => trigger("hum on comment", { issue_comment: { types: ["created"] } }, { if: "github.event.comment.user.type != 'Bot'" }),
88
- "hum-push.yml": ({ itemsDir, runBranchPrefix }) => trigger("hum on item push", { push: { branches: ["**", `!${runBranchPrefix}**`], paths: [`${itemsDir}/**`] } }),
89
- "hum-dispatch.yml": () => trigger("hum on dispatch", { repository_dispatch: { types: [DISPATCH_EVENT] } }),
90
- "hum-schedule.yml": ({ ciSchedule }) => trigger("hum on schedule", { schedule: [{ cron: ciSchedule }], workflow_dispatch: null }),
91
- } as const satisfies Record<string, (settings: WorkflowSettings) => object>;
203
+ [WORKFLOW_FILES.wake]: wake,
204
+ [WORKFLOW_FILES.comment]: () => trigger("hum on comment", { issue_comment: { types: ["created"] } }, { if: TRUSTED_COMMENT }),
205
+ [WORKFLOW_FILES.push]: ({ itemsDir, runBranchPrefix }) => trigger("hum on item push", { push: { branches: ["**", `!${runBranchPrefix}**`], paths: [`${itemsDir}/**`] } }),
206
+ [WORKFLOW_FILES.dispatch]: () => trigger("hum on dispatch", { repository_dispatch: { types: [DISPATCH_EVENT] } }),
207
+ [WORKFLOW_FILES.schedule]: ({ ciSchedule }) => trigger("hum on schedule", { schedule: [{ cron: ciSchedule }], workflow_dispatch: null }),
208
+ } as const satisfies Record<(typeof WORKFLOW_FILES)[keyof typeof WORKFLOW_FILES], (settings: WorkflowSettings) => object>;
92
209
 
93
210
  export type WorkflowFile = { readonly file: string; readonly text: string };
94
211
 
95
212
  /** The workflow files for an owner's repo, each named for `.github/workflows/`. */
96
213
  export const ciWorkflows = (settings: WorkflowSettings): WorkflowFile[] =>
97
- Object.entries(WORKFLOWS).map(([file, build]) => ({ file, text: stringify(build(settings), { lineWidth: 0 }) }));
214
+ Object.entries(WORKFLOWS).map(([file, build]) => ({ file, text: render(build(settings)) }));