@jini-ai/admin 0.3.10 → 0.4.1

package/dist/agent-plugins/react/index.js

@@ -0,0 +1,13 @@
+import { bindReact } from '../../react/bind-react.js';
+import { agentPluginsModule } from '../agent-plugins.module.js';
+import { AgentPluginsPortsContext } from './hooks/AgentPluginsPorts.hooks.js';
+import { agentPluginsMessagesEn as m } from '../messages.en.js';
+export { useAgentPluginsPorts } from './hooks/AgentPluginsPorts.hooks.js';
+/** Host-owned bundled policy copy. All page/tab loaders remain lazy. */
+export function agentPlugins(_required, { uninstallNotice = m.uninstallUnavailable } = {}) {
+    const tabs = { ...agentPluginsModule.pages.agentPlugins.tabs, installed: { ...agentPluginsModule.pages.agentPlugins.tabs.installed, params: { uninstallNotice } }, downloaded: { ...agentPluginsModule.pages.agentPlugins.tabs.downloaded, params: { uninstallNotice } } };
+    const module = { ...agentPluginsModule, pages: { agentPlugins: { ...agentPluginsModule.pages.agentPlugins, tabs } } };
+    const react = bindReact({ module, views: { agentPlugins: { page: () => import('./pages/AgentPluginsPage.js'), tabs: { installed: () => import('./tabs/InstalledTab.js'), downloaded: () => import('./tabs/DownloadedTab.js'), marketplace: () => import('./tabs/MarketplaceTab.js') } } } }, { context: AgentPluginsPortsContext });
+    return Object.assign(module, { react });
+}
+//# sourceMappingURL=index.js.map

package/dist/agent-plugins/react/pages/AgentPluginsPage.d.ts

@@ -0,0 +1,4 @@
+import type { ModulePageProps } from '../../../react/bind-react.js';
+export declare function AgentPluginsPage(props: ModulePageProps, _optional?: {}): import("react").JSX.Element;
+export default AgentPluginsPage;
+//# sourceMappingURL=AgentPluginsPage.d.ts.map

package/dist/agent-plugins/react/pages/AgentPluginsPage.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Suspense } from 'react';
+import { ConfirmDialog, Notice, Spinner, Tabs } from '@jini-ai/ui-kit/react';
+import { AgentPluginsPageContext, useAgentPluginsPage } from '../hooks/AgentPluginsPage.hooks.js';
+import { AgentPluginInspector } from '../components/AgentPluginInspector.js';
+import { agentPluginsMessagesEn as m } from '../../messages.en.js';
+export function AgentPluginsPage(props, _optional = {}) {
+    const vm = useAgentPluginsPage(props);
+    return _jsxs("section", { "data-jini-part": "agent-plugins.page", children: [_jsx("h1", { children: props.description.label }), vm.denied ? _jsx(Notice, { tone: "danger", children: m.denied }) : _jsxs(AgentPluginsPageContext.Provider, { value: vm.scope, children: [_jsx("p", { children: m.description }), _jsx(Tabs, { label: "Agent Plugin views", value: vm.activeId, items: vm.items, onValueChange: vm.onValueChange }), _jsx(Suspense, { fallback: _jsx(Spinner, { label: m.loading }), children: vm.ActiveTab && _jsx(vm.ActiveTab, { params: vm.params, permissions: vm.permissions }) }), vm.inspector && _jsx(AgentPluginInspector, { pluginId: vm.inspector.pluginId, name: vm.inspector.name, permissions: vm.permissions, onClose: vm.closeInspector }, vm.inspector.pluginId), vm.confirmation && _jsx(ConfirmDialog, { open: true, title: vm.confirmation.title, body: vm.confirmation.body, consequence: "Stops this package\u2019s skills on the next assistant run.", confirmLabel: vm.confirmation.confirmLabel, cancelLabel: "Cancel", tone: "warning", pending: vm.confirming, agentMayConfirm: false, onConfirm: vm.confirm, onCancel: vm.cancel, errorLabel: m.actionError })] })] });
+}
+export default AgentPluginsPage;
+//# sourceMappingURL=AgentPluginsPage.js.map

package/dist/agent-plugins/react/tabs/DownloadedTab.d.ts

@@ -0,0 +1,4 @@
+import type { TabViewProps } from '../../../react/bind-react.js';
+export declare function DownloadedTab(props: TabViewProps, _optional?: {}): import("react").JSX.Element;
+export default DownloadedTab;
+//# sourceMappingURL=DownloadedTab.d.ts.map

package/dist/agent-plugins/react/tabs/DownloadedTab.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { AgentPluginListPanel } from '../components/AgentPluginListPanel.js';
+export function DownloadedTab(props, _optional = {}) { return _jsx(AgentPluginListPanel, { props: props, mode: "downloaded" }); }
+export default DownloadedTab;
+//# sourceMappingURL=DownloadedTab.js.map

package/dist/agent-plugins/react/tabs/InstalledTab.d.ts

@@ -0,0 +1,4 @@
+import type { TabViewProps } from '../../../react/bind-react.js';
+export declare function InstalledTab(props: TabViewProps, _optional?: {}): import("react").JSX.Element;
+export default InstalledTab;
+//# sourceMappingURL=InstalledTab.d.ts.map

package/dist/agent-plugins/react/tabs/InstalledTab.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { AgentPluginListPanel } from '../components/AgentPluginListPanel.js';
+export function InstalledTab(props, _optional = {}) { return _jsx(AgentPluginListPanel, { props: props, mode: "installed" }); }
+export default InstalledTab;
+//# sourceMappingURL=InstalledTab.js.map

package/dist/agent-plugins/react/tabs/MarketplaceTab.d.ts

@@ -0,0 +1,4 @@
+import type { TabViewProps } from '../../../react/bind-react.js';
+export declare function MarketplaceTab(props: TabViewProps, _optional?: {}): import("react").JSX.Element;
+export default MarketplaceTab;
+//# sourceMappingURL=MarketplaceTab.d.ts.map

package/dist/agent-plugins/react/tabs/MarketplaceTab.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Notice } from '@jini-ai/ui-kit/react';
+import { useMarketplaceTab } from '../hooks/MarketplaceTab.hooks.js';
+import { agentPluginsMessagesEn as m } from '../../messages.en.js';
+export function MarketplaceTab(props, _optional = {}) {
+    const vm = useMarketplaceTab(props);
+    return vm.denied ? _jsx(Notice, { tone: "danger", children: m.denied }) : _jsxs("section", { "aria-label": "Agent Plugin Marketplace", children: [_jsx("h2", { children: m.marketplaceTitle }), _jsx("p", { children: m.marketplaceDescription }), _jsx("p", { children: m.marketplaceHint }), _jsx("a", { href: vm.specUrl, target: "_blank", rel: "noreferrer", children: "Read the package format" })] });
+}
+export default MarketplaceTab;
+//# sourceMappingURL=MarketplaceTab.js.map

package/dist/agent-plugins/rules.d.ts

@@ -0,0 +1,33 @@
+import type { AgentPluginSummary, AgentPluginFiles, AgentPluginPackageFile, AgentPluginDisableRequest } from './models.js';
+export declare const AGENT_PLUGINS_READ = "admin.plugins.read";
+export declare const AGENT_PLUGINS_WRITE = "admin.plugins.enable";
+export declare const AGENT_PLUGINS_SPEC_URL = "https://agent-plugins.org/specification";
+export declare function humanizeAgentPluginId({ pluginId }: {
+    pluginId: string;
+}, _optional?: {}): string;
+/** Only wire metadata enters snapshots; never leak lifecycle paths or extra server properties. */
+export declare function agentPluginSummary({ row }: {
+    row: AgentPluginSummary;
+}, _optional?: {}): AgentPluginSummary;
+export declare function agentPluginFilesSnapshot({ listing }: {
+    listing: AgentPluginFiles;
+}, _optional?: {}): AgentPluginFiles;
+export declare function selectAgentPluginFile({ files, path }: {
+    files: readonly AgentPluginPackageFile[];
+    path: string;
+}, _optional?: {}): AgentPluginPackageFile | null;
+export declare function agentPluginFileNotice({ file }: {
+    file: AgentPluginPackageFile;
+}, _optional?: {}): string | null;
+/** Confirmation names the target and workspace effect; Turn off never implies file deletion. */
+export declare function agentPluginDisableCopy({ pluginId, variant }: AgentPluginDisableRequest, _optional?: {}): {
+    title: string;
+    confirmLabel: string;
+    body: string;
+};
+export type AgentPluginGlyphKind = 'compliance' | 'deploy' | 'design' | 'integration' | 'content' | 'package';
+/** Whole words, strongest evidence first: id, keywords, skills. Never guess a category. */
+export declare function agentPluginGlyphKind({ plugin }: {
+    plugin: AgentPluginSummary;
+}, _optional?: {}): AgentPluginGlyphKind;
+//# sourceMappingURL=rules.d.ts.map

package/dist/agent-plugins/rules.js

@@ -0,0 +1,51 @@
+import { buildPackageFileTree, firstPackageFilePath } from './package-file-tree.js';
+export const AGENT_PLUGINS_READ = 'admin.plugins.read';
+export const AGENT_PLUGINS_WRITE = 'admin.plugins.enable';
+export const AGENT_PLUGINS_SPEC_URL = 'https://agent-plugins.org/specification';
+// Closed vocabulary: no heuristic can distinguish an acronym from a real word reliably.
+const acronyms = new Set(['ai', 'api', 'cli', 'css', 'html', 'http', 'id', 'io', 'json', 'mcp', 'rss', 'sdk', 'seo', 'sql', 'ui', 'url', 'ux', 'yaml']);
+export function humanizeAgentPluginId({ pluginId }, _optional = {}) {
+    return pluginId.split('-').filter(Boolean).map(part => acronyms.has(part.toLowerCase()) ? part.toUpperCase() : part.charAt(0).toUpperCase() + part.slice(1)).join(' ');
+}
+/** Only wire metadata enters snapshots; never leak lifecycle paths or extra server properties. */
+export function agentPluginSummary({ row }, _optional = {}) {
+    return Object.freeze({ pluginId: row.pluginId, version: row.version ?? null, description: row.description ?? null, keywords: Object.freeze([...row.keywords]), skills: Object.freeze(row.skills.map(s => Object.freeze({ name: s.name, summary: s.summary }))), mcpServerIds: Object.freeze([...row.mcpServerIds]), enabled: row.enabled });
+}
+export function agentPluginFilesSnapshot({ listing }, _optional = {}) {
+    return Object.freeze({ pluginId: listing.pluginId, files: Object.freeze(listing.files.map(f => Object.freeze({ relativePath: f.relativePath, sizeBytes: f.sizeBytes, content: f.content, omitted: f.omitted }))), truncated: listing.truncated, limits: Object.freeze({ maxFiles: listing.limits.maxFiles, maxEntries: listing.limits.maxEntries, maxFileBytes: listing.limits.maxFileBytes, maxTotalBytes: listing.limits.maxTotalBytes }) });
+}
+export function selectAgentPluginFile({ files, path }, _optional = {}) {
+    const selected = files.find(f => f.relativePath === path);
+    if (selected)
+        return selected;
+    const first = firstPackageFilePath({ nodes: buildPackageFileTree({ paths: files.map(f => f.relativePath) }) });
+    return files.find(f => f.relativePath === first) ?? files[0] ?? null;
+}
+const omissions = { binary: 'Binary file — not shown.', 'too-large': 'Too large to show here.', symlink: 'Symbolic link — not followed.', unreadable: 'This file could not be read.' };
+export function agentPluginFileNotice({ file }, _optional = {}) {
+    return file.omitted === null && file.content !== null ? null : omissions[file.omitted ?? 'unreadable'] ?? omissions.unreadable;
+}
+/** Confirmation names the target and workspace effect; Turn off never implies file deletion. */
+export function agentPluginDisableCopy({ pluginId, variant }, _optional = {}) {
+    const name = humanizeAgentPluginId({ pluginId });
+    return { title: variant === 'remove' ? `Turn off ${name}?` : `Disable ${name} for this workspace?`, confirmLabel: variant === 'remove' ? 'Turn off' : 'Disable', body: 'Its skills stop reaching the assistant on the next run. The package stays on disk, remains listed on both tabs, and can be enabled again.' };
+}
+const vocabulary = [
+    ['compliance', ['compliance', 'privacy', 'gdpr', 'ccpa', 'cpra', 'consent', 'security', 'audit', 'wcag', 'accessibility']],
+    ['deploy', ['deploy', 'deployment', 'hosting', 'release', 'ship', 'production', 'ci', 'fly']],
+    ['design', ['design', 'ui', 'ux', 'uiux', 'theme', 'brand', 'visual']],
+    ['integration', ['mcp', 'integration', 'connector', 'webhook', 'api']],
+    ['content', ['docs', 'documentation', 'content', 'writing', 'copy', 'blog']],
+];
+/** Whole words, strongest evidence first: id, keywords, skills. Never guess a category. */
+export function agentPluginGlyphKind({ plugin }, _optional = {}) {
+    const tokens = (values) => new Set(values.flatMap(s => s.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)));
+    for (const tier of [[plugin.pluginId], plugin.keywords, plugin.skills.map(s => s.name)]) {
+        const words = tokens(tier);
+        const match = vocabulary.find(([, values]) => values.some(v => words.has(v)));
+        if (match)
+            return match[0];
+    }
+    return 'package';
+}
+//# sourceMappingURL=rules.js.map

package/dist/browser/index.d.ts

@@ -5,4 +5,5 @@
  * `navigation.ts`'s header.
  */
 export { NAVIGATION_EVENT, installInternalLinkInterceptor, navigate, readRoutePath, subscribeToRoute, } from './navigation.js';
+export { createAdminShellNavigation } from './shell-navigation.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/browser/index.js

@@ -5,4 +5,5 @@
  * `navigation.ts`'s header.
  */
 export { NAVIGATION_EVENT, installInternalLinkInterceptor, navigate, readRoutePath, subscribeToRoute, } from './navigation.js';
+export { createAdminShellNavigation } from './shell-navigation.js';
 //# sourceMappingURL=index.js.map

package/dist/browser/navigation.d.ts

@@ -11,14 +11,21 @@
 /** Fires on `navigate()`. `pushState` does not emit `popstate`, so subscribers need this too. */
 export declare const NAVIGATION_EVENT = "jini:admin-navigate";
 /** The current route path, read from the address bar. */
-export declare function readRoutePath(base?: string): string;
+export declare function readRoutePath({ window }: {
+    readonly window: Pick<Window, 'location'>;
+}, { base }?: {
+    readonly base?: string;
+}): string;
 /**
  * Navigates without a page load.
  *
  * Takes a *route path*, not a URL — passing `/admin/settings` here would produce
  * `/admin/admin/settings`, which is exactly the class of mistake `adminHref` prevents.
  */
-export declare function navigate(routePath: string, options?: {
+export declare function navigate({ routePath, window }: {
+    readonly routePath: string;
+    readonly window: Pick<Window, 'location' | 'history' | 'dispatchEvent'>;
+}, options?: {
     readonly replace?: boolean;
     readonly base?: string;
 }): void;
@@ -33,7 +40,15 @@ export declare function navigate(routePath: string, options?: {
  *
  * @returns a teardown function.
  */
-export declare function installInternalLinkInterceptor(base?: string): () => void;
+export declare function installInternalLinkInterceptor({ window, document }: {
+    readonly window: Pick<Window, 'location' | 'history' | 'dispatchEvent'>;
+    readonly document: Pick<Document, 'addEventListener' | 'removeEventListener'>;
+}, { base }?: {
+    readonly base?: string;
+}): () => void;
 /** Subscribes to route changes from both `popstate` and programmatic `navigate()`. */
-export declare function subscribeToRoute(onChange: () => void): () => void;
+export declare function subscribeToRoute({ window, onChange }: {
+    readonly window: Pick<Window, 'addEventListener' | 'removeEventListener'>;
+    readonly onChange: () => void;
+}): () => void;
 //# sourceMappingURL=navigation.d.ts.map

package/dist/browser/navigation.js

@@ -12,8 +12,8 @@ import { DEFAULT_ADMIN_BASE, adminHref, currentRoutePath, stripTrailingSlash } f
 /** Fires on `navigate()`. `pushState` does not emit `popstate`, so subscribers need this too. */
 export const NAVIGATION_EVENT = 'jini:admin-navigate';
 /** The current route path, read from the address bar. */
-export function readRoutePath(base = DEFAULT_ADMIN_BASE) {
-    return currentRoutePath(window.location.pathname, base);
+export function readRoutePath({ window }, { base = DEFAULT_ADMIN_BASE } = {}) {
+    return currentRoutePath({ pathname: window.location.pathname }, { base });
 }
 /**
  * Navigates without a page load.
@@ -21,9 +21,9 @@ export function readRoutePath(base = DEFAULT_ADMIN_BASE) {
  * Takes a *route path*, not a URL — passing `/admin/settings` here would produce
  * `/admin/admin/settings`, which is exactly the class of mistake `adminHref` prevents.
  */
-export function navigate(routePath, options = {}) {
+export function navigate({ routePath, window }, options = {}) {
     const base = options.base ?? DEFAULT_ADMIN_BASE;
-    const url = adminHref(routePath, base);
+    const url = adminHref({ routePath }, { base });
     /*
      * Navigating to where you already are is a no-op, not a history entry. Without this, clicking
      * the already-active sidebar link five times pushes five identical entries and Back appears
@@ -41,7 +41,7 @@ export function navigate(routePath, options = {}) {
      * same-path/different-query navigation is a real one.
      */
     const target = new URL(url, window.location.href);
-    const isCurrent = stripTrailingSlash(target.pathname) === stripTrailingSlash(window.location.pathname) &&
+    const isCurrent = stripTrailingSlash({ pathname: target.pathname }) === stripTrailingSlash({ pathname: window.location.pathname }) &&
         target.search === window.location.search &&
         target.hash === window.location.hash;
     if (isCurrent)
@@ -63,7 +63,7 @@ export function navigate(routePath, options = {}) {
  *
  * @returns a teardown function.
  */
-export function installInternalLinkInterceptor(base = DEFAULT_ADMIN_BASE) {
+export function installInternalLinkInterceptor({ window, document }, { base = DEFAULT_ADMIN_BASE } = {}) {
     const onClick = (event) => {
         // Anything but an unmodified primary click is the browser's to handle: cmd/ctrl-click opens a
         // tab, shift-click a window, alt-click downloads.
@@ -96,13 +96,13 @@ export function installInternalLinkInterceptor(base = DEFAULT_ADMIN_BASE) {
         // `url.hash` is carried through: an in-page fragment (`/admin/settings#seo-defaults`) is not a
         // routing concern, but dropping it silently loses the anchor. It never reaches the matcher —
         // the route snapshot is path + query only — so preserving it cannot affect routing.
-        navigate(`${currentRoutePath(url.pathname, base)}${url.search}${url.hash}`, { base });
+        navigate({ window, routePath: `${currentRoutePath({ pathname: url.pathname }, { base })}${url.search}${url.hash}` }, { base });
     };
     document.addEventListener('click', onClick);
     return () => document.removeEventListener('click', onClick);
 }
 /** Subscribes to route changes from both `popstate` and programmatic `navigate()`. */
-export function subscribeToRoute(onChange) {
+export function subscribeToRoute({ window, onChange }) {
     window.addEventListener('popstate', onChange);
     window.addEventListener(NAVIGATION_EVENT, onChange);
     return () => {

package/dist/browser/shell-navigation.d.ts

@@ -0,0 +1,12 @@
+import type { AdminShellNavigationPort } from '../core/ports/shell.js';
+/**
+ * Adapt the existing browser router to the shell's object-based navigation port.
+ * @param args Required live browser location, history/event port and document port; the admin mount path is supplied on each port call.
+ * @returns A query-preserving History API adapter. Construct only in a browser host.
+ */
+export declare function createAdminShellNavigation(args: {
+    readonly location: Pick<Location, 'pathname' | 'search'>;
+    readonly window: Pick<Window, 'location' | 'history' | 'dispatchEvent' | 'addEventListener' | 'removeEventListener'>;
+    readonly document: Pick<Document, 'addEventListener' | 'removeEventListener'>;
+}): AdminShellNavigationPort;
+//# sourceMappingURL=shell-navigation.d.ts.map

package/dist/browser/shell-navigation.js

@@ -0,0 +1,16 @@
+import { currentRoutePath } from '../core/routing/rules.js';
+import { installInternalLinkInterceptor, navigate, subscribeToRoute } from './navigation.js';
+/**
+ * Adapt the existing browser router to the shell's object-based navigation port.
+ * @param args Required live browser location, history/event port and document port; the admin mount path is supplied on each port call.
+ * @returns A query-preserving History API adapter. Construct only in a browser host.
+ */
+export function createAdminShellNavigation(args) {
+    return {
+        readRoute: ({ base }) => `${currentRoutePath({ pathname: args.location.pathname }, { base })}${args.location.search}`,
+        subscribe: ({ onChange }) => subscribeToRoute({ window: args.window, onChange }),
+        navigate: ({ base, routePath }, options = {}) => navigate({ routePath, window: args.window }, { base, ...options }),
+        installLinkInterceptor: ({ base }) => installInternalLinkInterceptor({ window: args.window, document: args.document }, { base }),
+    };
+}
+//# sourceMappingURL=shell-navigation.js.map

package/dist/contracts/credential-management.d.ts

@@ -0,0 +1,8 @@
+/** Optional navigation to the host's single named-credential management home. */
+export interface CredentialManagementPort {
+    open(required: {
+        kind: 'source-control';
+    }, optional?: Record<string, never>): void;
+}
+export declare const credentialManagementToken: import("../core/module/token.js").AdminPortToken<CredentialManagementPort, "admin.credentials.management">;
+//# sourceMappingURL=credential-management.d.ts.map

package/dist/contracts/credential-management.js

@@ -0,0 +1,3 @@
+import { adminPort } from '../core/module/token.js';
+export const credentialManagementToken = adminPort({ id: 'admin.credentials.management' });
+//# sourceMappingURL=credential-management.js.map

package/dist/contracts/media-picker.d.ts

@@ -0,0 +1,17 @@
+/** Data returned across tab boundaries. Consumers need no media implementation import. */
+export interface MediaAsset {
+    readonly id: string;
+    readonly title: string;
+    readonly alt: string;
+    readonly contentType: string | null;
+    readonly publicUrl: string | null;
+}
+export interface MediaPickerPort {
+    pick(required: {
+        accept: readonly string[];
+    }, optional?: {
+        signal?: AbortSignal;
+    }): Promise<MediaAsset | null>;
+}
+export declare const mediaPickerToken: import("../core/module/token.js").AdminPortToken<MediaPickerPort, "admin.media.picker">;
+//# sourceMappingURL=media-picker.d.ts.map

package/dist/contracts/media-picker.js

@@ -0,0 +1,5 @@
+import { adminPort } from '../core/module/token.js';
+export const mediaPickerToken = adminPort({
+    id: 'admin.media.picker',
+});
+//# sourceMappingURL=media-picker.js.map

package/dist/contracts/playground-render-target.d.ts

@@ -0,0 +1,18 @@
+/** Opaque headlessly; browser hosts publish an actual portal container, never an id or flag. */
+export interface PlaygroundTargetSnapshot {
+    readonly target: object | null;
+}
+export interface PlaygroundRenderTargetPort {
+    getSnapshot(required?: Record<string, never>, optional?: Record<string, never>): PlaygroundTargetSnapshot;
+    subscribe(required: {
+        listener: () => void;
+    }, optional?: Record<string, never>): () => void;
+    /** A lease belongs to its publisher; releasing a stale lease cannot erase the current node. */
+    register(required: {
+        target: object;
+    }, optional?: Record<string, never>): {
+        release(required?: Record<string, never>, optional?: Record<string, never>): void;
+    };
+}
+export declare const playgroundRenderTargetToken: import("../core/module/token.js").AdminPortToken<PlaygroundRenderTargetPort, "admin.playground.render-target">;
+//# sourceMappingURL=playground-render-target.d.ts.map

package/dist/contracts/playground-render-target.js

@@ -0,0 +1,3 @@
+import { adminPort } from '../core/module/token.js';
+export const playgroundRenderTargetToken = adminPort({ id: 'admin.playground.render-target' });
+//# sourceMappingURL=playground-render-target.js.map

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

@@ -0,0 +1,138 @@
+/**
+ * @file The runtime half of `AdminEntityPort`: registration, descriptor validation, and the one
+ * erasure a screen generic over all entities needs.
+ *
+ * `core/ports/entities.ts` is types only, like every other port. Everything here is the code those
+ * types cannot be: checks that a descriptor is internally consistent, and the single cast that
+ * turns a descriptor-generic port into the shape a screen can hold.
+ *
+ * ## Why any of this is runtime rather than type-level
+ *
+ * Two of the descriptor's own promises are not expressible in the type system:
+ *
+ * - `titleField` names a `text` field on this same descriptor. Encoding that needs a conditional
+ *   type heavy enough to make every descriptor's error message unreadable — and a typo here is not
+ *   cosmetic: it makes every relation picker pointing at this entity render `undefined` for every
+ *   row, which looks like missing data rather than a typo.
+ * - `relation.target` names another *registered* entity. A descriptor cannot know what it will be
+ *   registered beside, so this can only be checked once the registry is assembled.
+ *
+ * Both are therefore checked at composition time, where they fail once, at startup, naming the
+ * problem — rather than at render time, silently, as blank cells.
+ */
+import type { AdminEntityDescriptor, AdminEntityField, AdminEntityPort, AdminEntityRegistry, AdminErasedEntityPort } from '../ports/entities.js';
+/**
+ * A row that does not match the descriptor its port advertises.
+ *
+ * This is the failure `eraseEntityPort`'s cast makes possible: the cast is sound in the direction
+ * that matters (a typed row *is* a bag of unknowns), and unsound only if an adapter lies about its
+ * own descriptor. Nothing in the type system catches that, so this is what does — as a report, not
+ * an exception: a mistyped field is a fidelity problem, and throwing on a read would take a
+ * mostly-working screen down over one bad cell.
+ */
+export interface AdminEntityRowViolation {
+    /** `descriptor.name` of the port that produced the row. */
+    readonly entity: string;
+    readonly operation: 'list' | 'get' | 'create' | 'update';
+    /** The offending row's `id`, or `'<no id>'` when that is itself what is wrong. */
+    readonly rowId: string;
+    /** Declared field name, `'id'`, or the undeclared key that appeared. */
+    readonly field: string;
+    readonly problem: 'missing-required' | 'wrong-type' | 'undeclared-field';
+    /** One sentence naming what was expected and what arrived. Safe to log verbatim. */
+    readonly detail: string;
+}
+export interface AdminEntityErasureOptions {
+    /**
+     * Where descriptor-conformance violations are reported.
+     *
+     * **Omit it and no row checking runs at all** — that is the zero-cost default, and it is why this
+     * package emits no diagnostics of its own (nothing here writes to `console`; a host owns its
+     * reporting the same way it owns its transport). A host wires this under its own development
+     * flag and gets adapter drift surfaced the moment it happens; production pays nothing.
+     */
+    readonly onViolation?: (violation: AdminEntityRowViolation) => void;
+}
+/**
+ * Whether `value` is a legal runtime value for `field`.
+ *
+ * Exported because an EDITOR needs exactly this judgement and must not re-derive it. A generic form
+ * that decides for itself what an `integer` accepts will drift from what the conformance walk
+ * below rejects, and the two disagreeing is worse than either being wrong alone: the form saves a
+ * value the port then reports as a violation, so the write succeeds and the diagnostic blames the
+ * adapter. `1.5` in an `integer` and `Infinity` in a `real` are both reachable from a plain
+ * `<input type="number">` — `step` constrains the spinner, not the parsed value — so this is not a
+ * theoretical seam. One function, both callers.
+ *
+ * @param field The declared field the value is destined for.
+ * @param value The candidate value, typically a form draft entry or an adapter-returned cell.
+ * @returns `null` when it conforms, otherwise a one-phrase reason naming what arrived instead.
+ *   Phrased to complete the sentence "declared `<kind>`; ...".
+ * @complexity Time O(1) for every kind but `json`; see {@link describeNonJsonValue} for that one.
+ * @overallScore 100
+ */
+export declare function describeAdminEntityFieldMismatch(field: AdminEntityField, value: unknown): string | null;
+/**
+ * Erases a port's descriptor generic so a screen can hold ports for different entities in one
+ * collection.
+ *
+ * The `as unknown as` below is unavoidable and is the only one in this port. `create` and `update`
+ * take the row type as a *parameter*, so `AdminEntityPort<SpecificDescriptor>` is contravariant in
+ * it and is genuinely not assignable to any common supertype. The cast is sound in the direction
+ * that gets exercised — a typed row is a bag of unknowns — and unsound only if the adapter's rows
+ * do not match the descriptor it advertises, which is precisely what `options.onViolation` is here
+ * to surface.
+ *
+ * @param port A port whose rows are typed by its own descriptor.
+ * @param options Wire `onViolation` to have every row checked against the descriptor on the way
+ *   out; omit it for zero added cost.
+ * @returns The same port, typed as {@link AdminErasedEntityPort}; a fresh wrapper object when
+ *   `onViolation` is set, and the original object when it is not.
+ * @complexity Time O(1) to erase; O(rows × fields) per call when checking is on.
+ * @overallScore 100
+ */
+export declare function eraseEntityPort<D extends AdminEntityDescriptor>(port: AdminEntityPort<D>, options?: AdminEntityErasureOptions): AdminErasedEntityPort;
+/**
+ * Assembles entity ports into a registry, validating every descriptor first.
+ *
+ * Same ergonomics as `createAdminClient`: one object literal, `TPorts` inferred, host-owned and
+ * Jini-shipped entries indistinguishable. Registering an entity is one line.
+ *
+ * **No key is reserved.** `createAdminClient` reserves `'transport'` because it merges the
+ * transport into the same object it returns; this returns nothing but the ports, so there is
+ * nothing an entity named `transport` could shadow. The returned object has a `null` prototype, so
+ * a lookup by an attacker- or URL-supplied name (`'constructor'`, `'__proto__'`) resolves to
+ * `undefined` rather than walking to `Object.prototype` and yielding a truthy non-port.
+ *
+ * Deliberately takes no erasure options: a registry holds ports with their row types intact, and
+ * checking only becomes possible once those types are erased. `onViolation` therefore belongs to
+ * {@link getErasedEntityPort}/{@link listErasedEntityPorts}, at the point the guarantee is dropped.
+ *
+ * @param ports Entity name -> port. Each key must equal that port's `descriptor.name`.
+ * @returns A frozen, null-prototype registry preserving each port's own type.
+ * @throws {Error} listing *every* problem found, not just the first — a descriptor with three
+ *   typos should take one round trip to fix, not three.
+ * @complexity Time O(entities × fields); space O(entities).
+ * @overallScore 100
+ */
+export declare function createAdminEntityRegistry<TPorts extends Record<string, AdminEntityPort<AdminEntityDescriptor>>>(ports: TPorts): AdminEntityRegistry<TPorts>;
+/**
+ * Every registered port, erased, in registration order — what a screen that renders any entity
+ * iterates.
+ *
+ * @complexity Time O(entities); space O(entities).
+ * @overallScore 100
+ */
+export declare function listErasedEntityPorts(registry: Readonly<Record<string, AdminEntityPort<AdminEntityDescriptor>>>, options?: AdminEntityErasureOptions): readonly AdminErasedEntityPort[];
+/**
+ * The erased port registered under `name`, or `null`.
+ *
+ * `name` is routinely a URL segment, so this never trusts a bare property read: the registry's null
+ * prototype already stops `'constructor'` resolving to something truthy, and `Object.hasOwn` holds
+ * that guarantee even for a caller that hands in a plain object literal instead.
+ *
+ * @complexity Time O(1) for the lookup, O(1) for the erasure.
+ * @overallScore 100
+ */
+export declare function getErasedEntityPort(registry: Readonly<Record<string, AdminEntityPort<AdminEntityDescriptor>>>, name: string, options?: AdminEntityErasureOptions): AdminErasedEntityPort | null;
+//# sourceMappingURL=rules.d.ts.map