@zeyolabs/kit 2026.11.7 → 2026.11.9

package/eslint-config.js

@@ -113,3 +113,71 @@ export const drizzleRules = {
 		'drizzle/enforce-update-with-where': ['error', { drizzleObjectName }],
 	},
 };
+
+/**
+ * Layer boundaries (see `standards/codex`): edges (remote functions, endpoints, hooks) reach the db
+ * only through managers; services never import managers; clients and libraries import nothing
+ * above them. Files are matched by name, so features keep `manager.server.ts`,
+ * `service.server.ts` and `client.server.ts` (or a `clients/` folder) and libraries live in `utils/`.
+ *
+ * - Starts as a warning so existing code can migrate; pass `severity: 'error'` once it is clean.
+ * - A file belongs to the first group it matches, in the order edge, service, client, library, so
+ *   `utils/clients/x.ts` is a client and gets only the client rules.
+ * - Flat config does not merge `no-restricted-imports` across entries. Put these rules LAST, and
+ *   pass your own restricted-import patterns as `extraPatterns` (added to every group).
+ * - Matching is by import specifier, so a barrel re-export bypasses it. An app with another layout
+ *   (e.g. `services/*.ts`) passes its own `globs` (which files are which layer) and `imports`
+ *   (which specifiers each layer is imported by). A green lint is not proof the boundaries hold.
+ * @param {{
+ *   severity?: 'error' | 'warn',
+ *   globs?: { client?: string[], edge?: string[], library?: string[], service?: string[] },
+ *   imports?: { client?: string[], manager?: string[], service?: string[] },
+ *   extraPatterns?: { group: string[], message?: string }[],
+ * }} [options]
+ */
+export function layerBoundaryRules(options = {}) {
+	const severity = options.severity ?? 'warn';
+	const extra = options.extraPatterns ?? [];
+	const globs = {
+		client: ['**/client.server.ts', '**/clients/**/*.ts'],
+		edge: ['**/*.remote.ts', '**/+server.ts', '**/+page.server.ts', '**/hooks.server.ts'],
+		library: ['**/utils/**/*.ts'],
+		service: ['**/service.server.ts'],
+		...options.globs,
+	};
+	const imports = {
+		client: ['**/client.server', '**/client.server.ts', '**/clients/**'],
+		manager: ['**/manager.server', '**/manager.server.ts'],
+		service: ['**/service.server', '**/service.server.ts'],
+		...options.imports,
+	};
+	const forbid = (group, message) => ({ group, message });
+	// First match wins: each group ignores the files of the groups before it.
+	const groups = [
+		[globs.edge, [forbid(imports.service, 'Edges call managers, not services (layer boundary).')]],
+		[
+			globs.service,
+			[forbid(imports.manager, 'Services must not import managers (layer boundary).')],
+		],
+		[
+			globs.client,
+			[
+				forbid(imports.manager, 'Clients must not import managers (layer boundary).'),
+				forbid(imports.service, 'Clients must not import services (layer boundary).'),
+			],
+		],
+		[
+			globs.library,
+			[
+				forbid(imports.manager, 'Libraries must not import managers (layer boundary).'),
+				forbid(imports.service, 'Libraries must not import services (layer boundary).'),
+				forbid(imports.client, 'Libraries must not import clients (layer boundary).'),
+			],
+		],
+	];
+	return groups.map(([files, patterns], index) => ({
+		files,
+		ignores: groups.slice(0, index).flatMap(([earlier]) => earlier),
+		rules: { 'no-restricted-imports': [severity, { patterns: [...patterns, ...extra] }] },
+	}));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zeyolabs/kit",
-	"version": "2026.11.7",
+	"version": "2026.11.9",
 	"description": "Shared SvelteKit-on-Cloudflare server toolkit: remote-function wrappers, passwordless auth (magic link + passkeys), email over a send_email binding or SMTP, Cloudflare context, monitoring, storage clients, utils and the ESLint config.",
 	"type": "module",
 	"repository": {

package/server/layers.ts

@@ -0,0 +1,53 @@
+import { waitUntil } from '../cloudflare/wait-until';
+
+// Shared shapes for the four layers every app is built from: libraries (static functions), clients
+// (talk to the outside world), services (talk to the db) and managers (permission, service call,
+// events). These are types and tiny helpers only: no base classes, so apps keep plain constructors.
+
+/**
+ * Who a service acts for. A service is built as `new XService(ctx, db)` and every query it runs is
+ * scoped by `ctx.accountId`; `memberId` and `kind` identify the actor for audit and events.
+ */
+export type ServiceCtx<Kind extends string = string> = {
+	accountId: number;
+	kind: Kind;
+	memberId: number;
+};
+
+/** What a service mutation returns: the result for the caller plus the events it caused. */
+export type Mutation<T, E> = { events: E[]; result: T };
+
+/** Builds a `Mutation`. `events` defaults to none. */
+export function mutation<T, E>(result: T, events: E[] = []): Mutation<T, E> {
+	return { events, result };
+}
+
+/**
+ * Where a manager sends the events a service returned (a realtime hub, a queue, a log). `publish`
+ * never blocks the caller and never throws: a failed publish must not fail the mutation that was
+ * already committed.
+ */
+export type EventPublisher<E> = { publish(events: E[]): void };
+
+/**
+ * An `EventPublisher` that hands `send` the events in the background (`waitUntil` in the Workers
+ * runtime, fire-and-forget elsewhere) and swallows its errors, passing them to `onError` if given.
+ */
+export function backgroundPublisher<E>(
+	send: (events: E[]) => Promise<unknown>,
+	onError?: (error: unknown) => void
+): EventPublisher<E> {
+	return {
+		publish(events) {
+			if (events.length === 0) return;
+			const run = (async () => {
+				try {
+					await send(events);
+				} catch (error) {
+					onError?.(error);
+				}
+			})();
+			void waitUntil(run);
+		},
+	};
+}

package/server/manager.ts

@@ -0,0 +1,29 @@
+import type { Membership } from '../auth/accounts/accounts';
+
+import { Accounts } from '../auth/accounts/accounts';
+import { Error403 } from '../utils/errors';
+
+// The manager gate. A manager is permission check, then a service call, then events. Each edge (a
+// SvelteKit hook, an MCP session, a Worker) resolves the principal its own way and passes the
+// membership in, so managers need no request and are testable without one.
+
+/** Throws a 403 unless `membership` grants `permission`. A missing membership fails closed. */
+export function requirePermission(membership: Membership | null, permission: string): Membership {
+	if (!membership || !Accounts.can(membership, permission)) {
+		throw Error403('You do not have permission to do that');
+	}
+	return membership;
+}
+
+/**
+ * Runs `fn` with the principal (membership now non-null), or throws a 403 before `fn` is called.
+ * Anything else the edge put on the principal (member id, actor kind, account id) comes through.
+ */
+export async function withPermission<P extends { membership: Membership | null }, T>(
+	principal: P,
+	permission: string,
+	fn: (principal: P & { membership: Membership }) => Promise<T> | T
+): Promise<T> {
+	const membership = requirePermission(principal.membership, permission);
+	return await fn({ ...principal, membership });
+}