@kirill.konshin/lint 0.5.5 → 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 (111) hide show
  1. package/README.md +38 -3
  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 -146
  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 -42
  30. package/dist/index.js +53 -85
  31. package/dist/lib.d.ts +21 -21
  32. package/dist/lib.js +261 -301
  33. package/dist/lintPrepare.d.ts +20 -17
  34. package/dist/lintPrepare.js +341 -371
  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 +11 -10
  40. package/dist/restrictions.js +18 -22
  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 +2 -0
  45. package/rules/openspec.md +1 -1
  46. package/skills/spec-steward/SKILL.md +3 -11
  47. package/skills/spec-steward/references/audit.md +18 -43
  48. package/skills/spec-steward/references/contract.md +4 -4
  49. package/skills/spec-steward/references/criteria.md +4 -4
  50. package/skills/spec-steward/references/review-format.md +6 -6
  51. package/skills/spec-steward/references/wiring.md +2 -2
  52. package/skills/spec-steward/references/worker.md +67 -0
  53. package/skills/spec-steward/scripts/lib/corpus.mjs +1 -1
  54. package/skills/spec-steward/scripts/lib/evidence.mjs +2 -147
  55. package/skills/spec-steward/scripts/lib/wire.mjs +6 -4
  56. package/skills/spec-steward/scripts/steward.mjs +30 -91
  57. package/skills/spec-steward/sweeps.json +49 -0
  58. package/skills/spec-tools/SKILL.md +46 -0
  59. package/skills/spec-tools/references/contract.md +111 -0
  60. package/skills/spec-tools/references/gitlab.md +122 -0
  61. package/skills/spec-verify/SKILL.md +153 -0
  62. package/spec-tools/dist/audit-DkZZulq6.mjs +130 -0
  63. package/spec-tools/dist/auditChanged-CNGjlake.mjs +1 -0
  64. package/spec-tools/dist/auditChanged-CZCvMgyZ.mjs +618 -0
  65. package/spec-tools/dist/auditReport-xgq4wK2i.mjs +458 -0
  66. package/spec-tools/dist/auditScope-CBuBtfPG.mjs +104 -0
  67. package/spec-tools/dist/changeGates-DdeQKfle.mjs +333 -0
  68. package/spec-tools/dist/changeGates-uy4Ti8rK.mjs +1 -0
  69. package/spec-tools/dist/ci-BUewHJS3.mjs +143 -0
  70. package/spec-tools/dist/ci-CFBzn8Of.mjs +1 -0
  71. package/spec-tools/dist/cli.mjs +93 -0
  72. package/spec-tools/dist/comment-szasMMg2.mjs +57 -0
  73. package/spec-tools/dist/files-Bppsb34B.mjs +1 -0
  74. package/spec-tools/dist/files-QlzY687_.mjs +38 -0
  75. package/spec-tools/dist/html-BMTkpbUN.mjs +1766 -0
  76. package/spec-tools/dist/jsonrepair-Dlm5dEen.mjs +742 -0
  77. package/spec-tools/dist/repo-CjIoUPYl.mjs +16 -0
  78. package/spec-tools/dist/repo-DUcnJw3c.mjs +1 -0
  79. package/spec-tools/dist/run-BElA9du3.mjs +67 -0
  80. package/spec-tools/dist/specDiff-8G56jMYn.mjs +123 -0
  81. package/spec-tools/dist/steward-DeieyOcj.mjs +34 -0
  82. package/spec-tools/dist/stewardAudit-BRMM0lrD.mjs +1 -0
  83. package/spec-tools/dist/stewardAudit-v0vOMfLN.mjs +271 -0
  84. package/spec-tools/dist/tier-Cn0P7juM.mjs +1 -0
  85. package/spec-tools/dist/tier-c3s_mA_I.mjs +65 -0
  86. package/spec-tools/dist/util-wnxhsnWO.mjs +49 -0
  87. package/spec-tools/dist/verdict-BFfN9PO8.mjs +58 -0
  88. package/spec-tools/dist/workers-BcIgckeq.mjs +417 -0
  89. package/spec-tools/dist/workflowEvidence-DyBj8EdG.mjs +1 -0
  90. package/spec-tools/dist/workflowEvidence-oui6ghPI.mjs +78 -0
  91. package/dist/configs/base.d.ts.map +0 -1
  92. package/dist/configs/imports.d.ts.map +0 -1
  93. package/dist/configs/nx.d.ts.map +0 -1
  94. package/dist/configs/prettier.d.ts.map +0 -1
  95. package/dist/configs/promise.d.ts.map +0 -1
  96. package/dist/configs/react.d.ts.map +0 -1
  97. package/dist/configs/storybook.d.ts.map +0 -1
  98. package/dist/configs/tailwind.d.ts.map +0 -1
  99. package/dist/configs/testing.d.ts.map +0 -1
  100. package/dist/configs/turbo.d.ts.map +0 -1
  101. package/dist/configs/typescriptTypeAware.d.ts.map +0 -1
  102. package/dist/configs/unicorn.d.ts.map +0 -1
  103. package/dist/exts.d.ts.map +0 -1
  104. package/dist/index.d.ts.map +0 -1
  105. package/dist/lib.d.ts.map +0 -1
  106. package/dist/lintPrepare.d.ts.map +0 -1
  107. package/dist/lintStaged.d.ts.map +0 -1
  108. package/dist/prettier.d.ts.map +0 -1
  109. package/dist/restrictions.d.ts.map +0 -1
  110. package/dist/yarn.d.cts.map +0 -1
  111. package/skills/spec-steward/workflows/audit.js +0 -539
@@ -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
- * @kirill.konshin/lint
4
- *
5
- * This script makes `rules`, `commands` and `skills` real directories in the consuming project's
6
- * `.agents` (canonical, cross-tool) and `.claude` (Claude Code), 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 both, pointing
9
- * straight at the installed package; the user's own files in `.agents` are mirrored into `.claude`. It also
10
- * generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
11
- *
12
- * Usage:
13
- * lint-prepare init - Initialize AGENTS.md in the current directory (default)
14
- * lint-prepare update - Force update AGENTS.md even if it exists
15
- * lint-prepare - Same as init
16
- *
17
- * The module also exports its functions and only runs `main()` when executed directly,
18
- * so it can be imported (for testing/reuse) without side effects.
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 = 'AGENTS.md';
27
- const CLAUDE_FILE = 'CLAUDE.md';
28
- const RULES_DIR = path.join(__dirname, '../rules');
29
- const SKILLS_DIR = path.join(__dirname, '../skills');
30
- const README_FILE = path.join(__dirname, '../README.md');
31
- // `.agents` is the cross-tool location (Codex, Cursor, Antigravity) holding the package links and the user's own
32
- // files, the latter are mirrored into `.claude` (Claude Code reads nothing else)
33
- const CANONICAL_AGENT_DIR = '.agents';
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 = ['rules', 'commands', 'skills'];
37
- const GITIGNORE = '.gitignore';
38
- 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";
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 = '<!-- @kirill.konshin/lint:generated -->';
54
+ const GENERATED_MARKER = "<!-- @kirill.konshin/lint:generated -->";
51
55
  const lstat = (file) => fs.lstatSync(file, { throwIfNoEntry: false });
52
56
  /**
53
- * `monorepo-turbo-nx` -> `Monorepo turbo nx`
54
- */
57
+ * `monorepo-turbo-nx` -> `Monorepo turbo nx`
58
+ */
55
59
  const toTitle = (name) => {
56
- const title = name.replaceAll('-', ' ');
57
- return title.charAt(0).toUpperCase() + title.slice(1);
60
+ const title = name.replaceAll("-", " ");
61
+ return title.charAt(0).toUpperCase() + title.slice(1);
58
62
  };
59
63
  /**
60
- * A rule's YAML frontmatter, empty when it has none.
61
- */
64
+ * A rule's YAML frontmatter, empty when it has none.
65
+ */
62
66
  const readFrontmatter = (content) => {
63
- const frontmatter = FRONTMATTER.exec(content)?.[1];
64
- const parsed = frontmatter ? parse(frontmatter) : undefined;
65
- return parsed && typeof parsed === 'object' ? parsed : {};
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
- * A frontmatter field read as a list of strings: one string, or a list of them.
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
- const items = typeof value === 'string' ? [value] : Array.isArray(value) ? value : [];
72
- const strings = items.filter((item) => typeof item === 'string' && item.trim() !== '');
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
- * `file` is the path inside a rules dir, e.g. `auth.md` or `frontend/react.md`.
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
- const { description, paths } = readFrontmatter(content);
80
- return {
81
- file,
82
- name: path.posix.basename(file, '.md'),
83
- description: typeof description === 'string' ? description.trim() : undefined,
84
- paths: stringList(paths),
85
- content,
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
- * Real files under `dir`, as paths relative to `root` - symlinks (incl. the package links next to them), linked
90
- * directories and dotfiles (`.gitignore`, `.DS_Store`) are skipped.
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
- return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
94
- const entryPath = path.join(dir, entry.name);
95
- if (entry.name.startsWith('.'))
96
- return [];
97
- if (entry.isDirectory())
98
- return listRealFiles(root, entryPath);
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
- * Dead symlinks under `dir`, walking real directories only.
104
- */
104
+ * Dead symlinks under `dir`, walking real directories only.
105
+ */
105
106
  function findDeadLinks(dir) {
106
- return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
107
- const entryPath = path.join(dir, entry.name);
108
- if (entry.isDirectory())
109
- return findDeadLinks(entryPath);
110
- return entry.isSymbolicLink() && !fs.existsSync(entryPath) ? [entryPath] : [];
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
- * Remove `link` and the directories it leaves empty, up to `root`.
115
- */
114
+ * Remove `link` and the directories it leaves empty, up to `root`.
115
+ */
116
116
  function removeLink(link, root) {
117
- fs.unlinkSync(link);
118
- for (let dir = path.dirname(link); dir !== root && !fs.readdirSync(dir).length; dir = path.dirname(dir)) {
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
- * mkdir -p `dir` (relative to cwd, starting with an agent dir, which itself may be a link) without going through
124
- * links below it: false when a part is a symlink or a file - those are the user's, nothing is written through them.
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
- const [agentDir, ...parts] = dir.split(path.sep);
128
- let current = path.join(cwd, agentDir);
129
- fs.mkdirSync(current, { recursive: true });
130
- for (const part of parts) {
131
- current = path.join(current, part);
132
- const stat = lstat(current);
133
- if (!stat)
134
- fs.mkdirSync(current);
135
- else if (!stat.isDirectory())
136
- return false;
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
- * Point `link` (relative to cwd) at `target`, unless the spot is the user's: a real file there, or a linked
142
- * directory on the way. Returns whether the link is in place.
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
- const linkPath = path.join(cwd, link);
146
- if (!ensureRealDir(cwd, path.dirname(link))) {
147
- console.log(`Skipped ${link}: ${path.dirname(link)} is not a real directory`);
148
- return false;
149
- }
150
- const stat = lstat(linkPath);
151
- if (stat && !stat.isSymbolicLink()) {
152
- console.log(`Kept ${link}: not a symlink`);
153
- return false;
154
- }
155
- // relative between REAL locations: cwd and the package (workspaces, yalc, pnpm store) may be reached through
156
- // symlinks, and a path computed between a symlinked and a real location dangles
157
- const text = path.relative(fs.realpathSync(path.dirname(linkPath)), target);
158
- if (stat && fs.readlinkSync(linkPath) === text)
159
- return true;
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
- * Links listed in a `.gitignore` this tool generated - it doubles as the record of what to clean up next time.
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
- const content = fs.existsSync(gitignore) ? fs.readFileSync(gitignore, 'utf-8') : '';
170
- if (!content.startsWith(GITIGNORE_HEADER))
171
- return [];
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
- * Write the `.gitignore` listing `links` (remove it when there are none), unless the user owns that file.
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
- const exists = fs.existsSync(gitignore);
182
- if (exists && !fs.readFileSync(gitignore, 'utf-8').startsWith(GITIGNORE_HEADER))
183
- return;
184
- if (!links.length) {
185
- if (exists)
186
- fs.unlinkSync(gitignore);
187
- return;
188
- }
189
- const entries = links.map((link) => `/${link.split(path.sep).join('/')}`).sort();
190
- 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"));
191
182
  }
192
183
  /**
193
- * Links to place, keyed by their path relative to cwd: package files into every agent dir, the user's own `.agents`
194
- * files into the mirrors. A user file wins over the package file at the same path.
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
- const canonicalDir = path.join(fs.realpathSync(cwd), CANONICAL_AGENT_DIR);
198
- const links = new Map();
199
- for (const [file, source] of packageFiles) {
200
- if (userFiles.has(file)) {
201
- console.log(`${path.join(CANONICAL_AGENT_DIR, file)} overrides the package file`);
202
- continue;
203
- }
204
- for (const dir of AGENT_DIRS)
205
- links.set(path.join(dir, file), fs.realpathSync(source));
206
- }
207
- for (const file of userFiles.keys()) {
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
- * Read all markdown files from the package rules directory.
215
- */
216
- export function readRules() {
217
- const rules = [];
218
- if (!fs.existsSync(RULES_DIR)) {
219
- console.error(`Rules directory not found: ${RULES_DIR}`);
220
- process.exit(1);
221
- }
222
- const files = fs
223
- .readdirSync(RULES_DIR)
224
- .filter((f) => f.endsWith('.md'))
225
- .sort();
226
- for (const file of files) {
227
- const filePath = path.join(RULES_DIR, file);
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
- * Read the package skills directory: every directory holding a `SKILL.md` is a skill named after the directory,
234
- * shipped with all its files (scripts, references, ...).
235
- */
236
- export function readSkills() {
237
- if (!fs.existsSync(SKILLS_DIR))
238
- return [];
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
- * Package files to link, keyed by their path inside an agent dir: `rules/<file>`, and every file of a skill at its
247
- * own relative path, plus the package README.md next to its `SKILL.md` (unless the skill ships one), so a skill can
248
- * reference `@README.md`.
249
- */
250
- export function packageFiles(rules, skills) {
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
- * The user's own files in `.agents` `rules`, `commands` and `skills`, keyed like packageFiles() - everything there
269
- * except the package links (and dotfiles).
270
- */
271
- export function readUserFiles(cwd) {
272
- const files = new Map();
273
- for (const kind of AGENT_KINDS) {
274
- const root = path.join(cwd, CANONICAL_AGENT_DIR, kind);
275
- if (!fs.statSync(root, { throwIfNoEntry: false })?.isDirectory())
276
- continue;
277
- for (const file of listRealFiles(root)) {
278
- files.set(path.join(kind, file), path.join(root, file));
279
- }
280
- }
281
- 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;
282
248
  }
283
249
  /**
284
- * Make `rules`, `commands` and `skills` real directories in every agent dir and link the files we know into them:
285
- * package files into both, pointing straight at the package, and the user's own `.agents` files into `.claude`.
286
- * Real files and linked directories are the user's - never written over or through. Dead links are
287
- * removed, and so are links from the previous run that are no longer placed: each directory's generated `.gitignore`
288
- * records them (and keeps them out of git, so the user's own files there stay tracked).
289
- *
290
- * FIXME Codex Includes
291
- * https://github.com/openai/codex/issues/17401
292
- * https://github.com/openai/codex/issues/6038
293
- * 32kb limit https://github.com/openai/codex/issues/13386
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
- * Rules as they end up in `.agents/rules`: the package ones plus the user's own, which win on the same file.
330
- */
331
- export function installedRules(rules, userFiles) {
332
- const byFile = new Map(rules.map((rule) => [rule.file, rule]));
333
- const rulesDir = `rules${path.sep}`;
334
- for (const [file, source] of userFiles) {
335
- if (!file.startsWith(rulesDir) || !file.endsWith('.md'))
336
- continue;
337
- const ruleFile = file.slice(rulesDir.length).split(path.sep).join('/');
338
- byFile.set(ruleFile, toRule(ruleFile, fs.readFileSync(source, 'utf-8')));
339
- }
340
- 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
+ }
341
297
  }
342
298
  /**
343
- * Fail if `CLAUDE.md` exists and isn't a symlink - we don't want to silently blow away a file the user wrote.
344
- */
345
- export function checkClaudeMdSafety(claudeMdPath) {
346
- let stat;
347
- try {
348
- stat = fs.lstatSync(claudeMdPath);
349
- }
350
- catch {
351
- return;
352
- }
353
- if (!stat.isSymbolicLink()) {
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
- * Symlink CLAUDE.md -> AGENTS.md so both point at the same generated content.
361
- */
362
- export function symlinkClaudeMd(cwd) {
363
- const claudeMdPath = path.join(cwd, CLAUDE_FILE);
364
- fs.rmSync(claudeMdPath, { force: true });
365
- 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
+ }
366
326
  }
367
327
  /**
368
- * Generate AGENTS.md with a `# Rules` section: one entry per rule (the package's and the user's own) with
369
- * its frontmatter `description`, the `paths` it is scoped to and a plain link to its `.agents/rules` entry.
370
- *
371
- * The links are plain, never `@path` imports: Claude Code loads `.claude/rules` itself (syncAgentDirs() links them
372
- * there) and honours each rule's `paths`, while an `@` import would load every rule into every session, scoped or not.
373
- * Codex, which expands no `@`, reads this index.
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
- * Check if AGENTS.md exists and was generated by this tool. When it was, also return
388
- * whatever follows the marker (the user's custom section) so it can be carried forward -
389
- * generateAgentsFile() always rebuilds the part above the marker from scratch, but must
390
- * never touch what a user wrote below it.
391
- */
392
- export function checkExisting(targetPath) {
393
- if (!fs.existsSync(targetPath)) {
394
- return { exists: false, generated: false, customSection: null };
395
- }
396
- const content = fs.readFileSync(targetPath, 'utf-8');
397
- const markerIndex = content.indexOf(GENERATED_MARKER);
398
- const generated = markerIndex !== -1;
399
- const customSection = generated ? content.slice(markerIndex + GENERATED_MARKER.length).trim() : null;
400
- 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`;
401
352
  }
402
353
  /**
403
- * Main function
404
- */
405
- export function main() {
406
- const args = process.argv.slice(2);
407
- const command = args[0] || 'init';
408
- const cwd = process.env.INIT_CWD || process.cwd();
409
- const targetPath = path.join(cwd, AGENTS_FILE);
410
- const claudeMdPath = path.join(cwd, CLAUDE_FILE);
411
- console.log(`@kirill.konshin/lint: ${command}`);
412
- console.log(`Target: ${targetPath}`);
413
- const { exists, generated, customSection } = checkExisting(targetPath);
414
- if (command === 'init') {
415
- if (exists && !generated) {
416
- console.log(`${AGENTS_FILE} exists and was not generated by this tool. Skipping.`);
417
- console.log('Use "lint-prepare update" to force overwrite, then merge manually.');
418
- return;
419
- }
420
- if (exists && generated) {
421
- console.log(`${AGENTS_FILE} exists and was generated by this tool. Updating...`);
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
- // Only run when executed directly (e.g. `lint-prepare init`), not when imported.
445
- if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(__filename)) {
446
- 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);
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 };