Merge pull request #595 from desci-labs/m0ar/history-debugger

toolshed: add history visualiser tool

.gitignore

@@ -13,8 +13,7 @@ database/
 ganache-data/
 ipfs-data/
 local-data/
-node-modules/
-node_modules/*
+**/node_modules
 .idea
 .composedbRuntimeDefinition.json
-openalex-importer
+openalex-importer

toolshed/README.md

@@ -0,0 +1,4 @@
+# The Toolshed 🔩
+Zero warranty scripts and misc that could prove useful in the future.
+
+These tools are not necessarily maintained or kept up-to-date.

toolshed/history-debugger/.gitignore

@@ -0,0 +1 @@
+outputs

toolshed/history-debugger/README.md

@@ -0,0 +1,23 @@
+# History Debugger
+Utility to compare token and stream histories, useful for investigating migrations and version ordering.
+
+## Setup
+Install dependencies:
+
+```bash
+npm ci
+```
+
+If you want the rendered SVG graph, you need to make sure `dot` is available in your `PATH`, which probably means installing `graphviz` with your package manager.
+
+## Use
+To debug a node, you need its (legacy) dPID, and it's streamID. With these at hand, run the script like so:
+
+```bash
+DPID=149 STREAM=kjzl6kcym7w8y6wtboiio6jmbpml97m04bji4zphyboqhsckz75qg48efglcjox npx tsx src/index.ts
+```
+
+This will generate three files in the `outputs` directory:
+- `149.md`: markdown table with metadata and version info
+- `149.dot`: raw dot graph for both histories
+- `149.svg`: rendered SVG from the dot graph