@lifeaitools/clauth 1.30.24 → 1.30.25

package/cli/commands/serve.js

@@ -58,6 +58,14 @@ import {
   DEFAULT_BOOTSTRAP,
 } from "./agent-pool.js";
 import { AgentCron, cronEnabled, nextRun } from "./agent-cron.js";
+import pm2 from "pm2";
+import { createPm2Adapter, PM2_OPERATION_CATALOG } from "../ops/pm2-adapter.js";
+import { createOperationPolicy } from "../ops/operation-policy.js";
+import { createJobStore } from "../ops/job-store.js";
+import { createCoolifyAdapter, deploymentUuidFrom } from "../ops/coolify-adapter.js";
+import { createDeploymentAdapter, parseDeploymentRegistry } from "../ops/deployment-adapter.js";
+import { createSerializedExecutor } from "../ops/serialized-executor.js";
+import { requestOps } from "./ops.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "../../package.json"), "utf8"));
@@ -1231,11 +1239,16 @@ function dashboardHtml(port, whitelist, isStaged = false, initWriteToken = null)
     <span id="service-search-count" class="service-search-count"></span>
   </div>
   <div id="grid" class="grid"><p class="loading">Loading services…</p></div>
-  <div class="footer">localhost:${port} · 127.0.0.1 only · 10-strike lockout</div>
+  <div class="footer" id="originFooter">checking origin… · 10-strike lockout</div>
 </div>
 
 <script>
-const BASE = "http://127.0.0.1:${port}";
+const BASE = location.origin;
+(function reportOrigin() {
+  const isLocal = /^(127\\.0\\.0\\.1|localhost|\\[::1\\])$/.test(location.hostname);
+  const el = document.getElementById("originFooter");
+  if (el) el.textContent = (isLocal ? "LOCAL" : "REMOTE") + " · " + BASE + " · 10-strike lockout";
+})();
 
 const SERVICE_HINTS = {
   "neo4j":           "neo4j+s://username:password@instance.databases.neo4j.io",
@@ -4027,6 +4040,170 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
   });
   const isSupervisorPort = port === getSupervisorPort();
   const supervisorTestNoToken = process.env.CLAUTH_SUPERVISOR_TEST_NO_TOKEN === "1";
+  const opsAdapter = createPm2Adapter(pm2);
+  const executePm2 = createSerializedExecutor();
+  const opsPolicy = createOperationPolicy({
+    enabled: String(process.env.CLAUTH_OPS_ENABLED || "").split(",").map((item) => item.trim()).filter(Boolean),
+    applications: (() => { try { return JSON.parse(process.env.CLAUTH_OPS_APPLICATIONS || "{}"); } catch { return {}; } })(),
+    adminEnabled: String(process.env.CLAUTH_OPS_ADMIN_ENABLED || "").split(",").map((item) => item.trim()).filter(Boolean),
+    adminApplications: (() => { try { return JSON.parse(process.env.CLAUTH_OPS_ADMIN_APPLICATIONS || "{}"); } catch { return {}; } })(),
+    allowHostWide: process.env.CLAUTH_OPS_ALLOW_HOST_WIDE === "1",
+  });
+  const opsJobs = createJobStore({
+    filePath: process.env.CLAUTH_OPS_JOB_STORE_PATH || path.join(getSupervisorDir(), "ops-jobs.json"),
+  });
+
+  async function getLoopbackSecret(service) {
+    const response = await fetch(`http://127.0.0.1:${LIVE_PORT}/v/${encodeURIComponent(service)}`, { signal: AbortSignal.timeout(5000) });
+    if (!response.ok) throw new Error(`${service} unavailable from local clauth`);
+    const value = (await response.text()).trim();
+    if (!value) throw new Error(`${service} is empty`);
+    return value;
+  }
+  const coolify = createCoolifyAdapter({
+    baseUrl: process.env.CLAUTH_COOLIFY_BASE_URL || "https://deploy.regendevcorp.com",
+    getToken: () => getLoopbackSecret("coolify-api"),
+  });
+  const deployments = (() => { try { return parseDeploymentRegistry(process.env.CLAUTH_OPS_DEPLOYMENTS || "{}"); } catch { return {}; } })();
+  const deploymentAdapter = createDeploymentAdapter({
+    deployments,
+    reload: async (target) => {
+      await executePm2(async () => {
+        await opsAdapter.connect();
+        try { await opsAdapter.execute("reload", { target, options: { updateEnv: true } }); } finally { await opsAdapter.disconnect(); }
+      });
+    },
+  });
+
+  /**
+   * Record an ops failure's upstream message to the LOCAL log only.
+   *
+   * job-store's sanitizer deliberately drops free-form `error` text so an
+   * upstream message cannot carry a credential into the persisted job file or
+   * the API response. That protection left every failure with an empty detail,
+   * so jobs reported `failed` with no reason at all. Jobs now carry an
+   * enumerated `code`; the underlying message goes here, to the same
+   * operator-only log as the rest of the daemon's diagnostics.
+   */
+  function logOpsFailure(kind, operation, error) {
+    const message = String(error?.message || error || "unknown");
+    try {
+      fs.appendFileSync(LOG_FILE, `[${new Date().toISOString()}] [OPS ${kind}/${operation}] ${message}\n`);
+    } catch {}
+  }
+
+  async function opsBearerRole(req) {
+    const header = req.headers.authorization;
+    const supplied = Array.isArray(header) ? header[0] : header;
+    if (!supplied || !String(supplied).startsWith("Bearer ")) return null;
+    const actual = String(supplied).slice(7).trim();
+    let admin; let agent;
+    try { admin = await getLoopbackSecret(process.env.CLAUTH_OPS_ADMIN_TOKEN_SERVICE || "vultr-ops-admin-token"); } catch {}
+    try { agent = await getLoopbackSecret(process.env.CLAUTH_OPS_AGENT_TOKEN_SERVICE || "vultr-ops-api-token"); } catch {}
+    if (admin && agent && admin === agent) return null;
+    for (const [role, expected] of [["admin", admin], ["agent", agent]]) {
+      if (!expected) continue;
+      const a = Buffer.from(actual); const b = Buffer.from(expected);
+      if (a.length === b.length && crypto.timingSafeEqual(a, b)) return role;
+    }
+    return null;
+  }
+
+  async function requireOpsBearer(req, res) {
+    const role = await opsBearerRole(req);
+    if (role) { req._opsRole = role; return true; }
+    res.writeHead(401, { "Content-Type": "application/json", ...CORS });
+    res.end(JSON.stringify({ error: "ops_bearer_required" }));
+    return false;
+  }
+
+  function submitOpsJob(operation, input, role = "agent") {
+    const authorization = opsPolicy.authorize(operation, input, role);
+    const job = opsJobs.create({ kind: "pm2", operation, target: input.target || input.name || null });
+    if (!authorization.ok) {
+      return opsJobs.event(job.id, "rejected", { code: authorization.code });
+    }
+    void (async () => {
+      opsJobs.event(job.id, "running");
+      try {
+        const result = await executePm2(async () => {
+          await opsAdapter.connect();
+          try { return await opsAdapter.execute(operation, input); } finally { await opsAdapter.disconnect(); }
+        });
+        opsJobs.event(job.id, "succeeded", operationReceipt(operation, result, authorization.allowed_targets || []));
+      } catch (error) {
+        // `error` alone is dropped by job-store's sanitizer (it refuses
+        // free-form upstream text so a credential cannot ride along), which
+        // left every failure with an empty detail. Emit an enumerated code so
+        // the failure has a reason; keep the message for the local log only.
+        logOpsFailure("pm2", operation, error);
+        opsJobs.event(job.id, "failed", { code: "pm2_operation_failed" });
+      }
+    })();
+    return opsJobs.get(job.id);
+  }
+
+  function operationReceipt(operation, result, allowedTargets) {
+    if (["list", "describe", "logs"].includes(operation)) {
+      const processes = Array.isArray(result)
+        ? result.filter((process) => allowedTargets.includes("*") || allowedTargets.includes(process?.name))
+        : [];
+      return { processes };
+    }
+    if (operation === "ping") return { status: "connected" };
+    return { status: "completed" };
+  }
+
+  function submitPromotionJob(applicationUuid) {
+    const job = opsJobs.create({ kind: "coolify", operation: "promote", target: applicationUuid });
+    const enabled = String(process.env.CLAUTH_OPS_ENABLED || "").split(",").map((item) => item.trim()).includes("coolify_promote");
+    const allowlist = (() => { try { return JSON.parse(process.env.CLAUTH_COOLIFY_PROMOTE_UUIDS || "[]"); } catch { return []; } })();
+    if (!enabled || !Array.isArray(allowlist) || !allowlist.includes(applicationUuid)) {
+      return opsJobs.event(job.id, "rejected", { code: "service_not_available" });
+    }
+    void (async () => {
+      opsJobs.event(job.id, "running");
+      try {
+        const deployment = await coolify.promote(applicationUuid);
+        // Coolify answers with a `deployments` ARRAY, not a flat object — see
+        // deploymentUuidFrom. Reading the flat field alone marked the job failed
+        // while the deployment was actually running.
+        const deploymentUuid = deploymentUuidFrom(deployment);
+        if (!deploymentUuid) {
+          // The deploy request itself SUCCEEDED (no throw); only the UUID was
+          // unreadable, so the deployment may well be RUNNING. The code says so
+          // explicitly rather than a bare "failed", because a plain failure
+          // invites a retry and a duplicate production deploy.
+          //
+          // An enumerated code, not a free-form error: job-store's sanitizer
+          // drops `error` on purpose to keep upstream text (and any credential
+          // inside it) out of the persisted job.
+          return opsJobs.event(job.id, "failed", { code: "coolify_deploy_accepted_uuid_unreadable" });
+        }
+        opsJobs.event(job.id, "waiting", { deployment_uuid: deploymentUuid });
+        const terminal = await coolify.poll(deploymentUuid, { attempts: Number(process.env.CLAUTH_COOLIFY_POLL_ATTEMPTS || 60), delay: () => new Promise((resolve) => setTimeout(resolve, 5000)) });
+        opsJobs.event(job.id, terminal.state === "succeeded" ? "succeeded" : terminal.state, { deployment_uuid: deploymentUuid, status: terminal.deployment?.status || null });
+      } catch (error) {
+        // The throw may have happened AFTER Coolify accepted the deploy (e.g.
+        // the poll lost the network), so this is not proof nothing shipped.
+        logOpsFailure("coolify", "promote", error);
+        opsJobs.event(job.id, "failed", { code: "coolify_promote_failed" });
+      }
+    })();
+    return opsJobs.get(job.id);
+  }
+
+  function submitDeploymentJob(application, ref) {
+    const job = opsJobs.create({ kind: "deployment", operation: "deploy", target: application });
+    const enabled = String(process.env.CLAUTH_OPS_ENABLED || "").split(",").map((item) => item.trim()).includes("deploy");
+    if (!enabled || !deployments[application]) return opsJobs.event(job.id, "rejected", { code: "service_not_available" });
+    void (async () => {
+      opsJobs.event(job.id, "running");
+      try { opsJobs.event(job.id, "building"); opsJobs.event(job.id, "succeeded", { result: await deploymentAdapter.deploy({ application, ref }) }); }
+      catch (error) { logOpsFailure("deployment", "deploy", error); opsJobs.event(job.id, "failed", { code: "deployment_failed" }); }
+    })();
+    return opsJobs.get(job.id);
+  }
 
   function hasSupervisorWrite(req) {
     if (validateWriteToken(req, writeSession)) return true;
@@ -4623,7 +4800,104 @@ function createServer(initPassword, whitelist, port, tunnelHostnameInit = null,
     }
 
     if (method === "GET" && reqPath === "/health") {
-      return ok(res, { ...supervisorHealth(), vault_locked: !password, clauth_version: VERSION });
+      return ok(res, { ...supervisorHealth(), listening_port: port, process_id: process.pid, vault_locked: !password, clauth_version: VERSION });
+    }
+
+    // Bearer-gated remote operations surface. It remains loopback-only at this
+    // layer; ingress/tunnel policy decides whether it is reachable remotely.
+    if (method === "GET" && reqPath === "/v1/ops/catalog") {
+      if (!await requireOpsBearer(req, res)) return;
+      return ok(res, { schema: "clauth.ops.v1", operations: PM2_OPERATION_CATALOG });
+    }
+
+    if (method === "GET" && reqPath === "/v1/ops/processes") {
+      if (!await requireOpsBearer(req, res)) return;
+      const job = submitOpsJob("list", {}, req._opsRole);
+      res.writeHead(job.phase === "rejected" ? 403 : 202, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job));
+    }
+
+    const opsProcessMatch = reqPath.match(/^\/v1\/ops\/processes\/([^/]+)$/);
+    if (method === "GET" && opsProcessMatch) {
+      if (!await requireOpsBearer(req, res)) return;
+      const job = submitOpsJob("describe", { target: decodeURIComponent(opsProcessMatch[1]) }, req._opsRole);
+      res.writeHead(job.phase === "rejected" ? 403 : 202, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job));
+    }
+
+    if (method === "POST" && reqPath === "/v1/ops/operations") {
+      if (!await requireOpsBearer(req, res)) return;
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "invalid_json" }));
+      }
+      const operation = String(body?.operation || "");
+      if (!PM2_OPERATION_CATALOG[operation]) {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "unknown_operation" }));
+      }
+      const job = submitOpsJob(operation, body?.input && typeof body.input === "object" ? body.input : {}, req._opsRole);
+      res.writeHead(job.phase === "rejected" ? 403 : 202, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job));
+    }
+
+    if (method === "POST" && reqPath === "/v1/ops/promotions") {
+      if (!await requireOpsBearer(req, res)) return;
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "invalid_json" }));
+      }
+      const applicationUuid = String(body?.application_uuid || "").trim();
+      if (!applicationUuid) {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "application_uuid_required" }));
+      }
+      const job = submitPromotionJob(applicationUuid);
+      res.writeHead(job.phase === "rejected" ? 403 : 202, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job));
+    }
+
+    if (method === "POST" && reqPath === "/v1/ops/deployments") {
+      if (!await requireOpsBearer(req, res)) return;
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "invalid_json" }));
+      }
+      const application = String(body?.application || "").trim();
+      if (!application) {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "application_required" }));
+      }
+      const job = submitDeploymentJob(application, body?.ref ? String(body.ref) : undefined);
+      res.writeHead(job.phase === "rejected" ? 403 : 202, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job));
+    }
+
+    const opsJobMatch = reqPath.match(/^\/v1\/ops\/jobs\/([^/]+)$/);
+    if (method === "GET" && opsJobMatch) {
+      if (!await requireOpsBearer(req, res)) return;
+      const job = opsJobs.get(decodeURIComponent(opsJobMatch[1]));
+      res.writeHead(job ? 200 : 404, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job || { error: "job_not_found" }));
+    }
+
+    const opsJobEventsMatch = reqPath.match(/^\/v1\/ops\/jobs\/([^/]+)\/events$/);
+    if (method === "GET" && opsJobEventsMatch) {
+      if (!await requireOpsBearer(req, res)) return;
+      const jobId = decodeURIComponent(opsJobEventsMatch[1]);
+      if (!opsJobs.get(jobId)) {
+        res.writeHead(404, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "job_not_found" }));
+      }
+      res.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", Connection: "keep-alive", ...CORS });
+      const unsubscribe = opsJobs.subscribe(jobId, (job) => {
+        if (!res.writableEnded) res.write(`event: job\ndata: ${JSON.stringify(job)}\n\n`);
+      });
+      req.on("close", unsubscribe);
+      return;
     }
 
     if (method === "GET" && reqPath === "/v1/plugins") {
@@ -11343,6 +11617,41 @@ const MCP_TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "clauth_ops_catalog",
+    description: "Return the Vultr deployment-control API catalog. Availability is still decided on Vultr.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_processes",
+    description: "Submit a scoped PM2 process-status query to the Vultr control plane. Only server-approved applications are returned.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_describe",
+    description: "Submit a scoped PM2 status query for one server-approved application.",
+    inputSchema: { type: "object", properties: { application: { type: "string" } }, required: ["application"], additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_deploy",
+    description: "Submit one manifest-scoped development deployment to Vultr. The server chooses the repository, build, PM2 process, and allowed ref.",
+    inputSchema: { type: "object", properties: { application: { type: "string" }, ref: { type: "string" } }, required: ["application"], additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_promote",
+    description: "Submit one server-allowlisted Coolify promotion and return its asynchronous job receipt.",
+    inputSchema: { type: "object", properties: { application_uuid: { type: "string" } }, required: ["application_uuid"], additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_job",
+    description: "Read the terminal or in-progress receipt for a deployment-control job.",
+    inputSchema: { type: "object", properties: { job_id: { type: "string" } }, required: ["job_id"], additionalProperties: false },
+  },
+  {
+    name: "clauth_ops_run",
+    description: "Submit one PM2 operation through the Vultr control plane. The remote agent/admin profile decides whether the operation and target are available.",
+    inputSchema: { type: "object", properties: { operation: { type: "string" }, input: { type: "object" } }, required: ["operation"], additionalProperties: false },
+  },
 ];
 
 const MCP_WRITE_TOOL_NAMES = new Set([
@@ -11350,6 +11659,9 @@ const MCP_WRITE_TOOL_NAMES = new Set([
   "clauth_disable",
   "clauth_set_project",
   "clauth_generate_token",
+  "clauth_ops_deploy",
+  "clauth_ops_promote",
+  "clauth_ops_run",
 ]);
 
 function filterMcpToolsForWriteMode(tools) {
@@ -11383,6 +11695,24 @@ function mcpError(text) {
   return { content: [{ type: "text", text }], isError: true };
 }
 
+async function callOpsFromMcp(vault, method, requestPath, body, { write = false } = {}) {
+  if (write && !vault.writeEnabled) return mcpError("MCP write tools are disabled by default. Launch clauth with CLAUTH_MCP_WRITE=1 for an explicit write-capable session.");
+  if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
+    const endpoint = process.env.CLAUTH_OPS_APPROVED_ORIGIN;
+    if (!endpoint) return mcpError("service_not_available");
+  try {
+    const url = new URL(endpoint);
+    if (url.protocol !== "https:") return mcpError("service_not_available");
+    const service = process.env.CLAUTH_OPS_TOKEN_SERVICE || "vultr-ops-api-token";
+    const credential = await vaultRetrieveValue(vault, service);
+    if (credential.error || !credential.value) return mcpError("service_not_available");
+    const payload = await requestOps({ endpoint: url.toString().replace(/\/$/, ""), token: String(credential.value), method, path: requestPath, body });
+    return mcpResult(JSON.stringify(payload, null, 2));
+  } catch {
+    return mcpError("service_not_available");
+  }
+}
+
 // Windows cmd.exe doesn't support single quotes — use bash for gws JSON args
 const GWS_EXEC_OPTS = { encoding: "utf8", timeout: 30000, windowsHide: true, shell: os.platform() === "win32" ? "bash" : undefined };
 
@@ -11393,6 +11723,13 @@ async function handleMcpTool(vault, name, args) {
   };
 
   switch (name) {
+    case "clauth_ops_catalog": return callOpsFromMcp(vault, "GET", "/v1/ops/catalog");
+    case "clauth_ops_processes": return callOpsFromMcp(vault, "GET", "/v1/ops/processes");
+    case "clauth_ops_describe": return callOpsFromMcp(vault, "GET", `/v1/ops/processes/${encodeURIComponent(args.application || "")}`);
+    case "clauth_ops_deploy": return callOpsFromMcp(vault, "POST", "/v1/ops/deployments", { application: args.application, ...(args.ref ? { ref: args.ref } : {}) }, { write: true });
+    case "clauth_ops_promote": return callOpsFromMcp(vault, "POST", "/v1/ops/promotions", { application_uuid: args.application_uuid }, { write: true });
+    case "clauth_ops_job": return callOpsFromMcp(vault, "GET", `/v1/ops/jobs/${encodeURIComponent(args.job_id || "")}`);
+    case "clauth_ops_run": return callOpsFromMcp(vault, "POST", "/v1/ops/operations", { operation: args.operation, input: args.input && typeof args.input === "object" ? args.input : {} }, { write: true });
     case "clauth_ping": {
       return mcpResult(
         vault.password

package/cli/commands/watchdog.js

@@ -131,7 +131,7 @@ export async function runWatchdog(action, opts = {}) {
       console.log("Usage: clauth watchdog restart <service-id>");
       return;
     }
-    const result = restartWatchdogService(serviceId);
+    const result = await restartWatchdogService(serviceId);
     console.log(JSON.stringify(result, null, 2));
     return;
   }

package/cli/index.js

@@ -150,6 +150,8 @@ import { runInstall } from './commands/install.js';
 import { runUninstall } from './commands/uninstall.js';
 import { runScrub } from './commands/scrub.js';
 import { runServe } from './commands/serve.js';
+import { runOps } from './commands/ops.js';
+import { runOpsInstall } from './commands/ops-install.js';
 import { runCodevelop } from './commands/codevelop.js';
 import { runNpm, runPublish } from './commands/npm.js';
 
@@ -1050,4 +1052,22 @@ Examples:
     await runServe({ ...opts, action: resolvedAction });
   });
 
+program
+  .command("ops <action>")
+  .description("Call the bearer-authenticated PM2 and Coolify operations control plane")
+  .option("--endpoint <url>", "HTTPS control-plane endpoint (or CLAUTH_OPS_ENDPOINT)")
+  .option("--target <name>", "PM2 process name or id")
+  .option("--script <path>", "PM2 script path for start")
+  .option("--instances <n>", "PM2 scale target")
+  .option("--operation <name>", "PM2 operation for run")
+  .option("--args-json <json>", "JSON positional arguments for a raw pm2_* operation")
+  .option("--options-json <json>", "JSON PM2 options for a typed operation")
+  .option("--application <uuid>", "registered Coolify application UUID for promote")
+  .option("--ref <name>", "registered Git ref for deploy")
+  .option("--job <id>", "job id for status lookup")
+  .option("--config <path>", "server-side JSON policy for ops install")
+  .option("--dry-run", "validate and print ops install configuration without changing PM2")
+  .addHelpText("after", `\nActions: catalog | list | describe | run | deploy | promote | job | install\n\nInstall: clauth ops install --config /etc/clauth/ops-control-plane.json\nThe installer creates or updates a PM2-managed local control plane, then proves /health and the bearer gate without reading a token.\n\nThe bearer is retrieved only from local clauth service vultr-ops-api-token and is never printed.\n`)
+  .action(async (action, opts) => { if (action === "install") await runOpsInstall(opts); else await runOps(action, opts); });
+
 program.parse(process.argv);

package/cli/ops/coolify-adapter.js

@@ -0,0 +1,80 @@
+const TERMINAL = new Map([
+  ["finished", "succeeded"], ["success", "succeeded"], ["successful", "succeeded"],
+  ["failed", "failed"], ["error", "failed"], ["cancelled", "failed"],
+]);
+
+function required(value, name) {
+  if (!value) throw new Error(`${name} is required`);
+  return value;
+}
+
+export function normalizeCoolifyState(value) {
+  const raw = String(value || "unknown").toLowerCase();
+  return TERMINAL.get(raw) || (raw.includes("progress") || raw.includes("queue") || raw.includes("running") ? "running" : "unknown");
+}
+
+/**
+ * Extract the deployment UUID from a Coolify deploy response.
+ *
+ * Coolify's `/api/v1/deploy` does NOT return the UUID at the top level — it
+ * answers with a `deployments` ARRAY:
+ *
+ *   { "deployments": [ { "message": "...", "resource_uuid": "...",
+ *                        "deployment_uuid": "ha9xjqcldy7duf2diyjdc20p" } ] }
+ *
+ * Reading only `body.deployment_uuid` therefore yields undefined, the caller
+ * concludes the promotion never started, and the job is marked failed — while
+ * Coolify is in fact building. That happened on a real life.ai promote:
+ * deployment ha9xjqcldy7duf2diyjdc20p was created at the same second the job
+ * reported failure. A failed job invites a retry, so the bug turns one
+ * production deploy into several.
+ *
+ * Accepts the array shape first, then the flat shapes, so a future/simplified
+ * response still resolves.
+ */
+export function deploymentUuidFrom(body) {
+  if (!body || typeof body !== "object") return null;
+  const list = Array.isArray(body.deployments) ? body.deployments : [];
+  for (const entry of list) {
+    if (!entry || typeof entry !== "object") continue;
+    const nested = entry.deployment_uuid || entry.uuid || entry.id;
+    if (typeof nested === "string" && nested) return nested;
+  }
+  const flat = body.deployment_uuid || body.uuid || body.id;
+  return typeof flat === "string" && flat ? flat : null;
+}
+
+export function createCoolifyAdapter({ baseUrl, getToken, fetchImpl = globalThis.fetch } = {}) {
+  const api = String(required(baseUrl, "baseUrl")).replace(/\/$/, "");
+  if (typeof getToken !== "function") throw new Error("getToken is required");
+  async function request(path, options = {}) {
+    const token = await getToken();
+    if (!token) throw new Error("coolify credential unavailable");
+    const headers = new Headers(options.headers || {});
+    headers.set("Accept", "application/json");
+    headers.set("Authorization", `Bearer ${token}`);
+    const response = await fetchImpl(`${api}${path}`, {
+      ...options,
+      headers,
+    });
+    if (!response.ok) throw new Error(`Coolify HTTP ${response.status}`);
+    return response.json();
+  }
+  return {
+    inspect(applicationUuid) { return request(`/api/v1/applications/${encodeURIComponent(required(applicationUuid, "applicationUuid"))}`); },
+    async promote(applicationUuid, options = {}) {
+      const uuid = encodeURIComponent(required(applicationUuid, "applicationUuid"));
+      return request(`/api/v1/deploy?uuid=${uuid}&force=true`, options);
+    },
+    async deployment(deploymentUuid) { return request(`/api/v1/deployments/${encodeURIComponent(required(deploymentUuid, "deploymentUuid"))}`); },
+    async poll(deploymentUuid, { attempts = 30, delay = async () => {} } = {}) {
+      for (let attempt = 1; attempt <= attempts; attempt++) {
+        const deployment = await this.deployment(deploymentUuid);
+        const state = normalizeCoolifyState(deployment.status || deployment.state);
+        if (state === "succeeded" || state === "failed") return { state, deployment, attempts: attempt };
+        await delay(attempt);
+      }
+      return { state: "timed_out", deployment: null, attempts };
+    },
+  };
+}

package/cli/ops/deployment-adapter.js

@@ -0,0 +1,63 @@
+import { execFile as execFileCallback } from "node:child_process";
+
+function execFile(command, args, options) {
+  return new Promise((resolve, reject) => execFileCallback(command, args, { ...options, windowsHide: true }, (error, stdout, stderr) => {
+    if (error) return reject(new Error(`${command} ${args.join(" ")}: ${String(stderr || error.message).trim()}`));
+    resolve({ stdout: String(stdout || "").trim(), stderr: String(stderr || "").trim() });
+  }));
+}
+
+function requireString(value, name) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${name} is required`);
+  return value.trim();
+}
+
+function validateApplication(config) {
+  if (!config || typeof config !== "object") throw new Error("deployment_not_registered");
+  requireString(config.repo_path, "deployment.repo_path");
+  requireString(config.pm2_name, "deployment.pm2_name");
+  if (!Array.isArray(config.build) || !config.build.every((value) => typeof value === "string" && value)) throw new Error("deployment.build must be a non-empty argv array");
+  if (!Array.isArray(config.allowed_refs) || !config.allowed_refs.every((value) => typeof value === "string" && value)) throw new Error("deployment.allowed_refs must be a string array");
+  if (!requireString(config.health_url, "deployment.health_url").startsWith("http")) throw new Error("deployment.health_url must be HTTP(S)");
+}
+
+export function parseDeploymentRegistry(raw = "{}") {
+  const parsed = typeof raw === "string" ? JSON.parse(raw) : raw;
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("CLAUTH_OPS_DEPLOYMENTS must be a JSON object");
+  for (const config of Object.values(parsed)) validateApplication(config);
+  return parsed;
+}
+
+export function createDeploymentAdapter({ deployments, run = execFile, fetch = globalThis.fetch, delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), reload }) {
+  if (typeof reload !== "function") throw new Error("reload callback is required");
+  return {
+    async deploy({ application, ref }) {
+      const name = requireString(application, "application");
+      const config = deployments[name];
+      validateApplication(config);
+      const requestedRef = requireString(ref || config.default_ref, "ref");
+      if (!config.allowed_refs.includes(requestedRef)) throw new Error("deployment_ref_not_allowed");
+      const cwd = config.repo_path;
+      const steps = [];
+      await run("git", ["fetch", "origin", requestedRef], { cwd });
+      steps.push("fetched");
+      const sha = (await run("git", ["rev-parse", "FETCH_HEAD"], { cwd })).stdout;
+      if (!/^[0-9a-f]{7,64}$/i.test(sha)) throw new Error("deployment_invalid_git_sha");
+      await run("git", ["checkout", "--detach", sha], { cwd });
+      steps.push("checked_out");
+      await run(config.build[0], config.build.slice(1), { cwd });
+      steps.push("built");
+      await reload(config.pm2_name);
+      steps.push("reloaded");
+      const attempts = Number(config.health_attempts || 30);
+      for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+          const response = await fetch(config.health_url, { signal: AbortSignal.timeout(Number(config.health_timeout_ms || 5000)) });
+          if (response.ok) return { application: name, ref: requestedRef, sha, health_url: config.health_url, attempts: attempt, steps };
+        } catch {}
+        await delay(Number(config.health_delay_ms || 1000));
+      }
+      throw new Error("deployment_health_check_timed_out");
+    },
+  };
+}