@norskvideo/ctl-dev-kit 0.2.93 → 0.2.95

package/conventions/docs-site.md

@@ -177,9 +177,9 @@ ln -s ../../../../../docs/generated/<slug> website/src/content/docs/guides/<slug
 
 `docs:site` runs the dev-kit's `docs/guide-stubs.ts stub` first, so the site
 builds on a checkout that has never captured. The captures come from the
-product's nightly `publish-docs.yml`, which saves `docs/generated` to the
-Actions cache after a passing engine tier; `publish-docs-site.yml` restores
-the newest set before its build (and runs when `publish-docs` completes, so a
+product's nightly `publish-docs.yml`, which keeps `docs/generated` as the
+`docs-captures` artifact after a passing engine tier; `publish-docs-site.yml`
+downloads the newest one before its build (and runs when `publish-docs` completes, so a
 fresh capture publishes without waiting for a push). It then runs
 `guide-stubs.ts check` and refuses to deploy while any guide is still a
 placeholder: until the guide has been captured once, the publish stops rather
@@ -214,9 +214,11 @@ where the repo has a site and is not a turnkey. On every push to `main` (and on
 demand) it installs `website/`, builds the public variant and deploys
 `website/dist-public` to Cloudflare Pages with `wrangler`. It never cancels a
 run in flight, because a cancelled deploy is a half-published site. Before the
-build it restores the newest recorded-guide captures from the Actions cache
-(`docs-captures-*`, saved by `publish-docs.yml`); a site with no recorded
-guides restores nothing it reads, and builds from its committed prose.
+build it downloads the newest recorded-guide captures (the `docs-captures`
+artifact `publish-docs.yml` keeps for 30 days, not the Actions cache, whose
+entries are versioned by a compression that varies across runners); a site
+with no recorded guides restores nothing it reads, and builds from its
+committed prose.
 
 Where it may exist is the gate's business (ADR-0012, and the documentation
 plan): a repo with `website/astro.config.mjs` may carry it; a repo without a
@@ -229,10 +231,11 @@ What the repo needs, per site, and none of it to build or review one locally:
 
 1. **A Cloudflare Pages project**, e.g. `norsk-acme-docs`.
 2. **A custom domain** on it — `<product>.norsk.video` — and the DNS record.
-3. **Two repo secrets.** `CLOUDFLARE_API_TOKEN`, a Pages:Edit token — the
-   existing one is deliberately narrow and must cover the new project: widen it
-   to all Pages projects in the account, or issue a second token — and
-   `CLOUDFLARE_ACCOUNT_ID`. The workflow verifies the token at the API (both the
+3. **The Cloudflare credentials reaching the repo.** The secret
+   `CLOUDFLARE_API_TOKEN`, a Pages:Edit token that covers the new project
+   (Pages permissions are account-wide), and the variable
+   `CLOUDFLARE_ACCOUNT_ID`. Both are org-level, shared with selected
+   repositories: add the repo to each. The workflow verifies the token at the API (both the
    user-owned and the account-owned endpoint), never with `wrangler whoami`,
    which a Pages:Edit token cannot answer.
 4. **One repo variable.** `NORSK_DOCS_SITE_PROJECT`, the project name from

package/conventions/publish-docs-site.yml

@@ -8,7 +8,7 @@
 # rides every push (conventions/docs-site.md, "Two documentation channels").
 # A site that also symlinks RECORDED guides (website/src/content/docs/guides/
 # <slug> -> docs/generated/<slug>) publishes them from the captures that nightly
-# run saves to the Actions cache: they are restored before the build, which
+# run keeps as an artifact: they are restored before the build, which
 # stubs only a guide never captured, and the gate below refuses to deploy a
 # stub. So the site also runs when publish-docs completes, to publish a fresh
 # capture without waiting for the next push.
@@ -26,7 +26,9 @@
 #                                      site publishes the day the variable is
 #                                      set, with no change here.
 #   secret   CLOUDFLARE_API_TOKEN      a Pages:Edit token covering that project
-#   secret   CLOUDFLARE_ACCOUNT_ID     the account the project lives in
+#   variable CLOUDFLARE_ACCOUNT_ID     the account the project lives in: not a
+#                                      secret, and the org already shares it as
+#                                      a variable (norsk-ctl reads it the same way)
 #
 # The site is BUILT whether or not it will be deployed: if the build is only
 # exercised on the day the Pages project appears, that day is when we find out
@@ -50,6 +52,7 @@ on:
 
 permissions:
   contents: read
+  actions: read # the newest docs-captures artifact, from the capture run
 
 # Never cancel in flight: a cancelled `wrangler pages deploy` is a half-published
 # site, and the next push rebuilds from the same inputs anyway. Queue instead.
@@ -122,17 +125,28 @@ jobs:
           clean: true
 
       # The recorded guides' captures, from the product's nightly capture run
-      # (publish-docs.yml saves docs/generated after a passing engine tier):
-      # the newest set, restored where docs:site:public expects it. None yet --
-      # a site that records no guides, or before the first capture -- restores
-      # nothing; the build stubs what is missing and the gate below refuses to
-      # deploy a stub.
+      # (publish-docs.yml keeps docs/generated as the docs-captures artifact
+      # after a passing engine tier): the newest unexpired one, put where
+      # docs:site:public expects it. None yet -- a site that records no guides,
+      # or before the first capture -- restores nothing; the build stubs what is
+      # missing and the gate below refuses to deploy a stub. gh comes from the
+      # build shell (the runners have no system gh).
       - name: Restore the recorded guides' captures
-        uses: actions/cache/restore@v4
-        with:
-          path: docs/generated
-          key: docs-captures-${{ github.sha }}
-          restore-keys: docs-captures-
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            run="$(gh api "repos/$GITHUB_REPOSITORY/actions/artifacts?name=docs-captures&per_page=20" \
+              --jq "[.artifacts[] | select(.expired | not)][0].workflow_run.id // empty")"
+            if [ -z "$run" ]; then
+              echo "no docs-captures artifact yet: nothing to restore"
+              exit 0
+            fi
+            mkdir -p docs/generated
+            gh run download "$run" --repo "$GITHUB_REPOSITORY" --name docs-captures --dir docs/generated
+            echo "restored the recorded guides captured by run $run"
+          '
 
       # website/ is a STANDALONE package -- its own bun.lock, outside the root
       # workspaces -- so the repo-root install never covers it, and the build
@@ -197,7 +211,7 @@ jobs:
       - name: Deploy to Cloudflare Pages
         env:
           CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
           NORSK_DOCS_SITE_PROJECT: ${{ vars.NORSK_DOCS_SITE_PROJECT }}
           PAGES_BRANCH: ${{ github.ref_name }}
         run: |
@@ -210,13 +224,13 @@ jobs:
             echo "     1. Create a Cloudflare Pages project for this site (e.g. $(basename "$GITHUB_REPOSITORY")-docs)."
             echo "     2. Add its custom domain${origin:+ (${origin#https://})} and the DNS record."
             echo "     3. Make sure CLOUDFLARE_API_TOKEN (Pages:Edit) covers that project, and that"
-            echo "        CLOUDFLARE_ACCOUNT_ID is set as a repo secret."
+            echo "        the variable CLOUDFLARE_ACCOUNT_ID reaches this repo."
             echo "     4. Set the repo variable NORSK_DOCS_SITE_PROJECT to the project name."
             echo "   Nothing in this workflow changes. See @norskvideo/ctl-dev-kit conventions/docs-site.md, Publishing."
             exit 0
           fi
           if [ -z "${CLOUDFLARE_API_TOKEN:-}" ] || [ -z "${CLOUDFLARE_ACCOUNT_ID:-}" ]; then
-            echo "::error::NORSK_DOCS_SITE_PROJECT=$NORSK_DOCS_SITE_PROJECT is set, but CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID must both be repo secrets"
+            echo "::error::NORSK_DOCS_SITE_PROJECT=$NORSK_DOCS_SITE_PROJECT is set, but this repo needs both the secret CLOUDFLARE_API_TOKEN and the variable CLOUDFLARE_ACCOUNT_ID"
             exit 1
           fi
           cf_verify() {

package/conventions/publish-docs.yml

@@ -319,16 +319,21 @@ jobs:
         run: nix develop .#build --command bun run docs:manual
 
       # The captures, for the product's own docs site: publish-docs-site.yml
-      # restores the newest set, so its recorded guides publish from this run,
-      # the only one that can make them. Only after a passing engine tier, so a
-      # site never takes a half-captured set over the last good one. Each run
-      # its own key: a cache entry is never overwritten.
-      - name: Cache the guide captures for the docs site
+      # downloads the newest docs-captures artifact, so its recorded guides
+      # publish from this run, the only one that can make them. Only after a
+      # passing engine tier, so a site never takes a half-captured set over the
+      # last good one. An artifact, not actions/cache: a cache entry is
+      # versioned by its compression, and the runner pool mixes machines with
+      # and without zstd, so a save on one never matched a restore on another
+      # (relay, 2026-10-21: saved on ashton-nuc, missed on test2-runner-1).
+      - name: Keep the guide captures for the docs site
         if: ${{ steps.engine.outcome == 'success' }}
-        uses: actions/cache/save@v4
+        uses: actions/upload-artifact@v4
         with:
+          name: docs-captures
           path: docs/generated
-          key: docs-captures-${{ github.sha }}-${{ github.run_id }}
+          retention-days: 30
+          if-no-files-found: error
 
       # Said three ways, so a failure is never silent: a warning on the run, a
       # line in its summary, and the cell's detail (the notify job).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.2.93",
+  "version": "0.2.95",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",