docs-cache 0.5.4 → 0.5.6

package/README.md

@@ -27,31 +27,38 @@ Documentation is cached in a gitignored location, exposed to agent and tool targ
 # Initialize (optional)
 npx docs-cache init
 
-# Add Sources
+# Add source(s)
 npx docs-cache add github:owner/repo#main
-npx docs-cache add gitlab:framework/core
-npx docs-cache add https://github.com/framework/core.git
-npx docs-cache add framework/core framework/other-repo
 
-# Sync
+# Sync and lock
 npx docs-cache sync
+npx docs-cache sync --frozen
 
-# Verify Integrity
-npx docs-cache verify
-
-# Check Status
-npx docs-cache status
+# Refresh tracked refs (write lock/materialized output)
+npx docs-cache update <source-id>
+npx docs-cache update --all --dry-run
 
-# Removal
-npx docs-cache remove core
-npx docs-cache remove framework/other-repo --prune
+# Optional: pin config ref(s) to commit SHA
+npx docs-cache pin <source-id>
 
-# Clean
+# Inspect / maintain
+npx docs-cache verify
+npx docs-cache status
+npx docs-cache remove <source-id>
 npx docs-cache clean
 ```
 
 > for more options: `npx docs-cache --help`
 
+## Recommended Workflow
+
+Use this flow to keep behavior predictable (similar to package manager manifest + lock workflows):
+
+1. Keep source intent in config (`ref: "main"`, `ref: "v1"`, or a commit SHA).
+2. Run `npx docs-cache update <id...>` (or `--all`) to refresh selected sources and lock data.
+3. Use `npx docs-cache sync --frozen` in CI to fail fast when lock data drifts.
+4. Use `npx docs-cache pin <id...>` only when you explicitly want to rewrite config refs to commit SHAs.
+
 ## Configuration
 
 `docs.config.json` at project root (or a `docs-cache` field in `package.json`):
@@ -100,10 +107,12 @@ These fields can be set in `defaults` and are inherited by every source unless o
 | `maxBytes`            | Maximum total bytes to materialize. Default: `200000000` (200 MB).                                                              |
 | `maxFiles`            | Maximum total files to materialize.                                                                                             |
 | `ignoreHidden`        | Skip hidden files and directories (dotfiles). Default: `false`.                                                                 |
-| `allowHosts`          | Allowed Git hosts. Default: `["github.com", "gitlab.com", "visualstudio.com"]`.                                                    |
+| `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: `true`.                        |
 
+> Brace expansion in `include` supports comma-separated lists (including multiple groups) like `**/*.{md,mdx}` and is capped at 500 expanded patterns per include entry. It does not support nested braces or numeric ranges.
+
 ### Source options
 
 #### Required

package/dist/cli.mjs

@@ -1,9 +1,11 @@
-import p from"node:path";import r from"node:process";import d from"picocolors";import{ExitCode as l}from"#cli/exit-code";import{parseArgs as w}from"#cli/parse-args";import{setSilentMode as y,setVerboseMode as v,symbols as a,ui as o}from"#cli/ui";const h="docs-cache",j=`
-Usage: ${h} <command> [options]
+import l from"node:path";import a from"node:process";import d from"picocolors";import{ExitCode as g}from"#cli/exit-code";import{parseArgs as w}from"#cli/parse-args";import{setSilentMode as y,setVerboseMode as v,symbols as r,ui as o}from"#cli/ui";const u="docs-cache",j=`
+Usage: ${u} <command> [options]
 
 Commands:
   add         Add sources to the config (supports github:org/repo#ref)
   remove      Remove sources from the config and targets
+  pin         Pin source refs to current commits
+  update      Refresh selected sources and lock data
   sync        Synchronize cache with config
   status      Show cache status
   clean       Remove project cache
@@ -15,6 +17,7 @@ Commands:
 Global options:
   --config <path>
   --cache-dir <path>
+  --frozen
   --offline
   --fail-on-miss
   --lock-only
@@ -29,15 +32,25 @@ Add options:
   --target <dir>
   --target-dir <path>
   --id <id>
-`,f=()=>{r.stdout.write(j.trimStart())},m=i=>{r.stderr.write(`${a.error} ${i}
-`)},O=async i=>{const e=i.options,{addSources:s}=await import("#commands/add"),{runSync:n}=await import("#commands/sync");if(i.entries.length===0)throw new Error("Usage: docs-cache add [--source <repo> --target <dir>] <repo...>");const t=await s({configPath:e.config,entries:i.entries});if(e.offline?e.json||o.line(`${a.warn} Offline: skipped sync`):await n({configPath:e.config,cacheDirOverride:e.cacheDir,json:e.json,lockOnly:e.lockOnly,offline:e.offline,failOnMiss:e.failOnMiss,sourceFilter:t.sources.map(c=>c.id),timeoutMs:e.timeoutMs,verbose:e.verbose}),e.json){r.stdout.write(`${JSON.stringify(t,null,2)}
-`);return}for(const c of t.sources){const g=c.repo.replace(/^https?:\/\//,"").replace(/\.git$/,""),$=c.targetDir?` ${d.dim("->")} ${d.magenta(c.targetDir)}`:"";o.item(a.success,c.id,`${d.blue(g)}${$}`)}t.skipped?.length&&o.line(`${a.warn} Skipped ${t.skipped.length} existing source${t.skipped.length===1?"":"s"}: ${t.skipped.join(", ")}`),o.line(`${a.info} Updated ${d.gray(p.relative(r.cwd(),t.configPath)||"docs.config.json")}`),t.gitignoreUpdated&&t.gitignorePath&&o.line(`${a.info} Updated ${d.gray(o.path(t.gitignorePath))}`)},D=async i=>{const e=i.options,{removeSources:s}=await import("#commands/remove"),{pruneCache:n}=await import("#commands/prune");if(i.ids.length===0)throw new Error("Usage: docs-cache remove <id...>");const t=await s({configPath:e.config,ids:i.ids});if(e.json){r.stdout.write(`${JSON.stringify(t,null,2)}
-`);return}if(t.removed.length>0&&o.line(`${a.success} Removed ${t.removed.length} source${t.removed.length===1?"":"s"}: ${t.removed.join(", ")}`),t.missing.length>0&&o.line(`${a.warn} Missing ${t.missing.length} source${t.missing.length===1?"":"s"}: ${t.missing.join(", ")}`),t.targetsRemoved.length>0){const c=t.targetsRemoved.map(g=>`${g.id} -> ${o.path(g.targetDir)}`).join(", ");o.line(`${a.success} Removed ${t.targetsRemoved.length} target${t.targetsRemoved.length===1?"":"s"}: ${c}`)}o.line(`${a.info} Updated ${d.gray(p.relative(r.cwd(),t.configPath)||"docs.config.json")}`),e.prune&&await n({configPath:e.config,cacheDirOverride:e.cacheDir,json:e.json})},S=async i=>{const e=i.options,{getStatus:s,printStatus:n}=await import("#commands/status"),t=await s({configPath:e.config,cacheDirOverride:e.cacheDir,json:e.json});if(e.json){r.stdout.write(`${JSON.stringify(t,null,2)}
-`);return}n(t)},P=async i=>{const e=i.options,{cleanCache:s}=await import("#commands/clean"),n=await s({configPath:e.config,cacheDirOverride:e.cacheDir,json:e.json});if(e.json){r.stdout.write(`${JSON.stringify(n,null,2)}
-`);return}if(n.removed){o.line(`${a.success} Removed cache at ${o.path(n.cacheDir)}`);return}o.line(`${a.info} Cache already missing at ${o.path(n.cacheDir)}`)},C=async i=>{const e=i.options,{cleanGitCache:s}=await import("#commands/clean-git-cache"),n=await s();if(e.json){r.stdout.write(`${JSON.stringify(n,null,2)}
-`);return}if(!n.removed){o.line(`${a.info} Global git cache already empty at ${o.path(n.cacheDir)}`);return}const t=n.bytesFreed!==void 0?`${(n.bytesFreed/1024/1024).toFixed(2)} MB`:"unknown size",c=n.repoCount!==void 0?` (${n.repoCount} cached repositor${n.repoCount===1?"y":"ies"})`:"";o.line(`${a.success} Cleared global git cache${c}: ${t} freed`),o.line(`${a.info} Cache location: ${o.path(n.cacheDir)}`)},b=async i=>{const e=i.options,{pruneCache:s}=await import("#commands/prune"),n=await s({configPath:e.config,cacheDirOverride:e.cacheDir,json:e.json});if(e.json){r.stdout.write(`${JSON.stringify(n,null,2)}
-`);return}if(n.removed.length===0){o.line(`${a.info} No cache entries to prune.`);return}o.line(`${a.success} Pruned ${n.removed.length} cache entr${n.removed.length===1?"y":"ies"}: ${n.removed.join(", ")}`)},k=async i=>{const e=i.options,{printSyncPlan:s,runSync:n}=await import("#commands/sync"),t=await n({configPath:e.config,cacheDirOverride:e.cacheDir,json:e.json,lockOnly:e.lockOnly,offline:e.offline,failOnMiss:e.failOnMiss,timeoutMs:e.timeoutMs,verbose:e.verbose});if(e.json){r.stdout.write(`${JSON.stringify(t,null,2)}
-`);return}s(t)},M=async i=>{const e=i.options,{printVerify:s,verifyCache:n}=await import("#commands/verify"),t=await n({configPath:e.config,cacheDirOverride:e.cacheDir,json:e.json});e.json?r.stdout.write(`${JSON.stringify(t,null,2)}
-`):s(t),t.results.some(c=>!c.ok)&&r.exit(l.FatalError)},x=async i=>{const e=i.options,{initConfig:s}=await import("#commands/init");if(e.config)throw new Error("Init does not accept --config. Use the project root.");const n=await s({cacheDirOverride:e.cacheDir,json:e.json});if(e.json){r.stdout.write(`${JSON.stringify(n,null,2)}
-`);return}o.line(`${a.success} Wrote ${d.gray(o.path(n.configPath))}`),n.gitignoreUpdated&&n.gitignorePath&&o.line(`${a.info} Updated ${d.gray(o.path(n.gitignorePath))}`)},N=async i=>{switch(i.command){case"add":await O(i);return;case"remove":await D(i);return;case"status":await S(i);return;case"clean":await P(i);return;case"clean-cache":await C(i);return;case"prune":await b(i);return;case"sync":await k(i);return;case"verify":await M(i);return;case"init":await x(i);return;default:o.line(`${h} ${i.command}: not implemented yet.`)}};async function R(){try{r.on("uncaughtException",u),r.on("unhandledRejection",u);const i=w();y(i.options.silent),v(i.options.verbose),i.help&&(f(),r.exit(l.Success)),i.command||(f(),r.exit(l.InvalidArgument)),i.command!=="add"&&i.command!=="remove"&&i.positionals.length>0&&(m(`${h}: unexpected arguments.`),f(),r.exit(l.InvalidArgument)),await N(i.parsed)}catch(i){u(i)}}function u(i){const e=i instanceof Error?i.message:String(i);m(e),r.exit(l.FatalError)}export{h as CLI_NAME,R as main};
+
+Pin options:
+  --all
+  --dry-run
+
+Update options:
+  --all
+  --dry-run
+`,h=()=>{a.stdout.write(j.trimStart())},m=i=>{a.stderr.write(`${r.error} ${i}
+`)},O=async i=>{const e=i.options,{addSources:s}=await import("#commands/add"),{runSync:t}=await import("#commands/sync");if(i.entries.length===0)throw new Error("Usage: docs-cache add [--source <repo> --target <dir>] <repo...>");const n=await s({configPath:e.config,entries:i.entries});if(e.offline?e.json||o.line(`${r.warn} Offline: skipped sync`):await t({configPath:e.config,cacheDirOverride:e.cacheDir,json:e.json,lockOnly:e.lockOnly,offline:e.offline,failOnMiss:e.failOnMiss,sourceFilter:n.sources.map(c=>c.id),timeoutMs:e.timeoutMs,verbose:e.verbose}),e.json){a.stdout.write(`${JSON.stringify(n,null,2)}
+`);return}for(const c of n.sources){const f=c.repo.replace(/^https?:\/\//,"").replace(/\.git$/,""),$=c.targetDir?` ${d.dim("->")} ${d.magenta(c.targetDir)}`:"";o.item(r.success,c.id,`${d.blue(f)}${$}`)}n.skipped?.length&&o.line(`${r.warn} Skipped ${n.skipped.length} existing source${n.skipped.length===1?"":"s"}: ${n.skipped.join(", ")}`),o.line(`${r.info} Updated ${d.gray(l.relative(a.cwd(),n.configPath)||"docs.config.json")}`),n.gitignoreUpdated&&n.gitignorePath&&o.line(`${r.info} Updated ${d.gray(o.path(n.gitignorePath))}`)},S=async i=>{const e=i.options,{removeSources:s}=await import("#commands/remove"),{pruneCache:t}=await import("#commands/prune");if(i.ids.length===0)throw new Error("Usage: docs-cache remove <id...>");const n=await s({configPath:e.config,ids:i.ids});if(e.json){a.stdout.write(`${JSON.stringify(n,null,2)}
+`);return}if(n.removed.length>0&&o.line(`${r.success} Removed ${n.removed.length} source${n.removed.length===1?"":"s"}: ${n.removed.join(", ")}`),n.missing.length>0&&o.line(`${r.warn} Missing ${n.missing.length} source${n.missing.length===1?"":"s"}: ${n.missing.join(", ")}`),n.targetsRemoved.length>0){const c=n.targetsRemoved.map(f=>`${f.id} -> ${o.path(f.targetDir)}`).join(", ");o.line(`${r.success} Removed ${n.targetsRemoved.length} target${n.targetsRemoved.length===1?"":"s"}: ${c}`)}o.line(`${r.info} Updated ${d.gray(l.relative(a.cwd(),n.configPath)||"docs.config.json")}`),e.prune&&await t({configPath:e.config,cacheDirOverride:e.cacheDir,json:e.json})},D=async i=>{const e=i.options;if(e.offline)throw new Error("Pin does not support --offline.");if(!e.all&&i.ids.length===0)throw new Error("Usage: docs-cache pin <id...> [--all]");const{pinSources:s}=await import("#commands/pin"),t=await s({configPath:e.config,ids:i.ids,all:e.all,dryRun:e.dryRun,timeoutMs:e.timeoutMs});if(e.json){a.stdout.write(`${JSON.stringify(t,null,2)}
+`);return}for(const n of t.updated)o.item(r.success,n.id,`${n.fromRef} -> ${n.toRef}`);for(const n of t.unchanged)o.item(r.info,n,"already pinned");if(t.missing.length>0&&o.line(`${r.warn} Missing ${t.missing.length} source${t.missing.length===1?"":"s"}: ${t.missing.join(", ")}`),t.dryRun){o.line(`${r.info} Dry run: no changes written to ${d.gray(l.relative(a.cwd(),t.configPath)||"docs.config.json")}`);return}o.line(`${r.info} Updated ${d.gray(l.relative(a.cwd(),t.configPath)||"docs.config.json")}`)},P=async i=>{const e=i.options;if(e.offline)throw new Error("Update does not support --offline.");if(!e.all&&i.ids.length===0)throw new Error("Usage: docs-cache update <id...> [--all]");const{printSyncPlan:s}=await import("#commands/sync"),{updateSources:t}=await import("#commands/update"),n=await t({configPath:e.config,cacheDirOverride:e.cacheDir,ids:i.ids,all:e.all,dryRun:e.dryRun,json:e.json,lockOnly:e.lockOnly,failOnMiss:e.failOnMiss,timeoutMs:e.timeoutMs,verbose:e.verbose,concurrency:e.concurrency,frozen:e.frozen});if(e.json){a.stdout.write(`${JSON.stringify(n,null,2)}
+`);return}s(n.plan),n.missing.length>0&&o.line(`${r.warn} Missing ${n.missing.length} source${n.missing.length===1?"":"s"}: ${n.missing.join(", ")}`),n.dryRun&&o.line(`${r.info} Dry run: no changes written to ${d.gray(l.relative(a.cwd(),n.plan.configPath)||"docs.config.json")}`)},M=async i=>{const e=i.options,{getStatus:s,printStatus:t}=await import("#commands/status"),n=await s({configPath:e.config,cacheDirOverride:e.cacheDir,json:e.json});if(e.json){a.stdout.write(`${JSON.stringify(n,null,2)}
+`);return}t(n)},R=async i=>{const e=i.options,{cleanCache:s}=await import("#commands/clean"),t=await s({configPath:e.config,cacheDirOverride:e.cacheDir,json:e.json});if(e.json){a.stdout.write(`${JSON.stringify(t,null,2)}
+`);return}if(t.removed){o.line(`${r.success} Removed cache at ${o.path(t.cacheDir)}`);return}o.line(`${r.info} Cache already missing at ${o.path(t.cacheDir)}`)},b=async i=>{const e=i.options,{cleanGitCache:s}=await import("#commands/clean-git-cache"),t=await s();if(e.json){a.stdout.write(`${JSON.stringify(t,null,2)}
+`);return}if(!t.removed){o.line(`${r.info} Global git cache already empty at ${o.path(t.cacheDir)}`);return}const n=t.bytesFreed!==void 0?`${(t.bytesFreed/1024/1024).toFixed(2)} MB`:"unknown size",c=t.repoCount!==void 0?` (${t.repoCount} cached repositor${t.repoCount===1?"y":"ies"})`:"";o.line(`${r.success} Cleared global git cache${c}: ${n} freed`),o.line(`${r.info} Cache location: ${o.path(t.cacheDir)}`)},C=async i=>{const e=i.options,{pruneCache:s}=await import("#commands/prune"),t=await s({configPath:e.config,cacheDirOverride:e.cacheDir,json:e.json});if(e.json){a.stdout.write(`${JSON.stringify(t,null,2)}
+`);return}if(t.removed.length===0){o.line(`${r.info} No cache entries to prune.`);return}o.line(`${r.success} Pruned ${t.removed.length} cache entr${t.removed.length===1?"y":"ies"}: ${t.removed.join(", ")}`)},k=async i=>{const e=i.options,{printSyncPlan:s,runSync:t}=await import("#commands/sync"),n=i.ids.length>0?i.ids:void 0,c=await t({configPath:e.config,cacheDirOverride:e.cacheDir,json:e.json,lockOnly:e.lockOnly,offline:e.offline,failOnMiss:e.failOnMiss,frozen:e.frozen,sourceFilter:n,timeoutMs:e.timeoutMs,verbose:e.verbose});if(e.json){a.stdout.write(`${JSON.stringify(c,null,2)}
+`);return}s(c)},U=async i=>{const e=i.options,{printVerify:s,verifyCache:t}=await import("#commands/verify"),n=await t({configPath:e.config,cacheDirOverride:e.cacheDir,json:e.json});e.json?a.stdout.write(`${JSON.stringify(n,null,2)}
+`):s(n),n.results.some(c=>!c.ok)&&a.exit(g.FatalError)},E=async i=>{const e=i.options,{initConfig:s}=await import("#commands/init");if(e.config)throw new Error("Init does not accept --config. Use the project root.");const t=await s({cacheDirOverride:e.cacheDir,json:e.json});if(e.json){a.stdout.write(`${JSON.stringify(t,null,2)}
+`);return}o.line(`${r.success} Wrote ${d.gray(o.path(t.configPath))}`),t.gitignoreUpdated&&t.gitignorePath&&o.line(`${r.info} Updated ${d.gray(o.path(t.gitignorePath))}`)},N=async i=>{switch(i.command){case"add":await O(i);return;case"remove":await S(i);return;case"pin":await D(i);return;case"update":await P(i);return;case"status":await M(i);return;case"clean":await R(i);return;case"clean-cache":await b(i);return;case"prune":await C(i);return;case"sync":await k(i);return;case"verify":await U(i);return;case"init":await E(i);return;default:o.line(`${u} ${i.command}: not implemented yet.`)}};async function x(){try{a.on("uncaughtException",p),a.on("unhandledRejection",p);const i=w();y(i.options.silent),v(i.options.verbose),i.help&&(h(),a.exit(g.Success)),i.command||(h(),a.exit(g.InvalidArgument)),i.command!=="add"&&i.command!=="remove"&&i.command!=="pin"&&i.command!=="update"&&i.command!=="sync"&&i.positionals.length>0&&(m(`${u}: unexpected arguments.`),h(),a.exit(g.InvalidArgument)),await N(i.parsed)}catch(i){p(i)}}function p(i){const e=i instanceof Error?i.message:String(i);m(e),a.exit(g.FatalError)}export{u as CLI_NAME,x as main};
 //# sourceMappingURL=cli.mjs.map

package/dist/esm/api.d.ts

@@ -4,9 +4,11 @@ export { parseArgs } from "#cli/parse-args";
 export { cleanCache } from "#commands/clean";
 export { cleanGitCache } from "#commands/clean-git-cache";
 export { initConfig } from "#commands/init";
+export { pinSources } from "#commands/pin";
 export { pruneCache } from "#commands/prune";
 export { removeSources } from "#commands/remove";
 export { printSyncPlan, runSync } from "#commands/sync";
+export { updateSources } from "#commands/update";
 export { verifyCache } from "#commands/verify";
 export { loadConfig } from "#config";
 export { redactRepoUrl } from "#git/redact";

package/dist/esm/api.mjs

@@ -4,9 +4,11 @@ export { parseArgs } from "#cli/parse-args";
 export { cleanCache } from "#commands/clean";
 export { cleanGitCache } from "#commands/clean-git-cache";
 export { initConfig } from "#commands/init";
+export { pinSources } from "#commands/pin";
 export { pruneCache } from "#commands/prune";
 export { removeSources } from "#commands/remove";
 export { printSyncPlan, runSync } from "#commands/sync";
+export { updateSources } from "#commands/update";
 export { verifyCache } from "#commands/verify";
 export { loadConfig } from "#config";
 export { redactRepoUrl } from "#git/redact";

package/dist/esm/cli/index.mjs

@@ -11,6 +11,8 @@ Usage: ${CLI_NAME} <command> [options]
 Commands:
   add         Add sources to the config (supports github:org/repo#ref)
   remove      Remove sources from the config and targets
+  pin         Pin source refs to current commits
+  update      Refresh selected sources and lock data
   sync        Synchronize cache with config
   status      Show cache status
   clean       Remove project cache
@@ -22,6 +24,7 @@ Commands:
 Global options:
   --config <path>
   --cache-dir <path>
+  --frozen
   --offline
   --fail-on-miss
   --lock-only
@@ -36,6 +39,14 @@ Add options:
   --target <dir>
   --target-dir <path>
   --id <id>
+
+Pin options:
+  --all
+  --dry-run
+
+Update options:
+  --all
+  --dry-run
 `;
 const printHelp = () => {
   process.stdout.write(HELP_TEXT.trimStart());
@@ -141,6 +152,89 @@ const runRemove = async (parsed) => {
     });
   }
 };
+const runPin = async (parsed) => {
+  const options = parsed.options;
+  if (options.offline) {
+    throw new Error("Pin does not support --offline.");
+  }
+  if (!options.all && parsed.ids.length === 0) {
+    throw new Error("Usage: docs-cache pin <id...> [--all]");
+  }
+  const { pinSources } = await import("#commands/pin");
+  const result = await pinSources({
+    configPath: options.config,
+    ids: parsed.ids,
+    all: options.all,
+    dryRun: options.dryRun,
+    timeoutMs: options.timeoutMs
+  });
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return;
+  }
+  for (const entry of result.updated) {
+    ui.item(symbols.success, entry.id, `${entry.fromRef} -> ${entry.toRef}`);
+  }
+  for (const id of result.unchanged) {
+    ui.item(symbols.info, id, "already pinned");
+  }
+  if (result.missing.length > 0) {
+    ui.line(
+      `${symbols.warn} Missing ${result.missing.length} source${result.missing.length === 1 ? "" : "s"}: ${result.missing.join(", ")}`
+    );
+  }
+  if (result.dryRun) {
+    ui.line(
+      `${symbols.info} Dry run: no changes written to ${pc.gray(path.relative(process.cwd(), result.configPath) || "docs.config.json")}`
+    );
+    return;
+  }
+  ui.line(
+    `${symbols.info} Updated ${pc.gray(path.relative(process.cwd(), result.configPath) || "docs.config.json")}`
+  );
+};
+const runUpdate = async (parsed) => {
+  const options = parsed.options;
+  if (options.offline) {
+    throw new Error("Update does not support --offline.");
+  }
+  if (!options.all && parsed.ids.length === 0) {
+    throw new Error("Usage: docs-cache update <id...> [--all]");
+  }
+  const { printSyncPlan } = await import("#commands/sync");
+  const { updateSources } = await import("#commands/update");
+  const result = await updateSources({
+    configPath: options.config,
+    cacheDirOverride: options.cacheDir,
+    ids: parsed.ids,
+    all: options.all,
+    dryRun: options.dryRun,
+    json: options.json,
+    lockOnly: options.lockOnly,
+    failOnMiss: options.failOnMiss,
+    timeoutMs: options.timeoutMs,
+    verbose: options.verbose,
+    concurrency: options.concurrency,
+    frozen: options.frozen
+  });
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return;
+  }
+  printSyncPlan(result.plan);
+  if (result.missing.length > 0) {
+    ui.line(
+      `${symbols.warn} Missing ${result.missing.length} source${result.missing.length === 1 ? "" : "s"}: ${result.missing.join(", ")}`
+    );
+  }
+  if (result.dryRun) {
+    ui.line(
+      `${symbols.info} Dry run: no changes written to ${pc.gray(path.relative(process.cwd(), result.plan.configPath) || "docs.config.json")}`
+    );
+  }
+};
 const runStatus = async (parsed) => {
   const options = parsed.options;
   const { getStatus, printStatus } = await import("#commands/status");
@@ -223,6 +317,7 @@ const runPrune = async (parsed) => {
 const runSyncCommand = async (parsed) => {
   const options = parsed.options;
   const { printSyncPlan, runSync } = await import("#commands/sync");
+  const sourceFilter = parsed.ids.length > 0 ? parsed.ids : void 0;
   const plan = await runSync({
     configPath: options.config,
     cacheDirOverride: options.cacheDir,
@@ -230,6 +325,8 @@ const runSyncCommand = async (parsed) => {
     lockOnly: options.lockOnly,
     offline: options.offline,
     failOnMiss: options.failOnMiss,
+    frozen: options.frozen,
+    sourceFilter,
     timeoutMs: options.timeoutMs,
     verbose: options.verbose
   });
@@ -288,6 +385,12 @@ const runCommand = async (parsed) => {
     case "remove":
       await runRemove(parsed);
       return;
+    case "pin":
+      await runPin(parsed);
+      return;
+    case "update":
+      await runUpdate(parsed);
+      return;
     case "status":
       await runStatus(parsed);
       return;
@@ -328,7 +431,7 @@ export async function main() {
       printHelp();
       process.exit(ExitCode.InvalidArgument);
     }
-    if (parsed.command !== "add" && parsed.command !== "remove" && parsed.positionals.length > 0) {
+    if (parsed.command !== "add" && parsed.command !== "remove" && parsed.command !== "pin" && parsed.command !== "update" && parsed.command !== "sync" && parsed.positionals.length > 0) {
       printError(`${CLI_NAME}: unexpected arguments.`);
       printHelp();
       process.exit(ExitCode.InvalidArgument);

package/dist/esm/cli/parse-args.d.ts

@@ -1,5 +1,5 @@
 import type { CliCommand, CliOptions } from "./types";
-declare const COMMANDS: readonly ["add", "remove", "sync", "status", "clean", "clean-cache", "prune", "verify", "init"];
+declare const COMMANDS: readonly ["add", "remove", "pin", "update", "sync", "status", "clean", "clean-cache", "prune", "verify", "init"];
 type Command = (typeof COMMANDS)[number];
 export type ParsedArgs = {
     command: Command | null;

package/dist/esm/cli/parse-args.mjs

@@ -4,6 +4,8 @@ import { ExitCode } from "#cli/exit-code";
 const COMMANDS = [
   "add",
   "remove",
+  "pin",
+  "update",
   "sync",
   "status",
   "clean",
@@ -18,6 +20,7 @@ const ADD_ONLY_OPTIONS = /* @__PURE__ */ new Set([
   "--target-dir",
   "--id"
 ]);
+const SCOPED_SOURCE_OPTIONS = /* @__PURE__ */ new Set(["--all", "--dry-run"]);
 const POSITIONAL_SKIP_OPTIONS = /* @__PURE__ */ new Set([
   "--config",
   "--cache-dir",
@@ -168,16 +171,40 @@ const parsePositionals = (rawArgs) => {
 };
 const assertAddOnlyOptions = (command, rawArgs) => {
   if (command === "add") {
+    for (const arg of rawArgs) {
+      const [flag] = arg.split("=");
+      if (SCOPED_SOURCE_OPTIONS.has(flag)) {
+        throw new Error(`${arg} is only valid for pin or update.`);
+      }
+    }
+    return;
+  }
+  if (command === "pin" || command === "update") {
+    for (const arg of rawArgs) {
+      if (ADD_ONLY_OPTIONS.has(arg)) {
+        throw new Error(`${arg} is only valid for add.`);
+      }
+      if (!arg.startsWith("--")) {
+        continue;
+      }
+      const [flag] = arg.split("=");
+      if (ADD_ONLY_OPTIONS_WITH_VALUES.has(flag)) {
+        throw new Error(`${flag} is only valid for add.`);
+      }
+    }
     return;
   }
   for (const arg of rawArgs) {
+    const [flag] = arg.split("=");
+    if (SCOPED_SOURCE_OPTIONS.has(flag)) {
+      throw new Error(`${arg} is only valid for pin or update.`);
+    }
     if (ADD_ONLY_OPTIONS.has(arg)) {
       throw new Error(`${arg} is only valid for add.`);
     }
     if (!arg.startsWith("--")) {
       continue;
     }
-    const [flag] = arg.split("=");
     if (ADD_ONLY_OPTIONS_WITH_VALUES.has(flag)) {
       throw new Error(`${flag} is only valid for add.`);
     }
@@ -191,6 +218,9 @@ const buildOptions = (result) => {
     failOnMiss: Boolean(result.options.failOnMiss),
     lockOnly: Boolean(result.options.lockOnly),
     prune: Boolean(result.options.prune),
+    all: Boolean(result.options.all),
+    dryRun: Boolean(result.options.dryRun),
+    frozen: Boolean(result.options.frozen),
     concurrency: result.options.concurrency ? Number(result.options.concurrency) : void 0,
     json: Boolean(result.options.json),
     timeoutMs: result.options.timeoutMs ? Number(result.options.timeoutMs) : void 0,
@@ -236,8 +266,12 @@ const buildParsedCommand = (command, options, positionals, addEntries) => {
       };
     case "remove":
       return { command: "remove", ids: positionals, options };
+    case "pin":
+      return { command: "pin", ids: positionals, options };
+    case "update":
+      return { command: "update", ids: positionals, options };
     case "sync":
-      return { command: "sync", options };
+      return { command: "sync", ids: positionals, options };
     case "status":
       return { command: "status", options };
     case "clean":
@@ -257,10 +291,12 @@ const buildParsedCommand = (command, options, positionals, addEntries) => {
 export const parseArgs = (argv = process.argv) => {
   try {
     const cli = cac("docs-cache");
-    cli.option("--config <path>", "Path to config file").option("--cache-dir <path>", "Override cache directory").option("--offline", "Disable network access").option("--fail-on-miss", "Fail when required sources are missing").option("--lock-only", "Update lock without materializing files").option("--prune", "Prune cache on remove").option("--concurrency <n>", "Concurrency limit").option("--json", "Output JSON").option("--timeout-ms <n>", "Network timeout in milliseconds").option("--silent", "Suppress non-error output").option("--verbose", "Enable verbose logging").help();
+    cli.option("--config <path>", "Path to config file").option("--cache-dir <path>", "Override cache directory").option("--all", "Apply command to all sources").option("--dry-run", "Preview changes without writing files").option("--frozen", "Fail if lock and resolved refs differ").option("--offline", "Disable network access").option("--fail-on-miss", "Fail when required sources are missing").option("--lock-only", "Update lock without materializing files").option("--prune", "Prune cache on remove").option("--concurrency <n>", "Concurrency limit").option("--json", "Output JSON").option("--timeout-ms <n>", "Network timeout in milliseconds").option("--silent", "Suppress non-error output").option("--verbose", "Enable verbose logging").help();
     cli.command("add [repo...]", "Add sources to the config").option("--source <repo>", "Source repo").option("--target <dir>", "Target directory for source").option("--target-dir <path>", "Target directory for source").option("--id <id>", "Source id");
     cli.command("remove <id...>", "Remove sources from the config and targets");
-    cli.command("sync", "Synchronize cache with config");
+    cli.command("pin [id...]", "Pin source refs to current commit");
+    cli.command("update [id...]", "Refresh selected sources and lock data");
+    cli.command("sync [id...]", "Synchronize cache with config");
     cli.command("status", "Show cache status");
     cli.command("clean", "Remove project cache");
     cli.command("clean-cache", "Clear global git cache");

package/dist/esm/cli/types.d.ts

@@ -5,6 +5,9 @@ export type CliOptions = {
     failOnMiss: boolean;
     lockOnly: boolean;
     prune: boolean;
+    all: boolean;
+    dryRun: boolean;
+    frozen: boolean;
     concurrency?: number;
     json: boolean;
     timeoutMs?: number;
@@ -24,8 +27,17 @@ export type CliCommand = {
     command: "remove";
     ids: string[];
     options: CliOptions;
+} | {
+    command: "pin";
+    ids: string[];
+    options: CliOptions;
+} | {
+    command: "update";
+    ids: string[];
+    options: CliOptions;
 } | {
     command: "sync";
+    ids: string[];
     options: CliOptions;
 } | {
     command: "status";

package/dist/esm/commands/pin.d.ts

@@ -0,0 +1,26 @@
+import { resolveRemoteCommit } from "#git/resolve-remote";
+type PinParams = {
+    configPath?: string;
+    ids: string[];
+    all: boolean;
+    dryRun?: boolean;
+    timeoutMs?: number;
+};
+type PinDeps = {
+    resolveRemoteCommit?: typeof resolveRemoteCommit;
+};
+type PinResultEntry = {
+    id: string;
+    fromRef: string;
+    toRef: string;
+    repo: string;
+};
+export declare const pinSources: (params: PinParams, deps?: PinDeps) => Promise<{
+    configPath: any;
+    dryRun: boolean;
+    pinned: PinResultEntry[];
+    updated: PinResultEntry[];
+    unchanged: string[];
+    missing: string[];
+}>;
+export {};

package/dist/esm/commands/pin.mjs

@@ -0,0 +1,111 @@
+import { resolveSources } from "#config";
+import {
+  mergeConfigBase,
+  readConfigAtPath,
+  resolveConfigTarget,
+  writeConfigFile
+} from "#config/io";
+import { resolveRemoteCommit } from "#git/resolve-remote";
+const DEFAULT_ALLOW_HOSTS = ["github.com", "gitlab.com", "visualstudio.com"];
+const PIN_RESOLVE_CONCURRENCY = 4;
+const isPinnedCommitRef = (ref) => /^[0-9a-f]{40}$/i.test(ref.trim());
+export const pinSources = async (params, deps = {}) => {
+  if (!params.all && params.ids.length === 0) {
+    throw new Error("Usage: docs-cache pin <id...> [--all]");
+  }
+  const target = await resolveConfigTarget(params.configPath);
+  const resolvedPath = target.resolvedPath;
+  const { config, rawConfig, rawPackage } = await readConfigAtPath(target);
+  const selectedIds = params.all ? new Set(config.sources.map((source) => source.id)) : new Set(params.ids);
+  const missing = params.all ? [] : params.ids.filter(
+    (id) => !config.sources.some((source) => source.id === id)
+  );
+  const resolvedSources = resolveSources(config);
+  const resolvedById = new Map(
+    resolvedSources.map((source) => [source.id, source])
+  );
+  const allowHosts = config.defaults?.allowHosts ?? DEFAULT_ALLOW_HOSTS;
+  const resolveCommit = deps.resolveRemoteCommit ?? resolveRemoteCommit;
+  const entriesById = /* @__PURE__ */ new Map();
+  const sourcesToProcess = config.sources.filter(
+    (source) => selectedIds.has(source.id)
+  );
+  const queue = [];
+  let cursor = 0;
+  const runNext = async () => {
+    const index = cursor;
+    cursor += 1;
+    const source = sourcesToProcess[index];
+    if (!source) {
+      return;
+    }
+    const resolved = resolvedById.get(source.id);
+    if (!resolved) {
+      return runNext();
+    }
+    const fromRef = source.ref ?? resolved.ref;
+    const trimmedFromRef = fromRef.trim();
+    if (isPinnedCommitRef(trimmedFromRef)) {
+      entriesById.set(source.id, {
+        id: source.id,
+        fromRef,
+        toRef: trimmedFromRef,
+        repo: resolved.repo
+      });
+      return runNext();
+    }
+    const remote = await resolveCommit({
+      repo: resolved.repo,
+      ref: resolved.ref,
+      allowHosts,
+      timeoutMs: params.timeoutMs
+    });
+    entriesById.set(source.id, {
+      id: source.id,
+      fromRef,
+      toRef: remote.resolvedCommit,
+      repo: remote.repo
+    });
+    return runNext();
+  };
+  for (let worker = 0; worker < Math.min(PIN_RESOLVE_CONCURRENCY, sourcesToProcess.length); worker += 1) {
+    queue.push(runNext());
+  }
+  await Promise.all(queue);
+  if (entriesById.size === 0) {
+    throw new Error("No matching sources found to pin.");
+  }
+  const nextSources = config.sources.map((source) => {
+    const pin = entriesById.get(source.id);
+    if (!pin) {
+      return source;
+    }
+    if (source.ref === pin.toRef) {
+      return source;
+    }
+    return {
+      ...source,
+      ref: pin.toRef
+    };
+  });
+  if (!params.dryRun) {
+    const nextConfig = mergeConfigBase(rawConfig ?? config, nextSources);
+    await writeConfigFile({
+      mode: target.mode,
+      resolvedPath,
+      config: nextConfig,
+      rawPackage
+    });
+  }
+  const pinned = Array.from(entriesById.values());
+  const updated = pinned.filter((entry) => entry.fromRef !== entry.toRef);
+  const unchanged = pinned.filter((entry) => entry.fromRef === entry.toRef).map((entry) => entry.id);
+  return {
+    configPath: resolvedPath,
+    dryRun: Boolean(params.dryRun),
+    pinned,
+    updated,
+    unchanged,
+    missing
+  };
+};

package/dist/esm/commands/sync.mjs

@@ -646,6 +646,18 @@ export const runSync = async (options, deps = {}) => {
       `Missing required source(s): ${requiredMissing.map((result) => result.id).join(", ")}.`
     );
   }
+  if (options.frozen) {
+    const drifted = plan.results.filter(
+      (result) => result.status !== "up-to-date"
+    );
+    if (drifted.length > 0) {
+      throw new Error(
+        `Frozen sync failed: lock is out of date for source(s): ${drifted.map((result) => result.id).join(
+          ", "
+        )}. Run docs-cache update or docs-cache sync to refresh the lock.`
+      );
+    }
+  }
   if (!options.lockOnly) {
     const defaults = plan.defaults;
     const runFetch = deps.fetchSource ?? fetchSource;

package/dist/esm/commands/update.d.ts

@@ -0,0 +1,28 @@
+import type { materializeSource } from "#cache/materialize";
+import type { fetchSource } from "#git/fetch-source";
+import type { resolveRemoteCommit } from "#git/resolve-remote";
+type UpdateOptions = {
+    configPath?: string;
+    cacheDirOverride?: string;
+    ids: string[];
+    all: boolean;
+    dryRun: boolean;
+    json: boolean;
+    lockOnly: boolean;
+    failOnMiss: boolean;
+    timeoutMs?: number;
+    verbose?: boolean;
+    concurrency?: number;
+    frozen?: boolean;
+};
+type UpdateDeps = {
+    resolveRemoteCommit?: typeof resolveRemoteCommit;
+    fetchSource?: typeof fetchSource;
+    materializeSource?: typeof materializeSource;
+};
+export declare const updateSources: (options: UpdateOptions, deps?: UpdateDeps) => Promise<{
+    dryRun: boolean;
+    missing: string[];
+    plan: any;
+}>;
+export {};

package/dist/esm/commands/update.mjs

@@ -0,0 +1,51 @@
+import { getSyncPlan, runSync } from "#commands/sync";
+import { loadConfig } from "#config";
+const resolveSelectedSourceIds = async (options) => {
+  const { sources } = await loadConfig(options.configPath);
+  if (options.all) {
+    return {
+      selectedIds: sources.map((source) => source.id),
+      missing: []
+    };
+  }
+  const existing = new Set(sources.map((source) => source.id));
+  const selectedIds = options.ids.filter((id) => existing.has(id));
+  const missing = options.ids.filter((id) => !existing.has(id));
+  if (selectedIds.length === 0) {
+    throw new Error("No matching sources found to update.");
+  }
+  return { selectedIds, missing };
+};
+export const updateSources = async (options, deps = {}) => {
+  if (!options.all && options.ids.length === 0) {
+    throw new Error("Usage: docs-cache update <id...> [--all]");
+  }
+  const { selectedIds, missing } = await resolveSelectedSourceIds(options);
+  const syncOptions = {
+    configPath: options.configPath,
+    cacheDirOverride: options.cacheDirOverride,
+    json: options.json,
+    lockOnly: options.lockOnly,
+    offline: false,
+    failOnMiss: options.failOnMiss,
+    frozen: options.frozen,
+    verbose: options.verbose,
+    concurrency: options.concurrency,
+    sourceFilter: selectedIds,
+    timeoutMs: options.timeoutMs
+  };
+  if (options.dryRun) {
+    const plan2 = await getSyncPlan(syncOptions, deps);
+    return {
+      dryRun: true,
+      missing,
+      plan: plan2
+    };
+  }
+  const plan = await runSync(syncOptions, deps);
+  return {
+    dryRun: false,
+    missing,
+    plan
+  };
+};

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

@@ -7,36 +7,12 @@ import { execa } from "execa";
 import { getErrnoCode } from "#core/errors";
 import { assertSafeSourceId } from "#core/source-id";
 import { exists, resolveGitCacheDir } from "#git/cache-dir";
+import { buildGitEnv, resolveGitCommand } from "#git/git-env";
 const DEFAULT_TIMEOUT_MS = 12e4;
 const DEFAULT_GIT_DEPTH = 1;
 const DEFAULT_RM_RETRIES = 3;
 const DEFAULT_RM_BACKOFF_MS = 100;
-const buildGitEnv = () => {
-  const pathValue = process.env.PATH ?? process.env.Path;
-  const pathExtValue = process.env.PATHEXT ?? (process.platform === "win32" ? ".COM;.EXE;.BAT;.CMD" : void 0);
-  return {
-    ...process.env,
-    ...pathValue ? { PATH: pathValue, Path: pathValue } : {},
-    ...pathExtValue ? { PATHEXT: pathExtValue } : {},
-    HOME: process.env.HOME,
-    USER: process.env.USER,
-    USERPROFILE: process.env.USERPROFILE,
-    TMPDIR: process.env.TMPDIR,
-    TMP: process.env.TMP,
-    TEMP: process.env.TEMP,
-    SYSTEMROOT: process.env.SYSTEMROOT,
-    WINDIR: process.env.WINDIR,
-    SSH_AUTH_SOCK: process.env.SSH_AUTH_SOCK,
-    SSH_AGENT_PID: process.env.SSH_AGENT_PID,
-    HTTP_PROXY: process.env.HTTP_PROXY,
-    HTTPS_PROXY: process.env.HTTPS_PROXY,
-    NO_PROXY: process.env.NO_PROXY,
-    GIT_TERMINAL_PROMPT: "0",
-    GIT_CONFIG_NOSYSTEM: "1",
-    GIT_CONFIG_NOGLOBAL: "1",
-    ...process.platform === "win32" ? {} : { GIT_ASKPASS: "/bin/false" }
-  };
-};
+const MAX_BRACE_EXPANSIONS = 500;
 const buildGitConfigs = (allowFileProtocol) => [
   "-c",
   "core.hooksPath=/dev/null",
@@ -91,7 +67,7 @@ const git = async (args, options) => {
   );
   const commandLabel = `git ${commandArgs.join(" ")}`;
   options?.logger?.(commandLabel);
-  const subprocess = execa("git", commandArgs, {
+  const subprocess = execa(resolveGitCommand(), commandArgs, {
     cwd: options?.cwd,
     timeout: options?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
     maxBuffer: 10 * 1024 * 1024,
@@ -178,7 +154,48 @@ const ensureCommitAvailable = async (repoPath, commit, options) => {
   });
 };
 const patternHasGlob = (pattern) => pattern.includes("*") || pattern.includes("?") || pattern.includes("[");
-const normalizeSparsePatterns = (include) => (include ?? []).map((pattern) => pattern.replace(/\\/g, "/")).filter(Boolean);
+const expandBracePattern = (pattern) => {
+  const results = [];
+  const expand = (value) => {
+    const braceMatch = value.match(/^(.*?){([^}]+)}(.*)$/);
+    if (!braceMatch) {
+      if (results.length >= MAX_BRACE_EXPANSIONS) {
+        throw new Error(
+          `Brace expansion exceeded ${MAX_BRACE_EXPANSIONS} patterns for '${pattern}'.`
+        );
+      }
+      results.push(value);
+      return;
+    }
+    const [, prefix, values, suffix] = braceMatch;
+    const valueList = values.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+    if (valueList.length === 0) {
+      if (results.length >= MAX_BRACE_EXPANSIONS) {
+        throw new Error(
+          `Brace expansion exceeded ${MAX_BRACE_EXPANSIONS} patterns for '${pattern}'.`
+        );
+      }
+      results.push(value);
+      return;
+    }
+    for (const entry of valueList) {
+      const expandedPattern = `${prefix}${entry}${suffix}`;
+      expand(expandedPattern);
+    }
+  };
+  expand(pattern);
+  return results;
+};
+const normalizeSparsePatterns = (include) => {
+  const patterns = include ?? [];
+  const expanded = [];
+  for (const pattern of patterns) {
+    const normalized = pattern.replace(/\\/g, "/");
+    if (!normalized) continue;
+    expanded.push(...expandBracePattern(normalized));
+  }
+  return expanded;
+};
 const isDirectoryLiteral = (pattern) => pattern.endsWith("/");
 const toNoConePattern = (pattern) => {
   if (!patternHasGlob(pattern) && isDirectoryLiteral(pattern)) {

package/dist/esm/git/git-env.d.ts

@@ -0,0 +1,3 @@
+declare const resolveGitCommand: () => string;
+declare const buildGitEnv: () => NodeJS.ProcessEnv;
+export { buildGitEnv, resolveGitCommand };

package/dist/esm/git/git-env.mjs

@@ -0,0 +1,33 @@
+const resolveGitCommand = () => {
+  const override = process.env.DOCS_CACHE_GIT_COMMAND;
+  if (override) {
+    return override;
+  }
+  return "git";
+};
+const buildGitEnv = () => {
+  const pathValue = process.env.PATH ?? process.env.Path;
+  const pathExtValue = process.env.PATHEXT ?? (process.platform === "win32" ? ".COM;.EXE;.BAT;.CMD" : void 0);
+  return {
+    ...process.env,
+    ...pathValue ? { PATH: pathValue, Path: pathValue } : {},
+    ...pathExtValue ? { PATHEXT: pathExtValue } : {},
+    HOME: process.env.HOME,
+    USER: process.env.USER,
+    USERPROFILE: process.env.USERPROFILE,
+    TMPDIR: process.env.TMPDIR,
+    TMP: process.env.TMP,
+    TEMP: process.env.TEMP,
+    SYSTEMROOT: process.env.SYSTEMROOT,
+    WINDIR: process.env.WINDIR,
+    SSH_AUTH_SOCK: process.env.SSH_AUTH_SOCK,
+    SSH_AGENT_PID: process.env.SSH_AGENT_PID,
+    HTTP_PROXY: process.env.HTTP_PROXY,
+    HTTPS_PROXY: process.env.HTTPS_PROXY,
+    NO_PROXY: process.env.NO_PROXY,
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_CONFIG_NOSYSTEM: "1",
+    ...process.platform === "win32" ? {} : { GIT_ASKPASS: "/bin/false" }
+  };
+};
+export { buildGitEnv, resolveGitCommand };

package/dist/esm/git/resolve-remote.mjs

@@ -1,7 +1,6 @@
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
+import { execa } from "execa";
+import { buildGitEnv, resolveGitCommand } from "#git/git-env";
 import { redactRepoUrl } from "#git/redact";
-const execFileAsync = promisify(execFile);
 const DEFAULT_TIMEOUT_MS = 3e4;
 const BLOCKED_PROTOCOLS = /* @__PURE__ */ new Set(["file:", "ftp:", "data:", "javascript:"]);
 const assertAllowedProtocol = (repo) => {
@@ -65,12 +64,13 @@ export const resolveRemoteCommit = async (params) => {
   enforceHostAllowlist(params.repo, params.allowHosts);
   const repoLabel = redactRepoUrl(params.repo);
   params.logger?.(`git ls-remote ${repoLabel} ${params.ref}`);
-  const { stdout } = await execFileAsync(
-    "git",
+  const { stdout } = await execa(
+    resolveGitCommand(),
     ["ls-remote", params.repo, params.ref],
     {
       timeout: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-      maxBuffer: 1024 * 1024
+      maxBuffer: 1024 * 1024,
+      env: buildGitEnv()
     }
   );
   const resolvedCommit = parseLsRemote(stdout);

package/dist/esm/types/sync.d.ts

@@ -5,6 +5,7 @@ export type SyncOptions = {
     lockOnly: boolean;
     offline: boolean;
     failOnMiss: boolean;
+    frozen?: boolean;
     verbose?: boolean;
     concurrency?: number;
     sourceFilter?: string[];

package/package.json

@@ -1,139 +1,136 @@
 {
-	"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"
-		]
-	}
-}
+  "name": "docs-cache",
+  "private": false,
+  "type": "module",
+  "version": "0.5.6",
+  "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"
+  }
+}