@supacloud/admin 0.8.2 → 0.10.0

package/README.md

@@ -6,12 +6,59 @@ Platform administration CLI for SupaCloud operators.
 
 Typical environment variables:
 
+- `SUPACLOUD_ENV` — environment identity such as `test` or `production`
+- `SUPACLOUD_READ_ONLY=true` — block every remote write
 - `SUPACLOUD_HOST`
 - `SUPACLOUD_SSH_KEY` or `SUPACLOUD_SSH_PASS`
 - `SUPACLOUD_SSH_HOST_FINGERPRINT` — required for SSH actions, in OpenSSH `SHA256:<base64>` form
 - `SUPACLOUD_API_URL`
 - `SUPACLOUD_API_TOKEN`
 
+## Environment selection and production confirmation
+
+Use `--env <name>` to load `.env.supacloud.<name>` from the current directory,
+or `--env-file <path>` to load one exact file. Every selected file must declare
+`SUPACLOUD_ENV`; a named file's declared value must match the selector. Global
+flags may appear before or after the command.
+
+Selected files are atomic context sources: Admin does not fill missing API,
+project, SSH, credential, or safety values from the process environment or a
+different dotenv file. Without a selector, a complete process context declaring
+`SUPACLOUD_ENV` is used as one source. If that process context is incomplete,
+`SUPACLOUD_ENV` selects `.env.supacloud.<value>` instead. The legacy `.env`
+fallback remains available only when no Admin context variables are present in
+the process.
+
+Production writes require `--confirm-production` before any HTTP or SSH action:
+
+- Project-scoped writes use the exact requested project ref. If the selected
+  profile declares `SUPACLOUD_PROJECT_REF`, an explicit different ref is
+  rejected for both reads and writes.
+- Platform API writes that genuinely have no project ref use
+  `platform:<API host>`, for example `platform:management.example.com`.
+- SSH writes that genuinely have no project ref use `host:<SSH host[:port]>`,
+  for example `host:production.example.com:2201`.
+
+A generic value such as `production` is never accepted. Project-scoped actions
+that omit a required ref do not fall back to a platform or host confirmation.
+`SUPACLOUD_READ_ONLY=true` blocks every remote write in every environment,
+including when it is set only in the process environment. Remote writes also
+require an explicit `SUPACLOUD_ENV`; unclassified process and legacy dotenv
+contexts remain usable for read-only actions but cannot mutate remote state.
+
+Management API URLs must be origin-and-path URLs without credentials, query
+strings, or fragments. This prevents URL-embedded secrets from being sent to a
+remote target or displayed by `status` and `--help`.
+
+```bash
+npx @supacloud/admin --env test status
+npx @supacloud/admin --env production project delete \
+  --ref abc123 --confirm-production abc123
+npx @supacloud/admin --env production ssh upgrade \
+  --version 0.50.31 --edge_runtime_version 0.16.8 \
+  --confirm-production host:production.example.com:2201
+```
+
 SSH host keys are fail-closed: setting `SUPACLOUD_HOST` and credentials is not
 enough to enable SSH actions. Obtain the fingerprint through a trusted channel,
 compare it out of band, then set it explicitly. For example, the discovery
@@ -29,8 +76,11 @@ npx @supacloud/admin status
 npx @supacloud/admin ssh ping
 npx @supacloud/admin ssh versions
 npx @supacloud/admin ssh diagnose
-npx @supacloud/admin project create --name my-app --domain example.com
+npx @supacloud/admin project create --name my-app --domain example.com \
+  --env_file /secure/path/.env.project-credentials.test --environment test
 npx @supacloud/admin project list
+npx @supacloud/admin project services --ref abc123
+npx @supacloud/admin project service_control --ref abc123 --service gotrue --service_action stop
 ```
 
 `ssh versions` emits JSON with `schema_version: 1` and fixed
@@ -106,6 +156,84 @@ Project commands owned by this CLI:
 - `project restore`
 - `project restart`
 - `project update_settings`
+- `project services` — read-only project service inventory
+- `project service_control` — constrained project service lifecycle control
+
+`project create` never prints project credentials. Pass an absolute
+`--env_file` path to explicitly request one-time service-role delivery. This
+mode requires both a complete bare `--api_domain` (or bare base `--domain`)
+and an exact `--environment test|production`; invalid or missing bindings fail
+before the remote project mutation. `--environment` is used only in the local
+credential file and is never sent to the Management API. Credential delivery is
+supported only on Linux, where Admin holds the canonical parent directory open
+and performs create, verification, and cleanup through `/proc/self/fd`. macOS
+and Windows fail with `ENV_FILE_PLATFORM_UNSUPPORTED` before creating a file or
+requesting remote credentials. On Linux, the target is exclusively reserved at
+mode `0600` before the remote mutation. The direct parent must be owned by the
+Admin process user. Every ancestor must be owned by root or that user and must
+not grant group/world write access; paths below writable sticky directories
+such as `/tmp` are rejected. Parent ownership, mode, and device/inode identity,
+plus file ownership, mode, and device/inode identity, are checked before and
+after writing through the held parent descriptor. The file and parent directory
+are synced before success is reported.
+The response API URL and project name must exactly match the request binding;
+the origin comparison includes the port. Existing files, symlinks, replaced
+parents, non-canonical paths, and missing or untrusted directories are rejected.
+The recommended name is
+`.env.project-credentials.<environment>`; verify that the target repository
+ignores it before running the command (SupaCloud's own `.env.*` rule does).
+This is an application credential file, not a SupaCloud Admin/Management
+profile: Admin rejects it before registering HTTP tools, so never select it
+with `supacloud-admin --env` or `--env-file`. Selected Admin files that contain
+project application credentials must also contain an explicit Management API
+URL and `SUPACLOUD_API_TOKEN`; Admin never substitutes the service-role key.
+The generated file contains only `SUPACLOUD_ENV`, `SUPACLOUD_PROJECT_REF`,
+`SUPABASE_URL`, and `SUPABASE_SERVICE_ROLE_KEY`; the public project origin is deliberately not
+written as `SUPACLOUD_API_URL`, which Admin reserves for the Management API.
+The success receipt marks `env_file_scope` as `project_application`. Standard
+output otherwise contains only credential-free fields. Supply
+`SUPACLOUD_API_TOKEN` through the process environment, never as a command
+argument.
+
+If the remote project is created but local env writing fails, the error receipt
+retains only the safe project ref and API URL, sets `remote_created: true` and
+`retry_safe: false`, and never includes the credential. A
+`credential_file_state: "absent"` receipt confirms cleanup and includes
+`credentials_written: false`. A `credential_file_state: "unknown"` receipt
+omits `credentials_written`; treat the target path as secret-bearing until an
+operator securely removes it or completes credential recovery/rotation. Repair
+the local path only after reading back the existing project and following that
+recovery flow; never blindly retry project creation.
+
+Service control accepts canonical service names only. `postgrest` supports
+`start`, `stop`, `restart`, `pause`, `resume`, and `status`; `gotrue`, `storage`,
+`postgresql`, `realtime`, and `gateway` support `start`, `stop`, and `restart`.
+The command calls only the Management API's existing
+`/v1/projects/{ref}/services` routes. A non-2xx response, a `success: false`
+receipt, or a response that does not match the requested service and action
+exits non-zero. Successful inventory and control responses are emitted as JSON
+with `project_ref` for strict read-back.
+
+The Management API remains authoritative for SupAuth ownership. Controlling
+GoTrue on a shared-auth project fails with `AUTH_RUNTIME_MANAGED_BY_OWNER`;
+the CLI does not redirect the operation to the owner project. Supply
+`SUPACLOUD_API_TOKEN` through the environment only; service-control commands do
+not accept credential flags.
+
+Create a completed full physical backup before a release with:
+
+```bash
+supacloud-admin platform create_backup --ref abc123 --backup_type full
+```
+
+The command reads the physical backup inventory before the write and performs
+one bounded reconciliation read after every mutation attempt. It exits non-zero
+unless the API confirms success and the inventory contains exactly one new,
+completed full backup with a nonzero size. The Management API rejects unknown
+project refs and resolves inventory from the persisted project database name.
+The JSON receipt contains only the project ref, requested type, backup ID,
+database, timestamps, and size. `platform list_backups --ref abc123` applies the
+same strict, sanitized inventory validation without creating a backup.
 
 Gateway / Caddy commands (config is injected via the Caddy JSON Admin API; requires admin privileges):