@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 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 four tools, all clients of a running serve's HTTP API. An agent reads
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
- **A live control plane on [chant](https://github.com/INTENTIUS/chant).** Every
4
- substrate in one graph, coloured by drift. Then act through delegated, gated Ops.
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
+ ![Two Terraform roots, app and net, drawn as boxes of resources with an edge for each reference](https://raw.githubusercontent.com/INTENTIUS/behold/main/docs/public/readme/two-roots.png)
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, each at a path of its own (`/choudoufu-compose`, `/terragrunt-choudoufu`,
453
- `/atmos-choudoufu`, `/chant-compose`); one is listed once its tool has a published cycle
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. A page shows the demo's live run, or replays
456
- its latest cycle, under a banner with the example's name, its products, a link to
457
- its code in INTENTIUS/terragucci, and a switcher when more than one is listed.
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 `/`. Any other short path answers
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 render time one further step happens to the copy in memory, never to the file on disk:
40
- [`src/icon-packs.ts`](./src/icon-packs.ts) splices each body into the graph SVG without its
41
- root `<svg>`, so the remaining `inkscape:`/`sodipodi:` attributes — which that root declared
42
- the namespaces for — are dropped and `xlink:href` becomes the plain SVG 2 `href`. Editor
43
- state only; nothing that paints.
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