@databricks/appkit-ui 0.27.1 → 0.29.0

package/dist/react/beta.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/schemas/plugin-manifest.generated.d.ts

@@ -104,6 +104,10 @@ interface PluginManifest {
    * When true, this plugin is excluded from the template plugins manifest (appkit.plugins.json) during sync.
    */
   hidden?: boolean;
+  /**
+   * Plugin stability level. Beta plugins may have breaking API changes between minor releases but are on a path to GA. GA (general availability) plugins follow semver strictly.
+   */
+  stability?: "beta" | "ga";
 }
 /**
  * Defines a single field for a resource. Each field has its own environment variable and optional description. Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instance_name, database_name or scope, key).

package/dist/schemas/plugin-manifest.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-manifest.generated.d.ts","names":[],"sources":["../../src/schemas/plugin-manifest.generated.ts"],"mappings":";;AAQA;;;;;KAAY,mBAAA;EACV,IAAA,EAAM,YAAA;EAQN;;;EAJA,KAAA;EAiBG;;;EAbH,WAAA;EAsBU;;;EAlBV,WAAA;EAkBsB;AAiHxB;;EA/HE,UAAA;EAuJY;;;EAnJZ,MAAA;IAAA,CACG,CAAA,WAAY,kBAAA;EAAA;AAAA;;;;;;;KASL,YAAA;;;;UAiHK,cAAA;;;;EAIf,OAAA;;;;EAIA,IAAA;;;;EAIA,WAAA;;;;EAIA,WAAA;;;;EAIA,SAAA;;;;IAIE,QAAA,EAAU,mBAAA;;;;IAIV,QAAA,EAAU,mBAAA;EAAA;;;;EAKZ,MAAA;IACE,MAAA,GAAS,YAAA;EAAA;;;;EAKX,MAAA;;;;EAIA,OAAA;;;;EAIA,UAAA;;;;EAIA,QAAA;;;;EAIA,OAAA;;;;EAIA,cAAA;;;;EAIA,MAAA;AAAA;;;;;;;UAQe,kBAAA;;;;EAIf,GAAA;;;;EAIA,WAAA;;;;EAIA,YAAA;;;;EAIA,QAAA;;;;EAIA,SAAA;;;;EAIA,KAAA;;;;EAIA,OAAA;AAAA;;;;;UAMe,YAAA;EACf,IAAA;EACA,UAAA;IAAA,CACG,CAAA,WAAY,oBAAA;EAAA;EAEf,KAAA,GAAQ,YAAA;EACR,QAAA;EACA,oBAAA;AAAA;;;;;UAMe,oBAAA;EACf,IAAA;EACA,WAAA;EACA,OAAA;EACA,IAAA;EACA,UAAA;IAAA,CACG,CAAA,WAAY,oBAAA;EAAA;EAEf,KAAA,GAAQ,oBAAA;EACR,OAAA;EACA,OAAA;EACA,SAAA;EACA,SAAA;EACA,QAAA;AAAA"}
+{"version":3,"file":"plugin-manifest.generated.d.ts","names":[],"sources":["../../src/schemas/plugin-manifest.generated.ts"],"mappings":";;AAQA;;;;;KAAY,mBAAA;EACV,IAAA,EAAM,YAAA;EAQN;;;EAJA,KAAA;EAiBG;;;EAbH,WAAA;EAsBU;;;EAlBV,WAAA;EAkBsB;AAiHxB;;EA/HE,UAAA;EAuJY;;;EAnJZ,MAAA;IAAA,CACG,CAAA,WAAY,kBAAA;EAAA;AAAA;;;;;;;KASL,YAAA;;;;UAiHK,cAAA;;;;EAIf,OAAA;;;;EAIA,IAAA;;;;EAIA,WAAA;;;;EAIA,WAAA;;;;EAIA,SAAA;;;;IAIE,QAAA,EAAU,mBAAA;;;;IAIV,QAAA,EAAU,mBAAA;EAAA;;;;EAKZ,MAAA;IACE,MAAA,GAAS,YAAA;EAAA;;;;EAKX,MAAA;;;;EAIA,OAAA;;;;EAIA,UAAA;;;;EAIA,QAAA;;;;EAIA,OAAA;;;;EAIA,cAAA;;;;EAIA,MAAA;;;;EAIA,SAAA;AAAA;;;;;;;UAQe,kBAAA;;;;EAIf,GAAA;;;;EAIA,WAAA;;;;EAIA,YAAA;;;;EAIA,QAAA;;;;EAIA,SAAA;;;;EAIA,KAAA;;;;EAIA,OAAA;AAAA;;;;;UAMe,YAAA;EACf,IAAA;EACA,UAAA;IAAA,CACG,CAAA,WAAY,oBAAA;EAAA;EAEf,KAAA,GAAQ,YAAA;EACR,QAAA;EACA,oBAAA;AAAA;;;;;UAMe,oBAAA;EACf,IAAA;EACA,WAAA;EACA,OAAA;EACA,IAAA;EACA,UAAA;IAAA,CACG,CAAA,WAAY,oBAAA;EAAA;EAEf,KAAA,GAAQ,oBAAA;EACR,OAAA;EACA,OAAA;EACA,SAAA;EACA,SAAA;EACA,QAAA;AAAA"}

package/dist/schemas/plugin-manifest.schema.json

@@ -95,6 +95,12 @@
       "type": "boolean",
       "default": false,
       "description": "When true, this plugin is excluded from the template plugins manifest (appkit.plugins.json) during sync."
+    },
+    "stability": {
+      "type": "string",
+      "enum": ["beta", "ga"],
+      "default": "ga",
+      "description": "Plugin stability level. Beta plugins may have breaking API changes between minor releases but are on a path to GA. GA (general availability) plugins follow semver strictly."
     }
   },
   "additionalProperties": false,

package/dist/schemas/template-plugins.schema.json

@@ -12,7 +12,7 @@
     },
     "version": {
       "type": "string",
-      "const": "1.0",
+      "enum": ["1.0", "1.1"],
       "description": "Schema version for the template plugins manifest"
     },
     "plugins": {
@@ -69,6 +69,12 @@
           "type": "string",
           "description": "Message displayed to the user after project initialization. Use this to inform about manual setup steps (e.g. environment variables, resource provisioning)."
         },
+        "stability": {
+          "type": "string",
+          "enum": ["beta", "ga"],
+          "default": "ga",
+          "description": "Plugin stability level. Beta is heading to GA; APIs may change between minor releases. GA (general availability) follows semver."
+        },
         "resources": {
           "type": "object",
           "required": ["required", "optional"],

package/dist/shared/src/agent.d.ts

@@ -0,0 +1 @@
+import "json-schema";

package/dist/shared/src/index.d.ts

@@ -1,3 +1,4 @@
+import "./agent.js";
 import { PluginClientConfigs, PluginEndpointMap, PluginEndpoints } from "./plugin.js";
 import "./cache.js";
 import "./execute.js";

package/dist/shared/src/plugin.d.ts

@@ -1,5 +1,5 @@
-import "express";
 import "json-schema";
+import "express";
 
 //#region ../shared/src/plugin.d.ts
 /** Map of endpoint names to their full paths for a plugin */

package/docs/api/appkit/Interface.PluginManifest.md

@@ -233,6 +233,24 @@ Resources that must be available for the plugin to function
 
 ***
 
+### stability?[​](#stability "Direct link to stability?")
+
+```ts
+optional stability: "beta" | "ga";
+
+```
+
+Plugin stability level. Beta plugins may have breaking API changes between minor releases but are on a path to GA. GA (general availability) plugins follow semver strictly.
+
+#### Inherited from[​](#inherited-from-8 "Direct link to Inherited from")
+
+```ts
+Omit.stability
+
+```
+
+***
+
 ### version?[​](#version "Direct link to version?")
 
 ```ts
@@ -242,7 +260,7 @@ optional version: string;
 
 Plugin version (semver format)
 
-#### Inherited from[​](#inherited-from-8 "Direct link to Inherited from")
+#### Inherited from[​](#inherited-from-9 "Direct link to Inherited from")
 
 ```ts
 Omit.version

package/docs/plugins/custom-plugins.md

@@ -134,7 +134,7 @@ This pattern allows:
   * **Cache management**: Access the cache service via `this.cache`. See [`CacheConfig`](./docs/api/appkit/Interface.CacheConfig.md) for configuration.
   * **Telemetry**: Instrument your plugin with traces and metrics via `this.telemetry`. See [`ITelemetry`](./docs/api/appkit/Interface.ITelemetry.md).
 
-* **Execution interceptors**: Use `execute()` and `executeStream()` with [`StreamExecutionSettings`](./docs/api/appkit/Interface.StreamExecutionSettings.md)
+* **Execution interceptors**: Use `execute()` and `executeStream()` with [`StreamExecutionSettings`](./docs/api/appkit/Interface.StreamExecutionSettings.md) for automatic caching, retry, timeout, and [telemetry span attributes](./docs/plugins/execution-context.md#telemetry-span-attributes) (`execution.context`, `caller.id`)
 
 **Consuming your plugin programmatically**
 

package/docs/plugins/execution-context.md

@@ -39,6 +39,18 @@ Exported from `@databricks/appkit`:
 * `getWarehouseId()`: `Promise<string>` (from `DATABRICKS_WAREHOUSE_ID` or auto-selected in dev)
 * `getWorkspaceId()`: `Promise<string>` (from `DATABRICKS_WORKSPACE_ID` or fetched)
 
+## Telemetry span attributes[​](#telemetry-span-attributes "Direct link to Telemetry span attributes")
+
+The `plugin.execute` span created by the execution interceptor chain includes these attributes:
+
+| Attribute                    | Type                    | Description                                                                        |
+| ---------------------------- | ----------------------- | ---------------------------------------------------------------------------------- |
+| `execution.context`          | `"user"` \| `"service"` | Whether the operation runs as a user (OBO) or service principal                    |
+| `caller.id`                  | `string`                | The user ID (OBO) or service principal ID                                          |
+| `execution.obo_dev_fallback` | `boolean`               | Set to `true` when an OBO call falls back to service principal in development mode |
+
+These attributes are automatically added when your plugin uses `execute()` or `executeStream()`. All built-in plugins use these methods for their OBO operations. Custom plugins should do the same to get automatic telemetry instrumentation.
+
 ## Development mode behavior[​](#development-mode-behavior "Direct link to Development mode behavior")
 
-In local development (`NODE_ENV=development`), if `asUser(req)` is called without a user token, it logs a warning and skips user impersonation — the operation runs with the default credentials configured for the app instead.
+In local development (`NODE_ENV=development`), if `asUser(req)` is called without a user token, it logs a warning and skips user impersonation — the operation runs with the default credentials configured for the app instead. The telemetry span will show `execution.context: "service"` with `execution.obo_dev_fallback: true` to distinguish these from regular service principal calls.

package/docs/plugins/stability.md

@@ -0,0 +1,156 @@
+# Plugin Stability Tiers
+
+AppKit plugins have a two-tier stability system that communicates API maturity and breaking-change expectations.
+
+## Tiers[​](#tiers "Direct link to Tiers")
+
+| Tier     | Import Path               | Contract                                                        |
+| -------- | ------------------------- | --------------------------------------------------------------- |
+| **Beta** | `@databricks/appkit/beta` | API may change between minor releases. On a path to GA.         |
+| **GA**   | `@databricks/appkit`      | Generally available. Production ready. Follows semver strictly. |
+
+The import path is the primary stability signal. Importing from `/beta` is explicit consent to potential breaking changes.
+
+## Promotion Path[​](#promotion-path "Direct link to Promotion Path")
+
+Promotion is one-way. Plugins can enter at any tier.
+
+```text
+beta ──→ ga
+
+```
+
+## Usage[​](#usage "Direct link to Usage")
+
+### Importing Plugins by Tier[​](#importing-plugins-by-tier "Direct link to Importing Plugins by Tier")
+
+```typescript
+// GA plugins
+import { server, analytics } from "@databricks/appkit";
+
+// Beta plugins
+import { someBetaPlugin } from "@databricks/appkit/beta";
+
+```
+
+### UI Components[​](#ui-components "Direct link to UI Components")
+
+`@databricks/appkit-ui` mirrors the same pattern:
+
+```typescript
+import { SomeComponent } from "@databricks/appkit-ui/react/beta";
+import { someUtil } from "@databricks/appkit-ui/js/beta";
+
+```
+
+## CLI Commands[​](#cli-commands "Direct link to CLI Commands")
+
+### Listing Plugins with Stability[​](#listing-plugins-with-stability "Direct link to Listing Plugins with Stability")
+
+```bash
+npx appkit plugin list
+
+```
+
+The output includes a STABILITY column showing each plugin's tier.
+
+### Creating a Plugin with Stability[​](#creating-a-plugin-with-stability "Direct link to Creating a Plugin with Stability")
+
+```bash
+npx appkit plugin create
+
+```
+
+The interactive flow prompts for a stability level (defaults to GA).
+
+### Promoting a Plugin[​](#promoting-a-plugin "Direct link to Promoting a Plugin")
+
+```bash
+# Promote from beta to GA
+npx appkit plugin promote my-plugin --to ga
+
+# Preview changes without modifying files
+npx appkit plugin promote my-plugin --to ga --dry-run
+
+```
+
+The promote command:
+
+* Updates the plugin's `manifest.json` stability field
+* Rewrites import paths across your project's `.ts`/`.tsx` files
+* Runs `plugin sync` to update `appkit.plugins.json`
+
+**Options:**
+
+* `--dry-run` -- Show what would change without writing
+* `--skip-imports` -- Only update the manifest
+* `--skip-sync` -- Don't auto-run sync
+* `--allow-installed` -- Allow promoting a plugin that lives only under `node_modules` (advanced)
+
+## Manifest Field[​](#manifest-field "Direct link to Manifest Field")
+
+The `stability` field in `manifest.json` is optional. When absent, the plugin is considered GA.
+
+```json
+{
+  "name": "my-plugin",
+  "displayName": "My Plugin",
+  "description": "An in-development feature",
+  "stability": "beta",
+  "resources": { "required": [], "optional": [] }
+}
+
+```
+
+Valid values: `"beta"`, `"ga"`.
+
+## Template Manifest (appkit.plugins.json)[​](#template-manifest-appkitpluginsjson "Direct link to Template Manifest (appkit.plugins.json)")
+
+When `plugin sync` discovers non-GA plugins, it includes their stability in the output. That is true for **every** discovery path: plugins resolved from your server file, from `--plugins-dir` / local plugin trees, and from known packages under `node_modules` (for example `@databricks/appkit`). The tier in each plugin’s `manifest.json` is always reflected in the synced template manifest when it is not GA.
+
+```json
+{
+  "version": "1.1",
+  "plugins": {
+    "my-plugin": {
+      "name": "my-plugin",
+      "stability": "beta",
+      "package": "@databricks/appkit"
+    }
+  }
+}
+
+```
+
+Only GA plugins can be marked `requiredByTemplate`. Non-GA plugins always remain optional during init.
+
+## For Third-Party Plugin Authors[​](#for-third-party-plugin-authors "Direct link to For Third-Party Plugin Authors")
+
+The import path (`/beta`) only applies to first-party plugins shipped inside `@databricks/appkit`. Third-party plugins declare stability via the `stability` field in their `manifest.json`. CLI tooling (`plugin list`, `plugin sync`) surfaces this information to users.
+
+## For First-Party Plugin Authors (AppKit Monorepo)[​](#for-first-party-plugin-authors-appkit-monorepo "Direct link to For First-Party Plugin Authors (AppKit Monorepo)")
+
+Inside the AppKit monorepo, each plugin's `manifest.json` `stability` field is the **single source of truth** for which subpath ships the plugin. Two build-time generators read every `packages/appkit/src/plugins/<name>/manifest.json`:
+
+* `tools/generate-plugin-entries.ts` writes the runtime export barrels:
+
+  <!-- -->
+
+  * `packages/appkit/src/plugins/ga-exports.generated.ts` — re-exports of GA plugins, included by `src/index.ts` (the `@databricks/appkit` entry).
+  * `packages/appkit/src/plugins/beta-exports.generated.ts` — re-exports of beta plugins, included by `src/beta.ts` (the `@databricks/appkit/beta` entry).
+
+* `tools/generate-plugin-doc-banners.ts` injects (or removes) a `:::warning Beta plugin` admonition at the top of each plugin's docs page (`docs/docs/plugins/<name>.md`) so a plugin's documented stability follows its manifest. The script only writes under `docs/docs/plugins/`: each manifest `name` must match the plugin schema pattern (`^[a-z][a-z0-9-]*$`), and resolved doc paths are checked so a malformed `name` cannot escape that directory.
+
+All generated artifacts are committed and verified by CI; an out-of-date file fails the `Check generated types are up to date` step.
+
+The `appkit plugin promote` command detects monorepo context (presence of `tools/generate-plugin-entries.ts`) and re-runs the generator after updating the manifest, so the runtime exports, the synced `appkit.plugins.json`, and the manifest can never drift apart.
+
+To move a built-in plugin between tiers manually:
+
+```bash
+# Edit packages/appkit/src/plugins/<name>/manifest.json
+# Set "stability": "beta" (or remove the field for GA)
+pnpm run generate:types   # regenerates schema/registry types, export barrels, and doc banners
+pnpm sync:template        # regenerates template/appkit.plugins.json
+
+```

package/llms.txt

@@ -53,6 +53,7 @@ npx @databricks/appkit docs <query>
 - [Model Serving plugin](./docs/plugins/model-serving.md): Provides an authenticated proxy to Databricks Model Serving endpoints, with invoke and streaming support.
 - [Plugin management](./docs/plugins/plugin-management.md): AppKit includes a CLI for managing plugins. All commands are available under npx @databricks/appkit plugin.
 - [Server plugin](./docs/plugins/server.md): Provides HTTP server capabilities with development and production modes.
+- [Plugin Stability Tiers](./docs/plugins/stability.md): AppKit plugins have a two-tier stability system that communicates API maturity and breaking-change expectations.
 - [Vector Search plugin](./docs/plugins/vector-search.md): Query Databricks Vector Search indexes with hybrid search, reranking, and cursor pagination from your AppKit application.
 
 ## appkit API reference [collapsed]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit-ui",
   "type": "module",
-  "version": "0.27.1",
+  "version": "0.29.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -24,7 +24,9 @@
   ],
   "exports": {
     "./js": "./dist/js/index.js",
+    "./js/beta": "./dist/js/beta.js",
     "./react": "./dist/react/index.js",
+    "./react/beta": "./dist/react/beta.js",
     "./package.json": "./package.json",
     "./styles.css": "./dist/styles.css"
   },