@thinger-io/cli-core 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## [0.1.0] - 2026-10-10
+
+First version, extracted from the core of `thinr` 1.3.5 and made
+independent of the product.
+
+### Added
+
+- CLI identity (`defineIdentity`): name, config folder, environment prefix,
+  login token, OAuth client, MCP server name and tool prefix, product
+  template.
+- `runCli` with the generic commands (login, logout, profile, device, product,
+  bucket, mcp) and extension points: `register` with the command groups,
+  `onNoCommand`, `mcpTools`, `mcpInstructions`.
+- MCP tools declared with bare names and `{tool:x}` / `{family:x}`
+  references, expanded and validated when the server starts; CLI tools can
+  replace generic ones explicitly (`replaces: true`).
+- `device create` / `device_create`, `bucket list` / `buckets`.
+
+### Changed (compared with thinr 1.3.5)
+
+- The API base URL and token come from the profile active for each request,
+  and the MCP `profile` argument is scoped per call (AsyncLocalStorage).
+- Servers may carry a scheme (`http://localhost:8080`); profiles are named
+  after the host.
+- `logout` forgets the current profile (or `--all`) and revokes the API token
+  the CLI minted, instead of deleting every profile.
+- Login works without prompts (`--server --username --token`) and fails with
+  a clear message when a prompt has no terminal.
+- The config file is written with mode 600.
+- Server error messages are kept in the errors shown to the user.

package/LICENSE

@@ -0,0 +1,22 @@
+
+MIT License
+
+Copyright (c) 2025 Thinger.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# @thinger-io/cli-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The shared core of the CLIs built on Thinger.io servers — `thinger`
+([@thinger-io/thinger-cli](https://github.com/thinger-io/thinger-cli)) and
+ThinRemote's `thinr` — and of the MCP servers they expose.
+
+It holds everything that is not specific to a product:
+
+- **API client** (`api`) — axios with the active profile's server and token on
+  every request, refresh on 401, self-signed TLS for localhost.
+- **Auth** (`auth`) — username/password (mints a permanent API token),
+  pasted token, OAuth device flow; interactive or fully non-interactive.
+- **Profiles** (`config`) — several servers per CLI, selected by `--profile`,
+  `<PREFIX>_PROFILE` or the saved default, and scoped per call
+  (`withActiveProfile`) so concurrent MCP calls don't mix servers.
+- **REST helpers** — `devices`, `property`, `resource`, `bucket`, `product`,
+  `profile` (product profiles), `tokens`, `alarms`, `storage`, with every
+  account path built in `paths`.
+- **Generic commands** (`cli`, `commands/*`) — login, logout, profile, device,
+  product, bucket, mcp.
+- **MCP** (`mcp/*`) — the stdio server and ~50 generic tools.
+
+## Identity
+
+The core knows nothing about the product it runs for. A CLI defines its
+identity once, before anything else, and runs:
+
+```js
+import { defineIdentity } from '@thinger-io/cli-core/identity';
+import { runCli } from '@thinger-io/cli-core/cli';
+
+defineIdentity({
+    name: 'acme', // binary name, used in hints
+    displayName: 'Acme IoT',
+    description: 'CLI for Acme IoT servers',
+    configDir: 'acme-cli', // ~/.config/acme-cli/config.json
+    envPrefix: 'ACME', // ACME_PROFILE, ACME_INSECURE
+    token: { id: 'acme_cli', name: 'Acme CLI' }, // minted by the password login
+    oauth: { clientId: null }, // OAuth device-flow client, if the platform ships one
+    defaultServer: null, // suggested by the login prompt
+    mcp: { serverName: 'acme', toolPrefix: 'acme' }, // tools become acme_devices, …
+    productTemplate: {}, // optional defaults for new products
+});
+
+await runCli({ version: '1.0.0' });
+```
+
+Each CLI keeps its own profiles, environment variables and MCP tool names,
+so two of them can run side by side without one operating on the other's
+servers.
+
+## Extending
+
+`runCli` takes:
+
+- `register(program, { device, product, bucket })` — add top-level commands,
+  or subcommands inside the generic groups.
+- `onNoCommand(program)` — what to do when called without arguments
+  (default: help).
+- `mcpTools` — the CLI's own MCP tools, declared with bare names
+  (`name: 'exec'`) and referring to others in descriptions as
+  `{tool:devices}` or `{family:token}`. Unknown references fail at startup.
+  A tool flagged `replaces: true` swaps out the generic tool of the same name.
+- `mcpInstructions` — server-level guidance sent to MCP clients.
+
+Modules are imported by path: `@thinger-io/cli-core/api`,
+`@thinger-io/cli-core/mcp/registry`, …
+
+## Development
+
+```bash
+npm install
+npm test           # under a made-up "acme" identity
+npm run lint
+npm run typecheck
+```
+
+## License
+
+MIT

package/lib/alarms.js

@@ -0,0 +1,223 @@
+import api from './api.js';
+import { apiError } from './errors.js';
+import { v1 } from './paths.js';
+
+// Backend enums (see backend/src/thinger/features/alarms/alarm_rule.hpp).
+// Exported so the dashboard can render labels/colors without re-deriving
+// them from string heuristics.
+export const ALARM_STATE = {
+    NONE: 0,
+    ACTIVATED: 1,
+    ACKNOWLEDGED: 2,
+    LATCHED: 3,
+    SHELVED: 4,
+    CLEARED: 5,
+};
+
+export const ALARM_SEVERITY = {
+    NONE: 0,
+    LOW: 1,
+    MEDIUM: 2,
+    HIGH: 3,
+    CRITICAL: 4,
+};
+
+export const ALARM_STATE_LABEL = {
+    0: 'none',
+    1: 'active',
+    2: 'ack',
+    3: 'latched',
+    4: 'shelved',
+    5: 'cleared',
+};
+
+export const ALARM_SEVERITY_LABEL = {
+    0: 'none',
+    1: 'low',
+    2: 'med',
+    3: 'high',
+    4: 'crit',
+};
+
+// Reverse maps so callers can pass human-readable strings ("ack", "shelved",
+// "high", …) instead of remembering the numeric enum values.
+const STATE_FROM_LABEL = {
+    none: ALARM_STATE.NONE,
+    active: ALARM_STATE.ACTIVATED,
+    activated: ALARM_STATE.ACTIVATED,
+    ack: ALARM_STATE.ACKNOWLEDGED,
+    acknowledged: ALARM_STATE.ACKNOWLEDGED,
+    latched: ALARM_STATE.LATCHED,
+    shelved: ALARM_STATE.SHELVED,
+    cleared: ALARM_STATE.CLEARED,
+};
+
+const SEVERITY_FROM_LABEL = {
+    none: ALARM_SEVERITY.NONE,
+    low: ALARM_SEVERITY.LOW,
+    med: ALARM_SEVERITY.MEDIUM,
+    medium: ALARM_SEVERITY.MEDIUM,
+    high: ALARM_SEVERITY.HIGH,
+    crit: ALARM_SEVERITY.CRITICAL,
+    critical: ALARM_SEVERITY.CRITICAL,
+};
+
+export function parseAlarmState(value) {
+    if (value == null) return undefined;
+    if (typeof value === 'number') return value;
+    const key = String(value).trim().toLowerCase();
+    return STATE_FROM_LABEL[key];
+}
+
+export function parseAlarmSeverity(value) {
+    if (value == null) return undefined;
+    if (typeof value === 'number') return value;
+    const key = String(value).trim().toLowerCase();
+    return SEVERITY_FROM_LABEL[key];
+}
+
+// Repeats a query param as the server expects (`?state=1&state=2`).
+function appendMulti(params, key, values) {
+    if (values == null) return;
+    const arr = Array.isArray(values) ? values : [values];
+    for (const v of arr) params.append(key, String(v));
+}
+
+/**
+ * Query alarm instances from /v1/users/{user}/alarms/instances.
+ *
+ * `state` and `severity` are repeated query params — pass numbers or
+ * arrays of numbers (matching the ALARM_STATE / ALARM_SEVERITY enums).
+ *
+ * @param {{
+ *   user?: string | null,
+ *   count?: number,
+ *   index?: number,
+ *   name?: string,
+ *   state?: number | number[],
+ *   severity?: number | number[],
+ *   sort?: string,
+ *   order?: string,
+ * }} [opts]
+ */
+export async function getAlarmInstances({
+    user = null,
+    count = 100,
+    index = 0,
+    name,
+    state,
+    severity,
+    sort,
+    order,
+} = {}) {
+    const params = new URLSearchParams();
+    params.set('count', String(count));
+    params.set('index', String(index));
+    if (name) params.set('name', name);
+    if (sort) params.set('sort', sort);
+    if (order) params.set('order', order);
+    appendMulti(params, 'state', state);
+    appendMulti(params, 'severity', severity);
+    try {
+        const res = await api.get(`${v1(user)}/alarms/instances?${params.toString()}`);
+        return Array.isArray(res.data) ? res.data : [];
+    } catch (e) {
+        throw apiError(e);
+    }
+}
+
+// Counter per state, e.g. { activated: 3, acknowledged: 1, ... }. The
+// server seeds zeros for every known state so consumers can render a
+// stable layout without null-checks.
+export async function getAlarmInstanceStats({ user = null } = {}) {
+    try {
+        const res = await api.get(`${v1(user)}/alarms/instances/stats`);
+        return res.data || {};
+    } catch (e) {
+        throw apiError(e);
+    }
+}
+
+export async function getAlarmInstance(instance, { user = null } = {}) {
+    try {
+        const res = await api.get(`${v1(user)}/alarms/instances/${encodeURIComponent(instance)}`);
+        return res.data;
+    } catch (e) {
+        throw apiError(e, { notFound: `Alarm instance not found: ${instance}` });
+    }
+}
+
+// PUT-style update. The server accepts only a small whitelist of fields
+// (see UPDATE_SCHEMA in alarms_instances.cpp): name, description, state,
+// annotation, reactivation. Anything else is rejected.
+export async function updateAlarmInstance(instance, body, { user = null } = {}) {
+    try {
+        const res = await api.put(
+            `${v1(user)}/alarms/instances/${encodeURIComponent(instance)}`,
+            body,
+        );
+        return res.data;
+    } catch (e) {
+        throw apiError(e, { notFound: `Alarm instance not found: ${instance}` });
+    }
+}
+
+export async function deleteAlarmInstance(instance, { user = null } = {}) {
+    try {
+        await api.delete(`${v1(user)}/alarms/instances/${encodeURIComponent(instance)}`);
+        return true;
+    } catch (e) {
+        throw apiError(e, { notFound: `Alarm instance not found: ${instance}` });
+    }
+}
+
+export async function getAlarmRules({ user = null, count = 200, index = 0 } = {}) {
+    const params = new URLSearchParams();
+    params.set('count', String(count));
+    params.set('index', String(index));
+    try {
+        const res = await api.get(`${v1(user)}/alarms/rules?${params.toString()}`);
+        return Array.isArray(res.data) ? res.data : [];
+    } catch (e) {
+        throw apiError(e);
+    }
+}
+
+export async function getAlarmRule(rule, { user = null } = {}) {
+    try {
+        const res = await api.get(`${v1(user)}/alarms/rules/${encodeURIComponent(rule)}`);
+        return res.data;
+    } catch (e) {
+        throw apiError(e, { notFound: `Alarm rule not found: ${rule}` });
+    }
+}
+
+// POST /v1/users/{user}/alarms/rules. The body must include `rule`,
+// `name`, `enabled` and an optional `config` object — see CREATE_SCHEMA
+// in alarms_rules.cpp for the full shape.
+export async function createAlarmRule(body, { user = null } = {}) {
+    try {
+        const res = await api.post(`${v1(user)}/alarms/rules`, body);
+        return res.data;
+    } catch (e) {
+        throw apiError(e);
+    }
+}
+
+export async function updateAlarmRule(rule, body, { user = null } = {}) {
+    try {
+        const res = await api.put(`${v1(user)}/alarms/rules/${encodeURIComponent(rule)}`, body);
+        return res.data;
+    } catch (e) {
+        throw apiError(e, { notFound: `Alarm rule not found: ${rule}` });
+    }
+}
+
+export async function deleteAlarmRule(rule, { user = null } = {}) {
+    try {
+        await api.delete(`${v1(user)}/alarms/rules/${encodeURIComponent(rule)}`);
+        return true;
+    } catch (e) {
+        throw apiError(e, { notFound: `Alarm rule not found: ${rule}` });
+    }
+}

package/lib/api.js

@@ -0,0 +1,91 @@
+import axios from 'axios';
+import { refreshToken, getAccessToken } from './auth.js';
+import { readConfig, serverURL } from './config.js';
+import { TIMEOUTS } from './constants.js';
+import { env } from './identity.js';
+import http from 'http';
+import https from 'https';
+
+const httpAgent = new http.Agent({ keepAlive: true });
+// Accept self-signed certificates when talking to local dev servers
+// (localhost / 127.0.0.1). Any other host still enforces full TLS
+// validation. Toggleable via <PREFIX>_INSECURE=1 for other local setups.
+const httpsAgent = new https.Agent({ keepAlive: true });
+const insecureAgent = new https.Agent({ keepAlive: true, rejectUnauthorized: false });
+
+const api = axios.create({
+    timeout: TIMEOUTS.API_DEFAULT_MS,
+    httpAgent,
+    httpsAgent,
+});
+
+api.interceptors.request.use(
+    (request) => {
+        // The server comes from the active profile on every request rather
+        // than from a process-wide default, so concurrent MCP tool calls
+        // scoped to different profiles each reach their own server.
+        if (!request.baseURL) request.baseURL = serverURL(readConfig().server);
+
+        // A caller probing a token it hasn't persisted yet sets the header
+        // itself; don't overwrite it with the stored one.
+        if (!request.headers['Authorization']) {
+            const token = getAccessToken();
+            if (token) request.headers['Authorization'] = `Bearer ${token}`;
+        }
+
+        // Allow self-signed TLS against localhost / 127.0.0.1 or when the user
+        // opts in explicitly. Anything else keeps default certificate validation.
+        // A malformed URL here is not worth aborting the request over — the
+        // HTTPS layer will surface the real error downstream; we only care
+        // about detecting localhost cheaply.
+        try {
+            const url = new URL(request.url || '', request.baseURL || 'https://placeholder/');
+            const isLocal = url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+            if (url.protocol === 'https:' && (isLocal || env('INSECURE') === '1')) {
+                request.httpsAgent = insecureAgent;
+            }
+        } catch {
+            // Intentionally swallowed — see note above.
+        }
+
+        return request;
+    },
+    (error) => {
+        return Promise.reject(error);
+    },
+);
+
+api.interceptors.response.use(
+    (response) => response,
+    async (error) => {
+        const originalRequest = error.config;
+
+        // Only intervene on 401s; everything else surfaces unchanged.
+        if (error.response?.status !== 401) return Promise.reject(error);
+
+        // Don't recurse: refresh requests themselves and already-retried
+        // requests must not trigger another refresh.
+        if (originalRequest?._isRefresh || originalRequest?._retry) {
+            return Promise.reject(error);
+        }
+
+        // Tokens issued via the username/password flow have no
+        // refresh_token. Skip the refresh attempt and let the 401 reach
+        // the caller — they can log in again.
+        if (!readConfig().refresh_token) return Promise.reject(error);
+
+        originalRequest._retry = true;
+
+        try {
+            const newToken = await refreshToken();
+            // Patch only this request; subsequent requests pick up the new
+            // token from config via the request interceptor.
+            originalRequest.headers['Authorization'] = `Bearer ${newToken}`;
+            return api(originalRequest);
+        } catch (refreshError) {
+            return Promise.reject(refreshError);
+        }
+    },
+);
+
+export default api;