@terminus-ai/cli 0.0.1

package/bin/capability-calls.mjs

@@ -0,0 +1,437 @@
+/**
+ * The release-capability compiler, driven by the SDK's call table.
+ *
+ * `capability-calls.json` (the app-runtime conformance bundle, vendored under
+ * bin/vendor/app-runtime-v1/) says which literal SDK call sites compile which
+ * release capabilities, which automation steps do, and which server-code calls
+ * do. This module applies that table and nothing else: a new call or grant is
+ * a new row there, not a new regular expression here. What the table states
+ * only in prose (its `checks`, and the server.run `unless`) stays code, in the
+ * caller: the horizontal registry, the one version per capability, the
+ * declared egress templates, and the server entry's exports.
+ */
+
+import { readFileSync } from "node:fs";
+
+import { CliError } from "./client.mjs";
+
+export const CAPABILITY_CALLS = JSON.parse(readFileSync(
+  new URL("./vendor/app-runtime-v1/capability-calls.json", import.meta.url),
+  "utf8",
+));
+
+/** The release shell switches the table compiles (`shell.notifications`, from
+ * a notifications.create call or a notification.create step). They are the
+ * release's, never the author's: clone and pull write one into terminus.json
+ * only where the author wrote it themselves. */
+export const COMPILED_SHELL_KEYS = new Set(
+  [...CAPABILITY_CALLS.calls, ...CAPABILITY_CALLS.workload_steps]
+    .flatMap((row) => [row.grant.capability, row.grant.also?.capability])
+    .filter((capability) => capability?.startsWith("shell."))
+    .map((capability) => capability.slice("shell.".length)),
+);
+
+const SOURCES = CAPABILITY_CALLS.sources;
+const SOURCE_EXTENSIONS = new Set(SOURCES.extensions);
+const SKIPPED_DIRECTORIES = new Set(SOURCES.skip_directories);
+const SKIPPED_FILES = new RegExp(SOURCES.skip_files, "u");
+const SDK_MODULE = "@terminus-ai/app-sdk";
+
+/** Whether a package file is scanned for SDK call sites. */
+export function capabilitySourceFile(filePath) {
+  const parts = filePath.replaceAll("\\", "/").split("/");
+  const basename = parts.at(-1) ?? "";
+  const dot = basename.lastIndexOf(".");
+  const extension = dot > 0 ? basename.slice(dot).toLowerCase() : "";
+  return SOURCE_EXTENSIONS.has(extension)
+    && !parts.some((part) => SKIPPED_DIRECTORIES.has(part))
+    && !SKIPPED_FILES.test(basename);
+}
+
+/** Remove comments while preserving string literals and byte offsets. This is
+ * deliberately a small lexical pass rather than a JavaScript parser: the
+ * compiler accepts only direct SDK calls with literal arguments. */
+export function maskCodeComments(source) {
+  const output = [...source];
+  let quote = null;
+  let escaped = false;
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    const next = source[index + 1];
+    if (quote) {
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === quote) quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+    if (char === "/" && next === "/") {
+      output[index] = " ";
+      output[index + 1] = " ";
+      index += 2;
+      while (index < source.length && source[index] !== "\n") {
+        output[index] = " ";
+        index += 1;
+      }
+      index -= 1;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      output[index] = " ";
+      output[index + 1] = " ";
+      index += 2;
+      while (index < source.length && !(source[index] === "*" && source[index + 1] === "/")) {
+        if (source[index] !== "\n") output[index] = " ";
+        index += 1;
+      }
+      if (index < source.length) {
+        output[index] = " ";
+        output[index + 1] = " ";
+        index += 1;
+      }
+    }
+  }
+  return output.join("");
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+/** The names a surface is called by in one file: the surface itself, and any
+ * `import { surface as alias } from "@terminus-ai/app-sdk"` (beside a default
+ * import or not). A longer member path ending in a binding matches too
+ * (`TerminusSDK.net.fetch(...)`). */
+export function sdkSurfaceBindings(code, surface) {
+  const bindings = new Set([surface]);
+  const imports = new RegExp(
+    `\\bimport\\s*(?:[A-Za-z_$][A-Za-z0-9_$]*\\s*,\\s*)?\\{([^}]*)\\}\\s*from\\s*(["'])${escapeRegExp(SDK_MODULE)}\\2`,
+    "gu",
+  );
+  const specifier = new RegExp(
+    `^(?:type\\s+)?${escapeRegExp(surface)}(?:\\s+as\\s+([A-Za-z_$][A-Za-z0-9_$]*))?$`,
+    "u",
+  );
+  for (const match of code.matchAll(imports)) {
+    for (const part of match[1].split(",")) {
+      const binding = specifier.exec(part.trim());
+      if (binding) bindings.add(binding[1] ?? surface);
+    }
+  }
+  return bindings;
+}
+
+/** The leading literal arguments of a call whose argument list starts at
+ * `start` (just past its `(`): single- or double-quoted strings (never a
+ * template literal) and integer literals, in order, up to the first argument
+ * that is not one. */
+function leadingLiterals(code, start, wanted) {
+  const values = [];
+  let index = start;
+  const skipSpace = () => {
+    while (index < code.length && /\s/u.test(code[index])) index += 1;
+  };
+  while (values.length < wanted) {
+    skipSpace();
+    const char = code[index];
+    let value;
+    if (char === '"' || char === "'") {
+      const end = code.indexOf(char, index + 1);
+      if (end < 0) break;
+      const content = code.slice(index + 1, end);
+      if (/[\\\n\r]/u.test(content)) break;
+      value = { kind: "string", text: content };
+      index = end + 1;
+    } else if (/[0-9]/u.test(char ?? "")) {
+      const match = /^[0-9]+/u.exec(code.slice(index));
+      value = { kind: "integer", text: match[0] };
+      index += match[0].length;
+    } else {
+      break;
+    }
+    skipSpace();
+    if (code[index] !== "," && code[index] !== ")") break;
+    values.push(value);
+    if (code[index] === ")") break;
+    index += 1;
+  }
+  return values;
+}
+
+/** Replace `{name}` placeholders from the call's literals; an integer
+ * argument that fills a whole string substitutes as a number. */
+function substitute(template, values) {
+  if (typeof template === "string") {
+    const whole = /^\{([a-z_]+)\}$/u.exec(template);
+    if (whole && Object.hasOwn(values, whole[1])) return values[whole[1]];
+    return template.replace(/\{([a-z_]+)\}/gu, (placeholder, name) => (
+      Object.hasOwn(values, name) ? String(values[name]) : placeholder
+    ));
+  }
+  if (Array.isArray(template)) return template.map((item) => substitute(item, values));
+  if (template && typeof template === "object") {
+    return Object.fromEntries(
+      Object.entries(template).map(([key, value]) => [key, substitute(value, values)]),
+    );
+  }
+  return template;
+}
+
+/** A path into the compiled release: `shell.<field>` is the release's own
+ * shell section (there is no `capabilities.shell`), everything else lives
+ * under capabilities. */
+function grantTarget(capability) {
+  const [head, ...rest] = capability.split(".");
+  return head === "shell"
+    ? { section: "shell", path: rest }
+    : { section: "capabilities", path: [head, ...rest] };
+}
+
+/**
+ * What the call sites and steps compiled so far: plain JSON-shaped groups
+ * keyed the way the table merges them. `apply` is the one place a grant row
+ * is interpreted; `release()` turns the groups into the wire sections.
+ */
+export class CompiledGrants {
+  constructor() {
+    this.groups = new Map();
+    this.declared = new Map();
+  }
+
+  group(target, make) {
+    const key = `${target.section}:${target.path.join(".")}`;
+    if (!this.groups.has(key)) this.groups.set(key, { target, value: make() });
+    return this.groups.get(key).value;
+  }
+
+  /** Apply one grant row for one call's literal values. `where` names the
+   * call site for a conflict message. */
+  apply(grant, values, where, mergeKey = null) {
+    const target = grantTarget(grant.capability);
+    if (grant.requires_declared !== undefined) {
+      const needed = this.declared.get(grant.capability) ?? [];
+      needed.push({ value: substitute(grant.requires_declared.match(/\{[a-z_]+\}/u)[0], values), where });
+      this.declared.set(grant.capability, needed);
+      return;
+    }
+    if (grant.set !== undefined) {
+      const holder = this.group(target, () => ({ set: undefined }));
+      holder.set = substitute(grant.set, values);
+      return;
+    }
+    if (grant.add !== undefined) {
+      const added = substitute(grant.add, values);
+      if (added && typeof added === "object") {
+        const sets = this.group(target, () => ({ fields: new Map() }));
+        for (const [field, value] of Object.entries(added)) {
+          if (!sets.fields.has(field)) sets.fields.set(field, new Set());
+          sets.fields.get(field).add(value);
+        }
+      } else {
+        this.group(target, () => ({ values: new Set() })).values.add(added);
+      }
+      return;
+    }
+    const entry = substitute(grant.entry ?? {}, values);
+    const by = grant.merge_by ?? mergeKey;
+    const key = grant.key !== undefined ? substitute(grant.key, values) : entry[by];
+    const keyed = this.group(target, () => ({ entries: new Map(), keyedObject: grant.key !== undefined }));
+    const existing = keyed.entries.get(key);
+    if (!existing) {
+      keyed.entries.set(key, structuredClone(entry));
+    } else {
+      for (const [field, value] of Object.entries(entry)) {
+        if (Array.isArray(value)) {
+          existing[field] = [...new Set([...(existing[field] ?? []), ...value])];
+        } else if (existing[field] === undefined) {
+          existing[field] = value;
+        } else if (JSON.stringify(existing[field]) !== JSON.stringify(value)) {
+          throw new CliError(
+            `${where}: ${grant.capability} '${key}' is used with both ${field} ${existing[field]} and ${value}`
+            + " — a package uses one",
+          );
+        }
+      }
+    }
+    if (grant.also) this.apply(grant.also, values, where, by);
+  }
+
+  /** Values a `requires_declared` grant collected for `capability`. */
+  required(capability) {
+    return (this.declared.get(capability) ?? []).map((item) => item.value);
+  }
+
+  /** The compiled groups, as the release's sections: sets sorted, keyed
+   * entries sorted by key with their array fields sorted. */
+  release() {
+    const capabilities = {};
+    const shell = {};
+    for (const { target, value } of this.groups.values()) {
+      let compiled;
+      if (value.values) compiled = [...value.values].sort();
+      else if (value.fields) {
+        compiled = Object.fromEntries([...value.fields].map(([field, set]) => [field, [...set].sort()]));
+      } else if (value.entries) {
+        const entries = [...value.entries].sort(([left], [right]) => (
+          String(left) < String(right) ? -1 : String(left) > String(right) ? 1 : 0
+        )).map(([key, entry]) => [key, Object.fromEntries(Object.entries(entry).map(
+          ([field, item]) => [field, Array.isArray(item) ? [...item].sort() : item],
+        ))]);
+        compiled = value.keyedObject ? Object.fromEntries(entries) : entries.map(([, entry]) => entry);
+      } else {
+        compiled = value.set;
+      }
+      let holder = target.section === "shell" ? shell : capabilities;
+      for (const segment of target.path.slice(0, -1)) {
+        holder[segment] ??= {};
+        holder = holder[segment];
+      }
+      holder[target.path.at(-1)] = compiled;
+    }
+    return { capabilities, shell };
+  }
+}
+
+/** What a call's non-literal arguments are called in a refusal. The table
+ * names each argument; these read the way a maker thinks of them. */
+const LITERAL_HINTS = {
+  horizontal: "a literal capability id and integer version",
+  connectors: "a literal connector slug",
+  services: "a literal artifact address and operation id",
+  egress: "a literal template name",
+  collect: "a literal channel name",
+  server: "a literal op name so Terminus can compile its grant",
+};
+
+function literalRefusal(file, call, argument) {
+  const [surface] = call.split(".");
+  if (call === "horizontal.invoke" && argument === "operation") {
+    return new CliError(`${file}: horizontal.invoke needs a literal operation id so Terminus can compile its grant`);
+  }
+  return new CliError(`${file}: ${call} must use ${LITERAL_HINTS[surface] ?? "literal arguments"}`);
+}
+
+/**
+ * Every table call in one file: each literal call site is handed to `onCall`
+ * (for the prose checks) and then applies its grant; a call — or a bare
+ * reference to a method whose grant needs literals — without them fails the
+ * build. `skip(row)` leaves out the rows a check excludes for this file.
+ */
+export function compileFileCalls(file, code, grants, { onCall = () => {}, skip = () => false } = {}) {
+  for (const row of CAPABILITY_CALLS.calls) {
+    if (skip(row)) continue;
+    const [surface, method] = row.call.split(".");
+    for (const binding of sdkSurfaceBindings(code, surface)) {
+      const prefix = `\\b${escapeRegExp(binding)}\\s*\\.\\s*${escapeRegExp(method)}`;
+      const calls = new RegExp(`${prefix}\\s*(?:<[^;()]*>)?\\s*\\(`, "gu");
+      const resolved = new Set();
+      for (const match of code.matchAll(calls)) {
+        const literals = leadingLiterals(code, match.index + match[0].length, row.literal_args.length);
+        const values = {};
+        for (const [position, argument] of row.literal_args.entries()) {
+          const literal = literals[position];
+          if (!literal || literal.kind !== argument.kind) {
+            throw literalRefusal(file, row.call, argument.name);
+          }
+          if (!new RegExp(argument.pattern, "u").test(literal.text)) {
+            if (row.call === "server.call") {
+              throw new CliError(
+                `${file}: server.call("${literal.text}") — op names are lowercase identifiers (a-z, 0-9, _ and -)`,
+              );
+            }
+            throw literalRefusal(file, row.call, argument.name);
+          }
+          values[argument.name] = argument.kind === "integer" ? Number(literal.text) : literal.text;
+        }
+        resolved.add(match.index);
+        onCall(row, values);
+        grants.apply(row.grant, values, file);
+      }
+      if (!row.literal_args.length) continue;
+      for (const match of code.matchAll(new RegExp(`${prefix}\\b`, "gu"))) {
+        if (!resolved.has(match.index)) throw literalRefusal(file, row.call, row.literal_args[0].name);
+      }
+    }
+  }
+}
+
+/** The automation steps the table compiles, with literal string params. A
+ * templated param (`{ $from }`) names nothing knowable, so it compiles no
+ * grant — the release's own validation refuses what it must. `skip` names
+ * actions the caller compiles itself (server.run, whose `unless` is prose). */
+export function compileWorkloadSteps(workloads, grants, { skip = [] } = {}) {
+  const rows = new Map(CAPABILITY_CALLS.workload_steps.map((row) => [row.action, row]));
+  for (const automation of Array.isArray(workloads?.automations) ? workloads.automations : []) {
+    for (const step of Array.isArray(automation?.steps) ? automation.steps : []) {
+      const row = rows.get(step?.action);
+      if (!row || skip.includes(row.action)) continue;
+      const values = {};
+      const literal = Object.entries(row.params).every(([name, type]) => {
+        const value = step.params?.[name];
+        if (type === "string" && typeof value === "string") {
+          values[name] = value;
+          return true;
+        }
+        return false;
+      });
+      if (literal) grants.apply(row.grant, values, `automation '${automation.name}'`);
+    }
+  }
+}
+
+/** The background entry a `server.run` step compiles for an op the app never
+ * calls itself (the table's `unless` keeps a called op's interactive `{}`). */
+export function serverRunEntry() {
+  return structuredClone(
+    CAPABILITY_CALLS.workload_steps.find((row) => row.action === "server.run").grant.entry,
+  );
+}
+
+const SERVER_RECORD_CALLS = CAPABILITY_CALLS.server_calls
+  .find((row) => row.call.startsWith("terminus.records."));
+
+/** The server-code record calls: `terminus.records.<verb>("<scope>",
+ * "<collection>", …)`, literal both, each compiled into server.records. */
+export function compileServerRecordCalls(sources) {
+  const [binding, verbs] = [
+    SERVER_RECORD_CALLS.call.split(".").slice(0, 2).join("."),
+    SERVER_RECORD_CALLS.call.split(".").at(-1).split("|"),
+  ];
+  const [scopeArgument, collectionArgument] = SERVER_RECORD_CALLS.literal_args;
+  const grants = new CompiledGrants();
+  const prefix = `\\b${binding.split(".").map(escapeRegExp).join("\\s*\\.\\s*")}\\s*\\.\\s*(${verbs.join("|")})`;
+  for (const source of sources) {
+    const code = maskCodeComments(source.code);
+    const resolved = new Set();
+    for (const match of code.matchAll(new RegExp(`${prefix}\\s*\\(`, "gu"))) {
+      const verb = match[1];
+      const literals = leadingLiterals(code, match.index + match[0].length, 2);
+      if (literals.length < 2 || literals.some((literal) => literal.kind !== "string")) continue;
+      const [scope, collection] = literals.map((literal) => literal.text);
+      if (!new RegExp(scopeArgument.pattern, "u").test(scope)) {
+        throw new CliError(
+          `${source.path}: terminus.records.${verb}("${scope}", …) — the scope is "global" or "installation"`,
+        );
+      }
+      if (!new RegExp(collectionArgument.pattern, "u").test(collection)) {
+        throw new CliError(
+          `${source.path}: terminus.records.${verb}(…, "${collection}") — collection names are lowercase identifiers`,
+        );
+      }
+      resolved.add(match.index);
+      grants.apply(SERVER_RECORD_CALLS.grant, { scope, collection }, source.path);
+    }
+    for (const match of code.matchAll(new RegExp(`${prefix}\\b`, "gu"))) {
+      if (!resolved.has(match.index)) {
+        throw new CliError(
+          `${source.path}: terminus.records.${match[1]} must name its scope and collection literally — `
+          + `terminus.records.${match[1]}("global", "scores", …) — so Terminus can compile its grant`,
+        );
+      }
+    }
+  }
+  return grants.release().capabilities.server?.records ?? null;
+}

package/bin/capsule-data.mjs

@@ -0,0 +1,260 @@
+import { randomUUID } from "node:crypto";
+import {
+  copyFile,
+  cp,
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+import { backup, DatabaseSync } from "node:sqlite";
+
+import { readAppPackage } from "./apps.mjs";
+import { CliError, commandUsageError, emitJson, parseFlags } from "./client.mjs";
+import { devCapsuleDirectory } from "./dev-capsules.mjs";
+import { DEFAULT_DEV_MEMBER } from "./dev-members.mjs";
+import { DEV_DIRECTORY, exists, sha256 } from "./files.mjs";
+
+// Plain `terminus dev` runs as one member, Alan — so that is whose capsule
+// these commands read and write unless --member names somebody else.
+function memberName(flags) {
+  return String(flags.member ?? DEFAULT_DEV_MEMBER).trim() || DEFAULT_DEV_MEMBER;
+}
+
+/** The members that have a local capsule for this app, for error messages. */
+async function localMembers(context) {
+  const usersDir = path.join(context.projectDir, DEV_DIRECTORY, "users");
+  let names = [];
+  try {
+    names = await readdir(usersDir);
+  } catch {
+    return [];
+  }
+  const found = [];
+  for (const name of names.sort()) {
+    const devRoot = path.join(context.projectDir, DEV_DIRECTORY);
+    if (await exists(devCapsuleDirectory(devRoot, context.appId, name))) found.push(name);
+  }
+  return found;
+}
+
+async function missingCapsuleError(context) {
+  const members = await localMembers(context);
+  const hint = members.length
+    ? `members with local data: ${members.join(", ")} (pass --member NAME)`
+    : "run terminus dev first";
+  return new CliError(`no local capsule for member '${context.member}'; ${hint}`);
+}
+
+async function capsuleContext(flags) {
+  const projectDir = path.resolve(flags._[0] ?? ".");
+  // Only the package identity is needed — never read the tree's content.
+  const pkg = await readAppPackage(projectDir, { allowMissingUi: true, includeContent: false });
+  if (pkg.manifest.kind !== "app" || !pkg.id) {
+    throw new CliError("capsule commands require an app package with a canonical terminus.json id");
+  }
+  const member = memberName(flags);
+  const devRoot = path.join(projectDir, DEV_DIRECTORY);
+  return {
+    projectDir,
+    appId: pkg.id,
+    member,
+    directory: devCapsuleDirectory(devRoot, pkg.id, member),
+  };
+}
+
+function openCapsuleDatabase(directory) {
+  const file = path.join(directory, "data.sqlite");
+  try {
+    return new DatabaseSync(file, { readOnly: true });
+  } catch (error) {
+    throw new CliError(`cannot open capsule database: ${error.message}`);
+  }
+}
+
+async function summarizeCapsule(directory, { verifyObjects = false } = {}) {
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(path.join(directory, "manifest.json"), "utf8"));
+  } catch (error) {
+    throw new CliError(`invalid capsule manifest: ${error.message}`);
+  }
+  if (manifest.capsule_format_version !== 1) {
+    throw new CliError(`unsupported capsule format ${manifest.capsule_format_version ?? "unknown"}`);
+  }
+
+  const db = openCapsuleDatabase(directory);
+  try {
+    const integrity = String(db.prepare("PRAGMA integrity_check").get().integrity_check);
+    if (integrity !== "ok") throw new CliError(`capsule SQLite integrity check failed: ${integrity}`);
+    const records = Number(db.prepare("SELECT COUNT(*) AS n FROM _terminus_records").get().n);
+    const changes = Number(db.prepare("SELECT COUNT(*) AS n FROM _terminus_changes").get().n);
+    const mutations = Number(db.prepare("SELECT COUNT(*) AS n FROM _terminus_mutations").get().n);
+    const objects = db.prepare(`
+      SELECT content_sha256, size_bytes FROM _terminus_object_refs ORDER BY content_sha256
+    `).all();
+    let objectBytes = 0;
+    const verified = new Set();
+    for (const object of objects) {
+      const hash = String(object.content_sha256);
+      objectBytes += Number(object.size_bytes);
+      if (!verifyObjects || verified.has(hash)) continue;
+      const file = path.join(directory, "objects", "sha256", hash.slice(0, 2), hash.slice(2, 4), hash);
+      let bytes;
+      try {
+        bytes = await readFile(file);
+      } catch {
+        throw new CliError(`capsule object ${hash} is missing`);
+      }
+      const actual = sha256(bytes);
+      if (actual !== hash) throw new CliError(`capsule object ${hash} failed its SHA-256 check`);
+      verified.add(hash);
+    }
+    return {
+      format: manifest.capsule_format_version,
+      app_id: manifest.app_id,
+      owner_user_id: manifest.owner_user_id,
+      records,
+      retained_changes: changes,
+      committed_mutations: mutations,
+      object_references: objects.length,
+      object_bytes: objectBytes,
+      integrity,
+      objects_verified: verifyObjects ? verified.size : null,
+      directory,
+    };
+  } finally {
+    db.close();
+  }
+}
+
+async function inspectCommand(flags) {
+  const context = await capsuleContext(flags);
+  if (!(await exists(context.directory))) throw await missingCapsuleError(context);
+  const summary = await summarizeCapsule(context.directory, { verifyObjects: flags.verify });
+  emitJson(flags, summary, () => {
+    console.log(`${summary.app_id} · ${summary.owner_user_id}`);
+    console.log(`Records: ${summary.records}`);
+    console.log(`Objects: ${summary.object_references} (${summary.object_bytes} bytes)`);
+    console.log(`SQLite integrity: ${summary.integrity}`);
+    if (flags.verify) console.log(`Verified object blobs: ${summary.objects_verified}`);
+    console.log(`Capsule: ${summary.directory}`);
+  });
+}
+
+async function exportCommand(flags) {
+  const context = await capsuleContext(flags);
+  if (!(await exists(context.directory))) throw await missingCapsuleError(context);
+  const target = path.resolve(
+    flags.output ?? flags._[1] ?? path.join(context.projectDir, `${context.member}-capsule`),
+  );
+  if (await exists(target)) throw new CliError(`export target already exists: ${target}`);
+
+  const staging = `${target}.tmp-${randomUUID()}`;
+  await mkdir(staging, { recursive: true });
+  try {
+    const sourceDb = openCapsuleDatabase(context.directory);
+    try {
+      await backup(sourceDb, path.join(staging, "data.sqlite"));
+    } finally {
+      sourceDb.close();
+    }
+    await copyFile(path.join(context.directory, "manifest.json"), path.join(staging, "manifest.json"));
+    const objects = path.join(context.directory, "objects");
+    if (await exists(objects)) await cp(objects, path.join(staging, "objects"), { recursive: true });
+    else await mkdir(path.join(staging, "objects"), { recursive: true });
+    const summary = await summarizeCapsule(staging, { verifyObjects: true });
+    const { directory: _directory, ...portableSummary } = summary;
+    await writeFile(
+      path.join(staging, "export.json"),
+      `${JSON.stringify({ exported_at: new Date().toISOString(), ...portableSummary }, null, 2)}\n`,
+      { mode: 0o600 },
+    );
+    await rename(staging, target);
+    const result = { ...summary, directory: target };
+    emitJson(flags, result, () => {
+      console.log(`Exported ${context.appId} / ${context.member} to ${target}`);
+    });
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+async function importCommand(flags) {
+  // One argument is the capsule (the app is the current folder); two are the
+  // app folder and then the capsule.
+  const [first, second] = flags._;
+  const capsule = second ?? first;
+  if (!capsule) throw commandUsageError("data", { sub: "import" });
+  const source = path.resolve(capsule);
+  const summary = await summarizeCapsule(source, { verifyObjects: true });
+  // Without --member, the capsule goes back to the member it came from.
+  const context = await capsuleContext({
+    ...flags,
+    _: second ? [first] : [],
+    member: flags.member ?? summary.owner_user_id,
+  });
+  if (summary.app_id !== context.appId) {
+    throw new CliError(`capsule belongs to ${summary.app_id}, not ${context.appId}`);
+  }
+  if (summary.owner_user_id !== context.member) {
+    throw new CliError(
+      `capsule belongs to member '${summary.owner_user_id}', not '${context.member}' (set --member)`,
+    );
+  }
+  if (await exists(context.directory)) {
+    const entries = await readdir(context.directory);
+    if (entries.length && !flags.force) {
+      throw new CliError("local capsule already exists; pass --force to replace it with a recoverable backup");
+    }
+  }
+
+  const parent = path.dirname(context.directory);
+  await mkdir(parent, { recursive: true });
+  const staging = path.join(parent, `.import-${randomUUID()}`);
+  await cp(source, staging, { recursive: true });
+  try {
+    await summarizeCapsule(staging, { verifyObjects: true });
+    let backupDirectory = null;
+    if (await exists(context.directory)) {
+      backupDirectory = `${context.directory}.backup-${new Date().toISOString().replaceAll(":", "-")}`;
+      await rename(context.directory, backupDirectory);
+    }
+    try {
+      await rename(staging, context.directory);
+    } catch (error) {
+      if (backupDirectory) await rename(backupDirectory, context.directory);
+      throw error;
+    }
+    const result = { ...summary, directory: context.directory, backup: backupDirectory };
+    emitJson(flags, result, () => {
+      console.log(`Imported ${context.appId} / ${context.member} into ${context.directory}`);
+      if (backupDirectory) console.log(`Previous capsule: ${backupDirectory}`);
+    });
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export async function dataCommand(args) {
+  const [verb, ...rest] = args;
+  const flags = parseFlags(rest, "data");
+  switch (verb) {
+    case "inspect":
+      await inspectCommand(flags);
+      break;
+    case "export":
+      await exportCommand(flags);
+      break;
+    case "import":
+      await importCommand(flags);
+      break;
+    default:
+      throw commandUsageError("data", verb ? { reason: `'${verb}' is not a data command.` } : {});
+  }
+}