@thinger-io/cli-core 0.3.0 → 0.4.1

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',

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';
 
@@ -111,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/tools-dashboards.js

@@ -1,6 +1,74 @@
 // @ts-check
-import { DASHBOARD_TARGETS, collectFiles, publishApp } from '../dashboard.js';
+import {
+    DASHBOARD_TARGETS,
+    checkDestination,
+    collectFiles,
+    destinationContext,
+    manifestName,
+    publishApp,
+    publishSummary,
+} from '../dashboard.js';
+import { devLink } from '../dashboard-dev.js';
+import { DEFAULT_TEMPLATE, initApp } from '../dashboard-init.js';
 import { inputError } from '../errors.js';
+import { toolName } from './naming.js';
+
+async function toolInit(args) {
+    if (args.to) checkDestination(args.to);
+    const r = await initApp({
+        dir: args.dir,
+        template: args.template,
+        to: args.to,
+        storage: args.storage,
+        from: args.from,
+        ci: args.ci,
+        install: args.install,
+    });
+    return {
+        content: [
+            {
+                type: 'text',
+                text: [
+                    `Created ${r.dir}: ${r.template} app on @thinger-io/dashboard-sdk ${r.dependency}, with ${manifestName()} (publishes ${r.build} to storage ${r.storage}${args.to ? '' : '; add destinations under dashboard.to'}) and AGENTS.md (how to develop it and the rules of the console's frame: read it).`,
+                    `Next: ${r.installed ? '' : 'npm install, then '}${r.devCommand} in the background (it serves ${r.devUrl}), ${toolName('dashboard_dev')} with url ${r.devUrl}${Object.keys(r.context).length ? '' : ' and a context'} and dir ${r.dir}, open the link with browser tools; when it works, npm run build and ${toolName('dashboard_publish')} with dir ${r.dir}/${r.build}.`,
+                ].join('\n'),
+            },
+        ],
+        isError: false,
+    };
+}
+
+async function toolDev(args) {
+    if (!args.url) throw inputError("pass url: the app's dev server, e.g. http://localhost:4200/");
+    if (args.to && args.context) throw inputError('pass to or context, not both');
+    if (args.to) checkDestination(args.to);
+    const dev = await devLink({
+        url: args.url,
+        context: args.to ? destinationContext(args.to) : args.context,
+        route: args.route ?? args.to?.route,
+        hours: args.hours,
+        user: args.user,
+        dir: args.dir || process.cwd(),
+        allowRemote: args.allow_remote === true,
+    });
+    const ctx = Object.entries(dev.context).map(([k, v]) => `${k} ${v}`);
+    const until = new Date(dev.expire).toISOString().slice(0, 16).replace('T', ' ');
+    return {
+        content: [
+            {
+                type: 'text',
+                text: [
+                    `Open this link in a browser: ${dev.link}`,
+                    `It opens ${dev.app} as a standalone page against ${dev.server} as ${dev.user}${ctx.length ? `, context ${ctx.join(', ')}` : ''}, with a temporary token (${dev.token}, full access, until ${until} UTC; a new link replaces it). Calls reach the real server: writes are real.`,
+                    ...dev.notes.map((n) => `Check: ${n}`),
+                    "The app's dev server reloads it on every change; its errors are in the browser console. Unlike in the console's sandboxed iframe, localStorage, cookies and a <base> tag work here, so do not rely on them.",
+                    `When it works, build it and publish the build once with ${toolName('dashboard_publish')}.`,
+                ].join('\n'),
+            },
+        ],
+        isError: false,
+    };
+}
 
 async function toolPublish(args) {
     if (args.dir && args.files) throw inputError('pass dir or files, not both');
@@ -21,45 +89,116 @@ async function toolPublish(args) {
         point: args.point,
         bump: args.bump,
         user: args.user,
+        dir: args.dir,
     });
-    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 };
+    return {
+        content: [{ type: 'text', text: publishSummary(result, { point: args.point }) }],
+        isError: false,
+    };
 }
 
 export const tools = [
+    {
+        name: 'dashboard_init',
+        description: `Create a dashboard app: a TypeScript project on @thinger-io/dashboard-sdk from one of the templates the SDK package ships (react by default, angular…), with its manifest for {tool:dashboard_dev} and {tool:dashboard_publish} and an AGENTS.md with the rules of the console's frame. Start every new dashboard app here instead of writing one from scratch.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                dir: {
+                    type: 'string',
+                    description:
+                        'New (or empty) folder for the app. Absolute, or relative to the folder this MCP server runs in.',
+                },
+                template: {
+                    type: 'string',
+                    description: `Template of the SDK package (default ${DEFAULT_TEMPLATE}).`,
+                },
+                to: {
+                    type: 'object',
+                    description:
+                        'Where it publishes, as in dashboard_publish: {type, id}, or {dashboard}. Its context is the one dashboard_dev uses.',
+                    properties: {
+                        dashboard: { type: 'string' },
+                        type: { type: 'string', enum: DASHBOARD_TARGETS },
+                        id: { type: 'string' },
+                    },
+                },
+                storage: {
+                    type: 'string',
+                    description: 'Storage it publishes to (default app_<folder>_<random>).',
+                },
+                from: {
+                    type: 'string',
+                    description:
+                        'SDK package to take the template from: a version or tag on npm (default the latest release), or a local folder or .tgz of it.',
+                },
+                ci: {
+                    type: 'boolean',
+                    description: 'Add a GitHub workflow that publishes it on push to main.',
+                },
+                install: { type: 'boolean', description: 'Run npm install.' },
+            },
+            required: ['dir'],
+        },
+        handler: toolInit,
+    },
+    {
+        name: 'dashboard_dev',
+        description: `Develop a dashboard app on its own dev server (ng serve, npm run dev…) against this server, then publish it once with {tool:dashboard_publish}, instead of publishing to try every change.
+
+Returns a link to the app's local url that opens it as a standalone page: the SDK reads the server, a temporary token and the context from the link and calls the server directly, so the app gets real data, its dev server reloads it on every change and its errors are in the browser console. Start the app's dev server first (the answer says when nothing answers at url). Open the link with the browser tools to see the app and read its console. Each call replaces the previous link's token.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                url: {
+                    type: 'string',
+                    description:
+                        'The app on its dev server, e.g. http://localhost:4200/ (a #route in it is kept).',
+                },
+                to: {
+                    type: 'object',
+                    description:
+                        'Destination whose context the app gets, as in dashboard_publish: {type, id}, or {dashboard} for a collection dashboard (no context).',
+                    properties: {
+                        dashboard: { type: 'string' },
+                        type: { type: 'string', enum: DASHBOARD_TARGETS },
+                        id: { type: 'string' },
+                        route: { type: 'string' },
+                    },
+                },
+                context: {
+                    type: 'object',
+                    description:
+                        'Or the SDK context itself: device, product, type, group, project ids.',
+                },
+                route: { type: 'string', description: 'Initial route, e.g. "/devices".' },
+                dir: {
+                    type: 'string',
+                    description:
+                        "The app's project folder, to check its SDK against this server (default: the folder this MCP server runs in).",
+                },
+                hours: {
+                    type: 'number',
+                    description: 'Hours the temporary token lasts (default 8, up to 168).',
+                },
+                allow_remote: {
+                    type: 'boolean',
+                    description:
+                        'Allow a url that is not on this machine. The link carries a full-access token: only for a dev server the user named and trusts.',
+                },
+                user: { type: 'string', description: 'Account to act on (admin only).' },
+            },
+            required: ['url'],
+        },
+        handler: toolDev,
+    },
     {
         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).`,
+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: start them with {tool:dashboard_init} (a TypeScript project on @thinger-io/dashboard-sdk with these rules set up and an AGENTS.md); hash routing, relative asset URLs and no <base> tag, render after Thinger.ready(), and no localStorage or cookies (opaque origin: keep state in properties through the SDK). Publish the build output folder; the answer warns when the app's SDK needs a newer server than this one, is not the latest on npm, or a page loads the deprecated script build (thinger-dashboard.js).`,
         inputSchema: {
             type: 'object',
             properties: {

package/lib/mcp/tools-misc.js

@@ -30,7 +30,7 @@ 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.",
+            "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.' } },

package/lib/mcp/tools-resource.js

@@ -548,8 +548,8 @@ export function resourceTools({ hooks: extraHooks, types: local = {}, actions: e
 
     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,
                 () => '',

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);
+        }
+    }
+}