@davidbyoung/software-factory 0.1.7 → 0.1.8

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.
@@ -234,6 +234,10 @@ export function githubCodeHost(o) {
234
234
  const repo = await t.rest("GET", API);
235
235
  return repo.private;
236
236
  },
237
+ async ownerIsOrganization() {
238
+ const repo = await t.rest("GET", API);
239
+ return repo.owner.type === "Organization";
240
+ },
237
241
  async checkRuns(sha) {
238
242
  const answer = await t.rest("GET", `${API}/commits/${sha}/check-runs?per_page=100`);
239
243
  return answer.check_runs.map((c) => ({
@@ -123,6 +123,8 @@ export type CodeHost = {
123
123
  defaultBranch(): Promise<string>;
124
124
  /** Whether only people given access can see the repository. */
125
125
  isPrivate(): Promise<boolean>;
126
+ /** Whether an organization owns the repository, rather than a person. */
127
+ ownerIsOrganization(): Promise<boolean>;
126
128
  /** The check runs on a commit, without its statuses. */
127
129
  checkRuns(sha: string): Promise<CheckRun[]>;
128
130
  /** The statuses on a commit, without its check runs. */
package/dist/config.d.mts CHANGED
@@ -194,6 +194,9 @@ export type Deps = {
194
194
  };
195
195
  /** `.claude/factory.choices.yaml`, null when there is none. */
196
196
  readChoices?: () => string | null;
197
+ /** The text of `.npmrc` at the root, or null. Read from disk unless
198
+ * given. */
199
+ readNpmrc?: () => string | null;
197
200
  /** Where presets are installed from. */
198
201
  root?: string;
199
202
  /** Which of the settings files differ from the last commit. */
package/dist/config.mjs CHANGED
@@ -775,6 +775,11 @@ export async function staleOf(d) {
775
775
  ? (P.findPackage(root, pkg)?.version ?? null)
776
776
  : undefined),
777
777
  load,
778
+ npmrcNames: (await import("./npmrc.mjs")).readNpmrc(d.readNpmrc
779
+ ? d.readNpmrc()
780
+ : existsSync(join(root, ".npmrc"))
781
+ ? readFileSync(join(root, ".npmrc"), "utf8")
782
+ : null).names,
778
783
  });
779
784
  }
780
785
  /** The settings in the lock, after checking it is current where `check`
package/dist/doctor.d.mts CHANGED
@@ -21,6 +21,9 @@ export type DoctorDeps = {
21
21
  out: (line: string) => void;
22
22
  };
23
23
  export declare function checks(d: DoctorDeps): Promise<Check[]>;
24
+ /** Whether Dependabot's settings name the registry at `url` under their
25
+ * `registries`, and every npm update lists it, or all of them. */
26
+ export declare function usesRegistry(settings: string, url: string): boolean;
24
27
  /** One check as a line: a tick, a cross with what to do, or a dash for a
25
28
  * part that is off. */
26
29
  export declare function line(c: Check): string;
package/dist/doctor.mjs CHANGED
@@ -4,7 +4,9 @@
4
4
  //
5
5
  // A stored secret cannot be read back, so a secret is checked only for
6
6
  // being set.
7
- import { readFileSync } from "node:fs";
7
+ import { existsSync, readFileSync } from "node:fs";
8
+ import { load } from "js-yaml";
9
+ import { bareRegistry, npmrcAt, privateRegistries } from "./npmrc.mjs";
8
10
  import { join } from "node:path";
9
11
  import { defaultDeps, filesDeps, repoRoot, resolveFiles, staleOf, } from "./config.mjs";
10
12
  import { presetChecks } from "./preset-commands.mjs";
@@ -97,25 +99,34 @@ export async function checks(d) {
97
99
  const [agent, codeHost, tickets, runner] = inUse(d.tools, chosen);
98
100
  out.push(...((await codeHost.setup.checks?.({ ...context([]), secrets: null })) ??
99
101
  []));
100
- let secrets;
102
+ // A secret the organization shares with the repository counts as set.
103
+ const isOrganization = await opened.codeHost
104
+ .ownerIsOrganization()
105
+ .catch(() => true);
106
+ const shared = isOrganization
107
+ ? await opened.runner.organizationSecretNames().catch(() => [])
108
+ : [];
109
+ let own;
101
110
  try {
102
- secrets = await opened.runner.secretNames();
111
+ own = await opened.runner.secretNames();
103
112
  }
104
113
  catch (e) {
105
- secrets = null;
114
+ own = null;
106
115
  out.push({
107
116
  state: "fail",
108
117
  text: "The secrets can be listed",
109
118
  fix: message(e),
110
119
  });
111
120
  }
121
+ const secrets = own === null ? null : [...own, ...shared];
112
122
  const cloudNeeds = secretSteps(d.tools, context(["cloud"])).flatMap((x) => x.step.needs.filter((n) => n.part === "cloud"));
113
123
  const on = partsOn(s, secrets ?? [], cloudNeeds);
114
124
  const needed = neededSecrets(on, secretSteps(d.tools, context(on)));
115
125
  const secretLine = (anyOf, forWhat) => {
116
126
  const found = anyOf.find((n) => secrets.includes(n));
127
+ const by = found && !own.includes(found) ? " by the organization" : "";
117
128
  return found
118
- ? { state: "pass", text: `${found} is set, for ${forWhat}` }
129
+ ? { state: "pass", text: `${found} is set${by}, for ${forWhat}` }
119
130
  : {
120
131
  state: "fail",
121
132
  text: `${anyOf.join(" or ")} is not set, for ${forWhat}`,
@@ -143,15 +154,132 @@ export async function checks(d) {
143
154
  if (secrets !== null)
144
155
  for (const need of needed.filter((n) => n.part === null))
145
156
  out.push(secretLine(need.anyOf, need.tool));
157
+ out.push(...(await npmChecks(d.root, opened, isOrganization, own, shared)));
146
158
  for (const tool of [tickets, runner, agent])
147
159
  out.push(...((await tool.setup.checks?.({ ...context(on), secrets })) ?? []));
148
160
  return out;
149
161
  }
162
+ const DEPENDABOT = ".github/dependabot.yml";
163
+ const FOR_NPM = "for installing what .npmrc names";
164
+ const FOR_DEPENDABOT = "for installing on Dependabot's pull requests";
165
+ /** The checks for the variables `.npmrc`'s sign-in lines read: each one's
166
+ * secret for Actions and for Dependabot, and whether Dependabot's settings
167
+ * use each registry `.npmrc` names. */
168
+ async function npmChecks(root, opened, isOrganization, own, shared) {
169
+ const npmrc = npmrcAt(root);
170
+ if (!npmrc.names.length)
171
+ return [];
172
+ const out = [];
173
+ let dependabot;
174
+ try {
175
+ dependabot = await opened.runner.dependabotSecretNames();
176
+ }
177
+ catch (e) {
178
+ dependabot = null;
179
+ out.push({
180
+ state: "fail",
181
+ text: "The Dependabot secrets can be listed",
182
+ fix: message(e),
183
+ });
184
+ }
185
+ const tokens = npmrc.names.filter((n) => n !== "GITHUB_TOKEN");
186
+ const organizations = isOrganization &&
187
+ dependabot !== null &&
188
+ tokens.some((n) => !dependabot.includes(n))
189
+ ? await opened.runner.organizationDependabotSecretNames(await opened.codeHost.isPrivate())
190
+ : [];
191
+ for (const name of npmrc.names) {
192
+ if (name === "GITHUB_TOKEN") {
193
+ out.push({
194
+ state: "off",
195
+ text: "GITHUB_TOKEN is the workflow's own token: it installs only the packages that give this repository access",
196
+ });
197
+ continue;
198
+ }
199
+ if (own !== null)
200
+ out.push(own.includes(name)
201
+ ? { state: "pass", text: `${name} is set, ${FOR_NPM}` }
202
+ : shared.includes(name)
203
+ ? {
204
+ state: "pass",
205
+ text: `${name} is set by the organization, ${FOR_NPM}`,
206
+ }
207
+ : {
208
+ state: "fail",
209
+ text: `${name} is not set, ${FOR_NPM}`,
210
+ fix: INIT,
211
+ });
212
+ if (dependabot === null)
213
+ continue;
214
+ out.push(dependabot.includes(name)
215
+ ? {
216
+ state: "pass",
217
+ text: `${name} is set for Dependabot, ${FOR_DEPENDABOT}`,
218
+ }
219
+ : organizations === null
220
+ ? {
221
+ state: "unknown",
222
+ text: `${name} is not set for Dependabot on the repository, and only an organization admin can see whether the organization sets it`,
223
+ }
224
+ : organizations.includes(name)
225
+ ? {
226
+ state: "pass",
227
+ text: `${name} is set by the organization for Dependabot, ${FOR_DEPENDABOT}`,
228
+ }
229
+ : {
230
+ state: "fail",
231
+ text: `${name} is not set for Dependabot, ${FOR_DEPENDABOT}`,
232
+ fix: INIT,
233
+ });
234
+ }
235
+ const path = join(root, DEPENDABOT);
236
+ if (existsSync(path)) {
237
+ const settings = readFileSync(path, "utf8");
238
+ for (const url of privateRegistries(npmrc))
239
+ out.push(usesRegistry(settings, url)
240
+ ? {
241
+ state: "pass",
242
+ text: `${DEPENDABOT} uses ${url} for its npm updates`,
243
+ }
244
+ : {
245
+ state: "unknown",
246
+ text: `${DEPENDABOT} doesn't use ${url} for its npm updates: unless your organization sets that registry for Dependabot, it never sees a new version of a package from there. Add it under registries, and name it in the npm entry's registries`,
247
+ });
248
+ }
249
+ return out;
250
+ }
251
+ /** Whether Dependabot's settings name the registry at `url` under their
252
+ * `registries`, and every npm update lists it, or all of them. */
253
+ export function usesRegistry(settings, url) {
254
+ let o;
255
+ try {
256
+ o = load(settings);
257
+ }
258
+ catch {
259
+ return false;
260
+ }
261
+ const isObj = (x) => typeof x === "object" && x !== null && !Array.isArray(x);
262
+ if (!isObj(o) || !isObj(o.registries))
263
+ return false;
264
+ const names = Object.entries(o.registries)
265
+ .filter(([, r]) => isObj(r) &&
266
+ typeof r.url === "string" &&
267
+ bareRegistry(r.url) === bareRegistry(url))
268
+ .map(([name]) => name);
269
+ const npm = (Array.isArray(o.updates) ? o.updates : []).filter((u) => isObj(u) && u["package-ecosystem"] === "npm");
270
+ return (names.length > 0 &&
271
+ npm.length > 0 &&
272
+ npm.every((u) => u.registries === "*" ||
273
+ (Array.isArray(u.registries) &&
274
+ u.registries.some((r) => names.includes(String(r))))));
275
+ }
150
276
  /** One check as a line: a tick, a cross with what to do, or a dash for a
151
277
  * part that is off. */
152
278
  export function line(c) {
153
279
  if (c.state === "off")
154
280
  return `- ${c.text}`;
281
+ if (c.state === "unknown")
282
+ return `? ${c.text}`;
155
283
  if (c.state === "pass")
156
284
  return `✓ ${c.text}`;
157
285
  const fix = c.fix ?? "";
package/dist/init.mjs CHANGED
@@ -18,6 +18,7 @@ import { checks as doctorChecks, doctorDeps, line } from "./doctor.mjs";
18
18
  import { branchDeps, needDefaultBranch, NoDefaultBranch, } from "./lib/default-branch.mjs";
19
19
  import { hasCommand, noTerminal } from "./lib/has-command.mjs";
20
20
  import { DEFAULT_RUNNER } from "./runner/index.mjs";
21
+ import { addressOf, firstRefusal, NPMRC, npmrcAt, } from "./npmrc.mjs";
21
22
  import { listed } from "./lib/listed.mjs";
22
23
  import { neededSecrets, PART_TEXT, PARTS, partsOn, resolveParts, SIGNING_KEY, } from "./parts.mjs";
23
24
  import { CONTEXT as REVIEW_VERDICT } from "./review-verdict.mjs";
@@ -138,6 +139,7 @@ export async function main(_argv, d) {
138
139
  ? `${tools[choice[kind]].label}, from your settings`
139
140
  : "chosen below";
140
141
  };
142
+ const npmrc = npmrcAt(d.root);
141
143
  d.out(`Setting up the software factory for ${repository}`);
142
144
  d.out("");
143
145
  d.out("Found");
@@ -147,11 +149,18 @@ export async function main(_argv, d) {
147
149
  row("Coding agent", agent.setup.found?.({ hasCommand: d.hasCommand }) ?? agent.label);
148
150
  row("Cloud builds", shown("runner"));
149
151
  row("package.json", hasPackage ? "yes" : "none, so a private one will be created");
152
+ if (npmrc.names.length)
153
+ row(NPMRC, `reads ${npmrc.names.join(", ")}`);
150
154
  row("Settings", settingsText === null ? "none yet" : SETTINGS_FILE);
151
155
  row("Board", settings?.tickets.board != null
152
156
  ? `${settings.tickets.board}, from your settings`
153
157
  : "none yet");
154
158
  d.out("");
159
+ const refused = firstRefusal(npmrc);
160
+ if (refused) {
161
+ d.out(refused);
162
+ return 1;
163
+ }
155
164
  const pick = async (kind, question) => {
156
165
  const tools = d.tools[kind];
157
166
  if (only(tools))
@@ -178,14 +187,22 @@ export async function main(_argv, d) {
178
187
  hasCommand: d.hasCommand,
179
188
  opened: { codeHost, runner, tickets },
180
189
  });
181
- let secrets;
190
+ let own;
191
+ let npm;
192
+ // A secret the organization shares with the repository counts as set.
193
+ const isOrganization = await codeHost.ownerIsOrganization().catch(() => true);
194
+ let shared = [];
182
195
  try {
183
- secrets = await runner.secretNames();
196
+ own = await runner.secretNames();
197
+ if (isOrganization)
198
+ shared = await runner.organizationSecretNames().catch(() => []);
199
+ npm = await npmSecrets(npmrc, runner, codeHost, isOrganization);
184
200
  }
185
201
  catch (e) {
186
202
  d.out(`Could not reach the code host: ${message(e)}`);
187
203
  return 1;
188
204
  }
205
+ const secrets = [...own, ...shared];
189
206
  const isSet = (n) => secrets.includes(n);
190
207
  const cloudNeeds = secretSteps(d.tools, context(["cloud"])).flatMap((s) => s.step.needs.filter((n) => n.part === "cloud"));
191
208
  const before = partsOn(settings, secrets, cloudNeeds);
@@ -357,7 +374,13 @@ export async function main(_argv, d) {
357
374
  // you choose to replace them.
358
375
  const steps = secretSteps(d.tools, context(parts));
359
376
  const needed = neededSecrets(parts, steps);
360
- const alreadySet = [...new Set(needed.flatMap((n) => n.anyOf.filter(isSet)))];
377
+ const npmBothSet = npm.tokens.filter((n) => isSet(n) && npm.dependabot(n) === "set");
378
+ const alreadySet = [
379
+ ...new Set([
380
+ ...needed.flatMap((n) => n.anyOf.filter(isSet)),
381
+ ...npmBothSet,
382
+ ]),
383
+ ];
361
384
  let replace = false;
362
385
  if (alreadySet.length)
363
386
  replace = await d.ask.confirm(alreadySet.length === 1
@@ -372,11 +395,22 @@ export async function main(_argv, d) {
372
395
  }))
373
396
  .filter((a) => a.names.length > 0);
374
397
  const wantsKey = parts.has("signing") && (replace || !isSet(SIGNING_KEY));
398
+ const npmAsked = npm.tokens
399
+ .map((name) => {
400
+ const again = replace && npmBothSet.includes(name);
401
+ return {
402
+ name,
403
+ actions: again || !isSet(name),
404
+ dependabot: again || npm.dependabot(name) !== "set",
405
+ unseen: !again && npm.dependabot(name) === "unknown",
406
+ };
407
+ })
408
+ .filter((a) => a.actions || a.dependabot);
375
409
  const stillRead = new Set(needed.flatMap((n) => n.anyOf));
376
410
  const deletable = [
377
411
  ...new Set(neededSecrets(new Set(removed), secretSteps(d.tools, context(removed)))
378
412
  .flatMap((n) => n.anyOf)
379
- .filter((n) => isSet(n) && !stillRead.has(n))),
413
+ .filter((n) => own.includes(n) && !stillRead.has(n))),
380
414
  ];
381
415
  // The plan.
382
416
  const newText = String(doc);
@@ -412,6 +446,8 @@ export async function main(_argv, d) {
412
446
  planRow("Board", `give board ${board} any of the factory's columns and fields it lacks`);
413
447
  if (toStore.length)
414
448
  planRow("Secrets", toStore.join(", "));
449
+ for (const a of npmAsked)
450
+ planRow("Secrets", `${a.name} ${forWhich(a)}`);
415
451
  if (parts.has("auto-merge"))
416
452
  planRow("Settings", "allow auto-merge on the repository");
417
453
  if (parts.has("review"))
@@ -496,6 +532,32 @@ export async function main(_argv, d) {
496
532
  break;
497
533
  }
498
534
  }
535
+ // The tokens .npmrc reads, each stored where it is missing.
536
+ for (const a of npmAsked) {
537
+ d.out("");
538
+ let prompt = "Paste the same token again (leave empty to do this later):";
539
+ if (a.actions && a.dependabot) {
540
+ d.out(`${NPMRC} reads ${a.name} for ${addressOf(npmrc, a.name)}.`);
541
+ d.out("The factory's workflows install with it. Use a token that can only read.");
542
+ prompt = "Paste it (leave empty to do this later):";
543
+ }
544
+ else if (!a.unseen)
545
+ d.out(a.actions
546
+ ? `${a.name} is set for Dependabot but not for Actions, and GitHub never shows a secret's value.`
547
+ : `${a.name} is set for Actions but not for Dependabot, and GitHub never shows a secret's value.`);
548
+ if (a.unseen)
549
+ d.out(`${a.name} isn't set for Dependabot on this repository, and only an organization admin can see whether your organization sets it. If it does, leave this empty.`);
550
+ const value = await d.ask.secret(prompt);
551
+ if (!value) {
552
+ d.out(`No ${a.name} stored. The factory's workflows fail at npm ci until it is. ${AGAIN}`);
553
+ continue;
554
+ }
555
+ if (a.actions)
556
+ await runner.setSecret(a.name, value);
557
+ if (a.dependabot)
558
+ await runner.setDependabotSecret(a.name, value);
559
+ d.out(`Stored ${a.name} ${forWhich(a)}.`);
560
+ }
499
561
  // The signing key.
500
562
  if (wantsKey) {
501
563
  const key = await d.keygen();
@@ -673,3 +735,30 @@ export async function run(argv) {
673
735
  throw e;
674
736
  }
675
737
  }
738
+ /** The tokens `.npmrc` reads, and whether each is set for Dependabot. */
739
+ async function npmSecrets(npmrc, runner, codeHost, isOrganization) {
740
+ const tokens = npmrc.names.filter((n) => n !== "GITHUB_TOKEN");
741
+ if (!tokens.length)
742
+ return { tokens, dependabot: () => "set" };
743
+ const own = await runner.dependabotSecretNames();
744
+ const organization = isOrganization && tokens.some((n) => !own.includes(n))
745
+ ? await runner.organizationDependabotSecretNames(await codeHost.isPrivate())
746
+ : [];
747
+ return {
748
+ tokens,
749
+ dependabot: (name) => own.includes(name)
750
+ ? "set"
751
+ : organization === null
752
+ ? isOrganization
753
+ ? "unknown"
754
+ : "missing"
755
+ : organization.includes(name)
756
+ ? "set"
757
+ : "missing",
758
+ };
759
+ }
760
+ const forWhich = (a) => a.actions && a.dependabot
761
+ ? "for Actions and for Dependabot"
762
+ : a.actions
763
+ ? "for Actions"
764
+ : "for Dependabot";
@@ -0,0 +1,29 @@
1
+ export declare const NPMRC = ".npmrc";
2
+ export type SignIn = {
3
+ name: string;
4
+ key: string;
5
+ };
6
+ export type Npmrc = {
7
+ /** Each variable a sign-in line reads, once, in the order first read. */
8
+ names: string[];
9
+ signIns: SignIn[];
10
+ /** Each registry URL a `registry=` or `@scope:registry=` line names. */
11
+ registries: string[];
12
+ };
13
+ export declare function readNpmrc(text: string | null): Npmrc;
14
+ /** The `.npmrc` at the root, read; nothing when there is none. */
15
+ export declare function npmrcAt(root: string): Npmrc;
16
+ /** Why a name can't be set from a secret, or null when it can. */
17
+ export declare function refusal(name: string): string | null;
18
+ /** The first refusal among the names, or null. */
19
+ export declare const firstRefusal: (n: Npmrc) => string | null;
20
+ declare const bare: (url: string) => string;
21
+ /** The registry a sign-in line is for: the registry URL whose host and
22
+ * path its key starts with, the longest when several do, or else the
23
+ * key's own `//host/path/`. */
24
+ export declare function addressOf(n: Npmrc, name: string): string;
25
+ /** The registries Dependabot has to be told, the public one aside. */
26
+ export declare const privateRegistries: (n: Npmrc) => string[];
27
+ /** The registry `.npmrc` sends a package's scope to, or null. */
28
+ export declare function npmrcRegistry(text: string | null, pkg: string): string | null;
29
+ export { bare as bareRegistry };
package/dist/npmrc.mjs ADDED
@@ -0,0 +1,98 @@
1
+ // What the factory reads from the repository's own `.npmrc`: the variables
2
+ // its sign-in lines read, which the workflows set from secrets of the same
3
+ // names, and the registries it names, which Dependabot has to know.
4
+ import { existsSync, readFileSync } from "node:fs";
5
+ import { join } from "node:path";
6
+ export const NPMRC = ".npmrc";
7
+ const SYNC = "npx --no-install factory sync";
8
+ const PUBLIC_REGISTRY = "https://registry.npmjs.org/";
9
+ const SIGN_IN = /:(_authToken|_auth|_password|username)$/;
10
+ /** npm's own pattern (`@npmcli/config`'s `env-replace.js`): an odd run of
11
+ * backslashes before `${` makes it text. */
12
+ const VARIABLE = /(?<!\\)(\\*)\$\{([^${}?]+)(\?)?\}/g;
13
+ /** The key and value of each setting line, as npm's `ini` reads them. */
14
+ function entries(text) {
15
+ const out = [];
16
+ for (const raw of text.split(/\r?\n/)) {
17
+ const line = raw.trim();
18
+ if (!line || line.startsWith("#") || line.startsWith(";"))
19
+ continue;
20
+ const at = line.indexOf("=");
21
+ if (at < 0)
22
+ continue;
23
+ const key = line.slice(0, at).trim();
24
+ let value = line.slice(at + 1).trim();
25
+ if (/^(".*"|'.*')$/.test(value))
26
+ value = value.slice(1, -1);
27
+ out.push({ key, value });
28
+ }
29
+ return out;
30
+ }
31
+ /** The variables a value reads. */
32
+ function variables(value) {
33
+ const out = [];
34
+ for (const m of value.matchAll(VARIABLE))
35
+ if (m[1].length % 2 === 0)
36
+ out.push(m[2]);
37
+ return out;
38
+ }
39
+ export function readNpmrc(text) {
40
+ const found = { names: [], signIns: [], registries: [] };
41
+ if (!text)
42
+ return found;
43
+ for (const { key, value } of entries(text)) {
44
+ if (key === "registry" || /^@[^:]+:registry$/.test(key)) {
45
+ if (!found.registries.includes(value))
46
+ found.registries.push(value);
47
+ continue;
48
+ }
49
+ if (!SIGN_IN.test(key))
50
+ continue;
51
+ for (const name of variables(value)) {
52
+ found.signIns.push({ name, key });
53
+ if (!found.names.includes(name))
54
+ found.names.push(name);
55
+ }
56
+ }
57
+ return found;
58
+ }
59
+ /** The `.npmrc` at the root, read; nothing when there is none. */
60
+ export function npmrcAt(root) {
61
+ const path = join(root, NPMRC);
62
+ return readNpmrc(existsSync(path) ? readFileSync(path, "utf8") : null);
63
+ }
64
+ /** Why a name can't be set from a secret, or null when it can. */
65
+ export function refusal(name) {
66
+ if (name === "GITHUB_TOKEN")
67
+ return null;
68
+ if (name.startsWith("GITHUB_"))
69
+ return `${NPMRC} reads \${${name}} to sign in, and GitHub refuses a secret whose name starts with GITHUB_. Rename it in ${NPMRC}, then run: ${SYNC}`;
70
+ if (["HOME", "PATH", "CI"].includes(name) || /^(RUNNER|ACTIONS)_/.test(name))
71
+ return `${NPMRC} reads \${${name}} to sign in, and the runner sets ${name} for itself. Rename it in ${NPMRC}, then run: ${SYNC}`;
72
+ return null;
73
+ }
74
+ /** The first refusal among the names, or null. */
75
+ export const firstRefusal = (n) => n.names.map(refusal).find((r) => r !== null) ?? null;
76
+ const bare = (url) => url.replace(/^[a-z]+:/i, "").replace(/\/+$/, "");
77
+ /** The registry a sign-in line is for: the registry URL whose host and
78
+ * path its key starts with, the longest when several do, or else the
79
+ * key's own `//host/path/`. */
80
+ export function addressOf(n, name) {
81
+ const key = n.signIns.find((s) => s.name === name)?.key ?? "";
82
+ const at = key.replace(SIGN_IN, "");
83
+ const match = n.registries
84
+ .filter((r) => at === bare(r) || at.startsWith(`${bare(r)}/`))
85
+ .sort((a, b) => bare(b).length - bare(a).length)[0];
86
+ return match ?? at;
87
+ }
88
+ /** The registries Dependabot has to be told, the public one aside. */
89
+ export const privateRegistries = (n) => n.registries.filter((r) => bare(r) !== bare(PUBLIC_REGISTRY));
90
+ /** The registry `.npmrc` sends a package's scope to, or null. */
91
+ export function npmrcRegistry(text, pkg) {
92
+ if (!text || !pkg.startsWith("@"))
93
+ return null;
94
+ const scope = pkg.split("/")[0];
95
+ const found = entries(text).find((e) => e.key === `${scope}:registry`);
96
+ return found ? found.value : null;
97
+ }
98
+ export { bare as bareRegistry };
@@ -34,8 +34,6 @@ export declare function installError(name: string, stderr: string, registry: str
34
34
  /** Whether a group in `.github/dependabot.yml` has the package as its only
35
35
  * pattern. */
36
36
  export declare function hasOwnGroup(text: string | null, pkg: string): Promise<boolean>;
37
- /** The registry `.npmrc` sends a package's scope to, or null. */
38
- export declare function npmrcRegistry(text: string | null, pkg: string): string | null;
39
37
  /** The lines `preset add` ends with for what Dependabot still needs. */
40
38
  export declare function nextLines(dependabot: string | null, npmrc: string | null, pkg: string): Promise<string[]>;
41
39
  export declare function add(argv: string[], d: PresetDeps): Promise<number>;
@@ -14,6 +14,7 @@ import { STATUS_CODES } from "node:http";
14
14
  import { dirname, join, relative, sep } from "node:path";
15
15
  import { filesDeps, parseChoices, repoRoot, resolveFiles, SETTINGS_FILE, SettingsError, } from "./config.mjs";
16
16
  import { CHOICES_FILE, choicesText, findPackage, LOCK_FILE, OWN, PLUGIN_LISTS, presetFaults, PRESET_FILE, readLock, shipped, shipsText, splitName, stable, staleMessages, } from "./preset.mjs";
17
+ import { npmrcRegistry } from "./npmrc.mjs";
17
18
  const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
18
19
  const DEPENDABOT = ".github/dependabot.yml";
19
20
  // ---------------------------------------------------------------- Values
@@ -246,18 +247,6 @@ export async function hasOwnGroup(text, pkg) {
246
247
  g.patterns.length === 1 &&
247
248
  g.patterns[0] === pkg));
248
249
  }
249
- /** The registry `.npmrc` sends a package's scope to, or null. */
250
- export function npmrcRegistry(text, pkg) {
251
- if (!text || !pkg.startsWith("@"))
252
- return null;
253
- const scope = pkg.split("/")[0];
254
- for (const line of text.split("\n")) {
255
- const m = /^\s*(@[^:\s]+):registry\s*=\s*(\S+)\s*$/.exec(line);
256
- if (m && m[1] === scope)
257
- return m[2];
258
- }
259
- return null;
260
- }
261
250
  const bare = (url) => url.replace(/\/+$/, "");
262
251
  /** The lines `preset add` ends with for what Dependabot still needs. */
263
252
  export async function nextLines(dependabot, npmrc, pkg) {
@@ -856,6 +845,7 @@ export async function changes(argv, d) {
856
845
  version: "",
857
846
  presets: [],
858
847
  hash: null,
848
+ npmrcVariables: [],
859
849
  settings: {},
860
850
  overridden: {},
861
851
  files: [],
package/dist/preset.d.mts CHANGED
@@ -143,6 +143,8 @@ export type Lock = {
143
143
  version: string;
144
144
  }[];
145
145
  hash: string | null;
146
+ /** The variables `.npmrc`'s sign-in lines read at the last sync. */
147
+ npmrcVariables: string[];
146
148
  settings: Obj | null;
147
149
  overridden: Record<string, Replaced[]>;
148
150
  files: string[];
@@ -161,6 +163,8 @@ export type StaleDeps = {
161
163
  * undefined when there is no node_modules to look in. */
162
164
  installed: (pkg: string) => string | null | undefined;
163
165
  load: (t: string) => unknown;
166
+ /** The variables `.npmrc`'s sign-in lines read now. */
167
+ npmrcNames?: string[];
164
168
  };
165
169
  /** Why the lock is stale, the first of: missing, from an earlier release,
166
170
  * a settings file changed, a preset not installed, a preset at another
package/dist/preset.mjs CHANGED
@@ -9,6 +9,7 @@ import { dirname, join, relative, sep } from "node:path";
9
9
  import { DEFAULT_CODE_HOST } from "./code-host/index.mjs";
10
10
  import { ROLE_SHAPE, ROLES, SETTINGS_FILE, SETTINGS_KEYS } from "./config.mjs";
11
11
  import { BUILT } from "./tool-names.mjs";
12
+ import { NPMRC, refusal } from "./npmrc.mjs";
12
13
  export const PRESET_FILE = "factory-preset.yaml";
13
14
  export const CHOICES_FILE = ".claude/factory.choices.yaml";
14
15
  export const LOCK_FILE = ".claude/factory.lock";
@@ -509,6 +510,9 @@ export function readLock(text, load) {
509
510
  }))
510
511
  : [],
511
512
  hash: typeof d["settings-hash"] === "string" ? d["settings-hash"] : null,
513
+ npmrcVariables: Array.isArray(d["npmrc-variables"])
514
+ ? d["npmrc-variables"].map(String)
515
+ : [],
512
516
  settings: isObj(d.settings) ? d.settings : null,
513
517
  overridden: isObj(d.overridden)
514
518
  ? d.overridden
@@ -536,6 +540,12 @@ export function staleReason(d) {
536
540
  const choicesOnly = changed.includes(CHOICES_FILE) && !changed.includes(SETTINGS_FILE);
537
541
  return staleMessages.changed(choicesOnly ? CHOICES_FILE : SETTINGS_FILE);
538
542
  }
543
+ const names = d.npmrcNames ?? [];
544
+ const refused = names.map(refusal).find((r) => r !== null);
545
+ if (refused)
546
+ return refused;
547
+ if (names.join("\n") !== lock.npmrcVariables.join("\n"))
548
+ return staleMessages.changed(NPMRC);
539
549
  for (const p of lock.presets) {
540
550
  const v = d.installed(splitName(p.name).pkg);
541
551
  if (v === null)
@@ -11,6 +11,17 @@ const FAILED = ["failure", "timed_out", "startup_failure"];
11
11
  export function githubActionsRunner(o) {
12
12
  const t = o.transport;
13
13
  const API = `repos/${o.repository}`;
14
+ /** Every secret a listing names, page by page: the list is an object,
15
+ * not an array, so it is paged by hand. */
16
+ const secretsAt = async (path) => {
17
+ const all = [];
18
+ for (let page = 1;; page++) {
19
+ const listed = await t.rest("GET", `${path}?per_page=100&page=${page}`);
20
+ all.push(...listed.secrets);
21
+ if (listed.secrets.length < 100)
22
+ return all;
23
+ }
24
+ };
14
25
  const reviewsOf = async (sha) => (await t.rest("GET", `${API}/actions/workflows/${REVIEW_WORKFLOW}/runs?head_sha=${sha}&per_page=5`)).workflow_runs;
15
26
  return {
16
27
  async startBuild(ticket, branch) {
@@ -90,20 +101,46 @@ export function githubActionsRunner(o) {
90
101
  throw error;
91
102
  }
92
103
  },
93
- async secretNames() {
94
- // The list is an object, not an array, so it is paged by hand.
95
- const names = [];
96
- for (let page = 1;; page++) {
97
- const listed = await t.rest("GET", `${API}/actions/secrets?per_page=100&page=${page}`);
98
- names.push(...listed.secrets.map((x) => x.name));
99
- if (listed.secrets.length < 100)
100
- return names;
101
- }
102
- },
104
+ secretNames: async () => (await secretsAt(`${API}/actions/secrets`)).map((x) => x.name),
103
105
  async setSecret(name, value) {
104
106
  if (!o.cli)
105
107
  throw new Error("Storing a secret needs the GitHub CLI.");
106
108
  await o.cli(["secret", "set", name, "--repo", o.repository], value);
107
109
  },
110
+ dependabotSecretNames: async () => (await secretsAt(`${API}/dependabot/secrets`)).map((x) => x.name),
111
+ async setDependabotSecret(name, value) {
112
+ if (!o.cli)
113
+ throw new Error("Storing a secret needs the GitHub CLI.");
114
+ await o.cli(["secret", "set", name, "--app", "dependabot", "--repo", o.repository], value);
115
+ },
116
+ organizationSecretNames: async () => (await secretsAt(`${API}/actions/organization-secrets`)).map((x) => x.name),
117
+ async organizationDependabotSecretNames(isPrivate) {
118
+ const org = `orgs/${o.repository.split("/")[0]}/dependabot/secrets`;
119
+ try {
120
+ const names = [];
121
+ for (const s of await secretsAt(org)) {
122
+ if (s.visibility === "all" ||
123
+ (s.visibility === "private" && isPrivate))
124
+ names.push(s.name);
125
+ else if (s.visibility === "selected") {
126
+ for (let page = 1;; page++) {
127
+ const shared = await t.rest("GET", `${org}/${s.name}/repositories?per_page=100&page=${page}`);
128
+ if (shared.repositories.some((r) => r.full_name === o.repository)) {
129
+ names.push(s.name);
130
+ break;
131
+ }
132
+ if (shared.repositories.length < 100)
133
+ break;
134
+ }
135
+ }
136
+ }
137
+ return names;
138
+ }
139
+ catch (error) {
140
+ if (statusOf(error) !== null)
141
+ return null;
142
+ throw error;
143
+ }
144
+ },
108
145
  };
109
146
  }
@@ -60,4 +60,17 @@ export type Runner = {
60
60
  /** Stores a secret the runner's jobs can read. The value never appears
61
61
  * in a command's arguments or its output. */
62
62
  setSecret(name: string, value: string): Promise<void>;
63
+ /** The names of the secrets the runner gives a job that the dependency
64
+ * bot's pull request starts. */
65
+ dependabotSecretNames(): Promise<string[]>;
66
+ /** Stores a secret for those jobs, as `setSecret` does. */
67
+ setDependabotSecret(name: string, value: string): Promise<void>;
68
+ /** The names of the secrets the repository's organization shares with
69
+ * it. Not called on a repository a person owns. */
70
+ organizationSecretNames(): Promise<string[]>;
71
+ /** The names of the organization's secrets for the dependency bot that
72
+ * reach this repository, which private ones do only when it is private,
73
+ * or null when the organization will not list them. Not called on a
74
+ * repository a person owns. */
75
+ organizationDependabotSecretNames(isPrivate: boolean): Promise<string[] | null>;
63
76
  };
package/dist/setup.d.mts CHANGED
@@ -7,7 +7,9 @@ import type { Tickets } from "./tickets/types.mts";
7
7
  * removing it is deleting that one rule. */
8
8
  export declare const RULE = "Software factory";
9
9
  export type Check = {
10
- state: "pass" | "fail" | "off";
10
+ /** `unknown`: the check can't be made from the repository, and fails
11
+ * nothing. */
12
+ state: "pass" | "fail" | "off" | "unknown";
11
13
  text: string;
12
14
  /** What to do about a failure. */
13
15
  fix?: string;
package/dist/sync.d.mts CHANGED
@@ -19,6 +19,11 @@ export declare function withDefaultBranch(text: string, name: string, file: stri
19
19
  * more, so the steps after the session still run before the job is
20
20
  * stopped. */
21
21
  export declare function withMinutes(text: string, minutes: number, file: string): string;
22
+ /** A workflow whose jobs that install packages set each name in `names`
23
+ * from a secret of the same name, in the job's `env`, so every step that
24
+ * runs npm reads it, a composite action's included. With `GITHUB_TOKEN`
25
+ * among them, the workflow may also read packages. Only lines are added. */
26
+ export declare function withNpmEnv(text: string, names: string[], file: string): string;
22
27
  /** A copy with the rules' numbers the settings give in place of the
23
28
  * defaults. A phrase is replaced only when its number is not the default,
24
29
  * and must then match exactly once. */
@@ -66,6 +71,8 @@ export type LockParts = {
66
71
  version: string;
67
72
  }[];
68
73
  hash: string;
74
+ /** The variables `.npmrc`'s sign-in lines read. */
75
+ npmrcVariables: string[];
69
76
  /** The settings in effect, as `factory config explain` prints them. */
70
77
  settings: string[];
71
78
  overridden: Record<string, Replaced[]>;
package/dist/sync.mjs CHANGED
@@ -17,6 +17,7 @@
17
17
  import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from "node:fs";
18
18
  import { dirname, join, relative, sep } from "node:path";
19
19
  import { fileURLToPath } from "node:url";
20
+ import { firstRefusal, npmrcAt } from "./npmrc.mjs";
20
21
  import { filesDeps, repoRoot, resolveFiles, RULE_NUMBERS, staleOf, defaultDeps, } from "./config.mjs";
21
22
  import { CHOICES_FILE, choicesText, settingsHash, staleChoices, } from "./preset.mjs";
22
23
  import { branchDeps, CANNOT_TELL, defaultBranch, } from "./lib/default-branch.mjs";
@@ -93,6 +94,56 @@ export function withMinutes(text, minutes, file) {
93
94
  const session = one(/^(\s+minutes: )\d+$/gm, minutes, text);
94
95
  return one(/^(\s+timeout-minutes: )\d+$/gm, minutes + 10, session);
95
96
  }
97
+ /** A workflow whose jobs that install packages set each name in `names`
98
+ * from a secret of the same name, in the job's `env`, so every step that
99
+ * runs npm reads it, a composite action's included. With `GITHUB_TOKEN`
100
+ * among them, the workflow may also read packages. Only lines are added. */
101
+ export function withNpmEnv(text, names, file) {
102
+ if (!names.length)
103
+ return text;
104
+ const lines = text.split("\n");
105
+ const jobsAt = lines.indexOf("jobs:");
106
+ if (jobsAt < 0)
107
+ return text;
108
+ const starts = lines
109
+ .map((l, i) => (i > jobsAt && /^ {2}[A-Za-z0-9_-]+:\s*$/.test(l) ? i : -1))
110
+ .filter((i) => i >= 0);
111
+ const entries = names.map((n) => ` ${n}: \${{ secrets.${n} }}`);
112
+ const inserts = [];
113
+ starts.forEach((start, k) => {
114
+ const end = starts[k + 1] ?? lines.length;
115
+ const job = lines.slice(start, end);
116
+ const installs = job.some((l) => (/\bnpm ci\b/.test(l) && !/^\s*#/.test(l)) ||
117
+ /^\s+uses: \.\/\.github\/actions\/factory-agent\s*$/.test(l));
118
+ if (!installs)
119
+ return;
120
+ const env = job.findIndex((l) => /^ {4}env:\s*$/.test(l));
121
+ const runsOn = job.findIndex((l) => /^ {4}runs-on:/.test(l));
122
+ const permissions = job.findIndex((l) => /^ {4}permissions:\s*$/.test(l));
123
+ if (names.includes("GITHUB_TOKEN") && permissions >= 0)
124
+ inserts.push({
125
+ at: start + permissions + 1,
126
+ lines: [" packages: read"],
127
+ });
128
+ if (env >= 0)
129
+ inserts.push({ at: start + env + 1, lines: entries });
130
+ else if (runsOn >= 0)
131
+ inserts.push({ at: start + runsOn + 1, lines: [" env:", ...entries] });
132
+ else
133
+ throw new Error(`${file}: expected a runs-on line in each job that installs, to set its env`);
134
+ });
135
+ if (!inserts.length)
136
+ return text;
137
+ if (names.includes("GITHUB_TOKEN")) {
138
+ const permissions = lines.indexOf("permissions:");
139
+ if (permissions < 0)
140
+ throw new Error(`${file}: expected a permissions block, to let GITHUB_TOKEN read packages`);
141
+ inserts.push({ at: permissions + 1, lines: [" packages: read"] });
142
+ }
143
+ for (const { at, lines: added } of inserts.sort((a, b) => b.at - a.at))
144
+ lines.splice(at, 0, ...added);
145
+ return lines.join("\n");
146
+ }
96
147
  const WORDS = [
97
148
  "zero",
98
149
  "one",
@@ -375,6 +426,9 @@ export function lockText(l) {
375
426
  ]
376
427
  : ["presets: []"]),
377
428
  `settings-hash: ${l.hash}`,
429
+ ...(l.npmrcVariables.length
430
+ ? ["npmrc-variables:", ...l.npmrcVariables.map((n) => ` - ${n}`)]
431
+ : ["npmrc-variables: []"]),
378
432
  "settings:",
379
433
  ...l.settings.map((line) => ` ${line}`),
380
434
  ...(replaced.length
@@ -451,19 +505,23 @@ export async function plan(pkg, root, r, branch) {
451
505
  const read = (p) => existsSync(join(root, p)) ? readFileSync(join(root, p), "utf8") : null;
452
506
  const write = new Map();
453
507
  const has = (p) => existsSync(join(root, p));
508
+ const npmrc = npmrcAt(root);
454
509
  for (const [from, to] of copies(pkg, s, has)) {
455
510
  const source = readFileSync(join(pkg, from), "utf8");
456
511
  const text = PUSH_WORKFLOWS.includes(from)
457
512
  ? withDefaultBranch(source, branch, from)
458
513
  : source;
459
514
  const kind = SESSION_WORKFLOWS[from.replace(/^workflows\//, "")];
460
- write.set(to, kind && from.startsWith("workflows/")
515
+ const written = kind && from.startsWith("workflows/")
461
516
  ? withMinutes(text, s.sessionMinutes[kind], from)
462
517
  : from === POLLER_WORKFLOW
463
518
  ? withSchedule(text, s.builds.pollMinutes, from)
464
519
  : from === AUTO_MERGE_WORKFLOW
465
520
  ? withPresetPackages(text, [...new Set(r.presets.map((p) => p.pkg))], from)
466
- : withRules(text, s.rules, from));
521
+ : withRules(text, s.rules, from);
522
+ write.set(to, from.startsWith("workflows/")
523
+ ? withNpmEnv(written, npmrc.names, from)
524
+ : written);
467
525
  }
468
526
  // A preset's agent or skill, unless the factory's own file or one the
469
527
  // repository wrote itself is at its path: those always stay.
@@ -499,6 +557,7 @@ export async function plan(pkg, root, r, branch) {
499
557
  version: manifest.version,
500
558
  presets: r.presets.map((p) => ({ name: p.name, version: p.version })),
501
559
  hash: settingsHash(r.ownText, chosen),
560
+ npmrcVariables: npmrc.names,
502
561
  settings,
503
562
  overridden: Object.fromEntries(r.resolution.overridden),
504
563
  files,
@@ -538,6 +597,11 @@ export async function main(argv, d) {
538
597
  }
539
598
  }
540
599
  r = await d.settings();
600
+ const refused = firstRefusal(npmrcAt(d.root));
601
+ if (refused) {
602
+ d.err(refused);
603
+ return 1;
604
+ }
541
605
  }
542
606
  catch (e) {
543
607
  d.err(e instanceof Error ? e.message : String(e));
@@ -312,6 +312,10 @@ gh secret set FACTORY_BUILD_TOKEN # builds in the cloud, with no board
312
312
  gh secret set FACTORY_AUTOMERGE_TOKEN # pull requests that merge themselves
313
313
  ```
314
314
 
315
+ For a private npm registry, each variable your `.npmrc` reads is stored
316
+ twice, with `gh secret set NAME` and `gh secret set NAME --app dependabot`:
317
+ [Private npm packages](setup.md#private-npm-packages).
318
+
315
319
  Two optional settings:
316
320
 
317
321
  - **Paying by the token instead of a subscription:** store an API key from
@@ -40,6 +40,7 @@ The "Removing it" column says what `factory remove` does with each.
40
40
  | ------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
41
41
  | Secrets and variables named `FACTORY_...` | You create them | Delete them |
42
42
  | `CLAUDE_CODE_OAUTH_TOKEN` | You create it, for the automated review and builds in the cloud | Delete it, unless another workflow uses it |
43
+ | The secrets your `.npmrc` reads, such as `NPM_TOKEN`, for Actions and for Dependabot | `init`, when you paste them | Leave them if your own CI uses them; otherwise delete both copies |
43
44
  | Labels: `merge: automatic`, `merge: manual`, `verdict: override`, `follow-up`, `spec` | First use | Delete them. Deleting a label removes it from every ticket |
44
45
  | A CI check that the factory's files are in step | Setup | Goes with `factory-check.yml` |
45
46
  | A "Review verdict" required check, as the ruleset "Software factory" | `init`, when the review is on; or you, in your branch rules | Delete the ruleset, under Settings, Rules, **first**, or pull requests wait on it forever |
@@ -253,6 +254,10 @@ factory.
253
254
  session step's timeout.
254
255
  - GitHub's shortest schedule is every five minutes, and scheduled runs can
255
256
  start late.
257
+ - **A pull request from a fork can't install a private package.** GitHub
258
+ gives a fork's pull request no secrets, so the factory check fails at
259
+ `npm ci` on one, in a repository with
260
+ [private npm packages](setup.md#private-npm-packages).
256
261
  - Public repositories are not billed for Actions minutes.
257
262
  - GitHub switches off scheduled workflows in a public repository with no
258
263
  activity for 60 days.
@@ -42,13 +42,14 @@ machine, which is all the [quick start](../quick-start.md) needs.
42
42
 
43
43
  It then asks only what your parts need:
44
44
 
45
- | Question | Asked when you chose | What you do |
46
- | ------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
47
- | Which board | A board | Choose a new one, made with the factory's columns, or a Project you already have |
48
- | Which files may merge without you | Pull requests that merge themselves | Type their patterns, such as `docs/**`. Start with a short list |
49
- | Where the poller runs | Builds that start from the board | Choose a schedule on GitHub Actions or a server you host. [Builds in the cloud](../builds.md) compares them |
50
- | The token `claude setup-token` prints | The review, and builds in the cloud | It runs the command for you. Follow what it says, then paste the token it prints |
51
- | A GitHub access token | A board, builds in the cloud, and pull requests that merge themselves | It opens GitHub's page with the right scopes checked. Choose an expiry, generate the token, and paste it |
45
+ | Question | Asked when you chose | What you do |
46
+ | ------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
47
+ | Which board | A board | Choose a new one, made with the factory's columns, or a Project you already have |
48
+ | Which files may merge without you | Pull requests that merge themselves | Type their patterns, such as `docs/**`. Start with a short list |
49
+ | Where the poller runs | Builds that start from the board | Choose a schedule on GitHub Actions or a server you host. [Builds in the cloud](../builds.md) compares them |
50
+ | The token `claude setup-token` prints | The review, and builds in the cloud | It runs the command for you. Follow what it says, then paste the token it prints |
51
+ | A GitHub access token | A board, builds in the cloud, and pull requests that merge themselves | It opens GitHub's page with the right scopes checked. Choose an expiry, generate the token, and paste it |
52
+ | The token your `.npmrc` reads | Nothing: it asks whenever `.npmrc` reads one ([Private npm packages](#private-npm-packages)) | Paste a token that can only read from your registry |
52
53
 
53
54
  A token is typed into a masked prompt and goes straight to your
54
55
  repository's secrets on GitHub. It is never printed or written to a file.
@@ -120,10 +121,142 @@ factory doctor
120
121
 
121
122
  runs the checks again at any time: the settings, the factory's files, the
122
123
  installed version, who the GitHub CLI is signed in as, that each secret
123
- your parts read is set, and the board's columns. GitHub never lets a
124
+ your parts read is set, those for
125
+ [private npm packages](#private-npm-packages), and the board's columns. GitHub never lets a
124
126
  secret be read back, so a wrong one shows when the first run that needs it
125
127
  fails, naming it.
126
128
 
129
+ ## Private npm packages
130
+
131
+ For a repository that installs a package from a private registry, such as
132
+ your company's own packages or a private [preset](../presets.md). At the
133
+ end, the factory's workflows install it as your machine does, and
134
+ Dependabot offers its new versions.
135
+
136
+ ### 1. Read the token from a variable in `.npmrc`
137
+
138
+ The workflows sign in to your registry the way npm does on your machine:
139
+ from the `.npmrc` at the root of your repository, which you commit. It
140
+ needs two lines, one that sends your packages' scope to the registry and
141
+ one that reads the token from an environment variable:
142
+
143
+ ```ini
144
+ @acme:registry=https://acme.jfrog.io/artifactory/api/npm/npm/
145
+ //acme.jfrog.io/artifactory/api/npm/npm/:_authToken=${NPM_TOKEN}
146
+ ```
147
+
148
+ Your registry's documentation gives both lines with its own address. The
149
+ variable can have any name; the factory stores the token as a secret of
150
+ the same name, so wherever this section says `NPM_TOKEN`, use yours. On
151
+ your machine, set the variable in your shell's profile, such as
152
+ `export NPM_TOKEN=...`. If the token line is only in your own
153
+ `~/.npmrc`, move it into this file with the variable in place of the
154
+ token: the workflows read only this one.
155
+
156
+ **It worked when** `npm ci` succeeds on your machine with the variable
157
+ set.
158
+
159
+ #### GitHub Packages
160
+
161
+ Read `${GITHUB_TOKEN}` in the token line. In the workflows it is their own
162
+ token, which can read the packages that give this repository access, so
163
+ `init` asks for nothing and you skip step 2. On your machine, set
164
+ `GITHUB_TOKEN` to a personal access token with the `read:packages` scope.
165
+ Dependabot has no token of its own for it: in step 4, store that personal
166
+ access token with `gh secret set PACKAGES_TOKEN --app dependabot`, and
167
+ name `PACKAGES_TOKEN` in place of `NPM_TOKEN`.
168
+
169
+ ### 2. Make a read-only token
170
+
171
+ On your registry, make a token that can only read, and only the packages
172
+ this repository installs. Builds and reviews in the cloud hold it while
173
+ they work, and they read tickets and pull requests that anyone with access
174
+ to the repository can write, so a read-only token is all that text could
175
+ ever lead one to give away.
176
+
177
+ ### 3. Store it with `factory init`
178
+
179
+ ```bash
180
+ factory init
181
+ ```
182
+
183
+ Under "Found", `init` lists `.npmrc` and the variable it reads. Then it
184
+ asks you to paste the token, rewrites the factory's workflows under
185
+ `.github/workflows/` to pass the token to npm, and stores it twice: as an
186
+ Actions secret, and as a Dependabot secret, since a workflow that
187
+ Dependabot's pull request starts can read only Dependabot secrets. If
188
+ `.npmrc` isn't listed under "Found", the token line is missing from the
189
+ file at your repository's root.
190
+
191
+ If your organization already shares the secret with this repository,
192
+ `init` does not ask for the Actions copy. It still asks for the Dependabot
193
+ copy, since only an organization admin can see whether the organization
194
+ sets that one: leave it empty if yours does. To set both once for every
195
+ repository, an organization admin runs:
196
+
197
+ ```bash
198
+ gh secret set NPM_TOKEN --org acme --visibility all
199
+ gh secret set NPM_TOKEN --org acme --visibility all --app dependabot
200
+ ```
201
+
202
+ ### 4. Tell Dependabot the registry
203
+
204
+ Skip this without a `.github/dependabot.yml`, or when your organization
205
+ sets the registry for Dependabot, which an organization admin can tell
206
+ you. Otherwise add the registry, and name it in your npm entry, or
207
+ Dependabot never sees a new version of a package from there:
208
+
209
+ ```yaml
210
+ registries:
211
+ acme: # any name; the npm entry uses it
212
+ type: npm-registry
213
+ url: https://acme.jfrog.io/artifactory/api/npm/npm/ # as in .npmrc
214
+ token: ${{secrets.NPM_TOKEN}} # the Dependabot secret from step 3
215
+ updates:
216
+ - package-ecosystem: npm
217
+ directory: /
218
+ registries: [acme]
219
+ schedule:
220
+ interval: weekly
221
+ ```
222
+
223
+ ### 5. Check it, and merge
224
+
225
+ Run `factory doctor`. **It worked when** it shows:
226
+
227
+ ```text
228
+ ✓ NPM_TOKEN is set, for installing what .npmrc names
229
+ ✓ NPM_TOKEN is set for Dependabot, for installing on Dependabot's pull requests
230
+ ✓ .github/dependabot.yml uses https://acme.jfrog.io/artifactory/api/npm/npm/ for its npm updates
231
+ ```
232
+
233
+ Without a `.github/dependabot.yml` there is no third line. A line that
234
+ starts with `?` is one `doctor` cannot check from the repository, such as
235
+ a secret or a registry your organization may set, which only an
236
+ organization admin can see. It fails nothing.
237
+
238
+ Then commit `.npmrc` and what `init` wrote on a branch, open a pull
239
+ request, and merge it as any other change. The pull request's own
240
+ "Factory check" is the last check: its "Install dependencies" step passes
241
+ once the workflows can sign in.
242
+
243
+ ### Replacing the token
244
+
245
+ When the token expires, the next workflow fails at `npm ci` with a 401.
246
+ Store the new one in both places:
247
+
248
+ ```bash
249
+ gh secret set NPM_TOKEN
250
+ gh secret set NPM_TOKEN --app dependabot
251
+ ```
252
+
253
+ or run `factory init` and answer yes when it asks to replace the secrets
254
+ already set. An organization admin runs the two commands in step 3
255
+ again instead.
256
+
257
+ If you rename the variable in `.npmrc`, the factory's commands stop and
258
+ say to run `factory sync`, which rewrites the workflows for the new name.
259
+
127
260
  ## Doing it by hand
128
261
 
129
262
  [Setting up on GitHub by hand](by-hand.md) has every step `init` takes,
@@ -48,9 +48,6 @@ as a code host's billing or what its workflows can see, are in
48
48
  then guards the old branch and not the new one. After the rename, run
49
49
  that command in each checkout, then `factory sync`, which writes the
50
50
  name into two workflows.
51
- - **A private [preset](presets.md) works on your machine, not yet in the
52
- factory's workflows.** _[Planned](developing.md#what-is-built)_: the
53
- workflows can't install a private package yet.
54
51
  - **One lock file is rebuilt for you after a conflict,** the one
55
52
  [`commands.relock`](configuration.md#commandsrelock) rebuilds, npm's by
56
53
  default. A second, such as another package manager's beside the
package/docs/presets.md CHANGED
@@ -391,16 +391,12 @@ it gets a pull request at its dependency bot's next run, as
391
391
 
392
392
  A preset is an npm package, so a private one installs on your machine the
393
393
  way any other private package does, from whichever registry your company
394
- uses, through your repository's `.npmrc`. Give the preset a Dependabot
395
- group of its own, the way
394
+ uses, through your repository's `.npmrc`.
395
+ [Private npm packages](github/setup.md#private-npm-packages) sets up the
396
+ factory's workflows and Dependabot to install it too. Give the preset a
397
+ Dependabot group of its own as well, the way
396
398
  [Dependency bots](github/reference.md#dependency-bots) does for the
397
- factory, and add its registry under `registries` in
398
- `.github/dependabot.yml`, so Dependabot sees its new versions.
399
- `factory preset add` names either one that's missing.
400
-
401
- _[Planned](developing.md#what-is-built)_: the factory's workflows can't
402
- install a private package yet, so a private preset works on your machine
403
- and not yet in the factory's workflows.
399
+ factory. `factory preset add` names what's missing.
404
400
 
405
401
  **It worked when** `factory doctor` shows:
406
402
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@davidbyoung/software-factory",
3
- "version": "0.1.7",
3
+ "version": "0.1.8",
4
4
  "description": "Refines, builds, and reviews tickets with Claude Code sessions, from a board to a merged pull request.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -150,6 +150,10 @@ changed the settings' shape, as version 2 does.
150
150
  Stop (step 6), and say the settings are the owner's to move, as "Moving to
151
151
  settings version 2" in the factory's `docs/updating.md` says for that
152
152
  release. Never edit `.claude/factory.yaml`.
153
+ When it fails on `.npmrc` instead, refusing a variable a sign-in line
154
+ reads, stop the same way and say the name is the owner's to change:
155
+ renaming it renames the secret and every developer's variable. Never edit
156
+ `.npmrc`.
153
157
 
154
158
  Commit what the sync wrote as a second commit, "Sync the factory's files to
155
159
  VERSION" or "Sync the settings to PACKAGE VERSION", and push. The push changes workflows, so it needs a token with