@thinger-io/cli-core 0.4.2 → 0.5.0

package/lib/commands/resources.js

@@ -0,0 +1,975 @@
+// @ts-check
+import { writeFile } from 'node:fs/promises';
+import { CATALOG, ancestry, idKey, idKeys, idNames } from '../mcp/catalog.js';
+import { textResult } from '../mcp/helpers.js';
+import { CLI, DATA, resourceTools } from '../mcp/tools-resource.js';
+import { inputError } from '../errors.js';
+import { identity } from '../identity.js';
+import { classifyError, isJsonMode, printErr, printOk } from '../output.js';
+import {
+    applyJsonFlag,
+    collectKeyString,
+    collectKeyValue,
+    confirmDestructive,
+    ensureConfigured,
+    extractField,
+    getGlobalUser,
+    parseJsonValue,
+    parseNonNegativeInt,
+    parsePositiveInt,
+    bodyFromOptions,
+    bodyOptions,
+} from './_shared.js';
+
+/**
+ * The generic resource commands: `<cli> <noun> [<noun>…] list|get|create|
+ * update|delete|clone|describe|set|<action>` for every type of the catalog
+ * the MCP serves, run by the same handlers as the `resource_*` tools (hooks
+ * included), so a type added to the catalog reaches both at once.
+ *
+ * A type's noun is its name without its parent's, nested under the
+ * parent's command (`device property`, `device bucket tag`); server types
+ * go under `admin`. Ids are positional, outermost parent first, each named
+ * after its noun (`<device> <property>`). A command written by hand wins:
+ * a generated verb whose name a group already has is left out.
+ */
+
+/** Verbs a type may have, in the order the help shows them. */
+const VERBS = /** @type {const} */ (['list', 'get', 'create', 'update', 'delete', 'clone']);
+
+/** Verbs that move data rather than records: their actions go under "Data:". */
+export const DATA_VERBS = [
+    'read',
+    'write',
+    'send',
+    'export',
+    'import',
+    'overview',
+    'call',
+    'upload',
+    'download',
+];
+
+const kebab = (name) => name.replaceAll('_', '-');
+
+/**
+ * Nouns of the types whose command is not their name without the parent's:
+ * the product profile categories go under `product profile`, alarms and
+ * assets under `alarm` and `asset`, and the export files of a bucket are
+ * `export-file` (`bucket export` downloads its data).
+ */
+const NOUN = {
+    alarm_rule: ['alarm', 'rule'],
+    alarm_instance: ['alarm', 'instance'],
+    asset_type: ['asset', 'type'],
+    asset_group: ['asset', 'group'],
+    product_profile_api: ['profile', 'api'],
+    product_profile_bucket: ['profile', 'bucket'],
+    product_profile_property: ['profile', 'property'],
+    product_profile_autoprovision: ['profile', 'autoprovision'],
+    product_profile_flow: ['profile', 'flow'],
+    product_profile_code: ['profile', 'code'],
+    bucket_export: ['export-file'],
+};
+
+/** Actions whose command is not the catalog's name in kebab case. */
+const ACTION_NAME = {
+    'alarm_rule.test_rule': 'test',
+    'host.read_settings': 'get-settings',
+    'plugin.remove': 'uninstall',
+};
+
+/** Groups that are not types, with their description. */
+export const GROUP_DESCRIPTIONS = {
+    alarm: 'Alarms: the rules that watch devices and buckets, and the instances they raise',
+    asset: 'Assets: types and groups that organize devices',
+    admin: 'Server administration (admin accounts): users, hosts, domains, brands…',
+    'product profile':
+        'Profile of a product: the API resources, buckets, properties, autoprovisioning, flows and code its devices get',
+    'device resource': "Resources of a connected device: its firmware's API and its product's",
+    'storage file': 'Files of a file storage',
+    doc: 'Guides for agents and app developers: the platform, product code, the dashboard SDK, this CLI',
+};
+
+/**
+ * Types whose records have a name and a description: their create and
+ * update take `-n` and `-d` (a test checks the set against the server's
+ * API).
+ */
+export const NAMED_FIELDS = new Set([
+    'device',
+    'product',
+    'bucket',
+    'dashboard',
+    'endpoint',
+    'storage',
+    'asset_type',
+    'asset_group',
+    'project',
+    'token',
+    'alarm_rule',
+    'alarm_instance',
+    'claim',
+    'property',
+    'sync',
+    'domain',
+    'brand',
+    'oauth_client',
+    'identity_provider',
+    'proxy',
+    'sync_lock',
+    'device_property',
+    'product_property',
+    'product_profile_api',
+    'product_profile_bucket',
+    'product_profile_property',
+    'product_profile_autoprovision',
+    'product_profile_flow',
+    'product_service',
+    'plugin_property',
+    'asset_type_property',
+    'asset_group_property',
+    'project_property',
+]);
+
+/** Command a type lives under: `alarm rule`, `device bucket tag`, `admin user`. */
+export function commandPath(type) {
+    const spec = CATALOG[type];
+    const own = NOUN[type] ?? [kebab(spec.parent ? type.slice(spec.parent.length + 1) : type)];
+    if (spec.parent) return [...commandPath(spec.parent), ...own];
+    return spec.scope === 'server' ? ['admin', ...own] : own;
+}
+
+/** Command of an action: `test` for alarm_rule's test_rule, `test-source`… */
+export const actionName = (type, action) => ACTION_NAME[`${type}.${action}`] ?? kebab(action);
+
+/**
+ * Argument names of a type's own ids: `<asset-type>`, `<property>`,
+ * `<file>`. They are the names the tools take in `ids`, in kebab case.
+ */
+export function idArgs(type) {
+    const key = idKey(type);
+    return key ? [kebab(key)] : [];
+}
+
+/** Argument names of a type's parents, outermost first. */
+export const parentArgs = (type) => ancestry(type).flatMap(idArgs);
+
+/** Type at a command path ('device property' → device_property). */
+export const TYPE_AT = new Map(Object.keys(CATALOG).map((t) => [commandPath(t).join(' '), t]));
+
+/** How a type reads in the help: "device property", "oauth-client". */
+const noun = (type) =>
+    commandPath(type)
+        .filter((n, i) => i || n !== 'admin')
+        .join(' ');
+
+/**
+ * The catalog's description for a command line: what names MCP tools
+ * (sentences, or remarks in parentheses) and the form of a `parent` id is
+ * for agents; the command line takes the parent ids one by one.
+ */
+export function cliDescription(text) {
+    return cliWording(text)
+        .replace(/\s*\([^)]*\btools?\b[^)]*\)/g, '')
+        .replace(/\s*\(parent: [^)]*\)/g, '')
+        .replace(/`body`/g, 'the body')
+        .split(/(?<=\.)\s+/)
+        .filter((s) => !s.includes('{tool:') && !/^Confirm with the user\b/.test(s))
+        .join(' ')
+        .trim()
+        .replace(/\.$/, '');
+}
+
+/**
+ * Commands of the operations of the core's types and actions (data,
+ * files, device resources, guides, apps): written by hand, not generated.
+ */
+export const CORE_COMMANDS = {
+    'bucket_data.list': 'bucket read',
+    'bucket_data.create': 'bucket write',
+    'storage_file.list': 'storage file list',
+    'storage_file.get': 'storage file download',
+    'storage_file.create': 'storage file upload',
+    'storage_file.update': 'storage file upload',
+    'storage_file.delete': 'storage file delete',
+    'device_resource.list': 'device resource list',
+    'device_resource.call': 'device resource call',
+    'device.overview': 'device overview',
+    'product_profile_api.call': 'product profile api call',
+    'plugin.call': 'plugin call',
+    'dashboard.init': 'dashboard init',
+    'dashboard.dev': 'dashboard dev',
+    'dashboard.publish': 'dashboard publish',
+    'doc.list': 'doc list',
+    'doc.get': 'doc get',
+    'profile.list': 'profile list',
+};
+
+/** The command of an operation (a type's verb or action): `device property list`. */
+function opCommand(type, op) {
+    const core = CORE_COMMANDS[`${type}.${op}`];
+    if (core) return core;
+    const spec = CATALOG[type];
+    if (!spec) return undefined;
+    if (spec.actions?.[op]) return `${commandPath(type).join(' ')} ${actionName(type, op)}`;
+    if (op in spec.ops || op === 'describe') return `${commandPath(type).join(' ')} ${op}`;
+    return undefined;
+}
+
+/** The command doing what tool `base` does, `type` the resource the text is about. */
+function commandFor(base, type) {
+    const verb = base.match(/^resource_(\w+)$/)?.[1];
+    if (!verb) return undefined;
+    // The texts point to describe for other types ("describe of any type").
+    const own = type && type in CATALOG && verb !== 'describe';
+    const at = own ? commandPath(type).join(' ') : '<noun>';
+    return `\`${identity().name} ${at} ${verb === 'call' ? '<action>' : verb}\``;
+}
+
+/**
+ * A text the commands share with the MCP tools, for a command line: the
+ * operations it names (`{op:type.verb}`, or the call written out:
+ * `<prefix>_resource_list type "x"`, ids after it as the positional
+ * arguments) and the tools (`{tool:x}`) as the commands that do the same,
+ * and their arguments as options. Operations without a command stay as
+ * they are.
+ *
+ * @param {string} text
+ * @param {string} [type]  The resource the text is about.
+ */
+export function cliWording(text, type) {
+    const prefix = identity().mcp.toolPrefix;
+    const tool = `(?:\\{tool:([a-z0-9_]+)\\}|\\b${prefix}_([a-z0-9_]+))`;
+    const op = new RegExp(
+        `(?:\\{op:([a-z0-9_]+)\\.([a-z0-9_]+)\\}|\\b${prefix}_resource_(\\w+) type "([a-z0-9_]+)"(?: action "([a-z0-9_]+)")?)(?: ids (\\{[^{}]*\\}))?`,
+        'g',
+    );
+    return text
+        .replace(op, (all, t1, op1, verb, t2, action, ids) => {
+            const words = opCommand(t1 ?? t2, op1 ?? action ?? verb);
+            if (!words) return all;
+            let values;
+            try {
+                values = ids ? Object.values(JSON.parse(ids)) : [];
+            } catch {
+                return all;
+            }
+            return `\`${identity().name} ${[words, ...values].join(' ')}\``;
+        })
+        .replace(new RegExp(tool, 'g'), (all, a, b) => commandFor(a ?? b, type) ?? all)
+        .replace(/\bpass index: (\d+)/g, 'pass --index $1')
+        .replace(/narrow it with filter\b/g, 'narrow it with --search or --filter');
+}
+
+/** The first sentence, for a line of help: the whole text goes after the options. */
+const firstSentence = (text) => text.split(/(?<=[.;:])\s+/)[0].replace(/[.;:]$/, '');
+
+/** Whether a command answers to `name`, by its name or an alias. */
+export const named = (cmd, name) => cmd.name() === name || cmd.aliases().includes(name);
+
+/**
+ * The group at `path` below `program`, made on the way when missing (with
+ * the type's description, or GROUP_DESCRIPTIONS'): groups written by hand
+ * keep theirs. Null when a segment is a command without subcommands, a
+ * CLI's own leaf: no group can go there.
+ *
+ * @param {import('commander').Command} program
+ * @param {string[]} path
+ */
+export function groupAt(program, path) {
+    let parent = program;
+    for (let i = 0; i < path.length; i++) {
+        const found = parent.commands.find((c) => named(c, path[i]));
+        if (found) {
+            if (!found.commands.length) return null;
+            parent = found;
+            continue;
+        }
+        const at = path.slice(0, i + 1).join(' ');
+        const type = TYPE_AT.get(at);
+        const top = path[0] === 'admin' ? 'Administration:' : 'Resources:';
+        parent = parent
+            .command(path[i])
+            .helpGroup(i ? 'Subresources:' : top)
+            .description(
+                type ? cliDescription(CATALOG[type].description) : (GROUP_DESCRIPTIONS[at] ?? ''),
+            );
+    }
+    return parent;
+}
+
+/** Describe the id arguments of a command on `type`: "ID of the alarm rule". */
+function describeIds(cmd, type) {
+    const help = new Map(
+        [...ancestry(type), type].flatMap((t) =>
+            idArgs(t).map((n) => [n, `ID of the ${t.replaceAll('_', ' ')}`]),
+        ),
+    );
+    help.set('new-id', 'ID of the copy');
+    help.set('value', 'Value, parsed as JSON (text when it is not JSON)');
+    for (const arg of cmd.registeredArguments) {
+        if (!arg.description) arg.description = help.get(arg.name()) ?? '';
+    }
+    return cmd;
+}
+
+/**
+ * `--search`, `--filter`, `--count` and `--index`: the options of every
+ * list, generated or written by hand.
+ *
+ * @param {import('commander').Command} cmd
+ */
+export function listOptions(cmd) {
+    return cmd
+        .option('--search <text>', 'Text to look for in ids and names')
+        .option(
+            '--filter <key=value>',
+            'Filter (repeatable): product, type, asset_type, asset_group, project, labels, or a field of the records',
+            collectKeyValue,
+        )
+        .option('--count <n>', 'Page size (default: all)', parsePositiveInt('count'))
+        .option('--index <n>', 'Offset of the first record', parseNonNegativeInt('index'));
+}
+
+/** Whether a list was given any of the listOptions. */
+export const hasListOptions = (opts) =>
+    ['search', 'filter', 'count', 'index'].some((o) => opts[o] !== undefined);
+
+/** The listOptions as resource_list takes them: every record unless --count. */
+function listArgs(opts) {
+    return {
+        ...(opts.search ? { search: opts.search } : {}),
+        ...(opts.filter ? { filter: opts.filter } : {}),
+        ...(opts.count ? { count: opts.count } : { all: true }),
+        ...(opts.index !== undefined ? { index: opts.index } : {}),
+    };
+}
+
+/** Handlers of the resource tools without a CLI's hooks, for the commands written by hand. */
+let plainTools;
+const plain = () =>
+    (plainTools ??= Object.fromEntries(resourceTools().map((t) => [t.name, t.handler])));
+
+/**
+ * The records of a list with the listOptions, through resource_list: what
+ * the lists written by hand show in their own table.
+ *
+ * @param {string} type
+ * @param {Record<string, any>} opts
+ * @param {string | null} [user]
+ */
+export async function listRecords(type, opts, user) {
+    const result = await plain().resource_list({
+        type,
+        ...listArgs(opts),
+        ...(user ? { user } : {}),
+        [CLI]: true,
+    });
+    return result[DATA] ?? [];
+}
+
+/** `--projects a@p1,b@p2` → ['a@p1', 'b@p2']. */
+const parseProjects = (list) =>
+    String(list)
+        .split(',')
+        .map((p) => p.trim())
+        .filter(Boolean);
+
+/** The `--projects` option of a create or update. */
+export const projectsOption = (cmd) =>
+    cmd.option('--projects <list>', 'Projects it belongs to, comma-separated "<owner>@<project>"');
+
+/**
+ * Set the projects of a record a command written by hand created
+ * (`--projects`), as the generated create does. A failure says the record
+ * is there all the same.
+ *
+ * @param {string} type
+ * @param {string} id
+ * @param {string} list  "<owner>@<project>", comma-separated.
+ * @param {string | null} [user]
+ */
+export async function setProjects(type, id, list, user) {
+    try {
+        await plain().resource_update({
+            type,
+            ids: { [/** @type {string} */ (idKey(type))]: id },
+            body: { projects: parseProjects(list) },
+            ...(user ? { user } : {}),
+        });
+    } catch (error) {
+        const { message, code } = classifyError(error);
+        throw Object.assign(
+            new Error(`${type} ${id} was created, but not its projects: ${message}`),
+            {
+                code,
+            },
+        );
+    }
+}
+
+/**
+ * Register the commands on `program`.
+ *
+ * @param {import('commander').Command} program
+ * @param {{
+ *   hooks?: Record<string, import('../mcp/resource-hooks.js').ResourceHooks>,
+ *   strict?: boolean,
+ * }} [opts]
+ *   `strict` (tests): a type whose path a CLI's own leaf takes throws,
+ *   instead of being left out (said on stderr with DEBUG set).
+ */
+export function registerResourceCommands(program, { hooks, strict = false } = {}) {
+    const tools = Object.fromEntries(resourceTools({ hooks }).map((t) => [t.name, t.handler]));
+
+    // Parents first: a child's group goes into its parent's.
+    const types = Object.keys(CATALOG).sort((a, b) => ancestry(a).length - ancestry(b).length);
+    for (const type of types) {
+        const spec = CATALOG[type];
+        const cmd = groupAt(program, commandPath(type));
+        if (!cmd) {
+            const message = `${commandPath(type).join(' ')}: a command of the CLI takes the place of the ${type} commands`;
+            if (strict) throw new Error(message);
+            if (process.env.DEBUG) process.stderr.write(`${message}\n`);
+            continue;
+        }
+        const has = (name) => cmd.commands.some((c) => named(c, name));
+
+        for (const verb of VERBS) {
+            if (verb in spec.ops && !has(verb)) addVerb(cmd, type, verb, tools);
+        }
+        if (spec.id === 'property' && 'update' in spec.ops && !has('set')) {
+            addVerb(cmd, type, 'set', tools);
+        }
+        if (!has('describe')) addDescribe(cmd, type, tools);
+        for (const [action, a] of Object.entries(spec.actions || {})) {
+            if (!has(actionName(type, action))) addAction(cmd, type, action, a, tools);
+        }
+    }
+}
+
+/**
+ * Positional arguments → the `ids` the tools take, by name: the parents',
+ * then the own one (`withId`; a create may leave it out).
+ */
+function locate(type, values, { withId }) {
+    const keys = idKeys(type);
+    const names = withId || !idKey(type) ? keys : keys.slice(0, -1);
+    /** @type {Record<string, string>} */
+    const ids = {};
+    names.forEach((key, i) => {
+        if (values[i] !== undefined && values[i] !== null) ids[key] = values[i];
+    });
+    return { ids };
+}
+
+/** How the ids of a call read in a question: `boiler/setpoint`. */
+const shown = (ids) => Object.values(ids).join('/');
+
+/** `<device> <bucket>`: commander's spelling of the arguments. */
+const argSpec = (names, optional = false) =>
+    names.map((n) => (optional ? `[${n}]` : `<${n}>`)).join(' ');
+
+/** Print the value `-f` picked: text as is, anything else as JSON; nothing when missing. */
+function printValue(value) {
+    if (value === undefined) return;
+    console.log(typeof value === 'string' ? value : JSON.stringify(value, null, 2));
+}
+
+/**
+ * Run an MCP tool handler as a command and print its answer: its text, or
+ * its data with --json.
+ *
+ * @param {(args: any) => any} handler
+ * @param {Record<string, any>} args
+ * @param {{ output?: string, field?: string }} [opts]  `output`: write the
+ *   answer (JSON) to this file; `field`: only this field (dot path) of it.
+ */
+export async function runTool(handler, args, { output, field } = {}) {
+    try {
+        const result = await handler({ ...args, [CLI]: true });
+        if (result?.isError) {
+            const message = result.content?.map((c) => c.text).join('\n') || 'failed';
+            printErr(message, { code: 'error' });
+            return;
+        }
+        let data = DATA in result ? result[DATA] : result.content?.map((c) => c.text).join('\n');
+        if (field !== undefined) data = extractField(data, field);
+        if (output) {
+            await writeFile(
+                output,
+                typeof data === 'string'
+                    ? data
+                    : data === null || data === undefined
+                      ? ''
+                      : `${JSON.stringify(data, null, 2)}\n`,
+            );
+            if (isJsonMode()) printOk({ file: output });
+            else process.stderr.write(`Saved to ${output}\n`);
+            return;
+        }
+        if (isJsonMode()) return printOk(data);
+        if (field !== undefined) return printValue(data);
+        for (const c of result.content || []) {
+            if (c.type === 'text') console.log(cliText(c.text, args.type));
+        }
+    } catch (error) {
+        const { message, code } = classifyError(error);
+        printErr(message, { code });
+    }
+}
+
+/**
+ * `set`: the value of a property, created when missing (an update first,
+ * then a create when the server has none).
+ */
+async function setValue(tools, args) {
+    try {
+        await tools.resource_update(args);
+    } catch (error) {
+        if (classifyError(error).code !== 'not_found') throw error;
+        await tools.resource_create(args);
+    }
+    const id = args.ids[/** @type {string} */ (idKey(args.type))];
+    const parent = idKeys(args.type)
+        .slice(0, -1)
+        .map((k) => args.ids[k])
+        .join('/');
+    const where = [parent, id].filter(Boolean).join('/');
+    return textResult(`Set ${noun(args.type)} ${where} to ${JSON.stringify(args.body.value)}.`, {
+        ...(parent ? { parent } : {}),
+        id,
+        value: args.body.value,
+    });
+}
+
+/** "an endpoint", "a device". */
+const article = (t) => `${/^[aeiou]/.test(t) ? 'an' : 'a'} ${t}`;
+
+const SUMMARY = {
+    list: (t) => `List ${t} records`,
+    get: (t) => `Show ${article(t)} as JSON`,
+    create: (t) => `Create ${article(t)} from --from and --set`,
+    update: (t) => `Update fields of ${article(t)} (fields left out are kept)`,
+    delete: (t) => `Delete ${article(t)}`,
+    clone: (t) => `Copy ${article(t)} under a new id`,
+    set: (t) => `Set the value of ${article(t)} (created when missing)`,
+};
+
+function addVerb(group, type, verb, tools) {
+    const spec = CATALOG[type];
+    const parents = parentArgs(type);
+    const ids = idArgs(type);
+    const what = noun(type);
+    // A create may take its id from the body, unless it is stored under it.
+    const optionalIds = verb === 'create' && !spec.upsert;
+    const usage = [
+        verb,
+        argSpec(parents),
+        verb === 'list' ? '' : argSpec(ids, optionalIds),
+        verb === 'clone' ? '<new-id>' : '',
+        verb === 'set' ? '<value>' : '',
+    ]
+        .filter(Boolean)
+        .join(' ');
+    const cmd = group
+        .command(usage)
+        .helpGroup('Records:')
+        .description(SUMMARY[verb](what))
+        .option('-j, --json', 'Output as JSON');
+    describeIds(cmd, type);
+
+    if (verb === 'list') listOptions(cmd);
+    if (['create', 'update', 'clone'].includes(verb) && NAMED_FIELDS.has(type)) {
+        cmd.option('-n, --name <name>', 'Name (over --from and --set)').option(
+            '-d, --description <text>',
+            'Description (over --from and --set)',
+        );
+    }
+    if (verb === 'create' || verb === 'update' || verb === 'clone') bodyOptions(cmd);
+    if ((verb === 'create' || verb === 'update') && 'projects' in spec.ops) projectsOption(cmd);
+    if (verb === 'update' && 'patch' in spec.ops) {
+        cmd.option('--merge', 'Patch the value (JSON merge) instead of replacing it');
+    }
+    if (verb === 'delete') cmd.option('-y, --yes', 'Do not ask for confirmation');
+    if (verb === 'get') {
+        cmd.option('-f, --field <path>', 'Print only this field (dot path, e.g. config.source)');
+        cmd.option('-o, --output <file>', 'Write the JSON to a file');
+    }
+
+    cmd.action(async (...params) => {
+        const command = params[params.length - 1];
+        const opts = params[params.length - 2];
+        const values = params.slice(0, -2);
+        applyJsonFlag(opts);
+        ensureConfigured();
+        const user = getGlobalUser(command);
+        try {
+            const where = locate(type, values, { withId: verb !== 'list' });
+            const base = { type, ids: where.ids, ...(user ? { user } : {}) };
+            if (verb === 'list')
+                return runTool(tools.resource_list, { ...base, ...listArgs(opts) });
+            if (verb === 'get') {
+                return runTool(tools.resource_get, base, {
+                    output: opts.output,
+                    field: opts.field,
+                });
+            }
+            if (verb === 'delete') {
+                const ok = await confirmDestructive(opts, `Delete ${what} ${shown(where.ids)}?`);
+                if (ok) await runTool(tools.resource_delete, base);
+                return;
+            }
+            if (verb === 'set') {
+                const value = parseJsonValue(values[values.length - 1]);
+                return runTool((args) => setValue(tools, args), { ...base, body: { value } });
+            }
+            let body = (await bodyFromOptions(opts)) ?? {};
+            // Only a create may take several records (an array of properties).
+            if (verb !== 'create' && (typeof body !== 'object' || Array.isArray(body))) {
+                throw inputError(`${verb} takes a JSON object`);
+            }
+            const fields = {
+                ...(opts.name !== undefined ? { name: opts.name } : {}),
+                ...(opts.description !== undefined ? { description: opts.description } : {}),
+                ...(opts.projects ? { projects: parseProjects(opts.projects) } : {}),
+            };
+            if (Object.keys(fields).length) {
+                if (typeof body !== 'object' || Array.isArray(body)) {
+                    const flags = Object.keys(fields).map((f) => `--${f}`);
+                    throw inputError(`${flags.join(', ')} need a JSON object body`);
+                }
+                body = { ...body, ...fields };
+            }
+            if (verb === 'create') return runTool(tools.resource_create, { ...base, body });
+            if (verb === 'update') {
+                return runTool(tools.resource_update, {
+                    ...base,
+                    body,
+                    ...(opts.merge ? { merge: true } : {}),
+                });
+            }
+            // clone: the new id goes into the body's id field.
+            const idFields = spec.bodyId ?? idNames(spec);
+            if (idFields.length !== 1)
+                throw inputError(`${what} cannot be cloned from the command line`);
+            const copy = values[values.length - 1];
+            return runTool(tools.resource_clone, {
+                ...base,
+                body: { ...body, [idFields[0]]: copy },
+            });
+        } catch (error) {
+            const { message, code } = classifyError(error);
+            printErr(message, { code });
+        }
+    });
+}
+
+function addDescribe(group, type, tools) {
+    group
+        .command('describe')
+        .helpGroup('Records:')
+        .description(
+            `Fields, examples and permissions of ${article(noun(type))}, from the server's API`,
+        )
+        .option('-j, --json', 'Output as JSON')
+        .action(async (opts) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            await runTool(
+                async (args) => {
+                    const result = await tools.resource_describe(args);
+                    if (result.isError || isJsonMode()) return result;
+                    const said = result.content.map((c) => c.text).join('\n');
+                    return textResult(describeForCli(said, type, group));
+                },
+                { type },
+            );
+        });
+}
+
+/** How a field of a JSON schema reads: its type, values or shape. */
+function schemaType(field) {
+    if (!field || typeof field !== 'object') return 'any';
+    if (field.enum) return field.enum.map((v) => JSON.stringify(v)).join('|');
+    if (field.const !== undefined) return JSON.stringify(field.const);
+    const alternatives = field.oneOf ?? field.anyOf;
+    if (alternatives) return [...new Set(alternatives.map(schemaType))].join('|');
+    if (field.type === 'array') return `array of ${schemaType(field.items)}`;
+    if (Array.isArray(field.type)) return field.type.join('|');
+    if (field.type) return field.type;
+    if (field.properties) return 'object';
+    if (field.patternProperties || field.additionalProperties) return 'map';
+    return 'any';
+}
+
+/** Limits of a field worth a mention: lengths, ranges, default. */
+function schemaLimits(field) {
+    const out = [];
+    if (field.maxLength !== undefined) out.push(`max ${field.maxLength} chars`);
+    if (field.minimum !== undefined) out.push(`min ${field.minimum}`);
+    if (field.maximum !== undefined) out.push(`max ${field.maximum}`);
+    if (field.default !== undefined) out.push(`default ${JSON.stringify(field.default)}`);
+    return out.join(', ');
+}
+
+/** Fields of an object schema, nested ones by their dot path, two levels down. */
+function schemaFields(schema, prefix = '', depth = 0) {
+    const required = new Set(schema?.required || []);
+    const rows = [];
+    for (const [name, field] of Object.entries(schema?.properties || {})) {
+        const path = `${prefix}${name}`;
+        const nested = field.type === 'array' ? field.items : field;
+        const children = Object.keys(nested?.properties || {});
+        let type = schemaType(field);
+        if (children.length && depth >= 1) type += ` {${children.join(', ')}}`;
+        const about = [schemaLimits(field), field.description].filter(Boolean).join('. ');
+        rows.push([`${path}${required.has(name) ? '*' : ''}`, type, about]);
+        if (children.length && depth < 1) {
+            rows.push(
+                ...schemaFields(nested, `${path}${field.type === 'array' ? '[]' : ''}.`, depth + 1),
+            );
+        }
+    }
+    return rows;
+}
+
+const indent = (text, by) => text.replace(/^/gm, ' '.repeat(by));
+
+/** Rows of schemaFields as aligned lines under a heading. */
+function fieldTable(heading, rows) {
+    const width = Math.min(30, Math.max(...rows.map((r) => r[0].length)));
+    const typeWidth = Math.min(24, Math.max(...rows.map((r) => r[1].length)));
+    const lines = rows.map(([name, type, about]) =>
+        `  ${name.padEnd(width)}  ${type.padEnd(typeWidth)}  ${about}`.trimEnd(),
+    );
+    return [heading, ...lines];
+}
+
+/**
+ * A body (`{schema, examples}`) as tables of fields and its examples,
+ * pretty. A body with alternatives (a device by its type) gets a table per
+ * alternative, named after the field that tells them apart.
+ */
+function describeBody(verb, body) {
+    const out = [];
+    const variants = (body.schema?.oneOf ?? body.schema?.anyOf)?.filter((v) => v?.properties);
+    if (variants?.length) {
+        const tag = Object.keys(variants[0].properties).find((name) =>
+            variants.every(
+                (v) => v.properties[name]?.enum || v.properties[name]?.const !== undefined,
+            ),
+        );
+        variants.forEach((v, i) => {
+            const when = tag ? `${tag} ${schemaType(v.properties[tag])}` : `option ${i + 1}`;
+            out.push(...fieldTable(`${verb} fields, ${when} (* required):`, schemaFields(v)));
+        });
+    } else if (body.schema?.properties) {
+        out.push(...fieldTable(`${verb} fields (* required):`, schemaFields(body.schema)));
+    } else if (body.schema) {
+        out.push(`${verb} body: ${schemaType(body.schema)}`);
+    }
+    for (const [name, example] of Object.entries(body.examples || {})) {
+        out.push(`${verb} example "${name}":`, indent(JSON.stringify(example, null, 2), 2));
+    }
+    return out.join('\n');
+}
+
+/**
+ * resource_describe's answer, for a command line: the commands of the type
+ * instead of the tools that run its operations and actions, its ids as the
+ * command takes them, the bodies as tables of fields and the JSON pretty.
+ */
+export function describeForCli(text, type, group) {
+    const at = `${identity().name} ${commandPath(type).join(' ')}`;
+    const actions = Object.keys(CATALOG[type]?.actions || {});
+    const rename = (line) =>
+        actions.reduce(
+            (out, a) =>
+                actionName(type, a) === a
+                    ? out
+                    : out.replace(new RegExp(`\\b${a}\\b`, 'g'), actionName(type, a)),
+            line,
+        );
+    const prose = (value) =>
+        cliDescription(cliWording(rename(value), type)).replace(
+            /\bproduct_profile_\* types\b/g,
+            `\`${identity().name} product profile\` commands`,
+        );
+    const json = (value) => {
+        try {
+            return JSON.parse(value);
+        } catch {
+            return undefined;
+        }
+    };
+    let examples = false;
+    return text
+        .split('\n')
+        .map((line) => {
+            // After "examples:", one call per line: the command that makes it.
+            if (examples) return exampleCommand(json(line));
+            if (line === 'examples:') {
+                examples = true;
+                return line;
+            }
+            const [, key, value] = line.match(/^(\w+): (.*)$/s) || [];
+            const parsed = value?.startsWith('{') ? json(value) : undefined;
+            if (key === 'operations') {
+                const verbs = group.commands
+                    .filter((c) => !c.commands.length && c.helpGroup() === 'Records:')
+                    .map((c) => c.name());
+                return `commands: ${at} ${verbs.join('|')}`;
+            }
+            if (key === 'ids') {
+                // As the commands take them: positional, outermost first.
+                const chain = ancestry(type);
+                const own = idArgs(type);
+                return [
+                    ...(chain.length
+                        ? [`parent: ${chain.join(' > ')} (ids ${argSpec(parentArgs(type))})`]
+                        : []),
+                    `id: ${own.length ? argSpec(own) : 'none: a single resource of its parent'}`,
+                ].join('\n');
+            }
+            // The usage of each command says which ids it takes.
+            if (key === 'own_id') return null;
+            if (key === 'actions' && parsed) {
+                const lines = Object.entries(parsed).map(
+                    ([a, { does }]) => `  ${at} ${actionName(type, a)}: ${prose(does ?? '')}`,
+                );
+                return `actions:\n${lines.join('\n')}`;
+            }
+            if (['create', 'update', 'clone'].includes(key) && parsed) {
+                return describeBody(key, parsed);
+            }
+            if (key === 'permissions' && parsed?.actions) {
+                // Actions by their command: test, not test_rule.
+                const named = Object.entries(parsed.actions).map(([verb, action]) => [
+                    actions.includes(verb) ? actionName(type, verb) : verb,
+                    action,
+                ]);
+                const width = Math.max(...named.map(([verb]) => verb.length));
+                const lines = named.map(([verb, action]) => `  ${verb.padEnd(width)}  ${action}`);
+                return `permissions (${parsed.resource_type}):\n${lines.join('\n')}`;
+            }
+            if (key === 'record_example' && parsed) {
+                return `record example:\n${indent(JSON.stringify(parsed, null, 2), 2)}`;
+            }
+            if (key === 'notes' || key === 'description') return `${key}: ${prose(value)}`;
+            return line;
+        })
+        .filter((line) => line !== null && line !== undefined)
+        .join('\n');
+}
+
+/**
+ * The command that makes an example call of resource_describe, or
+ * undefined (dropped) when no command does: `thinger device property get
+ * boiler setpoint`, with its body piped to --from.
+ *
+ * @param {{ tool?: string, arguments?: Record<string, any>, does?: string } | undefined} example
+ */
+function exampleCommand(example) {
+    const args = example?.arguments;
+    const tool = String(example?.tool ?? '').replace(/^[a-z0-9]+_(?=resource_)/, '');
+    const verb = tool.replace(/^resource_/, '');
+    if (!args?.type) return undefined;
+    const words = opCommand(args.type, verb === 'call' ? args.action : verb);
+    // Lists take filters as options the example does not map: skip them.
+    if (!words || (args.filter && Object.keys(args.filter).length)) return undefined;
+    const line = [identity().name, words, ...Object.values(args.ids || {})].join(' ');
+    const piped =
+        args.body === undefined ? line : `echo '${JSON.stringify(args.body)}' | ${line} --from -`;
+    return `  ${piped}${example?.does ? `  # ${example.does}` : ''}`;
+}
+
+/**
+ * A tool's text, for a command line (see cliWording), its type by the
+ * command's noun. Lines of JSON records are printed as they come.
+ */
+function cliText(text, type) {
+    const label = type && type in CATALOG ? new RegExp(`\\b${type}\\b`, 'g') : null;
+    return text
+        .split('\n')
+        .map((line) => {
+            if (/^\s*([[{\]}]|"[^"]*":)/.test(line)) return line;
+            const out = cliWording(line, type);
+            return label && !out.includes('{') ? out.replace(label, noun(type)) : out;
+        })
+        .join('\n');
+}
+
+/**
+ * Actions that undo things as a delete does, asking first unless -y: the
+ * question each asks, of the type's noun and the ids.
+ */
+const DESTRUCTIVE = {
+    replace_all: (what, of) => `Replace every ${what} of ${of}?`,
+    'plugin.remove': (what, of) => `Uninstall plugin ${of}? Its data is removed.`,
+    'host.restart': (what, of) => `Restart host ${of}? Every connection drops meanwhile.`,
+};
+
+function addAction(group, type, action, spec, tools) {
+    const parents = parentArgs(type);
+    const ids = spec.on === 'collection' ? [] : idArgs(type);
+    const name = actionName(type, action);
+    const destructive = DESTRUCTIVE[`${type}.${action}`] ?? DESTRUCTIVE[action];
+    const usage = [name, argSpec(parents), argSpec(ids)].filter(Boolean).join(' ');
+    const cmd = group
+        .command(usage)
+        .helpGroup(DATA_VERBS.includes(name) ? 'Data:' : 'Actions:')
+        // The group lists the first sentence; the command's help, all of it.
+        .summary(firstSentence(cliDescription(spec.description)))
+        .description(cliDescription(spec.description))
+        .option('-q, --query <key=value>', 'Query parameter (repeatable)', collectKeyString)
+        .option('-f, --field <path>', 'Print only this field of the answer (dot path)')
+        .option('-o, --output <file>', 'Write the answer to a file')
+        .option('-j, --json', 'Output as JSON');
+    describeIds(cmd, type);
+    if (spec.method !== 'get') bodyOptions(cmd);
+    if (destructive) cmd.option('-y, --yes', 'Do not ask for confirmation');
+    cmd.action(async (...params) => {
+        const command = params[params.length - 1];
+        const opts = params[params.length - 2];
+        const values = params.slice(0, -2);
+        applyJsonFlag(opts);
+        ensureConfigured();
+        const user = getGlobalUser(command);
+        try {
+            const where = locate(type, values, { withId: spec.on !== 'collection' });
+            let body = await bodyFromOptions(opts);
+            if (
+                destructive &&
+                !(await confirmDestructive(opts, destructive(noun(type), shown(where.ids))))
+            ) {
+                return;
+            }
+            // Actions that ask first: the command line asked already (or
+            // never did, for those it runs as typed).
+            if (
+                spec.confirm &&
+                (body === undefined || (typeof body === 'object' && !Array.isArray(body)))
+            ) {
+                body = { ...(body ?? {}), confirm: true };
+            }
+            await runTool(
+                tools.resource_call,
+                {
+                    type,
+                    action,
+                    ids: where.ids,
+                    ...(body !== undefined ? { body } : {}),
+
+                    ...(opts.query ? { query: opts.query } : {}),
+                    ...(user ? { user } : {}),
+                },
+                { output: opts.output, field: opts.field },
+            );
+        } catch (error) {
+            const { message, code } = classifyError(error);
+            printErr(message, { code });
+        }
+    });
+}