@thinger-io/cli-core 0.1.0 → 0.2.0

package/lib/mcp/tools-storage.js

@@ -0,0 +1,173 @@
+// @ts-check
+import fs from 'node:fs';
+import nodePath from 'node:path';
+import api from '../api.js';
+import { collectFiles, uploadFiles } from '../dashboard.js';
+import { apiError, inputError } from '../errors.js';
+import { v1 } from '../paths.js';
+import { deleteStorageFile, readStorageFile, writeStorageFile } from '../storage.js';
+
+/** Files of a storage (the storages themselves are the catalog type "storage"). */
+
+const text = (t) => ({ content: [{ type: 'text', text: t }], isError: false });
+const userParam = { type: 'string', description: 'Account to act on (admin only).' };
+const storageParam = { type: 'string', description: 'Storage id.' };
+
+function required(args, ...names) {
+    for (const name of names) {
+        if (args[name] === undefined || args[name] === '') throw inputError(`${name} is required`);
+    }
+}
+
+/** A path inside the storage, without leading slashes (they would double up in the URL). */
+const clean = (p) => String(p).replace(/^\/+/, '');
+
+async function toolList(args) {
+    required(args, 'storage');
+    const params = args.path ? { path: clean(args.path) } : undefined;
+    try {
+        const res = await api.get(
+            `${v1(args.user)}/storages/${encodeURIComponent(args.storage)}/files`,
+            { params },
+        );
+        const files = Array.isArray(res.data) ? res.data : [];
+        return text(files.length ? files.map((f) => JSON.stringify(f)).join('\n') : 'No files.');
+    } catch (e) {
+        // The server keeps files on disk and creates a storage's folder with
+        // its first file: an empty storage answers 404 too.
+        if (e.response?.status === 404) {
+            return text(
+                `No files${args.path ? ` under ${clean(args.path)}` : ''} (or no storage ${args.storage}).`,
+            );
+        }
+        throw apiError(e);
+    }
+}
+
+async function toolRead(args) {
+    required(args, 'storage', 'path');
+    return text(await readStorageFile(args.storage, clean(args.path), args.user));
+}
+
+/** Largest single local file uploaded at once. */
+const MAX_FILE = 50 * 1024 * 1024;
+/** Largest local folder uploaded in one call. */
+const MAX_FOLDER = 200 * 1024 * 1024;
+
+/** Upload a local file (to `path`, default its name) or folder (under `path`). */
+async function uploadLocal(args) {
+    if (args.content !== undefined) throw inputError('pass content or local, not both');
+    const local = nodePath.resolve(String(args.local));
+    if (!fs.existsSync(local)) throw inputError(`No such local file or folder: ${args.local}`);
+    /** @type {Record<string, Buffer>} */
+    let files;
+    if (fs.statSync(local).isDirectory()) {
+        const prefix = args.path ? `${clean(args.path).replace(/\/+$/, '')}/` : '';
+        files = Object.fromEntries(
+            Object.entries(
+                collectFiles(local, {
+                    skip: new Set(['.git']),
+                    maxBytes: MAX_FOLDER,
+                    tooLarge: 'upload its subfolders or files in separate calls',
+                }),
+            ).map(([f, c]) => [prefix + f, c]),
+        );
+        if (!Object.keys(files).length) throw inputError(`${args.local} has no files`);
+    } else {
+        if (fs.statSync(local).size > MAX_FILE) {
+            throw inputError(`${args.local} is larger than ${MAX_FILE / 1024 / 1024} MB`);
+        }
+        files = {
+            [args.path ? clean(args.path) : nodePath.basename(local)]: fs.readFileSync(local),
+        };
+    }
+    await uploadFiles(args.storage, files, args.user);
+    const names = Object.keys(files);
+    const bytes = Object.values(files).reduce((n, c) => n + c.length, 0);
+    const shown =
+        names.slice(0, 20).join(', ') + (names.length > 20 ? `… (+${names.length - 20})` : '');
+    return text(
+        `Uploaded ${names.length} file(s), ${bytes} bytes, to storage ${args.storage}: ${shown}.`,
+    );
+}
+
+async function toolWrite(args) {
+    required(args, 'storage');
+    if (args.local !== undefined) return uploadLocal(args);
+    required(args, 'path');
+    if (typeof args.content !== 'string') throw inputError('content must be a string');
+    await writeStorageFile(args.storage, clean(args.path), args.content, args.user);
+    return text(
+        `Wrote ${clean(args.path)} (${Buffer.byteLength(args.content)} bytes) to storage ${args.storage}.`,
+    );
+}
+
+async function toolDelete(args) {
+    required(args, 'storage', 'path');
+    const deleted = await deleteStorageFile(args.storage, clean(args.path), args.user);
+    return text(deleted ? `Deleted ${clean(args.path)}.` : `No such file: ${clean(args.path)}.`);
+}
+
+const pathParam = {
+    type: 'string',
+    description: 'File path inside the storage, e.g. "web/index.html".',
+};
+
+export const tools = [
+    {
+        name: 'storage_file_list',
+        description:
+            'List the files of a storage (path, size, modification time), optionally only under a folder.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                storage: storageParam,
+                path: { type: 'string', description: 'Folder to list.' },
+                user: userParam,
+            },
+            required: ['storage'],
+        },
+        handler: toolList,
+    },
+    {
+        name: 'storage_file_read',
+        description: 'Read a text file of a storage.',
+        inputSchema: {
+            type: 'object',
+            properties: { storage: storageParam, path: pathParam, user: userParam },
+            required: ['storage', 'path'],
+        },
+        handler: toolRead,
+    },
+    {
+        name: 'storage_file_write',
+        description:
+            'Create or overwrite files in a storage; folders on the path are created. Either `content` (text) at `path`, or `local`: a file or folder on this machine, uploaded as is (binary too) to `path` (a file defaults to its own name; a folder goes under `path`, or the root). Use `local` for anything big: CSV to import, images, product code with its node_modules.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                storage: storageParam,
+                path: pathParam,
+                content: { type: 'string', description: 'Text content of the file at `path`.' },
+                local: {
+                    type: 'string',
+                    description:
+                        'Local file or folder to upload instead of `content` (up to 50 MB per file and 200 MB per call).',
+                },
+                user: userParam,
+            },
+            required: ['storage'],
+        },
+        handler: toolWrite,
+    },
+    {
+        name: 'storage_file_delete',
+        description: 'Delete a file of a storage. Permanent: confirm with the user first.',
+        inputSchema: {
+            type: 'object',
+            properties: { storage: storageParam, path: pathParam, user: userParam },
+            required: ['storage', 'path'],
+        },
+        handler: toolDelete,
+    },
+];

package/lib/openapi.js

@@ -0,0 +1,169 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import api from './api.js';
+import { cacheDir, readConfig, serverURL } from './config.js';
+
+/**
+ * The server's own description of its API.
+ *
+ * Every Thinger server publishes its OpenAPI document without a token at
+ * `/v1/server/swagger.json`, and its version at `/v1/server/version`. The
+ * document is what `resource_describe` reads the request schemas and
+ * examples from, so they always match the server the profile points at
+ * rather than whichever version this package was built against.
+ *
+ * It is cached per server and version: in memory for the life of the
+ * process and on disk under the CLI's cache folder, so a new MCP session
+ * costs one small version request instead of a 300 KB download. A server
+ * with the document disabled (`deployment.disable_swagger`) falls back to
+ * the copy bundled with this package, flagged as such.
+ */
+
+const BUNDLED_FILE = new URL('../openapi/swagger.json', import.meta.url);
+/** Server version the bundled copy was taken from. */
+export const BUNDLED_VERSION = 'develop 2026-10-11 (98)';
+
+/** @type {Map<string, Promise<Spec>>} */
+const memory = new Map();
+
+/**
+ * @typedef {object} Spec
+ * @property {any} doc            The OpenAPI document, or null when none is available.
+ * @property {string} source      Where it came from: "server 7.2.4-beta", "bundled copy (…)".
+ */
+
+/** The bundled OpenAPI document (also the fixture the tests check the catalog against). */
+export function bundledSpec() {
+    return JSON.parse(fs.readFileSync(BUNDLED_FILE, 'utf8'));
+}
+
+/**
+ * OpenAPI document of the active profile's server.
+ *
+ * @returns {Promise<Spec>}
+ */
+export async function serverSpec() {
+    const base = serverURL(readConfig().server) || '';
+    let version = 'unknown';
+    try {
+        const res = await api.get('/v1/server/version');
+        version = String(res.data?.version || 'unknown');
+    } catch {
+        // An unreachable server fails the real request soon enough; the
+        // description can still come from the bundled copy.
+    }
+    const key = `${base}@${version}`;
+    if (!memory.has(key)) {
+        const pending = loadSpec(base, version);
+        // A failed load must not stick: the next call tries again.
+        pending.catch(() => memory.delete(key));
+        memory.set(key, pending);
+    }
+    return memory.get(key);
+}
+
+async function loadSpec(base, version) {
+    const file = path.join(cacheDir(), `openapi-${slug(base)}-${slug(version)}.json`);
+    if (version !== 'unknown') {
+        try {
+            return { doc: JSON.parse(fs.readFileSync(file, 'utf8')), source: `server ${version}` };
+        } catch {
+            // Not cached yet (or unreadable): fetch it.
+        }
+    }
+    try {
+        const res = await api.get('/v1/server/swagger.json');
+        if (res.data && typeof res.data === 'object' && res.data.paths) {
+            if (version !== 'unknown') {
+                try {
+                    fs.writeFileSync(file, JSON.stringify(res.data));
+                } catch {
+                    // A read-only home only costs the next session a download.
+                }
+            }
+            return { doc: res.data, source: `server ${version}` };
+        }
+    } catch {
+        // Disabled or unreachable: fall through to the bundled copy.
+    }
+    return {
+        doc: bundledSpec(),
+        source: `bundled copy (server ${BUNDLED_VERSION}; this server, ${version}, does not publish its own)`,
+    };
+}
+
+function slug(text) {
+    return String(text)
+        .replace(/^[a-z]+:\/\//i, '')
+        .replace(/[^a-zA-Z0-9.-]+/g, '_');
+}
+
+/**
+ * Find the operation a method and path template refer to. Ids in the
+ * template are written `{}`; a server path parameter matches any segment,
+ * and the path with the most literal matches wins, so `profile/code`
+ * finds its own entry instead of `profile/{category}`.
+ *
+ * @param {any} doc
+ * @param {string} method
+ * @param {string} template
+ * @returns {{ path: string, operation: any } | null}
+ */
+export function findOperation(doc, method, template) {
+    const want = template.split('/');
+    let best = null;
+    let bestScore = -1;
+    for (const [p, item] of Object.entries(doc?.paths || {})) {
+        const have = p.split('/');
+        if (have.length !== want.length || !item[method]) continue;
+        let score = 0;
+        let ok = true;
+        for (let i = 0; i < have.length; i++) {
+            const param = have[i].startsWith('{');
+            if (param) continue;
+            if (have[i] !== want[i]) {
+                ok = false;
+                break;
+            }
+            score++;
+        }
+        if (ok && score > bestScore) {
+            best = { path: p, operation: item[method] };
+            bestScore = score;
+        }
+    }
+    return best;
+}
+
+const SCALARS = new Set(['string', 'number', 'integer', 'boolean']);
+const VERBOSE = new Set(['description', 'example', 'examples', 'title']);
+
+/**
+ * Copy of `node` with every local `$ref` replaced by what it points to.
+ * A schema that refers to itself is cut at the second visit.
+ *
+ * @param {any} doc
+ * @param {any} node
+ */
+export function resolveRefs(doc, node, seen = new Set()) {
+    if (Array.isArray(node)) return node.map((n) => resolveRefs(doc, n, seen));
+    if (!node || typeof node !== 'object') return node;
+    if (typeof node.$ref === 'string' && node.$ref.startsWith('#/')) {
+        if (seen.has(node.$ref)) return { description: `(recursive: ${node.$ref})` };
+        const target = node.$ref
+            .slice(2)
+            .split('/')
+            .reduce((n, key) => n?.[key], doc);
+        // A shared scalar (resource_id, resource_name…) appears once per
+        // field that uses it: its constraints say all there is to say, the
+        // prose and examples repeated on every field would only bury them.
+        if (target && typeof target === 'object' && SCALARS.has(target.type)) {
+            return Object.fromEntries(Object.entries(target).filter(([key]) => !VERBOSE.has(key)));
+        }
+        return resolveRefs(doc, target, new Set([...seen, node.$ref]));
+    }
+    return Object.fromEntries(
+        Object.entries(node).map(([key, value]) => [key, resolveRefs(doc, value, seen)]),
+    );
+}

package/lib/paths.js

@@ -30,3 +30,11 @@ export function v3(user) {
 export function device(user, deviceId) {
     return `${v3(user)}/devices/${deviceId}`;
 }
+
+/**
+ * `/users/{account}/plugins/{plugin}` — where a plugin serves its own API
+ * (no version prefix: the plugin defines the rest of the path).
+ */
+export function pluginApi(user, plugin) {
+    return `/users/${resolveUser(user)}/plugins/${encodeURIComponent(plugin)}`;
+}

package/lib/resource.js

@@ -1,6 +1,7 @@
 import { resolveUser } from './config.js';
 import { device } from './paths.js';
 import api from './api.js';
+import { TIMEOUTS } from './constants.js';
 import { apiError } from './errors.js';
 import { info, warning, hint } from './format.js';
 
@@ -69,6 +70,7 @@ export async function executeDeviceResource(deviceId, resourceId, inputs, option
         const response = await api.post(
             `${device(user, deviceId)}/resources/${resourceId}`,
             inputs,
+            { timeout: TIMEOUTS.API_LONG_MS },
         );
         return response.data;
     } catch (error) {

package/lib/storage.js

@@ -1,4 +1,5 @@
 import api from './api.js';
+import { TIMEOUTS } from './constants.js';
 import { apiError } from './errors.js';
 import { v1, v2 } from './paths.js';
 
@@ -99,7 +100,7 @@ export async function writeStorageFile(storageId, filePath, content, user) {
         await api.put(
             `${v2(user)}/storages/${storageId}/files/${filePath}?overwrite=true`,
             content,
-            { headers: { 'Content-Type': 'text/plain' } },
+            { headers: { 'Content-Type': 'text/plain' }, timeout: TIMEOUTS.API_LONG_MS },
         );
     } catch (e) {
         throw apiError(e);