@pilotiq/pilotiq 0.24.1 → 0.24.3

package/src/routes.ts

@@ -1,303 +0,0 @@
-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'
-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
-// loops + the per-Resource / per-Global / per-Page registration
-// dispatchers. See `docs/plans/routes-split.md` for the per-phase map.
-import { registerPanelRoutes }       from './routes/panel.js'
-import { registerResourceRoutes }    from './routes/resources.js'
-import { registerGlobalRoutes }      from './routes/globals.js'
-import { registerCustomPageRoutes }  from './routes/pages.js'
-import { registerThemeRoutes }       from './routes/theme.js'
-
-export function registerPilotiqRoutes(
-  router: Router,
-  pilotiq: Pilotiq,
-): void {
-  const cfg = pilotiq.getConfig()
-  const base = cfg.path
-
-  // Fail fast at boot — a silent 404 at request time is much harder to
-  // debug than a clear error here. Dangling-reference checks run even
-  // when `cfg.clusters` is empty.
-  const clusterSet = new Set(cfg.clusters)
-  const assertClusterRegistered = (
-    kind:  'Resource' | 'Global' | 'Page',
-    items: Array<{ name: string; cluster?: ClusterClass }>,
-  ): void => {
-    for (const item of items) {
-      if (item.cluster === undefined) continue
-      if (!clusterSet.has(item.cluster)) {
-        throw new Error(
-          `[Pilotiq] ${kind} ${item.name} references cluster ${item.cluster.name} which is not registered. ` +
-          `Add it to Pilotiq.clusters([…]).`,
-        )
-      }
-    }
-  }
-  assertClusterRegistered('Resource', cfg.resources)
-  assertClusterRegistered('Global',   cfg.globals)
-  assertClusterRegistered('Page',     cfg.pages)
-
-  if (cfg.clusters.length > 0) {
-    const seenClusterSlug = new Set<string>()
-    for (const C of cfg.clusters) {
-      const s = C.getSlug()
-      if (s === '' || /^_/.test(s) || s === 'theme' || s === 'api') {
-        throw new Error(
-          `[Pilotiq] Cluster ${C.name} uses reserved slug "${s}". ` +
-          `Cluster slugs cannot be empty, start with "_", or equal "theme" / "api".`,
-        )
-      }
-      if (seenClusterSlug.has(s)) {
-        throw new Error(
-          `[Pilotiq] Two clusters share slug "${s}". Cluster slugs must be unique.`,
-        )
-      }
-      seenClusterSlug.add(s)
-    }
-    // Top-level (no cluster) child slugs must not collide with cluster
-    // slugs — `<panel-base>/<slug>` would resolve to the cluster first.
-    const assertNoSlugCollision = <T extends { name: string; cluster?: ClusterClass; getSlug(): string }>(
-      kind:  'Resource' | 'Global' | 'Page',
-      items: T[],
-      skip?: (item: T) => boolean,
-    ): void => {
-      for (const item of items) {
-        if (item.cluster || (skip?.(item) ?? false)) continue
-        if (seenClusterSlug.has(item.getSlug())) {
-          const hint = kind === 'Resource'
-            ? ` Either rename the resource or move it inside the cluster.`
-            : ''
-          throw new Error(
-            `[Pilotiq] ${kind} ${item.name} slug "${item.getSlug()}" collides with a registered cluster slug.${hint}`,
-          )
-        }
-      }
-    }
-    assertNoSlugCollision('Resource', cfg.resources)
-    assertNoSlugCollision('Global',   cfg.globals)
-    assertNoSlugCollision('Page',     cfg.pages, P => P === cfg.dashboardPage)
-    // landingPage sanity — a cluster's landing page must be inside the
-    // cluster (or the redirect would jump out of the cluster URL space).
-    for (const C of cfg.clusters) {
-      const lp = C.landingPage
-      if (lp === undefined) continue
-      if (!cfg.pages.includes(lp)) {
-        throw new Error(
-          `[Pilotiq] Cluster ${C.name}.landingPage references ${lp.name} which is not registered in Pilotiq.pages([…]).`,
-        )
-      }
-      if (lp.cluster !== C) {
-        throw new Error(
-          `[Pilotiq] Cluster ${C.name}.landingPage = ${lp.name}, but ${lp.name}.cluster does not point back at ${C.name}.`,
-        )
-      }
-    }
-  }
-
-  // Plan #11 — fail fast at boot when any relation manager's
-  // `relationship` collides with a reserved URL token. A silent 404 at
-  // request time is much harder to debug.
-  //
-  // Phase B nested resources — same validation walks managers declared
-  // via `M.relations()` (one level deep). Depth-3+ is rejected here too:
-  // declaring `relations()` on a nested manager isn't supported in
-  // Phase B (Filament also caps at depth 2).
-  for (const R of cfg.resources) {
-    for (const M of R.relations()) {
-      const rel = M.getRelationship()
-      if (RESERVED_RELATIONSHIP_TOKENS.has(rel)) {
-        throw new Error(
-          `[Pilotiq] RelationManager ${M.name} on ${R.name} uses reserved relationship "${rel}". ` +
-          `Reserved tokens: ${[...RESERVED_RELATIONSHIP_TOKENS].join(', ')}. Rename it.`,
-        )
-      }
-      for (const N of M.relations()) {
-        const nestedRel = N.getRelationship()
-        if (RESERVED_RELATIONSHIP_TOKENS.has(nestedRel)) {
-          throw new Error(
-            `[Pilotiq] Nested RelationManager ${N.name} under ${M.name} on ${R.name} uses reserved relationship "${nestedRel}". ` +
-            `Reserved tokens: ${[...RESERVED_RELATIONSHIP_TOKENS].join(', ')}. Rename it.`,
-          )
-        }
-        if (N.relations().length > 0) {
-          throw new Error(
-            `[Pilotiq] Nested RelationManager ${N.name} under ${M.name} on ${R.name} declares its own relations(). ` +
-            `Phase B caps nesting at depth 2 (admin-table reference frameworks cap at depth 2 too). Drop the nested relations() override.`,
-          )
-        }
-      }
-    }
-  }
-
-  // Record sub-pages — boot-time validation of slugs declared under
-  // `Resource.pages().record`. The route URL is
-  // `${resourceBase}/${slug}/:id/${subPageSlug}`, so the sub-page slug
-  // shares the same URL slot as a relation-manager's relationship. We
-  // run the slug-pattern check, the reserved-token check, and the
-  // manager-collision check before mounting any routes — a misconfigured
-  // sub-page is a dev-time error, not a runtime 404.
-  const RECORD_PAGE_SLUG_PATTERN = /^[A-Za-z0-9_-]+$/
-  for (const R of cfg.resources) {
-    const recordPages = R.getRecordPages()
-    const subPageSlugs = Object.keys(recordPages)
-    if (subPageSlugs.length === 0) continue
-    const managerSlugs = new Set(R.relations().map(M => M.getRelationship()))
-    for (const subPageSlug of subPageSlugs) {
-      if (!RECORD_PAGE_SLUG_PATTERN.test(subPageSlug)) {
-        throw new Error(
-          `[Pilotiq] Record sub-page slug ${JSON.stringify(subPageSlug)} on ${R.name} ` +
-          `must match /^[A-Za-z0-9_-]+$/. Rename it.`,
-        )
-      }
-      if (RESERVED_RELATIONSHIP_TOKENS.has(subPageSlug)) {
-        throw new Error(
-          `[Pilotiq] Record sub-page slug "${subPageSlug}" on ${R.name} collides with a reserved URL token. ` +
-          `Reserved tokens: ${[...RESERVED_RELATIONSHIP_TOKENS].join(', ')}. Rename it.`,
-        )
-      }
-      if (managerSlugs.has(subPageSlug)) {
-        throw new Error(
-          `[Pilotiq] Record sub-page slug "${subPageSlug}" on ${R.name} collides with relation manager relationship "${subPageSlug}". ` +
-          `Sub-page slugs and relation slugs share the same URL slot — rename one.`,
-        )
-      }
-    }
-  }
-
-  // Reorderable rows + editable cell columns — fail fast at boot when a
-  // Resource declares either capability but its bound model can't
-  // persist. We invoke `R.table(Table.make())` once per resource (same
-  // call shape `defaultPages` uses at request time) and inspect both
-  // markers in a single pass. The model.reorder / model.update checks
-  // are symmetric with Plan #13's restore/forceDelete guards. Results
-  // cached per-resource so the route loop below can decide whether to
-  // mount `_reorder` / `_cell`.
-  const reorderEnabled = new Map<string, string>() // slug → column
-  const editableEnabled = new Set<string>()
-  for (const R of cfg.resources) {
-    let probe: ReturnType<typeof Table.make> | undefined
-    try { probe = R.table(Table.make()) }
-    catch { continue }   // user-side throw — neither flag applies
-
-    const probeColumn = probe.getReorderableColumn()
-    if (probeColumn !== undefined) {
-      if (!R.model || typeof R.model.reorder !== 'function') {
-        throw new Error(
-          `[Pilotiq] ${R.name}.table() calls reorderable("${probeColumn}") but the bound model has no reorder(ids) method. ` +
-          `Implement \`async reorder(ids)\` on the rudder Model (or remove the .reorderable() call).`,
-        )
-      }
-      reorderEnabled.set(R.getSlug(), probeColumn)
-    }
-
-    const hasEditable = (probe.getChildren() ?? [])
-      .some(c => c instanceof Column && c.isEditable())
-    if (hasEditable) {
-      if (!R.model || typeof R.model.update !== 'function') {
-        throw new Error(
-          `[Pilotiq] ${R.name}.table() declares an editable cell column ` +
-          `(TextInputColumn / ToggleColumn / SelectColumn) but the bound ` +
-          `model has no update(id, data) method. Set Resource.model = M ` +
-          `(rudder ORM convention) or drop the editable column.`,
-        )
-      }
-      editableEnabled.add(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()
-  }
-
-  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)
-
-    // ── 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()),
-      })
-    }
-
-    // ── 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
-  // matches the registration order on `.use()` / `.plugins([…])`. Each
-  // plugin owns its own URL convention; pilotiq's underscore-prefixed
-  // sibling-route precedent (`_search`, `_uploads`, `_widget`,
-  // `_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)
-  }
-}
-
-// ─── Lifecycle helpers exported for tests ────────────────
-export { dispatchFormSubmit, findForms, selectForm }
-export { loadTableRecords, parseTableQuery, findTables } from './elements/dispatchTable.js'
-export type { Form }

package/src/schema/Alert.test.ts

@@ -1,109 +0,0 @@
-import { describe, it, beforeEach } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Alert } from './Alert.js'
-import { Action } from '../actions/Action.js'
-import { resolveSchema, _resetResolverRegistry } from './resolveSchema.js'
-
-beforeEach(() => _resetResolverRegistry())
-
-describe('Alert schema primitive', () => {
-  it('emits content + info default + no title key', () => {
-    const meta = Alert.make('Heads up').toMeta()
-    assert.equal(meta.type,      'alert')
-    assert.equal(meta.content,   'Heads up')
-    assert.equal(meta.alertType, 'info')
-    assert.equal('title' in meta, false)
-  })
-
-  it('honors warning / success / danger', () => {
-    assert.equal(Alert.make('a').warning().toMeta().alertType, 'warning')
-    assert.equal(Alert.make('a').success().toMeta().alertType, 'success')
-    assert.equal(Alert.make('a').danger().toMeta().alertType,  'danger')
-  })
-
-  it('emits title when set', () => {
-    const meta = Alert.make('body').title('Heads up').toMeta()
-    assert.equal(meta.title, 'Heads up')
-  })
-
-  it('actions(...) lands on _children and resolves into meta.children', async () => {
-    const upgrade = Action.make('upgrade').label('Upgrade').url('/billing')
-    const tree = [Alert.make('Free tier limits reached').warning().actions([upgrade])]
-    const out = await resolveSchema(tree)
-    assert.equal(out[0]!.type, 'alert')
-    const children = (out[0]!.children ?? []) as Array<{ type: string; name?: string }>
-    assert.equal(children.length, 1)
-    assert.equal(children[0]!.type, 'action')
-    assert.equal(children[0]!.name, 'upgrade')
-  })
-
-  it('actions visibility evaluates against the schema context', async () => {
-    const a = Action.make('admin-only').label('Admin').visible(({ user }) => Boolean(user))
-    const b = Action.make('always')    .label('Both' )
-    const tree = [Alert.make('hi').actions([a, b])]
-
-    // No user → admin-only action drops out.
-    const noUser = await resolveSchema(tree, {})
-    const noUserChildren = (noUser[0]!.children ?? []) as Array<{ name?: string }>
-    assert.equal(noUserChildren.length, 1)
-    assert.equal(noUserChildren[0]!.name, 'always')
-
-    // User present → both survive.
-    const withUser = await resolveSchema(tree, { user: { name: 'Sue' } })
-    const withUserChildren = (withUser[0]!.children ?? []) as Array<{ name?: string }>
-    assert.equal(withUserChildren.length, 2)
-  })
-
-  it('without actions(...) emits no children key', async () => {
-    const tree = [Alert.make('plain').info()]
-    const out = await resolveSchema(tree)
-    assert.equal('children' in out[0]!, false)
-  })
-
-  // ─── Filament v5 chrome polish (2026-05-08, audit gap #8) ──
-
-  it('controls(...) is an alias for actions(...)', async () => {
-    const a = Action.make('upgrade').label('Upgrade').url('/billing')
-    const tree = [Alert.make('hi').controls([a])]
-    const out = await resolveSchema(tree)
-    const children = (out[0]!.children ?? []) as Array<{ type: string; name?: string }>
-    assert.equal(children.length, 1)
-    assert.equal(children[0]!.name, 'upgrade')
-  })
-
-  it('controlActions(...) is the variadic spread alias', async () => {
-    const a = Action.make('upgrade').label('Upgrade').url('/billing')
-    const b = Action.make('learnMore').label('Read more').url('/docs')
-    const tree = [Alert.make('hi').controlActions(a, b)]
-    const out = await resolveSchema(tree)
-    const children = (out[0]!.children ?? []) as Array<{ name?: string }>
-    assert.equal(children.length, 2)
-    assert.equal(children[0]!.name, 'upgrade')
-    assert.equal(children[1]!.name, 'learnMore')
-  })
-
-  it('dismissible() emits dismissible: true on meta; absent by default', () => {
-    assert.equal('dismissible' in Alert.make('a').toMeta(),                   false)
-    assert.equal(Alert.make('a').dismissible().toMeta().dismissible,          true)
-    assert.equal('dismissible' in Alert.make('a').dismissible(false).toMeta(), false)
-  })
-
-  it('persistDismissal(key) auto-arms dismissible() and stamps the key', () => {
-    const meta = Alert.make('a').persistDismissal('billing-2026-q2').toMeta()
-    assert.equal(meta.dismissible,      true)
-    assert.equal(meta.persistDismissal, 'billing-2026-q2')
-  })
-
-  it('iconColor() emits the override only when set', () => {
-    assert.equal('iconColor' in Alert.make('a').toMeta(),                  false)
-    assert.equal(Alert.make('a').iconColor('destructive').toMeta().iconColor, 'destructive')
-  })
-
-  it('footerActionsAlignment() emits only when non-default', () => {
-    assert.equal('actionsAlignment' in Alert.make('a').toMeta(),                                 false)
-    assert.equal('actionsAlignment' in Alert.make('a').footerActionsAlignment('start').toMeta(), false)
-    assert.equal(Alert.make('a').footerActionsAlignment('center').toMeta().actionsAlignment, 'center')
-    assert.equal(Alert.make('a').footerActionsAlignment('end').toMeta().actionsAlignment,    'end')
-  })
-})

package/src/schema/Alert.ts

@@ -1,131 +0,0 @@
-import { Element } from './Element.js'
-import type { Action } from '../actions/Action.js'
-import type { IconColor } from './Icon.js'
-
-export type AlertType = 'info' | 'warning' | 'success' | 'danger'
-
-/**
- * Alignment for the footer-actions row inside an `Alert` (Filament v5
- * parity). `'start'` aligns the buttons to the leading edge (LTR =
- * left), `'center'` to the middle, `'end'` to the trailing edge (LTR =
- * right). Defaults to `'start'`.
- */
-export type AlertActionsAlignment = 'start' | 'center' | 'end'
-
-export class Alert extends Element {
-  private _alertType:        AlertType = 'info'
-  private _title?:           string
-  private _dismissible       = false
-  private _persistKey?:      string
-  private _iconColor?:       IconColor
-  private _actionsAlignment: AlertActionsAlignment = 'start'
-
-  private constructor(private content: string) {
-    super()
-  }
-
-  static make(content: string): Alert {
-    return new Alert(content)
-  }
-
-  alertType(t: AlertType): this { this._alertType = t; return this }
-  title(t: string):        this { this._title     = t; return this }
-
-  info():    this { return this.alertType('info')    }
-  warning(): this { return this.alertType('warning') }
-  success(): this { return this.alertType('success') }
-  danger():  this { return this.alertType('danger')  }
-
-  /**
-   * Action buttons rendered as a footer row below the alert body —
-   * matches the reference admin's `Callout` shape (in-callout CTAs like
-   * "Upgrade" or "Read changelog"). Same wiring as `Heading.actions(...)`
-   * and `EmptyState.footer(...)` — actions land on `_children` and the
-   * standard schema walker resolves them so `Action.evaluate(ctx)`
-   * (visibility / authorize) fires unchanged.
-   */
-  actions(actions: Action[]): this {
-    this._children = actions
-    return this
-  }
-
-  /** Filament v5 parity alias for `actions([...])`. Identical semantics. */
-  controls(actions: Action[]): this {
-    return this.actions(actions)
-  }
-
-  /**
-   * Filament v5 parity — variadic `controlActions(a, b, c, …)` matches
-   * the spread shape `controlActions(Action::make(...), Action::make(...))`.
-   */
-  controlActions(...actions: Action[]): this {
-    return this.actions(actions)
-  }
-
-  /**
-   * Toggle the close (`×`) button rendered in the alert's top-right
-   * corner. Off by default (matches today's behaviour). Dismissal is
-   * per-mount (component-local state) unless paired with
-   * `persistDismissal(key)`, which writes to `localStorage` so the
-   * alert stays hidden across reloads.
-   *
-   * @example
-   *   Alert.make('Heads up — billing downgrades on Friday.')
-   *     .warning()
-   *     .dismissible()
-   *     .persistDismissal('billing-downgrade-2026-q2')
-   */
-  dismissible(value: boolean = true): this {
-    this._dismissible = value
-    return this
-  }
-
-  /**
-   * Persist dismissal under a stable localStorage key. Auto-arms
-   * `dismissible(true)` so the close button shows up. The key is
-   * stored under `pilotiq.alert.<key>` to namespace from other
-   * pilotiq localStorage entries; users only see the leaf segment.
-   */
-  persistDismissal(key: string): this {
-    this._persistKey  = key
-    this._dismissible = true
-    return this
-  }
-
-  /**
-   * Override the icon color independent of the alert type. By default
-   * the renderer picks an icon hue matching `alertType`
-   * (info/warning/success/danger); call this to force a different one
-   * — e.g. a `warning`-typed alert with a `'destructive'` icon when
-   * the message escalates partway through a flow.
-   */
-  iconColor(color: IconColor): this {
-    this._iconColor = color
-    return this
-  }
-
-  /**
-   * Align the footer actions row. Defaults to `'start'` (LTR-left).
-   * Use `'end'` for "primary action sits opposite the close button"
-   * layouts; `'center'` for short single-button alerts.
-   */
-  footerActionsAlignment(alignment: AlertActionsAlignment): this {
-    this._actionsAlignment = alignment
-    return this
-  }
-
-  getType(): string { return 'alert' }
-
-  toMeta() {
-    return {
-      type:      'alert' as const,
-      content:   this.content,
-      alertType: this._alertType,
-      ...(this._title             !== undefined ? { title:             this._title             } : {}),
-      ...(this._dismissible                     ? { dismissible:       true                    } : {}),
-      ...(this._persistKey        !== undefined ? { persistDismissal:  this._persistKey        } : {}),
-      ...(this._iconColor         !== undefined ? { iconColor:         this._iconColor         } : {}),
-      ...(this._actionsAlignment !== 'start'    ? { actionsAlignment:  this._actionsAlignment  } : {}),
-    }
-  }
-}