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