@davidbyoung/software-factory 0.1.9 → 0.1.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/agents/factory-ticket-readiness.md +20 -15
- package/dist/board.d.mts +1 -1
- package/dist/board.mjs +4 -7
- package/dist/cli.mjs +23 -1
- package/dist/code-host/github.d.mts +1 -1
- package/dist/code-host/github.mjs +31 -2
- package/dist/code-host/types.d.mts +20 -1
- package/dist/code-host/types.mjs +8 -0
- package/dist/columns-suggest.d.mts +25 -5
- package/dist/columns-suggest.mjs +117 -21
- package/dist/commands.d.mts +8 -2
- package/dist/commands.mjs +92 -8
- package/dist/config.d.mts +19 -7
- package/dist/config.mjs +109 -30
- package/dist/doctor.mjs +1 -2
- package/dist/explain.mjs +7 -1
- package/dist/init.d.mts +19 -0
- package/dist/init.mjs +139 -23
- package/dist/lib/gh.d.mts +6 -0
- package/dist/lib/gh.mjs +11 -1
- package/dist/lib/listed.d.mts +3 -2
- package/dist/lib/listed.mjs +5 -4
- package/dist/lib/work-status.d.mts +5 -5
- package/dist/lib/work-status.mjs +7 -8
- package/dist/merge-policy.mjs +7 -3
- package/dist/poller.d.mts +1 -1
- package/dist/poller.mjs +9 -6
- package/dist/pr.d.mts +8 -6
- package/dist/pr.mjs +47 -22
- package/dist/review-verdict.d.mts +22 -4
- package/dist/review-verdict.mjs +55 -17
- package/dist/specs/index.d.mts +6 -0
- package/dist/specs/index.mjs +15 -0
- package/dist/specs/openspec.d.mts +2 -0
- package/dist/specs/openspec.mjs +78 -0
- package/dist/specs/types.d.mts +53 -0
- package/dist/specs/types.mjs +4 -0
- package/dist/ticket.d.mts +6 -1
- package/dist/ticket.mjs +62 -3
- package/dist/tickets/github-access.d.mts +5 -0
- package/dist/tickets/github-access.mjs +22 -0
- package/dist/tickets/github.mjs +2 -0
- package/dist/tickets/types.d.mts +4 -0
- package/dist/tool-names.d.mts +2 -0
- package/dist/tool-names.mjs +3 -0
- package/dist/tools.d.mts +2 -0
- package/dist/tools.mjs +3 -0
- package/docs/builds.md +30 -14
- package/docs/cli.md +48 -30
- package/docs/configuration.md +237 -73
- package/docs/developing.md +104 -59
- package/docs/existing-repo.md +51 -29
- package/docs/github/by-hand.md +13 -1
- package/docs/github/setup.md +26 -2
- package/docs/glossary.md +7 -6
- package/docs/limitations.md +8 -5
- package/docs/presets.md +15 -3
- package/docs/updating.md +147 -2
- package/docs/workflow.md +26 -9
- package/package.json +1 -1
- package/rules.md +36 -30
- package/settings.schema.json +14 -9
- package/skills/factory-address-review/SKILL.md +40 -39
- package/skills/factory-build/SKILL.md +77 -52
- package/skills/factory-deps/SKILL.md +6 -4
- package/skills/factory-refine/SKILL.md +30 -22
- package/skills/factory-resolve-conflicts/SKILL.md +8 -7
package/dist/commands.mjs
CHANGED
|
@@ -6,18 +6,30 @@
|
|
|
6
6
|
// factory end-to-end FILE [--times K] # commands.end-to-end, K times in a row
|
|
7
7
|
// factory specs check # specs.check
|
|
8
8
|
//
|
|
9
|
+
// and the commands that reach the spec tool `specs` names:
|
|
10
|
+
//
|
|
11
|
+
// factory specs list # each spec it keeps
|
|
12
|
+
// factory specs new N # start ticket N's spec
|
|
13
|
+
// factory specs finish N # fold ticket N's spec in
|
|
14
|
+
//
|
|
9
15
|
// Each command runs with bash from the repository's root, with its output
|
|
10
16
|
// passed through and no standard input. `test-one` gets FILE and NAME in its
|
|
11
|
-
// environment, `end-to-end` FILE, and the spec check
|
|
12
|
-
// argument a command does not know prints its usage and
|
|
17
|
+
// environment, `end-to-end` FILE, and the spec check the spec tool's
|
|
18
|
+
// environment. An argument a command does not know prints its usage and
|
|
19
|
+
// exits 2.
|
|
13
20
|
import { spawnSync } from "node:child_process";
|
|
14
21
|
import { colorOn, painter, plain } from "./lib/color.mjs";
|
|
15
22
|
import { defaultDeps, loadSettings, repoRoot, SETTINGS_FILE, SettingsError, } from "./config.mjs";
|
|
23
|
+
import { specTools } from "./specs/index.mjs";
|
|
24
|
+
import { openTickets } from "./tickets/index.mjs";
|
|
16
25
|
const USAGE = {
|
|
17
26
|
gate: "Usage: factory gate",
|
|
18
27
|
"test-one": "Usage: factory test-one FILE [NAME]",
|
|
19
28
|
"end-to-end": "Usage: factory end-to-end FILE [--times K]",
|
|
20
29
|
"specs-check": "Usage: factory specs check",
|
|
30
|
+
"specs-list": "Usage: factory specs list",
|
|
31
|
+
"specs-new": "Usage: factory specs new N",
|
|
32
|
+
"specs-finish": "Usage: factory specs finish N",
|
|
21
33
|
};
|
|
22
34
|
/** What `factory end-to-end` was asked: the file, and how many runs when
|
|
23
35
|
* `--times` is given; null when the arguments are not ones it knows. */
|
|
@@ -46,10 +58,16 @@ export async function main(argv, d) {
|
|
|
46
58
|
return 2;
|
|
47
59
|
};
|
|
48
60
|
const e2e = name === "end-to-end" ? endToEndArgs(args) : null;
|
|
49
|
-
if (name === "gate" || name === "specs-check") {
|
|
61
|
+
if (name === "gate" || name === "specs-check" || name === "specs-list") {
|
|
50
62
|
if (args.length > 0)
|
|
51
63
|
return usage();
|
|
52
64
|
}
|
|
65
|
+
else if (name === "specs-new" || name === "specs-finish") {
|
|
66
|
+
// A ticket as the ticket system writes it: GitHub's, the only one
|
|
67
|
+
// built, are whole numbers.
|
|
68
|
+
if (args.length !== 1 || !/^[1-9]\d*$/.test(args[0]))
|
|
69
|
+
return usage();
|
|
70
|
+
}
|
|
53
71
|
else if (name === "test-one") {
|
|
54
72
|
if (args.length < 1 || args.length > 2)
|
|
55
73
|
return usage();
|
|
@@ -114,14 +132,72 @@ export async function main(argv, d) {
|
|
|
114
132
|
}
|
|
115
133
|
return test(0);
|
|
116
134
|
}
|
|
117
|
-
|
|
118
|
-
|
|
135
|
+
const tool = d.specTools[s.specs];
|
|
136
|
+
if (s.specs === "none" || !tool) {
|
|
137
|
+
d.out(`${paint("dim", "-")} ${NO_SPEC_TOOL}`);
|
|
138
|
+
return 0;
|
|
139
|
+
}
|
|
140
|
+
if (name === "specs-check")
|
|
141
|
+
return ended(d.exec(s.specCheck, d.root, tool.env), "The specs check passed.", "The specs check failed.");
|
|
142
|
+
if (name === "specs-list") {
|
|
143
|
+
const specs = tool.list(d.root);
|
|
144
|
+
d.out(`specs: ${s.specs}`);
|
|
145
|
+
if (specs.length === 0)
|
|
146
|
+
d.out(" none yet");
|
|
147
|
+
const width = Math.max(0, ...specs.map((x) => x.name.length));
|
|
148
|
+
for (const x of specs)
|
|
149
|
+
d.out(` ${x.name.padEnd(width)} ${x.path}`);
|
|
150
|
+
return 0;
|
|
151
|
+
}
|
|
152
|
+
const id = args[0];
|
|
153
|
+
const failed = (line) => {
|
|
154
|
+
d.err(`${paint("red", "✗")} ${line}`);
|
|
155
|
+
return 1;
|
|
156
|
+
};
|
|
157
|
+
if (name === "specs-finish") {
|
|
158
|
+
if (!tool.started(d.root, id)) {
|
|
159
|
+
if (tool.finished(d.root, id)) {
|
|
160
|
+
d.out(`${paint("green", "✓")} Ticket ${id}'s spec is already folded into ${tool.foldsInto}.`);
|
|
161
|
+
return 0;
|
|
162
|
+
}
|
|
163
|
+
return failed(`Ticket ${id} has no spec started: run factory specs new ${id} first.`);
|
|
164
|
+
}
|
|
165
|
+
if (tool.finish(d.root, id) !== 0)
|
|
166
|
+
return failed(`Could not fold ticket ${id}'s spec into ${tool.foldsInto}.`);
|
|
167
|
+
d.out(`${paint("green", "✓")} Folded ticket ${id}'s spec into ${tool.foldsInto}.`);
|
|
119
168
|
return 0;
|
|
120
169
|
}
|
|
121
|
-
|
|
170
|
+
let labels;
|
|
171
|
+
try {
|
|
172
|
+
labels = await d.labels(s, Number(id));
|
|
173
|
+
}
|
|
174
|
+
catch (e) {
|
|
175
|
+
d.err(e instanceof Error ? e.message : String(e));
|
|
176
|
+
return 1;
|
|
177
|
+
}
|
|
178
|
+
if (!tool.runs(d.root))
|
|
179
|
+
return failed(`${tool.name} is not installed: run factory init, which installs it.`);
|
|
180
|
+
const folder = tool.folder(id);
|
|
181
|
+
if (tool.started(d.root, id))
|
|
182
|
+
d.out(`Ticket ${id}'s spec is already started in ${folder}`);
|
|
183
|
+
else {
|
|
184
|
+
if (tool.start(d.root, id) !== 0)
|
|
185
|
+
return failed(`Could not start ticket ${id}'s spec in ${folder}`);
|
|
186
|
+
d.out(`Started ticket ${id}'s spec in ${folder}`);
|
|
187
|
+
}
|
|
188
|
+
const files = tool.files(id, labels.includes("spec"));
|
|
189
|
+
const width = Math.max(...files.map((f) => f.path.length)) + 2;
|
|
190
|
+
const kinds = Math.max(...files.map((f) => f.kind.length));
|
|
191
|
+
d.out(`Write each file from ticket ${id}'s body:`);
|
|
192
|
+
for (const f of files)
|
|
193
|
+
d.out(` ${f.kind.padEnd(kinds)} ${f.path.padEnd(width)}${f.what}`);
|
|
194
|
+
d.out(`Then: ${tool.then}`);
|
|
195
|
+
return 0;
|
|
122
196
|
}
|
|
123
|
-
|
|
124
|
-
|
|
197
|
+
export const NO_SPEC_TOOL = "No spec tool (specs: none): each ticket holds its own spec.";
|
|
198
|
+
/** `factory gate`, `factory test-one`, `factory end-to-end`,
|
|
199
|
+
* and `factory specs check`, `list`, `new`, and `finish`, as `specs-check`
|
|
200
|
+
* and the rest. */
|
|
125
201
|
export async function run(argv) {
|
|
126
202
|
const root = repoRoot();
|
|
127
203
|
return main(argv, {
|
|
@@ -136,5 +212,13 @@ export async function run(argv) {
|
|
|
136
212
|
out: (line) => console.log(line),
|
|
137
213
|
err: (line) => console.error(line),
|
|
138
214
|
paint: painter(colorOn()),
|
|
215
|
+
specTools: specTools(),
|
|
216
|
+
labels: async (settings, id) => {
|
|
217
|
+
const { tickets } = await openTickets(settings, {
|
|
218
|
+
repository: settings.repository,
|
|
219
|
+
board: null,
|
|
220
|
+
});
|
|
221
|
+
return (await tickets.read(id)).labels;
|
|
222
|
+
},
|
|
139
223
|
});
|
|
140
224
|
}
|
package/dist/config.d.mts
CHANGED
|
@@ -26,7 +26,8 @@ export declare const TRIGGERS: readonly ["own-server", "github-action", "manual"
|
|
|
26
26
|
/** How often the scheduled poller may check the board, in minutes: each
|
|
27
27
|
* divides an hour, so a schedule every N minutes keeps an even beat. */
|
|
28
28
|
export declare const POLL_MINUTES: readonly [5, 10, 15, 30, 60];
|
|
29
|
-
|
|
29
|
+
/** The values `specs` takes: none, or a spec tool built. */
|
|
30
|
+
export declare const SPECS: string[];
|
|
30
31
|
declare const FIELD_DEFAULTS: {
|
|
31
32
|
readonly session: "Session";
|
|
32
33
|
readonly "runs-in": "Runs in";
|
|
@@ -59,9 +60,12 @@ export type Settings = {
|
|
|
59
60
|
* field that holds it, or null for the description. */
|
|
60
61
|
ticketFields: FieldMapping;
|
|
61
62
|
};
|
|
62
|
-
/** Where pull requests are
|
|
63
|
+
/** Where pull requests are, and the pattern a build's branch is named
|
|
64
|
+
* by. The pattern is null only when init reads settings without it, to
|
|
65
|
+
* ask for it. */
|
|
63
66
|
codeHost: {
|
|
64
67
|
type: string;
|
|
68
|
+
branchName: string | null;
|
|
65
69
|
};
|
|
66
70
|
builds: {
|
|
67
71
|
/** What notices a card moved to Ready and starts its build. */
|
|
@@ -71,7 +75,7 @@ export type Settings = {
|
|
|
71
75
|
/** How often the scheduled poller checks the board. */
|
|
72
76
|
pollMinutes: (typeof POLL_MINUTES)[number];
|
|
73
77
|
};
|
|
74
|
-
specs:
|
|
78
|
+
specs: string;
|
|
75
79
|
/** The command that checks the specs, or null when `specs` is none. */
|
|
76
80
|
specCheck: string | null;
|
|
77
81
|
/** Every command a build runs, each from the repository's root. */
|
|
@@ -157,8 +161,6 @@ export type Accessibility = (typeof ACCESSIBILITY)[number];
|
|
|
157
161
|
export declare const SITE_AGENT = "factory-ui-reviewer";
|
|
158
162
|
/** The agent that needs `commands.end-to-end`. */
|
|
159
163
|
export declare const E2E_AGENT = "factory-e2e-reviewer";
|
|
160
|
-
/** The spec check where `specs.type` is openspec and none is written. */
|
|
161
|
-
export declare const OPENSPEC_CHECK = "npx --no-install openspec validate --all --strict --no-interactive";
|
|
162
164
|
/** `commands.relock` where none is written. */
|
|
163
165
|
export declare const DEFAULT_RELOCK = "npm install";
|
|
164
166
|
export declare const NO_PLAYWRIGHT = "site needs Playwright: npm install -D playwright";
|
|
@@ -175,10 +177,18 @@ export declare function repoRoot(from?: string): string;
|
|
|
175
177
|
export declare const SETTINGS_FILE = ".claude/factory.yaml";
|
|
176
178
|
/** A key under `tickets.fields` naming a heading of the repository's own. */
|
|
177
179
|
export declare const OWN_HEADING: RegExp;
|
|
180
|
+
export declare const BRANCH_PLACEHOLDERS: readonly ["ticket", "user"];
|
|
181
|
+
/** Why a branch name pattern can't be used, in the words the settings
|
|
182
|
+
* check prints after its key, or null when it can. The placeholders are
|
|
183
|
+
* filled before git's rules are applied, so only the pattern's own text
|
|
184
|
+
* can break them. */
|
|
185
|
+
export declare function branchPatternFault(pattern: string): string | null;
|
|
178
186
|
/** The settings with every default filled in. Throws a SettingsError naming
|
|
179
187
|
* the key on anything unsound. `exists` says whether a path from the root
|
|
180
188
|
* exists, for the plugins' files. */
|
|
181
|
-
export declare function parseSettings(raw: unknown, exists: (path: string) => boolean, built?: Built
|
|
189
|
+
export declare function parseSettings(raw: unknown, exists: (path: string) => boolean, built?: Built, { partial }?: {
|
|
190
|
+
partial?: boolean;
|
|
191
|
+
}): Settings;
|
|
182
192
|
/** One line for each pattern that matches none of `files`: a stale pattern
|
|
183
193
|
* is how a policy rots. */
|
|
184
194
|
export declare function patternWarnings(s: Settings, files: string[]): string[];
|
|
@@ -235,9 +245,11 @@ export declare function parseChoices(text: string | null, load: YamlLoad): Recor
|
|
|
235
245
|
* `presets`, and `.claude/factory.yaml`, as `factory sync` combines them
|
|
236
246
|
* into the lock. `factoryFile` and `ownFile` say which preset files are
|
|
237
247
|
* kept back: the factory's own, and the repository's own. */
|
|
238
|
-
export declare function resolveFiles(d: Deps, keep?: {
|
|
248
|
+
export declare function resolveFiles(d: Deps, { partial, ...keep }?: {
|
|
239
249
|
factoryFile?: (path: string) => boolean;
|
|
240
250
|
ownFile?: (path: string) => boolean;
|
|
251
|
+
/** Read settings init fills in, as `parseSettings` takes it. */
|
|
252
|
+
partial?: boolean;
|
|
241
253
|
}): Promise<Resolved>;
|
|
242
254
|
/** Why the lock `d` reads is stale, or null when it is current or `d`
|
|
243
255
|
* reads none. */
|
package/dist/config.mjs
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
//
|
|
6
6
|
// factory config get KEY # e.g. repository, tickets.board
|
|
7
7
|
// factory plugins [ROLE] # kind, name, role, files or labels
|
|
8
|
-
// factory config check #
|
|
8
|
+
// factory config check # ✓ The settings are valid., or what is wrong
|
|
9
9
|
//
|
|
10
10
|
// A list prints one item per line. A failure names the key and exits 1.
|
|
11
11
|
import { colorOn, painter, plain } from "./lib/color.mjs";
|
|
@@ -15,6 +15,7 @@ import { createRequire } from "node:module";
|
|
|
15
15
|
import { dirname, join } from "node:path";
|
|
16
16
|
import { DEFAULT_CODE_HOST, unsupportedCodeHost } from "./code-host/index.mjs";
|
|
17
17
|
import { matchesAny } from "./lib/glob.mjs";
|
|
18
|
+
import { listed } from "./lib/listed.mjs";
|
|
18
19
|
import { DEFAULT_RUNNER, unsupportedRunner } from "./runner/index.mjs";
|
|
19
20
|
import { FACTORY_FIELDS } from "./ticket-fields.mjs";
|
|
20
21
|
import { BUILT, unsupported } from "./tool-names.mjs";
|
|
@@ -90,7 +91,8 @@ export const TRIGGERS = ["own-server", "github-action", "manual"];
|
|
|
90
91
|
/** How often the scheduled poller may check the board, in minutes: each
|
|
91
92
|
* divides an hour, so a schedule every N minutes keeps an even beat. */
|
|
92
93
|
export const POLL_MINUTES = [5, 10, 15, 30, 60];
|
|
93
|
-
|
|
94
|
+
/** The values `specs` takes: none, or a spec tool built. */
|
|
95
|
+
export const SPECS = ["none", ...Object.keys(BUILT.specs)];
|
|
94
96
|
const FIELD_DEFAULTS = {
|
|
95
97
|
session: "Session",
|
|
96
98
|
"runs-in": "Runs in",
|
|
@@ -118,8 +120,6 @@ export const ACCESSIBILITY = [
|
|
|
118
120
|
export const SITE_AGENT = "factory-ui-reviewer";
|
|
119
121
|
/** The agent that needs `commands.end-to-end`. */
|
|
120
122
|
export const E2E_AGENT = "factory-e2e-reviewer";
|
|
121
|
-
/** The spec check where `specs.type` is openspec and none is written. */
|
|
122
|
-
export const OPENSPEC_CHECK = "npx --no-install openspec validate --all --strict --no-interactive";
|
|
123
123
|
/** `commands.relock` where none is written. */
|
|
124
124
|
export const DEFAULT_RELOCK = "npm install";
|
|
125
125
|
export const NO_PLAYWRIGHT = "site needs Playwright: npm install -D playwright";
|
|
@@ -150,7 +150,7 @@ export const SETTINGS_KEYS = {
|
|
|
150
150
|
...Object.keys(FIELD_DEFAULTS),
|
|
151
151
|
...FACTORY_FIELDS.map((f) => f.key),
|
|
152
152
|
],
|
|
153
|
-
"code-host": ["type"],
|
|
153
|
+
"code-host": ["type", "branch-name"],
|
|
154
154
|
builds: ["trigger", "runner", "poll-minutes"],
|
|
155
155
|
specs: ["type", "check"],
|
|
156
156
|
commands: [
|
|
@@ -347,13 +347,31 @@ function ticketFieldsOf(o) {
|
|
|
347
347
|
}
|
|
348
348
|
return out;
|
|
349
349
|
}
|
|
350
|
-
/** Each state's columns: a name, a list of names, or none
|
|
351
|
-
*
|
|
352
|
-
*
|
|
353
|
-
|
|
354
|
-
|
|
350
|
+
/** Each state's columns: a name, a list of names, or none. With a board,
|
|
351
|
+
* every state is written, since the factory's own names describe one
|
|
352
|
+
* board and a state left to them would read any other wrong. Without one,
|
|
353
|
+
* each state keeps its own name, for the comments and `factory status`.
|
|
354
|
+
* `partial` lets a board's block leave states out, each read as no column
|
|
355
|
+
* and listed in `missing`, for init alone, which fills them in. Only an
|
|
356
|
+
* approved ticket goes to ready, so it takes one name. */
|
|
357
|
+
function columnNames(v, board, partial) {
|
|
358
|
+
const states = Object.entries(STATE_KEYS);
|
|
359
|
+
if (board === null)
|
|
360
|
+
return {
|
|
361
|
+
columns: Object.fromEntries(states.map(([k, status]) => [k, DEFAULT_COLUMNS[status]])),
|
|
362
|
+
missing: [],
|
|
363
|
+
};
|
|
364
|
+
const empty = v === undefined || v === null || (isObj(v) && !Object.keys(v).length);
|
|
365
|
+
if (empty && !partial)
|
|
366
|
+
fail("tickets.columns", `is required with tickets.board: run factory init to choose which of board ${board}'s columns shows each state`);
|
|
367
|
+
const o = empty ? {} : object(v, "tickets.columns");
|
|
368
|
+
const missing = states.map(([k]) => k).filter((k) => o[k] === undefined);
|
|
369
|
+
if (missing.length && !partial)
|
|
370
|
+
fail("tickets.columns", missing.length === 1
|
|
371
|
+
? `${missing[0]} has no column: give it a column, a list of columns, or none, or run factory init to choose it`
|
|
372
|
+
: `${listed(missing)} have no column: give each a column, a list of columns, or none, or run factory init to choose them`);
|
|
355
373
|
const out = {};
|
|
356
|
-
for (const [k
|
|
374
|
+
for (const [k] of states) {
|
|
357
375
|
const key = `tickets.columns.${k}`;
|
|
358
376
|
const value = o[k];
|
|
359
377
|
if (Array.isArray(value)) {
|
|
@@ -366,7 +384,7 @@ function columnNames(v) {
|
|
|
366
384
|
: fail(`${key}[${i}]`, "must be a name"));
|
|
367
385
|
}
|
|
368
386
|
else if (value === undefined)
|
|
369
|
-
out[k] =
|
|
387
|
+
out[k] = null;
|
|
370
388
|
else if (value === "none")
|
|
371
389
|
out[k] = null;
|
|
372
390
|
else if (typeof value === "string" && value.trim())
|
|
@@ -374,7 +392,62 @@ function columnNames(v) {
|
|
|
374
392
|
else
|
|
375
393
|
fail(key, "must be a name, a list of names, or none");
|
|
376
394
|
}
|
|
377
|
-
return out;
|
|
395
|
+
return { columns: out, missing };
|
|
396
|
+
}
|
|
397
|
+
export const BRANCH_PLACEHOLDERS = ["ticket", "user"];
|
|
398
|
+
const QUOTED_EXAMPLE = 'branch-name: "{ticket}"';
|
|
399
|
+
/** The pattern a build's branch is named by, or null when it is left out
|
|
400
|
+
* and `partial` lets it be, for init to ask for. */
|
|
401
|
+
function branchNameOf(v, partial) {
|
|
402
|
+
const key = "code-host.branch-name";
|
|
403
|
+
if (v === undefined || v === null) {
|
|
404
|
+
if (partial)
|
|
405
|
+
return null;
|
|
406
|
+
return fail(key, `is required. Run factory init to set it, or add it, such as ${QUOTED_EXAMPLE}`);
|
|
407
|
+
}
|
|
408
|
+
if (isObj(v))
|
|
409
|
+
return fail(key, `is a map, not a pattern. Quote it: ${QUOTED_EXAMPLE}`);
|
|
410
|
+
if (typeof v !== "string")
|
|
411
|
+
return fail(key, `must be a pattern, such as ${QUOTED_EXAMPLE}`);
|
|
412
|
+
const fault = branchPatternFault(v);
|
|
413
|
+
return fault ? fail(key, fault) : v;
|
|
414
|
+
}
|
|
415
|
+
/** Why a branch name pattern can't be used, in the words the settings
|
|
416
|
+
* check prints after its key, or null when it can. The placeholders are
|
|
417
|
+
* filled before git's rules are applied, so only the pattern's own text
|
|
418
|
+
* can break them. */
|
|
419
|
+
export function branchPatternFault(pattern) {
|
|
420
|
+
for (const [, name] of pattern.matchAll(/\{([A-Za-z0-9-]+)\}/g))
|
|
421
|
+
if (!BRANCH_PLACEHOLDERS.includes(name))
|
|
422
|
+
return `{${name}} is not a placeholder. The placeholders are ${listed(BRANCH_PLACEHOLDERS.map((p) => `{${p}}`))}`;
|
|
423
|
+
if (!pattern.includes("{ticket}"))
|
|
424
|
+
return "needs {ticket}, or every build gets the same branch";
|
|
425
|
+
const reason = gitBranchFault(pattern.replaceAll("{ticket}", "1").replaceAll("{user}", "u"));
|
|
426
|
+
return reason && `${pattern} can't be a git branch name: ${reason}`;
|
|
427
|
+
}
|
|
428
|
+
/** The first of git's rules for a branch name (`git check-ref-format
|
|
429
|
+
* --branch`) that `name` breaks, or null. */
|
|
430
|
+
function gitBranchFault(name) {
|
|
431
|
+
if (name.includes(" "))
|
|
432
|
+
return "it has a space";
|
|
433
|
+
// eslint-disable-next-line no-control-regex
|
|
434
|
+
if (/[\x00-\x1f\x7f]/.test(name))
|
|
435
|
+
return "it has a control character";
|
|
436
|
+
for (const s of ["..", "//", "@{", "~", "^", ":", "?", "*", "[", "\\"])
|
|
437
|
+
if (name.includes(s))
|
|
438
|
+
return `it has ${s}`;
|
|
439
|
+
for (const s of ["-", "/"])
|
|
440
|
+
if (name.startsWith(s))
|
|
441
|
+
return `it starts with ${s}`;
|
|
442
|
+
for (const s of ["/", ".lock", "."])
|
|
443
|
+
if (name.endsWith(s))
|
|
444
|
+
return `it ends with ${s}`;
|
|
445
|
+
const parts = name.split("/");
|
|
446
|
+
if (parts.some((p) => p.startsWith(".")))
|
|
447
|
+
return "a part starts with .";
|
|
448
|
+
if (parts.some((p) => p.endsWith(".lock")))
|
|
449
|
+
return "a part ends with .lock";
|
|
450
|
+
return null;
|
|
378
451
|
}
|
|
379
452
|
/** A part you can swap, written as a block with a `type` or as one word. */
|
|
380
453
|
function typed(v, key, extra) {
|
|
@@ -482,7 +555,7 @@ function commandsOf(v) {
|
|
|
482
555
|
/** The settings with every default filled in. Throws a SettingsError naming
|
|
483
556
|
* the key on anything unsound. `exists` says whether a path from the root
|
|
484
557
|
* exists, for the plugins' files. */
|
|
485
|
-
export function parseSettings(raw, exists, built = BUILT) {
|
|
558
|
+
export function parseSettings(raw, exists, built = BUILT, { partial = false } = {}) {
|
|
486
559
|
const written = raw ?? {};
|
|
487
560
|
// The version comes before any other key, so a file in the older shape is
|
|
488
561
|
// told so, not told its keys are unknown.
|
|
@@ -522,9 +595,11 @@ export function parseSettings(raw, exists, built = BUILT) {
|
|
|
522
595
|
board !== "none" &&
|
|
523
596
|
!(Number.isInteger(board) && board > 0))
|
|
524
597
|
fail("tickets.board", "must be a whole number above zero, or none");
|
|
525
|
-
const
|
|
598
|
+
const codeHostBlock = typed(top["code-host"], "code-host");
|
|
599
|
+
const codeHost = codeHostBlock.type ?? DEFAULT_CODE_HOST;
|
|
526
600
|
if (typeof codeHost !== "string" || !built.codeHost.includes(codeHost))
|
|
527
601
|
throw new SettingsError(`${SETTINGS_FILE}: ${unsupportedCodeHost(String(codeHost), built.codeHost)}`);
|
|
602
|
+
const branchName = branchNameOf(codeHostBlock["branch-name"], partial);
|
|
528
603
|
const builds = object(top.builds, "builds");
|
|
529
604
|
const trigger = oneOf(builds.trigger, "builds.trigger", TRIGGERS, "manual");
|
|
530
605
|
const minutes = builds["poll-minutes"];
|
|
@@ -545,8 +620,8 @@ export function parseSettings(raw, exists, built = BUILT) {
|
|
|
545
620
|
const boardFields = Object.fromEntries(Object.entries(rawFields).filter(([k]) => k in FIELD_DEFAULTS));
|
|
546
621
|
if (Object.keys(boardFields).length && !hasBoard)
|
|
547
622
|
fail("tickets.fields", "needs tickets.board");
|
|
548
|
-
const columns = columnNames(tickets.columns);
|
|
549
|
-
if (columns.backlog === null)
|
|
623
|
+
const { columns, missing } = columnNames(tickets.columns, hasBoard ? board : null, partial);
|
|
624
|
+
if (columns.backlog === null && !missing.includes("backlog"))
|
|
550
625
|
fail("tickets.columns.backlog", "cannot be none: every ticket starts there");
|
|
551
626
|
const seen = new Map();
|
|
552
627
|
for (const [key, list] of Object.entries(columns)) {
|
|
@@ -560,19 +635,21 @@ export function parseSettings(raw, exists, built = BUILT) {
|
|
|
560
635
|
for (const name of list ?? [])
|
|
561
636
|
seen.set(name, key);
|
|
562
637
|
}
|
|
563
|
-
if (columns.ready === null &&
|
|
638
|
+
if (columns.ready === null &&
|
|
639
|
+
trigger !== "manual" &&
|
|
640
|
+
!missing.includes("ready"))
|
|
564
641
|
fail("tickets.columns.ready", "no column shows ready, so nothing would start a build: name one, or set builds.trigger to manual");
|
|
565
642
|
if (tickets.fields !== undefined && !isObj(tickets.fields))
|
|
566
643
|
fail("tickets.fields", "must be a block of settings");
|
|
567
644
|
const fieldNames = names(boardFields, "tickets.fields", FIELD_DEFAULTS);
|
|
568
645
|
const ticketFields = ticketFieldsOf(rawFields);
|
|
569
646
|
const specsBlock = typed(top.specs ?? "none", "specs");
|
|
570
|
-
const specs = oneOf(specsBlock.type, "specs",
|
|
571
|
-
if (specsBlock.check !== undefined && specs
|
|
647
|
+
const specs = oneOf(specsBlock.type, "specs", ["none", ...Object.keys(built.specs)], "none");
|
|
648
|
+
if (specsBlock.check !== undefined && specs === "none")
|
|
572
649
|
throw new SettingsError(`${SETTINGS_FILE}: specs.check needs specs.type: openspec`);
|
|
573
|
-
const specCheck = specs === "
|
|
574
|
-
?
|
|
575
|
-
:
|
|
650
|
+
const specCheck = specs === "none"
|
|
651
|
+
? null
|
|
652
|
+
: (command(specsBlock.check, "specs.check") ?? built.specs[specs]);
|
|
576
653
|
const autoMerge = object(top["auto-merge"], "auto-merge");
|
|
577
654
|
const prReview = top["pr-review"] === undefined
|
|
578
655
|
? null
|
|
@@ -606,7 +683,7 @@ export function parseSettings(raw, exists, built = BUILT) {
|
|
|
606
683
|
fields: fieldNames,
|
|
607
684
|
ticketFields,
|
|
608
685
|
},
|
|
609
|
-
codeHost: { type: codeHost },
|
|
686
|
+
codeHost: { type: codeHost, branchName },
|
|
610
687
|
builds: { trigger, runner, pollMinutes },
|
|
611
688
|
specs,
|
|
612
689
|
specCheck,
|
|
@@ -696,7 +773,7 @@ export function parseChoices(text, load) {
|
|
|
696
773
|
* `presets`, and `.claude/factory.yaml`, as `factory sync` combines them
|
|
697
774
|
* into the lock. `factoryFile` and `ownFile` say which preset files are
|
|
698
775
|
* kept back: the factory's own, and the repository's own. */
|
|
699
|
-
export async function resolveFiles(d, keep = {}) {
|
|
776
|
+
export async function resolveFiles(d, { partial = false, ...keep } = {}) {
|
|
700
777
|
const load = await yamlOf(d);
|
|
701
778
|
let ownText;
|
|
702
779
|
let own;
|
|
@@ -758,7 +835,9 @@ export async function resolveFiles(d, keep = {}) {
|
|
|
758
835
|
const exists = (path) => d.exists(path) || resolution.files.has(path);
|
|
759
836
|
let settings;
|
|
760
837
|
try {
|
|
761
|
-
settings = parseSettings(isObj(own) ? resolution.raw : own, exists
|
|
838
|
+
settings = parseSettings(isObj(own) ? resolution.raw : own, exists, BUILT, {
|
|
839
|
+
partial,
|
|
840
|
+
});
|
|
762
841
|
}
|
|
763
842
|
catch (e) {
|
|
764
843
|
throw e instanceof SettingsError ? fromPreset(e, resolution) : e;
|
|
@@ -920,10 +999,10 @@ export const defaultDeps = (root = repoRoot(), env = process.env) => ({
|
|
|
920
999
|
});
|
|
921
1000
|
/** The column each state shows in on the board, null for none. */
|
|
922
1001
|
export function columnsOf(s) {
|
|
923
|
-
|
|
924
|
-
|
|
925
|
-
|
|
926
|
-
|
|
1002
|
+
return Object.fromEntries(Object.entries(STATE_KEYS).map(([key, status]) => [
|
|
1003
|
+
status,
|
|
1004
|
+
s.tickets.columns[key],
|
|
1005
|
+
]));
|
|
927
1006
|
}
|
|
928
1007
|
/** The board's names for the fields the sync writes, null for none. */
|
|
929
1008
|
export function fieldNamesOf(s) {
|
package/dist/doctor.mjs
CHANGED
|
@@ -155,8 +155,7 @@ export async function checks(d) {
|
|
|
155
155
|
// line, or the names asked for when none is.
|
|
156
156
|
const key = anyOf.find((n) => secrets.includes(n)) ?? anyOf.join(" or ");
|
|
157
157
|
const entry = reads.get(key) ?? { anyOf, fors: [] };
|
|
158
|
-
|
|
159
|
-
entry.fors.push(forWhat);
|
|
158
|
+
entry.fors.push(forWhat);
|
|
160
159
|
reads.set(key, entry);
|
|
161
160
|
};
|
|
162
161
|
for (const part of PARTS) {
|
package/dist/explain.mjs
CHANGED
|
@@ -75,7 +75,13 @@ export async function explainLines(s, marks, exists) {
|
|
|
75
75
|
block(["tickets", "fields"]);
|
|
76
76
|
for (const [k, v] of Object.entries(s.tickets.ticketFields))
|
|
77
77
|
put(["tickets", "fields", k], v ?? "none");
|
|
78
|
-
|
|
78
|
+
block(["code-host"]);
|
|
79
|
+
put(["code-host", "type"], s.codeHost.type);
|
|
80
|
+
// Quoted always: YAML reads a pattern that starts with `{` as a map.
|
|
81
|
+
lines.push({
|
|
82
|
+
text: `${pad(1)}branch-name: ${JSON.stringify(s.codeHost.branchName)}`,
|
|
83
|
+
mark: marks.value(["code-host", "branch-name"]),
|
|
84
|
+
});
|
|
79
85
|
block(["builds"]);
|
|
80
86
|
put(["builds", "trigger"], s.builds.trigger);
|
|
81
87
|
put(["builds", "runner"], s.builds.runner);
|
package/dist/init.d.mts
CHANGED
|
@@ -47,7 +47,26 @@ export type InitDeps = {
|
|
|
47
47
|
checks: () => Promise<Check[]>;
|
|
48
48
|
packageName: string;
|
|
49
49
|
packageVersion: string;
|
|
50
|
+
/** The branch name a preset in effect supplies to settings that read
|
|
51
|
+
* as `settingsText`, or null for none. */
|
|
52
|
+
presetBranchName: (settingsText: string) => Promise<string | null>;
|
|
53
|
+
/** The spec tool a preset in effect names for settings that read as
|
|
54
|
+
* `settingsText`, \`none\` included, or null when none names one. */
|
|
55
|
+
presetSpecs: (settingsText: string) => Promise<string | null>;
|
|
56
|
+
/** Runs an install from the root; its status and standard error. */
|
|
57
|
+
install: (argv: string[]) => Promise<{
|
|
58
|
+
status: number;
|
|
59
|
+
stderr: string;
|
|
60
|
+
}>;
|
|
50
61
|
};
|
|
62
|
+
/** The branch name a preset in effect supplies to the settings `text`
|
|
63
|
+
* of the repository at `root`, or null for none. Settings whose presets
|
|
64
|
+
* can't be read get the question: the check that follows says what is
|
|
65
|
+
* wrong with them. */
|
|
66
|
+
export declare const presetBranchNameAt: (root: string) => (text: string) => Promise<string | null>;
|
|
67
|
+
/** The spec tool a preset in effect names, as `presetBranchNameAt` finds
|
|
68
|
+
* a branch name. */
|
|
69
|
+
export declare const presetSpecsAt: (root: string) => (text: string) => Promise<string | null>;
|
|
51
70
|
/** The repository and code host a remote's address names, or null for one
|
|
52
71
|
* on a code host the factory does not support. */
|
|
53
72
|
export declare function parseRemote(url: string, tools?: Registry): {
|