feat(apps): surface beta plugin tier in apps init by MarioCadenas · Pull Request #5090 · databricks/cli

MarioCadenas · 2026-04-27T10:28:19Z

Why

AppKit (databricks/appkit#264)
added a stability field on plugins (stable or beta) and bumped
appkit.plugins.json to schema 1.1. databricks apps init was
stability-blind: every plugin rendered identically in the picker, and
the AppKit init template needs Stability on each selected plugin to
route beta plugins through the @databricks/appkit/beta subpath
(commit d826a532).

Changes

libs/apps/manifest: add Plugin.Stability (json:"stability,omitempty")
and a StabilityLabel() passthrough. Plain string, not an enum, so
unknown future tiers round-trip.
libs/apps/prompt: new RenderStabilityTier adds a colored (beta)
suffix to plugin labels (yellow #FFAB00); unknown tiers fall back to
gray. Stable/unset gets no suffix.
cmd/apps/init.go: pluginVar now carries Stability, populated from
the manifest, so the AppKit template can branch on {{$p.Stability}}.

No flag-gating of beta plugins. AppKit's sync step already strips
requiredByTemplate from non-stable plugins, so they show up as
selectable rather than mandatory.

Test plan

go test ./cmd/apps/... ./libs/apps/manifest/... ./libs/apps/prompt/...
golangci-lint clean on changed packages.
Visual: apps init against a local template with mixed
stable/beta/unknown plugins. Yellow (beta), gray for unknown,
nothing for stable.

huh applies its own foreground to the focused row, so the inline tier
color is partially overridden on whichever row is currently highlighted.
Easy to swap for a non-colored [beta] token if that's annoying in
practice.

Demo

demo-beta-system.mp4

The init template hard-coded a single `from '@databricks/appkit'` import for every plugin, which would resolve to `undefined` for beta plugins (they live behind the `/beta` subpath export). Splits the import emission by plugin stability: - Stable plugins stay on the existing line. - Each beta plugin gets its own `from '@databricks/appkit/beta'` import line. Backwards-compatible with the current Databricks CLI: until pluginVar exposes Stability, `$p.Stability` resolves to the empty string, every plugin compares unequal to "beta", and rendering matches today's output. Once databricks/cli#5090 lands the field, beta plugins start routing to the right import automatically. The plugins: [...] array body is unchanged — both stable and beta plugins are constructed identically (`plugin()`) once they're in scope, so the runtime call list doesn't depend on tier. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

Round-trip the new optional `stability` field on AppKit plugin manifests (experimental / preview / stable, schema 1.1, see databricks/appkit#264) and surface non-stable tiers as a colored parenthetical suffix in the `databricks apps init` plugin picker. Stability is stored as a plain string so unknown future tiers round-trip and render in gray instead of breaking the loader.

Mirrors the AppKit PR which dropped `experimental` and renamed `preview` to `beta` (databricks/appkit#264). Forward-compat fallback for unknown tiers is preserved. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

The AppKit template now branches on `{{$p.Stability}}` to route beta plugins through the `/beta` subpath export. Make pluginVar carry the field so the template can read it. See databricks/appkit#264 commit d826a532. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

…tern The AppKit init template was tightened to emit a single combined beta import line via a string-accumulator pre-pass (databricks/appkit#264 commit 488797fc): {{- $betaImports := "" -}} {{- range $name, $p := .plugins -}} {{- if eq $p.Stability "beta" -}} {{- if eq $betaImports "" -}} {{- $betaImports = $name -}} {{- else -}} {{- $betaImports = printf "%s, %s" $betaImports $name -}} {{- end -}} {{- end -}} {{- end -}} That pattern depends on three text/template features: - Variable reassignment (`$x = ...`) inside `range`, against an outer-scope variable. - The `printf` builtin. - Pointer-field access (`$p.Stability`) on map values. If a future refactor of executeTemplate (or a Go template engine swap) breaks any of these, users would silently get malformed server.ts files at `databricks apps init` time. This regression test exercises the exact pattern with hermetic input — no AppKit checkout required — and asserts the expected import shapes for all-stable, single beta, multi beta, all-beta, and unknown-tier (alpha) cases. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

The init template hard-coded a single `from '@databricks/appkit'` import for every plugin, which would resolve to `undefined` for beta plugins (they live behind the `/beta` subpath export). Splits the import emission by plugin stability: - Stable plugins stay on the existing line. - Each beta plugin gets its own `from '@databricks/appkit/beta'` import line. Backwards-compatible with the current Databricks CLI: until pluginVar exposes Stability, `$p.Stability` resolves to the empty string, every plugin compares unequal to "beta", and rendering matches today's output. Once databricks/cli#5090 lands the field, beta plugins start routing to the right import automatically. The plugins: [...] array body is unchanged — both stable and beta plugins are constructed identically (`plugin()`) once they're in scope, so the runtime call list doesn't depend on tier. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

pkosiec

LGTM

Mirrors the AppKit-side rename (databricks/appkit#264). Real synced manifests will now carry `"stability": "ga"` instead of `"stable"`; empty/unset still maps to GA. Also renames internal test fixtures and identifiers from "stable" to "ga"/"GA" so the codebase stays consistent with the new wire value. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

Hard rename of the production-ready stability tier from "stable" to "ga" (general availability). Schema enum becomes ["beta", "ga"]; "stable" is no longer a valid manifest value. Why "ga": "stable" was overloaded — every git branch, plugin release, and SDK version is "stable" in some sense. "ga" matches the broader Databricks product vocabulary for the production-ready / semver-strict tier and reads unambiguously alongside "beta". Touched layers (every place "stable" had any meaning is renamed): - Schemas: `enum: ["beta", "stable"]` -> `["beta", "ga"]` in both `plugin-manifest.schema.json` and `template-plugins.schema.json`, with descriptions updated. Default value changes from "stable" to "ga" so absent stability still maps to the production-ready tier. - TypeScript types: `Stability = "beta" | "stable"` -> `"beta" | "ga"` across `manifest-types.ts`, `plugin-manifest.generated.ts`, `promote.ts`, `sync.ts`, `list.ts`, `create.ts`, and the two generators in `tools/`. - Promote command: TIER_ORDER, IMPORT_PATH_MAP, isStability, error messages, validation, --to flag help, and the post-promote generator/sync block. - Sync command: the strip-requiredByTemplate condition now compares against "ga" instead of "stable". - Create command: interactive prompt offers "GA" / "Beta" (label), with values "ga" / "beta". Existing default-omit logic preserved. - Generated barrel: renamed `stable-exports.generated.ts` -> `ga-exports.generated.ts` via `git mv`. `src/index.ts` and the `tools/generate-plugin-entries.ts` writer updated. CI freshness diff list and root `package.json` scripts updated too. - Doc banners generator: only beta plugins get a banner; the GA branch strips any existing banner. No banner is emitted for GA (matches the design — absence of beta = GA, no extra label needed). - Tests: bulk-renamed `to: "stable"` test args to `to: "ga"`, updated `isStability`/TIER_ORDER tests for the new tier name, and extended the legacy-rejection cases so manifests or --to flags carrying "stable" (now legacy), "experimental", or "preview" are all rejected up front. - Stability docs page: tier name updated everywhere; promotion path diagram now reads `beta ──→ ga`; current-plugins-by-tier section says "GA" instead of "Stable". Backwards compat: the schema rejects the legacy "stable" value, so a stale manifest must migrate to "ga" (or omit the field). Built-in plugins never wrote the field explicitly, so no first-party manifest needs editing. Third-party plugins that explicitly committed `"stability": "stable"` will fail validation until they update — this is the "hard rename" the user explicitly chose over a deprecation alias. CLI side (databricks/cli#5090) is intentionally NOT touched here. The CLI hardcodes a "stable" check in `Plugin.StabilityLabel()` to suppress the picker suffix for the default tier. After this rename, that check still suppresses "stable" (now legacy / never written by AppKit) but absent-stability plugins (the new GA default) already render with no suffix because the field is omitted from the JSON. So the CLI keeps working without changes; an explicit "ga" written into a manifest would render as "(ga)" in the picker, which is acceptable for now. A follow-up CLI PR can update the suppression check. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

The init template hard-coded a single `from '@databricks/appkit'` import for every plugin, which would resolve to `undefined` for beta plugins (they live behind the `/beta` subpath export). Splits the import emission by plugin stability: - Stable plugins stay on the existing line. - Each beta plugin gets its own `from '@databricks/appkit/beta'` import line. Backwards-compatible with the current Databricks CLI: until pluginVar exposes Stability, `$p.Stability` resolves to the empty string, every plugin compares unequal to "beta", and rendering matches today's output. Once databricks/cli#5090 lands the field, beta plugins start routing to the right import automatically. The plugins: [...] array body is unchanged — both stable and beta plugins are constructed identically (`plugin()`) once they're in scope, so the runtime call list doesn't depend on tier. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

Hard rename of the production-ready stability tier from "stable" to "ga" (general availability). Schema enum becomes ["beta", "ga"]; "stable" is no longer a valid manifest value. Why "ga": "stable" was overloaded — every git branch, plugin release, and SDK version is "stable" in some sense. "ga" matches the broader Databricks product vocabulary for the production-ready / semver-strict tier and reads unambiguously alongside "beta". Touched layers (every place "stable" had any meaning is renamed): - Schemas: `enum: ["beta", "stable"]` -> `["beta", "ga"]` in both `plugin-manifest.schema.json` and `template-plugins.schema.json`, with descriptions updated. Default value changes from "stable" to "ga" so absent stability still maps to the production-ready tier. - TypeScript types: `Stability = "beta" | "stable"` -> `"beta" | "ga"` across `manifest-types.ts`, `plugin-manifest.generated.ts`, `promote.ts`, `sync.ts`, `list.ts`, `create.ts`, and the two generators in `tools/`. - Promote command: TIER_ORDER, IMPORT_PATH_MAP, isStability, error messages, validation, --to flag help, and the post-promote generator/sync block. - Sync command: the strip-requiredByTemplate condition now compares against "ga" instead of "stable". - Create command: interactive prompt offers "GA" / "Beta" (label), with values "ga" / "beta". Existing default-omit logic preserved. - Generated barrel: renamed `stable-exports.generated.ts` -> `ga-exports.generated.ts` via `git mv`. `src/index.ts` and the `tools/generate-plugin-entries.ts` writer updated. CI freshness diff list and root `package.json` scripts updated too. - Doc banners generator: only beta plugins get a banner; the GA branch strips any existing banner. No banner is emitted for GA (matches the design — absence of beta = GA, no extra label needed). - Tests: bulk-renamed `to: "stable"` test args to `to: "ga"`, updated `isStability`/TIER_ORDER tests for the new tier name, and extended the legacy-rejection cases so manifests or --to flags carrying "stable" (now legacy), "experimental", or "preview" are all rejected up front. - Stability docs page: tier name updated everywhere; promotion path diagram now reads `beta ──→ ga`; current-plugins-by-tier section says "GA" instead of "Stable". Backwards compat: the schema rejects the legacy "stable" value, so a stale manifest must migrate to "ga" (or omit the field). Built-in plugins never wrote the field explicitly, so no first-party manifest needs editing. Third-party plugins that explicitly committed `"stability": "stable"` will fail validation until they update — this is the "hard rename" the user explicitly chose over a deprecation alias. CLI side (databricks/cli#5090) is intentionally NOT touched here. The CLI hardcodes a "stable" check in `Plugin.StabilityLabel()` to suppress the picker suffix for the default tier. After this rename, that check still suppresses "stable" (now legacy / never written by AppKit) but absent-stability plugins (the new GA default) already render with no suffix because the field is omitted from the JSON. So the CLI keeps working without changes; an explicit "ga" written into a manifest would render as "(ga)" in the picker, which is acceptable for now. A follow-up CLI PR can update the suppression check. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

The previous template branched on `$p.Stability` (a per-plugin struct field exposed by databricks/cli#5090). On older CLIs whose `pluginVar` predates that PR — i.e. an empty `struct{}{}` — Go's text/template errors on the missing field, the CLI's `executeTemplate` catches the error and returns the file unchanged, and the user gets a `server.ts` with raw `{{...}}` directives that won't compile. Bad fallback. Move the per-plugin "is this beta?" lookup off the struct field and onto a top-level map (`$.betaPlugins map[string]bool`): {{- if and $.betaPlugins (index $.betaPlugins $name) -}} Why this is backwards-compatible: - Map keys absent from the top-level data map return zero (nil) under the CLI's `Option("missingkey=zero")`. So `$.betaPlugins` resolves to nil on older CLIs. - Go text/template's `and`/`or` have been lazy since Go 1.18 — the first nil/false argument short-circuits and the rest aren't evaluated. So we never `index` a nil map. - Result: every plugin lands on the GA import line and the file renders cleanly. Beta routing is gated on the CLI populating the new top-level map. Verified by rendering the template against three data shapes via Go's text/template directly (test program reproduced inline below): OLD CLI (empty pluginVar, no .betaPlugins) -> renders, GA-only NEW CLI (.Stability field, no .betaPlugins) -> renders, GA-only NEW CLI+ (.betaPlugins populated) -> renders, beta routed ```go type pluginVarOld struct{} type pluginVarNew struct{ Stability string } tmpl, _ := template.New("server.ts").Option("missingkey=zero").Parse(src) // each shape executes without error and produces sensible output ``` Companion CLI follow-up: `databricks/cli#5090` should populate `betaPlugins map[string]bool` in `templateData()` (derived from `pluginVar.Stability == "beta"`) so new CLIs activate the routing. Without that, the new CLI behaves like an old one (graceful but no beta routing). The existing `pluginVar.Stability` stays useful for the picker label; only the template lookup moves to the top-level map. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

* feat: add plugin stability system with import-path enforcement Add a `stability` field to plugin manifests with full CLI tooling. Plugins declare their tier in manifest.json; the import path (`@databricks/appkit/<tier>` for non-stable, `@databricks/appkit` for stable) enforces the contract at the package boundary so consumers cannot accidentally take a dependency on an unstable API. This commit lands the initial three-tier implementation (experimental/preview/stable). A follow-up commit on this branch collapses to two tiers (beta/stable); the per-commit history shows the evolution. - Schema: stability enum on plugin-manifest and template-plugins schemas - Entrypoints: per-tier subpath exports in appkit and appkit-ui - CLI sync: propagate stability, strip requiredByTemplate for non-stable, orphan resource detection, template version bumped to 1.1 - CLI list: always-visible STABILITY column - CLI scaffold: stability prompt during plugin create - CLI promote: new command to promote plugins between tiers - Docs: stability tiers documentation page Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> * fix(plugin): harden promote command against path traversal & sync failures Address review findings on the three-tier plugin stability system: Security: - Validate plugin name against npm-package charset (rejects "..", path separators, NUL, backslash; allows @scope/name) - Bound the node_modules manifest lookup with isWithinDirectory so a typo'd or malicious name cannot escape dist/plugins - Refuse to mutate manifests under node_modules unless --allow-installed is passed (reinstall would silently revert otherwise) - Replace console.error(err) in the action handler with a fixed message and a DEBUG-gated full-error dump to avoid leaking absolute paths / stack frames into telemetry Correctness: - Validate the manifest's stability field before any mutation; reject unknown values (e.g. "Stable") instead of silently treating them as stable and writing back - Make a failed post-promote 'plugin sync' exit non-zero and skip the success message - Guard sync.ts orphan detection against null / non-object plugin entries in a stale appkit.plugins.json Robustness: - Skip symlinked directories during the project walk (prevents both cycles and out-of-tree rewrites) - Expand the directory-skip list (.git, .turbo, .next, .nuxt, .cache, .svelte-kit, .vite, .parcel-cache, coverage, build, out) - Align findTsFiles depth cap with sync.ts MAX_SCAN_DEPTH - Add boundary check inside the recursive TS walk Tests: - Replace placeholder tests with real runPromote integration tests covering invalid names, path-traversal attempts, unknown tiers, invalid manifest stability, demotion, no-op, dry-run, import rewriting, symlink boundaries, and the node_modules guard Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> * docs: regenerate plugin-manifest schema & typedoc for stability field Re-running 'pnpm docs:build' picks up three derived artifacts that the original feature commit missed: - docs/docs/api/appkit/Interface.PluginManifest.md (typedoc): adds the new optional 'stability' field on PluginManifest - docs/static/schemas/plugin-manifest.schema.json: adds the experimental/preview/stable enum (default "stable") - docs/static/schemas/template-plugins.schema.json: adds 'stability' and bumps schema version from const "1.0" to enum ["1.0","1.1"] Generated by 'pnpm docs:build'; no source changes. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> * refactor(plugin): collapse stability tiers to beta/stable Removes the "experimental" tier entirely and renames "preview" to "beta". The stability system now has two tiers instead of three: beta ──→ stable Beta plugins follow the previous Preview contract: APIs may change between minor releases, but the plugin is on a path to stable. Changes: - Schema: plugin-manifest and template-plugins enums updated to ["beta", "stable"]; manifest schema version stays at 1.1. - Subpath exports: drop @databricks/appkit/experimental and @databricks/appkit-ui/{js,react}/experimental; rename /preview to /beta. Source entry files renamed via git mv (experimental.ts files removed). - Promote command: TIER_ORDER, IMPORT_PATH_MAP, isStability(), help text, and tests updated. Legacy tier values are now rejected both as --to targets and as manifest stability values; tests assert this. - Create command: stability prompt offers Stable | Beta only. - list/sync/CreateAnswers types narrowed to "beta" | "stable". - Docs: stability.md rewritten for the two-tier system; auto-generated Interface.PluginManifest.md and docs/static/schemas/* match the new enum after pnpm docs:build. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> * fix(template): import beta plugins from /beta subpath The init template hard-coded a single `from '@databricks/appkit'` import for every plugin, which would resolve to `undefined` for beta plugins (they live behind the `/beta` subpath export). Splits the import emission by plugin stability: - Stable plugins stay on the existing line. - Each beta plugin gets its own `from '@databricks/appkit/beta'` import line. Backwards-compatible with the current Databricks CLI: until pluginVar exposes Stability, `$p.Stability` resolves to the empty string, every plugin compares unequal to "beta", and rendering matches today's output. Once databricks/cli#5090 lands the field, beta plugins start routing to the right import automatically. The plugins: [...] array body is unchanged — both stable and beta plugins are constructed identically (`plugin()`) once they're in scope, so the runtime call list doesn't depend on tier. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> * fix(template): consolidate beta plugin imports into a single line The previous template emitted a separate import line per beta plugin: import { betaA } from '@databricks/appkit/beta'; import { betaB } from '@databricks/appkit/beta'; Switch to a single combined import: import { betaA, betaB } from '@databricks/appkit/beta'; Implementation: a string-accumulator pre-pass over .plugins builds a comma-separated list of beta names using printf, then a single guarded import line is emitted if the list is non-empty. Pure text/template, no sprig functions required, so it works against the Databricks CLI's existing template engine. Behavior unchanged when no beta plugins are selected (no extra import line, identical to all-stable rendering today). Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> * feat(appkit): codegen stable/beta export barrels from plugin manifests Closes a real gap in the stability system: the manifest's `stability` field, the synced appkit.plugins.json, and the runtime entry exports (src/index.ts, src/beta.ts) were three independent sources of truth that could drift apart. Promoting a plugin via manifest edit alone produced a broken state where the CLI generated `import { x } from "@databricks/appkit/beta"` for a plugin that was still actually exported from `@databricks/appkit`, leaving `x` undefined at runtime. Make the manifest the single source of truth. - New generator at tools/generate-plugin-entries.ts reads every packages/appkit/src/plugins/<name>/manifest.json, groups by `stability`, and writes two committed barrels: packages/appkit/src/plugins/stable-exports.generated.ts packages/appkit/src/plugins/beta-exports.generated.ts Hidden plugins (manifest.hidden = true) are skipped, preserving the current vector-search behaviour. - src/index.ts and src/beta.ts now delegate to the generated barrels via `export *`, so adding/moving a plugin only requires editing one file (its manifest). - The hand-curated kitchen-sink barrel at src/plugins/index.ts is removed; the generated barrels replace it and knip flagged it as unused. - Wired into the build: - packages/appkit/package.json#scripts.build:package now runs the generator before tsdown. - Root `generate:types` includes plugin-entries so existing CI "Check generated types are up to date" catches stale barrels. The CI step's git diff list is extended accordingly. - Added a focused `generate:plugin-entries` root script for convenience. - `appkit plugin promote` detects monorepo context (presence of tools/generate-plugin-entries.ts) and re-runs the generator after updating the manifest, before kicking off `plugin sync`. Outside the monorepo (third-party plugin projects) it's a no-op. - docs/docs/plugins/stability.md gains a "For First-Party Plugin Authors" section explaining the single-source-of-truth model and how to flip a plugin between tiers manually. Verified end-to-end: marking genie as `stability: "beta"` → `pnpm run generate:plugin-entries` → genie moves from stable-exports.generated.ts to beta-exports.generated.ts → `pnpm sync:template` → genie carries `stability: "beta"` and no `requiredByTemplate` in appkit.plugins.json. All three layers consistent without manual edits. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> * fix(plugin): close drift gaps surfaced by review Three review-blocker fixes that together restore the PR's headline "manifest is the single source of truth, all layers stay aligned" claim: 1. Post-promote sync writes to the right file in the monorepo. Previously `runPromote` shelled out to `npx appkit plugin sync --write` with no flags, which defaults `outputPath` to `<cwd>/appkit.plugins.json` and never touches `template/appkit.plugins.json` (the file shipped with the AppKit init template). In the monorepo path the manifest changed and the runtime barrels regenerated, but the synced template manifest stayed stale. Detect monorepo context the same way the generator step does (presence of `tools/generate-plugin-entries.ts`) and prefer `pnpm run sync:template` when available, which has the right flags wired (`--plugins-dir packages/appkit/src/plugins --output template/appkit.plugins.json --require-plugins server`). Outside the monorepo the original `npx appkit plugin sync --write` is still used. 2. CI freshness gate now covers `template/appkit.plugins.json`. The existing "Check generated types are up to date" step diffs the four schema/registry/barrel files but not the synced template manifest. A contributor editing a plugin's `stability` by hand and forgetting `pnpm sync:template` could land a drift between the manifest and what the Go init template branches on at scaffold time. Add a follow-up step that runs `pnpm run sync:template` and fails the build on a non-empty diff, mirroring the existing pattern. 3. Generator validates `manifest.name` and folder name against the schema regex AND a JS-identifier rule. `tools/generate-plugin-entries.ts` interpolates `name` directly into `export { ${name} } from "./${folder}";`. The schema accepts `^[a-z][a-z0-9-]*$` (kebab-case) and even shows `"my-custom-plugin"` as an example. Today this is masked because `vector-search` (the only kebab-named plugin) is `hidden: true`, but the instant any hyphenated plugin graduates the generator emits a TypeScript syntax error. The same gap is also a defense-in-depth code-injection vector (CWE-94) — a malicious manifest with `"name": "x }; await import('./evil'); //"` would generate parseable, side-effect-importing TS that runs at module load on every consumer. Add a `validateIdentifier` pass that runs both the schema regex (`^[a-z][a-z0-9-]*$`, mirroring `appkit plugin validate`) and a JS-identifier rule (`^[a-z][a-zA-Z0-9_]*$`, restricted to lowercase first letter to match the existing built-ins) on both `manifest.name` and the plugin folder name. Throws with a clear message pointing at the offending manifest and explaining how to fix it. Verified manually: - Adding a `bad-name` plugin folder with `"name": "bad-name"` makes the generator throw with the expected error message before tsdown runs. - Removing the bad plugin and re-running produces the canonical 6-stable / 0-beta barrels. - `pnpm build && pnpm -r typecheck && pnpm test && pnpm docs:build` all clean. 88 test files, 1680 tests passing. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> * chore: reconcile generated artifacts after rebase onto main Rebase onto main pulled in the new `jobs` plugin (#280) and a duplicate `export * from "./plugins/stable-exports.generated";` from the conflict resolution in `packages/appkit/src/index.ts`. Two follow-on changes: - Re-run `tools/generate-plugin-entries.ts` so `jobs` is included in `stable-exports.generated.ts`. The codegen commit on this branch predates the jobs plugin landing. - Dedupe the duplicate `export *` line in `index.ts` that crept in during the merge resolution of the codegen commit. No behavior change beyond making `jobs` reachable through `@databricks/appkit` (matching what main already does via the hand-curated barrel that this PR replaces). Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> * fix(ci): build shared package before sync:template freshness check The new "Check synced template manifest is up to date" step in the lint job ran `pnpm run sync:template`, which goes through `packages/shared/bin/appkit.js` -> `packages/shared/dist/cli/index.js`. The lint job only does `pnpm install --frozen-lockfile` (no build), so dist doesn't exist and Node throws ERR_MODULE_NOT_FOUND. Initially tried bypassing the bin and running the CLI from source via `tsx packages/shared/src/cli/index.ts`, but that made knip discover the source file as a new entry point (since the workflow yaml now references it from outside the ignored `packages/shared` workspace) and flag `commander` and `dotenv/config` as unlisted root-level dependencies. Cleaner fix: add a step to build just the shared package (~1s) before the freshness check, then use the existing `pnpm run sync:template` script unchanged. Mirrors what users would do locally. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> * fix(ci): build shared dist directly via tsdown, not full build:package Previous attempt used `pnpm --filter shared build:package` to produce the dist needed by `pnpm sync:template`. That script also re-runs `tools/generate-schema-types.ts` which writes the raw (unformatted) version of `plugin-manifest.generated.ts` — and the next CI step ("Run Biome Check") then fails because the file no longer matches what biome would format it to. Invoke tsdown directly via `pnpm --filter shared exec tsdown` so we get the dist without regenerating any schema-derived sources. Reproduced locally: tsdown builds, sync:template succeeds, biome check stays clean. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> * feat(docs): auto-inject beta banner on plugin docs page from manifest Closes the docs side of the "manifest is the single source of truth" contract. Previously, flipping a plugin's `stability` to `"beta"` updated the runtime export barrel, the synced template manifest, and the API typedoc, but the plugin's hand-written docs page in `docs/docs/plugins/<name>.md` looked identical to a stable plugin's. A new `tools/generate-plugin-doc-banners.ts` reads each `packages/appkit/src/plugins/<name>/manifest.json` and, when stability is non-stable, injects a Docusaurus admonition immediately after the H1: :::warning Beta plugin This plugin is currently **beta**. APIs may change between minor releases. Import from `@databricks/appkit/beta`. See [Plugin Stability Tiers](./stability.md). ::: The block is delimited by marker comments and is fully idempotent: re-runs strip any existing banner first, then re-inject only when stability != "stable". Stable / absent stability removes the banner. Wiring: - New generator + a `generate:plugin-doc-banners` script in root `package.json`. Folded into `pnpm run generate:types` so the existing CI freshness gate covers it. - CI's "Check generated types are up to date" step now also diffs the eight built-in plugin doc pages (analytics, files, genie, jobs, lakebase, server, model-serving, vector-search). A drift between manifest stability and the docs page banner fails the PR. - `appkit plugin promote` (monorepo branch) now runs `pnpm run generate:types` instead of `generate-plugin-entries.ts` alone, so promote keeps both the runtime barrels AND the docs banner in sync after the manifest write. - Doc filename mapping handles the one mismatch (`serving` -> `model-serving.md`) via a small `DOC_FILE_OVERRIDES` table. - Stability docs (`docs/docs/plugins/stability.md`) updated to mention the new docs-side generator alongside the runtime barrels. Verified locally: - `pnpm run generate:types` against canonical state (all stable) writes the barrels and skips every doc page (no banner to add or remove). Working tree stays clean. - Temporarily marking serving as beta -> generator injects the banner into model-serving.md, with the manifest -> doc-file override picking the right file. Reverting -> banner stripped, file byte-identical to the committed version. - All quality gates pass: build, sync:template, check:fix, typecheck, 91 test files, docs:build. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> * fix(build): run plugin doc-banners generator as part of pnpm build The doc-banners generator was only wired into `pnpm run generate:types`, which means a maintainer flipping a plugin's `stability` field and running `pnpm build` (the most common build flow) got the runtime barrels and the synced template manifest updated but NOT the plugin's docs page banner. Discovered by trying it: marking the jobs plugin as beta and running `pnpm build` left `docs/docs/plugins/jobs.md` unchanged — no banner appeared until `pnpm run generate:types` was invoked manually. Append the generator to the root `pnpm build` script so the docs banner follows the manifest on the same flow that handles everything else. The generator is idempotent and fast (sub-100ms for ~7 plugins), so running it on every build has negligible cost. Verified end-to-end: - Mark jobs as beta -> `pnpm build` -> jobs.md gains the `:::warning Beta plugin` admonition immediately after the H1. - Revert manifest -> `pnpm build` -> banner stripped, jobs.md byte-identical to the committed version. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> * fix(plugin): scope promote import rewrite to the targeted plugin Address review feedback on PR #264. ## Comment: rewriteImportsInFile rewrites every beta import, not just the ## promoted one (#264 (comment)...) Pre-fix, the rewriter did: content.split("@databricks/appkit/beta").join("@databricks/appkit") which mangled multi-specifier imports — promoting only `betaA` would move `betaB` along with it onto the stable subpath, where `betaB` doesn't exist: // before import { betaA, betaB } from "@databricks/appkit/beta"; // promote betaA --to stable, pre-fix (BROKEN) import { betaA, betaB } from "@databricks/appkit"; ^^^^^ now resolves to undefined at runtime Now: take `pluginName` as an argument, match the import statement via regex, parse the specifier list, find the targeted plugin (by binding name — handles `name`, `name as alias`, `type name`, and the kebab-to-camelCase manifest convention like `vector-search` -> `vectorSearch`), and either: - Single-specifier import: rewrite the source. - Multi-specifier import: keep remaining specifiers on the original source AND emit a new import line for the promoted specifier from the new source. Imports that don't reference the targeted plugin are left untouched. Eight new unit tests cover: single-specifier rewrite, dry-run preserved, no-op when plugin not in file, multi-specifier split (the reviewer's case), preserves `import type`, matches aliased specifiers on the binding (not the alias), multi-line specifier lists, and multiple packages in the same file rewritten independently. The existing runPromote integration test was rewritten to lock in the contract that unrelated beta imports stay put. ## Comment: redundant `as "beta"` cast in sync.ts; would lie if a ## third tier is added later The cast was unnecessary — narrowing `manifest.stability !== "stable"` on top of a truthy check already produces the non-stable variant (currently `"beta"`). Removed the cast and added a comment explaining the narrowing so a future `"alpha"` tier flows through type-correctly without revisiting this code. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> * refactor(plugin): rename "stable" tier to "ga" Hard rename of the production-ready stability tier from "stable" to "ga" (general availability). Schema enum becomes ["beta", "ga"]; "stable" is no longer a valid manifest value. Why "ga": "stable" was overloaded — every git branch, plugin release, and SDK version is "stable" in some sense. "ga" matches the broader Databricks product vocabulary for the production-ready / semver-strict tier and reads unambiguously alongside "beta". Touched layers (every place "stable" had any meaning is renamed): - Schemas: `enum: ["beta", "stable"]` -> `["beta", "ga"]` in both `plugin-manifest.schema.json` and `template-plugins.schema.json`, with descriptions updated. Default value changes from "stable" to "ga" so absent stability still maps to the production-ready tier. - TypeScript types: `Stability = "beta" | "stable"` -> `"beta" | "ga"` across `manifest-types.ts`, `plugin-manifest.generated.ts`, `promote.ts`, `sync.ts`, `list.ts`, `create.ts`, and the two generators in `tools/`. - Promote command: TIER_ORDER, IMPORT_PATH_MAP, isStability, error messages, validation, --to flag help, and the post-promote generator/sync block. - Sync command: the strip-requiredByTemplate condition now compares against "ga" instead of "stable". - Create command: interactive prompt offers "GA" / "Beta" (label), with values "ga" / "beta". Existing default-omit logic preserved. - Generated barrel: renamed `stable-exports.generated.ts` -> `ga-exports.generated.ts` via `git mv`. `src/index.ts` and the `tools/generate-plugin-entries.ts` writer updated. CI freshness diff list and root `package.json` scripts updated too. - Doc banners generator: only beta plugins get a banner; the GA branch strips any existing banner. No banner is emitted for GA (matches the design — absence of beta = GA, no extra label needed). - Tests: bulk-renamed `to: "stable"` test args to `to: "ga"`, updated `isStability`/TIER_ORDER tests for the new tier name, and extended the legacy-rejection cases so manifests or --to flags carrying "stable" (now legacy), "experimental", or "preview" are all rejected up front. - Stability docs page: tier name updated everywhere; promotion path diagram now reads `beta ──→ ga`; current-plugins-by-tier section says "GA" instead of "Stable". Backwards compat: the schema rejects the legacy "stable" value, so a stale manifest must migrate to "ga" (or omit the field). Built-in plugins never wrote the field explicitly, so no first-party manifest needs editing. Third-party plugins that explicitly committed `"stability": "stable"` will fail validation until they update — this is the "hard rename" the user explicitly chose over a deprecation alias. CLI side (databricks/cli#5090) is intentionally NOT touched here. The CLI hardcodes a "stable" check in `Plugin.StabilityLabel()` to suppress the picker suffix for the default tier. After this rename, that check still suppresses "stable" (now legacy / never written by AppKit) but absent-stability plugins (the new GA default) already render with no suffix because the field is omitted from the JSON. So the CLI keeps working without changes; an explicit "ga" written into a manifest would render as "(ga)" in the picker, which is acceptable for now. A follow-up CLI PR can update the suppression check. Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> * fix(plugin): propagate stability from node_modules sync; harden doc-banner paths Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> * docs(plugins): document sync stability paths and doc-banner name checks Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> --------- Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com> Co-authored-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

MarioCadenas temporarily deployed to test-trigger-is April 27, 2026 10:28 — with GitHub Actions Inactive

MarioCadenas mentioned this pull request Apr 27, 2026

feat(plugin): add stability system (beta/stable) with promote command databricks/appkit#264

Merged

MarioCadenas changed the title ~~Surface plugin stability tier in apps init~~ feat(apps): surface beta plugin tier in apps init Apr 27, 2026

MarioCadenas temporarily deployed to test-trigger-is April 27, 2026 17:37 — with GitHub Actions Inactive

MarioCadenas temporarily deployed to test-trigger-is April 28, 2026 10:47 — with GitHub Actions Inactive

MarioCadenas temporarily deployed to test-trigger-is April 28, 2026 10:55 — with GitHub Actions Inactive

MarioCadenas added 4 commits April 28, 2026 20:33

MarioCadenas force-pushed the mario/573055d1 branch from 8b525ff to 6bd7b5c Compare April 28, 2026 18:35

MarioCadenas temporarily deployed to test-trigger-is April 28, 2026 18:35 — with GitHub Actions Inactive

MarioCadenas marked this pull request as ready for review April 28, 2026 19:12

Merge branch 'main' into mario/573055d1

4a22225

MarioCadenas requested a review from pkosiec April 28, 2026 19:14

MarioCadenas temporarily deployed to test-trigger-is April 28, 2026 19:15 — with GitHub Actions Inactive

MarioCadenas requested review from atilafassina and ditadi and removed request for atilafassina April 28, 2026 19:19

pkosiec approved these changes Apr 30, 2026

View reviewed changes

Merge branch 'main' into mario/573055d1

b1c6488

MarioCadenas temporarily deployed to test-trigger-is April 30, 2026 12:45 — with GitHub Actions Inactive

MarioCadenas temporarily deployed to test-trigger-is April 30, 2026 13:00 — with GitHub Actions Inactive

MarioCadenas enabled auto-merge April 30, 2026 13:10

MarioCadenas disabled auto-merge April 30, 2026 13:22

MarioCadenas enabled auto-merge April 30, 2026 13:35

MarioCadenas disabled auto-merge April 30, 2026 13:36

MarioCadenas enabled auto-merge April 30, 2026 13:37

fjakobs approved these changes Apr 30, 2026

View reviewed changes

fjakobs disabled auto-merge April 30, 2026 14:51

fjakobs merged commit 0fba87d into main Apr 30, 2026
24 of 25 checks passed

fjakobs deleted the mario/573055d1 branch April 30, 2026 14:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(apps): surface beta plugin tier in apps init#5090

feat(apps): surface beta plugin tier in apps init#5090
fjakobs merged 7 commits intomainfrom
mario/573055d1

MarioCadenas commented Apr 27, 2026 •

edited

Loading

Uh oh!

pkosiec left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

MarioCadenas commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

Changes

Test plan

Demo

Uh oh!

pkosiec left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

MarioCadenas commented Apr 27, 2026 •

edited

Loading