@git-stunts/git-warp 11.2.1 → 11.5.0

package/src/domain/warp/provenance.methods.js

@@ -13,6 +13,8 @@ import { createEmptyStateV5, reduceV5 } from '../services/JoinReducer.js';
 import { ProvenancePayload } from '../services/ProvenancePayload.js';
 import { decodePatchMessage, detectMessageKind } from '../services/WarpMessageCodec.js';
 
+/** @typedef {import('../types/WarpTypesV2.js').PatchV2} PatchV2 */
+
 /**
  * Returns all patch SHAs that affected a given node or edge.
  *
@@ -184,7 +186,7 @@ export async function _computeBackwardCone(nodeId) {
       cone.set(sha, patch);
 
       // Add read dependencies to the queue
-      const patchReads = /** @type {any} */ (patch)?.reads; // TODO(ts-cleanup): type patch array
+      const patchReads = /** @type {{reads?: string[]}} */ (patch).reads;
       if (patchReads) {
         for (const readEntity of patchReads) {
           if (!visited.has(readEntity)) {
@@ -261,8 +263,8 @@ export async function _loadPatchesBySha(shas) {
  * This ensures deterministic ordering regardless of discovery order.
  *
  * @this {import('../WarpGraph.js').default}
- * @param {Array<{patch: any, sha: string}>} patches - Unsorted patch entries
- * @returns {Array<{patch: any, sha: string}>} Sorted patch entries
+ * @param {Array<{patch: PatchV2, sha: string}>} patches - Unsorted patch entries
+ * @returns {Array<{patch: PatchV2, sha: string}>} Sorted patch entries
  */
 export function _sortPatchesCausally(patches) {
   return [...patches].sort((a, b) => {

package/src/domain/warp/query.methods.js

@@ -8,7 +8,7 @@
  */
 
 import { orsetContains, orsetElements } from '../crdt/ORSet.js';
-import { decodePropKey, isEdgePropKey, decodeEdgePropKey, encodeEdgeKey, decodeEdgeKey } from '../services/KeyCodec.js';
+import { decodePropKey, isEdgePropKey, decodeEdgePropKey, encodeEdgeKey, decodeEdgeKey, CONTENT_PROPERTY_KEY } from '../services/KeyCodec.js';
 import { compareEventIds } from '../utils/EventId.js';
 import { cloneStateV5 } from '../services/JoinReducer.js';
 import QueryBuilder from '../services/QueryBuilder.js';
@@ -37,7 +37,7 @@ export async function hasNode(nodeId) {
  *
  * @this {import('../WarpGraph.js').default}
  * @param {string} nodeId - The node ID to get properties for
- * @returns {Promise<Map<string, *>|null>} Map of property key → value, or null if node doesn't exist
+ * @returns {Promise<Map<string, unknown>|null>} Map of property key → value, or null if node doesn't exist
  * @throws {import('../errors/QueryError.js').default} If no cached state exists (code: `E_NO_STATE`)
  */
 export async function getNodeProps(nodeId) {
@@ -66,7 +66,7 @@ export async function getNodeProps(nodeId) {
  * @param {string} from - Source node ID
  * @param {string} to - Target node ID
  * @param {string} label - Edge label
- * @returns {Promise<Record<string, *>|null>} Object of property key → value, or null if edge doesn't exist
+ * @returns {Promise<Record<string, unknown>|null>} Object of property key → value, or null if edge doesn't exist
  * @throws {import('../errors/QueryError.js').default} If no cached state exists (code: `E_NO_STATE`)
  */
 export async function getEdgeProps(from, to, label) {
@@ -85,7 +85,7 @@ export async function getEdgeProps(from, to, label) {
 
   const birthEvent = s.edgeBirthEvent?.get(edgeKey);
 
-  /** @type {Record<string, any>} */
+  /** @type {Record<string, unknown>} */
   const props = {};
   for (const [propKey, register] of s.prop) {
     if (!isEdgePropKey(propKey)) {
@@ -177,7 +177,7 @@ export async function getNodes() {
  * Gets all visible edges in the materialized state.
  *
  * @this {import('../WarpGraph.js').default}
- * @returns {Promise<Array<{from: string, to: string, label: string, props: Record<string, *>}>>} Array of edge info
+ * @returns {Promise<Array<{from: string, to: string, label: string, props: Record<string, unknown>}>>} Array of edge info
  * @throws {import('../errors/QueryError.js').default} If no cached state exists (code: `E_NO_STATE`)
  */
 export async function getEdges() {
@@ -275,5 +275,88 @@ export async function observer(name, config) {
  */
 export async function translationCost(configA, configB) {
   await this._ensureFreshState();
-  return computeTranslationCost(configA, configB, this._cachedState);
+  const s = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (this._cachedState);
+  return computeTranslationCost(configA, configB, s);
+}
+
+/**
+ * Gets the content blob OID for a node, or null if none is attached.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} nodeId - The node ID to check
+ * @returns {Promise<string|null>} Hex blob OID or null
+ * @throws {import('../errors/QueryError.js').default} If no cached state exists (code: `E_NO_STATE`)
+ */
+export async function getContentOid(nodeId) {
+  const props = await getNodeProps.call(this, nodeId);
+  if (!props) {
+    return null;
+  }
+  // getNodeProps returns a Map — use .get() for property access
+  const oid = props.get(CONTENT_PROPERTY_KEY);
+  return (typeof oid === 'string') ? oid : null;
+}
+
+/**
+ * Gets the content blob for a node, or null if none is attached.
+ *
+ * Returns the raw Buffer from `readBlob()`. Consumers wanting text
+ * should call `.toString('utf8')` on the result.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} nodeId - The node ID to get content for
+ * @returns {Promise<Buffer|null>} Content buffer or null
+ * @throws {Error} If the referenced blob OID is not in the object store
+ *   (e.g., garbage-collected despite anchoring). Callers should handle this
+ *   if operating on repos with aggressive GC or partial clones.
+ */
+export async function getContent(nodeId) {
+  const oid = await getContentOid.call(this, nodeId);
+  if (!oid) {
+    return null;
+  }
+  return await this._persistence.readBlob(oid);
+}
+
+/**
+ * Gets the content blob OID for an edge, or null if none is attached.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} from - Source node ID
+ * @param {string} to - Target node ID
+ * @param {string} label - Edge label
+ * @returns {Promise<string|null>} Hex blob OID or null
+ * @throws {import('../errors/QueryError.js').default} If no cached state exists (code: `E_NO_STATE`)
+ */
+export async function getEdgeContentOid(from, to, label) {
+  const props = await getEdgeProps.call(this, from, to, label);
+  if (!props) {
+    return null;
+  }
+  // getEdgeProps returns a plain object — use bracket access
+  const oid = props[CONTENT_PROPERTY_KEY];
+  return (typeof oid === 'string') ? oid : null;
+}
+
+/**
+ * Gets the content blob for an edge, or null if none is attached.
+ *
+ * Returns the raw Buffer from `readBlob()`. Consumers wanting text
+ * should call `.toString('utf8')` on the result.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} from - Source node ID
+ * @param {string} to - Target node ID
+ * @param {string} label - Edge label
+ * @returns {Promise<Buffer|null>} Content buffer or null
+ * @throws {Error} If the referenced blob OID is not in the object store
+ *   (e.g., garbage-collected despite anchoring). Callers should handle this
+ *   if operating on repos with aggressive GC or partial clones.
+ */
+export async function getEdgeContent(from, to, label) {
+  const oid = await getEdgeContentOid.call(this, from, to, label);
+  if (!oid) {
+    return null;
+  }
+  return await this._persistence.readBlob(oid);
 }

package/src/domain/warp/sync.methods.js

@@ -31,6 +31,9 @@ import { buildWriterRef } from '../utils/RefLayout.js';
 import { collectGCMetrics } from '../services/GCMetrics.js';
 import HttpSyncServer from '../services/HttpSyncServer.js';
 import { signSyncRequest, canonicalizePath } from '../services/SyncAuthService.js';
+import { isError } from '../types/WarpErrors.js';
+
+/** @typedef {import('../types/WarpPersistence.js').CorePersistence} CorePersistence */
 
 // ── Private helpers ─────────────────────────────────────────────────────────
 
@@ -221,10 +224,12 @@ export async function createSyncRequest() {
  */
 export async function processSyncRequest(request) {
   const localFrontier = await this.getFrontier();
+  /** @type {CorePersistence} */
+  const persistence = this._persistence;
   return await processSyncRequestImpl(
     request,
     localFrontier,
-    /** @type {any} */ (this._persistence), // TODO(ts-cleanup): narrow port type
+    persistence,
     this._graphName,
     { codec: this._codec }
   );
@@ -253,7 +258,7 @@ export function applySyncResponse(response) {
     });
   }
 
-  const currentFrontier = /** @type {any} */ (this._cachedState.observedFrontier); // TODO(ts-cleanup): narrow port type
+  const currentFrontier = /** @type {Map<string, string>} */ (/** @type {unknown} */ (this._cachedState.observedFrontier));
   const result = /** @type {{state: import('../services/JoinReducer.js').WarpStateV5, frontier: Map<string, string>, applied: number}} */ (applySyncResponseImpl(response, this._cachedState, currentFrontier));
 
   // Update cached state
@@ -352,12 +357,12 @@ export async function syncWith(remote, options = {}) {
     targetUrl.hash = '';
   }
   let attempt = 0;
-  const emit = (/** @type {string} */ type, /** @type {Record<string, any>} */ payload = {}) => {
+  const emit = (/** @type {string} */ type, /** @type {Record<string, unknown>} */ payload = {}) => {
     if (typeof onStatus === 'function') {
-      onStatus(/** @type {any} */ ({ type, attempt, ...payload })); // TODO(ts-cleanup): type sync protocol
+      onStatus(/** @type {{type: string, attempt: number}} */ ({ type, attempt, ...payload }));
     }
   };
-  const shouldRetry = (/** @type {any} */ err) => { // TODO(ts-cleanup): type error
+  const shouldRetry = (/** @type {unknown} */ err) => {
     if (isDirectPeer) { return false; }
     if (err instanceof SyncError) {
       return ['E_SYNC_REMOTE', 'E_SYNC_TIMEOUT', 'E_SYNC_NETWORK'].includes(err.code);
@@ -400,7 +405,7 @@ export async function syncWith(remote, options = {}) {
           });
         });
       } catch (err) {
-        if (/** @type {any} */ (err)?.name === 'AbortError') { // TODO(ts-cleanup): type error
+        if (isError(err) && err.name === 'AbortError') {
           throw new OperationAbortedError('syncWith', { reason: 'Signal received' });
         }
         if (err instanceof TimeoutError) {
@@ -411,7 +416,7 @@ export async function syncWith(remote, options = {}) {
         }
         throw new SyncError('Network error', {
           code: 'E_SYNC_NETWORK',
-          context: { message: /** @type {any} */ (err)?.message }, // TODO(ts-cleanup): type error
+          context: { message: isError(err) ? err.message : String(err) },
         });
       }
 
@@ -474,7 +479,7 @@ export async function syncWith(remote, options = {}) {
       shouldRetry,
       onRetry: (/** @type {Error} */ error, /** @type {number} */ attemptNumber, /** @type {number} */ delayMs) => {
         if (typeof onStatus === 'function') {
-          onStatus(/** @type {any} */ ({ type: 'retrying', attempt: attemptNumber, delayMs, error })); // TODO(ts-cleanup): type sync protocol
+          onStatus(/** @type {{type: string, attempt: number, delayMs: number, error: Error}} */ ({ type: 'retrying', attempt: attemptNumber, delayMs, error }));
         }
       },
     });
@@ -488,7 +493,7 @@ export async function syncWith(remote, options = {}) {
     return syncResult;
   } catch (err) {
     this._logTiming('syncWith', t0, { error: /** @type {Error} */ (err) });
-    if (/** @type {any} */ (err)?.name === 'AbortError') { // TODO(ts-cleanup): type error
+    if (isError(err) && err.name === 'AbortError') {
       const abortedError = new OperationAbortedError('syncWith', { reason: 'Signal received' });
       if (typeof onStatus === 'function') {
         onStatus({ type: 'failed', attempt, error: abortedError });
@@ -518,13 +523,13 @@ export async function syncWith(remote, options = {}) {
  * @param {string} [options.host='127.0.0.1'] - Host to bind
  * @param {string} [options.path='/sync'] - Path to handle sync requests
  * @param {number} [options.maxRequestBytes=4194304] - Max request size in bytes
- * @param {import('../../ports/HttpServerPort.js').default} options.httpPort - HTTP server adapter (required)
+ * @param {import('../../ports/HttpServerPort.js').default} options.httpPort - HTTP server adapter
  * @param {{ keys: Record<string, string>, mode?: 'enforce'|'log-only' }} [options.auth] - Auth configuration
  * @returns {Promise<{close: () => Promise<void>, url: string}>} Server handle
  * @throws {Error} If port is not a number
  * @throws {Error} If httpPort adapter is not provided
  */
-export async function serve({ port, host = '127.0.0.1', path = '/sync', maxRequestBytes = DEFAULT_SYNC_SERVER_MAX_BYTES, httpPort, auth } = /** @type {any} */ ({})) { // TODO(ts-cleanup): needs options type
+export async function serve({ port, host = '127.0.0.1', path = '/sync', maxRequestBytes = DEFAULT_SYNC_SERVER_MAX_BYTES, httpPort, auth } = /** @type {{ port: number, httpPort: import('../../ports/HttpServerPort.js').default }} */ ({})) {
   if (typeof port !== 'number') {
     throw new Error('serve() requires a numeric port');
   }

package/src/globals.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Minimal ambient declarations for Deno and Bun runtime globals.
+ *
+ * These cover ONLY the APIs actually used in this codebase:
+ *   - Deno.serve()          (DenoHttpAdapter.js)
+ *   - Deno.env.get()        (bin/cli/infrastructure.js)
+ *   - Bun.serve()           (BunHttpAdapter.js)
+ *
+ * Do NOT install @types/deno or @types/bun — this file is intentionally
+ * narrow to avoid pulling in thousands of unrelated declarations.
+ */
+
+/* ------------------------------------------------------------------ */
+/*  Deno                                                              */
+/* ------------------------------------------------------------------ */
+
+interface DenoAddr {
+  transport: string;
+  hostname: string;
+  port: number;
+}
+
+interface DenoServer {
+  shutdown(): Promise<void>;
+  addr: DenoAddr;
+}
+
+interface DenoServeOptions {
+  port?: number;
+  hostname?: string;
+  onListen?: () => void;
+}
+
+interface DenoEnv {
+  get(name: string): string | undefined;
+}
+
+declare namespace Deno {
+  const env: DenoEnv;
+  function serve(
+    options: DenoServeOptions,
+    handler: (request: Request) => Promise<Response> | Response,
+  ): DenoServer;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Bun                                                               */
+/* ------------------------------------------------------------------ */
+
+interface BunServer {
+  stop(closeActiveConnections?: boolean): Promise<void>;
+  hostname: string;
+  port: number;
+}
+
+interface BunServeOptions {
+  port?: number;
+  hostname?: string;
+  fetch: (request: Request) => Promise<Response> | Response;
+}
+
+declare namespace Bun {
+  function serve(options: BunServeOptions): BunServer;
+}

package/src/infrastructure/adapters/BunHttpAdapter.js

@@ -106,8 +106,8 @@ function createFetchHandler(requestHandler, logger) {
       const portReq = await toPortRequest(request);
       const portRes = await requestHandler(portReq);
       return toResponse(portRes);
-    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type error
-      if (err.status === 413) {
+    } catch (err) {
+      if (typeof err === 'object' && err !== null && /** @type {{status?: number}} */ (err).status === 413) {
         return new Response(PAYLOAD_TOO_LARGE, {
           status: 413,
           headers: { 'Content-Type': 'text/plain', 'Content-Length': PAYLOAD_TOO_LARGE_LENGTH },
@@ -125,6 +125,10 @@ function createFetchHandler(requestHandler, logger) {
   };
 }
 
+/**
+ * @typedef {{ hostname: string, port: number, stop: (closeActiveConnections?: boolean) => Promise<void> }} BunServer
+ */
+
 /**
  * Starts a Bun server and invokes the callback with (null) on success
  * or (err) on failure.
@@ -132,12 +136,11 @@ function createFetchHandler(requestHandler, logger) {
  * Note: Bun.serve() is synchronous, so cb fires on the same tick
  * (unlike Node's server.listen which defers via the event loop).
  *
- * @param {*} serveOptions
+ * @param {BunServeOptions} serveOptions
  * @param {Function|undefined} cb - Node-style callback
- * @returns {*} The Bun server instance
+ * @returns {BunServer} The Bun server instance
  */
 function startServer(serveOptions, cb) {
-  // @ts-expect-error — Bun global is only available in Bun runtime
   const server = globalThis.Bun.serve(serveOptions);
   if (cb) {
     cb(null);
@@ -148,13 +151,15 @@ function startServer(serveOptions, cb) {
 /**
  * Safely stops a Bun server, forwarding errors to the callback.
  *
- * @param {{ server: * }} state - Shared mutable state
+ * @param {{ server: BunServer | null }} state - Shared mutable state
  * @param {Function} [callback]
  */
 function stopServer(state, callback) {
   try {
     if (state.server) {
-      state.server.stop();
+      // stop() synchronously halts the listener; the returned Promise
+      // represents draining of active connections — safe to ignore here.
+      void state.server.stop();
       state.server = null;
     }
     if (callback) {
@@ -192,7 +197,7 @@ export default class BunHttpAdapter extends HttpServerPort {
    */
   createServer(requestHandler) {
     const fetchHandler = createFetchHandler(requestHandler, this._logger);
-    /** @type {{ server: * }} */
+    /** @type {{ server: BunServer | null }} */
     const state = { server: null };
 
     return {
@@ -204,7 +209,7 @@ export default class BunHttpAdapter extends HttpServerPort {
       listen(port, host, callback) {
         const cb = typeof host === 'function' ? host : callback;
         const bindHost = typeof host === 'string' ? host : undefined;
-        /** @type {*} */ // TODO(ts-cleanup): type Bun.serve options
+        /** @type {BunServeOptions} */
         const serveOptions = { port, fetch: fetchHandler };
 
         if (bindHost !== undefined) {

package/src/infrastructure/adapters/CasSeekCacheAdapter.js

@@ -16,6 +16,11 @@
  * @module infrastructure/adapters/CasSeekCacheAdapter
  */
 
+/**
+ * Minimal interface for the ContentAddressableStore from @git-stunts/git-cas.
+ * @typedef {{ readManifest: Function, restore: Function, store: Function, createTree: Function }} CasStore
+ */
+
 import SeekCachePort from '../../ports/SeekCachePort.js';
 import { buildSeekCacheRef } from '../../domain/utils/RefLayout.js';
 import { Readable } from 'node:stream';
@@ -59,7 +64,7 @@ export default class CasSeekCacheAdapter extends SeekCachePort {
   /**
    * Lazily initializes the ContentAddressableStore.
    * @private
-   * @returns {Promise<*>}
+   * @returns {Promise<CasStore>}
    */
   async _getCas() {
     if (!this._casPromise) {
@@ -73,7 +78,7 @@ export default class CasSeekCacheAdapter extends SeekCachePort {
 
   /**
    * @private
-   * @returns {Promise<*>}
+   * @returns {Promise<CasStore>}
    */
   async _initCas() {
     const { default: ContentAddressableStore } = await import(
@@ -132,7 +137,7 @@ export default class CasSeekCacheAdapter extends SeekCachePort {
    * @returns {Promise<CacheIndex>} The mutated index
    */
   async _mutateIndex(mutate) {
-    /** @type {*} */ // TODO(ts-cleanup): type CAS retry error
+    /** @type {unknown} */
     let lastErr;
     for (let attempt = 0; attempt < MAX_CAS_RETRIES; attempt++) {
       const index = await this._readIndex();
@@ -144,7 +149,7 @@ export default class CasSeekCacheAdapter extends SeekCachePort {
         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}`);
+          throw new Error(`CasSeekCacheAdapter: index update failed after retries: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
         }
       }
     }

package/src/infrastructure/adapters/DenoHttpAdapter.js

@@ -100,8 +100,8 @@ function createHandler(requestHandler, logger) {
       const plain = await toPlainRequest(request);
       const response = await requestHandler(plain);
       return toDenoResponse(response);
-    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type error
-      if (err.status === 413) {
+    } catch (err) {
+      if (typeof err === 'object' && err !== null && /** @type {{status?: number}} */ (err).status === 413) {
         const msg = new TextEncoder().encode('Payload Too Large');
         return new Response(msg, {
           status: 413,
@@ -140,7 +140,7 @@ function closeImpl(state, callback) {
         callback();
       }
     },
-    /** @param {*} err */ (err) => {
+    /** @param {unknown} err */ (err) => {
       state.server = null;
       if (callback) {
         callback(err);
@@ -210,7 +210,7 @@ export default class DenoHttpAdapter extends HttpServerPort {
         const hostname = typeof host === 'string' ? host : undefined;
 
         try {
-          /** @type {*} */ // TODO(ts-cleanup): type Deno.serve options
+          /** @type {DenoServeOptions} */
           const serveOptions = {
             port,
             onListen() {
@@ -223,9 +223,8 @@ 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 (/** @type {*} */ err) { // TODO(ts-cleanup): type error
+        } catch (err) {
           if (cb) {
             cb(err);
           } else {

package/src/infrastructure/adapters/GitGraphAdapter.js

@@ -43,6 +43,7 @@
  * @see {@link https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain} for Git plumbing concepts
  */
 
+import { Buffer } from 'node:buffer';
 import { retry } from '@git-stunts/alfred';
 import GraphPersistencePort from '../../ports/GraphPersistencePort.js';
 import { validateOid, validateRef, validateLimit, validateConfigKey } from './adapterValidation.js';
@@ -145,11 +146,12 @@ async function refExists(execute, ref) {
   try {
     await execute({ args: ['show-ref', '--verify', '--quiet', ref] });
     return true;
-  } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type error
-    if (getExitCode(err) === 1) {
+  } catch (err) {
+    const gitErr = /** @type {GitError} */ (err);
+    if (getExitCode(gitErr) === 1) {
       return false;
     }
-    if (isDanglingObjectError(err)) {
+    if (isDanglingObjectError(gitErr)) {
       return false;
     }
     throw err;
@@ -509,7 +511,9 @@ export default class GitGraphAdapter extends GraphPersistencePort {
     const stream = await this.plumbing.executeStream({
       args: ['cat-file', 'blob', oid]
     });
-    return await stream.collect({ asString: false });
+    const raw = await stream.collect({ asString: false });
+    // Ensure a real Node Buffer (plumbing may return Uint8Array)
+    return Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
   }
 
   /**
@@ -544,11 +548,12 @@ export default class GitGraphAdapter extends GraphPersistencePort {
         args: ['rev-parse', ref]
       });
       return oid.trim();
-    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type error
-      if (getExitCode(err) === 1) {
+    } catch (err) {
+      const gitErr = /** @type {GitError} */ (err);
+      if (getExitCode(gitErr) === 1) {
         return null;
       }
-      if (isDanglingObjectError(err)) {
+      if (isDanglingObjectError(gitErr)) {
         return null;
       }
       throw err;
@@ -628,8 +633,8 @@ export default class GitGraphAdapter extends GraphPersistencePort {
     try {
       await this._executeWithRetry({ args: ['cat-file', '-e', sha] });
       return true;
-    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type error
-      if (getExitCode(err) === 1) {
+    } catch (err) {
+      if (getExitCode(/** @type {GitError} */ (err)) === 1) {
         return false;
       }
       throw err;
@@ -704,8 +709,8 @@ export default class GitGraphAdapter extends GraphPersistencePort {
         args: ['merge-base', '--is-ancestor', potentialAncestor, descendant]
       });
       return true;  // Exit code 0 means it IS an ancestor
-    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type error
-      if (this._getExitCode(err) === 1) {
+    } catch (err) {
+      if (this._getExitCode(/** @type {GitError} */ (err)) === 1) {
         return false; // Exit code 1 means it is NOT an ancestor
       }
       throw err; // Re-throw unexpected errors
@@ -726,8 +731,8 @@ export default class GitGraphAdapter extends GraphPersistencePort {
       });
       // Preserve empty-string values; only drop trailing newline
       return value.replace(/\n$/, '');
-    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type error
-      if (this._isConfigKeyNotFound(err)) {
+    } catch (err) {
+      if (this._isConfigKeyNotFound(/** @type {GitError} */ (err))) {
         return null;
       }
       throw err;

package/src/infrastructure/adapters/NodeHttpAdapter.js

@@ -71,7 +71,7 @@ export default class NodeHttpAdapter extends HttpServerPort {
     const logger = this._logger;
     const server = createServer((req, res) => {
       dispatch(req, res, { handler: requestHandler, logger }).catch(
-        /** @param {*} err */ (err) => {
+        /** @param {unknown} err */ (err) => {
           logger.error('[NodeHttpAdapter] unhandled dispatch error:', err);
         });
     });
@@ -85,7 +85,7 @@ export default class NodeHttpAdapter extends HttpServerPort {
       listen(port, host, callback) {
         const cb = typeof host === 'function' ? host : callback;
         const bindHost = typeof host === 'string' ? host : undefined;
-        /** @param {*} err */
+        /** @param {unknown} err */
         const onError = (err) => {
           if (cb) {
             cb(err);

package/src/infrastructure/adapters/WebCryptoAdapter.js

@@ -38,8 +38,8 @@ function toWebCryptoAlgo(algorithm) {
 function toUint8Array(data) {
   if (data instanceof Uint8Array) { return data; }
   if (typeof data === 'string') { return new TextEncoder().encode(data); }
-  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(/** @type {*} */ (data))) { // TODO(ts-cleanup): narrow port type
-    const buf = /** @type {Buffer} */ (/** @type {*} */ (data)); // TODO(ts-cleanup): narrow port type
+  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(data)) {
+    const buf = /** @type {Buffer} */ (data);
     return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
   }
   throw new Error('WebCryptoAdapter: data must be string, Buffer, or Uint8Array');

package/src/visualization/layouts/converters.js

@@ -7,7 +7,7 @@
  */
 
 /**
- * @typedef {{ id: string, label: string, props?: Record<string, any> }} GraphDataNode
+ * @typedef {{ id: string, label: string, props?: Record<string, unknown> }} GraphDataNode
  * @typedef {{ from: string, to: string, label?: string }} GraphDataEdge
  * @typedef {{ nodes: GraphDataNode[], edges: GraphDataEdge[] }} GraphData
  */
@@ -16,7 +16,7 @@
  * Converts a query result payload + edge array into graph data.
  * Edges are filtered to only those connecting matched nodes.
  *
- * @param {{ nodes?: Array<{ id: string, props?: Record<string, any> }> } | null} payload - Query result
+ * @param {{ nodes?: Array<{ id: string, props?: Record<string, unknown> }> } | null} payload - Query result
  * @param {Array<{ from: string, to: string, label?: string }>}  edges   - Edge array from graph.getEdges()
  * @returns {GraphData}
  */

package/src/visualization/layouts/elkAdapter.js

@@ -3,7 +3,7 @@
  */
 
 /**
- * @typedef {{ id: string, label: string, props?: Record<string, any> }} GraphDataNode
+ * @typedef {{ id: string, label: string, props?: Record<string, unknown> }} GraphDataNode
  * @typedef {{ from: string, to: string, label?: string }} GraphDataEdge
  * @typedef {{ nodes: GraphDataNode[], edges: GraphDataEdge[] }} GraphData
  * @typedef {{ text: string }} ElkLabel