@k2b/cloud 0.6.0-rc.0

package/src/cli/admin/data.ts

@@ -0,0 +1,343 @@
+/**
+ * Storage diagnostics for Postgres and Redis.
+ */
+import { command, flag } from "../index";
+import { apiGet, formatBytes, printJsonOrTable, truncate } from "./shared";
+
+export type DiagnosticWarning = {
+  title: string;
+  detail: string;
+  tone: "amber" | "red";
+};
+
+export type PostgresDiagnostics = {
+  available: boolean;
+  error: string | null;
+  schemas: number;
+  tables: number;
+  totalBytes: number;
+  installedExtensions: number;
+  availableExtensions: number;
+  tableRows: {
+    schema: string;
+    name: string;
+    estimatedRows: number;
+    deadRows: number;
+    totalBytes: number;
+    tableBytes: number;
+    indexBytes: number;
+    warnings: string[];
+  }[];
+  extensionRows: {
+    name: string;
+    installed: boolean;
+    installedVersion: string | null;
+    defaultVersion: string | null;
+    comment: string | null;
+  }[];
+  warnings: DiagnosticWarning[];
+};
+
+export type PostgresSession = {
+  pid: number;
+  application: string | null;
+  user: string | null;
+  state: string | null;
+  waitEventType: string | null;
+  waitEvent: string | null;
+  queryAgeSeconds: number | null;
+  transactionAgeSeconds: number | null;
+  blockedBy: number[];
+  query: string | null;
+};
+
+export type PostgresIndexDiagnostic = {
+  schema: string;
+  table: string;
+  name: string;
+  sizeBytes: number;
+  scans: number;
+  isUnique: boolean;
+  isPrimary: boolean;
+};
+
+/** Sessions report ages rather than measured durations. */
+const formatSeconds = (seconds: number | null): string => {
+  if (seconds === null || !Number.isFinite(seconds)) return "-";
+  if (seconds < 60) return `${Math.round(seconds)}s`;
+  if (seconds < 3600) return `${Math.round(seconds / 60)}m`;
+  return `${Math.round(seconds / 3600)}h`;
+};
+
+export type RedisRuntime = {
+  usedMemoryBytes: number | null;
+  maxMemoryBytes: number | null;
+  maxMemoryPolicy: string | null;
+  evictedKeys: number | null;
+  connectedClients: number | null;
+  hitRate: number | null;
+};
+
+export type RedisDiagnostics = {
+  runtime?: RedisRuntime;
+  available: boolean;
+  error: string | null;
+  dbSize: number;
+  sampledKeys: number;
+  scanComplete: boolean;
+  keyspace: { database: string; keys: number; expires: number; avgTtlMs: number }[];
+  prefixes: { depth: number; prefix: string; count: number; share: number }[];
+  warnings: DiagnosticWarning[];
+};
+
+export const schemaRows = (tables: PostgresDiagnostics["tableRows"]) => {
+  const schemas = new Map<string, { schema: string; tables: number; rows: number; totalBytes: number; warnings: number }>();
+  for (const table of tables) {
+    const current = schemas.get(table.schema) ?? { schema: table.schema, tables: 0, rows: 0, totalBytes: 0, warnings: 0 };
+    current.tables += 1;
+    current.rows += table.estimatedRows;
+    current.totalBytes += table.totalBytes;
+    current.warnings += table.warnings.length;
+    schemas.set(table.schema, current);
+  }
+  return [...schemas.values()]
+    .sort((a, b) => b.totalBytes - a.totalBytes)
+    .map((schema) => ({ ...schema, total: formatBytes(schema.totalBytes) }));
+};
+
+export const dataCommands = [
+  command("postgres summary", {
+    summary: "Show Postgres diagnostic summary",
+    run: async ({ ctx }) => {
+      const data = await apiGet<PostgresDiagnostics>(ctx, "/api/gateway/data/postgres");
+      const rows = [
+        {
+          available: data.available,
+          schemas: data.schemas,
+          tables: data.tables,
+          storage: formatBytes(data.totalBytes),
+          extensions: `${data.installedExtensions}/${data.availableExtensions}`,
+          warnings: data.warnings.length,
+          error: data.error ?? "",
+        },
+      ];
+      printJsonOrTable(ctx, data, rows, [
+        { key: "available" },
+        { key: "schemas" },
+        { key: "tables" },
+        { key: "storage" },
+        { key: "extensions" },
+        { key: "warnings" },
+        { key: "error" },
+      ]);
+    },
+  }),
+  command("postgres tables", {
+    summary: "List Postgres tables",
+    flags: {
+      schema: flag.string({ description: "Schema filter" }),
+      search: flag.string({ aliases: ["q"], description: "Search schema, table, or warning" }),
+      sort: flag.enum(["size", "rows", "name", "dead"], { default: "size", description: "Sort order" }),
+    },
+    run: async ({ ctx, flags }) => {
+      const data = await apiGet<PostgresDiagnostics>(ctx, "/api/gateway/data/postgres");
+      const needle = flags.search?.toLowerCase();
+      const tables = data.tableRows
+        .filter((table) => !flags.schema || table.schema === flags.schema)
+        .filter((table) => {
+          if (!needle) return true;
+          return `${table.schema}.${table.name} ${table.warnings.join(" ")}`.toLowerCase().includes(needle);
+        })
+        .sort((a, b) => {
+          if (flags.sort === "rows") return b.estimatedRows - a.estimatedRows;
+          if (flags.sort === "dead") return b.deadRows - a.deadRows;
+          if (flags.sort === "name") return `${a.schema}.${a.name}`.localeCompare(`${b.schema}.${b.name}`);
+          return b.totalBytes - a.totalBytes;
+        });
+      const rows = tables.map((table) => ({
+        table: `${table.schema}.${table.name}`,
+        rows: table.estimatedRows,
+        total: formatBytes(table.totalBytes),
+        heap: formatBytes(table.tableBytes),
+        indexes: formatBytes(table.indexBytes),
+        deadRows: table.deadRows,
+        warnings: table.warnings.join(", "),
+      }));
+      printJsonOrTable(ctx, { ...data, tableRows: tables }, rows, [
+        { key: "table" },
+        { key: "rows" },
+        { key: "total" },
+        { key: "heap" },
+        { key: "indexes" },
+        { key: "deadRows" },
+        { key: "warnings" },
+      ]);
+    },
+  }),
+  command("postgres schemas", {
+    summary: "List Postgres schemas with aggregate table size",
+    run: async ({ ctx }) => {
+      const data = await apiGet<PostgresDiagnostics>(ctx, "/api/gateway/data/postgres");
+      const rows = schemaRows(data.tableRows);
+      printJsonOrTable(ctx, { items: rows }, rows, [
+        { key: "schema" },
+        { key: "tables" },
+        { key: "rows" },
+        { key: "total" },
+        { key: "warnings" },
+      ]);
+    },
+  }),
+  command("postgres extensions", {
+    summary: "List available Postgres extensions",
+    flags: {
+      installed: flag.boolean({ description: "Only installed extensions" }),
+      search: flag.string({ aliases: ["q"], description: "Search extensions" }),
+    },
+    run: async ({ ctx, flags }) => {
+      const data = await apiGet<PostgresDiagnostics>(ctx, "/api/gateway/data/postgres");
+      const needle = flags.search?.toLowerCase();
+      const rows = data.extensionRows
+        .filter((extension) => !flags.installed || extension.installed)
+        .filter((extension) => {
+          if (!needle) return true;
+          return `${extension.name} ${extension.comment ?? ""}`.toLowerCase().includes(needle);
+        })
+        .map((extension) => ({
+          name: extension.name,
+          installed: extension.installed,
+          installedVersion: extension.installedVersion ?? "",
+          defaultVersion: extension.defaultVersion ?? "",
+          description: truncate(extension.comment, 80),
+        }));
+      printJsonOrTable(ctx, { items: rows }, rows, [
+        { key: "name" },
+        { key: "installed" },
+        { key: "installedVersion" },
+        { key: "defaultVersion" },
+        { key: "description" },
+      ]);
+    },
+  }),
+  command("postgres sessions", {
+    summary: "List backend sessions, blocked and longest-running first",
+    description:
+      "Answers who is blocking and who holds the idle connections — questions the aggregate connection count can raise but not resolve. Sessions reporting no application_name show as 'unnamed'; that is a finding, not a gap in the output.",
+    examples: ["cld admin postgres sessions --json", "cld admin postgres sessions --blocked"],
+    flags: {
+      blocked: flag.boolean({ description: "Only sessions waiting on another session" }),
+      idle: flag.boolean({ description: "Include plainly idle sessions" }),
+    },
+    run: async ({ ctx, flags }) => {
+      const raw = await apiGet<{ items: PostgresSession[] }>(ctx, "/api/gateway/data/postgres/sessions");
+      const items = raw.items
+        .filter((session) => !flags.blocked || session.blockedBy.length > 0)
+        .filter((session) => flags.idle || session.state !== "idle" || session.blockedBy.length > 0);
+      printJsonOrTable(
+        ctx,
+        { items },
+        items.map((session) => ({
+          pid: session.pid,
+          state: session.blockedBy.length > 0 ? `blocked by ${session.blockedBy.join(",")}` : (session.state ?? "-"),
+          application: session.application ?? "unnamed",
+          waiting: session.waitEvent ? `${session.waitEventType}: ${session.waitEvent}` : "-",
+          txAge: formatSeconds(session.transactionAgeSeconds),
+          query: truncate(session.query, 60) ?? "-",
+        })),
+        [
+          { key: "pid", label: "PID" },
+          { key: "state", label: "State" },
+          { key: "application", label: "Application" },
+          { key: "waiting", label: "Waiting on" },
+          { key: "txAge", label: "Txn age" },
+          { key: "query", label: "Statement" },
+        ],
+      );
+    },
+  }),
+
+  command("postgres indexes", {
+    summary: "List the largest indexes with their scan counts",
+    description:
+      "Index bulk is invisible on a per-table total size. Scans are cumulative since the last statistics reset, so zero means 'not used since then' — not that the index is unnecessary.",
+    examples: ["cld admin postgres indexes --json", "cld admin postgres indexes --unused"],
+    flags: { unused: flag.boolean({ description: "Only indexes never scanned since the last statistics reset" }) },
+    run: async ({ ctx, flags }) => {
+      const raw = await apiGet<{ items: PostgresIndexDiagnostic[] }>(ctx, "/api/gateway/data/postgres/indexes");
+      const items = raw.items.filter((index) => !flags.unused || (index.scans === 0 && !index.isPrimary));
+      printJsonOrTable(
+        ctx,
+        { items },
+        items.map((index) => ({
+          index: index.name,
+          table: `${index.schema}.${index.table}`,
+          kind: index.isPrimary ? "primary" : index.isUnique ? "unique" : "index",
+          size: formatBytes(index.sizeBytes),
+          scans: index.scans,
+        })),
+        [{ key: "index" }, { key: "table" }, { key: "kind" }, { key: "size" }, { key: "scans" }],
+      );
+    },
+  }),
+
+  command("redis summary", {
+    summary: "Show Redis diagnostic summary",
+    run: async ({ ctx }) => {
+      const data = await apiGet<RedisDiagnostics>(ctx, "/api/gateway/data/redis");
+      const expiring = data.keyspace.reduce((sum, row) => sum + row.expires, 0);
+      const runtime = data.runtime;
+      const rows = [
+        {
+          available: data.available,
+          keys: data.dbSize,
+          expiring,
+          // Keyspace shape says nothing about health; these are the signals
+          // that actually indicate Redis is in trouble.
+          memory: runtime?.usedMemoryBytes == null ? "-" : formatBytes(runtime.usedMemoryBytes),
+          evicted: runtime?.evictedKeys ?? "-",
+          hitRate: runtime?.hitRate == null ? "-" : `${(runtime.hitRate * 100).toFixed(1)}%`,
+          clients: runtime?.connectedClients ?? "-",
+          warnings: data.warnings.length,
+          error: data.error ?? "",
+        },
+      ];
+      printJsonOrTable(ctx, data, rows, [
+        { key: "available" },
+        { key: "keys" },
+        { key: "expiring" },
+        { key: "memory" },
+        { key: "evicted" },
+        { key: "hitRate", label: "Hit rate" },
+        { key: "clients" },
+        { key: "warnings" },
+        { key: "error" },
+      ]);
+    },
+  }),
+  command("redis prefixes", {
+    summary: "List sampled Redis prefixes",
+    flags: {
+      depth: flag.int({ default: 3, min: 1, max: 3, description: "Prefix depth" }),
+      search: flag.string({ aliases: ["q"], description: "Search prefixes" }),
+    },
+    run: async ({ ctx, flags }) => {
+      const data = await apiGet<RedisDiagnostics>(ctx, "/api/gateway/data/redis");
+      const needle = flags.search?.toLowerCase();
+      const rows = data.prefixes
+        .filter((prefix) => prefix.depth === flags.depth)
+        .filter((prefix) => !needle || prefix.prefix.toLowerCase().includes(needle))
+        .map((prefix) => ({
+          prefix: prefix.prefix,
+          depth: prefix.depth,
+          count: prefix.count,
+          share: `${(prefix.share * 100).toFixed(1)}%`,
+        }));
+      printJsonOrTable(ctx, { items: rows, sampledKeys: data.sampledKeys, scanComplete: data.scanComplete }, rows, [
+        { key: "prefix" },
+        { key: "depth" },
+        { key: "count" },
+        { key: "share" },
+      ]);
+    },
+  }),
+];

package/src/cli/admin/documentation.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { cliText, command, confirmFlag, flag, printStructured } from "../index";
+import { apiGet } from "./shared";
+
+const path = "/api/admin/core/settings";
+
+export const documentationCommands = [
+  command("documentation get", {
+    summary: "Read the website used by administration documentation links",
+    async run({ ctx }) {
+      const config = z.object({ url: z.string() }).parse(await apiGet(ctx, `${path}/documentation`));
+      if (!printStructured(ctx, config)) ctx.print(config.url);
+    },
+  }),
+  command("documentation set", {
+    summary: "Set the documentation base URL without changing authentication or other settings",
+    flags: {
+      url: flag.string({ required: true, description: "Documentation base URL, such as https://cloud.k2b.dev" }),
+      yes: confirmFlag("Confirm documentation website change"),
+    },
+    async run({ ctx, flags }) {
+      if (!flags.yes) throw new Error(cliText(ctx, { en: "Documentation changes require --yes.", de: "Doku-Änderungen erfordern --yes." }));
+      await ctx.readJson(
+        await ctx.fetch(path, {
+          method: "PUT",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ updates: { "app.documentation_url": flags.url } }),
+        }),
+      );
+      if (!printStructured(ctx, { saved: true }))
+        ctx.print(cliText(ctx, { en: "Documentation website saved.", de: "Dokumentationsadresse gespeichert." }));
+    },
+  }),
+];

package/src/cli/admin/gateway.ts

@@ -0,0 +1,155 @@
+/**
+ * Gateway surface: the registry of running apps and the route table.
+ */
+import { arg, type CloudCliContext, command, confirmFlag, flag } from "../index";
+import { apiGet, apiJson, formatMs, printJsonOrTable, queryString } from "./shared";
+
+export type GatewayHealth = {
+  status: "ok" | "warn" | "error";
+  checkedAt: string;
+  summary: Record<string, number>;
+  apps: {
+    id: string;
+    name: string;
+    status: "ok" | "warn" | "error";
+    online: boolean;
+    healthy: boolean;
+    lastSeenAt: string;
+    offlineForMs: number;
+  }[];
+};
+
+export type GatewayRoute = {
+  prefix: string;
+  appId: string;
+  count: number;
+  errors: number;
+  slow: number;
+  avgDurationMs: number | null;
+};
+
+export type GatewayRoutesResponse = {
+  generatedAt: string | null;
+  instanceId: string | null;
+  total: number;
+  routeCount: number;
+  items: GatewayRoute[];
+};
+
+export const resolveApp = async (ctx: CloudCliContext, ref: string) => {
+  const health = await apiGet<GatewayHealth>(ctx, "/api/gateway/health");
+  const lower = ref.toLowerCase();
+  const matches = health.apps.filter((app) => app.id.toLowerCase() === lower || app.name.toLowerCase() === lower);
+  if (matches.length === 1) return { health, app: matches[0]! };
+  if (matches.length > 1) throw new Error(`Ambiguous app reference "${ref}". Use an app id.`);
+  throw new Error(`App "${ref}" not found.`);
+};
+
+export const gatewayCommands = [
+  command("apps list", {
+    summary: "List registered apps and live health",
+    run: async ({ ctx }) => {
+      const health = await apiGet<GatewayHealth>(ctx, "/api/gateway/health");
+      const rows = health.apps.map((app) => ({
+        id: app.id,
+        name: app.name,
+        status: app.status,
+        online: app.online,
+        healthy: app.healthy,
+        lastSeen: app.lastSeenAt,
+        offlineMs: app.offlineForMs,
+      }));
+      printJsonOrTable(ctx, health, rows, [
+        { key: "id" },
+        { key: "status" },
+        { key: "online" },
+        { key: "healthy" },
+        { key: "lastSeen" },
+        { key: "name" },
+      ]);
+    },
+  }),
+  command("apps get", {
+    summary: "Show one registered app by id or exact name",
+    args: { ref: arg.required({ valueLabel: "id|name" }) },
+    run: async ({ ctx, args }) => {
+      const { app } = await resolveApp(ctx, args.ref);
+      printJsonOrTable(
+        ctx,
+        app,
+        [
+          {
+            id: app.id,
+            name: app.name,
+            status: app.status,
+            online: app.online,
+            healthy: app.healthy,
+            lastSeen: app.lastSeenAt,
+            offlineMs: app.offlineForMs,
+          },
+        ],
+        [
+          { key: "id" },
+          { key: "name" },
+          { key: "status" },
+          { key: "online" },
+          { key: "healthy" },
+          { key: "lastSeen" },
+          { key: "offlineMs" },
+        ],
+      );
+    },
+  }),
+  command("apps remove", {
+    summary: "Remove an offline registered app",
+    args: { id: arg.required({ valueLabel: "app-id" }) },
+    flags: { yes: confirmFlag("Confirm removing the offline app registry entry") },
+    run: async ({ ctx, args, flags }) => {
+      if (!flags.yes) throw new Error("Refusing to remove an app without --yes.");
+      const result = await apiJson<{ id: string }>(ctx, "DELETE", `/api/gateway/apps/${encodeURIComponent(args.id)}`);
+      if (ctx.options.output === "json") ctx.json(result);
+      else ctx.print(`Removed ${result.id}.`);
+    },
+  }),
+  command("routes list", {
+    summary: "List active gateway routes",
+    flags: {
+      search: flag.string({ aliases: ["q"], description: "Search route prefix or app id" }),
+      app: flag.string({ description: "Filter by app id" }),
+      errors: flag.boolean({ description: "Only routes with errors" }),
+      range: flag.enum(["1h", "6h", "24h", "7d", "30d"] as const, {
+        default: "24h",
+        description: "Traffic window for hit and error counts",
+      }),
+      sort: flag.enum(["count", "prefix", "errors"], { default: "count", description: "Sort by count, prefix, or errors" }),
+    },
+    run: async ({ ctx, flags }) => {
+      const result = await apiGet<GatewayRoutesResponse>(
+        ctx,
+        `/api/gateway/routes${queryString({
+          search: flags.search,
+          app: flags.app,
+          errors: flags.errors,
+          sort: flags.sort,
+          range: flags.range,
+        })}`,
+      );
+      const rows = result.items.map((route) => ({
+        prefix: route.prefix,
+        app: route.appId,
+        requests: route.count,
+        errors: route.errors,
+        slow: route.slow,
+        avgMs: formatMs(route.avgDurationMs),
+      }));
+      printJsonOrTable(ctx, result, rows, [
+        { key: "prefix" },
+        { key: "app" },
+        { key: "requests" },
+        { key: "errors" },
+        { key: "slow" },
+        { key: "avgMs", label: "Avg" },
+      ]);
+    },
+  }),
+];

package/src/cli/admin/index.ts

@@ -0,0 +1,61 @@
+/**
+ * `cld admin` — Cloud administration surfaces.
+ *
+ * Commands are grouped per domain in sibling modules; this file only composes
+ * them. The groups map to the admin UI areas, so a command and the page that
+ * shows the same data stay easy to find together.
+ */
+import { defineCliCommands } from "../commands";
+import { accountAdministrationCommands } from "./account-administration";
+import { accountCategoryCommands } from "./account-categories";
+import { appSignInCommands } from "./app-sign-in";
+import { aiUsageCommands } from "./ai-usage";
+import { dataCommands } from "./data";
+import { documentationCommands } from "./documentation";
+import { gatewayCommands } from "./gateway";
+import { instanceCommands } from "./instance";
+import { jobCommands } from "./jobs";
+import { legalCommands } from "./legal";
+import { linuxCommands } from "./linux";
+import { logCommands } from "./logs";
+import { metricsCommands } from "./metrics";
+import { natsCommands } from "./nats";
+import { notificationCommands } from "./notifications";
+import { syncCommands } from "./sync";
+import { telemetryCommands } from "./telemetry";
+import { webhookCommands } from "./webhooks";
+import { workflowCommands } from "./workflows";
+
+export default defineCliCommands({
+  name: "admin",
+  summary: "Inspect and operate Cloud administration surfaces.",
+  groupSummaries: {
+    "app-sign-in config": "Manage the trusted app website and pairing policy.",
+    "accounts config": "Manage account types and sign-in visibility.",
+    "accounts administration": "Manage account requests and account/group follow-up notices.",
+    legal: "Manage Terms, Privacy, and Imprint.",
+    linux: "Prepare Linux identities.",
+    "linux config": "Manage Linux identity defaults and allocation range.",
+  },
+  commands: [
+    ...documentationCommands,
+    ...appSignInCommands,
+    ...accountCategoryCommands,
+    ...accountAdministrationCommands,
+    ...aiUsageCommands,
+    ...instanceCommands,
+    ...gatewayCommands,
+    ...logCommands,
+    ...telemetryCommands,
+    ...jobCommands,
+    ...legalCommands,
+    ...linuxCommands,
+    ...workflowCommands,
+    ...dataCommands,
+    ...notificationCommands,
+    ...webhookCommands,
+    ...metricsCommands,
+    ...natsCommands,
+    ...syncCommands,
+  ],
+});