glassbrain 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1271,14 +1271,21 @@ function diffText(s, labelOf, limit = 20) {
1271
1271
  }
1272
1272
 
1273
1273
  // cli/glassbrain.ts
1274
- var HELP = (schema) => `glassbrain: open, diff and validate knowledge graphs.
1275
- Your agent writes the graph as plain JSON; glassbrain shows it and what changed.
1276
- Not installed? Put npx in front: npx glassbrain kg
1274
+ var HELP = (schema) => `glassbrain: open, diff and validate knowledge graphs, written as plain JSON.
1277
1275
 
1278
- WRITE A GRAPH
1279
- One JSON file, two arrays. \`parent\` says what sits inside what; that is the
1280
- whole structure. Every other relation is an edge.
1276
+ [ STRUCTURE ]
1277
+ A folder is a graph; one folder per pass, the name sets the order.
1278
+ kg/
1279
+ \u251C\u2500\u2500 _profile.json shared by every pass ( see [ APPEARANCE ] )
1280
+ \u251C\u2500\u2500 1-skeleton/graph.json each folder holds a graph ( see [ DATA ] )
1281
+ \u251C\u2500\u2500 2-filled/graph.json
1282
+ \u2514\u2500\u2500 3-linked/graph.json
1281
1283
 
1284
+ Passes are optional. Use them for the step harness, diffs and version control.
1285
+ JSON at any depth merges by id; split by area only when a file gets too big to write.
1286
+
1287
+ [ DATA ]
1288
+ Two arrays, \`nodes\` and \`edges\`.
1282
1289
  { "nodes": [
1283
1290
  { "id": "src", "label": "src", "kind": "folder" },
1284
1291
  { "id": "src/login.ts", "label": "login.ts", "kind": "file", "parent": "src",
@@ -1287,47 +1294,51 @@ WRITE A GRAPH
1287
1294
  "edges": [
1288
1295
  { "source": "src/login.ts", "target": "src/db.ts", "kind": "uses" } ] }
1289
1296
 
1290
- id any string, stable across versions: a path or a slug, never a counter
1291
- label what is shown (defaults to id)
1292
- kind any word for what sort of thing it is (folder, page, feature, decision)
1293
- parent the id of the node it sits inside
1294
- description markdown for the detail panel; [text](node:<id>) links to a node
1295
- flags markers, e.g. ["stub"] for a node not filled in yet
1296
- Order in the arrays does not matter. Other fields are kept and shown in the detail panel.
1297
+ The parent structure helps readability. Start with a few meaningful groups and give every other node a parent.
1298
+ Keep kinds few and consistent; put supporting detail in descriptions.
1299
+
1300
+ FIELDS
1301
+ id stable across passes: a path or a slug, never a counter
1302
+ label what is shown (defaults to id)
1303
+ kind a word: folder, file, feature, decision
1304
+ parent id of the node this sits inside
1305
+ description markdown; [text](node:<id>) links to a node
1306
+ flags e.g. ["stub"] for a node not filled in yet
1307
+ layer which plane ( see [ APPEARANCE ] )
1308
+
1309
+ Any other field is kept and shown in the detail panel.
1310
+
1297
1311
  Full schema: ${schema}
1298
1312
 
1299
- BUILD IT IN PASSES
1300
- Each pass is a new folder: copy the last one, edit the copy.
1301
- kg/1-skeleton every node at the depth asked (or what a newcomer needs), read from
1302
- the source (not memory), nested by parent; flag each one "stub"
1303
- kg/2-filled descriptions (1-3 sentences, from the source), stub flags removed
1304
- kg/3-linked edges a reader would agree with
1305
- After each pass:
1306
- glassbrain validate kg --strict fix everything it reports
1307
- glassbrain diff kg/1-skeleton kg/2-filled only this pass's job: ~changed in 2,
1308
- edges added in 3, nothing else
1309
- At the end:
1310
- glassbrain kg opens all passes; give the user the path
1313
+ [ APPEARANCE ]
1314
+ kg/_profile.json, shared by every pass.
1315
+
1316
+ COLORS give each kind you use a color; the rest stay grey.
1317
+ { "nodePalette": { "file": "#6366f1", "function": "#10b981" },
1318
+ "edgePalette": { "calls": "#2563eb" }, "placeholderFlags": ["stub"] }
1319
+ "placeholderFlags" makes a flagged "stub" look unfinished.
1320
+
1321
+ LAYERS only for real planes: abstraction levels (contract vs implementation),
1322
+ never grouping. A node picks one with "layer", else the first; "z" orders them.
1323
+ { "layers": [ { "id": "api", "label": "API", "z": 0 },
1324
+ { "id": "ui", "label": "UI", "z": 1 } ] }
1325
+
1326
+ Full schema: ${schema.replace("graph.schema", "profile.schema")}
1311
1327
 
1312
- COLORS: kg/_profile.json, shared by every pass
1313
- Give each kind a color, or every node and edge is drawn the same grey:
1314
- { "nodePalette": { "file": "#6366f1", "function": "#10b981" },
1315
- "edgePalette": { "calls": "#2563eb" }, "placeholderFlags": ["stub"] }
1316
- Layers (2.5D), sizes, labels and the rest: ${schema.replace("graph.schema", "profile.schema")}
1328
+ [ COMMANDS ]
1329
+ Always: validate before handing over. Fix everything it reports.
1317
1330
 
1318
- COMMANDS
1319
- glassbrain <path> open in the browser (same as: view)
1320
- glassbrain diff <old> <new> what changed between two graphs
1321
- glassbrain diff <git-ref> <path> <path> at that commit vs. now (default ref: HEAD)
1322
- glassbrain validate <path> check against the schema and the structure
1331
+ glassbrain <path> open it (passes play as steps); prints the path to hand over
1332
+ glassbrain diff <old> <new> only what changed between two graphs
1333
+ glassbrain diff <git-ref> <path> in a git repo, the same graph at an earlier commit, where
1334
+ the history is the versions (default ref: HEAD)
1335
+ glassbrain validate <path> schema and structure
1323
1336
  glassbrain convert <path> [out-dir] write any supported format as glassbrain JSON
1324
1337
 
1325
1338
  <path> is a file, a folder, or <git-ref>:<path> (HEAD~1:kg/graph.json).
1326
- A folder of sub-folders is a list of versions. Also opens, as they are:
1327
- Graphify graph.json, Understand-Anything knowledge-graph.json, MCP memory.jsonl,
1328
- a markdown folder (Obsidian / LLM wiki).
1339
+ Also reads Graphify, Understand-Anything, memory.jsonl and markdown folders as-is.
1329
1340
 
1330
- OPTIONS
1341
+ [ OPTIONS ]
1331
1342
  --json machine-readable output (diff, validate)
1332
1343
  --strict exit 1 on warnings too (validate)
1333
1344
  --exit-code exit 1 when anything changed (diff)
@@ -1336,8 +1347,7 @@ OPTIONS
1336
1347
  --out <file.html> write the page here instead of a temp file (view, diff)
1337
1348
  --open / --no-open open the browser or not (diff opens only in a terminal)
1338
1349
  --format <id> force a format: native, graphify, understand-anything, memory, obsidian
1339
- -h, --help this help
1340
- -v, --version the version
1350
+ -h, --help / -v, --version this help / the version
1341
1351
 
1342
1352
  More: https://github.com/voidixyn/glassbrain
1343
1353
  `;