membot 0.0.1 → 0.1.1

package/scripts/apply-transformers-patch.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Apply the @huggingface/transformers patch to node_modules so that
+# `bun build --compile` produces a binary using the WASM backend
+# (onnxruntime-web) instead of onnxruntime-node, whose native bindings
+# can't be bundled into a single-binary distribution.
+#
+# We apply the patch imperatively (rather than via package.json
+# `patchedDependencies`) because that field, when present in a
+# published package, breaks `bun install` from a tarball.
+
+PATCH="patches/@huggingface%2Ftransformers@4.2.0.patch"
+TARGET="node_modules/@huggingface/transformers"
+MARKER="$TARGET/.membot-transformers-patch-applied"
+
+if [ ! -d "$TARGET" ]; then
+	echo "error: $TARGET not found — run \`bun install\` first" >&2
+	exit 1
+fi
+
+if [ ! -f "$PATCH" ]; then
+	echo "error: $PATCH not found" >&2
+	exit 1
+fi
+
+if [ -f "$MARKER" ]; then
+	echo "transformers patch already applied — skipping"
+	exit 0
+fi
+
+echo "Applying transformers patch ($PATCH) to $TARGET..."
+git apply --directory="$TARGET" "$PATCH"
+touch "$MARKER"
+echo "Patch applied."

package/src/cli.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env bun
+
+import { bold, cyan, dim, green, yellow } from "ansis";
+import { program } from "commander";
+import pkg from "../package.json" with { type: "json" };
+import { registerCheckUpdateCommand } from "./commands/check-update.ts";
+import { registerMcpxCommand } from "./commands/mcpx.ts";
+import { registerReindexCommand } from "./commands/reindex.ts";
+import { registerServeCommand } from "./commands/serve.ts";
+import { registerSkillCommand } from "./commands/skill.ts";
+import { registerUpgradeCommand } from "./commands/upgrade.ts";
+import type { BuildContextOptions } from "./context.ts";
+import { mountAsCommanderCommand } from "./mount/commander.ts";
+import { OPERATIONS } from "./operations/index.ts";
+import { logger } from "./output/logger.ts";
+import { maybeCheckForUpdate } from "./update/background.ts";
+
+program
+	.name("membot")
+	.description("Versioned context store with hybrid search for AI agents. Stdio + HTTP MCP server and CLI.")
+	.version(pkg.version)
+	.option("-c, --config <path>", "membot data dir (default ~/.membot)")
+	.option("-j, --json", "force JSON output")
+	.option("-v, --verbose", "verbose / debug logging")
+	.option("--no-color", "disable ANSI colors")
+	.option("--no-interactive", "force non-interactive mode (no spinners)");
+
+program.configureHelp({
+	styleTitle: (str) => bold(str),
+	styleCommandText: (str) => cyan(str),
+	styleSubcommandText: (str) => cyan(str),
+	styleOptionText: (str) => yellow(str),
+	styleArgumentText: (str) => green(str),
+	styleDescriptionText: (str) => dim(str),
+});
+
+const getContextOptions = (): BuildContextOptions => {
+	const opts = program.opts<{
+		config?: string;
+		json?: boolean;
+		verbose?: boolean;
+		color?: boolean;
+		interactive?: boolean;
+	}>();
+	return {
+		configFlag: opts.config,
+		json: opts.json,
+		verbose: opts.verbose,
+		noColor: opts.color === false,
+		noInteractive: opts.interactive === false,
+	};
+};
+
+for (const op of OPERATIONS) {
+	mountAsCommanderCommand(program, op, getContextOptions);
+}
+
+registerServeCommand(program);
+registerReindexCommand(program);
+registerMcpxCommand(program);
+registerSkillCommand(program);
+registerCheckUpdateCommand(program);
+registerUpgradeCommand(program);
+
+const updateNotice = maybeCheckForUpdate();
+
+program.parse();
+
+process.on("beforeExit", async () => {
+	const notice = await updateNotice;
+	if (notice) logger.writeRaw(notice);
+});

package/src/commands/check-update.ts

@@ -0,0 +1,69 @@
+import { cyan, dim, green, yellow } from "ansis";
+import type { Command } from "commander";
+import { createSpinner } from "nanospinner";
+import pkg from "../../package.json" with { type: "json" };
+import { saveUpdateCache } from "../update/cache.ts";
+import { checkForUpdate, type UpdateCache } from "../update/checker.ts";
+
+/**
+ * Register `membot check-update`. Performs a non-destructive npm-registry check,
+ * caches the result, and prints the current/latest version (plus changelog when an
+ * update is available). Emits raw `UpdateInfo` JSON when `--json` is set.
+ */
+export function registerCheckUpdateCommand(program: Command) {
+	program
+		.command("check-update")
+		.description("Check for a newer version of membot")
+		.action(async () => {
+			const opts = program.opts();
+			const json = !!(opts.json as boolean | undefined);
+			const isTTY = process.stderr.isTTY ?? false;
+
+			const spinner =
+				!json && isTTY ? createSpinner("Checking for updates...", { stream: process.stderr }).start() : null;
+
+			try {
+				const info = await checkForUpdate(pkg.version);
+
+				const cache: UpdateCache = {
+					lastCheckAt: new Date().toISOString(),
+					latestVersion: info.latestVersion,
+					hasUpdate: info.hasUpdate,
+					changelog: info.changelog,
+				};
+				await saveUpdateCache(cache);
+
+				spinner?.stop();
+
+				if (json) {
+					console.log(JSON.stringify(info, null, 2));
+					return;
+				}
+
+				if (!info.hasUpdate) {
+					if (info.aheadOfLatest) {
+						console.log(
+							yellow(`membot v${info.currentVersion} is ahead of latest published release (v${info.latestVersion})`),
+						);
+					} else {
+						console.log(green(`membot is up to date (v${info.currentVersion})`));
+					}
+					return;
+				}
+
+				console.log(yellow(`Update available: ${info.currentVersion} → ${info.latestVersion}`));
+
+				if (info.changelog) {
+					console.log("");
+					console.log(dim(info.changelog));
+				}
+
+				console.log("");
+				console.log(cyan("Run `membot upgrade` to update"));
+			} catch (err) {
+				spinner?.error({ text: "Failed to check for updates" });
+				console.error(String(err));
+				process.exit(1);
+			}
+		});
+}

package/src/commands/mcpx.ts

@@ -0,0 +1,112 @@
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import type { Command } from "commander";
+import { logger } from "../output/logger.ts";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Resolve the path to the bundled mcpx CLI entrypoint. We spawn it as a
+ * child process rather than calling its functions directly so that the
+ * upstream's argv parsing, output formatting, and config conventions stay
+ * authoritative — `membot mcpx <subcmd>` behaves identically to the user
+ * running `mcpx <subcmd>` themselves, just with our project's `--config`
+ * resolution layered on top when applicable.
+ */
+const MCPX_CLI = fileURLToPath(import.meta.resolve("@evantahler/mcpx/cli"));
+
+/**
+ * Forward an argv slice to the bundled mcpx CLI. Inherits stdio so prompts
+ * and pretty output flow through as if mcpx were called directly. Exits
+ * the parent process with the child's status code on failure.
+ */
+export async function runMcpx(args: string[]): Promise<void> {
+	const proc = Bun.spawn(["bun", MCPX_CLI, ...args], {
+		stdout: "inherit",
+		stderr: "inherit",
+		stdin: "inherit",
+	});
+	const code = await proc.exited;
+	if (code !== 0) process.exit(code);
+}
+
+/**
+ * Pull the verbatim argv tokens that follow `mcpx` in `process.argv`. We
+ * forward them unmodified so flags (`--help`, `-c`, etc.) reach the
+ * upstream CLI exactly as the user typed them.
+ */
+function getRawMcpxArgs(): string[] {
+	const idx = process.argv.indexOf("mcpx");
+	return idx === -1 ? [] : process.argv.slice(idx + 1);
+}
+
+const PASSTHROUGH_SUBCOMMANDS: ReadonlyArray<[name: string, desc: string]> = [
+	["servers", "List configured MCP server names"],
+	["info", "Show server overview or schema for a specific tool"],
+	["search", "Search tools by keyword and/or semantic similarity"],
+	["exec", "Execute a tool call"],
+	["add", "Add an MCP server"],
+	["remove", "Remove an MCP server"],
+	["ping", "Check connectivity to MCP servers"],
+	["auth", "Authenticate with an HTTP MCP server"],
+	["deauth", "Remove stored authentication for a server"],
+	["resource", "List resources for a server, or read a specific resource"],
+	["prompt", "List prompts for a server, or get a specific prompt"],
+	["task", "Manage async tool tasks (list, get, result, cancel)"],
+	["index", "Build the search index from all configured servers"],
+];
+
+/**
+ * Register `membot mcpx <subcommand>` for every passthrough subcommand on
+ * the upstream CLI. `--help` and unknown options are forwarded so users
+ * always get authoritative mcpx help text.
+ */
+export function registerMcpxCommand(program: Command): void {
+	const mcpx = program.command("mcpx").description("Forward to the bundled mcpx CLI for managing MCP servers");
+
+	const verifyVersion = (() => {
+		try {
+			const ourPkg = require("../../package.json") as { dependencies: Record<string, string> };
+			const mcpxPkg = require("@evantahler/mcpx/package.json") as { version: string };
+			const declared = ourPkg.dependencies["@evantahler/mcpx"];
+			if (!declared) return true;
+			return (
+				mcpxPkg.version === declared ||
+				declared.startsWith(mcpxPkg.version) ||
+				mcpxPkg.version.startsWith(declared.replace(/^[\^~]/, ""))
+			);
+		} catch {
+			return true;
+		}
+	})();
+	if (!verifyVersion) {
+		logger.warn("@evantahler/mcpx version mismatch — `membot mcpx` may behave unexpectedly.");
+	}
+
+	for (const [name, description] of PASSTHROUGH_SUBCOMMANDS) {
+		mcpx
+			.command(name)
+			.description(description)
+			.allowUnknownOption(true)
+			.helpOption(false)
+			.argument("[args...]", "arguments forwarded to mcpx")
+			.action(async () => {
+				await runMcpx(getRawMcpxArgs());
+			});
+	}
+
+	// Upstream mcpx's "list" is the default action when invoked with no
+	// subcommand — not a registered subcommand — so strip the "list" token
+	// before forwarding.
+	mcpx
+		.command("list")
+		.description("List all tools, resources, and prompts across all configured servers")
+		.allowUnknownOption(true)
+		.helpOption(false)
+		.argument("[args...]", "arguments forwarded to mcpx")
+		.action(async () => {
+			const raw = getRawMcpxArgs();
+			const args = raw[0] === "list" ? raw.slice(1) : raw;
+			await runMcpx(args);
+		});
+}

package/src/commands/reindex.ts

@@ -0,0 +1,53 @@
+import type { Command } from "commander";
+import { buildContext, closeContext } from "../context.ts";
+import { rebuildFts } from "../db/chunks.ts";
+import { logger } from "../output/logger.ts";
+
+/**
+ * `membot reindex`
+ *
+ * Rebuild the FTS index over `current_chunks`. Useful after manually
+ * editing the DB or upgrading after a schema change. Does NOT re-embed —
+ * embeddings are durable and are managed by the ingest/refresh pipelines.
+ */
+export function registerReindexCommand(program: Command): void {
+	program
+		.command("reindex")
+		.description("Rebuild the FTS keyword index over current chunks")
+		.action(async () => {
+			const ctx = await buildContext({});
+			try {
+				const result = await rebuildFts(ctx.db);
+				switch (result.kind) {
+					case "rebuilt":
+						logger.info(`reindex: FTS index rebuilt over ${result.chunk_count} chunks`);
+						console.log(JSON.stringify({ ok: true, chunk_count: result.chunk_count }));
+						break;
+					case "no_chunks":
+						logger.info("reindex: no chunks to index — run `membot add <path>` to ingest content first");
+						console.log(JSON.stringify({ ok: true, chunk_count: 0 }));
+						break;
+					case "extension_unavailable":
+						logger.warn(
+							`reindex: FTS extension unavailable — search will degrade to semantic-only${
+								result.cause ? ` (${result.cause})` : ""
+							}`,
+						);
+						console.log(
+							JSON.stringify({
+								ok: false,
+								reason: "fts_extension_unavailable",
+								cause: result.cause,
+							}),
+						);
+						break;
+					case "rebuild_failed":
+						logger.warn(`reindex: FTS rebuild failed${result.cause ? ` (${result.cause})` : ""}`);
+						console.log(JSON.stringify({ ok: false, reason: "rebuild_failed", cause: result.cause }));
+						break;
+				}
+			} finally {
+				await closeContext(ctx);
+			}
+		});
+}

package/src/commands/serve.ts

@@ -0,0 +1,58 @@
+import type { Command } from "commander";
+import { buildContext, closeContext } from "../context.ts";
+import { startStdioServer } from "../mcp/server.ts";
+import { logger } from "../output/logger.ts";
+import { startDaemon } from "../refresh/scheduler.ts";
+
+/**
+ * `membot serve [--http <port>] [--watch] [--tick <sec>]`
+ *
+ * Start the MCP server in stdio mode (default) or HTTP streamable mode
+ * (when `--http <port>` is given). Optionally also start the refresh
+ * daemon (`--watch`) which ticks every `--tick` seconds and refreshes
+ * any rows whose `refresh_frequency_sec` has elapsed.
+ */
+export function registerServeCommand(program: Command): void {
+	program
+		.command("serve")
+		.description("Run the MCP server (stdio default, --http for streamable HTTP) and optionally the refresh daemon")
+		.option("--http <port>", "expose MCP over HTTP on this port instead of stdio")
+		.option("--watch", "also run the refresh daemon (auto-refresh due rows)")
+		.option("--tick <sec>", "daemon tick interval in seconds (default 60)")
+		.action(async (options: { http?: string; watch?: boolean; tick?: string }) => {
+			const httpPort = options.http ? Number(options.http) : null;
+			let stopServer: (() => Promise<void>) | null = null;
+			let stopDaemon: (() => void) | null = null;
+
+			const onShutdown = async () => {
+				if (stopDaemon) stopDaemon();
+				if (stopServer) await stopServer();
+			};
+			process.on("SIGINT", () => {
+				logger.info("shutting down...");
+				onShutdown().finally(() => process.exit(0));
+			});
+			process.on("SIGTERM", () => {
+				onShutdown().finally(() => process.exit(0));
+			});
+
+			if (httpPort && !Number.isFinite(httpPort)) {
+				logger.error(`invalid --http port: ${options.http}`);
+				process.exit(2);
+			}
+
+			if (options.watch) {
+				const ctx = await buildContext({});
+				const tickSec = options.tick ? Number(options.tick) : ctx.config.daemon.tick_interval_sec;
+				stopDaemon = startDaemon(ctx, Number.isFinite(tickSec) && tickSec > 0 ? tickSec : 60);
+				process.on("beforeExit", () => closeContext(ctx));
+			}
+
+			if (httpPort) {
+				const { startHttpServer } = await import("../mcp/server.ts");
+				stopServer = await startHttpServer(httpPort);
+			} else {
+				stopServer = await startStdioServer();
+			}
+		});
+}

package/src/commands/skill.ts

@@ -0,0 +1,131 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import type { Command } from "commander";
+import claudeSkill from "../../.claude/skills/membot.md" with { type: "text" };
+import cursorRule from "../../.cursor/rules/membot.mdc" with { type: "text" };
+import { HelpfulError, isHelpfulError, mapKindToExit } from "../errors.ts";
+import { renderCliError } from "../mount/commander.ts";
+import { logger } from "../output/logger.ts";
+import { detectMode, setMode } from "../output/tty.ts";
+
+interface SkillTarget {
+	agentLabel: string;
+	scopeLabel: string;
+	dir: string;
+	filename: string;
+	content: string;
+}
+
+interface SkillInstallOptions {
+	claude?: boolean;
+	cursor?: boolean;
+	global?: boolean;
+	project?: boolean;
+	force?: boolean;
+}
+
+/**
+ * `membot skill install [--claude] [--cursor] [--global|--project] [-f]`
+ *
+ * Drop the membot agent skill into the right location for Claude Code
+ * (`.claude/skills/membot.md`) or Cursor (`.cursor/rules/membot.mdc`),
+ * either in the current project (default) or in the user's home directory
+ * (`--global`). Both flags can be combined to install for both targets at
+ * once. The skill files are bundled into the binary via Bun text imports
+ * so this works in the compiled distribution as well as in `bun run`.
+ */
+export function registerSkillCommand(program: Command): void {
+	const skill = program.command("skill").description("Install agent skills (Claude Code, Cursor)");
+
+	skill
+		.command("install")
+		.description(
+			"Install the membot skill into Claude Code (.claude/skills/membot.md) and/or Cursor (.cursor/rules/membot.mdc)",
+		)
+		.option("--claude", "install for Claude Code")
+		.option("--cursor", "install for Cursor")
+		.option("--global", "install to the user's home directory (default: project)")
+		.option("--project", "install to the current working directory (default)")
+		.option("-f, --force", "overwrite if the skill file already exists")
+		.action((opts: SkillInstallOptions) => {
+			const globalOpts = program.optsWithGlobals<{ json?: boolean; verbose?: boolean; color?: boolean }>();
+			setMode(
+				detectMode({
+					json: globalOpts.json,
+					verbose: globalOpts.verbose,
+					noColor: globalOpts.color === false,
+				}),
+			);
+			try {
+				install(opts);
+			} catch (err) {
+				renderCliError(err);
+				process.exit(isHelpfulError(err) ? mapKindToExit(err.kind) : 1);
+			}
+		});
+}
+
+/**
+ * Resolve and write every requested skill file. Throws `HelpfulError` on
+ * any input or conflict failure so the mount-style error renderer can
+ * surface a uniform JSON / colorized message.
+ */
+function install(opts: SkillInstallOptions): void {
+	if (!opts.claude && !opts.cursor) {
+		throw new HelpfulError({
+			kind: "input_error",
+			message: "no agent target specified",
+			hint: "Pass --claude, --cursor, or both — e.g. `membot skill install --claude`",
+		});
+	}
+
+	const targets = computeTargets(opts);
+	for (const target of targets) {
+		const dest = join(target.dir, target.filename);
+		if (existsSync(dest) && !opts.force) {
+			throw new HelpfulError({
+				kind: "conflict",
+				message: `${dest} already exists`,
+				hint: "Re-run with --force to overwrite",
+			});
+		}
+		mkdirSync(target.dir, { recursive: true });
+		writeFileSync(dest, target.content, "utf-8");
+		logger.info(`installed ${target.agentLabel} skill (${target.scopeLabel}): ${dest}`);
+	}
+}
+
+/**
+ * Materialise the (agent × scope) cartesian product of install targets the
+ * user asked for. Default scope is project when neither --global nor
+ * --project is passed; passing both installs to both locations.
+ */
+function computeTargets(opts: SkillInstallOptions): SkillTarget[] {
+	const scopes: { label: string; resolveDir: (rel: string) => string }[] = [];
+	if (opts.global) scopes.push({ label: "global", resolveDir: (rel) => join(homedir(), rel) });
+	if (opts.project || !opts.global) scopes.push({ label: "project", resolveDir: (rel) => resolve(rel) });
+
+	const targets: SkillTarget[] = [];
+	for (const scope of scopes) {
+		if (opts.claude) {
+			targets.push({
+				agentLabel: "Claude Code",
+				scopeLabel: scope.label,
+				dir: scope.resolveDir(".claude/skills"),
+				filename: "membot.md",
+				content: claudeSkill,
+			});
+		}
+		if (opts.cursor) {
+			targets.push({
+				agentLabel: "Cursor",
+				scopeLabel: scope.label,
+				dir: scope.resolveDir(".cursor/rules"),
+				filename: "membot.mdc",
+				content: cursorRule,
+			});
+		}
+	}
+	return targets;
+}