@jini-ai/admin 0.3.9 → 0.4.0

package/dist/core/module/create-admin.js

@@ -0,0 +1,187 @@
+export class AdminConfigError extends Error {
+    issues;
+    constructor({ issues }, _optional = {}) {
+        super(`Invalid admin configuration:\n${issues.map((issue) => `- ${issue}`).join('\n')}`);
+        this.name = 'AdminConfigError';
+        this.issues = Object.freeze([...issues]);
+    }
+}
+export function createAdmin({ modules, ports, }, options = {}) {
+    const issues = [];
+    const tokens = new Map();
+    const identities = new Map();
+    const providers = new Map();
+    const ids = new Set(), paths = new Set(), tabIds = new Set();
+    const requiredNames = new Set();
+    const host = ports;
+    const values = { ...host };
+    const omitted = new Set(options.omit ?? []);
+    const grants = new Set(options.permissions ?? []);
+    const allowed = (permissions = []) => permissions.every((p) => grants.has(p));
+    function collect(map = {}, required = false) {
+        for (const [name, tok] of Object.entries(map)) {
+            const old = tokens.get(name);
+            if (!tok.id || tok.cardinality !== 'one' || !Number.isInteger(tok.version) || tok.version < 1)
+                issues.push(`Invalid token: ${name}`);
+            if (old && (old.id !== tok.id || old.version !== tok.version))
+                issues.push(`Incompatible token: ${name}`);
+            const alias = identities.get(tok.id);
+            if (alias && alias !== name)
+                issues.push(`Token ${tok.id} has conflicting names: ${alias}, ${name}`);
+            identities.set(tok.id, name);
+            tokens.set(name, tok);
+            if (required)
+                requiredNames.add(name);
+        }
+    }
+    for (const module of modules) {
+        if (ids.has(module.id))
+            issues.push(`Duplicate module: ${module.id}`);
+        ids.add(module.id);
+        collect(module.requires, true);
+        collect(module.optional);
+        collect(module.provides);
+        for (const name of Object.keys(module.provides ?? {})) {
+            if (providers.has(name))
+                issues.push(`Duplicate provider: ${name}`);
+            providers.set(name, module);
+            if (host[name] != null &&
+                !options.overrides?.includes(name))
+                issues.push(`Provider collision: ${name}; declare an override`);
+            if (!module.factories?.[name] && host[name] == null)
+                issues.push(`Missing provider factory: ${name}`);
+        }
+        for (const name of Object.keys(module.factories ?? {}))
+            if (!(name in (module.provides ?? {})))
+                issues.push(`Undeclared provider factory: ${name}`);
+        for (const [pageId, page] of Object.entries(module.pages)) {
+            if (paths.has(page.path))
+                issues.push(`Duplicate route: ${page.path}`);
+            paths.add(page.path);
+            for (const [tabId, tab] of Object.entries(page.tabs)) {
+                const full = `${module.id}.${pageId}.${tabId}`;
+                tabIds.add(full);
+                collect(tab.requires, !omitted.has(full));
+                collect(tab.optional);
+            }
+        }
+    }
+    for (const id of omitted)
+        if (!tabIds.has(id))
+            issues.push(`Unknown tab: ${id}`);
+    for (const name of options.overrides ?? [])
+        if (!providers.has(String(name)))
+            issues.push(`Unknown provider override: ${String(name)}`);
+    for (const name of Object.keys(host))
+        if (!tokens.has(name))
+            issues.push(`Unknown port: ${name}`);
+    for (const name of requiredNames)
+        if (host[name] == null && !providers.has(name))
+            issues.push(`Missing port: ${name}`);
+    // Validate the graph before executing factories, so a boot error has no partial side effects.
+    const sorted = [], visiting = new Set(), visited = new Set();
+    function visit(name, chain) {
+        if (visited.has(name) || host[name] != null)
+            return;
+        if (visiting.has(name)) {
+            issues.push(`Provider cycle: ${[...chain, name].join(' -> ')}`);
+            return;
+        }
+        visiting.add(name);
+        const module = providers.get(name);
+        for (const dep of Object.keys(dependencies(module)))
+            if (providers.has(dep))
+                visit(dep, [...chain, name]);
+        visiting.delete(name);
+        visited.add(name);
+        sorted.push(name);
+    }
+    for (const name of providers.keys())
+        visit(name, []);
+    if (issues.length)
+        throw new AdminConfigError({ issues: [...new Set(issues)] });
+    const disposables = [];
+    function dependencies(module) {
+        const tabPorts = Object.values(module.pages)
+            .flatMap((page) => Object.values(page.tabs))
+            .reduce((result, tab) => ({ ...result, ...tab.requires, ...tab.optional }), {});
+        return { ...module.requires, ...module.optional, ...tabPorts };
+    }
+    function narrow(module) {
+        return Object.freeze(Object.fromEntries(Object.keys(dependencies(module)).map((name) => [name, values[name]])));
+    }
+    try {
+        for (const name of sorted) {
+            const value = providers.get(name).factories[name]({ ports: narrow(providers.get(name)), permissions: [...grants] }, {});
+            if (value == null)
+                throw new Error(`Provider returned no value: ${name}`);
+            values[name] = value;
+            if (typeof value === 'object' && 'dispose' in value && typeof value.dispose === 'function')
+                disposables.push(value);
+        }
+    }
+    catch (error) {
+        for (const value of disposables.reverse())
+            value.dispose();
+        throw new AdminConfigError({
+            issues: [error instanceof Error ? error.message : 'Provider initialization failed'],
+        });
+    }
+    const description = Object.freeze({
+        modules: Object.freeze([...ids]),
+        pages: Object.freeze(modules.flatMap((module) => Object.entries(module.pages).map(([id, page]) => ({
+            id: `${module.id}.${id}`,
+            path: page.path,
+            label: page.label,
+            visible: allowed(page.permissions),
+            agentReachable: page.agentReachable === true && allowed(page.permissions),
+            permissions: page.permissions ?? [],
+            grants: Object.freeze([...grants]),
+            ...(page.nav ? { nav: page.nav } : {}),
+            tabs: Object.entries(page.tabs).map(([tabId, tab]) => {
+                const full = `${module.id}.${id}.${tabId}`;
+                const absent = Object.keys(tab.optional ?? {}).find((name) => values[name] == null);
+                const reason = omitted.has(full)
+                    ? 'omitted'
+                    : !allowed(page.permissions) || !allowed(tab.permissions)
+                        ? 'permission denied'
+                        : absent
+                            ? `optional port unavailable: ${absent}`
+                            : null;
+                return {
+                    id: full,
+                    label: tab.label,
+                    visible: reason === null,
+                    reason,
+                    params: tab.params ?? {},
+                    agentReachable: reason === null && page.agentReachable === true && tab.agentReachable === true,
+                };
+            }),
+        })))),
+        ports: Object.freeze([...tokens]
+            .filter(([name]) => values[name] != null)
+            .map(([name, tok]) => ({
+            name,
+            token: tok.id,
+            version: tok.version,
+            source: host[name] != null ? 'host' : 'module',
+        }))),
+    });
+    let disposed = false;
+    return {
+        describe: () => description,
+        scope: ({ module }) => {
+            if (disposed || !modules.includes(module))
+                throw new AdminConfigError({ issues: [`Module scope unavailable: ${module.id}`] });
+            return narrow(module);
+        },
+        dispose: () => {
+            if (!disposed) {
+                disposed = true;
+                for (const value of disposables.reverse())
+                    value.dispose();
+            }
+        },
+    };
+}
+//# sourceMappingURL=create-admin.js.map

package/dist/core/module/define-admin-module.d.ts

@@ -0,0 +1,4 @@
+import type { AdminModule } from './types.js';
+/** Definition is data only; boot validates identities before any factory runs. */
+export declare function defineAdminModule<const M extends AdminModule>(required: M, _optional?: Record<string, never>): M;
+//# sourceMappingURL=define-admin-module.d.ts.map

package/dist/core/module/define-admin-module.js

@@ -0,0 +1,5 @@
+/** Definition is data only; boot validates identities before any factory runs. */
+export function defineAdminModule(required, _optional = {}) {
+    return Object.freeze(required);
+}
+//# sourceMappingURL=define-admin-module.js.map

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

@@ -0,0 +1,7 @@
+export { adminPort } from './token.js';
+export type { AdminPortToken, PortMap, PortValues } from './token.js';
+export { defineAdminModule } from './define-admin-module.js';
+export { createAdmin, AdminConfigError } from './create-admin.js';
+export type { AdminHostPorts, AdminOptions } from './create-admin.js';
+export type { AdminModule, AdminPage, AdminTab, AdminInstance, AdminDescription, ScopedPorts, TabId, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/module/index.js

@@ -0,0 +1,4 @@
+export { adminPort } from './token.js';
+export { defineAdminModule } from './define-admin-module.js';
+export { createAdmin, AdminConfigError } from './create-admin.js';
+//# sourceMappingURL=index.js.map

package/dist/core/module/token.d.ts

@@ -0,0 +1,19 @@
+/** Structurally compatible with @jini-ai/core's singleton Token<T, Id>.
+ * Admin currently has no core dependency or core/token export to reuse. Keep the same
+ * named/versioned wire identity without adding an undeclared runtime dependency. */
+export interface AdminPortToken<T = unknown, Id extends string = string> {
+    readonly id: Id;
+    readonly version: number;
+    readonly cardinality: 'one';
+    readonly __type?: T;
+}
+export declare function adminPort<T, const Id extends string = string>({ id }: {
+    id: Id;
+}, { version }?: {
+    version?: number;
+}): AdminPortToken<T, Id>;
+export type PortMap = Readonly<Record<string, AdminPortToken>>;
+export type PortValues<P extends PortMap> = {
+    readonly [K in keyof P]: P[K] extends AdminPortToken<infer T> ? T : never;
+};
+//# sourceMappingURL=token.d.ts.map

package/dist/core/module/token.js

@@ -0,0 +1,4 @@
+export function adminPort({ id }, { version = 1 } = {}) {
+    return Object.freeze({ id, version, cardinality: 'one' });
+}
+//# sourceMappingURL=token.js.map

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

@@ -0,0 +1,79 @@
+import type { PortMap, PortValues } from './token.js';
+export interface AdminTab {
+    readonly label: string;
+    readonly params?: Readonly<Record<string, unknown>>;
+    readonly requires?: PortMap;
+    /** A tab depending on an unwired optional port is hidden, with a reason in describe(). */
+    readonly optional?: PortMap;
+    readonly permissions?: readonly string[];
+    readonly agentReachable?: boolean;
+}
+export interface AdminPage {
+    readonly path: string;
+    readonly label: string;
+    readonly nav?: {
+        readonly group: string;
+        readonly icon?: string;
+    };
+    readonly permissions?: readonly string[];
+    readonly agentReachable?: boolean;
+    readonly tabs: Readonly<Record<string, AdminTab>>;
+}
+export interface AdminModule {
+    readonly id: string;
+    readonly requires?: PortMap;
+    readonly optional?: PortMap;
+    readonly provides?: PortMap;
+    readonly pages: Readonly<Record<string, AdminPage>>;
+    readonly messages?: Readonly<Record<string, string>>;
+    readonly factories?: Readonly<Record<string, (required: {
+        ports: Readonly<Record<string, unknown>>;
+        permissions: readonly string[];
+    }, optional?: Record<string, never>) => unknown>>;
+}
+type Intersect<U> = (U extends unknown ? (value: U) => void : never) extends (value: infer I) => void ? I : never;
+type TabPortValues<M extends AdminModule> = {
+    [P in keyof M['pages']]: {
+        [T in keyof M['pages'][P]['tabs']]: M['pages'][P]['tabs'][T] extends infer Tab ? Tab extends AdminTab ? PortValues<NonNullable<Tab['requires']>> & PortValues<NonNullable<Tab['optional']>> : {} : never;
+    }[keyof M['pages'][P]['tabs']];
+}[keyof M['pages']];
+export type ScopedPorts<M extends AdminModule> = PortValues<NonNullable<M['requires']>> & Partial<PortValues<NonNullable<M['optional']>> & Intersect<TabPortValues<M>>>;
+export type TabId<M extends AdminModule> = M extends unknown ? {
+    [P in keyof M['pages'] & string]: `${M['id']}.${P}.${keyof M['pages'][P]['tabs'] & string}`;
+}[keyof M['pages'] & string] : never;
+export interface AdminDescription {
+    readonly modules: readonly string[];
+    readonly pages: readonly {
+        id: string;
+        path: string;
+        label: string;
+        visible: boolean;
+        agentReachable: boolean;
+        permissions: readonly string[];
+        grants: readonly string[];
+        nav?: AdminPage['nav'];
+        tabs: readonly {
+            id: string;
+            label: string;
+            visible: boolean;
+            reason: string | null;
+            params: Readonly<Record<string, unknown>>;
+            agentReachable: boolean;
+        }[];
+    }[];
+    readonly ports: readonly {
+        name: string;
+        token: string;
+        version: number;
+        source: 'host' | 'module';
+    }[];
+}
+export interface AdminInstance {
+    describe(required?: Record<string, never>, optional?: Record<string, never>): AdminDescription;
+    scope<M extends AdminModule>(required: {
+        module: M;
+    }, optional?: Record<string, never>): ScopedPorts<M>;
+    dispose(required?: Record<string, never>, optional?: Record<string, never>): void;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/core/module/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -28,5 +28,8 @@
  * @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;
+export declare function hasPermission({ permissions, permission }: {
+    readonly permissions: readonly string[];
+    readonly permission: string;
+}): boolean;
 //# sourceMappingURL=rules.d.ts.map

package/dist/core/permissions/rules.js

@@ -28,7 +28,7 @@
  * @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) {
+export function hasPermission({ permissions, permission }) {
     return permissions.includes('*') || permissions.includes(permission);
 }
 //# sourceMappingURL=rules.js.map

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

@@ -28,7 +28,7 @@ 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?: {
+    listRecentAnalyticsHits(requiredArgs: Record<string, never>, optionalArgs?: {
         limit?: number;
     }): Promise<readonly AdminAnalyticsHit[]>;
 }

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

@@ -30,7 +30,7 @@ export interface AdminAuthPort {
     }): Promise<{
         user: AdminAuthUser;
     }>;
-    logout(): Promise<{
+    logout(requiredArgs: Record<string, never>): Promise<{
         ok: boolean;
     }>;
     /**
@@ -41,7 +41,7 @@ export interface AdminAuthPort {
      * entirely rather than send an empty array; callers should not treat "absent" and "empty" as the
      * same thing.
      */
-    me(): Promise<{
+    me(requiredArgs: Record<string, never>): Promise<{
         user: AdminAuthUser;
         effectivePermissions?: readonly string[];
     }>;

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

@@ -68,23 +68,26 @@ export interface CommentsSettings {
  *  fifth member of this union. */
 export type CommentModerationAction = "approve" | "spam" | "trash" | "restore";
 export interface AdminCommentsPort {
-    listCommentsQueue(options?: {
+    listCommentsQueue(requiredArgs: Record<string, never>, optionalArgs?: {
         status?: CommentStatus;
         cursor?: string;
         limit?: number;
     }): Promise<AdminCommentsQueuePage>;
     /** See the file header: resolves to `void` even on success. */
-    moderateComment(commentId: string, input: {
+    moderateComment(requiredArgs: {
+        commentId: string;
         action: CommentModerationAction;
         expectedVersion: number;
-    }, options?: {
+    }, optionalArgs?: {
         note?: string;
     }): Promise<void>;
     /** Hard delete, no version guard, separate permission — see the file header. */
-    purgeComment(commentId: string, options?: {
+    purgeComment(requiredArgs: {
+        commentId: string;
+    }, optionalArgs?: {
         note?: string;
     }): Promise<void>;
-    getCommentsSettings(): Promise<CommentsSettings>;
-    putCommentsSettings(patch?: Partial<CommentsSettings>): Promise<CommentsSettings>;
+    getCommentsSettings(requiredArgs: Record<string, never>): Promise<CommentsSettings>;
+    putCommentsSettings(requiredArgs: Record<string, never>, optionalArgs?: Partial<CommentsSettings>): Promise<CommentsSettings>;
 }
 //# sourceMappingURL=comments.d.ts.map

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

@@ -10,12 +10,14 @@
  * This port owns the type since `createDatabaseRestorePoint` is where a restore point actually
  * comes into being; `recovery.ts` imports it rather than redeclaring it.
  *
- * ## `migrateForward` satisfies `GatedOperation`; see `recovery.ts` for the triad that doesn't
+ * ## Both migration and restore satisfy `GatedOperation`, with different input needs
  *
  * The reference implementation's `planMigrateForward` takes no input and `executeMigrateForward` takes only the
  * confirmation token — no operation-specific extra fields on any of the three calls. That means
- * this triad is a clean, direct instance of `../gated/types.js`'s `GatedOperation`, unlike
- * Recovery's restore ceremony (see that file's header for why restore is different). A
+ * this triad is a clean, direct instance of `../gated/types.js`'s `GatedOperation` using its
+ * default confirm/execute inputs. Recovery's restore ceremony uses the same abstraction with operation-specific
+ * confirm/execute inputs to record disclosure consent and bind the restore target (see that
+ * file's header for why those extra fields matter). A
  * compile-time assertion of that fact lives in `../__tests__/database-gated.test.ts`.
  */
 import type { GatedConfirmResult, GatedOperation, GatedPlanResult } from '../gated/types.js';
@@ -68,7 +70,7 @@ export interface AdminDatabasePort {
      * `outcome` and bounded by `fromDate`/`toDate`. Keyset-paginated via `cursor`/`nextCursor`, not
      * offset-paginated — do not compute a page number from `limit`.
      */
-    getDatabaseTimeline(options?: {
+    getDatabaseTimeline(requiredArgs: Record<string, never>, optionalArgs?: {
         kind?: string;
         outcome?: string;
         fromDate?: string;
@@ -79,23 +81,24 @@ export interface AdminDatabasePort {
         items: readonly AdminLedgerRow[];
         nextCursor: string | null;
     }>;
-    listDatabaseRestorePoints(): Promise<readonly AdminRestorePoint[]>;
+    listDatabaseRestorePoints(requiredArgs: Record<string, never>): Promise<readonly AdminRestorePoint[]>;
     /**
      * Captures a new restore point on demand. `costAck` should be `true` once the operator has
      * acknowledged a shown cost warning for a `RestorePointCostClass` of `"expensive"` — a host may
      * reject the call without it rather than silently proceeding.
      */
-    createDatabaseRestorePoint(options?: {
+    createDatabaseRestorePoint(requiredArgs: Record<string, never>, optionalArgs?: {
         trigger?: string;
         costAck?: boolean;
     }): Promise<AdminRestorePointSummary>;
     /**
      * The forward-migration ceremony (schema/data migration to the host's current expected state),
-     * as a `GatedOperation` — see the file header for why this triad, unlike Recovery's restore, fits
-     * the generic shape directly. `plan` takes no meaningful input beyond the ceremony trigger; the
-     * plan is computed entirely from the site's current migration state server-side.
+     * as a `GatedOperation` — see the file header for why this triad uses the default confirm/execute
+     * inputs while Recovery's restore supplies operation-specific ones. `plan` takes no meaningful
+     * input beyond the ceremony trigger; the plan is computed entirely from the site's current
+     * migration state server-side.
      */
-    readonly migrateForward: GatedOperation<void, unknown, MigrateForwardResult>;
+    readonly migrateForward: GatedOperation<Record<string, never>, unknown, MigrateForwardResult>;
 }
 export type { GatedConfirmResult, GatedOperation, GatedPlanResult };
 //# sourceMappingURL=database.d.ts.map