make-cloudflare 0.1.0__tar.gz

make_cloudflare-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.env
+
+# wrangler caches its Pages upload state here (site/ is deployed by direct upload).
+.wrangler/
+
+# The VS Code extension in editors/vscode: `dist/` is above, and these two are what
+# building a .vsix leaves behind. `npm install` is never run there -- the extension has
+# no runtime dependency and both CLIs come from `npx --yes` -- so node_modules/ is
+# listed to catch the day somebody tries.
+node_modules/
+*.vsix

make_cloudflare-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: make-cloudflare
+Version: 0.1.0
+Summary: Cloudflare Pages direct upload for mkrun -- deploy a built site with no Node and no wrangler.
+Project-URL: Homepage, https://make.optersoft.com
+Author-email: "Optersoft, S.L." <david@optersoft.com>
+License-Expression: MIT OR Apache-2.0
+Keywords: cloudflare,deploy,direct upload,mk,mkrun,pages
+Requires-Python: >=3.11
+Requires-Dist: blake3>=1.0
+Requires-Dist: mkrun>=0.4.1
+Description-Content-Type: text/markdown
+
+# make-cloudflare
+
+Cloudflare Pages **direct upload** for [`mkrun`](https://pypi.org/project/mkrun/), in
+Python: publish a built directory with no Node on the machine and no `wrangler`
+in the pipeline.
+
+```python
+# Makefile.py in a consuming repo
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["mkrun>=0.4", "make-cloudflare>=0.1"]
+# ///
+from make_cloudflare import cloudflare  # importing is what registers the group
+```
+
+```console
+$ mk cloudflare.deploy site/dist --project mkrun     # production (branch main)
+$ mk cloudflare.deploy site/dist --branch try        # a preview, on its own URL
+$ mk cloudflare.projects                             # what the account has
+$ mk cloudflare.deployments --limit 5                # one project's recent ones
+$ mk -n cloudflare.deploy site/dist                  # the plan; nothing is sent
+```
+
+Credentials are the two variables wrangler already reads, so a repository that
+deploys from CI needs no new secret: `CLOUDFLARE_ACCOUNT_ID` and
+`CLOUDFLARE_API_TOKEN` (a token with **Cloudflare Pages: Edit**). The token's
+name ends in `TOKEN`, so mkrun treats it as a credential — it is withheld from
+the environment until a task asks for it, redacted in everything printed, and
+readable from the encrypted store. The project can come from `--project` or from
+`CLOUDFLARE_PAGES_PROJECT` in the repo's env layer.
+
+## Why this exists
+
+`wrangler pages deploy` is four HTTPS calls and a hash. Reaching them through
+`npx` costs a Node toolchain in repositories that otherwise have none — a Rust
+one, a [frontage](https://github.com/optersoft/frontage) one — and a
+`node_modules` in the deploy image of every one of them.
+
+```
+POST /accounts/<acct>/pages/projects/<p>/upload-token   -> a short-lived JWT
+POST /pages/assets/check-missing                        -> what is not stored yet
+POST /pages/assets/upload                               -> the files, batched
+POST /pages/assets/upsert-hashes
+POST /accounts/<acct>/pages/projects/<p>/deployments    -> the manifest
+```
+
+Three things make a naive port wrong, and all three fail **silently** — every
+call returns 200 and the site serves the old bytes, or none:
+
+- **The hash is BLAKE3 of a strange input**: the base64 *text* of the contents
+  with the extension (no dot) appended, first 32 hex characters. Not of the
+  bytes, and not SHA-256. `tests/test_pages.py` locks it with a golden value.
+- **`_headers`, `_redirects` and `_routes.json` are not assets.** They are
+  fields on the deployment. Walk them in as ordinary files and the deploy
+  reports success while the site's CSP stops applying.
+- **`check-missing`, `upload` and `upsert-hashes` take the JWT, not the account
+  token, and carry no `/accounts/<id>` prefix** — the JWT already names the
+  account.
+
+## What it does not do
+
+**Pages Functions.** A directory holding `_worker.js` or `functions/` is
+refused by name rather than half-deployed: bundling a Worker is a build step,
+not an upload, and wrangler should keep doing it.
+
+**Steps 2 and 3 are undocumented.** They exist because wrangler uses them, and
+Cloudflare can change them without a changelog; the documented `deployments`
+endpoint alone cannot upload a file. That is the real cost of dropping
+wrangler, and it is the reason this is a small module with a golden test rather
+than a wrapper nobody reads.
+
+Nothing here is specific to any owner or account. The group name is
+`cloudflare`, and it merges with a repo's own `cloudflare.*` tasks — groups are
+namespaces — so only a same-named task collides; this package claims `deploy`,
+`projects` and `deployments`, nothing else. `blake3` is the one dependency, and
+it lives here rather than in the runner so `mkrun` itself stays dependency-free.

make_cloudflare-0.1.0/README.md

@@ -0,0 +1,76 @@
+# make-cloudflare
+
+Cloudflare Pages **direct upload** for [`mkrun`](https://pypi.org/project/mkrun/), in
+Python: publish a built directory with no Node on the machine and no `wrangler`
+in the pipeline.
+
+```python
+# Makefile.py in a consuming repo
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["mkrun>=0.4", "make-cloudflare>=0.1"]
+# ///
+from make_cloudflare import cloudflare  # importing is what registers the group
+```
+
+```console
+$ mk cloudflare.deploy site/dist --project mkrun     # production (branch main)
+$ mk cloudflare.deploy site/dist --branch try        # a preview, on its own URL
+$ mk cloudflare.projects                             # what the account has
+$ mk cloudflare.deployments --limit 5                # one project's recent ones
+$ mk -n cloudflare.deploy site/dist                  # the plan; nothing is sent
+```
+
+Credentials are the two variables wrangler already reads, so a repository that
+deploys from CI needs no new secret: `CLOUDFLARE_ACCOUNT_ID` and
+`CLOUDFLARE_API_TOKEN` (a token with **Cloudflare Pages: Edit**). The token's
+name ends in `TOKEN`, so mkrun treats it as a credential — it is withheld from
+the environment until a task asks for it, redacted in everything printed, and
+readable from the encrypted store. The project can come from `--project` or from
+`CLOUDFLARE_PAGES_PROJECT` in the repo's env layer.
+
+## Why this exists
+
+`wrangler pages deploy` is four HTTPS calls and a hash. Reaching them through
+`npx` costs a Node toolchain in repositories that otherwise have none — a Rust
+one, a [frontage](https://github.com/optersoft/frontage) one — and a
+`node_modules` in the deploy image of every one of them.
+
+```
+POST /accounts/<acct>/pages/projects/<p>/upload-token   -> a short-lived JWT
+POST /pages/assets/check-missing                        -> what is not stored yet
+POST /pages/assets/upload                               -> the files, batched
+POST /pages/assets/upsert-hashes
+POST /accounts/<acct>/pages/projects/<p>/deployments    -> the manifest
+```
+
+Three things make a naive port wrong, and all three fail **silently** — every
+call returns 200 and the site serves the old bytes, or none:
+
+- **The hash is BLAKE3 of a strange input**: the base64 *text* of the contents
+  with the extension (no dot) appended, first 32 hex characters. Not of the
+  bytes, and not SHA-256. `tests/test_pages.py` locks it with a golden value.
+- **`_headers`, `_redirects` and `_routes.json` are not assets.** They are
+  fields on the deployment. Walk them in as ordinary files and the deploy
+  reports success while the site's CSP stops applying.
+- **`check-missing`, `upload` and `upsert-hashes` take the JWT, not the account
+  token, and carry no `/accounts/<id>` prefix** — the JWT already names the
+  account.
+
+## What it does not do
+
+**Pages Functions.** A directory holding `_worker.js` or `functions/` is
+refused by name rather than half-deployed: bundling a Worker is a build step,
+not an upload, and wrangler should keep doing it.
+
+**Steps 2 and 3 are undocumented.** They exist because wrangler uses them, and
+Cloudflare can change them without a changelog; the documented `deployments`
+endpoint alone cannot upload a file. That is the real cost of dropping
+wrangler, and it is the reason this is a small module with a golden test rather
+than a wrapper nobody reads.
+
+Nothing here is specific to any owner or account. The group name is
+`cloudflare`, and it merges with a repo's own `cloudflare.*` tasks — groups are
+namespaces — so only a same-named task collides; this package claims `deploy`,
+`projects` and `deployments`, nothing else. `blake3` is the one dependency, and
+it lives here rather than in the runner so `mkrun` itself stays dependency-free.

make_cloudflare-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "make-cloudflare"
+version = "0.1.0"
+description = "Cloudflare Pages direct upload for mkrun -- deploy a built site with no Node and no wrangler."
+readme = "README.md"
+requires-python = ">=3.11"
+# Same dual licence as mkrun, for the same reason: this member is generic and
+# publishable. The licence texts live at the repository root; a built wheel
+# carries the SPDX expression, which is what PEP 639 asks for.
+license = "MIT OR Apache-2.0"
+authors = [{ name = "Optersoft, S.L.", email = "david@optersoft.com" }]
+keywords = ["cloudflare", "pages", "deploy", "direct upload", "mk", "mkrun"]
+# blake3 is not optional and not replaceable: Cloudflare's asset store is keyed
+# on it, so a deploy that hashes with anything else uploads files nothing will
+# ever ask for. It lives here rather than in the runner precisely so `mkrun`
+# itself stays dependency-free -- see this repo's CLAUDE.md, rule 4.
+dependencies = ["mkrun>=0.4.1", "blake3>=1.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/make_cloudflare"]
+
+[project.urls]
+Homepage = "https://make.optersoft.com"
+
+# The runner is the other half of this repository, so resolve it from the
+# working tree instead of PyPI, exactly as rust/ does: a change to `make.http`
+# is testable against a real consumer in the same commit that makes it.
+[tool.uv.sources]
+mkrun = { workspace = true }
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+# No [tool.ruff] here on purpose: every member shares the root config, so they
+# cannot drift apart by an isort option.

make_cloudflare-0.1.0/src/make_cloudflare/__init__.py

@@ -0,0 +1,35 @@
+"""Cloudflare tasks for mkrun -- the `cloudflare` group.
+
+Today it is Pages direct upload: `cloudflare.deploy` publishes a built
+directory, `cloudflare.projects` lists what the account has, and
+`cloudflare.deployments` shows a project's recent ones. No Node, no wrangler --
+four HTTPS calls and a BLAKE3 hash.
+
+Importing is what registers it:
+
+    # Makefile.py
+    from make_cloudflare import cloudflare
+
+The group merges with a repo's own `cloudflare.*` tasks -- groups are
+namespaces, and this package claims only the three names above.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["cloudflare", "pages"]
+
+
+def __getattr__(name: str):
+    """Import on first access, keeping module scope import-free.
+
+    The same shape as the other task packages: startup latency is a feature of
+    the tool this plugs into, so nothing heavy -- `blake3`, here -- may load
+    before it is asked for.
+    """
+    if name in __all__:
+        import importlib
+
+        return importlib.import_module(f".{name}", __name__)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

make_cloudflare-0.1.0/src/make_cloudflare/cloudflare.py

@@ -0,0 +1,52 @@
+"""The `cloudflare` group: deploy to Pages, and see what is there.
+
+Nothing here knows whose account it runs in. The project name comes from the
+task line or from `CLOUDFLARE_PAGES_PROJECT` in the repo's env layer, and the
+credentials come from `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_API_TOKEN` -- the
+same two names wrangler reads, so a repository that already deploys through CI
+needs no new secret.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+from make import arg, note, step, task
+
+from . import pages
+
+
+@task(group="cloudflare", name="deploy", dangerous=True, secrets=["CLOUDFLARE_API_TOKEN"])
+def deploy(
+    directory: str = "dist",
+    *,
+    project: str | None = None,
+    branch: Annotated[str, arg(help="the Pages branch; the production one publishes live")] = "main",
+) -> None:
+    """Publish a built directory to Cloudflare Pages by direct upload.
+
+    No Node and no wrangler: four HTTPS calls. `--branch` is what decides
+    production -- the project's production branch goes live, every other name
+    lands as a preview on its own URL.
+    """
+    url = pages.deploy(Path(directory), project=pages.project_name(project), branch=branch)
+    note(f"deployed -- {url}")
+
+
+@task(group="cloudflare", name="projects", secrets=["CLOUDFLARE_API_TOKEN"])
+def projects() -> None:
+    """List the account's Pages projects, and where each one deploys from."""
+    for project in pages.projects():
+        source = (project.get("source") or {}).get("type") or "direct upload"
+        domains = ", ".join(project.get("domains") or []) or "--"
+        step(f"{project.get('name', '?')}  [{source}]  {domains}")
+
+
+@task(group="cloudflare", name="deployments", secrets=["CLOUDFLARE_API_TOKEN"])
+def deployments(project: str | None = None, *, limit: int = 10) -> None:
+    """The most recent deployments of one project, newest first."""
+    for entry in pages.deployments(pages.project_name(project))[:limit]:
+        stage = (entry.get("latest_stage") or {}).get("status", "?")
+        env_name = entry.get("environment", "?")
+        step(f"{entry.get('created_on', '?')}  {env_name:<10} {stage:<10} {entry.get('url', '')}")

make_cloudflare-0.1.0/src/make_cloudflare/pages.py

@@ -0,0 +1,422 @@
+"""Cloudflare Pages direct upload, in Python.
+
+`wrangler pages deploy` is four HTTPS calls and a hash. This is those four
+calls, so a repository with no Node -- a Rust one, a frontage one -- can publish
+a built directory without installing a JavaScript toolchain to do it.
+
+    from make_cloudflare import pages
+
+    pages.deploy("site/dist", project="mkrun")            # production
+    pages.deploy("site/dist", project="mkrun", branch="x")  # a preview
+
+The flow, and the three things a naive port gets wrong:
+
+1. `POST /accounts/<acct>/pages/projects/<p>/upload-token` -> a short-lived JWT.
+2. `POST /pages/assets/check-missing` (JWT) -> the hashes not already stored.
+   Note the missing `/accounts/<acct>` prefix on this call and the next: the
+   JWT carries the account, and adding the prefix 404s.
+3. `POST /pages/assets/upload` (JWT), then `upsert-hashes` -- in batches.
+4. `POST /accounts/<acct>/pages/projects/<p>/deployments` -> the manifest.
+
+**The hash is BLAKE3 of a strange input**: the base64 *text* of the contents
+with the extension (no dot) appended, first 32 hex characters. Not of the bytes,
+not SHA-256. Get it wrong and every call still succeeds while the deployment
+serves nothing.
+
+**`_headers`, `_redirects` and `_routes.json` are not assets.** They are form
+fields on the deployment, and a port that walks them in as ordinary files
+reports success while the site's CSP quietly stops applying.
+
+**Steps 2 and 3 are undocumented.** They exist because wrangler uses them;
+Cloudflare can change them without a changelog. The documented `deployments`
+endpoint alone cannot upload a file.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import mimetypes
+import os
+import secrets as _random
+from collections.abc import Iterable, Iterator, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from make import env, http, note, step
+from make.context import mark_sensitive
+from make.errors import ConfigError, MakeError
+
+__all__ = [
+    "Asset",
+    "collect",
+    "deploy",
+    "deployments",
+    "file_hash",
+    "manifest_of",
+    "project_name",
+    "projects",
+]
+
+API = "https://api.cloudflare.com/client/v4"
+
+#: Pages' own limits. Both are refused by the API anyway; refusing here names
+#: the offending file instead of failing the batch that happened to carry it.
+MAX_ASSET_SIZE = 25 * 1024 * 1024
+MAX_ASSET_COUNT = 20_000
+
+#: One upload request. Cloudflare accepts more; these keep a single request
+#: small enough to retry cheaply on a bad connection, which matters more than
+#: shaving round trips off a deploy that happens by hand.
+BATCH_FILES = 100
+BATCH_BYTES = 10 * 1024 * 1024
+
+#: Handled by Pages itself, as fields on the deployment -- never as assets.
+SPECIAL_FILES = ("_headers", "_redirects", "_routes.json")
+
+#: Never uploaded. `_worker.js` and `functions/` are Pages Functions, which this
+#: module does not build: a directory that has them is a Functions project and
+#: belongs on wrangler until someone needs it here.
+SKIP_NAMES = {".DS_Store", "Thumbs.db", ".gitkeep", *SPECIAL_FILES}
+SKIP_DIRS = {".git", "node_modules", "__pycache__", ".wrangler"}
+FUNCTIONS = ("_worker.js", "_worker.js.map", "_worker.bundle", "functions")
+
+
+@dataclass(frozen=True)
+class Asset:
+    """One file, as the manifest and the upload endpoint each want it."""
+
+    key: str
+    """Manifest path, with the leading slash Cloudflare requires."""
+    file: Path
+    hash: str
+    size: int
+    content_type: str
+
+
+# -- hashing ---------------------------------------------------------------
+
+
+def file_hash(data: bytes, extension: str = "") -> str:
+    """Cloudflare's asset key: `blake3(base64(data) + ext)` , first 32 hex chars.
+
+    `extension` is the suffix without its dot, and the empty string for a file
+    that has none. The base64 text is hashed, not the bytes -- that is not a
+    mistake in the reading of wrangler, it is what wrangler does, and the store
+    is keyed on the result.
+    """
+    from blake3 import blake3
+
+    payload = base64.b64encode(data) + extension.encode()
+    return blake3(payload).hexdigest()[:32]
+
+
+# -- walking a built directory --------------------------------------------
+
+
+def _walk(directory: Path) -> Iterator[Path]:
+    for parent, dirs, names in os.walk(directory):
+        dirs[:] = sorted(d for d in dirs if d not in SKIP_DIRS)
+        for name in sorted(names):
+            if name not in SKIP_NAMES:
+                yield Path(parent) / name
+
+
+def collect(directory: str | Path) -> tuple[list[Asset], dict[str, str]]:
+    """Every uploadable file under `directory`, plus the special files' contents.
+
+    Returns `(assets, specials)`, where `specials` maps `_headers` /
+    `_redirects` / `_routes.json` to their text. They are deliberately not
+    assets: Pages takes them as fields on the deployment.
+    """
+    root = Path(directory).resolve()
+    if not root.is_dir():
+        raise MakeError(f"{root} is not a directory", hint="build the site first")
+
+    for name in FUNCTIONS:
+        if (root / name).exists():
+            raise MakeError(
+                f"{root / name} is a Pages Functions project",
+                hint="this module uploads static assets only -- deploy it with wrangler",
+            )
+
+    assets: list[Asset] = []
+    for file in _walk(root):
+        data = file.read_bytes()
+        if len(data) > MAX_ASSET_SIZE:
+            raise MakeError(
+                f"{file.relative_to(root)} is {len(data) / 1_048_576:.1f} MiB",
+                hint=f"Cloudflare Pages refuses any asset over {MAX_ASSET_SIZE // 1_048_576} MiB",
+            )
+        guessed, _ = mimetypes.guess_type(file.name)
+        assets.append(
+            Asset(
+                key="/" + file.relative_to(root).as_posix(),
+                file=file,
+                hash=file_hash(data, file.suffix.lstrip(".")),
+                size=len(data),
+                content_type=guessed or "application/octet-stream",
+            )
+        )
+
+    if not assets:
+        raise MakeError(f"{root} holds no files to upload")
+    if len(assets) > MAX_ASSET_COUNT:
+        raise MakeError(
+            f"{len(assets)} files under {root}",
+            hint=f"Cloudflare Pages takes at most {MAX_ASSET_COUNT} per deployment",
+        )
+
+    specials = {name: (root / name).read_text() for name in SPECIAL_FILES if (root / name).is_file()}
+    return assets, specials
+
+
+def manifest_of(assets: Iterable[Asset]) -> dict[str, str]:
+    """The deployment manifest: `/path` -> hash."""
+    return {asset.key: asset.hash for asset in assets}
+
+
+# -- the API ---------------------------------------------------------------
+
+
+def _credentials(account: str | None, token: str | None) -> tuple[str, str]:
+    # The layers first, as every task package that needs a credential does: without
+    # this, `require` sees only the process environment, and a machine whose
+    # `~/.make/secrets.env` already holds these two is told to set what it has set.
+    # The secret itself is still withheld from child processes until asked for --
+    # `layered()` holds sensitive values back by design.
+    if account is None or token is None:
+        env.layered()
+    account = account or env.require(
+        "CLOUDFLARE_ACCOUNT_ID", hint="the account id from any zone's overview page"
+    )
+    token = token or env.require(
+        "CLOUDFLARE_API_TOKEN",
+        hint="an API token with the `Cloudflare Pages: Edit` permission, "
+        "from https://dash.cloudflare.com/profile/api-tokens",
+    )
+    mark_sensitive(token)
+    return account, token
+
+
+def _call(
+    method: str,
+    url: str,
+    *,
+    auth: str,
+    body: bytes | None = None,
+    content_type: str | None = None,
+    timeout: float = 120.0,
+) -> Any:
+    """One API call, returning `result` -- a dict or a list, as the endpoint says.
+
+    Under `--dry-run` nothing is sent and this returns `None`, which every
+    caller reads as "unknown". A dry run therefore prints the whole plan
+    instead of stopping at the first call whose answer it needed.
+    """
+    headers = {"Authorization": f"Bearer {auth}"}
+    if content_type:
+        headers["Content-Type"] = content_type
+    answer = http.request(url, method=method, headers=headers, data=body, timeout=timeout)
+    if answer.skipped:
+        return None
+    if answer.status == 0:
+        raise MakeError(f"{method} {url}: no answer from Cloudflare")
+    try:
+        payload = json.loads(answer.body)
+    except ValueError:
+        payload = {}
+    if not answer.ok or not payload.get("success", False):
+        detail = "; ".join(f"{e.get('code', '?')}: {e.get('message', '')}" for e in payload.get("errors", []))
+        # Cloudflare's own text goes in the message, not the hint: a 403 saying
+        # which permission the token lacks is the thing to read, and a hint is
+        # printed as advice rather than as the failure.
+        raise MakeError(
+            f"{method} {url} -> {answer.status}" + (f": {detail}" if detail else ""),
+            hint=None if detail else (answer.body[:300] or None),
+        )
+    return payload.get("result")
+
+
+def _json_call(method: str, url: str, *, auth: str, payload: object, **kwargs: Any) -> Any:
+    return _call(
+        method, url, auth=auth, body=json.dumps(payload).encode(), content_type="application/json", **kwargs
+    )
+
+
+def _multipart(fields: Mapping[str, str], files: Mapping[str, str] | None = None) -> tuple[bytes, str]:
+    """Encode a deployment's form: plain fields, then the special files as file parts.
+
+    ⚠ `_headers` and `_redirects` must be FILE parts (a `filename=` on the part),
+    the way wrangler appends them: `formData.append("_headers", new File(...))`.
+    Sent as plain text fields, the deployment succeeds and Pages silently ignores
+    them -- every header rule, the CSP included, simply stops applying.
+    """
+    boundary = "----mk" + _random.token_hex(16)
+    chunks: list[bytes] = []
+    for name, value in fields.items():
+        chunks.append(f"--{boundary}\r\n".encode())
+        chunks.append(f'Content-Disposition: form-data; name="{name}"\r\n\r\n'.encode())
+        chunks.append(value.encode())
+        chunks.append(b"\r\n")
+    for name, value in (files or {}).items():
+        chunks.append(f"--{boundary}\r\n".encode())
+        chunks.append(f'Content-Disposition: form-data; name="{name}"; filename="{name}"\r\n'.encode())
+        chunks.append(b"Content-Type: application/octet-stream\r\n\r\n")
+        chunks.append(value.encode())
+        chunks.append(b"\r\n")
+    chunks.append(f"--{boundary}--\r\n".encode())
+    return b"".join(chunks), f"multipart/form-data; boundary={boundary}"
+
+
+def _batches(assets: list[Asset]) -> Iterator[list[Asset]]:
+    batch: list[Asset] = []
+    total = 0
+    for asset in assets:
+        encoded = asset.size * 4 // 3
+        if batch and (len(batch) >= BATCH_FILES or total + encoded > BATCH_BYTES):
+            yield batch
+            batch, total = [], 0
+        batch.append(asset)
+        total += encoded
+    if batch:
+        yield batch
+
+
+# -- the tasks' behaviour --------------------------------------------------
+
+
+def deploy(
+    directory: str | Path,
+    *,
+    project: str,
+    branch: str = "main",
+    account: str | None = None,
+    token: str | None = None,
+) -> str:
+    """Publish a built directory and return the deployment's URL.
+
+    `branch` is what decides production: Pages treats the project's production
+    branch (`main` for every project here) as the live deployment and every
+    other name as a preview on its own URL. There is no `--production` flag to
+    forget; there is a branch name to get right.
+    """
+    account, token = _credentials(account, token)
+    assets, specials = collect(directory)
+    plural = "" if len(assets) == 1 else "s"
+    step(f"{len(assets)} file{plural}, {sum(a.size for a in assets) / 1024:.0f} KiB -> {project} ({branch})")
+
+    granted = _call("GET", f"{API}/accounts/{account}/pages/projects/{project}/upload-token", auth=token)
+    jwt = str(granted.get("jwt", "")) if isinstance(granted, dict) else ""
+    if jwt:
+        mark_sensitive(jwt)
+    # The JWT is what the two asset endpoints want; the account token is not
+    # accepted there. Falling back to it keeps a dry run legible rather than
+    # correct -- there is nothing to authenticate when nothing is sent.
+    upload_auth = jwt or token
+
+    # `check-missing` answers with the hashes Cloudflare does NOT already hold:
+    # a repeat deploy of an unchanged site uploads nothing. `None` is a dry run,
+    # where the honest plan is "all of them".
+    missing = _json_call(
+        "POST",
+        f"{API}/pages/assets/check-missing",
+        auth=upload_auth,
+        payload={"hashes": [a.hash for a in assets]},
+    )
+    pending = assets if missing is None else [a for a in assets if a.hash in set(missing)]
+
+    if pending:
+        for batch in _batches(pending):
+            _json_call(
+                "POST",
+                f"{API}/pages/assets/upload",
+                auth=upload_auth,
+                payload=[
+                    {
+                        "key": asset.hash,
+                        "value": base64.b64encode(asset.file.read_bytes()).decode(),
+                        "metadata": {"contentType": asset.content_type},
+                        "base64": True,
+                    }
+                    for asset in batch
+                ],
+            )
+        if len(pending) == len(assets):
+            note(f"uploading all {len(assets)} file{plural}")
+        else:
+            note(f"uploading {len(pending)} of {len(assets)}; Cloudflare already holds the rest")
+    else:
+        note("every file was already stored; only the manifest changes")
+
+    _json_call(
+        "POST",
+        f"{API}/pages/assets/upsert-hashes",
+        auth=upload_auth,
+        payload={"hashes": [a.hash for a in assets]},
+    )
+
+    fields = {"manifest": json.dumps(manifest_of(assets)), "branch": branch}
+    body, content_type = _multipart(fields, specials)
+    created = _call(
+        "POST",
+        f"{API}/accounts/{account}/pages/projects/{project}/deployments",
+        auth=token,
+        body=body,
+        content_type=content_type,
+    )
+    if specials:
+        note("as deployment files, not assets: " + ", ".join(sorted(specials)))
+    url = created.get("url") if isinstance(created, dict) else None
+    return str(url or f"https://{branch}.{project}.pages.dev")
+
+
+def projects(*, account: str | None = None, token: str | None = None) -> list[dict]:
+    """Every Pages project on the account."""
+    account, token = _credentials(account, token)
+    result = _call("GET", f"{API}/accounts/{account}/pages/projects", auth=token)
+    return list(result) if isinstance(result, list) else []
+
+
+def create_project(
+    project: str, *, production_branch: str = "main", account: str | None = None, token: str | None = None
+) -> dict:
+    """The project named `project`, created for direct upload if the account has none.
+
+    Idempotent: an existing project is returned as it is, whatever its branch or source.
+    Its `subdomain` is where it serves -- `<project>.pages.dev` only if no other account
+    holds that name; Cloudflare appends a suffix otherwise, so read it, never assume it.
+    """
+    account, token = _credentials(account, token)
+    for found in _call("GET", f"{API}/accounts/{account}/pages/projects", auth=token) or []:
+        if found.get("name") == project:
+            return found
+    step(f"creating the Pages project {project} (production branch {production_branch})")
+    created = _json_call(
+        "POST",
+        f"{API}/accounts/{account}/pages/projects",
+        auth=token,
+        payload={"name": project, "production_branch": production_branch},
+    )
+    return created if isinstance(created, dict) else {"name": project}
+
+
+def deployments(project: str, *, account: str | None = None, token: str | None = None) -> list[dict]:
+    """A project's deployments, newest first."""
+    account, token = _credentials(account, token)
+    result = _call("GET", f"{API}/accounts/{account}/pages/projects/{project}/deployments", auth=token)
+    return list(result) if isinstance(result, list) else []
+
+
+def project_name(project: str | None) -> str:
+    """The project to act on: the one given, else the repo's env layer."""
+    if project:
+        return project
+    found = env.get("CLOUDFLARE_PAGES_PROJECT")
+    if found:
+        return found
+    raise ConfigError(
+        "no Pages project given",
+        hint="pass --project, or set CLOUDFLARE_PAGES_PROJECT in this repo's env layer",
+    )

make_cloudflare-0.1.0/tests/conftest.py

@@ -0,0 +1,19 @@
+"""Test setup for make-cloudflare.
+
+Importing the group is what registers it, and a module is imported once per
+process -- so the registry is populated here, once, rather than relying on
+whichever test file happened to import first.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from make.tasks import registry
+
+
+@pytest.fixture(scope="session", autouse=True)
+def register_groups():
+    from make_cloudflare import cloudflare  # noqa: F401
+
+    registry.finalize()

make_cloudflare-0.1.0/tests/test_pages.py

@@ -0,0 +1,284 @@
+"""make-cloudflare: the hash is the contract, and the special files are not assets."""
+
+from __future__ import annotations
+
+import base64
+import json
+
+import pytest
+
+from make.errors import MakeError
+from make.testing import context
+from make_cloudflare import pages
+
+
+def build(root, files: dict[str, str]):
+    for name, text in files.items():
+        target = root / name
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(text)
+    return root
+
+
+class FakeHTTP:
+    """Stands in for `make.http.request`, answering each endpoint in turn."""
+
+    def __init__(self, *, missing: list[str] | None = None):
+        self.calls: list[tuple[str, str, dict]] = []
+        self.missing = missing
+
+    def __call__(self, url, *, method="GET", headers=None, data=None, **kwargs):
+        self.calls.append((method, url, {"headers": headers or {}, "data": data}))
+        if url.endswith("/upload-token"):
+            result = {"jwt": "jot"}
+        elif url.endswith("/check-missing"):
+            sent = json.loads(data)["hashes"]
+            result = sent if self.missing is None else self.missing
+        elif url.endswith("/deployments"):
+            result = {"url": "https://abc123.example.pages.dev"}
+        else:
+            result = {}
+        return pages.http.Response(
+            url=url, status=200, body=json.dumps({"success": True, "errors": [], "result": result})
+        )
+
+    def urls(self, fragment: str) -> list[str]:
+        return [url for _, url, _ in self.calls if fragment in url]
+
+    def body(self, fragment: str):
+        return next(call["data"] for _, url, call in self.calls if fragment in url)
+
+    def auth(self, fragment: str) -> str:
+        call = next(c for _, url, c in self.calls if fragment in url)
+        return call["headers"]["Authorization"]
+
+
+def deploy(monkeypatch, root, fake, **kwargs):
+    monkeypatch.setattr(pages.http, "request", fake)
+    return pages.deploy(root, project="demo", account="acct", token="tok", **kwargs)
+
+
+# -- the hash --------------------------------------------------------------
+
+
+def test_the_hash_is_blake3_of_the_base64_text_plus_the_extension():
+    # Locked deliberately. Cloudflare's asset store is keyed on this value, so
+    # a "simplification" to hashing the raw bytes -- the obvious reading -- would
+    # upload files that nothing ever asks for, with every call still returning
+    # 200. If this test fails, the deploy is broken, not the test.
+    assert pages.file_hash(b"hello", "html") == "a2b82584e50075886b08927390f2f573"
+    assert len(pages.file_hash(b"hello", "html")) == 32
+
+
+def test_the_extension_is_part_of_the_hash():
+    assert pages.file_hash(b"same", "html") != pages.file_hash(b"same", "css")
+    assert pages.file_hash(b"same", "") != pages.file_hash(b"same", "html")
+
+
+# -- walking the directory -------------------------------------------------
+
+
+def test_collect_keys_with_a_leading_slash_and_skips_the_noise(tmp_path):
+    build(
+        tmp_path,
+        {
+            "index.html": "<h1>hi</h1>",
+            "assets/app.css": "body{}",
+            ".DS_Store": "junk",
+            "node_modules/dep/index.js": "junk",
+        },
+    )
+    assets, specials = pages.collect(tmp_path)
+    assert pages.manifest_of(assets).keys() == {"/index.html", "/assets/app.css"}
+    assert specials == {}
+
+
+def test_the_special_files_are_fields_not_assets(tmp_path):
+    build(
+        tmp_path,
+        {"index.html": "x", "_headers": "/*\n  X-Frame-Options: DENY\n", "_redirects": "/a /b 301\n"},
+    )
+    assets, specials = pages.collect(tmp_path)
+    assert pages.manifest_of(assets).keys() == {"/index.html"}
+    assert set(specials) == {"_headers", "_redirects"}
+
+
+def test_a_functions_project_is_refused(tmp_path):
+    build(tmp_path, {"index.html": "x", "_worker.js": "export default {}"})
+    with pytest.raises(MakeError, match="Functions"):
+        pages.collect(tmp_path)
+
+
+def test_an_oversized_asset_is_named(tmp_path):
+    (tmp_path / "big.bin").write_bytes(b"x" * (pages.MAX_ASSET_SIZE + 1))
+    with pytest.raises(MakeError, match=r"big\.bin"):
+        pages.collect(tmp_path)
+
+
+def test_an_empty_directory_is_refused(tmp_path):
+    with pytest.raises(MakeError, match="no files"):
+        pages.collect(tmp_path)
+
+
+# -- the four calls --------------------------------------------------------
+
+
+def test_deploy_makes_the_four_calls_in_order(monkeypatch, tmp_path):
+    build(tmp_path, {"index.html": "x"})
+    fake = FakeHTTP()
+    url = deploy(monkeypatch, tmp_path, fake)
+    assert [u.rsplit("/", 1)[-1] for _, u, _ in fake.calls] == [
+        "upload-token",
+        "check-missing",
+        "upload",
+        "upsert-hashes",
+        "deployments",
+    ]
+    assert url == "https://abc123.example.pages.dev"
+
+
+def test_the_asset_endpoints_use_the_jwt_and_omit_the_account(monkeypatch, tmp_path):
+    build(tmp_path, {"index.html": "x"})
+    fake = FakeHTTP()
+    deploy(monkeypatch, tmp_path, fake)
+    for endpoint in ("/assets/check-missing", "/assets/upload", "/assets/upsert-hashes"):
+        assert fake.auth(endpoint) == "Bearer jot"
+        assert "/accounts/" not in fake.urls(endpoint)[0]
+    assert fake.auth("/deployments") == "Bearer tok"
+    assert "/accounts/acct/" in fake.urls("/deployments")[0]
+
+
+def test_only_the_missing_hashes_are_uploaded(monkeypatch, tmp_path):
+    build(tmp_path, {"index.html": "x", "second.html": "y"})
+    wanted = pages.file_hash(b"y", "html")
+    fake = FakeHTTP(missing=[wanted])
+    deploy(monkeypatch, tmp_path, fake)
+    uploaded = json.loads(fake.body("/assets/upload"))
+    assert [entry["key"] for entry in uploaded] == [wanted]
+    assert base64.b64decode(uploaded[0]["value"]) == b"y"
+    assert uploaded[0]["metadata"]["contentType"].startswith("text/html")
+    # ... and the manifest still names both, or the unchanged one would 404.
+    assert (
+        len(
+            json.loads(
+                fake.body("/deployments")
+                .decode()
+                .split('name="manifest"')[1]
+                .split("\r\n\r\n")[1]
+                .split("\r\n")[0]
+            )
+        )
+        == 2
+    )
+
+
+def test_nothing_uploads_when_cloudflare_already_has_it_all(monkeypatch, tmp_path):
+    build(tmp_path, {"index.html": "x"})
+    fake = FakeHTTP(missing=[])
+    deploy(monkeypatch, tmp_path, fake)
+    assert fake.urls("/assets/upload") == []
+    assert fake.urls("/deployments")  # the deployment is still created
+
+
+def test_the_deployment_carries_the_manifest_the_branch_and_the_headers(monkeypatch, tmp_path):
+    build(tmp_path, {"index.html": "x", "_headers": "/*\n  X-Frame-Options: DENY\n"})
+    fake = FakeHTTP()
+    deploy(monkeypatch, tmp_path, fake, branch="preview")
+    body = fake.body("/deployments").decode()
+    assert 'name="manifest"' in body and "/index.html" in body
+    assert 'name="branch"\r\n\r\npreview' in body
+    assert 'name="_headers"' in body and "X-Frame-Options" in body
+
+
+def test_a_cloudflare_error_names_its_own_message(monkeypatch, tmp_path):
+    build(tmp_path, {"index.html": "x"})
+
+    def angry(url, **kwargs):
+        return pages.http.Response(
+            url=url,
+            status=403,
+            body=json.dumps({"success": False, "errors": [{"code": 10000, "message": "no permission"}]}),
+        )
+
+    monkeypatch.setattr(pages.http, "request", angry)
+    with pytest.raises(MakeError, match="no permission"):
+        pages.deploy(tmp_path, project="demo", account="acct", token="tok")
+
+
+def test_dry_run_sends_nothing(tmp_path):
+    build(tmp_path, {"index.html": "x"})
+    with context(tmp_path, dry_run=True):
+        # The real http module, which refuses to make a request under --dry-run:
+        # a plan is printed and the fallback URL comes back.
+        url = pages.deploy(tmp_path, project="demo", account="acct", token="tok")
+    assert url == "https://main.demo.pages.dev"
+
+
+# -- batching --------------------------------------------------------------
+
+
+def test_uploads_are_batched_by_count_and_by_size(tmp_path):
+    assets = [
+        pages.Asset(
+            key=f"/{i}.txt", file=tmp_path / f"{i}.txt", hash=f"h{i}", size=1, content_type="text/plain"
+        )
+        for i in range(pages.BATCH_FILES * 2 + 3)
+    ]
+    assert [len(b) for b in pages._batches(assets)] == [pages.BATCH_FILES, pages.BATCH_FILES, 3]
+
+    fat = [
+        pages.Asset(key="/a", file=tmp_path / "a", hash="a", size=pages.BATCH_BYTES, content_type="x"),
+        pages.Asset(key="/b", file=tmp_path / "b", hash="b", size=pages.BATCH_BYTES, content_type="x"),
+    ]
+    assert [len(b) for b in pages._batches(fat)] == [1, 1]
+
+
+def test_the_special_files_are_file_parts_of_the_deployment():
+    """Pages reads `_headers` only as a FILE part, as wrangler sends it.
+
+    As a plain field the deployment still succeeds and the site serves with no
+    header rules at all -- isard.pages.dev lost its CSP that way on 2026-10-03.
+    """
+    body, content_type = pages._multipart({"branch": "main"}, {"_headers": "/*\n  X-Test: 1\n"})
+    text = body.decode()
+    assert 'name="_headers"; filename="_headers"' in text
+    assert 'name="branch"\r\n\r\nmain' in text  # an ordinary field stays one
+    assert "X-Test: 1" in text
+    assert content_type.startswith("multipart/form-data; boundary=")
+
+
+# -- creating a project ----------------------------------------------------
+
+
+def projects_api(existing):
+    calls = []
+
+    def answer(url, *, method="GET", headers=None, data=None, **kwargs):
+        calls.append((method, url, data))
+        if method == "GET":
+            result = [{"name": name, "subdomain": f"{name}.pages.dev"} for name in existing]
+        else:
+            sent = json.loads(data)
+            result = {"name": sent["name"], "subdomain": f"{sent['name']}-x1y.pages.dev"}
+        return pages.http.Response(
+            url=url, status=200, body=json.dumps({"success": True, "errors": [], "result": result})
+        )
+
+    return answer, calls
+
+
+def test_an_existing_project_is_returned_and_nothing_is_created(monkeypatch):
+    answer, calls = projects_api(["demo"])
+    monkeypatch.setattr(pages.http, "request", answer)
+    assert pages.create_project("demo", account="acct", token="tok")["subdomain"] == "demo.pages.dev"
+    assert [method for method, _, _ in calls] == ["GET"]
+
+
+def test_a_missing_project_is_created_on_its_production_branch(monkeypatch):
+    answer, calls = projects_api(["other"])
+    monkeypatch.setattr(pages.http, "request", answer)
+    made = pages.create_project("demo", account="acct", token="tok")
+    assert made["subdomain"] == "demo-x1y.pages.dev"
+    method, url, data = calls[-1]
+    assert (method, url.endswith("/accounts/acct/pages/projects")) == ("POST", True)
+    assert json.loads(data) == {"name": "demo", "production_branch": "main"}