@thinger-io/cli-core 0.2.1 → 0.4.0

package/lib/commands/dashboard.js

@@ -0,0 +1,262 @@
+// @ts-check
+import path from 'node:path';
+import open from 'open';
+import {
+    collectFiles,
+    destinationContext,
+    manifestName,
+    parseDestination,
+    publishApp,
+    publishSummary,
+    readManifest,
+} from '../dashboard.js';
+import { DEV_HOURS, devLink } from '../dashboard-dev.js';
+import { DEFAULT_TEMPLATE, initApp } from '../dashboard-init.js';
+import { inputError } from '../errors.js';
+import { accent, hint, warning } from '../format.js';
+import { identity } from '../identity.js';
+import { isJsonMode, printOk } from '../output.js';
+import { applyJsonFlag, ensureConfigured, getGlobalUser, runCommand } from './_shared.js';
+
+const collect = (value, previous = []) => [...previous, value];
+
+/** Destinations of the command line, each with the shared --entry / --route / --name. */
+function flagDestinations(opts) {
+    return (opts.to || []).map((value) => ({
+        ...parseDestination(value),
+        ...(opts.entry ? { entry: opts.entry } : {}),
+        ...(opts.route ? { route: opts.route } : {}),
+        ...(opts.name ? { name: opts.name } : {}),
+    }));
+}
+
+/** `<cli> dashboard dev|publish` — url-source dashboard apps. */
+export function registerDashboardCommands(program) {
+    const cli = identity().name;
+    const dashboard = program
+        .command('dashboard')
+        .helpGroup('Operations:')
+        .description(
+            'Dashboard apps (HTML + the dashboard SDK): develop them on their dev server and publish them',
+        )
+        .addHelpText(
+            'after',
+            `
+Both commands read defaults from ${manifestName()} in the working folder (or --config):
+  { "dashboard": { "dir": "dist/greenhouse/browser", "storage": "app_greenhouse", "prune": true,
+                   "to": [{ "type": "device", "id": "gh_01" }],
+                   "dev": { "url": "http://localhost:4200/", "context": { "device": "gh_01" } } } }
+
+In CI, ${identity().envPrefix}_TOKEN and ${identity().envPrefix}_SERVER replace the saved profile (unless --profile or ${identity().envPrefix}_PROFILE names one).`,
+        );
+
+    dashboard
+        .command('init <dir>')
+        .description(
+            'Create a dashboard app (TypeScript, on @thinger-io/dashboard-sdk) from a template of the SDK',
+        )
+        .option(
+            '-t, --template <name>',
+            `Template of the SDK package: react, angular… (default ${DEFAULT_TEMPLATE})`,
+        )
+        .option(
+            '--to <destination>',
+            'Where it publishes: device:<id>, product:<id>, dashboard:<id>…',
+        )
+        .option('-s, --storage <id>', 'Storage it publishes to (default app_<folder>_<random>)')
+        .option(
+            '--from <package>',
+            'SDK package to take the template from: a version or tag on npm, or a folder or .tgz',
+        )
+        .option('--ci', 'Add a GitHub workflow that publishes it on every push to main')
+        .option('--install', 'Run npm install')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (dir, opts) => {
+            applyJsonFlag(opts);
+            await runCommand({
+                start: 'Creating the app...',
+                fn: () =>
+                    initApp({
+                        dir,
+                        template: opts.template,
+                        to: opts.to ? parseDestination(opts.to) : undefined,
+                        storage: opts.storage,
+                        from: opts.from,
+                        ci: !!opts.ci,
+                        install: !!opts.install,
+                    }),
+                success: (r) =>
+                    `Created ${r.name} (${r.template}, ${r.sdk ? `SDK ${r.sdk}` : 'SDK'})`,
+                failure: 'Failed to create the app',
+                onSuccess: (r) => {
+                    if (isJsonMode()) {
+                        printOk(r);
+                        return;
+                    }
+                    console.log(
+                        hint(
+                            `  ${r.dir}: ${r.template} app on ${r.dependency.startsWith('file:') ? r.dependency : `@thinger-io/dashboard-sdk ${r.dependency}`}, ${manifestName()} (publishes ${r.build} to ${r.storage}) and AGENTS.md.`,
+                        ),
+                    );
+                    console.log(`\n  cd ${dir}`);
+                    if (!r.installed) console.log('  npm install');
+                    console.log(`  ${r.devCommand}`);
+                    console.log(
+                        `  ${cli} dashboard dev${Object.keys(r.context).length ? '' : ' --device <id>'}   ${hint('# link to the running app against the server')}`,
+                    );
+                    console.log(`  npm run build && ${cli} dashboard publish`);
+                },
+            });
+        });
+
+    dashboard
+        .command('dev [url]')
+        .description(
+            'Link that opens the app on its own dev server (ng serve, Vite…) against the server, with a temporary token',
+        )
+        .option(
+            '--to <destination>',
+            'Context of a destination: device:<id>, product:<id>, dashboard:<id>…',
+        )
+        .option('--device <id>', 'Device in the SDK context')
+        .option('--product <id>', 'Product in the SDK context')
+        .option('--asset-type <id>', 'Asset type in the SDK context')
+        .option('--asset-group <id>', 'Asset group in the SDK context')
+        .option('--project <id>', 'Project the app runs in')
+        .option('--route <route>', 'Initial route, e.g. /devices')
+        .option('--hours <hours>', `Hours the token lasts (default ${DEV_HOURS})`, Number)
+        .option('--open', 'Open the link in the browser')
+        .option(
+            '--allow-remote',
+            'Allow an app url that is not on this machine (the link carries a full-access token)',
+        )
+        .option('--config <file>', `Manifest (default ${manifestName()})`)
+        .option('-j, --json', 'Output as JSON')
+        .addHelpText(
+            'after',
+            `
+Start the app's dev server first (the command warns when nothing answers at the url).
+The app bundles @thinger-io/dashboard-sdk, which takes the server, a temporary token and the
+context from the link: its dev server needs no proxy. Each run replaces the previous link's
+token (one per project).`,
+        )
+        .action(async (url, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+            await runCommand({
+                start: 'Creating the dev link...',
+                fn: async () => {
+                    const manifest = readManifest(opts.config);
+                    const dev = manifest?.dev || {};
+                    const app = url || dev.url;
+                    if (!app) {
+                        throw inputError(
+                            `pass the app's dev server url (e.g. ${cli} dashboard dev http://localhost:4200/ --device gw1), or set dev.url in ${manifestName()}`,
+                        );
+                    }
+                    const explicit = {
+                        device: opts.device,
+                        product: opts.product,
+                        type: opts.assetType,
+                        group: opts.assetGroup,
+                        project: opts.project,
+                    };
+                    const to = opts.to ? parseDestination(opts.to) : manifest?.to?.[0];
+                    const context = Object.values(explicit).some(Boolean)
+                        ? explicit
+                        : !opts.to && dev.context
+                          ? dev.context
+                          : destinationContext(to);
+                    return devLink({
+                        url: app,
+                        context,
+                        route: opts.route ?? dev.route ?? to?.route,
+                        hours: opts.hours ?? dev.hours,
+                        user,
+                        dir: manifest ? path.dirname(manifest.file) : process.cwd(),
+                        allowRemote: !!opts.allowRemote,
+                    });
+                },
+                success: () => 'Dev link ready',
+                failure: 'Failed to create the dev link',
+                onSuccess: async (dev) => {
+                    if (isJsonMode()) printOk(dev);
+                    else {
+                        const ctx = Object.entries(dev.context).map(([k, v]) => `${k} ${v}`);
+                        const until = new Date(dev.expire).toTimeString().slice(0, 5);
+                        console.log(`  ${accent(dev.link)}`);
+                        console.log(
+                            hint(
+                                `  ${dev.app} → ${dev.server} as ${dev.user}${ctx.length ? `, ${ctx.join(', ')}` : ''}. Temporary token ${dev.token} until ${until}: writes are real.`,
+                            ),
+                        );
+                        for (const note of dev.notes) console.log(warning(`  ${note}`));
+                    }
+                    if (opts.open) await open(dev.link).catch(() => {});
+                },
+            });
+        });
+
+    dashboard
+        .command('publish [dir]')
+        .description('Upload an app to a public storage and point dashboards at it')
+        .option('-s, --storage <id>', 'Storage of the app (created public if missing)')
+        .option(
+            '--to <destination>',
+            'Dashboard to point (repeatable): dashboard:<id>, device:<id>, product:<id>, asset_type:<id>, asset_group:<id>, project:<id>',
+            collect,
+        )
+        .option('--entry <page>', 'Page the destinations open (default index.html)')
+        .option('--route <route>', 'Initial route of the destinations')
+        .option('--name <name>', 'Name of a collection dashboard')
+        .option('--prune', 'Delete files of the storage that are not in this upload')
+        .option('--no-prune', "Keep the storage's other files (overrides the manifest)")
+        .option('--bump', 'Make consoles that have the app open reload it at once')
+        .option(
+            '--preview [hours]',
+            'Also print standalone preview links (read-only, 1 h by default)',
+        )
+        .option('--no-point', 'Upload without pointing the destinations (preview links only)')
+        .option('--config <file>', `Manifest (default ${manifestName()})`)
+        .option('-j, --json', 'Output as JSON')
+        .action(async (dir, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+            await runCommand({
+                start: 'Publishing...',
+                fn: async () => {
+                    const manifest = readManifest(opts.config);
+                    const folder = dir || manifest?.dir;
+                    const to = opts.to ? flagDestinations(opts) : manifest?.to || [];
+                    const prune = opts.prune ?? manifest?.prune;
+                    const preview =
+                        opts.preview === undefined
+                            ? false
+                            : opts.preview === true
+                              ? true
+                              : Number(opts.preview);
+                    return publishApp({
+                        storage: opts.storage || manifest?.storage,
+                        files: folder ? collectFiles(folder) : undefined,
+                        prune: !!prune,
+                        to,
+                        preview,
+                        point: opts.point,
+                        bump: !!opts.bump,
+                        user,
+                        dir: folder,
+                    });
+                },
+                success: (r) => `Published ${r.storage}`,
+                failure: 'Failed to publish',
+                onSuccess: (result) => {
+                    if (isJsonMode()) printOk(result);
+                    else console.log(publishSummary(result, { point: opts.point }));
+                },
+            });
+        });
+
+    return dashboard;
+}

package/lib/config.js

@@ -131,6 +131,8 @@ export function getActiveProfile() {
     if (scoped) return scoped;
     if (activeProfileOverride) return activeProfileOverride;
     if (env('PROFILE')) return env('PROFILE');
+    // A profile given by the environment has no name: readConfig reads it.
+    if (envProfile()) return null;
     const store = readStore();
     if (store.default && store.profiles[store.default]) return store.default;
     // Fall back to the only profile if there's exactly one.
@@ -224,16 +226,48 @@ export function deleteProfile(name) {
  * Check if any profile is configured.
  */
 export function configExists() {
+    if (envProfile()) return true;
     const store = readStore();
     if (!Object.keys(store.profiles).length) return false;
     return getActiveProfile() != null;
 }
 
+/**
+ * A profile given by the environment, for CI and other machines without a
+ * login: <PREFIX>_TOKEN (an access token) and <PREFIX>_SERVER (a host or a
+ * url; never the identity's default server, which would receive a token
+ * meant for another one). The user comes from the
+ * token. It applies unless a profile is named (--profile, <PREFIX>_PROFILE,
+ * a tool call's `profile`), which keeps reading the saved ones.
+ *
+ * @returns {{ server: string | undefined, token: string, username: string, env: true } | null}
+ */
+function envProfile() {
+    const token = env('TOKEN');
+    if (!token || scopedProfile.getStore() || activeProfileOverride || env('PROFILE')) return null;
+    // Without a server it is still the profile in use: requireConfig says what is missing.
+    const server = env('SERVER') || undefined;
+    let username = null;
+    try {
+        username = JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString()).usr;
+    } catch {
+        // Not a JWT: requireConfig reports the missing user.
+    }
+    return {
+        server,
+        token,
+        username,
+        env: true,
+    };
+}
+
 /**
  * Read the active profile's data.
  * @returns {Object} Active profile fields (server, username, token, ...) or {}
  */
 export function readConfig() {
+    const fromEnv = envProfile();
+    if (fromEnv) return fromEnv;
     const store = readStore();
     const name = getActiveProfile();
     if (!name) return {};
@@ -258,6 +292,14 @@ export function resolveUser(user) {
 
 export function requireConfig() {
     const config = readConfig();
+    if (config.env && !config.server) {
+        const { envPrefix } = identity();
+        const err = new Error(
+            `${envPrefix}_TOKEN is set without ${envPrefix}_SERVER: set both, or unset ${envPrefix}_TOKEN to use the saved profiles.`,
+        );
+        err.code = 'not_configured';
+        throw err;
+    }
     if (!config.token || !config.server || !config.username) {
         const err = new Error(`Not configured. ${loginHint()}`);
         err.code = 'not_configured';

package/lib/dashboard-dev.js

@@ -0,0 +1,180 @@
+// @ts-check
+import { createHash } from 'node:crypto';
+import { readConfig, serverURL } from './config.js';
+import { previewUrl, replaceToken } from './dashboard.js';
+import { checkSdk } from './dashboard-sdk.js';
+import { inputError } from './errors.js';
+
+/**
+ * Local development of url-source dashboards: the app runs on its own dev
+ * server (ng serve, Vite…) and is opened directly, as a standalone page,
+ * with a link whose fragment carries the server (`thinger_api`), a
+ * temporary access token and the SDK context. The SDK calls the server
+ * itself (it answers CORS from any origin), so the app gets real data with
+ * its dev server's reload and the browser's own tools. The app bundles the
+ * SDK (an npm dependency), so its dev server needs no proxy.
+ *
+ * Unlike in the console, the page is not in a sandboxed iframe: what only
+ * fails there (localStorage, cookies, a <base> tag) does not fail here.
+ */
+
+const CONTEXT_FIELDS = ['device', 'product', 'type', 'group', 'project'];
+const ID_RE = /^[a-zA-Z0-9_-]{1,32}$/;
+export const DEV_HOURS = 8;
+const CHECK_TIMEOUT_MS = 3000;
+
+/**
+ * The SDK context of a dev link, checked.
+ *
+ * @param {Record<string, string | undefined>} [context]
+ * @returns {Record<string, string>}
+ */
+export function checkContext(context = {}) {
+    /** @type {Record<string, string>} */
+    const out = {};
+    for (const [key, id] of Object.entries(context)) {
+        if (id === undefined || id === null || id === '') continue;
+        if (!CONTEXT_FIELDS.includes(key)) {
+            throw inputError(`context keys are ${CONTEXT_FIELDS.join(', ')}; got "${key}"`);
+        }
+        if (typeof id !== 'string' || !ID_RE.test(id)) {
+            throw inputError(`invalid ${key} id: "${id}"`);
+        }
+        out[key] = id;
+    }
+    return out;
+}
+
+/**
+ * Token id of dev links: one per project, so a new link replaces the
+ * previous one instead of piling up tokens.
+ *
+ * @param {string} [project]
+ */
+export function devTokenId(project) {
+    if (!project) return 'dashboard_dev';
+    const readable = `dashboard_dev_${project}`;
+    if (readable.length <= 32) return readable;
+    return `dashboard_dev_${createHash('sha1').update(project).digest('hex').slice(0, 18)}`;
+}
+
+/** A host of this machine: localhost, *.localhost, 127.0.0.0/8, [::1]. */
+export function isLoopback(hostname) {
+    const host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    return (
+        host === 'localhost' ||
+        host.endsWith('.localhost') ||
+        host === '::1' ||
+        /^127(\.\d{1,3}){3}$/.test(host)
+    );
+}
+
+/**
+ * The app's url, checked: http(s), no credentials in it, and on this
+ * machine unless `allowRemote`: the link carries a full-access token, and
+ * the url may come from a manifest of someone else's repository.
+ *
+ * @param {string} url
+ * @param {{ allowRemote?: boolean }} [opts]
+ */
+export function checkAppUrl(url, { allowRemote = false } = {}) {
+    let parsed;
+    try {
+        parsed = new URL(String(url));
+    } catch {
+        throw inputError(`pass the url of the app's dev server, e.g. http://localhost:4200/`);
+    }
+    if (!/^https?:$/.test(parsed.protocol) || parsed.username || parsed.password) {
+        throw inputError(`the app's url must be http(s) without credentials: ${url}`);
+    }
+    if (!allowRemote && !isLoopback(parsed.hostname)) {
+        throw inputError(
+            `${parsed.host} is not this machine: the link would give it a full-access token. Pass allow remote (--allow-remote) only for a dev server you trust`,
+        );
+    }
+    return parsed;
+}
+
+/** GET with a short timeout: status and text, or the reason it failed. */
+async function probe(url) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(CHECK_TIMEOUT_MS) });
+        return { status: res.status, text: await res.text() };
+    } catch (e) {
+        return { error: e?.cause?.code || e?.name || String(e) };
+    }
+}
+
+/**
+ * Notes on the app as its dev server serves it: whether it answers, and its
+ * page for the SDK check. Never an error: the link works once the dev
+ * server runs.
+ *
+ * @param {URL} app
+ * @returns {Promise<{ notes: string[], html?: string }>}
+ */
+export async function checkApp(app) {
+    const page = await probe(`${app.origin}${app.pathname}${app.search}`);
+    if (page.error || page.status >= 400) {
+        return {
+            notes: [
+                `Nothing serves the app at ${app.origin}${app.pathname} (${page.error || `HTTP ${page.status}`}): start its dev server, then open the link.`,
+            ],
+        };
+    }
+    return { notes: [], html: page.text };
+}
+
+/**
+ * A link that opens the app on its dev server against the profile's server,
+ * with a temporary token (full access to the account, or to the project
+ * with a project context) valid for `hours`. A new link replaces the
+ * previous one's token.
+ *
+ * @param {{ url: string, context?: Record<string, string | undefined>, route?: string,
+ *   hours?: number, user?: string | null, check?: boolean, dir?: string, allowRemote?: boolean }} opts
+ *   `dir`: the app's project folder, to check the SDK it is built with.
+ */
+export async function devLink({
+    url,
+    context: raw,
+    route,
+    hours = DEV_HOURS,
+    user,
+    check = true,
+    dir,
+    allowRemote = false,
+}) {
+    const app = checkAppUrl(url, { allowRemote });
+    const context = checkContext(raw);
+    if (!(hours > 0 && hours <= 24 * 7)) throw inputError('hours is between 0 and 168');
+    const config = readConfig();
+    const server = serverURL(config.server);
+    if (!server || !config.token) throw inputError('no server configured: sign in first');
+
+    let notes = [];
+    if (check) {
+        const { notes: served, html } = await checkApp(app);
+        const files = html === undefined ? {} : { 'index.html': html };
+        notes = [...served, ...(await checkSdk({ dir, files }))];
+    }
+    const { token, accessToken, expire } = await replaceToken(devTokenId(context.project), {
+        name: 'Dashboard dev (temporary)',
+        allow: { '*': { '*': '*' } },
+        hours,
+        project: context.project,
+        user,
+    });
+    const hash = route ?? app.hash.replace(/^#/, '');
+    const base = `${app.origin}${app.pathname}${app.search}${hash ? `#${hash}` : ''}`;
+    return {
+        link: previewUrl(base, accessToken, { api: server, ...context }),
+        app: `${app.origin}${app.pathname}`,
+        server,
+        user: user || config.username,
+        context,
+        token,
+        expire,
+        notes,
+    };
+}