@clearance/cli 0.1.4

package/dist/store.d.ts

@@ -0,0 +1,9 @@
+import { type ManagementStore } from "@clearance/management";
+import type { GlobalOpts } from "./output.js";
+/**
+ * Open the shared management store used by CLI (same services as API).
+ * DATABASE_URL → Postgres SoT; otherwise local JSON for one-command local dev.
+ */
+export declare function openStore(opts: GlobalOpts): Promise<ManagementStore>;
+export declare function flushStore(store: ManagementStore): Promise<void>;
+export declare function closeStores(): Promise<void>;

package/dist/store.js

@@ -0,0 +1,43 @@
+import { createManagementStore, } from "@clearance/management";
+const openStores = new Set();
+let hooksInstalled = false;
+function installFlushHooks() {
+    if (hooksInstalled)
+        return;
+    hooksInstalled = true;
+    const flushAll = () => {
+        for (const s of openStores) {
+            // fire-and-forget best effort on sync exit paths
+            void s.ready();
+        }
+    };
+    process.once("beforeExit", () => {
+        void Promise.all([...openStores].map((s) => s.ready()));
+    });
+    process.once("exit", flushAll);
+}
+/**
+ * Open the shared management store used by CLI (same services as API).
+ * DATABASE_URL → Postgres SoT; otherwise local JSON for one-command local dev.
+ */
+export async function openStore(opts) {
+    installFlushHooks();
+    const store = await createManagementStore({
+        dataPath: opts.dataPath,
+        databaseUrl: process.env.DATABASE_URL || undefined,
+    });
+    openStores.add(store);
+    return store;
+}
+export async function flushStore(store) {
+    await store.ready();
+}
+export async function closeStores() {
+    for (const store of openStores) {
+        await store.ready();
+        if ("destroy" in store && typeof store.destroy === "function") {
+            await store.destroy();
+        }
+    }
+    openStores.clear();
+}

package/dist/upgrade.d.ts

@@ -0,0 +1,114 @@
+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;
+}>;

package/dist/upgrade.js

@@ -0,0 +1,262 @@
+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,
+    };
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@clearance/cli",
+  "version": "0.1.4",
+  "description": "Clearance CLI — operate auth projects, enterprise connections, migrations, and deploys",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/clearance-auth/clearance",
+    "directory": "packages/clearance-cli"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "clearance": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "commander": "^13.1.0",
+    "@clearance/management": "0.1.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/stage-ops.mjs && chmod +x dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run --maxWorkers=1",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}