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 +4 -3
- package/dist/cli/glassbrain.js +62 -20
- package/package.json +1 -1
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
|
|
175
|
-
|
|
176
|
-
|
|
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
|
|
package/dist/cli/glassbrain.js
CHANGED
|
@@ -1271,33 +1271,75 @@ function diffText(s, labelOf, limit = 20) {
|
|
|
1271
1271
|
}
|
|
1272
1272
|
|
|
1273
1273
|
// cli/glassbrain.ts
|
|
1274
|
-
var HELP = `glassbrain
|
|
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
|
-
|
|
1277
|
-
|
|
1278
|
-
|
|
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
|
-
|
|
1286
|
-
|
|
1287
|
-
|
|
1288
|
-
|
|
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
|
-
|
|
1291
|
-
|
|
1292
|
-
|
|
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
|
-
--
|
|
1297
|
-
--
|
|
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
|
|
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