@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.
Files changed (57) hide show
  1. package/README.md +9 -8
  2. package/dist/cli.mjs +13 -1
  3. package/dist/code-host/github-setup.mjs +1 -1
  4. package/dist/config.d.mts +74 -20
  5. package/dist/config.mjs +326 -76
  6. package/dist/deps.d.mts +6 -4
  7. package/dist/deps.mjs +29 -7
  8. package/dist/doctor.d.mts +3 -0
  9. package/dist/doctor.mjs +7 -4
  10. package/dist/explain.d.mts +13 -2
  11. package/dist/explain.mjs +58 -43
  12. package/dist/init.mjs +9 -7
  13. package/dist/lib/default-branch.d.mts +1 -1
  14. package/dist/lib/default-branch.mjs +2 -2
  15. package/dist/lib/refined-check.mjs +1 -1
  16. package/dist/lib/work-status.d.mts +2 -2
  17. package/dist/lib/work-status.mjs +4 -4
  18. package/dist/parts.d.mts +1 -1
  19. package/dist/parts.mjs +2 -2
  20. package/dist/preset-commands.d.mts +65 -0
  21. package/dist/preset-commands.mjs +1148 -0
  22. package/dist/preset.d.mts +169 -0
  23. package/dist/preset.mjs +550 -0
  24. package/dist/remove.mjs +34 -1
  25. package/dist/review-cost.mjs +1 -1
  26. package/dist/review-tools.mjs +3 -3
  27. package/dist/session-start.d.mts +3 -0
  28. package/dist/session-start.mjs +12 -1
  29. package/dist/sync.d.mts +42 -7
  30. package/dist/sync.mjs +166 -32
  31. package/docs/builds.md +12 -11
  32. package/docs/cli.md +27 -8
  33. package/docs/configuration.md +723 -714
  34. package/docs/design.md +1 -1
  35. package/docs/developing.md +20 -8
  36. package/docs/existing-repo.md +1 -1
  37. package/docs/github/by-hand.md +9 -9
  38. package/docs/github/reference.md +4 -19
  39. package/docs/github/setup.md +3 -3
  40. package/docs/glossary.md +18 -9
  41. package/docs/limitations.md +4 -1
  42. package/docs/plugins.md +36 -24
  43. package/docs/presets.md +410 -0
  44. package/docs/quick-start.md +21 -18
  45. package/docs/removing.md +1 -1
  46. package/docs/skills.md +28 -23
  47. package/docs/updating.md +22 -14
  48. package/docs/workflow.md +13 -14
  49. package/package.json +1 -1
  50. package/rules.md +1 -1
  51. package/settings.schema.json +60 -11
  52. package/skills/factory-build/SKILL.md +1 -1
  53. package/skills/factory-deps/SKILL.md +23 -12
  54. package/skills/factory-design/SKILL.md +2 -2
  55. package/skills/factory-refine/SKILL.md +2 -2
  56. package/skills/factory-resolve-conflicts/SKILL.md +6 -0
  57. 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 -->|tell a session to build it| D[Build: on your machine]
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
- | [Plug-ins](docs/plugins.md) | Putting your own skills and agents to work |
108
- | [Builds in the cloud](docs/builds.md) | Starting builds from your board |
109
- | [Updating](docs/updating.md) | Getting a new version |
110
- | [What it changes, and removing it](docs/removing.md) | Everything it adds, and how to undo it |
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: "[SLOT]",
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?.ciReview != null;
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 plug-in does, in the order `factory plugins` prints them. */
7
- export declare const SLOTS: readonly ["refiner", "mockups", "builder", "reviewer", "prover", "test-reviewer", "resolver"];
8
- export type Slot = (typeof SLOTS)[number];
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 SlotShape = {
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 slot: the phase and key it is written under, the one kind it
20
- * takes, whether it holds one plug-in or a list, and whether a plug-in in
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 SLOT_SHAPE: Record<Slot, SlotShape>;
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
- slot: Slot;
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 plug-ins the settings name, in the slots' order. `pluginsOf` adds
90
- * the factory's own for each slot left out. */
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 CI review, on when `ci-review` is written, with the commands it
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
- ciReview: {
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 plug-ins' files. */
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
- export declare const defaultDeps: (root?: string) => Deps;
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 command runs in. */
201
- export declare const loadSettings: (d?: Deps) => Promise<Settings>;
202
- /** Every plug-in the factory will use, in the slots' order: the settings'
203
- * own, and the factory's for each slot they leave out. The refiner and the
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 plug-in of a
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 [SLOT]`. */
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 = {