@git-stunts/git-warp 10.7.0 → 11.2.1

package/bin/cli/commands/trust.js

@@ -0,0 +1,154 @@
+/**
+ * CLI handler for `git warp trust`.
+ *
+ * Evaluates writer trust status against signed evidence in the trust
+ * record chain. Returns a TrustAssessment payload.
+ *
+ * @module cli/commands/trust
+ */
+
+import { EXIT_CODES, parseCommandArgs, getEnvVar } from '../infrastructure.js';
+import { trustSchema } from '../schemas.js';
+import { createPersistence, resolveGraphName } from '../shared.js';
+import defaultCodec from '../../../src/domain/utils/defaultCodec.js';
+import { TrustRecordService } from '../../../src/domain/trust/TrustRecordService.js';
+import { buildState } from '../../../src/domain/trust/TrustStateBuilder.js';
+import { evaluateWriters } from '../../../src/domain/trust/TrustEvaluator.js';
+
+/** @typedef {import('../types.js').CliOptions} CliOptions */
+
+const TRUST_OPTIONS = {
+  mode: { type: 'string' },
+  'trust-pin': { type: 'string' },
+};
+
+/**
+ * @param {string[]} args
+ * @returns {{ mode: string|null, trustPin: string|null }}
+ */
+export function parseTrustArgs(args) {
+  const { values } = parseCommandArgs(args, TRUST_OPTIONS, trustSchema);
+  return values;
+}
+
+/**
+ * Resolves the trust pin from CLI flag → env → live ref.
+ * @param {string|null} cliPin
+ * @returns {{pin: string|null, source: string, sourceDetail: string|null, status: string}}
+ */
+function resolveTrustPin(cliPin) {
+  if (cliPin) {
+    return { pin: cliPin, source: 'cli_pin', sourceDetail: cliPin, status: 'pinned' };
+  }
+  const envPin = getEnvVar('WARP_TRUST_PIN');
+  if (envPin) {
+    return { pin: envPin, source: 'env_pin', sourceDetail: envPin, status: 'pinned' };
+  }
+  return { pin: null, source: 'ref', sourceDetail: null, status: 'configured' };
+}
+
+/**
+ * Discovers all writer IDs from the writers prefix refs.
+ * @param {*} persistence
+ * @param {string} graphName
+ * @returns {Promise<string[]>}
+ */
+async function discoverWriterIds(persistence, graphName) {
+  const prefix = `refs/warp/${graphName}/writers/`;
+  const refs = await persistence.listRefs(prefix);
+  return refs
+    .map((/** @type {string} */ ref) => ref.slice(prefix.length))
+    .filter((/** @type {string} */ id) => id.length > 0)
+    .sort();
+}
+
+/**
+ * Builds a not_configured assessment when no trust records exist.
+ * @param {string} graphName
+ * @returns {{payload: *, exitCode: number}}
+ */
+function buildNotConfiguredResult(graphName) {
+  return {
+    payload: {
+      graph: graphName,
+      trustSchemaVersion: 1,
+      mode: 'signed_evidence_v1',
+      trustVerdict: 'not_configured',
+      trust: {
+        status: 'not_configured',
+        source: 'none',
+        sourceDetail: null,
+        evaluatedWriters: [],
+        untrustedWriters: [],
+        explanations: [],
+        evidenceSummary: {
+          recordsScanned: 0,
+          activeKeys: 0,
+          revokedKeys: 0,
+          activeBindings: 0,
+          revokedBindings: 0,
+        },
+      },
+    },
+    exitCode: EXIT_CODES.OK,
+  };
+}
+
+/**
+ * @param {{options: CliOptions, args: string[]}} params
+ * @returns {Promise<{payload: *, exitCode: number}>}
+ */
+export default async function handleTrust({ options, args }) {
+  const { mode, trustPin } = parseTrustArgs(args);
+  const { persistence } = await createPersistence(options.repo);
+  const graphName = await resolveGraphName(persistence, options.graph);
+
+  const recordService = new TrustRecordService({
+    persistence: /** @type {*} TODO(ts-cleanup) */ (persistence),
+    codec: defaultCodec,
+  });
+
+  // Resolve pin (determines source + status)
+  const { pin, source, sourceDetail, status } = resolveTrustPin(trustPin);
+
+  // Read trust records
+  const records = await recordService.readRecords(graphName, pin ? { tip: pin } : {});
+
+  if (records.length === 0) {
+    return buildNotConfiguredResult(graphName);
+  }
+
+  // Build trust state
+  const trustState = buildState(records);
+
+  // Discover writers
+  const writerIds = await discoverWriterIds(persistence, graphName);
+
+  // Build policy
+  const policy = {
+    schemaVersion: 1,
+    mode: mode ?? 'warn',
+    writerPolicy: 'all_writers_must_be_trusted',
+  };
+
+  // Evaluate
+  const assessment = evaluateWriters(writerIds, trustState, policy);
+
+  // Override source/status from pin resolution (evaluator sets defaults)
+  const payload = {
+    graph: graphName,
+    ...assessment,
+    trust: {
+      ...assessment.trust,
+      status,
+      source,
+      sourceDetail,
+    },
+  };
+
+  const exitCode = assessment.trustVerdict === 'fail' && (mode === 'enforce')
+    ? EXIT_CODES.TRUST_FAIL
+    : EXIT_CODES.OK;
+
+  return { payload, exitCode };
+}

package/bin/cli/commands/verify-audit.js

@@ -0,0 +1,113 @@
+import { AuditVerifierService } from '../../../src/domain/services/AuditVerifierService.js';
+import defaultCodec from '../../../src/domain/utils/defaultCodec.js';
+import { EXIT_CODES, parseCommandArgs, getEnvVar } from '../infrastructure.js';
+import { verifyAuditSchema } from '../schemas.js';
+import { createPersistence, resolveGraphName } from '../shared.js';
+
+/** @typedef {import('../types.js').CliOptions} CliOptions */
+
+/**
+ * Detects trust configuration from environment and returns a structured warning.
+ * Domain services never read process.env — detection happens at the CLI boundary.
+ * @returns {{ code: string, message: string, sources: string[] } | null}
+ */
+function detectTrustWarning() {
+  const sources = [];
+  if (getEnvVar('WARP_TRUSTED_ROOT')) {
+    sources.push('env');
+  }
+  if (sources.length === 0) {
+    return null;
+  }
+  return {
+    code: 'TRUST_CONFIG_PRESENT_UNENFORCED',
+    message: 'Trust root configured but signature verification is not implemented in v1',
+    sources,
+  };
+}
+
+const VERIFY_AUDIT_OPTIONS = {
+  since: { type: 'string' },
+  writer: { type: 'string' },
+  'trust-mode': { type: 'string' },
+  'trust-pin': { type: 'string' },
+};
+
+/** @param {string[]} args */
+export function parseVerifyAuditArgs(args) {
+  const { values } = parseCommandArgs(args, VERIFY_AUDIT_OPTIONS, verifyAuditSchema);
+  return {
+    since: values.since,
+    writerFilter: values.writer,
+    trustMode: values['trust-mode'],
+    trustPin: values['trust-pin'],
+  };
+}
+
+/**
+ * @param {{options: CliOptions, args: string[]}} params
+ * @returns {Promise<{payload: *, 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
+    codec: defaultCodec,
+  });
+
+  const trustWarning = detectTrustWarning();
+
+  /** @type {*} */ // TODO(ts-cleanup): type verify-audit payload
+  let payload;
+  if (writerFilter !== undefined) {
+    const chain = await verifier.verifyChain(graphName, writerFilter, { since });
+    const invalid = chain.status !== 'VALID' && chain.status !== 'PARTIAL' ? 1 : 0;
+    payload = {
+      graph: graphName,
+      verifiedAt: new Date().toISOString(),
+      summary: {
+        total: 1,
+        valid: chain.status === 'VALID' ? 1 : 0,
+        partial: chain.status === 'PARTIAL' ? 1 : 0,
+        invalid,
+      },
+      chains: [chain],
+      trustWarning,
+    };
+  } else {
+    payload = await verifier.verifyAll(graphName, { since, trustWarning });
+  }
+
+  // Attach trust assessment only when explicitly requested via --trust-mode
+  if (trustMode) {
+    try {
+      const trustAssessment = await verifier.evaluateTrust(graphName, {
+        pin: trustPin,
+        mode: trustMode,
+      });
+      payload.trustAssessment = trustAssessment;
+    } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type catch
+      if (trustMode === 'enforce') {
+        throw err;
+      }
+      payload.trustAssessment = {
+        trustSchemaVersion: 1,
+        mode: 'signed_evidence_v1',
+        trustVerdict: 'error',
+        error: err?.message ?? 'Trust evaluation failed',
+      };
+    }
+  }
+
+  const hasInvalid = payload.summary.invalid > 0;
+  const trustFailed = trustMode === 'enforce' &&
+    payload.trustAssessment?.trustVerdict === 'fail';
+  return {
+    payload,
+    exitCode: trustFailed ? EXIT_CODES.TRUST_FAIL
+      : hasInvalid ? EXIT_CODES.INTERNAL
+        : EXIT_CODES.OK,
+  };
+}

package/bin/cli/commands/view.js

@@ -0,0 +1,45 @@
+import process from 'node:process';
+import { parseCommandArgs, usageError } from '../infrastructure.js';
+import { viewSchema } from '../schemas.js';
+
+/** @typedef {import('../types.js').CliOptions} CliOptions */
+
+const VIEW_OPTIONS = {
+  list: { type: 'boolean', default: false },
+  log: { type: 'boolean', default: false },
+};
+
+/**
+ * @param {{options: CliOptions, args: string[]}} params
+ * @returns {Promise<{payload: *, exitCode: number}>}
+ */
+export default async function handleView({ options, args }) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw usageError('view command requires an interactive terminal (TTY)');
+  }
+
+  const { values, positionals } = parseCommandArgs(args, VIEW_OPTIONS, viewSchema, { allowPositionals: true });
+  const viewMode = values.log || positionals[0] === 'log' ? 'log' : 'list';
+
+  try {
+    // @ts-expect-error — optional peer dependency, may not be installed
+    const { startTui } = await import('@git-stunts/git-warp-tui');
+    await startTui({
+      repo: options.repo || '.',
+      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);
+    if (isMissing && isTui) {
+      throw usageError(
+        'Interactive TUI requires @git-stunts/git-warp-tui.\n' +
+        '  Install with: npm install -g @git-stunts/git-warp-tui',
+      );
+    }
+    throw err;
+  }
+  return { payload: undefined, exitCode: 0 };
+}

package/bin/cli/infrastructure.js

@@ -0,0 +1,336 @@
+import path from 'node:path';
+import process from 'node:process';
+import { parseArgs as nodeParseArgs } from 'node:util';
+
+/** @typedef {import('./types.js').CliOptions} CliOptions */
+
+export const EXIT_CODES = {
+  OK: 0,
+  USAGE: 1,
+  NOT_FOUND: 2,
+  INTERNAL: 3,
+  /** Trust policy denial (enforce mode). */
+  TRUST_FAIL: 4,
+};
+
+/**
+ * Reads an environment variable across Node, Bun, and Deno runtimes.
+ * @param {string} name
+ * @returns {string|undefined}
+ */
+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; }
+  }
+  return undefined;
+}
+
+export const HELP_TEXT = `warp-graph <command> [options]
+(or: git warp <command> [options])
+
+Commands:
+  info             Summarize graphs in the repo
+  query            Run a logical graph query
+  path             Find a logical path between two nodes
+  history          Show writer history
+  check            Report graph health/GC status
+  doctor           Diagnose structural issues and suggest fixes
+  verify-audit     Verify audit receipt chain integrity
+  trust            Evaluate writer trust from signed evidence
+  materialize      Materialize and checkpoint all graphs
+  seek             Time-travel: step through graph history by Lamport tick
+  view             Interactive TUI graph browser (requires @git-stunts/git-warp-tui)
+  install-hooks    Install post-merge git hook
+
+Options:
+  --repo <path>     Path to git repo (default: cwd)
+  --json            Emit JSON output (pretty-printed, sorted keys)
+  --ndjson          Emit compact single-line JSON (for piping/scripting)
+  --view [mode]     Visual output (ascii, browser, svg:FILE, html:FILE)
+  --graph <name>    Graph name (required if repo has multiple graphs)
+  --writer <id>     Writer id (default: cli)
+  -h, --help        Show this help
+
+Install-hooks options:
+  --force           Replace existing hook (backs up original)
+
+Query options:
+  --match <glob>        Match node ids (default: *)
+  --outgoing [label]    Traverse outgoing edge (repeatable)
+  --incoming [label]    Traverse incoming edge (repeatable)
+  --where-prop k=v      Filter nodes by prop equality (repeatable)
+  --select <fields>     Fields to select (id, props)
+
+Path options:
+  --from <id>           Start node id
+  --to <id>             End node id
+  --dir <out|in|both>   Traversal direction (default: out)
+  --label <label>       Filter by edge label (repeatable, comma-separated)
+  --max-depth <n>       Maximum depth
+
+History options:
+  --node <id>           Filter patches touching node id
+
+Doctor options:
+  --strict              Treat warnings as failures (exit 4)
+
+Verify-audit options:
+  --writer <id>         Verify a single writer's chain (default: all)
+  --since <commit>      Verify from tip down to this commit (inclusive)
+  --trust-mode <mode>   Trust evaluation mode (warn, enforce)
+  --trust-pin <sha>     Pin trust evaluation to a specific record chain commit
+
+Trust options:
+  --mode <warn|enforce> Override trust evaluation mode
+  --trust-pin <sha>     Pin trust evaluation to a specific record chain commit
+
+Seek options:
+  --tick <N|+N|-N>      Jump to tick N, or step forward/backward
+  --latest              Clear cursor, return to present
+  --save <name>         Save current position as named cursor
+  --load <name>         Restore a saved cursor
+  --list                List all saved cursors
+  --drop <name>         Delete a saved cursor
+  --diff                Show structural diff (added/removed nodes, edges, props)
+  --diff-limit <N>      Max diff entries (default 2000)
+`;
+
+/**
+ * Structured CLI error with exit code and error code.
+ */
+export class CliError extends Error {
+  /**
+   * @param {string} message - Human-readable error message
+   * @param {Object} [options]
+   * @param {string} [options.code='E_CLI'] - Machine-readable error code
+   * @param {number} [options.exitCode=3] - Process exit code
+   * @param {Error} [options.cause] - Underlying cause
+   */
+  constructor(message, { code = 'E_CLI', exitCode = EXIT_CODES.INTERNAL, cause } = {}) {
+    super(message);
+    this.code = code;
+    this.exitCode = exitCode;
+    this.cause = cause;
+  }
+}
+
+/** @param {string} message */
+export function usageError(message) {
+  return new CliError(message, { code: 'E_USAGE', exitCode: EXIT_CODES.USAGE });
+}
+
+/** @param {string} message */
+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'];
+
+const BASE_OPTIONS = {
+  repo:   { type: 'string', short: 'r' },
+  json:   { type: 'boolean', default: false },
+  ndjson: { type: 'boolean', default: false },
+  view:   { type: 'string' },
+  graph:  { type: 'string' },
+  writer: { type: 'string', default: 'cli' },
+  help:   { type: 'boolean', short: 'h', default: false },
+};
+
+/**
+ * Pre-processes argv to handle --view's optional-value semantics.
+ * If --view is followed by a command name or flag (or is last), injects 'ascii'.
+ * Validates the view mode value.
+ * @param {string[]} argv
+ * @returns {string[]}
+ */
+function preprocessView(argv) {
+  const idx = argv.indexOf('--view');
+  if (idx === -1) {
+    return argv;
+  }
+  const next = argv[idx + 1];
+  const needsDefault = !next || next.startsWith('-') || KNOWN_COMMANDS.includes(next);
+  if (needsDefault) {
+    return [...argv.slice(0, idx + 1), 'ascii', ...argv.slice(idx + 1)];
+  }
+  const validModes = ['ascii', 'browser'];
+  const validPrefixes = ['svg:', 'html:'];
+  const isValid = validModes.includes(next) ||
+    validPrefixes.some((prefix) => next.startsWith(prefix));
+  if (!isValid) {
+    throw usageError(`Invalid view mode: ${next}. Valid modes: ascii, browser, svg:FILE, html:FILE`);
+  }
+  return argv;
+}
+
+/** String flags that always consume a value argument */
+const BASE_STRING_FLAGS = new Set(['--repo', '-r', '--graph', '--writer']);
+/** Boolean flags (no value) */
+const BASE_BOOL_FLAGS = new Set(['--json', '--ndjson', '--help', '-h']);
+
+/**
+ * Checks if a value looks like it belongs to --view (not a flag or command).
+ * @param {string|undefined} next
+ * @returns {boolean}
+ */
+function isViewValue(next) {
+  if (!next || next.startsWith('-') || KNOWN_COMMANDS.includes(next)) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Extracts base flags from anywhere in argv, leaving command + commandArgs.
+ *
+ * Base flags (--repo, --graph, --writer, --view, --json, --ndjson, --help)
+ * can appear before or after the command. Everything else (unknown flags,
+ * positionals after the command) becomes commandArgs.
+ *
+ * @param {string[]} argv
+ * @returns {{baseArgs: string[], command: string|undefined, commandArgs: string[]}}
+ */
+function extractBaseArgs(argv) {
+  /** @type {string[]} */
+  const baseArgs = [];
+  /** @type {string[]} */
+  const rest = [];
+  /** @type {string|undefined} */
+  let command;
+  let pastCommand = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (arg === '--') {
+      rest.push(...argv.slice(i + 1));
+      break;
+    }
+
+    if (BASE_STRING_FLAGS.has(arg)) {
+      baseArgs.push(arg);
+      if (i + 1 < argv.length) {
+        baseArgs.push(argv[++i]);
+      }
+      continue;
+    }
+
+    // Handle --flag=value form for string flags
+    if (arg.startsWith('--') && BASE_STRING_FLAGS.has(arg.split('=')[0])) {
+      baseArgs.push(arg);
+      continue;
+    }
+
+    // --view has optional-value semantics: consume next only if it looks like a view mode
+    if (arg === '--view') {
+      baseArgs.push(arg);
+      if (isViewValue(argv[i + 1])) {
+        baseArgs.push(argv[++i]);
+      }
+      continue;
+    }
+
+    if (arg.startsWith('--view=')) {
+      baseArgs.push(arg);
+      continue;
+    }
+
+    if (BASE_BOOL_FLAGS.has(arg)) {
+      baseArgs.push(arg);
+      continue;
+    }
+
+    if (!pastCommand && !arg.startsWith('-')) {
+      command = arg;
+      pastCommand = true;
+      continue;
+    }
+
+    rest.push(arg);
+  }
+
+  return { baseArgs, command, commandArgs: rest };
+}
+
+/**
+ * Two-pass arg parser using node:util.parseArgs.
+ *
+ * Pass 1: extract base flags from anywhere in argv.
+ * Pass 2: pre-process --view (optional-value semantics) on base args.
+ * Pass 3: parseArgs with strict:true on base args only.
+ *
+ * @param {string[]} argv
+ * @returns {{options: CliOptions, command: string|undefined, commandArgs: string[]}}
+ */
+export function parseArgs(argv) {
+  const { baseArgs, command, commandArgs } = extractBaseArgs(argv);
+  const processed = preprocessView(baseArgs);
+
+  /** @type {*} */ // TODO(ts-cleanup): type parseArgs return
+  let parsed;
+  try {
+    parsed = nodeParseArgs({
+      args: processed,
+      options: /** @type {*} */ (BASE_OPTIONS), // TODO(ts-cleanup): type parseArgs config
+      strict: true,
+      allowPositionals: false,
+    });
+  } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type parseArgs error
+    throw usageError(err.message);
+  }
+
+  const { values } = parsed;
+
+  /** @type {CliOptions} */
+  const options = {
+    repo: path.resolve(typeof values.repo === 'string' ? values.repo : process.cwd()),
+    json: Boolean(values.json),
+    ndjson: Boolean(values.ndjson),
+    view: typeof values.view === 'string' ? values.view : null,
+    graph: typeof values.graph === 'string' ? values.graph : null,
+    writer: typeof values.writer === 'string' ? values.writer : 'cli',
+    help: Boolean(values.help),
+  };
+
+  return { options, command, commandArgs };
+}
+
+/**
+ * Parses command-level args using node:util.parseArgs + Zod validation.
+ *
+ * @param {string[]} args - Command-specific args (after command name)
+ * @param {Object} config - parseArgs options config
+ * @param {import('zod').ZodType} schema - Zod schema to validate/transform parsed values
+ * @param {Object} [opts]
+ * @param {boolean} [opts.allowPositionals=false] - Whether to allow positional arguments
+ * @returns {{values: *, positionals: string[]}}
+ */
+export function parseCommandArgs(args, config, schema, { allowPositionals = false } = {}) {
+  /** @type {*} */ // TODO(ts-cleanup): type parseArgs return
+  let parsed;
+  try {
+    parsed = nodeParseArgs({
+      args,
+      options: /** @type {*} */ (config), // TODO(ts-cleanup): type parseArgs config
+      strict: true,
+      allowPositionals,
+    });
+  } catch (/** @type {*} */ err) { // TODO(ts-cleanup): type parseArgs error
+    throw usageError(err.message);
+  }
+
+  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
+    throw usageError(msg);
+  }
+
+  return { values: result.data, positionals: parsed.positionals || [] };
+}
+