make-cloudflare 0.1.0__tar.gz → 0.3.0__tar.gz

{make_cloudflare-0.1.0 → make_cloudflare-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: make-cloudflare
-Version: 0.1.0
+Version: 0.3.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>
@@ -29,8 +29,10 @@ 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.deploy dist --functions functions    # with Pages Functions
 $ mk cloudflare.projects                             # what the account has
 $ mk cloudflare.deployments --limit 5                # one project's recent ones
+$ mk cloudflare.prune --keep 10                      # delete all but the newest ten
 $ mk -n cloudflare.deploy site/dist                  # the plan; nothing is sent
 ```
 
@@ -42,6 +44,24 @@ 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.
 
+**Every deploy prunes the project to its newest 10 deployments** (`--keep N`
+to change it, `--keep 0` to keep them all; `pages.deploy(..., keep=)` from
+Python). Pages never deletes one by itself, and each stays reachable on its own
+`<hash>.<project>.pages.dev` URL forever. The live production deployment is
+never deleted, however old; a pruned preview that was still its branch's alias
+takes that branch URL with it.
+
+**Pages Functions go up with the deployment.** `--functions functions` (or
+`pages.deploy(..., functions=)`) names the tree. It sits **beside** the built
+directory, as wrangler expects, and `/api/...` answers from the same project and
+origin. Bundling it is a build step, not an upload, so that one step is
+`wrangler pages functions build --outfile` (from PATH, or through `npx`). It
+writes exactly the `_worker.bundle` the deployment takes, plus
+`functions-filepath-routing-config.json` and a generated `_routes.json`; the
+site's own `_routes.json` wins. Everything else is still the four calls below.
+Bindings (D1, KV) and secrets are settings on the Pages project, never part of
+the upload.
+
 ## Why this exists
 
 `wrangler pages deploy` is four HTTPS calls and a hash. Reaching them through
@@ -72,9 +92,9 @@ call returns 200 and the site serves the old bytes, or none:
 
 ## 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.
+**Advanced-mode `_worker.js`.** A `_worker.js` (or a `functions/`) *inside*
+the built directory is refused by name: it would otherwise be served as a
+static file. Pages Functions go beside it, through `--functions`.
 
 **Steps 2 and 3 are undocumented.** They exist because wrangler uses them, and
 Cloudflare can change them without a changelog; the documented `deployments`
@@ -85,5 +105,5 @@ 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
+`projects`, `deployments` and `prune`, 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 → make_cloudflare-0.3.0}/README.md

@@ -16,8 +16,10 @@ 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.deploy dist --functions functions    # with Pages Functions
 $ mk cloudflare.projects                             # what the account has
 $ mk cloudflare.deployments --limit 5                # one project's recent ones
+$ mk cloudflare.prune --keep 10                      # delete all but the newest ten
 $ mk -n cloudflare.deploy site/dist                  # the plan; nothing is sent
 ```
 
@@ -29,6 +31,24 @@ 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.
 
+**Every deploy prunes the project to its newest 10 deployments** (`--keep N`
+to change it, `--keep 0` to keep them all; `pages.deploy(..., keep=)` from
+Python). Pages never deletes one by itself, and each stays reachable on its own
+`<hash>.<project>.pages.dev` URL forever. The live production deployment is
+never deleted, however old; a pruned preview that was still its branch's alias
+takes that branch URL with it.
+
+**Pages Functions go up with the deployment.** `--functions functions` (or
+`pages.deploy(..., functions=)`) names the tree. It sits **beside** the built
+directory, as wrangler expects, and `/api/...` answers from the same project and
+origin. Bundling it is a build step, not an upload, so that one step is
+`wrangler pages functions build --outfile` (from PATH, or through `npx`). It
+writes exactly the `_worker.bundle` the deployment takes, plus
+`functions-filepath-routing-config.json` and a generated `_routes.json`; the
+site's own `_routes.json` wins. Everything else is still the four calls below.
+Bindings (D1, KV) and secrets are settings on the Pages project, never part of
+the upload.
+
 ## Why this exists
 
 `wrangler pages deploy` is four HTTPS calls and a hash. Reaching them through
@@ -59,9 +79,9 @@ call returns 200 and the site serves the old bytes, or none:
 
 ## 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.
+**Advanced-mode `_worker.js`.** A `_worker.js` (or a `functions/`) *inside*
+the built directory is refused by name: it would otherwise be served as a
+static file. Pages Functions go beside it, through `--functions`.
 
 **Steps 2 and 3 are undocumented.** They exist because wrangler uses them, and
 Cloudflare can change them without a changelog; the documented `deployments`
@@ -72,5 +92,5 @@ 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
+`projects`, `deployments` and `prune`, 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 → make_cloudflare-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "make-cloudflare"
-version = "0.1.0"
+version = "0.3.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"

{make_cloudflare-0.1.0 → make_cloudflare-0.3.0}/src/make_cloudflare/__init__.py

@@ -2,7 +2,8 @@
 
 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 --
+`cloudflare.deployments` shows a project's recent ones, and `cloudflare.prune`
+deletes all but the newest ten (which every deploy also does). No Node, no wrangler --
 four HTTPS calls and a BLAKE3 hash.
 
 Importing is what registers it:
@@ -11,12 +12,12 @@ Importing is what registers it:
     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.
+namespaces, and this package claims only the four names above.
 """
 
 from __future__ import annotations
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
 __all__ = ["cloudflare", "pages"]
 

{make_cloudflare-0.1.0 → make_cloudflare-0.3.0}/src/make_cloudflare/cloudflare.py

@@ -23,14 +23,20 @@ def deploy(
     *,
     project: str | None = None,
     branch: Annotated[str, arg(help="the Pages branch; the production one publishes live")] = "main",
+    keep: Annotated[int, arg(help="deployments to keep afterwards; 0 keeps every one")] = pages.KEEP,
+    functions: Annotated[str | None, arg(help="a Pages Functions tree to bundle and deploy with it")] = None,
 ) -> None:
     """Publish a built directory to Cloudflare Pages by direct upload.
 
-    No Node and no wrangler: four HTTPS calls. `--branch` is what decides
+    No Node and no wrangler: four HTTPS calls. (`--functions` is the exception:
+    wrangler bundles that tree, and only bundles it.) `--branch` is what decides
     production -- the project's production branch goes live, every other name
-    lands as a preview on its own URL.
+    lands as a preview on its own URL. Then the project is pruned to its
+    newest `--keep` deployments; the live one always stays.
     """
-    url = pages.deploy(Path(directory), project=pages.project_name(project), branch=branch)
+    url = pages.deploy(
+        Path(directory), project=pages.project_name(project), branch=branch, keep=keep, functions=functions
+    )
     note(f"deployed -- {url}")
 
 
@@ -50,3 +56,11 @@ def deployments(project: str | None = None, *, limit: int = 10) -> None:
         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', '')}")
+
+
+@task(group="cloudflare", name="prune", dangerous=True, secrets=["CLOUDFLARE_API_TOKEN"])
+def prune(project: str | None = None, *, keep: int = pages.KEEP) -> None:
+    """Delete all but a project's newest `--keep` deployments; the live one always stays."""
+    name = pages.project_name(project)
+    if not pages.prune(name, keep=keep):
+        note(f"{name} has {keep} deployments or fewer; nothing to delete")

{make_cloudflare-0.1.0 → make_cloudflare-0.3.0}/src/make_cloudflare/pages.py

@@ -8,6 +8,7 @@ a built directory without installing a JavaScript toolchain to do it.
 
     pages.deploy("site/dist", project="mkrun")            # production
     pages.deploy("site/dist", project="mkrun", branch="x")  # a preview
+    pages.deploy("dist", project="name", functions="functions")  # with Pages Functions
 
 The flow, and the three things a naive port gets wrong:
 
@@ -30,6 +31,13 @@ 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.
+
+**Pages Functions are built by wrangler, and only built.** Bundling a
+`functions/` tree into a Worker is esbuild plus Cloudflare's routing glue, and
+`wrangler pages functions build --outfile` writes exactly the `_worker.bundle`
+the deployment takes. That one build step is the only thing wrangler does here;
+the upload is still these calls. Bindings (D1, KV) and secrets are settings on
+the Pages project, never part of the upload.
 """
 
 from __future__ import annotations
@@ -39,17 +47,20 @@ import json
 import mimetypes
 import os
 import secrets as _random
+import shutil
+import tempfile
 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 import env, http, note, sh, step
 from make.context import mark_sensitive
 from make.errors import ConfigError, MakeError
 
 __all__ = [
     "Asset",
+    "build_functions",
     "collect",
     "deploy",
     "deployments",
@@ -57,6 +68,7 @@ __all__ = [
     "manifest_of",
     "project_name",
     "projects",
+    "prune",
 ]
 
 API = "https://api.cloudflare.com/client/v4"
@@ -72,12 +84,21 @@ MAX_ASSET_COUNT = 20_000
 BATCH_FILES = 100
 BATCH_BYTES = 10 * 1024 * 1024
 
+#: How many deployments a project keeps after a deploy: the newest ones, plus
+#: the live production deployment wherever it falls. Pages itself keeps every
+#: one forever, each on its own URL.
+KEEP = 10
+
+#: One page of the deployments listing.
+PER_PAGE = 25
+
 #: 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.
+#: Never uploaded. Pages Functions live *beside* the built directory and are
+#: handed to `deploy(functions=...)`; inside it they would be served as static
+#: files -- the source of the API, readable by anyone. An advanced-mode
+#: `_worker.js` is not built here at all.
 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")
@@ -137,8 +158,9 @@ def collect(directory: str | Path) -> tuple[list[Asset], dict[str, str]]:
     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",
+                f"{root / name} is Pages Functions code inside the built directory",
+                hint="keep `functions/` beside the built directory and pass `functions=`; "
+                "an advanced-mode `_worker.js` is not supported",
             )
 
     assets: list[Asset] = []
@@ -200,7 +222,18 @@ def _credentials(account: str | None, token: str | None) -> tuple[str, str]:
     return account, token
 
 
-def _call(
+def _call(method: str, url: str, **kwargs: Any) -> 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.
+    """
+    payload = _envelope(method, url, **kwargs)
+    return None if payload is None else payload.get("result")
+
+
+def _envelope(
     method: str,
     url: str,
     *,
@@ -208,13 +241,8 @@ def _call(
     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.
-    """
+) -> dict | None:
+    """One API call, returning Cloudflare's whole answer -- `result_info` too."""
     headers = {"Authorization": f"Bearer {auth}"}
     if content_type:
         headers["Content-Type"] = content_type
@@ -236,7 +264,7 @@ def _call(
             f"{method} {url} -> {answer.status}" + (f": {detail}" if detail else ""),
             hint=None if detail else (answer.body[:300] or None),
         )
-    return payload.get("result")
+    return payload
 
 
 def _json_call(method: str, url: str, *, auth: str, payload: object, **kwargs: Any) -> Any:
@@ -245,7 +273,9 @@ def _json_call(method: str, url: str, *, auth: str, payload: object, **kwargs: A
     )
 
 
-def _multipart(fields: Mapping[str, str], files: Mapping[str, str] | None = None) -> tuple[bytes, str]:
+def _multipart(
+    fields: Mapping[str, str], files: Mapping[str, str | bytes] | 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),
@@ -264,7 +294,7 @@ def _multipart(fields: Mapping[str, str], files: Mapping[str, str] | None = None
         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(value if isinstance(value, bytes) else value.encode())
         chunks.append(b"\r\n")
     chunks.append(f"--{boundary}--\r\n".encode())
     return b"".join(chunks), f"multipart/form-data; boundary={boundary}"
@@ -284,6 +314,55 @@ def _batches(assets: list[Asset]) -> Iterator[list[Asset]]:
         yield batch
 
 
+# -- Pages Functions -------------------------------------------------------
+
+
+def _wrangler() -> list[str]:
+    found = shutil.which("wrangler")
+    return [found] if found else ["npx", "--yes", "wrangler"]
+
+
+def build_functions(functions: str | Path, directory: str | Path, out: str | Path) -> dict[str, bytes]:
+    """Bundle a `functions/` tree; return the deployment's file parts.
+
+    `_worker.bundle` (the Worker, already in the upload form Pages takes),
+    `functions-filepath-routing-config.json`, and `_routes.json` unless the
+    built directory brings its own -- the same three `wrangler pages deploy`
+    sends. Empty under `--dry-run`, where nothing was built.
+    """
+    source = Path(functions).resolve()
+    root = Path(directory).resolve()
+    if not source.is_dir():
+        raise MakeError(f"{source} is not a directory", hint="`functions=` names the Pages Functions tree")
+    out = Path(out)
+    bundle, config, routes = out / "_worker.bundle", out / "routing-config.json", out / "_routes.json"
+    sh(
+        *_wrangler(),
+        "pages",
+        "functions",
+        "build",
+        source,
+        "--outfile",
+        bundle,
+        "--output-config-path",
+        config,
+        "--output-routes-path",
+        routes,
+        "--build-output-directory",
+        root,
+        cwd=source.parent,
+    )
+    if not bundle.is_file():
+        return {}
+    parts = {
+        "_worker.bundle": bundle.read_bytes(),
+        "functions-filepath-routing-config.json": config.read_bytes(),
+    }
+    if not (root / "_routes.json").is_file() and routes.is_file():
+        parts["_routes.json"] = routes.read_bytes()
+    return parts
+
+
 # -- the tasks' behaviour --------------------------------------------------
 
 
@@ -292,6 +371,8 @@ def deploy(
     *,
     project: str,
     branch: str = "main",
+    keep: int = KEEP,
+    functions: str | Path | None = None,
     account: str | None = None,
     token: str | None = None,
 ) -> str:
@@ -301,9 +382,18 @@ def deploy(
     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.
+
+    `functions` names a Pages Functions tree (`functions/`, beside the built
+    directory): it is bundled by `build_functions` and goes up with the
+    deployment, so `/api/...` answers from the same project.
+
+    Afterwards the project is pruned to its newest `keep` deployments (see
+    `prune`); `keep=0` leaves every one in place.
     """
     account, token = _credentials(account, token)
     assets, specials = collect(directory)
+    with tempfile.TemporaryDirectory(prefix="mk-pages-") as scratch:
+        worker = build_functions(functions, directory, scratch) if functions is not None else {}
     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})")
 
@@ -358,7 +448,7 @@ def deploy(
     )
 
     fields = {"manifest": json.dumps(manifest_of(assets)), "branch": branch}
-    body, content_type = _multipart(fields, specials)
+    body, content_type = _multipart(fields, {**specials, **worker})
     created = _call(
         "POST",
         f"{API}/accounts/{account}/pages/projects/{project}/deployments",
@@ -366,9 +456,11 @@ def deploy(
         body=body,
         content_type=content_type,
     )
-    if specials:
-        note("as deployment files, not assets: " + ", ".join(sorted(specials)))
+    if specials or worker:
+        note("as deployment files, not assets: " + ", ".join(sorted({**specials, **worker})))
     url = created.get("url") if isinstance(created, dict) else None
+    if keep:
+        prune(project, keep=keep, account=account, token=token)
     return str(url or f"https://{branch}.{project}.pages.dev")
 
 
@@ -403,10 +495,55 @@ def create_project(
 
 
 def deployments(project: str, *, account: str | None = None, token: str | None = None) -> list[dict]:
-    """A project's deployments, newest first."""
+    """A project's deployments, newest first -- every page of them.
+
+    The listing is paginated, and one page is not all of a project that has
+    been deployed by hand for a month. `[]` under `--dry-run`.
+    """
     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 []
+    found: list[dict] = []
+    page = 1
+    while True:
+        payload = _envelope(
+            "GET",
+            f"{API}/accounts/{account}/pages/projects/{project}/deployments?page={page}&per_page={PER_PAGE}",
+            auth=token,
+        )
+        result = (payload or {}).get("result")
+        if not isinstance(result, list) or not result:
+            return found
+        found.extend(result)
+        pages_total = ((payload or {}).get("result_info") or {}).get("total_pages")
+        if isinstance(pages_total, int) and page >= pages_total:
+            return found
+        page += 1
+
+
+def prune(
+    project: str, *, keep: int = KEEP, account: str | None = None, token: str | None = None
+) -> list[dict]:
+    """Delete all but the newest `keep` deployments of `project`; return the deleted ones.
+
+    The live production deployment is never deleted, however old -- Pages
+    refuses it anyway, and it is the site. A preview that is still its branch's
+    alias goes with `force=true`: its branch URL stops serving, which is what
+    pruning a preview means.
+    """
+    if keep < 1:
+        raise MakeError(f"keep={keep} would delete every deployment", hint="keep at least 1")
+    account, token = _credentials(account, token)
+    base = f"{API}/accounts/{account}/pages/projects/{project}"
+    found = deployments(project, account=account, token=token)
+    if len(found) <= keep:
+        return []
+    live = (_call("GET", base, auth=token) or {}).get("canonical_deployment") or {}
+    doomed = [d for d in found[keep:] if d.get("id") and d.get("id") != live.get("id")]
+    for entry in doomed:
+        _call("DELETE", f"{base}/deployments/{entry['id']}?force=true", auth=token)
+    if doomed:
+        plural = "" if len(doomed) == 1 else "s"
+        note(f"pruned {len(doomed)} old deployment{plural} of {project}; kept the newest {keep}")
+    return doomed
 
 
 def project_name(project: str | None) -> str:

{make_cloudflare-0.1.0 → make_cloudflare-0.3.0}/tests/test_pages.py

@@ -109,6 +109,13 @@ def test_a_functions_project_is_refused(tmp_path):
         pages.collect(tmp_path)
 
 
+def test_functions_inside_the_built_directory_are_refused(tmp_path):
+    """Served from there, the API's source would be a static file anyone can read."""
+    build(tmp_path, {"index.html": "x", "functions/api/x.ts": "export const onRequest = 1"})
+    with pytest.raises(MakeError, match="inside the built directory"):
+        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"):
@@ -133,6 +140,7 @@ def test_deploy_makes_the_four_calls_in_order(monkeypatch, tmp_path):
         "upload",
         "upsert-hashes",
         "deployments",
+        "deployments?page=1&per_page=25",  # the prune: one deployment, nothing to delete
     ]
     assert url == "https://abc123.example.pages.dev"
 
@@ -282,3 +290,136 @@ def test_a_missing_project_is_created_on_its_production_branch(monkeypatch):
     method, url, data = calls[-1]
     assert (method, url.endswith("/accounts/acct/pages/projects")) == ("POST", True)
     assert json.loads(data) == {"name": "demo", "production_branch": "main"}
+
+
+# -- pruning ---------------------------------------------------------------
+
+
+def history_api(count: int, *, live: str, per_page: int = 25):
+    """A project with `count` deployments, `d0` newest, served in pages of `per_page`."""
+    calls: list[tuple[str, str]] = []
+    ids = [f"d{i}" for i in range(count)]
+
+    def answer(url, *, method="GET", **kwargs):
+        calls.append((method, url))
+        info = None
+        if method == "DELETE":
+            result = None
+        elif "/deployments?" in url:
+            page = int(url.split("page=")[1].split("&")[0])
+            chunk = ids[(page - 1) * per_page : page * per_page]
+            result = [{"id": i} for i in chunk]
+            info = {"page": page, "per_page": per_page, "total_pages": -(-count // per_page)}
+        elif url.endswith("/deployments"):
+            result = {"url": "https://new.demo.pages.dev"}
+        elif url.endswith("/projects/demo"):
+            result = {"name": "demo", "canonical_deployment": {"id": live}}
+        else:
+            result = {"jwt": "jot"} if url.endswith("/upload-token") else []
+        body = {"success": True, "errors": [], "result": result}
+        if info:
+            body["result_info"] = info
+        return pages.http.Response(url=url, status=200, body=json.dumps(body))
+
+    return answer, calls
+
+
+def deleted(calls) -> list[str]:
+    return [url.split("/deployments/")[1].split("?")[0] for method, url in calls if method == "DELETE"]
+
+
+def test_prune_keeps_the_newest_and_reads_every_page(monkeypatch):
+    answer, calls = history_api(60, live="d0")
+    monkeypatch.setattr(pages.http, "request", answer)
+    gone = pages.prune("demo", keep=10, account="acct", token="tok")
+    assert [d["id"] for d in gone] == [f"d{i}" for i in range(10, 60)]
+    assert deleted(calls) == [f"d{i}" for i in range(10, 60)]
+    assert sum("/deployments?page=" in url for _, url in calls) == 3
+    assert all(url.endswith("?force=true") for method, url in calls if method == "DELETE")
+
+
+def test_prune_never_deletes_the_live_deployment(monkeypatch):
+    answer, calls = history_api(15, live="d12")  # a run of previews pushed it down
+    monkeypatch.setattr(pages.http, "request", answer)
+    pages.prune("demo", keep=10, account="acct", token="tok")
+    assert deleted(calls) == ["d10", "d11", "d13", "d14"]
+
+
+def test_prune_with_little_history_deletes_nothing(monkeypatch):
+    answer, calls = history_api(10, live="d0")
+    monkeypatch.setattr(pages.http, "request", answer)
+    assert pages.prune("demo", keep=10, account="acct", token="tok") == []
+    assert deleted(calls) == []
+
+
+def test_prune_refuses_to_keep_nothing():
+    with pytest.raises(MakeError, match="every deployment"):
+        pages.prune("demo", keep=0, account="acct", token="tok")
+
+
+def test_deploy_prunes_unless_told_to_keep_everything(monkeypatch, tmp_path):
+    build(tmp_path, {"index.html": "x"})
+    answer, calls = history_api(12, live="d0")
+    monkeypatch.setattr(pages.http, "request", answer)
+    pages.deploy(tmp_path, project="demo", account="acct", token="tok")
+    assert deleted(calls) == ["d10", "d11"]
+
+    calls.clear()
+    pages.deploy(tmp_path, project="demo", account="acct", token="tok", keep=0)
+    assert deleted(calls) == [] and not any("/deployments?" in url for _, url in calls)
+
+
+# -- Pages Functions -------------------------------------------------------
+
+
+def fake_wrangler(monkeypatch):
+    """Stands in for `wrangler pages functions build`, writing the three outputs."""
+    seen = []
+
+    def run(*argv, cwd=None, **kwargs):
+        argv = [str(a) for a in argv]
+        seen.append(argv)
+        out = {
+            flag: argv[argv.index(flag) + 1]
+            for flag in ("--outfile", "--output-config-path", "--output-routes-path")
+        }
+        pages.Path(out["--outfile"]).write_bytes(b"--bundle--")
+        pages.Path(out["--output-config-path"]).write_text('{"routes": []}')
+        pages.Path(out["--output-routes-path"]).write_text('{"include": ["/api/*"]}')
+
+    monkeypatch.setattr(pages, "sh", run)
+    return seen
+
+
+def test_functions_go_up_as_file_parts_of_the_deployment(monkeypatch, tmp_path):
+    site = build(tmp_path / "dist", {"index.html": "x"})
+    functions = build(tmp_path / "functions", {"api/[[path]].ts": "export const onRequest = 1"})
+    seen = fake_wrangler(monkeypatch)
+    fake = FakeHTTP()
+    deploy(monkeypatch, site, fake, functions=functions)
+
+    assert seen[0][1:4] == ["pages", "functions", "build"] or seen[0][3:6] == ["pages", "functions", "build"]
+    body = fake.body("/deployments").decode()
+    assert 'name="_worker.bundle"; filename="_worker.bundle"' in body and "--bundle--" in body
+    assert 'name="functions-filepath-routing-config.json"; filename=' in body
+    assert 'name="_routes.json"; filename="_routes.json"' in body and "/api/*" in body
+    # The functions are never assets.
+    assert "[[path]]" not in fake.body("/check-missing").decode()
+
+
+def test_the_sites_own_routes_beat_the_generated_ones(monkeypatch, tmp_path):
+    site = build(tmp_path / "dist", {"index.html": "x", "_routes.json": '{"include": ["/mine/*"]}'})
+    functions = build(tmp_path / "functions", {"api/x.ts": "export const onRequest = 1"})
+    fake_wrangler(monkeypatch)
+    fake = FakeHTTP()
+    deploy(monkeypatch, site, fake, functions=functions)
+
+    body = fake.body("/deployments").decode()
+    assert body.count('filename="_routes.json"') == 1
+    assert "/mine/*" in body and "/api/*" not in body
+
+
+def test_a_missing_functions_tree_is_named(monkeypatch, tmp_path):
+    site = build(tmp_path / "dist", {"index.html": "x"})
+    with pytest.raises(MakeError, match="not a directory"):
+        deploy(monkeypatch, site, FakeHTTP(), functions=tmp_path / "nope")