@davidbyoung/software-factory 0.1.9 → 0.1.11
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/agents/factory-ticket-readiness.md +20 -15
- package/dist/board.d.mts +1 -1
- package/dist/board.mjs +4 -7
- package/dist/cli.mjs +23 -1
- package/dist/code-host/github.d.mts +1 -1
- package/dist/code-host/github.mjs +31 -2
- package/dist/code-host/types.d.mts +20 -1
- package/dist/code-host/types.mjs +8 -0
- package/dist/columns-suggest.d.mts +25 -5
- package/dist/columns-suggest.mjs +117 -21
- package/dist/commands.d.mts +8 -2
- package/dist/commands.mjs +92 -8
- package/dist/config.d.mts +19 -7
- package/dist/config.mjs +109 -30
- package/dist/doctor.mjs +1 -2
- package/dist/explain.mjs +7 -1
- package/dist/init.d.mts +19 -0
- package/dist/init.mjs +139 -23
- package/dist/lib/gh.d.mts +6 -0
- package/dist/lib/gh.mjs +11 -1
- package/dist/lib/listed.d.mts +3 -2
- package/dist/lib/listed.mjs +5 -4
- package/dist/lib/work-status.d.mts +5 -5
- package/dist/lib/work-status.mjs +7 -8
- package/dist/merge-policy.mjs +7 -3
- package/dist/poller.d.mts +1 -1
- package/dist/poller.mjs +9 -6
- package/dist/pr.d.mts +8 -6
- package/dist/pr.mjs +47 -22
- package/dist/review-verdict.d.mts +22 -4
- package/dist/review-verdict.mjs +55 -17
- package/dist/specs/index.d.mts +6 -0
- package/dist/specs/index.mjs +15 -0
- package/dist/specs/openspec.d.mts +2 -0
- package/dist/specs/openspec.mjs +78 -0
- package/dist/specs/types.d.mts +53 -0
- package/dist/specs/types.mjs +4 -0
- package/dist/ticket.d.mts +6 -1
- package/dist/ticket.mjs +62 -3
- package/dist/tickets/github-access.d.mts +5 -0
- package/dist/tickets/github-access.mjs +22 -0
- package/dist/tickets/github.mjs +2 -0
- package/dist/tickets/types.d.mts +4 -0
- package/dist/tool-names.d.mts +2 -0
- package/dist/tool-names.mjs +3 -0
- package/dist/tools.d.mts +2 -0
- package/dist/tools.mjs +3 -0
- package/docs/builds.md +30 -14
- package/docs/cli.md +48 -30
- package/docs/configuration.md +237 -73
- package/docs/developing.md +104 -59
- package/docs/existing-repo.md +51 -29
- package/docs/github/by-hand.md +13 -1
- package/docs/github/setup.md +26 -2
- package/docs/glossary.md +7 -6
- package/docs/limitations.md +8 -5
- package/docs/presets.md +15 -3
- package/docs/updating.md +147 -2
- package/docs/workflow.md +26 -9
- package/package.json +1 -1
- package/rules.md +36 -30
- package/settings.schema.json +14 -9
- package/skills/factory-address-review/SKILL.md +40 -39
- package/skills/factory-build/SKILL.md +77 -52
- package/skills/factory-deps/SKILL.md +6 -4
- package/skills/factory-refine/SKILL.md +30 -22
- package/skills/factory-resolve-conflicts/SKILL.md +8 -7
package/dist/ticket.mjs
CHANGED
|
@@ -17,6 +17,7 @@
|
|
|
17
17
|
// (`tickets/`), so no skill calls a ticket system itself:
|
|
18
18
|
//
|
|
19
19
|
// factory ticket view N [--field title|state|labels|body] [--json]
|
|
20
|
+
// factory ticket answers N # the comments that count as answers
|
|
20
21
|
// factory ticket list [--label LABEL] [--title "TITLE"] [--json]
|
|
21
22
|
// factory ticket edit N [--title TITLE] [--body-file FILE [--attach FILE]...]
|
|
22
23
|
// factory ticket comment N --body-file FILE [--attach FILE]...
|
|
@@ -59,7 +60,7 @@ import { sessionIdentity } from "./lib/gh.mjs";
|
|
|
59
60
|
import { openCodeHost } from "./code-host/index.mjs";
|
|
60
61
|
import { openRunner } from "./runner/index.mjs";
|
|
61
62
|
import { loadSettings, targetOf } from "./config.mjs";
|
|
62
|
-
import { commentBody, sameName, reviewingPulls, workState, } from "./lib/work-status.mjs";
|
|
63
|
+
import { AGENT_MARK, commentBody, sameName, reviewingPulls, workState, } from "./lib/work-status.mjs";
|
|
63
64
|
import { missingParts } from "./lib/refined-check.mjs";
|
|
64
65
|
import { commonDir, readClock, writeClock } from "./lib/clock.mjs";
|
|
65
66
|
import { costNote, measureSession, projectsDir } from "./lib/usage.mjs";
|
|
@@ -67,6 +68,7 @@ import { boardConfigOf, checkFields } from "./board.mjs";
|
|
|
67
68
|
import { refuseBareTags, refuseOverride } from "./guard-ticket-text.mjs";
|
|
68
69
|
import { openTickets } from "./tickets/index.mjs";
|
|
69
70
|
import { GROUPS, need, supports, } from "./tickets/types.mjs";
|
|
71
|
+
import { NotSignedInError } from "./code-host/types.mjs";
|
|
70
72
|
export async function readComments(c, issue) {
|
|
71
73
|
return (await c.tickets.read(issue)).comments;
|
|
72
74
|
}
|
|
@@ -280,23 +282,60 @@ export function formatTicket(t) {
|
|
|
280
282
|
t.body.trimEnd() || "(no body)",
|
|
281
283
|
];
|
|
282
284
|
for (const c of t.comments)
|
|
283
|
-
lines.push("",
|
|
285
|
+
lines.push("", ...formatComment(c));
|
|
284
286
|
return lines;
|
|
285
287
|
}
|
|
288
|
+
/** One comment as `view` prints it: a line naming it, then its body. */
|
|
289
|
+
export function formatComment(c) {
|
|
290
|
+
return [
|
|
291
|
+
`--- comment ${c.id} by ${c.author} at ${c.createdAt}`,
|
|
292
|
+
c.body.trimEnd(),
|
|
293
|
+
];
|
|
294
|
+
}
|
|
295
|
+
/** The comments on a ticket that count as answers: by someone the ticket
|
|
296
|
+
* system says may decide, without the agent mark, oldest first. Asks once
|
|
297
|
+
* for each distinct author. */
|
|
298
|
+
async function answersOf(t, ticket) {
|
|
299
|
+
const unmarked = ticket.comments.filter((c) => !c.body.includes(AGENT_MARK));
|
|
300
|
+
const authors = [...new Set(unmarked.map((c) => c.author))];
|
|
301
|
+
const may = await Promise.all(authors.map((a) => t.mayDecide(a)));
|
|
302
|
+
const deciders = new Set(authors.filter((_, i) => may[i]));
|
|
303
|
+
return unmarked
|
|
304
|
+
.filter((c) => deciders.has(c.author))
|
|
305
|
+
.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
|
|
306
|
+
}
|
|
286
307
|
const FIELDS = ["title", "state", "labels", "body"];
|
|
287
308
|
const READS_AND_WRITES = new Set([
|
|
288
309
|
"view",
|
|
310
|
+
"answers",
|
|
289
311
|
"list",
|
|
290
312
|
"edit",
|
|
291
313
|
"comment",
|
|
292
314
|
"open",
|
|
293
315
|
"label",
|
|
294
316
|
"link",
|
|
317
|
+
"branch",
|
|
295
318
|
"blockers",
|
|
296
319
|
"block",
|
|
297
320
|
"unblock",
|
|
298
321
|
"supports",
|
|
299
322
|
]);
|
|
323
|
+
/** The branch a build of `ticket` pushes, from `code-host.branch-name`. */
|
|
324
|
+
async function branchOf(ticket, d) {
|
|
325
|
+
let user = "";
|
|
326
|
+
if (d.branchName.includes("{user}"))
|
|
327
|
+
try {
|
|
328
|
+
user = await d.signedInAs(d.repository, d.codeHost);
|
|
329
|
+
}
|
|
330
|
+
catch (e) {
|
|
331
|
+
if (!(e instanceof NotSignedInError))
|
|
332
|
+
throw e;
|
|
333
|
+
throw new Error("code-host.branch-name uses {user}, and gh is not signed in: run gh auth login", { cause: e });
|
|
334
|
+
}
|
|
335
|
+
return d.branchName
|
|
336
|
+
.replaceAll("{ticket}", String(ticket))
|
|
337
|
+
.replaceAll("{user}", user);
|
|
338
|
+
}
|
|
300
339
|
/** The commands that read or write a ticket for a skill. Null when
|
|
301
340
|
* `command` is not one of them. */
|
|
302
341
|
async function ticketCommand(command, args, d) {
|
|
@@ -324,6 +363,18 @@ async function ticketCommand(command, args, d) {
|
|
|
324
363
|
d.out(String(ticket[field]));
|
|
325
364
|
return 0;
|
|
326
365
|
}
|
|
366
|
+
case "answers": {
|
|
367
|
+
const ticket = await t.read(numbered());
|
|
368
|
+
const answers = await answersOf(t, ticket);
|
|
369
|
+
if (answers.length === 0)
|
|
370
|
+
d.out(`#${ticket.number} has no answers from an approver yet.`);
|
|
371
|
+
answers.forEach((c, i) => {
|
|
372
|
+
if (i > 0)
|
|
373
|
+
d.out("");
|
|
374
|
+
formatComment(c).forEach(d.out);
|
|
375
|
+
});
|
|
376
|
+
return 0;
|
|
377
|
+
}
|
|
327
378
|
case "list": {
|
|
328
379
|
const label = option(args, "--label");
|
|
329
380
|
const title = option(args, "--title");
|
|
@@ -413,6 +464,11 @@ async function ticketCommand(command, args, d) {
|
|
|
413
464
|
case "link":
|
|
414
465
|
d.out(t.linkText(numbered()));
|
|
415
466
|
return 0;
|
|
467
|
+
case "branch": {
|
|
468
|
+
const ticket = await t.read(numbered());
|
|
469
|
+
d.out(await branchOf(ticket.number, d));
|
|
470
|
+
return 0;
|
|
471
|
+
}
|
|
416
472
|
case "blockers": {
|
|
417
473
|
const list = await need(t, "blockers").list(numbered());
|
|
418
474
|
for (const b of list)
|
|
@@ -437,7 +493,7 @@ async function ticketCommand(command, args, d) {
|
|
|
437
493
|
return null;
|
|
438
494
|
}
|
|
439
495
|
}
|
|
440
|
-
const USAGE = "Usage: npx --no-install factory ticket claim|still-live|stop|end|refining|waiting|refined|ready|cost|view|list|edit|comment|open|label|link|blockers|block|unblock|supports|follow-up ...";
|
|
496
|
+
const USAGE = "Usage: npx --no-install factory ticket claim|still-live|stop|end|refining|waiting|refined|ready|cost|view|answers|list|edit|comment|open|label|link|branch|blockers|block|unblock|supports|follow-up ...";
|
|
441
497
|
export async function main(argv, deps) {
|
|
442
498
|
const [command, first, ...rest] = argv;
|
|
443
499
|
const issue = Number(first);
|
|
@@ -450,6 +506,8 @@ export async function main(argv, deps) {
|
|
|
450
506
|
...deps,
|
|
451
507
|
config: boardConfigOf(settings),
|
|
452
508
|
codeHost: settings.codeHost.type,
|
|
509
|
+
// Null only when init reads the settings to ask for it.
|
|
510
|
+
branchName: settings.codeHost.branchName,
|
|
453
511
|
repository,
|
|
454
512
|
board,
|
|
455
513
|
...opened,
|
|
@@ -561,6 +619,7 @@ export async function run(argv) {
|
|
|
561
619
|
return main(argv, {
|
|
562
620
|
open: (settings, target) => openTickets(settings, target),
|
|
563
621
|
openPulls: (repository, codeHost) => openCodeHost(repository, codeHost).open(),
|
|
622
|
+
signedInAs: (repository, codeHost) => openCodeHost(repository, codeHost).signedInAs(),
|
|
564
623
|
runner: (repository, name) => openRunner(repository, name),
|
|
565
624
|
settings: () => loadSettings(),
|
|
566
625
|
env: process.env,
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import { type Transport } from "./transport.mts";
|
|
2
|
+
/** Whether `login` can write to `repository` (owner/name), counting every
|
|
3
|
+
* grant: repository, team, organization, and enterprise. Rejects when
|
|
4
|
+
* GitHub cannot say, so a failed lookup is never read as "yes". */
|
|
5
|
+
export declare function writeAccess(t: Transport, repository: string, login: string): Promise<boolean>;
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
// Whether an account can write to a GitHub repository: the one lookup both
|
|
2
|
+
// GitHub adapters ask when they decide whose words count as instructions.
|
|
3
|
+
import { statusOf } from "./transport.mjs";
|
|
4
|
+
/** Whether `login` can write to `repository` (owner/name), counting every
|
|
5
|
+
* grant: repository, team, organization, and enterprise. Rejects when
|
|
6
|
+
* GitHub cannot say, so a failed lookup is never read as "yes". */
|
|
7
|
+
export async function writeAccess(t, repository, login) {
|
|
8
|
+
const API = `repos/${repository}`;
|
|
9
|
+
try {
|
|
10
|
+
const answer = await t.rest("GET", `${API}/collaborators/${encodeURIComponent(login)}/permission`);
|
|
11
|
+
return answer.permission === "admin" || answer.permission === "write";
|
|
12
|
+
}
|
|
13
|
+
catch (error) {
|
|
14
|
+
if (statusOf(error) !== 404)
|
|
15
|
+
throw error;
|
|
16
|
+
// A token that cannot see a private repository gets a 404 for every
|
|
17
|
+
// name, so a 404 means "no such account" only when the repository can
|
|
18
|
+
// be read.
|
|
19
|
+
await t.rest("GET", API);
|
|
20
|
+
return false;
|
|
21
|
+
}
|
|
22
|
+
}
|
package/dist/tickets/github.mjs
CHANGED
|
@@ -7,6 +7,7 @@ import { rmSync, writeFileSync } from "node:fs";
|
|
|
7
7
|
import { tmpdir } from "node:os";
|
|
8
8
|
import { dirname, join } from "node:path";
|
|
9
9
|
import { NotFoundError, } from "./types.mjs";
|
|
10
|
+
import { writeAccess } from "./github-access.mjs";
|
|
10
11
|
import { statusOf } from "./transport.mjs";
|
|
11
12
|
import { sameName } from "../lib/work-status.mjs";
|
|
12
13
|
const toComment = (raw) => ({
|
|
@@ -346,6 +347,7 @@ export function githubTickets(o) {
|
|
|
346
347
|
await issue(n);
|
|
347
348
|
}
|
|
348
349
|
},
|
|
350
|
+
mayDecide: (author) => writeAccess(t, o.repository, author),
|
|
349
351
|
linkText: (n) => `Closes #${n}`,
|
|
350
352
|
address: (n) => `https://github.com/${o.repository}/issues/${n}`,
|
|
351
353
|
board: {
|
package/dist/tickets/types.d.mts
CHANGED
|
@@ -178,6 +178,10 @@ export type Tickets = {
|
|
|
178
178
|
open(ticket: NewTicket): Promise<number>;
|
|
179
179
|
addLabel(ticket: number, label: string): Promise<void>;
|
|
180
180
|
removeLabel(ticket: number, label: string): Promise<void>;
|
|
181
|
+
/** Whether a comment by `author` may decide on a ticket: an answer to a
|
|
182
|
+
* question, taken as an instruction. Rejects when the system cannot
|
|
183
|
+
* say. */
|
|
184
|
+
mayDecide(author: string): Promise<boolean>;
|
|
181
185
|
/** What makes a merged pull request close the ticket. */
|
|
182
186
|
linkText(ticket: number): string;
|
|
183
187
|
/** The address of the ticket's page. */
|
package/dist/tool-names.d.mts
CHANGED
|
@@ -3,6 +3,8 @@ export type Built = {
|
|
|
3
3
|
/** Each ticket system, with the keys it adds under `tickets`. */
|
|
4
4
|
tickets: Readonly<Record<string, readonly string[]>>;
|
|
5
5
|
runner: readonly string[];
|
|
6
|
+
/** Each spec tool, with the check \`specs.check\` defaults to. */
|
|
7
|
+
specs: Readonly<Record<string, string>>;
|
|
6
8
|
};
|
|
7
9
|
export declare const BUILT: Built;
|
|
8
10
|
/** The words every command fails with for a name that is not built, such
|
package/dist/tool-names.mjs
CHANGED
|
@@ -8,6 +8,9 @@ export const BUILT = {
|
|
|
8
8
|
codeHost: ["github"],
|
|
9
9
|
tickets: { github: [] },
|
|
10
10
|
runner: ["github-actions"],
|
|
11
|
+
specs: {
|
|
12
|
+
openspec: "npx --no-install openspec validate --all --strict --no-interactive",
|
|
13
|
+
},
|
|
11
14
|
};
|
|
12
15
|
/** The words every command fails with for a name that is not built, such
|
|
13
16
|
* as `tickets.type "jira" is not supported. "github" is the only ticket
|
package/dist/tools.d.mts
CHANGED
|
@@ -5,6 +5,7 @@ import type { Part } from "./parts.mts";
|
|
|
5
5
|
import { type Runner } from "./runner/index.mts";
|
|
6
6
|
import type { Chosen, SecretStep, SetupContext, SetupStep, ToolSetup } from "./setup.mts";
|
|
7
7
|
import { type Tickets } from "./tickets/index.mts";
|
|
8
|
+
import { type SpecTools } from "./specs/index.mts";
|
|
8
9
|
import { type Built } from "./tool-names.mts";
|
|
9
10
|
export type Tool = {
|
|
10
11
|
label: string;
|
|
@@ -31,6 +32,7 @@ export type Registry = {
|
|
|
31
32
|
agent: Record<string, Tool & {
|
|
32
33
|
agent: Agent;
|
|
33
34
|
}>;
|
|
35
|
+
specs: SpecTools;
|
|
34
36
|
};
|
|
35
37
|
export declare const TOOLS: Registry;
|
|
36
38
|
/** The names and keys the settings accept, as `config.mts` checks them. */
|
package/dist/tools.mjs
CHANGED
|
@@ -12,6 +12,7 @@ import { githubTicketsSetup } from "./tickets/github-setup.mjs";
|
|
|
12
12
|
import { openTickets } from "./tickets/index.mjs";
|
|
13
13
|
import { ghTransport } from "./tickets/transport.mjs";
|
|
14
14
|
import { githubActionsSetup } from "./runner/setup.mjs";
|
|
15
|
+
import { specTools } from "./specs/index.mjs";
|
|
15
16
|
import { BUILT } from "./tool-names.mjs";
|
|
16
17
|
export const TOOLS = {
|
|
17
18
|
codeHost: {
|
|
@@ -50,6 +51,7 @@ export const TOOLS = {
|
|
|
50
51
|
agent: claudeCodeAgent(spawn),
|
|
51
52
|
},
|
|
52
53
|
},
|
|
54
|
+
specs: specTools(),
|
|
53
55
|
};
|
|
54
56
|
/** The names and keys the settings accept, as `config.mts` checks them. */
|
|
55
57
|
export function builtOf(r) {
|
|
@@ -57,6 +59,7 @@ export function builtOf(r) {
|
|
|
57
59
|
codeHost: Object.keys(r.codeHost),
|
|
58
60
|
tickets: Object.fromEntries(Object.entries(r.tickets).map(([name, t]) => [name, t.keys])),
|
|
59
61
|
runner: Object.keys(r.runner),
|
|
62
|
+
specs: Object.fromEntries(Object.entries(r.specs).map(([name, t]) => [name, t.defaultCheck])),
|
|
60
63
|
};
|
|
61
64
|
}
|
|
62
65
|
/** The tools in use, in the order setup asks for them. */
|
package/docs/builds.md
CHANGED
|
@@ -64,7 +64,10 @@ stores it.
|
|
|
64
64
|
commits name your coding agent as their author and that account as their
|
|
65
65
|
committer, and its pull request and comments are that account's. When the token is yours, that is you. A team that wants an
|
|
66
66
|
agent account makes one on the code host, gives it write access, and stores
|
|
67
|
-
its token instead. Nothing else changes.
|
|
67
|
+
its token instead. Nothing else changes. An agent account can write to the
|
|
68
|
+
repository, so it counts as an approver, but every comment it posts
|
|
69
|
+
carries the factory's mark, and a session never takes a marked comment as
|
|
70
|
+
an instruction.
|
|
68
71
|
|
|
69
72
|
**Signed commits.** With a signing key stored as a secret, the build signs
|
|
70
73
|
each commit, and the code host shows it as verified when the key belongs to
|
|
@@ -116,28 +119,40 @@ does no further check.
|
|
|
116
119
|
### What it reads from its environment
|
|
117
120
|
|
|
118
121
|
On a server you host, the poller runs with no copy of your repository, so
|
|
119
|
-
it takes everything from environment variables. All
|
|
120
|
-
|
|
122
|
+
it takes everything from environment variables. All five are required.
|
|
123
|
+
Without `FACTORY_REPOSITORY` it doesn't start. Without any of the others,
|
|
124
|
+
it logs `not polling:` naming each that is missing, and starts no build
|
|
125
|
+
until they are set. On a schedule it has a
|
|
121
126
|
checkout, and needs only the token.
|
|
122
127
|
|
|
123
128
|
| Variable | What it is |
|
|
124
129
|
| ---------------------- | ------------------------------------------------------------------- |
|
|
125
130
|
| `FACTORY_REPOSITORY` | The repository, as `owner/name` |
|
|
126
131
|
| `FACTORY_BOARD_OWNER` | The account the board belongs to |
|
|
127
|
-
| `FACTORY_BOARD_NUMBER` |
|
|
132
|
+
| `FACTORY_BOARD_NUMBER` | The board's number, the last part of its address |
|
|
128
133
|
| `FACTORY_BOARD_TOKEN` | An access token that can read the board, comment, and start a build |
|
|
134
|
+
| `FACTORY_READY_COLUMN` | The column that approves a build |
|
|
129
135
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
[`
|
|
134
|
-
|
|
135
|
-
when it applies.
|
|
136
|
+
The repository, the board's number, and the ready column repeat what your
|
|
137
|
+
settings file says, because the poller cannot read it. The ready column
|
|
138
|
+
is the one [`tickets.columns.ready`](configuration.md#ticketscolumns)
|
|
139
|
+
names. [`factory board check`](cli.md) prints it on the ready row, for
|
|
140
|
+
you to copy:
|
|
136
141
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
142
|
+
```text
|
|
143
|
+
? ready Ready: the poller needs FACTORY_READY_COLUMN set to "Ready"
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
A poller only runs with a ready column: with `ready: none`, builds start
|
|
147
|
+
only when you ask, and there is no poller to host.
|
|
148
|
+
|
|
149
|
+
A poller set up before `FACTORY_READY_COLUMN` was required logs
|
|
150
|
+
`not polling: FACTORY_READY_COLUMN not set` after an update, and polls
|
|
151
|
+
nothing until you set it.
|
|
152
|
+
|
|
153
|
+
The factory takes the board's owner to be the repository's owner
|
|
154
|
+
everywhere else, a person or an organization, so a board owned by another
|
|
155
|
+
account is not supported yet.
|
|
141
156
|
|
|
142
157
|
### Its limits
|
|
143
158
|
|
|
@@ -171,6 +186,7 @@ docker run \
|
|
|
171
186
|
-e FACTORY_BOARD_OWNER=your-name \
|
|
172
187
|
-e FACTORY_BOARD_NUMBER=1 \
|
|
173
188
|
-e FACTORY_BOARD_TOKEN \
|
|
189
|
+
-e FACTORY_READY_COLUMN=Ready \
|
|
174
190
|
ghcr.io/davidbyoung/software-factory-poller:0.2.0
|
|
175
191
|
```
|
|
176
192
|
|
package/docs/cli.md
CHANGED
|
@@ -51,7 +51,7 @@ nothing to fix.
|
|
|
51
51
|
`doctor` prints its checks under headings: `Settings and files`, then
|
|
52
52
|
each tool's name, such as `GitHub` or `Claude Code`, then the parts you
|
|
53
53
|
left off. Each check starts with a mark: ✓ works, ✗ needs fixing, ?
|
|
54
|
-
|
|
54
|
+
worth a look, and - off on purpose. `doctor` exits 1 when a
|
|
55
55
|
check fails. GitHub never lets a secret be read back, so `doctor` checks
|
|
56
56
|
only that each secret your parts read is set.
|
|
57
57
|
|
|
@@ -137,32 +137,34 @@ prints what the ticket system returned as one JSON value. `edit`,
|
|
|
137
137
|
`comment`, and `open` refuse a body with a bare tag-like `<word>` the
|
|
138
138
|
ticket system would swallow, name it, and post nothing.
|
|
139
139
|
|
|
140
|
-
| Command | What it does
|
|
141
|
-
| ---------------------------------------------------------- |
|
|
142
|
-
| `factory ticket view N` | Prints ticket N: its title, state, labels, body, and comments with their IDs and authors
|
|
143
|
-
| `factory ticket
|
|
144
|
-
| `factory ticket
|
|
145
|
-
| `factory ticket list
|
|
146
|
-
| `factory ticket
|
|
147
|
-
| `factory ticket
|
|
148
|
-
| `factory ticket
|
|
149
|
-
| `factory ticket
|
|
150
|
-
| `factory ticket label N --
|
|
151
|
-
| `factory ticket
|
|
152
|
-
| `factory ticket
|
|
153
|
-
| `factory ticket
|
|
154
|
-
| `factory ticket
|
|
155
|
-
| `factory ticket
|
|
156
|
-
| `factory ticket
|
|
157
|
-
| `factory ticket
|
|
158
|
-
| `factory ticket
|
|
159
|
-
| `factory ticket
|
|
160
|
-
| `factory ticket
|
|
161
|
-
| `factory ticket
|
|
162
|
-
| `factory ticket
|
|
163
|
-
| `factory ticket
|
|
164
|
-
| `factory ticket
|
|
165
|
-
| `factory
|
|
140
|
+
| Command | What it does |
|
|
141
|
+
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
142
|
+
| `factory ticket view N` | Prints ticket N: its title, state, labels, body, and comments with their IDs and authors |
|
|
143
|
+
| `factory ticket answers N` | Prints each comment on N that counts as an answer: its author can write to the repository, and it is not the factory's own. Says so when there is none |
|
|
144
|
+
| `factory ticket view N --field NAME` | Prints one of `title`, `state`, `labels` (one per line), or `body`, and nothing else |
|
|
145
|
+
| `factory ticket list` | Lists the open tickets: number, title, and labels, separated by tabs |
|
|
146
|
+
| `factory ticket list --label LABEL` | Only those with the label. `--title "TITLE"` keeps those whose title is exactly that |
|
|
147
|
+
| `factory ticket edit N [--title TITLE] [--body-file FILE]` | Replaces N's title, its body, or both. `--attach FILE` adds an image to a body |
|
|
148
|
+
| `factory ticket comment N --body-file FILE` | Comments on N and prints the comment's ID. `--attach FILE` adds an image |
|
|
149
|
+
| `factory ticket open --title TITLE --body-file FILE` | Opens a ticket and prints its number. `--label LABEL` adds a label |
|
|
150
|
+
| `factory ticket label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off |
|
|
151
|
+
| `factory ticket label N --was-removed LABEL` | Prints `yes` if the label was ever removed from N, otherwise `no` |
|
|
152
|
+
| `factory ticket link N` | Prints the text that makes a merged pull request close N, such as "Closes #12" |
|
|
153
|
+
| `factory ticket branch N` | Prints the branch a build of N pushes, from [`code-host.branch-name`](configuration.md#code-host), such as `12` or `feature/octocat/12`. Exits 1 when N does not exist, or the pattern has `{user}` and `gh` is not signed in |
|
|
154
|
+
| `factory ticket blockers N` | One line per ticket N waits on: its number and whether it is open |
|
|
155
|
+
| `factory ticket block N --by M` | Records that N waits on M |
|
|
156
|
+
| `factory ticket unblock N --by M` | Removes that record |
|
|
157
|
+
| `factory ticket supports GROUP` | Prints `yes` or `no` for `board`, `blockers`, `label-history`, or `attachments` |
|
|
158
|
+
| `factory ticket claim N` | Claims ticket N for this session. Prints `claimed`, `held by`, or `blocked by` |
|
|
159
|
+
| `factory ticket still-live N` | Says whether this session still holds N |
|
|
160
|
+
| `factory ticket stop N "reason"` | Releases N and says why |
|
|
161
|
+
| `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` |
|
|
162
|
+
| `factory ticket refining N` | Marks N as being refined |
|
|
163
|
+
| `factory ticket waiting N` | Marks N as waiting on your reply to a round of questions |
|
|
164
|
+
| `factory ticket refined N` | Marks N as refined, unless its body lacks what a build reads. `--check` makes that check alone and posts nothing |
|
|
165
|
+
| `factory ticket ready N` | Moves N to Ready. Only when you ask a session to |
|
|
166
|
+
| `factory ticket cost N` | Notes what this session spent on N since it started |
|
|
167
|
+
| `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 |
|
|
166
168
|
|
|
167
169
|
`factory ticket refined N` posts nothing and exits 1 when N's body lacks a
|
|
168
170
|
section a build reads, printing one line for each, such as
|
|
@@ -182,15 +184,16 @@ ticket system.
|
|
|
182
184
|
| `factory pr reply N COMMENT --body-file FILE` | Replies on a thread |
|
|
183
185
|
| `factory pr resolve N COMMENT` | Resolves a thread |
|
|
184
186
|
| `factory pr closes N` | The tickets N closes |
|
|
187
|
+
| `factory pr for-branch BRANCH` | The newest pull request from BRANCH, open or not: `#N open`, `#N merged`, or `#N closed`, or `none` when there has been none |
|
|
185
188
|
| `factory pr wait-checks N` | Waits for every CI run on the pushed commit. Prints `success`, `failure:` with the failed checks, or `no checks` |
|
|
186
189
|
| `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 |
|
|
187
|
-
| `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`
|
|
190
|
+
| `factory pr comments N` | N's conversation comments: ID, author, time, and first line. `--author LOGIN`, `--contains TEXT`, `--from-approvers`, which keeps the comments whose author can write to the repository, and `--json`, which prints each comment's `id`, `user.login`, `body`, and `created_at` |
|
|
188
191
|
| `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 |
|
|
189
192
|
| `factory pr comment-view ID` | Prints one conversation comment's body |
|
|
190
193
|
| `factory pr label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off |
|
|
191
194
|
| `factory pr watch N` | Waits until N needs attention, says why, and exits |
|
|
192
195
|
| `factory pr watch N --release` | Stops watching N |
|
|
193
|
-
| `factory pr review-pending N REVIEW` | Exits 0 when
|
|
196
|
+
| `factory pr review-pending N REVIEW` | Exits 0 when an approver's review has something of theirs to answer, and 1, saying why, when it has not |
|
|
194
197
|
| `factory pr conflicts` | The pull requests the conflict sweep takes, one number a line; exits 0 when there is one and 1 when none |
|
|
195
198
|
| `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 |
|
|
196
199
|
| `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) |
|
|
@@ -222,9 +225,24 @@ You can run them too.
|
|
|
222
225
|
| `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 `✗ The gate failed on:` and the command. Ends with `✓ Every gate command passed.` and exits 0 when every command passes, and exits 1 at the first that fails or when no gate is set |
|
|
223
226
|
| `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 |
|
|
224
227
|
| `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. Ends with `✓ The test passed.` or `✗ The test failed.` |
|
|
225
|
-
| `factory specs
|
|
228
|
+
| `factory specs list` | Prints each spec your spec tool keeps, one per line with its file, or `none yet` |
|
|
229
|
+
| `factory specs new N` | Starts ticket N's spec: with OpenSpec, it creates `openspec/changes/issue-N/`. Then it prints each file to write or update there, which part of the ticket goes in it, and, last, the command to run once they are written. It writes none of them itself, and run again, it prints them again |
|
|
230
|
+
| `factory specs check` | Runs [`specs.check`](configuration.md#specscheck), the check of your written specs, ending with `✓ The specs check passed.` or `✗ The specs check failed.` |
|
|
231
|
+
| `factory specs finish N` | With OpenSpec, folds ticket N's spec into `openspec/specs/`, ending with `✓ Folded ticket N's spec into openspec/specs/.` It changes files and commits nothing |
|
|
226
232
|
| `factory default-branch` | Prints the name of your repository's default branch, which nothing in the factory assumes is `main` |
|
|
227
233
|
|
|
234
|
+
With [`specs: none`](configuration.md#specs), each of the four
|
|
235
|
+
`factory specs` commands prints
|
|
236
|
+
`- No spec tool (specs: none): each ticket holds its own spec.` and
|
|
237
|
+
exits 0. Otherwise each exits 0 when it worked and 1 when it didn't, and
|
|
238
|
+
says why on its last line: `new` when your spec tool isn't installed, which
|
|
239
|
+
`factory init` fixes, and `finish` when ticket N has no spec started,
|
|
240
|
+
which `factory specs new N` fixes.
|
|
241
|
+
|
|
242
|
+
A build runs `new` before it writes any code, and `finish` just before
|
|
243
|
+
its last commit, so you rarely run those two yourself. `list` is the one
|
|
244
|
+
to know: it names the spec to read before you change what it describes.
|
|
245
|
+
|
|
228
246
|
`factory default-branch` asks, in turn, the event of the workflow run it
|
|
229
247
|
is in, `origin/HEAD` in your checkout, and the code host, whose answer it
|
|
230
248
|
writes to `origin/HEAD` so the next run asks nobody. A checkout with no
|