@thinger-io/cli-core 0.2.1 → 0.4.0

package/lib/mcp/tools-resource.js

@@ -28,6 +28,131 @@ import { mergeHooks } from './resource-hooks.js';
  * document when the model needs it.
  */
 
+/**
+ * Types and actions a CLI adds to the catalog (`runCli({ resourceTypes,
+ * resourceActions })`): its platform's own things, served by the same
+ * tools. A CLI type has no REST path: its functions answer each verb.
+ *
+ * What reaches those functions comes from the model: `parent` and `id` are
+ * checked for their number of segments (and `..`, empty or control
+ * characters), but `id`, `filter`, `query` and the body are still untrusted
+ * input, to be validated before use.
+ *
+ * @typedef {object} LocalContext
+ * @property {string} type
+ * @property {string} [parent]
+ * @property {string} [id]
+ * @property {string | null} [user]
+ * @property {Record<string, any>} [filter]  resource_list's filter.
+ * @property {Record<string, any>} [query]   resource_call's query.
+ * @property {boolean} [full]
+ * @property {Record<string, any>} state
+ *
+ * @typedef {object} LocalAction
+ * @property {string} description
+ * @property {'item' | 'collection' | 'either'} [on]  Whether it takes an id: item (default)
+ *   needs one, collection takes none, either takes it or not.
+ * @property {object} [body]  JSON schema of its body, shown by resource_describe.
+ * @property {(body: any, ctx: LocalContext) => any} run  Returns the answer: text,
+ *   anything JSON, or a whole tool result ({content: [{type, text}], isError}) to flag a
+ *   failure (only actions can; the verbs answer text or JSON).
+ *
+ * @typedef {object} LocalType
+ * @property {string} description  One line, shown in the catalog summary.
+ * @property {string} [parent]  Type this one hangs off (the server's or another CLI
+ *   type with an id): its location is the `parent`.
+ * @property {string} [id]      Name of the item id; without one, a single resource of its parent.
+ * @property {string} [notes]   Longer guidance returned by resource_describe.
+ * @property {object} [schema]  JSON schema of a record, the body of create and update.
+ * @property {() => Record<string, any> | Promise<Record<string, any>>} [describe]  More
+ *   for resource_describe to show (a reference the type's records follow, say).
+ * @property {(ctx: LocalContext) => any[] | Promise<any[]>} [list]  The whole list:
+ *   search and paging are done by the tool.
+ * @property {(ctx: LocalContext) => any} [get]
+ * @property {(body: any, ctx: LocalContext) => any} [create]  Returns a result or a note.
+ * @property {(body: any, ctx: LocalContext) => any} [update]
+ * @property {(ctx: LocalContext) => any} [delete]
+ * @property {Record<string, LocalAction>} [actions]
+ */
+
+const LOCAL_VERBS = /** @type {const} */ (['list', 'get', 'create', 'update', 'delete']);
+const ACTION_ON = new Set(['item', 'collection', 'either']);
+// eslint-disable-next-line no-control-regex -- control characters are what it looks for
+const CONTROL = /[\x00-\x1f]/;
+
+/** An own key of a plain map: never `constructor` or another inherited one. */
+const own = (map, key) =>
+    map && typeof key === 'string' && Object.hasOwn(map, key) ? map[key] : undefined;
+
+/** A whole MCP tool result, as an action may answer to flag a failure. */
+const isToolResult = (v) =>
+    !!v &&
+    typeof v === 'object' &&
+    Array.isArray(v.content) &&
+    v.content.every((c) => c && typeof c === 'object' && typeof c.type === 'string') &&
+    Object.keys(v).every((k) => k === 'content' || k === 'isError' || k === '_meta');
+
+/**
+ * Longest answer a CLI type or action gives (characters of the text sent):
+ * a file it reads can be huge. Server types are never cut: a record read to
+ * be edited and written back must be whole.
+ */
+export const MAX_TEXT = 100_000;
+
+/** `text` cut at MAX_TEXT, saying so. */
+function capped(t) {
+    t = String(t ?? '');
+    if (t.length <= MAX_TEXT) return t;
+    return `${t.slice(0, MAX_TEXT)}\n… (cut: ${t.length} characters in total, showing the first ${MAX_TEXT})`;
+}
+
+/**
+ * Check what a CLI adds against the catalog: a type or an action that
+ * clashes with the server's is a mistake, found when the server starts.
+ *
+ * @param {Record<string, LocalType>} types
+ * @param {Record<string, Record<string, LocalAction>>} actions
+ */
+export function checkLocal(types, actions) {
+    for (const [name, t] of Object.entries(types)) {
+        if (CATALOG[name]) throw new Error(`Resource type "${name}" is already a server type`);
+        if (!t.description) throw new Error(`Resource type "${name}" needs a description`);
+        if (t.parent && !CATALOG[t.parent] && !own(types, t.parent)) {
+            throw new Error(`Resource type "${name}": unknown parent "${t.parent}"`);
+        }
+        const seen = new Set([name]);
+        for (let p = t.parent; p && own(types, p); p = types[p].parent) {
+            if (seen.has(p)) throw new Error(`Resource type "${name}": its parents loop`);
+            if (!types[p].id) throw new Error(`Resource type "${name}": parent "${p}" has no id`);
+            seen.add(p);
+        }
+        if (!LOCAL_VERBS.some((v) => typeof t[v] === 'function') && !t.actions) {
+            throw new Error(`Resource type "${name}" has no operations`);
+        }
+        for (const [a, spec] of Object.entries(t.actions || {})) checkAction(name, a, spec);
+    }
+    for (const [type, list] of Object.entries(actions)) {
+        if (!CATALOG[type] && !types[type]) {
+            throw new Error(`Actions for unknown resource type "${type}"`);
+        }
+        for (const [a, spec] of Object.entries(list)) {
+            if (CATALOG[type]?.actions?.[a] || types[type]?.actions?.[a]) {
+                throw new Error(`Resource type "${type}" already has an action "${a}"`);
+            }
+            checkAction(type, a, spec);
+        }
+    }
+}
+
+function checkAction(type, name, spec) {
+    if (typeof spec?.run !== 'function' || !spec.description) {
+        throw new Error(`Action "${name}" of "${type}" needs a description and run()`);
+    }
+    if (spec.on !== undefined && !ACTION_ON.has(spec.on)) {
+        throw new Error(`Action "${name}" of "${type}": on must be item, collection or either`);
+    }
+}
+
 /** `{tool:x}` in catalog notes → full tool names (tests check they exist). */
 const expandNotes = (notes) => notes.replace(/\{tool:([a-z0-9_]+)\}/g, (_, base) => toolName(base));
 
@@ -209,7 +334,7 @@ function responseExample(operation) {
 }
 
 /** Which tool runs each verb of a type. */
-function operationsOf(type) {
+function operationsOf(ops) {
     const tools = {
         list: toolName('resource_list'),
         get: toolName('resource_get'),
@@ -220,30 +345,115 @@ function operationsOf(type) {
         clone: toolName('resource_clone'),
         projects: `${toolName('resource_update')} with {projects: [...]}`,
     };
-    return Object.fromEntries(Object.keys(type.ops).map((verb) => [verb, tools[verb]]));
-}
-
-function catalogSummary(names) {
-    const lines = names.map((name) => {
-        const t = CATALOG[name];
-        const parent = t.parent ? ` (parent ${parentHint(name)})` : '';
-        const id = idNames(t).length ? '' : ' (single, no id)';
-        const actions = Object.keys(t.actions || {});
-        const ops =
-            Object.keys(t.ops).join(' ') + (actions.length ? ` | ${actions.join(' ')}` : '');
-        return `${name}${parent}${id}: ${expandNotes(t.description)} [${ops}]`;
-    });
-    return `Resource types, with their operations and, after |, their actions (run with ${toolName('resource_call')}). ${toolName('resource_describe')} with a type gives its schemas and examples.\n\n${lines.join('\n')}`;
+    return Object.fromEntries(Object.keys(ops).map((verb) => [verb, tools[verb]]));
 }
 
 /**
- * The tools, for the types this server mode exposes.
+ * The tools, over the catalog and what the CLI adds to it.
  *
- * @param {{ hooks?: Record<string, import('./resource-hooks.js').ResourceHooks> }} [opts]
+ * @param {{
+ *   hooks?: Record<string, import('./resource-hooks.js').ResourceHooks>,
+ *   types?: Record<string, LocalType>,
+ *   actions?: Record<string, Record<string, LocalAction>>,
+ * }} [opts]
  */
-export function resourceTools({ hooks: extraHooks } = {}) {
+export function resourceTools({ hooks: extraHooks, types: local = {}, actions: extra = {} } = {}) {
+    checkLocal(local, extra);
     const hooks = mergeHooks(extraHooks);
-    const served = new Set(typeNames());
+    const served = new Set([...typeNames(), ...Object.keys(local)]);
+
+    /** Verbs of a type: the catalog's, or the functions a CLI type has. */
+    const opsOf = (name) =>
+        own(local, name)
+            ? Object.fromEntries(
+                  LOCAL_VERBS.filter((v) => typeof local[name][v] === 'function').map((v) => [
+                      v,
+                      'cli',
+                  ]),
+              )
+            : CATALOG[name].ops;
+    /** Actions a CLI adds, to its own types or to the server's. */
+    const localActionsOf = (name) => ({
+        ...(own(local, name)?.actions || {}),
+        ...(own(extra, name) || {}),
+    });
+    const actionNames = (name) => [
+        ...Object.keys(CATALOG[name]?.actions || {}),
+        ...Object.keys(localActionsOf(name)),
+    ];
+    const namesWith = (verb) => [...served].filter((n) => verb in opsOf(n));
+    /** How the parent of a type is written: `<device>`, `<device>/<bucket>`. */
+    const parentOf = (name) => {
+        if (!own(local, name)) return parentHint(name);
+        const p = local[name].parent;
+        return p ? [parentOf(p), idOf(p)].filter(Boolean).join('/') : '';
+    };
+    function idOf(name) {
+        if (!own(local, name)) return idHint(name);
+        return local[name].id ? `<${local[name].id}>` : '';
+    }
+
+    /**
+     * `parent` (and `id`, when needed) as many segments as the type's
+     * location has, none empty, `.`, `..` or with control characters. The
+     * id of a CLI type is one value, which may hold "/" (a path).
+     */
+    function checkLocation(args, { needsId }) {
+        const bad = (part) => !part || part === '.' || part === '..' || CONTROL.test(part);
+        const segments = (value, hint, what) => {
+            if (!hint) return;
+            const parts = value === undefined || value === null ? [] : String(value).split('/');
+            if (parts.length !== hint.split('/').length || parts.some(bad)) {
+                throw inputError(`${what} (${hint}) is required`);
+            }
+        };
+        segments(args.parent, parentOf(args.type), 'parent');
+        if (!needsId || !idOf(args.type)) return;
+        if (own(local, args.type)) {
+            const id = args.id === undefined || args.id === null ? '' : String(args.id);
+            if (!id || CONTROL.test(id))
+                throw inputError(`id (${idOf(args.type)}) is required`);
+        } else {
+            segments(args.id, idOf(args.type), 'id');
+        }
+    }
+
+    function catalogSummary(names) {
+        const lines = names.map((name) => {
+            const t = local[name] || CATALOG[name];
+            const parent = t.parent ? ` (parent ${parentOf(name)})` : '';
+            const id = idOf(name) ? '' : ' (single, no id)';
+            const actions = actionNames(name);
+            const ops =
+                Object.keys(opsOf(name)).join(' ') +
+                (actions.length ? ` | ${actions.join(' ')}` : '');
+            return `${name}${parent}${id}: ${expandNotes(t.description)} [${ops}]`;
+        });
+        return `Resource types, with their operations and, after |, their actions (run with ${toolName('resource_call')}). ${toolName('resource_describe')} with a type gives its schemas and examples.\n\n${lines.join('\n')}`;
+    }
+
+    /** Context of a call on a CLI type or action, with its parent and id checked. */
+    function localContext(args, { needsId = true, state = {} } = {}) {
+        checkLocation(args, { needsId });
+        return {
+            type: args.type,
+            parent: args.parent,
+            id: args.id,
+            user: args.user,
+            filter: args.filter,
+            query: args.query,
+            full: args.full === true,
+            state,
+        };
+    }
+
+    /** What a CLI function answered, as tool text. */
+    const answer = (value) =>
+        value === undefined || value === null || value === ''
+            ? undefined
+            : typeof value === 'string'
+              ? value
+              : JSON.stringify(value, null, 2);
 
     /**
      * Validate the type for a verb and build the hook context.
@@ -258,10 +468,16 @@ export function resourceTools({ hooks: extraHooks } = {}) {
                 `Unknown type "${type ?? ''}". ${toolName('resource_describe')} lists them.`,
             );
         }
-        if (!(verb in CATALOG[type].ops)) {
-            const allowed = Object.keys(CATALOG[type].ops).join(', ');
+        if (!(verb in opsOf(type))) {
+            const allowed = Object.keys(opsOf(type)).join(', ');
             throw inputError(`Type "${type}" does not support ${verb} (it supports: ${allowed})`);
         }
+        // CLI types: located before any hook runs; the id of a create may
+        // still come from the body.
+        if (own(local, type)) {
+            if (args.merge) throw inputError(`${type} takes no merge: send the fields to change`);
+            checkLocation(args, { needsId: verb !== 'list' && verb !== 'create' });
+        }
         const ctx = {
             type,
             parent: args.parent,
@@ -284,10 +500,56 @@ export function resourceTools({ hooks: extraHooks } = {}) {
         return body;
     }
 
+    /** Actions as resource_describe shows them: how to run, what they do, their body. */
+    function describeActions(actions) {
+        return Object.fromEntries(
+            Object.entries(actions).map(([a, spec]) => {
+                const entry = {
+                    run: `${toolName('resource_call')} action "${a}"`,
+                    does: expandNotes(spec.description),
+                };
+                if (typeof spec.run === 'function') {
+                    const on = spec.on || 'item';
+                    if (on !== 'item') entry.id = on === 'collection' ? 'none' : 'optional';
+                    if (spec.body) entry.body = { schema: spec.body };
+                } else if (spec.on === 'collection') {
+                    entry.id = 'none';
+                }
+                return [a, entry];
+            }),
+        );
+    }
+
+    /** resource_describe of a CLI type: everything it says comes from its definition. */
+    async function describeLocal(name) {
+        const t = local[name];
+        const out = { type: name, description: expandNotes(t.description) };
+        if (t.parent) out.parent = `${t.parent} (write it as "${parentOf(name)}")`;
+        out.id = t.id ? idOf(name) : 'none: a single resource of its parent';
+        out.operations = operationsOf(opsOf(name));
+        if (t.schema) out.fields = t.schema;
+        const actions = localActionsOf(name);
+        if (Object.keys(actions).length) out.actions = describeActions(actions);
+        if (t.notes) out.notes = expandNotes(t.notes);
+        if (t.describe) {
+            try {
+                Object.assign(out, await t.describe());
+            } catch (e) {
+                out.reference = `unavailable: ${e instanceof Error ? e.message : String(e)}`;
+            }
+        }
+        return Object.entries(out)
+            .map(
+                ([key, value]) =>
+                    `${key}: ${typeof value === 'string' ? value : JSON.stringify(value)}`,
+            )
+            .join('\n');
+    }
+
     async function toolDescribe(args) {
         if (!args.type) {
-            // The overview call: the types, plus the server's guide to its
-            // concepts when it publishes one (older servers do not).
+            // The overview call: the types, plus the guide to the
+            // platform's concepts.
             const concepts = await readDoc('concepts').then(
                 (d) => d.text,
                 () => '',
@@ -302,23 +564,15 @@ export function resourceTools({ hooks: extraHooks } = {}) {
             throw inputError(`Unknown type "${args.type}".\n\n${catalogSummary([...served])}`);
         }
         const name = args.type;
+        if (own(local, name)) return text(capped(await describeLocal(name)));
         const type = CATALOG[name];
         const out = { type: name, description: expandNotes(type.description) };
         const chain = ancestry(name);
         if (chain.length) out.parent = `${chain.join(' > ')} (write it as "${parentHint(name)}")`;
         out.id = idNames(type).length ? idHint(name) : 'none: a single resource of its parent';
-        out.operations = operationsOf(type);
-        if (type.actions) {
-            out.actions = Object.fromEntries(
-                Object.entries(type.actions).map(([a, spec]) => [
-                    a,
-                    {
-                        run: `${toolName('resource_call')} action "${a}"`,
-                        does: expandNotes(spec.description),
-                    },
-                ]),
-            );
-        }
+        out.operations = operationsOf(type.ops);
+        const allActions = { ...(type.actions || {}), ...localActionsOf(name) };
+        if (Object.keys(allActions).length) out.actions = describeActions(allActions);
         if (type.notes) out.notes = expandNotes(type.notes);
         if (type.sdk) {
             out.sdk = await readDoc('dashboard-sdk').then(
@@ -381,7 +635,12 @@ export function resourceTools({ hooks: extraHooks } = {}) {
     }
 
     async function toolList(args) {
-        const { type } = prepare(args, 'list');
+        const { type, ctx } = prepare(args, 'list');
+        if (own(local, type)) {
+            const lctx = localContext(args, { needsId: false, state: ctx.state });
+            const data = (await local[type].list?.(lctx)) ?? [];
+            return text(capped(pageOf(type, data, args, true)));
+        }
         const params = { ...(CATALOG[type].listQuery || {}), ...(args.filter || {}) };
         // Search: the server matches `name` against ids and names (partial,
         // case-insensitive, as a regular expression: escape it). Lists the
@@ -395,6 +654,14 @@ export function resourceTools({ hooks: extraHooks } = {}) {
         let data = await sendList(type, args, params);
         const fields = CATALOG[type].listFields;
         if (fields && Array.isArray(data)) data = data.map((record) => pick(record, fields));
+        return text(pageOf(type, data, args, whole));
+    }
+
+    /**
+     * A list as resource_list answers it: searched here when the source
+     * answers it whole, and paged here when it ignores count/index.
+     */
+    function pageOf(type, data, args, whole) {
         // Lists answered whole: every word must appear in what a record shows.
         if (args.search && whole && Array.isArray(data)) {
             const words = String(args.search).toLowerCase().split(/\s+/).filter(Boolean);
@@ -406,29 +673,32 @@ export function resourceTools({ hooks: extraHooks } = {}) {
         // Some collections ignore count/index and answer everything: page
         // them here so one call cannot flood the conversation.
         const pageSize = args.count ?? 50;
-        if (Array.isArray(data) && data.length > pageSize) {
-            const from = args.index ?? 0;
+        const from = args.index ?? 0;
+        if (Array.isArray(data) && (data.length > pageSize || (whole && from > 0))) {
             const page = data.slice(from, from + pageSize);
             const next =
                 from + page.length < data.length
                     ? `; pass index: ${from + page.length} for more, or narrow it with filter`
                     : '';
-            return text(
-                `${formatList(type, page, Infinity)}\n(${data.length} in total, showing ${from}–${from + page.length - 1}${next})`,
-            );
+            return `${formatList(type, page, Infinity)}\n(${data.length} in total, showing ${from}–${from + page.length - 1}${next})`;
         }
-        return text(formatList(type, data, whole ? Infinity : pageSize));
+        return formatList(type, data, whole ? Infinity : pageSize);
     }
 
     async function toolGet(args) {
         const { type, ctx, hook } = prepare(args, 'get');
-        let record = await send(type, 'get', args);
+        const mine = own(local, type);
+        let record = mine
+            ? await mine.get?.(localContext(args, { state: ctx.state }))
+            : await send(type, 'get', args);
         if (hook.afterGet) record = await hook.afterGet(record, ctx);
-        return text(JSON.stringify(record, null, 2));
+        if (!mine) return text(JSON.stringify(record, null, 2));
+        return text(capped(answer(record) ?? `No ${label(type, args)}.`));
     }
 
     async function toolCreate(args) {
         const { type, ctx, hook } = prepare(args, 'create');
+        if (own(local, type)) return createLocal(args, ctx, hook);
         const t = CATALOG[type];
         let body = bodyArg(args, 'create');
         // `projects` is not a field the server takes on create: set it right
@@ -472,9 +742,46 @@ export function resourceTools({ hooks: extraHooks } = {}) {
         return text(lines.join('\n'));
     }
 
+    async function createLocal(args, ctx, hook) {
+        const t = local[args.type];
+        let body = bodyArg(args, 'create');
+        if (Array.isArray(body)) throw inputError('body must be a JSON object');
+        if (t.id && args.id !== undefined && body[t.id] === undefined)
+            body = { [t.id]: args.id, ...body };
+        // The hook may set or normalise the id: read it after.
+        if (hook.beforeCreate) body = await hook.beforeCreate(body, ctx);
+        const id = args.id ?? (t.id ? body?.[t.id] : undefined);
+        if (t.id && (id === undefined || id === null || id === '')) {
+            throw inputError(`give the ${args.type} id: \`id\`, or the body field "${t.id}"`);
+        }
+        ctx.id = id;
+        const lctx = localContext({ ...args, id }, { state: ctx.state });
+        const result = await t.create?.(body, lctx);
+        const lines = [`Created ${label(args.type, { parent: args.parent, id })}.`];
+        const said = answer(result);
+        if (said) lines.push(said);
+        const note = hook.afterCreate && (await hook.afterCreate(result, ctx));
+        if (note) lines.push('', note);
+        return text(lines.join('\n'));
+    }
+
     async function toolUpdate(args) {
         /** @type {import('./catalog.js').Verb} */
         const verb = args.merge ? 'patch' : 'update';
+        if (own(local, args.type)) {
+            const { type, ctx, hook } = prepare(args, 'update');
+            let body = bodyArg(args, 'update');
+            if (Array.isArray(body)) throw inputError('body must be a JSON object');
+            if (hook.beforeUpdate) body = await hook.beforeUpdate(body, ctx);
+            const result = await local[type].update?.(
+                body,
+                localContext(args, { state: ctx.state }),
+            );
+            const said = answer(result);
+            return text(
+                `Updated ${label(type, args)}: ${Object.keys(body).join(', ')}.${said ? `\n${said}` : ''}`,
+            );
+        }
         const { projects, ...fields } = bodyArg(args, 'update');
         const { type, ctx, hook } = prepare(args, projects !== undefined ? 'projects' : verb);
         const done = [];
@@ -506,8 +813,13 @@ export function resourceTools({ hooks: extraHooks } = {}) {
 
     async function toolDelete(args) {
         const { type, ctx, hook } = prepare(args, 'delete');
-        await send(type, 'delete', args);
+        const mine = own(local, type);
+        const result = mine
+            ? await mine.delete?.(localContext(args, { state: ctx.state }))
+            : await send(type, 'delete', args);
         const lines = [`Deleted ${label(type, args)}.`];
+        const said = mine && answer(result);
+        if (said) lines.push(said);
         const note = hook.afterDelete && (await hook.afterDelete(ctx));
         if (note) lines.push(note);
         return text(lines.join('\n'));
@@ -543,11 +855,36 @@ export function resourceTools({ hooks: extraHooks } = {}) {
 
     async function toolCall(args) {
         const type = args.type;
-        if (!type || !served.has(type) || !CATALOG[type].actions) {
+        const known = typeof type === 'string' && served.has(type);
+        const mine = known ? own(localActionsOf(type), args.action) : undefined;
+        if (mine) {
+            const on = mine.on || 'item';
+            if (on === 'collection' && args.id !== undefined) {
+                throw inputError(`${args.action} takes no id`);
+            }
+            const ctx = localContext(args, { needsId: on === 'item' });
+            const result = await mine.run(args.body, ctx);
+            if (isToolResult(result)) {
+                return {
+                    ...result,
+                    content: result.content.map((c) =>
+                        c.type === 'text' ? { ...c, text: capped(c.text) } : c,
+                    ),
+                };
+            }
+            const said = answer(result);
+            return text(capped(said ?? `Ran ${args.action} on ${label(type, args)}.`));
+        }
+        if (!known || !actionNames(type).length) {
             throw inputError(
                 `Type "${type ?? ''}" has no actions. ${toolName('resource_describe')} lists them after |.`,
             );
         }
+        if (!own(CATALOG[type]?.actions, args.action)) {
+            throw inputError(
+                `Type "${type}" has no action "${args.action}" (it has: ${actionNames(type).join(', ')})`,
+            );
+        }
         const { method, url, query } = actionRequest(type, args.action, args);
         const spec = CATALOG[type].actions?.[args.action];
         const started = Date.now();
@@ -585,7 +922,7 @@ export function resourceTools({ hooks: extraHooks } = {}) {
 
     const typeParam = (verb) => ({
         type: 'string',
-        enum: typeNames({ verb }),
+        enum: verb ? namesWith(verb) : [...served],
         description: 'Resource type (see {tool:resource_describe}).',
     });
     const common = {
@@ -609,7 +946,7 @@ export function resourceTools({ hooks: extraHooks } = {}) {
                 "Describe a resource type: its parent and id, the operations it supports and, from this server's API, the request schemas and examples for create, update and clone. Call it before writing a type for the first time. Without `type`: all types and a guide to the platform's concepts (start here).",
             inputSchema: {
                 type: 'object',
-                properties: { type: { ...typeParam(), enum: [...served] } },
+                properties: { type: typeParam() },
                 required: [],
             },
             handler: toolDescribe,
@@ -650,7 +987,7 @@ export function resourceTools({ hooks: extraHooks } = {}) {
                     full: {
                         type: 'boolean',
                         description:
-                            'Plugin catalog manifests only: also include the product code and the console dashboard (large).',
+                            'Plugin catalog manifests: also include the product code and the console dashboard (large). Types that take it say so in their notes.',
                     },
                     user: common.user,
                 },
@@ -742,7 +1079,7 @@ export function resourceTools({ hooks: extraHooks } = {}) {
                 properties: {
                     type: {
                         type: 'string',
-                        enum: Object.keys(CATALOG).filter((n) => CATALOG[n].actions),
+                        enum: [...served].filter((n) => actionNames(n).length),
                         description: 'Resource type.',
                     },
                     action: { type: 'string', description: 'Action name, e.g. "verify".' },

package/lib/tgz.js

@@ -0,0 +1,66 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+
+/**
+ * Extract an npm package tarball (.tgz) into a folder, without a `tar`
+ * binary: only regular files and folders, every path kept inside `dest`.
+ * npm packs ustar archives, with pax headers for long paths.
+ *
+ * @param {Buffer} tgz
+ * @param {string} dest  Folder to extract into (created).
+ * @param {{ strip?: number }} [opts]  Leading path segments to drop (1 for npm's `package/`).
+ */
+export function extractTgz(tgz, dest, { strip = 0 } = {}) {
+    let tar;
+    try {
+        tar = zlib.gunzipSync(tgz);
+    } catch {
+        throw new Error('not a .tgz archive');
+    }
+    const root = path.resolve(dest);
+    fs.mkdirSync(root, { recursive: true });
+    const field = (buf, start, length) =>
+        buf.toString('utf8', start, start + length).replace(/\0.*$/s, '');
+    let offset = 0;
+    /** @type {string | null} */
+    let longName = null;
+    while (offset + 512 <= tar.length) {
+        const header = tar.subarray(offset, offset + 512);
+        if (header.every((b) => b === 0)) break;
+        const size = parseInt(field(header, 124, 12).trim() || '0', 8);
+        if (!Number.isFinite(size) || size < 0) throw new Error('corrupt tar header');
+        const type = String.fromCharCode(header[156] || 48);
+        const prefix = field(header, 345, 155);
+        const name =
+            longName ?? (prefix ? `${prefix}/${field(header, 0, 100)}` : field(header, 0, 100));
+        longName = null;
+        const body = tar.subarray(offset + 512, offset + 512 + size);
+        offset += 512 + Math.ceil(size / 512) * 512;
+
+        if (type === 'x') {
+            // pax extended header: "<len> path=<value>\n" records for the next entry
+            const match = /(?:^|\n)\d+ path=([^\n]*)\n/.exec(body.toString('utf8'));
+            if (match) longName = match[1];
+            continue;
+        }
+        if (type === 'L') {
+            longName = body.toString('utf8').replace(/\0.*$/s, '');
+            continue;
+        }
+        if (type !== '0' && type !== '5') continue; // links, devices… are skipped
+        const parts = name.split('/').filter(Boolean).slice(strip);
+        if (!parts.length) continue;
+        if (parts.some((p) => p === '..' || p.includes('\\') || p.includes(':'))) {
+            throw new Error(`unsafe path in archive: ${name}`);
+        }
+        const target = path.join(root, ...parts);
+        if (!target.startsWith(root + path.sep)) throw new Error(`unsafe path in archive: ${name}`);
+        if (type === '5') fs.mkdirSync(target, { recursive: true });
+        else {
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, body);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@thinger-io/cli-core",
-    "version": "0.2.1",
+    "version": "0.4.0",
     "description": "Shared core of the Thinger.io CLIs and their MCP servers: API client, auth, profiles, generic commands and MCP tools",
     "type": "module",
     "exports": {
@@ -8,6 +8,7 @@
     },
     "files": [
         "lib",
+        "docs",
         "openapi",
         "CHANGELOG.md",
         "LICENSE",
@@ -38,6 +39,7 @@
     "dependencies": {
         "@inquirer/prompts": "^8.4.1",
         "@modelcontextprotocol/sdk": "^1.29.0",
+        "@thinger-io/dashboard-sdk": "^0.3.0",
         "axios": "^1.10.0",
         "chalk": "^5.4.1",
         "commander": "^14.0.0",