@git-stunts/git-warp 10.1.2 → 10.4.2

package/README.md

@@ -4,6 +4,10 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![npm version](https://badge.fury.io/js/%40git-stunts%2Fgit-warp.svg)](https://www.npmjs.com/package/@git-stunts/git-warp)
 
+<p align="center">
+  <img src="hero.gif" alt="git-warp CLI demo" width="600">
+</p>
+
 A multi-writer graph database that uses Git commits as its storage substrate. Graph state is stored as commits pointing to the empty tree (`4b825dc...`), making the data invisible to normal Git workflows while inheriting Git's content-addressing, cryptographic integrity, and distributed replication.
 
 Writers collaborate without coordination using CRDTs (OR-Set for nodes/edges, LWW registers for properties). Every writer maintains an independent patch chain; materialization deterministically merges all writers into a single consistent view.
@@ -403,12 +407,28 @@ git warp history --writer alice
 # Check graph health, status, and GC metrics
 git warp check
 
+# Time-travel: step through graph history
+git warp seek --tick 3                  # jump to Lamport tick 3
+git warp seek --tick=+1                 # step forward one tick
+git warp seek --tick=-1                 # step backward one tick
+git warp seek --save before-refactor    # bookmark current position
+git warp seek --load before-refactor    # restore bookmark
+git warp seek --latest                  # return to present
+git warp seek --clear-cache             # purge persistent seek cache
+git warp seek --no-persistent-cache --tick 5  # skip cache for one invocation
+
 # Visualize query results (ascii output by default)
 git warp query --match 'user:*' --outgoing manages --view
 ```
 
 All commands accept `--repo <path>` to target a specific Git repository, `--json` for machine-readable output, and `--view [mode]` for visual output (ascii by default, or browser, svg:FILE, html:FILE).
 
+When a seek cursor is active, `query`, `info`, `materialize`, and `history` automatically show state at the selected tick.
+
+<p align="center">
+  <img src="docs/seek-demo.gif" alt="git warp seek time-travel demo" width="600">
+</p>
+
 ## Architecture
 
 The codebase follows hexagonal architecture with ports and adapters:
@@ -421,15 +441,17 @@ The codebase follows hexagonal architecture with ports and adapters:
 - `CryptoPort` -- hash/HMAC operations
 - `LoggerPort` -- structured logging
 - `ClockPort` -- time measurement
+- `SeekCachePort` -- persistent seek materialization cache
 
 **Adapters** implement the ports:
 - `GitGraphAdapter` -- wraps `@git-stunts/plumbing` for Git operations
 - `ClockAdapter` -- unified clock (factory: `ClockAdapter.node()`, `ClockAdapter.global()`)
 - `NodeCryptoAdapter` -- cryptographic operations via `node:crypto`
-- `WebCryptoAdapter` -- cryptographic operations via Web Crypto API (browsers, Deno, Bun, Node 20+)
+- `WebCryptoAdapter` -- cryptographic operations via Web Crypto API (browsers, Deno, Bun, Node 22+)
 - `NodeHttpAdapter` / `BunHttpAdapter` / `DenoHttpAdapter` -- HTTP server per runtime
 - `ConsoleLogger` / `NoOpLogger` -- logging implementations
 - `CborCodec` -- CBOR serialization for patches
+- `CasSeekCacheAdapter` -- persistent seek cache via `@git-stunts/git-cas`
 
 **Domain** contains the core logic:
 - `WarpGraph` -- public API facade
@@ -459,10 +481,15 @@ The codebase follows hexagonal architecture with ports and adapters:
 ## Testing
 
 ```bash
-npm test                # unit tests (vitest)
+npm test                # unit tests (vitest, Docker)
+npm run test:local      # unit tests without Docker
 npm run lint            # eslint
-npm run test:bench      # benchmarks
-npm run test:bats       # CLI integration tests (Docker + BATS)
+
+# Multi-runtime test matrix (Docker)
+npm run test:node22     # Node 22: unit + integration + BATS CLI
+npm run test:bun        # Bun: API integration tests
+npm run test:deno       # Deno: API integration tests
+npm run test:matrix     # All runtimes in parallel
 ```
 
 ## AIΩN Foundations Series