@databricks/appkit 0.74.1 → 0.75.1

package/docs/api/appkit.md

@@ -63,6 +63,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [EvalResult](./docs/api/appkit/Interface.EvalResult.md)                                               | The outcome of running one eval.                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | [EvalRunSummary](./docs/api/appkit/Interface.EvalRunSummary.md)                                       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [EvalSummary](./docs/api/appkit/Interface.EvalSummary.md)                                             | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| [EvalWebServer](./docs/api/appkit/Interface.EvalWebServer.md)                                         | Auto-start config for the app under test, à la Playwright's `webServer`. When set in a root `evals.config.ts`, the CLI boots the app before running evals and tears it down after — so you don't have to start the server by hand.                                                                                                                                                                                                                            |
 | [FilePolicyUser](./docs/api/appkit/Interface.FilePolicyUser.md)                                       | Minimal user identity passed to the policy function.                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [FileResource](./docs/api/appkit/Interface.FileResource.md)                                           | Describes the file or directory being acted upon.                                                                                                                                                                                                                                                                                                                                                                                                             |
 | [FunctionTool](./docs/api/appkit/Interface.FunctionTool.md)                                           | -                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
@@ -197,7 +198,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [createLakebasePool](./docs/api/appkit/Function.createLakebasePool.md)                 | Create a Lakebase pool with appkit's logger integration. Telemetry automatically uses appkit's OpenTelemetry configuration via global registry.                                                                                                                                                                                                                                                            |
 | [createLakebasePoolManager](./docs/api/appkit/Function.createLakebasePoolManager.md)   | Create a pool manager that maintains per-key Lakebase connection pools.                                                                                                                                                                                                                                                                                                                                    |
 | [createWorkspaceClient](./docs/api/appkit/Function.createWorkspaceClient.md)           | Construct an AppKit workspace client.                                                                                                                                                                                                                                                                                                                                                                      |
-| [database](./docs/api/appkit/Function.database.md)                                     | Create a typed database plugin registration for a finalized schema.                                                                                                                                                                                                                                                                                                                                        |
+| [database](./docs/api/appkit/Function.database.md)                                     | Create the database plugin. Omit configuration to load `config/database/schema.ts`, or supply a typed schema override.                                                                                                                                                                                                                                                                                     |
 | [defineEval](./docs/api/appkit/Function.defineEval.md)                                 | Define an agent eval. Default-export the result from a `server/agents/<id>/evals/*.eval.ts` file.                                                                                                                                                                                                                                                                                                          |
 | [defineEvalConfig](./docs/api/appkit/Function.defineEvalConfig.md)                     | Define per-directory eval config. Default-export from `evals.config.ts`.                                                                                                                                                                                                                                                                                                                                   |
 | [defineManifest](./docs/api/appkit/Function.defineManifest.md)                         | Validates a raw manifest (typically a `manifest.json` import) against the canonical Zod schema and returns it as a strict [PluginManifest](./docs/api/appkit/Interface.PluginManifest.md).                                                                                                                                                                                                           |
@@ -210,6 +211,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [evalGlyph](./docs/api/appkit/Function.evalGlyph.md)                                   | Status glyph for a single eval result.                                                                                                                                                                                                                                                                                                                                                                     |
 | [executeFromRegistry](./docs/api/appkit/Function.executeFromRegistry.md)               | Validates tool-call arguments against the entry's schema and invokes its handler. On validation failure, returns an LLM-friendly error string (matching the behavior of `tool()`) rather than throwing, so the model can self-correct on its next turn.                                                                                                                                                    |
 | [extractServingEndpoints](./docs/api/appkit/Function.extractServingEndpoints.md)       | Extract serving endpoint config from a server file by AST-parsing it. Looks for `serving({ endpoints: { alias: { env: "..." }, ... } })` calls and extracts the endpoint alias names and their environment variable mappings.                                                                                                                                                                              |
+| [findRootEvalConfig](./docs/api/appkit/Function.findRootEvalConfig.md)                 | Path to the root `evals.config.ts` (from [defineEvalConfig](./docs/api/appkit/Function.defineEvalConfig.md)) at `<rootDir>/evals.config.ts`, or `undefined` when absent. The root config holds run-wide settings (`baseUrl`, `webServer`); it's distinct from the per-agent configs found by [discoverEvalConfigs](./docs/api/appkit/Function.discoverEvalConfigs.md).                         |
 | [findServerFile](./docs/api/appkit/Function.findServerFile.md)                         | Find the server entry file by checking candidate paths in order.                                                                                                                                                                                                                                                                                                                                           |
 | [fk](./docs/api/appkit/Function.fk.md)                                                 | Declare foreign-key to another column.                                                                                                                                                                                                                                                                                                                                                                     |
 | [formatEvalDetail](./docs/api/appkit/Function.formatEvalDetail.md)                     | Indented detail lines for a failing eval (error + failing assertions).                                                                                                                                                                                                                                                                                                                                     |
@@ -240,6 +242,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
 | [jsonb](./docs/api/appkit/Function.jsonb.md)                                           | -                                                                                                                                                                                                                                                                                                                                                                                                          |
 | [loadAgentFromFile](./docs/api/appkit/Function.loadAgentFromFile.md)                   | Loads a single markdown agent file and resolves its frontmatter against registered plugin toolkits + ambient tool library.                                                                                                                                                                                                                                                                                 |
 | [loadAgentsFromDir](./docs/api/appkit/Function.loadAgentsFromDir.md)                   | Scans a directory for one subdirectory per agent, each containing `agent.md` (frontmatter + body). Produces an `AgentDefinition` record keyed by agent id (folder name). Throws on frontmatter errors or unresolved references. Returns an empty map if the directory does not exist.                                                                                                                      |
+| [loadRootEvalConfig](./docs/api/appkit/Function.loadRootEvalConfig.md)                 | Load the root `evals.config.ts` under `rootDir` (the project root), or return `undefined` when there is none. This is the run-wide config carrying `baseUrl`/`webServer`; the CLI reads it to resolve options and manage the app-under-test lifecycle before calling [runEvalsInDir](./docs/api/appkit/Function.runEvalsInDir.md).                                                                   |
 | [matches](./docs/api/appkit/Function.matches.md)                                       | Passes when the value matches `pattern`.                                                                                                                                                                                                                                                                                                                                                                   |
 | [mcpServer](./docs/api/appkit/Function.mcpServer.md)                                   | Factory for declaring a custom MCP server tool.                                                                                                                                                                                                                                                                                                                                                            |
 | [normalizeHost](./docs/api/appkit/Function.normalizeHost.md)                           | Ensure the host has a scheme (Databricks env often lacks `https://`).                                                                                                                                                                                                                                                                                                                                      |

package/docs/plugins/database.md

@@ -4,7 +4,7 @@ Beta plugin
 
 This plugin is currently **beta**. APIs may change between minor releases. Import from `@databricks/appkit/beta`. See [Plugin Stability Tiers](./docs/plugins/stability.md).
 
-Declare a schema and use `database({ schema })` to get generated HTTP CRUD and a server-side database client. CRUD is enabled for every declared table by default. Use `api` to restrict the generated routes without disabling server-side access.
+Declare your tables in `config/database/schema.ts` and register `database()` to get generated HTTP CRUD and a server-side database client. CRUD is enabled for every declared table by default. Use `api` to restrict the generated routes without disabling server-side access.
 
 Shared application access
 
@@ -16,19 +16,30 @@ Restrict access to the app and grant its service principal only the database per
 
 Configure a Lakebase `postgres` resource and its connection environment variables as described in [Lakebase configuration](./docs/plugins/lakebase.md#environment-variables). The database tables must already exist and match the declared schema. This plugin checks connectivity during setup; it does not create or migrate tables.
 
+Apps scaffolded with the Database plugin selected include an empty `config/database/schema.ts`, so `database()` can start without requiring sample tables. Replace the empty declaration with your models when their PostgreSQL tables are ready.
+
+For local development, the PostgreSQL username is resolved from your Databricks credentials when `PGUSER` and `DATABRICKS_CLIENT_ID` are absent. An explicitly configured username takes precedence.
+
 ```ts
-import { createApp, server } from "@databricks/appkit";
-import { database, defineSchema, id, text } from "@databricks/appkit/beta";
+// config/database/schema.ts
+import { defineSchema, id, text } from "@databricks/appkit/beta";
 
-const schema = defineSchema((builder) => ({
+export const schema = defineSchema((builder) => ({
   notes: builder.table("notes", {
     id: id(),
     body: text().notNull(),
   }),
 }));
 
+```
+
+```ts
+// server/index.ts
+import { createApp, server } from "@databricks/appkit";
+import { database } from "@databricks/appkit/beta";
+
 const AppKit = await createApp({
-  plugins: [server(), database({ schema })],
+  plugins: [server(), database()],
 });
 
 ```
@@ -45,41 +56,59 @@ With the server plugin enabled, this registers:
 
 A table without a public primary key supports list and create only. `upsert` is available to server code but has no generated HTTP route.
 
+## Schema discovery and overrides[​](#schema-discovery-and-overrides "Direct link to Schema discovery and overrides")
+
+`database()` and `database({})` use the same defaults. During setup, the plugin loads the named `schema` export from `config/database/schema.ts`, relative to the application's working directory. The file must export a finalized `defineSchema()` result. Missing files, import failures, and invalid exports fail setup before the plugin creates a connection pool; they do not silently create an empty schema.
+
+Keep `config/database/schema.ts` and its local imports in your deployment. The plugin loads TypeScript through Jiti, so a plain Node production process does not need a separate TypeScript loader. The schema module should only declare tables, not connect to the database or start the app.
+
+For a different layout or a deployment that contains only a server bundle, import the schema explicitly and pass it to the plugin:
+
+```ts
+import { schema } from "../config/database/schema";
+
+database({ schema });
+
+```
+
+An explicit schema always takes precedence and skips file discovery. An invalid explicit schema fails setup instead of falling back to another file.
+
+Run `appkit generate-types` to generate the database registry. With that registry, configuration without an explicit schema still infers table names and hook payloads. An explicitly supplied schema also checks configuration keys against its own table names.
+
 ## Restrict the generated API[​](#restrict-the-generated-api "Direct link to Restrict the generated API")
 
 Omitting `api`, or setting it to `true` or `{}`, enables full CRUD. Restrictions are optional. There is no separate write opt-in.
 
 ```ts
 // No generated HTTP routes. The server-side client still works.
-database({ schema, api: false });
+database({ api: false });
 
 // Read-only routes for every table.
-database({ schema, api: { writes: false } });
+database({ api: { writes: false } });
 
 // Full CRUD for selected tables only.
-database({ schema, api: { tables: ["notes"] } });
+database({ api: { tables: ["notes"] } });
 
 // Allow reads, create, and update, but not delete.
 database({
-  schema,
   api: { writes: { operations: ["create", "update"] } },
 });
 
 // Read every table, but allow writes only to notes.
 database({
-  schema,
   api: { writes: { tables: ["notes"] } },
 });
 
 ```
 
-| Option                  | Default                      | Effect                                    |
-| ----------------------- | ---------------------------- | ----------------------------------------- |
-| `api`                   | `true`                       | `false` disables all generated routes     |
-| `api.tables`            | All declared tables          | Limits which tables have routes           |
-| `api.writes`            | `true`                       | `false` keeps only read routes            |
-| `api.writes.tables`     | All exposed tables           | Limits which exposed tables accept writes |
-| `api.writes.operations` | `create`, `update`, `delete` | Limits which writes are enabled           |
+| Option                  | Default                                     | Effect                                    |
+| ----------------------- | ------------------------------------------- | ----------------------------------------- |
+| `schema`                | Named export in `config/database/schema.ts` | Overrides automatic schema loading        |
+| `api`                   | `true`                                      | `false` disables all generated routes     |
+| `api.tables`            | All declared tables                         | Limits which tables have routes           |
+| `api.writes`            | `true`                                      | `false` keeps only read routes            |
+| `api.writes.tables`     | All exposed tables                          | Limits which exposed tables accept writes |
+| `api.writes.operations` | `create`, `update`, `delete`                | Limits which writes are enabled           |
 
 `api.tables: []` disables all generated routes. An empty write-table or write-operation list keeps reads and disables writes. Tables omitted from `api.tables` also cannot be included through relations on exposed tables. These restrictions apply to HTTP only, not to the server-side client or hooks.
 
@@ -114,7 +143,6 @@ A table can declare `beforeCreate`, `afterCreate`, `beforeUpdate`, `afterUpdate`
 import { DatabaseValidationError } from "@databricks/appkit";
 
 database({
-  schema,
   hooks: {
     notes: {
       beforeCreate(values) {

package/llms.txt

@@ -97,7 +97,7 @@ npx @databricks/appkit docs <query>
 - [Function: createLakebasePool()](./docs/api/appkit/Function.createLakebasePool.md): Create a Lakebase pool with appkit's logger integration.
 - [Function: createLakebasePoolManager()](./docs/api/appkit/Function.createLakebasePoolManager.md): Create a pool manager that maintains per-key Lakebase connection pools.
 - [Function: createWorkspaceClient()](./docs/api/appkit/Function.createWorkspaceClient.md): Construct an AppKit workspace client.
-- [Function: database()](./docs/api/appkit/Function.database.md): Create a typed database plugin registration for a finalized schema.
+- [Function: database()](./docs/api/appkit/Function.database.md): Call Signature
 - [Function: defineEval()](./docs/api/appkit/Function.defineEval.md): Define an agent eval. Default-export the result from a
 - [Function: defineEvalConfig()](./docs/api/appkit/Function.defineEvalConfig.md): Define per-directory eval config. Default-export from evals.config.ts.
 - [Function: defineManifest()](./docs/api/appkit/Function.defineManifest.md): Validates a raw manifest (typically a manifest.json import) against the
@@ -110,6 +110,7 @@ npx @databricks/appkit docs <query>
 - [Function: evalGlyph()](./docs/api/appkit/Function.evalGlyph.md): Status glyph for a single eval result.
 - [Function: executeFromRegistry()](./docs/api/appkit/Function.executeFromRegistry.md): Validates tool-call arguments against the entry's schema and invokes its
 - [Function: extractServingEndpoints()](./docs/api/appkit/Function.extractServingEndpoints.md): Extract serving endpoint config from a server file by AST-parsing it.
+- [Function: findRootEvalConfig()](./docs/api/appkit/Function.findRootEvalConfig.md): Path to the root evals.config.ts (from defineEvalConfig) at
 - [Function: findServerFile()](./docs/api/appkit/Function.findServerFile.md): Find the server entry file by checking candidate paths in order.
 - [Function: fk()](./docs/api/appkit/Function.fk.md): Declare foreign-key to another column.
 - [Function: formatEvalDetail()](./docs/api/appkit/Function.formatEvalDetail.md): Indented detail lines for a failing eval (error + failing assertions).
@@ -140,6 +141,7 @@ npx @databricks/appkit docs <query>
 - [Function: jsonb()](./docs/api/appkit/Function.jsonb.md): Returns
 - [Function: loadAgentFromFile()](./docs/api/appkit/Function.loadAgentFromFile.md): Loads a single markdown agent file and resolves its frontmatter against
 - [Function: loadAgentsFromDir()](./docs/api/appkit/Function.loadAgentsFromDir.md): Scans a directory for one subdirectory per agent, each containing
+- [Function: loadRootEvalConfig()](./docs/api/appkit/Function.loadRootEvalConfig.md): Load the root evals.config.ts under rootDir (the project root), or return
 - [Function: matches()](./docs/api/appkit/Function.matches.md): Passes when the value matches pattern.
 - [Function: mcpServer()](./docs/api/appkit/Function.mcpServer.md): Factory for declaring a custom MCP server tool.
 - [Function: normalizeHost()](./docs/api/appkit/Function.normalizeHost.md): Ensure the host has a scheme (Databricks env often lacks https://).
@@ -189,6 +191,7 @@ npx @databricks/appkit docs <query>
 - [Interface: EvalResult](./docs/api/appkit/Interface.EvalResult.md): The outcome of running one eval.
 - [Interface: EvalRunSummary](./docs/api/appkit/Interface.EvalRunSummary.md): Properties
 - [Interface: EvalSummary](./docs/api/appkit/Interface.EvalSummary.md): Properties
+- [Interface: EvalWebServer](./docs/api/appkit/Interface.EvalWebServer.md): Auto-start config for the app under test, à la Playwright's webServer. When
 - [Interface: FilePolicyUser](./docs/api/appkit/Interface.FilePolicyUser.md): Minimal user identity passed to the policy function.
 - [Interface: FileResource](./docs/api/appkit/Interface.FileResource.md): Describes the file or directory being acted upon.
 - [Interface: FunctionTool](./docs/api/appkit/Interface.FunctionTool.md): Properties

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit",
   "type": "module",
-  "version": "0.74.1",
+  "version": "0.75.1",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {