@ingram-tech/nk-dev 0.18.0 → 0.19.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.
package/README.md CHANGED
@@ -81,8 +81,9 @@ tsc), so versions stay under your control. nk only orchestrates.
81
81
  skips files that already exist.
82
82
  - **`nk doctor [--fix]`** — report drift from the canonical nk-dev toolchain
83
83
  (superseded deps, config `extends`, package.json scripts, the agent-guide
84
- import, a stale `.prettierignore`, an unsealed migration chain and the DDL in
85
- it drizzle can't model, a page under `app/auth/` shadowing a Better Auth
84
+ import (from any CLAUDE.md up to the repository root), a stale
85
+ `.prettierignore`, an unsealed migration chain and the DDL in it drizzle
86
+ can't model, a page under `app/auth/` shadowing a Better Auth
86
87
  endpoint — static segments beat the `[...all]` catch-all, so such a page
87
88
  silently 405s the endpoint, a page or layout whose `openGraph` carries no
88
89
  image — its own object replaces the inherited one, so the card unfurls as a
@@ -96,7 +97,10 @@ tsc), so versions stay under your control. nk only orchestrates.
96
97
  - **`nk format` / `nk format --check`** — formats code (JS/TS/JSON/CSS) with
97
98
  oxfmt. `--check` verifies without writing (CI). SQL isn't formatted; see
98
99
  [Why no SQL formatting?](#why-no-sql-formatting).
99
- - **`nk lint`** — `oxlint`.
100
+ - **`nk lint`** — `oxlint`. nk-dev ships oxlint's type-aware backend
101
+ (`oxlint-tsgolint`) and hands it to oxlint, so a site turns on type-aware
102
+ rules with `"options": { "typeAware": true }` in `.oxlintrc.json` and
103
+ declares nothing else. An `OXLINT_TSGOLINT_PATH` you set wins.
100
104
  - **`nk knip`** — `knip` (unused dependencies / exports / files).
101
105
  - **`nk migrations [--check|--reseal|--ddl]`** — guard the `drizzle/` migration
102
106
  chain, with no database involved. Verifies each file against the hashes in
@@ -113,8 +117,9 @@ tsc), so versions stay under your control. nk only orchestrates.
113
117
  apply → `nk format` + `nk type-check`) and its syntactic-not-semantic limits
114
118
  live in the codemod skill, `skills/ts-codemod.md`.
115
119
  - **`nk check`** — `oxlint` + `oxfmt --check` + `knip` (only when the repo has a
116
- knip config) + the agent-guide import gate + the migration seal. The CI gate;
117
- runs every checker and reports them all before failing.
120
+ knip config) + the agent-guide import gate (any CLAUDE.md from the site up
121
+ to the repository root) + the migration seal. The CI gate; runs every
122
+ checker and reports them all before failing.
118
123
  - **`nk type-check`** — `next typegen && tsc --noEmit`, with recovery: when
119
124
  every error sits inside generated types (`.next/types`, `.next/dev/types` —
120
125
  a deleted route or a killed dev server leaves them stale, and `next typegen`
@@ -1,7 +1,10 @@
1
- import { existsSync, readFileSync } from "node:fs";
2
- import { dirname, resolve } from "node:path";
1
+ import { existsSync, readFileSync, writeFileSync } from "node:fs";
2
+ import { dirname, relative, resolve } from "node:path";
3
3
 
4
- // A Claude Code `@import` of the shared guide, e.g.
4
+ /** The line that `@import`s the shared guide into a CLAUDE.md. */
5
+ export const GUIDE_IMPORT = "@./node_modules/@ingram-tech/nk-dev/guide.md";
6
+
7
+ // Any spelling of the import, e.g.
5
8
  // @./node_modules/@ingram-tech/nk-dev/guide.md
6
9
  // @./web/node_modules/@ingram-tech/nk-dev/guide.md (app in a subdir)
7
10
  const IMPORT_RE = /@\S*nk-dev\/guide\.md/;
@@ -15,21 +18,39 @@ function readDeps(cwd) {
15
18
  }
16
19
  }
17
20
 
18
- // CLAUDE.md sits next to package.json for a standard site; for an app nested in a
19
- // subdir (e.g. `web/`) it lives one level up at the repo root. Check both.
20
- function findClaudeMd(cwd) {
21
- for (const dir of [cwd, dirname(resolve(cwd))]) {
22
- const p = resolve(dir, "CLAUDE.md");
23
- if (existsSync(p)) return p;
21
+ /**
22
+ * Every CLAUDE.md from `cwd` up to the repository root, nearest first. Claude
23
+ * Code loads all of them, so an import in any one reaches the agent. The walk
24
+ * stops at the directory holding `.git`: a CLAUDE.md above the repository is
25
+ * absent in CI, and must not pass the gate on one machine only.
26
+ */
27
+ function claudeFiles(cwd) {
28
+ const files = [];
29
+ let dir = resolve(cwd);
30
+ for (;;) {
31
+ const file = resolve(dir, "CLAUDE.md");
32
+ if (existsSync(file)) files.push(file);
33
+ const parent = dirname(dir);
34
+ if (existsSync(resolve(dir, ".git")) || parent === dir) return files;
35
+ dir = parent;
24
36
  }
25
- return null;
37
+ }
38
+
39
+ /** The CLAUDE.md that imports the guide, from `cwd` up to the repository root. */
40
+ function findGuideImport(cwd) {
41
+ const files = claudeFiles(cwd);
42
+ return {
43
+ files,
44
+ importer: files.find((file) => IMPORT_RE.test(readFileSync(file, "utf8"))),
45
+ };
26
46
  }
27
47
 
28
48
  /**
29
49
  * nextkit's shared agent guidance (`@ingram-tech/nk-dev/guide.md`) only reaches
30
- * an AI agent if the site's CLAUDE.md `@import`s it. A site can depend on nk-dev
50
+ * an AI agent if a CLAUDE.md it loads `@import`s it. A site can depend on nk-dev
31
51
  * yet forget the import line — then the guidance silently never loads. When the
32
- * package is a dependency, assert CLAUDE.md actually imports it.
52
+ * package is a dependency, assert that a CLAUDE.md from here to the repository
53
+ * root imports it.
33
54
  *
34
55
  * Returns `{ ok, reason }`. `ok` is true when there's nothing to enforce (the
35
56
  * package isn't a dependency) or the import is present; `reason` explains a miss.
@@ -38,18 +59,36 @@ export function checkAgentGuideImport(cwd = process.cwd()) {
38
59
  const deps = readDeps(cwd);
39
60
  if (!deps || !deps["@ingram-tech/nk-dev"]) return { ok: true };
40
61
 
41
- const claudePath = findClaudeMd(cwd);
42
- if (!claudePath) {
62
+ const { files, importer } = findGuideImport(cwd);
63
+ if (importer) return { ok: true };
64
+ if (files.length === 0) {
43
65
  return {
44
66
  ok: false,
45
67
  reason: "depends on @ingram-tech/nk-dev but has no CLAUDE.md importing its guide",
46
68
  };
47
69
  }
48
- if (!IMPORT_RE.test(readFileSync(claudePath, "utf8"))) {
49
- return {
50
- ok: false,
51
- reason: "CLAUDE.md does not @import @ingram-tech/nk-dev/guide.md (shared agent guidance won't load)",
52
- };
70
+ return {
71
+ ok: false,
72
+ reason: "CLAUDE.md does not @import @ingram-tech/nk-dev/guide.md, and no CLAUDE.md above it up to the repository root does (shared agent guidance won't load)",
73
+ };
74
+ }
75
+
76
+ /**
77
+ * Make the guide reach the agent working in `dir`: when no CLAUDE.md from `dir`
78
+ * to the repository root imports it, add the import to `dir/CLAUDE.md`,
79
+ * creating the file if needed. Idempotent. Returns a short past-tense note.
80
+ */
81
+ export function ensureGuideImport(dir) {
82
+ const { importer } = findGuideImport(dir);
83
+ if (importer) {
84
+ return `${relative(dir, importer) || "CLAUDE.md"} already imports the agent guide`;
85
+ }
86
+ const file = resolve(dir, "CLAUDE.md");
87
+ if (!existsSync(file)) {
88
+ writeFileSync(file, `# Project\n\n${GUIDE_IMPORT}\n`);
89
+ return "wrote CLAUDE.md with the agent-guide import";
53
90
  }
54
- return { ok: true };
91
+ const body = readFileSync(file, "utf8");
92
+ writeFileSync(file, `${body.replace(/\n*$/, "")}\n\n${GUIDE_IMPORT}\n`);
93
+ return "added the agent-guide import to CLAUDE.md";
55
94
  }
package/lib/doctor.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
2
2
  import { resolve } from "node:path";
3
+ import { checkAgentGuideImport, ensureGuideImport } from "./agent-guide.js";
3
4
  import { authNextFindings } from "./auth-next.js";
4
5
  import { authShadowFindings } from "./auth-shadow.js";
5
6
  import { authVersionFindings } from "./auth-version.js";
@@ -25,7 +26,6 @@ const CANONICAL_SCRIPTS = {
25
26
  "type-check": "nk type-check",
26
27
  };
27
28
 
28
- const GUIDE_IMPORT = "@./node_modules/@ingram-tech/nk-dev/guide.md";
29
29
  const OXLINTRC_FILE = "node_modules/@ingram-tech/nk-dev/oxlintrc.json";
30
30
  /** Matches any `extends` entry that reaches nk-dev's oxlintrc, whatever the prefix. */
31
31
  const OXLINTRC_EXTENDS_RE = /(^|\/)node_modules\/@ingram-tech\/nk-dev\/oxlintrc\.json$/;
@@ -180,31 +180,15 @@ export function findings(cwd) {
180
180
  });
181
181
  }
182
182
 
183
- // 5. CLAUDE.md imports the shared guide.
184
- const claudePath = resolve(cwd, "CLAUDE.md");
185
- if (deps["@ingram-tech/nk-dev"]) {
186
- const claude = existsSync(claudePath) ? readFileSync(claudePath, "utf8") : null;
187
- if (claude === null || !/@\S*nk-dev\/guide\.md/.test(claude)) {
188
- out.push({
189
- id: "claude:guide-import",
190
- level: "error",
191
- message:
192
- claude === null
193
- ? "no CLAUDE.md importing the nk-dev guide"
194
- : "CLAUDE.md does not @import the nk-dev guide",
195
- fix: (dir) => {
196
- const p = resolve(dir, "CLAUDE.md");
197
- const body = existsSync(p)
198
- ? readFileSync(p, "utf8")
199
- : "# Project\n";
200
- writeFileSync(
201
- p,
202
- `${body.replace(/\n*$/, "")}\n\n${GUIDE_IMPORT}\n`,
203
- );
204
- return "added the guide import to CLAUDE.md";
205
- },
206
- });
207
- }
183
+ // 5. A CLAUDE.md from here to the repository root imports the shared guide.
184
+ const guide = checkAgentGuideImport(cwd);
185
+ if (!guide.ok) {
186
+ out.push({
187
+ id: "claude:guide-import",
188
+ level: "error",
189
+ message: guide.reason,
190
+ fix: ensureGuideImport,
191
+ });
208
192
  }
209
193
 
210
194
  // 6. knip.json ignoreDependencies referencing superseded packages (stale).
package/lib/init.js CHANGED
@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
2
2
  import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
3
3
  import { dirname, resolve } from "node:path";
4
4
  import { fileURLToPath } from "node:url";
5
+ import { ensureGuideImport } from "./agent-guide.js";
5
6
 
6
7
  // Files live at the package root, two levels up from lib/.
7
8
  const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -99,8 +100,6 @@ set -eu
99
100
  exec bun x --bun nextkit-format-staged
100
101
  `;
101
102
 
102
- const GUIDE_IMPORT = "@./node_modules/@ingram-tech/nk-dev/guide.md";
103
-
104
103
  export function init() {
105
104
  const cwd = process.cwd();
106
105
 
@@ -135,8 +134,8 @@ export function init() {
135
134
  // 7. Format-on-commit hook + git wiring.
136
135
  setupGitHook(cwd);
137
136
 
138
- // 8. Make sure the agent guide is imported into CLAUDE.md.
139
- ensureGuideImport(cwd);
137
+ // 8. Make sure the agent guide is imported into a CLAUDE.md the agent loads.
138
+ log(ensureGuideImport(cwd));
140
139
 
141
140
  // 9. A `prepare` script so the hook re-wires itself on every `bun install`.
142
141
  ensurePrepareScript(cwd);
@@ -163,22 +162,6 @@ function setupGitHook(cwd) {
163
162
  });
164
163
  }
165
164
 
166
- function ensureGuideImport(cwd) {
167
- const claudePath = resolve(cwd, "CLAUDE.md");
168
- if (!existsSync(claudePath)) {
169
- writeFileSync(claudePath, `# Project\n\n${GUIDE_IMPORT}\n`);
170
- log("wrote CLAUDE.md with the agent-guide import");
171
- return;
172
- }
173
- const body = readFileSync(claudePath, "utf8");
174
- if (body.includes("nk-dev/guide.md")) {
175
- log("CLAUDE.md already imports the agent guide.");
176
- return;
177
- }
178
- writeFileSync(claudePath, `${body.replace(/\n*$/, "")}\n\n${GUIDE_IMPORT}\n`);
179
- log("added the agent-guide import to CLAUDE.md");
180
- }
181
-
182
165
  function hintVitestConfig(cwd) {
183
166
  if (existsSync(resolve(cwd, "vitest.config.ts"))) {
184
167
  skip("vitest.config.ts");
@@ -1,4 +1,4 @@
1
- import { checkAgentGuideImport } from "./agent-guide.js";
1
+ import { GUIDE_IMPORT, checkAgentGuideImport } from "./agent-guide.js";
2
2
  import {
3
3
  cleanGeneratedArtifacts,
4
4
  onlyGeneratedTypeErrors,
@@ -9,6 +9,7 @@ import { FORMATTER } from "./formatter.js";
9
9
  import { hasKnipConfig, runKnip } from "./knip.js";
10
10
  import { checkSeal } from "./migrations.js";
11
11
  import { run, runCapture, writeThrough } from "./run.js";
12
+ import { lintEnvironment } from "./tsgolint.js";
12
13
  import {
13
14
  tailwindCoverageFindings,
14
15
  tailwindSourceFindings,
@@ -17,7 +18,11 @@ import { readdirSync, rmSync } from "node:fs";
17
18
 
18
19
  /** `nk lint [...]` — oxlint, with extra args passed through (e.g. `--fix`). */
19
20
  export function lint(extraArgs = []) {
20
- process.exit(run(FORMATTER.lint[0], [...FORMATTER.lint[1], ...extraArgs]));
21
+ process.exit(
22
+ run(FORMATTER.lint[0], [...FORMATTER.lint[1], ...extraArgs], {
23
+ env: lintEnvironment(),
24
+ }),
25
+ );
21
26
  }
22
27
 
23
28
  /**
@@ -31,7 +36,8 @@ export function lint(extraArgs = []) {
31
36
  export function check() {
32
37
  // Run every gate before deciding (no short-circuit), so one failure doesn't
33
38
  // hide another. oxc splits lint (oxlint) and format (oxfmt), so we run both.
34
- const lintFailed = run(FORMATTER.lint[0], FORMATTER.lint[1]) !== 0;
39
+ const lintFailed =
40
+ run(FORMATTER.lint[0], FORMATTER.lint[1], { env: lintEnvironment() }) !== 0;
35
41
  const fmtFailed = run(FORMATTER.checkFormat[0], FORMATTER.checkFormat[1]) !== 0;
36
42
  // knip (unused deps/exports/files). Opt-in: only when the repo has a knip
37
43
  // config — knip has no shareable config, so absence means "not adopted".
@@ -42,7 +48,7 @@ export function check() {
42
48
  if (!guide.ok) {
43
49
  console.error(`nk check: ${guide.reason}`);
44
50
  console.error(
45
- " → add `@./node_modules/@ingram-tech/nk-dev/guide.md` to your CLAUDE.md (or run `nk init`).",
51
+ ` → add \`${GUIDE_IMPORT}\` to your CLAUDE.md (or run \`nk init\`).`,
46
52
  );
47
53
  }
48
54
  // Applied migrations are immutable. A no-op on sites without a `drizzle/`
@@ -0,0 +1,35 @@
1
+ import { createRequire } from "node:module";
2
+
3
+ const require = createRequire(import.meta.url);
4
+
5
+ /**
6
+ * The native binary behind oxlint's type-aware rules, or null when this
7
+ * platform has none. oxlint looks for it only in `node_modules/.bin` above the
8
+ * linted directory and on PATH, and a dependency of nk-dev reaches neither
9
+ * (bun's isolated installs link only a project's direct dependencies). So nk
10
+ * resolves it from here, through the platform package oxlint-tsgolint's own
11
+ * wrapper would spawn — the binary, not the wrapper, which needs `node`.
12
+ */
13
+ export function tsgolintPath() {
14
+ const binary = process.platform === "win32" ? "tsgolint.exe" : "tsgolint";
15
+ try {
16
+ const wrapper = createRequire(require.resolve("oxlint-tsgolint/package.json"));
17
+ return wrapper.resolve(
18
+ `@oxlint-tsgolint/${process.platform}-${process.arch}/${binary}`,
19
+ );
20
+ } catch (error) {
21
+ if (error.code === "MODULE_NOT_FOUND") return null;
22
+ throw error;
23
+ }
24
+ }
25
+
26
+ /**
27
+ * The environment for an oxlint run: `env` with `OXLINT_TSGOLINT_PATH` set to
28
+ * the resolved backend. A path the caller set wins. oxlint reads the variable
29
+ * only when the project's config turns on type-aware linting.
30
+ */
31
+ export function lintEnvironment(env = process.env) {
32
+ if (env.OXLINT_TSGOLINT_PATH) return env;
33
+ const path = tsgolintPath();
34
+ return path === null ? env : { ...env, OXLINT_TSGOLINT_PATH: path };
35
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ingram-tech/nk-dev",
3
- "version": "0.18.0",
3
+ "version": "0.19.0",
4
4
  "description": "The nextkit dev toolchain in one package: the `nk` CLI plus shared oxlint/oxfmt, TypeScript, and Vitest config, the format-on-commit hook, and the AI agent guide. `nk init` scaffolds a site to use it.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -46,15 +46,16 @@
46
46
  },
47
47
  "dependencies": {
48
48
  "@ast-grep/cli": "^0.45.3",
49
- "@testing-library/dom": "^10.4.1",
49
+ "@testing-library/dom": "^10.4.2",
50
50
  "@testing-library/jest-dom": "^7.0.1",
51
51
  "@typescript/native": "npm:typescript@^7.0.2",
52
- "jsdom": "^30.0.1",
53
- "knip": "^6.35.1",
54
- "oxfmt": "^0.67.0",
55
- "oxlint": "^1.82.0",
52
+ "jsdom": "^30.1.1",
53
+ "knip": "^6.39.0",
54
+ "oxfmt": "^0.71.0",
55
+ "oxlint": "^1.86.0",
56
+ "oxlint-tsgolint": "^7.0.2003",
56
57
  "typescript": "npm:@typescript/typescript6@^6.0.2",
57
- "vitest": "^5.0.0"
58
+ "vitest": "^5.0.3"
58
59
  },
59
60
  "engines": {
60
61
  "node": "^22.22.2 || ^24.15.0 || >=26.0.0"