@supacloud/cli 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/cli",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Project-scoped CLI for SupaCloud users",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,7 +9,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "scripts": {
     "dev": "bun run --watch src/index.ts",
@@ -30,7 +31,7 @@
     "directory": "packages/cli"
   },
   "dependencies": {
-    "zod": "^4.4.3"
+    "@sinclair/typebox": "^0.34.52"
   },
   "devDependencies": {
     "@types/bun": "^1.3.14",

package/skills/supacloud-cli/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: supacloud-cli
+description: Use when operating, implementing, diagnosing, deploying, or documenting a SupaCloud project through supacloud-cli, especially database schema, functions/RPC, triggers, RLS, indexes, grants, extensions, migrations, backups, auth, storage, Edge Functions, frontend, queues, task events, diagnostics, or gateway work. Also use when an AI might otherwise call SQL, psql, a database API, or the Management API directly.
+---
+
+# SupaCloud CLI
+
+Use `supacloud-cli` as the project-level control surface and keep durable changes reproducible from version-controlled files. Use `supacloud-admin` only for server/platform operations.
+
+## Non-negotiable rules
+
+1. Inspect repository state and project context before any action:
+
+   ```bash
+   git status --short --branch
+   supacloud-cli status
+   ```
+
+   A missing remote project context does not block local `migration_new`, `db_diff`, or `db_reset`; it blocks remote inspection/apply until context is supplied.
+
+2. Never place secrets, service-role keys, database URLs, passwords, or tokens in commands that will be logged, source files, migration files, or chat output.
+3. Treat schema, functions/RPC, triggers, RLS policies, indexes, grants, extensions, and seed/reference-data changes as migrations. Do not apply them through `database query`, `psql`, a dashboard SQL editor, or a raw Management API call.
+4. Use `database query` only for read-only inspection unless the user explicitly authorizes a documented break-glass operation. Break-glass work still requires a backup, rollback SQL, and a follow-up migration in the same task.
+5. Run a remote migration dry-run before apply. Production apply requires explicit user approval in the current task.
+6. Do not edit `supabase_migrations.schema_migrations` through ordinary SQL. Migration history is an application ledger, not a schema backup or source of truth. For a proven-equivalent historical baseline, use the controlled `database baseline_migrations` action with dry-run and explicit approval.
+7. Service-role credentials authenticate the SupaCloud Management API. Never reinterpret them as PostgreSQL passwords or forward them to the official Supabase CLI.
+
+## Workflow
+
+1. Classify the request using [references/command-map.md](references/command-map.md).
+2. For database work, load [references/database-workflow.md](references/database-workflow.md) and choose either new-change or historical-drift reconciliation.
+3. Prefer the smallest read-only inspection that proves current state.
+4. Create or update version-controlled artifacts before remote writes.
+5. Verify locally, inspect the diff, and run the narrowest relevant tests.
+6. Preview remote changes with `--dry_run`.
+7. Apply only within the user-authorized environment and scope.
+8. Read back migration history and affected resources; report exact evidence and any remaining drift.
+
+## Database default
+
+For a new database change:
+
+```bash
+supacloud-cli supabase migration_new --name add_accounts
+# Edit the generated SQL migration.
+supacloud-cli supabase db_reset --no_seed
+supacloud-cli supabase push --ref <project-ref> --dir supabase/migrations --dry_run
+# Apply only after explicit approval.
+supacloud-cli supabase push --ref <project-ref> --dir supabase/migrations
+```
+
+Use `db_diff` as an authoring aid, not as permission to bypass review:
+
+```bash
+supacloud-cli supabase db_diff --schema public --name reconcile_public_schema
+```
+
+For a database that was previously changed directly, stop further direct writes and follow the reconciliation workflow in [references/database-workflow.md](references/database-workflow.md). Do not push guessed historical migrations against a live database. After schema equivalence is proven, preview and record the baseline through:
+
+```bash
+supacloud-cli database baseline_migrations \
+  --ref <project-ref> \
+  --dir supabase/migrations \
+  --dry_run
+```
+
+## CLI boundaries
+
+- `supacloud-cli`: project status, database, migrations, auth, storage, Edge Functions, frontend, queues, task events, diagnostics, and project gateway configuration.
+- `supacloud-admin`: installation, upgrades, SSH diagnostics, platform-wide project lifecycle, tenant runtime, and server operations.
+- Official `supabase` CLI: invoked only through the allowlisted `supacloud-cli supabase` adapter for supported local authoring or explicit-DSN inspection commands.
+- Direct HTTP/SQL: read-only diagnosis or an explicitly approved break-glass path; never the default implementation path.
+
+## Completion evidence
+
+Before declaring success, provide:
+
+- migration filenames and reviewed diff;
+- local reset/test/typecheck evidence appropriate to the project;
+- remote dry-run evidence;
+- explicit approval reference for production apply;
+- applied migration/read-back evidence;
+- backup and rollback references for destructive or reconciliation work.

package/skills/supacloud-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SupaCloud CLI"
+  short_description: "安全使用 SupaCloud CLI 与数据库迁移"
+  default_prompt: "Use $supacloud-cli to manage this SupaCloud project through migrations and safe CLI workflows."

package/skills/supacloud-cli/references/command-map.md

@@ -0,0 +1,50 @@
+# SupaCloud CLI command map
+
+Load this reference when selecting a command surface or when a user asks an AI to “just change the database.”
+
+## Decision table
+
+| Intent | Use | Guardrail |
+| --- | --- | --- |
+| Inspect current project binding | `supacloud-cli status` | Read-only; run first |
+| Inspect project health/logs/tasks | `project`, `queue`, `task_events`, `diagnostics` | Prefer bounded reads |
+| Read database rows or metadata | `database query` and database inspection actions | `SELECT`/read-only by default |
+| Create schema/function/RPC/trigger/RLS/index/grant/extension | `supabase migration_new`, then edit SQL | Never direct remote DDL |
+| Generate migration from local schema changes | `supabase db_diff` | Review generated SQL before use |
+| Rebuild local database | `supabase db_reset` | Local only; preserve required seed behavior |
+| Inspect or back up a remote database | `supabase db_pull`, `migration_list`, `db_dump`, `gen_types` | Requires explicit PostgreSQL DSN; redact it |
+| Preview/apply migrations remotely | `supabase push` | Always dry-run first; production needs explicit approval |
+| Mark proven-equivalent historical migrations as applied | `database baseline_migrations` | Dry-run, schema-equivalence proof, backup, explicit approval |
+| Manage Auth/Storage/Edge Functions/frontend/secrets | Corresponding project module | Keep deployable config/code in version control |
+| Configure project gateway routes | `gateway` | Requires an admin-capable project token; inspect before write |
+| Install/upgrade/debug SupaCloud servers | `supacloud-admin` | Platform boundary; not a project CLI action |
+
+If `status` reports missing project context, local migration authoring may still
+continue. Do not attempt remote inspection, baseline, push, or resource changes
+until a project-scoped context is resolved.
+
+## Command groups
+
+- `status`: resolved context, Management API connectivity, authentication, and project reachability.
+- `project`: project metadata, health, logs, API keys/settings, background tasks, retry/cancel, DLQ, and background settings.
+- `database`: read/query, schema inspection, extensions, indexes, RLS, stats, migration push, controlled historical baseline, and SQL-file execution.
+- `supabase`: allowlisted official CLI adapter for migration authoring, local reset/diff, explicit-DSN inspection/backup/type generation, and SupaCloud-controlled migration push.
+- `auth`: provider and authentication configuration.
+- `storage`: buckets and object-management workflows.
+- `edge_functions`: deploy and configure Edge Functions.
+- `frontend`: list, build/deploy, domain, and deployment workflows.
+- `secrets`: project secret management; never print values after write.
+- `queue`, `task_events`, `diagnostics`: asynchronous workload operations and bounded diagnostics.
+- `gateway`: project route/config/rebuild operations.
+- `ai`: inspect or install this packaged Skill.
+
+## Safe inspection pattern
+
+```bash
+supacloud-cli status
+supacloud-cli project get
+supacloud-cli project health
+supacloud-cli supabase migration_list --db_url "$SUPACLOUD_DB_URL"
+```
+
+Do not paste the DSN value into chat or commit it to shell scripts. Prefer an environment variable supplied outside the repository.

package/skills/supacloud-cli/references/database-workflow.md

@@ -0,0 +1,112 @@
+# Database migration and drift workflow
+
+Migration files are the durable source of truth. `supabase_migrations.schema_migrations` records what the controlled migration path applied; it does not discover console/`psql` changes and does not reconstruct the current schema.
+
+## New changes
+
+1. Inspect the repository, existing migrations, migration history, and relevant schema.
+2. Create a migration:
+
+   ```bash
+   supacloud-cli supabase migration_new --name <intent>
+   ```
+
+3. Put tables, views, functions/RPC, triggers, RLS, indexes, grants, extensions, and required reference data in the generated SQL file.
+4. Make migrations deterministic and reviewable:
+   - qualify schemas;
+   - avoid environment-specific IDs, domains, and secrets;
+   - use transactions when the operation supports them;
+   - document destructive statements and rollback strategy;
+   - avoid modifying an already-applied migration.
+5. Rebuild locally and run application tests:
+
+   ```bash
+   supacloud-cli supabase db_reset --no_seed
+   ```
+
+6. Preview remote application:
+
+   ```bash
+   supacloud-cli supabase push --ref <project-ref> --dir supabase/migrations --dry_run
+   ```
+
+7. After explicit environment approval, apply and read back migration history.
+
+## Previously changed remote database
+
+Do not fabricate old migration files and immediately push them. Reconcile deliberately:
+
+1. Freeze direct SQL/dashboard writes for the reconciliation window.
+2. Inventory three states separately:
+   - version-controlled migration files;
+   - remote migration-history rows;
+   - actual remote schema/functions/policies/grants.
+3. Create a schema-only backup before changing tracking or schema:
+
+   ```bash
+   supacloud-cli supabase db_dump \
+     --db_url "$SUPACLOUD_DB_URL" \
+     --file backups/pre-reconcile-schema.sql
+   ```
+
+4. In an isolated branch/worktree, pull the actual remote schema:
+
+   ```bash
+   supacloud-cli supabase db_pull \
+     --db_url "$SUPACLOUD_DB_URL" \
+     --declarative \
+     --name remote_baseline
+   ```
+
+5. Review the generated artifacts. Remove ownership, secret, environment-specific, and extension noise that should not be portable.
+6. Choose one strategy:
+   - Empty/new migration repository: establish a reviewed baseline representing the current remote schema.
+   - Existing migration repository: keep applied migrations immutable and add one reconciliation migration for the verified delta.
+7. Prove the chosen migration set can recreate the desired schema from a clean local database. Compare the recreated schema with the captured remote schema.
+8. Only after equivalence is proven, preview the controlled baseline action:
+
+   ```bash
+   supacloud-cli database baseline_migrations \
+     --ref <project-ref> \
+     --dir supabase/migrations \
+     --dry_run
+   ```
+
+9. Review every file listed under `Would mark as applied`. Obtain explicit approval, then rerun without `--dry_run`. This action records the selected local migration files through the SupaCloud migration-mode API; it does not execute their DDL.
+10. Never insert/update/delete `supabase_migrations.schema_migrations` via `database query`. If the controlled baseline action cannot represent the verified state, stop and request operator assistance.
+11. Run `supabase push --dry_run`; it should report no unintended pending historical migration. Read back migration history and affected objects.
+
+## Functions, triggers, RLS, and grants
+
+These are schema objects even when business logic lives inside them. Keep them in migrations:
+
+- `CREATE OR REPLACE FUNCTION ...`
+- trigger creation/removal;
+- `ALTER TABLE ... ENABLE ROW LEVEL SECURITY`;
+- `CREATE POLICY` / `ALTER POLICY` / `DROP POLICY`;
+- role grants and default privileges;
+- extension enablement and version changes.
+
+For function replacement, verify signature, volatility, security definer/invoker behavior, `search_path`, ownership, grants, and callers. A function body diff without its security attributes is incomplete.
+
+## Backups and rollback
+
+- Schema backup: `supabase db_dump` with the default schema mode.
+- Data backup: use an approved data-backup path; do not assume schema dump includes application data.
+- Restore testing: prove the backup can be parsed/restored in an isolated database before relying on it.
+- Destructive migrations: prefer expand-contract rollout, record affected rows, and provide reversal or forward-fix SQL.
+- Migration history is not a backup. Keep backups outside the migration directory and exclude credentials from filenames/content.
+
+## Break-glass
+
+A direct remote write is acceptable only when waiting for the normal migration pipeline would cause greater harm and the user explicitly authorizes it. Before execution:
+
+1. record incident scope and exact target;
+2. take a relevant backup;
+3. prepare bounded SQL plus rollback SQL;
+4. show the SQL without secrets;
+5. receive explicit approval;
+6. execute once and read back;
+7. create the equivalent migration immediately so repository truth matches production.
+
+If any item is missing, stop instead of improvising a direct write.