@arcote.tech/arc-cli 0.7.19 → 0.7.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcote.tech/arc-cli",
-  "version": "0.7.19",
+  "version": "0.7.21",
   "description": "CLI tool for Arc framework",
   "module": "index.ts",
   "main": "dist/index.js",
@@ -12,13 +12,13 @@
     "build": "bun build --target=bun ./src/index.ts --outdir=dist --external @arcote.tech/arc --external @arcote.tech/arc-ds --external @arcote.tech/arc-react --external @arcote.tech/platform --external '@opentelemetry/*' && chmod +x dist/index.js"
   },
   "dependencies": {
-    "@arcote.tech/arc": "^0.7.19",
-    "@arcote.tech/arc-ds": "^0.7.19",
-    "@arcote.tech/arc-react": "^0.7.19",
-    "@arcote.tech/arc-host": "^0.7.19",
-    "@arcote.tech/arc-adapter-db-sqlite": "^0.7.19",
-    "@arcote.tech/arc-adapter-db-postgres": "^0.7.19",
-    "@arcote.tech/arc-otel": "^0.7.19",
+    "@arcote.tech/arc": "^0.7.21",
+    "@arcote.tech/arc-ds": "^0.7.21",
+    "@arcote.tech/arc-react": "^0.7.21",
+    "@arcote.tech/arc-host": "^0.7.21",
+    "@arcote.tech/arc-adapter-db-sqlite": "^0.7.21",
+    "@arcote.tech/arc-adapter-db-postgres": "^0.7.21",
+    "@arcote.tech/arc-otel": "^0.7.21",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/api-logs": "^0.57.0",
     "@opentelemetry/core": "^1.30.0",
@@ -31,7 +31,7 @@
     "@opentelemetry/sdk-trace-base": "^1.30.0",
     "@opentelemetry/sdk-trace-node": "^1.30.0",
     "@opentelemetry/semantic-conventions": "^1.27.0",
-    "@arcote.tech/platform": "^0.7.19",
+    "@arcote.tech/platform": "^0.7.21",
     "@clack/prompts": "^0.9.0",
     "commander": "^11.1.0",
     "chokidar": "^3.5.3",

package/src/builder/access-extractor.ts

@@ -7,7 +7,6 @@ import {
   writeFileSync,
 } from "fs";
 import { join } from "path";
-import { isContextPackage, type WorkspacePackage } from "./module-builder";
 
 // ---------------------------------------------------------------------------
 // access-extractor — discovers per-module access rules (`protectedBy(...)`)
@@ -27,8 +26,8 @@ import { isContextPackage, type WorkspacePackage } from "./module-builder";
 // non-context (pure-browser) packages are skipped. This is sensible: access
 // checks logically belong with server state, not display components.
 //
-// Order requirement: buildContextPackages MUST run before extractAccessMap
-// — server bundles at `packages/<pkg>/dist/server/main/index.js` must exist.
+// Order requirement: buildServerApp MUST run before extractAccessMap — the
+// combined server bundle at `<arcDir>/server/_server.js` must exist.
 // ---------------------------------------------------------------------------
 
 export interface SerializedAccessRule {
@@ -44,19 +43,16 @@ export type SerializedAccessMap = Record<string, SerializedModuleAccess>;
 
 export async function extractAccessMap(
   rootDir: string,
-  packages: readonly WorkspacePackage[],
+  serverBundlePath: string,
 ): Promise<SerializedAccessMap> {
-  // Each entry: a context-package server bundle path that the worker will
-  // dynamically import. Bun resolves the bundle's internal external imports
-  // (`@arcote.tech/platform` etc.) via node_modules walking from the bundle
-  // location — workspace symlinks point back to source.
-  const serverBundles = packages
-    .filter((p) => isContextPackage(p.packageJson))
-    .map((p) => ({
-      name: p.name,
-      path: join(p.path, "dist", "server", "main", "index.js"),
-    }))
-    .filter((b) => existsSync(b.path));
+  // The combined server bundle (`<arcDir>/server/_server.js`) side-effect-
+  // registers every module via the platform singleton when imported. The
+  // worker imports just this entry; Bun resolves its `chunk-<hash>.js` siblings
+  // and external peers (`@arcote.tech/platform` etc.) by walking node_modules
+  // from the bundle's directory.
+  const serverBundles = existsSync(serverBundlePath)
+    ? [{ name: "server", path: serverBundlePath }]
+    : [];
 
   // Worker must live INSIDE the workspace tree so Bun's module resolver can
   // walk up to <rootDir>/node_modules and find @arcote.tech/platform via the

package/src/builder/module-builder.ts

@@ -18,7 +18,7 @@ import {
   type BuildCache,
 } from "./build-cache";
 import type { ChunkPlan } from "./chunk-planner";
-import { SHELL_EXTERNALS } from "./framework-peers";
+import { SHELL_EXTERNALS, FRAMEWORK_PEERS } from "./framework-peers";
 import {
   readInstalledVersion,
   sha256Hex,
@@ -125,6 +125,43 @@ function serverExternalsPlugin(): import("bun").BunPlugin {
   };
 }
 
+/**
+ * SERVER bundles inline their workspace (`@ndt/*`) deps so each flattened
+ * `.arc/platform/server/<pkg>.js` is self-contained (the deploy image has no
+ * `node_modules/@ndt/*` tree). Bun would resolve a bare `@ndt/x` import through
+ * package.json `exports` to that dep's PRE-BUILT `dist/server/main/index.js` —
+ * an already-fully-inlined bundle. Nesting one fully-inlined bundle inside
+ * every consumer is catastrophic:
+ *   - diamonds duplicate the shared dep per graph edge (2^depth copies),
+ *   - dist/ is never wiped, so stale bombs from a previous dep graph keep
+ *     getting re-inlined across rebuilds.
+ * Result: bundles ballooned into the hundreds-of-MB / GB range (content =
+ * 1.1 GB, sizes lining up as powers of two by graph depth).
+ *
+ * This plugin pins every workspace package name to its SOURCE entrypoint
+ * (`src/index.ts`). The single Bun.build pass then includes each transitive
+ * module exactly once (Bun dedups by resolved path), so a server bundle is the
+ * size of its UNIQUE source closure — no nesting, no stale re-inlining.
+ *
+ * `sideEffects: true` keeps the dep's top-level `module(...).build()`
+ * registration from being tree-shaken when it's imported only for a named
+ * symbol (workspace packages ship `"sideEffects": false`).
+ */
+function workspaceSourcePlugin(srcByName: Map<string, string>): import("bun").BunPlugin {
+  return {
+    name: "workspace-source",
+    setup(build) {
+      // Bare specifiers only (skip relative `./` and absolute `/`). Non-
+      // workspace bare imports (react, @arcote.tech/*, npm deps) miss the map
+      // and fall through to the `external` list unchanged.
+      build.onResolve({ filter: /^[^./]/ }, (args) => {
+        const src = srcByName.get(args.path);
+        return src ? { path: src, sideEffects: true } : null;
+      });
+    },
+  };
+}
+
 function jsxDevShimPlugin(): import("bun").BunPlugin {
   return {
     name: "jsx-dev-runtime-shim",
@@ -145,12 +182,25 @@ export { Fragment };
   };
 }
 
-/** Clients that a context package is built for. */
+// Per-package context build is BROWSER-only. The server side is produced by a
+// single combined `buildServerApp` pass (see below) — bundling each package's
+// server context separately and inlining its deps' pre-built dist caused
+// catastrophic nested duplication (content.js hit 1.1 GB) and turned the
+// consumer's undeclared cyclic `@ndt/*` imports into broken init order. One
+// shared pass dedups every module once and is cycle-safe (same as the browser
+// app build).
 const CONTEXT_CLIENTS = [
-  { name: "server", target: "bun" as const, defines: { ONLY_SERVER: "true", ONLY_BROWSER: "false", ONLY_CLIENT: "false" } },
   { name: "browser", target: "browser" as const, defines: { ONLY_SERVER: "false", ONLY_BROWSER: "true", ONLY_CLIENT: "true" } },
 ];
 
+/** Server-side build defines — applied by the combined `buildServerApp` pass. */
+const SERVER_DEFINES = { ONLY_SERVER: "true", ONLY_BROWSER: "false", ONLY_CLIENT: "false" } as const;
+
+/** Filename of the combined server bundle entry under `<arcDir>/server/`.
+ *  loadServerContext + the access extractor import exactly this file; Bun's
+ *  auto-emitted `chunk-<hash>.js` siblings are pulled in transitively. */
+export const SERVER_ENTRY_FILE = "_server.js";
+
 export interface WorkspacePackage {
   name: string;
   path: string;
@@ -305,32 +355,16 @@ async function buildContextClient(
 
   console.log(`  building: ${pkg.name} (${client.name})`);
 
-  // Externals depend on the target client:
-  //
-  // - BROWSER client: workspace deps MUST be external. Inlining them per
-  //   package would make every context package's dist ship its own copy
-  //   of every workspace dep — the top-level browser Bun.build would see
-  //   N pre-inlined copies of context singletons (`WorkspaceContext =
-  //   createContext`) and could not dedupe them, breaking provider lookup.
-  //
-  // - SERVER client: workspace deps MUST be bundled inline. The deploy
-  //   image flattens each package's server bundle to
-  //   `.arc/platform/server/<pkg>.js` and runs them via a single
-  //   `loadServerContext()` import loop. There is no `node_modules/@ndt/*`
-  //   tree inside the image, so bare `@ndt/workspace` specifiers would
-  //   fail to resolve at startup. Inline duplication is harmless on the
-  //   server: it's a single Node/Bun process and Arc modules register via
-  //   a shared platform registry singleton (registry.ts), so two physical
-  //   copies of the workspace module still merge into one context.
+  // BROWSER client: every dep (workspace + npm + framework peers) is external.
+  // Inlining workspace deps per package would make each context package's dist
+  // ship its own copy of every workspace dep — the top-level browser Bun.build
+  // (`buildBrowserApp`) would then see N pre-inlined copies of context
+  // singletons (`WorkspaceContext = createContext`) and could not dedupe them,
+  // breaking provider lookup. The server side is handled separately by the
+  // combined `buildServerApp` pass.
   const peerDeps = Object.keys(pkg.packageJson.peerDependencies ?? {});
   const allDeps = (pkg.packageJson.dependencies ?? {}) as Record<string, string>;
-  const isBrowser = client.name === "browser";
-  const workspaceDeps = isBrowser
-    ? Object.keys(allDeps)
-    : Object.entries(allDeps)
-        .filter(([, spec]) => !spec.startsWith("workspace:"))
-        .map(([name]) => name);
-  const externals = [...peerDeps, ...workspaceDeps];
+  const externals = [...peerDeps, ...Object.keys(allDeps)];
 
   const result = await Bun.build({
     entrypoints: [pkg.entrypoint],
@@ -339,9 +373,7 @@ async function buildContextClient(
     format: "esm",
     naming: "index.[ext]",
     external: externals,
-    plugins: isBrowser
-      ? [jsxDevShimPlugin()]
-      : [jsxDevShimPlugin(), serverExternalsPlugin()],
+    plugins: [jsxDevShimPlugin()],
     define: client.defines,
   });
 
@@ -385,11 +417,13 @@ export async function buildContextPackages(
   const contexts = packages.filter((p) => isContextPackage(p.packageJson));
   if (contexts.length === 0) return { declarationErrors: [] };
 
-  // Topological order — each package's server bundle inlines its workspace
-  // deps, so those deps must have their `dist/` ready before Bun.build tries
-  // to resolve them. Without this, a fresh checkout (no dist/ yet) fails the
-  // first build because content's resolve of @ndt/strategy hits a missing
-  // file. Inside a topological level, packages are built in parallel.
+  // Topological order by declared `workspace:` deps. The browser BUNDLE
+  // externalizes every dep (order-independent), but the type-declaration pass
+  // (tsc) resolves `@ndt/x` types through that package's emitted
+  // `dist/browser/index.d.ts` — so a dep's declarations must exist before a
+  // dependent's decl build runs, else tsc reports "Cannot find module @ndt/x".
+  // The declared dep graph is acyclic; undeclared cyclic imports live in source
+  // only and don't affect this ordering. Inside a layer, packages build in parallel.
   const byName = new Map(contexts.map((p) => [p.name, p]));
   const remaining = new Set(contexts.map((p) => p.name));
   const done = new Set<string>();
@@ -440,6 +474,147 @@ export async function buildContextPackages(
   return { declarationErrors };
 }
 
+// ---------------------------------------------------------------------------
+// Combined server bundle — ONE Bun.build for ALL context packages' server side.
+//
+// Replaces N per-package server builds that each inlined their deps' PRE-BUILT
+// dist (`@ndt/x` → `x/dist/server/main/index.js`). That nested an already-
+// fully-inlined bundle inside every consumer: shared deps duplicated per graph
+// edge (content's server bundle reached 1.1 GB) and the consumer's undeclared
+// cyclic `@ndt/*` imports turned into broken module-init order.
+//
+// One shared pass with `splitting: true` — the same recipe as buildBrowserApp:
+//   - every module is bundled from SOURCE exactly once (Bun dedups by path),
+//   - `@ndt/*` workspace deps resolve to their `src/` entry (workspaceSourcePlugin)
+//     so nothing pulls a pre-built dist,
+//   - npm deps + framework peers stay external — the deploy image installs them
+//     into /app/node_modules via `.arc/platform/package.json` (collectFrameworkDeps),
+//   - splitting makes Bun emit eager top-level init, which is cycle-safe; the
+//     old non-split per-package build emitted lazy `__esm` wrappers that broke
+//     under the consumer's import cycles (`workspace.ids` was undefined).
+//
+// Output under `<arcDir>/server/`:
+//   _server.js          ← entry: side-effect-imports every context module
+//   chunk-<hash>.js × N ← auto-shared module chunks
+// loadServerContext + the access extractor import `_server.js`; chunks ride along.
+// ---------------------------------------------------------------------------
+
+export interface ServerAppResult {
+  readonly entryFile: string;
+  readonly cached: boolean;
+}
+
+export async function buildServerApp(
+  rootDir: string,
+  serverDir: string,
+  packages: WorkspacePackage[],
+  cache: BuildCache,
+  noCache: boolean,
+): Promise<ServerAppResult> {
+  void rootDir; // resolution is source-based; rootDir kept for signature parity
+  const contexts = packages.filter((p) => isContextPackage(p.packageJson));
+  mkdirSync(serverDir, { recursive: true });
+
+  // Every workspace package name → its SOURCE entry. Spans ALL packages, not
+  // just context ones — a context package imports non-context workspace libs
+  // (e.g. content-core) that must inline from source too.
+  const srcByName = new Map(packages.map((p) => [p.name, p.entrypoint]));
+
+  // External = framework peers + every non-workspace npm dep any package
+  // declares. NOT bundled; resolved at runtime from /app/node_modules (the
+  // deploy image installs exactly this set — collectFrameworkDeps). Only the
+  // `@ndt/*` workspace source is inlined.
+  const externalSet = new Set<string>(FRAMEWORK_PEERS);
+  for (const p of packages) {
+    for (const name of Object.keys(p.packageJson.peerDependencies ?? {})) {
+      externalSet.add(name);
+    }
+    for (const [name, spec] of Object.entries(
+      (p.packageJson.dependencies ?? {}) as Record<string, string>,
+    )) {
+      if (!spec.startsWith("workspace:")) externalSet.add(name);
+    }
+  }
+  const external = [...externalSet];
+
+  const unitId = "server-app";
+  const inputHash = sha256OfJson({
+    members: packages
+      .map((p) => ({ name: p.name, src: pkgSourceHash(p) }))
+      .sort((a, b) => a.name.localeCompare(b.name)),
+    contexts: contexts.map((p) => p.name).sort(),
+    external: [...external].sort(),
+    defines: SERVER_DEFINES,
+  });
+
+  const entryFileAbs = join(serverDir, SERVER_ENTRY_FILE);
+  if (!noCache && isCacheHit(cache, unitId, inputHash, [entryFileAbs])) {
+    console.log(`  ✓ cached: ${unitId}`);
+    return { entryFile: SERVER_ENTRY_FILE, cached: true };
+  }
+
+  console.log(`  building: ${unitId} (${contexts.length} server modules)`);
+
+  // Wipe stale .js — old per-package flattened bundles AND previous chunks —
+  // so a smaller rebuild never leaves orphaned content-addressed chunks behind.
+  for (const f of readdirSync(serverDir)) {
+    if (f.endsWith(".js")) rmSync(join(serverDir, f), { force: true });
+  }
+
+  // Entry side-effect-imports every context module so each registers via the
+  // platform registry singleton. Written to a tmp subdir so it isn't shipped.
+  const tmpDir = join(serverDir, "_entries");
+  mkdirSync(tmpDir, { recursive: true });
+  const entrySrc = join(tmpDir, SERVER_ENTRY_FILE.replace(/\.js$/, ".ts"));
+  writeFileSync(
+    entrySrc,
+    contexts.map((p) => `import "${p.name}";`).join("\n") + "\n",
+  );
+
+  let result;
+  try {
+    result = await Bun.build({
+      entrypoints: [entrySrc],
+      outdir: serverDir,
+      target: "bun",
+      format: "esm",
+      // splitting:true is the whole point — it makes Bun emit eager top-level
+      // init (cycle-safe) instead of lazy `__esm` wrappers. Shared modules land
+      // in chunk-<hash>.js referenced by the entry.
+      splitting: true,
+      naming: "[name].[ext]",
+      external,
+      plugins: [
+        jsxDevShimPlugin(),
+        serverExternalsPlugin(),
+        workspaceSourcePlugin(srcByName),
+      ],
+      define: SERVER_DEFINES,
+    });
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true });
+  }
+
+  if (!result.success) {
+    for (const log of result.logs) console.error(log);
+    throw new Error("Server app build failed");
+  }
+
+  const entryOut = result.outputs.find((o) => o.kind === "entry-point");
+  if (!entryOut) {
+    throw new Error("Server app build: entry not found in outputs");
+  }
+  if (basename(entryOut.path) !== SERVER_ENTRY_FILE) {
+    throw new Error(
+      `Server app build: unexpected entry name ${basename(entryOut.path)} (wanted ${SERVER_ENTRY_FILE})`,
+    );
+  }
+
+  const outputHash = sha256OfDir(serverDir);
+  updateCache(cache, unitId, inputHash, { outputHash });
+  return { entryFile: SERVER_ENTRY_FILE, cached: false };
+}
+
 
 // ---------------------------------------------------------------------------
 // Browser app build — one Bun.build with multiple entrypoints.

package/src/deploy/bootstrap.ts

@@ -133,6 +133,9 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
   //   - stack isn't fully ready, OR
   //   - marker is missing (legacy v0.5 deploy with no .arc-state.json), OR
   //   - configHash differs from last bootstrap (deploy.arc.json changed), OR
+  //   - the CLI version changed (generators evolve — compose/Caddyfile/
+  //     observability configs must be re-rendered + re-uploaded even when
+  //     deploy.arc.json itself is unchanged), OR
   //   - registry container isn't running (e.g. legacy stack predates v0.7)
   // Without this, an old v0.5 stack (no registry container) is classified as
   // "ready" and bootstrap is skipped — then `docker login` on the next step
@@ -141,6 +144,7 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
     state.kind !== "ready" ||
     state.marker === null ||
     state.marker.configHash !== inputs.configHash ||
+    state.marker.cliVersion !== inputs.cliVersion ||
     !(await isRegistryRunning(cfg));
 
   if (needUpStack) {
@@ -156,7 +160,7 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
   // without forcing a full bootstrap.
   if (cfg.observability?.enabled) {
     log("Ensuring observability sidecars are running...");
-    const obsServices = ["otel-collector", "tempo", "loki", "prometheus", "grafana"];
+    const obsServices = ["otel-collector", "tempo", "loki", "prometheus", "alloy", "grafana"];
     await assertExec(
       cfg.target,
       `cd ${cfg.target.remoteDir} && docker compose pull --ignore-pull-failures ${obsServices.join(" ")} && docker compose up -d ${obsServices.join(" ")}`,
@@ -307,10 +311,11 @@ async function upStack(inputs: BootstrapInputs): Promise<void> {
   // `observability/` directory referenced by compose bind-mounts.
   if (observabilityFiles && observabilityHtpasswd) {
     // Make sure both the top-level `observability/` dir and the nested
-    // `grafana-dashboards/` exist before scp tries to land files there.
+    // `grafana-dashboards/` + `grafana-alerting/` exist before scp tries
+    // to land files there.
     await assertExec(
       cfg.target,
-      `mkdir -p ${cfg.target.remoteDir}/observability/grafana-dashboards`,
+      `mkdir -p ${cfg.target.remoteDir}/observability/grafana-dashboards ${cfg.target.remoteDir}/observability/grafana-alerting`,
     );
     // Make sure local nested dir exists too — `generateObservabilityConfigs`
     // returns relative paths like `observability/grafana-dashboards/x.json`

package/src/deploy/caddyfile.ts

@@ -20,23 +20,48 @@ export function generateCaddyfile(cfg: DeployConfig): string {
     cfg.caddy.email === "internal" ? "" : `\n    email ${cfg.caddy.email}`;
   const tlsDirective =
     cfg.caddy.email === "internal" ? "\n    tls internal" : "";
+  const observability = cfg.observability?.enabled === true;
+
+  // Access logs land on stdout as JSON → Alloy tails the container → Loki
+  // (`{compose_service="caddy"}`). Off by default in Caddy, hence per-vhost.
+  const logDirective = observability
+    ? ["    log {", "        output stdout", "        format json", "    }"]
+    : [];
 
   const lines: string[] = [];
   lines.push("# Generated by `arc platform deploy` — do not edit by hand.");
   lines.push("");
   lines.push("{");
   lines.push("    admin off");
+  if (observability) {
+    // Per-request HTTP metrics (caddy_http_*). Top-level global option —
+    // requires Caddy >= 2.9 (the `servers > metrics` form is deprecated).
+    lines.push("    metrics {");
+    lines.push("        per_host");
+    lines.push("    }");
+  }
   if (email) lines.push(`   ${email.trim()}`);
   lines.push("}");
   lines.push("");
 
+  // Exposition endpoint for Prometheus (scrapes caddy:2020 on arc-net).
+  // Plain HTTP, never exposed publicly; works with `admin off` (only the
+  // admin-API /metrics endpoint dies with the admin interface).
+  if (observability) {
+    lines.push(":2020 {");
+    lines.push("    metrics");
+    lines.push("}");
+    lines.push("");
+  }
+
   // Public blocks — one per env. When observability is on, add a `/otel/*`
   // path that forwards browser-side OTLP/HTTP to the collector. Strips the
   // /otel prefix so the collector sees the same /v1/{traces,logs,metrics}
   // paths it would receive from same-network senders.
   for (const [name, env] of Object.entries(cfg.envs)) {
     lines.push(`${env.domain} {${tlsDirective}`);
-    if (cfg.observability?.enabled) {
+    lines.push(...logDirective);
+    if (observability) {
       lines.push("    handle_path /otel/* {");
       lines.push("        reverse_proxy otel-collector:4318");
       lines.push("    }");
@@ -54,13 +79,11 @@ export function generateCaddyfile(cfg: DeployConfig): string {
   // the apex of the first env's domain (e.g. observability.app.example.com
   // when the primary env is app.example.com). Caddy issues a separate
   // ACME certificate for this hostname.
-  if (cfg.observability?.enabled) {
-    const firstEnv = Object.values(cfg.envs)[0];
-    if (firstEnv) {
-      const subdomain = cfg.observability.subdomain ?? "observability";
-      const apex = apexOf(firstEnv.domain);
-      const observabilityDomain = `${subdomain}.${apex}`;
-      lines.push(`${observabilityDomain} {${tlsDirective}`);
+  if (observability) {
+    const domain = observabilityDomain(cfg);
+    if (domain) {
+      lines.push(`${domain} {${tlsDirective}`);
+      lines.push(...logDirective);
       // Basic-auth credentials live in the same htpasswd file used for the
       // registry — bootstrap appends an "admin" line with bcrypted password.
       lines.push("    basic_auth {");
@@ -77,6 +100,7 @@ export function generateCaddyfile(cfg: DeployConfig): string {
   // 5 GiB request body cap fits real app images comfortably (default 100MB
   // triggers 413 on the first layer push).
   lines.push(`${cfg.registry.domain} {${tlsDirective}`);
+  lines.push(...logDirective);
   lines.push("    reverse_proxy registry:5000 {");
   lines.push("        header_up Host {host}");
   lines.push("    }");
@@ -88,6 +112,17 @@ export function generateCaddyfile(cfg: DeployConfig): string {
   return lines.join("\n") + "\n";
 }
 
+/** Public hostname of the Grafana UI (`<subdomain>.<apex-of-first-env>`), or
+ *  null when observability is off / no envs exist. Shared by the Caddyfile
+ *  vhost and Grafana's GF_SERVER_ROOT_URL (compose.ts). */
+export function observabilityDomain(cfg: DeployConfig): string | null {
+  if (!cfg.observability?.enabled) return null;
+  const firstEnv = Object.values(cfg.envs)[0];
+  if (!firstEnv) return null;
+  const subdomain = cfg.observability.subdomain ?? "observability";
+  return `${subdomain}.${apexOf(firstEnv.domain)}`;
+}
+
 /** Apex of a (possibly-subdomain) host. `app.example.com` → `example.com`,
  *  `example.com` → `example.com`, `example.co.uk` → `co.uk` (approximate —
  *  good enough for the observability subdomain). */