@corvio/admin-cli 0.1.0-beta.2

package/README.md

@@ -0,0 +1,12 @@
+# Corvio Platform Administrator CLI
+
+Official read-only CLI for bounded Corvio platform investigations. It is separate from the Workspace CLI and accepts only a short-lived `cva_` credential.
+
+```bash
+npm install --global @corvio/admin-cli
+export CORVIO_ADMIN_API_KEY='cva_...'
+corvio-admin auth status
+corvio-admin catalog --json
+```
+
+Every data query requires a purpose and returns an auditable receipt. This package contains no ordinary Workspace commands. See [the administrator CLI guide](https://corvio.ai/developers/admin-cli).

package/dist/cli.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+import {
+  ApiClient,
+  CliError,
+  EXIT,
+  listOption,
+  normalizeApiBase,
+  numberOption,
+  option,
+  readAdminCredential,
+  readTextFile,
+  runMain,
+  writeResult,
+} from "./core.js";
+
+const VERSION = "0.1.0-beta.2";
+const DEFAULT_API_BASE = "https://api.corvio.ai/v1";
+const USER_AGENT = `corvio-admin-cli/${VERSION}`;
+
+const HELP = `Corvio Platform Administrator CLI ${VERSION}
+
+Usage:
+  corvio-admin auth status
+  corvio-admin capabilities
+  corvio-admin catalog
+  corvio-admin query|data query --file <request.json>
+  corvio-admin workspaces list --purpose <reason>
+  corvio-admin users list --purpose <reason>
+  corvio-admin runs list|content [id] --purpose <reason>
+  corvio-admin worker-jobs list --purpose <reason>
+  corvio-admin usage events|summary --purpose <reason>
+  corvio-admin receipts get <id>
+
+Authentication:
+  Set CORVIO_ADMIN_API_KEY to a short-lived cva_ key.
+
+This package contains no Workspace ask, search, docs, files, sync, or share commands.
+`;
+
+function baseUrl(options) {
+  return normalizeApiBase(options["api-base"] || process.env.CORVIO_API_BASE, DEFAULT_API_BASE);
+}
+
+function client(options) {
+  const credential = readAdminCredential();
+  if (!credential) {
+    throw new CliError("Set CORVIO_ADMIN_API_KEY to a short-lived cva_ key.", {
+      code: "admin_auth_required",
+      exitCode: EXIT.AUTH,
+    });
+  }
+  return new ApiClient({ baseUrl: baseUrl(options), credential: credential.key, userAgent: USER_AGENT });
+}
+
+function listQuery(options) {
+  return {
+    purpose: option(options, "purpose", { required: true }),
+    workspace_id: options["workspace-id"],
+    status: options.status,
+    limit: numberOption(options, "limit", 100),
+    cursor: options.cursor,
+  };
+}
+
+async function authStatus(options) {
+  const api = client(options);
+  const identity = await api.request("/me");
+  if (identity.api_key?.audience !== "platform_admin") {
+    throw new CliError("The configured key is not a platform administrator credential.", {
+      code: "admin_audience_required",
+      exitCode: EXIT.AUTH,
+    });
+  }
+  writeResult({ authenticated: true, source: "environment", identity }, { json: options.json });
+}
+
+async function capabilities(options) {
+  const api = client(options);
+  const [index, identity] = await Promise.all([api.request("/admin"), api.request("/me")]);
+  writeResult({ cli_version: VERSION, api: index, principal: identity }, { json: options.json });
+}
+
+async function catalog(options) {
+  writeResult(await client(options).request("/admin/data/catalog"), { json: options.json });
+}
+
+async function query(options) {
+  let body;
+  if (options.file) {
+    body = JSON.parse(await readTextFile(options.file));
+    if (options.purpose) body.purpose = options.purpose;
+  } else {
+    body = {
+      dataset: option(options, "dataset", { required: true }),
+      purpose: option(options, "purpose", { required: true }),
+      fields: listOption(options, "fields"),
+      group_by: listOption(options, "group-by"),
+      metrics: options.metrics ? JSON.parse(options.metrics) : [],
+      filters: options.filters ? JSON.parse(options.filters) : [],
+      order_by: options["order-by"] ? JSON.parse(options["order-by"]) : [],
+      limit: numberOption(options, "limit", 100),
+      cursor: options.cursor || null,
+    };
+  }
+  writeResult(await client(options).request("/admin/data/query", { method: "POST", body }), { json: options.json });
+}
+
+async function listResource(options, resource) {
+  writeResult(await client(options).request(`/admin/${resource}`, { query: listQuery(options) }), { json: options.json });
+}
+
+async function main({ options, positionals }) {
+  const [command, action, id] = positionals;
+  if (options.version || command === "version") return writeResult(VERSION, { json: options.json });
+  if (options.help || !command || command === "help") return writeResult(HELP.trimEnd(), { json: false });
+  if (command === "auth" && action === "status") return authStatus(options);
+  if (command === "capabilities") return capabilities(options);
+  if (command === "catalog") return catalog(options);
+  if (command === "query") return query(options);
+  if (command === "data" && action === "query") return query(options);
+  if (command === "workspaces" && (action || "list") === "list") return listResource(options, "workspaces");
+  if (command === "users" && (action || "list") === "list") return listResource(options, "users");
+  if (command === "worker-jobs" && (action || "list") === "list") return listResource(options, "worker-jobs");
+  if (command === "runs" && action === "list") return listResource(options, "runs");
+  if (command === "runs" && action === "content") {
+    const runId = id || option(options, "id", { required: true });
+    const purpose = option(options, "purpose", { required: true });
+    return writeResult(await client(options).request(`/admin/runs/${runId}/content`, { query: { purpose } }), { json: options.json });
+  }
+  if (command === "usage" && action === "events") return listResource(options, "usage/events");
+  if (command === "usage" && action === "summary") {
+    return writeResult(await client(options).request("/admin/usage/summary", { query: listQuery(options) }), { json: options.json });
+  }
+  if (command === "receipts" && action === "get") {
+    const receiptId = id || option(options, "id", { required: true });
+    return writeResult(await client(options).request(`/admin/data/query-receipts/${receiptId}`), { json: options.json });
+  }
+  throw new CliError(`Unknown administrator command: ${positionals.join(" ")}`);
+}
+
+await runMain(main);

package/dist/core.js

@@ -0,0 +1,324 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+export const EXIT = Object.freeze({
+  OK: 0,
+  USAGE: 2,
+  AUTH: 3,
+  UNAVAILABLE: 4,
+  CONFLICT: 5,
+  RATE_LIMIT: 6,
+  REMOTE: 7,
+});
+
+export class CliError extends Error {
+  constructor(message, { code = "cli_error", exitCode = EXIT.USAGE, status = null, details = null } = {}) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+    this.exitCode = exitCode;
+    this.status = status;
+    this.details = details;
+  }
+}
+
+function exitCodeForStatus(status) {
+  if (status === 401 || status === 403) return EXIT.AUTH;
+  if (status === 409) return EXIT.CONFLICT;
+  if (status === 429) return EXIT.RATE_LIMIT;
+  return EXIT.REMOTE;
+}
+
+export function parseArgv(argv) {
+  const options = Object.create(null);
+  const positionals = [];
+  const booleanOptions = new Set([
+    "json",
+    "no-input",
+    "yes",
+    "allow-actions",
+    "private-link",
+    "force",
+    "help",
+    "version",
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (!value.startsWith("--")) {
+      positionals.push(value);
+      continue;
+    }
+    const separator = value.indexOf("=");
+    const name = value.slice(2, separator === -1 ? undefined : separator);
+    if (booleanOptions.has(name)) {
+      options[name] = separator === -1 ? true : value.slice(separator + 1) !== "false";
+      continue;
+    }
+    if (separator !== -1) {
+      options[name] = value.slice(separator + 1);
+      continue;
+    }
+    const next = argv[index + 1];
+    if (next === undefined || next.startsWith("--")) {
+      throw new CliError(`Option --${name} requires a value.`, { code: "missing_option_value" });
+    }
+    options[name] = next;
+    index += 1;
+  }
+  return { options, positionals };
+}
+
+export function option(options, name, { required = false, fallback = undefined } = {}) {
+  const value = options[name] ?? fallback;
+  if (required && (value === undefined || String(value).trim() === "")) {
+    throw new CliError(`Missing required option --${name}.`, { code: "missing_required_option" });
+  }
+  return value;
+}
+
+export function listOption(options, name, fallback = []) {
+  const value = options[name];
+  if (value === undefined) return fallback;
+  return String(value).split(",").map((item) => item.trim()).filter(Boolean);
+}
+
+export function numberOption(options, name, fallback) {
+  const value = options[name];
+  if (value === undefined) return fallback;
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isFinite(parsed) || parsed < 1) {
+    throw new CliError(`Option --${name} must be a positive integer.`, { code: "invalid_number_option" });
+  }
+  return parsed;
+}
+
+export function normalizeApiBase(value, fallback) {
+  const raw = String(value || fallback).trim().replace(/\/+$/, "");
+  if (!/^https:\/\//i.test(raw) && !/^http:\/\/(127\.0\.0\.1|localhost)(:\d+)?/i.test(raw)) {
+    throw new CliError("Corvio API base must use HTTPS (localhost is allowed for development).", {
+      code: "insecure_api_base",
+    });
+  }
+  return raw.endsWith("/v1") ? raw : `${raw}/v1`;
+}
+
+export class ApiClient {
+  constructor({ baseUrl, credential = null, userAgent, fetchImpl = globalThis.fetch }) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.credential = credential;
+    this.userAgent = userAgent;
+    this.fetchImpl = fetchImpl;
+  }
+
+  async request(path, { method = "GET", body, query, headers = {}, auth = true } = {}) {
+    const url = new URL(`${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`);
+    for (const [key, value] of Object.entries(query || {})) {
+      if (value !== undefined && value !== null && value !== "") url.searchParams.set(key, String(value));
+    }
+    const requestHeaders = {
+      accept: "application/json",
+      "user-agent": this.userAgent,
+      ...headers,
+    };
+    if (body !== undefined) requestHeaders["content-type"] = "application/json";
+    if (auth) {
+      if (!this.credential) {
+        throw new CliError("Corvio authentication is required.", { code: "auth_required", exitCode: EXIT.AUTH });
+      }
+      requestHeaders.authorization = `Bearer ${this.credential}`;
+    }
+    let response;
+    try {
+      response = await this.fetchImpl(url, {
+        method,
+        headers: requestHeaders,
+        body: body === undefined ? undefined : JSON.stringify(body),
+      });
+    } catch (cause) {
+      throw new CliError(`Unable to reach Corvio: ${cause instanceof Error ? cause.message : String(cause)}`, {
+        code: "network_error",
+        exitCode: EXIT.REMOTE,
+      });
+    }
+    const text = await response.text();
+    let payload = null;
+    if (text) {
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        payload = { message: text.slice(0, 500) };
+      }
+    }
+    if (!response.ok) {
+      const envelope = payload?.error || payload?.detail || payload || {};
+      throw new CliError(String(envelope.message || envelope.code || `Corvio request failed (${response.status}).`), {
+        code: String(envelope.code || `http_${response.status}`),
+        status: response.status,
+        exitCode: exitCodeForStatus(response.status),
+        details: envelope.details || null,
+      });
+    }
+    return payload;
+  }
+}
+
+function configRoot(env = process.env) {
+  if (env.CORVIO_CONFIG_DIR) return resolve(env.CORVIO_CONFIG_DIR);
+  if (env.XDG_CONFIG_HOME) return join(resolve(env.XDG_CONFIG_HOME), "corvio");
+  return join(homedir(), ".config", "corvio");
+}
+
+export function workspaceCredentialPath(env = process.env) {
+  return join(configRoot(env), "credentials.json");
+}
+
+export async function readWorkspaceCredential(env = process.env) {
+  const environmentKey = String(env.CORVIO_API_KEY || "").trim();
+  if (environmentKey) {
+    if (!environmentKey.startsWith("cvk_")) {
+      throw new CliError("CORVIO_API_KEY must be a Workspace cvk_ key.", {
+        code: "invalid_workspace_key",
+        exitCode: EXIT.AUTH,
+      });
+    }
+    return { key: environmentKey, source: "environment", profile: null, metadata: null };
+  }
+  const path = workspaceCredentialPath(env);
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(path, "utf8"));
+  } catch (cause) {
+    if (cause?.code === "ENOENT") return null;
+    throw new CliError("Stored Corvio credentials are unreadable.", { code: "credential_store_invalid", exitCode: EXIT.AUTH });
+  }
+  const profileName = String(parsed.active_profile || "default");
+  const profile = parsed.profiles?.[profileName];
+  const key = String(profile?.api_key || "").trim();
+  if (!key.startsWith("cvk_")) {
+    throw new CliError("Stored Corvio credentials are invalid; run `corvio auth login` again.", {
+      code: "credential_store_invalid",
+      exitCode: EXIT.AUTH,
+    });
+  }
+  return { key, source: "device_link", profile: profileName, metadata: profile };
+}
+
+export async function storeWorkspaceCredential(payload, env = process.env) {
+  const path = workspaceCredentialPath(env);
+  const root = dirname(path);
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  await chmod(root, 0o700).catch(() => {});
+  const profileName = String(payload.workspace_id || "default");
+  const document = {
+    version: 1,
+    active_profile: profileName,
+    profiles: {
+      [profileName]: {
+        api_key: payload.secret,
+        key_id: payload.key_id,
+        workspace_id: payload.workspace_id,
+        workspace_name: payload.workspace_name,
+        scopes: payload.scopes || [],
+        created_at: payload.created_at || new Date().toISOString(),
+        source: "device_link",
+      },
+    },
+  };
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+  await chmod(temporary, 0o600);
+  await rename(temporary, path);
+  await chmod(path, 0o600);
+  return { path, profile: profileName };
+}
+
+export async function clearWorkspaceCredential(env = process.env) {
+  const path = workspaceCredentialPath(env);
+  await rm(path, { force: true });
+  return path;
+}
+
+export function readAdminCredential(env = process.env) {
+  const key = String(env.CORVIO_ADMIN_API_KEY || "").trim();
+  if (!key) return null;
+  if (!key.startsWith("cva_")) {
+    throw new CliError("CORVIO_ADMIN_API_KEY must be a platform administrator cva_ key.", {
+      code: "invalid_admin_key",
+      exitCode: EXIT.AUTH,
+    });
+  }
+  return { key, source: "environment" };
+}
+
+export function writeResult(value, { json = false, stdout = process.stdout } = {}) {
+  if (json || typeof value !== "string") {
+    stdout.write(`${JSON.stringify(value, null, json ? 2 : 0)}\n`);
+  } else {
+    stdout.write(`${value}\n`);
+  }
+}
+
+export function writeError(error, { json = false, stderr = process.stderr } = {}) {
+  const safe = {
+    error: {
+      code: error instanceof CliError ? error.code : "unexpected_error",
+      message: error instanceof Error ? error.message : String(error),
+      ...(error instanceof CliError && error.status ? { status: error.status } : {}),
+      ...(error instanceof CliError && error.details ? { details: error.details } : {}),
+    },
+  };
+  stderr.write(json ? `${JSON.stringify(safe)}\n` : `Error: ${safe.error.message}\n`);
+}
+
+export async function runMain(main, argv = process.argv.slice(2)) {
+  let json = argv.includes("--json");
+  try {
+    const parsed = parseArgv(argv);
+    json = Boolean(parsed.options.json);
+    await main(parsed);
+  } catch (error) {
+    writeError(error, { json });
+    process.exitCode = error instanceof CliError ? error.exitCode : 1;
+  }
+}
+
+export async function openBrowser(url) {
+  const target = String(url);
+  const command = platform() === "darwin" ? "open" : platform() === "win32" ? "cmd" : "xdg-open";
+  const args = platform() === "win32" ? ["/c", "start", "", target] : [target];
+  try {
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function sleep(milliseconds) {
+  await new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds));
+}
+
+export async function readTextFile(path) {
+  return readFile(resolve(String(path)), "utf8");
+}
+
+export async function writeTextFile(path, content) {
+  const target = resolve(String(path));
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, content, "utf8");
+  return target;
+}
+
+export function requireConfirmation(options, action) {
+  if (!options.yes) {
+    throw new CliError(`${action} requires --yes.`, { code: "confirmation_required" });
+  }
+}
+
+export function idempotencyKey(options) {
+  return String(options["idempotency-key"] || randomUUID());
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@corvio/admin-cli",
+  "version": "0.1.0-beta.2",
+  "description": "Official read-only Corvio platform administrator CLI.",
+  "type": "module",
+  "bin": {
+    "corvio-admin": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "prepack": "node ../../scripts/build.mjs admin"
+  },
+  "engines": {
+    "node": ">=20.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NeoFlux-AI/corvio.git",
+    "directory": "developer-cli/packages/admin"
+  },
+  "homepage": "https://corvio.ai/developers/admin-cli",
+  "bugs": {
+    "url": "https://github.com/NeoFlux-AI/corvio/issues"
+  },
+  "keywords": [
+    "corvio",
+    "cli",
+    "admin",
+    "operations"
+  ]
+}