satoridb 1.2.6 → 1.2.7

package/cli.js

@@ -1,12 +1,7 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * Satori Interactive CLI (Improved)
- * - Command registry (easy to extend)
- * - Robust arg parsing (quotes, escapes)
- * - Fixed bugs (lecture args check, set_mindspace double call)
- * - Better UX (history, tab completion, prompt context)
- * - Centralized error handling
+ * Satori Interactive CLI
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -18,11 +13,28 @@ const os_1 = __importDefault(require("os"));
 const fs_1 = __importDefault(require("fs"));
 const child_process_1 = require("child_process");
 const readline_1 = __importDefault(require("readline"));
-// -------------------------------
-// Globals / State
-// -------------------------------
-const binName = os_1.default.platform() === "win32" ? "satori.exe" : "satori";
-const binPath = path_1.default.join(os_1.default.homedir(), ".satori", "bin", binName);
+// ── ANSI helpers ───────────────────────────────────────────────────────────────
+const c = {
+    reset: '\x1b[0m',
+    dim: '\x1b[2m',
+    bold: '\x1b[1m',
+    cyan: '\x1b[96m',
+    green: '\x1b[92m',
+    yellow: '\x1b[93m',
+    red: '\x1b[91m',
+    blue: '\x1b[94m',
+    magenta: '\x1b[95m',
+};
+// ── State ──────────────────────────────────────────────────────────────────────
+let VERSION = '1.2.6';
+try {
+    VERSION = require('./package.json').version;
+}
+catch { }
+const binName = os_1.default.platform() === 'win32' ? 'satori.exe' : 'satori';
+const binPath = path_1.default.join(os_1.default.homedir(), '.satori', 'bin', binName);
+const historyDir = path_1.default.join(os_1.default.homedir(), '.satori');
+const historyFile = path_1.default.join(historyDir, '.cli_history');
 let satori = null;
 let session = {
     host: null,
@@ -30,21 +42,75 @@ let session = {
     password: null,
     mindspace: null,
 };
-// -------------------------------
-// Utils
-// -------------------------------
+// ── Print helpers ──────────────────────────────────────────────────────────────
+const ok = (msg) => console.log(`  ${c.green}✓${c.reset}  ${msg}`);
+const fail = (msg) => console.error(`  ${c.red}✗${c.reset}  ${msg}`);
+const info = (msg) => console.log(`  ${c.dim}${msg}${c.reset}`);
+function colorJson(obj) {
+    if (obj === null || obj === undefined)
+        return `${c.dim}null${c.reset}`;
+    if (typeof obj === 'string')
+        return obj;
+    if (typeof obj === 'number')
+        return `${c.yellow}${obj}${c.reset}`;
+    if (typeof obj === 'boolean')
+        return `${c.magenta}${obj}${c.reset}`;
+    return JSON.stringify(obj, null, 2)
+        .replace(/"([^"]+)":/g, `${c.cyan}"$1"${c.reset}:`)
+        .replace(/: "([^"]*)"/g, `: ${c.green}"$1"${c.reset}`)
+        .replace(/: (-?\d+(?:\.\d+)?)/g, `: ${c.yellow}$1${c.reset}`)
+        .replace(/: (true|false)/g, `: ${c.magenta}$1${c.reset}`)
+        .replace(/: null/g, `: ${c.dim}null${c.reset}`);
+}
+function print(obj) {
+    if (obj === null || obj === undefined)
+        return;
+    const s = colorJson(obj);
+    console.log('\n' + s.split('\n').map(l => `  ${l}`).join('\n') + '\n');
+}
+function spinner(text) {
+    if (!process.stdout.isTTY)
+        return () => { };
+    const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    let i = 0;
+    const id = setInterval(() => {
+        process.stdout.write(`\r  ${c.dim}${frames[i++ % frames.length]}${c.reset}  ${c.dim}${text}${c.reset}  `);
+    }, 80);
+    return () => {
+        clearInterval(id);
+        process.stdout.write('\r' + ' '.repeat(text.length + 10) + '\r');
+    };
+}
+// ── Banner ─────────────────────────────────────────────────────────────────────
+function showBanner() {
+    const logo = [
+        ` ___  _ _  ____  ___  ____  ____`,
+        `/ __|| | |/ _  |/   ||  _ \\|_  _|`,
+        `\\__ \\| | |\\__  | / \\ ||   /  | | `,
+        `|___/|___|/____||_| |_||_|\\_\\ |_| `,
+    ];
+    console.log();
+    logo.forEach(l => console.log(`  ${c.cyan}${c.bold}${l}${c.reset}`));
+    console.log();
+    console.log(`  ${c.dim}AI-Native Distributed Object Database  ·  v${VERSION}${c.reset}`);
+    console.log(`  ${c.dim}Type ${c.reset}${c.cyan}help${c.reset}` +
+        `${c.dim} for commands  ·  ${c.reset}${c.cyan}connect <host>${c.reset}${c.dim} to begin${c.reset}`);
+    console.log();
+}
+// ── Utilities ──────────────────────────────────────────────────────────────────
 function assertInstalled() {
     if (!fs_1.default.existsSync(binPath)) {
-        console.error("❌ Satori binary not found. Reinstall the package.");
+        fail('Satori binary not found. Run: npm install -g satoridb');
         process.exit(1);
     }
 }
 function runBinary(args) {
     assertInstalled();
-    const r = (0, child_process_1.spawnSync)(binPath, args, { stdio: "inherit" });
+    const r = (0, child_process_1.spawnSync)(binPath, args, { stdio: 'inherit' });
     if (r.error)
         throw r.error;
 }
+/** Tokenises a shell-style line respecting single/double quotes and backslash escapes. */
 function parseArgs(line) {
     const re = /"([^"\\]*(?:\\.[^"\\]*)*)"|'([^'\\]*(?:\\.[^'\\]*)*)'|(\S+)/g;
     const out = [];
@@ -53,17 +119,18 @@ function parseArgs(line) {
         out.push(m[1] ?? m[2] ?? m[3]);
     return out.map(v => v.replace(/\\"/g, '"').replace(/\\'/g, "'"));
 }
+/** Auto-casts string tokens to bool / number / JSON when unambiguous. */
 function parseData(v) {
-    if (typeof v !== "string")
+    if (typeof v !== 'string')
         return v;
     const t = v.trim();
-    if (t === "true")
+    if (t === 'true')
         return true;
-    if (t === "false")
+    if (t === 'false')
         return false;
-    if (!isNaN(Number(t)) && t !== "")
+    if (t !== '' && !isNaN(Number(t)))
         return Number(t);
-    if (t.startsWith("{") || t.startsWith("[")) {
+    if (t.startsWith('{') || t.startsWith('[')) {
         try {
             return JSON.parse(t);
         }
@@ -73,8 +140,17 @@ function parseData(v) {
 }
 function requireConn() {
     if (!satori)
-        throw new Error("No active connection. Use: connect <host> [user] [password]");
+        throw new Error('Not connected — use: connect <host>');
 }
+function requireMindspace() {
+    requireConn();
+    if (!session.mindspace) {
+        throw new Error('No mindspace selected — use: mindspace select <id>');
+    }
+}
+// Returns `any` so the extra auth fields don't clash with typed SDK payloads.
+// The satori-node already injects username/password via its constructor, but
+// some server builds also accept them in the command body — keep for compat.
 function withCreds(p = {}) {
     if (session.user)
         p.user = session.user;
@@ -82,205 +158,554 @@ function withCreds(p = {}) {
         p.password = session.password;
     return p;
 }
+/**
+ * Plain-text prompt — ANSI codes inside the prompt string break readline's
+ * cursor-position tracking, so keep it clean.
+ */
 function promptLabel() {
-    return `satori${session.mindspace ? `:${session.mindspace}` : ""}> `;
+    const host = session.host
+        ? session.host.replace(/^wss?:\/\//, '').replace(/:\d+$/, '')
+        : null;
+    const ms = session.mindspace ? `[${session.mindspace}]` : '';
+    return host ? `${host}${ms} › ` : 'satori › ';
+}
+// ── History ────────────────────────────────────────────────────────────────────
+function loadHistory() {
+    try {
+        if (fs_1.default.existsSync(historyFile)) {
+            return fs_1.default.readFileSync(historyFile, 'utf8')
+                .split('\n').filter(Boolean).reverse().slice(0, 500);
+        }
+    }
+    catch { }
+    return [];
+}
+function saveHistory(history) {
+    try {
+        fs_1.default.mkdirSync(historyDir, { recursive: true });
+        fs_1.default.writeFileSync(historyFile, [...history].reverse().join('\n') + '\n');
+    }
+    catch { }
 }
-// -------------------------------
-// Commands Registry
-// -------------------------------
 const commands = {
-    help: {
-        desc: "Show help",
-        run() { showHelp(); }
-    },
-    exit: { run() { process.exit(0); } },
-    quit: { run() { process.exit(0); } },
-    clear: { run() { console.clear(); } },
+    // ── Connection ───────────────────────────────────────────────────────────────
     connect: {
-        desc: "connect <host> [user] [password]",
-        async run([host, user = null, password = null]) {
+        group: 'Connection', noConn: true,
+        desc: 'connect <host> [user] [password]',
+        async run([host, user, password]) {
             if (!host)
-                throw new Error("Usage: connect <host> [user] [password]");
-            console.log(`🔗 Connecting to ${host}...`);
-            if (user != null && password != null) {
-                satori = new satori_node_1.Satori({ host, username: user, password });
+                throw new Error('Usage: connect <host> [user] [password]');
+            const stop = spinner(`Connecting to ${host}`);
+            try {
+                satori = (user && password)
+                    ? new satori_node_1.Satori({ host, username: user, password })
+                    : new satori_node_1.Satori({ host, username: '', password: '' });
+                await satori.connect();
+                stop();
+                Object.assign(session, { host, user: user ?? null, password: password ?? null });
+                ok(`Connected  ${c.dim}${host}${c.reset}`);
             }
-            else {
-                satori = new satori_node_1.Satori({ host: host, username: "", password: "" });
+            catch (e) {
+                stop();
+                satori = null;
+                throw new Error(`Connection failed: ${e.message ?? e}`);
             }
-            await satori.connect();
-            Object.assign(session, { host, user, password });
-            console.log("✅ Connected");
         }
     },
-    mindspace: {
-        desc: "mindspace select <id>",
-        run([sub, id]) {
-            if (sub !== "select" || !id)
-                throw new Error("Usage: mindspace select <id>");
-            session.mindspace = id;
-            console.log(`🧠 Mindspace selected: ${id}`);
+    disconnect: {
+        group: 'Connection',
+        desc: 'Disconnect from server',
+        run() {
+            requireConn();
+            const host = session.host;
+            satori = null;
+            Object.assign(session, { host: null, user: null, password: null, mindspace: null });
+            ok(`Disconnected from ${host}`);
         }
     },
+    status: {
+        group: 'Connection', noConn: true,
+        desc: 'Show connection info',
+        run() {
+            if (!satori) {
+                info('Not connected');
+                return;
+            }
+            console.log();
+            console.log(`  ${c.dim}Host      ${c.reset}${c.cyan}${session.host}${c.reset}`);
+            if (session.user)
+                console.log(`  ${c.dim}User      ${c.reset}${session.user}`);
+            if (session.mindspace)
+                console.log(`  ${c.dim}Mindspace ${c.reset}${c.green}${session.mindspace}${c.reset}`);
+            console.log(`  ${c.dim}Status    ${c.reset}${c.green}● Connected${c.reset}`);
+            console.log();
+        }
+    },
+    // ── Data ─────────────────────────────────────────────────────────────────────
     set: {
-        desc: "set <key> <data>",
+        group: 'Data',
+        desc: 'set <key> <data>',
         async run([key, ...rest]) {
             requireConn();
             if (!key || !rest.length)
-                throw new Error("Usage: set <key> <data>");
-            const data = parseData(rest.join(" "));
-            await satori.set(withCreds({ key, data }));
-            console.log(`✅ Saved: ${key}`);
+                throw new Error('Usage: set <key> <data>');
+            const stop = spinner('Writing...');
+            await satori.set(withCreds({ key, data: parseData(rest.join(' ')) }));
+            stop();
+            ok(`Saved  ${c.cyan}${key}${c.reset}`);
         }
     },
     get: {
-        desc: "get <key>",
+        group: 'Data',
+        desc: 'get [key]',
         async run([key]) {
             requireConn();
+            const stop = spinner('Fetching...');
             const r = await satori.get(withCreds(key ? { key } : {}));
-            console.log(JSON.stringify(r, null, 2));
+            stop();
+            print(r);
         }
     },
     put: {
-        desc: "put <key> <field> <value>",
-        async run([key, field, value]) {
+        group: 'Data',
+        desc: 'put <key> <field> <value>',
+        async run([key, field, ...rest]) {
             requireConn();
-            if (!key || !field)
-                throw new Error("Usage: put <key> <field> <value>");
-            await satori.put(withCreds({ key, replace_field: field, replace_value: parseData(value) }));
-            console.log("✅ Updated");
+            if (!key || !field || !rest.length)
+                throw new Error('Usage: put <key> <field> <value>');
+            const stop = spinner('Updating...');
+            await satori.put(withCreds({
+                key,
+                replace_field: field,
+                replace_value: parseData(rest.join(' ')),
+            }));
+            stop();
+            ok(`Updated  ${c.cyan}${key}${c.reset}.${field}`);
         }
     },
     delete: {
-        desc: "delete <key>",
+        group: 'Data',
+        desc: 'delete <key>',
         async run([key]) {
             requireConn();
             if (!key)
-                throw new Error("Usage: delete <key>");
+                throw new Error('Usage: delete <key>');
+            const stop = spinner('Deleting...');
             await satori.delete(withCreds({ key }));
-            console.log(`🗑️ Deleted: ${key}`);
+            stop();
+            ok(`Deleted  ${c.cyan}${key}${c.reset}`);
+        }
+    },
+    push: {
+        group: 'Data',
+        desc: 'push <key> <array> <value>  – append to array field',
+        async run([key, array, ...rest]) {
+            requireConn();
+            if (!key || !array || !rest.length)
+                throw new Error('Usage: push <key> <array> <value>');
+            const stop = spinner('Pushing...');
+            const r = await satori.push(withCreds({ key, array, value: parseData(rest.join(' ')) }));
+            stop();
+            print(r);
+        }
+    },
+    pop: {
+        group: 'Data',
+        desc: 'pop <key> <array>  – remove last array element',
+        async run([key, array]) {
+            requireConn();
+            if (!key || !array)
+                throw new Error('Usage: pop <key> <array>');
+            const stop = spinner('Popping...');
+            const r = await satori.pop(withCreds({ key, array }));
+            stop();
+            print(r);
+        }
+    },
+    splice: {
+        group: 'Data',
+        desc: 'splice <key> <array>  – remove first array element',
+        async run([key, array]) {
+            requireConn();
+            if (!key || !array)
+                throw new Error('Usage: splice <key> <array>');
+            const stop = spinner('Splicing...');
+            const r = await satori.splice(withCreds({ key, array }));
+            stop();
+            print(r);
+        }
+    },
+    remove: {
+        group: 'Data',
+        desc: 'remove <key> <array> <value>  – remove specific value from array',
+        async run([key, array, ...rest]) {
+            requireConn();
+            if (!key || !array || !rest.length)
+                throw new Error('Usage: remove <key> <array> <value>');
+            const stop = spinner('Removing...');
+            const r = await satori.remove(withCreds({ key, array, value: parseData(rest.join(' ')) }));
+            stop();
+            print(r);
+        }
+    },
+    // ── Graph ─────────────────────────────────────────────────────────────────────
+    'set-vertex': {
+        group: 'Graph',
+        desc: 'set-vertex <from> <to> [weight]',
+        async run([from, to, weight]) {
+            requireConn();
+            if (!from || !to)
+                throw new Error('Usage: set-vertex <from> <to> [weight]');
+            const stop = spinner('Creating edge...');
+            await satori.setVertex(withCreds({
+                key: from, vertex: to,
+                weight: weight !== undefined ? Number(weight) : 1,
+            }));
+            stop();
+            ok(`Edge  ${c.cyan}${from}${c.reset} → ${c.cyan}${to}${c.reset}`);
+        }
+    },
+    'get-vertex': {
+        group: 'Graph',
+        desc: 'get-vertex <key>',
+        async run([key]) {
+            requireConn();
+            if (!key)
+                throw new Error('Usage: get-vertex <key>');
+            const stop = spinner('Fetching edges...');
+            const r = await satori.getVertex(withCreds({ key }));
+            stop();
+            print(r);
+        }
+    },
+    'delete-vertex': {
+        group: 'Graph',
+        desc: 'delete-vertex <from> <to>',
+        async run([from, to]) {
+            requireConn();
+            if (!from || !to)
+                throw new Error('Usage: delete-vertex <from> <to>');
+            const stop = spinner('Removing edge...');
+            await satori.deleteVertex(withCreds({ key: from, vertex: to }));
+            stop();
+            ok(`Edge removed  ${c.cyan}${from}${c.reset} → ${c.cyan}${to}${c.reset}`);
         }
     },
+    dfs: {
+        group: 'Graph',
+        desc: 'dfs <node>  – depth-first traversal',
+        async run([node]) {
+            requireConn();
+            if (!node)
+                throw new Error('Usage: dfs <node>');
+            const stop = spinner('Traversing (DFS)...');
+            const r = await satori.dfs(withCreds({ node }));
+            stop();
+            print(r);
+        }
+    },
+    bfs: {
+        group: 'Graph',
+        desc: 'bfs <node>  – breadth-first traversal',
+        async run([node]) {
+            requireConn();
+            if (!node)
+                throw new Error('Usage: bfs <node>');
+            const stop = spinner('Traversing (BFS)...');
+            const r = await satori.graphBfs(withCreds({ node }));
+            stop();
+            print(r);
+        }
+    },
+    'shortest-path': {
+        group: 'Graph',
+        desc: 'shortest-path <node> <target>',
+        async run([node, target]) {
+            requireConn();
+            if (!node || !target)
+                throw new Error('Usage: shortest-path <node> <target>');
+            const stop = spinner('Computing...');
+            const r = await satori.graphShortestPath(withCreds({ node, target }));
+            stop();
+            print(r);
+        }
+    },
+    // ── AI ───────────────────────────────────────────────────────────────────────
     ask: {
-        desc: "ask \"<question>\"",
-        async run([q, backend = null]) {
+        group: 'AI',
+        desc: 'ask "<question>" [backend]',
+        async run([q, backend]) {
             requireConn();
             if (!q)
-                throw new Error("Usage: ask \"<question>\"");
-            const r = await satori.ask(withCreds({ question: q, backend }));
-            console.log(JSON.stringify(r, null, 2));
+                throw new Error('Usage: ask "<question>" [backend]');
+            const stop = spinner('Thinking...');
+            const r = await satori.ask(withCreds({
+                question: q,
+                ...(backend ? { backend } : {}),
+            }));
+            stop();
+            const answer = r?.message ?? r?.data ?? r;
+            print(answer);
         }
     },
     query: {
-        desc: "query \"<query>\"",
-        async run([q, backend = null]) {
+        group: 'AI',
+        desc: 'query "<text>" [backend]',
+        async run([q, backend]) {
             requireConn();
             if (!q)
-                throw new Error("Usage: query \"<query>\"");
-            const r = await satori.query(withCreds({ query: q, backend }));
-            console.log(JSON.stringify(r, null, 2));
+                throw new Error('Usage: query "<text>" [backend]');
+            const stop = spinner('Searching...');
+            const r = await satori.query(withCreds({
+                query: q,
+                ...(backend ? { backend } : {}),
+            }));
+            stop();
+            print(r);
+        }
+    },
+    // ── Mindspace ─────────────────────────────────────────────────────────────────
+    mindspace: {
+        group: 'Mindspace', noConn: true,
+        desc: 'mindspace select <id>  – set active mindspace (local only)',
+        run([sub, id]) {
+            if (sub !== 'select' || !id)
+                throw new Error('Usage: mindspace select <id>');
+            session.mindspace = id;
+            ok(`Active mindspace: ${c.green}${id}${c.reset}`);
+        }
+    },
+    'set-mindspace': {
+        group: 'Mindspace',
+        desc: 'set-mindspace [id]  – create / activate mindspace on server',
+        async run([id]) {
+            requireConn();
+            const mid = id ?? session.mindspace;
+            if (!mid)
+                throw new Error('Provide an ID or select one first: mindspace select <id>');
+            const stop = spinner(`Activating ${mid}...`);
+            await satori.setMindspace(withCreds({ mindspace_id: mid, config: '' }));
+            stop();
+            session.mindspace = mid;
+            ok(`Mindspace active: ${c.green}${mid}${c.reset}`);
+        }
+    },
+    'delete-mindspace': {
+        group: 'Mindspace',
+        desc: 'delete-mindspace <id>',
+        async run([id]) {
+            requireConn();
+            if (!id)
+                throw new Error('Usage: delete-mindspace <id>');
+            const stop = spinner(`Deleting ${id}...`);
+            await satori.deleteMindspace(withCreds({ mindspace_id: id }));
+            stop();
+            if (session.mindspace === id)
+                session.mindspace = null;
+            ok(`Deleted mindspace: ${c.cyan}${id}${c.reset}`);
         }
     },
     chat: {
-        desc: "chat \"<message>\"",
+        group: 'Mindspace',
+        desc: 'chat "<message>"',
         async run([msg]) {
-            requireConn();
-            if (!session.mindspace)
-                throw new Error("Select a mindspace first");
-            const r = await satori.chatMindspace({ minspace_id: session.mindspace, message: msg });
-            console.log(r);
+            requireMindspace();
+            if (!msg)
+                throw new Error('Usage: chat "<message>"');
+            const stop = spinner('Thinking...');
+            const r = await satori.chatMindspace(withCreds({ minspace_id: session.mindspace, message: msg }));
+            stop();
+            print(r);
         }
     },
     lecture: {
-        desc: "lecture \"<corpus>\"",
+        group: 'Mindspace',
+        desc: 'lecture "<corpus>"',
         async run([corpus]) {
+            requireMindspace();
+            if (!corpus)
+                throw new Error('Usage: lecture "<corpus>"');
+            const stop = spinner('Ingesting corpus...');
+            const r = await satori.lectureMindspace(withCreds({ mindspace_id: session.mindspace, corpus }));
+            stop();
+            const msg = r?.message;
+            if (msg)
+                ok(msg);
+            else
+                ok('Corpus ingested');
+        }
+    },
+    // ── Crypto ────────────────────────────────────────────────────────────────────
+    encrypt: {
+        group: 'Crypto',
+        desc: 'encrypt <key> <encryption_key>',
+        async run([key, encryption_key]) {
+            requireConn();
+            if (!key || !encryption_key)
+                throw new Error('Usage: encrypt <key> <encryption_key>');
+            const stop = spinner('Encrypting...');
+            const r = await satori.encrypt(withCreds({ key, encryption_key }));
+            stop();
+            print(r);
+        }
+    },
+    decrypt: {
+        group: 'Crypto',
+        desc: 'decrypt <key> <encryption_key>',
+        async run([key, encryption_key]) {
+            requireConn();
+            if (!key || !encryption_key)
+                throw new Error('Usage: decrypt <key> <encryption_key>');
+            const stop = spinner('Decrypting...');
+            const r = await satori.decrypt(withCreds({ key, encryption_key }));
+            stop();
+            print(r);
+        }
+    },
+    // ── Analytics ─────────────────────────────────────────────────────────────────
+    operations: {
+        group: 'Analytics',
+        desc: 'operations  – recent operation log',
+        async run() {
             requireConn();
-            if (!session.mindspace)
-                throw new Error("Select a mindspace first");
-            const r = await satori.lectureMindspace({ mindspace_id: session.mindspace, corpus });
-            console.log(r.message);
+            const stop = spinner('Fetching...');
+            const r = await satori.getOperations();
+            stop();
+            print(r);
         }
     },
-    set_mindspace: {
-        desc: "set_mindspace [mindspace_id]",
-        async run([mindspace_id = null]) {
+    freq: {
+        group: 'Analytics',
+        desc: 'freq <key>  – access frequency for a key',
+        async run([key]) {
             requireConn();
-            if (!satori)
-                throw new Error("No active connection");
-            let payload = { config: {} };
-            if (mindspace_id)
-                payload.mindspace_id = mindspace_id;
-            else if (session.mindspace)
-                payload.mindspace_id = session.mindspace;
-            const res = await satori.setMindspace(payload);
-            if (payload.mindspace_id)
-                session.mindspace = payload.mindspace_id;
-            console.log(`🧠 Mindspace configured: ${payload.mindspace_id ?? res.data}`);
+            if (!key)
+                throw new Error('Usage: freq <key>');
+            const stop = spinner('Fetching...');
+            const r = await satori.getAccessFrequency(key);
+            stop();
+            print(r);
         }
     },
+    // ── Utility ───────────────────────────────────────────────────────────────────
+    help: {
+        group: 'Utility', noConn: true,
+        desc: 'Show help',
+        run() { showHelp(); }
+    },
+    clear: {
+        group: 'Utility', noConn: true,
+        desc: 'Clear screen',
+        run() { console.clear(); showBanner(); }
+    },
+    exit: {
+        group: 'Utility', noConn: true,
+        desc: 'Exit',
+        run() { process.exit(0); }
+    },
+    quit: {
+        group: 'Utility', noConn: true,
+        desc: 'Exit',
+        run() { process.exit(0); }
+    },
+};
+// Backward-compat aliases (old underscore variants kept for muscle memory)
+const aliases = {
+    set_mindspace: 'set-mindspace',
+    delete_mindspace: 'delete-mindspace',
+    set_vertex: 'set-vertex',
+    get_vertex: 'get-vertex',
+    delete_vertex: 'delete-vertex',
+    shortest_path: 'shortest-path',
 };
-// -------------------------------
-// Help
-// -------------------------------
+for (const [alias, canonical] of Object.entries(aliases)) {
+    commands[alias] = commands[canonical];
+}
+// ── Help ───────────────────────────────────────────────────────────────────────
 function showHelp() {
-    console.log("\n📚 Commands:\n");
-    Object.entries(commands).forEach(([k, v]) => {
-        if ('desc' in v && v.desc)
-            console.log(`  ${k.padEnd(12)} ${v.desc}`);
-    });
-    console.log("");
+    var _a;
+    const hidden = new Set(['quit', ...Object.keys(aliases)]);
+    const groups = {};
+    for (const [name, cmd] of Object.entries(commands)) {
+        if (hidden.has(name))
+            continue;
+        (groups[_a = cmd.group] ?? (groups[_a] = [])).push([name, cmd.desc]);
+    }
+    console.log();
+    for (const [group, entries] of Object.entries(groups)) {
+        console.log(`  ${c.yellow}${group}${c.reset}`);
+        for (const [name, desc] of entries) {
+            const argsPart = desc.startsWith(name) ? desc.slice(name.length).trim() : desc;
+            console.log(`    ${c.cyan}${name.padEnd(20)}${c.reset}` +
+                `${c.dim}${argsPart}${c.reset}`);
+        }
+        console.log();
+    }
 }
-// -------------------------------
-// Interactive Shell
-// -------------------------------
+// ── REPL ───────────────────────────────────────────────────────────────────────
 async function startREPL() {
+    showBanner();
+    // Tab-completion list: canonical names only (no aliases, no quit duplicate)
+    const completionList = Object.keys(commands).filter(k => !aliases[k] && k !== 'quit');
     const rl = readline_1.default.createInterface({
         input: process.stdin,
         output: process.stdout,
         historySize: 500,
         completer(line) {
-            const hits = Object.keys(commands).filter(c => c.startsWith(line));
-            return [hits.length ? hits : Object.keys(commands), line];
-        }
+            const hits = completionList.filter(k => k.startsWith(line));
+            return [hits.length ? hits : completionList, line];
+        },
     });
+    // Restore saved history into readline's internal array
+    const history = loadHistory();
+    if (history.length && rl.history) {
+        rl.history.push(...history);
+    }
     const refreshPrompt = () => rl.setPrompt(promptLabel());
     refreshPrompt();
     rl.prompt();
-    rl.on("line", async (line) => {
-        const parts = parseArgs(line.trim());
-        if (!parts.length)
-            return rl.prompt();
+    rl.on('line', async (raw) => {
+        const line = raw.trim();
+        if (!line) {
+            rl.prompt();
+            return;
+        }
+        const parts = parseArgs(line);
         const [cmd, ...args] = parts;
         const entry = commands[cmd];
         try {
-            if (!entry)
-                throw new Error("Unknown command. Type 'help'.");
-            if (satori == null) {
-                console.error("❌ You are not connected");
+            if (!entry) {
+                fail(`Unknown command: ${c.cyan}${cmd}${c.reset}  — type ${c.cyan}help${c.reset}`);
+            }
+            else if (!entry.noConn && !satori) {
+                fail(`Not connected — use: ${c.cyan}connect <host>${c.reset}`);
             }
             else {
                 await entry.run(args);
             }
         }
         catch (e) {
-            console.error("❌", e.message);
+            fail(e.message ?? String(e));
         }
         refreshPrompt();
         rl.prompt();
     });
+    rl.on('close', () => {
+        saveHistory(rl.history ?? []);
+        console.log();
+        process.exit(0);
+    });
 }
-// -------------------------------
-// Entry
-// -------------------------------
+// ── Entry ──────────────────────────────────────────────────────────────────────
 const argv = process.argv.slice(2);
-if (argv[0] === "run") {
+if (argv[0] === 'run') {
     runBinary(argv.slice(1));
 }
-else if (argv[0] === "update") {
-    require("./postinstall");
+else if (argv[0] === 'update') {
+    require('./postinstall');
 }
-else if (argv[0] === "verify") {
-    require("./verify-install");
+else if (argv[0] === 'verify') {
+    require('./verify-install');
 }
 else {
     startREPL();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "satoridb",
-  "version": "1.2.6",
+  "version": "1.2.7",
   "description": "Install satori",
   "bin": {
     "satoridb": "./cli.js"

package/postinstall.js

@@ -10,14 +10,32 @@ let { spawnSync } = require("child_process");
 let platform = os.platform();
 let arch = os.arch();
 
+// ── CLI-only mode ──────────────────────────────────────────────────────────────
+// Set SATORI_NO_BINARY=1 to skip the binary download entirely.
+// The interactive shell (satoridb) still works — it only needs a running
+// Satori server reachable over WebSocket.
+//
+//   SATORI_NO_BINARY=1 npm install -g satoridb
+//
+if (process.env.SATORI_NO_BINARY === "1") {
+  console.log("  ℹ  Skipping Satori binary download  (SATORI_NO_BINARY=1)");
+  console.log("  ·  The CLI shell is ready:   satoridb");
+  console.log("  ·  To download the binary later:  satoridb update");
+  process.exit(0);
+}
+
 let baseURL = "https://www.satoridb.com";
 let fileName;
 
 if (platform === "linux") fileName = "lin/satori-linux.zip";
 else if (platform === "win32") fileName = "win/satori-win.zip";
 else {
-  console.log("❌ Platform not supported:", platform);
-  process.exit(1);
+  // Unsupported platform — warn but do not fail; CLI shell still works.
+  console.log(`  ⚠  No pre-built binary for platform: ${platform}`);
+  console.log("  ·  The CLI shell is still available:  satoridb");
+  console.log("  ·  Connect to any Satori server via:  connect <ws://host:port>");
+  console.log("  ·  To skip this message next time:    SATORI_NO_BINARY=1 npm install -g satoridb");
+  process.exit(0);
 }
 
 let binName = platform === "win32" ? "satori.exe" : "satori";