@thinger-io/cli-core 0.4.2 → 0.5.0

package/lib/commands/_shared.js

@@ -34,6 +34,16 @@ export function getGlobalUser(cmd) {
     return root.opts().user || null;
 }
 
+export function parseNonNegativeInt(label) {
+    return (value) => {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n < 0) {
+            throw new InvalidArgumentError(`${label} must be a non-negative integer`);
+        }
+        return n;
+    };
+}
+
 export function parsePositiveInt(label) {
     return (value) => {
         const n = Number(value);
@@ -54,6 +64,37 @@ export function collectKeyValue(value, previous = {}) {
     return { ...previous, [value.slice(0, idx)]: parseJsonValue(value.slice(idx + 1)) };
 }
 
+// Like collectKeyValue, values kept as written: query parameters, where
+// "007" must not become 7.
+export function collectKeyString(value, previous = {}) {
+    const idx = value.indexOf('=');
+    if (idx === -1) throw new InvalidArgumentError('must be key=value');
+    return { ...previous, [value.slice(0, idx)]: value.slice(idx + 1) };
+}
+
+/**
+ * Set `value` at a dot path of `target` (`data.source` → target.data.source),
+ * creating the objects on the way. Keys that would reach the prototype are
+ * refused.
+ *
+ * @param {Record<string, any>} target
+ * @param {string} path
+ * @param {any} value
+ */
+export function setPath(target, path, value) {
+    const keys = path.split('.');
+    if (keys.some((k) => !k || k === '__proto__' || k === 'constructor' || k === 'prototype')) {
+        throw new InvalidArgumentError(`invalid field: ${path}`);
+    }
+    let node = target;
+    for (const k of keys.slice(0, -1)) {
+        if (!node[k] || typeof node[k] !== 'object' || Array.isArray(node[k])) node[k] = {};
+        node = node[k];
+    }
+    node[keys[keys.length - 1]] = value;
+    return target;
+}
+
 // Parse a command-line value as JSON, falling back to the raw string so
 // `property set dev name foo` works without shell-escaping quotes.
 export function parseJsonValue(raw) {
@@ -66,7 +107,9 @@ export function parseJsonValue(raw) {
 }
 
 // Read a JSON document from a file path, or from stdin when the path is `-`.
-export async function readJsonArgument(source) {
+// With `lines`, a file of one JSON document per line (NDJSON) is read as
+// the array of them.
+export async function readJsonArgument(source, { lines = false } = {}) {
     let text;
     if (source === '-') {
         const chunks = [];
@@ -78,10 +121,55 @@ export async function readJsonArgument(source) {
     try {
         return JSON.parse(text);
     } catch (error) {
+        if (lines) {
+            try {
+                return text
+                    .split('\n')
+                    .filter((l) => l.trim())
+                    .map((l) => JSON.parse(l));
+            } catch {
+                // Report the error of the whole document.
+            }
+        }
         throw new InvalidArgumentError(`${source} is not valid JSON: ${error.message}`);
     }
 }
 
+/**
+ * The body a command builds from `--from <file|->` and repeatable
+ * `--set key=value` (dot paths nest) on top of it. Undefined when neither
+ * is given.
+ *
+ * @param {{ from?: string, set?: Record<string, any> }} opts
+ * @param {{ lines?: boolean }} [read]  Passed to readJsonArgument.
+ */
+export async function bodyFromOptions(opts, read) {
+    let body;
+    if (opts.from) body = await readJsonArgument(opts.from, read);
+    if (opts.set) {
+        if (
+            body !== undefined &&
+            (typeof body !== 'object' || body === null || Array.isArray(body))
+        ) {
+            throw new InvalidArgumentError('--set needs the --from body to be a JSON object');
+        }
+        body = body ?? {};
+        for (const [k, v] of Object.entries(opts.set)) setPath(body, k, v);
+    }
+    return body;
+}
+
+/** `--from` and `--set`, the options of bodyFromOptions. */
+export function bodyOptions(cmd, setFlag = '-s, --set <key=value>') {
+    return cmd
+        .option('--from <file>', 'JSON body from a file, or - for stdin')
+        .option(
+            setFlag,
+            'Body field (repeatable; values parsed as JSON when they are; dots nest: data.source=resource)',
+            collectKeyValue,
+        );
+}
+
 /**
  * Ask before an irreversible action unless `--yes` was given. Refuses in a
  * non-interactive shell (or JSON mode) without `--yes` rather than

package/lib/commands/api.js

@@ -0,0 +1,90 @@
+// @ts-check
+import { writeFile } from 'node:fs/promises';
+import { rawApiCall } from '../raw-api.js';
+import { inputError } from '../errors.js';
+import { classifyError, isJsonMode, printErr, printOk } from '../output.js';
+import {
+    applyJsonFlag,
+    collectKeyString,
+    ensureConfigured,
+    getGlobalUser,
+    bodyFromOptions,
+    bodyOptions,
+} from './_shared.js';
+
+/** `<cli> api <path>` — any request to the server, as `gh api` does for GitHub. */
+export function registerApiCommand(program) {
+    bodyOptions(
+        program
+            .command('api <path>')
+            .helpGroup('Integration:')
+            .description('Send a request to the server API (anything the commands do not cover)')
+            .option(
+                '-X, --method <method>',
+                'GET, POST, PUT, PATCH or DELETE (default: GET, or POST with a body)',
+            ),
+    )
+        .option('-q, --query <key=value>', 'Query parameter (repeatable)', collectKeyString)
+        .option('-o, --output <file>', 'Write the answer to a file (downloads, binary answers)')
+        .option('-j, --json', 'Output as JSON ({ ok, data })')
+        .addHelpText(
+            'after',
+            `
+The path is relative to the profile's server; {user} stands for the account
+(the profile's, or --user). The answer is printed as it comes: JSON pretty
+printed, text as is.
+
+Examples:
+  $ <cli> api /v1/users/{user}/endpoints
+  $ <cli> api /v1/users/{user}/buckets -s bucket=temps -s name=Temperatures -s source=write
+  $ <cli> api -X PUT /v1/users/{user}/devices/sensor1 --from device.json
+  $ <cli> api /v1/users/{user}/buckets/temps/data -q items=100 -q sort=desc
+  $ <cli> api /v2/users/{user}/storages/web/files/index.html -o index.html`.replaceAll(
+                '<cli>',
+                program.name(),
+            ),
+        )
+        .action(async (path, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            try {
+                const body = await bodyFromOptions(opts);
+                if (
+                    body !== undefined &&
+                    ['GET', 'DELETE'].includes(String(opts.method).toUpperCase())
+                ) {
+                    throw inputError(
+                        `${opts.method.toUpperCase()} takes no body: pass query parameters with -q`,
+                    );
+                }
+                const res = await rawApiCall({
+                    method: opts.method,
+                    path,
+                    query: opts.query,
+                    body,
+                    user: getGlobalUser(cmd),
+                });
+                if (opts.output) {
+                    await writeFile(opts.output, res.raw);
+                    if (isJsonMode()) printOk({ status: res.status, file: opts.output });
+                    else process.stderr.write(`Saved to ${opts.output}\n`);
+                    return;
+                }
+                if (res.kind === 'binary') {
+                    if (isJsonMode() || process.stdout.isTTY) {
+                        throw inputError(
+                            `the answer is binary (${res.contentType || 'unknown type'}, ${res.body.length} bytes): save it with -o <file>`,
+                        );
+                    }
+                    process.stdout.write(res.body);
+                    return;
+                }
+                if (isJsonMode()) printOk(res.body);
+                else if (res.kind === 'json') console.log(JSON.stringify(res.body, null, 2));
+                else if (res.kind === 'text') process.stdout.write(res.raw);
+            } catch (error) {
+                const { message, code } = classifyError(error);
+                printErr(message, { code });
+            }
+        });
+}

package/lib/commands/arguments.js

@@ -0,0 +1,62 @@
+// @ts-check
+
+/**
+ * Help for the positional arguments of the commands written by hand, kept
+ * in one table instead of spread over every `.command('x <id>')`. A command
+ * path ('dashboard init') wins over the argument name alone; a CLI adds its
+ * own tables (runCli's `argumentHelp`).
+ */
+const BY_COMMAND = {
+    api: { path: 'API path, e.g. /v1/users/{user}/devices ({user}: your account)' },
+    'device set-product': { product: 'Product ID ("" removes the device from its product)' },
+    'device resource call': { resource: 'Resource of the device to call' },
+    'product profile api call': { resource: 'API resource of the product profile' },
+    'doc get': { doc: 'ID of the guide (doc list gives them)' },
+
+    'dashboard init': { dir: 'New or empty folder for the app' },
+    'dashboard dev': {
+        url: 'Address of the app on its dev server (default: dev.url of the manifest)',
+    },
+    'dashboard publish': { dir: 'Folder to upload (default: dir of the manifest)' },
+    'storage file list': { folder: 'Folder of the storage to list (default: all the files)' },
+    'storage file upload': { local: 'Local file or folder' },
+    'storage file download': { path: 'Path of the file in the storage' },
+    'storage file delete': { path: 'Path of the file in the storage' },
+    'plugin call': { path: 'Path in the API of the plugin, e.g. /api/status' },
+    'profile add': { name: 'Profile name (asked when missing)' },
+};
+
+const BY_NAME = {
+    device: 'Device ID',
+    product: 'Product ID',
+    bucket: 'Data Bucket ID',
+    property: 'Property ID',
+    value: 'Value, parsed as JSON (text when it is not JSON)',
+    storage: 'File storage ID',
+    plugin: 'Plugin ID',
+    name: 'Profile name',
+};
+
+/**
+ * Describe the arguments that have no description yet, in the whole tree.
+ *
+ * @param {import('commander').Command} program
+ * @param {{ byCommand?: Record<string, Record<string, string>>, byName?: Record<string, string> }} [extra]
+ *   A CLI's own tables, read before the core's.
+ */
+export function describeArguments(program, { byCommand = {}, byName = {} } = {}) {
+    const walk = (cmd, path) => {
+        for (const arg of cmd.registeredArguments) {
+            if (arg.description) continue;
+            const name = arg.name();
+            arg.description =
+                byCommand[path]?.[name] ??
+                BY_COMMAND[path]?.[name] ??
+                byName[name] ??
+                BY_NAME[name] ??
+                '';
+        }
+        for (const sub of cmd.commands) walk(sub, path ? `${path} ${sub.name()}` : sub.name());
+    };
+    walk(program, '');
+}

package/lib/commands/bucket.js

@@ -2,6 +2,7 @@
 import { getBucketData, getBuckets } from '../bucket.js';
 import { hint, info, label, success } from '../format.js';
 import { isJsonMode, printOk } from '../output.js';
+import { hasListOptions, listOptions, listRecords } from './resources.js';
 import {
     applyJsonFlag,
     ensureConfigured,
@@ -10,71 +11,78 @@ import {
     runCommand,
 } from './_shared.js';
 
-/** `<cli> bucket list|read` — data buckets and their time series. */
+/**
+ * `<cli> bucket list|read` — data buckets as a table and their time
+ * series; the rest of the group (write, export, records, tags…) comes from
+ * the tool and resource commands.
+ */
 export function registerBucketCommands(program) {
     const bucket = program
         .command('bucket')
-        .helpGroup('Operations:')
-        .description('Data buckets: list them and read their time series');
+        .helpGroup('Resources:')
+        .description('Data buckets: records, time series, exports and tags');
 
-    bucket
-        .command('list')
-        .description('List the data buckets of the account')
-        .option('-j, --json', 'Output as JSON')
-        .action(async (opts, cmd) => {
-            applyJsonFlag(opts);
-            ensureConfigured();
-            const user = getGlobalUser(cmd);
-            await runCommand({
-                start: 'Fetching buckets...',
-                fn: () => getBuckets(user),
-                success: (buckets) => `Found ${buckets.length} bucket(s)`,
-                failure: 'Failed to list buckets',
-                onSuccess: (buckets) => {
-                    if (isJsonMode()) {
-                        printOk(buckets);
-                        return;
-                    }
-                    const idWidth = buckets.reduce(
-                        (w, b) => Math.max(w, String(b.bucket ?? '').length),
-                        0,
+    listOptions(
+        bucket
+            .command('list')
+            .helpGroup('Records:')
+            .description('List the data buckets of the account')
+            .option('-j, --json', 'Output as JSON'),
+    ).action(async (opts, cmd) => {
+        applyJsonFlag(opts);
+        ensureConfigured();
+        const user = getGlobalUser(cmd);
+        await runCommand({
+            start: 'Fetching buckets...',
+            fn: () => (hasListOptions(opts) ? listRecords('bucket', opts, user) : getBuckets(user)),
+            success: (buckets) => `Found ${buckets.length} bucket(s)`,
+            failure: 'Failed to list buckets',
+            onSuccess: (buckets) => {
+                if (isJsonMode()) {
+                    printOk(buckets);
+                    return;
+                }
+                const idWidth = buckets.reduce(
+                    (w, b) => Math.max(w, String(b.bucket ?? '').length),
+                    0,
+                );
+                for (const b of buckets) {
+                    const flag = b.enabled === false ? hint('disabled') : success('enabled ');
+                    const extras = [
+                        b.name && b.name !== b.bucket ? hint(`(${b.name})`) : '',
+                        b.product ? info(`[${b.product}]`) : '',
+                        b.config?.source ? hint(`source: ${b.config.source}`) : '',
+                    ].filter(Boolean);
+                    console.log(
+                        `  ${flag}  ${label(String(b.bucket ?? '(no id)').padEnd(idWidth))}${extras.length ? '  ' + extras.join('  ') : ''}`,
                     );
-                    for (const b of buckets) {
-                        const flag = b.enabled === false ? hint('disabled') : success('enabled ');
-                        const extras = [
-                            b.name && b.name !== b.bucket ? hint(`(${b.name})`) : '',
-                            b.product ? info(`[${b.product}]`) : '',
-                            b.config?.source ? hint(`source: ${b.config.source}`) : '',
-                        ].filter(Boolean);
-                        console.log(
-                            `  ${flag}  ${label(String(b.bucket ?? '(no id)').padEnd(idWidth))}${extras.length ? '  ' + extras.join('  ') : ''}`,
-                        );
-                    }
-                },
-            });
+                }
+            },
         });
+    });
 
     bucket
-        .command('read <bucketId>')
+        .command('read <bucket>')
+        .helpGroup('Data:')
         .description('Read samples from a bucket (latest first by default)')
-        .option('-d, --device <deviceId>', 'Series a product bucket keeps for this device')
-        .option('-n, --items <n>', 'Number of samples (default: 10)', parsePositiveInt('items'), 10)
+        .option('-d, --device <device>', 'Series a product bucket keeps for this device')
+        .option('-n, --items <n>', 'Number of samples', parsePositiveInt('items'), 10)
         .option('-m, --minutes <n>', 'Only the last N minutes', parsePositiveInt('minutes'))
-        .option('--sort <order>', 'asc or desc (default: desc)', 'desc')
+        .option('--sort <order>', 'asc or desc', 'desc')
         .option('--agg <window>', 'Aggregation window, e.g. 5m, 1h')
         .option('--agg-type <reducer>', 'Reducer: mean, max, min, sum, count, first, last…')
         .option('--fields <list>', 'Comma-separated fields to return')
         .option('--group-by <key>', 'Group key, e.g. device')
         .option('-j, --json', 'Output as JSON')
-        .action(async (bucketId, opts, cmd) => {
+        .action(async (id, opts, cmd) => {
             applyJsonFlag(opts);
             ensureConfigured();
             const user = getGlobalUser(cmd);
             await runCommand({
-                start: `Reading ${bucketId}...`,
+                start: `Reading ${id}...`,
                 fn: () =>
                     getBucketData({
-                        bucket: bucketId,
+                        bucket: id,
                         device: opts.device,
                         user,
                         items: opts.items,

package/lib/commands/dashboard.js

@@ -35,9 +35,9 @@ export function registerDashboardCommands(program) {
     const cli = identity().name;
     const dashboard = program
         .command('dashboard')
-        .helpGroup('Operations:')
+        .helpGroup('Resources:')
         .description(
-            'Dashboard apps (HTML + the dashboard SDK): develop them on their dev server and publish them',
+            'Dashboards: apps on the dashboard SDK (create, develop and publish them) and their records',
         )
         .addHelpText(
             'after',
@@ -52,6 +52,7 @@ In CI, ${identity().envPrefix}_TOKEN and ${identity().envPrefix}_SERVER replace
 
     dashboard
         .command('init <dir>')
+        .helpGroup('Apps:')
         .description(
             'Create a dashboard app (TypeScript, on @thinger-io/dashboard-sdk) from a template of the SDK',
         )
@@ -111,6 +112,7 @@ In CI, ${identity().envPrefix}_TOKEN and ${identity().envPrefix}_SERVER replace
 
     dashboard
         .command('dev [url]')
+        .helpGroup('Apps:')
         .description(
             'Link that opens the app on its own dev server (ng serve, Vite…) against the server, with a temporary token',
         )
@@ -200,6 +202,7 @@ token (one per project).`,
 
     dashboard
         .command('publish [dir]')
+        .helpGroup('Apps:')
         .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(