@thinger-io/cli-core 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,105 @@
 # Changelog
 
+## [0.2.0] - 2026-10-10
+
+Incompatible change of the MCP tools: from 48 tools, one per type and
+operation, to 23, less than half the size in `tools/list` (about 23,200
+characters instead of 51,400, roughly 6,400 tokens instead of 14,300).
+
+### Added
+
+- Seven generic tools over a catalog of the server's resource types:
+  `resource_describe`, `resource_list`, `resource_get`, `resource_create`,
+  `resource_update` (`merge: true` patches property values; `projects` in
+  the body sets the resource's projects), `resource_delete`,
+  `resource_clone`. The catalog (`mcp/catalog.js`) covers devices,
+  products, buckets, dashboards, endpoints, storages, asset types and
+  groups, projects, tokens, alarm rules and instances, claims, account
+  properties and their children (device properties, tokens, buckets, bucket
+  tags, services and HTTP callback; product properties, profile entries,
+  code and services; bucket tags and exports; asset type, asset group and
+  project properties; roles, project members and roles, syncs) and the
+  server's administration (users, hosts, domains, brands, OAuth clients,
+  identity providers, proxies, under /v1 rather than an account). Each tool
+  offers only the types that support its verb; permissions are the
+  server's to enforce.
+- `resource_describe` reads the request schemas and examples from the
+  server's own OpenAPI document (`/v1/server/swagger.json`), cached per
+  server and version in `~/.config/<cli>/cache`; servers that do not publish
+  it fall back to the bundled copy (`openapi/swagger.json`, the server's
+  develop as of 2026-10-10). It also lists, for each verb, the permission action a token
+  needs (`permissions`: `Device` / `ReadDeviceStatus`…), taken from the same
+  document.
+- Resource hooks: generated device credentials, the identity's product
+  template, device token expiries as durations ("30d") and permission tree
+  checks.
+  CLIs add theirs with `runCli({ resourceHooks })`.
+- Plugins: type `plugin` (installed by default; the installable catalog
+  with filter `available`, summarised) with actions install, upgrade,
+  remove, start, stop, restart, pause, unpause, kill, public, private;
+  `plugin_property`; and `plugin_call` for the API each plugin serves.
+  Lists that ignore count/index are paged client-side, and `resource_list`
+  takes a `search`: by id or name on the server (escaped, any case), or
+  over every field shown on lists the server answers whole (plugins).
+- `resource_call`: actions of a type that are not CRUD, declared in the
+  catalog with their operationId (checked against the OpenAPI document):
+  verify a domain, restart a host or read/replace its settings, send a
+  brand's test email, call an endpoint, export a product, read a device's
+  usage, test an alarm rule (rule, source, notification).
+- Tools that are not CRUD: `bucket_data_read`, `bucket_data_write`,
+  `device_resource_list`, `device_resource_call`, `device_data_send`,
+  `device_overview`, `product_resource_call`,
+  `storage_file_list` / `_read` / `_write` / `_delete`.
+- `dashboard_publish`: publishes HTML apps as url-source dashboards
+  (servers with url-source dashboards). Uploads a local folder (a build
+  output, subfolders included) or inline files to a public storage, with
+  `prune` to delete files a new build no longer has; and/or points
+  dashboards at it: dashboards of the collection, or the `dashboard`
+  property of a device, product, asset type, asset group or project
+  (checked before anything is uploaded), each with its own entry page and
+  initial hash route. One storage can serve an app shared by many
+  dashboards. Entry urls carry `?v=` against stale caches; scripts and
+  styles without a content hash are reported.
+- `doc_read`: the documentation the server publishes for agents, listed in
+  its index (`/sdk/docs.json`): a guide to the platform's concepts, the
+  dashboard SDK reference, its TypeScript declarations… A guide added to the
+  index reaches the model without a CLI release. The same documents are MCP
+  resources (`<prefix>://<id>`), the concepts guide is appended to
+  `resource_describe` without a type, and the SDK reference to
+  `resource_describe` of the dashboard type. Only paths on the profile's own
+  server are followed. CLIs add the guides they ship with
+  `runCli({ docs })`, listed first and readable without a server.
+- `scripts/catalog-draft.js`: drafts catalog entries from an OpenAPI
+  document.
+
+### Changed
+
+- A 403 no longer says the token may have expired: it says the token or the
+  account is not allowed, with the server's reason. The error code is still
+  `unauthorized`.
+- `profiles` is now `profile_list`; `bucket_read` is `bucket_data_read`;
+  `resource_list` / `resource_call` (device resources) are
+  `device_resource_list` / `device_resource_call`.
+- `buildTools(extraTools, { admin, hooks })`; `genericTools` is now a
+  function of the same options.
+
+### Removed
+
+- The per-type tools, replaced by `resource_*` on the matching type:
+  `devices`, `device_info`, `device_create`, `device_set_product`,
+  `device_delete`, `products`, `product_create`, `product_update`,
+  `product_delete`, `product_property_*`, `product_profile_*`,
+  `property_get`, `property_set`, `token_*`, `device_token_*`,
+  `alarm_rules`, `alarm_rule_*`, `alarm_instances`, `alarm_instance_*`,
+  `buckets`.
+
+## [0.1.1] - 2026-10-10
+
+### Fixed
+
+- `repository.url` in the canonical `git+https` form npm expects; first release
+  published from GitHub Actions through Trusted Publishing.
+
 ## [0.1.0] - 2026-10-10
 
 First version, extracted from the core of `thinr` 1.3.5 and made

package/README.md

@@ -18,7 +18,13 @@ It holds everything that is not specific to a product:
   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.
+- **MCP** (`mcp/*`) — the stdio server and 22 generic tools: eight
+  `resource_*` tools over a catalog of the server's resource types, and the
+  operations that are not CRUD (bucket data, device resources, storage
+  files, dashboard publishing, the server's documentation…), plus that
+  documentation as MCP resources.
+- **OpenAPI** (`openapi`) — the server's own API description, cached per
+  server and version, with a bundled copy as fallback.
 
 ## Identity
 
@@ -38,7 +44,7 @@ defineIdentity({
     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, …
+    mcp: { serverName: 'acme', toolPrefix: 'acme' }, // tools become acme_resource_list, …
     productTemplate: {}, // optional defaults for new products
 });
 
@@ -58,11 +64,37 @@ servers.
 - `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.
+  (`name: 'device_exec'`) and referring to others in descriptions as
+  `{tool:resource_list}` or `{family:storage_file}`. Unknown references fail
+  at startup. A tool flagged `replaces: true` swaps out the generic tool of
+  the same name.
+- `resourceHooks` — the CLI's hooks on catalog types (`{ product: {
+afterDelete } }`), run after the core's: see `mcp/resource-hooks.js`.
 - `mcpInstructions` — server-level guidance sent to MCP clients.
 
+## MCP tools
+
+Tool names follow `<object>[_<subobject>]_<verb>`, with the verbs list, get,
+describe, create, update, delete, clone, call, read, write, send.
+
+The server's collections are reached through eight generic tools —
+`resource_describe`, `resource_list`, `resource_get`, `resource_create`,
+`resource_update`, `resource_delete`, `resource_clone`, `resource_call`
+(actions that are not CRUD) — that take a `type`
+from the catalog (`lib/mcp/catalog.js`), a `parent` for child types and an
+`id`. The catalog is a reviewed table, never discovered at run time: each
+type has its path, API version, parent, id and the verbs it allows, with the
+server's operationId for each (the tests check them against the bundled
+OpenAPI document). `resource_describe` reads the request schemas and
+examples from the OpenAPI document of the server the profile points at.
+
+To draft catalog entries after an API change:
+
+```bash
+curl -s https://<server>/v1/server/swagger.json -o openapi/swagger.json
+node scripts/catalog-draft.js
+```
+
 Modules are imported by path: `@thinger-io/cli-core/api`,
 `@thinger-io/cli-core/mcp/registry`, …
 

package/lib/api.js

@@ -17,6 +17,9 @@ const api = axios.create({
     timeout: TIMEOUTS.API_DEFAULT_MS,
     httpAgent,
     httpsAgent,
+    // Arrays as repeated keys (product=a&product=b), which the server reads
+    // as "any of"; axios's default product[]=a matches only the first.
+    paramsSerializer: { indexes: null },
 });
 
 api.interceptors.request.use(

package/lib/auth.js

@@ -4,8 +4,11 @@ import ora from 'ora';
 import open, { apps } from 'open';
 import {
     getActiveProfile,
+    getProfile,
     mergeConfig,
+    profileTarget,
     readConfig,
+    restoreProfile,
     setActiveProfile,
     writeConfig,
 } from './config.js';
@@ -90,15 +93,32 @@ export async function authenticate(opts = {}) {
     // Persist the server first: the API client takes its base URL from the
     // active profile, so the login requests below already reach it.
     // Pin the profile just written, so the merges below land on it even
-    // when another profile is the default.
-    setActiveProfile(writeConfig({ server }));
-
-    if (method === 'userpass') {
-        await authenticateWithUserPass(opts);
-    } else if (method === 'oauth') {
-        await authenticateWithOAuth(opts, existing);
-    } else {
-        await authenticateWithToken(opts);
+    // when another profile is the default. A login that fails or is
+    // interrupted puts the previous profile back: a wrong password must
+    // not leave the user (and their MCP servers) signed out.
+    const target = profileTarget(server);
+    const previous = target ? getProfile(target) : undefined;
+    const name = writeConfig({ server });
+    setActiveProfile(name);
+    const restore = () => restoreProfile(name, previous);
+    const onSigint = () => {
+        restore();
+        process.exit(130);
+    };
+    process.once('SIGINT', onSigint);
+    try {
+        if (method === 'userpass') {
+            await authenticateWithUserPass(opts);
+        } else if (method === 'oauth') {
+            await authenticateWithOAuth(opts, existing);
+        } else {
+            await authenticateWithToken(opts);
+        }
+    } catch (error) {
+        restore();
+        throw error;
+    } finally {
+        process.removeListener('SIGINT', onSigint);
     }
 }
 

package/lib/bucket.js

@@ -38,6 +38,7 @@ import { v1, v2, v3 } from './paths.js';
  *   max_ts?: number,
  *   agg?: string,
  *   agg_type?: string,
+ *   tz?: string,
  *   fields?: string,
  *   group_by?: string | null,
  * }} opts
@@ -53,6 +54,7 @@ export async function getBucketData({
     max_ts,
     agg,
     agg_type,
+    tz,
     fields,
     group_by,
 } = {}) {
@@ -67,6 +69,7 @@ export async function getBucketData({
     }
     if (agg) params.agg = agg;
     if (agg_type) params.agg_type = agg_type;
+    if (tz) params.tz = tz;
     if (group_by) params.group_by = group_by;
     if (fields) params.fields = fields;
 

package/lib/cli.js

@@ -22,11 +22,16 @@ import { registerBucketCommands } from './commands/bucket.js';
  *   onNoCommand?: (program: Command) => Promise<void> | void,
  *   mcpTools?: Array<object>,
  *   mcpInstructions?: string,
+ *   resourceHooks?: Record<string, import('./mcp/resource-hooks.js').ResourceHooks>,
+ *   docs?: Parameters<typeof import('./docs.js').defineCliDocs>[0],
  * }} opts
  *   `register` adds the CLI's own commands, at the top level or inside the
  *   generic groups. `onNoCommand` runs when the CLI is called without
  *   arguments (default: print the help). `mcpTools` are the CLI's own MCP
- *   tools (see buildTools).
+ *   tools (see buildTools), and `resourceHooks` its hooks on the
+ *   catalog types the generic `resource_*` tools serve. `docs` are guides
+ *   the CLI ships, served by `doc_read` and as MCP resources next to the
+ *   server's documentation.
  */
 export async function runCli({
     version,
@@ -35,6 +40,8 @@ export async function runCli({
     onNoCommand,
     mcpTools = [],
     mcpInstructions,
+    resourceHooks,
+    docs,
 }) {
     const id = identity();
 
@@ -79,7 +86,13 @@ export async function runCli({
         .description('Start the MCP server (stdio) for AI tool integration')
         .action(async () => {
             try {
-                await startMCPServer({ version, tools: mcpTools, instructions: mcpInstructions });
+                await startMCPServer({
+                    version,
+                    tools: mcpTools,
+                    instructions: mcpInstructions,
+                    resourceHooks,
+                    docs,
+                });
             } catch (error) {
                 console.error(`Error: ${classifyError(error).message}`);
                 process.exit(1);

package/lib/config.js

@@ -50,8 +50,20 @@ function getConfigPath() {
     if (!fs.existsSync(configDir)) {
         fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
     }
+    ownerOnly(configDir, 0o700);
+    const configPath = path.join(configDir, 'config.json');
+    if (fs.existsSync(configPath)) ownerOnly(configPath, 0o600);
+    return configPath;
+}
 
-    return path.join(configDir, 'config.json');
+/**
+ * Folder for data the CLI can always rebuild (server API descriptions…),
+ * next to the profiles. Created on first access.
+ */
+export function cacheDir() {
+    const dir = path.join(os.homedir(), '.config', identity().configDir, 'cache');
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
 }
 
 function emptyStore() {
@@ -79,10 +91,27 @@ function readStore() {
     return raw;
 }
 
+/**
+ * Take group and other permissions away from a file or folder made by an
+ * older version (or by hand): `mode` on create does not fix existing ones.
+ */
+function ownerOnly(file, mode) {
+    try {
+        if ((fs.statSync(file).mode & 0o077) !== 0) fs.chmodSync(file, mode);
+    } catch {
+        // Not ours to fix (another owner, a filesystem without modes).
+    }
+}
+
 function writeStore(store) {
     const configPath = getConfigPath();
-    // The file holds API tokens: keep it readable by its owner only.
-    fs.writeFileSync(configPath, JSON.stringify(store, null, 2), { encoding: 'utf8', mode: 0o600 });
+    // The file holds API tokens: readable by its owner only. Written aside
+    // and renamed, so a crash or a concurrent reader never sees half a file,
+    // and the rename leaves the new file's mode on the path.
+    const tmp = `${configPath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(store, null, 2), { encoding: 'utf8', mode: 0o600 });
+    ownerOnly(tmp, 0o600);
+    fs.renameSync(tmp, configPath);
 }
 
 /**
@@ -247,8 +276,7 @@ export function requireConfig() {
  */
 export function writeConfig(config) {
     const store = readStore();
-    const name =
-        activeProfileOverride || profileNameFor(config && config.server) || getActiveProfile();
+    const name = profileTarget(config && config.server);
     if (!name) {
         throw new Error('Cannot write config without a server / profile name');
     }
@@ -258,6 +286,28 @@ export function writeConfig(config) {
     return name;
 }
 
+/** The profile writeConfig({ server }) writes to. */
+export function profileTarget(server) {
+    return activeProfileOverride || profileNameFor(server) || getActiveProfile();
+}
+
+/**
+ * Put a profile back as it was (`undefined`: it did not exist), after a
+ * login that failed half-way.
+ *
+ * @param {string} name
+ * @param {Record<string, any> | undefined} profile
+ */
+export function restoreProfile(name, profile) {
+    const store = readStore();
+    if (profile) {
+        store.profiles[name] = profile;
+        writeStore(store);
+    } else if (store.profiles[name]) {
+        deleteProfile(name);
+    }
+}
+
 /**
  * Merge fields into the active profile.
  */

package/lib/constants.js

@@ -12,6 +12,14 @@ export const TIMEOUTS = {
     /** Default axios request timeout for control-plane HTTP calls. */
     API_DEFAULT_MS: 10_000,
 
+    /**
+     * Requests that do work on the server or move files: resource actions
+     * (plugin install pulls a container, bucket import, product export),
+     * device and plugin calls, uploads. The server keeps working past a
+     * client timeout, so a short one only makes callers retry half-done jobs.
+     */
+    API_LONG_MS: 10 * 60 * 1000,
+
     /**
      * Refresh a JWT access token this close to (or past) its `exp`
      * before opening a WebSocket. WS handshakes lack the