@git-stunts/git-warp 11.2.1 → 11.3.3

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 {};

package/bin/presenters/index.js

@@ -30,6 +30,8 @@ import {
   renderSeek,
   renderVerifyAudit,
   renderTrust,
+  renderPatchShow,
+  renderPatchList,
 } from './text.js';
 
 // ── Color control ────────────────────────────────────────────────────────────
@@ -61,8 +63,29 @@ export function shouldStripColor() {
 
 // ── Text renderer map ────────────────────────────────────────────────────────
 
-/** @type {Map<string, function(*): string>} */
-const TEXT_RENDERERS = new Map(/** @type {[string, function(*): string][]} */ ([
+/** @param {import('./text.js').PatchShowPayload & Partial<import('./text.js').PatchListPayload>} payload */
+function renderPatch(payload) {
+  if (payload.ops) {
+    return renderPatchShow(payload);
+  }
+  return renderPatchList(/** @type {import('./text.js').PatchListPayload} */ (payload));
+}
+
+/** @param {{ graph: string, tree?: string, orphanCount?: number, orphans?: string[] }} payload */
+function renderTree(payload) {
+  const lines = [`Graph: ${payload.graph}`];
+  if (payload.tree) {
+    lines.push(payload.tree);
+  }
+  if (payload.orphanCount && payload.orphanCount > 0 && payload.orphans) {
+    lines.push('');
+    lines.push(`Orphans (${payload.orphanCount}): ${payload.orphans.join(', ')}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/** @type {Map<string, function(unknown): string>} */
+const TEXT_RENDERERS = new Map(/** @type {[string, function(unknown): string][]} */ ([
   ['info', renderInfo],
   ['query', renderQuery],
   ['path', renderPath],
@@ -73,11 +96,13 @@ const TEXT_RENDERERS = new Map(/** @type {[string, function(*): string][]} */ ([
   ['seek', renderSeek],
   ['verify-audit', renderVerifyAudit],
   ['trust', renderTrust],
+  ['patch', renderPatch],
+  ['tree', renderTree],
   ['install-hooks', renderInstallHooks],
 ]));
 
-/** @type {Map<string, function(*): string>} */
-const VIEW_RENDERERS = new Map(/** @type {[string, function(*): string][]} */ ([
+/** @type {Map<string, function(unknown): string>} */
+const VIEW_RENDERERS = new Map(/** @type {[string, function(unknown): string][]} */ ([
   ['info', renderInfoView],
   ['check', renderCheckView],
   ['history', renderHistoryView],
@@ -102,7 +127,7 @@ function writeHtmlExport(filePath, svgContent) {
 
 /**
  * Handles svg:PATH and html:PATH view modes for commands that carry _renderedSvg.
- * @param {*} payload
+ * @param {{ _renderedSvg?: string }} payload
  * @param {string} view
  * @returns {boolean} true if handled
  */
@@ -146,13 +171,13 @@ function writeText(text, strip) {
 /**
  * Writes a command result to stdout/stderr in the requested format.
  *
- * @param {*} payload - Command result payload
+ * @param {Record<string, unknown>} payload - Command result payload
  * @param {{format: string, command: string, view: string|null|boolean}} options
  */
 export function present(payload, { format, command, view }) {
   // Error payloads always go to stderr as plain text
   if (payload?.error) {
-    process.stderr.write(renderError(payload));
+    process.stderr.write(renderError(/** @type {import('./text.js').ErrorPayload} */ (payload)));
     return;
   }
 
@@ -186,7 +211,7 @@ export function present(payload, { format, command, view }) {
 
 /**
  * Handles --view output dispatch (ASCII view, SVG file, HTML file).
- * @param {*} payload
+ * @param {Record<string, unknown>} payload
  * @param {string} command
  * @param {string|boolean} view
  */
@@ -200,7 +225,8 @@ function presentView(payload, command, view) {
 
   // query is special: uses pre-rendered _renderedAscii
   if (command === 'query') {
-    writeText(`${payload._renderedAscii ?? ''}\n`, strip);
+    const ascii = typeof payload._renderedAscii === 'string' ? payload._renderedAscii : '';
+    writeText(`${ascii}\n`, strip);
     return;
   }
 

package/bin/presenters/json.js

@@ -8,18 +8,19 @@
 
 /**
  * Recursively sorts object keys for deterministic JSON output.
- * @param {*} input
- * @returns {*}
+ * @param {unknown} input
+ * @returns {unknown}
  */
 function normalize(input) {
   if (Array.isArray(input)) {
     return input.map(normalize);
   }
   if (input && typeof input === 'object') {
-    /** @type {Record<string, *>} */
+    const rec = /** @type {Record<string, unknown>} */ (input);
+    /** @type {Record<string, unknown>} */
     const sorted = {};
-    for (const key of Object.keys(input).sort()) {
-      sorted[key] = normalize(input[key]);
+    for (const key of Object.keys(rec).sort()) {
+      sorted[key] = normalize(rec[key]);
     }
     return sorted;
   }
@@ -28,7 +29,7 @@ function normalize(input) {
 
 /**
  * Pretty-printed JSON with sorted keys (2-space indent).
- * @param {*} value
+ * @param {unknown} value
  * @returns {string}
  */
 export function stableStringify(value) {
@@ -37,7 +38,7 @@ export function stableStringify(value) {
 
 /**
  * Single-line JSON with sorted keys (no indent).
- * @param {*} value
+ * @param {unknown} value
  * @returns {string}
  */
 export function compactStringify(value) {
@@ -48,18 +49,19 @@ export function compactStringify(value) {
  * Shallow-clones a payload, removing all top-level underscore-prefixed keys.
  * These are internal rendering artifacts (e.g. _renderedSvg, _renderedAscii)
  * that should not leak into JSON/NDJSON output.
- * @param {*} payload
- * @returns {*}
+ * @param {Record<string, unknown> | unknown} payload
+ * @returns {Record<string, unknown> | unknown}
  */
 export function sanitizePayload(payload) {
   if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
     return payload;
   }
-  /** @type {Record<string, *>} */
+  const rec = /** @type {Record<string, unknown>} */ (payload);
+  /** @type {Record<string, unknown>} */
   const clean = {};
-  for (const key of Object.keys(payload)) {
+  for (const key of Object.keys(rec)) {
     if (!key.startsWith('_')) {
-      clean[key] = payload[key];
+      clean[key] = rec[key];
     }
   }
   return clean;