@thinger-io/cli-core 0.1.0 → 0.2.0

package/lib/mcp/tools-dashboards.js

@@ -0,0 +1,123 @@
+// @ts-check
+import { DASHBOARD_TARGETS, collectFiles, publishApp } from '../dashboard.js';
+import { inputError } from '../errors.js';
+
+async function toolPublish(args) {
+    if (args.dir && args.files) throw inputError('pass dir or files, not both');
+    if (args.files) {
+        if (typeof args.files !== 'object' || Array.isArray(args.files)) {
+            throw inputError('files must be an object of { "path": "content" }');
+        }
+        for (const [file, content] of Object.entries(args.files)) {
+            if (typeof content !== 'string') throw inputError(`files["${file}"] must be a string`);
+        }
+    }
+    const result = await publishApp({
+        storage: args.storage,
+        files: args.dir ? collectFiles(args.dir) : args.files,
+        prune: args.prune,
+        to: args.to,
+        preview: args.preview,
+        point: args.point,
+        bump: args.bump,
+        user: args.user,
+    });
+    const lines = [];
+    if (result.uploaded.length) {
+        lines.push(
+            `Uploaded ${result.uploaded.length} file(s) to ${result.storageCreated ? 'new public' : 'public'} storage ${result.storage}` +
+                (result.deleted.length
+                    ? `; deleted ${result.deleted.length} no longer in the app.`
+                    : '.'),
+        );
+    }
+    for (const p of result.pointed) lines.push(`${p.to} → ${p.url}\n  open: ${p.open}`);
+    if (!result.pointed.length && args.point !== false) {
+        lines.push(
+            'No dashboard was pointed: those already showing this storage load the new files the next time they open.',
+        );
+    }
+    if (result.previews.length) {
+        const until = new Date(result.previews[0].expire)
+            .toISOString()
+            .slice(0, 16)
+            .replace('T', ' ');
+        lines.push(
+            `Preview links (standalone pages for a browser, read-only token valid until ${until} UTC; servers that ignore token expiry keep it until the next preview replaces it; the previous preview links of this storage stop working):`,
+        );
+        for (const p of result.previews) {
+            lines.push(`${p.to} → ${p.url}\n  layout check (website and phone sizes): ${p.layout}`);
+        }
+    }
+    return { content: [{ type: 'text', text: lines.join('\n') }], isError: false };
+}
+
+export const tools = [
+    {
+        name: 'dashboard_publish',
+        description: `Publish an HTML app to a public storage and point dashboards at it. Upload (dir or files) and point (to) are both optional: upload a new build, point more dashboards at an app already uploaded, or both. Read the dashboard SDK reference with {tool:resource_describe} type "dashboard" first.
+
+Destinations (to): {dashboard} for the dashboards collection (created if missing, empty context), or {type, id} to set the "dashboard" property of a device, product, asset_type, asset_group or project, whose id the page gets in Thinger.context. Each may open its own entry page and an initial hash route.
+
+One app can serve many dashboards: name its storage (e.g. app_<project>) and upload the build output folder with prune: true (hashed file names change between builds). Dashboards point at the storage folder (…/files/, served as the storage's index) or at another entry page by name, without version queries: files are served with no-cache and an ETag, so viewers always get the latest upload. Apps in the iframe: no <base> tag (relative asset paths resolve next to the entry page), hash routing (Angular: withHashLocation()), wait for Thinger.ready() before rendering (Angular: provideAppInitializer(() => Thinger.ready())), <script src="/sdk/0.1/thinger-dashboard.js"> in index.html (the SDK version the app was written for; /sdk/thinger-dashboard.js is always the latest), and no localStorage or cookies (opaque origin: keep state in properties through the SDK).`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                storage: {
+                    type: 'string',
+                    description:
+                        'Public storage of the app (created if missing). Required unless there is one destination.',
+                },
+                dir: {
+                    type: 'string',
+                    description:
+                        'Local folder to upload, subfolders included (e.g. dist/app/browser).',
+                },
+                files: {
+                    type: 'object',
+                    description: 'Or files inline: {"index.html": "<html>…"}.',
+                },
+                prune: {
+                    type: 'boolean',
+                    description: 'Delete files of the storage that are not in this upload.',
+                },
+                to: {
+                    type: 'array',
+                    description: 'Dashboards to point at the app.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            dashboard: { type: 'string', description: 'Collection dashboard id.' },
+                            type: { type: 'string', enum: DASHBOARD_TARGETS },
+                            id: { type: 'string' },
+                            entry: { type: 'string', description: 'Page (default index.html).' },
+                            route: {
+                                type: 'string',
+                                description: 'Initial route, e.g. "/devices".',
+                            },
+                            name: { type: 'string', description: 'Collection dashboard name.' },
+                        },
+                    },
+                },
+                bump: {
+                    type: 'boolean',
+                    description:
+                        'Add ?v=<publish time> to the dashboard urls so consoles that have the app open reload it at once (otherwise they get the new files on their next load).',
+                },
+                preview: {
+                    type: ['boolean', 'number'],
+                    description:
+                        'Also return standalone links to review or share each destination in a browser (whole page, scrollable, unlike the console iframe). true: valid 1 h; a number: that many hours (up to 720). Each link carries a read-only access token, one per app and project, replaced by the next preview (older links stop working); actions in the app (device resource calls, writes) answer 403 there. With only storage and preview, it links to the app without context.',
+                },
+                point: {
+                    type: 'boolean',
+                    description:
+                        'false: only build preview links for `to`, without pointing those dashboards again.',
+                },
+                user: { type: 'string', description: 'Account to act on (admin only).' },
+            },
+            required: [],
+        },
+        handler: toolPublish,
+    },
+];

package/lib/mcp/tools-devices.js

@@ -1,280 +1,134 @@
 // @ts-check
-import {
-    CREDENTIAL_DEVICE_TYPES,
-    DEVICE_TYPES,
-    createDevice,
-    deleteDevice,
-    generateDeviceCredentials,
-    getDevice,
-    getDevices,
-} from '../devices.js';
-import { setDeviceProduct } from '../product.js';
-import { inputError } from '../errors.js';
+import api from '../api.js';
+import { apiError, inputError } from '../errors.js';
+import { device, v1 } from '../paths.js';
+import { callDeviceResource, listDeviceResourcesWithSchemas } from '../resource.js';
 
-async function toolDevices(args) {
-    const query = args.query ? String(args.query).trim() : '';
-    const filter = query ? { name: query } : {};
-    const devices = await getDevices(filter, args.user);
-
-    // `connection.ts` is when the state last changed, so it reads as
-    // "connected since" for a live device and "offline since" for a dead
-    // one: it tells at a glance whether something dropped a minute ago
-    // or back in July.
-    const since = (d) => {
-        const ts = d.connection?.ts;
-        if (!ts) return '';
-        const when = new Date(ts).toISOString().replace('T', ' ').slice(0, 16);
-        return d.connection?.active ? `  connected since ${when}` : `  offline since ${when}`;
-    };
-
-    const renderLine = (d) => {
-        const status = d.connection?.active ? 'online ' : 'offline';
-        const label = d.name ? ` (${d.name})` : '';
-        const type = d.type && d.type !== 'Generic' ? ` <${d.type}>` : '';
-        const product = d.product ? ` [${d.product}]` : '';
-        return `${status}  ${d.device ?? '(record without id)'}${label}${type}${product}${since(d)}`;
-    };
-
-    if (!query) {
-        return {
-            content: [
-                { type: 'text', text: devices.map(renderLine).join('\n') || 'No devices found' },
-            ],
-            isError: false,
-        };
-    }
+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),
+    );
 
-    const limit = Number.isFinite(args.limit) && args.limit > 0 ? Math.floor(args.limit) : 20;
-    const limited = devices.slice(0, limit);
-    const header =
-        devices.length === 0
-            ? `No devices match "${query}"`
-            : `${devices.length} match(es) for "${query}"${devices.length > limit ? ` — showing first ${limit}` : ''}:`;
-    return {
-        content: [{ type: 'text', text: [header, ...limited.map(renderLine)].join('\n') }],
-        isError: false,
-    };
+function requireDevice(args) {
+    if (!args.device) throw inputError('device is required');
+    return args.device;
 }
 
-async function toolDeviceInfo(args) {
-    const device = args.device_id;
-    if (!device) throw inputError('device_id is required');
-    const record = await getDevice(device, args.user);
-    const c = record.connection || {};
-    const meta = [];
-    const add = (key, value) => {
-        if (value !== undefined && value !== null && value !== '') {
-            meta.push(`${(key + ':').padEnd(15)}${value}`);
-        }
-    };
-    add('device', record.device);
-    add('name', record.name);
-    add('type', record.type);
-    add('protocol', record.protocol);
-    add('product', record.product);
-    add('asset_group', record.asset_group);
-    add('asset_type', record.asset_type);
-    add('description', record.description);
-    add('enabled', record.enabled);
-    if (record.labels && Object.keys(record.labels).length) {
-        add('labels', JSON.stringify(record.labels));
-    }
-    if (record.connection) {
-        const since = c.ts ? ` since ${new Date(c.ts).toISOString()}` : '';
-        add('connection', `${c.active ? 'online' : 'offline'}${since}`);
-        add('ip_address', c.ip ?? c.ip_address);
-    }
-    // Everything else the server reports (traffic counters, location,
-    // security, timeouts…) as JSON: the fields vary with the device type.
-    const shown = new Set(['ts', 'active', 'ip', 'ip_address']);
-    const rest = Object.fromEntries(Object.entries(c).filter(([k]) => !shown.has(k)));
-    const text = Object.keys(rest).length
-        ? `${meta.join('\n')}\n\nconnection details:\n${JSON.stringify(rest, null, 2)}`
-        : meta.join('\n');
-    return { content: [{ type: 'text', text }], isError: false };
+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 toolDeviceCreate(args) {
-    if (!args.device_id) throw inputError('device_id is required');
-    const type = args.type || 'Generic';
-    if (!DEVICE_TYPES.includes(type)) {
-        throw inputError(`type must be one of ${DEVICE_TYPES.join(', ')} (got "${type}")`);
-    }
-    const needsCredentials = CREDENTIAL_DEVICE_TYPES.has(type);
-    if (!needsCredentials && args.credentials) {
-        throw inputError(`${type} devices do not take credentials`);
-    }
-    if (needsCredentials && args.credentials && args.credentials.length < 6) {
-        throw inputError('credentials must be at least 6 characters');
-    }
-    const credentials = needsCredentials
-        ? args.credentials || generateDeviceCredentials()
-        : undefined;
-    const sent = await createDevice(
-        {
-            device: args.device_id,
-            type,
-            name: args.name,
-            description: args.description,
-            credentials,
-            product: args.product,
-            asset_group: args.asset_group,
-            asset_type: args.asset_type,
-            labels: args.labels,
-        },
-        args.user,
+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,
+        }),
     );
-    const lines = [`Created ${type} device "${sent.device}".`];
-    if (credentials) {
-        lines.push(
-            `credentials: ${credentials}`,
-            '',
-            'The server stores credentials hashed: this is the only time they can be read. Hand them to whoever flashes the device now.',
-        );
-    }
-    return { content: [{ type: 'text', text: lines.join('\n') }], isError: false };
 }
 
-async function toolDeviceSetProduct(args) {
-    const device = args.device_id;
-    if (!device) throw inputError('device is required');
-    if (args.product === undefined || args.product === null)
-        throw inputError('product is required (pass "" to unassign)');
-    await setDeviceProduct(device, args.product, args.user);
-    const label =
-        args.product === ''
-            ? `Unassigned ${device} from its product.`
-            : `Assigned ${device} → product "${args.product}".`;
-    return { content: [{ type: 'text', text: label }], isError: false };
+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 toolDeviceDelete(args) {
-    const device = args.device_id;
-    if (!device) throw inputError('device is required');
-    const removed = await deleteDevice(device, args.user);
-    return {
-        content: [
-            {
-                type: 'text',
-                text: removed ? `Deleted ${device}` : `Device ${device} did not exist`,
-            },
-        ],
-        isError: false,
-    };
+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: 'devices',
+        name: 'device_resource_list',
         description:
-            'List devices with their online/offline status (and since when), type <in angle brackets> when not Generic, and assigned [product]. Pass `query` to filter by device id or name (case-insensitive regex on the server side, so plain substrings, anchors, wildcards and alternations all work). Use this before any other device tool to discover or narrow down ids.',
+            "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: {
-                query: {
-                    type: 'string',
-                    description:
-                        'Optional pattern matched against device id and name. Plain substrings work ("office"); regex metacharacters are also honoured ("^raspberry", "mac|book"). Case-insensitive.',
-                },
-                limit: {
-                    type: 'number',
-                    description:
-                        'Maximum matches to return when `query` is set (default: 20). Ignored when listing without a query.',
-                },
-                user: {
-                    type: 'string',
-                    description:
-                        'API user (for admin impersonation). Omit to use your own account.',
-                },
-            },
-            required: [],
+            properties: { device: deviceParam, user: userParam },
+            required: ['device'],
         },
-        handler: toolDevices,
+        handler: toolResourceList,
     },
     {
-        name: 'device_info',
+        name: 'device_resource_call',
         description:
-            'Get the server record of a device: type, protocol, assigned product, asset group/type, labels, description, and its connection state (online/offline since when, IP address, traffic counters and whatever else the server reports for that device type).',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                device_id: { type: 'string', description: 'Device ID' },
-                user: { type: 'string', description: 'API user' },
-            },
-            required: ['device_id'],
-        },
-        handler: toolDeviceInfo,
-    },
-    {
-        name: 'device_create',
-        description: `Register a new device on the server.
-
-Types: "Generic" (default; devices using the platform client libraries over IOTMP), "MQTT", "HTTP" (devices pushing data through HTTP callbacks), "Virtual", "Subdevice". Generic and MQTT devices authenticate with credentials: pass \`credentials\` (6+ characters) or omit them to get random ones generated. The server stores them hashed, so the response is the only place they can be read — give them to the user right away.
-
-Pass \`product\` to have the device inherit that product's profile (buckets, API resources, property handlers) from the start. Fails with code already_exists if the id is taken.`,
+            '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_id: {
-                    type: 'string',
-                    description: 'New device ID (letters, digits, dash, underscore).',
-                },
-                type: {
-                    type: 'string',
-                    enum: ['Generic', 'MQTT', 'HTTP', 'Virtual', 'Subdevice'],
-                    description: 'Device type. Default: Generic.',
-                },
-                credentials: {
-                    type: 'string',
-                    description:
-                        'Device credentials for Generic/MQTT devices (6+ characters). Omit to generate random ones.',
-                },
-                name: { type: 'string', description: 'Display name.' },
-                description: { type: 'string', description: 'Free-form description.' },
-                product: { type: 'string', description: 'Product ID to assign the device to.' },
-                asset_group: { type: 'string', description: 'Asset group ID.' },
-                asset_type: { type: 'string', description: 'Asset type ID.' },
-                labels: {
-                    type: 'object',
-                    description: 'Key/value string labels, e.g. {"site": "madrid"}.',
-                    additionalProperties: { type: 'string' },
-                },
-                user: { type: 'string', description: 'API user' },
+                device: deviceParam,
+                resource: { type: 'string', description: 'Resource name.' },
+                inputs: { description: 'Input value or object the resource declares.' },
+                user: userParam,
             },
-            required: ['device_id'],
+            required: ['device', 'resource'],
         },
-        handler: toolDeviceCreate,
+        handler: toolResourceCall,
     },
     {
-        name: 'device_set_product',
+        name: 'device_data_send',
         description:
-            "Assign a device to a product, or unassign it by passing an empty string. Devices inherit the product's API resources and profile configuration (scripts, buckets, etc.) once assigned. Typical flow: configure the product profile with {tool:product_profile_bucket_set} / {tool:product_profile_api_set}, then assign devices here.",
+            '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_id: { type: 'string', description: 'Device ID' },
-                product: {
-                    type: 'string',
-                    description: 'Product ID to assign, or empty string "" to unassign.',
-                },
-                user: { type: 'string', description: 'API user' },
+                device: deviceParam,
+                data: { description: 'JSON payload, e.g. {"temperature": 21.5}.' },
+                user: userParam,
             },
-            required: ['device_id', 'product'],
+            required: ['device', 'data'],
         },
-        handler: toolDeviceSetProduct,
+        handler: toolDataSend,
     },
     {
-        name: 'device_delete',
+        name: 'device_overview',
         description:
-            'Delete a device record from the platform. Destructive and irreversible — drops the device, its server-side metadata, and stored properties. A device still running with the old credentials will fail to connect until it is registered again. Idempotent: returns success when the device was already absent.',
+            '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: {
-                device_id: { type: 'string', description: 'Device ID to delete.' },
-                user: { type: 'string', description: 'API user' },
+                locations: { type: 'boolean', description: 'Include device locations.' },
+                user: userParam,
             },
-            required: ['device_id'],
+            required: [],
         },
-        handler: toolDeviceDelete,
+        handler: toolOverview,
     },
 ];

package/lib/mcp/tools-misc.js

@@ -0,0 +1,48 @@
+// @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: those this CLI ships and those the server publishes (the platform's concepts, how-tos, the dashboard SDK reference…). 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

@@ -0,0 +1,63 @@
+// @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,
+    },
+];