drawbore 0.0.0-stage → 0.1.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/CHANGELOG.md +21 -0
- package/LICENSE +21 -0
- package/README.md +76 -3
- package/bin/drawbore.js +267 -0
- package/lib/checker.js +399 -0
- package/lib/index.js +14 -0
- package/lib/installer.js +405 -0
- package/lib/prompts.js +374 -0
- package/package.json +42 -5
- package/skills/discover/SKILL.md +77 -0
- package/skills/frame/SKILL.md +85 -0
- package/skills/frame/references/change-brief.md +55 -0
- package/skills/init-project/SKILL.md +86 -0
- package/skills/recall/SKILL.md +62 -0
- package/skills/record/SKILL.md +99 -0
- package/skills/record/references/artifact-formats.md +131 -0
- package/skills/release/SKILL.md +108 -0
- package/skills/review/SKILL.md +117 -0
- package/templates/instruction.md +9 -0
- package/templates/manifest.json +12 -0
- package/templates/record/context.md +14 -0
- package/templates/record/decisions/.gitkeep +0 -0
- package/templates/record/glossary.md +7 -0
- package/templates/record/index.md +16 -0
- package/templates/record/principles.md +3 -0
- package/templates/record/stack.md +7 -0
- package/templates/record/system.md +3 -0
- package/templates/record/work/.gitkeep +0 -0
package/lib/installer.js
ADDED
|
@@ -0,0 +1,405 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { access, copyFile, cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
import { fileURLToPath } from "node:url";
|
|
5
|
+
|
|
6
|
+
const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
|
|
7
|
+
|
|
8
|
+
export const supportedLocations = Object.freeze({
|
|
9
|
+
".agents": "AGENTS.md",
|
|
10
|
+
".claude": "CLAUDE.md",
|
|
11
|
+
".codex": "AGENTS.md",
|
|
12
|
+
".cursor": "AGENTS.md",
|
|
13
|
+
".omp": "AGENTS.md",
|
|
14
|
+
".opencode": "AGENTS.md",
|
|
15
|
+
});
|
|
16
|
+
|
|
17
|
+
export const notebookDirectory = ".drawbore";
|
|
18
|
+
export const installMarkerFile = ".drawbore-install.json";
|
|
19
|
+
const skillMarkerFile = ".drawbore-skill.json";
|
|
20
|
+
|
|
21
|
+
const instructionMarkers = Object.freeze({
|
|
22
|
+
start: "<!-- drawbore:start -->",
|
|
23
|
+
end: "<!-- drawbore:end -->",
|
|
24
|
+
});
|
|
25
|
+
|
|
26
|
+
export class SkillConflictError extends Error {
|
|
27
|
+
constructor(conflicts) {
|
|
28
|
+
super(formatConflictMessage(conflicts));
|
|
29
|
+
this.name = "SkillConflictError";
|
|
30
|
+
this.conflicts = conflicts;
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
export async function loadPackageData() {
|
|
35
|
+
const [manifestText, versionText, instructionText] = await Promise.all([
|
|
36
|
+
readFile(path.join(packageRoot, "templates", "manifest.json"), "utf8"),
|
|
37
|
+
readFile(path.join(packageRoot, "package.json"), "utf8"),
|
|
38
|
+
readFile(path.join(packageRoot, "templates", "instruction.md"), "utf8"),
|
|
39
|
+
]);
|
|
40
|
+
|
|
41
|
+
return {
|
|
42
|
+
...JSON.parse(manifestText),
|
|
43
|
+
version: JSON.parse(versionText).version,
|
|
44
|
+
instructionTemplate: instructionText,
|
|
45
|
+
packageRoot,
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export async function findProjectRoot(cwd = process.cwd()) {
|
|
50
|
+
let current = path.resolve(cwd);
|
|
51
|
+
while (true) {
|
|
52
|
+
if (await exists(path.join(current, ".git"))) return current;
|
|
53
|
+
const parent = path.dirname(current);
|
|
54
|
+
if (parent === current) return path.resolve(cwd);
|
|
55
|
+
current = parent;
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
export async function inspectProject(root) {
|
|
60
|
+
const locations = [];
|
|
61
|
+
for (const [locationPath, instructionName] of Object.entries(supportedLocations)) {
|
|
62
|
+
locations.push({
|
|
63
|
+
path: locationPath,
|
|
64
|
+
instructionName,
|
|
65
|
+
instructionExists: await exists(path.join(root, instructionName)),
|
|
66
|
+
skillsExist: await exists(path.join(root, locationPath, "skills")),
|
|
67
|
+
});
|
|
68
|
+
}
|
|
69
|
+
return { root, notebookExists: await exists(path.join(root, notebookDirectory)), locations };
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
export async function installSkills(root, location, packageData, options = {}) {
|
|
73
|
+
const locationDir = path.join(root, location);
|
|
74
|
+
await assertDirectoryTarget(locationDir, `${location} in ${root}`);
|
|
75
|
+
const destination = path.join(locationDir, "skills");
|
|
76
|
+
await assertDirectoryTarget(destination, `${location}/skills`);
|
|
77
|
+
await mkdir(destination, { recursive: true });
|
|
78
|
+
|
|
79
|
+
const { previousHashes, installNamespace } = await readInstallState(root, location);
|
|
80
|
+
const conflicts = await findConflicts(destination, location, packageData, previousHashes, installNamespace);
|
|
81
|
+
|
|
82
|
+
if (conflicts.length > 0 && options.force !== true) {
|
|
83
|
+
throw new SkillConflictError(conflicts);
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
const preserved = [];
|
|
87
|
+
const replaced = [];
|
|
88
|
+
const hashes = {};
|
|
89
|
+
|
|
90
|
+
for (const skill of packageData.skills) {
|
|
91
|
+
const source = path.join(packageRoot, "skills", skill);
|
|
92
|
+
const target = path.join(destination, skill);
|
|
93
|
+
await copySkillDirectory(source, target, `skills/${skill}`, `${location}/skills/${skill}`, {
|
|
94
|
+
preserved,
|
|
95
|
+
replaced,
|
|
96
|
+
hashes,
|
|
97
|
+
previousHashes,
|
|
98
|
+
replaceExisting: options.replaceExisting === true,
|
|
99
|
+
force: options.force === true,
|
|
100
|
+
});
|
|
101
|
+
await writeSkillMarker(target, packageData.namespace, skill);
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
return { preserved, replaced, hashes, conflicts };
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
async function findConflicts(destination, location, packageData, previousHashes, installNamespace) {
|
|
108
|
+
const conflicts = [];
|
|
109
|
+
for (const skill of packageData.skills) {
|
|
110
|
+
const target = path.join(destination, skill);
|
|
111
|
+
if (!(await isForeignSkill(target, skill, packageData, previousHashes, installNamespace))) continue;
|
|
112
|
+
conflicts.push({ location, skill, target, reason: "foreign-skill" });
|
|
113
|
+
}
|
|
114
|
+
return conflicts;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
async function readInstallState(root, location) {
|
|
118
|
+
return {
|
|
119
|
+
previousHashes: await readInstalledSkillHashes(root, location),
|
|
120
|
+
installNamespace: await readInstallNamespace(root),
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
// A skill is foreign when it exists and its content diverges from what this
|
|
125
|
+
// package ships, unless this installer or this namespace already owns it. A
|
|
126
|
+
// path whose type differs from the package's is a file/directory conflict the
|
|
127
|
+
// copy loop preserves, never foreign content to overwrite.
|
|
128
|
+
async function isForeignSkill(target, skill, packageData, previousHashes, installNamespace) {
|
|
129
|
+
if (!(await isDirectory(target))) return false;
|
|
130
|
+
if (await hasSkillMarker(target, packageData.namespace)) return false;
|
|
131
|
+
const marker = await readSkillMarker(target);
|
|
132
|
+
if (isRecord(marker) && typeof marker.namespace === "string") return true;
|
|
133
|
+
if (installNamespace === packageData.namespace && (await matchesRecordedHashes(target, skill, previousHashes))) {
|
|
134
|
+
return false;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
const source = path.join(packageRoot, "skills", skill);
|
|
138
|
+
const packageFiles = await listFiles(source);
|
|
139
|
+
const targetFiles = await listFiles(target);
|
|
140
|
+
const divergent = [];
|
|
141
|
+
|
|
142
|
+
for (const file of packageFiles) {
|
|
143
|
+
const targetPath = path.join(target, ...file.split("/"));
|
|
144
|
+
// A directory where the package has a file is the `SKILL.md` collision
|
|
145
|
+
// shape; it is preserved, not counted as foreign content.
|
|
146
|
+
if ((await pathType(targetPath)) !== "file") continue;
|
|
147
|
+
if (!(await readFile(targetPath)).equals(await readFile(path.join(source, ...file.split("/"))))) {
|
|
148
|
+
divergent.push(file);
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
for (const file of targetFiles) {
|
|
152
|
+
if (file !== skillMarkerFile && !packageFiles.includes(file)) divergent.push(file);
|
|
153
|
+
}
|
|
154
|
+
return divergent.length > 0;
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
// An installed skill whose marker was deleted still belongs to us while its
|
|
158
|
+
// files hash-match what the install marker recorded.
|
|
159
|
+
async function matchesRecordedHashes(target, skill, previousHashes) {
|
|
160
|
+
const prefix = `skills/${skill}/`;
|
|
161
|
+
const recorded = Object.keys(previousHashes).filter((key) => key.startsWith(prefix));
|
|
162
|
+
if (recorded.length === 0) return false;
|
|
163
|
+
const targetFiles = (await listFiles(target)).filter((file) => file !== skillMarkerFile);
|
|
164
|
+
if (targetFiles.length !== recorded.length) return false;
|
|
165
|
+
for (const key of recorded) {
|
|
166
|
+
const relative = key.slice(prefix.length);
|
|
167
|
+
if (!targetFiles.includes(relative)) return false;
|
|
168
|
+
const contents = await readFile(path.join(target, ...relative.split("/")));
|
|
169
|
+
if (hashContents(contents) !== previousHashes[key]) return false;
|
|
170
|
+
}
|
|
171
|
+
return true;
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
async function listFiles(root) {
|
|
175
|
+
const files = [];
|
|
176
|
+
async function walk(directory) {
|
|
177
|
+
for (const entry of await readdir(directory, { withFileTypes: true })) {
|
|
178
|
+
const absolute = path.join(directory, entry.name);
|
|
179
|
+
if (entry.isDirectory()) {
|
|
180
|
+
await walk(absolute);
|
|
181
|
+
} else {
|
|
182
|
+
files.push(path.relative(root, absolute).split(path.sep).join("/"));
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
await walk(root);
|
|
187
|
+
return files;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
async function readInstallNamespace(root) {
|
|
191
|
+
const marker = await readInstallMarker(root);
|
|
192
|
+
return typeof marker.namespace === "string" ? marker.namespace : null;
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
async function readSkillMarker(target) {
|
|
196
|
+
try {
|
|
197
|
+
return JSON.parse(await readFile(path.join(target, skillMarkerFile), "utf8"));
|
|
198
|
+
} catch {
|
|
199
|
+
return null;
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
async function hasSkillMarker(target, namespace) {
|
|
204
|
+
const marker = await readSkillMarker(target);
|
|
205
|
+
return isRecord(marker) && marker.namespace === namespace;
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
async function writeSkillMarker(target, namespace, skill) {
|
|
209
|
+
await writeFile(
|
|
210
|
+
path.join(target, skillMarkerFile),
|
|
211
|
+
`${JSON.stringify({ namespace, skill }, null, 2)}\n`,
|
|
212
|
+
"utf8",
|
|
213
|
+
);
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
async function copySkillDirectory(source, target, hashTarget, displayTarget, state) {
|
|
217
|
+
await mkdir(target, { recursive: true });
|
|
218
|
+
for (const entry of await readdir(source, { withFileTypes: true })) {
|
|
219
|
+
const sourcePath = path.join(source, entry.name);
|
|
220
|
+
const targetPath = path.join(target, entry.name);
|
|
221
|
+
const hashPath = `${hashTarget}/${entry.name}`;
|
|
222
|
+
const displayPath = `${displayTarget}/${entry.name}`;
|
|
223
|
+
|
|
224
|
+
if (entry.isDirectory()) {
|
|
225
|
+
const existing = await pathType(targetPath);
|
|
226
|
+
if (existing === "file" && !state.force) {
|
|
227
|
+
state.preserved.push(displayPath);
|
|
228
|
+
continue;
|
|
229
|
+
}
|
|
230
|
+
if (existing === "file" && state.force) {
|
|
231
|
+
await rm(targetPath, { recursive: true, force: true });
|
|
232
|
+
}
|
|
233
|
+
await mkdir(targetPath, { recursive: true });
|
|
234
|
+
await copySkillDirectory(sourcePath, targetPath, hashPath, displayPath, state);
|
|
235
|
+
continue;
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
const existing = await pathType(targetPath);
|
|
239
|
+
if (existing === "directory" && !state.force) {
|
|
240
|
+
state.preserved.push(displayPath);
|
|
241
|
+
continue;
|
|
242
|
+
}
|
|
243
|
+
if (existing === "directory" && state.force) {
|
|
244
|
+
await rm(targetPath, { recursive: true, force: true });
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
const sourceContents = await readFile(sourcePath);
|
|
248
|
+
const sourceHash = hashContents(sourceContents);
|
|
249
|
+
|
|
250
|
+
if (existing === "file") {
|
|
251
|
+
const targetContents = await readFile(targetPath);
|
|
252
|
+
if (sourceContents.equals(targetContents)) {
|
|
253
|
+
state.hashes[hashPath] = sourceHash;
|
|
254
|
+
continue;
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
const targetHash = hashContents(targetContents);
|
|
258
|
+
const previousHash = state.previousHashes[hashPath];
|
|
259
|
+
const isUnmodifiedPackageFile = previousHash !== undefined && targetHash === previousHash;
|
|
260
|
+
if (!state.replaceExisting && !state.force && !isUnmodifiedPackageFile) {
|
|
261
|
+
state.preserved.push(displayPath);
|
|
262
|
+
if (previousHash !== undefined) state.hashes[hashPath] = previousHash;
|
|
263
|
+
continue;
|
|
264
|
+
}
|
|
265
|
+
state.replaced.push(displayPath);
|
|
266
|
+
}
|
|
267
|
+
await copyFile(sourcePath, targetPath);
|
|
268
|
+
state.hashes[hashPath] = sourceHash;
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
async function readInstalledSkillHashes(root, location) {
|
|
273
|
+
const marker = await readInstallMarker(root);
|
|
274
|
+
return sanitizeHashes(marker.skillHashes?.[location]);
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
async function readInstallMarker(root) {
|
|
278
|
+
try {
|
|
279
|
+
return JSON.parse(await readFile(path.join(root, installMarkerFile), "utf8"));
|
|
280
|
+
} catch {
|
|
281
|
+
return {};
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
function formatConflictMessage(conflicts) {
|
|
286
|
+
const lines = conflicts.map((conflict) => `- ${[conflict.location, "skills", conflict.skill].join("/")}`);
|
|
287
|
+
return `Drawbore will not overwrite skills it does not own:\n${lines.join("\n")}\nRe-run with --force to replace them.`;
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
function isRecord(value) {
|
|
291
|
+
return value !== null && typeof value === "object" && !Array.isArray(value);
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
function hashContents(contents) {
|
|
295
|
+
return createHash("sha256").update(contents).digest("hex");
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
async function pathType(target) {
|
|
299
|
+
try {
|
|
300
|
+
const stats = await stat(target);
|
|
301
|
+
return stats.isDirectory() ? "directory" : "file";
|
|
302
|
+
} catch (error) {
|
|
303
|
+
if (error.code === "ENOENT") return null;
|
|
304
|
+
throw error;
|
|
305
|
+
}
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
async function isDirectory(target) {
|
|
309
|
+
return (await pathType(target)) === "directory";
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
async function assertDirectoryTarget(target, label) {
|
|
313
|
+
const type = await pathType(target);
|
|
314
|
+
if (type === "file") throw new Error(`Cannot install into ${label}: ${target} exists as a file`);
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
export async function createNotebook(root) {
|
|
318
|
+
const destination = path.join(root, notebookDirectory);
|
|
319
|
+
await assertDirectoryTarget(destination, notebookDirectory);
|
|
320
|
+
await mkdir(destination, { recursive: true });
|
|
321
|
+
for (const subdirectory of ["decisions", "work"]) {
|
|
322
|
+
await assertDirectoryTarget(path.join(destination, subdirectory), `${notebookDirectory}/${subdirectory}`);
|
|
323
|
+
}
|
|
324
|
+
await cp(path.join(packageRoot, "templates", "record"), destination, {
|
|
325
|
+
recursive: true,
|
|
326
|
+
force: false,
|
|
327
|
+
errorOnExist: false,
|
|
328
|
+
});
|
|
329
|
+
await mkdir(path.join(destination, "decisions"), { recursive: true });
|
|
330
|
+
await mkdir(path.join(destination, "work"), { recursive: true });
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
export async function addInstruction(root, instructionFile, packageData) {
|
|
334
|
+
const destination = path.join(root, instructionFile);
|
|
335
|
+
const destinationType = await pathType(destination);
|
|
336
|
+
if (destinationType === "directory") throw new Error(`Cannot write ${destination}: path is a directory`);
|
|
337
|
+
const existing = destinationType === "file" ? await readFile(destination, "utf8") : "";
|
|
338
|
+
const block = packageData.instructionTemplate.trim();
|
|
339
|
+
const { start: startMarker, end: endMarker } = instructionMarkers;
|
|
340
|
+
const start = existing.indexOf(startMarker);
|
|
341
|
+
const end = existing.indexOf(endMarker);
|
|
342
|
+
let updated;
|
|
343
|
+
|
|
344
|
+
if (start !== -1 && end !== -1 && end > start) {
|
|
345
|
+
updated = `${existing.slice(0, start)}${block}${existing.slice(end + endMarker.length)}`;
|
|
346
|
+
} else if (start !== -1) {
|
|
347
|
+
updated = `${existing.slice(0, start)}${block}\n`;
|
|
348
|
+
} else {
|
|
349
|
+
const separator = existing.length === 0 ? "" : existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
|
|
350
|
+
updated = `${existing}${separator}${block}\n`;
|
|
351
|
+
}
|
|
352
|
+
await writeFile(destination, updated, "utf8");
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
export async function writeInstallMarker(
|
|
356
|
+
root,
|
|
357
|
+
packageData,
|
|
358
|
+
selectedLocations,
|
|
359
|
+
notebookCreated,
|
|
360
|
+
instructionFiles,
|
|
361
|
+
skillHashes = {},
|
|
362
|
+
) {
|
|
363
|
+
const destination = path.join(root, installMarkerFile);
|
|
364
|
+
const existing = await readInstallMarker(root);
|
|
365
|
+
const payload = {
|
|
366
|
+
version: packageData.version,
|
|
367
|
+
installedAt: new Date().toISOString(),
|
|
368
|
+
namespace: packageData.namespace,
|
|
369
|
+
skills: packageData.skills,
|
|
370
|
+
locations: selectedLocations,
|
|
371
|
+
notebook: notebookCreated ? notebookDirectory : null,
|
|
372
|
+
instructions: instructionFiles,
|
|
373
|
+
skillHashes: mergeSkillHashes(existing.skillHashes, skillHashes),
|
|
374
|
+
};
|
|
375
|
+
await writeFile(destination, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
function mergeSkillHashes(existing, next) {
|
|
379
|
+
const merged = {};
|
|
380
|
+
for (const [location, hashes] of Object.entries(existing ?? {})) {
|
|
381
|
+
const sanitized = sanitizeHashes(hashes);
|
|
382
|
+
if (Object.keys(sanitized).length > 0) merged[location] = sanitized;
|
|
383
|
+
}
|
|
384
|
+
for (const [location, hashes] of Object.entries(next ?? {})) {
|
|
385
|
+
const sanitized = sanitizeHashes(hashes);
|
|
386
|
+
merged[location] = sanitized;
|
|
387
|
+
}
|
|
388
|
+
return merged;
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
function sanitizeHashes(hashes) {
|
|
392
|
+
if (!isRecord(hashes)) return {};
|
|
393
|
+
return Object.fromEntries(
|
|
394
|
+
Object.entries(hashes).filter(([, hash]) => typeof hash === "string" && /^[a-f0-9]{64}$/.test(hash)),
|
|
395
|
+
);
|
|
396
|
+
}
|
|
397
|
+
|
|
398
|
+
async function exists(target) {
|
|
399
|
+
try {
|
|
400
|
+
await access(target);
|
|
401
|
+
return true;
|
|
402
|
+
} catch {
|
|
403
|
+
return false;
|
|
404
|
+
}
|
|
405
|
+
}
|