@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
@@ -1,11 +1,17 @@
1
1
  import type { Item } from "../adapter-api.ts";
2
2
  import { declaredKind } from "../decide/kind.ts";
3
3
  import { usualSize } from "../decide/risk.ts";
4
- import type { DefaultsConfig, HumConfig, PathRule, RunPlace, SlotRecipe } from "../config/schema.ts";
4
+ import type { DefaultsConfig, HumConfig, PathRule, PullRequestToken, RunPlace, SlotRecipe } from "../config/schema.ts";
5
+ import { APP_TOKEN_ACTION, CI_WORKFLOW_FILES, CLAUDE_TOKEN, isGitHubHosted, readsForeignContext, WAKE_OWN_ENV } from "../config/wake-job.ts";
5
6
  import type { CiJob, RepoScan } from "./scan.ts";
6
7
  import {
7
8
  CHECK_COMMAND,
8
9
  CHECK_SCRIPTS,
10
+ CLAUDE_ACTION,
11
+ CLAUDE_ACTION_SIGN_IN,
12
+ CLAUDE_API_KEY,
13
+ CLAUDE_CREDENTIAL_ENV,
14
+ CLAUDE_COMMAND,
9
15
  DATA_AND_SECRET_GLOBS,
10
16
  DEFAULT_FOLDER_RANK,
11
17
  FOLDER_RANKS,
@@ -15,6 +21,7 @@ import {
15
21
  ROOT_MARKDOWN_RANK,
16
22
  RUN_SCRIPT,
17
23
  SECRET_TEMPLATE,
24
+ SECRET_VALUE,
18
25
  } from "./tables.ts";
19
26
 
20
27
  /** The settings setup proposes from a scan; the owner changes any of them before they are written. */
@@ -28,6 +35,7 @@ export type Proposal = {
28
35
  readonly kindLabels: Readonly<Record<string, string>>;
29
36
  readonly runSlots: Pick<HumConfig["runSlots"], "services" | "recipe">;
30
37
  readonly runPlaces: readonly RunPlace[];
38
+ readonly wakeJob: Pick<HumConfig, "ciRunner" | "ciContainer" | "ciEnv" | "ciClaudeAuth" | "pullRequestToken">;
31
39
  };
32
40
 
33
41
  const isPullRequestJob = ({ triggers }: CiJob): boolean => triggers.includes("pull_request");
@@ -46,7 +54,7 @@ const scriptCommand = (scan: RepoScan, script: string): string | undefined => {
46
54
  * The commands the repo's own CI runs on a pull request to check a change; else its package scripts that check.
47
55
  * A run checks a fresh clone, which has no dependencies yet, so the lockfile install comes first.
48
56
  */
49
- export const checksOf = (scan: RepoScan): string[] => {
57
+ const checksOf = (scan: RepoScan): string[] => {
50
58
  const fromCi = unique(scan.ci.filter(isPullRequestJob).flatMap(({ commands }) => commands.filter(isCheck)));
51
59
  const checks = fromCi.length > 0 ? fromCi : CHECK_SCRIPTS.flatMap((script) => scriptCommand(scan, script) ?? []);
52
60
 
@@ -60,14 +68,14 @@ const rankOfFolder = (folder: string): number => FOLDER_RANKS.find((row) => row.
60
68
  const topFolders = (tracked: readonly string[]): string[] => unique(tracked.flatMap((path) => (path.includes("/") ? [path.split("/")[0] ?? ""] : []))).sort();
61
69
 
62
70
  /** A rule per top-level folder, one for markdown at the root and one for the other root files, so no path is left unplaced. */
63
- export const pathRulesOf = (tracked: readonly string[], levels: HumConfig["levels"]): PathRule[] => [
71
+ const pathRulesOf = (tracked: readonly string[], levels: HumConfig["levels"]): PathRule[] => [
64
72
  ...topFolders(tracked).map((folder) => ({ glob: `${folder}/**`, level: levelAt(levels, rankOfFolder(folder)) })),
65
73
  { glob: "*.md", level: levelAt(levels, ROOT_MARKDOWN_RANK) },
66
74
  { glob: "*", level: levelAt(levels, DEFAULT_FOLDER_RANK) },
67
75
  ];
68
76
 
69
77
  /** The data and secrets globs that match a tracked file; a file that only shows the shape of a secret does not count. */
70
- export const strictGlobsOf = (tracked: readonly string[]): string[] =>
78
+ const strictGlobsOf = (tracked: readonly string[]): string[] =>
71
79
  DATA_AND_SECRET_GLOBS.filter((glob) => tracked.some((path) => new Bun.Glob(glob).match(path) && !SECRET_TEMPLATE.test(path)));
72
80
 
73
81
  const mapLabels = (labels: readonly string[], kinds: readonly string[]): Record<string, string> =>
@@ -80,7 +88,7 @@ const mapLabels = (labels: readonly string[], kinds: readonly string[]): Record<
80
88
  );
81
89
 
82
90
  /** Label → kind for the labels the repo uses: those on its issue templates and the ones it lists. A label the table does not know is left out. */
83
- export const kindLabelsOf = (scan: RepoScan, repoLabels: readonly string[], kinds: readonly string[]): Record<string, string> =>
91
+ const kindLabelsOf = (scan: RepoScan, repoLabels: readonly string[], kinds: readonly string[]): Record<string, string> =>
84
92
  mapLabels([...scan.issueTemplates.flatMap(({ labels }) => labels), ...repoLabels], kinds);
85
93
 
86
94
  /** How many of the open items name their kind through the map, a kind's own name or a template field. */
@@ -103,8 +111,70 @@ const recipeOf = (scan: RepoScan, checks: readonly string[]): SlotRecipe => {
103
111
  };
104
112
  };
105
113
 
114
+ const isAction = (uses: string, action: string): boolean => uses.startsWith(`${action}@`);
115
+
116
+ const runsClaude = ({ commands, actions }: CiJob): boolean => commands.some((command) => CLAUDE_COMMAND.test(command)) || actions.some(({ uses }) => isAction(uses, CLAUDE_ACTION));
117
+
118
+ const secretIn = (value: string | undefined): string | undefined => (value === undefined ? undefined : SECRET_VALUE.exec(value)?.[1]);
119
+
120
+ /** The first GitHub App a job mints a token from with both its client ID, or its older App ID, and its private key in secrets. */
121
+ const appOf = (jobs: readonly CiJob[]): PullRequestToken | undefined =>
122
+ jobs
123
+ .flatMap(({ actions }) => actions)
124
+ .flatMap(({ uses, with: inputs }): PullRequestToken[] => {
125
+ const clientIdSecret = secretIn(inputs["client-id"] ?? inputs["app-id"]);
126
+ const privateKeySecret = secretIn(inputs["private-key"]);
127
+
128
+ return isAction(uses, APP_TOKEN_ACTION) && clientIdSecret !== undefined && privateKeySecret !== undefined ? [{ from: "app", clientIdSecret, privateKeySecret }] : [];
129
+ })[0];
130
+
131
+ /** The inputs a job gives the Claude Code action, all its steps together. */
132
+ const claudeInputsOf = ({ actions }: CiJob): Readonly<Record<string, string>> =>
133
+ Object.assign({}, ...actions.filter(({ uses }) => isAction(uses, CLAUDE_ACTION)).map((action) => action.with));
134
+
135
+ /** Whether a job hands Claude Code an OAuth token: its env, commands or action inputs name the token, or the action takes one under any secret's name. */
136
+ const readsClaudeToken = (job: CiJob): boolean =>
137
+ CLAUDE_ACTION_SIGN_IN.oauthToken in claudeInputsOf(job) ||
138
+ [...Object.entries(job.env).flat(), ...job.commands, ...job.actions.flatMap((action) => Object.values(action.with))].some((text) => text.includes(CLAUDE_TOKEN));
139
+
140
+ /** The env the Claude Code job signs in and runs with: its own, without the names the wake job sets itself, and the API key its action takes as an input. */
141
+ const claudeEnvOf = (job: CiJob): Record<string, string> => {
142
+ const apiKey = claudeInputsOf(job)[CLAUDE_ACTION_SIGN_IN.apiKey];
143
+ const fromInput = apiKey === undefined ? [] : [[CLAUDE_API_KEY, apiKey] as const];
144
+
145
+ return Object.fromEntries([...Object.entries(job.env), ...fromInput].filter(([name, value]) => !WAKE_OWN_ENV.has(name) && !readsForeignContext(value)));
146
+ };
147
+
148
+ /** What a scan cannot read from the files: the repo's labels, and whether anyone may read and comment on it. */
149
+ export type RepoFacts = { readonly labels?: readonly string[]; readonly isPublic?: boolean };
150
+
151
+ /**
152
+ * The wake job's settings from the job most like it: the one that runs Claude Code gives its runner, container, env
153
+ * and sign-in; without one, the first pull request job that names a runner gives its runner and container. hum's own
154
+ * workflows are left out, so a second setup reads the owner's. The App comes from any job that mints a token. Sign-in
155
+ * through env is proposed only where the env holds a credential, so no proposal signs in with nothing. A value that
156
+ * reads a context the wake job lacks would break the wake, so it is not proposed. On a public repo a runner GitHub
157
+ * does not host is never proposed: the owner names one on their own.
158
+ */
159
+ const wakeJobOf = (ci: readonly CiJob[], shipped: DefaultsConfig, isPublic: boolean): Proposal["wakeJob"] => {
160
+ const jobs = ci.filter(({ file }) => !CI_WORKFLOW_FILES.has(file));
161
+ const claude = jobs.find(runsClaude);
162
+ const like = claude ?? jobs.find((job) => isPullRequestJob(job) && job.runner !== undefined);
163
+ const ciEnv = claude ? claudeEnvOf(claude) : shipped.ciEnv;
164
+ const holdsCredential = Object.keys(ciEnv).some((name) => CLAUDE_CREDENTIAL_ENV.has(name));
165
+ const mayRunOn = (runner: HumConfig["ciRunner"]): boolean => !readsForeignContext(runner) && (!isPublic || isGitHubHosted(runner));
166
+
167
+ return {
168
+ ciRunner: like?.runner !== undefined && mayRunOn(like.runner) ? like.runner : shipped.ciRunner,
169
+ ciContainer: like?.container !== undefined && !readsForeignContext(like.container) ? like.container : shipped.ciContainer,
170
+ ciEnv,
171
+ ciClaudeAuth: claude && readsClaudeToken(claude) ? "oauth-token" : claude && holdsCredential ? "env" : shipped.ciClaudeAuth,
172
+ pullRequestToken: appOf(jobs) ?? shipped.pullRequestToken,
173
+ };
174
+ };
175
+
106
176
  /** Everything setup proposes from a scan, before it asks. */
107
- export const proposeSetup = (scan: RepoScan, shipped: DefaultsConfig, repoLabels: readonly string[] = []): Proposal => {
177
+ export const proposeSetup = (scan: RepoScan, shipped: DefaultsConfig, { labels = [], isPublic = false }: RepoFacts = {}): Proposal => {
108
178
  const checks = checksOf(scan);
109
179
 
110
180
  return {
@@ -113,8 +183,9 @@ export const proposeSetup = (scan: RepoScan, shipped: DefaultsConfig, repoLabels
113
183
  strictPaths: strictGlobsOf(scan.tracked),
114
184
  usualSizes: scan.folders.map(({ folder, sizes }) => ({ folder, usual: usualSize(sizes, shipped.sizeRange) })),
115
185
  windows: { fixWindow: shipped.changeLabels.fixWindow, measureWindow: shipped.measureWindow },
116
- kindLabels: kindLabelsOf(scan, repoLabels, shipped.kinds),
186
+ kindLabels: kindLabelsOf(scan, labels, shipped.kinds),
117
187
  runSlots: { services: shipped.runSlots.services, recipe: recipeOf(scan, checks) },
118
188
  runPlaces: shipped.runPlaces,
189
+ wakeJob: wakeJobOf(scan.ci, shipped, isPublic),
119
190
  };
120
191
  };
@@ -2,11 +2,11 @@ import { mkdtempSync, readFileSync } from "node:fs";
2
2
  import { tmpdir } from "node:os";
3
3
  import { join } from "node:path";
4
4
  import { z } from "zod";
5
- import type { AdapterContext } from "../adapter-api.ts";
5
+ import { type AdapterContext, Holder, ItemId } from "../adapter-api.ts";
6
6
  import { runContract } from "../adapters/contract.ts";
7
7
  import { markdownAdapter } from "../adapters/markdown.ts";
8
8
  import { type Config, loadConfig, readConfigDir } from "../config/load.ts";
9
- import { commandTimeoutMs, exec, SHIPPED_COMMAND_TIMEOUT_MS } from "../exec.ts";
9
+ import { commandTimeoutMs, type Env, exec, SHIPPED_COMMAND_TIMEOUT_MS } from "../exec.ts";
10
10
  import { SlotPool } from "../slots/pool.ts";
11
11
  import { orMissing } from "../state/fs.ts";
12
12
  import { openState } from "../state/open.ts";
@@ -14,7 +14,7 @@ import { checksTimeoutMs, runChecks } from "../worker/checks.ts";
14
14
  import { openWorker } from "../worker/open.ts";
15
15
  import { Scratch } from "./scratch.ts";
16
16
 
17
- export type StepStatus = "passed" | "failed" | "skipped";
17
+ type StepStatus = "passed" | "failed" | "skipped";
18
18
 
19
19
  /** One thing setup proved, with how long it took. A skip says why, so nothing passes silently. */
20
20
  export type Step = { readonly name: string; readonly status: StepStatus; readonly detail: string; readonly ms: number };
@@ -27,9 +27,9 @@ const failed = (detail: string): Outcome => ({ status: "failed", detail });
27
27
 
28
28
  const skipped = (detail: string): Outcome => ({ status: "skipped", detail });
29
29
 
30
- /** Runs one step; a throw is the step failing, in the error's own words. */
31
30
  const stepOf = (name: string, outcome: Outcome, started: number): Step => ({ name, status: outcome.status, detail: outcome.detail, ms: Math.round(performance.now() - started) });
32
31
 
32
+ /** Runs one step; a throw is the step failing, in the error's own words. */
33
33
  const timed = async (name: string, run: () => Promise<Outcome>): Promise<Step> => {
34
34
  const started = performance.now();
35
35
 
@@ -37,6 +37,9 @@ const timed = async (name: string, run: () => Promise<Outcome>): Promise<Step> =
37
37
  };
38
38
 
39
39
  export type ProveEnv = {
40
+ readonly now: () => number;
41
+ readonly processEnv: Env;
42
+ readonly newSessionId: () => string;
40
43
  readonly hopeSkills: ReadonlySet<string>;
41
44
  readonly base: string;
42
45
  /** Whether to run one item end to end through the real `claude`; each run spends live calls. */
@@ -56,7 +59,7 @@ const ENGINE = "@moo.md/hum";
56
59
  const LOCAL_PIN = /^(file|link):/;
57
60
 
58
61
  /** What the registry says about the pinned version: found, or the package exists without it, or the package is not published. */
59
- export const npmPublished = async (pin: string): Promise<"found" | "missing-version" | "unpublished"> => {
62
+ const npmPublished = async (pin: string): Promise<"found" | "missing-version" | "unpublished"> => {
60
63
  const viewed = await exec("npm", ["view", `${ENGINE}@${pin}`, "version"], { throwOnError: false, timeoutMs: SHIPPED_COMMAND_TIMEOUT_MS });
61
64
 
62
65
  if (viewed.exitCode === 0) return "found";
@@ -93,7 +96,7 @@ const checksStep = async (repo: string, config: Config): Promise<Outcome> => {
93
96
  const markdownOver = (repo: string, base: string, hum: Config["hum"], context: AdapterContext) =>
94
97
  markdownAdapter({ repo, base, claimPrefix: hum.claimPrefix, itemsDir: hum.itemsDir, identity: hum.commitIdentity, writeRaceRetries: hum.writeRaceRetries, itemReadsAtOnce: hum.itemReadsAtOnce, mergeMethod: hum.mergeMethod, ownerBranchPrefix: hum.ownerBranchPrefix, timeoutMs: commandTimeoutMs(hum) }, context);
95
98
 
96
- const contractStep = async (config: Config, scratch: Scratch, base: string): Promise<Outcome> => {
99
+ const contractStep = async (config: Config, scratch: Scratch, { base, now, processEnv }: Pick<ProveEnv, "base" | "now" | "processEnv">): Promise<Outcome> => {
97
100
  const others = Object.entries(config.hum.integrations ?? {}).filter(([, adapter]) => adapter !== "markdown");
98
101
 
99
102
  if (others.length > 0) return skipped(`${others.map(([slot, adapter]) => `${slot}: ${adapter}`).join(", ")} write to a live target; run its contract suite there`);
@@ -101,7 +104,7 @@ const contractStep = async (config: Config, scratch: Scratch, base: string): Pro
101
104
  let skew = 0;
102
105
  let count = 0;
103
106
 
104
- const context: AdapterContext = { report: () => {}, now: () => Date.now() + skew };
107
+ const context: AdapterContext = { report: () => {}, now: () => now() + skew, env: processEnv };
105
108
  const first = markdownOver(await scratch.worker(), base, config.hum, context);
106
109
  const second = markdownOver(await scratch.worker(), base, config.hum, context);
107
110
 
@@ -109,7 +112,7 @@ const contractStep = async (config: Config, scratch: Scratch, base: string): Pro
109
112
  name: "markdown",
110
113
  adapter: first,
111
114
  other: async () => second,
112
- seed: (title) => scratch.seed(`contract-${++count}`, title, "body"),
115
+ seed: async (title) => ItemId.parse(await scratch.seed(`contract-${++count}`, title, "body")),
113
116
  advance: async (ms) => void (skew += ms),
114
117
  spent: () => first.spent(),
115
118
  });
@@ -137,8 +140,8 @@ const slotStep = async (config: Config, scratch: Scratch, env: ProveEnv): Promis
137
140
  if (!config.hum.runSlots.enabled) return skipped("run slots are off in hum.json");
138
141
 
139
142
  const pool = mkdtempSync(join(tmpdir(), "hum-prove-slots-"));
140
- const state = openState(mkdtempSync(join(tmpdir(), "hum-prove-state-")));
141
- const slots = new SlotPool({ repo: scratch.owner, state, config: { ...config.hum, runners: 1, runSlots: { ...config.hum.runSlots, pool } }, base: env.base });
143
+ const state = openState(mkdtempSync(join(tmpdir(), "hum-prove-state-")), { now: env.now });
144
+ const slots = new SlotPool({ repo: scratch.owner, state, config: { ...config.hum, runners: 1, runSlots: { ...config.hum.runSlots, pool } }, base: env.base, now: env.now });
142
145
  const started = performance.now();
143
146
 
144
147
  await slots.maintain();
@@ -172,8 +175,11 @@ const runItem = async (scratch: Scratch, env: ProveEnv): Promise<Outcome> => {
172
175
  const results: string[] = [];
173
176
 
174
177
  const worker = await openWorker(scratch.owner, {
178
+ now: env.now,
179
+ env: env.processEnv,
180
+ newSessionId: env.newSessionId,
175
181
  hopeSkills: env.hopeSkills,
176
- holder: "setup-proof",
182
+ holder: Holder.parse("setup-proof"),
177
183
  base: env.base,
178
184
  where: "ci",
179
185
  stateDir: mkdtempSync(join(tmpdir(), "hum-prove-state-")),
@@ -205,7 +211,7 @@ export const proveSetup = async (repo: string, env: ProveEnv): Promise<Step[]> =
205
211
  return [
206
212
  configured,
207
213
  await timed("checks", () => checksStep(repo, config)),
208
- await timed("contract", () => contractStep(config, scratch, env.base)),
214
+ await timed("contract", () => contractStep(config, scratch, env)),
209
215
  await timed("engine pin", () => pinStep(repo, env)),
210
216
  await timed("slot", () => slotStep(config, scratch, env)),
211
217
  await timed("item", () => itemStep(repo, config, env)),
package/src/setup/scan.ts CHANGED
@@ -1,17 +1,17 @@
1
1
  import { accessSync, constants, readFileSync } from "node:fs";
2
2
  import { basename, join } from "node:path";
3
- import { parse as parseYaml } from "yaml";
3
+ import { parseDocument } from "yaml";
4
4
  import { z } from "zod";
5
5
  import { gitIn } from "../adapters/git.ts";
6
6
  import { readHistory } from "../adapters/history.ts";
7
- import { SHIPPED_DEFAULTS } from "../config/schema.ts";
7
+ import { type HumConfig, SHIPPED_DEFAULTS } from "../config/schema.ts";
8
8
  import { SHIPPED_COMMAND_TIMEOUT_MS } from "../exec.ts";
9
9
  import { orMissing } from "../state/fs.ts";
10
- import { ENV_SCRIPTS } from "../slots/scan.ts";
11
10
  import {
12
11
  CODEOWNERS_FILES,
13
12
  COMPOSE_FILES,
14
13
  ENV_EXAMPLE_FILES,
14
+ ENV_SCRIPTS,
15
15
  ENV_TOOLING_FILES,
16
16
  ISSUE_TEMPLATE_FOLDER,
17
17
  LOCKFILES,
@@ -22,10 +22,22 @@ import {
22
22
  WORKFLOW_FOLDER,
23
23
  } from "./tables.ts";
24
24
 
25
- /** One job of a CI workflow: when it runs and the shell commands its steps run. */
26
- export type CiJob = { readonly file: string; readonly job: string; readonly triggers: readonly string[]; readonly commands: readonly string[] };
25
+ /** One job of a CI workflow: when it runs, where, with what env, and the shell commands and actions its steps run. */
26
+ export type CiJob = {
27
+ readonly file: string;
28
+ readonly job: string;
29
+ readonly triggers: readonly string[];
30
+ readonly commands: readonly string[];
31
+ /** What the job's `runs-on` holds: a label, a label list or a runner group. */
32
+ readonly runner: HumConfig["ciRunner"] | undefined;
33
+ /** The job's container: its image, with the registry sign-in, env, ports, volumes and options where the job names them. */
34
+ readonly container: NonNullable<HumConfig["ciContainer"]> | undefined;
35
+ /** The env every step gets: the workflow's, with the job's own over it. */
36
+ readonly env: Readonly<Record<string, string>>;
37
+ readonly actions: readonly { readonly uses: string; readonly with: Readonly<Record<string, string>> }[];
38
+ };
27
39
 
28
- export type FolderHistory = { readonly folder: string; readonly changes: number; readonly sizes: readonly number[] };
40
+ type FolderHistory = { readonly folder: string; readonly changes: number; readonly sizes: readonly number[] };
29
41
 
30
42
  /** What a repo already holds that setup reads before it asks. */
31
43
  export type RepoScan = {
@@ -49,7 +61,7 @@ export type RepoScan = {
49
61
 
50
62
  const textOf = (repo: string, path: string): string => (path === "" ? "" : orMissing(() => readFileSync(join(repo, path), "utf8"), ""));
51
63
 
52
- const exists = (repo: string, path: string): boolean => orMissing(() => (accessSync(join(repo, path)), true), false);
64
+ const doesExist = (repo: string, path: string): boolean => orMissing(() => (accessSync(join(repo, path)), true), false);
53
65
 
54
66
  const isRunnable = (repo: string, path: string): boolean => orMissing(() => (accessSync(join(repo, path), constants.X_OK), true), false);
55
67
 
@@ -61,9 +73,49 @@ const PackageJson = z.looseObject({
61
73
  devDependencies: z.record(z.string(), z.string()).default({}),
62
74
  });
63
75
 
76
+ /** YAML reads `1` and `true` as a number and a boolean; a workflow passes each on as text. */
77
+ const Text = z.union([z.string(), z.number(), z.boolean()]).transform(String);
78
+
79
+ /** A map's entries that are text: one that is not, such as a key YAML reads with no value, is left out alone. No entries where the workflow writes an expression in the map's place. */
80
+ const TextMap = z
81
+ .record(z.string(), z.unknown())
82
+ .catch({})
83
+ .transform((map) => Object.fromEntries(Object.entries(map).flatMap(([key, value]) => (Text.safeParse(value).success ? [[key, String(value)]] : []))));
84
+
85
+ const RunnerLabels = z.union([z.string(), z.array(z.string()).min(1)]);
86
+
87
+ /** A key the workflow leaves out stays out, so what a scan reads has the shape `hum.json` holds. */
88
+ const withoutUnset = <T extends object>(value: T): T => JSON.parse(JSON.stringify(value));
89
+
90
+ const RunsOn = z
91
+ .union([RunnerLabels, z.looseObject({ group: z.string(), labels: RunnerLabels.optional() }).transform(({ group, labels }) => withoutUnset({ group, labels })), z.looseObject({ labels: RunnerLabels }).transform(({ labels }) => labels)])
92
+ .optional()
93
+ .catch(undefined);
94
+
95
+ const Container = z
96
+ .union([
97
+ z.string(),
98
+ z
99
+ .object({ image: z.string(), credentials: z.object({ username: Text, password: Text }).optional(), env: TextMap.optional(), ports: z.array(z.union([z.string(), z.number()])).optional(), volumes: z.array(z.string()).optional(), options: z.string().optional() })
100
+ .transform(({ image, ...beside }) => (Object.values(beside).every((value) => value === undefined) ? image : withoutUnset({ image, ...beside }))),
101
+ ])
102
+ .optional()
103
+ .catch(undefined);
104
+
64
105
  const Workflow = z.looseObject({
65
106
  on: z.union([z.string().transform((trigger) => [trigger]), z.array(z.string()), z.record(z.string(), z.unknown()).transform((triggers) => Object.keys(triggers))]).default([]),
66
- jobs: z.record(z.string(), z.looseObject({ steps: z.array(z.looseObject({ run: z.string().optional() })).default([]) })).default({}),
107
+ env: TextMap,
108
+ jobs: z
109
+ .record(
110
+ z.string(),
111
+ z.looseObject({
112
+ "runs-on": RunsOn,
113
+ container: Container,
114
+ env: TextMap,
115
+ steps: z.array(z.looseObject({ run: z.string().optional(), uses: z.string().optional(), with: TextMap })).default([]),
116
+ }),
117
+ )
118
+ .default({}),
67
119
  });
68
120
 
69
121
  const Compose = z.looseObject({ services: z.record(z.string(), z.looseObject({ image: z.string().optional() })).default({}) });
@@ -72,6 +124,14 @@ const Template = z.looseObject({ labels: z.union([z.string(), z.array(z.string()
72
124
 
73
125
  const TEMPLATE_FRONT_MATTER = /^---\n([\s\S]*?)\n---/;
74
126
 
127
+ /** A YAML file read through `schema`, or undefined when the file does not parse or does not fit it. */
128
+ const yamlOf = <Schema extends z.ZodType>(schema: Schema, text: string): z.output<Schema> | undefined => {
129
+ const document = parseDocument(text);
130
+ const parsed = document.errors.length === 0 ? schema.safeParse(document.toJS()) : undefined;
131
+
132
+ return parsed?.success ? parsed.data : undefined;
133
+ };
134
+
75
135
  const commandsOf = (run: string): string[] =>
76
136
  run
77
137
  .split("\n")
@@ -81,22 +141,26 @@ const commandsOf = (run: string): string[] =>
81
141
  /** The CI workflows' jobs. A workflow that does not parse is skipped, because the owner's CI is not setup's to judge. */
82
142
  const ciJobsOf = (repo: string): CiJob[] =>
83
143
  filesIn(repo, `${WORKFLOW_FOLDER}/*.{yml,yaml}`).flatMap((file) => {
84
- const parsed = Workflow.safeParse(parseYaml(textOf(repo, file)));
144
+ const workflow = yamlOf(Workflow, textOf(repo, file));
85
145
 
86
- if (!parsed.success) return [];
146
+ if (workflow === undefined) return [];
87
147
 
88
- const triggers = parsed.data.on;
148
+ const triggers = workflow.on;
89
149
 
90
- return Object.entries(parsed.data.jobs).map(([job, { steps }]) => ({
150
+ return Object.entries(workflow.jobs).map(([job, { steps, ...where }]) => ({
91
151
  file: basename(file),
92
152
  job,
93
153
  triggers,
94
154
  commands: steps.flatMap((step) => commandsOf(step.run ?? "")),
155
+ runner: where["runs-on"],
156
+ container: where.container,
157
+ env: { ...workflow.env, ...where.env },
158
+ actions: steps.flatMap((step) => (step.uses === undefined ? [] : [{ uses: step.uses, with: step.with }])),
95
159
  }));
96
160
  });
97
161
 
98
162
  const codeownersOf = (repo: string): RepoScan["codeowners"] => {
99
- const file = CODEOWNERS_FILES.find((candidate) => exists(repo, candidate));
163
+ const file = CODEOWNERS_FILES.find((candidate) => doesExist(repo, candidate));
100
164
 
101
165
  return textOf(repo, file ?? "")
102
166
  .split("\n")
@@ -105,10 +169,10 @@ const codeownersOf = (repo: string): RepoScan["codeowners"] => {
105
169
  };
106
170
 
107
171
  const composeOf = (repo: string): RepoScan["composeServices"] => {
108
- const file = COMPOSE_FILES.find((candidate) => exists(repo, candidate));
109
- const parsed = Compose.safeParse(parseYaml(textOf(repo, file ?? "")));
172
+ const file = COMPOSE_FILES.find((candidate) => doesExist(repo, candidate));
173
+ const compose = yamlOf(Compose, textOf(repo, file ?? ""));
110
174
 
111
- return parsed.success ? Object.entries(parsed.data.services).map(([name, { image }]) => ({ name, image })) : [];
175
+ return compose ? Object.entries(compose.services).map(([name, { image }]) => ({ name, image })) : [];
112
176
  };
113
177
 
114
178
  /** The environment scripts a repo is built to run: executable files in the usual places. */
@@ -127,9 +191,9 @@ const templatesOf = (repo: string): RepoScan["issueTemplates"] =>
127
191
  filesIn(repo, `${ISSUE_TEMPLATE_FOLDER}/*`).flatMap((file) => {
128
192
  const text = textOf(repo, file);
129
193
  const front = file.endsWith(".md") ? TEMPLATE_FRONT_MATTER.exec(text)?.[1] ?? "" : text;
130
- const parsed = Template.safeParse(parseYaml(front));
194
+ const template = yamlOf(Template, front);
131
195
 
132
- return parsed.success ? [{ file: basename(file), labels: [parsed.data.labels].flat().flatMap((label) => label.split(",").map((one) => one.trim()).filter(Boolean)) }] : [];
196
+ return template ? [{ file: basename(file), labels: [template.labels].flat().flatMap((label) => label.split(",").map((one) => one.trim()).filter(Boolean)) }] : [];
133
197
  });
134
198
 
135
199
  const trackedOf = async (repo: string): Promise<string[]> => (await gitIn(repo, { timeoutMs: SHIPPED_COMMAND_TIMEOUT_MS }).raw(["ls-files"])).split("\n").filter(Boolean).slice(0, TRACKED_FILE_LIMIT);
@@ -143,14 +207,13 @@ const foldersOf = async (repo: string, base: string): Promise<FolderHistory[]> =
143
207
 
144
208
  if (log.code !== 0) return [];
145
209
 
146
- const changes = await readHistory(git, base, SHIPPED_DEFAULTS);
147
- const folders = new Map<string, number[]>();
210
+ const touches = (await readHistory(git, base, SHIPPED_DEFAULTS)).flatMap(({ files, size }) => [...new Set(files.map(topFolder).filter(Boolean))].map((folder) => ({ folder, size })));
148
211
 
149
- for (const change of changes) {
150
- for (const folder of new Set(change.files.map(topFolder).filter(Boolean))) folders.set(folder, [...(folders.get(folder) ?? []), change.size]);
151
- }
212
+ return [...new Set(touches.map(({ folder }) => folder))].map((folder) => {
213
+ const sizes = touches.flatMap((touch) => (touch.folder === folder ? [touch.size] : []));
152
214
 
153
- return [...folders].map(([folder, sizes]) => ({ folder, changes: sizes.length, sizes: sizes.toReversed() }));
215
+ return { folder, changes: sizes.length, sizes: sizes.toReversed() };
216
+ });
154
217
  };
155
218
 
156
219
  const humSchemaOf = (repo: string): number | undefined => {
@@ -164,7 +227,7 @@ export const scanRepo = async (repo: string, base: string): Promise<RepoScan> =>
164
227
  const manifest = PackageJson.safeParse(orMissing(() => JSON.parse(textOf(repo, "package.json") || "null"), null));
165
228
  const scripts = manifest.success ? manifest.data.scripts : {};
166
229
  const pinned = manifest.success ? { ...manifest.data.dependencies, ...manifest.data.devDependencies }["@moo.md/hum"] : undefined;
167
- const lockfile = Object.entries(LOCKFILES).find(([file]) => exists(repo, file));
230
+ const lockfile = Object.entries(LOCKFILES).find(([file]) => doesExist(repo, file));
168
231
 
169
232
  return {
170
233
  packageManager: lockfile?.[1],
@@ -174,9 +237,9 @@ export const scanRepo = async (repo: string, base: string): Promise<RepoScan> =>
174
237
  composeServices: composeOf(repo),
175
238
  envScripts: envScriptsOf(repo),
176
239
  setupTargets: setupTargetsOf(repo, scripts),
177
- toolVersions: TOOL_VERSION_FILES.filter((file) => exists(repo, file)),
178
- envExamples: ENV_EXAMPLE_FILES.filter((file) => exists(repo, file)),
179
- envTooling: ENV_TOOLING_FILES.filter((file) => exists(repo, file)),
240
+ toolVersions: TOOL_VERSION_FILES.filter((file) => doesExist(repo, file)),
241
+ envExamples: ENV_EXAMPLE_FILES.filter((file) => doesExist(repo, file)),
242
+ envTooling: ENV_TOOLING_FILES.filter((file) => doesExist(repo, file)),
180
243
  issueTemplates: templatesOf(repo),
181
244
  tracked: await trackedOf(repo),
182
245
  folders: await foldersOf(repo, base),
@@ -1,9 +1,11 @@
1
1
  import { join } from "node:path";
2
+ import type { GitIdentityRead } from "../adapters/git.ts";
2
3
  import { type RawConfig, readConfigDir } from "../config/load.ts";
3
- import { DefaultsConfig, Kind } from "../config/schema.ts";
4
+ import { noGitIdentity, type Result } from "../config/refusal.ts";
5
+ import { DefaultsConfig, type HumConfig, Kind } from "../config/schema.ts";
4
6
 
5
7
  /** Where the shipped defaults sit, in the package or in the owner's `node_modules`. */
6
- export const DEFAULTS_DIR = join(import.meta.dir, "..", "..", "defaults");
8
+ const DEFAULTS_DIR = join(import.meta.dir, "..", "..", "defaults");
7
9
 
8
10
  export const shippedRaw = (): RawConfig => readConfigDir(DEFAULTS_DIR);
9
11
 
@@ -13,3 +15,7 @@ export const shippedConfig = () => {
13
15
 
14
16
  return { hum: DefaultsConfig.parse(raw.hum), kinds: Object.fromEntries(Object.entries(raw.kinds).map(([name, file]) => [name, Kind.parse(file)])) };
15
17
  };
18
+
19
+ /** The shipped settings as an owner's own: they commit as the identity git config holds, and refuse without one. */
20
+ export const shippedSettingsAs = (git: GitIdentityRead): Result<HumConfig> =>
21
+ git.found ? { ok: true, value: { ...DefaultsConfig.parse(shippedRaw().hum), commitIdentity: git.identity } } : { ok: false, refusal: noGitIdentity(git.missing) };
@@ -26,7 +26,7 @@ export const INSTALL_COMMANDS = {
26
26
  } as const satisfies Record<PackageManager, string>;
27
27
 
28
28
  /** The command that runs a package script, per package manager that has scripts. */
29
- export const RUN_SCRIPT: Readonly<Record<PackageManager, string | undefined>> = { bun: "bun run", pnpm: "pnpm run", yarn: "yarn", npm: "npm run", uv: undefined, poetry: undefined, cargo: undefined, go: undefined };
29
+ export const RUN_SCRIPT = { bun: "bun run", pnpm: "pnpm run", yarn: "yarn", npm: "npm run", uv: undefined, poetry: undefined, cargo: undefined, go: undefined } as const satisfies Record<PackageManager, string | undefined>;
30
30
 
31
31
  /** Package scripts that check a change, in the order a repo's own run gives them. */
32
32
  export const CHECK_SCRIPTS = ["check", "typecheck", "lint", "test"] as const;
@@ -40,9 +40,30 @@ export const CHECK_COMMAND = /\b(test|tests|lint|typecheck|type-check|tsc|check|
40
40
  /** A CI command line that is not a check, whatever words it holds: installs, publishing, shell plumbing. */
41
41
  export const NOT_A_CHECK = /^(echo|export|cd|mkdir|cp|mv|rm|curl|wget|sudo|gh|git)\b|\b(install|publish|deploy|release|upload|setup)\b/;
42
42
 
43
+ /** A CI command line that installs or runs Claude Code. */
44
+ export const CLAUDE_COMMAND = /@anthropic-ai\/claude-code|(^|[\s;&|(])claude(\s|$)/;
45
+
46
+ /** The action a CI step runs Claude Code with, named without its version. */
47
+ export const CLAUDE_ACTION = "anthropics/claude-code-action";
48
+
49
+ /** The action's inputs that sign Claude Code in: an API key, and the OAuth token `claude setup-token` makes. */
50
+ export const CLAUDE_ACTION_SIGN_IN = { apiKey: "anthropic_api_key", oauthToken: "claude_code_oauth_token" } as const;
51
+
52
+ /** The env name Claude Code reads an API key from. */
53
+ export const CLAUDE_API_KEY = "ANTHROPIC_API_KEY";
54
+
55
+ /** Env that signs Claude Code in with no OAuth token: a key, a gateway's token, or a cloud provider whose own credentials the job holds. */
56
+ export const CLAUDE_CREDENTIAL_ENV: ReadonlySet<string> = new Set([CLAUDE_API_KEY, "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CODE_USE_FOUNDRY"]);
57
+
58
+ /** An input or env value that is one secret, which the first group names. */
59
+ export const SECRET_VALUE = /^\$\{\{\s*secrets\.(\w+)\s*\}\}$/;
60
+
43
61
  /** The files that hold a repo's tool versions. */
44
62
  export const TOOL_VERSION_FILES = [".tool-versions", ".nvmrc", ".node-version", ".bun-version", ".python-version", "mise.toml", ".mise.toml", "rust-toolchain.toml", ".go-version"] as const;
45
63
 
64
+ /** Where owners keep a script that sets up a working environment, in the order a repo's own convention is preferred. */
65
+ export const ENV_SCRIPTS = ["bin/setup", "script/setup", "scripts/setup", "scripts/setup.sh", "bin/env", "scripts/env", "scripts/env.sh"] as const;
66
+
46
67
  export const ENV_EXAMPLE_FILES = [".env.example", ".env.sample", ".env.template"] as const;
47
68
 
48
69
  /** The owner's own environment tooling: a recipe calls it and rebuilds nothing. */
@@ -95,7 +116,5 @@ export const KIND_LABEL_WORDS = {
95
116
  /** Hours a wait gets before it ends stuck, by who it waits on. */
96
117
  export const WAIT_HOURS = { owner: 72, other: 24 } as const;
97
118
 
98
- export const HOUR_MS = 3_600_000;
99
-
100
119
  /** Tracked files setup reads the repo's shape from, at most. */
101
120
  export const TRACKED_FILE_LIMIT = 50_000;
@@ -1,5 +1,6 @@
1
1
  import { OWNER_WAIT_TAG, STUCK_TAG, WAIT_TAG, type Kind, type StateNodeJSON } from "../config/schema.ts";
2
- import { HOUR_MS, WAIT_HOURS } from "./tables.ts";
2
+ import { HOUR_MS } from "../time.ts";
3
+ import { WAIT_HOURS } from "./tables.ts";
3
4
 
4
5
  /** A state a kind's machine waits in, with the hours its timeout proposes. */
5
6
  export type Wait = { readonly kind: string; readonly state: string; readonly waitsOn: "owner" | "other"; readonly hours: number };
@@ -8,7 +9,7 @@ export type Wait = { readonly kind: string; readonly state: string; readonly wai
8
9
  export type WaitAnswers = Readonly<Record<string, number>>;
9
10
 
10
11
  /** The key a wait's answer sits under. */
11
- export const waitKey = ({ kind, state }: Pick<Wait, "kind" | "state">): string => `${kind}/${state}`;
12
+ const waitKey = ({ kind, state }: Pick<Wait, "kind" | "state">): string => `${kind}/${state}`;
12
13
 
13
14
  const isOwnerWait = (tags: readonly string[] | undefined): boolean => tags?.includes(OWNER_WAIT_TAG) ?? false;
14
15
 
@@ -27,24 +28,21 @@ export const waitsOf = (kinds: Readonly<Record<string, Kind>>): Wait[] =>
27
28
  );
28
29
 
29
30
  /** The state a timed-out wait goes to: the kind's first stuck state. */
30
- const stuckStateOf = (kind: string, config: Kind): string => {
31
- const stuck = Object.entries(config.machine.states).find(([, node]) => node.tags?.includes(STUCK_TAG));
32
-
33
- if (!stuck) throw new Error(`kind "${kind}" has no state tagged "${STUCK_TAG}" for a timed-out wait to go to`);
34
-
35
- return stuck[0];
36
- };
31
+ const stuckStateOf = (config: Kind): string | undefined => Object.entries(config.machine.states).find(([, node]) => node.tags?.includes(STUCK_TAG))?.[0];
37
32
 
38
33
  const hasTimeout = (node: StateNodeJSON): boolean => node.timeout !== undefined || Object.keys(node.after ?? {}).length > 0;
39
34
 
40
35
  /**
41
36
  * The kinds with a timeout on every wait: the hours answered, else the proposed hours. A timed-out wait ends stuck.
42
- * A wait that already has a timeout keeps it.
37
+ * A wait that already has a timeout keeps it. A kind with no stuck state stays as it is, so the config check refuses its waits.
43
38
  */
44
39
  export const withTimeouts = (kinds: Readonly<Record<string, Kind>>, answers: WaitAnswers): Record<string, Kind> =>
45
40
  Object.fromEntries(
46
41
  Object.entries(kinds).map(([kind, config]) => {
47
- const stuck = stuckStateOf(kind, config);
42
+ const stuck = stuckStateOf(config);
43
+
44
+ if (stuck === undefined) return [kind, config];
45
+
48
46
  const hoursOf = new Map(waitsOf({ [kind]: config }).map((wait) => [wait.state, answers[waitKey(wait)] ?? wait.hours]));
49
47
 
50
48
  const states = Object.entries(config.machine.states).map(([state, node]): [string, StateNodeJSON] => {