@clearance/cli 0.1.4 → 0.2.1

package/dist/__tests__/api-test-server.d.ts

@@ -0,0 +1,2 @@
+export declare function authenticatedApiEnv(dataPath: string): NodeJS.ProcessEnv;
+export declare function stopAuthenticatedApiServers(): void;

package/dist/__tests__/api-test-server.js

@@ -0,0 +1,73 @@
+import { execFileSync, spawn } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const apiEntry = resolve(dirname(fileURLToPath(import.meta.url)), "../../../clearance-api/dist/server.js");
+const OPERATOR_TOKEN = "test-operator-token-for-cli-api-32chars!!";
+const servers = new Map();
+function allocatePort() {
+    return Number(execFileSync(process.execPath, [
+        "-e",
+        "const net=require('node:net');const s=net.createServer();s.listen(0,'127.0.0.1',()=>{console.log(s.address().port);s.close()})",
+    ], { encoding: "utf8" }).trim());
+}
+function pause(milliseconds) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+export function authenticatedApiEnv(dataPath) {
+    const existing = servers.get(dataPath);
+    if (existing) {
+        return {
+            CLEARANCE_OPERATOR_TOKEN: OPERATOR_TOKEN,
+            CLEARANCE_API_URL: existing.apiUrl,
+        };
+    }
+    const port = allocatePort();
+    const apiUrl = `http://127.0.0.1:${port}`;
+    const child = spawn(process.execPath, [apiEntry], {
+        env: {
+            ...process.env,
+            DATABASE_URL: "",
+            CLEARANCE_DATA_PATH: dataPath,
+            CLEARANCE_API_PORT: String(port),
+            CLEARANCE_OPERATOR_TOKEN: OPERATOR_TOKEN,
+            CLEARANCE_SECRET: "unit-test-secret-value-not-default!!",
+            CLEARANCE_BASE_URL: apiUrl,
+            CLEARANCE_CORS_ORIGINS: "http://localhost:3100",
+            CLEARANCE_CREDENTIAL_KEY: "unit-test-credential-key-material-32b!!",
+            CLEARANCE_CREDENTIAL_KEY_ID: "k1",
+            NODE_ENV: "development",
+        },
+        stdio: ["ignore", "ignore", "ignore"],
+    });
+    servers.set(dataPath, { process: child, apiUrl });
+    let ready = false;
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+        if (child.exitCode !== null)
+            break;
+        try {
+            execFileSync("curl", ["--fail", "--silent", "--max-time", "1", `${apiUrl}/livez`], {
+                stdio: "ignore",
+            });
+            ready = true;
+            break;
+        }
+        catch {
+            pause(50);
+        }
+    }
+    if (!ready) {
+        child.kill("SIGTERM");
+        servers.delete(dataPath);
+        throw new Error(`Clearance API test server failed to start at ${apiUrl}`);
+    }
+    return {
+        CLEARANCE_OPERATOR_TOKEN: OPERATOR_TOKEN,
+        CLEARANCE_API_URL: apiUrl,
+    };
+}
+export function stopAuthenticatedApiServers() {
+    for (const server of servers.values()) {
+        server.process.kill("SIGTERM");
+    }
+    servers.clear();
+}

package/dist/index.js

@@ -1,15 +1,14 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { addMember, addMemberInAuth, executeMemberImportPlan, planMemberImport, archiveOrganization, archiveOrganizationInAuth, createBackup, createEnvironment, createProject, createOrganization, createOrgInAuth, createScimConnection, createSetupLink, createSsoConnection, createSsoConnectionReal, testSsoConnectionReal, testSsoConnectionLive, testScimConnectionLive, createScimConnectionReal, testScimConnectionReal, ensureAuthMigrated, createPostgresBackup, createRole, createApiKey, verifyPostgresBackup, restorePostgresBackup, upgradeCheckWithDb, createUser, createUserInAuth, configureSsoConnection, closeAuthBundle, deleteUser, deleteUserInAuth, disableScimConnection, disableScimConnectionReal, disableSsoConnection, disableSsoConnectionReal, disableUser, disableUserInAuth, exportUsers, USERS_EXPORT_MAX_LIMIT, getLatestReadiness, initProject, inspectEnvironment, inspectApiKey, inspectScimConnection, inspectSsoConnection, inspectSession, inspectSessionInAuth, inspectOrganization, inspectUser, listEnvironments, listEventsPage, exportEvents, EVENTS_EXPORT_MAX_LIMIT, EVENTS_TAIL_MAX_LIMIT, beginEventsTail, pollEventsTail, inspectEvent, replayDiagnosticTrace, listMembers, listOrganizations, listOrganizationsPage, listProjects, listRoles, listApiKeys, normalizeAndValidateApiKeyScopes, listScimConnections, listSessionsPage, listSessionsPageInAuth, listSsoConnections, listUsers, listUsersPage, ClearanceError, promoteEnvironment, removeMember, removeMemberInAuth, resolveMembershipId, revokeSession, revokeSessionInAuth, revokeApiKey, rotateScimCredential, rotateSsoCredential, rotateApiKey, updateMember, updateMemberInAuth, updateOrganization, updateOrganizationInAuth, updateUser, updateUserInAuth, loadLegacyFixture, migrationStatus, overviewStats, planMigration, previewMigration, planEnvironmentCreate, planProjectCreate, restoreBackup, rollbackMigrationDurable, runDoctor, runMigrationDurable, runReadinessCheck, testScimConnection, testSsoConnection, updateRole, validateSamlProviderConfig, syncRuntimeOrganizationToManagementDurable, upgradeCheck, verifyBackup, verifyMigrationDurable, validateRole, parseConfigJson, publicConfig, setConfig, validateConfig, validateApiKeyName, diffConfig, generateRuntimeSchema, getRuntimeSchemaStatus, migrateRuntimeSchema, } from "@clearance/management";
+import { addMember, addMemberInAuth, executeMemberImportPlan, planMemberImport, archiveOrganization, archiveOrganizationInAuth, createBackup, createEnvironment, createProject, createOrganization, createOrgInAuth, createScimConnection, createSetupLink, createSsoConnection, createSsoConnectionReal, testSsoConnectionReal, testSsoConnectionLive, testScimConnectionLive, createScimConnectionReal, testScimConnectionReal, ensureAuthMigrated, createPostgresBackup, createRole, createApiKey, verifyPostgresBackup, restorePostgresBackup, upgradeCheckWithDb, createUser, createUserInAuth, createUserWithPasswordSetupInAuth, configureSsoConnection, closeAuthBundle, deleteUser, deleteUserInAuth, disableScimConnection, disableScimConnectionReal, disableSsoConnection, disableSsoConnectionReal, disableUser, disableUserInAuth, exportUsers, USERS_EXPORT_MAX_LIMIT, getLatestReadiness, initProject, inspectEnvironment, inspectApiKey, inspectScimConnection, inspectSsoConnection, inspectSession, inspectSessionInAuth, inspectOrganization, inspectUser, listEnvironments, listEventsPage, exportEvents, EVENTS_EXPORT_MAX_LIMIT, EVENTS_TAIL_MAX_LIMIT, beginEventsTail, pollEventsTail, inspectEvent, replayDiagnosticTrace, listMembers, listOrganizations, listOrganizationsPage, listProjects, listRoles, listApiKeys, normalizeAndValidateApiKeyScopes, listScimConnections, listSessionsPage, listSessionsPageInAuth, listSsoConnections, listUsers, listUsersPage, ClearanceError, promoteEnvironment, removeMember, removeMemberInAuth, resolveMembershipId, revokeSession, revokeSessionInAuth, revokeApiKey, rotateScimCredential, rotateSsoCredential, rotateApiKey, updateMember, updateMemberInAuth, updateOrganization, updateOrganizationInAuth, updateUser, updateUserInAuth, loadLegacyFixture, migrationStatus, overviewStats, planMigration, previewMigration, planEnvironmentCreate, planProjectCreate, restoreBackup, rollbackMigrationDurable, runDoctor, runMigrationDurable, runReadinessCheck, testScimConnection, testSsoConnection, updateRole, validateSamlProviderConfig, syncRuntimeOrganizationToManagementDurable, upgradeCheck, verifyBackup, verifyMigrationDurable, validateRole, parseConfigJson, publicConfig, setConfig, validateConfig, validateApiKeyName, diffConfig, generateRuntimeSchema, getRuntimeSchemaStatus, migrateRuntimeSchema, } from "@clearance/management";
 import { CliExitError, fail, printResult } from "./output.js";
 import { closeStores, flushStore, openStore } from "./store.js";
 import { applyUpgrade, planUpgrade, rollbackUpgrade, verifyUpgrade } from "./upgrade.js";
 import { deleteSavedCredential, environmentToken, fetchWhoami, normalizeApiUrl, normalizeProfile, readTokenFromStdin, validateAndSaveCredential, } from "./operator-auth.js";
 import { resolveApiSession } from "./api-client.js";
-import { commandPath, dispatchRemoteCommand, isHostLocalCommand, } from "./remote-dispatch.js";
+import { commandPath, dispatchRemoteCommand, } from "./remote-dispatch.js";
 const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 function globals(cmd) {
     const opts = cmd.optsWithGlobals();
@@ -19,7 +18,6 @@ function globals(cmd) {
         yes: Boolean(opts.yes),
         dryRun: Boolean(opts.dryRun),
         dataPath: opts.dataPath,
-        localDirect: Boolean(opts.localDirect) || process.env.CLEARANCE_LOCAL_DIRECT === "1",
         profile: opts.profile,
         apiUrl: opts.apiUrl,
     };
@@ -134,31 +132,20 @@ async function main() {
         .option("--dry-run", "Preview mutations", false)
         .option("--data-path <path>", "Path to Clearance data store")
         .option("--profile <name>", "Saved API profile")
-        .option("--api-url <url>", "Clearance management API origin override")
-        .option("--local-direct", "Explicitly operate the local JSON/Postgres store (development and host operations only)", false);
+        .option("--api-url <url>", "Clearance management API origin override");
     program.hook("preAction", async (_root, actionCommand) => {
         const g = globals(actionCommand);
         try {
             const path = commandPath(actionCommand);
             if (path === "login" || path === "logout" || path === "whoami")
                 return;
-            if (g.localDirect)
-                return;
-            if (isHostLocalCommand(path)) {
-                throw new ClearanceError({
-                    code: "CLI_LOCAL_DIRECT_REQUIRED",
-                    message: `${path} is an explicitly host-local workflow.`,
-                    stage: "cli.dispatch",
-                    remediation: "Rerun with --local-direct after confirming the selected host and database.",
-                });
-            }
             const session = await resolveApiSession({ profile: g.profile, apiUrl: g.apiUrl });
             if (!session) {
                 throw new ClearanceError({
                     code: "CLI_LOGIN_REQUIRED",
                     message: "An authenticated Clearance API profile is required.",
                     stage: "cli.dispatch",
-                    remediation: "Run clearance login --profile <name>, or choose --local-direct for local development.",
+                    remediation: "Run clearance login --profile <name> for the intended API origin.",
                 });
             }
             const result = await dispatchRemoteCommand(session, path, actionCommand.processedArgs, actionCommand.opts(), g);
@@ -436,7 +423,7 @@ async function main() {
         .command("create")
         .requiredOption("--email <email>")
         .requiredOption("--name <name>")
-        .option("--password <password>", "Initial password; generated and returned once when omitted")
+        .option("--password <password>", "Explicit initial password; omitted creates an expiring single-use setup token")
         .action(async (opts, cmd) => {
         const g = globals(cmd);
         try {
@@ -446,28 +433,38 @@ async function main() {
                 return;
             }
             await store.refresh();
-            const generatedPassword = opts.password
-                ? undefined
-                : `Tmp!${randomBytes(18).toString("base64url")}aA1`;
-            const password = opts.password ?? generatedPassword;
-            const user = process.env.DATABASE_URL
-                ? await createUserInAuth({
-                    email: opts.email,
-                    name: opts.name,
-                    password,
-                    managementStore: store,
-                })
-                : createUser(store, {
-                    email: opts.email,
-                    name: opts.name,
-                    source: "cli",
-                });
+            const provisioned = process.env.DATABASE_URL
+                ? typeof opts.password === "string" && opts.password.length > 0
+                    ? {
+                        user: await createUserInAuth({
+                            email: opts.email,
+                            name: opts.name,
+                            password: opts.password,
+                            managementStore: store,
+                        }),
+                        passwordSetup: undefined,
+                    }
+                    : await createUserWithPasswordSetupInAuth({
+                        email: opts.email,
+                        name: opts.name,
+                        managementStore: store,
+                    })
+                : { user: createUser(store, {
+                        email: opts.email,
+                        name: opts.name,
+                        source: "cli",
+                    }), passwordSetup: undefined };
             await flushStore(store);
             printResult(g, {
-                user,
-                ...(generatedPassword ? { temporaryPassword: generatedPassword } : {}),
+                user: provisioned.user,
+                ...(provisioned.passwordSetup
+                    ? {
+                        passwordSetupToken: provisioned.passwordSetup.token,
+                        passwordSetupExpiresAt: provisioned.passwordSetup.expiresAt,
+                    }
+                    : {}),
                 storeBackend: store.backend,
-            }, `Created ${user.email} (${user.id})`);
+            }, `Created ${provisioned.user.email} (${provisioned.user.id})`);
         }
         catch (e) {
             fail(e, g);
@@ -2465,12 +2462,13 @@ async function main() {
                 }, `operator ${whoami.projectId}/${whoami.environmentId} via ${via} (${session.apiUrl})`);
                 return;
             }
-            printResult(g, {
-                authenticated: false,
-                mode: "local-direct",
-                credentialSource: "none",
-                storeBackend: process.env.DATABASE_URL ? "postgres" : "json",
-            }, "Local direct mode; no remote operator credential is configured.");
+            throw new ClearanceError({
+                code: "CLI_LOGIN_REQUIRED",
+                message: "No authenticated Clearance API profile is configured.",
+                stage: "cli.auth",
+                status: 401,
+                remediation: "Run clearance login --profile <name> for the intended API origin.",
+            });
         }
         catch (e) {
             fail(e, g);

package/dist/ops/deploy/upgrades/README.md

@@ -6,10 +6,10 @@
 deploy/upgrades/steps/<targetVersion>/apply.sh
 ```
 
-The currently supported transition is `0.1.4` to `0.2.0`. Its shipped hook is
-`deploy/upgrades/steps/0.2.0/apply.sh`; it verifies the release marker is at
-`0.1.4`, advances it to `0.2.0`, and verifies the result. The Clearance CLI
-packages this hook under `dist/ops/deploy/upgrades/steps/0.2.0/apply.sh`.
+The currently supported transition is `0.1.4` to `0.2.1`. Its shipped hook is
+`deploy/upgrades/steps/0.2.1/apply.sh`; it verifies the release marker is at
+`0.1.4`, advances it to `0.2.1`, and verifies the result. The Clearance CLI
+packages this hook under `dist/ops/deploy/upgrades/steps/0.2.1/apply.sh`.
 
 ## Contract
 

package/dist/ops/deploy/upgrades/steps/0.2.0/apply.sh

@@ -47,13 +47,17 @@ CREATE TABLE IF NOT EXISTS clearance_schema_migrations (
 INSERT INTO clearance_schema_migrations(version, plan_id, plan_sha256, from_version)
 VALUES (:'from_version', 'application-baseline', :'plan_sha', NULL)
 ON CONFLICT (version) DO NOTHING;
-UPDATE clearance_management_snapshot
-SET data = jsonb_set(data, '{releaseVersion}', to_jsonb(:'to_version'::text), false),
-    revision = revision + 1,
-    updated_at = now()
-WHERE id = 1 AND data->>'releaseVersion' = :'from_version';
+WITH advanced AS (
+  UPDATE clearance_management_snapshot
+  SET data = jsonb_set(data, '{releaseVersion}', to_jsonb(:'to_version'::text), false),
+      revision = revision + 1,
+      updated_at = now()
+  WHERE id = 1 AND data->>'releaseVersion' = :'from_version'
+  RETURNING 1
+)
 INSERT INTO clearance_schema_migrations(version, plan_id, plan_sha256, from_version)
-VALUES (:'to_version', :'plan_id', :'plan_sha', :'from_version');
+SELECT :'to_version', :'plan_id', :'plan_sha', :'from_version'
+FROM advanced;
 COMMIT;
 SQL
 

package/dist/ops/deploy/upgrades/steps/0.2.1/apply.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Shipped 0.1.4 -> 0.2.1 database transition.
+set -Eeuo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../../.." && pwd)"
+# shellcheck source=scripts/lib/ops-common.sh
+source "$ROOT/scripts/lib/ops-common.sh"
+
+PLAN=""
+FROM=""
+TO=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --plan) PLAN="$2"; shift 2 ;;
+    --from) FROM="$2"; shift 2 ;;
+    --to) TO="$2"; shift 2 ;;
+    *) die "unknown upgrade hook argument: $1" ;;
+  esac
+done
+
+[[ -f "$PLAN" ]] || die "upgrade plan is missing"
+[[ "$FROM" == "0.1.4" && "$TO" == "0.2.1" ]] \
+  || die "this hook only supports 0.1.4 to 0.2.1"
+
+require_pg_client
+require_cmd node
+URL="$(resolve_database_url)"
+PLAN_ID="$(node -e 'const j=require(process.argv[1]); process.stdout.write(j.planId)' "$PLAN")"
+PLAN_SHA="$(sha256_file "$PLAN")"
+[[ "$PLAN_ID" =~ ^upg_[0-9TZ]+_[a-f0-9]+$ ]] || die "unsafe plan id"
+require_application_release "$URL" "$FROM"
+
+# This is the application-owned migration contract: the durable management
+# snapshot used by the running API advances atomically with an append-only
+# migration ledger. It cannot pass against the old test-only ops marker.
+psql_q "$URL" \
+  -v from_version="$FROM" -v to_version="$TO" \
+  -v plan_id="$PLAN_ID" -v plan_sha="$PLAN_SHA" <<'SQL' >/dev/null
+BEGIN;
+CREATE TABLE IF NOT EXISTS clearance_schema_migrations (
+  version text PRIMARY KEY,
+  applied_at timestamptz NOT NULL DEFAULT now(),
+  plan_id text NOT NULL,
+  plan_sha256 text NOT NULL,
+  from_version text
+);
+INSERT INTO clearance_schema_migrations(version, plan_id, plan_sha256, from_version)
+VALUES (:'from_version', 'application-baseline', :'plan_sha', NULL)
+ON CONFLICT (version) DO NOTHING;
+WITH advanced AS (
+  UPDATE clearance_management_snapshot
+  SET data = jsonb_set(data, '{releaseVersion}', to_jsonb(:'to_version'::text), false),
+      revision = revision + 1,
+      updated_at = now()
+  WHERE id = 1 AND data->>'releaseVersion' = :'from_version'
+  RETURNING 1
+)
+INSERT INTO clearance_schema_migrations(version, plan_id, plan_sha256, from_version)
+SELECT :'to_version', :'plan_id', :'plan_sha', :'from_version'
+FROM advanced;
+COMMIT;
+SQL
+
+require_application_release "$URL" "$TO"
+ledger_plan="$(psql_q "$URL" -At -c "SELECT plan_id FROM clearance_schema_migrations WHERE version = '${TO}'")"
+[[ "$ledger_plan" == "$PLAN_ID" ]] || die "migration ledger did not record plan $PLAN_ID"

package/dist/output.d.ts

@@ -5,7 +5,6 @@ export interface GlobalOpts {
     yes?: boolean;
     dryRun?: boolean;
     dataPath?: string;
-    localDirect?: boolean;
     profile?: string;
     apiUrl?: string;
 }

package/dist/remote-dispatch.d.ts

@@ -1,10 +1,8 @@
 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>;
+import { type GlobalOpts } from "./output.js";
 export declare const REMOTE_COMMANDS: Set<string>;
-export type CommandExecution = "authentication" | "remote-api" | "host-local" | "unavailable";
+export type CommandExecution = "authentication" | "remote-api" | "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

@@ -1,39 +1,16 @@
-import { ClearanceError } from "@clearance/management";
+import { ClearanceError, parseConfigJson, writeExportArtifact } 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"],
-]);
+import { CliExitError } from "./output.js";
 export const REMOTE_COMMANDS = new Set([
-    "init", "doctor", "overview",
+    "init", "doctor", "dev", "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",
+    "users list", "users inspect", "users create", "users update", "users disable", "users delete", "users export",
     "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",
+    "orgs members list", "orgs members add", "orgs members update", "orgs members remove", "orgs members import",
+    "events list", "events tail", "events inspect", "events export", "events replay",
     "keys list", "keys create", "keys rotate", "keys revoke",
     "sessions list", "sessions revoke",
     "roles list", "roles validate", "roles create", "roles update",
@@ -41,12 +18,13 @@ export const REMOTE_COMMANDS = new Set([
     "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",
+    "import legacy", "migration plan", "migration run", "migration verify", "migration rollback", "migration status",
+    "backup create", "backup verify", "backup restore", "upgrade check", "upgrade plan", "upgrade apply", "upgrade verify", "upgrade rollback",
+    "schema status", "schema generate", "schema migrate",
 ]);
 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";
@@ -65,6 +43,71 @@ function query(path, values) {
 function body(values) {
     return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
 }
+function localFile(path, code, label) {
+    try {
+        return readFileSync(resolve(String(path)), "utf8");
+    }
+    catch {
+        throw error(code, `${label} could not be read.`, "Provide a readable local file and retry.");
+    }
+}
+function configCandidate(path) {
+    let contents;
+    try {
+        contents = readFileSync(resolve(String(path)), "utf8");
+    }
+    catch {
+        throw new ClearanceError({
+            code: "CONFIG_FILE_UNREADABLE",
+            message: "Config file could not be read.",
+            stage: "config.parse",
+            remediation: "Provide a readable JSON config file.",
+        });
+    }
+    return parseConfigJson(contents);
+}
+function writeRemoteExport(envelope, options, collection) {
+    const format = options.format === "jsonl" ? "jsonl" : "json";
+    const values = Array.isArray(envelope[collection]) ? envelope[collection] : [];
+    const contents = format === "jsonl"
+        ? values.length === 0
+            ? ""
+            : `${values.map((value) => JSON.stringify(value)).join("\n")}\n`
+        : `${JSON.stringify(envelope, null, 2)}\n`;
+    const outputPath = writeExportArtifact(String(options.output), contents, Boolean(options.force), {
+        stage: `${collection}.export`,
+        existsCode: `${collection.toUpperCase()}_EXPORT_EXISTS`,
+        writeFailedCode: `${collection.toUpperCase()}_EXPORT_WRITE_FAILED`,
+    });
+    return { ...envelope, outputPath };
+}
+function emitTailEvent(json, event) {
+    process.stdout.write(json
+        ? `${JSON.stringify(event)}\n`
+        : `${event.createdAt} ${event.action} actor=${event.actor} outcome=${event.outcome} id=${event.id}\n`);
+}
+function integerOption(value, fallback, minimum, maximum, name, code = "CLI_OPTION_INVALID") {
+    const parsed = value === undefined ? fallback : Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) {
+        throw error(code, `${name} must be an integer from ${minimum} to ${maximum}.`, `Pass a valid --${name} value.`);
+    }
+    return parsed;
+}
+async function resolveRemoteMembershipId(session, organizationId, options) {
+    if (typeof options.member === "string" && options.member.trim())
+        return options.member;
+    if (typeof options.user !== "string" || !options.user.trim()) {
+        throw error("MEMBER_ID_REQUIRED", "Membership update or removal requires --member or --user.", "List organization members, then pass a membership id or principal id.");
+    }
+    const response = await requestManagementApi(session, {
+        path: `/v1/organizations/${encodeURIComponent(String(organizationId))}/members`,
+    });
+    const membership = (response.members ?? []).find((candidate) => candidate.principalId === options.user && candidate.status !== "removed");
+    if (!membership) {
+        throw error("MEMBER_NOT_FOUND", "Membership not found.", "List organization members and verify the principal id.");
+    }
+    return membership.id;
+}
 export function commandPath(command) {
     const names = [];
     let current = command;
@@ -74,12 +117,9 @@ export function commandPath(command) {
     }
     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.");
+        throw error("CLI_REMOTE_DRY_RUN_UNSUPPORTED", `${path} does not yet expose a server-side dry-run contract.`, "Use the command without --dry-run after reviewing the target.");
     }
 }
 function requireConfirmation(global, code, label) {
@@ -100,6 +140,7 @@ export async function dispatchRemoteCommand(session, path, args, opts, global) {
             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 "dev": return requestManagementApi(session, { path: "/v1/dev" });
         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" });
@@ -123,6 +164,14 @@ export async function dispatchRemoteCommand(session, path, args, opts, global) {
             requireConfirmation(global, "USER_DELETE_CONFIRM_REQUIRED", "User deletion");
             requireRemoteMutation(global, path);
             return requestManagementApi(session, { method: "DELETE", path: `/v1/users/${id}` });
+        case "users export": {
+            const envelope = await requestManagementApi(session, {
+                method: "POST",
+                path: "/v1/users/export",
+                body: body({ format: opts.format, limit: opts.limit, status: opts.status }),
+            });
+            return writeRemoteExport(envelope, opts, "users");
+        }
         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":
@@ -136,18 +185,74 @@ export async function dispatchRemoteCommand(session, path, args, opts, global) {
         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 } });
+            const membershipId = await resolveRemoteMembershipId(session, opts.org, opts);
+            return requestManagementApi(session, { method: "PATCH", path: `/v1/organizations/${encodeURIComponent(String(opts.org))}/members/${encodeURIComponent(membershipId)}`, 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 } });
+            const membershipId = await resolveRemoteMembershipId(session, opts.org, opts);
+            return requestManagementApi(session, { method: "DELETE", path: `/v1/organizations/${encodeURIComponent(String(opts.org))}/members/${encodeURIComponent(membershipId)}`, body: { dryRun: global.dryRun } });
+        }
+        case "orgs members import": {
+            requireConfirmation(global, "MEMBER_IMPORT_CONFIRMATION_REQUIRED", "Member import");
+            const filename = String(opts.file);
+            const format = opts.format ?? (filename.toLowerCase().endsWith(".json")
+                ? "json"
+                : filename.toLowerCase().endsWith(".csv")
+                    ? "csv"
+                    : undefined);
+            if (format !== "json" && format !== "csv") {
+                throw error("MEMBER_IMPORT_FORMAT_REQUIRED", "Member import format is required.", "Use a .json or .csv file, or pass --format json|csv.");
+            }
+            return requestManagementApi(session, {
+                method: "POST",
+                path: `/v1/organizations/${encodeURIComponent(String(opts.org))}/members/import`,
+                body: {
+                    content: localFile(opts.file, "MEMBER_IMPORT_FILE_UNREADABLE", "Member import file"),
+                    format,
+                    dryRun: global.dryRun || !global.yes,
+                    confirm: global.yes && !global.dryRun,
+                },
+            });
+        }
+        case "events list": return requestManagementApi(session, { path: query("/v1/events", { limit: opts.limit, cursor: opts.cursor, action: opts.action, organizationId: opts.org }) });
+        case "events tail": {
+            const limit = integerOption(opts.limit, 20, 1, 1000, "limit", "EVENTS_TAIL_OPTION_INVALID");
+            const pollInterval = integerOption(opts.pollInterval, 1000, 100, 60_000, "poll-interval", "EVENTS_TAIL_OPTION_INVALID");
+            const maxEvents = integerOption(opts.maxEvents, 0, 0, Number.MAX_SAFE_INTEGER, "max-events", "EVENTS_TAIL_OPTION_INVALID");
+            const tailPath = query("/v1/events", { limit, action: opts.action, organizationId: opts.org });
+            const seen = new Set();
+            let emitted = 0;
+            const poll = async () => {
+                const response = await requestManagementApi(session, { path: tailPath });
+                const fresh = (response.events ?? []).filter((event) => !seen.has(event.id)).reverse();
+                for (const event of fresh) {
+                    seen.add(event.id);
+                    if (maxEvents !== 0 && emitted >= maxEvents)
+                        break;
+                    emitTailEvent(Boolean(global.json), event);
+                    emitted += 1;
+                }
+                return response;
+            };
+            await poll();
+            if (opts.once || (maxEvents !== 0 && emitted >= maxEvents))
+                throw new CliExitError(0);
+            while (maxEvents === 0 || emitted < maxEvents) {
+                await new Promise((resolveDelay) => setTimeout(resolveDelay, pollInterval));
+                await poll();
+            }
+            throw new CliExitError(0);
         }
-        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 export": {
+            const envelope = await requestManagementApi(session, {
+                method: "POST",
+                path: "/v1/events/export",
+                body: body({ format: opts.format, limit: opts.limit, action: opts.action, organizationId: opts.org, before: opts.before }),
+            });
+            return writeRemoteExport(envelope, opts, "events");
+        }
         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":
@@ -160,11 +265,13 @@ export async function dispatchRemoteCommand(session, path, args, opts, global) {
             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` });
+            requireConfirmation(global, "SESSION_CONFIRM_REQUIRED", "Session revocation");
+            return requestManagementApi(session, { method: "POST", path: `/v1/sessions/${id}/revoke`, body: { dryRun: global.dryRun } });
         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 validate": {
+            const validation = await requestManagementApi(session, { method: "POST", path: "/v1/roles/validate", body: body({ name: opts.name, slug: opts.slug, permissions: opts.permission }) });
+            return { validation };
+        }
         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":
@@ -173,8 +280,7 @@ export async function dispatchRemoteCommand(session, path, args, opts, global) {
             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 }) });
+            return requestManagementApi(session, { method: "PATCH", path: `/v1/sso/${id}`, body: body({ issuer: opts.issuer, audience: opts.audience, domain: opts.domain, dryRun: global.dryRun }) });
         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.");
@@ -189,7 +295,7 @@ export async function dispatchRemoteCommand(session, path, args, opts, global) {
             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");
+            requireConfirmation(global, "SSO_CONFIRM_REQUIRED", "SSO disable");
             return requestManagementApi(session, { method: "POST", path: `/v1/sso/${id}/disable`, body: { dryRun: global.dryRun } });
         case "scim create":
             requireRemoteMutation(global, path);
@@ -216,17 +322,147 @@ export async function dispatchRemoteCommand(session, path, args, opts, global) {
             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 "import legacy":
+            requireConfirmation(global, "CLEARANCE_IMPORT_CONFIRMATION_REQUIRED", "Legacy import");
+            return requestManagementApi(session, {
+                method: "POST",
+                path: "/v1/import/legacy",
+                body: {
+                    fixture: localFile(opts.file, "CLEARANCE_IMPORT_FILE_UNREADABLE", "Legacy import file"),
+                    dryRun: global.dryRun || !global.yes,
+                    confirm: global.yes && !global.dryRun,
+                },
+            });
+        case "migration plan":
+            return requestManagementApi(session, {
+                method: "POST",
+                path: "/v1/migrations/plan",
+                body: {
+                    source: opts.source,
+                    fixture: localFile(opts.fixture, "CLEARANCE_IMPORT_FILE_UNREADABLE", "Migration fixture"),
+                },
+            });
+        case "migration run":
+            return requestManagementApi(session, {
+                method: "POST",
+                path: `/v1/migrations/${encodeURIComponent(String(opts.id))}/run`,
+                body: {
+                    fixture: localFile(opts.fixture, "CLEARANCE_IMPORT_FILE_UNREADABLE", "Migration fixture"),
+                    dryRun: global.dryRun,
+                },
+            });
+        case "migration verify":
+            return requestManagementApi(session, {
+                method: "POST",
+                path: `/v1/migrations/${encodeURIComponent(String(opts.id))}/verify`,
+                body: {
+                    fixture: localFile(opts.fixture, "CLEARANCE_IMPORT_FILE_UNREADABLE", "Migration fixture"),
+                },
+            });
+        case "migration rollback":
+            requireConfirmation(global, "MIGRATION_ROLLBACK_CONFIRM_REQUIRED", "Migration rollback");
+            return requestManagementApi(session, {
+                method: "POST",
+                path: `/v1/migrations/${encodeURIComponent(String(opts.id))}/rollback`,
+                body: {
+                    fixture: localFile(opts.fixture, "CLEARANCE_IMPORT_FILE_UNREADABLE", "Migration fixture"),
+                    confirm: global.yes && !global.dryRun,
+                },
+            });
+        case "migration status":
+            return requestManagementApi(session, { path: `/v1/migrations/${encodeURIComponent(String(opts.id))}` });
+        case "backup create":
+            if (opts.dir !== undefined) {
+                throw error("BACKUP_DIRECTORY_SERVER_MANAGED", "Backup storage is configured by the API deployment.", "Set CLEARANCE_BACKUP_DIR on the API and mount durable storage there.");
+            }
+            return requestManagementApi(session, { method: "POST", path: "/v1/backups", body: {} });
+        case "backup verify":
+            return requestManagementApi(session, { method: "POST", path: `/v1/backups/${encodeURIComponent(String(opts.id))}/verify`, body: {} });
+        case "backup restore":
+            requireConfirmation(global, "BACKUP_RESTORE_CONFIRM_REQUIRED", "Backup restore");
+            return requestManagementApi(session, {
+                method: "POST",
+                path: `/v1/backups/${encodeURIComponent(String(opts.id))}/restore`,
+                body: { target: opts.target, confirm: global.yes && !global.dryRun },
+            });
+        case "upgrade check":
+            return requestManagementApi(session, { path: "/v1/upgrades/check" });
+        case "upgrade plan":
+            return requestManagementApi(session, {
+                method: "POST",
+                path: "/v1/upgrades/plan",
+                body: body({ target: opts.target, dir: opts.dir, current: opts.current, dryRun: global.dryRun }),
+            });
+        case "upgrade apply":
+            requireConfirmation(global, "UPGRADE_APPLY_CONFIRMATION_REQUIRED", "Upgrade apply");
+            return requestManagementApi(session, {
+                method: "POST",
+                path: "/v1/upgrades/apply",
+                body: { plan: opts.plan, dir: opts.dir, dryRun: global.dryRun, confirm: global.yes && !global.dryRun },
+            });
+        case "upgrade verify":
+            return requestManagementApi(session, {
+                method: "POST",
+                path: "/v1/upgrades/verify",
+                body: body({ plan: opts.plan, dir: opts.dir, healthUrl: opts.healthUrl, dryRun: global.dryRun }),
+            });
+        case "upgrade rollback":
+            requireConfirmation(global, "UPGRADE_ROLLBACK_CONFIRMATION_REQUIRED", "Upgrade rollback");
+            return requestManagementApi(session, {
+                method: "POST",
+                path: "/v1/upgrades/rollback",
+                body: body({
+                    plan: opts.plan,
+                    dir: opts.dir,
+                    dryRun: global.dryRun,
+                    confirm: global.yes && !global.dryRun,
+                    restoreActive: opts.restoreActive,
+                    activeDatabaseConfirmation: opts.confirm,
+                    backupDir: opts.backupDir,
+                }),
+            });
+        case "schema status":
+            return requestManagementApi(session, { path: "/v1/schema/status" });
+        case "schema generate": {
+            if (!opts.output) {
+                throw error("SCHEMA_GENERATE_OUTPUT_REQUIRED", "schema generate requires an explicit --output path.", "Provide --output <path> for the generated SQL artifact.");
+            }
+            const result = await requestManagementApi(session, {
+                method: "POST",
+                path: "/v1/schema/generate",
+                body: {},
+            });
+            const { sql, ...metadata } = result;
+            if (typeof sql !== "string") {
+                throw error("SCHEMA_GENERATE_RESPONSE_INVALID", "The API did not return generated SQL.", "Upgrade the Clearance API and retry.");
+            }
+            if (global.dryRun)
+                return { ...metadata, dryRun: true };
+            const outputPath = writeExportArtifact(String(opts.output), sql, Boolean(opts.force), {
+                stage: "schema.generate",
+                existsCode: "SCHEMA_GENERATE_EXISTS",
+                writeFailedCode: "SCHEMA_GENERATE_WRITE_FAILED",
+            });
+            return { ...metadata, dryRun: false, outputPath };
+        }
+        case "schema migrate":
+            requireConfirmation(global, "SCHEMA_MIGRATE_CONFIRMATION_REQUIRED", "Schema migration");
+            return requestManagementApi(session, {
+                method: "POST",
+                path: "/v1/schema/migrate",
+                body: { dryRun: global.dryRun, confirm: global.yes && !global.dryRun },
+            });
         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;
+            const config = opts.file ? configCandidate(opts.file) : 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"));
+            const config = configCandidate(opts.file);
             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.");
+            throw error("CLI_REMOTE_COMMAND_UNAVAILABLE", `${path} has no versioned management API contract in this release.`, "Upgrade the Clearance API to a version that exposes this workflow.");
     }
 }

package/dist/upgrade.d.ts

@@ -1,114 +1 @@
-export interface UpgradeOptions {
-    target?: string;
-    plan?: string;
-    dir?: string;
-    healthUrl?: string;
-    current?: string;
-    dryRun?: boolean;
-    yes?: boolean;
-    restoreActive?: boolean;
-    confirm?: string;
-    backupDir?: string;
-}
-export declare function planUpgrade(opts: UpgradeOptions): Promise<{
-    schemaVersion: string;
-    operation: string;
-    dryRun: boolean;
-    plan: {
-        id: string;
-        path: string;
-        currentVersion: string;
-        targetVersion: string;
-        status: string;
-    };
-} | {
-    schemaVersion: string;
-    operation: string;
-    dryRun: boolean;
-    plan: {
-        targetVersion: string;
-        currentVersion: string | null;
-        directory: string;
-        createsArtifacts: boolean;
-    };
-}>;
-export declare function applyUpgrade(opts: UpgradeOptions): Promise<{
-    operation: string;
-    wouldRun: string[];
-    schemaVersion: string;
-    dryRun: boolean;
-    plan: {
-        id: string;
-        path: string;
-        currentVersion: string;
-        targetVersion: string;
-        status: string;
-    };
-} | {
-    schemaVersion: string;
-    operation: string;
-    dryRun: boolean;
-    plan: {
-        id: string;
-        targetVersion: string;
-        status: string;
-        backupId: string | null;
-        rollbackReference: {} | null;
-    };
-}>;
-export declare function verifyUpgrade(opts: UpgradeOptions): Promise<{
-    schemaVersion: string;
-    operation: string;
-    dryRun: boolean;
-    plan: {
-        id: string;
-        targetVersion: string;
-        status: string;
-        updatedAt?: undefined;
-        backupId?: undefined;
-    };
-    wouldRun: string[];
-} | {
-    schemaVersion: string;
-    operation: string;
-    plan: {
-        id: string;
-        targetVersion: string;
-        status: string;
-        updatedAt: string | null;
-        backupId: string | null;
-    };
-    dryRun?: undefined;
-    wouldRun?: undefined;
-}>;
-export declare function rollbackUpgrade(opts: UpgradeOptions): Promise<{
-    schemaVersion: string;
-    operation: string;
-    dryRun: boolean;
-    mode: string;
-    activeDatabaseUntouched: boolean;
-    wouldModifyActiveDatabase: boolean;
-    plan: {
-        id: string;
-        targetVersion: string;
-        status: string;
-    };
-    wouldRun: string[];
-    rollbackReceipt?: undefined;
-    receipt?: undefined;
-} | {
-    schemaVersion: string;
-    operation: string;
-    dryRun: boolean;
-    mode: string;
-    activeDatabaseUntouched: boolean;
-    plan: {
-        id: string;
-        targetVersion: string;
-        status: string;
-    };
-    rollbackReceipt: string;
-    receipt: Record<string, unknown>;
-    wouldModifyActiveDatabase?: undefined;
-    wouldRun?: undefined;
-}>;
+export { applyUpgrade, planUpgrade, rollbackUpgrade, verifyUpgrade, type UpgradeOptions, } from "@clearance/management";

package/dist/upgrade.js

@@ -1,262 +1 @@
-import { execFile } from "node:child_process";
-import { createHash } from "node:crypto";
-import { constants, existsSync, promises as fs } from "node:fs";
-import { dirname, isAbsolute, relative, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { promisify } from "node:util";
-import { ClearanceError } from "@clearance/management";
-const execFileAsync = promisify(execFile);
-const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
-const SOURCE_ROOT = resolve(MODULE_DIR, "../../..");
-const PACKAGED_ROOT = resolve(MODULE_DIR, "ops");
-const OPS_ROOT = existsSync(resolve(PACKAGED_ROOT, "scripts/upgrade-plan.sh"))
-    ? PACKAGED_ROOT
-    : SOURCE_ROOT;
-const SCRIPTS = {
-    plan: resolve(OPS_ROOT, "scripts/upgrade-plan.sh"),
-    apply: resolve(OPS_ROOT, "scripts/upgrade-apply.sh"),
-    verify: resolve(OPS_ROOT, "scripts/upgrade-verify.sh"),
-    rollback: resolve(OPS_ROOT, "scripts/upgrade-rollback.sh"),
-};
-const PLAN_ID = /^upg_[A-Za-z0-9_-]+$/;
-const VERSION = /^[0-9A-Za-z][0-9A-Za-z._+-]{0,127}$/;
-const SHA256 = /^[a-f0-9]{64}$/;
-const MAX_ARTIFACT_BYTES = 1024 * 1024;
-const SCRIPT_TIMEOUT_MS = 30 * 60_000;
-function upgradeError(code, message, stage, remediation) {
-    return new ClearanceError({ code, message, stage, remediation, status: 400 });
-}
-function safeDirectory(input, stage) {
-    if (!input || input.includes("\0") || !isAbsolute(input)) {
-        throw upgradeError("UPGRADE_DIR_INVALID", "Upgrade directory must be an absolute path.", stage, "Pass --dir with an absolute, dedicated upgrade artifact directory.");
-    }
-    return resolve(input);
-}
-function safeVersion(value, option, stage) {
-    if (!value || !VERSION.test(value)) {
-        throw upgradeError("UPGRADE_VERSION_INVALID", `--${option} must be a simple release version.`, stage, "Use letters, numbers, dots, underscores, plus, or hyphens only.");
-    }
-    return value;
-}
-function safeHealthUrl(value) {
-    if (!value)
-        return undefined;
-    try {
-        const url = new URL(value);
-        if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username || url.password || url.hash || url.search)
-            throw new Error();
-        return url.toString();
-    }
-    catch {
-        throw upgradeError("UPGRADE_HEALTH_URL_INVALID", "--health-url must be a credential-free HTTP(S) URL.", "upgrade.verify", "Pass an absolute http:// or https:// health endpoint without credentials, query parameters, or a fragment.");
-    }
-}
-function isInside(parent, child) {
-    const path = relative(parent, child);
-    return path === "" || (!path.startsWith("..") && !isAbsolute(path));
-}
-function planPaths(planRef, dir, stage) {
-    if (!planRef || planRef.includes("\0")) {
-        throw upgradeError("UPGRADE_PLAN_INVALID", "--plan is required.", stage, "Pass a plan ID returned by upgrade plan.");
-    }
-    const planPath = isAbsolute(planRef)
-        ? resolve(planRef)
-        : PLAN_ID.test(planRef)
-            ? resolve(dir, `${planRef}.plan.json`)
-            : "";
-    if (!planPath || !isInside(dir, planPath) || !planPath.endsWith(".plan.json")) {
-        throw upgradeError("UPGRADE_PLAN_INVALID", "--plan must be a plan ID or a plan file inside --dir.", stage, "Use a plan ID returned by upgrade plan and the matching --dir.");
-    }
-    const id = planPath.slice(planPath.lastIndexOf("/") + 1, -".plan.json".length);
-    if (!PLAN_ID.test(id)) {
-        throw upgradeError("UPGRADE_PLAN_INVALID", "Plan filename is invalid.", stage, "Use an unmodified plan generated by clearance upgrade plan.");
-    }
-    return { planPath, statePath: resolve(dir, `${id}.state.json`) };
-}
-async function readArtifact(path, code, stage) {
-    let handle;
-    try {
-        handle = await fs.open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
-        const stat = await handle.stat();
-        if (!stat.isFile() || stat.size < 2 || stat.size > MAX_ARTIFACT_BYTES)
-            throw new Error();
-        const bytes = await handle.readFile();
-        return { parsed: JSON.parse(bytes.toString("utf8")), bytes };
-    }
-    catch {
-        throw upgradeError(code, "Upgrade artifact is missing or invalid JSON.", stage, "Create a new plan with clearance upgrade plan; do not edit upgrade artifacts.");
-    }
-    finally {
-        await handle?.close().catch(() => undefined);
-    }
-}
-async function listDirectory(path, stage, allowMissing = false) {
-    try {
-        return await fs.readdir(path);
-    }
-    catch (error) {
-        if (allowMissing && error.code === "ENOENT")
-            return [];
-        throw upgradeError("UPGRADE_DIR_UNREADABLE", "Upgrade artifact directory cannot be read.", stage, "Use a readable, dedicated upgrade artifact directory.");
-    }
-}
-async function assertArtifactDirectory(path, stage, allowMissing = false) {
-    try {
-        const stat = await fs.lstat(path);
-        if (stat.isSymbolicLink() || !stat.isDirectory())
-            throw new Error();
-    }
-    catch (error) {
-        if (allowMissing && error.code === "ENOENT")
-            return;
-        throw upgradeError("UPGRADE_DIR_UNSAFE", "Upgrade artifact directory must be a real directory, not a file or symlink.", stage, "Use a dedicated local directory owned by the current operator.");
-    }
-}
-async function readArtifacts(planRef, dir, stage) {
-    await assertArtifactDirectory(dir, stage);
-    const { planPath, statePath } = planPaths(planRef, dir, stage);
-    const planArtifact = await readArtifact(planPath, "UPGRADE_PLAN_INVALID", stage);
-    const stateArtifact = await readArtifact(statePath, "UPGRADE_STATE_INVALID", stage);
-    const plan = planArtifact.parsed;
-    const state = stateArtifact.parsed;
-    const planId = planPath.slice(planPath.lastIndexOf("/") + 1, -".plan.json".length);
-    if (plan.immutable !== true || plan.planId !== planId || state.planId !== planId || typeof plan.currentVersion !== "string" || typeof plan.targetVersion !== "string" || typeof state.status !== "string" || typeof state.planSha256 !== "string" || !SHA256.test(state.planSha256)) {
-        throw upgradeError("UPGRADE_PLAN_INVALID", "Upgrade plan and state artifacts are inconsistent.", stage, "Create a new plan with clearance upgrade plan; do not edit upgrade artifacts.");
-    }
-    safeVersion(plan.currentVersion, "current", stage);
-    safeVersion(plan.targetVersion, "target", stage);
-    if (plan.currentVersion === plan.targetVersion) {
-        throw upgradeError("UPGRADE_PLAN_INVALID", "Upgrade plan current and target versions must differ.", stage, "Create a new plan for a different target release.");
-    }
-    const checksum = createHash("sha256").update(planArtifact.bytes).digest("hex");
-    if (checksum !== state.planSha256) {
-        throw upgradeError("UPGRADE_PLAN_TAMPERED", "Upgrade plan checksum does not match its state artifact.", stage, "Create a new plan with clearance upgrade plan; do not edit upgrade artifacts.");
-    }
-    return { planPath, statePath, plan, state };
-}
-async function runScript(operation, args, stage) {
-    try {
-        await execFileAsync("bash", [SCRIPTS[operation], ...args], {
-            cwd: OPS_ROOT,
-            env: process.env,
-            maxBuffer: 1024 * 1024,
-            timeout: SCRIPT_TIMEOUT_MS,
-        });
-    }
-    catch {
-        throw upgradeError("UPGRADE_SCRIPT_FAILED", `Upgrade ${operation} failed.`, stage, "Inspect the upgrade plan/state artifacts and protected operational logs, correct the issue, then create a new plan if required.");
-    }
-}
-function planResult(plan, state, planPath, dryRun = false) {
-    return {
-        schemaVersion: "v1",
-        operation: "upgrade.plan",
-        dryRun,
-        plan: {
-            id: plan.planId,
-            path: planPath,
-            currentVersion: plan.currentVersion,
-            targetVersion: plan.targetVersion,
-            status: state.status,
-        },
-    };
-}
-export async function planUpgrade(opts) {
-    const target = safeVersion(opts.target, "target", "upgrade.plan");
-    const dir = safeDirectory(opts.dir, "upgrade.plan");
-    const current = opts.current ? safeVersion(opts.current, "current", "upgrade.plan") : undefined;
-    if (opts.dryRun) {
-        return { schemaVersion: "v1", operation: "upgrade.plan", dryRun: true, plan: { targetVersion: target, currentVersion: current ?? null, directory: dir, createsArtifacts: false } };
-    }
-    const args = ["--target", target, "--dir", dir];
-    if (current)
-        args.push("--current", current);
-    await assertArtifactDirectory(dir, "upgrade.plan", true);
-    const existingPlans = new Set(await listDirectory(dir, "upgrade.plan", true));
-    await runScript("plan", args, "upgrade.plan");
-    await assertArtifactDirectory(dir, "upgrade.plan");
-    const entries = await listDirectory(dir, "upgrade.plan");
-    const createdPlans = entries.filter((entry) => entry.endsWith(".plan.json") && !existingPlans.has(entry));
-    if (createdPlans.length !== 1)
-        throw upgradeError("UPGRADE_ARTIFACT_AMBIGUOUS", "Plan script did not create exactly one identifiable plan artifact.", "upgrade.plan", "Retry in an empty, dedicated upgrade artifact directory with no concurrent upgrade planning process.");
-    const artifacts = await readArtifacts(resolve(dir, createdPlans[0]), dir, "upgrade.plan");
-    return planResult(artifacts.plan, artifacts.state, artifacts.planPath);
-}
-export async function applyUpgrade(opts) {
-    const dir = safeDirectory(opts.dir, "upgrade.apply");
-    const artifacts = await readArtifacts(opts.plan ?? "", dir, "upgrade.apply");
-    if (opts.dryRun)
-        return { ...planResult(artifacts.plan, artifacts.state, artifacts.planPath, true), operation: "upgrade.apply", wouldRun: ["preflight", "verified_backup", "version_hook"] };
-    if (!opts.yes)
-        throw upgradeError("UPGRADE_APPLY_CONFIRMATION_REQUIRED", "upgrade apply requires --yes.", "upgrade.apply", "Review the plan or run upgrade apply with --dry-run, then rerun with --yes to apply.");
-    await runScript("apply", ["--plan", artifacts.planPath, "--dir", dir], "upgrade.apply");
-    const result = await readArtifacts(artifacts.planPath, dir, "upgrade.apply");
-    return { schemaVersion: "v1", operation: "upgrade.apply", dryRun: false, plan: { id: result.plan.planId, targetVersion: result.plan.targetVersion, status: result.state.status, backupId: result.state.backupId ?? null, rollbackReference: result.state.rollbackReference ?? null } };
-}
-export async function verifyUpgrade(opts) {
-    const dir = safeDirectory(opts.dir, "upgrade.verify");
-    const healthUrl = safeHealthUrl(opts.healthUrl);
-    const artifacts = await readArtifacts(opts.plan ?? "", dir, "upgrade.verify");
-    if (opts.dryRun) {
-        return {
-            schemaVersion: "v1",
-            operation: "upgrade.verify",
-            dryRun: true,
-            plan: { id: artifacts.plan.planId, targetVersion: artifacts.plan.targetVersion, status: artifacts.state.status },
-            wouldRun: ["backup_reference_check", "apply_marker_check", ...(healthUrl ? ["health_url_check"] : [])],
-        };
-    }
-    await runScript("verify", ["--plan", artifacts.planPath, "--dir", dir, ...(healthUrl ? ["--health-url", healthUrl] : [])], "upgrade.verify");
-    const result = await readArtifacts(artifacts.planPath, dir, "upgrade.verify");
-    return { schemaVersion: "v1", operation: "upgrade.verify", plan: { id: result.plan.planId, targetVersion: result.plan.targetVersion, status: result.state.status, updatedAt: result.state.updatedAt ?? null, backupId: result.state.backupId ?? null } };
-}
-export async function rollbackUpgrade(opts) {
-    const dir = safeDirectory(opts.dir, "upgrade.rollback");
-    const artifacts = await readArtifacts(opts.plan ?? "", dir, "upgrade.rollback");
-    const mode = opts.restoreActive ? "active_database_restore" : "isolated_verify_only";
-    if (opts.dryRun) {
-        return {
-            schemaVersion: "v1",
-            operation: "upgrade.rollback",
-            dryRun: true,
-            mode,
-            activeDatabaseUntouched: true,
-            wouldModifyActiveDatabase: Boolean(opts.restoreActive),
-            plan: { id: artifacts.plan.planId, targetVersion: artifacts.plan.targetVersion, status: artifacts.state.status },
-            wouldRun: opts.restoreActive
-                ? ["advisory_lock", "safety_backup", "staging_restore", "database_swap", "live_verification", "rollback_receipt"]
-                : ["backup_checksum_check", "isolated_restore", "reconciliation", "rollback_receipt"],
-        };
-    }
-    if (!opts.yes) {
-        throw upgradeError("UPGRADE_ROLLBACK_CONFIRMATION_REQUIRED", "upgrade rollback requires --yes.", "upgrade.rollback", "Review with upgrade rollback --dry-run, then rerun with --yes to verify the rollback reference.");
-    }
-    const scriptArgs = ["--plan", artifacts.planPath, "--dir", dir];
-    if (opts.restoreActive) {
-        if (!opts.confirm || !new RegExp(`^RESTORE_ACTIVE:${artifacts.plan.planId}:[A-Za-z_][A-Za-z0-9_]{0,62}$`).test(opts.confirm)) {
-            throw upgradeError("UPGRADE_ACTIVE_ROLLBACK_CONFIRMATION_REQUIRED", "Active rollback requires the exact plan and database confirmation token.", "upgrade.rollback", `Pass --restore-active --confirm RESTORE_ACTIVE:${artifacts.plan.planId}:<database> with --yes.`);
-        }
-        scriptArgs.push("--restore-active", "--confirm", opts.confirm);
-        if (opts.backupDir)
-            scriptArgs.push("--backup-dir", safeDirectory(opts.backupDir, "upgrade.rollback"));
-    }
-    await runScript("rollback", scriptArgs, "upgrade.rollback");
-    const result = await readArtifacts(artifacts.planPath, dir, "upgrade.rollback");
-    const receiptPath = opts.restoreActive
-        ? result.state.rollbackReceipt
-        : resolve(dir, "rollbacks", `${result.plan.planId}.rollback-drill.json`);
-    if (typeof receiptPath !== "string" || !isInside(dir, resolve(receiptPath))) {
-        throw upgradeError("UPGRADE_ROLLBACK_RECEIPT_INVALID", "Rollback receipt is missing or escaped the upgrade directory.", "upgrade.rollback", "Inspect protected rollback logs and preserve the upgrade artifact directory for recovery.");
-    }
-    const receipt = await readArtifact(resolve(receiptPath), "UPGRADE_ROLLBACK_RECEIPT_INVALID", "upgrade.rollback");
-    return {
-        schemaVersion: "v1",
-        operation: "upgrade.rollback",
-        dryRun: false,
-        mode,
-        activeDatabaseUntouched: !opts.restoreActive,
-        plan: { id: result.plan.planId, targetVersion: result.plan.targetVersion, status: result.state.status },
-        rollbackReceipt: resolve(receiptPath),
-        receipt: receipt.parsed,
-    };
-}
+export { applyUpgrade, planUpgrade, rollbackUpgrade, verifyUpgrade, } from "@clearance/management";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clearance/cli",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "Clearance CLI — operate auth projects, enterprise connections, migrations, and deploys",
   "type": "module",
   "license": "MIT",
@@ -20,14 +20,14 @@
     "dist"
   ],
   "dependencies": {
-    "commander": "^13.1.0",
-    "@clearance/management": "0.1.4"
+    "commander": "^14.0.3",
+    "@clearance/management": "0.2.1"
   },
   "devDependencies": {
-    "@types/node": "^22.13.10",
-    "tsx": "^4.19.3",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.5"
+    "@types/node": "^22.20.1",
+    "tsx": "^4.23.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && node scripts/stage-ops.mjs && chmod +x dist/index.js",