@ultimat3/admin 30.1.0 → 30.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/admin",
-  "version": "30.1.0",
+  "version": "30.3.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.1.0",
-    "@ultimat3/ai": "30.1.0",
-    "@ultimat3/cache": "30.1.0",
-    "@ultimat3/core": "30.1.0",
-    "@ultimat3/db": "30.1.0",
-    "@ultimat3/entity": "30.1.0",
-    "@ultimat3/http": "30.1.0",
-    "@ultimat3/i18n": "30.1.0",
-    "@ultimat3/jobs": "30.1.0",
-    "@ultimat3/mcp": "30.1.0",
-    "@ultimat3/money": "30.1.0",
-    "@ultimat3/policy": "30.1.0",
-    "@ultimat3/query": "30.1.0",
-    "@ultimat3/render": "30.1.0",
-    "@ultimat3/schema": "30.1.0",
-    "@ultimat3/ui": "30.1.0"
+    "@ultimat3/action": "30.3.0",
+    "@ultimat3/ai": "30.3.0",
+    "@ultimat3/cache": "30.3.0",
+    "@ultimat3/core": "30.3.0",
+    "@ultimat3/db": "30.3.0",
+    "@ultimat3/entity": "30.3.0",
+    "@ultimat3/http": "30.3.0",
+    "@ultimat3/i18n": "30.3.0",
+    "@ultimat3/jobs": "30.3.0",
+    "@ultimat3/mcp": "30.3.0",
+    "@ultimat3/money": "30.3.0",
+    "@ultimat3/policy": "30.3.0",
+    "@ultimat3/query": "30.3.0",
+    "@ultimat3/render": "30.3.0",
+    "@ultimat3/schema": "30.3.0",
+    "@ultimat3/ui": "30.3.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/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;
 }