@anthusai/papyrus 1.0.0-next.9 → 1.1.0

package/amplify/publication/renditions-function.ts

@@ -0,0 +1,112 @@
+import { Duration, Size } from "aws-cdk-lib";
+import * as events from "aws-cdk-lib/aws-events";
+import * as targets from "aws-cdk-lib/aws-events-targets";
+import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { Architecture, type Code, Function as LambdaFunction, Runtime } from "aws-cdk-lib/aws-lambda";
+import * as s3 from "aws-cdk-lib/aws-s3";
+import * as sqs from "aws-cdk-lib/aws-sqs";
+import type { Construct } from "constructs";
+import { execSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { pythonLambdaCode, type SiteBundleFile } from "../functions/shared/python-bundle";
+import {
+  RENDITIONS_EPHEMERAL_STORAGE_MB,
+  RENDITIONS_MEDIA_PREFIX,
+  RENDITIONS_MEMORY_MB,
+  RENDITIONS_TIMEOUT_SECONDS,
+  renditionsEnvironment,
+  renditionsEventPattern,
+} from "./renditions-settings";
+
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(dirname, "../..");
+
+export const renditionsRequirements = ["PyYAML>=6.0.2,<7", "citeproc-py>=0.8.2,<1", "anthus-markus==0.5.1", "Pillow>=11.3,<12"];
+
+export type RenditionsFunctionProps = {
+  siteBucket: s3.IBucket;
+  mediaBucket: s3.IBucket;
+  siteFiles: SiteBundleFile[];
+  code?: Code;
+};
+
+export type RenditionsFunction = {
+  function: LambdaFunction;
+  rule: events.Rule;
+  deadLetterQueue: sqs.Queue;
+};
+
+function installCheckoutRequirements(outputDir: string): void {
+  const requirementsPath = path.join(projectRoot, "amplify/functions/renditions/requirements.txt");
+  execSync(
+    `python3 -m pip install -r "${requirementsPath}" -t "${outputDir}" --no-cache-dir --platform manylinux2014_aarch64 --implementation cp --python-version 3.12 --only-binary=:all: --ignore-requires-python`,
+    { cwd: projectRoot, stdio: "inherit" },
+  );
+}
+
+export function addRenditionsFunction(scope: Construct, props: RenditionsFunctionProps): RenditionsFunction {
+  const deadLetterQueue = new sqs.Queue(scope, "RenditionsDeadLetterQueue", {
+    encryption: sqs.QueueEncryption.SQS_MANAGED,
+    retentionPeriod: Duration.days(14),
+    enforceSSL: true,
+  });
+  const renditions = new LambdaFunction(scope, "RenditionsFunction", {
+    runtime: Runtime.PYTHON_3_12,
+    architecture: Architecture.ARM_64,
+    handler: "handler.handler",
+    timeout: Duration.seconds(RENDITIONS_TIMEOUT_SECONDS),
+    memorySize: RENDITIONS_MEMORY_MB,
+    ephemeralStorageSize: Size.mebibytes(RENDITIONS_EPHEMERAL_STORAGE_MB),
+    retryAttempts: 2,
+    deadLetterQueue,
+    environment: renditionsEnvironment(props.siteBucket.bucketName),
+    code: props.code ?? pythonLambdaCode(
+      {
+        functionDir: "renditions",
+        modules: ["papyrus_content"],
+        requirements: renditionsRequirements,
+        noDeps: true,
+        checkoutExtras: installCheckoutRequirements,
+        siteFiles: props.siteFiles,
+      },
+      [
+        "bash",
+        "-c",
+        [
+          "set -euo pipefail",
+          "mkdir -p /asset-output/papyrus_content",
+          "cp amplify/functions/renditions/handler.py /asset-output/handler.py",
+          "cp -R src/papyrus_content/. /asset-output/papyrus_content/",
+          "python3 -m pip install -r amplify/functions/renditions/requirements.txt -t /asset-output --no-cache-dir",
+        ].join(" && "),
+      ],
+    ),
+  });
+  renditions.addToRolePolicy(
+    new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: ["s3:GetObject"],
+      resources: [props.mediaBucket.arnForObjects(`${RENDITIONS_MEDIA_PREFIX}*`)],
+    }),
+  );
+  renditions.addToRolePolicy(
+    new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: ["s3:PutObject", "s3:GetObject"],
+      resources: [props.siteBucket.arnForObjects("*")],
+    }),
+  );
+  renditions.addToRolePolicy(
+    new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: ["s3:ListBucket"],
+      resources: [props.siteBucket.bucketArn],
+    }),
+  );
+  const rule = new events.Rule(scope, "MediaObjectCreatedRule", {
+    eventPattern: renditionsEventPattern(props.mediaBucket.bucketName),
+  });
+  rule.addTarget(new targets.LambdaFunction(renditions, { retryAttempts: 2 }));
+  return { function: renditions, rule, deadLetterQueue };
+}

package/amplify/publication/renditions-settings.js

@@ -0,0 +1,51 @@
+/**
+ * Pure planning for the upload-time renditions function of an s3-projection
+ * site (no CDK imports, so it can be tested without synthesizing).
+ *
+ * The function exists only for a site whose `projection.json` carries an
+ * `images` section (the one place the image pipeline settings live, shared by
+ * the renditions function and the projector) or `media.originals: true`
+ * (every media object is also published as is, at its key without `media/`).
+ */
+import fs from "node:fs";
+import path from "node:path";
+export const RENDITIONS_MEMORY_MB = 3008;
+export const RENDITIONS_TIMEOUT_SECONDS = 300;
+export const RENDITIONS_EPHEMERAL_STORAGE_MB = 2048;
+export const RENDITIONS_STATIC_DIRECTORY = "/var/task/site_static";
+export const RENDITIONS_MEDIA_PREFIX = "media/";
+export const RENDITIONS_FUNCTION_NAME_ENV = "PAPYRUS_RENDITIONS_FUNCTION_NAME";
+export function projectionSettingsHaveImages(settingsPath) {
+    if (!fs.existsSync(settingsPath))
+        return false;
+    const parsed = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    return typeof parsed.images === "object" && parsed.images !== null;
+}
+export function projectionSettingsPublishOriginals(settingsPath) {
+    if (!fs.existsSync(settingsPath))
+        return false;
+    const parsed = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    return parsed.media?.originals === true;
+}
+export function planRenditions(publication, workingDirectory) {
+    if (publication?.staticDir === undefined)
+        return { enabled: false, siteFiles: [] };
+    const settingsFile = path.join(publication.staticDir, "projection.json");
+    const resolved = path.resolve(workingDirectory, settingsFile);
+    if (!projectionSettingsHaveImages(resolved) && !projectionSettingsPublishOriginals(resolved))
+        return { enabled: false, siteFiles: [] };
+    return { enabled: true, siteFiles: [{ from: settingsFile, to: "site_static/projection.json" }] };
+}
+export function renditionsEventPattern(mediaBucketName) {
+    return {
+        source: ["aws.s3"],
+        detailType: ["Object Created"],
+        detail: { bucket: { name: [mediaBucketName] }, object: { key: [{ prefix: RENDITIONS_MEDIA_PREFIX }] } },
+    };
+}
+export function renditionsEnvironment(siteBucketName) {
+    return {
+        PAPYRUS_SITE_BUCKET: siteBucketName,
+        PAPYRUS_SITE_STATIC_DIR: RENDITIONS_STATIC_DIRECTORY,
+    };
+}

package/amplify/publication/renditions-settings.ts

@@ -0,0 +1,58 @@
+/**
+ * Pure planning for the upload-time renditions function of an s3-projection
+ * site (no CDK imports, so it can be tested without synthesizing).
+ *
+ * The function exists only for a site whose `projection.json` carries an
+ * `images` section (the one place the image pipeline settings live, shared by
+ * the renditions function and the projector) or `media.originals: true`
+ * (every media object is also published as is, at its key without `media/`).
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+export const RENDITIONS_MEMORY_MB = 3008;
+export const RENDITIONS_TIMEOUT_SECONDS = 300;
+export const RENDITIONS_EPHEMERAL_STORAGE_MB = 2048;
+export const RENDITIONS_STATIC_DIRECTORY = "/var/task/site_static";
+export const RENDITIONS_MEDIA_PREFIX = "media/";
+export const RENDITIONS_FUNCTION_NAME_ENV = "PAPYRUS_RENDITIONS_FUNCTION_NAME";
+
+export type RenditionsPlan = {
+  enabled: boolean;
+  siteFiles: Array<{ from: string; to: string }>;
+};
+
+export function projectionSettingsHaveImages(settingsPath: string): boolean {
+  if (!fs.existsSync(settingsPath)) return false;
+  const parsed = JSON.parse(fs.readFileSync(settingsPath, "utf8")) as Record<string, unknown>;
+  return typeof parsed.images === "object" && parsed.images !== null;
+}
+
+export function projectionSettingsPublishOriginals(settingsPath: string): boolean {
+  if (!fs.existsSync(settingsPath)) return false;
+  const parsed = JSON.parse(fs.readFileSync(settingsPath, "utf8")) as { media?: { originals?: unknown } };
+  return parsed.media?.originals === true;
+}
+
+export function planRenditions(publication: { staticDir?: string } | undefined, workingDirectory: string): RenditionsPlan {
+  if (publication?.staticDir === undefined) return { enabled: false, siteFiles: [] };
+  const settingsFile = path.join(publication.staticDir, "projection.json");
+  const resolved = path.resolve(workingDirectory, settingsFile);
+  if (!projectionSettingsHaveImages(resolved) && !projectionSettingsPublishOriginals(resolved)) return { enabled: false, siteFiles: [] };
+  return { enabled: true, siteFiles: [{ from: settingsFile, to: "site_static/projection.json" }] };
+}
+
+export function renditionsEventPattern(mediaBucketName: string): Record<string, unknown> {
+  return {
+    source: ["aws.s3"],
+    detailType: ["Object Created"],
+    detail: { bucket: { name: [mediaBucketName] }, object: { key: [{ prefix: RENDITIONS_MEDIA_PREFIX }] } },
+  };
+}
+
+export function renditionsEnvironment(siteBucketName: string): Record<string, string> {
+  return {
+    PAPYRUS_SITE_BUCKET: siteBucketName,
+    PAPYRUS_SITE_STATIC_DIR: RENDITIONS_STATIC_DIRECTORY,
+  };
+}

package/amplify/publication/reproject-on-deploy.js

@@ -0,0 +1,73 @@
+import { CustomResource, Duration } from "aws-cdk-lib";
+import * as cloudwatch from "aws-cdk-lib/aws-cloudwatch";
+import { PolicyStatement } from "aws-cdk-lib/aws-iam";
+import * as lambda from "aws-cdk-lib/aws-lambda";
+import { Provider } from "aws-cdk-lib/custom-resources";
+export const REPROJECT_ON_DEPLOY_TIMEOUT_SECONDS = 900;
+export const DEPLOY_RENDER_METRIC_NAMESPACE = "Papyrus/Projection";
+export const DEPLOY_RENDER_DRIFT_METRIC_NAME = "DeployRenderDrift";
+export const DEPLOY_RENDER_TASK = "deploy-render";
+const FAILURE_MESSAGE_LIMIT = 600;
+const RESULT_SUMMARY_LIMIT = 900;
+export function reprojectDeployToken(environment, now = Date.now) {
+    const buildJobId = (environment.AWS_JOB_ID ?? "").trim();
+    return buildJobId !== "" ? `job-${buildJobId}` : `time-${now()}`;
+}
+/**
+ * Runs inside the deploy: invokes the content-actions Lambda synchronously, so a render that fails fails the
+ * stack update (and with it the Amplify build) with the failure in the build log. The Lambda's result, which
+ * includes the drift check, is written to its log and returned as the resource's data.
+ */
+export const DEPLOY_RENDER_HANDLER_SOURCE = `
+const { LambdaClient, InvokeCommand } = require("@aws-sdk/client-lambda");
+
+exports.handler = async (event) => {
+  if (event.RequestType === "Delete") return { PhysicalResourceId: event.PhysicalResourceId };
+  const properties = event.ResourceProperties;
+  const client = new LambdaClient({ maxAttempts: 1 });
+  const response = await client.send(new InvokeCommand({
+    FunctionName: properties.FunctionName,
+    InvocationType: "RequestResponse",
+    Payload: JSON.stringify({ projectionTask: { task: properties.Task, deployToken: properties.DeployToken } }),
+  }));
+  const text = Buffer.from(response.Payload || []).toString("utf8");
+  console.log("deploy render result: " + text);
+  if (response.FunctionError) {
+    throw new Error("The post-deploy render failed (" + response.FunctionError + "): " + text.slice(0, ${FAILURE_MESSAGE_LIMIT}));
+  }
+  return { PhysicalResourceId: "reproject-" + properties.DeployToken, Data: { Result: text.slice(0, ${RESULT_SUMMARY_LIMIT}) } };
+};
+`;
+/**
+ * Renders every published page after each backend deploy and checks the site store for drift (a dry run:
+ * nothing is deleted). The token is a property, so CloudFormation runs the resource again on every deploy.
+ */
+export function addReprojectOnDeploy(stack, contentActions, deployToken) {
+    const handler = new lambda.Function(stack, "DeployRenderHandler", {
+        runtime: lambda.Runtime.NODEJS_20_X,
+        handler: "index.handler",
+        code: lambda.Code.fromInline(DEPLOY_RENDER_HANDLER_SOURCE),
+        timeout: Duration.seconds(REPROJECT_ON_DEPLOY_TIMEOUT_SECONDS),
+        description: "Starts the post-deploy render of the site and fails the deploy if it cannot finish.",
+    });
+    handler.addToRolePolicy(new PolicyStatement({ actions: ["lambda:InvokeFunction"], resources: [contentActions.functionArn] }));
+    const provider = new Provider(stack, "DeployRenderProvider", { onEventHandler: handler });
+    new cloudwatch.Alarm(stack, "DeployRenderDriftAlarm", {
+        metric: new cloudwatch.Metric({
+            namespace: DEPLOY_RENDER_METRIC_NAMESPACE,
+            metricName: DEPLOY_RENDER_DRIFT_METRIC_NAME,
+            dimensionsMap: { FunctionName: contentActions.functionName },
+            statistic: "Maximum",
+            period: Duration.days(1),
+        }),
+        evaluationPeriods: 1,
+        threshold: 1,
+        comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+        treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
+        alarmDescription: "The last post-deploy render found drift between the published content and the site store (stale pages, orphan pages or redirects). Nothing was deleted; run papyrus ops content project --reconcile to repair.",
+    });
+    return new CustomResource(stack, "ReprojectOnDeploy", {
+        serviceToken: provider.serviceToken,
+        properties: { FunctionName: contentActions.functionName, Task: DEPLOY_RENDER_TASK, DeployToken: deployToken },
+    });
+}

package/amplify/publication/reproject-on-deploy.ts

@@ -0,0 +1,78 @@
+import { CustomResource, Duration, Stack } from "aws-cdk-lib";
+import * as cloudwatch from "aws-cdk-lib/aws-cloudwatch";
+import { PolicyStatement } from "aws-cdk-lib/aws-iam";
+import * as lambda from "aws-cdk-lib/aws-lambda";
+import { Provider } from "aws-cdk-lib/custom-resources";
+
+export const REPROJECT_ON_DEPLOY_TIMEOUT_SECONDS = 900;
+export const DEPLOY_RENDER_METRIC_NAMESPACE = "Papyrus/Projection";
+export const DEPLOY_RENDER_DRIFT_METRIC_NAME = "DeployRenderDrift";
+export const DEPLOY_RENDER_TASK = "deploy-render";
+const FAILURE_MESSAGE_LIMIT = 600;
+const RESULT_SUMMARY_LIMIT = 900;
+
+export function reprojectDeployToken(environment: Record<string, string | undefined>, now: () => number = Date.now): string {
+  const buildJobId = (environment.AWS_JOB_ID ?? "").trim();
+  return buildJobId !== "" ? `job-${buildJobId}` : `time-${now()}`;
+}
+
+/**
+ * Runs inside the deploy: invokes the content-actions Lambda synchronously, so a render that fails fails the
+ * stack update (and with it the Amplify build) with the failure in the build log. The Lambda's result, which
+ * includes the drift check, is written to its log and returned as the resource's data.
+ */
+export const DEPLOY_RENDER_HANDLER_SOURCE = `
+const { LambdaClient, InvokeCommand } = require("@aws-sdk/client-lambda");
+
+exports.handler = async (event) => {
+  if (event.RequestType === "Delete") return { PhysicalResourceId: event.PhysicalResourceId };
+  const properties = event.ResourceProperties;
+  const client = new LambdaClient({ maxAttempts: 1 });
+  const response = await client.send(new InvokeCommand({
+    FunctionName: properties.FunctionName,
+    InvocationType: "RequestResponse",
+    Payload: JSON.stringify({ projectionTask: { task: properties.Task, deployToken: properties.DeployToken } }),
+  }));
+  const text = Buffer.from(response.Payload || []).toString("utf8");
+  console.log("deploy render result: " + text);
+  if (response.FunctionError) {
+    throw new Error("The post-deploy render failed (" + response.FunctionError + "): " + text.slice(0, ${FAILURE_MESSAGE_LIMIT}));
+  }
+  return { PhysicalResourceId: "reproject-" + properties.DeployToken, Data: { Result: text.slice(0, ${RESULT_SUMMARY_LIMIT}) } };
+};
+`;
+
+/**
+ * Renders every published page after each backend deploy and checks the site store for drift (a dry run:
+ * nothing is deleted). The token is a property, so CloudFormation runs the resource again on every deploy.
+ */
+export function addReprojectOnDeploy(stack: Stack, contentActions: lambda.IFunction, deployToken: string): CustomResource {
+  const handler = new lambda.Function(stack, "DeployRenderHandler", {
+    runtime: lambda.Runtime.NODEJS_20_X,
+    handler: "index.handler",
+    code: lambda.Code.fromInline(DEPLOY_RENDER_HANDLER_SOURCE),
+    timeout: Duration.seconds(REPROJECT_ON_DEPLOY_TIMEOUT_SECONDS),
+    description: "Starts the post-deploy render of the site and fails the deploy if it cannot finish.",
+  });
+  handler.addToRolePolicy(new PolicyStatement({ actions: ["lambda:InvokeFunction"], resources: [contentActions.functionArn] }));
+  const provider = new Provider(stack, "DeployRenderProvider", { onEventHandler: handler });
+  new cloudwatch.Alarm(stack, "DeployRenderDriftAlarm", {
+    metric: new cloudwatch.Metric({
+      namespace: DEPLOY_RENDER_METRIC_NAMESPACE,
+      metricName: DEPLOY_RENDER_DRIFT_METRIC_NAME,
+      dimensionsMap: { FunctionName: contentActions.functionName },
+      statistic: "Maximum",
+      period: Duration.days(1),
+    }),
+    evaluationPeriods: 1,
+    threshold: 1,
+    comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+    treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
+    alarmDescription:
+      "The last post-deploy render found drift between the published content and the site store (stale pages, orphan pages or redirects). Nothing was deleted; run papyrus ops content project --reconcile to repair.",
+  });
+  return new CustomResource(stack, "ReprojectOnDeploy", {
+    serviceToken: provider.serviceToken,
+    properties: { FunctionName: contentActions.functionName, Task: DEPLOY_RENDER_TASK, DeployToken: deployToken },
+  });
+}

package/amplify/publication/s3-projection-settings.js

@@ -0,0 +1,67 @@
+export const S3_PROJECTION_PROJECTOR_MODULE = "site_projector";
+export const S3_PROJECTION_STATIC_DIRECTORY = "/var/task/site_static";
+export function distributionIdFromArn(distributionArn) {
+    return distributionArn.slice(distributionArn.lastIndexOf("/") + 1);
+}
+export function s3ProjectionEnvironment(input) {
+    const environment = {
+        PAPYRUS_PUBLICATION_KIND: "s3-projection",
+        PAPYRUS_SITE_BUCKET: input.bucketName,
+    };
+    const distributionId = input.distributionId
+        ?? (input.distributionArn !== undefined ? distributionIdFromArn(input.distributionArn) : undefined);
+    if (distributionId !== undefined)
+        environment.PAPYRUS_EDGE_DISTRIBUTION_ID = distributionId;
+    environment.PAPYRUS_REDIRECTS_KVS_ARN = input.keyValueStoreArn;
+    environment.PAPYRUS_PROJECTION_DLQ_URL = input.deadLetterQueueUrl;
+    if (input.cache?.htmlSMaxAgeSeconds !== undefined)
+        environment.PAPYRUS_HTML_S_MAXAGE_SECONDS = String(input.cache.htmlSMaxAgeSeconds);
+    if (input.cache?.invalidation === "off")
+        environment.PAPYRUS_EDGE_INVALIDATION = "off";
+    if (input.publicHostName !== undefined)
+        environment.PAPYRUS_SITE_PUBLIC_URL = `https://${input.publicHostName}`;
+    if (input.projector !== undefined)
+        environment.PAPYRUS_SITE_PROJECTOR = S3_PROJECTION_PROJECTOR_MODULE;
+    if (input.staticDir !== undefined)
+        environment.PAPYRUS_SITE_STATIC_DIR = S3_PROJECTION_STATIC_DIRECTORY;
+    return environment;
+}
+export function s3ProjectionPolicyStatements(input) {
+    const statements = [
+        { actions: ["s3:PutObject", "s3:DeleteObject", "s3:GetObject"], resources: [`${input.bucketArn}/*`] },
+        { actions: ["s3:ListBucket"], resources: [input.bucketArn] },
+    ];
+    if (input.distributionArn !== undefined && input.cache?.invalidation !== "off") {
+        statements.push({ actions: ["cloudfront:CreateInvalidation"], resources: [input.distributionArn] });
+    }
+    statements.push({
+        actions: [
+            "cloudfront-keyvaluestore:DescribeKeyValueStore",
+            "cloudfront-keyvaluestore:GetKey",
+            "cloudfront-keyvaluestore:PutKey",
+            "cloudfront-keyvaluestore:DeleteKey",
+            "cloudfront-keyvaluestore:UpdateKeys",
+            "cloudfront-keyvaluestore:ListKeys",
+        ],
+        resources: [input.keyValueStoreArn],
+    }, { actions: ["sqs:SendMessage"], resources: [input.deadLetterQueueArn] });
+    return statements;
+}
+export const S3_PROJECTION_CONTENT_ACTIONS_MEMORY_MB = 2048;
+export function planS3ProjectionBackend(publication) {
+    if (publication === undefined)
+        return { enabled: false, siteFiles: [], contentActionsMemorySize: undefined };
+    const siteFiles = [];
+    if (publication.projector !== undefined) {
+        siteFiles.push({ from: publication.projector, to: `${S3_PROJECTION_PROJECTOR_MODULE}.py` });
+    }
+    if (publication.staticDir !== undefined) {
+        siteFiles.push({ from: publication.staticDir, to: "site_static" });
+    }
+    return { enabled: true, siteFiles, contentActionsMemorySize: S3_PROJECTION_CONTENT_ACTIONS_MEMORY_MB };
+}
+export function contentActionsPublicationWiring(publication) {
+    if (publication === undefined)
+        return { environment: {}, policyStatements: [] };
+    return { environment: publication.environment, policyStatements: publication.policyStatements };
+}

package/amplify/publication/s3-projection-settings.ts

@@ -0,0 +1,101 @@
+/**
+ * Environment contract and IAM statements for the s3-projection publication.
+ * Pure (no CDK imports) so both can be tested without synthesizing.
+ */
+export type S3ProjectionSettingsInput = {
+  bucketName: string;
+  bucketArn: string;
+  keyValueStoreArn: string;
+  deadLetterQueueUrl: string;
+  deadLetterQueueArn: string;
+  distributionArn?: string;
+  distributionId?: string;
+  publicHostName?: string;
+  cache?: { htmlSMaxAgeSeconds?: number; invalidation?: "targeted" | "off" };
+  projector?: string;
+  staticDir?: string;
+};
+
+export type S3ProjectionPolicyStatementSpec = {
+  actions: string[];
+  resources: string[];
+};
+
+export const S3_PROJECTION_PROJECTOR_MODULE = "site_projector";
+export const S3_PROJECTION_STATIC_DIRECTORY = "/var/task/site_static";
+
+export function distributionIdFromArn(distributionArn: string): string {
+  return distributionArn.slice(distributionArn.lastIndexOf("/") + 1);
+}
+
+export function s3ProjectionEnvironment(input: S3ProjectionSettingsInput): Record<string, string> {
+  const environment: Record<string, string> = {
+    PAPYRUS_PUBLICATION_KIND: "s3-projection",
+    PAPYRUS_SITE_BUCKET: input.bucketName,
+  };
+  const distributionId = input.distributionId
+    ?? (input.distributionArn !== undefined ? distributionIdFromArn(input.distributionArn) : undefined);
+  if (distributionId !== undefined) environment.PAPYRUS_EDGE_DISTRIBUTION_ID = distributionId;
+  environment.PAPYRUS_REDIRECTS_KVS_ARN = input.keyValueStoreArn;
+  environment.PAPYRUS_PROJECTION_DLQ_URL = input.deadLetterQueueUrl;
+  if (input.cache?.htmlSMaxAgeSeconds !== undefined) environment.PAPYRUS_HTML_S_MAXAGE_SECONDS = String(input.cache.htmlSMaxAgeSeconds);
+  if (input.cache?.invalidation === "off") environment.PAPYRUS_EDGE_INVALIDATION = "off";
+  if (input.publicHostName !== undefined) environment.PAPYRUS_SITE_PUBLIC_URL = `https://${input.publicHostName}`;
+  if (input.projector !== undefined) environment.PAPYRUS_SITE_PROJECTOR = S3_PROJECTION_PROJECTOR_MODULE;
+  if (input.staticDir !== undefined) environment.PAPYRUS_SITE_STATIC_DIR = S3_PROJECTION_STATIC_DIRECTORY;
+  return environment;
+}
+
+export function s3ProjectionPolicyStatements(input: S3ProjectionSettingsInput): S3ProjectionPolicyStatementSpec[] {
+  const statements: S3ProjectionPolicyStatementSpec[] = [
+    { actions: ["s3:PutObject", "s3:DeleteObject", "s3:GetObject"], resources: [`${input.bucketArn}/*`] },
+    { actions: ["s3:ListBucket"], resources: [input.bucketArn] },
+  ];
+  if (input.distributionArn !== undefined && input.cache?.invalidation !== "off") {
+    statements.push({ actions: ["cloudfront:CreateInvalidation"], resources: [input.distributionArn] });
+  }
+  statements.push(
+    {
+      actions: [
+        "cloudfront-keyvaluestore:DescribeKeyValueStore",
+        "cloudfront-keyvaluestore:GetKey",
+        "cloudfront-keyvaluestore:PutKey",
+        "cloudfront-keyvaluestore:DeleteKey",
+        "cloudfront-keyvaluestore:UpdateKeys",
+        "cloudfront-keyvaluestore:ListKeys",
+      ],
+      resources: [input.keyValueStoreArn],
+    },
+    { actions: ["sqs:SendMessage"], resources: [input.deadLetterQueueArn] },
+  );
+  return statements;
+}
+
+export type S3ProjectionBackendPlan = {
+  enabled: boolean;
+  siteFiles: Array<{ from: string; to: string }>;
+  contentActionsMemorySize: number | undefined;
+};
+
+export const S3_PROJECTION_CONTENT_ACTIONS_MEMORY_MB = 2048;
+
+export function planS3ProjectionBackend(
+  publication: { projector?: string; staticDir?: string } | undefined,
+): S3ProjectionBackendPlan {
+  if (publication === undefined) return { enabled: false, siteFiles: [], contentActionsMemorySize: undefined };
+  const siteFiles: Array<{ from: string; to: string }> = [];
+  if (publication.projector !== undefined) {
+    siteFiles.push({ from: publication.projector, to: `${S3_PROJECTION_PROJECTOR_MODULE}.py` });
+  }
+  if (publication.staticDir !== undefined) {
+    siteFiles.push({ from: publication.staticDir, to: "site_static" });
+  }
+  return { enabled: true, siteFiles, contentActionsMemorySize: S3_PROJECTION_CONTENT_ACTIONS_MEMORY_MB };
+}
+
+export function contentActionsPublicationWiring<Statement>(
+  publication: { environment: Record<string, string>; policyStatements: Statement[] } | undefined,
+): { environment: Record<string, string>; policyStatements: Statement[] } {
+  if (publication === undefined) return { environment: {}, policyStatements: [] };
+  return { environment: publication.environment, policyStatements: publication.policyStatements };
+}