@gloom-sh/terminal 0.0.0-stage → 0.19.0

package/src/cli/commands/plugins.ts

@@ -0,0 +1,382 @@
+import { basename, join, resolve } from "path";
+import { existsSync, lstatSync, readFileSync, rmSync } from "fs";
+import {
+  DEPRECATED_HOST_EXPORTS,
+  REMOVED_HOST_EXPORTS,
+  checkPluginCompatibility,
+  explainPluginLoadError,
+  findHostImports,
+  pluginSourceFiles,
+  readPluginManifest,
+  type HostExportTable,
+} from "../../plugins/compat";
+import type { AbsorbedPlugin } from "../../plugins/absorbed";
+import {
+  findAbsorbedCheckout,
+  getPluginsDir,
+  readPluginCommit,
+  resolvePluginBrowserEntry,
+  resolvePluginEntry,
+} from "../../plugins/loader";
+import { linkHostPackages } from "../../plugins/host-link";
+import {
+  installedPluginDirectories,
+  loadRegistryListings,
+  readPluginRemote,
+  readPluginRemoteHeads,
+  updatePlugin,
+  validatePluginDirectoryName,
+  type RegistryListing,
+} from "../../plugins/installer";
+import { isReservedBuiltinPluginId } from "../../plugins/ownership";
+import { pluginFromModule, pluginSupportsTarget } from "../../plugins/plugin-export";
+import { formatVersion, requiredGloomberb } from "../../utils/semver";
+import { ALL_PLUGIN_TARGETS, type GloomPlugin, type PluginTarget } from "../../types/plugin";
+import {
+  cliStyles,
+  renderStats,
+  renderTable,
+} from "../../utils/cli-output";
+import type { CliCommandContext } from "../../types/plugin";
+import { fail } from "../errors";
+import { VERSION } from "../../version";
+
+/**
+ * The `plugins`, `update` and `plugin doctor` commands. Installing, updating
+ * and linking themselves live in plugins/installer.ts, shared with the
+ * marketplace and the desktop.
+ */
+
+const PLUGINS_DIR = getPluginsDir();
+
+/**
+ * For a leftover checkout of a plugin that is built in now. The folder is
+ * not removed for the user: an older Gloomberb sharing it may still load it.
+ */
+function absorbedNotice(absorbed: AbsorbedPlugin, directory: string | null): string {
+  const built = `${absorbed.name} is built into Gloom now`;
+  return directory ? `${built}; remove this copy with "gloom remove ${directory}".` : `${built}.`;
+}
+
+export async function updatePlugins(name?: string) {
+  const dirs = name ? [validatePluginDirectoryName(name)] : installedPluginDirectories();
+
+  if (dirs.length === 0) {
+    console.log(cliStyles.muted("No plugins installed."));
+    return;
+  }
+
+  const listings = await loadRegistryListings();
+  for (const dir of dirs) {
+    const targetDir = join(PLUGINS_DIR, dir);
+    const absorbed = findAbsorbedCheckout(targetDir);
+    if (absorbed) {
+      console.log(cliStyles.muted(`Skipping ${dir} (${absorbed.name} is built into Gloom now)`));
+      continue;
+    }
+    if (lstatSync(targetDir, { throwIfNoEntry: false })?.isSymbolicLink()) {
+      console.log(cliStyles.muted(`Skipping ${dir} (linked to a local checkout)`));
+      continue;
+    }
+    if (!existsSync(join(targetDir, ".git"))) {
+      console.log(cliStyles.warning(`Skipping ${dir} (not a git repo)`));
+      continue;
+    }
+    const remote = readPluginRemote(targetDir);
+    const listing = remote ? listings.get(remote.toLowerCase()) : undefined;
+    const required = requiredGloomberb(listing?.minGloomberb);
+    if (required) {
+      console.log(cliStyles.warning(`Skipping ${dir} (needs Gloom ${required}, this is ${VERSION})`));
+      continue;
+    }
+    try {
+      await updatePlugin(dir, { pin: listing?.pin ?? undefined });
+    } catch (error) {
+      console.error(cliStyles.danger(`Failed to update ${dir}: ${error instanceof Error ? error.message : String(error)}`));
+    }
+  }
+}
+
+type PluginCheckStatus = "ok" | "warn" | "fail";
+
+interface PluginCheck {
+  id: string;
+  status: PluginCheckStatus;
+  message: string;
+}
+
+export interface PluginDoctorReport {
+  directory: string;
+  path: string;
+  id: string | null;
+  name: string | null;
+  version: string | null;
+  linked: boolean;
+  commit: string | null;
+  checks: PluginCheck[];
+  /** Worst status across the checks. */
+  status: PluginCheckStatus;
+}
+
+const HOST_LITERAL_PATTERN = /https?:\/\/([a-z0-9][a-z0-9.-]*\.[a-z]{2,})/gi;
+
+const IGNORED_HOST_PATTERN = /(^|\.)(example\.(com|org|net)|localhost|github\.com|gloom\.sh)$/i;
+
+function hostCovered(host: string, declared: readonly string[]): boolean {
+  return declared.some((entry) => host === entry || host.endsWith(`.${entry}`));
+}
+
+/** Host imports the compat tables list, as `name from gloomberb/x (...)` lines. */
+function listedHostImports<T>(
+  sources: readonly string[],
+  table: HostExportTable<T>,
+  describeEntry: (entry: T) => string,
+): string[] {
+  const found = new Set<string>();
+  for (const source of sources) {
+    for (const { specifier, name } of findHostImports(source)) {
+      const entry = table[specifier]?.[name];
+      if (entry) found.add(`${name} from ${specifier} (${describeEntry(entry)})`);
+    }
+  }
+  return [...found].sort();
+}
+
+/**
+ * Everything that makes a plugin show up as `failed` or as a broken pane
+ * later, checked before the author publishes: the entry resolves, the
+ * Gloomberb it declares is this one or older, it imports nothing removed or
+ * deprecated, the module evaluates, the export is a plugin, the id is free,
+ * the targets are real, the hosts it reaches are declared, and the browser
+ * build the desktop and web app need actually compiles.
+ */
+async function doctorPlugin(nameOrPath: string): Promise<PluginDoctorReport> {
+  const candidate = nameOrPath.includes("/") || nameOrPath.startsWith(".") ? resolve(nameOrPath) : join(PLUGINS_DIR, nameOrPath);
+  if (!existsSync(candidate)) fail(`Plugin "${nameOrPath}" was not found.`, PLUGINS_DIR);
+  const directory = basename(candidate);
+  const linked = lstatSync(candidate).isSymbolicLink();
+  const checks: PluginCheck[] = [];
+  const report: PluginDoctorReport = {
+    directory,
+    path: candidate,
+    id: null,
+    name: null,
+    version: null,
+    linked,
+    commit: readPluginCommit(candidate),
+    checks,
+    status: "ok",
+  };
+  const add = (id: string, status: PluginCheckStatus, message: string) => {
+    checks.push({ id, status, message });
+    if (status === "fail" || (status === "warn" && report.status === "ok")) report.status = status;
+  };
+
+  // Not broken, and not worth importing: the loader skips it for the built-in.
+  const absorbed = findAbsorbedCheckout(candidate);
+  if (absorbed) {
+    const installed = candidate === join(PLUGINS_DIR, directory);
+    add("built-in", "warn", `Not loaded: ${absorbedNotice(absorbed, installed ? directory : null)}`);
+    return report;
+  }
+
+  const entryFile = await resolvePluginEntry(candidate);
+  if (!entryFile) {
+    add("entry", "fail", "No entry file: add index.ts or a package.json \"main\".");
+    return report;
+  }
+  add("entry", "ok", basename(entryFile));
+
+  const link = linkHostPackages(candidate);
+  if (link.error) add("host-link", "fail", `Gloom runtime is not linked: ${link.error}`);
+  else if (link.provider === "process") add("host-link", "ok", "served by the host process");
+  else add("host-link", "ok", `linked ${link.linked.join(", ")}`);
+
+  const incompatible = checkPluginCompatibility(candidate);
+  const declaredMin = readPluginManifest(candidate).minGloomberb;
+  // The loader skips this check for a linked checkout, so it only warns there.
+  if (incompatible) add("gloom", linked ? "warn" : "fail", incompatible.error);
+  else if (declaredMin) add("gloom", "ok", `${formatVersion(declaredMin)} or newer`);
+  else add("gloom", "warn", "Declares no minimum Gloom: set minGloom in gloom.json.");
+
+  // Before the import: a removed export is exactly what makes it fail.
+  const sources = pluginSourceFiles(candidate).map((file) => readFileSync(file, "utf-8"));
+  const removed = listedHostImports(sources, REMOVED_HOST_EXPORTS, (entry) => `removed in ${entry.removedIn}; use ${entry.use}`);
+  const deprecated = listedHostImports(sources, DEPRECATED_HOST_EXPORTS, (entry) => `deprecated in ${entry.deprecatedIn}; use ${entry.use}`);
+  if (removed.length > 0) add("host-api", "fail", `Imports removed APIs: ${removed.join(", ")}`);
+  if (deprecated.length > 0) add("host-api", "warn", `Imports deprecated APIs: ${deprecated.join(", ")}`);
+  if (removed.length === 0 && deprecated.length === 0) add("host-api", "ok", "no removed or deprecated imports");
+
+  let plugin: GloomPlugin | null = null;
+  try {
+    plugin = pluginFromModule(await import(`${entryFile}?doctor=${Date.now()}`));
+    if (!plugin) {
+      add("export", "fail", "Module evaluated, but the default export is not a GloomPlugin (id and name are required).");
+      return report;
+    }
+    report.id = plugin.id;
+    report.name = plugin.name;
+    report.version = plugin.version ?? null;
+    add("export", "ok", `${plugin.name} v${plugin.version ?? "0.0.0"}`);
+  } catch (error) {
+    add("export", "fail", `Import failed: ${explainPluginLoadError(error instanceof Error ? error.message : String(error))}`);
+    return report;
+  }
+
+  if (!plugin.version) add("version", "warn", "No version; the marketplace cannot tell when an update is available.");
+  if (isReservedBuiltinPluginId(plugin.id)) add("id", "fail", `"${plugin.id}" is reserved by a built-in module.`);
+  else add("id", "ok", plugin.id);
+
+  const badTargets = (plugin.targets ?? []).filter((target) => !ALL_PLUGIN_TARGETS.includes(target as PluginTarget));
+  if (badTargets.length > 0) add("targets", "fail", `Unknown targets: ${badTargets.join(", ")}`);
+  else add("targets", "ok", plugin.targets?.length ? plugin.targets.join(", ") : "all renderers");
+
+  if (plugin.configSchema) {
+    const missingKeys = plugin.configSchema.filter((field) => !field.key || !field.label);
+    if (missingKeys.length > 0) add("config-schema", "fail", "Every configSchema field needs a key and a label.");
+    else add("config-schema", "ok", `${plugin.configSchema.length} setting${plugin.configSchema.length === 1 ? "" : "s"}`);
+  }
+
+  const declaredHosts = plugin.hosts ?? [];
+  const seenHosts = new Set<string>();
+  for (const text of sources) {
+    for (const match of text.matchAll(HOST_LITERAL_PATTERN)) {
+      const host = match[1]!.toLowerCase();
+      if (IGNORED_HOST_PATTERN.test(host)) continue;
+      seenHosts.add(host);
+    }
+  }
+  const undeclared = [...seenHosts].filter((host) => !hostCovered(host, declaredHosts)).sort();
+  if (undeclared.length > 0) {
+    // A regex over source: a link the plugin only opens in the browser shows
+    // up too, so this is a prompt to check, not a verdict.
+    add("hosts", "warn", `In source but not in hosts: ${undeclared.join(", ")}. Anything fetched from there works on desktop and fails on the web.`);
+  } else {
+    add("hosts", "ok", declaredHosts.length ? declaredHosts.join(", ") : "no third-party hosts found");
+  }
+
+  const rendersInBrowser = pluginSupportsTarget(plugin, "desktop") || pluginSupportsTarget(plugin, "web");
+  if (rendersInBrowser) {
+    const browserEntry = await resolvePluginBrowserEntry(candidate);
+    try {
+      const { bundleExternalPlugin } = await import("../../plugins/bundle");
+      const { getPluginCacheDir } = await import("../../plugins/loader");
+      const outDir = join(getPluginCacheDir(), "doctor", directory);
+      const result = await bundleExternalPlugin(candidate, outDir, { define: { "process.env.NODE_ENV": "\"production\"" } });
+      const size = Math.round(Bun.file(result.outputPath).size / 1024);
+      add("browser-build", "ok", `${basename(browserEntry ?? entryFile)} compiles for the desktop view (${size}KB)`);
+      rmSync(outDir, { recursive: true, force: true });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      add("browser-build", "fail", `Desktop build failed: ${message.split("\n")[0]}. Ship an index.browser.ts without node:* imports, or set targets to ["cli", "tui"].`);
+    }
+  } else {
+    add("browser-build", "ok", "skipped, terminal only");
+  }
+
+  return report;
+}
+
+export async function doctorPlugins(nameOrPath?: string): Promise<PluginDoctorReport[]> {
+  if (nameOrPath) return [await doctorPlugin(nameOrPath)];
+  const reports: PluginDoctorReport[] = [];
+  for (const dir of installedPluginDirectories()) reports.push(await doctorPlugin(dir));
+  return reports;
+}
+
+export interface InstalledPluginRow {
+  name: string;
+  version: string;
+  commit: string;
+  /** Set only with --check: "up to date", the commit waiting, or "" for a linked checkout. */
+  update?: string;
+  description: string;
+  linked: boolean;
+  /**
+   * Why the loader skips it without importing it: it needs a newer Gloomberb,
+   * the checkout is known to break, or the plugin is built in now.
+   */
+  blocked?: string;
+}
+
+async function readInstalledPlugins(options: { check?: boolean }): Promise<InstalledPluginRow[]> {
+  const entries = installedPluginDirectories();
+  if (entries.length === 0) return [];
+
+  const absorbed = new Map(entries.map((name) => [name, findAbsorbedCheckout(join(PLUGINS_DIR, name))]));
+  const updatable = entries.filter((name) => !absorbed.get(name));
+  // Off by default: this is a local listing, and asking every remote turns it
+  // into a network call that can hang behind a credential prompt.
+  const listings = options.check ? await loadRegistryListings() : new Map<string, RegistryListing>();
+  const heads = options.check && updatable.length > 0 ? await readPluginRemoteHeads(updatable) : {};
+
+  return entries.map((name) => {
+    const dir = join(PLUGINS_DIR, name);
+    const builtIn = absorbed.get(name);
+    let version = "";
+    let description = "";
+    const pkgPath = join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        version = pkg.version || "";
+        description = pkg.description || "";
+      } catch {
+        // Intentional ignore: The installed-plugin row reports the unreadable manifest.
+        description = "Unreadable package.json";
+      }
+    }
+    const linked = lstatSync(dir).isSymbolicLink();
+    const commit = readPluginCommit(dir);
+    const blocked = builtIn ? absorbedNotice(builtIn, name) : linked ? null : checkPluginCompatibility(dir)?.error;
+    const row: InstalledPluginRow = {
+      name,
+      version,
+      commit: linked ? "linked" : commit ? commit.slice(0, 7) : "",
+      description,
+      linked,
+      ...(blocked ? { blocked } : {}),
+    };
+    if (!options.check) return row;
+    // `update` skips it, so nothing is waiting.
+    if (builtIn) return { ...row, update: "" };
+    const remote = readPluginRemote(dir);
+    // A registry-listed plugin moves between reviewed commits, so what its
+    // branch holds today says nothing about whether an update is waiting.
+    const reviewed = remote ? listings.get(remote.toLowerCase())?.pin?.commit : undefined;
+    const target = reviewed ?? heads[name];
+    const behind = !linked && !!target && !!commit && !commit.toLowerCase().startsWith(target.toLowerCase());
+    return { ...row, update: linked ? "" : behind ? target!.slice(0, 7) : "up to date" };
+  });
+}
+
+export async function listPlugins(ctx: CliCommandContext, options: { check?: boolean } = {}) {
+  const plugins = await readInstalledPlugins(options);
+  const columns = [
+    { key: "name", header: "Plugin", shrink: false },
+    { key: "version", header: "Version" },
+    { key: "commit", header: "Commit" },
+    ...(options.check ? [{ key: "update", header: "Update" }] : []),
+    { key: "description", header: "Description" },
+  ];
+  ctx.printResult({ data: plugins, metadata: { directory: PLUGINS_DIR } }, {
+    columns,
+    text: (rows) => {
+      if (rows.length === 0) {
+        return cliStyles.muted("No plugins installed. Install one with gloom install <user/repo>.");
+      }
+      return [
+        renderTable(
+          columns.map(({ header, shrink }) => ({ header, shrink })),
+          rows.map((row) => columns.map(({ key }) => {
+            const value = String(row[key as keyof InstalledPluginRow] ?? "");
+            return key === "update" && value && value !== "up to date" ? cliStyles.warning(value) : value;
+          })),
+        ),
+        ...rows.filter((row) => row.blocked).map((row) => cliStyles.warning(`${row.name} is not loaded: ${row.blocked}`)),
+        "",
+        renderStats([["Directory", cliStyles.muted(PLUGINS_DIR)]]),
+      ].join("\n");
+    },
+  });
+}

package/src/cli/commands/remote.ts

@@ -0,0 +1,219 @@
+import { getDataDir } from "../../data/config/store";
+import type { CliCommandContext } from "../../types/plugin";
+import { sendRemoteControlRequest } from "../../remote/client";
+import type { RemoteAppKind, RemoteControlRequest, RemoteControlResponse } from "../../remote/types";
+import { CLI_COMMAND_GROUPS } from "../help";
+import type { BuiltinCliCommandDef } from "../command-options";
+
+interface RemoteArgs {
+  args: string[];
+  appKind?: RemoteAppKind;
+  expectRev?: string;
+  intervalMs: number;
+}
+
+export const remoteCliCommand: BuiltinCliCommandDef = {
+  name: "remote",
+  description: "Drive a running Gloom app through its remote API",
+  // Resources, operations and JSON go to the app as typed.
+  keepsArgAsTyped: () => true,
+  help: {
+    group: CLI_COMMAND_GROUPS.app,
+    usage: [
+      "remote schema",
+      "remote help",
+      "remote get <resource>",
+      "remote call <operation> [json]",
+      "remote patch <resource> <json-patch> [--expect-rev <rev>]",
+      "remote batch <json>",
+      "remote watch <resource> [--interval <ms>]",
+    ],
+    options: [
+      { flags: "--app <app>", description: "tui or desktop, when both are running" },
+      { flags: "--expect-rev <rev>", description: "Refuse the patch unless the resource is still at this revision" },
+      { flags: "--interval <ms>", description: "How often watch polls, at least 100 (default 1000)" },
+      { flags: "--dry-run", description: "Check a call, patch, or batch without applying it" },
+    ],
+    examples: ["remote schema", "remote get layout", "remote watch layout --limit 5"],
+  },
+  execute: async (rawArgs, ctx) => {
+    const parsed = parseRemoteArgs(rawArgs);
+    const action = parsed.args[0];
+    if (!action) {
+      ctx.fail("Usage: gloom remote <schema|help|get|call|patch|batch|watch>");
+      return;
+    }
+
+    // No data folder means this profile never opened the app, so none is running to drive.
+    const dataDir = await getDataDir();
+    if (!dataDir) {
+      ctx.fail("No running Gloom app found.", "Open the desktop app or run gloom, then try again.");
+      return;
+    }
+
+    if (action === "watch") {
+      const resource = parsed.args[1];
+      if (!resource) {
+        ctx.fail("Usage: gloom remote watch <resource>");
+        return;
+      }
+      const limit = ctx.cliOptions.limit ?? Number.POSITIVE_INFINITY;
+      for (let index = 0; index < limit; index += 1) {
+        const response = await sendRemoteControlRequest({ type: "get", resource }, {
+          dataDir,
+          appKind: parsed.appKind,
+        });
+        printRemoteResponse(response, ctx);
+        if (index < limit - 1) await new Promise((resolve) => setTimeout(resolve, parsed.intervalMs));
+      }
+      return;
+    }
+
+    const request = buildRemoteRequest(action, parsed, ctx.cliOptions.dryRun);
+    const response = await sendRemoteControlRequest(request, {
+      dataDir,
+      appKind: parsed.appKind,
+    });
+    printRemoteResponse(response, ctx);
+  },
+};
+
+function parseRemoteArgs(rawArgs: string[]): RemoteArgs {
+  const args: string[] = [];
+  let appKind: RemoteAppKind | undefined;
+  let expectRev: string | undefined;
+  let intervalMs = 1_000;
+
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index]!;
+    if (arg === "--app") {
+      index += 1;
+      appKind = parseAppKind(rawArgs[index]);
+      continue;
+    }
+    if (arg.startsWith("--app=")) {
+      appKind = parseAppKind(arg.slice("--app=".length));
+      continue;
+    }
+    if (arg === "--expect-rev") {
+      index += 1;
+      expectRev = rawArgs[index];
+      if (!expectRev) throw new Error("Missing value for --expect-rev.");
+      continue;
+    }
+    if (arg.startsWith("--expect-rev=")) {
+      expectRev = arg.slice("--expect-rev=".length);
+      continue;
+    }
+    if (arg === "--interval") {
+      index += 1;
+      intervalMs = parseInterval(rawArgs[index]);
+      continue;
+    }
+    if (arg.startsWith("--interval=")) {
+      intervalMs = parseInterval(arg.slice("--interval=".length));
+      continue;
+    }
+    args.push(arg);
+  }
+
+  return { args, appKind, expectRev, intervalMs };
+}
+
+function buildRemoteRequest(action: string, parsed: RemoteArgs, dryRun: boolean): RemoteControlRequest {
+  switch (action) {
+    case "schema":
+      return { type: "schema" };
+    case "help":
+      return { type: "help" };
+    case "get": {
+      const resource = parsed.args[1];
+      if (!resource) throw new Error("Usage: gloom remote get <resource>");
+      return { type: "get", resource };
+    }
+    case "call": {
+      const operation = parsed.args[1];
+      if (!operation) throw new Error("Usage: gloom remote call <operation> [json]");
+      return {
+        type: "call",
+        operation,
+        input: parseJsonValue(parsed.args[2], {}),
+        dryRun,
+      };
+    }
+    case "patch": {
+      const resource = parsed.args[1];
+      const patchRaw = parsed.args[2];
+      if (!resource || !patchRaw) throw new Error("Usage: gloom remote patch <resource> <json-patch>");
+      const patch = parseJsonValue(patchRaw, []);
+      if (!Array.isArray(patch)) throw new Error("Remote patch payload must be a JSON array.");
+      return {
+        type: "patch",
+        resource,
+        patch,
+        expectRev: parsed.expectRev,
+        dryRun,
+      };
+    }
+    case "batch": {
+      const payload = parseJsonValue(parsed.args[1], null);
+      if (!payload) throw new Error("Usage: gloom remote batch <json>");
+      if (Array.isArray(payload)) return { type: "batch", requests: payload as RemoteControlRequest[], dryRun };
+      return withCliDryRun(payload as RemoteControlRequest, dryRun);
+    }
+    default:
+      throw new Error(`Unknown remote action "${action}".`);
+  }
+}
+
+function withCliDryRun(request: RemoteControlRequest, dryRun: boolean): RemoteControlRequest {
+  if (!dryRun) return request;
+  if (request.type === "batch") return { ...request, dryRun: true };
+  if (request.type === "call" || request.type === "patch") return { ...request, dryRun: true };
+  return request;
+}
+
+function parseAppKind(value: string | undefined): RemoteAppKind {
+  if (value === "tui" || value === "desktop") return value;
+  throw new Error("--app must be either tui or desktop.");
+}
+
+function parseInterval(value: string | undefined): number {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 100) {
+    throw new Error("--interval must be an integer >= 100.");
+  }
+  return parsed;
+}
+
+function parseJsonValue<T>(raw: string | undefined, fallback: T): unknown {
+  if (raw == null) return fallback;
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`Invalid JSON payload: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function printRemoteResponse(
+  response: RemoteControlResponse,
+  ctx: CliCommandContext,
+): void {
+  if (!response.ok) {
+    const details = response.error.details == null
+      ? undefined
+      : typeof response.error.details === "string"
+        ? response.error.details
+        : JSON.stringify(response.error.details, null, 2);
+    ctx.fail(response.error.message, details);
+    return;
+  }
+  const data = response.state ? { data: response.data, state: response.state } : response.data;
+  ctx.printResult({
+    data,
+    metadata: response.rev ? { rev: response.rev } : undefined,
+    warnings: response.warnings,
+  }, {
+    text: (data) => JSON.stringify(data, null, 2),
+  });
+}