RepoPilot

supabase / cli

Search supabase/cli

GitHub

Code

Understand supabase/cli's source layout and find a starting point for your task using the saved repository evidence.

B
Architecture grade
score 71/100
5
Import cycles
lower is better
363
Modules parsed
552 edges
90%
Layeredness
clean-layer ratio

Measured from the parsed import graph, retained from the earlier analysis. Coupling, not a reading order.

How the code fits together

AI
  • CLI Configuration & SchemaConfiguration parsing, validation, and schema management for Supabase projects
  • Functions & DeploymentEdge Functions configuration, manifest handling, and deployment orchestration
  • API Client & ContractsGenerated API contracts and HTTP client for Supabase backend communication
  • Local Development StackOrchestration of local Postgres, Edge Runtime, and other services
  • Authentication & SecurityAuthentication configuration including email, SMS, OAuth providers, and MFA

Files at d5ac73f665a2 · descriptions are AI-written.

The descriptions and the file list come from different revisions. Check responsibilities against source.

Where to start reading

  1. Repository root
  2. Repository root
  3. Public API candidatename match
  4. Public API candidatename match
  5. Runtime candidatename match
  7. Suggested starting pointAI

Find files for a task

AI

Add a new configuration section to supabase.json

Suggested by the saved analysis. Some step paths were not captured or refer to generated or vendor files; only observed source files are linked.

  • Export and integrate the schema into the root project configuration
  • Update the JSON Schema definition for IDE autocomplete support

Add a new Edge Function deployment feature

Suggested by the saved analysis. Some step paths were not captured or refer to generated or vendor files; only observed source files are linked.

  • Extend the functions configuration schema with new properties
  • Update the functions manifest model to track the new metadata
  • Add integration test verifying end-to-end deployment flow

Add a new local service to the development stack

Suggested by the saved analysis. Verify the proposed change against these source files.

  • Implement service command definition and lifecycle hooks
  • Add network and port configuration for the service
  • Implement subprocess management for the service process
  • Add integration tests for startup, shutdown, and error scenarios

Change the public API

Start with possible export surfaces, then check their consumers and tests. These suggestions use file names, not verified execution paths.

  • File-name match for this task.
  • File-name match for this task.
  • File-name match for this task.

Trace runtime behavior

Start with possible startup or request handlers, then follow the calls for your scenario. These suggestions use file names, not verified execution paths.

  • File-name match for this task.

Add or update tests

Use a nearby test as a pattern. Read the root manifest or contribution guide for the correct test command. These suggestions use file names, not verified execution paths.

  • File-name match for this task.
  • File-name match for this task.
  • File-name match for this task.

Change build or automation

Inspect the relevant configuration and the commands it runs before changing the workflow. These suggestions use file names, not verified execution paths.

  • File-name match for this task.
  • File-name match for this task.
  • File-name match for this task.

File paths come from a snapshot of up to 500 captured paths; an omitted file may still exist.

  • Public and runtime candidates are based on file names; their exports and execution paths still need checking in source.
  • The file list was refreshed after the written analysis. Subsystem descriptions and suggested changes may describe an older revision.

Import graph details

Modules (22)

Source directories grouped from the import graph. Each links to a per-module page with its files and how it couples to the rest.

Also: packages/config/src/project-config, packages/stack/src/identity, packages/stack/src/namespace/drivers, packages/config/src/auth, packages/api/src/internal, apps/cli-e2e/src/server, packages/stack/src/preparation, packages/stack/src/storage, packages/api/src/generated, packages/api/src/config, packages/stack/src/functions, apps/cli-e2e/src/tests, packages/api/src, apps/cli-e2e/tests

Circular dependencies (5)

  • project.ts → resolve.ts → project.ts
  • Database.ts → DatabaseSnapshot.ts → Database.ts
  • Database.ts → DockerDatabaseStorage.ts → Database.ts
  • Catalog.ts → Analytics.ts → ServiceConfig.ts → StackNamespace.ts → Registry.ts → Catalog.ts
  • GatewayLog.ts → LogflareEvents.ts → GatewayLog.ts

Architecture and request flow

Critical modules — by import-graph evidence

Import graph
363 files parsed · 552 internal edges

A file is "critical" when lots of other files in the repo import it. The list is sorted by how many files import each one; the top of the list is the most load-bearing. A flame icon means the file is also one of the most-edited recently — when a critical file changes a lot, bugs there ripple wider, so it's where regressions are most likely.

How the B grade breaks down

Imports flow one direction90%
36/40

What fraction of imports go from application code (likely to change) toward foundation code (more stable). High % means the codebase has clean layers — like a pyramid, not a hairball. Healthy repos are above 85%.

Foundation vs application separationspread = 0.35
30/30

Measures how distinct foundation files (rarely change, lots of files depend on them) are from application files (change often, depend on lots of things). A wider spread (higher σ) means clearer layers; a narrow spread means everything's tangled together at roughly the same level.

No circular imports5 cycles
5/30

A 'cycle' is when file A imports B which imports A again (possibly via more files in between). Cycles make builds slower, refactors harder, and tests trickier. −5 points per cycle found.

Imports going the wrong way

Foundation code importing application code — this drags stable code along with every application change.

packages/api/src/internal/effect-client.ts↑packages/api/src/internal/client.ts
packages/config/src/base.ts↑packages/config/src/auth/index.ts
packages/config/src/base.ts↑packages/config/src/db.ts
packages/config/src/base.ts↑packages/config/src/edge_runtime.ts
packages/config/src/cli-config.layer.ts↑packages/config/src/io.ts
List — top 12 most-imported files

Architecture evolution

See how the import graph changed in the last 90 days — grade shift, cycles added/removed, top-file rotation. Heavy compute (~30s on first load), cached for 30 days after.

Circular imports (5)

packages/config/src/project.tstopackages/config/src/lib/resolve.tstopackages/config/src/project.ts
packages/stack/src/services/Database.tstopackages/stack/src/services/DatabaseSnapshot.tstopackages/stack/src/services/Database.ts
packages/stack/src/services/Database.tstopackages/stack/src/storage/DockerDatabaseStorage.tstopackages/stack/src/services/Database.ts
packages/stack/src/services/Catalog.tstopackages/stack/src/services/Analytics.tstopackages/stack/src/services/ServiceConfig.tstopackages/stack/src/StackNamespace.tstopackages/stack/src/namespace/Registry.tstopackages/stack/src/services/Catalog.ts
packages/stack/src/host/GatewayLog.tstopackages/stack/src/host/LogflareEvents.tstopackages/stack/src/host/GatewayLog.ts

Possibly-unused modules (15)

Import graph

Nothing else in the repo imports these files, and they don't look like entry points — so they may be dead code. Verify before removing: dynamic imports, re-exports, and framework auto-loading (Next.js routes, plugin/DI registries) aren't tracked by the import graph.

isolatedpackages/cli-test-helpers/src/harness.ts
isolatedapps/cli-e2e/vitest.config.ts
isolatedapps/cli-go/fsevents/fsevents.go
isolatedapps/cli-go/fsevents/wrap.go
isolatedapps/cli-go/internal/db/diff/diff.go
isolatedapps/cli-go/internal/db/diff/diff_test.go
isolatedapps/cli-go/internal/db/diff/migra.go
isolatedapps/cli-go/internal/db/diff/pgschema.go
isolatedapps/cli-go/internal/db/diff/save_diff_test.go
isolatedapps/cli-go/internal/db/diff/shadow.go
isolatedapps/cli-go/internal/db/diff/templates/migra.ts
isolatedapps/cli-go/internal/db/reset/reset.go
isolatedapps/cli-go/internal/db/reset/reset_test.go
isolatedapps/cli-go/internal/db/start/start.go
isolatedapps/cli-go/internal/db/start/start_test.go

Request flow

Technology choices

TypeScript + Effect.ts

Provides strong type safety for CLI operations and functional error handling without try-catch boilerplate

JSON Schema validation

Enables IDE autocomplete for supabase.json and prevents invalid configuration at parse time

OpenAPI code generation

Keeps API client in sync with backend API changes automatically

Bun runtime

Provides fast task execution and native TypeScript support for CLI bootstrapping

Build time and runtime

Build-time

  • ▸
    OpenAPI contract generation — Generates TypeScript API client from openapi.json schema
  • ▸
    JSON Schema compilation — Compiles Zod/TypeScript schemas into JSON Schema for IDE support
  • ▸
    TypeScript type checking — Type validation across monorepo packages

Runtime

  • ▸
    Config parsing and validation — Loads supabase.json and validates against schema on every CLI invocation
  • ▸
    Local service orchestration — Spawns and manages Postgres, Edge Runtime, and emulator subprocesses
  • ▸
    API client requests — Makes HTTP requests to Supabase backend for deployment and project management
  • ▸
    Environment variable resolution — Resolves .env files and variable substitution in configuration

Design trade-offs

Monorepo structure with @supabase/config, @supabase/api, @supabase/stack packages

Allows independent versioning and reuse of core libraries by other Supabase tools

Increases build complexity and requires careful dependency management across packages

Separate config schema layer from CLI command layer

Decouples configuration validation from command execution, enabling API-driven workflows

More files to navigate but clearer separation of concerns

Generate API contracts from OpenAPI spec

Ensures CLI always has current API definitions without manual updates

Requires OpenAPI spec maintenance and build-time code generation

Non-goals

  • ✗GUI/web-based interface (CLI-only tool)
  • ✗Cross-platform Windows support (primarily Linux/macOS focus based on Postgres local support)
  • ✗Real-time collaborative editing (stateless deployment model)
  • ✗Direct database schema migrations without version control (migration tracking is file-based)

Code quality and hotspots

Quality Score: 70/100

Low Risk

This repo is in good health with CI, tests, and active maintenance.

High churn files -10High complexity -10Multiple anti-patterns -10

Maintainability grade

Static analysis

How maintainable the code looks — from complexity, code issues, test presence, file size, and hotspot load. It grades the shape of the code, not defect risk, and doesn't replace review.

F
20/100
A ≥ 85, B ≥ 70, C ≥ 55, D ≥ 40, F < 40
Cyclomatic complexityavg 498
0/35
Code issues3 errors, 523 warnings
0/20
Testspresent · ~75% of files
20/20
Largest file23,230 lines
0/15
Hotspot load10 high-risk files
0/10

Configuration status

CI/CD Pipeline — configured

Provider: GitHub Actions

46 GitHub Actions workflows

Test Suite — detected

1,027 test files detected

Stack: Jest/Vitest · Go test

Where: apps/cli-e2e/src/tests · .github/scripts · .github/scripts/ai-review

Test Coverage — ~75%heuristic

1,027 test files / 1,369 source files. This is a file-count ratio, not real line coverage — set up Codecov for authoritative numbers.

Dependency Scanning — 1 tool configured

CodeQL

Live Signals

Real-time data from Codecov, GitHub Actions, GitHub Issues, deps.dev — not estimates.

CI pass rate74%

last 50 runs · median 54s

Stale-issue ratio0%

of 14 recent open issues are 30d+ old with no replies

Maintainer response16h

median first-reply across 3 recent issues · fast

Top hotspots

Files edited often AND hard to reason about. Churn = recent commit frequency, Complexity = branches and nesting, Risk = both combined. These are the highest-leverage targets for refactoring or testing.

generated/contracts.ts
Churn: 100 (50 commits/180d)Complexity: 100Risk: 100
api/types.gen.go
Churn: 100 (45 commits/180d)Complexity: 100Risk: 100

All hotspots

Files that change often and are complex tend to accumulate more bugs

AI-suggested anti-patterns

AI · unverified

Pattern-matches from the file structure and dependencies — useful as hypotheses, but not grounded in actual source. For real findings see Code Scanning above.

Monorepo circular dependencies

Medium

Multiple packages export config utilities that are re-exported by others, risking circular imports during bundling

packages/config/src, packages/api/src, packages/stack/src

Mixed async patterns (Promise + Effect)

Medium

Codebase uses both Effect.ts async and native Promise patterns, complicating error handling uniformity

packages/config/src/promise-facade.ts, packages/api/src/internal/

Large configuration objects

Low

Single project config object accumulates all feature sections (auth, functions, storage), risking God Object anti-pattern

packages/config/src/project-config/project-config.ts

AI-suggested bottlenecks

AI · unverified

Speculation from file structure, not profiling data. Validate against real metrics before acting on these.

Synchronous validation on hot path Bottleneck

All CLI commands depend on schema validation; slow validators block every operation

packages/config/src/validate.ts

Sequential subprocess initialization Bottleneck

Subprocess spawning is serial; starting multiple local services waits for each sequentially

packages/stack/src/HostProcess.ts

Network I/O serialization Bottleneck

All API calls route through single client instance; network I/O latency directly impacts deployment speed

packages/api/src/internal/client.ts

Code metrics

Static analysis on sampled source files (up to 15 files).

Avg Cyclomatic Complexity498

Counts if/for/while/switch/catch/ternary branches

Errors / Warnings3 / 523

Secrets, empty catches, console.log, var usage, long lines

Largest File Analyzed23230 lines
apps/cli-go/pkg/api/client.gen.go