@moo.md/hum 0.0.0-stage → 0.1.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 (150) hide show
  1. package/defaults/hum.json +321 -0
  2. package/defaults/kinds/check.json +183 -0
  3. package/defaults/kinds/docs.json +151 -0
  4. package/defaults/kinds/feature.json +202 -0
  5. package/defaults/kinds/fix.json +183 -0
  6. package/defaults/kinds/hotfix.json +164 -0
  7. package/defaults/roles/build.md +3 -0
  8. package/defaults/roles/fix.md +1 -0
  9. package/defaults/roles/plan.md +3 -0
  10. package/defaults/roles/review.md +3 -0
  11. package/evals/alignment/RESULTS.md +8 -0
  12. package/evals/alignment/cases.jsonl +128 -0
  13. package/evals/alignment/sample.jsonl +20 -0
  14. package/evals/kind/RESULTS.md +5 -0
  15. package/evals/kind/cases.jsonl +24 -0
  16. package/evals/plan-outcome/RESULTS.md +4 -0
  17. package/evals/plan-outcome/cases.jsonl +12 -0
  18. package/evals/repeat-pair/RESULTS.md +4 -0
  19. package/evals/repeat-pair/cases.jsonl +51 -0
  20. package/evals/reply-option/RESULTS.md +3 -0
  21. package/evals/reply-option/cases.jsonl +45 -0
  22. package/evals/review-verdict/RESULTS.md +4 -0
  23. package/evals/review-verdict/cases.jsonl +12 -0
  24. package/package.json +88 -4
  25. package/schema/hum.schema.json +1355 -0
  26. package/scripts/eval.ts +244 -0
  27. package/src/adapter-api.ts +134 -0
  28. package/src/adapters/admit.ts +111 -0
  29. package/src/adapters/argument.ts +11 -0
  30. package/src/adapters/claim.ts +93 -0
  31. package/src/adapters/claude-bg.ts +392 -0
  32. package/src/adapters/claude-p.ts +599 -0
  33. package/src/adapters/contract.ts +231 -0
  34. package/src/adapters/fake.ts +157 -0
  35. package/src/adapters/git.ts +156 -0
  36. package/src/adapters/github.ts +479 -0
  37. package/src/adapters/guard.ts +152 -0
  38. package/src/adapters/history.ts +215 -0
  39. package/src/adapters/item-file.ts +102 -0
  40. package/src/adapters/limit.ts +67 -0
  41. package/src/adapters/markdown.ts +365 -0
  42. package/src/adapters/marked.ts +127 -0
  43. package/src/adapters/model-call.ts +75 -0
  44. package/src/adapters/once.ts +45 -0
  45. package/src/adapters/owner-commit.ts +60 -0
  46. package/src/adapters/pull-requests.ts +253 -0
  47. package/src/adapters/registry.ts +156 -0
  48. package/src/adapters/roundup.ts +293 -0
  49. package/src/adapters/serial.ts +22 -0
  50. package/src/adapters/transcript.ts +99 -0
  51. package/src/cli/commands.ts +46 -0
  52. package/src/cli/main.ts +8 -0
  53. package/src/cli/ops.ts +224 -0
  54. package/src/cli/service.ts +156 -0
  55. package/src/cli/setup.ts +141 -0
  56. package/src/cli/shared-watch.ts +127 -0
  57. package/src/config/change.ts +54 -0
  58. package/src/config/checks.ts +217 -0
  59. package/src/config/git-ref-name.d.ts +3 -0
  60. package/src/config/hash.ts +6 -0
  61. package/src/config/json.ts +6 -0
  62. package/src/config/load.ts +88 -0
  63. package/src/config/machine.ts +20 -0
  64. package/src/config/migrate.ts +61 -0
  65. package/src/config/refusal.ts +58 -0
  66. package/src/config/schema.ts +465 -0
  67. package/src/config/settings.ts +6 -0
  68. package/src/config/state-map.ts +76 -0
  69. package/src/decide/alignment.ts +79 -0
  70. package/src/decide/answer.ts +131 -0
  71. package/src/decide/kind.ts +39 -0
  72. package/src/decide/labels.ts +137 -0
  73. package/src/decide/merge.ts +102 -0
  74. package/src/decide/prose.ts +109 -0
  75. package/src/decide/question.ts +159 -0
  76. package/src/decide/review.ts +10 -0
  77. package/src/decide/risk.ts +216 -0
  78. package/src/decide/taste.ts +37 -0
  79. package/src/exec.ts +85 -0
  80. package/src/index.ts +200 -0
  81. package/src/loop/breaks.ts +8 -0
  82. package/src/loop/check-item.ts +76 -0
  83. package/src/loop/ci.ts +8 -0
  84. package/src/loop/github.ts +81 -0
  85. package/src/loop/groups.ts +108 -0
  86. package/src/loop/memory.ts +70 -0
  87. package/src/loop/notes.ts +76 -0
  88. package/src/loop/pair.ts +39 -0
  89. package/src/loop/pass.ts +99 -0
  90. package/src/loop/proof.ts +85 -0
  91. package/src/loop/prove-item.ts +33 -0
  92. package/src/loop/records.ts +75 -0
  93. package/src/loop/signals.ts +130 -0
  94. package/src/measure/inputs.ts +28 -0
  95. package/src/measure/measure.ts +68 -0
  96. package/src/service/cards.ts +24 -0
  97. package/src/service/ci-tick.ts +28 -0
  98. package/src/service/launchd.ts +16 -0
  99. package/src/service/supervise.ts +145 -0
  100. package/src/service/systemd.ts +44 -0
  101. package/src/service/token.ts +21 -0
  102. package/src/service/unit.ts +29 -0
  103. package/src/service/wake.ts +30 -0
  104. package/src/service/workflows.ts +97 -0
  105. package/src/setup/propose.ts +120 -0
  106. package/src/setup/prove.ts +216 -0
  107. package/src/setup/scan.ts +186 -0
  108. package/src/setup/scratch.ts +81 -0
  109. package/src/setup/shipped.ts +15 -0
  110. package/src/setup/tables.ts +101 -0
  111. package/src/setup/waits.ts +58 -0
  112. package/src/setup/write.ts +161 -0
  113. package/src/slots/env.ts +42 -0
  114. package/src/slots/pool.ts +329 -0
  115. package/src/slots/scan.ts +26 -0
  116. package/src/slots/worktree.ts +17 -0
  117. package/src/state/events.ts +52 -0
  118. package/src/state/faults.ts +73 -0
  119. package/src/state/format.ts +50 -0
  120. package/src/state/fs.ts +100 -0
  121. package/src/state/items.ts +195 -0
  122. package/src/state/open.ts +80 -0
  123. package/src/state/ops.ts +76 -0
  124. package/src/state/records.ts +35 -0
  125. package/src/state/runs.ts +99 -0
  126. package/src/state/saved.ts +119 -0
  127. package/src/status/file.ts +49 -0
  128. package/src/status/format.ts +132 -0
  129. package/src/status/sections.ts +14 -0
  130. package/src/status/version.ts +2 -0
  131. package/src/time.ts +7 -0
  132. package/src/worker/alignment-report.ts +18 -0
  133. package/src/worker/answers.ts +153 -0
  134. package/src/worker/base-check.ts +45 -0
  135. package/src/worker/checks.ts +40 -0
  136. package/src/worker/kind.ts +68 -0
  137. package/src/worker/land.ts +509 -0
  138. package/src/worker/lifecycle.ts +97 -0
  139. package/src/worker/merged.ts +29 -0
  140. package/src/worker/open.ts +100 -0
  141. package/src/worker/prose-run.ts +56 -0
  142. package/src/worker/questions.ts +89 -0
  143. package/src/worker/scheduler.ts +135 -0
  144. package/src/worker/signature.ts +41 -0
  145. package/src/worker/tally.ts +25 -0
  146. package/src/worker/taste.ts +38 -0
  147. package/src/worker/thin-path.ts +886 -0
  148. package/src/worker/worker.ts +750 -0
  149. package/surface.json +8787 -0
  150. package/README.md +0 -3
@@ -0,0 +1,130 @@
1
+ import { dirname, extname } from "node:path";
2
+ import { Lang, parse } from "@ast-grep/napi";
3
+ import type { ReviewNote } from "./records.ts";
4
+
5
+ /** The languages whose hunks the parser reads. A hunk in any other language leaves the signals that need a parse unapplied. */
6
+ const PARSED_LANGUAGES = new Map<string, Lang>([
7
+ [".ts", Lang.TypeScript],
8
+ [".tsx", Lang.Tsx],
9
+ [".js", Lang.JavaScript],
10
+ [".jsx", Lang.JavaScript],
11
+ [".mjs", Lang.JavaScript],
12
+ [".cjs", Lang.JavaScript],
13
+ ]);
14
+
15
+ const IDENTIFIER_KINDS = ["identifier", "property_identifier", "type_identifier"] as const;
16
+
17
+ const DECLARATION_KINDS = ["function_declaration", "class_declaration", "interface_declaration", "type_alias_declaration", "enum_declaration", "method_definition", "variable_declarator", "public_field_definition", "property_signature"] as const;
18
+
19
+ const WORD = /[A-Za-z_$][\w$]*/g;
20
+ const CODE_SPAN = /`([^`\n]+)`/g;
21
+ const SUGGESTION_BLOCK = /```suggestion\n([\s\S]*?)```/g;
22
+ const STRING_LITERAL = /(["'`])(?:\\.|(?!\1).)*\1/g;
23
+ const NUMBER_LITERAL = /\b\d+(?:\.\d+)?\b/g;
24
+ const HUNK_HEADER = /^(@@|diff |index |--- |\+\+\+ )/;
25
+ const CHANGED_LINE = /^[+-]/;
26
+ const KEYWORDS = new Set(["const", "let", "var", "function", "return", "if", "else", "new", "await", "async", "export", "import", "from", "type", "interface", "class", "extends", "this", "true", "false", "null", "undefined", "typeof", "for", "of", "in"]);
27
+
28
+ /** A one-character word names nothing, so two notes quoting it say nothing alike. */
29
+ const MIN_WORD_LENGTH = 3;
30
+
31
+ const squash = (text: string): string => text.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, " ").replace(/\s+/g, " ").trim();
32
+
33
+ const bodyLines = (hunk: string): string[] => hunk.split("\n").filter((line) => !HUNK_HEADER.test(line));
34
+
35
+ const codeOf = (hunk: string): string => bodyLines(hunk).map((line) => line.slice(1)).join("\n");
36
+
37
+ const changedCodeOf = (hunk: string): string => bodyLines(hunk).flatMap((line) => (CHANGED_LINE.test(line) ? [line.slice(1)] : [])).join("\n");
38
+
39
+ const wordsOf = (text: string): Set<string> => new Set((text.match(WORD) ?? []).filter((word) => word.length >= MIN_WORD_LENGTH));
40
+
41
+ const matchesOf = (pattern: RegExp, text: string): Set<string> => new Set([...text.matchAll(pattern)].flatMap(([, found = ""]) => squash(found) || []));
42
+
43
+ const codePatternOf = (hunk: string): string =>
44
+ changedCodeOf(hunk)
45
+ .replace(STRING_LITERAL, "S")
46
+ .replace(NUMBER_LITERAL, "N")
47
+ .replace(WORD, (word) => (KEYWORDS.has(word) ? word : "I"))
48
+ .replace(/\s+/g, "");
49
+
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)}`;
52
+
53
+ const parsedOf = (note: ReviewNote): { identifiers: Set<string>; declared: Set<string> } | undefined => {
54
+ if (note.hunk === "") return { identifiers: new Set(), declared: new Set() };
55
+
56
+ const lang = PARSED_LANGUAGES.get(extname(note.file ?? ""));
57
+
58
+ if (lang === undefined) return undefined;
59
+
60
+ const identifiersIn = (code: string) => parse(lang, code).root().findAll({ rule: { any: IDENTIFIER_KINDS.map((kind) => ({ kind })) } }).map((node) => node.text());
61
+ const declaredIn = (code: string) => parse(lang, code).root().findAll({ rule: { any: DECLARATION_KINDS.map((kind) => ({ kind })) } }).flatMap((node) => node.field("name")?.text() ?? []);
62
+
63
+ return { identifiers: new Set(identifiersIn(codeOf(note.hunk))), declared: new Set(declaredIn(changedCodeOf(note.hunk))) };
64
+ };
65
+
66
+ /** What the signals compare, read once from a note. */
67
+ export type Prepared = {
68
+ readonly note: ReviewNote;
69
+ readonly text: string;
70
+ readonly suggestions: Set<string>;
71
+ readonly spans: Set<string>;
72
+ /** Identifiers the note's text names that its own hunk holds. `undefined` when the hunk cannot be parsed. */
73
+ readonly named: Set<string> | undefined;
74
+ readonly declared: Set<string> | undefined;
75
+ readonly glob: string | undefined;
76
+ readonly pattern: string;
77
+ };
78
+
79
+ export const prepare = (note: ReviewNote): Prepared => {
80
+ const parsed = parsedOf(note);
81
+
82
+ return {
83
+ note,
84
+ text: squash(note.text),
85
+ suggestions: matchesOf(SUGGESTION_BLOCK, note.text),
86
+ spans: new Set([...matchesOf(CODE_SPAN, note.text)].filter((span) => span.length >= MIN_WORD_LENGTH)),
87
+ named: parsed && new Set([...wordsOf(note.text)].filter((word) => parsed.identifiers.has(word))),
88
+ declared: parsed?.declared,
89
+ glob: note.file === undefined ? undefined : globOf(note.file),
90
+ pattern: codePatternOf(note.hunk),
91
+ };
92
+ };
93
+
94
+ const shares = <T>(a: Set<T> | undefined, b: Set<T> | undefined): boolean => a !== undefined && b !== undefined && [...a].some((found) => b.has(found));
95
+
96
+ /** Two notes on one change are about one hunk; only notes across changes repeat. */
97
+ const isAnotherChange = (a: Prepared, b: Prepared): boolean => a.note.change !== b.note.change;
98
+
99
+ const BREAK_SOURCES: readonly ReviewNote["source"][] = ["revert", "fix"];
100
+
101
+ type Signal = {
102
+ readonly name: string;
103
+ /** The signal reads a parsed hunk: it is left unapplied for a note whose hunk is not in a parsed language. */
104
+ readonly parsed: boolean;
105
+ readonly pairs: (a: Prepared, b: Prepared) => boolean;
106
+ };
107
+
108
+ /** The deterministic signals, checked in order. */
109
+ export const SIGNALS: readonly Signal[] = [
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) },
114
+ {
115
+ name: "same-code-pattern",
116
+ parsed: false,
117
+ pairs: (a, b) => BREAK_SOURCES.includes(a.note.source) && BREAK_SOURCES.includes(b.note.source) && a.pattern !== "" && a.pattern === b.pattern,
118
+ },
119
+ ];
120
+
121
+ /** The first signal that pairs two notes, and the signals a note's language left unapplied. */
122
+ export type Pairing = { readonly signal?: string; readonly unapplied: readonly string[] };
123
+
124
+ export const pairing = (a: Prepared, b: Prepared): Pairing => {
125
+ const canRead = (signal: Signal): boolean => !signal.parsed || (a.named !== undefined && b.named !== undefined);
126
+ const unapplied = SIGNALS.flatMap((signal) => (canRead(signal) ? [] : [signal.name]));
127
+ const found = SIGNALS.find((signal) => canRead(signal) && signal.pairs(a, b));
128
+
129
+ return { signal: found?.name, unapplied };
130
+ };
@@ -0,0 +1,28 @@
1
+ import type { State } from "../state/open.ts";
2
+ import type { Counted } from "./measure.ts";
3
+
4
+ /** Spent records of work outside any item carry this prefix. */
5
+ /** The prefix of the op key every question to the owner is written under. */
6
+ const QUESTION_OP = "question:";
7
+
8
+ export const LOOP_SPEND_PREFIX = "loop:";
9
+
10
+ /** Reads what each item cost from what the engine saved: notes, question events and the item's token total. */
11
+ export const measureInputsOf = (state: State) => {
12
+ const merges = state.merges.list();
13
+ const notes = state.notes.list();
14
+ const spent = state.spent.list();
15
+ const asked = state.ops.list().filter(({ op, state: done }) => op.startsWith(QUESTION_OP) && done === "done");
16
+
17
+ const costOf = (item: string, shas: readonly string[]): Counted => ({
18
+ notes: notes.filter((note) => note.item === item || shas.includes(note.change)).length,
19
+ questions: asked.filter((found) => found.itemId === item).length,
20
+ tokens: spent.find((found) => found.item === item)?.total ?? 0,
21
+ });
22
+
23
+ return {
24
+ merged: merges.map(({ item, sha, at, paths }) => ({ item, at, paths, ...costOf(item, [sha]) })),
25
+ abandoned: state.parked.list().flatMap(({ item, why, since }) => (why === "stuck" && !merges.some((merge) => merge.item === item) ? [{ item, since, paths: [], ...costOf(item, []) }] : [])),
26
+ loopTokens: spent.filter(({ item }) => item.startsWith(LOOP_SPEND_PREFIX)).reduce((total, { total: tokens }) => total + tokens, 0),
27
+ };
28
+ };
@@ -0,0 +1,68 @@
1
+ /** What an item cost the owner: review notes, questions, and model tokens. */
2
+ export type Counted = { readonly notes: number; readonly questions: number; readonly tokens: number };
3
+
4
+ export type MergedChange = Counted & { readonly item: string; readonly at: number; readonly paths: readonly string[] };
5
+
6
+ /** An item that never merged. Its cost counts all the same, so dropping work never lowers a number. */
7
+ export type AbandonedItem = Counted & { readonly item: string; readonly since: number; readonly paths: readonly string[] };
8
+
9
+ export type PerMerge = { readonly merges: number; readonly abandoned: number; readonly notes: number; readonly questions: number; readonly tokens: number };
10
+
11
+ export type MeasureInput = {
12
+ readonly merged: readonly MergedChange[];
13
+ readonly abandoned: readonly AbandonedItem[];
14
+ /** Tokens spent outside any item, such as comparing review notes. */
15
+ readonly loopTokens: number;
16
+ readonly window: number;
17
+ /** Path globs that each get their own numbers over their own last `window` merged changes. */
18
+ readonly globs: readonly string[];
19
+ };
20
+
21
+ export type Measured = PerMerge & {
22
+ readonly window: number;
23
+ readonly byPath: ({ readonly glob: string } & PerMerge)[];
24
+ };
25
+
26
+ const sum = (counted: readonly Counted[], key: keyof Counted): number => counted.reduce((total, found) => total + found[key], 0);
27
+
28
+ const perMerge = (merged: readonly MergedChange[], abandoned: readonly AbandonedItem[], loopTokens: number): PerMerge => {
29
+ const all = [...merged, ...abandoned];
30
+ const merges = merged.length;
31
+
32
+ return {
33
+ merges,
34
+ abandoned: abandoned.length,
35
+ notes: sum(all, "notes") / merges,
36
+ questions: sum(all, "questions") / merges,
37
+ tokens: (sum(all, "tokens") + loopTokens) / merges,
38
+ };
39
+ };
40
+
41
+ const newestFirst = (merged: readonly MergedChange[], window: number): MergedChange[] => merged.toSorted((a, b) => b.at - a.at).slice(0, window);
42
+
43
+ /** The abandoned items from the oldest merge in the window on. */
44
+ const abandonedSince = (abandoned: readonly AbandonedItem[], inWindow: readonly MergedChange[]): AbandonedItem[] => {
45
+ const start = Math.min(...inWindow.map(({ at }) => at));
46
+
47
+ return abandoned.filter(({ since }) => since >= start);
48
+ };
49
+
50
+ const touches = (glob: string, paths: readonly string[]): boolean => paths.some((path) => new Bun.Glob(glob).match(path));
51
+
52
+ /**
53
+ * The three numbers per merged change over the last `window` merged changes, and over each path's own last
54
+ * `window`. `undefined` while nothing has merged, when a per-merge number has no meaning.
55
+ */
56
+ export const measureOf = ({ merged, abandoned, loopTokens, window, globs }: MeasureInput): Measured | undefined => {
57
+ const recent = newestFirst(merged, window);
58
+
59
+ if (recent.length === 0) return undefined;
60
+
61
+ const byPath = globs.flatMap((glob) => {
62
+ const onPath = newestFirst(merged.filter(({ paths }) => touches(glob, paths)), window);
63
+
64
+ return onPath.length === 0 ? [] : [{ glob, ...perMerge(onPath, abandonedSince(abandoned, onPath).filter(({ paths }) => touches(glob, paths)), 0) }];
65
+ });
66
+
67
+ return { window, ...perMerge(recent, abandonedSince(abandoned, recent), loopTokens), byPath };
68
+ };
@@ -0,0 +1,24 @@
1
+ export const CARD_CODES = { workerDown: "worker-down", tokenExpiring: "token-expiring", tokenRejected: "token-rejected" } as const;
2
+
3
+ const WORKER_FIX = "Look at the unit's log for the cause. Starting the unit again lets the worker start again.";
4
+
5
+ const TOKEN_FIX = "Run `claude setup-token`, store it as the CLAUDE_CODE_OAUTH_TOKEN secret and set ciToken.setUp in .hum/hum.json to today.";
6
+
7
+ const ERROR_EXCERPT = 160;
8
+
9
+ const kind =
10
+ <Facts>(code: string, fix: string, cause: (facts: Facts) => string) =>
11
+ (facts: Facts) => ({ code, cause: cause(facts), fix });
12
+
13
+ /** Every card the service layer raises, as a function from the facts it is raised for. */
14
+ export const CARD_KINDS = {
15
+ workerSilent: kind(CARD_CODES.workerDown, WORKER_FIX, ({ seconds, ticks }: { seconds: number; ticks: number }) => `The worker has written no heartbeat for ${seconds} seconds, ${ticks} ticks.`),
16
+ workerGaveUp: kind(
17
+ CARD_CODES.workerDown,
18
+ WORKER_FIX,
19
+ ({ crashes, windowMinutes, exitCode }: { crashes: number; windowMinutes: number; exitCode: number }) =>
20
+ `The worker exited ${crashes} times in ${windowMinutes} minutes, the last with code ${exitCode}. Restarts have stopped.`,
21
+ ),
22
+ tokenExpiring: kind(CARD_CODES.tokenExpiring, TOKEN_FIX, ({ setUp, validUntil }: { setUp: string; validUntil: string }) => `The CI token made on ${setUp} is valid until ${validUntil}.`),
23
+ tokenRejected: kind(CARD_CODES.tokenRejected, TOKEN_FIX, ({ said }: { said: string }) => `claude was refused with a 401: ${said.slice(0, ERROR_EXCERPT)}`),
24
+ };
@@ -0,0 +1,28 @@
1
+ import { type GitIdentity, gitIn, push, whenGitFailed } from "../adapters/git.ts";
2
+ import { SECOND_MS } from "../time.ts";
3
+
4
+ /** Where the scheduled workflow leaves its last tick. A ref holds no file, so no branch or checkout changes. */
5
+ export const CI_TICK_REF = "refs/hum/ticks/ci";
6
+
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> => {
9
+ const when = `${Math.floor(at / SECOND_MS)} +0000`;
10
+ const git = gitIn(repo, { identity, timeoutMs, env: { GIT_AUTHOR_DATE: when, GIT_COMMITTER_DATE: when } });
11
+ const tree = (await git.raw(["hash-object", "-w", "-t", "tree", "/dev/null"])).trim();
12
+ const commit = (await git.raw(["commit-tree", tree, "-m", `hum ci tick ${new Date(at).toISOString()}`])).trim();
13
+
14
+ await push(git, ["--force", remote, `${commit}:${CI_TICK_REF}`]);
15
+ };
16
+
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> => {
19
+ const git = gitIn(repo, { timeoutMs });
20
+
21
+ const fetched = await git.raw(["fetch", "--quiet", "--no-tags", remote, `+${CI_TICK_REF}:${CI_TICK_REF}`]).then(() => true, whenGitFailed(false));
22
+
23
+ if (!fetched) return undefined;
24
+
25
+ const at = Number((await git.raw(["log", "-1", "--format=%ct", CI_TICK_REF])).trim());
26
+
27
+ return Number.isFinite(at) && at > 0 ? at * SECOND_MS : undefined;
28
+ };
@@ -0,0 +1,16 @@
1
+ import { build } from "plist";
2
+ import type { UnitBuilder } from "./unit.ts";
3
+
4
+ /** A launchd job that starts at load and again after a failure only: the start script exits 0 when it gives up. */
5
+ export const launchdUnit: UnitBuilder = ({ label, repo, command, path, env, log, restartDelaySeconds }) =>
6
+ build({
7
+ Label: label,
8
+ ProgramArguments: [...command],
9
+ WorkingDirectory: repo,
10
+ EnvironmentVariables: { PATH: path, ...env },
11
+ RunAtLoad: true,
12
+ KeepAlive: { SuccessfulExit: false },
13
+ ThrottleInterval: restartDelaySeconds,
14
+ StandardOutPath: log,
15
+ StandardErrorPath: log,
16
+ });
@@ -0,0 +1,145 @@
1
+ import { createActor, createAsyncLogic, setup, toPromise } from "xstate";
2
+ import { z } from "zod";
3
+ import { ENGINE_VERSION } from "../state/format.ts";
4
+ import type { State } from "../state/open.ts";
5
+ import { readHeartbeat, writeCards } from "../status/file.ts";
6
+ import { MINUTE_MS, SECOND_MS } from "../time.ts";
7
+ import { CARD_CODES, CARD_KINDS } from "./cards.ts";
8
+
9
+ /** The exit code of a worker that stopped because an update arrived. `EX_TEMPFAIL`: the supervisor starts it again without counting a crash. */
10
+ export const EXIT_UPDATED = 75;
11
+
12
+ /** A worker process, or a stand-in for one. */
13
+ export type Child = { readonly exited: Promise<number>; readonly kill: () => void };
14
+
15
+ export type Supervision = {
16
+ readonly state: Pick<State, "faults" | "heartbeatPath" | "statusPath">;
17
+ readonly spawn: () => Child;
18
+ readonly now: () => number;
19
+ /** The time between heartbeat looks, and the worker's tick interval until it writes a heartbeat. */
20
+ readonly intervalMs: number;
21
+ readonly workerDownTicks: number;
22
+ readonly maxCrashes: number;
23
+ readonly crashWindowMs: number;
24
+ /** The pause before the first restart, doubled for each crash still inside the window, up to `maxBackoffMs`. */
25
+ readonly backoffMs: number;
26
+ readonly maxBackoffMs: number;
27
+ readonly stop: AbortSignal;
28
+ };
29
+
30
+ export type Ended = "stopped" | "gave-up";
31
+
32
+ const Context = z.object({
33
+ crashes: z.array(z.number()),
34
+ /** The last time anything showed the worker alive, or the start. A restart does not move it, so a worker that exits at start still goes stale. */
35
+ quietSince: z.number(),
36
+ });
37
+
38
+ type Context = z.infer<typeof Context>;
39
+
40
+ type Card = ReturnType<(typeof CARD_KINDS)["workerSilent"]> | undefined;
41
+
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
+ const showWorkerDown = ({ faults, statusPath }: Supervision["state"], card: Card, now: number): void => {
44
+ faults.clear(CARD_CODES.workerDown);
45
+
46
+ if (card) faults.raise(card);
47
+
48
+ writeCards(statusPath, faults.list(), ENGINE_VERSION, now);
49
+ };
50
+
51
+ const isUpdateExit = (exitCode: number): boolean => exitCode === EXIT_UPDATED;
52
+
53
+ const crashesInWindow = (crashes: readonly number[], at: number, windowMs: number): number[] => [...crashes.filter((crashed) => at - crashed < windowMs), at];
54
+
55
+ type Silence = { readonly quietSince: number; readonly silentMs: number; readonly isSilent: boolean };
56
+
57
+ /** How long nothing has shown the worker alive, and whether that is `ticks` of the worker's own tick interval. */
58
+ const silenceOf = (quietSince: number, beat: { readonly time: number; readonly intervalMs: number } | undefined, now: number, o: Pick<Supervision, "intervalMs" | "workerDownTicks">): Silence => {
59
+ const lastSeen = Math.max(quietSince, beat?.time ?? 0);
60
+ const silentMs = now - lastSeen;
61
+
62
+ return { quietSince: lastSeen, silentMs, isSilent: silentMs >= o.workerDownTicks * (beat?.intervalMs ?? o.intervalMs) };
63
+ };
64
+
65
+ const backoffFor = (crashes: number, { backoffMs, maxBackoffMs }: Pick<Supervision, "backoffMs" | "maxBackoffMs">): number => Math.min(backoffMs * 2 ** (crashes - 1), maxBackoffMs);
66
+
67
+ /**
68
+ * The start script as a machine. It runs the worker and starts it again when it exits, looks at the heartbeat once
69
+ * a tick, and stops restarting after too many crashes in the window. Giving up ends it as `gave-up`, so the
70
+ * unit's exit code is 0 and the unit does not start the script again.
71
+ */
72
+ const supervisorMachine = (o: Supervision, current: { child?: Child }) => {
73
+ const supervisor = setup({
74
+ schemas: { context: Context, events: { stop: z.object({}) } },
75
+ delays: { tick: o.intervalMs, backoff: ({ context }) => backoffFor(context.crashes.length, o) },
76
+ actors: {
77
+ worker: createAsyncLogic({ run: () => (current.child = o.spawn()).exited }),
78
+ exit: createAsyncLogic({ run: () => current.child?.exited ?? Promise.resolve(0) }),
79
+ },
80
+ });
81
+
82
+ const hasReachedLimit = (crashes: readonly number[]): boolean => crashes.length >= o.maxCrashes;
83
+
84
+ const looking = {
85
+ after: {
86
+ tick: ({ context }: { context: Context }, enq: (effect: () => void) => void) => {
87
+ const now = o.now();
88
+ const { quietSince, silentMs, isSilent } = silenceOf(context.quietSince, readHeartbeat(o.state.heartbeatPath), now, o);
89
+ const isShown = o.state.faults.list().some((card) => card.key === CARD_CODES.workerDown);
90
+ const mustChangeCard = isSilent !== isShown;
91
+
92
+ if (mustChangeCard) enq(() => showWorkerDown(o.state, isSilent ? CARD_KINDS.workerSilent({ seconds: Math.round(silentMs / SECOND_MS), ticks: o.workerDownTicks }) : undefined, now));
93
+
94
+ return { target: "looking", reenter: true, context: { ...context, quietSince } };
95
+ },
96
+ },
97
+ };
98
+
99
+ return supervisor.createMachine({
100
+ id: "supervisor",
101
+ context: { crashes: [], quietSince: o.now() },
102
+ initial: "running",
103
+ on: { stop: { target: "#supervisor.stopping" } },
104
+ states: {
105
+ running: {
106
+ initial: "looking",
107
+ invoke: {
108
+ src: "worker",
109
+ onDone: ({ context, event }, enq) => {
110
+ const exitCode = event.output;
111
+
112
+ if (isUpdateExit(exitCode)) return { target: "running", reenter: true };
113
+
114
+ const now = o.now();
115
+ const crashes = crashesInWindow(context.crashes, now, o.crashWindowMs);
116
+
117
+ if (!hasReachedLimit(crashes)) return { target: "backingOff", context: { ...context, crashes } };
118
+
119
+ enq(() => showWorkerDown(o.state, CARD_KINDS.workerGaveUp({ crashes: crashes.length, windowMinutes: Math.round(o.crashWindowMs / MINUTE_MS), exitCode }), now));
120
+
121
+ return { target: "gaveUp", context: { ...context, crashes } };
122
+ },
123
+ },
124
+ states: { looking },
125
+ },
126
+ backingOff: { initial: "looking", after: { backoff: { target: "running" } }, states: { looking } },
127
+ stopping: { entry: (_, enq) => void enq(() => current.child?.kill()), invoke: { src: "exit", onDone: { target: "stopped" } }, on: { stop: undefined } },
128
+ gaveUp: { type: "final", output: "gave-up" as const },
129
+ stopped: { type: "final", output: "stopped" as const },
130
+ },
131
+ });
132
+ };
133
+
134
+ /** Runs the start script until `stop` or the crash limit. */
135
+ export const supervise = (o: Supervision): Promise<Ended> => {
136
+ const actor = createActor(supervisorMachine(o, {})).start();
137
+ const halt = () => actor.send({ type: "stop" });
138
+
139
+ showWorkerDown(o.state, undefined, o.now());
140
+
141
+ if (o.stop.aborted) halt();
142
+ else o.stop.addEventListener("abort", halt, { once: true });
143
+
144
+ return toPromise(actor).finally(() => o.stop.removeEventListener("abort", halt));
145
+ };
@@ -0,0 +1,44 @@
1
+ import type { UnitBuilder } from "./unit.ts";
2
+
3
+ type Sections = Readonly<Record<string, Readonly<Record<string, string>>>>;
4
+
5
+ /** systemd reads `%` as the start of a specifier. */
6
+ const literalPercent = (text: string): string => text.replace(/%/g, "%%");
7
+
8
+ /** A word in a systemd line: quoted, with `%` and `$` doubled so no specifier or variable expands. */
9
+ const word = (text: string): string => `"${literalPercent(text).replace(/[\\"]/g, "\\$&").replace(/\$/g, "$$$$")}"`;
10
+
11
+ const assertOneLine = (values: readonly string[]): void => {
12
+ for (const value of values) if (/[\n\r]/.test(value)) throw new Error(`a unit value holds a line break: ${JSON.stringify(value)}`);
13
+ };
14
+
15
+ /**
16
+ * systemd reads `Key=value` lines whose quotes are its own. An INI library quotes a value that holds a quote
17
+ * and so changes what systemd reads.
18
+ */
19
+ const serialize = (sections: Sections): string =>
20
+ `${Object.entries(sections)
21
+ .map(([section, keys]) => `[${section}]\n${Object.entries(keys).map(([key, value]) => `${key}=${value}`).join("\n")}`)
22
+ .join("\n\n")}\n`;
23
+
24
+ /** A user service that restarts after a failure only: the start script exits 0 when it gives up. */
25
+ export const systemdUnit: UnitBuilder = ({ repo, command, path, env, restartDelaySeconds }) => {
26
+ const environment = { PATH: path, ...env };
27
+
28
+ assertOneLine([repo, ...command, ...Object.values(environment)]);
29
+
30
+ return serialize({
31
+ Unit: { Description: `hum worker for ${literalPercent(repo)}`, After: "network-online.target", Wants: "network-online.target" },
32
+ Service: {
33
+ Type: "simple",
34
+ WorkingDirectory: literalPercent(repo),
35
+ Environment: Object.entries(environment)
36
+ .map(([key, value]) => word(`${key}=${value}`))
37
+ .join(" "),
38
+ ExecStart: command.map(word).join(" "),
39
+ Restart: "on-failure",
40
+ RestartSec: String(restartDelaySeconds),
41
+ },
42
+ Install: { WantedBy: "default.target" },
43
+ });
44
+ };
@@ -0,0 +1,21 @@
1
+ import type { Faults } from "../state/faults.ts";
2
+ import { DAY_MS } from "../time.ts";
3
+ import { CARD_CODES, CARD_KINDS } from "./cards.ts";
4
+
5
+ /** `claude setup-token` makes a one-year token. */
6
+ export const TOKEN_LIFE_DAYS = 365;
7
+
8
+ /** What `claude -p` prints for a rejected token: `Failed to authenticate. API Error: 401 Invalid bearer token`. */
9
+ export const UNAUTHORIZED = /API Error: 401|Failed to authenticate/i;
10
+
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 }));
13
+
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 => {
16
+ const expires = Date.parse(setUp) + TOKEN_LIFE_DAYS * DAY_MS;
17
+
18
+ if (now < expires - warnDays * DAY_MS) return faults.clear(CARD_CODES.tokenExpiring);
19
+
20
+ faults.raise(CARD_KINDS.tokenExpiring({ setUp, validUntil: new Date(expires).toISOString().slice(0, 10) }));
21
+ };
@@ -0,0 +1,29 @@
1
+ import { launchdUnit } from "./launchd.ts";
2
+ import { systemdUnit } from "./systemd.ts";
3
+
4
+ /** What a unit needs to run `hum serve` on its own: every path absolute, because a unit starts with a bare PATH. */
5
+ export type UnitVars = {
6
+ /** The launchd label, which also names the unit's file. */
7
+ readonly label: string;
8
+ /** The owner's checkout. */
9
+ readonly repo: string;
10
+ /** The program and its arguments: the runtime, the `hum` entry, `serve`, then the worker's options. */
11
+ readonly command: readonly string[];
12
+ /** The unit's PATH; it must reach `git`, `claude` and the runtime. */
13
+ readonly path: string;
14
+ /** More environment, such as `HOME`. */
15
+ readonly env?: Readonly<Record<string, string>>;
16
+ /** Where launchd writes the output. */
17
+ readonly log: string;
18
+ /** The seconds a service manager waits before it starts a failed script again. */
19
+ readonly restartDelaySeconds: number;
20
+ };
21
+
22
+ export type UnitKind = "launchd" | "systemd";
23
+
24
+ export type UnitBuilder = (vars: UnitVars) => string;
25
+
26
+ const UNITS = { launchd: launchdUnit, systemd: systemdUnit } as const satisfies Record<UnitKind, UnitBuilder>;
27
+
28
+ /** The unit file of one service manager. Throws when a value would break the file. */
29
+ export const renderUnit = (kind: UnitKind, vars: UnitVars): string => UNITS[kind](vars);
@@ -0,0 +1,30 @@
1
+ import * as core from "@actions/core";
2
+ import type { Card } from "../status/format.ts";
3
+ import type { Worker } from "../worker/worker.ts";
4
+
5
+ /**
6
+ * CI wake: ticks, lets the runs it started end, and ticks again until a tick starts nothing. A CI job holds no
7
+ * session across a wait for the owner: a run that needs them has pushed its branch, asked on the item and ended.
8
+ */
9
+ export const wakeUntilQuiet = async (worker: Worker): Promise<void> => {
10
+ for (;;) {
11
+ const result = await worker.tick();
12
+
13
+ await worker.idle();
14
+
15
+ if (result.kind !== "ran" || result.started.length === 0) return;
16
+ }
17
+ };
18
+
19
+ /** The card as one line of text. */
20
+ const line = (card: Card): string => `${card.cause} ${card.fix}`;
21
+
22
+ /**
23
+ * Shows the cards where a CI job's reader looks: one error annotation each, and the job's step summary when the
24
+ * runner gives one. The job's status file dies with the job, so this is the only place CI shows a card.
25
+ */
26
+ export const reportCards = async (cards: readonly Card[]): Promise<void> => {
27
+ for (const card of cards) core.error(line(card), { title: `hum ${card.code}` });
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();
30
+ };