@lifeaitools/clauth 1.30.23 → 1.30.25

package/cli/commands/npm.js

@@ -1,182 +1,182 @@
-import fs from "fs";
-import os from "os";
-import path from "path";
-import { spawnSync } from "child_process";
-
-const CLAUTH_NPM_URL = "http://127.0.0.1:52437/v/npm";
-
-function run(cmd, args, opts = {}) {
-  const useCmd = process.platform === "win32" && ["npm", "gh"].includes(cmd);
-  const executable = useCmd ? "cmd.exe" : cmd;
-  const finalArgs = useCmd ? ["/d", "/s", "/c", cmd, ...args] : args;
-  const result = spawnSync(executable, finalArgs, {
-    encoding: "utf8",
-    ...opts,
-    env: { ...process.env, ...(opts.env || {}) }
-  });
-  if (result.error) throw result.error;
-  return result;
-}
-
-function redactNpmTokenList(text) {
-  return String(text || "").replace(/npm_[A-Za-z0-9]+/g, token => `${token.slice(0, 9)}...${token.slice(-4)}`);
-}
-
-async function fetchNpmToken() {
-  const response = await fetch(CLAUTH_NPM_URL);
-  if (!response.ok) throw new Error(`failed to fetch npm token from clauth daemon: HTTP ${response.status}`);
-  const token = (await response.text()).trim();
-  if (!token) throw new Error("clauth npm token is empty");
-  if (!token.startsWith("npm_")) throw new Error("clauth npm token does not look like an npm token");
-  return token;
-}
-
-function withNpmAuth(token, fn) {
-  const npmrc = path.join(os.tmpdir(), `clauth-npm-${process.pid}-${Date.now()}.npmrc`);
-  try {
-    fs.writeFileSync(npmrc, `//registry.npmjs.org/:_authToken=${token}`, { encoding: "utf8", mode: 0o600 });
-    return fn(npmrc);
-  } finally {
-    try { fs.rmSync(npmrc, { force: true }); } catch {}
-  }
-}
-
-function runNpmWithToken(token, args) {
-  return withNpmAuth(token, npmrc => run("npm", ["--userconfig", npmrc, ...args]));
-}
-
-function printResult(result, { redact = true } = {}) {
-  const stdout = redact ? redactNpmTokenList(result.stdout) : result.stdout;
-  const stderr = redact ? redactNpmTokenList(result.stderr) : result.stderr;
-  if (stdout) process.stdout.write(stdout);
-  if (stderr) process.stderr.write(stderr);
-}
-
-function usage() {
-  console.log(`clauth npm <action>
-
-Actions:
-  whoami                         Verify the clauth npm token identity
-  tokens                         List npm token metadata with token strings redacted
-  set-local                      Write the clauth npm token to the user npm config
-  sync-github-secret <repo>       Set repo secret NPM_TOKEN from clauth, e.g. LIFEAI/rdc-skills
-  rerun <run-id> --repo <repo>    Rerun a failed GitHub Actions workflow
-`);
-}
-
-export async function runNpm(action = "help", opts = {}) {
-  if (action === "help") {
-    usage();
-    return;
-  }
-
-  const token = await fetchNpmToken();
-
-  if (action === "whoami") {
-    const result = runNpmWithToken(token, ["whoami", "--registry=https://registry.npmjs.org/"]);
-    printResult(result);
-    if (result.status !== 0) process.exitCode = result.status;
-    return;
-  }
-
-  if (action === "tokens") {
-    const result = runNpmWithToken(token, ["token", "list", "--json", "--registry=https://registry.npmjs.org/"]);
-    printResult(result);
-    if (result.status !== 0) process.exitCode = result.status;
-    return;
-  }
-
-  if (action === "set-local") {
-    const result = run("npm", ["config", "set", "//registry.npmjs.org/:_authToken", token, "--location=user"]);
-    if (result.status !== 0) {
-      printResult(result);
-      process.exitCode = result.status;
-      return;
-    }
-    console.log("local npm auth updated from clauth service 'npm'");
-    return;
-  }
-
-  if (action === "sync-github-secret") {
-    const repo = opts.repo || opts.args?.[0];
-    if (!repo) throw new Error("repo is required, e.g. clauth npm sync-github-secret LIFEAI/rdc-skills");
-    const result = run("gh", ["secret", "set", "NPM_TOKEN", "--repo", repo], { input: token });
-    printResult(result);
-    if (result.status !== 0) process.exitCode = result.status;
-    else console.log(`GitHub secret NPM_TOKEN updated for ${repo}`);
-    return;
-  }
-
-  if (action === "rerun") {
-    const runId = opts.args?.[0];
-    const repo = opts.repo;
-    if (!runId || !repo) throw new Error("usage: clauth npm rerun <run-id> --repo LIFEAI/rdc-skills");
-    const result = run("gh", ["run", "rerun", runId, "--repo", repo, "--failed"]);
-    printResult(result);
-    if (result.status !== 0) process.exitCode = result.status;
-    else console.log(`rerun requested for ${repo} run ${runId}`);
-    return;
-  }
-
-  usage();
-  throw new Error(`unknown clauth npm action: ${action}`);
-}
-
-// ── Guarded publish ──────────────────────────────────────────────────────────
-// Generic, package-agnostic publish that REFUSES to publish unless the package
-// is already committed and pushed to GitHub — so the npm tarball can never be
-// built from uncommitted "dev" code that isn't on the repo. Works for standalone
-// repos and monorepo subpackages (clean-check is scoped to the package's dir).
-export async function runPublish(target, opts = {}) {
-  const pkgDir = path.resolve(target || process.cwd());
-  const pkgJsonPath = path.join(pkgDir, "package.json");
-  if (!fs.existsSync(pkgJsonPath)) throw new Error(`No package.json found at ${pkgDir}`);
-  const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8"));
-  if (!pkg.name || !pkg.version) throw new Error(`package.json at ${pkgDir} is missing name or version`);
-  if (pkg.private === true) throw new Error(`${pkg.name} is marked "private": true — refusing to publish`);
-  const access = opts.access || pkg.publishConfig?.access || (pkg.name.startsWith("@") ? "public" : undefined);
-
-  const gitRoot = run("git", ["rev-parse", "--show-toplevel"], { cwd: pkgDir }).stdout?.trim();
-  if (!gitRoot) throw new Error(`${pkgDir} is not inside a git repository`);
-  const rel = path.relative(gitRoot, pkgDir) || ".";
-
-  // Guard 1 — nothing uncommitted in the package (else we'd pack dev code).
-  const dirty = run("git", ["status", "--porcelain", "--", rel], { cwd: gitRoot }).stdout?.trim();
-  if (dirty && !opts.allowDirty) {
-    throw new Error(`Refusing to publish ${pkg.name}@${pkg.version}: uncommitted changes in ${rel} would be packed but are NOT on GitHub:\n${dirty}\n\nCommit + push first (or pass --allow-dirty to override).`);
-  }
-
-  // Guard 2 — HEAD is on a remote (actually pushed to GitHub).
-  const head = run("git", ["rev-parse", "HEAD"], { cwd: gitRoot }).stdout?.trim();
-  const onRemote = run("git", ["branch", "-r", "--contains", head], { cwd: gitRoot }).stdout?.trim();
-  if (!onRemote && !opts.allowUnpushed) {
-    throw new Error(`Refusing to publish ${pkg.name}@${pkg.version}: HEAD ${head.slice(0, 9)} is not on any remote branch — push to GitHub first (or pass --allow-unpushed to override).`);
-  }
-
-  // Traceability — warn (don't block) if there's no v<version> tag at HEAD.
-  const tags = (run("git", ["tag", "--points-at", "HEAD"], { cwd: gitRoot }).stdout || "").split("\n").map((s) => s.trim()).filter(Boolean);
-  if (!tags.includes(`v${pkg.version}`)) {
-    console.log(`⚠  No git tag v${pkg.version} at HEAD (traceability only). Tags here: ${tags.join(", ") || "none"}`);
-  }
-
-  console.log(`${opts.dryRun ? "[dry-run] " : ""}Publishing ${pkg.name}@${pkg.version} from ${rel} @ ${head.slice(0, 9)} (pushed${access ? `, access=${access}` : ""})`);
-
-  const token = await fetchNpmToken();
-  const args = ["publish"];
-  if (access) args.push("--access", access);
-  if (opts.dryRun) args.push("--dry-run");
-  const result = withNpmAuth(token, (npmrc) => run("npm", ["--userconfig", npmrc, ...args], { cwd: pkgDir }));
-  printResult(result, { redact: true });
-  if (result.status !== 0) { process.exitCode = result.status; throw new Error(`npm publish failed for ${pkg.name}`); }
-  if (opts.dryRun) { console.log("Dry run complete — nothing published."); return; }
-
-  // Verify on the registry directly (bypasses npm's local cache lag).
-  try {
-    const reg = await fetch(`https://registry.npmjs.org/${pkg.name}`);
-    const meta = await reg.json();
-    if (meta.versions?.[pkg.version]) console.log(`✓ Verified ${pkg.name}@${pkg.version} on the registry (latest: ${meta["dist-tags"]?.latest}).`);
-    else console.log(`⚠  ${pkg.name}@${pkg.version} not visible on the registry yet (propagation lag) — re-check shortly.`);
-  } catch (e) {
-    console.log(`(could not verify on registry: ${e.message})`);
-  }
-}
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { spawnSync } from "child_process";
+
+const CLAUTH_NPM_URL = "http://127.0.0.1:52437/v/npm";
+
+function run(cmd, args, opts = {}) {
+  const useCmd = process.platform === "win32" && ["npm", "gh"].includes(cmd);
+  const executable = useCmd ? "cmd.exe" : cmd;
+  const finalArgs = useCmd ? ["/d", "/s", "/c", cmd, ...args] : args;
+  const result = spawnSync(executable, finalArgs, {
+    encoding: "utf8",
+    ...opts,
+    env: { ...process.env, ...(opts.env || {}) }
+  });
+  if (result.error) throw result.error;
+  return result;
+}
+
+function redactNpmTokenList(text) {
+  return String(text || "").replace(/npm_[A-Za-z0-9]+/g, token => `${token.slice(0, 9)}...${token.slice(-4)}`);
+}
+
+async function fetchNpmToken() {
+  const response = await fetch(CLAUTH_NPM_URL);
+  if (!response.ok) throw new Error(`failed to fetch npm token from clauth daemon: HTTP ${response.status}`);
+  const token = (await response.text()).trim();
+  if (!token) throw new Error("clauth npm token is empty");
+  if (!token.startsWith("npm_")) throw new Error("clauth npm token does not look like an npm token");
+  return token;
+}
+
+function withNpmAuth(token, fn) {
+  const npmrc = path.join(os.tmpdir(), `clauth-npm-${process.pid}-${Date.now()}.npmrc`);
+  try {
+    fs.writeFileSync(npmrc, `//registry.npmjs.org/:_authToken=${token}`, { encoding: "utf8", mode: 0o600 });
+    return fn(npmrc);
+  } finally {
+    try { fs.rmSync(npmrc, { force: true }); } catch {}
+  }
+}
+
+function runNpmWithToken(token, args) {
+  return withNpmAuth(token, npmrc => run("npm", ["--userconfig", npmrc, ...args]));
+}
+
+function printResult(result, { redact = true } = {}) {
+  const stdout = redact ? redactNpmTokenList(result.stdout) : result.stdout;
+  const stderr = redact ? redactNpmTokenList(result.stderr) : result.stderr;
+  if (stdout) process.stdout.write(stdout);
+  if (stderr) process.stderr.write(stderr);
+}
+
+function usage() {
+  console.log(`clauth npm <action>
+
+Actions:
+  whoami                         Verify the clauth npm token identity
+  tokens                         List npm token metadata with token strings redacted
+  set-local                      Write the clauth npm token to the user npm config
+  sync-github-secret <repo>       Set repo secret NPM_TOKEN from clauth, e.g. LIFEAI/rdc-skills
+  rerun <run-id> --repo <repo>    Rerun a failed GitHub Actions workflow
+`);
+}
+
+export async function runNpm(action = "help", opts = {}) {
+  if (action === "help") {
+    usage();
+    return;
+  }
+
+  const token = await fetchNpmToken();
+
+  if (action === "whoami") {
+    const result = runNpmWithToken(token, ["whoami", "--registry=https://registry.npmjs.org/"]);
+    printResult(result);
+    if (result.status !== 0) process.exitCode = result.status;
+    return;
+  }
+
+  if (action === "tokens") {
+    const result = runNpmWithToken(token, ["token", "list", "--json", "--registry=https://registry.npmjs.org/"]);
+    printResult(result);
+    if (result.status !== 0) process.exitCode = result.status;
+    return;
+  }
+
+  if (action === "set-local") {
+    const result = run("npm", ["config", "set", "//registry.npmjs.org/:_authToken", token, "--location=user"]);
+    if (result.status !== 0) {
+      printResult(result);
+      process.exitCode = result.status;
+      return;
+    }
+    console.log("local npm auth updated from clauth service 'npm'");
+    return;
+  }
+
+  if (action === "sync-github-secret") {
+    const repo = opts.repo || opts.args?.[0];
+    if (!repo) throw new Error("repo is required, e.g. clauth npm sync-github-secret LIFEAI/rdc-skills");
+    const result = run("gh", ["secret", "set", "NPM_TOKEN", "--repo", repo], { input: token });
+    printResult(result);
+    if (result.status !== 0) process.exitCode = result.status;
+    else console.log(`GitHub secret NPM_TOKEN updated for ${repo}`);
+    return;
+  }
+
+  if (action === "rerun") {
+    const runId = opts.args?.[0];
+    const repo = opts.repo;
+    if (!runId || !repo) throw new Error("usage: clauth npm rerun <run-id> --repo LIFEAI/rdc-skills");
+    const result = run("gh", ["run", "rerun", runId, "--repo", repo, "--failed"]);
+    printResult(result);
+    if (result.status !== 0) process.exitCode = result.status;
+    else console.log(`rerun requested for ${repo} run ${runId}`);
+    return;
+  }
+
+  usage();
+  throw new Error(`unknown clauth npm action: ${action}`);
+}
+
+// ── Guarded publish ──────────────────────────────────────────────────────────
+// Generic, package-agnostic publish that REFUSES to publish unless the package
+// is already committed and pushed to GitHub — so the npm tarball can never be
+// built from uncommitted "dev" code that isn't on the repo. Works for standalone
+// repos and monorepo subpackages (clean-check is scoped to the package's dir).
+export async function runPublish(target, opts = {}) {
+  const pkgDir = path.resolve(target || process.cwd());
+  const pkgJsonPath = path.join(pkgDir, "package.json");
+  if (!fs.existsSync(pkgJsonPath)) throw new Error(`No package.json found at ${pkgDir}`);
+  const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8"));
+  if (!pkg.name || !pkg.version) throw new Error(`package.json at ${pkgDir} is missing name or version`);
+  if (pkg.private === true) throw new Error(`${pkg.name} is marked "private": true — refusing to publish`);
+  const access = opts.access || pkg.publishConfig?.access || (pkg.name.startsWith("@") ? "public" : undefined);
+
+  const gitRoot = run("git", ["rev-parse", "--show-toplevel"], { cwd: pkgDir }).stdout?.trim();
+  if (!gitRoot) throw new Error(`${pkgDir} is not inside a git repository`);
+  const rel = path.relative(gitRoot, pkgDir) || ".";
+
+  // Guard 1 — nothing uncommitted in the package (else we'd pack dev code).
+  const dirty = run("git", ["status", "--porcelain", "--", rel], { cwd: gitRoot }).stdout?.trim();
+  if (dirty && !opts.allowDirty) {
+    throw new Error(`Refusing to publish ${pkg.name}@${pkg.version}: uncommitted changes in ${rel} would be packed but are NOT on GitHub:\n${dirty}\n\nCommit + push first (or pass --allow-dirty to override).`);
+  }
+
+  // Guard 2 — HEAD is on a remote (actually pushed to GitHub).
+  const head = run("git", ["rev-parse", "HEAD"], { cwd: gitRoot }).stdout?.trim();
+  const onRemote = run("git", ["branch", "-r", "--contains", head], { cwd: gitRoot }).stdout?.trim();
+  if (!onRemote && !opts.allowUnpushed) {
+    throw new Error(`Refusing to publish ${pkg.name}@${pkg.version}: HEAD ${head.slice(0, 9)} is not on any remote branch — push to GitHub first (or pass --allow-unpushed to override).`);
+  }
+
+  // Traceability — warn (don't block) if there's no v<version> tag at HEAD.
+  const tags = (run("git", ["tag", "--points-at", "HEAD"], { cwd: gitRoot }).stdout || "").split("\n").map((s) => s.trim()).filter(Boolean);
+  if (!tags.includes(`v${pkg.version}`)) {
+    console.log(`⚠  No git tag v${pkg.version} at HEAD (traceability only). Tags here: ${tags.join(", ") || "none"}`);
+  }
+
+  console.log(`${opts.dryRun ? "[dry-run] " : ""}Publishing ${pkg.name}@${pkg.version} from ${rel} @ ${head.slice(0, 9)} (pushed${access ? `, access=${access}` : ""})`);
+
+  const token = await fetchNpmToken();
+  const args = ["publish"];
+  if (access) args.push("--access", access);
+  if (opts.dryRun) args.push("--dry-run");
+  const result = withNpmAuth(token, (npmrc) => run("npm", ["--userconfig", npmrc, ...args], { cwd: pkgDir }));
+  printResult(result, { redact: true });
+  if (result.status !== 0) { process.exitCode = result.status; throw new Error(`npm publish failed for ${pkg.name}`); }
+  if (opts.dryRun) { console.log("Dry run complete — nothing published."); return; }
+
+  // Verify on the registry directly (bypasses npm's local cache lag).
+  try {
+    const reg = await fetch(`https://registry.npmjs.org/${pkg.name}`);
+    const meta = await reg.json();
+    if (meta.versions?.[pkg.version]) console.log(`✓ Verified ${pkg.name}@${pkg.version} on the registry (latest: ${meta["dist-tags"]?.latest}).`);
+    else console.log(`⚠  ${pkg.name}@${pkg.version} not visible on the registry yet (propagation lag) — re-check shortly.`);
+  } catch (e) {
+    console.log(`(could not verify on registry: ${e.message})`);
+  }
+}

package/cli/commands/ops-install.js

@@ -0,0 +1,211 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import pm2 from "pm2";
+
+const DEFAULT_PORT = 52439;
+const DEFAULT_NAME = "clauth-deployment";
+const INSTALLER_MARKER = "clauth.ops.install.v1";
+const OPS_ENV_KEYS = new Set([
+  "CLAUTH_OPS_INSTALLER_MARKER", "CLAUTH_OPS_ENABLED", "CLAUTH_OPS_APPLICATIONS", "CLAUTH_OPS_ADMIN_ENABLED",
+  "CLAUTH_OPS_ADMIN_APPLICATIONS", "CLAUTH_OPS_ALLOW_HOST_WIDE", "CLAUTH_OPS_DEPLOYMENTS", "CLAUTH_COOLIFY_PROMOTE_UUIDS",
+]);
+const RUNTIME_ENV_KEYS = new Set(["PATH", "Path", "HOME", "USERPROFILE", "APPDATA", "LOCALAPPDATA", "SystemRoot", "SYSTEMROOT", "ComSpec", "TMP", "TEMP"]);
+const RESTORABLE_PM2_KEYS = ["node_args", "exec_mode", "instances", "namespace", "watch", "kill_retry_time", "merge_logs", "windowsHide", "stop_exit_codes"];
+
+function requiredString(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${label} is required`);
+  return value.trim();
+}
+
+function stringList(value, label) {
+  if (value == null) return [];
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string" && item.trim())) throw new Error(`${label} must be an array of non-empty strings`);
+  return value.map((item) => item.trim());
+}
+
+function applicationPolicy(value, label) {
+  if (value == null) return {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  return Object.fromEntries(Object.entries(value).map(([operation, targets]) => [operation, stringList(targets, `${label}.${operation}`)]));
+}
+
+/**
+ * An operation is only usable when it ALSO has a target allowlist.
+ *
+ * `createOperationPolicy` reads the allowlist from `applications[operation]` and
+ * rejects with `service_not_available` when it is empty (operation-policy.js,
+ * the `!allowed.length` guard). That code reads like the service is down, but
+ * it actually means "no targets configured" — so a config carrying only
+ * `agent_enabled` installs cleanly, passes the health and bearer-gate probes,
+ * and then rejects every authenticated call. That exact combination shipped to
+ * the canary and was misdiagnosed for a day as a missing credential.
+ *
+ * Read operations (`list`, `describe`, `ping`, `logs`, …) are affected too: the
+ * `!allowed.length` guard runs before the read/mutate distinction, so a read op
+ * with no allowlist is rejected just the same.
+ *
+ * Fail at install instead, naming the operations that would silently break.
+ */
+function assertEnabledOperationsHaveTargets(enabled, applications, label) {
+  const missing = enabled.filter((operation) => !(applications[operation] || []).length);
+  if (!missing.length) return;
+  const applicationsLabel = label.replace("_enabled", "_applications");
+  throw new Error(
+    `${label}: ${missing.join(", ")} enabled but absent from ${applicationsLabel}. An enabled operation with no target allowlist is rejected at runtime with service_not_available. Add a target list (e.g. {"${missing[0]}": ["*"]}) or remove it from the enabled list.`,
+  );
+}
+
+export function loadOpsInstallConfig(configPath) {
+  const raw = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("ops installer config must be a JSON object");
+  const port = raw.port == null ? DEFAULT_PORT : Number(raw.port);
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error("port must be an integer from 1024 through 65535");
+  const pm2Name = raw.pm2_name == null ? DEFAULT_NAME : requiredString(raw.pm2_name, "pm2_name");
+  const operations = raw.operations && typeof raw.operations === "object" && !Array.isArray(raw.operations) ? raw.operations : {};
+
+  const enabled = stringList(operations.agent_enabled, "operations.agent_enabled");
+  const applications = applicationPolicy(operations.agent_applications, "operations.agent_applications");
+  const adminEnabled = stringList(operations.admin_enabled, "operations.admin_enabled");
+  const adminApplications = applicationPolicy(operations.admin_applications, "operations.admin_applications");
+
+  assertEnabledOperationsHaveTargets(enabled, applications, "operations.agent_enabled");
+  assertEnabledOperationsHaveTargets(adminEnabled, adminApplications, "operations.admin_enabled");
+
+  return {
+    port,
+    pm2Name,
+    enabled,
+    applications,
+    adminEnabled,
+    adminApplications,
+    allowHostWide: operations.allow_host_wide === true,
+    deployments: raw.deployments && typeof raw.deployments === "object" && !Array.isArray(raw.deployments) ? raw.deployments : {},
+    coolifyPromoteUuids: stringList(raw.coolify_promote_uuids, "coolify_promote_uuids"),
+  };
+}
+
+export function buildOpsServiceSpec({ config, rootDir }) {
+  const cli = path.join(rootDir, "cli", "index.js");
+  const runtimeEnv = Object.fromEntries([...RUNTIME_ENV_KEYS].flatMap((key) => process.env[key] == null ? [] : [[key, process.env[key]]]));
+  return {
+    name: config.pm2Name,
+    script: cli,
+    args: `serve foreground --port ${config.port} --isolated`,
+    cwd: rootDir,
+    autorestart: true,
+    restart_delay: 1000,
+    max_restarts: 20,
+    // Do not inherit the invoking agent or shell environment: PM2 otherwise
+    // stores every inherited value in its process metadata.
+    // PM2 only activates filtering for a non-empty array.  Exclude every
+    // inherited key, then explicitly add the small runtime allowlist above.
+    filter_env: Object.keys(process.env),
+    env: {
+      ...runtimeEnv,
+      CLAUTH_OPS_INSTALLER_MARKER: INSTALLER_MARKER,
+      CLAUTH_OPS_ENABLED: [...config.enabled, ...(Object.keys(config.deployments).length ? ["deploy"] : []), ...(config.coolifyPromoteUuids.length ? ["coolify_promote"] : [])].join(","),
+      CLAUTH_OPS_APPLICATIONS: JSON.stringify(config.applications),
+      CLAUTH_OPS_ADMIN_ENABLED: config.adminEnabled.join(","),
+      CLAUTH_OPS_ADMIN_APPLICATIONS: JSON.stringify(config.adminApplications),
+      CLAUTH_OPS_ALLOW_HOST_WIDE: config.allowHostWide ? "1" : "0",
+      CLAUTH_OPS_DEPLOYMENTS: JSON.stringify(config.deployments),
+      CLAUTH_COOLIFY_PROMOTE_UUIDS: JSON.stringify(config.coolifyPromoteUuids),
+    },
+  };
+}
+
+function pm2Call(method, ...args) {
+  return new Promise((resolve, reject) => pm2[method](...args, (error, value) => error ? reject(error) : resolve(value)));
+}
+
+async function probe(endpoint) {
+  const health = await fetch(`${endpoint}/health`, { signal: AbortSignal.timeout(5000) });
+  const healthBody = health.ok ? await health.json() : null;
+  if (healthBody?.status !== "ok") throw new Error(`health probe failed at ${endpoint}`);
+  const catalog = await fetch(`${endpoint}/v1/ops/catalog`, { signal: AbortSignal.timeout(5000) });
+  if (catalog.status !== 401) throw new Error(`bearer gate probe failed: expected HTTP 401, received ${catalog.status}`);
+  return { health_status: health.status, bearer_gate_status: catalog.status, listening_port: healthBody.listening_port, process_id: healthBody.process_id };
+}
+
+function argsFor(entry) {
+  const value = entry?.pm2_env?.args ?? entry?.args ?? "";
+  return Array.isArray(value) ? value.join(" ") : String(value || "");
+}
+
+function ownedService(entry, spec) {
+  const env = entry?.pm2_env || {};
+  return env.CLAUTH_OPS_INSTALLER_MARKER === INSTALLER_MARKER
+    && path.resolve(env.pm_exec_path || "") === path.resolve(spec.script)
+    && path.resolve(env.pm_cwd || "") === path.resolve(spec.cwd)
+    && argsFor(entry) === spec.args;
+}
+
+export function previousSpec(entry) {
+  const env = entry.pm2_env || {};
+  const restored = {
+    name: env.name,
+    script: env.pm_exec_path,
+    args: argsFor(entry),
+    cwd: env.pm_cwd,
+    autorestart: env.autorestart !== false,
+    restart_delay: env.restart_delay || 1000,
+    max_restarts: env.max_restarts || 20,
+    filter_env: Object.keys(process.env),
+    env: Object.fromEntries(Object.entries(env).filter(([key]) => OPS_ENV_KEYS.has(key) || RUNTIME_ENV_KEYS.has(key))),
+  };
+  if (env.exec_interpreter !== undefined) restored.interpreter = env.exec_interpreter;
+  for (const key of RESTORABLE_PM2_KEYS) if (env[key] !== undefined) restored[key] = env[key];
+  return restored;
+}
+
+async function rollback(previous, name) {
+  try { await pm2Call("delete", name); } catch {}
+  if (previous) await pm2Call("start", previous);
+}
+
+export async function runOpsInstall(opts = {}) {
+  const configPath = path.resolve(requiredString(opts.config, "--config"));
+  const config = loadOpsInstallConfig(configPath);
+  const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+  const spec = buildOpsServiceSpec({ config, rootDir });
+  const endpoint = `http://127.0.0.1:${config.port}`;
+  if (opts.dryRun) {
+    process.stdout.write(`${JSON.stringify({ action: "install", dry_run: true, platform: process.platform, endpoint, pm2_name: config.pm2Name, policy_file: configPath, operations: Object.keys(config.applications).sort() }, null, 2)}\n`);
+    return;
+  }
+  await new Promise((resolve, reject) => pm2.connect(false, (error) => error ? reject(error) : resolve()));
+  let result;
+  let previous = null;
+  try {
+    const existing = (await pm2Call("list")).find((entry) => (entry.name || entry.pm2_env?.name) === config.pm2Name);
+    // PM2 rejects an inline `env` object on restart-by-name.  Replacing only
+    // this dedicated control-plane process is the supported way to apply a
+    // changed server policy without touching any managed application.
+    if (existing && !ownedService(existing, spec)) throw new Error(`refusing to replace non-installer PM2 process: ${config.pm2Name}`);
+    previous = existing ? previousSpec(existing) : null;
+    if (existing) await pm2Call("delete", config.pm2Name);
+    await pm2Call("start", spec);
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+      try {
+        result = await probe(endpoint);
+        const current = (await pm2Call("list")).find((entry) => (entry.name || entry.pm2_env?.name) === config.pm2Name);
+        const pid = current?.pid ?? current?.pm2_env?.pm_pid;
+        const status = current?.pm2_env?.status ?? current?.status;
+        if (status !== "online" || !Number.isInteger(pid) || result.process_id !== pid || result.listening_port !== config.port) {
+          throw new Error("new PM2 process does not own the verified control-plane endpoint");
+        }
+        break;
+      } catch (error) {
+        if (attempt === 19) throw error;
+        await new Promise((resolve) => setTimeout(resolve, 250));
+      }
+    }
+  } catch (error) {
+    await rollback(previous, config.pm2Name);
+    throw error;
+  } finally {
+    await new Promise((resolve) => pm2.disconnect(() => resolve()));
+  }
+  process.stdout.write(`${JSON.stringify({ action: "install", platform: process.platform, endpoint, pm2_name: config.pm2Name, policy_file: configPath, health_status: result.health_status, bearer_gate_status: result.bearer_gate_status }, null, 2)}\n`);
+}

package/cli/commands/ops.js

@@ -0,0 +1,69 @@
+const DEFAULT_LOCAL_CLAUTH = "http://127.0.0.1:52437";
+
+function endpointFrom(opts) {
+  const approved = process.env.CLAUTH_OPS_APPROVED_ORIGIN;
+  if (!approved) throw new Error("Ops endpoint unavailable: CLAUTH_OPS_APPROVED_ORIGIN is required");
+  const approvedUrl = new URL(approved);
+  const requested = opts.endpoint ? new URL(opts.endpoint) : approvedUrl;
+  if (approvedUrl.protocol !== "https:" || requested.origin !== approvedUrl.origin) throw new Error("Ops endpoint is not the approved Vultr origin");
+  return approvedUrl.toString().replace(/\/$/, "");
+}
+
+async function bearer(service = process.env.CLAUTH_OPS_TOKEN_SERVICE || "vultr-ops-api-token") {
+  const response = await fetch(`${process.env.CLAUTH_LOCAL_URL || DEFAULT_LOCAL_CLAUTH}/v/${encodeURIComponent(service)}`);
+  if (!response.ok) throw new Error(`${service} unavailable from local clauth`);
+  const token = (await response.text()).trim();
+  if (!token) throw new Error("vultr-ops-api-token is empty");
+  return token;
+}
+
+export async function requestOps({ endpoint, token, method, path, body }) {
+  const response = await fetch(`${endpoint}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${token}`, Accept: "application/json", ...(body ? { "Content-Type": "application/json" } : {}) },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+  });
+  const payload = await response.json().catch(() => ({ error: "invalid_json_response" }));
+  if (!response.ok) throw new Error(payload.error || `ops HTTP ${response.status}`);
+  return payload;
+}
+
+function print(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+export async function runOps(action, opts = {}) {
+  const endpoint = endpointFrom(opts);
+  const token = await bearer(opts.tokenService);
+  const request = (method, path, body) => requestOps({ endpoint, token, method, path, body });
+  if (action === "catalog") return print(await request("GET", "/v1/ops/catalog"));
+  if (action === "list") return print(await request("GET", "/v1/ops/processes"));
+  if (action === "describe") {
+    if (!opts.target) throw new Error("--target is required for describe");
+    return print(await request("GET", `/v1/ops/processes/${encodeURIComponent(opts.target)}`));
+  }
+  if (action === "run") {
+    if (!opts.operation) throw new Error("--operation is required for run");
+    const input = {
+      ...(opts.target ? { target: opts.target } : {}),
+      ...(opts.script ? { script: opts.script } : {}),
+      ...(opts.instances ? { instances: Number(opts.instances) } : {}),
+      ...(opts.argsJson ? { args: JSON.parse(opts.argsJson) } : {}),
+      ...(opts.optionsJson ? { options: JSON.parse(opts.optionsJson) } : {}),
+    };
+    return print(await request("POST", "/v1/ops/operations", { operation: opts.operation, input }));
+  }
+  if (action === "promote") {
+    if (!opts.application) throw new Error("--application is required for promote");
+    return print(await request("POST", "/v1/ops/promotions", { application_uuid: opts.application }));
+  }
+  if (action === "deploy") {
+    if (!opts.application) throw new Error("--application is required for deploy");
+    return print(await request("POST", "/v1/ops/deployments", { application: opts.application, ...(opts.ref ? { ref: opts.ref } : {}) }));
+  }
+  if (action === "job") {
+    if (!opts.job) throw new Error("--job is required for job");
+    return print(await request("GET", `/v1/ops/jobs/${encodeURIComponent(opts.job)}`));
+  }
+  throw new Error(`unknown ops action: ${action}`);
+}