@setzkasten-cms/astro-admin 0.6.0

package/src/api-routes/auth-login.ts

@@ -0,0 +1,87 @@
+import type { APIRoute } from 'astro'
+import { createGitHubAuth } from '@setzkasten-cms/auth'
+import { createGoogleAuth } from '@setzkasten-cms/auth'
+
+/**
+ * Login initiation – redirects the user to the chosen OAuth provider.
+ *
+ * GET /api/setzkasten/auth/login?provider=github|google
+ */
+export const GET: APIRoute = async ({ request, url, cookies, redirect }) => {
+  const provider = url.searchParams.get('provider') ?? 'github'
+
+  const config = (globalThis as Record<string, unknown>).__SETZKASTEN_CONFIG__ as
+    | { adminPath: string; hasGitHub: boolean; hasGoogle: boolean }
+    | undefined
+
+  const adminPath = config?.adminPath ?? '/admin'
+
+  // On Vercel, url.origin may resolve to localhost. Use the Host header instead.
+  const host = request.headers.get('x-forwarded-host') ?? request.headers.get('host') ?? url.host
+  const protocol = request.headers.get('x-forwarded-proto') ?? (url.protocol === 'https:' ? 'https' : 'http')
+  const origin = `${protocol}://${host}`
+  const redirectUri = `${origin}/api/setzkasten/auth/callback`
+
+  let loginUrl: string
+
+  if (provider === 'google') {
+    const googleClientId = import.meta.env.GOOGLE_CLIENT_ID ?? process.env.GOOGLE_CLIENT_ID ?? ''
+    const googleClientSecret = import.meta.env.GOOGLE_CLIENT_SECRET ?? process.env.GOOGLE_CLIENT_SECRET ?? ''
+
+    if (!googleClientId || !googleClientSecret) {
+      return new Response('Google OAuth not configured', { status: 500 })
+    }
+
+    const auth = createGoogleAuth({
+      clientId: googleClientId,
+      clientSecret: googleClientSecret,
+      redirectUri,
+    })
+
+    loginUrl = auth.getLoginUrl('google')
+
+    // Store the PKCE code verifier in a cookie for the callback
+    // Arctic generates it internally – we extract it from the URL
+    const urlObj = new URL(loginUrl)
+    const state = urlObj.searchParams.get('state')
+    if (state) {
+      cookies.set('setzkasten_oauth_state', JSON.stringify({ state, provider: 'google' }), {
+        httpOnly: true,
+        secure: true,
+        sameSite: 'lax',
+        path: '/',
+        maxAge: 600, // 10 min
+      })
+    }
+  } else {
+    // Default: GitHub
+    const ghClientId = import.meta.env.GITHUB_CLIENT_ID ?? process.env.GITHUB_CLIENT_ID ?? ''
+    const ghClientSecret = import.meta.env.GITHUB_CLIENT_SECRET ?? process.env.GITHUB_CLIENT_SECRET ?? ''
+
+    if (!ghClientId || !ghClientSecret) {
+      return new Response('GitHub OAuth not configured', { status: 500 })
+    }
+
+    const auth = createGitHubAuth({
+      clientId: ghClientId,
+      clientSecret: ghClientSecret,
+      redirectUri,
+    })
+
+    loginUrl = auth.getLoginUrl('github')
+
+    const urlObj = new URL(loginUrl)
+    const state = urlObj.searchParams.get('state')
+    if (state) {
+      cookies.set('setzkasten_oauth_state', JSON.stringify({ state, provider: 'github' }), {
+        httpOnly: true,
+        secure: true,
+        sameSite: 'lax',
+        path: '/',
+        maxAge: 600,
+      })
+    }
+  }
+
+  return redirect(loginUrl)
+}

package/src/api-routes/auth-logout.ts

@@ -0,0 +1,9 @@
+import type { APIRoute } from 'astro'
+
+/**
+ * Logout – clears the session cookie and redirects to home.
+ */
+export const GET: APIRoute = async ({ cookies, redirect }) => {
+  cookies.delete('setzkasten_session', { path: '/' })
+  return redirect('/')
+}

package/src/api-routes/auth-session.ts

@@ -0,0 +1,36 @@
+import type { APIRoute } from 'astro'
+
+/**
+ * Session check – returns current user info or 401.
+ * Used by the admin SPA to check if the user is logged in.
+ */
+export const GET: APIRoute = async ({ cookies }) => {
+  const session = cookies.get('setzkasten_session')?.value
+  if (!session) {
+    return new Response(JSON.stringify({ authenticated: false }), {
+      status: 401,
+      headers: { 'Content-Type': 'application/json' },
+    })
+  }
+
+  try {
+    const parsed = JSON.parse(session) as { user: unknown; expiresAt: number }
+
+    if (parsed.expiresAt < Date.now()) {
+      cookies.delete('setzkasten_session', { path: '/' })
+      return new Response(JSON.stringify({ authenticated: false, reason: 'expired' }), {
+        status: 401,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }
+
+    return new Response(JSON.stringify({ authenticated: true, user: parsed.user }), {
+      headers: { 'Content-Type': 'application/json' },
+    })
+  } catch {
+    return new Response(JSON.stringify({ authenticated: false }), {
+      status: 401,
+      headers: { 'Content-Type': 'application/json' },
+    })
+  }
+}

package/src/api-routes/catalog-add.ts

@@ -0,0 +1,151 @@
+import type { APIRoute } from 'astro'
+import { registry } from '@setzkasten-cms/catalog'
+import { resolveStorageConfig, prefixPath } from './_storage-config'
+import { validateCatalogAddBody, buildCatalogAddCommit } from './catalog-helpers'
+import { generateAddKey, addToPageConfig } from './section-management'
+
+/**
+ * POST /api/setzkasten/catalog/add
+ *
+ * Adds a catalog template to a page:
+ * - Creates content JSON with template's defaultContent (_sections/{key}.json)
+ * - Appends new entry to the page config (pages/_{pageKey}.json)
+ *
+ * Body: { templateName, pageKey, sectionKey? (override), owner?, repo?, branch?, contentPath? }
+ */
+export const POST: APIRoute = async ({ request, cookies }) => {
+  const session = cookies.get('setzkasten_session')?.value
+  if (!session) return new Response('Unauthorized', { status: 401 })
+
+  const githubToken = import.meta.env.GITHUB_TOKEN ?? process.env.GITHUB_TOKEN
+  if (!githubToken) return new Response('GitHub token not configured', { status: 500 })
+
+  try {
+    const body = await request.json() as Record<string, unknown>
+
+    let validated: ReturnType<typeof validateCatalogAddBody>
+    try {
+      validated = validateCatalogAddBody(body)
+    } catch (e) {
+      return Response.json({ error: e instanceof Error ? e.message : 'Invalid request' }, { status: 400 })
+    }
+
+    const { templateName, pageKey } = validated
+
+    const storage = resolveStorageConfig(body)
+    if (!storage) return Response.json({ error: 'Could not resolve owner/repo' }, { status: 400 })
+    const { owner, repo, branch, projectPrefix } = storage
+
+    const serverConfig = (globalThis as any).__SETZKASTEN_CONFIG__
+    const contentPath = (body.contentPath as string) || serverConfig?.storage?.contentPath || 'content'
+
+    const headers = {
+      Authorization: `Bearer ${githubToken}`,
+      Accept: 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+      'Content-Type': 'application/json',
+    }
+
+    // 1. Read page config
+    const configKey = '_' + pageKey.replace(/\//g, '_')
+    const rawPageConfigPath = `${contentPath}/pages/${configKey}.json`
+    const pageConfigPath = prefixPath(rawPageConfigPath, projectPrefix)
+    const pageConfigRaw = await fetchFileContent(owner, repo, branch, pageConfigPath, githubToken)
+    if (!pageConfigRaw) return Response.json({ error: 'Page config not found' }, { status: 404 })
+
+    const pageConfig = JSON.parse(pageConfigRaw)
+    const existingKeys: string[] = (pageConfig.sections ?? []).map((s: { key: string }) => s.key)
+
+    // 2. Determine section key
+    const sectionKey = validated.sectionKey ?? generateAddKey(existingKeys, templateName)
+    if (existingKeys.includes(sectionKey)) {
+      return Response.json({ error: `Key "${sectionKey}" already exists on this page` }, { status: 409 })
+    }
+
+    // 3. Get template + default content
+    const template = registry.get(templateName)
+    const { sectionJsonPath } = buildCatalogAddCommit({
+      contentPath,
+      projectPrefix,
+      pageKey,
+      sectionKey,
+      templateName,
+      pageConfigPath: rawPageConfigPath,
+    })
+
+    // 4. Commit: content JSON + updated page config
+    const updatedConfig = addToPageConfig(pageConfig, sectionKey, templateName)
+
+    const commitResult = await batchCommit(
+      owner, repo, branch,
+      [
+        { path: pageConfigPath, content: JSON.stringify(updatedConfig, null, 2) },
+        { path: sectionJsonPath, content: JSON.stringify(template.defaultContent, null, 2) },
+      ],
+      `content: add catalog template "${templateName}" as "${sectionKey}" to ${pageKey}`,
+      headers,
+    )
+
+    if (!commitResult.ok) return Response.json({ error: commitResult.error }, { status: 500 })
+
+    return Response.json({ success: true, sectionKey, commitSha: commitResult.sha })
+  } catch (error) {
+    console.error('[setzkasten] catalog-add error:', error)
+    return Response.json(
+      { error: error instanceof Error ? error.message : 'Catalog add failed' },
+      { status: 500 },
+    )
+  }
+}
+
+async function fetchFileContent(owner: string, repo: string, branch: string, path: string, token: string): Promise<string | null> {
+  try {
+    const res = await fetch(
+      `https://api.github.com/repos/${owner}/${repo}/contents/${path}?ref=${branch}`,
+      { headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28' } },
+    )
+    if (!res.ok) return null
+    const data = await res.json() as { content: string; encoding: string }
+    return data.encoding === 'base64' ? Buffer.from(data.content, 'base64').toString('utf-8') : data.content
+  } catch { return null }
+}
+
+async function batchCommit(
+  owner: string, repo: string, branch: string,
+  files: Array<{ path: string; content: string }>,
+  message: string,
+  headers: Record<string, string>,
+): Promise<{ ok: true; sha: string } | { ok: false; error: string }> {
+  try {
+    const refRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/git/refs/heads/${branch}`, { headers })
+    if (!refRes.ok) return { ok: false, error: `Failed to get HEAD: ${refRes.status}` }
+    const { object: { sha: headSha } } = await refRes.json() as { object: { sha: string } }
+
+    const commitRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/git/commits/${headSha}`, { headers })
+    if (!commitRes.ok) return { ok: false, error: `Failed to get commit: ${commitRes.status}` }
+    const { tree: { sha: baseSha } } = await commitRes.json() as { tree: { sha: string } }
+
+    const treeRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/git/trees`, {
+      method: 'POST', headers,
+      body: JSON.stringify({ base_tree: baseSha, tree: files.map(f => ({ path: f.path, mode: '100644', type: 'blob', content: f.content })) }),
+    })
+    if (!treeRes.ok) return { ok: false, error: `Failed to create tree: ${treeRes.status}` }
+    const { sha: treeSha } = await treeRes.json() as { sha: string }
+
+    const newCommitRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/git/commits`, {
+      method: 'POST', headers,
+      body: JSON.stringify({ tree: treeSha, parents: [headSha], message }),
+    })
+    if (!newCommitRes.ok) return { ok: false, error: `Failed to create commit: ${newCommitRes.status}` }
+    const { sha: newSha } = await newCommitRes.json() as { sha: string }
+
+    const updateRes = await fetch(`https://api.github.com/repos/${owner}/${repo}/git/refs/heads/${branch}`, {
+      method: 'PATCH', headers, body: JSON.stringify({ sha: newSha }),
+    })
+    if (!updateRes.ok) return { ok: false, error: `Failed to update ref: ${updateRes.status}` }
+
+    return { ok: true, sha: newSha }
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : 'Commit failed' }
+  }
+}

package/src/api-routes/catalog-export.ts

@@ -0,0 +1,86 @@
+import type { APIRoute } from 'astro'
+import { exportTemplate } from '@setzkasten-cms/catalog'
+import { resolveStorageConfig, prefixPath } from './_storage-config'
+
+/**
+ * POST /api/setzkasten/catalog/export
+ *
+ * Exports a managed section as a `.setzkasten-template` JSON string.
+ * The caller can save this to a file or upload it to a shared catalog.
+ *
+ * Body: { sectionKey, owner?, repo?, branch?, contentPath? }
+ */
+export const POST: APIRoute = async ({ request, cookies }) => {
+  const session = cookies.get('setzkasten_session')?.value
+  if (!session) return new Response('Unauthorized', { status: 401 })
+
+  const githubToken = import.meta.env.GITHUB_TOKEN ?? process.env.GITHUB_TOKEN
+  if (!githubToken) return new Response('GitHub token not configured', { status: 500 })
+
+  try {
+    const body = await request.json() as {
+      sectionKey: string
+      owner?: string
+      repo?: string
+      branch?: string
+      contentPath?: string
+    }
+
+    if (!body.sectionKey) {
+      return Response.json({ error: 'sectionKey is required' }, { status: 400 })
+    }
+
+    const storage = resolveStorageConfig(body)
+    if (!storage) return Response.json({ error: 'Could not resolve owner/repo' }, { status: 400 })
+    const { owner, repo, branch, projectPrefix } = storage
+
+    const serverConfig = (globalThis as any).__SETZKASTEN_CONFIG__
+    const fullConfig = (globalThis as any).__SETZKASTEN_FULL_CONFIG__
+    const contentPath = body.contentPath || serverConfig?.storage?.contentPath || 'content'
+    const { sectionKey } = body
+
+    // 1. Read section content JSON
+    const sectionJsonPath = prefixPath(`${contentPath}/_sections/${sectionKey}.json`, projectPrefix)
+    const contentRaw = await fetchFileContent(owner, repo, branch, sectionJsonPath, githubToken)
+    if (!contentRaw) return Response.json({ error: `Section content not found: ${sectionKey}` }, { status: 404 })
+
+    const content = JSON.parse(contentRaw) as Record<string, unknown>
+
+    // 2. Find section definition from full config
+    const sectionDef = findSectionDef(fullConfig, sectionKey)
+    if (!sectionDef) {
+      return Response.json({ error: `Section definition not found for key: ${sectionKey}` }, { status: 404 })
+    }
+
+    // 3. Export to template format
+    const templateJson = exportTemplate(sectionKey, sectionDef, content)
+
+    return Response.json({ success: true, template: templateJson })
+  } catch (error) {
+    console.error('[setzkasten] catalog-export error:', error)
+    return Response.json(
+      { error: error instanceof Error ? error.message : 'Export failed' },
+      { status: 500 },
+    )
+  }
+}
+
+function findSectionDef(fullConfig: any, sectionKey: string): any {
+  if (!fullConfig?.products) return null
+  for (const product of Object.values(fullConfig.products) as any[]) {
+    if (product?.sections?.[sectionKey]) return product.sections[sectionKey]
+  }
+  return null
+}
+
+async function fetchFileContent(owner: string, repo: string, branch: string, path: string, token: string): Promise<string | null> {
+  try {
+    const res = await fetch(
+      `https://api.github.com/repos/${owner}/${repo}/contents/${path}?ref=${branch}`,
+      { headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28' } },
+    )
+    if (!res.ok) return null
+    const data = await res.json() as { content: string; encoding: string }
+    return data.encoding === 'base64' ? Buffer.from(data.content, 'base64').toString('utf-8') : data.content
+  } catch { return null }
+}

package/src/api-routes/catalog-helpers.ts

@@ -0,0 +1,83 @@
+/**
+ * Pure helper functions for catalog API routes.
+ * No GitHub API, no Astro runtime — fully unit-testable.
+ */
+
+import { registry } from '@setzkasten-cms/catalog'
+import { prefixPath } from './_storage-config'
+
+// ---------------------------------------------------------------------------
+// GET /api/setzkasten/catalog
+// ---------------------------------------------------------------------------
+
+/** Returns the full catalog list (all built-in templates) for the API response. */
+export function buildCatalogResponse() {
+  return registry.list()
+}
+
+// ---------------------------------------------------------------------------
+// POST /api/setzkasten/catalog/add
+// ---------------------------------------------------------------------------
+
+export interface CatalogAddBody {
+  templateName?: unknown
+  pageKey?: unknown
+  sectionKey?: unknown
+  [key: string]: unknown
+}
+
+/**
+ * Validates the request body for POST /api/setzkasten/catalog/add.
+ * Throws with a descriptive message on any validation error.
+ */
+export function validateCatalogAddBody(body: CatalogAddBody): {
+  templateName: string
+  pageKey: string
+  sectionKey?: string
+} {
+  if (!body.templateName || typeof body.templateName !== 'string') {
+    throw new Error('templateName is required')
+  }
+  if (!body.pageKey || typeof body.pageKey !== 'string') {
+    throw new Error('pageKey is required')
+  }
+  // Validate templateName exists in registry (throws if not)
+  registry.get(body.templateName)
+
+  return {
+    templateName: body.templateName,
+    pageKey: body.pageKey,
+    sectionKey: typeof body.sectionKey === 'string' ? body.sectionKey : undefined,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Commit path builder
+// ---------------------------------------------------------------------------
+
+export interface CatalogAddCommitOpts {
+  contentPath: string
+  projectPrefix: string
+  pageKey: string
+  sectionKey: string
+  templateName: string
+  pageConfigPath: string
+}
+
+export interface CatalogAddCommitPaths {
+  sectionJsonPath: string
+  pageConfigPath: string
+}
+
+/**
+ * Builds the file paths that need to be committed when adding a catalog template to a page.
+ */
+export function buildCatalogAddCommit(opts: CatalogAddCommitOpts): CatalogAddCommitPaths {
+  const sectionJsonPath = prefixPath(
+    `${opts.contentPath}/_sections/${opts.sectionKey}.json`,
+    opts.projectPrefix,
+  )
+  const pageConfigPath = prefixPath(opts.pageConfigPath, opts.projectPrefix)
+
+  return { sectionJsonPath, pageConfigPath }
+}

package/src/api-routes/catalog-list.ts

@@ -0,0 +1,12 @@
+import type { APIRoute } from 'astro'
+import { buildCatalogResponse } from './catalog-helpers'
+
+/**
+ * GET /api/setzkasten/catalog
+ *
+ * Returns all available catalog templates (built-in registry).
+ * No authentication required — catalog is read-only metadata.
+ */
+export const GET: APIRoute = async () => {
+  return Response.json({ templates: buildCatalogResponse() })
+}

package/src/api-routes/config.ts

@@ -0,0 +1,30 @@
+import type { APIRoute } from 'astro'
+
+/**
+ * Returns the full SetzKastenConfig as JSON.
+ * The config is injected into globalThis by the integration at build time.
+ *
+ * GET /api/setzkasten/config
+ */
+export const GET: APIRoute = async () => {
+  const config = (globalThis as Record<string, unknown>).__SETZKASTEN_FULL_CONFIG__ ?? {}
+  const ssrConfig = (globalThis as Record<string, unknown>).__SETZKASTEN_CONFIG__ as Record<string, unknown> | undefined
+
+  const result = {
+    storage: { kind: 'github' },
+    auth: { providers: ['github'] },
+    theme: {},
+    products: {},
+    collections: {},
+    ...config,
+    // Include storage params so the client can create ProxyContentRepository
+    _storage: ssrConfig?.storage ?? undefined,
+    _hasGitHub: ssrConfig?.hasGitHub ?? false,
+    _hasGoogle: ssrConfig?.hasGoogle ?? false,
+  }
+
+  return new Response(JSON.stringify(result), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}

package/src/api-routes/deploy-hook.ts

@@ -0,0 +1,69 @@
+import type { APIRoute } from 'astro'
+
+/**
+ * Triggers the configured deploy hook URL after a content commit.
+ * Called by the CMS UI after every successful GitHub commit.
+ *
+ * The deploy hook URL is set via:
+ *   setzkasten({ deployHook: { url: 'https://api.vercel.com/v1/integrations/deploy/...' } })
+ *
+ * Compatible with Vercel, Netlify, Cloudflare Pages and any URL that accepts a POST.
+ */
+export const POST: APIRoute = async ({ cookies }) => {
+  const session = cookies.get('setzkasten_session')?.value
+  if (!session) {
+    return new Response('Unauthorized', { status: 401 })
+  }
+
+  const config = (globalThis as any).__SETZKASTEN_CONFIG__ as {
+    deployHook?: { url: string; secret?: string }
+  } | undefined
+
+  if (!config?.deployHook?.url) {
+    return new Response(JSON.stringify({ skipped: true, reason: 'Kein deployHook konfiguriert' }), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    })
+  }
+
+  const { url, secret } = config.deployHook
+
+  try {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'User-Agent': 'setzkasten-cms',
+    }
+
+    if (secret) {
+      headers['X-Setzkasten-Secret'] = secret
+    }
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        event: 'content.commit',
+        timestamp: new Date().toISOString(),
+      }),
+    })
+
+    if (!response.ok) {
+      console.warn(`[setzkasten] Deploy hook antwortete mit ${response.status}: ${url}`)
+      return new Response(
+        JSON.stringify({ ok: false, status: response.status }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      )
+    }
+
+    return new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    })
+  } catch (error) {
+    console.error('[setzkasten] Deploy hook fehlgeschlagen:', error)
+    return new Response(
+      JSON.stringify({ ok: false, error: String(error) }),
+      { status: 200, headers: { 'Content-Type': 'application/json' } },
+    )
+  }
+}

package/src/api-routes/github-proxy.ts

@@ -0,0 +1,111 @@
+import type { APIRoute } from 'astro'
+import { writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * Server-side proxy for GitHub API calls.
+ * The GitHub App token stays server-side (never exposed to browser).
+ *
+ * Client calls: POST /api/setzkasten/github/repos/{owner}/{repo}/...
+ * Proxy forwards to: https://api.github.com/repos/{owner}/{repo}/...
+ */
+export const ALL: APIRoute = async ({ params, request, cookies }) => {
+  // Verify session
+  const session = cookies.get('setzkasten_session')?.value
+  if (!session) {
+    return new Response('Unauthorized', { status: 401 })
+  }
+
+  const githubPath = params.path
+  if (!githubPath) {
+    return new Response('Missing path', { status: 400 })
+  }
+
+  // GitHub App token from environment (never sent to client)
+  const githubToken = import.meta.env.GITHUB_TOKEN ?? process.env.GITHUB_TOKEN
+
+  if (!githubToken) {
+    return new Response('GitHub token not configured', { status: 500 })
+  }
+
+  const githubUrl = `https://api.github.com/${githubPath}`
+
+  try {
+    // Forward the request to GitHub API
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${githubToken}`,
+      Accept: 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+    }
+
+    // Forward Content-Type for write operations
+    const contentType = request.headers.get('content-type')
+    if (contentType) {
+      headers['Content-Type'] = contentType
+    }
+
+    const body =
+      request.method !== 'GET' && request.method !== 'HEAD'
+        ? await request.text()
+        : undefined
+
+    const response = await fetch(githubUrl, {
+      method: request.method,
+      headers,
+      body,
+    })
+
+    // Forward response with rate limit headers
+    const responseHeaders = new Headers()
+    responseHeaders.set('Content-Type', response.headers.get('content-type') ?? 'application/json')
+
+    const rateLimitHeaders = [
+      'x-ratelimit-limit',
+      'x-ratelimit-remaining',
+      'x-ratelimit-reset',
+    ]
+    for (const header of rateLimitHeaders) {
+      const value = response.headers.get(header)
+      if (value) responseHeaders.set(header, value)
+    }
+
+    // Forward ETag for caching
+    const etag = response.headers.get('etag')
+    if (etag) responseHeaders.set('etag', etag)
+
+    const responseText = await response.text()
+
+    // Mirror successful PUT writes to local filesystem (dev-server sync).
+    // GitHub path pattern: repos/{owner}/{repo}/contents/{filePath}
+    // We extract {filePath} and write it relative to repoRoot so the
+    // Vite virtual content module picks it up on next HMR cycle.
+    if (request.method === 'PUT' && response.ok && body) {
+      try {
+        const repoRoot: string | undefined = (globalThis as any).__SETZKASTEN_CONFIG__?.repoRoot
+        if (repoRoot) {
+          // githubPath = "repos/{owner}/{repo}/contents/{filePath}"
+          const contentsMatch = githubPath.match(/^repos\/[^/]+\/[^/]+\/contents\/(.+)$/)
+          if (contentsMatch) {
+            const filePath = contentsMatch[1]!
+            const parsed = JSON.parse(body) as { content?: string }
+            if (parsed.content) {
+              // GitHub API sends base64 with possible line breaks
+              const decoded = Buffer.from(parsed.content.replace(/\s/g, ''), 'base64').toString('utf-8')
+              await writeFile(join(repoRoot, filePath), decoded, 'utf-8').catch(() => {})
+            }
+          }
+        }
+      } catch {
+        // Non-fatal — local sync is best-effort
+      }
+    }
+
+    return new Response(responseText, {
+      status: response.status,
+      headers: responseHeaders,
+    })
+  } catch (error) {
+    console.error('[setzkasten] GitHub proxy error:', error)
+    return new Response('GitHub API request failed', { status: 502 })
+  }
+}