perf(scripts): cache registry responses so --check runs in 0.05s instead of 29s (#3062)

`--check` makes one HTTPS request per tracked component — 46 round trips
for a run that is almost entirely I/O wait: 28.6s wall against 0.13s of
user time. That is enough friction that nobody runs the status command,
which rather defeats having one.

Responses are now cached under `node_modules/.cache/shadcn-sync/`, keyed
by source URL, with a 60-minute TTL:

  cold (empty cache)   26.86s   0 cached, 46 fetched
  warm                  0.05s  46 cached,  0 fetched
  --no-cache           28.74s   0 cached, 46 fetched

`node_modules/.cache/` is the conventional home: already gitignored
(verified via git check-ignore), and a clean install discards it, which
is the right lifetime for a cache.

The load-bearing detail is that `allowCache` gates READS only, and only
read-only commands pass it. `--check` and `--diff` may answer from cache;
`--update` and `--update-all` never do. A stale `--check` is a slightly
out-of-date status line, but a stale `--update` would put hour-old code
on disk under a message saying it is current. Writes still refresh the
entry, so an update leaves the cache warm for the next check.

Proved that split by poisoning the cached `button` entry:
`--check` reported button as 51-line modified — it reads the cache — while
`--update button` ignored the poison entirely, wrote the real upstream
content (clean tree, zero POISONED lines), and write-refreshed the entry.

Degradation is quiet by design: a missing, unreadable or corrupt entry
falls through to the network (garbage file → 45 cached, 1 fetched, exit
0), and a cache directory that cannot be written never fails the run.
Expiry verified by ageing every entry to 61 minutes — 0 cached, 46
fetched.

The summary always reports where the data came from. A run that returns
in 50ms is otherwise indistinguishable from one that silently fetched
nothing.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: os-zhuang

scripts/shadcn-sync.js

@@ -18,13 +18,15 @@
  *   --backup          Create backup before updating
  *   --force           Overwrite even when local edits would be lost
  *   --no-verify       Skip the type-check that runs after an update
+ *   --no-cache        Bypass cached registry responses (--check / --diff)
  */
 
 import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import https from 'https';
 import { spawnSync } from 'child_process';
+import crypto from 'crypto';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -34,6 +36,21 @@ const COMPONENTS_DIR = path.join(REPO_ROOT, 'packages/components/src/ui');
 const MANIFEST_PATH = path.join(REPO_ROOT, 'packages/components/shadcn-components.json');
 const BACKUP_DIR = path.join(REPO_ROOT, 'packages/components/.backup');
 
+/**
+ * Registry response cache.
+ *
+ * `--check` makes one request per tracked component — 46 round trips for a
+ * run that is otherwise pure I/O wait (28.6s wall, 0.13s of it user time).
+ * That is enough friction to stop people running it, which defeats the point
+ * of having a status command at all.
+ *
+ * Lives under `node_modules/.cache/` by convention: already gitignored, and a
+ * clean install discards it, which is the right lifetime for a cache.
+ */
+const CACHE_DIR = path.join(REPO_ROOT, 'node_modules/.cache/shadcn-sync');
+const CACHE_TTL_MS = 60 * 60 * 1000;
+const cacheStats = { hits: 0, misses: 0 };
+
 // ANSI color codes
 const colors = {
   reset: '\x1b[0m',
@@ -73,6 +90,48 @@ async function fetchUrl(url) {
   });
 }
 
+function cacheFileFor(url) {
+  return path.join(CACHE_DIR, `${crypto.createHash('sha1').update(url).digest('hex').slice(0, 16)}.json`);
+}
+
+/**
+ * Fetch a registry entry, optionally serving it from the on-disk cache.
+ *
+ * ⚠️ `allowCache` controls READING only. Writes always refresh the entry, so a
+ * command that must see live data (`--update`) still warms the cache for the
+ * next `--check`.
+ *
+ * The read/write split is the safety property: read-only commands may answer
+ * from a cached copy, but nothing that writes a component file ever does.
+ * A stale `--check` is a mildly out-of-date status line; a stale `--update`
+ * would put hour-old code on disk under a message saying it is current.
+ */
+async function fetchRegistry(url, { allowCache = false } = {}) {
+  if (allowCache) {
+    try {
+      const entry = JSON.parse(await fs.readFile(cacheFileFor(url), 'utf-8'));
+      if (typeof entry?.fetchedAt === 'number' && Date.now() - entry.fetchedAt < CACHE_TTL_MS) {
+        cacheStats.hits++;
+        return entry.data;
+      }
+    } catch {
+      /* absent, unreadable or corrupt — fall through and refetch */
+    }
+  }
+
+  const data = await fetchUrl(url);
+  cacheStats.misses++;
+
+  try {
+    await fs.mkdir(CACHE_DIR, { recursive: true });
+    await fs.writeFile(cacheFileFor(url), JSON.stringify({ url, fetchedAt: Date.now(), data }));
+  } catch {
+    /* the cache is an optimisation; never fail a run because it can't be written */
+  }
+
+  return data;
+}
+
 async function loadManifest() {
   try {
     const content = await fs.readFile(MANIFEST_PATH, 'utf-8');
@@ -215,7 +274,7 @@ function verifyPackageCompiles({ backup } = {}) {
   return false;
 }
 
-async function checkComponent(name, manifest) {
+async function checkComponent(name, manifest, options = {}) {
   const componentInfo = manifest.components[name];
   if (!componentInfo) {
     return {
@@ -232,7 +291,7 @@ async function checkComponent(name, manifest) {
 
     // Fetch latest from registry
     try {
-      const registryData = await fetchUrl(componentInfo.source);
+      const registryData = await fetchRegistry(componentInfo.source, { allowCache: options.allowCache });
       // Rewrite before comparing, so import-path style alone does not read as
       // a difference — the local file has already been through this transform.
       const shadcnContent = rewriteRegistryImports(registryData.files?.[0]?.content || '');
@@ -300,7 +359,7 @@ async function checkComponent(name, manifest) {
   }
 }
 
-async function checkAllComponents() {
+async function checkAllComponents(options = {}) {
   logSection('Checking Components Status');
 
   const manifest = await loadManifest();
@@ -319,7 +378,7 @@ async function checkAllComponents() {
   };
 
   for (const component of localComponents) {
-    const result = await checkComponent(component, manifest);
+    const result = await checkComponent(component, manifest, options);
     results[result.status].push(result);
 
     const symbol = {
@@ -349,6 +408,17 @@ async function checkAllComponents() {
   log(`● Custom:    ${results.custom.length} components (not tracked upstream)`, 'blue');
   log(`✗ Errors:    ${results.error.length} components`, 'red');
 
+  // A run that returns in under a second is otherwise indistinguishable from
+  // one that silently fetched nothing, so always say where the data came from.
+  if (cacheStats.hits > 0 || cacheStats.misses > 0) {
+    const ttlMin = Math.round(CACHE_TTL_MS / 60000);
+    log(
+      `\nRegistry: ${cacheStats.hits} cached, ${cacheStats.misses} fetched ` +
+        `(cache TTL ${ttlMin}min — --no-cache to force live)`,
+      'dim',
+    );
+  }
+
   // The actionable bucket: upstream moved and nothing local is at risk.
   if (results.outdated.length > 0) {
     log('\nSafe to sync now:', 'cyan');
@@ -403,8 +473,9 @@ async function updateComponent(name, manifest, options = {}) {
 
   try {
     // Fetch from registry
-    const registryData = await fetchUrl(componentInfo.source);
-    
+    // allowCache omitted on purpose: a write must never come from a cached copy.
+    const registryData = await fetchRegistry(componentInfo.source);
+
     if (!registryData.files || registryData.files.length === 0) {
       log(`No files found in registry for ${name}`, 'red');
       return false;
@@ -551,7 +622,7 @@ async function updateAllComponents(options = {}) {
   }
 }
 
-async function showDiff(name) {
+async function showDiff(name, options = {}) {
   logSection(`Component Diff: ${name}`);
 
   const manifest = await loadManifest();
@@ -565,7 +636,7 @@ async function showDiff(name) {
   try {
     const localPath = path.join(COMPONENTS_DIR, `${name}.tsx`);
     const localContent = await fs.readFile(localPath, 'utf-8');
-    const registryData = await fetchUrl(componentInfo.source);
+    const registryData = await fetchRegistry(componentInfo.source, { allowCache: options.allowCache });
     // Same transform `--update` would apply, so the two sides are comparable.
     const shadcnContent = rewriteRegistryImports(registryData.files?.[0]?.content || '');
 
@@ -607,9 +678,11 @@ async function listComponents() {
 // Main CLI
 async function main() {
   const args = process.argv.slice(2);
-  
+  // Read-only commands may answer from cache; --no-cache forces live fetches.
+  const allowCache = !args.includes('--no-cache');
+
   if (args.length === 0 || args.includes('--check')) {
-    await checkAllComponents();
+    await checkAllComponents({ allowCache });
   } else if (args.includes('--update-all')) {
     const backup = args.includes('--backup');
     const verify = !args.includes('--no-verify');
@@ -637,7 +710,7 @@ async function main() {
       log('Error: --diff requires a component name', 'red');
       process.exit(1);
     }
-    await showDiff(componentName);
+    await showDiff(componentName, { allowCache });
   } else if (args.includes('--list')) {
     await listComponents();
   } else if (args.includes('--help') || args.includes('-h')) {
@@ -652,6 +725,7 @@ async function main() {
     console.log('  --backup             Create backup before updating');
     console.log('  --force              Overwrite even if local edits would be lost');
     console.log('  --no-verify          Skip the post-update type-check');
+    console.log('  --no-cache           Bypass the cached registry responses (--check/--diff)');
     console.log('  --help, -h           Show this help message\n');
   } else {
     log('Unknown option. Use --help for usage information.', 'red');