https://github.com/databricks-solutions/lakebase-app-dev-kit
Opinionated git-Lakebase branch-pairing workflows. Shared executable surface for the lakebase-scm-extension (VS Code/Cursor) and coding agents — Claude Code, Claude Desktop, OpenAI Foundry, Cursor, Databricks Genie Code.
https://github.com/databricks-solutions/lakebase-app-dev-kit
Last synced: 15 days ago
JSON representation
Opinionated git-Lakebase branch-pairing workflows. Shared executable surface for the lakebase-scm-extension (VS Code/Cursor) and coding agents — Claude Code, Claude Desktop, OpenAI Foundry, Cursor, Databricks Genie Code.
- Host: GitHub
- URL: https://github.com/databricks-solutions/lakebase-app-dev-kit
- Owner: databricks-solutions
- License: other
- Created: 2026-05-23T16:31:59.000Z (21 days ago)
- Default Branch: main
- Last Pushed: 2026-05-24T21:58:19.000Z (20 days ago)
- Last Synced: 2026-05-24T22:22:40.160Z (20 days ago)
- Language: TypeScript
- Size: 646 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS.txt
- Security: SECURITY.md
- Notice: NOTICE.md
Awesome Lists containing this project
README
# lakebase-app-dev-kit
Lakebase-backed application development kit. The shared foundation that the [`lakebase-scm-extension`](https://github.com/databricks-solutions/lakebase-scm-extension) (VS Code/Cursor) and coding agents – Claude Code (terminal), Claude Desktop, OpenAI Foundry, Cursor, and Databricks Genie Code – all consume. One canonical implementation; multiple presentation layers and workflow-domain skills.
**Workflow domains** (kit-authored, one skill each, hosted under `skills/`):
- **[`lakebase-scm-workflows`](skills/lakebase-scm-workflows/README.md)** – paired-branch source control, schema diff, PR flow, runner setup.
- **[`lakebase-release-workflows`](skills/lakebase-release-workflows/SKILL.md)** – branching + release methodology for Lakebase-paired projects.
- **[`lakebase-tdd-workflows`](skills/lakebase-tdd-workflows/README.md)** – test-driven development against paired branches, with a Scrum-Master orchestrator and HITL gates at every phase boundary.
- Future domains include deploying to Databricks Apps and beyond.
**Shared canon** (kit-authored, unprefixed because not Lakebase-specific):
- **[`software-design-principles`](skills/software-design-principles/SKILL.md)** – SOLID, DRY, DTSTTCPW, clean code, layered architecture, cross-cutting concerns, NFRs. Imported by the workflow domain skills.
**Vendored upstream skills** (also under `skills/`, synced from [`databricks/devhub`](https://github.com/databricks/devhub/tree/main/.agents/skills)):
- **[`databricks-core`](https://github.com/databricks/devhub/blob/main/.agents/skills/databricks-core/SKILL.md)** – CLI basics, authentication, profile selection. Parent skill referenced by `databricks-lakebase`.
- **[`databricks-lakebase`](https://github.com/databricks/devhub/blob/main/.agents/skills/databricks-lakebase/SKILL.md)** – canonical agent reference for the `databricks postgres` CLI surface (project / branch / endpoint / database resource shapes, name formats, "never delete the production branch" rule, discovery via `-h`).
The vendored skills are read-only mirrors of upstream. To pull the latest, run `bash scripts/sync-devhub-skills.sh` and commit any diff in a focused PR. Kit-authored skills wrap the operations; vendored skills document the CLI surface those operations are built on. Agents that consume the kit (e.g. via `install.sh`) inherit both layers.
The "app dev" framing covers applications, services, libraries, and any other software that uses Lakebase – including projects deployed to Databricks Apps.
## What this is
- **`scripts/`** – Node/TypeScript modules that implement the operations: GitHub auth + repo + runner + secrets, Lakebase get-connection + branch lifecycle + schema-diff + create-project + scaffold, git wrappers, and shared utilities. Each has CLI and module entry points.
- **`skills//SKILL.md`** – Per-workflow-domain agent surface. A coding agent reads this and drives the same scripts the extension does.
- **`apps/mcp-server/`** – Single MCP server exposing every skill's tools to MCP-capable agents (Claude Desktop, OpenAI Codex, Cursor-via-MCP).
- **`tools/openai-foundry/`** – Pre-rendered OpenAI Foundry / Codex tool spec covering the same tool surface.
- **`templates/`** – Project templates the kit ships into newly-bootstrapped Lakebase-paired projects.
- **`tests/`** – Vitest BDD tests. Live Lakebase paths skip cleanly when `LAKEBASE_TEST_*` env vars aren't set.
## Single-seam credential handoff
Two narrow auth seams, both enforced by CI grep guards:
- **`scripts/lakebase/get-connection.ts`** is the only path that mints Lakebase credentials. Every other workflow op calls `getConnection()`. See [skills/lakebase-scm-workflows/references/get-connection.md](skills/lakebase-scm-workflows/references/get-connection.md).
- **`scripts/github/auth.ts`** is the only path that resolves a GitHub token. Fallback chain: `GITHUB_TOKEN` env → VS Code `getSession` (in the extension host only) → `gh auth token`. See [skills/lakebase-scm-workflows/references/github-auth.md](skills/lakebase-scm-workflows/references/github-auth.md).
## Install
For agent use (running `node scripts/lakebase/.js` directly):
```bash
git clone https://github.com/databricks-solutions/lakebase-app-dev-kit
cd lakebase-app-dev-kit
npm install # prepare script builds dist/
```
For a JS/TS host (extension, Node service) that imports substrate functions, depend on this repo via a git URL. npm publish is gated on org/scope/runner questions and intentionally deferred:
```jsonc
// host package.json
"dependencies": {
"@databricks-solutions/lakebase-app-dev-kit":
"github:databricks-solutions/lakebase-app-dev-kit#"
}
```
Pin to a sha for reproducibility. `prepare` builds `dist/` on install.
### For coding agents
`install.sh` at the repo root copies the canonical `skills/lakebase-scm-workflows/` tree into the path each agent reads from. Auto-detects installed agents; `--tools` overrides. Mirrors the pattern in [`databricks-solutions/ai-dev-kit`](https://github.com/databricks-solutions/ai-dev-kit).
```bash
# Auto-detect installed agents, prompt to pick
bash <(curl -sL https://raw.githubusercontent.com/databricks-solutions/lakebase-app-dev-kit/main/install.sh)
# Specific targets
./install.sh --tools claude,cursor
# Upload skill into a Databricks workspace for Genie Code
./install.sh --install-to-genie --profile DEFAULT
```
Supported targets today: **Claude Code (terminal)** via `.claude/skills/`, **Cursor** via `.cursor/skills/`, and **Databricks Genie Code** via workspace upload. **Claude Desktop / OpenAI Codex** consume the same surface via the MCP manifest at `.mcp.json` – the server lives at `apps/mcp-server/` (built to `dist/apps/mcp-server/index.js`, also exposed as the `lakebase-mcp-server` bin). **OpenAI Foundry** consumes a pre-rendered tool-spec JSON at [`tools/openai-foundry/lakebase-app-dev-kit.tools.json`](tools/openai-foundry/lakebase-app-dev-kit.tools.json), regenerated by `python3 scripts/openai-foundry.py` from the same `apps/mcp-server/tools.ts` registry. Per-agent display metadata for OpenAI runtimes lives at `skills/lakebase-scm-workflows/agents/openai.yaml` (dev-hub convention).
The MCP server and the Foundry tool-spec generator are two presentations of one source: `apps/mcp-server/tools.ts`. Drift between them is caught by `python3 scripts/openai-foundry.py validate` in CI.
`@modelcontextprotocol/sdk` is declared as an **optional peer dependency** of this package, not a regular `dependency`. Consumers that only import the substrate's TypeScript modules (like `lakebase-scm-extension`) won't drag the MCP runtime into their `node_modules`. Anyone running the `lakebase-mcp-server` bin from a dev clone gets it via `devDependencies`; standalone bin users install it into their own project.
`manifest.json` at the repo root is a machine-readable index of every skill + its files, regenerated by `python3 scripts/skills.py` (validate in CI with `python3 scripts/skills.py validate`). Matches the shape used by [`databricks/databricks-agent-skills`](https://github.com/databricks/databricks-agent-skills).
## Imports
```ts
import { resolveGitHubToken } from "@databricks-solutions/lakebase-app-dev-kit/github";
import { getConnection, createBranch, deleteBranch } from "@databricks-solutions/lakebase-app-dev-kit/lakebase";
import { commitAndPush } from "@databricks-solutions/lakebase-app-dev-kit/git";
```
The root barrel `@databricks-solutions/lakebase-app-dev-kit` re-exports everything; sub-paths (`/github`, `/lakebase`, `/git`, `/util`) and individual modules (`/lakebase/branch-create`, etc.) are also exposed via the `exports` map.
## CLIs
The package exposes six bins (resolved relative to `node_modules/.bin/` when installed):
- `lakebase-get-connection` – mint a DSN or pg.Pool against a branch
- `lakebase-schema-diff` – parent-aware schema diff between two Lakebase branches
- `lakebase-github-token` – print/diagnose the resolved GitHub token
- `lakebase-create-project` – end-to-end Lakebase-paired project bootstrap
- `lakebase-migrate` – apply / rollback / status / list schema migrations against a branch
- `lakebase-mcp-server` – stdio MCP server exposing the tool registry
## Contributing
Maintainer-facing docs (development setup, build, test tiers, the single-seam contributor rule, release flow, and the pull-request checklist) live in [`CONTRIBUTING.md`](./CONTRIBUTING.md).
## Support
Databricks does not offer official support for content in this repository. For questions or bugs, please open a GitHub issue and the team will help on a best-effort basis.
## License
See [LICENSE.md](LICENSE.md).