@git-stunts/git-warp 10.8.0 → 11.2.1

package/bin/cli/commands/doctor/types.js

@@ -0,0 +1,89 @@
+/**
+ * Type definitions for the `doctor` command.
+ *
+ * @module cli/commands/doctor/types
+ */
+
+// ── JSON-safe recursive value type ──────────────────────────────────────────
+
+/** @typedef {null | boolean | number | string | Array<*> | {[k:string]: *}} JsonValue */ // TODO(ts-cleanup): recursive type
+
+/** @typedef {{[k:string]: JsonValue}} FindingEvidence */
+
+// ── Finding ─────────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} DoctorFinding
+ * @property {string} id - Check identifier (e.g. 'repo-accessible')
+ * @property {'ok'|'warn'|'fail'} status
+ * @property {string} code - Machine-readable code from CODES registry
+ * @property {'data_integrity'|'security'|'operability'|'hygiene'} impact
+ * @property {string} message - Human-readable summary
+ * @property {string} [fix] - Suggested remediation command or instruction
+ * @property {string} [helpUrl] - Stable documentation anchor
+ * @property {FindingEvidence} [evidence] - JSON-safe supporting data
+ * @property {number} [durationMs] - Time spent on this check
+ */
+
+// ── Policy ──────────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} DoctorPolicy
+ * @property {boolean} strict
+ * @property {number} clockSkewMs
+ * @property {number} checkpointMaxAgeHours
+ * @property {number} globalDeadlineMs
+ * @property {{[checkId:string]: number}} checkTimeouts
+ */
+
+// ── Payload ─────────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} DoctorPayload
+ * @property {1} doctorVersion
+ * @property {string} repo
+ * @property {string} graph
+ * @property {string} checkedAt - ISO 8601 timestamp
+ * @property {'ok'|'degraded'|'failed'} health
+ * @property {DoctorPolicy} policy
+ * @property {DoctorSummary} summary
+ * @property {DoctorFinding[]} findings
+ * @property {number} durationMs
+ */
+
+/**
+ * @typedef {Object} DoctorSummary
+ * @property {number} checksRun
+ * @property {number} findingsTotal
+ * @property {number} ok
+ * @property {number} warn
+ * @property {number} fail
+ * @property {string[]} priorityActions
+ */
+
+// ── Context passed to each check ────────────────────────────────────────────
+
+/**
+ * @typedef {Object} DoctorContext
+ * @property {import('../../types.js').Persistence} persistence
+ * @property {string} graphName
+ * @property {Array<{writerId: string, sha: string|null, ref: string}>} writerHeads
+ * @property {DoctorPolicy} policy
+ * @property {string} repoPath
+ */
+
+/**
+ * @callback DoctorCheck
+ * @param {DoctorContext} ctx
+ * @returns {Promise<DoctorFinding|DoctorFinding[]|null>}
+ */
+
+// ── Exit codes ──────────────────────────────────────────────────────────────
+
+export const DOCTOR_EXIT_CODES = {
+  OK: 0,
+  FINDINGS: 3,
+  STRICT_FINDINGS: 4,
+};
+
+export {};

package/bin/cli/commands/history.js

@@ -0,0 +1,73 @@
+import { summarizeOps } from '../../../src/visualization/renderers/ascii/history.js';
+import { EXIT_CODES, notFoundError, parseCommandArgs } from '../infrastructure.js';
+import { historySchema } from '../schemas.js';
+import { openGraph, applyCursorCeiling, emitCursorWarning } from '../shared.js';
+
+/** @typedef {import('../types.js').CliOptions} CliOptions */
+
+const HISTORY_OPTIONS = {
+  node: { type: 'string' },
+};
+
+/** @param {string[]} args */
+function parseHistoryArgs(args) {
+  const { values } = parseCommandArgs(args, HISTORY_OPTIONS, historySchema);
+  return { node: values.node ?? null };
+}
+
+/**
+ * @param {*} patch
+ * @param {string} nodeId
+ */
+function patchTouchesNode(patch, nodeId) {
+  const ops = Array.isArray(patch?.ops) ? patch.ops : [];
+  for (const op of ops) {
+    if (op.node === nodeId) {
+      return true;
+    }
+    if (op.from === nodeId || op.to === nodeId) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Handles the `history` command: shows patch history for a writer.
+ * @param {{options: CliOptions, args: string[]}} params
+ * @returns {Promise<{payload: *, exitCode: number}>}
+ */
+export default async function handleHistory({ options, args }) {
+  const historyOptions = parseHistoryArgs(args);
+  const { graph, graphName, persistence } = await openGraph(options);
+  const cursorInfo = await applyCursorCeiling(graph, persistence, graphName);
+  emitCursorWarning(cursorInfo, null);
+
+  const writerId = options.writer;
+  let patches = await graph.getWriterPatches(writerId);
+  if (cursorInfo.active) {
+    patches = patches.filter((/** @type {*} */ { patch }) => patch.lamport <= /** @type {number} */ (cursorInfo.tick)); // TODO(ts-cleanup): type CLI payload
+  }
+  if (patches.length === 0) {
+    throw notFoundError(`No patches found for writer: ${writerId}`);
+  }
+
+  const entries = patches
+    .filter((/** @type {*} */ { patch }) => !historyOptions.node || patchTouchesNode(patch, historyOptions.node)) // TODO(ts-cleanup): type CLI payload
+    .map((/** @type {*} */ { patch, sha }) => ({ // TODO(ts-cleanup): type CLI payload
+      sha,
+      schema: patch.schema,
+      lamport: patch.lamport,
+      opCount: Array.isArray(patch.ops) ? patch.ops.length : 0,
+      opSummary: Array.isArray(patch.ops) ? summarizeOps(patch.ops) : undefined,
+    }));
+
+  const payload = {
+    graph: graphName,
+    writer: writerId,
+    nodeFilter: historyOptions.node,
+    entries,
+  };
+
+  return { payload, exitCode: EXIT_CODES.OK };
+}

package/bin/cli/commands/info.js

@@ -0,0 +1,139 @@
+import WebCryptoAdapter from '../../../src/infrastructure/adapters/WebCryptoAdapter.js';
+import WarpGraph from '../../../src/domain/WarpGraph.js';
+import {
+  buildCheckpointRef,
+  buildCoverageRef,
+  buildWritersPrefix,
+  parseWriterIdFromRef,
+} from '../../../src/domain/utils/RefLayout.js';
+import { notFoundError } from '../infrastructure.js';
+import { createPersistence, listGraphNames, readActiveCursor, readCheckpointDate } from '../shared.js';
+
+/** @typedef {import('../types.js').CliOptions} CliOptions */
+/** @typedef {import('../types.js').Persistence} Persistence */
+/** @typedef {import('../types.js').GraphInfoResult} GraphInfoResult */
+
+/**
+ * Collects metadata about a single graph (writer count, refs, patches, checkpoint).
+ * @param {Persistence} persistence
+ * @param {string} graphName
+ * @param {Object} [options]
+ * @param {boolean} [options.includeWriterIds=false]
+ * @param {boolean} [options.includeRefs=false]
+ * @param {boolean} [options.includeWriterPatches=false]
+ * @param {boolean} [options.includeCheckpointDate=false]
+ * @returns {Promise<GraphInfoResult>}
+ */
+async function getGraphInfo(persistence, graphName, {
+  includeWriterIds = false,
+  includeRefs = false,
+  includeWriterPatches = false,
+  includeCheckpointDate = false,
+} = {}) {
+  const writersPrefix = buildWritersPrefix(graphName);
+  const writerRefs = typeof persistence.listRefs === 'function'
+    ? await persistence.listRefs(writersPrefix)
+    : [];
+  const writerIds = /** @type {string[]} */ (writerRefs
+    .map((ref) => parseWriterIdFromRef(ref))
+    .filter(Boolean)
+    .sort());
+
+  /** @type {GraphInfoResult} */
+  const info = {
+    name: graphName,
+    writers: {
+      count: writerIds.length,
+    },
+  };
+
+  if (includeWriterIds) {
+    info.writers.ids = writerIds;
+  }
+
+  if (includeRefs || includeCheckpointDate) {
+    const checkpointRef = buildCheckpointRef(graphName);
+    const checkpointSha = await persistence.readRef(checkpointRef);
+
+    /** @type {{ref: string, sha: string|null, date?: string|null}} */
+    const checkpoint = { ref: checkpointRef, sha: checkpointSha || null };
+
+    if (includeCheckpointDate && checkpointSha) {
+      const checkpointDate = await readCheckpointDate(persistence, checkpointSha);
+      checkpoint.date = checkpointDate;
+    }
+
+    info.checkpoint = checkpoint;
+
+    if (includeRefs) {
+      const coverageRef = buildCoverageRef(graphName);
+      const coverageSha = await persistence.readRef(coverageRef);
+      info.coverage = { ref: coverageRef, sha: coverageSha || null };
+    }
+  }
+
+  if (includeWriterPatches && writerIds.length > 0) {
+    const graph = await WarpGraph.open({
+      persistence,
+      graphName,
+      writerId: 'cli',
+      crypto: new WebCryptoAdapter(),
+    });
+    /** @type {Record<string, number>} */
+    const writerPatches = {};
+    for (const writerId of writerIds) {
+      const patches = await graph.getWriterPatches(writerId);
+      writerPatches[/** @type {string} */ (writerId)] = patches.length;
+    }
+    info.writerPatches = writerPatches;
+  }
+
+  return info;
+}
+
+/**
+ * Handles the `info` command: summarizes graphs in the repository.
+ * @param {{options: CliOptions}} params
+ * @returns {Promise<{repo: string, graphs: GraphInfoResult[]}>}
+ */
+export default async function handleInfo({ options }) {
+  const { persistence } = await createPersistence(options.repo);
+  const graphNames = await listGraphNames(persistence);
+
+  if (options.graph && !graphNames.includes(options.graph)) {
+    throw notFoundError(`Graph not found: ${options.graph}`);
+  }
+
+  const detailGraphs = new Set();
+  if (options.graph) {
+    detailGraphs.add(options.graph);
+  } else if (graphNames.length === 1) {
+    detailGraphs.add(graphNames[0]);
+  }
+
+  // In view mode, include extra data for visualization
+  const isViewMode = Boolean(options.view);
+
+  const graphs = [];
+  for (const name of graphNames) {
+    const includeDetails = detailGraphs.has(name);
+    const info = await getGraphInfo(persistence, name, {
+      includeWriterIds: includeDetails || isViewMode,
+      includeRefs: includeDetails || isViewMode,
+      includeWriterPatches: isViewMode,
+      includeCheckpointDate: isViewMode,
+    });
+    const activeCursor = await readActiveCursor(persistence, name);
+    if (activeCursor) {
+      info.cursor = { active: true, tick: activeCursor.tick, mode: activeCursor.mode };
+    } else {
+      info.cursor = { active: false };
+    }
+    graphs.push(info);
+  }
+
+  return {
+    repo: options.repo,
+    graphs,
+  };
+}

package/bin/cli/commands/install-hooks.js

@@ -0,0 +1,128 @@
+import fs from 'node:fs';
+import process from 'node:process';
+import { classifyExistingHook } from '../../../src/domain/services/HookInstaller.js';
+import { EXIT_CODES, usageError, parseCommandArgs } from '../infrastructure.js';
+import { installHooksSchema } from '../schemas.js';
+import { createHookInstaller, isInteractive, promptUser } from '../shared.js';
+
+/** @typedef {import('../types.js').CliOptions} CliOptions */
+
+const INSTALL_HOOKS_OPTIONS = {
+  force: { type: 'boolean', default: false },
+};
+
+/** @param {string[]} args */
+function parseInstallHooksArgs(args) {
+  const { values } = parseCommandArgs(args, INSTALL_HOOKS_OPTIONS, installHooksSchema);
+  return values;
+}
+
+/**
+ * @param {*} classification
+ * @param {{force: boolean}} hookOptions
+ */
+async function resolveStrategy(classification, hookOptions) {
+  if (hookOptions.force) {
+    return 'replace';
+  }
+
+  if (classification.kind === 'none') {
+    return 'install';
+  }
+
+  if (classification.kind === 'ours') {
+    return await promptForOursStrategy(classification);
+  }
+
+  return await promptForForeignStrategy();
+}
+
+/** @param {*} classification */
+async function promptForOursStrategy(classification) {
+  const installer = createHookInstaller();
+  if (classification.version === installer._version) {
+    return 'up-to-date';
+  }
+
+  if (!isInteractive()) {
+    throw usageError('Existing hook found. Use --force or run interactively.');
+  }
+
+  const answer = await promptUser(
+    `Upgrade hook from v${classification.version} to v${installer._version}? [Y/n] `,
+  );
+  if (answer === '' || answer.toLowerCase() === 'y') {
+    return 'upgrade';
+  }
+  return 'skip';
+}
+
+async function promptForForeignStrategy() {
+  if (!isInteractive()) {
+    throw usageError('Existing hook found. Use --force or run interactively.');
+  }
+
+  process.stderr.write('Existing post-merge hook found.\n');
+  process.stderr.write('  1) Append (keep existing hook, add warp section)\n');
+  process.stderr.write('  2) Replace (back up existing, install fresh)\n');
+  process.stderr.write('  3) Skip\n');
+  const answer = await promptUser('Choose [1-3]: ');
+
+  if (answer === '1') {
+    return 'append';
+  }
+  if (answer === '2') {
+    return 'replace';
+  }
+  return 'skip';
+}
+
+/** @param {string} hookPath */
+function readHookContent(hookPath) {
+  try {
+    return fs.readFileSync(hookPath, 'utf8');
+  } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type fs error
+    if (err.code === 'ENOENT') {
+      return null;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Handles the `install-hooks` command.
+ * @param {{options: CliOptions, args: string[]}} params
+ * @returns {Promise<{payload: *, exitCode: number}>}
+ */
+export default async function handleInstallHooks({ options, args }) {
+  const hookOptions = parseInstallHooksArgs(args);
+  const installer = createHookInstaller();
+  const status = installer.getHookStatus(options.repo);
+  const content = readHookContent(status.hookPath);
+  const classification = classifyExistingHook(content);
+  const strategy = await resolveStrategy(classification, hookOptions);
+
+  if (strategy === 'up-to-date') {
+    return {
+      payload: {
+        action: 'up-to-date',
+        hookPath: status.hookPath,
+        version: installer._version,
+      },
+      exitCode: EXIT_CODES.OK,
+    };
+  }
+
+  if (strategy === 'skip') {
+    return {
+      payload: { action: 'skipped' },
+      exitCode: EXIT_CODES.OK,
+    };
+  }
+
+  const result = installer.install(options.repo, { strategy });
+  return {
+    payload: result,
+    exitCode: EXIT_CODES.OK,
+  };
+}

package/bin/cli/commands/materialize.js

@@ -0,0 +1,99 @@
+import WebCryptoAdapter from '../../../src/infrastructure/adapters/WebCryptoAdapter.js';
+import WarpGraph from '../../../src/domain/WarpGraph.js';
+import { EXIT_CODES, notFoundError } from '../infrastructure.js';
+import { createPersistence, listGraphNames, readActiveCursor, emitCursorWarning } from '../shared.js';
+
+/** @typedef {import('../types.js').CliOptions} CliOptions */
+/** @typedef {import('../types.js').Persistence} Persistence */
+
+/**
+ * Materializes a single graph, creates a checkpoint, and returns summary stats.
+ * @param {{persistence: Persistence, graphName: string, writerId: string, ceiling?: number}} params
+ * @returns {Promise<{graph: string, nodes: number, edges: number, properties: number, checkpoint: string|null, writers: Record<string, number>, patchCount: number}>}
+ */
+async function materializeOneGraph({ persistence, graphName, writerId, ceiling }) {
+  const graph = await WarpGraph.open({ persistence, graphName, writerId, crypto: new WebCryptoAdapter() });
+  await graph.materialize(ceiling !== undefined ? { ceiling } : undefined);
+  const nodes = await graph.getNodes();
+  const edges = await graph.getEdges();
+  const checkpoint = ceiling !== undefined ? null : await graph.createCheckpoint();
+  const status = await graph.status();
+
+  // Build per-writer patch counts for the view renderer
+  /** @type {Record<string, number>} */
+  const writers = {};
+  let totalPatchCount = 0;
+  for (const wId of Object.keys(status.frontier)) {
+    const patches = await graph.getWriterPatches(wId);
+    writers[wId] = patches.length;
+    totalPatchCount += patches.length;
+  }
+
+  const properties = await graph.getPropertyCount();
+
+  return {
+    graph: graphName,
+    nodes: nodes.length,
+    edges: edges.length,
+    properties,
+    checkpoint,
+    writers,
+    patchCount: totalPatchCount,
+  };
+}
+
+/**
+ * Handles the `materialize` command: materializes and checkpoints all graphs.
+ * @param {{options: CliOptions}} params
+ * @returns {Promise<{payload: *, exitCode: number}>}
+ */
+export default async function handleMaterialize({ options }) {
+  const { persistence } = await createPersistence(options.repo);
+  const graphNames = await listGraphNames(persistence);
+
+  if (graphNames.length === 0) {
+    return {
+      payload: { graphs: [] },
+      exitCode: EXIT_CODES.OK,
+    };
+  }
+
+  const targets = options.graph
+    ? [options.graph]
+    : graphNames;
+
+  if (options.graph && !graphNames.includes(options.graph)) {
+    throw notFoundError(`Graph not found: ${options.graph}`);
+  }
+
+  const results = [];
+  let cursorWarningEmitted = false;
+  for (const name of targets) {
+    try {
+      const cursor = await readActiveCursor(persistence, name);
+      const ceiling = cursor ? cursor.tick : undefined;
+      if (cursor && !cursorWarningEmitted) {
+        emitCursorWarning({ active: true, tick: cursor.tick, maxTick: null }, null);
+        cursorWarningEmitted = true;
+      }
+      const result = await materializeOneGraph({
+        persistence,
+        graphName: name,
+        writerId: options.writer,
+        ceiling,
+      });
+      results.push(result);
+    } catch (error) {
+      results.push({
+        graph: name,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  const allFailed = results.every((r) => /** @type {*} */ (r).error); // TODO(ts-cleanup): type CLI payload
+  return {
+    payload: { graphs: results },
+    exitCode: allFailed ? EXIT_CODES.INTERNAL : EXIT_CODES.OK,
+  };
+}

package/bin/cli/commands/path.js

@@ -0,0 +1,88 @@
+import { renderSvg } from '../../../src/visualization/renderers/svg/index.js';
+import { layoutGraph, pathResultToGraphData } from '../../../src/visualization/layouts/index.js';
+import { EXIT_CODES, usageError, notFoundError, parseCommandArgs } from '../infrastructure.js';
+import { openGraph, applyCursorCeiling, emitCursorWarning } from '../shared.js';
+import { pathSchema } from '../schemas.js';
+
+/** @typedef {import('../types.js').CliOptions} CliOptions */
+
+const PATH_OPTIONS = {
+  from: { type: 'string' },
+  to: { type: 'string' },
+  dir: { type: 'string' },
+  label: { type: 'string', multiple: true },
+  'max-depth': { type: 'string' },
+};
+
+/** @param {string[]} args */
+function parsePathArgs(args) {
+  const { values, positionals } = parseCommandArgs(args, PATH_OPTIONS, pathSchema, { allowPositionals: true });
+
+  // Positionals can supply from/to when flags are omitted
+  const from = values.from || positionals[0] || null;
+  const to = values.to || positionals[1] || null;
+
+  if (!from || !to) {
+    throw usageError('Path requires --from and --to (or two positional ids)');
+  }
+
+  // Expand comma-separated labels
+  const labels = values.labels.flatMap((/** @type {string} */ l) => l.split(',').map((/** @type {string} */ s) => s.trim()).filter(Boolean));
+
+  /** @type {string|string[]|undefined} */
+  let labelFilter;
+  if (labels.length === 1) {
+    labelFilter = labels[0];
+  } else if (labels.length > 1) {
+    labelFilter = labels;
+  }
+
+  return { from, to, dir: values.dir, labelFilter, maxDepth: values.maxDepth };
+}
+
+/**
+ * Handles the `path` command: finds a shortest path between two nodes.
+ * @param {{options: CliOptions, args: string[]}} params
+ * @returns {Promise<{payload: *, exitCode: number}>}
+ */
+export default async function handlePath({ options, args }) {
+  const pathOptions = parsePathArgs(args);
+  const { graph, graphName, persistence } = await openGraph(options);
+  const cursorInfo = await applyCursorCeiling(graph, persistence, graphName);
+  emitCursorWarning(cursorInfo, null);
+
+  try {
+    const result = await graph.traverse.shortestPath(
+      pathOptions.from,
+      pathOptions.to,
+      {
+        dir: pathOptions.dir,
+        labelFilter: pathOptions.labelFilter,
+        maxDepth: pathOptions.maxDepth,
+      }
+    );
+
+    const payload = {
+      graph: graphName,
+      from: pathOptions.from,
+      to: pathOptions.to,
+      ...result,
+    };
+
+    if (options.view && result.found && typeof options.view === 'string' && (options.view.startsWith('svg:') || options.view.startsWith('html:'))) {
+      const graphData = pathResultToGraphData(payload);
+      const positioned = await layoutGraph(graphData, { type: 'path' });
+      payload._renderedSvg = renderSvg(positioned, { title: `${graphName} path` });
+    }
+
+    return {
+      payload,
+      exitCode: result.found ? EXIT_CODES.OK : EXIT_CODES.NOT_FOUND,
+    };
+  } catch (/** @type {*} */ error) { // TODO(ts-cleanup): type error
+    if (error && error.code === 'NODE_NOT_FOUND') {
+      throw notFoundError(error.message);
+    }
+    throw error;
+  }
+}