glassbrain 0.1.0 → 0.1.2

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.
package/README.md CHANGED
@@ -171,9 +171,10 @@ Each tool's own notion of "inside" becomes the structure; everything else become
171
171
  2. Point it at something you have: `npx glassbrain <file-or-folder>`.
172
172
  3. Ask your agent, no skill needed:
173
173
 
174
- > Map how our checkout flow works as glassbrain JSON (format: the first section of
175
- > github.com/voidixyn/glassbrain). Save a snapshot after each pass in kg/, run
176
- > `npx glassbrain validate kg` after each, then `npx glassbrain kg`.
174
+ > Map how our checkout flow works as a glassbrain graph (run `npx glassbrain` first).
175
+
176
+ `npx glassbrain` with no arguments prints the format and how to build in passes, so the
177
+ agent needs nothing else.
177
178
 
178
179
  Or give it the skills above and write your own: a skill is a short markdown file.
179
180
 
@@ -1271,33 +1271,75 @@ function diffText(s, labelOf, limit = 20) {
1271
1271
  }
1272
1272
 
1273
1273
  // cli/glassbrain.ts
1274
- var HELP = `glassbrain \u2014 open, diff and validate knowledge graphs
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
1275
1277
 
1276
- Usage
1277
- glassbrain <path> open a graph in the browser (same as: view)
1278
- glassbrain view <path> open it; a folder of versions gets a version bar
1279
- glassbrain diff <old> <new> what changed between two graphs
1280
- glassbrain diff <git-ref> <path> <path> at <git-ref> vs. the working tree
1281
- glassbrain diff <path> same, against HEAD
1282
- glassbrain validate <path> check files against the schema and the structure
1283
- glassbrain convert <path> [out-dir] write any supported format as glassbrain JSON
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.
1284
1281
 
1285
- <path> is a file, a folder, or <git-ref>:<path> (e.g. HEAD~1:graph.json).
1286
- Formats are detected from content: glassbrain {nodes, edges}, Graphify graph.json,
1287
- Understand-Anything knowledge-graph.json, MCP memory.jsonl, a markdown folder
1288
- (Obsidian / LLM wiki). A folder holding only sub-folders of JSON = versions.
1282
+ { "nodes": [
1283
+ { "id": "src", "label": "src", "kind": "folder" },
1284
+ { "id": "src/login.ts", "label": "login.ts", "kind": "file", "parent": "src",
1285
+ "description": "Checks the password, then opens a session. Markdown." },
1286
+ { "id": "src/db.ts", "label": "db.ts", "kind": "file", "parent": "src" } ],
1287
+ "edges": [
1288
+ { "source": "src/login.ts", "target": "src/db.ts", "kind": "uses" } ] }
1289
1289
 
1290
- Options
1291
- --out <file.html> write the page here instead of a temp file (view, diff)
1292
- --open / --no-open open the browser or not (diff opens only in a terminal)
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
+ Full schema: ${schema}
1298
+
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
1311
+
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")}
1317
+
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
1323
+ glassbrain convert <path> [out-dir] write any supported format as glassbrain JSON
1324
+
1325
+ <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).
1329
+
1330
+ OPTIONS
1293
1331
  --json machine-readable output (diff, validate)
1332
+ --strict exit 1 on warnings too (validate)
1333
+ --exit-code exit 1 when anything changed (diff)
1294
1334
  --all list every change, not the first 20 (diff)
1295
1335
  --ignore <a,b> fields that do not count as a change (diff)
1296
- --exit-code exit 1 when there are changes (diff)
1297
- --strict exit 1 on warnings too (validate)
1336
+ --out <file.html> write the page here instead of a temp file (view, diff)
1337
+ --open / --no-open open the browser or not (diff opens only in a terminal)
1298
1338
  --format <id> force a format: native, graphify, understand-anything, memory, obsidian
1299
1339
  -h, --help this help
1300
- -v, --version print the version
1340
+ -v, --version the version
1341
+
1342
+ More: https://github.com/voidixyn/glassbrain
1301
1343
  `;
1302
1344
  var VALUED = /* @__PURE__ */ new Set(["out", "format", "ignore"]);
1303
1345
  var SWITCHES = /* @__PURE__ */ new Set(["open", "json", "all", "exit-code", "strict", "help", "version"]);
@@ -1481,7 +1523,7 @@ if (a.flags.version) {
1481
1523
  const pkg = JSON.parse(fs2.readFileSync(path2.join(here, "../../package.json"), "utf8"));
1482
1524
  console.log(pkg.version);
1483
1525
  } else if (a.flags.help || a.cmd === "view" && !a.pos.length) {
1484
- process.stdout.write(HELP);
1526
+ process.stdout.write(HELP(path2.join(here, "../../schema/graph.schema.json")));
1485
1527
  } else {
1486
1528
  try {
1487
1529
  ({ view, diff: runDiff, validate: runValidate, convert: runConvert })[a.cmd](a);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "glassbrain",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Know what your agent knows: open, diff and review the knowledge graphs agents write. Plain JSON in, one html file out.",
5
5
  "keywords": [
6
6
  "knowledge-graph",