rcf-lite 0.22.0 → 0.24.0

package/blueprints/deploy-cloudflare-workers/contributions/probes/assets-manifest-scan.mjs

@@ -0,0 +1,207 @@
+// Source-tree scan probe for the deploy-cloudflare-workers v1.2.0
+// Workers-with-static-assets shape (T-0 of the Cloudflare round 6
+// spec, section 5.0). accountBound false: this probe reads the
+// applied fixture wrangler.toml and asserts three properties:
+//
+//   1. When the elicited assets-directory answer is non-empty, the
+//      [assets] table's directory field equals the elicited answer
+//      (assetsBlockEmitted, canonical AC-12113-1).
+//   2. When the elicited run-worker-first answer is truthy, the
+//      [assets] table carries run_worker_first equal to true; when
+//      falsy or unanswered, run_worker_first is absent
+//      (spaFallbackShape facet of AC-12113-1).
+//   3. The manifest never carries a Pages-only pages_build_output_dir
+//      field alongside [assets]; the two shapes are mutually
+//      exclusive per Cloudflare's static-assets doc.
+//
+// Verdict envelope per spec section 3.2: { verdict, detail,
+// anchorAcId, aggregateVerdict } where anchorAcId is
+// AC-12113-1 (the assetsBlockEmitted anchor). aggregateVerdict is
+// pass when every result is pass, warn when any is warn (unused
+// here), fail when any is fail. Cleans up any temporary files it
+// wrote on exit.
+
+import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
+import { dirname, resolve, join } from 'node:path';
+
+export const anchorAcId = 'AC-12113-1';
+export const accountBound = false;
+
+// Minimal wrangler.toml reader. Handles the small subset of TOML the
+// blueprint's manifest declares (top-level scalars, one [assets]
+// table, and boolean/string literals). Reaches for no runtime dep;
+// keeps the probe accountBound-false and dependency-free.
+export function parseWranglerToml(text) {
+  const lines = text.split(/\r?\n/);
+  const root = {};
+  let currentTable = root;
+  let currentTableName = '';
+  for (const raw of lines) {
+    const line = raw.replace(/^\s+/, '').replace(/\s+$/, '');
+    if (line === '' || line.startsWith('#')) continue;
+    const tableMatch = line.match(/^\[([A-Za-z0-9_.\-]+)\]$/);
+    if (tableMatch) {
+      currentTableName = tableMatch[1];
+      root[currentTableName] = root[currentTableName] || {};
+      currentTable = root[currentTableName];
+      continue;
+    }
+    const kv = line.match(/^([A-Za-z0-9_\-]+)\s*=\s*(.+)$/);
+    if (!kv) continue;
+    const key = kv[1];
+    let value = kv[2].trim();
+    // Strip trailing comments (a naive #-then-space split; sufficient
+    // for the wrangler shapes this blueprint generates).
+    const hashAt = value.indexOf(' #');
+    if (hashAt !== -1) value = value.slice(0, hashAt).trim();
+    if (value === 'true') {
+      currentTable[key] = true;
+    } else if (value === 'false') {
+      currentTable[key] = false;
+    } else if (/^-?\d+$/.test(value)) {
+      currentTable[key] = Number(value);
+    } else if (value.startsWith('"') && value.endsWith('"')) {
+      currentTable[key] = value.slice(1, -1);
+    } else if (value.startsWith("'") && value.endsWith("'")) {
+      currentTable[key] = value.slice(1, -1);
+    } else {
+      currentTable[key] = value;
+    }
+  }
+  return root;
+}
+
+// Drive the scan against the fixture. `opts.fixtureRoot` names the
+// directory the wrangler.toml lives in; `opts.elicited` names the
+// answers the fixture baked in (assets-directory string, run-worker-
+// first boolean). Optionally `opts.simulate` is one of
+// 'mixed-shape' or 'empty-assets': the caller rewrites wrangler.toml
+// in a scratch copy for the simulate branches so the base fixture
+// stays honest.
+export async function scan(opts) {
+  const fixtureRoot = opts.fixtureRoot;
+  const elicited = opts.elicited || {};
+  const manifestPath = opts.manifestPath || join(fixtureRoot, 'wrangler.toml');
+  const text = await readFile(manifestPath, 'utf8');
+  const parsed = parseWranglerToml(text);
+  const results = [];
+  const detail = {
+    manifestPath,
+    parsed,
+    elicited: {
+      assetsDirectory: elicited['assets-directory'] || '',
+      runWorkerFirst: elicited['run-worker-first'] === true,
+    },
+  };
+
+  const assets = parsed.assets || null;
+  const answered = detail.elicited.assetsDirectory !== '';
+  if (answered) {
+    if (!assets) {
+      results.push({
+        verdict: 'fail',
+        detail: 'assets table absent: elicited assets-directory is "' + detail.elicited.assetsDirectory + '" but wrangler.toml carries no [assets] block',
+        anchorAcId,
+      });
+    } else if (assets.directory !== detail.elicited.assetsDirectory) {
+      results.push({
+        verdict: 'fail',
+        detail: 'assets.directory mismatch: wrangler.toml carries directory=' + JSON.stringify(assets.directory) + ' but elicited answer is ' + JSON.stringify(detail.elicited.assetsDirectory),
+        anchorAcId,
+      });
+    } else {
+      results.push({
+        verdict: 'pass',
+        detail: 'assets.directory equals elicited assets-directory answer ' + JSON.stringify(assets.directory),
+        anchorAcId,
+      });
+    }
+    const runWorkerFirstOnManifest = assets && Object.prototype.hasOwnProperty.call(assets, 'run_worker_first');
+    if (detail.elicited.runWorkerFirst) {
+      if (!runWorkerFirstOnManifest || assets.run_worker_first !== true) {
+        results.push({
+          verdict: 'fail',
+          detail: 'run_worker_first mismatch: elicited answer is true but manifest carries ' + (runWorkerFirstOnManifest ? String(assets.run_worker_first) : 'no run_worker_first key'),
+          anchorAcId,
+        });
+      } else {
+        results.push({
+          verdict: 'pass',
+          detail: 'assets.run_worker_first equals true, matching the elicited run-worker-first answer',
+          anchorAcId,
+        });
+      }
+    } else {
+      if (runWorkerFirstOnManifest && assets.run_worker_first !== false) {
+        results.push({
+          verdict: 'fail',
+          detail: 'run_worker_first mismatch: elicited answer is falsy but manifest carries run_worker_first=' + JSON.stringify(assets.run_worker_first),
+          anchorAcId,
+        });
+      } else {
+        results.push({
+          verdict: 'pass',
+          detail: 'assets.run_worker_first is absent (or false), matching the falsy elicited run-worker-first answer',
+          anchorAcId,
+        });
+      }
+    }
+  } else {
+    if (assets) {
+      results.push({
+        verdict: 'fail',
+        detail: 'assets table present without an elicited assets-directory answer: bare-Worker shape expected, wrangler.toml carries [assets] block',
+        anchorAcId,
+      });
+    } else {
+      results.push({
+        verdict: 'pass',
+        detail: 'no [assets] block on wrangler.toml, matching the bare-Worker shape (assets-directory elicit unanswered)',
+        anchorAcId,
+      });
+    }
+  }
+
+  const pagesFieldAtRoot = Object.prototype.hasOwnProperty.call(parsed, 'pages_build_output_dir');
+  const pagesFieldUnderAssets = assets && Object.prototype.hasOwnProperty.call(assets, 'pages_build_output_dir');
+  if (pagesFieldAtRoot || pagesFieldUnderAssets) {
+    results.push({
+      verdict: 'fail',
+      detail: 'mixed-shape drift: wrangler.toml carries pages_build_output_dir (' + (pagesFieldAtRoot ? 'top-level' : 'inside [assets]') + ') alongside the Workers-with-static-assets shape; the two are mutually exclusive per Cloudflare static-assets doc',
+      anchorAcId,
+    });
+  } else {
+    results.push({
+      verdict: 'pass',
+      detail: 'no pages_build_output_dir field on wrangler.toml (Workers-with-static-assets shape is exclusive of the Pages shape)',
+      anchorAcId,
+    });
+  }
+
+  const aggregateVerdict = results.some((r) => r.verdict === 'fail')
+    ? 'fail'
+    : results.some((r) => r.verdict === 'warn')
+      ? 'warn'
+      : 'pass';
+
+  return { verdict: aggregateVerdict, aggregateVerdict, anchorAcId, results, detail };
+}
+
+// Convenience for the run-shim: write a report file next to a
+// project-relative .rcf/reports/ path. Creates the directory if it
+// does not exist; the shim removes any scratch file it wrote to
+// simulate the mixed-shape or empty-assets branch before exit.
+export async function writeReport(reportPath, report) {
+  await mkdir(dirname(reportPath), { recursive: true });
+  await writeFile(reportPath, JSON.stringify(report, null, 2) + '\n', 'utf8');
+}
+
+export async function removeIfExists(path) {
+  try {
+    await rm(path, { force: true });
+  } catch (_err) {
+    // Nothing to clean.
+  }
+}
+
+export default { scan, writeReport, removeIfExists, parseWranglerToml, anchorAcId, accountBound };

package/blueprints/deploy-cloudflare-workers/contributions/requirements/deploy-cloudflare-workers-req-013.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-cloudflare-workers-REQ-013",
+  "prdId": "PRD-001",
+  "title": "Workers-with-static-assets shape: an [assets] directory declared under wrangler blesses static assets served by the Worker",
+  "description": "The blueprint blesses the Workers-with-static-assets deploy shape as the ratified SPA-on-Workers shape (per ADR-1306, quoting the Cloudflare Pages landing-page recommendation verbatim). A project answering the elicited `assets-directory` parameter with a non-empty path emits an `[assets]` block on `wrangler.toml` whose `directory` value carries the elicited path (for example `directory = \"./dist\"`). Cloudflare's Workers runtime serves files from that directory at the edge before the Worker fetch handler runs (unless `run_worker_first` is set truthy per REQ-014). A project answering with an empty path keeps the bare-Worker shape (no `[assets]` block, no static-asset lookup). The wrangler manifest MUST NOT carry any Pages-only field (`pages_build_output_dir`) alongside `[assets]`; the two shapes are mutually exclusive per Cloudflare's static-assets doc.",
+  "category": "technical",
+  "domain": "deploy",
+  "priority": "must",
+  "rationale": "Cloudflare's own Pages landing page tells new projects to start with Workers; the Workers-with-static-assets shape is the primary SPA-on-Workers deploy shape. Blessing it here means a rcf-lite project choosing SPA-on-Workers gets a single, ratified wrangler shape rather than a hand-rolled convention. The mutual exclusion of `[assets]` and `pages_build_output_dir` keeps a project from silently drifting into a mixed-shape wrangler that Cloudflare's runtime refuses at deploy time.",
+  "tags": [
+    "blueprint:deploy-cloudflare-workers",
+    "category:13-static-assets"
+  ],
+  "version": "1.2.0",
+  "status": "approved",
+  "createdAt": "2026-09-07T00:00:00Z",
+  "updatedAt": "2026-09-07T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/requirements/deploy-cloudflare-workers-req-014.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-cloudflare-workers-REQ-014",
+  "prdId": "PRD-001",
+  "title": "SPA fallback discipline: run_worker_first flips the assets pipeline off the fetch handler's critical path",
+  "description": "The blueprint elicits `run-worker-first` (boolean, default false) alongside the `[assets] directory` shape from REQ-013. When the operator answers truthy, the generated wrangler manifest emits `run_worker_first = true` under the `[assets]` block: Cloudflare's runtime runs the Worker's fetch handler BEFORE looking up a static asset for the requested path. That is the shape a SPA-on-Workers project uses when the Worker owns arbitrary routing or when the Worker's auth middleware must gate every path a static file could shadow. When the operator answers falsy or leaves the elicit unanswered, `run_worker_first` is absent from the manifest and Cloudflare's runtime looks up a static asset first, falling back to the Worker only when no asset matches. The Worker code and the guide teach both shapes; the elicit surface is one boolean, the wrangler shape is one line.",
+  "category": "technical",
+  "domain": "deploy",
+  "priority": "should",
+  "rationale": "The default (asset lookup first, Worker on miss) is right for a static-content-heavy project. The truthy branch is what keeps auth middleware from being silently bypassed by an unauthenticated request for a file the assets pipeline serves from the edge cache. Naming the discipline as its own REQ makes the shape trade legible; anchoring the elicit to a wrangler line keeps the choice observable in the applied project.",
+  "tags": [
+    "blueprint:deploy-cloudflare-workers",
+    "category:13-static-assets"
+  ],
+  "version": "1.2.0",
+  "status": "approved",
+  "createdAt": "2026-09-07T00:00:00Z",
+  "updatedAt": "2026-09-07T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/user-stories/deploy-cloudflare-workers-us-12113.json

@@ -0,0 +1,36 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12113",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-013",
+  "version": "1.2.0",
+  "status": "approved",
+  "title": "SPA-on-Workers deploy shape: [assets] block emitted with the elicited directory and the run_worker_first hint",
+  "asA": "operator deploying a SPA on Cloudflare Workers",
+  "iWant": "the generated wrangler.toml to carry an [assets] block whose directory matches my elicited answer and whose run_worker_first field carries my elicited SPA fallback choice",
+  "soThat": "my SPA-on-Workers project ships with a single, ratified wrangler shape and my static assets and my auth-gated routes both behave the way Cloudflare's runtime documents them",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12113-1",
+      "description": "Given the operator answers assets-directory with a non-empty path P at blueprint add, when the wrangler manifest generator emits wrangler.toml, then the manifest contains exactly one [assets] block whose directory field equals P (with the leading `./` preserved when the operator answered `./P`) and the manifest carries no pages_build_output_dir field. When the operator answers assets-directory with an empty string or leaves the elicit unanswered, the manifest carries no [assets] block and no pages_build_output_dir field. Anchored to TAC-1302-deploy-cloudflare-workers-wrangler-manifest; probed by assets-manifest-scan.mjs (source-tree scan against the applied fixture wrangler.toml) with anchorAcId AC-12113-1.",
+      "given": "an applied fixture whose operator answered assets-directory = ./dist at blueprint add",
+      "when": "the probe module assets-manifest-scan.mjs parses the fixture wrangler.toml",
+      "then": "the parsed structure contains an assets table whose directory string equals ./dist and no top-level pages_build_output_dir key; the probe returns verdict pass",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12113-2",
+      "description": "Given the operator answers run-worker-first with true alongside a non-empty assets-directory, when the manifest is generated, then the [assets] block carries run_worker_first = true. Given the operator answers run-worker-first with false or leaves it unanswered, when the manifest is generated, then the [assets] block does NOT carry a run_worker_first key (Cloudflare's runtime treats the absent field as the default asset-lookup-first shape). Anchored to TAC-1302; probed by assets-manifest-scan.mjs with anchorAcId AC-12113-1 (the same module surfaces both facets of the shape).",
+      "given": "an applied fixture whose operator answered assets-directory = ./dist and run-worker-first = true",
+      "when": "the probe module parses the fixture wrangler.toml",
+      "then": "the parsed [assets] table carries run_worker_first equal to true; when the fixture is switched with SIMULATE_EMPTY_ASSETS=true the run_worker_first field is absent (the whole [assets] block is absent) and the probe still returns verdict pass because the bare-Worker shape is legal",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1302-deploy-cloudflare-workers-wrangler-manifest"
+  ],
+  "createdAt": "2026-09-07T00:00:00Z",
+  "updatedAt": "2026-09-07T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/user-stories/deploy-cloudflare-workers-us-12114.json

@@ -0,0 +1,27 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12114",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-013",
+  "version": "1.2.0",
+  "status": "approved",
+  "title": "assets-directory elicitation: the operator picks the static-assets root at blueprint add",
+  "asA": "operator applying deploy-cloudflare-workers on a fresh project",
+  "iWant": "the blueprint to prompt me for the static-assets directory at blueprint add and remember my answer on my project's sidecar so re-apply picks it back up",
+  "soThat": "my wrangler.toml reflects my project's build output shape without me having to hand-edit the [assets] block",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12114-1",
+      "description": "The blueprint.json elicits[] block declares an entry with id assets-directory, kind string, default empty. The blueprint loader accepts the entry (validateElicits shape gate on src/blueprint/loader.js). The CLI accepts --answer assets-directory=<path> at blueprint add; the applied sidecar records the answered value on appliedElicitations.assets-directory. When the operator does not pass --answer assets-directory, the effective value is the empty-string default and the wrangler generator emits no [assets] block.",
+      "given": "a fresh rcf init scratch project after rcf define blueprint add ./blueprints/deploy-cloudflare-workers --answer assets-directory=./public --answer run-worker-first=false",
+      "when": "the applied sidecar records the operator's answers and a wrangler.toml is generated",
+      "then": "appliedElicitations.assets-directory equals ./public; the generated wrangler.toml carries [assets] directory = \"./public\" and no run_worker_first field; the manifest carries no pages_build_output_dir field",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1302-deploy-cloudflare-workers-wrangler-manifest"
+  ],
+  "createdAt": "2026-09-07T00:00:00Z",
+  "updatedAt": "2026-09-07T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/user-stories/deploy-cloudflare-workers-us-12115.json

@@ -0,0 +1,27 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12115",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-014",
+  "version": "1.2.0",
+  "status": "approved",
+  "title": "Migrate-from-Pages guidance: the guide links Cloudflare's own migrate-from-Pages walkthrough and pins the ratified shape choice",
+  "asA": "operator on a Cloudflare Pages project deciding whether to migrate",
+  "iWant": "the blueprint's guide to name the Workers-with-static-assets shape as the ratified default, quote Cloudflare's own landing-page recommendation verbatim, and link the migrate-from-Pages walkthrough Cloudflare publishes",
+  "soThat": "I can read the decision, the standards trace and the migration path in one place without stitching them together from three vendor pages",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12115-1",
+      "description": "The guide file blueprints/deploy-cloudflare-workers/guide/deploy-cloudflare-workers.md gains one new section titled Workers-with-static-assets: the SPA-on-Workers shape. The section carries the verbatim Cloudflare Pages landing-page quote (Workers supports most Pages use cases and offers a broader feature set. It is Cloudflare's primary platform for building applications. Start new projects with Workers.), the two elicit signatures (assets-directory string default empty; run-worker-first boolean default false), a copy-paste wrangler.toml snippet showing the [assets] block with directory and the run_worker_first hint, and a link to the Cloudflare migrate-from-Pages guide at https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/. The Cloudflare Workers static-assets doc at https://developers.cloudflare.com/workers/static-assets/ is cited in the same section. Both URLs return HTTP 200 at gate time.",
+      "given": "the updated guide file on the T-0 branch",
+      "when": "a reader opens the guide and grep locates the section heading, the verbatim quote and the two URLs",
+      "then": "the section heading appears once; the verbatim landing-page quote appears once; both Cloudflare URLs appear at least once each; a curl -fsSI on each URL returns HTTP 200",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": [
+    "TAC-1302-deploy-cloudflare-workers-wrangler-manifest"
+  ],
+  "createdAt": "2026-09-07T00:00:00Z",
+  "updatedAt": "2026-09-07T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/docs/topics.md

@@ -32,14 +32,14 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
 | security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
 | security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
-| deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
+| deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.2.0 | `deploymentTarget` |
 | persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
 | observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.1.0 | `healthProbes`, `readinessSemantics` |
 | application-datatable | 17101-17899 | 18xx | shipped v1.0.0 | none |
 | application-charts | 18101-18899 | 19xx | shipped v1.0.0 | none |
 | application-dashboard | 19101-19899 | 20xx | shipped v1.0.0 | none |
 | application-notifications-in-app | 20101-20899 | 21xx | shipped v1.0.0 | none |
-| application-admin-console | 21101-21899 | 22xx | shipped v1.0.0 | none |
+| application-admin-console | 21101-21899 | 22xx | shipped v1.1.0 | `adminConsoleSignInSurface` |
 | application-empty-error-states | 22101-22899 | 23xx | shipped v1.0.0 | none |
 | application-file-upload | 23101-23899 | 24xx | shipped v1.0.0 | none |
 | application-forms-wizard | 24101-24899 | 25xx | shipped v1.0.0 | none |
@@ -47,6 +47,14 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | application-onboarding-tour | 26101-26899 | 27xx | shipped v1.0.0 | none |
 | persistence-data-postgres | 27101-27899 | 28xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
 | object-storage-s3 | 28101-28899 | 29xx | shipped v1.0.0 | `objectStorageContract` |
+| messaging-queue-cloudflare | 29101-29899 | 30xx | shipped v1.0.0 | `deliverySemantics` |
+| jobs-background | 30101-30899 | 31xx | shipped v1.0.0 | `backgroundJobModel` |
+| platform-cloudflare-kv | 31101-31899 | 32xx | shipped v1.0.0 | `keyValueStoreContract` |
+| platform-cloudflare-cron-triggers | 32101-32899 | 33xx | shipped v1.0.0 | `scheduledTriggerContract` |
+| platform-cloudflare-durable-objects | 33101-33899 | 34xx | shipped v1.0.0 | `strongConsistencyCellContract`, `websocketHubContract` |
+| edge-cloudflare-access | 34101-34899 | 35xx | shipped v1.0.0 | `edgeAuthenticationGate` |
+| edge-cloudflare-turnstile | 35101-35899 | 36xx | shipped v1.0.0 | `humanVerificationGate` |
+| edge-cloudflare-rate-limiting | 36101-36899 | 37xx | shipped v1.0.0 | `edgeThrottleContract` |
 
 US 12101-12112 sit at the LOW end of the 12101-12899 band on purpose. A project-side story that mechanically derives from a deploy-cloudflare-workers REQ id into the number `12112` would collide against deploy-cloudflare-workers-US-12112 in this package; the band leaves headroom at the HIGH end (US 12181-12899) so a project's own stories anchored to deploy-cloudflare-workers REQs can allocate without conflict. The watchpost run4 lesson applies here too. Band spacing between the last shipped block (security-secrets-management, 8101-8899, 9xx) and this one (12101-12899, 13xx) leaves the 9xxx-11xxx US bands and the 10xx-12xx suffix blocks open for concurrent-lane authoring so a peer authoring another blueprint in the same PR window does not collide with this one.
 

package/blueprints/deploy-cloudflare-workers/guide/deploy-cloudflare-workers.md

@@ -72,3 +72,28 @@ A project applies the blueprint on a fresh tree, declares its Worker in `wrangle
 ## Cost-honesty paragraph
 
 Shipping this doc set costs the project the following. Every ship to production is now a two-step act (merge to main, then an operator-triggered promote) instead of a single-step merge-to-production; the discipline is intentional and adds a small friction to prototype-shaped work where merge-to-production is fine. The default Cloudflare Workers vendor commits the project to an edge-runtime shape; a project whose runtime needs a long-lived process cannot use the default and has to supersede ADR-1302. The served-surface verifier fails CI on real drift; a project that wants faster promotes buys them by tightening the probe set or by accepting a larger risk of a failed promote, neither is free. The three URL kinds (per-version-id, stable alias, production) are three hostnames the project has to reason about; a project that would rather have one hostname loses the class of leaks-through-collapsed-URL the blueprint's ADR-1303 closes. The wrangler manifest becomes a piece of documentation the project maintains as part of its normal change flow; a project that would rather push deploy config into ad-hoc shell scripts loses the manifest's own validation gate. The deploy-log record is a stream the project now maintains; wiring it to a real sink (a status page, a SIEM, a data warehouse) is a project cost the blueprint does not carry. The blueprint says nothing about the vendor's own dashboard workflows, about DNS and TLS provisioning outside the vendor's own custom-hostname primitive, about compliance reporting on deploy events, or about staged canary or blue-green rollouts; a project that needs any of those spends its own build cycles on them and this blueprint does not save it any work there.
+
+## Workers-with-static-assets: the SPA-on-Workers shape
+
+Cloudflare's own Pages landing page states, verbatim (fetched 2026-09-06): "Workers supports most Pages use cases and offers a broader feature set. It is Cloudflare's primary platform for building applications. Start new projects with Workers." The `deploy-cloudflare-workers` v1.2.0 bump follows the recommendation: new SPA-on-Workers projects apply this blueprint in the Workers-with-static-assets shape rather than reaching for Cloudflare Pages. `ADR-1306-deploy-cloudflare-workers-spa-shape` is the ratified decision and carries the verbatim quote on its body plus the standards trace on the contribution entry (`standardsTraceClause: Cloudflare Pages landing-page recommendation (2026-09-06)`). Cloudflare's Workers static-assets docs at `https://developers.cloudflare.com/workers/static-assets/` are the operational reference for the shape; the migrate-from-Pages walkthrough at `https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/` is the path for a project on Pages that wants to jump.
+
+The bump adds two elicits on the top-level `elicits[]` block:
+
+- `assets-directory` (kind `string`, default empty): the path (relative to the Worker source root) whose files Cloudflare serves at the edge as static assets. An empty answer keeps the bare-Worker shape (no `[assets]` block on the generated `wrangler.toml`); a non-empty answer emits `[assets] directory = "<answered path>"`.
+- `run-worker-first` (kind `boolean`, default `false`): the SPA fallback discipline. A truthy answer emits `run_worker_first = true` under the `[assets]` block; a falsy or unanswered answer omits the field, leaving Cloudflare's runtime to serve a matching static asset before the Worker fetch handler runs. The elicit is only meaningful when `assets-directory` is non-empty (a Worker with no assets has nothing to serve first); the loader-side `when-elicitedNonEmpty` predicate the spec calls for is a mechanism follow-up, so the elicit fires unconditionally today.
+
+Copy-paste `wrangler.toml` snippet for the ratified shape:
+
+```
+name = "my-spa-worker"
+main = "src/index.mjs"
+compatibility_date = "2026-09-06"
+
+[assets]
+directory = "./dist"
+run_worker_first = true
+```
+
+The `[assets]` block and Pages' `pages_build_output_dir` field are mutually exclusive per Cloudflare's static-assets doc; the T-0 probe `assets-manifest-scan.mjs` (`accountBound: false`, `anchorAcId: AC-12113-1`) refuses on a manifest that carries both. A project on the bare-Worker shape (no static assets served at the edge) leaves both elicits unanswered and the probe reports the bare shape as passing.
+
+Migrating from Cloudflare Pages: read Cloudflare's own walkthrough at `https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/`, apply this blueprint at v1.2.0 with `assets-directory` set to the build-output directory the Pages project pointed at (typically `./dist`, `./build`, or `./public`), pick `run-worker-first` per the project's routing shape, and drop the Pages workflow. The Workers-with-static-assets shape covers the SPA and API surfaces the Pages workflow covered; the promote and rollback verbs on this blueprint carry through unchanged.

package/blueprints/edge-cloudflare-access/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to `edge-cloudflare-access` are recorded here. The shape follows Keep a Changelog and Semantic Versioning per the blueprint authoring standard.
+
+## 1.0.0 (2026-09-07)
+
+### Added
+
+- v1.0.0 mint of the `edge-cloudflare-access` blueprint, category `edge`, capabilities `["zeroTrustGate"]`. Ships a shipped JWT validator middleware that is the sole reader of the `Cf-Access-Jwt-Assertion` header per REQ-001, an Access application declaration surface with elicited hostname or self-hosted-app id, an elicited policy shape from the enum (email-domain, service-token-only, service-token-plus-email-domain, group-membership), a metadata-only audit event contract per REQ-004, and a break-glass posture per REQ-005 with an elicited service-auth pair for CI-signed automation.
+- 6 REQs (`edge-cloudflare-access-REQ-001..006`), 9 USs (`edge-cloudflare-access-US-34101..34109`), 4 TACs (`TAC-3501` JWT validator, `TAC-3502` Access application declaration, `TAC-3503` policy shape enum, `TAC-3504` audit sink), 4 ADRs (`ADR-3501` scope-global on new topic `edgeAuthenticationGate` with `standardsTraceClause: Cloudflare Access policy actions and rule selectors`; `ADR-3502` identity provider elicited with `recommendedDefault: null`; `ADR-3503` policy scope elicited with `recommendedDefault: application-level`; `ADR-3504` audit retention delegated to the applied logging companion with sentinel clause).
+- 6 Node-only probes under `contributions/probes/`: `jwt-validator-fixture` (fixture-signed JWT validates and principal reduces to `{email, sub, groups}` on request.auth), `jwt-validator-reject` (three subcases: missing header, expired exp, mis-signed each return 401 with one metadata-only audit event), `admin-console-gate-surface` (extended admin-console fixture flips its sign-in surface per applied capability set; covers `AC-34108-1`), `audit-event-secrecy` (5 pass + 5 reject runs produce 10 metadata-only records with no forbidden substrings, no token slices, no header names beyond `path`), `real-account-gated-url` (`accountBound: true`; records `accountBoundSkipped: true` in CI without `CI_HAS_CLOUDFLARE_ACCOUNT` per spec section 3.5) and `wrangler-seam` (drives `wrangler dev --local` on the fixture; `/protected` returns HTTP 401 on the shipped validator's missing-header reject path; `/health` returns HTTP 200 exempt; warn semantics per section 3.1 pass-with-skip if wrangler is missing or fails to bind).
+- 6 elicited parameters on `blueprint.json`: `access-application-host` (or `access-selfhosted-app-id`, exactly one required), `access-audience`, `access-jwks-url`, `access-policy-shape` (enum default `email-domain`), `access-bypass-service-auth-id` (blank disables break-glass).
+- `suggestedCompanions`: `logging` (for the metadata-only audit sink retention), `errorHandling` (for the validator failure boundary) and `secretsManagement` (for the paired break-glass service-auth secret).
+- Ships the shared `cf-edge` sample-app fixture at `packages/rcf-lite/test/fixtures/cf-edge/` (T-4 mints it per spec section 3.3). The fixture ships the applied Worker (`src/index.mjs`), the JWT validator (`src/jwt-validator.mjs`, sole reader of the `Cf-Access-Jwt-Assertion` header), a dependency-free RS256 fixture-JWT signer (`test/jwt-signer.mjs`) and a local JWKS server (`test/jwks-server.mjs`). No new rcf-lite runtime dependency (Node's built-in `crypto` module signs and verifies).
+- Extends `packages/rcf-lite/test/fixtures/probe-pack-application-admin-console/` with a `/admin/sign-in` route rendering the Access-gated surface (with `?caps=zeroTrustGate`) or the local-login surface (without). The extension rides `application-admin-console` v1.1.0.
+- Anatomy test at `packages/rcf-lite/test/blueprint/edge-cloudflare-access-anatomy.test.js` covers `TS-110..119` on the T-4 chain slice (blueprint shape, contributions cross-check, JWT validator behaviour, sole-reader guarantee, audit-event secrecy, break-glass posture, admin-console composition, fixture files, ADR bodies and clauses, guide sections and vendor URL).
+
+### Known limitations
+
+- The `real-account-gated-url` probe records `accountBoundSkipped: true` and aggregates to `pass` when `CI_HAS_CLOUDFLARE_ACCOUNT` or `CF_ACCESS_HOST` are unset (spec section 3.5 pass-with-skip). Full mechanism reach requires a CI environment with both env vars set and a deployed hostname behind an issued Zero Trust policy.
+- The v1.0.0 boundary defers per-path policy scope authoring, group-membership rule authoring and identity-provider federation to v1.1.0. The shipped validator observes the JWT's `groups` claim but does not enforce policy on it (the Cloudflare edge enforces before the request reaches the origin Worker); a future minor could ship a group-membership refinement.
+- The `wrangler-seam` probe warns (never fails) when `wrangler` is not installed under `packages/rcf-lite/test/fixtures/cf-edge/node_modules/.bin/wrangler`; a handler thrown at the workerd boundary is a genuine fail per the round-6 T-3 gate directive.
+- The Access-gated sign-in surface on `application-admin-console` v1.1.0 shows a placeholder principal email in the fixture (supplied via `?principalEmail=` or `ADMIN_CONSOLE_PRINCIPAL_EMAIL` env var). In a real deployment the principal reads from `request.auth.email` the JWT validator attaches; the fixture does not embed the validator (it renders the surface).

package/blueprints/edge-cloudflare-access/README.md

@@ -0,0 +1,141 @@
+# edge-cloudflare-access
+
+A rcf-lite blueprint that ships an opinionated wiring for Cloudflare
+Access as the edge authentication gate on a Workers project. One
+JWT validator middleware sits at the top of every fetch handler,
+verifies the JWT Cloudflare Access mints against the JWKS the
+service publishes, and reduces the principal onto `request.auth` as
+`{email, sub, groups}`. Every audit event carries only
+`{email, outcome, timestamp, path}`; no token slice, no header
+value beyond `path` ever leaves the validator boundary.
+
+- Version: `1.0.0`
+- Category: `edge`
+- Capabilities: `["zeroTrustGate"]`
+- Suggested companions: `logging`, `errorHandling`, `secretsManagement`
+
+## When to reach for it
+
+- Any Cloudflare Workers project that needs an authenticated edge
+  (only authenticated principals reach the origin Worker).
+- Any project that has adopted the Zero Trust posture and wants a
+  vendor-neutral seam (`request.auth`) between the edge and the
+  downstream handler.
+- Compose with `application-admin-console` v1.1.0 for the Access-gated
+  sign-in surface (round-4 T-4 capability-minor pattern).
+
+## The six REQs
+
+| REQ | What |
+| --- | --- |
+| `edge-cloudflare-access-REQ-001` | The JWT validator is the sole reader of the `Cf-Access-Jwt-Assertion` header and reduces the principal onto `request.auth`. |
+| `edge-cloudflare-access-REQ-002` | An Access application is declared with an elicited hostname or self-hosted-app id and an elicited policy shape from the enum. |
+| `edge-cloudflare-access-REQ-003` | The operator issues a Zero Trust policy via the guide's dashboard walk-through or the alternative API path. |
+| `edge-cloudflare-access-REQ-004` | The audit event carries only `{email, outcome, timestamp, path}` with no token value or headers. |
+| `edge-cloudflare-access-REQ-005` | Break-glass posture: an elicited bypass-service-auth pair authenticates CI automation. |
+| `edge-cloudflare-access-REQ-006` | Composition with `application-admin-console` v1.1.0: the sign-in surface flips per applied capability set. |
+
+## The wired shape
+
+The validator is the one place the `Cf-Access-Jwt-Assertion` header
+is read. Consumers reach the reduced principal via `request.auth`.
+The public surface is:
+
+```
+createAccessValidator({ env, eventSink, fetch?, clock?, bypassServiceAuth? })
+  -> { validate, middleware }
+```
+
+Where `env` carries the elicited `ACCESS_JWKS_URL` and `ACCESS_AUDIENCE`.
+The `middleware(request, envSwitches?)` returns either
+`{rejected: true, response, outcome}` for a 401 rejection or
+`{rejected: false, outcome}` after attaching `request.auth` in place.
+
+## Elicited parameters
+
+- `access-application-host` OR `access-selfhosted-app-id`: pick
+  exactly one at apply. The dashboard walk-through follows the
+  hostname path when the first is set and the self-hosted-app id
+  path when the second is set.
+- `access-audience`: the JWT audience tag the Access policy issues
+  the validator refuses tokens whose `aud` claim does not match.
+- `access-jwks-url`: the JWKS endpoint URL the validator fetches.
+  Cloudflare Access publishes this at
+  `https://<team>.cloudflareaccess.com/cdn-cgi/access/certs`.
+- `access-policy-shape` (default `email-domain`): one of
+  `email-domain`, `service-token-only`,
+  `service-token-plus-email-domain`, `group-membership`. Drives
+  the guide walk-through and the API alternative.
+- `access-bypass-service-auth-id`: leave blank to disable
+  break-glass. When set, the paired secret is delegated to the
+  applied `secretsManagement` companion via
+  `security-secrets-management`.
+
+## The six probes
+
+The probes live under `contributions/probes/`. Each has a matching
+`run-<probe-name>.mjs` shim that writes a per-blueprint report to
+`.rcf/reports/blueprints/edge-cloudflare-access/<probe-name>.json`
+under the fixture root.
+
+| Probe | anchorAcId | accountBound | What it covers |
+| --- | --- | --- | --- |
+| `jwt-validator-fixture.mjs` | `AC-34101-1` | false | Fixture-signed JWT validates; principal reduces to `{email, sub, groups}` on request.auth; one audit event with `outcome: validated` and allowed keys only. |
+| `jwt-validator-reject.mjs` | `AC-34102-1` | false | Three subcases: missing header, expired exp, mis-signed each return HTTP 401 with exactly one audit event whose keys are drawn from the allowed set; outcomes: `missing`, `expired`, `invalid`. |
+| `admin-console-gate-surface.mjs` | `AC-34108-1` | false | The extended admin-console fixture flips the sign-in surface: with `?caps=zeroTrustGate` it renders `[data-surface=access-gated]`; without it renders `[data-surface=local-login]`. Mutually exclusive on both branches. |
+| `audit-event-secrecy.mjs` | `AC-34106-1` | false | After 5 pass + 5 reject runs, the audit sink holds 10 metadata-only records; the serialised sink contains no substring of any JWT (or its segments) and no header names beyond `path`. |
+| `real-account-gated-url.mjs` | `AC-34109-1` | true | Fetch against a scheduled Access-configured hostname (`CF_ACCESS_HOST`) with `CI_HAS_CLOUDFLARE_ACCOUNT=true` follows the redirect chain to a `<team>.cloudflareaccess.com` URL. Records `accountBoundSkipped: true` without both env vars (pass-with-skip). |
+| `wrangler-seam.mjs` | `AC-34101-1` | false | Spawns `wrangler dev --local` on the cf-edge fixture. `/protected` returns HTTP 401 on the shipped validator's missing-header reject path (workerd boundary); `/health` returns HTTP 200 exempt. Warn semantics per section 3.1 pass-with-skip if wrangler is missing or fails to bind; a handler thrown at the workerd boundary is a fail. |
+
+## Mechanism-reach note
+
+- `AC-34101-1` (fixture JWT validate) and `AC-34102-1` (reject) are
+  covered by the in-process probes plus the wrangler-seam probe
+  under workerd.
+- `AC-34103-1` (sole-reader guarantee) is covered by the anatomy
+  test that greps `src/**/*.mjs` for the header string.
+- `AC-34104-1` (Access application declaration) is covered by the
+  anatomy test that reads `blueprint.json` for the elicits[] shape.
+- `AC-34105-1` (guide dashboard walk-through and API alternative)
+  is covered by the anatomy test that greps the shipped guide file
+  for the two section headings and the vendor URL.
+- `AC-34106-1` (audit metadata secrecy) is covered by the
+  `audit-event-secrecy` probe.
+- `AC-34107-1` (break-glass posture) is covered by the anatomy
+  test that drives the validator with an elicited pair.
+- `AC-34108-1` (admin-console composition) is covered by the
+  `admin-console-gate-surface` probe (both branches) and by the
+  shipped `application-admin-console.pack.mjs` pack check
+  `AC-21815-1` (Playwright-driven on the extended fixture).
+- `AC-34109-1` (real-account gated URL) is covered by the
+  `real-account-gated-url` probe (skipped in CI without both env
+  vars per section 3.5).
+
+## Two-line gate-reviewer boot
+
+```
+cd packages/rcf-lite/test/fixtures/cf-edge
+pnpm install --ignore-workspace
+```
+
+Then run every probe:
+
+```
+node ../../../../../blueprints/edge-cloudflare-access/contributions/probes/run-jwt-validator-fixture.mjs
+node ../../../../../blueprints/edge-cloudflare-access/contributions/probes/run-jwt-validator-reject.mjs
+node ../../../../../blueprints/edge-cloudflare-access/contributions/probes/run-audit-event-secrecy.mjs
+node ../../../../../blueprints/edge-cloudflare-access/contributions/probes/run-admin-console-gate-surface.mjs
+node ../../../../../blueprints/edge-cloudflare-access/contributions/probes/run-real-account-gated-url.mjs
+node ../../../../../blueprints/edge-cloudflare-access/contributions/probes/run-wrangler-seam.mjs
+```
+
+Each probe prints a report envelope and writes it to
+`.rcf/reports/blueprints/edge-cloudflare-access/<probe-name>.json`.
+
+## Composition companion
+
+- `application-admin-console` v1.1.0 consumes `zeroTrustGate`
+  optionally: the admin-console's sign-in surface renders
+  Access-gated when `zeroTrustGate` is in the applied set (and
+  falls back to `security-auth-*` local login otherwise). The
+  v1.1.0 minor rides this PR (round-4 T-4 capability-minor pattern).