@thinger-io/cli-core 0.2.1 → 0.4.0

package/lib/dashboard-init.js

@@ -0,0 +1,417 @@
+// @ts-check
+import { exec } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { checkDestination, destinationContext, manifestName } from './dashboard.js';
+import { SDK_PACKAGE } from './dashboard-sdk.js';
+import { inputError } from './errors.js';
+import { identity } from './identity.js';
+import { toolName } from './mcp/naming.js';
+import { extractTgz } from './tgz.js';
+
+const run = promisify(exec);
+const REGISTRY = 'https://registry.npmjs.org';
+const FETCH_TIMEOUT_MS = 30000;
+
+/**
+ * `dashboard init`: a new dashboard app from one of the templates the SDK
+ * package ships (`templates/<name>` in @thinger-io/dashboard-sdk), ready to
+ * develop with `dashboard dev` and publish with `dashboard publish`: the
+ * project, its manifest (`<cli>.json`) and an AGENTS.md with the rules an
+ * app in the console's frame follows.
+ */
+
+/** Template the init uses unless told otherwise. */
+export const DEFAULT_TEMPLATE = 'react';
+
+/** Folders of a template never copied (left there by trying it in place). */
+const NOT_COPIED = new Set(['node_modules', 'dist', '.angular']);
+
+/** The SDK package the CLI installs (its own dependency), or null. */
+function ownSdk() {
+    try {
+        return path.dirname(createRequire(import.meta.url).resolve(`${SDK_PACKAGE}/package.json`));
+    } catch {
+        return null;
+    }
+}
+
+/** A version or dist-tag of the SDK on npm, as `--from` names it ("0.3.0", "next", "<pkg>@0.3.0"). */
+export function sdkSpec(from) {
+    const tag = from.startsWith(`${SDK_PACKAGE}@`) ? from.slice(SDK_PACKAGE.length + 1) : from;
+    return /^[0-9A-Za-z][0-9A-Za-z.+-]{0,63}$/.test(tag) ? tag : null;
+}
+
+/**
+ * Download a version (or dist-tag) of the SDK package from npm, checking
+ * its integrity.
+ *
+ * @param {string} tag
+ * @returns {Promise<Buffer>}
+ */
+async function downloadSdk(tag) {
+    const signal = () => AbortSignal.timeout(FETCH_TIMEOUT_MS);
+    const meta = await fetch(`${REGISTRY}/${SDK_PACKAGE}/${encodeURIComponent(tag)}`, {
+        signal: signal(),
+    });
+    if (meta.status === 404) throw inputError(`${SDK_PACKAGE} has no version or tag "${tag}"`);
+    if (!meta.ok) throw new Error(`npm answered ${meta.status}`);
+    const { dist } = await meta.json();
+    if (typeof dist?.tarball !== 'string' || !dist.tarball.startsWith(`${REGISTRY}/`)) {
+        throw new Error('npm gave no tarball');
+    }
+    const res = await fetch(dist.tarball, { signal: signal() });
+    if (!res.ok) throw new Error(`npm answered ${res.status} for the tarball`);
+    const tgz = Buffer.from(await res.arrayBuffer());
+    const sri = /^sha512-(.+)$/.exec(dist.integrity || '');
+    if (sri && createHash('sha512').update(tgz).digest('base64') !== sri[1]) {
+        throw new Error('the tarball does not match its integrity');
+    }
+    return tgz;
+}
+
+/**
+ * The SDK package to take the templates from: by default its latest
+ * release on npm (or the CLI's own copy when npm cannot be reached);
+ * `from` names a local package folder, a .tgz, or a version or tag on npm.
+ *
+ * @param {string} [from]
+ * @returns {Promise<{ root: string, version: string, dependency: string, notes: string[],
+ *   cleanup: () => void }>}
+ */
+async function sdkPackage(from) {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dashboard-init-'));
+    const cleanup = () => fs.rmSync(tmp, { recursive: true, force: true });
+    const notes = [];
+    try {
+        const local = from && fs.existsSync(from) ? path.resolve(from) : null;
+        let root = local && fs.statSync(local).isDirectory() ? local : null;
+        /** @type {Buffer | null} */
+        let tgz = root || !local ? null : fs.readFileSync(local);
+        if (!root && !tgz) {
+            const tag = from ? sdkSpec(from) : 'latest';
+            if (!tag) {
+                throw inputError(
+                    `--from is a folder or .tgz of ${SDK_PACKAGE}, or one of its versions or tags; got "${from}"`,
+                );
+            }
+            try {
+                tgz = await downloadSdk(tag);
+            } catch (e) {
+                // Offline: the copy the CLI installs, unless another one was asked for.
+                root = from || e.code === 'input_error' ? null : ownSdk();
+                if (!root) {
+                    if (e.code === 'input_error') throw e;
+                    throw inputError(
+                        `could not get ${SDK_PACKAGE}@${tag} from npm (${e.message}); pass --from with a local copy of the package`,
+                    );
+                }
+                notes.push(
+                    `npm could not be reached (${e.message}): the template comes from the SDK the CLI installs.`,
+                );
+            }
+        }
+        if (tgz) {
+            try {
+                extractTgz(tgz, tmp, { strip: 1 });
+            } catch (e) {
+                throw inputError(`${from || SDK_PACKAGE}: ${e.message}`);
+            }
+            root = tmp;
+        }
+        const pkgFile = path.join(/** @type {string} */ (root), 'package.json');
+        const pkg = fs.existsSync(pkgFile) ? JSON.parse(fs.readFileSync(pkgFile, 'utf8')) : {};
+        if (pkg.name !== SDK_PACKAGE) {
+            throw inputError(`${from || root} is not the ${SDK_PACKAGE} package`);
+        }
+        // A local copy is installed from where it is; one from npm by version.
+        const dependency = local ? `file:${local}` : `^${pkg.version}`;
+        return {
+            root: /** @type {string} */ (root),
+            version: pkg.version,
+            dependency,
+            notes,
+            cleanup,
+        };
+    } catch (e) {
+        cleanup();
+        throw e;
+    }
+}
+
+/** An npm package name from a folder name. */
+export function packageName(dir) {
+    const name = path
+        .basename(path.resolve(dir))
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/^[._-]+|[-]+$/g, '');
+    return name || 'dashboard-app';
+}
+
+/**
+ * The storage an app publishes to by default: app_<name>_<random>, within 32
+ * characters, so two apps in folders of the same name never share (and
+ * prune) one storage.
+ */
+export function appStorage(name, suffix = randomBytes(2).toString('hex')) {
+    return `${`app_${name.replace(/[^a-zA-Z0-9_-]/g, '_')}`.slice(0, 27)}_${suffix}`;
+}
+
+function copyDir(from, to) {
+    fs.mkdirSync(to, { recursive: true });
+    for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+        const src = path.join(from, entry.name);
+        const dest = path.join(to, entry.name === '_gitignore' ? '.gitignore' : entry.name);
+        if (entry.isDirectory()) {
+            if (!NOT_COPIED.has(entry.name)) copyDir(src, dest);
+        } else if (entry.isFile()) fs.copyFileSync(src, dest);
+    }
+}
+
+function editJson(file, edit) {
+    const json = JSON.parse(fs.readFileSync(file, 'utf8'));
+    edit(json);
+    fs.writeFileSync(file, JSON.stringify(json, null, 4) + '\n');
+}
+
+/** Guide for the agents that work on the app. */
+function agentsGuide({ name, template, buildDir, devCommand }) {
+    const cli = identity().name;
+    return `# ${name}
+
+A Thinger dashboard app (${template} template) built on \`${SDK_PACKAGE}\`. The Thinger
+console shows it in a sandboxed iframe, loading the build from a file storage; it also runs on
+its own as a standalone page.
+
+## Develop
+
+1. \`npm install\`, then \`${devCommand}\` (the app's dev server).
+2. \`${cli} dashboard dev\` gives a link that opens the local app against the Thinger server, with
+   a temporary token and the context in ${manifestName()} (\`dev\`). Open it in a browser: the
+   app gets real data, reloads on every change, and its errors are in the browser console.
+   Agents: the MCP tool \`${toolName('dashboard_dev')}\` gives the same link; open it with browser
+   tools.
+3. \`npm run build\`, then \`${cli} dashboard publish\`: it uploads \`${buildDir}\` and points the
+   destinations in ${manifestName()} at it.
+
+## Reviewing the layout
+
+Dashboards show at website sizes (around 1150 × 758 and 950 × 678) and on phones (around
+380 × 600). Open the dev link and resize the window; below about 500 px, where a desktop window
+does not shrink, use Playwright with a fixed viewport, or load the dev link in an iframe of that
+size from a page of the app's own dev server (same origin, so you can look inside it). Give the
+iframe the whole dev link, with its \`#…&thinger_token=…\` part, never \`location.href\`: the SDK
+removes the token from the address bar when it starts, and a frame does not take the session
+from the tab, so it would have none. The frame posts \`thinger:dashboard-ready\` to the page once
+its data is in. The package README has more under "Reviewing the layout".
+
+## Rules (they only fail once published, inside the console)
+
+- Hash routing only: the storage serves real files, not app routes.
+- Relative asset URLs and no \`<base>\` tag.
+- Render after \`Thinger.ready()\`: it brings the user, the token and the context
+  (\`Thinger.context.device\`…).
+- No localStorage or cookies (the frame has an opaque origin): keep settings in properties
+  through the SDK.
+- Reach the server only through the SDK (\`Thinger.*\`), never with a token of your own.
+- Reload the app with \`Thinger.reload()\`, never \`location.reload()\`: inside the console a
+  plain reload loses the frame's key and the app gets no token.
+
+## Reference
+
+\`node_modules/${SDK_PACKAGE}/README.md\` documents every call of the installed version, and its
+types come with the package; \`CHANGELOG.md\` there says what changes between versions.
+`;
+}
+
+/** npm package of the running CLI, to run it with npx in CI. */
+function cliPackage() {
+    if (identity().npmPackage) return identity().npmPackage;
+    try {
+        let dir = path.dirname(fs.realpathSync(process.argv[1]));
+        for (;;) {
+            const file = path.join(dir, 'package.json');
+            if (fs.existsSync(file)) {
+                const { name } = JSON.parse(fs.readFileSync(file, 'utf8'));
+                if (name) return name;
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir) break;
+            dir = parent;
+        }
+    } catch {
+        // fall back to the binary name
+    }
+    return identity().name;
+}
+
+/** Workflow that publishes the app on every push to main. */
+function ciWorkflow() {
+    const { envPrefix } = identity();
+    return `name: Publish dashboard
+on:
+    push:
+        branches: [main]
+jobs:
+    publish:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: 22
+            - run: npm ci && npm run build
+            - run: npx -y ${cliPackage()} dashboard publish
+              env:
+                  ${envPrefix}_SERVER: \${{ vars.${envPrefix}_SERVER }}
+                  ${envPrefix}_TOKEN: \${{ secrets.${envPrefix}_TOKEN }}
+`;
+}
+
+/**
+ * Create a dashboard app in `dir` (new or empty).
+ *
+ * @param {{ dir: string, template?: string, to?: import('./dashboard.js').Destination,
+ *   storage?: string, from?: string, ci?: boolean, install?: boolean }} opts
+ */
+export async function initApp({
+    dir,
+    template = DEFAULT_TEMPLATE,
+    to,
+    storage,
+    from,
+    ci = false,
+    install = false,
+}) {
+    if (!dir) throw inputError('pass the folder of the new app');
+    const target = path.resolve(dir);
+    const existed = fs.existsSync(target);
+    if (existed && !fs.statSync(target).isDirectory()) throw inputError(`${dir} is a file`);
+    if (existed && fs.readdirSync(target).some((f) => f !== '.git')) {
+        throw inputError(`${dir} is not empty: pass a new folder`);
+    }
+    if (to) checkDestination(to);
+
+    const pkg = await sdkPackage(from);
+    try {
+        return await createApp({ target, dir, template, to, storage, ci, install, pkg });
+    } catch (e) {
+        // Leave no half-made app behind (a .git that was there stays).
+        if (existed) {
+            for (const f of fs.readdirSync(target)) {
+                if (f !== '.git') fs.rmSync(path.join(target, f), { recursive: true, force: true });
+            }
+        } else fs.rmSync(target, { recursive: true, force: true });
+        throw e;
+    } finally {
+        pkg.cleanup();
+    }
+}
+
+/** The steps of initApp once the package is at hand. */
+async function createApp({ target, dir, template, to, storage, ci, install, pkg }) {
+    const notes = [...pkg.notes];
+    {
+        const templates = path.join(pkg.root, 'templates');
+        const available = fs.existsSync(templates)
+            ? fs
+                  .readdirSync(templates, { withFileTypes: true })
+                  .filter((e) => e.isDirectory())
+                  .map((e) => e.name)
+            : [];
+        if (!available.includes(template)) {
+            throw inputError(
+                `${SDK_PACKAGE} ${pkg.version} has no template "${template}"; it has ${available.join(', ') || 'none'}`,
+            );
+        }
+        copyDir(path.join(templates, template), target);
+    }
+    if (!fs.existsSync(path.join(target, 'package.json'))) {
+        throw inputError(`template "${template}" has no package.json`);
+    }
+
+    const name = packageName(target);
+    let original;
+    editJson(path.join(target, 'package.json'), (json) => {
+        original = json.name;
+        json.name = name;
+        for (const deps of [json.dependencies, json.devDependencies]) {
+            if (deps?.[SDK_PACKAGE]) deps[SDK_PACKAGE] = pkg.dependency;
+        }
+    });
+    const scripts = JSON.parse(fs.readFileSync(path.join(target, 'package.json'), 'utf8')).scripts;
+
+    // Angular names its build folder after the project: dist/<project>/browser.
+    const angular = fs.existsSync(path.join(target, 'angular.json'));
+    if (angular && original) {
+        for (const file of ['angular.json', 'README.md']) {
+            const full = path.join(target, file);
+            if (fs.existsSync(full)) {
+                fs.writeFileSync(full, fs.readFileSync(full, 'utf8').split(original).join(name));
+            }
+        }
+    }
+    const buildDir = angular ? `dist/${name}/browser` : 'dist';
+    const devCommand = scripts?.dev ? 'npm run dev' : 'npm start';
+    const devUrl = angular ? 'http://localhost:4200/' : 'http://localhost:5173/';
+
+    const manifest = {
+        dashboard: {
+            dir: buildDir,
+            storage: storage || appStorage(name),
+            prune: true,
+            ...(to ? { to: [to] } : {}),
+            dev: { url: devUrl },
+        },
+    };
+    fs.writeFileSync(path.join(target, manifestName()), JSON.stringify(manifest, null, 4) + '\n');
+    fs.writeFileSync(
+        path.join(target, 'AGENTS.md'),
+        agentsGuide({ name, template, buildDir, devCommand }),
+    );
+    fs.writeFileSync(path.join(target, 'CLAUDE.md'), '@AGENTS.md\n');
+    if (ci && pkg.dependency.startsWith('file:')) {
+        notes.push(
+            `The SDK dependency points at a local copy (${pkg.dependency}): the workflow's npm ci fails until it names a published version.`,
+        );
+    }
+    if (ci) {
+        const workflows = path.join(target, '.github', 'workflows');
+        fs.mkdirSync(workflows, { recursive: true });
+        fs.writeFileSync(path.join(workflows, 'dashboard.yml'), ciWorkflow());
+    }
+    if (install) {
+        try {
+            // a fixed command line, run in the app's folder
+            await run('npm install --no-fund --no-audit', { cwd: target });
+        } catch (e) {
+            throw inputError(
+                `created ${dir}, but npm install failed: ${
+                    String(e.stderr || e.message)
+                        .trim()
+                        .split('\n')
+                        .slice(-1)[0]
+                }`,
+            );
+        }
+    }
+    return {
+        dir: target,
+        name,
+        template,
+        sdk: pkg.version,
+        dependency: pkg.dependency,
+        build: buildDir,
+        devCommand,
+        devUrl,
+        storage: manifest.dashboard.storage,
+        context: destinationContext(to),
+        installed: install,
+        notes,
+    };
+}

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