@thinger-io/cli-core 0.3.0 → 0.4.0

package/lib/dashboard-sdk.js

@@ -0,0 +1,184 @@
+// @ts-check
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import api from './api.js';
+
+/**
+ * The dashboard SDK an app is built with (`@thinger-io/dashboard-sdk`,
+ * bundled into the app), against the server it is published to and the
+ * latest release on npm. The package declares the oldest server it works
+ * with and, per function, any newer one it needs (`compat.json`); the
+ * server tells its version at `/v1/server/version`. Everything here is
+ * advice: what cannot be read gives no note.
+ */
+
+export const SDK_PACKAGE = '@thinger-io/dashboard-sdk';
+const REGISTRY = 'https://registry.npmjs.org';
+const TIMEOUT_MS = 3000;
+/** Oldest SDK the console gives a token to (per-load frame key, PROTOCOL.md "Frame key"). */
+export const CONSOLE_MIN_SDK = '0.3.0';
+const SCRIPT_BUILD = /<script[^>]+src=["'][^"']*thinger-dashboard(?:\.min)?\.js["']/i;
+
+/** Numeric order of dotted versions (0.9 < 0.10); suffixes are ignored. */
+export function compareVersions(a, b) {
+    const x = numeric(a).split('.').map(Number);
+    const y = numeric(b).split('.').map(Number);
+    for (let i = 0; i < Math.max(x.length, y.length); i++) {
+        const d = (x[i] || 0) - (y[i] || 0);
+        if (d) return d;
+    }
+    return 0;
+}
+
+/** "7.3.4-152-g308cf54a-develop" → "7.3.4". */
+export function numeric(version) {
+    return /^\d+(?:\.\d+)*/.exec(String(version ?? ''))?.[0] || '0';
+}
+
+/**
+ * Folder of the SDK package installed for an app: searched in node_modules
+ * from `dir` up (a build folder sits inside its project).
+ *
+ * @param {string} dir
+ * @returns {string | null}
+ */
+export function sdkPackageDir(dir) {
+    let current = path.resolve(dir);
+    for (;;) {
+        const pkgDir = path.join(current, 'node_modules', ...SDK_PACKAGE.split('/'));
+        if (fs.existsSync(path.join(pkgDir, 'package.json'))) return pkgDir;
+        const parent = path.dirname(current);
+        if (parent === current) return null;
+        current = parent;
+    }
+}
+
+/**
+ * Folder of the SDK package for the CLI's own use (its documentation):
+ * the project's in the working folder, else the one the CLI installs.
+ *
+ * @returns {string | null}
+ */
+export function cliSdkPackageDir() {
+    const project = sdkPackageDir(process.cwd());
+    if (project) return project;
+    try {
+        return path.dirname(createRequire(import.meta.url).resolve(`${SDK_PACKAGE}/package.json`));
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The SDK package installed for an app: searched in node_modules from
+ * `dir` up (a build folder sits inside its project).
+ *
+ * @param {string} dir
+ * @returns {{ version: string, compat: { baseServer?: string, functions?: Record<string, string> } } | null}
+ */
+export function installedSdk(dir) {
+    const pkgDir = sdkPackageDir(dir);
+    if (!pkgDir) return null;
+    try {
+        const { version } = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8'));
+        let compat = {};
+        try {
+            compat = JSON.parse(fs.readFileSync(path.join(pkgDir, 'dist', 'compat.json'), 'utf8'));
+        } catch {
+            // older packages have no manifest
+        }
+        return typeof version === 'string' ? { version, compat } : null;
+    } catch {
+        return null;
+    }
+}
+
+/** The server's version, or null when it cannot be read. */
+async function serverVersion() {
+    try {
+        const res = await api.get('/v1/server/version', { timeout: TIMEOUT_MS });
+        return typeof res.data?.version === 'string' ? res.data.version : null;
+    } catch {
+        return null;
+    }
+}
+
+/** The latest SDK on npm, or null (not published, offline…). */
+async function latestSdk() {
+    try {
+        const res = await fetch(`${REGISTRY}/${SDK_PACKAGE}/latest`, {
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        if (!res.ok) return null;
+        const { version } = await res.json();
+        return typeof version === 'string' ? version : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Notes for an installed SDK against a server version and the latest
+ * release.
+ *
+ * @param {{ version: string, compat: { baseServer?: string, functions?: Record<string, string> } }} sdk
+ * @param {string | null} server  The server's version.
+ * @param {string | null} latest  The latest SDK on npm.
+ * @returns {string[]}
+ */
+export function sdkNotes(sdk, server, latest) {
+    const notes = [];
+    if (compareVersions(sdk.version, CONSOLE_MIN_SDK) < 0) {
+        notes.push(
+            `The app uses ${SDK_PACKAGE} ${sdk.version}: inside the console it gets no token (the console needs SDK ${CONSOLE_MIN_SDK} or later). Update it: npm install ${SDK_PACKAGE}@^${CONSOLE_MIN_SDK}.`,
+        );
+    }
+    const { baseServer, functions = {} } = sdk.compat || {};
+    if (server && baseServer && compareVersions(server, baseServer) < 0) {
+        notes.push(
+            `The app's dashboard SDK ${sdk.version} needs Thinger ${baseServer} or later; this server runs ${numeric(server)}: the app will not work on it.`,
+        );
+    } else if (server) {
+        const missing = Object.entries(functions)
+            .filter(([, min]) => compareVersions(server, min) < 0)
+            .map(([name, min]) => `${name} (${min})`);
+        if (missing.length) {
+            notes.push(
+                `On this server (Thinger ${numeric(server)}) these SDK calls fail because they need a newer one: ${missing.join(', ')}.`,
+            );
+        }
+    }
+    if (latest && compareVersions(sdk.version, latest) < 0) {
+        notes.push(
+            `The app uses ${SDK_PACKAGE} ${sdk.version}; the latest is ${latest}. Its CHANGELOG.md says what changes and how to migrate: npm install ${SDK_PACKAGE}@^${latest}.`,
+        );
+    }
+    return notes;
+}
+
+/**
+ * Notes on the SDK of an app: the package found from `dir` (its project or
+ * build folder) against the profile's server and npm, and pages loading
+ * the deprecated script build instead.
+ *
+ * @param {{ dir?: string, files?: Record<string, Buffer | string> }} app
+ * @returns {Promise<string[]>}
+ */
+export async function checkSdk({ dir, files = {} }) {
+    const notes = [];
+    const scripts = Object.entries(files).filter(
+        ([name, content]) => /\.html?$/i.test(name) && SCRIPT_BUILD.test(String(content)),
+    );
+    if (scripts.length) {
+        notes.push(
+            `${scripts.map(([name]) => name).join(', ')} ${scripts.length === 1 ? 'loads' : 'load'} the SDK's script build (thinger-dashboard.js), which is deprecated: install ${SDK_PACKAGE} and import { Thinger } from it, so the SDK goes in the build.`,
+        );
+    }
+    const sdk = dir ? installedSdk(dir) : null;
+    if (sdk) {
+        const [server, latest] = await Promise.all([serverVersion(), latestSdk()]);
+        notes.push(...sdkNotes(sdk, server, latest));
+    }
+    return notes;
+}

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