docs-cache 0.5.2 → 0.5.4

package/README.md

@@ -102,7 +102,7 @@ These fields can be set in `defaults` and are inherited by every source unless o
 | `ignoreHidden`        | Skip hidden files and directories (dotfiles). Default: `false`.                                                                 |
 | `allowHosts`          | Allowed Git hosts. Default: `["github.com", "gitlab.com", "visualstudio.com"]`.                                                    |
 | `toc`                 | Generate per-source `TOC.md`. Default: `true`. Supports `true`, `false`, or a format: `"tree"` (human readable), `"compressed"` |
-| `unwrapSingleRootDir` | If the materialized output is nested under a single directory, unwrap it (recursively). Default: `false`.                       |
+| `unwrapSingleRootDir` | If the materialized output is nested under a single directory, unwrap it (recursively). Default: `true`.                        |
 
 ### Source options
 

package/dist/esm/cache/materialize.mjs

@@ -121,7 +121,7 @@ const resolveMaterializeParams = (params) => ({
   ...params,
   exclude: params.exclude ?? [],
   ignoreHidden: params.ignoreHidden ?? false,
-  unwrapSingleRootDir: params.unwrapSingleRootDir ?? false,
+  unwrapSingleRootDir: params.unwrapSingleRootDir ?? true,
   json: params.json ?? false,
   progressThrottleMs: params.progressThrottleMs ?? 120
 });

package/dist/esm/config/index.mjs

@@ -19,7 +19,7 @@ export const DEFAULT_CONFIG = {
     ignoreHidden: false,
     allowHosts: ["github.com", "gitlab.com", "visualstudio.com"],
     toc: true,
-    unwrapSingleRootDir: false
+    unwrapSingleRootDir: true
   },
   sources: []
 };

package/dist/esm/git/fetch-source.mjs

@@ -177,35 +177,54 @@ const ensureCommitAvailable = async (repoPath, commit, options) => {
     logger: options?.logger
   });
 };
-const isSparseEligible = (include) => {
-  if (!include || include.length === 0) {
-    return false;
+const patternHasGlob = (pattern) => pattern.includes("*") || pattern.includes("?") || pattern.includes("[");
+const normalizeSparsePatterns = (include) => (include ?? []).map((pattern) => pattern.replace(/\\/g, "/")).filter(Boolean);
+const isDirectoryLiteral = (pattern) => pattern.endsWith("/");
+const toNoConePattern = (pattern) => {
+  if (!patternHasGlob(pattern) && isDirectoryLiteral(pattern)) {
+    return pattern.endsWith("/") ? pattern : `${pattern}/`;
+  }
+  return pattern;
+};
+const resolveSparseSpec = (include) => {
+  const normalized = normalizeSparsePatterns(include);
+  if (normalized.length === 0) {
+    return { enabled: false, mode: "cone", patterns: [] };
   }
-  for (const pattern of include) {
-    if (!pattern || pattern.includes("**")) {
-      return false;
+  const conePaths = [];
+  let coneEligible = true;
+  for (const pattern of normalized) {
+    if (pattern.includes("**")) {
+      coneEligible = false;
+      break;
     }
+    if (patternHasGlob(pattern)) {
+      coneEligible = false;
+      break;
+    }
+    if (isDirectoryLiteral(pattern)) {
+      conePaths.push(pattern.replace(/\/+$/, ""));
+      continue;
+    }
+    coneEligible = false;
+    break;
   }
-  return true;
-};
-const extractSparsePaths = (include) => {
-  if (!include) {
-    return [];
+  const uniquePaths = Array.from(new Set(conePaths.filter(Boolean)));
+  if (coneEligible && uniquePaths.length > 0) {
+    return { enabled: true, mode: "cone", patterns: uniquePaths };
   }
-  const paths = include.map((pattern) => {
-    const normalized = pattern.replace(/\\/g, "/");
-    const starIndex = normalized.indexOf("*");
-    const base = starIndex === -1 ? normalized : normalized.slice(0, starIndex);
-    return base.replace(/\/+$|\/$/, "");
-  });
-  return Array.from(new Set(paths.filter((value) => value.length > 0)));
+  return {
+    enabled: true,
+    mode: "no-cone",
+    patterns: normalized.map(toNoConePattern)
+  };
 };
 const cloneRepo = async (params, outDir) => {
   if (params.offline) {
     throw new Error(`Cannot clone ${params.repo} while offline.`);
   }
   const isCommitRef = /^[0-9a-f]{7,40}$/i.test(params.ref);
-  const useSparse = isSparseEligible(params.include);
+  const sparseSpec = resolveSparseSpec(params.include);
   const buildCloneArgs = () => {
     const cloneArgs2 = [
       "clone",
@@ -218,7 +237,7 @@ const cloneRepo = async (params, outDir) => {
     return cloneArgs2;
   };
   const cloneArgs = buildCloneArgs();
-  if (useSparse) {
+  if (sparseSpec.enabled) {
     cloneArgs.push("--sparse");
   }
   if (!isCommitRef) {
@@ -239,14 +258,16 @@ const cloneRepo = async (params, outDir) => {
     logger: params.logger,
     offline: params.offline
   });
-  if (useSparse) {
-    const sparsePaths = extractSparsePaths(params.include);
-    if (sparsePaths.length > 0) {
-      await git(["-C", outDir, "sparse-checkout", "set", ...sparsePaths], {
-        timeoutMs: params.timeoutMs,
-        logger: params.logger
-      });
+  if (sparseSpec.enabled) {
+    const sparseArgs = ["-C", outDir, "sparse-checkout", "set"];
+    if (sparseSpec.mode === "no-cone") {
+      sparseArgs.push("--no-cone");
     }
+    sparseArgs.push(...sparseSpec.patterns);
+    await git(sparseArgs, {
+      timeoutMs: params.timeoutMs,
+      logger: params.logger
+    });
   }
   await git(
     ["-C", outDir, "checkout", "--quiet", "--detach", params.resolvedCommit],
@@ -281,9 +302,14 @@ const addWorktreeFromCache = async (params, cachePath, outDir) => {
       allowFileProtocol: true
     }
   );
-  const sparsePaths = isSparseEligible(params.include) ? extractSparsePaths(params.include) : [];
-  if (sparsePaths.length > 0) {
-    await git(["-C", outDir, "sparse-checkout", "set", ...sparsePaths], {
+  const sparseSpec = resolveSparseSpec(params.include);
+  if (sparseSpec.enabled) {
+    const sparseArgs = ["-C", outDir, "sparse-checkout", "set"];
+    if (sparseSpec.mode === "no-cone") {
+      sparseArgs.push("--no-cone");
+    }
+    sparseArgs.push(...sparseSpec.patterns);
+    await git(sparseArgs, {
       timeoutMs: params.timeoutMs,
       logger: params.logger,
       allowFileProtocol: true
@@ -380,7 +406,7 @@ const cloneOrUpdateRepo = async (params, outDir) => {
   const cacheExists = await exists(cachePath);
   const cacheValid = cacheExists && await isValidGitRepo(cachePath);
   const isCommitRef = /^[0-9a-f]{7,40}$/i.test(params.ref);
-  const useSparse = isSparseEligible(params.include);
+  const sparseSpec = resolveSparseSpec(params.include);
   let usedCache = cacheValid;
   let worktreeUsed = false;
   const cacheRoot = resolveGitCacheDir();
@@ -410,7 +436,7 @@ const cloneOrUpdateRepo = async (params, outDir) => {
   if (await isPartialClone(cachePath)) {
     localCloneArgs.splice(2, 0, "--filter=blob:none");
   }
-  if (useSparse) {
+  if (sparseSpec.enabled) {
     localCloneArgs.push("--sparse");
   }
   if (!isCommitRef) {
@@ -428,15 +454,17 @@ const cloneOrUpdateRepo = async (params, outDir) => {
     progressLogger: params.progressLogger,
     forceProgress: Boolean(params.progressLogger)
   });
-  if (useSparse) {
-    const sparsePaths = extractSparsePaths(params.include);
-    if (sparsePaths.length > 0) {
-      await git(["-C", outDir, "sparse-checkout", "set", ...sparsePaths], {
-        timeoutMs: params.timeoutMs,
-        allowFileProtocol: true,
-        logger: params.logger
-      });
+  if (sparseSpec.enabled) {
+    const sparseArgs = ["-C", outDir, "sparse-checkout", "set"];
+    if (sparseSpec.mode === "no-cone") {
+      sparseArgs.push("--no-cone");
     }
+    sparseArgs.push(...sparseSpec.patterns);
+    await git(sparseArgs, {
+      timeoutMs: params.timeoutMs,
+      allowFileProtocol: true,
+      logger: params.logger
+    });
   }
   await ensureCommitAvailable(outDir, params.resolvedCommit, {
     timeoutMs: params.timeoutMs,

package/dist/esm/source-id.mjs

@@ -1,4 +1,5 @@
-const SAFE_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+const INVALID_ID_PATTERN = /[<>:"/\\|?*]/;
+const TRAILING_DOT_SPACE_PATTERN = /[.\s]+$/;
 const MAX_ID_LENGTH = 200;
 const RESERVED_NAMES = /* @__PURE__ */ new Set([
   ".",
@@ -14,15 +15,28 @@ export const assertSafeSourceId = (value, label) => {
   if (typeof value !== "string" || value.length === 0) {
     throw new Error(`${label} must be a non-empty string.`);
   }
+  if (value.trim().length === 0) {
+    throw new Error(`${label} must not be blank.`);
+  }
   if (value.length > MAX_ID_LENGTH) {
     throw new Error(`${label} exceeds maximum length of ${MAX_ID_LENGTH}.`);
   }
-  if (!SAFE_ID_PATTERN.test(value)) {
+  for (const char of value) {
+    const code = char.codePointAt(0);
+    if (code !== void 0 && (code <= 31 || code === 127)) {
+      throw new Error(`${label} must not contain control characters.`);
+    }
+  }
+  if (TRAILING_DOT_SPACE_PATTERN.test(value)) {
+    throw new Error(`${label} must not end with dots or spaces.`);
+  }
+  if (INVALID_ID_PATTERN.test(value) || value.includes("\0")) {
     throw new Error(
-      `${label} must contain only alphanumeric characters, hyphens, and underscores.`
+      `${label} must not contain path separators or reserved characters (< > : " / \\ | ? *).`
     );
   }
-  if (RESERVED_NAMES.has(value.toUpperCase())) {
+  const normalized = value.replace(/[.\s]+$/g, "");
+  if (RESERVED_NAMES.has(normalized.toUpperCase())) {
     throw new Error(`${label} uses reserved name '${value}'.`);
   }
   return value;

package/package.json

@@ -1,136 +1,139 @@
 {
-  "name": "docs-cache",
-  "private": false,
-  "type": "module",
-  "version": "0.5.2",
-  "description": "CLI for deterministic local caching of external documentation for agents and tools",
-  "author": "Frederik Bosch",
-  "license": "MIT",
-  "homepage": "https://github.com/fbosch/docs-cache#readme",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/fbosch/docs-cache.git"
-  },
-  "bugs": {
-    "url": "https://github.com/fbosch/docs-cache/issues"
-  },
-  "keywords": [
-    "docs",
-    "documentation",
-    "cache",
-    "agent",
-    "ai",
-    "git",
-    "cli"
-  ],
-  "sideEffects": false,
-  "engines": {
-    "node": ">=18"
-  },
-  "bin": {
-    "docs-cache": "./bin/docs-cache.mjs"
-  },
-  "files": [
-    "bin",
-    "dist/cli.mjs",
-    "dist/esm/**/*.mjs",
-    "dist/esm/**/*.d.ts",
-    "dist/lock.mjs",
-    "dist/shared/*.mjs",
-    "README.md",
-    "LICENSE"
-  ],
-  "imports": {
-    "#cache/*": {
-      "types": "./dist/esm/cache/*.d.ts",
-      "default": "./dist/esm/cache/*.mjs"
-    },
-    "#cli/*": {
-      "types": "./dist/esm/cli/*.d.ts",
-      "default": "./dist/esm/cli/*.mjs"
-    },
-    "#commands/*": {
-      "types": "./dist/esm/commands/*.d.ts",
-      "default": "./dist/esm/commands/*.mjs"
-    },
-    "#core/*": {
-      "types": "./dist/esm/*.d.ts",
-      "default": "./dist/esm/*.mjs"
-    },
-    "#config": {
-      "types": "./dist/esm/config/index.d.ts",
-      "default": "./dist/esm/config/index.mjs"
-    },
-    "#config/*": {
-      "types": "./dist/esm/config/*.d.ts",
-      "default": "./dist/esm/config/*.mjs"
-    },
-    "#git/*": {
-      "types": "./dist/esm/git/*.d.ts",
-      "default": "./dist/esm/git/*.mjs"
-    },
-    "#types/*": {
-      "types": "./dist/esm/types/*.d.ts",
-      "default": "./dist/esm/types/*.mjs"
-    }
-  },
-  "dependencies": {
-    "@clack/prompts": "^1.0.0",
-    "cac": "^6.7.14",
-    "cli-truncate": "^4.0.0",
-    "execa": "^9.6.1",
-    "fast-glob": "^3.3.2",
-    "log-update": "^7.0.2",
-    "picocolors": "^1.1.1",
-    "picomatch": "^4.0.3",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.3.14",
-    "@size-limit/file": "^12.0.0",
-    "@types/node": "^25.2.0",
-    "bumpp": "^10.3.2",
-    "c8": "^10.1.3",
-    "jiti": "^2.5.1",
-    "lint-staged": "^16.2.7",
-    "simple-git-hooks": "^2.13.1",
-    "size-limit": "^12.0.0",
-    "tinybench": "^6.0.0",
-    "ts-complex": "^1.0.0",
-    "typescript": "^5.9.3",
-    "unbuild": "^3.6.1"
-  },
-  "size-limit": [
-    {
-      "path": "dist/cli.mjs",
-      "limit": "10 kB"
-    }
-  ],
-  "complexity": {
-    "maxCyclomatic": 20,
-    "minMaintainability": 60,
-    "top": 10
-  },
-  "simple-git-hooks": {
-    "pre-commit": "pnpm lint-staged && pnpm typecheck"
-  },
-  "lint-staged": {
-    "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}": [
-      "biome check --write --no-errors-on-unmatched"
-    ]
-  },
-  "scripts": {
-    "build": "unbuild",
-    "dev": "unbuild --stub",
-    "lint": "biome check .",
-    "release": "pnpm run lint && pnpm run typecheck && bumpp && pnpm publish --access public",
-    "test": "pnpm build && node --test",
-    "test:coverage": "pnpm build && c8 --include dist --exclude bin --reporter=text node --test",
-    "bench": "pnpm build && node scripts/benchmarks/run.mjs",
-    "complexity": "node scripts/complexity/run.mjs",
-    "schema:build": "node scripts/generate-schema.mjs",
-    "size": "size-limit",
-    "test:watch": "node --test --watch",
-    "typecheck": "tsc --noEmit"
-  }
-}
+	"name": "docs-cache",
+	"private": false,
+	"type": "module",
+	"version": "0.5.4",
+	"packageManager": "pnpm@10.14.0+sha512.ad27a79641b49c3e481a16a805baa71817a04bbe06a38d17e60e2eaee83f6a146c6a688125f5792e48dd5ba30e7da52a5cda4c3992b9ccf333f9ce223af84748",
+	"description": "CLI for deterministic local caching of external documentation for agents and tools",
+	"author": "Frederik Bosch",
+	"license": "MIT",
+	"homepage": "https://github.com/fbosch/docs-cache#readme",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/fbosch/docs-cache.git"
+	},
+	"bugs": {
+		"url": "https://github.com/fbosch/docs-cache/issues"
+	},
+	"keywords": [
+		"docs",
+		"documentation",
+		"cache",
+		"agent",
+		"ai",
+		"git",
+		"cli"
+	],
+	"sideEffects": false,
+	"engines": {
+		"node": ">=18"
+	},
+	"bin": {
+		"docs-cache": "./bin/docs-cache.mjs"
+	},
+	"files": [
+		"bin",
+		"dist/cli.mjs",
+		"dist/esm/**/*.mjs",
+		"dist/esm/**/*.d.ts",
+		"dist/lock.mjs",
+		"dist/shared/*.mjs",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"build": "unbuild",
+		"dev": "unbuild --stub",
+		"lint": "biome check .",
+		"prepublishOnly": "pnpm audit --audit-level=high && pnpm build && pnpm size && pnpm schema:build",
+		"release": "pnpm run lint && pnpm run typecheck && bumpp && pnpm publish --access public",
+		"test": "pnpm build && node --test",
+		"test:coverage": "pnpm build && c8 --include dist --exclude bin --reporter=text node --test",
+		"bench": "pnpm build && node scripts/benchmarks/run.mjs",
+		"complexity": "node scripts/complexity/run.mjs",
+		"schema:build": "node scripts/generate-schema.mjs",
+		"size": "size-limit",
+		"test:watch": "node --test --watch",
+		"typecheck": "tsc --noEmit",
+		"prepare": "simple-git-hooks"
+	},
+	"imports": {
+		"#cache/*": {
+			"types": "./dist/esm/cache/*.d.ts",
+			"default": "./dist/esm/cache/*.mjs"
+		},
+		"#cli/*": {
+			"types": "./dist/esm/cli/*.d.ts",
+			"default": "./dist/esm/cli/*.mjs"
+		},
+		"#commands/*": {
+			"types": "./dist/esm/commands/*.d.ts",
+			"default": "./dist/esm/commands/*.mjs"
+		},
+		"#core/*": {
+			"types": "./dist/esm/*.d.ts",
+			"default": "./dist/esm/*.mjs"
+		},
+		"#config": {
+			"types": "./dist/esm/config/index.d.ts",
+			"default": "./dist/esm/config/index.mjs"
+		},
+		"#config/*": {
+			"types": "./dist/esm/config/*.d.ts",
+			"default": "./dist/esm/config/*.mjs"
+		},
+		"#git/*": {
+			"types": "./dist/esm/git/*.d.ts",
+			"default": "./dist/esm/git/*.mjs"
+		},
+		"#types/*": {
+			"types": "./dist/esm/types/*.d.ts",
+			"default": "./dist/esm/types/*.mjs"
+		}
+	},
+	"dependencies": {
+		"@clack/prompts": "^1.0.0",
+		"cac": "^6.7.14",
+		"cli-truncate": "^4.0.0",
+		"execa": "^9.6.1",
+		"fast-glob": "^3.3.2",
+		"log-update": "^7.0.2",
+		"picocolors": "^1.1.1",
+		"picomatch": "^4.0.3",
+		"zod": "^4.3.6"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.14",
+		"@size-limit/file": "^12.0.0",
+		"@types/node": "^25.2.0",
+		"bumpp": "^10.3.2",
+		"c8": "^10.1.3",
+		"jiti": "^2.5.1",
+		"lint-staged": "^16.2.7",
+		"simple-git-hooks": "^2.13.1",
+		"size-limit": "^12.0.0",
+		"tinybench": "^6.0.0",
+		"ts-complex": "^1.0.0",
+		"typescript": "^5.9.3",
+		"unbuild": "^3.6.1"
+	},
+	"size-limit": [
+		{
+			"path": "dist/cli.mjs",
+			"limit": "10 kB"
+		}
+	],
+	"complexity": {
+		"maxCyclomatic": 20,
+		"minMaintainability": 60,
+		"top": 10
+	},
+	"simple-git-hooks": {
+		"pre-commit": "pnpm lint-staged && pnpm typecheck"
+	},
+	"lint-staged": {
+		"*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}": [
+			"biome check --write --no-errors-on-unmatched"
+		]
+	}
+}