@moo.md/hum 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/defaults/hum.json +5 -0
  2. package/defaults/roles/build.md +1 -1
  3. package/defaults/roles/fix.md +1 -1
  4. package/npm-shrinkwrap.json +3297 -0
  5. package/package.json +6 -2
  6. package/release.json +3 -0
  7. package/schema/hum.schema.json +47 -7
  8. package/scripts/eval.ts +21 -5
  9. package/src/adapter-api.ts +3 -1
  10. package/src/adapters/claude-bg.ts +2 -2
  11. package/src/adapters/claude-p.ts +44 -18
  12. package/src/adapters/contract.ts +12 -0
  13. package/src/adapters/fake.ts +5 -0
  14. package/src/adapters/git.ts +61 -9
  15. package/src/adapters/github-client.ts +15 -0
  16. package/src/adapters/github-commits.ts +84 -0
  17. package/src/adapters/github.ts +9 -0
  18. package/src/adapters/guard.ts +1 -0
  19. package/src/adapters/item-file.ts +1 -1
  20. package/src/adapters/markdown.ts +10 -1
  21. package/src/adapters/pull-requests.ts +8 -8
  22. package/src/adapters/registry.ts +3 -6
  23. package/src/adapters/roundup.ts +3 -0
  24. package/src/bytes.ts +1 -0
  25. package/src/cli/service.ts +176 -29
  26. package/src/cli/setup.ts +4 -5
  27. package/src/config/checks.ts +21 -50
  28. package/src/config/load.ts +2 -3
  29. package/src/config/machine.ts +29 -0
  30. package/src/config/refusal.ts +5 -6
  31. package/src/config/schema.ts +23 -7
  32. package/src/config/wake-job.ts +6 -2
  33. package/src/decide/risk.ts +2 -2
  34. package/src/exec.ts +10 -0
  35. package/src/index.ts +1 -1
  36. package/src/loop/records.ts +8 -1
  37. package/src/measure/rate.ts +14 -0
  38. package/src/publish/bundle.ts +128 -0
  39. package/src/publish/handoff.ts +107 -0
  40. package/src/publish/handover.ts +182 -0
  41. package/src/publish/intents.ts +61 -0
  42. package/src/publish/publisher.ts +259 -0
  43. package/src/publish/wake.ts +78 -0
  44. package/src/service/ci-state.ts +99 -0
  45. package/src/service/plugins.ts +137 -0
  46. package/src/service/wake.ts +3 -1
  47. package/src/service/workflows.ts +122 -28
  48. package/src/setup/propose.ts +17 -4
  49. package/src/setup/prove.ts +3 -3
  50. package/src/setup/write.ts +2 -2
  51. package/src/state/items.ts +17 -8
  52. package/src/state/open.ts +20 -6
  53. package/src/state/records.ts +7 -0
  54. package/src/state/runs.ts +5 -0
  55. package/src/state/saved.ts +17 -2
  56. package/src/worker/base-check.ts +41 -13
  57. package/src/worker/checks.ts +3 -2
  58. package/src/worker/evidence.ts +72 -0
  59. package/src/worker/kind.ts +4 -7
  60. package/src/worker/land.ts +173 -81
  61. package/src/worker/merged.ts +20 -8
  62. package/src/worker/open.ts +33 -17
  63. package/src/worker/questions.ts +16 -8
  64. package/src/worker/signed-push.ts +167 -0
  65. package/src/worker/thin-path.ts +245 -133
  66. package/src/worker/worker.ts +50 -9
  67. package/surface.json +185 -56
@@ -1,12 +1,14 @@
1
1
  import { Document, visit } from "yaml";
2
2
  import { CLAUDE_FLOOR } from "../adapters/claude-p.ts";
3
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
+ import { APP_TOKEN_ACTION, APP_TOKEN_MINUTES, CLAUDE_TOKEN, readsSecrets, secretsNamed, TRUSTED_ASSOCIATIONS, WAKE_ENV as ENV, WORKFLOW_FILES } from "../config/wake-job.ts";
5
+ import { ENGINE_VERSION } from "../state/format.ts";
6
+ import { MEGABYTE } from "../bytes.ts";
5
7
 
6
8
  /** The settings the workflows are built from. */
7
9
  export type WorkflowSettings = Pick<
8
10
  HumConfig,
9
- "runBranchPrefix" | "itemsDir" | "ciSchedule" | "commitIdentity" | "ciWakeTimeoutMinutes" | "pullRequestToken" | "ciRunner" | "ciContainer" | "ciEnv" | "ciClaudeAuth"
11
+ "runBranchPrefix" | "itemsDir" | "ciSchedule" | "commitIdentity" | "ciWakeTimeoutMinutes" | "ciOutboxMaxMegabytes" | "pullRequestToken" | "ciRunner" | "ciContainer" | "ciEnv" | "ciClaudeAuth"
10
12
  >;
11
13
 
12
14
  /** The type of the `repository_dispatch` event a tracker's webhook sends. */
@@ -14,8 +16,6 @@ const DISPATCH_EVENT = "hum-wake";
14
16
 
15
17
  const WAKE_PATH = `./.github/workflows/${WORKFLOW_FILES.wake}`;
16
18
 
17
- const HOPE_MARKETPLACE = "saadshahd/moo.md";
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
 
@@ -26,12 +26,17 @@ const BUN_VERSION = Bun.version;
26
26
  const ACTIONS = {
27
27
  checkout: { uses: "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1", release: "v7.0.1" },
28
28
  appToken: { uses: `${APP_TOKEN_ACTION}@64ab729a6294000f5aa4a4bc0b73d1f32bc45510`, release: "v3.3.0" },
29
+ upload: { uses: "actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9", release: "v7.0.2" },
30
+ download: { uses: "actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333", release: "v8.0.2" },
29
31
  } as const;
30
32
 
31
33
  const RELEASE_OF: ReadonlyMap<string, string> = new Map(Object.values(ACTIONS).map(({ uses, release }) => [uses, release]));
32
34
 
33
35
  const PERMISSIONS = { contents: "write", issues: "write", "pull-requests": "write" } as const;
34
36
 
37
+ /** The workflow token's permissions: the App's, and reading the run's artifacts, which the publish job sizes before it downloads one. */
38
+ const WORKFLOW_PERMISSIONS = { ...PERMISSIONS, actions: "read" } as const;
39
+
35
40
  /** One wake at a time: a second event waits for the first run instead of racing it. */
36
41
  const CONCURRENCY = { group: "hum-wake", "cancel-in-progress": false } as const;
37
42
 
@@ -52,7 +57,7 @@ type TriggerJob = { readonly if?: string };
52
57
  const trigger = (name: string, on: TriggerEvents, job: TriggerJob = {}) => ({
53
58
  name,
54
59
  on,
55
- permissions: PERMISSIONS,
60
+ permissions: WORKFLOW_PERMISSIONS,
56
61
  concurrency: CONCURRENCY,
57
62
  jobs: { wake: { ...job, uses: WAKE_PATH, secrets: "inherit" } },
58
63
  });
@@ -99,18 +104,27 @@ const CLAUDE_SIGN_IN = {
99
104
 
100
105
  /**
101
106
  * 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.
107
+ * holds it. An App's token is minted with the workflow token's permissions, so both hold the same rights. A wake
108
+ * whose App secrets are unset stops at its first step and says which: with the workflow token in their place, the
109
+ * pull requests it opened would start no checks. A secret's token falls back to the workflow token while it is unset.
103
110
  */
104
111
  const githubToken = (source: PullRequestToken) =>
105
112
  source.from === "secret"
106
- ? { secrets: { [source.secret]: OPTIONAL_SECRET }, env: {}, steps: [], token: `\${{ secrets.${source.secret} || github.token }}` }
113
+ ? { secrets: { [source.secret]: OPTIONAL_SECRET }, env: {}, check: [], steps: [], token: `\${{ secrets.${source.secret} || github.token }}` }
107
114
  : {
108
115
  secrets: { [source.clientIdSecret]: OPTIONAL_SECRET, [source.privateKeySecret]: OPTIONAL_SECRET },
109
- env: { [ENV.hasApp]: `\${{ secrets.${source.clientIdSecret} != '' }}` },
116
+ env: { [ENV.hasApp]: `\${{ secrets.${source.clientIdSecret} != '' && secrets.${source.privateKeySecret} != '' }}` },
117
+ check: [
118
+ {
119
+ if: `env.${ENV.hasApp} != 'true'`,
120
+ run: `echo "::error title=hum::The GitHub App secrets ${source.clientIdSecret} and ${source.privateKeySecret} are not both set. A pull request opened with the workflow token starts no checks, so this wake stops. Set both secrets, or change pullRequestToken in .hum/hum.json."
121
+ exit 1
122
+ `,
123
+ },
124
+ ],
110
125
  steps: [
111
126
  {
112
127
  id: APP_TOKEN_STEP,
113
- if: `env.${ENV.hasApp} == 'true'`,
114
128
  uses: ACTIONS.appToken.uses,
115
129
  with: {
116
130
  "client-id": secret(source.clientIdSecret),
@@ -119,7 +133,7 @@ const githubToken = (source: PullRequestToken) =>
119
133
  },
120
134
  },
121
135
  ],
122
- token: `\${{ steps.${APP_TOKEN_STEP}.outputs.token || github.token }}`,
136
+ token: `\${{ steps.${APP_TOKEN_STEP}.outputs.token }}`,
123
137
  };
124
138
 
125
139
  /**
@@ -142,43 +156,123 @@ git config --global --add safe.directory "$GITHUB_WORKSPACE"
142
156
  },
143
157
  });
144
158
 
159
+ /** The inbox gather hands the work job, and the outbox the work job hands publish: one artifact each, kept a day. */
160
+ const HANDOVER = { inbox: "hum-inbox", outbox: "hum-outbox" } as const;
161
+
162
+ const RETENTION_DAYS = 1;
163
+
164
+ /** Where a handover sits on the runner: as an action's input reads it, and as a shell reads it. */
165
+ const handoverPath = (name: string): string => `\${{ runner.temp }}/${name}`;
166
+
167
+ const handoverFolder = (name: string): string => `"$RUNNER_TEMP/${name}"`;
168
+
169
+ const upload = (name: string) => ({ uses: ACTIONS.upload.uses, with: { name, path: handoverPath(name), "retention-days": RETENTION_DAYS, "if-no-files-found": "error" } });
170
+
171
+ const download = (name: string) => ({ uses: ACTIONS.download.uses, with: { name, path: handoverPath(name) } });
172
+
173
+ /** Stops the job before it downloads the artifact `name` when GitHub's artifacts API says it is larger than `maxBytes`, or the run holds no single one. */
174
+ const sizeCheck = (name: string, maxBytes: number) => ({
175
+ env: { [ENV.actionsToken]: "${{ github.token }}" },
176
+ run: `node --input-type=module -e '
177
+ const env = process.env;
178
+ const reply = await fetch(env.GITHUB_API_URL + "/repos/" + env.GITHUB_REPOSITORY + "/actions/runs/" + env.GITHUB_RUN_ID + "/artifacts?name=${name}", { headers: { authorization: "Bearer " + env.${ENV.actionsToken}, accept: "application/vnd.github+json" } });
179
+ if (!reply.ok) throw new Error("GitHub artifacts API answered " + reply.status);
180
+ const { artifacts } = await reply.json();
181
+ if (artifacts.length !== 1) throw new Error("the run holds " + artifacts.length + " artifacts named ${name}");
182
+ if (artifacts[0].size_in_bytes > ${maxBytes}) throw new Error("${name} holds " + artifacts[0].size_in_bytes + " bytes, over the ${maxBytes} bytes publish reads; this wake publishes nothing");
183
+ '
184
+ `,
185
+ });
186
+
187
+ /** What gather settled, as its job output: publish trusts it, and the work job checks out the base it names. */
188
+ const GATHERED = "${{ needs.gather.outputs.gathered }}";
189
+
190
+ const GATHERED_BASE = "${{ fromJSON(needs.gather.outputs.gathered).baseSha }}";
191
+
192
+ /** hum at this engine's own version from npm, which checks the package against the registry's integrity and installs each dependency at the version and hash its shrinkwrap pins; the jobs that hold GitHub's token run this hum and none of the repo's code. */
193
+ const PUBLISHED_HUM = `@moo.md/hum@${ENGINE_VERSION}`;
194
+
195
+ /** The tools every job installs at exact versions, each with the one install script that fetches its native binary. */
196
+ const TOOLS = [
197
+ { spec: `bun@${BUN_VERSION}`, folder: "bun", script: "install.js" },
198
+ { spec: `@anthropic-ai/claude-code@${CLAUDE_FLOOR}`, folder: "@anthropic-ai/claude-code", script: "install.cjs" },
199
+ ] as const;
200
+
201
+ /**
202
+ * Installs the tools, and `extra` packages, with no package's install script, so no dependency of theirs runs code at
203
+ * install; then the tools' own scripts alone fetch their native binaries.
204
+ */
205
+ const installTools = (extra = "") => ({
206
+ run: [`npm install --global --prefix "${JOB_TOOLS}" --ignore-scripts ${TOOLS.map(({ spec }) => spec).join(" ")}${extra}`, ...TOOLS.map(({ folder, script }) => `(cd "${JOB_TOOLS}/lib/node_modules/${folder}" && node ${script})`)].join("\n"),
207
+ });
208
+
209
+ /** Git in a job container trusts the checkout the runner's user owns; the global config is the job's own file. */
210
+ const SAFE_CHECKOUT = { run: 'git config --global --add safe.directory "$GITHUB_WORKSPACE"\n' } as const;
211
+
145
212
  /**
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.
213
+ * The wake, as three jobs. `gather` and `publish` hold GitHub's token and run hum as published, with none of the
214
+ * repo's code: no install of its packages, no hook and no check; each mints an App's token at its end, inside the
215
+ * token's hour. `work` holds no GitHub token: its workflow token reads the repo alone and stays out of the checkout,
216
+ * and everything it needs from GitHub reaches it in gather's inbox. Its runs and the repo's checks run there, and what
217
+ * they made goes to publish as the outbox, which publish checks before any write. The Claude sign-in and every `ciEnv`
218
+ * value that reads a secret reach the steps that run hum alone. A runner GitHub does not host keeps what a job leaves,
219
+ * so a process a run left could outlive the work job there: ephemeral runners close that.
151
220
  */
152
- const wake = ({ commitIdentity, ciWakeTimeoutMinutes, pullRequestToken, ciRunner, ciContainer, ciEnv, ciClaudeAuth }: WorkflowSettings) => {
221
+ const wake = ({ commitIdentity, ciWakeTimeoutMinutes, ciOutboxMaxMegabytes, pullRequestToken, ciRunner, ciContainer, ciEnv, ciClaudeAuth }: WorkflowSettings) => {
153
222
  const claude = CLAUDE_SIGN_IN[ciClaudeAuth];
154
223
  const github = githubToken(pullRequestToken);
155
224
  const env = envByReach(ciEnv);
225
+ const where = { "runs-on": ciRunner, container: ciContainer ?? NO_KEY };
226
+ const humEnv = { ...env.humStep, ...claude.env, [ENV.githubToken]: github.token };
227
+ const checkout = (ref?: string) => ({ uses: ACTIONS.checkout.uses, with: { ...(ref && { ref }), "fetch-depth": 0, "persist-credentials": false } });
228
+
229
+ /** A job that holds GitHub's token: hum from npm, git that pushes as hum, and the token minted last. It installs no plugin: it makes judgment calls alone, which load none. */
230
+ const holdsToken = ({ before, ref, run, permissions = PERMISSIONS }: { readonly before: readonly object[]; readonly ref?: string; readonly run: object; readonly permissions?: typeof PERMISSIONS }) => ({
231
+ ...where,
232
+ permissions,
233
+ "timeout-minutes": APP_TOKEN_MINUTES,
234
+ env: { ...env.everyStep, ...github.env, [ENV.event]: "${{ github.event_name }}" },
235
+ steps: [...github.check, checkout(ref), JOB_PATHS_STEP, installTools(` ${PUBLISHED_HUM}`), gitSetup(commitIdentity), ...before, ...github.steps, run],
236
+ });
156
237
 
157
238
  return {
158
239
  name: "hum wake",
159
240
  on: { workflow_call: { secrets: { ...ownerSecrets({ ciRunner, ciContainer, ciEnv }), ...claude.secrets, ...github.secrets } } },
160
- permissions: PERMISSIONS,
241
+ permissions: {},
161
242
  jobs: {
162
- wake: {
163
- "runs-on": ciRunner,
164
- container: ciContainer ?? NO_KEY,
243
+ gather: {
244
+ ...holdsToken({ before: [], run: { id: "gather", run: `hum wake gather --inbox ${handoverFolder(HANDOVER.inbox)}`, env: humEnv } }),
245
+ outputs: { gathered: "${{ steps.gather.outputs.gathered }}" },
246
+ },
247
+ work: {
248
+ needs: "gather",
249
+ ...where,
250
+ permissions: { contents: "read" },
165
251
  "timeout-minutes": ciWakeTimeoutMinutes,
166
- env: { ...env.everyStep, ...github.env, [ENV.event]: "${{ github.event_name }}" },
252
+ env: Object.keys(env.everyStep).length > 0 ? env.everyStep : NO_KEY,
167
253
  steps: [
168
- { uses: ACTIONS.checkout.uses, with: { "fetch-depth": 0 } },
254
+ checkout(GATHERED_BASE),
169
255
  JOB_PATHS_STEP,
170
- { run: `npm install --global --prefix "${JOB_TOOLS}" bun@${BUN_VERSION} @anthropic-ai/claude-code@${CLAUDE_FLOOR}` },
256
+ installTools(),
171
257
  { 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 } },
258
+ { run: "./node_modules/.bin/hum plugins" },
259
+ SAFE_CHECKOUT,
260
+ download(HANDOVER.inbox),
261
+ { run: `./node_modules/.bin/hum wake work --inbox ${handoverFolder(HANDOVER.inbox)} --outbox ${handoverFolder(HANDOVER.outbox)}`, env: { ...env.humStep, ...claude.env } },
262
+ upload(HANDOVER.outbox),
176
263
  ],
177
264
  },
265
+ publish: {
266
+ needs: ["gather", "work"],
267
+ ...holdsToken({ ref: GATHERED_BASE, permissions: WORKFLOW_PERMISSIONS, before: [sizeCheck(HANDOVER.outbox, ciOutboxMaxMegabytes * MEGABYTE), download(HANDOVER.outbox)], run: { run: `hum wake publish --outbox ${handoverFolder(HANDOVER.outbox)} --event "$${ENV.event}"`, env: { ...humEnv, [ENV.gathered]: GATHERED } } }),
268
+ },
178
269
  },
179
270
  };
180
271
  };
181
272
 
273
+ /** An item push wakes hum only on the default branch: a wake runs the checked-out branch's code with every secret, and anyone who may push a branch could change that code. */
274
+ const ON_DEFAULT_BRANCH = "github.ref_name == github.event.repository.default_branch";
275
+
182
276
  /** 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
277
  const TRUSTED_COMMENT = `github.event.comment.user.type != 'Bot' && contains(fromJSON('${JSON.stringify(TRUSTED_ASSOCIATIONS)}'), github.event.comment.author_association)`;
184
278
 
@@ -202,7 +296,7 @@ const render = (workflow: Workflow): string => {
202
296
  const WORKFLOWS = {
203
297
  [WORKFLOW_FILES.wake]: wake,
204
298
  [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}/**`] } }),
299
+ [WORKFLOW_FILES.push]: ({ itemsDir, runBranchPrefix }) => trigger("hum on item push", { push: { branches: ["**", `!${runBranchPrefix}**`], paths: [`${itemsDir}/**`] } }, { if: ON_DEFAULT_BRANCH }),
206
300
  [WORKFLOW_FILES.dispatch]: () => trigger("hum on dispatch", { repository_dispatch: { types: [DISPATCH_EVENT] } }),
207
301
  [WORKFLOW_FILES.schedule]: ({ ciSchedule }) => trigger("hum on schedule", { schedule: [{ cron: ciSchedule }], workflow_dispatch: null }),
208
302
  } as const satisfies Record<(typeof WORKFLOW_FILES)[keyof typeof WORKFLOW_FILES], (settings: WorkflowSettings) => object>;
@@ -1,7 +1,7 @@
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, PullRequestToken, RunPlace, SlotRecipe } from "../config/schema.ts";
4
+ import type { DefaultsConfig, HumConfig, PathRule, PullRequestToken, RunPlace, Slot, SlotRecipe } from "../config/schema.ts";
5
5
  import { APP_TOKEN_ACTION, CI_WORKFLOW_FILES, CLAUDE_TOKEN, isGitHubHosted, readsForeignContext, WAKE_OWN_ENV } from "../config/wake-job.ts";
6
6
  import type { CiJob, RepoScan } from "./scan.ts";
7
7
  import {
@@ -36,6 +36,8 @@ export type Proposal = {
36
36
  readonly runSlots: Pick<HumConfig["runSlots"], "services" | "recipe">;
37
37
  readonly runPlaces: readonly RunPlace[];
38
38
  readonly wakeJob: Pick<HumConfig, "ciRunner" | "ciContainer" | "ciEnv" | "ciClaudeAuth" | "pullRequestToken">;
39
+ /** The adapter of each slot that does not use the markdown source; empty where the repo keeps no work in issues. */
40
+ readonly integrations: NonNullable<HumConfig["integrations"]>;
39
41
  };
40
42
 
41
43
  const isPullRequestJob = ({ triggers }: CiJob): boolean => triggers.includes("pull_request");
@@ -145,8 +147,18 @@ const claudeEnvOf = (job: CiJob): Record<string, string> => {
145
147
  return Object.fromEntries([...Object.entries(job.env), ...fromInput].filter(([name, value]) => !WAKE_OWN_ENV.has(name) && !readsForeignContext(value)));
146
148
  };
147
149
 
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
+ /** What a scan cannot read from the files: the repo's labels, whether anyone may read and comment on it, and how many issues are open on GitHub. */
151
+ export type RepoFacts = { readonly labels?: readonly string[]; readonly isPublic?: boolean; readonly openIssues?: number };
152
+
153
+ /** The slots GitHub issues serve: the items, the questions on them and the answers to those. */
154
+ const ISSUE_SLOTS = ["work-source", "questions", "answers"] as const satisfies readonly Slot[];
155
+
156
+ /**
157
+ * A repo on GitHub that tracks work in issues, open ones or an issue template, takes its items, questions and answers
158
+ * from them; any other keeps markdown items under `.hum/work`. Without a GitHub read there is no issue to count.
159
+ */
160
+ const integrationsOf = (scan: RepoScan, openIssues: number | undefined): Proposal["integrations"] =>
161
+ openIssues !== undefined && (openIssues > 0 || scan.issueTemplates.length > 0) ? Object.fromEntries(ISSUE_SLOTS.map((slot) => [slot, "github"])) : {};
150
162
 
151
163
  /**
152
164
  * The wake job's settings from the job most like it: the one that runs Claude Code gives its runner, container, env
@@ -174,7 +186,7 @@ const wakeJobOf = (ci: readonly CiJob[], shipped: DefaultsConfig, isPublic: bool
174
186
  };
175
187
 
176
188
  /** Everything setup proposes from a scan, before it asks. */
177
- export const proposeSetup = (scan: RepoScan, shipped: DefaultsConfig, { labels = [], isPublic = false }: RepoFacts = {}): Proposal => {
189
+ export const proposeSetup = (scan: RepoScan, shipped: DefaultsConfig, { labels = [], isPublic = false, openIssues }: RepoFacts = {}): Proposal => {
178
190
  const checks = checksOf(scan);
179
191
 
180
192
  return {
@@ -187,5 +199,6 @@ export const proposeSetup = (scan: RepoScan, shipped: DefaultsConfig, { labels =
187
199
  runSlots: { services: shipped.runSlots.services, recipe: recipeOf(scan, checks) },
188
200
  runPlaces: shipped.runPlaces,
189
201
  wakeJob: wakeJobOf(scan.ci, shipped, isPublic),
202
+ integrations: integrationsOf(scan, openIssues),
190
203
  };
191
204
  };
@@ -40,7 +40,7 @@ export type ProveEnv = {
40
40
  readonly now: () => number;
41
41
  readonly processEnv: Env;
42
42
  readonly newSessionId: () => string;
43
- readonly hopeSkills: ReadonlySet<string>;
43
+ readonly installedSkills: ReadonlySet<string>;
44
44
  readonly base: string;
45
45
  /** Whether to run one item end to end through the real `claude`; each run spends live calls. */
46
46
  readonly item: boolean;
@@ -76,7 +76,7 @@ const pinOf = (repo: string): string | undefined => {
76
76
  };
77
77
 
78
78
  const configStep = (repo: string, env: ProveEnv): Outcome & { readonly config?: Config } => {
79
- const loaded = loadConfig(readConfigDir(join(repo, ".hum")), { env: { hopeSkills: env.hopeSkills } });
79
+ const loaded = loadConfig(readConfigDir(join(repo, ".hum")), { env: { installedSkills: env.installedSkills } });
80
80
 
81
81
  return loaded.ok ? { ...passed("every state is reachable, reaches done or stuck, and every wait has a timeout"), config: loaded.value } : failed(loaded.refusal.message);
82
82
  };
@@ -178,7 +178,7 @@ const runItem = async (scratch: Scratch, env: ProveEnv): Promise<Outcome> => {
178
178
  now: env.now,
179
179
  env: env.processEnv,
180
180
  newSessionId: env.newSessionId,
181
- hopeSkills: env.hopeSkills,
181
+ installedSkills: env.installedSkills,
182
182
  holder: Holder.parse("setup-proof"),
183
183
  base: env.base,
184
184
  where: "ci",
@@ -36,7 +36,7 @@ export const SetupAnswers = z.strictObject({
36
36
  export type SetupAnswers = z.infer<typeof SetupAnswers>;
37
37
 
38
38
  export type SetupEnv = {
39
- readonly hopeSkills: ReadonlySet<string>;
39
+ readonly installedSkills: ReadonlySet<string>;
40
40
  /** Where a Mac or Linux service unit is written; default the user's home. */
41
41
  readonly home?: string;
42
42
  readonly platform?: NodeJS.Platform;
@@ -144,7 +144,7 @@ export const writeSetup = (repo: string, answers: SetupAnswers, env: SetupEnv):
144
144
  const timed = withTimeouts(parsedKinds(base), answers.waitHours);
145
145
  const kinds = Object.fromEntries(Object.entries(base.kinds).map(([name, file]) => [name, timed[name] ? asJson(timed[name]) : file]));
146
146
  const roles = { ...shipped.roles, ...existing?.roles };
147
- const loaded = loadConfig({ hum: asJson(hum), kinds, roles }, { env: { hopeSkills: env.hopeSkills } });
147
+ const loaded = loadConfig({ hum: asJson(hum), kinds, roles }, { env: { installedSkills: env.installedSkills } });
148
148
 
149
149
  if (!loaded.ok) return { ok: false, refusal: loaded.refusal };
150
150
 
@@ -52,6 +52,15 @@ export const persistedSnapshot = (actor: AnyActor): Json => Json.parse(JSON.pars
52
52
 
53
53
  const reason = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause));
54
54
 
55
+ /** The cards an item's saved state raises: the only cards a work job hands publish. */
56
+ export const SNAPSHOT_CARDS = {
57
+ writeFailed: "snapshot-write-failed",
58
+ unreadable: "snapshot-unreadable",
59
+ restoreError: "snapshot-restore-error",
60
+ newerEngine: "snapshot-from-newer-engine",
61
+ machineUnknown: "snapshot-machine-unknown",
62
+ } as const;
63
+
55
64
  const DAMAGED_FIX = "Restore the file from a backup, or delete it to start the item over; the other items go on.";
56
65
 
57
66
  /** Per-item snapshots under `items/`. Every failure becomes one fault card; nothing is thrown for bad data. */
@@ -86,7 +95,7 @@ export class Items {
86
95
  return {
87
96
  ok: false,
88
97
  fault: this.#faults.raise({
89
- code: "snapshot-write-failed",
98
+ code: SNAPSHOT_CARDS.writeFailed,
90
99
  item: itemId,
91
100
  cause: `The state of ${itemId} could not be saved: ${reason(error)}. The last saved state is kept.`,
92
101
  fix: "Free disk space where hum keeps its state; the next change saves it again.",
@@ -94,7 +103,7 @@ export class Items {
94
103
  };
95
104
  }
96
105
 
97
- this.#faults.clear({ code: "snapshot-write-failed", item: itemId });
106
+ this.#faults.clear({ code: SNAPSHOT_CARDS.writeFailed, item: itemId });
98
107
 
99
108
  return { ok: true, value: undefined };
100
109
  }
@@ -131,8 +140,8 @@ export class Items {
131
140
  */
132
141
  async restore(itemId: string, kind: Kind, { kindAt, sources = {}, clock }: RestoreOptions = {}): Promise<Outcome<AnyActor | undefined>> {
133
142
  const file = this.path(itemId);
134
- const unreadable = (why: string) => this.#fault({ itemId, code: "snapshot-unreadable", cause: `The saved state of ${itemId} at ${file} is damaged: ${why}.`, fix: DAMAGED_FIX });
135
- const unrestorable = (why: string) => this.#fault({ itemId, code: "snapshot-restore-error", cause: `The saved state of ${itemId} does not restore: ${why}.`, fix: DAMAGED_FIX });
143
+ const unreadable = (why: string) => this.#fault({ itemId, code: SNAPSHOT_CARDS.unreadable, cause: `The saved state of ${itemId} at ${file} is damaged: ${why}.`, fix: DAMAGED_FIX });
144
+ const unrestorable = (why: string) => this.#fault({ itemId, code: SNAPSHOT_CARDS.restoreError, cause: `The saved state of ${itemId} does not restore: ${why}.`, fix: DAMAGED_FIX });
136
145
  let parsed: Json;
137
146
 
138
147
  try {
@@ -142,7 +151,7 @@ export class Items {
142
151
 
143
152
  if (error instanceof SyntaxError) return unreadable(error.message);
144
153
 
145
- return this.#fault({ itemId, code: "snapshot-unreadable", cause: `The saved state of ${itemId} at ${file} cannot be read: ${reason(error)}.`, fix: "Fix the file's permissions or restore it from a backup; the other items go on." });
154
+ return this.#fault({ itemId, code: SNAPSHOT_CARDS.unreadable, cause: `The saved state of ${itemId} at ${file} cannot be read: ${reason(error)}.`, fix: "Fix the file's permissions or restore it from a backup; the other items go on." });
146
155
  }
147
156
 
148
157
  const header = Header.safeParse(parsed);
@@ -150,7 +159,7 @@ export class Items {
150
159
  if (!header.success) return unreadable("it has no format or engine version");
151
160
 
152
161
  if (header.data.format > this.#format || isFromNewerEngine({ written: header.data.engineVersion, running: this.#engineVersion })) {
153
- return this.#fault({ itemId, code: "snapshot-from-newer-engine", cause: `The saved state of ${itemId} was written by hum ${header.data.engineVersion}, which is newer than the running ${this.#engineVersion}.`, fix: "Update the engine to that version or later: bun add --exact @moo.md/hum@latest." });
162
+ return this.#fault({ itemId, code: SNAPSHOT_CARDS.newerEngine, cause: `The saved state of ${itemId} was written by hum ${header.data.engineVersion}, which is newer than the running ${this.#engineVersion}.`, fix: "Update the engine to that version or later: bun add --exact @moo.md/hum@latest." });
154
163
  }
155
164
 
156
165
  let envelope: ReturnType<typeof Envelope.safeParse>;
@@ -171,12 +180,12 @@ export class Items {
171
180
  const previous = kindAt?.(machineVersion);
172
181
 
173
182
  if (!previous) {
174
- return this.#fault({ itemId, code: "snapshot-machine-unknown", cause: `${itemId} was saved under version ${machineVersion} of its machine, and this config holds no map from it.`, fix: "Add a stateMap for that version to the kind file, or delete the item's saved state." });
183
+ return this.#fault({ itemId, code: SNAPSHOT_CARDS.machineUnknown, cause: `${itemId} was saved under version ${machineVersion} of its machine, and this config holds no map from it.`, fix: "Add a stateMap for that version to the kind file, or delete the item's saved state." });
175
184
  }
176
185
 
177
186
  current = await migrateSnapshot(previous, kind, snapshot, sources);
178
187
  } catch (error) {
179
- return this.#fault({ itemId, code: "snapshot-restore-error", cause: `${itemId} could not move from machine version ${machineVersion} to ${kind.machine.version}: ${reason(error)}.`, fix: "Map the state in the kind's stateMap, or delete the item's saved state." });
188
+ return this.#fault({ itemId, code: SNAPSHOT_CARDS.restoreError, cause: `${itemId} could not move from machine version ${machineVersion} to ${kind.machine.version}: ${reason(error)}.`, fix: "Map the state in the kind's stateMap, or delete the item's saved state." });
180
189
  }
181
190
  }
182
191
 
package/src/state/open.ts CHANGED
@@ -10,7 +10,17 @@ import { Choice } from "../status/format.ts";
10
10
  import { OpKeys } from "./ops.ts";
11
11
  import { Records } from "./records.ts";
12
12
  import { RunRecords } from "./runs.ts";
13
- import { ItemKind, Landing, Learned, Limit, Parked, QueuedQuestion, ReadyList, SavedPlan, SettledAnswer, Slot, Spent, Verdict } from "./saved.ts";
13
+ import { FiledFollowUp, ItemKind, Landing, Learned, Limit, Parked, PullRequestText, QueuedQuestion, ReadyList, SavedPlan, SettledAnswer, Slot, Spent, Verdict } from "./saved.ts";
14
+
15
+ /** Names under the state folder that other modules address by name. */
16
+ export const STATUS_FILE = "status.json";
17
+ export const HEARTBEAT_FILE = "heartbeat.json";
18
+ export const INBOX_DIR = "inbox";
19
+ export const STOPS_DIR = "stops";
20
+ export const SLOTS_DIR = "slots";
21
+
22
+ /** Publish's own git repo, beside the state, never saved with it. */
23
+ export const PUBLISH_DIR = "publish";
14
24
 
15
25
  /** On the Mac and in a clone, state lives in the repo's git common dir, so every worktree shares it. */
16
26
  export const defaultStateDir = async (cwd: string): Promise<string> => {
@@ -30,13 +40,13 @@ export const openState = (dir: string, { now, ...codec }: StateOptions) => {
30
40
  return {
31
41
  dir,
32
42
  /** The one status file for the repo. */
33
- statusPath: join(dir, "status.json"),
43
+ statusPath: join(dir, STATUS_FILE),
34
44
  /** The worker's heartbeat, one file the service unit reads. */
35
- heartbeatPath: join(dir, "heartbeat.json"),
45
+ heartbeatPath: join(dir, HEARTBEAT_FILE),
36
46
  /** The answer hook drops one file here per posted answer; its content is the item id. */
37
- inbox: join(dir, "inbox"),
47
+ inbox: join(dir, INBOX_DIR),
38
48
  /** A background run's Stop hook drops one file here per stop: the run's session id and transcript path. */
39
- stops: join(dir, "stops"),
49
+ stops: join(dir, STOPS_DIR),
40
50
  faults,
41
51
  items: new Items(join(dir, "items"), faults, now, codec),
42
52
  events: new EventLog(join(dir, "events"), now),
@@ -49,7 +59,7 @@ export const openState = (dir: string, { now, ...codec }: StateOptions) => {
49
59
  limit: new Records(join(dir, "limit"), Limit),
50
60
  ready: new Records(join(dir, "ready"), ReadyList),
51
61
  /** The run slots, by name. */
52
- slots: new Records(join(dir, "slots"), Slot),
62
+ slots: new Records(join(dir, SLOTS_DIR), Slot),
53
63
  landings: new Records(join(dir, "landings"), Landing),
54
64
  /** Path rules by glob. */
55
65
  learned: new Records(join(dir, "learned"), Learned),
@@ -57,8 +67,12 @@ export const openState = (dir: string, { now, ...codec }: StateOptions) => {
57
67
  itemKinds: new Records(join(dir, "item-kinds"), ItemKind),
58
68
  plans: new Records(join(dir, "plans"), SavedPlan),
59
69
  verdicts: new Records(join(dir, "verdicts"), Verdict),
70
+ /** The pull request text the latest build or fix run wrote, by item. */
71
+ pullRequests: new Records(join(dir, "pull-requests"), PullRequestText),
60
72
  /** Questions by item, waiting for room under the daily cap or asked within the day. */
61
73
  questions: new Records(join(dir, "questions"), QueuedQuestion),
74
+ /** Follow-up items a pass filed within the day, by the item filed. */
75
+ followUps: new Records(join(dir, "follow-ups"), FiledFollowUp),
62
76
  /** Choices made without the owner, by item and time. */
63
77
  choices: new Records(join(dir, "choices"), Choice),
64
78
  /** Each answer's disposition, by item and ordinal. */
@@ -25,6 +25,13 @@ export class Records<S extends z.core.$ZodType> {
25
25
  atomicWrite(this.#path(key), `${JSON.stringify(z.parse(this.#schema, value))}\n`);
26
26
  }
27
27
 
28
+ /** Copies the record at `key` into another store of its kind, as its schema reads it, where this one has it. */
29
+ copyTo(into: Records<S>, key: string): void {
30
+ const record = this.get(key);
31
+
32
+ if (record !== undefined) atomicWrite(into.#path(key), `${JSON.stringify(record)}\n`);
33
+ }
34
+
28
35
  remove(key: string): void {
29
36
  rmSync(this.#path(key), { force: true });
30
37
  }
package/src/state/runs.ts CHANGED
@@ -71,6 +71,11 @@ export class RunRecords {
71
71
  };
72
72
  }
73
73
 
74
+ /** Saves a record another process kept, as it is. */
75
+ keep(record: RunRecord): void {
76
+ atomicWrite(this.#path(record), `${JSON.stringify(RunRecord.parse(record))}\n`);
77
+ }
78
+
74
79
  /** Rewrites a begun run's record. Nothing removes a record, so one gone since `begin` saved it throws. */
75
80
  #rewrite(key: RunKey, change: { readonly sessionId?: string; readonly endedAt?: number; readonly memoryUsed?: string[] }): RunRecord {
76
81
  const record = this.get(key);
@@ -31,8 +31,10 @@ export const Landing = z.object({
31
31
  change: Change,
32
32
  /** The commit the change ends at, before hum marks the item done: what a review reads. */
33
33
  head: name,
34
- /** The owner approved this change in its review state, before it was saved. */
35
- ownerApproved: z.boolean(),
34
+ /** The passes in a row whose push to the base another push beat. */
35
+ lostRaces: z.int().nonnegative().default(0),
36
+ /** The change's patch id against the base: the same change rebased keeps its landing. */
37
+ patch: z.string().optional(),
36
38
  /** The alignment call's grades, or why it abstained; made once per change. */
37
39
  alignment: z.union([z.object({ graded: AlignmentAnswer }), z.object({ abstained: name })]).optional(),
38
40
  });
@@ -61,6 +63,16 @@ export const SavedPlan = z.object({ item: name, plan: PlanFile, hash: name, mode
61
63
 
62
64
  export type SavedPlan = z.infer<typeof SavedPlan>;
63
65
 
66
+ /** One picture or video of the change at work, kept at `url`, or why the one the run named was left out. */
67
+ export const Evidence = z.union([z.object({ kind: z.enum(["image", "video"]), url: z.url() }), z.object({ left: name })]);
68
+
69
+ export type Evidence = z.infer<typeof Evidence>;
70
+
71
+ /** The pull request a build or fix run wrote for its item's whole change, under the repo's own rules for one; the latest run's stands. */
72
+ export const PullRequestText = z.object({ item: name, title: name, body: name, evidence: Evidence.optional() });
73
+
74
+ export type PullRequestText = z.infer<typeof PullRequestText>;
75
+
64
76
  /** A fresh review run's verdict on the change that ends at `head`. */
65
77
  export const Verdict = z.object({ item: name, head: name, event: name, reason: z.string(), cites: z.array(Cite), models });
66
78
 
@@ -82,6 +94,9 @@ export const QueuedQuestion = z.object({
82
94
 
83
95
  export type QueuedQuestion = z.infer<typeof QueuedQuestion>;
84
96
 
97
+ /** A follow-up item a pass filed, which counts against the daily question cap like a question asked. */
98
+ export const FiledFollowUp = z.object({ item: name, from: name, at: time });
99
+
85
100
  const settledFields = {
86
101
  item: name,
87
102
  /** The answer's number among the thread's answers and replies from people. */
@@ -10,7 +10,7 @@ export type BaseCheckOptions = {
10
10
  readonly state: State;
11
11
  readonly config: Config;
12
12
  readonly workSource: Pick<WorkSource, "fileFollowUp">;
13
- /** The owner's checkout; the merged commit is fetched into it. */
13
+ /** A repo whose `origin/<base>` holds the base's history; the merged commit is fetched into it. */
14
14
  readonly git: Git;
15
15
  readonly remote: string;
16
16
  readonly base: string;
@@ -19,27 +19,55 @@ export type BaseCheckOptions = {
19
19
  readonly item: string;
20
20
  };
21
21
 
22
+ /** The repo's checks on the base at some commit, for the merges they cover: their failure, absent when they passed. */
23
+ export type BaseCheck = { readonly items: readonly string[]; readonly failure?: string | undefined };
24
+
22
25
  const FAILURE_EXCERPT = 1500;
23
26
 
27
+ const failureAt = async ({ config, git, checks }: Pick<BaseCheckOptions, "config" | "git" | "checks">, sha: string): Promise<string | undefined> =>
28
+ (await inWorktreeAt(git, sha, (folder) => runChecks(checks, folder, { timeoutMs: checksTimeoutMs(config.hum) })))?.slice(0, FAILURE_EXCERPT);
29
+
24
30
  /**
25
- * After an item merged, the repo's checks run on the base at the merged commit. A failure there is a break: it is
26
- * saved, a follow-up fix item is filed, and the owner's level for the change says whether its paths are blocked until
27
- * that item merges. The fix limit counts the break beside the breaks git shows.
31
+ * Settles the base checks that cover merged items: each merge not yet checked counts as checked, and a failure is a
32
+ * break of each. A break is saved, a follow-up fix item is filed, and the owner's level for the change says whether
33
+ * its paths are blocked until that item merges; the fix limit counts it beside the breaks git shows. A report can only
34
+ * add breaks: an item with no unchecked merge is passed over.
28
35
  */
29
- export const checkBaseAfterMerge = async ({ state, config, workSource, git, remote, base, checks, now, item }: BaseCheckOptions): Promise<void> => {
30
- const merge = state.merges.get(item);
36
+ export const settleBaseCheck = async ({ state, config, workSource, git, base, now }: Omit<BaseCheckOptions, "item" | "remote" | "checks">, { items, failure }: BaseCheck): Promise<void> => {
37
+ for (const item of items) {
38
+ const merge = state.merges.get(item);
39
+
40
+ if (!merge || merge.baseChecked) continue;
41
+
42
+ if (failure !== undefined) {
43
+ const { placement } = await placementOf({ config, state, git, base, now }, { paths: merge.paths, size: 0, loosened: false, pinChanged: false });
44
+ const followUp = await workSource.fileFollowUp(ItemId.parse(item), { title: `Fix the checks that fail on ${base} after ${item} merged`, body: `Kind: fix\n\nThe repo's checks fail on ${base} after ${merge.sha}, the commit that merged ${item}.\n\n\`\`\`\n${failure}\n\`\`\`` });
31
45
 
32
- if (!config.hum.breakCheck || checks.length === 0 || !merge) return;
46
+ state.breaks.put(item, { item, sha: merge.sha, at: now(), paths: merge.paths, level: placement.level.name, failure, onBreak: placement.level.onBreak, followUp: followUp.id });
47
+ }
33
48
 
34
- await git.raw(["fetch", "-q", remote, base]);
49
+ state.merges.put(item, { ...merge, baseChecked: true });
50
+ }
51
+ };
35
52
 
36
- const failure = await inWorktreeAt(git, merge.sha, (folder) => runChecks(checks, folder, { timeoutMs: checksTimeoutMs(config.hum) }));
53
+ /** Whether the owner's config has the base checked after merges: the break check is on and there are checks to run. */
54
+ const checksBase = ({ config, checks }: Pick<BaseCheckOptions, "config" | "checks">): boolean => config.hum.breakCheck && checks.length > 0;
37
55
 
38
- if (failure === undefined) return;
56
+ /** After an item merged, the repo's checks run on the base at the merged commit, and their result is settled. */
57
+ export const checkBaseAfterMerge = async (o: BaseCheckOptions): Promise<void> => {
58
+ const merge = o.state.merges.get(o.item);
39
59
 
40
- const { placement } = await placementOf({ config, state, git, base, now }, { paths: merge.paths, size: 0, loosened: false, pinChanged: false });
41
- const followUp = await workSource.fileFollowUp(ItemId.parse(item), { title: `Fix the checks that fail on ${base} after ${item} merged`, body: `Kind: fix\n\nThe repo's checks fail on ${base} at ${merge.sha}, the commit that merged ${item}.\n\n\`\`\`\n${failure.slice(0, FAILURE_EXCERPT)}\n\`\`\`` });
60
+ if (!checksBase(o) || !merge) return;
42
61
 
43
- state.breaks.put(item, { item, sha: merge.sha, at: now(), paths: merge.paths, level: placement.level.name, failure: failure.slice(0, FAILURE_EXCERPT), onBreak: placement.level.onBreak, followUp: followUp.id });
62
+ await o.git.raw(["fetch", "-q", o.remote, o.base]);
63
+ await settleBaseCheck(o, { items: [o.item], failure: await failureAt(o, merge.sha) });
44
64
  };
45
65
 
66
+ /** The repo's checks at `at`, a commit of the base, for every merge no check has covered yet; undefined when none waits or the break check is off. */
67
+ export const checkMergesAt = async (o: Pick<BaseCheckOptions, "state" | "config" | "git" | "checks">, at: string): Promise<BaseCheck | undefined> => {
68
+ const items = o.state.merges.list().flatMap(({ item, baseChecked }) => (baseChecked ? [] : [item]));
69
+
70
+ if (!checksBase(o) || items.length === 0) return undefined;
71
+
72
+ return { items, failure: await failureAt(o, at) };
73
+ };