ghcr-manager-visualizer 0.9.10 → 1.0.1

package/README.md

@@ -4,12 +4,37 @@ Local browser visualizer for `ghcr-manager` SQLite scan databases.
 
 Use it to inspect manifest graphs, compare two scans of the same package, and investigate cleanup edge cases.
 
+![Example compare view: red-bordered manifests are present in the older scan and removed in the newer one.](https://raw.githubusercontent.com/ghcr-manager/ghcr-manager/main/docs/images/visualizer/graph-2images-cosign--wide.png "Example compare view: red-bordered manifests are present in the older scan and removed in the newer one.")
+
+_Example compare view: red-bordered manifests are present in the older scan and removed in the newer one._
+
+## Quick Demo
+
+Download the test scenario DB from the latest release and try the visualizer without first running your own workflow.
+
+The DB contains dozens of scenario packages with different graphs and before/after views of cleanup operations on them.
+
+```sh
+curl -LO https://github.com/ghcr-manager/ghcr-manager/releases/latest/download/ghcr-manager-release-scenarios.sqlite
+npx ghcr-manager-visualizer --db ./ghcr-manager-release-scenarios.sqlite
+```
+
+Open the local URL printed by the command and select:
+
+- owner: `ghcr-manager-test`
+- package: select one with `2images` or `2multiarch` in the name
+- tag search: `image` or `multiarch`
+
+Good search terms for tags in most scenarios are: `image`, `multiarch`, `keep`, or `delete`.
+
 ## Install
 
 ```sh
 npm install --global ghcr-manager-visualizer
 ```
 
+> Requirement: Node.js `24` or newer.
+
 ## Run
 
 ```sh
@@ -29,13 +54,56 @@ Example:
 ghcr-manager-visualizer --db ./artifacts/acme__demo.sqlite --host 0.0.0.0 --port 4000
 ```
 
-## DB Inputs
+## DB Input
+
+The visualizer reads the SQLite DB produced by `ghcr-manager` as GitHub Action artifacts uploaded by `scan`, `cleanup`.
+
+Typical flow:
+
+1. Run a `scan` or `cleanup` workflow and download the SQLite DB run artifact.
+2. Start `ghcr-manager-visualizer` with that DB.
+3. Select owner and package, then enter a tag or digest to center the graph.
+4. Optionally select a second scan to compare two recorded scans.
+
+## Compare Mode
 
-The visualizer reads the SQLite DB format produced by:
+When a package has at least two completed scans, the visualizer defaults to comparing the newest two scans:
 
-- `ghcr-manager scan`
-- `ghcr-manager cleanup`
-- `ghcr-manager db-merge`
+- main scan: the older of the newest two scans
+- compare scan: the newest scan
+
+In compare mode, the visualizer shows delta information in two places.
+
+Manifest nodes:
+
+- gray border: present in both scans
+- green border: added in the newer scan
+- red border: removed in the newer scan
+
+Tags in the details panel:
+
+- plain tag text: present in both scans
+- `(+) tag-name`: tag added in the newer scan
+- `(-) tag-name`: tag removed in the newer scan
+
+This is the fastest way to inspect what changed between two scans of one package graph.
+
+[![Visualizer Show Compare Mode](https://raw.githubusercontent.com/ghcr-manager/ghcr-manager/main/docs/images/visualizer/visualizer-show-compare-mode.png)](https://github.com/ghcr-manager/ghcr-manager/blob/main/docs/images/visualizer/visualizer-show-compare-mode.png)
+
+## Source Checkout
+
+From this repository checkout, you can run the visualizer without publishing:
+
+```sh
+npm run visualize -- --db ./artifacts/acme__demo.sqlite
+```
+
+Or build and run the workspace directly:
+
+```sh
+npm run build:visualizer
+npm run visualizer:start -- --db ./artifacts/acme__demo.sqlite
+```
 
 ## Project
 

package/dist/public/app.js

@@ -336,13 +336,15 @@ function buildNodeLabel(node) {
   const secondaryLines = [];
 
   if (node.displayPlatform) {
-    secondaryLines.push(node.displayPlatform);
+    secondaryLines.push(`arch: ${node.displayPlatform}`);
   }
 
-  secondaryLines.push(node.tags.length > 0 ? buildTagDisplayText(node.tags[0]) : `#${node.versionId}`);
-
-  if (node.tags.length > 1) {
-    secondaryLines.push(node.tags.slice(1).map(buildTagDisplayText).join(" | "));
+  if (node.tags.length > 0) {
+    for (const tag of node.tags) {
+      secondaryLines.push(`tag: ${buildTagDisplayText(tag)}`);
+    }
+  } else {
+    secondaryLines.push(`version: ${node.versionId}`);
   }
 
   return [primaryLine, "", ...secondaryLines].join("\n");

package/dist/public/index.html

@@ -48,7 +48,7 @@
           </label>
           <label>
             Depth
-            <input id="depth" name="depth" type="number" min="0" max="30" value="5" required />
+            <input id="depth" name="depth" type="number" min="0" max="100" value="12" required />
           </label>
           <button type="submit">Load graph</button>
         </form>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ghcr-manager-visualizer",
-  "version": "0.9.10",
+  "version": "v1.0.1",
   "description": "Inspect ghcr-manager SQLite scan databases in a local browser graph visualizer.",
   "type": "module",
   "homepage": "https://github.com/ghcr-manager/ghcr-manager#readme",