Skip to content

feat(cli): add appkit doctor command - #489

Open
IamGalymzhan wants to merge 3 commits into
mainfrom
feat/doctor-command
Open

feat(cli): add appkit doctor command#489
IamGalymzhan wants to merge 3 commits into
mainfrom
feat/doctor-command

Conversation

@IamGalymzhan

@IamGalymzhan IamGalymzhan commented Jul 23, 2026

Copy link
Copy Markdown
Collaborator

appkit doctor - cli command that checks connectivity to the Databricks resources

The command does three level of checks:

  1. auth - validates DATABRICKS_HOST and authenticates to the workspace
  2. config - validates that each needed environmental variable is present (e.g. warehouse_id, genie_space_id)
  3. existence - checks that given resource exists and reachable by read requests ( .get() or SELECT 1) to check connection

Output is a list of resources and problems if any with hints. Also there is option --json for machine readable output.

Examples:

Failed auth

image

Genie Space is not provided, Job is not accessible or doesn't exists

image

Everything is setup correctly

image

How it works:

  1. Resolve all resources needed for the app from appkit.plugins.json
  2. Auth: calls currentUser.me() to check that auth is fine
  3. Config: for each resource declared checks that corresponding environmental variable is present
  4. Existence: for each resource declared tries to connect and check if resource exists / has permission to access
  5. Print a report for user or for the agent with --json option

@github-actions

Copy link
Copy Markdown
Contributor

🔬  Run evals on this PR  ·  Go to Evals Monitor →

@github-actions

github-actions Bot commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

📦 Bundle size report

Compared against bundle-size-baseline.json (main).

✅ No size changes vs the baseline.

@databricks/appkit

npm tarball (packed): 763 KB — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist raw gzip
JS (runtime) 791 KB 276 KB
Type declarations 285 KB 97 KB
Source maps 1.5 MB 515 KB
Other 11 KB 3.7 KB
Total 2.6 MB 892 KB
Per-entry composition (own code — deps external (as shipped))
Entry Initial (gz) Lazy (gz) Total (gz) node_modules (min) Own code (min)
. 86 KB 2.5 KB 89 KB external 281 KB
./beta 40 KB 231 B 40 KB external 119 KB
./type-generator 19 KB 0 B 19 KB external 54 KB

Chunks:

Entry Chunk Load Size (gz)
. index.js initial 82 KB
. utils.js initial 4.0 KB
. remote-tunnel-manager.js lazy 2.5 KB
./beta beta.js initial 30 KB
./beta databricks.js initial 5.8 KB
./beta service-context.js initial 3.2 KB
./beta client-options.js initial 220 B
./beta databricks.js lazy 128 B
./beta index.js lazy 103 B
./type-generator index.js initial 19 KB

@databricks/appkit-ui

npm tarball (packed): 305 KB — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist raw gzip
JS (runtime) 359 KB 119 KB
Type declarations 205 KB 74 KB
Source maps 685 KB 224 KB
CSS 16 KB 3.3 KB
Total 1.2 MB 421 KB
Per-entry composition (consumer bundle — deps bundled, peerDeps external)
Entry Initial (gz) Lazy (gz) Total (gz) node_modules (min) Own code (min)
./js 4.3 KB 49 KB 54 KB 208 KB 12 KB
./js/beta 20 B 0 B 20 B 0 B 0 B
./react 429 KB 49 KB 478 KB 1.3 MB 168 KB
./react/beta 20 B 0 B 20 B 0 B 0 B

Chunks:

Entry Chunk Load Size (gz)
./js index.js initial 4.2 KB
./js chunk initial 120 B
./js apache-arrow lazy 49 KB
./js/beta beta.js initial 20 B
./react index.js initial 427 KB
./react tslib initial 2.1 KB
./react apache-arrow lazy 49 KB
./react/beta beta.js initial 20 B

Diagnose whether an AppKit app's declared Databricks resources are actually
usable, beyond the startup env-var check. Registered as `appkit doctor`.

Three layers per resource:
- auth: validate DATABRICKS_HOST, then currentUser.me() (once, app-wide)
- config: offline env-var presence check
- existence: live per-type probe — control-plane .get() for warehouse,
  serving, genie, job, volume, vector index, uc_function; a real SELECT 1
  connection for Lakebase/postgres. Errors are classified (NOT_FOUND,
  INVALID_VALUE, ACCESS_DENIED) with clean one-line messages.

Actionable hints translate opaque failures into the fix: expired/missing
credentials to the right `databricks auth login`, a serving endpoint keyed by
id to its name, and a Lakebase auth failure to the PGUSER/identity mismatch.

Reaches the Databricks SDK / @databricks/appkit only through a runtime
import in databricks-client.ts, keeping the SDK-free shared package free of
the dependency and degrading gracefully when it is absent.

Output is a friendly list (errors first; plugin/type + reason shown only on
rows needing attention) or --json; exit code is non-zero on any error so it
can gate CI.

Signed-off-by: Galymzhan <zhangazy2004@gmail.com>
@IamGalymzhan
IamGalymzhan force-pushed the feat/doctor-command branch from 8907117 to 0744f9a Compare July 24, 2026 11:24
@github-actions

github-actions Bot commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

🤖 AppKit PR bot

🔬 Run evals

Start an eval for this PR from the evals-monitor app: Go to Evals Monitor →

📦 Try this PR's app template

Scaffolds a new app from this PR's SDK build. Run it in any folder (requires the GitHub CLI — gh auth login — and the Databricks CLI):

gh run download 30265331104 -R databricks/appkit -n appkit-template-0.48.0-pr.1d287a9-feat-doctor-command-489 -D appkit-pr-489 \
  && unzip -o "appkit-pr-489/appkit-template-0.48.0-pr.1d287a9-feat-doctor-command-489.zip" -d "appkit-pr-489" \
  && databricks apps init --template "appkit-pr-489"

The template pins @databricks/appkit and @databricks/appkit-ui to tarballs built from this branch, so the scaffolded app runs against this PR's code.

@IamGalymzhan
IamGalymzhan force-pushed the feat/doctor-command branch from fc846c6 to 1dde6f9 Compare July 27, 2026 09:40
Signed-off-by: Galymzhan <zhangazy2004@gmail.com>
@IamGalymzhan
IamGalymzhan force-pushed the feat/doctor-command branch from 1dde6f9 to 7569c08 Compare July 27, 2026 09:55
Run existence probes concurrently via Promise.all (independent network
reads; input order preserved), cache DATABRICKS_HOST in a local, and drop
a redundant `unknown | undefined` parameter type.

Signed-off-by: Galymzhan <zhangazy2004@gmail.com>
@IamGalymzhan
IamGalymzhan marked this pull request as ready for review July 27, 2026 13:13
@IamGalymzhan
IamGalymzhan requested a review from a team as a code owner July 27, 2026 13:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant