@davidbyoung/software-factory 0.1.3 → 0.1.4
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/README.md +12 -11
- package/actions/factory-agent/action.yml +1 -1
- package/agents/factory-e2e-reviewer.md +102 -0
- package/agents/factory-test-reviewer.md +26 -64
- package/agents/factory-ticket-readiness.md +14 -6
- package/dist/cli.mjs +29 -2
- package/dist/commands.d.mts +16 -0
- package/dist/commands.mjs +129 -0
- package/dist/config.d.mts +61 -13
- package/dist/config.mjs +267 -65
- package/dist/deps.d.mts +7 -4
- package/dist/deps.mjs +20 -9
- package/dist/doctor.d.mts +3 -2
- package/dist/doctor.mjs +19 -4
- package/dist/explain.d.mts +4 -2
- package/dist/explain.mjs +66 -19
- package/dist/guard-commit.d.mts +7 -2
- package/dist/guard-commit.mjs +58 -21
- package/dist/init.d.mts +4 -2
- package/dist/init.mjs +15 -5
- package/dist/lib/default-branch.d.mts +35 -0
- package/dist/lib/default-branch.mjs +117 -0
- package/dist/lib/refined-check.d.mts +7 -0
- package/dist/lib/refined-check.mjs +76 -0
- package/dist/patch-coverage.d.mts +13 -0
- package/dist/patch-coverage.mjs +73 -0
- package/dist/pr-watch.d.mts +3 -2
- package/dist/pr-watch.mjs +22 -5
- package/dist/pr.mjs +34 -2
- package/dist/session-start.d.mts +23 -13
- package/dist/session-start.mjs +56 -44
- package/dist/site/servers.d.mts +6 -2
- package/dist/site/servers.mjs +14 -9
- package/dist/site.mjs +2 -2
- package/dist/sync.d.mts +8 -2
- package/dist/sync.mjs +40 -6
- package/dist/ticket.mjs +19 -1
- package/docs/builds.md +8 -8
- package/docs/cli.md +82 -45
- package/docs/configuration.md +455 -139
- package/docs/design.md +17 -4
- package/docs/developing.md +37 -6
- package/docs/existing-repo.md +8 -6
- package/docs/github/by-hand.md +23 -10
- package/docs/github/reference.md +19 -14
- package/docs/github/setup.md +12 -9
- package/docs/glossary.md +13 -3
- package/docs/limitations.md +27 -2
- package/docs/plugins.md +302 -48
- package/docs/quick-start.md +36 -8
- package/docs/removing.md +1 -1
- package/docs/skills.md +101 -52
- package/docs/updating.md +148 -3
- package/docs/workflow.md +13 -10
- package/package.json +1 -1
- package/review.md +20 -11
- package/rules.md +22 -18
- package/settings.schema.json +289 -69
- package/skills/factory-address-review/SKILL.md +50 -30
- package/skills/factory-build/SKILL.md +75 -22
- package/skills/factory-deps/SKILL.md +46 -21
- package/skills/factory-design/SKILL.md +17 -8
- package/skills/factory-diagnose/SKILL.md +22 -20
- package/skills/factory-mutate/SKILL.md +38 -24
- package/skills/factory-refine/SKILL.md +55 -31
- package/skills/factory-resolve-conflicts/SKILL.md +76 -34
- package/skills/factory-trace/SKILL.md +3 -2
- package/workflows/factory-build.yml +1 -1
- package/workflows/factory-conflicts.yml +8 -8
- package/workflows/factory-deps.yml +1 -1
- package/workflows/factory-review.yml +1 -1
- package/skills/factory-address-review/patch-coverage.py +0 -68
package/dist/sync.mjs
CHANGED
|
@@ -7,13 +7,16 @@
|
|
|
7
7
|
// factory sync # write what differs
|
|
8
8
|
// factory sync --check # write nothing; exit 1 naming what differs
|
|
9
9
|
//
|
|
10
|
-
// A copy is the source, byte for byte
|
|
11
|
-
//
|
|
10
|
+
// A copy is the source, byte for byte but for what the settings and the
|
|
11
|
+
// repository decide: the minutes a session may run, the poller's schedule,
|
|
12
|
+
// the rules' numbers, and the default branch's name in the push triggers.
|
|
13
|
+
// Edit the source in the package, never the copy. A file the lock lists that the package no longer has is
|
|
12
14
|
// deleted. Nothing else is.
|
|
13
15
|
import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from "node:fs";
|
|
14
16
|
import { dirname, join, relative, sep } from "node:path";
|
|
15
17
|
import { fileURLToPath } from "node:url";
|
|
16
18
|
import { defaultDeps, loadSettings, repoRoot, RULE_NUMBERS, } from "./config.mjs";
|
|
19
|
+
import { branchDeps, CANNOT_TELL, defaultBranch, } from "./lib/default-branch.mjs";
|
|
17
20
|
/** The package's own folder: the parent of `src/`, or of `dist/` once
|
|
18
21
|
* compiled. */
|
|
19
22
|
export const PACKAGE = dirname(dirname(fileURLToPath(import.meta.url)));
|
|
@@ -30,6 +33,7 @@ const DEPENDABOT = ".github/dependabot.yml";
|
|
|
30
33
|
const NEEDS = {
|
|
31
34
|
"skills/factory-design": (s) => s.site !== null,
|
|
32
35
|
"agents/factory-ui-reviewer.md": (s) => s.site !== null,
|
|
36
|
+
"agents/factory-e2e-reviewer.md": (s) => s.commands.endToEnd !== null,
|
|
33
37
|
"skills/factory-deps": (_, has) => has(DEPENDABOT),
|
|
34
38
|
"workflows/factory-deps.yml": (_, has) => has(DEPENDABOT),
|
|
35
39
|
"workflows/factory-deps-auto-merge.yml": (_, has) => has(DEPENDABOT),
|
|
@@ -48,6 +52,24 @@ export function withSchedule(text, minutes, file) {
|
|
|
48
52
|
const cron = minutes === 60 ? "0 * * * *" : `*/${minutes} * * * *`;
|
|
49
53
|
return text.replace(pattern, (_, lead) => `${lead}"${cron}"`);
|
|
50
54
|
}
|
|
55
|
+
/** The workflows whose push trigger names the default branch. A workflow
|
|
56
|
+
* cannot ask for it in a trigger, so the sync writes it there. */
|
|
57
|
+
const PUSH_WORKFLOWS = [
|
|
58
|
+
"workflows/factory-check.yml",
|
|
59
|
+
"workflows/factory-conflicts.yml",
|
|
60
|
+
];
|
|
61
|
+
/** A workflow with the one `branches:` line of its push trigger naming the
|
|
62
|
+
* default branch and nothing else. */
|
|
63
|
+
export function withDefaultBranch(text, name, file) {
|
|
64
|
+
const pattern = /^(\s+branches: )\[[^\]\n]*\]$/gm;
|
|
65
|
+
if ((text.match(pattern) ?? []).length !== 1)
|
|
66
|
+
throw new Error(`${file}: expected one branches line, to set the push trigger's branch`);
|
|
67
|
+
// Plain where YAML reads the name as text, quoted otherwise.
|
|
68
|
+
const written = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(name)
|
|
69
|
+
? name
|
|
70
|
+
: JSON.stringify(name);
|
|
71
|
+
return text.replace(pattern, (_, lead) => `${lead}[${written}]`);
|
|
72
|
+
}
|
|
51
73
|
/** The workflows that run a Claude session, by the kind of session each
|
|
52
74
|
* runs. */
|
|
53
75
|
const SESSION_WORKFLOWS = {
|
|
@@ -344,14 +366,18 @@ export function lockedFiles(text) {
|
|
|
344
366
|
.map((l) => /^ {2}- (.+)$/.exec(l)?.[1])
|
|
345
367
|
.filter((f) => Boolean(f));
|
|
346
368
|
}
|
|
347
|
-
/** What a sync of `root` from `pkg` writes and deletes
|
|
348
|
-
|
|
369
|
+
/** What a sync of `root` from `pkg` writes and deletes, in a repository
|
|
370
|
+
* whose default branch is `branch`. */
|
|
371
|
+
export function plan(pkg, root, s, branch) {
|
|
349
372
|
const manifest = JSON.parse(readFileSync(join(pkg, "package.json"), "utf8"));
|
|
350
373
|
const read = (p) => existsSync(join(root, p)) ? readFileSync(join(root, p), "utf8") : null;
|
|
351
374
|
const write = new Map();
|
|
352
375
|
const has = (p) => existsSync(join(root, p));
|
|
353
376
|
for (const [from, to] of copies(pkg, s, has)) {
|
|
354
|
-
const
|
|
377
|
+
const source = readFileSync(join(pkg, from), "utf8");
|
|
378
|
+
const text = PUSH_WORKFLOWS.includes(from)
|
|
379
|
+
? withDefaultBranch(source, branch, from)
|
|
380
|
+
: source;
|
|
355
381
|
const kind = SESSION_WORKFLOWS[from.replace(/^workflows\//, "")];
|
|
356
382
|
write.set(to, kind && from.startsWith("workflows/")
|
|
357
383
|
? withMinutes(text, s.sessionMinutes[kind], from)
|
|
@@ -387,7 +413,14 @@ export async function main(argv, d) {
|
|
|
387
413
|
d.err(e instanceof Error ? e.message : String(e));
|
|
388
414
|
return 1;
|
|
389
415
|
}
|
|
390
|
-
|
|
416
|
+
// Nothing is written with a guessed name: a push trigger that names the
|
|
417
|
+
// wrong branch never runs.
|
|
418
|
+
const branch = await d.defaultBranch();
|
|
419
|
+
if (branch === null) {
|
|
420
|
+
d.err(CANNOT_TELL);
|
|
421
|
+
return 1;
|
|
422
|
+
}
|
|
423
|
+
const p = plan(d.pkg, d.root, s, branch);
|
|
391
424
|
const differ = differences(d.root, p);
|
|
392
425
|
if (check) {
|
|
393
426
|
if (differ.length === 0)
|
|
@@ -419,6 +452,7 @@ export async function run(argv) {
|
|
|
419
452
|
root,
|
|
420
453
|
pkg: PACKAGE,
|
|
421
454
|
settings: () => loadSettings(defaultDeps(root)),
|
|
455
|
+
defaultBranch: () => defaultBranch(branchDeps(root)),
|
|
422
456
|
out: (line) => console.log(line),
|
|
423
457
|
err: (line) => console.error(line),
|
|
424
458
|
});
|
package/dist/ticket.mjs
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
// npx --no-install factory ticket stop N "one-line reason"
|
|
9
9
|
// npx --no-install factory ticket end N
|
|
10
10
|
// npx --no-install factory ticket refining|waiting N
|
|
11
|
-
// npx --no-install factory ticket refined N [--before-file FILE]
|
|
11
|
+
// npx --no-install factory ticket refined N [--check] [--before-file FILE]
|
|
12
12
|
// npx --no-install factory follow-up FILE "what is wrong"
|
|
13
13
|
// npx --no-install factory ticket ready N
|
|
14
14
|
// npx --no-install factory ticket cost N
|
|
@@ -36,6 +36,11 @@
|
|
|
36
36
|
// or pull request N. The clock is keyed by CLAUDE_CODE_SESSION_ID, the ID the
|
|
37
37
|
// hooks receive and the transcript's file name.
|
|
38
38
|
//
|
|
39
|
+
// `refined` posts its marker only on a ticket whose body a build can read
|
|
40
|
+
// (`lib/refined-check.mts`): otherwise it prints one line for each part that
|
|
41
|
+
// is missing and exits 1. With `--check` it posts nothing, and prints
|
|
42
|
+
// `sound` when nothing is missing.
|
|
43
|
+
//
|
|
39
44
|
// `ready` moves issue N's card to Ready when the owner asks a session to, so
|
|
40
45
|
// the sync and the poller treat it as the owner's own move. It is the one
|
|
41
46
|
// write to Status outside the sync, and needs the project scope:
|
|
@@ -55,6 +60,7 @@ import { openCodeHost } from "./code-host/index.mjs";
|
|
|
55
60
|
import { openRunner } from "./runner/index.mjs";
|
|
56
61
|
import { loadSettings, targetOf } from "./config.mjs";
|
|
57
62
|
import { commentBody, sameName, reviewingPulls, workState, } from "./lib/work-status.mjs";
|
|
63
|
+
import { missingParts } from "./lib/refined-check.mjs";
|
|
58
64
|
import { commonDir, readClock, writeClock } from "./lib/clock.mjs";
|
|
59
65
|
import { costNote, measureSession, projectsDir } from "./lib/usage.mjs";
|
|
60
66
|
import { boardConfigOf, checkFields } from "./board.mjs";
|
|
@@ -509,6 +515,18 @@ export async function main(argv, deps) {
|
|
|
509
515
|
await post(d, issue, { kind: "cost", cost: takeCost(issue, d) });
|
|
510
516
|
break;
|
|
511
517
|
case "refined": {
|
|
518
|
+
// A body the build could not read gets no marker, whoever wrote it.
|
|
519
|
+
const ticket = await d.tickets.read(issue);
|
|
520
|
+
const missing = missingParts(ticket.body, ticket.labels);
|
|
521
|
+
if (missing.length > 0) {
|
|
522
|
+
for (const line of missing)
|
|
523
|
+
console.error(line);
|
|
524
|
+
return 1;
|
|
525
|
+
}
|
|
526
|
+
if (rest.includes("--check")) {
|
|
527
|
+
d.out("sound");
|
|
528
|
+
return 0;
|
|
529
|
+
}
|
|
512
530
|
const at = rest.indexOf("--before-file");
|
|
513
531
|
const before = at === -1 ? undefined : d.readFile(rest[at + 1]);
|
|
514
532
|
await post(d, issue, {
|
package/docs/builds.md
CHANGED
|
@@ -72,8 +72,8 @@ the account the build acts as. Without one, its commits are unsigned.
|
|
|
72
72
|
commits is not shown as verified, when your own git signs commits.
|
|
73
73
|
|
|
74
74
|
**Before the session starts,** the commands under
|
|
75
|
-
[`build-setup`](configuration.md#
|
|
76
|
-
your npm dependencies are installed.
|
|
75
|
+
[`commands.build-setup`](configuration.md#commandsbuild-setup) in your
|
|
76
|
+
settings run, after your npm dependencies are installed.
|
|
77
77
|
|
|
78
78
|
## The other jobs that run in the cloud
|
|
79
79
|
|
|
@@ -82,11 +82,11 @@ anything to do and starts a session only when there is, so a run with
|
|
|
82
82
|
nothing to do costs about a minute of the runner and no use of the agent. A
|
|
83
83
|
run that works costs about what a build does.
|
|
84
84
|
|
|
85
|
-
| Job | Starts on
|
|
86
|
-
| ------------------------ |
|
|
87
|
-
| Answering your review | A review you submit on a pull request
|
|
88
|
-
| The conflict sweep | A push to your
|
|
89
|
-
| Dependency pull requests | Three times a day, or by hand
|
|
85
|
+
| Job | Starts on | What the session does |
|
|
86
|
+
| ------------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
87
|
+
| Answering your review | A review you submit on a pull request | Works your comments with `factory-address-review` |
|
|
88
|
+
| The conflict sweep | A push to your default branch, nightly, or by hand | Merges your default branch into each pull request that conflicts with it, with `factory-resolve-conflicts` |
|
|
89
|
+
| Dependency pull requests | Three times a day, or by hand | Moves each dependency update toward merged, with `factory-deps`, in a repository with a `.github/dependabot.yml` |
|
|
90
90
|
|
|
91
91
|
Each acts as the same account a build does. The review job answers your
|
|
92
92
|
reviews only: the factory's own replies start runs that find nothing of
|
|
@@ -101,7 +101,7 @@ each ticket in Ready with no open blocker it:
|
|
|
101
101
|
|
|
102
102
|
1. posts a comment on the ticket saying a build is starting, carrying a
|
|
103
103
|
marker;
|
|
104
|
-
2. starts a build of that ticket in the cloud, from your
|
|
104
|
+
2. starts a build of that ticket in the cloud, from your default branch.
|
|
105
105
|
|
|
106
106
|
```bash
|
|
107
107
|
factory poller
|
package/docs/cli.md
CHANGED
|
@@ -55,11 +55,15 @@ read is set.
|
|
|
55
55
|
| ------------------------ | ----------------------------------------------------------------- | ----- |
|
|
56
56
|
| `factory config get KEY` | To print one setting in effect, such as `tickets.board` | Built |
|
|
57
57
|
| `factory config explain` | To see every setting in effect, defaults included | Built |
|
|
58
|
-
| `factory plugins` | To see
|
|
58
|
+
| `factory plugins` | To see the plug-ins the factory will use, by slot | Built |
|
|
59
59
|
| `factory site compare` | To picture a website's pages before and after a change. See below | Built |
|
|
60
60
|
| `factory site stop` | To end the sites `compare --keep` left running | Built |
|
|
61
61
|
| `factory remove` | To take the factory out of a repository | Built |
|
|
62
62
|
|
|
63
|
+
`factory plugins` prints one line for each plug-in, the factory's own
|
|
64
|
+
included: its kind, its name, its [slot](plugins.md#the-slots), then its
|
|
65
|
+
files or labels. `factory plugins SLOT` prints one slot's lines.
|
|
66
|
+
|
|
63
67
|
A new version is installed with npm and applied with `factory sync`, as
|
|
64
68
|
[Updating](updating.md) says. [Removing](removing.md) says what `remove`
|
|
65
69
|
deletes and what it leaves to you.
|
|
@@ -102,42 +106,48 @@ ticket system would swallow, name it, and post nothing.
|
|
|
102
106
|
| `factory ticket end N` | A run's last step: releases this session's claim if no open pull request links N. Prints `released`, `kept`, or `not live` |
|
|
103
107
|
| `factory ticket refining N` | Marks N as being refined |
|
|
104
108
|
| `factory ticket waiting N` | Marks N as waiting on your reply to a round of questions |
|
|
105
|
-
| `factory ticket refined N` | Marks N as refined
|
|
109
|
+
| `factory ticket refined N` | Marks N as refined, unless its body lacks what a build reads. `--check` makes that check alone and posts nothing |
|
|
106
110
|
| `factory ticket ready N` | Moves N to Ready. Only when you ask a session to |
|
|
107
111
|
| `factory ticket cost N` | Notes what this session spent on N since it started |
|
|
108
112
|
| `factory follow-up FILE "what is wrong"` | Adds a line about that file to the follow-ups ticket, opening the ticket if none is open |
|
|
109
113
|
|
|
114
|
+
`factory ticket refined N` posts nothing and exits 1 when N's body lacks a
|
|
115
|
+
section a build reads, printing one line for each, such as
|
|
116
|
+
`missing: ## Acceptance criteria`. With `--check` it prints `sound` for a
|
|
117
|
+
body that passes. [Plug-ins](plugins.md#refiner) lists the sections.
|
|
118
|
+
|
|
110
119
|
### Pull requests
|
|
111
120
|
|
|
112
121
|
Pull requests stay on the code host whatever the ticket system. A pull
|
|
113
122
|
request's conversation comments and labels go through these, never the
|
|
114
123
|
ticket system.
|
|
115
124
|
|
|
116
|
-
| Command | What it does
|
|
117
|
-
| ------------------------------------------------ |
|
|
118
|
-
| `factory pr state [N]` | What stands between N and a merge: checks, review, threads, conflict
|
|
119
|
-
| `factory pr threads N` | The unresolved review threads, each with its comments. `--all` lists the resolved ones too
|
|
120
|
-
| `factory pr reply N COMMENT --body-file FILE` | Replies on a thread
|
|
121
|
-
| `factory pr resolve N COMMENT` | Resolves a thread
|
|
122
|
-
| `factory pr closes N` | The tickets N closes
|
|
123
|
-
| `factory pr wait-checks N` | Waits for every CI run on the pushed commit. Prints `success`, `failure:` with the failed checks, or `no checks`
|
|
124
|
-
| `factory pr ready N` | Marks a draft ready for review. When `commit.gpgsign` is `true`, refuses while the code host shows a commit as not verified
|
|
125
|
-
| `factory pr comments N` | N's conversation comments: ID, author, time, and first line. `--author LOGIN`, `--contains TEXT`, and `--json`, which prints each comment's `id`, `user.login`, `body`, and `created_at`
|
|
126
|
-
| `factory pr comment N --body-file FILE` | Posts a conversation comment and prints its ID. Refuses a bare tag-like `<word>`, as `ticket comment` does
|
|
127
|
-
| `factory pr comment-view ID` | Prints one conversation comment's body
|
|
128
|
-
| `factory pr label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off
|
|
129
|
-
| `factory pr watch N` | Waits until N needs attention, says why, and exits
|
|
130
|
-
| `factory pr watch N --release` | Stops watching N
|
|
131
|
-
| `factory pr review-pending N REVIEW` | Exits 0 when the owner's review has something of theirs to answer, and 1, saying why, when it has not
|
|
132
|
-
| `factory pr conflicts` | The pull requests the conflict sweep takes, one number a line; exits 0 when there is one and 1 when none
|
|
133
|
-
| `factory pr open --title TITLE --body-file FILE` | Opens a draft pull request from the current branch into the default branch and prints its number. `--base BRANCH` names another base, and `--ready` opens it ready for review. Fails in the code host's own words when the branch has nothing new or already has one open
|
|
134
|
-
| `factory pr view N --field FIELD` | Prints one field of N: `head` (its last commit, in full), `branch`, `base`, `title`, `body`, `state`, or `mergeable` (`dirty` for a conflict, `unknown` until the code host has worked it out)
|
|
135
|
-
| `factory pr review N REVIEW` | One review as JSON: its author, its body, and each comment it left on a line, with the comment a reply replies to
|
|
136
|
-
| `factory pr unverified N` | Each of N's commits the code host does not show as signed, with the reason. Prints nothing when it shows them all
|
|
137
|
-
| `factory pr
|
|
138
|
-
| `factory pr
|
|
139
|
-
| `factory
|
|
140
|
-
| `factory deps
|
|
125
|
+
| Command | What it does |
|
|
126
|
+
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
127
|
+
| `factory pr state [N]` | What stands between N and a merge: checks, review, threads, conflict |
|
|
128
|
+
| `factory pr threads N` | The unresolved review threads, each with its comments. `--all` lists the resolved ones too |
|
|
129
|
+
| `factory pr reply N COMMENT --body-file FILE` | Replies on a thread |
|
|
130
|
+
| `factory pr resolve N COMMENT` | Resolves a thread |
|
|
131
|
+
| `factory pr closes N` | The tickets N closes |
|
|
132
|
+
| `factory pr wait-checks N` | Waits for every CI run on the pushed commit. Prints `success`, `failure:` with the failed checks, or `no checks` |
|
|
133
|
+
| `factory pr ready N` | Marks a draft ready for review. When `commit.gpgsign` is `true`, refuses while the code host shows a commit as not verified |
|
|
134
|
+
| `factory pr comments N` | N's conversation comments: ID, author, time, and first line. `--author LOGIN`, `--contains TEXT`, and `--json`, which prints each comment's `id`, `user.login`, `body`, and `created_at` |
|
|
135
|
+
| `factory pr comment N --body-file FILE` | Posts a conversation comment and prints its ID. Refuses a bare tag-like `<word>`, as `ticket comment` does |
|
|
136
|
+
| `factory pr comment-view ID` | Prints one conversation comment's body |
|
|
137
|
+
| `factory pr label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off |
|
|
138
|
+
| `factory pr watch N` | Waits until N needs attention, says why, and exits |
|
|
139
|
+
| `factory pr watch N --release` | Stops watching N |
|
|
140
|
+
| `factory pr review-pending N REVIEW` | Exits 0 when the owner's review has something of theirs to answer, and 1, saying why, when it has not |
|
|
141
|
+
| `factory pr conflicts` | The pull requests the conflict sweep takes, one number a line; exits 0 when there is one and 1 when none |
|
|
142
|
+
| `factory pr open --title TITLE --body-file FILE` | Opens a draft pull request from the current branch into the default branch and prints its number. `--base BRANCH` names another base, and `--ready` opens it ready for review. Fails in the code host's own words when the branch has nothing new or already has one open |
|
|
143
|
+
| `factory pr view N --field FIELD` | Prints one field of N: `head` (its last commit, in full), `branch`, `base`, `title`, `body`, `state`, or `mergeable` (`dirty` for a conflict, `unknown` until the code host has worked it out) |
|
|
144
|
+
| `factory pr review N REVIEW` | One review as JSON: its author, its body, and each comment it left on a line, with the comment a reply replies to |
|
|
145
|
+
| `factory pr unverified N` | Each of N's commits the code host does not show as signed, with the reason. Prints nothing when it shows them all |
|
|
146
|
+
| `factory pr uncovered [BASE] [LCOV]` | The lines the branch added or changed that the coverage report shows no test covers, a file at a time: `MISS` for a line no test ran, and `PART` for a line that ran with a branch never taken. `BASE` is what the branch is compared with, and is the default branch on `origin` when left out. `LCOV` is the report, and is `coverage/lcov.info` when left out. Prints nothing when every such line is covered |
|
|
147
|
+
| `factory pr failed N` | For N's last commit, the failures `wait-checks` counts: each failed job's name and the last 200 lines of its log, from the newest run of each workflow started by a push or a pull request, and what a check that did not pass wrote about itself. Prints nothing when nothing failed |
|
|
148
|
+
| `factory pr review-again N` | Asks for a fresh review of N's last commit. Exits 1, saying so, when no review has run on it |
|
|
149
|
+
| `factory deps` | The open dependency pull requests, their checks, and what each needs |
|
|
150
|
+
| `factory deps --any` | Exits 0 when a dependency pull request is open and 1 when none is |
|
|
141
151
|
|
|
142
152
|
`factory pr wait-checks N` waits until the code host
|
|
143
153
|
shows the commit you pushed as N's head, then until the newest run of each
|
|
@@ -146,25 +156,50 @@ the factory's own jobs, so a failed board sync does not stop a pull
|
|
|
146
156
|
request being marked ready. With no run two minutes after the commit became the head, it
|
|
147
157
|
prints `no checks` and exits 0. A failure exits 3.
|
|
148
158
|
|
|
159
|
+
### Your repository's commands
|
|
160
|
+
|
|
161
|
+
Skills call these to check and test a change, so no skill names a test
|
|
162
|
+
runner or a linter: each runs what your settings list under
|
|
163
|
+
[`commands`](configuration.md#commands) and
|
|
164
|
+
[`specs`](configuration.md#specs), with bash, from the repository's root.
|
|
165
|
+
You can run them too.
|
|
166
|
+
|
|
167
|
+
| Command | What it does |
|
|
168
|
+
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
169
|
+
| `factory gate` | Runs each [`commands.gate`](configuration.md#commandsgate) command in order, printing `$` and the command before each. Stops at the first that fails, with `gate failed on:` and the command. Exits 0 when every command passes, and 1 at the first that fails or when no gate is set |
|
|
170
|
+
| `factory test-one FILE [NAME]` | Runs [`commands.test-one`](configuration.md#commandstest-one), one test file alone or the one test NAME in it, and exits with its status |
|
|
171
|
+
| `factory end-to-end FILE [--times K]` | Runs [`commands.end-to-end`](configuration.md#commandsend-to-end), one end-to-end spec alone, and exits with its status. With `--times K`, K times in a row, stopping at the first run that fails |
|
|
172
|
+
| `factory specs check` | Runs [`specs.check`](configuration.md#specscheck), the check of your written specs, and exits with its status. Prints `specs are off` when `specs` is `none` |
|
|
173
|
+
| `factory default-branch` | Prints the name of your repository's default branch, which nothing in the factory assumes is `main` |
|
|
174
|
+
|
|
175
|
+
`factory default-branch` asks, in turn, the event of the workflow run it
|
|
176
|
+
is in, `origin/HEAD` in your checkout, and the code host, whose answer it
|
|
177
|
+
writes to `origin/HEAD` so the next run asks nobody. A checkout with no
|
|
178
|
+
`origin` remote takes git's own `init.defaultBranch`, or `main`. When a
|
|
179
|
+
remote exists and none of the three answers, it exits 1 with
|
|
180
|
+
`Could not tell the default branch. Run: git remote set-head origin --auto`.
|
|
181
|
+
`factory sync` and `factory site compare` stop with the same line, and
|
|
182
|
+
the commit hook blocks a session's git command with it.
|
|
183
|
+
|
|
149
184
|
### Workflows and hooks
|
|
150
185
|
|
|
151
|
-
| Command | Run by | What it does
|
|
152
|
-
| --------------------------- | ------------------------------- |
|
|
153
|
-
| `factory board collect` | The board-sync workflow | Reads the tickets and posts the comments a closed pull request or the nightly run needs
|
|
154
|
-
| `factory board apply` | The board-sync workflow | Sets each ticket's column and fields from its comments
|
|
155
|
-
| `factory board --dry-run` | You, to see what it would set | Reads the tickets and the board, prints what the sync would set, and writes nothing
|
|
156
|
-
| `factory merge-policy N` | The merge-policy workflow | Decides whether N may merge without you, and why
|
|
157
|
-
| `factory review verdict` | The review-verdict workflow | Posts the "Review verdict" status for a commit
|
|
158
|
-
| `factory review cost` | The review workflow | Adds what the CI review cost to its summary
|
|
159
|
-
| `factory review tools` | The review workflow | Prints the tools the CI review may use, from [`ci-review.commands`](configuration.md#ci-review)
|
|
160
|
-
| `factory poller` | Your server | Starts a build for each Ready ticket. See [Builds](builds.md)
|
|
161
|
-
| `factory poller --once` | The scheduled poller's workflow | One pass of the poller, with the board and Ready column from your settings
|
|
162
|
-
| `factory guard` | A hook, before each command | Runs both guards below on one Bash call
|
|
163
|
-
| `factory guard commit` | Within `factory guard` | Blocks a commit on your
|
|
164
|
-
| `factory guard ticket-text` | Within `factory guard` | Refuses ticket text with a bare `<tag>`, which the ticket system would swallow
|
|
165
|
-
| `factory reviewers start` | A hook, when an agent starts | Records a reviewer's run on the ticket, for its cost
|
|
166
|
-
| `factory reviewers stop` | A hook, when an agent stops | The same
|
|
167
|
-
| `factory session-start` | A hook, when a session starts | Shows unfinished branches and each ticket's state
|
|
186
|
+
| Command | Run by | What it does | State |
|
|
187
|
+
| --------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
|
|
188
|
+
| `factory board collect` | The board-sync workflow | Reads the tickets and posts the comments a closed pull request or the nightly run needs | Built |
|
|
189
|
+
| `factory board apply` | The board-sync workflow | Sets each ticket's column and fields from its comments | Built |
|
|
190
|
+
| `factory board --dry-run` | You, to see what it would set | Reads the tickets and the board, prints what the sync would set, and writes nothing | Built |
|
|
191
|
+
| `factory merge-policy N` | The merge-policy workflow | Decides whether N may merge without you, and why | Built |
|
|
192
|
+
| `factory review verdict` | The review-verdict workflow | Posts the "Review verdict" status for a commit | Built |
|
|
193
|
+
| `factory review cost` | The review workflow | Adds what the CI review cost to its summary | Built |
|
|
194
|
+
| `factory review tools` | The review workflow | Prints the tools the CI review may use, from [`ci-review.commands`](configuration.md#ci-review) | Built |
|
|
195
|
+
| `factory poller` | Your server | Starts a build for each Ready ticket. See [Builds](builds.md) | Built |
|
|
196
|
+
| `factory poller --once` | The scheduled poller's workflow | One pass of the poller, with the board and Ready column from your settings | Built |
|
|
197
|
+
| `factory guard` | A hook, before each command | Runs both guards below on one Bash call | Built |
|
|
198
|
+
| `factory guard commit` | Within `factory guard` | Blocks a commit on your default branch, a push to it, a force push, or a commit while a [`commands.before-commit`](configuration.md#commandsbefore-commit) command fails | Built |
|
|
199
|
+
| `factory guard ticket-text` | Within `factory guard` | Refuses ticket text with a bare `<tag>`, which the ticket system would swallow | Built |
|
|
200
|
+
| `factory reviewers start` | A hook, when an agent starts | Records a reviewer's run on the ticket, for its cost | Built |
|
|
201
|
+
| `factory reviewers stop` | A hook, when an agent stops | The same | Built |
|
|
202
|
+
| `factory session-start` | A hook, when a session starts | Shows unfinished branches and each ticket's state | Built |
|
|
168
203
|
|
|
169
204
|
The board sync runs `collect` and `apply` as two steps, so the board's
|
|
170
205
|
token reaches only the second. The board's number comes from
|
|
@@ -174,7 +209,9 @@ token reaches only the second. The board's number comes from
|
|
|
174
209
|
|
|
175
210
|
- `0`: done, or the answer is the line printed.
|
|
176
211
|
- `2`: no such command; the usage is printed. A guard also exits 2 when it
|
|
177
|
-
blocks a call
|
|
212
|
+
blocks a call, and so does one of
|
|
213
|
+
[your repository's commands](#your-repositorys-commands) given an
|
|
214
|
+
argument it does not know.
|
|
178
215
|
- `3`: `pr wait-checks` saw a check fail.
|
|
179
216
|
- Any other non-zero: it could not do it, and the reason is on standard
|
|
180
217
|
error. A command that could not reach the code host or the ticket system
|