@thinger-io/cli-core 0.2.1 → 0.4.0

package/lib/dashboard.js

@@ -5,13 +5,15 @@ import path from 'node:path';
 import api from './api.js';
 import { TIMEOUTS } from './constants.js';
 import { readConfig, serverURL } from './config.js';
+import { checkSdk } from './dashboard-sdk.js';
 import { apiError, inputError } from './errors.js';
+import { identity } from './identity.js';
 import { v1, v2, v3 } from './paths.js';
 
 /**
  * Url-source dashboards: an HTML page (plus its scripts, styles, images)
  * kept in a file storage and rendered by the console in an iframe, where it
- * talks to the server through the dashboard SDK (`/sdk/0.1/thinger-dashboard.js`).
+ * talks to the server through the dashboard SDK (`@thinger-io/dashboard-sdk`, in its build).
  *
  * The storage must be public: the iframe cannot send an Authorization
  * header when it loads the page's files. Only the code is exposed; every API
@@ -200,7 +202,7 @@ async function remove(storage, files, user) {
  */
 
 /** @param {Destination} d */
-function checkDestination(d) {
+export function checkDestination(d) {
     if (!d || typeof d !== 'object') throw inputError('each destination must be an object');
     if (!d.dashboard === !(d.type || d.id)) {
         throw inputError('a destination is either {dashboard} or {type, id}');
@@ -334,7 +336,25 @@ export function previewTokenId(storage, project) {
  * @returns {Promise<{ token: string, accessToken: string, expire: number }>}
  */
 export async function previewToken(storage, { project, hours = PREVIEW_HOURS, user } = {}) {
-    const token = previewTokenId(storage, project);
+    return replaceToken(previewTokenId(storage, project), {
+        name: `Preview of ${storage}${project ? ` (${project})` : ''}`,
+        allow: PREVIEW_ALLOW,
+        hours,
+        project,
+        user,
+    });
+}
+
+/**
+ * Create an access token valid for `hours`, replacing the one with the same
+ * id: the expiry is signed into the token, so it is renewed by deleting it
+ * and creating it again. Inside a project (?project=) it only works there.
+ *
+ * @param {string} token  Token id.
+ * @param {{ name: string, allow: object, hours: number, project?: string, user?: string | null }} opts
+ * @returns {Promise<{ token: string, accessToken: string, expire: number }>}
+ */
+export async function replaceToken(token, { name, allow, hours, project, user }) {
     const params = project ? { project } : undefined;
     try {
         await api.delete(`${v1(user)}/tokens/${token}`, { params });
@@ -346,13 +366,7 @@ export async function previewToken(storage, { project, hours = PREVIEW_HOURS, us
     try {
         res = await api.post(
             `${v1(user)}/tokens`,
-            {
-                token,
-                name: `Preview of ${storage}${project ? ` (${project})` : ''}`,
-                enabled: true,
-                allow: PREVIEW_ALLOW,
-                expire,
-            },
+            { token, name, enabled: true, allow, expire },
             { params },
         );
     } catch (e) {
@@ -375,26 +389,16 @@ export async function previewToken(storage, { project, hours = PREVIEW_HOURS, us
 export function previewUrl(url, token, context = {}) {
     const params = new URLSearchParams({ thinger_token: token });
     for (const [key, id] of Object.entries(context)) if (id) params.set(`thinger_${key}`, id);
-    const [base, route] = url.split('#');
+    const hash = url.indexOf('#');
+    const base = hash < 0 ? url : url.slice(0, hash);
+    const route = hash < 0 ? '' : url.slice(hash + 1);
+    // The route goes first in the fragment: it must not add parameters of its own.
+    if (/[&#]/.test(route)) throw inputError(`a route has no "&" or "#": ${route}`);
     return `${base}#${route || '/'}&${params}`;
 }
 
-/** Sizes the layout check opens an app at: website embeds and a phone. */
-export const LAYOUT_SIZES = '1150x758,950x678,380x598';
-
-/**
- * The server's layout harness (/sdk/preview.html) around a preview link:
- * it shows the app at several sizes and lists layout issues.
- *
- * @param {string} base  Server url.
- * @param {string} url   Standalone preview link.
- */
-export function layoutUrl(base, url) {
-    return `${base}/sdk/preview.html#src=${encodeURIComponent(url)}&sizes=${LAYOUT_SIZES}`;
-}
-
 /** The SDK context key each destination type fills. */
-const CONTEXT_KEYS = {
+export const CONTEXT_KEYS = {
     device: 'device',
     product: 'product',
     asset_type: 'type',
@@ -466,7 +470,8 @@ async function point(d, url, user) {
  *   point?: boolean,
  *   bump?: boolean,
  *   user?: string | null,
- * }} opts
+ *   dir?: string,
+ * }} opts  `dir`: the folder the files come from, to check the SDK it was built with.
  */
 export async function publishApp({
     storage,
@@ -477,6 +482,7 @@ export async function publishApp({
     point: repoint = true,
     bump = false,
     user,
+    dir,
 }) {
     if (!Array.isArray(to)) throw inputError('to must be a list of destinations');
     to.forEach(checkDestination);
@@ -589,7 +595,6 @@ export async function publishApp({
             previews.push({
                 to: d.dashboard ? `dashboard ${d.dashboard}` : d.type ? `${d.type} ${d.id}` : 'app',
                 url,
-                layout: layoutUrl(base, url),
                 expire,
             });
         }
@@ -601,5 +606,143 @@ export async function publishApp({
         deleted,
         pointed,
         previews,
+        sdk: files ? await checkSdk({ dir, files }) : [],
     };
 }
+
+/**
+ * A destination written as `kind:id` on the command line: `dashboard:sales`,
+ * `device:gw1`, `product:meter`, `asset_type:pump`, `asset_group:plant`,
+ * `project:demo`.
+ *
+ * @param {string} value
+ * @returns {Destination}
+ */
+export function parseDestination(value) {
+    const m = /^([a-z_]+):(.+)$/.exec(String(value));
+    const kinds = ['dashboard', ...DASHBOARD_TARGETS];
+    if (!m || !kinds.includes(m[1])) {
+        throw inputError(
+            `a destination is <${kinds.join('|')}>:<id>, e.g. device:gw1; got "${value}"`,
+        );
+    }
+    const d = m[1] === 'dashboard' ? { dashboard: m[2] } : { type: m[1], id: m[2] };
+    checkDestination(d);
+    return d;
+}
+
+/** The SDK context a destination gives its app (empty for collection dashboards). */
+export function destinationContext(d) {
+    return d?.type ? { [CONTEXT_KEYS[d.type]]: d.id } : {};
+}
+
+/** File, in an app's folder, describing how it is published and developed. */
+export function manifestName() {
+    return `${identity().name}.json`;
+}
+
+/**
+ * The `dashboard` section of an app's manifest (`<cli>.json`), or null when
+ * there is none. Paths in it are relative to the manifest.
+ *
+ *   {
+ *     "dashboard": {
+ *       "dir": "dist/app/browser",      // build output to publish
+ *       "storage": "app_greenhouse",
+ *       "prune": true,
+ *       "to": [{ "type": "device", "id": "gh_01", "route": "/" }],
+ *       "dev": { "url": "http://localhost:4200/",   // the app's dev server
+ *                "context": { "device": "gh_01" } } // default: the first destination's
+ *     }
+ *   }
+ *
+ * @param {string} [file]  Manifest path (default: <cli>.json in the working folder).
+ * @returns {{ file: string, dir?: string, storage?: string, prune?: boolean, entry?: string,
+ *   to?: Destination[], dev?: { url?: string, context?: Record<string, string>,
+ *   route?: string, hours?: number } } | null}
+ */
+export function readManifest(file) {
+    const full = path.resolve(file || manifestName());
+    if (!fs.existsSync(full)) {
+        if (file) throw inputError(`No such file: ${file}`);
+        return null;
+    }
+    let json;
+    try {
+        json = JSON.parse(fs.readFileSync(full, 'utf8'));
+    } catch (e) {
+        throw inputError(`${full} is not valid JSON: ${e.message}`);
+    }
+    const section = json?.dashboard;
+    if (!section || typeof section !== 'object') {
+        if (file) throw inputError(`${full} has no "dashboard" section`);
+        return null;
+    }
+    if (section.to !== undefined) {
+        if (!Array.isArray(section.to)) throw inputError(`${full}: dashboard.to must be a list`);
+        section.to.forEach(checkDestination);
+    }
+    const base = path.dirname(full);
+    const dir = section.dir ? path.resolve(base, String(section.dir)) : undefined;
+    // A manifest may come with someone else's repository: what it publishes
+    // stays inside its folder (a folder outside it is passed on the command line).
+    if (dir) {
+        const rel = path.relative(base, dir);
+        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+            throw inputError(`${full}: dashboard.dir must be inside its folder`);
+        }
+    }
+    const types = { storage: 'string', prune: 'boolean', entry: 'string', dev: 'object' };
+    for (const [key, type] of Object.entries(types)) {
+        if (section[key] !== undefined && typeof section[key] !== type) {
+            throw inputError(`${full}: dashboard.${key} must be a ${type}`);
+        }
+    }
+    const dev = section.dev || {};
+    const devTypes = { url: 'string', context: 'object', route: 'string', hours: 'number' };
+    for (const [key, type] of Object.entries(devTypes)) {
+        if (dev[key] !== undefined && (typeof dev[key] !== type || dev[key] === null)) {
+            throw inputError(`${full}: dashboard.dev.${key} must be a ${type}`);
+        }
+    }
+    return { ...section, file: full, dir };
+}
+
+/**
+ * Human summary of a publishApp result, as the CLI prints it and the MCP
+ * tool answers it.
+ *
+ * @param {Awaited<ReturnType<typeof publishApp>>} result
+ * @param {{ point?: boolean }} [opts]
+ */
+export function publishSummary(result, { point: repoint = true } = {}) {
+    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 && repoint !== 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}`);
+        }
+    }
+    for (const note of result.sdk || []) lines.push(`SDK: ${note}`);
+    return lines.join('\n');
+}

package/lib/docs.js

@@ -1,33 +1,67 @@
 // @ts-check
 import fs from 'node:fs';
-import api from './api.js';
-import { apiError, inputError } from './errors.js';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SDK_PACKAGE, cliSdkPackageDir } from './dashboard-sdk.js';
+import { inputError } from './errors.js';
 
 /**
- * Documentation the server publishes for agents and app developers: a
- * guide to the platform's concepts, the dashboard SDK reference, its
- * TypeScript declarations… listed in the server's own index
- * (`/sdk/docs.json`), so a new guide reaches the model by being added
- * there, without a new CLI release. Always read from the server the profile
- * points at, so it matches the version it runs.
+ * Documentation for agents and app developers, all local: the platform's
+ * guides that cli-core ships (concepts, product code, server
+ * administration), the dashboard SDK's reference and types from its npm
+ * package, and the guides a CLI adds for its own platform. None depends on
+ * the server: where a feature needs a given server version the text says
+ * "since Thinger X", and the server tells its version at
+ * `/v1/server/version`.
  *
  * @typedef {object} Doc
  * @property {string} id
  * @property {string} title
  * @property {string} [description]
- * @property {string} [path]  Path on the same server (`/sdk/…`), for the server's documents.
- * @property {string} [file]  Local file, for the documents a CLI ships.
+ * @property {string} [file]  Local file.
+ * @property {string[]} [files]  Local files read as one document (the SDK's type declarations).
  * @property {string} [format] markdown, typescript, json…
  */
 
+const DOCS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'docs');
+
+/** The platform's guides, shipped with cli-core. */
+/** @type {Doc[]} */
+export const PLATFORM_DOCS = [
+    {
+        id: 'concepts',
+        title: 'Thinger concepts',
+        description:
+            'How projects, devices (incl. Virtual), products, buckets (reading, importing history), asset types and groups, properties, alarms (rule syntax), endpoints, storages, tokens, dashboards and events relate, and which data source to use for each need.',
+        file: path.join(DOCS_DIR, 'thinger-concepts.md'),
+        format: 'markdown',
+    },
+    {
+        id: 'product-code',
+        title: 'Product code',
+        description:
+            "JavaScript run by a product's profile: functions that compute resource values (simulated devices), payload transforms, device_id_resolver; runtime, signatures, placeholders, state between calls, logging and limits.",
+        file: path.join(DOCS_DIR, 'thinger-product-code.md'),
+        format: 'markdown',
+    },
+    {
+        id: 'server-admin',
+        title: 'Server administration',
+        description:
+            'For admins: host settings and restarts, custom domains with their brand (DNS, certificates, logos, email), user accounts, OAuth clients, identity providers and proxies, with their side effects and risks.',
+        file: path.join(DOCS_DIR, 'thinger-server-admin.md'),
+        format: 'markdown',
+    },
+];
+
 /** @type {Doc[]} */
 let cliDocs = [];
 
 /**
- * Documents the CLI itself ships (its own platform's guides), listed next
- * to the server's. They travel with the CLI because they describe what the
- * CLI implements on top of the server. Ids must not clash with the server's:
- * the CLI's win.
+ * Documents the CLI itself ships (its own platform's guides), listed first.
+ * They travel with the CLI because they describe what the CLI implements on
+ * top of the server. On an id clash with cli-core's documents, the CLI's
+ * win.
  *
  * @param {Array<{ id: string, title: string, description?: string, format?: string, file: string | URL }>} docs
  */
@@ -39,113 +73,74 @@ export function defineCliDocs(docs = []) {
     }
     cliDocs = docs.map((d) => ({
         ...d,
-        file: d.file instanceof URL ? d.file.pathname : String(d.file),
+        file: d.file instanceof URL ? fileURLToPath(d.file) : String(d.file),
         format: d.format || 'markdown',
     }));
 }
 
-const INDEX = '/sdk/docs.json';
-
-/** Documents servers published before the index existed: looked for when there is no index. */
-/** @type {Doc[]} */
-export const FALLBACK_DOCS = [
-    {
-        id: 'concepts',
-        title: 'Thinger concepts',
-        description: 'How the platform pieces relate, and which data source to use for each need.',
-        path: '/sdk/thinger-concepts.md',
-        format: 'markdown',
-    },
-    {
-        id: 'dashboard-sdk',
-        title: 'Dashboard SDK reference',
-        description: 'Build url dashboards and web apps that run inside the console.',
-        path: '/sdk/thinger-dashboard.md',
-        format: 'markdown',
-    },
-    {
-        id: 'dashboard-sdk-types',
-        title: 'Dashboard SDK TypeScript declarations',
-        description: 'Type declarations for the global Thinger object.',
-        path: '/sdk/thinger-dashboard.d.ts',
-        format: 'typescript',
-    },
-];
-
-/** A path on the profile's own server: never another host, never a parent folder. */
-const LOCAL_PATH = /^\/(?!\/)[^?#\\]*$/;
-
-export function validDoc(d) {
-    return (
-        d &&
-        typeof d.id === 'string' &&
-        /^[a-z0-9][a-z0-9._-]*$/i.test(d.id) &&
-        typeof d.path === 'string' &&
-        LOCAL_PATH.test(d.path) &&
-        !d.path.split('/').includes('..')
-    );
-}
-
-/** Text of a file on the server, whatever type it is labelled with (dev servers say video/mp2t for .ts). */
-async function readText(path) {
-    const res = await api.get(path, { transformResponse: [(x) => x], responseType: 'text' });
-    return String(res.data ?? '');
-}
-
 /**
- * The documents the server publishes, from its index; the known ones when
- * it has no index.
+ * The dashboard SDK's documents, from its npm package: the project's (the
+ * version the app uses), else the CLI's own.
  *
- * @returns {Promise<Doc[]>}
+ * @returns {Doc[]}
  */
-async function listServerDocs() {
-    let raw;
-    try {
-        raw = await readText(INDEX);
-    } catch (e) {
-        if (e.response?.status === 404) return publishedFallbacks();
-        throw apiError(e);
-    }
-    let docs;
+function sdkDocs() {
+    const dir = cliSdkPackageDir();
+    if (!dir) return [];
+    let version;
     try {
-        docs = JSON.parse(raw).docs;
+        version = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).version;
     } catch {
-        throw inputError(`The server's documentation index (${INDEX}) is not valid JSON`);
+        return [];
     }
-    return Array.isArray(docs)
-        ? docs.filter(validDoc).map((d) => ({ ...d, title: d.title || d.id }))
+    /** @type {Doc[]} */
+    const docs = [];
+    const readme = path.join(dir, 'README.md');
+    if (fs.existsSync(readme)) {
+        docs.push({
+            id: 'dashboard-sdk',
+            title: `Dashboard SDK reference (${SDK_PACKAGE} ${version})`,
+            description:
+                'Build dashboard apps (React, Angular…) on the SDK package: installing it, the console and standalone modes, routing, context and every call.',
+            file: readme,
+            format: 'markdown',
+        });
+    }
+    const dist = path.join(dir, 'dist');
+    const declarations = fs.existsSync(dist)
+        ? fs.readdirSync(dist).filter((f) => f.endsWith('.d.ts'))
         : [];
+    if (declarations.includes('index.d.ts')) {
+        const first = ['index.d.ts', 'types.d.ts'];
+        const order = [
+            ...first.filter((f) => declarations.includes(f)),
+            ...declarations.filter((f) => !first.includes(f)).sort(),
+        ];
+        docs.push({
+            id: 'dashboard-sdk-types',
+            title: `Dashboard SDK TypeScript declarations (${SDK_PACKAGE} ${version})`,
+            description:
+                'Type declarations of the SDK (index.d.ts, then the data types and each module); they come with the package.',
+            files: order.map((f) => path.join(dist, f)),
+            format: 'typescript',
+        });
+    }
+    return docs;
 }
 
 /**
- * Every document available: the CLI's own, then the server's. When the
- * server cannot be read, the CLI's alone (and the error if there are none).
+ * Every document available: the CLI's own, the platform's, then the
+ * dashboard SDK's (from its package). Ids are unique: the first wins.
  *
  * @returns {Promise<Doc[]>}
  */
 export async function listDocs() {
-    let server;
-    try {
-        server = await listServerDocs();
-    } catch (e) {
-        if (!cliDocs.length) throw e;
-        server = [];
+    /** @type {Doc[]} */
+    const docs = [];
+    for (const d of [...cliDocs, ...PLATFORM_DOCS, ...sdkDocs()]) {
+        if (!docs.some((x) => x.id === d.id)) docs.push(d);
     }
-    const own = new Set(cliDocs.map((d) => d.id));
-    return [...cliDocs, ...server.filter((d) => !own.has(d.id))];
-}
-
-/** Without an index, the known documents this server actually serves. */
-async function publishedFallbacks() {
-    const served = await Promise.all(
-        FALLBACK_DOCS.map((d) =>
-            readText(d.path).then(
-                () => true,
-                () => false,
-            ),
-        ),
-    );
-    return FALLBACK_DOCS.filter((_, i) => served[i]);
+    return docs;
 }
 
 /**
@@ -162,15 +157,20 @@ export async function readDoc(id) {
             `Unknown document "${id}". Available: ${docs.map((d) => d.id).join(', ') || 'none'}.`,
         );
     }
-    if (doc.file) return { doc, text: fs.readFileSync(doc.file, 'utf8') };
-    try {
-        return { doc, text: await readText(doc.path) };
-    } catch (e) {
-        if (e.response?.status === 404) {
-            throw inputError(`This server does not publish "${doc.title}" (${doc.path}).`);
-        }
-        throw apiError(e);
+    if (doc.files) {
+        const text = doc.files
+            .map(
+                (f) =>
+                    `// ${path.basename(f)}\n` +
+                    fs
+                        .readFileSync(f, 'utf8')
+                        .replace(/^\/\/# sourceMappingURL=.*$/gm, '')
+                        .trim(),
+            )
+            .join('\n\n');
+        return { doc, text };
     }
+    return { doc, text: fs.readFileSync(/** @type {string} */ (doc.file), 'utf8') };
 }
 
 /** MIME type for a document format. */

package/lib/identity.js

@@ -31,6 +31,8 @@
  * @property {string | null} defaultServer  Server suggested by the login prompt.
  * @property {{ serverName: string, toolPrefix: string }} mcp
  *   MCP server name and the prefix every tool name gets (`<prefix>_devices`).
+ * @property {string} [npmPackage]  npm package of the CLI, run with npx by the CI workflow
+ *   `dashboard init --ci` writes (default: the package of its entry point).
  * @property {ProductTemplate} [productTemplate]
  *   Defaults for products created through the CLI or MCP, for platforms
  *   whose products need a given shape (a type, a bucket every device feeds).

package/lib/mcp/catalog.js

@@ -67,7 +67,7 @@ import { inputError } from '../errors.js';
  *   query has these params are kept that long per profile (slow, remote catalogs).
  * @property {Record<string, Action>} [actions]  Operations that are not CRUD, run with
  *   `resource_call`: verify a domain, restart a host, test an alarm rule…
- * @property {boolean} [sdk]       `resource_describe` adds the dashboard SDK reference, read from the server.
+ * @property {boolean} [sdk]       `resource_describe` adds the dashboard SDK reference (from its package, see docs.js).
  */
 
 const PROPERTY_NOTES =
@@ -173,7 +173,7 @@ export const CATALOG = {
         path: 'dashboards',
         id: 'dashboard',
         sdk: true,
-        notes: 'Build dashboards as HTML apps that use the dashboard SDK (source "url", the page at `url`): {tool:dashboard_publish} uploads the app and points the dashboard at it. Widget layouts (source "widgets") are legacy, made in the console editor: read them, do not create new ones. The SDK reference is under `sdk`; TypeScript apps get its declarations with {tool:doc_read} id "dashboard-sdk-types". A per-device, product, asset type, asset group or project dashboard is the "dashboard" property of that resource instead ({tool:dashboard_publish} with `target`).',
+        notes: 'Build dashboards as HTML apps that use the dashboard SDK (source "url", the page at `url`): {tool:dashboard_publish} uploads the app and points the dashboard at it. Start it with {tool:dashboard_init} (a TypeScript project on the npm package @thinger-io/dashboard-sdk), develop it on its own dev server with {tool:dashboard_dev} (a link that opens the local app against this server, in the context you pick), and publish it once it works. Widget layouts (source "widgets") are legacy, made in the console editor: read them, do not create new ones. The SDK reference is under `sdk`; its types come with the package (node_modules/@thinger-io/dashboard-sdk). A per-device, product, asset type, asset group or project dashboard is the "dashboard" property of that resource instead ({tool:dashboard_publish} with `to: [{type, id}]`).',
         ops: {
             list: 'Dashboard_List',
             create: 'Dashboard_Create',
@@ -339,6 +339,16 @@ export const CATALOG = {
             delete: 'Alarm_DeleteInstance',
             projects: 'Alarm_UpdateInstanceProjects',
         },
+        actions: {
+            stats: {
+                op: 'Alarm_ReadInstanceStats',
+                method: 'get',
+                path: 'stats',
+                on: 'collection',
+                description:
+                    'How many instances there are in each state: the health of the account at a glance, without listing them.',
+            },
+        },
         notes: 'States: 0 none, 1 active, 2 acknowledged, 3 latched, 4 shelved, 5 cleared; severities: 0 none, 1 low, 2 medium, 3 high, 4 critical. Acknowledge with update {state: 2, annotation?}; shelve with {state: 4, reactivation: {type: "timespan", timespan: {value, magnitude: "minute"|"hour"|"day"…}}}; clear with {state: 5} (a cleared alarm cannot be reactivated). Prefer clearing to deleting: delete removes the history. List filters: state and severity (arrays allowed), name, sort, order, and exact values of nested fields with dots: {"alarm.rule": "<rule id>"}, {"origin.id": "<device>"}, or both (servers before this filter ignore it and list every instance: check the records). `search` matches the instance id and the rule\'s name, not the rule id. A record: {instance, name, description, state, severity, alarm: {rule: <rule id>, group, type}, origin: {source: "device", id: <device>, name}, asset_type, asset_group, activation: {initiated, completed, detections}, normalization: {…}, evaluation: {last_values: {<source>: {<field>: value}}, last_completed}, notification: {last_type, total_completed, total_failed}, project}; times in unix ms.',
     },
     claim: {

package/lib/mcp/registry.js

@@ -7,7 +7,7 @@ import { tools as pluginTools } from './tools-plugins.js';
 import { tools as productTools } from './tools-products.js';
 import { resourceTools } from './tools-resource.js';
 import { tools as storageTools } from './tools-storage.js';
-import { FALLBACK_DOCS, docMimeType, listDocs, readDoc } from '../docs.js';
+import { docMimeType, listDocs, readDoc } from '../docs.js';
 import { identity } from '../identity.js';
 import { expandToolRefs, toolName } from './naming.js';
 
@@ -15,6 +15,10 @@ import { expandToolRefs, toolName } from './naming.js';
  * @typedef {object} ToolOptions
  * @property {Record<string, import('./resource-hooks.js').ResourceHooks>} [hooks]
  *   The CLI's own hooks on catalog types (see resource-hooks.js).
+ * @property {Record<string, import('./tools-resource.js').LocalType>} [types]
+ *   Resource types the CLI adds, served by the same `resource_*` tools.
+ * @property {Record<string, Record<string, import('./tools-resource.js').LocalAction>>} [actions]
+ *   Actions the CLI adds to resource types (the server's or its own).
  */
 
 /**
@@ -107,14 +111,12 @@ function expandSchema(node, known, where) {
 }
 
 /**
- * MCP resources: the documents the server of the default profile lists in
- * its documentation index (see docs.js), each as `<prefix>://<id>`. Listed
- * on every request, so a guide the server adds shows up without a CLI
- * release; the known ones when the server cannot be reached.
+ * MCP resources: the documents of docs.js (the platform's guides, the
+ * dashboard SDK's and the CLI's own), each as `<prefix>://<id>`.
  */
 export async function listResources() {
     const prefix = identity().mcp.toolPrefix;
-    const docs = await listDocs().catch(() => FALLBACK_DOCS);
+    const docs = await listDocs();
     return docs.map((d) => ({
         uri: `${prefix}://${d.id}`,
         name: d.id,

package/lib/mcp/server.js

@@ -25,13 +25,16 @@ import { defineCliDocs } from '../docs.js';
  *   tools?: Array<object>,
  *   instructions?: string,
  *   resourceHooks?: Record<string, import('./resource-hooks.js').ResourceHooks>,
+ *   resourceTypes?: Record<string, import('./tools-resource.js').LocalType>,
+ *   resourceActions?: Record<string, Record<string, import('./tools-resource.js').LocalAction>>,
  *   docs?: Parameters<typeof import('../docs.js').defineCliDocs>[0],
  * }} [opts]
  *   `version` is echoed in the `initialize` response's `serverInfo.version`;
  *   callers pass their `package.json#version` so the two never drift.
  *   `tools` are CLI-specific tools added to the generic set.
  *   `instructions` is the server-level guidance sent to the client.
- *   `resourceHooks` are the CLI's hooks on catalog types.
+ *   `resourceHooks` are the CLI's hooks on catalog types; `resourceTypes`
+ *   and `resourceActions` the types and actions it adds to the catalog.
  *   `docs` are the guides the CLI ships (see docs.js).
  */
 export async function startMCPServer({
@@ -39,11 +42,17 @@ export async function startMCPServer({
     tools: extra = [],
     instructions,
     resourceHooks,
+    resourceTypes,
+    resourceActions,
     docs,
 } = {}) {
     const { mcp } = identity();
     defineCliDocs(docs);
-    const tools = buildTools(extra, { hooks: resourceHooks });
+    const tools = buildTools(extra, {
+        hooks: resourceHooks,
+        types: resourceTypes,
+        actions: resourceActions,
+    });
 
     const server = new Server(
         {