@git-stunts/git-warp 10.1.2 → 10.4.2

package/src/infrastructure/adapters/CasSeekCacheAdapter.js

@@ -0,0 +1,311 @@
+/**
+ * CAS-backed seek materialization cache adapter.
+ *
+ * Implements SeekCachePort using @git-stunts/git-cas for persistent storage
+ * of serialized WarpStateV5 snapshots. Each cached state is stored as a CAS
+ * asset (chunked blobs + manifest tree), and an index ref tracks the mapping
+ * from cache keys to tree OIDs.
+ *
+ * Index ref: `refs/warp/<graphName>/seek-cache` → blob containing JSON index.
+ *
+ * Blobs are loose Git objects — `git gc` prunes them using the configured
+ * prune expiry (default ~2 weeks). Use vault pinning for GC-safe persistence.
+ *
+ * **Requires Node >= 22.0.0** (inherited from `@git-stunts/git-cas`).
+ *
+ * @module infrastructure/adapters/CasSeekCacheAdapter
+ */
+
+import SeekCachePort from '../../ports/SeekCachePort.js';
+import { buildSeekCacheRef } from '../../domain/utils/RefLayout.js';
+import { Readable } from 'node:stream';
+
+const DEFAULT_MAX_ENTRIES = 200;
+const INDEX_SCHEMA_VERSION = 1;
+const MAX_CAS_RETRIES = 3;
+
+/**
+ * @typedef {Object} IndexEntry
+ * @property {string} treeOid - Git tree OID of the CAS asset
+ * @property {string} createdAt - ISO 8601 timestamp
+ * @property {number} ceiling - Lamport ceiling tick
+ * @property {string} frontierHash - Hex hash portion of the cache key
+ * @property {number} sizeBytes - Serialized state size in bytes
+ * @property {string} codec - Codec identifier (e.g. 'cbor-v1')
+ * @property {number} schemaVersion - Index entry schema version
+ * @property {string} [lastAccessedAt] - ISO 8601 timestamp of last read (for LRU eviction)
+ */
+
+/**
+ * @typedef {Object} CacheIndex
+ * @property {number} schemaVersion - Index-level schema version
+ * @property {Record<string, IndexEntry>} entries - Map of cacheKey → entry
+ */
+
+export default class CasSeekCacheAdapter extends SeekCachePort {
+  /**
+   * @param {{ persistence: *, plumbing: *, graphName: string, maxEntries?: number }} options
+   */
+  constructor({ persistence, plumbing, graphName, maxEntries }) {
+    super();
+    this._persistence = persistence;
+    this._plumbing = plumbing;
+    this._graphName = graphName;
+    this._maxEntries = maxEntries ?? DEFAULT_MAX_ENTRIES;
+    this._ref = buildSeekCacheRef(graphName);
+    this._casPromise = null;
+  }
+
+  /**
+   * Lazily initializes the ContentAddressableStore.
+   * @private
+   * @returns {Promise<*>}
+   */
+  async _getCas() {
+    if (!this._casPromise) {
+      this._casPromise = this._initCas().catch((err) => {
+        this._casPromise = null;
+        throw err;
+      });
+    }
+    return await this._casPromise;
+  }
+
+  /**
+   * @private
+   * @returns {Promise<*>}
+   */
+  async _initCas() {
+    const { default: ContentAddressableStore } = await import(
+      /* webpackIgnore: true */ '@git-stunts/git-cas'
+    );
+    return ContentAddressableStore.createCbor({ plumbing: this._plumbing });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Index management
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Reads the current cache index from the ref.
+   * @private
+   * @returns {Promise<CacheIndex>}
+   */
+  async _readIndex() {
+    const oid = await this._persistence.readRef(this._ref);
+    if (!oid) {
+      return { schemaVersion: INDEX_SCHEMA_VERSION, entries: {} };
+    }
+    try {
+      const buf = await this._persistence.readBlob(oid);
+      const parsed = JSON.parse(buf.toString('utf8'));
+      if (parsed.schemaVersion !== INDEX_SCHEMA_VERSION) {
+        return { schemaVersion: INDEX_SCHEMA_VERSION, entries: {} };
+      }
+      return parsed;
+    } catch {
+      return { schemaVersion: INDEX_SCHEMA_VERSION, entries: {} };
+    }
+  }
+
+  /**
+   * Writes the cache index blob and updates the ref.
+   * @private
+   * @param {CacheIndex} index - The index to write
+   * @returns {Promise<void>}
+   */
+  async _writeIndex(index) {
+    const json = JSON.stringify(index);
+    const oid = await this._persistence.writeBlob(Buffer.from(json, 'utf8'));
+    await this._persistence.updateRef(this._ref, oid);
+  }
+
+  /**
+   * Mutates the index with retry on write failure.
+   *
+   * Note: this adapter is single-writer — concurrent index mutations from
+   * separate processes may lose updates. The retry loop handles transient
+   * I/O errors (e.g. temporary lock contention), not true CAS conflicts.
+   *
+   * @private
+   * @param {function(CacheIndex): CacheIndex} mutate - Mutation function applied to current index
+   * @returns {Promise<CacheIndex>} The mutated index
+   */
+  async _mutateIndex(mutate) {
+    /** @type {*} */ // TODO(ts-cleanup): type CAS retry error
+    let lastErr;
+    for (let attempt = 0; attempt < MAX_CAS_RETRIES; attempt++) {
+      const index = await this._readIndex();
+      const mutated = mutate(index);
+      try {
+        await this._writeIndex(mutated);
+        return mutated;
+      } catch (err) {
+        lastErr = err;
+        // Transient write failure — retry with fresh read
+        if (attempt === MAX_CAS_RETRIES - 1) {
+          throw new Error(`CasSeekCacheAdapter: index update failed after retries: ${lastErr.message}`);
+        }
+      }
+    }
+    /* c8 ignore next - unreachable */
+    throw new Error('CasSeekCacheAdapter: index update failed');
+  }
+
+  /**
+   * Evicts oldest entries when index exceeds maxEntries.
+   * @private
+   * @param {CacheIndex} index
+   * @returns {CacheIndex}
+   */
+  _enforceMaxEntries(index) {
+    const keys = Object.keys(index.entries);
+    if (keys.length <= this._maxEntries) {
+      return index;
+    }
+    // Sort by last access (or creation) ascending — evict least recently used
+    const sorted = keys.sort((a, b) => {
+      const ea = index.entries[a];
+      const eb = index.entries[b];
+      const ta = ea.lastAccessedAt || ea.createdAt || '';
+      const tb = eb.lastAccessedAt || eb.createdAt || '';
+      return ta < tb ? -1 : ta > tb ? 1 : 0;
+    });
+    const toEvict = sorted.slice(0, keys.length - this._maxEntries);
+    for (const k of toEvict) {
+      delete index.entries[k];
+    }
+    return index;
+  }
+
+  /**
+   * Parses ceiling and frontierHash from a versioned cache key.
+   * @private
+   * @param {string} key - e.g. 'v1:t42-abcdef...'
+   * @returns {{ ceiling: number, frontierHash: string }}
+   */
+  _parseKey(key) {
+    const colonIdx = key.indexOf(':');
+    const rest = colonIdx >= 0 ? key.slice(colonIdx + 1) : key;
+    const dashIdx = rest.indexOf('-');
+    const ceiling = parseInt(rest.slice(1, dashIdx), 10);
+    const frontierHash = rest.slice(dashIdx + 1);
+    return { ceiling, frontierHash };
+  }
+
+  // ---------------------------------------------------------------------------
+  // SeekCachePort implementation
+  // ---------------------------------------------------------------------------
+
+  /**
+   * @override
+   * @param {string} key
+   * @returns {Promise<Buffer|null>}
+   */
+  async get(key) {
+    const cas = await this._getCas();
+    const index = await this._readIndex();
+    const entry = index.entries[key];
+    if (!entry) {
+      return null;
+    }
+
+    try {
+      const manifest = await cas.readManifest({ treeOid: entry.treeOid });
+      const { buffer } = await cas.restore({ manifest });
+      // Update lastAccessedAt for LRU eviction ordering
+      await this._mutateIndex((idx) => {
+        if (idx.entries[key]) {
+          idx.entries[key].lastAccessedAt = new Date().toISOString();
+        }
+        return idx;
+      });
+      return buffer;
+    } catch {
+      // Blob GC'd or corrupted — self-heal by removing dead entry
+      await this._mutateIndex((idx) => {
+        delete idx.entries[key];
+        return idx;
+      });
+      return null;
+    }
+  }
+
+  /**
+   * @override
+   * @param {string} key
+   * @param {Buffer} buffer
+   * @returns {Promise<void>}
+   */
+  async set(key, buffer) {
+    const cas = await this._getCas();
+    const { ceiling, frontierHash } = this._parseKey(key);
+
+    // Store buffer as CAS asset
+    const source = Readable.from([buffer]);
+    const manifest = await cas.store({
+      source,
+      slug: key,
+      filename: 'state.cbor',
+    });
+    const treeOid = await cas.createTree({ manifest });
+
+    // Update index with rich metadata
+    await this._mutateIndex((index) => {
+      index.entries[key] = {
+        treeOid,
+        createdAt: new Date().toISOString(),
+        ceiling,
+        frontierHash,
+        sizeBytes: buffer.length,
+        codec: 'cbor-v1',
+        schemaVersion: INDEX_SCHEMA_VERSION,
+      };
+      return this._enforceMaxEntries(index);
+    });
+  }
+
+  /**
+   * @override
+   * @param {string} key
+   * @returns {Promise<boolean>}
+   */
+  async has(key) {
+    const index = await this._readIndex();
+    return key in index.entries;
+  }
+
+  /** @override */
+  async keys() {
+    const index = await this._readIndex();
+    return Object.keys(index.entries);
+  }
+
+  /**
+   * @override
+   * @param {string} key
+   * @returns {Promise<boolean>}
+   */
+  async delete(key) {
+    let existed = false;
+    await this._mutateIndex((index) => {
+      existed = key in index.entries;
+      delete index.entries[key];
+      return index;
+    });
+    return existed;
+  }
+
+  /**
+   * Removes the index ref. CAS tree/blob objects are left as loose Git
+   * objects and will be pruned by `git gc` (default expiry ~2 weeks).
+   * @override
+   */
+  async clear() {
+    try {
+      await this._persistence.deleteRef(this._ref);
+    } catch {
+      // Ref may not exist — that's fine
+    }
+  }
+}

package/src/infrastructure/adapters/ClockAdapter.js

@@ -15,7 +15,7 @@ import ClockPort from '../../ports/ClockPort.js';
 export default class ClockAdapter extends ClockPort {
   /**
    * @param {object} [options]
-   * @param {Performance} [options.performanceImpl] - Performance API implementation.
+   * @param {{ now(): number }} [options.performanceImpl] - Performance API implementation.
    *   Defaults to `globalThis.performance`.
    */
   constructor({ performanceImpl } = {}) {
@@ -28,7 +28,7 @@ export default class ClockAdapter extends ClockPort {
    * @returns {ClockAdapter}
    */
   static node() {
-    return new ClockAdapter({ performanceImpl: nodePerformance });
+    return new ClockAdapter({ performanceImpl: /** @type {{ now(): number }} */ (nodePerformance) });
   }
 
   /**

package/src/infrastructure/adapters/DenoHttpAdapter.js

@@ -46,9 +46,10 @@ async function readStreamBody(bodyStream) {
  * HttpServerPort request handlers.
  *
  * @param {Request} request - Deno Request object
- * @returns {Promise<{ method: string, url: string, headers: Object, body: Uint8Array|undefined }>}
+ * @returns {Promise<{ method: string, url: string, headers: Record<string, string>, body: Uint8Array|undefined }>}
  */
 async function toPlainRequest(request) {
+  /** @type {Record<string, string>} */
   const headers = {};
   request.headers.forEach((value, key) => {
     headers[key] = value;
@@ -75,11 +76,11 @@ async function toPlainRequest(request) {
 /**
  * Converts a plain-object response from the handler into a Deno Response.
  *
- * @param {{ status?: number, headers?: Object, body?: string|Uint8Array }} plain
+ * @param {{ status?: number, headers?: Record<string, string>, body?: string|Uint8Array|null }} plain
  * @returns {Response}
  */
 function toDenoResponse(plain) {
-  return new Response(plain.body ?? null, {
+  return new Response(/** @type {BodyInit | null} */ (plain.body ?? null), {
     status: plain.status || 200,
     headers: plain.headers || {},
   });
@@ -99,7 +100,7 @@ function createHandler(requestHandler, logger) {
       const plain = await toPlainRequest(request);
       const response = await requestHandler(plain);
       return toDenoResponse(response);
-    } catch (err) {
+    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type error
       if (err.status === 413) {
         const msg = new TextEncoder().encode('Payload Too Large');
         return new Response(msg, {
@@ -122,7 +123,7 @@ function createHandler(requestHandler, logger) {
 /**
  * Gracefully shuts down the Deno HTTP server.
  *
- * @param {object} state - Shared mutable state `{ server }`
+ * @param {{ server: *}} state - Shared mutable state `{ server }`
  * @param {Function} [callback]
  */
 function closeImpl(state, callback) {
@@ -139,7 +140,7 @@ function closeImpl(state, callback) {
         callback();
       }
     },
-    (err) => {
+    /** @param {*} err */ (err) => {
       state.server = null;
       if (callback) {
         callback(err);
@@ -151,7 +152,7 @@ function closeImpl(state, callback) {
 /**
  * Returns the server's bound address info.
  *
- * @param {object} state - Shared mutable state `{ server }`
+ * @param {{ server: * }} state - Shared mutable state `{ server }`
  * @returns {{ address: string, port: number, family: string }|null}
  */
 function addressImpl(state) {
@@ -189,17 +190,27 @@ export default class DenoHttpAdapter extends HttpServerPort {
     this._logger = logger || noopLogger;
   }
 
-  /** @inheritdoc */
+  /**
+   * @param {Function} requestHandler
+   * @returns {{ listen: Function, close: Function, address: Function }}
+   */
   createServer(requestHandler) {
     const handler = createHandler(requestHandler, this._logger);
+    /** @type {{ server: * }} */
     const state = { server: null };
 
     return {
+      /**
+       * @param {number} port
+       * @param {string|Function} [host]
+       * @param {Function} [callback]
+       */
       listen: (port, host, callback) => {
         const cb = typeof host === 'function' ? host : callback;
         const hostname = typeof host === 'string' ? host : undefined;
 
         try {
+          /** @type {*} */ // TODO(ts-cleanup): type Deno.serve options
           const serveOptions = {
             port,
             onListen() {
@@ -212,8 +223,9 @@ export default class DenoHttpAdapter extends HttpServerPort {
             serveOptions.hostname = hostname;
           }
 
+          // @ts-expect-error — Deno global is only available in Deno runtime
           state.server = globalThis.Deno.serve(serveOptions, handler);
-        } catch (err) {
+        } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type error
           if (cb) {
             cb(err);
           } else {
@@ -221,6 +233,7 @@ export default class DenoHttpAdapter extends HttpServerPort {
           }
         }
       },
+      /** @param {Function} [callback] */
       close: (callback) => {
         closeImpl(state, callback);
       },

package/src/infrastructure/adapters/GitGraphAdapter.js

@@ -73,9 +73,13 @@ const TRANSIENT_ERROR_PATTERNS = [
   'connection timed out',
 ];
 
+/**
+ * @typedef {Error & { details?: { stderr?: string, code?: number }, exitCode?: number, code?: number }} GitError
+ */
+
 /**
  * Determines if an error is transient and safe to retry.
- * @param {Error} error - The error to check
+ * @param {GitError} error - The error to check
  * @returns {boolean} True if the error is transient
  */
 function isTransientError(error) {
@@ -102,7 +106,7 @@ const DEFAULT_RETRY_OPTIONS = {
 /**
  * Extracts the exit code from a Git command error.
  * Checks multiple possible locations where the exit code may be stored.
- * @param {Error} err - The error object
+ * @param {GitError} err - The error object
  * @returns {number|undefined} The exit code if found
  */
 function getExitCode(err) {
@@ -120,7 +124,7 @@ async function refExists(execute, ref) {
   try {
     await execute({ args: ['show-ref', '--verify', '--quiet', ref] });
     return true;
-  } catch (err) {
+  } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type error
     if (getExitCode(err) === 1) {
       return false;
     }
@@ -164,11 +168,6 @@ async function refExists(execute, ref) {
  * synchronization, and the retry logic handles lock contention gracefully.
  *
  * @extends GraphPersistencePort
- * @implements {CommitPort}
- * @implements {BlobPort}
- * @implements {TreePort}
- * @implements {RefPort}
- * @implements {ConfigPort}
  * @see {@link GraphPersistencePort} for the abstract interface contract
  * @see {@link DEFAULT_RETRY_OPTIONS} for retry configuration details
  *
@@ -198,19 +197,7 @@ export default class GitGraphAdapter extends GraphPersistencePort {
   /**
    * Creates a new GitGraphAdapter instance.
    *
-   * @param {Object} options - Configuration options
-   * @param {import('@git-stunts/plumbing').default} options.plumbing - The Git plumbing
-   *   instance to use for executing Git commands. Must be initialized with a valid
-   *   repository path.
-   * @param {import('@git-stunts/alfred').RetryOptions} [options.retryOptions={}] - Custom
-   *   retry options to override the defaults. Useful for tuning retry behavior based
-   *   on deployment environment:
-   *   - `retries` (number): Maximum retry attempts (default: 3)
-   *   - `delay` (number): Initial delay in ms (default: 100)
-   *   - `maxDelay` (number): Maximum delay cap in ms (default: 2000)
-   *   - `backoff` ('exponential'|'linear'|'constant'): Backoff strategy
-   *   - `jitter` ('full'|'decorrelated'|'none'): Jitter strategy
-   *   - `shouldRetry` (function): Custom predicate for retryable errors
+   * @param {{ plumbing: *, retryOptions?: Object }} options - Configuration options
    *
    * @throws {Error} If plumbing is not provided
    *
@@ -447,6 +434,7 @@ export default class GitGraphAdapter extends GraphPersistencePort {
    */
   async readTree(treeOid) {
     const oids = await this.readTreeOids(treeOid);
+    /** @type {Record<string, Buffer>} */
     const files = {};
     // Process sequentially to avoid spawning thousands of concurrent readBlob calls
     for (const [path, oid] of Object.entries(oids)) {
@@ -468,6 +456,7 @@ export default class GitGraphAdapter extends GraphPersistencePort {
       args: ['ls-tree', '-r', '-z', treeOid]
     });
 
+    /** @type {Record<string, string>} */
     const oids = {};
     // NUL-separated records: "mode type oid\tpath\0"
     const records = output.split('\0');
@@ -534,7 +523,7 @@ export default class GitGraphAdapter extends GraphPersistencePort {
         args: ['rev-parse', ref]
       });
       return oid.trim();
-    } catch (err) {
+    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type error
       if (getExitCode(err) === 1) {
         return null;
       }
@@ -607,7 +596,7 @@ export default class GitGraphAdapter extends GraphPersistencePort {
     try {
       await this._executeWithRetry({ args: ['cat-file', '-e', sha] });
       return true;
-    } catch (err) {
+    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type error
       if (getExitCode(err) === 1) {
         return false;
       }
@@ -683,7 +672,7 @@ export default class GitGraphAdapter extends GraphPersistencePort {
         args: ['merge-base', '--is-ancestor', potentialAncestor, descendant]
       });
       return true;  // Exit code 0 means it IS an ancestor
-    } catch (err) {
+    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type error
       if (this._getExitCode(err) === 1) {
         return false; // Exit code 1 means it is NOT an ancestor
       }
@@ -705,7 +694,7 @@ export default class GitGraphAdapter extends GraphPersistencePort {
       });
       // Preserve empty-string values; only drop trailing newline
       return value.replace(/\n$/, '');
-    } catch (err) {
+    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type error
       if (this._isConfigKeyNotFound(err)) {
         return null;
       }
@@ -757,7 +746,7 @@ export default class GitGraphAdapter extends GraphPersistencePort {
   /**
    * Extracts the exit code from a Git command error.
    * Delegates to the standalone getExitCode helper.
-   * @param {Error} err - The error object
+   * @param {GitError} err - The error object
    * @returns {number|undefined} The exit code if found
    * @private
    */
@@ -768,7 +757,7 @@ export default class GitGraphAdapter extends GraphPersistencePort {
   /**
    * Checks if an error indicates a config key was not found.
    * Exit code 1 from `git config --get` means the key doesn't exist.
-   * @param {Error} err - The error object
+   * @param {GitError} err - The error object
    * @returns {boolean} True if the error indicates key not found
    * @private
    */

package/src/infrastructure/adapters/NodeCryptoAdapter.js

@@ -13,19 +13,32 @@ import {
  * @extends CryptoPort
  */
 export default class NodeCryptoAdapter extends CryptoPort {
-  /** @inheritdoc */
+  /**
+   * @param {string} algorithm
+   * @param {string|Buffer|Uint8Array} data
+   * @returns {Promise<string>}
+   */
   // eslint-disable-next-line @typescript-eslint/require-await -- async ensures sync throws become rejected promises
   async hash(algorithm, data) {
     return createHash(algorithm).update(data).digest('hex');
   }
 
-  /** @inheritdoc */
+  /**
+   * @param {string} algorithm
+   * @param {string|Buffer|Uint8Array} key
+   * @param {string|Buffer|Uint8Array} data
+   * @returns {Promise<Buffer>}
+   */
   // eslint-disable-next-line @typescript-eslint/require-await -- async ensures sync throws become rejected promises
   async hmac(algorithm, key, data) {
     return createHmac(algorithm, key).update(data).digest();
   }
 
-  /** @inheritdoc */
+  /**
+   * @param {Buffer|Uint8Array} a
+   * @param {Buffer|Uint8Array} b
+   * @returns {boolean}
+   */
   timingSafeEqual(a, b) {
     return nodeTimingSafeEqual(a, b);
   }

package/src/infrastructure/adapters/NodeHttpAdapter.js

@@ -7,6 +7,9 @@ const MAX_BODY_BYTES = 10 * 1024 * 1024;
 /**
  * Collects the request body and dispatches to the handler, returning
  * a 500 response if the handler throws.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {{ handler: Function, logger: { error: Function } }} options
  */
 async function dispatch(req, res, { handler, logger }) {
   try {
@@ -60,33 +63,52 @@ export default class NodeHttpAdapter extends HttpServerPort {
     this._logger = logger || noopLogger;
   }
 
-  /** @inheritdoc */
+  /**
+   * @param {Function} requestHandler
+   * @returns {{ listen: Function, close: Function, address: Function }}
+   */
   createServer(requestHandler) {
     const logger = this._logger;
     const server = createServer((req, res) => {
-      dispatch(req, res, { handler: requestHandler, logger }).catch((err) => {
-        logger.error('[NodeHttpAdapter] unhandled dispatch error:', err);
-      });
+      dispatch(req, res, { handler: requestHandler, logger }).catch(
+        /** @param {*} err */ (err) => {
+          logger.error('[NodeHttpAdapter] unhandled dispatch error:', err);
+        });
     });
 
     return {
+      /**
+       * @param {number} port
+       * @param {string|Function} [host]
+       * @param {Function} [callback]
+       */
       listen(port, host, callback) {
         const cb = typeof host === 'function' ? host : callback;
         const bindHost = typeof host === 'string' ? host : undefined;
+        /** @param {*} err */
         const onError = (err) => {
           if (cb) {
             cb(err);
           }
         };
         server.once('error', onError);
-        const args = bindHost !== undefined ? [port, bindHost] : [port];
-        server.listen(...args, () => {
-          server.removeListener('error', onError);
-          if (cb) {
-            cb(null);
-          }
-        });
+        if (bindHost !== undefined) {
+          server.listen(port, bindHost, () => {
+            server.removeListener('error', onError);
+            if (cb) {
+              cb(null);
+            }
+          });
+        } else {
+          server.listen(port, () => {
+            server.removeListener('error', onError);
+            if (cb) {
+              cb(null);
+            }
+          });
+        }
       },
+      /** @param {((err?: Error) => void)} [callback] */
       close(callback) {
         server.close(callback);
       },