@moo.md/hum 0.2.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.
- package/defaults/hum.json +9 -2
- package/package.json +1 -1
- package/schema/hum.schema.json +208 -7
- package/src/adapters/github.ts +27 -4
- package/src/adapters/registry.ts +2 -1
- package/src/cli/setup.ts +14 -4
- package/src/config/checks.ts +13 -0
- package/src/config/migrate.ts +5 -2
- package/src/config/refusal.ts +8 -2
- package/src/config/schema.ts +67 -5
- package/src/config/wake-job.ts +74 -0
- package/src/service/workflows.ts +164 -47
- package/src/setup/propose.ts +74 -3
- package/src/setup/scan.ts +61 -5
- package/src/setup/tables.ts +18 -0
- package/src/setup/write.ts +50 -17
- package/surface.json +445 -40
package/defaults/hum.json
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
{
|
|
2
|
-
"schemaVersion":
|
|
2
|
+
"schemaVersion": 2,
|
|
3
3
|
"levels": [
|
|
4
4
|
{
|
|
5
5
|
"name": "low",
|
|
@@ -139,7 +139,14 @@
|
|
|
139
139
|
},
|
|
140
140
|
"restartDelaySeconds": 10,
|
|
141
141
|
"ciWakeTimeoutMinutes": 60,
|
|
142
|
-
"
|
|
142
|
+
"pullRequestToken": {
|
|
143
|
+
"from": "secret",
|
|
144
|
+
"secret": "HUM_GITHUB_TOKEN"
|
|
145
|
+
},
|
|
146
|
+
"ciRunner": "ubuntu-latest",
|
|
147
|
+
"ciContainer": null,
|
|
148
|
+
"ciEnv": {},
|
|
149
|
+
"ciClaudeAuth": "oauth-token",
|
|
143
150
|
"strictPaths": [],
|
|
144
151
|
"launches": [],
|
|
145
152
|
"sizeRange": {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@moo.md/hum",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "The hum engine: work items become Claude Code agent runs, the repo's checks decide what they can, and only what nothing settles becomes a question to the owner.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": {
|
package/schema/hum.schema.json
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
"properties": {
|
|
5
5
|
"schemaVersion": {
|
|
6
6
|
"type": "number",
|
|
7
|
-
"const":
|
|
7
|
+
"const": 2
|
|
8
8
|
},
|
|
9
9
|
"levels": {
|
|
10
10
|
"minItems": 1,
|
|
@@ -533,11 +533,55 @@
|
|
|
533
533
|
"maximum": 9007199254740991,
|
|
534
534
|
"description": "Seconds the service manager waits before it starts a failed start script again."
|
|
535
535
|
},
|
|
536
|
-
"
|
|
537
|
-
"default":
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
536
|
+
"pullRequestToken": {
|
|
537
|
+
"default": {
|
|
538
|
+
"from": "secret",
|
|
539
|
+
"secret": "HUM_GITHUB_TOKEN"
|
|
540
|
+
},
|
|
541
|
+
"oneOf": [
|
|
542
|
+
{
|
|
543
|
+
"type": "object",
|
|
544
|
+
"properties": {
|
|
545
|
+
"from": {
|
|
546
|
+
"type": "string",
|
|
547
|
+
"const": "secret"
|
|
548
|
+
},
|
|
549
|
+
"secret": {
|
|
550
|
+
"type": "string",
|
|
551
|
+
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
|
|
552
|
+
}
|
|
553
|
+
},
|
|
554
|
+
"required": [
|
|
555
|
+
"from",
|
|
556
|
+
"secret"
|
|
557
|
+
],
|
|
558
|
+
"additionalProperties": false
|
|
559
|
+
},
|
|
560
|
+
{
|
|
561
|
+
"type": "object",
|
|
562
|
+
"properties": {
|
|
563
|
+
"from": {
|
|
564
|
+
"type": "string",
|
|
565
|
+
"const": "app"
|
|
566
|
+
},
|
|
567
|
+
"clientIdSecret": {
|
|
568
|
+
"type": "string",
|
|
569
|
+
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
|
|
570
|
+
},
|
|
571
|
+
"privateKeySecret": {
|
|
572
|
+
"type": "string",
|
|
573
|
+
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
|
|
574
|
+
}
|
|
575
|
+
},
|
|
576
|
+
"required": [
|
|
577
|
+
"from",
|
|
578
|
+
"clientIdSecret",
|
|
579
|
+
"privateKeySecret"
|
|
580
|
+
],
|
|
581
|
+
"additionalProperties": false
|
|
582
|
+
}
|
|
583
|
+
],
|
|
584
|
+
"description": "Where a CI run's GitHub token comes from: { from: 'secret', secret } names a repository secret that holds a fine-grained token; { from: 'app', clientIdSecret, privateKeySecret } names the two secrets a GitHub App mints a token from each run, with the workflow's own permissions. clientIdSecret holds the App's client ID or its older App ID: the action that mints the token reads either as the same input. A pull request opened with the workflow token starts no workflows, so its required checks never run; one opened with this token does. A CI run falls back to the workflow token while the secret, or the client ID secret, is unset."
|
|
541
585
|
},
|
|
542
586
|
"ciWakeTimeoutMinutes": {
|
|
543
587
|
"default": 60,
|
|
@@ -546,6 +590,163 @@
|
|
|
546
590
|
"maximum": 9007199254740991,
|
|
547
591
|
"description": "Minutes a CI wake may run before GitHub stops it."
|
|
548
592
|
},
|
|
593
|
+
"ciRunner": {
|
|
594
|
+
"default": "ubuntu-latest",
|
|
595
|
+
"anyOf": [
|
|
596
|
+
{
|
|
597
|
+
"anyOf": [
|
|
598
|
+
{
|
|
599
|
+
"type": "string",
|
|
600
|
+
"minLength": 1
|
|
601
|
+
},
|
|
602
|
+
{
|
|
603
|
+
"minItems": 1,
|
|
604
|
+
"type": "array",
|
|
605
|
+
"items": {
|
|
606
|
+
"type": "string",
|
|
607
|
+
"minLength": 1
|
|
608
|
+
}
|
|
609
|
+
}
|
|
610
|
+
]
|
|
611
|
+
},
|
|
612
|
+
{
|
|
613
|
+
"type": "object",
|
|
614
|
+
"properties": {
|
|
615
|
+
"group": {
|
|
616
|
+
"type": "string",
|
|
617
|
+
"minLength": 1
|
|
618
|
+
},
|
|
619
|
+
"labels": {
|
|
620
|
+
"anyOf": [
|
|
621
|
+
{
|
|
622
|
+
"type": "string",
|
|
623
|
+
"minLength": 1
|
|
624
|
+
},
|
|
625
|
+
{
|
|
626
|
+
"minItems": 1,
|
|
627
|
+
"type": "array",
|
|
628
|
+
"items": {
|
|
629
|
+
"type": "string",
|
|
630
|
+
"minLength": 1
|
|
631
|
+
}
|
|
632
|
+
}
|
|
633
|
+
]
|
|
634
|
+
}
|
|
635
|
+
},
|
|
636
|
+
"required": [
|
|
637
|
+
"group"
|
|
638
|
+
],
|
|
639
|
+
"additionalProperties": false
|
|
640
|
+
}
|
|
641
|
+
],
|
|
642
|
+
"description": "What the CI wake job runs on, as a workflow's runs-on holds it: one runner label, a list of labels the runner must carry all of, or { group, labels } for a runner group. On a public repo, a runner GitHub does not host keeps what a wake leaves on it, and setup asks before it writes one."
|
|
643
|
+
},
|
|
644
|
+
"ciContainer": {
|
|
645
|
+
"default": null,
|
|
646
|
+
"anyOf": [
|
|
647
|
+
{
|
|
648
|
+
"anyOf": [
|
|
649
|
+
{
|
|
650
|
+
"type": "string",
|
|
651
|
+
"minLength": 1
|
|
652
|
+
},
|
|
653
|
+
{
|
|
654
|
+
"type": "object",
|
|
655
|
+
"properties": {
|
|
656
|
+
"image": {
|
|
657
|
+
"type": "string",
|
|
658
|
+
"minLength": 1
|
|
659
|
+
},
|
|
660
|
+
"credentials": {
|
|
661
|
+
"type": "object",
|
|
662
|
+
"properties": {
|
|
663
|
+
"username": {
|
|
664
|
+
"type": "string",
|
|
665
|
+
"minLength": 1
|
|
666
|
+
},
|
|
667
|
+
"password": {
|
|
668
|
+
"type": "string",
|
|
669
|
+
"minLength": 1
|
|
670
|
+
}
|
|
671
|
+
},
|
|
672
|
+
"required": [
|
|
673
|
+
"username",
|
|
674
|
+
"password"
|
|
675
|
+
],
|
|
676
|
+
"additionalProperties": false
|
|
677
|
+
},
|
|
678
|
+
"env": {
|
|
679
|
+
"type": "object",
|
|
680
|
+
"propertyNames": {
|
|
681
|
+
"type": "string",
|
|
682
|
+
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
|
|
683
|
+
},
|
|
684
|
+
"additionalProperties": {
|
|
685
|
+
"type": "string"
|
|
686
|
+
}
|
|
687
|
+
},
|
|
688
|
+
"ports": {
|
|
689
|
+
"type": "array",
|
|
690
|
+
"items": {
|
|
691
|
+
"anyOf": [
|
|
692
|
+
{
|
|
693
|
+
"type": "string",
|
|
694
|
+
"minLength": 1
|
|
695
|
+
},
|
|
696
|
+
{
|
|
697
|
+
"type": "integer",
|
|
698
|
+
"exclusiveMinimum": 0,
|
|
699
|
+
"maximum": 9007199254740991
|
|
700
|
+
}
|
|
701
|
+
]
|
|
702
|
+
}
|
|
703
|
+
},
|
|
704
|
+
"volumes": {
|
|
705
|
+
"type": "array",
|
|
706
|
+
"items": {
|
|
707
|
+
"type": "string",
|
|
708
|
+
"minLength": 1
|
|
709
|
+
}
|
|
710
|
+
},
|
|
711
|
+
"options": {
|
|
712
|
+
"type": "string",
|
|
713
|
+
"minLength": 1
|
|
714
|
+
}
|
|
715
|
+
},
|
|
716
|
+
"required": [
|
|
717
|
+
"image"
|
|
718
|
+
],
|
|
719
|
+
"additionalProperties": false
|
|
720
|
+
}
|
|
721
|
+
]
|
|
722
|
+
},
|
|
723
|
+
{
|
|
724
|
+
"type": "null"
|
|
725
|
+
}
|
|
726
|
+
],
|
|
727
|
+
"description": "The container the CI wake job runs in: its image, or { image, credentials: { username, password }, env, ports, volumes, options } as a workflow's container holds them, or null to run on the runner itself. The image needs git, node and npm; a container that runs as root needs IS_SANDBOX=1 in ciEnv, or Claude Code refuses to skip its permission prompts."
|
|
728
|
+
},
|
|
729
|
+
"ciEnv": {
|
|
730
|
+
"default": {},
|
|
731
|
+
"type": "object",
|
|
732
|
+
"propertyNames": {
|
|
733
|
+
"type": "string",
|
|
734
|
+
"pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
|
|
735
|
+
},
|
|
736
|
+
"additionalProperties": {
|
|
737
|
+
"type": "string"
|
|
738
|
+
},
|
|
739
|
+
"description": "Env the CI wake job sets, such as a gateway's settings; a value may be a workflow expression. A value that reads a secret reaches only the step that runs hum; every other value reaches every step, the installs too. A name the job sets itself, such as GH_TOKEN, is refused."
|
|
740
|
+
},
|
|
741
|
+
"ciClaudeAuth": {
|
|
742
|
+
"default": "oauth-token",
|
|
743
|
+
"type": "string",
|
|
744
|
+
"enum": [
|
|
745
|
+
"oauth-token",
|
|
746
|
+
"env"
|
|
747
|
+
],
|
|
748
|
+
"description": "How a CI run's Claude Code signs in: 'oauth-token' requires the CLAUDE_CODE_OAUTH_TOKEN secret, from `claude setup-token`; 'env' asks for no secret, and ciEnv carries the credentials, such as a gateway's settings."
|
|
749
|
+
},
|
|
549
750
|
"strictPaths": {
|
|
550
751
|
"default": [],
|
|
551
752
|
"type": "array",
|
|
@@ -1193,7 +1394,7 @@
|
|
|
1193
1394
|
"type": "string",
|
|
1194
1395
|
"minLength": 1
|
|
1195
1396
|
},
|
|
1196
|
-
"description": "GitHub logins whose pull request reviews and comments are the owner's review notes."
|
|
1397
|
+
"description": "GitHub logins whose pull request reviews and comments are the owner's review notes, and whose issue comments hum reads as replies. hum also reads the issue comments of the repo's owner, the owning organisation's members and invited collaborators, and reads no one else's."
|
|
1197
1398
|
},
|
|
1198
1399
|
"repeatAt": {
|
|
1199
1400
|
"default": 2,
|
package/src/adapters/github.ts
CHANGED
|
@@ -5,6 +5,7 @@ import { z } from "zod";
|
|
|
5
5
|
import { ADAPTER_API_VERSION, type AdapterContext, type Answers, type Claim, type Item, ItemId, PermanentError, type Integrations, type Questions, type Release, type Watch, type WorkSource } from "../adapter-api.ts";
|
|
6
6
|
import type { Json } from "../config/json.ts";
|
|
7
7
|
import type { MERGE_METHODS } from "../config/schema.ts";
|
|
8
|
+
import { TRUSTED_ASSOCIATIONS } from "../config/wake-job.ts";
|
|
8
9
|
import { HOUR_MS } from "../time.ts";
|
|
9
10
|
import { parseArgument } from "./argument.ts";
|
|
10
11
|
import { claimCommit, claimCommitMessage, claimer, claimOfCommit, isLive } from "./claim.ts";
|
|
@@ -30,6 +31,11 @@ const Commit = z.object({ oid: z.string(), message: z.string() });
|
|
|
30
31
|
|
|
31
32
|
const Labels = z.object({ nodes: z.array(z.object({ name: z.string() })) });
|
|
32
33
|
|
|
34
|
+
/** A comment with who wrote it; GitHub names no author once the account is deleted. */
|
|
35
|
+
const IssueComment = z.object({ body: z.string(), createdAt: z.string(), authorAssociation: z.string(), author: z.object({ __typename: z.string(), login: z.string() }).nullable() });
|
|
36
|
+
|
|
37
|
+
type IssueComment = z.infer<typeof IssueComment>;
|
|
38
|
+
|
|
33
39
|
const ReadyItems = z.object({
|
|
34
40
|
repository: z.object({
|
|
35
41
|
issues: z.object({ nodes: z.array(z.object({ number: z.int().positive(), title: z.string() })) }),
|
|
@@ -45,7 +51,7 @@ const ItemReply = z.object({
|
|
|
45
51
|
body: z.string(),
|
|
46
52
|
state: z.enum(["OPEN", "CLOSED"]),
|
|
47
53
|
labels: Labels,
|
|
48
|
-
comments: z.object({ nodes: z.array(
|
|
54
|
+
comments: z.object({ nodes: z.array(IssueComment) }),
|
|
49
55
|
}),
|
|
50
56
|
ref: z.object({ target: Commit.partial() }).nullable(),
|
|
51
57
|
}),
|
|
@@ -85,7 +91,7 @@ const ITEM = `query Item($owner: String!, $name: String!, $number: Int!, $claimR
|
|
|
85
91
|
issue(number: $number) {
|
|
86
92
|
id title body state
|
|
87
93
|
labels(first: 100) { nodes { name } }
|
|
88
|
-
comments(first: 100, after: $cursor) { nodes { body createdAt } pageInfo { hasNextPage endCursor } }
|
|
94
|
+
comments(first: 100, after: $cursor) { nodes { body createdAt authorAssociation author { __typename login } } pageInfo { hasNextPage endCursor } }
|
|
89
95
|
}
|
|
90
96
|
ref(qualifiedName: $claimRef) { target { ... on Commit { message } } }
|
|
91
97
|
}
|
|
@@ -149,6 +155,8 @@ export type GitHubOptions = {
|
|
|
149
155
|
/** Open issues with this label are the ready items. */
|
|
150
156
|
readonly readyLabel: string;
|
|
151
157
|
readonly mergeMethod: (typeof MERGE_METHODS)[number];
|
|
158
|
+
/** Logins whose comments are read whatever GitHub says of them, beside the people the repo trusts. */
|
|
159
|
+
readonly ownerLogins: readonly string[];
|
|
152
160
|
/** The client to use; by default one on the owner's own login. */
|
|
153
161
|
readonly client?: GitHubClient;
|
|
154
162
|
/** The owner's `commandTimeoutSeconds` in milliseconds: the limit of the `gh auth token` that reads the owner's login. */
|
|
@@ -166,14 +174,29 @@ type Whole = Integrations & {
|
|
|
166
174
|
|
|
167
175
|
type StandingClaim = { readonly claim: Claim; readonly sha: string };
|
|
168
176
|
|
|
177
|
+
const TRUSTED: ReadonlySet<string> = new Set(TRUSTED_ASSOCIATIONS);
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* Whether hum reads a comment. Anyone may comment on a public repo, a reply after a question is an answer, and hum's
|
|
181
|
+
* marker is only text, so who wrote a comment decides, never what it says. A person's is read when the repo trusts
|
|
182
|
+
* them or the owner names them. A bot's is read only when it is one of hum's own: in CI hum posts as the workflow's
|
|
183
|
+
* bot or the owner's App, and only a workflow or an App the owner installed posts as a bot at all.
|
|
184
|
+
*/
|
|
185
|
+
const isHeard = (owners: ReadonlySet<string>) => ({ body, author, authorAssociation }: IssueComment): boolean => {
|
|
186
|
+
if (author === null) return false;
|
|
187
|
+
|
|
188
|
+
return author.__typename === "Bot" ? parseComment(body, 0).author === "hum" : owners.has(author.login.toLowerCase()) || TRUSTED.has(authorAssociation);
|
|
189
|
+
};
|
|
190
|
+
|
|
169
191
|
/**
|
|
170
|
-
* GitHub on the owner's own login: issues are items, comments are the thread. Each read is one GraphQL query,
|
|
192
|
+
* GitHub on the owner's own login: issues are items, and the comments hum reads are the thread. Each read is one GraphQL query,
|
|
171
193
|
* each write one mutation. A claim is a branch: its first commit is made through REST, since no mutation makes a
|
|
172
194
|
* bare commit, and created with `createRef`; a renewal or an expired take is `createCommitOnBranch` on the head it
|
|
173
195
|
* read. `watch` is one REST request with `If-None-Match`, because GitHub answers 304 free of rate limit.
|
|
174
196
|
*/
|
|
175
197
|
export const githubAdapter = (options: GitHubOptions, { now, env }: AdapterContext): Whole => {
|
|
176
198
|
const { base, claimPrefix, readyLabel, mergeMethod, timeoutMs } = options;
|
|
199
|
+
const isHeardHere = isHeard(new Set(options.ownerLogins.map((login) => login.toLowerCase())));
|
|
177
200
|
const repo = parseArgument(Repo, options.repo);
|
|
178
201
|
const [owner = "", name = ""] = repo.split("/");
|
|
179
202
|
const where = { owner, name };
|
|
@@ -226,7 +249,7 @@ export const githubAdapter = (options: GitHubOptions, { now, env }: AdapterConte
|
|
|
226
249
|
|
|
227
250
|
issueIds.set(number, repository.issue.id);
|
|
228
251
|
|
|
229
|
-
return repository;
|
|
252
|
+
return { ...repository, issue: { ...repository.issue, comments: { nodes: repository.issue.comments.nodes.filter(isHeardHere) } } };
|
|
230
253
|
};
|
|
231
254
|
|
|
232
255
|
const comment = async (id: string, body: string): Promise<void> => {
|
package/src/adapters/registry.ts
CHANGED
|
@@ -33,6 +33,7 @@ const AdapterSettings = z.looseObject({
|
|
|
33
33
|
itemsDir: HumConfig.shape.itemsDir,
|
|
34
34
|
commitIdentity: HumConfig.shape.commitIdentity,
|
|
35
35
|
readyLabel: HumConfig.shape.readyLabel,
|
|
36
|
+
ownerLogins: HumConfig.shape.ownerLogins,
|
|
36
37
|
mergeMethod: HumConfig.shape.mergeMethod,
|
|
37
38
|
ownerBranchPrefix: HumConfig.shape.ownerBranchPrefix,
|
|
38
39
|
writeRaceRetries: HumConfig.shape.writeRaceRetries,
|
|
@@ -85,7 +86,7 @@ const BUILT_IN = {
|
|
|
85
86
|
github: async ({ path, settings, context }) => {
|
|
86
87
|
const timeoutMs = commandTimeoutMs(settings);
|
|
87
88
|
|
|
88
|
-
return githubAdapter({ repo: await githubRepo(path, timeoutMs), base: await defaultBase(path, timeoutMs), claimPrefix: settings.claimPrefix, readyLabel: settings.readyLabel, mergeMethod: settings.mergeMethod, timeoutMs }, context);
|
|
89
|
+
return githubAdapter({ repo: await githubRepo(path, timeoutMs), base: await defaultBase(path, timeoutMs), claimPrefix: settings.claimPrefix, readyLabel: settings.readyLabel, mergeMethod: settings.mergeMethod, ownerLogins: settings.ownerLogins, timeoutMs }, context);
|
|
89
90
|
},
|
|
90
91
|
roundup: async ({ context }) => roundupAdapter({}, context),
|
|
91
92
|
} satisfies Readonly<Record<string, (repo: Repo) => Promise<Adapter>>>;
|
package/src/cli/setup.ts
CHANGED
|
@@ -38,6 +38,15 @@ type GithubFacts = {
|
|
|
38
38
|
readonly workflowsMayOpenPullRequests: boolean;
|
|
39
39
|
};
|
|
40
40
|
|
|
41
|
+
const Visibility = z.object({ visibility: z.string() });
|
|
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
|
+
|
|
41
50
|
const WorkflowPermissions = z.object({ can_approve_pull_request_reviews: z.boolean() });
|
|
42
51
|
|
|
43
52
|
/** Setup reads before any `hum.json` is written, so its commands run on the shipped time limit. */
|
|
@@ -97,21 +106,22 @@ export const addSetupCommands = (root: Command, io: Io, done: (code: number) =>
|
|
|
97
106
|
const shipped = shippedConfig();
|
|
98
107
|
const scan = await scanRepo(io.cwd, base);
|
|
99
108
|
const facts = await githubFacts(io.cwd);
|
|
100
|
-
const
|
|
109
|
+
const isPublic = await isPublicRepo(io.cwd);
|
|
110
|
+
const proposal = proposeSetup(scan, shipped.hum, { labels: facts?.labels, isPublic: isPublic ?? true });
|
|
101
111
|
const { tracked, folders, ...shown } = scan;
|
|
102
112
|
const coverage = facts && kindCoverage(facts.items, shipped.hum.kinds, proposal.kindLabels);
|
|
103
113
|
const gitIdentity = await readGitIdentity(setupGit(io.cwd));
|
|
104
114
|
|
|
105
|
-
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, gitIdentity }, null, "\t")}\n`);
|
|
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`);
|
|
106
116
|
});
|
|
107
117
|
|
|
108
118
|
setup
|
|
109
119
|
.command("write")
|
|
110
120
|
.description("Write .hum/ and the service files from the answers file, or write nothing and say why.")
|
|
111
|
-
.requiredOption("--answers <file>", 'JSON: { "hum": {settings}, "waitHours": { "kind/state": hours }, "schemaVersion":
|
|
121
|
+
.requiredOption("--answers <file>", 'JSON: { "hum": {settings}, "waitHours": { "kind/state": hours }, "schemaVersion": 2 }')
|
|
112
122
|
.option("--home <folder>", "where the service unit goes; default the user's home")
|
|
113
123
|
.action(async ({ answers, home }: { answers: string; home?: string }) => {
|
|
114
|
-
const result = writeSetup(io.cwd, readAnswers(answers), { hopeSkills: listHopeSkills(await hopeRoot()), home, gitIdentity: await readGitIdentity(setupGit(io.cwd)) });
|
|
124
|
+
const result = writeSetup(io.cwd, readAnswers(answers), { hopeSkills: listHopeSkills(await hopeRoot()), home, gitIdentity: await readGitIdentity(setupGit(io.cwd)), isPublicRepo: await isPublicRepo(io.cwd) });
|
|
115
125
|
|
|
116
126
|
io.stdout(`${JSON.stringify(result.ok ? { written: result.written } : { refused: result.refusal.message }, null, "\t")}\n`);
|
|
117
127
|
done(result.ok ? EXIT_OK : EXIT_FAILED);
|
package/src/config/checks.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { toDirectedGraph } from "xstate/graph";
|
|
2
|
+
import { APP_TOKEN_MINUTES, WAKE_OWN_ENV } from "./wake-job.ts";
|
|
2
3
|
import { kindMachine } from "./machine.ts";
|
|
3
4
|
import type { Problem } from "./refusal.ts";
|
|
4
5
|
import {
|
|
@@ -193,6 +194,16 @@ const pathProblems = (hum: HumConfig): Problem[] => {
|
|
|
193
194
|
];
|
|
194
195
|
};
|
|
195
196
|
|
|
197
|
+
/** `ciEnv` sets none of the env the wake job sets itself. */
|
|
198
|
+
const wakeEnvProblems = ({ ciEnv }: HumConfig): Problem[] =>
|
|
199
|
+
Object.keys(ciEnv).flatMap((name): Problem[] => (WAKE_OWN_ENV.has(name) ? [{ problem: "wake-env-taken", name }] : []));
|
|
200
|
+
|
|
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
|
+
: [];
|
|
206
|
+
|
|
196
207
|
/** The proof a path names for a kind: its own, else the one for every kind. */
|
|
197
208
|
export const proofFor = (rule: PathRule, kind: string): string | undefined => rule.proofs?.[kind] ?? rule.proofs?.[ALL_KINDS];
|
|
198
209
|
|
|
@@ -210,4 +221,6 @@ export const checkConfig = (
|
|
|
210
221
|
...eventProblems(hum, kinds),
|
|
211
222
|
...skillProblems(hum, env),
|
|
212
223
|
...namingProblems(hum),
|
|
224
|
+
...wakeEnvProblems(hum),
|
|
225
|
+
...appTokenProblems(hum),
|
|
213
226
|
];
|
package/src/config/migrate.ts
CHANGED
|
@@ -21,8 +21,11 @@ export const climb = <T extends object>(value: T, from: number, to: number, step
|
|
|
21
21
|
/** Per earlier schema version: rewrites a config at that version into the next version's shape. */
|
|
22
22
|
export type Migrations = Steps<ConfigJson>;
|
|
23
23
|
|
|
24
|
-
/** One entry per earlier schema version.
|
|
25
|
-
export const MIGRATIONS
|
|
24
|
+
/** One entry per earlier schema version. Setup climbs the owner's answers, a part of a config, through the same steps, so a step rewrites only the keys it finds. */
|
|
25
|
+
export const MIGRATIONS = {
|
|
26
|
+
/** 2 holds the pull request token as one of its sources: the secret 1 named becomes `{ from: "secret", secret }`. */
|
|
27
|
+
1: ({ pullRequestTokenSecret, ...config }) => (pullRequestTokenSecret === undefined ? config : { ...config, pullRequestToken: { from: "secret", secret: pullRequestTokenSecret } }),
|
|
28
|
+
} satisfies Migrations;
|
|
26
29
|
|
|
27
30
|
const Raw = z.record(z.string(), Json);
|
|
28
31
|
const Version = z.int();
|
package/src/config/refusal.ts
CHANGED
|
@@ -14,7 +14,9 @@ export type Problem =
|
|
|
14
14
|
| { readonly problem: "missing-file"; readonly file: string }
|
|
15
15
|
| { readonly problem: "unknown-level"; readonly level: string }
|
|
16
16
|
| { readonly problem: "path-without-proof"; readonly glob: string; readonly level: string }
|
|
17
|
-
| { readonly problem: "overlapping-prefixes"; readonly run: string; readonly claim: string }
|
|
17
|
+
| { readonly problem: "overlapping-prefixes"; readonly run: string; readonly claim: string }
|
|
18
|
+
| { readonly problem: "wake-env-taken"; readonly name: string }
|
|
19
|
+
| { readonly problem: "wake-outlasts-app-token"; readonly minutes: number; readonly tokenMinutes: number };
|
|
18
20
|
|
|
19
21
|
/** A config change the engine will not take. The caller keeps the last good config. */
|
|
20
22
|
export type Refusal =
|
|
@@ -23,7 +25,8 @@ export type Refusal =
|
|
|
23
25
|
| { readonly code: "invalid-config"; readonly problems: readonly Problem[]; readonly message: string }
|
|
24
26
|
| { readonly code: "unmapped-state"; readonly items: readonly { readonly kind: string; readonly state: string }[]; readonly message: string }
|
|
25
27
|
| { readonly code: "change-from-run"; readonly branch: string; readonly message: string }
|
|
26
|
-
| { readonly code: "no-git-identity"; readonly missing: readonly string[]; readonly message: string }
|
|
28
|
+
| { readonly code: "no-git-identity"; readonly missing: readonly string[]; readonly message: string }
|
|
29
|
+
| { readonly code: "own-runner-on-public-repo"; readonly message: string };
|
|
27
30
|
|
|
28
31
|
export type Result<T> = { readonly ok: true; readonly value: T } | { readonly ok: false; readonly refusal: Refusal };
|
|
29
32
|
|
|
@@ -46,6 +49,9 @@ const DESCRIPTIONS = {
|
|
|
46
49
|
"unknown-level": (p) => `risk level "${p.level}" is not in levels`,
|
|
47
50
|
"path-without-proof": (p) => `path "${p.glob}" is at level "${p.level}", whose release waits for proof, and names no proof for every kind`,
|
|
48
51
|
"overlapping-prefixes": (p) => `the run branch prefix "${p.run}" and the claim prefix "${p.claim}" overlap: one starts with the other`,
|
|
52
|
+
"wake-env-taken": (p) => `ciEnv sets ${p.name}, which the CI wake job sets itself`,
|
|
53
|
+
"wake-outlasts-app-token": (p) =>
|
|
54
|
+
`ciWakeTimeoutMinutes is ${p.minutes}, and the token a GitHub App mints lasts ${p.tokenMinutes} minutes: a longer wake loses GitHub before it ends`,
|
|
49
55
|
} as const satisfies Describe;
|
|
50
56
|
|
|
51
57
|
// SAFETY: each description is keyed by the problem name it reads, so the lookup by `problem.problem` takes its own variant.
|
package/src/config/schema.ts
CHANGED
|
@@ -4,10 +4,10 @@ import { z } from "zod";
|
|
|
4
4
|
import shippedConfig from "../../defaults/hum.json" with { type: "json" };
|
|
5
5
|
|
|
6
6
|
/** The `hum.json` schema version this engine writes. */
|
|
7
|
-
export const SCHEMA_VERSION =
|
|
7
|
+
export const SCHEMA_VERSION = 2;
|
|
8
8
|
|
|
9
9
|
/** The schema versions this engine reads, each migrated up to `SCHEMA_VERSION` by `migrateConfig`. */
|
|
10
|
-
export const READABLE_SCHEMA_VERSIONS: readonly number[] = [1];
|
|
10
|
+
export const READABLE_SCHEMA_VERSIONS: readonly number[] = [1, 2];
|
|
11
11
|
|
|
12
12
|
/** Parts the engine ships; the owner adds roles, never these. */
|
|
13
13
|
export const FIXED_PARTS = [
|
|
@@ -57,6 +57,10 @@ export const MERGE_METHODS = ["merge", "squash", "rebase"] as const;
|
|
|
57
57
|
|
|
58
58
|
export type MergeMethod = (typeof MERGE_METHODS)[number];
|
|
59
59
|
|
|
60
|
+
const CLAUDE_AUTHS = ["oauth-token", "env"] as const;
|
|
61
|
+
|
|
62
|
+
const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
|
|
63
|
+
|
|
60
64
|
/** Who reviews a change before it merges: no one, a fresh agent review run, or that run and then the owner. */
|
|
61
65
|
export const REVIEWS = ["none", "agent", "owner"] as const;
|
|
62
66
|
|
|
@@ -117,6 +121,40 @@ const backoff = z
|
|
|
117
121
|
|
|
118
122
|
const fraction = z.number().gt(0).lt(1);
|
|
119
123
|
|
|
124
|
+
/** A name GitHub stores a secret under: a workflow reads it as `secrets.<name>`, and GitHub keeps the `GITHUB_` prefix for its own. */
|
|
125
|
+
const secretName = z
|
|
126
|
+
.string()
|
|
127
|
+
.regex(ENV_NAME, "a secret's name is letters, digits and underscores, and starts with no digit")
|
|
128
|
+
.refine((secret) => !/^GITHUB_/i.test(secret), "a secret's name may not start with GITHUB_, which GitHub keeps for its own");
|
|
129
|
+
|
|
130
|
+
const runnerLabels = z.union([name, z.array(name).min(1)]);
|
|
131
|
+
|
|
132
|
+
/** What a job's `runs-on` holds: one label, every label the runner must carry, or a runner group with the labels wanted in it. */
|
|
133
|
+
const Runner = z.union([runnerLabels, z.strictObject({ group: name, labels: runnerLabels.optional() })]);
|
|
134
|
+
|
|
135
|
+
const envName = z.string().regex(ENV_NAME, "an env name is letters, digits and underscores, and starts with no digit");
|
|
136
|
+
|
|
137
|
+
/** A job's container: its image alone, or the image with what a workflow's `container` holds beside it, each as written there. */
|
|
138
|
+
const Container = z.union([
|
|
139
|
+
name,
|
|
140
|
+
z.strictObject({
|
|
141
|
+
image: name,
|
|
142
|
+
credentials: z.strictObject({ username: name, password: name }).optional(),
|
|
143
|
+
env: z.record(envName, z.string()).optional(),
|
|
144
|
+
ports: z.array(z.union([name, z.int().positive()])).optional(),
|
|
145
|
+
volumes: z.array(name).optional(),
|
|
146
|
+
options: name.optional(),
|
|
147
|
+
}),
|
|
148
|
+
]);
|
|
149
|
+
|
|
150
|
+
/** Where a CI run's GitHub token comes from: a secret that holds one, or a GitHub App that mints one per run from its client ID and private key. */
|
|
151
|
+
const PullRequestToken = z.discriminatedUnion("from", [
|
|
152
|
+
z.strictObject({ from: z.literal("secret"), secret: secretName }),
|
|
153
|
+
z.strictObject({ from: z.literal("app"), clientIdSecret: secretName, privateKeySecret: secretName }),
|
|
154
|
+
]);
|
|
155
|
+
|
|
156
|
+
export type PullRequestToken = z.infer<typeof PullRequestToken>;
|
|
157
|
+
|
|
120
158
|
const Launch = z.union([
|
|
121
159
|
z.strictObject({ glob: name, level: name, from: date, until: date }).refine(({ from, until }) => from < until, "a launch ends after it starts"),
|
|
122
160
|
z.strictObject({ glob: name, level: name, base: name }),
|
|
@@ -163,8 +201,24 @@ const Shipped = z.object({
|
|
|
163
201
|
itemReadsAtOnce: count.describe("Item files the markdown source reads at once; each read is a git process."),
|
|
164
202
|
restartBackoff: backoff.describe("The pause before the service's first restart of a crashed worker, doubled each crash up to the longest pause."),
|
|
165
203
|
restartDelaySeconds: seconds.describe("Seconds the service manager waits before it starts a failed start script again."),
|
|
166
|
-
|
|
204
|
+
pullRequestToken: PullRequestToken.describe(
|
|
205
|
+
"Where a CI run's GitHub token comes from: { from: 'secret', secret } names a repository secret that holds a fine-grained token; { from: 'app', clientIdSecret, privateKeySecret } names the two secrets a GitHub App mints a token from each run, with the workflow's own permissions. clientIdSecret holds the App's client ID or its older App ID: the action that mints the token reads either as the same input. A pull request opened with the workflow token starts no workflows, so its required checks never run; one opened with this token does. A CI run falls back to the workflow token while the secret, or the client ID secret, is unset.",
|
|
206
|
+
),
|
|
167
207
|
ciWakeTimeoutMinutes: count.describe("Minutes a CI wake may run before GitHub stops it."),
|
|
208
|
+
ciRunner: Runner.describe(
|
|
209
|
+
"What the CI wake job runs on, as a workflow's runs-on holds it: one runner label, a list of labels the runner must carry all of, or { group, labels } for a runner group. On a public repo, a runner GitHub does not host keeps what a wake leaves on it, and setup asks before it writes one.",
|
|
210
|
+
),
|
|
211
|
+
ciContainer: Container.nullable().describe(
|
|
212
|
+
"The container the CI wake job runs in: its image, or { image, credentials: { username, password }, env, ports, volumes, options } as a workflow's container holds them, or null to run on the runner itself. The image needs git, node and npm; a container that runs as root needs IS_SANDBOX=1 in ciEnv, or Claude Code refuses to skip its permission prompts.",
|
|
213
|
+
),
|
|
214
|
+
ciEnv: z
|
|
215
|
+
.record(envName, z.string())
|
|
216
|
+
.describe(
|
|
217
|
+
"Env the CI wake job sets, such as a gateway's settings; a value may be a workflow expression. A value that reads a secret reaches only the step that runs hum; every other value reaches every step, the installs too. A name the job sets itself, such as GH_TOKEN, is refused.",
|
|
218
|
+
),
|
|
219
|
+
ciClaudeAuth: z
|
|
220
|
+
.enum(CLAUDE_AUTHS)
|
|
221
|
+
.describe("How a CI run's Claude Code signs in: 'oauth-token' requires the CLAUDE_CODE_OAUTH_TOKEN secret, from `claude setup-token`; 'env' asks for no secret, and ciEnv carries the credentials, such as a gateway's settings."),
|
|
168
222
|
strictPaths: z.array(name).describe("Globs of data and secrets: a change touching one takes the strictest level."),
|
|
169
223
|
launches: z
|
|
170
224
|
.array(Launch)
|
|
@@ -221,7 +275,11 @@ const Shipped = z.object({
|
|
|
221
275
|
.describe(
|
|
222
276
|
"Prewarmed run slots on the Mac: worktrees of the owner's checkout that background runs work in, as many as 'runners'. 'pool' is the folder that holds them, relative to the checkout or absolute, and never inside .git, where Claude Code writes nothing; 'services' gives each slot its own services or one shared set with a database per slot; 'ports' starts each slot's block of ports; 'recipe' is the owner's own setup commands.",
|
|
223
277
|
),
|
|
224
|
-
ownerLogins: z
|
|
278
|
+
ownerLogins: z
|
|
279
|
+
.array(name)
|
|
280
|
+
.describe(
|
|
281
|
+
"GitHub logins whose pull request reviews and comments are the owner's review notes, and whose issue comments hum reads as replies. hum also reads the issue comments of the repo's owner, the owning organisation's members and invited collaborators, and reads no one else's.",
|
|
282
|
+
),
|
|
225
283
|
repeatAt: count.describe("Review notes stating one rule at which hum files a check item for it."),
|
|
226
284
|
repeatPrecision: fraction.describe("The lowest precision on labelled pairs at which a model's call that two notes state one rule files a check item; below it the pair waits as a possible repeat."),
|
|
227
285
|
tasteRules: z.array(name).describe("The owner's taste rules that have no deterministic check. Each pull request hum opens gets a comment saying whether its diff keeps each rule; the comment reports only and gates nothing."),
|
|
@@ -417,7 +475,11 @@ export const OWNER_CHANGEABLE = {
|
|
|
417
475
|
"restart backoff": "restartBackoff",
|
|
418
476
|
"restart delay": "restartDelaySeconds",
|
|
419
477
|
"CI wake timeout": "ciWakeTimeoutMinutes",
|
|
420
|
-
"pull request token
|
|
478
|
+
"pull request token": "pullRequestToken",
|
|
479
|
+
"CI runner": "ciRunner",
|
|
480
|
+
"CI container": "ciContainer",
|
|
481
|
+
"CI env": "ciEnv",
|
|
482
|
+
"CI Claude auth": "ciClaudeAuth",
|
|
421
483
|
"data and secrets paths": "strictPaths",
|
|
422
484
|
"path rules": "paths",
|
|
423
485
|
launches: "launches",
|