@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.
Files changed (67) hide show
  1. package/agents/factory-ticket-readiness.md +20 -15
  2. package/dist/board.d.mts +1 -1
  3. package/dist/board.mjs +4 -7
  4. package/dist/cli.mjs +23 -1
  5. package/dist/code-host/github.d.mts +1 -1
  6. package/dist/code-host/github.mjs +31 -2
  7. package/dist/code-host/types.d.mts +20 -1
  8. package/dist/code-host/types.mjs +8 -0
  9. package/dist/columns-suggest.d.mts +25 -5
  10. package/dist/columns-suggest.mjs +117 -21
  11. package/dist/commands.d.mts +8 -2
  12. package/dist/commands.mjs +92 -8
  13. package/dist/config.d.mts +19 -7
  14. package/dist/config.mjs +109 -30
  15. package/dist/doctor.mjs +1 -2
  16. package/dist/explain.mjs +7 -1
  17. package/dist/init.d.mts +19 -0
  18. package/dist/init.mjs +139 -23
  19. package/dist/lib/gh.d.mts +6 -0
  20. package/dist/lib/gh.mjs +11 -1
  21. package/dist/lib/listed.d.mts +3 -2
  22. package/dist/lib/listed.mjs +5 -4
  23. package/dist/lib/work-status.d.mts +5 -5
  24. package/dist/lib/work-status.mjs +7 -8
  25. package/dist/merge-policy.mjs +7 -3
  26. package/dist/poller.d.mts +1 -1
  27. package/dist/poller.mjs +9 -6
  28. package/dist/pr.d.mts +8 -6
  29. package/dist/pr.mjs +47 -22
  30. package/dist/review-verdict.d.mts +22 -4
  31. package/dist/review-verdict.mjs +55 -17
  32. package/dist/specs/index.d.mts +6 -0
  33. package/dist/specs/index.mjs +15 -0
  34. package/dist/specs/openspec.d.mts +2 -0
  35. package/dist/specs/openspec.mjs +78 -0
  36. package/dist/specs/types.d.mts +53 -0
  37. package/dist/specs/types.mjs +4 -0
  38. package/dist/ticket.d.mts +6 -1
  39. package/dist/ticket.mjs +62 -3
  40. package/dist/tickets/github-access.d.mts +5 -0
  41. package/dist/tickets/github-access.mjs +22 -0
  42. package/dist/tickets/github.mjs +2 -0
  43. package/dist/tickets/types.d.mts +4 -0
  44. package/dist/tool-names.d.mts +2 -0
  45. package/dist/tool-names.mjs +3 -0
  46. package/dist/tools.d.mts +2 -0
  47. package/dist/tools.mjs +3 -0
  48. package/docs/builds.md +30 -14
  49. package/docs/cli.md +48 -30
  50. package/docs/configuration.md +237 -73
  51. package/docs/developing.md +104 -59
  52. package/docs/existing-repo.md +51 -29
  53. package/docs/github/by-hand.md +13 -1
  54. package/docs/github/setup.md +26 -2
  55. package/docs/glossary.md +7 -6
  56. package/docs/limitations.md +8 -5
  57. package/docs/presets.md +15 -3
  58. package/docs/updating.md +147 -2
  59. package/docs/workflow.md +26 -9
  60. package/package.json +1 -1
  61. package/rules.md +36 -30
  62. package/settings.schema.json +14 -9
  63. package/skills/factory-address-review/SKILL.md +40 -39
  64. package/skills/factory-build/SKILL.md +77 -52
  65. package/skills/factory-deps/SKILL.md +6 -4
  66. package/skills/factory-refine/SKILL.md +30 -22
  67. 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("", `--- comment ${c.id} by ${c.author} at ${c.createdAt}`, c.body.trimEnd());
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
+ }
@@ -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: {
@@ -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. */
@@ -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
@@ -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 four are required; it
120
- exits at startup naming any that is missing. On a schedule it has a
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` | Which board |
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
- One more is optional. `FACTORY_READY_COLUMN` is the name of the column
131
- that approves a build, and defaults to Ready. The poller has no settings
132
- file, so a repository whose
133
- [`tickets.columns.ready`](configuration.md#ticketscolumns) names another
134
- column sets it where the poller runs. `factory board check` reminds you
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
- The repository and the board's number repeat what your settings file says,
138
- because the poller cannot read it. The factory takes the board's owner to
139
- be the repository's owner everywhere else, a person or an organization, so
140
- a board owned by another account is not supported yet.
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
- can't be told from here, and - off on purpose. `doctor` exits 1 when a
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 view N --field NAME` | Prints one of `title`, `state`, `labels` (one per line), or `body`, and nothing else |
144
- | `factory ticket list` | Lists the open tickets: number, title, and labels, separated by tabs |
145
- | `factory ticket list --label LABEL` | Only those with the label. `--title "TITLE"` keeps those whose title is exactly that |
146
- | `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 |
147
- | `factory ticket comment N --body-file FILE` | Comments on N and prints the comment's ID. `--attach FILE` adds an image |
148
- | `factory ticket open --title TITLE --body-file FILE` | Opens a ticket and prints its number. `--label LABEL` adds a label |
149
- | `factory ticket label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off |
150
- | `factory ticket label N --was-removed LABEL` | Prints `yes` if the label was ever removed from N, otherwise `no` |
151
- | `factory ticket link N` | Prints the text that makes a merged pull request close N, such as "Closes #12" |
152
- | `factory ticket blockers N` | One line per ticket N waits on: its number and whether it is open |
153
- | `factory ticket block N --by M` | Records that N waits on M |
154
- | `factory ticket unblock N --by M` | Removes that record |
155
- | `factory ticket supports GROUP` | Prints `yes` or `no` for `board`, `blockers`, `label-history`, or `attachments` |
156
- | `factory ticket claim N` | Claims ticket N for this session. Prints `claimed`, `held by`, or `blocked by` |
157
- | `factory ticket still-live N` | Says whether this session still holds N |
158
- | `factory ticket stop N "reason"` | Releases N and says why |
159
- | `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` |
160
- | `factory ticket refining N` | Marks N as being refined |
161
- | `factory ticket waiting N` | Marks N as waiting on your reply to a round of questions |
162
- | `factory ticket refined N` | Marks N as refined, unless its body lacks what a build reads. `--check` makes that check alone and posts nothing |
163
- | `factory ticket ready N` | Moves N to Ready. Only when you ask a session to |
164
- | `factory ticket cost N` | Notes what this session spent on N since it started |
165
- | `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 |
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 the owner's review has something of theirs to answer, and 1, saying why, when it has not |
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 check` | Runs [`specs.check`](configuration.md#specscheck), the check of your written specs, and exits with its status, ending with `✓ The specs check passed.` or `✗ The specs check failed.`. Prints `specs are off` when `specs` is `none` |
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