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

package/src/core/db.ts

@@ -0,0 +1,11 @@
+import { drizzle } from 'drizzle-orm/d1'
+import * as schema from './schema.js'
+
+export type VulseDb = ReturnType<typeof createDb>
+
+export function createDb(binding: D1Database) {
+  if (!binding) throw new Error('Vulse: D1 binding "DB" is missing. Add it to wrangler.toml.')
+  return drizzle(binding, { schema })
+}
+
+export * as schema from './schema.js'

package/src/core/errors.ts

@@ -0,0 +1,34 @@
+export type ErrorCode = 'VALIDATION' | 'NOT_FOUND' | 'ACCESS_DENIED' | 'CONFLICT' | 'INTERNAL'
+
+export class VulseError extends Error {
+  readonly code: ErrorCode
+  readonly status: number
+  readonly details?: Record<string, unknown>
+
+  constructor(code: ErrorCode, status: number, message: string, details?: Record<string, unknown>) {
+    super(message)
+    this.name = 'VulseError'
+    this.code = code
+    this.status = status
+    if (details !== undefined) {
+      this.details = details
+    }
+  }
+
+  static isVulseError(e: unknown): e is VulseError {
+    return e instanceof VulseError
+  }
+}
+
+export class ValidationError extends VulseError {
+  constructor(message: string, details?: Record<string, unknown>) { super('VALIDATION', 422, message, details) }
+}
+export class NotFoundError extends VulseError {
+  constructor(message = 'Not found') { super('NOT_FOUND', 404, message) }
+}
+export class AccessDeniedError extends VulseError {
+  constructor(message = 'Access denied') { super('ACCESS_DENIED', 403, message) }
+}
+export class ConflictError extends VulseError {
+  constructor(message: string, details?: Record<string, unknown>) { super('CONFLICT', 409, message, details) }
+}

package/src/core/forms/compile.ts

@@ -0,0 +1,84 @@
+import { z } from 'astro/zod'
+import type { FormDefinition, FormFieldDefinition } from './definition.js'
+
+export interface CompiledForm {
+  schema: z.ZodObject<z.ZodRawShape>
+  inputFields: FormFieldDefinition[]
+  uniqueFields: string[]
+}
+
+const LAYOUT_KINDS = new Set(['submit', 'honeypot'])
+
+export function compileForm(def: FormDefinition): CompiledForm {
+  const inputFields = def.fields.filter((f) => !LAYOUT_KINDS.has(f.ui.kind))
+  const uniqueFields = inputFields
+    .filter((f) => f.validation?.unique)
+    .map((f) => f.name)
+
+  const shape: Record<string, z.ZodTypeAny> = {}
+  for (const field of inputFields) {
+    shape[field.name] = compileFormField(field)
+  }
+
+  return {
+    schema: z.object(shape),
+    inputFields,
+    uniqueFields,
+  }
+}
+
+function compileFormField(f: FormFieldDefinition): z.ZodTypeAny {
+  let s: z.ZodTypeAny = z.never()
+  const v = f.validation
+
+  switch (f.ui.kind) {
+    case 'text':
+    case 'textarea': {
+      let str = z.string()
+      if (v?.min !== undefined) str = str.min(v.min)
+      if (v?.max !== undefined) str = str.max(v.max)
+      if (v?.pattern) str = str.regex(new RegExp(v.pattern))
+      if (v?.url) str = str.url()
+      s = str
+      break
+    }
+    case 'email': {
+      let str = z.string().email()
+      if (v?.min !== undefined) str = str.min(v.min)
+      if (v?.max !== undefined) str = str.max(v.max)
+      s = str
+      break
+    }
+    case 'number': {
+      let num = v?.integer ? z.coerce.number().int() : z.coerce.number()
+      if (v?.min !== undefined) num = num.min(v.min)
+      if (v?.max !== undefined) num = num.max(v.max)
+      s = num
+      break
+    }
+    case 'date':
+    case 'time':
+    case 'datetime':
+      s = z.string()
+      break
+    case 'select':
+    case 'radio':
+      s = z.enum(f.ui.options as [string, ...string[]])
+      break
+    case 'checkbox':
+      s = z.boolean()
+      break
+    case 'file':
+      s = z.string().min(1)
+      break
+    case 'hidden':
+      s = z.string()
+      break
+  }
+
+  if (f.default !== undefined) s = s.default(f.default)
+  if (f.optional && !v?.required) s = s.optional()
+  else if (v?.required) s = s.refine((val) => val !== '' && val !== undefined && val !== null, { message: 'Required' })
+
+  return s
+}

package/src/core/forms/definition.ts

@@ -0,0 +1,102 @@
+import { z } from 'astro/zod'
+
+const handleRegex = /^[a-z][a-z0-9_-]*$/
+const fieldNameRegex = /^[a-z_][a-z0-9_-]*$/
+
+export const FormFieldValidationSchema = z.object({
+  required: z.boolean().optional(),
+  min: z.number().optional(),
+  max: z.number().optional(),
+  pattern: z.string().optional(),
+  email: z.boolean().optional(),
+  url: z.boolean().optional(),
+  integer: z.boolean().optional(),
+  unique: z.boolean().optional(),
+})
+
+export type FormFieldValidation = z.infer<typeof FormFieldValidationSchema>
+
+export const FormFieldUiSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('text') }),
+  z.object({ kind: z.literal('textarea') }),
+  z.object({ kind: z.literal('email') }),
+  z.object({ kind: z.literal('number') }),
+  z.object({ kind: z.literal('date') }),
+  z.object({ kind: z.literal('time') }),
+  z.object({ kind: z.literal('datetime') }),
+  z.object({ kind: z.enum(['select', 'radio']), options: z.array(z.string()).min(1) }),
+  z.object({ kind: z.literal('checkbox'), label: z.string().optional() }),
+  z.object({
+    kind: z.literal('file'),
+    accept: z.array(z.string()).optional(),
+    maxBytes: z.number().int().positive().optional(),
+  }),
+  z.object({ kind: z.literal('hidden'), value: z.string().optional() }),
+  z.object({ kind: z.literal('honeypot') }),
+  z.object({ kind: z.literal('submit'), label: z.string().optional() }),
+])
+
+export type FormFieldUi = z.infer<typeof FormFieldUiSchema>
+
+export const FormFieldDefinitionSchema = z.object({
+  name: z.string().regex(fieldNameRegex),
+  label: z.string().optional(),
+  ui: FormFieldUiSchema,
+  optional: z.boolean(),
+  default: z.unknown().optional(),
+  validation: FormFieldValidationSchema.optional(),
+})
+
+export type FormFieldDefinition = z.infer<typeof FormFieldDefinitionSchema>
+
+export const FormSettingsSchema = z.object({
+  enabled: z.boolean().default(true),
+  successMessage: z.string().optional(),
+  redirectTo: z.string().optional(),
+  honeypotField: z.string().optional(),
+  rateLimit: z.object({
+    maxPerIp: z.number().int().positive(),
+    windowSec: z.number().int().positive(),
+  }).optional(),
+  uploadDraftTtlHours: z.number().int().positive().optional(),
+  notifyEmails: z.array(z.string().email()).optional(),
+  confirmationEmail: z.object({
+    enabled: z.boolean(),
+    toField: z.string(),
+    subject: z.string(),
+    bodyTemplate: z.string(),
+  }).optional(),
+})
+
+export type FormSettings = z.infer<typeof FormSettingsSchema>
+
+export const FormActionSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('notify'),
+    emails: z.array(z.string().email()),
+    template: z.string().optional(),
+  }),
+  z.object({
+    type: z.literal('confirmation'),
+    toField: z.string(),
+    subject: z.string(),
+    bodyTemplate: z.string(),
+  }),
+  z.object({
+    type: z.literal('webhook'),
+    url: z.string().url(),
+    headers: z.record(z.string(), z.string()).optional(),
+  }),
+])
+
+export type FormAction = z.infer<typeof FormActionSchema>
+
+export const FormDefinitionSchema = z.object({
+  handle: z.string().regex(handleRegex),
+  label: z.string().min(1),
+  fields: z.array(FormFieldDefinitionSchema).default([]),
+  settings: FormSettingsSchema,
+  actions: z.array(FormActionSchema).default([]),
+})
+
+export type FormDefinition = z.infer<typeof FormDefinitionSchema>

package/src/core/forms/rate-limit.ts

@@ -0,0 +1,52 @@
+import { sha256Hex } from '../sha256.js'
+import { eq, and, lt } from 'drizzle-orm'
+import type { VulseDb } from '../db.js'
+import { vulseFormRateLimits } from '../schema.js'
+
+export async function hashIp(ip: string): Promise<string> {
+  return sha256Hex(ip)
+}
+
+export async function checkRateLimit(
+  db: VulseDb,
+  formHandle: string,
+  ipHash: string,
+  opts: { maxPerIp: number; windowSec: number } = { maxPerIp: 10, windowSec: 3600 },
+): Promise<{ allowed: boolean; retryAfterSec?: number }> {
+  const windowMs = opts.windowSec * 1000
+  const now = Date.now()
+  const windowStart = new Date(Math.floor(now / windowMs) * windowMs)
+
+  const existing = await db.select().from(vulseFormRateLimits)
+    .where(and(
+      eq(vulseFormRateLimits.formHandle, formHandle),
+      eq(vulseFormRateLimits.ipHash, ipHash),
+      eq(vulseFormRateLimits.windowStart, windowStart),
+    ))
+    .get()
+
+  if (!existing) {
+    await db.insert(vulseFormRateLimits).values({
+      formHandle,
+      ipHash,
+      windowStart,
+      count: 1,
+    })
+    return { allowed: true }
+  }
+
+  if (existing.count >= opts.maxPerIp) {
+    const retryAfterSec = Math.ceil((windowStart.getTime() + windowMs - now) / 1000)
+    return { allowed: false, retryAfterSec }
+  }
+
+  await db.update(vulseFormRateLimits)
+    .set({ count: existing.count + 1 })
+    .where(and(
+      eq(vulseFormRateLimits.formHandle, formHandle),
+      eq(vulseFormRateLimits.ipHash, ipHash),
+      eq(vulseFormRateLimits.windowStart, windowStart),
+    ))
+
+  return { allowed: true }
+}

package/src/core/forms/unique.ts

@@ -0,0 +1,38 @@
+import { sha256Hex } from '../sha256.js'
+import type { VulseDb } from '../db.js'
+import { vulseFormUniqueValues } from '../schema.js'
+import { ConflictError } from '../errors.js'
+
+export function normalizeUniqueValue(value: unknown): string {
+  return String(value).trim().toLowerCase()
+}
+
+export async function hashUniqueValue(value: unknown): Promise<string> {
+  return sha256Hex(normalizeUniqueValue(value))
+}
+
+export async function insertUniqueValues(
+  db: VulseDb,
+  formHandle: string,
+  submissionId: string,
+  fields: Record<string, unknown>,
+  uniqueFieldNames: string[],
+): Promise<void> {
+  const now = new Date()
+  for (const name of uniqueFieldNames) {
+    const value = fields[name]
+    if (value === undefined || value === null || value === '') continue
+    const valueHash = await hashUniqueValue(value)
+    try {
+      await db.insert(vulseFormUniqueValues).values({
+        formHandle,
+        fieldName: name,
+        valueHash,
+        submissionId,
+        createdAt: now,
+      })
+    } catch {
+      throw new ConflictError(`Duplicate value for field "${name}"`, { field: name })
+    }
+  }
+}

package/src/core/globals/compile.ts

@@ -0,0 +1,35 @@
+import type { z } from 'astro/zod'
+import { compileBlueprintSchema } from '../blueprints/compile.js'
+import type { CompiledSet } from '../sets/compile.js'
+import type { FieldDefinition } from '../blueprints/definition.js'
+import { type GlobalSetDefinition, hashGlobalSetDefinition } from './definition.js'
+
+export interface CompiledGlobalSet {
+  handle: string
+  label: string
+  fields: FieldDefinition[]
+  schema: z.ZodObject<z.ZodRawShape>
+  hash: string
+}
+
+export async function compileGlobalSet(
+  def: GlobalSetDefinition,
+  sets?: Map<string, CompiledSet>,
+): Promise<CompiledGlobalSet> {
+  const options = sets ? { sets } : {}
+  return {
+    handle: def.handle,
+    label: def.label,
+    fields: def.fields,
+    schema: compileBlueprintSchema(
+      {
+        handle: def.handle,
+        label: def.label,
+        singleton: true,
+        fields: def.fields,
+      },
+      options,
+    ),
+    hash: await hashGlobalSetDefinition(def),
+  }
+}

package/src/core/globals/definition.ts

@@ -0,0 +1,27 @@
+import { z } from 'astro/zod'
+import { sha256Hex } from '../sha256.js'
+import { type FieldDefinition, FieldDefinitionSchema } from '../blueprints/definition.js'
+
+export const GlobalSetDefinitionSchema = z.object({
+  handle: z.string().regex(/^[a-z][a-z0-9_-]*$/),
+  label: z.string().min(1),
+  fields: z.array(FieldDefinitionSchema).default([]),
+})
+
+export type GlobalSetDefinition = z.infer<typeof GlobalSetDefinitionSchema>
+
+export async function hashGlobalSetDefinition(def: GlobalSetDefinition): Promise<string> {
+  const canonical = JSON.stringify({
+    handle: def.handle,
+    label: def.label,
+    fields: def.fields.map((f: FieldDefinition) => ({
+      name: f.name,
+      label: f.label ?? null,
+      ui: f.ui,
+      optional: f.optional,
+      default: f.default ?? null,
+      validation: f.validation ?? null,
+    })),
+  })
+  return sha256Hex(canonical)
+}

package/src/core/locales.ts

@@ -0,0 +1,45 @@
+import type { VulseDb } from './db.js'
+import { SettingsRepo } from './repos/settings.js'
+import { DEFAULT_LOCALE } from './repos/entries.js'
+
+export const LOCALES_KEY = 'locales'
+export const DEFAULT_LOCALE_KEY = 'defaultLocale'
+
+// BCP-47-ish: 2-3 letter base + optional region. Conservative, easy to extend later.
+const LOCALE_CODE_RE = /^[a-z]{2,3}(-[A-Z]{2})?$/
+
+export interface LocalesConfig {
+  /** Ordered list of locales supported by the site. Always contains defaultLocale. */
+  locales: string[]
+  /** The locale used when none is specified. */
+  defaultLocale: string
+}
+
+export function isValidLocaleCode(code: string): boolean {
+  return code === DEFAULT_LOCALE || LOCALE_CODE_RE.test(code)
+}
+
+export async function readLocalesConfig(db: VulseDb): Promise<LocalesConfig> {
+  const repo = new SettingsRepo(db)
+  const [raw, def] = await Promise.all([
+    repo.get<unknown>(LOCALES_KEY),
+    repo.get<string>(DEFAULT_LOCALE_KEY),
+  ])
+  const locales = Array.isArray(raw)
+    ? raw.filter((v): v is string => typeof v === 'string' && isValidLocaleCode(v))
+    : []
+  const defaultLocale = typeof def === 'string' && isValidLocaleCode(def) ? def : DEFAULT_LOCALE
+  if (locales.length === 0) locales.push(defaultLocale)
+  if (!locales.includes(defaultLocale)) locales.unshift(defaultLocale)
+  return { locales, defaultLocale }
+}
+
+/** Validate a locale param against site configuration; throws if unknown. */
+export async function resolveLocale(db: VulseDb, candidate: string | null | undefined): Promise<string> {
+  const cfg = await readLocalesConfig(db)
+  if (!candidate || candidate === DEFAULT_LOCALE) return cfg.defaultLocale
+  if (!cfg.locales.includes(candidate)) {
+    throw new Error(`Unknown locale '${candidate}'. Supported: ${cfg.locales.join(', ')}`)
+  }
+  return candidate
+}

package/src/core/migrations.ts

@@ -0,0 +1,48 @@
+import initSql from '../../migrations/0000_init.sql?raw'
+import collectionsSetsSql from '../../migrations/0001_collections_sets.sql?raw'
+import ftsSql from '../../migrations/0003_fts.sql?raw'
+import formsSql from '../../migrations/0004_forms.sql?raw'
+import globalsSql from '../../migrations/0005_globals.sql?raw'
+import previewSessionsSql from '../../migrations/0006_preview_sessions.sql?raw'
+
+const MIGRATIONS = [
+  { id: '0000_init', sql: initSql },
+  { id: '0001_collections_sets', sql: collectionsSetsSql },
+  // 0002_tree_drafts was folded into 0000_init when the schema was reshaped for
+  // i18n. The ID is intentionally skipped so the ledger remains forward-only.
+  { id: '0003_fts', sql: ftsSql },
+  { id: '0004_forms', sql: formsSql },
+  { id: '0005_globals', sql: globalsSql },
+  { id: '0006_preview_sessions', sql: previewSessionsSql },
+] as const
+
+function splitStatements(sql: string): string[] {
+  return sql
+    .split('--> statement-breakpoint')
+    .map((s) => s.trim())
+    .filter(Boolean)
+}
+
+/** Applies bundled SQL migrations directly to a D1 binding (used in tests and Workers). */
+export async function applyMigrations(db: D1Database): Promise<void> {
+  await db.exec(
+    'CREATE TABLE IF NOT EXISTS _vulse_migrations (id TEXT PRIMARY KEY, applied_at INTEGER NOT NULL)',
+  )
+
+  for (const migration of MIGRATIONS) {
+    const applied = await db
+      .prepare('SELECT id FROM _vulse_migrations WHERE id = ?')
+      .bind(migration.id)
+      .first()
+    if (applied) continue
+
+    for (const stmt of splitStatements(migration.sql)) {
+      await db.exec(stmt.replace(/\s+/g, ' '))
+    }
+
+    await db
+      .prepare('INSERT INTO _vulse_migrations (id, applied_at) VALUES (?, ?)')
+      .bind(migration.id, Date.now())
+      .run()
+  }
+}

package/src/core/parse-content.ts

@@ -0,0 +1,85 @@
+import type { z } from 'astro/zod'
+import { ValidationError } from './errors.js'
+
+export interface ContentValidationIssue {
+  path: (string | number)[]
+  message: string
+  code?: string
+}
+
+/**
+ * Parses arbitrary content against a Zod schema. On failure, throws a
+ * ValidationError whose message names the first offending field (so the
+ * top-level error banner reads sensibly) and whose `details.issues` carries
+ * the full list with humanized messages for inline field display.
+ */
+export function parseContent<S extends z.ZodTypeAny>(schema: S, content: unknown): z.infer<S> {
+  const parsed = schema.safeParse(content)
+  if (parsed.success) return parsed.data
+
+  const issues: ContentValidationIssue[] = parsed.error.issues.map((issue) => ({
+    path: issue.path.filter((p): p is string | number => typeof p === 'string' || typeof p === 'number'),
+    message: humanizeIssue(issue),
+    code: issue.code,
+  }))
+
+  throw new ValidationError(summarize(issues), { issues })
+}
+
+function summarize(issues: ContentValidationIssue[]): string {
+  if (issues.length === 0) return 'Validation failed'
+  const first = issues[0]!
+  const fieldLabel = first.path.length ? first.path.join('.') : 'Content'
+  if (issues.length === 1) return `${fieldLabel}: ${first.message}`
+  return `${fieldLabel}: ${first.message} (and ${issues.length - 1} more issue${issues.length - 1 === 1 ? '' : 's'})`
+}
+
+interface ZodIssueLike {
+  code: string
+  message: string
+  path: (string | number | symbol)[]
+  // Zod 4 fields
+  expected?: string
+  origin?: string
+  minimum?: number | bigint
+  maximum?: number | bigint
+  inclusive?: boolean
+  format?: string
+  // Zod 3 fields (kept for compatibility)
+  received?: string
+  type?: string
+  validation?: string
+}
+
+function humanizeIssue(issue: unknown): string {
+  const i = issue as ZodIssueLike
+
+  // Missing required value.
+  if (i.code === 'invalid_type') {
+    if (i.received === 'undefined' || i.received === 'null') return 'This field is required.'
+    if (/received (undefined|null)/.test(i.message)) return 'This field is required.'
+    if (i.expected) return `Expected ${i.expected}.`
+  }
+
+  // Length / numeric bounds.
+  const origin = i.origin ?? i.type
+  if (i.code === 'too_small') {
+    if (origin === 'string' && Number(i.minimum) === 1) return 'This field is required.'
+    if (origin === 'string') return `Must be at least ${i.minimum} characters.`
+    if (origin === 'number') return `Must be ${i.inclusive ? 'at least' : 'greater than'} ${i.minimum}.`
+    if (origin === 'array') return `Add at least ${i.minimum} item${i.minimum === 1 ? '' : 's'}.`
+  }
+  if (i.code === 'too_big') {
+    if (origin === 'string') return `Must be at most ${i.maximum} characters.`
+    if (origin === 'number') return `Must be ${i.inclusive ? 'at most' : 'less than'} ${i.maximum}.`
+    if (origin === 'array') return `No more than ${i.maximum} item${i.maximum === 1 ? '' : 's'}.`
+  }
+
+  // String formats (Zod 4: invalid_format with format; Zod 3: invalid_string with validation).
+  const fmt = i.format ?? i.validation
+  if (fmt === 'email') return 'Enter a valid email address.'
+  if (fmt === 'url') return 'Enter a valid URL.'
+
+  if (i.message === 'Required') return 'This field is required.'
+  return i.message
+}