fix(cache): use readable origin keys instead of truncated base64 (#17)

The previous scheme encoded origins as the first 8 characters of
base64(full URL), which caused all HTTPS registries to collide on
"aHR0cHM6" (the base64 of "https://").

New scheme produces readable, collision-resistant keys:
- Format: [http~]hostname[~port][~path~segments]
- Segments truncated: <=5 chars kept whole, else first 3 + last 2
- HTTPS implicit, only http~ prefix for HTTP origins
- npm alias preserved for registry.npmjs.com/org, replicate.npmjs.com

Examples:
  https://registry.npmjs.com         -> npm
  https://packages.example.com/js    -> paces.exale.com~js
  http://localhost:4873              -> http~locst~4873
  https://host.jfrog.io/art/api/npm  -> host.jfrog.io~art~api~npm

Backward compatibility:
- Old base64 keys (without . or ~) decode to <legacy:...>
- No migration needed; old cache entries become orphans

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: indexzero

src/cache/cache-key.js

@@ -5,6 +5,23 @@
 
 const CACHE_KEY_VERSION = 'v1';
 
+const NPM_HOSTS = new Set([
+  'registry.npmjs.com',
+  'registry.npmjs.org',
+  'replicate.npmjs.com'
+]);
+
+/**
+ * Truncate a segment for compact cache keys
+ * If segment is 5 chars or less, keep whole. Otherwise, first 3 + last 2.
+ * @param {string} segment - Segment to truncate
+ * @returns {string} Truncated segment
+ */
+function truncateSegment(segment) {
+  if (segment.length <= 5) return segment;
+  return segment.slice(0, 3) + segment.slice(-2);
+}
+
 /**
  * Create a cache key for a partition
  * @param {string} startKey - Start key of the partition
@@ -16,7 +33,7 @@ export function createPartitionKey(startKey, endKey, origin = 'https://replicate
   const originKey = encodeOrigin(origin);
   const startHex = encodeKeySegment(startKey);
   const endHex = encodeKeySegment(endKey);
-  
+
   return `${CACHE_KEY_VERSION}:partition:${originKey}:${startHex}:${endHex}`;
 }
 
@@ -29,30 +46,53 @@ export function createPartitionKey(startKey, endKey, origin = 'https://replicate
 export function createPackumentKey(packageName, origin = 'https://registry.npmjs.com') {
   const originKey = encodeOrigin(origin);
   const nameHex = encodeKeySegment(packageName);
-  
+
   return `${CACHE_KEY_VERSION}:packument:${originKey}:${nameHex}`;
 }
 
 /**
- * Encode origin URL to short key
+ * Encode origin URL to short, readable key
+ * Format: [http~]hostname[~port][~path~segments]
+ * - HTTPS is implicit (only prefix http~ for HTTP)
+ * - Each segment truncated: <=5 chars kept whole, else first 3 + last 2
+ * - Hostname uses . separator, port/path use ~ separator
  * @param {string} origin - Full origin URL
  * @returns {string} Short origin key
  */
 function encodeOrigin(origin) {
-  // Use short aliases for common registries
-  if (origin === 'https://replicate.npmjs.com') return 'npm';
-  if (origin === 'https://registry.npmjs.org') return 'npm';
-  if (origin === 'https://registry.npmjs.com') return 'npm';
-  
-  // For custom registries, use first 8 chars of base64url
-  const encoder = new TextEncoder();
-  const bytes = encoder.encode(origin);
-  // Simple base64url encoding for edge compatibility
-  const base64 = btoa(String.fromCharCode(...bytes))
-    .replace(/\+/g, '-')
-    .replace(/\//g, '_')
-    .replace(/=/g, '');
-  return base64.substring(0, 8);
+  // Handle bare hostnames (no protocol)
+  if (!origin.includes('://')) {
+    origin = 'https://' + origin;
+  }
+
+  const url = new URL(origin);
+  const hostname = url.hostname.toLowerCase();
+  const isHttp = url.protocol === 'http:';
+  const isDefaultPort =
+    !url.port ||
+    (url.protocol === 'https:' && url.port === '443') ||
+    (url.protocol === 'http:' && url.port === '80');
+  const pathSegments = url.pathname.split('/').filter(Boolean);
+
+  // Check npm alias
+  if (NPM_HOSTS.has(hostname) && isDefaultPort && pathSegments.length === 0) {
+    return 'npm';
+  }
+
+  // Truncate hostname segments (split by .)
+  const truncatedHost = hostname
+    .split('.')
+    .map(truncateSegment)
+    .join('.');
+
+  // Build parts array
+  const parts = [];
+  if (isHttp) parts.push('http');
+  parts.push(truncatedHost);
+  if (!isDefaultPort && url.port) parts.push(url.port);
+  parts.push(...pathSegments.map(truncateSegment));
+
+  return parts.join('~');
 }
 
 /**
@@ -103,16 +143,35 @@ export function decodeCacheKey(cacheKey) {
 }
 
 /**
- * Decode origin from short key
+ * Decode origin from short key (best-effort reconstruction)
+ * Handles both old base64 format and new readable format
  * @param {string} originKey - Short origin key
- * @returns {string} Full origin URL
+ * @returns {string} Reconstructed origin URL (may not match original exactly)
  */
 function decodeOrigin(originKey) {
   if (originKey === 'npm') return 'https://registry.npmjs.com';
-  
-  // For custom registries, decode from base64url
-  // Note: This is lossy - we only stored first 8 chars
-  return `<custom:${originKey}>`;
+
+  // Detect new readable format: contains '.' (hostname) or '~' (separator)
+  if (originKey.includes('.') || originKey.includes('~')) {
+    // New readable format
+    const isHttp = originKey.startsWith('http~');
+    const protocol = isHttp ? 'http://' : 'https://';
+    const remainder = isHttp ? originKey.slice(5) : originKey;
+
+    // Split on ~ to get hostname and path/port parts
+    const parts = remainder.split('~');
+    const hostname = parts[0];
+    const rest = parts.slice(1);
+
+    // Reconstruct URL (note: truncated segments cannot be fully recovered)
+    if (rest.length === 0) {
+      return `${protocol}${hostname}`;
+    }
+    return `${protocol}${hostname}/${rest.join('/')}`;
+  }
+
+  // Old base64 format - cannot decode meaningfully
+  return `<legacy:${originKey}>`;
 }
 
 /**

src/cache/test/cache-key.test.js

@@ -101,11 +101,22 @@ describe('Cache Key Utilities', () => {
       assert.equal(decoded.origin, 'https://registry.npmjs.com');
     });
 
-    it('should handle custom origins as lossy', () => {
-      const key = createPartitionKey('a', 'b', 'https://very-long-custom-registry.example.com');
+    it('should handle custom origins with readable format', () => {
+      const key = createPartitionKey('a', 'b', 'https://packages.example.com/javascript');
       const decoded = decodeCacheKey(key);
-      
-      assert.ok(decoded.origin.startsWith('<custom:'));
+
+      // Decoded origin is best-effort reconstruction from truncated segments
+      assert.ok(decoded.origin.includes('paces.exale.com'));
+      assert.ok(decoded.origin.includes('javpt'));
+    });
+
+    it('should handle legacy base64 origin keys', () => {
+      // Simulate decoding an old-format key by calling decodeCacheKey directly
+      // Old keys had base64 origins like 'aHR0cHM6' that can't contain '.' or '~'
+      const legacyKey = 'v1:packument:aHR0cHM6:657870726573';
+      const decoded = decodeCacheKey(legacyKey);
+
+      assert.ok(decoded.origin.startsWith('<legacy:'));
     });
 
     it('should throw on invalid format', () => {
@@ -121,6 +132,63 @@ describe('Cache Key Utilities', () => {
     });
   });
 
+  describe('origin encoding scheme', () => {
+    it('should use npm alias for npm registries', () => {
+      const key1 = createPackumentKey('test', 'https://registry.npmjs.com');
+      const key2 = createPackumentKey('test', 'https://registry.npmjs.org');
+      const key3 = createPackumentKey('test', 'https://replicate.npmjs.com');
+
+      assert.ok(key1.includes(':npm:'));
+      assert.ok(key2.includes(':npm:'));
+      assert.ok(key3.includes(':npm:'));
+    });
+
+    it('should truncate segments: <=5 chars kept whole, else first 3 + last 2', () => {
+      // 'packages' (8 chars) -> 'pac' + 'es' = 'paces'
+      // 'example' (7 chars) -> 'exa' + 'le' = 'exale'
+      // 'com' (3 chars) -> 'com'
+      // 'javascript' (10 chars) -> 'jav' + 'pt' = 'javpt'
+      const key = createPackumentKey('test', 'https://packages.example.com/javascript');
+      assert.ok(key.includes(':paces.exale.com~javpt:'));
+    });
+
+    it('should handle http protocol with prefix', () => {
+      const key = createPackumentKey('test', 'http://localhost:4873');
+      assert.ok(key.includes(':http~locst~4873:'));
+    });
+
+    it('should handle multiple path segments', () => {
+      const key = createPackumentKey('test', 'https://mycompany.jfrog.io/artifactory/api/npm/npm-local');
+      // mycompany -> mycom + 'ny' = myany? No wait: first 3 + last 2 = 'myc' + 'ny' = 'mycny'
+      // Actually: 'mycompany' is 9 chars -> 'myc' + 'ny' = 'mycny'
+      // 'jfrog' is 5 chars -> 'jfrog'
+      // 'artifactory' is 11 chars -> 'art' + 'ry' = 'artry'
+      // 'api' is 3 chars -> 'api'
+      // 'npm' is 3 chars -> 'npm'
+      // 'npm-local' is 9 chars -> 'npm' + 'al' = 'npmal'
+      assert.ok(key.includes('mycny.jfrog.io~artry~api~npm~npmal'));
+    });
+
+    it('should handle bare hostnames by assuming https', () => {
+      const key = createPackumentKey('test', 'my-registry.com');
+      assert.ok(key.includes(':my-ry.com:'));
+    });
+
+    it('should omit default ports', () => {
+      const key1 = createPackumentKey('test', 'https://example.com:443');
+      const key2 = createPackumentKey('test', 'http://example.com:80');
+
+      // Should not contain port numbers for default ports
+      assert.ok(!key1.includes('443'));
+      assert.ok(!key2.includes('80'));
+    });
+
+    it('should preserve non-default ports', () => {
+      const key = createPackumentKey('test', 'https://example.com:8443');
+      assert.ok(key.includes('~8443'));
+    });
+  });
+
   describe('hex encoding edge cases', () => {
     it('should handle unicode correctly', () => {
       const key = createPackumentKey('😀emoji');