Add deprecation getters for Astro.locals.runtime (#15075)

* feat(cloudflare): add deprecation getters for Astro.locals.runtime

Adds helpful error messages when accessing removed runtime properties:
- runtime.env -> import { env } from 'cloudflare:workers'
- runtime.cf -> Astro.request.cf
- runtime.caches -> global caches object
- runtime.ctx -> Astro.locals.cfContext

Improves migration experience from v5 to v6.

* chore: add changeset for runtime deprecation helpers

* Update .changeset/helpful-runtime-errors.md

Co-authored-by: Armand Philippot <[email protected]>

* fix(cloudflare): hide runtime from types and enumeration

- Remove runtime from Runtime interface to prevent autocomplete
- Use Object.defineProperty with enumerable: false

---------

Co-authored-by: Armand Philippot <[email protected]>

Author: matthewp

.changeset/helpful-runtime-errors.md

@@ -0,0 +1,12 @@
+---
+'@astrojs/cloudflare': patch
+---
+
+Adds deprecation errors for `Astro.locals.runtime` properties to help migrate from Astro v5 to v6
+
+When accessing the removed `Astro.locals.runtime` properties on Cloudflare, developers now receive clear error messages explaining the migration path:
+
+- `Astro.locals.runtime.env` → Use `import { env } from "cloudflare:workers"`
+- `Astro.locals.runtime.cf` → Use `Astro.request.cf`
+- `Astro.locals.runtime.caches` → Use the global `caches` object
+- `Astro.locals.runtime.ctx` → Use `Astro.locals.cfContext`

packages/integrations/cloudflare/src/utils/handler.ts

@@ -59,6 +59,31 @@ export async function handle(
 	const locals: Runtime = {
 		cfContext: context,
 	};
+	Object.defineProperty(locals, 'runtime', {
+		enumerable: false,
+		value: {
+			get env(): never {
+				throw new Error(
+					`Astro.locals.runtime.env has been removed in Astro v6. Use 'import { env } from "cloudflare:workers"' instead.`,
+				);
+			},
+			get cf(): never {
+				throw new Error(
+					`Astro.locals.runtime.cf has been removed in Astro v6. Use 'Astro.request.cf' instead.`,
+				);
+			},
+			get caches(): never {
+				throw new Error(
+					`Astro.locals.runtime.caches has been removed in Astro v6. Use the global 'caches' object instead.`,
+				);
+			},
+			get ctx(): never {
+				throw new Error(
+					`Astro.locals.runtime.ctx has been removed in Astro v6. Use 'Astro.locals.cfContext' instead.`,
+				);
+			},
+		},
+	});
 
 	const response = await app.render(
 		request as Request & Parameters<ExportedHandlerFetchHandler>[0],