open-index/open-npm huggingface dataset:
npm package: @sbtools/core
Description: Core CLI orchestrator for supabase-tools — config, plugins, snapshot pipeline.
Latest version: 0.9.0

# @sbtools/core

Core CLI orchestrator for supabase-tools — config, plugin loader, snapshot pipeline.

## Installation

```bash
npm install @sbtools/core
```

## Usage

```bash
npx sbt <command>
```

Or add to your `package.json`:

```json
{
  "scripts": {
    "sbt": "sbt",
    "start": "sbt start",
    "migrate": "sbt migrate"
  }
}
```

Then `npm run start`, etc.

## What's Included

- Config loading and validation (`supabase-tools.config.json`)
- Dynamic plugin loader (npm packages or filesystem paths)
- Docker Compose management (Supabase stack)
- Migration runner
- Snapshot pipeline (export DB schema)
- Pre-flight checks

## Dependencies

| Type | Requirement |
|------|-------------|
| Docker | Must be running for `start`, `stop`, `restart`, `status`, `snapshot`, `migrate` |
| Compose files | `docker-compose.db.yml` in toolsDir |
| Migrations dir | `config.paths.migrations` must exist for `migrate` |
| Snapshot meta | `{paths.snapshot}/_meta/snapshot.json` must exist for `generate-atlas` (default: `.sbt/snapshot/`; run `sbt snapshot` first) |

## Plugins

Add plugins via config:

```json
{
  "plugins": [
    { "path": "@sbtools/plugin-erd", "config": {} }
  ]
}
```

Plugins add commands like `generate-erd`, `test`, `logs`, etc.
npm package: @sbtools/plugin-db-test
Description: Database test runner plugin for supabase-tools (pgTAP + PGlite).
Latest version: 0.8.0

# @sbtools/plugin-db-test

Plugin for [supabase-tools](https://github.com/supabase/supabase) that runs database tests using pgTAP. Supports live database mode (Docker) or in-memory PGlite mode.

## Quick Start

```bash
# Live mode (requires sbt start)
npm run sbt -- test

# In-memory mode (no Docker required)
npm run sbt -- test --mem
```

## Commands

| Command | Description |
|---------|-------------|
| `test` | Run pgTAP tests from supabase/tests |
| `test --mem` | Run tests in-memory via PGlite (applies migrations first) |

## Configuration

| Key | Default | Description |
|-----|---------|-------------|
| `testsDir` | `supabase/tests` | Directory containing .sql test files |
| `migrationsDir` | `supabase/migrations` | Migrations to apply in --mem mode |

## Dependencies

| Type | Requirement |
|------|-------------|
| Docker | Must be running for live mode (`sbt test`) |
| Database | DB must be running and accessible for live mode |
| Files | `supabase/tests` — test SQL files must exist |
| Files | Migrations dir must exist for `--mem` mode (no Docker needed) |

## Project Structure

```
packages/plugin-db-test/
├── src/
│   ├── index.ts      # Plugin entry, test command
│   ├── runner-live.ts # Live DB test execution
│   ├── runner-mem.ts  # PGlite in-memory execution
│   └── test-utils.ts  # pgTAP helpers
├── package.json
├── tsconfig.json
└── README.md
```
npm package: @sbtools/plugin-erd
Description: ERD diagram generation plugin for supabase-tools.
Latest version: 0.8.0

# @sbtools/plugin-erd

Plugin for [supabase-tools](https://github.com/supabase/supabase) that generates Mermaid ERD diagrams for each public table. Connects to the database to introspect columns, primary keys, and foreign keys.

## Quick Start

```bash
# Ensure database is running (sbt start)
npm run sbt -- generate-erd
# Output: docs/entity-relations/<table>.md
```

## Commands

| Command | Description |
|---------|-------------|
| `generate-erd` | Generate Mermaid ERD diagrams for all public tables |

## Configuration

Plugin config goes in `plugins[].config`:

```json
{
  "plugins": [{
    "path": "@sbtools/plugin-erd",
    "config": {
      "erdOutput": "docs/development/entity-relations",
      "displayColumns": ["name", "email", "full_name", "slug", "title"]
    }
  }]
}
```

| Key | Default | Description |
|-----|---------|-------------|
| `erdOutput` | `<docsOutput>/entity-relations` | Output directory for .md files |
| `displayColumns` | `["name", "email", "full_name", "slug", "title"]` | Column names to display on referenced entities |

## Dependencies

| Type | Requirement |
|------|-------------|
| Database | `DATABASE_URL` or `config.db.url`; DB must be running and accessible |

## Project Structure

```
packages/plugin-erd/
├── src/
│   ├── index.ts   # Plugin entry, generate-erd command
│   └── builder.ts # Mermaid generation, column mapping
├── package.json
├── tsconfig.json
└── README.md
```
npm package: @sbtools/plugin-frontend-usage
Description: Scans frontend code for Supabase SDK usage and generates an interactive HTML report.
Latest version: 0.9.0

# @sbtools/plugin-frontend-usage

Plugin for [supabase-tools](../../) that scans frontend `.ts/.tsx/.js/.jsx` files for Supabase SDK usage (table queries, RPCs, auth, storage, edge functions, REST calls) and generates an interactive HTML report + integrates with Backend Atlas.

## Quick Start

```bash
# 1. Add to supabase-tools.config.json
# 2. Run
npx tsx supabase-tools/cli.ts frontend-usage
# → docs/frontend-usage.html
```

## Commands

| Command | Description |
|---------|-------------|
| `frontend-usage` | Scan src/, generate HTML report, open in browser |
| `frontend-usage --json` | Output raw JSON to stdout |
| `frontend-usage --no-open` | Skip opening the report |
| `frontend-usage --help` | Show all options |

## Patterns Detected

| Pattern | Resource Type | Example |
|---------|---------------|---------|
| `.from("table")` | table | `supabase.from("papers")` |
| `.rpc("fn")` | rpc | `supabase.rpc("get_stats")` |
| `.auth.signIn*` etc. | auth | `supabase.auth.signInWithPassword(...)` |
| `.storage.from("bucket")` | storage | `supabase.storage.from("avatars")` |
| `.functions.invoke("name")` | edge_function | `supabase.functions.invoke("process")` |
| `fetch(".../rest/v1/...")` | rest_api | `fetch("/rest/v1/papers")` |
| `fetch(".../functions/v1/...")` | edge_function | `fetch("/functions/v1/hello")` |

## Configuration

```json
{
  "plugins": [
    {
      "path": "@sbtools/plugin-frontend-usage",
      "config": {
        "scanPaths": ["src/"]
      }
    }
  ]
}
```

| Key | Default | Description |
|-----|---------|-------------|
| `scanPaths` | `["src/"]` | Directories to scan for frontend files |

## Dependencies

| Type | Requirement |
|------|-------------|
| Files | Scan paths (default `src/`) must exist |

No Docker or database required.

## Atlas Integration

- **getAtlasData()**: Component → resource mapping as `frontend_usage` category
- **getAtlasView()**: Typed Atlas section definitions compiled by core
- **getStatusLines()**: Summary line in `sbt status`

## Project Structure

```
plugin-frontend-usage/
├── index.ts
├── src/
│   ├── index.ts       # SbtPlugin
│   ├── scanner.ts     # File discovery + scanning
│   ├── patterns.ts    # Regex patterns
│   ├── analyzer.ts    # Aggregation
│   ├── html-generator.ts # Delegates to shared @sbtools/ui-web renderer
│   └── atlas/
│       └── styles.ts
├── package.json
├── tsconfig.json
├── README.md
└── SKILL.md
```
npm package: @sbtools/plugin-migration-studio
Description: Migration authoring studio for supabase-tools — create and apply migrations from a browser UI.
Latest version: 0.10.0

# @sbtools/plugin-migration-studio

Migration authoring UI for supabase-tools. Create migrations in a browser-based editor, analyze SQL, and apply via the core `sbt migrate` flow.

## Features

- **SQL editor** — Write migration SQL in the browser
- **Modern dark theme** — Black-first visual style aligned with dashboard aesthetics
- **Live analysis** — Analyze SQL to see operations and risk indicators (uses shared `analyzeMigrationSql` from SDK)
- **Save / Update migration** — Create new or overwrite pending migration; dry run before apply; wrap in transaction
- **Apply migrations** — Runs `sbt migrate` (requires confirmation)
- **Live refresh bridge** — SSE endpoint (`/api/events`) refreshes migration/status context when `sbt watch` updates artifacts
- **Dashboard embedding support** — Works both as standalone Studio and embedded inside dashboard migrations flow

## Setup

Add to `supabase-tools.config.json`:

```json
{
  "plugins": [
    { "path": "@sbtools/plugin-migration-studio", "config": {} }
  ]
}
```

## Usage

```bash
sbt migration-studio
```

Opens the studio at http://localhost:3335. Use `--port N` to change the port.

## Contract

- **Produces:** `migration.studio.draft` (planned)
- **Consumes:** `migration.analysis` (optional — for richer context when migration-audit has run)

Apply path uses the core migration execution flow; no duplicate migration engine.
npm package: @sbtools/plugin-scaffold
Description: Scaffolds new supabase-tools plugins with consistent boilerplate.
Latest version: 0.8.0

# @sbtools/plugin-scaffold

Plugin for supabase-tools that scaffolds new plugins with consistent boilerplate matching established patterns.

## Quick Start

```bash
# Internal plugin (packages/plugin-<name>/)
npm run sbt -- scaffold-plugin analytics

# External plugin (supabase-tools-<name>-plugin/)
npm run sbt -- scaffold-plugin my-feature --external

# With Atlas hooks
npm run sbt -- scaffold-plugin dashboard --hooks
```

## Commands

| Command | Description |
|---------|-------------|
| `scaffold-plugin <name>` | Create internal plugin in packages/ |
| `scaffold-plugin <name> --external` | Create external plugin as sibling dir |
| `scaffold-plugin <name> --hooks` | Include Atlas hook stubs |

## Configuration

No config required.

## Dependencies

None — only requires config (`projectRoot`, `toolsDir` from context).

## Project Structure

```
packages/plugin-scaffold/
├── src/
│   ├── index.ts           # SbtPlugin with scaffold-plugin command
│   └── templates/         # File generators
├── package.json
├── tsconfig.json
└── README.md
```
npm package: @sbtools/plugin-typegen
Description: TypeScript type generation plugin for supabase-tools.
Latest version: 0.9.0

# @sbtools/plugin-typegen

Plugin for [supabase-tools](https://github.com/supabase/supabase) that generates TypeScript types from the running Supabase instance. Uses the PostgREST types generator endpoint.

## Quick Start

```bash
# Ensure database is running (sbt start)
npm run sbt -- generate-types
# Output: .sbt/types/supabase.ts (or configured path)
```

## Commands

| Command | Description |
|---------|-------------|
| `generate-types` | Fetch TypeScript types from PostgREST and write to file |

## Configuration

Plugin config goes in `plugins[].config`:

```json
{
  "plugins": [{
    "path": "@sbtools/plugin-typegen",
    "config": { "typesOutput": "src/types/supabase.ts" }
  }]
}
```

| Key | Default | Description |
|-----|---------|-------------|
| `typesOutput` | `.sbt/types/supabase.ts` | Output file path |

Environment: `SUPABASE_TYPES_SCHEMAS` to limit schemas (comma-separated).

## Dependencies

| Type | Requirement |
|------|-------------|
| Docker | DB container must be running (PostgREST types endpoint) |
| Files | `docker-compose.db.yml` in toolsDir (for key extraction) |

## Project Structure

```
packages/plugin-typegen/
├── src/
│   └── index.ts   # Plugin entry, generate-types command
├── package.json
├── tsconfig.json
└── README.md
```
npm package: @sbtools/sdk
Description: Plugin SDK for supabase-tools — shared types, interfaces, and utilities.
Latest version: 0.8.0

# @sbtools/sdk

Plugin SDK for supabase-tools — shared types, interfaces, and utilities.

## Installation

```bash
npm install @sbtools/sdk
```

## Usage

```ts
import { ui, SbtError, handleError } from "@sbtools/sdk";
import type { SbtPlugin, PluginContext } from "@sbtools/sdk";
```

## API

- **SbtPlugin** — Plugin contract with `name`, `version`, `commands`, hooks
- **PluginContext** — Runtime context (`projectRoot`, `toolsDir`, `pluginConfig`, etc.)
- **ui** — CLI output helpers (`info`, `success`, `warn`, `step`, `table`, etc.)
- **Error classes** — `ConfigError`, `DatabaseError`, `SnapshotError`, `PluginError`, `SbtError`
- **Filesystem** — `ensureDir`, `readText`, `writeFileInDir`, `safeName`, `safeFileName`, `sanitizeSlug`, `sanitizeIdentifier`
- **Container** — `sanitizeContainerPrefix`, `deriveContainerPrefix` — Docker project prefix from config
- **Compose** — `extractComposeKey`, `extractSupabaseKeys` — Extract keys from docker-compose files
- **CLI** — `hasFlag`, `getArg`, `openFile`, `withHelp`, `loadPackageVersion`
- **Dashboard** — `DashboardView`, `DashboardSectionDef`, etc. — JSON-serializable plugin UI contributions for `sbt dashboard`
- **Schema** — `SchemaFilter` — Parameterized SQL filter type (`{ clause, params }`)

## Dependencies

None — pure utilities, no runtime dependencies.

See [SDK docs](https://bazokhan.github.io/supabase-tools/sdk/) for full reference.
npm package: @sbtools/ui-web
Description: Shared React UI renderer package for supabase-tools web pages.
Latest version: 0.9.0

# @sbtools/ui-web

Shared UI package for supabase-tools — SSR page renderers and the Vite-built React dashboard SPA.

## Installation

```bash
npm install @sbtools/ui-web
```

## What's Included

### SSR Renderers

Server-side page renderers used by plugin CLI commands to generate standalone HTML files:

- `renderDepgraphPage` — Interactive dependency graph (`sbt depgraph --html`)
- `renderFrontendUsagePage` — Frontend SDK usage report (`sbt frontend-usage`)
- `renderMigrationAuditPage` — Migration audit report (`sbt migration-audit`)
- `renderMigrationDetailPage` — Per-migration detail pages
- `renderLogsViewerPage` — Live log viewer (`sbt logs viewer`)
- `renderMigrationStudioPage` — Migration authoring UI (`sbt migration-studio`)
- `renderRawDocument` — Base HTML document shell

### Dashboard SPA

A Vite-built React single-page application served by `sbt dashboard`:

- App shell with sidebar navigation and dark mode toggle
- Shared components: StatCard, Badge, SearchInput, CodeBlock, DataTable, CardGrid, GenericSection
- Plugin-driven pages rendered from `DashboardSectionDef` JSON config
- Design tokens with automatic light/dark mode (`tokens.css`)

The dashboard is bundled into `@sbtools/core` during build — consumers don't need to install this package directly.

## Usage

```ts
import { renderDepgraphPage, renderRawDocument } from "@sbtools/ui-web";
```

## Development

To run the dashboard SPA with Vite HMR:

1. **Start the dashboard backend** (serves API and static assets on port 3400):

   ```bash
   sbt dashboard
   ```

2. **Generate atlas data** (required for `/api/atlas-data`):

   ```bash
   sbt generate-atlas
   ```

3. **Run Vite dev server** with API proxy:

   ```bash
   npm run dev
   ```

   Or from repo root: `npm run dashboard:dev`

   The UI runs at `http://localhost:5173`. API calls to `/api/*` are proxied to the backend at `http://127.0.0.1:3400`.

   Set `DASHBOARD_API_PORT` if the backend runs on a different port.

## Dependencies

- `react`, `react-dom` — Used for `renderToStaticMarkup` in SSR renderers
- `vite`, `@vitejs/plugin-react` — Dev dependencies for dashboard build