@plenary/cli 0.3.0

package/dist/index.js

@@ -0,0 +1,1043 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync as readFileSync5 } from "fs";
+import { Command, CommanderError as CommanderError2 } from "commander";
+
+// src/output.ts
+import { PlenaryError } from "@plenary/client";
+import { CommanderError } from "commander";
+
+// src/errors.ts
+var CliError = class extends Error {
+  exitCode;
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+};
+function usageError(message) {
+  return new CliError(message, 2);
+}
+
+// src/output.ts
+function formatTable(rows, header) {
+  const all = header ? [header, ...rows] : rows;
+  if (all.length === 0) return "";
+  const widths = [];
+  for (const row of all) {
+    row.forEach((cell, i) => {
+      widths[i] = Math.max(widths[i] ?? 0, cell.length);
+    });
+  }
+  return all.map(
+    (row) => row.map((cell, i) => i === row.length - 1 ? cell : cell.padEnd(widths[i] ?? 0)).join("  ").trimEnd()
+  ).join("\n");
+}
+function toJson(value) {
+  return JSON.stringify(value, null, 2);
+}
+function describeError(err, debug = false) {
+  if (err instanceof PlenaryError) {
+    let line = `plenary: ${err.code} (HTTP ${err.status})`;
+    if (err.vars && Object.keys(err.vars).length > 0) {
+      line += "\n" + Object.entries(err.vars).map(([k, v]) => `  ${k}: ${fmtVar(v)}`).join("\n");
+    }
+    return line;
+  }
+  if (err instanceof CliError) return `plenary: ${err.message}`;
+  if (err instanceof Error) {
+    const cause = err.cause instanceof Error ? `: ${err.cause.message}` : "";
+    return debug && err.stack ? err.stack : `plenary: ${err.message}${cause}`;
+  }
+  return `plenary: ${String(err)}`;
+}
+function exitCodeFor(err) {
+  if (err instanceof CliError) return err.exitCode;
+  if (err instanceof CommanderError) return err.exitCode === 0 ? 0 : 2;
+  return 1;
+}
+function fmtVar(v) {
+  return typeof v === "string" ? v : JSON.stringify(v);
+}
+
+// src/config.ts
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+var CONFIG_FILE = "plenary.json";
+var DEFAULT_METADATA_DIR = "plenary";
+function findConfigFile(from) {
+  let dir = path.resolve(from);
+  for (; ; ) {
+    const candidate = path.join(dir, CONFIG_FILE);
+    if (existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+var CONFIG_KEYS = ["baseUrl", "siteKey", "locale", "metadataDir"];
+function readProjectConfig(file) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (err) {
+    throw usageError(`${file}: ${err.message}`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw usageError(`${file}: expected a JSON object`);
+  }
+  const out = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (!CONFIG_KEYS.includes(key)) {
+      throw usageError(`${file}: unknown key "${key}"`);
+    }
+    if (typeof value !== "string") {
+      throw usageError(`${file}: "${key}" must be a string`);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+function readDotEnv(file) {
+  const out = {};
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return out;
+  }
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const m = /^(?:export\s+)?(PLENARY_[A-Z0-9_]+)=(.*)$/.exec(line);
+    if (!m) continue;
+    let value = (m[2] ?? "").trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    out[m[1]] = value;
+  }
+  return out;
+}
+function resolveContext(opts, io) {
+  const configPath = opts.config ? path.resolve(io.cwd, opts.config) : findConfigFile(io.cwd);
+  if (opts.config && !existsSync(configPath)) {
+    throw usageError(`config file not found: ${configPath}`);
+  }
+  const file = configPath ? readProjectConfig(configPath) : {};
+  const projectRoot = configPath ? path.dirname(configPath) : io.cwd;
+  const env = { ...readDotEnv(path.join(projectRoot, ".env")), ...pick(io.env) };
+  const baseUrl = opts.baseUrl ?? env.PLENARY_BASE_URL ?? file.baseUrl;
+  return {
+    io,
+    baseUrl: baseUrl ? baseUrl.replace(/\/+$/, "") : void 0,
+    apiKey: opts.apiKey ?? env.PLENARY_API_KEY,
+    siteKey: opts.site ?? env.PLENARY_SITE_KEY ?? file.siteKey,
+    locale: opts.locale ?? env.PLENARY_LOCALE ?? file.locale,
+    metadataDir: env.PLENARY_METADATA_DIR ?? file.metadataDir ?? DEFAULT_METADATA_DIR,
+    projectRoot,
+    configPath,
+    json: opts.json ?? false,
+    debug: opts.debug ?? false
+  };
+}
+function pick(env) {
+  const out = {};
+  for (const [k, v] of Object.entries(env)) {
+    if (k.startsWith("PLENARY_") && v !== void 0 && v !== "") out[k] = v;
+  }
+  return out;
+}
+function requireBaseUrl(ctx) {
+  if (!ctx.baseUrl) {
+    throw usageError(
+      "no base URL: pass --base-url, set PLENARY_BASE_URL, or run `plenary init`"
+    );
+  }
+  return ctx.baseUrl;
+}
+function requireApiKey(ctx) {
+  if (!ctx.apiKey) {
+    throw usageError("no credential: pass --api-key or set PLENARY_API_KEY");
+  }
+  return ctx.apiKey;
+}
+
+// src/api/http.ts
+import { errorFromResponse } from "@plenary/client";
+function apiPath(p) {
+  return p.startsWith("/") ? p : `/api/v1/${p}`;
+}
+async function request(ctx, method, path6, opts = {}) {
+  const base = requireBaseUrl(ctx);
+  const auth = opts.auth ?? "required";
+  const headers = { ...opts.headers };
+  if (auth === "required") headers["X-API-KEY"] = requireApiKey(ctx);
+  else if (auth === "optional" && ctx.apiKey) headers["X-API-KEY"] = ctx.apiKey;
+  const url = new URL(base + apiPath(path6));
+  for (const [k, v] of Object.entries(opts.query ?? {})) {
+    if (v !== void 0) url.searchParams.set(k, v);
+  }
+  let body;
+  if (opts.form) {
+    body = opts.form;
+  } else if (opts.body !== void 0) {
+    headers["Content-Type"] = "application/json";
+    body = JSON.stringify(opts.body);
+  }
+  if (ctx.debug) ctx.io.stderr.write(`> ${method} ${url}
+`);
+  const response = await ctx.io.fetch(url, { method, headers, body });
+  const data = await parseBody(response);
+  if (ctx.debug) ctx.io.stderr.write(`< ${response.status}
+`);
+  if (!response.ok && !opts.allowError) {
+    throw errorFromResponse(response.status, data);
+  }
+  return { status: response.status, ok: response.ok, headers: response.headers, data };
+}
+async function parseBody(response) {
+  if (response.status === 204) return null;
+  const text = await response.text();
+  if (text === "") return null;
+  const type = response.headers.get("content-type") ?? "";
+  if (type.includes("json")) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  return text;
+}
+
+// src/input.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { createInterface } from "readline/promises";
+function parsePairs(pairs, sep, what) {
+  const out = {};
+  for (const pair of pairs) {
+    const i = pair.indexOf(sep);
+    if (i <= 0) throw usageError(`invalid ${what} "${pair}": expected key${sep}value`);
+    out[pair.slice(0, i).trim()] = pair.slice(i + 1).trim();
+  }
+  return out;
+}
+async function readText(data, stdin) {
+  if (data === "-") return readStream(stdin);
+  if (data.startsWith("@")) {
+    try {
+      return readFileSync2(data.slice(1), "utf8");
+    } catch (err) {
+      throw usageError(`cannot read ${data.slice(1)}: ${err.message}`);
+    }
+  }
+  return data;
+}
+async function readData(data, stdin, flag = "--data") {
+  const text = await readText(data, stdin);
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw usageError(`${flag} is not valid JSON: ${err.message}`);
+  }
+}
+async function readObject(data, stdin, flag = "--data") {
+  const value = await readData(data, stdin, flag);
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw usageError(`${flag} must be a JSON object`);
+  }
+  return value;
+}
+async function readStream(stream) {
+  const chunks = [];
+  for await (const chunk of stream) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function confirm(io, question, yes) {
+  if (yes) return;
+  if (!io.isTTY) throw usageError(`${question} \u2014 pass -y to confirm without a terminal`);
+  const rl = createInterface({ input: io.stdin, output: io.stderr });
+  try {
+    const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
+    if (answer !== "y" && answer !== "yes") throw usageError("aborted");
+  } finally {
+    rl.close();
+  }
+}
+
+// src/commands/api.ts
+import { errorFromResponse as errorFromResponse2 } from "@plenary/client";
+var METHODS = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
+function collect(value, previous) {
+  return [...previous, value];
+}
+function registerApi(program, io) {
+  program.command("api").description("Call any API endpoint and print the response body").argument("<method>", "GET, POST, PUT, PATCH, DELETE, or HEAD").argument("<path>", "a path such as models or /api/v1/models").option("-d, --data <json>", "request body: inline JSON, @file, or - for stdin").option("-q, --query <key=value>", "query parameter (repeatable)", collect, []).option("-H, --header <key:value>", "request header (repeatable)", collect, []).option("-i, --include", "print the status line and response headers to stderr").addHelpText(
+    "after",
+    `
+Examples:
+  plenary api GET models
+  plenary api GET content/post -q site_key=main -q limit=5
+  plenary api POST content/post -q site_key=main -d '{"fields":{"title":"Hello"}}'
+  plenary api PUT models/<uuid> -d @model.json`
+  ).action(
+    async (methodArg, path6, opts, cmd) => {
+      const ctx = resolveContext(cmd.optsWithGlobals(), io);
+      const method = methodArg.toUpperCase();
+      if (!METHODS.has(method)) throw usageError(`unsupported method "${methodArg}"`);
+      const body = opts.data !== void 0 ? await readData(opts.data, io.stdin) : void 0;
+      const res = await request(ctx, method, path6, {
+        query: parsePairs(opts.query, "=", "query parameter"),
+        headers: parsePairs(opts.header, ":", "header"),
+        body,
+        auth: "optional",
+        allowError: true
+      });
+      if (opts.include) {
+        io.stderr.write(`HTTP ${res.status}
+`);
+        res.headers.forEach((v, k) => io.stderr.write(`${k}: ${v}
+`));
+        io.stderr.write("\n");
+      }
+      if (res.data !== null) {
+        io.stdout.write((typeof res.data === "string" ? res.data : toJson(res.data)) + "\n");
+      }
+      if (!res.ok) {
+        io.stderr.write(describeError(errorFromResponse2(res.status, res.data)) + "\n");
+        throw new CliError("", 1);
+      }
+    }
+  );
+}
+
+// src/commands/catalog.ts
+function registerCatalog(program, io, name) {
+  const group = program.command(name).description(name === "models" ? "Content models and objects" : "Forms");
+  group.command("list").description(`List ${name}`).action(async (_opts, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const res = await request(ctx, "GET", name);
+    if (ctx.json) {
+      io.stdout.write(toJson(res.data) + "\n");
+      return;
+    }
+    const rows = res.data.map((m) => [
+      m.key,
+      m.kind,
+      m.name_singular,
+      String(m.fields_count),
+      m.active ? "" : "inactive"
+    ]);
+    io.stdout.write(formatTable(rows, ["KEY", "KIND", "NAME", "FIELDS", ""]) + "\n");
+  });
+  group.command("get").description(`Show one of the ${name} by key or id`).argument("<key>").option("--yaml", "print the YAML file the metadata commands use").action(async (key, opts, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const res = await request(ctx, "GET", `${name}/${encodeURIComponent(key)}`);
+    const m = res.data;
+    if (opts.yaml) {
+      const yaml = await request(ctx, "GET", `${name}/${m.id}/yaml`);
+      io.stdout.write(yaml.data.endsWith("\n") ? yaml.data : yaml.data + "\n");
+      return;
+    }
+    if (ctx.json) {
+      io.stdout.write(toJson(m) + "\n");
+      return;
+    }
+    const head = [
+      ["Key", m.key],
+      ["Kind", m.kind],
+      ["Name", `${m.name_singular} / ${m.name_plural}`],
+      ["Id", m.id],
+      ["Sites", (m.sites ?? []).join(", ") || "-"],
+      ["Active", m.active ? "yes" : "no"]
+    ];
+    if (m.description) head.push(["Description", m.description]);
+    if (m.entry_count !== void 0) head.push(["Entries", String(m.entry_count)]);
+    const fields = m.fields.map((f) => [
+      f.key,
+      f.type,
+      f.name,
+      [f.required ? "required" : "", f.localized ? "localized" : ""].filter(Boolean).join(", ")
+    ]);
+    io.stdout.write(
+      formatTable(head) + "\n\n" + formatTable(fields, ["FIELD", "TYPE", "NAME", ""]) + "\n"
+    );
+  });
+  return group;
+}
+
+// src/entries/client.ts
+import { createClient } from "@plenary/client";
+function requireSiteKey(ctx) {
+  if (!ctx.siteKey) {
+    throw usageError("no site key: pass --site, set PLENARY_SITE_KEY, or set siteKey in plenary.json");
+  }
+  return ctx.siteKey;
+}
+async function resolveLocale(ctx, siteKey) {
+  if (ctx.locale) return ctx.locale;
+  const sites = await request(ctx, "GET", "sites");
+  const site = sites.data.find((s) => s.key === siteKey);
+  if (!site) throw usageError(`site "${siteKey}" not found on the instance`);
+  return site.default_locale;
+}
+async function contentClient(ctx) {
+  const siteKey = requireSiteKey(ctx);
+  return createClient({
+    baseUrl: requireBaseUrl(ctx),
+    siteKey,
+    apiKey: requireApiKey(ctx),
+    locale: await resolveLocale(ctx, siteKey),
+    fetch: ctx.io.fetch
+  });
+}
+
+// src/entries/query.ts
+var OPERATORS = /* @__PURE__ */ new Set(["$eq", "$ne", "$lt", "$lte", "$gt", "$gte", "$in", "$nin", "$like", "$ilike", "$is_null"]);
+function parseWhere(specs) {
+  const where = {};
+  for (const spec of specs) {
+    const eq = spec.indexOf("=");
+    if (eq <= 0) throw usageError(`invalid --where "${spec}": expected field=value or field=$op:value`);
+    const field = spec.slice(0, eq).trim();
+    const raw = spec.slice(eq + 1);
+    if (!raw.startsWith("$")) {
+      where[field] = raw;
+      continue;
+    }
+    const colon = raw.indexOf(":");
+    const op = colon === -1 ? raw : raw.slice(0, colon);
+    const value = colon === -1 ? "" : raw.slice(colon + 1);
+    if (!OPERATORS.has(op)) throw usageError(`invalid --where "${spec}": unknown operator ${op}`);
+    let typed = value;
+    if (op === "$in" || op === "$nin") typed = value.split(",").map((s) => s.trim()).filter(Boolean);
+    else if (op === "$is_null") typed = value === "" || value === "true";
+    const existing = where[field] ?? {};
+    where[field] = { ...typeof existing === "object" ? existing : {}, [op]: typed };
+  }
+  return where;
+}
+function parseSort(specs) {
+  const sort = {};
+  for (const spec of specs) {
+    const [field, dir = "asc"] = spec.split(":");
+    if (!field || dir !== "asc" && dir !== "desc") {
+      throw usageError(`invalid --sort "${spec}": expected field or field:asc|desc`);
+    }
+    sort[field] = dir;
+  }
+  return sort;
+}
+function parseHydrate(specs) {
+  const out = {};
+  for (const spec of specs) {
+    const [field, list] = spec.split("=");
+    if (!field) throw usageError(`invalid --hydrate "${spec}"`);
+    out[field] = list === void 0 || list === "*" ? "*" : list.split(",");
+  }
+  return out;
+}
+function parseInt10(value, flag) {
+  if (value === void 0) return void 0;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) throw usageError(`${flag} must be a non-negative integer`);
+  return n;
+}
+async function toReadOptions(flags) {
+  const opts = {};
+  if (flags.include) opts.include = flags.include.split(",");
+  if (flags.exclude) opts.exclude = flags.exclude.split(",");
+  if (flags.hydrate?.length) opts.hydrate = parseHydrate(flags.hydrate);
+  return opts;
+}
+async function toListOptions(flags, stdin) {
+  const opts = await toReadOptions(flags);
+  if (flags.where?.length && flags.filters) throw usageError("--where and --filters are mutually exclusive");
+  if (flags.where?.length) opts.where = parseWhere(flags.where);
+  if (flags.filters) opts.filters = await readData(flags.filters, stdin, "--filters");
+  if (flags.sort?.length) opts.sort = parseSort(flags.sort);
+  const limit = parseInt10(flags.limit, "--limit");
+  const offset = parseInt10(flags.offset, "--offset");
+  if (limit !== void 0) opts.limit = limit;
+  if (offset !== void 0) opts.offset = offset;
+  if (flags.count) opts.count = true;
+  return opts;
+}
+
+// src/commands/entries.ts
+function collect2(value, previous) {
+  return [...previous, value];
+}
+function withListFlags(cmd) {
+  return cmd.option("-w, --where <field=value>", "filter: field=value or field=$op:value (repeatable)", collect2, []).option("--filters <json>", "a filter tree (inline JSON, @file, or -); excludes --where").option("-s, --sort <field[:dir]>", "sort field, asc unless :desc (repeatable, in precedence order)", collect2, []).option("--limit <n>", "page size").option("--offset <n>", "rows to skip").option("--include <fields>", "comma-separated data fields to return").option("--exclude <fields>", "comma-separated data fields to omit").option("--hydrate <field[=subfields]>", "hydrate a reference field (repeatable)", collect2, []).option("--count", "ask for the total and show it");
+}
+function withWriteFlags(cmd) {
+  return cmd.option("-d, --data <json>", "the field values as a JSON object (inline, @file, or -)").option("--slug <slug>").option("--folder <id>", "content folder id").option("--note <text>", "revision note (required by models with Require Change Notes)").option("--publish-at <iso>", "schedule a publish").option("--unpublish-at <iso>", "schedule an unpublish");
+}
+function entryRow(e) {
+  return [e.id, e.status, e.slug ?? "", e.title ?? "", e.updated_at];
+}
+var ENTRY_HEADER = ["ID", "STATUS", "SLUG", "TITLE", "UPDATED"];
+var PAGE = 100;
+async function* pageAll(client, model, opts) {
+  const limit = opts.limit ?? PAGE;
+  let offset = opts.offset ?? 0;
+  for (; ; ) {
+    const { items } = await client.listEntries(model, { ...opts, limit, offset, count: false });
+    for (const e of items) yield e;
+    if (items.length < limit) return;
+    offset += items.length;
+  }
+}
+async function publish(ctx, id, action) {
+  return (await request(ctx, "POST", `content/${encodeURIComponent(id)}/${action}`)).data;
+}
+function registerEntries(program, io) {
+  const entries = program.command("entries").description("Content entries");
+  withListFlags(entries.command("list").description("List a model's entries").argument("<model>")).action(
+    async (model, flags, cmd) => {
+      const ctx = resolveContext(cmd.optsWithGlobals(), io);
+      const client = await contentClient(ctx);
+      const result = await client.listEntries(model, await toListOptions(flags, io.stdin));
+      if (ctx.json) {
+        io.stdout.write(toJson(result) + "\n");
+        return;
+      }
+      io.stdout.write(formatTable(result.items.map(entryRow), ENTRY_HEADER) + "\n");
+      if (result.total !== void 0) io.stdout.write(`${result.items.length} of ${result.total}
+`);
+    }
+  );
+  entries.command("get").description("Print one entry as JSON; omit the slug for a singleton").argument("<model>").argument("[slug-or-id]").option("--include <fields>").option("--exclude <fields>").option("--hydrate <field[=subfields]>", "hydrate a reference field (repeatable)", collect2, []).action(async (model, slug, flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const client = await contentClient(ctx);
+    const opts = await toReadOptions(flags);
+    const entry = slug === void 0 ? await client.getSingleton(model, opts) : await client.getEntry(model, slug, opts);
+    io.stdout.write(toJson(entry) + "\n");
+  });
+  withWriteFlags(entries.command("create").description("Create a draft entry").argument("<model>")).option("--publish", "publish it right after creating").action(async (model, flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const siteKey = requireSiteKey(ctx);
+    if (flags.data === void 0) throw usageError("--data is required");
+    const body = { fields: await readObject(flags.data, io.stdin) };
+    if (ctx.locale) body.locale = ctx.locale;
+    applyWriteFlags(body, flags);
+    let entry = (await request(ctx, "POST", `content/${encodeURIComponent(model)}`, { query: { site_key: siteKey }, body })).data;
+    if (flags.publish) entry = await publish(ctx, entry.id, "publish");
+    report(ctx, entry, "created");
+  });
+  withWriteFlags(
+    entries.command("update").description("Update an entry: --data is merged into its fields (a null removes one)").argument("<model>").argument("<slug-or-id>")
+  ).action(async (model, slug, flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const client = await contentClient(ctx);
+    const current = await client.getEntry(model, slug);
+    const fields = { ...current.data };
+    if (flags.data !== void 0) {
+      for (const [k, v] of Object.entries(await readObject(flags.data, io.stdin))) {
+        if (v === null) delete fields[k];
+        else fields[k] = v;
+      }
+    }
+    const body = {
+      fields,
+      slug: current.slug ?? void 0,
+      locale: current.locale ?? void 0,
+      folder_id: current.folder_id,
+      publish_at: current.publish_at,
+      unpublish_at: current.unpublish_at
+    };
+    applyWriteFlags(body, flags);
+    const entry = (await request(ctx, "PUT", `content/${encodeURIComponent(current.id)}`, { body })).data;
+    report(ctx, entry, "updated");
+  });
+  entries.command("delete").description("Delete an entry (recoverable from history while the model tracks revisions)").argument("<id>").option("--note <text>", "revision note").option("-y, --yes", "do not ask").action(async (id, flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    await confirm(io, `Delete entry ${id}?`, Boolean(flags.yes));
+    await request(ctx, "DELETE", `content/${encodeURIComponent(id)}`, { query: { note: flags.note } });
+    if (ctx.json) io.stdout.write(toJson({ id, deleted: true }) + "\n");
+    else io.stdout.write(`deleted ${id}
+`);
+  });
+  for (const action of ["publish", "unpublish"]) {
+    entries.command(action).description(`${action === "publish" ? "Publish" : "Unpublish"} an entry now`).argument("<id>").action(async (id, _flags, cmd) => {
+      const ctx = resolveContext(cmd.optsWithGlobals(), io);
+      report(ctx, await publish(ctx, id, action), action === "publish" ? "published" : "unpublished");
+    });
+  }
+  withListFlags(
+    entries.command("export").description("Write every matching entry to stdout as NDJSON").argument("<model>")
+  ).action(async (model, flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const client = await contentClient(ctx);
+    for await (const e of pageAll(client, model, await toListOptions(flags, io.stdin))) {
+      io.stdout.write(JSON.stringify(e) + "\n");
+    }
+  });
+  entries.command("import").description("Create one entry per NDJSON line (exported entries or {fields, slug, \u2026} bodies)").argument("<model>").argument("<file>", "a file, or - for stdin").option("--publish", "publish each entry after creating it").addHelpText(
+    "after",
+    `
+Every line is tried; a line that fails is reported with its number and the
+run continues, exiting 1 at the end if any failed.`
+  ).action(async (model, file, flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const siteKey = requireSiteKey(ctx);
+    const text = await readText(file === "-" ? "-" : `@${file}`, io.stdin);
+    let failed = 0;
+    let n = 0;
+    for (const raw of text.split("\n")) {
+      const line = raw.trim();
+      if (line === "") continue;
+      n++;
+      try {
+        const body = importBody(JSON.parse(line), ctx);
+        let entry = (await request(ctx, "POST", `content/${encodeURIComponent(model)}`, {
+          query: { site_key: siteKey },
+          body
+        })).data;
+        if (flags.publish) entry = await publish(ctx, entry.id, "publish");
+        io.stdout.write(`ok    ${entry.id}${entry.slug ? `  ${entry.slug}` : ""}
+`);
+      } catch (err) {
+        failed++;
+        const why = err instanceof Error ? err.code ?? err.message : String(err);
+        io.stdout.write(`fail  line ${n}: ${why}
+`);
+      }
+    }
+    io.stderr.write(`${n - failed} created, ${failed} failed
+`);
+    if (failed) throw new CliError("", 1);
+  });
+}
+function applyWriteFlags(body, flags) {
+  if (flags.slug !== void 0) body.slug = flags.slug;
+  if (flags.folder !== void 0) body.folder_id = flags.folder;
+  if (flags.publishAt !== void 0) body.publish_at = flags.publishAt;
+  if (flags.unpublishAt !== void 0) body.unpublish_at = flags.unpublishAt;
+  if (flags.note !== void 0) body.note = flags.note;
+}
+function importBody(line, ctx) {
+  if ("fields" in line) return line;
+  if (!("data" in line)) throw usageError("expected an object with fields or data");
+  const e = line;
+  const body = { fields: e.data ?? {} };
+  if (e.slug) body.slug = e.slug;
+  if (e.locale ?? ctx.locale) body.locale = e.locale ?? ctx.locale;
+  if (e.folder_id) body.folder_id = e.folder_id;
+  if (e.publish_at) body.publish_at = e.publish_at;
+  if (e.unpublish_at) body.unpublish_at = e.unpublish_at;
+  return body;
+}
+function report(ctx, entry, verb) {
+  if (ctx.json) ctx.io.stdout.write(toJson(entry) + "\n");
+  else ctx.io.stdout.write(`${verb} ${entry.id}${entry.slug ? `  ${entry.slug}` : ""}  (${entry.status})
+`);
+}
+
+// src/commands/formentries.ts
+function collect3(value, previous) {
+  return [...previous, value];
+}
+function toQuery(ctx, opts) {
+  const q = {};
+  if (ctx.siteKey) q.site_key = ctx.siteKey;
+  for (const [field, value] of Object.entries(opts.where ?? {})) {
+    if (typeof value === "object" && value !== null) {
+      for (const [op, v] of Object.entries(value)) {
+        q[`where:${field}.${op}`] = Array.isArray(v) ? v.join(",") : String(v);
+      }
+    } else {
+      q[`where:${field}`] = String(value);
+    }
+  }
+  if (opts.filters) q.filters = JSON.stringify(opts.filters);
+  for (const [field, dir] of Object.entries(opts.sort ?? {})) q[`sort:${field}`] = dir;
+  if (opts.limit !== void 0) q.limit = String(opts.limit);
+  if (opts.offset !== void 0) q.offset = String(opts.offset);
+  if (opts.count) q.count = "true";
+  return q;
+}
+var PAGE2 = 100;
+function registerFormEntries(forms, io) {
+  const entries = forms.command("entries").description("Form entries (what visitors submitted)");
+  const listFlags = (cmd) => cmd.option("-w, --where <field=value>", "filter: field=value or field=$op:value (repeatable)", collect3, []).option("--filters <json>", "a filter tree (inline JSON, @file, or -)").option("-s, --sort <field[:dir]>", "sort field, asc unless :desc (repeatable)", collect3, []).option("--limit <n>").option("--offset <n>").option("--count", "ask for the total and show it");
+  listFlags(entries.command("list").description("List a form's entries").argument("<form>")).action(
+    async (form, flags, cmd) => {
+      const ctx = resolveContext(cmd.optsWithGlobals(), io);
+      const opts = await toListOptions(flags, io.stdin);
+      const res = await request(ctx, "GET", `forms/${encodeURIComponent(form)}/entries`, {
+        query: toQuery(ctx, opts)
+      });
+      const total = res.headers.get("X-Total-Count");
+      if (ctx.json) {
+        io.stdout.write(toJson({ items: res.data, ...total !== null ? { total: Number(total) } : {} }) + "\n");
+        return;
+      }
+      const rows = res.data.map((e) => [e.id, e.status, e.site_key, e.created_at, summary(e.data)]);
+      io.stdout.write(formatTable(rows, ["ID", "STATUS", "SITE", "CREATED", "DATA"]) + "\n");
+      if (total !== null) io.stdout.write(`${res.data.length} of ${total}
+`);
+    }
+  );
+  listFlags(entries.command("export").description("Write every matching entry to stdout as NDJSON").argument("<form>")).action(
+    async (form, flags, cmd) => {
+      const ctx = resolveContext(cmd.optsWithGlobals(), io);
+      const opts = await toListOptions(flags, io.stdin);
+      const limit = opts.limit ?? PAGE2;
+      let offset = opts.offset ?? 0;
+      for (; ; ) {
+        const res = await request(ctx, "GET", `forms/${encodeURIComponent(form)}/entries`, {
+          query: toQuery(ctx, { ...opts, limit, offset, count: false })
+        });
+        for (const e of res.data) io.stdout.write(JSON.stringify(e) + "\n");
+        if (res.data.length < limit) return;
+        offset += res.data.length;
+      }
+    }
+  );
+}
+function summary(data) {
+  return Object.entries(data).slice(0, 3).map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`).join(" ");
+}
+
+// src/commands/media.ts
+import { readFileSync as readFileSync3 } from "fs";
+import path2 from "path";
+function size(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function registerMedia(program, io) {
+  const media = program.command("media").description("Media library");
+  media.command("upload").description("Upload one or more files").argument("<files...>").option("--folder <id>", "media folder id").option("--private", "store as a private asset").action(async (files, flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const uploaded = [];
+    let failed = 0;
+    for (const file of files) {
+      let bytes;
+      try {
+        bytes = readFileSync3(file);
+      } catch (err) {
+        throw usageError(`cannot read ${file}: ${err.message}`);
+      }
+      const form = new FormData();
+      form.append("upload_file", new Blob([new Uint8Array(bytes)]), path2.basename(file));
+      if (flags.folder) form.append("folder_id", flags.folder);
+      if (flags.private) form.append("visibility", "private");
+      try {
+        const res = await request(ctx, "POST", "media", { form });
+        uploaded.push(res.data);
+        if (!ctx.json) io.stdout.write(`${res.data.media_id}  ${res.data.file_name}
+`);
+      } catch (err) {
+        if (files.length === 1) throw err;
+        failed++;
+        const code = err.code ?? err.message;
+        io.stdout.write(`fail  ${file}: ${code}
+`);
+      }
+    }
+    if (ctx.json) io.stdout.write(toJson(uploaded) + "\n");
+    if (failed) throw new CliError("", 1);
+  });
+  media.command("list").description("List media").option("--search <text>", "match file names and captions").option("--path <prefix>", "only assets under this folder path").option("--limit <n>").option("--page <n>").action(async (flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const res = await request(ctx, "GET", "media", {
+      query: { search: flags.search, path_prefix: flags.path, limit: flags.limit, page: flags.page }
+    });
+    if (ctx.json) {
+      io.stdout.write(toJson(res.data) + "\n");
+      return;
+    }
+    const rows = res.data.map((m) => [m.media_id, m.media_type, m.file_name, size(m.file_size), m.path, m.visibility]);
+    io.stdout.write(formatTable(rows, ["ID", "TYPE", "FILE", "SIZE", "PATH", "VISIBILITY"]) + "\n");
+  });
+  media.command("get").description("Print one media item as JSON").argument("<id>").action(async (id, _flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const res = await request(ctx, "GET", `media/${encodeURIComponent(id)}`);
+    io.stdout.write(toJson(res.data) + "\n");
+  });
+}
+
+// src/commands/metadata.ts
+import path4 from "path";
+
+// src/metadata/dir.ts
+import { existsSync as existsSync2, mkdirSync, readdirSync, readFileSync as readFileSync4, writeFileSync } from "fs";
+import path3 from "path";
+var MANAGED_DIRS = ["models", "forms"];
+function readTree(root) {
+  const out = [];
+  for (const rel of managedFiles(root)) {
+    out.push({ path: rel, content: readFileSync4(path3.join(root, rel), "utf8") });
+  }
+  return out;
+}
+function writeTree(root, files) {
+  const before = new Set(managedFiles(root));
+  const written = [];
+  for (const f of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
+    if (!isTreePath(f.path)) continue;
+    const abs = path3.join(root, f.path);
+    mkdirSync(path3.dirname(abs), { recursive: true });
+    writeFileSync(abs, f.content);
+    written.push(f.path);
+    before.delete(f.path);
+  }
+  return { written, stale: [...before].sort() };
+}
+function isTreePath(p) {
+  const parts = p.split("/");
+  return parts.length === 2 && MANAGED_DIRS.includes(parts[0]) && parts[1].endsWith(".yaml");
+}
+function managedFiles(root) {
+  const out = [];
+  for (const dir of MANAGED_DIRS) {
+    const abs = path3.join(root, dir);
+    if (!existsSync2(abs)) continue;
+    for (const name of readdirSync(abs).sort()) {
+      if (name.endsWith(".yaml")) out.push(`${dir}/${name}`);
+    }
+  }
+  return out.sort();
+}
+
+// src/metadata/plan.ts
+function formatPlan(result, verbose = false) {
+  const lines = [];
+  let creates = 0;
+  let updates = 0;
+  let noops = 0;
+  for (const c of result.changes) {
+    if (c.action === "create") creates++;
+    else if (c.action === "update") updates++;
+    else noops++;
+    if (c.action === "noop" && !verbose) continue;
+    const label = c.action === "noop" ? "unchanged" : c.action;
+    lines.push(`${label.padEnd(9)} ${c.kind.padEnd(10)} ${c.key}${detail(c)}`);
+  }
+  const counts = `${creates} to create, ${updates} to update, ${noops} unchanged`;
+  if (creates + updates === 0) lines.push(`No changes: ${noops} unchanged.`);
+  else lines.push(result.applied ? `Applied: ${counts}.` : `Plan: ${counts}.`);
+  return lines.join("\n");
+}
+function detail(c) {
+  const d = c.detail;
+  if (!d) return "";
+  const parts = [];
+  if (d.fields_added.length) parts.push(`+${d.fields_added.join(",")}`);
+  if (d.fields_changed.length) parts.push(`~${d.fields_changed.join(",")}`);
+  if (d.fields_removed.length) parts.push(`-${d.fields_removed.join(",")}`);
+  if (d.attributes_changed) parts.push("settings");
+  if (d.transformers_changed) parts.push("transformers");
+  return parts.length ? `  (${parts.join(" ")})` : "";
+}
+
+// src/commands/metadata.ts
+function treeRoot(ctx, opts) {
+  return opts.dir ? path4.resolve(ctx.io.cwd, opts.dir) : path4.resolve(ctx.projectRoot, ctx.metadataDir);
+}
+function readTreeOrFail(root) {
+  const files = readTree(root);
+  if (files.length === 0) throw usageError(`no YAML files under ${root}/models or ${root}/forms`);
+  return files;
+}
+async function runImport(ctx, root, apply, verbose) {
+  const files = readTreeOrFail(root);
+  const res = await request(ctx, "POST", "metadata/models/import", { body: { files, apply } });
+  if (ctx.json) ctx.io.stdout.write(toJson(res.data) + "\n");
+  else ctx.io.stdout.write(formatPlan(res.data, verbose) + "\n");
+}
+function registerMetadata(program, io) {
+  const metadata = program.command("metadata").description("Keep a directory of model and form YAML in step with the instance").addHelpText(
+    "after",
+    `
+The tree is models/<key>.yaml and forms/<key>.yaml under the metadata
+directory ("metadataDir" in plenary.json, default ./plenary). See
+docs/CONTENT_MODELS.md, "YAML import and export".`
+  );
+  metadata.command("pull").description("Write every model and form the key may read into the directory").option("--dir <path>", "metadata directory (default: the configured one)").action(async (opts, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const root = treeRoot(ctx, opts);
+    const res = await request(ctx, "GET", "metadata/models");
+    const result = writeTree(root, res.data.files);
+    if (ctx.json) {
+      io.stdout.write(toJson({ dir: root, ...result }) + "\n");
+      return;
+    }
+    io.stdout.write(`wrote ${result.written.length} file${result.written.length === 1 ? "" : "s"} to ${root}
+`);
+    if (result.written.length === 0) {
+      io.stderr.write("the server sent no models: the key may lack content:models:read (a public key never has it)\n");
+    }
+    if (result.stale.length) {
+      io.stdout.write(`not on the server (left in place):
+${result.stale.map((p) => `  ${p}`).join("\n")}
+`);
+    }
+  });
+  metadata.command("diff").description("Preview what push would change, without writing anything").option("--dir <path>", "metadata directory (default: the configured one)").option("--verbose", "list unchanged models too").action(async (opts, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    await runImport(ctx, treeRoot(ctx, opts), false, Boolean(opts.verbose));
+  });
+  metadata.command("push").description("Apply the directory to the instance (creates and updates; never deletes)").option("--dir <path>", "metadata directory (default: the configured one)").option("--dry-run", "same as diff").option("--verbose", "list unchanged models too").action(async (opts, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    await runImport(ctx, treeRoot(ctx, opts), !opts.dryRun, Boolean(opts.verbose));
+  });
+}
+
+// src/commands/init.ts
+import { existsSync as existsSync3, writeFileSync as writeFileSync2 } from "fs";
+import path5 from "path";
+import { createInterface as createInterface2 } from "readline/promises";
+function registerInit(program, io) {
+  program.command("init").description(`Write a ${CONFIG_FILE} for this project (never a credential)`).option("--dir <path>", "metadata directory, relative to the config file", DEFAULT_METADATA_DIR).option("-f, --force", `overwrite an existing ${CONFIG_FILE}`).addHelpText(
+    "after",
+    `
+The base URL, site and locale come from --base-url, --site and --locale (or
+their PLENARY_* variables); anything missing is prompted for on a terminal.`
+  ).action(async (opts, cmd) => {
+    const target = path5.join(io.cwd, CONFIG_FILE);
+    if (existsSync3(target) && !opts.force) {
+      throw usageError(`${target} already exists (pass --force to overwrite)`);
+    }
+    const globals = cmd.optsWithGlobals();
+    const ctx = resolveContext({ ...globals, config: void 0 }, { ...io, cwd: path5.parse(io.cwd).root });
+    const baseUrl = globals.baseUrl ?? ctx.baseUrl ?? await ask(io, "Base URL (https://cms.example.com)");
+    if (!baseUrl) throw usageError("a base URL is required: pass --base-url or set PLENARY_BASE_URL");
+    const siteKey = globals.site ?? ctx.siteKey ?? await ask(io, "Site key", "default");
+    const locale = globals.locale ?? ctx.locale ?? await ask(io, "Locale", "en-us");
+    const config = { baseUrl: baseUrl.replace(/\/+$/, "") };
+    if (siteKey) config.siteKey = siteKey;
+    if (locale) config.locale = locale;
+    if (opts.dir !== DEFAULT_METADATA_DIR) config.metadataDir = opts.dir;
+    writeFileSync2(target, JSON.stringify(config, null, 2) + "\n");
+    io.stdout.write(`wrote ${target}
+`);
+  });
+}
+async function ask(io, label, fallback) {
+  if (!io.isTTY) return fallback;
+  const rl = createInterface2({ input: io.stdin, output: io.stderr });
+  try {
+    const answer = (await rl.question(fallback ? `${label} [${fallback}]: ` : `${label}: `)).trim();
+    return answer === "" ? fallback : answer;
+  } finally {
+    rl.close();
+  }
+}
+
+// src/commands/status.ts
+import { PlenaryError as PlenaryError2 } from "@plenary/client";
+function registerStatus(program, io) {
+  program.command("status").description("Show the instance's health and which credential this run holds").action(async (_opts, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const health = await request(ctx, "GET", "/api/v1/health", { auth: "none", allowError: true });
+    let me;
+    let credentialError;
+    let undescribed = false;
+    if (ctx.apiKey) {
+      try {
+        me = (await request(ctx, "GET", "/api/v1/auth/me")).data;
+      } catch (err) {
+        if (!(err instanceof PlenaryError2)) throw err;
+        if (err.status === 403) undescribed = true;
+        else credentialError = err;
+      }
+    }
+    const failed = !health.ok || credentialError !== void 0;
+    if (ctx.json) {
+      io.stdout.write(
+        toJson({
+          base_url: ctx.baseUrl,
+          health: health.data,
+          credential: me ?? null,
+          credential_error: credentialError ? { status: credentialError.status, code: credentialError.code } : null
+        }) + "\n"
+      );
+      if (failed) throw new CliError("", 1);
+      return;
+    }
+    const lines = [`Instance   ${ctx.baseUrl}`];
+    if (health.ok || health.status === 503 && typeof health.data === "object") {
+      const h = health.data;
+      lines.push(`Version    ${h.version} (${h.edition})`);
+      lines.push(`Status     ${h.status}, database ${h.database}${h.license ? `, license ${h.license}` : ""}`);
+    } else {
+      lines.push(`Status     unreachable (HTTP ${health.status})`);
+    }
+    if (me?.principal === "api_key") {
+      lines.push(`Credential ${me.key_type} API key "${me.name}" (${me.grants.length} grant${me.grants.length === 1 ? "" : "s"}${me.sites.length ? `, sites ${me.sites.join(", ")}` : ""})`);
+    } else if (me?.principal === "user") {
+      lines.push(`Credential user session, role ${me.role_name ?? me.role}`);
+    } else if (credentialError) {
+      lines.push(`Credential rejected: ${credentialError.code} (HTTP ${credentialError.status})`);
+    } else if (undescribed) {
+      lines.push("Credential API key accepted (this server predates API-key support on /auth/me and cannot describe the key)");
+    } else {
+      lines.push("Credential none (set PLENARY_API_KEY or pass --api-key)");
+    }
+    if (ctx.configPath) lines.push(`Config     ${ctx.configPath}`);
+    io.stdout.write(lines.join("\n") + "\n");
+    if (failed) throw new CliError("", 1);
+  });
+}
+
+// src/cli.ts
+function version() {
+  try {
+    const pkg = JSON.parse(readFileSync5(new URL("../package.json", import.meta.url), "utf8"));
+    return pkg.version;
+  } catch {
+    return "0.0.0";
+  }
+}
+function createProgram(io) {
+  const program = new Command("plenary").description("Command-line client for the Plenary API").version(version(), "-v, --version").option("--base-url <url>", "instance URL (PLENARY_BASE_URL)").option("--api-key <key>", "API key (PLENARY_API_KEY)").option("--site <key>", "site key (PLENARY_SITE_KEY)").option("--locale <code>", "locale (PLENARY_LOCALE)").option("--config <path>", "plenary.json to use (default: nearest, searching upward)").option("--json", "print machine-readable JSON").option("--debug", "print requests and stack traces to stderr").showHelpAfterError("(run with --help for usage)").exitOverride().configureOutput({
+    writeOut: (s) => io.stdout.write(s),
+    writeErr: (s) => io.stderr.write(s)
+  });
+  registerInit(program, io);
+  registerStatus(program, io);
+  registerMetadata(program, io);
+  registerCatalog(program, io, "models");
+  registerFormEntries(registerCatalog(program, io, "forms"), io);
+  registerEntries(program, io);
+  registerMedia(program, io);
+  registerApi(program, io);
+  return program;
+}
+async function run(argv, io) {
+  const program = createProgram(io);
+  try {
+    await program.parseAsync(argv, { from: "user" });
+    return 0;
+  } catch (err) {
+    if (err instanceof CommanderError2) {
+      return exitCodeFor(err);
+    }
+    const debug = Boolean(program.opts().debug);
+    const message = describeError(err, debug);
+    if (message !== "plenary: ") io.stderr.write(message + "\n");
+    return exitCodeFor(err);
+  }
+}
+
+// src/index.ts
+run(process.argv.slice(2), {
+  stdout: process.stdout,
+  stderr: process.stderr,
+  stdin: process.stdin,
+  env: process.env,
+  cwd: process.cwd(),
+  fetch: globalThis.fetch,
+  isTTY: Boolean(process.stdin.isTTY)
+}).then((code) => {
+  process.exitCode = code;
+});
+//# sourceMappingURL=index.js.map