@stitchdb/cli 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# @stitchdb/cli
+
+`stitch` — memory + agent control plane CLI.
+
+## Install
+
+```bash
+npm install -g @stitchdb/cli
+stitch login   # paste your API key
+```
+
+## Memory
+
+```bash
+stitch remember "We chose Drizzle over Prisma" --kind decision --tag db
+stitch recall "which ORM do we use?"
+```
+
+## Run an agent on this machine
+
+```bash
+# 1. Register an agent identity (one-time, returns an id):
+stitch agent register my-laptop
+
+# 2. Hold open the control channel — keep this running:
+stitch agent run --id agt_a1b2c3d4e5f60789
+
+# 3. From any other machine, dispatch a command:
+stitch agent dispatch agt_a1b2c3d4e5f60789 "summarize the last commit"
+```
+
+By default `stitch agent run` will execute `claude -p "<prompt>"` for `prompt`-kind dispatches. Shell execution is opt-in via `--allow-shell`.
+
+## Add to Claude Code
+
+```bash
+stitch mcp-install
+# prints the `claude mcp add stitch …` command
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,492 @@
+#!/usr/bin/env node
+/**
+ * `stitch` — CLI for the Stitch memory + agent control plane.
+ *
+ *   stitch login                          Save your API key locally.
+ *   stitch logout                         Remove the saved key.
+ *   stitch whoami                         Show the configured key (masked).
+ *
+ *   stitch remember <text> [--kind X] [--tag a,b]
+ *   stitch recall <query> [-k 5]
+ *
+ *   stitch agent register <name>          Create a new agent identity.
+ *   stitch agent list                     List your agents (online status).
+ *   stitch agent run --id <agent_id>      Hold open a control channel + execute dispatched commands.
+ *   stitch agent dispatch <id> <prompt>   Send a command to a connected agent.
+ *   stitch agent revoke <id>              Revoke an agent.
+ *
+ *   stitch workspace create <name>
+ *   stitch workspace list
+ *   stitch workspace use <id>             Set the default workspace.
+ *
+ *   stitch mcp-install [--id <agent_id>]  Print the `claude mcp add stitch …` command for your workspace.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { spawn } from 'node:child_process';
+import { Stitch } from '@stitchdb/agent';
+const CONFIG_DIR = path.join(os.homedir(), '.stitch');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+function loadConfig() {
+    try {
+        return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function saveConfig(c) {
+    if (!fs.existsSync(CONFIG_DIR))
+        fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(c, null, 2), { mode: 0o600 });
+}
+function mask(key) {
+    if (!key)
+        return '(none)';
+    if (key.length < 12)
+        return '****';
+    return key.slice(0, 7) + '…' + key.slice(-4);
+}
+function client(cfg) {
+    if (!cfg.apiKey) {
+        console.error('Not logged in. Run: stitch login');
+        process.exit(2);
+    }
+    return new Stitch({
+        apiKey: cfg.apiKey,
+        baseUrl: cfg.baseUrl,
+        workspace: cfg.defaultWorkspace,
+    });
+}
+// ─── Argv helpers ──────────────────────────────────────────────────────────
+function parseFlag(args, names) {
+    for (const name of names) {
+        const i = args.findIndex((a) => a === name || a.startsWith(name + '='));
+        if (i === -1)
+            continue;
+        if (args[i].includes('='))
+            return args[i].split('=', 2)[1];
+        return args[i + 1];
+    }
+    return undefined;
+}
+function hasFlag(args, names) {
+    return args.some((a) => names.some((n) => a === n));
+}
+function positional(args) {
+    return args.filter((a) => !a.startsWith('-'));
+}
+async function readJsonBody(res) {
+    const text = await res.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(text);
+    }
+}
+// ─── Commands ──────────────────────────────────────────────────────────────
+async function cmdLogin(args) {
+    const fromFlag = parseFlag(args, ['--key', '-k']);
+    const fromEnv = process.env.STITCHDB_API_KEY;
+    let key = fromFlag || fromEnv;
+    if (!key) {
+        process.stdout.write('Paste your StitchDB API key: ');
+        key = await readLine();
+    }
+    key = (key || '').trim();
+    if (!key.startsWith('sdb_sk_')) {
+        console.error('That does not look like a Stitch key (should start with sdb_sk_).');
+        process.exit(2);
+    }
+    const cfg = loadConfig();
+    cfg.apiKey = key;
+    cfg.baseUrl = cfg.baseUrl || 'https://db.stitchdb.com';
+    saveConfig(cfg);
+    console.log(`Saved key ${mask(key)} to ${CONFIG_FILE}`);
+}
+async function cmdLogout() {
+    const cfg = loadConfig();
+    delete cfg.apiKey;
+    delete cfg.defaultWorkspace;
+    saveConfig(cfg);
+    console.log('Logged out.');
+}
+async function cmdWhoami() {
+    const cfg = loadConfig();
+    console.log('API key:    ', mask(cfg.apiKey || ''));
+    console.log('Base URL:   ', cfg.baseUrl || 'https://db.stitchdb.com');
+    console.log('Workspace:  ', cfg.defaultWorkspace || '(none — first will auto-create)');
+    console.log('Config file:', CONFIG_FILE);
+}
+async function cmdRemember(args) {
+    const cfg = loadConfig();
+    const stitch = client(cfg);
+    const positionals = positional(args);
+    const content = positionals.join(' ');
+    if (!content) {
+        console.error('Usage: stitch remember <text>');
+        process.exit(2);
+    }
+    const kind = parseFlag(args, ['--kind']);
+    const tagFlag = parseFlag(args, ['--tag', '--tags']);
+    const tags = tagFlag ? tagFlag.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+    const out = await stitch.remember(content, { kind, tags });
+    console.log(`Stored ${out.id}${out.embedded ? '' : ' (no embedding — degraded mode)'}`);
+}
+async function cmdRecall(args) {
+    const cfg = loadConfig();
+    const stitch = client(cfg);
+    const positionals = positional(args);
+    const query = positionals.join(' ');
+    if (!query) {
+        console.error('Usage: stitch recall <query> [-k 5]');
+        process.exit(2);
+    }
+    const k = Number(parseFlag(args, ['-k', '--k']) || '5');
+    const hits = await stitch.recall(query, { k });
+    if (hits.length === 0) {
+        console.log('No matches.');
+        return;
+    }
+    for (const [i, h] of hits.entries()) {
+        console.log(`${(i + 1).toString().padStart(2)}. [${h.kind}] (score ${h.score.toFixed(3)}, ${h.id})`);
+        console.log('    ' + h.content.split('\n').join('\n    '));
+    }
+}
+async function cmdWorkspace(args) {
+    const cfg = loadConfig();
+    const stitch = client(cfg);
+    const sub = args[0];
+    const rest = args.slice(1);
+    if (sub === 'list') {
+        const list = await stitch.workspaces.list();
+        for (const w of list)
+            console.log(`${w.id}  ${w.name}`);
+    }
+    else if (sub === 'create') {
+        const name = positional(rest).join(' ') || 'default';
+        const w = await stitch.workspaces.create(name);
+        console.log(`Created ${w.id}  ${w.name}`);
+    }
+    else if (sub === 'use') {
+        const id = rest[0];
+        if (!id) {
+            console.error('Usage: stitch workspace use <id>');
+            process.exit(2);
+        }
+        cfg.defaultWorkspace = id;
+        saveConfig(cfg);
+        console.log(`Default workspace set: ${id}`);
+    }
+    else {
+        console.error('Usage: stitch workspace [list|create <name>|use <id>]');
+        process.exit(2);
+    }
+}
+async function cmdAgent(args) {
+    const cfg = loadConfig();
+    if (!cfg.apiKey) {
+        console.error('Not logged in. Run: stitch login');
+        process.exit(2);
+    }
+    const sub = args[0];
+    const rest = args.slice(1);
+    const baseUrl = cfg.baseUrl || 'https://db.stitchdb.com';
+    if (sub === 'register') {
+        const name = positional(rest).join(' ') || os.hostname();
+        const res = await fetch(`${baseUrl}/v1/agent/agents`, {
+            method: 'POST',
+            headers: { 'Authorization': `Bearer ${cfg.apiKey}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                name,
+                machine: `${os.platform()} ${os.arch()} (${os.hostname()})`,
+                version: 'cli-0.1.0',
+                capabilities: ['claude_code', 'shell'],
+            }),
+        });
+        const body = await readJsonBody(res);
+        if (!res.ok) {
+            console.error(body);
+            process.exit(1);
+        }
+        console.log(`Agent registered: ${body.agent.id}`);
+        console.log(`Run on the target machine:`);
+        console.log(`  stitch agent run --id ${body.agent.id}`);
+        return;
+    }
+    if (sub === 'list') {
+        const res = await fetch(`${baseUrl}/v1/agent/agents`, {
+            headers: { 'Authorization': `Bearer ${cfg.apiKey}` },
+        });
+        const body = await readJsonBody(res);
+        if (!res.ok) {
+            console.error(body);
+            process.exit(1);
+        }
+        if (body.agents.length === 0) {
+            console.log('No agents yet. Try: stitch agent register <name>');
+            return;
+        }
+        for (const a of body.agents) {
+            const status = a.online ? '● online' : (a.revoked_at ? 'revoked' : '○ offline');
+            const ago = a.last_seen_at ? humanAgo(Date.now() - a.last_seen_at) : 'never';
+            console.log(`${a.id}  ${status.padEnd(10)}  ${a.name.padEnd(24)}  last seen ${ago}`);
+        }
+        return;
+    }
+    if (sub === 'run') {
+        const agentId = parseFlag(rest, ['--id', '-i']);
+        if (!agentId) {
+            console.error('Usage: stitch agent run --id <agent_id>');
+            process.exit(2);
+        }
+        const allowShell = hasFlag(rest, ['--allow-shell']);
+        return runAgent(cfg, agentId, { allowShell });
+    }
+    if (sub === 'dispatch') {
+        const positionals = positional(rest);
+        const agentId = positionals[0];
+        const prompt = positionals.slice(1).join(' ');
+        if (!agentId || !prompt) {
+            console.error('Usage: stitch agent dispatch <agent_id> <prompt>');
+            process.exit(2);
+        }
+        const kind = parseFlag(rest, ['--kind']) || 'prompt';
+        const cwd = parseFlag(rest, ['--cwd']);
+        const timeoutMs = Number(parseFlag(rest, ['--timeout']) || '120000');
+        const payload = { kind, timeoutMs };
+        if (kind === 'shell')
+            payload.command = prompt;
+        else
+            payload.prompt = prompt;
+        if (cwd)
+            payload.cwd = cwd;
+        const res = await fetch(`${baseUrl}/v1/agent/agents/${encodeURIComponent(agentId)}/dispatch`, {
+            method: 'POST',
+            headers: { 'Authorization': `Bearer ${cfg.apiKey}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+        });
+        const body = await readJsonBody(res);
+        if (!res.ok) {
+            console.error(body);
+            process.exit(1);
+        }
+        if (body.error) {
+            console.error('Error:', body.error);
+            process.exit(1);
+        }
+        if (body.stdout)
+            process.stdout.write(body.stdout);
+        if (body.stderr)
+            process.stderr.write(body.stderr);
+        if (typeof body.exit_code === 'number')
+            process.exit(body.exit_code);
+        return;
+    }
+    if (sub === 'revoke') {
+        const id = rest[0];
+        if (!id) {
+            console.error('Usage: stitch agent revoke <id>');
+            process.exit(2);
+        }
+        const res = await fetch(`${baseUrl}/v1/agent/agents/${encodeURIComponent(id)}`, {
+            method: 'DELETE',
+            headers: { 'Authorization': `Bearer ${cfg.apiKey}` },
+        });
+        const body = await readJsonBody(res);
+        if (!res.ok) {
+            console.error(body);
+            process.exit(1);
+        }
+        console.log(`Revoked ${id}`);
+        return;
+    }
+    console.error('Usage: stitch agent [register|list|run|dispatch|revoke] …');
+    process.exit(2);
+}
+async function cmdMcpInstall(args) {
+    const cfg = loadConfig();
+    if (!cfg.apiKey) {
+        console.error('Not logged in. Run: stitch login');
+        process.exit(2);
+    }
+    const stitch = client(cfg);
+    const ws = await stitch.resolveWorkspace();
+    const baseUrl = cfg.baseUrl || 'https://db.stitchdb.com';
+    console.log('# Add Stitch as an MCP server in Claude Code:');
+    console.log(`claude mcp add stitch \\`);
+    console.log(`  ${baseUrl}/mcp/v1/${ws} \\`);
+    console.log(`  --transport http \\`);
+    console.log(`  --header "Authorization: Bearer ${cfg.apiKey}"`);
+    console.log();
+    console.log('# Or for Cursor / Continue / Aider — add the same URL with the same Authorization header.');
+}
+// ─── Agent run loop ─────────────────────────────────────────────────────────
+async function runAgent(cfg, agentId, opts) {
+    const baseUrl = (cfg.baseUrl || 'https://db.stitchdb.com').replace(/^http/, 'ws');
+    const url = `${baseUrl}/ws/agent?id=${encodeURIComponent(agentId)}&key=${encodeURIComponent(cfg.apiKey)}`;
+    let connection = 0;
+    let backoff = 1000;
+    const connect = () => new Promise((resolveOuter) => {
+        connection++;
+        const startedAt = Date.now();
+        const ws = new WebSocket(url);
+        ws.addEventListener('open', () => {
+            backoff = 1000;
+            console.log(`[stitch agent] online — id=${agentId} (connection #${connection})`);
+            // Send initial status report.
+            ws.send(JSON.stringify({
+                type: 'status',
+                status: {
+                    cwd: process.cwd(),
+                    platform: process.platform,
+                    arch: process.arch,
+                    host: os.hostname(),
+                    allow_shell: opts.allowShell,
+                    pid: process.pid,
+                },
+            }));
+            // Heartbeat every 30s.
+            const hb = setInterval(() => {
+                if (ws.readyState === ws.OPEN)
+                    ws.send(JSON.stringify({ type: 'heartbeat' }));
+            }, 30_000);
+            ws.__hb = hb;
+        });
+        ws.addEventListener('message', async (e) => {
+            let msg;
+            try {
+                msg = JSON.parse(typeof e.data === 'string' ? e.data : new TextDecoder().decode(e.data));
+            }
+            catch {
+                return;
+            }
+            if (msg.type === 'dispatch') {
+                const { taskId } = msg;
+                try {
+                    const result = await executeDispatch(msg, opts);
+                    ws.send(JSON.stringify({ type: 'response', taskId, result, final: true }));
+                }
+                catch (err) {
+                    ws.send(JSON.stringify({ type: 'response', taskId, error: err?.message || String(err), final: true }));
+                }
+            }
+        });
+        ws.addEventListener('error', () => { });
+        ws.addEventListener('close', () => {
+            clearInterval(ws.__hb);
+            const lifespan = Date.now() - startedAt;
+            console.error(`[stitch agent] disconnected (lived ${Math.round(lifespan / 1000)}s) — reconnecting in ${backoff}ms`);
+            setTimeout(() => connect().then(resolveOuter), backoff);
+            backoff = Math.min(backoff * 2, 30_000);
+        });
+    });
+    // Hold the process open forever (until SIGINT).
+    await connect();
+    await new Promise(() => { });
+}
+async function executeDispatch(input, opts) {
+    if (input.kind === 'prompt') {
+        if (!input.prompt)
+            throw new Error('prompt is required');
+        // Spawn `claude -p <prompt>` if Claude Code is on PATH.
+        const claudeBin = process.env.STITCH_CLAUDE_BIN || 'claude';
+        const out = await run(claudeBin, ['-p', input.prompt], { cwd: input.cwd });
+        return out;
+    }
+    if (input.kind === 'shell') {
+        if (!opts.allowShell)
+            throw new Error('Shell execution not enabled. Run with --allow-shell to opt in.');
+        if (!input.command)
+            throw new Error('command is required');
+        const out = await run('/bin/sh', ['-c', input.command], { cwd: input.cwd, env: input.env });
+        return out;
+    }
+    if (input.kind === 'ping') {
+        return { ok: true, ts: Date.now() };
+    }
+    throw new Error(`Unknown dispatch kind: ${input.kind}`);
+}
+function run(cmd, args, opts = {}) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, {
+            cwd: opts.cwd || process.cwd(),
+            env: { ...process.env, ...(opts.env || {}) },
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => stdout += d.toString());
+        child.stderr.on('data', (d) => stderr += d.toString());
+        child.on('error', (err) => resolve({ stdout, stderr: stderr + '\n[spawn error] ' + err.message, exit_code: 127 }));
+        child.on('close', (code) => resolve({ stdout, stderr, exit_code: code ?? 0 }));
+    });
+}
+function readLine() {
+    return new Promise((resolve) => {
+        const onData = (d) => { process.stdin.off('data', onData); resolve(d.toString().trim()); };
+        process.stdin.on('data', onData);
+    });
+}
+function humanAgo(ms) {
+    if (ms < 60_000)
+        return Math.round(ms / 1000) + 's ago';
+    if (ms < 3_600_000)
+        return Math.round(ms / 60_000) + 'm ago';
+    if (ms < 86_400_000)
+        return Math.round(ms / 3_600_000) + 'h ago';
+    return Math.round(ms / 86_400_000) + 'd ago';
+}
+function help() {
+    console.log(`stitch — memory + agent control plane
+
+  stitch login                                Save your API key.
+  stitch whoami                               Show the configured key.
+  stitch logout
+
+  stitch remember <text> [--kind X] [--tag a,b]
+  stitch recall <query> [-k 5]
+
+  stitch workspace [list | create <name> | use <id>]
+
+  stitch agent register <name>                Create an agent identity (id only).
+  stitch agent list
+  stitch agent run --id <agent_id> [--allow-shell]
+  stitch agent dispatch <agent_id> <prompt> [--kind prompt|shell] [--cwd path]
+  stitch agent revoke <agent_id>
+
+  stitch mcp-install                          Print the Claude Code MCP install command.
+`);
+}
+// ─── Entry ─────────────────────────────────────────────────────────────────
+async function main(argv) {
+    const [cmd, ...rest] = argv;
+    try {
+        switch (cmd) {
+            case 'login': return cmdLogin(rest);
+            case 'logout': return cmdLogout();
+            case 'whoami': return cmdWhoami();
+            case 'remember': return cmdRemember(rest);
+            case 'recall': return cmdRecall(rest);
+            case 'workspace':
+            case 'ws': return cmdWorkspace(rest);
+            case 'agent': return cmdAgent(rest);
+            case 'mcp-install':
+            case 'mcp': return cmdMcpInstall(rest);
+            case 'help':
+            case '--help':
+            case '-h':
+            case undefined: return help();
+            default:
+                console.error(`Unknown command: ${cmd}`);
+                help();
+                process.exit(2);
+        }
+    }
+    catch (e) {
+        console.error('Error:', e?.message || e);
+        process.exit(1);
+    }
+}
+main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@stitchdb/cli",
+  "version": "0.1.0",
+  "description": "Stitch CLI — manage memory + run agents from your terminal",
+  "type": "module",
+  "bin": {
+    "stitch": "dist/cli.js"
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx src/cli.ts"
+  },
+  "keywords": ["mcp", "ai", "agent", "claude-code", "memory", "stitchdb"],
+  "license": "MIT",
+  "engines": { "node": ">=20" },
+  "dependencies": {
+    "@stitchdb/agent": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^22.0.0"
+  }
+}