@git-stunts/git-warp 10.1.1

package/src/ports/GraphPersistencePort.js

@@ -0,0 +1,57 @@
+/**
+ * Abstract port for graph persistence operations.
+ *
+ * Defines the contract for reading and writing graph data to a Git-backed
+ * storage layer. Concrete adapters (e.g., GitGraphAdapter) implement this
+ * interface to provide actual Git operations.
+ *
+ * This is a **composite port** that implements the union of five focused ports:
+ *
+ * - {@link CommitPort} — commit creation, reading, logging, counting, ping
+ * - {@link BlobPort} — blob read/write
+ * - {@link TreePort} — tree read/write, emptyTree getter
+ * - {@link RefPort} — ref update/read/delete
+ * - {@link ConfigPort} — git config get/set
+ *
+ * Domain services should document which focused port(s) they actually depend on
+ * via JSDoc, even though they accept the full GraphPersistencePort at runtime.
+ * This enables future narrowing without breaking backward compatibility.
+ *
+ * All methods throw by default and must be overridden by implementations.
+ *
+ * @abstract
+ * @implements {CommitPort}
+ * @implements {BlobPort}
+ * @implements {TreePort}
+ * @implements {RefPort}
+ * @implements {ConfigPort}
+ */
+
+import CommitPort from './CommitPort.js';
+import BlobPort from './BlobPort.js';
+import TreePort from './TreePort.js';
+import RefPort from './RefPort.js';
+import ConfigPort from './ConfigPort.js';
+
+class GraphPersistencePort {}
+
+const focusedPorts = [CommitPort, BlobPort, TreePort, RefPort, ConfigPort];
+const seen = new Map();
+
+for (const Port of focusedPorts) {
+  const descriptors = Object.getOwnPropertyDescriptors(Port.prototype);
+  delete descriptors.constructor;
+
+  for (const [name, descriptor] of Object.entries(descriptors)) {
+    if (seen.has(name)) {
+      throw new Error(
+        `GraphPersistencePort composition collision: "${name}" defined by both ` +
+          `${seen.get(name).name} and ${Port.name}`,
+      );
+    }
+    seen.set(name, Port);
+    Object.defineProperty(GraphPersistencePort.prototype, name, descriptor);
+  }
+}
+
+export default GraphPersistencePort;

package/src/ports/HttpServerPort.js

@@ -0,0 +1,25 @@
+/**
+ * Port for HTTP server creation.
+ *
+ * Abstracts platform-specific HTTP server APIs so domain code
+ * doesn't depend on node:http directly.
+ */
+export default class HttpServerPort {
+  /**
+   * Creates an HTTP server with a platform-agnostic request handler.
+   *
+   * The request handler receives a plain object `{ method, url, headers, body }`
+   * and must return `{ status, headers, body }`. No raw req/res objects
+   * are exposed to the domain.
+   *
+   * @param {Function} requestHandler - Async function (request) => response
+   * @param {string} requestHandler.method - HTTP method
+   * @param {string} requestHandler.url - Request URL
+   * @param {Object} requestHandler.headers - Request headers (lowercased keys)
+   * @param {Buffer|undefined} requestHandler.body - Request body (undefined if none)
+   * @returns {{ listen: Function, close: Function, address: Function }} Server with listen(port, [host], cb(err)), close(cb), and address()
+   */
+  createServer(_requestHandler) {
+    throw new Error('HttpServerPort.createServer() not implemented');
+  }
+}

package/src/ports/IndexStoragePort.js

@@ -0,0 +1,39 @@
+/**
+ * Port interface for bitmap index storage operations.
+ *
+ * This port defines the contract for persisting and retrieving
+ * the sharded bitmap index data. Adapters implement this interface
+ * to store indexes in different backends (Git, filesystem, etc.).
+ *
+ * This port is a subset of the focused ports: it uses methods from
+ * {@link BlobPort} (writeBlob, readBlob), {@link TreePort} (writeTree,
+ * readTreeOids), and {@link RefPort} (updateRef, readRef).
+ *
+ * @abstract
+ */
+
+import BlobPort from './BlobPort.js';
+import TreePort from './TreePort.js';
+import RefPort from './RefPort.js';
+
+class IndexStoragePort {}
+
+const picks = [
+  [BlobPort, ['writeBlob', 'readBlob']],
+  [TreePort, ['writeTree', 'readTreeOids']],
+  [RefPort, ['updateRef', 'readRef']],
+];
+
+for (const [Port, methods] of picks) {
+  const descriptors = Object.getOwnPropertyDescriptors(Port.prototype);
+  for (const name of methods) {
+    if (!descriptors[name]) {
+      throw new Error(
+        `IndexStoragePort: "${name}" not found on ${Port.name}.prototype`,
+      );
+    }
+    Object.defineProperty(IndexStoragePort.prototype, name, descriptors[name]);
+  }
+}
+
+export default IndexStoragePort;

package/src/ports/LoggerPort.js

@@ -0,0 +1,68 @@
+/**
+ * Port interface for structured logging operations.
+ *
+ * This port defines the contract for logging across the application.
+ * Adapters implement this interface to provide different logging
+ * backends (console, file, external services, no-op for testing).
+ *
+ * All methods accept an optional context object for structured metadata.
+ * Child loggers inherit and merge parent context.
+ *
+ * @abstract
+ */
+export default class LoggerPort {
+  /**
+   * Log a debug-level message.
+   * @param {string} message - The log message
+   * @param {Record<string, unknown>} [context] - Structured metadata
+   * @returns {void}
+   * @abstract
+   */
+  debug(_message, _context) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Log an info-level message.
+   * @param {string} message - The log message
+   * @param {Record<string, unknown>} [context] - Structured metadata
+   * @returns {void}
+   * @abstract
+   */
+  info(_message, _context) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Log a warning-level message.
+   * @param {string} message - The log message
+   * @param {Record<string, unknown>} [context] - Structured metadata
+   * @returns {void}
+   * @abstract
+   */
+  warn(_message, _context) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Log an error-level message.
+   * @param {string} message - The log message
+   * @param {Record<string, unknown>} [context] - Structured metadata
+   * @returns {void}
+   * @abstract
+   */
+  error(_message, _context) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Create a child logger with additional base context.
+   * Child loggers inherit parent context and merge with their own.
+   * @param {Record<string, unknown>} context - Base context for the child logger
+   * @returns {LoggerPort} A new logger instance with merged context
+   * @abstract
+   */
+  child(_context) {
+    throw new Error('Not implemented');
+  }
+}

package/src/ports/RefPort.js

@@ -0,0 +1,51 @@
+/**
+ * Port for Git ref operations.
+ *
+ * Defines the contract for creating, reading, and deleting Git refs.
+ * This is one of five focused ports extracted from GraphPersistencePort.
+ *
+ * @abstract
+ * @see GraphPersistencePort - Composite port implementing all five focused ports
+ */
+export default class RefPort {
+  /**
+   * Updates a ref to point to an OID.
+   * @param {string} ref - The ref name (e.g., 'refs/warp/events/writers/alice')
+   * @param {string} oid - The OID to point to
+   * @returns {Promise<void>}
+   * @throws {Error} If not implemented by a concrete adapter
+   */
+  async updateRef(_ref, _oid) {
+    throw new Error('RefPort.updateRef() not implemented');
+  }
+
+  /**
+   * Reads the OID a ref points to.
+   * @param {string} ref - The ref name
+   * @returns {Promise<string|null>} The OID, or null if the ref does not exist
+   * @throws {Error} If not implemented by a concrete adapter
+   */
+  async readRef(_ref) {
+    throw new Error('RefPort.readRef() not implemented');
+  }
+
+  /**
+   * Deletes a ref.
+   * @param {string} ref - The ref name to delete
+   * @returns {Promise<void>}
+   * @throws {Error} If not implemented by a concrete adapter
+   */
+  async deleteRef(_ref) {
+    throw new Error('RefPort.deleteRef() not implemented');
+  }
+
+  /**
+   * Lists refs matching a prefix.
+   * @param {string} prefix - The ref prefix to match (e.g., 'refs/warp/events/writers/')
+   * @returns {Promise<string[]>} Array of matching ref names
+   * @throws {Error} If not implemented by a concrete adapter
+   */
+  async listRefs(_prefix) {
+    throw new Error('RefPort.listRefs() not implemented');
+  }
+}

package/src/ports/TreePort.js

@@ -0,0 +1,51 @@
+/**
+ * Port for Git tree operations.
+ *
+ * Defines the contract for writing and reading Git tree objects.
+ * This is one of five focused ports extracted from GraphPersistencePort.
+ *
+ * @abstract
+ * @see GraphPersistencePort - Composite port implementing all five focused ports
+ */
+export default class TreePort {
+  /**
+   * Creates a Git tree from mktree-formatted entries.
+   * @param {string[]} entries - Lines in git mktree format (e.g., "100644 blob <oid>\t<path>")
+   * @returns {Promise<string>} The Git OID of the created tree
+   * @throws {Error} If not implemented by a concrete adapter
+   */
+  async writeTree(_entries) {
+    throw new Error('TreePort.writeTree() not implemented');
+  }
+
+  /**
+   * Reads a tree and returns a map of path to content.
+   * @param {string} treeOid - The tree OID to read
+   * @returns {Promise<Record<string, Buffer>>} Map of file path to blob content
+   * @throws {Error} If not implemented by a concrete adapter
+   */
+  async readTree(_treeOid) {
+    throw new Error('TreePort.readTree() not implemented');
+  }
+
+  /**
+   * Reads a tree and returns a map of path to blob OID.
+   * Useful for lazy-loading shards without reading all blob contents.
+   * @param {string} treeOid - The tree OID to read
+   * @returns {Promise<Record<string, string>>} Map of file path to blob OID
+   * @throws {Error} If not implemented by a concrete adapter
+   */
+  async readTreeOids(_treeOid) {
+    throw new Error('TreePort.readTreeOids() not implemented');
+  }
+
+  /**
+   * The well-known SHA for Git's empty tree object.
+   * All WARP graph commits point to this tree so that no files appear in the working directory.
+   * @type {string}
+   * @readonly
+   */
+  get emptyTree() {
+    throw new Error('TreePort.emptyTree not implemented');
+  }
+}

package/src/visualization/index.js

@@ -0,0 +1,26 @@
+/**
+ * Visualization module - main exports
+ */
+
+// ASCII renderers
+export * from './renderers/ascii/index.js';
+
+// SVG renderer
+export { renderSvg } from './renderers/svg/index.js';
+
+// Layout engine
+export {
+  layoutGraph,
+  queryResultToGraphData,
+  pathResultToGraphData,
+  rawGraphToGraphData,
+  toElkGraph,
+  getDefaultLayoutOptions,
+  runLayout,
+} from './layouts/index.js';
+
+// Utils
+export { truncate } from './utils/truncate.js';
+export { timeAgo, formatDuration } from './utils/time.js';
+export { padRight, padLeft, center } from './utils/unicode.js';
+export { stripAnsi } from './utils/ansi.js';

package/src/visualization/layouts/converters.js

@@ -0,0 +1,75 @@
+/**
+ * Data converters: transform WarpGraph payloads into a normalized graph-data
+ * intermediate format consumed by the ELK adapter.
+ *
+ * Intermediate format:
+ *   { nodes: [{ id, label, props? }], edges: [{ from, to, label? }] }
+ */
+
+/**
+ * Converts a query result payload + edge array into graph data.
+ * Edges are filtered to only those connecting matched nodes.
+ *
+ * @param {Object} payload - Query result { nodes: [{id, props}] }
+ * @param {Array}  edges   - Edge array from graph.getEdges()
+ * @returns {{ nodes: Array, edges: Array }}
+ */
+export function queryResultToGraphData(payload, edges) {
+  const nodes = (payload?.nodes ?? []).map((n) => ({
+    id: n.id,
+    label: n.id,
+    props: n.props,
+  }));
+
+  const nodeSet = new Set(nodes.map((n) => n.id));
+
+  const filtered = (edges ?? [])
+    .filter((e) => nodeSet.has(e.from) && nodeSet.has(e.to))
+    .map((e) => ({ from: e.from, to: e.to, label: e.label }));
+
+  return { nodes, edges: filtered };
+}
+
+/**
+ * Converts a path result payload into graph data.
+ * Builds a linear chain of nodes with labelled edges.
+ *
+ * @param {Object} payload - Path result { path: string[], edges?: string[] }
+ * @returns {{ nodes: Array, edges: Array }}
+ */
+export function pathResultToGraphData(payload) {
+  const pathArr = payload?.path ?? [];
+  const edgeLabels = payload?.edges ?? [];
+
+  const nodes = pathArr.map((id) => ({ id, label: id }));
+
+  const edges = [];
+  for (let i = 0; i < pathArr.length - 1; i++) {
+    edges.push({
+      from: pathArr[i],
+      to: pathArr[i + 1],
+      label: edgeLabels[i],
+    });
+  }
+
+  return { nodes, edges };
+}
+
+/**
+ * Converts raw getNodes() + getEdges() output into graph data.
+ *
+ * @param {string[]} nodeIds - Array of node IDs
+ * @param {Array}    edges   - Edge array from graph.getEdges()
+ * @returns {{ nodes: Array, edges: Array }}
+ */
+export function rawGraphToGraphData(nodeIds, edges) {
+  const nodes = (nodeIds ?? []).map((id) => ({ id, label: id }));
+
+  const mapped = (edges ?? []).map((e) => ({
+    from: e.from,
+    to: e.to,
+    label: e.label,
+  }));
+
+  return { nodes, edges: mapped };
+}

package/src/visualization/layouts/elkAdapter.js

@@ -0,0 +1,86 @@
+/**
+ * ELK adapter: converts normalised graph data into ELK JSON input.
+ */
+
+const LAYOUT_PRESETS = {
+  query: {
+    'elk.algorithm': 'layered',
+    'elk.direction': 'DOWN',
+    'elk.spacing.nodeNode': '40',
+    'elk.layered.spacing.nodeNodeBetweenLayers': '60',
+  },
+  path: {
+    'elk.algorithm': 'layered',
+    'elk.direction': 'RIGHT',
+    'elk.spacing.nodeNode': '40',
+    'elk.layered.spacing.nodeNodeBetweenLayers': '60',
+  },
+  slice: {
+    'elk.algorithm': 'layered',
+    'elk.direction': 'DOWN',
+    'elk.spacing.nodeNode': '40',
+    'elk.layered.spacing.nodeNodeBetweenLayers': '60',
+  },
+};
+
+const DEFAULT_PRESET = LAYOUT_PRESETS.query;
+
+/**
+ * Returns ELK layout options for a given visualisation type.
+ *
+ * @param {'query'|'path'|'slice'} type
+ * @returns {Object} ELK layout options
+ */
+export function getDefaultLayoutOptions(type) {
+  return LAYOUT_PRESETS[type] ?? DEFAULT_PRESET;
+}
+
+/**
+ * Estimates pixel width for a node label.
+ * Approximates monospace glyph width at ~9px with 24px padding.
+ */
+function estimateNodeWidth(label) {
+  const charWidth = 9;
+  const padding = 24;
+  const minWidth = 80;
+  return Math.max((label?.length ?? 0) * charWidth + padding, minWidth);
+}
+
+const NODE_HEIGHT = 40;
+
+/**
+ * Converts normalised graph data to an ELK graph JSON object.
+ *
+ * @param {{ nodes: Array, edges: Array }} graphData
+ * @param {{ type?: string, layoutOptions?: Object }} [options]
+ * @returns {Object} ELK-format graph
+ */
+export function toElkGraph(graphData, options = {}) {
+  const { type = 'query', layoutOptions } = options;
+
+  const children = (graphData.nodes ?? []).map((n) => ({
+    id: n.id,
+    width: estimateNodeWidth(n.label),
+    height: NODE_HEIGHT,
+    labels: [{ text: n.label ?? n.id }],
+  }));
+
+  const edges = (graphData.edges ?? []).map((e, i) => {
+    const edge = {
+      id: `e${i}`,
+      sources: [e.from],
+      targets: [e.to],
+    };
+    if (e.label) {
+      edge.labels = [{ text: e.label }];
+    }
+    return edge;
+  });
+
+  return {
+    id: 'root',
+    layoutOptions: layoutOptions ?? getDefaultLayoutOptions(type),
+    children,
+    edges,
+  };
+}

package/src/visualization/layouts/elkLayout.js

@@ -0,0 +1,95 @@
+/**
+ * ELK layout runner: lazy-loads elkjs and executes layout.
+ *
+ * The ELK engine (~2.5 MB) is loaded via dynamic import() only when
+ * a layout is actually requested, keeping normal CLI startup fast.
+ */
+
+let elkPromise = null;
+
+/**
+ * Returns (or creates) a singleton ELK instance.
+ * @returns {Promise<Object>} ELK instance
+ */
+function getElk() {
+  if (!elkPromise) {
+    elkPromise = import('elkjs/lib/elk.bundled.js').then((mod) => new mod.default());
+  }
+  return elkPromise;
+}
+
+/**
+ * Runs ELK layout on a graph and returns a PositionedGraph.
+ *
+ * @param {Object} elkGraph - ELK-format graph from toElkGraph()
+ * @returns {Promise<Object>} PositionedGraph
+ */
+export async function runLayout(elkGraph) {
+  let result;
+  try {
+    const elk = await getElk();
+    result = await elk.layout(elkGraph);
+  } catch {
+    return fallbackLayout(elkGraph);
+  }
+  return toPositionedGraph(result);
+}
+
+/**
+ * Converts ELK output to a PositionedGraph.
+ */
+function toPositionedGraph(result) {
+  const nodes = (result.children ?? []).map((c) => ({
+    id: c.id,
+    x: c.x ?? 0,
+    y: c.y ?? 0,
+    width: c.width ?? 80,
+    height: c.height ?? 40,
+    label: c.labels?.[0]?.text ?? c.id,
+  }));
+
+  const edges = (result.edges ?? []).map((e) => ({
+    id: e.id,
+    source: e.sources?.[0] ?? '',
+    target: e.targets?.[0] ?? '',
+    label: e.labels?.[0]?.text,
+    sections: e.sections ?? [],
+  }));
+
+  return {
+    nodes,
+    edges,
+    width: result.width ?? 0,
+    height: result.height ?? 0,
+  };
+}
+
+/**
+ * Fallback: line nodes up horizontally when ELK fails.
+ */
+function fallbackLayout(elkGraph) {
+  let x = 20;
+  const nodes = (elkGraph.children ?? []).map((c) => {
+    const node = {
+      id: c.id,
+      x,
+      y: 20,
+      width: c.width ?? 80,
+      height: c.height ?? 40,
+      label: c.labels?.[0]?.text ?? c.id,
+    };
+    x += (c.width ?? 80) + 40;
+    return node;
+  });
+
+  const edges = (elkGraph.edges ?? []).map((e) => ({
+    id: e.id,
+    source: e.sources?.[0] ?? '',
+    target: e.targets?.[0] ?? '',
+    label: e.labels?.[0]?.text,
+    sections: [],
+  }));
+
+  const totalWidth = x;
+  return { nodes, edges, width: totalWidth, height: 80 };
+}

package/src/visualization/layouts/index.js

@@ -0,0 +1,29 @@
+/**
+ * Layout engine facade.
+ *
+ * Orchestrates: converter → ELK adapter → ELK runner → PositionedGraph.
+ */
+
+export {
+  queryResultToGraphData,
+  pathResultToGraphData,
+  rawGraphToGraphData,
+} from './converters.js';
+
+export { toElkGraph, getDefaultLayoutOptions } from './elkAdapter.js';
+export { runLayout } from './elkLayout.js';
+
+import { toElkGraph } from './elkAdapter.js';
+import { runLayout } from './elkLayout.js';
+
+/**
+ * Full pipeline: graphData → PositionedGraph.
+ *
+ * @param {{ nodes: Array, edges: Array }} graphData - Normalised graph data
+ * @param {{ type?: string, layoutOptions?: Object }} [options]
+ * @returns {Promise<Object>} PositionedGraph
+ */
+export async function layoutGraph(graphData, options = {}) {
+  const elkGraph = toElkGraph(graphData, options);
+  return await runLayout(elkGraph);
+}

package/src/visualization/renderers/ascii/box.js

@@ -0,0 +1,16 @@
+import boxen from 'boxen';
+
+/**
+ * Wraps content in a bordered box using boxen.
+ *
+ * @param {string} content - The text content to display inside the box
+ * @param {Object} [options] - Options forwarded to boxen (e.g. title, borderColor)
+ * @returns {string} The boxed content string
+ */
+export function createBox(content, options = {}) {
+  return boxen(content, {
+    padding: 1,
+    borderStyle: 'double',
+    ...options,
+  });
+}