feat: Astro Sanity data layer and consolidated typegen

Adds apps/site/src/lib/sanity/* and converts all 26 GROQ queries from
`groq` tagged templates to `defineQuery`, so generated types flow to call sites
and the `as` casts the Next app needed are gone.

Two assumptions from the migration plan turned out to be wrong, and were
verified empirically before committing to a layout:

- TypeGen DOES resolve const interpolation inside defineQuery, including across
  module boundaries. The shared projection partials (baseFieldsNoContent,
  contentFields, ...) are therefore kept in queries/shared.ts rather than being
  inlined into every query.
- @astrojs/cloudflare v14 reduced `Runtime` to `{ cfContext }` and marks
  `locals.runtime` a deprecated getter. Bindings and vars are read via
  `import { env } from "cloudflare:workers"` instead — which is also what the
  pre-Next Astro app did.

Three bugs in the harvested fetch layer (dev:apps/web/src/utils/sanity.ts) are
fixed rather than carried over:

- `useCdn: false` on the base client. Under Next this was masked by ISR; under
  pure SSR it would put every anonymous page view on the uncached live API.
  Published reads now use the CDN, which Sanity purges on publish.
- stega configured on the base client and suppressed per-request. Inverted:
  off by default, on only in previewClient, so RSS/sitemap/OG/JSON-LD cannot
  leak zero-width characters into hrefs and XML.
- read token sourced from `import.meta.env`, which Vite inlines into the server
  bundle — that would bake the token into the deployed Worker script. Now read
  per-request from the runtime env, and preview fails closed when absent.

Config is resolved per-request because wrangler `vars` reach the Worker through
the runtime env, not `import.meta.env`. apiVersion is pinned to 2025-09-30 to
match apps/sanity/sanity.config.ts; the old Astro app used 2026-03-17, a silent
divergence between what authors preview in Vision and what the site renders.

Middleware builds the request context onto `locals.sanity` and sets
`no-store, private` + `noindex` on preview responses, so a page containing
unpublished drafts cannot be written to the edge cache.

Queries that took a $type parameter (docCount, rssQuery) are split per type —
a parameterised _type widens the generated result to a union of every document
type. urlForImage is consolidated to one implementation keeping the
`.auto("format")` behaviour; resolveHref now covers the whole public route map
instead of only "post".

Typegen moves entirely into apps/sanity: apps/web/sanity.cli.ts is deleted along
with its typegen/predev/prebuild scripts and its `sanity` devDependency, and the
two stale schema copies (apps/web/sanity/extract.json, apps/web/schema.json) are
removed. CI regenerates types before typechecking and fails if the committed
extract.json has drifted.

Verified end to end: `wrangler dev` serves the home page with real Sanity
content from the dev dataset, typechecking clean with no casts.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HZ4S1uTJwFdbv3A6PHWfw2

Author: codercatdev

.github/workflows/ci.yml

@@ -27,6 +27,15 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      # Generates apps/sanity/extract.json and the site's types.gen.ts, both of
+      # which are derived artifacts and therefore gitignored. Runs before
+      # typecheck because the site imports the generated types.
+      - name: Typegen
+        run: pnpm typegen
+        env:
+          SANITY_STUDIO_PROJECT_ID: hfh83o0w
+          SANITY_STUDIO_DATASET: production
+
       - name: Lint (site)
         run: pnpm --filter @codingcatdev/site lint
 
@@ -45,17 +54,13 @@ jobs:
           SANITY_STUDIO_PROJECT_ID: hfh83o0w
           SANITY_STUDIO_DATASET: production
 
-      # extract.json is the single source of truth for typegen. If it drifts
-      # from the schema, generated types silently go stale — which is how three
-      # divergent copies accumulated before.
+      # extract.json is committed and is the single source of truth for typegen.
+      # The Typegen step above regenerates it; if that changed the file, the
+      # commit is stale. This is what stopped three divergent copies before.
       - name: Verify extract.json is current
         run: |
-          pnpm --filter @codingcatdev/sanity typegen:extract
           if ! git diff --quiet -- apps/sanity/extract.json; then
             echo "::error::apps/sanity/extract.json is stale. Run 'pnpm typegen' and commit the result."
             git diff --stat -- apps/sanity/extract.json
             exit 1
           fi
-        env:
-          SANITY_STUDIO_PROJECT_ID: hfh83o0w
-          SANITY_STUDIO_DATASET: production

apps/sanity/package.json

@@ -7,7 +7,7 @@
     "build": "sanity build",
     "deploy": "sanity deploy",
     "typegen:extract": "sanity schema extract --path=./extract.json --workspace production --force",
-    "typegen": "pnpm run typegen:extract"
+    "typegen": "pnpm run typegen:extract && sanity typegen generate"
   },
   "dependencies": {
     "@portabletext/block-tools": "^5.2.0",

apps/sanity/sanity.cli.ts

@@ -7,4 +7,12 @@ export default defineCliConfig({
   },
   // Set via SANITY_STUDIO_HOSTNAME in CI: e.g. "codingcat.dev" (prod), "codingcat-dev" (dev)
   studioHost: process.env.SANITY_STUDIO_HOSTNAME,
+  typegen: {
+    // Queries must live in .ts files — TypeGen cannot parse .astro frontmatter,
+    // so defineQuery calls inside .astro are silently skipped.
+    path: "../site/src/lib/sanity/queries/**/*.ts",
+    schema: "./extract.json",
+    generates: "../site/src/lib/sanity/types.gen.ts",
+    overloadClientMethods: true,
+  },
 });

apps/site/package.json

@@ -33,6 +33,7 @@
     "@astrojs/check": "^0.9.10",
     "@biomejs/biome": "2.2.4",
     "@tailwindcss/typography": "^0.5.19",
+    "@types/node": "^24.12.4",
     "typescript": "^5.9",
     "wrangler": "^4.123.0"
   }

apps/site/src/env.d.ts

@@ -0,0 +1,7 @@
+/// <reference path="../.astro/types.d.ts" />
+
+declare namespace App {
+	interface Locals {
+		sanity: import("./lib/sanity/context").SanityRequestContext;
+	}
+}

apps/site/src/lib/sanity/client.ts

@@ -0,0 +1,70 @@
+import {
+	type ClientPerspective,
+	createClient,
+	type SanityClient,
+} from "@sanity/client";
+import type { SanityConfig } from "./config";
+
+/**
+ * Clients are memoized per (config, mode) for the life of the isolate. Workers
+ * reuses isolates across requests, so this avoids rebuilding a client per hit
+ * while still letting config come from the request.
+ */
+const cache = new Map<string, SanityClient>();
+
+function memo(key: string, make: () => SanityClient): SanityClient {
+	let client = cache.get(key);
+	if (!client) {
+		client = make();
+		cache.set(key, client);
+	}
+	return client;
+}
+
+/**
+ * Anonymous, published-only reads.
+ *
+ * `useCdn: true` is the single highest-leverage setting here. There is no
+ * Next-style cache layer under SSR on Workers, so every request would otherwise
+ * hit the uncached live API. apicdn is purged by Sanity on publish, so content
+ * is still fresh within seconds.
+ *
+ * stega is OFF here and enabled only in previewClient. Encoded zero-width
+ * characters are harmless in text nodes but corrupt hrefs, <meta> content,
+ * JSON-LD and XML feeds — defaulting it off fails safe.
+ */
+export function publishedClient(config: SanityConfig): SanityClient {
+	const { projectId, dataset, apiVersion } = config;
+	return memo(`pub:${projectId}:${dataset}:${apiVersion}`, () =>
+		createClient({
+			projectId,
+			dataset,
+			apiVersion,
+			useCdn: true,
+			perspective: "published",
+			stega: false,
+		}),
+	);
+}
+
+/** Authenticated draft/preview reads, with stega and source maps enabled. */
+export function previewClient(
+	config: SanityConfig,
+	token: string,
+	perspective: ClientPerspective,
+): SanityClient {
+	const { projectId, dataset, apiVersion, studioUrl } = config;
+	const key = `prev:${projectId}:${dataset}:${apiVersion}:${String(perspective)}`;
+	return memo(key, () =>
+		createClient({
+			projectId,
+			dataset,
+			apiVersion,
+			useCdn: false,
+			perspective,
+			token,
+			resultSourceMap: "withKeyArraySelector",
+			stega: { enabled: true, studioUrl },
+		}),
+	);
+}

apps/site/src/lib/sanity/config.ts

@@ -0,0 +1,50 @@
+/**
+ * Sanity connection config.
+ *
+ * Resolved per-request rather than at module scope: on Workers the values in
+ * `wrangler.jsonc` `vars` arrive through `locals.runtime.env`, and are NOT
+ * visible to `import.meta.env` (which Vite bakes in at build time). The
+ * `import.meta.env` fallback exists so `astro dev` works without a Worker.
+ */
+
+export interface SanityConfig {
+	projectId: string;
+	dataset: string;
+	apiVersion: string;
+	/**
+	 * Absolute Studio URL used for stega edit-intent links.
+	 *
+	 * MUST include the workspace basePath. sanity.config.ts defines workspaces
+	 * with basePath "/production" and "/dev"; without it every click-to-edit
+	 * link lands on the workspace picker instead of the document.
+	 */
+	studioUrl: string;
+}
+
+type EnvLike = Record<string, string | undefined>;
+
+/** apiVersion is pinned to match apps/sanity/sanity.config.ts exactly. */
+const DEFAULTS = {
+	projectId: "hfh83o0w",
+	dataset: "production",
+	apiVersion: "2025-09-30",
+	studioUrl: "https://codingcat.dev.sanity.studio/production",
+} as const;
+
+function read(env: EnvLike | undefined, key: string): string | undefined {
+	const fromRuntime = env?.[key];
+	if (fromRuntime) {
+		return fromRuntime;
+	}
+	const fromBuild = (import.meta.env as EnvLike)[key];
+	return fromBuild || undefined;
+}
+
+export function resolveSanityConfig(env?: EnvLike): SanityConfig {
+	return {
+		projectId: read(env, "PUBLIC_SANITY_PROJECT_ID") ?? DEFAULTS.projectId,
+		dataset: read(env, "PUBLIC_SANITY_DATASET") ?? DEFAULTS.dataset,
+		apiVersion: read(env, "PUBLIC_SANITY_API_VERSION") ?? DEFAULTS.apiVersion,
+		studioUrl: read(env, "PUBLIC_SANITY_STUDIO_URL") ?? DEFAULTS.studioUrl,
+	};
+}

apps/site/src/lib/sanity/context.ts

@@ -0,0 +1,67 @@
+import type { ClientReturn, QueryParams } from "@sanity/client";
+import type { SanityImageSource } from "@sanity/image-url";
+import { resolveSanityConfig, type SanityConfig } from "./config";
+import { resolveOpenGraphImage, urlForImage } from "./image";
+import { fetchPublished, loadQuery } from "./load-query";
+import {
+	PERSPECTIVE_PARAM,
+	PREVIEW_COOKIE,
+	type PreviewContext,
+	resolvePreview,
+} from "./preview";
+
+/**
+ * Per-request Sanity access, built once in middleware and exposed on
+ * `Astro.locals.sanity` so pages don't have to thread config/preview around.
+ */
+export interface SanityRequestContext {
+	config: SanityConfig;
+	preview: PreviewContext;
+	/** Draft-aware read. Uses stega + drafts when preview is active. */
+	loadQuery<const Q extends string>(
+		query: Q,
+		params?: QueryParams,
+	): Promise<ClientReturn<Q>>;
+	/** Published-only, stega-free read. Use for RSS, sitemap, OG, JSON-LD. */
+	fetchPublished<const Q extends string>(
+		query: Q,
+		params?: QueryParams,
+	): Promise<ClientReturn<Q>>;
+	urlForImage(
+		source: SanityImageSource | undefined,
+	): ReturnType<typeof urlForImage>;
+	resolveOpenGraphImage(
+		image: (SanityImageSource & { alt?: string }) | undefined,
+		width?: number,
+		height?: number,
+	): ReturnType<typeof resolveOpenGraphImage>;
+}
+
+export function createSanityContext({
+	env,
+	url,
+	hasPreviewCookie,
+}: {
+	env: Record<string, string | undefined> | undefined;
+	url: URL;
+	hasPreviewCookie: boolean;
+}): SanityRequestContext {
+	const config = resolveSanityConfig(env);
+	const preview = resolvePreview({
+		env,
+		hasPreviewCookie,
+		perspectiveParam: url.searchParams.get(PERSPECTIVE_PARAM),
+	});
+
+	return {
+		config,
+		preview,
+		loadQuery: (query, params) => loadQuery(config, preview, query, params),
+		fetchPublished: (query, params) => fetchPublished(config, query, params),
+		urlForImage: (source) => urlForImage(config, source),
+		resolveOpenGraphImage: (image, width, height) =>
+			resolveOpenGraphImage(config, image, width, height),
+	};
+}
+
+export { PREVIEW_COOKIE, PERSPECTIVE_PARAM };

apps/site/src/lib/sanity/image.ts

@@ -0,0 +1,56 @@
+import { stegaClean } from "@sanity/client/stega";
+import {
+	createImageUrlBuilder,
+	type SanityImageSource,
+} from "@sanity/image-url";
+import type { SanityConfig } from "./config";
+
+type Builder = ReturnType<typeof createImageUrlBuilder>;
+
+const builders = new Map<string, Builder>();
+
+function builderFor({ projectId, dataset }: SanityConfig): Builder {
+	const key = `${projectId}:${dataset}`;
+	let b = builders.get(key);
+	if (!b) {
+		b = createImageUrlBuilder({ projectId, dataset });
+		builders.set(key, b);
+	}
+	return b;
+}
+
+/**
+ * Consolidated from the Next app, which had two divergent copies: a bare one in
+ * sanity/lib/image.ts and one in sanity/lib/utils.ts that added
+ * `.auto("format").fit("max")`. The latter behaviour wins — auto=format is what
+ * serves WebP/AVIF.
+ */
+export function urlForImage(
+	config: SanityConfig,
+	source: SanityImageSource | undefined,
+) {
+	if (!source || !(source as { asset?: unknown })?.asset) {
+		return undefined;
+	}
+	return builderFor(config).image(source).auto("format").fit("max");
+}
+
+export function resolveOpenGraphImage(
+	config: SanityConfig,
+	image: (SanityImageSource & { alt?: string }) | undefined,
+	width = 1920,
+	height = 1080,
+) {
+	const url = urlForImage(config, image)?.width(width).height(height).url();
+	if (!url) {
+		return undefined;
+	}
+	return {
+		// stegaClean: this lands in a <meta content> attribute, where stega's
+		// zero-width characters would corrupt the URL.
+		url: stegaClean(url),
+		alt: stegaClean(image?.alt) || "CodingCat.dev Image",
+		width,
+		height,
+	};
+}

apps/site/src/lib/sanity/load-query.ts

@@ -0,0 +1,39 @@
+import type { ClientReturn, QueryParams } from "@sanity/client";
+import { previewClient, publishedClient } from "./client";
+import type { SanityConfig } from "./config";
+import type { PreviewContext } from "./preview";
+
+/**
+ * The `const QueryString extends string` generic preserves the query's literal
+ * type through the wrapper, which is what lets `ClientReturn<Q>` pick the right
+ * result type out of the `declare module "@sanity/client"` query map emitted by
+ * `sanity typegen`. That is what removes the `as` casts the Next app needed.
+ */
+export async function loadQuery<const QueryString extends string>(
+	config: SanityConfig,
+	preview: PreviewContext,
+	query: QueryString,
+	params: QueryParams = {},
+): Promise<ClientReturn<QueryString>> {
+	const client = preview.enabled
+		? previewClient(config, preview.token, preview.perspective)
+		: publishedClient(config);
+	return client.fetch<ClientReturn<QueryString>>(query, params);
+}
+
+/**
+ * Published-only, stega-free reads for RSS, sitemap, OG images and JSON-LD.
+ *
+ * Deliberately a separate function rather than a flag on loadQuery, so these
+ * paths can never be handed a preview context by accident.
+ */
+export async function fetchPublished<const QueryString extends string>(
+	config: SanityConfig,
+	query: QueryString,
+	params: QueryParams = {},
+): Promise<ClientReturn<QueryString>> {
+	return publishedClient(config).fetch<ClientReturn<QueryString>>(
+		query,
+		params,
+	);
+}