diff --git a/src/apx/templates/addons/claude/.mcp.json b/src/apx/templates/addons/claude/.mcp.json index d97a0e70..820ec2f7 100644 --- a/src/apx/templates/addons/claude/.mcp.json +++ b/src/apx/templates/addons/claude/.mcp.json @@ -1,16 +1,12 @@ { "mcpServers": { - "shadcn": { - "command": "bun", - "args": ["x", "--bun", "shadcn@latest", "mcp"] - }, "apx": { "command": "uv", - "args": ["run", "apx", "dev", "mcp"] + "args": ["run", "apx", "mcp"] }, "playwright": { - "command": "bun", - "args": ["x", "--bun", "@playwright/mcp@latest"] + "command": "uv", + "args": ["run", "apx", "bun", "x", "--bun", "@playwright/mcp@latest"] } } } diff --git a/src/apx/templates/addons/claude/CLAUDE.md.jinja2 b/src/apx/templates/addons/claude/CLAUDE.md.jinja2 index 672d9bb4..d6ceb438 100644 --- a/src/apx/templates/addons/claude/CLAUDE.md.jinja2 +++ b/src/apx/templates/addons/claude/CLAUDE.md.jinja2 @@ -1,18 +1,19 @@ # Do's and Don'ts -- If the apx development servers are started, don't regenerate the OpenAPI client. -- Prefer running apx related commands via mcp server if it's available. -- Prefer to add new components via shadcn mcp server if it's available. +- OpenAPI client auto-regenerates on code changes when dev servers are running - don't manually regenerate. +- Prefer running apx related commands via MCP server if it's available. +- Use the apx MCP `search_registry_components` and `add_component` tools to find and add shadcn/ui components. - When using the API calls on the frontend, use error boundaries to handle errors. -- Run apx dev check command (via CLI) to check for errors in the project code after making changes. -- If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright mcp to automate browser actions (e.g. screenshots, clicks, etc.). -- **Databricks SDK:** Use the apx MCP tools (`search_databricks_sdk`, `get_method_spec`, `get_model_spec`) to look up Databricks SDK methods and models instead of guessing or hallucinating API signatures. +- Run `apx dev check` command (via CLI or MCP) to check for errors in the project code after making changes. +- If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright MCP to automate browser actions (e.g. screenshots, clicks, etc.). +- **Databricks SDK:** Use the apx MCP `docs` tool to search Databricks SDK documentation instead of guessing or hallucinating API signatures. ## Package Management -- **Frontend:** Always use `bun` (never `npm`) +- **Frontend:** Bun might not be present on user's $PATH. It's recommended to use prebundled bun (e.g., `uv run apx bun install` or `uv run apx bun add `), unless user explicitly stated otherwise. - **Python:** Always use `uv` (never `pip`) ## Component Management -- **Adding components:** When adding a new component via CLI command, always add `--yes` flag to skip confirmation +- **Finding components:** Use MCP `search_registry_components` to search for available shadcn/ui components +- **Adding components:** Use MCP `add_component` or CLI `uv run apx components add --yes` to add components - **Component location:** If component was added to a wrong location (e.g. stored into `src/components` instead of `src/{{app_name}}/ui/components`), move it to the proper folder - **Component organization:** Prefer grouping components by functionality rather than by file type (e.g. `src/{{app_name}}/ui/components/chat/`) @@ -42,12 +43,16 @@ uv run apx dev start uv run apx dev status ``` -**View logs** (stored in `~/.apx/{app_id}/logs/`): +**Check for errors** (TypeScript, Python linting): ```bash -uv run apx dev logs # All logs -uv run apx dev logs --ui # Frontend only -uv run apx dev logs --backend # Backend only -uv run apx dev tail # Live stream +uv run apx dev check +``` + +**View logs:** +```bash +uv run apx dev logs # Recent logs (default: last 10m) +uv run apx dev logs -d 1h # Logs from last hour +uv run apx dev logs -f # Follow/stream logs live ``` **Stop servers:** @@ -60,10 +65,22 @@ uv run apx dev stop uv run apx build ``` -**OpenAPI generation** (auto-runs with `dev start`): -```bash -uv run apx openapi # Generate once -uv run apx openapi --watch # Watch mode -``` +**Note:** OpenAPI client is automatically regenerated on every code change when dev servers are running. No manual regeneration needed. + +## MCP Tools Reference + +When the apx MCP server is available, use these tools: -**Note:** The OpenAPI watcher runs automatically with `dev start`. Manual generation is rarely needed. \ No newline at end of file +| Tool | Description | +|------|-------------| +| `start` | Start development server and return the URL | +| `stop` | Stop the development server | +| `restart` | Restart the development server (preserves port if possible) | +| `logs` | Fetch recent dev server logs | +| `check` | Check project code for errors (runs tsc and ty checks in parallel) | +| `refresh_openapi` | Regenerate OpenAPI schema and API client | +| `search_registry_components` | Search shadcn registry components using semantic search | +| `add_component` | Add a component to the project | +| `docs` | Search Databricks SDK documentation for code examples and API references | +| `databricks_apps_logs` | Fetch logs from deployed Databricks app using Databricks CLI | +| `get_route_info` | Get code example for using a specific API route | diff --git a/src/apx/templates/addons/codex/AGENTS.md.jinja2 b/src/apx/templates/addons/codex/AGENTS.md.jinja2 index 672d9bb4..d6ceb438 100644 --- a/src/apx/templates/addons/codex/AGENTS.md.jinja2 +++ b/src/apx/templates/addons/codex/AGENTS.md.jinja2 @@ -1,18 +1,19 @@ # Do's and Don'ts -- If the apx development servers are started, don't regenerate the OpenAPI client. -- Prefer running apx related commands via mcp server if it's available. -- Prefer to add new components via shadcn mcp server if it's available. +- OpenAPI client auto-regenerates on code changes when dev servers are running - don't manually regenerate. +- Prefer running apx related commands via MCP server if it's available. +- Use the apx MCP `search_registry_components` and `add_component` tools to find and add shadcn/ui components. - When using the API calls on the frontend, use error boundaries to handle errors. -- Run apx dev check command (via CLI) to check for errors in the project code after making changes. -- If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright mcp to automate browser actions (e.g. screenshots, clicks, etc.). -- **Databricks SDK:** Use the apx MCP tools (`search_databricks_sdk`, `get_method_spec`, `get_model_spec`) to look up Databricks SDK methods and models instead of guessing or hallucinating API signatures. +- Run `apx dev check` command (via CLI or MCP) to check for errors in the project code after making changes. +- If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright MCP to automate browser actions (e.g. screenshots, clicks, etc.). +- **Databricks SDK:** Use the apx MCP `docs` tool to search Databricks SDK documentation instead of guessing or hallucinating API signatures. ## Package Management -- **Frontend:** Always use `bun` (never `npm`) +- **Frontend:** Bun might not be present on user's $PATH. It's recommended to use prebundled bun (e.g., `uv run apx bun install` or `uv run apx bun add `), unless user explicitly stated otherwise. - **Python:** Always use `uv` (never `pip`) ## Component Management -- **Adding components:** When adding a new component via CLI command, always add `--yes` flag to skip confirmation +- **Finding components:** Use MCP `search_registry_components` to search for available shadcn/ui components +- **Adding components:** Use MCP `add_component` or CLI `uv run apx components add --yes` to add components - **Component location:** If component was added to a wrong location (e.g. stored into `src/components` instead of `src/{{app_name}}/ui/components`), move it to the proper folder - **Component organization:** Prefer grouping components by functionality rather than by file type (e.g. `src/{{app_name}}/ui/components/chat/`) @@ -42,12 +43,16 @@ uv run apx dev start uv run apx dev status ``` -**View logs** (stored in `~/.apx/{app_id}/logs/`): +**Check for errors** (TypeScript, Python linting): ```bash -uv run apx dev logs # All logs -uv run apx dev logs --ui # Frontend only -uv run apx dev logs --backend # Backend only -uv run apx dev tail # Live stream +uv run apx dev check +``` + +**View logs:** +```bash +uv run apx dev logs # Recent logs (default: last 10m) +uv run apx dev logs -d 1h # Logs from last hour +uv run apx dev logs -f # Follow/stream logs live ``` **Stop servers:** @@ -60,10 +65,22 @@ uv run apx dev stop uv run apx build ``` -**OpenAPI generation** (auto-runs with `dev start`): -```bash -uv run apx openapi # Generate once -uv run apx openapi --watch # Watch mode -``` +**Note:** OpenAPI client is automatically regenerated on every code change when dev servers are running. No manual regeneration needed. + +## MCP Tools Reference + +When the apx MCP server is available, use these tools: -**Note:** The OpenAPI watcher runs automatically with `dev start`. Manual generation is rarely needed. \ No newline at end of file +| Tool | Description | +|------|-------------| +| `start` | Start development server and return the URL | +| `stop` | Stop the development server | +| `restart` | Restart the development server (preserves port if possible) | +| `logs` | Fetch recent dev server logs | +| `check` | Check project code for errors (runs tsc and ty checks in parallel) | +| `refresh_openapi` | Regenerate OpenAPI schema and API client | +| `search_registry_components` | Search shadcn registry components using semantic search | +| `add_component` | Add a component to the project | +| `docs` | Search Databricks SDK documentation for code examples and API references | +| `databricks_apps_logs` | Fetch logs from deployed Databricks app using Databricks CLI | +| `get_route_info` | Get code example for using a specific API route | diff --git a/src/apx/templates/addons/cursor/.cursor/mcp.json b/src/apx/templates/addons/cursor/.cursor/mcp.json index 2faeb603..1e6a8d33 100644 --- a/src/apx/templates/addons/cursor/.cursor/mcp.json +++ b/src/apx/templates/addons/cursor/.cursor/mcp.json @@ -1,12 +1,8 @@ { "mcpServers": { - "shadcn": { - "command": "bun", - "args": ["x", "--bun", "shadcn@latest", "mcp"] - }, "apx": { "command": "uv", - "args": ["run", "apx", "dev", "mcp"] + "args": ["run", "apx", "mcp"] } } } diff --git a/src/apx/templates/addons/cursor/.cursor/rules/project.mdc.jinja2 b/src/apx/templates/addons/cursor/.cursor/rules/project.mdc.jinja2 index 08408267..05f82e8e 100644 --- a/src/apx/templates/addons/cursor/.cursor/rules/project.mdc.jinja2 +++ b/src/apx/templates/addons/cursor/.cursor/rules/project.mdc.jinja2 @@ -5,21 +5,22 @@ alwaysApply: true # Cursor Agent Rules # Do's and Don'ts -- If the apx development servers are started and running, don't regenerate the OpenAPI client. -- Prefer running apx related commands via mcp server if it's available. -- Prefer to add new components via shadcn mcp server if it's available. +- OpenAPI client auto-regenerates on code changes when dev servers are running - don't manually regenerate. +- Prefer running apx related commands via MCP server if it's available. +- Use the apx MCP `search_registry_components` and `add_component` tools to find and add shadcn/ui components. - When using the API calls on the frontend, use error boundaries to handle errors. -- Run apx dev check command (via CLI or via mcp) to check for errors in the project code after making changes. -- If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright mcp to automate browser actions (e.g. screenshots, clicks, etc.). +- Run `apx dev check` command (via CLI or MCP) to check for errors in the project code after making changes. +- If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright MCP to automate browser actions (e.g. screenshots, clicks, etc.). - Avoid unnecessary restarts of the development servers -- **Databricks SDK:** Use the apx MCP tools (`search_databricks_sdk`, `get_method_spec`, `get_model_spec`) to look up Databricks SDK methods and models instead of guessing or hallucinating API signatures. +- **Databricks SDK:** Use the apx MCP `docs` tool to search Databricks SDK documentation instead of guessing or hallucinating API signatures. ## Package Management -- **Frontend:** Always use `bun` (never `npm`) +- **Frontend:** Bun might not be present on user's $PATH. It's recommended to use prebundled bun (e.g., `uv run apx bun install` or `uv run apx bun add `), unless user explicitly stated otherwise. - **Python:** Always use `uv` (never `pip`) ## Component Management -- **Adding components:** When adding a new component via CLI command, always add `--yes` flag to skip confirmation +- **Finding components:** Use MCP `search_registry_components` to search for available shadcn/ui components +- **Adding components:** Use MCP `add_component` or CLI `uv run apx components add --yes` to add components - **Component location:** If component was added to a wrong location (e.g. stored into `src/components` instead of `src/{{app_name}}/ui/components`), move it to the proper folder - **Component organization:** Prefer grouping components by functionality rather than by file type (e.g. `src/{{app_name}}/ui/components/chat/`) @@ -50,12 +51,16 @@ uv run apx dev start uv run apx dev status ``` -**View logs** (stored in `~/.apx/{app_id}/logs/`): +**Check for errors** (TypeScript, Python linting): ```bash -uv run apx dev logs # All logs -uv run apx dev logs --ui # Frontend only -uv run apx dev logs --backend # Backend only -uv run apx dev tail # Live stream +uv run apx dev check +``` + +**View logs:** +```bash +uv run apx dev logs # Recent logs (default: last 10m) +uv run apx dev logs -d 1h # Logs from last hour +uv run apx dev logs -f # Follow/stream logs live ``` **Stop servers:** @@ -68,10 +73,22 @@ uv run apx dev stop uv run apx build ``` -**OpenAPI generation** (auto-runs on each change with `dev start`): -```bash -uv run apx openapi # Generate once -uv run apx openapi --watch # Watch mode -``` - -**Note:** The OpenAPI watcher runs automatically with `dev start`. Manual generation is rarely needed. \ No newline at end of file +**Note:** OpenAPI client is automatically regenerated on every code change when dev servers are running. No manual regeneration needed. + +## MCP Tools Reference + +When the apx MCP server is available, use these tools: + +| Tool | Description | +|------|-------------| +| `start` | Start development server and return the URL | +| `stop` | Stop the development server | +| `restart` | Restart the development server (preserves port if possible) | +| `logs` | Fetch recent dev server logs | +| `check` | Check project code for errors (runs tsc and ty checks in parallel) | +| `refresh_openapi` | Regenerate OpenAPI schema and API client | +| `search_registry_components` | Search shadcn registry components using semantic search | +| `add_component` | Add a component to the project | +| `docs` | Search Databricks SDK documentation for code examples and API references | +| `databricks_apps_logs` | Fetch logs from deployed Databricks app using Databricks CLI | +| `get_route_info` | Get code example for using a specific API route | diff --git a/src/apx/templates/addons/vscode/.github/instructions/project.md.jinja2 b/src/apx/templates/addons/vscode/.github/instructions/project.md.jinja2 index 8c185749..3316dbf1 100644 --- a/src/apx/templates/addons/vscode/.github/instructions/project.md.jinja2 +++ b/src/apx/templates/addons/vscode/.github/instructions/project.md.jinja2 @@ -5,20 +5,21 @@ alwaysApply: true # Copilot Rules # Do's and Don'ts -- If the apx development servers are started, don't regenerate the OpenAPI client. -- Prefer running apx related commands via mcp server if it's available. -- Prefer to add new components via shadcn mcp server if it's available. +- OpenAPI client auto-regenerates on code changes when dev servers are running - don't manually regenerate. +- Prefer running apx related commands via MCP server if it's available. +- Use the apx MCP `search_registry_components` and `add_component` tools to find and add shadcn/ui components. - When using the API calls on the frontend, use error boundaries to handle errors. -- Run apx dev check command (via CLI) to check for errors in the project code after making changes. -- If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright mcp to automate browser actions (e.g. screenshots, clicks, etc.). -- **Databricks SDK:** Use the apx MCP tools (`search_databricks_sdk`, `get_method_spec`, `get_model_spec`) to look up Databricks SDK methods and models instead of guessing or hallucinating API signatures. +- Run `apx dev check` command (via CLI or MCP) to check for errors in the project code after making changes. +- If agent has access to native browser tool, use it to verify changes on the frontend. If such tool is not present or is not working, use playwright MCP to automate browser actions (e.g. screenshots, clicks, etc.). +- **Databricks SDK:** Use the apx MCP `docs` tool to search Databricks SDK documentation instead of guessing or hallucinating API signatures. ## Package Management -- **Frontend:** Always use `bun` (never `npm`) +- **Frontend:** Bun might not be present on user's $PATH. It's recommended to use prebundled bun (e.g., `uv run apx bun install` or `uv run apx bun add `), unless user explicitly stated otherwise. - **Python:** Always use `uv` (never `pip`) ## Component Management -- **Adding components:** When adding a new component via CLI command, always add `--yes` flag to skip confirmation +- **Finding components:** Use MCP `search_registry_components` to search for available shadcn/ui components +- **Adding components:** Use MCP `add_component` or CLI `uv run apx components add --yes` to add components - **Component location:** If component was added to a wrong location (e.g. stored into `src/components` instead of `src/{{app_name}}/ui/components`), move it to the proper folder - **Component organization:** Prefer grouping components by functionality rather than by file type (e.g. `src/{{app_name}}/ui/components/chat/`) @@ -48,12 +49,16 @@ uv run apx dev start uv run apx dev status ``` -**View logs** (stored in `~/.apx/{app_id}/logs/`): +**Check for errors** (TypeScript, Python linting): ```bash -uv run apx dev logs # All logs -uv run apx dev logs --ui # Frontend only -uv run apx dev logs --backend # Backend only -uv run apx dev tail # Live stream +uv run apx dev check +``` + +**View logs:** +```bash +uv run apx dev logs # Recent logs (default: last 10m) +uv run apx dev logs -d 1h # Logs from last hour +uv run apx dev logs -f # Follow/stream logs live ``` **Stop servers:** @@ -66,10 +71,22 @@ uv run apx dev stop uv run apx build ``` -**OpenAPI generation** (auto-runs with `dev start`): -```bash -uv run apx openapi # Generate once -uv run apx openapi --watch # Watch mode -``` +**Note:** OpenAPI client is automatically regenerated on every code change when dev servers are running. No manual regeneration needed. + +## MCP Tools Reference + +When the apx MCP server is available, use these tools: -**Note:** The OpenAPI watcher runs automatically with `dev start`. Manual generation is rarely needed. \ No newline at end of file +| Tool | Description | +|------|-------------| +| `start` | Start development server and return the URL | +| `stop` | Stop the development server | +| `restart` | Restart the development server (preserves port if possible) | +| `logs` | Fetch recent dev server logs | +| `check` | Check project code for errors (runs tsc and ty checks in parallel) | +| `refresh_openapi` | Regenerate OpenAPI schema and API client | +| `search_registry_components` | Search shadcn registry components using semantic search | +| `add_component` | Add a component to the project | +| `docs` | Search Databricks SDK documentation for code examples and API references | +| `databricks_apps_logs` | Fetch logs from deployed Databricks app using Databricks CLI | +| `get_route_info` | Get code example for using a specific API route | diff --git a/src/apx/templates/addons/vscode/.vscode/mcp.json b/src/apx/templates/addons/vscode/.vscode/mcp.json index d97a0e70..820ec2f7 100644 --- a/src/apx/templates/addons/vscode/.vscode/mcp.json +++ b/src/apx/templates/addons/vscode/.vscode/mcp.json @@ -1,16 +1,12 @@ { "mcpServers": { - "shadcn": { - "command": "bun", - "args": ["x", "--bun", "shadcn@latest", "mcp"] - }, "apx": { "command": "uv", - "args": ["run", "apx", "dev", "mcp"] + "args": ["run", "apx", "mcp"] }, "playwright": { - "command": "bun", - "args": ["x", "--bun", "@playwright/mcp@latest"] + "command": "uv", + "args": ["run", "apx", "bun", "x", "--bun", "@playwright/mcp@latest"] } } } diff --git a/src/apx/templates/base/.claude/skills/apx/SKILL.md.jinja2 b/src/apx/templates/base/.claude/skills/apx/SKILL.md.jinja2 new file mode 100644 index 00000000..5b14361c --- /dev/null +++ b/src/apx/templates/base/.claude/skills/apx/SKILL.md.jinja2 @@ -0,0 +1,116 @@ +--- +name: apx +description: Quick reference for apx toolkit commands and MCP tools for building Databricks Apps +--- + +# 🚀 apx Toolkit + +apx is the toolkit for building full-stack Databricks Apps with React + FastAPI. + +## 📦 Project Structure + +``` +src/{{app_name}}/ +├── ui/ # React + Vite frontend +│ ├── components/ # UI components (shadcn/ui) +│ ├── routes/ # @tanstack/react-router pages +│ ├── lib/ # Utilities (api client, selector) +│ └── styles/ # CSS styles +└── backend/ # FastAPI backend + ├── app.py # Main FastAPI app + ├── router.py # API routes + ├── models.py # Pydantic models + └── config.py # Configuration +``` + +## 🔧 CLI Commands + +| Command | Description | +|---------|-------------| +| `uv run apx dev start` | 🟢 Start all dev servers (backend + frontend + OpenAPI watcher) | +| `uv run apx dev stop` | 🔴 Stop all dev servers | +| `uv run apx dev status` | 📊 Check status of running servers | +| `uv run apx dev check` | ✅ Check for TypeScript/Python errors | +| `uv run apx dev logs` | 📜 View recent logs (default: last 10m) | +| `uv run apx dev logs -f` | 📡 Follow/stream logs in real-time | +| `uv run apx build` | 📦 Build for production | +| `uv run apx bun ` | 🍞 Run bun commands (install, add, etc.) | +| `uv run apx components add ` | 🧩 Add a shadcn/ui component | + +## 🔌 MCP Tools + +When the apx MCP server is running, these tools are available: + +| Tool | Description | +|------|-------------| +| `start` | 🟢 Start development server and return the URL | +| `stop` | 🔴 Stop the development server | +| `restart` | 🔄 Restart development server (preserves port if possible) | +| `logs` | 📜 Fetch recent dev server logs | +| `check` | ✅ Check project code for errors (tsc + ty in parallel) | +| `search_registry_components` | 🔍 Search shadcn registry components (semantic search) | +| `add_component` | ➕ Add a component to the project | +| `docs` | 📚 Search Databricks SDK docs for code examples | +| `databricks_apps_logs` | 📊 Fetch logs from deployed app via Databricks CLI | +| `get_route_info` | 🛣️ Get code example for using a specific API route | +| `refresh_openapi` | 🔄 Regenerate OpenAPI schema and API client | + +## 💡 Development Workflow + +### Starting Development +```bash +uv run apx dev start # Starts everything in background +uv run apx dev status # Verify servers are running +``` + +### Adding UI Components +```bash +# Search for components first +uv run apx components add button --yes +uv run apx components add card --yes +``` + +### Installing Frontend Dependencies +```bash +uv run apx bun add lucide-react # Add a package +uv run apx bun install # Install all deps +``` + +### Checking for Errors +```bash +uv run apx dev check # TypeScript + Python linting +``` + +### Viewing Logs +```bash +uv run apx dev logs # Recent logs (last 10m) +uv run apx dev logs -d 1h # Logs from last hour +uv run apx dev logs -f # Follow/stream logs live +``` + +## ⚡ Key Patterns + +### API Models (3-model pattern) +- `Entity` - Database/internal model +- `EntityIn` - Input/request model +- `EntityOut` - Output/response model + +### Frontend Data Fetching +```tsx +// Use Suspense hooks with selector() +const { data } = useGetItemsSuspense(selector()); +``` + +### API Routes +```python +@router.get("/items", response_model=list[ItemOut], operation_id="getItems") +async def get_items(): + ... +``` + +## 🔗 Resources + +- OpenAPI client: `src/{{app_name}}/ui/lib/api/` (auto-generated) +- Routes: `src/{{app_name}}/ui/routes/` +- Components: `src/{{app_name}}/ui/components/` +- Backend: `src/{{app_name}}/backend/`