@caelo-cms/provisioning 0.1.0

package/caddy/Caddyfile.production

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: MPL-2.0
+#
+# Production vhost. No noindex header — the bot-indexing behavior comes
+# straight from each page's emitted robots.txt (CMS_REQUIREMENTS §8.3).
+#
+# P6.2 — root is /srv/current, a symlink the deploy.trigger /
+# deploy.promote / deploy.rollback ops atomically re-target. The
+# routing manifest (/srv/current/routing-manifest.json) lists every
+# emitted page + its output path; P9 will swap this Caddyfile for one
+# that consults the manifest to handle locale URL strategies, and P13
+# will use the same indirection for A/B variant edge selection.
+
+:80 {
+	root * /srv/current
+	encode gzip
+	try_files {path} {path}/index.html
+	file_server
+}

package/caddy/Caddyfile.staging

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: MPL-2.0
+#
+# Staging vhost. Per CMS_REQUIREMENTS §16.5 staging is always noindexed at
+# the serving layer (not just via robots.txt body) — `X-Robots-Tag:
+# noindex, nofollow` is enforced here so a misconfigured robots.txt can
+# never accidentally let a bot index a staging page.
+#
+# `try_files` falls back to <slug>/index.html so the page-output paths
+# the static generator emits ("about/index.html") work as clean URLs.
+#
+# P6.2 — root is /srv/current, a symlink the deploy.trigger op atomically
+# re-targets to the most recent build. Caddy follows the symlink at
+# request time so a deploy is invisible to in-flight requests.
+
+:80 {
+	root * /srv/current
+	encode gzip
+	header X-Robots-Tag "noindex, nofollow"
+	try_files {path} {path}/index.html
+	file_server
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@caelo-cms/provisioning",
+  "version": "0.1.0",
+  "private": false,
+  "license": "MPL-2.0",
+  "description": "Pulumi-driven provisioning for Caelo CMS — `bunx @caelo-cms/provisioning --provider <self-hosted|gcp|aws|azure>` brings up a TLS-served install with Postgres + storage + secrets manager + the admin + the API gateway.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "cms-provision": "./src/cli.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc -b"
+  },
+  "dependencies": {
+    "@pulumi/aws": "^7",
+    "@pulumi/awsx": "^3",
+    "@pulumi/azure-native": "^3",
+    "@pulumi/command": "^1",
+    "@pulumi/gcp": "^9",
+    "@pulumi/pulumi": "^3"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P15 — shared cloud-provider adapter contract.
+ *
+ * Every per-provider Pulumi stack at `packages/provisioning/stacks/<provider>/`
+ * exports a `provision(inputs: CloudAdapterInputs): CloudAdapterOutputs`
+ * function. The Caelo runtime never knows which provider it's running
+ * on — it just consumes the connection strings + URLs the adapter
+ * publishes via `CloudAdapterOutputs`. This keeps the per-provider
+ * surface small (~6 capabilities, see master plan) and the runtime
+ * provider-agnostic.
+ *
+ * Pulumi types are intentionally NOT imported here so that callers
+ * outside the Pulumi runtime (e.g. the cms-provision CLI, the admin
+ * app's DNS-guidance page) can consume the *plain* shape without
+ * dragging in the @pulumi/pulumi peer dep. Per-stack `index.ts` files
+ * narrow the output type to `pulumi.Output<T>` at their boundary.
+ */
+
+export type Environment = "dev" | "staging" | "production";
+export type LocaleStrategy = "subdirectory" | "subdomain" | "domain";
+
+export interface LocaleConfig {
+  /** ISO code, e.g. "en", "de", "fr-CA". */
+  readonly code: string;
+  /** URL strategy. Mixed strategies in one install are explicitly supported. */
+  readonly strategy: LocaleStrategy;
+  /** Required when strategy is "subdomain" or "domain"; ignored for "subdirectory". */
+  readonly host?: string;
+}
+
+export interface CloudAdapterInputs {
+  /** Primary domain (e.g. example.com). Admin + production public both bind here. */
+  readonly domain: string;
+  /** Operator email used for ACME / cert provisioning + Pulumi notifications. */
+  readonly ownerEmail: string;
+  /** Three-env model (CMS_REQUIREMENTS §16.5). Cloud installs always provision all three. */
+  readonly environments: ReadonlyArray<Environment>;
+  /** Per-locale routing config — drives per-domain cert + DNS guidance + edge routing. */
+  readonly locales: ReadonlyArray<LocaleConfig>;
+  /** Optional pre-existing secret references (e.g. from a CI secrets manager). */
+  readonly preProvisionedSecrets?: {
+    readonly anthropicApiKey?: string;
+    readonly resendApiKey?: string;
+  };
+}
+
+/**
+ * DNS records the operator must create at their registrar to make the
+ * install reachable. Surfaced in the admin's /security/dns page with
+ * live resolver status badges.
+ */
+export interface DnsRecord {
+  readonly hostname: string; // e.g. "de.example.com"
+  readonly type: "A" | "AAAA" | "CNAME" | "TXT";
+  readonly value: string; // the value the operator's registrar must hold
+  readonly purpose: string; // human-readable description
+}
+
+/**
+ * Plain-data adapter outputs. Per-stack code wraps each field in
+ * `pulumi.Output<…>` at the Pulumi boundary, but the *shape* is shared
+ * across providers so the cms-provision CLI + the DNS UI can consume
+ * any provider's outputs uniformly.
+ */
+export interface CloudAdapterOutputs {
+  /** DSN for cms_admin role (encrypted in Pulumi state). */
+  readonly adminDatabaseUrl: string;
+  /** DSN for cms_public role (encrypted in Pulumi state). */
+  readonly publicDatabaseUrl: string;
+  /** Provider-native blob URL (s3://, gs://, https://<account>.blob.core.windows.net/<container>). */
+  readonly mediaStorageUrl: string;
+  /** Public-facing URL the admin reaches for media reads. */
+  readonly mediaCdnBaseUrl: string;
+  /** Bootstrap-token URL — operator opens this once after `pulumi up`. */
+  readonly bootstrapUrl: string;
+  /** DNS records consumed by the admin's DNS-guidance page. */
+  readonly dnsRecordsRequired: ReadonlyArray<DnsRecord>;
+  /**
+   * Where edge-A/B assignment logs land — read by the P12A analytics plugin's
+   * provider-specific log adapter. Provider-native sink URL (BigQuery dataset,
+   * Athena database, Log Analytics workspace).
+   */
+  readonly edgeLogSinkUrl: string;
+  /** Which provider produced these outputs — drives the analytics plugin's adapter dispatch. */
+  readonly provider: SupportedProvider;
+  /** Which environment this output snapshot represents. */
+  readonly environment: Environment;
+}
+
+export type SupportedProvider = "self-hosted" | "gcp" | "aws" | "azure";
+
+/**
+ * Convenience: the shape persisted in `cms_admin.provisioning_outputs.outputs_json`.
+ * Pulumi runs the adapter, the CLI's `pulumi-output-sync` subcommand reads
+ * `pulumi stack output --json`, hashes the result, and writes a row keyed on
+ * (provider, environment) so the admin UI can read without provider creds.
+ */
+export interface ProvisioningOutputsJson {
+  readonly outputs: CloudAdapterOutputs;
+  readonly syncedAt: string; // ISO timestamp
+}

package/src/bootstrap-token.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P14 — owner bootstrap token. cms-provision generates one at first
+ * `up`; the operator visits /setup?token=<…> to create the first
+ * Owner. Single-use, 24h TTL.
+ */
+
+export interface BootstrapToken {
+  readonly token: string;
+  readonly expiresAt: string;
+}
+
+export function generateBootstrapToken(): BootstrapToken {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  const token = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+  const expiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString();
+  return { token, expiresAt };
+}

package/src/caddy.ts

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P14 — Caddyfile generator.
+ *
+ * Reads the `domains` table + the deploy targets and emits a
+ * deterministic Caddyfile string. The CLI's `regenerate-caddy`
+ * sub-command writes this to `/etc/caddy/Caddyfile` and runs
+ * `caddy reload`.
+ *
+ * Per-vhost shape:
+ *   <hostname> {
+ *     # admin   → reverse_proxy localhost:5173
+ *     # public  → root + try_files (static), with /api/* → gateway
+ *     # locale  → same as public, scoped to a per-locale dist dir
+ *     tls <ownerEmail>
+ *   }
+ *
+ * Staging vhosts force `X-Robots-Tag: noindex`.
+ */
+
+export interface CaddyDomainSpec {
+  readonly hostname: string;
+  readonly kind: "admin" | "public" | "locale-public";
+  readonly localeCode?: string;
+  readonly env: "production" | "staging";
+}
+
+export interface CaddyfileSpec {
+  readonly ownerEmail: string;
+  readonly publicSiteRoot: string; // absolute path on disk
+  readonly stagingSiteRoot: string;
+  readonly adminPort: number;
+  readonly gatewayPort: number;
+  readonly domains: ReadonlyArray<CaddyDomainSpec>;
+}
+
+export function generateCaddyfile(spec: CaddyfileSpec): string {
+  const blocks: string[] = [];
+
+  // Global options.
+  blocks.push(`{
+  email ${spec.ownerEmail}
+}
+`);
+
+  for (const d of spec.domains) {
+    blocks.push(vhost(d, spec));
+  }
+
+  // Localhost dev fallback when no domains are configured (so a fresh
+  // `cms-provision` produces a working Caddyfile even pre-DNS).
+  if (spec.domains.length === 0) {
+    blocks.push(`# No domains configured yet — cms-provision regenerate-caddy
+# will overwrite this file when you add one at /security/domains.
+:8081 {
+  reverse_proxy localhost:${spec.adminPort}
+}
+`);
+  }
+
+  return blocks.join("\n");
+}
+
+function vhost(d: CaddyDomainSpec, spec: CaddyfileSpec): string {
+  const noindex = d.env === "staging" ? `\n  header X-Robots-Tag "noindex"` : "";
+  if (d.kind === "admin") {
+    return `${d.hostname} {${noindex}
+  reverse_proxy localhost:${spec.adminPort}
+}
+`;
+  }
+  // public / locale-public — same shape: API routes go to the gateway,
+  // the rest serves static files. Locale variants serve from a
+  // per-locale subdirectory.
+  const root = d.env === "staging" ? spec.stagingSiteRoot : spec.publicSiteRoot;
+  const localeSubdir = d.kind === "locale-public" && d.localeCode ? `/${d.localeCode}` : "";
+  return `${d.hostname} {${noindex}
+  root * ${root}${localeSubdir}
+  handle /api/* {
+    reverse_proxy localhost:${spec.gatewayPort}
+  }
+  handle /admin/* {
+    reverse_proxy localhost:${spec.adminPort}
+  }
+  handle {
+    file_server {
+      try_files {path} {path}/index.html /index.html
+    }
+  }
+}
+`;
+}

package/src/cdn-copy.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P15 — per-provider CDN-copy adapter contract.
+ *
+ * P7 ships the `media_assets.usage_count` threshold + the `media.set_cdn`
+ * op that flips a per-asset boolean. P15 wires the actual edge-pin
+ * operation per provider:
+ *   - AWS  → CloudFront cache invalidation + warmer request.
+ *   - GCP  → set Cache-Control metadata on the GCS object so Cloud CDN
+ *           respects the long TTL.
+ *   - Azure → Front Door purge + warm endpoint.
+ *
+ * The redeploy-orchestrator's `cdnCopyTick()` (currently a no-op for
+ * cloud installs) drains the per-asset CDN-pin queue using the adapter
+ * registered for the active provider.
+ *
+ * Each provider's stack publishes a `CdnCopyAdapter` instance via its
+ * Pulumi outputs (the actual implementation is dynamically imported by
+ * the orchestrator at runtime so `@caelo-cms/provisioning` doesn't pull in
+ * `@aws-sdk/...`/`@google-cloud/...`/`@azure/...` as static deps). The
+ * interface defined here is the only thing both sides agree on.
+ */
+
+export interface CdnCopyAdapter {
+  /**
+   * Mark the asset at `assetKey` (object key in primary storage) as
+   * CDN-cached. Returns the public CDN URL — admin uses this as the
+   * canonical URL for the asset thereafter.
+   */
+  pin(assetKey: string): Promise<string>;
+  /** Reverse — drop from CDN edge cache. */
+  unpin(assetKey: string): Promise<void>;
+}
+
+/**
+ * No-op adapter for self-hosted installs (Caddy serves directly from
+ * disk; no separate CDN tier). Returns the input asset key as a relative
+ * URL so callers don't have to special-case the no-CDN case.
+ */
+export const selfHostedCdnCopy: CdnCopyAdapter = {
+  async pin(assetKey) {
+    return `/media/${assetKey}`;
+  },
+  async unpin() {
+    // no-op
+  },
+};
+
+/**
+ * Resolves the right adapter per `process.env.CAELO_PROVIDER`. Lazy
+ * dynamic-imports the per-provider implementation so a self-hosted
+ * install never loads the cloud SDKs.
+ *
+ * Returns `selfHostedCdnCopy` ONLY for `provider==='self-hosted'` or an
+ * unset env (treated as self-hosted). For `gcp`/`aws`/`azure`, the
+ * matching `cdn-copy-<gcs|aws|azure>.ts` file MUST exist in this
+ * directory — those land with the per-provider PRs. Per CLAUDE.md §2
+ * "no fallbacks pre-1.0" we deliberately do NOT silently degrade to
+ * the self-hosted no-op when the file is missing: a missing module is
+ * a deploy bug + the orchestrator tick should crash loudly so the
+ * operator notices instead of silently dropping CDN-pin requests.
+ */
+export async function loadCdnCopyAdapter(provider?: string): Promise<CdnCopyAdapter> {
+  switch (provider) {
+    case "gcp":
+      // biome-ignore lint/suspicious/noExplicitAny: opt-in dynamic import
+      return ((await import("./cdn-copy-gcs.js" as string)) as any).gcsCloudCdnPin;
+    case "aws":
+      // biome-ignore lint/suspicious/noExplicitAny: opt-in dynamic import
+      return ((await import("./cdn-copy-aws.js" as string)) as any).s3CloudfrontPrewarm;
+    case "azure":
+      // biome-ignore lint/suspicious/noExplicitAny: opt-in dynamic import
+      return ((await import("./cdn-copy-azure.js" as string)) as any).azureBlobCdnPrefetch;
+    case undefined:
+    case "":
+    case "self-hosted":
+      return selfHostedCdnCopy;
+    default:
+      throw new Error(
+        `loadCdnCopyAdapter: unknown CAELO_PROVIDER='${provider}'. Expected one of: self-hosted | gcp | aws | azure.`,
+      );
+  }
+}