@supacloud/cli 0.15.0 → 0.17.0

package/README.md

@@ -146,6 +146,7 @@ supacloud-cli queue dlq --queue emails --limit 20
 supacloud-cli task_events inspect_webhook --ref abc123
 supacloud-cli database query --sql "select now()"
 supacloud-cli database query --ref abc123 --file ./queries/vector-search.sql
+supacloud-cli database migration_inventory --ref abc123
 supacloud-cli database push_migrations --ref abc123 --dir supabase/migrations --dry_run
 supacloud-cli supabase migration_new --name add_accounts
 supacloud-cli supabase db_diff --schema public --name add_accounts
@@ -154,22 +155,70 @@ supacloud-cli frontend list --ref abc123
 supacloud-cli branch create --name feature-orders --data_mode schema_only
 supacloud-cli branch promotion_plan --branch_ref preview123
 supacloud-cli branch promote --branch_ref preview123 --plan_checksum <sha256>
-supacloud-cli edge_functions deploy --ref abc123 --slug hello --path ./supabase/functions/hello
-supacloud-cli edge_functions deploy_bundle --ref abc123 --slug hello --files '{"index.ts":"export default { fetch: () => new Response(\"ok\") }"}'
-supacloud-cli edge_functions source --ref abc123 --slug hello --output ./hello.ts
-supacloud-cli edge_functions activate --ref abc123 --slug hello --version 3
+supacloud-cli edge_functions deploy --ref abc123 --slug hello --path ./supabase/functions/hello --expected-active-version absent
+supacloud-cli edge_functions deploy --ref abc123 --slug hello --prebundled-path ./dist/hello.js --expected-sha256 <sha256> --expected-active-version 4
+supacloud-cli edge_functions deploy_bundle --ref abc123 --slug hello --files '{"index.ts":"export default { fetch: () => new Response(\"ok\") }"}' --expected-active-version 7
+supacloud-cli edge_functions source --ref abc123 --slug hello --version 7 --output ./hello-v7.ts
+supacloud-cli edge_functions activate --ref abc123 --slug hello --version 3 --expected-active-version 8
 supacloud-cli scheduled_functions list --ref abc123
 supacloud-cli secrets upsert --ref abc123 --from-env API_KEY,WEBHOOK_SECRET
+supacloud-cli storage list_buckets --ref abc123
+supacloud-cli storage get_bucket --ref abc123 --bucket reports
+supacloud-cli storage create_bucket --ref abc123 --bucket reports --public false \
+  --file_size_limit 10485760 --allowed_mime_types "application/pdf,image/png"
+supacloud-cli storage update_bucket --ref abc123 --bucket reports \
+  --expected_revision <revision-from-get_bucket> \
+  --allowed_mime_types '["application/pdf"]'
+supacloud-cli storage delete_bucket --ref abc123 --bucket reports \
+  --expected_revision <revision-from-get_bucket> --require_empty true
 ```
 
+`database migration_inventory` reads the canonical migration ledger through the
+project-scoped Management API and prints only a validated JSON array. It rejects
+non-2xx responses, malformed entries, unsafe project refs, duplicate canonical
+migration versions, checksum
+drift, and statement-count mismatches instead of treating them as an empty
+ledger. `database list_migrations` remains available with its legacy SQL-backed,
+human-readable behavior.
+
+Bucket list/get output includes the metadata `revision`. Update and delete reject
+stale revisions with HTTP 409. Delete additionally requires `require_empty=true`;
+it never empties a bucket. Mutation receipts bind `project_ref`, `bucket_id`,
+`previous_revision`, and `new_revision` (`null` after delete).
+
+`database push_migrations` rejects a remote row that reuses a local migration
+name with another version, or a local version with another name, before either
+dry-run reporting or apply can continue. This keeps the preview consistent with
+the server conflict that would otherwise occur after deployment starts.
+
 `edge_functions deploy --path` bundles local TypeScript and dependencies with
 Bun and runs a local syntax check before upload. The Management API validates and
 normalizes the final server-side artifact against the multi-tenant Edge Runtime
 module policy consistently for CLI, Web Console, and direct API deployments.
+For an artifact already built and validated by release automation, use
+`deploy --prebundled-path <file> --expected-sha256 <64-lowercase-hex>`. The CLI
+holds the opened regular file while reading it, rejects metadata drift, invalid
+UTF-8, or a caller-hash mismatch before HTTP, and never passes the artifact in
+the process argument list. The Management API validates the hash and runtime
+policy again, rejects any normalization that would change the code, and stores
+the submitted bytes unchanged as both immutable source and runtime artifact.
+`--prebundled-path` is mutually exclusive with `--path`, `--code`, and
+`--minify`.
 `deploy_bundle --files` accepts a JSON object in shell usage.
 Use `source --output <file>` for large Functions so terminal or automation output
 limits cannot truncate the original TS/JS source code. The destination must not
-already exist.
+already exist. Add the positive version observed from `list` as
+`source --version <N>` to read the immutable release instead of the moving active
+pointer; this remains correct across an active-version A→B→A transition.
+
+`deploy`, `deploy_bundle`, and `activate` require
+`--expected-active-version <N|absent>`. Read the current positive integer
+version from `edge_functions list`; use `absent` only when creating a slug that
+does not yet exist. A stale value returns HTTP 409 without building, preheating,
+or activating another version. List output remains a JSON array with string
+`slug` and numeric `version` fields, while source output is exactly
+`{ "code": "..." }`. Release automation must use `source --version <N>` for a
+version-bound backup.
 
 `edge_functions activate` restores an existing immutable Function version and
 returns a machine-readable receipt containing the activated version and JWT
@@ -180,27 +229,50 @@ Mutation receipts use schema `supacloud.cli.release-control.v1`. An
 `OUTCOME_UNKNOWN` error means the server may have committed the mutation before
 the response was lost or failed validation; read back current state before any
 retry.
+Version `0` is reserved for service-internal legacy recovery and cannot be used
+as a public CLI/API activation target or expected active version.
+
+```json
+{
+  "schema": "supacloud.cli.release-control.v1",
+  "ok": true,
+  "operation": "edge_functions.deploy_bundle",
+  "project_ref": "abc123",
+  "slug": "hello",
+  "previous_active_version": "7",
+  "active_version": "8",
+  "version": "8",
+  "verify_jwt": true
+}
+```
 
 Scheduled Function lifecycle operations are also project-scoped:
 
 ```bash
 supacloud-cli scheduled_functions create --ref abc123 --name nightly \
   --slug cleanup --cron "0 2 * * *" --method POST
+supacloud-cli scheduled_functions get --ref abc123 --schedule_id <id>
 supacloud-cli scheduled_functions update --ref abc123 --schedule_id <id> \
-  --cron "0 3 * * *"
-supacloud-cli scheduled_functions delete --ref abc123 --schedule_id <id>
+  --expected_updated_at <updated_at-from-list> --cron "0 3 * * *"
+supacloud-cli scheduled_functions delete --ref abc123 --schedule_id <id> \
+  --expected_updated_at <updated_at-from-list>
 ```
 
 Schedule IDs are canonical UUIDv4 values returned by create/list. Cron values
 use bounded numeric five-field syntax with wildcards, lists, ranges, and steps;
 out-of-range endpoints and steps are rejected before HTTP dispatch.
+Update and delete require the exact canonical UTC `updated_at` returned by list.
+A stale revision fails with HTTP 409 and performs no mutation; read the list
+again before deciding whether to issue a new write.
 
 Use `--body_file ./payload.json` for a JSON-object request body. Header values
 must come from environment variables: pass a JSON name mapping such as
 `--header_env '{"x-schedule-token":"SCHEDULE_TOKEN"}'`. Platform-owned
 `authorization`, `apikey`, and `x-project-ref` headers cannot be overridden. Receipts never
 include header values or body content; list and mutation receipts report only
-whether the body is empty and the configured header names.
+whether the body is empty and the configured header names. Update receipts bind
+`previous_updated_at` to the requested revision and return a newer `updated_at`;
+delete receipts return the matched revision as `deleted_updated_at`.
 
 For secret writes, `--from-env` accepts a comma-separated list of environment
 variable names. The CLI reads each non-empty value from its own process