feat: use node_modules/.cache/nadle as default cache directory (#546)

nam-hle · claude · web-flow · commit 276116b5dd87 · 2026-02-24T23:03:47.000+07:00
## Summary - Change default cache directory from `.nadle/` to `node_modules/.cache/nadle/` to align with JS ecosystem conventions (Turborepo, Nx, ESLint, Vite, Babel, Webpack) - Already gitignored via `node_modules/`, cleaned on fresh install, less project root clutter - `--cache-dir` CLI flag and `configure({ cacheDir })` override continue to work as before Closes #500 ## Test plan - [ ] CI passes on all platforms (Ubuntu, macOS, Windows) - [ ] `cache-dir`, `clean-cache`, and `no-cache` tests verify the new default path - [ ] Snapshots updated for `--show-config` and `--help` output reflecting new default 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
diff --git a/.gitignore b/.gitignore
@@ -17,6 +17,7 @@ nadle.iml
 __temp__
 .docusaurus
 .vercel
+# legacy cache directory (before v0.6)
 .nadle*
 
 # generated docs
diff --git a/packages/docs/docs/getting-started/features.md b/packages/docs/docs/getting-started/features.md
@@ -142,7 +142,7 @@ tasks.register("deploy", async ({ context }) => {
 Nadle caches task results based on declared inputs and outputs. When inputs haven't changed since the last run, the task is skipped and outputs are restored from cache.
 
 - Declare file and directory inputs/outputs
-- Cache stored in `.nadle/` directory
+- Cache stored in `node_modules/.cache/nadle/` directory
 - Skip with `--no-cache` flag
 
 ```typescript
diff --git a/packages/nadle/package.json b/packages/nadle/package.json
@@ -8,6 +8,7 @@
 		"build": "nadle build",
 		"start": "tsc -p tsconfig.build.json --watch --noEmit false",
 		"test": "nadle test",
+		"update": "vitest -u",
 		"bench": "vitest bench"
 	},
 	"files": [
diff --git a/packages/nadle/src/core/options/cli-options.ts b/packages/nadle/src/core/options/cli-options.ts
@@ -102,7 +102,7 @@ export const CLIOptions = {
 		key: "cache-dir",
 		options: {
 			type: "string",
-			defaultDescription: "<projectDir>/.nadle",
+			defaultDescription: "<projectDir>/node_modules/.cache/nadle",
 			description: "Directory to store task cache results"
 		}
 	},
diff --git a/packages/nadle/src/core/utilities/constants.ts b/packages/nadle/src/core/utilities/constants.ts
@@ -22,4 +22,4 @@ export const LINES = {
 	VERTICAL_RIGHT: "├"
 };
 
-export const DEFAULT_CACHE_DIR_NAME = ".nadle";
+export const DEFAULT_CACHE_DIR_NAME = "node_modules/.cache/nadle";
diff --git a/packages/nadle/test/__snapshots__/builtin-tasks/delete-task.test.ts.snap b/packages/nadle/test/__snapshots__/builtin-tasks/delete-task.test.ts.snap
@@ -130,7 +130,7 @@ Command: /ROOT/nadle.mjs --max-workers 1 --no-footer deleteJsonFiles --log-level
     "packageManager": "npm",
     "currentWorkspaceId": "root"
   },
-  "cacheDir": "/ROOT/test/__fixtures__/delete-task/__temp__/__{hash}__/.nadle",
+  "cacheDir": "/ROOT/test/__fixtures__/delete-task/__temp__/__{hash}__/node_modules/.cache/nadle",
   "minWorkers": 1
 }
 [info] Detected environments: { CI: false, TEST: true }
diff --git a/packages/nadle/test/__snapshots__/builtin-tasks/node-task.test.ts.snap b/packages/nadle/test/__snapshots__/builtin-tasks/node-task.test.ts.snap
@@ -58,7 +58,7 @@ Command: /ROOT/nadle.mjs --max-workers 1 --no-footer pass --log-level info
     "packageManager": "npm",
     "currentWorkspaceId": "root"
   },
-  "cacheDir": "/ROOT/test/__fixtures__/node-task/.nadle",
+  "cacheDir": "/ROOT/test/__fixtures__/node-task/node_modules/.cache/nadle",
   "minWorkers": 1
 }
 [info] Detected environments: { CI: false, TEST: true }
diff --git a/packages/nadle/test/__snapshots__/builtin-tasks/npm-task.test.ts.snap b/packages/nadle/test/__snapshots__/builtin-tasks/npm-task.test.ts.snap
@@ -58,7 +58,7 @@ Command: /ROOT/nadle.mjs --max-workers 1 --no-footer pass --log-level info
     "packageManager": "npm",
     "currentWorkspaceId": "root"
   },
-  "cacheDir": "/ROOT/test/__fixtures__/npm-task/.nadle",
+  "cacheDir": "/ROOT/test/__fixtures__/npm-task/node_modules/.cache/nadle",
   "minWorkers": 1
 }
 [info] Detected environments: { CI: false, TEST: true }
diff --git a/packages/nadle/test/__snapshots__/builtin-tasks/npx-task.test.ts.snap b/packages/nadle/test/__snapshots__/builtin-tasks/npx-task.test.ts.snap
@@ -58,7 +58,7 @@ Command: /ROOT/nadle.mjs --max-workers 1 --no-footer pass --log-level info
     "packageManager": "npm",
     "currentWorkspaceId": "root"
   },
-  "cacheDir": "/ROOT/test/__fixtures__/npx-task/.nadle",
+  "cacheDir": "/ROOT/test/__fixtures__/npx-task/node_modules/.cache/nadle",
   "minWorkers": 1
 }
 [info] Detected environments: { CI: false, TEST: true }
diff --git a/packages/nadle/test/__snapshots__/builtin-tasks/pnpm-task.test.ts.snap b/packages/nadle/test/__snapshots__/builtin-tasks/pnpm-task.test.ts.snap
@@ -58,7 +58,7 @@ Command: /ROOT/nadle.mjs --max-workers 1 --no-footer pass --log-level info
     "packageManager": "npm",
     "currentWorkspaceId": "root"
   },
-  "cacheDir": "/ROOT/test/__fixtures__/pnpm-task/.nadle",
+  "cacheDir": "/ROOT/test/__fixtures__/pnpm-task/node_modules/.cache/nadle",
   "minWorkers": 1
 }
 [info] Detected environments: { CI: false, TEST: true }
diff --git a/packages/nadle/test/__snapshots__/builtin-tasks/pnpx-task.test.ts.snap b/packages/nadle/test/__snapshots__/builtin-tasks/pnpx-task.test.ts.snap
@@ -58,7 +58,7 @@ Command: /ROOT/nadle.mjs --max-workers 1 --no-footer pass --log-level info
     "packageManager": "npm",
     "currentWorkspaceId": "root"
   },
-  "cacheDir": "/ROOT/test/__fixtures__/pnpx-task/.nadle",
+  "cacheDir": "/ROOT/test/__fixtures__/pnpx-task/node_modules/.cache/nadle",
   "minWorkers": 1
 }
 [info] Detected environments: { CI: false, TEST: true }
diff --git a/packages/nadle/test/__snapshots__/options/config-key.test.ts.snap b/packages/nadle/test/__snapshots__/options/config-key.test.ts.snap
@@ -47,7 +47,7 @@ Command: /ROOT/nadle.mjs --max-workers 1 --no-footer --show-config --config-key
     "packageManager": "npm",
     "currentWorkspaceId": "root"
   },
-  "cacheDir": "/ROOT/test/__fixtures__/main/.nadle",
+  "cacheDir": "/ROOT/test/__fixtures__/main/node_modules/.cache/nadle",
   "minWorkers": 1
 }
 `;
diff --git a/packages/nadle/test/__snapshots__/options/help.test.ts.snap b/packages/nadle/test/__snapshots__/options/help.test.ts.snap
@@ -27,7 +27,8 @@ Execution options:
 
 General options:
   -c, --config       Path to config file      [string] [default: <cwd>/nadle.config.{js,mjs,ts,mts}]
-      --cache-dir    Directory to store task cache results   [string] [default: <projectDir>/.nadle]
+      --cache-dir    Directory to store task cache results
+                                          [string] [default: <projectDir>/node_modules/.cache/nadle]
       --log-level    Set the logging level
                                   [string] [choices: "error", "log", "info", "debug"] [default: log]
       --min-workers  Minimum number of workers (integer or percentage)
diff --git a/packages/nadle/test/__snapshots__/options/show-config.test.ts.snap b/packages/nadle/test/__snapshots__/options/show-config.test.ts.snap
@@ -52,7 +52,7 @@ Command: /ROOT/nadle.mjs --max-workers 1 --no-footer hello --show-config
     "packageManager": "npm",
     "currentWorkspaceId": "root"
   },
-  "cacheDir": "/ROOT/test/__fixtures__/main/.nadle",
+  "cacheDir": "/ROOT/test/__fixtures__/main/node_modules/.cache/nadle",
   "minWorkers": 1
 }
 `;
@@ -110,6 +110,6 @@ Command: /ROOT/nadle.mjs --no-footer hello --show-config --min-workers 2 --max-w
     "packageManager": "npm",
     "currentWorkspaceId": "root"
   },
-  "cacheDir": "/ROOT/test/__fixtures__/main/.nadle"
+  "cacheDir": "/ROOT/test/__fixtures__/main/node_modules/.cache/nadle"
 }
 `;
diff --git a/packages/nadle/test/__snapshots__/options/stacktrace.test.ts.snap b/packages/nadle/test/__snapshots__/options/stacktrace.test.ts.snap
@@ -17,10 +17,10 @@ Command: /ROOT/nadle.mjs --max-workers 1 --no-footer throwable --stacktrace
 
 [log]
 <Green>✓</Green> Task <Bold>hello</BoldDim> <Green>DONE</Green> <Dim>{duration}</BoldDim>
-[log] <Yellow>></Yellow> Task <Bold>throwable</BoldDim> <Yellow>STARTED</Yellow>
-
 [log]
 <Red>×</Red> Task <Bold>throwable</BoldDim> <Red>FAILED</Red> {duration}
+[log] <Yellow>></Yellow> Task <Bold>throwable</BoldDim> <Yellow>STARTED</Yellow>
+
 [log]
 <Bold><Red>RUN FAILED</Red></BoldDim> in <Bold>{duration}</BoldDim> <Dim>(<Bold>2</BoldDim><Dim> tasks executed, <Bold>1</BoldDim><Dim> task failed)</BoldDim>
 ---------- Stderr ------------
diff --git a/packages/nadle/test/options/cache-dir.test.ts b/packages/nadle/test/options/cache-dir.test.ts
@@ -5,7 +5,7 @@ import { it, expect, describe } from "vitest";
 
 import { isPathExists } from "../../src/core/utilities/fs.js";
 
-const DEFAULT_CACHE_DIR = ".nadle";
+const DEFAULT_CACHE_DIR = "node_modules/.cache/nadle";
 const VIA_FILE_CACHE_DIR = ".nadle-custom-by-file";
 const VIA_CLI_CACHE_DIR = ".nadle-custom-by-cli";
 
diff --git a/packages/nadle/test/options/clean-cache.test.ts b/packages/nadle/test/options/clean-cache.test.ts
@@ -11,7 +11,7 @@ const files = fixture()
 	.file("input.txt", "input")
 	.build();
 
-const DEFAULT_CACHE_DIR = ".nadle";
+const DEFAULT_CACHE_DIR = "node_modules/.cache/nadle";
 const CUSTOM_CACHE_DIR = ".nadle-custom";
 
 const cacheDirNames = [DEFAULT_CACHE_DIR, CUSTOM_CACHE_DIR];
diff --git a/packages/nadle/test/options/no-cache.test.ts b/packages/nadle/test/options/no-cache.test.ts
@@ -24,23 +24,23 @@ describe.concurrent("--no-cache", () => {
 		expect(await getStdout(exec`--cache --show-config`)).contain(`"cache": true`);
 	});
 
-	it("should create the .nadle directory by default", () =>
+	it("should create the node_modules/.cache/nadle directory by default", () =>
 		withGeneratedFixture({
 			files: noCacheFiles,
 			testFn: async ({ cwd, exec }) => {
 				await expect(getStdout(exec`bundle`)).resolves.toSettle("bundle", "done");
 				await expect(getStdout(exec`bundle`)).resolves.toSettle("bundle", "up-to-date");
-				await expect(isPathExists(Path.join(cwd, ".nadle"))).resolves.toBe(true);
+				await expect(isPathExists(Path.join(cwd, "node_modules/.cache/nadle"))).resolves.toBe(true);
 			}
 		}));
 
-	it("should not create the .nadle directory when specifying --no-cache", () =>
+	it("should not create the node_modules/.cache/nadle directory when specifying --no-cache", () =>
 		withGeneratedFixture({
 			files: noCacheFiles,
 			testFn: async ({ cwd, exec }) => {
 				await expect(getStdout(exec`bundle --no-cache`)).resolves.toSettle("bundle", "done");
 				await expect(getStdout(exec`bundle --no-cache`)).resolves.toSettle("bundle", "done");
-				await expect(isPathExists(Path.join(cwd, ".nadle"))).resolves.toBe(false);
+				await expect(isPathExists(Path.join(cwd, "node_modules/.cache/nadle"))).resolves.toBe(false);
 			}
 		}));
 });
diff --git a/spec/05-caching.md b/spec/05-caching.md
@@ -89,7 +89,7 @@ Multiple reasons may be reported for a single cache miss.
 
 ## Storage Layout
 
-Cache data is stored under the cache directory (default: `.nadle/`):
+Cache data is stored under the cache directory (default: `node_modules/.cache/nadle/`):
 
 ```
 {cacheDir}/
diff --git a/spec/CHANGELOG.md b/spec/CHANGELOG.md
@@ -8,6 +8,13 @@ Versioning follows [Semantic Versioning](https://semver.org/):
 - **MINOR**: New concept, new section, or materially expanded rules
 - **PATCH**: Clarifications, corrections, wording improvements
 
+## 1.5.1 — 2026-02-24
+
+### Changed
+
+- 05-caching: Default cache directory changed from `.nadle/` to
+  `node_modules/.cache/nadle/` to align with JS ecosystem conventions.
+
 ## 1.5.0 — 2026-02-22
 
 ### Added
diff --git a/spec/README.md b/spec/README.md
@@ -1,6 +1,6 @@
 # Nadle Specification
 
-**Version**: 1.5.0
+**Version**: 1.5.1
 
 This directory contains the language-agnostic specification for Nadle, a type-safe,
 Gradle-inspired task runner for Node.js.

Original file line number	Diff line number	Diff line change
`@@ -102,7 +102,7 @@ export const CLIOptions = {`
`102`	`102`	`key: "cache-dir",`
`103`	`103`	`options: {`
`104`	`104`	`type: "string",`
`105`		`- defaultDescription: "<projectDir>/.nadle",`
	`105`	`+ defaultDescription: "<projectDir>/node_modules/.cache/nadle",`
`106`	`106`	`description: "Directory to store task cache results"`
`107`	`107`	`}`
`108`	`108`	`},`
Original file line number	Diff line number	Diff line change
`@@ -130,7 +130,7 @@ Command: /ROOT/nadle.mjs --max-workers 1 --no-footer deleteJsonFiles --log-level`
`130`	`130`	`"packageManager": "npm",`
`131`	`131`	`"currentWorkspaceId": "root"`
`132`	`132`	`},`
`133`		`- "cacheDir": "/ROOT/test/__fixtures__/delete-task/__temp__/__{hash}__/.nadle",`
	`133`	`+ "cacheDir": "/ROOT/test/__fixtures__/delete-task/__temp__/__{hash}__/node_modules/.cache/nadle",`
`134`	`134`	`"minWorkers": 1`
`135`	`135`	`}`
`136`	`136`	`[info] Detected environments: { CI: false, TEST: true }`
Original file line number	Diff line number	Diff line change
`@@ -58,7 +58,7 @@ Command: /ROOT/nadle.mjs --max-workers 1 --no-footer pass --log-level info`
`58`	`58`	`"packageManager": "npm",`
`59`	`59`	`"currentWorkspaceId": "root"`
`60`	`60`	`},`
`61`		`- "cacheDir": "/ROOT/test/__fixtures__/node-task/.nadle",`
	`61`	`+ "cacheDir": "/ROOT/test/__fixtures__/node-task/node_modules/.cache/nadle",`
`62`	`62`	`"minWorkers": 1`
`63`	`63`	`}`
`64`	`64`	`[info] Detected environments: { CI: false, TEST: true }`