@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/README.md
CHANGED
|
@@ -36,7 +36,7 @@ request to read. You decide what merges.
|
|
|
36
36
|
flowchart LR
|
|
37
37
|
A[You write a ticket] --> B[Refine: a session asks your decisions and writes the spec]
|
|
38
38
|
B --> C{You approve}
|
|
39
|
-
C -->|
|
|
39
|
+
C -->|"run /factory-build N in a session"| D[Build: on your machine]
|
|
40
40
|
C -->|move its card to Ready| E[Build: in the cloud]
|
|
41
41
|
D --> F[A pull request, with tests and a review]
|
|
42
42
|
E --> F
|
|
@@ -101,13 +101,14 @@ else is optional and comes later.
|
|
|
101
101
|
|
|
102
102
|
**Guides**
|
|
103
103
|
|
|
104
|
-
| Page | For
|
|
105
|
-
| -------------------------------------------------------------- |
|
|
106
|
-
| [Adopting it in an existing repository](docs/existing-repo.md) | Not JavaScript, an existing board, a team
|
|
107
|
-
| [
|
|
108
|
-
| [
|
|
109
|
-
| [
|
|
110
|
-
| [
|
|
104
|
+
| Page | For |
|
|
105
|
+
| -------------------------------------------------------------- | -------------------------------------------- |
|
|
106
|
+
| [Adopting it in an existing repository](docs/existing-repo.md) | Not JavaScript, an existing board, a team |
|
|
107
|
+
| [Plugins](docs/plugins.md) | Putting your own skills and agents to work |
|
|
108
|
+
| [Presets](docs/presets.md) | Sharing settings across several repositories |
|
|
109
|
+
| [Builds in the cloud](docs/builds.md) | Starting builds from your board |
|
|
110
|
+
| [Updating](docs/updating.md) | Getting a new version |
|
|
111
|
+
| [What it changes, and removing it](docs/removing.md) | Everything it adds, and how to undo it |
|
|
111
112
|
|
|
112
113
|
**Reference**
|
|
113
114
|
|
package/dist/cli.mjs
CHANGED
|
@@ -141,6 +141,18 @@ export const COMMANDS = [
|
|
|
141
141
|
args: "",
|
|
142
142
|
run: async (argv) => (await import("./remove.mjs")).run(argv),
|
|
143
143
|
},
|
|
144
|
+
...[
|
|
145
|
+
["add", "NAME [--yes] [--dry-run]"],
|
|
146
|
+
["remove", "NAME [--yes] [--dry-run]"],
|
|
147
|
+
["choices", ""],
|
|
148
|
+
["choose", "KEY PRESET"],
|
|
149
|
+
["check", ""],
|
|
150
|
+
["changes", "REF"],
|
|
151
|
+
].map(([sub, args]) => ({
|
|
152
|
+
words: ["preset", sub],
|
|
153
|
+
args,
|
|
154
|
+
run: async (argv) => (await import("./preset-commands.mjs")).run([sub, ...argv]),
|
|
155
|
+
})),
|
|
144
156
|
{
|
|
145
157
|
words: ["config", "get"],
|
|
146
158
|
args: "KEY",
|
|
@@ -168,7 +180,7 @@ export const COMMANDS = [
|
|
|
168
180
|
},
|
|
169
181
|
{
|
|
170
182
|
words: ["plugins"],
|
|
171
|
-
args: "[
|
|
183
|
+
args: "[ROLE]",
|
|
172
184
|
run: async (argv) => (await import("./config.mjs")).run(["plugins", ...argv]),
|
|
173
185
|
},
|
|
174
186
|
{
|
|
@@ -123,7 +123,7 @@ export const githubCodeHostSetup = {
|
|
|
123
123
|
leftovers: (c) => {
|
|
124
124
|
const lines = [];
|
|
125
125
|
// init only ever adds the rule, so it can outlast the review.
|
|
126
|
-
const sure = c.settings?.
|
|
126
|
+
const sure = c.settings?.prReview != null;
|
|
127
127
|
lines.push(`Delete the "${RULE}" ruleset first${sure ? "" : ", if there is one"}, under Settings, Rules: until then every pull request waits on its "Review verdict" check`);
|
|
128
128
|
const names = ALL_TOKENS.filter((n) => c.secrets === null || c.secrets.includes(n));
|
|
129
129
|
if (names.length)
|
package/dist/config.d.mts
CHANGED
|
@@ -3,12 +3,12 @@ import { type Built } from "./tool-names.mts";
|
|
|
3
3
|
import { type Watch, type Columns, type StateKey } from "./lib/work-status.mts";
|
|
4
4
|
export declare class SettingsError extends Error {
|
|
5
5
|
}
|
|
6
|
-
/** What a
|
|
7
|
-
export declare const
|
|
8
|
-
export type
|
|
6
|
+
/** What a plugin does, in the order `factory plugins` prints them. */
|
|
7
|
+
export declare const ROLES: readonly ["refiner", "mockups", "builder", "reviewer", "prover", "test-reviewer", "resolver"];
|
|
8
|
+
export type Role = (typeof ROLES)[number];
|
|
9
9
|
/** The phases `plugins` is grouped by. */
|
|
10
10
|
export declare const PHASES: readonly ["refine", "build", "test", "conflicts"];
|
|
11
|
-
type
|
|
11
|
+
type RoleShape = {
|
|
12
12
|
phase: (typeof PHASES)[number];
|
|
13
13
|
key: string;
|
|
14
14
|
kind: Plugin["kind"];
|
|
@@ -16,10 +16,10 @@ type SlotShape = {
|
|
|
16
16
|
files: "required" | "optional" | "none";
|
|
17
17
|
labels: "required" | "none";
|
|
18
18
|
};
|
|
19
|
-
/** Each
|
|
20
|
-
* takes, whether it holds one
|
|
19
|
+
/** Each role: the phase and key it is written under, the one kind it
|
|
20
|
+
* takes, whether it holds one plugin or a list, and whether a plugin in
|
|
21
21
|
* it must have, may have, or cannot have `files` and `labels`. */
|
|
22
|
-
export declare const
|
|
22
|
+
export declare const ROLE_SHAPE: Record<Role, RoleShape>;
|
|
23
23
|
export declare const TRIGGERS: readonly ["own-server", "github-action", "manual"];
|
|
24
24
|
/** How often the scheduled poller may check the board, in minutes: each
|
|
25
25
|
* divides an hour, so a schedule every N minutes keeps an even beat. */
|
|
@@ -34,7 +34,7 @@ export type FieldKey = keyof typeof FIELD_DEFAULTS;
|
|
|
34
34
|
export type Plugin = {
|
|
35
35
|
kind: "skill" | "agent";
|
|
36
36
|
name: string;
|
|
37
|
-
|
|
37
|
+
role: Role;
|
|
38
38
|
files: string[];
|
|
39
39
|
labels: string[];
|
|
40
40
|
};
|
|
@@ -86,8 +86,8 @@ export type Settings = {
|
|
|
86
86
|
/** Rebuilds the package manager's lock file after a conflict in it. */
|
|
87
87
|
relock: string;
|
|
88
88
|
};
|
|
89
|
-
/** The
|
|
90
|
-
* the factory's own for each
|
|
89
|
+
/** The plugins the settings name, in the roles' order. `pluginsOf` adds
|
|
90
|
+
* the factory's own for each role left out. */
|
|
91
91
|
plugins: Plugin[];
|
|
92
92
|
/** Whether `plugins.test.reviewers` is written. Written, it is the whole
|
|
93
93
|
* list of test reviewers, even when it is empty. */
|
|
@@ -97,9 +97,9 @@ export type Settings = {
|
|
|
97
97
|
deny: string[];
|
|
98
98
|
commands: string[];
|
|
99
99
|
};
|
|
100
|
-
/** The
|
|
100
|
+
/** The pull request review, on when `pr-review` is written, with the commands it
|
|
101
101
|
* may run as prefixes beside the factory's own; null when it is off. */
|
|
102
|
-
|
|
102
|
+
prReview: {
|
|
103
103
|
commands: string[];
|
|
104
104
|
} | null;
|
|
105
105
|
/** How the factory looks at the repository's website; null when the
|
|
@@ -167,13 +167,14 @@ export declare function repoRoot(from?: string): string;
|
|
|
167
167
|
export declare const SETTINGS_FILE = ".claude/factory.yaml";
|
|
168
168
|
/** The settings with every default filled in. Throws a SettingsError naming
|
|
169
169
|
* the key on anything unsound. `exists` says whether a path from the root
|
|
170
|
-
* exists, for the
|
|
170
|
+
* exists, for the plugins' files. */
|
|
171
171
|
export declare function parseSettings(raw: unknown, exists: (path: string) => boolean, built?: Built): Settings;
|
|
172
172
|
/** One line for each pattern that matches none of `files`: a stale pattern
|
|
173
173
|
* is how a policy rots. */
|
|
174
174
|
export declare function patternWarnings(s: Settings, files: string[]): string[];
|
|
175
175
|
type YamlLoad = (text: string) => unknown;
|
|
176
176
|
export type Deps = {
|
|
177
|
+
/** `.claude/factory.yaml`, or the file FACTORY_SETTINGS names. */
|
|
177
178
|
readFile: () => string;
|
|
178
179
|
exists: (path: string) => boolean;
|
|
179
180
|
/** Whether an npm package resolves from the repository's root. */
|
|
@@ -182,13 +183,62 @@ export type Deps = {
|
|
|
182
183
|
loadYaml: () => Promise<YamlLoad>;
|
|
183
184
|
out: (line: string) => void;
|
|
184
185
|
err: (line: string) => void;
|
|
186
|
+
/** Where the settings come from when every command reads the lock:
|
|
187
|
+
* `check` stops on a stale one. Unset, they are resolved from the files
|
|
188
|
+
* the lock is made from. */
|
|
189
|
+
lock?: {
|
|
190
|
+
read: () => string | null;
|
|
191
|
+
check: boolean;
|
|
192
|
+
};
|
|
193
|
+
/** `.claude/factory.choices.yaml`, null when there is none. */
|
|
194
|
+
readChoices?: () => string | null;
|
|
195
|
+
/** Where presets are installed from. */
|
|
196
|
+
root?: string;
|
|
197
|
+
/** Which of the settings files differ from the last commit. */
|
|
198
|
+
changed?: () => string[];
|
|
199
|
+
/** A package's installed version: null when it is not installed, and
|
|
200
|
+
* undefined where there is no node_modules to look in. */
|
|
201
|
+
installed?: (pkg: string) => string | null | undefined;
|
|
185
202
|
};
|
|
186
203
|
export declare const NO_DEPENDENCIES = "The factory's settings cannot be read until dependencies are installed: run npm ci.";
|
|
204
|
+
/** The settings resolved from the files the lock is made from: the
|
|
205
|
+
* presets, `.claude/factory.yaml`, and the choices between them. */
|
|
206
|
+
export type Resolved = {
|
|
207
|
+
settings: Settings;
|
|
208
|
+
resolution: import("./preset.mts").Resolution;
|
|
209
|
+
presets: import("./preset.mts").Found[];
|
|
210
|
+
/** `.claude/factory.yaml` as written, and its text. */
|
|
211
|
+
own: Record<string, unknown>;
|
|
212
|
+
ownText: string;
|
|
213
|
+
choices: Record<string, string>;
|
|
214
|
+
choicesText: string | null;
|
|
215
|
+
/** Whether a path exists, counting the files the presets ship. */
|
|
216
|
+
exists: (path: string) => boolean;
|
|
217
|
+
};
|
|
218
|
+
/** The choices file read as a map from a key to a preset's name. */
|
|
219
|
+
export declare function parseChoices(text: string | null, load: YamlLoad): Record<string, string>;
|
|
220
|
+
/** The settings combined from the factory's defaults, each preset in
|
|
221
|
+
* `presets`, and `.claude/factory.yaml`, as `factory sync` combines them
|
|
222
|
+
* into the lock. `factoryFile` and `ownFile` say which preset files are
|
|
223
|
+
* kept back: the factory's own, and the repository's own. */
|
|
224
|
+
export declare function resolveFiles(d: Deps, keep?: {
|
|
225
|
+
factoryFile?: (path: string) => boolean;
|
|
226
|
+
ownFile?: (path: string) => boolean;
|
|
227
|
+
}): Promise<Resolved>;
|
|
228
|
+
/** Why the lock `d` reads is stale, or null when it is current or `d`
|
|
229
|
+
* reads none. */
|
|
230
|
+
export declare function staleOf(d: Deps): Promise<string | null>;
|
|
231
|
+
/** The lines of the lock's `settings` block, as `factory config explain`
|
|
232
|
+
* printed them when the lock was written. */
|
|
233
|
+
export declare function lockSettingsLines(text: string): string[];
|
|
187
234
|
/** The settings file: FACTORY_SETTINGS where it is set, for trying settings
|
|
188
235
|
* against a board without changing the repository's, and otherwise the
|
|
189
236
|
* repository's own. */
|
|
190
237
|
export declare const settingsPath: (root: string, env?: Record<string, string | undefined>) => string;
|
|
191
|
-
|
|
238
|
+
/** The settings of the checkout at `root`, read from its lock, or from
|
|
239
|
+
* the lock FACTORY_LOCK names without checking it is current, or from the
|
|
240
|
+
* settings file FACTORY_SETTINGS names with no lock at all. */
|
|
241
|
+
export declare const defaultDeps: (root?: string, env?: Record<string, string | undefined>) => Deps;
|
|
192
242
|
/** The column each state shows in on the board, null for none. */
|
|
193
243
|
export declare function columnsOf(s: Settings): Columns;
|
|
194
244
|
/** The board's names for the fields the sync writes, null for none. */
|
|
@@ -197,17 +247,21 @@ export declare function fieldNamesOf(s: Settings): {
|
|
|
197
247
|
runsIn: string | null;
|
|
198
248
|
cost: string | null;
|
|
199
249
|
};
|
|
200
|
-
/** The settings of the checkout the
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
250
|
+
/** The settings of the checkout at `root` resolved from the files the lock
|
|
251
|
+
* is made from, for the commands that make or check the lock. */
|
|
252
|
+
export declare const filesDeps: (root?: string, env?: Record<string, string | undefined>) => Deps;
|
|
253
|
+
/** The settings of the checkout the command runs in: from its lock, or
|
|
254
|
+
* resolved from the files where `d` reads no lock. */
|
|
255
|
+
export declare function loadSettings(d?: Deps): Promise<Settings>;
|
|
256
|
+
/** Every plugin the factory will use, in the roles' order: the settings'
|
|
257
|
+
* own, and the factory's for each role they leave out. The refiner and the
|
|
204
258
|
* prover are always there. The factory's test reviewer is there unless the
|
|
205
|
-
* settings write the list. Its design skill is the mockups
|
|
259
|
+
* settings write the list. Its design skill is the mockups plugin of a
|
|
206
260
|
* site that names none, once it is synced. */
|
|
207
261
|
export declare function pluginsOf(s: Settings, exists: (path: string) => boolean): Plugin[];
|
|
208
262
|
export declare function main(argv: string[], d: Deps): Promise<number>;
|
|
209
263
|
/** `factory config get KEY`, `factory config check`, and
|
|
210
|
-
* `factory plugins [
|
|
264
|
+
* `factory plugins [ROLE]`. */
|
|
211
265
|
export declare function run(argv: string[]): Promise<number>;
|
|
212
266
|
/** What a reading needs from the settings. */
|
|
213
267
|
export type Target = {
|