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

package/src/core/blueprints/definition.ts

@@ -0,0 +1,185 @@
+import { z } from 'astro/zod'
+import { SeoFieldMappingSchema } from './seo.js'
+
+export const SelectOptionSchema = z.union([
+  z.string().min(1),
+  z.object({ key: z.string().min(1), label: z.string().min(1) }),
+])
+
+export const LinkValueSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('url'), url: z.string().min(1) }),
+  z.object({
+    type: z.literal('entry'),
+    entryId: z.string().min(1),
+    collection: z.string().min(1),
+  }),
+  z.object({ type: z.literal('first-child') }),
+])
+
+const textFieldUiSchema = z.object({ kind: z.literal('text') })
+const textareaFieldUiSchema = z.object({ kind: z.literal('textarea') })
+const blocksFieldUiSchema = z.object({
+  kind: z.literal('blocks'),
+  sets: z.array(z.string().regex(/^[a-z][a-z0-9_-]*$/)).optional(),
+})
+const dateFieldUiSchema = z.object({ kind: z.literal('date') })
+const booleanFieldUiSchema = z.object({ kind: z.literal('boolean') })
+const selectFieldUiSchema = z.object({
+  kind: z.literal('select'),
+  options: z.array(SelectOptionSchema).min(1),
+  multiple: z.boolean().optional(),
+  placeholder: z.string().optional(),
+  clearable: z.boolean().optional(),
+})
+const relationshipFieldUiSchema = z.object({
+  kind: z.literal('relationship'),
+  to: z.string().min(1),
+})
+const entryFieldUiSchema = z.object({
+  kind: z.literal('entry'),
+  collections: z.array(z.string().min(1)).min(1),
+})
+const entriesFieldUiSchema = z.object({
+  kind: z.literal('entries'),
+  collections: z.array(z.string().min(1)).min(1),
+  max: z.number().int().positive().optional(),
+})
+const linkFieldUiSchema = z.object({
+  kind: z.literal('link'),
+  collections: z.array(z.string().min(1)).optional(),
+})
+const assetFieldUiSchema = z.object({ kind: z.literal('asset') })
+
+const nonReplicatorFieldUiSchemas = [
+  textFieldUiSchema,
+  textareaFieldUiSchema,
+  blocksFieldUiSchema,
+  dateFieldUiSchema,
+  booleanFieldUiSchema,
+  selectFieldUiSchema,
+  relationshipFieldUiSchema,
+  entryFieldUiSchema,
+  entriesFieldUiSchema,
+  linkFieldUiSchema,
+  assetFieldUiSchema,
+] as const
+
+export const NonReplicatorFieldUiSchema = z.discriminatedUnion('kind', nonReplicatorFieldUiSchemas)
+
+export const FieldValidationSchema = z
+  .object({
+    min: z.number().int().nonnegative().optional(),
+    max: z.number().int().positive().optional(),
+  })
+  .optional()
+
+export const NestedFieldDefinitionSchema = z.object({
+  name: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/),
+  label: z.string().optional(),
+  ui: NonReplicatorFieldUiSchema,
+  optional: z.boolean(),
+  default: z.unknown().optional(),
+  validation: FieldValidationSchema,
+})
+
+export const ReplicatorSetSchema = z.object({
+  name: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/),
+  label: z.string().optional(),
+  fields: z.array(NestedFieldDefinitionSchema).min(1),
+})
+
+const replicatorFieldUiSchema = z.object({
+  kind: z.literal('replicator'),
+  sets: z.array(ReplicatorSetSchema).min(1),
+})
+
+const gridFieldUiSchema = z.object({
+  kind: z.literal('grid'),
+  fields: z.array(NestedFieldDefinitionSchema).min(1),
+  minRows: z.number().int().nonnegative().optional(),
+  maxRows: z.number().int().positive().optional(),
+  mode: z.enum(['table', 'stacked']).optional(),
+  addLabel: z.string().optional(),
+})
+
+const fieldUiSchemas = [
+  ...nonReplicatorFieldUiSchemas,
+  replicatorFieldUiSchema,
+  gridFieldUiSchema,
+] as const
+
+export const FieldUiSchema = z.discriminatedUnion('kind', fieldUiSchemas)
+
+export const FieldDefinitionSchema = z.object({
+  name: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/),
+  label: z.string().optional(),
+  ui: FieldUiSchema,
+  optional: z.boolean(),
+  default: z.unknown().optional(),
+  validation: FieldValidationSchema,
+})
+
+export const PreviewDefinitionSchema = z.object({
+  path: z
+    .string()
+    .min(1)
+    .refine((p) => p.startsWith('/'), 'path must start with /')
+    .refine((p) => p.includes('{slug}'), 'path must include {slug}'),
+  rootSelector: z.string().min(1).optional(),
+  live: z.boolean().optional(),
+})
+
+const BlueprintDefinitionObjectSchema = z.object({
+  handle: z.string().regex(/^[a-z][a-z0-9_-]*$/),
+  label: z.string().min(1),
+  singleton: z.boolean(),
+  tree: z.boolean().optional(),
+  maxDepth: z.number().int().positive().optional(),
+  drafts: z.boolean().optional(),
+  seo: z.boolean().optional(),
+  seoMapping: SeoFieldMappingSchema.optional(),
+  preview: PreviewDefinitionSchema.optional(),
+  fields: z.array(FieldDefinitionSchema).min(1),
+})
+
+function checkBlueprintConstraints(
+  d: { singleton: boolean; tree?: boolean | undefined; maxDepth?: number | undefined },
+  ctx: z.RefinementCtx,
+) {
+  if (d.singleton && d.tree) {
+    ctx.addIssue({
+      code: 'custom',
+      message: 'A blueprint cannot be both singleton and tree-structured.',
+      path: ['tree'],
+    })
+  }
+  if (d.maxDepth !== undefined && !d.tree) {
+    ctx.addIssue({
+      code: 'custom',
+      message: 'maxDepth requires tree: true.',
+      path: ['maxDepth'],
+    })
+  }
+}
+
+export const BlueprintDefinitionSchema =
+  BlueprintDefinitionObjectSchema.superRefine(checkBlueprintConstraints)
+
+export type SelectOption = z.infer<typeof SelectOptionSchema>
+export type LinkValue = z.infer<typeof LinkValueSchema>
+export type NonReplicatorFieldUi = z.infer<typeof NonReplicatorFieldUiSchema>
+export type NestedFieldDefinition = z.infer<typeof NestedFieldDefinitionSchema>
+export type ReplicatorSetDefinition = z.infer<typeof ReplicatorSetSchema>
+export type FieldUi = z.infer<typeof FieldUiSchema>
+export type FieldDefinition = z.infer<typeof FieldDefinitionSchema>
+export type PreviewDefinition = z.infer<typeof PreviewDefinitionSchema>
+export type BlueprintDefinition = z.infer<typeof BlueprintDefinitionSchema>
+
+export const FieldDefinitionWithRenameSchema = FieldDefinitionSchema.extend({
+  previousName: z.string().optional(),
+})
+export const BlueprintDefinitionWithRenamesSchema = BlueprintDefinitionObjectSchema.extend({
+  fields: z.array(FieldDefinitionWithRenameSchema).min(1),
+}).superRefine(checkBlueprintConstraints)
+export type FieldDefinitionWithRename = z.infer<typeof FieldDefinitionWithRenameSchema>
+export type BlueprintDefinitionWithRenames = z.infer<typeof BlueprintDefinitionWithRenamesSchema>

package/src/core/blueprints/load.ts

@@ -0,0 +1,144 @@
+import type { z } from 'astro/zod'
+import { BlueprintRegistry } from './registry.js'
+import type { Blueprint } from './types.js'
+import type { VulseDb } from '../db.js'
+import { createDb } from '../db.js'
+import { compileBlueprintSchema } from './compile.js'
+import { listBlueprintDefinitions } from './mutations.js'
+import { seedCodeBlueprints } from './seed.js'
+import { loadCompiledSets } from '../sets/service.js'
+import { toPreviewConfig } from './preview-path.js'
+import { applySeoToSchema, type SeoFieldMapping } from './seo.js'
+
+let registryCache: BlueprintRegistry | null = null
+let seededBlueprints: Blueprint[] | null = null
+
+async function loadBlueprintModules(): Promise<Blueprint[]> {
+  if (seededBlueprints) return seededBlueprints
+  try {
+    const mod = await import('virtual:vulse-blueprints')
+    return mod.default as Blueprint[]
+  } catch {
+    return []
+  }
+}
+
+function finalizeBlueprint(bp: Blueprint): Blueprint {
+  const seo = bp.seo === true
+  if (!seo) return bp
+  return {
+    ...bp,
+    seo: true,
+    schema: applySeoToSchema(bp.schema as z.ZodObject<z.ZodRawShape>),
+  }
+}
+
+function normalizeSeoMapping(
+  mapping: Partial<Record<keyof SeoFieldMapping, string | undefined>> | undefined,
+): SeoFieldMapping | undefined {
+  if (!mapping) return undefined
+  const out: SeoFieldMapping = {}
+  if (mapping.metaTitle !== undefined) out.metaTitle = mapping.metaTitle
+  if (mapping.metaDescription !== undefined) out.metaDescription = mapping.metaDescription
+  if (mapping.ogImage !== undefined) out.ogImage = mapping.ogImage
+  return Object.keys(out).length ? out : undefined
+}
+
+function mergeAdmin(compiled: Blueprint, code?: Blueprint): Blueprint['admin'] {
+  const admin = code?.admin ?? compiled.admin
+  const seoMapping = normalizeSeoMapping(code?.admin?.seoMapping ?? compiled.definition?.seoMapping)
+  if (!seoMapping) return admin
+  return { ...admin, seoMapping }
+}
+
+function mergeBlueprint(compiled: Blueprint, code?: Blueprint): Blueprint {
+  const rawPreview = code?.preview ?? compiled.preview
+  const preview = rawPreview ? toPreviewConfig(rawPreview) : undefined
+  const seo = code?.seo ?? compiled.seo
+  return finalizeBlueprint({
+    ...compiled,
+    admin: mergeAdmin(compiled, code),
+    ...(code?.access ? { access: code.access } : {}),
+    ...(preview ? { preview } : {}),
+    ...(seo ? { seo: true } : {}),
+  })
+}
+
+function inferAdmin(def: Blueprint['definition']): Blueprint['admin'] {
+  const titleField = def?.fields.find((f) => f.ui.kind === 'text')?.name ?? def?.fields[0]?.name ?? 'id'
+  return { titleField, listColumns: [titleField] }
+}
+
+export async function registryFromDb(db: VulseDb): Promise<BlueprintRegistry> {
+  const codeBlueprints = await loadBlueprintModules()
+  await seedCodeBlueprints(db, codeBlueprints)
+  const sets = await loadCompiledSets(db)
+  const codeByName = new Map(codeBlueprints.map((bp) => [bp.name, bp]))
+  const reg = new BlueprintRegistry()
+
+  const definitions = await listBlueprintDefinitions(db)
+  for (const def of definitions) {
+    const schema = compileBlueprintSchema(def, { sets })
+    const code = codeByName.get(def.handle)
+    const bp: Blueprint = mergeBlueprint({
+      name: def.handle,
+      label: def.label,
+      schema,
+      admin: code?.admin ?? inferAdmin(def),
+      singleton: def.singleton,
+      fields: def.fields,
+      definition: def,
+      ...(def.tree !== undefined ? { tree: def.tree } : {}),
+      ...(def.maxDepth !== undefined ? { maxDepth: def.maxDepth } : {}),
+      ...(def.drafts !== undefined ? { drafts: def.drafts } : {}),
+      ...(def.seo !== undefined ? { seo: def.seo } : {}),
+      ...(def.preview ? { preview: toPreviewConfig(def.preview) } : {}),
+    }, code)
+    reg.register(bp)
+  }
+
+  for (const code of codeBlueprints) {
+    if (!reg.has(code.name)) reg.register(finalizeBlueprint(code))
+  }
+
+  return reg
+}
+
+/** Load registry from D1 when available, otherwise code-only blueprints. */
+export async function registryForRequest(db?: VulseDb): Promise<BlueprintRegistry> {
+  if (db) {
+    return registryFromDb(db)
+  }
+  if (registryCache) return registryCache
+  try {
+    const { getRuntimeEnv } = await import('../../server/env.js')
+    const env = getRuntimeEnv()
+    const conn = createDb(env.DB)
+    registryCache = await registryFromDb(conn)
+    return registryCache
+  } catch {
+    return registryFromUserCollections()
+  }
+}
+
+export async function registryFromUserCollections(db?: VulseDb): Promise<BlueprintRegistry> {
+  if (db) return registryFromDb(db)
+  if (registryCache) return registryCache
+  const reg = new BlueprintRegistry()
+  for (const bp of await loadBlueprintModules()) {
+    reg.register(finalizeBlueprint(bp))
+  }
+  registryCache = reg
+  return reg
+}
+
+/** For tests: bypass blueprint loading with explicit blueprints. */
+export function _seedRegistry(blueprints: Blueprint[]): void {
+  seededBlueprints = blueprints
+  registryCache = null
+}
+
+export function _resetRegistry(): void {
+  registryCache = null
+  seededBlueprints = null
+}

package/src/core/blueprints/mutations.ts

@@ -0,0 +1,236 @@
+import { asc, eq, sql } from 'drizzle-orm'
+import type { VulseDb } from '../db.js'
+import { vulseCollections } from '../schema.js'
+import { NotFoundError, ValidationError } from '../errors.js'
+import { hashDefinition } from './compile.js'
+import {
+  type BlueprintDefinition,
+  BlueprintDefinitionSchema,
+  type BlueprintDefinitionWithRenames,
+  BlueprintDefinitionWithRenamesSchema,
+  type FieldDefinitionWithRename,
+  type FieldUi,
+  type NestedFieldDefinition,
+} from './definition.js'
+
+export async function createBlueprint(
+  db: VulseDb,
+  input: BlueprintDefinition,
+): Promise<BlueprintDefinition> {
+  const def = await validateNew(db, input)
+  const now = Date.now()
+  await db.insert(vulseCollections).values({
+    handle: def.handle,
+    label: def.label,
+    definition: def,
+    blueprintHash: await hashDefinition(def),
+    singleton: def.singleton,
+    tree: def.tree === true,
+    drafts: def.drafts === true,
+    createdAt: new Date(now),
+    updatedAt: new Date(now),
+  })
+  return def
+}
+
+export async function updateBlueprint(
+  db: VulseDb,
+  handle: string,
+  input: BlueprintDefinitionWithRenames,
+): Promise<BlueprintDefinition> {
+  const existing = await loadDefinition(db, handle)
+  if (!existing) throw new NotFoundError(`blueprint not found: ${handle}`)
+
+  const incoming = { ...input, handle }
+  const parsed = parseOrThrow(BlueprintDefinitionWithRenamesSchema, incoming)
+
+  const oldNames = new Set(existing.fields.map((f) => f.name))
+  for (const f of parsed.fields) {
+    if (f.previousName !== undefined && !oldNames.has(f.previousName)) {
+      throw new ValidationError(`previousName '${f.previousName}' was not in the prior definition`, {
+        issues: [{ path: ['fields', parsed.fields.indexOf(f), 'previousName'] }],
+      })
+    }
+  }
+
+  await ensureValidCrossField(db, parsed, handle)
+
+  const renames = computeRenames(parsed.fields)
+  const canonical = stripRenames(parsed)
+
+  for (const [oldName, newName] of renames) {
+    // Per-locale content lives in `vulse_entry_locales`. Rename keys in both
+    // the live `content` and the in-flight `draft_content` when present.
+    await db.run(sql`
+      UPDATE vulse_entry_locales
+      SET content = json_set(
+        json_remove(content, '$.' || ${oldName}),
+        '$.' || ${newName},
+        json_extract(content, '$.' || ${oldName})
+      )
+      WHERE collection = ${handle}
+        AND json_extract(content, '$.' || ${oldName}) IS NOT NULL
+    `)
+    await db.run(sql`
+      UPDATE vulse_entry_locales
+      SET draft_content = json_set(
+        json_remove(draft_content, '$.' || ${oldName}),
+        '$.' || ${newName},
+        json_extract(draft_content, '$.' || ${oldName})
+      )
+      WHERE collection = ${handle}
+        AND draft_content IS NOT NULL
+        AND json_extract(draft_content, '$.' || ${oldName}) IS NOT NULL
+    `)
+  }
+  await db.update(vulseCollections).set({
+    label: canonical.label,
+    definition: canonical,
+    blueprintHash: await hashDefinition(canonical),
+    singleton: canonical.singleton,
+    tree: canonical.tree === true,
+    drafts: canonical.drafts === true,
+    updatedAt: new Date(),
+  }).where(eq(vulseCollections.handle, handle))
+
+  return canonical
+}
+
+export async function deleteBlueprint(db: VulseDb, handle: string): Promise<void> {
+  const existing = await db.select({ handle: vulseCollections.handle })
+    .from(vulseCollections)
+    .where(eq(vulseCollections.handle, handle))
+    .get()
+  if (!existing) throw new NotFoundError(`blueprint not found: ${handle}`)
+  await db.delete(vulseCollections).where(eq(vulseCollections.handle, handle))
+}
+
+export async function listBlueprintDefinitions(db: VulseDb): Promise<BlueprintDefinition[]> {
+  const rows = await db.select({ definition: vulseCollections.definition })
+    .from(vulseCollections)
+    .orderBy(asc(vulseCollections.createdAt))
+  return rows.map((r) => BlueprintDefinitionSchema.parse(r.definition))
+}
+
+export async function getBlueprintDefinition(db: VulseDb, handle: string): Promise<BlueprintDefinition | null> {
+  const row = await db.select({ definition: vulseCollections.definition })
+    .from(vulseCollections)
+    .where(eq(vulseCollections.handle, handle))
+    .get()
+  if (!row) return null
+  return BlueprintDefinitionSchema.parse(row.definition)
+}
+
+async function validateNew(db: VulseDb, input: BlueprintDefinition): Promise<BlueprintDefinition> {
+  const def = parseOrThrow(BlueprintDefinitionSchema, input)
+  const dup = await db.select({ handle: vulseCollections.handle })
+    .from(vulseCollections)
+    .where(eq(vulseCollections.handle, def.handle))
+    .get()
+  if (dup) {
+    throw new ValidationError(`handle '${def.handle}' already exists`, { issues: [{ path: ['handle'] }] })
+  }
+  await ensureValidCrossField(db, def, null)
+  return def
+}
+
+async function ensureValidCrossField(
+  db: VulseDb,
+  def: BlueprintDefinition | BlueprintDefinitionWithRenames,
+  selfHandle: string | null,
+): Promise<void> {
+  await ensureValidFieldList(db, def.fields, ['fields'], selfHandle ?? def.handle)
+}
+
+async function ensureValidFieldList(
+  db: VulseDb,
+  fields: Array<{ name: string; ui: FieldUi } | NestedFieldDefinition>,
+  path: Array<string | number>,
+  currentHandle: string,
+): Promise<void> {
+  const seen = new Set<string>()
+  for (let i = 0; i < fields.length; i++) {
+    const f = fields[i]!
+    if (seen.has(f.name)) {
+      throw new ValidationError(`duplicate field name '${f.name}'`, { issues: [{ path: [...path, i, 'name'] }] })
+    }
+    seen.add(f.name)
+  }
+
+  for (let i = 0; i < fields.length; i++) {
+    const f = fields[i]!
+    if (f.ui.kind === 'relationship' && 'to' in f.ui) {
+      if (f.ui.to === currentHandle) continue
+      const target = await db.select({ handle: vulseCollections.handle })
+        .from(vulseCollections)
+        .where(eq(vulseCollections.handle, f.ui.to))
+        .get()
+      if (!target) {
+        throw new ValidationError(`relationship target '${f.ui.to}' does not exist`, {
+          issues: [{ path: [...path, i, 'ui', 'to'] }],
+        })
+      }
+    }
+
+    if (f.ui.kind === 'replicator' && 'sets' in f.ui) {
+      const seenSets = new Set<string>()
+      for (let j = 0; j < f.ui.sets.length; j++) {
+        const set = f.ui.sets[j]!
+        if (seenSets.has(set.name)) {
+          throw new ValidationError(`duplicate set name '${set.name}'`, {
+            issues: [{ path: [...path, i, 'ui', 'sets', j, 'name'] }],
+          })
+        }
+        seenSets.add(set.name)
+        await ensureValidFieldList(db, set.fields, [...path, i, 'ui', 'sets', j, 'fields'], currentHandle)
+      }
+    }
+  }
+}
+
+function computeRenames(fields: FieldDefinitionWithRename[]): Array<[string, string]> {
+  const out: Array<[string, string]> = []
+  for (const f of fields) {
+    if (f.previousName !== undefined && f.previousName !== f.name) {
+      out.push([f.previousName, f.name])
+    }
+  }
+  return out
+}
+
+function stripRenames(def: BlueprintDefinitionWithRenames): BlueprintDefinition {
+  return {
+    handle: def.handle,
+    label: def.label,
+    singleton: def.singleton,
+    ...(def.tree !== undefined ? { tree: def.tree } : {}),
+    ...(def.maxDepth !== undefined ? { maxDepth: def.maxDepth } : {}),
+    ...(def.drafts !== undefined ? { drafts: def.drafts } : {}),
+    ...(def.seo !== undefined ? { seo: def.seo } : {}),
+    ...(def.seoMapping !== undefined ? { seoMapping: def.seoMapping } : {}),
+    ...(def.preview !== undefined ? { preview: def.preview } : {}),
+    fields: def.fields.map(({ previousName: _previousName, ...rest }) => rest),
+  }
+}
+
+async function loadDefinition(db: VulseDb, handle: string): Promise<BlueprintDefinition | null> {
+  const row = await db.select({ definition: vulseCollections.definition })
+    .from(vulseCollections)
+    .where(eq(vulseCollections.handle, handle))
+    .get()
+  if (!row) return null
+  return BlueprintDefinitionSchema.parse(row.definition)
+}
+
+function parseOrThrow<T>(
+  schema: {
+    safeParse: (x: unknown) => { success: true; data: T } | { success: false; error: { issues: unknown[] } }
+  },
+  value: unknown,
+): T {
+  const result = schema.safeParse(value)
+  if (!result.success) {
+    throw new ValidationError('Validation failed', { issues: result.error.issues })
+  }
+  return result.data
+}

package/src/core/blueprints/preview-path.ts

@@ -0,0 +1,33 @@
+import type { PreviewDefinition } from './definition.js'
+import type { PreviewConfig } from './types.js'
+
+/** Normalize preview config for Blueprint types (`exactOptionalPropertyTypes`). */
+export function toPreviewConfig(preview: PreviewDefinition | PreviewConfig): PreviewConfig {
+  return {
+    path: preview.path,
+    ...(preview.rootSelector !== undefined ? { rootSelector: preview.rootSelector } : {}),
+    ...(preview.live !== undefined ? { live: preview.live } : {}),
+  }
+}
+
+/** Default public URL template for a collection's entry pages. */
+export function defaultPreviewPath(collectionHandle: string): string {
+  if (!collectionHandle || collectionHandle === 'page') return '/{slug}'
+  return `/${collectionHandle}/{slug}`
+}
+
+export function resolvePreviewPath(bp: { name: string; preview?: PreviewConfig | null }): string {
+  return bp.preview?.path ?? defaultPreviewPath(bp.name)
+}
+
+export function resolvePreviewConfig(bp: {
+  name: string
+  preview?: PreviewConfig | null
+}): PreviewConfig {
+  const path = resolvePreviewPath(bp)
+  return {
+    path,
+    ...(bp.preview?.rootSelector ? { rootSelector: bp.preview.rootSelector } : {}),
+    ...(bp.preview?.live === false ? { live: false } : {}),
+  }
+}