@kirill.konshin/lint 0.5.1 → 0.5.3
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/README.md +6 -4
- package/dist/lintPrepare.d.ts +32 -31
- package/dist/lintPrepare.d.ts.map +1 -1
- package/dist/lintPrepare.js +261 -125
- package/package.json +5 -3
- package/rules/agent.md +42 -36
- package/rules/openspec.md +12 -0
- package/rules/testing.md +1 -0
- package/skills/lint-repo.md +2 -2
- package/skills/spec-steward/SKILL.md +76 -0
- package/skills/spec-steward/references/apply.md +18 -0
- package/skills/spec-steward/references/audit.md +57 -0
- package/skills/spec-steward/references/contract.md +186 -0
- package/skills/spec-steward/references/criteria.md +59 -0
- package/skills/spec-steward/references/model.md +71 -0
- package/skills/spec-steward/references/review-format.md +61 -0
- package/skills/spec-steward/references/wiring.md +19 -0
- package/skills/spec-steward/scripts/lib/align.mjs +126 -0
- package/skills/spec-steward/scripts/lib/checks.mjs +584 -0
- package/skills/spec-steward/scripts/lib/citations.mjs +156 -0
- package/skills/spec-steward/scripts/lib/corpus.mjs +259 -0
- package/skills/spec-steward/scripts/lib/coverage.mjs +124 -0
- package/skills/spec-steward/scripts/lib/evidence.mjs +335 -0
- package/skills/spec-steward/scripts/lib/git.mjs +138 -0
- package/skills/spec-steward/scripts/lib/review.mjs +347 -0
- package/skills/spec-steward/scripts/lib/scan.mjs +364 -0
- package/skills/spec-steward/scripts/lib/util.mjs +161 -0
- package/skills/spec-steward/scripts/lib/wire.mjs +331 -0
- package/skills/spec-steward/scripts/steward.mjs +350 -0
- package/skills/spec-steward/workflows/audit.js +539 -0
package/dist/lintPrepare.js
CHANGED
|
@@ -2,11 +2,13 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* @kirill.konshin/lint
|
|
4
4
|
*
|
|
5
|
-
* This script
|
|
6
|
-
*
|
|
7
|
-
* symlinks
|
|
8
|
-
*
|
|
9
|
-
*
|
|
5
|
+
* This script makes `rules`, `commands` and `skills` real directories in the consuming project's
|
|
6
|
+
* `.agents` (canonical, cross-tool), `.claude` (Claude Code) and `.codex`, and fills them with
|
|
7
|
+
* file symlinks only: package rules and skills (SKILL.md plus the package README.md alongside it,
|
|
8
|
+
* so a skill can reference `@README.md`; a folder skill with every file it ships) go into all three, pointing straight
|
|
9
|
+
* at the installed
|
|
10
|
+
* package; the user's own files in `.agents` are mirrored into `.claude` and `.codex`. It also
|
|
11
|
+
* generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
|
|
10
12
|
*
|
|
11
13
|
* Usage:
|
|
12
14
|
* lint-prepare init - Initialize AGENTS.md in the current directory (default)
|
|
@@ -27,10 +29,14 @@ const CLAUDE_FILE = 'CLAUDE.md';
|
|
|
27
29
|
const RULES_DIR = path.join(__dirname, '../rules');
|
|
28
30
|
const SKILLS_DIR = path.join(__dirname, '../skills');
|
|
29
31
|
const README_FILE = path.join(__dirname, '../README.md');
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
const
|
|
32
|
+
// `.agents` is the cross-tool location (Codex, Cursor, Antigravity) holding the package links and the user's own
|
|
33
|
+
// files, the latter are mirrored into `.claude` (Claude Code reads nothing else) and `.codex`
|
|
34
|
+
const CANONICAL_AGENT_DIR = '.agents';
|
|
35
|
+
const MIRROR_AGENT_DIRS = ['.claude', '.codex'];
|
|
36
|
+
const AGENT_DIRS = [CANONICAL_AGENT_DIR, ...MIRROR_AGENT_DIRS];
|
|
37
|
+
const AGENT_KINDS = ['rules', 'commands', 'skills'];
|
|
38
|
+
const GITIGNORE = '.gitignore';
|
|
39
|
+
const GITIGNORE_HEADER = '# Generated by @kirill.konshin/lint: symlinks it manages here, your own files stay tracked';
|
|
34
40
|
const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
|
|
35
41
|
const HEADER = `# AI Agent Rules
|
|
36
42
|
|
|
@@ -43,11 +49,7 @@ const FOOTER = `---
|
|
|
43
49
|
|
|
44
50
|
Add your project-specific rules below the comment line.`;
|
|
45
51
|
const GENERATED_MARKER = '<!-- @kirill.konshin/lint:generated -->';
|
|
46
|
-
|
|
47
|
-
* Relative path between the REAL locations of `from` and `to`: the cwd and the package (workspaces, yalc, pnpm store)
|
|
48
|
-
* may be reached through symlinks, and a path computed between a symlinked and a real location dangles.
|
|
49
|
-
*/
|
|
50
|
-
const realRelative = (from, to) => path.relative(fs.realpathSync(from), fs.realpathSync(to));
|
|
52
|
+
const lstat = (file) => fs.lstatSync(file, { throwIfNoEntry: false });
|
|
51
53
|
/**
|
|
52
54
|
* `monorepo-turbo-nx` -> `Monorepo turbo nx`
|
|
53
55
|
*/
|
|
@@ -63,6 +65,140 @@ const readDescription = (content) => {
|
|
|
63
65
|
const description = frontmatter ? parse(frontmatter)?.description : undefined;
|
|
64
66
|
return typeof description === 'string' ? description.trim() : undefined;
|
|
65
67
|
};
|
|
68
|
+
/**
|
|
69
|
+
* `file` is the path inside a rules dir, e.g. `auth.md` or `frontend/react.md`.
|
|
70
|
+
*/
|
|
71
|
+
const toRule = (file, content) => ({
|
|
72
|
+
file,
|
|
73
|
+
name: path.posix.basename(file, '.md'),
|
|
74
|
+
description: readDescription(content),
|
|
75
|
+
content,
|
|
76
|
+
});
|
|
77
|
+
/**
|
|
78
|
+
* Real files under `dir`, as paths relative to `root` - symlinks (incl. the package links next to them), linked
|
|
79
|
+
* directories and dotfiles (`.gitignore`, `.DS_Store`) are skipped.
|
|
80
|
+
*/
|
|
81
|
+
function listRealFiles(root, dir = root) {
|
|
82
|
+
return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
|
|
83
|
+
const entryPath = path.join(dir, entry.name);
|
|
84
|
+
if (entry.name.startsWith('.'))
|
|
85
|
+
return [];
|
|
86
|
+
if (entry.isDirectory())
|
|
87
|
+
return listRealFiles(root, entryPath);
|
|
88
|
+
return entry.isFile() ? [path.relative(root, entryPath)] : [];
|
|
89
|
+
});
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Dead symlinks under `dir`, walking real directories only.
|
|
93
|
+
*/
|
|
94
|
+
function findDeadLinks(dir) {
|
|
95
|
+
return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
|
|
96
|
+
const entryPath = path.join(dir, entry.name);
|
|
97
|
+
if (entry.isDirectory())
|
|
98
|
+
return findDeadLinks(entryPath);
|
|
99
|
+
return entry.isSymbolicLink() && !fs.existsSync(entryPath) ? [entryPath] : [];
|
|
100
|
+
});
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* Remove `link` and the directories it leaves empty, up to `root`.
|
|
104
|
+
*/
|
|
105
|
+
function removeLink(link, root) {
|
|
106
|
+
fs.unlinkSync(link);
|
|
107
|
+
for (let dir = path.dirname(link); dir !== root && !fs.readdirSync(dir).length; dir = path.dirname(dir)) {
|
|
108
|
+
fs.rmdirSync(dir);
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* mkdir -p `dir` (relative to cwd, starting with an agent dir, which itself may be a link) without going through
|
|
113
|
+
* links below it: false when a part is a symlink or a file - those are the user's, nothing is written through them.
|
|
114
|
+
*/
|
|
115
|
+
function ensureRealDir(cwd, dir) {
|
|
116
|
+
const [agentDir, ...parts] = dir.split(path.sep);
|
|
117
|
+
let current = path.join(cwd, agentDir);
|
|
118
|
+
fs.mkdirSync(current, { recursive: true });
|
|
119
|
+
for (const part of parts) {
|
|
120
|
+
current = path.join(current, part);
|
|
121
|
+
const stat = lstat(current);
|
|
122
|
+
if (!stat)
|
|
123
|
+
fs.mkdirSync(current);
|
|
124
|
+
else if (!stat.isDirectory())
|
|
125
|
+
return false;
|
|
126
|
+
}
|
|
127
|
+
return true;
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* Point `link` (relative to cwd) at `target`, unless the spot is the user's: a real file there, or a linked
|
|
131
|
+
* directory on the way. Returns whether the link is in place.
|
|
132
|
+
*/
|
|
133
|
+
function placeLink(cwd, link, target) {
|
|
134
|
+
const linkPath = path.join(cwd, link);
|
|
135
|
+
if (!ensureRealDir(cwd, path.dirname(link))) {
|
|
136
|
+
console.log(`Skipped ${link}: ${path.dirname(link)} is not a real directory`);
|
|
137
|
+
return false;
|
|
138
|
+
}
|
|
139
|
+
const stat = lstat(linkPath);
|
|
140
|
+
if (stat && !stat.isSymbolicLink()) {
|
|
141
|
+
console.log(`Kept ${link}: not a symlink`);
|
|
142
|
+
return false;
|
|
143
|
+
}
|
|
144
|
+
// relative between REAL locations: cwd and the package (workspaces, yalc, pnpm store) may be reached through
|
|
145
|
+
// symlinks, and a path computed between a symlinked and a real location dangles
|
|
146
|
+
const text = path.relative(fs.realpathSync(path.dirname(linkPath)), target);
|
|
147
|
+
if (stat && fs.readlinkSync(linkPath) === text)
|
|
148
|
+
return true;
|
|
149
|
+
if (stat)
|
|
150
|
+
fs.unlinkSync(linkPath);
|
|
151
|
+
fs.symlinkSync(text, linkPath);
|
|
152
|
+
return true;
|
|
153
|
+
}
|
|
154
|
+
/**
|
|
155
|
+
* Links listed in a `.gitignore` this tool generated - it doubles as the record of what to clean up next time.
|
|
156
|
+
*/
|
|
157
|
+
function readManifest(gitignore) {
|
|
158
|
+
const content = fs.existsSync(gitignore) ? fs.readFileSync(gitignore, 'utf-8') : '';
|
|
159
|
+
if (!content.startsWith(GITIGNORE_HEADER))
|
|
160
|
+
return [];
|
|
161
|
+
return content
|
|
162
|
+
.split('\n')
|
|
163
|
+
.filter((line) => line.startsWith('/') && line !== `/${GITIGNORE}`)
|
|
164
|
+
.map((line) => path.normalize(line.slice(1)));
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* Write the `.gitignore` listing `links` (remove it when there are none), unless the user owns that file.
|
|
168
|
+
*/
|
|
169
|
+
function writeManifest(gitignore, links) {
|
|
170
|
+
const exists = fs.existsSync(gitignore);
|
|
171
|
+
if (exists && !fs.readFileSync(gitignore, 'utf-8').startsWith(GITIGNORE_HEADER))
|
|
172
|
+
return;
|
|
173
|
+
if (!links.length) {
|
|
174
|
+
if (exists)
|
|
175
|
+
fs.unlinkSync(gitignore);
|
|
176
|
+
return;
|
|
177
|
+
}
|
|
178
|
+
const entries = links.map((link) => `/${link.split(path.sep).join('/')}`).sort();
|
|
179
|
+
fs.writeFileSync(gitignore, [GITIGNORE_HEADER, `/${GITIGNORE}`, ...entries, ''].join('\n'));
|
|
180
|
+
}
|
|
181
|
+
/**
|
|
182
|
+
* Links to place, keyed by their path relative to cwd: package files into every agent dir, the user's own `.agents`
|
|
183
|
+
* files into the mirrors. A user file wins over the package file at the same path.
|
|
184
|
+
*/
|
|
185
|
+
function plannedLinks(cwd, packageFiles, userFiles) {
|
|
186
|
+
const canonicalDir = path.join(fs.realpathSync(cwd), CANONICAL_AGENT_DIR);
|
|
187
|
+
const links = new Map();
|
|
188
|
+
for (const [file, source] of packageFiles) {
|
|
189
|
+
if (userFiles.has(file)) {
|
|
190
|
+
console.log(`${path.join(CANONICAL_AGENT_DIR, file)} overrides the package file`);
|
|
191
|
+
continue;
|
|
192
|
+
}
|
|
193
|
+
for (const dir of AGENT_DIRS)
|
|
194
|
+
links.set(path.join(dir, file), fs.realpathSync(source));
|
|
195
|
+
}
|
|
196
|
+
for (const file of userFiles.keys()) {
|
|
197
|
+
for (const dir of MIRROR_AGENT_DIRS)
|
|
198
|
+
links.set(path.join(dir, file), path.join(canonicalDir, file));
|
|
199
|
+
}
|
|
200
|
+
return links;
|
|
201
|
+
}
|
|
66
202
|
/**
|
|
67
203
|
* Read all markdown files from the package rules directory.
|
|
68
204
|
*/
|
|
@@ -78,67 +214,77 @@ export function readRules() {
|
|
|
78
214
|
.sort();
|
|
79
215
|
for (const file of files) {
|
|
80
216
|
const filePath = path.join(RULES_DIR, file);
|
|
81
|
-
|
|
82
|
-
rules.push({
|
|
83
|
-
file,
|
|
84
|
-
name: file.replace('.md', ''),
|
|
85
|
-
description: readDescription(content),
|
|
86
|
-
content,
|
|
87
|
-
});
|
|
217
|
+
rules.push(toRule(file, fs.readFileSync(filePath, 'utf-8')));
|
|
88
218
|
}
|
|
89
219
|
return rules;
|
|
90
220
|
}
|
|
91
221
|
/**
|
|
92
|
-
* Read
|
|
93
|
-
*
|
|
222
|
+
* Read the package skills directory. A markdown file becomes its own skill, named after the file (without extension)
|
|
223
|
+
* - e.g. `lint-repo.md` becomes the `lint-repo` skill; a directory holding a `SKILL.md` is a folder skill named after
|
|
224
|
+
* the directory, shipped with its scripts and references.
|
|
94
225
|
*/
|
|
95
226
|
export function readSkills() {
|
|
96
227
|
if (!fs.existsSync(SKILLS_DIR))
|
|
97
228
|
return [];
|
|
98
229
|
return fs
|
|
99
|
-
.readdirSync(SKILLS_DIR)
|
|
100
|
-
.
|
|
101
|
-
.
|
|
102
|
-
|
|
230
|
+
.readdirSync(SKILLS_DIR, { withFileTypes: true })
|
|
231
|
+
.flatMap((entry) => {
|
|
232
|
+
if (entry.isDirectory() && fs.existsSync(path.join(SKILLS_DIR, entry.name, 'SKILL.md'))) {
|
|
233
|
+
return [{ file: entry.name, name: entry.name, folder: true }];
|
|
234
|
+
}
|
|
235
|
+
return entry.isFile() && entry.name.endsWith('.md')
|
|
236
|
+
? [{ file: entry.name, name: entry.name.replace('.md', '') }]
|
|
237
|
+
: [];
|
|
238
|
+
})
|
|
239
|
+
.sort((a, b) => a.name.localeCompare(b.name));
|
|
103
240
|
}
|
|
104
241
|
/**
|
|
105
|
-
*
|
|
106
|
-
*
|
|
107
|
-
*
|
|
242
|
+
* Package files to link, keyed by their path inside an agent dir: `rules/<file>`, `skills/<name>/SKILL.md` plus the
|
|
243
|
+
* package README.md next to it, so a skill can reference `@README.md`, and every file of a folder skill at its own
|
|
244
|
+
* relative path.
|
|
108
245
|
*/
|
|
109
|
-
export function
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
for (const
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
246
|
+
export function packageFiles(rules, skills) {
|
|
247
|
+
const files = new Map();
|
|
248
|
+
const hasReadme = fs.existsSync(README_FILE);
|
|
249
|
+
for (const rule of rules) {
|
|
250
|
+
files.set(path.join('rules', rule.file), path.join(RULES_DIR, rule.file));
|
|
251
|
+
}
|
|
252
|
+
for (const skill of skills) {
|
|
253
|
+
if (skill.folder) {
|
|
254
|
+
const root = path.join(SKILLS_DIR, skill.file);
|
|
255
|
+
for (const file of listRealFiles(root)) {
|
|
256
|
+
files.set(path.join('skills', skill.name, file), path.join(root, file));
|
|
257
|
+
}
|
|
258
|
+
continue;
|
|
118
259
|
}
|
|
260
|
+
files.set(path.join('skills', skill.name, 'SKILL.md'), path.join(SKILLS_DIR, skill.file));
|
|
261
|
+
if (hasReadme)
|
|
262
|
+
files.set(path.join('skills', skill.name, 'README.md'), README_FILE);
|
|
119
263
|
}
|
|
264
|
+
return files;
|
|
120
265
|
}
|
|
121
266
|
/**
|
|
122
|
-
*
|
|
267
|
+
* The user's own files in `.agents` `rules`, `commands` and `skills`, keyed like packageFiles() - everything there
|
|
268
|
+
* except the package links (and dotfiles).
|
|
123
269
|
*/
|
|
124
|
-
export function
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
console.error(`${CLAUDE_FILE} exists and is not a symlink.`);
|
|
134
|
-
console.error('Remove or back it up manually, then re-run.');
|
|
135
|
-
process.exit(1);
|
|
270
|
+
export function readUserFiles(cwd) {
|
|
271
|
+
const files = new Map();
|
|
272
|
+
for (const kind of AGENT_KINDS) {
|
|
273
|
+
const root = path.join(cwd, CANONICAL_AGENT_DIR, kind);
|
|
274
|
+
if (!fs.statSync(root, { throwIfNoEntry: false })?.isDirectory())
|
|
275
|
+
continue;
|
|
276
|
+
for (const file of listRealFiles(root)) {
|
|
277
|
+
files.set(path.join(kind, file), path.join(root, file));
|
|
278
|
+
}
|
|
136
279
|
}
|
|
280
|
+
return files;
|
|
137
281
|
}
|
|
138
282
|
/**
|
|
139
|
-
*
|
|
140
|
-
*
|
|
141
|
-
*
|
|
283
|
+
* Make `rules`, `commands` and `skills` real directories in every agent dir and link the files we know into them:
|
|
284
|
+
* package files into all three, pointing straight at the package, the user's own `.agents` files into `.claude` and
|
|
285
|
+
* `.codex`. Real files and linked directories are the user's - never written over or through. Dead links are
|
|
286
|
+
* removed, and so are links from the previous run that are no longer placed: each directory's generated `.gitignore`
|
|
287
|
+
* records them (and keeps them out of git, so the user's own files there stay tracked).
|
|
142
288
|
*
|
|
143
289
|
* FIXME Codex Includes
|
|
144
290
|
* https://github.com/openai/codex/issues/17401
|
|
@@ -149,66 +295,65 @@ export function checkClaudeMdSafety(claudeMdPath) {
|
|
|
149
295
|
* (Claude Code itself doesn't need it - it auto-loads every file under `.claude/rules` regardless of whether it's
|
|
150
296
|
* indexed anywhere).
|
|
151
297
|
*/
|
|
152
|
-
export function
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
298
|
+
export function syncAgentDirs(cwd, packageFiles, userFiles) {
|
|
299
|
+
const links = plannedLinks(cwd, packageFiles, userFiles);
|
|
300
|
+
for (const dir of AGENT_DIRS) {
|
|
301
|
+
for (const kind of AGENT_KINDS) {
|
|
302
|
+
const root = path.join(dir, kind);
|
|
303
|
+
const rootPath = path.join(cwd, root);
|
|
304
|
+
const gitignore = path.join(rootPath, GITIGNORE);
|
|
305
|
+
if (!ensureRealDir(cwd, root)) {
|
|
306
|
+
console.log(`Skipped ${root}: not a real directory`);
|
|
307
|
+
continue;
|
|
308
|
+
}
|
|
309
|
+
for (const link of findDeadLinks(rootPath)) {
|
|
310
|
+
removeLink(link, rootPath);
|
|
311
|
+
}
|
|
312
|
+
const placed = [];
|
|
313
|
+
for (const [link, target] of links) {
|
|
314
|
+
if (link.startsWith(root + path.sep) && placeLink(cwd, link, target)) {
|
|
315
|
+
placed.push(path.relative(root, link));
|
|
316
|
+
}
|
|
317
|
+
}
|
|
318
|
+
for (const link of readManifest(gitignore)) {
|
|
319
|
+
const linkPath = path.join(rootPath, link);
|
|
320
|
+
if (!placed.includes(link) && lstat(linkPath)?.isSymbolicLink())
|
|
321
|
+
removeLink(linkPath, rootPath);
|
|
322
|
+
}
|
|
323
|
+
writeManifest(gitignore, placed);
|
|
164
324
|
}
|
|
165
|
-
|
|
166
|
-
});
|
|
325
|
+
}
|
|
167
326
|
}
|
|
168
327
|
/**
|
|
169
|
-
*
|
|
170
|
-
* that isn't a symlink - same reasoning as checkRulesDirSafety. Only the specific skill's
|
|
171
|
-
* own subdirectory is checked/wiped, not the whole `.claude/skills` or `.codex/skills`
|
|
172
|
-
* parent, since other packages (or the user) may keep unrelated skills there.
|
|
328
|
+
* Rules as they end up in `.agents/rules`: the package ones plus the user's own, which win on the same file.
|
|
173
329
|
*/
|
|
174
|
-
export function
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
for (const
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
process.exit(1);
|
|
183
|
-
}
|
|
330
|
+
export function installedRules(rules, userFiles) {
|
|
331
|
+
const byFile = new Map(rules.map((rule) => [rule.file, rule]));
|
|
332
|
+
const rulesDir = `rules${path.sep}`;
|
|
333
|
+
for (const [file, source] of userFiles) {
|
|
334
|
+
if (!file.startsWith(rulesDir) || !file.endsWith('.md'))
|
|
335
|
+
continue;
|
|
336
|
+
const ruleFile = file.slice(rulesDir.length).split(path.sep).join('/');
|
|
337
|
+
byFile.set(ruleFile, toRule(ruleFile, fs.readFileSync(source, 'utf-8')));
|
|
184
338
|
}
|
|
339
|
+
return [...byFile].sort(([a], [b]) => (a < b ? -1 : 1)).map(([, rule]) => rule);
|
|
185
340
|
}
|
|
186
341
|
/**
|
|
187
|
-
*
|
|
188
|
-
* `<cwd>/.codex/skills/<name>/`, so both Claude Code and Codex CLI can discover and run
|
|
189
|
-
* them. The package README.md is symlinked alongside SKILL.md so a skill can reference it
|
|
190
|
-
* via `@README.md` regardless of how the tool resolves relative mentions.
|
|
342
|
+
* Fail if `CLAUDE.md` exists and isn't a symlink - we don't want to silently blow away a file the user wrote.
|
|
191
343
|
*/
|
|
192
|
-
export function
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
if (hasReadme) {
|
|
205
|
-
const readmeLink = path.join(skillDir, 'README.md');
|
|
206
|
-
fs.symlinkSync(realRelative(skillDir, README_FILE), readmeLink);
|
|
207
|
-
}
|
|
208
|
-
targetDirs.push(skillDir);
|
|
209
|
-
}
|
|
344
|
+
export function checkClaudeMdSafety(claudeMdPath) {
|
|
345
|
+
let stat;
|
|
346
|
+
try {
|
|
347
|
+
stat = fs.lstatSync(claudeMdPath);
|
|
348
|
+
}
|
|
349
|
+
catch {
|
|
350
|
+
return;
|
|
351
|
+
}
|
|
352
|
+
if (!stat.isSymbolicLink()) {
|
|
353
|
+
console.error(`${CLAUDE_FILE} exists and is not a symlink.`);
|
|
354
|
+
console.error('Remove or back it up manually, then re-run.');
|
|
355
|
+
process.exit(1);
|
|
210
356
|
}
|
|
211
|
-
return targetDirs;
|
|
212
357
|
}
|
|
213
358
|
/**
|
|
214
359
|
* Symlink CLAUDE.md -> AGENTS.md so both point at the same generated content.
|
|
@@ -219,24 +364,23 @@ export function symlinkClaudeMd(cwd) {
|
|
|
219
364
|
fs.symlinkSync(AGENTS_FILE, claudeMdPath);
|
|
220
365
|
}
|
|
221
366
|
/**
|
|
222
|
-
* Generate AGENTS.md with a `# Rules` section: a `## Title` block per rule file
|
|
223
|
-
* frontmatter `description` and a reference to
|
|
367
|
+
* Generate AGENTS.md with a `# Rules` section: a `## Title` block per rule file (the package's
|
|
368
|
+
* and the user's own) with its frontmatter `description` and a reference to its `.agents/rules` entry.
|
|
224
369
|
*
|
|
225
|
-
* `.claude/rules/*.md` are symlinked by
|
|
370
|
+
* `.claude/rules/*.md` are symlinked by syncAgentDirs() above and auto-discovered by
|
|
226
371
|
* Claude Code at launch (confirmed: Claude Code recursively loads every `.md` file
|
|
227
372
|
* under `.claude/rules`, symlinks included) - no reference to them is needed here.
|
|
228
373
|
* The sections below are for other tools that only read AGENTS.md.
|
|
229
374
|
*/
|
|
230
|
-
export function generateAgentsFile(rules,
|
|
231
|
-
// where the rules really are, e.g. `node_modules/@kirill.konshin/lint/rules`, `packages/lint/rules` in a workspace
|
|
232
|
-
const relativeRulesDir = realRelative(cwd, RULES_DIR).split(path.sep).join('/');
|
|
375
|
+
export function generateAgentsFile(rules, customSection) {
|
|
233
376
|
/**
|
|
234
377
|
* @see https://code.claude.com/docs/en/memory#import-additional-files
|
|
235
378
|
* @see https://github.com/anthropics/claude-code/issues/13614 @import -> @path/file.md in Claude
|
|
236
379
|
* @see https://github.com/openai/codex/issues/17401 - no @path/file.md in Codex yet
|
|
237
380
|
*/
|
|
238
381
|
const sections = rules.map((rule) => {
|
|
239
|
-
|
|
382
|
+
// the canonical entry (a package link or the user's own file), not the package install path
|
|
383
|
+
const rulePath = `${CANONICAL_AGENT_DIR}/rules/${rule.file}`;
|
|
240
384
|
return [
|
|
241
385
|
`## ${toTitle(rule.name)}`,
|
|
242
386
|
rule.description,
|
|
@@ -287,23 +431,15 @@ export function main() {
|
|
|
287
431
|
}
|
|
288
432
|
}
|
|
289
433
|
if (command === 'update' || command === 'init') {
|
|
290
|
-
for (const dir of RULES_TARGET_DIRS) {
|
|
291
|
-
checkRulesDirSafety(path.join(cwd, dir));
|
|
292
|
-
}
|
|
293
434
|
checkClaudeMdSafety(claudeMdPath);
|
|
294
435
|
const rules = readRules();
|
|
295
436
|
console.log(`Found ${rules.length} rule files: ${rules.map((r) => r.name).join(', ')}`);
|
|
296
|
-
const targetRulesDirs = symlinkRules(cwd, rules);
|
|
297
|
-
for (const targetRulesDir of targetRulesDirs) {
|
|
298
|
-
console.log(`Symlinked rules to ${targetRulesDir}`);
|
|
299
|
-
}
|
|
300
437
|
const skills = readSkills();
|
|
301
438
|
console.log(`Found ${skills.length} skill(s): ${skills.map((s) => s.name).join(', ')}`);
|
|
302
|
-
const
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
const content = generateAgentsFile(rules, cwd, customSection);
|
|
439
|
+
const userFiles = readUserFiles(cwd);
|
|
440
|
+
syncAgentDirs(cwd, packageFiles(rules, skills), userFiles);
|
|
441
|
+
console.log(`Synced ${AGENT_DIRS.join(', ')}, mirrored ${userFiles.size} own file(s) from ${CANONICAL_AGENT_DIR}`);
|
|
442
|
+
const content = generateAgentsFile(installedRules(rules, userFiles), customSection);
|
|
307
443
|
fs.writeFileSync(targetPath, content, 'utf-8');
|
|
308
444
|
console.log(`${exists ? 'Updated' : 'Created'} ${AGENTS_FILE}`);
|
|
309
445
|
symlinkClaudeMd(cwd);
|
package/package.json
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kirill.konshin/lint",
|
|
3
3
|
"description": "ESLint + Prettier + lint-staged config and AI agent rules/skills for monorepos",
|
|
4
|
-
"version": "0.5.
|
|
4
|
+
"version": "0.5.3",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"skipGenerate": true,
|
|
7
7
|
"bin": {
|
|
8
|
-
"lint-prepare": "./dist/lintPrepare.js"
|
|
8
|
+
"lint-prepare": "./dist/lintPrepare.js",
|
|
9
|
+
"spec-steward": "./skills/spec-steward/scripts/steward.mjs"
|
|
9
10
|
},
|
|
10
11
|
"main": "./dist/index.js",
|
|
11
12
|
"module": "./dist/index.js",
|
|
@@ -41,7 +42,8 @@
|
|
|
41
42
|
"files": [
|
|
42
43
|
"dist",
|
|
43
44
|
"rules",
|
|
44
|
-
"skills"
|
|
45
|
+
"skills",
|
|
46
|
+
"!skills/**/*.test.mjs"
|
|
45
47
|
],
|
|
46
48
|
"dependencies": {
|
|
47
49
|
"@eslint/config-helpers": "^0.7.0",
|