@anthusai/papyrus 0.0.0 → 1.0.0-next.10

package/infra/build-specs.ts

@@ -0,0 +1,131 @@
+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 ops content export-published --drafts --out content-export --clean",
+      readerConfig.buildCommand,
+      `papyrus ops 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 ops content export-published --auth guest --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/github-oidc-provider.js

@@ -0,0 +1,24 @@
+import { CfnOutput, Stack } from "aws-cdk-lib";
+import * as iam from "aws-cdk-lib/aws-iam";
+export const GITHUB_OIDC_PROVIDER_HOST = "token.actions.githubusercontent.com";
+/**
+ * Account-global singleton: AWS allows one IAM OIDC provider per issuer URL per
+ * account, so this never belongs in a per-site stack. Deploy it once per
+ * account, and only after `aws iam list-open-id-connect-providers` shows no
+ * provider for token.actions.githubusercontent.com. When one already exists,
+ * do not deploy this stack: per-site CI roles only reference the provider by
+ * its ARN (arn:aws:iam::<account>:oidc-provider/token.actions.githubusercontent.com)
+ * and work against an existing provider unchanged.
+ */
+export class GithubOidcProviderStack extends Stack {
+    providerArn;
+    constructor(scope, id, props) {
+        super(scope, id, props);
+        const provider = new iam.OpenIdConnectProvider(this, "GithubOidc", {
+            url: `https://${GITHUB_OIDC_PROVIDER_HOST}`,
+            clientIds: ["sts.amazonaws.com"],
+        });
+        this.providerArn = provider.openIdConnectProviderArn;
+        new CfnOutput(this, "GithubOidcProviderArn", { value: provider.openIdConnectProviderArn });
+    }
+}

package/infra/github-oidc-provider.ts

@@ -0,0 +1,30 @@
+import { Construct } from "constructs";
+import { CfnOutput, Stack, StackProps } from "aws-cdk-lib";
+import * as iam from "aws-cdk-lib/aws-iam";
+
+export const GITHUB_OIDC_PROVIDER_HOST = "token.actions.githubusercontent.com";
+
+/**
+ * Account-global singleton: AWS allows one IAM OIDC provider per issuer URL per
+ * account, so this never belongs in a per-site stack. Deploy it once per
+ * account, and only after `aws iam list-open-id-connect-providers` shows no
+ * provider for token.actions.githubusercontent.com. When one already exists,
+ * do not deploy this stack: per-site CI roles only reference the provider by
+ * its ARN (arn:aws:iam::<account>:oidc-provider/token.actions.githubusercontent.com)
+ * and work against an existing provider unchanged.
+ */
+export class GithubOidcProviderStack extends Stack {
+  public readonly providerArn: string;
+
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    const provider = new iam.OpenIdConnectProvider(this, "GithubOidc", {
+      url: `https://${GITHUB_OIDC_PROVIDER_HOST}`,
+      clientIds: ["sts.amazonaws.com"],
+    });
+
+    this.providerArn = provider.openIdConnectProviderArn;
+    new CfnOutput(this, "GithubOidcProviderArn", { value: provider.openIdConnectProviderArn });
+  }
+}

package/infra/index.js

@@ -0,0 +1,15 @@
+// aws-cdk-lib and constructs are OPTIONAL peers of @anthusai/papyrus: only a publication's infra/ package installs them.
+try {
+  await import("aws-cdk-lib");
+  await import("constructs");
+} catch (error) {
+  throw new Error(
+    "@anthusai/papyrus/infra needs aws-cdk-lib and constructs, which are optional peer dependencies. " +
+      "Install them in the package that imports this entry (your infra/ folder): npm install aws-cdk-lib constructs. " +
+      "(" + (error && error.code) + ")",
+  );
+}
+export const { AmplifyAppShellStack } = await import("./amplify-app-shell.js");
+export const { GithubOidcProviderStack } = await import("./github-oidc-provider.js");
+export { parseSiteConfig } from "./site-config.js";
+export { cmsProductionBuildSpec, cmsStagingBuildSpec, readerBuildSpec, buildSpecFor } from "./build-specs.js";

package/infra/site-config.js

@@ -0,0 +1,186 @@
+export const DEFAULT_CI_BRANCHES = ["main", "staging"];
+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 STACK_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9-]{0,127}$/;
+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 GITHUB_OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/;
+const GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+$/;
+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 isStagingEnabled(config) {
+    return config.cms.staging !== false;
+}
+export function resolveStagingDomainName(config) {
+    if (!isStagingEnabled(config))
+        return undefined;
+    if (config.cms.stagingDomainName)
+        return config.cms.stagingDomainName;
+    if (!config.cms.domainName)
+        return undefined;
+    const [, ...rest] = config.cms.domainName.split(".");
+    return ["staging", ...rest].join(".");
+}
+export function resolveStackName(config) {
+    return config.stackName ?? `amplify-app-shell-${config.siteId}`;
+}
+export function resolveStoragePreviewPrefix(config) {
+    return config.storagePreviewPrefix ?? "preview/";
+}
+export function parseSiteConfig(raw) {
+    const record = requireObject(raw, "site");
+    rejectUnknownKeys(record, ["siteId", "repository", "brand", "frontend", "hostedZoneId", "stackName", "cms", "reader", "papyrusVersion", "storagePreviewPrefix", "github"], "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 = optionalString(record.hostedZoneId, "hostedZoneId", HOSTED_ZONE_ID_PATTERN, "Route 53 zone id");
+    const stackName = optionalString(record.stackName, "stackName", STACK_NAME_PATTERN, "CloudFormation stack name");
+    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", "staging", "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)}`);
+    }
+    if (cmsRecord.staging !== undefined && typeof cmsRecord.staging !== "boolean") {
+        fail("cms.staging", `must be a boolean, got ${JSON.stringify(cmsRecord.staging)}`);
+    }
+    const cms = {
+        appName: optionalString(cmsRecord.appName, "cms.appName", APP_NAME_PATTERN),
+        domainName: optionalString(cmsRecord.domainName, "cms.domainName", HOST_NAME_PATTERN, "host name"),
+        staging: cmsRecord.staging,
+        buildComputeType: buildComputeType,
+        environment: requireStringRecord(cmsRecord.environment, "cms.environment"),
+        stagingDomainName: optionalString(cmsRecord.stagingDomainName, "cms.stagingDomainName", HOST_NAME_PATTERN, "host name"),
+    };
+    if (cms.staging === false && cms.stagingDomainName) {
+        fail("cms.stagingDomainName", "must not be set when cms.staging is false");
+    }
+    if (cms.stagingDomainName && !cms.domainName) {
+        fail("cms.stagingDomainName", "requires cms.domainName");
+    }
+    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: optionalString(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"`);
+    }
+    let github;
+    if (record.github !== undefined) {
+        const githubRecord = requireObject(record.github, "github");
+        rejectUnknownKeys(githubRecord, ["owner", "repo", "branches", "ciCanDeployInfra"], "github");
+        const owner = requireString(githubRecord.owner, "github.owner", GITHUB_OWNER_PATTERN, "plain GitHub login");
+        const repo = requireString(githubRecord.repo, "github.repo", GITHUB_REPO_PATTERN);
+        if (repository !== `https://github.com/${owner}/${repo}`) {
+            fail("github", `owner/repo must match repository ${repository}`);
+        }
+        let branches = cms.staging === false ? DEFAULT_CI_BRANCHES.filter((branch) => branch !== "staging") : DEFAULT_CI_BRANCHES;
+        if (githubRecord.branches !== undefined) {
+            if (!Array.isArray(githubRecord.branches) || githubRecord.branches.length === 0) {
+                fail("github.branches", "must be a non-empty array of branch names");
+            }
+            branches = githubRecord.branches.map((branch, index) => {
+                if (typeof branch === "string" && /[*?]/.test(branch)) {
+                    fail(`github.branches[${index}]`, `must not contain wildcards: ${JSON.stringify(branch)}`);
+                }
+                return requireString(branch, `github.branches[${index}]`, BRANCH_NAME_PATTERN);
+            });
+        }
+        const ciCanDeployInfra = githubRecord.ciCanDeployInfra ?? false;
+        if (typeof ciCanDeployInfra !== "boolean")
+            fail("github.ciCanDeployInfra", "must be a boolean");
+        github = { owner, repo, branches, ciCanDeployInfra: ciCanDeployInfra };
+    }
+    const hasDomain = cms.domainName !== undefined || reader?.domainName !== undefined;
+    if (hasDomain && hostedZoneId === undefined) {
+        fail("hostedZoneId", "is required when cms.domainName or reader.domainName is set");
+    }
+    if (!hasDomain && hostedZoneId !== undefined) {
+        fail("hostedZoneId", "is only allowed when cms.domainName or reader.domainName is set");
+    }
+    const config = {
+        siteId,
+        repository,
+        brand,
+        frontend,
+        hostedZoneId,
+        stackName,
+        cms,
+        reader,
+        papyrusVersion,
+        storagePreviewPrefix,
+        github,
+    };
+    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 stagingDomainName = resolveStagingDomainName(config);
+    const requiredOrigins = [
+        ...(cms.domainName ? [`https://${cms.domainName}/`] : []),
+        ...(stagingDomainName ? [`https://${stagingDomainName}/`] : []),
+        LOCAL_DEVELOPMENT_ORIGIN,
+    ];
+    for (const origin of requiredOrigins) {
+        if (!redirectUrls.includes(origin)) {
+            fail("cms.environment.PAPYRUS_OAUTH_REDIRECT_URLS", `must include ${origin}`);
+        }
+    }
+    return config;
+}

package/infra/site-config.ts

@@ -0,0 +1,235 @@
+export type AmplifyAppShellSiteConfig = {
+  siteId: string;
+  repository: string;
+  brand: string;
+  frontend: "pretext" | "markus-static";
+  hostedZoneId?: string;
+  stackName?: string;
+  cms: {
+    appName?: string;
+    domainName?: string;
+    staging?: boolean;
+    buildComputeType?: "STANDARD" | "STANDARD_8GB";
+    environment: Record<string, string>;
+    stagingDomainName?: string;
+  };
+  reader?: {
+    appName?: string;
+    domainName?: string;
+    branchName?: string;
+    buildCommand: string;
+    baseDirectory: string;
+    environment?: Record<string, string>;
+  };
+  papyrusVersion: string;
+  storagePreviewPrefix?: string;
+  github?: {
+    owner: string;
+    repo: string;
+    branches: string[];
+    ciCanDeployInfra: boolean;
+  };
+};
+
+export const DEFAULT_CI_BRANCHES = ["main", "staging"];
+
+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 STACK_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9-]{0,127}$/;
+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 GITHUB_OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/;
+const GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+$/;
+const LOCAL_DEVELOPMENT_ORIGIN = "http://localhost:3001/";
+
+function fail(field: string, problem: string): never {
+  throw new Error(`site.json: ${field} ${problem}`);
+}
+
+function requireObject(value: unknown, field: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    fail(field, "must be an object");
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireString(value: unknown, field: string, pattern?: RegExp, patternHint?: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    fail(field, "must be a non-empty string");
+  }
+  if (pattern && !pattern.test(value as string)) {
+    fail(field, `is invalid${patternHint ? ` (${patternHint})` : ""}: ${JSON.stringify(value)}`);
+  }
+  return value as string;
+}
+
+function optionalString(value: unknown, field: string, pattern?: RegExp, patternHint?: string): string | undefined {
+  return value === undefined ? undefined : requireString(value, field, pattern, patternHint);
+}
+
+function requireStringRecord(value: unknown, field: string): Record<string, string> {
+  const record = requireObject(value, field);
+  const result: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(record)) {
+    if (typeof entry !== "string") fail(`${field}.${key}`, "must be a string");
+    result[key] = entry as string;
+  }
+  return result;
+}
+
+function rejectUnknownKeys(record: Record<string, unknown>, allowed: string[], field: string): void {
+  for (const key of Object.keys(record)) {
+    if (!allowed.includes(key)) fail(`${field}.${key}`, `is not a known field (known: ${allowed.join(", ")})`);
+  }
+}
+
+export function isStagingEnabled(config: Pick<AmplifyAppShellSiteConfig, "cms">): boolean {
+  return config.cms.staging !== false;
+}
+
+export function resolveStagingDomainName(config: Pick<AmplifyAppShellSiteConfig, "cms">): string | undefined {
+  if (!isStagingEnabled(config)) return undefined;
+  if (config.cms.stagingDomainName) return config.cms.stagingDomainName;
+  if (!config.cms.domainName) return undefined;
+  const [, ...rest] = config.cms.domainName.split(".");
+  return ["staging", ...rest].join(".");
+}
+
+export function resolveStackName(config: Pick<AmplifyAppShellSiteConfig, "siteId" | "stackName">): string {
+  return config.stackName ?? `amplify-app-shell-${config.siteId}`;
+}
+
+export function resolveStoragePreviewPrefix(config: Pick<AmplifyAppShellSiteConfig, "storagePreviewPrefix">): string {
+  return config.storagePreviewPrefix ?? "preview/";
+}
+
+export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
+  const record = requireObject(raw, "site");
+  rejectUnknownKeys(
+    record,
+    ["siteId", "repository", "brand", "frontend", "hostedZoneId", "stackName", "cms", "reader", "papyrusVersion", "storagePreviewPrefix", "github"],
+    "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 = optionalString(record.hostedZoneId, "hostedZoneId", HOSTED_ZONE_ID_PATTERN, "Route 53 zone id");
+  const stackName = optionalString(record.stackName, "stackName", STACK_NAME_PATTERN, "CloudFormation stack name");
+  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", "staging", "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)}`);
+  }
+  if (cmsRecord.staging !== undefined && typeof cmsRecord.staging !== "boolean") {
+    fail("cms.staging", `must be a boolean, got ${JSON.stringify(cmsRecord.staging)}`);
+  }
+  const cms: AmplifyAppShellSiteConfig["cms"] = {
+    appName: optionalString(cmsRecord.appName, "cms.appName", APP_NAME_PATTERN),
+    domainName: optionalString(cmsRecord.domainName, "cms.domainName", HOST_NAME_PATTERN, "host name"),
+    staging: cmsRecord.staging as boolean | undefined,
+    buildComputeType: buildComputeType as "STANDARD" | "STANDARD_8GB" | undefined,
+    environment: requireStringRecord(cmsRecord.environment, "cms.environment"),
+    stagingDomainName: optionalString(cmsRecord.stagingDomainName, "cms.stagingDomainName", HOST_NAME_PATTERN, "host name"),
+  };
+
+  if (cms.staging === false && cms.stagingDomainName) {
+    fail("cms.stagingDomainName", "must not be set when cms.staging is false");
+  }
+  if (cms.stagingDomainName && !cms.domainName) {
+    fail("cms.stagingDomainName", "requires cms.domainName");
+  }
+
+  let reader: AmplifyAppShellSiteConfig["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: optionalString(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"`);
+  }
+
+  let github: AmplifyAppShellSiteConfig["github"];
+  if (record.github !== undefined) {
+    const githubRecord = requireObject(record.github, "github");
+    rejectUnknownKeys(githubRecord, ["owner", "repo", "branches", "ciCanDeployInfra"], "github");
+    const owner = requireString(githubRecord.owner, "github.owner", GITHUB_OWNER_PATTERN, "plain GitHub login");
+    const repo = requireString(githubRecord.repo, "github.repo", GITHUB_REPO_PATTERN);
+    if (repository !== `https://github.com/${owner}/${repo}`) {
+      fail("github", `owner/repo must match repository ${repository}`);
+    }
+    let branches = cms.staging === false ? DEFAULT_CI_BRANCHES.filter((branch) => branch !== "staging") : DEFAULT_CI_BRANCHES;
+    if (githubRecord.branches !== undefined) {
+      if (!Array.isArray(githubRecord.branches) || githubRecord.branches.length === 0) {
+        fail("github.branches", "must be a non-empty array of branch names");
+      }
+      branches = (githubRecord.branches as unknown[]).map((branch, index) => {
+        if (typeof branch === "string" && /[*?]/.test(branch)) {
+          fail(`github.branches[${index}]`, `must not contain wildcards: ${JSON.stringify(branch)}`);
+        }
+        return requireString(branch, `github.branches[${index}]`, BRANCH_NAME_PATTERN);
+      });
+    }
+    const ciCanDeployInfra = githubRecord.ciCanDeployInfra ?? false;
+    if (typeof ciCanDeployInfra !== "boolean") fail("github.ciCanDeployInfra", "must be a boolean");
+    github = { owner, repo, branches, ciCanDeployInfra: ciCanDeployInfra as boolean };
+  }
+
+  const hasDomain = cms.domainName !== undefined || reader?.domainName !== undefined;
+  if (hasDomain && hostedZoneId === undefined) {
+    fail("hostedZoneId", "is required when cms.domainName or reader.domainName is set");
+  }
+  if (!hasDomain && hostedZoneId !== undefined) {
+    fail("hostedZoneId", "is only allowed when cms.domainName or reader.domainName is set");
+  }
+
+  const config: AmplifyAppShellSiteConfig = {
+    siteId,
+    repository,
+    brand,
+    frontend,
+    hostedZoneId,
+    stackName,
+    cms,
+    reader,
+    papyrusVersion,
+    storagePreviewPrefix,
+    github,
+  };
+
+  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 stagingDomainName = resolveStagingDomainName(config);
+  const requiredOrigins = [
+    ...(cms.domainName ? [`https://${cms.domainName}/`] : []),
+    ...(stagingDomainName ? [`https://${stagingDomainName}/`] : []),
+    LOCAL_DEVELOPMENT_ORIGIN,
+  ];
+  for (const origin of requiredOrigins) {
+    if (!redirectUrls.includes(origin)) {
+      fail("cms.environment.PAPYRUS_OAUTH_REDIRECT_URLS", `must include ${origin}`);
+    }
+  }
+
+  return config;
+}

package/lib/amplify-outputs-guard.ts

@@ -0,0 +1,24 @@
+const PRODUCTION_GRAPHQL_HOST = "64hviw";
+const PRODUCTION_USER_POOL_ID = "us-east-1_40Uot7WSv";
+
+export function isProductionAmplifyOutputs(outputs: Record<string, unknown> | null): boolean {
+  if (!outputs) return false;
+  const graphqlUrl = String((outputs.data as { url?: string } | undefined)?.url ?? "");
+  const userPoolId = String((outputs.auth as { user_pool_id?: string } | undefined)?.user_pool_id ?? "");
+  return graphqlUrl.includes(PRODUCTION_GRAPHQL_HOST) || userPoolId === PRODUCTION_USER_POOL_ID;
+}
+
+export function assertSandboxAmplifyOutputsForDev(outputs: Record<string, unknown>): void {
+  if (process.env.NODE_ENV === "production") return;
+  if (!isProductionAmplifyOutputs(outputs)) return;
+  const graphqlUrl = String((outputs.data as { url?: string } | undefined)?.url ?? "");
+  throw new Error(
+    [
+      "Papyrus dev is configured for production Amplify (amplify_outputs.json → " +
+        (graphqlUrl || "production AppSync") +
+        ").",
+      "Run `npm run outputs:sandbox` or restart with `npm run dev` (runs ensure-sandbox-amplify-outputs first).",
+      "Use ~/Projects/Papyrus-production for production deploys only.",
+    ].join(" "),
+  );
+}

package/lib/amplify-outputs-path.ts

@@ -0,0 +1,16 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function getAmplifyOutputsPath(): string {
+  const explicit = process.env.PAPYRUS_AMPLIFY_OUTPUTS?.trim();
+  if (explicit) {
+    return path.isAbsolute(explicit) ? explicit : path.join(process.cwd(), explicit);
+  }
+  return path.join(process.cwd(), "amplify_outputs.json");
+}
+
+export function readAmplifyOutputsFile(): Record<string, unknown> | null {
+  const outputsPath = getAmplifyOutputsPath();
+  if (!fs.existsSync(outputsPath)) return null;
+  return JSON.parse(fs.readFileSync(outputsPath, "utf8")) as Record<string, unknown>;
+}