docs-cache 0.5.5 → 0.5.7

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`):

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

@@ -188,7 +188,17 @@ const buildLockSource = (result, prior, now) => ({
 const buildLock = async (plan, previous) => {
   const toolVersion = await loadToolVersion();
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  const sources = { ...previous?.sources ?? {} };
+  const configSourceIds = new Set(
+    plan.config.sources.map((source) => source.id)
+  );
+  const sources = {};
+  if (previous?.sources) {
+    for (const [id, source] of Object.entries(previous.sources)) {
+      if (configSourceIds.has(id)) {
+        sources[id] = source;
+      }
+    }
+  }
   for (const result of plan.results) {
     const prior = sources[result.id];
     sources[result.id] = buildLockSource(result, prior, now);
@@ -646,6 +656,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

@@ -418,8 +418,24 @@ const handleMissingCache = async (params, cachePath, cacheExists) => {
   await cloneRepo(params, cachePath);
   return { usedCache: false, worktreeUsed: false };
 };
-const cloneOrUpdateRepo = async (params, outDir) => {
+const cloneOrUpdateInFlight = /* @__PURE__ */ new Map();
+const cloneOrUpdateRepo = (params, outDir) => {
   const cachePath = getPersistentCachePath(params.repo);
+  const inflight = cloneOrUpdateInFlight.get(cachePath);
+  if (inflight !== void 0) {
+    return inflight.then(() => cloneOrUpdateRepo(params, outDir));
+  }
+  const promise = (async () => {
+    try {
+      return await cloneOrUpdateRepoImpl(params, outDir, cachePath);
+    } finally {
+      cloneOrUpdateInFlight.delete(cachePath);
+    }
+  })();
+  cloneOrUpdateInFlight.set(cachePath, promise);
+  return promise;
+};
+const cloneOrUpdateRepoImpl = async (params, outDir, cachePath) => {
   const cacheExists = await exists(cachePath);
   const cacheValid = cacheExists && await isValidGitRepo(cachePath);
   const isCommitRef = /^[0-9a-f]{7,40}$/i.test(params.ref);

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

@@ -2,7 +2,7 @@
   "name": "docs-cache",
   "private": false,
   "type": "module",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "CLI for deterministic local caching of external documentation for agents and tools",
   "author": "Frederik Bosch",
   "license": "MIT",