@davidbyoung/software-factory 0.1.5 → 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 +12 -0
- package/dist/config.d.mts +57 -3
- package/dist/config.mjs +268 -18
- 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 +12 -1
- package/dist/explain.mjs +47 -32
- package/dist/init.mjs +6 -4
- package/dist/lib/default-branch.d.mts +1 -1
- package/dist/lib/default-branch.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/session-start.d.mts +3 -0
- package/dist/session-start.mjs +12 -1
- package/dist/sync.d.mts +42 -7
- package/dist/sync.mjs +165 -31
- package/docs/builds.md +12 -11
- package/docs/cli.md +21 -2
- package/docs/configuration.md +65 -13
- package/docs/developing.md +9 -2
- package/docs/github/by-hand.md +5 -5
- package/docs/github/reference.md +2 -17
- package/docs/github/setup.md +1 -1
- package/docs/glossary.md +12 -2
- package/docs/limitations.md +3 -0
- package/docs/plugins.md +16 -5
- package/docs/presets.md +410 -0
- package/docs/quick-start.md +20 -17
- package/docs/skills.md +21 -16
- package/docs/updating.md +14 -7
- package/docs/workflow.md +12 -13
- package/package.json +1 -1
- package/settings.schema.json +52 -3
- package/skills/factory-deps/SKILL.md +23 -12
- package/skills/factory-design/SKILL.md +1 -1
- package/skills/factory-resolve-conflicts/SKILL.md +6 -0
- package/workflows/factory-claude-review.yml +7 -2
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. */
|
|
@@ -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
|
|
|
@@ -68,6 +68,25 @@ 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.
|
package/docs/configuration.md
CHANGED
|
@@ -24,7 +24,8 @@ and look up any other setting under [Every setting](#every-setting).
|
|
|
24
24
|
that writes to the board.
|
|
25
25
|
- **`factory sync`:** a command you run. It copies the factory's skills,
|
|
26
26
|
agents, rules, and workflows into your repository, choosing which ones
|
|
27
|
-
from this file
|
|
27
|
+
from this file, and writes the settings in effect into
|
|
28
|
+
`.claude/factory.lock`. It has nothing to do with the board sync.
|
|
28
29
|
- **Skill and agent:** a skill is a set of instructions a session follows,
|
|
29
30
|
and an agent is a separate reviewer a session launches to read something
|
|
30
31
|
and report back.
|
|
@@ -64,6 +65,20 @@ The [glossary](glossary.md) has the rest.
|
|
|
64
65
|
|
|
65
66
|
- **Your comments are kept.** `factory init` writes a comment above each
|
|
66
67
|
section, and updates never remove yours.
|
|
68
|
+
- **Every command reads the lock, not this file.** `factory sync` combines
|
|
69
|
+
the factory's defaults, any [`presets`](#presets) you list, and this
|
|
70
|
+
file, and writes every setting the factory will use, defaults included,
|
|
71
|
+
into `.claude/factory.lock`, which you commit and never edit. Until you
|
|
72
|
+
sync after a change, every command stops and says so, but the ones that
|
|
73
|
+
fix or report it: `factory sync`, `factory doctor`,
|
|
74
|
+
`factory config check`, and the `factory preset` commands.
|
|
75
|
+
|
|
76
|
+
```text
|
|
77
|
+
.claude/factory.yaml changed since the last sync. Run: npx --no-install factory sync
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
[`factory config explain`](cli.md) prints the settings in effect, each
|
|
81
|
+
marked with where its value came from.
|
|
67
82
|
|
|
68
83
|
## The shortest file
|
|
69
84
|
|
|
@@ -72,7 +87,7 @@ version: 2
|
|
|
72
87
|
repository: your-name/your-repo
|
|
73
88
|
```
|
|
74
89
|
|
|
75
|
-
With only this, the factory refines a ticket when you
|
|
90
|
+
With only this, the factory refines a ticket when you run `/factory-refine N` in a session,
|
|
76
91
|
nothing merges without you, and there is no board. Before a session can
|
|
77
92
|
build a ticket, you also need to tell it how to check a change:
|
|
78
93
|
[`commands.gate`](#commandsgate), below.
|
|
@@ -101,10 +116,10 @@ factory sync
|
|
|
101
116
|
```
|
|
102
117
|
|
|
103
118
|
`factory config check` prints nothing when the file is valid, and names
|
|
104
|
-
the setting when it is not. `factory sync` then rewrites the
|
|
105
|
-
that depend on what you changed, and lists each file it
|
|
106
|
-
|
|
107
|
-
|
|
119
|
+
the setting when it is not. `factory sync` then rewrites the lock and the
|
|
120
|
+
copied files that depend on what you changed, and lists each file it
|
|
121
|
+
wrote. Every change needs it, one under `plugins` included, as
|
|
122
|
+
[How the file works](#how-the-file-works) says.
|
|
108
123
|
|
|
109
124
|
## Every setting
|
|
110
125
|
|
|
@@ -131,6 +146,29 @@ It is written down rather than worked out from your checkout, because the
|
|
|
131
146
|
[poller](#builds), which watches your board from outside any checkout,
|
|
132
147
|
needs it too.
|
|
133
148
|
|
|
149
|
+
### `presets`
|
|
150
|
+
|
|
151
|
+
Settings shared by several repositories, each an npm package your team
|
|
152
|
+
publishes, listed in the order they apply: a later preset wins over an
|
|
153
|
+
earlier one, and your own settings in this file win over every preset's.
|
|
154
|
+
|
|
155
|
+
```yaml
|
|
156
|
+
presets:
|
|
157
|
+
- "@acme/factory-preset" # what every Acme repository shares
|
|
158
|
+
- "@acme/factory-preset/node" # extra settings for its Node repositories
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
- **Default:** none.
|
|
162
|
+
- **Add or remove one** with `factory preset add NAME` or
|
|
163
|
+
`factory preset remove NAME`, which install or uninstall the package,
|
|
164
|
+
edit this list, and sync. A name that starts with `@` must be quoted.
|
|
165
|
+
- **A preset can't set** `repository`, `auto-merge.allow`, or
|
|
166
|
+
`auto-merge.commands`, and can't list other presets
|
|
167
|
+
([why](presets.md#what-a-preset-cant-set)).
|
|
168
|
+
|
|
169
|
+
[Presets](presets.md) says how they combine, how to choose between two
|
|
170
|
+
that disagree, and how to write one.
|
|
171
|
+
|
|
134
172
|
### `tickets`
|
|
135
173
|
|
|
136
174
|
Where your tickets live, and which board shows them.
|
|
@@ -149,7 +187,7 @@ tickets:
|
|
|
149
187
|
|
|
150
188
|
Without a board, `factory status` still shows every ticket's state, which
|
|
151
189
|
the factory keeps in comments on the ticket. Builds then start only when
|
|
152
|
-
you
|
|
190
|
+
you run `/factory-build N` in a session.
|
|
153
191
|
|
|
154
192
|
One board can show tickets from several repositories. Give each
|
|
155
193
|
repository the same `board`. Each repository's board sync,
|
|
@@ -278,8 +316,8 @@ builds:
|
|
|
278
316
|
|
|
279
317
|
The three triggers:
|
|
280
318
|
|
|
281
|
-
- **`manual`:** nothing watches the board. You
|
|
282
|
-
|
|
319
|
+
- **`manual`:** nothing watches the board. You build a ticket by running
|
|
320
|
+
`/factory-build 12` in a session.
|
|
283
321
|
- **`own-server`:** a small program you host, the poller, checks the board
|
|
284
322
|
once a minute and starts a cloud build for each ticket in Ready.
|
|
285
323
|
[Hosting the poller](builds.md#hosting-the-poller-own-server) shows how
|
|
@@ -583,7 +621,7 @@ session-minutes:
|
|
|
583
621
|
build: 300
|
|
584
622
|
```
|
|
585
623
|
|
|
586
|
-
| Setting |
|
|
624
|
+
| Setting | Limits the session that is | Default |
|
|
587
625
|
| -------------- | --------------------------------------------------------- | ------- |
|
|
588
626
|
| `build` | Building a ticket | `230` |
|
|
589
627
|
| `conflicts` | Fixing a pull request's conflicts with the default branch | `110` |
|
|
@@ -636,11 +674,25 @@ agent at `.claude/agents/NAME.md`:
|
|
|
636
674
|
- **`factory plugins`** prints every plugin the factory will use, its own
|
|
637
675
|
included, one per line: skill or agent, its name, its role, and its
|
|
638
676
|
files or labels. `factory plugins reviewer` prints one role's.
|
|
677
|
+
- **A plugin can come from a [preset](#presets),** which ships its agent
|
|
678
|
+
or skill too. To leave out one that a preset adds to a list, name it
|
|
679
|
+
here with `off: true`:
|
|
680
|
+
|
|
681
|
+
```yaml
|
|
682
|
+
plugins:
|
|
683
|
+
build:
|
|
684
|
+
reviewers:
|
|
685
|
+
- agent: acme-security-reviewer
|
|
686
|
+
off: true
|
|
687
|
+
```
|
|
688
|
+
|
|
639
689
|
- **`factory config check`** stops on an agent in a role that takes a
|
|
640
690
|
skill, or the other way round; on `files` or `labels` in a role that
|
|
641
691
|
doesn't take them; on a builder with no `labels`; on a build reviewer or
|
|
642
|
-
resolver with no `files`;
|
|
643
|
-
exist
|
|
692
|
+
resolver with no `files`; on a skill or agent whose file doesn't
|
|
693
|
+
exist and no preset ships; and on `off: true` for a plugin no preset
|
|
694
|
+
names, where the fix is to delete that entry. It warns on a `files`
|
|
695
|
+
pattern that matches no file.
|
|
644
696
|
|
|
645
697
|
#### `plugins.refine`
|
|
646
698
|
|
|
@@ -845,7 +897,7 @@ you. Each line it prints is shown as a reason.
|
|
|
845
897
|
What a held pull request says, one line for each file or command that held
|
|
846
898
|
it:
|
|
847
899
|
|
|
848
|
-
|
|
|
900
|
+
| The status says | Why |
|
|
849
901
|
| -------------------------------------- | ----------------------------------------------- |
|
|
850
902
|
| `PATH: the factory's own files` | The file is one of the factory's, listed above |
|
|
851
903
|
| `PATH: held by auto-merge.deny` | The file matches `deny` |
|
package/docs/developing.md
CHANGED
|
@@ -509,7 +509,10 @@ this repository's own reviewer, reads a changed page as that person.
|
|
|
509
509
|
- **A page says who it is for and what they will have at the end,** in its
|
|
510
510
|
first lines.
|
|
511
511
|
- **Lead with the command that does it.** The same steps by hand go on a
|
|
512
|
-
page of their own, linked once.
|
|
512
|
+
page of their own, linked once. A step that runs a skill shows its slash
|
|
513
|
+
command, such as `/factory-refine 12`, not only words to say to a
|
|
514
|
+
session: words leave the session to pick the skill, and leave the reader
|
|
515
|
+
not knowing which one ran.
|
|
513
516
|
- **Say only what the reader must do or decide.** What a command does for
|
|
514
517
|
them is one sentence, and a link to the page that lists it.
|
|
515
518
|
- **A setting links to its entry in `docs/configuration.md` where a page
|
|
@@ -522,4 +525,8 @@ this repository's own reviewer, reads a changed page as that person.
|
|
|
522
525
|
person doing each thing, and an example where the rule is abstract. A
|
|
523
526
|
word the factory gives its own meaning, such as "the sync" or "a
|
|
524
527
|
session", is explained or linked where the page first uses it. A table
|
|
525
|
-
cell reads as part of a sentence, and no column repeats another.
|
|
528
|
+
cell reads as part of a sentence, and no column repeats another. A
|
|
529
|
+
column header names what its cells hold, such as "What it does" or
|
|
530
|
+
"Without one", and reads on its own: not a pronoun or a clipped phrase,
|
|
531
|
+
such as "It" or "Left out", that makes sense only once a cell is read
|
|
532
|
+
into it.
|
package/docs/github/by-hand.md
CHANGED
|
@@ -186,12 +186,12 @@ prints the run's link, with no session open on your machine.
|
|
|
186
186
|
`sync` already wrote the workflows these use, and each does nothing until
|
|
187
187
|
it has work and its secrets:
|
|
188
188
|
|
|
189
|
-
| Workflow |
|
|
189
|
+
| Workflow | What its Claude Code session does |
|
|
190
190
|
| ----------------------- | ------------------------------------------------------------------------------------ |
|
|
191
|
-
| `factory-build.yml` |
|
|
192
|
-
| `factory-review.yml` |
|
|
193
|
-
| `factory-conflicts.yml` |
|
|
194
|
-
| `factory-deps.yml` |
|
|
191
|
+
| `factory-build.yml` | Builds a ticket |
|
|
192
|
+
| `factory-review.yml` | Answers a review you submit on a pull request |
|
|
193
|
+
| `factory-conflicts.yml` | Resolves a conflict between a pull request and your default branch |
|
|
194
|
+
| `factory-deps.yml` | Moves Dependabot's pull requests along, written once `.github/dependabot.yml` exists |
|
|
195
195
|
|
|
196
196
|
1. **Store your Claude token** as `CLAUDE_CODE_OAUTH_TOKEN`.
|
|
197
197
|
2. **Store a GitHub token that can push**, as `FACTORY_BUILD_TOKEN`. With
|
package/docs/github/reference.md
CHANGED
|
@@ -187,23 +187,8 @@ you set yourself alone.
|
|
|
187
187
|
|
|
188
188
|
## Skills in Claude Code
|
|
189
189
|
|
|
190
|
-
In Claude Code
|
|
191
|
-
|
|
192
|
-
calls the same skill.
|
|
193
|
-
|
|
194
|
-
| Type | Same as asking |
|
|
195
|
-
| -------------------------------- | ---------------------------------- |
|
|
196
|
-
| `/factory-refine 12` | "refine ticket 12" |
|
|
197
|
-
| `/factory-build 12` | "build ticket 12" |
|
|
198
|
-
| `/factory-address-review 280` | "address the review on 280" |
|
|
199
|
-
| `/factory-resolve-conflicts 280` | "resolve the conflicts on 280" |
|
|
200
|
-
| `/factory-diagnose` | "diagnose this failing test" |
|
|
201
|
-
| `/factory-mutate` | "mutate this test" |
|
|
202
|
-
| `/factory-deps` | "fix the dependency pull requests" |
|
|
203
|
-
| `/factory-design` | "mock up a new about page" |
|
|
204
|
-
|
|
205
|
-
Typing `/factory` in a session lists them, which is also how to check that
|
|
206
|
-
a session picked the factory up.
|
|
190
|
+
In Claude Code each skill is a slash command, such as `/factory-refine 12`.
|
|
191
|
+
[Skills](../skills.md#at-a-glance) lists every one with what it does.
|
|
207
192
|
|
|
208
193
|
**Where the files live.** `sync` writes the factory's skills to
|
|
209
194
|
`.claude/skills/factory-*/` and its agents to
|