agentlink-sh 0.26.0

package/README.md

@@ -0,0 +1,485 @@
+# 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 & Run
+
+### 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
+```
+
+### npx (any platform with Node.js 18+)
+
+```bash
+npx agentlink-sh@latest
+```
+
+Or run directly with npx (requires Node.js 18+):
+
+```bash
+npx agentlink-sh@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)
+agentlink my-app
+
+# With a prompt for Claude Code
+agentlink my-app --prompt "Build a project management tool with kanban boards"
+
+# Interactive wizard
+agentlink
+```
+
+## Commands
+
+### `agentlink [name]`
+
+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 prompt (passed to Claude Code on launch)
+agentlink my-app --prompt "Build a project management tool"
+
+# 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
+
+# Scaffold files only — no Supabase setup. Run `env add dev` later in a
+# terminal to finish the env. Use when an agent scaffolds without browser
+# access and hands off to the user.
+agentlink my-app --skip-env
+
+# 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                                            |
+| `--skip-env`        | Scaffold files without touching Supabase (no OAuth, no project, no Docker, no apply)  |
+| `--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                                       |
+| `--link`            | Link to an existing Supabase project (with `--project-ref` + connection flags)        |
+
+### `agentlink sb login`
+
+Authenticate with Supabase via OAuth (opens browser). Tokens are cached per-org in `~/.config/agentlink/credentials.json` and auto-refreshed.
+
+```bash
+agentlink sb login
+```
+
+> The top-level `agentlink login` / `agentlink token` commands still work but print a deprecation warning. The top-level `login` namespace is reserved for future Agent Link accounts.
+
+### `agentlink sb token`
+
+Show or set the Supabase personal access token (PAT) used for non-interactive CI/CD.
+
+```bash
+agentlink sb token show           # Print the current token and its source
+agentlink sb token set sbp_...    # Save a new token
+```
+
+### `agentlink env`
+
+Manage project environments. Agent Link enforces a fixed `local → dev → prod` model — no custom names (`staging`, `dev2`, etc. are rejected).
+
+#### `env add [name]`
+
+Add a cloud environment and (by default) deploy the current schema + functions to it. If `[name]` is omitted, a picker shows `dev` / `prod` with a `— linked to <projectRef>` / `— not linked` hint per row.
+
+```bash
+agentlink env add              # Interactive picker
+agentlink env add dev          # Connect the dev cloud environment
+agentlink env add prod         # Connect production. Does NOT touch .env.local.
+agentlink env add dev --no-deploy    # Register the env but skip the initial deploy
+agentlink env add dev --setup-ci     # Also scaffold a GitHub Actions workflow
+```
+
+If the environment already exists, `env add` prompts with a 3-way menu:
+
+```
+  If you just changed schemas or functions, cancel and run `agentlink env deploy <name>` instead.
+
+? Environment "dev" already exists. What would you like to do?
+❯ Re-apply full setup — schemas, functions, secrets, PostgREST + auth config
+  Relink to a different Supabase project
+  Cancel
+```
+
+`Re-apply full setup` re-runs the full bootstrap (schemas + functions + vault + PostgREST + auth + verify). Use it when auth providers, PostgREST config, or vault secrets changed — otherwise prefer `env deploy` (lighter, idempotent).
+
+#### `env use [name]`
+
+Switch the active environment. Rewrites the managed block in `.env.local` and updates `manifest.cloud.default`. If `[name]` is omitted, a picker lists `dev` / `prod` (and `local` when the project is local-only or already on local) with a ✓ next to the active env.
+
+```bash
+agentlink env use              # Interactive picker
+agentlink env use dev          # Switch to dev
+agentlink env use local        # Switch to local Docker
+agentlink env use prod         # Switch to prod (requires y/N confirmation)
+```
+
+`env use prod` prints an amber warning and requires explicit confirmation before writing `.env.local` — any app or test you run locally will hit production data. After confirming, subsequent `env deploy` / `db apply` / `db sql` / `db rebuild` invocations print an `▲ Active env: prod` banner as a reminder.
+
+#### `env deploy [name]`
+
+Apply schemas (`db apply`) and deploy edge functions to the chosen env. Idempotent. Does NOT mutate `manifest.cloud.default` — deploy is a one-shot action, so `env use dev && env deploy prod` stays on dev afterwards.
+
+```bash
+agentlink env deploy              # Interactive picker (preselects cloud.default)
+agentlink env deploy dev          # Deploy to dev
+agentlink env deploy prod         # Deploy to prod (requires y/N confirmation)
+agentlink env deploy prod --yes   # Skip the confirmation (for CI)
+agentlink env deploy dev --dry-run  # Print the target without applying
+```
+
+Auth providers / PostgREST config / vault secrets are NOT touched by `env deploy` — those are configured during initial `env add`. If any of those changed, use `env add <name> → Re-apply full setup` instead.
+
+Generated CI workflows (`env add --setup-ci`) call `env deploy <name> --yes --non-interactive`.
+
+#### `env list`
+
+Show all configured environments with their org, project ref, and which one is currently active.
+
+```bash
+agentlink env list
+```
+
+#### `env remove <name>`
+
+Remove an environment from `agentlink.json`. Offers to also wipe the stored DB password for that project.
+
+```bash
+agentlink env remove prod
+agentlink env remove prod -y   # Skip confirmations
+```
+
+> The previous `agentlink env relink <name>` command still works but prints a deprecation warning — use `env add <name>` (with the env already registered) and pick **Relink to a different Supabase project**. The top-level `agentlink deploy` command has been removed entirely; use `agentlink env deploy` instead.
+
+### `agentlink check`
+
+Verify project setup. Outputs JSON with diagnostic info: `ready`, `supabase_running`, database state (extensions, queues, functions, secrets, api_schema), and file checks.
+
+```bash
+agentlink check
+agentlink check --env prod    # Check a specific cloud env
+```
+
+### `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`
+
+Database operations. Every subcommand targets the active cloud env (`manifest.cloud.default`) unless `--env <name>` or `--db-url <url>` is passed.
+
+#### `db apply`
+
+Apply all schema files in `supabase/schemas/` to the database using pg-delta declarative apply. Generates TypeScript types afterwards unless `--skip-types` is set.
+
+```bash
+agentlink db apply
+agentlink db apply --skip-types
+agentlink db apply --env prod
+agentlink db apply --db-url postgresql://...
+```
+
+#### `db migrate <name>`
+
+Generate a migration file from the diff between the current database state and the schema files. Intended for creating auditable deployment artifacts — `env deploy` does NOT generate migrations.
+
+```bash
+agentlink db migrate add_charts_table
+agentlink db migrate add_charts_table --env prod
+```
+
+#### `db sql <query>`
+
+Run ad-hoc SQL against the active database. Uses `psql` locally, Management API for cloud.
+
+```bash
+agentlink db sql "SELECT count(*) FROM public.profiles"
+agentlink db sql "SELECT * FROM api.chart_list()" --json
+agentlink db sql "..." --env prod
+```
+
+#### `db types`
+
+Regenerate `src/types/database.ts` (Vite) or `types/database.ts` (Next.js) from the `api` schema.
+
+```bash
+agentlink db types
+agentlink db types --output custom/path.ts
+```
+
+#### `db rebuild`
+
+Nuke `supabase/migrations/*`, re-apply schemas, and regenerate a single baseline migration. Recovery path when migration state gets broken early in a project.
+
+```bash
+agentlink db rebuild
+```
+
+#### `db url [--fix]`
+
+Show the correct pooler DB URL for the active cloud env. `--fix` updates `.env.local` if the current value is stale.
+
+```bash
+agentlink db url
+agentlink db url --fix
+```
+
+#### `db password [value]`
+
+Show or set the stored DB password for the active cloud env's project.
+
+```bash
+agentlink db password                 # Prompt (masked) + save
+agentlink db password "new-password"  # Set directly
+```
+
+#### `db backup`
+
+Snapshot the current env's database into three SQL files following Supabase's recommended `db dump` triplet — `roles.sql` (role-only), `schema.sql` (definitions), and `data.sql` (COPY-formatted data, with the `storage.buckets_vectors` / `storage.vector_indexes` tables excluded). Files are written to `supabase/backups/<env>/<YYYY-MM-DDTHH-MM-SS>/`; each run creates a fresh timestamped subdirectory so previous snapshots are preserved.
+
+On first run, `supabase/backups/` is appended to the project's root `.gitignore` under an "Agent Link — database backups" comment. Idempotent on re-runs. Snapshots may contain real production data, so they're gitignored by default.
+
+```bash
+agentlink db backup                    # Active env (cloud.default, or local if none)
+agentlink db backup --env prod         # Target prod explicitly (shows ▲ Active env: prod if active)
+agentlink db backup --db-url "postgresql://..."  # Override URL entirely
+```
+
+Works on cloud envs, local Docker, and bare projects — doesn't require `supabase/schemas/` or any scaffolded files, just a reachable DB. Read-only; no cloud mutation.
+
+### `agentlink env config [subcommand] [env-name]`
+
+Apply one or more server-side config sections to a cloud env. The three subsystems are **independent** — run just the one that drifted, or `all` for a full re-apply. Same primitives used by `env add`'s initial bootstrap, so there's no config drift between first-time setup and re-applies.
+
+| Subcommand | What it does |
+|-----------|--------------|
+| `secrets` | Seed Vault (`SUPABASE_URL` / `SUPABASE_PUBLISHABLE_KEY` / `SUPABASE_SECRET_KEY`) **and** mirror to edge-function secrets under `SB_*` prefix (set-if-absent — user-set custom values survive). |
+| `db` | PATCH PostgREST to expose the `api` schema. |
+| `auth` | PATCH auth config (hooks + signup settings). |
+| `all` | Run all three in order. |
+
+Both positionals are optional — omit either (or both) for an interactive picker:
+
+```bash
+agentlink env config                      # Pick subcommand + env interactively
+agentlink env config secrets              # Secrets; env picker
+agentlink env config prod                 # Env=prod; subcommand picker
+agentlink env config secrets prod         # Both specified
+agentlink env config auth prod            # Just auth, against prod (confirms)
+agentlink env config all dev --yes        # Full re-apply to dev, no prompts
+agentlink env config secrets --env prod   # --env flag accepted for CI scripts
+```
+
+Idempotent. Works on bare projects (no `supabase/schemas` required). Cloud-only — `env config all local` is rejected.
+
+### `agentlink frontend <name>`
+
+Scaffold only the frontend template (no Supabase setup).
+
+```bash
+agentlink frontend my-app           # React + Vite
+agentlink frontend my-app --nextjs  # NextJS
+```
+
+> `agentlink template` is the previous name and still works, but prints a deprecation warning.
+
+## Typical workflows
+
+### First-time scaffold, iterate, deploy to prod
+
+```bash
+# 1. Scaffold a cloud dev project
+agentlink my-app --prompt "build a project tracker"
+
+# 2. Agent builds — you iterate locally, `db apply` runs against dev.
+
+# 3. Connect prod (creates a separate Supabase project)
+cd my-app
+agentlink env add prod
+
+# 4. Deploy
+agentlink env deploy prod        # Prompts y/N; deploys schemas + functions
+```
+
+### Agent-driven scaffold, user finishes in terminal
+
+```bash
+# 1. Agent (no browser access) scaffolds only — no Supabase touched
+agentlink my-app --skip-env --prompt "..."
+
+# 2. User, in their terminal:
+cd my-app
+agentlink env add dev            # OAuth opens browser, env is ready
+
+# 3. Continue with the agent — schemas are ready to apply.
+agentlink db apply
+```
+
+### Hotfix on prod
+
+```bash
+# Edit supabase/schemas/*.sql locally
+agentlink env deploy prod         # Pushes just the delta + functions
+```
+
+### Rebuild migration history early in a project
+
+```bash
+# Dev DB is messy, migration files are inconsistent
+agentlink db rebuild              # Wipes migrations, re-applies schemas, creates one baseline
+```
+
+## 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
+```
+
+## Development
+
+See [`DEVELOPMENT.md`](./DEVELOPMENT.md) for the internal dev guide (source file layout, template system, adding scaffolded files).