@supacloud/admin 0.8.1 → 0.9.0

package/README.md

@@ -31,6 +31,8 @@ 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 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 +108,23 @@ 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
+
+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.
 
 Gateway / Caddy commands (config is injected via the Caddy JSON Admin API; requires admin privileges):
 

package/dist/index.js

@@ -25302,6 +25302,11 @@ async function removePartialUpload(sftp, partialPath, uploadError) {
 }
 
 // src/shared/cli.ts
+function cliToolResultIsError(toolResult) {
+  if (toolResult.isError === true)
+    return true;
+  return toolResult.content?.some((chunk) => chunk.type === "text" && chunk.text?.trimStart().startsWith("❌") === true) ?? false;
+}
 function coerceCliValue(value) {
   if (value === "true")
     return true;
@@ -25430,7 +25435,7 @@ async function runCli(cliTools, args, options = {}) {
     } else {
       console.log(JSON.stringify(result, null, 2));
     }
-    process.exit(result && typeof result === "object" && "isError" in result && result.isError === true ? 1 : 0);
+    process.exit(cliToolResultIsError(result) ? 1 : 0);
   } catch (error) {
     const message = formatCliError(error);
     console.error(`❌ Error: ${message}`);
@@ -28673,6 +28678,150 @@ ${JSON.stringify(r.data, null, 2)}` : `❌ Failed (${r.status})`;
 }
 
 // src/shared/tools/project-cli-tools.ts
+var PROJECT_SERVICE_NAMES = [
+  "postgrest",
+  "gotrue",
+  "storage",
+  "postgresql",
+  "realtime",
+  "gateway"
+];
+var PROJECT_SERVICE_CONTROL_ACTIONS = [
+  "start",
+  "stop",
+  "restart",
+  "pause",
+  "resume",
+  "status"
+];
+var STUDIO_PROJECT_SERVICE_NAMES = [
+  "db",
+  "rest",
+  "auth",
+  "realtime",
+  "storage"
+];
+var STUDIO_PROJECT_SERVICE_STATUSES = [
+  "ACTIVE_HEALTHY",
+  "COMING_UP",
+  "UNHEALTHY"
+];
+var AUTH_RUNTIME_MANAGED_BY_OWNER = "AUTH_RUNTIME_MANAGED_BY_OWNER";
+var AUTH_SERVICE_HOST_SUFFIX = "-auth";
+var SAFE_PROJECT_REF2 = /^[a-z0-9-]{1,20}$/;
+var SAFE_AUTHORITY_PROJECT_REF = /^[A-Za-z0-9_-]{1,20}$/;
+var MAX_SERVICE_CONTROL_MESSAGE_LENGTH = 256;
+var SUPPORTED_PROJECT_SERVICE_ACTIONS = {
+  postgrest: ["start", "stop", "restart", "pause", "resume", "status"],
+  gotrue: ["start", "stop", "restart"],
+  storage: ["start", "stop", "restart"],
+  postgresql: ["start", "stop", "restart"],
+  realtime: ["start", "stop", "restart"],
+  gateway: ["start", "stop", "restart"]
+};
+function projectToolResponse(text) {
+  return { content: [{ type: "text", text }] };
+}
+function failedProjectServiceResponse(message) {
+  return {
+    content: [{ type: "text", text: `❌ ${message}` }],
+    isError: true
+  };
+}
+function failedProjectServiceHttpResponse(response) {
+  if (response.status === 409 && isRecordPayload(response.data) && response.data.code === AUTH_RUNTIME_MANAGED_BY_OWNER && typeof response.data.authority_project_ref === "string" && SAFE_AUTHORITY_PROJECT_REF.test(response.data.authority_project_ref)) {
+    const ownerBoundary = {
+      status: response.status,
+      code: AUTH_RUNTIME_MANAGED_BY_OWNER,
+      authority_project_ref: response.data.authority_project_ref
+    };
+    return failedProjectServiceResponse(JSON.stringify(ownerBoundary));
+  }
+  return failedProjectServiceResponse(`Failed (${response.status})`);
+}
+function isRecordPayload(payload) {
+  return typeof payload === "object" && payload !== null && !Array.isArray(payload);
+}
+function isStudioProjectServiceName(name) {
+  return typeof name === "string" && STUDIO_PROJECT_SERVICE_NAMES.some((allowedName) => name === allowedName);
+}
+function hasValidStudioServiceHealth(serviceId, status, healthy) {
+  if (status === "INACTIVE")
+    return serviceId === "auth" && healthy === false;
+  const knownStatus = STUDIO_PROJECT_SERVICE_STATUSES.some((allowedStatus) => status === allowedStatus);
+  return knownStatus && healthy === (status === "ACTIVE_HEALTHY");
+}
+function hasValidStudioServiceHost(serviceId, projectRef, hostIds) {
+  if (!Array.isArray(hostIds) || hostIds.length !== 1 || typeof hostIds[0] !== "string")
+    return false;
+  if (serviceId === "auth") {
+    if (!hostIds[0].endsWith(AUTH_SERVICE_HOST_SUFFIX))
+      return false;
+    return SAFE_AUTHORITY_PROJECT_REF.test(hostIds[0].slice(0, -AUTH_SERVICE_HOST_SUFFIX.length));
+  }
+  return hostIds[0] === `${projectRef}-${serviceId}`;
+}
+function isProjectServiceStatus(payload, projectRef) {
+  if (!isRecordPayload(payload))
+    return false;
+  if (!isStudioProjectServiceName(payload.id) || payload.name !== payload.id)
+    return false;
+  return hasValidStudioServiceHealth(payload.id, payload.status, payload.healthy) && hasValidStudioServiceHost(payload.id, projectRef, payload.service_host_ids);
+}
+function projectServiceStatusOutput(status) {
+  return {
+    id: status.id,
+    name: status.name,
+    status: status.status,
+    healthy: status.healthy,
+    service_host_ids: [status.service_host_ids[0]]
+  };
+}
+function projectServicesResponse(projectRef, response) {
+  if (!response.ok)
+    return failedProjectServiceHttpResponse(response);
+  if (!SAFE_PROJECT_REF2.test(projectRef) || !Array.isArray(response.data) || response.data.length !== 5) {
+    return failedProjectServiceResponse("Project service inventory response is invalid");
+  }
+  if (!response.data.every((service) => isProjectServiceStatus(service, projectRef))) {
+    return failedProjectServiceResponse("Project service inventory response is invalid");
+  }
+  const serviceIds = new Set(response.data.map((service) => service.id));
+  if (serviceIds.size !== STUDIO_PROJECT_SERVICE_NAMES.length) {
+    return failedProjectServiceResponse("Project service inventory response is invalid");
+  }
+  const services = response.data.map(projectServiceStatusOutput);
+  return projectToolResponse(JSON.stringify({ project_ref: projectRef, services }, null, 2));
+}
+function supportsProjectServiceAction(service, action) {
+  return SUPPORTED_PROJECT_SERVICE_ACTIONS[service].includes(action);
+}
+function projectServiceReceiptError(receipt, requestedService, requestedAction) {
+  if (!isRecordPayload(receipt))
+    return "Project service control response is invalid";
+  if (receipt.service !== requestedService || receipt.action !== requestedAction) {
+    return "Project service control response does not match the request";
+  }
+  if (receipt.success === false)
+    return "Project service control failed";
+  if (receipt.success !== true || typeof receipt.message !== "string" || receipt.message.length > MAX_SERVICE_CONTROL_MESSAGE_LENGTH) {
+    return "Project service control response is invalid";
+  }
+  return null;
+}
+function projectServiceControlResponse(projectRef, requestedService, requestedAction, response) {
+  if (!response.ok)
+    return failedProjectServiceHttpResponse(response);
+  const receiptError = projectServiceReceiptError(response.data, requestedService, requestedAction);
+  if (receiptError)
+    return failedProjectServiceResponse(receiptError);
+  return projectToolResponse(JSON.stringify({
+    project_ref: projectRef,
+    service: requestedService,
+    action: requestedAction,
+    success: true
+  }, null, 2));
+}
 var formatTasks = (data) => {
   if (!Array.isArray(data))
     return JSON.stringify(data, null, 2);
@@ -28716,7 +28865,7 @@ function resolveRef(refFromArgs, defaultRef) {
   return ref;
 }
 function registerAdminProjectCliTools(server, http) {
-  server.tool("project", "Platform-level project lifecycle management. Actions: list, create, get, delete, pause, restore, restart, settings, update_settings, api_keys, health, logs, tasks", {
+  server.tool("project", "Platform-level project lifecycle management. Actions: list, create, get, delete, pause, restore, restart, settings, update_settings, api_keys, health, logs, tasks, services, service_control", {
     action: withDescription(stringEnum([
       "list",
       "create",
@@ -28730,9 +28879,11 @@ function registerAdminProjectCliTools(server, http) {
       "api_keys",
       "health",
       "logs",
-      "tasks"
+      "tasks",
+      "services",
+      "service_control"
     ]), "Action to perform"),
-    ref: optional(Type.String(), "Project ref (required for most actions except 'list' and 'create')"),
+    ref: optional(Type.String(), "[*] Project ref (required for most actions except 'list' and 'create')"),
     name: optional(Type.String(), "[create] Project name"),
     region: optional(Type.String(), "[create] Region (default: local)"),
     organization_id: optional(Type.String(), "[create] Organization ID"),
@@ -28741,7 +28892,9 @@ function registerAdminProjectCliTools(server, http) {
     auth_domain: optional(Type.String(), "[create] Explicit Auth/OIDC domain"),
     studio_domain: optional(Type.String(), "[create] Explicit Studio domain"),
     settings: optional(Type.Record(Type.String(), Type.Unknown()), "[update_settings] Config fields to update"),
-    log_type: optional(stringEnum(["all", "auth", "database", "api"]), "[logs] Filter by service")
+    log_type: optional(stringEnum(["all", "auth", "database", "api"]), "[logs] Filter by service"),
+    service: optional(stringEnum(PROJECT_SERVICE_NAMES), "[service_control] Canonical service name"),
+    service_action: optional(stringEnum(PROJECT_SERVICE_CONTROL_ACTIONS), "[service_control] Supported action for the selected service")
   }, async ({
     action,
     ref,
@@ -28753,7 +28906,9 @@ function registerAdminProjectCliTools(server, http) {
     auth_domain,
     studio_domain,
     settings,
-    log_type
+    log_type,
+    service,
+    service_action
   }) => {
     let text;
     switch (action) {
@@ -28829,6 +28984,24 @@ function registerAdminProjectCliTools(server, http) {
         text = res.ok ? formatTasks(res.data) : `❌ Failed (${res.status})`;
         break;
       }
+      case "services": {
+        const resolvedRef = resolveRef(ref);
+        return projectServicesResponse(resolvedRef, await http.get(`/v1/projects/${encodeURIComponent(resolvedRef)}/services`));
+      }
+      case "service_control": {
+        const resolvedRef = resolveRef(ref);
+        if (!service)
+          throw new Error("'service' is required for service_control");
+        if (!service_action)
+          throw new Error("'service_action' is required for service_control");
+        if (!supportsProjectServiceAction(service, service_action)) {
+          throw new Error(`'${service_action}' is not supported for service '${service}'`);
+        }
+        const encodedRef = encodeURIComponent(resolvedRef);
+        const encodedService = encodeURIComponent(service);
+        const encodedAction = encodeURIComponent(service_action);
+        return projectServiceControlResponse(resolvedRef, service, service_action, await http.post(`/v1/projects/${encodedRef}/services/${encodedService}/${encodedAction}`));
+      }
       default:
         text = `❌ Unknown action: ${action}`;
     }
@@ -29167,7 +29340,7 @@ Actions: routes, upsert_route, update_route, delete_route, config, get_certifica
 // package.json
 var package_default = {
   name: "@supacloud/admin",
-  version: "0.8.1",
+  version: "0.9.0",
   description: "Platform administration CLI for SupaCloud operators",
   type: "module",
   main: "./dist/index.js",
@@ -29281,6 +29454,8 @@ EXAMPLES
   supacloud-admin ssh install --public_domain api.example.com --studio_domain studio.example.com
   supacloud-admin project create --name my-app --domain example.com
   supacloud-admin project list
+  supacloud-admin project services --ref abc123
+  supacloud-admin project service_control --ref abc123 --service gotrue --service_action stop
   supacloud-admin platform metrics
   supacloud-admin gateway routes --ref abc123
   supacloud-admin gateway upsert_route --ref abc123 --route_id webhook --hosts "api.example.com" --paths "/webhook/*" --upstream 10.0.0.5:8080
@@ -29460,11 +29635,11 @@ async function main() {
           console.log(chunk.text);
         }
       }
-      if (result.isError === true)
-        process.exitCode = 1;
-      return;
+    } else {
+      console.log(JSON.stringify(result, null, 2));
     }
-    console.log(JSON.stringify(result, null, 2));
+    if (cliToolResultIsError(result))
+      process.exitCode = 1;
     return;
   }
   await runCli(cliTools, args, { commandName: "supacloud-admin" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/admin",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Platform administration CLI for SupaCloud operators",
   "type": "module",
   "main": "./dist/index.js",