@kirill.konshin/lint 0.5.5 → 0.6.1
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 +38 -3
- package/commands/spec-author.md +39 -0
- package/dist/configs/base.d.ts +4 -3
- package/dist/configs/base.js +61 -74
- package/dist/configs/imports.d.ts +3 -2
- package/dist/configs/imports.js +95 -146
- package/dist/configs/nx.d.ts +4 -3
- package/dist/configs/nx.js +31 -41
- package/dist/configs/prettier.d.ts +3 -2
- package/dist/configs/prettier.js +19 -16
- package/dist/configs/promise.d.ts +3 -2
- package/dist/configs/promise.js +16 -16
- package/dist/configs/react.d.ts +4 -3
- package/dist/configs/react.js +178 -217
- package/dist/configs/storybook.d.ts +4 -3
- package/dist/configs/storybook.js +22 -22
- package/dist/configs/tailwind.d.ts +4 -3
- package/dist/configs/tailwind.js +67 -91
- package/dist/configs/testing.d.ts +7 -6
- package/dist/configs/testing.js +112 -146
- package/dist/configs/turbo.d.ts +4 -3
- package/dist/configs/turbo.js +19 -27
- package/dist/configs/typescriptTypeAware.d.ts +4 -3
- package/dist/configs/typescriptTypeAware.js +99 -95
- package/dist/configs/unicorn.d.ts +3 -2
- package/dist/configs/unicorn.js +34 -41
- package/dist/exts.d.ts +2 -1
- package/dist/exts.js +10 -11
- package/dist/index.d.ts +44 -42
- package/dist/index.js +53 -85
- package/dist/lib.d.ts +21 -21
- package/dist/lib.js +262 -301
- package/dist/lintPrepare.d.ts +20 -17
- package/dist/lintPrepare.js +341 -371
- package/dist/lintStaged.d.ts +4 -3
- package/dist/lintStaged.js +25 -22
- package/dist/prettier.d.ts +4 -3
- package/dist/prettier.js +16 -17
- package/dist/restrictions.d.ts +11 -10
- package/dist/restrictions.js +18 -22
- package/dist/yarn.cjs +79 -98
- package/dist/yarn.d.cts +3 -2
- package/package.json +22 -8
- package/rules/agent.md +2 -0
- package/rules/openspec.md +1 -1
- package/skills/spec-steward/SKILL.md +4 -12
- package/skills/spec-steward/references/audit.md +18 -43
- package/skills/spec-steward/references/contract.md +9 -9
- package/skills/spec-steward/references/criteria.md +4 -4
- package/skills/spec-steward/references/review-format.md +6 -6
- package/skills/spec-steward/references/wiring.md +2 -2
- package/skills/spec-steward/references/worker.md +67 -0
- package/skills/spec-steward/sweeps.json +49 -0
- package/skills/spec-tools/SKILL.md +48 -0
- package/skills/spec-tools/references/contract.md +111 -0
- package/skills/spec-tools/references/gitlab.md +120 -0
- package/skills/spec-tools/scripts/cli.js +8129 -0
- package/skills/spec-verify/SKILL.md +153 -0
- package/dist/configs/base.d.ts.map +0 -1
- package/dist/configs/imports.d.ts.map +0 -1
- package/dist/configs/nx.d.ts.map +0 -1
- package/dist/configs/prettier.d.ts.map +0 -1
- package/dist/configs/promise.d.ts.map +0 -1
- package/dist/configs/react.d.ts.map +0 -1
- package/dist/configs/storybook.d.ts.map +0 -1
- package/dist/configs/tailwind.d.ts.map +0 -1
- package/dist/configs/testing.d.ts.map +0 -1
- package/dist/configs/turbo.d.ts.map +0 -1
- package/dist/configs/typescriptTypeAware.d.ts.map +0 -1
- package/dist/configs/unicorn.d.ts.map +0 -1
- package/dist/exts.d.ts.map +0 -1
- package/dist/index.d.ts.map +0 -1
- package/dist/lib.d.ts.map +0 -1
- package/dist/lintPrepare.d.ts.map +0 -1
- package/dist/lintStaged.d.ts.map +0 -1
- package/dist/prettier.d.ts.map +0 -1
- package/dist/restrictions.d.ts.map +0 -1
- package/dist/yarn.d.cts.map +0 -1
- package/skills/spec-steward/scripts/lib/align.mjs +0 -127
- package/skills/spec-steward/scripts/lib/checks.mjs +0 -589
- package/skills/spec-steward/scripts/lib/citations.mjs +0 -156
- package/skills/spec-steward/scripts/lib/corpus.mjs +0 -256
- package/skills/spec-steward/scripts/lib/coverage.mjs +0 -123
- package/skills/spec-steward/scripts/lib/evidence.mjs +0 -334
- package/skills/spec-steward/scripts/lib/git.mjs +0 -138
- package/skills/spec-steward/scripts/lib/review.mjs +0 -347
- package/skills/spec-steward/scripts/lib/scan.mjs +0 -364
- package/skills/spec-steward/scripts/lib/util.mjs +0 -161
- package/skills/spec-steward/scripts/lib/wire.mjs +0 -331
- package/skills/spec-steward/scripts/steward.mjs +0 -350
- package/skills/spec-steward/workflows/audit.js +0 -539
package/dist/lintPrepare.js
CHANGED
|
@@ -1,41 +1,45 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
import { fileURLToPath } from "node:url";
|
|
4
|
+
import fs from "node:fs";
|
|
5
|
+
import { parse } from "yaml";
|
|
6
|
+
//#region src/lintPrepare.ts
|
|
2
7
|
/**
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
import fs from 'node:fs';
|
|
21
|
-
import path from 'node:path';
|
|
22
|
-
import { fileURLToPath } from 'node:url';
|
|
23
|
-
import { parse } from 'yaml';
|
|
8
|
+
* @kirill.konshin/lint
|
|
9
|
+
*
|
|
10
|
+
* This script makes `rules`, `commands` and `skills` real directories in the consuming project's
|
|
11
|
+
* `.agents` (canonical, cross-tool) and `.claude` (Claude Code), and fills them with
|
|
12
|
+
* file symlinks only: package rules, commands and skills (every file a skill folder ships, plus the package
|
|
13
|
+
* README.md next to its SKILL.md, so a skill can reference `@README.md`) go into both, pointing
|
|
14
|
+
* straight at the installed package; the user's own files in `.agents` are mirrored into `.claude`. It also
|
|
15
|
+
* generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
|
|
16
|
+
*
|
|
17
|
+
* Usage:
|
|
18
|
+
* lint-prepare init - Initialize AGENTS.md in the current directory (default)
|
|
19
|
+
* lint-prepare update - Force update AGENTS.md even if it exists
|
|
20
|
+
* lint-prepare - Same as init
|
|
21
|
+
*
|
|
22
|
+
* The module also exports its functions and only runs `main()` when executed directly,
|
|
23
|
+
* so it can be imported (for testing/reuse) without side effects.
|
|
24
|
+
*/
|
|
24
25
|
const __filename = fileURLToPath(import.meta.url);
|
|
25
26
|
const __dirname = path.dirname(__filename);
|
|
26
|
-
const AGENTS_FILE =
|
|
27
|
-
const CLAUDE_FILE =
|
|
28
|
-
const RULES_DIR = path.join(__dirname,
|
|
29
|
-
const SKILLS_DIR = path.join(__dirname,
|
|
30
|
-
const
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
const
|
|
34
|
-
const MIRROR_AGENT_DIRS = ['.claude'];
|
|
27
|
+
const AGENTS_FILE = "AGENTS.md";
|
|
28
|
+
const CLAUDE_FILE = "CLAUDE.md";
|
|
29
|
+
const RULES_DIR = path.join(__dirname, "../rules");
|
|
30
|
+
const SKILLS_DIR = path.join(__dirname, "../skills");
|
|
31
|
+
const COMMANDS_DIR = path.join(__dirname, "../commands");
|
|
32
|
+
const README_FILE = path.join(__dirname, "../README.md");
|
|
33
|
+
const CANONICAL_AGENT_DIR = ".agents";
|
|
34
|
+
const MIRROR_AGENT_DIRS = [".claude"];
|
|
35
35
|
const AGENT_DIRS = [CANONICAL_AGENT_DIR, ...MIRROR_AGENT_DIRS];
|
|
36
|
-
const AGENT_KINDS = [
|
|
37
|
-
|
|
38
|
-
|
|
36
|
+
const AGENT_KINDS = [
|
|
37
|
+
"rules",
|
|
38
|
+
"commands",
|
|
39
|
+
"skills"
|
|
40
|
+
];
|
|
41
|
+
const GITIGNORE = ".gitignore";
|
|
42
|
+
const GITIGNORE_HEADER = "# Generated by @kirill.konshin/lint: symlinks it manages here, your own files stay tracked";
|
|
39
43
|
const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
|
|
40
44
|
const HEADER = `# AI Agent Rules
|
|
41
45
|
|
|
@@ -47,401 +51,367 @@ const FOOTER = `---
|
|
|
47
51
|
# Custom Rules
|
|
48
52
|
|
|
49
53
|
Add your project-specific rules below the comment line.`;
|
|
50
|
-
const GENERATED_MARKER =
|
|
54
|
+
const GENERATED_MARKER = "<!-- @kirill.konshin/lint:generated -->";
|
|
51
55
|
const lstat = (file) => fs.lstatSync(file, { throwIfNoEntry: false });
|
|
52
56
|
/**
|
|
53
|
-
|
|
54
|
-
|
|
57
|
+
* `monorepo-turbo-nx` -> `Monorepo turbo nx`
|
|
58
|
+
*/
|
|
55
59
|
const toTitle = (name) => {
|
|
56
|
-
|
|
57
|
-
|
|
60
|
+
const title = name.replaceAll("-", " ");
|
|
61
|
+
return title.charAt(0).toUpperCase() + title.slice(1);
|
|
58
62
|
};
|
|
59
63
|
/**
|
|
60
|
-
|
|
61
|
-
|
|
64
|
+
* A rule's YAML frontmatter, empty when it has none.
|
|
65
|
+
*/
|
|
62
66
|
const readFrontmatter = (content) => {
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
67
|
+
const frontmatter = FRONTMATTER.exec(content)?.[1];
|
|
68
|
+
const parsed = frontmatter ? parse(frontmatter) : void 0;
|
|
69
|
+
return parsed && typeof parsed === "object" ? parsed : {};
|
|
66
70
|
};
|
|
67
71
|
/**
|
|
68
|
-
|
|
69
|
-
|
|
72
|
+
* A frontmatter field read as a list of strings: one string, or a list of them.
|
|
73
|
+
*/
|
|
70
74
|
const stringList = (value) => {
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
return strings.length ? strings : undefined;
|
|
75
|
+
const strings = (typeof value === "string" ? [value] : Array.isArray(value) ? value : []).filter((item) => typeof item === "string" && item.trim() !== "");
|
|
76
|
+
return strings.length ? strings : void 0;
|
|
74
77
|
};
|
|
75
78
|
/**
|
|
76
|
-
|
|
77
|
-
|
|
79
|
+
* `file` is the path inside a rules dir, e.g. `auth.md` or `frontend/react.md`.
|
|
80
|
+
*/
|
|
78
81
|
const toRule = (file, content) => {
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
82
|
+
const { description, paths } = readFrontmatter(content);
|
|
83
|
+
return {
|
|
84
|
+
file,
|
|
85
|
+
name: path.posix.basename(file, ".md"),
|
|
86
|
+
description: typeof description === "string" ? description.trim() : void 0,
|
|
87
|
+
paths: stringList(paths),
|
|
88
|
+
content
|
|
89
|
+
};
|
|
87
90
|
};
|
|
88
91
|
/**
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
+
* Real files under `dir`, as paths relative to `root` - symlinks (incl. the package links next to them), linked
|
|
93
|
+
* directories and dotfiles (`.gitignore`, `.DS_Store`) are skipped.
|
|
94
|
+
*/
|
|
92
95
|
function listRealFiles(root, dir = root) {
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
return entry.isFile() ? [path.relative(root, entryPath)] : [];
|
|
100
|
-
});
|
|
96
|
+
return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
|
|
97
|
+
const entryPath = path.join(dir, entry.name);
|
|
98
|
+
if (entry.name.startsWith(".")) return [];
|
|
99
|
+
if (entry.isDirectory()) return listRealFiles(root, entryPath);
|
|
100
|
+
return entry.isFile() ? [path.relative(root, entryPath)] : [];
|
|
101
|
+
});
|
|
101
102
|
}
|
|
102
103
|
/**
|
|
103
|
-
|
|
104
|
-
|
|
104
|
+
* Dead symlinks under `dir`, walking real directories only.
|
|
105
|
+
*/
|
|
105
106
|
function findDeadLinks(dir) {
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
});
|
|
107
|
+
return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
|
|
108
|
+
const entryPath = path.join(dir, entry.name);
|
|
109
|
+
if (entry.isDirectory()) return findDeadLinks(entryPath);
|
|
110
|
+
return entry.isSymbolicLink() && !fs.existsSync(entryPath) ? [entryPath] : [];
|
|
111
|
+
});
|
|
112
112
|
}
|
|
113
113
|
/**
|
|
114
|
-
|
|
115
|
-
|
|
114
|
+
* Remove `link` and the directories it leaves empty, up to `root`.
|
|
115
|
+
*/
|
|
116
116
|
function removeLink(link, root) {
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
fs.rmdirSync(dir);
|
|
120
|
-
}
|
|
117
|
+
fs.unlinkSync(link);
|
|
118
|
+
for (let dir = path.dirname(link); dir !== root && !fs.readdirSync(dir).length; dir = path.dirname(dir)) fs.rmdirSync(dir);
|
|
121
119
|
}
|
|
122
120
|
/**
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
121
|
+
* mkdir -p `dir` (relative to cwd, starting with an agent dir, which itself may be a link) without going through
|
|
122
|
+
* links below it: false when a part is a symlink or a file - those are the user's, nothing is written through them.
|
|
123
|
+
*/
|
|
126
124
|
function ensureRealDir(cwd, dir) {
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
}
|
|
138
|
-
return true;
|
|
125
|
+
const [agentDir, ...parts] = dir.split(path.sep);
|
|
126
|
+
let current = path.join(cwd, agentDir);
|
|
127
|
+
fs.mkdirSync(current, { recursive: true });
|
|
128
|
+
for (const part of parts) {
|
|
129
|
+
current = path.join(current, part);
|
|
130
|
+
const stat = lstat(current);
|
|
131
|
+
if (!stat) fs.mkdirSync(current);
|
|
132
|
+
else if (!stat.isDirectory()) return false;
|
|
133
|
+
}
|
|
134
|
+
return true;
|
|
139
135
|
}
|
|
140
136
|
/**
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
137
|
+
* Point `link` (relative to cwd) at `target`, unless the spot is the user's: a real file there, or a linked
|
|
138
|
+
* directory on the way. Returns whether the link is in place.
|
|
139
|
+
*/
|
|
144
140
|
function placeLink(cwd, link, target) {
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
if (stat)
|
|
161
|
-
fs.unlinkSync(linkPath);
|
|
162
|
-
fs.symlinkSync(text, linkPath);
|
|
163
|
-
return true;
|
|
141
|
+
const linkPath = path.join(cwd, link);
|
|
142
|
+
if (!ensureRealDir(cwd, path.dirname(link))) {
|
|
143
|
+
console.log(`Skipped ${link}: ${path.dirname(link)} is not a real directory`);
|
|
144
|
+
return false;
|
|
145
|
+
}
|
|
146
|
+
const stat = lstat(linkPath);
|
|
147
|
+
if (stat && !stat.isSymbolicLink()) {
|
|
148
|
+
console.log(`Kept ${link}: not a symlink`);
|
|
149
|
+
return false;
|
|
150
|
+
}
|
|
151
|
+
const text = path.relative(fs.realpathSync(path.dirname(linkPath)), target);
|
|
152
|
+
if (stat && fs.readlinkSync(linkPath) === text) return true;
|
|
153
|
+
if (stat) fs.unlinkSync(linkPath);
|
|
154
|
+
fs.symlinkSync(text, linkPath);
|
|
155
|
+
return true;
|
|
164
156
|
}
|
|
165
157
|
/**
|
|
166
|
-
|
|
167
|
-
|
|
158
|
+
* Links listed in a `.gitignore` this tool generated - it doubles as the record of what to clean up next time.
|
|
159
|
+
*/
|
|
168
160
|
function readManifest(gitignore) {
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
return content
|
|
173
|
-
.split('\n')
|
|
174
|
-
.filter((line) => line.startsWith('/') && line !== `/${GITIGNORE}`)
|
|
175
|
-
.map((line) => path.normalize(line.slice(1)));
|
|
161
|
+
const content = fs.existsSync(gitignore) ? fs.readFileSync(gitignore, "utf-8") : "";
|
|
162
|
+
if (!content.startsWith(GITIGNORE_HEADER)) return [];
|
|
163
|
+
return content.split("\n").filter((line) => line.startsWith("/") && line !== `/${GITIGNORE}`).map((line) => path.normalize(line.slice(1)));
|
|
176
164
|
}
|
|
177
165
|
/**
|
|
178
|
-
|
|
179
|
-
|
|
166
|
+
* Write the `.gitignore` listing `links` (remove it when there are none), unless the user owns that file.
|
|
167
|
+
*/
|
|
180
168
|
function writeManifest(gitignore, links) {
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
169
|
+
const exists = fs.existsSync(gitignore);
|
|
170
|
+
if (exists && !fs.readFileSync(gitignore, "utf-8").startsWith(GITIGNORE_HEADER)) return;
|
|
171
|
+
if (!links.length) {
|
|
172
|
+
if (exists) fs.unlinkSync(gitignore);
|
|
173
|
+
return;
|
|
174
|
+
}
|
|
175
|
+
const entries = links.map((link) => `/${link.split(path.sep).join("/")}`).sort();
|
|
176
|
+
fs.writeFileSync(gitignore, [
|
|
177
|
+
GITIGNORE_HEADER,
|
|
178
|
+
`/${GITIGNORE}`,
|
|
179
|
+
...entries,
|
|
180
|
+
""
|
|
181
|
+
].join("\n"));
|
|
191
182
|
}
|
|
192
183
|
/**
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
184
|
+
* Links to place, keyed by their path relative to cwd: package files into every agent dir, the user's own `.agents`
|
|
185
|
+
* files into the mirrors. A user file wins over the package file at the same path.
|
|
186
|
+
*/
|
|
196
187
|
function plannedLinks(cwd, packageFiles, userFiles) {
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
for (const dir of MIRROR_AGENT_DIRS)
|
|
209
|
-
links.set(path.join(dir, file), path.join(canonicalDir, file));
|
|
210
|
-
}
|
|
211
|
-
return links;
|
|
188
|
+
const canonicalDir = path.join(fs.realpathSync(cwd), CANONICAL_AGENT_DIR);
|
|
189
|
+
const links = /* @__PURE__ */ new Map();
|
|
190
|
+
for (const [file, source] of packageFiles) {
|
|
191
|
+
if (userFiles.has(file)) {
|
|
192
|
+
console.log(`${path.join(CANONICAL_AGENT_DIR, file)} overrides the package file`);
|
|
193
|
+
continue;
|
|
194
|
+
}
|
|
195
|
+
for (const dir of AGENT_DIRS) links.set(path.join(dir, file), fs.realpathSync(source));
|
|
196
|
+
}
|
|
197
|
+
for (const file of userFiles.keys()) for (const dir of MIRROR_AGENT_DIRS) links.set(path.join(dir, file), path.join(canonicalDir, file));
|
|
198
|
+
return links;
|
|
212
199
|
}
|
|
213
200
|
/**
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
rules.push(toRule(file, fs.readFileSync(filePath, 'utf-8')));
|
|
229
|
-
}
|
|
230
|
-
return rules;
|
|
201
|
+
* Read all markdown files from the package rules directory.
|
|
202
|
+
*/
|
|
203
|
+
function readRules() {
|
|
204
|
+
const rules = [];
|
|
205
|
+
if (!fs.existsSync(RULES_DIR)) {
|
|
206
|
+
console.error(`Rules directory not found: ${RULES_DIR}`);
|
|
207
|
+
process.exit(1);
|
|
208
|
+
}
|
|
209
|
+
const files = fs.readdirSync(RULES_DIR).filter((f) => f.endsWith(".md")).sort();
|
|
210
|
+
for (const file of files) {
|
|
211
|
+
const filePath = path.join(RULES_DIR, file);
|
|
212
|
+
rules.push(toRule(file, fs.readFileSync(filePath, "utf-8")));
|
|
213
|
+
}
|
|
214
|
+
return rules;
|
|
231
215
|
}
|
|
232
216
|
/**
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
return fs
|
|
240
|
-
.readdirSync(SKILLS_DIR, { withFileTypes: true })
|
|
241
|
-
.filter((entry) => entry.isDirectory() && fs.existsSync(path.join(SKILLS_DIR, entry.name, 'SKILL.md')))
|
|
242
|
-
.map((entry) => ({ name: entry.name }))
|
|
243
|
-
.sort((a, b) => a.name.localeCompare(b.name));
|
|
217
|
+
* Read the package skills directory: every directory holding a `SKILL.md` is a skill named after the directory,
|
|
218
|
+
* shipped with all its files (scripts, references, ...).
|
|
219
|
+
*/
|
|
220
|
+
function readSkills() {
|
|
221
|
+
if (!fs.existsSync(SKILLS_DIR)) return [];
|
|
222
|
+
return fs.readdirSync(SKILLS_DIR, { withFileTypes: true }).filter((entry) => entry.isDirectory() && fs.existsSync(path.join(SKILLS_DIR, entry.name, "SKILL.md"))).map((entry) => ({ name: entry.name })).sort((a, b) => a.name.localeCompare(b.name));
|
|
244
223
|
}
|
|
245
224
|
/**
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
const files = new Map();
|
|
252
|
-
const hasReadme = fs.existsSync(README_FILE);
|
|
253
|
-
for (const rule of rules) {
|
|
254
|
-
files.set(path.join('rules', rule.file), path.join(RULES_DIR, rule.file));
|
|
255
|
-
}
|
|
256
|
-
for (const skill of skills) {
|
|
257
|
-
const root = path.join(SKILLS_DIR, skill.name);
|
|
258
|
-
const readme = path.join('skills', skill.name, 'README.md');
|
|
259
|
-
for (const file of listRealFiles(root)) {
|
|
260
|
-
files.set(path.join('skills', skill.name, file), path.join(root, file));
|
|
261
|
-
}
|
|
262
|
-
if (hasReadme && !files.has(readme))
|
|
263
|
-
files.set(readme, README_FILE);
|
|
264
|
-
}
|
|
265
|
-
return files;
|
|
225
|
+
* Read the package commands directory: every markdown file is a command named after the file.
|
|
226
|
+
*/
|
|
227
|
+
function readCommands() {
|
|
228
|
+
if (!fs.existsSync(COMMANDS_DIR)) return [];
|
|
229
|
+
return fs.readdirSync(COMMANDS_DIR).filter((f) => f.endsWith(".md")).sort();
|
|
266
230
|
}
|
|
267
231
|
/**
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
232
|
+
* Package files to link, keyed by their path inside an agent dir: `rules/<file>`, `commands/<file>`, and every file
|
|
233
|
+
* of a skill at its own relative path, plus the package README.md next to its `SKILL.md` (unless the skill ships
|
|
234
|
+
* one), so a skill can reference `@README.md`.
|
|
235
|
+
*/
|
|
236
|
+
function packageFiles(rules, skills, commands = []) {
|
|
237
|
+
const files = /* @__PURE__ */ new Map();
|
|
238
|
+
const hasReadme = fs.existsSync(README_FILE);
|
|
239
|
+
for (const rule of rules) files.set(path.join("rules", rule.file), path.join(RULES_DIR, rule.file));
|
|
240
|
+
for (const command of commands) files.set(path.join("commands", command), path.join(COMMANDS_DIR, command));
|
|
241
|
+
for (const skill of skills) {
|
|
242
|
+
const root = path.join(SKILLS_DIR, skill.name);
|
|
243
|
+
const readme = path.join("skills", skill.name, "README.md");
|
|
244
|
+
for (const file of listRealFiles(root)) files.set(path.join("skills", skill.name, file), path.join(root, file));
|
|
245
|
+
if (hasReadme && !files.has(readme)) files.set(readme, README_FILE);
|
|
246
|
+
}
|
|
247
|
+
return files;
|
|
282
248
|
}
|
|
283
249
|
/**
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
* TODO: generate `.claude/CLAUDE.md` with an index of the symlinked rules, for humans browsing `.claude/rules` manually
|
|
296
|
-
* (Claude Code itself doesn't need it - it auto-loads every file under `.claude/rules` regardless of whether it's
|
|
297
|
-
* indexed anywhere).
|
|
298
|
-
*/
|
|
299
|
-
export function syncAgentDirs(cwd, packageFiles, userFiles) {
|
|
300
|
-
const links = plannedLinks(cwd, packageFiles, userFiles);
|
|
301
|
-
for (const dir of AGENT_DIRS) {
|
|
302
|
-
for (const kind of AGENT_KINDS) {
|
|
303
|
-
const root = path.join(dir, kind);
|
|
304
|
-
const rootPath = path.join(cwd, root);
|
|
305
|
-
const gitignore = path.join(rootPath, GITIGNORE);
|
|
306
|
-
if (!ensureRealDir(cwd, root)) {
|
|
307
|
-
console.log(`Skipped ${root}: not a real directory`);
|
|
308
|
-
continue;
|
|
309
|
-
}
|
|
310
|
-
for (const link of findDeadLinks(rootPath)) {
|
|
311
|
-
removeLink(link, rootPath);
|
|
312
|
-
}
|
|
313
|
-
const placed = [];
|
|
314
|
-
for (const [link, target] of links) {
|
|
315
|
-
if (link.startsWith(root + path.sep) && placeLink(cwd, link, target)) {
|
|
316
|
-
placed.push(path.relative(root, link));
|
|
317
|
-
}
|
|
318
|
-
}
|
|
319
|
-
for (const link of readManifest(gitignore)) {
|
|
320
|
-
const linkPath = path.join(rootPath, link);
|
|
321
|
-
if (!placed.includes(link) && lstat(linkPath)?.isSymbolicLink())
|
|
322
|
-
removeLink(linkPath, rootPath);
|
|
323
|
-
}
|
|
324
|
-
writeManifest(gitignore, placed);
|
|
325
|
-
}
|
|
326
|
-
}
|
|
250
|
+
* The user's own files in `.agents` `rules`, `commands` and `skills`, keyed like packageFiles() - everything there
|
|
251
|
+
* except the package links (and dotfiles).
|
|
252
|
+
*/
|
|
253
|
+
function readUserFiles(cwd) {
|
|
254
|
+
const files = /* @__PURE__ */ new Map();
|
|
255
|
+
for (const kind of AGENT_KINDS) {
|
|
256
|
+
const root = path.join(cwd, CANONICAL_AGENT_DIR, kind);
|
|
257
|
+
if (!fs.statSync(root, { throwIfNoEntry: false })?.isDirectory()) continue;
|
|
258
|
+
for (const file of listRealFiles(root)) files.set(path.join(kind, file), path.join(root, file));
|
|
259
|
+
}
|
|
260
|
+
return files;
|
|
327
261
|
}
|
|
328
262
|
/**
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
263
|
+
* Make `rules`, `commands` and `skills` real directories in every agent dir and link the files we know into them:
|
|
264
|
+
* package files into both, pointing straight at the package, and the user's own `.agents` files into `.claude`.
|
|
265
|
+
* Real files and linked directories are the user's - never written over or through. Dead links are
|
|
266
|
+
* removed, and so are links from the previous run that are no longer placed: each directory's generated `.gitignore`
|
|
267
|
+
* records them (and keeps them out of git, so the user's own files there stay tracked).
|
|
268
|
+
*
|
|
269
|
+
* FIXME Codex Includes
|
|
270
|
+
* https://github.com/openai/codex/issues/17401
|
|
271
|
+
* https://github.com/openai/codex/issues/6038
|
|
272
|
+
* 32kb limit https://github.com/openai/codex/issues/13386
|
|
273
|
+
*
|
|
274
|
+
* TODO: generate `.claude/CLAUDE.md` with an index of the symlinked rules, for humans browsing `.claude/rules` manually
|
|
275
|
+
* (Claude Code itself doesn't need it - it auto-loads every file under `.claude/rules` regardless of whether it's
|
|
276
|
+
* indexed anywhere).
|
|
277
|
+
*/
|
|
278
|
+
function syncAgentDirs(cwd, packageFiles, userFiles) {
|
|
279
|
+
const links = plannedLinks(cwd, packageFiles, userFiles);
|
|
280
|
+
for (const dir of AGENT_DIRS) for (const kind of AGENT_KINDS) {
|
|
281
|
+
const root = path.join(dir, kind);
|
|
282
|
+
const rootPath = path.join(cwd, root);
|
|
283
|
+
const gitignore = path.join(rootPath, GITIGNORE);
|
|
284
|
+
if (!ensureRealDir(cwd, root)) {
|
|
285
|
+
console.log(`Skipped ${root}: not a real directory`);
|
|
286
|
+
continue;
|
|
287
|
+
}
|
|
288
|
+
for (const link of findDeadLinks(rootPath)) removeLink(link, rootPath);
|
|
289
|
+
const placed = [];
|
|
290
|
+
for (const [link, target] of links) if (link.startsWith(root + path.sep) && placeLink(cwd, link, target)) placed.push(path.relative(root, link));
|
|
291
|
+
for (const link of readManifest(gitignore)) {
|
|
292
|
+
const linkPath = path.join(rootPath, link);
|
|
293
|
+
if (!placed.includes(link) && lstat(linkPath)?.isSymbolicLink()) removeLink(linkPath, rootPath);
|
|
294
|
+
}
|
|
295
|
+
writeManifest(gitignore, placed);
|
|
296
|
+
}
|
|
341
297
|
}
|
|
342
298
|
/**
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
console.error(`${CLAUDE_FILE} exists and is not a symlink.`);
|
|
355
|
-
console.error('Remove or back it up manually, then re-run.');
|
|
356
|
-
process.exit(1);
|
|
357
|
-
}
|
|
299
|
+
* Rules as they end up in `.agents/rules`: the package ones plus the user's own, which win on the same file.
|
|
300
|
+
*/
|
|
301
|
+
function installedRules(rules, userFiles) {
|
|
302
|
+
const byFile = new Map(rules.map((rule) => [rule.file, rule]));
|
|
303
|
+
const rulesDir = `rules${path.sep}`;
|
|
304
|
+
for (const [file, source] of userFiles) {
|
|
305
|
+
if (!file.startsWith(rulesDir) || !file.endsWith(".md")) continue;
|
|
306
|
+
const ruleFile = file.slice(rulesDir.length).split(path.sep).join("/");
|
|
307
|
+
byFile.set(ruleFile, toRule(ruleFile, fs.readFileSync(source, "utf-8")));
|
|
308
|
+
}
|
|
309
|
+
return [...byFile].sort(([a], [b]) => a < b ? -1 : 1).map(([, rule]) => rule);
|
|
358
310
|
}
|
|
359
311
|
/**
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
312
|
+
* Fail if `CLAUDE.md` exists and isn't a symlink - we don't want to silently blow away a file the user wrote.
|
|
313
|
+
*/
|
|
314
|
+
function checkClaudeMdSafety(claudeMdPath) {
|
|
315
|
+
let stat;
|
|
316
|
+
try {
|
|
317
|
+
stat = fs.lstatSync(claudeMdPath);
|
|
318
|
+
} catch {
|
|
319
|
+
return;
|
|
320
|
+
}
|
|
321
|
+
if (!stat.isSymbolicLink()) {
|
|
322
|
+
console.error(`${CLAUDE_FILE} exists and is not a symlink.`);
|
|
323
|
+
console.error("Remove or back it up manually, then re-run.");
|
|
324
|
+
process.exit(1);
|
|
325
|
+
}
|
|
366
326
|
}
|
|
367
327
|
/**
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
*/
|
|
375
|
-
export function generateAgentsFile(rules, customSection) {
|
|
376
|
-
const entries = rules.map((rule) => {
|
|
377
|
-
// the canonical entry (a package link or the user's own file), not the package install path
|
|
378
|
-
const rulePath = `${CANONICAL_AGENT_DIR}/rules/${rule.file}`;
|
|
379
|
-
const description = rule.description ? ` — ${rule.description}` : '';
|
|
380
|
-
const scope = rule.paths ? `; when touching ${rule.paths.map((glob) => `\`${glob}\``).join(', ')}` : '';
|
|
381
|
-
return `- **${toTitle(rule.name)}**${description}${scope}: [${rulePath}](${rulePath})`;
|
|
382
|
-
});
|
|
383
|
-
const generated = `${HEADER}\n\n# Rules\n\n${entries.join('\n')}\n\n${FOOTER}\n\n${GENERATED_MARKER}`;
|
|
384
|
-
return customSection ? `${generated}\n\n${customSection}\n` : `${generated}\n`;
|
|
328
|
+
* Symlink CLAUDE.md -> AGENTS.md so both point at the same generated content.
|
|
329
|
+
*/
|
|
330
|
+
function symlinkClaudeMd(cwd) {
|
|
331
|
+
const claudeMdPath = path.join(cwd, CLAUDE_FILE);
|
|
332
|
+
fs.rmSync(claudeMdPath, { force: true });
|
|
333
|
+
fs.symlinkSync(AGENTS_FILE, claudeMdPath);
|
|
385
334
|
}
|
|
386
335
|
/**
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
336
|
+
* Generate AGENTS.md with a `# Rules` section: one entry per rule (the package's and the user's own) with
|
|
337
|
+
* its frontmatter `description`, the `paths` it is scoped to and a plain link to its `.agents/rules` entry.
|
|
338
|
+
*
|
|
339
|
+
* The links are plain, never `@path` imports: Claude Code loads `.claude/rules` itself (syncAgentDirs() links them
|
|
340
|
+
* there) and honours each rule's `paths`, while an `@` import would load every rule into every session, scoped or not.
|
|
341
|
+
* Codex, which expands no `@`, reads this index.
|
|
342
|
+
*/
|
|
343
|
+
function generateAgentsFile(rules, customSection) {
|
|
344
|
+
const entries = rules.map((rule) => {
|
|
345
|
+
const rulePath = `${CANONICAL_AGENT_DIR}/rules/${rule.file}`;
|
|
346
|
+
const description = rule.description ? ` — ${rule.description}` : "";
|
|
347
|
+
const scope = rule.paths ? `; when touching ${rule.paths.map((glob) => `\`${glob}\``).join(", ")}` : "";
|
|
348
|
+
return `- **${toTitle(rule.name)}**${description}${scope}: [${rulePath}](${rulePath})`;
|
|
349
|
+
});
|
|
350
|
+
const generated = `${HEADER}\n\n# Rules\n\n${entries.join("\n")}\n\n${FOOTER}\n\n${GENERATED_MARKER}`;
|
|
351
|
+
return customSection ? `${generated}\n\n${customSection}\n` : `${generated}\n`;
|
|
401
352
|
}
|
|
402
353
|
/**
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
}
|
|
423
|
-
}
|
|
424
|
-
if (command === 'update' || command === 'init') {
|
|
425
|
-
checkClaudeMdSafety(claudeMdPath);
|
|
426
|
-
const rules = readRules();
|
|
427
|
-
console.log(`Found ${rules.length} rule files: ${rules.map((r) => r.name).join(', ')}`);
|
|
428
|
-
const skills = readSkills();
|
|
429
|
-
console.log(`Found ${skills.length} skill(s): ${skills.map((s) => s.name).join(', ')}`);
|
|
430
|
-
const userFiles = readUserFiles(cwd);
|
|
431
|
-
syncAgentDirs(cwd, packageFiles(rules, skills), userFiles);
|
|
432
|
-
console.log(`Synced ${AGENT_DIRS.join(', ')}, mirrored ${userFiles.size} own file(s) from ${CANONICAL_AGENT_DIR}`);
|
|
433
|
-
const content = generateAgentsFile(installedRules(rules, userFiles), customSection);
|
|
434
|
-
fs.writeFileSync(targetPath, content, 'utf-8');
|
|
435
|
-
console.log(`${exists ? 'Updated' : 'Created'} ${AGENTS_FILE}`);
|
|
436
|
-
symlinkClaudeMd(cwd);
|
|
437
|
-
console.log(`Symlinked ${CLAUDE_FILE} -> ${AGENTS_FILE}`);
|
|
438
|
-
return;
|
|
439
|
-
}
|
|
440
|
-
console.log(`Unknown command: ${command}`);
|
|
441
|
-
console.log('Usage: lint-prepare [init|update]');
|
|
442
|
-
process.exit(1);
|
|
354
|
+
* Check if AGENTS.md exists and was generated by this tool. When it was, also return
|
|
355
|
+
* whatever follows the marker (the user's custom section) so it can be carried forward -
|
|
356
|
+
* generateAgentsFile() always rebuilds the part above the marker from scratch, but must
|
|
357
|
+
* never touch what a user wrote below it.
|
|
358
|
+
*/
|
|
359
|
+
function checkExisting(targetPath) {
|
|
360
|
+
if (!fs.existsSync(targetPath)) return {
|
|
361
|
+
exists: false,
|
|
362
|
+
generated: false,
|
|
363
|
+
customSection: null
|
|
364
|
+
};
|
|
365
|
+
const content = fs.readFileSync(targetPath, "utf-8");
|
|
366
|
+
const markerIndex = content.indexOf(GENERATED_MARKER);
|
|
367
|
+
const generated = markerIndex !== -1;
|
|
368
|
+
return {
|
|
369
|
+
exists: true,
|
|
370
|
+
generated,
|
|
371
|
+
customSection: generated ? content.slice(markerIndex + 39).trim() : null
|
|
372
|
+
};
|
|
443
373
|
}
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
374
|
+
/**
|
|
375
|
+
* Main function
|
|
376
|
+
*/
|
|
377
|
+
function main() {
|
|
378
|
+
const command = process.argv.slice(2)[0] || "init";
|
|
379
|
+
const cwd = process.env.INIT_CWD || process.cwd();
|
|
380
|
+
const targetPath = path.join(cwd, AGENTS_FILE);
|
|
381
|
+
const claudeMdPath = path.join(cwd, CLAUDE_FILE);
|
|
382
|
+
console.log(`@kirill.konshin/lint: ${command}`);
|
|
383
|
+
console.log(`Target: ${targetPath}`);
|
|
384
|
+
const { exists, generated, customSection } = checkExisting(targetPath);
|
|
385
|
+
if (command === "init") {
|
|
386
|
+
if (exists && !generated) {
|
|
387
|
+
console.log(`${AGENTS_FILE} exists and was not generated by this tool. Skipping.`);
|
|
388
|
+
console.log("Use \"lint-prepare update\" to force overwrite, then merge manually.");
|
|
389
|
+
return;
|
|
390
|
+
}
|
|
391
|
+
if (exists && generated) console.log(`${AGENTS_FILE} exists and was generated by this tool. Updating...`);
|
|
392
|
+
}
|
|
393
|
+
if (command === "update" || command === "init") {
|
|
394
|
+
checkClaudeMdSafety(claudeMdPath);
|
|
395
|
+
const rules = readRules();
|
|
396
|
+
console.log(`Found ${rules.length} rule files: ${rules.map((r) => r.name).join(", ")}`);
|
|
397
|
+
const skills = readSkills();
|
|
398
|
+
console.log(`Found ${skills.length} skill(s): ${skills.map((s) => s.name).join(", ")}`);
|
|
399
|
+
const commands = readCommands();
|
|
400
|
+
console.log(`Found ${commands.length} command(s): ${commands.map((c) => c.replace(/\.md$/, "")).join(", ")}`);
|
|
401
|
+
const userFiles = readUserFiles(cwd);
|
|
402
|
+
syncAgentDirs(cwd, packageFiles(rules, skills, commands), userFiles);
|
|
403
|
+
console.log(`Synced ${AGENT_DIRS.join(", ")}, mirrored ${userFiles.size} own file(s) from ${CANONICAL_AGENT_DIR}`);
|
|
404
|
+
const content = generateAgentsFile(installedRules(rules, userFiles), customSection);
|
|
405
|
+
fs.writeFileSync(targetPath, content, "utf-8");
|
|
406
|
+
console.log(`${exists ? "Updated" : "Created"} ${AGENTS_FILE}`);
|
|
407
|
+
symlinkClaudeMd(cwd);
|
|
408
|
+
console.log(`Symlinked ${CLAUDE_FILE} -> ${AGENTS_FILE}`);
|
|
409
|
+
return;
|
|
410
|
+
}
|
|
411
|
+
console.log(`Unknown command: ${command}`);
|
|
412
|
+
console.log("Usage: lint-prepare [init|update]");
|
|
413
|
+
process.exit(1);
|
|
447
414
|
}
|
|
415
|
+
if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(__filename)) main();
|
|
416
|
+
//#endregion
|
|
417
|
+
export { checkClaudeMdSafety, checkExisting, generateAgentsFile, installedRules, main, packageFiles, readCommands, readRules, readSkills, readUserFiles, symlinkClaudeMd, syncAgentDirs };
|