@moo.md/hum 0.3.0 → 0.4.1

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 +28 -33
  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 +22 -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 +126 -30
  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
@@ -9,7 +9,7 @@ import type { MergeMethod } from "../config/schema.ts";
9
9
  import { parseArgument } from "./argument.ts";
10
10
  import { claimCommitMessage, claimer, claimOfCommit, isLive } from "./claim.ts";
11
11
  import { type GitIdentity, gitIn, push, readOrAbsent } from "./git.ts";
12
- import { appendEntry, type ItemFile, newItemFile, parseItemFile, READY_STATE } from "./item-file.ts";
12
+ import { appendEntry, DONE_STATE, type ItemFile, markDone, newItemFile, parseItemFile, READY_STATE } from "./item-file.ts";
13
13
  import { answerMarker, followUpBody, followUpKey, questionText } from "./marked.ts";
14
14
  import { type CommitLanded, landOwnerCommit } from "./owner-commit.ts";
15
15
  import type { PullRequests } from "./pull-requests.ts";
@@ -352,6 +352,15 @@ export const markdownAdapter = ({ repo, claimPrefix, itemsDir, identity, writeRa
352
352
 
353
353
  return failed ?? { id, title };
354
354
  },
355
+ /** A landed change already carries the item file's done state, so this writes only where it does not. */
356
+ finish: async (id) =>
357
+ write(`hum: finish ${id}`, async () => {
358
+ const source = await itemSource(id);
359
+
360
+ if (source === undefined) throw new PermanentError(`no item "${id}" under ${itemsDir}/`);
361
+
362
+ return parseItemFile(source).state === DONE_STATE ? undefined : { path: pathOf(id), content: markDone(source) };
363
+ }),
355
364
  },
356
365
  questions: {
357
366
  ask: (id, question) => appendTo(id, { kind: "question" }, questionText(question)),
@@ -3,12 +3,13 @@ import pMemoize from "p-memoize";
3
3
  import { z } from "zod";
4
4
  import type { Json } from "../config/json.ts";
5
5
  import { MERGE_METHODS, type MergeMethod } from "../config/schema.ts";
6
- import type { Env } from "../exec.ts";
7
- import { type GitHubClient, MERGE_METHOD, ownerGitHub, raise } from "./github-client.ts";
6
+ import { MERGE_METHOD, raise, type RepoClientOptions, repoClient } from "./github-client.ts";
8
7
 
9
8
  /** What the target branch's rules ask of a change that lands on it. */
10
9
  export type BranchRules = {
11
10
  readonly requiresPullRequest: boolean;
11
+ /** Every commit that reaches the branch must carry a signature GitHub verifies. */
12
+ readonly requiresSignatures: boolean;
12
13
  /** The merge methods a pull request may use; undefined when no rule narrows them. */
13
14
  readonly mergeMethods: readonly MergeMethod[] | undefined;
14
15
  };
@@ -59,6 +60,8 @@ const Rule = z.looseObject({
59
60
 
60
61
  const PULL_REQUEST_RULE = "pull_request";
61
62
 
63
+ const SIGNATURES_RULE = "required_signatures";
64
+
62
65
  const PullNode = z.object({
63
66
  id: z.string(),
64
67
  number: z.int(),
@@ -137,12 +140,8 @@ export const methodFor = (
137
140
  : (allowed[0] ?? preferred);
138
141
 
139
142
  /** Pull requests and branch rules of a GitHub repo, on the owner's own login unless a client is given. `timeoutMs` bounds the `gh auth token` that reads that login. */
140
- export const gitHubPullRequests = (
141
- repo: string,
142
- options: { readonly timeoutMs: number } & ({ readonly client: () => Promise<GitHubClient> } | { readonly env: Env }),
143
- ): PullRequests => {
144
- const [owner = "", name = ""] = repo.split("/");
145
- const connect = "client" in options ? options.client : () => ownerGitHub(options.timeoutMs, options.env);
143
+ export const gitHubPullRequests = (repo: string, options: RepoClientOptions): PullRequests => {
144
+ const { owner, name, connect } = repoClient(repo, options);
146
145
 
147
146
  const rulesCache = new Map<string, BranchRules>();
148
147
 
@@ -176,6 +175,7 @@ export const gitHubPullRequests = (
176
175
 
177
176
  return {
178
177
  requiresPullRequest: pullRule !== undefined,
178
+ requiresSignatures: rules.some((rule) => rule.type === SIGNATURES_RULE),
179
179
  mergeMethods: pullRule?.parameters?.allowed_merge_methods,
180
180
  };
181
181
  },
@@ -4,7 +4,7 @@ import { pathToFileURL } from "node:url";
4
4
  import { z } from "zod";
5
5
  import { ADAPTER_API_VERSION, type Adapter, type AdapterContext, type AdapterFactory, type Integrations, PermanentError } from "../adapter-api.ts";
6
6
  import { readSettings } from "../config/settings.ts";
7
- import { HumConfig } from "../config/schema.ts";
7
+ import { HumConfig, SLOTS, type Slot } from "../config/schema.ts";
8
8
  import { commandTimeoutMs, type Env } from "../exec.ts";
9
9
  import type { Faults } from "../state/faults.ts";
10
10
  import type { Card } from "../status/format.ts";
@@ -15,10 +15,7 @@ import { markdownAdapter } from "./markdown.ts";
15
15
  import { gitHubPullRequests, type PullRequests } from "./pull-requests.ts";
16
16
  import { roundupAdapter } from "./roundup.ts";
17
17
 
18
- /** The integration slots `hum.json` `integrations` names, each to an adapter. */
19
- export const SLOTS = ["work-source", "questions", "answers", "release"] as const;
20
-
21
- export type Slot = (typeof SLOTS)[number];
18
+ export { SLOTS, type Slot } from "../config/schema.ts";
22
19
 
23
20
  const MARKDOWN = "markdown";
24
21
  const FALLBACK_BASE = "main";
@@ -28,7 +25,7 @@ const MARKDOWN_SLOTS: readonly Slot[] = ["work-source", "questions", "answers"];
28
25
 
29
26
  /** What the adapters read from `hum.json`; every other key belongs to the worker. */
30
27
  const AdapterSettings = z.looseObject({
31
- integrations: z.partialRecord(z.enum(SLOTS), z.string().min(1)).optional(),
28
+ integrations: HumConfig.shape.integrations,
32
29
  claimPrefix: HumConfig.shape.claimPrefix,
33
30
  itemsDir: HumConfig.shape.itemsDir,
34
31
  commitIdentity: HumConfig.shape.commitIdentity,
@@ -267,6 +267,9 @@ export const roundupAdapter = (options: RoundupOptions, { now, env }: AdapterCon
267
267
 
268
268
  return { id, title };
269
269
  },
270
+ finish: async (id) => {
271
+ if (!(await todo(id)).done) await call("todo_complete", { id: parseArgument(TodoId, id) });
272
+ },
270
273
  },
271
274
  questions: {
272
275
  ask: (id, question) => postMarked(id, questionMarker(question.options), questionText(question)),
package/src/bytes.ts ADDED
@@ -0,0 +1 @@
1
+ export const MEGABYTE = 1024 * 1024;
@@ -1,23 +1,38 @@
1
+ import * as core from "@actions/core";
1
2
  import { randomUUID } from "node:crypto";
2
- import { hostname } from "node:os";
3
+ import { mkdtempSync } from "node:fs";
4
+ import { hostname, tmpdir } from "node:os";
3
5
  import { join } from "node:path";
4
6
  import type { Command } from "commander";
5
7
  import { x } from "tinyexec";
6
8
  import { z } from "zod";
7
- import { listHopeSkills } from "../config/load.ts";
9
+ import { listPluginSkills } from "../config/load.ts";
8
10
  import { HumConfig } from "../config/schema.ts";
9
11
  import { readSettings } from "../config/settings.ts";
10
12
  import { commandTimeoutMs, exec, SHIPPED_COMMAND_TIMEOUT_MS } from "../exec.ts";
13
+ import { CI_STATE_REF, CiStateRaced, restoreCiState, saveCiState } from "../service/ci-state.ts";
11
14
  import { readCiTick, recordCiTick } from "../service/ci-tick.ts";
12
15
  import { EXIT_UPDATED, supervise } from "../service/supervise.ts";
16
+ import { installPlugins } from "../service/plugins.ts";
13
17
  import { reportCards, wakeUntilQuiet } from "../service/wake.ts";
14
- import { defaultStateDir, openState } from "../state/open.ts";
18
+ import { defaultStateDir, openState, STATUS_FILE } from "../state/open.ts";
15
19
  import { SECOND_MS } from "../time.ts";
16
20
  import { readStatus } from "../status/file.ts";
17
- import { npmLatest, openWorker } from "../worker/open.ts";
21
+ import { npmLatest, type OpenWorkerOptions, workerOptions } from "../worker/open.ts";
22
+ import { Worker, type WorkerOptions } from "../worker/worker.ts";
23
+ import { DEFAULT_BASE, publisherOf } from "../worker/thin-path.ts";
24
+ import { tallyOf } from "../worker/tally.ts";
25
+ import { Gathered, inboxIntegrations, readInbox, readOutbox, workRemote, writeBaseCheck, writeInbox, writeOutboxState, writePass } from "../publish/handover.ts";
26
+ import { checkMergesAt } from "../worker/base-check.ts";
27
+ import { publishWake } from "../publish/wake.ts";
28
+ import { configuredModelCall } from "../adapters/model-call.ts";
29
+ import { type Git, gitIn } from "../adapters/git.ts";
30
+ import { APP_TOKEN_MINUTES, WAKE_ENV } from "../config/wake-job.ts";
31
+ import { MINUTE_MS } from "../time.ts";
18
32
  import type { Io } from "./ops.ts";
19
- import { Holder } from "../adapter-api.ts";
33
+ import { Holder, type Item, ItemId } from "../adapter-api.ts";
20
34
  import { parseArgument } from "../adapters/argument.ts";
35
+ import { MEGABYTE } from "../bytes.ts";
21
36
 
22
37
  const EXIT_OK = 0;
23
38
 
@@ -26,6 +41,8 @@ const EXIT_STAY_DOWN = EXIT_OK;
26
41
 
27
42
  const EXIT_CARDS_SHOWN = 1;
28
43
 
44
+ const EXIT_FAILED = 1;
45
+
29
46
  const SCHEDULE_EVENT = "schedule";
30
47
 
31
48
  type WorkFlags = { holder?: string; base?: string };
@@ -36,18 +53,23 @@ const withWorkOptions = (cmd: Command): Command =>
36
53
  .option("--holder <name>", "the name this worker claims items by; default <where>@<host>")
37
54
  .option("--base <branch>", "the branch items merge into; default main");
38
55
 
39
- const PluginList = z.array(z.looseObject({ id: z.string(), installPath: z.string() }));
56
+ const PluginList = z.array(z.looseObject({ id: z.string(), installPath: z.string(), enabled: z.boolean().default(true) }));
40
57
 
41
- /** The folder of the installed hope plugin: `HUM_HOPE_ROOT`, else the path `claude plugin list` gives. */
42
- export const hopeRoot = async (): Promise<string> => {
43
- if (process.env.HUM_HOPE_ROOT) return process.env.HUM_HOPE_ROOT;
58
+ const HOPE = "hope";
59
+
60
+ /**
61
+ * The skills of every enabled plugin, as a role names them (`sound:prime`), read from the folders `claude plugin list`
62
+ * gives. `HUM_HOPE_ROOT` names hope's folder instead, and then hope's skills are all there is. hope must be there.
63
+ */
64
+ export const installedSkills = async (): Promise<ReadonlySet<string>> => {
65
+ if (process.env.HUM_HOPE_ROOT) return new Set(listPluginSkills(HOPE, process.env.HUM_HOPE_ROOT));
44
66
 
45
67
  const listed = await exec("claude", ["plugin", "list", "--json"], { timeoutMs: SHIPPED_COMMAND_TIMEOUT_MS });
46
- const hope = listed.exitCode === 0 ? PluginList.parse(JSON.parse(listed.stdout)).find((plugin) => plugin.id.startsWith("hope@")) : undefined;
68
+ const plugins = listed.exitCode === 0 ? PluginList.parse(JSON.parse(listed.stdout)).filter(({ enabled }) => enabled).map(({ id, installPath }) => ({ name: id.split("@")[0] ?? id, installPath })) : [];
47
69
 
48
- if (!hope) throw new Error("the hope plugin is not installed: run `claude plugin install hope@moo.md`, or set HUM_HOPE_ROOT to its folder");
70
+ if (!plugins.some(({ name }) => name === HOPE)) throw new Error("the hope plugin is not installed: run `claude plugin install hope@moo.md`, or set HUM_HOPE_ROOT to its folder");
49
71
 
50
- return hope.installPath;
72
+ return new Set(plugins.flatMap(({ name, installPath }) => listPluginSkills(name, installPath)));
51
73
  };
52
74
 
53
75
  const ServiceSettings = z.looseObject({
@@ -72,19 +94,20 @@ const serviceSettings = (repo: string): z.infer<typeof ServiceSettings> => {
72
94
  };
73
95
 
74
96
  /** The Mac reads the npm version and when the scheduled workflow last ran; a CI job is that workflow. */
75
- const openFor = async ({ cwd: repo, env }: Io, flags: WorkFlags, where: "mac" | "ci") => {
97
+ const optionsFor = async ({ cwd: repo, env }: Io, flags: WorkFlags, where: "mac" | "ci", extra: Partial<OpenWorkerOptions> = {}): Promise<WorkerOptions> => {
76
98
  const timeoutMs = commandTimeoutMs(serviceSettings(repo));
77
99
 
78
- return openWorker(repo, {
100
+ return workerOptions(repo, {
79
101
  now: Date.now,
80
102
  env,
81
103
  newSessionId: randomUUID,
82
- hopeSkills: listHopeSkills(await hopeRoot()),
104
+ installedSkills: extra.judgmentsOnly ? undefined : await installedSkills(),
83
105
  holder: parseArgument(Holder, flags.holder ?? `${where}@${hostname()}`),
84
106
  base: flags.base,
85
107
  where,
86
108
  latestVersion: where === "mac" ? npmLatest : undefined,
87
109
  ciTick: where === "mac" ? () => readCiTick({ repo, remote: "origin", timeoutMs }) : undefined,
110
+ ...extra,
88
111
  });
89
112
  };
90
113
 
@@ -100,8 +123,9 @@ const spawnWorker = (cwd: string, workArgs: readonly string[]) => {
100
123
  };
101
124
 
102
125
  /**
103
- * `hum work`, `hum serve` and `hum wake`: the processes a service unit and a CI workflow start. They are not ops:
104
- * roles and machines never name them, so they stay out of the table `hum help --json` prints.
126
+ * `hum work`, `hum serve` and `hum wake`'s jobs: the processes a service unit and a CI workflow start. They are not ops:
127
+ * roles and machines never name them, so they stay out of the table `hum help --json` prints. A CI job's git dir dies
128
+ * with it, so gather brings back the state the last wake saved first and saves it for publish, which saves it again.
105
129
  */
106
130
  export const addServiceCommands = (root: Command, io: Io, done: (code: number) => void): void => {
107
131
  withWorkOptions(root.command("work").description("Run the worker on this machine until it is stopped or an update arrives; exits 75 for an update."))
@@ -110,7 +134,7 @@ export const addServiceCommands = (root: Command, io: Io, done: (code: number) =
110
134
 
111
135
  onStop(() => abort.abort());
112
136
 
113
- const worker = await openFor(io, flags, "mac");
137
+ const worker = new Worker(await optionsFor(io, flags, "mac"));
114
138
  const ended = await worker.serve(abort.signal);
115
139
 
116
140
  io.stderr(`hum work: stopped, ${ended.reason}\n`);
@@ -144,19 +168,142 @@ export const addServiceCommands = (root: Command, io: Io, done: (code: number) =
144
168
  done(EXIT_STAY_DOWN);
145
169
  });
146
170
 
147
- withWorkOptions(root.command("wake").description("One CI wake: tick until nothing more starts, record the tick when --event is schedule, and show the cards."))
148
- .option("--event <name>", "the GitHub event that started this job")
149
- .action(async (flags: WorkFlags & { event?: string }) => {
150
- const worker = await openFor(io, flags, "ci");
171
+ root
172
+ .command("plugins")
173
+ .description("Install hope and the repo's own Claude Code plugins for a CI wake: moo.md at the commit this engine shipped with, then each marketplace and enabled plugin .claude/settings.json names.")
174
+ .action(async () => {
175
+ try {
176
+ for (const args of await installPlugins({ repo: io.cwd, env: io.env })) io.stdout(`claude ${args.join(" ")}\n`);
151
177
 
152
- await wakeUntilQuiet(worker);
178
+ done(EXIT_OK);
179
+ } catch (error) {
180
+ io.stderr(`hum plugins: ${error instanceof Error ? error.message : String(error)}\n`);
181
+ done(EXIT_FAILED);
182
+ }
183
+ });
153
184
 
154
- if (flags.event === SCHEDULE_EVENT) await recordCiTick({ repo: io.cwd, remote: "origin", at: Date.now(), identity: worker.config.hum.commitIdentity, timeoutMs: commandTimeoutMs(worker.config.hum) });
185
+ const wake = root.command("wake").description("One CI wake, as three jobs: gather claims and settles with GitHub's token, work runs with none, and publish checks and applies what work made.");
155
186
 
156
- const status = readStatus(join(await defaultStateDir(io.cwd), "status.json"));
157
- const cards = status.ok ? status.status.cards : [];
187
+ withWorkOptions(wake.command("gather").description("Bring back the state the last wake saved, claim each item and settle its answers and kind, save the state, and write the inbox the work job reads; sets the job output `gathered` for publish."))
188
+ .requiredOption("--inbox <folder>", "where to write the inbox")
189
+ .action((flags: WorkFlags & { inbox: string }) => wakeJob(io, done, async () => {
190
+ const dir = await defaultStateDir(io.cwd);
191
+ const timeoutMs = commandTimeoutMs(serviceSettings(io.cwd));
192
+ const where = { repo: io.cwd, remote: "origin", dir, timeoutMs };
193
+ const read = await restoreCiState(where);
194
+ const claimed = new Map<string, Item>();
195
+ const options = await optionsFor(io, flags, "ci", { ciJob: { kind: "gather", gathered: claimed }, judgmentsOnly: true });
196
+ const worker = new Worker(options);
158
197
 
159
- await reportCards(cards, { hasStepSummary: Boolean(process.env.GITHUB_STEP_SUMMARY) });
160
- done(cards.length > 0 ? EXIT_CARDS_SHOWN : EXIT_OK);
161
- });
198
+ for (let before = -1; claimed.size > before; ) {
199
+ before = claimed.size;
200
+ await worker.tick();
201
+ await worker.idle();
202
+ }
203
+
204
+ const base = options.base ?? DEFAULT_BASE;
205
+ const saved = await saveCiState({ ...where, ...read, identity: options.config.hum.commitIdentity, at: Date.now() });
206
+ const heads = await remoteHeads(gitIn(io.cwd, { timeoutMs }), options.config.hum.runBranchPrefix);
207
+ const baseSha = (await remoteHeads(gitIn(io.cwd, { timeoutMs }), base)).get(base);
208
+
209
+ if (baseSha === undefined) throw new Error(`origin has no branch ${base}`);
210
+
211
+ heads.delete(base);
212
+
213
+ const gathered: Gathered = { holder: options.holder, base, baseSha, heads: Object.fromEntries(heads), claimed: [...claimed.keys()].map((id) => ItemId.parse(id)), stateRead: saved.read };
214
+
215
+ writeInbox(flags.inbox, { gathered, items: [...claimed.values()] }, dir);
216
+ core.setOutput("gathered", JSON.stringify(gathered));
217
+
218
+ return dir;
219
+ }));
220
+
221
+ wake
222
+ .command("work")
223
+ .description("Run each item the inbox holds with no GitHub token: runs clone the base and hum branches gather saw, and each pass leaves what it asks publish to do in the outbox, with hum's state.")
224
+ .requiredOption("--inbox <folder>", "the inbox gather wrote")
225
+ .requiredOption("--outbox <folder>", "where to write the outbox")
226
+ .action((flags: { inbox: string; outbox: string }) => wakeJob(io, done, async () => {
227
+ const dir = await defaultStateDir(io.cwd);
228
+ const timeoutMs = commandTimeoutMs(serviceSettings(io.cwd));
229
+ const inbox = readInbox(flags.inbox, dir);
230
+ const { gathered } = inbox;
231
+ const remote = await workRemote({ checkout: io.cwd, gathered, folder: mkdtempSync(join(io.env.RUNNER_TEMP ?? tmpdir(), "hum-remote-")), timeoutMs });
232
+
233
+ const options = await optionsFor(io, { holder: gathered.holder, base: gathered.base }, "ci", {
234
+ remote,
235
+ integrations: inboxIntegrations(inbox, Date.now),
236
+ ciJob: { kind: "work", publish: async (pass, worked) => void writePass(flags.outbox, { ...pass, result: worked }) },
237
+ });
238
+
239
+ const baseCheck = await checkMergesAt({ ...options, git: gitIn(io.cwd, { timeoutMs }) }, gathered.baseSha);
240
+
241
+ if (baseCheck !== undefined) writeBaseCheck(flags.outbox, baseCheck);
242
+
243
+ await wakeUntilQuiet(new Worker(options));
244
+ writeOutboxState(flags.outbox, dir);
245
+
246
+ return dir;
247
+ }));
248
+
249
+ wake
250
+ .command("publish")
251
+ .description(`Check and apply the work job's outbox with GitHub's token, from what gather settled in ${WAKE_ENV.gathered}, save the state, and record the tick when --event is schedule.`)
252
+ .requiredOption("--outbox <folder>", "the outbox the work job wrote")
253
+ .option("--event <name>", "the GitHub event that started this wake")
254
+ .action((flags: { outbox: string; event?: string }) => wakeJob(io, done, async () => {
255
+ const started = Date.now();
256
+ const gathered = Gathered.parse(JSON.parse(io.env[WAKE_ENV.gathered] ?? "null"));
257
+ const dir = await defaultStateDir(io.cwd);
258
+ const timeoutMs = commandTimeoutMs(serviceSettings(io.cwd));
259
+ const where = { repo: io.cwd, remote: "origin", dir, timeoutMs };
260
+ const read = await restoreCiState(where);
261
+
262
+ if (read.read !== gathered.stateRead) throw new CiStateRaced(`hum's state at ${CI_STATE_REF} is not the one gather saved, so another wake ran since; this wake publishes nothing`);
263
+
264
+ const options = await optionsFor(io, { holder: gathered.holder, base: gathered.base }, "ci", { judgmentsOnly: true });
265
+ const { hum } = options.config;
266
+ const outbox = readOutbox(flags.outbox, { maxBytes: hum.ciOutboxMaxMegabytes * MEGABYTE, claimed: new Set(gathered.claimed) });
267
+ const judge = options.judge ?? configuredModelCall(options.runner, hum, (item, tokens) => tallyOf(options.state, item).spend(tokens));
268
+ const publisher = publisherOf({ ...options, workSource: options.adapters.workSource, questions: options.adapters.questions }, judge, started + (APP_TOKEN_MINUTES - hum.ciMergeMarginMinutes) * MINUTE_MS);
269
+
270
+ let saved = read;
271
+
272
+ const save = async () => {
273
+ saved = await saveCiState({ ...where, ...saved, identity: hum.commitIdentity, at: Date.now() });
274
+ };
275
+
276
+ await publishWake({ publisher, gathered, outbox, work: openState(outbox.stateDir, { now: Date.now }), save });
277
+
278
+ if (flags.event === SCHEDULE_EVENT) await recordCiTick({ repo: io.cwd, remote: "origin", at: Date.now(), identity: hum.commitIdentity, timeoutMs });
279
+
280
+ return dir;
281
+ }));
282
+ };
283
+
284
+ /** Runs one job of a wake, then shows the cards its state holds; the job exits 1 when it shows any or fails. */
285
+ const wakeJob = async (io: Io, done: (code: number) => void, job: () => Promise<string>): Promise<void> => {
286
+ try {
287
+ const status = readStatus(join(await job(), STATUS_FILE));
288
+ const cards = status.ok ? status.status.cards : [];
289
+
290
+ await reportCards(cards, { hasStepSummary: Boolean(process.env.GITHUB_STEP_SUMMARY) });
291
+ done(cards.length > 0 ? EXIT_CARDS_SHOWN : EXIT_OK);
292
+ } catch (error) {
293
+ io.stderr(`hum wake: ${error instanceof Error ? error.message : String(error)}\n`);
294
+ done(EXIT_FAILED);
295
+ }
162
296
  };
297
+
298
+ /** Each branch on origin under `prefix`, or named `prefix`, at its head. */
299
+ const remoteHeads = async (git: Git, prefix: string): Promise<Map<string, string>> =>
300
+ new Map(
301
+ (await git.raw(["ls-remote", "--heads", "origin", `refs/heads/${prefix}*`]))
302
+ .split("\n")
303
+ .filter(Boolean)
304
+ .map((line) => {
305
+ const [sha = "", ref = ""] = line.split("\t");
306
+
307
+ return [ref.slice("refs/heads/".length), sha] as const;
308
+ }),
309
+ );
package/src/cli/setup.ts CHANGED
@@ -5,7 +5,6 @@ import { x } from "tinyexec";
5
5
  import { z } from "zod";
6
6
  import type { Item } from "../adapter-api.ts";
7
7
  import { gitIn, readGitIdentity } from "../adapters/git.ts";
8
- import { listHopeSkills } from "../config/load.ts";
9
8
  import { HumConfig } from "../config/schema.ts";
10
9
  import { CommandTimedOut, exec, SHIPPED_COMMAND_TIMEOUT_MS } from "../exec.ts";
11
10
  import { readSettings } from "../config/settings.ts";
@@ -16,7 +15,7 @@ import { shippedConfig } from "../setup/shipped.ts";
16
15
  import { waitsOf } from "../setup/waits.ts";
17
16
  import { readAnswers, writeSetup } from "../setup/write.ts";
18
17
  import type { Io } from "./ops.ts";
19
- import { hopeRoot } from "./service.ts";
18
+ import { installedSkills } from "./service.ts";
20
19
 
21
20
  const EXIT_OK = 0;
22
21
  const EXIT_FAILED = 1;
@@ -31,22 +30,16 @@ const GhLabels = z.array(z.object({ name: z.string() }));
31
30
 
32
31
  const EVAL_SCRIPT = join(import.meta.dir, "..", "..", "scripts", "eval.ts");
33
32
 
33
+ /** What the scan reads from GitHub. Each fact is read alone, and one whose read fails is unknown while the rest stand. */
34
34
  type GithubFacts = {
35
- readonly items: readonly Pick<Item, "body" | "labels">[];
36
- readonly labels: readonly string[];
35
+ readonly items: readonly Pick<Item, "body" | "labels">[] | undefined;
36
+ readonly labels: readonly string[] | undefined;
37
37
  /** Whether the repo lets a workflow open pull requests; off, a CI run cannot open one at all. */
38
- readonly workflowsMayOpenPullRequests: boolean;
38
+ readonly workflowsMayOpenPullRequests: boolean | undefined;
39
39
  };
40
40
 
41
41
  const Visibility = z.object({ visibility: z.string() });
42
42
 
43
- /** Whether anyone may read and comment on the repo; undefined without `gh` or a GitHub remote. */
44
- const isPublicRepo = async (repo: string): Promise<boolean | undefined> => {
45
- const viewed = await gh(repo, ["repo", "view", "--json", "visibility"]);
46
-
47
- return isRead(viewed) ? Visibility.parse(JSON.parse(viewed.stdout)).visibility === "PUBLIC" : undefined;
48
- };
49
-
50
43
  const WorkflowPermissions = z.object({ can_approve_pull_request_reviews: z.boolean() });
51
44
 
52
45
  /** Setup reads before any `hum.json` is written, so its commands run on the shipped time limit. */
@@ -63,25 +56,27 @@ const gh = async (repo: string, args: readonly string[]) => {
63
56
  }
64
57
  };
65
58
 
66
- type GhOutput = Awaited<ReturnType<typeof gh>>;
67
-
68
- const isRead = (output: GhOutput): output is NonNullable<GhOutput> => output?.exitCode === 0;
59
+ /**
60
+ * What one `gh` read prints, through `parse`; undefined where the read fails: without `gh` or a GitHub remote, or
61
+ * without the rights it needs, as a read that needs admin fails for anyone else.
62
+ */
63
+ const ghRead = async <T>(repo: string, args: readonly string[], parse: (stdout: string) => T): Promise<T | undefined> => {
64
+ const output = await gh(repo, args);
69
65
 
70
- /** The repo's open issues and its label names, from `gh`. Without `gh` or a GitHub remote there are none, and the scan prints no coverage. */
71
- const githubFacts = async (repo: string): Promise<GithubFacts | undefined> => {
72
- const issues = await gh(repo, ["issue", "list", "--state", "open", "--limit", GH_LIST_LIMIT, "--json", "body,labels"]);
73
- const labels = await gh(repo, ["label", "list", "--limit", GH_LIST_LIMIT, "--json", "name"]);
74
-
75
- const permissions = await gh(repo, ["api", "repos/{owner}/{repo}/actions/permissions/workflow"]);
66
+ return output?.exitCode === 0 ? parse(output.stdout) : undefined;
67
+ };
76
68
 
77
- if (!isRead(issues) || !isRead(labels) || !isRead(permissions)) return undefined;
69
+ /** Whether anyone may read and comment on the repo; undefined where `gh` cannot read it. */
70
+ const isPublicRepo = (repo: string): Promise<boolean | undefined> => ghRead(repo, ["repo", "view", "--json", "visibility"], (stdout) => Visibility.parse(JSON.parse(stdout)).visibility === "PUBLIC");
78
71
 
79
- return {
80
- items: GhIssues.parse(JSON.parse(issues.stdout)).map(({ body, labels: on }) => ({ body, labels: on.map(({ name }) => name) })),
81
- labels: GhLabels.parse(JSON.parse(labels.stdout)).map(({ name }) => name),
82
- workflowsMayOpenPullRequests: WorkflowPermissions.parse(JSON.parse(permissions.stdout)).can_approve_pull_request_reviews,
83
- };
84
- };
72
+ /** The repo's open issues, its label names and its workflow permissions, from `gh`. Without the open issues and the labels both read, the scan prints no coverage, as the issues are counted against the labels. */
73
+ const githubFacts = async (repo: string): Promise<GithubFacts> => ({
74
+ items: await ghRead(repo, ["issue", "list", "--state", "open", "--limit", GH_LIST_LIMIT, "--json", "body,labels"], (stdout) =>
75
+ GhIssues.parse(JSON.parse(stdout)).map(({ body, labels }) => ({ body, labels: labels.map(({ name }) => name) })),
76
+ ),
77
+ labels: await ghRead(repo, ["label", "list", "--limit", GH_LIST_LIMIT, "--json", "name"], (stdout) => GhLabels.parse(JSON.parse(stdout)).map(({ name }) => name)),
78
+ workflowsMayOpenPullRequests: await ghRead(repo, ["api", "repos/{owner}/{repo}/actions/permissions/workflow"], (stdout) => WorkflowPermissions.parse(JSON.parse(stdout)).can_approve_pull_request_reviews),
79
+ });
85
80
 
86
81
  const printStep = ({ name, status, detail, ms }: Step): string => `${status.padEnd(7)} ${name} (${ms} ms): ${detail}`;
87
82
 
@@ -107,12 +102,12 @@ export const addSetupCommands = (root: Command, io: Io, done: (code: number) =>
107
102
  const scan = await scanRepo(io.cwd, base);
108
103
  const facts = await githubFacts(io.cwd);
109
104
  const isPublic = await isPublicRepo(io.cwd);
110
- const proposal = proposeSetup(scan, shipped.hum, { labels: facts?.labels, isPublic: isPublic ?? true });
105
+ const proposal = proposeSetup(scan, shipped.hum, { labels: facts.labels, isPublic: isPublic ?? true, openIssues: facts.items?.length });
111
106
  const { tracked, folders, ...shown } = scan;
112
- const coverage = facts && kindCoverage(facts.items, shipped.hum.kinds, proposal.kindLabels);
107
+ const coverage = facts.items && facts.labels && kindCoverage(facts.items, shipped.hum.kinds, proposal.kindLabels);
113
108
  const gitIdentity = await readGitIdentity(setupGit(io.cwd));
114
109
 
115
- io.stdout(`${JSON.stringify({ scan: { ...shown, trackedFiles: tracked.length, folders: folders.map(({ folder, changes }) => ({ folder, changes })) }, proposal, waits: waitsOf(shipped.kinds), coverage: coverage ?? null, workflowsMayOpenPullRequests: facts?.workflowsMayOpenPullRequests ?? null, isPublicRepo: isPublic ?? null, gitIdentity }, null, "\t")}\n`);
110
+ io.stdout(`${JSON.stringify({ scan: { ...shown, trackedFiles: tracked.length, folders: folders.map(({ folder, changes }) => ({ folder, changes })) }, proposal, waits: waitsOf(shipped.kinds), coverage: coverage ?? null, workflowsMayOpenPullRequests: facts.workflowsMayOpenPullRequests ?? null, isPublicRepo: isPublic ?? null, gitIdentity }, null, "\t")}\n`);
116
111
  });
117
112
 
118
113
  setup
@@ -121,7 +116,7 @@ export const addSetupCommands = (root: Command, io: Io, done: (code: number) =>
121
116
  .requiredOption("--answers <file>", 'JSON: { "hum": {settings}, "waitHours": { "kind/state": hours }, "schemaVersion": 2 }')
122
117
  .option("--home <folder>", "where the service unit goes; default the user's home")
123
118
  .action(async ({ answers, home }: { answers: string; home?: string }) => {
124
- const result = writeSetup(io.cwd, readAnswers(answers), { hopeSkills: listHopeSkills(await hopeRoot()), home, gitIdentity: await readGitIdentity(setupGit(io.cwd)), isPublicRepo: await isPublicRepo(io.cwd) });
119
+ const result = writeSetup(io.cwd, readAnswers(answers), { installedSkills: await installedSkills(), home, gitIdentity: await readGitIdentity(setupGit(io.cwd)), isPublicRepo: await isPublicRepo(io.cwd) });
125
120
 
126
121
  io.stdout(`${JSON.stringify(result.ok ? { written: result.written } : { refused: result.refusal.message }, null, "\t")}\n`);
127
122
  done(result.ok ? EXIT_OK : EXIT_FAILED);
@@ -133,7 +128,7 @@ export const addSetupCommands = (root: Command, io: Io, done: (code: number) =>
133
128
  .option("--base <branch>", "the branch items merge into", DEFAULT_BASE)
134
129
  .option("--item", "run one item through the real claude on a scratch copy; spends live calls")
135
130
  .action(async ({ base, item }: { base: string; item?: true }) => {
136
- const steps = await proveSetup(io.cwd, { now: Date.now, processEnv: io.env, newSessionId: randomUUID, hopeSkills: listHopeSkills(await hopeRoot()), base, item: item === true });
131
+ const steps = await proveSetup(io.cwd, { now: Date.now, processEnv: io.env, newSessionId: randomUUID, installedSkills: await installedSkills(), base, item: item === true });
137
132
 
138
133
  io.stdout(`${steps.map(printStep).join("\n")}\n`);
139
134
  done(steps.some(({ status }) => status === "failed") ? EXIT_FAILED : EXIT_OK);
@@ -1,6 +1,5 @@
1
- import { toDirectedGraph } from "xstate/graph";
2
1
  import { APP_TOKEN_MINUTES, WAKE_OWN_ENV } from "./wake-job.ts";
3
- import { kindMachine } from "./machine.ts";
2
+ import { kindMachine, nextStates, reachedFrom } from "./machine.ts";
4
3
  import type { Problem } from "./refusal.ts";
5
4
  import {
6
5
  FIXED_PARTS,
@@ -15,8 +14,8 @@ import {
15
14
  WAIT_TAG,
16
15
  } from "./schema.ts";
17
16
 
18
- /** What the checks read besides the config: hope's installed skills, by bare name (`intent`, not `hope:intent`). */
19
- export type CheckEnv = { readonly hopeSkills: ReadonlySet<string> };
17
+ /** What the checks read besides the config: the installed plugins' skills, as a role names them (`hope:intent`); absent where no role runs, so no role's skills are checked. */
18
+ export type CheckEnv = { readonly installedSkills?: ReadonlySet<string> };
20
19
 
21
20
  type Transitions = StateNodeJSON["onTimeout"];
22
21
 
@@ -37,39 +36,14 @@ const isXstateEvent = (event: string): boolean => event.startsWith("xstate.") ||
37
36
  /** Every state is reachable and reaches done or stuck; every wait has a timeout and an action. */
38
37
  const graphProblems = (kind: string, config: Kind): Problem[] => {
39
38
  const { states, initial } = config.machine;
40
- const graph = toDirectedGraph(kindMachine(config));
41
- const forward = new Map<string, string[]>();
39
+ const forward = nextStates(config);
42
40
  const backward = new Map<string, string[]>();
43
41
 
44
- for (const node of graph.children) {
45
- for (const edge of node.edges) {
46
- forward.set(edge.source.key, [...(forward.get(edge.source.key) ?? []), edge.target.key]);
47
- backward.set(edge.target.key, [...(backward.get(edge.target.key) ?? []), edge.source.key]);
48
- }
49
- }
50
-
51
- const walk = (from: Iterable<string>, edges: Map<string, string[]>) => {
52
- const seen = new Set<string>(from);
53
- const todo = [...seen];
42
+ for (const [source, targets] of forward) for (const target of targets) backward.set(target, [...(backward.get(target) ?? []), source]);
54
43
 
55
- for (let key = todo.pop(); key !== undefined; key = todo.pop()) {
56
- for (const next of edges.get(key) ?? []) {
57
- if (seen.has(next)) continue;
58
-
59
- seen.add(next);
60
- todo.push(next);
61
- }
62
- }
63
-
64
- return seen;
65
- };
66
-
67
- const reachable = walk([initial], forward);
68
-
69
- const finishing = walk(
70
- Object.entries(states).flatMap(([name, node]) => (isTerminal(node) ? [name] : [])),
71
- backward,
72
- );
44
+ const reachable = reachedFrom(initial, forward);
45
+ const terminal = Object.entries(states).flatMap(([name, node]) => (isTerminal(node) ? [name] : []));
46
+ const finishing = new Set(terminal.flatMap((state) => [...reachedFrom(state, backward)]));
73
47
 
74
48
  return Object.entries(states).flatMap(([state, node]): Problem[] => [
75
49
  ...(reachable.has(state) ? [] : [{ problem: "unreachable-state", kind, state } as const]),
@@ -157,15 +131,14 @@ const eventProblems = (hum: HumConfig, kinds: Readonly<Record<string, Kind>>): P
157
131
  ];
158
132
  };
159
133
 
160
- /** Each `hope:<skill>` a role names exists in hope's installed copy. */
161
- const skillProblems = (hum: HumConfig, env: CheckEnv): Problem[] =>
162
- Object.entries(hum.roles).flatMap(([role, { skills }]) =>
163
- skills.flatMap((skill): Problem[] =>
164
- skill.startsWith("hope:") && !env.hopeSkills.has(skill.slice("hope:".length))
165
- ? [{ problem: "missing-hope-skill", skill, role }]
166
- : [],
167
- ),
168
- );
134
+ /** A plugin's skill is named `<plugin>:<skill>`; a bare name is the repo's or the user's own, which no plugin list holds. */
135
+ const isPluginSkill = (skill: string): boolean => skill.includes(":");
136
+
137
+ /** Each plugin skill a role names is in an installed plugin, where roles run. */
138
+ const skillProblems = (hum: HumConfig, { installedSkills }: CheckEnv): Problem[] =>
139
+ installedSkills === undefined
140
+ ? []
141
+ : Object.entries(hum.roles).flatMap(([role, { skills }]) => skills.flatMap((skill): Problem[] => (isPluginSkill(skill) && !installedSkills.has(skill) ? [{ problem: "missing-skill", skill, role }] : [])));
169
142
 
170
143
  /** A run branch could then share a name, or a folder, with a claim branch. */
171
144
  const doPrefixesOverlap = ({ runBranchPrefix, claimPrefix }: Naming): boolean =>
@@ -194,15 +167,13 @@ const pathProblems = (hum: HumConfig): Problem[] => {
194
167
  ];
195
168
  };
196
169
 
197
- /** `ciEnv` sets none of the env the wake job sets itself. */
170
+ /** `ciEnv` sets none of the env the wake's jobs set themselves. */
198
171
  const wakeEnvProblems = ({ ciEnv }: HumConfig): Problem[] =>
199
172
  Object.keys(ciEnv).flatMap((name): Problem[] => (WAKE_OWN_ENV.has(name) ? [{ problem: "wake-env-taken", name }] : []));
200
173
 
201
- /** A wake that mints an App's token ends before the token does. */
202
- const appTokenProblems = ({ pullRequestToken, ciWakeTimeoutMinutes }: HumConfig): Problem[] =>
203
- pullRequestToken.from === "app" && ciWakeTimeoutMinutes > APP_TOKEN_MINUTES
204
- ? [{ problem: "wake-outlasts-app-token", minutes: ciWakeTimeoutMinutes, tokenMinutes: APP_TOKEN_MINUTES }]
205
- : [];
174
+ /** Publish keeps less than the App token's hour in hand, so it has time left to merge. */
175
+ const mergeMarginProblems = ({ ciMergeMarginMinutes }: HumConfig): Problem[] =>
176
+ ciMergeMarginMinutes < APP_TOKEN_MINUTES ? [] : [{ problem: "merge-margin-fills-token-hour", minutes: ciMergeMarginMinutes, tokenMinutes: APP_TOKEN_MINUTES }];
206
177
 
207
178
  /** The proof a path names for a kind: its own, else the one for every kind. */
208
179
  export const proofFor = (rule: PathRule, kind: string): string | undefined => rule.proofs?.[kind] ?? rule.proofs?.[ALL_KINDS];
@@ -222,5 +193,5 @@ export const checkConfig = (
222
193
  ...skillProblems(hum, env),
223
194
  ...namingProblems(hum),
224
195
  ...wakeEnvProblems(hum),
225
- ...appTokenProblems(hum),
196
+ ...mergeMarginProblems(hum),
226
197
  ];