@thinger-io/cli-core 0.4.2 → 0.5.0

package/lib/mcp/tools-buckets.js

@@ -1,130 +0,0 @@
-// @ts-check
-import api from '../api.js';
-import { TIMEOUTS } from '../constants.js';
-import { getBucketData } from '../bucket.js';
-import { apiError, inputError } from '../errors.js';
-import { v1 } from '../paths.js';
-
-async function toolBucketDataRead(args) {
-    if (!args.bucket) throw inputError('bucket is required');
-    const data = await getBucketData({
-        bucket: args.bucket,
-        device: args.device,
-        user: args.user,
-        items: args.items || 10,
-        sort: args.sort || 'desc',
-        minutes: args.minutes,
-        min_ts: args.min_ts,
-        max_ts: args.max_ts,
-        agg: args.agg,
-        agg_type: args.agg_type,
-        tz: args.tz,
-        fields: Array.isArray(args.fields) ? args.fields.join(',') : args.fields,
-        group_by: args.group_by,
-    });
-    const text =
-        Array.isArray(data) && data.length === 0 ? 'No data' : JSON.stringify(data, null, 2);
-    return { content: [{ type: 'text', text }], isError: false };
-}
-
-async function toolBucketDataWrite(args) {
-    if (!args.bucket) throw inputError('bucket is required');
-    if (!args.data || typeof args.data !== 'object') {
-        throw inputError('data must be a JSON object (one sample) or an array of them');
-    }
-    const count = Array.isArray(args.data) ? args.data.length : 1;
-    const params = args.ts !== undefined ? { ts: args.ts } : undefined;
-    try {
-        await api.post(
-            `${v1(args.user)}/buckets/${encodeURIComponent(args.bucket)}/data`,
-            args.data,
-            { params, timeout: TIMEOUTS.API_LONG_MS },
-        );
-    } catch (e) {
-        throw apiError(e, { notFound: `Bucket not found: ${args.bucket}` });
-    }
-    return {
-        content: [
-            {
-                type: 'text',
-                text: `Wrote ${count} sample${count === 1 ? '' : 's'} to bucket ${args.bucket}.`,
-            },
-        ],
-        isError: false,
-    };
-}
-
-const userParam = { type: 'string', description: 'Account to act on (admin only).' };
-
-export const tools = [
-    {
-        name: 'bucket_data_read',
-        description: `Query the time series of a bucket (find them with {tool:resource_list}: type "bucket", or "device_bucket" for one device).
-
-- Without \`device\`: the whole bucket. A bucket declared in a product profile holds every device of the product interleaved; \`group_by: "device"\` gives one row per device, when samples carry that tag.
-- With \`device\`: the series the bucket keeps for that device.`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                bucket: { type: 'string', description: 'Bucket id.' },
-                device: {
-                    type: 'string',
-                    description:
-                        'Device id, to read only its records: the bucket needs the `device` tag (product buckets have it).',
-                },
-                items: {
-                    type: 'number',
-                    description: 'Samples to return (default 10, at most 1000).',
-                },
-                minutes: {
-                    type: 'number',
-                    description: 'Last N minutes (instead of min_ts/max_ts).',
-                },
-                min_ts: { type: 'number', description: 'From (unix ms).' },
-                max_ts: { type: 'number', description: 'To (unix ms, 0 = now).' },
-                sort: { type: 'string', description: '"desc" (default) or "asc", by time.' },
-                agg: { type: 'string', description: 'Aggregation window: "5m", "1h"…' },
-                agg_type: {
-                    type: 'string',
-                    description:
-                        'Reducer: mean, max, min, sum, count, first, last, mode, median, spread, stddev.',
-                },
-                tz: {
-                    type: 'string',
-                    description:
-                        'IANA time zone for the aggregation windows, e.g. "Europe/Madrid": "1d" then cuts at local midnight (default UTC).',
-                },
-                fields: {
-                    type: ['string', 'array'],
-                    items: { type: 'string' },
-                    description:
-                        'Fields to return: comma-separated or an array. Without fields, an aggregation covers numeric fields only (those of the latest record in the range); name string fields explicitly to read them with last, first, mode or count.',
-                },
-                group_by: { type: 'string', description: 'Group key, e.g. "device".' },
-                user: userParam,
-            },
-            required: ['bucket'],
-        },
-        handler: toolBucketDataRead,
-    },
-    {
-        name: 'bucket_data_write',
-        description:
-            'Write samples to a bucket whose data source accepts API writes: one object, stored with the current time or `ts`, or an array of objects, each with its own numeric `ts` (unix ms; MongoDB and InfluxDB buckets). Servers limit how often a bucket can be written (429 when exceeded): for long histories, import a CSV ({tool:resource_call} action "import" on the bucket).',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                bucket: { type: 'string', description: 'Bucket id.' },
-                data: {
-                    type: ['object', 'array'],
-                    description:
-                        'Sample fields, e.g. {"temperature": 21.5}, or an array of samples with `ts`.',
-                },
-                ts: { type: 'number', description: 'Timestamp of the sample (unix ms).' },
-                user: userParam,
-            },
-            required: ['bucket', 'data'],
-        },
-        handler: toolBucketDataWrite,
-    },
-];

package/lib/mcp/tools-devices.js

@@ -1,134 +0,0 @@
-// @ts-check
-import api from '../api.js';
-import { apiError, inputError } from '../errors.js';
-import { device, v1 } from '../paths.js';
-import { callDeviceResource, listDeviceResourcesWithSchemas } from '../resource.js';
-
-const text = (t) => ({ content: [{ type: 'text', text: t }], isError: false });
-const json = (data) =>
-    text(
-        data === undefined || data === null || data === ''
-            ? '(no output)'
-            : typeof data === 'string'
-              ? data
-              : JSON.stringify(data, null, 2),
-    );
-
-function requireDevice(args) {
-    if (!args.device) throw inputError('device is required');
-    return args.device;
-}
-
-async function toolResourceList(args) {
-    const entries = await listDeviceResourcesWithSchemas(requireDevice(args), {
-        user: args.user,
-    });
-    const kind = (f) =>
-        ({ 1: 'no params', 2: 'input', 3: 'output', 4: 'input/output' })[f] || 'unknown';
-    const lines = entries.map((e) => {
-        const parts = [`${e.name} [${kind(e.fn)}]`];
-        if (e.in !== undefined) parts.push(`  in:  ${JSON.stringify(e.in)}`);
-        if (e.out !== undefined) parts.push(`  out: ${JSON.stringify(e.out)}`);
-        return parts.join('\n');
-    });
-    return text(lines.length ? lines.join('\n\n') : '(no resources)');
-}
-
-async function toolResourceCall(args) {
-    if (!args.resource) throw inputError('resource is required');
-    return json(
-        await callDeviceResource(requireDevice(args), args.resource, args.inputs, {
-            user: args.user,
-        }),
-    );
-}
-
-async function toolDataSend(args) {
-    const id = requireDevice(args);
-    if (args.data === undefined) throw inputError('data is required');
-    try {
-        const res = await api.post(`${device(args.user, id)}/callback/data`, args.data);
-        const answer = res.data;
-        const shown =
-            answer !== undefined &&
-            answer !== '' &&
-            (typeof answer !== 'object' || (answer && Object.keys(answer).length));
-        return text(`Sent data to ${id}.${shown ? `\nAnswer: ${JSON.stringify(answer)}` : ''}`);
-    } catch (e) {
-        throw apiError(e, { notFound: `Device not found: ${id}` });
-    }
-}
-
-async function toolOverview(args) {
-    try {
-        const [stats, locations] = await Promise.all([
-            api.get(`${v1(args.user)}/info/devices/stats`),
-            args.locations ? api.get(`${v1(args.user)}/info/devices/locations`) : null,
-        ]);
-        return json(locations ? { stats: stats.data, locations: locations.data } : stats.data);
-    } catch (e) {
-        throw apiError(e);
-    }
-}
-
-const deviceParam = { type: 'string', description: 'Device id.' };
-const userParam = { type: 'string', description: 'Account to act on (admin only).' };
-
-export const tools = [
-    {
-        name: 'device_resource_list',
-        description:
-            "List the resources a connected device exposes, with their input/output shapes: the device's own API, declared by its firmware (a sensor to read, an output to switch), plus the API resources its product adds. Not to be confused with server resources ({family:resource}). The device must be online.",
-        inputSchema: {
-            type: 'object',
-            properties: { device: deviceParam, user: userParam },
-            required: ['device'],
-        },
-        handler: toolResourceList,
-    },
-    {
-        name: 'device_resource_call',
-        description:
-            'Call a resource of a connected device and return its output. With `inputs` it runs the resource; without them it only reads its output. See {tool:device_resource_list} for names and inputs.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                device: deviceParam,
-                resource: { type: 'string', description: 'Resource name.' },
-                inputs: { description: 'Input value or object the resource declares.' },
-                user: userParam,
-            },
-            required: ['device', 'resource'],
-        },
-        handler: toolResourceCall,
-    },
-    {
-        name: 'device_data_send',
-        description:
-            'Send data to the server on behalf of an HTTP device, as the device itself would: the server runs the callback configured for it (write a bucket, set a property, call an endpoint; see type device_callback).',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                device: deviceParam,
-                data: { description: 'JSON payload, e.g. {"temperature": 21.5}.' },
-                user: userParam,
-            },
-            required: ['device', 'data'],
-        },
-        handler: toolDataSend,
-    },
-    {
-        name: 'device_overview',
-        description:
-            'Usage of all the devices of the account over the last 30 days, per day; with `locations`, also the last known position of each connected device.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                locations: { type: 'boolean', description: 'Include device locations.' },
-                user: userParam,
-            },
-            required: [],
-        },
-        handler: toolOverview,
-    },
-];

package/lib/mcp/tools-misc.js

@@ -1,48 +0,0 @@
-// @ts-check
-import { getActiveProfile, getProfile, listProfiles } from '../config.js';
-import { listDocs, readDoc } from '../docs.js';
-
-/** The tools about the CLI itself: its documentation and its profiles. */
-
-const text = (t) => ({ content: [{ type: 'text', text: t }], isError: false });
-
-async function toolDocRead(args) {
-    if (args.id) return text((await readDoc(args.id)).text);
-    const docs = await listDocs();
-    if (!docs.length) return text('No documentation available.');
-    return text(
-        docs
-            .map((d) => `${d.id}: ${d.title}${d.description ? ` — ${d.description}` : ''}`)
-            .join('\n'),
-    );
-}
-
-async function toolProfileList() {
-    const active = getActiveProfile();
-    const lines = listProfiles().map((name) => {
-        const data = getProfile(name) || {};
-        return `${name === active ? '* ' : '  '}${name}  (${data.username || ''}@${data.server || name})`;
-    });
-    return text(lines.join('\n') || 'No profiles configured');
-}
-
-export const tools = [
-    {
-        name: 'doc_read',
-        description:
-            "Read the guides for agents and app developers: the platform's concepts, product code, server administration, the dashboard SDK reference and types (the version the project in this folder uses), and this CLI's own. Without `id`, lists them. Read the relevant guide before building something new.",
-        inputSchema: {
-            type: 'object',
-            properties: { id: { type: 'string', description: 'Document id from the list.' } },
-            required: [],
-        },
-        handler: toolDocRead,
-    },
-    {
-        name: 'profile_list',
-        description:
-            'List the configured CLI profiles: each one is a server with its own credentials. Pass a profile name as `profile` on any other tool to use that server for one call.\n\nProfiles are not accounts: another account on the same server is reached with `user` (admin only), not with a profile.',
-        inputSchema: { type: 'object', properties: {}, required: [] },
-        handler: toolProfileList,
-    },
-];

package/lib/mcp/tools-plugins.js

@@ -1,63 +0,0 @@
-// @ts-check
-import api from '../api.js';
-import { TIMEOUTS } from '../constants.js';
-import { apiError, inputError } from '../errors.js';
-import { pluginApi } from '../paths.js';
-
-const METHODS = ['get', 'post', 'put', 'patch', 'delete'];
-
-/** Call the API a plugin serves (its routes are its own: no catalog). */
-async function toolPluginCall(args) {
-    if (!args.plugin) throw inputError('plugin is required');
-    const method = (args.method || 'get').toLowerCase();
-    if (!METHODS.includes(method)) throw inputError(`method must be one of ${METHODS.join(', ')}`);
-    const path = args.path ? `/${String(args.path).replace(/^\/+/, '')}` : '';
-    if (path.split('/').includes('..')) throw inputError('path must not contain ".."');
-    try {
-        const res = await api.request({
-            method,
-            url: `${pluginApi(args.user, args.plugin)}${path}`,
-            data: method === 'get' || method === 'delete' ? undefined : (args.body ?? {}),
-            params: args.query,
-            paramsSerializer: { indexes: null },
-            transformResponse: [(x) => x],
-            responseType: 'text',
-            timeout: TIMEOUTS.API_LONG_MS,
-        });
-        const raw = String(res.data ?? '');
-        let text = raw;
-        try {
-            text = JSON.stringify(JSON.parse(raw), null, 2);
-        } catch {}
-        return {
-            content: [{ type: 'text', text: text || `${res.status} (no content)` }],
-            isError: false,
-        };
-    } catch (e) {
-        throw apiError(e, { notFound: `Not found: plugin ${args.plugin}${path}` });
-    }
-}
-
-export const tools = [
-    {
-        name: 'plugin_call',
-        description:
-            'Call the API an installed plugin serves, at its own `path` (what it offers depends on the plugin; see its documentation or try GET on its root). Find plugins with {tool:resource_list} type "plugin".',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                plugin: { type: 'string', description: 'Plugin id.' },
-                path: {
-                    type: 'string',
-                    description: 'Path inside the plugin, e.g. "/api/status".',
-                },
-                method: { type: 'string', enum: METHODS, description: 'Default get.' },
-                body: { description: 'JSON body for post / put / patch.' },
-                query: { type: 'object', description: 'Query parameters.' },
-                user: { type: 'string', description: 'Account to act on (admin only).' },
-            },
-            required: ['plugin'],
-        },
-        handler: toolPluginCall,
-    },
-];

package/lib/mcp/tools-products.js

@@ -1,52 +0,0 @@
-// @ts-check
-import api from '../api.js';
-import { TIMEOUTS } from '../constants.js';
-import { apiError, inputError } from '../errors.js';
-import { v1 } from '../paths.js';
-
-const json = (data) => ({
-    content: [{ type: 'text', text: JSON.stringify(data ?? null, null, 2) }],
-    isError: false,
-});
-
-function productPath(args) {
-    if (!args.product) throw inputError('product is required');
-    return `${v1(args.user)}/products/${encodeURIComponent(args.product)}`;
-}
-
-async function toolResourceCall(args) {
-    if (!args.resource) throw inputError('resource is required');
-    try {
-        const res = await api.post(
-            `${productPath(args)}/resources/${encodeURIComponent(args.resource)}`,
-            args.data ?? {},
-            { timeout: TIMEOUTS.API_LONG_MS },
-        );
-        return json(res.data);
-    } catch (e) {
-        throw apiError(e, {
-            notFound: `Not found: product ${args.product} or its resource ${args.resource}`,
-        });
-    }
-}
-
-const userParam = { type: 'string', description: 'Account to act on (admin only).' };
-
-export const tools = [
-    {
-        name: 'product_resource_call',
-        description:
-            "Call a product API resource for the product as a whole, as an external system feeding data in would. The entry needs a `device_id_resolver` (a function of the product code that returns each payload's device); `data` may be an array, one payload per device. To call it for one device, use {tool:device_resource_call}.",
-        inputSchema: {
-            type: 'object',
-            properties: {
-                product: { type: 'string', description: 'Product id.' },
-                resource: { type: 'string', description: 'Resource name in the product profile.' },
-                data: { description: 'JSON payload.' },
-                user: userParam,
-            },
-            required: ['product', 'resource'],
-        },
-        handler: toolResourceCall,
-    },
-];

package/lib/mcp/tools-storage.js

@@ -1,173 +0,0 @@
-// @ts-check
-import fs from 'node:fs';
-import nodePath from 'node:path';
-import api from '../api.js';
-import { collectFiles, uploadFiles } from '../dashboard.js';
-import { apiError, inputError } from '../errors.js';
-import { v1 } from '../paths.js';
-import { deleteStorageFile, readStorageFile, writeStorageFile } from '../storage.js';
-
-/** Files of a storage (the storages themselves are the catalog type "storage"). */
-
-const text = (t) => ({ content: [{ type: 'text', text: t }], isError: false });
-const userParam = { type: 'string', description: 'Account to act on (admin only).' };
-const storageParam = { type: 'string', description: 'Storage id.' };
-
-function required(args, ...names) {
-    for (const name of names) {
-        if (args[name] === undefined || args[name] === '') throw inputError(`${name} is required`);
-    }
-}
-
-/** A path inside the storage, without leading slashes (they would double up in the URL). */
-const clean = (p) => String(p).replace(/^\/+/, '');
-
-async function toolList(args) {
-    required(args, 'storage');
-    const params = args.path ? { path: clean(args.path) } : undefined;
-    try {
-        const res = await api.get(
-            `${v1(args.user)}/storages/${encodeURIComponent(args.storage)}/files`,
-            { params },
-        );
-        const files = Array.isArray(res.data) ? res.data : [];
-        return text(files.length ? files.map((f) => JSON.stringify(f)).join('\n') : 'No files.');
-    } catch (e) {
-        // The server keeps files on disk and creates a storage's folder with
-        // its first file: an empty storage answers 404 too.
-        if (e.response?.status === 404) {
-            return text(
-                `No files${args.path ? ` under ${clean(args.path)}` : ''} (or no storage ${args.storage}).`,
-            );
-        }
-        throw apiError(e);
-    }
-}
-
-async function toolRead(args) {
-    required(args, 'storage', 'path');
-    return text(await readStorageFile(args.storage, clean(args.path), args.user));
-}
-
-/** Largest single local file uploaded at once. */
-const MAX_FILE = 50 * 1024 * 1024;
-/** Largest local folder uploaded in one call. */
-const MAX_FOLDER = 200 * 1024 * 1024;
-
-/** Upload a local file (to `path`, default its name) or folder (under `path`). */
-async function uploadLocal(args) {
-    if (args.content !== undefined) throw inputError('pass content or local, not both');
-    const local = nodePath.resolve(String(args.local));
-    if (!fs.existsSync(local)) throw inputError(`No such local file or folder: ${args.local}`);
-    /** @type {Record<string, Buffer>} */
-    let files;
-    if (fs.statSync(local).isDirectory()) {
-        const prefix = args.path ? `${clean(args.path).replace(/\/+$/, '')}/` : '';
-        files = Object.fromEntries(
-            Object.entries(
-                collectFiles(local, {
-                    skip: new Set(['.git']),
-                    maxBytes: MAX_FOLDER,
-                    tooLarge: 'upload its subfolders or files in separate calls',
-                }),
-            ).map(([f, c]) => [prefix + f, c]),
-        );
-        if (!Object.keys(files).length) throw inputError(`${args.local} has no files`);
-    } else {
-        if (fs.statSync(local).size > MAX_FILE) {
-            throw inputError(`${args.local} is larger than ${MAX_FILE / 1024 / 1024} MB`);
-        }
-        files = {
-            [args.path ? clean(args.path) : nodePath.basename(local)]: fs.readFileSync(local),
-        };
-    }
-    await uploadFiles(args.storage, files, args.user);
-    const names = Object.keys(files);
-    const bytes = Object.values(files).reduce((n, c) => n + c.length, 0);
-    const shown =
-        names.slice(0, 20).join(', ') + (names.length > 20 ? `… (+${names.length - 20})` : '');
-    return text(
-        `Uploaded ${names.length} file(s), ${bytes} bytes, to storage ${args.storage}: ${shown}.`,
-    );
-}
-
-async function toolWrite(args) {
-    required(args, 'storage');
-    if (args.local !== undefined) return uploadLocal(args);
-    required(args, 'path');
-    if (typeof args.content !== 'string') throw inputError('content must be a string');
-    await writeStorageFile(args.storage, clean(args.path), args.content, args.user);
-    return text(
-        `Wrote ${clean(args.path)} (${Buffer.byteLength(args.content)} bytes) to storage ${args.storage}.`,
-    );
-}
-
-async function toolDelete(args) {
-    required(args, 'storage', 'path');
-    const deleted = await deleteStorageFile(args.storage, clean(args.path), args.user);
-    return text(deleted ? `Deleted ${clean(args.path)}.` : `No such file: ${clean(args.path)}.`);
-}
-
-const pathParam = {
-    type: 'string',
-    description: 'File path inside the storage, e.g. "web/index.html".',
-};
-
-export const tools = [
-    {
-        name: 'storage_file_list',
-        description:
-            'List the files of a storage (path, size, modification time), optionally only under a folder.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                storage: storageParam,
-                path: { type: 'string', description: 'Folder to list.' },
-                user: userParam,
-            },
-            required: ['storage'],
-        },
-        handler: toolList,
-    },
-    {
-        name: 'storage_file_read',
-        description: 'Read a text file of a storage.',
-        inputSchema: {
-            type: 'object',
-            properties: { storage: storageParam, path: pathParam, user: userParam },
-            required: ['storage', 'path'],
-        },
-        handler: toolRead,
-    },
-    {
-        name: 'storage_file_write',
-        description:
-            'Create or overwrite files in a storage; folders on the path are created. Either `content` (text) at `path`, or `local`: a file or folder on this machine, uploaded as is (binary too) to `path` (a file defaults to its own name; a folder goes under `path`, or the root). Use `local` for anything big: CSV to import, images, product code with its node_modules.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                storage: storageParam,
-                path: pathParam,
-                content: { type: 'string', description: 'Text content of the file at `path`.' },
-                local: {
-                    type: 'string',
-                    description:
-                        'Local file or folder to upload instead of `content` (up to 50 MB per file and 200 MB per call).',
-                },
-                user: userParam,
-            },
-            required: ['storage'],
-        },
-        handler: toolWrite,
-    },
-    {
-        name: 'storage_file_delete',
-        description: 'Delete a file of a storage. Permanent: confirm with the user first.',
-        inputSchema: {
-            type: 'object',
-            properties: { storage: storageParam, path: pathParam, user: userParam },
-            required: ['storage', 'path'],
-        },
-        handler: toolDelete,
-    },
-];