open-managed-agents 0.1.0

package/dist/scripts/oma-doctor.js

@@ -0,0 +1,230 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, readFileSync, statSync } from "node:fs";
+import { createServer } from "node:net";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseModelDeploymentConfigFromEnv, validateModelDeploymentConfigAgainstCatalog, } from "../src/control-plane/models/deployment-config.js";
+import { createReadOnlyPiModelCatalog } from "../src/control-plane/models/catalog.js";
+import { DEFAULT_OMA_SANDBOX_IMAGE } from "../src/control-plane/sessions/pi/sandbox/image.js";
+import { DEFAULT_OMA_EGRESS_SIDECAR_IMAGE, resolveOmaUpEgressEnvironment, } from "../src/control-plane/egress/image.js";
+export async function inspectOma(options, runtime = { env: process.env }) {
+    const checks = [];
+    const env = runtime.env;
+    const command = runtime.command ?? spawnSync;
+    const nodeVersion = runtime.nodeVersion ?? process.versions.node;
+    const [major = 0, minor = 0] = nodeVersion.split(".").map(Number);
+    checks.push(check("node.version", major > 22 || (major === 22 && minor >= 19) ? "pass" : "fail", major > 22 || (major === 22 && minor >= 19)
+        ? `Node ${nodeVersion} satisfies >=22.19.0.`
+        : `Node ${nodeVersion} is too old; install Node >=22.19.0.`));
+    const home = env.OMA_HOME?.trim() || join(homedir(), ".oma");
+    const homePathCheck = inspectPath("paths.oma_home", home, "directory", 0o700);
+    checks.push(homePathCheck);
+    let deployment;
+    try {
+        if (homePathCheck.status === "fail") {
+            throw new Error("OMA_HOME is not safe to inspect");
+        }
+        deployment = parseModelDeploymentConfigFromEnv(env, { home });
+        const authPathCheck = inspectPath("paths.pi_auth", deployment.authPath, "file", 0o600);
+        const modelsPathCheck = inspectPath("paths.pi_models", deployment.modelsPath, "file", 0o600);
+        checks.push(authPathCheck, modelsPathCheck);
+        if (authPathCheck.status === "fail" || modelsPathCheck.status === "fail") {
+            throw new Error("Pi configuration paths are not safe to read");
+        }
+        const authData = readAuthSnapshot(deployment.authPath);
+        const catalog = createReadOnlyPiModelCatalog({
+            allowedProviders: deployment.allowedProviders,
+            defaultModel: deployment.defaultModel,
+            authPath: deployment.authPath,
+            modelsPath: deployment.modelsPath,
+            allowModelAuthCommands: deployment.allowModelAuthCommands,
+        }, authData);
+        validateModelDeploymentConfigAgainstCatalog(deployment, {
+            hasProvider: (provider) => catalog.allowedProviders.has(provider),
+            hasModel: (model) => catalog.resolve(model) !== undefined,
+        });
+        checks.push(check("models.catalog", "pass", `${catalog.list().length} registered model(s) across ${catalog.allowedProviders.size} enabled provider(s); default ${catalog.defaultModel.provider}/${catalog.defaultModel.id}.`));
+        const defaultModel = catalog.resolve(catalog.defaultModel);
+        const configured = defaultModel !== undefined && catalog.hasConfiguredAuth(defaultModel);
+        checks.push(check("models.credentials", configured ? "pass" : "warn", configured
+            ? `Credentials are configured for default model ${catalog.defaultModel.provider}/${catalog.defaultModel.id}.`
+            : `Credentials are not configured for default model ${catalog.defaultModel.provider}/${catalog.defaultModel.id}; the local-compatible smoke still works, or run oma auth set ${catalog.defaultModel.provider} before a credentialed session.`));
+        checks.push(check("models.config", catalog.securityReport.warnings.length === 0 ? "pass" : "warn", catalog.securityReport.warnings.length === 0
+            ? "Model configuration passed read-only validation."
+            : `Model configuration is valid with ${catalog.securityReport.warnings.length} warning(s); run oma models validate for details.`));
+    }
+    catch (error) {
+        checks.push(check("models.catalog", "fail", safeError("Model configuration is invalid", error)));
+    }
+    if (options.sandbox === "docker-local") {
+        const info = command("docker", ["info"], { encoding: "utf8" });
+        checks.push(check("sandbox.runtime", info.status === 0 ? "pass" : "fail", info.status === 0 ? "Docker daemon is reachable." : "Docker daemon is unavailable; start Docker and retry."));
+        const image = command("docker", ["image", "inspect", DEFAULT_OMA_SANDBOX_IMAGE], { encoding: "utf8" });
+        checks.push(check("sandbox.image", image.status === 0 ? "pass" : "warn", image.status === 0
+            ? "The pinned OMA sandbox image is already present locally."
+            : "The pinned OMA sandbox image is not present locally; oma doctor did not download it."));
+        try {
+            const effective = resolveOmaUpEgressEnvironment(env, "docker-local");
+            if (effective.OMA_ENABLE_EGRESS === "false") {
+                checks.push(check("egress.sidecar", "warn", "Approved HTTPS egress is explicitly disabled; only offline environments can run."));
+            }
+            else {
+                const sidecarImage = effective.OMA_EGRESS_SIDECAR_IMAGE ?? DEFAULT_OMA_EGRESS_SIDECAR_IMAGE;
+                const sidecar = command("docker", ["image", "inspect", sidecarImage], { encoding: "utf8" });
+                checks.push(check("egress.sidecar", sidecar.status === 0 ? "pass" : "warn", sidecar.status === 0
+                    ? "The effective digest-pinned OMA egress sidecar is present locally."
+                    : "The effective digest-pinned OMA egress sidecar is not present locally; oma doctor did not download it."));
+            }
+        }
+        catch (error) {
+            checks.push(check("egress.sidecar", "fail", safeError("Egress configuration is invalid", error)));
+        }
+    }
+    else {
+        const executable = env.OMA_MICROSANDBOX_COMMAND?.trim() || "msb";
+        const version = command(executable, ["--version"], { encoding: "utf8" });
+        checks.push(check("sandbox.runtime", version.status === 0 ? "pass" : "fail", version.status === 0 ? "Microsandbox CLI is reachable." : `Microsandbox CLI ${executable} is unavailable.`));
+        checks.push(check("sandbox.image", "warn", "Microsandbox image presence is not inspected in read-only mode; no image was downloaded."));
+        checks.push(check("egress.sidecar", "warn", "Approved HTTPS egress presets are not supported by microsandbox-local in this alpha."));
+    }
+    checks.push(await inspectPort(env, runtime.fetch ?? globalThis.fetch));
+    return { schema_version: 1, ok: !checks.some((item) => item.status === "fail"), checks };
+}
+function readAuthSnapshot(path) {
+    if (!existsSync(path))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error("auth.json is not valid JSON");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("auth.json must contain an object");
+    }
+    for (const [provider, value] of Object.entries(parsed)) {
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            throw new Error(`auth.json.${provider} must contain a credential object`);
+        }
+        const credential = value;
+        if (credential.type !== "api_key" && credential.type !== "oauth") {
+            throw new Error(`auth.json.${provider}.type must be api_key or oauth`);
+        }
+        if (credential.type === "api_key" && (typeof credential.key !== "string" || credential.key.length === 0)) {
+            throw new Error(`auth.json.${provider}.key must be a non-empty string`);
+        }
+    }
+    return parsed;
+}
+function inspectPath(id, path, kind, expectedMode) {
+    if (!existsSync(path))
+        return check(id, "warn", `${path} does not exist; oma doctor left it unchanged.`);
+    const lst = lstatSync(path);
+    if (lst.isSymbolicLink())
+        return check(id, "fail", `${path} is a symlink; use an owner-controlled ${kind}.`);
+    const st = statSync(path);
+    const correctKind = kind === "directory" ? st.isDirectory() : st.isFile();
+    if (!correctKind)
+        return check(id, "fail", `${path} is not a ${kind}.`);
+    const mode = st.mode & 0o777;
+    if ((mode & 0o077) !== 0) {
+        return check(id, "fail", `${path} permissions are 0${mode.toString(8)}; expected owner-only access such as 0${expectedMode.toString(8)}.`);
+    }
+    return check(id, "pass", `${path} is owner-controlled.`);
+}
+async function inspectPort(env, fetchImpl) {
+    const host = env.OMA_HOST?.trim() || "127.0.0.1";
+    const port = Number(env.OMA_PORT?.trim() || "4180");
+    if (!Number.isSafeInteger(port) || port < 1 || port > 65535) {
+        return check("server.port", "fail", "OMA_PORT must be an integer from 1 through 65535.");
+    }
+    if (host === "127.0.0.1" || host === "localhost" || host === "::1") {
+        try {
+            const response = await fetchImpl(`http://${host}:${port}/health`, { signal: AbortSignal.timeout(750) });
+            if (response.ok)
+                return check("server.port", "pass", `OMA is already responding on ${host}:${port}.`);
+        }
+        catch {
+            // A failed health request is followed by a bind-only availability test.
+        }
+    }
+    return await new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", () => resolve(check("server.port", "fail", `${host}:${port} is occupied by a process that did not answer as OMA.`)));
+        server.listen({ host, port, exclusive: true }, () => {
+            server.close(() => resolve(check("server.port", "pass", `${host}:${port} is available for oma up.`)));
+        });
+    });
+}
+function check(id, status, summary) {
+    return { id, status, summary };
+}
+function safeError(prefix, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return `${prefix}: ${message.replace(/https?:\/\/[^\s]+/g, "[redacted-url]")}`;
+}
+function parseArgs(argv) {
+    let json = false;
+    let sandbox = "docker-local";
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--sandbox") {
+            const value = argv[++index];
+            if (value === "docker" || value === "docker-local")
+                sandbox = "docker-local";
+            else if (value === "microsandbox" || value === "microsandbox-local")
+                sandbox = "microsandbox-local";
+            else
+                throw new Error("--sandbox requires docker or microsandbox");
+        }
+        else {
+            throw new Error(`Unknown option for oma doctor: ${arg}`);
+        }
+    }
+    return { json, sandbox };
+}
+async function main() {
+    let options;
+    try {
+        options = parseArgs(process.argv.slice(2));
+    }
+    catch (error) {
+        console.error(`oma: ${error instanceof Error ? error.message : String(error)}\nRun \`oma doctor --help\` for usage.`);
+        process.exit(2);
+    }
+    let report;
+    try {
+        report = await inspectOma(options);
+    }
+    catch (error) {
+        const summary = safeError("Doctor could not complete its read-only inspection", error);
+        if (options.json) {
+            console.log(JSON.stringify({
+                schema_version: 1,
+                ok: false,
+                checks: [check("doctor.internal", "fail", summary)],
+            }, null, 2));
+        }
+        else {
+            console.error(`oma: ${summary}`);
+        }
+        process.exit(2);
+    }
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log("OMA doctor (read-only)\n");
+        for (const item of report.checks)
+            console.log(`${item.status.toUpperCase().padEnd(4)} ${item.id}  ${item.summary}`);
+        console.log(`\n${report.ok ? "Ready" : "Not ready"}. No files were created and no images were downloaded.`);
+    }
+    process.exit(report.ok ? 0 : 1);
+}
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+    await main();
+}

package/dist/scripts/oma-models.js

@@ -0,0 +1,299 @@
+// Operator CLI for Pi model/provider discovery and model credential storage
+// (plan 0139 D6). This intentionally reuses the same deployment parser,
+// catalog factory, and atomic AuthStorage backend as the control plane.
+import { stdin as input, stderr as errorOut } from "node:process";
+import { pathToFileURL } from "node:url";
+import { parseModelDeploymentConfigFromEnv, validateModelDeploymentConfigAgainstCatalog, } from "../src/control-plane/models/deployment-config.js";
+import { createOmaAuthStorageBackend } from "../src/control-plane/models/auth-storage-backend.js";
+import { createPiModelCatalog } from "../src/control-plane/models/catalog.js";
+const USAGE = `Usage: npx tsx scripts/oma-models.ts <command> [args]
+
+Commands:
+  providers-status                         Show enabled model providers
+  models-list [--provider name] [--available]
+                                           List enabled models
+  models-validate [--file path]            Validate Pi models.json and deployment policy
+  auth-set <provider> [--stdin]            Store an API key for an enabled provider
+  auth-remove <provider>                   Remove a stored provider API key (idempotent)
+  auth-status [provider]                   Show credential readiness without secrets
+`;
+export async function runModelsCli(argv, runtime) {
+    const [command, ...args] = argv;
+    if (command === undefined || command === "help" || command === "--help") {
+        return { code: command === undefined ? 1 : 0, stdout: USAGE, stderr: "" };
+    }
+    try {
+        switch (command) {
+            case "providers-status":
+                return ok(providersStatus(loadCatalog(runtime.env)));
+            case "models-list": {
+                const options = parseModelsListArgs(args);
+                return ok(modelsList(loadCatalog(runtime.env), options));
+            }
+            case "models-validate":
+                return ok(modelsValidate(runtime.env, parseModelsValidateArgs(args)));
+            case "auth-set":
+                return ok(await authSet(runtime, args));
+            case "auth-remove":
+                return ok(authRemove(runtime.env, args));
+            case "auth-status":
+                assertAuthStatusArgs(args);
+                return ok(authStatus(loadCatalog(runtime.env), args));
+            default:
+                return fail(`Unknown command: ${command}\n\n${USAGE}`);
+        }
+    }
+    catch (err) {
+        return fail(err instanceof Error ? err.message : String(err));
+    }
+}
+function loadCatalog(env, overrides = {}) {
+    const deployment = parseModelDeploymentConfigFromEnv(env);
+    const config = {
+        ...deployment,
+        ...(overrides.modelsPath === undefined ? {} : { modelsPath: overrides.modelsPath }),
+    };
+    const catalog = createPiModelCatalog({
+        allowedProviders: config.allowedProviders,
+        defaultModel: config.defaultModel,
+        authPath: config.authPath,
+        modelsPath: config.modelsPath,
+        allowModelAuthCommands: config.allowModelAuthCommands,
+        authBackend: createOmaAuthStorageBackend(config.authPath),
+    });
+    validateModelDeploymentConfigAgainstCatalog(config, {
+        hasProvider: (provider) => catalog.allowedProviders.has(provider),
+        hasModel: (model) => catalog.resolve(model) !== undefined,
+    });
+    return catalog;
+}
+function providersStatus(catalog) {
+    const lines = ["provider\tname\tready_models\ttotal_models\tdefault"];
+    for (const provider of [...catalog.allowedProviders].sort()) {
+        const models = catalog.list({ provider });
+        const available = models.filter((model) => catalog.hasConfiguredAuth(model));
+        const isDefault = provider === catalog.defaultModel.provider;
+        const displayName = catalog.modelRegistry.getProviderDisplayName(provider);
+        lines.push([
+            provider,
+            displayName,
+            String(available.length),
+            String(models.length),
+            isDefault ? "true" : "false",
+        ].join("\t"));
+    }
+    return `${lines.join("\n")}\n`;
+}
+function modelsList(catalog, options) {
+    if (options.provider !== undefined && !catalog.allowedProviders.has(options.provider)) {
+        throw new Error(`Model provider ${options.provider} is not enabled on this deployment`);
+    }
+    const models = catalog.list({
+        provider: options.provider,
+        availableOnly: options.availableOnly,
+    }).sort((a, b) => a.provider.localeCompare(b.provider) ||
+        a.id.localeCompare(b.id));
+    const lines = ["provider\tid\tname\tapi\tcredentials_configured\tdefault"];
+    for (const model of models) {
+        const isDefault = model.provider === catalog.defaultModel.provider &&
+            model.id === catalog.defaultModel.id;
+        lines.push([
+            model.provider,
+            model.id,
+            model.name,
+            model.api,
+            catalog.hasConfiguredAuth(model) ? "true" : "false",
+            isDefault ? "true" : "false",
+        ].join("\t"));
+    }
+    return `${lines.join("\n")}\n`;
+}
+function modelsValidate(env, options) {
+    const catalog = loadCatalog(env, options.file === undefined ? {} : { modelsPath: options.file });
+    const warnings = catalog.securityReport.warnings.map((warning) => `Warning: ${warning}`);
+    return [
+        ...warnings,
+        `Model configuration is valid.`,
+        `Enabled providers: ${[...catalog.allowedProviders].sort().join(", ")}`,
+        `Default model: ${catalog.defaultModel.provider}/${catalog.defaultModel.id}`,
+        "",
+    ].join("\n");
+}
+async function authSet(runtime, args) {
+    const parsed = parseAuthSetArgs(args);
+    const catalog = loadCatalog(runtime.env);
+    assertEnabledProvider(catalog, parsed.provider);
+    const key = parsed.stdin
+        ? await (runtime.readStdin ?? readAllStdin)()
+        : await (runtime.promptSecret ?? promptSecret)(`API key for ${parsed.provider}: `);
+    const trimmed = key.trim();
+    if (trimmed === "")
+        throw new Error("API key must not be empty");
+    catalog.authStorage.set(parsed.provider, { type: "api_key", key: trimmed });
+    return (`Stored API key for ${parsed.provider}.\n` +
+        `The key was not printed. Restart \`oma up\` for a running appliance to observe this change.\n`);
+}
+function authRemove(env, args) {
+    if (args.length !== 1)
+        throw new Error("Usage: oma auth remove <provider>");
+    const [provider] = args;
+    assertProviderName(provider);
+    const catalog = loadCatalog(env);
+    catalog.authStorage.remove(provider);
+    return `Removed stored API key for ${provider} if one existed. Restart \`oma up\` for a running appliance to observe this change.\n`;
+}
+function authStatus(catalog, args) {
+    const providers = args.length === 1 ? [args[0]] : [...catalog.allowedProviders].sort();
+    const lines = ["provider\tstored\tready_models\ttotal_models"];
+    for (const provider of providers) {
+        assertProviderName(provider);
+        assertEnabledProvider(catalog, provider);
+        const models = catalog.list({ provider });
+        const ready = models.filter((model) => catalog.hasConfiguredAuth(model));
+        lines.push([
+            provider,
+            catalog.authStorage.has(provider) ? "true" : "false",
+            String(ready.length),
+            String(models.length),
+        ].join("\t"));
+    }
+    return `${lines.join("\n")}\n`;
+}
+function assertAuthStatusArgs(args) {
+    if (args.length > 1 || args[0]?.startsWith("--")) {
+        throw new Error("Usage: oma auth status [provider]");
+    }
+}
+function parseModelsListArgs(args) {
+    const options = { availableOnly: false };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--provider") {
+            const provider = requiredOption(args, ++index, arg);
+            assertProviderName(provider);
+            options.provider = provider;
+        }
+        else if (arg === "--available") {
+            options.availableOnly = true;
+        }
+        else {
+            throw new Error(`Unknown option for oma models list: ${arg}\nRun \`oma help models list\` for usage.`);
+        }
+    }
+    return options;
+}
+function parseModelsValidateArgs(args) {
+    const options = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--file") {
+            options.file = requiredOption(args, ++index, arg);
+        }
+        else {
+            throw new Error(`Unknown option for oma models validate: ${arg}\nRun \`oma help models validate\` for usage.`);
+        }
+    }
+    return options;
+}
+function parseAuthSetArgs(args) {
+    const [provider, ...rest] = args;
+    if (!provider)
+        throw new Error("Usage: oma auth set <provider> [--stdin]");
+    assertProviderName(provider);
+    let stdin = false;
+    for (const arg of rest) {
+        if (arg === "--stdin") {
+            stdin = true;
+        }
+        else if (arg.startsWith("--")) {
+            throw new Error(`Unknown option for oma auth set: ${arg}\nRun \`oma help auth set\` for usage.`);
+        }
+        else {
+            throw new Error("oma auth set does not accept API keys as command-line arguments. Use --stdin or the hidden prompt.");
+        }
+    }
+    return { provider, stdin };
+}
+function assertEnabledProvider(catalog, provider) {
+    if (!catalog.allowedProviders.has(provider)) {
+        throw new Error(`Model provider ${provider} is not enabled on this deployment`);
+    }
+}
+function assertProviderName(provider) {
+    if (provider === "" || provider.trim() !== provider) {
+        throw new Error(`Invalid provider name: ${provider}`);
+    }
+}
+function requiredOption(args, index, option) {
+    const value = args[index];
+    if (value === undefined || value.startsWith("--"))
+        throw new Error(`${option} requires a value`);
+    return value;
+}
+function ok(stdout) {
+    return { code: 0, stdout, stderr: "" };
+}
+function fail(message) {
+    return { code: 2, stdout: "", stderr: `${message}\n` };
+}
+async function readAllStdin() {
+    let out = "";
+    input.setEncoding("utf8");
+    for await (const chunk of input)
+        out += chunk;
+    if (out.endsWith("\n"))
+        out = out.slice(0, -1);
+    if (out.endsWith("\r"))
+        out = out.slice(0, -1);
+    if (out.includes("\n") || out.includes("\r")) {
+        throw new Error("--stdin accepts exactly one API key value");
+    }
+    return out;
+}
+async function promptSecret(message) {
+    if (!input.isTTY)
+        throw new Error("Cannot prompt for an API key on non-interactive stdin; use --stdin");
+    errorOut.write(message);
+    return await new Promise((resolve, reject) => {
+        const chunks = [];
+        const wasRaw = input.isRaw;
+        const onData = (chunk) => {
+            const text = chunk.toString("utf8");
+            for (const char of text) {
+                if (char === "\n" || char === "\r") {
+                    cleanup();
+                    errorOut.write("\n");
+                    resolve(chunks.join(""));
+                    return;
+                }
+                if (char === "\u0003") {
+                    cleanup();
+                    errorOut.write("\n");
+                    reject(new Error("Cancelled"));
+                    return;
+                }
+                if (char === "\u007f" || char === "\b") {
+                    chunks.pop();
+                    continue;
+                }
+                chunks.push(char);
+            }
+        };
+        const cleanup = () => {
+            input.off("data", onData);
+            input.setRawMode(wasRaw);
+            input.pause();
+        };
+        input.resume();
+        input.setRawMode(true);
+        input.on("data", onData);
+    });
+}
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+    const result = await runModelsCli(process.argv.slice(2), { env: process.env });
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    process.exit(result.code);
+}

package/dist/scripts/oma-workspaces.js

@@ -0,0 +1,133 @@
+// Operator CLI for workspace and API-key provisioning (plan 0113 D8).
+//
+// Runs against the live server's SQLite database through
+// openWorkspaceStoreForProvisioning: same WAL/busy_timeout pragmas, no
+// .oma.lock, so keys take effect without a server restart.
+//
+//   OMA_SQLITE_PATH=/path/to/oma.db npx tsx scripts/oma-workspaces.ts <command>
+import { pathToFileURL } from "node:url";
+import { openWorkspaceStoreForProvisioning, } from "../src/control-plane/deployment-storage.js";
+const USAGE = `Usage: npx tsx scripts/oma-workspaces.ts <command> [args]
+
+The database path comes from OMA_SQLITE_PATH or --db <path> (the same file
+the OMA server uses). Commands run safely while the server is up; minted and
+revoked keys take effect without a restart.
+
+Commands:
+  create-workspace <name>            Create a workspace and print its id
+  list-workspaces                    List workspace ids and names
+  mint-key <workspace_id> [label]    Mint an API key. The plaintext is printed
+                                     ONCE and never stored; only its SHA-256
+                                     digest exists at rest.
+  list-keys <workspace_id>           List key digests, labels, revocation state
+  revoke-key <key_sha256>            Revoke a key (tombstone; audit row kept)
+`;
+export function runWorkspacesCli(argv, env) {
+    const args = [...argv];
+    let sqlitePath = env.OMA_SQLITE_PATH;
+    const dbFlag = args.indexOf("--db");
+    if (dbFlag !== -1) {
+        sqlitePath = args[dbFlag + 1];
+        if (sqlitePath === undefined)
+            return fail("--db requires a path");
+        args.splice(dbFlag, 2);
+    }
+    const [command, ...rest] = args;
+    if (command === undefined || command === "help" || command === "--help") {
+        return { code: command === undefined ? 1 : 0, stdout: USAGE, stderr: "" };
+    }
+    if (sqlitePath === undefined || sqlitePath.trim() === "") {
+        return fail("Set OMA_SQLITE_PATH or pass --db <path>");
+    }
+    let store;
+    try {
+        store = openWorkspaceStoreForProvisioning(sqlitePath);
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : String(error));
+    }
+    try {
+        return dispatch(store, command, rest);
+    }
+    finally {
+        store.close();
+    }
+}
+function dispatch(store, command, args) {
+    switch (command) {
+        case "create-workspace": {
+            const [name] = args;
+            if (!name)
+                return fail("create-workspace requires a name");
+            const workspace = store.createWorkspace(name);
+            return ok(`Created workspace ${workspace.workspace_id} (${workspace.name})\n` +
+                `Next: mint-key ${workspace.workspace_id}\n`);
+        }
+        case "list-workspaces": {
+            const rows = store.listWorkspaces();
+            return ok(rows.map((row) => `${row.workspace_id}\t${row.name}`).join("\n") + "\n");
+        }
+        case "mint-key": {
+            const [workspaceId, label = "default"] = args;
+            if (!workspaceId)
+                return fail("mint-key requires a workspace_id");
+            let minted;
+            try {
+                minted = store.mintKey(workspaceId, label);
+            }
+            catch (error) {
+                return fail(error instanceof Error ? error.message : String(error));
+            }
+            return ok(`Workspace:  ${minted.workspaceId}\n` +
+                `Label:      ${minted.label}\n` +
+                `Key sha256: ${minted.keySha256}\n` +
+                `API key:    ${minted.plaintextKey}\n` +
+                `\n` +
+                `This is the ONLY time the key is shown. Store it now.\n` +
+                `Clients send it as the x-api-key header.\n`);
+        }
+        case "list-keys": {
+            const [workspaceId] = args;
+            if (!workspaceId)
+                return fail("list-keys requires a workspace_id");
+            if (!store.getWorkspace(workspaceId)) {
+                return fail(`Workspace not found: ${workspaceId}`);
+            }
+            const rows = store.listKeys(workspaceId);
+            const lines = rows.map((row) => `${row.key_sha256}\t${row.label}\t` +
+                (row.revoked_at === null ? "active" : `revoked ${row.revoked_at}`));
+            return ok(lines.length === 0 ? "(no keys)\n" : lines.join("\n") + "\n");
+        }
+        case "revoke-key": {
+            const [keySha256] = args;
+            if (!keySha256)
+                return fail("revoke-key requires a key_sha256");
+            const existing = store.getKey(keySha256);
+            if (existing === undefined)
+                return fail(`Key not found: ${keySha256}`);
+            if (existing.revoked_at !== null) {
+                return ok(`Key was already revoked at ${existing.revoked_at}\n`);
+            }
+            store.revokeKey(keySha256);
+            return ok(`Revoked ${keySha256} (workspace ${existing.workspace_id}).\n` +
+                `New requests with this key now fail with 401. Already-open SSE\n` +
+                `streams run until disconnect; restart the server to sever them.\n`);
+        }
+        default:
+            return fail(`Unknown command: ${command}\n\n${USAGE}`);
+    }
+}
+function ok(stdout) {
+    return { code: 0, stdout, stderr: "" };
+}
+function fail(message) {
+    return { code: 1, stdout: "", stderr: `${message}\n` };
+}
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+    const result = runWorkspacesCli(process.argv.slice(2), process.env);
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    process.exit(result.code);
+}