@shivaedev/admin 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShivaeDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @shivaedev/admin
+
+Admin tooling starts with an explicit list of pages and the operations each page needs. This package collects native Effect contracts behind the administrator role, so every page operation shares the same boundary.
+
+## Declare the tools operators can use
+
+```ts
+const Jobs = adminPage({
+  id: "jobs",
+  route: { path: "/admin/jobs", title: "Jobs" },
+  contract: contract("admin.jobs", { queries: [Failed] }),
+});
+const Admin = adminRegistry(Jobs);
+```
+
+The page exposes `admin.jobs.failed` and the generated `admin.jobs.$changes` subscription. Both require `AuthenticatedAdmin`. A query-only contract has no command; an owner without the `admin` role remains forbidden.
+
+## Use native contracts and Layers
+
+Install `@shivaedev/admin` with `effect`. Declare each page's queries, commands and streams with `@shivaedev/effect-contract`, then pass its native contract to `adminPage`. The stable id identifies the page at server registration; route metadata belongs to the application's view. Author RPC namespaces in the contract name, such as `admin.jobs`.
+
+```ts
+import { Schema } from "effect";
+import { adminPage } from "@shivaedev/admin/page.ts";
+import { adminRegistry } from "@shivaedev/admin/registry.ts";
+import { contract } from "@shivaedev/effect-contract/contract.ts";
+import { query } from "@shivaedev/effect-contract/operation.ts";
+
+const Failed = query("failed", {
+  reads: () => [],
+  success: Schema.Array(Schema.String),
+});
+const Jobs = adminPage({
+  id: "jobs",
+  route: { path: "/admin/jobs", title: "Jobs" },
+  contract: contract("admin.jobs", { queries: [Failed] }),
+});
+const Admin = adminRegistry(Jobs);
+```
+
+`Jobs.contract` keeps the native `.declaration` and `.application.toLayer` APIs. `adminRegistry(...pages)` returns `pages` and a native `group`. Duplicate page ids, route paths and RPC tags, including generated subscriptions, fail when the registry is created.
+
+Register server handler Layers by page id:
+
+```ts
+import { Effect, Layer } from "effect";
+import { registerAdmin } from "@shivaedev/admin/server/registerAdmin.ts";
+import { authenticatedAdminLayer } from "@shivaedev/platform/server/rpc-server/roles.ts";
+
+const registration = registerAdmin(Admin, {
+  jobs: Jobs.contract.application.toLayer({
+    "admin.jobs.failed": () => Effect.succeed(["mail-42"]),
+  }),
+});
+const handlers = registration.handlers.pipe(
+  Layer.provideMerge(authenticatedAdminLayer(sessions)),
+);
+```
+
+Pass `registration.group` and `handlers` to the existing application's RPC host on `/rpc`, merging them with its other groups and Layers as needed. The Platform host supplies generated change handlers; registration requires the page's application handlers. Handler Layer errors and service requirements remain inferred. Missing or extra page ids fail at registration; TypeScript also checks each Layer provides the handlers for its page.
+
+Page declarations and the registry are browser-safe. Server registration lives under `/server`; views belong in the application. This package ships no UI components and adds no transport. The package's stories prove role enforcement through native in-process RPC, with an already resolved session as a precondition.

package/dist/page.d.ts

@@ -0,0 +1,30 @@
+import type { Rpc, RpcGroup } from "effect/rpc";
+import type { Contract } from "@shivaedev/effect-contract/contract.ts";
+import type { CommandShape, QueryShape, StreamShape } from "@shivaedev/effect-contract/operation.ts";
+import { AuthenticatedAdmin } from "@shivaedev/platform/rpc/middleware.ts";
+export interface AdminRoute {
+    readonly path: string;
+    readonly title: string;
+}
+declare const AdminPageTypeId: unique symbol;
+export interface AdminPage {
+    readonly contract: RpcGroup.Any & {
+        readonly application: RpcGroup.Any;
+        readonly requests: ReadonlyMap<string, Rpc.Any>;
+    };
+    readonly id: string;
+    readonly route: AdminRoute;
+    readonly [AdminPageTypeId]: true;
+}
+export declare function adminPage<const TId extends string, const TName extends string, const TQueries extends readonly QueryShape[], const TCommands extends readonly CommandShape[], TRpcs extends Rpc.Any, const TStreams extends readonly StreamShape[]>(page: {
+    readonly id: TId;
+    readonly route: AdminRoute;
+    readonly contract: Contract<TName, TQueries, TCommands, TRpcs, TStreams>;
+}): {
+    id: TId;
+    route: AdminRoute;
+    [AdminPageTypeId]: true;
+    contract: Contract<TName, TQueries, TCommands, Rpc.AddMiddleware<TRpcs, typeof AuthenticatedAdmin>, TStreams, undefined>;
+};
+export {};
+//# sourceMappingURL=page.d.ts.map

package/dist/page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../src/page.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wCAAwC,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AACrG,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAE3E,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,QAAA,MAAM,eAAe,eAAsC,CAAC;AAE5D,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,GAAG;QACjC,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,GAAG,CAAC;QACnC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;KAChD,CAAC;IACF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,CAAC,eAAe,CAAC,EAAE,IAAI,CAAC;CACjC;AAED,wBAAgB,SAAS,CACxB,KAAK,CAAC,GAAG,SAAS,MAAM,EACxB,KAAK,CAAC,KAAK,SAAS,MAAM,EAC1B,KAAK,CAAC,QAAQ,SAAS,SAAS,UAAU,EAAE,EAC5C,KAAK,CAAC,SAAS,SAAS,SAAS,YAAY,EAAE,EAC/C,KAAK,SAAS,GAAG,CAAC,GAAG,EACrB,KAAK,CAAC,QAAQ,SAAS,SAAS,WAAW,EAAE,EAC5C,IAAI,EAAE;IAAE,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAA;CAAE;QAA3G,GAAG;WAAkB,UAAU;;;EAErD"}

package/dist/page.js

@@ -0,0 +1,6 @@
+import { AuthenticatedAdmin } from "@shivaedev/platform/rpc/middleware.ts";
+const AdminPageTypeId = Symbol.for("@shivaedev/admin/Page");
+export function adminPage(page) {
+    return { ...page, [AdminPageTypeId]: true, contract: page.contract.middleware(AuthenticatedAdmin) };
+}
+//# sourceMappingURL=page.js.map

package/dist/page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.js","sourceRoot":"","sources":["../src/page.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAO3E,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAY5D,MAAM,UAAU,SAAS,CAOvB,IAAgI;IACjI,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC,eAAe,CAAC,EAAE,IAAa,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,kBAAkB,CAAC,EAAE,CAAC;AAC9G,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,8 @@
+import { RpcGroup } from "effect/rpc";
+import type { AdminPage } from "./page.ts";
+export interface AdminRegistry<TPages extends readonly AdminPage[]> {
+    readonly group: RpcGroup.RpcGroup<RpcGroup.Rpcs<TPages[number]["contract"]>>;
+    readonly pages: TPages;
+}
+export declare function adminRegistry<const TPages extends readonly AdminPage[]>(...pages: TPages): AdminRegistry<TPages>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,MAAM,WAAW,aAAa,CAAC,MAAM,SAAS,SAAS,SAAS,EAAE;IACjE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAC7E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,aAAa,CAAC,KAAK,CAAC,MAAM,SAAS,SAAS,SAAS,EAAE,EAAE,GAAG,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAkBhH"}

package/dist/registry.js

@@ -0,0 +1,21 @@
+import { RpcGroup } from "effect/rpc";
+export function adminRegistry(...pages) {
+    const ids = new Set();
+    const paths = new Set();
+    const tags = new Set();
+    function unique(seen, value, kind) {
+        if (seen.has(value)) {
+            throw new Error(`Duplicate admin ${kind}: ${value}`);
+        }
+        seen.add(value);
+    }
+    for (const page of pages) {
+        unique(ids, page.id, "page id");
+        unique(paths, page.route.path, "path");
+        for (const tag of page.contract.requests.keys()) {
+            unique(tags, tag, "RPC tag");
+        }
+    }
+    return { group: RpcGroup.make().merge(...pages.map((page) => page.contract)), pages };
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAQtC,MAAM,UAAU,aAAa,CAA4C,GAAG,KAAa;IACxF,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,SAAS,MAAM,CAAC,IAAiB,EAAE,KAAa,EAAE,IAAY;QAC7D,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC;QACtD,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACjB,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;QAChC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACvC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;YACjD,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;QAC9B,CAAC;IACF,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;AACvF,CAAC"}

package/dist/server/registerAdmin.d.ts

@@ -0,0 +1,14 @@
+import { Layer } from "effect";
+import type { Rpc, RpcGroup } from "effect/rpc";
+import type { AdminPage } from "#page.ts";
+import type { AdminRegistry } from "#registry.ts";
+type HandlerLayers<TPages extends readonly AdminPage[]> = {
+    readonly [TPage in TPages[number] as TPage["id"]]: Layer.Layer<Rpc.ToHandler<RpcGroup.Rpcs<TPage["contract"]["application"]>>, unknown, unknown>;
+};
+type RegisteredLayers<THandlers> = Extract<THandlers[keyof THandlers], Layer.Any>;
+export declare function registerAdmin<const TPages extends readonly AdminPage[], THandlers extends HandlerLayers<TPages>>(registry: AdminRegistry<TPages>, handlers: THandlers & Record<Exclude<keyof THandlers, TPages[number]["id"]>, never>): {
+    readonly group: AdminRegistry<TPages>["group"];
+    readonly handlers: Layer.Layer<Layer.Success<RegisteredLayers<THandlers>>, Layer.Error<RegisteredLayers<THandlers>>, Layer.Services<RegisteredLayers<THandlers>>>;
+};
+export {};
+//# sourceMappingURL=registerAdmin.d.ts.map

package/dist/server/registerAdmin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registerAdmin.d.ts","sourceRoot":"","sources":["../../src/server/registerAdmin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAC/B,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,KAAK,aAAa,CAAC,MAAM,SAAS,SAAS,SAAS,EAAE,IAAI;IACzD,QAAQ,EAAE,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC;CAChJ,CAAC;AAEF,KAAK,gBAAgB,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;AAElF,wBAAgB,aAAa,CAAC,KAAK,CAAC,MAAM,SAAS,SAAS,SAAS,EAAE,EAAE,SAAS,SAAS,aAAa,CAAC,MAAM,CAAC,EAC/G,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,EAC/B,QAAQ,EAAE,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,GACjF;IACF,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC;IAC/C,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAC7B,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC,EAC1C,KAAK,CAAC,KAAK,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC,EACxC,KAAK,CAAC,QAAQ,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAC3C,CAAC;CACF,CAAC"}

package/dist/server/registerAdmin.js

@@ -0,0 +1,16 @@
+import { Layer } from "effect";
+export function registerAdmin(registry, handlers) {
+    const ids = new Set(registry.pages.map((page) => page.id));
+    for (const id of ids) {
+        if (!Object.hasOwn(handlers, id)) {
+            throw new Error(`Missing admin handlers: ${id}`);
+        }
+    }
+    for (const id of Object.keys(handlers)) {
+        if (!ids.has(id)) {
+            throw new Error(`Unregistered admin handlers: ${id}`);
+        }
+    }
+    return { group: registry.group, handlers: Layer.mergeAll(Layer.empty, ...Object.values(handlers)) };
+}
+//# sourceMappingURL=registerAdmin.js.map

package/dist/server/registerAdmin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registerAdmin.js","sourceRoot":"","sources":["../../src/server/registerAdmin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAsB/B,MAAM,UAAU,aAAa,CAC5B,QAA6C,EAC7C,QAAwE;IAExE,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3D,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,2BAA2B,EAAE,EAAE,CAAC,CAAC;QAClD,CAAC;IACF,CAAC;IACD,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,gCAAgC,EAAE,EAAE,CAAC,CAAC;QACvD,CAAC;IACF,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;AACrG,CAAC"}

package/package.json

@@ -1,11 +1,69 @@
 {
   "name": "@shivaedev/admin",
-  "version": "0.0.0",
-  "description": "Placeholder for @shivaedev/admin. The first real release follows.",
-  "license": "MIT",
+  "version": "0.1.0",
+  "description": "Explicit admin page contracts and a protected native Effect RPC registry",
+  "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/admin#readme",
+  "bugs": {
+    "url": "https://github.com/ShivaeDev/platform/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShivaeDev/platform.git",
     "directory": "packages/admin"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "imports": {
+    "#test/*": "./src/test-support/*",
+    "#*.ts": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "exports": {
+    "./*.ts": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/test-support",
+    "README.md"
+  ],
+  "dependencies": {
+    "@shivaedev/effect-contract": "0.12.0",
+    "@shivaedev/platform": "0.28.0"
+  },
+  "devDependencies": {
+    "@shivaedev/quality": "0.38.0",
+    "@shivaedev/test-story": "0.19.0",
+    "@types/node": "24.19.2",
+    "effect": "4.0.5",
+    "typescript": "7.0.2",
+    "vitest": "5.0.5"
+  },
+  "peerDependencies": {
+    "effect": "4.0.5"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "node --eval \"import('node:fs').then(({ rmSync }) => rmSync('dist', { force: true, recursive: true }))\" && tsc --project tsconfig.build.json",
+    "ready": "pnpm typecheck && pnpm test && pnpm build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
 }

package/src/page.ts

@@ -0,0 +1,32 @@
+import type { Rpc, RpcGroup } from "effect/rpc";
+import type { Contract } from "@shivaedev/effect-contract/contract.ts";
+import type { CommandShape, QueryShape, StreamShape } from "@shivaedev/effect-contract/operation.ts";
+import { AuthenticatedAdmin } from "@shivaedev/platform/rpc/middleware.ts";
+
+export interface AdminRoute {
+	readonly path: string;
+	readonly title: string;
+}
+
+const AdminPageTypeId = Symbol.for("@shivaedev/admin/Page");
+
+export interface AdminPage {
+	readonly contract: RpcGroup.Any & {
+		readonly application: RpcGroup.Any;
+		readonly requests: ReadonlyMap<string, Rpc.Any>;
+	};
+	readonly id: string;
+	readonly route: AdminRoute;
+	readonly [AdminPageTypeId]: true;
+}
+
+export function adminPage<
+	const TId extends string,
+	const TName extends string,
+	const TQueries extends readonly QueryShape[],
+	const TCommands extends readonly CommandShape[],
+	TRpcs extends Rpc.Any,
+	const TStreams extends readonly StreamShape[],
+>(page: { readonly id: TId; readonly route: AdminRoute; readonly contract: Contract<TName, TQueries, TCommands, TRpcs, TStreams> }) {
+	return { ...page, [AdminPageTypeId]: true as const, contract: page.contract.middleware(AuthenticatedAdmin) };
+}

package/src/registry.ts

@@ -0,0 +1,27 @@
+import { RpcGroup } from "effect/rpc";
+import type { AdminPage } from "./page.ts";
+
+export interface AdminRegistry<TPages extends readonly AdminPage[]> {
+	readonly group: RpcGroup.RpcGroup<RpcGroup.Rpcs<TPages[number]["contract"]>>;
+	readonly pages: TPages;
+}
+
+export function adminRegistry<const TPages extends readonly AdminPage[]>(...pages: TPages): AdminRegistry<TPages> {
+	const ids = new Set<string>();
+	const paths = new Set<string>();
+	const tags = new Set<string>();
+	function unique(seen: Set<string>, value: string, kind: string) {
+		if (seen.has(value)) {
+			throw new Error(`Duplicate admin ${kind}: ${value}`);
+		}
+		seen.add(value);
+	}
+	for (const page of pages) {
+		unique(ids, page.id, "page id");
+		unique(paths, page.route.path, "path");
+		for (const tag of page.contract.requests.keys()) {
+			unique(tags, tag, "RPC tag");
+		}
+	}
+	return { group: RpcGroup.make().merge(...pages.map((page) => page.contract)), pages };
+}

package/src/server/registerAdmin.ts

@@ -0,0 +1,39 @@
+import { Layer } from "effect";
+import type { Rpc, RpcGroup } from "effect/rpc";
+import type { AdminPage } from "#page.ts";
+import type { AdminRegistry } from "#registry.ts";
+
+type HandlerLayers<TPages extends readonly AdminPage[]> = {
+	readonly [TPage in TPages[number] as TPage["id"]]: Layer.Layer<Rpc.ToHandler<RpcGroup.Rpcs<TPage["contract"]["application"]>>, unknown, unknown>;
+};
+
+type RegisteredLayers<THandlers> = Extract<THandlers[keyof THandlers], Layer.Any>;
+
+export function registerAdmin<const TPages extends readonly AdminPage[], THandlers extends HandlerLayers<TPages>>(
+	registry: AdminRegistry<TPages>,
+	handlers: THandlers & Record<Exclude<keyof THandlers, TPages[number]["id"]>, never>,
+): {
+	readonly group: AdminRegistry<TPages>["group"];
+	readonly handlers: Layer.Layer<
+		Layer.Success<RegisteredLayers<THandlers>>,
+		Layer.Error<RegisteredLayers<THandlers>>,
+		Layer.Services<RegisteredLayers<THandlers>>
+	>;
+};
+export function registerAdmin(
+	registry: AdminRegistry<readonly AdminPage[]>,
+	handlers: Readonly<Record<string, Layer.Layer<never, unknown, unknown>>>,
+) {
+	const ids = new Set(registry.pages.map((page) => page.id));
+	for (const id of ids) {
+		if (!Object.hasOwn(handlers, id)) {
+			throw new Error(`Missing admin handlers: ${id}`);
+		}
+	}
+	for (const id of Object.keys(handlers)) {
+		if (!ids.has(id)) {
+			throw new Error(`Unregistered admin handlers: ${id}`);
+		}
+	}
+	return { group: registry.group, handlers: Layer.mergeAll(Layer.empty, ...Object.values(handlers)) };
+}