@intentius/behold 0.29.43 → 0.29.44

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.
Files changed (65) hide show
  1. package/AGENTS.md +77 -0
  2. package/dist/cli.js +3969 -1918
  3. package/package.json +1 -1
  4. package/web/app.js +1452 -73
  5. package/web/carve-narration.js +33 -1
  6. package/web/chant-live-pace.js +138 -0
  7. package/web/chant-live-pace.test.js +116 -0
  8. package/web/chant-pr-marks.js +417 -39
  9. package/web/chant-pr-marks.test.js +208 -4
  10. package/web/collision-marks.js +124 -0
  11. package/web/collision-marks.test.js +89 -0
  12. package/web/cone.js +269 -0
  13. package/web/cone.test.js +213 -0
  14. package/web/dots-live.test.js +151 -1
  15. package/web/dots-lod.js +20 -0
  16. package/web/dots-lod.test.js +19 -1
  17. package/web/dots-scene.js +110 -10
  18. package/web/dots.js +144 -31
  19. package/web/embed.js +1 -1
  20. package/web/event-help-modal.js +85 -3
  21. package/web/event-help-modal.test.js +85 -1
  22. package/web/feature-flags.js +143 -0
  23. package/web/feature-flags.test.js +96 -0
  24. package/web/index.html +33 -0
  25. package/web/kiosk-carve.js +59 -6
  26. package/web/kiosk-event-help-ui.js +150 -19
  27. package/web/kiosk-event-help.js +102 -15
  28. package/web/kiosk-event-help.test.js +58 -1
  29. package/web/kiosk-metrics.js +4 -3
  30. package/web/kiosk-runs.js +8 -5
  31. package/web/kiosk-shot.js +157 -3
  32. package/web/kiosk-shot.test.js +223 -1
  33. package/web/kiosk-source.js +43 -0
  34. package/web/kiosk-source.test.js +39 -0
  35. package/web/kiosk-story-gate.test.js +44 -0
  36. package/web/kiosk-track.js +312 -0
  37. package/web/kiosk-track.test.js +148 -0
  38. package/web/kiosk-unknown-step.test.js +58 -0
  39. package/web/kiosk-vendor.js +71 -4
  40. package/web/kiosk-vendor.test.js +103 -3
  41. package/web/kiosk-watch.js +154 -1
  42. package/web/kiosk-watch.test.js +53 -1
  43. package/web/kiosk.html +57 -22
  44. package/web/kiosk.js +566 -53
  45. package/web/kiosk.test.js +2 -1
  46. package/web/small-stage.test.js +150 -0
  47. package/web/terragucci-blocked.test.js +192 -0
  48. package/web/terragucci-change.js +197 -17
  49. package/web/terragucci-components-live.js +189 -13
  50. package/web/terragucci-live-pace.js +92 -0
  51. package/web/terragucci-wave-results.test.js +125 -0
  52. package/web/terralith.html +7 -7
  53. package/web/tg-outside.js +124 -0
  54. package/web/tg-outside.test.js +100 -0
  55. package/web/tg-read-pills.js +122 -0
  56. package/web/tg-read-pills.test.js +117 -0
  57. package/web/theme.js +13 -1
  58. package/web/theme.test.js +21 -1
  59. package/web/tooltip.js +19 -7
  60. package/web/tooltip.test.js +15 -0
  61. package/web/tours/terralith.json +4 -4
  62. package/web/trunk-lane.test.js +1 -1
  63. package/web/view-url.js +8 -2
  64. package/web/why.js +129 -1
  65. package/web/why.test.js +113 -1
@@ -0,0 +1,92 @@
1
+ // behold#741: a terragucci apply played at the pace chant's is (web/chant-live-pace.js).
2
+ //
3
+ // /api/terragucci/progress moves per wave: each read of the run view says
4
+ // where every wave stands. On a fast estate two reads apart can take a wave
5
+ // from queued to applied, or two waves at once, and the graph would jump.
6
+ // This pacer keeps the waves' changes in the order the reads gave them and
7
+ // shows them one at a time: a wave shows applying for at least `apply` ms,
8
+ // then its outcome for at least `done` ms, before the next wave's change
9
+ // shows. A wave seen going straight from queued to applied or failed is
10
+ // shown applying first: it did apply between the two reads. Once the run
11
+ // view stops moving (`watching` false) the rest plays at the catch-up pace.
12
+ //
13
+ // - A run first seen (a reload, a late viewer) shows as it stands, with no replay.
14
+ // - Only for a kiosk telling a chapter-carrying scenario; every other view
15
+ // reads the progress as it came.
16
+ //
17
+ // Pure apart from the clock it is given.
18
+
19
+ import { PACE } from "./chant-live-pace.js";
20
+
21
+ export { PACE };
22
+
23
+ const SETTLED = new Set(["applied", "failed", "refused", "blocked"]);
24
+ const RAN = new Set(["applied", "failed"]);
25
+
26
+ /** A run view's key: a new commit's run (the fix's apply) plays from its own start. */
27
+ const keyOf = (p) => `${(p.run && p.run.project) || ""}|${(p.run && p.run.commit) || ""}`;
28
+
29
+ /**
30
+ * A pacer. `progress(p)` answers the progress as it shows now, its waves'
31
+ * states held back to the pace; `pending` says whether more is still to come.
32
+ */
33
+ export function createProgressPacer({ now = () => Date.now(), pace = PACE } = {}) {
34
+ const runs = new Map();
35
+ let pending = false;
36
+ const progress = (p) => {
37
+ pending = false;
38
+ if (!p || p.error || !p.run || !p.run.present || !Array.isArray(p.states) || !p.states.length) return p;
39
+ const key = keyOf(p);
40
+ let st = runs.get(key);
41
+ const waves = [...p.states].sort((a, b) => a.number - b.number);
42
+ if (!st) {
43
+ // A wave first seen applying started then, as far as the view knows: its outcome waits its dwell from now.
44
+ const t0 = now();
45
+ st = { target: new Map(waves.map((w) => [w.number, w.state])), shown: new Map(waves.map((w) => [w.number, w.state])), queue: [], waveStart: new Map(waves.filter((w) => w.state === "applying").map((w) => [w.number, t0])), lastSettleAt: null };
46
+ runs.set(key, st);
47
+ if (runs.size > 8) runs.delete(runs.keys().next().value);
48
+ return p;
49
+ }
50
+ // The reads' changes, in wave order, onto the queue.
51
+ for (const w of waves) {
52
+ if (st.target.get(w.number) === w.state) continue;
53
+ const was = st.target.get(w.number);
54
+ st.target.set(w.number, w.state);
55
+ if (RAN.has(w.state) && was !== "applying") st.queue.push({ wave: w.number, state: "applying" });
56
+ st.queue.push({ wave: w.number, state: w.state });
57
+ }
58
+ const t = now();
59
+ const dwellApply = p.watching === false ? pace.catchApply : pace.apply;
60
+ const dwellDone = p.watching === false ? pace.catchDone : pace.done;
61
+ while (st.queue.length) {
62
+ const e = st.queue[0];
63
+ if (e.state === "applying") {
64
+ if (st.lastSettleAt !== null && t - st.lastSettleAt < dwellDone) break;
65
+ st.waveStart.set(e.wave, t);
66
+ } else if (SETTLED.has(e.state)) {
67
+ const started = st.waveStart.get(e.wave);
68
+ if (started !== undefined && t - started < dwellApply) break;
69
+ if (started === undefined && st.lastSettleAt !== null && t - st.lastSettleAt < dwellDone) break;
70
+ st.lastSettleAt = t;
71
+ }
72
+ st.shown.set(e.wave, e.state);
73
+ st.queue.shift();
74
+ }
75
+ pending = st.queue.length > 0;
76
+ if (!pending) return p;
77
+ return { ...p, states: p.states.map((w) => (st.shown.has(w.number) && st.shown.get(w.number) !== w.state ? { ...w, state: st.shown.get(w.number) } : w)), paced: true };
78
+ };
79
+ return {
80
+ progress,
81
+ get pending() {
82
+ return pending;
83
+ },
84
+ };
85
+ }
86
+
87
+ /** The waves as the kiosk's track ticks them: chant's words for a terragucci wave's state. */
88
+ const TICK = { "not-started": "waiting", planned: "waiting", waiting: "gated", applying: "running", applied: "applied", failed: "failed", refused: "gated", blocked: "blocked" };
89
+ export function trackWaves(progress) {
90
+ if (!progress || progress.error || !Array.isArray(progress.states)) return null;
91
+ return [...progress.states].sort((a, b) => a.number - b.number).map((w) => ({ wave: w.number, state: TICK[w.state] || "waiting" }));
92
+ }
@@ -0,0 +1,125 @@
1
+ // behold#751: a terragucci wave's result is worded from its own report, not
2
+ // its Forgejo job's status. terragucci ends the job of a wave that applied
3
+ // what it planned and blocked the rest as a failure (terragucci#1161), so the
4
+ // commit status isn't green while roots are unapplied. On the fan-out kiosks
5
+ // that read "wave 3 failed" in the fix chapter, where cluster-a broke in wave
6
+ // 2 and wave 3 applied cluster-b's six apps and blocked cluster-a's six.
7
+ //
8
+ // The reports and runs are a real fan-out-choudoufu cycle's
9
+ // (src/__fixtures__/terragucci-wave-results: run 6745, the change's merge,
10
+ // and 6748, the fix's), read the way /api/terragucci reads them.
11
+ import { readFileSync } from "node:fs";
12
+ import { join } from "node:path";
13
+ import { beforeAll, describe, expect, it } from "vitest";
14
+ import { readTerragucci } from "../src/terragucci-reports.ts";
15
+ import { terragucciSource } from "../src/terragucci-source.ts";
16
+ import { cycleFacts, ehSnapshot, storyTrail } from "./kiosk-event-help.js";
17
+ import { componentMarks, reportStatus } from "./terragucci-components-live.js";
18
+ import { resultWords, waveResultOf } from "./terragucci-change.js";
19
+
20
+ const FIXTURE = join(import.meta.dirname, "..", "src", "__fixtures__", "terragucci-wave-results");
21
+ const CHANGE = "2a615596a4f0ed954bdcaa83f77e575eaf2cb5ab";
22
+ const FIX = "5cfbdb79c7a45d4b4d80e4c8e2a200afcc9c225e";
23
+ const FIX_PR = "57fcc6ed000000000000000000000000000000aa";
24
+ const APPS_A = ["app-01", "app-02", "app-03", "app-04", "app-05", "app-06"];
25
+ const APPS_B = ["app-07", "app-08", "app-09", "app-10", "app-11", "app-12"];
26
+ const run6745 = JSON.parse(readFileSync(join(FIXTURE, "run-6745.json"), "utf8"));
27
+ const run6748 = JSON.parse(readFileSync(join(FIXTURE, "run-6748.json"), "utf8"));
28
+ // The fix's pull request's plan run: its apply jobs skipped.
29
+ const run6746 = { schema: "demo.run/v1", id: 6746, commit: FIX_PR, cycle: 605, pull: 56, status: "success", jobs: [1, 2, 3].map((n) => ({ name: `apply-wave-${n}`, status: "skipped", steps: [] })) };
30
+ const waves = [
31
+ { job: "apply-wave-1", wave: 1, roots: ["network"] },
32
+ { job: "apply-wave-2", wave: 2, roots: ["cluster-a", "cluster-b"] },
33
+ { job: "apply-wave-3", wave: 3, roots: [...APPS_A, ...APPS_B] },
34
+ ];
35
+ const demo = (step, more = {}) => ({ cycle: 605, scenario: "fan-out-choudoufu", step, label: "", started_at: "2026-10-19T01:57:00Z", pull: 55, commit: CHANGE, ...more });
36
+ // The run views as terragucci wrote them: the change's (wave 2 failed, wave 3 applied) and the fix's.
37
+ const runView = (commit, updated, states) => ({ run: { present: true, commit, updated }, states: states.map(([number, state, roots]) => ({ number, state, roots, changed: roots, totals: {} })), reads: [] });
38
+ const changeView = runView(CHANGE, "2026-10-19T01:58:52.600Z", [[1, "applied", ["network"]], [2, "failed", ["cluster-a", "cluster-b"]], [3, "applied", [...APPS_A, ...APPS_B]]]);
39
+ const fixView = runView(FIX, "2026-10-19T02:01:47.800Z", [[1, "applied", ["network"]], [2, "applied", ["cluster-a", "cluster-b"]], [3, "applied", [...APPS_A, ...APPS_B]]]);
40
+
41
+ let answer;
42
+ beforeAll(async () => {
43
+ const structural = { validation: { by: "structural" }, check: (_n, doc) => (doc && typeof doc === "object" ? undefined : "not an object") };
44
+ const r = await readTerragucci(terragucciSource(FIXTURE), { validator: structural });
45
+ answer = { roots: [], pull_request: null, results: r.results };
46
+ });
47
+
48
+ const facts = (snap) => cycleFacts(ehSnapshot({ waves, ...snap }));
49
+ const byId = (fs, tail) => fs.find((f) => f.id.endsWith(tail));
50
+ const failedWaves = (fs) => fs.filter((f) => f.kind === "failed").map((f) => f.subjects.wave);
51
+
52
+ describe("a wave's result from its report (behold#751)", () => {
53
+ it("words run 6745's wave 3 as its report does, and its wave 2 as failed", () => {
54
+ expect(resultWords(waveResultOf(answer, CHANGE, 3))).toBe("applied 6, 6 blocked by cluster-a");
55
+ expect(resultWords(waveResultOf(answer, CHANGE.slice(0, 8), 2))).toBe("1 failed, 1 applied");
56
+ expect(resultWords(waveResultOf(answer, FIX, 3))).toBe("applied");
57
+ // A report finished before the job started is an earlier run's: the job's status speaks.
58
+ expect(waveResultOf(answer, CHANGE, 3, { after: "2026-10-19T02:30:00Z" })).toBeNull();
59
+ expect(waveResultOf(answer, CHANGE, 3, { after: run6745.jobs.find((j) => j.name === "apply-wave-3").started_at })).not.toBeNull();
60
+ expect(waveResultOf({ roots: [] }, CHANGE, 3)).toBeNull();
61
+ });
62
+ });
63
+
64
+ describe("event-help: the failure chapter and the fix chapter (behold#751)", () => {
65
+ it("in the failure chapter, wave 2 failed and wave 3 applied 6 with 6 blocked, never 'wave 3 failed'", () => {
66
+ const fs = facts({ demo: demo("failed"), answer, progress: changeView, runDoc: run6745, runDocs: [run6745] });
67
+ expect(failedWaves(fs)).toEqual([2]);
68
+ expect(byId(fs, "|w2|failed")).toMatchObject({ text: "wave 2 failed", critical: true });
69
+ expect(byId(fs, "|w3|blocked")).toMatchObject({ kind: "blocked", text: "wave 3 applied 6, 6 blocked by cluster-a", critical: false, subjects: { wave: 3, job: "apply-wave-3", run: 6745 } });
70
+ // The run view's "wave 3 applied" is the blocked fact's to say, with what it held back.
71
+ expect(byId(fs, "|w3|applied")).toBeUndefined();
72
+ expect(storyTrail(fs).map((f) => f.text)).toEqual(expect.arrayContaining(["wave 2 failed", "wave 3 applied 6, 6 blocked by cluster-a"]));
73
+ });
74
+
75
+ it("in the fix chapter, the pill and trail say the same of the change's run, now an earlier one", () => {
76
+ const fs = facts({ demo: demo("planned", { pull: 56, commit: FIX_PR }), answer, progress: changeView, runDoc: run6746, runDocs: [run6745, run6746] });
77
+ expect(failedWaves(fs)).toEqual([2]);
78
+ expect(fs.some((f) => f.text === "wave 3 failed")).toBe(false);
79
+ expect(byId(fs, "|w3|blocked")).toMatchObject({ text: "wave 3 applied 6, 6 blocked by cluster-a", subjects: { wave: 3, job: "apply-wave-3", run: 6745 } });
80
+ });
81
+
82
+ it("in the fix's apply, wave 3 runs again and applies", () => {
83
+ const fs = facts({ demo: demo("applied", { pull: 56, commit: FIX }), answer, progress: fixView, runDoc: run6748, runDocs: [run6745, run6746, run6748] });
84
+ expect(fs.some((f) => f.text === "wave 3 failed")).toBe(false);
85
+ expect(byId(fs, "|w3|rerun")).toMatchObject({ text: "wave 3 runs again" });
86
+ expect(byId(fs, "|w3|applied")).toMatchObject({ text: "wave 3 applied" });
87
+ });
88
+
89
+ it("falls back to the job's status where no report of the wave is read", () => {
90
+ const fs = facts({ demo: demo("failed"), answer: { roots: [] }, progress: changeView, runDoc: run6745, runDocs: [run6745] });
91
+ expect(failedWaves(fs)).toEqual([2, 3]);
92
+ const later = facts({ demo: demo("planned", { pull: 56, commit: FIX_PR }), answer: { roots: [] }, progress: changeView, runDoc: run6746, runDocs: [run6745, run6746] });
93
+ expect(failedWaves(later)).toEqual([2, 3]);
94
+ });
95
+ });
96
+
97
+ describe("the wave box's title (behold#751)", () => {
98
+ const facets = {
99
+ jobs: [
100
+ { component: "network", jobName: "apply-wave-1", wave: 1 },
101
+ { component: "cluster-a", jobName: "apply-wave-2", wave: 2 },
102
+ { component: "cluster-b", jobName: "apply-wave-2", wave: 2 },
103
+ ...[...APPS_A, ...APPS_B].map((c) => ({ component: c, jobName: "apply-wave-3", wave: 3 })),
104
+ ],
105
+ };
106
+ const runs = { doc: { runs: [{ id: 6745, commit: CHANGE, jobs: run6745.jobs.map(({ name, status }) => ({ name, status })) }] } };
107
+
108
+ it("says wave 3 applied 6 with 6 blocked, and wave 2 failed, on run 6745", () => {
109
+ const m = componentMarks(answer, changeView, facets, { runs });
110
+ expect(m.waves[3].title).toBe("apply-wave-3 · applied 6, 6 blocked by cluster-a");
111
+ expect(m.waves[3].tone).toBe("wait");
112
+ expect(m.waves[2].title).toBe("apply-wave-2 · failed");
113
+ expect(m.waves[2].tone).toBe("bad");
114
+ expect(m.waves[1].title).toBe("apply-wave-1 · succeeded");
115
+ });
116
+
117
+ it("keeps the job's status with no report of the wave, and for any job that did not fail", () => {
118
+ expect(componentMarks({ roots: [] }, changeView, facets, { runs }).waves[3].title).toBe("apply-wave-3 · failed");
119
+ const ok = { status: "success", words: "succeeded", tone: "ok", run: 6748 };
120
+ expect(reportStatus(ok, waveResultOf(answer, CHANGE, 3))).toBe(ok);
121
+ const failed = { status: "failure", words: "failed", tone: "bad", run: 6745 };
122
+ expect(reportStatus(failed, waveResultOf(answer, CHANGE, 2))).toBe(failed);
123
+ expect(reportStatus(failed, null)).toBe(failed);
124
+ });
125
+ });
@@ -9,14 +9,14 @@
9
9
  href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Ccircle cx='8' cy='8' r='6' fill='none' stroke='%23a6adc8' stroke-width='1.6'/%3E%3Ccircle cx='8' cy='8' r='2.2' fill='%23a6adc8'/%3E%3C/svg%3E"
10
10
  />
11
11
  <style>
12
- /* The pre-paint fallback: Sea Shells' tokens (KIOSK_THEME in theme.js), which initTheme() replaces with the viewer's theme. */
12
+ /* The pre-paint fallback: Box's tokens (KIOSK_THEME in theme.js, behold#758), which initTheme() replaces with the viewer's theme. */
13
13
  :root {
14
- --bg: #09141b; --panel: #1c2325; --line: #2c2e2d; --fg: #deb88d; --muted: #91877a; --ink2: #ceb395;
15
- --edge: #4d483f; --managed: #027c9b; --foreign: #fca02f; --pending: #1e4950;
16
- --degraded: #d15123; --neutral: #695e4e; --runtime: #50a3b5;
17
- --rule: #3d4142; --focus: #364548; --active: #243235; --well: #01070d; --shadow: #010304;
18
- --surface-box: #161a1d; --surface-pane-a: #1c2023; --surface-pane-b: #222629; --soft: #deb88d; --muted-ink: #9a9083;
19
- --managed-ink: #0e7f9e; --foreign-ink: #fca02f; --pending-ink: #567b82; --runtime-ink: #50a3b5;
14
+ --bg: #141d2b; --panel: #213027; --line: #2e3d2a; --fg: #9fef00; --muted: #7d9e5a; --ink2: #97d742;
15
+ --edge: #40601d; --managed: #19cb00; --foreign: #cecb00; --pending: #0d73cc;
16
+ --degraded: #cc0403; --neutral: #537c18; --runtime: #0dcdcd;
17
+ --rule: #515e48; --focus: #577597; --active: #223f47; --well: #070f1c; --shadow: #030406;
18
+ --surface-box: #20242a; --surface-pane-a: #262a30; --surface-pane-b: #2c3036; --soft: #9fef00; --muted-ink: #8aaa67;
19
+ --managed-ink: #19cb00; --foreign-ink: #cecb00; --pending-ink: #2b83da; --runtime-ink: #0dcdcd;
20
20
  --font-ui: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
21
21
  --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
22
22
  --r-ctl: 6px; --t-body: 13px;
@@ -0,0 +1,124 @@
1
+ // behold#743: an apply made outside the pipeline, beside the pipeline's run
2
+ // of the same estate. terragucci#1163's fan-out-choudoufu has an operator run
3
+ // `choudoufu apply -target=aws_sqs_queue.alarms` on app-01's estate while the
4
+ // pipeline's wave 3 applies app-01. choudoufu keeps a record per resource and
5
+ // no state file to lock, so both land and neither waits. demo.json's
6
+ // `outside` says so at each step of that beat ({ who, estate, command, state,
7
+ // started_at, ended_at, resources, log }, null otherwise); the kiosk frame
8
+ // draws it as a mark on the estate's card, tagged "outside the pipeline".
9
+ //
10
+ // Pure: which card the estate is, and the mark's words and tone. app.js
11
+ // places and draws it.
12
+
13
+ /** The tag that sets the mark apart from the pipeline's own marks. */
14
+ export const OUTSIDE_TAG = "outside the pipeline";
15
+
16
+ /**
17
+ * The card an outside apply's `estate` is: a card id or root name that is
18
+ * the estate itself, else the one whose name the estate ends with after a
19
+ * prefix ("fo-app-01" is app-01: choudoufu names a root's estate with the
20
+ * scenario's prefix). Null when none is, or more than one could be.
21
+ */
22
+ export function outsideCard(estate, ids) {
23
+ if (typeof estate !== "string" || !estate) return null;
24
+ const list = [...new Set((ids || []).filter((i) => typeof i === "string" && i))];
25
+ if (list.includes(estate)) return estate;
26
+ const tail = list.filter((i) => estate.length > i.length && estate.endsWith(i) && /[-_./:]/.test(estate[estate.length - i.length - 1]));
27
+ if (tail.length === 1) return tail[0];
28
+ // The longest wins when one name ends another ("app-1" and "x-app-1"): a tie is no answer.
29
+ const longest = tail.sort((a, b) => b.length - a.length);
30
+ return longest.length > 1 && longest[0].length > longest[1].length ? longest[0] : null;
31
+ }
32
+
33
+ /** The pipeline's states for a card that mean its own apply of the estate has landed. */
34
+ const LANDED = new Set(["applied", "applied-earlier", "already-applied"]);
35
+
36
+ /**
37
+ * The mark's model. `outside` is demo.json's; `pipeline` the card's state as
38
+ * the pipeline's run draws it now ("applying", "applied", "planned"...), or
39
+ * null; `card` the card's name; `change` what the pipeline's plan changes on
40
+ * it ("1 to change"), when the marks say; `wave` the wave that applies it.
41
+ *
42
+ * - `lines`: the mark's lines, top to bottom, each `{ text, kind }`: `who`
43
+ * (who ran it and its state), `command`, `resources`, `pipeline` (what the
44
+ * pipeline does to the same estate meanwhile), `landed` (once both ended:
45
+ * both changes are on the estate).
46
+ * - `tone`: busy while it applies, ok once applied, bad when it failed (TG_TONE's keys).
47
+ * - `pulse`: it applies now.
48
+ * - `both`: it and the pipeline's apply of the card both landed, and neither waited.
49
+ */
50
+ export function outsideModel(outside, { pipeline = null, card = null, change = null, wave = null } = {}) {
51
+ if (!outside || typeof outside !== "object") return null;
52
+ const who = outside.who || "someone";
53
+ const name = card || outside.estate;
54
+ const state = outside.state;
55
+ const res = Array.isArray(outside.resources) ? outside.resources.filter((r) => typeof r === "string" && r) : [];
56
+ const added = res.length ? `+ ${res.slice(0, 2).join(", ")}${res.length > 2 ? ` and ${res.length - 2} more` : ""}` : null;
57
+ const command = { text: `$ ${outside.command || "an apply"}`, kind: "command" };
58
+ const both = state === "applied" && LANDED.has(pipeline);
59
+ const tone = state === "applying" ? "busy" : state === "failed" ? "bad" : "ok";
60
+ if (both) {
61
+ // Both changes on the estate, each said: the pipeline's, then the one made outside it.
62
+ const lines = [
63
+ { text: `both landed on ${name}, and neither waited`, kind: "landed" },
64
+ { text: `${Number.isInteger(wave) ? `the pipeline's wave ${wave}` : "the pipeline"}: its planned change${change ? `, ${change}` : ""}`, kind: "pipeline" },
65
+ { text: `${who}: ${added || "its apply"}`, kind: "resources" },
66
+ command,
67
+ ];
68
+ return { tag: OUTSIDE_TAG, lines, tone, pulse: false, both, card: name };
69
+ }
70
+ const lines = [];
71
+ if (state === "applying") lines.push({ text: `${who} is applying to ${name}`, kind: "who" });
72
+ else if (state === "failed") lines.push({ text: `${who}'s apply to ${name} failed`, kind: "who" });
73
+ else lines.push({ text: `${who}'s apply to ${name} landed`, kind: "who" });
74
+ lines.push(command);
75
+ if (added) lines.push({ text: added, kind: "resources" });
76
+ const p = pipelineWords(pipeline, name, wave);
77
+ if (p) lines.push({ text: p, kind: "pipeline" });
78
+ return { tag: OUTSIDE_TAG, lines, tone, pulse: state === "applying", both, card: name };
79
+ }
80
+
81
+ /**
82
+ * What the pipeline does to the same estate, said beside the outside apply. Its wave by number, which the wave box's
83
+ * title and its job's status ("wave 3 · running") say too: the card's own words follow the run view, which may still
84
+ * say queued while the wave's job applies it.
85
+ */
86
+ function pipelineWords(pipeline, name, wave) {
87
+ const its = Number.isInteger(wave) ? `the pipeline's wave ${wave}` : "the pipeline";
88
+ if (LANDED.has(pipeline)) return `${its} applied ${name} too, and did not wait`;
89
+ if (pipeline === "applying") return `${its} applies ${name} at the same time`;
90
+ if (pipeline === "failed") return `${its} failed to apply ${name}`;
91
+ if (pipeline === "blocked") return null;
92
+ return `${its} applies ${name} too`;
93
+ }
94
+
95
+ /**
96
+ * Where the mark goes around the card's box `card` ({ x, y, x2, y2 }), a
97
+ * mark `w` by `h`: above, below, left or right of it, a few gaps out, slid
98
+ * along the side. Each spot with its rect `r` and how far it sits from the
99
+ * card (`far`); the caller scores them against what is drawn around.
100
+ */
101
+ export function outsideSpots(card, w, h, { gaps = [12, 28, 48], slides = [0, -0.25, 0.25, -0.5, 0.5] } = {}) {
102
+ const out = [];
103
+ const cx = (card.x + card.x2) / 2;
104
+ const cy = (card.y + card.y2) / 2;
105
+ for (const side of ["top", "left", "bottom", "right"]) {
106
+ for (const g of gaps) {
107
+ for (const f of slides) {
108
+ let x;
109
+ let y;
110
+ if (side === "top" || side === "bottom") {
111
+ x = cx - w / 2 + f * w;
112
+ y = side === "top" ? card.y - g - h : card.y2 + g;
113
+ } else {
114
+ x = side === "left" ? card.x - g - w : card.x2 + g;
115
+ y = cy - h / 2 + f * h;
116
+ }
117
+ const r = { x, y, x2: x + w, y2: y + h };
118
+ const far = Math.hypot(Math.max(r.x - card.x2, 0, card.x - r.x2), Math.max(r.y - card.y2, 0, card.y - r.y2));
119
+ out.push({ r, side, gap: g, far });
120
+ }
121
+ }
122
+ }
123
+ return out;
124
+ }
@@ -0,0 +1,100 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { OUTSIDE_TAG, outsideCard, outsideModel, outsideSpots } from "./tg-outside.js";
3
+
4
+ // behold#743: terragucci#1163's fan-out-choudoufu, chapter 3: an operator applies a queue to app-01's estate (fo-app-01)
5
+ // while the pipeline's wave 3 applies app-01.
6
+ const ids = ["network", "cluster-a", "cluster-b", ...Array.from({ length: 12 }, (_, i) => `app-${String(i + 1).padStart(2, "0")}`)];
7
+ const outside = (over = {}) => ({
8
+ who: "an operator",
9
+ estate: "fo-app-01",
10
+ command: "choudoufu apply -target=aws_sqs_queue.alarms",
11
+ state: "applying",
12
+ started_at: "2026-10-19T00:31:14Z",
13
+ ended_at: null,
14
+ resources: ["aws_sqs_queue.alarms"],
15
+ log: [],
16
+ ...over,
17
+ });
18
+ const texts = (m) => m.lines.map((l) => l.text);
19
+
20
+ describe("the card an outside apply is on (behold#743)", () => {
21
+ it("is the card the estate names, or the one its name ends with after a prefix", () => {
22
+ expect(outsideCard("app-01", ids)).toBe("app-01");
23
+ expect(outsideCard("fo-app-01", ids)).toBe("app-01");
24
+ expect(outsideCard("fo-cluster-a", ids)).toBe("cluster-a");
25
+ });
26
+ it("is none when no card is it, or a suffix without a separator", () => {
27
+ expect(outsideCard("fo-app-13", ids)).toBe(null);
28
+ expect(outsideCard("xapp-01", ids)).toBe(null);
29
+ expect(outsideCard("", ids)).toBe(null);
30
+ expect(outsideCard(null, ids)).toBe(null);
31
+ expect(outsideCard("fo-app-01", [])).toBe(null);
32
+ });
33
+ it("takes the longest name when one name ends another", () => {
34
+ expect(outsideCard("fo-x-app-01", ["app-01", "x-app-01"])).toBe("x-app-01");
35
+ expect(outsideCard("fo-app-01", ["app-01", "app-01"])).toBe("app-01");
36
+ });
37
+ });
38
+
39
+ describe("the outside apply's mark (behold#743)", () => {
40
+ it("is nothing without one", () => {
41
+ expect(outsideModel(null)).toBe(null);
42
+ expect(outsideModel(undefined, { pipeline: "applying" })).toBe(null);
43
+ });
44
+ it("says who, the command, the resources and what the pipeline does meanwhile, while it applies", () => {
45
+ const m = outsideModel(outside(), { pipeline: "applying", card: "app-01", wave: 3 });
46
+ expect(m.tag).toBe(OUTSIDE_TAG);
47
+ expect(m.tag).toBe("outside the pipeline");
48
+ expect(texts(m)).toEqual(["an operator is applying to app-01", "$ choudoufu apply -target=aws_sqs_queue.alarms", "+ aws_sqs_queue.alarms", "the pipeline's wave 3 applies app-01 at the same time"]);
49
+ expect(m).toMatchObject({ tone: "busy", pulse: true, both: false, card: "app-01" });
50
+ });
51
+ it("says the pipeline's wave is coming before it applies, and that it landed without waiting once it has", () => {
52
+ expect(texts(outsideModel(outside(), { pipeline: "not-started", card: "app-01", wave: 3 })).at(-1)).toBe("the pipeline's wave 3 applies app-01 too");
53
+ expect(texts(outsideModel(outside(), { pipeline: "applied", card: "app-01", wave: 3 })).at(-1)).toBe("the pipeline's wave 3 applied app-01 too, and did not wait");
54
+ // Without a wave, the pipeline.
55
+ expect(texts(outsideModel(outside(), { pipeline: "applying", card: "app-01" })).at(-1)).toBe("the pipeline applies app-01 at the same time");
56
+ expect(texts(outsideModel(outside(), { pipeline: "blocked", card: "app-01" }))).toHaveLength(3);
57
+ });
58
+ it("says both changes landed, with no lock or wait, once both ended", () => {
59
+ const m = outsideModel(outside({ state: "applied", ended_at: "2026-10-19T00:31:42Z" }), { pipeline: "applied", card: "app-01", change: "1 to change", wave: 3 });
60
+ expect(m).toMatchObject({ tone: "ok", pulse: false, both: true });
61
+ expect(texts(m)).toEqual(["both landed on app-01, and neither waited", "the pipeline's wave 3: its planned change, 1 to change", "an operator: + aws_sqs_queue.alarms", "$ choudoufu apply -target=aws_sqs_queue.alarms"]);
62
+ expect(texts(m).join(" ")).not.toMatch(/\block(ed)?\b|waiting|blocked/);
63
+ // A fix's later step reads the pipeline's earlier apply as landed too.
64
+ const later = outsideModel(outside({ state: "applied" }), { pipeline: "applied-earlier", card: "app-01" });
65
+ expect(later.both).toBe(true);
66
+ expect(texts(later)[1]).toBe("the pipeline: its planned change");
67
+ });
68
+ it("says it landed alone while the pipeline's apply has not", () => {
69
+ const m = outsideModel(outside({ state: "applied" }), { pipeline: "applying", card: "app-01" });
70
+ expect(m.both).toBe(false);
71
+ expect(texts(m)[0]).toBe("an operator's apply to app-01 landed");
72
+ });
73
+ it("says a failure in its tone", () => {
74
+ const m = outsideModel(outside({ state: "failed" }), { pipeline: "applied", card: "app-01" });
75
+ expect(m).toMatchObject({ tone: "bad", pulse: false, both: false });
76
+ expect(texts(m)[0]).toBe("an operator's apply to app-01 failed");
77
+ });
78
+ it("names the estate when no card is given, and counts resources past two", () => {
79
+ const m = outsideModel(outside({ resources: ["a.b", "c.d", "e.f", "g.h"] }));
80
+ expect(texts(m)[0]).toBe("an operator is applying to fo-app-01");
81
+ expect(texts(m)).toContain("+ a.b, c.d and 2 more");
82
+ expect(texts(outsideModel(outside({ resources: [] }))).some((t) => t.startsWith("+"))).toBe(false);
83
+ });
84
+ });
85
+
86
+ describe("where the mark may go (behold#743)", () => {
87
+ const card = { x: 100, y: 100, x2: 260, y2: 180 };
88
+ it("offers spots on every side, none on the card", () => {
89
+ const spots = outsideSpots(card, 300, 90);
90
+ expect(new Set(spots.map((s) => s.side))).toEqual(new Set(["top", "left", "bottom", "right"]));
91
+ const hits = (r) => r.x < card.x2 && r.x2 > card.x && r.y < card.y2 && r.y2 > card.y;
92
+ expect(spots.some((s) => hits(s.r))).toBe(false);
93
+ for (const s of spots) expect(s.r.x2 - s.r.x).toBe(300);
94
+ });
95
+ it("says how far each sits from the card", () => {
96
+ const top = outsideSpots(card, 300, 90, { gaps: [12], slides: [0] }).find((s) => s.side === "top");
97
+ expect(top.r).toEqual({ x: 30, y: -2, x2: 330, y2: 88 });
98
+ expect(top.far).toBe(12);
99
+ });
100
+ });
@@ -0,0 +1,122 @@
1
+ // behold#744: a terragucci read's words ("app-06 reads cluster-a's applied
2
+ // state") are no longer drawn for good, out in open ground. Each read's line
3
+ // stays; its pill sits at the reader's end and shows only while it matters:
4
+ // while someone points at the reader, the root it reads or the line, or, on a
5
+ // kiosk playing on its own, for a few seconds when the reader starts applying
6
+ // or fails or is blocked. This module says which reads those are and for how
7
+ // long; app.js draws them.
8
+ //
9
+ // Pure apart from the clock it is given.
10
+
11
+ /** How long a read's pill shows on its own, in ms; the fade is the last fifth of it. */
12
+ export const FLASH_MS = 6000;
13
+ /** At most this many pills show on their own at once: the newest win. */
14
+ export const FLASH_MAX = 3;
15
+ /**
16
+ * The reader states a pill shows for (its wave runs it, or it did not apply), most telling first: a failed root's read
17
+ * before its wave's, and those before the blocked apps that follow it. Seen first after a reload counts too: the kiosk
18
+ * reloads its frame at a new step (the step's focus is in its address), which is when the state matters.
19
+ */
20
+ const MATTERS = { failed: 0, applying: 1, blocked: 2 };
21
+
22
+ /** A read's key, one per line: reader and the root it reads. */
23
+ export const readKey = (e) => `${e.from}→${e.to}`;
24
+
25
+ /** A wave job's status that says the wave runs now (its job's, or the run view's after a re-run took it over). */
26
+ const RUNNING = new Set(["running", "applying"]);
27
+ /** A card's states that its running wave makes applying: the pull request's plan still shows until the run view moves. */
28
+ const NOT_YET = new Set(["planned", "not-started", "waiting"]);
29
+
30
+ /**
31
+ * Each reader root's state, from the marks the components zoom draws
32
+ * (componentMarks: `cards[component] = { root, wave, state }` and each
33
+ * wave's job status, paced as a story plays it) when there are, else
34
+ * rootStates' `roots[path] = { state }`. A card whose wave's job runs now
35
+ * reads applying, though the view still shows the plan it applies.
36
+ */
37
+ export function readerStates(marks, roots) {
38
+ const out = {};
39
+ for (const c of Object.values((marks && marks.cards) || {})) {
40
+ if (!c || !c.root) continue;
41
+ const w = marks.waves && marks.waves[c.wave];
42
+ const job = w && w.status ? w.status.status : null;
43
+ out[c.root] = NOT_YET.has(c.state) && RUNNING.has(job) ? "applying" : c.state;
44
+ }
45
+ if (roots) for (const [path, r] of Object.entries(roots)) if (!(path in out) && r) out[path] = r.state;
46
+ return out;
47
+ }
48
+
49
+ /**
50
+ * The reads whose pill shows on its own now. `live(edges, states)` keeps when
51
+ * each reader came into the state it is in, and answers `[{ key, age }]`
52
+ * (age in ms) for the reads whose reader came into applying, failed or
53
+ * blocked less than `hold` ms ago, newest first (then failed, applying,
54
+ * blocked), `max` at most.
55
+ */
56
+ export function createReadFlash({ now = () => Date.now(), hold = FLASH_MS, max = FLASH_MAX } = {}) {
57
+ const seen = new Map(); // root -> { state, at } (at null: nothing to show for it)
58
+ const live = (edges, states) => {
59
+ const t = now();
60
+ for (const root of new Set((edges || []).map((e) => e.from))) {
61
+ const s = (states && states[root]) || null;
62
+ const was = seen.get(root);
63
+ if (was && was.state === s) continue;
64
+ seen.set(root, { state: s, at: s in MATTERS ? t : null });
65
+ }
66
+ const out = [];
67
+ for (const e of edges || []) {
68
+ const w = seen.get(e.from);
69
+ if (!w || w.at === null || t - w.at >= hold) continue;
70
+ out.push({ key: readKey(e), age: t - w.at, rank: MATTERS[w.state] });
71
+ }
72
+ out.sort((a, b) => a.age - b.age || a.rank - b.rank || (a.key < b.key ? -1 : 1));
73
+ return out.slice(0, max).map(({ key, age }) => ({ key, age }));
74
+ };
75
+ return { live };
76
+ }
77
+
78
+ /**
79
+ * The reads a pointer on a root lights: the ones it makes and the ones made
80
+ * of it. On a read's own line, that read alone.
81
+ */
82
+ export function hotReads(edges, { root = null, key = null } = {}) {
83
+ if (key) return (edges || []).some((e) => readKey(e) === key) ? [key] : [];
84
+ if (!root) return [];
85
+ return (edges || []).filter((e) => e.from === root || e.to === root).map(readKey);
86
+ }
87
+
88
+ /**
89
+ * Where a pill goes beside the reader's card, `box` ({ x, y, x2, y2 }), for
90
+ * the line that leaves it at `p0`: just outside the side `p0` is on, slid
91
+ * along it, a few gaps out, each with how far it sits from `p0`. The caller
92
+ * scores them against the text and cards around; nearer is better.
93
+ */
94
+ export function pillSpots(box, p0, w, h, { gaps = [6, 18, 34], slides = [0, -0.3, 0.3, -0.5, 0.5] } = {}) {
95
+ const d = { top: Math.abs(p0.y - box.y), bottom: Math.abs(p0.y - box.y2), left: Math.abs(p0.x - box.x), right: Math.abs(p0.x - box.x2) };
96
+ const side = Object.keys(d).reduce((a, b) => (d[b] < d[a] ? b : a));
97
+ const out = [];
98
+ // The side the line leaves from first; the card's other sides after, farther round from p0.
99
+ const sides = [side, ...["top", "bottom", "left", "right"].filter((s) => s !== side)];
100
+ sides.forEach((s, i) => {
101
+ for (const g of gaps) {
102
+ for (const f of slides) {
103
+ let c;
104
+ if (s === "top" || s === "bottom") {
105
+ const x = (i === 0 ? p0.x : (box.x + box.x2) / 2) + f * w;
106
+ c = { x, y: s === "top" ? box.y - g - h / 2 : box.y2 + g + h / 2 };
107
+ } else {
108
+ const y = (i === 0 ? p0.y : (box.y + box.y2) / 2) + f * h * 2;
109
+ c = { x: s === "left" ? box.x - g - w / 2 : box.x2 + g + w / 2, y };
110
+ }
111
+ const r = { x: c.x - w / 2, y: c.y - h / 2, x2: c.x + w / 2, y2: c.y + h / 2 };
112
+ out.push({ c, r, side: s, gap: g, far: Math.hypot(Math.max(r.x - p0.x, 0, p0.x - r.x2), Math.max(r.y - p0.y, 0, p0.y - r.y2)), round: i });
113
+ }
114
+ }
115
+ });
116
+ return out;
117
+ }
118
+
119
+ /** The point on rect `r` nearest `p`: where a pill's leader meets it. */
120
+ export function nearestOn(r, p) {
121
+ return { x: Math.max(r.x, Math.min(p.x, r.x2)), y: Math.max(r.y, Math.min(p.y, r.y2)) };
122
+ }