@ekrist1/vulse 0.1.6-alpha.3 → 0.1.7-alpha.4

package/src/core/repos/revisions.ts

@@ -0,0 +1,60 @@
+import { and, desc, eq } from 'drizzle-orm'
+import type { VulseDb } from '../db.js'
+import { entryRevisions } from '../schema.js'
+import { NotFoundError } from '../errors.js'
+import { DEFAULT_LOCALE, EntriesRepo } from './entries.js'
+
+export interface RevisionRow {
+  id: string
+  entryId: string
+  locale: string
+  version: number
+  content: unknown
+  authorId: string | null
+  changeSummary: string | null
+  createdAt: Date
+}
+
+export class RevisionsRepo {
+  constructor(private db: VulseDb) {}
+
+  async listByEntry(entryId: string, locale: string = DEFAULT_LOCALE): Promise<RevisionRow[]> {
+    return await this.db.select().from(entryRevisions)
+      .where(and(eq(entryRevisions.entryId, entryId), eq(entryRevisions.locale, locale)))
+      .orderBy(desc(entryRevisions.version)) as RevisionRow[]
+  }
+
+  async getVersion(entryId: string, version: number, locale: string = DEFAULT_LOCALE): Promise<RevisionRow | null> {
+    const [row] = await this.db.select().from(entryRevisions)
+      .where(and(
+        eq(entryRevisions.entryId, entryId),
+        eq(entryRevisions.locale, locale),
+        eq(entryRevisions.version, version),
+      ))
+    return (row as RevisionRow | undefined) ?? null
+  }
+
+  async restore(entryId: string, version: number, opts: { userId: string; locale?: string }): Promise<void> {
+    const locale = opts.locale ?? DEFAULT_LOCALE
+    const target = await this.getVersion(entryId, version, locale)
+    if (!target) throw new NotFoundError(`Revision ${version} for ${entryId} (${locale}) not found`)
+    const repo = new EntriesRepo(this.db)
+    await repo.updateWithRevision(entryId, {
+      locale,
+      content: target.content,
+      updatedBy: opts.userId,
+      changeSummary: `Restored v${version}`,
+    })
+  }
+
+  /** Keep only the most recent `keep` revisions per (entry, locale). */
+  async prune(entryId: string, locale: string, keep: number): Promise<number> {
+    if (keep < 1) return 0
+    const all = await this.listByEntry(entryId, locale)
+    const toDelete = all.slice(keep)
+    for (const r of toDelete) {
+      await this.db.delete(entryRevisions).where(eq(entryRevisions.id, r.id))
+    }
+    return toDelete.length
+  }
+}

package/src/core/repos/settings.ts

@@ -0,0 +1,23 @@
+import { eq } from 'drizzle-orm'
+import type { VulseDb } from '../db.js'
+import { settings } from '../schema.js'
+
+export class SettingsRepo {
+  constructor(private db: VulseDb) {}
+
+  async get<T = unknown>(key: string): Promise<T | null> {
+    const [row] = await this.db.select().from(settings).where(eq(settings.key, key))
+    return (row?.value as T | undefined) ?? null
+  }
+
+  async set(key: string, value: unknown): Promise<void> {
+    const now = new Date()
+    await this.db.insert(settings).values({ key, value, updatedAt: now })
+      .onConflictDoUpdate({ target: settings.key, set: { value, updatedAt: now } })
+  }
+
+  async all(): Promise<Record<string, unknown>> {
+    const rows = await this.db.select().from(settings)
+    return Object.fromEntries(rows.map((r) => [r.key, r.value]))
+  }
+}

package/src/core/schema.ts

@@ -0,0 +1,244 @@
+import { sqliteTable, text, integer, index, uniqueIndex, primaryKey, type AnySQLiteColumn } from 'drizzle-orm/sqlite-core'
+import { sql } from 'drizzle-orm'
+
+// --- Vulse content (i18n model) ---
+//
+// `vulse_entries` is the single-identity shell: one row per logical entry, holding
+// only locale-independent data (tree position, ownership). Per-locale data
+// (slug, status, content, drafts) lives in `vulse_entry_locales`, keyed by
+// (entry_id, locale). Slug uniqueness is per (collection, locale).
+
+export const entries = sqliteTable('vulse_entries', {
+  id: text('id').primaryKey(),
+  collection: text('collection').notNull(),
+  parentId: text('parent_id').references((): AnySQLiteColumn => entries.id, { onDelete: 'cascade' }),
+  sortOrder: integer('sort_order').notNull().default(0),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull(),
+  createdBy: text('created_by'),
+}, (t) => ({
+  byCollection: index('vulse_entries_collection').on(t.collection),
+  byTree: index('vulse_entries_tree').on(t.collection, t.parentId, t.sortOrder),
+}))
+
+export const entryLocales = sqliteTable('vulse_entry_locales', {
+  entryId: text('entry_id').notNull().references(() => entries.id, { onDelete: 'cascade' }),
+  collection: text('collection').notNull(),
+  locale: text('locale').notNull(),
+  slug: text('slug').notNull(),
+  status: text('status', { enum: ['draft', 'published'] }).notNull().default('draft'),
+  version: integer('version').notNull().default(1),
+  content: text('content', { mode: 'json' }).notNull(),
+  draftContent: text('draft_content', { mode: 'json' }),
+  publishedAt: integer('published_at', { mode: 'timestamp_ms' }),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull(),
+  updatedBy: text('updated_by'),
+}, (t) => ({
+  pk: primaryKey({ columns: [t.entryId, t.locale] }),
+  uniqSlug: uniqueIndex('vulse_entry_locales_collection_locale_slug').on(t.collection, t.locale, t.slug),
+  byStatus: index('vulse_entry_locales_status_published').on(t.collection, t.locale, t.status, t.publishedAt),
+}))
+
+export const entryRevisions = sqliteTable('vulse_entry_revisions', {
+  id: text('id').primaryKey(),
+  entryId: text('entry_id').notNull().references(() => entries.id, { onDelete: 'cascade' }),
+  locale: text('locale').notNull(),
+  version: integer('version').notNull(),
+  content: text('content', { mode: 'json' }).notNull(),
+  authorId: text('author_id'),
+  changeSummary: text('change_summary'),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+}, (t) => ({
+  byEntry: index('vulse_entry_revisions_entry_locale_version').on(t.entryId, t.locale, t.version),
+}))
+
+export const media = sqliteTable('vulse_media', {
+  id: text('id').primaryKey(),
+  r2Key: text('r2_key').notNull(),
+  mime: text('mime').notNull(),
+  size: integer('size').notNull(),
+  width: integer('width'),
+  height: integer('height'),
+  alt: text('alt'),
+  blurhash: text('blurhash'),
+  uploadedBy: text('uploaded_by'),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  deletedAt: integer('deleted_at', { mode: 'timestamp_ms' }),
+}, (t) => ({
+  // Partial index on active rows: every list query reads `WHERE deleted_at IS NULL`.
+  active: index('vulse_media_active').on(t.createdAt).where(sql`${t.deletedAt} IS NULL`),
+}))
+
+export const vulseCollections = sqliteTable('vulse_collections', {
+  handle: text('handle').primaryKey(),
+  label: text('label').notNull(),
+  definition: text('definition', { mode: 'json' }).notNull(),
+  blueprintHash: text('blueprint_hash').notNull(),
+  // `schema_version` lets future definition-shape changes migrate row-by-row
+  // without a destructive table rewrite.
+  schemaVersion: integer('schema_version').notNull().default(1),
+  singleton: integer('singleton', { mode: 'boolean' }).notNull().default(false),
+  tree: integer('tree', { mode: 'boolean' }).notNull().default(false),
+  drafts: integer('drafts', { mode: 'boolean' }).notNull().default(false),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull(),
+})
+
+export const vulseSets = sqliteTable('vulse_sets', {
+  handle: text('handle').primaryKey(),
+  label: text('label').notNull(),
+  definition: text('definition', { mode: 'json' }).notNull(),
+  schemaVersion: integer('schema_version').notNull().default(1),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull(),
+})
+
+export const settings = sqliteTable('vulse_settings', {
+  key: text('key').primaryKey(),
+  value: text('value', { mode: 'json' }).notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull(),
+})
+
+// --- Forms ---
+
+export const vulseForms = sqliteTable('vulse_forms', {
+  handle: text('handle').primaryKey(),
+  label: text('label').notNull(),
+  definition: text('definition', { mode: 'json' }).notNull(),
+  schemaVersion: integer('schema_version').notNull().default(1),
+  enabled: integer('enabled', { mode: 'boolean' }).notNull().default(true),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull(),
+})
+
+export const vulseFormSubmissions = sqliteTable('vulse_form_submissions', {
+  id: text('id').primaryKey(),
+  formHandle: text('form_handle').notNull().references(() => vulseForms.handle, { onDelete: 'cascade' }),
+  payload: text('payload', { mode: 'json' }).notNull(),
+  fileRefs: text('file_refs', { mode: 'json' }).notNull().default([]),
+  meta: text('meta', { mode: 'json' }).notNull(),
+  status: text('status', { enum: ['received', 'processed', 'failed'] }).notNull().default('received'),
+  error: text('error'),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+}, (t) => ({
+  byFormCreated: index('vulse_form_submissions_form_created').on(t.formHandle, t.createdAt),
+  byFormStatus: index('vulse_form_submissions_form_status').on(t.formHandle, t.status),
+}))
+
+export const vulseFormUploadDrafts = sqliteTable('vulse_form_upload_drafts', {
+  id: text('id').primaryKey(),
+  formHandle: text('form_handle').notNull().references(() => vulseForms.handle, { onDelete: 'cascade' }),
+  fieldName: text('field_name').notNull(),
+  mediaId: text('media_id').notNull().references(() => media.id, { onDelete: 'cascade' }),
+  expiresAt: integer('expires_at', { mode: 'timestamp_ms' }).notNull(),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+}, (t) => ({
+  byExpires: index('vulse_form_upload_drafts_expires').on(t.expiresAt),
+}))
+
+export const vulseFormUniqueValues = sqliteTable('vulse_form_unique_values', {
+  formHandle: text('form_handle').notNull().references(() => vulseForms.handle, { onDelete: 'cascade' }),
+  fieldName: text('field_name').notNull(),
+  valueHash: text('value_hash').notNull(),
+  submissionId: text('submission_id').notNull().references(() => vulseFormSubmissions.id, { onDelete: 'cascade' }),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+}, (t) => ({
+  pk: uniqueIndex('vulse_form_unique_values_pk').on(t.formHandle, t.fieldName, t.valueHash),
+  bySubmission: index('vulse_form_unique_values_submission').on(t.submissionId),
+}))
+
+export const vulseFormRateLimits = sqliteTable('vulse_form_rate_limits', {
+  formHandle: text('form_handle').notNull(),
+  ipHash: text('ip_hash').notNull(),
+  windowStart: integer('window_start', { mode: 'timestamp_ms' }).notNull(),
+  count: integer('count').notNull().default(1),
+}, (t) => ({
+  pk: uniqueIndex('vulse_form_rate_limits_pk').on(t.formHandle, t.ipHash, t.windowStart),
+}))
+
+// --- Globals ---
+
+export const vulseGlobalSets = sqliteTable('vulse_global_sets', {
+  handle: text('handle').primaryKey(),
+  label: text('label').notNull(),
+  definition: text('definition', { mode: 'json' }).notNull(),
+  blueprintHash: text('blueprint_hash').notNull().default(''),
+  schemaVersion: integer('schema_version').notNull().default(1),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull(),
+})
+
+export const vulseGlobalValues = sqliteTable('vulse_global_values', {
+  handle: text('handle').primaryKey().references(() => vulseGlobalSets.handle, { onDelete: 'cascade' }),
+  content: text('content', { mode: 'json' }).notNull().default({}),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull(),
+})
+
+// --- Live preview ---
+
+export const vulsePreviewSessions = sqliteTable('vulse_preview_sessions', {
+  id: text('id').primaryKey(),
+  userId: text('user_id').notNull(),
+  entryId: text('entry_id'),
+  collection: text('collection').notNull(),
+  locale: text('locale').notNull().default('default'),
+  slug: text('slug').notNull(),
+  content: text('content', { mode: 'json' }).notNull(),
+  expiresAt: integer('expires_at', { mode: 'timestamp_ms' }).notNull(),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull(),
+}, (t) => ({
+  byExpires: index('vulse_preview_sessions_expires').on(t.expiresAt),
+  byUser: index('vulse_preview_sessions_user').on(t.userId),
+}))
+
+// --- Better Auth (canonical column names per better-auth Drizzle adapter) ---
+
+export const user = sqliteTable('user', {
+  id: text('id').primaryKey(),
+  name: text('name').notNull(),
+  email: text('email').notNull().unique(),
+  emailVerified: integer('email_verified', { mode: 'boolean' }).notNull().default(false),
+  image: text('image'),
+  role: text('role', { enum: ['admin', 'editor', 'member'] }).notNull().default('member'),
+  displayName: text('display_name'),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull(),
+})
+
+export const session = sqliteTable('session', {
+  id: text('id').primaryKey(),
+  userId: text('user_id').notNull().references(() => user.id, { onDelete: 'cascade' }),
+  token: text('token').notNull().unique(),
+  expiresAt: integer('expires_at', { mode: 'timestamp_ms' }).notNull(),
+  ipAddress: text('ip_address'),
+  userAgent: text('user_agent'),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull(),
+})
+
+export const account = sqliteTable('account', {
+  id: text('id').primaryKey(),
+  userId: text('user_id').notNull().references(() => user.id, { onDelete: 'cascade' }),
+  accountId: text('account_id').notNull(),
+  providerId: text('provider_id').notNull(),
+  accessToken: text('access_token'),
+  refreshToken: text('refresh_token'),
+  idToken: text('id_token'),
+  accessTokenExpiresAt: integer('access_token_expires_at', { mode: 'timestamp_ms' }),
+  refreshTokenExpiresAt: integer('refresh_token_expires_at', { mode: 'timestamp_ms' }),
+  scope: text('scope'),
+  password: text('password'),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull(),
+})
+
+export const verification = sqliteTable('verification', {
+  id: text('id').primaryKey(),
+  identifier: text('identifier').notNull(),
+  value: text('value').notNull(),
+  expiresAt: integer('expires_at', { mode: 'timestamp_ms' }).notNull(),
+  createdAt: integer('created_at', { mode: 'timestamp_ms' }).notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' }).notNull(),
+})

package/src/core/sets/compile.ts

@@ -0,0 +1,12 @@
+import type { z } from 'astro/zod'
+import { compileFieldObject } from '../blueprints/compile.js'
+import type { SetDefinition } from './definition.js'
+
+export interface CompiledSet {
+  definition: SetDefinition
+  schema: z.ZodObject<z.ZodRawShape>
+}
+
+export function compileSet(def: SetDefinition): CompiledSet {
+  return { definition: def, schema: compileFieldObject(def.fields) }
+}

package/src/core/sets/definition.ts

@@ -0,0 +1,10 @@
+import { z } from 'astro/zod'
+import { NestedFieldDefinitionSchema } from '../blueprints/definition.js'
+
+export const SetDefinitionSchema = z.object({
+  handle: z.string().regex(/^[a-z][a-z0-9_-]*$/),
+  label: z.string().min(1),
+  fields: z.array(NestedFieldDefinitionSchema).min(1),
+})
+
+export type SetDefinition = z.infer<typeof SetDefinitionSchema>

package/src/core/sets/service.ts

@@ -0,0 +1,82 @@
+import { eq } from 'drizzle-orm'
+import type { VulseDb } from '../db.js'
+import { vulseSets } from '../schema.js'
+import { ValidationError } from '../errors.js'
+import { type SetDefinition, SetDefinitionSchema } from './definition.js'
+
+export interface SetDTO extends SetDefinition {
+  createdAt: string
+  updatedAt: string
+}
+
+function parseRow(row: {
+  handle: string
+  definition: unknown
+  createdAt: Date
+  updatedAt: Date
+}): SetDTO {
+  const def = SetDefinitionSchema.parse(row.definition)
+  return {
+    ...def,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  }
+}
+
+export async function createSet(db: VulseDb, input: SetDefinition): Promise<SetDTO> {
+  const parsed = SetDefinitionSchema.safeParse(input)
+  if (!parsed.success) throw new ValidationError('Invalid set', { issues: parsed.error.issues })
+  const def = parsed.data
+  const now = new Date()
+  await db.insert(vulseSets).values({
+    handle: def.handle,
+    label: def.label,
+    definition: def,
+    createdAt: now,
+    updatedAt: now,
+  })
+  const created = await getSet(db, def.handle)
+  if (!created) throw new Error(`set not found after create: ${def.handle}`)
+  return created
+}
+
+export async function listSets(db: VulseDb): Promise<SetDTO[]> {
+  const rows = await db.select().from(vulseSets).orderBy(vulseSets.createdAt)
+  return rows.map(parseRow)
+}
+
+export async function getSet(db: VulseDb, handle: string): Promise<SetDTO | null> {
+  const row = await db.select().from(vulseSets).where(eq(vulseSets.handle, handle)).get()
+  return row ? parseRow(row) : null
+}
+
+export async function updateSet(db: VulseDb, handle: string, input: SetDefinition): Promise<SetDTO> {
+  if (input.handle !== handle) {
+    throw new Error(`set handle is immutable (got '${input.handle}', expected '${handle}')`)
+  }
+  const parsed = SetDefinitionSchema.safeParse(input)
+  if (!parsed.success) throw new ValidationError('Invalid set', { issues: parsed.error.issues })
+  const def = parsed.data
+  await db.update(vulseSets).set({
+    label: def.label,
+    definition: def,
+    updatedAt: new Date(),
+  }).where(eq(vulseSets.handle, handle))
+  const out = await getSet(db, handle)
+  if (!out) throw new Error(`set not found: ${handle}`)
+  return out
+}
+
+export async function deleteSet(db: VulseDb, handle: string): Promise<void> {
+  await db.delete(vulseSets).where(eq(vulseSets.handle, handle))
+}
+
+export async function loadCompiledSets(db: VulseDb): Promise<Map<string, import('./compile.js').CompiledSet>> {
+  const { compileSet } = await import('./compile.js')
+  const rows = await listSets(db)
+  const map = new Map<string, import('./compile.js').CompiledSet>()
+  for (const row of rows) {
+    map.set(row.handle, compileSet(row))
+  }
+  return map
+}

package/src/core/sets/validate-tree.ts

@@ -0,0 +1,57 @@
+import type { z } from 'astro/zod'
+import type { CompiledSet } from './compile.js'
+
+interface PMNode {
+  type?: unknown
+  attrs?: unknown
+  content?: unknown
+}
+
+function isNode(v: unknown): v is PMNode {
+  return typeof v === 'object' && v !== null && 'type' in v
+}
+
+export function validateSetNodes(
+  doc: unknown,
+  basePath: (string | number)[],
+  sets: Map<string, CompiledSet>,
+  ctx: z.core.$RefinementCtx,
+): void {
+  if (!isNode(doc)) return
+  walk(doc, basePath)
+
+  function walk(node: PMNode, path: (string | number)[]): void {
+    if (node.type === 'vulseSet') {
+      const attrs = (node.attrs ?? {}) as Record<string, unknown>
+      const handle = typeof attrs.set === 'string' ? attrs.set : undefined
+      const data = (attrs.data ?? {}) as unknown
+      const compiled = handle ? sets.get(handle) : undefined
+
+      if (!compiled) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [...path, 'set'],
+          message: `unknown set: ${handle ?? '(empty)'}`,
+        })
+        return
+      }
+
+      const parsed = compiled.schema.safeParse(data)
+      if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+          ctx.addIssue({
+            ...issue,
+            path: [...path, 'data', ...issue.path],
+          })
+        }
+      }
+      return
+    }
+
+    if (Array.isArray(node.content)) {
+      node.content.forEach((child: unknown, i: number) => {
+        if (isNode(child)) walk(child, [...path, 'content', i])
+      })
+    }
+  }
+}

package/src/core/sha256.ts

@@ -0,0 +1,10 @@
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+/** Workers-safe SHA-256 hex digest (no node:crypto). */
+export async function sha256Hex(input: string): Promise<string> {
+  const data = new TextEncoder().encode(input)
+  const hash = await crypto.subtle.digest('SHA-256', data)
+  return bytesToHex(new Uint8Array(hash))
+}

package/src/core/slug.ts

@@ -0,0 +1,30 @@
+const VALID_SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+export function normalizeSlug(input: string): string {
+  return input
+    .normalize('NFKD').replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-')
+}
+
+export function isValidSlug(input: string): boolean {
+  return VALID_SLUG.test(input)
+}
+
+const VALID_FIELD_HANDLE = /^[a-zA-Z_][a-zA-Z0-9_]*$/
+
+export function normalizeFieldHandle(input: string): string {
+  return input
+    .normalize('NFKD').replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9_]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .replace(/_+/g, '_')
+    .replace(/^[^a-z_]+/, '')
+}
+
+export function isValidFieldHandle(input: string): boolean {
+  return VALID_FIELD_HANDLE.test(input)
+}

package/src/scaffold/collection-write.ts

@@ -0,0 +1,83 @@
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import {
+  type CollectionScaffoldInput,
+  generateCollectionScaffoldFiles,
+  patchContentConfig,
+} from './collection.js'
+
+export interface WriteCollectionScaffoldOptions {
+  force?: boolean
+  skipBlueprint?: boolean
+  skipPages?: boolean
+  skipContentConfig?: boolean
+}
+
+export interface WriteCollectionScaffoldResult {
+  written: string[]
+  skipped: string[]
+  patched: string[]
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function writeCollectionScaffold(
+  cwd: string,
+  input: CollectionScaffoldInput,
+  opts: WriteCollectionScaffoldOptions = {},
+): Promise<WriteCollectionScaffoldResult> {
+  const written: string[] = []
+  const skipped: string[] = []
+  const patched: string[] = []
+
+  const files = generateCollectionScaffoldFiles(input, {
+    includeBlueprint: !opts.skipBlueprint,
+    includeContentConfig: false,
+    includeIndex: !opts.skipPages && !!input.indexRoute?.trim(),
+  }).filter((file) => !opts.skipPages || !file.path.startsWith('src/pages/'))
+
+  for (const file of files) {
+    const abs = join(cwd, file.path)
+    if (await exists(abs) && !opts.force) {
+      skipped.push(file.path)
+      continue
+    }
+    await mkdir(dirname(abs), { recursive: true })
+    await writeFile(abs, file.content, 'utf8')
+    written.push(file.path)
+  }
+
+  if (!opts.skipContentConfig) {
+    const configPath = join(cwd, 'src/content.config.ts')
+    if (await exists(configPath)) {
+      const existing = await readFile(configPath, 'utf8')
+      const next = patchContentConfig(existing, input)
+      if (next !== existing) {
+        await writeFile(configPath, next, 'utf8')
+        patched.push('src/content.config.ts')
+      } else if (existing.includes(`${input.handle}:`)) {
+        skipped.push('src/content.config.ts (already configured)')
+      }
+    } else {
+      const content = generateCollectionScaffoldFiles(input, {
+        includeBlueprint: false,
+        includeContentConfig: true,
+        includeIndex: false,
+      })[0]
+      if (content) {
+        await mkdir(dirname(configPath), { recursive: true })
+        await writeFile(configPath, content.content, 'utf8')
+        written.push('src/content.config.ts')
+      }
+    }
+  }
+
+  return { written, skipped, patched }
+}