@git-stunts/git-warp 11.2.1 → 11.5.0

package/bin/cli/commands/seek.js

@@ -17,6 +17,7 @@ import { openGraph, readActiveCursor, writeActiveCursor, wireSeekCache } from '.
 /** @typedef {import('../types.js').WriterTickInfo} WriterTickInfo */
 /** @typedef {import('../types.js').CursorBlob} CursorBlob */
 /** @typedef {import('../types.js').SeekSpec} SeekSpec */
+/** @typedef {import('../../../src/domain/services/StateDiff.js').StateDiffResult} StateDiffResult */
 
 // ============================================================================
 // Cursor I/O Helpers (seek-only)
@@ -257,18 +258,19 @@ function computeSeekStateDiff(prevCursor, next, frontierHash) {
 
 /**
  * @param {{tick: number, perWriter: Map<string, WriterTickInfo>, graph: WarpGraphInstance}} params
- * @returns {Promise<Record<string, {sha: string, opSummary: *}>|null>}
+ * @returns {Promise<Record<string, {sha: string, opSummary: unknown}>|null>}
  */
 async function buildTickReceipt({ tick, perWriter, graph }) {
   if (!Number.isInteger(tick) || tick <= 0) {
     return null;
   }
 
-  /** @type {Record<string, {sha: string, opSummary: *}>} */
+  /** @type {Record<string, {sha: string, opSummary: unknown}>} */
   const receipt = {};
 
   for (const [writerId, info] of perWriter) {
-    const sha = /** @type {*} */ (info?.tickShas)?.[tick]; // TODO(ts-cleanup): type CLI payload
+    const tickShas = /** @type {Record<number, string> | undefined} */ (info?.tickShas);
+    const sha = tickShas?.[tick];
     if (!sha) {
       continue;
     }
@@ -283,7 +285,7 @@ async function buildTickReceipt({ tick, perWriter, graph }) {
 
 /**
  * @param {{graph: WarpGraphInstance, prevTick: number|null, currentTick: number, diffLimit: number}} params
- * @returns {Promise<{structuralDiff: *, diffBaseline: string, baselineTick: number|null, truncated: boolean, totalChanges: number, shownChanges: number}>}
+ * @returns {Promise<{structuralDiff: unknown, diffBaseline: string, baselineTick: number|null, truncated: boolean, totalChanges: number, shownChanges: number}>}
  */
 async function computeStructuralDiff({ graph, prevTick, currentTick, diffLimit }) {
   let beforeState = null;
@@ -303,18 +305,22 @@ async function computeStructuralDiff({ graph, prevTick, currentTick, diffLimit }
   }
 
   await graph.materialize({ ceiling: currentTick });
-  const afterState = /** @type {*} */ (await graph.getStateSnapshot()); // TODO(ts-cleanup): narrow WarpStateV5
+  const afterState = await graph.getStateSnapshot();
+  if (!afterState) {
+    const empty = { nodes: { added: [], removed: [] }, edges: { added: [], removed: [] }, props: { set: [], removed: [] } };
+    return applyDiffLimit(empty, diffBaseline, baselineTick, diffLimit);
+  }
   const diff = diffStates(beforeState, afterState);
 
   return applyDiffLimit(diff, diffBaseline, baselineTick, diffLimit);
 }
 
 /**
- * @param {*} diff
+ * @param {StateDiffResult} diff
  * @param {string} diffBaseline
  * @param {number|null} baselineTick
  * @param {number} diffLimit
- * @returns {{structuralDiff: *, diffBaseline: string, baselineTick: number|null, truncated: boolean, totalChanges: number, shownChanges: number}}
+ * @returns {{structuralDiff: StateDiffResult, diffBaseline: string, baselineTick: number|null, truncated: boolean, totalChanges: number, shownChanges: number}}
  */
 function applyDiffLimit(diff, diffBaseline, baselineTick, diffLimit) {
   const totalChanges =
@@ -327,7 +333,7 @@ function applyDiffLimit(diff, diffBaseline, baselineTick, diffLimit) {
   }
 
   let remaining = diffLimit;
-  const cap = (/** @type {any[]} */ arr) => {
+  const cap = (/** @type {unknown[]} */ arr) => {
     const take = Math.min(arr.length, remaining);
     remaining -= take;
     return arr.slice(0, take);
@@ -340,7 +346,7 @@ function applyDiffLimit(diff, diffBaseline, baselineTick, diffLimit) {
   };
 
   const shownChanges = diffLimit - remaining;
-  return { structuralDiff: capped, diffBaseline, baselineTick, truncated: true, totalChanges, shownChanges };
+  return { structuralDiff: /** @type {StateDiffResult} */ (capped), diffBaseline, baselineTick, truncated: true, totalChanges, shownChanges };
 }
 
 // ============================================================================
@@ -349,7 +355,7 @@ function applyDiffLimit(diff, diffBaseline, baselineTick, diffLimit) {
 
 /**
  * @param {{graph: WarpGraphInstance, graphName: string, persistence: Persistence, activeCursor: CursorBlob|null, ticks: number[], maxTick: number, perWriter: Map<string, WriterTickInfo>, frontierHash: string}} params
- * @returns {Promise<{payload: *, exitCode: number}>}
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
  */
 async function handleSeekStatus({ graph, graphName, persistence, activeCursor, ticks, maxTick, perWriter, frontierHash }) {
   if (activeCursor) {
@@ -411,7 +417,7 @@ async function handleSeekStatus({ graph, graphName, persistence, activeCursor, t
 /**
  * Handles the `git warp seek` command across all sub-actions.
  * @param {{options: CliOptions, args: string[]}} params
- * @returns {Promise<{payload: *, exitCode: number}>}
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
  */
 export default async function handleSeek({ options, args }) {
   const seekSpec = parseSeekArgs(args);

package/bin/cli/commands/tree.js

@@ -0,0 +1,230 @@
+import { EXIT_CODES, usageError, parseCommandArgs } from '../infrastructure.js';
+import { openGraph, applyCursorCeiling, emitCursorWarning } from '../shared.js';
+import { z } from 'zod';
+
+/** @typedef {import('../types.js').CliOptions} CliOptions */
+
+const TREE_OPTIONS = {
+  edge: { type: 'string' },
+  prop: { type: 'string', multiple: true },
+  'max-depth': { type: 'string' },
+};
+
+const treeSchema = z.object({
+  edge: z.string().optional(),
+  prop: z.union([z.string(), z.array(z.string())]).optional(),
+  'max-depth': z.coerce.number().int().nonnegative().optional(),
+}).strict().transform((val) => ({
+  edgeLabel: val.edge ?? null,
+  props: Array.isArray(val.prop) ? val.prop : val.prop ? [val.prop] : [],
+  maxDepth: val['max-depth'],
+}));
+
+/**
+ * Builds a parent-to-children adjacency map from edges.
+ * @param {Array<{from: string, to: string, label?: string}>} edges
+ * @param {string|null} labelFilter
+ * @returns {Map<string, Array<{id: string, label: string}>>}
+ */
+function buildChildMap(edges, labelFilter) {
+  /** @type {Map<string, Array<{id: string, label: string}>>} */
+  const children = new Map();
+  /** @type {Set<string>} */
+  const hasParent = new Set();
+
+  for (const edge of edges) {
+    if (labelFilter && edge.label !== labelFilter) {
+      continue;
+    }
+    if (!children.has(edge.from)) {
+      children.set(edge.from, []);
+    }
+    const fromChildren = children.get(edge.from);
+    if (fromChildren) {
+      fromChildren.push({ id: edge.to, label: edge.label || '' });
+    }
+    hasParent.add(edge.to);
+  }
+
+  return children;
+}
+
+/**
+ * Finds root nodes (nodes with outgoing edges but no incoming edges in the filtered set).
+ * @param {string[]} nodeIds
+ * @param {Array<{from: string, to: string, label?: string}>} edges
+ * @param {string|null} labelFilter
+ * @returns {string[]}
+ */
+function findRoots(nodeIds, edges, labelFilter) {
+  const hasParent = new Set();
+  const hasChild = new Set();
+
+  for (const edge of edges) {
+    if (labelFilter && edge.label !== labelFilter) {
+      continue;
+    }
+    hasParent.add(edge.to);
+    hasChild.add(edge.from);
+  }
+
+  // Roots: nodes that have children but no parents in the filtered edge set
+  const roots = nodeIds.filter((id) => !hasParent.has(id) && hasChild.has(id));
+  if (roots.length > 0) {
+    return roots.sort();
+  }
+
+  // Fallback: nodes with no incoming edges at all
+  return nodeIds.filter((id) => !hasParent.has(id)).sort();
+}
+
+/**
+ * Formats annotation string for a node based on requested props.
+ * @param {Record<string, unknown>} nodeProps
+ * @param {string[]} propKeys
+ * @returns {string}
+ */
+function formatAnnotation(nodeProps, propKeys) {
+  if (propKeys.length === 0 || !nodeProps) {
+    return '';
+  }
+  const parts = [];
+  for (const key of propKeys) {
+    if (Object.prototype.hasOwnProperty.call(nodeProps, key)) {
+      parts.push(`${key}: ${nodeProps[key]}`);
+    }
+  }
+  return parts.length > 0 ? `  [${parts.join(', ')}]` : '';
+}
+
+/**
+ * Renders a tree structure as lines with box-drawing characters.
+ * @param {object} params
+ * @param {string} params.nodeId
+ * @param {Map<string, Array<{id: string, label: string}>>} params.childMap
+ * @param {Map<string, Record<string, unknown>>} params.propsMap
+ * @param {string[]} params.propKeys
+ * @param {string} params.prefix
+ * @param {boolean} params.isLast
+ * @param {Set<string>} params.visited
+ * @param {number} params.depth
+ * @param {number|undefined} params.maxDepth
+ * @param {string[]} params.lines
+ */
+function renderTreeNode({ nodeId, childMap, propsMap, propKeys, prefix, isLast, visited, depth, maxDepth, lines }) {
+  const connector = depth === 0 ? '' : (isLast ? '\u2514\u2500\u2500 ' : '\u251C\u2500\u2500 ');
+  const annotation = formatAnnotation(propsMap.get(nodeId) || {}, propKeys);
+  lines.push(`${prefix}${connector}${nodeId}${annotation}`);
+
+  if (visited.has(nodeId)) {
+    lines.push(`${prefix}${isLast ? '    ' : '\u2502   '}  (cycle)`);
+    return;
+  }
+  visited.add(nodeId);
+
+  if (maxDepth !== undefined && depth >= maxDepth) {
+    const kids = childMap.get(nodeId);
+    if (kids && kids.length > 0) {
+      lines.push(`${prefix}${isLast ? '    ' : '\u2502   '}  ... (${kids.length} children)`);
+    }
+    return;
+  }
+
+  const kids = childMap.get(nodeId) || [];
+  const childPrefix = depth === 0 ? '' : `${prefix}${isLast ? '    ' : '\u2502   '}`;
+  for (let i = 0; i < kids.length; i++) {
+    renderTreeNode({
+      nodeId: kids[i].id,
+      childMap,
+      propsMap,
+      propKeys,
+      prefix: childPrefix,
+      isLast: i === kids.length - 1,
+      visited,
+      depth: depth + 1,
+      maxDepth,
+      lines,
+    });
+  }
+}
+
+/**
+ * Handles the `tree` command: ASCII tree output from graph edges.
+ * @param {{options: CliOptions, args: string[]}} params
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
+ */
+export default async function handleTree({ options, args }) {
+  const { values, positionals } = parseCommandArgs(
+    args, TREE_OPTIONS, treeSchema, { allowPositionals: true },
+  );
+  const { graph, graphName, persistence } = await openGraph(options);
+  const cursorInfo = await applyCursorCeiling(graph, persistence, graphName);
+  emitCursorWarning(cursorInfo, null);
+
+  const queryResult = await graph.query().run();
+  const edges = await graph.getEdges();
+  const rootArg = positionals[0] || null;
+
+  const nodeIds = queryResult.nodes.map((/** @type {{id: string}} */ n) => n.id);
+  const propsMap = new Map(queryResult.nodes.map((/** @type {{id: string, props?: Record<string, unknown>}} */ n) => [n.id, n.props || {}]));
+  const childMap = buildChildMap(edges, values.edgeLabel);
+
+  const roots = rootArg ? [rootArg] : findRoots(nodeIds, edges, values.edgeLabel);
+
+  if (rootArg && !nodeIds.includes(rootArg)) {
+    throw usageError(`Node not found: ${rootArg}`);
+  }
+
+  /** @type {string[]} */
+  const lines = [];
+  for (const root of roots) {
+    renderTreeNode({
+      nodeId: root,
+      childMap,
+      propsMap,
+      propKeys: values.props,
+      prefix: '',
+      isLast: true,
+      visited: new Set(),
+      depth: 0,
+      maxDepth: values.maxDepth,
+      lines,
+    });
+  }
+
+  // Collect orphans (nodes not reachable from any root)
+  const reachable = new Set();
+  collectReachable(roots, childMap, reachable);
+  const orphans = nodeIds.filter((/** @type {string} */ id) => !reachable.has(id));
+
+  const payload = {
+    graph: graphName,
+    roots,
+    tree: lines.join('\n'),
+    orphanCount: orphans.length,
+    orphans: orphans.length > 0 ? orphans : undefined,
+  };
+
+  return { payload, exitCode: EXIT_CODES.OK };
+}
+
+/**
+ * Collects all reachable node IDs via DFS.
+ * @param {string[]} roots
+ * @param {Map<string, Array<{id: string, label: string}>>} childMap
+ * @param {Set<string>} reachable
+ */
+function collectReachable(roots, childMap, reachable) {
+  const stack = [...roots];
+  while (stack.length > 0) {
+    const id = /** @type {string} */ (stack.pop());
+    if (reachable.has(id)) {
+      continue;
+    }
+    reachable.add(id);
+    const kids = childMap.get(id) || [];
+    for (const kid of kids) {
+      stack.push(kid.id);
+    }
+  }
+}

package/bin/cli/commands/trust.js

@@ -49,7 +49,7 @@ function resolveTrustPin(cliPin) {
 
 /**
  * Discovers all writer IDs from the writers prefix refs.
- * @param {*} persistence
+ * @param {import('../types.js').Persistence} persistence
  * @param {string} graphName
  * @returns {Promise<string[]>}
  */
@@ -96,7 +96,7 @@ function buildNotConfiguredResult(graphName) {
 
 /**
  * @param {{options: CliOptions, args: string[]}} params
- * @returns {Promise<{payload: *, exitCode: number}>}
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
  */
 export default async function handleTrust({ options, args }) {
   const { mode, trustPin } = parseTrustArgs(args);
@@ -104,7 +104,7 @@ export default async function handleTrust({ options, args }) {
   const graphName = await resolveGraphName(persistence, options.graph);
 
   const recordService = new TrustRecordService({
-    persistence: /** @type {*} TODO(ts-cleanup) */ (persistence),
+    persistence: /** @type {import('../../../src/domain/types/WarpPersistence.js').CorePersistence} */ (/** @type {unknown} */ (persistence)),
     codec: defaultCodec,
   });
 

package/bin/cli/commands/verify-audit.js

@@ -46,20 +46,20 @@ export function parseVerifyAuditArgs(args) {
 
 /**
  * @param {{options: CliOptions, args: string[]}} params
- * @returns {Promise<{payload: *, exitCode: number}>}
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
  */
 export default async function handleVerifyAudit({ options, args }) {
   const { since, writerFilter, trustMode, trustPin } = parseVerifyAuditArgs(args);
   const { persistence } = await createPersistence(options.repo);
   const graphName = await resolveGraphName(persistence, options.graph);
   const verifier = new AuditVerifierService({
-    persistence: /** @type {*} */ (persistence), // TODO(ts-cleanup): narrow port type
+    persistence: /** @type {import('../../../src/domain/types/WarpPersistence.js').CorePersistence} */ (/** @type {unknown} */ (persistence)),
     codec: defaultCodec,
   });
 
   const trustWarning = detectTrustWarning();
 
-  /** @type {*} */ // TODO(ts-cleanup): type verify-audit payload
+  /** @type {Record<string, unknown>} */
   let payload;
   if (writerFilter !== undefined) {
     const chain = await verifier.verifyChain(graphName, writerFilter, { since });
@@ -88,7 +88,7 @@ export default async function handleVerifyAudit({ options, args }) {
         mode: trustMode,
       });
       payload.trustAssessment = trustAssessment;
-    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type catch
+    } catch (err) {
       if (trustMode === 'enforce') {
         throw err;
       }
@@ -96,14 +96,15 @@ export default async function handleVerifyAudit({ options, args }) {
         trustSchemaVersion: 1,
         mode: 'signed_evidence_v1',
         trustVerdict: 'error',
-        error: err?.message ?? 'Trust evaluation failed',
+        error: err instanceof Error ? err.message : 'Trust evaluation failed',
       };
     }
   }
 
-  const hasInvalid = payload.summary.invalid > 0;
+  const { summary, trustAssessment } = /** @type {{summary: {invalid: number}, trustAssessment?: {trustVerdict?: string}}} */ (payload);
+  const hasInvalid = summary.invalid > 0;
   const trustFailed = trustMode === 'enforce' &&
-    payload.trustAssessment?.trustVerdict === 'fail';
+    trustAssessment?.trustVerdict === 'fail';
   return {
     payload,
     exitCode: trustFailed ? EXIT_CODES.TRUST_FAIL

package/bin/cli/commands/view.js

@@ -11,7 +11,7 @@ const VIEW_OPTIONS = {
 
 /**
  * @param {{options: CliOptions, args: string[]}} params
- * @returns {Promise<{payload: *, exitCode: number}>}
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
  */
 export default async function handleView({ options, args }) {
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
@@ -29,10 +29,11 @@ export default async function handleView({ options, args }) {
       graph: options.graph || 'default',
       mode: viewMode,
     });
-  } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type error
-    const isMissing = err.code === 'ERR_MODULE_NOT_FOUND' || (err.message && err.message.includes('Cannot find module'));
-    const isTui = err.specifier?.includes('git-warp-tui') ||
-      /cannot find (?:package|module) ['"]@git-stunts\/git-warp-tui/i.test(err.message);
+  } catch (err) {
+    const errObj = /** @type {{code?: string, message?: string, specifier?: string}} */ (typeof err === 'object' && err !== null ? err : {});
+    const isMissing = errObj.code === 'ERR_MODULE_NOT_FOUND' || (errObj.message && errObj.message.includes('Cannot find module'));
+    const isTui = errObj.specifier?.includes('git-warp-tui') ||
+      /cannot find (?:package|module) ['"]@git-stunts\/git-warp-tui/i.test(errObj.message || '');
     if (isMissing && isTui) {
       throw usageError(
         'Interactive TUI requires @git-stunts/git-warp-tui.\n' +

package/bin/cli/infrastructure.js

@@ -11,6 +11,8 @@ export const EXIT_CODES = {
   INTERNAL: 3,
   /** Trust policy denial (enforce mode). */
   TRUST_FAIL: 4,
+  /** Valid result but negative (e.g. no path found). Follows grep convention. */
+  NO_MATCH: 1,
 };
 
 /**
@@ -22,9 +24,7 @@ export function getEnvVar(name) {
   if (typeof process !== 'undefined' && process.env) {
     return process.env[name];
   }
-  // @ts-expect-error — Deno global is only present in Deno runtime
   if (typeof Deno !== 'undefined') {
-    // @ts-expect-error — Deno global is only present in Deno runtime
     // eslint-disable-next-line no-undef
     try { return Deno.env.get(name); } catch { return undefined; }
   }
@@ -45,6 +45,8 @@ Commands:
   trust            Evaluate writer trust from signed evidence
   materialize      Materialize and checkpoint all graphs
   seek             Time-travel: step through graph history by Lamport tick
+  patch            Decode and inspect raw patches
+  tree             ASCII tree traversal from root nodes
   view             Interactive TUI graph browser (requires @git-stunts/git-warp-tui)
   install-hooks    Install post-merge git hook
 
@@ -99,6 +101,18 @@ Seek options:
   --drop <name>         Delete a saved cursor
   --diff                Show structural diff (added/removed nodes, edges, props)
   --diff-limit <N>      Max diff entries (default 2000)
+
+Patch options:
+  show <sha>            Decode and display a single patch as JSON
+  list                  List all patches sorted by Lamport clock
+  --writer <id>         Filter by writer (list only)
+  --limit <n>           Max entries to show (list only)
+
+Tree options:
+  [rootNode]            Root node id (auto-detected if omitted)
+  --edge <label>        Follow only this edge label
+  --prop <key>          Annotate nodes with this property (repeatable)
+  --max-depth <n>       Maximum traversal depth
 `;
 
 /**
@@ -130,7 +144,7 @@ export function notFoundError(message) {
   return new CliError(message, { code: 'E_NOT_FOUND', exitCode: EXIT_CODES.NOT_FOUND });
 }
 
-export const KNOWN_COMMANDS = ['info', 'query', 'path', 'history', 'check', 'doctor', 'materialize', 'seek', 'verify-audit', 'trust', 'install-hooks', 'view'];
+export const KNOWN_COMMANDS = ['info', 'query', 'path', 'history', 'check', 'doctor', 'materialize', 'seek', 'verify-audit', 'trust', 'patch', 'tree', 'install-hooks', 'view'];
 
 const BASE_OPTIONS = {
   repo:   { type: 'string', short: 'r' },
@@ -272,17 +286,17 @@ export function parseArgs(argv) {
   const { baseArgs, command, commandArgs } = extractBaseArgs(argv);
   const processed = preprocessView(baseArgs);
 
-  /** @type {*} */ // TODO(ts-cleanup): type parseArgs return
+  /** @type {{ values: Record<string, string|boolean|string[]|boolean[]|undefined>, positionals: string[] }} */
   let parsed;
   try {
     parsed = nodeParseArgs({
       args: processed,
-      options: /** @type {*} */ (BASE_OPTIONS), // TODO(ts-cleanup): type parseArgs config
+      options: /** @type {import('node:util').ParseArgsConfig['options']} */ (BASE_OPTIONS),
       strict: true,
       allowPositionals: false,
     });
-  } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type parseArgs error
-    throw usageError(err.message);
+  } catch (err) {
+    throw usageError(err instanceof Error ? err.message : String(err));
   }
 
   const { values } = parsed;
@@ -312,22 +326,22 @@ export function parseArgs(argv) {
  * @returns {{values: *, positionals: string[]}}
  */
 export function parseCommandArgs(args, config, schema, { allowPositionals = false } = {}) {
-  /** @type {*} */ // TODO(ts-cleanup): type parseArgs return
+  /** @type {{ values: Record<string, string|boolean|string[]|boolean[]|undefined>, positionals: string[] }} */
   let parsed;
   try {
     parsed = nodeParseArgs({
       args,
-      options: /** @type {*} */ (config), // TODO(ts-cleanup): type parseArgs config
+      options: /** @type {import('node:util').ParseArgsConfig['options']} */ (config),
       strict: true,
       allowPositionals,
     });
-  } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type parseArgs error
-    throw usageError(err.message);
+  } catch (err) {
+    throw usageError(err instanceof Error ? err.message : String(err));
   }
 
   const result = schema.safeParse(parsed.values);
   if (!result.success) {
-    const msg = result.error.issues.map((/** @type {*} */ issue) => issue.message).join('; '); // TODO(ts-cleanup): type Zod issue
+    const msg = result.error.issues.map((/** @type {{message: string}} */ issue) => issue.message).join('; ');
     throw usageError(msg);
   }
 

package/bin/cli/shared.js

@@ -92,7 +92,7 @@ export async function openGraph(options) {
       throw notFoundError(`Graph not found: ${options.graph}`);
     }
   }
-  const graph = /** @type {WarpGraphInstance} */ (/** @type {*} */ (await WarpGraph.open({ // TODO(ts-cleanup): narrow port type
+  const graph = /** @type {WarpGraphInstance} */ (/** @type {unknown} */ (await WarpGraph.open({
     persistence,
     graphName,
     writerId: options.writer,
@@ -183,7 +183,7 @@ export function createHookInstaller() {
   const templateDir = path.resolve(__dirname, '..', '..', 'scripts', 'hooks');
   const { version } = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', '..', 'package.json'), 'utf8'));
   return new HookInstaller({
-    fs: /** @type {*} */ (fs), // TODO(ts-cleanup): narrow port type
+    fs: /** @type {import('../../src/domain/services/HookInstaller.js').FsAdapter} */ (/** @type {unknown} */ (fs)),
     execGitConfig: execGitConfigValue,
     version,
     templateDir,

package/bin/cli/types.js

@@ -10,7 +10,7 @@
  * @property {(sha: string) => Promise<boolean>} nodeExists
  * @property {(sha: string, coverageSha: string) => Promise<boolean>} isAncestor
  * @property {() => Promise<{ok: boolean}>} ping
- * @property {*} plumbing
+ * @property {unknown} plumbing
  */
 
 /**
@@ -19,18 +19,19 @@
  * @property {() => Promise<Array<{id: string}>>} getNodes
  * @property {() => Promise<Array<{from: string, to: string, label?: string}>>} getEdges
  * @property {() => Promise<string|null>} createCheckpoint
- * @property {() => *} query
+ * @property {() => QueryBuilderLike} query
  * @property {{ shortestPath: Function }} traverse
- * @property {(writerId: string) => Promise<Array<{patch: any, sha: string}>>} getWriterPatches
- * @property {() => Promise<{frontier: Record<string, any>}>} status
- * @property {() => Promise<Map<string, any>>} getFrontier
+ * @property {(writerId: string) => Promise<Array<{patch: {schema?: number, lamport: number, ops?: Array<{type: string, node?: string, from?: string, to?: string}>}, sha: string}>>} getWriterPatches
+ * @property {() => Promise<{frontier: Record<string, string>}>} status
+ * @property {() => Promise<string[]>} discoverWriters
+ * @property {() => Promise<Map<string, string>>} getFrontier
  * @property {() => {totalTombstones: number, tombstoneRatio: number}} getGCMetrics
  * @property {() => Promise<number>} getPropertyCount
  * @property {() => Promise<import('../../src/domain/services/JoinReducer.js').WarpStateV5 | null>} getStateSnapshot
  * @property {() => Promise<{ticks: number[], maxTick: number, perWriter: Map<string, WriterTickInfo>}>} discoverTicks
- * @property {(sha: string) => Promise<{ops?: any[]}>} loadPatchBySha
- * @property {(cache: any) => void} setSeekCache
- * @property {*} seekCache
+ * @property {(sha: string) => Promise<{ops?: Array<{type: string, node?: string, from?: string, to?: string}>}>} loadPatchBySha
+ * @property {(cache: import('../../src/ports/SeekCachePort.js').default) => void} setSeekCache
+ * @property {{clear: () => Promise<void>} | null} seekCache
  * @property {number} [_seekCeiling]
  * @property {boolean} [_provenanceDegraded]
  */
@@ -82,4 +83,14 @@
  * @property {number} diffLimit
  */
 
+/**
+ * @typedef {Object} QueryBuilderLike
+ * @property {(label?: string) => QueryBuilderLike} outgoing
+ * @property {(label?: string) => QueryBuilderLike} incoming
+ * @property {(fn: Function) => QueryBuilderLike} where
+ * @property {(pattern: string) => QueryBuilderLike} match
+ * @property {(fields: string[]) => QueryBuilderLike} select
+ * @property {() => Promise<{nodes: Array<{id: string, props?: Record<string, unknown>}>, stateHash?: string}>} run
+ */
+
 export {};