@stitchdb/cli 0.1.0 → 0.3.0

package/dist/cli.js

@@ -2,32 +2,63 @@
 /**
  * `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 login                                  Save your API key locally.
+ *   stitch logout                                 Remove the saved key.
+ *   stitch whoami                                 Show the configured key (masked).
+ *
+ *   stitch install                                One-shot: install Stitch as an MCP
+ *                                                 server in Claude Code, wire auto-log
+ *                                                 hooks, write a CLAUDE.md instruction
+ *                                                 in the current project so Claude
+ *                                                 auto-recalls past context at session start.
  *
  *   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 thread append --role <r> [--thread <t>] [--content <c>]
+ *                                                 Append a turn (or read content from stdin).
+ *                                                 Used by Claude Code hooks for auto-logging.
+ *   stitch thread recall [--thread <t>] [--last 10] [--semantic <q>]
+ *   stitch thread current                         Print the thread name for the current repo / cwd.
+ *
+ *   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.
+ *   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 workspace use <id>
  *
- *   stitch mcp-install [--id <agent_id>]  Print the `claude mcp add stitch …` command for your workspace.
+ *   stitch mcp-install                            Print the `claude mcp add stitch …` command.
  */
 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 { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { Stitch } from '@stitchdb/agent';
 const CONFIG_DIR = path.join(os.homedir(), '.stitch');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+const UPDATE_CACHE = path.join(CONFIG_DIR, 'update-check.json');
+// Embedded at build time from package.json, but keeps a fallback if the file's
+// not next to the bundle (e.g. published tarball layout).
+const CLI_VERSION = readSelfVersion() ?? '0.0.0';
+function readSelfVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        for (const candidate of [path.join(here, '..', 'package.json'), path.join(here, 'package.json')]) {
+            if (fs.existsSync(candidate)) {
+                const pkg = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+                if (pkg.name === '@stitchdb/cli' && typeof pkg.version === 'string')
+                    return pkg.version;
+            }
+        }
+    }
+    catch { /* ignore */ }
+    return null;
+}
 function loadConfig() {
     try {
         return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
@@ -306,6 +337,311 @@ async function cmdAgent(args) {
     console.error('Usage: stitch agent [register|list|run|dispatch|revoke] …');
     process.exit(2);
 }
+// ── Threads — append / recall / current ───────────────────────────────────
+function inferThread() {
+    // Reasonable default: <git-repo-name>/<branch> if we're in a git repo,
+    // else the cwd's basename. Hooks call this to get a stable thread per project.
+    try {
+        const dir = process.cwd();
+        let cur = dir;
+        for (let i = 0; i < 8; i++) {
+            if (fs.existsSync(path.join(cur, '.git'))) {
+                const parent = path.dirname(cur);
+                const repoName = path.basename(cur);
+                let branch = 'main';
+                try {
+                    const head = fs.readFileSync(path.join(cur, '.git', 'HEAD'), 'utf8').trim();
+                    const m = head.match(/^ref:\s+refs\/heads\/(.+)$/);
+                    if (m)
+                        branch = m[1];
+                }
+                catch { /* detached */ }
+                return `${repoName}/${branch}`;
+                void parent;
+            }
+            const next = path.dirname(cur);
+            if (next === cur)
+                break;
+            cur = next;
+        }
+        return path.basename(dir);
+    }
+    catch {
+        return 'default';
+    }
+}
+async function cmdThread(args) {
+    const cfg = loadConfig();
+    const stitch = client(cfg);
+    const sub = args[0];
+    const rest = args.slice(1);
+    if (sub === 'append') {
+        const role = parseFlag(rest, ['--role']);
+        let thread = parseFlag(rest, ['--thread', '-t']) || inferThread();
+        let content = parseFlag(rest, ['--content', '-c']);
+        if (!content) {
+            // If no --content given, read from stdin (so a hook can pipe in the message).
+            content = await readStdinAll();
+        }
+        if (!role) {
+            console.error('Usage: stitch thread append --role user|assistant --content <text> [--thread name]');
+            process.exit(2);
+        }
+        if (!content) {
+            console.error('No content provided (use --content or pipe stdin).');
+            process.exit(2);
+        }
+        const out = await stitch.thread(thread).append({ role, content });
+        console.log(`Appended ${out.turn_id} to ${thread} (${out.thread_id})`);
+        return;
+    }
+    if (sub === 'recall') {
+        const positionals = positional(rest);
+        const thread = parseFlag(rest, ['--thread', '-t']) || positionals[0] || inferThread();
+        const last = Number(parseFlag(rest, ['--last']) || '10');
+        const semantic = parseFlag(rest, ['--semantic']);
+        const out = await stitch.thread(thread).recall({ last, semantic, semantic_k: 5 });
+        if (!out.thread_id) {
+            console.log('Thread not found.');
+            return;
+        }
+        if (out.recent.length === 0 && out.semantic.length === 0) {
+            console.log('Empty thread.');
+            return;
+        }
+        if (out.recent.length) {
+            console.log(`# Recent (${out.recent.length})`);
+            for (const t of out.recent)
+                console.log(`- ${t.role}: ${t.content}`);
+        }
+        if (out.semantic.length) {
+            console.log(`\n# Semantic matches`);
+            for (const t of out.semantic)
+                console.log(`- ${t.role} (score ${(t.score ?? 0).toFixed(3)}): ${t.content}`);
+        }
+        return;
+    }
+    if (sub === 'current') {
+        console.log(inferThread());
+        return;
+    }
+    console.error('Usage: stitch thread [append|recall|current] …');
+    process.exit(2);
+}
+function readStdinAll() {
+    return new Promise((resolve) => {
+        let data = '';
+        if (process.stdin.isTTY) {
+            resolve('');
+            return;
+        }
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (c) => (data += c));
+        process.stdin.on('end', () => resolve(data.trim()));
+    });
+}
+function loadUpdateCache() {
+    try {
+        return JSON.parse(fs.readFileSync(UPDATE_CACHE, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function saveUpdateCache(c) {
+    try {
+        if (!fs.existsSync(CONFIG_DIR))
+            fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(UPDATE_CACHE, JSON.stringify(c));
+    }
+    catch { /* ignore */ }
+}
+function semverGt(a, b) {
+    const pa = a.split('.').map((x) => parseInt(x, 10) || 0);
+    const pb = b.split('.').map((x) => parseInt(x, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] ?? 0) > (pb[i] ?? 0))
+            return true;
+        if ((pa[i] ?? 0) < (pb[i] ?? 0))
+            return false;
+    }
+    return false;
+}
+/**
+ * Best-effort fetch of the latest published version. Cached for 6h so we don't
+ * hammer npm. Runs after the user's command is done and prints a one-line
+ * notice if an update is available. Never blocks, never errors loudly.
+ */
+async function maybeNotifyUpdate() {
+    if (process.env.STITCH_NO_UPDATE_CHECK === '1')
+        return;
+    try {
+        const cache = loadUpdateCache();
+        const fresh = cache && Date.now() - cache.checkedAt < 6 * 3600_000;
+        let latest = fresh ? cache.latest : '';
+        if (!fresh) {
+            const ctrl = new AbortController();
+            const t = setTimeout(() => ctrl.abort(), 1500);
+            try {
+                const res = await fetch('https://registry.npmjs.org/@stitchdb/cli/latest', { signal: ctrl.signal });
+                if (res.ok) {
+                    const j = await res.json();
+                    if (j.version)
+                        latest = j.version;
+                    saveUpdateCache({ checkedAt: Date.now(), latest });
+                }
+            }
+            finally {
+                clearTimeout(t);
+            }
+        }
+        if (latest && semverGt(latest, CLI_VERSION)) {
+            const msg = `\n  Stitch CLI ${latest} is available (you have ${CLI_VERSION}). Run: stitch update\n`;
+            process.stderr.write(msg);
+        }
+    }
+    catch { /* never let the check break a real command */ }
+}
+async function cmdUpdate(args) {
+    const channel = parseFlag(args, ['--tag']) || 'latest';
+    console.log(`Updating @stitchdb/cli (current: ${CLI_VERSION}) → ${channel}…`);
+    // Use the user's npm. Try `npm i -g @stitchdb/cli@latest` first; if that
+    // fails with EACCES, retry under sudo.
+    const cmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const result = spawnSync(cmd, ['install', '-g', `@stitchdb/cli@${channel}`], { stdio: 'inherit' });
+    if (result.status !== 0) {
+        console.error('\nUpdate failed. Try one of:');
+        console.error(`  npm install -g @stitchdb/cli@${channel}`);
+        console.error(`  sudo npm install -g @stitchdb/cli@${channel}`);
+        process.exit(result.status ?? 1);
+    }
+    // Reset the cache so we don't nag with the version we just installed.
+    saveUpdateCache({ checkedAt: Date.now(), latest: '0.0.0' });
+    console.log('\nUpdated. Open a fresh shell or run `which stitch` to verify.');
+}
+// ── One-shot install: MCP server + auto-log hooks + project CLAUDE.md ─────
+async function cmdInstall(args) {
+    const cfg = loadConfig();
+    if (!cfg.apiKey) {
+        console.error('Run `stitch login` first.');
+        process.exit(2);
+    }
+    const stitch = client(cfg);
+    const ws = await stitch.resolveWorkspace();
+    const baseUrl = cfg.baseUrl || 'https://db.stitchdb.com';
+    const mcpUrl = `${baseUrl}/mcp/v1/${ws}`;
+    const noMcp = hasFlag(args, ['--no-mcp']);
+    const noHooks = hasFlag(args, ['--no-hooks']);
+    const noClaudeMd = hasFlag(args, ['--no-claude-md']);
+    // 1. claude mcp add
+    if (!noMcp) {
+        const claudePath = process.env.STITCH_CLAUDE_BIN || 'claude';
+        process.stdout.write('• Adding Stitch as an MCP server in Claude Code… ');
+        const { exit_code, stderr } = await runSilent(claudePath, [
+            'mcp', 'add', '--transport', 'http', '--scope', 'user', 'stitch', mcpUrl,
+            '-H', `Authorization: Bearer ${cfg.apiKey}`,
+        ]);
+        if (exit_code === 0)
+            console.log('ok');
+        else if (stderr.includes('already exists'))
+            console.log('already configured');
+        else
+            console.log(`failed (${stderr.trim().slice(0, 120)})`);
+    }
+    // 2. Hooks for auto-logging conversations
+    if (!noHooks) {
+        process.stdout.write('• Wiring auto-log hooks (UserPromptSubmit + Stop)… ');
+        try {
+            const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+            const existing = fs.existsSync(settingsPath)
+                ? JSON.parse(fs.readFileSync(settingsPath, 'utf8'))
+                : {};
+            existing.hooks = existing.hooks || {};
+            existing.hooks.UserPromptSubmit = mergeHook(existing.hooks.UserPromptSubmit, STITCH_USER_HOOK);
+            existing.hooks.Stop = mergeHook(existing.hooks.Stop, STITCH_STOP_HOOK);
+            fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+            fs.writeFileSync(settingsPath, JSON.stringify(existing, null, 2));
+            console.log('ok');
+        }
+        catch (e) {
+            console.log(`skipped (${e.message})`);
+        }
+    }
+    // 3. CLAUDE.md instruction in cwd so Claude auto-recalls at session start
+    if (!noClaudeMd) {
+        const claudeMd = path.join(process.cwd(), 'CLAUDE.md');
+        const block = STITCH_CLAUDE_MD_BLOCK;
+        let body = '';
+        let action = 'created';
+        if (fs.existsSync(claudeMd)) {
+            body = fs.readFileSync(claudeMd, 'utf8');
+            if (body.includes('<!-- stitch:auto -->')) {
+                action = 'already present';
+            }
+            else {
+                body = body.trimEnd() + '\n\n' + block + '\n';
+                action = 'appended';
+            }
+        }
+        else {
+            body = block + '\n';
+        }
+        if (action !== 'already present')
+            fs.writeFileSync(claudeMd, body);
+        console.log(`• ${action === 'created' ? 'Wrote' : action === 'appended' ? 'Appended to' : 'Found'} ./CLAUDE.md (${action})`);
+    }
+    console.log();
+    console.log('Done. Open a fresh `claude` session — Stitch is wired.');
+    console.log('  • remember/recall tools are available');
+    console.log('  • every turn auto-logs to the thread for this repo');
+    console.log('  • Claude auto-pulls past context at session start (per CLAUDE.md)');
+}
+const STITCH_USER_HOOK = {
+    matcher: '*',
+    hooks: [
+        { type: 'command', command: `bash -c 'jq -r .prompt | stitch thread append --role user --thread "$(stitch thread current)" 2>/dev/null || true'` },
+    ],
+};
+const STITCH_STOP_HOOK = {
+    matcher: '*',
+    hooks: [
+        { type: 'command', command: `bash -c 'jq -r .response.text 2>/dev/null | stitch thread append --role assistant --thread "$(stitch thread current)" 2>/dev/null || true'` },
+    ],
+};
+function mergeHook(existing, entry) {
+    const arr = Array.isArray(existing) ? existing.slice() : [];
+    // Replace any earlier Stitch entry; identify by marker substring.
+    const isStitch = (h) => JSON.stringify(h).includes('stitch thread append');
+    const filtered = arr.filter((h) => !isStitch(h));
+    filtered.push(entry);
+    return filtered;
+}
+const STITCH_CLAUDE_MD_BLOCK = `<!-- stitch:auto -->
+## Stitch memory
+
+This project is wired to Stitch (memory layer for AI agents).
+
+When a session starts here, **call \`recall\` from the \`stitch\` MCP server first**
+to pull any prior facts, decisions, or discussion threads about this repo before
+answering. The thread name for this repo is reported by \`stitch thread current\`.
+
+When you learn something durable about this codebase or its conventions, call
+\`remember\` to save it — \`fact\`, \`decision\`, \`snippet\`, or \`preference\`.
+
+Every user message and assistant reply is also auto-logged to a per-repo thread
+via Claude Code hooks, so future sessions can \`thread_recall\` to resume context.
+<!-- /stitch:auto -->`;
+async function runSilent(cmd, args) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args);
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => (stdout += d.toString()));
+        child.stderr.on('data', (d) => (stderr += d.toString()));
+        child.on('error', (e) => resolve({ stdout, stderr: stderr + '\n' + e.message, exit_code: 127 }));
+        child.on('close', (code) => resolve({ stdout, stderr, exit_code: code ?? 0 }));
+    });
+}
 async function cmdMcpInstall(args) {
     const cfg = loadConfig();
     if (!cfg.apiKey) {
@@ -445,9 +781,24 @@ function help() {
   stitch whoami                               Show the configured key.
   stitch logout
 
+  stitch update                               Update to the latest @stitchdb/cli.
+  stitch version                              Print the installed version.
+
+  stitch install [--no-mcp] [--no-hooks] [--no-claude-md]
+                                              One-shot: register Stitch as an MCP
+                                              server in Claude Code, wire up auto-log
+                                              hooks, drop a CLAUDE.md instruction in
+                                              the current project so Claude auto-recalls
+                                              at session start.
+
   stitch remember <text> [--kind X] [--tag a,b]
   stitch recall <query> [-k 5]
 
+  stitch thread append --role user|assistant [--thread <name>] [--content <text>]
+  stitch thread recall [--thread <name>] [--last 10] [--semantic <q>]
+  stitch thread current                       Print the auto-derived thread name
+                                              for the current repo / cwd.
+
   stitch workspace [list | create <name> | use <id>]
 
   stitch agent register <name>                Create an agent identity (id only).
@@ -469,6 +820,16 @@ async function main(argv) {
             case 'whoami': return cmdWhoami();
             case 'remember': return cmdRemember(rest);
             case 'recall': return cmdRecall(rest);
+            case 'thread': return cmdThread(rest);
+            case 'install': return cmdInstall(rest);
+            case 'update':
+            case 'upgrade': return cmdUpdate(rest);
+            case 'version':
+            case '--version':
+            case '-v': {
+                console.log(CLI_VERSION);
+                return;
+            }
             case 'workspace':
             case 'ws': return cmdWorkspace(rest);
             case 'agent': return cmdAgent(rest);
@@ -489,4 +850,4 @@ async function main(argv) {
         process.exit(1);
     }
 }
-main(process.argv.slice(2));
+main(process.argv.slice(2)).then(() => maybeNotifyUpdate());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stitchdb/cli",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Stitch CLI — manage memory + run agents from your terminal",
   "type": "module",
   "bin": {