agentlink-sh 0.28.0 → 0.30.0

package/README.md

@@ -4,68 +4,64 @@ 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
+## Run
 
-Install cli globally.
-
-```bash
-npm i -g agentlink-sh@latest
-```
-
-Or run directly with npx (requires Node.js 18+):
+Run directly with `npx` (requires Node.js 18+):
 
 ```bash
 npx agentlink-sh@latest
 ```
 
+`npx` always pulls the latest version. There's no global install step — every command below is prefixed with `npx agentlink-sh@latest`.
+
 ## Quick start
 
 ```bash
 # Create a new project (cloud by default)
-agentlink my-app
+npx agentlink-sh@latest my-app
 
 # With a prompt for Claude Code
-agentlink my-app --prompt "Build a project management tool with kanban boards"
+npx agentlink-sh@latest my-app --prompt "Build a project management tool with kanban boards"
 
 # Interactive wizard
-agentlink
+npx agentlink-sh@latest
 ```
 
 ## Commands
 
-### `agentlink [name]`
+### `npx agentlink-sh@latest [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
+npx agentlink-sh@latest
 
 # With project name
-agentlink my-app
+npx agentlink-sh@latest my-app
 
 # With prompt (passed to Claude Code on launch)
-agentlink my-app --prompt "Build a project management tool"
+npx agentlink-sh@latest my-app --prompt "Build a project management tool"
 
 # Local Docker mode (instead of cloud)
-agentlink my-app --local
+npx agentlink-sh@latest my-app --local
 
 # NextJS instead of React + Vite
-agentlink my-app --nextjs
+npx agentlink-sh@latest my-app --nextjs
 
 # Backend only (no frontend)
-agentlink my-app --no-frontend
+npx agentlink-sh@latest my-app --no-frontend
 
 # Skip companion skills
-agentlink my-app --no-skills
+npx agentlink-sh@latest 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
+npx agentlink-sh@latest my-app --skip-env
 
 # Non-interactive (CI-friendly)
-agentlink my-app --yes --non-interactive --token $SUPABASE_TOKEN --org $ORG_ID --region us-east-1
+npx agentlink-sh@latest my-app --yes --non-interactive --token $SUPABASE_TOKEN --org $ORG_ID --region us-east-1
 ```
 
 **Options:**
@@ -89,26 +85,26 @@ agentlink my-app --yes --non-interactive --token $SUPABASE_TOKEN --org $ORG_ID -
 | `--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`
+### `npx agentlink-sh@latest 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
+npx agentlink-sh@latest 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.
+> The top-level `login` / `token` commands still work but print a deprecation warning. The top-level `login` namespace is reserved for future Agent Link accounts.
 
-### `agentlink sb token`
+### `npx agentlink-sh@latest 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
+npx agentlink-sh@latest sb token show           # Print the current token and its source
+npx agentlink-sh@latest sb token set sbp_...    # Save a new token
 ```
 
-### `agentlink env`
+### `npx agentlink-sh@latest env`
 
 Manage project environments. Agent Link enforces a fixed `local → dev → prod` model — no custom names (`staging`, `dev2`, etc. are rejected).
 
@@ -117,17 +113,17 @@ Manage project environments. Agent Link enforces a fixed `local → dev → prod
 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
+npx agentlink-sh@latest env add              # Interactive picker
+npx agentlink-sh@latest env add dev          # Connect the dev cloud environment
+npx agentlink-sh@latest env add prod         # Connect production. Does NOT touch .env.local.
+npx agentlink-sh@latest env add dev --no-deploy    # Register the env but skip the initial deploy
+npx agentlink-sh@latest 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.
+  If you just changed schemas or functions, cancel and run `npx agentlink-sh@latest env deploy <name>` instead.
 
 ? Environment "dev" already exists. What would you like to do?
 ❯ Re-apply full setup — schemas, functions, secrets, PostgREST + auth config
@@ -142,10 +138,10 @@ If the environment already exists, `env add` prompts with a 3-way menu:
 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)
+npx agentlink-sh@latest env use              # Interactive picker
+npx agentlink-sh@latest env use dev          # Switch to dev
+npx agentlink-sh@latest env use local        # Switch to local Docker
+npx agentlink-sh@latest 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.
@@ -155,11 +151,11 @@ agentlink env use prod         # Switch to prod (requires y/N confirmation)
 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
+npx agentlink-sh@latest env deploy              # Interactive picker (preselects cloud.default)
+npx agentlink-sh@latest env deploy dev          # Deploy to dev
+npx agentlink-sh@latest env deploy prod         # Deploy to prod (requires y/N confirmation)
+npx agentlink-sh@latest env deploy prod --yes   # Skip the confirmation (for CI)
+npx agentlink-sh@latest 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.
@@ -171,7 +167,7 @@ Generated CI workflows (`env add --setup-ci`) call `env deploy <name> --yes --no
 Show all configured environments with their org, project ref, and which one is currently active.
 
 ```bash
-agentlink env list
+npx agentlink-sh@latest env list
 ```
 
 #### `env remove <name>`
@@ -179,31 +175,31 @@ agentlink env list
 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
+npx agentlink-sh@latest env remove prod
+npx agentlink-sh@latest 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.
+> The previous `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 `deploy` command has been removed entirely; use `env deploy` instead.
 
-### `agentlink check`
+### `npx agentlink-sh@latest 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
+npx agentlink-sh@latest check
+npx agentlink-sh@latest check --env prod    # Check a specific cloud env
 ```
 
-### `agentlink info [name]`
+### `npx agentlink-sh@latest 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
+npx agentlink-sh@latest info                # List all components
+npx agentlink-sh@latest info tenant_select  # Detail for one component
 ```
 
-### `agentlink db`
+### `npx agentlink-sh@latest db`
 
 Database operations. Every subcommand targets the active cloud env (`manifest.cloud.default`) unless `--env <name>` or `--db-url <url>` is passed.
 
@@ -212,10 +208,10 @@ Database operations. Every subcommand targets the active cloud env (`manifest.cl
 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://...
+npx agentlink-sh@latest db apply
+npx agentlink-sh@latest db apply --skip-types
+npx agentlink-sh@latest db apply --env prod
+npx agentlink-sh@latest db apply --db-url postgresql://...
 ```
 
 #### `db migrate <name>`
@@ -223,8 +219,8 @@ agentlink db apply --db-url postgresql://...
 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
+npx agentlink-sh@latest db migrate add_charts_table
+npx agentlink-sh@latest db migrate add_charts_table --env prod
 ```
 
 #### `db sql <query>`
@@ -232,9 +228,9 @@ agentlink db migrate add_charts_table --env prod
 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
+npx agentlink-sh@latest db sql "SELECT count(*) FROM public.profiles"
+npx agentlink-sh@latest db sql "SELECT * FROM api.chart_list()" --json
+npx agentlink-sh@latest db sql "..." --env prod
 ```
 
 #### `db types`
@@ -242,8 +238,8 @@ agentlink db sql "..." --env prod
 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
+npx agentlink-sh@latest db types
+npx agentlink-sh@latest db types --output custom/path.ts
 ```
 
 #### `db rebuild`
@@ -251,7 +247,7 @@ agentlink db types --output custom/path.ts
 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
+npx agentlink-sh@latest db rebuild
 ```
 
 #### `db url [--fix]`
@@ -259,8 +255,8 @@ agentlink db rebuild
 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
+npx agentlink-sh@latest db url
+npx agentlink-sh@latest db url --fix
 ```
 
 #### `db password [value]`
@@ -268,8 +264,8 @@ agentlink db url --fix
 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
+npx agentlink-sh@latest db password                 # Prompt (masked) + save
+npx agentlink-sh@latest db password "new-password"  # Set directly
 ```
 
 #### `db backup`
@@ -279,14 +275,14 @@ Snapshot the current env's database into three SQL files following Supabase's re
 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
+npx agentlink-sh@latest db backup                    # Active env (cloud.default, or local if none)
+npx agentlink-sh@latest db backup --env prod         # Target prod explicitly (shows ▲ Active env: prod if active)
+npx agentlink-sh@latest 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]`
+### `npx agentlink-sh@latest 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.
 
@@ -300,27 +296,27 @@ Apply one or more server-side config sections to a cloud env. The three subsyste
 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
+npx agentlink-sh@latest env config                      # Pick subcommand + env interactively
+npx agentlink-sh@latest env config secrets              # Secrets; env picker
+npx agentlink-sh@latest env config prod                 # Env=prod; subcommand picker
+npx agentlink-sh@latest env config secrets prod         # Both specified
+npx agentlink-sh@latest env config auth prod            # Just auth, against prod (confirms)
+npx agentlink-sh@latest env config all dev --yes        # Full re-apply to dev, no prompts
+npx agentlink-sh@latest 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>`
+### `npx agentlink-sh@latest frontend <name>`
 
 Scaffold only the frontend template (no Supabase setup).
 
 ```bash
-agentlink frontend my-app           # React + Vite
-agentlink frontend my-app --nextjs  # NextJS
+npx agentlink-sh@latest frontend my-app           # React + Vite
+npx agentlink-sh@latest frontend my-app --nextjs  # NextJS
 ```
 
-> `agentlink template` is the previous name and still works, but prints a deprecation warning.
+> `frontend` replaces the previous `template` command, which still works but prints a deprecation warning.
 
 ## Typical workflows
 
@@ -328,44 +324,44 @@ agentlink frontend my-app --nextjs  # NextJS
 
 ```bash
 # 1. Scaffold a cloud dev project
-agentlink my-app --prompt "build a project tracker"
+npx agentlink-sh@latest 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
+npx agentlink-sh@latest env add prod
 
 # 4. Deploy
-agentlink env deploy prod        # Prompts y/N; deploys schemas + functions
+npx agentlink-sh@latest 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 "..."
+npx agentlink-sh@latest my-app --skip-env --prompt "..."
 
 # 2. User, in their terminal:
 cd my-app
-agentlink env add dev            # OAuth opens browser, env is ready
+npx agentlink-sh@latest env add dev            # OAuth opens browser, env is ready
 
 # 3. Continue with the agent — schemas are ready to apply.
-agentlink db apply
+npx agentlink-sh@latest db apply
 ```
 
 ### Hotfix on prod
 
 ```bash
 # Edit supabase/schemas/*.sql locally
-agentlink env deploy prod         # Pushes just the delta + functions
+npx agentlink-sh@latest 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
+npx agentlink-sh@latest db rebuild              # Wipes migrations, re-applies schemas, creates one baseline
 ```
 
 ## What it does
@@ -386,7 +382,7 @@ The scaffold runs a multi-step process:
 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.
+Running `npx agentlink-sh@latest` 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
 

package/dist/{chunk-ILLYV7U7.js → chunk-KECTTRCF.js}

@@ -40,6 +40,17 @@ var SUPPORTED_PGDELTA = pgdeltaPkg.version;
 function pgdeltaBin() {
   return path.join(pgdeltaDir(), "dist", "cli", "bin", "cli.js");
 }
+var PINNED_PNPM_VERSION = "10.34.1";
+var PACKAGE_MANAGER_FIELD = `pnpm@${PINNED_PNPM_VERSION}`;
+var PNPM_INSTALL_CMD = "corepack pnpm install";
+var COREPACK_ENV = {
+  COREPACK_ENABLE_DOWNLOAD_PROMPT: "0"
+};
+var ONLY_BUILT_DEPENDENCIES = [
+  "@tailwindcss/oxide",
+  "esbuild",
+  "supabase"
+];
 function pgd() {
   return `${JSON.stringify(process.execPath)} ${JSON.stringify(pgdeltaBin())}`;
 }
@@ -48,6 +59,7 @@ var POSTGREST_CONFIG = {
   db_extra_search_path: "public, extensions",
   max_rows: 1e3
 };
+var AUTH_RATE_LIMIT_EMAIL_SENT = 1e3;
 var AUTH_CONFIG = {
   hook_send_email_enabled: true,
   hook_send_email_uri: "pg-functions://postgres/public/_hook_send_email",
@@ -62,7 +74,17 @@ var AUTH_CONFIG = {
   security_refresh_token_reuse_interval: 10,
   external_anonymous_users_enabled: false,
   password_min_length: 8,
-  mailer_autoconfirm: false
+  mailer_autoconfirm: false,
+  // 8-digit email OTP — kept in sync with config.toml's auth.email.otp_length
+  // so the verify-OTP flow is identical on local and deployed environments.
+  mailer_otp_length: 8,
+  // Lifted alongside `hook_send_email_enabled: true` above — once the send
+  // hook is on, auth emails go through our edge function (Resend), not
+  // Supabase's tiny built-in test pool. Leaving Supabase's stock 2/hour
+  // default in place would silently throttle real signup load even though
+  // the underlying provider can handle thousands. See the constant's
+  // docblock for the choice of 1000 and the dashboard-override caveat.
+  rate_limit_email_sent: AUTH_RATE_LIMIT_EMAIL_SENT
 };
 var AUTH_CONFIG_DEV_OVERRIDES = {
   mailer_autoconfirm: true
@@ -73,17 +95,43 @@ var RESEND_SMTP = {
   user: "resend"
 };
 
+// src/theme.ts
+var rgb = (r, g, b) => (s) => `\x1B[38;2;${r};${g};${b}m${s}\x1B[0m`;
+var blue = rgb(92, 184, 228);
+var amber = rgb(232, 168, 56);
+var red = rgb(239, 68, 68);
+var dim = (s) => `\x1B[2m${s}\x1B[0m`;
+var bold = (s) => `\x1B[1m${s}\x1B[0m`;
+var link = (url, label) => `\x1B]8;;${url}\x07${label ?? url}\x1B]8;;\x07`;
+function deprecated(oldCmd, newCmd) {
+  console.error(
+    amber(
+      `Warning: \`${oldCmd}\` is deprecated and will be removed in the next major version. Use \`${newCmd}\` instead.`
+    )
+  );
+}
+
 export {
   SUPPORTED_SUPABASE_CLI,
   OAUTH_CLIENT_ID,
   OAUTH_CLIENT_SECRET,
   supabaseBin,
   sb,
-  SUPPORTED_PGDELTA,
   pgdeltaBin,
+  PACKAGE_MANAGER_FIELD,
+  PNPM_INSTALL_CMD,
+  COREPACK_ENV,
+  ONLY_BUILT_DEPENDENCIES,
   pgd,
   POSTGREST_CONFIG,
   AUTH_CONFIG,
   AUTH_CONFIG_DEV_OVERRIDES,
-  RESEND_SMTP
+  RESEND_SMTP,
+  blue,
+  amber,
+  red,
+  dim,
+  bold,
+  link,
+  deprecated
 };