{"id":50335601,"url":"https://github.com/databricks-solutions/lakebase-app-dev-kit","last_synced_at":"2026-05-29T13:30:24.994Z","repository":{"id":359840814,"uuid":"1247683065","full_name":"databricks-solutions/lakebase-app-dev-kit","owner":"databricks-solutions","description":"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.","archived":false,"fork":false,"pushed_at":"2026-05-24T21:58:19.000Z","size":662,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T22:22:40.160Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/databricks-solutions.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS.txt","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE.md","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-23T16:31:59.000Z","updated_at":"2026-05-24T21:58:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/databricks-solutions/lakebase-app-dev-kit","commit_stats":null,"previous_names":["databricks-solutions/lakebase-scm-workflows","databricks-solutions/lakebase-app-dev-kit"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/databricks-solutions/lakebase-app-dev-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databricks-solutions%2Flakebase-app-dev-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databricks-solutions%2Flakebase-app-dev-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databricks-solutions%2Flakebase-app-dev-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databricks-solutions%2Flakebase-app-dev-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/databricks-solutions","download_url":"https://codeload.github.com/databricks-solutions/lakebase-app-dev-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databricks-solutions%2Flakebase-app-dev-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33655440,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-29T13:30:24.072Z","updated_at":"2026-05-29T13:30:24.985Z","avatar_url":"https://github.com/databricks-solutions.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lakebase-app-dev-kit\n\nLakebase-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.\n\n**Workflow domains** (kit-authored, one skill each, hosted under `skills/`):\n- **[`lakebase-scm-workflows`](skills/lakebase-scm-workflows/README.md)** – paired-branch source control, schema diff, PR flow, runner setup.\n- **[`lakebase-release-workflows`](skills/lakebase-release-workflows/SKILL.md)** – branching + release methodology for Lakebase-paired projects.\n- **[`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.\n- Future domains include deploying to Databricks Apps and beyond.\n\n**Shared canon** (kit-authored, unprefixed because not Lakebase-specific):\n- **[`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.\n\n**Vendored upstream skills** (also under `skills/`, synced from [`databricks/devhub`](https://github.com/databricks/devhub/tree/main/.agents/skills)):\n- **[`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`.\n- **[`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`).\n\nThe 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.\n\nThe \"app dev\" framing covers applications, services, libraries, and any other software that uses Lakebase – including projects deployed to Databricks Apps.\n\n## What this is\n\n- **`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.\n- **`skills/\u003cdomain\u003e/SKILL.md`** – Per-workflow-domain agent surface. A coding agent reads this and drives the same scripts the extension does.\n- **`apps/mcp-server/`** – Single MCP server exposing every skill's tools to MCP-capable agents (Claude Desktop, OpenAI Codex, Cursor-via-MCP).\n- **`tools/openai-foundry/`** – Pre-rendered OpenAI Foundry / Codex tool spec covering the same tool surface.\n- **`templates/`** – Project templates the kit ships into newly-bootstrapped Lakebase-paired projects.\n- **`tests/`** – Vitest BDD tests. Live Lakebase paths skip cleanly when `LAKEBASE_TEST_*` env vars aren't set.\n\n## Single-seam credential handoff\n\nTwo narrow auth seams, both enforced by CI grep guards:\n\n- **`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).\n- **`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).\n\n## Install\n\nFor agent use (running `node scripts/lakebase/\u003cverb\u003e.js` directly):\n\n```bash\ngit clone https://github.com/databricks-solutions/lakebase-app-dev-kit\ncd lakebase-app-dev-kit\nnpm install   # prepare script builds dist/\n```\n\nFor 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:\n\n```jsonc\n// host package.json\n\"dependencies\": {\n  \"@databricks-solutions/lakebase-app-dev-kit\":\n    \"github:databricks-solutions/lakebase-app-dev-kit#\u003ccommit-sha-or-tag\u003e\"\n}\n```\n\nPin to a sha for reproducibility. `prepare` builds `dist/` on install.\n\n### For coding agents\n\n`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).\n\n```bash\n# Auto-detect installed agents, prompt to pick\nbash \u003c(curl -sL https://raw.githubusercontent.com/databricks-solutions/lakebase-app-dev-kit/main/install.sh)\n\n# Specific targets\n./install.sh --tools claude,cursor\n\n# Upload skill into a Databricks workspace for Genie Code\n./install.sh --install-to-genie --profile DEFAULT\n```\n\nSupported 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).\n\nThe 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.\n\n`@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.\n\n`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).\n\n## Imports\n\n```ts\nimport { resolveGitHubToken } from \"@databricks-solutions/lakebase-app-dev-kit/github\";\nimport { getConnection, createBranch, deleteBranch } from \"@databricks-solutions/lakebase-app-dev-kit/lakebase\";\nimport { commitAndPush } from \"@databricks-solutions/lakebase-app-dev-kit/git\";\n```\n\nThe 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.\n\n## CLIs\n\nThe package exposes six bins (resolved relative to `node_modules/.bin/` when installed):\n\n- `lakebase-get-connection` – mint a DSN or pg.Pool against a branch\n- `lakebase-schema-diff` – parent-aware schema diff between two Lakebase branches\n- `lakebase-github-token` – print/diagnose the resolved GitHub token\n- `lakebase-create-project` – end-to-end Lakebase-paired project bootstrap\n- `lakebase-migrate` – apply / rollback / status / list schema migrations against a branch\n- `lakebase-mcp-server` – stdio MCP server exposing the tool registry\n\n## Contributing\n\nMaintainer-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).\n\n## Support\n\nDatabricks 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.\n\n## License\n\nSee [LICENSE.md](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabricks-solutions%2Flakebase-app-dev-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatabricks-solutions%2Flakebase-app-dev-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabricks-solutions%2Flakebase-app-dev-kit/lists"}