@git-stunts/git-warp 10.8.0 → 11.3.3

package/bin/cli/shared.js

@@ -0,0 +1,244 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import readline from 'node:readline';
+import { execFileSync } from 'node:child_process';
+// @ts-expect-error — no type declarations for @git-stunts/plumbing
+import GitPlumbing, { ShellRunnerFactory } from '@git-stunts/plumbing';
+import WarpGraph from '../../src/domain/WarpGraph.js';
+import GitGraphAdapter from '../../src/infrastructure/adapters/GitGraphAdapter.js';
+import WebCryptoAdapter from '../../src/infrastructure/adapters/WebCryptoAdapter.js';
+import {
+  REF_PREFIX,
+  buildCursorActiveRef,
+} from '../../src/domain/utils/RefLayout.js';
+import CasSeekCacheAdapter from '../../src/infrastructure/adapters/CasSeekCacheAdapter.js';
+import { HookInstaller } from '../../src/domain/services/HookInstaller.js';
+import { parseCursorBlob } from '../../src/domain/utils/parseCursorBlob.js';
+import { usageError, notFoundError } from './infrastructure.js';
+
+/** @typedef {import('./types.js').Persistence} Persistence */
+/** @typedef {import('./types.js').WarpGraphInstance} WarpGraphInstance */
+/** @typedef {import('./types.js').CursorBlob} CursorBlob */
+/** @typedef {import('./types.js').CliOptions} CliOptions */
+/** @typedef {import('./types.js').SeekSpec} SeekSpec */
+
+/** @param {string} repoPath @returns {Promise<{persistence: Persistence}>} */
+export async function createPersistence(repoPath) {
+  const runner = ShellRunnerFactory.create();
+  const plumbing = new GitPlumbing({ cwd: repoPath, runner });
+  const persistence = new GitGraphAdapter({ plumbing });
+  const ping = await persistence.ping();
+  if (!ping.ok) {
+    throw usageError(`Repository not accessible: ${repoPath}`);
+  }
+  return { persistence };
+}
+
+/** @param {Persistence} persistence @returns {Promise<string[]>} */
+export async function listGraphNames(persistence) {
+  if (typeof persistence.listRefs !== 'function') {
+    return [];
+  }
+  const refs = await persistence.listRefs(REF_PREFIX);
+  const prefix = `${REF_PREFIX}/`;
+  const names = new Set();
+
+  for (const ref of refs) {
+    if (!ref.startsWith(prefix)) {
+      continue;
+    }
+    const rest = ref.slice(prefix.length);
+    const [graphName] = rest.split('/');
+    if (graphName) {
+      names.add(graphName);
+    }
+  }
+
+  return [...names].sort();
+}
+
+/**
+ * @param {Persistence} persistence
+ * @param {string|null} explicitGraph
+ * @returns {Promise<string>}
+ */
+export async function resolveGraphName(persistence, explicitGraph) {
+  if (explicitGraph) {
+    return explicitGraph;
+  }
+  const graphNames = await listGraphNames(persistence);
+  if (graphNames.length === 1) {
+    return graphNames[0];
+  }
+  if (graphNames.length === 0) {
+    throw notFoundError('No graphs found in repo; specify --graph');
+  }
+  throw usageError('Multiple graphs found; specify --graph');
+}
+
+/**
+ * Opens a WarpGraph for the given CLI options.
+ * @param {CliOptions} options - Parsed CLI options
+ * @returns {Promise<{graph: WarpGraphInstance, graphName: string, persistence: Persistence}>}
+ * @throws {import('./infrastructure.js').CliError} If the specified graph is not found
+ */
+export async function openGraph(options) {
+  const { persistence } = await createPersistence(options.repo);
+  const graphName = await resolveGraphName(persistence, options.graph);
+  if (options.graph) {
+    const graphNames = await listGraphNames(persistence);
+    if (!graphNames.includes(options.graph)) {
+      throw notFoundError(`Graph not found: ${options.graph}`);
+    }
+  }
+  const graph = /** @type {WarpGraphInstance} */ (/** @type {unknown} */ (await WarpGraph.open({
+    persistence,
+    graphName,
+    writerId: options.writer,
+    crypto: new WebCryptoAdapter(),
+  })));
+  return { graph, graphName, persistence };
+}
+
+/**
+ * Reads the active cursor and sets `_seekCeiling` on the graph instance
+ * so that subsequent materialize calls respect the time-travel boundary.
+ *
+ * @param {WarpGraphInstance} graph - WarpGraph instance
+ * @param {Persistence} persistence - GraphPersistencePort adapter
+ * @param {string} graphName - Name of the WARP graph
+ * @returns {Promise<{active: boolean, tick: number|null, maxTick: number|null}>}
+ */
+export async function applyCursorCeiling(graph, persistence, graphName) {
+  const cursor = await readActiveCursor(persistence, graphName);
+  if (cursor) {
+    graph._seekCeiling = cursor.tick;
+    return { active: true, tick: cursor.tick, maxTick: null };
+  }
+  return { active: false, tick: null, maxTick: null };
+}
+
+/**
+ * Prints a seek cursor warning banner to stderr when a cursor is active.
+ *
+ * @param {{active: boolean, tick: number|null, maxTick: number|null}} cursorInfo
+ * @param {number|null} maxTick
+ * @returns {void}
+ */
+export function emitCursorWarning(cursorInfo, maxTick) {
+  if (cursorInfo.active) {
+    const maxLabel = maxTick !== null && maxTick !== undefined ? ` of ${maxTick}` : '';
+    process.stderr.write(`\u26A0 seek active (tick ${cursorInfo.tick}${maxLabel}) \u2014 run "git warp seek --latest" to return to present\n`);
+  }
+}
+
+/**
+ * Reads the active seek cursor for a graph from Git ref storage.
+ *
+ * @param {Persistence} persistence - GraphPersistencePort adapter
+ * @param {string} graphName - Name of the WARP graph
+ * @returns {Promise<CursorBlob|null>}
+ */
+export async function readActiveCursor(persistence, graphName) {
+  const ref = buildCursorActiveRef(graphName);
+  const oid = await persistence.readRef(ref);
+  if (!oid) {
+    return null;
+  }
+  const buf = await persistence.readBlob(oid);
+  return parseCursorBlob(buf, 'active cursor');
+}
+
+/**
+ * Writes (creates or overwrites) the active seek cursor for a graph.
+ *
+ * @param {Persistence} persistence - GraphPersistencePort adapter
+ * @param {string} graphName - Name of the WARP graph
+ * @param {CursorBlob} cursor - Cursor state to persist
+ * @returns {Promise<void>}
+ */
+export async function writeActiveCursor(persistence, graphName, cursor) {
+  const ref = buildCursorActiveRef(graphName);
+  const json = JSON.stringify(cursor);
+  const oid = await persistence.writeBlob(Buffer.from(json, 'utf8'));
+  await persistence.updateRef(ref, oid);
+}
+
+/**
+ * @param {Persistence} persistence
+ * @param {string|null} checkpointSha
+ */
+export async function readCheckpointDate(persistence, checkpointSha) {
+  if (!checkpointSha) {
+    return null;
+  }
+  const info = await persistence.getNodeInfo(checkpointSha);
+  return info.date || null;
+}
+
+export function createHookInstaller() {
+  const __filename = new URL(import.meta.url).pathname;
+  const __dirname = path.dirname(__filename);
+  const templateDir = path.resolve(__dirname, '..', '..', 'scripts', 'hooks');
+  const { version } = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', '..', 'package.json'), 'utf8'));
+  return new HookInstaller({
+    fs: /** @type {import('../../src/domain/services/HookInstaller.js').FsAdapter} */ (/** @type {unknown} */ (fs)),
+    execGitConfig: execGitConfigValue,
+    version,
+    templateDir,
+    path,
+  });
+}
+
+/**
+ * @param {string} repoPath
+ * @param {string} key
+ * @returns {string|null}
+ */
+export function execGitConfigValue(repoPath, key) {
+  try {
+    if (key === '--git-dir') {
+      return execFileSync('git', ['-C', repoPath, 'rev-parse', '--git-dir'], {
+        encoding: 'utf8',
+      }).trim();
+    }
+    return execFileSync('git', ['-C', repoPath, 'config', key], {
+      encoding: 'utf8',
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function isInteractive() {
+  return Boolean(process.stderr.isTTY);
+}
+
+/** @param {string} question @returns {Promise<string>} */
+export function promptUser(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr,
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * @param {{graph: WarpGraphInstance, persistence: Persistence, graphName: string, seekSpec: SeekSpec}} params
+ */
+export function wireSeekCache({ graph, persistence, graphName, seekSpec }) {
+  if (seekSpec.noPersistentCache) {
+    return;
+  }
+  graph.setSeekCache(new CasSeekCacheAdapter({
+    persistence,
+    plumbing: persistence.plumbing,
+    graphName,
+  }));
+}

package/bin/cli/types.js

@@ -0,0 +1,96 @@
+/**
+ * @typedef {Object} Persistence
+ * @property {(prefix: string) => Promise<string[]>} listRefs
+ * @property {(ref: string) => Promise<string|null>} readRef
+ * @property {(ref: string, oid: string) => Promise<void>} updateRef
+ * @property {(ref: string) => Promise<void>} deleteRef
+ * @property {(oid: string) => Promise<Buffer>} readBlob
+ * @property {(buf: Buffer) => Promise<string>} writeBlob
+ * @property {(sha: string) => Promise<{date?: string|null}>} getNodeInfo
+ * @property {(sha: string) => Promise<boolean>} nodeExists
+ * @property {(sha: string, coverageSha: string) => Promise<boolean>} isAncestor
+ * @property {() => Promise<{ok: boolean}>} ping
+ * @property {unknown} plumbing
+ */
+
+/**
+ * @typedef {Object} WarpGraphInstance
+ * @property {(opts?: {ceiling?: number}) => Promise<void>} materialize
+ * @property {() => Promise<Array<{id: string}>>} getNodes
+ * @property {() => Promise<Array<{from: string, to: string, label?: string}>>} getEdges
+ * @property {() => Promise<string|null>} createCheckpoint
+ * @property {() => QueryBuilderLike} query
+ * @property {{ shortestPath: Function }} traverse
+ * @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?: 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]
+ */
+
+/**
+ * @typedef {Object} WriterTickInfo
+ * @property {number[]} ticks
+ * @property {string|null} tipSha
+ * @property {Record<number, string>} [tickShas]
+ */
+
+/**
+ * @typedef {Object} CursorBlob
+ * @property {number} tick
+ * @property {string} [mode]
+ * @property {number} [nodes]
+ * @property {number} [edges]
+ * @property {string} [frontierHash]
+ */
+
+/**
+ * @typedef {Object} CliOptions
+ * @property {string} repo
+ * @property {boolean} json
+ * @property {boolean} ndjson
+ * @property {string|null} view
+ * @property {string|null} graph
+ * @property {string} writer
+ * @property {boolean} help
+ */
+
+/**
+ * @typedef {Object} GraphInfoResult
+ * @property {string} name
+ * @property {{count: number, ids?: string[]}} writers
+ * @property {{ref: string, sha: string|null, date?: string|null}} [checkpoint]
+ * @property {{ref: string, sha: string|null}} [coverage]
+ * @property {Record<string, number>} [writerPatches]
+ * @property {{active: boolean, tick?: number, mode?: string}} [cursor]
+ */
+
+/**
+ * @typedef {Object} SeekSpec
+ * @property {string} action
+ * @property {string|null} tickValue
+ * @property {string|null} name
+ * @property {boolean} noPersistentCache
+ * @property {boolean} diff
+ * @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

@@ -22,11 +22,16 @@ import {
   renderQuery,
   renderPath,
   renderCheck,
+  renderDoctor,
   renderHistory,
   renderError,
   renderMaterialize,
   renderInstallHooks,
   renderSeek,
+  renderVerifyAudit,
+  renderTrust,
+  renderPatchShow,
+  renderPatchList,
 } from './text.js';
 
 // ── Color control ────────────────────────────────────────────────────────────
@@ -58,20 +63,46 @@ 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],
   ['check', renderCheck],
+  ['doctor', renderDoctor],
   ['history', renderHistory],
   ['materialize', renderMaterialize],
   ['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],
@@ -96,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
  */
@@ -140,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;
   }
 
@@ -180,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
  */
@@ -194,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;