@anthusai/papyrus 1.0.0-next.2 → 1.0.0-next.4

package/infra/amplify-app-shell.ts

@@ -1,155 +1,181 @@
-export type AmplifyAppShellSiteConfig = {
-  /** CDK context selector and stack id suffix. */
-  siteId: string;
-  /** Amplify app name (also the CloudFormation stack-friendly id). */
-  appName: string;
-  /** Human description shown in the Amplify console. */
-  description: string;
-  /** GitHub repo URL the CMS deploys from. */
-  repository: string;
-  /** Amplify platform. Papyrus CMS is always WEB_COMPUTE (Next.js SSR). */
-  platform: "WEB_COMPUTE";
-  /** Deploy branch. */
-  branchName: string;
-  /** Branch environment variables (PAPYRUS_SITE_BRAND etc.). */
-  environment: Record<string, string>;
-  /**
-   * Secrets Manager secret name holding the GitHub access token used by
-   * Amplify to clone the repo. CDK reads it via a dynamic reference so the
-   * token never lands in the CloudFormation template. Populate the secret
-   * before deploying. Replace the initial token with a dedicated fine-grained
-   * PAT scoped to this repo.
-   */
-  githubTokenSecretName: string;
-  /** Custom domain for the CMS (newsroom.<site>.us). Apex stays on the reader. */
-  domainName: string;
-  /** Route 53 hosted zone id for the domain. */
-  hostedZoneId: string;
-  /** Build compute type. */
-  buildComputeType?: "STANDARD" | "STANDARD_8GB";
-  /** Enable branch auto-build so pushes trigger deploys. */
-  enableAutoBuild?: boolean;
-};
-
 import { Construct } from "constructs";
-import { Stack, StackProps, SecretValue } from "aws-cdk-lib";
+import { ArnFormat, CfnOutput, Stack, StackProps } from "aws-cdk-lib";
 import * as iam from "aws-cdk-lib/aws-iam";
 import * as amplify from "aws-cdk-lib/aws-amplify";
+import { cmsProductionBuildSpec, cmsStagingBuildSpec, readerBuildSpec } from "./build-specs";
+import { AmplifyAppShellSiteConfig, resolveStagingDomainName } from "./site-config";
 
+function environmentVariables(variables: Record<string, string>): amplify.CfnBranch.EnvironmentVariableProperty[] {
+  return Object.entries(variables).map(([name, value]) => ({ name, value }));
+}
 
 /**
- * Provisions the Amplify *app shell* for a Papyrus publication CMS:
- *
- *   - AWS::Amplify::App (WEB_COMPUTE, GitHub repo connection via PAT in Secrets Manager)
- *   - AWS::Amplify::Branch (main, with PAPYRUS_SITE_BRAND env vars)
- *   - AWS::Amplify::Domain (newsroom.<site>.us on the site's Route 53 zone)
- *   - IAM service role (backend deploy) + compute role (SSR rendering)
+ * Provisions the Amplify *app shell* of a Papyrus publication from its
+ * site.json:
  *
- * The Papyrus *backend* (AppSync, Storage, Lambda) is NOT created here. It
- * deploys via `ampx pipeline-deploy` from the repo `amplify.yml` once Amplify
- * CI runs a build on the branch. This stack only creates the container the
- * backend deploys into, so the app is never "created manually" in the console.
+ *   - CMS app (WEB_COMPUTE) with branches `main` (production, owns the backend)
+ *     and `staging` (frontend only, reads the production backend)
+ *   - for `markus-static` sites, a reader app (WEB) with branch `main`
+ *   - one domain association per branch/app, IAM service and compute roles
  *
- * The GitHub access token is read from Secrets Manager by dynamic reference,
- * so the token value never appears in the synthesized template.
+ * No repository and no access token are configured: the apps are manual-deploy
+ * until Amplify's GitHub App is connected once in the console
+ * (docs/site-hosting.md). The Papyrus backend itself is created inside the CMS
+ * app by `ampx pipeline-deploy` from the production build.
  */
 export class AmplifyAppShellStack extends Stack {
-  public readonly appId: string;
-  public readonly defaultDomain: string;
+  public readonly cmsAppId: string;
+  public readonly readerAppId?: string;
 
   constructor(scope: Construct, id: string, config: AmplifyAppShellSiteConfig, props?: StackProps) {
     super(scope, id, props);
 
-    const githubToken = SecretValue.secretsManager(config.githubTokenSecretName).unsafeUnwrap();
+    const cmsAppName = config.cms.appName ?? `${config.siteId}-cms`;
+    const stagingDomainName = resolveStagingDomainName(config);
 
-    // Service role Amplify assumes to deploy the backend (ampx pipeline-deploy
-    // creates AppSync, Storage, Lambda, etc., so it needs broad permissions).
-    const serviceRole = new iam.Role(this, "AmplifyServiceRole", {
+    const cmsServiceRole = new iam.Role(this, "AmplifyServiceRole", {
       assumedBy: new iam.ServicePrincipal("amplify.amazonaws.com"),
-      description: `Backend deploy service role for Amplify app ${config.appName}`,
+      description: `Backend deploy and staging build service role for Amplify app ${cmsAppName} (AdministratorAccess: documented risk)`,
       managedPolicies: [iam.ManagedPolicy.fromAwsManagedPolicyName("AdministratorAccess")],
     });
 
-    // WEB_COMPUTE (Next.js SSR) requires a compute role for the rendering server.
     const computeRole = new iam.Role(this, "AmplifyComputeRole", {
       assumedBy: new iam.ServicePrincipal("amplify.amazonaws.com"),
-      description: `SSR compute role for Amplify app ${config.appName}`,
+      description: `SSR compute role for Amplify app ${cmsAppName}`,
       managedPolicies: [
         iam.ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"),
         iam.ManagedPolicy.fromAwsManagedPolicyName("CloudWatchLogsFullAccess"),
       ],
     });
 
-    const app = new amplify.CfnApp(this, "App", {
-      name: config.appName,
-      description: config.description,
-      platform: config.platform,
-      repository: config.repository,
-      accessToken: githubToken,
-      iamServiceRole: serviceRole.roleArn,
+    const cmsApp = new amplify.CfnApp(this, "App", {
+      name: cmsAppName,
+      description: `Papyrus newsroom CMS for ${config.siteId} (WEB_COMPUTE)`,
+      platform: "WEB_COMPUTE",
+      iamServiceRole: cmsServiceRole.roleArn,
       computeRoleArn: computeRole.roleArn,
-      buildSpec: this.buildSpec(),
+      buildSpec: cmsProductionBuildSpec(config),
+      jobConfig: config.cms.buildComputeType ? { buildComputeType: config.cms.buildComputeType } : undefined,
       customRules: [{ source: "/<*>", target: "/index.html", status: "404-200" }],
     });
 
-    this.appId = app.attrAppId;
-    this.defaultDomain = `${app.attrAppId}.amplifyapp.com`;
+    const stagingMode: Record<string, string> = config.frontend === "markus-static"
+      ? { PAPYRUS_STAGING_PREVIEW: "static" }
+      : { PAPYRUS_CONTENT_SOURCE: "drafts" };
 
-    const branch = new amplify.CfnBranch(this, "Branch", {
-      appId: app.attrAppId,
-      branchName: config.branchName,
+    const productionBranch = new amplify.CfnBranch(this, "Branch", {
+      appId: cmsApp.attrAppId,
+      branchName: "main",
       stage: "PRODUCTION",
-      enableAutoBuild: config.enableAutoBuild ?? true,
+      enableAutoBuild: true,
+      enablePerformanceMode: false,
+      environmentVariables: environmentVariables({
+        ...config.cms.environment,
+        PAPYRUS_SITE_BRAND: config.brand,
+        SITE_ENV: "production",
+        PAPYRUS_CONTENT_SOURCE: "published",
+      }),
+    });
+
+    const stagingBranch = new amplify.CfnBranch(this, "StagingBranch", {
+      appId: cmsApp.attrAppId,
+      branchName: "staging",
+      stage: "BETA",
+      enableAutoBuild: true,
       enablePerformanceMode: false,
-      environmentVariables: Object.entries(config.environment).map(([key, value]) => ({
-        name: key,
-        value,
-      })),
+      buildSpec: cmsStagingBuildSpec(config),
+      environmentVariables: environmentVariables({
+        ...config.cms.environment,
+        PAPYRUS_SITE_BRAND: config.brand,
+        SITE_ENV: "staging",
+        ...stagingMode,
+        NEXT_PUBLIC_PAPYRUS_STAGING_URL: `https://${stagingDomainName}`,
+      }),
+    });
+
+    const productionDomain = new amplify.CfnDomain(this, "Domain", {
+      appId: cmsApp.attrAppId,
+      domainName: config.cms.domainName,
+      subDomainSettings: [{ branchName: "main", prefix: "" }],
     });
-    branch.addResourceDependency(app);
+    productionDomain.addResourceDependency(productionBranch);
 
-    const domain = new amplify.CfnDomain(this, "Domain", {
-      appId: app.attrAppId,
-      domainName: config.domainName,
-      subDomainSettings: [{ branchName: config.branchName, prefix: "" }],
+    const stagingDomain = new amplify.CfnDomain(this, "StagingDomain", {
+      appId: cmsApp.attrAppId,
+      domainName: stagingDomainName,
+      subDomainSettings: [{ branchName: "staging", prefix: "" }],
     });
-    domain.addResourceDependency(branch);
+    stagingDomain.addResourceDependency(stagingBranch);
 
-    this.exportValue(app.attrAppId, { description: `Amplify app id for ${config.appName}` });
+    this.cmsAppId = cmsApp.attrAppId;
+    new CfnOutput(this, "CmsAppId", { value: cmsApp.attrAppId, description: `Amplify app id for ${cmsAppName}` });
+    new CfnOutput(this, "CmsOrigin", { value: `https://${config.cms.domainName}/` });
+    new CfnOutput(this, "StagingOrigin", { value: `https://${stagingDomainName}/` });
+
+    if (config.reader) {
+      this.readerAppId = this.addReaderApp(config, config.reader, cmsApp.attrAppId);
+    }
   }
 
-  /**
-   * Build spec mirrors the repo root amplify.yml so the app deploys the full
-   * Papyrus backend + Next.js frontend on every build. Inlined because Amplify
-   * needs a buildSpec on the app for the first deploy before the repo is cloned.
-   */
-  private buildSpec(): string {
-    return [
-      "version: 1",
-      "backend:",
-      "  phases:",
-      "    build:",
-      "      commands:",
-      "        - npm install --cache .npm --prefer-offline",
-      "        - |",
-      "          if [ -z \"${PAPYRUS_CONSOLE_RESPONDER_IMAGE_URI:-}\" ]; then",
-      "            export PAPYRUS_CONSOLE_RESPONDER_ALLOW_LOCAL_BUILD=true",
-      "          fi",
-      "        - npx ampx pipeline-deploy --debug --branch $AWS_BRANCH --app-id $AWS_APP_ID",
-      "frontend:",
-      "  phases:",
-      "    build:",
-      "      commands:",
-      "        - env | grep -e '^PAPYRUS_CONTENT_SOURCE=' -e '^PAPYRUS_EDITION_SLUG=' -e '^PAPYRUS_REVALIDATE_SECRET=' >> .env.production",
-      "        - npm run build",
-      "  artifacts:",
-      "    baseDirectory: .next",
-      "    files:",
-      "      - '**/*'",
-      "  cache:",
-      "    paths:",
-      "      - .next/cache/**/*",
-      "      - .npm/**/*",
-    ].join("\n");
+  private addReaderApp(
+    config: AmplifyAppShellSiteConfig,
+    reader: NonNullable<AmplifyAppShellSiteConfig["reader"]>,
+    cmsAppId: string,
+  ): string {
+    const readerAppName = reader.appName ?? `${config.siteId}-reader`;
+    const readerBranchName = reader.branchName ?? "main";
+
+    const readerServiceRole = new iam.Role(this, "ReaderServiceRole", {
+      assumedBy: new iam.ServicePrincipal("amplify.amazonaws.com"),
+      description: `Static reader build role for Amplify app ${readerAppName} (reads the CMS app's SSM secrets and media only)`,
+    });
+    readerServiceRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "ReadSiteSecretsForJwtMinting",
+        actions: ["ssm:GetParameter", "ssm:GetParameters"],
+        resources: [
+          this.formatArn({ service: "ssm", resource: "parameter", resourceName: `amplify/${cmsAppId}/*`, arnFormat: ArnFormat.SLASH_RESOURCE_NAME }),
+          this.formatArn({ service: "ssm", resource: "parameter", resourceName: `amplify/shared/${cmsAppId}/*`, arnFormat: ArnFormat.SLASH_RESOURCE_NAME }),
+        ],
+      }),
+    );
+    readerServiceRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "ReadMediaForExport",
+        actions: ["s3:GetObject"],
+        resources: ["arn:aws:s3:::amplify-*/media/*"],
+      }),
+    );
+
+    const readerApp = new amplify.CfnApp(this, "ReaderApp", {
+      name: readerAppName,
+      description: `Papyrus static reader for ${config.siteId} (WEB)`,
+      platform: "WEB",
+      iamServiceRole: readerServiceRole.roleArn,
+      buildSpec: readerBuildSpec(config),
+    });
+
+    const readerBranch = new amplify.CfnBranch(this, "ReaderBranch", {
+      appId: readerApp.attrAppId,
+      branchName: readerBranchName,
+      stage: "PRODUCTION",
+      enableAutoBuild: true,
+      environmentVariables: environmentVariables({
+        ...(reader.environment ?? {}),
+        PAPYRUS_SITE_BRAND: config.brand,
+        SITE_ENV: "production",
+      }),
+    });
+
+    const readerDomain = new amplify.CfnDomain(this, "ReaderDomain", {
+      appId: readerApp.attrAppId,
+      domainName: reader.domainName,
+      subDomainSettings: [{ branchName: readerBranchName, prefix: "" }],
+    });
+    readerDomain.addResourceDependency(readerBranch);
+
+    new CfnOutput(this, "ReaderAppId", { value: readerApp.attrAppId, description: `Amplify app id for ${readerAppName}` });
+    new CfnOutput(this, "ReaderOrigin", { value: `https://${reader.domainName}/` });
+    return readerApp.attrAppId;
   }
 }

package/infra/build-specs.js

@@ -0,0 +1,86 @@
+import { resolveStoragePreviewPrefix } from "./site-config.js";
+export function papyrusVersionToPep440(version) {
+    const match = /^(\d+\.\d+\.\d+)(?:-[0-9A-Za-z-]+\.(\d+))?$/.exec(version);
+    if (!match)
+        throw new Error(`cannot map ${version} to PEP 440`);
+    return match[2] === undefined ? match[1] : `${match[1]}.dev${match[2]}`;
+}
+function yamlScalar(command) {
+    const needsQuoting = /: | #|^[-?:,\[\]{}#&*!|>'"%@`]|:$/.test(command);
+    return needsQuoting ? `'${command.replace(/'/g, "''")}'` : command;
+}
+function commandLines(commands, indent) {
+    return commands.map((command) => `${indent}- ${yamlScalar(command)}`);
+}
+const NPM_CLEAN_INSTALL = "npm ci --cache .npm --prefer-offline";
+const FRONTEND_ENVIRONMENT_CAPTURE = "env | grep -e '^PAPYRUS_' -e '^SITE_ENV=' -e '^NEXT_PUBLIC_' >> .env.production";
+function pythonProvisioningCommands(config) {
+    return [
+        "export UV_CACHE_DIR=\"$PWD/.uv-cache\"",
+        "curl -LsSf https://astral.sh/uv/install.sh | sh",
+        "export PATH=\"$HOME/.local/bin:$PATH\"",
+        "uv python install 3.12",
+        "uv venv --python 3.12 .venv",
+        `uv pip install --python .venv "papyrus-newsroom[markus]==${papyrusVersionToPep440(config.papyrusVersion)}"`,
+        "export PATH=\"$PWD/.venv/bin:$PATH\"",
+    ];
+}
+function reader(config) {
+    if (!config.reader)
+        throw new Error(`site ${config.siteId} has no reader app (frontend ${config.frontend})`);
+    return config.reader;
+}
+function frontendSection(preBuildCommands, buildCommands, artifactsDirectory, cachePaths) {
+    const lines = ["frontend:", "  phases:"];
+    if (preBuildCommands.length > 0) {
+        lines.push("    preBuild:", "      commands:", ...commandLines(preBuildCommands, "        "));
+    }
+    lines.push("    build:", "      commands:", ...commandLines(buildCommands, "        "), "  artifacts:", `    baseDirectory: ${artifactsDirectory}`, "    files:", "      - '**/*'", "  cache:", "    paths:", ...cachePaths.map((cachePath) => `      - ${cachePath}`));
+    return lines;
+}
+export function cmsProductionBuildSpec(config) {
+    return [
+        "version: 1",
+        "backend:",
+        "  phases:",
+        "    build:",
+        "      commands:",
+        ...commandLines([
+            NPM_CLEAN_INSTALL,
+            "if [ -z \"${PAPYRUS_CONSOLE_RESPONDER_IMAGE_URI:-}\" ]; then export PAPYRUS_CONSOLE_RESPONDER_ALLOW_LOCAL_BUILD=true; fi",
+            "npx ampx pipeline-deploy --branch $AWS_BRANCH --app-id $AWS_APP_ID",
+        ], "        "),
+        ...frontendSection([], [FRONTEND_ENVIRONMENT_CAPTURE, "npx papyrus-app sync && npm run build"], ".next", [".next/cache/**/*", ".npm/**/*"]),
+    ].join("\n") + "\n";
+}
+export function cmsStagingBuildSpec(config) {
+    const preBuild = [NPM_CLEAN_INSTALL, "npx ampx generate outputs --branch main --app-id $AWS_APP_ID"];
+    const cachePaths = [".next/cache/**/*", ".npm/**/*"];
+    if (config.frontend === "markus-static") {
+        const readerConfig = reader(config);
+        preBuild.push(...pythonProvisioningCommands(config), "papyrus auth refresh-jwt --write-env .env", "papyrus content export-published --drafts --out content-export --clean", readerConfig.buildCommand, `papyrus content upload-preview --dir ${readerConfig.baseDirectory} --prefix ${resolveStoragePreviewPrefix(config)}`);
+        cachePaths.push(".uv-cache/**/*");
+    }
+    return [
+        "version: 1",
+        ...frontendSection(preBuild, [FRONTEND_ENVIRONMENT_CAPTURE, "npx papyrus-app sync && npm run build"], ".next", cachePaths),
+    ].join("\n") + "\n";
+}
+export function readerBuildSpec(config) {
+    const readerConfig = reader(config);
+    return [
+        "version: 1",
+        ...frontendSection([
+            ...pythonProvisioningCommands(config),
+            "papyrus auth refresh-jwt --write-env .env",
+            "papyrus content export-published --out content-export --clean",
+        ], [readerConfig.buildCommand], readerConfig.baseDirectory, [".uv-cache/**/*"]),
+    ].join("\n") + "\n";
+}
+export function buildSpecFor(config, app) {
+    if (app === "cms-production")
+        return cmsProductionBuildSpec(config);
+    if (app === "cms-staging")
+        return cmsStagingBuildSpec(config);
+    return readerBuildSpec(config);
+}

package/infra/build-specs.ts

@@ -0,0 +1,132 @@
+import { AmplifyAppShellSiteConfig, resolveStoragePreviewPrefix } from "./site-config";
+
+export type BuildSpecAppName = "cms-production" | "cms-staging" | "reader";
+
+export function papyrusVersionToPep440(version: string): string {
+  const match = /^(\d+\.\d+\.\d+)(?:-[0-9A-Za-z-]+\.(\d+))?$/.exec(version);
+  if (!match) throw new Error(`cannot map ${version} to PEP 440`);
+  return match[2] === undefined ? match[1] : `${match[1]}.dev${match[2]}`;
+}
+
+function yamlScalar(command: string): string {
+  const needsQuoting = /: | #|^[-?:,\[\]{}#&*!|>'"%@`]|:$/.test(command);
+  return needsQuoting ? `'${command.replace(/'/g, "''")}'` : command;
+}
+
+function commandLines(commands: string[], indent: string): string[] {
+  return commands.map((command) => `${indent}- ${yamlScalar(command)}`);
+}
+
+const NPM_CLEAN_INSTALL = "npm ci --cache .npm --prefer-offline";
+
+const FRONTEND_ENVIRONMENT_CAPTURE =
+  "env | grep -e '^PAPYRUS_' -e '^SITE_ENV=' -e '^NEXT_PUBLIC_' >> .env.production";
+
+function pythonProvisioningCommands(config: AmplifyAppShellSiteConfig): string[] {
+  return [
+    "export UV_CACHE_DIR=\"$PWD/.uv-cache\"",
+    "curl -LsSf https://astral.sh/uv/install.sh | sh",
+    "export PATH=\"$HOME/.local/bin:$PATH\"",
+    "uv python install 3.12",
+    "uv venv --python 3.12 .venv",
+    `uv pip install --python .venv "papyrus-newsroom[markus]==${papyrusVersionToPep440(config.papyrusVersion)}"`,
+    "export PATH=\"$PWD/.venv/bin:$PATH\"",
+  ];
+}
+
+function reader(config: AmplifyAppShellSiteConfig): NonNullable<AmplifyAppShellSiteConfig["reader"]> {
+  if (!config.reader) throw new Error(`site ${config.siteId} has no reader app (frontend ${config.frontend})`);
+  return config.reader;
+}
+
+function frontendSection(preBuildCommands: string[], buildCommands: string[], artifactsDirectory: string, cachePaths: string[]): string[] {
+  const lines = ["frontend:", "  phases:"];
+  if (preBuildCommands.length > 0) {
+    lines.push("    preBuild:", "      commands:", ...commandLines(preBuildCommands, "        "));
+  }
+  lines.push(
+    "    build:",
+    "      commands:",
+    ...commandLines(buildCommands, "        "),
+    "  artifacts:",
+    `    baseDirectory: ${artifactsDirectory}`,
+    "    files:",
+    "      - '**/*'",
+    "  cache:",
+    "    paths:",
+    ...cachePaths.map((cachePath) => `      - ${cachePath}`),
+  );
+  return lines;
+}
+
+export function cmsProductionBuildSpec(config: AmplifyAppShellSiteConfig): string {
+  return [
+    "version: 1",
+    "backend:",
+    "  phases:",
+    "    build:",
+    "      commands:",
+    ...commandLines(
+      [
+        NPM_CLEAN_INSTALL,
+        "if [ -z \"${PAPYRUS_CONSOLE_RESPONDER_IMAGE_URI:-}\" ]; then export PAPYRUS_CONSOLE_RESPONDER_ALLOW_LOCAL_BUILD=true; fi",
+        "npx ampx pipeline-deploy --branch $AWS_BRANCH --app-id $AWS_APP_ID",
+      ],
+      "        ",
+    ),
+    ...frontendSection(
+      [],
+      [FRONTEND_ENVIRONMENT_CAPTURE, "npx papyrus-app sync && npm run build"],
+      ".next",
+      [".next/cache/**/*", ".npm/**/*"],
+    ),
+  ].join("\n") + "\n";
+}
+
+export function cmsStagingBuildSpec(config: AmplifyAppShellSiteConfig): string {
+  const preBuild = [NPM_CLEAN_INSTALL, "npx ampx generate outputs --branch main --app-id $AWS_APP_ID"];
+  const cachePaths = [".next/cache/**/*", ".npm/**/*"];
+  if (config.frontend === "markus-static") {
+    const readerConfig = reader(config);
+    preBuild.push(
+      ...pythonProvisioningCommands(config),
+      "papyrus auth refresh-jwt --write-env .env",
+      "papyrus content export-published --drafts --out content-export --clean",
+      readerConfig.buildCommand,
+      `papyrus content upload-preview --dir ${readerConfig.baseDirectory} --prefix ${resolveStoragePreviewPrefix(config)}`,
+    );
+    cachePaths.push(".uv-cache/**/*");
+  }
+  return [
+    "version: 1",
+    ...frontendSection(
+      preBuild,
+      [FRONTEND_ENVIRONMENT_CAPTURE, "npx papyrus-app sync && npm run build"],
+      ".next",
+      cachePaths,
+    ),
+  ].join("\n") + "\n";
+}
+
+export function readerBuildSpec(config: AmplifyAppShellSiteConfig): string {
+  const readerConfig = reader(config);
+  return [
+    "version: 1",
+    ...frontendSection(
+      [
+        ...pythonProvisioningCommands(config),
+        "papyrus auth refresh-jwt --write-env .env",
+        "papyrus content export-published --out content-export --clean",
+      ],
+      [readerConfig.buildCommand],
+      readerConfig.baseDirectory,
+      [".uv-cache/**/*"],
+    ),
+  ].join("\n") + "\n";
+}
+
+export function buildSpecFor(config: AmplifyAppShellSiteConfig, app: BuildSpecAppName): string {
+  if (app === "cms-production") return cmsProductionBuildSpec(config);
+  if (app === "cms-staging") return cmsStagingBuildSpec(config);
+  return readerBuildSpec(config);
+}

package/infra/index.js

@@ -10,3 +10,5 @@ try {
   );
 }
 export const { AmplifyAppShellStack } = await import("./amplify-app-shell.js");
+export { parseSiteConfig } from "./site-config.js";
+export { cmsProductionBuildSpec, cmsStagingBuildSpec, readerBuildSpec, buildSpecFor } from "./build-specs.js";

package/infra/site-config.js

@@ -0,0 +1,125 @@
+const SITE_ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const REPOSITORY_PATTERN = /^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const HOSTED_ZONE_ID_PATTERN = /^Z[A-Z0-9]+$/;
+const HOST_NAME_PATTERN = /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/;
+const APP_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 _.-]*$/;
+const BRANCH_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9/_.-]*$/;
+const PAPYRUS_VERSION_PATTERN = /^\d+\.\d+\.\d+(-[0-9A-Za-z-]+\.\d+)?$/;
+const LOCAL_DEVELOPMENT_ORIGIN = "http://localhost:3001/";
+function fail(field, problem) {
+    throw new Error(`site.json: ${field} ${problem}`);
+}
+function requireObject(value, field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        fail(field, "must be an object");
+    }
+    return value;
+}
+function requireString(value, field, pattern, patternHint) {
+    if (typeof value !== "string" || value.trim() === "") {
+        fail(field, "must be a non-empty string");
+    }
+    if (pattern && !pattern.test(value)) {
+        fail(field, `is invalid${patternHint ? ` (${patternHint})` : ""}: ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+function optionalString(value, field, pattern, patternHint) {
+    return value === undefined ? undefined : requireString(value, field, pattern, patternHint);
+}
+function requireStringRecord(value, field) {
+    const record = requireObject(value, field);
+    const result = {};
+    for (const [key, entry] of Object.entries(record)) {
+        if (typeof entry !== "string")
+            fail(`${field}.${key}`, "must be a string");
+        result[key] = entry;
+    }
+    return result;
+}
+function rejectUnknownKeys(record, allowed, field) {
+    for (const key of Object.keys(record)) {
+        if (!allowed.includes(key))
+            fail(`${field}.${key}`, `is not a known field (known: ${allowed.join(", ")})`);
+    }
+}
+export function resolveStagingDomainName(config) {
+    if (config.cms.stagingDomainName)
+        return config.cms.stagingDomainName;
+    const [, ...rest] = config.cms.domainName.split(".");
+    return ["staging", ...rest].join(".");
+}
+export function resolveStoragePreviewPrefix(config) {
+    return config.storagePreviewPrefix ?? "preview/";
+}
+export function parseSiteConfig(raw) {
+    const record = requireObject(raw, "site");
+    rejectUnknownKeys(record, ["siteId", "repository", "brand", "frontend", "hostedZoneId", "cms", "reader", "papyrusVersion", "storagePreviewPrefix"], "site");
+    const siteId = requireString(record.siteId, "siteId", SITE_ID_PATTERN, "kebab-case");
+    const repository = requireString(record.repository, "repository", REPOSITORY_PATTERN, "https://github.com/<org>/<repo>");
+    const brand = requireString(record.brand, "brand");
+    const frontend = requireString(record.frontend, "frontend");
+    if (frontend !== "pretext" && frontend !== "markus-static") {
+        fail("frontend", `must be "pretext" or "markus-static", got ${JSON.stringify(frontend)}`);
+    }
+    const hostedZoneId = requireString(record.hostedZoneId, "hostedZoneId", HOSTED_ZONE_ID_PATTERN, "Route 53 zone id");
+    const papyrusVersion = requireString(record.papyrusVersion, "papyrusVersion", PAPYRUS_VERSION_PATTERN, "exact version such as 1.0.0 or 1.0.0-next.1");
+    const storagePreviewPrefix = optionalString(record.storagePreviewPrefix, "storagePreviewPrefix", /^[A-Za-z0-9._-]+\/$/, "must end with /");
+    const cmsRecord = requireObject(record.cms, "cms");
+    rejectUnknownKeys(cmsRecord, ["appName", "domainName", "buildComputeType", "environment", "stagingDomainName"], "cms");
+    const buildComputeType = cmsRecord.buildComputeType;
+    if (buildComputeType !== undefined && buildComputeType !== "STANDARD" && buildComputeType !== "STANDARD_8GB") {
+        fail("cms.buildComputeType", `must be "STANDARD" or "STANDARD_8GB", got ${JSON.stringify(buildComputeType)}`);
+    }
+    const cms = {
+        appName: optionalString(cmsRecord.appName, "cms.appName", APP_NAME_PATTERN),
+        domainName: requireString(cmsRecord.domainName, "cms.domainName", HOST_NAME_PATTERN, "host name"),
+        buildComputeType: buildComputeType,
+        environment: requireStringRecord(cmsRecord.environment, "cms.environment"),
+        stagingDomainName: optionalString(cmsRecord.stagingDomainName, "cms.stagingDomainName", HOST_NAME_PATTERN, "host name"),
+    };
+    let reader;
+    if (record.reader !== undefined) {
+        if (frontend !== "markus-static")
+            fail("reader", `is only allowed when frontend is "markus-static"`);
+        const readerRecord = requireObject(record.reader, "reader");
+        rejectUnknownKeys(readerRecord, ["appName", "domainName", "branchName", "buildCommand", "baseDirectory", "environment"], "reader");
+        reader = {
+            appName: optionalString(readerRecord.appName, "reader.appName", APP_NAME_PATTERN),
+            domainName: requireString(readerRecord.domainName, "reader.domainName", HOST_NAME_PATTERN, "host name"),
+            branchName: optionalString(readerRecord.branchName, "reader.branchName", BRANCH_NAME_PATTERN),
+            buildCommand: requireString(readerRecord.buildCommand, "reader.buildCommand"),
+            baseDirectory: requireString(readerRecord.baseDirectory, "reader.baseDirectory"),
+            environment: readerRecord.environment === undefined ? undefined : requireStringRecord(readerRecord.environment, "reader.environment"),
+        };
+    }
+    else if (frontend === "markus-static") {
+        fail("reader", `is required when frontend is "markus-static"`);
+    }
+    const config = {
+        siteId,
+        repository,
+        brand,
+        frontend,
+        hostedZoneId,
+        cms,
+        reader,
+        papyrusVersion,
+        storagePreviewPrefix,
+    };
+    const redirectValue = cms.environment.PAPYRUS_OAUTH_REDIRECT_URLS;
+    if (redirectValue === undefined)
+        fail("cms.environment.PAPYRUS_OAUTH_REDIRECT_URLS", "is required");
+    const redirectUrls = redirectValue.split(",").map((url) => url.trim());
+    const requiredOrigins = [
+        `https://${cms.domainName}/`,
+        `https://${resolveStagingDomainName(config)}/`,
+        LOCAL_DEVELOPMENT_ORIGIN,
+    ];
+    for (const origin of requiredOrigins) {
+        if (!redirectUrls.includes(origin)) {
+            fail("cms.environment.PAPYRUS_OAUTH_REDIRECT_URLS", `must include ${origin}`);
+        }
+    }
+    return config;
+}