@ultimat3/admin 30.2.0 → 30.4.0

package/README.md

@@ -482,7 +482,13 @@ The admin exposes **its own MCP surface**, derived from the same resources and g
 ```ts
 import { adminMcp, adminMcpTools } from '@ultimat3/admin';
 
-export const mcp = adminMcp({ app: admin, actor: (session) => actorFor(session.token) });
+// apps/admin/mcp.ts — module scope: the mount serves every apps/<app>/mcp.ts, after the scan
+export const mcp = adminMcp({
+  app: admin,
+  path: '/admin/mcp', // beside the web endpoint's /mcp
+  include: 'exposed', // the app's exposed actions (admin:write) and queries (admin:read) too
+  actor: ({ token, facts }) => actorFor(token, facts),
+});
 adminMcpTools(admin, ctx); // admin.post.list · admin.post.read · admin.search · admin.action.post.publish
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/admin",
-  "version": "30.2.0",
+  "version": "30.4.0",
   "description": "Two dashboards: the /_x framework dev panels and the generated, AI-first app admin",
   "keywords": [
     "ultimate",
@@ -45,21 +45,21 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "30.2.0",
-    "@ultimat3/ai": "30.2.0",
-    "@ultimat3/cache": "30.2.0",
-    "@ultimat3/core": "30.2.0",
-    "@ultimat3/db": "30.2.0",
-    "@ultimat3/entity": "30.2.0",
-    "@ultimat3/http": "30.2.0",
-    "@ultimat3/i18n": "30.2.0",
-    "@ultimat3/jobs": "30.2.0",
-    "@ultimat3/mcp": "30.2.0",
-    "@ultimat3/money": "30.2.0",
-    "@ultimat3/policy": "30.2.0",
-    "@ultimat3/query": "30.2.0",
-    "@ultimat3/render": "30.2.0",
-    "@ultimat3/schema": "30.2.0",
-    "@ultimat3/ui": "30.2.0"
+    "@ultimat3/action": "30.4.0",
+    "@ultimat3/ai": "30.4.0",
+    "@ultimat3/cache": "30.4.0",
+    "@ultimat3/core": "30.4.0",
+    "@ultimat3/db": "30.4.0",
+    "@ultimat3/entity": "30.4.0",
+    "@ultimat3/http": "30.4.0",
+    "@ultimat3/i18n": "30.4.0",
+    "@ultimat3/jobs": "30.4.0",
+    "@ultimat3/mcp": "30.4.0",
+    "@ultimat3/money": "30.4.0",
+    "@ultimat3/policy": "30.4.0",
+    "@ultimat3/query": "30.4.0",
+    "@ultimat3/render": "30.4.0",
+    "@ultimat3/schema": "30.4.0",
+    "@ultimat3/ui": "30.4.0"
   }
 }

package/src/errors.ts

@@ -30,6 +30,7 @@ export const ADMIN_OWNED_ERROR_CODES = [
   'X_ADMIN_ACTION_NOT_APPLICABLE',
   'X_ADMIN_MOUNT_MISSING',
   'X_ADMIN_VIEW_WRITE',
+  'X_ADMIN_READ_ONLY_WRITE',
 ] as const;
 
 /**
@@ -64,6 +65,7 @@ export const ADMIN_ERROR_TITLES: Readonly<Record<AdminOwnedErrorCode, string>> =
   X_ADMIN_ACTION_NOT_APPLICABLE: 'an admin action was run on a row its when() rule excludes',
   X_ADMIN_MOUNT_MISSING: 'an admin batch job ran in a process that never declared its admin',
   X_ADMIN_VIEW_WRITE: 'an admin resource over a view entity offers a write',
+  X_ADMIN_READ_ONLY_WRITE: 'an admin resource over a readOnly entity offers a write',
 };
 
 // One unconditional call, so a second package claiming one of admin's codes throws

package/src/mcp-scopes.ts

@@ -2,10 +2,10 @@
 // what a resolved token carries. The gate itself is `@ultimat3/mcp`'s registry — this file only
 // declares the cut (`defineAppMcp({ scopes })`) and the token's half of it.
 
-import type { McpScopes } from '@ultimat3/mcp';
+import type { McpScopes, ProjectablePrimitive } from '@ultimat3/mcp';
 import { expandPermissions } from './authz';
 import type { AdminMcpTool } from './mcp-tools';
-import { ADMIN_DESTROY, ADMIN_PERMISSIONS } from './permissions';
+import { ADMIN_DESTROY, ADMIN_PERMISSIONS, ADMIN_READ, ADMIN_WRITE } from './permissions';
 
 const isAdminPermission = (scope: string): boolean =>
   (ADMIN_PERMISSIONS as readonly string[]).includes(scope);
@@ -34,3 +34,21 @@ export function adminToolScopes(tools: readonly AdminMcpTool[]): McpScopes {
   for (const tool of tools) by.set(tool.scope, [...(by.get(tool.scope) ?? []), tool.name]);
   return Object.fromEntries(by);
 }
+
+/**
+ * The app's exposed primitives an admin endpoint serves (`adminMcp({ include: 'exposed' })`),
+ * each under the admin scope its KIND needs — a query reads, an action writes; the framework
+ * cannot tell an insert from a delete, so never `admin:destroy`. Merged into the admin's own cut,
+ * so the map stays total and a read-only token stays read-only on the app's tools too.
+ */
+export function includedToolScopes(
+  primitives: readonly ProjectablePrimitive[],
+  scopes: McpScopes,
+): McpScopes {
+  const by = new Map(Object.entries(scopes).map(([scope, names]) => [scope, [...names]]));
+  for (const primitive of primitives) {
+    const scope = primitive.mutates === false ? ADMIN_READ : ADMIN_WRITE;
+    by.set(scope, [...(by.get(scope) ?? []), primitive.name]);
+  }
+  return Object.fromEntries(by);
+}

package/src/mcp.ts

@@ -8,9 +8,11 @@ import {
   type AnyMcpTool,
   type AppMcp,
   defineAppMcp,
+  exposedPrimitives,
   type JsonSchema,
   jsonResult,
   type McpCaller,
+  type McpRequestFacts,
   type McpToolResult,
   type ResolvedToken,
   type ToolArgs,
@@ -33,7 +35,7 @@ import {
 import { AdminFilterInvalidError } from './errors';
 import type { AdminFieldType } from './fields';
 import { type AskedFilter, checkedFilter } from './list-filters';
-import { adminTokenScopes, adminToolScopes } from './mcp-scopes';
+import { adminTokenScopes, adminToolScopes, includedToolScopes } from './mcp-scopes';
 import { type AdminMcpTool, adminMcpTools, adminToolCatalog } from './mcp-tools';
 import type { AdminAction, AdminRow } from './registry';
 import { adminSearch } from './search';
@@ -250,9 +252,23 @@ export interface AdminMcpActor extends AdminActor {
 
 export interface AdminMcpOptions {
   readonly app: AdminApp;
-  /** Resolve the MCP session's actor. The same hook the HTTP surface uses, never a bypass. */
-  actor(session: { readonly token?: string }): Promise<AdminMcpActor | null> | AdminMcpActor | null;
+  /**
+   * Resolve the MCP session's actor. The same hook the HTTP surface uses, never a bypass. `facts`:
+   * how the request arrived (address, `Origin`) — what a development token is decided on.
+   */
+  actor(session: {
+    readonly token?: string;
+    readonly facts?: McpRequestFacts;
+  }): Promise<AdminMcpActor | null> | AdminMcpActor | null;
   readonly requestId?: () => string;
+  /** Mount path, `defineAppMcp`'s own. Default `/mcp`; an admin surface beside the app's says `/admin/mcp`. */
+  readonly path?: string;
+  /**
+   * `'exposed'`: the app's own MCP tools here too, projected by `defineAppMcp` as on `/mcp`, each
+   * under its kind's admin scope (`includedToolScopes`). Call `adminMcp` at module scope in
+   * `apps/<app>/mcp.ts`: the mount refuses a catalog built before the scan ended (`X_MCP_INCLUDE_EARLY`).
+   */
+  readonly include?: 'exposed';
 }
 
 /** A field type an agent can actually send. Anything richer is a JSON object on the wire. */
@@ -436,15 +452,20 @@ export function adminMcp(opts: AdminMcpOptions): AppMcp {
   const requestId = opts.requestId ?? ((): string => crypto.randomUUID());
   const catalog = adminToolCatalog(opts.app);
 
+  const own = adminToolScopes(catalog);
+
   return defineAppMcp({
     name: 'admin',
     tools: catalog.map((tool) => toMcpTool(opts, requestId, tool)),
+    ...(opts.path === undefined ? {} : { path: opts.path }),
+    // The app's tools are `defineAppMcp`'s projection, never a copy; the scopes read the same registry.
+    ...(opts.include === undefined ? {} : { include: opts.include }),
     // The connection gate: each tool needs its admin-level permission as a token scope, checked
     // by the registry BEFORE the actor's policy. A stdio host builds its caller's scopes with
     // `adminTokenScopes`, as `resolveToken` does below.
-    scopes: adminToolScopes(catalog),
-    async resolveToken(token: string): Promise<ResolvedToken | null> {
-      const actor = await opts.actor({ token });
+    scopes: opts.include === 'exposed' ? includedToolScopes(exposedPrimitives(), own) : own,
+    async resolveToken(token: string, facts: McpRequestFacts): Promise<ResolvedToken | null> {
+      const actor = await opts.actor({ token, facts });
       // `kind: 'agent'` — the same actor shape an agent gets everywhere else, so a policy
       // that distinguishes agents from people keeps working on this surface.
       //

package/src/registry.ts

@@ -86,6 +86,8 @@ export interface AdminEntity {
    * hand-built fixture has none; a view offers reads alone (`resource-operations.ts`).
    */
   readonly $viewQuery?: { readonly materialized: boolean } | null;
+  /** `entity({ readOnly })`'s reason, `null` on a table the app writes: reads alone, as a view. */
+  readonly $readOnly?: string | null;
   /** Resolves foreign-key targets. See `entity-columns.ts` for what the admin takes from it. */
   $describe(): AdminEntityDescription;
 }

package/src/resource-operations.ts

@@ -1,7 +1,7 @@
 // Single responsibility: which operations an admin resource offers. Every one, by default, on a
-// table; only the reads on a view entity (`entity({ view })`), whose rows Postgres derives — so a
-// view gets no create/edit/delete route, button or MCP tool, and an override asking for one is
-// refused where it was declared.
+// table; only the reads on a view entity (`entity({ view })`), whose rows Postgres derives, and on a
+// `readOnly` one — so neither gets a create/edit/delete route, button or MCP tool, and an override
+// asking for one is refused where it was declared.
 
 import { renderFixShellArg, UltimateError } from '@ultimat3/core';
 import { ADMIN_OPERATIONS, type AdminOperation } from './permissions';
@@ -23,14 +23,34 @@ export class AdminViewWriteError extends UltimateError {
   }
 }
 
+/** An admin resource over a `readOnly` entity was declared with a write its repository refuses. */
+export class AdminReadOnlyWriteError extends UltimateError {
+  constructor(input: {
+    readonly entity: string;
+    readonly reason: string;
+    readonly writes: readonly AdminOperation[];
+  }) {
+    super({
+      code: 'X_ADMIN_READ_ONLY_WRITE',
+      cause: `${input.entity} is readOnly (${input.reason}), and its admin resource offers ${input.writes.join(', ')} — every one would be refused with X_ENTITY_READ_ONLY`,
+      fix: `x entities show ${renderFixShellArg(input.entity, '<entity>')} --json   # then drop operations from its admin resource (a readOnly table lists read-only), or name only ${VIEW_OPERATIONS.join(', ')}`,
+    });
+  }
+}
+
 export function operationsFor(
   entity: AdminEntity,
   declared: readonly AdminOperation[] | undefined,
 ): readonly AdminOperation[] {
   const isView = entity.$viewQuery !== undefined && entity.$viewQuery !== null;
-  if (!isView) return declared ?? ADMIN_OPERATIONS;
+  const reason = entity.$readOnly ?? null;
+  if (!isView && reason === null) return declared ?? ADMIN_OPERATIONS;
   if (declared === undefined) return VIEW_OPERATIONS;
   const writes = declared.filter((operation) => !READS.has(operation));
-  if (writes.length > 0) throw new AdminViewWriteError({ entity: entity.$name, writes });
+  if (writes.length > 0) {
+    throw isView
+      ? new AdminViewWriteError({ entity: entity.$name, writes })
+      : new AdminReadOnlyWriteError({ entity: entity.$name, reason: reason ?? '', writes });
+  }
   return declared;
 }