@warren-dean/code-kit 0.22.1 → 0.23.0

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.
@@ -82,7 +82,8 @@ function laneStandards(root, config, lane) {
82
82
  return lines.join('');
83
83
  }
84
84
 
85
- const marked = (body) => `${BEGIN(INSTRUCTIONS_VERSION)}\n${body.trim()}\n${END}`;
85
+ // With a blank line inside each marker, as Prettier writes markdown, so a project's format check passes (#77).
86
+ const marked = (body) => `${BEGIN(INSTRUCTIONS_VERSION)}\n\n${body.trim()}\n\n${END}`;
86
87
 
87
88
  /** The lead's section of CLAUDE.md, between its markers. */
88
89
  export function leadSection(root, config) {
@@ -13,6 +13,7 @@ import { decidedBy, laneOf, openRequests } from './rules.mjs';
13
13
  import { instructionsState } from './instructions.mjs';
14
14
  import { SECURITY_AGENT_FILE } from './security.mjs';
15
15
  import { laneClaims } from './laneclaims.mjs';
16
+ import { keptBecause, worktrees } from './worktrees.mjs';
16
17
  import { pickPerLane } from './schedule.mjs';
17
18
 
18
19
  export const DRAFT_FILE = '.claude/code-kit.draft.json';
@@ -77,7 +78,8 @@ const hasMarkdown = (dir) => {
77
78
  };
78
79
 
79
80
  /**
80
- * { step, why, args, then, attention, brief }. `brief`: the brief's open questions (ASK-4). `step` is a skill (spec-design, init, check, dispatch,
81
+ * { step, why, args, then, attention, brief, worktrees }. `brief`: the brief's open questions (ASK-4);
82
+ * `worktrees`: the merged ones still holding changes, { branch, story, changes, files }, for the person (LEAN-8). `step` is a skill (spec-design, init, check, dispatch,
81
83
  * review), `merge` (the head of the merge queue, where the lead merges), `wait` (lanes are
82
84
  * building) or `done`. `base(config)` resolves the branch lanes merge into.
83
85
  */
@@ -85,6 +87,8 @@ export function nextStep(root, base) {
85
87
  const attention = [];
86
88
  // ASK-4: the brief's open questions, for the person's Decisions tab.
87
89
  let briefQuestions = [];
90
+ // LEAN-8: merged worktrees still holding changes, for the person to keep or discard.
91
+ let holdingTrees = [];
88
92
  const result = (step, why, extra = {}) => ({
89
93
  step,
90
94
  why,
@@ -92,6 +96,7 @@ export function nextStep(root, base) {
92
96
  then: [],
93
97
  attention,
94
98
  brief: briefQuestions,
99
+ worktrees: holdingTrees,
95
100
  ...extra,
96
101
  });
97
102
  const isRepo = git(root, 'rev-parse', '--is-inside-work-tree') === 'true';
@@ -159,6 +164,26 @@ export function nextStep(root, base) {
159
164
  );
160
165
  }
161
166
 
167
+ // LEAN-8: worktrees that are done with are only disk space; prune takes them after each merge and as a
168
+ // session starts, and those still holding changes are the person's to keep or discard.
169
+ const trees = worktrees(root, config);
170
+ const leftovers = trees.filter((w) => !keptBecause(w) && !w.missing).length;
171
+ if (leftovers)
172
+ attention.push(
173
+ `${leftovers} worktree${leftovers === 1 ? ' is' : 's are'} done with; \`code-kit worktrees prune\` removes them, keeping their reports.`,
174
+ );
175
+ const holding = trees.filter((w) => w.kind === 'agent' && w.merged && !w.clean && !w.agentAtWork);
176
+ holdingTrees = holding.map((w) => ({
177
+ branch: w.branch,
178
+ story: w.story,
179
+ changes: w.changes,
180
+ files: w.files,
181
+ }));
182
+ if (holding.length)
183
+ attention.push(
184
+ `${holding.map((w) => w.branch).join(', ')} ${holding.length === 1 ? 'is' : 'are'} merged, but ${holding.length === 1 ? 'its worktree still holds' : 'their worktrees still hold'} uncommitted changes: the person keeps or discards each, from the band (discarding keeps them as a patch).`,
185
+ );
186
+
162
187
  const { specs, plan } = config.docs ?? {};
163
188
  if (!specs || !plan)
164
189
  return result(
@@ -256,12 +281,6 @@ export function nextStep(root, base) {
256
281
  attention.push(
257
282
  `${unbuildable.join(', ')} can't be dispatched until the plan's gaps are fixed.`,
258
283
  );
259
- // LEAN-6: worktrees whose story is merged and which hold nothing uncommitted are only disk space.
260
- const leftovers = mergedWorktrees(root, config);
261
- if (leftovers)
262
- attention.push(
263
- `${leftovers} worktree${leftovers === 1 ? ' is' : 's are'} merged and clean; \`code-kit worktrees prune\` removes them, keeping their reports.`,
264
- );
265
284
  // ONB-8: code-kit's own instructions to the lead and the lanes, brought up to date before the next step:
266
285
  // a newer code-kit's rules reach the agents only through them.
267
286
  const instructions = instructionsState(root, config);
@@ -524,23 +543,3 @@ export function missingSkills(root) {
524
543
  }
525
544
  return out;
526
545
  }
527
-
528
- /** LEAN-6: how many of the project's worktrees have a merged branch and nothing uncommitted. */
529
- function mergedWorktrees(root, config) {
530
- const list = git(root, 'worktree', 'list', '--porcelain');
531
- if (!list) return 0;
532
- const from = config.branches?.protected?.[0];
533
- if (!from || !git(root, 'rev-parse', '--verify', '-q', from)) return 0;
534
- let n = 0;
535
- for (const block of list.split('\n\n').slice(1)) {
536
- const path = /^worktree (.+)$/m.exec(block)?.[1];
537
- const branch = /^branch refs\/heads\/(.+)$/m.exec(block)?.[1];
538
- if (!path || !branch) continue;
539
- const merged =
540
- spawnSync('git', ['merge-base', '--is-ancestor', branch, from], { cwd: root }).status === 0;
541
- if (!merged) continue;
542
- const status = spawnSync('git', ['-C', path, 'status', '--porcelain'], { encoding: 'utf8' });
543
- if (status.status === 0 && !status.stdout.trim()) n++;
544
- }
545
- return n;
546
- }
@@ -1,10 +1,15 @@
1
- // What the npm registry says about a package, for the lead's delegated dependency approvals: the
2
- // licence, how often it's downloaded, when it was last released, and whether installing it runs
3
- // scripts. The rule itself is a pure function, so it's tested without the network.
1
+ // What the npm registry, or PyPI for a Python package, says about a package, for the lead's delegated
2
+ // dependency approvals: the licence, how often it's downloaded, when it was last released, and whether
3
+ // installing it runs scripts. The rule itself is a pure function, so it's tested without the network.
4
4
  import { DEPENDENCY_APPROVAL } from './dependencies.mjs';
5
5
 
6
6
  const REGISTRY = () => process.env.CODE_KIT_NPM_REGISTRY ?? 'https://registry.npmjs.org';
7
7
  const DOWNLOADS = () => process.env.CODE_KIT_NPM_DOWNLOADS ?? 'https://api.npmjs.org';
8
+ const PYPI = () => process.env.CODE_KIT_PYPI ?? 'https://pypi.org';
9
+ const PYPI_STATS = () => process.env.CODE_KIT_PYPI_STATS ?? 'https://pypistats.org';
10
+
11
+ /** The package managers whose packages come from PyPI. */
12
+ export const PYPI_MANAGERS = new Set(['pip', 'uv', 'poetry', 'pipenv', 'pdm']);
8
13
 
9
14
  /** The package an approval name stands for: `dep-@scope+pkg` → `@scope/pkg`. */
10
15
  export const packageOf = (approvalName) =>
@@ -69,6 +74,68 @@ export async function npmFacts(pkg) {
69
74
  }
70
75
  }
71
76
 
77
+ // PyPI's licence words as the SPDX ids a rule names: its classifiers first, then its free-text field.
78
+ const PYPI_LICENCES = [
79
+ [/\bMIT\b/i, 'MIT'],
80
+ [/\bApache\b.*2|Apache Software License/i, 'Apache-2.0'],
81
+ [/BSD.*3|3-Clause|New BSD|Modified BSD/i, 'BSD-3-Clause'],
82
+ [/BSD.*2|2-Clause|Simplified BSD/i, 'BSD-2-Clause'],
83
+ [/\bISC\b/i, 'ISC'],
84
+ [/Python Software Foundation|\bPSF\b/i, 'PSF-2.0'],
85
+ [/Mozilla Public License 2|\bMPL[- ]?2/i, 'MPL-2.0'],
86
+ [/\bLGPL/i, 'LGPL'],
87
+ [/\bAGPL/i, 'AGPL-3.0'],
88
+ [/\bGPL.*3|GPLv3/i, 'GPL-3.0'],
89
+ [/\bGPL.*2|GPLv2/i, 'GPL-2.0'],
90
+ ];
91
+
92
+ /** A PyPI project's licence as an SPDX id: its licence expression, else its classifiers, else its text. */
93
+ export function pypiLicence(info) {
94
+ if (info?.license_expression) return info.license_expression;
95
+ const words = [
96
+ ...(info?.classifiers ?? []).filter((c) => c.startsWith('License ::')),
97
+ ...(info?.license && info.license.length <= 80 ? [info.license] : []),
98
+ ];
99
+ for (const w of words) for (const [re, id] of PYPI_LICENCES) if (re.test(w)) return id;
100
+ return info?.license && info.license.length <= 40 ? info.license : 'unknown';
101
+ }
102
+
103
+ /**
104
+ * #70: the same facts for a Python package, from PyPI: a release with no wheel builds from source as it
105
+ * installs, which is what an npm install script that compiles is.
106
+ */
107
+ export async function pypiFacts(pkg) {
108
+ const name = encodeURIComponent(pkg.replace(/\[.*\]$/, '').toLowerCase());
109
+ try {
110
+ const meta = await fetch(`${PYPI()}/pypi/${name}/json`, {
111
+ headers: { accept: 'application/json' },
112
+ });
113
+ if (meta.status === 404) return { error: `${pkg} isn't on PyPI` };
114
+ if (!meta.ok) return { error: `PyPI answered ${meta.status} for ${pkg}` };
115
+ const doc = await meta.json();
116
+ const files = doc.urls ?? [];
117
+ const stats = await fetch(`${PYPI_STATS()}/api/packages/${name}/recent`, {
118
+ headers: { accept: 'application/json' },
119
+ });
120
+ const weeklyDownloads = stats.ok ? ((await stats.json()).data?.last_week ?? 0) : 0;
121
+ const wheel = files.some((f) => f.packagetype === 'bdist_wheel');
122
+ return {
123
+ licence: pypiLicence(doc.info),
124
+ weeklyDownloads,
125
+ lastRelease:
126
+ files
127
+ .map((f) => f.upload_time_iso_8601)
128
+ .filter(Boolean)
129
+ .sort()
130
+ .at(-1) ?? null,
131
+ installScripts: files.length > 0 && !wheel,
132
+ installScriptKind: files.length > 0 && !wheel ? 'build' : null,
133
+ };
134
+ } catch (e) {
135
+ return { error: `couldn't reach PyPI (${e.message})` };
136
+ }
137
+ }
138
+
72
139
  /** Why `facts` falls outside `rule`, as sentences; empty when it's within it. */
73
140
  export function dependencyRuleProblems(facts, rule, now = Date.now()) {
74
141
  if (facts.error) return [facts.error];
@@ -7,7 +7,16 @@
7
7
  // them the new-issue link to open; a report someone already filed gets a comment instead of a second issue.
8
8
  import { createHash } from 'node:crypto';
9
9
  import { execFileSync } from 'node:child_process';
10
- import { appendFileSync, mkdirSync, readFileSync, realpathSync } from 'node:fs';
10
+ import {
11
+ appendFileSync,
12
+ closeSync,
13
+ mkdirSync,
14
+ openSync,
15
+ readFileSync,
16
+ realpathSync,
17
+ statSync,
18
+ unlinkSync,
19
+ } from 'node:fs';
11
20
  import { homedir, platform, release } from 'node:os';
12
21
  import { dirname, join } from 'node:path';
13
22
  import { fileURLToPath } from 'node:url';
@@ -21,6 +30,47 @@ const PLUGIN = JSON.parse(
21
30
  export const REPO = PLUGIN.repository.replace(/^https:\/\/github\.com\//, '').replace(/\.git$/, '');
22
31
 
23
32
  const fileOf = (root) => join(projectWorktrees(root)[0] ?? root, REPORTS_FILE);
33
+ /** REPORT-3: held while a report is being sent, so a second Send can't file it again. */
34
+ const sendingOf = (root, id) => join(dirname(fileOf(root)), `report-sending-${id}`);
35
+ /** A send that's held its claim this long died before it finished, and the report is a draft again. */
36
+ const SENDING_MS = 5 * 60 * 1000;
37
+
38
+ function sendingSince(root, id, now = Date.now()) {
39
+ try {
40
+ const at = statSync(sendingOf(root, id)).mtimeMs;
41
+ return now - at < SENDING_MS ? at : null;
42
+ } catch {
43
+ return null;
44
+ }
45
+ }
46
+
47
+ /** Claims the send of `id`, or says it's being sent already: one claim, whichever process asks first. */
48
+ function claimSend(root, id, now = Date.now()) {
49
+ const file = sendingOf(root, id);
50
+ mkdirSync(dirname(file), { recursive: true });
51
+ for (let tries = 0; tries < 2; tries++) {
52
+ try {
53
+ closeSync(openSync(file, 'wx'));
54
+ return true;
55
+ } catch {
56
+ if (sendingSince(root, id, now) !== null) return false;
57
+ try {
58
+ unlinkSync(file);
59
+ } catch {
60
+ // taken by another send meanwhile
61
+ }
62
+ }
63
+ }
64
+ return false;
65
+ }
66
+
67
+ const releaseSend = (root, id) => {
68
+ try {
69
+ unlinkSync(sendingOf(root, id));
70
+ } catch {
71
+ // gone already
72
+ }
73
+ };
24
74
 
25
75
  function records(root) {
26
76
  try {
@@ -86,8 +136,8 @@ function bodyOf(r) {
86
136
  }
87
137
 
88
138
  /**
89
- * Every report, oldest first: { id, at, by, title, body, fingerprint, state: 'draft' | 'sent' | 'discarded',
90
- * sent: { at, url, comment } | null }.
139
+ * Every report, oldest first: { id, at, by, title, body, fingerprint, state: 'draft' | 'sending' | 'sent' |
140
+ * 'discarded', sent: { at, url, comment } | null }. `sending`: a Send is filing it now.
91
141
  */
92
142
  export function readReports(root) {
93
143
  const byId = new Map();
@@ -102,7 +152,9 @@ export function readReports(root) {
102
152
  });
103
153
  if (r.kind === 'discarded') d.state = 'discarded';
104
154
  }
105
- return [...byId.values()].map(({ kind, ...r }) => r);
155
+ return [...byId.values()].map(({ kind, ...r }) =>
156
+ r.state === 'draft' && sendingSince(root, r.id) !== null ? { ...r, state: 'sending' } : r,
157
+ );
106
158
  }
107
159
 
108
160
  export const draftReports = (root) => readReports(root).filter((r) => r.state === 'draft');
@@ -175,9 +227,24 @@ const gh = (args) =>
175
227
  * it already, otherwise a new issue; without a working `gh`, nothing is sent and the link is returned.
176
228
  */
177
229
  export function sendReport(root, id, now = Date.now()) {
178
- const r = readReports(root).find((x) => x.id === id);
179
- if (!r) return { ok: false, why: `There's no report ${id}.` };
180
- if (r.state !== 'draft') return { ok: false, why: `${id} was ${r.state} already.` };
230
+ const before = readReports(root).find((x) => x.id === id);
231
+ if (!before) return { ok: false, why: `There's no report ${id}.` };
232
+ if (before.state === 'sending') return { ok: false, why: `${id} is being sent already.` };
233
+ if (before.state !== 'draft') return { ok: false, why: `${id} was ${before.state} already.` };
234
+ if (!claimSend(root, id, now)) return { ok: false, why: `${id} is being sent already.` };
235
+ try {
236
+ // Another send may have finished between the read and the claim.
237
+ const r = readReports(root).find((x) => x.id === id);
238
+ if (r.sent || r.state === 'discarded')
239
+ return { ok: false, why: `${id} was ${r.sent ? 'sent' : 'discarded'} already.` };
240
+ return fileIssue(root, r, now);
241
+ } finally {
242
+ releaseSend(root, id);
243
+ }
244
+ }
245
+
246
+ function fileIssue(root, r, now) {
247
+ const { id } = r;
181
248
  let url;
182
249
  let comment = false;
183
250
  try {
@@ -240,6 +307,8 @@ export function sendReport(root, id, now = Date.now()) {
240
307
  export function discardReport(root, id, now = Date.now()) {
241
308
  const r = readReports(root).find((x) => x.id === id);
242
309
  if (!r) return { ok: false, why: `There's no report ${id}.` };
310
+ if (r.state === 'sending')
311
+ return { ok: false, why: `${id} is being sent, so it can't be discarded.` };
243
312
  if (r.state !== 'draft') return { ok: false, why: `${id} was ${r.state} already.` };
244
313
  append(root, { kind: 'discarded', id, at: new Date(now).toISOString() });
245
314
  return { ok: true };
@@ -388,7 +388,11 @@ function requestRecords(root) {
388
388
  export const readRequests = (root) => requestRecords(root).filter((r) => !r.drop);
389
389
 
390
390
  /** CARD-7: whether a request was dropped (the person dismissed it, or the lead said it's no longer needed). */
391
- const droppedIn = (drops, r) => drops.some((d) => d.of === r.at && sameRequest(d, r));
391
+ // A drop written before drops carried the request's session (code-kit issue #78) matches it whatever its session.
392
+ const droppedIn = (drops, r) =>
393
+ drops.some(
394
+ (d) => d.of === r.at && sameRequest('session' in d ? d : { ...d, session: r.session }, r),
395
+ );
392
396
 
393
397
  /**
394
398
  * CARD-7: drops open requests: `which` is a request's number in `openRequests`' order (1 is the
@@ -409,7 +413,7 @@ export function dropRequests(root, which, { by, reason = null }, now = Date.now(
409
413
  for (const r of picked)
410
414
  appendFileSync(
411
415
  file,
412
- `${JSON.stringify({ drop: true, of: r.at, actor: r.actor, names: r.names, what: r.what, by, reason, at: new Date(now).toISOString() })}\n`,
416
+ `${JSON.stringify({ drop: true, of: r.at, actor: r.actor, session: r.session ?? null, names: r.names, what: r.what, by, reason, at: new Date(now).toISOString() })}\n`,
413
417
  );
414
418
  return { ok: true, dropped: picked };
415
419
  }
@@ -849,8 +853,12 @@ function specCheckProblem(rel, root) {
849
853
  return null; // not a git worktree: nothing to key the report on
850
854
  }
851
855
  if (rel === report) return null;
852
- const file = join(root, report);
853
- if (existsSync(file) && /\|\s*Requirement\s*\|/i.test(readFileSync(file, 'utf8'))) return null;
856
+ // In the worktree, or in the main checkout, where it's kept when a worktree goes (#55).
857
+ const read = (dir) => {
858
+ const file = join(dir, report);
859
+ return existsSync(file) && /\|\s*Requirement\s*\|/i.test(readFileSync(file, 'utf8'));
860
+ };
861
+ if (read(root) || read(projectWorktrees(root)[0] ?? root)) return null;
854
862
  return `Run the spec-check skill before writing code on this branch. Save its report (the requirement table, questions and recommendation) to ${report}, then continue.`;
855
863
  }
856
864
 
@@ -164,6 +164,27 @@ function currentBranchOf(root) {
164
164
  }
165
165
  }
166
166
 
167
+ // The runtime's own noise, which says nothing about whether the check passed (#57).
168
+ const NOISE = [
169
+ /^\(node:\d+\) \[?\w*\]? ?(DeprecationWarning|ExperimentalWarning|Warning)\b/,
170
+ /^\(Use `node --trace-(deprecation|warnings) /,
171
+ /^\s*$/,
172
+ ];
173
+ const FAILING = /\b(fail(ed|ing|s)?|error|✗|✘|×|expected|received|assert|panic|traceback)\b/i;
174
+
175
+ /**
176
+ * What a failed check printed, as the lead needs it (#57): the runtime's warnings left out, the lines
177
+ * that name a failure first (up to 20), then the last 20 lines.
178
+ */
179
+ export function failureOutput(output) {
180
+ const lines = String(output ?? '')
181
+ .split('\n')
182
+ .filter((l) => !NOISE.some((re) => re.test(l)));
183
+ const tail = lines.slice(-20);
184
+ const named = lines.filter((l) => FAILING.test(l) && !tail.includes(l)).slice(0, 20);
185
+ return [...named, ...(named.length ? ['…'] : []), ...tail].join('\n');
186
+ }
187
+
167
188
  /**
168
189
  * The files changed, every problem with the branch, grouped as { ownership, protected, layers,
169
190
  * baseline, design, tests, regression, standards, checks }, and the checks `skipped` because a tool isn't
@@ -301,6 +322,7 @@ export function verifyBranch({
301
322
  if (fix) found.regression.push(...proveFix({ root, from, base, changed, config, fix }));
302
323
 
303
324
  let skipped = [];
325
+ let unfinished = false;
304
326
  if (checks) {
305
327
  const actor = lane
306
328
  ? { kind: 'lane', lane, label: `${lane} lane branch` }
@@ -308,13 +330,10 @@ export function verifyBranch({
308
330
  const ran = runChecks(config, changed, root, actor);
309
331
  skipped = ran.skipped;
310
332
  const { failure } = ran;
311
- if (failure)
312
- found.checks.push(
313
- `${failure.title}\n${String(failure.output ?? '')
314
- .split('\n')
315
- .slice(-40)
316
- .join('\n')}`.trim(),
317
- );
333
+ if (failure) {
334
+ found.checks.push(`${failure.title}\n${failureOutput(failure.output)}`.trim());
335
+ unfinished = Boolean(failure.timedOut);
336
+ }
318
337
  }
319
- return { changed, found, skipped };
338
+ return { changed, found, skipped, unfinished };
320
339
  }