@git-stunts/git-warp 10.8.0 → 11.3.3

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<unknown> | {[k:string]: unknown}} JsonValue */
+
+/** @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,80 @@
+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 */
+/** @typedef {{patch: {schema?: number, lamport: number, ops?: Array<{type: string, node?: string, from?: string, to?: string}>}, sha: string}} PatchEntry */
+
+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 {{ops?: Array<{node?: string, from?: string, to?: string}>}} 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: unknown, 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 {PatchEntry} */ { patch }) => patch.lamport <= /** @type {number} */ (cursorInfo.tick));
+  }
+  if (patches.length === 0) {
+    const knownWriters = await graph.discoverWriters();
+    if (knownWriters.length > 0) {
+      throw notFoundError(
+        `No patches found for writer: ${writerId}\nKnown writers: ${knownWriters.join(', ')}\nUse: warp-graph history --writer <id>`
+      );
+    }
+    throw notFoundError(`No patches found for writer: ${writerId}`);
+  }
+
+  const entries = patches
+    .filter((/** @type {PatchEntry} */ { patch }) => !historyOptions.node || patchTouchesNode(patch, historyOptions.node))
+    .map((/** @type {PatchEntry} */ { patch, sha }) => ({
+      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 {{kind: string, version?: string, appended?: boolean}} 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 {{kind: string, version?: string, appended?: boolean}} 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 (err) {
+    if (err instanceof Error && /** @type {{code?: string}} */ (err).code === 'ENOENT') {
+      return null;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Handles the `install-hooks` command.
+ * @param {{options: CliOptions, args: string[]}} params
+ * @returns {Promise<{payload: unknown, 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: unknown, 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) => 'error' in r);
+  return {
+    payload: { graphs: results },
+    exitCode: allFailed ? EXIT_CODES.INTERNAL : EXIT_CODES.OK,
+  };
+}

package/bin/cli/commands/patch.js

@@ -0,0 +1,142 @@
+import { EXIT_CODES, usageError, notFoundError, parseCommandArgs } from '../infrastructure.js';
+import { openGraph } from '../shared.js';
+import { z } from 'zod';
+
+/** @typedef {import('../types.js').CliOptions} CliOptions */
+
+const PATCH_OPTIONS = {
+  writer: { type: 'string' },
+  limit: { type: 'string' },
+};
+
+const patchSchema = z.object({
+  writer: z.string().optional(),
+  limit: z.coerce.number().int().positive().optional(),
+}).strict();
+
+/**
+ * Collects all patches across all writers (or a single writer).
+ * @param {import('../types.js').WarpGraphInstance} graph
+ * @param {string|null} writerFilter
+ * @returns {Promise<Array<{sha: string, writer: string, patch: {schema?: number, lamport: number, ops?: Array<Record<string, unknown>>, context?: Record<string, unknown>}}>>}
+ */
+async function collectPatches(graph, writerFilter) {
+  const writers = writerFilter ? [writerFilter] : await graph.discoverWriters();
+  const all = [];
+  for (const writerId of writers) {
+    const patches = await graph.getWriterPatches(writerId);
+    for (const { patch, sha } of patches) {
+      all.push({ sha, writer: writerId, patch });
+    }
+  }
+  // Sort by lamport ascending
+  all.sort((a, b) => (a.patch.lamport ?? 0) - (b.patch.lamport ?? 0));
+  return all;
+}
+
+/**
+ * Handles the `patch` command: show or list decoded patches.
+ * @param {{options: CliOptions, args: string[]}} params
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
+ */
+export default async function handlePatch({ options, args }) {
+  // First positional is the subaction: show or list
+  const subaction = args[0];
+  const rest = args.slice(1);
+
+  if (subaction === 'show') {
+    return await handlePatchShow({ options, args: rest });
+  }
+  if (subaction === 'list') {
+    return await handlePatchList({ options, args: rest });
+  }
+  if (!subaction) {
+    throw usageError('Usage: warp-graph patch <show|list> [options]\n  show <sha>   Decode and display a single patch\n  list         List all patches');
+  }
+  throw usageError(`Unknown patch subaction: ${subaction}. Use: show, list`);
+}
+
+/**
+ * @param {{options: CliOptions, args: string[]}} params
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
+ */
+async function handlePatchShow({ options, args }) {
+  if (!args[0]) {
+    throw usageError('Usage: warp-graph patch show <sha>');
+  }
+  const targetSha = args[0];
+  const { graph, graphName } = await openGraph(options);
+  const allPatches = await collectPatches(graph, null);
+
+  const match = allPatches.find((p) => p.sha === targetSha || p.sha.startsWith(targetSha));
+  if (!match) {
+    throw notFoundError(`Patch not found: ${targetSha}`);
+  }
+
+  const payload = {
+    graph: graphName,
+    sha: match.sha,
+    writer: match.writer,
+    lamport: match.patch.lamport,
+    schema: match.patch.schema,
+    ops: match.patch.ops,
+    context: match.patch.context,
+  };
+
+  return { payload, exitCode: EXIT_CODES.OK };
+}
+
+/**
+ * @param {{options: CliOptions, args: string[]}} params
+ * @returns {Promise<{payload: unknown, exitCode: number}>}
+ */
+async function handlePatchList({ options, args }) {
+  const { values } = parseCommandArgs(args, PATCH_OPTIONS, patchSchema);
+  const { graph, graphName } = await openGraph(options);
+  const writerFilter = values.writer || null;
+  const allPatches = await collectPatches(graph, writerFilter);
+
+  const limit = values.limit ?? allPatches.length;
+  const entries = allPatches.slice(0, limit).map((p) => ({
+    sha: p.sha.slice(0, 7),
+    fullSha: p.sha,
+    writer: p.writer,
+    lamport: p.patch.lamport,
+    opCount: Array.isArray(p.patch.ops) ? p.patch.ops.length : 0,
+    nodeIds: extractNodeIds(p.patch.ops || []),
+  }));
+
+  const payload = {
+    graph: graphName,
+    total: allPatches.length,
+    showing: entries.length,
+    writerFilter,
+    entries,
+  };
+
+  return { payload, exitCode: EXIT_CODES.OK };
+}
+
+/**
+ * Extracts unique node IDs touched by a patch's operations.
+ * @param {Array<Record<string, unknown>>} ops
+ * @returns {string[]}
+ */
+function extractNodeIds(ops) {
+  if (!Array.isArray(ops)) {
+    return [];
+  }
+  const ids = new Set();
+  for (const op of ops) {
+    if (op.node) {
+      ids.add(op.node);
+    }
+    if (op.from) {
+      ids.add(op.from);
+    }
+    if (op.to) {
+      ids.add(op.to);
+    }
+  }
+  return [...ids].sort();
+}