@pilotiq/pilotiq 0.21.0 → 0.23.0

package/src/routes.ts

@@ -1,4 +1,5 @@
 import type { Router } from '@rudderjs/router'
+import type { MiddlewareHandler } from '@rudderjs/contracts'
 import type { Pilotiq } from './Pilotiq.js'
 import { Form } from './elements/Form.js'
 import { dispatchFormSubmit, findForms, selectForm } from './elements/dispatchForm.js'
@@ -6,6 +7,7 @@ import { RESERVED_RELATIONSHIP_TOKENS } from './RelationManager.js'
 import { Table } from './elements/Table.js'
 import { Column } from './Column.js'
 import type { ClusterClass } from './Cluster.js'
+import { wantsJson } from './routes/helpers.js'
 
 // `routes.ts` is split into a directory of focused modules under
 // `./routes/`. This file is the orchestrator — boot-time validation
@@ -214,46 +216,68 @@ export function registerPilotiqRoutes(
     }
   }
 
-  // ── Panel-level sibling routes ────────────────────────
-  // Dashboard, _uploads, _widget, _search, _notifications.
-  // Pulled out 2026-05-12 (Phase 2 of the routes.ts split).
-  registerPanelRoutes(router, pilotiq, base)
-
-  // ── Resource routes ───────────────────────────────────
-  // List / view / create / edit / delete + soft-delete / actions /
-  // widgets / deferred-table / reorder / per-row editable cells / the
-  // four form-state companion endpoints / record sub-pages. Each
-  // Resource also fans out into its registered relation managers
-  // (depth-1 + depth-2). Pulled out 2026-05-12 (Phase 5 of the
-  // routes.ts split).
-  for (const R of cfg.resources) {
-    registerResourceRoutes(router, pilotiq, R, base, {
-      reorderable: reorderEnabled.has(R.getSlug()),
-      editable:    editableEnabled.has(R.getSlug()),
-    })
+  // ── `Pilotiq.guard()` — panel-wide 401 layer ──────────
+  // Documented as the unauthenticated-request gate, but until 2026-05-21
+  // only `_uploads` consulted it — every other route relied on
+  // `cfg.user` returning null + `R.canX(user, …)` defaulting to true,
+  // so an app that wired `guard(req => Auth.check())` but shipped any
+  // Resource without `canAccess` ended up with an unauthenticated,
+  // fully-readable admin panel. Wrap every core panel route in one
+  // group so the guard runs in front of every handler.
+  const guardMiddleware: MiddlewareHandler = async (req, res, next) => {
+    if (cfg.guard) {
+      const allowed = await cfg.guard(req)
+      if (!allowed) {
+        res.status(401)
+        if (wantsJson(req)) return res.json({ ok: false, error: 'Unauthorized' })
+        return res.send('Unauthorized')
+      }
+    }
+    return next()
   }
 
-  // ── Globals (singletons — 2-segment, no /:id) ────────
-  // Pulled out 2026-05-12 (Phase 3 of the routes.ts split).
-  for (const G of cfg.globals) {
-    registerGlobalRoutes(router, pilotiq, G, base)
-  }
+  router.group({ middleware: [guardMiddleware] }, () => {
+    // ── Panel-level sibling routes ────────────────────────
+    // Dashboard, _uploads, _widget, _search, _notifications.
+    // Pulled out 2026-05-12 (Phase 2 of the routes.ts split).
+    registerPanelRoutes(router, pilotiq, base)
 
-  // ── Custom pages (2-segment, slug route) ──────────────
-  // Pulled out 2026-05-12 (Phase 3 of the routes.ts split).
-  for (const PageClass of cfg.pages) {
-    // The dashboard page lives at `${base}` (panel routes handle it);
-    // skip it here so we don't register a duplicate `${pageUrl}` route
-    // or a broken `${base}/` (when `slug = ''`).
-    if (cfg.dashboardPage === PageClass) continue
-    registerCustomPageRoutes(router, pilotiq, PageClass, base)
-  }
+    // ── Resource routes ───────────────────────────────────
+    // List / view / create / edit / delete + soft-delete / actions /
+    // widgets / deferred-table / reorder / per-row editable cells / the
+    // four form-state companion endpoints / record sub-pages. Each
+    // Resource also fans out into its registered relation managers
+    // (depth-1 + depth-2). Pulled out 2026-05-12 (Phase 5 of the
+    // routes.ts split).
+    for (const R of cfg.resources) {
+      registerResourceRoutes(router, pilotiq, R, base, {
+        reorderable: reorderEnabled.has(R.getSlug()),
+        editable:    editableEnabled.has(R.getSlug()),
+      })
+    }
 
-  // ── Theme editor ──────────────────────────────────────
-  // Pulled out 2026-05-12 (Phase 3 of the routes.ts split).
-  if (cfg.themeEditor) {
-    registerThemeRoutes(router, pilotiq, base)
-  }
+    // ── Globals (singletons — 2-segment, no /:id) ────────
+    // Pulled out 2026-05-12 (Phase 3 of the routes.ts split).
+    for (const G of cfg.globals) {
+      registerGlobalRoutes(router, pilotiq, G, base)
+    }
+
+    // ── Custom pages (2-segment, slug route) ──────────────
+    // Pulled out 2026-05-12 (Phase 3 of the routes.ts split).
+    for (const PageClass of cfg.pages) {
+      // The dashboard page lives at `${base}` (panel routes handle it);
+      // skip it here so we don't register a duplicate `${pageUrl}` route
+      // or a broken `${base}/` (when `slug = ''`).
+      if (cfg.dashboardPage === PageClass) continue
+      registerCustomPageRoutes(router, pilotiq, PageClass, base)
+    }
+
+    // ── Theme editor ──────────────────────────────────────
+    // Pulled out 2026-05-12 (Phase 3 of the routes.ts split).
+    if (cfg.themeEditor) {
+      registerThemeRoutes(router, pilotiq, base)
+    }
+  })
 
   // Plugin route hook — runs AFTER all core routes register so plugins
   // can mount their own HTTP surface alongside the panel's. Order
@@ -263,6 +287,11 @@ export function registerPilotiqRoutes(
   // `_notifications`) is the recommended shape. Failures inside a
   // plugin's hook propagate — boot order is "register all core, then
   // each plugin in order"; a throw on hook N stops hooks N+1..N+M.
+  //
+  // Plugin routes mount OUTSIDE the guard group — plugins own their
+  // own auth posture (e.g. public webhooks, custom auth handshakes).
+  // Plugin authors that want the panel guard should consult
+  // `cfg.guard` themselves at the top of their handlers.
   for (const plugin of pilotiq.getPlugins()) {
     plugin.registerRoutes?.(router, pilotiq)
   }

package/src/theme/index.ts

@@ -10,6 +10,12 @@ export { iconMap, resolveIconName } from './icon-map.js'
 export { colors, BASE_COLOR_NAMES, HUE_NAMES } from './colors.js'
 export { parseSeedToScale } from './generate-scale.js'
 export { migrateThemeOverrides } from './migrate.js'
+export { prismaThemeStorage } from './storage.js'
+export type {
+  ThemeStorageAdapter,
+  PanelGlobalDelegate,
+  PrismaThemeStorageOptions,
+} from './storage.js'
 
 export type { ColorName, ColorScale, ColorStep } from './colors.js'
 export type {

package/src/theme/storage.test.ts

@@ -0,0 +1,126 @@
+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

@@ -0,0 +1,106 @@
+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'
+}