membot 0.0.1 → 0.1.1

package/src/operations/diff.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { getCurrent, getVersion } from "../db/files.ts";
+import { HelpfulError } from "../errors.ts";
+import { colors } from "../output/formatter.ts";
+import { defineOperation } from "./types.ts";
+
+export const diffOperation = defineOperation({
+	name: "membot_diff",
+	cliName: "diff",
+	description: `Return a unified diff between two versions of a file. \`a\` is required; \`b\` defaults to the current version. Both \`a\` and \`b\` are version_id timestamps from membot_versions. Use to understand what a refresh actually changed before deciding to act on the new content.`,
+	inputSchema: z.object({
+		logical_path: z.string().describe("Path of the file"),
+		a: z.string().describe("Older version_id"),
+		b: z.string().optional().describe("Newer version_id; default current"),
+	}),
+	outputSchema: z.object({
+		logical_path: z.string(),
+		a: z.string(),
+		b: z.string(),
+		diff: z.string(),
+	}),
+	cli: { positional: ["logical_path", "a", "b"] },
+	console_formatter: (result) => {
+		const header = `${colors.bold(result.logical_path)} ${colors.dim(`${result.a} → ${result.b}`)}`;
+		if (!result.diff.trim()) return `${header}\n${colors.dim("(no changes)")}`;
+		const body = result.diff
+			.split("\n")
+			.map((line) => {
+				if (line.startsWith("---") || line.startsWith("+++") || line.startsWith("@@")) return colors.cyan(line);
+				if (line.startsWith("+")) return colors.green(line);
+				if (line.startsWith("-")) return colors.red(line);
+				return line;
+			})
+			.join("\n");
+		return `${header}\n${body}`;
+	},
+	handler: async (input, ctx) => {
+		const aRow = await getVersion(ctx.db, input.logical_path, input.a);
+		const bRow = input.b
+			? await getVersion(ctx.db, input.logical_path, input.b)
+			: await getCurrent(ctx.db, input.logical_path);
+		if (!aRow || !bRow) {
+			throw new HelpfulError({
+				kind: "not_found",
+				message: `couldn't load both versions for diff (${aRow ? "" : "a missing"} ${bRow ? "" : "b missing"})`.trim(),
+				hint: `Run \`membot versions ${input.logical_path}\` to list valid version_ids.`,
+			});
+		}
+		const diff = unifiedDiff(aRow.content ?? "", bRow.content ?? "", input.a, bRow.version_id);
+		return { logical_path: input.logical_path, a: aRow.version_id, b: bRow.version_id, diff };
+	},
+});
+
+/**
+ * Produce a minimal unified diff between two strings using a simple LCS
+ * algorithm. We don't pull in a diff library because the volumes are small
+ * and the output format is a stable convenience for humans/agents reading
+ * what changed across versions.
+ */
+function unifiedDiff(a: string, b: string, aLabel: string, bLabel: string): string {
+	const aLines = a.split("\n");
+	const bLines = b.split("\n");
+	const out: string[] = [`--- ${aLabel}`, `+++ ${bLabel}`];
+
+	// Simple line-by-line walk using LCS.
+	const lcs = lcsTable(aLines, bLines);
+	let i = 0;
+	let j = 0;
+	const ops: { kind: "=" | "-" | "+"; line: string }[] = [];
+	while (i < aLines.length && j < bLines.length) {
+		if (aLines[i] === bLines[j]) {
+			ops.push({ kind: "=", line: aLines[i]! });
+			i++;
+			j++;
+		} else if ((lcs[i + 1]?.[j] ?? 0) >= (lcs[i]?.[j + 1] ?? 0)) {
+			ops.push({ kind: "-", line: aLines[i]! });
+			i++;
+		} else {
+			ops.push({ kind: "+", line: bLines[j]! });
+			j++;
+		}
+	}
+	while (i < aLines.length) ops.push({ kind: "-", line: aLines[i++]! });
+	while (j < bLines.length) ops.push({ kind: "+", line: bLines[j++]! });
+
+	for (const op of ops) {
+		out.push(`${op.kind === "=" ? " " : op.kind}${op.line}`);
+	}
+	return out.join("\n");
+}
+
+/** Build the LCS dynamic-programming table for two arrays. */
+function lcsTable(a: string[], b: string[]): number[][] {
+	const m = a.length;
+	const n = b.length;
+	const t: number[][] = Array.from({ length: m + 1 }, () => new Array<number>(n + 1).fill(0));
+	for (let i = m - 1; i >= 0; i--) {
+		const ti = t[i]!;
+		const tin = t[i + 1]!;
+		for (let j = n - 1; j >= 0; j--) {
+			ti[j] = a[i] === b[j] ? (tin[j + 1] ?? 0) + 1 : Math.max(tin[j] ?? 0, ti[j + 1] ?? 0);
+		}
+	}
+	return t;
+}

package/src/operations/index.ts

@@ -0,0 +1,38 @@
+import { addOperation } from "./add.ts";
+import { diffOperation } from "./diff.ts";
+import { infoOperation } from "./info.ts";
+import { listOperation } from "./list.ts";
+import { moveOperation } from "./move.ts";
+import { pruneOperation } from "./prune.ts";
+import { readOperation } from "./read.ts";
+import { refreshOperation } from "./refresh.ts";
+import { removeOperation } from "./remove.ts";
+import { searchOperation } from "./search.ts";
+import { treeOperation } from "./tree.ts";
+import type { Operation } from "./types.ts";
+import { versionsOperation } from "./versions.ts";
+import { writeOperation } from "./write.ts";
+
+/**
+ * Ordered registry of every Operation. The CLI and the MCP server both
+ * iterate this list and call the appropriate mount adapter, so a new tool
+ * is added by writing one file under `operations/` and appending it here.
+ *
+ * Order influences `--help` output and MCP `tools/list` ordering.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: heterogenous Operation generics — registry stays open-ended on purpose
+export const OPERATIONS: Operation<any, any>[] = [
+	addOperation,
+	listOperation,
+	treeOperation,
+	readOperation,
+	searchOperation,
+	infoOperation,
+	versionsOperation,
+	diffOperation,
+	writeOperation,
+	moveOperation,
+	removeOperation,
+	refreshOperation,
+	pruneOperation,
+];

package/src/operations/info.ts

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { getCurrent, getVersion } from "../db/files.ts";
+import { HelpfulError } from "../errors.ts";
+import { colors } from "../output/formatter.ts";
+import { defineOperation } from "./types.ts";
+
+export const infoOperation = defineOperation({
+	name: "membot_info",
+	cliName: "info",
+	description: `Inspect metadata for a file: source (local path or URL), fetcher used, refresh schedule, last refresh status, all sha256 digests, and whether the requested version is the current one. Does NOT return file content — use membot_read for that. Use this to decide whether a refresh is worth forcing or whether to trust a cached row.`,
+	inputSchema: z.object({
+		logical_path: z.string().describe("Path to inspect"),
+		version: z.string().optional().describe("Specific version_id; default current"),
+	}),
+	outputSchema: z.object({
+		logical_path: z.string(),
+		version_id: z.string(),
+		version_is_current: z.boolean(),
+		source_type: z.string(),
+		source_path: z.string().nullable(),
+		source_sha256: z.string().nullable(),
+		blob_sha256: z.string().nullable(),
+		content_sha256: z.string().nullable(),
+		mime_type: z.string().nullable(),
+		size_bytes: z.number().nullable(),
+		description: z.string().nullable(),
+		fetcher: z.string().nullable(),
+		fetcher_server: z.string().nullable(),
+		fetcher_tool: z.string().nullable(),
+		fetcher_args: z.record(z.string(), z.unknown()).nullable(),
+		refresh_frequency_sec: z.number().nullable(),
+		refreshed_at: z.string().nullable(),
+		last_refresh_status: z.string().nullable(),
+		change_note: z.string().nullable(),
+		created_at: z.string(),
+		tombstone: z.boolean(),
+	}),
+	cli: { positional: ["logical_path"] },
+	console_formatter: (result) => {
+		const fmt = (k: string, v: string): string => `${colors.dim(k.padEnd(22))}${v}`;
+		const yn = (b: boolean): string => (b ? colors.green("yes") : colors.dim("no"));
+		const orDash = (s: string | null): string => s ?? colors.dim("-");
+		const lines: string[] = [];
+		const head = `${colors.cyan(result.logical_path)} ${colors.dim(`@ ${result.version_id}`)}`;
+		lines.push(result.tombstone ? `${head} ${colors.red("[tombstoned]")}` : head);
+		lines.push(fmt("current", yn(result.version_is_current)));
+		lines.push(fmt("source_type", orDash(result.source_type)));
+		lines.push(fmt("source_path", orDash(result.source_path)));
+		lines.push(fmt("mime_type", orDash(result.mime_type)));
+		lines.push(fmt("size_bytes", result.size_bytes !== null ? String(result.size_bytes) : colors.dim("-")));
+		lines.push(fmt("description", orDash(result.description)));
+		lines.push(fmt("content_sha256", orDash(result.content_sha256)));
+		lines.push(fmt("blob_sha256", orDash(result.blob_sha256)));
+		lines.push(fmt("source_sha256", orDash(result.source_sha256)));
+		if (result.fetcher) lines.push(fmt("fetcher", result.fetcher));
+		if (result.fetcher_server) lines.push(fmt("fetcher_server", result.fetcher_server));
+		if (result.fetcher_tool) lines.push(fmt("fetcher_tool", result.fetcher_tool));
+		if (result.fetcher_args) lines.push(fmt("fetcher_args", JSON.stringify(result.fetcher_args)));
+		lines.push(
+			fmt(
+				"refresh_frequency",
+				result.refresh_frequency_sec !== null ? `${result.refresh_frequency_sec}s` : colors.dim("-"),
+			),
+		);
+		lines.push(fmt("refreshed_at", orDash(result.refreshed_at)));
+		lines.push(
+			fmt(
+				"last_refresh_status",
+				result.last_refresh_status === "failed"
+					? colors.red(result.last_refresh_status)
+					: result.last_refresh_status === "ok" || result.last_refresh_status === "fresh"
+						? colors.green(result.last_refresh_status)
+						: orDash(result.last_refresh_status),
+			),
+		);
+		if (result.change_note) lines.push(fmt("change_note", result.change_note));
+		lines.push(fmt("created_at", result.created_at));
+		return lines.join("\n");
+	},
+	handler: async (input, ctx) => {
+		const cur = await getCurrent(ctx.db, input.logical_path);
+		const row = input.version ? await getVersion(ctx.db, input.logical_path, input.version) : cur;
+		if (!row) {
+			throw new HelpfulError({
+				kind: "not_found",
+				message: `no version of ${input.logical_path}${input.version ? ` at ${input.version}` : ""}`,
+				hint: `Run \`membot versions ${input.logical_path}\` to list versions, or \`membot ls\` for paths.`,
+			});
+		}
+		return {
+			...row,
+			version_is_current: !!cur && cur.version_id === row.version_id,
+		};
+	},
+});

package/src/operations/list.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { listCurrent } from "../db/files.ts";
+import { colors, renderTable } from "../output/formatter.ts";
+import { defineOperation } from "./types.ts";
+
+export const listOperation = defineOperation({
+	name: "membot_list",
+	cliName: "ls",
+	bashEquivalent: "ls",
+	description: `List current files under an optional prefix, with size, mime type, refresh frequency, and last refresh status. Returns one row per logical_path (current version only). Pair with membot_tree for shape, membot_search for content-based discovery.`,
+	inputSchema: z.object({
+		prefix: z.string().optional().describe("Only show paths starting with this prefix"),
+		limit: z.number().default(1000).describe("Max rows to return"),
+		offset: z.number().default(0).describe("Skip this many rows (paginate)"),
+	}),
+	outputSchema: z.object({
+		entries: z.array(
+			z.object({
+				logical_path: z.string(),
+				version_id: z.string(),
+				size_bytes: z.number().nullable(),
+				mime_type: z.string().nullable(),
+				refresh_frequency_sec: z.number().nullable(),
+				last_refresh_status: z.string().nullable(),
+				refreshed_at: z.string().nullable(),
+				description: z.string().nullable(),
+			}),
+		),
+		count: z.number(),
+	}),
+	cli: { positional: ["prefix"] },
+	console_formatter: (result) => {
+		if (result.entries.length === 0) return colors.dim("(no entries)");
+		const rows = result.entries.map((e) => [
+			e.logical_path,
+			e.size_bytes !== null ? formatSize(e.size_bytes) : "-",
+			e.mime_type ?? "-",
+			e.last_refresh_status ?? "-",
+		]);
+		const table = renderTable(["PATH", "SIZE", "MIME", "STATUS"], rows, {
+			columnStyles: [colors.cyan, colors.dim, colors.dim, statusStyle],
+		});
+		return `${table}\n${colors.dim(`${result.count} ${result.count === 1 ? "entry" : "entries"}`)}`;
+	},
+	handler: async (input, ctx) => {
+		const rows = await listCurrent(ctx.db, {
+			prefix: input.prefix,
+			limit: input.limit,
+			offset: input.offset,
+		});
+		return {
+			entries: rows.map((r) => ({
+				logical_path: r.logical_path,
+				version_id: r.version_id,
+				size_bytes: r.size_bytes,
+				mime_type: r.mime_type,
+				refresh_frequency_sec: r.refresh_frequency_sec,
+				last_refresh_status: r.last_refresh_status,
+				refreshed_at: r.refreshed_at,
+				description: r.description,
+			})),
+			count: rows.length,
+		};
+	},
+});
+
+/** Map refresh status → semantic color. `failed` red, `stale`/`partial` yellow, `ok` green, anything else plain. */
+function statusStyle(s: string): string {
+	const trimmed = s.trim();
+	if (trimmed === "failed" || trimmed === "error") return colors.red(s);
+	if (trimmed === "stale" || trimmed === "partial") return colors.yellow(s);
+	if (trimmed === "ok" || trimmed === "fresh") return colors.green(s);
+	return s;
+}
+
+/** Format a byte count in human units. 1024 boundary, two-digit precision past KB. */
+function formatSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes}B`;
+	const units = ["KB", "MB", "GB", "TB"];
+	let i = -1;
+	let n = bytes;
+	while (n >= 1024 && i < units.length - 1) {
+		n /= 1024;
+		i++;
+	}
+	return `${n.toFixed(n >= 100 ? 0 : 1)}${units[i]}`;
+}

package/src/operations/move.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { insertChunksForVersion, listChunksForVersion, rebuildFts } from "../db/chunks.ts";
+import { getCurrent, insertVersion, millisIso, tombstone } from "../db/files.ts";
+import { HelpfulError } from "../errors.ts";
+import { buildSearchText } from "../ingest/search-text.ts";
+import { colors } from "../output/formatter.ts";
+import { defineOperation } from "./types.ts";
+
+export const moveOperation = defineOperation({
+	name: "membot_move",
+	cliName: "mv",
+	bashEquivalent: "mv",
+	description: `Rename a logical_path. Creates one new version under the new path with full content carried over and tombstones the old path. History remains queryable under both names via membot_versions.`,
+	inputSchema: z.object({
+		from_logical_path: z.string().describe("Source path"),
+		to_logical_path: z.string().describe("Destination path"),
+	}),
+	outputSchema: z.object({
+		from_logical_path: z.string(),
+		to_logical_path: z.string(),
+		new_version_id: z.string(),
+	}),
+	cli: { positional: ["from_logical_path", "to_logical_path"] },
+	console_formatter: (result) =>
+		`${colors.green("✓")} ${colors.cyan(result.from_logical_path)} → ${colors.cyan(result.to_logical_path)} ${colors.dim(`@ ${result.new_version_id}`)}`,
+	handler: async (input, ctx) => {
+		const cur = await getCurrent(ctx.db, input.from_logical_path);
+		if (!cur) {
+			throw new HelpfulError({
+				kind: "not_found",
+				message: `${input.from_logical_path} doesn't exist (or is tombstoned)`,
+				hint: "Run `membot ls` to see paths.",
+			});
+		}
+		if (await getCurrent(ctx.db, input.to_logical_path)) {
+			throw new HelpfulError({
+				kind: "conflict",
+				message: `${input.to_logical_path} already has a current version`,
+				hint: "Pick a different destination or `membot rm` the existing one first.",
+			});
+		}
+		const newVersion = millisIso(Date.now());
+		await insertVersion(ctx.db, {
+			logical_path: input.to_logical_path,
+			version_id: newVersion,
+			source_type: cur.source_type,
+			source_path: cur.source_path,
+			source_mtime_ms: cur.source_mtime_ms,
+			source_sha256: cur.source_sha256,
+			blob_sha256: cur.blob_sha256,
+			content_sha256: cur.content_sha256,
+			content: cur.content,
+			description: cur.description,
+			mime_type: cur.mime_type,
+			size_bytes: cur.size_bytes,
+			fetcher: cur.fetcher,
+			fetcher_server: cur.fetcher_server,
+			fetcher_tool: cur.fetcher_tool,
+			fetcher_args: cur.fetcher_args,
+			refresh_frequency_sec: cur.refresh_frequency_sec,
+			refreshed_at: cur.refreshed_at,
+			last_refresh_status: cur.last_refresh_status,
+			change_note: `move from ${input.from_logical_path}`,
+		});
+
+		const oldChunks = await listChunksForVersion(ctx.db, cur.logical_path, cur.version_id);
+		const reKeyed = oldChunks.map((c) => ({
+			chunk_index: c.chunk_index,
+			chunk_content: c.chunk_content,
+			search_text: buildSearchText(input.to_logical_path, cur.description, c.chunk_content),
+			embedding: c.embedding,
+		}));
+		await insertChunksForVersion(ctx.db, input.to_logical_path, newVersion, reKeyed);
+		await tombstone(ctx.db, input.from_logical_path, `moved to ${input.to_logical_path}`);
+		await rebuildFts(ctx.db);
+
+		return {
+			from_logical_path: input.from_logical_path,
+			to_logical_path: input.to_logical_path,
+			new_version_id: newVersion,
+		};
+	},
+});

package/src/operations/prune.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { gcOrphanBlobs } from "../db/blobs.ts";
+import { pruneOldVersions } from "../db/files.ts";
+import { HelpfulError } from "../errors.ts";
+import { colors } from "../output/formatter.ts";
+import { defineOperation } from "./types.ts";
+
+export const pruneOperation = defineOperation({
+	name: "membot_prune",
+	cliName: "prune",
+	description: `Permanently drop non-current versions older than the cutoff and garbage-collect orphan blobs. Current versions and tombstones-with-no-newer-version are preserved. Use sparingly — pruned versions cannot be recovered.`,
+	inputSchema: z.object({
+		before: z
+			.string()
+			.describe("Duration (e.g. 30d, 7d) or absolute ISO timestamp — versions strictly older are dropped"),
+		dry_run: z.boolean().default(true).describe("Report what would be removed without changing the DB"),
+	}),
+	outputSchema: z.object({
+		cutoff: z.string(),
+		removed_versions: z.number(),
+		removed_orphan_blobs: z.number(),
+		dry_run: z.boolean(),
+	}),
+	cli: { positional: ["before"] },
+	console_formatter: (result) => {
+		const tag = result.dry_run ? colors.yellow("[dry-run]") : colors.green("[applied]");
+		const head = `${tag} cutoff ${colors.cyan(result.cutoff)}`;
+		const versions = `${colors.yellow(`${result.removed_versions} version${result.removed_versions === 1 ? "" : "s"}`)} would be dropped`;
+		const blobs = result.dry_run
+			? colors.dim("(orphan blob count not computed in dry-run)")
+			: `${colors.yellow(`${result.removed_orphan_blobs} orphan blob${result.removed_orphan_blobs === 1 ? "" : "s"}`)} reclaimed`;
+		return `${head}\n${versions}\n${blobs}`;
+	},
+	handler: async (input, ctx) => {
+		const cutoff = resolveCutoff(input.before);
+		if (input.dry_run) {
+			const cnt =
+				(
+					await ctx.db.queryGet<{ n: number }>(
+						`SELECT COUNT(*) AS n FROM files
+				 WHERE version_id < CAST(?1 AS TIMESTAMP)
+				   AND (logical_path, version_id) NOT IN (
+				     SELECT logical_path, MAX(version_id) FROM files GROUP BY logical_path
+				   )`,
+						cutoff,
+					)
+				)?.n ?? 0;
+			return { cutoff, removed_versions: Number(cnt), removed_orphan_blobs: 0, dry_run: true };
+		}
+		const removed = await pruneOldVersions(ctx.db, cutoff);
+		const orphans = await gcOrphanBlobs(ctx.db);
+		return {
+			cutoff,
+			removed_versions: removed.removed,
+			removed_orphan_blobs: orphans.removed,
+			dry_run: false,
+		};
+	},
+});
+
+/** Convert a duration string or ISO timestamp into an ISO cutoff. */
+function resolveCutoff(input: string): string {
+	const trimmed = input.trim();
+	const m = trimmed.match(/^(\d+)([smhd])$/i);
+	if (m) {
+		const n = Number(m[1]);
+		const unit = m[2]?.toLowerCase() ?? "s";
+		const sec = unit === "s" ? 1 : unit === "m" ? 60 : unit === "h" ? 3600 : 86400;
+		return new Date(Date.now() - n * sec * 1000).toISOString();
+	}
+	const parsed = Date.parse(trimmed);
+	if (Number.isNaN(parsed)) {
+		throw new HelpfulError({
+			kind: "input_error",
+			message: `invalid --before: ${input}`,
+			hint: "Use a duration like 30d, or an ISO-8601 timestamp like 2024-01-01T00:00:00Z.",
+		});
+	}
+	return new Date(parsed).toISOString();
+}

package/src/operations/read.ts

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { readBlob } from "../db/blobs.ts";
+import { getCurrent, getVersion } from "../db/files.ts";
+import { HelpfulError } from "../errors.ts";
+import { colors } from "../output/formatter.ts";
+import { defineOperation } from "./types.ts";
+
+export const readOperation = defineOperation({
+	name: "membot_read",
+	cliName: "read",
+	bashEquivalent: "cat",
+	description: `Read a stored file. By default returns the cleaned markdown surrogate the rest of the index sees — for a markdown source that's the original text, for a PDF/DOCX/HTML that's the converted markdown, and for an image that's its caption. Pass bytes=true to instead return the **original ingested bytes verbatim** (base64-encoded): for a textual source like .md or .txt that's the literal source you uploaded, NOT the surrogate; for binary sources it's the raw PDF / DOCX / image bytes. Defaults to the current version; pass \`version\` (timestamp) to read a historical snapshot — use membot_versions to enumerate available versions. For finding content across many files, use membot_search instead of repeated membot_read calls.`,
+	inputSchema: z.object({
+		logical_path: z.string().describe("Path of the file to read"),
+		version: z.string().optional().describe("Specific version_id (ISO timestamp) — defaults to current"),
+		bytes: z
+			.boolean()
+			.default(false)
+			.describe(
+				"Return original ingested bytes (base64) verbatim instead of the markdown surrogate. For textual sources this is the original text, NOT the surrogate.",
+			),
+		offset: z.number().optional().describe("1-based start line (text mode only)"),
+		limit: z.number().optional().describe("Number of lines to return (text mode only)"),
+	}),
+	outputSchema: z.object({
+		logical_path: z.string(),
+		version_id: z.string(),
+		mime_type: z.string().nullable(),
+		size_bytes: z.number().nullable(),
+		version_is_current: z.boolean(),
+		content: z.string().optional(),
+		description: z.string().nullable().optional(),
+		bytes_base64: z.string().optional(),
+		blob_available: z.boolean(),
+	}),
+	cli: { positional: ["logical_path"] },
+	console_formatter: (result) => {
+		const tag = result.version_is_current ? colors.green("[current]") : colors.yellow("[historical]");
+		const head = `${colors.cyan(result.logical_path)} ${colors.dim(`@ ${result.version_id}`)} ${tag}`;
+		const meta = colors.dim(
+			`mime=${result.mime_type ?? "-"} size=${result.size_bytes ?? "-"} blob=${result.blob_available ? "yes" : "no"}`,
+		);
+		if (result.bytes_base64 !== undefined) {
+			return `${head}\n${meta}\n${colors.dim(`(${result.bytes_base64.length} base64 chars; pipe with --json for the full payload)`)}`;
+		}
+		const body = result.content ?? "";
+		return `${head}\n${meta}\n\n${body}`;
+	},
+	handler: async (input, ctx) => {
+		const cur = await getCurrent(ctx.db, input.logical_path);
+		const row = input.version ? await getVersion(ctx.db, input.logical_path, input.version) : cur;
+		if (!row) {
+			throw new HelpfulError({
+				kind: "not_found",
+				message: `no version of ${input.logical_path}${input.version ? ` at ${input.version}` : ""} found`,
+				hint: `Run \`membot ls\` to see paths, or \`membot versions ${input.logical_path}\` to list versions.`,
+			});
+		}
+		const isCurrent = !!cur && cur.version_id === row.version_id;
+
+		if (input.bytes) {
+			const blob = row.blob_sha256 ? await readBlob(ctx.db, row.blob_sha256) : null;
+			if (!blob) {
+				throw new HelpfulError({
+					kind: "not_found",
+					message: `no blob bytes available for ${input.logical_path}@${row.version_id}`,
+					hint: "Inline writes do not have an underlying blob. Use the markdown surrogate (default) instead.",
+				});
+			}
+			return {
+				logical_path: row.logical_path,
+				version_id: row.version_id,
+				mime_type: blob.mime_type,
+				size_bytes: blob.size_bytes,
+				version_is_current: isCurrent,
+				bytes_base64: Buffer.from(blob.bytes).toString("base64"),
+				blob_available: true,
+			};
+		}
+
+		const content = sliceLines(row.content ?? "", input.offset, input.limit);
+		return {
+			logical_path: row.logical_path,
+			version_id: row.version_id,
+			mime_type: row.mime_type,
+			size_bytes: row.size_bytes,
+			version_is_current: isCurrent,
+			content,
+			description: row.description,
+			blob_available: !!row.blob_sha256,
+		};
+	},
+});
+
+/** Return the requested 1-based line range (offset..offset+limit-1) or the full body. */
+function sliceLines(text: string, offset?: number, limit?: number): string {
+	if (offset === undefined && limit === undefined) return text;
+	const lines = text.split("\n");
+	const start = Math.max(0, (offset ?? 1) - 1);
+	const end = limit !== undefined ? start + limit : lines.length;
+	return lines.slice(start, end).join("\n");
+}

package/src/operations/refresh.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { listDueRefreshes } from "../db/files.ts";
+import { colors } from "../output/formatter.ts";
+import { refreshOne } from "../refresh/runner.ts";
+import { defineOperation } from "./types.ts";
+
+export const refreshOperation = defineOperation({
+	name: "membot_refresh",
+	cliName: "refresh",
+	description: `Re-read a file's source and create a new version only if the source bytes changed. Pass \`logical_path\` to refresh one file, or omit it to refresh every file whose refresh_frequency_sec has elapsed. Local files are detected via mtime+sha; remote files are re-fetched via the same mcpx invocation that was originally used. On auth or network failure the prior version stays current — check \`last_refresh_status\`.`,
+	inputSchema: z.object({
+		logical_path: z.string().optional().describe("Single path to refresh; omit for all-due"),
+		force: z.boolean().default(false).describe("Re-embed even if source sha is unchanged"),
+	}),
+	outputSchema: z.object({
+		processed: z.array(
+			z.object({
+				logical_path: z.string(),
+				status: z.enum(["ok", "unchanged", "failed"]),
+				new_version_id: z.string().optional(),
+				error: z.string().optional(),
+			}),
+		),
+		count: z.number(),
+	}),
+	cli: { positional: ["logical_path"] },
+	console_formatter: (result) => {
+		if (result.processed.length === 0) return colors.dim("(nothing due to refresh)");
+		let updated = 0;
+		let unchanged = 0;
+		let failed = 0;
+		const lines = result.processed.map((p) => {
+			if (p.status === "ok") {
+				updated++;
+				const ver = p.new_version_id ? colors.dim(`→ ${p.new_version_id}`) : "";
+				return `${colors.green("✓")} ${colors.cyan(p.logical_path)} ${ver}`;
+			}
+			if (p.status === "unchanged") {
+				unchanged++;
+				return `${colors.dim("·")} ${colors.dim(p.logical_path)} ${colors.dim("(unchanged)")}`;
+			}
+			failed++;
+			return `${colors.red("✗")} ${p.logical_path} ${colors.dim(p.error ?? "")}`;
+		});
+		const parts = [colors.green(`updated ${updated}`), colors.dim(`unchanged ${unchanged}`)];
+		if (failed) parts.push(colors.red(`failed ${failed}`));
+		return `${lines.join("\n")}\n${parts.join(", ")}`;
+	},
+	handler: async (input, ctx) => {
+		const targets = input.logical_path
+			? [input.logical_path]
+			: (await listDueRefreshes(ctx.db)).map((r) => r.logical_path);
+		const out: Array<{
+			logical_path: string;
+			status: "ok" | "unchanged" | "failed";
+			new_version_id?: string;
+			error?: string;
+		}> = [];
+		ctx.progress.start(targets.length, "refresh");
+		for (const path of targets) {
+			ctx.progress.tick(path);
+			try {
+				const r = await refreshOne(ctx, path, input.force);
+				out.push(r);
+			} catch (err) {
+				out.push({ logical_path: path, status: "failed", error: err instanceof Error ? err.message : String(err) });
+			}
+		}
+		ctx.progress.done(`refresh: ${out.filter((r) => r.status === "ok").length}/${out.length} updated`);
+		return { processed: out, count: out.length };
+	},
+});