@intentius/behold 0.29.50 → 0.29.52

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/web/app.js CHANGED
@@ -10,7 +10,8 @@
10
10
  // renderPanelView never rewrites, so the select mounts once and survives re-renders).
11
11
  import "./view-repo.js"; // behold#571: first, so every read carries the page's ?repo=
12
12
  import { createRefreshQueue } from "./refresh-queue.js";
13
- import { readViewQuery, writeViewQuery, settleView, settlePlace, refusalLine } from "./view-url.js";
13
+ import { indexCompositeMembers } from "./composite-members.js";
14
+ import { readViewQuery, writeViewQuery, settleView, settlePlace, refusalLine, withOpening, defaultEnv } from "./view-url.js";
14
15
  import { quietCardLines, readEmbed, selectMessage, viewFromMessage, wheelPx, wheelZoomsBare } from "./embed.js";
15
16
  import { WORDS as POP_WORDS, cardRoot as popCardRoot, placePopover, popReduce, popState, resourcePopover, rootPopover } from "./kiosk-popover.js";
16
17
  import { waveListKey, waveListOf } from "./kiosk-wave-list.js";
@@ -25,6 +26,7 @@ import { renderTrunkLane } from "./trunk-lane.js";
25
26
  import { startLocalRuns } from "./local-run.js";
26
27
  import { entriesFor as csEntriesFor, gapLines as csGapLines, inspectHeading as csInspectHeading, nodeMarks as csNodeMarks, offGraph as csOffGraph, overlayHeader as csHeader, overlayLegend as csLegend, PREVIEW_NOTE as CS_PREVIEW_NOTE } from "./change-set-overlay.js";
27
28
  import { collisionFilter as coFilter, collisionHeader as coHeader, collisionMarks as coMarks, collisionsFor as coFor, COLLISION_NOTE as CO_NOTE, FILES_NOTE as CO_FILES_NOTE, FILTER_OFF as CO_FILTER_OFF, FILTER_ON as CO_FILTER_ON, gapLines as coGapLines, hideEdge as coHideEdge, itemRow as coItemRow, nodeRow as coNodeRow, sideLines as coSideLines } from "./collision-marks.js";
29
+ import { dimEdge as hmDimEdge, HEALTH_NOTE as HM_NOTE, healthHeader as hmHeader, healthLegendRows as hmLegendRows, healthMarks as hmMarks, healthRows as hmRows, memberLines as hmMemberLines } from "./health-marks.js";
28
30
  import { flagMarks as flFlagMarks, flagRow as flFlagRow, flagsFor as flFlagsFor, flagsHeader as flHeader, gapLines as flGapLines, NODES_NOTE as FL_NODES_NOTE, pickEnv as flPickEnv, STALE_COLOR as FL_STALE_COLOR, TURN_ON_NOTE as FL_TURN_ON_NOTE } from "./feature-flags.js";
29
31
  import { renderYodelLane } from "./sql-yodeler-lane.js";
30
32
  import { initTerragucciEstate } from "./terragucci-estate.js";
@@ -119,6 +121,7 @@ import { ehStore, ehStored } from "./event-help-store.js";
119
121
  // which commit, approved by whom — and, when the ledger's run id cannot be
120
122
  // followed, the reason in words rather than a guessed link.
121
123
  import { releaseRows } from "./release.js";
124
+ import { renderExportNote } from "./export-note.js";
122
125
  import { danglingFor, danglingRows, danglingHeading, DANGLING_EXPLAINED } from "./dangling.js";
123
126
  import { comparisonRow, comparisonSummary } from "./cross-env.js";
124
127
  // The marker-vs-derived mark on a choudoufu card: how its identity was found.
@@ -374,6 +377,9 @@ if (staticMode) {
374
377
  } catch {
375
378
  /* no manifest → apiFetch falls back to a not-captured error */
376
379
  }
380
+ // #824: the line `behold export --note` put at the page's foot.
381
+ const noteEl = document.getElementById("export-note");
382
+ if (noteEl) renderExportNote(noteEl, document, manifest);
377
383
  }
378
384
 
379
385
  /** Canonical key for a read URL — path + the lens params (whitelisted, sorted)
@@ -1053,6 +1059,12 @@ function inspect(node) {
1053
1059
  panel.appendChild(row);
1054
1060
  }
1055
1061
  }
1062
+ // #825: runtime health from chant lifecycle health, and a record's rotation.
1063
+ const hmInspect = hmAnswer && hmAnswer.env === view.env ? hmRows(hmAnswer, node.id) : [];
1064
+ if (hmInspect.length) {
1065
+ const add = section(`runtime health · ${hmAnswer.env}`);
1066
+ for (const [k, v] of hmInspect) add(k, v);
1067
+ }
1056
1068
  // #684: the in-flight work items colliding on this card.
1057
1069
  const coRows = coAnswer && coOn ? coFor(coAnswer, node.id) : [];
1058
1070
  if (coRows.length) {
@@ -2604,7 +2616,8 @@ let selectedNodeId = null;
2604
2616
  let viewUrlReady = false; // nothing is written back until the link has been read
2605
2617
  function openFromQuery() {
2606
2618
  viewUrlReady = true;
2607
- applyWantedView(readViewQuery(location.search));
2619
+ // #827: a static export can name the view it opens on; the link's own query wins.
2620
+ applyWantedView(withOpening(manifest && manifest.opening, readViewQuery(location.search)));
2608
2621
  }
2609
2622
 
2610
2623
  /**
@@ -2956,7 +2969,7 @@ function syncViewUrl() {
2956
2969
  focus: view.focus,
2957
2970
  run: view.run,
2958
2971
  };
2959
- const defaults = { env: (projectInfo && projectInfo.currentEnv) || null, lens: savedColourMode };
2972
+ const defaults = { env: defaultEnv(manifest && manifest.opening, projectInfo && projectInfo.currentEnv), lens: savedColourMode };
2960
2973
  const next = location.pathname + writeViewQuery(location.search, state, defaults) + location.hash;
2961
2974
  if (next === location.pathname + location.search + location.hash) return;
2962
2975
  try {
@@ -3069,6 +3082,7 @@ function renderPanelModel() {
3069
3082
  } else if (dm) {
3070
3083
  host.appendChild(panelMuted("attribute drift not read — the overlay is ownership only. ⌘K → “Re-check live with plan”."));
3071
3084
  }
3085
+ renderHealthLegend(host); // #825: runtime health, beside drift and apart from it
3072
3086
  // The actionable nodes — foreign (adoptable) and pending (not applied yet).
3073
3087
  const attention = ir.nodes.filter((n) => {
3074
3088
  const s = n.attrs && n.attrs._status;
@@ -6474,6 +6488,117 @@ function renderCollisionsTab() {
6474
6488
  }
6475
6489
  initCollisions();
6476
6490
 
6491
+ // --- #825: runtime health and rotation ---------------------------------------
6492
+ // When the graph shows an environment, /api/health is read once for it (a
6493
+ // static export replays the captured snapshot): per card that has a health
6494
+ // read, healthy, unhealthy or unknown from `chant lifecycle health`, or a hole
6495
+ // with chant's reason when the read failed; and per Route 53 record whose
6496
+ // HealthCheckId names a declared check, its rotation. Health never touches a
6497
+ // card's fill, which stays the drift overlay's. A tag under the card says the
6498
+ // state, an unhealthy card gets a solid ring and a hole a dashed one, and a
6499
+ // record out of rotation is dimmed with its edges. "Re-check live" reads it
6500
+ // again with ?fresh=1.
6501
+ let hmAnswer = null;
6502
+ let hmLoading = null;
6503
+ function syncHealth(m) {
6504
+ // `progressive` is the overlay while members are still reading (#422).
6505
+ const drift = !!m && !!m.env && ["overlay", "progressive", "logical"].includes(m.mode);
6506
+ if (!drift || publicMode) {
6507
+ markHealthCards(null);
6508
+ return;
6509
+ }
6510
+ if (hmAnswer && hmAnswer.env === m.env) {
6511
+ markHealthCards(hmAnswer);
6512
+ return;
6513
+ }
6514
+ loadHealth(m.env, false);
6515
+ }
6516
+ async function loadHealth(env, fresh) {
6517
+ if (publicMode) return;
6518
+ if (hmLoading === env && !fresh) return;
6519
+ hmLoading = env;
6520
+ const answer = await apiFetch(`/api/health?env=${encodeURIComponent(env)}${fresh ? "&fresh=1" : ""}`)
6521
+ .then((r) => r.json())
6522
+ .catch((e) => ({ error: String(e) }));
6523
+ if (hmLoading !== env) return; // a newer env was asked for meanwhile
6524
+ hmLoading = null;
6525
+ hmAnswer = { ...answer, env };
6526
+ if (view.env === env) {
6527
+ markHealthCards(hmAnswer);
6528
+ renderPanel();
6529
+ }
6530
+ }
6531
+ function markHealthCards(a) {
6532
+ const svg = document.querySelector("#graph svg");
6533
+ if (!svg) return;
6534
+ for (const old of svg.querySelectorAll("[data-hm-mark]")) old.remove();
6535
+ for (const d of svg.querySelectorAll("[data-hm-dim]")) {
6536
+ d.removeAttribute("data-hm-dim");
6537
+ d.style.opacity = "";
6538
+ }
6539
+ if (!a) return;
6540
+ const ids = [...svg.querySelectorAll("[data-node-id]")].map((g) => g.getAttribute("data-node-id"));
6541
+ for (const [id, mk] of Object.entries(hmMarks(a, ids))) {
6542
+ const g = svg.querySelector('[data-node-id="' + CSS.escape(id) + '"]');
6543
+ if (!g) continue;
6544
+ const rect = g.querySelector("rect");
6545
+ const box = rect && rect.getBBox ? rect.getBBox() : { x: 0, y: 0, width: 150, height: 60 };
6546
+ if (mk.ring) {
6547
+ const ring = document.createElementNS("http://www.w3.org/2000/svg", "rect");
6548
+ ring.setAttribute("data-hm-mark", "ring");
6549
+ for (const [k, v] of Object.entries({ x: box.x - 3, y: box.y - 3, width: box.width + 6, height: box.height + 6, rx: 8, fill: "none", stroke: mk.color, "stroke-width": 2, "pointer-events": "none" })) ring.setAttribute(k, String(v));
6550
+ if (mk.ring === "dashed") ring.setAttribute("stroke-dasharray", "4 4");
6551
+ g.appendChild(ring);
6552
+ }
6553
+ const tag = document.createElementNS("http://www.w3.org/2000/svg", "text");
6554
+ tag.setAttribute("data-hm-mark", "tag");
6555
+ tag.setAttribute("x", String(box.x));
6556
+ // Under the card, where the flag tag sits (#683): above it, a card in a
6557
+ // box's top row would run into the box's own header.
6558
+ tag.setAttribute("y", String(box.y + box.height + 13));
6559
+ tag.setAttribute("font-size", "11");
6560
+ tag.setAttribute("font-weight", "700");
6561
+ tag.setAttribute("fill", mk.color);
6562
+ tag.textContent = `● ${mk.tag}`;
6563
+ const title = document.createElementNS("http://www.w3.org/2000/svg", "title");
6564
+ title.textContent = mk.title;
6565
+ tag.appendChild(title);
6566
+ g.appendChild(tag);
6567
+ if (mk.dim) {
6568
+ // The card and its own text go faint; the tag under it stays legible.
6569
+ for (const child of g.children) {
6570
+ if (child.hasAttribute("data-hm-mark")) continue;
6571
+ child.setAttribute("data-hm-dim", "1");
6572
+ child.style.opacity = "0.35";
6573
+ }
6574
+ }
6575
+ }
6576
+ for (const e of svg.querySelectorAll("g[data-edge-from]")) {
6577
+ if (!hmDimEdge(a, e.getAttribute("data-edge-from"), e.getAttribute("data-edge-to"))) continue;
6578
+ e.setAttribute("data-hm-dim", "1");
6579
+ e.style.opacity = "0.25";
6580
+ }
6581
+ }
6582
+ /** The Model tab's health legend, under the drift legend. */
6583
+ function renderHealthLegend(host) {
6584
+ if (!hmAnswer || hmAnswer.env !== view.env || publicMode) return;
6585
+ const h = hmHeader(hmAnswer);
6586
+ const heading = panelHeading(h.text);
6587
+ heading.title = h.title || HM_NOTE;
6588
+ if (h.tone === "refusal") heading.style.color = "var(--degraded)";
6589
+ host.appendChild(heading);
6590
+ for (const r of hmLegendRows(hmAnswer)) host.appendChild(panelDotRow(r.color, r.text, r.count));
6591
+ for (const [id, r] of Object.entries(hmAnswer.rotation || {})) {
6592
+ if (r.inRotation !== false) continue;
6593
+ host.appendChild(panelDotRow("var(--degraded)", id, "out of rotation", () => selectNode(id)));
6594
+ }
6595
+ for (const l of hmMemberLines(hmAnswer)) {
6596
+ const p = panelMuted(l.text);
6597
+ p.title = l.title;
6598
+ host.appendChild(p);
6599
+ }
6600
+ }
6601
+
6477
6602
  // --- #681: a waiting gate's change set, on the graph -------------------------
6478
6603
  // Opened from a gate card's "change set" link in the Trunk tab. The server
6479
6604
  // reads the gate from status and the stored change set from chant change-set
@@ -7221,6 +7346,7 @@ function resetDialCaches() {
7221
7346
 
7222
7347
  // Composite → member list, for the inspect pane. Derived once from the base
7223
7348
  // (attribute-tier) source graph, where every node carries its `compositeInstance`
7349
+ // (indexed by web/composite-members.js, #828)
7224
7350
  // — then a detail-1 composite node lists what it expands to. Cached per lens
7225
7351
  // (reset in resetDialCaches); structural, so no live/env call needed.
7226
7352
  let compositeMembersCache = null;
@@ -7230,9 +7356,7 @@ async function getCompositeMembers(instanceId) {
7230
7356
  try {
7231
7357
  const q = lensParams(new URLSearchParams({ detail: "3" }));
7232
7358
  const j = await apiFetch(`/api/graph?${q}`).then((r) => r.json());
7233
- for (const n of (j.ir && j.ir.nodes) || []) {
7234
- if (n.compositeInstance) (compositeMembersCache[n.compositeInstance] ||= []).push({ id: n.id, kind: n.kind });
7235
- }
7359
+ compositeMembersCache = indexCompositeMembers(j.ir && j.ir.nodes);
7236
7360
  } catch {
7237
7361
  /* leave the cache empty — the members section shows "(no members found)" */
7238
7362
  }
@@ -8407,6 +8531,7 @@ function render(ir, svg, m) {
8407
8531
  if (csAnswer) markChangeSetCards(); // #681: and the change set a gate binds, as a preview
8408
8532
  if (flAnswer) markFlagCards(); // #683: and the feature flags of each flagged member
8409
8533
  if (coAnswer) markCollisionCards(); // #684: and the nodes two in-flight work items touch
8534
+ syncHealth(m); // #825: and runtime health, with the records out of rotation
8410
8535
  applyLayout(); // #228: last, so the hand-placed deltas ride on top of every other pass
8411
8536
  drawTgReads(); // #568: after the layout, so the reads lines meet the cards where they now sit
8412
8537
  renderDial();
@@ -9724,6 +9849,7 @@ async function refresh() {
9724
9849
  if (!res.ok) throw new Error((await res.json()).error || res.statusText);
9725
9850
  const { ir, svg, meta: m, captured } = await res.json();
9726
9851
  render(ir, svg, m);
9852
+ if (view.env) loadHealth(view.env, true); // #825: health moves on its own; read it again too
9727
9853
  nowline(captured ? "↻ refreshed — new lanes frame" : "↻ refreshed — no change");
9728
9854
  } catch (err) {
9729
9855
  meta.textContent = prev;
@@ -0,0 +1,21 @@
1
+ // behold#828: a composites-zoom card's member list. The inspect pane derives it
2
+ // from the attribute-tier graph, where every member carries its
3
+ // `compositeInstance` and `compositeParent`. chant keys a collapsed composite by
4
+ // its instance name, and when two composites share that name (an AWS
5
+ // FargateAlb and a GCP CloudRunServiceComposite both exported as `web`) it
6
+ // names them `<instance>@<CompositeType>` (chant#4178). So each member is
7
+ // listed under both keys, and a card finds its own members whichever id it has.
8
+ //
9
+ // Pure logic, no DOM.
10
+
11
+ /** Member lists by composite id: `<instance>` and `<instance>@<compositeParent>`. */
12
+ export function indexCompositeMembers(nodes) {
13
+ const out = {};
14
+ for (const n of nodes || []) {
15
+ if (!n.compositeInstance) continue;
16
+ const member = { id: n.id, kind: n.kind };
17
+ (out[n.compositeInstance] ||= []).push(member);
18
+ if (n.compositeParent) (out[`${n.compositeInstance}@${n.compositeParent}`] ||= []).push(member);
19
+ }
20
+ return out;
21
+ }
@@ -0,0 +1,25 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { indexCompositeMembers } from "./composite-members.js";
3
+
4
+ const nodes = [
5
+ { id: "webCluster", kind: "AWS::ECS::Cluster", compositeInstance: "web", compositeParent: "FargateAlb" },
6
+ { id: "webService", kind: "AWS::ECS::Service", compositeInstance: "web", compositeParent: "FargateAlb" },
7
+ { id: "GcpwebService", kind: "RunService", compositeInstance: "web", compositeParent: "CloudRunServiceComposite" },
8
+ { id: "zone", kind: "AWS::Route53::HostedZone" },
9
+ ];
10
+
11
+ describe("indexCompositeMembers (#828)", () => {
12
+ it("lists each of two same-named composites under chant's split id", () => {
13
+ const idx = indexCompositeMembers(nodes);
14
+ expect(idx["web@FargateAlb"].map((m) => m.id)).toEqual(["webCluster", "webService"]);
15
+ expect(idx["web@CloudRunServiceComposite"]).toEqual([{ id: "GcpwebService", kind: "RunService" }]);
16
+ });
17
+ it("keeps the bare instance id for a composite whose name is its own", () => {
18
+ const idx = indexCompositeMembers([{ id: "a", kind: "K", compositeInstance: "app", compositeParent: "Thing" }]);
19
+ expect(idx.app).toEqual([{ id: "a", kind: "K" }]);
20
+ });
21
+ it("leaves out nodes no composite owns", () => {
22
+ expect(Object.values(indexCompositeMembers(nodes)).flat().some((m) => m.id === "zone")).toBe(false);
23
+ expect(indexCompositeMembers(undefined)).toEqual({});
24
+ });
25
+ });
@@ -0,0 +1,35 @@
1
+ // #824: the line an export shows at its foot, from `behold export --note`.
2
+ // The manifest carries it as `note`; a static page draws it under the graph,
3
+ // where the three-cloud demo's page says how to run the estate yourself.
4
+ // Plain text, with a span in backticks drawn as code. Nothing else is markup:
5
+ // the text is set as text, never as HTML.
6
+
7
+ /** The note split into runs of plain text and code, in order. An unclosed
8
+ * backtick is kept as text. */
9
+ export function noteSegments(text) {
10
+ const out = [];
11
+ const re = /`([^`]+)`/g;
12
+ let at = 0;
13
+ for (let m = re.exec(text); m; m = re.exec(text)) {
14
+ if (m.index > at) out.push({ code: false, text: text.slice(at, m.index) });
15
+ out.push({ code: true, text: m[1] });
16
+ at = m.index + m[0].length;
17
+ }
18
+ if (at < text.length) out.push({ code: false, text: text.slice(at) });
19
+ return out;
20
+ }
21
+
22
+ /** The note a manifest carries, or null when it carries none. */
23
+ export function manifestNote(manifest) {
24
+ const note = manifest && typeof manifest.note === "string" ? manifest.note.trim() : "";
25
+ return note || null;
26
+ }
27
+
28
+ /** Fill `el` with the note and show it; hide it when there is no note. */
29
+ export function renderExportNote(el, doc, manifest) {
30
+ const note = manifestNote(manifest);
31
+ el.textContent = "";
32
+ el.hidden = !note;
33
+ if (!note) return;
34
+ for (const seg of noteSegments(note)) el.appendChild(seg.code ? Object.assign(doc.createElement("code"), { textContent: seg.text }) : doc.createTextNode(seg.text));
35
+ }
@@ -0,0 +1,45 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { manifestNote, noteSegments, renderExportNote } from "./export-note.js";
3
+
4
+ // #824: the line under an exported page.
5
+ describe("an export's note", () => {
6
+ it("splits backticked spans out as code", () => {
7
+ expect(noteSegments("Run this yourself: `npx @intentius/behold demo three-cloud`")).toEqual([
8
+ { code: false, text: "Run this yourself: " },
9
+ { code: true, text: "npx @intentius/behold demo three-cloud" },
10
+ ]);
11
+ expect(noteSegments("`a` and `b`.")).toEqual([
12
+ { code: true, text: "a" },
13
+ { code: false, text: " and " },
14
+ { code: true, text: "b" },
15
+ { code: false, text: "." },
16
+ ]);
17
+ });
18
+
19
+ it("keeps an unclosed backtick as text", () => {
20
+ expect(noteSegments("run `this")).toEqual([{ code: false, text: "run `this" }]);
21
+ });
22
+
23
+ it("reads the note from the manifest, and nothing when it has none", () => {
24
+ expect(manifestNote({ note: " hi " })).toBe("hi");
25
+ expect(manifestNote({})).toBe(null);
26
+ expect(manifestNote(null)).toBe(null);
27
+ expect(manifestNote({ note: 3 })).toBe(null);
28
+ });
29
+
30
+ it("sets the note as text, never as markup", () => {
31
+ const made = [];
32
+ const doc = {
33
+ createElement: (tag) => ({ tag, textContent: "" }),
34
+ createTextNode: (text) => ({ text }),
35
+ };
36
+ const el = { hidden: true, textContent: "old", appendChild: (n) => made.push(n) };
37
+ renderExportNote(el, doc, { note: "<b>x</b> `y`" });
38
+ expect(el.hidden).toBe(false);
39
+ expect(made).toEqual([{ text: "<b>x</b> " }, { tag: "code", textContent: "y" }]);
40
+
41
+ renderExportNote(el, doc, {});
42
+ expect(el.hidden).toBe(true);
43
+ expect(el.textContent).toBe("");
44
+ });
45
+ });
@@ -0,0 +1,146 @@
1
+ // #825: runtime health and rotation on the graph. Pure words and colours from
2
+ // /api/health; app.js draws them.
3
+ //
4
+ // Health is what `chant lifecycle health` says about a declared thing that
5
+ // serves: a Route 53 health check, an ECS service, a Container App, a Cloud
6
+ // Run service. It is not drift, so it never touches the card's fill: a tag
7
+ // under the card says the state, and an unhealthy card gets a solid ring in
8
+ // the degraded colour. A check chant could not read is a hole, a dashed ring
9
+ // in the neutral colour with chant's reason, never drawn as unhealthy.
10
+ //
11
+ // A Route 53 record whose health check is unhealthy is out of rotation: the
12
+ // record and its edges are dimmed and its tag says which check took it out.
13
+ // A check that is unknown or was not read leaves the record's rotation
14
+ // unknown, said in words, and nothing is dimmed.
15
+
16
+ /** The colour of each state, from the drift legend's tokens. */
17
+ export const HEALTH_COLOR = {
18
+ healthy: "var(--managed)",
19
+ unhealthy: "var(--degraded)",
20
+ unknown: "var(--muted)",
21
+ unobserved: "var(--neutral)",
22
+ absent: "var(--muted)",
23
+ };
24
+
25
+ /** The word for each state on a card and in the legend. */
26
+ export const HEALTH_WORD = {
27
+ healthy: "healthy",
28
+ unhealthy: "unhealthy",
29
+ unknown: "health unknown",
30
+ unobserved: "health not read",
31
+ absent: "not deployed",
32
+ };
33
+
34
+ /** The note on what health is, for the legend's tooltip. */
35
+ export const HEALTH_NOTE =
36
+ "From chant lifecycle health: whether a declared health check or service is serving, read apart from drift. A check chant could not read is shown as not read, never as unhealthy. A Route 53 record is out of rotation when the health check its HealthCheckId names is unhealthy.";
37
+
38
+ /** Whether the answer has anything to draw. */
39
+ export function healthUsable(a) {
40
+ return !!a && !a.error && !a.refusal && !!a.nodes;
41
+ }
42
+
43
+ /** The legend's first line: what was read, or why it wasn't. */
44
+ export function healthHeader(a) {
45
+ if (!a || a.error) return { text: `health not read${a && a.error ? `: ${a.error}` : ""}`, title: "", tone: "refusal" };
46
+ if (a.refusal) return { text: `health not read: ${a.refusal.error}`, title: [a.refusal.remedy, a.degraded ? `Without it, ${a.degraded}.` : ""].filter(Boolean).join("\n"), tone: "refusal" };
47
+ const n = Object.keys(a.nodes).length;
48
+ if (!n) return { text: "nothing declared here has a health read", title: HEALTH_NOTE, tone: "quiet" };
49
+ return { text: `health · ${a.env}`, title: HEALTH_NOTE, tone: "quiet" };
50
+ }
51
+
52
+ /** The legend's rows: one per state that occurs, with its count, then the records out of rotation. */
53
+ export function healthLegendRows(a) {
54
+ if (!healthUsable(a)) return [];
55
+ const c = a.counts || {};
56
+ const rows = [];
57
+ for (const k of ["healthy", "unhealthy", "unknown", "unobserved", "absent"]) {
58
+ if (c[k]) rows.push({ color: HEALTH_COLOR[k], text: HEALTH_WORD[k], count: String(c[k]) });
59
+ }
60
+ if (c.outOfRotation) rows.push({ color: HEALTH_COLOR.unhealthy, text: "records out of rotation", count: String(c.outOfRotation), dashed: true });
61
+ return rows;
62
+ }
63
+
64
+ /** Members whose read was refused, as lines under the legend. */
65
+ export function memberLines(a) {
66
+ if (!a || !Array.isArray(a.members)) return [];
67
+ return a.members.filter((m) => m.refusal).map((m) => ({ text: `${m.member ? `${m.member}: ` : ""}health not read: ${m.refusal.error}`, title: m.refusal.remedy || "" }));
68
+ }
69
+
70
+ /** The tooltip of one node's health. */
71
+ function healthTitle(id, h) {
72
+ if (h.state === "unobserved") return [`${id}: chant could not read its health (${h.reason}).`, h.detail || "", "This is a hole, not a verdict: the check may be fine."].filter(Boolean).join("\n");
73
+ if (h.state === "absent") return `${id}: the provider says it is not deployed.`;
74
+ return [`${id}: ${h.state}`, h.detail, h.checkedAt ? `checked ${h.checkedAt}` : "", `read ${h.observedAt}`].filter(Boolean).join("\n");
75
+ }
76
+
77
+ /**
78
+ * The marks to draw, per node id in `ids` that has health or a rotation:
79
+ * `tag` (the line under the card), `color`, `ring` (`solid`, `dashed` or
80
+ * none), `dim` (the record is out of rotation) and `title`.
81
+ */
82
+ export function healthMarks(a, ids) {
83
+ const out = {};
84
+ if (!healthUsable(a)) return out;
85
+ const want = new Set(ids);
86
+ for (const [id, h] of Object.entries(a.nodes)) {
87
+ if (!want.has(id)) continue;
88
+ const word = h.state === "unobserved" ? `${HEALTH_WORD.unobserved}: ${h.reason}` : HEALTH_WORD[h.state] || h.state;
89
+ out[id] = {
90
+ tag: word,
91
+ color: HEALTH_COLOR[h.state] || "var(--muted)",
92
+ ring: h.state === "unhealthy" ? "solid" : h.state === "unobserved" ? "dashed" : null,
93
+ dim: false,
94
+ title: healthTitle(id, h),
95
+ };
96
+ }
97
+ for (const [id, r] of Object.entries(a.rotation || {})) {
98
+ if (!want.has(id) || out[id]) continue;
99
+ out[id] = {
100
+ tag: r.line,
101
+ color: r.inRotation === false ? HEALTH_COLOR.unhealthy : r.inRotation === true ? HEALTH_COLOR.healthy : HEALTH_COLOR.unknown,
102
+ ring: null,
103
+ dim: r.inRotation === false,
104
+ title: rotationTitle(r),
105
+ };
106
+ }
107
+ return out;
108
+ }
109
+
110
+ function rotationTitle(r) {
111
+ if (r.inRotation === false) return `${r.record} is out of rotation: Route 53 stops answering with it while ${r.check} is unhealthy.`;
112
+ if (r.inRotation === true) return `${r.record} is in rotation: ${r.check} is healthy.`;
113
+ return `${r.record}: rotation unknown. behold has no verdict for ${r.check}, so it does not guess.`;
114
+ }
115
+
116
+ /** Whether an edge between two ids is drawn dimmed: when either end is a record out of rotation. */
117
+ export function dimEdge(a, from, to) {
118
+ if (!healthUsable(a) || !a.rotation) return false;
119
+ const out = (id) => !!a.rotation[id] && a.rotation[id].inRotation === false;
120
+ return out(from) || out(to);
121
+ }
122
+
123
+ /** The inspect pane's rows for one node: label and value pairs. */
124
+ export function healthRows(a, nodeId) {
125
+ if (!healthUsable(a)) return [];
126
+ const rows = [];
127
+ const h = a.nodes[nodeId];
128
+ if (h) {
129
+ if (h.state === "unobserved") {
130
+ rows.push(["state", HEALTH_WORD.unobserved], ["reason", h.reason]);
131
+ if (h.detail) rows.push(["detail", h.detail]);
132
+ } else if (h.state === "absent") {
133
+ rows.push(["state", HEALTH_WORD.absent]);
134
+ } else {
135
+ rows.push(["state", h.state], ["detail", h.detail]);
136
+ if (h.checkedAt) rows.push(["checked", h.checkedAt]);
137
+ rows.push(["read", h.observedAt]);
138
+ }
139
+ if (h.type) rows.push(["type", h.type]);
140
+ }
141
+ const r = a.rotation && a.rotation[nodeId];
142
+ if (r) rows.push(["rotation", r.inRotation === false ? "out" : r.inRotation === true ? "in" : "unknown"], ["health check", r.check], ["why", r.line]);
143
+ const routed = Object.values(a.rotation || {}).filter((x) => x.check === nodeId);
144
+ for (const x of routed) rows.push(["guards", `${x.record} (${x.inRotation === false ? "out of rotation" : x.inRotation === true ? "in rotation" : "rotation unknown"})`]);
145
+ return rows;
146
+ }
@@ -0,0 +1,67 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { describe, expect, it } from "vitest";
4
+ import { healthCounts, nodeHealthOf, rotationOf } from "../src/runtime-health.ts";
5
+ import { dimEdge, HEALTH_COLOR, healthHeader, healthLegendRows, healthMarks, healthRows, memberLines } from "./health-marks.js";
6
+
7
+ // #825: the marks drawn from what chant printed for the #823 prototype
8
+ // (src/__fixtures__/health): the dns member against a floci whose Azure
9
+ // check fails, and the azure member with nothing behind it (a hole).
10
+ const FIX = join(import.meta.dirname, "..", "src", "__fixtures__", "health");
11
+ const read = (f) => JSON.parse(readFileSync(join(FIX, f), "utf8"));
12
+ const nodes = { ...nodeHealthOf(read("dns-health.json"), "dns"), ...nodeHealthOf(read("azure-health.json"), "azure") };
13
+ const rotation = rotationOf(read("dns-graph-ir.json"), nodes, "dns");
14
+ const answer = { env: "prod", nodes, rotation, counts: healthCounts(nodes, rotation), members: [{ member: "dns" }, { member: "gcp", refusal: { error: "Runtime health needs chant 0.124.33 or newer.", remedy: "Upgrade." } }] };
15
+ const ids = ["dns/awsCheck", "dns/azureCheck", "dns/azureRecord", "dns/awsRecord", "azure/app", "dns/zone"];
16
+
17
+ describe("health marks (#825)", () => {
18
+ it("tags each card with its state, rings the unhealthy one solid and the hole dashed", () => {
19
+ const m = healthMarks(answer, ids);
20
+ expect(m["dns/awsCheck"]).toMatchObject({ tag: "healthy", color: HEALTH_COLOR.healthy, ring: null, dim: false });
21
+ expect(m["dns/azureCheck"]).toMatchObject({ tag: "unhealthy", color: "var(--degraded)", ring: "solid" });
22
+ expect(m["dns/azureCheck"].title).toMatch(/0\/8 checkers healthy/);
23
+ expect(m["azure/app"]).toMatchObject({ tag: "health not read: read-failed", color: "var(--neutral)", ring: "dashed" });
24
+ expect(m["azure/app"].title).toMatch(/not a verdict/);
25
+ expect(m["dns/zone"]).toBeUndefined();
26
+ });
27
+
28
+ it("dims the record out of rotation and its edges, and only that one", () => {
29
+ const m = healthMarks(answer, ids);
30
+ expect(m["dns/azureRecord"]).toMatchObject({ tag: "out of rotation: azureCheck unhealthy", dim: true });
31
+ expect(m["dns/awsRecord"]).toMatchObject({ tag: "in rotation: awsCheck healthy", dim: false });
32
+ expect(dimEdge(answer, "dns/azureRecord", "dns/azureCheck")).toBe(true);
33
+ expect(dimEdge(answer, "dns/azureRecord", "dns/zone")).toBe(true);
34
+ expect(dimEdge(answer, "dns/awsRecord", "dns/awsCheck")).toBe(false);
35
+ });
36
+
37
+ it("dims nothing when the check was not read", () => {
38
+ const unread = nodeHealthOf(read("dns-unobserved.json"), "dns");
39
+ const rot = rotationOf(read("dns-graph-ir.json"), unread, "dns");
40
+ const a = { env: "prod", nodes: unread, rotation: rot, counts: healthCounts(unread, rot) };
41
+ expect(Object.values(healthMarks(a, ids)).some((x) => x.dim)).toBe(false);
42
+ expect(healthMarks(a, ids)["dns/azureRecord"].tag).toBe("rotation unknown: azureCheck not read");
43
+ });
44
+
45
+ it("gives the inspect pane the detail, checkedAt and what a check guards", () => {
46
+ expect(healthRows(answer, "dns/azureCheck")).toEqual([
47
+ ["state", "unhealthy"],
48
+ ["detail", "0/8 checkers healthy; last: Failure: DNS resolution failed for w825-nowhere.invalid."],
49
+ ["checked", "2026-10-21T04:48:42.977269840Z"],
50
+ ["read", "2026-10-21T04:48:58.414Z"],
51
+ ["type", "AWS::Route53::HealthCheck"],
52
+ ["guards", "dns/azureRecord (out of rotation)"],
53
+ ]);
54
+ expect(healthRows(answer, "dns/azureRecord")).toEqual([["rotation", "out"], ["health check", "dns/azureCheck"], ["why", "out of rotation: azureCheck unhealthy"]]);
55
+ expect(healthRows(answer, "azure/app")).toEqual([["state", "health not read"], ["reason", "read-failed"], ["detail", "fetch failed"], ["type", "Microsoft.App/containerApps"]]);
56
+ });
57
+
58
+ it("words the legend, a refused member, and a refusal", () => {
59
+ expect(healthHeader(answer).text).toBe("health · prod");
60
+ expect(healthLegendRows(answer).map((r) => [r.text, r.count])).toEqual([["healthy", "2"], ["unhealthy", "1"], ["health not read", "1"], ["records out of rotation", "1"]]);
61
+ expect(memberLines(answer)).toEqual([{ text: "gcp: health not read: Runtime health needs chant 0.124.33 or newer.", title: "Upgrade." }]);
62
+ const refused = { refusal: { error: "Runtime health needs chant 0.124.33 or newer.", remedy: "Upgrade." }, degraded: "the graph draws no health marks" };
63
+ expect(healthHeader(refused)).toMatchObject({ tone: "refusal" });
64
+ expect(healthMarks(refused, ids)).toEqual({});
65
+ expect(healthMarks({ error: "not in this static export" }, ids)).toEqual({});
66
+ });
67
+ });
package/web/index.html CHANGED
@@ -86,6 +86,7 @@
86
86
  #app #inspect { grid-row: 2; grid-column: 1; border-left: 0; border-top: 1px solid var(--rule); max-height: 45vh; }
87
87
  #app #inspect-resize { display: none; }
88
88
  #app #nowline { grid-column: 1; grid-row: 3; }
89
+ #app #export-note { grid-column: 1; grid-row: 4; }
89
90
  }
90
91
  #graph { grid-row: 1; grid-column: 1; overflow: auto; position: relative; }
91
92
  #inspect { grid-row: 1; grid-column: 2; border-left: 1px solid var(--rule); background: var(--panel);
@@ -831,6 +832,11 @@
831
832
  wears the managed edge its new owner paints everything with. */
832
833
  #graph [data-node-id].carved rect:first-of-type { stroke: var(--managed); stroke-width: 2; }
833
834
 
835
+ /* #824: behold export --note, the line a static page shows at its foot (web/export-note.js). */
836
+ #export-note { grid-column: 1 / 3; grid-row: 3; margin: 0; padding: var(--s3) var(--s4); border-top: 1px solid var(--rule);
837
+ background: var(--panel); color: var(--ink2); font: var(--t-body)/1.45 var(--font-ui); text-align: center; }
838
+ #export-note[hidden] { display: none; }
839
+ #export-note code { white-space: nowrap; font-family: var(--font-mono); color: var(--fg); background: var(--well); padding: 1px var(--s1); border-radius: var(--r-ctl); }
834
840
  #nowline { grid-column: 1 / 3; grid-row: 2; margin: 0; max-height: 160px; overflow: auto; display: none;
835
841
  background: var(--well); border-top: 1px solid var(--rule); padding: var(--s3) var(--s4);
836
842
  font: var(--t-caption)/1.6 var(--font-mono); color: var(--fg); white-space: pre-wrap; }
@@ -973,6 +979,7 @@
973
979
  </aside>
974
980
  <button id="inspect-reopen" title="Show inspect panel">Inspect ‹</button>
975
981
  <pre id="nowline"></pre>
982
+ <p id="export-note" hidden></p>
976
983
  </div>
977
984
  <!-- The floating control panel (see the #panel CSS comment above). The
978
985
  View tab keeps stable slots (#panel-zoom / #panel-viewtools /
package/web/view-url.js CHANGED
@@ -172,6 +172,31 @@ export function refusalLine(refused) {
172
172
  return "from the link: " + refused.map((r) => `${r.key}=${r.value} not opened, ${r.reason}`).join("; ");
173
173
  }
174
174
 
175
+ /**
176
+ * #827: the view a static export opens on, `behold export --open-env` and
177
+ * `--open-zoom`, as its manifest's `opening` carries them. A link's own query
178
+ * wins over it, key by key, so a shared link still opens where it points.
179
+ * Only a string `env` and `zoom` are taken; settleView checks them as it
180
+ * checks a link's.
181
+ */
182
+ export function withOpening(opening, want) {
183
+ const o = {};
184
+ if (opening && typeof opening === "object") {
185
+ if (typeof opening.env === "string" && opening.env) o.env = opening.env;
186
+ if (typeof opening.zoom === "string" && opening.zoom) o.zoom = opening.zoom;
187
+ }
188
+ return { ...o, ...(want || {}) };
189
+ }
190
+
191
+ /** #827: the env a load with no `env` parameter gives: the export's opening
192
+ * env when it names one, else the env behold was started with. writeViewQuery
193
+ * takes it as `defaults.env`, so picking the source graph in such a bundle
194
+ * writes `env=` and a reload keeps it. */
195
+ export function defaultEnv(opening, currentEnv) {
196
+ if (opening && typeof opening.env === "string" && opening.env) return opening.env;
197
+ return currentEnv || null;
198
+ }
199
+
175
200
  function listOr(xs) {
176
201
  const a = (xs || []).filter(Boolean);
177
202
  if (!a.length) return "nothing";