link-cache 0.3.0 → 0.4.1

package/README.md

@@ -4,14 +4,97 @@ Zero-dependency helper CLIs for **cached** link checking with [Lychee][], for
 any static site that builds to a `public/` directory (Docsy, Hugo, and others).
 Two tools:
 
-- **`lychee-norm-cache`** — run lychee over your built `public/` output, then
-  normalize `.lycheecache` so reruns and commits stay byte stable.
-- **`refcache`** — inspect and prune that `.lycheecache` (the "refcache"): list
-  the oldest entries, prune a count or percentage, or print a summary.
+- **`lychee-norm-cache`** — run lychee over your built `public/` output, keeping
+  the committed `link-cache.jsonc` cache and lychee's derived `.lycheecache` in
+  sync.
+- **`link-cache`** — inspect and prune the cache: list the oldest entries, prune
+  a count or percentage (optionally scoped by URL regex; `manual` entries are
+  exempt — they retire via their `expires` date), or print a summary (status,
+  provenance, ages). (`refcache` is a deprecated alias.)
+
+With a committed `lychee.toml` and `link-cache.jsonc`, these give a site a
+self-contained, cached link-checking setup: fast reruns, and diffs that reflect
+real changes — link statuses, and check recency for freshly re-verified entries.
+
+## The owned cache: `link-cache.jsonc`
+
+The committed source of truth is `link-cache.jsonc` — a JSONC file,
+pretty-printed by construction in Prettier's style (so `prettier --check` passes
+it untouched), one multi-line object per URL, sorted, with `//` comments allowed
+on their own lines. Each comment attaches to the entry below it and survives
+rewrites for as long as the entry's status holds; a status change replaces the
+entry and retires its comments (a stale rationale is worse than none). The
+multi-line shape is deliberate: field-per-line entries keep concurrent updates
+merging cleanly under git's normal 3-way merge.
+
+```jsonc
+{
+  "https://example.com/": {
+    "status": 200,
+    "when": "2026-08-29T20:06:38Z",
+    "via": "lychee",
+  },
+  // Seeded pending my-org/repo#123; the target lands with that merge.
+  "https://example.com/future-page/": {
+    "status": 200,
+    "when": "2026-08-29T20:06:38Z",
+    "via": "manual",
+    "expires": "2026-09-30",
+  },
+}
+```
+
+Each entry records:
+
+- **`status`** — generalized: positive values are HTTP statuses; `0` is
+  unchecked; negative values are tool-specific errors (`-10` timeout, `-20`
+  network/DNS, `-30` certificate, `-40` generic client error).
+- **`when`** — the moment the status was established, as RFC3339 UTC at whole
+  seconds (`YYYY-MM-DDTHH:MM:SSZ`), converting exactly to and from lychee's
+  epoch-seconds cache timestamps. The form is strict — no fractional seconds, no
+  offsets — so timestamps are byte-comparable and lexicographically
+  chronological.
+- **`via`** — the resolver that set the status: `lychee`, `manual`
+  (hand-seeded), or a named specialized resolver (e.g. a browser-grade probe).
+- **`expires`** (optional, `manual` entries) — `YYYY-MM-DD`. Until then the
+  entry is trusted (never re-checked, overriding lychee's `max_cache_age`);
+  after that, it's re-checked live and replaced by the verified result.
+
+Lychee's own CSV cache, `.lycheecache`, is **derived**: `lychee-norm-cache`
+projects the owned cache into it before each run and folds lychee's results back
+afterwards. Gitignore `.lycheecache`; commit `link-cache.jsonc`. A re-check that
+changes an entry's status replaces the entry (provenance moves to `lychee`); a
+re-confirmation leaves provenance-bearing entries (`manual`, named resolvers)
+untouched, while `lychee`-owned entries refresh their `when` to record recency.
+A URL the run itself reports as failing is recorded as a negative tool-error
+status; an entry that merely goes missing from lychee's CSV is left untouched
+(cache-status excludes, cache aging, and site changes all remove entries from
+healthy runs).
+
+Without a `link-cache.jsonc`, `lychee-norm-cache` falls back to the legacy mode:
+normalize the committed `.lycheecache` in place. To migrate:
+
+```sh
+npm run check:links -- --migrate   # .lycheecache -> link-cache.jsonc
+```
+
+then commit `link-cache.jsonc` and gitignore `.lycheecache`. If the CSV cache
+carried a `merge=union` gitattribute, drop it rather than moving it over: union
+merging proved ineffective in practice, and on a multi-line file it can
+interleave entries into invalid JSON. The owned cache merges with git's normal
+3-way merge; on a conflict, resolve either way and rerun the check — the next
+run re-normalizes the file.
+
+## Exit codes (`lychee-norm-cache`)
+
+- `0` — success.
+- `1` — dead links: the check ran and found failures.
+- `2` — preflight or sanity failure: lychee or `public/` missing, lychee config
+  error, or **zero links checked** (an empty or fully-excluded `public/` is a
+  false-clean, not a pass).
 
-With a committed `lychee.toml` and `.lycheecache`, these give a site a
-self-contained, cached link-checking setup: fast reruns, and diffs that only
-change when links actually change.
+Warn-style wrappers can soften exit 1 (advisory link rot) while still failing
+hard on exit 2 (the check didn't actually run).
 
 ## Requirements
 
@@ -31,7 +114,7 @@ npm install --save-dev link-cache
 Or, to install from GitHub rather than the npm registry:
 
 ```sh
-npm install --save-dev github:chalin/link-cache#semver:^0.3.0
+npm install --save-dev github:chalin/link-cache#semver:^0.4.0
 ```
 
 This puts both bins on your project's `PATH`.
@@ -44,22 +127,23 @@ Wire the bins into your `package.json` scripts (bare names — `npm run` puts
 ```json
 "scripts": {
   "check:links": "lychee-norm-cache",
-  "refcache": "refcache"
+  "link-cache": "link-cache"
 }
 ```
 
 ```sh
-npm run check:links          # check links, then sort/normalize the cache
-npm run refcache -- --summary # cache stats (count, oldest, status, ages)
+npm run check:links              # sync caches, run lychee, fold results back
+npm run link-cache -- --summary  # cache stats (count, oldest, status, via, ages)
+npm run link-cache -- --match 'github\.com' --prune 10  # trim 10 oldest matching
 ```
 
 > [!WARNING]
 >
-> Don't invoke these bins via `npx`: this package isn't on the npm registry, so
-> on a stale or missing `node_modules`, `npx` falls back to the public registry
-> and runs **whatever package holds the name there** (the `lychee-norm-cache`
-> name is squatted). Bare bin names in `npm run` scripts resolve locally or fail
-> loudly — they never touch the registry.
+> Don't invoke these bins via `npx`: on a stale or missing `node_modules`, `npx`
+> falls back to the public registry and runs **whatever package holds the bin's
+> name there** (the `lychee-norm-cache` name is squatted). Bare bin names in
+> `npm run` scripts resolve locally or fail loudly — they never touch the
+> registry.
 
 `lychee-norm-cache` runs in the current directory (your site root) and forwards
 any extra arguments to lychee. Run either tool with `--help` for its full
@@ -69,10 +153,12 @@ forwards (e.g. `--offline`, `--max-cache-age 0`).
 ## Development
 
 The published CLIs have **zero runtime dependencies**; Prettier is the only dev
-dependency. Run the checks (format + tests) with:
+dependency. The committed `.npmrc` applies the usual supply-chain controls
+(lock-exact installs, script execution default-deny, release cooldown). Run the
+checks (format + tests) with:
 
 ```sh
-npm install
+npm run install:safe
 npm run check
 ```
 

package/check/index.mjs

@@ -1,32 +1,58 @@
 #!/usr/bin/env node
-// The `lychee-norm-cache` bin: run lychee over a built site and normalize
-// .lycheecache for byte-stable reruns. Runs in the cwd (the site root), so any
-// site with a lychee.toml can reuse it. Run with `--help` for usage.
+// The `lychee-norm-cache` bin: run lychee over a built site, maintained around
+// an owned JSONC cache (link-cache.jsonc, the committed source of truth) with
+// lychee's CSV .lycheecache derived from it. Falls back to legacy CSV-only
+// normalization when no owned cache exists. Run with `--help` for usage.
 //
 // When GITHUB_TOKEN is unset, a token is bridged from the gh CLI — lychee reads
 // GITHUB_TOKEN, which also lifts the github.com rate limit; CI sets it directly.
+//
+// Exit codes: 0 success; 1 dead links; 2 preflight or sanity failure (lychee
+// or public/ missing, zero links checked, lychee config error).
 
 import { spawnSync } from 'node:child_process';
-import {
-  existsSync,
-  readFileSync,
-  realpathSync,
-  statSync,
-  writeFileSync,
-} from 'node:fs';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import {
+  CSV_FILE,
+  OWNED_FILE,
+  mergeBack,
+  migrateCsvText,
+  parseCsv,
+  parseOwned,
+  projectToCsv,
+  serializeCsv,
+  serializeOwned,
+} from '../lib/cache.mjs';
+import { writeFileAtomic } from '../lib/write.mjs';
+
 const INSTALL_HINT = 'https://github.com/lycheeverse/lychee#installation';
 
-const USAGE = `Usage: lychee-norm-cache [lychee args...]
+export const EXIT_OK = 0;
+export const EXIT_DEAD_LINKS = 1;
+export const EXIT_PREFLIGHT = 2;
+
+const USAGE = `Usage: lychee-norm-cache [--migrate] [lychee args...]
 
-Run lychee over this site's built ./public output, then normalize .lycheecache
-so reruns stay byte stable. Bridges a GitHub token from the gh CLI when
-GITHUB_TOKEN isn't set; extra arguments pass through to lychee.
+Run lychee over this site's built ./public output. With a committed
+${OWNED_FILE}, the ${CSV_FILE} handed to lychee is derived from it before the
+run and folded back into it afterwards; otherwise ${CSV_FILE} is normalized in
+place (legacy mode). Bridges a GitHub token from the gh CLI when GITHUB_TOKEN
+isn't set; extra arguments pass through to lychee.
 
+  --migrate    convert an existing ${CSV_FILE} to ${OWNED_FILE} and exit
   -h, --help   show this help
 
+Exit codes: 0 success; 1 dead links; 2 preflight/sanity failure (missing
+lychee or public/, lychee config or usage errors, zero links verified).
+
+Lychee's summary must reach stdout in its default or JSON format — it is the
+wrapper's proof that a check completed — so flags that divert or reshape
+stdout (--output, --format junit, --dump-inputs, ...) are unsupported here;
+run lychee directly for those.
+
 Requires the lychee binary on your PATH and a lychee.toml at the site root.
 Run \`lychee --help\` for all link-checking options.`;
 
@@ -66,6 +92,61 @@ export function publicDirOf(cwd) {
   return publicDir;
 }
 
+// Check counts from lychee's stdout summary — the human line ("🔍 2 Total …
+// ✅ 1 OK 🚫 0 Errors …") or --format json fields; null when neither is
+// present. A parsed summary is the proof that a check actually completed.
+export function parseSummary(stdout) {
+  const m = /(\d+)\s+Total\b[\s\S]*?(\d+)\s+OK\b[\s\S]*?(\d+)\s+Errors?\b/.exec(
+    stdout,
+  );
+  if (m) return { total: +m[1], ok: +m[2], errors: +m[3] };
+  const total = /"total"\s*:\s*(\d+)/.exec(stdout);
+  const ok = /"successful"\s*:\s*(\d+)/.exec(stdout);
+  const errors = /"errors"\s*:\s*(\d+)/.exec(stdout);
+  return total && ok && errors
+    ? { total: +total[1], ok: +ok[1], errors: +errors[1] }
+    : null;
+}
+
+// Map lychee's exit code to ours (0 ok, 1 dead links, 2 preflight). A parsed
+// summary is required in every case: lychee exits 2 both for broken links and
+// for argument errors, and exits 0 from non-check modes (--dump-inputs) and
+// diverted-output runs (--output FILE, --format junit/detailed) — without the
+// summary there is no proof a check completed.
+export function mapLycheeExit(code, summary) {
+  if (!summary) return EXIT_PREFLIGHT;
+  if (code === 0) return EXIT_OK;
+  if (code === 2) return EXIT_DEAD_LINKS;
+  return EXIT_PREFLIGHT;
+}
+
+// URLs the run itself reported as failing — the human "[ERROR] URL …" lines,
+// or --format json's fail_map. Positive per-URL evidence for the merge-back's
+// failure recording; CSV absence alone proves nothing (cache_exclude_status,
+// max_cache_age, and site changes all remove entries from healthy runs).
+export function parseFailedUrls(stdout) {
+  const failed = new Set();
+  const trimmed = stdout.trim();
+  if (trimmed.startsWith('{')) {
+    try {
+      const failMap = JSON.parse(trimmed).fail_map ?? {};
+      for (const failures of Object.values(failMap)) {
+        for (const f of failures) {
+          const url = typeof f.url === 'string' ? f.url : f.url?.url;
+          if (url) failed.add(url);
+        }
+      }
+      return failed;
+    } catch {
+      // fall through to the line scan
+    }
+  }
+  for (const m of stdout.matchAll(/^\s*\[ERROR\]\s+(\S+)/gm)) {
+    failed.add(m[1]);
+  }
+  return failed;
+}
+
 // --- lychee invocation -----------------------------------------------------
 
 function ghAuthToken() {
@@ -77,39 +158,133 @@ function hasLychee() {
   return !spawnSync('lychee', ['--version'], { stdio: 'ignore' }).error;
 }
 
+function fail(message) {
+  process.stderr.write(`[help] ${message}\n`);
+  return EXIT_PREFLIGHT;
+}
+
+function migrate(cwd) {
+  const csvPath = path.join(cwd, CSV_FILE);
+  const ownedPath = path.join(cwd, OWNED_FILE);
+  if (existsSync(ownedPath)) return fail(`${OWNED_FILE} already exists.`);
+  if (!existsSync(csvPath)) return fail(`${CSV_FILE} not found.`);
+  const { text, count, malformed } = migrateCsvText(
+    readFileSync(csvPath, 'utf8'),
+  );
+  // Migration is specified lossless: refuse rather than silently drop.
+  if (malformed) {
+    return fail(
+      `${CSV_FILE} has ${malformed} malformed line(s); fix or remove them, then rerun.`,
+    );
+  }
+  writeFileAtomic(ownedPath, text);
+  console.log(
+    `Migrated ${count} entries to ${OWNED_FILE}. Commit it and gitignore ${CSV_FILE}.`,
+  );
+  return EXIT_OK;
+}
+
 function main(argv) {
   if (argv.includes('-h') || argv.includes('--help')) {
     console.log(USAGE);
-    return 0;
+    return EXIT_OK;
   }
 
+  const cwd = process.cwd();
+  if (argv.includes('--migrate')) return migrate(cwd);
+
   if (!hasLychee()) {
-    process.stderr.write(`[help] lychee not found. Install: ${INSTALL_HINT}\n`);
-    return 1;
+    return fail(`lychee not found. Install: ${INSTALL_HINT}`);
   }
 
-  const cwd = process.cwd();
   const publicDir = publicDirOf(cwd);
   if (!publicDir) {
-    process.stderr.write(
-      `[help] ${path.join(cwd, 'public')} not found. Build the site first.\n`,
+    return fail(`${path.join(cwd, 'public')} not found. Build the site first.`);
+  }
+
+  const ownedPath = path.join(cwd, OWNED_FILE);
+  const cachePath = path.join(cwd, CSV_FILE);
+  const owned = existsSync(ownedPath)
+    ? parseOwned(readFileSync(ownedPath, 'utf8'))
+    : null;
+  const now = Date.now() / 1000;
+
+  // The owned-cache lens requires lychee's cache; enforce rather than let a
+  // cacheless run erase every projected entry on merge-back.
+  const hasCacheFlag = argv.some(
+    (a) => a === '--cache' || a.startsWith('--cache='),
+  );
+  if (owned && argv.includes('--cache=false')) {
+    return fail(`--cache=false is incompatible with ${OWNED_FILE}.`);
+  }
+  const cacheArgs = hasCacheFlag ? [] : ['--cache'];
+
+  // Derive the CSV lychee will read from the owned cache.
+  if (owned) {
+    writeFileAtomic(
+      cachePath,
+      serializeCsv(projectToCsv(owned.entries, { now })),
     );
-    return 1;
   }
 
   const token = resolveToken();
-  const status =
-    spawnSync(
-      'lychee',
-      ['--config', 'lychee.toml', '--root-dir', publicDir, ...argv, publicDir],
-      { stdio: 'inherit', env: { ...process.env, GITHUB_TOKEN: token } },
-    ).status ?? 1;
-
-  // Normalize the cache even on failure, so a partial run still leaves a stable
-  // .lycheecache.
-  const cachePath = path.join(cwd, '.lycheecache');
-  if (existsSync(cachePath)) {
-    writeFileSync(cachePath, sortCacheText(readFileSync(cachePath, 'utf8')));
+  // stdout is captured for the completion/zero-check sanity checks and echoed
+  // afterwards; stderr (progress) still streams. The generous buffer bound
+  // keeps spawnSync simple; overruns surface via run.error below.
+  const run = spawnSync(
+    'lychee',
+    [
+      '--config',
+      'lychee.toml',
+      ...cacheArgs,
+      '--root-dir',
+      publicDir,
+      ...argv,
+      publicDir,
+    ],
+    {
+      stdio: ['inherit', 'pipe', 'inherit'],
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024,
+      env: { ...process.env, GITHUB_TOKEN: token },
+    },
+  );
+  if (run.stdout) process.stdout.write(run.stdout);
+  if (run.error) {
+    return fail(`lychee failed to run: ${run.error.message}`);
+  }
+  const summary = parseSummary(run.stdout ?? '');
+  const status = mapLycheeExit(run.status ?? 1, summary);
+
+  // On a preflight failure lychee produced no trustworthy results: leave both
+  // caches untouched (folding would mislabel unprojected entries as failed).
+  if (status === EXIT_PREFLIGHT) {
+    return fail('lychee did not complete a check; caches left untouched.');
+  }
+
+  // A clean run in which nothing got a verdict is a false-clean (empty or
+  // fully-excluded public/), not a success — and folding it would mislabel
+  // unattempted entries as failed, so the check precedes the fold. Cache hits
+  // count toward OK in lychee's summary, so a fully-cached run passes.
+  if (status === EXIT_OK && summary && summary.ok + summary.errors === 0) {
+    return fail('lychee verified 0 links: empty or fully-excluded public/?');
+  }
+
+  // Fold the post-run CSV back into the owned cache (also on dead links, so a
+  // completed run with failures still leaves a stable, truthful cache), or
+  // normalize the CSV in place in legacy mode.
+  if (owned) {
+    const csvEntries = existsSync(cachePath)
+      ? parseCsv(readFileSync(cachePath, 'utf8')).entries
+      : [];
+    const failedUrls = parseFailedUrls(run.stdout ?? '');
+    writeFileAtomic(
+      ownedPath,
+      serializeOwned(mergeBack(owned, csvEntries, { now, failedUrls })),
+    );
+    writeFileAtomic(cachePath, sortCacheText(readFileSync(cachePath, 'utf8')));
+  } else if (existsSync(cachePath)) {
+    writeFileAtomic(cachePath, sortCacheText(readFileSync(cachePath, 'utf8')));
   }
 
   return status;
@@ -126,5 +301,12 @@ function isEntryPoint() {
 }
 
 if (isEntryPoint()) {
-  process.exit(main(process.argv.slice(2)));
+  // Wrapper exceptions (e.g. a malformed owned cache) are preflight failures,
+  // not dead links: warn wrappers must not swallow them.
+  try {
+    process.exit(main(process.argv.slice(2)));
+  } catch (err) {
+    process.stderr.write(`[error] ${err.message}\n`);
+    process.exit(EXIT_PREFLIGHT);
+  }
 }

package/lib/cache.mjs

@@ -0,0 +1,369 @@
+// Shared cache-file model: the owned JSONC cache (link-cache.jsonc, source of
+// truth) and its derived Lychee CSV (.lycheecache). Pure functions only — no
+// I/O — so both bins and the tests share one implementation.
+//
+// Owned-file format: JSONC, pretty-printed by construction in Prettier's jsonc
+// style (2-space indent, one field per line, trailing commas), so the file
+// passes `prettier --check` untouched. Every entry is multi-line — the field
+// separation is what keeps concurrent edits merging cleanly — and whole-line
+// `//` comments attach to the entry that follows them. Entries are sorted by
+// raw URL byte order (matching LC_ALL=C). Stripping comments and trailing
+// commas yields valid JSON.
+//
+// Entry schema: { "status": INT, "when": RFC3339_UTC, "via": "RESOLVER" }
+// with an optional "expires": "YYYY-MM-DD" (manual entries). Status
+// generalizes HTTP: positive = HTTP status, 0 = unchecked, negative =
+// tool-specific error. `when` is the canonical whole-second UTC form
+// (YYYY-MM-DDTHH:MM:SSZ) — no fractional seconds, no offsets — validated
+// strictly: this tool is the file's only writer, so a non-canonical value is
+// a bug to surface, not smooth over (lesson from the htmltest-era
+// RFC3339Nano/offset churn).
+
+export const OWNED_FILE = 'link-cache.jsonc';
+export const CSV_FILE = '.lycheecache';
+
+// Tool-specific error statuses (the htmltest-fork convention).
+export const STATUS_TIMEOUT = -10;
+export const STATUS_NETWORK_ERROR = -20;
+export const STATUS_CERT_ERROR = -30;
+export const STATUS_CLIENT_ERROR = -40;
+
+const WHEN_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+
+// Epoch seconds -> canonical `when`.
+export function tsToWhen(ts) {
+  return new Date(ts * 1000).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+// Canonical `when` -> epoch seconds; NaN when non-canonical (strict: the
+// regex gates shape, and the round-trip equality check rejects impossible
+// dates that Date.parse would silently normalize, e.g. Feb 30 -> Mar 2).
+export function whenToTs(when) {
+  if (!WHEN_RE.test(when)) return NaN;
+  const ts = Date.parse(when) / 1000;
+  return tsToWhen(ts) === when ? ts : NaN;
+}
+
+const byUrlBytes = (a, b) =>
+  Buffer.compare(Buffer.from(a.url), Buffer.from(b.url));
+
+// --- CSV (.lycheecache) ------------------------------------------------------
+
+// Unquote a CSV field: lychee quotes URLs that contain a comma.
+export function csvUnquote(field) {
+  return field.startsWith('"') && field.endsWith('"')
+    ? field.slice(1, -1).replace(/""/g, '"')
+    : field;
+}
+
+export function csvQuote(url) {
+  return /[",]/.test(url) ? `"${url.replace(/"/g, '""')}"` : url;
+}
+
+// Parse one URL,STATUS,TIMESTAMP line; null when malformed. Lexically strict:
+// STATUS and TIMESTAMP must be non-empty digit runs (`Number('')` is 0, which
+// would silently coin status-0/epoch-0 entries from truncated lines).
+export function parseCsvLine(raw) {
+  const lastComma = raw.lastIndexOf(',');
+  if (lastComma < 0) return null;
+  const tsField = raw.slice(lastComma + 1);
+  const head = raw.slice(0, lastComma);
+  const statusComma = head.lastIndexOf(',');
+  if (statusComma < 0) return null;
+  const statusField = head.slice(statusComma + 1).trim();
+  if (!/^\d+$/.test(tsField) || !/^-?\d+$/.test(statusField)) return null;
+  const url = csvUnquote(head.slice(0, statusComma));
+  if (url === '') return null;
+  return { url, status: Number(statusField), ts: Number(tsField) };
+}
+
+// Parse a whole CSV cache; malformed lines are counted, duplicates keep the
+// newest timestamp.
+export function parseCsv(text) {
+  const byUrl = new Map();
+  let malformed = 0;
+  for (const raw of text.split('\n')) {
+    if (raw.trim() === '') continue;
+    const entry = parseCsvLine(raw);
+    if (!entry) {
+      malformed += 1;
+      continue;
+    }
+    const prior = byUrl.get(entry.url);
+    if (!prior || entry.ts >= prior.ts) byUrl.set(entry.url, entry);
+  }
+  return { entries: [...byUrl.values()].sort(byUrlBytes), malformed };
+}
+
+export function serializeCsv(entries) {
+  if (entries.length === 0) return '';
+  return (
+    [...entries]
+      .sort(byUrlBytes)
+      .map((e) => `${csvQuote(e.url)},${e.status},${e.ts}`)
+      .join('\n') + '\n'
+  );
+}
+
+// --- owned JSONC (link-cache.jsonc) -----------------------------------------
+
+const COMMENT_RE = /^\s*\/\//;
+// The line that opens an entry: `"URL": {` (the key is a JSON string, which
+// cannot span lines).
+const ENTRY_OPEN_RE = /^\s*("(?:[^"\\]|\\.)*")\s*:\s*\{/;
+
+// Strip a line-ending comma when the next non-blank line closes an object —
+// per-line, so commas inside URL strings are never touched (JSON strings
+// cannot span lines).
+function stripTrailingCommas(lines) {
+  const out = [...lines];
+  for (let i = 0; i < out.length; i++) {
+    if (!out[i].trimEnd().endsWith(',')) continue;
+    let j = i + 1;
+    while (j < out.length && out[j].trim() === '') j++;
+    if (j < out.length && out[j].trim().startsWith('}')) {
+      out[i] = out[i].trimEnd().slice(0, -1);
+    }
+  }
+  return out;
+}
+
+const ENTRY_FIELDS = new Set(['status', 'when', 'via', 'expires']);
+
+// A calendar-real YYYY-MM-DD (round-trip check rejects e.g. Feb 30).
+function isCanonicalDate(s) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(s)) return false;
+  const t = Date.parse(`${s}T00:00:00Z`);
+  return Number.isFinite(t) && new Date(t).toISOString().slice(0, 10) === s;
+}
+
+// Rejects unknown fields (a rewrite would silently drop them) and restricts
+// `expires` to manual entries — resolvers set statuses, owners set trust
+// windows. Relax the via restriction if a named resolver ever needs expiry.
+// Statuses live in one of three domains: HTTP (100-999, the only ones that
+// project into Lychee's CSV — Lychee rejects codes outside that range at
+// load, which would wedge the run), 0 (unchecked), negative (tool errors).
+function isValidStatus(s) {
+  return Number.isInteger(s) && (s < 0 || s === 0 || (s >= 100 && s <= 999));
+}
+
+function validateEntry(url, v) {
+  return (
+    v !== null &&
+    typeof v === 'object' &&
+    Object.keys(v).every((k) => ENTRY_FIELDS.has(k)) &&
+    isValidStatus(v.status) &&
+    typeof v.when === 'string' &&
+    Number.isFinite(whenToTs(v.when)) &&
+    whenToTs(v.when) >= 0 && // pre-epoch would project a negative CSV ts
+    typeof v.via === 'string' &&
+    (v.expires === undefined ||
+      (v.via === 'manual' && isCanonicalDate(v.expires)))
+  );
+}
+
+// Parse the owned cache. Throws on malformed content (the file is committed
+// and tool-written; silent drops would lose data on the next rewrite),
+// including blank input — a zero-byte file is a truncated write, not an empty
+// cache (that one is `{}`). Comments are collected line-wise and attached to
+// the entry whose opening `"URL": {` line follows them; comments after the
+// last entry are kept as `trailing`. Duplicate URL keys are rejected: with
+// merge=union gone, a duplicate is a bad merge resolution to surface, not a
+// leftover to paper over.
+export function parseOwned(text) {
+  if (text.trim() === '') {
+    throw new Error(`${OWNED_FILE}: blank file (truncated write?)`);
+  }
+  const lines = text.split('\n');
+
+  // Comment attachment pass; also detects duplicate keys line-wise (the JSON
+  // pass below cannot: Object.entries already collapsed them).
+  const commentsByUrl = new Map();
+  const seenUrls = new Set();
+  const trailing = [];
+  let pending = [];
+  for (const raw of lines) {
+    if (COMMENT_RE.test(raw)) {
+      pending.push(`  ${raw.trim()}`);
+      continue;
+    }
+    const open = ENTRY_OPEN_RE.exec(raw);
+    if (open) {
+      const url = JSON.parse(open[1]);
+      if (seenUrls.has(url)) {
+        throw new Error(`${OWNED_FILE}: duplicate entry for ${url}`);
+      }
+      seenUrls.add(url);
+      if (pending.length) {
+        commentsByUrl.set(url, pending);
+        pending = [];
+      }
+    }
+  }
+  trailing.push(...pending);
+
+  // Data pass: strip comments and trailing commas, then parse as JSON.
+  const dataLines = stripTrailingCommas(
+    lines.filter((l) => !COMMENT_RE.test(l)),
+  );
+  let obj;
+  try {
+    obj = JSON.parse(dataLines.join('\n') || '{}');
+  } catch (err) {
+    throw new Error(`${OWNED_FILE}: invalid JSONC: ${err.message}`);
+  }
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+    throw new Error(`${OWNED_FILE}: top level must be an object`);
+  }
+
+  const entries = [];
+  for (const [url, v] of Object.entries(obj)) {
+    if (!validateEntry(url, v)) {
+      throw new Error(`${OWNED_FILE}: malformed entry for ${url}`);
+    }
+    entries.push({
+      url,
+      status: v.status,
+      ts: whenToTs(v.when), // epoch internally; `when` re-derives on write
+      via: v.via,
+      expires: v.expires,
+      comments: commentsByUrl.get(url) ?? [],
+    });
+  }
+  return { entries: entries.sort(byUrlBytes), trailing };
+}
+
+// Canonical serialization = Prettier's jsonc style (2-space indent, one field
+// per line, trailing commas, always multi-line), so the output is
+// prettier-idempotent by construction.
+export function serializeEntry({ url, status, ts, via, expires }) {
+  const fields = [
+    `    "status": ${status},`,
+    `    "when": ${JSON.stringify(tsToWhen(ts))},`,
+    `    "via": ${JSON.stringify(via)},`,
+  ];
+  if (expires !== undefined) {
+    fields.push(`    "expires": ${JSON.stringify(expires)},`);
+  }
+  return [`  ${JSON.stringify(url)}: {`, ...fields, '  },'].join('\n');
+}
+
+export function serializeOwned({ entries, trailing = [] }) {
+  if (entries.length === 0 && trailing.length === 0) return '{}\n';
+  const lines = ['{'];
+  for (const entry of [...entries].sort(byUrlBytes)) {
+    lines.push(...(entry.comments ?? []).map((c) => `  ${c.trim()}`));
+    lines.push(serializeEntry(entry));
+  }
+  lines.push(...trailing.map((c) => `  ${c.trim()}`), '}');
+  return lines.join('\n') + '\n';
+}
+
+// --- lens: owned -> CSV projection ------------------------------------------
+
+const dateToTs = (isoDate) => Date.parse(`${isoDate}T23:59:59Z`) / 1000;
+
+// Project the owned entries into Lychee's CSV. Only positive (HTTP) statuses
+// project — Lychee never persists errors, and would re-drop the rest. An
+// unexpired entry with `expires` projects with a fresh timestamp so it
+// outlives Lychee's max_cache_age until its own expiry; once expired it is
+// omitted, forcing a live re-check.
+export function projectToCsv(entries, { now = Date.now() / 1000 } = {}) {
+  const projected = [];
+  for (const e of entries) {
+    if (e.status <= 0) continue;
+    if (e.expires !== undefined) {
+      const cutoff = dateToTs(e.expires);
+      if (!Number.isFinite(cutoff) || now > cutoff) continue;
+      projected.push({ url: e.url, status: e.status, ts: Math.floor(now) });
+      continue;
+    }
+    projected.push({ url: e.url, status: e.status, ts: e.ts });
+  }
+  return projected;
+}
+
+// --- lens: CSV -> owned merge-back ------------------------------------------
+
+// Fold a post-run CSV back into the owned entries. Rules (owner, 08-31;
+// absence-inference dropped 08-31 adversarial round):
+//   - new URL: added with via "lychee";
+//   - status changed: the whole entry is replaced (via "lychee", fresh fields,
+//     comments dropped — a stale rationale is worse than none);
+//   - status equal: provenance-bearing entries (via != "lychee") stay
+//     untouched — a re-confirmation; "lychee" entries adopt the fresh ts;
+//   - expired `expires` entry present in the CSV: replaced wholesale (the seed
+//     served its purpose);
+//   - URL in `failedUrls` (positive evidence from the run's own error report):
+//     recorded as STATUS_CLIENT_ERROR under via "lychee", keeping the entry's
+//     comments (the rationale still explains the URL);
+//   - entry missing from the CSV without failure evidence: untouched. CSV
+//     absence is ambiguous — cache_exclude_status, max_cache_age expiry, and
+//     URLs no longer in the site all remove entries from healthy runs — so it
+//     never justifies a failure verdict on its own.
+export function mergeBack(
+  owned,
+  csvEntries,
+  { now = Date.now() / 1000, failedUrls = new Set() } = {},
+) {
+  const csvByUrl = new Map(csvEntries.map((e) => [e.url, e]));
+  const merged = [];
+
+  for (const entry of owned.entries) {
+    const csv = csvByUrl.get(entry.url);
+    csvByUrl.delete(entry.url);
+
+    const expired =
+      entry.expires !== undefined &&
+      (!Number.isFinite(dateToTs(entry.expires)) ||
+        now > dateToTs(entry.expires));
+
+    if (failedUrls.has(entry.url)) {
+      merged.push({
+        url: entry.url,
+        status: STATUS_CLIENT_ERROR,
+        ts: Math.floor(now),
+        via: 'lychee',
+        comments: entry.comments ?? [],
+      });
+      continue;
+    }
+
+    if (!csv) {
+      merged.push(entry); // absent without evidence: untouched
+      continue;
+    }
+
+    if (expired || csv.status !== entry.status) {
+      merged.push({
+        url: entry.url,
+        status: csv.status,
+        ts: csv.ts,
+        via: 'lychee',
+        comments: [],
+      });
+    } else if (entry.via === 'lychee') {
+      merged.push({ ...entry, ts: csv.ts });
+    } else {
+      merged.push(entry); // re-confirmation: provenance untouched
+    }
+  }
+
+  for (const csv of csvByUrl.values()) {
+    merged.push({ ...csv, via: 'lychee', comments: [] });
+  }
+
+  return { entries: merged.sort(byUrlBytes), trailing: owned.trailing };
+}
+
+// --- migration ---------------------------------------------------------------
+
+// One-shot .lycheecache -> link-cache.jsonc: every entry becomes via "lychee".
+export function migrateCsvText(csvText) {
+  const { entries, malformed } = parseCsv(csvText);
+  const owned = {
+    entries: entries.map((e) => ({ ...e, via: 'lychee', comments: [] })),
+    trailing: [],
+  };
+  return { text: serializeOwned(owned), count: entries.length, malformed };
+}

package/lib/write.mjs

@@ -0,0 +1,12 @@
+// Atomic file write shared by the bins: write to a same-directory temp file,
+// then rename over the target. A crash mid-write leaves the original intact
+// instead of a truncated cache (which the strict parsers would then reject,
+// wedging every subsequent run).
+
+import { renameSync, writeFileSync } from 'node:fs';
+
+export function writeFileAtomic(path, text) {
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, text);
+  renameSync(tmp, path);
+}

package/{refcache → link-cache}/index.mjs

@@ -1,17 +1,25 @@
 #!/usr/bin/env node
-// The `refcache` bin: inspect and prune a Lychee refcache. Read-only unless
-// `--prune` is given, and never hits the network. Run with `--help` for usage.
+// The `link-cache` bin (deprecated alias: `refcache`): inspect and prune a
+// link cache — the owned JSONC cache (link-cache.jsonc) or a legacy Lychee CSV
+// (.lycheecache). Read-only unless `--prune` is given, and never hits the
+// network. Run with `--help` for usage.
 //
-// Refcache line format: URL,STATUS,UNIX_TIMESTAMP — the URL is CSV-quoted when
-// it contains a comma, so STATUS and TIMESTAMP are read from the final two
-// fields.
+// CSV line format: URL,STATUS,UNIX_TIMESTAMP — the URL is CSV-quoted when it
+// contains a comma, so STATUS and TIMESTAMP are read from the final two fields.
 
-import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
+import {
+  CSV_FILE,
+  OWNED_FILE,
+  parseOwned,
+  serializeOwned,
+} from '../lib/cache.mjs';
+import { writeFileAtomic } from '../lib/write.mjs';
+
 const DAY = 86400;
 const BUCKET_COUNT = 5;
-const DEFAULT_PATH = '.lycheecache';
 
 // --- parsing ---------------------------------------------------------------
 
@@ -28,9 +36,9 @@ function parseLine(raw) {
   return { url, status, ts };
 }
 
-// Parse the whole file, keeping the original lines (so a prune can rewrite the
-// file with a minimal, still-sorted diff) and tagging each entry with its line
-// index.
+// Parse a whole CSV cache, keeping the original lines (so a prune can rewrite
+// the file with a minimal, still-sorted diff) and tagging each entry with its
+// line index.
 export function parseCache(text) {
   const lines = text.split('\n');
   const entries = [];
@@ -44,7 +52,21 @@ export function parseCache(text) {
     }
     entries.push({ ...parsed, index });
   });
-  return { lines, entries, malformed };
+  return { kind: 'csv', lines, entries, malformed };
+}
+
+// Adapt the owned JSONC cache to the same entry shape (string status, index).
+export function parseOwnedCache(text) {
+  const owned = parseOwned(text);
+  const entries = owned.entries.map((e, index) => ({
+    url: e.url,
+    status: String(e.status),
+    ts: e.ts,
+    via: e.via,
+    index,
+    src: e,
+  }));
+  return { kind: 'owned', owned, entries, malformed: 0 };
 }
 
 // --- selection / pruning ---------------------------------------------------
@@ -88,20 +110,24 @@ export function computeStats(
   { now = Date.now() / 1000, malformed = 0, pruned = 0 } = {},
 ) {
   const statusCounts = new Map();
+  const viaCounts = new Map();
   const ages = [];
   let oldestTs = null;
   let newestTs = null;
 
   for (const entry of entries) {
     statusCounts.set(entry.status, (statusCounts.get(entry.status) ?? 0) + 1);
+    if (entry.via !== undefined) {
+      viaCounts.set(entry.via, (viaCounts.get(entry.via) ?? 0) + 1);
+    }
     if (oldestTs === null || entry.ts < oldestTs) oldestTs = entry.ts;
     if (newestTs === null || entry.ts > newestTs) newestTs = entry.ts;
     ages.push(Math.floor((now - entry.ts) / DAY));
   }
 
-  const byStatus = [...statusCounts.entries()].sort(
-    (a, b) => b[1] - a[1] || a[0].localeCompare(b[0]),
-  );
+  const desc = (a, b) => b[1] - a[1] || a[0].localeCompare(b[0]);
+  const byStatus = [...statusCounts.entries()].sort(desc);
+  const byVia = [...viaCounts.entries()].sort(desc);
 
   const at = (ts) =>
     ts === null ? null : { ts, ageDays: Math.floor((now - ts) / DAY) };
@@ -112,6 +138,7 @@ export function computeStats(
     malformed,
     pruned,
     byStatus,
+    byVia,
     oldest,
     newest: at(newestTs),
     ageBuckets: ageHistogram(ages, oldest ? oldest.ageDays : 0),
@@ -145,14 +172,15 @@ export function formatList(entries, n, { now = Date.now() / 1000 } = {}) {
   const head = `${chosen.length} oldest ${chosen.length === 1 ? 'entry' : 'entries'}:`;
   const rows = chosen.map((e) => {
     const ageDays = Math.floor((now - e.ts) / DAY);
-    return `  ${localStamp(e.ts)}  ${String(ageDays).padStart(4)}d  ${e.status}  ${displayUrl(e.url)}`;
+    const via = e.via !== undefined ? `  ${e.via}` : '';
+    return `  ${localStamp(e.ts)}  ${String(ageDays).padStart(4)}d  ${e.status}${via}  ${displayUrl(e.url)}`;
   });
   return [head, ...rows].join('\n');
 }
 
 export function formatStats(stats, { now = Date.now() / 1000, path } = {}) {
   const lines = [];
-  lines.push(`Lychee refcache${path ? `: ${path}` : ''}`);
+  lines.push(`Link cache${path ? `: ${path}` : ''}`);
   lines.push(`  Entries: ${stats.count}`);
   if (stats.pruned) {
     const before = stats.count + stats.pruned;
@@ -174,6 +202,14 @@ export function formatStats(stats, { now = Date.now() / 1000, path } = {}) {
     lines.push(`    ${status.padEnd(5)} ${n}`);
   }
 
+  if (stats.byVia?.length) {
+    lines.push('  Via:');
+    const w = Math.max(...stats.byVia.map(([via]) => via.length));
+    for (const [via, n] of stats.byVia) {
+      lines.push(`    ${via.padEnd(w)}  ${n}`);
+    }
+  }
+
   if (stats.ageBuckets.length) {
     lines.push('  Age:');
     const w = Math.max(...stats.ageBuckets.map((b) => b.label.length));
@@ -187,19 +223,33 @@ export function formatStats(stats, { now = Date.now() / 1000, path } = {}) {
 
 // --- ordered execution -----------------------------------------------------
 
-// Run the parsed ops in order over the evolving cache. Pure: returns the text to
-// print and the lines to write (null when nothing was pruned); no I/O.
-export function runOps(parsed, ops, { now = Date.now() / 1000, path } = {}) {
+// Run the parsed ops in order over the evolving cache, optionally scoped to
+// URLs matching `match`. Pure: returns the text to print and the text to write
+// (null when nothing was pruned); no I/O.
+export function runOps(
+  parsed,
+  ops,
+  { now = Date.now() / 1000, path, match = null } = {},
+) {
   const removed = new Set();
   let pruned = 0;
   const out = [];
-  const current = () => parsed.entries.filter((e) => !removed.has(e.index));
+  // Match against the unquoted URL: legacy-CSV entries carry the raw
+  // (possibly CSV-quoted) field, which would defeat anchored regexes.
+  const inScope = (e) => (match ? match.test(displayUrl(e.url)) : true);
+  const current = () =>
+    parsed.entries.filter((e) => !removed.has(e.index) && inScope(e));
 
   for (const op of ops) {
     if (op.kind === 'list') {
       out.push(formatList(current(), Number(op.value), { now }));
     } else if (op.kind === 'prune') {
-      const cur = current();
+      // Manual entries are exempt: pruning schedules re-checks for
+      // lychee-verified entries, while a manual entry's lifecycle is owned by
+      // its author and its `expires` date — and under prune-refresh rotation
+      // re-confirmed seeds keep their original timestamp, so they'd otherwise
+      // age to the front and get evicted mid-lifecycle.
+      const cur = current().filter((e) => e.via !== 'manual');
       const k = resolvePruneCount(op.value, cur.length);
       for (const victim of selectOldest(cur, k)) removed.add(victim.index);
       pruned += k;
@@ -216,9 +266,24 @@ export function runOps(parsed, ops, { now = Date.now() / 1000, path } = {}) {
     }
   }
 
-  const writeLines =
-    pruned > 0 ? parsed.lines.filter((_, i) => !removed.has(i)) : null;
-  return { output: out.join('\n\n'), writeLines, pruned };
+  let writeText = null;
+  if (pruned > 0) {
+    // Survivors are all unpruned entries — including those outside the
+    // --match scope, which the scope only shields from ops, never from the
+    // rewrite.
+    const survivors = parsed.entries.filter((e) => !removed.has(e.index));
+    if (parsed.kind === 'owned') {
+      // Comments of surviving entries travel with them; pruned entries take
+      // their comment lines along.
+      writeText = serializeOwned({
+        entries: survivors.map((e) => e.src),
+        trailing: parsed.owned.trailing,
+      });
+    } else {
+      writeText = parsed.lines.filter((_, i) => !removed.has(i)).join('\n');
+    }
+  }
+  return { output: out.join('\n\n'), writeText, pruned };
 }
 
 // --- CLI -------------------------------------------------------------------
@@ -226,6 +291,8 @@ export function runOps(parsed, ops, { now = Date.now() / 1000, path } = {}) {
 const FLAGS = new Map([
   ['-l', 'list'],
   ['--list', 'list'],
+  ['-m', 'match'],
+  ['--match', 'match'],
   ['-p', 'prune'],
   ['--prune', 'prune'],
   ['-s', 'summary'],
@@ -236,6 +303,7 @@ export function parseArgs(argv) {
   const ops = [];
   const seen = new Set();
   let path = null;
+  let match = null;
   let help = false;
 
   for (let i = 0; i < argv.length; i++) {
@@ -254,6 +322,14 @@ export function parseArgs(argv) {
       }
       const value = argv[++i];
       if (value === undefined) throw new Error(`${a} requires a value`);
+      if (kind === 'match') {
+        try {
+          match = new RegExp(value);
+        } catch (err) {
+          throw new Error(`--match needs a valid regex: ${err.message}`);
+        }
+        continue;
+      }
       if (kind === 'list' && !/^\d+$/.test(value)) {
         throw new Error(`--list needs a count, got: ${value}`);
       }
@@ -268,23 +344,26 @@ export function parseArgs(argv) {
     path = a;
   }
 
-  return { ops, path: path ?? DEFAULT_PATH, help };
+  return { ops, path, match, help };
 }
 
-const USAGE = `Usage: refcache [REFCACHE_FILE] [options]
+const USAGE = `Usage: link-cache [CACHE_FILE] [options]
 
-Inspect and prune a Lychee refcache (default: ${DEFAULT_PATH}). Options run in
-the order given, over the evolving cache, so \`-l 5 -p 5\` lists the 5 oldest
-about to be pruned, while \`-p 5 -l 5\` lists the next 5 after pruning.
+Inspect and prune a link cache: the owned ${OWNED_FILE} (default when present)
+or a legacy Lychee CSV like ${CSV_FILE}. Options run in the order given, over
+the evolving cache, so \`-l 5 -p 5\` lists the 5 oldest about to be pruned,
+while \`-p 5 -l 5\` lists the next 5 after pruning.
 
   -l, --list NUM        list the NUM oldest entries
-  -p, --prune NUM[%]    drop the NUM (or NUM%) oldest entries, then rewrite
-  -s, --summary         print a summary (counts, ages, status, histogram)
+  -m, --match REGEX     scope all operations to URLs matching REGEX
+  -p, --prune NUM[%]    drop the NUM (or NUM%) oldest non-manual entries, then
+                        rewrite (manual entries retire via their expires date)
+  -s, --summary         print a summary (counts, ages, status, via, histogram)
   -h, --help            show this help
 
 With no options, prints the summary. A flag may not be repeated.`;
 
-function main(argv) {
+export function main(argv) {
   let args;
   try {
     args = parseArgs(argv);
@@ -298,23 +377,35 @@ function main(argv) {
     return;
   }
 
+  const path = args.path ?? (existsSync(OWNED_FILE) ? OWNED_FILE : CSV_FILE);
+
   let text;
   try {
-    text = readFileSync(args.path, 'utf8');
+    text = readFileSync(path, 'utf8');
   } catch {
-    console.error(`[error] cannot read refcache file: ${args.path}`);
+    console.error(`[error] cannot read cache file: ${path}`);
+    process.exit(1);
+  }
+
+  const isOwned = path.endsWith('.jsonc') || text.trimStart().startsWith('{');
+  let parsed;
+  try {
+    parsed = isOwned ? parseOwnedCache(text) : parseCache(text);
+  } catch (err) {
+    console.error(`[error] ${err.message}`);
     process.exit(1);
   }
 
   const now = Date.now() / 1000;
   const ops = args.ops.length ? args.ops : [{ kind: 'summary' }];
-  const { output, writeLines } = runOps(parseCache(text), ops, {
+  const { output, writeText } = runOps(parsed, ops, {
     now,
-    path: args.path,
+    path,
+    match: args.match,
   });
 
   if (output) console.log(output);
-  if (writeLines) writeFileSync(args.path, writeLines.join('\n'));
+  if (writeText !== null) writeFileAtomic(path, writeText);
 }
 
 // Real-path compare, not `file://${argv[1]}`: npm links bins as symlinks, so

package/link-cache/refcache.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// The deprecated `refcache` alias bin: warn, then delegate to link-cache. A
+// dedicated wrapper (not an argv[1] sniff) so the notice also fires under
+// npm's Windows shims, which invoke the target file directly.
+
+import { main } from './index.mjs';
+
+process.stderr.write(
+  '[warn] the refcache bin is deprecated; use link-cache instead.\n',
+);
+main(process.argv.slice(2));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "link-cache",
-  "version": "0.3.0",
-  "description": "Zero-dependency helper CLIs for cached Lychee link-checking: lychee-norm-cache (run + normalize .lycheecache) and refcache (inspect/prune the cache).",
+  "version": "0.4.1",
+  "description": "Zero-dependency helper CLIs for cached Lychee link-checking around an owned JSONC cache (link-cache.jsonc) with provenance: lychee-norm-cache (run + sync caches) and link-cache (inspect/prune).",
   "keywords": [
     "lychee",
     "link-checker",
@@ -17,16 +17,21 @@
   "type": "module",
   "bin": {
     "lychee-norm-cache": "check/index.mjs",
-    "refcache": "refcache/index.mjs"
+    "link-cache": "link-cache/index.mjs",
+    "refcache": "link-cache/refcache.mjs"
   },
   "files": [
     "check/index.mjs",
-    "refcache/index.mjs"
+    "lib/cache.mjs",
+    "lib/write.mjs",
+    "link-cache/index.mjs",
+    "link-cache/refcache.mjs"
   ],
   "scripts": {
     "check": "npm run check:format && npm test",
     "check:format": "prettier --check .",
     "fix:format": "prettier --write .",
+    "install:safe": "npm ci --ignore-scripts --no-audit --no-fund",
     "test": "node --test"
   },
   "prettier": {