@407dev/cms-astro 0.1.0

package/src/image.ts

@@ -0,0 +1,64 @@
+export interface ImageTransformOptions {
+  width?: number;
+  height?: number;
+  format?: string;
+  fit?: 'scale-down' | 'contain' | 'cover' | 'crop' | 'pad' | string;
+  quality?: number;
+}
+
+/**
+ * Determines whether a URL is hosted on a zone domain eligible for /cdn-cgi/image transforms.
+ * Non-zone URLs (*.r2.dev, localhost, relative paths, data/blob URLs) return false.
+ */
+export function isCdnTransformableUrl(url: string): boolean {
+  if (!url || typeof url !== 'string') return false;
+  if (url.startsWith('data:') || url.startsWith('blob:')) return false;
+  if (url.includes('localhost') || url.includes('127.0.0.1') || url.includes('.r2.dev')) {
+    return false;
+  }
+  return url.startsWith('http://') || url.startsWith('https://');
+}
+
+/**
+ * Builds a Cloudflare /cdn-cgi/image/... transform URL.
+ * Automatically degrades to the raw source URL for non-transformable hostnames.
+ */
+export function buildCdnImageUrl(url: string, options: ImageTransformOptions = {}): string {
+  if (!isCdnTransformableUrl(url)) {
+    return url;
+  }
+
+  const params: string[] = [];
+  if (options.width !== undefined && options.width !== null) {
+    params.push(`width=${options.width}`);
+  }
+  if (options.height !== undefined && options.height !== null) {
+    params.push(`height=${options.height}`);
+  }
+
+  params.push(`format=${options.format || 'auto'}`);
+
+  if (options.fit) {
+    params.push(`fit=${options.fit}`);
+  }
+  if (options.quality !== undefined && options.quality !== null) {
+    params.push(`quality=${options.quality}`);
+  }
+
+  const optionString = params.join(',');
+  return `/cdn-cgi/image/${optionString}/${url}`;
+}
+
+/**
+ * Generates an HTML srcset string with Cloudflare /cdn-cgi/image transforms for specified widths.
+ */
+export function buildSrcSet(
+  url: string,
+  widths: number[] = [400, 800, 1200, 1600],
+  options: Omit<ImageTransformOptions, 'width'> = {},
+): string {
+  if (!url) return '';
+  if (!isCdnTransformableUrl(url)) return '';
+
+  return widths.map((w) => `${buildCdnImageUrl(url, { ...options, width: w })} ${w}w`).join(', ');
+}

package/src/index.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import {
+  cms,
+  cmsAstro,
+  createCmsClient,
+  getPreviewData,
+  renderRedirectsFile,
+  renderRobotsTxt,
+  renderSitemapXml,
+  signPreviewToken,
+  verifyPreviewToken,
+} from './index';
+
+describe('cms-astro package entrypoint', () => {
+  it('exports all expected SDK utilities and functions', () => {
+    expect(typeof createCmsClient).toBe('function');
+    expect(typeof cmsAstro).toBe('function');
+    expect(typeof cms).toBe('function');
+    expect(typeof verifyPreviewToken).toBe('function');
+    expect(typeof signPreviewToken).toBe('function');
+    expect(typeof getPreviewData).toBe('function');
+    expect(typeof renderRobotsTxt).toBe('function');
+    expect(typeof renderSitemapXml).toBe('function');
+    expect(typeof renderRedirectsFile).toBe('function');
+  });
+
+  it('configures cmsAstro with empty options falling back to process.env', async () => {
+    const originalSiteId = process.env.CMS_SITE_ID;
+    const originalContentUrl = process.env.CMS_CONTENT_URL;
+    const originalPreviewSecret = process.env.CMS_PREVIEW_SECRET;
+
+    process.env.CMS_SITE_ID = 'site_env_123';
+    process.env.CMS_CONTENT_URL = 'https://content.example.com';
+    process.env.CMS_PREVIEW_SECRET = 'secret_env_456';
+
+    try {
+      const integration = cmsAstro();
+      expect(integration.name).toBe('@407dev/cms-astro');
+
+      let updatedViteConfig: Record<string, unknown> | null = null;
+      let warningLogged = false;
+      const fakeSetupArgs = {
+        updateConfig: ({ vite }: { vite: Record<string, unknown> }) => {
+          updatedViteConfig = vite;
+        },
+        command: 'build' as const,
+        injectScript: () => {},
+        addMiddleware: () => {},
+        addDevToolbarApp: () => {},
+        logger: {
+          warn: (msg: string) => {
+            if (msg.includes('deprecated')) warningLogged = true;
+          },
+          error: () => {},
+          info: () => {},
+        },
+      };
+
+      const setupHook = integration.hooks['astro:config:setup'];
+      if (typeof setupHook === 'function') {
+        await (setupHook as (args: unknown) => Promise<void>)(fakeSetupArgs);
+      }
+
+      expect(updatedViteConfig).toBeDefined();
+      const define = (updatedViteConfig as unknown as { define: Record<string, string> }).define;
+      expect(define['import.meta.env.CMS_SITE_ID']).toBe('"site_env_123"');
+      expect(define['import.meta.env.CMS_CONTENT_URL']).toBe('"https://content.example.com"');
+      expect(define['import.meta.env.CMS_PREVIEW_SECRET']).toBeUndefined();
+      expect(warningLogged).toBe(true);
+    } finally {
+      process.env.CMS_SITE_ID = originalSiteId;
+      process.env.CMS_CONTENT_URL = originalContentUrl;
+      process.env.CMS_PREVIEW_SECRET = originalPreviewSecret;
+    }
+  });
+});

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from './client';
+export * from './fields';
+export * from './head';
+export * from './image';
+export * from './integration';
+export * from './jwt';
+export * from './middleware/preview';
+export * from './preview';
+export * from './richtext/render';
+export * from './runtime/bundle';
+export * from './runtime/store';
+export * from './siteFiles';
+export * from './types';

package/src/integration.ts

@@ -0,0 +1,218 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { AstroIntegration } from 'astro';
+import { getClient, initCmsClient } from './client';
+import { mintDevPreviewToken } from './dev/preview-token';
+import { buildBridgeScript } from './preview/bridge-script';
+import { markBundleReady } from './runtime/bundle';
+import { clearMissingFieldWarnings, getMissingFieldWarnings } from './runtime/store';
+import { CMS_TOOLBAR_ICON } from './toolbar/icon';
+import type { CmsAstroOptions } from './types';
+
+function deriveRouteFromComponent(componentPath: string): string {
+  let route = componentPath
+    .replace(/\\/g, '/')
+    .replace(/^.*src\/pages\/?/, '/')
+    .replace(/\.(astro|mdx|md|ts|js|jsx|tsx)$/, '')
+    .replace(/\/index$/, '');
+  if (!route.startsWith('/')) {
+    route = `/${route}`;
+  }
+  return route === '' ? '/' : route;
+}
+
+export function cmsAstro(options: CmsAstroOptions = {}): AstroIntegration {
+  return {
+    name: '@407dev/cms-astro',
+    hooks: {
+      'astro:config:setup': async ({
+        updateConfig,
+        command,
+        injectScript,
+        addMiddleware,
+        addDevToolbarApp,
+        logger,
+      }) => {
+        // Register preview middleware
+        addMiddleware({
+          entrypoint: '@407dev/cms-astro/middleware',
+          order: 'pre',
+        });
+
+        // Initialize client singleton
+        if (options.client) {
+          initCmsClient({ client: options.client });
+        } else {
+          initCmsClient({
+            siteId: options.siteId,
+            contentUrl: options.contentUrl,
+            previewSecret: options.previewSecret,
+          });
+        }
+
+        // Register environment variables
+        const effectiveSiteId = options.siteId || process.env.CMS_SITE_ID || '';
+        const effectiveContentUrl = options.contentUrl || process.env.CMS_CONTENT_URL || '';
+        const effectivePreviewSecret =
+          options.previewSecret || process.env.CMS_PREVIEW_SECRET || '';
+
+        if (command !== 'dev' && (options.previewSecret || process.env.CMS_PREVIEW_SECRET)) {
+          logger.warn(
+            'previewSecret and CMS_PREVIEW_SECRET are deprecated and ignored outside astro dev. Site hosts no longer verify preview tokens.',
+          );
+        }
+
+        if (effectiveContentUrl || effectiveSiteId) {
+          updateConfig({
+            vite: {
+              define: {
+                'import.meta.env.CMS_CONTENT_URL': JSON.stringify(effectiveContentUrl),
+                'import.meta.env.CMS_SITE_ID': JSON.stringify(effectiveSiteId),
+              },
+            },
+          });
+        }
+
+        // In dev, inject full bridge script and dev toolbar
+        if (command === 'dev') {
+          injectScript(
+            'page',
+            buildBridgeScript({
+              editorOrigins: options.editorOrigins,
+            }),
+          );
+
+          const devModulePath = './dev/index.js';
+          const { resolveDevConfig, createVerifier, cmsDevApiPlugin } = await import(
+            /* @vite-ignore */ devModulePath
+          );
+
+          const devConfig = await resolveDevConfig({
+            siteId: options.siteId,
+            apiUrl: options.apiUrl,
+            siteDir: process.cwd(),
+          });
+
+          if (devConfig.status === 'refused') {
+            logger.error(`CMS dev routes disabled: ${devConfig.reason}`);
+          }
+          if (devConfig.status === 'read-only') {
+            logger.warn(
+              `CMS dev toolbar is READ-ONLY: ${devConfig.mismatch?.source} (${devConfig.mismatch?.actual}) ≠ site rendered (${devConfig.mismatch?.expected})`,
+            );
+          }
+
+          const verifier = await createVerifier({
+            siteDir: process.cwd(),
+            siteId: devConfig.siteId,
+          });
+
+          addDevToolbarApp({
+            id: 'cms-content',
+            name: 'CMS Content',
+            icon: CMS_TOOLBAR_ICON,
+            entrypoint: fileURLToPath(new URL('./toolbar/app.js', import.meta.url)),
+          });
+
+          updateConfig({
+            vite: {
+              plugins: [
+                cmsDevApiPlugin({
+                  devConfig,
+                  client: getClient(),
+                  verifier,
+                  previewSecret: effectivePreviewSecret,
+                  editorOrigins: options.editorOrigins,
+                }),
+              ],
+            },
+          });
+        }
+
+        // Fetch bundle once on setup/build and write to .cms/bundle.json
+        const activeClient = getClient();
+        if (activeClient) {
+          try {
+            // Dev serves draft content; self-mint a preview token from the shared secret
+            // since the content-worker's draft endpoint still requires one (token rules unchanged).
+            const devPreviewToken =
+              command === 'dev'
+                ? await mintDevPreviewToken(activeClient.siteId, effectivePreviewSecret)
+                : null;
+
+            const bundle = await activeClient.getBundle(
+              devPreviewToken ? { previewToken: devPreviewToken } : undefined,
+            );
+            markBundleReady(bundle);
+
+            const cmsDir = path.resolve(process.cwd(), '.cms');
+            if (!fs.existsSync(cmsDir)) {
+              fs.mkdirSync(cmsDir, { recursive: true });
+            }
+            fs.writeFileSync(
+              path.join(cmsDir, 'bundle.json'),
+              JSON.stringify(bundle, null, 2),
+              'utf-8',
+            );
+          } catch {
+            // Fail gracefully if fetch fails
+          }
+        }
+      },
+
+      'astro:routes:resolved': async ({ routes }) => {
+        try {
+          const cmsDir = path.resolve(process.cwd(), '.cms');
+          if (!fs.existsSync(cmsDir)) {
+            fs.mkdirSync(cmsDir, { recursive: true });
+          }
+
+          const serializedRoutes = routes.map(
+            (r: {
+              route?: string;
+              pathname?: string;
+              component?: string;
+              entrypoint?: string;
+              type?: string;
+              params?: string[];
+            }) => {
+              const comp = r.component || r.entrypoint || '';
+              let routePattern = r.route || r.pathname || '';
+              if (!routePattern && comp) {
+                routePattern = deriveRouteFromComponent(comp);
+              }
+              return {
+                route: routePattern,
+                component: comp,
+                type: r.type || 'page',
+                params: r.params || [],
+              };
+            },
+          );
+
+          fs.writeFileSync(
+            path.join(cmsDir, 'routes.json'),
+            JSON.stringify(serializedRoutes, null, 2),
+            'utf-8',
+          );
+        } catch {
+          // Ignore if .cms directory write fails
+        }
+      },
+
+      'astro:build:done': async ({ logger }) => {
+        // Report missing field warnings recorded during SSG
+        const missing = getMissingFieldWarnings();
+        if (missing.length > 0) {
+          logger.warn(
+            `CMS Build Warning: ${missing.length} field(s) were rendered with empty/missing values: ${missing.join(', ')}`,
+          );
+          clearMissingFieldWarnings();
+        }
+      },
+    },
+  };
+}
+
+export const cms = cmsAstro;

package/src/jwt.ts

@@ -0,0 +1,131 @@
+import type { PreviewTokenPayload, VerifyTokenResult } from './types';
+
+// Base64url encoding and decoding helpers using standard Web APIs
+function base64UrlEncode(data: Uint8Array | string): string {
+  let bytes: Uint8Array;
+  if (typeof data === 'string') {
+    bytes = new TextEncoder().encode(data);
+  } else {
+    bytes = data;
+  }
+
+  let binary = '';
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  const base64 = btoa(binary);
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function base64UrlDecode(str: string): Uint8Array {
+  let base64 = str.replace(/-/g, '+').replace(/_/g, '/');
+  while (base64.length % 4 !== 0) {
+    base64 += '=';
+  }
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+function base64UrlDecodeToString(str: string): string {
+  const bytes = base64UrlDecode(str);
+  return new TextDecoder().decode(bytes);
+}
+
+async function getHmacKey(secret: string, usage: 'sign' | 'verify'): Promise<CryptoKey> {
+  const enc = new TextEncoder();
+  return crypto.subtle.importKey(
+    'raw',
+    enc.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    [usage],
+  );
+}
+
+/**
+ * Signs a payload with HS256 using standard Web Crypto API.
+ */
+export async function signPreviewToken(
+  payload: Record<string, unknown>,
+  secret: string,
+): Promise<string> {
+  const header = { alg: 'HS256', typ: 'JWT' };
+  const encodedHeader = base64UrlEncode(JSON.stringify(header));
+  const encodedPayload = base64UrlEncode(JSON.stringify(payload));
+  const data = new TextEncoder().encode(`${encodedHeader}.${encodedPayload}`);
+
+  const key = await getHmacKey(secret, 'sign');
+  const signature = await crypto.subtle.sign('HMAC', key, data);
+  const encodedSignature = base64UrlEncode(new Uint8Array(signature));
+
+  return `${encodedHeader}.${encodedPayload}.${encodedSignature}`;
+}
+
+/**
+ * Locally verifies a signed JWT token against a shared secret using standard Web Crypto API.
+ * Never performs network requests.
+ */
+export async function verifyPreviewToken(
+  token: string | null | undefined,
+  secret: string | undefined,
+  expectedSiteId?: string,
+): Promise<VerifyTokenResult> {
+  if (!token || typeof token !== 'string') {
+    return { valid: false, error: 'Preview token is missing or empty' };
+  }
+
+  if (!secret || typeof secret !== 'string') {
+    return { valid: false, error: 'Preview token secret is not configured' };
+  }
+
+  const parts = token.trim().split('.');
+  if (parts.length !== 3) {
+    return { valid: false, error: 'Invalid JWT structure' };
+  }
+
+  const [encodedHeader, encodedPayload, encodedSignature] = parts;
+
+  try {
+    // 1. Verify signature with SubtleCrypto
+    const key = await getHmacKey(secret, 'verify');
+    const data = new TextEncoder().encode(`${encodedHeader}.${encodedPayload}`);
+    const signatureBytes = base64UrlDecode(encodedSignature);
+
+    const isSigValid = await crypto.subtle.verify(
+      'HMAC',
+      key,
+      signatureBytes as unknown as BufferSource,
+      data as unknown as BufferSource,
+    );
+    if (!isSigValid) {
+      return { valid: false, error: 'Invalid token signature' };
+    }
+
+    // 2. Decode and parse payload
+    const payloadJson = base64UrlDecodeToString(encodedPayload);
+    const payload = JSON.parse(payloadJson) as PreviewTokenPayload;
+
+    // 3. Verify expiration
+    const now = Math.floor(Date.now() / 1000);
+    if (typeof payload.exp === 'number' && payload.exp < now) {
+      return { valid: false, error: 'Preview token has expired' };
+    }
+
+    // 4. Verify site scope if specified; fail closed when the payload has no site_id
+    if (expectedSiteId && payload.site_id !== expectedSiteId) {
+      return {
+        valid: false,
+        error: `Preview token site_id (${payload.site_id}) does not match expected site_id (${expectedSiteId})`,
+      };
+    }
+
+    return { valid: true, payload };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { valid: false, error: `Failed to verify preview token: ${msg}` };
+  }
+}

package/src/middleware/index.ts

@@ -0,0 +1,4 @@
+import { createPreviewMiddleware } from './preview';
+
+export const onRequest = createPreviewMiddleware();
+export * from './preview';

package/src/middleware/preview.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it, vi } from 'vitest';
+import { initCmsClient } from '../client';
+import type { CmsClient, ContentBundle } from '../types';
+import { createPreviewMiddleware } from './preview';
+
+const TEST_SITE_ID = '11111111-1111-1111-1111-111111111111';
+
+const mockBundle: ContentBundle = {
+  bundleVersion: 1,
+  site_id: TEST_SITE_ID,
+  fields: { 'home.title': 'Draft Home' },
+  collections: {},
+  entries: {},
+  routes: [],
+  settings: {},
+  redirects: [],
+};
+
+const mockClient: CmsClient = {
+  siteId: TEST_SITE_ID,
+  contentUrl: 'http://localhost:8788',
+  async getBundle() {
+    return mockBundle;
+  },
+  async getFields() {
+    return mockBundle.fields;
+  },
+  async getField<T = unknown>(key: string) {
+    return (mockBundle.fields[key] as T) ?? null;
+  },
+  async getCollections() {
+    return {};
+  },
+  async getEntries() {
+    return [];
+  },
+  async getEntry() {
+    return null;
+  },
+  async getRoutes() {
+    return [];
+  },
+  async getSiteConfig() {
+    return {
+      site_id: TEST_SITE_ID,
+      redirects: [],
+      robots: {},
+      default_seo: {},
+      sitemap: {},
+      not_found_path: null,
+    };
+  },
+  clearCache() {},
+};
+
+describe('createPreviewMiddleware', () => {
+  it('passes through standard non-preview requests without tokens', async () => {
+    const middleware = createPreviewMiddleware({ client: mockClient });
+    const context = {
+      request: new Request('http://localhost:4321/about'),
+      url: new URL('http://localhost:4321/about'),
+    };
+    const next = vi.fn().mockResolvedValue(new Response('Standard Page', { status: 200 }));
+
+    const res = await middleware(context, next);
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(await res.text()).toBe('Standard Page');
+  });
+
+  it('rejects /_preview route when preview token is missing', async () => {
+    const middleware = createPreviewMiddleware({ client: mockClient });
+    const context = {
+      request: new Request('http://localhost:4321/_preview'),
+      url: new URL('http://localhost:4321/_preview'),
+    };
+    const next = vi.fn();
+
+    const res = await middleware(context, next);
+    expect(res.status).toBe(400);
+    expect(await res.text()).toBe('Preview token is missing');
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('handles /_preview rewrite and injects bridge script when bundle fetch succeeds', async () => {
+    const middleware = createPreviewMiddleware({ client: mockClient });
+    const context = {
+      request: new Request('http://localhost:4321/_preview?preview_token=valid-token'),
+      url: new URL('http://localhost:4321/_preview?preview_token=valid-token'),
+      rewrite: vi.fn().mockImplementation(async (targetPath: string) => {
+        expect(targetPath).toBe('/');
+        return new Response('<html><body><h1>Hello</h1></body></html>', {
+          status: 200,
+          headers: { 'content-type': 'text/html' },
+        });
+      }),
+    };
+    const next = vi.fn();
+
+    const res = await middleware(context, next);
+    expect(res.status).toBe(200);
+    expect(context.rewrite).toHaveBeenCalledWith('/');
+    const html = await res.text();
+    expect(html).toContain('window.__CMS_BRIDGE_INITIALIZED__');
+    expect(html).toContain('<h1>Hello</h1>');
+  });
+
+  it('returns 404 when bundle fetch returns 401/403 (e.g. wrong site or invalid token)', async () => {
+    const failingClient: CmsClient = {
+      ...mockClient,
+      async getBundle() {
+        const error = new Error('CMS Client: Failed to fetch bundle (status 401): Unauthorized');
+        (error as unknown as { status: number }).status = 401;
+        throw error;
+      },
+    };
+
+    const middleware = createPreviewMiddleware({ client: failingClient });
+    const context = {
+      request: new Request('http://localhost:4321/?preview_token=invalid-or-wrong-site-token'),
+      url: new URL('http://localhost:4321/?preview_token=invalid-or-wrong-site-token'),
+    };
+    const next = vi.fn();
+
+    const res = await middleware(context, next);
+    expect(res.status).toBe(404);
+    expect(await res.text()).toBe('Preview token is not valid for this site');
+    expect(res.headers.get('Cache-Control')).toBe('private, no-store');
+    expect(res.headers.get('X-Robots-Tag')).toBe('noindex, nofollow');
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('resolves singleton client via getClient() if not passed directly in options', async () => {
+    initCmsClient({ client: mockClient });
+
+    const middleware = createPreviewMiddleware();
+    const context = {
+      request: new Request('http://localhost:4321/_preview/about?preview_token=valid-token'),
+      url: new URL('http://localhost:4321/_preview/about?preview_token=valid-token'),
+      rewrite: vi.fn().mockImplementation(async (targetPath: string) => {
+        expect(targetPath).toBe('/about');
+        return new Response('<html><body><h1>About</h1></body></html>', {
+          status: 200,
+          headers: { 'content-type': 'text/html' },
+        });
+      }),
+    };
+    const next = vi.fn();
+
+    const res = await middleware(context, next);
+    expect(res.status).toBe(200);
+    expect(context.rewrite).toHaveBeenCalledWith('/about');
+  });
+
+  it('keeps draft bundle active in AsyncLocalStorage while response stream is consumed', async () => {
+    const { getActiveBundle } = await import('../runtime/store');
+
+    const middleware = createPreviewMiddleware({ client: mockClient });
+
+    const context = {
+      request: new Request('http://localhost:4321/?preview_token=valid-token'),
+      url: new URL('http://localhost:4321/?preview_token=valid-token'),
+    };
+    const next = vi.fn().mockImplementation(async () => {
+      const stream = new ReadableStream({
+        start(controller) {
+          const active = getActiveBundle();
+          const content = `<html><body><h1>${active?.fields?.['home.title'] || 'Missing'}</h1></body></html>`;
+          controller.enqueue(new TextEncoder().encode(content));
+          controller.close();
+        },
+      });
+      return new Response(stream, {
+        status: 200,
+        headers: { 'content-type': 'text/html' },
+      });
+    });
+
+    const res = await middleware(context, next);
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).toContain('<h1>Draft Home</h1>');
+    expect(html).toContain('window.__CMS_BRIDGE_INITIALIZED__');
+  });
+});