@moo.md/hum 0.2.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 (70) hide show
  1. package/defaults/hum.json +14 -2
  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 +251 -10
  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 +36 -4
  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 +5 -7
  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 +16 -7
  27. package/src/config/checks.ts +27 -43
  28. package/src/config/load.ts +2 -3
  29. package/src/config/machine.ts +29 -0
  30. package/src/config/migrate.ts +5 -2
  31. package/src/config/refusal.ts +9 -4
  32. package/src/config/schema.ts +86 -8
  33. package/src/config/wake-job.ts +78 -0
  34. package/src/decide/risk.ts +2 -2
  35. package/src/exec.ts +10 -0
  36. package/src/index.ts +1 -1
  37. package/src/loop/records.ts +8 -1
  38. package/src/measure/rate.ts +14 -0
  39. package/src/publish/bundle.ts +128 -0
  40. package/src/publish/handoff.ts +107 -0
  41. package/src/publish/handover.ts +182 -0
  42. package/src/publish/intents.ts +61 -0
  43. package/src/publish/publisher.ts +259 -0
  44. package/src/publish/wake.ts +78 -0
  45. package/src/service/ci-state.ts +99 -0
  46. package/src/service/plugins.ts +137 -0
  47. package/src/service/wake.ts +3 -1
  48. package/src/service/workflows.ts +261 -50
  49. package/src/setup/propose.ts +87 -3
  50. package/src/setup/prove.ts +3 -3
  51. package/src/setup/scan.ts +61 -5
  52. package/src/setup/tables.ts +18 -0
  53. package/src/setup/write.ts +52 -19
  54. package/src/state/items.ts +17 -8
  55. package/src/state/open.ts +20 -6
  56. package/src/state/records.ts +7 -0
  57. package/src/state/runs.ts +5 -0
  58. package/src/state/saved.ts +17 -2
  59. package/src/worker/base-check.ts +41 -13
  60. package/src/worker/checks.ts +3 -2
  61. package/src/worker/evidence.ts +72 -0
  62. package/src/worker/kind.ts +4 -7
  63. package/src/worker/land.ts +173 -81
  64. package/src/worker/merged.ts +20 -8
  65. package/src/worker/open.ts +33 -17
  66. package/src/worker/questions.ts +16 -8
  67. package/src/worker/signed-push.ts +167 -0
  68. package/src/worker/thin-path.ts +245 -133
  69. package/src/worker/worker.ts +50 -9
  70. package/surface.json +610 -76
@@ -1,11 +1,17 @@
1
1
  import type { Item } from "../adapter-api.ts";
2
2
  import { declaredKind } from "../decide/kind.ts";
3
3
  import { usualSize } from "../decide/risk.ts";
4
- import type { DefaultsConfig, HumConfig, PathRule, RunPlace, SlotRecipe } from "../config/schema.ts";
4
+ import type { DefaultsConfig, HumConfig, PathRule, PullRequestToken, RunPlace, Slot, SlotRecipe } from "../config/schema.ts";
5
+ import { APP_TOKEN_ACTION, CI_WORKFLOW_FILES, CLAUDE_TOKEN, isGitHubHosted, readsForeignContext, WAKE_OWN_ENV } from "../config/wake-job.ts";
5
6
  import type { CiJob, RepoScan } from "./scan.ts";
6
7
  import {
7
8
  CHECK_COMMAND,
8
9
  CHECK_SCRIPTS,
10
+ CLAUDE_ACTION,
11
+ CLAUDE_ACTION_SIGN_IN,
12
+ CLAUDE_API_KEY,
13
+ CLAUDE_CREDENTIAL_ENV,
14
+ CLAUDE_COMMAND,
9
15
  DATA_AND_SECRET_GLOBS,
10
16
  DEFAULT_FOLDER_RANK,
11
17
  FOLDER_RANKS,
@@ -15,6 +21,7 @@ import {
15
21
  ROOT_MARKDOWN_RANK,
16
22
  RUN_SCRIPT,
17
23
  SECRET_TEMPLATE,
24
+ SECRET_VALUE,
18
25
  } from "./tables.ts";
19
26
 
20
27
  /** The settings setup proposes from a scan; the owner changes any of them before they are written. */
@@ -28,6 +35,9 @@ export type Proposal = {
28
35
  readonly kindLabels: Readonly<Record<string, string>>;
29
36
  readonly runSlots: Pick<HumConfig["runSlots"], "services" | "recipe">;
30
37
  readonly runPlaces: readonly RunPlace[];
38
+ readonly wakeJob: Pick<HumConfig, "ciRunner" | "ciContainer" | "ciEnv" | "ciClaudeAuth" | "pullRequestToken">;
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"]>;
31
41
  };
32
42
 
33
43
  const isPullRequestJob = ({ triggers }: CiJob): boolean => triggers.includes("pull_request");
@@ -103,8 +113,80 @@ const recipeOf = (scan: RepoScan, checks: readonly string[]): SlotRecipe => {
103
113
  };
104
114
  };
105
115
 
116
+ const isAction = (uses: string, action: string): boolean => uses.startsWith(`${action}@`);
117
+
118
+ const runsClaude = ({ commands, actions }: CiJob): boolean => commands.some((command) => CLAUDE_COMMAND.test(command)) || actions.some(({ uses }) => isAction(uses, CLAUDE_ACTION));
119
+
120
+ const secretIn = (value: string | undefined): string | undefined => (value === undefined ? undefined : SECRET_VALUE.exec(value)?.[1]);
121
+
122
+ /** The first GitHub App a job mints a token from with both its client ID, or its older App ID, and its private key in secrets. */
123
+ const appOf = (jobs: readonly CiJob[]): PullRequestToken | undefined =>
124
+ jobs
125
+ .flatMap(({ actions }) => actions)
126
+ .flatMap(({ uses, with: inputs }): PullRequestToken[] => {
127
+ const clientIdSecret = secretIn(inputs["client-id"] ?? inputs["app-id"]);
128
+ const privateKeySecret = secretIn(inputs["private-key"]);
129
+
130
+ return isAction(uses, APP_TOKEN_ACTION) && clientIdSecret !== undefined && privateKeySecret !== undefined ? [{ from: "app", clientIdSecret, privateKeySecret }] : [];
131
+ })[0];
132
+
133
+ /** The inputs a job gives the Claude Code action, all its steps together. */
134
+ const claudeInputsOf = ({ actions }: CiJob): Readonly<Record<string, string>> =>
135
+ Object.assign({}, ...actions.filter(({ uses }) => isAction(uses, CLAUDE_ACTION)).map((action) => action.with));
136
+
137
+ /** Whether a job hands Claude Code an OAuth token: its env, commands or action inputs name the token, or the action takes one under any secret's name. */
138
+ const readsClaudeToken = (job: CiJob): boolean =>
139
+ CLAUDE_ACTION_SIGN_IN.oauthToken in claudeInputsOf(job) ||
140
+ [...Object.entries(job.env).flat(), ...job.commands, ...job.actions.flatMap((action) => Object.values(action.with))].some((text) => text.includes(CLAUDE_TOKEN));
141
+
142
+ /** The env the Claude Code job signs in and runs with: its own, without the names the wake job sets itself, and the API key its action takes as an input. */
143
+ const claudeEnvOf = (job: CiJob): Record<string, string> => {
144
+ const apiKey = claudeInputsOf(job)[CLAUDE_ACTION_SIGN_IN.apiKey];
145
+ const fromInput = apiKey === undefined ? [] : [[CLAUDE_API_KEY, apiKey] as const];
146
+
147
+ return Object.fromEntries([...Object.entries(job.env), ...fromInput].filter(([name, value]) => !WAKE_OWN_ENV.has(name) && !readsForeignContext(value)));
148
+ };
149
+
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"])) : {};
162
+
163
+ /**
164
+ * The wake job's settings from the job most like it: the one that runs Claude Code gives its runner, container, env
165
+ * and sign-in; without one, the first pull request job that names a runner gives its runner and container. hum's own
166
+ * workflows are left out, so a second setup reads the owner's. The App comes from any job that mints a token. Sign-in
167
+ * through env is proposed only where the env holds a credential, so no proposal signs in with nothing. A value that
168
+ * reads a context the wake job lacks would break the wake, so it is not proposed. On a public repo a runner GitHub
169
+ * does not host is never proposed: the owner names one on their own.
170
+ */
171
+ const wakeJobOf = (ci: readonly CiJob[], shipped: DefaultsConfig, isPublic: boolean): Proposal["wakeJob"] => {
172
+ const jobs = ci.filter(({ file }) => !CI_WORKFLOW_FILES.has(file));
173
+ const claude = jobs.find(runsClaude);
174
+ const like = claude ?? jobs.find((job) => isPullRequestJob(job) && job.runner !== undefined);
175
+ const ciEnv = claude ? claudeEnvOf(claude) : shipped.ciEnv;
176
+ const holdsCredential = Object.keys(ciEnv).some((name) => CLAUDE_CREDENTIAL_ENV.has(name));
177
+ const mayRunOn = (runner: HumConfig["ciRunner"]): boolean => !readsForeignContext(runner) && (!isPublic || isGitHubHosted(runner));
178
+
179
+ return {
180
+ ciRunner: like?.runner !== undefined && mayRunOn(like.runner) ? like.runner : shipped.ciRunner,
181
+ ciContainer: like?.container !== undefined && !readsForeignContext(like.container) ? like.container : shipped.ciContainer,
182
+ ciEnv,
183
+ ciClaudeAuth: claude && readsClaudeToken(claude) ? "oauth-token" : claude && holdsCredential ? "env" : shipped.ciClaudeAuth,
184
+ pullRequestToken: appOf(jobs) ?? shipped.pullRequestToken,
185
+ };
186
+ };
187
+
106
188
  /** Everything setup proposes from a scan, before it asks. */
107
- export const proposeSetup = (scan: RepoScan, shipped: DefaultsConfig, repoLabels: readonly string[] = []): Proposal => {
189
+ export const proposeSetup = (scan: RepoScan, shipped: DefaultsConfig, { labels = [], isPublic = false, openIssues }: RepoFacts = {}): Proposal => {
108
190
  const checks = checksOf(scan);
109
191
 
110
192
  return {
@@ -113,8 +195,10 @@ export const proposeSetup = (scan: RepoScan, shipped: DefaultsConfig, repoLabels
113
195
  strictPaths: strictGlobsOf(scan.tracked),
114
196
  usualSizes: scan.folders.map(({ folder, sizes }) => ({ folder, usual: usualSize(sizes, shipped.sizeRange) })),
115
197
  windows: { fixWindow: shipped.changeLabels.fixWindow, measureWindow: shipped.measureWindow },
116
- kindLabels: kindLabelsOf(scan, repoLabels, shipped.kinds),
198
+ kindLabels: kindLabelsOf(scan, labels, shipped.kinds),
117
199
  runSlots: { services: shipped.runSlots.services, recipe: recipeOf(scan, checks) },
118
200
  runPlaces: shipped.runPlaces,
201
+ wakeJob: wakeJobOf(scan.ci, shipped, isPublic),
202
+ integrations: integrationsOf(scan, openIssues),
119
203
  };
120
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",
package/src/setup/scan.ts CHANGED
@@ -4,7 +4,7 @@ import { parseDocument } from "yaml";
4
4
  import { z } from "zod";
5
5
  import { gitIn } from "../adapters/git.ts";
6
6
  import { readHistory } from "../adapters/history.ts";
7
- import { SHIPPED_DEFAULTS } from "../config/schema.ts";
7
+ import { type HumConfig, SHIPPED_DEFAULTS } from "../config/schema.ts";
8
8
  import { SHIPPED_COMMAND_TIMEOUT_MS } from "../exec.ts";
9
9
  import { orMissing } from "../state/fs.ts";
10
10
  import {
@@ -22,8 +22,20 @@ import {
22
22
  WORKFLOW_FOLDER,
23
23
  } from "./tables.ts";
24
24
 
25
- /** One job of a CI workflow: when it runs and the shell commands its steps run. */
26
- export type CiJob = { readonly file: string; readonly job: string; readonly triggers: readonly string[]; readonly commands: readonly string[] };
25
+ /** One job of a CI workflow: when it runs, where, with what env, and the shell commands and actions its steps run. */
26
+ export type CiJob = {
27
+ readonly file: string;
28
+ readonly job: string;
29
+ readonly triggers: readonly string[];
30
+ readonly commands: readonly string[];
31
+ /** What the job's `runs-on` holds: a label, a label list or a runner group. */
32
+ readonly runner: HumConfig["ciRunner"] | undefined;
33
+ /** The job's container: its image, with the registry sign-in, env, ports, volumes and options where the job names them. */
34
+ readonly container: NonNullable<HumConfig["ciContainer"]> | undefined;
35
+ /** The env every step gets: the workflow's, with the job's own over it. */
36
+ readonly env: Readonly<Record<string, string>>;
37
+ readonly actions: readonly { readonly uses: string; readonly with: Readonly<Record<string, string>> }[];
38
+ };
27
39
 
28
40
  type FolderHistory = { readonly folder: string; readonly changes: number; readonly sizes: readonly number[] };
29
41
 
@@ -61,9 +73,49 @@ const PackageJson = z.looseObject({
61
73
  devDependencies: z.record(z.string(), z.string()).default({}),
62
74
  });
63
75
 
76
+ /** YAML reads `1` and `true` as a number and a boolean; a workflow passes each on as text. */
77
+ const Text = z.union([z.string(), z.number(), z.boolean()]).transform(String);
78
+
79
+ /** A map's entries that are text: one that is not, such as a key YAML reads with no value, is left out alone. No entries where the workflow writes an expression in the map's place. */
80
+ const TextMap = z
81
+ .record(z.string(), z.unknown())
82
+ .catch({})
83
+ .transform((map) => Object.fromEntries(Object.entries(map).flatMap(([key, value]) => (Text.safeParse(value).success ? [[key, String(value)]] : []))));
84
+
85
+ const RunnerLabels = z.union([z.string(), z.array(z.string()).min(1)]);
86
+
87
+ /** A key the workflow leaves out stays out, so what a scan reads has the shape `hum.json` holds. */
88
+ const withoutUnset = <T extends object>(value: T): T => JSON.parse(JSON.stringify(value));
89
+
90
+ const RunsOn = z
91
+ .union([RunnerLabels, z.looseObject({ group: z.string(), labels: RunnerLabels.optional() }).transform(({ group, labels }) => withoutUnset({ group, labels })), z.looseObject({ labels: RunnerLabels }).transform(({ labels }) => labels)])
92
+ .optional()
93
+ .catch(undefined);
94
+
95
+ const Container = z
96
+ .union([
97
+ z.string(),
98
+ z
99
+ .object({ image: z.string(), credentials: z.object({ username: Text, password: Text }).optional(), env: TextMap.optional(), ports: z.array(z.union([z.string(), z.number()])).optional(), volumes: z.array(z.string()).optional(), options: z.string().optional() })
100
+ .transform(({ image, ...beside }) => (Object.values(beside).every((value) => value === undefined) ? image : withoutUnset({ image, ...beside }))),
101
+ ])
102
+ .optional()
103
+ .catch(undefined);
104
+
64
105
  const Workflow = z.looseObject({
65
106
  on: z.union([z.string().transform((trigger) => [trigger]), z.array(z.string()), z.record(z.string(), z.unknown()).transform((triggers) => Object.keys(triggers))]).default([]),
66
- jobs: z.record(z.string(), z.looseObject({ steps: z.array(z.looseObject({ run: z.string().optional() })).default([]) })).default({}),
107
+ env: TextMap,
108
+ jobs: z
109
+ .record(
110
+ z.string(),
111
+ z.looseObject({
112
+ "runs-on": RunsOn,
113
+ container: Container,
114
+ env: TextMap,
115
+ steps: z.array(z.looseObject({ run: z.string().optional(), uses: z.string().optional(), with: TextMap })).default([]),
116
+ }),
117
+ )
118
+ .default({}),
67
119
  });
68
120
 
69
121
  const Compose = z.looseObject({ services: z.record(z.string(), z.looseObject({ image: z.string().optional() })).default({}) });
@@ -95,11 +147,15 @@ const ciJobsOf = (repo: string): CiJob[] =>
95
147
 
96
148
  const triggers = workflow.on;
97
149
 
98
- return Object.entries(workflow.jobs).map(([job, { steps }]) => ({
150
+ return Object.entries(workflow.jobs).map(([job, { steps, ...where }]) => ({
99
151
  file: basename(file),
100
152
  job,
101
153
  triggers,
102
154
  commands: steps.flatMap((step) => commandsOf(step.run ?? "")),
155
+ runner: where["runs-on"],
156
+ container: where.container,
157
+ env: { ...workflow.env, ...where.env },
158
+ actions: steps.flatMap((step) => (step.uses === undefined ? [] : [{ uses: step.uses, with: step.with }])),
103
159
  }));
104
160
  });
105
161
 
@@ -40,6 +40,24 @@ export const CHECK_COMMAND = /\b(test|tests|lint|typecheck|type-check|tsc|check|
40
40
  /** A CI command line that is not a check, whatever words it holds: installs, publishing, shell plumbing. */
41
41
  export const NOT_A_CHECK = /^(echo|export|cd|mkdir|cp|mv|rm|curl|wget|sudo|gh|git)\b|\b(install|publish|deploy|release|upload|setup)\b/;
42
42
 
43
+ /** A CI command line that installs or runs Claude Code. */
44
+ export const CLAUDE_COMMAND = /@anthropic-ai\/claude-code|(^|[\s;&|(])claude(\s|$)/;
45
+
46
+ /** The action a CI step runs Claude Code with, named without its version. */
47
+ export const CLAUDE_ACTION = "anthropics/claude-code-action";
48
+
49
+ /** The action's inputs that sign Claude Code in: an API key, and the OAuth token `claude setup-token` makes. */
50
+ export const CLAUDE_ACTION_SIGN_IN = { apiKey: "anthropic_api_key", oauthToken: "claude_code_oauth_token" } as const;
51
+
52
+ /** The env name Claude Code reads an API key from. */
53
+ export const CLAUDE_API_KEY = "ANTHROPIC_API_KEY";
54
+
55
+ /** Env that signs Claude Code in with no OAuth token: a key, a gateway's token, or a cloud provider whose own credentials the job holds. */
56
+ export const CLAUDE_CREDENTIAL_ENV: ReadonlySet<string> = new Set([CLAUDE_API_KEY, "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CODE_USE_FOUNDRY"]);
57
+
58
+ /** An input or env value that is one secret, which the first group names. */
59
+ export const SECRET_VALUE = /^\$\{\{\s*secrets\.(\w+)\s*\}\}$/;
60
+
43
61
  /** The files that hold a repo's tool versions. */
44
62
  export const TOOL_VERSION_FILES = [".tool-versions", ".nvmrc", ".node-version", ".bun-version", ".python-version", "mise.toml", ".mise.toml", "rust-toolchain.toml", ".go-version"] as const;
45
63
 
@@ -8,7 +8,8 @@ import { hashJson } from "../config/hash.ts";
8
8
  import { Json } from "../config/json.ts";
9
9
  import { migrateConfig } from "../config/migrate.ts";
10
10
  import { noGitIdentity, type Refusal, type Result } from "../config/refusal.ts";
11
- import { Kind, READABLE_SCHEMA_VERSIONS, SCHEMA_VERSION } from "../config/schema.ts";
11
+ import { type HumConfig, Kind, READABLE_SCHEMA_VERSIONS, SCHEMA_VERSION } from "../config/schema.ts";
12
+ import { isGitHubHosted } from "../config/wake-job.ts";
12
13
  import { ciWorkflows } from "../service/workflows.ts";
13
14
  import { renderUnit, type UnitKind } from "../service/unit.ts";
14
15
  import { atomicWrite } from "../state/fs.ts";
@@ -28,12 +29,14 @@ export const SetupAnswers = z.strictObject({
28
29
  waitHours: z.record(z.string(), z.number().positive()).default({}),
29
30
  /** The schema version the writing skill produces; a newer one than this engine reads is refused. */
30
31
  schemaVersion: z.int().optional(),
32
+ /** Set only after the owner said yes: CI wakes may run on a runner GitHub does not host although anyone may comment on the repo. */
33
+ ownRunnerOnPublicRepo: z.literal(true).optional(),
31
34
  });
32
35
 
33
36
  export type SetupAnswers = z.infer<typeof SetupAnswers>;
34
37
 
35
38
  export type SetupEnv = {
36
- readonly hopeSkills: ReadonlySet<string>;
39
+ readonly installedSkills: ReadonlySet<string>;
37
40
  /** Where a Mac or Linux service unit is written; default the user's home. */
38
41
  readonly home?: string;
39
42
  readonly platform?: NodeJS.Platform;
@@ -41,26 +44,43 @@ export type SetupEnv = {
41
44
  readonly runtime?: { readonly bun: string; readonly path: string };
42
45
  /** The owner's name and email as git config holds them: the identity hum.json takes unless it names one already. */
43
46
  readonly gitIdentity: GitIdentityRead;
47
+ /** Whether anyone may read and comment on the repo, as GitHub says; left out where nothing could say. */
48
+ readonly isPublicRepo?: boolean;
44
49
  };
45
50
 
46
51
  export type SetupResult = { readonly ok: true; readonly written: readonly string[]; readonly config: Config } | { readonly ok: false; readonly refusal: Refusal };
47
52
 
48
53
  const UPDATE_ENGINE = "Update the engine: bun add --exact @moo.md/hum@latest.";
49
54
 
50
- /** Refuses a schema the installed engine does not read, whether the existing file has it or the writer would produce it. */
51
- const schemaRefusal = (existing: Json | undefined, target: number): Refusal | undefined => {
52
- if (!READABLE_SCHEMA_VERSIONS.includes(target)) {
53
- return {
54
- code: "unknown-schema-version",
55
- found: target,
56
- readable: READABLE_SCHEMA_VERSIONS,
57
- message: `Setup would write hum.json schemaVersion ${target}, and this engine reads ${READABLE_SCHEMA_VERSIONS.join(", ")}. ${UPDATE_ENGINE} Nothing was written.`,
58
- };
59
- }
55
+ /** Refuses answers written for a schema the installed engine does not read. */
56
+ const targetRefusal = (target: number): Refusal | undefined =>
57
+ READABLE_SCHEMA_VERSIONS.includes(target)
58
+ ? undefined
59
+ : {
60
+ code: "unknown-schema-version",
61
+ found: target,
62
+ readable: READABLE_SCHEMA_VERSIONS,
63
+ message: `Setup would write hum.json schemaVersion ${target}, and this engine reads ${READABLE_SCHEMA_VERSIONS.join(", ")}. ${UPDATE_ENGINE} Nothing was written.`,
64
+ };
60
65
 
61
- const migrated = existing === undefined ? undefined : migrateConfig(existing);
62
-
63
- return migrated && !migrated.ok ? { ...migrated.refusal, message: `${migrated.refusal.message} Nothing was written.` } : undefined;
66
+ /**
67
+ * A wake runs an agent that holds the owner's secrets. On a runner GitHub does not host, what a wake leaves behind
68
+ * stays on the machine, and on a public repo more people reach what starts a wake. So the owner says yes to the two
69
+ * together, and a repo whose visibility nothing could read counts as public.
70
+ */
71
+ const ownRunnerRefusal = ({ runPlaces, ciRunner }: HumConfig, answers: SetupAnswers, isPublicRepo: boolean | undefined): Refusal | undefined =>
72
+ !runPlaces.includes("ci") || isGitHubHosted(ciRunner) || isPublicRepo === false || answers.ownRunnerOnPublicRepo === true
73
+ ? undefined
74
+ : {
75
+ code: "own-runner-on-public-repo",
76
+ message: `ciRunner names a runner GitHub does not host, and this repo ${isPublicRepo ? "is public" : "may be public: gh could not say"}. A wake there runs an agent with your secrets on a machine that keeps what the wake leaves. Name a runner GitHub hosts, or ask the owner and set "ownRunnerOnPublicRepo": true in the answers. Nothing was written.`,
77
+ };
78
+
79
+ /** Settings migrated to the schema this engine writes, so the repo's file and the answers merge at one version; refused at a schema it does not read. */
80
+ const atCurrentSchema = (hum: Json): Result<Readonly<Record<string, Json>>> => {
81
+ const migrated = migrateConfig(hum);
82
+
83
+ return migrated.ok ? migrated : { ok: false, refusal: { ...migrated.refusal, message: `${migrated.refusal.message} Nothing was written.` } };
64
84
  };
65
85
 
66
86
  /** The identity hum.json already holds, else the one git config holds, else the refusal that says what to set. */
@@ -99,14 +119,23 @@ const asJson = (value: Kind | Readonly<Record<string, Json>>): Json => Json.pars
99
119
  */
100
120
  export const writeSetup = (repo: string, answers: SetupAnswers, env: SetupEnv): SetupResult => {
101
121
  const existing = readExisting(repo);
102
- const refused = schemaRefusal(existing?.hum, answers.schemaVersion ?? SCHEMA_VERSION);
122
+ const target = answers.schemaVersion ?? SCHEMA_VERSION;
123
+ const refused = targetRefusal(target);
103
124
 
104
125
  if (refused) return { ok: false, refusal: refused };
105
126
 
106
127
  const shipped = shippedRaw();
107
128
  const base = existing ?? shipped;
129
+ const fromRepo = atCurrentSchema(base.hum);
130
+
131
+ if (!fromRepo.ok) return fromRepo;
132
+
133
+ const answered = atCurrentSchema({ ...answers.hum, schemaVersion: target });
134
+
135
+ if (!answered.ok) return answered;
136
+
108
137
  const shippedHum = HumObject.parse(shipped.hum);
109
- const given = { ...HumObject.parse(base.hum), ...answers.hum };
138
+ const given = { ...fromRepo.value, ...answered.value };
110
139
  const identity = identityOf(given, env.gitIdentity);
111
140
 
112
141
  if (!identity.ok) return identity;
@@ -115,10 +144,14 @@ export const writeSetup = (repo: string, answers: SetupAnswers, env: SetupEnv):
115
144
  const timed = withTimeouts(parsedKinds(base), answers.waitHours);
116
145
  const kinds = Object.fromEntries(Object.entries(base.kinds).map(([name, file]) => [name, timed[name] ? asJson(timed[name]) : file]));
117
146
  const roles = { ...shipped.roles, ...existing?.roles };
118
- 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 } });
119
148
 
120
149
  if (!loaded.ok) return { ok: false, refusal: loaded.refusal };
121
150
 
151
+ const ownRunner = ownRunnerRefusal(loaded.value.hum, answers, env.isPublicRepo);
152
+
153
+ if (ownRunner) return { ok: false, refusal: ownRunner };
154
+
122
155
  const files = [
123
156
  { path: join(repo, ".hum", "hum.json"), text: jsonText(ownerKeys(hum, shippedHum)) },
124
157
  ...Object.entries(kinds).map(([name, kind]) => ({ path: join(repo, ".hum", "kinds", `${name}.json`), text: jsonText(kind) })),
@@ -164,5 +197,5 @@ const serviceFile = (repo: string, config: Config, env: SetupEnv): FileToWrite =
164
197
  };
165
198
  };
166
199
 
167
- /** The answers file the skill writes: `{ "hum": {...}, "waitHours": {...}, "schemaVersion": 1 }`. */
200
+ /** The answers file the skill writes: `{ "hum": {...}, "waitHours": {...}, "schemaVersion": 2 }`, with `"ownRunnerOnPublicRepo": true` once the owner agreed to it. */
168
201
  export const readAnswers = (file: string): SetupAnswers => SetupAnswers.parse(JSON.parse(readFileSync(file, "utf8")));
@@ -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. */