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

package/dist/commands/docs.js

@@ -0,0 +1,183 @@
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveConfig, isJsonOutput } from "../lib/config.js";
+import { printTable, printJson, printKeyValue } from "../lib/output.js";
+import { handleError, CLIError, EXIT } from "../lib/errors.js";
+const HTTP_METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Resolve the OpenAPI spec to use. Bundled by default; --live re-fetches
+ * from the active context's base URL.
+ */
+async function loadSpec(command, live) {
+    if (!live) {
+        const bundled = join(__dirname, "..", "..", "openapi", "openapi.json");
+        return JSON.parse(readFileSync(bundled, "utf-8"));
+    }
+    const config = resolveConfig(command);
+    const url = `${config.baseUrl.replace(/\/+$/, "")}/v3/api-docs`;
+    const res = await fetch(url, {
+        headers: { Authorization: `Bearer ${config.apiKey}` },
+    });
+    if (!res.ok) {
+        throw new CLIError(`Failed to fetch live spec from ${url}: HTTP ${res.status}. ` +
+            `Is the backend running with SPRING_PROFILES_ACTIVE=spec?`, EXIT.GENERIC);
+    }
+    return (await res.json());
+}
+export function makeDocsCommand() {
+    const cmd = new Command("docs").description("Browse API documentation from the OpenAPI spec");
+    cmd
+        .command("list")
+        .description("List command groups (OpenAPI tags)")
+        .option("--live", "Fetch the spec from the server instead of the bundled copy")
+        .action(async (opts, command) => {
+        try {
+            const spec = await loadSpec(command, opts.live === true);
+            const groups = collectGroups(spec);
+            if (isJsonOutput(command)) {
+                printJson({ groups });
+                return;
+            }
+            printTable(groups, [
+                { key: "name", header: "GROUP" },
+                { key: "operations", header: "OPS" },
+                { key: "description", header: "DESCRIPTION" },
+            ]);
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd
+        .command("sections")
+        .description("List all operationIds across the spec")
+        .option("--live", "Fetch the spec from the server")
+        .action(async (opts, command) => {
+        try {
+            const spec = await loadSpec(command, opts.live === true);
+            const ops = collectOperations(spec);
+            if (isJsonOutput(command)) {
+                printJson({ operations: ops });
+                return;
+            }
+            printTable(ops, [
+                { key: "operationId", header: "OPERATION" },
+                { key: "method", header: "METHOD" },
+                { key: "path", header: "PATH" },
+                { key: "tag", header: "GROUP" },
+            ]);
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd
+        .command("show <operationId>")
+        .description("Show details for a single operation")
+        .option("--live", "Fetch the spec from the server")
+        .action(async (operationId, opts, command) => {
+        try {
+            const spec = await loadSpec(command, opts.live === true);
+            const ops = collectOperations(spec);
+            const op = ops.find((o) => o.operationId === operationId);
+            if (!op) {
+                throw new CLIError(`Operation "${operationId}" not found.`, EXIT.NOT_FOUND);
+            }
+            if (isJsonOutput(command)) {
+                printJson(op);
+                return;
+            }
+            printKeyValue({
+                Operation: op.operationId,
+                Method: op.method.toUpperCase(),
+                Path: op.path,
+                Group: op.tag ?? "(none)",
+                Summary: op.summary ?? "",
+                Description: op.description ?? "",
+                "Response codes": Object.keys(op.responses ?? {}).join(", ") || "(none)",
+            });
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    cmd
+        .command("search <query>")
+        .description("Search summaries, paths, and operationIds (case-insensitive)")
+        .option("--live", "Fetch the spec from the server")
+        .action(async (query, opts, command) => {
+        try {
+            const spec = await loadSpec(command, opts.live === true);
+            const q = query.toLowerCase();
+            const matches = collectOperations(spec).filter((op) => {
+                return (op.path.toLowerCase().includes(q) ||
+                    (op.operationId?.toLowerCase().includes(q) ?? false) ||
+                    (op.summary?.toLowerCase().includes(q) ?? false));
+            });
+            if (isJsonOutput(command)) {
+                printJson({ query, matches });
+                return;
+            }
+            if (matches.length === 0) {
+                process.stderr.write(`No matches for "${query}".\n`);
+                return;
+            }
+            printTable(matches, [
+                { key: "operationId", header: "OPERATION" },
+                { key: "method", header: "METHOD" },
+                { key: "path", header: "PATH" },
+                { key: "summary", header: "SUMMARY" },
+            ]);
+        }
+        catch (err) {
+            handleError(err, { json: isJsonOutput(command) });
+        }
+    });
+    return cmd;
+}
+function collectGroups(spec) {
+    const counts = new Map();
+    for (const [, item] of Object.entries(spec.paths ?? {})) {
+        for (const method of HTTP_METHODS) {
+            const op = item[method];
+            if (!op)
+                continue;
+            const tags = op.tags ?? ["(untagged)"];
+            for (const tag of tags) {
+                counts.set(tag, (counts.get(tag) ?? 0) + 1);
+            }
+        }
+    }
+    const descriptions = new Map((spec.tags ?? []).map((t) => [t.name, t.description ?? ""]));
+    return [...counts.entries()]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([name, operations]) => ({
+        name,
+        operations,
+        description: descriptions.get(name) ?? "",
+    }));
+}
+function collectOperations(spec) {
+    const out = [];
+    for (const [path, item] of Object.entries(spec.paths ?? {})) {
+        for (const method of HTTP_METHODS) {
+            const op = item[method];
+            if (!op)
+                continue;
+            out.push({
+                operationId: op.operationId ?? `${method.toUpperCase()} ${path}`,
+                method,
+                path,
+                tag: op.tags?.[0],
+                summary: op.summary,
+                description: op.description,
+                responses: op.responses,
+            });
+        }
+    }
+    return out.sort((a, b) => a.operationId.localeCompare(b.operationId));
+}
+//# sourceMappingURL=docs.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { Command } from "commander";
+import { makeAuthCommand } from "./commands/auth.js";
+import { makeContextCommand } from "./commands/context.js";
+import { makeConfigCommand } from "./commands/config.js";
+import { makeDocsCommand } from "./commands/docs.js";
+import { checkForUpdates } from "./lib/update-notifier.js";
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+const program = new Command();
+program
+    .name("iot")
+    .description("CLI for the iot platform by Manfred Kunze Development " +
+    "(also installed as `mkd-iot` and `mki`)")
+    .version(pkg.version)
+    .option("--api-key <key>", "API key (overrides config)")
+    .option("--base-url <url>", "Base URL (overrides config)")
+    .option("--context <name>", "Use a named context for this invocation only")
+    .option("--json", "Output raw JSON instead of formatted tables")
+    .option("--no-color", "Disable colored output")
+    .option("--verbose", "Print resolved base URL, masked key, and request info on stderr");
+program.addCommand(makeAuthCommand());
+program.addCommand(makeContextCommand());
+program.addCommand(makeConfigCommand());
+program.addCommand(makeDocsCommand());
+const json = process.argv.includes("--json");
+const updater = checkForUpdates(pkg.version, { json });
+program
+    .parseAsync()
+    .then(async () => {
+    await updater.notify();
+})
+    .catch((err) => {
+    process.stderr.write(`Fatal: ${err.message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/lib/client.d.ts

@@ -0,0 +1,15 @@
+import { type Client } from "openapi-fetch";
+import type { Command } from "commander";
+import type { paths } from "../generated/openapi.js";
+import { type IotConfig } from "./config.js";
+export type IotClient = Client<paths>;
+/**
+ * Build an openapi-fetch client bound to the resolved config. The middleware
+ * stack converts non-2xx responses into typed `ApiError`s so callers get a
+ * uniform error surface.
+ */
+export declare function getClient(command: Command): {
+    client: IotClient;
+    config: IotConfig;
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/lib/client.js

@@ -0,0 +1,55 @@
+import createClient from "openapi-fetch";
+import { resolveConfig, isVerbose } from "./config.js";
+import { ApiError } from "./errors.js";
+import { maskKey } from "./output.js";
+const errorMiddleware = {
+    async onResponse({ request, response }) {
+        if (response.ok)
+            return undefined;
+        let body = {};
+        try {
+            body = (await response.clone().json());
+        }
+        catch {
+            // Empty or non-JSON body — leave defaults.
+        }
+        const url = new URL(request.url);
+        throw new ApiError({
+            status: body.status ?? response.status,
+            message: body.detail ??
+                body.message ??
+                body.error ??
+                `HTTP ${response.status}: ${response.statusText}`,
+            code: body.code,
+            errors: body.errors,
+            method: request.method,
+            path: url.pathname,
+        });
+    },
+};
+/**
+ * Build an openapi-fetch client bound to the resolved config. The middleware
+ * stack converts non-2xx responses into typed `ApiError`s so callers get a
+ * uniform error surface.
+ */
+export function getClient(command) {
+    const config = resolveConfig(command);
+    const client = createClient({
+        baseUrl: config.baseUrl.replace(/\/+$/, ""),
+        headers: { Authorization: `Bearer ${config.apiKey}` },
+    });
+    if (isVerbose(command)) {
+        const verboseMiddleware = {
+            onRequest({ request }) {
+                const url = new URL(request.url);
+                process.stderr.write(`[verbose] ${request.method} ${url.pathname}${url.search} ` +
+                    `(base=${config.baseUrl}, key=${maskKey(config.apiKey)})\n`);
+                return undefined;
+            },
+        };
+        client.use(verboseMiddleware);
+    }
+    client.use(errorMiddleware);
+    return { client, config };
+}
+//# sourceMappingURL=client.js.map

package/dist/lib/config.d.ts

@@ -0,0 +1,63 @@
+import Conf from "conf";
+import type { Command } from "commander";
+export interface ContextEntry {
+    baseUrl: string;
+    apiKey: string;
+}
+export interface IotConfigStore {
+    currentContext: string;
+    contexts: Record<string, ContextEntry>;
+}
+export interface IotConfig {
+    apiKey: string;
+    baseUrl: string;
+}
+/**
+ * Fallback base URL when the user has no context, env var, or local config.
+ * Override at build time by setting IOT_DEFAULT_BASE_URL — e.g. for distributions
+ * targeting a different deployment.
+ */
+export declare const DEFAULT_BASE_URL: string;
+/**
+ * Conf store. The cwd override allows tests (and users who want strict env
+ * isolation) to redirect the store via IOT_CLI_CONFIG_DIR.
+ */
+declare const store: Conf<IotConfigStore>;
+export { store };
+export declare function validateContextName(name: string): void;
+export declare function getActiveContextName(): string;
+export declare function getActiveContext(): ContextEntry | undefined;
+export declare function getAllContexts(): Record<string, ContextEntry>;
+export declare function getContext(name: string): ContextEntry | undefined;
+export declare function getContextCount(): number;
+export declare function setContext(name: string, entry: ContextEntry): void;
+export declare function deleteContext(name: string): void;
+export declare function renameContext(oldName: string, newName: string): void;
+export declare function setActiveContext(name: string): void;
+/**
+ * Resolve configuration with priority:
+ *   1. CLI flag (--api-key, --base-url)
+ *   2. Per-invocation context override (--context <name>)
+ *   3. Environment variables (IOT_API_KEY, IOT_BASE_URL)
+ *   4. Local .iot file (cwd or any ancestor)
+ *   5. Active context from config store
+ */
+export declare function resolveConfig(command: Command): IotConfig;
+/** Walk up Commander's parent chain to find root program */
+export declare function getRootCommand(cmd: Command): Command;
+/** Check if --json flag is set on root command */
+export declare function isJsonOutput(command: Command): boolean;
+/** Check if --verbose flag is set on root command */
+export declare function isVerbose(command: Command): boolean;
+/**
+ * Read user preference (config get/set). Distinct from contexts —
+ * preferences are global, not per-environment.
+ */
+export type PreferenceKey = "defaultOutput" | "colorMode" | "pageSize";
+export declare function isPreferenceKey(s: string): s is PreferenceKey;
+export declare function getPreference<T = string>(key: PreferenceKey): T | undefined;
+export declare function setPreference(key: PreferenceKey, value: string): void;
+export declare function unsetPreference(key: PreferenceKey): void;
+export declare function listPreferences(): Record<string, string>;
+export declare function listPreferenceKeys(): readonly PreferenceKey[];
+//# sourceMappingURL=config.d.ts.map

package/dist/lib/config.js

@@ -0,0 +1,188 @@
+import Conf from "conf";
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+/**
+ * Fallback base URL when the user has no context, env var, or local config.
+ * Override at build time by setting IOT_DEFAULT_BASE_URL — e.g. for distributions
+ * targeting a different deployment.
+ */
+export const DEFAULT_BASE_URL = process.env.IOT_DEFAULT_BASE_URL ?? "https://iot.manfred-kunze.dev/api";
+const CONFIG_DEFAULTS = {
+    currentContext: "default",
+    contexts: {},
+};
+/**
+ * Conf store. The cwd override allows tests (and users who want strict env
+ * isolation) to redirect the store via IOT_CLI_CONFIG_DIR.
+ */
+const store = new Conf({
+    projectName: "iot-cli",
+    projectSuffix: "",
+    cwd: process.env.IOT_CLI_CONFIG_DIR,
+    defaults: CONFIG_DEFAULTS,
+});
+export { store };
+const CONTEXT_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+export function validateContextName(name) {
+    if (!CONTEXT_NAME_RE.test(name)) {
+        throw new Error("Context name must contain only letters, numbers, hyphens, and underscores.");
+    }
+}
+export function getActiveContextName() {
+    return store.get("currentContext") ?? "default";
+}
+export function getActiveContext() {
+    const name = getActiveContextName();
+    const contexts = store.get("contexts") ?? {};
+    return contexts[name];
+}
+export function getAllContexts() {
+    return store.get("contexts") ?? {};
+}
+export function getContext(name) {
+    return getAllContexts()[name];
+}
+export function getContextCount() {
+    return Object.keys(getAllContexts()).length;
+}
+export function setContext(name, entry) {
+    validateContextName(name);
+    const contexts = getAllContexts();
+    contexts[name] = entry;
+    store.set("contexts", contexts);
+}
+export function deleteContext(name) {
+    const contexts = getAllContexts();
+    if (!contexts[name]) {
+        throw new Error(`Context "${name}" does not exist.`);
+    }
+    if (Object.keys(contexts).length === 1) {
+        throw new Error("Cannot delete the last remaining context.");
+    }
+    delete contexts[name];
+    store.set("contexts", contexts);
+    if (getActiveContextName() === name) {
+        const remaining = Object.keys(contexts)[0];
+        store.set("currentContext", remaining);
+    }
+}
+export function renameContext(oldName, newName) {
+    validateContextName(newName);
+    const contexts = getAllContexts();
+    if (!contexts[oldName]) {
+        throw new Error(`Context "${oldName}" does not exist.`);
+    }
+    if (contexts[newName]) {
+        throw new Error(`Context "${newName}" already exists.`);
+    }
+    contexts[newName] = contexts[oldName];
+    delete contexts[oldName];
+    store.set("contexts", contexts);
+    if (getActiveContextName() === oldName) {
+        store.set("currentContext", newName);
+    }
+}
+export function setActiveContext(name) {
+    const contexts = getAllContexts();
+    if (!contexts[name]) {
+        const available = Object.keys(contexts).join(", ") || "(none)";
+        throw new Error(`Context "${name}" does not exist. Available contexts: ${available}`);
+    }
+    store.set("currentContext", name);
+}
+/**
+ * Walk up from cwd to filesystem root looking for a .iot JSON file.
+ */
+function readLocalFile() {
+    let dir = process.cwd();
+    while (true) {
+        const candidate = resolve(dir, ".iot");
+        if (existsSync(candidate)) {
+            try {
+                const parsed = JSON.parse(readFileSync(candidate, "utf-8"));
+                return { apiKey: parsed.apiKey, baseUrl: parsed.baseUrl };
+            }
+            catch {
+                // Malformed file — fall through, don't keep searching ancestors.
+                return {};
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return {};
+        dir = parent;
+    }
+}
+/**
+ * Resolve configuration with priority:
+ *   1. CLI flag (--api-key, --base-url)
+ *   2. Per-invocation context override (--context <name>)
+ *   3. Environment variables (IOT_API_KEY, IOT_BASE_URL)
+ *   4. Local .iot file (cwd or any ancestor)
+ *   5. Active context from config store
+ */
+export function resolveConfig(command) {
+    const root = getRootCommand(command);
+    const opts = root.opts();
+    const local = readLocalFile();
+    // --context <name> picks a specific stored context for this call without
+    // changing the persistent active context.
+    const overrideCtx = typeof opts.context === "string" ? getContext(opts.context) : undefined;
+    if (typeof opts.context === "string" && !overrideCtx) {
+        throw new Error(`Context "${opts.context}" does not exist. Run "iot context list" to see available contexts.`);
+    }
+    const fallbackCtx = overrideCtx ?? getActiveContext();
+    const apiKey = opts.apiKey ?? process.env.IOT_API_KEY ?? local.apiKey ?? fallbackCtx?.apiKey;
+    const baseUrl = opts.baseUrl ??
+        process.env.IOT_BASE_URL ??
+        local.baseUrl ??
+        fallbackCtx?.baseUrl ??
+        DEFAULT_BASE_URL;
+    if (!apiKey) {
+        throw new Error('No API key configured. Run "iot auth login".');
+    }
+    return { apiKey, baseUrl };
+}
+/** Walk up Commander's parent chain to find root program */
+export function getRootCommand(cmd) {
+    let root = cmd;
+    while (root.parent)
+        root = root.parent;
+    return root;
+}
+/** Check if --json flag is set on root command */
+export function isJsonOutput(command) {
+    return getRootCommand(command).opts().json === true;
+}
+/** Check if --verbose flag is set on root command */
+export function isVerbose(command) {
+    return getRootCommand(command).opts().verbose === true;
+}
+const PREFERENCE_KEYS = ["defaultOutput", "colorMode", "pageSize"];
+export function isPreferenceKey(s) {
+    return PREFERENCE_KEYS.includes(s);
+}
+export function getPreference(key) {
+    // conf stores preferences under a `preferences` map to keep them separate
+    // from contexts. We don't pre-declare them in the schema so the user can
+    // add their own arbitrary keys later (still validated through isPreferenceKey).
+    const prefs = (store.get("preferences") ?? {});
+    return prefs[key];
+}
+export function setPreference(key, value) {
+    const prefs = (store.get("preferences") ?? {});
+    prefs[key] = value;
+    store.set("preferences", prefs);
+}
+export function unsetPreference(key) {
+    const prefs = (store.get("preferences") ?? {});
+    delete prefs[key];
+    store.set("preferences", prefs);
+}
+export function listPreferences() {
+    return (store.get("preferences") ?? {});
+}
+export function listPreferenceKeys() {
+    return PREFERENCE_KEYS;
+}
+//# sourceMappingURL=config.js.map

package/dist/lib/errors.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Process exit codes. Stable contract for scripts piping into the CLI.
+ * Update README.md when these change.
+ */
+export declare const EXIT: {
+    readonly OK: 0;
+    readonly GENERIC: 1;
+    readonly UNAUTHORIZED: 2;
+    readonly FORBIDDEN: 3;
+    readonly NOT_FOUND: 4;
+    readonly CONFLICT: 5;
+    readonly VALIDATION: 6;
+    readonly SERVER: 7;
+    readonly NETWORK: 8;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/**
+ * 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 declare class CLIError extends Error {
+    readonly exitCode: ExitCode;
+    readonly suggestion?: string;
+    constructor(message: string, exitCode?: ExitCode, suggestion?: string);
+}
+export interface ApiErrorPayload {
+    status: number;
+    code?: string;
+    message: string;
+    errors?: unknown;
+    /** Original request (method + path) — useful in 404 messages. */
+    method?: string;
+    path?: string;
+}
+/**
+ * Thrown by the openapi-fetch error middleware when the server returns a
+ * non-2xx response. Carries the parsed response body and request info.
+ */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly errors?: unknown;
+    readonly method?: string;
+    readonly path?: string;
+    constructor(payload: ApiErrorPayload);
+}
+/**
+ * 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 declare function apiErrorToCliError(err: ApiError): CLIError;
+/**
+ * Detect a generic node-fetch network failure (DNS, refused, timeout).
+ * openapi-fetch surfaces these as raw `TypeError` / `Error` instances.
+ */
+export declare function isNetworkError(err: unknown): boolean;
+/**
+ * Convert any thrown value into a CLIError. Pure function for testability.
+ */
+export declare function toCliError(err: unknown, baseUrl?: string): CLIError;
+/**
+ * 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 declare function handleError(err: unknown, opts: {
+    json: boolean;
+    baseUrl?: string;
+}): never;
+//# sourceMappingURL=errors.d.ts.map