@protobase/server 0.4.1 → 0.5.0

package/dist/admin-options.d.ts

@@ -0,0 +1,35 @@
+import { AuditQueue, PipelineHook, ScanGuardMode } from "./types.js";
+import { AssistantOptions } from "./assistant/assistant-settings.js";
+import { RuntimeOptions } from "./runtime/runtime-settings.js";
+import { ResolveOptions } from "@protobase/schema";
+//#region src/admin-options.d.ts
+export type AdminOptions = {
+  /** Default `/api/v1`. */
+  basePath?: string;
+  /** Applied to every request's transaction with SET LOCAL. Default 15000. */
+  statementTimeoutMs?: number;
+  /** List shapes that would sequentially scan a table of more than `seqScanRows` rows (default 10000). Default mode `reject`. */
+  scanGuard?: {
+    mode?: ScanGuardMode;
+    seqScanRows?: number;
+  };
+  /** Runs inside the write transaction after each create, update and delete. */
+  writeHooks?: PipelineHook[];
+  /** The project's roles (from `defineRoles`): an operation without an access rule needs the matching capability. */
+  roles?: ResolveOptions['roles'];
+  /** What an operation without a rule does; overrides the capability check. Without `roles` the default is allow. */
+  defaultAccess?: ResolveOptions['defaultAccess'];
+  /** Whether list items carry their `permissions` (update, delete): true by default, or `{ except: [...] }` for resources that opt out. */
+  rowPermissions?: boolean | {
+    except: string[];
+  };
+  /** Receives an event for every reveal of a sensitive field. Default: printed to the console, nothing kept. */
+  audit?: AuditQueue;
+  /** Called with every error the API turns into a 500, so the host can report it. */
+  onUnhandledError?: (error: unknown) => void;
+  /** The assistant in the admin app's dock: a backend elsewhere or the built-in one (see `AssistantOptions`); `false` turns it off. */
+  assistant?: AssistantOptions | false;
+  /** The runtime updates endpoint behind the top bar's update button (see `RuntimeOptions`); `false` turns it off. */
+  runtime?: RuntimeOptions | false;
+};
+//#endregion

package/dist/aggregate-service.js

@@ -1,8 +1,8 @@
 import { badRequest } from "./problem.js";
+import { columnId, filterCondition, scopeConditions, tableId, whereClause } from "./sql-parts.js";
 import { checkedFilter } from "./filter-input.js";
 import { readScope, requestAccess, requireOperation } from "./request-access.js";
 import { readTransaction } from "./transactions.js";
-import { columnId, filterCondition, scopeConditions, tableId, whereClause } from "./sql-parts.js";
 import { parseParams } from "./params.js";
 import { facetCounts, histogram, series } from "@protobase/query";
 import { sql } from "kysely";

package/dist/assistant/assistant-settings.d.ts

@@ -1,16 +1,12 @@
+import { ModelSettings } from "./chat-completions.js";
+import { AssistantTool } from "./tools.js";
 //#region src/assistant/assistant-settings.d.ts
-/** An OpenAI-compatible chat completions endpoint for the built-in assistant. */
-export type ModelSettings = {
-  baseUrl: string;
-  apiKey: string;
-  model: string;
-  fetch?: typeof fetch;
-};
 /**
  * `url`: an assistant backend elsewhere, which the dock talks to instead of the built-in one.
  * `apiKey`, `model`, `baseUrl`: the built-in assistant, which answers questions about the app with a chat model.
  * `chats`: the directory the built-in assistant keeps conversations in, one file each.
  * Each falls back to its environment variable; `fetch` replaces the model endpoint, for tests.
+ * `tools`: the app's own tools, which the built-in assistant offers after its own; a backend elsewhere has its own.
  */
 export type AssistantOptions = {
   url?: string;
@@ -19,6 +15,7 @@ export type AssistantOptions = {
   baseUrl?: string;
   chats?: string;
   fetch?: typeof fetch;
+  tools?: AssistantTool[];
 };
 export type AssistantSettings = {
   kind: 'external';

package/dist/assistant/built-in-assistant.js

@@ -6,16 +6,31 @@ import { assistantProtocolRoutes } from "./protocol-routes.js";
 import { readOnlyQueryTool, readWriteQueryTool } from "./query-tools.js";
 import { runTurn } from "./turn.js";
 //#region src/assistant/built-in-assistant.ts
+const toolName = /^[A-Za-z0-9_-]{1,64}$/;
+/** The tools in order; a name a model endpoint refuses, or one taken twice, stops the server at startup. */
+const checkedTools = (tools) => {
+	const seen = /* @__PURE__ */ new Set();
+	for (const tool of tools) {
+		if (!toolName.test(tool.name)) throw new Error(`Assistant tool name "${tool.name}" must be 1 to 64 letters, digits, _ or -`);
+		if (seen.has(tool.name)) throw new Error(`Two assistant tools are named "${tool.name}"; give one of them another name`);
+		seen.add(tool.name);
+	}
+	return tools;
+};
 const pageContext = (page) => page && `The user is on the page ${page} of the app (/<resource> lists records, /<resource>/<key> shows one).`;
 /**
 * Protobase's own assistant: answers questions about the app, reads its data with read-only queries and proposes
-* changes the user approves, for callers with the `admin` or `ai` role. Made only of the exported building blocks and
-* its prompt, which describes what the caller may see of the app. Conversations are files in the `chats` directory.
-* On OpenRouter it caches the prompt and asks for little reasoning.
+* changes the user approves, with the app's own tools besides, for callers with the `admin` or `ai` role. Made only of
+* the exported building blocks and its prompt, which describes what the caller may see of the app. Conversations are
+* files in the `chats` directory. On OpenRouter it caches the prompt and asks for little reasoning.
 */
-const builtInAssistant = ({ model, chats, db, meta, authenticate, report }) => {
+const builtInAssistant = ({ model, chats, db, meta, authenticate, tools: appTools = [], records, report }) => {
 	const conversations = createConversations({ store: fileConversationStore(chats) });
-	const tools = [readOnlyQueryTool(db), readWriteQueryTool(db)];
+	const tools = checkedTools([
+		readOnlyQueryTool(db),
+		readWriteQueryTool(db),
+		...appTools
+	]);
 	const onOpenRouter = model.baseUrl === openRouterUrl;
 	return assistantProtocolRoutes({
 		authenticate,
@@ -30,6 +45,7 @@ const builtInAssistant = ({ model, chats, db, meta, authenticate, report }) => {
 				session,
 				system: appContext(body.resources, body.views),
 				tools,
+				...records && { records: records(session) },
 				report,
 				...page && { context: pageContext(page) },
 				...onOpenRouter && {

package/dist/assistant/chat-completions.d.ts

@@ -1,5 +1,11 @@
-import { ModelSettings } from "./assistant-settings.js";
 //#region src/assistant/chat-completions.d.ts
+/** An OpenAI-compatible chat completions endpoint for the built-in assistant. */
+export type ModelSettings = {
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+  fetch?: typeof fetch;
+};
 export type ToolCall = {
   id: string;
   type: 'function';

package/dist/assistant/conversations.d.ts

@@ -1,5 +1,5 @@
-import { Session } from "../types.js";
 import { ChatMessage } from "./chat-completions.js";
+import { Session } from "../types.js";
 import { ConversationStore } from "./conversation-store.js";
 import { AssistantEvent, AssistantState } from "@protobase/schema";
 //#region src/assistant/conversations.d.ts

package/dist/assistant/records.d.ts

@@ -0,0 +1,23 @@
+import { Row } from "../types.js";
+import "../deps.js";
+//#region src/assistant/records.d.ts
+/** A record's key: its URL text (`a,b` when composite), a scalar, or its parts. */
+export type RecordKeyInput = string | number | Array<string | number>;
+/** A record as the user may see it, with the ETag a later update can pass to fail when someone changed it since. */
+export type ToolRecord = {
+  record: Row;
+  etag: string;
+};
+/**
+ * The app's resources as the session's user: their access rules, tenant scope, validation and write hooks apply as
+ * in the REST API. A refusal or a missing record rejects with an `HttpProblem`, which a tool can turn into text.
+ */
+export type ToolRecords = {
+  get: (resource: string, key: RecordKeyInput) => Promise<ToolRecord>;
+  create: (resource: string, data: Row) => Promise<ToolRecord>;
+  /** With `etag`, fails with 412 when the record changed since it was read; without, it updates any version. */
+  update: (resource: string, key: RecordKeyInput, data: Row, options?: {
+    etag?: string;
+  }) => Promise<ToolRecord>;
+};
+//#endregion

package/dist/assistant/records.js

@@ -0,0 +1,53 @@
+import { notFound } from "../problem.js";
+import { decodeKeyText } from "../key.js";
+import { readRecord } from "../read-service.js";
+import { runWrite } from "../write-pipeline.js";
+import { encodeKey } from "@protobase/schema";
+//#region src/assistant/records.ts
+/** `ToolRecords` over the admin's resources for `session`. */
+const assistantRecords = (deps, session) => {
+	const entryOf = (resource) => {
+		const entry = deps.registry.find(resource);
+		if (!entry) throw notFound(`There is no resource "${resource}"`);
+		return entry;
+	};
+	const keyOf = (resource, key) => {
+		const entry = entryOf(resource);
+		return {
+			entry,
+			key: decodeKeyText(entry, Array.isArray(key) ? encodeKey(key) : String(key))
+		};
+	};
+	return {
+		get: async (resource, input) => {
+			const { entry, key } = keyOf(resource, input);
+			const { record, etag } = await readRecord(deps, entry, session, key);
+			return {
+				record,
+				etag
+			};
+		},
+		create: async (resource, data) => runWrite(deps, entryOf(resource), session, {
+			operation: "create",
+			body: data
+		}),
+		update: async (resource, input, data, { etag } = {}) => {
+			const { entry, key } = keyOf(resource, input);
+			return runWrite(deps, entry, session, {
+				operation: "update",
+				key,
+				body: data,
+				ifMatch: etag ?? "*"
+			});
+		}
+	};
+};
+const withoutAdmin = () => Promise.reject(/* @__PURE__ */ new Error("This assistant has no records: ToolContext.records works in the built-in assistant"));
+/** Records for a turn without an admin around it, such as in a backend of its own: every call fails. */
+const noRecords = {
+	get: withoutAdmin,
+	create: withoutAdmin,
+	update: withoutAdmin
+};
+//#endregion
+export { assistantRecords, noRecords };

package/dist/assistant/tools.d.ts

@@ -1,6 +1,7 @@
 import { Session } from "../types.js";
 import { Conversation } from "./conversations.js";
 import { ApprovalAnswer, ApprovalRequest } from "./approval.js";
+import { ToolRecords } from "./records.js";
 import { AssistantPart } from "@protobase/schema";
 //#region src/assistant/tools.d.ts
 export type ToolContext = {
@@ -10,6 +11,8 @@ export type ToolContext = {
   show: (part: AssistantPart) => void;
   /** Asks the user to approve with a card in that message (see `requestApproval`). */
   approve: (request: ApprovalRequest) => Promise<ApprovalAnswer>;
+  /** The app's resources as the session's user, through their access rules and write hooks (built-in assistant only). */
+  records: ToolRecords;
 };
 /**
  * A function the model may call during a turn. `parameters` is the JSON Schema of its arguments; `run` gets them

package/dist/assistant/turn.d.ts

@@ -1,7 +1,7 @@
-import { ModelSettings } from "./assistant-settings.js";
+import { ModelSettings, ReasoningEffort } from "./chat-completions.js";
 import { Session } from "../types.js";
-import { ReasoningEffort } from "./chat-completions.js";
 import { Conversation } from "./conversations.js";
+import { ToolRecords } from "./records.js";
 import { AssistantTool } from "./tools.js";
 //#region src/assistant/turn.d.ts
 export type TurnOptions = {
@@ -11,6 +11,8 @@ export type TurnOptions = {
   /** The system prompt. */
   system: string;
   tools?: AssistantTool[];
+  /** What tools get as `records`; without it, their calls fail. */
+  records?: ToolRecords;
   /** Model calls in one turn before it stops. Default 8. */
   maxSteps?: number;
   /** Gets errors other than the model endpoint's refusals, which the user only sees as a failure. */

package/dist/assistant/turn.js

@@ -1,6 +1,7 @@
 import { requestApproval } from "./approval.js";
 import { withCacheBreakpoints } from "./cache-breakpoints.js";
 import { ModelError, streamChatCompletion } from "./chat-completions.js";
+import { noRecords } from "./records.js";
 //#region src/assistant/turn.ts
 const toolResult = async (call, tools, context) => {
 	const tool = tools.find((entry) => entry.name === call.function.name);
@@ -39,7 +40,8 @@ const runTurn = async (options, text) => {
 		session,
 		conversation,
 		show,
-		approve: (request) => requestApproval(conversation, messageId, request)
+		approve: (request) => requestApproval(conversation, messageId, request),
+		records: options.records ?? noRecords
 	};
 	const specs = tools.map((tool) => ({
 		type: "function",

package/dist/assistant/widget.d.ts

@@ -0,0 +1,15 @@
+import { AssistantWidgetPart } from "@protobase/schema";
+//#region src/assistant/widget.d.ts
+/** The most a widget's props may take, as JSON in UTF-8: room for ids and settings, not for the state it shows. */
+export declare const maxWidgetPropsBytes = 2048;
+export type WidgetOptions = {
+  id?: string;
+  fallback?: AssistantWidgetPart['fallback'];
+};
+/**
+ * A widget part for `show`: the app's component `name` draws it with `props`, fetching what it shows itself. A name
+ * that is not PascalCase, or props that are not a JSON object of at most 2 KB, throw, so a tool cannot keep state in
+ * the chat by accident. Without an `id`, the part gets a new one; show a part with the same id again to replace it.
+ */
+export declare const widget: (name: string, props: Record<string, unknown>, options?: WidgetOptions) => AssistantWidgetPart;
+//#endregion

package/dist/assistant/widget.js

@@ -0,0 +1,32 @@
+//#region src/assistant/widget.ts
+const componentName = /^[A-Z][A-Za-z0-9]*$/;
+/** The most a widget's props may take, as JSON in UTF-8: room for ids and settings, not for the state it shows. */
+const maxWidgetPropsBytes = 2048;
+const isPlainObject = (value) => typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype;
+const isJson = (value) => {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (Array.isArray(value)) return value.every(isJson);
+	return isPlainObject(value) && Object.values(value).every(isJson);
+};
+/**
+* A widget part for `show`: the app's component `name` draws it with `props`, fetching what it shows itself. A name
+* that is not PascalCase, or props that are not a JSON object of at most 2 KB, throw, so a tool cannot keep state in
+* the chat by accident. Without an `id`, the part gets a new one; show a part with the same id again to replace it.
+*/
+const widget = (name, props, options = {}) => {
+	if (!componentName.test(name)) throw new Error(`Widget name "${name}" must be PascalCase, such as TaskProposal`);
+	if (!isPlainObject(props) || !isJson(props)) throw new Error(`The props of widget ${name} must be a JSON object`);
+	const bytes = new TextEncoder().encode(JSON.stringify(props)).length;
+	if (bytes > 2048) throw new Error(`The props of widget ${name} take ${bytes} bytes, more than ${maxWidgetPropsBytes}; pass ids and let the widget fetch the rest`);
+	const { id = crypto.randomUUID(), fallback } = options;
+	return {
+		type: "widget",
+		id,
+		name,
+		props,
+		...fallback && { fallback }
+	};
+};
+//#endregion
+export { maxWidgetPropsBytes, widget };

package/dist/batch/reorder.js

@@ -1,10 +1,10 @@
 import { badRequest } from "../problem.js";
-import { tenantScope } from "../tenant.js";
-import { requireOperation, targetFilter, writableFields } from "../request-access.js";
 import { columnId, keyConditions, scopeConditions, tableId, whereClause } from "../sql-parts.js";
 import { fetchRecord } from "../records.js";
-import { missing, shown } from "../write-shared.js";
+import { tenantScope } from "../tenant.js";
+import { requireOperation, targetFilter, writableFields } from "../request-access.js";
 import { validateBody } from "../validate-body.js";
+import { missing, shown } from "../write-shared.js";
 import { applyUpdate, planUpdate } from "../write-update.js";
 import { encodeKey } from "@protobase/schema";
 import { sql } from "kysely";

package/dist/create-admin.d.ts

@@ -1,6 +1,7 @@
 import { AdminAuth } from "./better-auth/create-auth.js";
 import { ResourceSource } from "./resource-source.js";
-import { AdminEnv, AdminOptions, Authenticator, PageSource, ViewSource } from "./types.js";
+import { AdminEnv, Authenticator, PageSource, ViewSource } from "./types.js";
+import { AdminOptions } from "./admin-options.js";
 import { Hono } from "hono";
 import { UserMenuSource } from "@protobase/schema";
 import { Db } from "@protobase/query";

package/dist/create-admin.js

@@ -1,5 +1,6 @@
 import { assistantSettings } from "./assistant/assistant-settings.js";
 import { createErrorHandler } from "./error-handler.js";
+import { assistantRecords } from "./assistant/records.js";
 import { builtInAssistant } from "./assistant/built-in-assistant.js";
 import { consoleAuditQueue } from "./audit/console-queue.js";
 import { authBasePath } from "./better-auth/create-auth.js";
@@ -84,14 +85,20 @@ const createAdmin = ({ resources, views = [], pages = [], userMenu, db, authenti
 		app.route(authBasePath, statusRoute(auth));
 		app.on(["GET", "POST"], `${authBasePath}/*`, (c) => auth.handler(c.req.raw));
 	}
-	if (assistant?.kind === "built-in") app.route(`${systemPath}/assistant`, builtInAssistant({
-		model: assistant.model,
-		chats: assistant.chats,
-		db,
-		meta,
-		authenticate,
-		report: options.onUnhandledError
-	}));
+	if (assistant?.kind === "built-in") {
+		const tools = options.assistant ? options.assistant.tools : void 0;
+		const records = (session) => assistantRecords(deps, session);
+		app.route(`${systemPath}/assistant`, builtInAssistant({
+			model: assistant.model,
+			chats: assistant.chats,
+			db,
+			meta,
+			authenticate,
+			tools,
+			records,
+			report: options.onUnhandledError
+		}));
+	}
 	app.route("/", batchRoute(deps, authenticate, meta));
 	app.route(basePath, api);
 	app.route(deps.systemPath || "/", system);

package/dist/deps.d.ts

@@ -0,0 +1,6 @@
+import "./types.js";
+import "./registry.js";
+import "./scan-guard.js";
+import { PageModel } from "@protobase/layout";
+import { ResolveOptions, ViewModel } from "@protobase/schema";
+import { Db } from "@protobase/query";

package/dist/index.d.ts

@@ -3,10 +3,18 @@ import { StaffSignIn } from "./better-auth/staff-log.js";
 import { OperatorProvider, readOperatorSettings } from "./better-auth/operator-provider.js";
 import { AdminAuth, CreateAuthOptions, UserCreatedHook, createAuth, normalizeRoles } from "./better-auth/create-auth.js";
 import { ResourceSource, configExports } from "./resource-source.js";
-import { AssistantOptions, AssistantSettings, ModelSettings, assistantRoles, assistantSettings, assistantVariables, seesAssistant } from "./assistant/assistant-settings.js";
+import { ChatMessage, ChatTextPart, Completion, CompletionOptions, ModelError, ModelSettings, ReasoningDetail, ReasoningEffort, ToolCall, ToolSpec, streamChatCompletion } from "./assistant/chat-completions.js";
+import { Admin, AuditEvent, AuditQueue, Authenticator, PipelineHook, ScanGuardMode, Session, TenantValue, User, ViewSource, WriteEvent, WriteOperation } from "./types.js";
+import { ConversationRecord, ConversationStore } from "./assistant/conversation-store.js";
+import { Conversation, ConversationsOptions, conversationKey, createConversations } from "./assistant/conversations.js";
+import { ApprovalAnswer, ApprovalRequest, requestApproval } from "./assistant/approval.js";
+import { RecordKeyInput, ToolRecord, ToolRecords } from "./assistant/records.js";
+import { AssistantTool, ToolContext, defineTool } from "./assistant/tools.js";
+import { AssistantOptions, AssistantSettings, assistantRoles, assistantSettings, assistantVariables, seesAssistant } from "./assistant/assistant-settings.js";
 import { RuntimeOptions, runtimeUrl, runtimeVariable, seesRuntime } from "./runtime/runtime-settings.js";
-import { Admin, AdminOptions, AuditEvent, AuditQueue, Authenticator, PipelineHook, ScanGuardMode, Session, TenantValue, User, ViewSource, WriteEvent, WriteOperation } from "./types.js";
+import { AdminOptions } from "./admin-options.js";
 import { CreateAdminInput, createAdmin } from "./create-admin.js";
+import { ProjectConfig, defineConfig, mergeConfig } from "./project-config.js";
 import { consoleAuditQueue } from "./audit/console-queue.js";
 import { JwtOptions, jwtAuthenticator } from "./auth/jwt.js";
 import { HttpProblem, badRequest, forbidden, notFound, unauthorized } from "./problem.js";
@@ -14,15 +22,11 @@ import { BetterAuthAuthenticatorOptions, betterAuthAuthenticator } from "./bette
 import { parseRoles } from "./better-auth/parse-roles.js";
 import { NewUser, StoredUser, createUser, deleteUser, hasUsers, listUsers, roleChoices, setUserBanned, setUserRole } from "./better-auth/users.js";
 import { IssueTokenOptions, issueToken, maxTokenTtlSeconds } from "./better-auth/tokens.js";
-import { ChatMessage, ChatTextPart, Completion, CompletionOptions, ModelError, ReasoningDetail, ReasoningEffort, ToolCall, ToolSpec, streamChatCompletion } from "./assistant/chat-completions.js";
-import { ConversationRecord, ConversationStore } from "./assistant/conversation-store.js";
-import { Conversation, ConversationsOptions, conversationKey, createConversations } from "./assistant/conversations.js";
 import { AssistantBackend, assistantProtocolRoutes } from "./assistant/protocol-routes.js";
 import { fileConversationStore } from "./assistant/file-conversation-store.js";
 import { withCacheBreakpoints } from "./assistant/cache-breakpoints.js";
-import { ApprovalAnswer, ApprovalRequest, requestApproval } from "./assistant/approval.js";
-import { AssistantTool, ToolContext, defineTool } from "./assistant/tools.js";
 import { TurnOptions, runTurn } from "./assistant/turn.js";
+import { WidgetOptions, maxWidgetPropsBytes, widget } from "./assistant/widget.js";
 import { QueryOptions, QueryResult, runReadOnlyQuery, runReadWriteQuery } from "./assistant/run-query.js";
 import { readOnlyQueryTool, readWriteQueryTool } from "./assistant/query-tools.js";
-export { type Admin, type AdminAuth, type AdminOptions, type ApprovalAnswer, type ApprovalRequest, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type Authenticator, type BetterAuthAuthenticatorOptions, type ChatMessage, type ChatTextPart, type Completion, type CompletionOptions, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CreateAdminInput, type CreateAuthOptions, HttpProblem, type IssueTokenOptions, type JwtOptions, ModelError, type ModelSettings, type NewUser, type OperatorProvider, type PipelineHook, type QueryOptions, type QueryResult, type ReasoningDetail, type ReasoningEffort, type ResourceSource, type RuntimeOptions, type ScanGuardMode, type Session, type SignInPolicy, type SignInRule, type StaffAccessRule, type StaffSignIn, type StoredUser, type TenantValue, type ToolCall, type ToolContext, type ToolSpec, type TurnOptions, type User, type UserCreatedHook, type ViewSource, type WriteEvent, type WriteOperation, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, badRequest, betterAuthAuthenticator, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createUser, defaultSignInPolicy, defineTool, deleteUser, fileConversationStore, forbidden, hasUsers, issueToken, jwtAuthenticator, listUsers, maxTokenTtlSeconds, normalizeRoles, notFound, parseRoles, readOnlyQueryTool, readOperatorSettings, readWriteQueryTool, requestApproval, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, seesAssistant, seesRuntime, setUserBanned, setUserRole, signInPolicyMethods, streamChatCompletion, unauthorized, withCacheBreakpoints };
+export { type Admin, type AdminAuth, type AdminOptions, type ApprovalAnswer, type ApprovalRequest, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type Authenticator, type BetterAuthAuthenticatorOptions, type ChatMessage, type ChatTextPart, type Completion, type CompletionOptions, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CreateAdminInput, type CreateAuthOptions, HttpProblem, type IssueTokenOptions, type JwtOptions, ModelError, type ModelSettings, type NewUser, type OperatorProvider, type PipelineHook, type ProjectConfig, type QueryOptions, type QueryResult, type ReasoningDetail, type ReasoningEffort, type RecordKeyInput, type ResourceSource, type RuntimeOptions, type ScanGuardMode, type Session, type SignInPolicy, type SignInRule, type StaffAccessRule, type StaffSignIn, type StoredUser, type TenantValue, type ToolCall, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TurnOptions, type User, type UserCreatedHook, type ViewSource, type WidgetOptions, type WriteEvent, type WriteOperation, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, badRequest, betterAuthAuthenticator, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createUser, defaultSignInPolicy, defineConfig, defineTool, deleteUser, fileConversationStore, forbidden, hasUsers, issueToken, jwtAuthenticator, listUsers, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, normalizeRoles, notFound, parseRoles, readOnlyQueryTool, readOperatorSettings, readWriteQueryTool, requestApproval, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, seesAssistant, seesRuntime, setUserBanned, setUserRole, signInPolicyMethods, streamChatCompletion, unauthorized, widget, withCacheBreakpoints };

package/dist/index.js

@@ -19,7 +19,9 @@ import { createUser, deleteUser, hasUsers, listUsers, roleChoices, setUserBanned
 import { runtimeUrl, runtimeVariable, seesRuntime } from "./runtime/runtime-settings.js";
 import { createAdmin } from "./create-admin.js";
 import { configExports } from "./resource-source.js";
+import { defineConfig, mergeConfig } from "./project-config.js";
 import { jwtAuthenticator } from "./auth/jwt.js";
 import { betterAuthAuthenticator } from "./better-auth/authenticator.js";
 import { issueToken, maxTokenTtlSeconds } from "./better-auth/tokens.js";
-export { HttpProblem, ModelError, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, badRequest, betterAuthAuthenticator, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createUser, defaultSignInPolicy, defineTool, deleteUser, fileConversationStore, forbidden, hasUsers, issueToken, jwtAuthenticator, listUsers, maxTokenTtlSeconds, normalizeRoles, notFound, parseRoles, readOnlyQueryTool, readOperatorSettings, readWriteQueryTool, requestApproval, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, seesAssistant, seesRuntime, setUserBanned, setUserRole, signInPolicyMethods, streamChatCompletion, unauthorized, withCacheBreakpoints };
+import { maxWidgetPropsBytes, widget } from "./assistant/widget.js";
+export { HttpProblem, ModelError, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, badRequest, betterAuthAuthenticator, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createUser, defaultSignInPolicy, defineConfig, defineTool, deleteUser, fileConversationStore, forbidden, hasUsers, issueToken, jwtAuthenticator, listUsers, maxTokenTtlSeconds, maxWidgetPropsBytes, mergeConfig, normalizeRoles, notFound, parseRoles, readOnlyQueryTool, readOperatorSettings, readWriteQueryTool, requestApproval, roleChoices, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, seesAssistant, seesRuntime, setUserBanned, setUserRole, signInPolicyMethods, streamChatCompletion, unauthorized, widget, withCacheBreakpoints };

package/dist/list-service.js

@@ -1,11 +1,11 @@
-import { checkedFilter, checkedSort } from "./filter-input.js";
-import { readScope, requestAccess, requireOperation } from "./request-access.js";
-import { readTransaction } from "./transactions.js";
 import { etagAlias } from "./sql-parts.js";
 import { etagOf } from "./etag.js";
 import { exposeRow, pickFields } from "./rows.js";
-import { deletedRows, listParams, pageSizeOf, parseParams, seekParams, selectedFields } from "./params.js";
+import { checkedFilter, checkedSort } from "./filter-input.js";
+import { readScope, requestAccess, requireOperation } from "./request-access.js";
 import { rowPermissions } from "./row-permissions.js";
+import { readTransaction } from "./transactions.js";
+import { deletedRows, listParams, pageSizeOf, parseParams, seekParams, selectedFields } from "./params.js";
 import { estimateCount, exactCount, listQuery, seekToPosition } from "@protobase/query";
 //#region src/list-service.ts
 /**

package/dist/project-config.d.ts

@@ -0,0 +1,28 @@
+import { AdminAuth } from "./better-auth/create-auth.js";
+import { Authenticator } from "./types.js";
+import { AdminOptions } from "./admin-options.js";
+import { Db } from "@protobase/query";
+//#region src/project-config.d.ts
+/** What `protobase.config.ts` may default-export. Everything is optional. */
+export type ProjectConfig = {
+  /** Names the config in errors, such as two configs defining the same tool; an extension should set it. */
+  name?: string;
+  /** Configs this one extends: merged in order before it (see `mergeConfig`). */
+  extends?: ProjectConfig[];
+  /** The config module, e.g. `import * as config from './config'`; default: ./config/index.ts and ./config/*\/ui.ts. */
+  config?: Record<string, unknown>;
+  db?: Db;
+  authenticate?: Authenticator;
+  /** A Better Auth instance; createAdmin mounts its routes under /api/auth. */
+  auth?: AdminAuth;
+  options?: AdminOptions;
+};
+/** Typed identity, for `export default defineConfig({ extends: [...], config, auth, ... })` in `protobase.config.ts`. */
+export declare const defineConfig: (config: ProjectConfig) => ProjectConfig;
+/**
+ * One config from several, each after the ones it `extends`, the last being the app's own. Named things are all kept:
+ * resources, views and pages of the config modules, assistant tools; one name defined by two configs is an error naming
+ * both. Write hooks run in the same order. Every other value is the last config's that sets it, so the app's own wins.
+ */
+export declare const mergeConfig: (...configs: ProjectConfig[]) => ProjectConfig;
+//#endregion

package/dist/project-config.js

@@ -0,0 +1,111 @@
+import { isPageDefinition } from "@protobase/layout";
+//#region src/project-config.ts
+/** Typed identity, for `export default defineConfig({ extends: [...], config, auth, ... })` in `protobase.config.ts`. */
+const defineConfig = (config) => config;
+const lastSet = (objects) => Object.fromEntries(objects.flatMap((object) => Object.entries(object)).filter(([, value]) => value !== void 0));
+const flatten = (config, label) => [...(config.extends ?? []).flatMap((parent, index) => flatten(parent, parent.name ?? `${label} extends[${index}]`)), {
+	config,
+	label
+}];
+const checkUnique = (kind, entries) => {
+	const seen = /* @__PURE__ */ new Map();
+	for (const { name, value, label } of entries) {
+		const first = seen.get(name);
+		if (first && first.value !== value) throw new Error(`${kind} "${name}" is defined twice, ${first.label === label ? `in ${label}` : `by ${first.label} and by ${label}`}; rename one of them`);
+		if (!first) seen.set(name, {
+			value,
+			label
+		});
+	}
+};
+const mergedModule = (named) => {
+	const withModule = named.filter(({ config }) => config.config);
+	if (withModule.length === 0) return void 0;
+	const exports = withModule.flatMap(({ config, label }) => Object.entries(config.config).map(([key, value]) => ({
+		key,
+		value,
+		label
+	})));
+	const values = exports.map((entry) => ({
+		...entry,
+		value: entry.value
+	}));
+	checkUnique("The resource", values.filter(({ value }) => typeof value?.recordSchema === "function" && typeof value.toModel === "function").map(({ value, label }) => ({
+		name: String(value.toModel().name),
+		value,
+		label
+	})));
+	checkUnique("The page", exports.filter(({ value }) => isPageDefinition(value)).map(({ value, label }) => ({
+		name: value.name,
+		value,
+		label
+	})));
+	const menus = values.filter(({ value }) => typeof value?.toUserMenuModel === "function");
+	if (new Set(menus.map(({ value }) => value)).size > 1) throw new Error(`Only one config may export a user menu; ${menus.map(({ label }) => label).join(" and ")} each do`);
+	const module = {};
+	const own = withModule.at(-1).label;
+	for (const { key, value, label } of exports) {
+		if (Object.values(module).includes(value)) continue;
+		module[label === own ? key : `${label}:${key}`] = value;
+	}
+	return module;
+};
+const mergedAssistant = (named) => {
+	const options = named.map(({ config, label }) => ({
+		assistant: config.options?.assistant,
+		label
+	})).filter(({ assistant }) => assistant !== void 0);
+	if (options.length === 0) return void 0;
+	if (options.at(-1).assistant === false) return false;
+	const after = options.slice(options.findLastIndex(({ assistant }) => assistant === false) + 1);
+	const tools = after.flatMap(({ assistant, label }) => (assistant.tools ?? []).map((tool) => ({
+		tool,
+		label
+	})));
+	checkUnique("The assistant tool", tools.map(({ tool, label }) => ({
+		name: tool.name,
+		value: tool,
+		label
+	})));
+	return {
+		...lastSet(after.map(({ assistant }) => assistant)),
+		...tools.length > 0 && { tools: tools.map(({ tool }) => tool) }
+	};
+};
+const mergedOptions = (named) => {
+	const all = named.flatMap(({ config }) => config.options ? [config.options] : []);
+	if (all.length === 0) return void 0;
+	const writeHooks = all.flatMap((options) => options.writeHooks ?? []);
+	const assistant = mergedAssistant(named);
+	return {
+		...lastSet(all),
+		...writeHooks.length > 0 && { writeHooks },
+		...assistant !== void 0 && { assistant }
+	};
+};
+/**
+* One config from several, each after the ones it `extends`, the last being the app's own. Named things are all kept:
+* resources, views and pages of the config modules, assistant tools; one name defined by two configs is an error naming
+* both. Write hooks run in the same order. Every other value is the last config's that sets it, so the app's own wins.
+*/
+const mergeConfig = (...configs) => {
+	const named = configs.flatMap((config, index) => flatten(config, config.name ?? `config ${index + 1}`));
+	const { db, authenticate, auth } = lastSet(named.map(({ config }) => ({
+		db: config.db,
+		authenticate: config.authenticate,
+		auth: config.auth
+	})));
+	const module = mergedModule(named);
+	const options = mergedOptions(named);
+	const name = configs.at(-1)?.name;
+	return {
+		...name && { name },
+		...module && { config: module },
+		...db && { db },
+		...authenticate && { authenticate },
+		...auth && { auth },
+		...options && { options }
+	};
+};
+//#endregion
+export { defineConfig, mergeConfig };

package/dist/read-service.js

@@ -1,10 +1,10 @@
 import { notFound } from "./problem.js";
-import { tenantScope } from "./tenant.js";
-import { recordDecision, requestAccess, requireOperation, targetFilter, visibleFields, writableFields } from "./request-access.js";
-import { readTransaction } from "./transactions.js";
 import { pickFields } from "./rows.js";
 import { fetchRecord } from "./records.js";
+import { tenantScope } from "./tenant.js";
+import { recordDecision, requestAccess, requireOperation, targetFilter, visibleFields, writableFields } from "./request-access.js";
 import { rowPermissions } from "./row-permissions.js";
+import { readTransaction } from "./transactions.js";
 //#region src/read-service.ts
 /** `edit` for fields the caller may change on this record, `read` for the rest (sensitive ones included); hidden fields are not listed at all. */
 const fieldModes = (access, canUpdate) => Object.fromEntries(Object.keys(access.readable.fields).map((name) => [name, canUpdate && writableFields(access, "update").includes(name) ? "edit" : "read"]));

package/dist/registry.d.ts

@@ -0,0 +1,2 @@
+import "./resource-source.js";
+import { ResourceModel } from "@protobase/schema";

package/dist/routes/record.js

@@ -1,11 +1,11 @@
 import { notFound } from "../problem.js";
+import { keyFromPath } from "../key.js";
 import { pickFields } from "../rows.js";
+import { readRecord } from "../read-service.js";
 import { runWrite } from "../write-pipeline.js";
-import { keyFromPath } from "../key.js";
 import { deletedRows, selectedFields } from "../params.js";
 import { returnPreference } from "./preferences.js";
 import { resolveTarget } from "./target.js";
-import { readRecord } from "../read-service.js";
 import { revealField } from "../reveal-service.js";
 import { Hono } from "hono";
 //#region src/routes/record.ts

package/dist/row-permissions.js

@@ -1,7 +1,7 @@
-import { tenantScope } from "./tenant.js";
-import { recordDecision } from "./request-access.js";
 import { aliasedColumn, columnId, scopeConditions, tableId, whereClause } from "./sql-parts.js";
 import { fetchRecord } from "./records.js";
+import { tenantScope } from "./tenant.js";
+import { recordDecision } from "./request-access.js";
 import { compileFilter } from "@protobase/query";
 import { sql } from "kysely";
 //#region src/row-permissions.ts

package/dist/scan-guard.d.ts

@@ -0,0 +1,4 @@
+import "./types.js";
+import "./registry.js";
+import { ResourceModel } from "@protobase/schema";
+import { Db } from "@protobase/query";

package/dist/types.d.ts

@@ -1,8 +1,6 @@
-import { AssistantOptions } from "./assistant/assistant-settings.js";
-import { RuntimeOptions } from "./runtime/runtime-settings.js";
 import { Hono } from "hono";
 import { PageModel } from "@protobase/layout";
-import { ResolveOptions, ResourceModel, ViewModel } from "@protobase/schema";
+import { ResourceModel, ViewModel } from "@protobase/schema";
 import { Db } from "@protobase/query";
 //#region src/types.d.ts
 export type TenantValue = string | number;
@@ -64,35 +62,6 @@ export type AuditQueue = {
   publish(event: AuditEvent): Promise<void>;
 };
 export type ScanGuardMode = 'reject' | 'warn' | 'off';
-export type AdminOptions = {
-  /** Default `/api/v1`. */
-  basePath?: string;
-  /** Applied to every request's transaction with SET LOCAL. Default 15000. */
-  statementTimeoutMs?: number;
-  /** List shapes that would sequentially scan a table of more than `seqScanRows` rows (default 10000). Default mode `reject`. */
-  scanGuard?: {
-    mode?: ScanGuardMode;
-    seqScanRows?: number;
-  };
-  /** Runs inside the write transaction after each create, update and delete. */
-  writeHooks?: PipelineHook[];
-  /** The project's roles (from `defineRoles`): an operation without an access rule needs the matching capability. */
-  roles?: ResolveOptions['roles'];
-  /** What an operation without a rule does; overrides the capability check. Without `roles` the default is allow. */
-  defaultAccess?: ResolveOptions['defaultAccess'];
-  /** Whether list items carry their `permissions` (update, delete): true by default, or `{ except: [...] }` for resources that opt out. */
-  rowPermissions?: boolean | {
-    except: string[];
-  };
-  /** Receives an event for every reveal of a sensitive field. Default: printed to the console, nothing kept. */
-  audit?: AuditQueue;
-  /** Called with every error the API turns into a 500, so the host can report it. */
-  onUnhandledError?: (error: unknown) => void;
-  /** The assistant in the admin app's dock: a backend elsewhere or the built-in one (see `AssistantOptions`); `false` turns it off. */
-  assistant?: AssistantOptions | false;
-  /** The runtime updates endpoint behind the top bar's update button (see `RuntimeOptions`); `false` turns it off. */
-  runtime?: RuntimeOptions | false;
-};
 export type ViewSource = {
   toModel(): ViewModel;
 };

package/dist/write-pipeline.js

@@ -1,10 +1,10 @@
 import { HttpProblem, badRequest } from "./problem.js";
+import { deleteRecord, fetchRecord, insertRecord, restoreRecord } from "./records.js";
 import { tenantScope } from "./tenant.js";
 import { requestAccess, requireOperation, targetFilter, writableFields } from "./request-access.js";
 import { writeTransaction } from "./transactions.js";
-import { deleteRecord, fetchRecord, insertRecord, restoreRecord } from "./records.js";
-import { assertWritten, checkPrecondition, decide, denied, firstKeyField, missing, notifier, shown } from "./write-shared.js";
 import { validateBody } from "./validate-body.js";
+import { assertWritten, checkPrecondition, decide, denied, firstKeyField, missing, notifier, shown } from "./write-shared.js";
 import { applyUpdate, planUpdate } from "./write-update.js";
 //#region src/write-pipeline.ts
 const withOwner = (access, values) => {

package/dist/write-shared.js

@@ -1,9 +1,9 @@
 import { forbidden, notFound, preconditionFailed, preconditionRequired } from "./problem.js";
-import { tenantScope } from "./tenant.js";
-import { andFilters, recordDecision } from "./request-access.js";
 import { ifMatchSatisfied } from "./etag.js";
 import { pickFields } from "./rows.js";
 import { fetchRecord } from "./records.js";
+import { tenantScope } from "./tenant.js";
+import { andFilters, recordDecision } from "./request-access.js";
 //#region src/write-shared.ts
 const missing = (entry) => notFound(`No ${entry.name} with this key`);
 const checkPrecondition = (current, ifMatch, required) => {

package/dist/write-update.js

@@ -1,8 +1,8 @@
+import { fetchRecord, updateRecord } from "./records.js";
 import { tenantScope } from "./tenant.js";
 import { targetFilter } from "./request-access.js";
-import { fetchRecord, updateRecord } from "./records.js";
-import { assertWritten, checkPrecondition, decide, denied, firstKeyField, missing, notifier } from "./write-shared.js";
 import { validateBody } from "./validate-body.js";
+import { assertWritten, checkPrecondition, decide, denied, firstKeyField, missing, notifier } from "./write-shared.js";
 //#region src/write-update.ts
 /**
 * Everything an update needs before it writes: the row (locked, inside the caller's tenant and row filters), the ETag

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -30,9 +30,9 @@
   },
   "dependencies": {
     "@better-auth/passkey": "^1.7.7",
-    "@protobase/layout": "0.4.1",
-    "@protobase/query": "0.4.1",
-    "@protobase/schema": "0.4.1",
+    "@protobase/layout": "0.5.0",
+    "@protobase/query": "0.5.0",
+    "@protobase/schema": "0.5.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@simplewebauthn/server": "^13.3.1",
     "better-auth": "^1.7.7",