@intentius/behold 0.30.2 → 0.31.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.
Files changed (92) hide show
  1. package/AGENTS.md +444 -15
  2. package/README.md +14 -13
  3. package/demos.json +14 -9
  4. package/dist/cli.js +53928 -26475
  5. package/example-carve/README.md +19 -23
  6. package/example-carve/app/package.json +1 -1
  7. package/example-carve/app/src/carved.ts +3 -3
  8. package/example-carve/carve-report.json +1 -1
  9. package/example-carve/{legacy-tf → tf-root}/terraform.tfstate +1 -1
  10. package/example-choudoufu-estate/README.md +7 -0
  11. package/example-choudoufu-estate/chant.workspace.json +1 -1
  12. package/example-choudoufu-estate/scripts/choudoufu-down.sh +2 -1
  13. package/example-choudoufu-estate/scripts/choudoufu-up.sh +10 -3
  14. package/example-terraform-estate/README.md +32 -5
  15. package/example-terraform-estate/chant.workspace.json +1 -1
  16. package/example-terraform-estate/recorded/adoption/platform.json +72 -0
  17. package/example-terraform-estate/recorded/adoption/prod.json +224 -0
  18. package/example-three-cloud/README.md +111 -18
  19. package/example-three-cloud/aws/Pulumi.yaml +15 -0
  20. package/example-three-cloud/aws/index.ts +174 -0
  21. package/example-three-cloud/aws/package-lock.json +2725 -0
  22. package/example-three-cloud/aws/package.json +14 -0
  23. package/example-three-cloud/aws/tsconfig.json +17 -0
  24. package/example-three-cloud/azure/main.tf +48 -0
  25. package/example-three-cloud/azure/site.tf +104 -0
  26. package/example-three-cloud/chant.config.json +9 -0
  27. package/example-three-cloud/chant.workspace.json +30 -4
  28. package/example-three-cloud/dns/chant.config.ts +26 -1
  29. package/example-three-cloud/dns/src/records.component.ts +32 -6
  30. package/example-three-cloud/package-lock.json +48 -27
  31. package/example-three-cloud/package.json +8 -6
  32. package/example-three-cloud/scripts/emulators-up.sh +28 -1
  33. package/example-three-cloud/scripts/front-door.ts +679 -86
  34. package/package.json +13 -6
  35. package/web/adopt-pulumi.js +114 -0
  36. package/web/adopt-pulumi.test.js +28 -0
  37. package/web/adopt.js +203 -0
  38. package/web/adopt.test.js +27 -0
  39. package/web/app.js +358 -10
  40. package/web/carve-steps.js +1 -1
  41. package/web/carve-steps.test.js +2 -2
  42. package/web/change-set-overlay.js +12 -5
  43. package/web/change-set-overlay.test.js +22 -0
  44. package/web/drift-stream.js +241 -0
  45. package/web/drift-stream.test.js +146 -0
  46. package/web/edge-weight.d.ts +1 -1
  47. package/web/edge-weight.js +5 -1
  48. package/web/edge-weight.test.js +19 -0
  49. package/web/graph-query.js +180 -0
  50. package/web/graph-query.test.js +49 -0
  51. package/web/graph.html +107 -0
  52. package/web/index-diff.js +109 -0
  53. package/web/index-diff.test.js +39 -0
  54. package/web/index.html +37 -0
  55. package/web/kiosk-ask-tips.js +15 -5
  56. package/web/kiosk-ask-tips.test.js +14 -1
  57. package/web/kiosk-estate-scene.js +72 -8
  58. package/web/kiosk-light-frame.js +1 -0
  59. package/web/kiosk-light.js +41 -3
  60. package/web/kiosk-member-kind.test.js +140 -0
  61. package/web/kiosk-popover.js +4 -1
  62. package/web/kiosk-side.js +296 -0
  63. package/web/kiosk-side.test.js +249 -0
  64. package/web/kiosk-watch.js +12 -0
  65. package/web/kiosk-watch.test.js +15 -1
  66. package/web/kiosk.html +47 -1
  67. package/web/kiosk.js +106 -7
  68. package/web/member-kind.js +31 -0
  69. package/web/template-apps.js +245 -0
  70. package/web/template-apps.test.js +252 -0
  71. package/web/templates.js +285 -0
  72. package/web/templates.test.js +155 -0
  73. package/web/terragucci-lifecycle.js +112 -62
  74. package/web/terragucci-lifecycle.test.js +29 -1
  75. package/web/terragucci-timeline.js +39 -2
  76. package/web/terragucci-timeline.test.js +42 -1
  77. package/example-three-cloud/aws/chant.config.ts +0 -8
  78. package/example-three-cloud/aws/site.component.ts +0 -13
  79. package/example-three-cloud/aws/src/site.ts +0 -27
  80. package/example-three-cloud/azure/chant.config.ts +0 -1
  81. package/example-three-cloud/azure/src/site.component.ts +0 -13
  82. package/example-three-cloud/azure/src/site.ts +0 -18
  83. /package/example-carve/{legacy-tf → tf-root}/cdn.tf +0 -0
  84. /package/example-carve/{legacy-tf → tf-root}/compute.tf +0 -0
  85. /package/example-carve/{legacy-tf → tf-root}/floci-override.tf.disabled +0 -0
  86. /package/example-carve/{legacy-tf → tf-root}/modules/cdn/main.tf +0 -0
  87. /package/example-carve/{legacy-tf → tf-root}/naming.tf +0 -0
  88. /package/example-carve/{legacy-tf → tf-root}/network.tf +0 -0
  89. /package/example-carve/{legacy-tf → tf-root}/observability.tf +0 -0
  90. /package/example-carve/{legacy-tf → tf-root}/outputs.tf +0 -0
  91. /package/example-carve/{legacy-tf → tf-root}/storage.tf +0 -0
  92. /package/example-carve/{legacy-tf → tf-root}/versions.tf +0 -0
@@ -2,11 +2,33 @@
2
2
  * The front door, rebuilt on the floci emulators: apply the four members,
3
3
  * turn Azure off, wait for Route 53 to notice, and export the page.
4
4
  *
5
- * tsx scripts/front-door.ts all --out <dir> every step below, in order
6
- * tsx scripts/front-door.ts apply run each member's component (gcp, azure, aws, then dns)
7
- * with `chant run --components`, in a copy of the
8
- * workspace, and wait until `chant lifecycle health`
9
- * reads azureCheck healthy
5
+ * tsx scripts/front-door.ts all --out <dir> apply, azure-off, wait and export, in order
6
+ * tsx scripts/front-door.ts plan --out <file> one change set over the four members, a part per engine:
7
+ * `chant lifecycle plan` for dns and gcp, chant's
8
+ * choudoufuPlanSet Op activity for the azure estate and `plunge
9
+ * preview` (pulumiPreviewPart) for the aws program,
10
+ * composed under one digest
11
+ * tsx scripts/front-door.ts apply [--change-set <file>]
12
+ * run gcp's component with `chant run --components` in a
13
+ * copy of the workspace, apply the azure estate, `plunge
14
+ * up` the aws program, run dns's components, and wait
15
+ * until `chant lifecycle health` reads azureCheck healthy.
16
+ * With --change-set, the four members are planned again
17
+ * first, and when any part's plan is not the one in the
18
+ * file the whole set is refused and nothing is applied
19
+ * tsx scripts/front-door.ts pr-plan-dns --base <ref> --out <dir>
20
+ * dns's pull-request plan of the change from <ref> to
21
+ * HEAD (`chant components pr-plan --member dns`), under
22
+ * the floci-az lock; writes pr-plan.json and
23
+ * change-set.json to <dir>, applies nothing
24
+ * tsx scripts/front-door.ts build-dns the dns records component's Build step: dns/dist/dns.json,
25
+ * its gcp parameter defaulted to what is applied and its
26
+ * checks pointed at the emulators
27
+ * tsx scripts/front-door.ts oob-edit <member> one edit to a member's live resources that its source
28
+ * does not make, on the emulators, so its card changes
29
+ * colour: dns's hosted zone comment, gcp's Cloud Run
30
+ * labels, azure's Container App tags, aws's log group
31
+ * retention
10
32
  * tsx scripts/front-door.ts azure-off deactivate the Azure app's active revision
11
33
  * tsx scripts/front-door.ts wait until azureCheck reads unhealthy
12
34
  * tsx scripts/front-door.ts export --out <dir> behold export, opening on env local at the components zoom
@@ -22,16 +44,66 @@
22
44
  * records each component's release on that remote's chant/lifecycle branch, so
23
45
  * the exported page shows a real last release on every component card, and
24
46
  * nothing is pushed anywhere but this directory. The export reads the copy.
47
+ *
48
+ * The azure member is a choudoufu estate (azure/*.tf, INTENTIUS/choudoufu#2246).
49
+ * It is planned and applied here in the workspace itself, through the
50
+ * terraform lexicon's activities and the root's chant.config.json, which
51
+ * names it as the lexicon's `azure` root: choudoufuPlanSet, run as an Op
52
+ * activity (planAzureSet), runs `choudoufu live-plan-set` over it, and
53
+ * choudoufuWaveApply applies exactly that set.
54
+ * Its record store and provider schemas stay in azure/, and the copy links
55
+ * to them. choudoufu is the one on PATH, or CHOUDOUFU_BIN. Every choudoufu
56
+ * call runs under the floci-az endpoint lock choudoufu's own Azure estates
57
+ * use (lockAzureEnv), so nothing it starts can reach a real subscription.
58
+ *
59
+ * The aws member is a Pulumi program on plunge (aws/index.ts, behold#1000),
60
+ * its backend plunge's record backend in aws/.plunge (Pulumi.yaml). It is
61
+ * planned with the pulumi lexicon's previewPulumiMember, which runs `plunge
62
+ * preview --json` and reads it with pulumiPreviewPart, and applied here with
63
+ * `plunge up` on the stack named after the environment, after which `plunge
64
+ * stack export` writes aws/stack-export.json, the export chant reads the
65
+ * member's graph from. plunge is the one on PATH, or PLUNGE_BIN. Every plunge
66
+ * call runs under the floci lock (lockAwsEnv): floci's fake key pair, no
67
+ * Pulumi Cloud login or backend from the shell, and an AWS_ENDPOINT_URL on
68
+ * this machine or nothing runs.
69
+ *
70
+ * dns reads azure's azureEndpoint and aws's awsEndpoint through chant
71
+ * (INTENTIUS/chant#4455): dns/src/records.component.ts has an `azure` and an
72
+ * `aws` component whose `member-outputs` steps read the estate through
73
+ * choudoufu and the stack through plunge, and its records step's cfn-deploy
74
+ * takes `stackOutput("azure", "azureEndpoint")` and `stackOutput("aws",
75
+ * "awsEndpoint")` as those parameters. So dns's components run under both
76
+ * locks (lockedChildEnv). gcpEndpoint is still read here, by build-dns, from
77
+ * what is applied.
25
78
  */
26
79
  import { execFileSync, spawnSync } from "node:child_process";
27
80
  import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
28
81
  import { dirname, join, relative, resolve } from "node:path";
29
82
  import { fileURLToPath } from "node:url";
30
- import { awsApply, awsDelete } from "@intentius/chant-lexicon-aws/op/activities";
31
- import { azApply } from "@intentius/chant-lexicon-azure/op/activities";
83
+ import { composeChangeSet, lifecyclePlanPart, verifyChangeSetDigest, type ChangeSetDocument, type ChangeSetPart } from "@intentius/chant/change-set";
84
+ import { PLAN_MOVED_EXIT_CODE } from "@intentius/chant/components/capability";
85
+ import { planCoveredBy } from "@intentius/chant/components/pr-run";
86
+ import type { ChangeSet as LifecycleChangeSet } from "@intentius/chant/lifecycle/change-set";
87
+ import type { OpConfig } from "@intentius/chant/op";
88
+ import { awsApply } from "@intentius/chant-lexicon-aws/op/activities";
32
89
  import { gcpApply } from "@intentius/chant-lexicon-gcp/op/activities";
90
+ import { choudoufuPlanSet, choudoufuWaveApply, terraformOutputs, type ChoudoufuPlanSetResult } from "@intentius/chant-lexicon-terraform/op/activities/terraform";
33
91
 
34
92
  const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
93
+
94
+ /**
95
+ * The pulumi lexicon, loaded by the aws plan alone (behold#1005). This
96
+ * directory depends on it (chant 0.124.58), and loading it here, not at the
97
+ * top, still lets every other subcommand (apply-azure among them) run in an
98
+ * install that lacks it.
99
+ */
100
+ async function pulumiRun(): Promise<typeof import("@intentius/chant-lexicon-pulumi/run")> {
101
+ try {
102
+ return await import("@intentius/chant-lexicon-pulumi/run");
103
+ } catch (e) {
104
+ throw new Error(`the aws part needs @intentius/chant-lexicon-pulumi, which is not installed here: run \`npm ci\` in example-three-cloud (README, "Which chant"). ${(e as Error).message}`);
105
+ }
106
+ }
35
107
  const WORK = join(ROOT, ".front-door");
36
108
  const CHANT = join(ROOT, "node_modules", ".bin", "chant");
37
109
  /** The copy the components run in, and the bare repository it pushes its release records to. */
@@ -39,15 +111,22 @@ const RUN = join(WORK, "run");
39
111
  const REMOTE = join(WORK, "run-remote.git");
40
112
 
41
113
  const ENV = "local";
42
- // The Azure resource group and the GCP project, as chant's live reads find them:
43
- // the resource group is named after the environment.
114
+ // The Azure resource group, named after the environment, and the GCP
115
+ // project, as the members declare them.
44
116
  const RESOURCE_GROUP = ENV;
45
117
  const GCP_PROJECT = process.env.GCP_PROJECT_ID ?? "three-cloud";
46
118
  const GCP_REGION = process.env.GCP_REGION ?? "asia-northeast1";
47
- const SUBSCRIPTION = process.env.AZURE_SUBSCRIPTION_ID ?? "00000000-0000-0000-0000-000000000001";
119
+ // The subscription, tenant and client the azure estate's provider block names (azure/main.tf).
120
+ const SUBSCRIPTION = "00000000-0000-0000-0000-000000000001";
121
+ const TENANT = "00000000-0000-0000-0000-000000000002";
122
+ const CLIENT = "00000000-0000-0000-0000-000000000003";
123
+ /** The chant lexicon root the azure estate is, in ./chant.config.json. */
124
+ const AZURE_ROOT = { root: "azure", cwd: ROOT };
48
125
 
49
126
  const AWS = process.env.AWS_ENDPOINT_URL ?? "http://localhost:4566";
50
127
  const AZURE = process.env.AZURE_ENDPOINT_URL ?? "http://localhost:4577";
128
+ /** floci-az's host:port, which the azure estate's provider reaches over TLS as its metadata host. */
129
+ const AZURE_HOST = new URL(AZURE).host;
51
130
  const GCP = process.env.GCP_ENDPOINT_URL ?? "http://localhost:4588";
52
131
  const CONTAINERS = {
53
132
  aws: process.env.FLOCI_CONTAINER ?? "chant-floci",
@@ -74,13 +153,62 @@ const say = (line: string): void => void process.stdout.write(`front-door: ${lin
74
153
 
75
154
  class Refusal extends Error {}
76
155
 
156
+ /**
157
+ * The azure estate's set plan, planned through chant's choudoufuPlanSet Op
158
+ * activity (chant#4483, behold#1017): a one-step Op, run in this process with
159
+ * runOpLocally over the activities `loadActivities(["terraform"])` resolves,
160
+ * so the plan goes through the same activity, contract and step record an Op
161
+ * file's step would. The step's result is read off the activity as it
162
+ * returns, because a step record carries no output.
163
+ *
164
+ * A terraform lexicon older than the activity (0.124.52 and before)
165
+ * contributes no choudoufuPlanSet activity, so with that chant the same
166
+ * function is called directly, as before. Both answer the same ChoudoufuPlanSetResult.
167
+ */
168
+ async function planAzureSet(): Promise<ChoudoufuPlanSetResult> {
169
+ const { activity, loadActivities, runOpLocally } = await import("@intentius/chant/op");
170
+ const activities = await loadActivities(["terraform"]);
171
+ const planSet = activities.get("choudoufuPlanSet");
172
+ if (!planSet) {
173
+ say("azure: this chant's terraform lexicon has no choudoufuPlanSet Op activity (chant#4483), so the plan set is called directly");
174
+ return choudoufuPlanSet(AZURE_ROOT);
175
+ }
176
+ let planned: ChoudoufuPlanSetResult | undefined;
177
+ activities.set("choudoufuPlanSet", async (args, signal) => {
178
+ planned = (await planSet(args, signal)) as ChoudoufuPlanSetResult;
179
+ return planned;
180
+ });
181
+ const op: OpConfig = {
182
+ name: "front-door-azure-plan",
183
+ overview: "Plan the azure estate as a one-root choudoufu set (live-plan-set), writing nothing to floci-az",
184
+ phases: [{ name: "Plan azure", steps: [activity("choudoufuPlanSet", { ...AZURE_ROOT }, { profile: "longInfra", id: "azure" })] }],
185
+ };
186
+ const profiles: Parameters<typeof runOpLocally>[2] = { longInfra: { timeout: "15m", retry: { maximumAttempts: 1 } } };
187
+ try {
188
+ await runOpLocally(op, activities, profiles);
189
+ } catch (e) {
190
+ throw new Refusal(`azure: the choudoufuPlanSet step failed: ${(e as Error).message}`);
191
+ }
192
+ if (!planned) throw new Refusal("azure: the choudoufuPlanSet step ran but returned no set plan");
193
+ return planned;
194
+ }
195
+
196
+ /** A refusal because a part's plan is not the approved one: chant's planMoved exit code. */
197
+ class PlanMoved extends Refusal {
198
+ readonly planMoved = true;
199
+ }
200
+
77
201
  // ---------------------------------------------------------------------------
78
202
  // Build
79
203
 
80
- function build(member: string): string {
204
+ function build(member: "dns" | "gcp"): string {
81
205
  const out = join(WORK, member === "gcp" ? "gcp.yaml" : `${member}.json`);
82
206
  mkdirSync(WORK, { recursive: true });
83
- const r = spawnSync(CHANT, ["build", "src", "-o", out], { cwd: join(ROOT, member), env: childEnv, encoding: "utf8" });
207
+ // dns lists terraform and pulumi too, for its member-outputs components,
208
+ // and the terraform lexicon writes the azure root it names into the same
209
+ // build after the template. Only the aws lexicon's template is wanted.
210
+ const lexicon = member === "dns" ? ["--lexicon", "aws"] : [];
211
+ const r = spawnSync(CHANT, ["build", "src", ...lexicon, "-o", out], { cwd: join(ROOT, member), env: childEnv, encoding: "utf8" });
84
212
  if (r.status !== 0) throw new Refusal(`chant build failed in ${member}:\n${r.stderr || r.stdout}`);
85
213
  return out;
86
214
  }
@@ -115,6 +243,352 @@ function containerAddress(name: string): string {
115
243
  return ip;
116
244
  }
117
245
 
246
+ // ---------------------------------------------------------------------------
247
+ // The floci-az endpoint lock, for every choudoufu call
248
+
249
+ /**
250
+ * The credential and endpoint variables azurerm, its SDK and the Azure CLI
251
+ * would read from the operator's shell, which no choudoufu call here keeps:
252
+ * choudoufu's FLOCI_AZ_SCRUBBED (live/e2e/lib/floci-az.sh), as it stands.
253
+ * Any of them could put a credential ahead of the client secret the provider
254
+ * block states, or move the authority.
255
+ */
256
+ const AZURE_SCRUBBED = `
257
+ ARM_CLIENT_CERTIFICATE ARM_CLIENT_CERTIFICATE_PATH ARM_CLIENT_CERTIFICATE_PASSWORD
258
+ ARM_CLIENT_ID_FILE_PATH ARM_CLIENT_SECRET_FILE_PATH
259
+ ARM_OIDC_TOKEN ARM_OIDC_TOKEN_FILE_PATH ARM_OIDC_REQUEST_TOKEN ARM_OIDC_REQUEST_URL
260
+ ARM_ADO_PIPELINE_SERVICE_CONNECTION_ID ARM_OIDC_AZURE_SERVICE_CONNECTION_ID AZURESUBSCRIPTION_SERVICE_CONNECTION_ID
261
+ ACTIONS_ID_TOKEN_REQUEST_TOKEN ACTIONS_ID_TOKEN_REQUEST_URL SYSTEM_ACCESSTOKEN SYSTEM_OIDCREQUESTURI
262
+ ARM_MSI_ENDPOINT ARM_MSI_API_VERSION ARM_AUXILIARY_TENANT_IDS ARM_PARTNER_ID
263
+ ARM_ACCESS_KEY ARM_SAS_TOKEN ARM_USE_AZUREAD ARM_STORAGE_USE_AZUREAD
264
+ AZURE_CLIENT_ID AZURE_TENANT_ID AZURE_CLIENT_SECRET AZURE_CLIENT_CERTIFICATE_PATH
265
+ AZURE_CLIENT_CERTIFICATE_PASSWORD AZURE_CLIENT_SEND_CERTIFICATE_CHAIN AZURE_USERNAME AZURE_PASSWORD
266
+ AZURE_FEDERATED_TOKEN_FILE AZURE_AUTHORITY_HOST AZURE_REGIONAL_AUTHORITY_NAME
267
+ AZURE_ADDITIONALLY_ALLOWED_TENANTS AZURE_TOKEN_CREDENTIALS AZURE_SUBSCRIPTION_ID
268
+ AZURE_POD_IDENTITY_AUTHORITY_HOST IDENTITY_ENDPOINT IDENTITY_HEADER IDENTITY_SERVER_THUMBPRINT
269
+ IMDS_ENDPOINT MSI_ENDPOINT MSI_SECRET
270
+ `.split(/\s+/).filter(Boolean);
271
+
272
+ /**
273
+ * Aim every choudoufu child at floci-az and nothing else: this process's
274
+ * environment is what the terraform lexicon's activities hand choudoufu, so
275
+ * it is locked here, the way choudoufu's floci_az_provider_env locks a shell.
276
+ * The provider block already states each argument, which beats the
277
+ * environment; this covers what a block cannot say. CHOUDOUFU_BIN, when set,
278
+ * is put on PATH as `choudoufu`, the binary chant.config.json names.
279
+ *
280
+ * TLS: azurerm reaches floci-az over https. On Linux floci-az's own CA is
281
+ * fetched and added to the bundle SSL_CERT_FILE names. Go on macOS trusts
282
+ * only the keychain, so there the certificate scripts/emulators-up.sh mounts
283
+ * is the one choudoufu's scripts/floci-az-mac-cert.sh made and the operator
284
+ * trusted once.
285
+ */
286
+ async function lockAzureEnv(): Promise<void> {
287
+ for (const v of AZURE_SCRUBBED) delete process.env[v];
288
+ const noLogin = join(WORK, "azure-config-no-login");
289
+ mkdirSync(noLogin, { recursive: true });
290
+ Object.assign(process.env, {
291
+ AZURE_CONFIG_DIR: noLogin,
292
+ ARM_SUBSCRIPTION_ID: SUBSCRIPTION,
293
+ ARM_TENANT_ID: TENANT,
294
+ ARM_CLIENT_ID: CLIENT,
295
+ ARM_CLIENT_SECRET: "floci-az-fake-secret",
296
+ ARM_USE_CLI: "false",
297
+ ARM_USE_MSI: "false",
298
+ ARM_USE_OIDC: "false",
299
+ ARM_USE_AKS_WORKLOAD_IDENTITY: "false",
300
+ ARM_METADATA_HOSTNAME: AZURE_HOST,
301
+ ARM_METADATA_HOST: AZURE_HOST,
302
+ ARM_RESOURCE_PROVIDER_REGISTRATIONS: "none",
303
+ ARM_DISABLE_TERRAFORM_PARTNER_ID: "true",
304
+ TF_VAR_floci_az_host: AZURE_HOST,
305
+ });
306
+ const bin = process.env.CHOUDOUFU_BIN;
307
+ if (bin) {
308
+ if (!existsSync(bin)) throw new Refusal(`CHOUDOUFU_BIN names ${bin}, which does not exist`);
309
+ const dir = join(WORK, "bin");
310
+ mkdirSync(dir, { recursive: true });
311
+ rmSync(join(dir, "choudoufu"), { force: true });
312
+ symlinkSync(resolve(bin), join(dir, "choudoufu"));
313
+ if (!process.env.PATH?.startsWith(`${dir}:`)) process.env.PATH = `${dir}:${process.env.PATH ?? ""}`;
314
+ }
315
+ if (process.platform === "darwin" || process.env.SSL_CERT_FILE?.endsWith("ca-bundle-with-floci-az.pem")) return;
316
+ const ca = await fetch(`http://${AZURE_HOST}/_floci/tls-cert`).then((r) => (r.ok ? r.text() : ""), () => "");
317
+ if (!ca.includes("BEGIN CERTIFICATE")) throw new Refusal(`azure: floci-az at ${AZURE_HOST} served no TLS certificate at /_floci/tls-cert; scripts/emulators-up.sh starts it with TLS on`);
318
+ const system = [process.env.SSL_CERT_FILE, "/etc/ssl/certs/ca-certificates.crt", "/etc/pki/tls/certs/ca-bundle.crt", "/etc/ssl/cert.pem"].find((f) => f && existsSync(f));
319
+ if (!system) throw new Refusal("azure: found no system CA bundle to add floci-az's CA to");
320
+ const bundle = join(WORK, "ca-bundle-with-floci-az.pem");
321
+ writeFileSync(bundle, `${readFileSync(system, "utf8")}\n${ca}`);
322
+ process.env.SSL_CERT_FILE = bundle;
323
+ }
324
+
325
+ // ---------------------------------------------------------------------------
326
+ // The floci lock, for every plunge call
327
+
328
+ /** The aws program's directory, where Pulumi.yaml names plunge's backend. */
329
+ const AWS_DIR = join(ROOT, "aws");
330
+ /** The `plunge stack export` chant reads the aws member's graph from (chant-lexicon-pulumi's PULUMI_EXPORT_FILE). */
331
+ const AWS_EXPORT = "stack-export.json";
332
+
333
+ /**
334
+ * Variables from the operator's shell that could point plunge at a real
335
+ * account or a Pulumi Cloud backend, or put a credential ahead of floci's
336
+ * fake key pair. None of them is handed to plunge.
337
+ */
338
+ const AWS_SCRUBBED = `
339
+ AWS_PROFILE AWS_DEFAULT_PROFILE AWS_SESSION_TOKEN AWS_SECURITY_TOKEN AWS_ROLE_ARN AWS_WEB_IDENTITY_TOKEN_FILE
340
+ AWS_CONTAINER_CREDENTIALS_RELATIVE_URI AWS_CONTAINER_CREDENTIALS_FULL_URI AWS_CONTAINER_AUTHORIZATION_TOKEN
341
+ AWS_SHARED_CREDENTIALS_FILE AWS_CONFIG_FILE
342
+ PULUMI_ACCESS_TOKEN PULUMI_BACKEND_URL PULUMI_API
343
+ `.split(/\s+/).filter(Boolean);
344
+
345
+ /**
346
+ * Aim every plunge child at floci and nothing else, the way lockAzureEnv aims
347
+ * choudoufu at floci-az: this process's environment is what the pulumi
348
+ * lexicon's runner hands plunge (defaultPlungeRunner runs `plunge` from
349
+ * PATH), so it is locked here. The program refuses an endpoint off this
350
+ * machine itself (aws/index.ts); this refuses before plunge starts. An empty
351
+ * passphrase is the stack's secrets provider: the program has no secrets.
352
+ * PLUNGE_BIN, when set, is put on PATH as `plunge`.
353
+ */
354
+ function lockAwsEnv(): void {
355
+ const host = new URL(AWS).hostname;
356
+ if (!["localhost", "127.0.0.1", "::1", "[::1]"].includes(host)) throw new Refusal(`aws: AWS_ENDPOINT_URL names ${AWS}, which is not on this machine; the aws program runs only against floci here`);
357
+ for (const v of AWS_SCRUBBED) delete process.env[v];
358
+ Object.assign(process.env, {
359
+ AWS_ENDPOINT_URL: AWS,
360
+ AWS_ACCESS_KEY_ID: "test",
361
+ AWS_SECRET_ACCESS_KEY: "test",
362
+ AWS_REGION: "us-east-1",
363
+ AWS_EC2_METADATA_DISABLED: "true",
364
+ PULUMI_CONFIG_PASSPHRASE: process.env.PULUMI_CONFIG_PASSPHRASE ?? "",
365
+ PULUMI_SKIP_UPDATE_CHECK: "true",
366
+ });
367
+ const bin = process.env.PLUNGE_BIN;
368
+ if (bin) {
369
+ if (!existsSync(bin)) throw new Refusal(`PLUNGE_BIN names ${bin}, which does not exist`);
370
+ const dir = join(WORK, "bin");
371
+ mkdirSync(dir, { recursive: true });
372
+ rmSync(join(dir, "plunge"), { force: true });
373
+ symlinkSync(resolve(bin), join(dir, "plunge"));
374
+ if (!process.env.PATH?.startsWith(`${dir}:`)) process.env.PATH = `${dir}:${process.env.PATH ?? ""}`;
375
+ }
376
+ }
377
+
378
+ /** `plunge <args>` in `cwd` under the floci lock; its stdout, or a refusal with what it said. */
379
+ function plunge(args: string[], cwd: string = AWS_DIR, opts: { show?: boolean } = {}): string {
380
+ const r = spawnSync("plunge", args, { cwd, env: process.env, encoding: "utf8", maxBuffer: 256 * 1024 * 1024, stdio: opts.show ? ["ignore", "inherit", "inherit"] : ["ignore", "pipe", "pipe"] });
381
+ if (r.error) throw new Refusal(`aws: plunge did not start (${r.error.message}); put plunge on PATH or name a build with PLUNGE_BIN`);
382
+ if (r.status !== 0) throw new Refusal(`aws: plunge ${args.join(" ")} failed (exit ${r.status})${opts.show ? "" : `:\n${(r.stderr || r.stdout || "").trim().split("\n").slice(-8).join("\n")}`}`);
383
+ return r.stdout ?? "";
384
+ }
385
+
386
+ /**
387
+ * The aws program ready to run: its packages installed, the backend
388
+ * directory Pulumi.yaml names made, and the stack named after the
389
+ * environment selected (created on the first run, which writes only plunge's
390
+ * own state under aws/ and the stack file's encryption salt).
391
+ */
392
+ function awsStack(cwd: string = AWS_DIR): void {
393
+ lockAwsEnv();
394
+ if (!existsSync(join(cwd, "node_modules", "@pulumi", "aws"))) {
395
+ say("aws: npm install in aws/ (the program's @pulumi/aws and @pulumi/pulumi)");
396
+ const r = spawnSync("npm", ["install", "--no-audit", "--no-fund"], { cwd, stdio: "inherit" });
397
+ if (r.status !== 0) throw new Refusal(`aws: npm install in ${relative(ROOT, cwd) || "."} failed (exit ${r.status})`);
398
+ }
399
+ mkdirSync(join(cwd, ".plunge"), { recursive: true });
400
+ plunge(["stack", "select", "--create", "--secrets-provider", "passphrase", ENV], cwd);
401
+ }
402
+
403
+ /** The aws stack's applied outputs (`plunge stack output --json --show-secrets=false`). */
404
+ function awsOutputs(cwd: string = AWS_DIR): Record<string, unknown> {
405
+ lockAwsEnv();
406
+ const text = plunge(["stack", "output", "--json", "--show-secrets=false", "--stack", ENV], cwd);
407
+ try {
408
+ return JSON.parse(text) as Record<string, unknown>;
409
+ } catch {
410
+ throw new Refusal(`aws: plunge stack output printed no JSON: ${text.slice(0, 300)}`);
411
+ }
412
+ }
413
+
414
+ /** The aws load balancer's hostname, or why there is none. */
415
+ function awsEndpoint(cwd: string = AWS_DIR): { endpoint: string } | { refused: string } {
416
+ try {
417
+ const out = awsOutputs(cwd);
418
+ return typeof out.awsEndpoint === "string" && out.awsEndpoint ? { endpoint: out.awsEndpoint } : { refused: "the stack has no awsEndpoint output" };
419
+ } catch (e) {
420
+ return { refused: e instanceof Error ? e.message : String(e) };
421
+ }
422
+ }
423
+
424
+ // ---------------------------------------------------------------------------
425
+ // Plan: one change set over the four members
426
+
427
+ /** `chant lifecycle plan <env> --json` in a chant member, parsed. */
428
+ function lifecyclePlan(member: string): LifecycleChangeSet {
429
+ const r = spawnSync(CHANT, ["lifecycle", "plan", ENV, "--json"], { cwd: join(ROOT, member), env: childEnv, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
430
+ if (r.status !== 0) throw new Refusal(`${member}: chant lifecycle plan ${ENV} failed (exit ${r.status}):\n${r.stderr || r.stdout}`);
431
+ return JSON.parse(r.stdout) as LifecycleChangeSet;
432
+ }
433
+
434
+ /**
435
+ * The change set a run over the whole workspace would approve, one part per
436
+ * engine: a chant part for each of dns and gcp, the azure estate's choudoufu
437
+ * part from choudoufuPlanSet (choudoufu's root digest as its nativeDigest),
438
+ * and the aws program's pulumi part from `plunge preview --json`
439
+ * (previewPulumiMember, which reads it with pulumiPreviewPart, the checked-in
440
+ * stack-export.json as the last deployment), composed under one document
441
+ * digest. Written to `out`. Reads only: nothing applies. The aws stack is
442
+ * selected first, and created on a first run (awsStack), which writes
443
+ * plunge's own state under aws/ and nothing on floci.
444
+ */
445
+ export async function plan(out: string): Promise<ChangeSetDocument> {
446
+ const parts: ChangeSetPart[] = [];
447
+ for (const member of ["dns", "gcp"]) {
448
+ say(`${member}: chant lifecycle plan ${ENV}`);
449
+ parts.push(lifecyclePlanPart({ member, plan: lifecyclePlan(member) }));
450
+ }
451
+ await lockAzureEnv();
452
+ say(`azure: choudoufu live-plan-set over the azure estate, on floci-az at ${AZURE_HOST}`);
453
+ parts.push((await planAzureSet()).changeSet);
454
+ awsStack();
455
+ say(`aws: plunge preview --json --stack ${ENV}, on floci at ${AWS}`);
456
+ const { previewPulumiMember } = await pulumiRun();
457
+ parts.push(await previewPulumiMember({ member: "aws", dir: AWS_DIR, stack: ENV }));
458
+ const chant = (JSON.parse(readFileSync(join(ROOT, "node_modules", "@intentius", "chant", "package.json"), "utf8")) as { version?: string }).version;
459
+ const doc = composeChangeSet(parts, chant ? { chant } : {});
460
+ mkdirSync(dirname(resolve(out)), { recursive: true });
461
+ writeFileSync(resolve(out), `${JSON.stringify(doc, null, 2)}\n`);
462
+ for (const m of doc.members) {
463
+ const counts = doc.summary.byMember[m.member] ?? {};
464
+ const changes = Object.entries(counts).filter(([action, n]) => n && action !== "no-op").map(([action, n]) => `${action} ${n}`).join(", ");
465
+ say(`plan: ${m.member} (${m.planner}) ${m.status}${m.status === "failed" ? `: ${m.error}` : `, ${changes || "no changes"}`}`);
466
+ }
467
+ say(`plan: change set ${doc.digest} over ${doc.members.length} members, written to ${relative(process.cwd(), resolve(out)) || out}`);
468
+ return doc;
469
+ }
470
+
471
+ /** One part of an approved set whose plan is not the one planned now. */
472
+ export interface MovedPart {
473
+ member: string;
474
+ planner: string;
475
+ /** The approved part's plan digest, and the fresh one's (null for a failed plan). */
476
+ approved: string | null;
477
+ fresh: string | null;
478
+ reason: string;
479
+ }
480
+
481
+ /**
482
+ * The parts of `approved` that `fresh` does not plan the same way. A part
483
+ * stands when it is in both, planned, under the same plan digest. For any
484
+ * other the reason is chant's own (`planCoveredBy`, the words a pull
485
+ * request's apply gives a member whose plan moved), or the two digests when
486
+ * chant has none. The set is refused when the documents' digests differ,
487
+ * which this lists the parts of; a document digest that moved with every
488
+ * part's plan digest the same (a hole, an entry) is its own line.
489
+ */
490
+ export function movedParts(approved: ChangeSetDocument, fresh: ChangeSetDocument): MovedPart[] {
491
+ const names = [...new Set([...approved.members, ...fresh.members].map((m) => m.member))].sort();
492
+ const out: MovedPart[] = [];
493
+ for (const name of names) {
494
+ const was = approved.members.find((m) => m.member === name);
495
+ const now = fresh.members.find((m) => m.member === name);
496
+ const digests = { approved: was?.planDigest ?? null, fresh: now?.planDigest ?? null };
497
+ const planner = (now ?? was)!.planner;
498
+ if (!now) {
499
+ out.push({ member: name, planner, ...digests, reason: `${name} is in the approved set and was not planned now` });
500
+ continue;
501
+ }
502
+ if (was && was.status === "planned" && now.status === "planned" && was.planDigest !== null && now.planDigest === was.planDigest) continue;
503
+ const reason = planCoveredBy(approved, fresh, name) ?? `${name}'s plan digest is ${digests.fresh ?? "none"}, and ${digests.approved ?? "none"} was approved`;
504
+ out.push({ member: name, planner, ...digests, reason });
505
+ }
506
+ return out;
507
+ }
508
+
509
+ /** What `apply --change-set` decided, written to .front-door/apply-verdict.json before anything applies. */
510
+ interface ApplyVerdict {
511
+ verdict: "refused" | "applying" | "applied";
512
+ approved: string;
513
+ fresh?: string;
514
+ moved?: MovedPart[];
515
+ reason?: string;
516
+ }
517
+
518
+ function writeVerdict(v: ApplyVerdict): void {
519
+ mkdirSync(WORK, { recursive: true });
520
+ writeFileSync(join(WORK, "apply-verdict.json"), `${JSON.stringify(v, null, 2)}\n`);
521
+ }
522
+
523
+ /**
524
+ * Apply the set in `file`, or refuse it whole. The document's own digest is
525
+ * checked first (verifyChangeSetDigest: an edited document binds nothing),
526
+ * then all four members are planned again (`plan`), and when the fresh
527
+ * document's digest is not the approved one the whole set is refused, every
528
+ * moved part named, before any member applies: one gate binds every part, so
529
+ * a changed plan in any part, chant, choudoufu or pulumi, refuses the set.
530
+ * The refusal exits with chant's planMoved code (3). Only a set that still
531
+ * stands is applied (`apply`).
532
+ */
533
+ export async function applyApproved(file: string): Promise<void> {
534
+ let approved: ChangeSetDocument;
535
+ try {
536
+ approved = JSON.parse(readFileSync(resolve(file), "utf8")) as ChangeSetDocument;
537
+ } catch (e) {
538
+ throw new Refusal(`apply: ${file} is not a change-set document: ${(e as Error).message}`);
539
+ }
540
+ if (!verifyChangeSetDigest(approved)) {
541
+ const reason = `the document's digest ${approved.digest} is not the one its parts give: it was changed after it was composed`;
542
+ writeVerdict({ verdict: "refused", approved: approved.digest, reason });
543
+ throw new PlanMoved(`apply: refused, nothing applied: ${reason}`);
544
+ }
545
+ const failed = approved.members.filter((m) => m.status !== "planned");
546
+ if (failed.length) {
547
+ const reason = `the approved set has parts that did not plan: ${failed.map((m) => `${m.member} (${m.planner}) ${m.status}${m.error ? `: ${m.error}` : ""}`).join("; ")}`;
548
+ writeVerdict({ verdict: "refused", approved: approved.digest, reason });
549
+ throw new Refusal(`apply: refused, nothing applied: ${reason}`);
550
+ }
551
+ say(`apply: planning the four members again, to check the set ${approved.digest} still stands`);
552
+ const fresh = await plan(join(WORK, "change-set.fresh.json"));
553
+ if (fresh.digest !== approved.digest) {
554
+ const moved = movedParts(approved, fresh);
555
+ const reason = moved.length
556
+ ? moved.map((m) => `${m.member} (${m.planner}): ${m.reason}`).join("; ")
557
+ : `the document digest is ${fresh.digest} now, with every part's plan digest the same (a hole or an entry moved)`;
558
+ writeVerdict({ verdict: "refused", approved: approved.digest, fresh: fresh.digest, moved, reason });
559
+ for (const m of moved) say(`apply: ${m.member} (${m.planner}) moved: ${m.reason}`);
560
+ throw new PlanMoved(`apply: the change set ${approved.digest} is refused whole, nothing applied: it plans as ${fresh.digest} now`);
561
+ }
562
+ writeVerdict({ verdict: "applying", approved: approved.digest, fresh: fresh.digest });
563
+ say(`apply: the set ${approved.digest} stands, every part as approved; applying`);
564
+ await apply();
565
+ writeVerdict({ verdict: "applied", approved: approved.digest, fresh: fresh.digest });
566
+ }
567
+
568
+ /**
569
+ * dns's pull-request plan of the change from `base` to HEAD, as dns's own
570
+ * pipeline would run it: `chant components pr-plan --member dns` in dns,
571
+ * with no status posted. A change under azure/ names the azure component
572
+ * (dns's `terraform.roots.azure`), so records is planned against what
573
+ * azure's plan says azureEndpoint will be. Under the floci-az lock, since
574
+ * the azure component's plan runs `choudoufu live-plan-set`, and the floci
575
+ * lock, since the aws component reads the stack with `plunge stack output`
576
+ * (or `plunge preview` when the change names aws). Reads only.
577
+ */
578
+ export async function prPlanDns(base: string, out: string): Promise<void> {
579
+ await lockAzureEnv();
580
+ awsStack();
581
+ mkdirSync(resolve(out), { recursive: true });
582
+ say(`dns: chant components pr-plan --base ${base} --member dns --env ${ENV}`);
583
+ const r = spawnSync(CHANT, ["components", "pr-plan", "--base", base, "--pr", "1", "--env", ENV, "--member", "dns", "--no-status", "--output", resolve(out)], {
584
+ cwd: join(ROOT, "dns"),
585
+ env: lockedChildEnv(),
586
+ stdio: "inherit",
587
+ });
588
+ // The report says what was planned; a member that failed to plan is in it.
589
+ if (!existsSync(join(resolve(out), "pr-plan.json"))) throw new Refusal(`dns: chant components pr-plan wrote no report (exit ${r.status})`);
590
+ }
591
+
118
592
  // ---------------------------------------------------------------------------
119
593
  // Apply
120
594
 
@@ -143,15 +617,18 @@ async function applyGcp(): Promise<string> {
143
617
  return addr.address;
144
618
  }
145
619
 
620
+ /** The azure estate: plan it as a one-root set, apply exactly that set, read its endpoint. */
146
621
  async function applyAzure(): Promise<string> {
147
- const template = build("azure");
148
- say(`azure: applying ${template} to ${AZURE} (resource group ${RESOURCE_GROUP})`);
149
- await azApply({ templatePath: template, resourceGroup: RESOURCE_GROUP, location: "westeurope", endpoint: AZURE, subscriptionId: SUBSCRIPTION });
150
- const app = await getJson(`${appUrl()}?api-version=2024-03-01`);
151
- const fqdn = (app.properties as { configuration?: { ingress?: { fqdn?: string } } } | undefined)?.configuration?.ingress?.fqdn;
152
- if (!fqdn) throw new Refusal(`azure: the container app web has no ingress fqdn (${JSON.stringify(app).slice(0, 300)})`);
622
+ await lockAzureEnv();
623
+ say(`azure: choudoufu live-plan-set over the azure estate, on floci-az at ${AZURE_HOST}`);
624
+ const set = await planAzureSet();
625
+ say(`azure: ${set.changed ? "applying" : "no changes in"} set ${set.setDigest} with live-wave-apply`);
626
+ const applied = await choudoufuWaveApply({ ...AZURE_ROOT, planSetFile: set.planSetFile, setDigest: set.setDigest });
627
+ if (!applied.landed) throw new Refusal(`azure: ${applied.message}`);
628
+ const { azureEndpoint } = await terraformOutputs(AZURE_ROOT);
629
+ if (typeof azureEndpoint !== "string" || !azureEndpoint) throw new Refusal("azure: the estate has no azureEndpoint output after its apply");
153
630
  await azureOn();
154
- return fqdn;
631
+ return azureEndpoint;
155
632
  }
156
633
 
157
634
  /** A run before this one turned Azure off, and applying the same app again
@@ -166,22 +643,24 @@ async function azureOn(): Promise<void> {
166
643
  say(`azure: revision ${newest.name} activated again`);
167
644
  }
168
645
 
169
- /** The aws member, or why it could not be applied. */
170
- async function applyAws(): Promise<{ endpoint: string } | { refused: string }> {
171
- const params = build("aws");
172
- // A stack that rolled back on its first create can't be updated; start it again.
173
- if ((await stackStatus("three-cloud-aws")) === "ROLLBACK_COMPLETE") {
174
- await awsDelete({ templatePath: params, stackName: "three-cloud-aws", endpoint: AWS, timeoutMs: 180_000 });
175
- }
176
- say(`aws: applying ${params} to ${AWS} as stack three-cloud-aws`);
177
- try {
178
- await awsApply({ templatePath: params, stackName: "three-cloud-aws", endpoint: AWS, timeoutMs: 180_000 });
179
- } catch (e) {
180
- const why = await stackFailure("three-cloud-aws");
181
- return { refused: `${e instanceof Error ? e.message : String(e)}${why ? `: ${why}` : ""}` };
182
- }
183
- const out = await stackOutputs("three-cloud-aws");
184
- return out.awsEndpoint ? { endpoint: out.awsEndpoint } : { refused: "the stack has no awsEndpoint output" };
646
+ /**
647
+ * The aws program: `plunge up` on the stack named after the environment,
648
+ * then `plunge stack export` to aws/stack-export.json, which is what chant
649
+ * reads the member's graph from (the graph read never runs the program).
650
+ * Returns the load balancer's hostname, the stack's awsEndpoint output.
651
+ * Unlike the CloudFormation stack it replaces, a failed `up` stops the run:
652
+ * dns reads awsEndpoint from the stack, so there is nothing for it to point
653
+ * at.
654
+ */
655
+ async function applyAws(): Promise<string> {
656
+ awsStack();
657
+ say(`aws: plunge up --stack ${ENV}, on floci at ${AWS}`);
658
+ plunge(["up", "--yes", "--non-interactive", "--skip-preview", "--stack", ENV], AWS_DIR, { show: true });
659
+ plunge(["stack", "export", "--stack", ENV, "--file", AWS_EXPORT]);
660
+ say(`aws: ${relative(process.cwd(), join(AWS_DIR, AWS_EXPORT)) || AWS_EXPORT} written, the export chant reads the member's graph from`);
661
+ const aws = awsEndpoint();
662
+ if ("refused" in aws) throw new Refusal(`aws: ${aws.refused}`);
663
+ return aws.endpoint;
185
664
  }
186
665
 
187
666
  /** Where floci's checkers connect for one cloud's check, as Route 53 does
@@ -211,9 +690,15 @@ function withProbes(template: string, probes: Record<string, Probe>): void {
211
690
  writeFileSync(template, JSON.stringify(doc, null, 2));
212
691
  }
213
692
 
214
- async function applyDns(endpoints: Record<string, string>, probes: Record<string, Probe>): Promise<void> {
693
+ /** The dns template, its parameters in `endpoints` defaulted and its checks pointed at `probes`. */
694
+ function dnsTemplate(endpoints: Record<string, string>, probes: Record<string, Probe>): string {
215
695
  const params = withDefaults(build("dns"), endpoints);
216
696
  withProbes(params, probes);
697
+ return params;
698
+ }
699
+
700
+ async function applyDns(endpoints: Record<string, string>, probes: Record<string, Probe>): Promise<void> {
701
+ const params = dnsTemplate(endpoints, probes);
217
702
  // The stack named after the environment, where chant's live read looks for a single-stack project.
218
703
  say(`dns: applying ${params} to ${AWS} as stack ${ENV}`);
219
704
  await awsApply({ templatePath: params, stackName: ENV, endpoint: AWS, timeoutMs: 180_000 });
@@ -222,11 +707,21 @@ async function applyDns(endpoints: Record<string, string>, probes: Record<string
222
707
  export async function apply(): Promise<void> {
223
708
  workspaceCopy();
224
709
  runComponent("gcp", "site");
225
- runComponent("azure", "site");
226
- // A run before this one turned Azure off, and applying the same app again leaves its revision inactive.
227
- await azureOn();
228
- runComponent("aws", "site");
229
- runComponent("dns", "records");
710
+ // The azure estate is no chant component: choudoufu applies it (applyAzure,
711
+ // which also turns a revision a run before this one left off back on).
712
+ say(`azure: web answers as ${await applyAzure()}`);
713
+ // The aws program is no chant component either: plunge applies it, in the
714
+ // workspace itself, and the copy links to its state (workspaceCopy). The
715
+ // copy's aws/ is another project directory to plunge, so the stack is
716
+ // selected there too, for the aws component's `plunge stack output`.
717
+ say(`aws: web answers as ${await applyAws()}`);
718
+ plunge(["stack", "select", ENV], join(RUN, "aws"));
719
+ // dns's azure and aws components read the estate's outputs through
720
+ // choudoufu and the stack's through plunge, so they run under both locks,
721
+ // and before records, which reads them.
722
+ await lockAzureEnv();
723
+ lockAwsEnv();
724
+ runComponent("dns", "azure,aws,records", lockedChildEnv());
230
725
  // Before anything is turned off, the check on Azure has to pass: that is
231
726
  // what shows the checkers reach floci-az at all.
232
727
  await waitFor("healthy");
@@ -244,11 +739,20 @@ function workspaceCopy(): void {
244
739
  rmSync(REMOTE, { recursive: true, force: true });
245
740
  const skip = /(^|[/\\])(node_modules|export|\.front-door|dist|\.git)([/\\]|$)/;
246
741
  // Entry by entry: a directory can't be copied into its own .front-door.
742
+ // The root's .chant holds choudoufuPlanSet's set plan documents, which
743
+ // belong to the workspace, not the copy.
247
744
  mkdirSync(RUN, { recursive: true });
248
745
  for (const e of readdirSync(ROOT)) {
249
- if (!skip.test(e)) cpSync(join(ROOT, e), join(RUN, e), { recursive: true, filter: (src) => !skip.test(relative(ROOT, src)) });
746
+ if (!skip.test(e) && e !== ".chant") cpSync(join(ROOT, e), join(RUN, e), { recursive: true, filter: (src) => !skip.test(relative(ROOT, src)) && !LINKED_STATE.includes(relative(ROOT, src)) });
250
747
  }
251
748
  symlinkSync(join(ROOT, "node_modules"), join(RUN, "node_modules"));
749
+ // The azure estate's schemas, lock file and records, and the aws program's
750
+ // plunge backend, stack file, export and packages, linked rather than
751
+ // copied: behold reads both members in the copy, the copy's dns reads
752
+ // their outputs, and choudoufu and plunge apply them here. A link may
753
+ // point at what the first apply has yet to write.
754
+ mkdirSync(join(AWS_DIR, ".plunge"), { recursive: true });
755
+ for (const p of LINKED_STATE) symlinkSync(join(ROOT, p), join(RUN, p));
252
756
  git(["init", "-q", "-b", "main"], RUN);
253
757
  git(["add", "-A"], RUN);
254
758
  git(["commit", "-q", "-m", "three-cloud"], RUN);
@@ -258,17 +762,66 @@ function workspaceCopy(): void {
258
762
  say(`run: the workspace copied to ${relative(ROOT, RUN)}, its releases recorded on ${relative(ROOT, REMOTE)}`);
259
763
  }
260
764
 
261
- /** One member's component, through chant's own deploy steps, against the emulators. */
262
- function runComponent(member: string, component: string): void {
765
+ /** What choudoufu keeps beside the azure estate, which the copy links to (workspaceCopy). */
766
+ const AZURE_STATE = [".terraform", ".terraform.lock.hcl", ".tofu-records"].map((f) => join("azure", f));
767
+ /** What plunge keeps beside the aws program, and its packages, which the copy links to too. */
768
+ const AWS_STATE = [".plunge", "Pulumi.local.yaml", "stack-export.json", "node_modules"].map((f) => join("aws", f));
769
+ const LINKED_STATE = [...AZURE_STATE, ...AWS_STATE];
770
+
771
+ /**
772
+ * childEnv with this process's environment as lockAzureEnv left it, for a
773
+ * chant child that starts choudoufu: the variables the lock removed stay
774
+ * removed, and the ones it set win.
775
+ */
776
+ function lockedChildEnv(): NodeJS.ProcessEnv {
777
+ const env: NodeJS.ProcessEnv = { ...childEnv, ...process.env };
778
+ for (const v of AZURE_SCRUBBED) if (!(v in process.env)) delete env[v];
779
+ return env;
780
+ }
781
+
782
+ /** One member's components (a name or a comma list), through chant's own deploy steps, against the emulators. */
783
+ function runComponent(member: string, component: string, env: NodeJS.ProcessEnv = childEnv): void {
263
784
  say(`${member}: chant run --components ${component} --env ${ENV}`);
264
785
  const r = spawnSync(join(RUN, "node_modules", ".bin", "chant"), ["run", "--components", component, "--env", ENV], {
265
786
  cwd: join(RUN, member),
266
- env: { ...childEnv, USER: "three-cloud-demo", GIT_AUTHOR_NAME: "three-cloud demo", GIT_AUTHOR_EMAIL: "demo@three-cloud.test", GIT_COMMITTER_NAME: "three-cloud demo", GIT_COMMITTER_EMAIL: "demo@three-cloud.test" },
787
+ env: { ...env, USER: "three-cloud-demo", GIT_AUTHOR_NAME: "three-cloud demo", GIT_AUTHOR_EMAIL: "demo@three-cloud.test", GIT_COMMITTER_NAME: "three-cloud demo", GIT_COMMITTER_EMAIL: "demo@three-cloud.test" },
267
788
  stdio: "inherit",
268
789
  });
269
790
  if (r.status !== 0) throw new Refusal(`${member}: the ${component} component did not apply (exit ${r.status})`);
270
791
  }
271
792
 
793
+ /**
794
+ * The dns records component's Build step: the template its cfn-deploy step
795
+ * applies, at dns/dist/dns.json. gcpEndpoint defaults to what the gcp member
796
+ * has applied; azureEndpoint and awsEndpoint have no default, since the step
797
+ * passes them from the azure and aws components' outputs. The checks point
798
+ * at the emulators, as in applyFrontDoor; awsCheck at floci only when the aws
799
+ * stack has an endpoint to probe.
800
+ */
801
+ async function buildDns(): Promise<void> {
802
+ const aws = awsEndpoint(join(ROOT, "aws"));
803
+ if ("refused" in aws) say(`aws: no awsEndpoint on the stack yet, so the aws check probes nothing that answers: ${aws.refused}`);
804
+ const gcp = await gcpAddress();
805
+ const params = dnsTemplate(
806
+ { gcpEndpoint: gcp },
807
+ {
808
+ awsCheck: { address: "endpoint" in aws ? containerAddress(CONTAINERS.aws) : "192.0.2.1", port: 80 },
809
+ azureCheck: { address: containerAddress(CONTAINERS.azure), port: 4577 },
810
+ gcpCheck: { address: gcp === "192.0.2.1" ? gcp : containerAddress(CONTAINERS.gcp), port: 80 },
811
+ },
812
+ );
813
+ const dist = join(ROOT, "dns", "dist");
814
+ mkdirSync(dist, { recursive: true });
815
+ cpSync(params, join(dist, "dns.json"));
816
+ say(`dns: ${relative(process.cwd(), join(dist, "dns.json")) || "dist/dns.json"} built, azureEndpoint and awsEndpoint left to the azure and aws components' outputs`);
817
+ }
818
+
819
+ /** The gcp load balancer's address, or 192.0.2.1 (RFC 5737) when there is none. */
820
+ async function gcpAddress(): Promise<string> {
821
+ const addr = (await fetch(`${GCP}/compute/v1/projects/${GCP_PROJECT}/global/addresses/three-cloud-ip`).then((r) => (r.ok ? r.json() : {}), () => ({}))) as { address?: string };
822
+ return addr.address ?? "192.0.2.1";
823
+ }
824
+
272
825
  /** The dns member, with the three endpoints the other members published. */
273
826
  async function applyFrontDoor(gcp: string, azure: string, aws: { endpoint: string } | { refused: string }): Promise<void> {
274
827
  // An aws stack that doesn't apply leaves its record pointing at a name that
@@ -296,14 +849,13 @@ async function applyFrontDoor(gcp: string, azure: string, aws: { endpoint: strin
296
849
  say("dns: applied");
297
850
  }
298
851
 
299
- /** The dns member alone, reading the three endpoints from what is already applied (its component's step). */
852
+ /** The dns member alone, outside chant, reading the three endpoints from what is already applied. */
300
853
  async function applyFrontDoorFromLive(): Promise<void> {
301
- const out = await stackOutputs("three-cloud-aws");
854
+ const aws = awsEndpoint();
302
855
  const app = await getJson(`${appUrl()}?api-version=2024-03-01`);
303
856
  const azure = (app.properties as { configuration?: { ingress?: { fqdn?: string } } } | undefined)?.configuration?.ingress?.fqdn;
304
857
  if (!azure) throw new Refusal("azure: the container app web has no ingress fqdn; apply the azure member first");
305
- const addr = (await fetch(`${GCP}/compute/v1/projects/${GCP_PROJECT}/global/addresses/three-cloud-ip`).then((r) => (r.ok ? r.json() : {}))) as { address?: string };
306
- await applyFrontDoor(addr.address ?? "192.0.2.1", azure, out.awsEndpoint ? { endpoint: out.awsEndpoint } : { refused: "the stack has no awsEndpoint output" });
858
+ await applyFrontDoor(await gcpAddress(), azure, aws);
307
859
  }
308
860
 
309
861
  // ---------------------------------------------------------------------------
@@ -405,38 +957,59 @@ async function awsQuery(service: string, form: Record<string, string>): Promise<
405
957
  return text;
406
958
  }
407
959
 
408
- async function stackStatus(stack: string): Promise<string | undefined> {
409
- try {
410
- const xml = await awsQuery("cloudformation", { Action: "DescribeStacks", Version: "2010-05-15", StackName: stack });
411
- return /<StackStatus>([^<]+)<\/StackStatus>/.exec(xml)?.[1];
412
- } catch {
413
- return undefined;
414
- }
960
+ /** One CloudFormation stack resource's physical id (the dns stack's zone, for oob-edit). */
961
+ async function stackResourceId(stack: string, logical: string): Promise<string> {
962
+ const xml = await awsQuery("cloudformation", { Action: "DescribeStackResource", Version: "2010-05-15", StackName: stack, LogicalResourceId: logical });
963
+ const id = /<PhysicalResourceId>([^<]+)<\/PhysicalResourceId>/.exec(xml)?.[1];
964
+ if (!id) throw new Refusal(`cloudformation: stack ${stack} has no resource ${logical}`);
965
+ return id;
415
966
  }
416
967
 
417
- /** The first resource-level reason a stack's events give for failing. */
418
- async function stackFailure(stack: string): Promise<string | undefined> {
419
- try {
420
- const xml = await awsQuery("cloudformation", { Action: "DescribeStackEvents", Version: "2010-05-15", StackName: stack });
421
- for (const event of xml.split("<member>")) {
422
- const field = (tag: string) => new RegExp(`<${tag}>([^<]*)</${tag}>`).exec(event)?.[1];
423
- const id = field("LogicalResourceId");
424
- const reason = field("ResourceStatusReason");
425
- if (id && id !== stack && field("ResourceStatus") === "CREATE_FAILED" && reason) {
426
- return `${id}: ${reason.replace(/&apos;/g, "'").replace(/&quot;/g, '"')}`;
427
- }
428
- }
429
- } catch {
430
- // no events to read; the applier's own message stands
431
- }
432
- return undefined;
433
- }
968
+ // ---------------------------------------------------------------------------
969
+ // An out-of-band edit, one per engine
434
970
 
435
- async function stackOutputs(stack: string): Promise<Record<string, string>> {
436
- const xml = await awsQuery("cloudformation", { Action: "DescribeStacks", Version: "2010-05-15", StackName: stack });
437
- const out: Record<string, string> = {};
438
- for (const m of xml.matchAll(/<OutputKey>([^<]+)<\/OutputKey>\s*<OutputValue>([^<]*)<\/OutputValue>/g)) out[m[1]!] = m[2]!;
439
- return out;
971
+ /** The members oob-edit knows an edit for, and what it changes. */
972
+ export const OOB_EDITS = {
973
+ dns: "the hosted zone's comment, through Route 53 (chant's live read compares HostedZoneConfig)",
974
+ gcp: "a label on the Cloud Run service three-cloud-site (chant's live read compares labels)",
975
+ azure: "a tag on the Container App web, beside its ownership markers (choudoufu's plan reads tags)",
976
+ aws: "the retention of the log group /ecs/three-cloud-aws-web, 7 days to 14 (plunge drift refreshes it)",
977
+ } as const;
978
+
979
+ /**
980
+ * One edit to a member's live resources that its source does not make, made
981
+ * straight against the emulator, the way a person in a console would: no
982
+ * chant, choudoufu or plunge runs it, so each engine has to notice it on its
983
+ * own read, and behold's card for that resource goes from in sync to
984
+ * drifted. For the maintainer's live run (behold#1000); nothing else calls it.
985
+ */
986
+ export async function oobEdit(member: string): Promise<void> {
987
+ if (member === "dns") {
988
+ const zone = (await stackResourceId(ENV, "zone")).replace(/^\/?hostedzone\//, "");
989
+ const body = `<?xml version="1.0" encoding="UTF-8"?><UpdateHostedZoneCommentRequest xmlns="https://route53.amazonaws.com/doc/2013-04-01/"><Comment>edited out of band (behold#1000)</Comment></UpdateHostedZoneCommentRequest>`;
990
+ const res = await fetch(`${AWS}/2013-04-01/hostedzone/${zone}`, { method: "POST", headers: { "content-type": "application/xml", authorization: "AWS4-HMAC-SHA256 Credential=test/20260101/us-east-1/route53/aws4_request, SignedHeaders=host, Signature=0" }, body });
991
+ if (!res.ok) throw new Refusal(`dns: UpdateHostedZoneComment on ${zone} answered ${res.status}: ${(await res.text()).slice(0, 300)}`);
992
+ } else if (member === "gcp") {
993
+ const location = /kind:\s*RunService[\s\S]*?^\s+location:\s*['"]?([a-z0-9-]+)/m.exec(readFileSync(build("gcp"), "utf8"))?.[1] ?? "us-central1";
994
+ const url = `${GCP}/v2/projects/${GCP_PROJECT}/locations/${location}/services/three-cloud-site`;
995
+ const svc = (await getJson(url)) as { labels?: Record<string, string> };
996
+ const res = await fetch(`${url}?updateMask=labels`, { method: "PATCH", headers: { "content-type": "application/json" }, body: JSON.stringify({ labels: { ...(svc.labels ?? {}), "edited-out-of-band": "behold-1000" } }) });
997
+ if (!res.ok) throw new Refusal(`gcp: patching three-cloud-site's labels answered ${res.status}: ${(await res.text()).slice(0, 300)}`);
998
+ } else if (member === "azure") {
999
+ const app = (await getJson(`${appUrl()}?api-version=2024-03-01`)) as { tags?: Record<string, string> };
1000
+ const res = await fetch(`${appUrl()}?api-version=2024-03-01`, { method: "PATCH", headers: { "content-type": "application/json" }, body: JSON.stringify({ tags: { ...(app.tags ?? {}), "edited-out-of-band": "behold-1000" } }) });
1001
+ if (!res.ok) throw new Refusal(`azure: patching the container app web's tags answered ${res.status}: ${(await res.text()).slice(0, 300)}`);
1002
+ } else if (member === "aws") {
1003
+ const res = await fetch(`${AWS}/`, {
1004
+ method: "POST",
1005
+ headers: { "content-type": "application/x-amz-json-1.1", "x-amz-target": "Logs_20140328.PutRetentionPolicy", authorization: "AWS4-HMAC-SHA256 Credential=test/20260101/us-east-1/logs/aws4_request, SignedHeaders=host, Signature=0" },
1006
+ body: JSON.stringify({ logGroupName: "/ecs/three-cloud-aws-web", retentionInDays: 14 }),
1007
+ });
1008
+ if (!res.ok) throw new Refusal(`aws: PutRetentionPolicy on /ecs/three-cloud-aws-web answered ${res.status}: ${(await res.text()).slice(0, 300)}`);
1009
+ } else {
1010
+ throw new Refusal(`oob-edit: no edit for ${member}; one of ${Object.keys(OOB_EDITS).join(", ")}`);
1011
+ }
1012
+ say(`${member}: edited out of band: ${OOB_EDITS[member as keyof typeof OOB_EDITS]}`);
440
1013
  }
441
1014
 
442
1015
  // ---------------------------------------------------------------------------
@@ -445,15 +1018,35 @@ async function main(argv: string[]): Promise<void> {
445
1018
  const [step, ...rest] = argv;
446
1019
  const outAt = rest.indexOf("--out");
447
1020
  const out = outAt >= 0 ? rest[outAt + 1] : undefined;
448
- if (step === "apply") return apply();
449
- // One member at a time, outside chant: apply-dns is the dns component's step; the others apply as before components ran them.
1021
+ if (step === "plan") {
1022
+ if (!out) throw new Refusal("plan needs --out <file>");
1023
+ return void (await plan(out));
1024
+ }
1025
+ if (step === "apply") {
1026
+ const setAt = rest.indexOf("--change-set");
1027
+ if (setAt < 0) return apply();
1028
+ const file = rest[setAt + 1];
1029
+ if (!file) throw new Refusal("apply --change-set needs <file>, a document `plan --out` wrote");
1030
+ return applyApproved(file);
1031
+ }
1032
+ // One member at a time, outside chant: apply-azure is the estate's choudoufu apply, apply-aws the
1033
+ // program's plunge up, apply-dns applies dns with all three endpoints read here; gcp applies as before
1034
+ // components ran it. build-dns is the dns records component's Build step.
1035
+ if (step === "build-dns") return buildDns();
1036
+ if (step === "pr-plan-dns") {
1037
+ const baseAt = rest.indexOf("--base");
1038
+ const base = baseAt >= 0 ? rest[baseAt + 1] : undefined;
1039
+ if (!base || !out) throw new Refusal("pr-plan-dns needs --base <ref> and --out <dir>");
1040
+ return prPlanDns(base, out);
1041
+ }
450
1042
  if (step === "apply-gcp") return void say(`gcp: the load balancer answers on ${await applyGcp()}`);
451
1043
  if (step === "apply-azure") return void say(`azure: web answers as ${await applyAzure()}`);
452
- if (step === "apply-aws") {
453
- const aws = await applyAws();
454
- return void say("refused" in aws ? `aws: NOT APPLIED: ${aws.refused}` : `aws: web answers as ${aws.endpoint}`);
455
- }
1044
+ if (step === "apply-aws") return void say(`aws: web answers as ${await applyAws()}`);
456
1045
  if (step === "apply-dns") return applyFrontDoorFromLive();
1046
+ if (step === "oob-edit") {
1047
+ if (!rest[0]) throw new Refusal(`oob-edit needs a member: ${Object.keys(OOB_EDITS).join(", ")}`);
1048
+ return oobEdit(rest[0]);
1049
+ }
457
1050
  if (step === "azure-off") return azureOff();
458
1051
  if (step === "wait") return waitFor("unhealthy");
459
1052
  if (step === "export" || step === "all") {
@@ -465,10 +1058,10 @@ async function main(argv: string[]): Promise<void> {
465
1058
  }
466
1059
  return exportPage(out);
467
1060
  }
468
- throw new Refusal("usage: front-door.ts all|apply|apply-gcp|apply-azure|apply-aws|apply-dns|azure-off|wait|export [--out <dir>]");
1061
+ throw new Refusal("usage: front-door.ts all|plan|apply [--change-set <file>]|apply-gcp|apply-azure|apply-aws|apply-dns|build-dns|pr-plan-dns|oob-edit <member>|azure-off|wait|export [--out <dir>|<file>] [--base <ref>]");
469
1062
  }
470
1063
 
471
1064
  main(process.argv.slice(2)).catch((e: unknown) => {
472
1065
  process.stderr.write(`front-door: ${e instanceof Error ? e.message : String(e)}\n`);
473
- process.exit(e instanceof Refusal ? 2 : 1);
1066
+ process.exit(e instanceof PlanMoved ? PLAN_MOVED_EXIT_CODE : e instanceof Refusal ? 2 : 1);
474
1067
  });