@davidbyoung/software-factory 0.1.4 → 0.1.6
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 +9 -8
- package/dist/cli.mjs +13 -1
- package/dist/code-host/github-setup.mjs +1 -1
- package/dist/config.d.mts +74 -20
- package/dist/config.mjs +326 -76
- package/dist/deps.d.mts +6 -4
- package/dist/deps.mjs +29 -7
- package/dist/doctor.d.mts +3 -0
- package/dist/doctor.mjs +7 -4
- package/dist/explain.d.mts +13 -2
- package/dist/explain.mjs +58 -43
- package/dist/init.mjs +9 -7
- package/dist/lib/default-branch.d.mts +1 -1
- package/dist/lib/default-branch.mjs +2 -2
- package/dist/lib/refined-check.mjs +1 -1
- package/dist/lib/work-status.d.mts +2 -2
- package/dist/lib/work-status.mjs +4 -4
- package/dist/parts.d.mts +1 -1
- package/dist/parts.mjs +2 -2
- package/dist/preset-commands.d.mts +65 -0
- package/dist/preset-commands.mjs +1148 -0
- package/dist/preset.d.mts +169 -0
- package/dist/preset.mjs +550 -0
- package/dist/remove.mjs +34 -1
- package/dist/review-cost.mjs +1 -1
- package/dist/review-tools.mjs +3 -3
- package/dist/session-start.d.mts +3 -0
- package/dist/session-start.mjs +12 -1
- package/dist/sync.d.mts +42 -7
- package/dist/sync.mjs +166 -32
- package/docs/builds.md +12 -11
- package/docs/cli.md +27 -8
- package/docs/configuration.md +723 -714
- package/docs/design.md +1 -1
- package/docs/developing.md +20 -8
- package/docs/existing-repo.md +1 -1
- package/docs/github/by-hand.md +9 -9
- package/docs/github/reference.md +4 -19
- package/docs/github/setup.md +3 -3
- package/docs/glossary.md +18 -9
- package/docs/limitations.md +4 -1
- package/docs/plugins.md +36 -24
- package/docs/presets.md +410 -0
- package/docs/quick-start.md +21 -18
- package/docs/removing.md +1 -1
- package/docs/skills.md +28 -23
- package/docs/updating.md +22 -14
- package/docs/workflow.md +13 -14
- package/package.json +1 -1
- package/rules.md +1 -1
- package/settings.schema.json +60 -11
- package/skills/factory-build/SKILL.md +1 -1
- package/skills/factory-deps/SKILL.md +23 -12
- package/skills/factory-design/SKILL.md +2 -2
- package/skills/factory-refine/SKILL.md +2 -2
- package/skills/factory-resolve-conflicts/SKILL.md +6 -0
- package/workflows/factory-claude-review.yml +8 -3
package/dist/sync.d.mts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import { type Settings } from "./config.mts";
|
|
1
|
+
import { type Resolved, type Settings } from "./config.mts";
|
|
2
|
+
import { type Replaced } from "./preset.mts";
|
|
2
3
|
/** The package's own folder: the parent of `src/`, or of `dist/` once
|
|
3
4
|
* compiled. */
|
|
4
5
|
export declare const PACKAGE: string;
|
|
@@ -58,27 +59,61 @@ export declare function withImport(text: string | null): string;
|
|
|
58
59
|
/** `CLAUDE.md` without the rules' import, nor the blank line `withImport`
|
|
59
60
|
* put before it, or null when nothing else is left. */
|
|
60
61
|
export declare function withoutImport(text: string): string | null;
|
|
61
|
-
export
|
|
62
|
-
|
|
62
|
+
export type LockParts = {
|
|
63
|
+
version: string;
|
|
64
|
+
presets: {
|
|
65
|
+
name: string;
|
|
66
|
+
version: string;
|
|
67
|
+
}[];
|
|
68
|
+
hash: string;
|
|
69
|
+
/** The settings in effect, as `factory config explain` prints them. */
|
|
70
|
+
settings: string[];
|
|
71
|
+
overridden: Record<string, Replaced[]>;
|
|
72
|
+
files: string[];
|
|
73
|
+
};
|
|
74
|
+
export declare function lockText(l: LockParts): string;
|
|
75
|
+
/** The files a lock lists, from any release's lock. One that a merge left
|
|
76
|
+
* with conflict markers is read line by line, from each side's `files`. */
|
|
77
|
+
export declare function lockedFiles(text: string | null, load: (t: string) => unknown): string[];
|
|
78
|
+
/** The dependency auto-merge workflow with each preset's package held back
|
|
79
|
+
* as the factory's own is, so a preset update waits for a person. */
|
|
80
|
+
export declare function withPresetPackages(text: string, packages: string[], file: string): string;
|
|
63
81
|
export type Plan = {
|
|
64
82
|
/** Path from the root, and its text, for each file a sync writes. */
|
|
65
83
|
write: Map<string, string>;
|
|
66
|
-
/** Paths the lock lists that this version no longer writes
|
|
84
|
+
/** Paths the lock lists that this version no longer writes, and the
|
|
85
|
+
* choices file once its last choice is dropped. */
|
|
67
86
|
remove: string[];
|
|
87
|
+
/** A line for each preset file left as it is. */
|
|
88
|
+
kept: string[];
|
|
89
|
+
/** A line for each choice dropped. */
|
|
90
|
+
dropped: string[];
|
|
68
91
|
};
|
|
69
92
|
/** What a sync of `root` from `pkg` writes and deletes, in a repository
|
|
70
93
|
* whose default branch is `branch`. */
|
|
71
|
-
export declare function plan(pkg: string, root: string,
|
|
94
|
+
export declare function plan(pkg: string, root: string, r: Resolved, branch: string): Promise<Plan>;
|
|
72
95
|
/** The paths whose content a sync would change, in the plan's order. */
|
|
73
96
|
export declare function differences(root: string, p: Plan): string[];
|
|
74
97
|
export declare function main(argv: string[], d: {
|
|
75
98
|
root: string;
|
|
76
99
|
pkg: string;
|
|
77
|
-
settings: () => Promise<
|
|
100
|
+
settings: () => Promise<Resolved>;
|
|
101
|
+
/** Why the lock is stale, or null when it is current. */
|
|
102
|
+
stale: () => Promise<string | null>;
|
|
78
103
|
/** The repository's default branch, or null when it cannot be told. */
|
|
79
|
-
defaultBranch: () => Promise<string | null>;
|
|
104
|
+
defaultBranch: (s: Settings) => Promise<string | null>;
|
|
80
105
|
out: (line: string) => void;
|
|
81
106
|
err: (line: string) => void;
|
|
82
107
|
}): Promise<number>;
|
|
108
|
+
/** The sync of the repository at `root`. */
|
|
109
|
+
export declare const syncDeps: (root: string) => {
|
|
110
|
+
root: string;
|
|
111
|
+
pkg: string;
|
|
112
|
+
settings: () => Promise<Resolved>;
|
|
113
|
+
stale: () => Promise<string | null>;
|
|
114
|
+
defaultBranch: (s: Settings) => Promise<string | null>;
|
|
115
|
+
out: (line: string) => void;
|
|
116
|
+
err: (line: string) => void;
|
|
117
|
+
};
|
|
83
118
|
export declare function run(argv: string[]): Promise<number>;
|
|
84
119
|
export {};
|
package/dist/sync.mjs
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
// Writes the factory's skills, agents, rules, review instructions,
|
|
2
2
|
// workflows, and the actions they call from the package into the
|
|
3
|
-
// repository, its
|
|
4
|
-
// import into `CLAUDE.md`, and
|
|
5
|
-
// `.claude/factory.lock`: the factory's version
|
|
3
|
+
// repository, the agents and skills its presets ship, its hook entries
|
|
4
|
+
// into `.claude/settings.json`, the rules' import into `CLAUDE.md`, and
|
|
5
|
+
// `.claude/factory.lock`: the factory's version, the presets, the settings
|
|
6
|
+
// in effect, and the files it wrote. Every other command reads the
|
|
7
|
+
// settings from the lock.
|
|
6
8
|
//
|
|
7
9
|
// factory sync # write what differs
|
|
8
10
|
// factory sync --check # write nothing; exit 1 naming what differs
|
|
@@ -15,7 +17,8 @@
|
|
|
15
17
|
import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from "node:fs";
|
|
16
18
|
import { dirname, join, relative, sep } from "node:path";
|
|
17
19
|
import { fileURLToPath } from "node:url";
|
|
18
|
-
import {
|
|
20
|
+
import { filesDeps, repoRoot, resolveFiles, RULE_NUMBERS, staleOf, defaultDeps, } from "./config.mjs";
|
|
21
|
+
import { CHOICES_FILE, choicesText, settingsHash, staleChoices, } from "./preset.mjs";
|
|
19
22
|
import { branchDeps, CANNOT_TELL, defaultBranch, } from "./lib/default-branch.mjs";
|
|
20
23
|
/** The package's own folder: the parent of `src/`, or of `dist/` once
|
|
21
24
|
* compiled. */
|
|
@@ -39,7 +42,7 @@ const NEEDS = {
|
|
|
39
42
|
"workflows/factory-deps-auto-merge.yml": (_, has) => has(DEPENDABOT),
|
|
40
43
|
"workflows/factory-board-sync.yml": (s) => s.tickets.board !== null,
|
|
41
44
|
"workflows/factory-merge-policy.yml": (s) => s.autoMerge.allow.length > 0,
|
|
42
|
-
"workflows/factory-claude-review.yml": (s) => s.
|
|
45
|
+
"workflows/factory-claude-review.yml": (s) => s.prReview !== null,
|
|
43
46
|
"workflows/factory-poller.yml": (s) => s.builds.trigger === "github-action",
|
|
44
47
|
};
|
|
45
48
|
const POLLER_WORKFLOW = "workflows/factory-poller.yml";
|
|
@@ -348,27 +351,102 @@ export function withoutImport(text) {
|
|
|
348
351
|
const after = lines.join("\n");
|
|
349
352
|
return after.trim() ? after : null;
|
|
350
353
|
}
|
|
351
|
-
|
|
354
|
+
/** A key or a value as YAML: plain where it reads back as the same text,
|
|
355
|
+
* quoted as JSON otherwise. */
|
|
356
|
+
const scalar = (v) => typeof v === "string" &&
|
|
357
|
+
/^[A-Za-z0-9_./][A-Za-z0-9_./ -]*$/.test(v) &&
|
|
358
|
+
!/ $/.test(v) &&
|
|
359
|
+
!/^(true|false|null|yes|no|on|off|~|[-+.\d][\d._eE+-]*)$/i.test(v)
|
|
360
|
+
? v
|
|
361
|
+
: JSON.stringify(v);
|
|
362
|
+
export function lockText(l) {
|
|
363
|
+
const replaced = Object.entries(l.overridden);
|
|
352
364
|
return [
|
|
353
|
-
"# Written by `factory sync`: the factory's version
|
|
354
|
-
"# wrote. Do not edit.",
|
|
355
|
-
`version: ${version}`,
|
|
365
|
+
"# Written by `factory sync`: the factory's version, the presets, the",
|
|
366
|
+
"# settings in effect, and the files it wrote. Do not edit.",
|
|
367
|
+
`version: ${l.version}`,
|
|
368
|
+
...(l.presets.length
|
|
369
|
+
? [
|
|
370
|
+
"presets:",
|
|
371
|
+
...l.presets.flatMap((p) => [
|
|
372
|
+
` - name: ${JSON.stringify(p.name)}`,
|
|
373
|
+
` version: ${scalar(p.version)}`,
|
|
374
|
+
]),
|
|
375
|
+
]
|
|
376
|
+
: ["presets: []"]),
|
|
377
|
+
`settings-hash: ${l.hash}`,
|
|
378
|
+
"settings:",
|
|
379
|
+
...l.settings.map((line) => ` ${line}`),
|
|
380
|
+
...(replaced.length
|
|
381
|
+
? [
|
|
382
|
+
"overridden:",
|
|
383
|
+
...replaced.flatMap(([key, values]) => [
|
|
384
|
+
` ${scalar(key)}:`,
|
|
385
|
+
...values.flatMap((r) => [
|
|
386
|
+
` - from: ${JSON.stringify(r.from)}`,
|
|
387
|
+
` value: ${JSON.stringify(r.value)}`,
|
|
388
|
+
]),
|
|
389
|
+
]),
|
|
390
|
+
]
|
|
391
|
+
: ["overridden: {}"]),
|
|
356
392
|
"files:",
|
|
357
|
-
...files.map((f) => ` - ${f}`),
|
|
393
|
+
...l.files.map((f) => ` - ${f}`),
|
|
358
394
|
"",
|
|
359
395
|
].join("\n");
|
|
360
396
|
}
|
|
361
|
-
|
|
397
|
+
/** The files a lock lists, from any release's lock. One that a merge left
|
|
398
|
+
* with conflict markers is read line by line, from each side's `files`. */
|
|
399
|
+
export function lockedFiles(text, load) {
|
|
362
400
|
if (!text)
|
|
363
401
|
return [];
|
|
402
|
+
try {
|
|
403
|
+
const o = load(text);
|
|
404
|
+
return Array.isArray(o?.files) ? o.files.map(String) : [];
|
|
405
|
+
}
|
|
406
|
+
catch {
|
|
407
|
+
const out = [];
|
|
408
|
+
let inFiles = false;
|
|
409
|
+
for (const line of text.split("\n")) {
|
|
410
|
+
if (/^files:/.test(line))
|
|
411
|
+
inFiles = true;
|
|
412
|
+
else if (/^\S/.test(line) && !/^(<{7}|={7}|>{7})/.test(line))
|
|
413
|
+
inFiles = false;
|
|
414
|
+
const item = inFiles ? /^ {2}- (.+)$/.exec(line)?.[1] : undefined;
|
|
415
|
+
if (item && !out.includes(item))
|
|
416
|
+
out.push(item);
|
|
417
|
+
}
|
|
418
|
+
return out;
|
|
419
|
+
}
|
|
420
|
+
}
|
|
421
|
+
const AUTO_MERGE_WORKFLOW = "workflows/factory-deps-auto-merge.yml";
|
|
422
|
+
const FACTORY_EXCLUSION = "!contains(steps.meta.outputs.dependency-names, 'davidbyoung/software-factory')";
|
|
423
|
+
/** The dependency auto-merge workflow with each preset's package held back
|
|
424
|
+
* as the factory's own is, so a preset update waits for a person. */
|
|
425
|
+
export function withPresetPackages(text, packages, file) {
|
|
426
|
+
if (!packages.length)
|
|
427
|
+
return text;
|
|
428
|
+
const at = text.split(FACTORY_EXCLUSION).length - 1;
|
|
429
|
+
if (at !== 1)
|
|
430
|
+
throw new Error(`${file}: expected one line holding back the factory, to hold back the presets too`);
|
|
364
431
|
return text
|
|
365
432
|
.split("\n")
|
|
366
|
-
.map((
|
|
367
|
-
.
|
|
433
|
+
.map((line) => {
|
|
434
|
+
if (line.trim() !== FACTORY_EXCLUSION)
|
|
435
|
+
return line;
|
|
436
|
+
const indent = line.slice(0, line.indexOf("!"));
|
|
437
|
+
return [
|
|
438
|
+
`${line} &&`,
|
|
439
|
+
...packages.map((p, i) => `${indent}!contains(steps.meta.outputs.dependency-names, '${p}')${i < packages.length - 1 ? " &&" : ""}`),
|
|
440
|
+
].join("\n");
|
|
441
|
+
})
|
|
442
|
+
.join("\n");
|
|
368
443
|
}
|
|
369
444
|
/** What a sync of `root` from `pkg` writes and deletes, in a repository
|
|
370
445
|
* whose default branch is `branch`. */
|
|
371
|
-
export function plan(pkg, root,
|
|
446
|
+
export async function plan(pkg, root, r, branch) {
|
|
447
|
+
const { load } = await import("js-yaml");
|
|
448
|
+
const { explainLines, markerOf } = await import("./explain.mjs");
|
|
449
|
+
const s = r.settings;
|
|
372
450
|
const manifest = JSON.parse(readFileSync(join(pkg, "package.json"), "utf8"));
|
|
373
451
|
const read = (p) => existsSync(join(root, p)) ? readFileSync(join(root, p), "utf8") : null;
|
|
374
452
|
const write = new Map();
|
|
@@ -383,15 +461,55 @@ export function plan(pkg, root, s, branch) {
|
|
|
383
461
|
? withMinutes(text, s.sessionMinutes[kind], from)
|
|
384
462
|
: from === POLLER_WORKFLOW
|
|
385
463
|
? withSchedule(text, s.builds.pollMinutes, from)
|
|
386
|
-
:
|
|
464
|
+
: from === AUTO_MERGE_WORKFLOW
|
|
465
|
+
? withPresetPackages(text, [...new Set(r.presets.map((p) => p.pkg))], from)
|
|
466
|
+
: withRules(text, s.rules, from));
|
|
467
|
+
}
|
|
468
|
+
// A preset's agent or skill, unless the factory's own file or one the
|
|
469
|
+
// repository wrote itself is at its path: those always stay.
|
|
470
|
+
const previous = lockedFiles(read(LOCK), load);
|
|
471
|
+
const kept = [];
|
|
472
|
+
for (const [to, { from, source }] of r.resolution.files) {
|
|
473
|
+
if (write.has(to))
|
|
474
|
+
kept.push(`kept ${to}, the factory's own, over ${from}`);
|
|
475
|
+
else if (existsSync(join(root, to)) && !previous.includes(to))
|
|
476
|
+
kept.push(`kept ${to}, this repository's own, over ${from}`);
|
|
477
|
+
else
|
|
478
|
+
write.set(to, readFileSync(source, "utf8"));
|
|
387
479
|
}
|
|
388
480
|
const launcher = launcherPath(pkg, root, manifest.name);
|
|
389
481
|
write.set(SETTINGS_JSON, withHooks(read(SETTINGS_JSON), launcher));
|
|
390
482
|
write.set(CLAUDE_MD, withImport(read(CLAUDE_MD)));
|
|
391
483
|
const files = [...write.keys()].filter((p) => p !== SETTINGS_JSON && p !== CLAUDE_MD);
|
|
392
|
-
|
|
393
|
-
const
|
|
394
|
-
|
|
484
|
+
// A choice whose preset is gone, or no longer sets its key, is dropped.
|
|
485
|
+
const stale = staleChoices(r.choices, r.presets.map((p) => p.name), r.resolution.setBy);
|
|
486
|
+
const choices = { ...r.choices };
|
|
487
|
+
for (const c of stale)
|
|
488
|
+
delete choices[c.key];
|
|
489
|
+
const chosen = stale.length ? choicesText(choices) : r.choicesText;
|
|
490
|
+
const remove = [];
|
|
491
|
+
if (stale.length) {
|
|
492
|
+
if (chosen === null)
|
|
493
|
+
remove.push(CHOICES_FILE);
|
|
494
|
+
else
|
|
495
|
+
write.set(CHOICES_FILE, chosen);
|
|
496
|
+
}
|
|
497
|
+
const settings = await explainLines(s, markerOf(r.resolution), (p) => r.exists(p) || write.has(p));
|
|
498
|
+
write.set(LOCK, lockText({
|
|
499
|
+
version: manifest.version,
|
|
500
|
+
presets: r.presets.map((p) => ({ name: p.name, version: p.version })),
|
|
501
|
+
hash: settingsHash(r.ownText, chosen),
|
|
502
|
+
settings,
|
|
503
|
+
overridden: Object.fromEntries(r.resolution.overridden),
|
|
504
|
+
files,
|
|
505
|
+
}));
|
|
506
|
+
remove.unshift(...previous.filter((p) => !write.has(p) && existsSync(join(root, p))));
|
|
507
|
+
return {
|
|
508
|
+
write,
|
|
509
|
+
remove: remove.filter((p) => existsSync(join(root, p))),
|
|
510
|
+
kept,
|
|
511
|
+
dropped: stale.map((c) => `dropped the choice for ${c.key}: ${c.reason}`),
|
|
512
|
+
};
|
|
395
513
|
}
|
|
396
514
|
/** The paths whose content a sync would change, in the plan's order. */
|
|
397
515
|
export function differences(root, p) {
|
|
@@ -401,13 +519,25 @@ export function differences(root, p) {
|
|
|
401
519
|
return !existsSync(at) || readFileSync(at, "utf8") !== text;
|
|
402
520
|
})
|
|
403
521
|
.map(([path]) => path);
|
|
404
|
-
|
|
522
|
+
// The lock comes last, as it records everything before it.
|
|
523
|
+
return [
|
|
524
|
+
...changed.filter((path) => path !== LOCK),
|
|
525
|
+
...p.remove,
|
|
526
|
+
...changed.filter((path) => path === LOCK),
|
|
527
|
+
];
|
|
405
528
|
}
|
|
406
529
|
export async function main(argv, d) {
|
|
407
530
|
const check = argv.includes("--check");
|
|
408
|
-
let
|
|
531
|
+
let r;
|
|
409
532
|
try {
|
|
410
|
-
|
|
533
|
+
if (check) {
|
|
534
|
+
const reason = await d.stale();
|
|
535
|
+
if (reason) {
|
|
536
|
+
d.err(reason);
|
|
537
|
+
return 1;
|
|
538
|
+
}
|
|
539
|
+
}
|
|
540
|
+
r = await d.settings();
|
|
411
541
|
}
|
|
412
542
|
catch (e) {
|
|
413
543
|
d.err(e instanceof Error ? e.message : String(e));
|
|
@@ -415,12 +545,12 @@ export async function main(argv, d) {
|
|
|
415
545
|
}
|
|
416
546
|
// Nothing is written with a guessed name: a push trigger that names the
|
|
417
547
|
// wrong branch never runs.
|
|
418
|
-
const branch = await d.defaultBranch();
|
|
548
|
+
const branch = await d.defaultBranch(r.settings);
|
|
419
549
|
if (branch === null) {
|
|
420
550
|
d.err(CANNOT_TELL);
|
|
421
551
|
return 1;
|
|
422
552
|
}
|
|
423
|
-
const p = plan(d.pkg, d.root,
|
|
553
|
+
const p = await plan(d.pkg, d.root, r, branch);
|
|
424
554
|
const differ = differences(d.root, p);
|
|
425
555
|
if (check) {
|
|
426
556
|
if (differ.length === 0)
|
|
@@ -431,6 +561,8 @@ export async function main(argv, d) {
|
|
|
431
561
|
d.err("Run `npx --no-install factory sync` and commit the result.");
|
|
432
562
|
return 1;
|
|
433
563
|
}
|
|
564
|
+
for (const line of [...p.kept, ...p.dropped])
|
|
565
|
+
d.out(line);
|
|
434
566
|
for (const path of differ) {
|
|
435
567
|
const at = join(d.root, path);
|
|
436
568
|
const text = p.write.get(path);
|
|
@@ -446,14 +578,16 @@ export async function main(argv, d) {
|
|
|
446
578
|
}
|
|
447
579
|
return 0;
|
|
448
580
|
}
|
|
581
|
+
/** The sync of the repository at `root`. */
|
|
582
|
+
export const syncDeps = (root) => ({
|
|
583
|
+
root,
|
|
584
|
+
pkg: PACKAGE,
|
|
585
|
+
settings: () => resolveFiles(filesDeps(root)),
|
|
586
|
+
stale: () => staleOf(defaultDeps(root)),
|
|
587
|
+
defaultBranch: (s) => defaultBranch(branchDeps(root, process.env, async () => s)),
|
|
588
|
+
out: (line) => console.log(line),
|
|
589
|
+
err: (line) => console.error(line),
|
|
590
|
+
});
|
|
449
591
|
export async function run(argv) {
|
|
450
|
-
|
|
451
|
-
return main(argv, {
|
|
452
|
-
root,
|
|
453
|
-
pkg: PACKAGE,
|
|
454
|
-
settings: () => loadSettings(defaultDeps(root)),
|
|
455
|
-
defaultBranch: () => defaultBranch(branchDeps(root)),
|
|
456
|
-
out: (line) => console.log(line),
|
|
457
|
-
err: (line) => console.error(line),
|
|
458
|
-
});
|
|
592
|
+
return main(argv, syncDeps(repoRoot()));
|
|
459
593
|
}
|
package/docs/builds.md
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
# Builds in the cloud
|
|
2
2
|
|
|
3
3
|
A build is one session taking one approved ticket to a pull request. You
|
|
4
|
-
can always build a ticket by
|
|
4
|
+
can always build a ticket by running `/factory-build N` in a session on
|
|
5
|
+
your machine. A build in
|
|
5
6
|
the cloud does the same with nobody at the keyboard: it runs on your code
|
|
6
7
|
host's cloud runner, and you read its log or its pull request afterward.
|
|
7
8
|
|
|
@@ -11,24 +12,24 @@ and the [reference](github/reference.md#workflows) has what runs there.
|
|
|
11
12
|
|
|
12
13
|
## Three ways a build starts
|
|
13
14
|
|
|
14
|
-
|
|
|
15
|
-
|
|
|
16
|
-
|
|
|
17
|
-
| Run `factory build 12`
|
|
18
|
-
| Move the ticket to Ready on a board
|
|
15
|
+
| What you do | Where the build runs | What you need |
|
|
16
|
+
| ------------------------------------ | --------------------------------------- | ----------------------------------------------------------------- |
|
|
17
|
+
| Run `/factory-build 12` in a session | In that session, wherever you opened it | Nothing |
|
|
18
|
+
| Run `factory build 12` | In the cloud | Builds in the cloud set up |
|
|
19
|
+
| Move the ticket to Ready on a board | In the cloud, at the poller's next pass | Builds in the cloud set up, and [the poller](#the-poller) running |
|
|
19
20
|
|
|
20
21
|
Which of the last two you use is
|
|
21
22
|
[`builds.trigger`](configuration.md#builds) in your
|
|
22
23
|
[settings](configuration.md#builds):
|
|
23
24
|
|
|
24
|
-
| `trigger` |
|
|
25
|
+
| `trigger` | What moving a ticket to Ready does |
|
|
25
26
|
| --------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
26
27
|
| `manual` | Records your approval and starts nothing. The default |
|
|
27
28
|
| `own-server` | Starts a build within a minute, through the poller you host |
|
|
28
29
|
| `github-action` | Starts one at the next pass of a schedule on the cloud runner, every `poll-minutes` minutes, with nothing to host |
|
|
29
30
|
|
|
30
|
-
`manual` is a fine place to stay.
|
|
31
|
-
`factory build` work whatever the trigger.
|
|
31
|
+
`manual` is a fine place to stay. Running `/factory-build N` in a session
|
|
32
|
+
and running `factory build N` work whatever the trigger.
|
|
32
33
|
|
|
33
34
|
## What a build in the cloud does
|
|
34
35
|
|
|
@@ -269,10 +270,10 @@ hour.
|
|
|
269
270
|
## No trigger: `manual`
|
|
270
271
|
|
|
271
272
|
Nothing watches the board. Moving a ticket to Ready records your approval
|
|
272
|
-
and starts nothing.
|
|
273
|
+
and starts nothing. In a session, type:
|
|
273
274
|
|
|
274
275
|
```text
|
|
275
|
-
build
|
|
276
|
+
/factory-build 12
|
|
276
277
|
```
|
|
277
278
|
|
|
278
279
|
The session claims the ticket, which moves it to "building" on the board,
|
package/docs/cli.md
CHANGED
|
@@ -21,8 +21,8 @@ A table with a State column has commands still to come, marked
|
|
|
21
21
|
**Planned**; every command in a table without one is built.
|
|
22
22
|
[What is built](developing.md#what-is-built) lists the parts.
|
|
23
23
|
|
|
24
|
-
The skills are not commands: you
|
|
25
|
-
such as
|
|
24
|
+
The skills are not `factory` commands: you type one in a session as a
|
|
25
|
+
slash command, such as `/factory-refine 12`. [Skills](skills.md) lists them.
|
|
26
26
|
|
|
27
27
|
## Setting up
|
|
28
28
|
|
|
@@ -55,19 +55,38 @@ 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 the
|
|
58
|
+
| `factory plugins` | To see the plugins the factory will use, by role | 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
|
|
64
|
-
included: its kind, its name, its [
|
|
65
|
-
files or labels. `factory plugins
|
|
63
|
+
`factory plugins` prints one line for each plugin, the factory's own
|
|
64
|
+
included: its kind, its name, its [role](plugins.md#the-roles), then its
|
|
65
|
+
files or labels. `factory plugins ROLE` prints one role's lines.
|
|
66
66
|
|
|
67
67
|
A new version is installed with npm and applied with `factory sync`, as
|
|
68
68
|
[Updating](updating.md) says. [Removing](removing.md) says what `remove`
|
|
69
69
|
deletes and what it leaves to you.
|
|
70
70
|
|
|
71
|
+
## Presets
|
|
72
|
+
|
|
73
|
+
A [preset](presets.md) is an npm package of settings that several
|
|
74
|
+
repositories share, listed under
|
|
75
|
+
[`presets`](configuration.md#presets).
|
|
76
|
+
|
|
77
|
+
| Command | When you run it |
|
|
78
|
+
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
79
|
+
| `factory preset add NAME` | To follow a preset. It shows what would change and asks before changing anything |
|
|
80
|
+
| `factory preset remove NAME` | To stop following one, the same way |
|
|
81
|
+
| `factory preset choices` | To see where two of your presets disagree, and choose which one this repository follows |
|
|
82
|
+
| `factory preset choose KEY PRESET` | To record one of those choices without questions, from a session or a script, as [Your choices](presets.md#your-choices) shows |
|
|
83
|
+
| `factory preset check` | In a preset's own package, before publishing it |
|
|
84
|
+
| `factory preset changes REF` | To see what the presets' update changed since `REF`, a git branch, tag, or commit such as `origin/main`. The [`factory-deps`](skills.md#factory-deps) skill posts it on each preset update |
|
|
85
|
+
|
|
86
|
+
`add` and `remove` ask only in a terminal. Elsewhere they print what would
|
|
87
|
+
change and stop, unless given `--yes`; `--dry-run` prints it and changes
|
|
88
|
+
nothing.
|
|
89
|
+
|
|
71
90
|
## Run for you
|
|
72
91
|
|
|
73
92
|
The rest are run by the skills, the hooks, and the workflows, not by you.
|
|
@@ -114,7 +133,7 @@ ticket system would swallow, name it, and post nothing.
|
|
|
114
133
|
`factory ticket refined N` posts nothing and exits 1 when N's body lacks a
|
|
115
134
|
section a build reads, printing one line for each, such as
|
|
116
135
|
`missing: ## Acceptance criteria`. With `--check` it prints `sound` for a
|
|
117
|
-
body that passes. [
|
|
136
|
+
body that passes. [Plugins](plugins.md#refiner) lists the sections.
|
|
118
137
|
|
|
119
138
|
### Pull requests
|
|
120
139
|
|
|
@@ -191,7 +210,7 @@ the commit hook blocks a session's git command with it.
|
|
|
191
210
|
| `factory merge-policy N` | The merge-policy workflow | Decides whether N may merge without you, and why | Built |
|
|
192
211
|
| `factory review verdict` | The review-verdict workflow | Posts the "Review verdict" status for a commit | Built |
|
|
193
212
|
| `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 [`
|
|
213
|
+
| `factory review tools` | The review workflow | Prints the tools the CI review may use, from [`pr-review.commands`](configuration.md#pr-review) | Built |
|
|
195
214
|
| `factory poller` | Your server | Starts a build for each Ready ticket. See [Builds](builds.md) | Built |
|
|
196
215
|
| `factory poller --once` | The scheduled poller's workflow | One pass of the poller, with the board and Ready column from your settings | Built |
|
|
197
216
|
| `factory guard` | A hook, before each command | Runs both guards below on one Bash call | Built |
|