@clearance/cli 0.1.4

package/dist/ops/scripts/upgrade-verify.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Post-apply upgrade verification: plan state, backup reference, schema health, optional HTTP.
+set -Eeuo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=lib/ops-common.sh
+source "$ROOT/scripts/lib/ops-common.sh"
+
+usage() {
+  cat <<'EOF'
+Usage: upgrade-verify.sh --plan PLAN_ID_OR_PATH [--dir DIR] [--health-url URL]
+EOF
+}
+
+PLAN_DIR="${CLEARANCE_UPGRADE_DIR:-$ROOT/.clearance/upgrades}"
+PLAN_REF=""
+HEALTH_URL="${CLEARANCE_HEALTH_URL:-}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --plan) PLAN_REF="$2"; shift 2 ;;
+    --dir) PLAN_DIR="$2"; shift 2 ;;
+    --health-url) HEALTH_URL="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) die "unknown argument: $1" ;;
+  esac
+done
+
+[[ -n "$PLAN_REF" ]] || die "--plan is required"
+if [[ -f "$PLAN_REF" ]]; then
+  PLAN_PATH="$PLAN_REF"
+else
+  PLAN_PATH="$PLAN_DIR/${PLAN_REF}.plan.json"
+fi
+[[ -f "$PLAN_PATH" ]] || die "plan not found"
+require_cmd node
+
+PLAN_ID="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.planId)' "$PLAN_PATH")"
+STATE_PATH="$PLAN_DIR/${PLAN_ID}.state.json"
+[[ -f "$STATE_PATH" ]] || die "state missing"
+
+STATUS="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.status||"")' "$STATE_PATH")"
+[[ "$STATUS" == "applied" || "$STATUS" == "verified" ]] || die "plan state is '$STATUS' (expected applied|verified)"
+
+BACKUP_ID="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.backupId||"")' "$STATE_PATH")"
+[[ -n "$BACKUP_ID" ]] || die "missing backupId rollback reference in state"
+BACKUP_META="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.backupMeta||"")' "$STATE_PATH")"
+[[ -f "$BACKUP_META" ]] || die "backup meta missing: $BACKUP_META"
+bash "$ROOT/scripts/backup-verify.sh" --dump "$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.backupDump)' "$STATE_PATH")" --meta "$BACKUP_META" >/dev/null
+
+# Schema still queryable
+if [[ -n "${DATABASE_URL:-}" ]]; then
+  require_pg_client
+  URL="$(resolve_database_url)"
+  psql_q "$URL" -c 'SELECT 1' >/dev/null || die "post-apply database health query failed"
+  TARGET="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.targetVersion)' "$PLAN_PATH")"
+  require_application_release "$URL" "$TARGET"
+  assert_safe_version "$TARGET" "target version"
+  LEDGER_PLAN="$(psql_q "$URL" -At -c "SELECT plan_id FROM clearance_schema_migrations WHERE version = '${TARGET}'")"
+  [[ "$LEDGER_PLAN" == "$PLAN_ID" ]] || die "migration ledger missing plan/version transition"
+  # Fingerprint may change after real migrations; ensure DB still has public schema access
+  EV="$(mktemp "${TMPDIR:-/tmp}/clearance-post-ev.XXXXXX")"
+  collect_db_evidence "$URL" "$EV"
+  [[ -s "$EV" ]] || die "failed to collect post-apply schema evidence"
+  rm -f "$EV"
+  printf 'upgrade-verify: database evidence collected\n' >&2
+fi
+
+# Optional HTTP health
+if [[ -n "$HEALTH_URL" ]]; then
+  require_cmd curl
+  code="$(curl -sS -o /dev/null -w '%{http_code}' "$HEALTH_URL" || true)"
+  [[ "$code" == "200" ]] || die "health URL $HEALTH_URL returned HTTP $code"
+  printf 'upgrade-verify: health URL OK\n' >&2
+fi
+
+# Applied marker exists
+MARKER="$PLAN_DIR/markers/${PLAN_ID}.applied"
+[[ -f "$MARKER" ]] || die "apply marker missing"
+
+TARGET="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.targetVersion)' "$PLAN_PATH")"
+MARKER_TO="$(node -e 'const fs=require("fs"); const j=JSON.parse(fs.readFileSync(process.argv[1],"utf8")); process.stdout.write(j.toVersion||"")' "$MARKER")"
+[[ "$MARKER_TO" == "$TARGET" ]] || die "marker version mismatch"
+
+node -e '
+  const fs=require("fs");
+  const p=process.argv[1];
+  const j=JSON.parse(fs.readFileSync(p,"utf8"));
+  const at=new Date().toISOString().replace(/\.\d{3}Z$/,"Z");
+  j.status="verified";
+  j.updatedAt=at;
+  j.applyJournal=j.applyJournal||[];
+  j.applyJournal.push({at, event:"verified"});
+  fs.writeFileSync(p, JSON.stringify(j,null,2)+"\n");
+' "$STATE_PATH"
+
+printf 'upgrade-verify: OK plan=%s target=%s\n' "$PLAN_ID" "$TARGET"
+printf 'VERIFY_OK=1\n'

package/dist/ops/scripts/validate-production-env.sh

@@ -0,0 +1,232 @@
+#!/usr/bin/env bash
+# Fail-closed production environment validation for Compose/Helm/TF operators.
+# Does not print secret values. Exits non-zero on any missing/weak/default secret.
+set -Eeuo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=lib/ops-common.sh
+source "$ROOT/scripts/lib/ops-common.sh"
+require_cmd node
+
+usage() {
+  cat <<'EOF'
+Usage: validate-production-env.sh
+
+Validates operator-supplied environment for production Compose overlay:
+  deploy/compose/docker-compose.production.yml
+
+Required (strong secrets, no defaults):
+  CLEARANCE_OPERATOR_TOKEN
+  CLEARANCE_SECRET
+  CLEARANCE_CREDENTIAL_KEY
+  CLEARANCE_CREDENTIAL_KEY_ID
+  CLEARANCE_CONSOLE_ADMIN_USER
+  CLEARANCE_CONSOLE_ADMIN_PASSWORD
+  CLEARANCE_CONSOLE_SESSION_SECRET
+  CLEARANCE_DB_USER
+  CLEARANCE_DB_PASSWORD
+  CLEARANCE_DB_NAME
+  DATABASE_URL          # full postgres URL; no compose password interpolation
+  CLEARANCE_BASE_URL
+  CLEARANCE_CONSOLE_URL
+  CLEARANCE_CORS_ORIGINS
+  CLEARANCE_API_PORT
+  CLEARANCE_CONSOLE_PORT
+  CLEARANCE_SAMPLE_PORT
+  CLEARANCE_PG_VOLUME
+  CLEARANCE_BACKUP_VOLUME
+  CLEARANCE_IMAGE_REPOSITORY
+  CLEARANCE_IMAGE_DIGEST          # sha256:... from the signed release
+  CLEARANCE_BACKUP_IMAGE_REPOSITORY
+  CLEARANCE_BACKUP_IMAGE_DIGEST   # sha256:... from the signed release
+
+Optional:
+  CLEARANCE_POSTGRES_PORT  # only if intentionally publishing Postgres to the host
+  CLEARANCE_GITHUB_CLIENT_ID + CLEARANCE_GITHUB_CLIENT_SECRET
+  CLEARANCE_GOOGLE_CLIENT_ID + CLEARANCE_GOOGLE_CLIENT_SECRET
+
+Fails closed on missing, empty, short, or known-weak values.
+EOF
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+errors=0
+note() { printf 'ok: %s\n' "$*"; }
+fail() { printf 'fail: %s\n' "$*" >&2; errors=$((errors + 1)); }
+
+check_secret() {
+  local label="$1"
+  local value="${2-}"
+  if is_forbidden_secret "$value"; then
+    fail "$label is missing, empty, short (<16), or a known weak default"
+  else
+    note "$label present and not a known weak default (len=${#value})"
+  fi
+}
+
+check_present() {
+  local label="$1"
+  local value="${2-}"
+  if [[ -z "$value" ]]; then
+    fail "$label is required and must be non-empty"
+  else
+    note "$label is set"
+  fi
+}
+
+check_port() {
+  local label="$1"
+  local value="$2"
+  if [[ ! "$value" =~ ^[0-9]+$ ]] || (( 10#$value < 1 || 10#$value > 65535 )); then
+    fail "$label must be an integer from 1 through 65535"
+  else
+    note "$label is a valid TCP port"
+  fi
+}
+
+check_https_url() {
+  local label="$1"
+  local value="$2"
+  if [[ "$value" =~ ^https://[^[:space:]]+$ ]]; then
+    note "$label uses HTTPS"
+  elif [[ "${CLEARANCE_ALLOW_LOCALHOST_PRODUCTION:-}" == "1" \
+    && "$value" =~ ^http://(localhost|127\.0\.0\.1)(:[0-9]+)?(/.*)?$ ]]; then
+    note "$label uses explicitly allowed local HTTP"
+  else
+    fail "$label must be an absolute HTTPS URL (local HTTP requires CLEARANCE_ALLOW_LOCALHOST_PRODUCTION=1)"
+  fi
+}
+
+# Secrets / credentials
+check_secret CLEARANCE_OPERATOR_TOKEN "${CLEARANCE_OPERATOR_TOKEN-}"
+check_secret CLEARANCE_SECRET "${CLEARANCE_SECRET-}"
+check_secret CLEARANCE_CREDENTIAL_KEY "${CLEARANCE_CREDENTIAL_KEY-}"
+check_present CLEARANCE_CREDENTIAL_KEY_ID "${CLEARANCE_CREDENTIAL_KEY_ID-}"
+check_present CLEARANCE_CONSOLE_ADMIN_USER "${CLEARANCE_CONSOLE_ADMIN_USER-}"
+check_secret CLEARANCE_CONSOLE_ADMIN_PASSWORD "${CLEARANCE_CONSOLE_ADMIN_PASSWORD-}"
+check_secret CLEARANCE_CONSOLE_SESSION_SECRET "${CLEARANCE_CONSOLE_SESSION_SECRET-}"
+check_secret CLEARANCE_DB_PASSWORD "${CLEARANCE_DB_PASSWORD-}"
+
+# Non-secret required production knobs (no compose defaults in overlay)
+check_present CLEARANCE_DB_USER "${CLEARANCE_DB_USER-}"
+check_present CLEARANCE_DB_NAME "${CLEARANCE_DB_NAME-}"
+check_present CLEARANCE_BASE_URL "${CLEARANCE_BASE_URL-}"
+check_present CLEARANCE_CONSOLE_URL "${CLEARANCE_CONSOLE_URL-}"
+check_present CLEARANCE_CORS_ORIGINS "${CLEARANCE_CORS_ORIGINS-}"
+check_port CLEARANCE_API_PORT "${CLEARANCE_API_PORT-}"
+check_port CLEARANCE_CONSOLE_PORT "${CLEARANCE_CONSOLE_PORT-}"
+check_port CLEARANCE_SAMPLE_PORT "${CLEARANCE_SAMPLE_PORT-}"
+check_present CLEARANCE_PG_VOLUME "${CLEARANCE_PG_VOLUME-}"
+check_present CLEARANCE_BACKUP_VOLUME "${CLEARANCE_BACKUP_VOLUME-}"
+check_present CLEARANCE_IMAGE_REPOSITORY "${CLEARANCE_IMAGE_REPOSITORY-}"
+check_present CLEARANCE_BACKUP_IMAGE_REPOSITORY "${CLEARANCE_BACKUP_IMAGE_REPOSITORY-}"
+if [[ "${CLEARANCE_IMAGE_DIGEST-}" =~ ^sha256:[0-9a-f]{64}$ ]]; then
+  note "CLEARANCE_IMAGE_DIGEST is an immutable sha256 digest"
+else
+  fail "CLEARANCE_IMAGE_DIGEST must be sha256 followed by 64 lowercase hex characters"
+fi
+if [[ "${CLEARANCE_BACKUP_IMAGE_DIGEST-}" =~ ^sha256:[0-9a-f]{64}$ ]]; then
+  note "CLEARANCE_BACKUP_IMAGE_DIGEST is an immutable sha256 digest"
+else
+  fail "CLEARANCE_BACKUP_IMAGE_DIGEST must be sha256 followed by 64 lowercase hex characters"
+fi
+
+check_optional_pair() {
+  local provider="$1"
+  local client_id="$2"
+  local client_secret="$3"
+  if [[ -n "$client_id" && -n "$client_secret" ]]; then
+    check_secret "${provider} client secret" "$client_secret"
+    note "${provider} social credentials are configured as a complete pair"
+  elif [[ -n "$client_id" || -n "$client_secret" ]]; then
+    fail "${provider} social credentials must set both client id and client secret"
+  else
+    note "${provider} social provider is disabled"
+  fi
+}
+
+check_optional_pair GitHub "${CLEARANCE_GITHUB_CLIENT_ID-}" "${CLEARANCE_GITHUB_CLIENT_SECRET-}"
+check_optional_pair Google "${CLEARANCE_GOOGLE_CLIENT_ID-}" "${CLEARANCE_GOOGLE_CLIENT_SECRET-}"
+
+# DATABASE_URL: full string required — refuse weak defaults and incomplete forms.
+if is_weak_database_url "${DATABASE_URL-}"; then
+  fail "DATABASE_URL missing, not a postgres URL, or uses weak/default credentials (redacted=$(redact_url "${DATABASE_URL-}"))"
+else
+  note "DATABASE_URL looks like a non-default postgres URL (redacted=$(redact_url "$DATABASE_URL"))"
+fi
+
+# The database container credentials and application URL must describe the same
+# user, password, and database. Compare via process environment; print no values.
+if [[ -n "${DATABASE_URL-}" ]]; then
+  if DATABASE_URL_CHECK="$DATABASE_URL" \
+    EXPECT_DB_USER="${CLEARANCE_DB_USER-}" \
+    EXPECT_DB_PASSWORD="${CLEARANCE_DB_PASSWORD-}" \
+    EXPECT_DB_NAME="${CLEARANCE_DB_NAME-}" \
+    node -e '
+      const u=new URL(process.env.DATABASE_URL_CHECK);
+      if(!/^postgres(ql)?:$/.test(u.protocol)) process.exit(1);
+      if(decodeURIComponent(u.username)!==process.env.EXPECT_DB_USER) process.exit(2);
+      if(decodeURIComponent(u.password)!==process.env.EXPECT_DB_PASSWORD) process.exit(3);
+      if(decodeURIComponent(u.pathname.replace(/^\//,""))!==process.env.EXPECT_DB_NAME) process.exit(4);
+    ' 2>/dev/null; then
+    note "DATABASE_URL credentials and database match Compose Postgres settings"
+  else
+    fail "DATABASE_URL user/password/database must match CLEARANCE_DB_USER/CLEARANCE_DB_PASSWORD/CLEARANCE_DB_NAME"
+  fi
+fi
+
+check_https_url CLEARANCE_BASE_URL "${CLEARANCE_BASE_URL-}"
+check_https_url CLEARANCE_CONSOLE_URL "${CLEARANCE_CONSOLE_URL-}"
+IFS=',' read -r -a cors_origins <<<"${CLEARANCE_CORS_ORIGINS-}"
+for origin in "${cors_origins[@]}"; do
+  check_https_url "CLEARANCE_CORS_ORIGINS entry" "${origin//[[:space:]]/}"
+done
+
+# Refuse localhost-only defaults that are fine for dev but not production profiles
+if [[ "${CLEARANCE_BASE_URL-}" == *"localhost"* || "${CLEARANCE_BASE_URL-}" == *"127.0.0.1"* ]]; then
+  if [[ "${CLEARANCE_ALLOW_LOCALHOST_PRODUCTION:-}" != "1" ]]; then
+    fail "CLEARANCE_BASE_URL points at localhost; set CLEARANCE_ALLOW_LOCALHOST_PRODUCTION=1 only for intentional local prod-profile tests"
+  else
+    note "CLEARANCE_BASE_URL is localhost (explicitly allowed for local prod-profile tests)"
+  fi
+fi
+
+# NODE_ENV must not be development when operators claim production
+if [[ "${NODE_ENV-}" == "development" || "${CLEARANCE_NODE_ENV-}" == "development" ]]; then
+  fail "NODE_ENV/CLEARANCE_NODE_ENV must not be 'development' for production validation"
+else
+  note "NODE_ENV is not development"
+fi
+
+# Compose production overlay must exist
+overlay="$ROOT/deploy/compose/docker-compose.production.yml"
+if [[ ! -f "$overlay" ]]; then
+  fail "missing production overlay: deploy/compose/docker-compose.production.yml"
+else
+  # Static fail-closed markers in overlay
+  if grep -qE 'CLEARANCE_SECRET:-\$\{|:-dev|:-secret|:-change-me|:-clearance\}' "$overlay"; then
+    fail "production overlay appears to embed weak defaults"
+  fi
+  if grep -qE 'DATABASE_URL:-\$\{' "$overlay"; then
+    fail "production overlay must not construct DATABASE_URL from password parts"
+  fi
+  if ! grep -q 'DATABASE_URL: \${DATABASE_URL:?' "$overlay"; then
+    fail "production overlay must require DATABASE_URL with fail-closed \${DATABASE_URL:?...}"
+  fi
+  if ! grep -q 'NODE_ENV: production' "$overlay"; then
+    fail "production overlay must force NODE_ENV: production"
+  fi
+  note "production overlay present with fail-closed DATABASE_URL and NODE_ENV"
+fi
+
+if [[ "$errors" -ne 0 ]]; then
+  printf '\nvalidate-production-env: FAILED (%s checks)\n' "$errors" >&2
+  exit 1
+fi
+
+printf '\nvalidate-production-env: OK\n'
+exit 0

package/dist/output.d.ts

@@ -0,0 +1,19 @@
+import { ClearanceError } from "@clearance/management";
+export interface GlobalOpts {
+    json?: boolean;
+    noInput?: boolean;
+    yes?: boolean;
+    dryRun?: boolean;
+    dataPath?: string;
+    localDirect?: boolean;
+    profile?: string;
+    apiUrl?: string;
+}
+export declare class CliExitError extends Error {
+    readonly exitCode: number;
+    constructor(exitCode?: number);
+}
+export declare function printResult(opts: GlobalOpts, data: unknown, human?: string): void;
+export declare function fail(err: unknown, opts: GlobalOpts): never;
+export declare function exitCodeFromDoctor(ok: boolean): number;
+export declare function asClearanceError(err: unknown): ClearanceError | null;

package/dist/output.js

@@ -0,0 +1,52 @@
+import { isClearanceError } from "@clearance/management";
+export class CliExitError extends Error {
+    exitCode;
+    constructor(exitCode = 1) {
+        super("CLI command failed");
+        this.name = "CliExitError";
+        this.exitCode = exitCode;
+    }
+}
+export function printResult(opts, data, human) {
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+        return;
+    }
+    if (human) {
+        process.stdout.write(`${human}\n`);
+        return;
+    }
+    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+}
+export function fail(err, opts) {
+    // A CliExitError means fail() already emitted a structured document and is
+    // unwinding. Re-throw untouched so a catch block that funnels back into
+    // fail() can never emit a second JSON document on stdout (--json contract:
+    // exactly one document per invocation).
+    if (err instanceof CliExitError) {
+        throw err;
+    }
+    if (isClearanceError(err)) {
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(err.toJSON(), null, 2)}\n`);
+        }
+        else {
+            process.stderr.write(`Error [${err.code}] stage=${err.stage}: ${err.message}\nRemediation: ${err.remediation}\n`);
+        }
+        throw new CliExitError(1);
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify({ error: { code: "INTERNAL", message, stage: "unknown", retryable: false } }, null, 2)}\n`);
+    }
+    else {
+        process.stderr.write(`Error: ${message}\n`);
+    }
+    throw new CliExitError(1);
+}
+export function exitCodeFromDoctor(ok) {
+    return ok ? 0 : 2;
+}
+export function asClearanceError(err) {
+    return isClearanceError(err) ? err : null;
+}

package/dist/remote-dispatch.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from "commander";
+import { type ApiSession } from "./api-client.js";
+import type { GlobalOpts } from "./output.js";
+export declare const HOST_LOCAL_COMMANDS: Map<string, string>;
+export declare const REMOTE_COMMANDS: Set<string>;
+export type CommandExecution = "authentication" | "remote-api" | "host-local" | "unavailable";
+export declare function classifyCommandPath(path: string): CommandExecution;
+export declare function commandPath(command: Command): string;
+export declare function isHostLocalCommand(path: string): boolean;
+export declare function dispatchRemoteCommand(session: ApiSession, path: string, args: unknown[], opts: Record<string, unknown>, global: GlobalOpts): Promise<unknown>;

package/dist/remote-dispatch.js

@@ -0,0 +1,232 @@
+import { ClearanceError } from "@clearance/management";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { requestManagementApi } from "./api-client.js";
+export const HOST_LOCAL_COMMANDS = new Map([
+    ["dev", "prints and launches host development paths"],
+    ["users export", "writes a bounded export to a caller-selected host path"],
+    ["orgs members import", "reads a caller-selected host file"],
+    ["events export", "writes a bounded export to a caller-selected host path"],
+    ["events tail", "owns a long-running terminal stream"],
+    ["import legacy", "reads a migration fixture from the host"],
+    ["migration plan", "creates host migration artifacts"],
+    ["migration run", "executes a host migration artifact"],
+    ["migration verify", "verifies a host migration fixture"],
+    ["migration rollback", "rolls back a host migration fixture"],
+    ["migration status", "inspects host migration artifacts"],
+    ["backup create", "runs database tooling and writes a host backup"],
+    ["backup verify", "verifies a host backup artifact"],
+    ["backup restore", "runs database tooling against the selected host"],
+    ["upgrade check", "inspects host deployment and database state"],
+    ["upgrade plan", "creates signed host upgrade artifacts"],
+    ["upgrade apply", "runs host deployment and database upgrade tooling"],
+    ["upgrade verify", "verifies host upgrade artifacts and database state"],
+    ["upgrade rollback", "restores or verifies a host database backup"],
+    ["schema status", "inspects the directly selected runtime database"],
+    ["schema generate", "writes SQL to a caller-selected host path"],
+    ["schema migrate", "runs migrations against the directly selected runtime database"],
+]);
+export const REMOTE_COMMANDS = new Set([
+    "init", "doctor", "overview",
+    "project list", "project inspect", "project create",
+    "env list", "env inspect", "env create", "env promote",
+    "users list", "users inspect", "users create", "users update", "users disable", "users delete",
+    "orgs list", "orgs inspect", "orgs create", "orgs update", "orgs archive",
+    "orgs members list", "orgs members add", "orgs members update", "orgs members remove",
+    "events list", "events inspect", "events replay",
+    "keys list", "keys create", "keys rotate", "keys revoke",
+    "sessions list", "sessions revoke",
+    "roles list", "roles validate", "roles create", "roles update",
+    "sso create", "sso configure", "sso test", "sso list", "sso setup-link", "sso rotate", "sso disable",
+    "scim create", "scim test", "scim list", "scim setup-link", "scim rotate", "scim disable", "scim replay",
+    "readiness check", "readiness report",
+    "config get", "config set", "config validate", "config diff",
+]);
+export function classifyCommandPath(path) {
+    if (path === "login" || path === "logout" || path === "whoami")
+        return "authentication";
+    if (HOST_LOCAL_COMMANDS.has(path))
+        return "host-local";
+    if (REMOTE_COMMANDS.has(path))
+        return "remote-api";
+    return "unavailable";
+}
+function error(code, message, remediation) {
+    return new ClearanceError({ code, message, stage: "cli.dispatch", remediation });
+}
+function query(path, values) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(values)) {
+        if (value !== undefined && value !== false && value !== "")
+            params.set(key, String(value));
+    }
+    return `${path}${params.size ? `?${params}` : ""}`;
+}
+function body(values) {
+    return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
+}
+export function commandPath(command) {
+    const names = [];
+    let current = command;
+    while (current?.parent) {
+        names.unshift(current.name());
+        current = current.parent;
+    }
+    return names.join(" ");
+}
+export function isHostLocalCommand(path) {
+    return HOST_LOCAL_COMMANDS.has(path);
+}
+function requireRemoteMutation(global, path) {
+    if (global.dryRun) {
+        throw error("CLI_REMOTE_DRY_RUN_UNSUPPORTED", `${path} does not yet expose a server-side dry-run contract.`, "Use the command without --dry-run, or choose --local-direct for a local development preview.");
+    }
+}
+function requireConfirmation(global, code, label) {
+    if (!global.yes && !global.dryRun) {
+        throw error(code, `${label} requires --yes.`, "Review the target, then pass --yes to confirm.");
+    }
+}
+function requireLiveTestMode(global, code, label) {
+    if (global.dryRun) {
+        throw error(code, `${label} cannot combine --live with --dry-run.`, "Remove --dry-run, review the live target, then pass --yes to confirm.");
+    }
+    requireConfirmation(global, code, label);
+}
+export async function dispatchRemoteCommand(session, path, args, opts, global) {
+    const id = typeof args[0] === "string" ? encodeURIComponent(args[0]) : "";
+    switch (path) {
+        case "init":
+            requireRemoteMutation(global, path);
+            return requestManagementApi(session, { method: "POST", path: "/v1/init", body: body({ name: opts.name, environment: opts.environment }) });
+        case "doctor": return requestManagementApi(session, { path: "/v1/doctor" });
+        case "overview": return requestManagementApi(session, { path: "/v1/overview" });
+        case "project list": return requestManagementApi(session, { path: "/v1/projects" });
+        case "project inspect": return requestManagementApi(session, { path: id ? `/v1/projects/${id}` : "/v1/projects/current" });
+        case "project create":
+            return requestManagementApi(session, { method: "POST", path: "/v1/projects", body: { name: opts.name, dryRun: global.dryRun } });
+        case "env list": return requestManagementApi(session, { path: "/v1/environments" });
+        case "env inspect": return requestManagementApi(session, { path: id ? `/v1/environments/${id}` : "/v1/environments/current" });
+        case "env create":
+            return requestManagementApi(session, { method: "POST", path: "/v1/environments", body: body({ name: opts.name, projectId: opts.projectId, kind: opts.kind, dryRun: global.dryRun }) });
+        case "env promote":
+            return requestManagementApi(session, { method: "POST", path: "/v1/environments/promote", body: body({ to: opts.to, from: opts.from, dryRun: global.dryRun || !global.yes, confirm: global.yes && !global.dryRun }) });
+        case "users list": return requestManagementApi(session, { path: query("/v1/users", { limit: opts.limit, cursor: opts.cursor }) });
+        case "users inspect": return requestManagementApi(session, { path: `/v1/users/${id}` });
+        case "users create":
+            return requestManagementApi(session, { method: "POST", path: "/v1/users", body: body({ email: opts.email, name: opts.name, password: opts.password, dryRun: global.dryRun }) });
+        case "users update":
+            return requestManagementApi(session, { method: "PATCH", path: `/v1/users/${id}`, body: body({ email: opts.email, name: opts.name, status: opts.status, dryRun: global.dryRun }) });
+        case "users disable":
+            return requestManagementApi(session, { method: "POST", path: `/v1/users/${id}/disable`, body: { dryRun: global.dryRun } });
+        case "users delete":
+            requireConfirmation(global, "USER_DELETE_CONFIRM_REQUIRED", "User deletion");
+            requireRemoteMutation(global, path);
+            return requestManagementApi(session, { method: "DELETE", path: `/v1/users/${id}` });
+        case "orgs list": return requestManagementApi(session, { path: query("/v1/organizations", { limit: opts.limit, cursor: opts.cursor }) });
+        case "orgs inspect": return requestManagementApi(session, { path: `/v1/organizations/${id}` });
+        case "orgs create":
+            requireRemoteMutation(global, path);
+            return requestManagementApi(session, { method: "POST", path: "/v1/organizations", body: body({ name: opts.name, slug: opts.slug, ownerUserId: opts.ownerUser }) });
+        case "orgs update":
+            return requestManagementApi(session, { method: "PATCH", path: `/v1/organizations/${id}`, body: body({ name: opts.name, slug: opts.slug, dryRun: global.dryRun }) });
+        case "orgs archive":
+            return requestManagementApi(session, { method: "POST", path: `/v1/organizations/${id}/archive`, body: { dryRun: global.dryRun || !global.yes, confirm: global.yes && !global.dryRun } });
+        case "orgs members list": return requestManagementApi(session, { path: `/v1/organizations/${encodeURIComponent(String(opts.org))}/members` });
+        case "orgs members add":
+            return requestManagementApi(session, { method: "POST", path: `/v1/organizations/${encodeURIComponent(String(opts.org))}/members`, body: body({ principalId: opts.user, role: opts.role, dryRun: global.dryRun }) });
+        case "orgs members update": {
+            if (!opts.member)
+                throw error("CLI_REMOTE_MEMBER_ID_REQUIRED", "Remote member update requires --member.", "List organization members and pass the membership id with --member.");
+            return requestManagementApi(session, { method: "PATCH", path: `/v1/organizations/${encodeURIComponent(String(opts.org))}/members/${encodeURIComponent(String(opts.member))}`, body: { role: opts.role, dryRun: global.dryRun } });
+        }
+        case "orgs members remove": {
+            requireConfirmation(global, "MEMBER_REMOVE_CONFIRM_REQUIRED", "Membership removal");
+            if (!opts.member)
+                throw error("CLI_REMOTE_MEMBER_ID_REQUIRED", "Remote member removal requires --member.", "List organization members and pass the membership id with --member.");
+            return requestManagementApi(session, { method: "DELETE", path: `/v1/organizations/${encodeURIComponent(String(opts.org))}/members/${encodeURIComponent(String(opts.member))}`, body: { dryRun: global.dryRun } });
+        }
+        case "events list": return requestManagementApi(session, { path: query("/v1/events", { limit: opts.limit, cursor: opts.cursor, action: opts.action, actor: opts.actor, outcome: opts.outcome }) });
+        case "events inspect": return requestManagementApi(session, { path: `/v1/events/${id}` });
+        case "events replay": return requestManagementApi(session, { method: "POST", path: "/v1/events/replay", body: { id: args[0], dryRun: global.dryRun || !global.yes, confirm: global.yes && !global.dryRun } });
+        case "keys list": return requestManagementApi(session, { path: query("/v1/keys", { includeRevoked: opts.includeRevoked }) });
+        case "keys create":
+            return requestManagementApi(session, { method: "POST", path: "/v1/keys", body: { name: opts.name, scopes: opts.scope, dryRun: global.dryRun } });
+        case "keys rotate":
+            requireConfirmation(global, "API_KEY_CONFIRMATION_REQUIRED", "API key rotation");
+            return requestManagementApi(session, { method: "POST", path: `/v1/keys/${id}/rotate`, body: { dryRun: global.dryRun } });
+        case "keys revoke":
+            requireConfirmation(global, "API_KEY_CONFIRMATION_REQUIRED", "API key revocation");
+            return requestManagementApi(session, { method: "POST", path: `/v1/keys/${id}/revoke`, body: { dryRun: global.dryRun } });
+        case "sessions list": return requestManagementApi(session, { path: query("/v1/sessions", { limit: opts.limit, cursor: opts.cursor, userId: opts.user, status: opts.status }) });
+        case "sessions revoke":
+            requireConfirmation(global, "SESSION_REVOKE_CONFIRM_REQUIRED", "Session revocation");
+            requireRemoteMutation(global, path);
+            return requestManagementApi(session, { method: "POST", path: `/v1/sessions/${id}/revoke` });
+        case "roles list": return requestManagementApi(session, { path: "/v1/roles" });
+        case "roles validate": return requestManagementApi(session, { method: "POST", path: "/v1/roles/validate", body: body({ name: opts.name, slug: opts.slug, permissions: opts.permission }) });
+        case "roles create":
+            return requestManagementApi(session, { method: "POST", path: "/v1/roles", body: body({ name: opts.name, slug: opts.slug, description: opts.description, permissions: opts.permission, dryRun: global.dryRun }) });
+        case "roles update":
+            return requestManagementApi(session, { method: "PATCH", path: `/v1/roles/${id}`, body: body({ name: opts.name, description: opts.description, permissions: opts.permission, dryRun: global.dryRun }) });
+        case "sso create":
+            requireRemoteMutation(global, path);
+            return requestManagementApi(session, { method: "POST", path: "/v1/sso", body: body({ organizationId: opts.org, provider: opts.provider, protocol: opts.protocol, issuer: opts.issuer, audience: opts.audience, domain: opts.domain, samlEntryPoint: opts.entryPoint, samlCertificate: opts.certificate ? readFileSync(resolve(String(opts.certificate)), "utf8") : undefined }) });
+        case "sso configure":
+            requireRemoteMutation(global, path);
+            return requestManagementApi(session, { method: "PATCH", path: `/v1/sso/${id}`, body: body({ issuer: opts.issuer, audience: opts.audience, domain: opts.domain }) });
+        case "sso test":
+            if (opts.live && opts.fixture)
+                throw error("SSO_TEST_MODE_CONFLICT", "--live and --fixture are mutually exclusive.", "Use one SSO test mode.");
+            if (opts.live)
+                requireLiveTestMode(global, "SSO_LIVE_CONFIRM_REQUIRED", "Live SSO conformance");
+            return requestManagementApi(session, { method: "POST", path: `/v1/sso/${id}/test`, body: body({ fixture: opts.fixture, live: opts.live }) });
+        case "sso list": return requestManagementApi(session, { path: query("/v1/sso", { organizationId: opts.org }) });
+        case "sso setup-link":
+            requireRemoteMutation(global, path);
+            return requestManagementApi(session, { method: "POST", path: "/v1/sso/setup-links", body: { organizationId: opts.org } });
+        case "sso rotate":
+            requireConfirmation(global, "SSO_CONFIRM_REQUIRED", "SSO credential rotation");
+            return requestManagementApi(session, { method: "POST", path: `/v1/sso/${id}/rotate`, body: { dryRun: global.dryRun } });
+        case "sso disable":
+            requireConfirmation(global, "SSO_DISABLE_CONFIRM_REQUIRED", "SSO disable");
+            return requestManagementApi(session, { method: "POST", path: `/v1/sso/${id}/disable`, body: { dryRun: global.dryRun } });
+        case "scim create":
+            requireRemoteMutation(global, path);
+            return requestManagementApi(session, { method: "POST", path: "/v1/scim", body: body({ organizationId: opts.org, provider: opts.provider, endpoint: opts.endpoint }) });
+        case "scim test":
+            if (opts.live && opts.fixture)
+                throw error("SCIM_TEST_MODE_CONFLICT", "--live and --fixture are mutually exclusive.", "Use one SCIM test mode.");
+            if (opts.live)
+                requireLiveTestMode(global, "SCIM_LIVE_CONFIRM_REQUIRED", "Live SCIM conformance");
+            return requestManagementApi(session, { method: "POST", path: `/v1/scim/${id}/test`, body: body({ fixture: opts.fixture, live: opts.live, dryRun: !opts.apply }) });
+        case "scim list": return requestManagementApi(session, { path: query("/v1/scim", { organizationId: opts.org }) });
+        case "scim setup-link":
+            requireRemoteMutation(global, path);
+            return requestManagementApi(session, { method: "POST", path: "/v1/scim/setup-links", body: { organizationId: opts.org } });
+        case "scim rotate":
+            requireConfirmation(global, "SCIM_CONFIRM_REQUIRED", "SCIM credential rotation");
+            return requestManagementApi(session, { method: "POST", path: `/v1/scim/${id}/rotate`, body: { dryRun: global.dryRun } });
+        case "scim disable":
+            requireConfirmation(global, "SCIM_DISABLE_CONFIRM_REQUIRED", "SCIM disable");
+            return requestManagementApi(session, { method: "POST", path: `/v1/scim/${id}/disable`, body: { dryRun: global.dryRun } });
+        case "scim replay":
+            return requestManagementApi(session, { method: "POST", path: `/v1/scim/traces/${encodeURIComponent(String(args[0]))}/replay`, body: { dryRun: global.dryRun || !global.yes, confirm: global.yes && !global.dryRun } });
+        case "readiness check":
+            requireRemoteMutation(global, path);
+            return requestManagementApi(session, { method: "POST", path: "/v1/readiness/check", body: { organizationId: opts.org } });
+        case "readiness report": return requestManagementApi(session, { path: `/v1/readiness/${encodeURIComponent(String(opts.org))}` });
+        case "config get": return requestManagementApi(session, { path: query("/v1/config", { key: args[0] }) });
+        case "config set": return requestManagementApi(session, { method: "PATCH", path: `/v1/config/${encodeURIComponent(String(args[0]))}`, body: { value: args[1], dryRun: global.dryRun } });
+        case "config validate": {
+            const config = opts.file ? JSON.parse(readFileSync(resolve(String(opts.file)), "utf8")) : undefined;
+            return requestManagementApi(session, { method: "POST", path: "/v1/config/validate", body: body({ config }) });
+        }
+        case "config diff": {
+            const config = JSON.parse(readFileSync(resolve(String(opts.file)), "utf8"));
+            return requestManagementApi(session, { method: "POST", path: "/v1/config/diff", body: { config } });
+        }
+        default:
+            throw error("CLI_REMOTE_COMMAND_UNAVAILABLE", `${path} has no versioned management API contract in this release.`, "Upgrade the Clearance API, or use --local-direct only for a development or host-local workflow.");
+    }
+}