@jini-ai/admin 0.1.0

package/dist/core/gated/types.js

@@ -0,0 +1,37 @@
+/**
+ * @file The plan -> confirm -> execute protocol for destructive operations.
+ *
+ * ## Why this is in core rather than in the panels that use it
+ *
+ * The reference implementation independently grew this same three-step shape in three unrelated places — database
+ * forward-migration (`planMigrateForward`/`confirmMigrateForward`/`executeMigrateForward`),
+ * point-in-time restore (`planRestore`/`confirmRestore`/`executeRestore`), and taxonomy term
+ * merge (`planMergeTerm`/`confirmMergeTerm`/`executeMergeTerm`) — sharing `GatedPlanResult<T>`
+ * and `GatedConfirmResult` types. Three independent arrivals at one shape is the signal that it
+ * is a protocol, not a coincidence, and any product doing irreversible operator actions will
+ * need it.
+ *
+ * ## What the three steps are for
+ *
+ * - **plan** is read-only and idempotent. It computes what *would* happen and returns a token.
+ *   Safe to call on render; safe to call twice.
+ * - **confirm** records that the operator saw the plan. Separate from execute so the UI can show
+ *   consequences the operator has to acknowledge, and so a stale plan (the world changed between
+ *   plan and execute) can be rejected here rather than half-applied.
+ * - **execute** does the thing. Requires the token from confirm.
+ *
+ * The token is what makes this more than a confirmation dialog: it binds the execute call to a
+ * specific computed plan, so an operator cannot approve a small change and have a large one run.
+ *
+ * ## Warning: this protocol promises reversibility it cannot itself deliver
+ *
+ * A hard-won rule from the reference implementation's admin UX audit: **never promise an undo the
+ * product cannot deliver.** A `reversible: true` plan means the *backend* claims a revert path
+ * exists — it does not mean the admin has a reachable UI for it. The reference implementation's
+ * post/page delete is a genuine server-side
+ * soft delete with no restore path reachable from the admin. A panel rendering "you can undo
+ * this" off this flag alone would be lying to the operator. Check that the revert is reachable,
+ * not merely that it exists.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/gated/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/gated/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG"}

package/dist/core/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file `@jini-ai/admin/core` — the universal half. No React, no DOM.
+ *
+ * This is the layer a panel author codes against. Anything that touches `window` lives in
+ * `@jini-ai/admin/browser`; anything that imports React lives in `@jini-ai/admin/react`. The
+ * boundary is enforced by this package's vitest config, which deliberately runs `src/core/**`
+ * without a DOM environment so a leak fails loudly rather than passing quietly.
+ */
+export type { AdminNavEntry, AdminPanel, AdminRoutePattern } from './manifest/types.js';
+export { buildAgentPageMap, buildNav, panelHref, resolveAgentPageId, resolvePanels, } from './manifest/rules.js';
+export type { AdminNavGroup, AdminNavItem, AdminRegistryContext } from './manifest/rules.js';
+export type { AdminRoute } from './routing/types.js';
+export { DEFAULT_ADMIN_BASE, adminHref, currentRoutePath, matchRoute, stripTrailingSlash, } from './routing/rules.js';
+export { hasPermission } from './permissions/rules.js';
+export { AdminApiError, createAdminClient, createHttpTransport, describeApiError, } from './transport/index.js';
+export type { AdminClient, AdminRouteGroupFactory, AdminTransport, AdminFetch, HttpTransportOptions, } from './transport/index.js';
+export type { GatedConfirmResult, GatedOperation, GatedPlanResult } from './gated/types.js';
+export type { AdminAnalyticsHit, AdminAnalyticsPort, AdminAuthPort, AdminAuthUser, AdminComment, AdminCommentsPort, AdminCommentsQueuePage, AdminDatabasePort, AdminDegradedBanner, AdminDisclosureResult, AdminExtensionEnabledResult, AdminExtensionsPort, AdminIdentityPort, AdminIdentityUser, AdminIntegrationDelivery, AdminIntegrationDeliverySummary, AdminIntegrationSubscription, AdminIntegrationsPort, AdminLedgerRow, AdminMedia, AdminMediaPort, AdminMember, AdminMembersPort, AdminPlugin, AdminPolicy, AdminRecoveryDeepLinkResult, AdminRecoveryPort, AdminRecoveryStatus, AdminRestorePoint, AdminRestorePointSummary, AdminRole, AdminSettingsPort, AdminWorkspace, AdminWorkspacePort, CategoryCount, CommentModerationAction, CommentsSettings, CommentStatus, DatabaseContextEnvelope, DegradedBannerActionKind, DegradedBannerKind, MigrateForwardResult, RestoreConfirmInput, RestoreExecuteInput, RestoreExecuteResult, RestorePointCostClass, SettingResolvedValue, SettingResetResponse, SettingScope, SettingValueResponse, } from './ports/index.js';
+export type { AdminAssignMenuLocationResult, AdminDeleteMenuResult, AdminFormCreateInput, AdminFormDefinition, AdminFormField, AdminFormNotifyConfig, AdminFormsPort, AdminFormSubmission, AdminFormSubmissionPage, AdminFormUpdatePatch, AdminMenu, AdminMenuBinding, AdminMenuCreateInput, AdminMenuCustomTarget, AdminMenuEntryTarget, AdminMenuItem, AdminMenuItemAttrs, AdminMenuRouteTarget, AdminMenusPort, AdminMenuTarget, AdminMenuTermTarget, AdminMenuUpdateTreeInput, AdminMenuUrlTarget, AdminRedirect, AdminRedirectCreateInput, AdminRedirectHitStats, AdminRedirectImportFailure, AdminRedirectImportResult, AdminRedirectListFilter, AdminRedirectsPort, AdminRedirectUpdatePatch, AdminSeoAnalysis, AdminSeoIssue, AdminSeoMeta, AdminSeoOpenGraph, AdminSeoOverrides, AdminSeoPort, AdminSeoRobotsDirective, AdminSeoRobotsRule, AdminSeoSettings, AdminSeoTwitterCard, FormDefinitionStatus, FormFieldType, MenuStatus, NavTargetKind, RedirectMatchType, RedirectSource, RedirectStatus, RedirectStatusCode, SeoIssueSeverity, SeoOpenGraphType, SeoTwitterCardKind, } from './ports/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxF,OAAO,EACL,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,kBAAkB,EAClB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAG7F,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EACL,kBAAkB,EAClB,SAAS,EACT,gBAAgB,EAChB,UAAU,EACV,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGvD,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,WAAW,EACX,sBAAsB,EACtB,cAAc,EACd,UAAU,EACV,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAG9B,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAG5F,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,2BAA2B,EAC3B,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,EACxB,+BAA+B,EAC/B,4BAA4B,EAC5B,qBAAqB,EACrB,cAAc,EACd,UAAU,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,2BAA2B,EAC3B,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,wBAAwB,EACxB,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,uBAAuB,EACvB,gBAAgB,EAChB,aAAa,EACb,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,YAAY,EACZ,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,6BAA6B,EAC7B,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,SAAS,EACT,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,EAClB,aAAa,EACb,wBAAwB,EACxB,qBAAqB,EACrB,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,kBAAkB,EAClB,wBAAwB,EACxB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,15 @@
+/**
+ * @file `@jini-ai/admin/core` — the universal half. No React, no DOM.
+ *
+ * This is the layer a panel author codes against. Anything that touches `window` lives in
+ * `@jini-ai/admin/browser`; anything that imports React lives in `@jini-ai/admin/react`. The
+ * boundary is enforced by this package's vitest config, which deliberately runs `src/core/**`
+ * without a DOM environment so a leak fails loudly rather than passing quietly.
+ */
+export { buildAgentPageMap, buildNav, panelHref, resolveAgentPageId, resolvePanels, } from './manifest/rules.js';
+export { DEFAULT_ADMIN_BASE, adminHref, currentRoutePath, matchRoute, stripTrailingSlash, } from './routing/rules.js';
+// Permissions — affordance only, never an authorization boundary.
+export { hasPermission } from './permissions/rules.js';
+// Transport — the seam every route group is built on.
+export { AdminApiError, createAdminClient, createHttpTransport, describeApiError, } from './transport/index.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EACL,iBAAiB,EACjB,QAAQ,EACR,SAAS,EACT,kBAAkB,EAClB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAK7B,OAAO,EACL,kBAAkB,EAClB,SAAS,EACT,gBAAgB,EAChB,UAAU,EACV,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAE5B,kEAAkE;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,sDAAsD;AACtD,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC"}

package/dist/core/manifest/rules.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @file Pure functions over a panel set: what mounts, what the sidebar shows, what an agent may
+ * reach. No DOM, no React, no I/O — every function here is a total function of its arguments,
+ * which is what makes the shell's behaviour testable without rendering anything.
+ */
+import type { AdminNavEntry, AdminPanel } from './types.js';
+/** What the host has actually wired, as seen by the registry. */
+export interface AdminRegistryContext {
+    /** Capability keys with a supplied port. Matched against each panel's `requires`. */
+    readonly capabilities?: readonly string[];
+    /** The operator's effective permissions, as returned by the host's auth endpoint. May contain
+     *  the owner wildcard `"*"` — see `permissions/rules.ts`. */
+    readonly permissions?: readonly string[];
+}
+/**
+ * The panels that actually mount, in registration order.
+ *
+ * A panel is dropped when a capability it requires is not wired, or when the operator lacks one
+ * of its permissions. Both are *silent* by design: an unmet requirement means the section does
+ * not exist for this build or this operator, which is different from an error.
+ *
+ * @complexity O(p * (r + m)) — p panels, r requirements each, m permissions each. All three are
+ * small, bounded by what a developer typed into a manifest.
+ */
+export declare function resolvePanels<T>(panels: readonly AdminPanel<T>[], context?: AdminRegistryContext): readonly AdminPanel<T>[];
+/** A sidebar group, ready to render. */
+export interface AdminNavGroup {
+    /** Group heading; absent for the ungrouped top row. */
+    readonly label?: string;
+    readonly items: readonly AdminNavItem[];
+}
+/** A sidebar row. `href` is a **route path** (`/settings`), never a URL — the shell applies the
+ *  base. Conflating the two is what produced the reference implementation's
+ *  `/admin/#/section/settings` URLs. */
+export interface AdminNavItem extends AdminNavEntry {
+    readonly id: string;
+    readonly href: string;
+}
+/**
+ * Derives the sidebar from the resolved panel set.
+ *
+ * Ordering is deterministic and has to be: groups appear in the order their first member was
+ * registered (with the ungrouped row always first), and items sort by `order` ascending with
+ * registration order as a stable tiebreak. A nav that reshuffles between builds because two
+ * panels share an `order` is a real bug — operators navigate by muscle memory.
+ *
+ * @complexity O(n log n) on the items within each group; O(n) otherwise.
+ */
+export declare function buildNav<T>(panels: readonly AdminPanel<T>[]): readonly AdminNavGroup[];
+/** Panel id -> its **route path**. `dashboard` is the root, not `/dashboard`. */
+export declare function panelHref(panelId: string): string;
+/**
+ * The agent-navigable page ids: panel id -> route path.
+ *
+ * Derived from `agentReachable`, which is left unset on most panels and falls back to
+ * `options.defaultReachable` (itself defaulting to `false`) — so with no options this is an
+ * allowlist populated only by deliberate opt-in, exactly as the reference implementation's
+ * hand-maintained page-map module was. An explicit `agentReachable: false` on a panel always
+ * excludes it regardless of `defaultReachable`, so a host that flips the default can still opt a
+ * specific panel back out. Detail routes are never gated by either — see `AdminPanel.agentReachable`.
+ *
+ * `defaultReachable: true` is for a host that has decided navigation-only reachability (getting an
+ * agent TO a page) carries no meaningful risk on its own — actually operating a page's controls is
+ * a separate, still per-element opt-in (`data-agent-element`) that this default has no effect on.
+ * A host for which that isn't true (a panel an agent should never even be told exists) should keep
+ * the default false and opt in per panel instead.
+ *
+ * Note the ordering dependency: callers must pass the **resolved** panel set, not the raw one, or
+ * an agent could navigate to a panel whose capability is not wired.
+ */
+export declare function buildAgentPageMap<T>(panels: readonly AdminPanel<T>[], options?: {
+    readonly defaultReachable?: boolean;
+}): Readonly<Record<string, string>>;
+/**
+ * The page id a resolved route reports through `data-agent-page`.
+ *
+ * Deliberately NOT the same question as "which nav row lights up" — that is the panel id, and
+ * conflating the two is the documented bug `AdminRoutePattern.agentPageId` exists to prevent.
+ *
+ * Falls back to the panel id so a detail route reports its list page (`/posts/abc` -> `posts`),
+ * which is the nearest id an agent can actually act on.
+ */
+export declare function resolveAgentPageId<T>(panels: readonly AdminPanel<T>[], panelId: string | null, view: string | null): string | null;
+//# sourceMappingURL=rules.d.ts.map

package/dist/core/manifest/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../../src/core/manifest/rules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE5D,iEAAiE;AACjE,MAAM,WAAW,oBAAoB;IACnC,qFAAqF;IACrF,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C;iEAC6D;IAC7D,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,MAAM,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,EAChC,OAAO,GAAE,oBAAyB,GACjC,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,CAQ1B;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;CACzC;AAED;;wCAEwC;AACxC,MAAM,WAAW,YAAa,SAAQ,aAAa;IACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,aAAa,EAAE,CA2BtF;AAQD,iFAAiF;AACjF,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,MAAM,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,EAChC,OAAO,GAAE;IAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GACpD,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAkBlC;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,MAAM,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,EAChC,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,IAAI,EAAE,MAAM,GAAG,IAAI,GAClB,MAAM,GAAG,IAAI,CAMf"}

package/dist/core/manifest/rules.js

@@ -0,0 +1,130 @@
+/**
+ * @file Pure functions over a panel set: what mounts, what the sidebar shows, what an agent may
+ * reach. No DOM, no React, no I/O — every function here is a total function of its arguments,
+ * which is what makes the shell's behaviour testable without rendering anything.
+ */
+import { hasPermission } from '../permissions/rules.js';
+/**
+ * The panels that actually mount, in registration order.
+ *
+ * A panel is dropped when a capability it requires is not wired, or when the operator lacks one
+ * of its permissions. Both are *silent* by design: an unmet requirement means the section does
+ * not exist for this build or this operator, which is different from an error.
+ *
+ * @complexity O(p * (r + m)) — p panels, r requirements each, m permissions each. All three are
+ * small, bounded by what a developer typed into a manifest.
+ */
+export function resolvePanels(panels, context = {}) {
+    const capabilities = context.capabilities ?? [];
+    const permissions = context.permissions ?? [];
+    return panels.filter((panel) => {
+        const capabilitiesMet = (panel.requires ?? []).every((key) => capabilities.includes(key));
+        if (!capabilitiesMet)
+            return false;
+        return (panel.permissions ?? []).every((p) => hasPermission(permissions, p));
+    });
+}
+/**
+ * Derives the sidebar from the resolved panel set.
+ *
+ * Ordering is deterministic and has to be: groups appear in the order their first member was
+ * registered (with the ungrouped row always first), and items sort by `order` ascending with
+ * registration order as a stable tiebreak. A nav that reshuffles between builds because two
+ * panels share an `order` is a real bug — operators navigate by muscle memory.
+ *
+ * @complexity O(n log n) on the items within each group; O(n) otherwise.
+ */
+export function buildNav(panels) {
+    const groups = new Map();
+    const groupOrder = [];
+    // Sentinel for "no group". A panel cannot collide with it: `group` is `string | undefined`, and
+    // an explicit empty-string group would be a labelless heading, which is the same thing.
+    const UNGROUPED = '';
+    panels.forEach((panel) => {
+        if (!panel.nav)
+            return;
+        const key = panel.nav.group ?? UNGROUPED;
+        if (!groups.has(key)) {
+            groups.set(key, []);
+            groupOrder.push(key);
+        }
+        groups.get(key)?.push({ ...panel.nav, id: panel.id, href: panelHref(panel.id) });
+    });
+    // Ungrouped first regardless of when it was registered — it is the top row, not a peer group.
+    const ordered = [
+        ...groupOrder.filter((k) => k === UNGROUPED),
+        ...groupOrder.filter((k) => k !== UNGROUPED),
+    ];
+    return ordered.map((key) => ({
+        ...(key === UNGROUPED ? {} : { label: key }),
+        items: stableSortByOrder(groups.get(key) ?? []),
+    }));
+}
+/** `Array.prototype.sort` is specified as stable, so equal `order` values keep registration
+ *  order — the tiebreak `buildNav` documents. Missing `order` sorts last, not as 0. */
+function stableSortByOrder(items) {
+    return [...items].sort((a, b) => (a.order ?? Number.MAX_SAFE_INTEGER) - (b.order ?? Number.MAX_SAFE_INTEGER));
+}
+/** Panel id -> its **route path**. `dashboard` is the root, not `/dashboard`. */
+export function panelHref(panelId) {
+    return panelId === 'dashboard' ? '/' : `/${panelId}`;
+}
+/**
+ * The agent-navigable page ids: panel id -> route path.
+ *
+ * Derived from `agentReachable`, which is left unset on most panels and falls back to
+ * `options.defaultReachable` (itself defaulting to `false`) — so with no options this is an
+ * allowlist populated only by deliberate opt-in, exactly as the reference implementation's
+ * hand-maintained page-map module was. An explicit `agentReachable: false` on a panel always
+ * excludes it regardless of `defaultReachable`, so a host that flips the default can still opt a
+ * specific panel back out. Detail routes are never gated by either — see `AdminPanel.agentReachable`.
+ *
+ * `defaultReachable: true` is for a host that has decided navigation-only reachability (getting an
+ * agent TO a page) carries no meaningful risk on its own — actually operating a page's controls is
+ * a separate, still per-element opt-in (`data-agent-element`) that this default has no effect on.
+ * A host for which that isn't true (a panel an agent should never even be told exists) should keep
+ * the default false and opt in per panel instead.
+ *
+ * Note the ordering dependency: callers must pass the **resolved** panel set, not the raw one, or
+ * an agent could navigate to a panel whose capability is not wired.
+ */
+export function buildAgentPageMap(panels, options = {}) {
+    const defaultReachable = options.defaultReachable ?? false;
+    const map = {};
+    panels.forEach((panel) => {
+        if ((panel.agentReachable ?? defaultReachable) === true)
+            map[panel.id] = panelHref(panel.id);
+        // A param-free detail route carrying an `agentPageId` is a destination in its own right —
+        // the reference implementation publishes `widget-regions -> /widgets/regions` exactly this
+        // way. A route WITH params
+        // is skipped: an agent has no id to supply, so publishing it would hand out a path that
+        // cannot be navigated. See `AdminRoutePattern.agentPageId`.
+        (panel.routes ?? []).forEach((route) => {
+            if (!route.agentPageId)
+                return;
+            if (route.pattern.includes(':'))
+                return;
+            map[route.agentPageId] = `${panelHref(panel.id)}${route.pattern}`.replace('//', '/');
+        });
+    });
+    return map;
+}
+/**
+ * The page id a resolved route reports through `data-agent-page`.
+ *
+ * Deliberately NOT the same question as "which nav row lights up" — that is the panel id, and
+ * conflating the two is the documented bug `AdminRoutePattern.agentPageId` exists to prevent.
+ *
+ * Falls back to the panel id so a detail route reports its list page (`/posts/abc` -> `posts`),
+ * which is the nearest id an agent can actually act on.
+ */
+export function resolveAgentPageId(panels, panelId, view) {
+    if (panelId == null)
+        return null;
+    const panel = panels.find((p) => p.id === panelId);
+    if (!panel)
+        return null;
+    const matched = (panel.routes ?? []).find((r) => r.view === view);
+    return matched?.agentPageId ?? panel.id;
+}
+//# sourceMappingURL=rules.js.map

package/dist/core/manifest/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../../src/core/manifest/rules.ts"],"names":[],"mappings":"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"}

package/dist/core/manifest/types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @file What an admin panel *is* — the contract a panel author codes against.
+ *
+ * This is the smallest surface in the package on purpose. A panel package (Jini-shipped,
+ * host-owned, third-party, or AI-generated) should need this module and nothing else: it has no
+ * React, no DOM, no transport, and no knowledge of the shell that will mount it.
+ *
+ * ## The three-file problem this replaces
+ *
+ * The reference implementation defines a section in three places — `App.tsx`'s `SECTIONS` map
+ * (routing allowlist + render dispatch), `nav.ts` (sidebar label/icon/group/order), and
+ * `agent-pages.ts` (which pages an AI agent may navigate to). Its own internal docs are emphatic
+ * that this is deliberate, and they are right about *why*:
+ *
+ * > "Do not derive this from `App.tsx`'s `SECTIONS` map. Doing so would make every new admin
+ * > screen agent-reachable simply by existing, which is the opposite of an allowlist."
+ *
+ * That reasoning survives here intact. What changes is only that the three facts live in one
+ * declaration instead of three files that must be kept in sync by hand — with `nav` optional
+ * (so a panel can be routable without a sidebar row, which the reference implementation's
+ * `appearance` and `settings-raw` panels both rely on) and `agentReachable` an explicit opt-in
+ * that defaults to false.
+ *
+ * The security property is strictly better than the three-file version: a panel author who forgets
+ * to think about agent reachability gets `false`, and an AI generating a panel manifest cannot
+ * make itself agent-reachable by omission. Under the old shape, forgetting to edit
+ * `agent-pages.ts` was also safe — but so was forgetting to edit `nav.ts`, and the two mistakes
+ * were indistinguishable from reading any one file.
+ */
+/**
+ * A detail-route pattern owned by a panel.
+ *
+ * The reference implementation's `parseRoute` hard-codes every detail route as a branch in one 30-line if-chain
+ * (`/posts/:id`, `/menus/new`, `/widgets/regions/:key`, `/collections/:key/:entryId`, ...), so a
+ * panel cannot add a route without editing the router. Declaring patterns on the panel inverts
+ * that: the matcher is generic and the panel owns its own URL space.
+ *
+ * Patterns are matched segment-by-segment against the route path:
+ * - a literal segment matches itself exactly
+ * - `:name` captures one segment into `params.name`
+ *
+ * There is deliberately no wildcard/splat and no regex. Every route in the corpus this was ported
+ * from is expressible without one, and both features make it possible for two panels to claim
+ * overlapping URL space in ways that are hard to diagnose.
+ */
+export interface AdminRoutePattern {
+    /** Pattern relative to the panel's own id segment: `/:postId`, `/regions/:regionKey`, `/new`. */
+    readonly pattern: string;
+    /** Discriminator the panel's renderer switches on. Panel-local; never globally unique. */
+    readonly view: string;
+    /**
+     * The page id this route reports to an agent, when it differs from the panel's.
+     *
+     * Two distinct effects, split by whether the pattern captures params — and the split is what
+     * the reference implementation actually needs, not a generalization:
+     *
+     * - **Param-free pattern** (`/regions`): the route becomes a published agent *destination* in
+     *   its own right, reachable by `page.navigate('widget-regions')`.
+     * - **Pattern with params** (`/regions/:regionKey`): the route is not a destination (an agent
+     *   cannot supply the id), but it *reports* this page id, so an agent that navigated to
+     *   `widget-regions` and landed on the editor is told it arrived where it asked.
+     *
+     * Omitted (the default) means the route reports its panel's id and publishes nothing — which is
+     * right for the common case: `/posts/abc` reports `posts`, the nearest id an agent can act on.
+     *
+     * This exists because collapsing the two questions is a documented past bug in the reference
+     * implementation's `App.tsx`: the sidebar wants a nav row to light up, an agent wants an id it can pass
+     * back to `page.navigate`, and widget regions is where they genuinely diverge — the sidebar has
+     * no regions row so it highlights `widgets`, while the agent must be told `widget-regions`.
+     * Sharing one function meant `page.navigate("widget-regions")` landed correctly and then
+     * reported `after: "widgets"`, telling the agent it had arrived somewhere it had not asked for.
+     * An agent's only correction for that is to navigate again.
+     */
+    readonly agentPageId?: string;
+}
+/** Sidebar presence. Optional on a panel — absence means routable but not listed. */
+export interface AdminNavEntry {
+    readonly label: string;
+    /** Inner SVG markup for an 18x18 stroked icon (`viewBox="0 0 18 18"`, `stroke="currentColor"`),
+     *  matching the convention already used across the reference implementation's `nav.ts`. Optional so a panel can be
+     *  listed before anyone has drawn it an icon. */
+    readonly icon?: string;
+    /** Group heading. Panels sharing a value are rendered together; omitted means the ungrouped
+     *  top row. */
+    readonly group?: string;
+    /** Ascending sort within a group. Ties fall back to registration order, which is stable. */
+    readonly order?: number;
+    /** Renders as a disabled row — announced but not yet built. */
+    readonly soon?: boolean;
+    /**
+     * When `soon` is set, renders the row as a REAL link (not a disabled non-link) while still
+     * showing the `soon` badge, so an operator can click through and preview the unfinished screen
+     * instead of the row being inert. Ignored when `soon` is falsy — there is nothing to opt into on
+     * a shipped row. Opt-in rather than a `soon` behavior change: the existing "disabled non-link"
+     * shape stays the default for a panel author who has not deliberately decided the in-progress
+     * screen is safe to preview.
+     */
+    readonly soonPreviewable?: boolean;
+}
+/**
+ * A panel: one admin section, its URL space, and the conditions under which it mounts.
+ *
+ * `TRender` is whatever the host's rendering layer needs — a React element thunk for
+ * `@jini-ai/admin/react`, something else for another framework. Keeping it a type parameter is
+ * what allows this module to stay free of any framework import.
+ */
+export interface AdminPanel<TRender = unknown> {
+    /**
+     * Stable identifier, and the first URL segment (`users` -> `/users`). Also the value the shell
+     * reports as the current page, so it must be the vocabulary a human would guess — the reference
+     * implementation's `agent-pages.ts` notes that a separate agent-facing naming scheme would mean an agent reading
+     * the page could not act on it without a translation table.
+     */
+    readonly id: string;
+    /** What the shell renders for this panel. */
+    readonly render: TRender;
+    /** Sidebar presence. Omit for a panel that is reachable by URL but not listed. */
+    readonly nav?: AdminNavEntry;
+    /**
+     * Whether an AI agent may navigate here via a `page.navigate`-style capability.
+     *
+     * **Defaults to false, and must stay an explicit opt-in.** See the file header — this is the
+     * allowlist property, and deriving it from anything else defeats the point.
+     *
+     * Detail routes are never agent-reachable regardless of this flag: they need an id the agent
+     * has to look up first, and the tool for that is a content catalog, not a navigation allowlist
+     * that would have to enumerate every row in the database (the reference implementation's
+     * `agent-pages.ts` hits exactly this case).
+     */
+    readonly agentReachable?: boolean;
+    /**
+     * Capability keys this panel needs wired before it can mount.
+     *
+     * This is the composability lever: a host does not ship or omit panel *code*, it supplies or
+     * withholds the *ports* a panel names here, and the registry drops any panel whose requirements
+     * are unmet — no dead nav row, no route that renders an error. A build that includes the
+     * payments panel but wires no payments port simply has no payments section.
+     */
+    readonly requires?: readonly string[];
+    /** Detail routes below `/{id}`. See `AdminRoutePattern`. */
+    readonly routes?: readonly AdminRoutePattern[];
+    /**
+     * Permission strings the operator must hold for this panel to appear.
+     *
+     * **Affordance only, never an authorization boundary** — carried over verbatim from the
+     * reference implementation's `lib/permissions.ts`, whose header is unusually clear about this
+     * and worth repeating: a bug
+     * here "can only show or hide a control; it cannot grant or block the underlying operation,
+     * because every mutation and tool call is independently re-checked server-side". Do not let a
+     * passing check here stand in for server-side authorization.
+     */
+    readonly permissions?: readonly string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/manifest/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/manifest/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAiB;IAChC,iGAAiG;IACjG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,qFAAqF;AACrF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;qDAEiD;IACjD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;mBACe;IACf,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU,CAAC,OAAO,GAAG,OAAO;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAEzB,kFAAkF;IAClF,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC;IAE7B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAElC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEtC,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAE/C;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C"}

package/dist/core/manifest/types.js

@@ -0,0 +1,31 @@
+/**
+ * @file What an admin panel *is* — the contract a panel author codes against.
+ *
+ * This is the smallest surface in the package on purpose. A panel package (Jini-shipped,
+ * host-owned, third-party, or AI-generated) should need this module and nothing else: it has no
+ * React, no DOM, no transport, and no knowledge of the shell that will mount it.
+ *
+ * ## The three-file problem this replaces
+ *
+ * The reference implementation defines a section in three places — `App.tsx`'s `SECTIONS` map
+ * (routing allowlist + render dispatch), `nav.ts` (sidebar label/icon/group/order), and
+ * `agent-pages.ts` (which pages an AI agent may navigate to). Its own internal docs are emphatic
+ * that this is deliberate, and they are right about *why*:
+ *
+ * > "Do not derive this from `App.tsx`'s `SECTIONS` map. Doing so would make every new admin
+ * > screen agent-reachable simply by existing, which is the opposite of an allowlist."
+ *
+ * That reasoning survives here intact. What changes is only that the three facts live in one
+ * declaration instead of three files that must be kept in sync by hand — with `nav` optional
+ * (so a panel can be routable without a sidebar row, which the reference implementation's
+ * `appearance` and `settings-raw` panels both rely on) and `agentReachable` an explicit opt-in
+ * that defaults to false.
+ *
+ * The security property is strictly better than the three-file version: a panel author who forgets
+ * to think about agent reachability gets `false`, and an AI generating a panel manifest cannot
+ * make itself agent-reachable by omission. Under the old shape, forgetting to edit
+ * `agent-pages.ts` was also safe — but so was forgetting to edit `nav.ts`, and the two mistakes
+ * were indistinguishable from reading any one file.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/manifest/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/manifest/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG"}

package/dist/core/permissions/rules.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @file Client-side permission-affordance helper.
+ *
+ * Ported verbatim in behaviour from the reference implementation's `lib/permissions.ts`. The bug that file
+ * exists to prevent is worth restating, because it is not obvious and it cost a real lockout:
+ *
+ * A host's "effective permissions" list is typically flattened to bare permission strings, and an
+ * unconstrained owner grant appears in it as the literal `"*"`. A plain
+ * `permissions.includes(permission)` check treats `"*"` as just another permission *name* and
+ * never matches it against a real permission like `"comments.read"` — which locked the workspace
+ * owner out of every permission-gated affordance in the admin. Every call site that checks a
+ * permission string should route through this helper rather than reintroducing a literal
+ * `.includes()`.
+ *
+ * ## NOT A SECURITY BOUNDARY
+ *
+ * This decides whether a button, section, or form renders. It never runs on the server and is
+ * never consulted by any route or command handler. A bug here — too permissive or too
+ * restrictive — can only show or hide a control; it cannot grant or block the underlying
+ * operation, because every mutation and tool call must be independently re-checked server-side.
+ * Do not import this into server code, and do not treat a passing call here as proof an action is
+ * actually allowed.
+ */
+/**
+ * True iff `permissions` grants `permission` — either an exact match, or the unconstrained owner
+ * wildcard `"*"`.
+ *
+ * @complexity O(n) array scan, n = `permissions.length` (a handful of grant strings for a real
+ * principal; never a caller-unbounded collection).
+ */
+export declare function hasPermission(permissions: readonly string[], permission: string): boolean;
+//# sourceMappingURL=rules.d.ts.map

package/dist/core/permissions/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../../src/core/permissions/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAEzF"}

package/dist/core/permissions/rules.js

@@ -0,0 +1,34 @@
+/**
+ * @file Client-side permission-affordance helper.
+ *
+ * Ported verbatim in behaviour from the reference implementation's `lib/permissions.ts`. The bug that file
+ * exists to prevent is worth restating, because it is not obvious and it cost a real lockout:
+ *
+ * A host's "effective permissions" list is typically flattened to bare permission strings, and an
+ * unconstrained owner grant appears in it as the literal `"*"`. A plain
+ * `permissions.includes(permission)` check treats `"*"` as just another permission *name* and
+ * never matches it against a real permission like `"comments.read"` — which locked the workspace
+ * owner out of every permission-gated affordance in the admin. Every call site that checks a
+ * permission string should route through this helper rather than reintroducing a literal
+ * `.includes()`.
+ *
+ * ## NOT A SECURITY BOUNDARY
+ *
+ * This decides whether a button, section, or form renders. It never runs on the server and is
+ * never consulted by any route or command handler. A bug here — too permissive or too
+ * restrictive — can only show or hide a control; it cannot grant or block the underlying
+ * operation, because every mutation and tool call must be independently re-checked server-side.
+ * Do not import this into server code, and do not treat a passing call here as proof an action is
+ * actually allowed.
+ */
+/**
+ * True iff `permissions` grants `permission` — either an exact match, or the unconstrained owner
+ * wildcard `"*"`.
+ *
+ * @complexity O(n) array scan, n = `permissions.length` (a handful of grant strings for a real
+ * principal; never a caller-unbounded collection).
+ */
+export function hasPermission(permissions, permission) {
+    return permissions.includes('*') || permissions.includes(permission);
+}
+//# sourceMappingURL=rules.js.map

package/dist/core/permissions/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../../src/core/permissions/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,WAA8B,EAAE,UAAkB;IAC9E,OAAO,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,WAAW,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;AACvE,CAAC"}

package/dist/core/ports/analytics.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @file `AdminAnalyticsPort` — a rolling window of recent traffic hits, for a live-ish activity
+ * view rather than aggregate reporting.
+ *
+ * Deliberately the thinnest port in the set (one method, no mutation, no pagination cursor). The
+ * reference implementation's route returns a bounded recent-hits list, not a queryable analytics store — there is no
+ * date-range filter, no aggregation, and no historical query on the contract because the reference
+ * implementation has none of those either. A host that needs real analytics reporting (rollups,
+ * date ranges, funnels, ...) needs a different, dedicated port; stretching this one to cover that
+ * by adding options over time would blur "recent activity feed" into "analytics platform", which
+ * is a materially different feature with different performance and retention expectations.
+ */
+/** One traffic event — either a page view or a named custom event. */
+export interface AdminAnalyticsHit {
+    readonly occurredAt: string;
+    readonly kind: "pageview" | "event";
+    readonly path: string;
+    /** Null when there was no referrer (direct navigation) or the host could not determine one. */
+    readonly referrerHost: string | null;
+    readonly deviceClass: "desktop" | "mobile" | "tablet" | "bot" | "unknown";
+    /** Null when the host could not classify the browser (e.g. an unrecognized or absent
+     *  user-agent). */
+    readonly browserFamily: string | null;
+    /** Set only for `kind: "event"`; null for a plain pageview. */
+    readonly eventName: string | null;
+}
+export interface AdminAnalyticsPort {
+    /** `limit` bounds how many recent hits come back; omitting it defers to the host's own default
+     *  bound rather than requesting an unbounded list — see the file header on why this is a recent
+     *  activity feed, not a queryable store. */
+    listRecentAnalyticsHits(options?: {
+        limit?: number;
+    }): Promise<readonly AdminAnalyticsHit[]>;
+}
+//# sourceMappingURL=analytics.d.ts.map

package/dist/core/ports/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../../src/core/ports/analytics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,sEAAsE;AACtE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+FAA+F;IAC/F,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IAC1E;uBACmB;IACnB,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,kBAAkB;IACjC;;gDAE4C;IAC5C,uBAAuB,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAAC;CAC9F"}