ronce-racine 0.5.2 → 0.7.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.
- package/AGENTS.md +7 -2
- package/README.md +213 -207
- package/agents/code-reviewer.md +1 -1
- package/dist/hooks/README.md +62 -0
- package/dist/hooks/readme-freshness.mjs +159 -0
- package/dist/hooks/truncate-output.mjs +13 -5
- package/dist/install.js +114 -711
- package/dist/src/catalog.js +80 -0
- package/dist/src/detect.js +140 -0
- package/dist/src/lock.js +200 -0
- package/dist/src/paths.js +25 -0
- package/dist/src/selector.js +324 -0
- package/dist/src/settings.js +55 -0
- package/dist/src/uninstall.js +170 -0
- package/docs/adopting-a-repo.md +29 -22
- package/docs/architecture.md +9 -10
- package/docs/catalog.md +86 -0
- package/docs/decisions.md +31 -13
- package/docs/developing.md +69 -29
- package/docs/distribution-model.md +130 -0
- package/docs/evaluating-skills.md +42 -2
- package/docs/git-worktrees.md +2 -2
- package/docs/quality-bar.md +55 -0
- package/docs/templates/rule.template.md +2 -1
- package/docs/writing-a-rule.md +13 -3
- package/docs/writing-a-skill.md +16 -7
- package/package.json +17 -4
- package/skills/adversarial-feature-challenge/SKILL.md +5 -3
- package/skills/api-contract-versioning/SKILL.md +6 -4
- package/skills/bug-ticket-root-cause/SKILL.md +5 -3
- package/skills/bug-triage-structured/SKILL.md +5 -3
- package/skills/ci-pipeline-orchestration/SKILL.md +5 -3
- package/skills/commit-readiness-review/SKILL.md +7 -3
- package/skills/commit-readiness-review/scripts/precommit-scan.ts +3 -3
- package/skills/comprehensive-test-strategy/SKILL.md +5 -3
- package/skills/daily-workflow-optimization/SKILL.md +6 -4
- package/skills/database-schema-evolution/SKILL.md +6 -4
- package/skills/ddd-backend-implementation/SKILL.md +5 -3
- package/skills/design-system-component-lifecycle/SKILL.md +6 -4
- package/skills/detection-sweep/SKILL.md +7 -3
- package/skills/detection-sweep/scripts/sweep.ts +3 -3
- package/skills/domain-glossary/README.md +44 -0
- package/skills/domain-glossary/SKILL.md +166 -0
- package/skills/frontend-fullstack-implementation/SKILL.md +6 -4
- package/skills/frontend-spec-call-site-audit/SKILL.md +7 -3
- package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +4 -1
- package/skills/merge-request-review/SKILL.md +5 -3
- package/skills/performance-profiling/README.md +69 -0
- package/skills/performance-profiling/SKILL.md +223 -0
- package/skills/performance-profiling/reference/go.md +235 -0
- package/skills/performance-profiling/reference/native.md +148 -0
- package/skills/performance-profiling/reference/node-web.md +157 -0
- package/skills/performance-profiling/reference/statistics.md +181 -0
- package/skills/performance-profiling/reference/tracy.md +137 -0
- package/skills/production-incident-diagnostic/SKILL.md +5 -3
- package/skills/qa-session-intake/SKILL.md +5 -3
- package/skills/recording-decisions/SKILL.md +5 -3
- package/skills/recurring-bug-root-cause/SKILL.md +5 -3
- package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +1 -1
- package/skills/refactoring-shared-component-api/SKILL.md +7 -3
- package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +10 -3
- package/skills/validating-features-end-to-end/SKILL.md +5 -3
- package/skills/visual-regression-check/SKILL.md +6 -4
- package/skills/writing-robust-tests/SKILL.md +8 -4
|
@@ -0,0 +1,324 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The interactive TTY selector: layout, rendering and keyboard logic.
|
|
3
|
+
*/
|
|
4
|
+
import { readFileSync, existsSync } from "node:fs";
|
|
5
|
+
import { join } from "node:path";
|
|
6
|
+
import { emitKeypressEvents } from "node:readline";
|
|
7
|
+
import { SELF } from "./paths.js";
|
|
8
|
+
import { KIND_LABEL } from "./detect.js";
|
|
9
|
+
const KIND_ORDER = ["rule", "skill", "script", "hook", "agent"];
|
|
10
|
+
// ─── Layout constants ─────────────────────────────────────────────────────────
|
|
11
|
+
const HEADER_LINES = 2;
|
|
12
|
+
const LEGEND_LINES = 2;
|
|
13
|
+
const DETAIL_LINES = 4;
|
|
14
|
+
const MIN_VIEWPORT_ROWS = 5;
|
|
15
|
+
const ITEM_LINE_WIDTH = 50;
|
|
16
|
+
// ─── ANSI helpers ─────────────────────────────────────────────────────────────
|
|
17
|
+
const DIM = (s) => `\x1b[2m${s}\x1b[0m`;
|
|
18
|
+
const INVERSE = (s) => `\x1b[7m${s}\x1b[0m`;
|
|
19
|
+
const BOLD = (s) => `\x1b[1m${s}\x1b[0m`;
|
|
20
|
+
// ─── Description precomputation ───────────────────────────────────────────────
|
|
21
|
+
/**
|
|
22
|
+
* Reads the real description of each item from its source file.
|
|
23
|
+
* Called once before the selector loop.
|
|
24
|
+
*/
|
|
25
|
+
function buildDetailMap(items) {
|
|
26
|
+
const map = new Map();
|
|
27
|
+
for (const item of items) {
|
|
28
|
+
map.set(item, readItemDescription(item));
|
|
29
|
+
}
|
|
30
|
+
return map;
|
|
31
|
+
}
|
|
32
|
+
function readItemDescription(item) {
|
|
33
|
+
try {
|
|
34
|
+
if (item.kind === "skill") {
|
|
35
|
+
const skillFile = join(SELF, "skills", item.name, "SKILL.md");
|
|
36
|
+
if (existsSync(skillFile)) {
|
|
37
|
+
const content = readFileSync(skillFile, "utf8");
|
|
38
|
+
const desc = extractFrontmatterField(content, "description");
|
|
39
|
+
if (desc)
|
|
40
|
+
return desc;
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
else if (item.kind === "rule") {
|
|
44
|
+
const ruleFile = join(SELF, "rules", item.name);
|
|
45
|
+
if (existsSync(ruleFile)) {
|
|
46
|
+
const content = readFileSync(ruleFile, "utf8");
|
|
47
|
+
// Look for the first # line after the frontmatter (or at the start of the file)
|
|
48
|
+
const afterFront = skipFrontmatter(content);
|
|
49
|
+
const m = /^#\s+(.+)/m.exec(afterFront);
|
|
50
|
+
if (m)
|
|
51
|
+
return m[1].trim();
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
else if (item.kind === "script") {
|
|
55
|
+
const scriptFile = join(SELF, "scripts", item.name);
|
|
56
|
+
if (existsSync(scriptFile)) {
|
|
57
|
+
const content = readFileSync(scriptFile, "utf8");
|
|
58
|
+
const desc = extractJsDocFirstSentence(content);
|
|
59
|
+
if (desc)
|
|
60
|
+
return desc;
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
else if (item.kind === "hook") {
|
|
64
|
+
const hookFile = join(SELF, "hooks", item.name);
|
|
65
|
+
if (existsSync(hookFile)) {
|
|
66
|
+
const content = readFileSync(hookFile, "utf8");
|
|
67
|
+
const desc = extractJsDocFirstSentence(content);
|
|
68
|
+
if (desc)
|
|
69
|
+
return desc;
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
else if (item.kind === "agent") {
|
|
73
|
+
const agentFile = join(SELF, "agents", item.name);
|
|
74
|
+
if (existsSync(agentFile)) {
|
|
75
|
+
const content = readFileSync(agentFile, "utf8");
|
|
76
|
+
const desc = extractFrontmatterField(content, "description");
|
|
77
|
+
if (desc)
|
|
78
|
+
return desc;
|
|
79
|
+
// Fallback: first line of the file
|
|
80
|
+
const firstLine = content.split("\n").find((l) => l.trim().length > 0);
|
|
81
|
+
if (firstLine)
|
|
82
|
+
return firstLine.replace(/^#\s*/, "").trim();
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
catch {
|
|
87
|
+
// Cannot read - fall back to the default
|
|
88
|
+
}
|
|
89
|
+
return item.reason;
|
|
90
|
+
}
|
|
91
|
+
function skipFrontmatter(content) {
|
|
92
|
+
if (!content.startsWith("---"))
|
|
93
|
+
return content;
|
|
94
|
+
const end = content.indexOf("\n---", 3);
|
|
95
|
+
if (end === -1)
|
|
96
|
+
return content;
|
|
97
|
+
return content.slice(end + 4);
|
|
98
|
+
}
|
|
99
|
+
function extractFrontmatterField(content, field) {
|
|
100
|
+
if (!content.startsWith("---"))
|
|
101
|
+
return null;
|
|
102
|
+
const end = content.indexOf("\n---", 3);
|
|
103
|
+
if (end === -1)
|
|
104
|
+
return null;
|
|
105
|
+
const front = content.slice(0, end);
|
|
106
|
+
const re = new RegExp(`^${field}:\\s*(.+)`, "m");
|
|
107
|
+
const m = re.exec(front);
|
|
108
|
+
if (!m)
|
|
109
|
+
return null;
|
|
110
|
+
// Strip any surrounding quotes
|
|
111
|
+
return m[1].trim().replace(/^["']|["']$/g, "");
|
|
112
|
+
}
|
|
113
|
+
function extractJsDocFirstSentence(content) {
|
|
114
|
+
const start = content.indexOf("/**");
|
|
115
|
+
if (start === -1)
|
|
116
|
+
return null;
|
|
117
|
+
const end = content.indexOf("*/", start);
|
|
118
|
+
const block = end === -1 ? content.slice(start) : content.slice(start, end);
|
|
119
|
+
// Remove /** and the leading * on each line
|
|
120
|
+
const text = block
|
|
121
|
+
.replace(/\/\*\*/, "")
|
|
122
|
+
.replace(/\*\/$/, "")
|
|
123
|
+
.split("\n")
|
|
124
|
+
.map((l) => l.replace(/^\s*\*\s?/, "").trim())
|
|
125
|
+
.filter(Boolean)
|
|
126
|
+
.join(" ");
|
|
127
|
+
// Take up to the first period or the end of the first "sentence"
|
|
128
|
+
const m = /^([^.\n]+\.?)/.exec(text);
|
|
129
|
+
return m ? m[1].trim() : text.slice(0, 120) || null;
|
|
130
|
+
}
|
|
131
|
+
// ─── Rendering sub-functions (pure) ───────────────────────────────────────────
|
|
132
|
+
function buildHeader(checkedCount, total) {
|
|
133
|
+
const title = BOLD("⚙ Installing ronce-racine");
|
|
134
|
+
const counter = `${checkedCount}/${total} selected`;
|
|
135
|
+
return ` ${title} ${counter}\n`;
|
|
136
|
+
}
|
|
137
|
+
function buildGroupHeader(kind, checkedInGroup, totalInGroup) {
|
|
138
|
+
const label = `${KIND_LABEL[kind]} (${checkedInGroup}/${totalInGroup})`;
|
|
139
|
+
const dashes = "─".repeat(Math.max(0, ITEM_LINE_WIDTH - label.length - 4));
|
|
140
|
+
return ` ─── ${label} ${dashes}`;
|
|
141
|
+
}
|
|
142
|
+
function buildItemLine(item, isChecked, isCursor) {
|
|
143
|
+
const box = isChecked ? "[x]" : "[ ]";
|
|
144
|
+
const baseName = item.name.replace(/\.md$/, "");
|
|
145
|
+
const optTag = item.optional ? " · opt" : "";
|
|
146
|
+
const nameField = (baseName + optTag).padEnd(28);
|
|
147
|
+
const line = ` ${isCursor ? "›" : " "} ${box} ${nameField} - ${item.reason}`;
|
|
148
|
+
if (isCursor)
|
|
149
|
+
return INVERSE(line);
|
|
150
|
+
if (item.optional)
|
|
151
|
+
return DIM(line);
|
|
152
|
+
return line;
|
|
153
|
+
}
|
|
154
|
+
function buildDetailPanel(item, detail) {
|
|
155
|
+
const kindLabel = KIND_LABEL[item.kind];
|
|
156
|
+
const baseName = item.name.replace(/\.md$/, "");
|
|
157
|
+
const token = `${item.kind}:${baseName}`;
|
|
158
|
+
const badge = item.optional ? " · optional" : " · recommended";
|
|
159
|
+
const desc = detail.get(item) ?? item.reason;
|
|
160
|
+
const header = ` Detail: ${kindLabel} › ${baseName} [token: ${token}]${badge}`;
|
|
161
|
+
const body = ` ${desc.slice(0, 120)}${desc.length > 120 ? "…" : ""}`;
|
|
162
|
+
return `\n${header}\n${body}\n`;
|
|
163
|
+
}
|
|
164
|
+
function buildLegend() {
|
|
165
|
+
return `\n ${DIM("↑↓ move · space toggle · a (un)check the group · enter confirm · q cancel")}`;
|
|
166
|
+
}
|
|
167
|
+
// ─── Main frame ────────────────────────────────────────────────────────────────
|
|
168
|
+
/**
|
|
169
|
+
* Builds the complete selector frame (pure function, no I/O).
|
|
170
|
+
* Returns the string to write after \x1b[2J\x1b[H.
|
|
171
|
+
*/
|
|
172
|
+
function buildSelectorFrame(opts) {
|
|
173
|
+
const { flat, checked, cursor, detail, rows } = opts;
|
|
174
|
+
// Viewport computation
|
|
175
|
+
const viewportRows = Math.max(MIN_VIEWPORT_ROWS, rows - HEADER_LINES - LEGEND_LINES - DETAIL_LINES);
|
|
176
|
+
// Header
|
|
177
|
+
const header = buildHeader(checked.size, flat.length);
|
|
178
|
+
// Build the list lines (with group headers)
|
|
179
|
+
const listLines = [];
|
|
180
|
+
let lastKind = null;
|
|
181
|
+
for (let i = 0; i < flat.length; i++) {
|
|
182
|
+
const item = flat[i];
|
|
183
|
+
if (item.kind !== lastKind) {
|
|
184
|
+
// Group header
|
|
185
|
+
const groupItems = flat.filter((x) => x.kind === item.kind);
|
|
186
|
+
const checkedInGroup = groupItems.filter((x) => checked.has(x)).length;
|
|
187
|
+
listLines.push(buildGroupHeader(item.kind, checkedInGroup, groupItems.length));
|
|
188
|
+
lastKind = item.kind;
|
|
189
|
+
}
|
|
190
|
+
listLines.push(buildItemLine(item, checked.has(item), i === cursor));
|
|
191
|
+
}
|
|
192
|
+
// Viewport: find the index in listLines corresponding to the cursor item
|
|
193
|
+
// We rebuild an item-index → line-index mapping
|
|
194
|
+
const itemLineIndices = [];
|
|
195
|
+
let lineIdx = 0;
|
|
196
|
+
let prevKind = null;
|
|
197
|
+
for (const item of flat) {
|
|
198
|
+
if (item.kind !== prevKind) {
|
|
199
|
+
lineIdx++; // group line
|
|
200
|
+
prevKind = item.kind;
|
|
201
|
+
}
|
|
202
|
+
itemLineIndices.push(lineIdx);
|
|
203
|
+
lineIdx++;
|
|
204
|
+
}
|
|
205
|
+
const cursorLineIdx = itemLineIndices[cursor] ?? 0;
|
|
206
|
+
// Compute the viewport start: keeps the cursor visible with a margin on both sides
|
|
207
|
+
const MARGIN = 2; // context lines kept around the cursor
|
|
208
|
+
const lineViewportStart = Math.max(0, Math.min(cursorLineIdx - MARGIN, listLines.length - viewportRows));
|
|
209
|
+
const visibleLines = listLines.slice(lineViewportStart, lineViewportStart + viewportRows);
|
|
210
|
+
// Overflow indicators
|
|
211
|
+
const overflowTop = lineViewportStart > 0 ? lineViewportStart : 0;
|
|
212
|
+
const overflowBottom = Math.max(0, listLines.length - (lineViewportStart + viewportRows));
|
|
213
|
+
const topIndicator = overflowTop > 0 ? ` ▲ ${overflowTop} more\n` : "";
|
|
214
|
+
const bottomIndicator = overflowBottom > 0 ? ` ▼ ${overflowBottom} more\n` : "";
|
|
215
|
+
// Detail panel
|
|
216
|
+
const currentItem = flat[cursor];
|
|
217
|
+
const detailPanel = currentItem ? buildDetailPanel(currentItem, detail) : "\n\n\n\n";
|
|
218
|
+
// Legend
|
|
219
|
+
const legend = buildLegend();
|
|
220
|
+
return (header +
|
|
221
|
+
"\n" +
|
|
222
|
+
topIndicator +
|
|
223
|
+
visibleLines.join("\n") +
|
|
224
|
+
"\n" +
|
|
225
|
+
bottomIndicator +
|
|
226
|
+
detailPanel +
|
|
227
|
+
legend +
|
|
228
|
+
"\n");
|
|
229
|
+
}
|
|
230
|
+
/**
|
|
231
|
+
* Applies one keypress to the selector state (mutated in place).
|
|
232
|
+
* Returns "continue", "confirm" (enter) or "cancel" (q / ctrl-c).
|
|
233
|
+
*/
|
|
234
|
+
export function applySelectorKey(state, key) {
|
|
235
|
+
const k = key?.name;
|
|
236
|
+
if ((key?.ctrl && k === "c") || k === "q")
|
|
237
|
+
return "cancel";
|
|
238
|
+
if (k === "up" || k === "k")
|
|
239
|
+
state.cursor = (state.cursor - 1 + state.flat.length) % state.flat.length;
|
|
240
|
+
else if (k === "down" || k === "j")
|
|
241
|
+
state.cursor = (state.cursor + 1) % state.flat.length;
|
|
242
|
+
else if (k === "space") {
|
|
243
|
+
const it = state.flat[state.cursor];
|
|
244
|
+
state.checked.has(it) ? state.checked.delete(it) : state.checked.add(it);
|
|
245
|
+
}
|
|
246
|
+
else if (k === "a") {
|
|
247
|
+
const kind = state.flat[state.cursor].kind;
|
|
248
|
+
const group = state.flat.filter((i) => i.kind === kind);
|
|
249
|
+
const allOn = group.every((i) => state.checked.has(i));
|
|
250
|
+
for (const i of group) {
|
|
251
|
+
if (allOn)
|
|
252
|
+
state.checked.delete(i);
|
|
253
|
+
else
|
|
254
|
+
state.checked.add(i);
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
else if (k === "return")
|
|
258
|
+
return "confirm";
|
|
259
|
+
return "continue";
|
|
260
|
+
}
|
|
261
|
+
export function interactiveSelect(items, preChecked) {
|
|
262
|
+
const flat = KIND_ORDER.flatMap((k) => items.filter((i) => i.kind === k));
|
|
263
|
+
const checked = new Set(preChecked);
|
|
264
|
+
let cursor = 0;
|
|
265
|
+
// Precompute the descriptions (once)
|
|
266
|
+
const detail = buildDetailMap(items);
|
|
267
|
+
const render = () => {
|
|
268
|
+
const frame = buildSelectorFrame({
|
|
269
|
+
flat,
|
|
270
|
+
checked,
|
|
271
|
+
cursor,
|
|
272
|
+
detail,
|
|
273
|
+
rows: process.stdout.rows ?? 24,
|
|
274
|
+
});
|
|
275
|
+
process.stdout.write(`\x1b[2J\x1b[H${frame}`);
|
|
276
|
+
};
|
|
277
|
+
return new Promise((resolve) => {
|
|
278
|
+
const stdin = process.stdin;
|
|
279
|
+
emitKeypressEvents(stdin);
|
|
280
|
+
let cleaned = false;
|
|
281
|
+
const cleanup = () => {
|
|
282
|
+
if (cleaned)
|
|
283
|
+
return;
|
|
284
|
+
cleaned = true;
|
|
285
|
+
process.stdout.write("\x1b[?25h\n");
|
|
286
|
+
stdin.setRawMode(false);
|
|
287
|
+
stdin.pause();
|
|
288
|
+
stdin.removeListener("keypress", onKey);
|
|
289
|
+
};
|
|
290
|
+
const state = { flat, checked, cursor };
|
|
291
|
+
const onKey = (_s, key) => {
|
|
292
|
+
try {
|
|
293
|
+
const outcome = applySelectorKey(state, key);
|
|
294
|
+
cursor = state.cursor; // render() reads the outer binding
|
|
295
|
+
if (outcome === "cancel") {
|
|
296
|
+
cleanup();
|
|
297
|
+
resolve(null);
|
|
298
|
+
return;
|
|
299
|
+
}
|
|
300
|
+
if (outcome === "confirm") {
|
|
301
|
+
cleanup();
|
|
302
|
+
resolve(flat.filter((i) => checked.has(i)));
|
|
303
|
+
return;
|
|
304
|
+
}
|
|
305
|
+
render();
|
|
306
|
+
}
|
|
307
|
+
catch {
|
|
308
|
+
cleanup();
|
|
309
|
+
resolve(null);
|
|
310
|
+
}
|
|
311
|
+
};
|
|
312
|
+
try {
|
|
313
|
+
stdin.setRawMode(true);
|
|
314
|
+
stdin.resume();
|
|
315
|
+
process.stdout.write("\x1b[?25l"); // hide the cursor
|
|
316
|
+
render();
|
|
317
|
+
stdin.on("keypress", onKey);
|
|
318
|
+
}
|
|
319
|
+
catch {
|
|
320
|
+
cleanup();
|
|
321
|
+
resolve(null);
|
|
322
|
+
}
|
|
323
|
+
});
|
|
324
|
+
}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* settings.json hook wiring.
|
|
3
|
+
*/
|
|
4
|
+
import { readFileSync, existsSync, writeFileSync } from "node:fs";
|
|
5
|
+
import { join } from "node:path";
|
|
6
|
+
import { shippedHookName } from "./paths.js";
|
|
7
|
+
import { copyPath } from "./lock.js";
|
|
8
|
+
export function mergeHookSettings(dotclaude, wirings) {
|
|
9
|
+
const settingsPath = join(dotclaude, "settings.json");
|
|
10
|
+
const existed = existsSync(settingsPath);
|
|
11
|
+
let settings = {};
|
|
12
|
+
let malformed = false;
|
|
13
|
+
if (existed) {
|
|
14
|
+
try {
|
|
15
|
+
settings = JSON.parse(readFileSync(settingsPath, "utf8"));
|
|
16
|
+
}
|
|
17
|
+
catch {
|
|
18
|
+
malformed = true; // keep {} but back up the original before overwriting
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
// A hooks section with an unexpected shape (array, string…) cannot be merged
|
|
22
|
+
// into: treat it like malformed JSON - back up the file and rebuild the section.
|
|
23
|
+
if (settings.hooks !== undefined && (typeof settings.hooks !== "object" || settings.hooks === null || Array.isArray(settings.hooks))) {
|
|
24
|
+
malformed = true;
|
|
25
|
+
delete settings.hooks;
|
|
26
|
+
}
|
|
27
|
+
settings.hooks ??= {};
|
|
28
|
+
const hooks = settings.hooks;
|
|
29
|
+
let added = 0;
|
|
30
|
+
for (const w of wirings) {
|
|
31
|
+
const command = `node $CLAUDE_PROJECT_DIR/.claude/hooks/${shippedHookName(w.commandFile)}`;
|
|
32
|
+
if (!Array.isArray(hooks[w.event])) {
|
|
33
|
+
if (hooks[w.event] !== undefined)
|
|
34
|
+
malformed = true;
|
|
35
|
+
hooks[w.event] = [];
|
|
36
|
+
}
|
|
37
|
+
const entries = hooks[w.event];
|
|
38
|
+
let entry = entries.find((e) => e && typeof e === "object" && Array.isArray(e.hooks) && (e.matcher ?? "") === (w.matcher ?? ""));
|
|
39
|
+
if (!entry) {
|
|
40
|
+
entry = { ...(w.matcher ? { matcher: w.matcher } : {}), hooks: [] };
|
|
41
|
+
entries.push(entry);
|
|
42
|
+
}
|
|
43
|
+
if (!entry.hooks.some((h) => h.command === command)) {
|
|
44
|
+
entry.hooks.push({ type: "command", command });
|
|
45
|
+
added++;
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
const backedUp = existed && (added > 0 || malformed);
|
|
49
|
+
if (added > 0 || malformed) {
|
|
50
|
+
if (backedUp)
|
|
51
|
+
copyPath(settingsPath, `${settingsPath}.bak`);
|
|
52
|
+
writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
|
|
53
|
+
}
|
|
54
|
+
return { added, backedUp, malformed };
|
|
55
|
+
}
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Removing an installation: the inverse of doInstall.
|
|
3
|
+
*
|
|
4
|
+
* Two properties matter more than completeness here. Nothing the installer did
|
|
5
|
+
* not write is ever deleted: removal is driven by the lockfile, tokens are
|
|
6
|
+
* validated before they become paths, every target is checked to sit inside
|
|
7
|
+
* the repository's own `.claude/`, and the hook unwiring only touches the exact
|
|
8
|
+
* commands the installer added. And nothing of the user's is lost: a detached
|
|
9
|
+
* token is left alone, a `.pre-install.bak` is restored over the file the
|
|
10
|
+
* install overwrote, and an artifact carrying local edits is backed up rather
|
|
11
|
+
* than dropped.
|
|
12
|
+
*/
|
|
13
|
+
import { existsSync, readFileSync, writeFileSync, rmSync, rmdirSync, readdirSync, renameSync } from "node:fs";
|
|
14
|
+
import { join, resolve, sep } from "node:path";
|
|
15
|
+
import { tokenPaths, compareToken } from "./lock.js";
|
|
16
|
+
import { shippedHookName, ADOPTED_HEADER } from "./paths.js";
|
|
17
|
+
/** Directories the installer creates, deepest first so a parent empties before it is tested. */
|
|
18
|
+
const OWNED_DIRS = ["rules/shared", "rules", "skills", "hooks", "agents", "scripts"];
|
|
19
|
+
/** Errors that mean "this directory is simply not removable", as opposed to a bug. */
|
|
20
|
+
const TOLERATED_RMDIR = new Set(["ENOTEMPTY", "EACCES", "EPERM", "EBUSY", "ENOENT", "ENOTDIR"]);
|
|
21
|
+
/**
|
|
22
|
+
* Drops the wirings the installer added from settings.json, and nothing else.
|
|
23
|
+
* Matching is by the hook file names recorded in the lockfile, not by "anything
|
|
24
|
+
* under .claude/hooks", so a hook the user wrote and wired themselves survives.
|
|
25
|
+
*/
|
|
26
|
+
export function unwireHookSettings(dotclaude, hookFiles) {
|
|
27
|
+
const settingsPath = join(dotclaude, "settings.json");
|
|
28
|
+
if (!existsSync(settingsPath))
|
|
29
|
+
return { removed: 0, unreadable: false };
|
|
30
|
+
let settings;
|
|
31
|
+
try {
|
|
32
|
+
settings = JSON.parse(readFileSync(settingsPath, "utf8"));
|
|
33
|
+
}
|
|
34
|
+
catch {
|
|
35
|
+
// Hand-edited into invalid JSON since the install: rewriting it would
|
|
36
|
+
// destroy whatever the user was in the middle of. Say so instead, because
|
|
37
|
+
// the hook files are about to go and the commands launching them would
|
|
38
|
+
// stay, failing on every event with nothing explaining why.
|
|
39
|
+
return { removed: 0, unreadable: true };
|
|
40
|
+
}
|
|
41
|
+
const hooks = settings.hooks;
|
|
42
|
+
if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
|
|
43
|
+
return { removed: 0, unreadable: false };
|
|
44
|
+
const ours = new Set(hookFiles.map((f) => shippedHookName(f)));
|
|
45
|
+
const isOurs = (command) => {
|
|
46
|
+
const file = command.split(/[/\\]/).pop() ?? "";
|
|
47
|
+
return command.includes(".claude") && ours.has(file);
|
|
48
|
+
};
|
|
49
|
+
let removed = 0;
|
|
50
|
+
for (const event of Object.keys(hooks)) {
|
|
51
|
+
const entries = hooks[event];
|
|
52
|
+
if (!Array.isArray(entries))
|
|
53
|
+
continue;
|
|
54
|
+
for (const entry of entries) {
|
|
55
|
+
if (!entry || !Array.isArray(entry.hooks))
|
|
56
|
+
continue;
|
|
57
|
+
const before = entry.hooks.length;
|
|
58
|
+
entry.hooks = entry.hooks.filter((h) => !(h && typeof h.command === "string" && isOurs(h.command)));
|
|
59
|
+
removed += before - entry.hooks.length;
|
|
60
|
+
}
|
|
61
|
+
// An entry we emptied was ours; one that was already empty is not our business.
|
|
62
|
+
hooks[event] = entries.filter((e) => !e || !Array.isArray(e.hooks) || e.hooks.length > 0);
|
|
63
|
+
if (hooks[event].length === 0)
|
|
64
|
+
delete hooks[event];
|
|
65
|
+
}
|
|
66
|
+
if (Object.keys(hooks).length === 0)
|
|
67
|
+
delete settings.hooks;
|
|
68
|
+
if (removed === 0)
|
|
69
|
+
return { removed, unreadable: false };
|
|
70
|
+
// A file reduced to {} only ever held our wiring, so it is ours to clean up -
|
|
71
|
+
// unless a .bak sits next to it, which means the user had one before us.
|
|
72
|
+
if (Object.keys(settings).length === 0 && !existsSync(`${settingsPath}.bak`))
|
|
73
|
+
rmSync(settingsPath, { force: true });
|
|
74
|
+
else
|
|
75
|
+
writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
|
|
76
|
+
return { removed, unreadable: false };
|
|
77
|
+
}
|
|
78
|
+
/** Removes a directory only once nothing is left in it. */
|
|
79
|
+
function removeIfEmpty(dir) {
|
|
80
|
+
if (!existsSync(dir) || readdirSync(dir).length > 0)
|
|
81
|
+
return;
|
|
82
|
+
try {
|
|
83
|
+
rmdirSync(dir);
|
|
84
|
+
}
|
|
85
|
+
catch (err) {
|
|
86
|
+
// A directory that will not go is a target-repo condition, not a reason to
|
|
87
|
+
// fail an uninstall that has already done its work. Anything else is a bug.
|
|
88
|
+
const code = err.code ?? "";
|
|
89
|
+
if (!TOLERATED_RMDIR.has(code))
|
|
90
|
+
throw err;
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
/** Guards against a lockfile token resolving anywhere but the repository's own .claude/. */
|
|
94
|
+
function insideDotClaude(repo, target) {
|
|
95
|
+
const root = resolve(join(repo, ".claude"));
|
|
96
|
+
const p = resolve(target);
|
|
97
|
+
return p === root || p.startsWith(root + sep);
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Deletes the artifacts recorded in `installed`, skipping `detached` ones.
|
|
101
|
+
* Returns what happened per token so the caller can report it.
|
|
102
|
+
*/
|
|
103
|
+
export function removeArtifacts(repo, installed, detached) {
|
|
104
|
+
const skip = new Set(detached);
|
|
105
|
+
const result = { removed: [], preserved: [], restored: [], backedUp: [] };
|
|
106
|
+
for (const token of installed) {
|
|
107
|
+
if (skip.has(token)) {
|
|
108
|
+
result.preserved.push(token);
|
|
109
|
+
continue;
|
|
110
|
+
}
|
|
111
|
+
const { inst } = tokenPaths(token, repo);
|
|
112
|
+
if (!insideDotClaude(repo, inst))
|
|
113
|
+
continue;
|
|
114
|
+
const backup = `${inst}.pre-install.bak`;
|
|
115
|
+
if (existsSync(inst)) {
|
|
116
|
+
// Local edits are exactly what `check` reports as drift. Uninstall is not
|
|
117
|
+
// the place to discover they are gone, so they leave a copy behind.
|
|
118
|
+
if (compareToken(token, repo) !== null) {
|
|
119
|
+
// An earlier uninstall may already have left one. It holds different
|
|
120
|
+
// user work, so it is numbered rather than overwritten.
|
|
121
|
+
let bak = `${inst}.pre-uninstall.bak`;
|
|
122
|
+
for (let n = 2; existsSync(bak); n++)
|
|
123
|
+
bak = `${inst}.pre-uninstall.${n}.bak`;
|
|
124
|
+
renameSync(inst, bak);
|
|
125
|
+
result.backedUp.push(token);
|
|
126
|
+
}
|
|
127
|
+
else {
|
|
128
|
+
rmSync(inst, { recursive: true, force: true });
|
|
129
|
+
}
|
|
130
|
+
result.removed.push(token);
|
|
131
|
+
}
|
|
132
|
+
// The backup holds what was there before the install overwrote it: giving
|
|
133
|
+
// it back is the whole point of having taken it.
|
|
134
|
+
if (existsSync(backup)) {
|
|
135
|
+
renameSync(backup, inst);
|
|
136
|
+
result.restored.push(token);
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
return result;
|
|
140
|
+
}
|
|
141
|
+
/**
|
|
142
|
+
* Rewrites the generated manifest to the rules that survived, removes the hooks
|
|
143
|
+
* README once no hook is left, and drops any directory now empty.
|
|
144
|
+
*
|
|
145
|
+
* Both generated files describe the artifacts around them, so they track what
|
|
146
|
+
* remains rather than being deleted outright: a detached rule still deserves
|
|
147
|
+
* its `.adopted` line, and a hook kept behind still deserves the README saying
|
|
148
|
+
* what it runs.
|
|
149
|
+
*/
|
|
150
|
+
export function cleanupLayout(repo, survivingRules) {
|
|
151
|
+
const dotclaude = join(repo, ".claude");
|
|
152
|
+
const manifest = join(dotclaude, "rules/shared/.adopted");
|
|
153
|
+
if (existsSync(manifest)) {
|
|
154
|
+
// From the tokens, never from readdir: the directory also holds the backups
|
|
155
|
+
// we just wrote and the user's own files we just handed back, and listing
|
|
156
|
+
// either as an adopted generic rule invites `install --rules-only` to
|
|
157
|
+
// overwrite them.
|
|
158
|
+
if (survivingRules.length === 0)
|
|
159
|
+
rmSync(manifest, { force: true });
|
|
160
|
+
else
|
|
161
|
+
writeFileSync(manifest, `${ADOPTED_HEADER}${[...survivingRules].sort().join("\n")}\n`);
|
|
162
|
+
}
|
|
163
|
+
const hooks = join(dotclaude, "hooks");
|
|
164
|
+
if (existsSync(hooks) && readdirSync(hooks).every((e) => e === "README.md")) {
|
|
165
|
+
rmSync(join(hooks, "README.md"), { force: true });
|
|
166
|
+
}
|
|
167
|
+
for (const dir of OWNED_DIRS)
|
|
168
|
+
removeIfEmpty(join(dotclaude, dir));
|
|
169
|
+
removeIfEmpty(dotclaude);
|
|
170
|
+
}
|
package/docs/adopting-a-repo.md
CHANGED
|
@@ -8,15 +8,24 @@
|
|
|
8
8
|
# 1. Proposal (read-only) - nothing is written
|
|
9
9
|
npx ronce-racine plan .
|
|
10
10
|
|
|
11
|
-
# 2. Install
|
|
12
|
-
npx ronce-racine install .
|
|
11
|
+
# 2. Install: an interactive selector opens, pre-checked with the recommendations
|
|
12
|
+
npx ronce-racine install .
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
+
`install` is interactive when it runs on a TTY: the selector lists the recommended artifacts (pre-checked) plus the optional ones (unchecked), and you confirm or amend the selection. Three flags skip or widen that step:
|
|
16
|
+
|
|
17
|
+
| Flag | Effect |
|
|
18
|
+
|---|---|
|
|
19
|
+
| `--yes` (`-y`) | no prompt: installs the pre-checked set (also the behavior when stdin is not a TTY, e.g. in CI) |
|
|
20
|
+
| `--all` | pre-checks the optional artifacts too (audits, etc.), still through the selector unless combined with `--yes` |
|
|
21
|
+
| `--pick <token...>` | installs exactly these `kind:name` tokens (`skill:detection-sweep`, `rule:commits.md`) and nothing else |
|
|
22
|
+
| `--rules-only` | restricts the whole run to rules |
|
|
23
|
+
|
|
15
24
|
The installer copies into `.claude/`:
|
|
16
|
-
- `rules/shared/` + the `.adopted` manifest
|
|
17
|
-
- `skills/<name>/` (relevant skills), `hooks/`, `agents/`
|
|
25
|
+
- `rules/shared/` + the generated `.adopted` manifest - drift is watchable via `ronce-racine check .`
|
|
26
|
+
- `skills/<name>/` (relevant skills), `scripts/`, `hooks/`, `agents/`
|
|
18
27
|
|
|
19
|
-
It merges the hook wirings into `.claude/settings.json` (
|
|
28
|
+
It merges the hook wirings into `.claude/settings.json` (deep-merges by event + matcher, idempotent, preserves unrelated settings, and backs an existing file up to `settings.json.bak` before rewriting it). A pre-existing artifact the installer has never managed is copied to `<file>.pre-install.bak` before being overwritten, so a hand-written skill or rule of yours is never lost silently. Check the diff (`git diff`, `git status`), then commit - `.claude/` travels via git → teammates + CI agents.
|
|
20
29
|
|
|
21
30
|
Update later: rerun `ronce-racine install .` (idempotent). For rules only, use `ronce-racine install . --rules-only` (same lockfile-based drift as everything else).
|
|
22
31
|
|
|
@@ -30,36 +39,33 @@ npx ronce-racine check . --strict # exit 1 on drift (blocking gate)
|
|
|
30
39
|
```
|
|
31
40
|
|
|
32
41
|
- **Drift**: a managed artifact was modified locally → reported (`~file`, `-missing`, `+added`).
|
|
33
|
-
- **Assumed customization**: `ronce-racine detach . skill:detection-sweep` takes the item out of control (it becomes "yours").
|
|
42
|
+
- **Assumed customization**: `ronce-racine detach . skill:detection-sweep` takes the item out of control (it becomes "yours"). The token is the one recorded in the lockfile, so rules carry their extension (`rule:commits.md`).
|
|
43
|
+
- **Backing out**: `ronce-racine uninstall .` removes what the lockfile records and unwires its own hooks, keeping detached items and restoring any `*.pre-install.bak`. Preview it with `--dry-run`. See [`distribution-model.md`](distribution-model.md#removing-an-installation).
|
|
34
44
|
- **Staleness**: the canonical version has moved on since install → "rerun install" warning.
|
|
35
45
|
|
|
36
46
|
CI gate: the [`templates/anti-drift.gitlab-ci.yml`](../templates/anti-drift.gitlab-ci.yml) snippet (soft via `allow_failure`, blocking by removing that line).
|
|
37
47
|
|
|
38
48
|
> The sections below describe the **rules-only approach** (rules and nothing else), still driven by `ronce-racine`.
|
|
39
49
|
|
|
40
|
-
## 1.
|
|
50
|
+
## 1. Choose the adopted rules
|
|
41
51
|
|
|
42
|
-
|
|
52
|
+
Selection happens at install time, not in a hand-written file:
|
|
43
53
|
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
minimal-code.md
|
|
47
|
-
commits.md
|
|
48
|
-
test-discipline.md
|
|
54
|
+
```bash
|
|
55
|
+
npx ronce-racine install . --rules-only # selector, pre-checked with the detected stack
|
|
56
|
+
npx ronce-racine install . --rules-only --pick rule:minimal-code.md rule:commits.md
|
|
49
57
|
```
|
|
50
58
|
|
|
51
|
-
|
|
59
|
+
`.claude/rules/shared/.adopted` is **written by the installer** as a record of what it adopted; editing it changes nothing, and the next install rewrites it. What is actually managed lives in the lockfile.
|
|
52
60
|
|
|
53
|
-
|
|
61
|
+
Only adopt the rules for which you want the **generic canonical** version. A rule you want to **enrich locally** (e.g. `secure-logging` with the project's identifiers and lint): leave it out of the selection, and keep your version in `.claude/rules/shared/` or `rules/<project>/`. A rule the installer never wrote is never touched by `install` or `check`; one you customized after adopting it is what `detach` is for.
|
|
54
62
|
|
|
55
|
-
|
|
56
|
-
npx ronce-racine install . --rules-only
|
|
57
|
-
```
|
|
63
|
+
## 2. Commit
|
|
58
64
|
|
|
59
|
-
The adopted files
|
|
65
|
+
The adopted files land in `.claude/rules/shared/` and are tracked in the lockfile (same drift mechanism as everything else). Check the diff (`git diff`), then commit:
|
|
60
66
|
|
|
61
67
|
```bash
|
|
62
|
-
git add .claude/rules/shared
|
|
68
|
+
git add .claude/rules/shared .claude/.ronce-racine.json
|
|
63
69
|
git commit -m "chore(rules): adopt the generic canonical rules (ronce-racine)"
|
|
64
70
|
```
|
|
65
71
|
|
|
@@ -75,6 +81,7 @@ When the canonical version evolves:
|
|
|
75
81
|
|
|
76
82
|
```bash
|
|
77
83
|
cd <repo>
|
|
78
|
-
npx ronce-racine install . --rules-only
|
|
79
|
-
git add .claude/rules/shared
|
|
84
|
+
npx ronce-racine install . --rules-only --yes
|
|
85
|
+
git add .claude/rules/shared .claude/.ronce-racine.json
|
|
86
|
+
git commit -m "chore(rules): resync canonical rules"
|
|
80
87
|
```
|