@pilotiq/pilotiq 0.23.1 → 0.24.2

package/src/theme/storage.test.ts

@@ -1,126 +0,0 @@
-import { describe, it, beforeEach } from 'node:test'
-import assert from 'node:assert/strict'
-import { prismaThemeStorage } from './storage.js'
-import type { PanelGlobalDelegate } from './storage.js'
-
-/**
- * Per-test stub for the prisma panelGlobal delegate. Captures the args
- * each method was called with so tests can assert the exact wire shape
- * we send Prisma (slug, JSON-encoded data, etc).
- */
-interface PrismaStub extends PanelGlobalDelegate {
-  rows: Map<string, { data: string | object | null }>
-  calls: { method: string; args: unknown }[]
-  /** When set, the next call to this method throws this error. */
-  throwOnce?: { method: 'findUnique' | 'upsert' | 'delete'; error: unknown }
-}
-
-function makeStub(initial: Record<string, unknown> = {}): PrismaStub {
-  const rows = new Map<string, { data: string | object | null }>()
-  for (const [slug, data] of Object.entries(initial)) {
-    rows.set(slug, { data: typeof data === 'string' ? data : JSON.stringify(data) })
-  }
-  const calls: { method: string; args: unknown }[] = []
-  const stub: PrismaStub = {
-    rows,
-    calls,
-    panelGlobal: {
-      async findUnique(args) {
-        calls.push({ method: 'findUnique', args })
-        if (stub.throwOnce?.method === 'findUnique') {
-          const e = stub.throwOnce.error; delete stub.throwOnce; throw e
-        }
-        return rows.get(args.where.slug) ?? null
-      },
-      async upsert(args) {
-        calls.push({ method: 'upsert', args })
-        if (stub.throwOnce?.method === 'upsert') {
-          const e = stub.throwOnce.error; delete stub.throwOnce; throw e
-        }
-        rows.set(args.where.slug, { data: args.update.data })
-        return undefined
-      },
-      async delete(args) {
-        calls.push({ method: 'delete', args })
-        if (stub.throwOnce?.method === 'delete') {
-          const e = stub.throwOnce.error; delete stub.throwOnce; throw e
-        }
-        if (!rows.has(args.where.slug)) {
-          const e: Error & { code?: string } = new Error('Record not found')
-          e.code = 'P2025'
-          throw e
-        }
-        rows.delete(args.where.slug)
-        return undefined
-      },
-    },
-  }
-  return stub
-}
-
-describe('prismaThemeStorage', () => {
-  let prisma: PrismaStub
-
-  beforeEach(() => { prisma = makeStub() })
-
-  it('load() returns null when no row exists', async () => {
-    const storage = prismaThemeStorage(prisma, { slug: 'admin__theme' })
-    assert.equal(await storage.load(), null)
-    assert.deepEqual(prisma.calls, [{ method: 'findUnique', args: { where: { slug: 'admin__theme' } } }])
-  })
-
-  it('load() parses JSON-string data', async () => {
-    prisma.rows.set('admin__theme', { data: JSON.stringify({ preset: 'nova' }) })
-    const storage = prismaThemeStorage(prisma, { slug: 'admin__theme' })
-    assert.deepEqual(await storage.load(), { preset: 'nova' })
-  })
-
-  it('load() passes through pre-parsed object data', async () => {
-    prisma.rows.set('admin__theme', { data: { preset: 'maia' } })
-    const storage = prismaThemeStorage(prisma, { slug: 'admin__theme' })
-    assert.deepEqual(await storage.load(), { preset: 'maia' })
-  })
-
-  it('save() JSON-encodes the overrides via upsert', async () => {
-    const storage = prismaThemeStorage(prisma, { slug: 'admin__theme' })
-    await storage.save({ preset: 'lyra', radius: 'medium' })
-    const stored = prisma.rows.get('admin__theme')
-    assert.ok(stored)
-    assert.equal(typeof stored.data, 'string')
-    assert.deepEqual(JSON.parse(stored.data as string), { preset: 'lyra', radius: 'medium' })
-    const upsertCall = prisma.calls.find(c => c.method === 'upsert')
-    assert.ok(upsertCall, 'expected upsert call')
-  })
-
-  it('clear() deletes the row', async () => {
-    prisma.rows.set('admin__theme', { data: '{}' })
-    const storage = prismaThemeStorage(prisma, { slug: 'admin__theme' })
-    await storage.clear()
-    assert.equal(prisma.rows.has('admin__theme'), false)
-  })
-
-  it('clear() tolerates "row not found" (P2025)', async () => {
-    const storage = prismaThemeStorage(prisma, { slug: 'admin__theme' })
-    // Row does not exist — stub throws P2025 — clear() must not propagate.
-    await storage.clear()
-  })
-
-  it('clear() rethrows non-P2025 errors', async () => {
-    prisma.rows.set('admin__theme', { data: '{}' })
-    prisma.throwOnce = { method: 'delete', error: new Error('connection lost') }
-    const storage = prismaThemeStorage(prisma, { slug: 'admin__theme' })
-    await assert.rejects(() => storage.clear(), /connection lost/)
-  })
-
-  it('save() bubbles non-P2025 errors', async () => {
-    prisma.throwOnce = { method: 'upsert', error: new Error('connection lost') }
-    const storage = prismaThemeStorage(prisma, { slug: 'admin__theme' })
-    await assert.rejects(() => storage.save({ preset: 'nova' }), /connection lost/)
-  })
-
-  it('load() bubbles errors (callers swallow if they want back-compat)', async () => {
-    prisma.throwOnce = { method: 'findUnique', error: new Error('connection lost') }
-    const storage = prismaThemeStorage(prisma, { slug: 'admin__theme' })
-    await assert.rejects(() => storage.load(), /connection lost/)
-  })
-})

package/src/theme/storage.ts

@@ -1,106 +0,0 @@
-import type { ThemeConfig } from './types.js'
-
-/**
- * Adapter that persists a panel's theme overrides — the JSON blob
- * written when a user edits theme settings via the `themeEditor()`
- * plugin and reloaded on next boot.
- *
- * The shipped implementation is `prismaThemeStorage`, which writes to
- * the `panelGlobal` row created by `@rudderjs/orm-prisma`. Apps on a
- * different ORM, key-value store, or filesystem can implement the
- * three methods themselves.
- *
- * Contract:
- *
- * - `load()` returns `null` when no overrides have been persisted yet
- *   (fresh install). Throwing surfaces a configuration error to the
- *   caller — pilotiq does not swallow.
- * - `save(overrides)` writes the blob verbatim. The next `load()` must
- *   return a deep-equal copy. Throwing surfaces to the route handler
- *   as a 500.
- * - `clear()` deletes the row. Tolerating "not found" is the adapter's
- *   responsibility — `clear()` on an empty store is a no-op.
- */
-export interface ThemeStorageAdapter {
-  load(): Promise<Partial<ThemeConfig> | null>
-  save(overrides: Partial<ThemeConfig>): Promise<void>
-  clear(): Promise<void>
-}
-
-/**
- * Minimal Prisma surface used by `prismaThemeStorage`. Narrow enough
- * to keep the import surface decoupled from `PrismaClient`'s generated
- * types — apps swap in any client whose `panelGlobal` delegate matches
- * this shape.
- */
-export interface PanelGlobalDelegate {
-  panelGlobal: {
-    findUnique(args: { where: { slug: string } }): Promise<{ data: string | object | null } | null>
-    upsert(args: {
-      where:  { slug: string }
-      update: { data: string }
-      create: { slug: string; data: string }
-    }): Promise<unknown>
-    delete(args: { where: { slug: string } }): Promise<unknown>
-  }
-}
-
-export interface PrismaThemeStorageOptions {
-  /** Row key written to `panelGlobal.slug`. Pass per-panel so multiple
-   *  panels in the same app don't clobber each other. Typically
-   *  `${panel.name}__theme`. */
-  slug: string
-}
-
-/**
- * Default storage adapter — writes JSON to the `panelGlobal` row keyed
- * by `opts.slug`. The Prisma delegate is dependency-injected so consumers
- * pick how to resolve it (e.g. `app.make('prisma')`, a direct import, a
- * test stub).
- *
- * @example
- * ```ts
- * import { Pilotiq } from '@pilotiq/pilotiq'
- * import { themeEditor, prismaThemeStorage } from '@pilotiq/pilotiq/plugins'
- *
- * const adminPanel = Pilotiq.make('Admin')
- *   .use(themeEditor({
- *     storage: prismaThemeStorage(prisma, { slug: 'admin__theme' }),
- *   }))
- * ```
- */
-export function prismaThemeStorage(
-  prisma: PanelGlobalDelegate,
-  opts:   PrismaThemeStorageOptions,
-): ThemeStorageAdapter {
-  const { slug } = opts
-  return {
-    async load() {
-      const row = await prisma.panelGlobal.findUnique({ where: { slug } })
-      if (!row?.data) return null
-      const raw = typeof row.data === 'string' ? JSON.parse(row.data) : row.data
-      return raw as Partial<ThemeConfig>
-    },
-    async save(overrides) {
-      const data = JSON.stringify(overrides)
-      await prisma.panelGlobal.upsert({
-        where:  { slug },
-        update: { data },
-        create: { slug, data },
-      })
-    },
-    async clear() {
-      try {
-        await prisma.panelGlobal.delete({ where: { slug } })
-      } catch (e) {
-        if (!isRecordNotFound(e)) throw e
-      }
-    },
-  }
-}
-
-function isRecordNotFound(e: unknown): boolean {
-  return typeof e === 'object'
-    && e !== null
-    && (e as { code?: string }).code === 'P2025'
-}

package/src/theme/theme-colors.ts

@@ -1,88 +0,0 @@
-import { colors, HUE_NAMES, type ColorScale } from './colors.js'
-import type { BaseColor, HueColor, ThemeColor, PresetDefinition } from './types.js'
-import { parseSeedToScale } from './generate-scale.js'
-
-/**
- * Theme (primary) color resolution.
- *
- * The theme color drives `--primary`, `--primary-foreground`, `--ring`, and
- * the matching sidebar variants. Built from a `ColorScale` so adding a new
- * hue is just adding an entry to `colors.ts`.
- *
- * The `'base'` sentinel means "use the current base color" — resolution
- * pulls the matching scale from `colors[baseColor]` at call time.
- *
- * Custom seeds (raw hex / oklch strings outside the `HueColor` union) are
- * parsed into a synthetic 50…950 scale via `parseSeedToScale`.
- */
-
-/**
- * Build the primary/ring overrides for a given color scale.
- *
- * `isBase` toggles between two strategies:
- *  - **base sentinel** (e.g. Theme = "Neutral"): use the strongest contrast
- *    *within the same scale* — primary is scale[900] in light, scale[50] in
- *    dark. Matches shadcn's neutral theme behavior (very dark/light primary).
- *  - **hue** (e.g. Theme = "Blue"): use scale[600] in BOTH light and dark so
- *    the brand color stays consistent across modes (instead of lifting to
- *    scale[400] in dark, which dilutes brand identity). Foreground stays the
- *    near-white neutral[50] for AA contrast against the saturated mid-tone.
- */
-function buildTheme(scale: ColorScale, isBase = false): PresetDefinition {
-  if (isBase) {
-    return {
-      light: {
-        '--primary':                      scale[900],
-        '--primary-foreground':           scale[50],
-        '--ring':                         scale[400],
-        '--sidebar-primary':              scale[900],
-        '--sidebar-primary-foreground':   scale[50],
-        '--sidebar-ring':                 scale[400],
-      },
-      dark: {
-        '--primary':                      scale[50],
-        '--primary-foreground':           scale[900],
-        '--ring':                         scale[600],
-        '--sidebar-primary':              scale[50],
-        '--sidebar-primary-foreground':   scale[900],
-        '--sidebar-ring':                 scale[600],
-      },
-    }
-  }
-  return {
-    light: {
-      '--primary':                      scale[600],
-      '--primary-foreground':           colors.neutral[50],
-      '--ring':                         scale[600],
-      '--sidebar-primary':              scale[600],
-      '--sidebar-primary-foreground':   colors.neutral[50],
-      '--sidebar-ring':                 scale[600],
-    },
-    dark: {
-      '--primary':                      scale[600],
-      '--primary-foreground':           colors.neutral[50],
-      '--ring':                         scale[600],
-      '--sidebar-primary':              scale[600],
-      '--sidebar-primary-foreground':   colors.neutral[50],
-      '--sidebar-ring':                 scale[600],
-    },
-  }
-}
-
-const themeColorMap: Record<HueColor, PresetDefinition> = Object.fromEntries(
-  HUE_NAMES.map(name => [name, buildTheme(colors[name])]),
-) as Record<HueColor, PresetDefinition>
-
-/**
- * Resolve a theme color value to its CSS variable overrides.
- *
- * @param themeColor  selected value — `'base'`, a known hue, or a raw seed string
- * @param baseColor   current base color (used to resolve `'base'` sentinel)
- */
-export function resolveThemeColor(themeColor: ThemeColor, baseColor: BaseColor): PresetDefinition {
-  if (themeColor === 'base') return buildTheme(colors[baseColor], true)
-  if (themeColor in themeColorMap) return themeColorMap[themeColor as HueColor]
-  // Custom seed — parse and synthesize a scale.
-  const synthetic = parseSeedToScale(themeColor)
-  return synthetic ? buildTheme(synthetic) : buildTheme(colors[baseColor], true)
-}

package/src/theme/types.ts

@@ -1,125 +0,0 @@
-import { BASE_COLOR_NAMES, HUE_NAMES } from './colors.js'
-
-// ─── Style Presets ─────────────────────────────────────────
-
-/** Built-in style presets — each defines a complete set of OKLCH CSS variables.
- *  `vega` is the Pilotiq brand (terracotta on cream, Satoshi). The other six are
- *  placeholder neutrals awaiting visual differentiation. */
-export type StylePreset = 'vega' | 'nova' | 'maia' | 'lyra' | 'mira' | 'luma' | 'sera'
-
-// ─── Base Colors (gray/neutral scales) ─────────────────────
-
-/** Base color scale — controls the neutral/gray tones across the UI. */
-export type BaseColor = typeof BASE_COLOR_NAMES[number]
-
-// ─── Theme + Chart Colors ──────────────────────────────────
-
-/** Hue tokens shared by both the Theme color and Chart color pickers. */
-export type HueColor = typeof HUE_NAMES[number]
-
-/** Theme (primary) color — drives buttons, links, active states, ring.
- *  `'base'` means "use the current base color's hue". Strings outside the
- *  union are treated as raw hex/oklch seeds (custom color escape hatch). */
-export type ThemeColor = 'base' | HueColor | (string & {})
-
-/** Chart palette color — drives `--chart-1..5` as a single-hue ramp.
- *  Same shape as `ThemeColor`. */
-export type ChartColor = ThemeColor
-
-// ─── Radius ────────────────────────────────────────────────
-
-/** Border radius preset. */
-export type RadiusPreset = 'none' | 'small' | 'default' | 'medium' | 'large' | 'xlarge'
-
-// ─── Spacing (UI density) ──────────────────────────────────
-
-/** Spacing density preset — drives Tailwind's `--spacing` multiplier so every
- *  `p-*`, `gap-*`, `m-*` utility scales uniformly across the panel. */
-export type SpacingPreset = 'default' | 'compact' | 'comfortable'
-
-// ─── Icon Library ──────────────────────────────────────────
-
-/** Icon library identifier — controls which icon set is resolved. */
-export type IconLibrary = 'lucide' | 'tabler' | 'remix' | 'phosphor'
-
-// ─── Fonts ─────────────────────────────────────────────────
-
-export interface ThemeFonts {
-  /** Google Fonts family name for headings, e.g. 'Space Grotesk'. */
-  heading?: string
-  /** Google Fonts family name for body text, e.g. 'Inter'. */
-  body?: string
-}
-
-// ─── Theme Config (user-facing) ────────────────────────────
-
-/**
- * Theme configuration — passed to `Pilotiq.theme()`.
- *
- * @example
- * ```ts
- * Pilotiq.make('admin').theme({
- *   preset: 'vega',
- *   baseColor: 'taupe',
- *   themeColor: 'orange',
- *   chartColor: 'base',
- *   radius: 'medium',
- *   fonts: { heading: 'Space Grotesk', body: 'Inter' },
- * })
- * ```
- */
-export interface ThemeConfig {
-  /** Style preset — sets all CSS variables at once. Defaults to `'vega'`. */
-  preset?:      StylePreset
-  /** Base color scale — overrides neutral/gray tones from the preset. */
-  baseColor?:   BaseColor
-  /** Theme (primary) color. `'base'` = derive from current base color. */
-  themeColor?:  ThemeColor
-  /** Chart color. `'base'` = derive ramp from current base color. */
-  chartColor?:  ChartColor
-  /** Border radius preset. Defaults to `'medium'` (Pilotiq brand). */
-  radius?:      RadiusPreset
-  /** Spacing density preset. `'default'` falls through to the per-style value
-   *  in `PRESET_SPACING` (e.g. Mira → compact, Vega → comfortable). */
-  spacing?:     SpacingPreset
-  /** Font families (loaded from Google Fonts / Fontshare). */
-  fonts?:       ThemeFonts
-  /** Icon library. */
-  iconLibrary?: IconLibrary
-  /** Escape hatch: raw CSS variable overrides in OKLCH. Applied last, highest priority. */
-  cssVariables?: {
-    light?: Record<string, string>
-    dark?:  Record<string, string>
-  }
-}
-
-// ─── Theme Meta (serialized, server → client) ──────────────
-
-/** Resolved theme data sent from server to client via viewProps. */
-export interface ThemeMeta {
-  /** CSS variable map for :root (light mode). Keys are CSS custom property names. */
-  light: Record<string, string>
-  /** CSS variable map for .dark (dark mode). */
-  dark:  Record<string, string>
-  /** Border radius value (e.g. '0.625rem'). */
-  radius: string
-  /** Spacing multiplier for Tailwind's `--spacing` token (e.g. '0.25rem'). */
-  spacing: string
-  /** Google Fonts families to load via <link> tag. */
-  fonts?: ThemeFonts
-  /** Font family CSS values with fallbacks (e.g. "'Inter', sans-serif"). */
-  fontFamily?: {
-    heading?: string
-    body?:    string
-  }
-  /** Icon library identifier for frontend icon resolution. */
-  iconLibrary: IconLibrary
-}
-
-// ─── Preset Definition ─────────────────────────────────────
-
-/** A complete set of CSS variable values for light and dark modes (OKLCH strings). */
-export interface PresetDefinition {
-  light: Record<string, string>
-  dark:  Record<string, string>
-}

package/src/uploads/UploadAdapter.ts

@@ -1,35 +0,0 @@
-/**
- * Pilotiq's upload contract. Apps register an adapter via
- * `Pilotiq.uploads({ adapter })`; the `_uploads` route hands every
- * incoming file to it. Pilotiq stays storage-agnostic — disk, S3,
- * R2, GCS, or a custom storage backend all implement the same shape.
- */
-export interface UploadAdapter {
-  /**
-   * Persist the file. Receive `{ file, directory? }`; return the
-   * URL the field should store. Throw to fail the upload — the
-   * route handler converts thrown errors into a 500 + toast.
-   */
-  put(req: UploadRequest): Promise<UploadResult>
-}
-
-export interface UploadRequest {
-  /** The browser-supplied File. Has `.name`, `.size`, `.type`, `.arrayBuffer()`. */
-  file:       File
-  /** Optional sub-directory hint set by `FileUpload.directory(...)`. */
-  directory?: string
-  /** The source field name — useful for adapter routing or audit logs. */
-  fieldName:  string
-}
-
-export interface UploadResult {
-  /** The public URL the field stores in the form value. */
-  url: string
-  /**
-   * Optional metadata to round-trip alongside the URL — file size,
-   * content type, etc. Renderers that show previews may use this.
-   * Not part of the form value; can be used by `afterStateUpdated`
-   * hooks server-side.
-   */
-  meta?: Record<string, unknown>
-}

package/src/uploads/index.ts

@@ -1,2 +0,0 @@
-export type { UploadAdapter, UploadRequest, UploadResult } from './UploadAdapter.js'
-export { localUpload, type LocalUploadConfig } from './localUpload.js'

package/src/uploads/localUpload.test.ts

@@ -1,70 +0,0 @@
-import { describe, it, before, after } from 'node:test'
-import assert from 'node:assert/strict'
-import { mkdtempSync, existsSync, readFileSync, rmSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-
-import { localUpload } from './localUpload.js'
-
-describe('localUpload adapter', () => {
-  let dir: string
-
-  before(() => {
-    dir = mkdtempSync(join(tmpdir(), 'pilotiq-uploads-'))
-  })
-
-  after(() => {
-    rmSync(dir, { recursive: true, force: true })
-  })
-
-  it('writes the file under root + returns a URL', async () => {
-    const adapter = localUpload({ root: dir, urlPrefix: '/uploads' })
-    const file = new File([new Uint8Array([1, 2, 3, 4])], 'photo.png', { type: 'image/png' })
-    const result = await adapter.put({ file, fieldName: 'cover' })
-
-    assert.match(result.url, /^\/uploads\/[a-f0-9]{32}\.png$/)
-    assert.deepEqual(result.meta, { name: 'photo.png', size: 4, type: 'image/png' })
-
-    const filename = result.url.replace('/uploads/', '')
-    const fullPath = join(dir, filename)
-    assert.ok(existsSync(fullPath), 'file was written to disk')
-    const written = readFileSync(fullPath)
-    assert.deepEqual(Array.from(written), [1, 2, 3, 4])
-  })
-
-  it('honors the directory option', async () => {
-    const adapter = localUpload({ root: dir, urlPrefix: '/uploads' })
-    const file = new File([new Uint8Array([0])], 'img.jpg', { type: 'image/jpeg' })
-    const result = await adapter.put({ file, fieldName: 'avatar', directory: 'avatars/2026' })
-    assert.match(result.url, /^\/uploads\/avatars\/2026\/[a-f0-9]{32}\.jpg$/)
-  })
-
-  it('strips path-traversal segments from directory', async () => {
-    const adapter = localUpload({ root: dir, urlPrefix: '/uploads' })
-    const file = new File([new Uint8Array([0])], 'x.png', { type: 'image/png' })
-    const result = await adapter.put({ file, fieldName: 'x', directory: '../../../etc/passwd' })
-    assert.match(result.url, /^\/uploads\/etc\/passwd\/[a-f0-9]{32}\.png$/)
-  })
-
-  it('drops over-long extensions (anti-traversal)', async () => {
-    const adapter = localUpload({ root: dir, urlPrefix: '/uploads' })
-    const file = new File([new Uint8Array([0])], 'note.thisisaverylongext', { type: 'text/plain' })
-    const result = await adapter.put({ file, fieldName: 'x' })
-    // Disallowed ext (>10 chars) → file written without extension
-    assert.match(result.url, /^\/uploads\/[a-f0-9]{32}$/)
-  })
-
-  it('drops extensions with non-alphanumeric chars', async () => {
-    const adapter = localUpload({ root: dir, urlPrefix: '/uploads' })
-    const file = new File([new Uint8Array([0])], 'note.png; rm -rf', { type: 'text/plain' })
-    const result = await adapter.put({ file, fieldName: 'x' })
-    assert.match(result.url, /^\/uploads\/[a-f0-9]{32}$/)
-  })
-
-  it('strips trailing slash from urlPrefix', async () => {
-    const adapter = localUpload({ root: dir, urlPrefix: '/uploads/' })
-    const file = new File([new Uint8Array([0])], 'x.png', { type: 'image/png' })
-    const result = await adapter.put({ file, fieldName: 'x' })
-    assert.match(result.url, /^\/uploads\/[a-f0-9]{32}\.png$/)
-  })
-})

package/src/uploads/localUpload.ts

@@ -1,84 +0,0 @@
-import { mkdir, writeFile } from 'node:fs/promises'
-import { join, extname } from 'node:path'
-import { randomBytes } from 'node:crypto'
-
-import type { UploadAdapter, UploadRequest, UploadResult } from './UploadAdapter.js'
-
-export interface LocalUploadConfig {
-  /**
-   * Filesystem directory where files are written. Resolved relative to
-   * `process.cwd()` if not absolute. The app's static-file middleware
-   * must serve this directory at `urlPrefix`.
-   *
-   * Example: `{ root: 'public/uploads', urlPrefix: '/uploads' }` writes
-   * to `<cwd>/public/uploads/<dir>/<id>.<ext>` and returns
-   * `/uploads/<dir>/<id>.<ext>`.
-   */
-  root:      string
-  /** URL prefix the file is served from. Without trailing slash. */
-  urlPrefix: string
-}
-
-/**
- * Disk-backed upload adapter. Writes incoming files under
- * `config.root/<directory>/<random-id>.<ext>` and returns the public
- * URL `<urlPrefix>/<directory>/<random-id>.<ext>`.
- *
- * v1: synchronous-ish (single `writeFile` per upload). No chunking,
- * no resumable uploads, no image processing.
- */
-export function localUpload(config: LocalUploadConfig): UploadAdapter {
-  return {
-    async put(req: UploadRequest): Promise<UploadResult> {
-      const { file, directory } = req
-      const ext     = sanitizeExt(extname(file.name))
-      const id      = randomId()
-      const subDir  = sanitizeDir(directory)
-      const fullDir = subDir
-        ? join(config.root, subDir)
-        : config.root
-
-      await mkdir(fullDir, { recursive: true })
-
-      const filename = `${id}${ext}`
-      const fullPath = join(fullDir, filename)
-      const buffer   = Buffer.from(await file.arrayBuffer())
-      await writeFile(fullPath, buffer)
-
-      const urlParts = [config.urlPrefix.replace(/\/$/, '')]
-      if (subDir) urlParts.push(subDir)
-      urlParts.push(filename)
-      return {
-        url: urlParts.join('/'),
-        meta: {
-          name: file.name,
-          size: file.size,
-          type: file.type,
-        },
-      }
-    },
-  }
-}
-
-function sanitizeDir(d: string | undefined): string {
-  if (!d) return ''
-  // Strip leading/trailing slashes and any ../ segments to avoid path
-  // traversal. Adapters are responsible for their own input validation.
-  return d
-    .replace(/^[/\\]+/, '')
-    .replace(/[/\\]+$/, '')
-    .split(/[/\\]/)
-    .filter(s => s !== '' && s !== '..' && s !== '.')
-    .join('/')
-}
-
-function sanitizeExt(ext: string): string {
-  // Extension comes from a user-uploaded filename — keep it conservative.
-  if (!ext || ext.length > 10) return ''
-  if (!/^\.[A-Za-z0-9]+$/.test(ext)) return ''
-  return ext.toLowerCase()
-}
-
-function randomId(): string {
-  return randomBytes(16).toString('hex')
-}