@agentlink.sh/cli 0.10.0

package/README.md

@@ -0,0 +1,345 @@
+# agentlink
+
+Teach AI agents the right way to build on Supabase.
+
+[Agent Link](https://agentlink.sh) is an opinionated skill set for Claude Code — and this CLI is how you start a project with it. One command scaffolds a Supabase backend with schema isolation, RPC-first data access, row-level security, multi-tenancy, and edge functions already wired up — plus a frontend (React + Vite or Next.js) with auth, theming, and shadcn/ui ready to go. Your agent doesn't have to figure out the architecture — it's already there. From that foundation, five domain skills give it one clear path for every decision: how to structure tables, write RLS policies, expose APIs, handle background work, and connect a frontend. No ambiguity, no wrong turns. First-try results.
+
+## Install
+
+### macOS
+
+```bash
+curl -fsSL https://agentlink.sh/install | sh
+```
+
+### Linux
+
+```bash
+wget -qO- https://agentlink.sh/install | sh
+```
+
+### Windows (PowerShell)
+
+```powershell
+irm https://agentlink.sh/install.ps1 | iex
+```
+
+### npm
+
+```bash
+npm install -g @agentlinksh/cli
+```
+
+Or run directly with npx (requires Node.js 18+):
+
+```bash
+npx @agentlinksh/cli@latest
+```
+
+The install scripts automatically detect your OS, install Node.js if needed, and set up the CLI globally.
+
+## Quick start
+
+```bash
+# Create a new project (cloud by default, zero questions with name + prompt)
+agentlink my-app "Build a project management tool with kanban boards"
+
+# Interactive wizard (asks project name and frontend choice)
+agentlink
+```
+
+## Commands
+
+### `agentlink [name] [prompt]`
+
+Interactive wizard that scaffolds a new project or updates an existing one. Uses Supabase Cloud by default — region is auto-detected from your timezone, all recommended skills are installed automatically.
+
+```bash
+# Interactive wizard
+agentlink
+
+# With project name
+agentlink my-app
+
+# With name and prompt (zero questions — express mode)
+agentlink my-app "Build a project management tool with kanban boards"
+
+# Local Docker mode (instead of cloud)
+agentlink my-app --local
+
+# NextJS instead of React + Vite
+agentlink my-app --nextjs
+
+# Backend only (no frontend)
+agentlink my-app --no-frontend
+
+# Skip companion skills
+agentlink my-app --no-skills
+
+# Non-interactive (CI-friendly)
+agentlink my-app --yes --non-interactive --token $SUPABASE_TOKEN --org $ORG_ID --region us-east-1
+```
+
+**Options:**
+
+| Flag                | Description                                      |
+| ------------------- | ------------------------------------------------ |
+| `--debug`           | Write debug log to `agentlink-debug.log`         |
+| `--force-update`    | Force update even if project is up to date       |
+| `--no-frontend`     | Skip frontend scaffolding (backend only)         |
+| `--nextjs`          | Use NextJS instead of React + Vite               |
+| `--local`           | Use local Docker instead of Supabase Cloud       |
+| `--no-skills`       | Skip companion skill installation                |
+| `--no-launch`       | Skip launching Claude Code after scaffold        |
+| `-y, --yes`         | Auto-confirm all prompts                         |
+| `--token <token>`   | Supabase access token (skips interactive login)  |
+| `--org <id>`        | Supabase organization ID                         |
+| `--region <region>` | Supabase Cloud region (auto-detected if omitted) |
+| `--prompt <prompt>` | Alternative to positional prompt argument        |
+| `--resume`          | Resume a previously failed scaffold              |
+| `--non-interactive` | Error instead of prompting when info is missing  |
+
+### `agentlink login`
+
+Authenticate with Supabase via OAuth (opens browser). Tokens are cached and auto-refreshed.
+
+```bash
+agentlink login
+```
+
+### `agentlink deploy`
+
+Deploy schema changes, edge functions, and secrets from dev to a target environment.
+
+```bash
+agentlink deploy              # Deploy to prod (default)
+agentlink deploy --dry-run    # Preview without applying
+agentlink deploy --ci         # Non-interactive for CI/CD
+agentlink deploy --env staging
+```
+
+### `agentlink env`
+
+Manage project environments.
+
+```bash
+agentlink env add prod        # Connect a production cloud project
+agentlink env use local       # Switch to local Docker for dev
+agentlink env list            # Show all environments
+agentlink env remove staging  # Remove an environment config
+```
+
+### `agentlink check`
+
+Verify project setup. Outputs JSON with diagnostic info: `setup_hash_match`, `supabase_running`, database state (extensions, queues, functions, secrets, api_schema), and file checks.
+
+```bash
+agentlink check
+```
+
+### `agentlink info [name]`
+
+Show documentation about scaffolded components. Without a name, lists all components. With a name, shows type, summary, description, signature, and related components.
+
+```bash
+agentlink info              # List all components
+agentlink info tenant_select # Detail for one component
+```
+
+### `agentlink db apply`
+
+Apply all schema files in `supabase/schemas/` to the database using pg-delta declarative apply.
+
+```bash
+agentlink db apply
+agentlink db apply --db-url postgresql://...  # Custom DB URL
+```
+
+### `agentlink db migrate <name>`
+
+Generate a migration from the diff between the current database state and the schema files.
+
+```bash
+agentlink db migrate add_charts_table
+agentlink db migrate add_charts_table --db-url postgresql://...
+```
+
+### `agentlink template <name>`
+
+Scaffold only the frontend template (no Supabase setup).
+
+```bash
+agentlink template my-app           # React + Vite
+agentlink template my-app --nextjs  # NextJS
+```
+
+## What it does
+
+The scaffold runs a multi-step process:
+
+1. **Prerequisites** — Checks for Supabase CLI, pg-delta, and psql
+2. **Configure files** — Writes template files, `config.toml`, and `.env.local`
+3. **Start Supabase** — Starts locally (Docker) or creates a Cloud project
+4. **Read config** — Reads Supabase API keys and connection info
+5. **Write env** — Updates `.env.local` with API keys and DB URL
+6. **Setup database** — Applies SQL schemas, writes migrations, configures auth
+7. **Verify setup** — Runs verification queries to confirm all components
+8. **Setup frontend** — Writes React + Vite or NextJS files (if selected)
+9. **Install frontend deps** — Runs `npm install` for the frontend
+10. **Configure Claude Code** — Sets up `CLAUDE.md` and Claude settings
+11. **Install MCP** — Installs Supabase MCP server (local mode only)
+12. **Install plugin** — Installs Agent Link plugin and companion skills
+13. **Finalize** — Creates git repo, writes `agentlink.json` manifest
+
+Running `agentlink` inside an existing project (with `agentlink.json`) triggers the **update** flow instead, which patches template files, updates the plugin, applies schema changes, and regenerates migrations.
+
+## Modes
+
+### Cloud mode (default)
+
+Creates a Supabase Cloud project. No local Docker or psql required. Uses the Management API for database operations, auth config, PostgREST config, and edge function deployment. Authenticates via OAuth (browser), token flag (`--token`), or cached credentials (`~/.config/agentlink/credentials.json`). Region is auto-detected from your timezone.
+
+### Local mode (`--local`)
+
+Runs Supabase in Docker via `supabase start`. Requires Docker and psql. Applies schemas via psql. Installs the Supabase MCP server for Claude Code.
+
+## Frontend options
+
+| Option                         | Frontend           | Key features                                      |
+| ------------------------------ | ------------------ | ------------------------------------------------- |
+| React + Vite (default)         | Vite + React       | Auth UI, theme switcher, shadcn/ui components     |
+| NextJS (`--nextjs`)            | Next.js App Router | SSR, server/client Supabase modules, same auth UI |
+| Backend only (`--no-frontend`) | None               | Minimal package.json with dev dependencies only   |
+
+## Companion skills
+
+The CLI installs all recommended companion skills for Claude Code automatically. Use `--no-skills` to skip.
+
+**Base skills (all frontends):**
+
+- `supabase/agent-skills@supabase-postgres-best-practices` (required)
+- `anthropics/skills@frontend-design`
+- `shadcn/ui`
+- `vercel-labs/agent-skills@vercel-react-best-practices`
+- `resend/react-email`
+- `resend/email-best-practices`
+- `resend/resend-skills`
+
+**Additional for NextJS:**
+
+- `vercel-labs/next-skills --skill next-best-practices`
+
+## Scaffolded project structure
+
+```
+my-app/
+├── agentlink.json                  # Project manifest
+├── CLAUDE.md                       # AI agent instructions
+├── .env.local                      # Environment variables
+├── .env.example
+├── .claude/
+│   └── settings.local.json         # Claude Code permissions
+├── supabase/
+│   ├── config.toml
+│   ├── schemas/
+│   │   ├── _schemas.sql            # Schema + role grants
+│   │   ├── _extensions.sql         # Extension declarations
+│   │   ├── public/
+│   │   │   ├── profiles.sql        # User profiles table
+│   │   │   ├── multitenancy.sql    # Tenants, memberships, invitations
+│   │   │   ├── _auth_tenant.sql    # Tenant auth helpers (RLS)
+│   │   │   ├── _internal_admin.sql # Vault, edge function calls, set_updated_at
+│   │   │   └── _hooks.sql          # Auth hooks
+│   │   └── api/
+│   │       ├── profile.sql         # Profile RPCs
+│   │       └── tenant.sql          # Tenant/invitation/membership RPCs
+│   ├── migrations/                 # Generated (never hand-written)
+│   └── functions/
+│       ├── _shared/
+│       │   ├── withSupabase.ts     # Auth wrapper for edge functions
+│       │   ├── responses.ts        # Response helpers
+│       │   └── types.ts            # Type definitions
+│       ├── queue-worker/           # PGMQ message queue handler
+│       └── send-email/             # Email sending + templates
+├── src/                            # Frontend source (Vite or NextJS)
+└── package.json
+```
+
+## Template architecture
+
+Scaffolded projects get their files from `src/template/supabase/`, which mirrors
+the target directory structure. SQL files are loaded as text by esbuild's built-in
+text loader. Edge function `.ts` and `.tsx` files are loaded as text by custom esbuild
+plugins (see `tsup.config.ts`).
+
+All template files are imported and registered in `src/templates.ts`:
+
+- `TEMPLATE_FILES` — map of relative path to content, used by `writeTemplateFiles()`
+- `EXEC_SQL` — subset of SQL that gets executed against the database during setup
+- `computeSetupHash()` — integrity hash for the agentlink manifest
+
+Files that depend on runtime values (`config.toml`, `.env`, seed SQL) are generated
+dynamically in `src/supabase.ts` and are not part of the template directory.
+
+### Adding a new scaffolded file
+
+1. Create the file at its target path under `src/template/supabase/`
+   (e.g., `src/template/supabase/functions/my-function/index.ts`)
+2. If it's a `.ts` file, add a type declaration in `src/template.d.ts`:
+   ```typescript
+   declare module "./template/supabase/functions/my-function/index.ts" {
+     const content: string;
+     export default content;
+   }
+   ```
+3. In `src/templates.ts`, add the import and register it in `TEMPLATE_FILES`:
+   ```typescript
+   import myFunction from "./template/supabase/functions/my-function/index.ts";
+   // ...
+   "functions/my-function/index.ts": myFunction,
+   ```
+4. If the file is SQL that needs to be executed against the database during setup,
+   also add it to the `EXEC_SQL` object and call it from `scaffold.ts`.
+
+## Development
+
+```bash
+cd cli
+npm install
+npm run build          # tsup -> dist/index.js (ESM, Node 18+)
+npm run dev            # tsup --watch
+npm run lint           # ESLint
+node dist/index.js     # Run locally
+```
+
+### Source files
+
+| File                        | Purpose                                                   |
+| --------------------------- | --------------------------------------------------------- |
+| `src/index.ts`              | Commander entry point, command definitions                |
+| `src/wizard.ts`             | Interactive setup flow                                    |
+| `src/scaffold.ts`           | Multi-step scaffolding with spinner UI                    |
+| `src/update.ts`             | Project update mechanism                                  |
+| `src/db.ts`                 | Database schema operations (apply, migrate)               |
+| `src/check.ts`              | Setup verification                                        |
+| `src/info.ts`               | Component documentation lookup                            |
+| `src/cloud.ts`              | Cloud mode (tokens, orgs, regions, Management API, OAuth) |
+| `src/oauth.ts`              | Supabase OAuth PKCE flow and token refresh                |
+| `src/deploy.ts`             | Deploy command (diff, validate, push)                     |
+| `src/env.ts`                | Environment management (add, use, list, remove)           |
+| `src/migration-analysis.ts` | Static analysis of migration SQL for data risks           |
+| `src/manifest.ts`           | `agentlink.json` I/O and environment resolution           |
+| `src/supabase.ts`           | Supabase CLI operations, migration management             |
+| `src/templates.ts`          | Template file registry and hash computation               |
+| `src/vite-templates.ts`     | React + Vite template files                               |
+| `src/nextjs-templates.ts`   | NextJS template files                                     |
+| `src/claude-md.ts`          | CLAUDE.md generation                                      |
+| `src/claude-settings.ts`    | Claude Code settings                                      |
+| `src/sql.ts`                | SQL generation (seeds, checks)                            |
+| `src/utils.ts`              | Shell commands, logging, validation                       |
+| `src/theme.ts`              | Terminal colors (Sheikah blue, amber, red)                |
+| `src/progress.ts`           | Resume state management                                   |
+| `src/ui.ts`                 | Spinner and progress display                              |
+| `src/banner.ts`             | CLI banner                                                |
+| `src/constants.ts`          | Pinned versions, Supabase/pgdelta CLI paths               |
+| `src/template.d.ts`         | TypeScript declarations for embedded templates            |