@thingd/cli 0.77.0 → 0.77.2

package/dist/data-movement.d.ts

@@ -0,0 +1,6 @@
+import { type CliContext } from "./index.js";
+export declare function runExport(context: CliContext): Promise<void>;
+export declare function runImport(context: CliContext): Promise<void>;
+export declare function runSnapshot(context: CliContext): Promise<void>;
+export declare function runBackup(context: CliContext): Promise<void>;
+//# sourceMappingURL=data-movement.d.ts.map

package/dist/data-movement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-movement.d.ts","sourceRoot":"","sources":["../src/data-movement.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,KAAK,UAAU,EAAwD,MAAM,YAAY,CAAC;AAwEnG,wBAAsB,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAyClE;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAsFlE;AAoND,wBAAsB,WAAW,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAmHpE;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAyClE"}

package/dist/data-movement.js

@@ -0,0 +1,475 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { hasFlag, requiredFlag, stringFlag, withDb, writeJson } from "./index.js";
+const SIDECAR_DEFAULT_URL = "http://localhost:8757";
+const DEFAULT_REDACT_KEYS = [
+    "password",
+    "secret",
+    "token",
+    "key",
+    "auth",
+    "credential",
+    "email",
+    "phone",
+    "session",
+    "cookie",
+    "signature",
+    "private",
+    "cert",
+    "api",
+];
+function redactText(text) {
+    let res = text;
+    // Redact emails
+    res = res.replace(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, "[REDACTED_EMAIL]");
+    // Redact API keys matching sk-...
+    res = res.replace(/sk-[a-zA-Z0-9]{20,}/g, "[REDACTED_KEY]");
+    // Redact Bearer tokens
+    res = res.replace(/bearer\s+[a-zA-Z0-9\-._~+/]+=*/gi, "Bearer [REDACTED]");
+    return res;
+}
+function redactValue(val, redactKeys) {
+    if (val === null || val === undefined) {
+        return val;
+    }
+    if (Array.isArray(val)) {
+        return val.map((item) => redactValue(item, redactKeys));
+    }
+    if (typeof val === "object") {
+        const obj = val;
+        const result = {};
+        for (const [k, v] of Object.entries(obj)) {
+            const lowerKey = k.toLowerCase();
+            const shouldRedact = redactKeys.some((rKey) => lowerKey.includes(rKey.toLowerCase()));
+            if (shouldRedact) {
+                result[k] = "[REDACTED]";
+            }
+            else if (v && typeof v === "object") {
+                result[k] = redactValue(v, redactKeys);
+            }
+            else if (typeof v === "string" && k === "text") {
+                result[k] = redactText(v);
+            }
+            else {
+                result[k] = v;
+            }
+        }
+        return result;
+    }
+    return val;
+}
+export async function runExport(context) {
+    const isEvents = hasFlag(context.parsed, "events");
+    const collection = stringFlag(context.parsed, "collection");
+    const outPath = requiredFlag(context.parsed, "out");
+    if (!isEvents && !collection) {
+        throw new Error("Must specify either --collection <name> or --events for export.");
+    }
+    if (isEvents && collection) {
+        throw new Error("Cannot specify both --collection <name> and --events.");
+    }
+    await withDb(context, async (db) => {
+        const redactFlag = stringFlag(context.parsed, "redact");
+        const isRedact = hasFlag(context.parsed, "redact");
+        const redactKeys = isRedact
+            ? redactFlag
+                ? redactFlag.split(",").map((k) => k.trim())
+                : DEFAULT_REDACT_KEYS
+            : null;
+        let lines = [];
+        if (collection) {
+            const objects = await db.listObjects(collection);
+            lines = objects.map((obj) => {
+                const finalObj = redactKeys ? redactValue(obj, redactKeys) : obj;
+                return JSON.stringify(finalObj);
+            });
+        }
+        else {
+            const stream = stringFlag(context.parsed, "stream");
+            const events = await db.events.list(stream);
+            lines = events.map((ev) => {
+                const finalEv = redactKeys ? redactValue(ev, redactKeys) : ev;
+                return JSON.stringify(finalEv);
+            });
+        }
+        writeFileSync(resolve(outPath), `${lines.join("\n")}\n`, "utf8");
+        writeJson(context.stdout, { success: true, count: lines.length, out: outPath }, context.pretty);
+    });
+}
+export async function runImport(context) {
+    const source = stringFlag(context.parsed, "source") ?? context.parsed.tokens[1] ?? "";
+    const type = stringFlag(context.parsed, "type");
+    const isDb = source.startsWith("postgresql://") ||
+        source.startsWith("postgres://") ||
+        source.startsWith("mysql://") ||
+        type === "postgres" ||
+        type === "mysql";
+    if (isDb) {
+        await runImportDb(context, source, type);
+        return;
+    }
+    // --- existing file import logic (unchanged) ---
+    const collection = requiredFlag(context.parsed, "collection");
+    const inPath = requiredFlag(context.parsed, "in");
+    const resolvedPath = resolve(inPath);
+    if (!existsSync(resolvedPath)) {
+        throw new Error(`Input file not found: ${inPath}`);
+    }
+    const content = readFileSync(resolvedPath, "utf8");
+    const lines = content
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+    // Detect file type
+    const isCsv = inPath.endsWith(".csv");
+    await withDb(context, async (db) => {
+        let count = 0;
+        if (isCsv) {
+            // Parse CSV
+            const headers = lines[0]?.split(",").map((h) => h.trim()) ?? [];
+            for (let i = 1; i < lines.length; i++) {
+                const values = lines[i]?.split(",") ?? [];
+                const obj = {};
+                for (let j = 0; j < headers.length; j++) {
+                    const key = headers[j];
+                    if (!key) {
+                        continue;
+                    }
+                    const val = values[j]?.trim() ?? "";
+                    // Try to infer types
+                    if (val === "" || val === "null") {
+                        obj[key] = null;
+                    }
+                    else if (val === "true") {
+                        obj[key] = true;
+                    }
+                    else if (val === "false") {
+                        obj[key] = false;
+                    }
+                    else if (!Number.isNaN(Number(val))) {
+                        obj[key] = Number(val);
+                    }
+                    else {
+                        obj[key] = val;
+                    }
+                }
+                // Add row index as ID if not present
+                if (!obj.id) {
+                    obj.id = `row-${i}`;
+                }
+                await db.put(collection, obj);
+                count += 1;
+            }
+        }
+        else {
+            // Parse JSONL
+            for (const line of lines) {
+                const parsedObj = JSON.parse(line);
+                if (!parsedObj.id || typeof parsedObj.id !== "string") {
+                    throw new Error("Imported object must contain a string 'id' field.");
+                }
+                await db.put(collection, parsedObj);
+                count += 1;
+            }
+        }
+        writeJson(context.stdout, { success: true, count, collection, format: isCsv ? "csv" : "jsonl" }, context.pretty);
+    });
+}
+// ── DB import helpers ──────────────────────────────────────────────────
+function resolveSidecarUrl(context) {
+    const flag = stringFlag(context.parsed, "sidecar");
+    if (flag) {
+        return flag.replace(/\/$/, "");
+    }
+    const envUrl = context.env.THINGD_URL;
+    if (envUrl) {
+        const normalized = envUrl.replace(/\/$/, "");
+        if (normalized.startsWith("http://") || normalized.startsWith("https://")) {
+            return normalized;
+        }
+    }
+    return SIDECAR_DEFAULT_URL;
+}
+function authHeaders(context) {
+    const token = stringFlag(context.parsed, "auth-token") ?? context.env.THINGD_AUTH_TOKEN;
+    return token ? { Authorization: `Bearer ${token}` } : {};
+}
+function detectConnectorType(source, explicitType) {
+    if (explicitType === "postgres" || explicitType === "mysql") {
+        return explicitType;
+    }
+    if (source.startsWith("postgresql://") || source.startsWith("postgres://")) {
+        return "postgres";
+    }
+    if (source.startsWith("mysql://")) {
+        return "mysql";
+    }
+    throw new Error(`Could not detect connector type from "${source.slice(0, 30)}...". Use --type postgres or --type mysql.`);
+}
+function parseConnectionString(source) {
+    const isUri = source.startsWith("postgresql://") ||
+        source.startsWith("postgres://") ||
+        source.startsWith("mysql://");
+    if (isUri) {
+        const url = new URL(source);
+        const defaultPort = source.startsWith("mysql://") ? 3306 : 5432;
+        return {
+            host: url.hostname,
+            port: url.port ? Number(url.port) : defaultPort,
+            database: decodeURIComponent(url.pathname.replace(/^\//, "")),
+            username: decodeURIComponent(url.username),
+            password: decodeURIComponent(url.password),
+            sslMode: url.searchParams.get("sslmode") ?? "prefer",
+        };
+    }
+    // Shorthand: host:port:database:username:password
+    const parts = source.split(":");
+    return {
+        host: parts[0] ?? "localhost",
+        port: Number(parts[1]) || 5432,
+        database: parts[2] ?? "",
+        username: parts[3] ?? "",
+        password: parts.slice(4).join(":"),
+        sslMode: "prefer",
+    };
+}
+function parseMappings(context) {
+    const maps = stringFlag(context.parsed, "map");
+    if (!maps) {
+        return [];
+    }
+    return maps.split(",").map((m) => {
+        const parts = m.split(":");
+        return [parts[0] ?? "", parts[1] ?? parts[0] ?? ""];
+    });
+}
+function buildColumnMapping(pairs) {
+    if (pairs.length === 0) {
+        return undefined;
+    }
+    return Object.fromEntries(pairs);
+}
+async function callConnectorSchema(url, type, auth, query, headers) {
+    const res = await fetch(`${url}/v1/connectors/${type}/schema`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...headers },
+        body: JSON.stringify({ auth, query }),
+    });
+    if (!res.ok) {
+        const err = await res.json().catch(() => null);
+        throw new Error(err?.error?.detail ?? `Schema discovery failed (HTTP ${res.status})`);
+    }
+    const json = await res.json();
+    return json.data;
+}
+async function callConnectorPull(url, type, auth, opts, headers) {
+    const res = await fetch(`${url}/v1/connectors/${type}/pull`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...headers },
+        body: JSON.stringify({
+            auth,
+            collection: opts.collection,
+            query: opts.query,
+            batchSize: opts.batchSize,
+            columnMapping: opts.columnMapping,
+        }),
+    });
+    if (!res.ok) {
+        const err = await res.json().catch(() => null);
+        throw new Error(err?.error?.detail ?? `Import failed (HTTP ${res.status})`);
+    }
+    const json = await res.json();
+    return json.data;
+}
+async function runImportDb(context, source, explicitType) {
+    const sidecarUrl = resolveSidecarUrl(context);
+    const headers = authHeaders(context);
+    const connectorType = detectConnectorType(source, explicitType);
+    const auth = parseConnectionString(source);
+    const collection = requiredFlag(context.parsed, "collection");
+    const batchSize = Number(stringFlag(context.parsed, "batch-size") ?? "1000");
+    const columnMapping = buildColumnMapping(parseMappings(context));
+    // Verify sidecar is reachable
+    try {
+        const healthRes = await fetch(`${sidecarUrl}/v1/health`, { headers });
+        if (!healthRes.ok) {
+            throw new Error(`Sidecar returned HTTP ${healthRes.status}`);
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Cannot reach sidecar at ${sidecarUrl}: ${message}. ` +
+            `Is thingd running? Try 'thingd mcp' first.`);
+    }
+    // --list-tables: show available tables
+    if (hasFlag(context.parsed, "list-tables")) {
+        const tables = await callConnectorSchema(sidecarUrl, connectorType, auth, "", headers);
+        writeJson(context.stdout, { tables }, context.pretty);
+        return;
+    }
+    // Resolve query from --tables or --query
+    const tablesFlag = stringFlag(context.parsed, "tables");
+    const queryFlag = stringFlag(context.parsed, "query");
+    if (!queryFlag && !tablesFlag) {
+        throw new Error("Must specify --tables (comma-separated) or --query for DB import.");
+    }
+    const queries = tablesFlag
+        ? tablesFlag.split(",").map((t) => `SELECT * FROM ${t.trim()}`)
+        : [queryFlag];
+    // --dry-run: show schema without importing
+    if (hasFlag(context.parsed, "dry-run")) {
+        const schemas = [];
+        for (const q of queries) {
+            const schema = await callConnectorSchema(sidecarUrl, connectorType, auth, q, headers);
+            schemas.push(schema);
+        }
+        writeJson(context.stdout, { dryRun: true, schemas }, context.pretty);
+        return;
+    }
+    // Execute imports for each query/table
+    let totalImported = 0;
+    for (const q of queries) {
+        const result = await callConnectorPull(sidecarUrl, connectorType, auth, { collection, query: q, batchSize, columnMapping }, headers);
+        totalImported += result.imported;
+    }
+    writeJson(context.stdout, { success: true, imported: totalImported, collection }, context.pretty);
+}
+export async function runSnapshot(context) {
+    const subCommand = context.parsed.tokens[1];
+    if (subCommand === "create") {
+        const outPath = requiredFlag(context.parsed, "out");
+        await withDb(context, async (db) => {
+            const collectionsMap = {};
+            const cols = await db.listCollections();
+            for (const col of cols) {
+                collectionsMap[col] = await db.listObjects(col);
+            }
+            const eventsList = await db.events.list();
+            const queuesMap = {};
+            const queues = await db.listQueues();
+            for (const q of queues) {
+                const queue = db.queue(q);
+                const [active, dead] = await Promise.all([queue.list(), queue.dead()]);
+                queuesMap[q] = { active, dead };
+            }
+            const snapshot = {
+                version: "1.0.0",
+                timestamp: new Date().toISOString(),
+                collections: collectionsMap,
+                events: eventsList,
+                queues: queuesMap,
+            };
+            writeFileSync(resolve(outPath), JSON.stringify(snapshot, null, 2), "utf8");
+            writeJson(context.stdout, { success: true, out: outPath }, context.pretty);
+        });
+    }
+    else if (subCommand === "restore") {
+        const inPath = requiredFlag(context.parsed, "in");
+        const resolvedPath = resolve(inPath);
+        if (!existsSync(resolvedPath)) {
+            throw new Error(`Snapshot file not found: ${inPath}`);
+        }
+        const snapshot = JSON.parse(readFileSync(resolvedPath, "utf8"));
+        if (snapshot.version !== "1.0.0") {
+            throw new Error(`Unsupported snapshot version: ${snapshot.version}`);
+        }
+        context.stderr.write("Restoring snapshot... (consider 'thingd backup --out pre-restore.db' first)\n");
+        await withDb(context, async (db) => {
+            try {
+                // 1. Restore Collections (clear existing first for true restore)
+                if (snapshot.collections) {
+                    for (const [colName, objects] of Object.entries(snapshot.collections)) {
+                        const currentObjs = await db.listObjects(colName);
+                        for (const obj of currentObjs) {
+                            await db.delete(colName, obj.id);
+                        }
+                        for (const obj of objects) {
+                            const cleanObj = { ...obj };
+                            delete cleanObj.collection;
+                            delete cleanObj.createdAt;
+                            delete cleanObj.updatedAt;
+                            delete cleanObj.version;
+                            await db.put(colName, cleanObj);
+                        }
+                    }
+                }
+                // 2. Restore Events
+                if (snapshot.events) {
+                    for (const ev of snapshot.events) {
+                        const cleanEv = { ...ev };
+                        delete cleanEv.id;
+                        delete cleanEv.createdAt;
+                        delete cleanEv.stream;
+                        await db.events.append(ev.stream, cleanEv);
+                    }
+                }
+                // 3. Restore Queues
+                if (snapshot.queues) {
+                    for (const [qName, jobsData] of Object.entries(snapshot.queues)) {
+                        const queue = db.queue(qName);
+                        const { active, dead } = jobsData;
+                        for (const job of active) {
+                            await queue.push(job.payload, {
+                                idempotencyKey: job.id,
+                                maxAttempts: job.maxAttempts,
+                            });
+                        }
+                        for (const job of dead) {
+                            await queue.push(job.payload, {
+                                idempotencyKey: job.id,
+                                maxAttempts: job.maxAttempts,
+                            });
+                        }
+                    }
+                }
+                writeJson(context.stdout, { success: true, in: inPath }, context.pretty);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                // Restore failed — recommend using backup for atomic recovery
+                context.stderr.write(`Restore failed: ${message}. Data may be partially restored.\n` +
+                    `For atomic restore, use 'thingd backup --out backup.db' before making changes\n` +
+                    `and copy the backup file to restore.\n`);
+                throw err;
+            }
+        });
+    }
+    else {
+        throw new Error(`Unknown snapshot command: ${subCommand}. Expected 'create' or 'restore'.`);
+    }
+}
+export async function runBackup(context) {
+    const inPath = stringFlag(context.parsed, "in");
+    const outPath = stringFlag(context.parsed, "out");
+    if (inPath) {
+        // Restore from backup file
+        const resolvedIn = resolve(inPath);
+        if (!existsSync(resolvedIn)) {
+            throw new Error(`Backup file not found: ${inPath}`);
+        }
+        await withDb(context, async (db) => {
+            if (db.path === ":memory:") {
+                throw new Error("Cannot restore an in-memory database. Use a file-based native database.");
+            }
+            // Close current DB, copy backup over, reopen happens after callback
+            await db.close();
+            const { copyFileSync } = await import("node:fs");
+            copyFileSync(resolvedIn, db.path);
+            context.stderr.write(`Restored from: ${resolvedIn}\n`);
+        });
+        return;
+    }
+    if (!outPath) {
+        throw new Error("Expected --out <path> (backup) or --in <path> (restore).");
+    }
+    await withDb(context, async (db) => {
+        if (db.path === ":memory:") {
+            throw new Error("Cannot backup an in-memory database. Use a file-based native database.");
+        }
+        db.backupTo(outPath);
+        const { statSync } = await import("node:fs");
+        const stats = statSync(outPath);
+        const sizeMb = (stats.size / (1024 * 1024)).toFixed(2);
+        context.stderr.write(`Backup created: ${outPath} (${sizeMb} MB)\n`);
+    });
+}

package/dist/doctor.d.ts

@@ -0,0 +1,3 @@
+import { type CliContext } from "./index.js";
+export declare function runDoctor(context: CliContext): Promise<void>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,YAAY,CAAC;AAEhE,wBAAsB,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAwIlE"}

package/dist/doctor.js

@@ -0,0 +1,108 @@
+import { NativeThingStore } from "@thingd/sdk";
+import pc from "picocolors";
+import { resolveConnection } from "./index.js";
+export async function runDoctor(context) {
+    context.stderr.write(`\n${pc.bold("thingd doctor")}\n`);
+    context.stderr.write(`${pc.dim("Running system diagnostics and connectivity tests...")}\n\n`);
+    let healthy = true;
+    // 1. Check Node version
+    const nodeVersion = process.version;
+    const majorVersion = Number.parseInt(nodeVersion.slice(1).split(".")[0] ?? "0", 10);
+    if (majorVersion >= 20) {
+        context.stderr.write(`  ${pc.green("✓")} Node version:   ${pc.cyan(nodeVersion)} (OK)\n`);
+    }
+    else {
+        healthy = false;
+        context.stderr.write(`  ${pc.red("×")} Node version:   ${pc.yellow(nodeVersion)} (Requires >= v20.x)\n`);
+    }
+    // 2. Resolve connection options
+    const connection = resolveConnection(context);
+    // 3. Native Driver Checks
+    if (connection.driver === "native") {
+        try {
+            const hasNative = await NativeThingStore.isAvailable();
+            if (hasNative) {
+                const loadedPath = (await NativeThingStore.getLoadedPath()) ?? "unknown";
+                const buildType = loadedPath.includes("prebuilds")
+                    ? pc.cyan("Loaded prebuilt driver")
+                    : pc.cyan("Loaded local development build");
+                context.stderr.write(`  ${pc.green("✓")} Native Addon:    ${buildType} (${pc.dim(loadedPath)})\n`);
+            }
+            else {
+                healthy = false;
+                context.stderr.write(`  ${pc.red("×")} Native Addon:    ${pc.yellow('Not found. Run "pnpm --filter thingd-native build" or configure THINGD_NATIVE_PATH.')}\n`);
+            }
+        }
+        catch (error) {
+            healthy = false;
+            context.stderr.write(`  ${pc.red("×")} Native Addon:    ${pc.yellow(`Failed to load native addon: ${error instanceof Error ? error.message : String(error)}`)}\n`);
+        }
+    }
+    else {
+        context.stderr.write(`  ${pc.dim("○")} Native Addon:    Skipped (Using driver: "${connection.driver ?? "memory"}")\n`);
+    }
+    // 4. Remote Sidecar Reachability & Auth Checks
+    if (connection.cloud) {
+        const rawUrl = connection.path;
+        const isLocal = rawUrl.includes("localhost") || rawUrl.includes("127.0.0.1");
+        if (!connection.authToken && !isLocal) {
+            context.stderr.write(`  ${pc.yellow("⚠")} Auth Token:     ${pc.yellow("Missing THINGD_AUTH_TOKEN for remote server (might fail)")}\n`);
+        }
+        else if (connection.authToken) {
+            context.stderr.write(`  ${pc.green("✓")} Auth Token:     ${pc.cyan("Configured")}\n`);
+        }
+        else {
+            context.stderr.write(`  ${pc.green("✓")} Auth Token:     ${pc.dim("Not required for local sidecar")}\n`);
+        }
+        try {
+            const targetUrl = new URL(rawUrl.startsWith("thingd://") ? `http://${rawUrl.slice("thingd://".length)}` : rawUrl);
+            if (targetUrl.pathname === "/mcp" || targetUrl.pathname === "") {
+                targetUrl.pathname = "/healthz";
+            }
+            else {
+                targetUrl.pathname = `${targetUrl.pathname.replace(/\/mcp$/, "")}/healthz`;
+            }
+            context.stderr.write(`  ${pc.dim("○")} Connectivity:   Checking reachability to ${pc.cyan(targetUrl.toString())}...\n`);
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 3000);
+            const headers = {};
+            if (connection.authToken) {
+                headers.Authorization = `Bearer ${connection.authToken}`;
+            }
+            try {
+                const response = await fetch(targetUrl, {
+                    signal: controller.signal,
+                    headers,
+                });
+                clearTimeout(timeoutId);
+                if (response.ok) {
+                    context.stderr.write(`  ${pc.green("✓")} Connectivity:   ${pc.cyan("Connected successfully!")} (${pc.dim(`HTTP ${response.status}`)})\n`);
+                }
+                else {
+                    healthy = false;
+                    context.stderr.write(`  ${pc.red("×")} Connectivity:   ${pc.yellow(`Server responded with non-2xx status`)} (${pc.dim(`HTTP ${response.status}`)})\n`);
+                }
+            }
+            catch (fetchError) {
+                clearTimeout(timeoutId);
+                healthy = false;
+                context.stderr.write(`  ${pc.red("×")} Connectivity:   ${pc.yellow(`Failed to connect. Connection refused or timed out.`)} (${pc.dim(fetchError instanceof Error ? fetchError.message : String(fetchError))})\n`);
+            }
+        }
+        catch (urlError) {
+            healthy = false;
+            context.stderr.write(`  ${pc.red("×")} Connectivity:   ${pc.yellow(`Invalid URL structure: ${urlError instanceof Error ? urlError.message : String(urlError)}`)}\n`);
+        }
+    }
+    else {
+        context.stderr.write(`  ${pc.green("✓")} Connectivity:   ${pc.cyan("Local persistent store")} (${pc.dim(connection.path)})\n`);
+    }
+    // Final Summary Report
+    context.stderr.write("\n");
+    if (healthy) {
+        context.stderr.write(`  ${pc.bold(pc.green("Diagnosis: Everything looks healthy!"))}\n\n`);
+    }
+    else {
+        context.stderr.write(`  ${pc.bold(pc.yellow("Diagnosis: Some items require attention (see errors above)."))}\n\n`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { ThingD, type ThingDDriver } from "@thingd/sdk";
+type CliEnv = Record<string, string | undefined>;
+type WritableLike = {
+    write(chunk: string): void;
+};
+type ReadableLike = NodeJS.ReadableStream;
+export type RunCliOptions = {
+    env?: CliEnv;
+    stdout?: WritableLike;
+    stderr?: WritableLike;
+    stdin?: ReadableLike;
+};
+export type ParsedArgs = {
+    tokens: string[];
+    flags: Map<string, string[]>;
+    booleans: Set<string>;
+};
+export type CliContext = {
+    parsed: ParsedArgs;
+    env: CliEnv;
+    stdout: WritableLike;
+    stderr: WritableLike;
+    stdin: ReadableLike;
+    pretty: boolean;
+};
+export type ConnectionOptions = {
+    path: string;
+    driver?: ThingDDriver;
+    authToken?: string;
+    cloud: boolean;
+    /** Cloud instance slug for multi-instance routing. */
+    instanceSlug?: string;
+    encryptionKey?: string;
+};
+export declare function runCli(args?: string[], options?: RunCliOptions): Promise<number>;
+export declare function withDb(context: CliContext, callback: (db: ThingD) => Promise<void>): Promise<void>;
+export declare function resolveConnection(context: CliContext): ConnectionOptions;
+export declare function hasFlag(parsed: ParsedArgs, name: string): boolean;
+export declare function stringFlag(parsed: ParsedArgs, name: string): string | undefined;
+export declare function stringFlags(parsed: ParsedArgs, name: string): string[] | undefined;
+export declare function requiredFlag(parsed: ParsedArgs, name: string): string;
+export declare function optionalToken(parsed: ParsedArgs, index: number): string | undefined;
+export declare function requiredToken(parsed: ParsedArgs, index: number, name: string): string;
+export declare function writeJson(target: WritableLike, data: unknown, pretty: boolean): void;
+export declare function writeText(target: WritableLike, text: string): void;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAeA,OAAO,EAYL,MAAM,EACN,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AASrB,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEjD,KAAK,YAAY,GAAG;IAClB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAEF,KAAK,YAAY,GAAG,MAAM,CAAC,cAAc,CAAC;AAE1C,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7B,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,UAAU,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAsCF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAqGF,wBAAsB,MAAM,CAC1B,IAAI,WAAwB,EAC5B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,MAAM,CAAC,CA8EjB;AAiuCD,wBAAsB,MAAM,CAC1B,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC,CAgBf;AA4BD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,iBAAiB,CAuDxE;AAiDD,wBAAgB,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE/E;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAGlF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMrE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEnF;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMrF;AAyFD,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAEpF;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAElE"}