@kirill.konshin/lint 0.7.3 → 0.8.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 (74) hide show
  1. package/README.md +160 -113
  2. package/dist/config.d.ts +103 -0
  3. package/dist/config.js +112 -0
  4. package/dist/configs/base.d.ts +1 -1
  5. package/dist/configs/nx.d.ts +1 -1
  6. package/dist/configs/nx.js +3 -8
  7. package/dist/configs/react.d.ts +3 -3
  8. package/dist/configs/react.js +6 -16
  9. package/dist/configs/storybook.d.ts +3 -3
  10. package/dist/configs/storybook.js +4 -9
  11. package/dist/configs/tailwind.d.ts +6 -25
  12. package/dist/configs/tailwind.js +3 -64
  13. package/dist/configs/testing.d.ts +1 -1
  14. package/dist/configs/testing.js +3 -15
  15. package/dist/configs/turbo.d.ts +2 -2
  16. package/dist/configs/turbo.js +4 -6
  17. package/dist/configs/typescriptTypeAware.d.ts +1 -1
  18. package/dist/gates.d.ts +72 -0
  19. package/dist/gates.js +132 -0
  20. package/dist/index.d.ts +15 -51
  21. package/dist/index.js +16 -14
  22. package/dist/lib.d.ts +1 -1
  23. package/dist/lib.js +1 -1
  24. package/dist/lintPrepare.d.ts +75 -28
  25. package/dist/lintPrepare.js +243 -35
  26. package/dist/testColocation.js +1 -1
  27. package/dist/vitePlus.d.ts +8 -18
  28. package/dist/vitePlus.js +40 -47
  29. package/package.json +7 -4
  30. package/rules/agent.md +1 -0
  31. package/rules/auth.md +3 -3
  32. package/rules/db.md +6 -9
  33. package/rules/expo.md +2 -0
  34. package/rules/github.md +1 -1
  35. package/rules/gitlab.md +1 -1
  36. package/rules/i18n.md +3 -0
  37. package/rules/monorepo-turbo-nx.md +38 -4
  38. package/rules/mui.md +8 -18
  39. package/rules/nextjs.md +13 -13
  40. package/rules/npm-yarn.md +28 -118
  41. package/rules/nx.md +1 -1
  42. package/rules/playwright.md +1 -1
  43. package/rules/react.md +7 -32
  44. package/rules/tailwind.md +9 -47
  45. package/rules/testing.md +2 -2
  46. package/rules/turbo.md +1 -1
  47. package/rules/typescript.md +6 -2
  48. package/rules/ui-kit.md +6 -0
  49. package/rules/vite.md +1 -1
  50. package/skills/lint-db/SKILL.md +23 -0
  51. package/skills/lint-electron/SKILL.md +9 -6
  52. package/skills/lint-github/SKILL.md +15 -8
  53. package/skills/lint-gitlab/SKILL.md +20 -5
  54. package/skills/lint-migrate/SKILL.md +18 -2
  55. package/skills/lint-mui/SKILL.md +28 -0
  56. package/skills/lint-nextjs/SKILL.md +53 -16
  57. package/skills/lint-npm-yarn/SKILL.md +126 -0
  58. package/skills/lint-repo/SKILL.md +12 -12
  59. package/skills/lint-tailwind/SKILL.md +53 -0
  60. package/skills/lint-webstorm/SKILL.md +3 -3
  61. package/skills/lint-worktree/SKILL.md +25 -9
  62. package/skills/spec-author/SKILL.md +2 -2
  63. package/skills/spec-steward/SKILL.md +1 -1
  64. package/skills/spec-steward/references/apply.md +1 -1
  65. package/skills/spec-steward/references/contract.md +2 -2
  66. package/skills/spec-steward/references/model.md +2 -2
  67. package/skills/spec-steward/references/review-format.md +4 -4
  68. package/skills/spec-steward/references/wiring.md +2 -2
  69. package/skills/spec-steward/references/worker.md +1 -1
  70. package/skills/spec-tools/SKILL.md +2 -2
  71. package/skills/spec-tools/references/rules/common.md +1 -1
  72. package/skills/spec-tools/references/rules/spec-steward.md +1 -1
  73. package/skills/spec-tools/scripts/cli.js +2 -2
  74. package/skills/spec-verify/SKILL.md +1 -1
@@ -1,7 +1,11 @@
1
1
  #!/usr/bin/env node
2
+ import { asOptions, findWorkspaceRoot } from "./lib.js";
3
+ import { LINT_CONFIG_FILE, resolveLintConfig } from "./config.js";
4
+ import { createRequire } from "node:module";
5
+ import fs from "node:fs";
2
6
  import path from "node:path";
3
7
  import { fileURLToPath } from "node:url";
4
- import fs from "node:fs";
8
+ import { spawnSync } from "node:child_process";
5
9
  import { parse } from "yaml";
6
10
  //#region src/lintPrepare.ts
7
11
  /**
@@ -9,8 +13,10 @@ import { parse } from "yaml";
9
13
  *
10
14
  * This script makes `rules` and `skills` real directories in the consuming project's `.agents`
11
15
  * (canonical, cross-tool, Codex reads it) and `.claude` (Claude Code), and symlinks the top-level
12
- * entries it knows into them: package rule files and skill folders go into both, pointing straight at
13
- * the installed package; the user's own `.agents` entries are mirrored into `.claude`. It also
16
+ * entries it knows into them: package rule files go into both, pointing straight at the installed
17
+ * package; the user's own `.agents` entries are mirrored into `.claude`. Skills are installed by the `skills` CLI,
18
+ * which this script runs: the skills dependencies ship (`skills experimental_sync`) and the git sources the `skills`
19
+ * map of `lint.config.ts` lists (`skills add`). The `rules` map of `lint.config.ts` leaves package rules out. It also
14
20
  * generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
15
21
  *
16
22
  * Usage:
@@ -34,6 +40,18 @@ const AGENT_KINDS = ["rules", "skills"];
34
40
  const LEGACY_DIRS = AGENT_DIRS.map((dir) => path.join(dir, "commands"));
35
41
  const GITIGNORE = ".gitignore";
36
42
  const GITIGNORE_HEADER = "# Generated by @kirill.konshin/lint: symlinks it manages here, your own files stay tracked";
43
+ const GITIGNORE_SYNCED = "# Installed by the skills CLI (skills-lock.json)";
44
+ const SKILLS_LOCK = "skills-lock.json";
45
+ const SKILLS_AGENTS = [
46
+ "-a",
47
+ "codex",
48
+ "claude-code"
49
+ ];
50
+ const SKILLS_SYNC_ARGS = [
51
+ "experimental_sync",
52
+ "-y",
53
+ ...SKILLS_AGENTS
54
+ ];
37
55
  const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
38
56
  const HEADER = `# AI Agent Rules
39
57
 
@@ -48,14 +66,18 @@ Add your project-specific rules below the comment line.`;
48
66
  const GENERATED_MARKER = "<!-- @kirill.konshin/lint:generated -->";
49
67
  /**
50
68
  * Marked sections of AGENTS.md that other tools own. Tools write their own agent instructions - nobody copies them by
51
- * hand: this file only provides each anchor, an empty marker pair, on every generation. Sequencing does the rest: the
52
- * tool runs right after `lint-prepare` in the same install script and fills its section - Vite+ on `vp config` (it
53
- * never creates a section, and its creating commands rewrite dependencies).
69
+ * hand: this file only provides each anchor, a marker pair, on every generation, and keeps what the tool wrote between
70
+ * them. Vite+ fills its section on `vp config`, run right after `lint-prepare` in the same install script (it never
71
+ * creates a section, and its creating commands rewrite dependencies); Next.js on `next dev`, when it detects an agent.
54
72
  */
55
73
  const TOOL_SECTIONS = [{
56
74
  tool: "Vite+",
57
75
  start: "<!--VITE PLUS START-->",
58
76
  end: "<!--VITE PLUS END-->"
77
+ }, {
78
+ tool: "Next.js",
79
+ start: "<!-- BEGIN:nextjs-agent-rules -->",
80
+ end: "<!-- END:nextjs-agent-rules -->"
59
81
  }];
60
82
  const lstat = (file) => fs.lstatSync(file, { throwIfNoEntry: false });
61
83
  /**
@@ -151,25 +173,42 @@ function placeLink(cwd, link, target) {
151
173
  * Links listed in a `.gitignore` this tool generated - it doubles as the record of what to clean up next time.
152
174
  */
153
175
  function readManifest(gitignore) {
176
+ return readGitignoreBlocks(gitignore).links;
177
+ }
178
+ /**
179
+ * The two lists of a `.gitignore` this tool generated: its own links, and the skills the `skills` CLI installed.
180
+ */
181
+ function readGitignoreBlocks(gitignore) {
154
182
  const content = fs.existsSync(gitignore) ? fs.readFileSync(gitignore, "utf-8") : "";
155
- if (!content.startsWith(GITIGNORE_HEADER)) return [];
156
- return content.split("\n").filter((line) => line.startsWith("/") && line !== `/${GITIGNORE}`).map((line) => path.normalize(line.slice(1)));
183
+ if (!content.startsWith(GITIGNORE_HEADER)) return {
184
+ links: [],
185
+ synced: []
186
+ };
187
+ const [own, synced = ""] = content.split(GITIGNORE_SYNCED);
188
+ const entries = (block) => block.split("\n").filter((line) => line.startsWith("/") && line !== `/${GITIGNORE}`).map((line) => path.normalize(line.slice(1)));
189
+ return {
190
+ links: entries(own),
191
+ synced: entries(synced)
192
+ };
157
193
  }
158
194
  /**
159
- * Write the `.gitignore` listing `links` (remove it when there are none), unless the user owns that file.
195
+ * Write the `.gitignore` listing `links`, then the `synced` skills below their own header (remove it when both are
196
+ * empty), unless the user owns that file.
160
197
  */
161
- function writeManifest(gitignore, links) {
198
+ function writeManifest(gitignore, links, synced = []) {
162
199
  const exists = fs.existsSync(gitignore);
163
200
  if (exists && !fs.readFileSync(gitignore, "utf-8").startsWith(GITIGNORE_HEADER)) return;
164
- if (!links.length) {
201
+ if (!links.length && !synced.length) {
165
202
  if (exists) fs.unlinkSync(gitignore);
166
203
  return;
167
204
  }
168
- const entries = links.map((link) => `/${link.split(path.sep).join("/")}`).sort();
205
+ const toEntries = (names) => names.map((name) => `/${name.split(path.sep).join("/")}`).sort();
206
+ const syncedBlock = synced.length ? [GITIGNORE_SYNCED, ...toEntries(synced)] : [];
169
207
  fs.writeFileSync(gitignore, [
170
208
  GITIGNORE_HEADER,
171
209
  `/${GITIGNORE}`,
172
- ...entries,
210
+ ...toEntries(links),
211
+ ...syncedBlock,
173
212
  ""
174
213
  ].join("\n"));
175
214
  }
@@ -231,39 +270,193 @@ function readSkills() {
231
270
  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));
232
271
  }
233
272
  /**
234
- * Package entries to link, keyed by their path inside an agent dir: every rule file as `rules/<file>` and every skill
235
- * folder as `skills/<name>`.
273
+ * Package entries to link, keyed by their path inside an agent dir: every rule file as `rules/<file>`. Package skills
274
+ * are not linked here: the `skills` CLI installs them (runSkillsSync()).
236
275
  */
237
- function packageEntries(rules, skills) {
276
+ function packageEntries(rules) {
238
277
  const entries = /* @__PURE__ */ new Map();
239
278
  for (const rule of rules) entries.set(path.join("rules", rule.file), path.join(RULES_DIR, rule.file));
240
- for (const skill of skills) entries.set(path.join("skills", skill.name), path.join(SKILLS_DIR, skill.name));
241
279
  return entries;
242
280
  }
243
281
  /**
282
+ * The directory the `skills` CLI installs a skill into: its name sanitized as the CLI does it (`sanitizeName`), so
283
+ * `model-redux-state/design-state-ownership` lives in `model-redux-state-design-state-ownership`.
284
+ */
285
+ const skillDirName = (name) => name.toLowerCase().replace(/[^a-z0-9._]+/g, "-").replace(/^[.-]+|[.-]+$/g, "").slice(0, 255) || "unnamed-skill";
286
+ /**
287
+ * Directory names of the skills the `skills` CLI installed, from its `skills-lock.json` in cwd; empty when there is
288
+ * none.
289
+ */
290
+ function readSyncedSkills(cwd) {
291
+ try {
292
+ const skills = JSON.parse(fs.readFileSync(path.join(cwd, SKILLS_LOCK), "utf-8"))?.skills;
293
+ return new Set(skills && typeof skills === "object" ? Object.keys(skills).map(skillDirName) : []);
294
+ } catch {
295
+ return /* @__PURE__ */ new Set();
296
+ }
297
+ }
298
+ /**
299
+ * A symlink into `node_modules`: how the `skills` CLI links a package skill, before its lock lists it.
300
+ */
301
+ const isPackageLink = (entry) => !!lstat(entry)?.isSymbolicLink() && fs.readlinkSync(entry).split(/[\\/]/).includes("node_modules");
302
+ /**
244
303
  * The user's own top-level entries in `.agents/rules` and `.agents/skills`, keyed like packageEntries() - everything
245
- * there except the links this tool placed (its generated `.gitignore` lists them), dead links and dotfiles.
304
+ * there except the links this tool placed (its generated `.gitignore` lists them), the skills the `skills` CLI
305
+ * installed, dead links and dotfiles.
246
306
  */
247
307
  function readUserEntries(cwd) {
248
308
  const entries = /* @__PURE__ */ new Map();
309
+ const synced = readSyncedSkills(cwd);
249
310
  for (const kind of AGENT_KINDS) {
250
311
  const root = path.join(cwd, CANONICAL_AGENT_DIR, kind);
251
312
  if (!fs.statSync(root, { throwIfNoEntry: false })?.isDirectory()) continue;
252
313
  const own = manifestNames(root);
253
314
  for (const name of fs.readdirSync(root)) {
254
315
  const entry = path.join(root, name);
255
- if (!name.startsWith(".") && !own.has(name) && fs.existsSync(entry)) entries.set(path.join(kind, name), entry);
316
+ const isSynced = kind === "skills" && (synced.has(name) || isPackageLink(entry));
317
+ if (!name.startsWith(".") && !own.has(name) && !isSynced && fs.existsSync(entry)) entries.set(path.join(kind, name), entry);
256
318
  }
257
319
  }
258
320
  return entries;
259
321
  }
260
322
  /**
323
+ * Run the `skills` CLI this package depends on, in `cwd`, telemetry off unless the user set it. A failure is a
324
+ * warning, the install goes on. Returns whether the command succeeded.
325
+ */
326
+ function runSkillsCli(cwd, args, run) {
327
+ const manifestPath = createRequire(import.meta.url).resolve("skills/package.json");
328
+ const { bin } = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
329
+ const result = run(process.execPath, [path.join(path.dirname(manifestPath), bin.skills), ...args], {
330
+ cwd,
331
+ stdio: "inherit",
332
+ env: {
333
+ DISABLE_TELEMETRY: "1",
334
+ ...process.env
335
+ }
336
+ });
337
+ if (result.status === 0) return true;
338
+ console.warn(`[lint-prepare] skills ${args[0]} failed (${result.error?.message ?? `exit code ${result.status}`}), skills may be missing: re-run lint-prepare`);
339
+ return false;
340
+ }
341
+ /**
342
+ * Install the skills dependencies ship (this package's own `skills/` folder among them) with the `skills` CLI, into
343
+ * `.agents/skills`, linked into `.claude/skills`. `exclude`: `package` or `package#skill` patterns to leave out. On CI
344
+ * nothing remote is touched (`--no-remote`). Returns whether the sync succeeded.
345
+ */
346
+ function runSkillsSync(cwd, run = spawnSync, exclude = []) {
347
+ const args = [...SKILLS_SYNC_ARGS];
348
+ if (process.env.CI) args.push("--no-remote");
349
+ if (exclude.length) args.push("--exclude", ...exclude);
350
+ return runSkillsCli(cwd, args, run);
351
+ }
352
+ /** An npm package that ships skills (`@scope/name`, or a name without `/`); anything else is a git source. */
353
+ const isNpmSkillSource = (source) => source.startsWith("@") || !source.includes("/");
354
+ /**
355
+ * Names of the skills an installed npm package ships: `skills/<name>/SKILL.md` or `dist/skills/<name>/SKILL.md`.
356
+ */
357
+ function readPackageSkills(cwd, packageName) {
358
+ return ["skills", path.join("dist", "skills")].flatMap((dir) => {
359
+ const root = path.join(cwd, "node_modules", packageName, dir);
360
+ if (!fs.existsSync(root)) return [];
361
+ return fs.readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory() && fs.existsSync(path.join(root, entry.name, "SKILL.md"))).map((entry) => entry.name);
362
+ });
363
+ }
364
+ /**
365
+ * Turn the `skills` map into CLI work. npm sources become `experimental_sync` exclusions: a disabled package, the
366
+ * `false` skills, or - when a package lists `true` skills - every other skill it ships. Enabled git sources become
367
+ * `skills add` work.
368
+ */
369
+ function planSkills(skills, packageSkills = () => []) {
370
+ const plan = {
371
+ syncExclude: [],
372
+ remote: []
373
+ };
374
+ for (const [source, option] of Object.entries(skills)) {
375
+ const { enabled = true, ref, skills: names = {} } = asOptions(option);
376
+ const listed = Object.keys(names).filter((name) => names[name]);
377
+ const excluded = Object.keys(names).filter((name) => !names[name]);
378
+ if (isNpmSkillSource(source)) {
379
+ if (!enabled) plan.syncExclude.push(source);
380
+ else {
381
+ const left = listed.length ? packageSkills(source).filter((name) => !listed.includes(name)) : excluded;
382
+ plan.syncExclude.push(...left.map((name) => `${source}#${name}`));
383
+ }
384
+ continue;
385
+ }
386
+ if (enabled) plan.remote.push({
387
+ source,
388
+ ref,
389
+ skills: listed.length ? listed : "*",
390
+ exclude: excluded
391
+ });
392
+ }
393
+ return plan;
394
+ }
395
+ /** The entries of `skills-lock.json` in cwd; empty when there is none. */
396
+ function readSkillsLock(cwd) {
397
+ try {
398
+ const lock = JSON.parse(fs.readFileSync(path.join(cwd, SKILLS_LOCK), "utf-8"));
399
+ return lock.skills && typeof lock.skills === "object" ? lock.skills : {};
400
+ } catch {
401
+ return {};
402
+ }
403
+ }
404
+ /**
405
+ * Install the git sources of the plan with `skills add`, skipping a source whose skills the lock already has at the
406
+ * same ref, then remove what the plan no longer wants: `lint.config.ts` owns the remote skills of `skills-lock.json`
407
+ * (the ones no package `skills` field asked for). Nothing on CI: remote skills need the network.
408
+ */
409
+ function syncRemoteSkills(cwd, remote, run = spawnSync) {
410
+ if (process.env.CI) return;
411
+ const own = (entry) => entry.sourceType !== "node_modules" && !entry.via;
412
+ const fromSource = (lock, { source, ref }) => Object.keys(lock).filter((name) => own(lock[name]) && lock[name].source === source && lock[name].ref === ref);
413
+ for (const wanted of remote) {
414
+ const installed = fromSource(readSkillsLock(cwd), wanted);
415
+ if (wanted.skills === "*" ? installed.length > 0 : wanted.skills.every((name) => installed.includes(name))) continue;
416
+ const skills = wanted.skills === "*" ? ["*"] : wanted.skills;
417
+ runSkillsCli(cwd, [
418
+ "add",
419
+ wanted.ref ? `${wanted.source}#${wanted.ref}` : wanted.source,
420
+ "-y",
421
+ ...SKILLS_AGENTS,
422
+ "--skill",
423
+ ...skills
424
+ ], run);
425
+ }
426
+ const lock = readSkillsLock(cwd);
427
+ const kept = new Set(remote.flatMap((wanted) => fromSource(lock, wanted).filter((name) => wanted.skills === "*" ? !wanted.exclude.includes(name) : wanted.skills.includes(name))));
428
+ const stale = Object.keys(lock).filter((name) => own(lock[name]) && !kept.has(name));
429
+ if (stale.length) runSkillsCli(cwd, [
430
+ "remove",
431
+ ...stale,
432
+ "-y"
433
+ ], run);
434
+ }
435
+ /** Package rules the `rules` map of `lint.config.ts` keeps. */
436
+ function enabledRules(rules, config) {
437
+ return rules.filter((rule) => config.rules?.[rule.name] !== false);
438
+ }
439
+ /**
440
+ * List the skills the `skills` CLI installed in the `.gitignore` of every agent `skills` dir: they stay out of git, and
441
+ * the links this tool placed keep their own list.
442
+ */
443
+ function recordSyncedSkills(cwd) {
444
+ const synced = [...readSyncedSkills(cwd)];
445
+ for (const dir of AGENT_DIRS) {
446
+ const root = path.join(cwd, dir, "skills");
447
+ if (!lstat(root)?.isDirectory()) continue;
448
+ const gitignore = path.join(root, GITIGNORE);
449
+ writeManifest(gitignore, readManifest(gitignore), synced.filter((name) => lstat(path.join(root, name))));
450
+ }
451
+ }
452
+ /**
261
453
  * Make `rules` and `skills` real directories in every agent dir and link the top-level entries we know into them:
262
- * package rule files and skill folders into both, pointing straight at the package, the user's own `.agents` entries
263
- * into `.claude`. A real entry is the user's - never written over or through. Dead links are removed, and so are
264
- * links from the previous run that are no longer placed (incl. the per-file links of older versions): each
265
- * directory's generated `.gitignore` records them (and keeps them out of git, so the user's own entries there stay
266
- * tracked). The `commands` directories older versions synced are cleaned up the same way, `.codex` is not touched.
454
+ * package rule files into both, pointing straight at the package, the user's own `.agents` entries into `.claude`.
455
+ * A real entry is the user's - never written over or through. Dead links are removed, and so are links from the
456
+ * previous run that are no longer placed (incl. the package skill links of older versions, so the `skills` CLI can
457
+ * place its own): each directory's generated `.gitignore` records them (and keeps them out of git, so the user's own
458
+ * entries there stay tracked); the skills the `skills` CLI installed are listed there too, but never cleaned up. The
459
+ * `commands` directories older versions synced are cleaned up the same way, `.codex` is not touched.
267
460
  *
268
461
  * FIXME Codex Includes
269
462
  * https://github.com/openai/codex/issues/17401
@@ -291,7 +484,7 @@ function syncAgentDirs(cwd, packageEntries, userEntries) {
291
484
  const linkPath = path.join(rootPath, link);
292
485
  if (!planned.some(([plannedLink]) => plannedLink === path.join(root, link)) && lstat(linkPath)?.isSymbolicLink()) removeLink(linkPath, rootPath);
293
486
  }
294
- writeManifest(gitignore, planned.filter(([link, target]) => placeLink(cwd, link, target)).map(([link]) => path.relative(root, link)));
487
+ writeManifest(gitignore, planned.filter(([link, target]) => placeLink(cwd, link, target)).map(([link]) => path.relative(root, link)), readGitignoreBlocks(gitignore).synced);
295
488
  }
296
489
  }
297
490
  /**
@@ -339,14 +532,18 @@ function symlinkClaudeMd(cwd) {
339
532
  * there) and honours each rule's `paths`, while an `@` import would load every rule into every session, scoped or not.
340
533
  * Codex, which expands no `@`, reads this index.
341
534
  */
342
- function generateAgentsFile(rules, customSection) {
535
+ function generateAgentsFile(rules, customSection, previous = "") {
343
536
  const entries = rules.map((rule) => {
344
537
  const rulePath = `${CANONICAL_AGENT_DIR}/rules/${rule.file}`;
345
538
  const description = rule.description ? ` — ${rule.description}` : "";
346
539
  const scope = rule.paths ? `; when touching ${rule.paths.map((glob) => `\`${glob}\``).join(", ")}` : "";
347
540
  return `- **${toTitle(rule.name)}**${description}${scope}: [${rulePath}](${rulePath})`;
348
541
  });
349
- const sections = TOOL_SECTIONS.map(({ start, end }) => `${start}\n${end}`);
542
+ const sections = TOOL_SECTIONS.map(({ start, end }) => {
543
+ const from = previous.indexOf(start);
544
+ const to = from === -1 ? -1 : previous.indexOf(end, from);
545
+ return to === -1 ? `${start}\n${end}` : previous.slice(from, to + end.length);
546
+ });
350
547
  const generated = `${HEADER}\n\n# Rules\n\n${entries.join("\n")}\n\n${sections.join("\n\n")}\n\n${FOOTER}\n\n${GENERATED_MARKER}`;
351
548
  return customSection ? `${generated}\n\n${customSection}\n` : `${generated}\n`;
352
549
  }
@@ -374,7 +571,7 @@ function checkExisting(targetPath) {
374
571
  /**
375
572
  * Main function
376
573
  */
377
- function main() {
574
+ async function main() {
378
575
  const command = process.argv.slice(2)[0] || "init";
379
576
  const cwd = process.env.INIT_CWD || process.cwd();
380
577
  const targetPath = path.join(cwd, AGENTS_FILE);
@@ -392,14 +589,20 @@ function main() {
392
589
  }
393
590
  if (command === "update" || command === "init") {
394
591
  checkClaudeMdSafety(claudeMdPath);
395
- const rules = readRules();
592
+ const root = findWorkspaceRoot(cwd);
593
+ if (!fs.existsSync(path.join(root, "lint.config.ts"))) console.warn(`[lint-prepare] ${LINT_CONFIG_FILE} is missing in ${root}: create it (see the @kirill.konshin/lint README), the defaults apply until then`);
594
+ const config = await resolveLintConfig({}, root);
595
+ const rules = enabledRules(readRules(), config);
396
596
  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
597
  const userEntries = readUserEntries(cwd);
400
- syncAgentDirs(cwd, packageEntries(rules, skills), userEntries);
598
+ syncAgentDirs(cwd, packageEntries(rules), userEntries);
401
599
  console.log(`Synced ${AGENT_DIRS.join(", ")}, mirrored ${userEntries.size} own entries from ${CANONICAL_AGENT_DIR}`);
402
- const content = generateAgentsFile(installedRules(rules, userEntries), customSection);
600
+ const plan = planSkills(config.skills ?? {}, (packageName) => readPackageSkills(cwd, packageName));
601
+ if (runSkillsSync(cwd, spawnSync, plan.syncExclude)) console.log(`Synced skills with the skills CLI, see ${SKILLS_LOCK}`);
602
+ syncRemoteSkills(cwd, plan.remote);
603
+ recordSyncedSkills(cwd);
604
+ const previous = exists ? fs.readFileSync(targetPath, "utf-8") : "";
605
+ const content = generateAgentsFile(installedRules(rules, userEntries), customSection, previous);
403
606
  fs.writeFileSync(targetPath, content, "utf-8");
404
607
  console.log(`${exists ? "Updated" : "Created"} ${AGENTS_FILE}`);
405
608
  symlinkClaudeMd(cwd);
@@ -410,6 +613,11 @@ function main() {
410
613
  console.log("Usage: lint-prepare [init|update]");
411
614
  process.exit(1);
412
615
  }
413
- if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(__filename)) main();
616
+ if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(__filename)) try {
617
+ await main();
618
+ } catch (error) {
619
+ console.error(error);
620
+ process.exit(1);
621
+ }
414
622
  //#endregion
415
- export { checkClaudeMdSafety, checkExisting, generateAgentsFile, installedRules, main, packageEntries, readRules, readSkills, readUserEntries, symlinkClaudeMd, syncAgentDirs };
623
+ export { checkClaudeMdSafety, checkExisting, enabledRules, generateAgentsFile, installedRules, isNpmSkillSource, main, packageEntries, planSkills, readPackageSkills, readRules, readSkills, readSyncedSkills, readUserEntries, recordSyncedSkills, runSkillsSync, skillDirName, symlinkClaudeMd, syncAgentDirs, syncRemoteSkills };
@@ -1,6 +1,6 @@
1
1
  import { tsExtsRaw } from "./exts.js";
2
- import path from "node:path";
3
2
  import fs from "node:fs";
3
+ import path from "node:path";
4
4
  //#region src/testColocation.ts
5
5
  const SOURCE_EXTS = tsExtsRaw.split(",").map((ext) => `.${ext}`);
6
6
  const TEST_SUFFIX = new RegExp(`\\.test\\.(${tsExtsRaw.replaceAll(",", "|")})$`);
@@ -1,21 +1,10 @@
1
1
  import { tsExts } from "./exts.js";
2
- import { DetectionOptions, TailwindOptions, ToggleOptions } from "./index.js";
2
+ import { LintConfig } from "./config.js";
3
3
  import { UserConfig } from "vite-plus";
4
4
  import { OxfmtConfig } from "vite-plus/fmt";
5
5
  import { OxlintConfig } from "vite-plus/lint";
6
6
  //#region src/vitePlus.d.ts
7
7
  type StagedConfig = NonNullable<UserConfig['staged']>;
8
- export type VitePlusOptions = {
9
- detection?: boolean | DetectionOptions;
10
- next?: boolean | ToggleOptions;
11
- storybook?: boolean | ToggleOptions;
12
- turbo?: boolean | ToggleOptions;
13
- nx?: boolean | ToggleOptions;
14
- jest?: boolean | ToggleOptions;
15
- vitest?: boolean | ToggleOptions;
16
- tailwind?: boolean | TailwindOptions;
17
- typeAware?: boolean | ToggleOptions;
18
- };
19
8
  /**
20
9
  * Oxlint config: the ESLint config's rules, by Oxlint's names. Each plugin's `recommended` set maps to Oxlint's
21
10
  * `correctness` category; the deliberate overrides of the ESLint config are listed rule by rule. Plugins Oxlint has no
@@ -26,7 +15,7 @@ export type VitePlusOptions = {
26
15
  * (off anyway). Import sorting moves to Oxfmt (`sortImports`), unused-import removal to `no-unused-vars` with an
27
16
  * import autofix.
28
17
  */
29
- export declare function lintConfig(options?: VitePlusOptions): OxlintConfig;
18
+ export declare function lintConfig(options?: LintConfig): OxlintConfig;
30
19
  /**
31
20
  * Oxfmt config: the Prettier config (`./prettier`), plus the import order `simple-import-sort` enforced (see
32
21
  * typescript.md). Oxfmt reads `.editorconfig`, which Prettier partly ignored, so the Prettier behaviors that differ
@@ -42,17 +31,18 @@ export declare function fmtConfig(): OxfmtConfig;
42
31
  */
43
32
  export declare function stagedConfig(): StagedConfig;
44
33
  /**
45
- * The shared Vite+ config: {@link lintConfig}, {@link fmtConfig} and {@link stagedConfig} merged with the consumer's
46
- * own config. Lists add up (`plugins`, `jsPlugins`, `overrides`, `ignorePatterns`), maps merge key by key (`rules`,
47
- * `settings`, `env`, ...), and a consumer's `staged` replaces the default. Wrap the result in `defineConfig`:
34
+ * The shared Vite+ config, from the workspace root `lint.config.ts`: {@link lintConfig}, {@link fmtConfig} and
35
+ * {@link stagedConfig}, then the project's own blocks (`vitePlus` key of `lint.config.ts`), then `config` (see
36
+ * `mergeUserConfig` for how blocks merge). `overrides` merge deep over `lint.config.ts`. Async: wrap the Promise in
37
+ * `defineConfig`, Vite+ awaits it:
48
38
  *
49
39
  * ```ts
50
40
  * import { vitePlusConfig } from '@kirill.konshin/lint/vite-plus';
51
41
  * import { defineConfig } from 'vite-plus';
52
42
  *
53
- * export default defineConfig(vitePlusConfig({ lint: { rules: { ... } } }));
43
+ * export default defineConfig(vitePlusConfig());
54
44
  * ```
55
45
  */
56
- export declare function vitePlusConfig(config?: UserConfig, options?: VitePlusOptions): UserConfig;
46
+ export declare function vitePlusConfig(config?: UserConfig, overrides?: LintConfig): Promise<UserConfig>;
57
47
  //#endregion
58
48
  export { tsExts };
package/dist/vitePlus.js CHANGED
@@ -1,7 +1,8 @@
1
+ import { GLOBAL_IGNORES, asOptions, findWorkspaceRoot } from "./lib.js";
1
2
  import { eslintExts, markupExtsRaw, prettierExtsRaw, tsExts, tsExtsRaw } from "./exts.js";
3
+ import { resolveLintConfig } from "./config.js";
2
4
  import { defaultExportFiles, filenameCaseIgnore } from "./conventions.js";
3
- import { GLOBAL_IGNORES, asOptions, findNextRoots, findWorkspaceRoot, hasJest, hasNext, hasNx, hasStorybook, hasTurbo, scanWorkspace, toolGate } from "./lib.js";
4
- import { tailwindGate } from "./configs/tailwind.js";
5
+ import { jestGate, nextGate, nxGate, storybookGate, tailwindGate, turboGate } from "./gates.js";
5
6
  import { dirname, relative } from "node:path";
6
7
  import { fileURLToPath } from "node:url";
7
8
  //#region src/vitePlus.ts
@@ -43,37 +44,15 @@ function workspaceGlob(dir, glob) {
43
44
  function lintConfig(options = {}) {
44
45
  const { enabled: defaultOn = true, strict = false } = asOptions(options.detection);
45
46
  const flag = (option) => option === void 0 && !defaultOn ? false : option;
46
- const next = toolGate(flag(options.next), strict, {
47
- tool: "next",
48
- has: hasNext,
49
- requirePackage: false,
50
- scan: () => findNextRoots(GLOBAL_IGNORES).map((dir) => `${dir}/package.json`)
51
- });
52
- const storybook = toolGate(flag(options.storybook), strict, {
53
- tool: "storybook",
54
- has: hasStorybook,
55
- packageName: "storybook",
56
- scan: () => scanWorkspace(".storybook/main.*", GLOBAL_IGNORES, { dot: true })
57
- });
58
- const turbo = toolGate(flag(options.turbo), false, {
59
- tool: "turbo",
60
- has: hasTurbo,
61
- requirePackage: false
62
- });
63
- const nx = toolGate(flag(options.nx), strict, {
64
- tool: "nx",
65
- has: hasNx,
66
- packageName: "eslint"
67
- });
68
- const jest = toolGate(flag(options.jest), strict, {
69
- tool: "jest",
70
- has: hasJest,
71
- requirePackage: false,
72
- scan: () => scanWorkspace("jest.config.*", GLOBAL_IGNORES)
73
- });
47
+ const next = nextGate(flag(options.next), strict, { requirePackage: false });
48
+ const storybook = storybookGate(flag(options.storybook), strict);
49
+ const turbo = turboGate(flag(options.turbo));
50
+ const nx = nxGate(flag(options.nx), strict, { packageName: "eslint" });
51
+ const jest = jestGate(flag(options.jest), strict);
74
52
  const vitest = asOptions(flag(options.vitest)).enabled ?? true;
75
53
  const tailwind = tailwindGate(flag(options.tailwind), strict);
76
- const { enabled: typeAware = true } = asOptions(options.typeAware);
54
+ const { enabled: typeAware = true } = asOptions(options.vitePlus?.typeAware);
55
+ const nextRootDir = next.enabled ? next.options.rootDir ?? (next.files.length > 0 ? next.files.map(dirname) : void 0) : void 0;
77
56
  const jsPlugins = [{
78
57
  name: "local",
79
58
  specifier: pluginPath("@kirill.konshin/lint/oxlint-plugin")
@@ -199,7 +178,7 @@ function lintConfig(options = {}) {
199
178
  ignorePatterns: GLOBAL_IGNORES,
200
179
  settings: {
201
180
  react: { version: "19" },
202
- ...next.enabled && next.files.length > 0 ? { next: { rootDir: next.files.map(dirname) } } : {},
181
+ ...nextRootDir ? { next: { rootDir: nextRootDir } } : {},
203
182
  ...tailwind ? { tailwindcss: { cssConfigPath: tailwind.absoluteCssConfigPath } } : {}
204
183
  },
205
184
  ...typeAware ? { options: {
@@ -372,22 +351,14 @@ function stagedConfig() {
372
351
  return { [`*.{${tsExtsRaw},${markupExtsRaw},${prettierExtsRaw}}`]: "vp check --fix" };
373
352
  }
374
353
  /**
375
- * The shared Vite+ config: {@link lintConfig}, {@link fmtConfig} and {@link stagedConfig} merged with the consumer's
376
- * own config. Lists add up (`plugins`, `jsPlugins`, `overrides`, `ignorePatterns`), maps merge key by key (`rules`,
377
- * `settings`, `env`, ...), and a consumer's `staged` replaces the default. Wrap the result in `defineConfig`:
378
- *
379
- * ```ts
380
- * import { vitePlusConfig } from '@kirill.konshin/lint/vite-plus';
381
- * import { defineConfig } from 'vite-plus';
382
- *
383
- * export default defineConfig(vitePlusConfig({ lint: { rules: { ... } } }));
384
- * ```
354
+ * `extra` merged over `base`: lists add up (`plugins`, `jsPlugins`, `overrides`, `ignorePatterns`), maps merge key by key
355
+ * (`rules`, `settings`, `env`, ...), an `extra` `staged` replaces the base one, other blocks are replaced.
385
356
  */
386
- function vitePlusConfig(config = {}, options = {}) {
387
- const { lint = {}, fmt = {}, staged, ...rest } = config;
388
- const baseLint = lintConfig(options);
389
- const baseFmt = fmtConfig();
357
+ function mergeUserConfig(base, extra) {
358
+ const { lint: baseLint = {}, fmt: baseFmt = {}, staged: baseStaged, ...baseRest } = base;
359
+ const { lint = {}, fmt = {}, staged, ...rest } = extra;
390
360
  return {
361
+ ...baseRest,
391
362
  ...rest,
392
363
  lint: {
393
364
  ...baseLint,
@@ -427,8 +398,30 @@ function vitePlusConfig(config = {}, options = {}) {
427
398
  ignorePatterns: [...baseFmt.ignorePatterns ?? [], ...fmt.ignorePatterns ?? []],
428
399
  overrides: [...baseFmt.overrides ?? [], ...fmt.overrides ?? []]
429
400
  },
430
- staged: staged ?? stagedConfig()
401
+ ...staged || baseStaged ? { staged: staged ?? baseStaged } : {}
431
402
  };
432
403
  }
404
+ /**
405
+ * The shared Vite+ config, from the workspace root `lint.config.ts`: {@link lintConfig}, {@link fmtConfig} and
406
+ * {@link stagedConfig}, then the project's own blocks (`vitePlus` key of `lint.config.ts`), then `config` (see
407
+ * `mergeUserConfig` for how blocks merge). `overrides` merge deep over `lint.config.ts`. Async: wrap the Promise in
408
+ * `defineConfig`, Vite+ awaits it:
409
+ *
410
+ * ```ts
411
+ * import { vitePlusConfig } from '@kirill.konshin/lint/vite-plus';
412
+ * import { defineConfig } from 'vite-plus';
413
+ *
414
+ * export default defineConfig(vitePlusConfig());
415
+ * ```
416
+ */
417
+ async function vitePlusConfig(config = {}, overrides = {}) {
418
+ const options = await resolveLintConfig(overrides);
419
+ const { typeAware: _typeAware, ...blocks } = options.vitePlus ?? {};
420
+ return mergeUserConfig(mergeUserConfig({
421
+ lint: lintConfig(options),
422
+ fmt: fmtConfig(),
423
+ staged: stagedConfig()
424
+ }, blocks), config);
425
+ }
433
426
  //#endregion
434
427
  export { fmtConfig, lintConfig, stagedConfig, tsExts, vitePlusConfig };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@kirill.konshin/lint",
3
3
  "description": "Vite+ (Oxlint + Oxfmt), ESLint + Prettier + lint-staged configs and AI agent rules/skills for monorepos",
4
- "version": "0.7.3",
4
+ "version": "0.8.0",
5
5
  "type": "module",
6
6
  "skipGenerate": true,
7
7
  "bin": {
@@ -16,6 +16,11 @@
16
16
  "types": "./dist/index.d.ts",
17
17
  "import": "./dist/index.js"
18
18
  },
19
+ "./config": {
20
+ "types": "./dist/config.d.ts",
21
+ "import": "./dist/config.js",
22
+ "default": "./dist/config.js"
23
+ },
19
24
  "./lint-staged": {
20
25
  "types": "./dist/lintStaged.d.ts",
21
26
  "import": "./dist/lintStaged.js",
@@ -86,6 +91,7 @@
86
91
  "jsonc-eslint-parser": "^3.3.0",
87
92
  "local-pkg": "^1.2.1",
88
93
  "path-scurry": "^2.0.2",
94
+ "skills": "1.7.4",
89
95
  "yaml": "^2.9.0"
90
96
  },
91
97
  "devDependencies": {
@@ -140,9 +146,6 @@
140
146
  "vite": {
141
147
  "optional": true
142
148
  },
143
- "vite-plus": {
144
- "optional": true
145
- },
146
149
  "vitest": {
147
150
  "optional": true
148
151
  }
package/rules/agent.md CHANGED
@@ -88,6 +88,7 @@ Do not use `.claude/commands` for anything. It's not portable (`.agent/commands`
88
88
  # `.agents/skills`
89
89
 
90
90
  - `.agents/skills` must be accompanied by symlinks in `.claude/skills`
91
+ - A personal skill (`~/.claude/skills`) overrides a project skill with the same name: do not install the same skill at both levels
91
92
  - May define either
92
93
  - A workflow
93
94
  - A process