glassbrain 0.1.0 → 0.1.1

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,65 @@ 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
+ Work in passes, each one a new folder (copy the last, edit the copy). For example:
1301
+ kg/1-skeleton/graph.json every node, nested by parent, no descriptions
1302
+ kg/2-filled/graph.json descriptions added, no new structure
1303
+ kg/3-linked/graph.json edges added
1304
+ After each pass: glassbrain validate kg --strict fix everything it reports
1305
+ glassbrain diff kg/1-skeleton kg/2-filled only this pass's job?
1306
+ At the end: glassbrain kg opens all passes with a version bar
1307
+
1308
+ COMMANDS
1309
+ glassbrain <path> open in the browser (same as: view)
1310
+ glassbrain diff <old> <new> what changed between two graphs
1311
+ glassbrain diff <git-ref> <path> <path> at that commit vs. now (default ref: HEAD)
1312
+ glassbrain validate <path> check against the schema and the structure
1313
+ glassbrain convert <path> [out-dir] write any supported format as glassbrain JSON
1314
+
1315
+ <path> is a file, a folder, or <git-ref>:<path> (HEAD~1:kg/graph.json).
1316
+ A folder of sub-folders is a list of versions. Also opens, as they are:
1317
+ Graphify graph.json, Understand-Anything knowledge-graph.json, MCP memory.jsonl,
1318
+ a markdown folder (Obsidian / LLM wiki).
1319
+
1320
+ OPTIONS
1293
1321
  --json machine-readable output (diff, validate)
1322
+ --strict exit 1 on warnings too (validate)
1323
+ --exit-code exit 1 when anything changed (diff)
1294
1324
  --all list every change, not the first 20 (diff)
1295
1325
  --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)
1326
+ --out <file.html> write the page here instead of a temp file (view, diff)
1327
+ --open / --no-open open the browser or not (diff opens only in a terminal)
1298
1328
  --format <id> force a format: native, graphify, understand-anything, memory, obsidian
1299
1329
  -h, --help this help
1300
- -v, --version print the version
1330
+ -v, --version the version
1331
+
1332
+ More: https://github.com/voidixyn/glassbrain
1301
1333
  `;
1302
1334
  var VALUED = /* @__PURE__ */ new Set(["out", "format", "ignore"]);
1303
1335
  var SWITCHES = /* @__PURE__ */ new Set(["open", "json", "all", "exit-code", "strict", "help", "version"]);
@@ -1481,7 +1513,7 @@ if (a.flags.version) {
1481
1513
  const pkg = JSON.parse(fs2.readFileSync(path2.join(here, "../../package.json"), "utf8"));
1482
1514
  console.log(pkg.version);
1483
1515
  } else if (a.flags.help || a.cmd === "view" && !a.pos.length) {
1484
- process.stdout.write(HELP);
1516
+ process.stdout.write(HELP(path2.join(here, "../../schema/graph.schema.json")));
1485
1517
  } else {
1486
1518
  try {
1487
1519
  ({ 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.1",
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",