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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: make-cloudflare
-Version: 0.1.0
+Version: 0.2.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>
@@ -31,6 +31,7 @@ $ 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 cloudflare.prune --keep 10                      # delete all but the newest ten
 $ mk -n cloudflare.deploy site/dist                  # the plan; nothing is sent
 ```
 
@@ -42,6 +43,13 @@ 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.
+
 ## Why this exists
 
 `wrangler pages deploy` is four HTTPS calls and a hash. Reaching them through
@@ -85,5 +93,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.2.0}/README.md

@@ -18,6 +18,7 @@ $ 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 cloudflare.prune --keep 10                      # delete all but the newest ten
 $ mk -n cloudflare.deploy site/dist                  # the plan; nothing is sent
 ```
 
@@ -29,6 +30,13 @@ 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.
+
 ## Why this exists
 
 `wrangler pages deploy` is four HTTPS calls and a hash. Reaching them through
@@ -72,5 +80,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.2.0}/pyproject.toml

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

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

@@ -23,14 +23,16 @@ 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,
 ) -> 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.
+    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)
     note(f"deployed -- {url}")
 
 
@@ -50,3 +52,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.2.0}/src/make_cloudflare/pages.py

@@ -57,6 +57,7 @@ __all__ = [
     "manifest_of",
     "project_name",
     "projects",
+    "prune",
 ]
 
 API = "https://api.cloudflare.com/client/v4"
@@ -72,6 +73,14 @@ 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")
 
@@ -200,7 +209,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 +228,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 +251,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:
@@ -292,6 +307,7 @@ def deploy(
     *,
     project: str,
     branch: str = "main",
+    keep: int = KEEP,
     account: str | None = None,
     token: str | None = None,
 ) -> str:
@@ -301,6 +317,9 @@ 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.
+
+    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)
@@ -369,6 +388,8 @@ def deploy(
     if specials:
         note("as deployment files, not assets: " + ", ".join(sorted(specials)))
     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 +424,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.2.0}/tests/test_pages.py

@@ -133,6 +133,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 +283,80 @@ 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)