@intentius/behold 0.31.0 → 0.32.0
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/AGENTS.md +347 -1
- package/README.md +64 -10
- package/THIRD_PARTY.md +6 -5
- package/dist/cli.js +32432 -28180
- package/example-choudoufu-estate/chant.workspace.json +1 -1
- package/example-terraform-estate/README.md +2 -2
- package/example-terraform-estate/chant.workspace.json +1 -1
- package/example-three-cloud/chant.workspace.json +2 -2
- package/example-three-cloud/package-lock.json +24 -24
- package/example-three-cloud/package.json +5 -5
- package/package.json +20 -9
- package/schemas/graph/v1/graph.schema.json +140 -0
- package/web/app.js +9 -4
- package/web/boot-motion.js +6 -0
- package/web/cut-around.d.ts +30 -0
- package/web/cut-around.js +138 -0
- package/web/edge-weight.d.ts +8 -2
- package/web/edge-weight.js +34 -4
- package/web/edge-weight.test.js +36 -1
- package/web/index.html +8 -20
- package/web/neighbourhood.js +105 -0
- package/web/neighbourhood.test.js +131 -0
- package/web/outside-refs.js +515 -0
- package/web/outside-refs.test.js +249 -0
- package/web/theme-paint.js +14 -0
package/AGENTS.md
CHANGED
|
@@ -45,6 +45,16 @@ draws nothing. A declaration with `members: []` (terragucci writes one for its
|
|
|
45
45
|
gates) declares nothing to draw, so serve, export and doctor read the
|
|
46
46
|
directory as they would without one, and say so (#489). `.behold.json`'s `members` are ignored beside a declaration;
|
|
47
47
|
`behold doctor --fix` writes the declaration for an estate that has only them.
|
|
48
|
+
A `kustomize`, `argo-app`, `flux-kustomization`, `helm-chart` or `cloudformation`
|
|
49
|
+
member is read the same way (#1056), and the detail tier of a read is passed on
|
|
50
|
+
as `--detail` (chant 0.124.35, `WORKSPACE_DETAIL_CHANT_FLOOR`). The kinds come
|
|
51
|
+
from the k8s, helm and aws lexicons the workspace pins (chant 0.124.49,
|
|
52
|
+
`WORKSPACE_KINDS_CHANT_FLOOR`). At chant's default detail a k8s node carries only
|
|
53
|
+
`apiVersion` and `kind`; the Argo and Flux path edges of src/estate-edges.ts need
|
|
54
|
+
`spec`, which comes at detail 3. A lens, `up`, `down` and a namespace stay on the
|
|
55
|
+
member's own `chant graph`. A kustomize member needs `kustomize` or `kubectl` on
|
|
56
|
+
PATH and a helm-chart member needs `helm`. The fixture is
|
|
57
|
+
e2e/fixtures/k8s-workspace and the test src/k8s-member.test.ts.
|
|
48
58
|
Several directories on the command line (`behold serve a b c`) stay the loose
|
|
49
59
|
view behold composes itself.
|
|
50
60
|
|
|
@@ -67,6 +77,52 @@ a scheduled read: it holds a slot in the read budget, has the read deadline,
|
|
|
67
77
|
and stops when the request does. `serve --hud <url>` (or `BEHOLD_HUD_URL`)
|
|
68
78
|
links a proposed decision to its review in hud.
|
|
69
79
|
|
|
80
|
+
## A folder with no declaration, read by its kinds' probes (behold#1079)
|
|
81
|
+
|
|
82
|
+
`chant workspace graph <dir> --discover` (INTENTIUS/chant#5095) finds the members
|
|
83
|
+
of a directory that has no `chant.workspace.json`: the kinds' probes claim
|
|
84
|
+
directories, a directory a local `module` source calls or that sits inside
|
|
85
|
+
another member is not a member of its own, and two kinds claiming one directory
|
|
86
|
+
at the same precedence is a tie that is not read. The document is a contract 1
|
|
87
|
+
graph with one more field, `discovered[]`, one entry per claimed directory
|
|
88
|
+
(`dir`, `member`, `kind`, `source`, `probe`, `outcome`, `claims`, `note`).
|
|
89
|
+
Member names are the lowercased path with runs of characters a name cannot
|
|
90
|
+
hold turned to `-`, and `.` is `root`, so node ids and `member=` links in a
|
|
91
|
+
discovered folder carry those names, not the folder's name.
|
|
92
|
+
|
|
93
|
+
src/discover-read.ts reads it through `src/workspace-reader.ts`, one chant call
|
|
94
|
+
per folder, and `readGraph` (src/read-graph.ts, signature unchanged) turns the
|
|
95
|
+
document into the `Workspace` a declaration would give. Each member then takes
|
|
96
|
+
its part of that one document (`discoveredVia`), so the estate code composes a
|
|
97
|
+
discovered folder exactly as it composes a declared workspace, including an
|
|
98
|
+
unreadable member drawn as a box with chant's reason. The note names each tied
|
|
99
|
+
directory and counts the directories left out as modules or inside a member.
|
|
100
|
+
A list of one path is read as that folder, which is how the server hands it
|
|
101
|
+
over; `behold serve`, `behold shot` and the server treat a folder this applies
|
|
102
|
+
to as an estate (`discoverAppliesToList`). The overlay, search and the other
|
|
103
|
+
per-member reads still go to the folder as they did.
|
|
104
|
+
|
|
105
|
+
The floor is `WORKSPACE_DISCOVER_CHANT_FLOOR`, 0.124.98 (src/chant-floors.ts):
|
|
106
|
+
chant#5095 is on chant's main after the 0.124.97 freeze. Below it, or when the
|
|
107
|
+
chant's version is unknown, nothing here runs and a folder is read as before.
|
|
108
|
+
`CHANT_RELEASE` (src/chant-release.ts) is not moved by this: that is a
|
|
109
|
+
maintainer step once 0.124.98 is on npm.
|
|
110
|
+
|
|
111
|
+
Which folders go through it is a measured choice, not "all of them". On the
|
|
112
|
+
`infra/` tree of a Kubernetes project checkout (52 Terraform roots, 2
|
|
113
|
+
CloudFormation templates, 1 manifests directory), behold's own Terraform reader
|
|
114
|
+
takes 3.5 s cold and 72 ms on a reread, because one chant reads one generated
|
|
115
|
+
project naming every root. `--discover` runs a reader per member: 44 s cold,
|
|
116
|
+
6.8 s on chant's member cache, 55 members. So the default (`auto`) discovers a
|
|
117
|
+
folder behold cannot draw (no member kind claims it: Kubernetes, Helm) or draws
|
|
118
|
+
only half of (a Terraform or choudoufu folder that also holds Kubernetes or
|
|
119
|
+
Helm files), and leaves a Terraform or choudoufu folder with none on its own
|
|
120
|
+
reader. A chant project is never discovered. `BEHOLD_DISCOVER=always|never|auto`
|
|
121
|
+
overrides it. Because the Terraform scratch project (`behold-tf-*`) stays the
|
|
122
|
+
reader for those folders, and the plan read, choudoufu, behaviour and search
|
|
123
|
+
(`behold-tfws-*`) write it too, `writeTerraformScratchProject` and its tests
|
|
124
|
+
stay.
|
|
125
|
+
|
|
70
126
|
## Chant version floors (behold#691)
|
|
71
127
|
|
|
72
128
|
behold shells each project's own chant, so a read can reach a chant that
|
|
@@ -119,6 +175,44 @@ mask modules, the investigation templates come from
|
|
|
119
175
|
`runCloudIndex` statically. src/value-match.ts stays until the pulumi
|
|
120
176
|
lexicon has a `referenceCatalog` (chant#4535's note on behold#1005).
|
|
121
177
|
|
|
178
|
+
## chant's reference catalog (behold#1080)
|
|
179
|
+
|
|
180
|
+
A declared workspace read by a chant at `REFERENCE_CATALOG_CHANT_FLOOR`
|
|
181
|
+
(0.124.98, the release that carries INTENTIUS/chant#5097; 0.124.97 is on npm
|
|
182
|
+
today) gets one more read: `chant workspace graph <root>` for the whole
|
|
183
|
+
workspace, at the tier the members are read at (src/reference-catalog.ts,
|
|
184
|
+
cached under the workspace's source stamp). A read of one member cannot see a
|
|
185
|
+
reference into another, so the per-member reads' `dangling` entries that carry
|
|
186
|
+
a `rule` are replaced by this read's, and its derived edges, `dangling[]`,
|
|
187
|
+
`ambiguous[]` and `catalog.rules` go on the composed IR (`ir.catalog`). The
|
|
188
|
+
floor is checked first; below it nothing is sent and the estate is composed as
|
|
189
|
+
before. `readGraph` does this, after behold's own edge passes and before the
|
|
190
|
+
cluster anchor.
|
|
191
|
+
|
|
192
|
+
src/catalog-draw.ts draws it, after the stacking (`graphView` and the estate
|
|
193
|
+
branch of `/api/graph` call `drawCatalog`). A catalog edge is weighed "joined"
|
|
194
|
+
(web/edge-weight.js, `isCatalogEdge`), apart from "inferred", and the weight
|
|
195
|
+
and the rule are stamped on the SVG's edge (`data-edge-weight`,
|
|
196
|
+
`data-edge-rule`) with inline strokes, so a static export keeps them. A
|
|
197
|
+
dangling reference whose rule is not containment is a dashed placeholder card
|
|
198
|
+
(kind of the `targetKind`, lexicon `behold`, `attrs._placeholder` the value, one
|
|
199
|
+
per member, kind and value), and an ambiguous one is a dotted edge to each
|
|
200
|
+
candidate with `viaAttr` "one of N". The picture ends with the key; the answer's
|
|
201
|
+
`meta.catalogLegend` has the same rows for the page, which hides the in-SVG one
|
|
202
|
+
and draws its own. The graph document keeps `rule`, the one field: chant's rule
|
|
203
|
+
id on a joined edge, and the reference's rule on the placeholder and ambiguous
|
|
204
|
+
edges.
|
|
205
|
+
|
|
206
|
+
The cluster anchor (src/cluster-anchor.ts) reads the join: a member whose
|
|
207
|
+
Applications name a cluster Secret that chant joins to one cluster resource
|
|
208
|
+
anchors its objects to that cluster only; a Secret with no match, two matches,
|
|
209
|
+
or a member that reaches several clusters anchors nothing and puts the reason
|
|
210
|
+
in the note (`ir.anchorNotes`). A member without a cluster Secret keeps the
|
|
211
|
+
guess. The fixtures are `chant workspace graph --discover --json` recorded
|
|
212
|
+
from a chant checkout at the catalog and its rules (e2e/fixtures/
|
|
213
|
+
reference-catalog), the tests src/catalog-draw.test.ts and
|
|
214
|
+
src/catalog-route.test.ts.
|
|
215
|
+
|
|
122
216
|
## A pipeline's numbers, from Prometheus (behold#571)
|
|
123
217
|
|
|
124
218
|
`behold serve --prometheus <url>` (or `BEHOLD_PROMETHEUS_URL`) adds `GET
|
|
@@ -1412,10 +1506,209 @@ remote does not take the LFS object, it refuses with the setup line and exits
|
|
|
1412
1506
|
1 before the branch moves; the local PNG is kept. `behold mcp`, `GET
|
|
1413
1507
|
/api/shot` and a `--public` serve never publish.
|
|
1414
1508
|
|
|
1509
|
+
## The graph document: `behold-graph/1` (#1066)
|
|
1510
|
+
|
|
1511
|
+
A graph snapshot (`{ir, meta}`, what `/api/graph` answers and what every
|
|
1512
|
+
export snapshot holds) becomes a versioned document through
|
|
1513
|
+
`toDocument(snapshot, opts)` (`src/to-document.ts`). The types, the version
|
|
1514
|
+
string and `checkGraphDocument` are in `src/graph-document.ts`, which imports
|
|
1515
|
+
nothing, so a browser host can load it. The JSON Schema ships in the package
|
|
1516
|
+
at `schemas/graph/v1/graph.schema.json` and is published at
|
|
1517
|
+
https://intentius.io/behold/schemas/graph/v1/graph.schema.json (its `$id`,
|
|
1518
|
+
the same bytes from `docs/public/`; a test holds the two together).
|
|
1519
|
+
|
|
1520
|
+
```
|
|
1521
|
+
{schema: "behold-graph/1", generator: {behold, chant?}, origin: {dir, rev?},
|
|
1522
|
+
cut: {kind: "whole" | "around" | "changed", ...}, nodes[], edges[], groups[],
|
|
1523
|
+
notes[], layout?}
|
|
1524
|
+
node: {id, title, subtitle, kind, lexicon, box?, file?, line?, change?,
|
|
1525
|
+
status?, color?, mainstat?, secondarystat?, stackOf?, detail__member?,
|
|
1526
|
+
detail__root?, detail__namespace?, detail__release?, attrs}
|
|
1527
|
+
edge: {id, source, target, kind, inferred, rule?, via?}
|
|
1528
|
+
group: {id: "<kind>:<key>", title, kind: stack | wave | pipeline | container, parent?}
|
|
1529
|
+
note: {kind, text, short?, box?, count?}
|
|
1530
|
+
```
|
|
1531
|
+
|
|
1532
|
+
The node and edge field names are the ones Grafana's node graph panel takes,
|
|
1533
|
+
so the panel reads `nodes` and `edges` with no transform. `subtitle` is the
|
|
1534
|
+
tool (`k8s` reads `kubernetes`), `status` is `attrs._status`, `color` its
|
|
1535
|
+
pinhole bar colour, `mainstat` the drift record's words or the plan's action,
|
|
1536
|
+
`change` the plan's action unless it is `no-op` or `read`. `file` is relative
|
|
1537
|
+
to the repository root, and absent when behold cannot place it there; an
|
|
1538
|
+
absolute `sourceLoc` is dropped. An edge whose end the view does not draw is
|
|
1539
|
+
left out and counted in `notes` (`edges-left-out`), so every `source` and
|
|
1540
|
+
`target` names a node. Edge ids are `<source>-><target>:<kind>[:<via>]`, with
|
|
1541
|
+
`#2`, `#3` on repeats. `rule` names the join behind an inferred edge: chant's
|
|
1542
|
+
catalog rule (`origin: "derived"`), or `behold:<join>` from the `join` field
|
|
1543
|
+
each behold pass now sets beside `inferred: true` (`value-match`,
|
|
1544
|
+
`k8s-declared`, `estate-member`, `cluster-anchor`, `composite-deps`,
|
|
1545
|
+
`choudoufu-lexicon`, `choudoufu-estate`). `attrs.source` is left out unless
|
|
1546
|
+
`opts.source` asks for it.
|
|
1547
|
+
|
|
1548
|
+
`documentOptions({projectDir, projectDirs?, workspace?, behold, rev?})`
|
|
1549
|
+
(`src/graph-document-context.ts`) works out what the IR does not carry: the
|
|
1550
|
+
served directory relative to its repository (the nearest `.git` above it),
|
|
1551
|
+
each member's directory and Terraform roots, and a scrubber that rewrites this
|
|
1552
|
+
machine's paths to repository-relative ones, the home directory to `~` and
|
|
1553
|
+
the temporary directory to `$TMPDIR`. The same snapshot and options give
|
|
1554
|
+
byte-identical JSON. Within `behold-graph/1` fields are only added and a
|
|
1555
|
+
reader ignores what it does not know; `checkGraphDocument` refuses any other
|
|
1556
|
+
`behold-graph/<n>` by name.
|
|
1557
|
+
|
|
1558
|
+
## The graph from the command line: `behold graph` (#1058)
|
|
1559
|
+
|
|
1560
|
+
`behold graph [dir] [--json | --ir] [-o <file>] [--detail 0..3] [--source]
|
|
1561
|
+
[--every-card]` reads a directory and prints it, with no server, no browser
|
|
1562
|
+
and no write but the `-o` file (src/graph-cli.ts). `--json`, the default, is
|
|
1563
|
+
the `behold-graph/1` document; `--ir` is the unversioned `{ir, meta}` that
|
|
1564
|
+
`/api/graph` answers, without its SVG. `--mermaid [--forge gitlab|github|forgejo]`
|
|
1565
|
+
is a flowchart that fits that forge's character budget (below); `--svg` is
|
|
1566
|
+
reserved for its painter (#1061) and exits 2 until it applies. Exit 1 is a
|
|
1567
|
+
directory chant would not read (its refusal and remedy on stderr), exit 2 a
|
|
1568
|
+
usage error. No output holds an absolute path: both go through
|
|
1569
|
+
`documentOptions`' scrubber, and `attrs.source` is left out without
|
|
1570
|
+
`--source`.
|
|
1571
|
+
|
|
1572
|
+
The Mermaid writer (#1060) is `toMermaid(doc, { forge })` in
|
|
1573
|
+
src/graph-mermaid.ts, over a `behold-graph/1` document, so a cut applies first.
|
|
1574
|
+
Ids are `n<index>` and `g<index>` over the sorted ids, one label line per card,
|
|
1575
|
+
boxes as subgraphs, inferred edges dotted, labels quoted and escaped with
|
|
1576
|
+
Mermaid entity codes. A document with a plan's `change` or a cut's `seed` gets
|
|
1577
|
+
four `classDef` lines: added (`create`), changed (`update`, `replace`), removed
|
|
1578
|
+
(`delete`) and neighbour (a card in the cut that is neither a seed nor changed).
|
|
1579
|
+
Over the budget it drops neighbours first, then whole boxes (those with the
|
|
1580
|
+
fewest changed cards first), and ends with a `N cards not shown` card; it never
|
|
1581
|
+
returns text over the budget. The budgets are one table, `FORGE_BUDGETS` in
|
|
1582
|
+
src/mermaid-budgets.ts: gitlab 2,000 characters, github and forgejo 20,000 and
|
|
1583
|
+
250 edges, a whole comment under 60,000. Each row has `confirmed: false` until
|
|
1584
|
+
the live check (e2e/forge-limits, #1065) records the forge's real figures; that
|
|
1585
|
+
check's result is an edit to the row. `forgeComment` builds the comment body
|
|
1586
|
+
(marker, count line, fenced diagram) and posts the per-root table from
|
|
1587
|
+
`rootTable` instead when the diagram had to leave cards out or the comment
|
|
1588
|
+
would reach its limit; the action (#1062) and the MCP text fallback (#1073)
|
|
1589
|
+
use these.
|
|
1590
|
+
|
|
1591
|
+
The read is `graphView(dir, opts)` (src/graph-view.ts): `readGraph`, then the
|
|
1592
|
+
lenses `/api/graph` runs over an estate's source picture: the plan when
|
|
1593
|
+
`terraformPlan` is passed (the server's setting, as an argument), collapse,
|
|
1594
|
+
stacking alike cards (`--every-card` turns it off), and the note, joined by
|
|
1595
|
+
`viewNote`. The route calls `shapeEstate` and `viewNote` from the same module,
|
|
1596
|
+
and src/graph-view.test.ts holds the view equal to the route's answer. The
|
|
1597
|
+
logical and components lenses, the traffic prediction (it reads per-user
|
|
1598
|
+
settings) and the SVG stay in the route. An output format is one entry in
|
|
1599
|
+
`GRAPH_FORMATS` (src/graph-formats.ts); a cut is a function over the document
|
|
1600
|
+
that the CLI hands a format as `cut`.
|
|
1601
|
+
|
|
1602
|
+
### A bare cluster: `behold graph --context <name>` (#1083)
|
|
1603
|
+
|
|
1604
|
+
`behold graph --context <name> [--kubeconfig <file>] [--namespace a,b]
|
|
1605
|
+
[--types t,u] [--allow-exec-plugin]` draws the cluster a kubeconfig context
|
|
1606
|
+
points at, with no chant project and no directory (src/read-cluster.ts).
|
|
1607
|
+
`--kubeconfig` alone reads that file's current context; without it the file is
|
|
1608
|
+
the first path in `KUBECONFIG`, then `~/.kube/config`. There is no reader of
|
|
1609
|
+
behold's own. `readCluster` calls chant's `indexCloud` (the cloud lister
|
|
1610
|
+
`behold index kubernetes` runs: API discovery, then a paged LIST per kind, read
|
|
1611
|
+
allowlist only) with the `none` store, so no index version and no file is
|
|
1612
|
+
written, and hands the result to `readComposed` (src/read-graph.ts), the passes
|
|
1613
|
+
`readGraph` runs over a directory's estate. `readGraph` still reads no
|
|
1614
|
+
kubeconfig. Cards are boxed by namespace (cluster-scoped objects in `cluster`)
|
|
1615
|
+
and take the ids `<namespace>/<Kind>/<name>`; an edge to an object the read did
|
|
1616
|
+
not list is dropped and counted in the note. What the objects name outside the
|
|
1617
|
+
cluster (web/outside-refs.js, #1082) is added as cards in a box called Outside
|
|
1618
|
+
the cluster. `behold serve` does not take a context yet.
|
|
1619
|
+
|
|
1620
|
+
Credentials: a token, a token file or a client certificate. A user that
|
|
1621
|
+
authenticates through an exec plugin (the GKE, EKS and AKS tools write these)
|
|
1622
|
+
is refused with exit 2, naming the context, before chant is loaded and before
|
|
1623
|
+
any request. `--allow-exec-plugin` runs the plugin once (src/kube-exec.ts, the
|
|
1624
|
+
ExecCredential protocol, no terminal) and reads with the credential it prints.
|
|
1625
|
+
An `auth-provider` user is always refused. Whether the switch should be on by
|
|
1626
|
+
default is the maintainer's ruling and is open.
|
|
1627
|
+
|
|
1628
|
+
The live read masks every key matching /secret/i, which chant's typing then
|
|
1629
|
+
shows as `[REDACTED]`. On chant 0.124.58 an ExternalSecret's
|
|
1630
|
+
`spec.secretStoreRef` is masked whole, so its store and provider draw no card
|
|
1631
|
+
and the note says so (chant#5116 keeps such reference fields readable). An Argo
|
|
1632
|
+
CD cluster Secret's name and server are masked too, and chant#5116 decides
|
|
1633
|
+
whether they show. behold draws what the lister returns under either answer.
|
|
1634
|
+
`BEHOLD_K3D_TESTS=1 npx vitest run src/read-cluster-live.test.ts` runs the
|
|
1635
|
+
live test on a k3d cluster named `behold-read-cluster-<pid>`, deleted afterward
|
|
1636
|
+
unless `BEHOLD_K3D_KEEP=1`; `BEHOLD_EXPECT_5116=1` makes its reference test
|
|
1637
|
+
fail instead of skip.
|
|
1638
|
+
|
|
1639
|
+
The same command is the `behold-graph` bin of `@intentius/behold-graph`,
|
|
1640
|
+
built from this repo into packages/graph by `npm run build:graph` (part of
|
|
1641
|
+
`npm run build`). Its entry is src/graph-package.ts, which exports `readGraph`,
|
|
1642
|
+
`graphView`, the formats, `toDocument` and the document types. Its
|
|
1643
|
+
dependencies are packages/graph/budget.json's allowlist, at behold's own
|
|
1644
|
+
ranges and version (a test holds both). `npm run check:graph-package` (CI runs
|
|
1645
|
+
it after the build) packs it, installs the tarball into an empty directory,
|
|
1646
|
+
prints the installed size, and fails above the budget, on a dependency not on
|
|
1647
|
+
the allowlist, or when `npm ls --all` names hono, `@hono/node-server`, the MCP
|
|
1648
|
+
SDK or the Kubernetes client. The first measurement was 127 MB and 55
|
|
1649
|
+
packages, against 238 MB and 162 for behold; the budget is 140 MB and 60.
|
|
1650
|
+
Most of it is chant itself (73 MB) and the TypeScript compiler chant loads
|
|
1651
|
+
configs with (23 MB). Publishing the package is the maintainer's step.
|
|
1652
|
+
|
|
1653
|
+
## The single-file viewer (#1070)
|
|
1654
|
+
|
|
1655
|
+
`npm run build:viewer` (scripts/build-viewer.mts) writes
|
|
1656
|
+
`dist/behold-viewer/`: `index.html` (no inline script), `viewer.js` (a
|
|
1657
|
+
classic script), `viewer.mjs` (the same as an ES module), `viewer.css`, a
|
|
1658
|
+
stand-in `graph.js`, and `viewer.html` with the script and the styles
|
|
1659
|
+
inlined, for an MCP resource or an unzipped artifact. It draws a
|
|
1660
|
+
`behold-graph/1` document with the painter `/api/graph` uses: the document is
|
|
1661
|
+
turned back into the IR (src/viewer/document-ir.ts, a card's box walked up to
|
|
1662
|
+
its stack, pipeline, wave and container) and painted by `paintDocument`
|
|
1663
|
+
(src/viewer/paint.ts), with the same box badges. The source is src/viewer/.
|
|
1664
|
+
|
|
1665
|
+
The document comes, in this order, from a `behold:graph {document, icons?}`
|
|
1666
|
+
message, from `window.__BEHOLD_GRAPH__` (graph.js, the only form that works
|
|
1667
|
+
from `file://`), or from `?src=<same-origin path>`. Options come from the
|
|
1668
|
+
query string and from `window.__BEHOLD_VIEWER__`, the query winning:
|
|
1669
|
+
`theme` (light, dark, blueprint, aws; absent, `prefers-color-scheme`),
|
|
1670
|
+
`node`, `focus` (box keys or ids), `host` (the parent's origin), `transport`
|
|
1671
|
+
(post, vscode, mcp, none) and `src`. In: `behold:theme {theme?, vars?}` (CSS
|
|
1672
|
+
custom properties only) and `behold:view {node?, focus?}`. Out:
|
|
1673
|
+
`behold:ready`, then `behold:select {id, kind, file}` per pick.
|
|
1674
|
+
src/viewer/transport.ts has the three hosts: a parent page (`postMessage` to
|
|
1675
|
+
`host` only, and only its messages read), a VS Code webview
|
|
1676
|
+
(`acquireVsCodeApi`, called once), and an MCP Apps view (JSON-RPC:
|
|
1677
|
+
`ui/initialize`, the document from `ui/notifications/tool-result`'s
|
|
1678
|
+
`structuredContent`, the theme from the host context, a pick sent as
|
|
1679
|
+
`ui/update-model-context`). With no `transport`, a page with
|
|
1680
|
+
`acquireVsCodeApi` is VS Code, one with `host` is a parent page, and a
|
|
1681
|
+
framed page with neither is MCP Apps.
|
|
1682
|
+
|
|
1683
|
+
The layout runs in a Web Worker: the script starts itself as the worker,
|
|
1684
|
+
from its own URL or, inlined, from its own text, and paints on the page when
|
|
1685
|
+
no worker starts (index.html opened from `file://`). A document with no
|
|
1686
|
+
boxes above `FLAT_LIMIT` cards is refused with the reason, since one flat
|
|
1687
|
+
layout grows far faster than the card count. The page sets
|
|
1688
|
+
`data-behold-viewer` on `<html>` (`waiting`, `drawing`, `drawn`, `refused`)
|
|
1689
|
+
and `window.__BEHOLD_VIEWER_STATE__` (cards, where it laid out, time to first
|
|
1690
|
+
paint).
|
|
1691
|
+
|
|
1692
|
+
The vendored icon table is left out of the build: it is 544 KB of the 684 KB
|
|
1693
|
+
painter. A host hands over the icons its document uses, as
|
|
1694
|
+
`window.__BEHOLD_ICONS__` or the message's `icons`; `graphScript(doc)`
|
|
1695
|
+
(src/viewer/graph-script.ts) writes a graph.js with both, and
|
|
1696
|
+
`documentIcons(doc)` finds the icons by painting the document once with the
|
|
1697
|
+
full table (`recordIcons` in src/icon-packs.ts). Once a host supplies icons,
|
|
1698
|
+
an icon it did not supply falls through to pinhole's keyword glyph
|
|
1699
|
+
(`supplyIcons`). The build fails above 300 KB minified or 100 KB gzipped for
|
|
1700
|
+
`viewer.js` or `viewer.mjs`, above 1 MB for the directory, on any Node
|
|
1701
|
+
built-in in the bundle, and when `viewer.js` names `EventSource` or
|
|
1702
|
+
`WebSocket`. On pinhole 0.5.0 it fails on the four `node:` imports in
|
|
1703
|
+
pinhole's root (#1069), which pinhole 0.6.0 removes.
|
|
1704
|
+
src/viewer/viewer-browser.test.ts opens it in headless Chrome from `file://`
|
|
1705
|
+
and under `default-src 'none'; script-src 'self'; style-src 'self'
|
|
1706
|
+
'unsafe-inline'`, and skips while pinhole is 0.5.0.
|
|
1707
|
+
|
|
1415
1708
|
## Over MCP: `behold mcp` (#916)
|
|
1416
1709
|
|
|
1417
1710
|
`behold mcp [project-dir] [--url <serve> | --port <n>]` is a stdio MCP server
|
|
1418
|
-
with
|
|
1711
|
+
with five tools for an agent (and a sixth for a view), most of them clients of a running serve's HTTP API; `graph` (#1073, below) reads the directory itself. An agent reads
|
|
1419
1712
|
`capabilities` first (#926): it calls `GET /api/capabilities` and returns
|
|
1420
1713
|
chant's capability catalog, the read contract's `capabilities` document
|
|
1421
1714
|
(`chant search --capabilities --json`, INTENTIUS/chant#4375), byte for byte.
|
|
@@ -1433,6 +1726,24 @@ followed by a text block `{link, state, serve}`. They take `query`, `env`,
|
|
|
1433
1726
|
and `height`. The answers are chant's: behold passes chant's documents
|
|
1434
1727
|
through and computes none of its own.
|
|
1435
1728
|
|
|
1729
|
+
`graph` (#1073) draws the repository, or a cut of it, and takes `dir` (a folder
|
|
1730
|
+
inside the project), `around` (comma-separated card or box ids, or a box title
|
|
1731
|
+
or Terraform root as the roots table prints it), `changed` (`<base>..<head>`),
|
|
1732
|
+
`depth` and `direction`. It reads in this process with the calls `behold graph`
|
|
1733
|
+
makes (`src/mcp-graph.ts`) and answers in text for every host: the counts, the
|
|
1734
|
+
cut, a Mermaid block when it fits (`MCP_MERMAID_BUDGET`, nine thousand
|
|
1735
|
+
characters) or a table of roots when it does not, and a link to the running
|
|
1736
|
+
serve at the card or box asked for, else the line that starts one. The whole
|
|
1737
|
+
text stays under `TEXT_CHARS` (18,000), well under Claude Code's 10,000-token
|
|
1738
|
+
warning, and holds no document JSON. `_meta.ui.resourceUri` names
|
|
1739
|
+
`ui://behold/viewer` (MIME type `text/html;profile=mcp-app`, MCP Apps spec
|
|
1740
|
+
2026-01-26), which `resources/read` serves from `src/viewer-resource.ts`:
|
|
1741
|
+
`dist/behold-viewer/viewer.html` (#1070's `npm run build:viewer`) when it is in
|
|
1742
|
+
the package, else a page saying the view is not in this build. The view gets
|
|
1743
|
+
its document from `graph_document`, a tool with `_meta.ui.visibility: ["app"]`
|
|
1744
|
+
that takes `graph`'s arguments (`structuredContent.view` of a `graph` result
|
|
1745
|
+
is exactly those), so the cards never enter the model's context.
|
|
1746
|
+
|
|
1436
1747
|
It finds the serve through `--url`/`--port`, then the per-user registry at
|
|
1437
1748
|
`<os.tmpdir()>/behold/serves/<pid>.json` (`{url, pid, projectDir, version,
|
|
1438
1749
|
startedAt}`, written by every serve at start, rewritten on a project switch,
|
|
@@ -2201,6 +2512,16 @@ live here, with the enforceable ones enforced.
|
|
|
2201
2512
|
from the environment and run under `e2e/lib/safe-env.sh`, which keeps real
|
|
2202
2513
|
cloud credentials out of reach and fails on a real-cloud rejection in the
|
|
2203
2514
|
log; e2e/README.md has the variables (behold#1032).
|
|
2515
|
+
- The painter bundles for a browser (#1069). `src/render.ts` and what it
|
|
2516
|
+
imports take no Node built-in: `npm run check:browser-bundle` bundles it
|
|
2517
|
+
with esbuild for `--platform=browser`, fails naming the import chain to any
|
|
2518
|
+
`node:` import, and prints the minified and gzipped sizes; CI runs it. A
|
|
2519
|
+
constant or card rule the painter needs from a module that reads disk or
|
|
2520
|
+
spawns lives in a module of its own (src/card-marks.ts,
|
|
2521
|
+
src/choudoufu-card.ts, src/carve-state.ts) and is re-exported from the old
|
|
2522
|
+
one. The icons come from src/icons.generated.ts: after a vendor script
|
|
2523
|
+
changes `web/icons`, run `npm run generate:icons` (`npm run check:icons`
|
|
2524
|
+
and src/generate-icons.test.ts fail until you do).
|
|
2204
2525
|
- **The local gate** is `just check` (tsc, tests, build). The tests never read
|
|
2205
2526
|
the caller's environment (behold#1013): src/test-env.ts, vitest's setup
|
|
2206
2527
|
file, removes CHOUDOUFU_BIN, PLUNGE_BIN and the other variables behold
|
|
@@ -2807,3 +3128,28 @@ strip either way: the DNS fan is 19564 x 400 upright and 900 x 10046 on its
|
|
|
2807
3128
|
side. A box under 4:1 is left exactly as it laid out. Measured: `terralith-4`
|
|
2808
3129
|
7660 x 5162 with 266 edges, waterpark 3536 x 3138 at detail 2 and 7142 x 6974
|
|
2809
3130
|
at detail 3 (from 4.2:1 and 15.1:1, the case #393's wrap did not answer).
|
|
3131
|
+
|
|
3132
|
+
## What live objects name outside the cluster (behold#1082)
|
|
3133
|
+
|
|
3134
|
+
`outsideRefs(objects, { graph })` in web/outside-refs.js is a pure function
|
|
3135
|
+
with no imports, so a browser bundle takes it whole. It turns Kubernetes
|
|
3136
|
+
objects as the API serves them into `{ cards, edges, notes }`: a cloud identity
|
|
3137
|
+
card for a ServiceAccount's `iam.gke.io/gcp-service-account`,
|
|
3138
|
+
`eks.amazonaws.com/role-arn` or `azure.workload.identity/client-id`
|
|
3139
|
+
annotation, a store card and a provider card (GCP Secret Manager, AWS Secrets
|
|
3140
|
+
Manager or Parameter Store, Vault, with the `remoteRef.key` values) for an
|
|
3141
|
+
ExternalSecret, and a source card for an Argo CD Application's `spec.source`
|
|
3142
|
+
and `spec.sources[]` or a Flux Kustomization's `sourceRef` and `path`. It reads
|
|
3143
|
+
the field paths chant#5098 and chant#5099 read, so a placeholder and a derived
|
|
3144
|
+
edge agree. A card's id is made from what it names, so two objects naming one
|
|
3145
|
+
thing share it, and a target the `graph` already holds gets no card and no
|
|
3146
|
+
edge. A field it cannot read goes in `notes`, never dropped.
|
|
3147
|
+
|
|
3148
|
+
Chant's live Kubernetes read masks every key matching /secret/i. An
|
|
3149
|
+
ExternalSecret's whole `spec.secretStoreRef` comes back as `<masked>`, so on a
|
|
3150
|
+
live read that ExternalSecret has no store card and its keys stay off the
|
|
3151
|
+
provider card; its note carries `waitsOn: "INTENTIUS/chant#5116"`. The
|
|
3152
|
+
ServiceAccount, provider and source cards work on a live read today.
|
|
3153
|
+
src/outside-refs-live.test.ts reads a scratch k3d cluster through chant's
|
|
3154
|
+
lister to show it (BEHOLD_K3D_TESTS=1; the cluster is `behold-outside-refs-<pid>`,
|
|
3155
|
+
created and deleted by the test). Fixtures are in web/outside-refs.test.js.
|
package/README.md
CHANGED
|
@@ -1,7 +1,20 @@
|
|
|
1
1
|
# behold
|
|
2
2
|
|
|
3
|
-
**
|
|
4
|
-
|
|
3
|
+
**Your infrastructure repo as a graph, from the files.**
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npx @intentius/behold serve .
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Run it in a folder of Terraform and it finds each root and draws it as a box of resources, with an edge for each reference the configuration states. It needs no state file or cloud account, and it runs no `terraform` binary. It writes nothing into the folder it reads. Terraform roots are what it draws from files today. Kubernetes manifests in a plain directory and the edges between tools are coming. behold works beside the tools a repo already uses.
|
|
10
|
+
|
|
11
|
+

|
|
12
|
+
|
|
13
|
+
## With chant
|
|
14
|
+
|
|
15
|
+
Reads what chant records for terragucci and plywood.
|
|
16
|
+
|
|
17
|
+
Every substrate in one graph, coloured by drift. Then act through delegated, gated Ops.
|
|
5
18
|
|
|
6
19
|
📖 **[Documentation](https://intentius.io/behold/)** starts with an agent prompt
|
|
7
20
|
that gets you to a running graph without reading anything else first.
|
|
@@ -130,6 +143,42 @@ To colour the graph by what is actually deployed, name an environment with
|
|
|
130
143
|
for one specific demo project. `behold demo` and `serve --local` supersede it for
|
|
131
144
|
every purpose; it is kept for compatibility and is not documented further.</sub>
|
|
132
145
|
|
|
146
|
+
## Print the graph: `behold graph`
|
|
147
|
+
|
|
148
|
+
`behold graph [dir]` reads a directory and prints its graph, with no server
|
|
149
|
+
and no browser. A CI job, an editor or a script can take the output as it is.
|
|
150
|
+
|
|
151
|
+
```sh
|
|
152
|
+
npx @intentius/behold graph ./infra --json | jq '.nodes | length'
|
|
153
|
+
npx @intentius/behold graph ./infra --ir -o graph.json --detail 3
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
`--json` (the default) prints the `behold-graph/1` document. `--ir` prints the
|
|
157
|
+
unversioned `{ir, meta}` snapshot that `/api/graph` answers, without its SVG.
|
|
158
|
+
Neither holds an absolute path, and a card's source text is left out unless
|
|
159
|
+
you pass `--source`. A root that does not parse is one card in the output, as
|
|
160
|
+
it is in the browser.
|
|
161
|
+
`--svg [--theme light|dark]` writes the picture as one self-contained SVG file.
|
|
162
|
+
|
|
163
|
+
Two cuts print part of the graph. `--changed <base>..<head>` keeps what
|
|
164
|
+
changed between two commits (cards added, removed or changed, marked `diff` in
|
|
165
|
+
the document) and the cards within `--depth` hops of them (default 1), read
|
|
166
|
+
from `git archive` into a temporary directory, so the checkout is not touched
|
|
167
|
+
and a shallow clone works once both commits are fetched. A commit that only
|
|
168
|
+
reformats a file changes no card. Past `--budget` cards (default 60) the
|
|
169
|
+
neighbours fold into a count per box, then the cut becomes a table of counts.
|
|
170
|
+
`--around <id>[,<id>...]` keeps the named cards or boxes and what is within
|
|
171
|
+
`--depth` hops, `--up` or `--down` for one direction.
|
|
172
|
+
|
|
173
|
+
```sh
|
|
174
|
+
npx @intentius/behold graph ./infra --changed origin/main...HEAD -o cut.json
|
|
175
|
+
npx @intentius/behold graph ./infra --around prod/prod/aws_vpc.main --depth 2
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
The same command ships on its own as `@intentius/behold-graph`
|
|
179
|
+
(`npx @intentius/behold-graph ./infra`), a smaller install with none of the
|
|
180
|
+
server's dependencies; packages/graph/README.md has its budget.
|
|
181
|
+
|
|
133
182
|
## Export and host: a shareable, interactive snapshot
|
|
134
183
|
|
|
135
184
|
`behold export` freezes whatever estate you're looking at into a **self-contained
|
|
@@ -449,15 +498,17 @@ The docs' terragucci page says what it shows.
|
|
|
449
498
|
|
|
450
499
|
The demo is served at `/`: the live demo's page, else the first listed one.
|
|
451
500
|
`/kiosk` redirects to `/`. The listed demos are the multi-state plan-and-apply
|
|
452
|
-
ones
|
|
453
|
-
|
|
501
|
+
ones (`choudoufu-compose`, `terragrunt-choudoufu`, `atmos-choudoufu`,
|
|
502
|
+
`chant-compose`); one is listed once its tool has a published cycle
|
|
454
503
|
(`cycles/<tool>/latest.json` beside `demo.json`) or is live, and
|
|
455
|
-
`/api/terragucci/demos` says which.
|
|
456
|
-
|
|
457
|
-
|
|
504
|
+
`/api/terragucci/demos` says which. No demo has a page of its own: a tool's
|
|
505
|
+
path (`/choudoufu-compose`, `/terragrunt-choudoufu`, `/atmos-choudoufu`,
|
|
506
|
+
`/chant-compose`) redirects to `/` with a 302, so a link to one lands on
|
|
507
|
+
whichever demo `/` shows. The page shows that demo under a banner with the
|
|
508
|
+
example's name, the act, its products and a link to its code.
|
|
458
509
|
The older tools' URLs (`/terraform`, `/terragrunt`, `/cdk-terrain`, `/choudoufu`,
|
|
459
|
-
`/chant`, and the fan-out pages) redirect to
|
|
460
|
-
404 with a link to the front page.
|
|
510
|
+
`/chant`, and the fan-out pages) redirect to `/` too. Any other short path
|
|
511
|
+
answers 404 with a link to the front page.
|
|
461
512
|
|
|
462
513
|
In a declared workspace, the gates waiting on a person come from
|
|
463
514
|
`chant workspace status <env> --json`, keyed `member/op/gate` the way arugula's
|
|
@@ -722,7 +773,10 @@ Flux mark, a `Helm::Release` the Helm wheel. The corpus is vendored under
|
|
|
722
773
|
`web/icons/` (30 kubernetes/community SVGs, 3 cncf/artwork marks for
|
|
723
774
|
Flux/Argo/Helm, licensing in `THIRD_PARTY.md`) and mapped kind by kind in
|
|
724
775
|
`src/icon-packs.ts`; a kind with no official icon falls through to pinhole's
|
|
725
|
-
keyword heuristic rather than a wrong picture.
|
|
776
|
+
keyword heuristic rather than a wrong picture. The painter reads the corpus from
|
|
777
|
+
`src/icons.generated.ts`, which `npm run generate:icons` writes from `web/icons/`
|
|
778
|
+
and `npm run check:icons` holds to it, so `src/render.ts` reads no file and
|
|
779
|
+
bundles for a browser (`npm run check:browser-bundle`, #1069).
|
|
726
780
|
|
|
727
781
|
dagre's layout is a good first draft, not a final one: drag a card to move
|
|
728
782
|
it, grab a containment box's corner to resize it, and both survive a reload.
|
package/THIRD_PARTY.md
CHANGED
|
@@ -36,11 +36,12 @@ into one document cannot collide. No geometry is touched; every path is byte-ide
|
|
|
36
36
|
upstream. [`scripts/vendor-icons.mjs`](./scripts/vendor-icons.mjs) re-fetches the corpus at
|
|
37
37
|
the pinned revision, and `--check` asserts the working tree still matches it.
|
|
38
38
|
|
|
39
|
-
At
|
|
40
|
-
[`src/icon-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
39
|
+
At build time one further step happens to a copy, never to the file on disk:
|
|
40
|
+
[`src/icon-svg.ts`](./src/icon-svg.ts) splits each body out of its root `<svg>`, so the
|
|
41
|
+
remaining `inkscape:`/`sodipodi:` attributes — which that root declared the namespaces for —
|
|
42
|
+
are dropped and `xlink:href` becomes the plain SVG 2 `href`. Editor state only; nothing that
|
|
43
|
+
paints. `npm run generate:icons` writes the result to `src/icons.generated.ts`, which is what
|
|
44
|
+
[`src/icon-packs.ts`](./src/icon-packs.ts) splices into the graph SVG.
|
|
44
45
|
|
|
45
46
|
## Flux, Argo and Helm project marks (`web/icons/cncf/`)
|
|
46
47
|
|