@pathmx/cloudflare 0.5.0

package/LICENSE.md

@@ -0,0 +1,172 @@
+# PathMX Proprietary Beta License
+
+Version 0.1 — July 21, 2026
+
+Copyright © 2026 DUO Interactive, LLC.
+All rights reserved.
+
+This license governs the first-party PathMX software distributed in the npm
+package `@pathmx/core`, including its command-line interface, bundled
+library surfaces, runtime and Player components, and accompanying
+documentation (the “Software”). DUO Interactive, LLC is the “Licensor.” This
+license does not cover the private PathMX source-code repository or separately
+identified third-party materials.
+
+“Project” means Paths, Sources, responses, data, and other content authored or
+processed with the Software.
+
+“Application” means software or a service created by you in which the Software
+supports product-specific functionality but is not itself offered as a
+general-purpose PathMX product.
+
+“Redistributable Components” means runtime, Player, or library portions of the
+Software incorporated into a Project, Application, or generated output through
+ordinary use of the Software or ordinary compilation and bundling tools.
+
+“Authorized Users” means your employees and individual contractors who use the
+Software on your behalf, and your hosting, continuous-integration, and other
+service providers that possess or run necessary copies solely to provide
+services to you.
+
+## 1. Agreement
+
+By installing, accessing, or using the Software, you agree to this license. If
+you use the Software on behalf of an organization, you represent that you have
+authority to accept this license for that organization. If you do not agree,
+do not install or use the Software.
+
+## 2. License grant
+
+Subject to this license, the Licensor grants you a non-exclusive, worldwide,
+royalty-free, non-transferable, and non-sublicensable license, perpetual for
+the version of the Software to which it applies unless terminated under
+Section 10, to:
+
+- install, execute, and use the Software for personal, educational,
+  internal-business, or commercial purposes;
+- use the Software to author, integrate, build, test, serve, play, host, and
+  operate Projects and Applications;
+- import, compile, bundle, configure, and integrate the Software through its
+  documented library and command-line interfaces;
+- create and distribute independent Projects, Applications, plugins, and
+  integrations that use those interfaces without modifying the Software
+  itself; and
+- make copies reasonably necessary for local development, testing, continuous
+  integration, backup, and hosted production environments.
+
+Your Authorized Users may exercise those rights solely on your behalf. You are
+responsible for their compliance with this license.
+
+You may reproduce and distribute Redistributable Components only as
+incorporated into your Project, Application, or generated output, and only when
+you preserve applicable license and proprietary notices. You may host and
+commercially provide access to that Project, Application, or output. You may
+not distribute Redistributable Components as a standalone package or as a
+general-purpose substitute for the Software.
+
+Each lawful recipient of a Redistributable Component may execute and use that
+component, display its output, and make technically necessary transitory copies
+solely as incorporated into the Project, Application, or output in which they
+received it. This limited recipient permission does not include a right to
+extract, modify, or redistribute the component separately.
+
+## 3. Restrictions
+
+Except where applicable law does not allow the restriction, you may not:
+
+- modify, adapt, translate, or create derivative works of the Software, except
+  for the compilation, bundling, configuration, and integration expressly
+  permitted in Section 2;
+- redistribute, sublicense, sell, lease, or otherwise provide the Software to
+  another person as a standalone package, product, or service except to an
+  Authorized User or as a Redistributable Component under Section 2;
+- resell, rebrand, or provide the Software as a hosted or managed service that
+  gives third parties general-purpose access to substantial PathMX authoring,
+  building, serving, Player-administration, or library functionality for their
+  own unrelated projects;
+- reverse engineer, decompile, disassemble, or otherwise attempt to derive the
+  source code of the Software; or
+- remove or alter copyright, license, trademark, or other proprietary notices.
+
+For clarity, the managed-service restriction does not prohibit a hosted
+Project or Application in which PathMX supports the licensee's own
+product-specific experience and is not itself the general-purpose product
+offered to customers.
+
+## 4. Your content
+
+As between you and the Licensor, you retain ownership of the Paths, Sources,
+responses, data, independent application code, and other content that you
+author or provide while using the Software. You are responsible for that
+content and for having the rights needed to use it.
+
+Generated output may contain Redistributable Components or third-party
+materials. Your ownership of your content does not change the ownership or
+license terms of those components and materials.
+
+## 5. Ownership and trademarks
+
+The Software is licensed, not sold. The Licensor and its suppliers retain all
+rights in the Software not expressly granted by this license. This license
+does not grant permission to use the PathMX name, logos, or other marks except
+as reasonably necessary to identify the Software accurately.
+
+## 6. Beta status and changes
+
+The Software is a proprietary beta release. Its APIs, behavior, file formats,
+and features may change or be removed without notice. The Licensor has no
+obligation to provide support, maintenance, updates, continued availability,
+or backward compatibility. A later version may be offered under different
+license terms, including an open-source license. Different terms for a later
+version do not change the license previously granted for an earlier version.
+
+## 7. Third-party materials
+
+The Software and Redistributable Components may include or depend on
+third-party materials governed by their own license terms. Those terms control
+for the applicable third-party materials. You must preserve third-party notices
+when the applicable third-party terms require it.
+
+## 8. Disclaimer of warranties
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED “AS IS” AND
+“AS AVAILABLE,” WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EXPRESS,
+IMPLIED, OR STATUTORY, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT, OR THAT THE SOFTWARE WILL BE
+SECURE, ERROR-FREE, OR UNINTERRUPTED.
+
+## 9. Limitation of liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE LICENSOR AND ITS CONTRIBUTORS,
+SUPPLIERS, AND AFFILIATES WILL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR FOR LOSS OF DATA,
+PROFITS, REVENUE, GOODWILL, OR BUSINESS OPPORTUNITY, ARISING FROM OR RELATED TO
+THE SOFTWARE OR THIS LICENSE, EVEN IF ADVISED OF THE POSSIBILITY OF THOSE
+DAMAGES.
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THEIR TOTAL LIABILITY FOR ALL CLAIMS
+ARISING FROM OR RELATED TO THE SOFTWARE OR THIS LICENSE WILL NOT EXCEED THE
+GREATER OF THE AMOUNT YOU PAID FOR THE SOFTWARE DURING THE TWELVE MONTHS BEFORE
+THE EVENT GIVING RISE TO THE CLAIM OR US$100.
+
+## 10. Termination
+
+This license terminates if you materially breach it and do not cure the breach
+within thirty days after receiving written notice from the Licensor. On
+termination, you and your Authorized Users must stop using and delete your
+copies of the Software. Sections 4, 5, 8, 9, 10, and 11 survive termination.
+Termination does not withdraw the limited permission already granted by
+Section 2 to lawful recipients of Redistributable Components distributed
+before termination.
+
+## 11. General
+
+If a provision of this license is unenforceable, it will be modified only to
+the minimum extent necessary to make it enforceable, and the remaining
+provisions will continue in effect. Failure to enforce a provision is not a
+waiver. You may not assign or transfer this license without the Licensor's
+written consent. The Licensor may assign this license together with ownership
+of the Software to a successor owner. This license binds and benefits the
+permitted successors and assigns of you and the Licensor. This license is the
+entire agreement concerning the Software unless you and the Licensor have
+signed a separate agreement that expressly replaces it.

package/README.md

@@ -0,0 +1,60 @@
+# @pathmx/cloudflare
+
+Opt-in publication plugin for deploying PathMX static publications as a
+Cloudflare Worker with Static Assets.
+
+```ts
+// plugins/cloudflare.plugin.ts
+import { CloudflarePlugin } from "@pathmx/cloudflare"
+
+export default CloudflarePlugin({
+  accountId: "0123456789abcdef0123456789abcdef",
+  worker: "my-pathmx-site",
+  origin: "https://docs.example.com",
+  basePath: "/course-guide",
+  domain: "docs.example.com",
+  routing: { type: "route", zone: "example.com" },
+})
+```
+
+`basePath` mounts every canonical PathMX route—including exact Markdown,
+runtime assets, polling records, and discovery documents—under one prefix. It
+is useful when a PathMX publication lives beside another application on the
+same origin.
+
+Set `accountId` when local credentials can access more than one Cloudflare
+account. It is written to the generated Wrangler configuration so validation
+and deployment select the same account.
+
+Domains default to Cloudflare Custom Domains. Select zone-route routing when
+an existing Worker route must run before the domain; PathMX emits the exact
+`docs.example.com/*` route so it outranks broader wildcard routes in that zone.
+
+For a sibling source checkout, keep both packages local and override peer
+resolution until they are published:
+
+```json
+{
+  "dependencies": {
+    "@pathmx/cloudflare": "file:../minipathmx/pathmx/cloudflare",
+    "pathmx": "file:../minipathmx/pathmx/core"
+  },
+  "overrides": {
+    "pathmx": "file:../minipathmx/pathmx/core"
+  }
+}
+```
+
+Stage locally by default. Validation invokes pinned Wrangler without deploying;
+deployment is the only command that mutates Cloudflare state.
+
+```sh
+pmx cloudflare publish
+pmx cloudflare publish --dry-run
+pmx cloudflare publish --deploy
+```
+
+The managed stage is written to `.pathmx/publish/cloudflare/`. Its generated
+Worker applies the canonical publication route manifest, including Markdown
+content negotiation and exact `.md` routes, before fetching immutable bodies
+from the Static Assets binding.

package/commands.ts

@@ -0,0 +1,47 @@
+import type { Command } from "commander"
+import type { PluginCommandContext } from "@pathmx/core"
+import type { CloudflarePluginOptions } from "./index.ts"
+import {
+  runCloudflarePublish,
+  type CloudflarePublishAction,
+} from "./publish.ts"
+
+type PublishFlags = Readonly<{
+  dryRun?: boolean
+  deploy?: boolean
+}>
+
+function actionFrom(flags: PublishFlags): CloudflarePublishAction {
+  if (flags.dryRun && flags.deploy) {
+    throw new Error(
+      "Cloudflare publish accepts only one of --dry-run or --deploy.",
+    )
+  }
+  return flags.deploy ? "deploy" : flags.dryRun ? "dry-run" : "stage"
+}
+
+function completion(action: CloudflarePublishAction) {
+  if (action === "deploy") return "Deployed"
+  if (action === "dry-run") return "Validated"
+  return "Staged"
+}
+
+export function registerCloudflareCommands(
+  group: Command,
+  ctx: PluginCommandContext,
+  options: CloudflarePluginOptions,
+) {
+  group
+    .command("publish")
+    .description("Stage or deploy a Cloudflare static Worker publication")
+    .option("--dry-run", "validate the staged deployment with Wrangler")
+    .option("--deploy", "authenticate and deploy with Wrangler")
+    .action(async (flags: PublishFlags) => {
+      const action = actionFrom(flags)
+      const result = await runCloudflarePublish(ctx, options, action)
+      for (const warning of result.warnings) console.warn(`warning: ${warning}`)
+      console.log(
+        `${completion(action)} ${result.routeCount} routes for Cloudflare at ${result.stageDir}`,
+      )
+    })
+}

package/index.ts

@@ -0,0 +1,34 @@
+import { definePlugin, type Plugin } from "@pathmx/core"
+import { registerCloudflareCommands } from "./commands.ts"
+
+export type CloudflareRouting =
+  | Readonly<{ type: "custom-domain" }>
+  | Readonly<{ type: "route"; zone: string }>
+
+export type CloudflarePluginOptions = Readonly<{
+  /** Optional Cloudflare account id used when more than one account is available. */
+  accountId?: string
+  /** Cloudflare Worker name. */
+  worker: string
+  /** Canonical HTTPS publication origin. */
+  origin: string
+  /** Optional same-origin mount path, for example `/course-guide`. */
+  basePath?: string
+  /** Optional custom domain attached only during deployment. */
+  domain?: string
+  /** How the domain is attached. Defaults to a Custom Domain. */
+  routing?: CloudflareRouting
+}>
+
+/** Add an explicit Cloudflare static-Worker publication command. */
+export function CloudflarePlugin(options: CloudflarePluginOptions): Plugin {
+  return definePlugin({
+    id: "cloudflare",
+    name: "Cloudflare",
+    commands(group, ctx) {
+      registerCloudflareCommands(group, ctx, options)
+    },
+  })
+}
+
+export default CloudflarePlugin

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@pathmx/cloudflare",
+  "description": "Cloudflare publication support for PathMX.",
+  "version": "0.5.0",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pathmx/pathmx-beta.git",
+    "directory": "pathmx/cloudflare"
+  },
+  "homepage": "https://github.com/pathmx/pathmx-beta#readme",
+  "bugs": "https://github.com/pathmx/pathmx-beta/issues",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta"
+  },
+  "type": "module",
+  "exports": "./index.ts",
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "peerDependencies": {
+    "@pathmx/core": "^0.5.0"
+  },
+  "dependencies": {
+    "commander": "^15.0.0"
+  }
+}

package/publish.ts

@@ -0,0 +1,512 @@
+import {
+  lstat,
+  mkdir,
+  mkdtemp,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises"
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  sep,
+} from "node:path"
+import type { PluginCommandContext } from "@pathmx/core"
+import { Log, PathMX } from "@pathmx/core/bun"
+import {
+  createPublication,
+  type PublicationManifest,
+  type PublicationRepresentation,
+  type PublicationStore,
+} from "@pathmx/core/publish"
+import type { CloudflarePluginOptions } from "./index.ts"
+import type {
+  CloudflareRepresentation,
+  CloudflareRoute,
+  CloudflareRoutes,
+} from "./runtime.ts"
+
+export const PATHMX_WRANGLER_VERSION = "4.125.0"
+export const CLOUDFLARE_COMPATIBILITY_DATE = "2026-08-24"
+
+const RECEIPT = "receipt.json"
+const RECEIPT_TYPE = "pathmx-cloudflare-publication"
+const RECEIPT_VERSION = 1
+const FREE_ASSET_LIMIT = 20_000
+const MAX_ASSET_LIMIT = 100_000
+const MAX_ASSET_BYTES = 25 * 1024 * 1024
+const ACCOUNT_ID = /^[a-f0-9]{32}$/
+const WORKER_NAME = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/
+const DOMAIN =
+  /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/
+
+export type CloudflarePublishAction = "stage" | "dry-run" | "deploy"
+
+export type CloudflareCommandRequest = Readonly<{
+  cwd: string
+  command: readonly string[]
+}>
+
+export type CloudflareCommandRunner = (
+  request: CloudflareCommandRequest,
+) => Promise<void>
+
+type PublishContext = Pick<
+  PluginCommandContext,
+  "pathsRoot" | "actionsRoot" | "projectRoot" | "stateRoot"
+>
+
+type ResolvedOptions = Readonly<{
+  accountId?: string
+  worker: string
+  origin: string
+  basePath?: string
+  domain?: string
+  routing?: CloudflarePluginOptions["routing"]
+}>
+
+type AssetInventory = Readonly<{
+  count: number
+  largest: Readonly<{ path: string; size: number }>
+}>
+
+function errorCode(error: unknown) {
+  return typeof error === "object" && error !== null && "code" in error
+    ? String(error.code)
+    : undefined
+}
+
+function resolveOptions(options: CloudflarePluginOptions): ResolvedOptions {
+  const accountId = options.accountId?.trim().toLowerCase()
+  if (accountId && !ACCOUNT_ID.test(accountId)) {
+    throw new Error(
+      "Cloudflare account id must be a 32-character hexadecimal value.",
+    )
+  }
+  if (!WORKER_NAME.test(options.worker)) {
+    throw new Error(
+      "Cloudflare worker must be 1-63 lowercase letters, numbers, or hyphens.",
+    )
+  }
+
+  let origin: URL
+  try {
+    origin = new URL(options.origin)
+  } catch {
+    throw new Error(`Invalid Cloudflare publication origin: ${options.origin}`)
+  }
+  if (
+    origin.protocol !== "https:" ||
+    origin.username ||
+    origin.password ||
+    origin.pathname !== "/" ||
+    origin.search ||
+    origin.hash
+  ) {
+    throw new Error(
+      "Cloudflare publication origin must be an HTTPS origin without credentials, path, query, or fragment.",
+    )
+  }
+
+  const domain = options.domain?.trim().toLowerCase()
+  if (domain && !DOMAIN.test(domain)) {
+    throw new Error(`Invalid Cloudflare custom domain: ${options.domain}`)
+  }
+  if (domain && origin.hostname !== domain) {
+    throw new Error(
+      `Cloudflare custom domain ${domain} must match publication origin ${origin.origin}.`,
+    )
+  }
+  if (options.routing && !domain) {
+    throw new Error("Cloudflare routing requires a domain.")
+  }
+  let routing = options.routing
+  if (routing?.type === "route") {
+    const zone = routing.zone.trim().toLowerCase()
+    if (
+      !DOMAIN.test(zone) ||
+      (domain !== zone && !domain?.endsWith(`.${zone}`))
+    ) {
+      throw new Error(
+        `Cloudflare route zone ${routing.zone} must contain domain ${domain}.`,
+      )
+    }
+    routing = Object.freeze({ type: "route", zone })
+  }
+  return Object.freeze({
+    ...(accountId ? { accountId } : {}),
+    worker: options.worker,
+    origin: origin.origin,
+    ...(options.basePath ? { basePath: options.basePath } : {}),
+    ...(domain ? { domain } : {}),
+    ...(routing ? { routing } : {}),
+  })
+}
+
+function representation(
+  value: PublicationRepresentation,
+): CloudflareRepresentation {
+  return Object.freeze({
+    artifact: value.artifact,
+    contentType: value.contentType,
+    ...(value.headers ? { headers: value.headers } : {}),
+  })
+}
+
+export function createCloudflareRoutes(
+  manifest: PublicationManifest,
+): CloudflareRoutes {
+  const routes: Record<string, CloudflareRoute> = {}
+  for (const route of manifest.routes) {
+    const defaults = route.representations.filter((item) => item.default)
+    if (defaults.length !== 1) {
+      throw new Error(
+        `Cloudflare route ${route.pathname} requires exactly one default representation.`,
+      )
+    }
+    const alternatives = route.representations.filter((item) => !item.default)
+    const markdown = alternatives.find(
+      (item) => item.type === "markdown" && item.accept === "text/markdown",
+    )
+    if (alternatives.some((item) => item !== markdown)) {
+      throw new Error(
+        `Cloudflare route ${route.pathname} has an unsupported representation.`,
+      )
+    }
+    routes[route.pathname] = Object.freeze({
+      default: representation(defaults[0]!),
+      ...(markdown
+        ? {
+            markdown: Object.freeze({
+              ...representation(markdown),
+              ...(markdown.alternatePath
+                ? { alternatePath: markdown.alternatePath }
+                : {}),
+            }),
+          }
+        : {}),
+    })
+  }
+  return Object.freeze(routes)
+}
+
+function renderWrangler(options: ResolvedOptions) {
+  return `${JSON.stringify(
+    {
+      $schema:
+        "https://raw.githubusercontent.com/cloudflare/workers-sdk/main/packages/wrangler/config-schema.json",
+      ...(options.accountId ? { account_id: options.accountId } : {}),
+      name: options.worker,
+      main: "./worker.ts",
+      compatibility_date: CLOUDFLARE_COMPATIBILITY_DATE,
+      workers_dev: true,
+      preview_urls: true,
+      assets: {
+        directory: "./site",
+        binding: "ASSETS",
+        run_worker_first: true,
+        html_handling: "none",
+        not_found_handling: "none",
+      },
+      ...(options.domain
+        ? {
+            routes:
+              options.routing?.type === "route"
+                ? [
+                    {
+                      pattern: `${options.domain}/*`,
+                      zone_name: options.routing.zone,
+                    },
+                  ]
+                : [{ pattern: options.domain, custom_domain: true }],
+          }
+        : {}),
+    },
+    null,
+    2,
+  )}\n`
+}
+
+function inspectAssets(manifest: PublicationManifest): AssetInventory {
+  const count = manifest.artifacts.length
+  if (count > MAX_ASSET_LIMIT) {
+    throw new Error(
+      `Cloudflare publication has ${count} assets; the platform maximum is ${MAX_ASSET_LIMIT}.`,
+    )
+  }
+
+  const largest = manifest.artifacts.reduce(
+    (current, artifact) =>
+      artifact.size > current.size
+        ? { path: artifact.path, size: artifact.size }
+        : current,
+    { path: "", size: 0 },
+  )
+  if (largest.size > MAX_ASSET_BYTES) {
+    throw new Error(
+      `Cloudflare asset exceeds 25 MiB: ${largest.path} (${largest.size} bytes).`,
+    )
+  }
+  return Object.freeze({ count, largest: Object.freeze(largest) })
+}
+
+function artifactPath(root: string, artifact: string) {
+  const path = resolve(root, artifact)
+  const local = relative(root, path)
+  if (
+    !artifact ||
+    isAbsolute(artifact) ||
+    local === ".." ||
+    local.startsWith(`..${sep}`) ||
+    isAbsolute(local)
+  ) {
+    throw new Error(`Invalid Cloudflare publication artifact: ${artifact}`)
+  }
+  return path
+}
+
+function cloudflareStore(root: string): PublicationStore {
+  return Object.freeze({
+    async put(artifact: string, body: Blob) {
+      const path = artifactPath(root, artifact)
+      await mkdir(dirname(path), { recursive: true })
+      await Bun.write(path, body)
+      return Object.freeze({
+        size: body.size,
+        read: async () => Bun.file(path),
+      })
+    },
+  })
+}
+
+async function assertManagedOrMissing(stageDir: string) {
+  try {
+    const info = await lstat(stageDir)
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+      throw new Error(
+        `Cloudflare publish stage is not a regular directory: ${stageDir}`,
+      )
+    }
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return
+    throw error
+  }
+
+  const receiptPath = join(stageDir, RECEIPT)
+  let receiptInfo
+  try {
+    receiptInfo = await lstat(receiptPath)
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") {
+      throw new Error(
+        `Refusing to replace unowned Cloudflare publish stage: ${stageDir}`,
+      )
+    }
+    throw error
+  }
+  if (!receiptInfo.isFile() || receiptInfo.isSymbolicLink()) {
+    throw new Error(`Invalid Cloudflare publish receipt: ${receiptPath}`)
+  }
+
+  let receipt: unknown
+  try {
+    receipt = JSON.parse(await readFile(receiptPath, "utf8"))
+  } catch {
+    throw new Error(`Invalid Cloudflare publish receipt: ${receiptPath}`)
+  }
+  if (
+    !receipt ||
+    typeof receipt !== "object" ||
+    (receipt as { type?: unknown }).type !== RECEIPT_TYPE ||
+    (receipt as { version?: unknown }).version !== RECEIPT_VERSION
+  ) {
+    throw new Error(`Invalid Cloudflare publish receipt: ${receiptPath}`)
+  }
+}
+
+async function replaceManagedStage(candidate: string, stageDir: string) {
+  await assertManagedOrMissing(stageDir)
+  const backup = `${candidate}.previous`
+  let moved = false
+  try {
+    await rename(stageDir, backup)
+    moved = true
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error
+  }
+  try {
+    await rename(candidate, stageDir)
+  } catch (error) {
+    if (moved) {
+      await rename(backup, stageDir)
+    }
+    throw error
+  }
+  if (moved) {
+    await rm(backup, { recursive: true, force: true }).catch(() => undefined)
+  }
+}
+
+async function writeAdapterFiles(
+  candidate: string,
+  manifest: PublicationManifest,
+  options: ResolvedOptions,
+  inventory: AssetInventory,
+) {
+  const routes = createCloudflareRoutes(manifest)
+  const runtime = await readFile(
+    new URL("./runtime.ts", import.meta.url),
+    "utf8",
+  )
+  await Promise.all([
+    writeFile(join(candidate, "routes.json"), `${JSON.stringify(routes)}\n`),
+    writeFile(join(candidate, "worker-runtime.ts"), runtime),
+    writeFile(
+      join(candidate, "worker.ts"),
+      [
+        'import { createCloudflareWorker } from "./worker-runtime.ts"',
+        'import routes from "./routes.json" with { type: "json" }',
+        "",
+        "export default createCloudflareWorker(routes)",
+        "",
+      ].join("\n"),
+    ),
+    writeFile(join(candidate, "wrangler.jsonc"), renderWrangler(options)),
+    writeFile(
+      join(candidate, RECEIPT),
+      `${JSON.stringify(
+        {
+          type: RECEIPT_TYPE,
+          version: RECEIPT_VERSION,
+          ...(options.accountId ? { accountId: options.accountId } : {}),
+          worker: options.worker,
+          origin: options.origin,
+          basePath: manifest.basePath,
+          ...(options.routing ? { routing: options.routing } : {}),
+          build: manifest.build,
+          routes: manifest.routes.length,
+          assets: inventory.count,
+          wrangler: PATHMX_WRANGLER_VERSION,
+          compatibilityDate: CLOUDFLARE_COMPATIBILITY_DATE,
+        },
+        null,
+        2,
+      )}\n`,
+    ),
+  ])
+}
+
+export const defaultCloudflareCommandRunner: CloudflareCommandRunner = async ({
+  cwd,
+  command,
+}) => {
+  const child = Bun.spawn([...command], {
+    cwd,
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  })
+  const exitCode = await child.exited
+  if (exitCode !== 0) {
+    throw new Error(
+      `Cloudflare command exited with status ${exitCode}: ${command.join(" ")}`,
+    )
+  }
+}
+
+function wranglerCommand(stageDir: string, ...args: string[]) {
+  return [
+    "bunx",
+    `wrangler@${PATHMX_WRANGLER_VERSION}`,
+    ...args,
+    "--config",
+    join(stageDir, "wrangler.jsonc"),
+  ]
+}
+
+async function runProviderAction(
+  action: CloudflarePublishAction,
+  context: PublishContext,
+  stageDir: string,
+  run: CloudflareCommandRunner,
+) {
+  if (action === "stage") return
+  if (action === "dry-run") {
+    await run({
+      cwd: context.projectRoot,
+      command: wranglerCommand(stageDir, "deploy", "--dry-run"),
+    })
+    return
+  }
+  await run({
+    cwd: context.projectRoot,
+    command: ["bunx", `wrangler@${PATHMX_WRANGLER_VERSION}`, "whoami"],
+  })
+  await run({
+    cwd: context.projectRoot,
+    command: wranglerCommand(stageDir, "deploy"),
+  })
+}
+
+export async function runCloudflarePublish(
+  context: PublishContext,
+  configured: CloudflarePluginOptions,
+  action: CloudflarePublishAction,
+  run: CloudflareCommandRunner = defaultCloudflareCommandRunner,
+) {
+  const options = resolveOptions(configured)
+  const stageDir = join(context.projectRoot, ".pathmx", "publish", "cloudflare")
+  await assertManagedOrMissing(stageDir)
+  const parent = dirname(stageDir)
+  await mkdir(parent, { recursive: true })
+  const candidate = await mkdtemp(join(parent, `.${basename(stageDir)}-`))
+  const siteDir = join(candidate, "site")
+  let app: Awaited<ReturnType<typeof PathMX>> | undefined
+
+  try {
+    app = await PathMX(context.pathsRoot, {
+      actionsRoot: context.actionsRoot,
+      stateRoot: context.stateRoot,
+      diagnostics: "throw",
+      runtime: { mode: "production", target: "static" },
+      log: new Log({ level: "error" }),
+    })
+    const exportingApp = app
+    await mkdir(siteDir)
+    const publication = await createPublication(exportingApp, {
+      origin: options.origin,
+      basePath: options.basePath,
+      store: cloudflareStore(siteDir),
+    })
+    await exportingApp.close()
+    app = undefined
+    const manifest = publication.manifest
+    const inventory = inspectAssets(manifest)
+    await writeAdapterFiles(candidate, manifest, options, inventory)
+    await replaceManagedStage(candidate, stageDir)
+    await runProviderAction(action, context, stageDir, run)
+    const warnings =
+      inventory.count > FREE_ASSET_LIMIT
+        ? [
+            `publication has ${inventory.count} static assets; Cloudflare's free plan permits ${FREE_ASSET_LIMIT}`,
+          ]
+        : []
+    return Object.freeze({
+      action,
+      stageDir,
+      siteDir: join(stageDir, "site"),
+      routeCount: manifest.routes.length,
+      assetCount: inventory.count,
+      largestAsset: inventory.largest,
+      warnings: Object.freeze(warnings),
+    })
+  } finally {
+    await app?.close().catch(() => undefined)
+    await rm(candidate, { recursive: true, force: true })
+  }
+}

package/runtime.ts

@@ -0,0 +1,154 @@
+export type CloudflareRepresentation = Readonly<{
+  artifact: string
+  contentType: string
+  headers?: Readonly<Record<string, string>>
+}>
+
+export type CloudflareRoute = Readonly<{
+  default: CloudflareRepresentation
+  markdown?: CloudflareRepresentation &
+    Readonly<{
+      alternatePath?: string
+    }>
+}>
+
+export type CloudflareRoutes = Readonly<Record<string, CloudflareRoute>>
+
+type AssetsBinding = Readonly<{
+  fetch(request: Request): Promise<Response>
+}>
+
+type CloudflareEnvironment = Readonly<{
+  ASSETS: AssetsBinding
+}>
+
+function acceptedQuality(header: string, target: string) {
+  const [targetType, targetSubtype] = target.split("/")
+  let quality = 0
+  let specificity = -1
+
+  for (const entry of header.split(",")) {
+    const [range = "", ...parameters] = entry.split(";")
+    const [type, subtype] = range.trim().toLowerCase().split("/")
+    if (
+      !type ||
+      !subtype ||
+      (type !== "*" && type !== targetType) ||
+      (subtype !== "*" && subtype !== targetSubtype)
+    ) {
+      continue
+    }
+
+    const candidateSpecificity =
+      (type === "*" ? 0 : 1) + (subtype === "*" ? 0 : 1)
+    const q = parameters
+      .map((parameter) => parameter.trim().match(/^q\s*=\s*(.+)$/i)?.[1])
+      .find((value) => value !== undefined)
+    const parsed = q === undefined ? 1 : Number(q)
+    const candidateQuality =
+      Number.isFinite(parsed) && parsed >= 0 && parsed <= 1 ? parsed : 0
+
+    if (
+      candidateSpecificity > specificity ||
+      (candidateSpecificity === specificity && candidateQuality > quality)
+    ) {
+      specificity = candidateSpecificity
+      quality = candidateQuality
+    }
+  }
+
+  return quality
+}
+
+function prefersMarkdown(request: Request) {
+  const accept = request.headers.get("Accept")
+  if (!accept) return false
+  const markdown = acceptedQuality(accept, "text/markdown")
+  return markdown > 0 && markdown > acceptedQuality(accept, "text/html")
+}
+
+function appendVary(headers: Headers, name: string) {
+  const values = (headers.get("Vary") ?? "")
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean)
+  if (!values.some((value) => value.toLowerCase() === name.toLowerCase())) {
+    values.push(name)
+  }
+  headers.set("Vary", values.join(", "))
+}
+
+function representationFor(route: CloudflareRoute, request: Request) {
+  return route.markdown && prefersMarkdown(request)
+    ? route.markdown
+    : route.default
+}
+
+function artifactRequest(request: Request, artifact: string) {
+  const url = new URL(request.url)
+  url.pathname = `/${artifact.replace(/^\/+/, "")}`
+  url.search = ""
+  return new Request(url, {
+    method: request.method,
+    headers: request.headers,
+  })
+}
+
+function routeResponse(
+  response: Response,
+  representation: CloudflareRepresentation,
+  route: CloudflareRoute,
+) {
+  if (response.status === 404) {
+    return new Response("Publication artifact unavailable", { status: 502 })
+  }
+  const output = new Response(response.body, response)
+  output.headers.set("Content-Type", representation.contentType)
+  for (const [name, value] of Object.entries(representation.headers ?? {})) {
+    output.headers.set(name, value)
+  }
+  if (route.markdown?.alternatePath && output.status < 400) {
+    appendVary(output.headers, "Accept")
+    const alternate = new URL(
+      route.markdown.alternatePath,
+      "https://pathmx.local",
+    ).pathname
+    output.headers.append(
+      "Link",
+      `<${alternate}>; rel="alternate"; type="text/markdown"`,
+    )
+  }
+  return output
+}
+
+/** Create the generated Worker's portable request handler. */
+export function createCloudflareWorker(routes: CloudflareRoutes) {
+  return Object.freeze({
+    async fetch(request: Request, env: CloudflareEnvironment) {
+      if (request.method !== "GET" && request.method !== "HEAD") {
+        return new Response("Method Not Allowed", {
+          status: 405,
+          headers: { Allow: "GET, HEAD" },
+        })
+      }
+
+      const url = new URL(request.url)
+      if (url.pathname.length > 1 && url.pathname.endsWith("/")) {
+        return new Response(null, {
+          status: 308,
+          headers: {
+            Location: url.pathname.replace(/\/+$/, "") + url.search,
+          },
+        })
+      }
+
+      const route = routes[url.pathname]
+      if (!route) return new Response("Not Found", { status: 404 })
+      const representation = representationFor(route, request)
+      const response = await env.ASSETS.fetch(
+        artifactRequest(request, representation.artifact),
+      )
+      return routeResponse(response, representation, route)
+    },
+  })
+}