@intentius/behold 0.29.57 → 0.30.1

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 (48) hide show
  1. package/AGENTS.md +388 -57
  2. package/README.md +67 -50
  3. package/demos.json +1 -1
  4. package/dist/cli.js +9958 -3080
  5. package/example-choudoufu-estate/chant.workspace.json +1 -1
  6. package/example-terraform-estate/README.md +10 -10
  7. package/example-terraform-estate/chant.workspace.json +1 -1
  8. package/example-three-cloud/README.md +17 -9
  9. package/example-three-cloud/aws/chant.config.ts +1 -1
  10. package/example-three-cloud/aws/site.component.ts +13 -0
  11. package/example-three-cloud/azure/chant.config.ts +1 -1
  12. package/example-three-cloud/azure/src/site.component.ts +13 -0
  13. package/example-three-cloud/azure/src/site.ts +5 -7
  14. package/example-three-cloud/dns/chant.config.ts +1 -1
  15. package/example-three-cloud/dns/src/records.component.ts +14 -0
  16. package/example-three-cloud/dns/src/route53.ts +4 -5
  17. package/example-three-cloud/gcp/chant.config.ts +1 -1
  18. package/example-three-cloud/gcp/src/site.component.ts +13 -0
  19. package/example-three-cloud/gcp/src/site.ts +7 -7
  20. package/example-three-cloud/package-lock.json +19 -19
  21. package/example-three-cloud/package.json +4 -4
  22. package/example-three-cloud/scripts/front-door.ts +89 -15
  23. package/package.json +10 -11
  24. package/web/agent-move.js +60 -0
  25. package/web/agent-move.test.js +55 -0
  26. package/web/app.js +622 -79
  27. package/web/dots-lod.js +1 -1
  28. package/web/embed.d.ts +3 -0
  29. package/web/embed.js +5 -3
  30. package/web/embed.test.js +8 -0
  31. package/web/index.html +64 -9
  32. package/web/layout-store.js +3 -3
  33. package/web/panel.js +28 -4
  34. package/web/release.js +6 -4
  35. package/web/release.test.js +2 -2
  36. package/web/search-view.d.ts +27 -0
  37. package/web/search-view.js +213 -0
  38. package/web/search-view.test.js +144 -0
  39. package/web/shot-frame.d.ts +5 -0
  40. package/web/shot-frame.js +116 -0
  41. package/web/shot-frame.test.js +90 -0
  42. package/web/themes.js +1 -1
  43. package/web/view-url.d.ts +18 -0
  44. package/web/view-url.js +153 -6
  45. package/web/view-url.test.js +72 -1
  46. package/example-three-cloud/azure/composites/container-app-site.ts +0 -77
  47. package/example-three-cloud/dns/composites/latency-entry.ts +0 -73
  48. package/example-three-cloud/gcp/composites/public-cloud-run.ts +0 -102
package/README.md CHANGED
@@ -460,7 +460,7 @@ button says who chant will record before the click: the person `--as` names
460
460
  (`--as github:<login>`), the person an authenticating proxy names in the header
461
461
  `--identity-header` trusts, or else the user running behold. A gate the
462
462
  workspace names in `identity.gates` is signed with that person's key when
463
- `--signing-key` (or `.behold.json`'s `approver.keys`) gives one, and sent to the
463
+ `--signing-key` (or `approver.keys` in behold's per-user settings) gives one, and sent to the
464
464
  command line otherwise (#690). Every approve route refuses in preview mode.
465
465
 
466
466
  In a declared workspace, the inspect pane of a member's box or a card has a
@@ -560,50 +560,67 @@ nothing else. Your Terraform is never edited; see AGENTS.md, "Invariant".
560
560
  ## Configuration: `.behold.json`
561
561
 
562
562
  An optional `.behold.json` in the served project's root is **behold's own**
563
- config, kept separate from `chant.config.ts` so behold's concerns (like the
564
- tier picker) don't leak into chant's. Three keys: `tiers` below, `executor`
565
- (which forge deploys an environment), and `members`, spelled `[{ "dir": "x", "kind":
563
+ config, which #470 retired. One key is still read, `members`, spelled `[{ "dir": "x", "kind":
566
564
  "chant" | "choudoufu" | "terraform" }]`, how an estate root names what it
567
565
  composes, fail-closed on a kind behold has no reader for. `members` is
568
566
  deprecated: a chant workspace declaration (`chant.workspace.json`) lists an
569
567
  estate's members for every reader, and beside one, `.behold.json`'s list is
570
568
  ignored. `behold doctor --fix` writes the declaration from it (see
571
- [Serve a chant workspace](https://intentius.io/behold/using/workspace/)). First, the
572
- project's deploy-**tier** axis, a dimension orthogonal to `environment` (chant
573
- has no native tier concept; it is entirely a project convention, e.g. Loom's
574
- components branching on an env-conditioned `namingParams.tier`):
569
+ [Serve a chant workspace](https://intentius.io/behold/using/workspace/)).
575
570
 
576
- ```json
577
- {
578
- "tiers": {
579
- "envVar": "LOOM_TIER",
580
- "values": ["light", "production", "production-ha"]
581
- }
582
- }
571
+ ### The tier axis: `buildParams` in `chant.config.ts`
572
+
573
+ The deploy-**tier** axis, a dimension orthogonal to `environment`, is a chant
574
+ build-time parameter (#470): a `buildParams` entry with a string `enum`, the
575
+ one named `tier` first, else the first such entry.
576
+
577
+ ```typescript
578
+ buildParams: {
579
+ tier: { type: "string", enum: ["light", "production", "production-ha"], default: "light", env: "LOOM_TIER" },
580
+ },
583
581
  ```
584
582
 
585
- - `envVar` is the env var name the project's source branches on; behold sets it
586
- for the chant shell-out whenever a tier is picked (`?tier=` → this var, never
587
- a chant CLI flag).
588
- - `values` is the tier picker's options.
583
+ - The `enum` is the tier picker's options.
584
+ - A picked tier (`?tier=`) reaches `chant graph` as `--param tier=<value>`, and
585
+ the parameter's `env` variable is set for the chant shell-out when it
586
+ declares one, so a chant command without `--param` sees it too.
587
+ - The current tier in the header is that `env` variable's value in behold's
588
+ own environment, when the parameter declares one.
589
+
590
+ No such parameter means no tier axis: the picker doesn't render and the graph
591
+ loads with no tier selected. `.behold.json`'s old `tiers` block is not read;
592
+ `behold doctor` warns where one is left.
593
+
594
+ ### Per-user settings: `approver` and `behaviour.traffic`
589
595
 
590
- **No `.behold.json` (or no `tiers` key) → no tier axis:** the picker doesn't
591
- render and the graph loads with no tier selected, which is the default for any
592
- project that doesn't opt in. There's no other tier config surface (not
593
- `chant.config.ts`, not an env var behold guesses the name of).
596
+ Who is approving (`approver`, see [Approving](https://intentius.io/behold/using/approving/))
597
+ and the traffic level the behaviour overlay predicts at (`behaviour.traffic`)
598
+ are one operator's settings, so since #470 they live in a per-user file outside
599
+ the project, beside the hand layout: `<cache>/behold/settings/<key>.json`
600
+ (`~/Library/Caches/behold/settings/` on macOS, `~/.cache/behold/settings/` on Linux, `%LOCALAPPDATA%\behold\settings\` on Windows; `BEHOLD_CACHE_DIR` moves it), keyed by the project's realpath like the layout. A project
601
+ whose `.behold.json` carried either block has it copied in on the first read
602
+ (relative key paths made absolute against the project); `.behold.json` is
603
+ never written or deleted.
594
604
 
595
605
  ### Deploy executors: `executor`
596
606
 
597
- The same file can designate which forge deploys an environment (#165):
607
+ A member's `chant.config.ts` designates which forge deploys an environment
608
+ (#165, #470), on the environment's entry:
598
609
 
599
- ```json
600
- {
601
- "executor": {
602
- "prod": { "forge": "github", "workflow": "deploy-prod.yml" }
603
- }
604
- }
610
+ ```ts
611
+ environments: [
612
+ "staging",
613
+ { name: "prod", executor: { forge: "github", workflow: "deploy-prod.yml" } },
614
+ ],
605
615
  ```
606
616
 
617
+ behold reads it from chant (`chant workspace graph --composites`, each
618
+ `components[].environments[]` row's `executor`, chant 0.124.47 or newer), and
619
+ never from the name of a generated `chant-components-<env>` workflow. A chant
620
+ older than that, or an environment that declares none, reads as no designation.
621
+ `.behold.json`'s old `executor` block is not read; `behold doctor` warns where
622
+ one is left, with the entry to add.
623
+
607
624
  It names the committed **workflow**, not just the forge, because two
608
625
  environments' generated pipelines carry identical job ids and a picker cannot
609
626
  tell them apart. For a designated environment the Deploy button dispatches that
@@ -624,33 +641,33 @@ state outside the project, so a behold restarted mid-deploy re-adopts the run
624
641
  and keeps following it. A follow whose stream dies is reported as `lost`, never
625
642
  as a verdict; `just e2e-ci-github` proves the whole contract against GitHub.
626
643
 
627
- ### The hand-layout sidecar: `.behold/layout.json`
644
+ ### The hand layout: a per-user cache
628
645
 
629
646
  dagre places your nodes; you can move them. Drag a card, resize a containment
630
647
  box, and the offsets are remembered per project and lens: in `localStorage`
631
- first, and (when the served project is writable) in a `.behold/layout.json`
632
- sidecar beside it, so a layout is shareable, reviewable in a diff, and honoured
633
- by `behold export`:
648
+ first, and in a per-user cache file outside the project, which is what
649
+ `behold export` bakes into its SVGs:
634
650
 
635
651
  ```json
636
- { "version": 1, "lenses": { "components": { "src/api#Component": { "dx": 40, "dy": -25 } } } }
652
+ { "version": 1, "projectDir": "/path/to/project", "lenses": { "components": { "src/api#Component": { "dx": 40, "dy": -25 } } } }
637
653
  ```
638
654
 
639
- This is the **only** file behold writes inside a served project. It stores
640
- deltas rather than absolute positions, so the graph stays chant's and your
641
- layout sits on top of it. A delta whose node has left the estate is dropped.
642
- `POST /api/layout` refuses politely in preview mode, during a static-export
643
- capture, on a read-only directory, and above its size caps. `↺ layout` in the
644
- graph clears the current lens on both tiers.
645
-
646
- **Gitignore it.** `.behold.json` (above) is config and belongs in the repo;
647
- `.behold/` is per-user state, one person's arrangement of the picture, so add
648
- it to the served project's `.gitignore` unless you actually want to share and
649
- review a layout:
650
-
651
- ```gitignore
652
- .behold/
653
- ```
655
+ The file is `<user cache>/behold/layouts/<key>.json`, where `<user cache>` is
656
+ `~/Library/Caches` on macOS, `%LOCALAPPDATA%` on Windows and `$XDG_CACHE_HOME`
657
+ (or `~/.cache`) elsewhere, and `<key>` is a hash of the project directory's
658
+ realpath. `BEHOLD_CACHE_DIR` moves `<user cache>/behold`. behold writes nothing
659
+ inside a served project (#469), so there is nothing to gitignore.
660
+
661
+ It stores deltas rather than absolute positions, so the graph stays chant's and
662
+ your layout sits on top of it. A delta whose node has left the estate is
663
+ dropped. `POST /api/layout` refuses politely in preview mode, during a
664
+ static-export capture, when the cache isn't writable, and above its size caps.
665
+ `↺ layout` in the graph clears the current lens on both tiers.
666
+
667
+ A project served by an older behold may have a `.behold/layout.json`. The first
668
+ time the cache has nothing for that project, behold reads the old file once
669
+ and copies it into the cache. It never changes or deletes it; remove it
670
+ yourself when you like.
654
671
 
655
672
  ## Layout
656
673
 
package/demos.json CHANGED
@@ -65,7 +65,7 @@
65
65
  },
66
66
  {
67
67
  "name": "terraform-estate",
68
- "description": "A multi-root Terraform estate, declared only: two roots applied separately (envs/prod and platform) plus the shared module both are built on — 37 cards boxed by root, module calls expanded into their own contents, and the two look-alike versions.tf files told apart. Shows what behold does NOT infer as clearly as what it draws: platform declares the KMS key and prod reads it back by alias, and no edge is drawn between them, because both ends carry the same unresolved interpolation (#381). Needs chant's terraform lexicon beside behold, which behold does not install: npm install --no-save @intentius/chant-lexicon-terraform@^0.124.0 @cdktn/hcl2json@^0.24.0 (without them the demo refuses with that line); the copy is linked to the lexicon behold resolved, since chant reads a workspace's pinned kinds from beside the workspace. No cloud, no Docker, no terraform binary.",
68
+ "description": "A multi-root Terraform estate, declared only: two roots applied separately (envs/prod and platform) plus the shared module both are built on — 37 cards boxed by root, module calls expanded into their own contents, and the two look-alike versions.tf files told apart. Shows what behold does NOT infer as clearly as what it draws: platform declares the KMS key and prod reads it back by alias, and no edge is drawn between them, because both ends carry the same unresolved interpolation (#381). Reads through chant's terraform lexicon (@intentius/chant-lexicon-terraform) and @cdktn/hcl2json, both installed with behold since #909 (an install that pruned them refuses with the line that puts them back); the copy is linked to the lexicon behold resolved, since chant reads a workspace's pinned kinds from beside the workspace. No cloud, no Docker, no terraform binary.",
69
69
  "source": "bundled",
70
70
  "dir": "example-terraform-estate",
71
71
  "requires": [],