@git-stunts/git-warp 10.7.0 → 11.2.1

package/bin/cli/schemas.js

@@ -0,0 +1,177 @@
+import { z } from 'zod';
+
+// ============================================================================
+// History
+// ============================================================================
+
+export const historySchema = z.object({
+  node: z.string().optional(),
+}).strict();
+
+// ============================================================================
+// Install-hooks
+// ============================================================================
+
+export const installHooksSchema = z.object({
+  force: z.boolean().default(false),
+}).strict();
+
+// ============================================================================
+// Verify-audit
+// ============================================================================
+
+export const verifyAuditSchema = z.object({
+  since: z.string().min(1, 'Missing value for --since').optional(),
+  writer: z.string().min(1, 'Missing value for --writer').optional(),
+  'trust-mode': z.enum(['warn', 'enforce']).optional(),
+  'trust-pin': z.string().min(1, 'Missing value for --trust-pin').optional(),
+}).strict();
+
+// ============================================================================
+// Path
+// ============================================================================
+
+export const pathSchema = z.object({
+  from: z.string().optional(),
+  to: z.string().optional(),
+  dir: z.enum(['out', 'in', 'both']).optional(),
+  label: z.union([z.string(), z.array(z.string())]).optional(),
+  'max-depth': z.coerce.number().int().nonnegative().optional(),
+}).strict().transform((val) => ({
+  from: val.from ?? null,
+  to: val.to ?? null,
+  dir: val.dir,
+  labels: Array.isArray(val.label) ? val.label : val.label ? [val.label] : [],
+  maxDepth: val['max-depth'],
+}));
+
+// ============================================================================
+// Query
+// ============================================================================
+
+export const querySchema = z.object({
+  match: z.string().optional(),
+  'where-prop': z.union([z.string(), z.array(z.string())]).optional(),
+  select: z.string().optional(),
+}).strict().transform((val) => ({
+  match: val.match ?? null,
+  whereProp: Array.isArray(val['where-prop']) ? val['where-prop'] : val['where-prop'] ? [val['where-prop']] : [],
+  select: val.select,
+}));
+
+// ============================================================================
+// View
+// ============================================================================
+
+export const viewSchema = z.object({
+  list: z.boolean().default(false),
+  log: z.boolean().default(false),
+}).strict();
+
+// ============================================================================
+// Trust
+// ============================================================================
+
+export const trustSchema = z.object({
+  mode: z.enum(['warn', 'enforce']).optional(),
+  'trust-pin': z.string().min(1, 'Missing value for --trust-pin').optional(),
+}).strict().transform((val) => ({
+  mode: val.mode ?? null,
+  trustPin: val['trust-pin'] ?? null,
+}));
+
+// ============================================================================
+// Doctor
+// ============================================================================
+
+export const doctorSchema = z.object({
+  strict: z.boolean().default(false),
+}).strict();
+
+// ============================================================================
+// Seek
+// ============================================================================
+
+export const seekSchema = z.object({
+  tick: z.string().optional(),
+  latest: z.boolean().default(false),
+  save: z.string().min(1, 'Missing value for --save').optional(),
+  load: z.string().min(1, 'Missing value for --load').optional(),
+  list: z.boolean().default(false),
+  drop: z.string().min(1, 'Missing value for --drop').optional(),
+  'clear-cache': z.boolean().default(false),
+  'no-persistent-cache': z.boolean().default(false),
+  diff: z.boolean().default(false),
+  'diff-limit': z.coerce.number().int({ message: '--diff-limit must be a positive integer' }).positive({ message: '--diff-limit must be a positive integer' }).default(2000),
+}).strict().superRefine((val, ctx) => {
+  // Count mutually exclusive action flags
+  const actions = [
+    val.tick !== undefined,
+    val.latest,
+    val.save !== undefined,
+    val.load !== undefined,
+    val.list,
+    val.drop !== undefined,
+    val['clear-cache'],
+  ].filter(Boolean);
+
+  if (actions.length > 1) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'Only one seek action flag allowed at a time (--tick, --latest, --save, --load, --list, --drop, --clear-cache)',
+    });
+  }
+
+  // --diff only with tick/latest/load
+  const DIFF_ACTIONS = val.tick !== undefined || val.latest || val.load !== undefined;
+  if (val.diff && !DIFF_ACTIONS) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: '--diff cannot be used without --tick, --latest, or --load',
+    });
+  }
+
+  // --diff-limit requires --diff
+  if (val['diff-limit'] !== 2000 && !val.diff) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: '--diff-limit requires --diff',
+    });
+  }
+}).transform((val) => {
+  /** @type {string} */
+  let action = 'status';
+  /** @type {string|null} */
+  let tickValue = null;
+  /** @type {string|null} */
+  let name = null;
+
+  if (val.tick !== undefined) {
+    action = 'tick';
+    tickValue = val.tick;
+  } else if (val.latest) {
+    action = 'latest';
+  } else if (val.save !== undefined) {
+    action = 'save';
+    name = val.save;
+  } else if (val.load !== undefined) {
+    action = 'load';
+    name = val.load;
+  } else if (val.list) {
+    action = 'list';
+  } else if (val.drop !== undefined) {
+    action = 'drop';
+    name = val.drop;
+  } else if (val['clear-cache']) {
+    action = 'clear-cache';
+  }
+
+  return {
+    action,
+    tickValue,
+    name,
+    noPersistentCache: val['no-persistent-cache'],
+    diff: val.diff,
+    diffLimit: val['diff-limit'],
+  };
+});

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 {*} */ (await WarpGraph.open({ // TODO(ts-cleanup): narrow port type
+    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 {*} */ (fs), // TODO(ts-cleanup): narrow port type
+    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,85 @@
+/**
+ * @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 {*} 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 {() => *} 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 {() => {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 {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
+ */
+
+export {};