@manfred-kunze-dev/iot-cli 3.0.0-dev.1

package/dist/lib/errors.js

@@ -0,0 +1,160 @@
+import chalk from "chalk";
+/**
+ * Process exit codes. Stable contract for scripts piping into the CLI.
+ * Update README.md when these change.
+ */
+export const EXIT = {
+    OK: 0,
+    GENERIC: 1,
+    UNAUTHORIZED: 2,
+    FORBIDDEN: 3,
+    NOT_FOUND: 4,
+    CONFLICT: 5,
+    VALIDATION: 6,
+    SERVER: 7,
+    NETWORK: 8,
+};
+/**
+ * Anything the CLI throws on purpose. Carries the exit code we want the
+ * process to terminate with and an optional one-line suggestion the user
+ * can act on ("Run iot auth login").
+ */
+export class CLIError extends Error {
+    exitCode;
+    suggestion;
+    constructor(message, exitCode = EXIT.GENERIC, suggestion) {
+        super(message);
+        this.name = "CLIError";
+        this.exitCode = exitCode;
+        this.suggestion = suggestion;
+    }
+}
+/**
+ * Thrown by the openapi-fetch error middleware when the server returns a
+ * non-2xx response. Carries the parsed response body and request info.
+ */
+export class ApiError extends Error {
+    status;
+    code;
+    errors;
+    method;
+    path;
+    constructor(payload) {
+        super(payload.message);
+        this.name = "ApiError";
+        this.status = payload.status;
+        this.code = payload.code;
+        this.errors = payload.errors;
+        this.method = payload.method;
+        this.path = payload.path;
+    }
+}
+/**
+ * Map an HTTP status to a CLIError with the spec-mandated exit code.
+ * Pulled out so test fixtures can assert the mapping without spinning a server.
+ */
+export function apiErrorToCliError(err) {
+    switch (err.status) {
+        case 401:
+            return new CLIError(err.message || "Not authenticated.", EXIT.UNAUTHORIZED, 'Run "iot auth login".');
+        case 403:
+            return new CLIError(err.message || "Forbidden.", EXIT.FORBIDDEN, "Your API key lacks permission for this resource.");
+        case 404: {
+            const path = err.method && err.path ? `${err.method} ${err.path}` : err.path ?? "resource";
+            return new CLIError(`Not found: ${path}.`, EXIT.NOT_FOUND);
+        }
+        case 409:
+            return new CLIError(err.message, EXIT.CONFLICT);
+        case 422: {
+            const details = formatValidationErrors(err.errors);
+            return new CLIError(details ? `${err.message}\n${details}` : err.message, EXIT.VALIDATION);
+        }
+        default:
+            if (err.status >= 500 && err.status < 600) {
+                return new CLIError(`Server error (${err.status}): ${err.message}`, EXIT.SERVER, "Try again or report at https://gitlab.com/manfred-kunze-dev/iot/-/issues.");
+            }
+            return new CLIError(err.message || `HTTP ${err.status}`, EXIT.GENERIC);
+    }
+}
+function formatValidationErrors(errors) {
+    if (!errors)
+        return undefined;
+    if (Array.isArray(errors)) {
+        return errors
+            .map((e) => (typeof e === "string" ? `  - ${e}` : `  - ${JSON.stringify(e)}`))
+            .join("\n");
+    }
+    if (typeof errors === "object") {
+        return Object.entries(errors)
+            .map(([field, msg]) => `  - ${field}: ${typeof msg === "string" ? msg : JSON.stringify(msg)}`)
+            .join("\n");
+    }
+    return String(errors);
+}
+/**
+ * Detect a generic node-fetch network failure (DNS, refused, timeout).
+ * openapi-fetch surfaces these as raw `TypeError` / `Error` instances.
+ */
+export function isNetworkError(err) {
+    if (!(err instanceof Error))
+        return false;
+    if (err.name === "AbortError")
+        return true;
+    const msg = err.message.toLowerCase();
+    return (msg.includes("fetch failed") ||
+        msg.includes("econnrefused") ||
+        msg.includes("enotfound") ||
+        msg.includes("eai_again") ||
+        msg.includes("etimedout") ||
+        msg.includes("network"));
+}
+/**
+ * Convert any thrown value into a CLIError. Pure function for testability.
+ */
+export function toCliError(err, baseUrl) {
+    if (err instanceof CLIError)
+        return err;
+    if (err instanceof ApiError)
+        return apiErrorToCliError(err);
+    if (isNetworkError(err)) {
+        return new CLIError(`Cannot reach ${baseUrl ?? "the server"}. Check the URL and your connection.`, EXIT.NETWORK);
+    }
+    if (err instanceof Error) {
+        return new CLIError(err.message, EXIT.GENERIC);
+    }
+    return new CLIError(String(err), EXIT.GENERIC);
+}
+/**
+ * Single top-level error handler. Writes to stderr (never stdout) so
+ * pipelines like `iot foo --json | jq` keep working even on failure.
+ *
+ * In JSON mode the error is serialised as
+ *   { "error": { "code": "...", "message": "...", "status": 401 } }
+ */
+export function handleError(err, opts) {
+    const cli = toCliError(err, opts.baseUrl);
+    if (opts.json) {
+        const apiInfo = {};
+        if (err instanceof ApiError) {
+            apiInfo.status = err.status;
+            if (err.code !== undefined)
+                apiInfo.code = err.code;
+        }
+        const payload = {
+            error: {
+                message: cli.message,
+                ...apiInfo,
+                ...(cli.suggestion ? { suggestion: cli.suggestion } : {}),
+            },
+        };
+        process.stderr.write(JSON.stringify(payload) + "\n");
+    }
+    else {
+        process.stderr.write(chalk.red(cli.message) + "\n");
+        if (cli.suggestion) {
+            process.stderr.write(chalk.dim(cli.suggestion) + "\n");
+        }
+    }
+    process.exit(cli.exitCode);
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/output.d.ts

@@ -0,0 +1,45 @@
+export interface Row {
+    [key: string]: unknown;
+}
+export interface Column {
+    /** Key into the row to read the value from. */
+    key: string;
+    /** Display header. Defaults to `key`. */
+    header?: string;
+    /** Optional formatter for the cell. */
+    format?: (value: unknown, row: Row) => string;
+}
+/**
+ * Whether interactive output (spinners, colors, prompts) should be active.
+ * False under --json, when stdout isn't a TTY, or in CI.
+ */
+export declare function isInteractive(opts?: {
+    json?: boolean;
+}): boolean;
+export declare function printTable(rows: Row[], columns: Column[]): void;
+/**
+ * Render a single record as a two-column key/value table — for "status"
+ * style detail screens.
+ */
+export declare function printKeyValue(record: Record<string, unknown>): void;
+export declare function printJson(value: unknown): void;
+/**
+ * Write a success/info line. Always to stdout when it carries useful info,
+ * stderr when it's purely a UX banner. Callers pick.
+ */
+export declare function printSuccess(message: string, target?: "stdout" | "stderr"): void;
+export declare function printWarning(message: string): void;
+export declare function printInfo(message: string, target?: "stdout" | "stderr"): void;
+/**
+ * Run an async action with an `ora` spinner. The spinner is suppressed
+ * automatically when the output isn't interactive (--json, non-TTY, CI) —
+ * the action still runs and its result is still returned, just without UI.
+ */
+export declare function withSpinner<T>(text: string, action: () => Promise<T>, opts?: {
+    json?: boolean;
+}): Promise<T>;
+/** Render a value sensibly: null/undefined → em dash, objects → JSON, rest → string. */
+export declare function formatValue(value: unknown): string;
+/** Last 4 + first 5 chars of an API key, with ellipsis between. */
+export declare function maskKey(key: string): string;
+//# sourceMappingURL=output.d.ts.map

package/dist/lib/output.js

@@ -0,0 +1,104 @@
+import chalk from "chalk";
+import Table from "cli-table3";
+import ora from "ora";
+/**
+ * Whether interactive output (spinners, colors, prompts) should be active.
+ * False under --json, when stdout isn't a TTY, or in CI.
+ */
+export function isInteractive(opts = {}) {
+    if (opts.json)
+        return false;
+    if (process.env.CI)
+        return false;
+    return process.stdout.isTTY === true;
+}
+/** Standard cli-table3 instance with consistent border style. */
+function newTable(head) {
+    return new Table({
+        head: head.map((h) => chalk.cyan(h)),
+        wordWrap: true,
+        style: { head: [], border: ["grey"] },
+    });
+}
+export function printTable(rows, columns) {
+    if (rows.length === 0) {
+        process.stdout.write(chalk.dim("(no rows)\n"));
+        return;
+    }
+    const table = newTable(columns.map((c) => c.header ?? c.key));
+    for (const row of rows) {
+        table.push(columns.map((c) => {
+            const v = row[c.key];
+            return c.format ? c.format(v, row) : formatValue(v);
+        }));
+    }
+    process.stdout.write(table.toString() + "\n");
+}
+/**
+ * Render a single record as a two-column key/value table — for "status"
+ * style detail screens.
+ */
+export function printKeyValue(record) {
+    const table = new Table({
+        style: { head: [], border: ["grey"] },
+    });
+    for (const [key, value] of Object.entries(record)) {
+        table.push({ [chalk.cyan(key)]: formatValue(value) });
+    }
+    process.stdout.write(table.toString() + "\n");
+}
+export function printJson(value) {
+    process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}
+/**
+ * Write a success/info line. Always to stdout when it carries useful info,
+ * stderr when it's purely a UX banner. Callers pick.
+ */
+export function printSuccess(message, target = "stdout") {
+    const stream = target === "stdout" ? process.stdout : process.stderr;
+    stream.write(chalk.green(message) + "\n");
+}
+export function printWarning(message) {
+    process.stderr.write(chalk.yellow(message) + "\n");
+}
+export function printInfo(message, target = "stderr") {
+    const stream = target === "stdout" ? process.stdout : process.stderr;
+    stream.write(message + "\n");
+}
+/**
+ * Run an async action with an `ora` spinner. The spinner is suppressed
+ * automatically when the output isn't interactive (--json, non-TTY, CI) —
+ * the action still runs and its result is still returned, just without UI.
+ */
+export async function withSpinner(text, action, opts = {}) {
+    if (!isInteractive(opts)) {
+        return action();
+    }
+    const spinner = ora({ text, stream: process.stderr }).start();
+    try {
+        const result = await action();
+        spinner.succeed();
+        return result;
+    }
+    catch (err) {
+        spinner.fail();
+        throw err;
+    }
+}
+/** Render a value sensibly: null/undefined → em dash, objects → JSON, rest → string. */
+export function formatValue(value) {
+    if (value === null || value === undefined)
+        return chalk.dim("—");
+    if (value === "")
+        return chalk.dim("(empty)");
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
+/** Last 4 + first 5 chars of an API key, with ellipsis between. */
+export function maskKey(key) {
+    if (key.length <= 12)
+        return key.replace(/./g, "*");
+    return `${key.slice(0, 5)}...${key.slice(-4)}`;
+}
+//# sourceMappingURL=output.js.map

package/dist/lib/update-notifier.d.ts

@@ -0,0 +1,18 @@
+export interface Updater {
+    notify: () => Promise<void> | void;
+}
+/**
+ * Check for updates in the background. Fire early so the fetch overlaps
+ * with the command itself, then call `notify()` once the command is done
+ * to print the (optional) banner.
+ *
+ * Always silent when:
+ *   - the version string is a stub/placeholder (no dots)
+ *   - `--json` mode is set (handled at call site via `opts.json`)
+ *   - `CI` env is set
+ *   - `IOT_DISABLE_UPDATE_NOTIFIER` env is set
+ */
+export declare function checkForUpdates(currentVersion: string, opts?: {
+    json?: boolean;
+}): Updater;
+//# sourceMappingURL=update-notifier.d.ts.map

package/dist/lib/update-notifier.js

@@ -0,0 +1,118 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import chalk from "chalk";
+const PKG_NAME = "@manfred-kunze-dev/iot-cli";
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const CACHE_DIR = process.env.IOT_CLI_CONFIG_DIR ?? join(homedir(), ".config", "iot-cli");
+const CACHE_FILE = join(CACHE_DIR, "update-check.json");
+function readCache() {
+    try {
+        return JSON.parse(readFileSync(CACHE_FILE, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(data) {
+    try {
+        mkdirSync(CACHE_DIR, { recursive: true });
+        writeFileSync(CACHE_FILE, JSON.stringify(data));
+    }
+    catch {
+        // Cache write failures are non-fatal; we'll just re-check on next run.
+    }
+}
+async function fetchLatestVersion(distTag) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 3000);
+        const res = await fetch(`https://registry.npmjs.org/${PKG_NAME}/${distTag}`, {
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return data.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function compareVersions(current, latest) {
+    const parse = (v) => v.replace(/^v/, "").split(/[.-]/).map((x) => Number(x) || 0);
+    const [cMaj = 0, cMin = 0, cPat = 0] = parse(current);
+    const [lMaj = 0, lMin = 0, lPat = 0] = parse(latest);
+    if (lMaj !== cMaj)
+        return lMaj > cMaj;
+    if (lMin !== cMin)
+        return lMin > cMin;
+    return lPat > cPat;
+}
+/**
+ * Pick which npm dist-tag to compare against. Pre-release installs
+ * (`1.2.3-dev.4`) follow the dev channel; stable installs follow latest.
+ */
+function distTagFor(current) {
+    return current.includes("-") ? "dev" : "latest";
+}
+/**
+ * Check for updates in the background. Fire early so the fetch overlaps
+ * with the command itself, then call `notify()` once the command is done
+ * to print the (optional) banner.
+ *
+ * Always silent when:
+ *   - the version string is a stub/placeholder (no dots)
+ *   - `--json` mode is set (handled at call site via `opts.json`)
+ *   - `CI` env is set
+ *   - `IOT_DISABLE_UPDATE_NOTIFIER` env is set
+ */
+export function checkForUpdates(currentVersion, opts = {}) {
+    if (opts.json || process.env.CI || process.env.IOT_DISABLE_UPDATE_NOTIFIER) {
+        return { notify: () => undefined };
+    }
+    if (!currentVersion.includes(".")) {
+        return { notify: () => undefined };
+    }
+    const tag = distTagFor(currentVersion);
+    let message = null;
+    const cache = readCache();
+    const now = Date.now();
+    if (cache && cache.distTag === tag && now - cache.lastCheck < CHECK_INTERVAL_MS) {
+        if (compareVersions(currentVersion, cache.latestVersion)) {
+            message = formatMessage(currentVersion, cache.latestVersion, tag);
+        }
+        return {
+            notify: () => {
+                if (message)
+                    process.stderr.write(message + "\n");
+            },
+        };
+    }
+    const pending = fetchLatestVersion(tag).then((latest) => {
+        if (latest) {
+            writeCache({ lastCheck: now, latestVersion: latest, distTag: tag });
+            if (compareVersions(currentVersion, latest)) {
+                message = formatMessage(currentVersion, latest, tag);
+            }
+        }
+    });
+    return {
+        notify: async () => {
+            await pending;
+            if (message)
+                process.stderr.write(message + "\n");
+        },
+    };
+}
+function formatMessage(current, latest, tag) {
+    const installCmd = tag === "latest" ? `npm i -g ${PKG_NAME}` : `npm i -g ${PKG_NAME}@${tag}`;
+    return [
+        "",
+        chalk.yellow(`Update available: ${chalk.dim(current)} → ${chalk.green(latest)}`),
+        chalk.yellow(`Run ${chalk.cyan(installCmd)} to update`),
+        "",
+    ].join("\n");
+}
+//# sourceMappingURL=update-notifier.js.map

package/openapi/openapi.json

@@ -0,0 +1,65 @@
+{
+  "openapi": "3.0.1",
+  "info": {
+    "title": "iot platform API (placeholder)",
+    "description": "Placeholder OpenAPI spec for the iot CLI. Replace by running `npm run generate` against a backend started with SPRING_PROFILES_ACTIVE=spec.",
+    "version": "0.0.0-placeholder"
+  },
+  "servers": [
+    {
+      "url": "/",
+      "description": "Same-origin"
+    }
+  ],
+  "tags": [
+    {
+      "name": "devices",
+      "description": "Device fleet"
+    }
+  ],
+  "paths": {
+    "/v1/devices/summary": {
+      "get": {
+        "tags": ["devices"],
+        "operationId": "getDevicesSummary",
+        "summary": "Aggregate counts of devices in the caller's organization. Used by the CLI as a lightweight auth probe.",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeviceSummary"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "DeviceSummary": {
+        "type": "object",
+        "properties": {
+          "total": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "online": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "offline": {
+            "type": "integer",
+            "format": "int64"
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@manfred-kunze-dev/iot-cli",
+  "version": "3.0.0-dev.1",
+  "description": "Command-line interface for the iot platform by Manfred Kunze Development",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "iot": "dist/index.js",
+    "mkd-iot": "dist/index.js",
+    "mki": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "generate:spec": "tsx --env-file-if-exists=.env openapi/scripts/fetch-spec.ts",
+    "generate:types": "openapi-typescript openapi/openapi.json -o src/generated/openapi.d.ts",
+    "generate": "npm run generate:spec && npm run generate:types",
+    "check:spec": "tsx --env-file-if-exists=.env openapi/scripts/check-drift.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^13.1.0",
+    "conf": "^13.1.0",
+    "openapi-fetch": "^0.13.5",
+    "ora": "^8.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.17",
+    "msw": "^2.7.0",
+    "openapi-typescript": "^7.13.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "homepage": "https://iot.manfred-kunze.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/manfred-kunze-dev/iot.git",
+    "directory": "cli"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "openapi/openapi.json",
+    "README.md"
+  ]
+}