@git-stunts/git-warp 10.1.1

package/src/domain/warp/Writer.js

@@ -0,0 +1,181 @@
+/**
+ * Writer - WARP writer abstraction for safe graph mutations.
+ *
+ * A Writer is the only way to mutate a WarpGraph state. It owns a writerId
+ * and maintains a single-writer chain under refs/warp/<graph>/writers/<writerId>.
+ *
+ * Key guarantees:
+ * - Single-writer chain per writerId
+ * - Ref-safe identity
+ * - CAS-based updates to prevent concurrent forks
+ * - Schema:2 only (PatchV2 ops with OR-Set semantics)
+ *
+ * @module domain/warp/Writer
+ * @see WARP Writer Spec v1
+ */
+
+import defaultCodec from '../utils/defaultCodec.js';
+import { validateWriterId, buildWriterRef } from '../utils/RefLayout.js';
+import { PatchSession } from './PatchSession.js';
+import { PatchBuilderV2 } from '../services/PatchBuilderV2.js';
+import { decodePatchMessage, detectMessageKind } from '../services/WarpMessageCodec.js';
+import { vvClone } from '../crdt/VersionVector.js';
+import WriterError from '../errors/WriterError.js';
+
+// Re-export for backward compatibility — consumers importing from Writer.js
+// should migrate to importing from '../errors/WriterError.js' directly.
+export { WriterError };
+
+/**
+ * Writer class for creating and committing patches to a WARP graph.
+ *
+ * @class Writer
+ */
+export class Writer {
+  /**
+   * Creates a new Writer instance.
+   *
+   * @param {Object} options
+   * @param {import('../../ports/GraphPersistencePort.js').default} options.persistence - Git adapter
+   * @param {string} options.graphName - Graph namespace
+   * @param {string} options.writerId - This writer's ID
+   * @param {import('../crdt/VersionVector.js').VersionVector} options.versionVector - Current version vector
+   * @param {() => Promise<import('../services/JoinReducer.js').WarpStateV5>} options.getCurrentState - Async function returning the current materialized V5 state
+   * @param {(result: {patch: Object, sha: string}) => void | Promise<void>} [options.onCommitSuccess] - Callback invoked after successful commit with { patch, sha }
+   * @param {'reject'|'cascade'|'warn'} [options.onDeleteWithData='warn'] - Policy when deleting a node with attached data
+   * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for CBOR serialization (defaults to domain-local codec)
+   */
+  constructor({ persistence, graphName, writerId, versionVector, getCurrentState, onCommitSuccess, onDeleteWithData = 'warn', codec }) {
+    validateWriterId(writerId);
+
+    /** @type {import('../../ports/GraphPersistencePort.js').default} */
+    this._persistence = persistence;
+
+    /** @type {string} */
+    this._graphName = graphName;
+
+    /** @type {string} */
+    this._writerId = writerId;
+
+    /** @type {import('../crdt/VersionVector.js').VersionVector} */
+    this._versionVector = versionVector;
+
+    /** @type {Function} */
+    this._getCurrentState = getCurrentState;
+
+    /** @type {Function|undefined} */
+    this._onCommitSuccess = onCommitSuccess;
+
+    /** @type {'reject'|'cascade'|'warn'} */
+    this._onDeleteWithData = onDeleteWithData;
+
+    /** @type {import('../../ports/CodecPort.js').default|undefined} */
+    this._codec = codec || defaultCodec;
+  }
+
+  /**
+   * Gets the writer ID.
+   * @returns {string}
+   */
+  get writerId() {
+    return this._writerId;
+  }
+
+  /**
+   * Gets the graph name.
+   * @returns {string}
+   */
+  get graphName() {
+    return this._graphName;
+  }
+
+  /**
+   * Gets the current writer head SHA.
+   *
+   * @returns {Promise<string|null>} The tip SHA or null if no commits yet
+   */
+  async head() {
+    const writerRef = buildWriterRef(this._graphName, this._writerId);
+    return await this._persistence.readRef(writerRef);
+  }
+
+  /**
+   * Begins a new patch session.
+   *
+   * Reads the current writer head and captures it as the expected parent
+   * for CAS-based commit.
+   *
+   * @returns {Promise<PatchSession>} A fluent patch session
+   *
+   * @example
+   * const writer = await graph.writer();
+   * const patch = await writer.beginPatch();
+   * patch.addNode('user:alice');
+   * patch.setProperty('user:alice', 'name', 'Alice');
+   * await patch.commit();
+   */
+  async beginPatch() {
+    // Read current writer head and capture for CAS
+    const writerRef = buildWriterRef(this._graphName, this._writerId);
+    const expectedOldHead = await this._persistence.readRef(writerRef);
+
+    // Calculate next lamport
+    let lamport = 1;
+    if (expectedOldHead) {
+      const commitMessage = await this._persistence.showNode(expectedOldHead);
+      const kind = detectMessageKind(commitMessage);
+      if (kind === 'patch') {
+        try {
+          const patchInfo = decodePatchMessage(commitMessage);
+          lamport = patchInfo.lamport + 1;
+        } catch {
+          // Malformed message, start at 1
+        }
+      }
+    }
+
+    // Create internal PatchBuilderV2
+    const builder = new PatchBuilderV2({
+      persistence: this._persistence,
+      graphName: this._graphName,
+      writerId: this._writerId,
+      lamport,
+      versionVector: vvClone(this._versionVector),
+      getCurrentState: this._getCurrentState,
+      expectedParentSha: expectedOldHead,
+      onCommitSuccess: this._onCommitSuccess,
+      onDeleteWithData: this._onDeleteWithData,
+      codec: this._codec,
+    });
+
+    // Return PatchSession wrapping the builder
+    return new PatchSession({
+      builder,
+      persistence: this._persistence,
+      graphName: this._graphName,
+      writerId: this._writerId,
+      expectedOldHead,
+    });
+  }
+
+  /**
+   * Convenience method to build and commit a patch in one call.
+   *
+   * @param {(p: PatchSession) => void | Promise<void>} build - Function to build the patch
+   * @returns {Promise<string>} The commit SHA of the new patch
+   * @throws {WriterError} EMPTY_PATCH if no operations were added
+   * @throws {WriterError} WRITER_REF_ADVANCED if CAS fails (ref moved since beginPatch)
+   * @throws {WriterError} PERSIST_WRITE_FAILED if git operations fail
+   *
+   * @example
+   * const sha = await writer.commitPatch(p => {
+   *   p.addNode('user:alice');
+   *   p.setProperty('user:alice', 'name', 'Alice');
+   * });
+   */
+  async commitPatch(build) {
+    const patch = await this.beginPatch();
+    await build(patch);
+    return await patch.commit();
+  }
+}

package/src/hooks/post-merge.sh

@@ -0,0 +1,60 @@
+#!/bin/sh
+# --- @git-stunts/git-warp post-merge hook __WARP_HOOK_VERSION__ ---
+# warp-hook-version: __WARP_HOOK_VERSION__
+#
+# Post-merge hook: notify (or auto-materialize) when warp refs changed.
+#
+# Compares refs/warp/ before and after merge by maintaining
+# a snapshot file at .git/warp-ref-snapshot. If any warp writer refs
+# changed and warp.autoMaterialize is true, runs `git warp materialize`.
+# Otherwise prints an informational message advising re-materialization.
+# Always exits 0 — never blocks a merge.
+
+GIT_DIR=$(git rev-parse --git-dir 2>/dev/null) || exit 0
+SNAPSHOT="${GIT_DIR}/warp-ref-snapshot"
+
+# Capture current warp refs (sorted for stable comparison)
+CURRENT=$(git for-each-ref --format='%(refname) %(objectname)' --sort=refname refs/warp/ 2>/dev/null) || true
+
+if [ -z "$CURRENT" ]; then
+  # No warp refs exist — clean up any stale snapshot and exit
+  rm -f "$SNAPSHOT"
+  exit 0
+fi
+
+CHANGED=0
+
+if [ -f "$SNAPSHOT" ]; then
+  PREVIOUS=$(cat "$SNAPSHOT")
+  if [ "$CURRENT" != "$PREVIOUS" ]; then
+    CHANGED=1
+  fi
+else
+  # First encounter — refs exist but no snapshot yet
+  CHANGED=1
+fi
+
+# Save current state for next comparison
+printf '%s\n' "$CURRENT" > "$SNAPSHOT"
+
+if [ "$CHANGED" -eq 0 ]; then
+  exit 0
+fi
+
+AUTO_MAT=$(git config --bool warp.autoMaterialize 2>/dev/null) || true
+
+if [ "$AUTO_MAT" = "true" ]; then
+  echo "[warp] Refs changed — auto-materializing..."
+  if command -v git-warp >/dev/null 2>&1; then
+    git-warp materialize || echo "[warp] Warning: auto-materialize failed."
+  elif command -v warp-graph >/dev/null 2>&1; then
+    warp-graph materialize || echo "[warp] Warning: auto-materialize failed."
+  else
+    echo "[warp] Warning: neither git-warp nor warp-graph found in PATH."
+  fi
+else
+  echo "[warp] Writer refs changed during merge. Call materialize() to see updates."
+fi
+
+exit 0
+# --- end @git-stunts/git-warp ---

package/src/infrastructure/adapters/BunHttpAdapter.js

@@ -0,0 +1,225 @@
+import HttpServerPort from '../../ports/HttpServerPort.js';
+
+const ERROR_BODY = 'Internal Server Error';
+const ERROR_BODY_BYTES = new TextEncoder().encode(ERROR_BODY);
+const ERROR_BODY_LENGTH = String(ERROR_BODY_BYTES.byteLength);
+
+const PAYLOAD_TOO_LARGE = 'Payload Too Large';
+const PAYLOAD_TOO_LARGE_LENGTH = String(new TextEncoder().encode(PAYLOAD_TOO_LARGE).byteLength);
+
+/** Absolute streaming body limit (10 MB) — matches NodeHttpAdapter. */
+const MAX_BODY_BYTES = 10 * 1024 * 1024;
+
+/**
+ * Reads a ReadableStream body with a byte-count limit.
+ * Aborts immediately when the limit is exceeded, preventing full buffering.
+ *
+ * @param {ReadableStream} bodyStream
+ * @returns {Promise<Uint8Array|undefined>}
+ */
+async function readStreamBody(bodyStream) {
+  const reader = bodyStream.getReader();
+  const chunks = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    total += value.byteLength;
+    if (total > MAX_BODY_BYTES) {
+      await reader.cancel();
+      throw Object.assign(new Error('Payload Too Large'), { status: 413 });
+    }
+    chunks.push(value);
+  }
+  if (total === 0) {
+    return undefined;
+  }
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return body;
+}
+
+/**
+ * Converts a Bun Request into the plain-object format expected by
+ * HttpServerPort request handlers.
+ *
+ * @param {Request} request - Bun fetch Request
+ * @returns {Promise<{ method: string, url: string, headers: Object, body: Buffer|undefined }>}
+ */
+async function toPortRequest(request) {
+  const headers = {};
+  request.headers.forEach((value, key) => {
+    headers[key] = value;
+  });
+
+  let body;
+  if (request.method !== 'GET' && request.method !== 'HEAD') {
+    const cl = headers['content-length'];
+    if (cl !== undefined && Number(cl) > MAX_BODY_BYTES) {
+      throw Object.assign(new Error('Payload Too Large'), { status: 413 });
+    }
+    if (request.body) {
+      body = await readStreamBody(request.body);
+    }
+  }
+
+  const parsedUrl = new URL(request.url);
+  return {
+    method: request.method,
+    url: parsedUrl.pathname + parsedUrl.search,
+    headers,
+    body,
+  };
+}
+
+/**
+ * Converts a plain-object port response into a Bun Response.
+ *
+ * @param {{ status?: number, headers?: Object, body?: string|Uint8Array }} portResponse
+ * @returns {Response}
+ */
+function toResponse(portResponse) {
+  return new Response(portResponse.body ?? null, {
+    status: portResponse.status || 200,
+    headers: portResponse.headers || {},
+  });
+}
+
+/**
+ * Creates the Bun fetch handler that bridges between Request/Response
+ * and the HttpServerPort plain-object contract.
+ *
+ * @param {Function} requestHandler - Port-style async handler
+ * @param {{ error: Function }} logger
+ * @returns {(request: Request) => Promise<Response>}
+ */
+function createFetchHandler(requestHandler, logger) {
+  return async (request) => {
+    try {
+      const portReq = await toPortRequest(request);
+      const portRes = await requestHandler(portReq);
+      return toResponse(portRes);
+    } catch (err) {
+      if (err.status === 413) {
+        return new Response(PAYLOAD_TOO_LARGE, {
+          status: 413,
+          headers: { 'Content-Type': 'text/plain', 'Content-Length': PAYLOAD_TOO_LARGE_LENGTH },
+        });
+      }
+      logger.error('BunHttpAdapter dispatch error', err);
+      return new Response(ERROR_BODY, {
+        status: 500,
+        headers: {
+          'Content-Type': 'text/plain',
+          'Content-Length': ERROR_BODY_LENGTH,
+        },
+      });
+    }
+  };
+}
+
+/**
+ * Starts a Bun server and invokes the callback with (null) on success
+ * or (err) on failure.
+ *
+ * Note: Bun.serve() is synchronous, so cb fires on the same tick
+ * (unlike Node's server.listen which defers via the event loop).
+ *
+ * @param {{ port: number, hostname?: string, fetch: Function }} serveOptions
+ * @param {Function|undefined} cb - Node-style callback
+ * @returns {Object} The Bun server instance
+ */
+function startServer(serveOptions, cb) {
+  const server = globalThis.Bun.serve(serveOptions);
+  if (cb) {
+    cb(null);
+  }
+  return server;
+}
+
+/**
+ * Safely stops a Bun server, forwarding errors to the callback.
+ *
+ * @param {{ server: Object|null }} state - Shared mutable state
+ * @param {Function} [callback]
+ */
+function stopServer(state, callback) {
+  try {
+    if (state.server) {
+      state.server.stop();
+      state.server = null;
+    }
+    if (callback) {
+      callback();
+    }
+  } catch (err) {
+    if (callback) {
+      callback(err);
+    }
+  }
+}
+
+const noopLogger = { error() {} };
+
+/**
+ * Bun HTTP adapter implementing HttpServerPort.
+ *
+ * Uses `globalThis.Bun.serve()` so the module can be imported on any
+ * runtime (it will throw at call-time if Bun is not available).
+ *
+ * @extends HttpServerPort
+ */
+export default class BunHttpAdapter extends HttpServerPort {
+  /**
+   * @param {{ logger?: { error: Function } }} [options]
+   */
+  constructor({ logger } = {}) {
+    super();
+    this._logger = logger || noopLogger;
+  }
+
+  /** @inheritdoc */
+  createServer(requestHandler) {
+    const fetchHandler = createFetchHandler(requestHandler, this._logger);
+    const state = { server: null };
+
+    return {
+      listen(port, host, callback) {
+        const cb = typeof host === 'function' ? host : callback;
+        const bindHost = typeof host === 'string' ? host : undefined;
+        const serveOptions = { port, fetch: fetchHandler };
+
+        if (bindHost !== undefined) {
+          serveOptions.hostname = bindHost;
+        }
+
+        try {
+          state.server = startServer(serveOptions, cb);
+        } catch (err) {
+          if (cb) {
+            cb(err);
+          }
+        }
+      },
+
+      close: (callback) => stopServer(state, callback),
+
+      address() {
+        if (!state.server) {
+          return null;
+        }
+        return {
+          address: state.server.hostname,
+          port: state.server.port,
+          family: state.server.hostname.includes(':') ? 'IPv6' : 'IPv4',
+        };
+      },
+    };
+  }
+}

package/src/infrastructure/adapters/ClockAdapter.js

@@ -0,0 +1,57 @@
+import { performance as nodePerformance } from 'node:perf_hooks';
+import ClockPort from '../../ports/ClockPort.js';
+
+/**
+ * Unified clock adapter supporting both Node.js and global performance APIs.
+ *
+ * Accepts an optional `performanceImpl` in the constructor, defaulting to
+ * `globalThis.performance`. Use the static factory methods for common cases:
+ *
+ * - `ClockAdapter.node()` — Node.js `perf_hooks.performance`
+ * - `ClockAdapter.global()` — `globalThis.performance` (Bun/Deno/browsers)
+ *
+ * @extends ClockPort
+ */
+export default class ClockAdapter extends ClockPort {
+  /**
+   * @param {object} [options]
+   * @param {Performance} [options.performanceImpl] - Performance API implementation.
+   *   Defaults to `globalThis.performance`.
+   */
+  constructor({ performanceImpl } = {}) {
+    super();
+    this._performance = performanceImpl || globalThis.performance;
+  }
+
+  /**
+   * Creates a ClockAdapter using Node.js `perf_hooks.performance`.
+   * @returns {ClockAdapter}
+   */
+  static node() {
+    return new ClockAdapter({ performanceImpl: nodePerformance });
+  }
+
+  /**
+   * Creates a ClockAdapter using `globalThis.performance`.
+   * @returns {ClockAdapter}
+   */
+  static global() {
+    return new ClockAdapter({ performanceImpl: globalThis.performance });
+  }
+
+  /**
+   * Returns a high-resolution timestamp in milliseconds.
+   * @returns {number}
+   */
+  now() {
+    return this._performance.now();
+  }
+
+  /**
+   * Returns the current wall-clock time as an ISO string.
+   * @returns {string}
+   */
+  timestamp() {
+    return new Date().toISOString();
+  }
+}

package/src/infrastructure/adapters/ConsoleLogger.js

@@ -0,0 +1,150 @@
+/* eslint-disable no-console */
+import LoggerPort from '../../ports/LoggerPort.js';
+
+/**
+ * Log levels in order of severity.
+ * @readonly
+ * @enum {number}
+ */
+export const LogLevel = Object.freeze({
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  ERROR: 3,
+  SILENT: 4,
+});
+
+/**
+ * Map of level names to LogLevel values.
+ * @type {Record<string, number>}
+ */
+const LEVEL_NAMES = Object.freeze({
+  debug: LogLevel.DEBUG,
+  info: LogLevel.INFO,
+  warn: LogLevel.WARN,
+  error: LogLevel.ERROR,
+  silent: LogLevel.SILENT,
+});
+
+/**
+ * Console logger adapter with structured JSON output.
+ *
+ * Provides a production-ready implementation of LoggerPort that outputs
+ * structured JSON logs to the console. Supports log level filtering,
+ * timestamps, and child loggers with inherited context.
+ *
+ * @example
+ * const logger = new ConsoleLogger({ level: LogLevel.INFO });
+ * logger.info('Server started', { port: 3000 });
+ * // Output: {"timestamp":"...","level":"INFO","message":"Server started","port":3000}
+ *
+ * @example
+ * const childLogger = logger.child({ requestId: 'abc-123' });
+ * childLogger.info('Request received');
+ * // Output: {"timestamp":"...","level":"INFO","message":"Request received","requestId":"abc-123"}
+ */
+export default class ConsoleLogger extends LoggerPort {
+  /**
+   * Creates a new ConsoleLogger instance.
+   * @param {Object} [options] - Logger options
+   * @param {number} [options.level=LogLevel.INFO] - Minimum log level to output
+   * @param {Record<string, unknown>} [options.context={}] - Base context for all log entries
+   * @param {function(): string} [options.timestampFn] - Custom timestamp function (defaults to ISO string)
+   */
+  constructor({ level = LogLevel.INFO, context = {}, timestampFn } = {}) {
+    super();
+    this._level = typeof level === 'string' ? (LEVEL_NAMES[level] ?? LogLevel.INFO) : level;
+    this._context = Object.freeze({ ...context });
+    this._timestampFn = timestampFn || (() => new Date().toISOString());
+  }
+
+  /**
+   * Log a debug-level message.
+   * @param {string} message - The log message
+   * @param {Record<string, unknown>} [context] - Additional structured metadata
+   * @returns {void}
+   */
+  debug(message, context) {
+    this._log({ level: LogLevel.DEBUG, levelName: 'DEBUG', message, context });
+  }
+
+  /**
+   * Log an info-level message.
+   * @param {string} message - The log message
+   * @param {Record<string, unknown>} [context] - Additional structured metadata
+   * @returns {void}
+   */
+  info(message, context) {
+    this._log({ level: LogLevel.INFO, levelName: 'INFO', message, context });
+  }
+
+  /**
+   * Log a warning-level message.
+   * @param {string} message - The log message
+   * @param {Record<string, unknown>} [context] - Additional structured metadata
+   * @returns {void}
+   */
+  warn(message, context) {
+    this._log({ level: LogLevel.WARN, levelName: 'WARN', message, context });
+  }
+
+  /**
+   * Log an error-level message.
+   * @param {string} message - The log message
+   * @param {Record<string, unknown>} [context] - Additional structured metadata
+   * @returns {void}
+   */
+  error(message, context) {
+    this._log({ level: LogLevel.ERROR, levelName: 'ERROR', message, context });
+  }
+
+  /**
+   * Create a child logger with additional base context.
+   * Child loggers inherit parent context and merge with their own.
+   * @param {Record<string, unknown>} context - Additional base context for the child
+   * @returns {ConsoleLogger} A new logger instance with merged context
+   */
+  child(context) {
+    return new ConsoleLogger({
+      level: this._level,
+      context: { ...this._context, ...context },
+      timestampFn: this._timestampFn,
+    });
+  }
+
+  /**
+   * Internal logging implementation.
+   * @param {Object} opts - Log options
+   * @param {number} opts.level - Numeric log level
+   * @param {string} opts.levelName - String representation of level
+   * @param {string} opts.message - Log message
+   * @param {Record<string, unknown>} [opts.context] - Additional context
+   * @private
+   */
+  _log({ level, levelName, message, context }) {
+    if (level < this._level) {
+      return;
+    }
+
+    const entry = {
+      timestamp: this._timestampFn(),
+      level: levelName,
+      message,
+      ...this._context,
+      ...context,
+    };
+
+    const output = JSON.stringify(entry);
+
+    switch (level) {
+      case LogLevel.ERROR:
+        console.error(output);
+        break;
+      case LogLevel.WARN:
+        console.warn(output);
+        break;
+      default:
+        console.log(output);
+    }
+  }
+}