membot 0.0.1 → 0.1.1

package/src/operations/remove.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { getCurrent, tombstone } from "../db/files.ts";
+import { HelpfulError } from "../errors.ts";
+import { colors } from "../output/formatter.ts";
+import { defineOperation } from "./types.ts";
+
+export const removeOperation = defineOperation({
+	name: "membot_delete",
+	cliName: "rm",
+	bashEquivalent: "rm",
+	description: `Tombstone a logical_path so it no longer appears in membot_list / membot_tree / membot_search. Old versions remain queryable via membot_versions and membot_read with an explicit version. Use membot_prune to permanently drop history.`,
+	inputSchema: z.object({
+		logical_path: z.string().describe("Path to tombstone"),
+		change_note: z.string().optional().describe("Why this is being deleted"),
+	}),
+	outputSchema: z.object({
+		logical_path: z.string(),
+		tombstone_version_id: z.string(),
+	}),
+	cli: { positional: ["logical_path"], aliases: { change_note: "-m" } },
+	console_formatter: (result) =>
+		`${colors.green("✓")} tombstoned ${colors.cyan(result.logical_path)} ${colors.dim(`@ ${result.tombstone_version_id}`)}`,
+	handler: async (input, ctx) => {
+		const cur = await getCurrent(ctx.db, input.logical_path);
+		if (!cur) {
+			throw new HelpfulError({
+				kind: "not_found",
+				message: `${input.logical_path} doesn't exist (or is already tombstoned)`,
+				hint: `Run \`membot ls\` to see active paths, or \`membot versions ${input.logical_path}\` to see history.`,
+			});
+		}
+		const v = await tombstone(ctx.db, input.logical_path, input.change_note ?? "deleted");
+		return { logical_path: input.logical_path, tombstone_version_id: v };
+	},
+});

package/src/operations/search.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { embedSingle } from "../ingest/embedder.ts";
+import { colors } from "../output/formatter.ts";
+import { fuseRRF } from "../search/hybrid.ts";
+import { searchKeyword } from "../search/keyword.ts";
+import { searchSemantic } from "../search/semantic.ts";
+import { defineOperation } from "./types.ts";
+
+export const searchOperation = defineOperation({
+	name: "membot_search",
+	cliName: "search",
+	bashEquivalent: "grep -r + semantic-search",
+	description: `Hybrid search over the context store. Pass \`query\` (natural language → semantic) and/or \`pattern\` (keyword/BM25); pass both for the strongest signal — hits matched by both float to the top via reciprocal rank fusion. Searches the CURRENT version of every file by default; set \`include_history=true\` to also search older versions. This is the primary discovery tool — prefer it over membot_read+scan.`,
+	inputSchema: z.object({
+		query: z.string().optional().describe("Natural-language query for semantic search"),
+		pattern: z.string().optional().describe("Keyword query for BM25 search"),
+		mode: z.enum(["hybrid", "semantic", "keyword"]).default("hybrid").describe("Search mode"),
+		path_prefix: z.string().optional().describe("Restrict to logical paths starting with this prefix"),
+		limit: z.number().default(10).describe("Max hits to return"),
+		include_history: z.boolean().default(false).describe("Also search older versions (default: current only)"),
+	}),
+	outputSchema: z.object({
+		hits: z.array(
+			z.object({
+				logical_path: z.string(),
+				version_id: z.string(),
+				chunk_index: z.number(),
+				snippet: z.string(),
+				score: z.number(),
+				semantic_score: z.number().nullable(),
+				keyword_score: z.number().nullable(),
+			}),
+		),
+		mode: z.string(),
+	}),
+	cli: { positional: ["query"] },
+	console_formatter: (result) => {
+		if (result.hits.length === 0) {
+			return colors.dim(`(no hits in ${result.mode} mode)`);
+		}
+		const blocks = result.hits.map((h) => {
+			const head = `${colors.cyan(h.logical_path)} ${colors.dim(`v=${h.version_id}`)} ${colors.green(`score=${h.score.toFixed(3)}`)}`;
+			const snippet = h.snippet
+				.split("\n")
+				.map((l) => `  ${l}`)
+				.join("\n");
+			return `${head}\n${colors.dim(snippet)}`;
+		});
+		return `${blocks.join("\n\n")}\n${colors.dim(`${result.hits.length} hit${result.hits.length === 1 ? "" : "s"} in ${result.mode} mode`)}`;
+	},
+	handler: async (input, ctx) => {
+		const query = input.query ?? input.pattern ?? "";
+		const pattern = input.pattern ?? input.query ?? "";
+
+		const semanticHits =
+			input.mode === "keyword" || !query.trim()
+				? []
+				: await searchSemantic(ctx.db, await embedSingle(query, ctx.config.embedding_model), {
+						limit: input.limit * 5,
+						pathPrefix: input.path_prefix,
+						includeHistory: input.include_history,
+					});
+
+		const keywordHits =
+			input.mode === "semantic" || !pattern.trim()
+				? []
+				: await searchKeyword(ctx.db, pattern, { limit: input.limit * 5, pathPrefix: input.path_prefix });
+
+		const fused = fuseRRF(semanticHits, keywordHits, { limit: input.limit });
+		return { hits: fused, mode: input.mode };
+	},
+});

package/src/operations/tree.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { listAllCurrentPaths } from "../db/files.ts";
+import { colors } from "../output/formatter.ts";
+import { defineOperation } from "./types.ts";
+
+interface TreeNode {
+	name: string;
+	full_path: string;
+	is_file: boolean;
+	children?: TreeNode[];
+}
+
+export const treeOperation = defineOperation({
+	name: "membot_tree",
+	cliName: "tree",
+	bashEquivalent: "tree",
+	description: `Render the logical-path tree of the current store. Tree is synthesised from "/" segments in logical_path — there are no real directories. Tombstoned and historical versions are hidden. Use this before membot_add to pick a sensible logical path.`,
+	inputSchema: z.object({
+		prefix: z.string().optional().describe("Only show paths starting with this prefix"),
+		max_depth: z.number().default(4).describe("How many path segments deep to render"),
+	}),
+	outputSchema: z.object({
+		root: z.string(),
+		tree: z.array(
+			z.object({
+				name: z.string(),
+				full_path: z.string(),
+				is_file: z.boolean(),
+				children: z.array(z.unknown()).optional(),
+			}),
+		),
+	}),
+	cli: { positional: ["prefix"] },
+	console_formatter: (result) => {
+		const lines: string[] = [colors.bold(result.root)];
+		const nodes = result.tree as TreeNode[];
+		renderNodes(nodes, "", lines);
+		if (lines.length === 1) lines.push(colors.dim("(empty)"));
+		return lines.join("\n");
+	},
+	handler: async (input, ctx) => {
+		const allPaths = await listAllCurrentPaths(ctx.db);
+		const filtered = input.prefix ? allPaths.filter((p) => p.startsWith(input.prefix!)) : allPaths;
+		return { root: input.prefix ?? "/", tree: buildTree(filtered, input.max_depth) };
+	},
+});
+
+/**
+ * Build a tree of TreeNode objects from a flat list of `/`-delimited paths.
+ * Splits each path into segments and groups by common prefix; nodes deeper
+ * than `maxDepth` are folded into their parent's `children` summary count.
+ */
+function buildTree(paths: string[], maxDepth: number): TreeNode[] {
+	const root: Map<string, TreeNode> = new Map();
+	for (const path of paths) {
+		const segs = path.split("/").filter(Boolean);
+		let level = root;
+		const trail: string[] = [];
+		for (let i = 0; i < segs.length && i < maxDepth; i++) {
+			const seg = segs[i]!;
+			trail.push(seg);
+			const fullPath = trail.join("/");
+			let node = level.get(seg);
+			if (!node) {
+				node = { name: seg, full_path: fullPath, is_file: i === segs.length - 1 };
+				level.set(seg, node);
+			} else if (i === segs.length - 1) {
+				node.is_file = true;
+			}
+			if (i < segs.length - 1) {
+				if (!node.children) node.children = [];
+				const childMap = new Map(node.children.map((c) => [c.name, c] as const));
+				node.children = [...childMap.values()];
+				level = childMap;
+				if (childMap.size === 0) {
+					level = new Map();
+					node.children = [];
+				} else {
+					// rebuild level pointer
+					level = new Map(node.children.map((c) => [c.name, c] as const));
+				}
+			}
+		}
+	}
+	return [...root.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Walk a tree and append `├── name` / `└── name` lines with proper continuation
+ * prefixes. Directories are rendered in cyan-bold; files in plain text.
+ */
+function renderNodes(nodes: TreeNode[], prefix: string, out: string[]): void {
+	const sorted = [...nodes].sort((a, b) => a.name.localeCompare(b.name));
+	sorted.forEach((node, i) => {
+		const last = i === sorted.length - 1;
+		const branch = last ? "└── " : "├── ";
+		const label = node.is_file && !node.children?.length ? node.name : colors.cyan(colors.bold(node.name));
+		out.push(`${prefix}${branch}${label}`);
+		if (node.children?.length) {
+			renderNodes(node.children, prefix + (last ? "    " : "│   "), out);
+		}
+	});
+}

package/src/operations/types.ts

@@ -0,0 +1,81 @@
+import type { z } from "zod";
+import type { AppContext } from "../context.ts";
+
+/**
+ * One user-facing capability defined ONCE: an MCP tool registration AND a
+ * commander CLI subcommand. Both surfaces consume `description`, `inputSchema`,
+ * and the handler from the same value, so help text and argument parsing
+ * cannot drift apart.
+ */
+export interface Operation<I extends z.ZodObject = z.ZodObject, O extends z.ZodTypeAny = z.ZodTypeAny> {
+	/** MCP tool name. Convention: `membot_<verb>` (e.g. "membot_add"). */
+	name: string;
+	/** CLI subcommand name. Defaults to `name.replace(/^membot_/, "").replaceAll("_", "-")`. */
+	cliName?: string;
+	/**
+	 * Optional bash-equivalent label (e.g. `cat`, `grep -r`). Surfaced as
+	 * `[[ bash equivalent: <value> ]]` by the description composer when the
+	 * mount adapter wants the prefix. Stored separately from `description`
+	 * so callers can render with or without the prefix as they choose.
+	 */
+	bashEquivalent?: string;
+	/**
+	 * Pure prose description string. Shown to the LLM in `tools/list` AND to
+	 * humans via `--help` (the mount adapter prepends `bashEquivalent` when
+	 * present). Should follow purpose → when-to-use → recovery-hint shape.
+	 */
+	description: string;
+	/** Single source of truth for the input contract. */
+	inputSchema: I;
+	/** Output contract — validated before being returned to the caller. */
+	outputSchema: O;
+	/** CLI-only metadata (positional args, short flag aliases, stdin source). */
+	cli?: CliMetadata<I>;
+	/**
+	 * Optional console formatter. Called by the commander mount adapter when
+	 * stdout is a TTY (and not in `--json` mode) to render the operation's
+	 * output as colorized human text. The MCP surface ignores this — agents
+	 * always receive the structured `outputSchema` data. When unset, the CLI
+	 * falls back to pretty-printed JSON.
+	 */
+	console_formatter?: (result: z.infer<O>) => string;
+	/** The work itself. AppContext gives access to db, embedder, mcpx, logger, config. */
+	handler: (input: z.infer<I>, ctx: AppContext) => Promise<z.infer<O>>;
+}
+
+/** CLI-only knobs for an Operation: positional args, short-flag aliases, stdin sourcing. */
+export interface CliMetadata<I extends z.ZodObject> {
+	/** Field names that should become positional arguments instead of flags. */
+	positional?: (keyof z.infer<I>)[];
+	/** Short-flag aliases keyed by field name (e.g. `{ logical_path: "-p" }`). */
+	aliases?: Partial<Record<keyof z.infer<I>, string>>;
+	/** Field name that should be filled from stdin when not otherwise supplied. */
+	stdinField?: keyof z.infer<I>;
+}
+
+/** Helper that infers the generic params and lets call sites stay terse. */
+export function defineOperation<I extends z.ZodObject, O extends z.ZodTypeAny>(op: Operation<I, O>): Operation<I, O> {
+	return op;
+}
+
+/**
+ * Default CLI command name for an Operation. Strips the `membot_` prefix and
+ * converts underscores to dashes. Override via `op.cliName`.
+ */
+export function defaultCliName(op: { name: string; cliName?: string }): string {
+	if (op.cliName) return op.cliName;
+	return op.name.replace(/^membot_/, "").replaceAll("_", "-");
+}
+
+/**
+ * Compose the surface-rendered description: `[[ bash equivalent: X ]] <desc>`
+ * when `bashEquivalent` is set, otherwise the raw `description`. Used by both
+ * the MCP and commander mount adapters so the same string lands in front of
+ * agents (`tools/list`) and humans (`--help`).
+ */
+export function composeDescription(op: { description: string; bashEquivalent?: string }): string {
+	if (op.bashEquivalent?.trim()) {
+		return `[[ bash equivalent: ${op.bashEquivalent.trim()} ]] ${op.description}`;
+	}
+	return op.description;
+}

package/src/operations/versions.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { listVersions } from "../db/files.ts";
+import { colors, renderTable } from "../output/formatter.ts";
+import { defineOperation } from "./types.ts";
+
+export const versionsOperation = defineOperation({
+	name: "membot_versions",
+	cliName: "versions",
+	description: `List every version of a file (newest first) with version_id, content_sha256, size, change_note, and refresh status. Use this to find the version_id you want to pass to membot_read or membot_diff. Tombstoned versions are included and flagged.`,
+	inputSchema: z.object({
+		logical_path: z.string().describe("Path whose versions to list"),
+	}),
+	outputSchema: z.object({
+		logical_path: z.string(),
+		versions: z.array(
+			z.object({
+				version_id: z.string(),
+				content_sha256: z.string().nullable(),
+				source_sha256: z.string().nullable(),
+				size_bytes: z.number().nullable(),
+				change_note: z.string().nullable(),
+				last_refresh_status: z.string().nullable(),
+				tombstone: z.boolean(),
+				created_at: z.string(),
+			}),
+		),
+	}),
+	cli: { positional: ["logical_path"] },
+	console_formatter: (result) => {
+		if (result.versions.length === 0) {
+			return `${colors.cyan(result.logical_path)}\n${colors.dim("(no versions)")}`;
+		}
+		// Newest first — first row is current unless tombstoned.
+		let currentMarked = false;
+		const rows = result.versions.map((v) => {
+			let marker = " ";
+			if (!currentMarked && !v.tombstone) {
+				marker = colors.green("→");
+				currentMarked = true;
+			}
+			const status = v.tombstone
+				? colors.red("tombstone")
+				: v.last_refresh_status === "failed"
+					? colors.red(v.last_refresh_status)
+					: (v.last_refresh_status ?? "-");
+			return [
+				marker,
+				v.tombstone ? colors.dim(v.version_id) : v.version_id,
+				v.created_at,
+				v.size_bytes !== null ? String(v.size_bytes) : "-",
+				(v.content_sha256 ?? "-").slice(0, 12),
+				status,
+				v.change_note ?? "",
+			];
+		});
+		const header = `${colors.bold(result.logical_path)}`;
+		const table = renderTable(["", "VERSION", "CREATED", "SIZE", "SHA", "STATUS", "NOTE"], rows, {
+			columnStyles: [undefined, colors.cyan, colors.dim, colors.dim, colors.dim],
+		});
+		return `${header}\n${table}`;
+	},
+	handler: async (input, ctx) => {
+		const versions = await listVersions(ctx.db, input.logical_path);
+		return {
+			logical_path: input.logical_path,
+			versions: versions.map((v) => ({
+				version_id: v.version_id,
+				content_sha256: v.content_sha256,
+				source_sha256: v.source_sha256,
+				size_bytes: v.size_bytes,
+				change_note: v.change_note,
+				last_refresh_status: v.last_refresh_status,
+				tombstone: v.tombstone,
+				created_at: v.created_at,
+			})),
+		};
+	},
+});

package/src/operations/write.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { insertChunksForVersion, rebuildFts } from "../db/chunks.ts";
+import { insertVersion, millisIso } from "../db/files.ts";
+import { chunkDeterministic } from "../ingest/chunker.ts";
+import { describe } from "../ingest/describer.ts";
+import { embed } from "../ingest/embedder.ts";
+import { parseDuration } from "../ingest/ingest.ts";
+import { sha256Hex } from "../ingest/local-reader.ts";
+import { buildSearchText } from "../ingest/search-text.ts";
+import { colors } from "../output/formatter.ts";
+import { defineOperation } from "./types.ts";
+
+export const writeOperation = defineOperation({
+	name: "membot_write",
+	cliName: "write",
+	bashEquivalent: "tee",
+	description: `Write inline agent-authored markdown. Creates a new version (source_type='inline') under the given logical_path. Use this to persist agent notes, summaries, or synthesised context that should survive across conversations. For mirroring an external document, use membot_add with a source URL instead — that gets you refresh-on-source-change for free.`,
+	inputSchema: z.object({
+		logical_path: z.string().describe("Path to write to"),
+		content: z.string().describe("Markdown body. CLI: pass via stdin if unspecified."),
+		change_note: z.string().optional().describe("Free-text note attached to the new version"),
+		refresh_frequency: z.string().optional().describe("Refresh cadence (rarely useful for inline)"),
+	}),
+	outputSchema: z.object({
+		logical_path: z.string(),
+		version_id: z.string(),
+		size_bytes: z.number(),
+	}),
+	cli: { positional: ["logical_path"], stdinField: "content" },
+	console_formatter: (result) =>
+		`${colors.green("✓")} ${colors.cyan(result.logical_path)} ${colors.dim(`@ ${result.version_id}`)} ${colors.dim(`(${result.size_bytes}B)`)}`,
+	handler: async (input, ctx) => {
+		const refreshSec = parseDuration(input.refresh_frequency);
+		const bytes = new TextEncoder().encode(input.content);
+		const description = await describe(input.logical_path, "text/markdown", input.content, ctx.config.llm);
+		const chunks = chunkDeterministic(input.content, ctx.config.chunker);
+		const searchTexts = chunks.map((c) => buildSearchText(input.logical_path, description, c.content));
+		const embeddings = await embed(searchTexts, ctx.config.embedding_model);
+
+		const versionId = millisIso(Date.now());
+		const contentSha = sha256Hex(bytes);
+		await insertVersion(ctx.db, {
+			logical_path: input.logical_path,
+			version_id: versionId,
+			source_type: "inline",
+			source_path: null,
+			source_mtime_ms: null,
+			source_sha256: contentSha,
+			blob_sha256: null,
+			content_sha256: contentSha,
+			content: input.content,
+			description,
+			mime_type: "text/markdown",
+			size_bytes: bytes.byteLength,
+			fetcher: "inline",
+			refresh_frequency_sec: refreshSec,
+			refreshed_at: new Date().toISOString(),
+			last_refresh_status: "ok",
+			change_note: input.change_note ?? null,
+		});
+
+		await insertChunksForVersion(
+			ctx.db,
+			input.logical_path,
+			versionId,
+			chunks.map((c, i) => ({
+				chunk_index: c.index,
+				chunk_content: c.content,
+				search_text: searchTexts[i] ?? buildSearchText(input.logical_path, description, c.content),
+				embedding: embeddings[i] ?? new Array(embeddings[0]?.length ?? 0).fill(0),
+			})),
+		);
+		await rebuildFts(ctx.db);
+
+		return { logical_path: input.logical_path, version_id: versionId, size_bytes: bytes.byteLength };
+	},
+});

package/src/output/formatter.ts

@@ -0,0 +1,68 @@
+import ansis, { bold, cyan, dim, green, red, yellow } from "ansis";
+import { isJson, useColor } from "./tty.ts";
+
+function colorize(fn: (s: string) => string, msg: string): string {
+	return useColor() ? fn(msg) : msg;
+}
+
+/**
+ * Render a final result for the CLI. JSON mode → JSON.stringify. Otherwise
+ * defer to the optional `console_formatter`, falling back to JSON.
+ */
+export function renderResult<T>(result: T, opts: { console_formatter?: (result: T) => string } = {}): string {
+	if (isJson()) {
+		return JSON.stringify(result, null, 2);
+	}
+	if (opts.console_formatter) return opts.console_formatter(result);
+	if (typeof result === "string") return result;
+	return JSON.stringify(result, null, 2);
+}
+
+/**
+ * Pretty-print a 2D array of cells as an aligned table. Column widths are
+ * computed from the visible (escape-stripped) length of each cell so coloured
+ * cells still align. Optional `columnStyles` are applied AFTER padding so they
+ * don't perturb width math.
+ */
+export function renderTable(
+	headers: string[],
+	rows: string[][],
+	opts: { columnStyles?: (((s: string) => string) | undefined)[] } = {},
+): string {
+	const widths = headers.map((h, i) => Math.max(visibleLen(h), ...rows.map((r) => visibleLen(r[i] ?? ""))));
+	const styles = opts.columnStyles ?? [];
+
+	const headerLine = headers.map((h, i) => pad(h, widths[i] ?? 0)).join("  ");
+	const separator = headers.map((_, i) => "─".repeat(widths[i] ?? 0)).join("  ");
+	const bodyLines = rows.map((r) =>
+		r
+			.map((cell, i) => {
+				const padded = pad(cell ?? "", widths[i] ?? 0);
+				const style = styles[i];
+				return style ? style(padded) : padded;
+			})
+			.join("  "),
+	);
+
+	const out = [colorize(bold, headerLine), colorize(dim, separator), ...bodyLines];
+	return out.join("\n");
+}
+
+function visibleLen(s: string): number {
+	return ansis.strip(s).length;
+}
+
+function pad(s: string, width: number): string {
+	const visible = visibleLen(s);
+	if (visible >= width) return s;
+	return s + " ".repeat(width - visible);
+}
+
+export const colors = {
+	bold: (s: string) => colorize(bold, s),
+	dim: (s: string) => colorize(dim, s),
+	red: (s: string) => colorize(red, s),
+	green: (s: string) => colorize(green, s),
+	yellow: (s: string) => colorize(yellow, s),
+	cyan: (s: string) => colorize(cyan, s),
+};

package/src/output/logger.ts

@@ -0,0 +1,114 @@
+import { dim, red, yellow } from "ansis";
+import { createSpinner } from "nanospinner";
+import { getMode, isJson, isSilent, isVerbose, useColor, useSpinner } from "./tty.ts";
+
+export interface Spinner {
+	update(text: string): void;
+	success(text?: string): void;
+	error(text?: string): void;
+	stop(): void;
+}
+
+const NOOP_SPINNER: Spinner = { update() {}, success() {}, error() {}, stop() {} };
+
+/**
+ * Process-wide singleton that owns stderr writes. All output is spinner-aware
+ * (clears the active spinner line, writes, then re-renders) so log lines don't
+ * shred a running progress indicator. Honors JSON, verbose, and color modes
+ * decided in `tty.ts` so callers never have to branch on environment.
+ */
+class Logger {
+	private static instance: Logger;
+	private activeSpinner: ReturnType<typeof createSpinner> | null = null;
+
+	/** Singleton accessor. Use the exported `logger` const instead in normal code. */
+	static getInstance(): Logger {
+		if (!Logger.instance) Logger.instance = new Logger();
+		return Logger.instance;
+	}
+
+	private color(fn: (s: string) => string, msg: string): string {
+		return useColor() ? fn(msg) : msg;
+	}
+
+	private writeStderr(msg: string): void {
+		if (this.activeSpinner) {
+			this.activeSpinner.clear();
+			process.stderr.write(`${msg}\n`);
+			this.activeSpinner.render();
+		} else {
+			process.stderr.write(`${msg}\n`);
+		}
+	}
+
+	/** Advisory info — stderr in interactive, suppressed in JSON or silent (CI/test). */
+	info(msg: string): void {
+		if (isJson() || isSilent()) return;
+		this.writeStderr(this.color(dim, msg));
+	}
+
+	/** Advisory warn — yellow on TTY, suppressed in JSON mode. */
+	warn(msg: string): void {
+		if (isJson()) return;
+		this.writeStderr(this.color(yellow, msg));
+	}
+
+	/** Errors always print, even in JSON mode (stderr won't break parseable stdout). */
+	error(msg: string): void {
+		this.writeStderr(this.color(red, msg));
+	}
+
+	/** Verbose-only debug. Silent unless `--verbose` is set, and always silent in JSON mode. */
+	debug(msg: string): void {
+		if (!isVerbose() || isJson()) return;
+		this.writeStderr(this.color(dim, msg));
+	}
+
+	/** Raw stderr write, no formatting added. Spinner-aware. */
+	writeRaw(msg: string): void {
+		if (this.activeSpinner) {
+			this.activeSpinner.clear();
+			process.stderr.write(msg);
+			this.activeSpinner.render();
+		} else {
+			process.stderr.write(msg);
+		}
+	}
+
+	/**
+	 * Start a stderr spinner. Returns a `Spinner` controller in interactive
+	 * mode; in JSON / piped / `CI=true` / `NO_COLOR` environments it returns
+	 * a no-op so call sites can use the same code path either way.
+	 */
+	startSpinner(text: string): Spinner {
+		if (!useSpinner()) return NOOP_SPINNER;
+
+		const spinner = createSpinner(text, { stream: process.stderr }).start();
+		this.activeSpinner = spinner;
+
+		return {
+			update: (t: string) => {
+				spinner.update({ text: t });
+			},
+			success: (t?: string) => {
+				spinner.success({ text: t });
+				if (this.activeSpinner === spinner) this.activeSpinner = null;
+			},
+			error: (t?: string) => {
+				spinner.error({ text: t });
+				if (this.activeSpinner === spinner) this.activeSpinner = null;
+			},
+			stop: () => {
+				spinner.stop();
+				if (this.activeSpinner === spinner) this.activeSpinner = null;
+			},
+		};
+	}
+
+	/** True when the logger should emit human output (used by progress). */
+	humanOutput(): boolean {
+		return !isJson() && !isSilent() && getMode().interactive;
+	}
+}
+
+export const logger = Logger.getInstance();