membot 0.0.1 → 0.1.0

package/src/commands/upgrade.ts

@@ -0,0 +1,220 @@
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { dim, green, red, yellow } from "ansis";
+import { $ } from "bun";
+import type { Command } from "commander";
+import { createSpinner } from "nanospinner";
+import pkg from "../../package.json" with { type: "json" };
+import { clearUpdateCache, loadUpdateCache, saveUpdateCache } from "../update/cache.ts";
+import {
+	checkForUpdate,
+	detectInstallMethod,
+	type InstallMethod,
+	needsCheck,
+	type UpdateCache,
+} from "../update/checker.ts";
+
+const GITHUB_REPO = pkg.repository.url.replace(/^https:\/\/github\.com\//, "").replace(/\.git$/, "");
+
+/** Build the platform-specific release artifact name (e.g. `membot-linux-x64`, `membot-windows-arm64.exe`). */
+function platformArtifactName(): string {
+	let os: string;
+	let ext = "";
+	switch (process.platform) {
+		case "darwin":
+			os = "darwin";
+			break;
+		case "win32":
+			os = "windows";
+			ext = ".exe";
+			break;
+		default:
+			os = "linux";
+			break;
+	}
+	const arch = process.arch === "arm64" ? "arm64" : "x64";
+	return `membot-${os}-${arch}${ext}`;
+}
+
+/** Run `bun install -g` or `npm install -g` and return whether it succeeded. */
+async function upgradeWithPackageManager(command: string, args: string[]): Promise<boolean> {
+	const result = await $`${command} ${args}`.nothrow();
+	return result.exitCode === 0;
+}
+
+/**
+ * Download the platform binary for `latestVersion` from GitHub releases and replace
+ * the running executable in place. Falls back to `sudo mv` if the target is non-writable.
+ */
+async function upgradeFromBinary(latestVersion: string): Promise<boolean> {
+	const artifact = platformArtifactName();
+	const tag = `v${latestVersion}`;
+	const url = `https://github.com/${GITHUB_REPO}/releases/download/${tag}/${artifact}`;
+
+	const tmpPath = join(tmpdir(), `membot-upgrade-${Date.now()}`);
+	const targetPath = process.execPath;
+
+	try {
+		const res = await fetch(url);
+		if (!res.ok) {
+			console.error(red(`Failed to download binary: HTTP ${res.status}`));
+			return false;
+		}
+
+		const bytes = await res.arrayBuffer();
+		await Bun.write(tmpPath, bytes);
+
+		await $`chmod +x ${tmpPath}`.quiet();
+
+		const mv = await $`mv ${tmpPath} ${targetPath}`.quiet().nothrow();
+
+		if (mv.exitCode !== 0) {
+			console.log(dim("Requires elevated permissions..."));
+			const sudo = await $`sudo mv ${tmpPath} ${targetPath}`.nothrow();
+			if (sudo.exitCode !== 0) {
+				console.error(red("Failed to install binary. Try running with sudo."));
+				return false;
+			}
+		}
+
+		return true;
+	} catch (err) {
+		console.error(red(`Failed to upgrade binary: ${err}`));
+		await $`rm -f ${tmpPath}`.quiet().nothrow();
+		return false;
+	}
+}
+
+/**
+ * Register `membot upgrade`. Detects the install method (npm/bun/binary/local-dev),
+ * uses cached update info if fresh, then performs the appropriate self-update.
+ * Emits structured JSON when `--json` is set.
+ */
+export function registerUpgradeCommand(program: Command) {
+	program
+		.command("upgrade")
+		.description("Upgrade membot to the latest version")
+		.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 cache = await loadUpdateCache();
+				let latestVersion: string;
+				let hasUpdate: boolean;
+
+				if (!needsCheck(cache) && cache) {
+					latestVersion = cache.latestVersion;
+					hasUpdate = cache.hasUpdate;
+				} else {
+					const info = await checkForUpdate(pkg.version);
+					latestVersion = info.latestVersion;
+					hasUpdate = info.hasUpdate;
+
+					const newCache: UpdateCache = {
+						lastCheckAt: new Date().toISOString(),
+						latestVersion,
+						hasUpdate,
+						changelog: info.changelog,
+					};
+					await saveUpdateCache(newCache);
+				}
+
+				if (!hasUpdate) {
+					spinner?.stop();
+					if (json) {
+						console.log(
+							JSON.stringify({
+								upgraded: false,
+								currentVersion: pkg.version,
+								message: "Already up to date",
+							}),
+						);
+					} else {
+						console.log(green(`membot is already up to date (v${pkg.version})`));
+					}
+					return;
+				}
+
+				const method: InstallMethod = detectInstallMethod();
+				spinner?.update({
+					text: `Upgrading from v${pkg.version} to v${latestVersion} (${method})...`,
+				});
+
+				let success = false;
+
+				switch (method) {
+					case "bun":
+						spinner?.stop();
+						success = await upgradeWithPackageManager("bun", ["install", "-g", `${pkg.name}@${latestVersion}`]);
+						break;
+
+					case "npm":
+						spinner?.stop();
+						success = await upgradeWithPackageManager("npm", ["install", "-g", `${pkg.name}@${latestVersion}`]);
+						break;
+
+					case "binary":
+						spinner?.stop();
+						success = await upgradeFromBinary(latestVersion);
+						break;
+
+					case "local-dev":
+						spinner?.stop();
+						if (json) {
+							console.log(
+								JSON.stringify({
+									upgraded: false,
+									currentVersion: pkg.version,
+									latestVersion,
+									installMethod: "local-dev",
+									message: "Running from source. Use `git pull && bun install` to update.",
+								}),
+							);
+						} else {
+							console.log(yellow("Running from source. Use `git pull && bun install` to update."));
+						}
+						return;
+				}
+
+				if (success) {
+					await clearUpdateCache();
+					if (json) {
+						console.log(
+							JSON.stringify({
+								upgraded: true,
+								previousVersion: pkg.version,
+								newVersion: latestVersion,
+								installMethod: method,
+							}),
+						);
+					} else {
+						console.log(green(`Successfully upgraded membot: v${pkg.version} → v${latestVersion}`));
+					}
+				} else {
+					if (json) {
+						console.log(
+							JSON.stringify({
+								upgraded: false,
+								currentVersion: pkg.version,
+								latestVersion,
+								installMethod: method,
+								message: "Upgrade failed",
+							}),
+						);
+					} else {
+						console.error(red("Upgrade failed. See errors above."));
+					}
+					process.exit(1);
+				}
+			} catch (err) {
+				spinner?.error({ text: "Upgrade failed" });
+				console.error(String(err));
+				process.exit(1);
+			}
+		});
+}

package/src/config/loader.ts

@@ -0,0 +1,100 @@
+import { mkdir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { defaultMembotHome, ENV, FILES } from "../constants.ts";
+import { asHelpful, HelpfulError } from "../errors.ts";
+import { type MembotConfig, MembotConfigSchema } from "./schemas.ts";
+
+export interface LoadConfigOptions {
+	configFlag?: string;
+}
+
+/**
+ * Resolve, read, and validate `~/.membot/config.json`. The directory is
+ * created if missing. Environment variables (ANTHROPIC_API_KEY) take
+ * precedence over the on-disk values for sensitive fields.
+ */
+export async function loadConfig(options: LoadConfigOptions = {}): Promise<{
+	config: MembotConfig;
+	dataDir: string;
+	configPath: string;
+}> {
+	const dataDir = resolveDataDir(options.configFlag);
+	await mkdir(dataDir, { recursive: true });
+
+	const configPath = resolve(dataDir, FILES.CONFIG_JSON);
+	let raw: unknown = {};
+	const file = Bun.file(configPath);
+	if (await file.exists()) {
+		try {
+			raw = JSON.parse(await file.text());
+		} catch (err) {
+			throw asHelpful(
+				err,
+				`while parsing ${configPath}`,
+				`Fix the JSON in ${configPath}, or delete it to regenerate defaults.`,
+				"input_error",
+			);
+		}
+	}
+
+	let config: MembotConfig;
+	try {
+		config = MembotConfigSchema.parse(raw);
+	} catch (err) {
+		throw asHelpful(
+			err,
+			`while validating ${configPath}`,
+			`Check ${configPath} against the documented schema, or delete it to regenerate defaults.`,
+			"input_error",
+		);
+	}
+
+	const envKey = process.env[ENV.ANTHROPIC_API_KEY];
+	if (envKey?.trim()) {
+		config = { ...config, llm: { ...config.llm, anthropic_api_key: envKey } };
+	}
+
+	if (config.data_dir !== dataDir) {
+		config = { ...config, data_dir: dataDir };
+	}
+
+	return { config, dataDir, configPath };
+}
+
+/**
+ * Pick the membot data directory. Precedence: explicit `--config` flag,
+ * then `MEMBOT_HOME` env var, then `~/.membot`. The chosen path is later
+ * created (recursive mkdir) and stamped back into `config.data_dir`.
+ */
+function resolveDataDir(flag?: string): string {
+	if (flag?.trim()) return resolve(flag);
+	const env = process.env[ENV.HOME];
+	if (env?.trim()) return resolve(env);
+	return defaultMembotHome();
+}
+
+/**
+ * Persist config to disk, with the Anthropic API key blanked out — the env
+ * var (`ANTHROPIC_API_KEY`) is the source of truth, never the file. Writing
+ * the key to disk would land it in shell history, dotfile syncs, and
+ * accidental commits.
+ */
+export async function saveConfig(configPath: string, config: MembotConfig): Promise<void> {
+	const safe: MembotConfig = {
+		...config,
+		llm: { ...config.llm, anthropic_api_key: "" },
+	};
+	await Bun.write(configPath, `${JSON.stringify(safe, null, 2)}\n`);
+}
+
+/**
+ * Tree-shaking guard. Not called at runtime — its presence keeps the module
+ * from being eliminated by aggressive bundlers when only types are imported.
+ */
+export function _ensureExportedSentinel(): never {
+	throw new HelpfulError({
+		kind: "internal_error",
+		message: "sentinel called",
+		hint: "This function exists only for tree-shaking sanity checks.",
+	});
+}

package/src/config/schemas.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { DEFAULTS, defaultMembotHome, EMBEDDING_DIMENSION, EMBEDDING_MODEL } from "../constants.ts";
+
+export const ChunkerConfigSchema = z.object({
+	mode: z.enum(["deterministic", "llm"]).default(DEFAULTS.CHUNKER_MODE),
+	target_chars: z.number().int().positive().default(DEFAULTS.CHUNKER_TARGET_CHARS),
+	max_chars: z.number().int().positive().default(DEFAULTS.CHUNKER_MAX_CHARS),
+});
+
+export const LlmConfigSchema = z.object({
+	anthropic_api_key: z.string().default(""),
+	converter_model: z.string().default(DEFAULTS.CONVERTER_MODEL),
+	chunker_model: z.string().default(DEFAULTS.CHUNKER_MODEL),
+	describer_model: z.string().default(DEFAULTS.DESCRIBER_MODEL),
+	vision_model: z.string().default(DEFAULTS.VISION_MODEL),
+});
+
+export const McpxConfigSchema = z.object({
+	config_path: z.string().default(""),
+});
+
+export const DaemonConfigSchema = z.object({
+	tick_interval_sec: z.number().int().positive().default(DEFAULTS.DAEMON_TICK_SEC),
+});
+
+export const MembotConfigSchema = z.object({
+	data_dir: z.string().default(defaultMembotHome()),
+	embedding_model: z.string().default(EMBEDDING_MODEL),
+	embedding_dimension: z.number().int().positive().default(EMBEDDING_DIMENSION),
+	chunker: ChunkerConfigSchema.default(() => ChunkerConfigSchema.parse({})),
+	llm: LlmConfigSchema.default(() => LlmConfigSchema.parse({})),
+	mcpx: McpxConfigSchema.default(() => McpxConfigSchema.parse({})),
+	daemon: DaemonConfigSchema.default(() => DaemonConfigSchema.parse({})),
+	default_refresh_frequency_sec: z.number().int().positive().nullable().default(null),
+});
+
+export type MembotConfig = z.infer<typeof MembotConfigSchema>;
+export type ChunkerConfig = z.infer<typeof ChunkerConfigSchema>;
+export type LlmConfig = z.infer<typeof LlmConfigSchema>;

package/src/constants.ts

@@ -0,0 +1,42 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Default data directory: `~/.membot`. Override via $MEMBOT_HOME or `--config`. */
+export function defaultMembotHome(): string {
+	const env = process.env.MEMBOT_HOME;
+	if (env?.trim()) return env;
+	return join(homedir(), ".membot");
+}
+
+export const ENV = {
+	HOME: "MEMBOT_HOME",
+	CONFIG: "MEMBOT_CONFIG",
+	DEBUG: "MEMBOT_DEBUG",
+	ANTHROPIC_API_KEY: "ANTHROPIC_API_KEY",
+	MCPX_CONFIG_PATH: "MCP_CONFIG_PATH",
+	NO_UPDATE_CHECK: "MEMBOT_NO_UPDATE_CHECK",
+} as const;
+
+export const EMBEDDING_MODEL = "Xenova/bge-small-en-v1.5";
+export const EMBEDDING_DIMENSION = 384;
+
+export const DEFAULTS = {
+	CHUNKER_MODE: "deterministic" as const,
+	CHUNKER_TARGET_CHARS: 4_000,
+	CHUNKER_MAX_CHARS: 15_000,
+	DAEMON_TICK_SEC: 60,
+	HTTP_TIMEOUT_MS: 30_000,
+	CONVERTER_MODEL: "claude-haiku-4-5-20251001",
+	CHUNKER_MODEL: "claude-haiku-4-5-20251001",
+	DESCRIBER_MODEL: "claude-haiku-4-5-20251001",
+	VISION_MODEL: "claude-haiku-4-5-20251001",
+	UPDATE_CHECK_INTERVAL_MS: 24 * 60 * 60 * 1000,
+	UPDATE_CHECK_TIMEOUT_MS: 5_000,
+} as const;
+
+export const FILES = {
+	CONFIG_JSON: "config.json",
+	INDEX_DUCKDB: "index.duckdb",
+	MODELS_DIR: "models",
+	LOGS_DIR: "logs",
+} as const;

package/src/context.ts

@@ -0,0 +1,80 @@
+import { join } from "node:path";
+import { McpxClient } from "@evantahler/mcpx";
+import { loadConfig } from "./config/loader.ts";
+import type { MembotConfig } from "./config/schemas.ts";
+import { ENV, FILES } from "./constants.ts";
+import { type DbConnection, openDb } from "./db/connection.ts";
+import { logger } from "./output/logger.ts";
+import type { Progress } from "./output/progress.ts";
+import { createProgress } from "./output/progress.ts";
+import { detectMode, setMode } from "./output/tty.ts";
+
+export interface AppContext {
+	config: MembotConfig;
+	dataDir: string;
+	configPath: string;
+	db: DbConnection;
+	logger: typeof logger;
+	progress: Progress;
+	mcpx: McpxClient | null;
+}
+
+export interface BuildContextOptions {
+	configFlag?: string;
+	json?: boolean;
+	verbose?: boolean;
+	noColor?: boolean;
+	noInteractive?: boolean;
+}
+
+/**
+ * Build the AppContext used by every operation handler. Initializes:
+ *  - output mode (TTY/JSON/color detection — frozen for the rest of the run)
+ *  - config (~/.membot/config.json with env overrides)
+ *  - DuckDB connection (~/.membot/index.duckdb), running migrations on first open
+ *  - mcpx client (lazy — opened on first remote fetch; null when no servers)
+ */
+export async function buildContext(options: BuildContextOptions = {}): Promise<AppContext> {
+	setMode(detectMode({ json: options.json, verbose: options.verbose, noColor: options.noColor }));
+
+	const { config, dataDir, configPath } = await loadConfig({ configFlag: options.configFlag });
+	const dbPath = join(dataDir, FILES.INDEX_DUCKDB);
+	const db = await openDb(dbPath);
+
+	const mcpx = await maybeMcpx(config);
+
+	return {
+		config,
+		dataDir,
+		configPath,
+		db,
+		logger,
+		progress: createProgress(),
+		mcpx,
+	};
+}
+
+async function maybeMcpx(config: MembotConfig): Promise<McpxClient | null> {
+	const configDir = config.mcpx.config_path || process.env[ENV.MCPX_CONFIG_PATH];
+	try {
+		const client = new McpxClient(configDir ? { configDir } : {});
+		return client;
+	} catch {
+		return null;
+	}
+}
+
+export async function closeContext(ctx: AppContext): Promise<void> {
+	try {
+		await ctx.db.close();
+	} catch {
+		// best effort
+	}
+	if (ctx.mcpx) {
+		try {
+			await ctx.mcpx.close();
+		} catch {
+			// best effort
+		}
+	}
+}

package/src/db/blobs.ts

@@ -0,0 +1,53 @@
+import type { DbConnection } from "./connection.ts";
+
+export interface BlobRow {
+	sha256: string;
+	mime_type: string;
+	size_bytes: number;
+	bytes: Uint8Array;
+}
+
+/**
+ * Insert a content-addressed blob, doing nothing when the sha256 already
+ * exists. Uses an explicit `?::BLOB` cast because DuckDB can't infer the
+ * column type from a JS Uint8Array on its own.
+ */
+export async function upsertBlob(db: DbConnection, blob: BlobRow): Promise<void> {
+	await db.queryRun(
+		`INSERT INTO blobs (sha256, mime_type, size_bytes, bytes)
+		 VALUES (?1, ?2, ?3, ?4::BLOB)
+		 ON CONFLICT (sha256) DO NOTHING`,
+		blob.sha256,
+		blob.mime_type,
+		blob.size_bytes,
+		blob.bytes,
+	);
+}
+
+/** Fetch a blob by sha256, or null. Used when serving `membot_read bytes=true`. */
+export async function readBlob(db: DbConnection, sha256: string): Promise<BlobRow | null> {
+	const row = await db.queryGet<{
+		sha256: string;
+		mime_type: string;
+		size_bytes: number;
+		bytes: Uint8Array;
+	}>(`SELECT sha256, mime_type, size_bytes, bytes FROM blobs WHERE sha256 = ?1`, sha256);
+	if (!row) return null;
+	return {
+		sha256: row.sha256,
+		mime_type: row.mime_type,
+		size_bytes: Number(row.size_bytes),
+		bytes: row.bytes,
+	};
+}
+
+/** Drop blobs whose sha256 isn't referenced by any non-tombstone file row. */
+export async function gcOrphanBlobs(db: DbConnection): Promise<{ removed: number }> {
+	const result = await db.queryRun(
+		`DELETE FROM blobs
+		 WHERE sha256 NOT IN (
+			SELECT DISTINCT blob_sha256 FROM files WHERE blob_sha256 IS NOT NULL
+		 )`,
+	);
+	return { removed: result.changes };
+}