@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 +10 -5
- package/lib/agent-guide.js +59 -20
- package/lib/doctor.js +10 -26
- package/lib/init.js +3 -20
- package/lib/passthrough.js +10 -4
- package/lib/tsgolint.js +35 -0
- package/package.json +8 -7
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
|
|
85
|
-
|
|
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
|
|
117
|
-
|
|
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`
|
package/lib/agent-guide.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
42
|
-
if (
|
|
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
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
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
|
-
|
|
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
|
|
185
|
-
if (
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
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");
|
package/lib/passthrough.js
CHANGED
|
@@ -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(
|
|
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 =
|
|
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
|
-
|
|
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/`
|
package/lib/tsgolint.js
ADDED
|
@@ -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.
|
|
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.
|
|
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.
|
|
53
|
-
"knip": "^6.
|
|
54
|
-
"oxfmt": "^0.
|
|
55
|
-
"oxlint": "^1.
|
|
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.
|
|
58
|
+
"vitest": "^5.0.3"
|
|
58
59
|
},
|
|
59
60
|
"engines": {
|
|
60
61
|
"node": "^22.22.2 || ^24.15.0 || >=26.0.0"
|