botholomew 0.8.1 → 0.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botholomew",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Local, autonomous AI agent for knowledge work — works your task queue while you sleep.",
   "type": "module",
   "bin": {

package/src/context/embedder-impl.ts

@@ -0,0 +1,69 @@
+import type { BotholomewConfig } from "../config/schemas.ts";
+
+type EmbedFn = (
+  texts: string[],
+  config: Required<BotholomewConfig>,
+) => Promise<number[][]>;
+
+interface OpenAIEmbeddingResponse {
+  data: { embedding: number[]; index: number }[];
+  usage: { total_tokens: number };
+}
+
+/**
+ * Embed multiple texts using the OpenAI embeddings API.
+ * Returns an array of float vectors with the configured dimension.
+ */
+export async function embed(
+  texts: string[],
+  config: Required<BotholomewConfig>,
+): Promise<number[][]> {
+  if (texts.length === 0) return [];
+
+  if (!config.openai_api_key) {
+    throw new Error(
+      "OpenAI API key is required for embeddings. Set openai_api_key in config or OPENAI_API_KEY env var.",
+    );
+  }
+
+  const response = await fetch("https://api.openai.com/v1/embeddings", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${config.openai_api_key}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      input: texts,
+      model: config.embedding_model,
+      dimensions: config.embedding_dimension,
+    }),
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(
+      `OpenAI embeddings API error (${response.status}): ${body}`,
+    );
+  }
+
+  const result = (await response.json()) as OpenAIEmbeddingResponse;
+
+  // Sort by index to ensure order matches input
+  const sorted = result.data.sort((a, b) => a.index - b.index);
+  return sorted.map((d) => d.embedding);
+}
+
+/**
+ * Embed a single text string.
+ */
+export async function embedSingle(
+  text: string,
+  config: Required<BotholomewConfig>,
+): Promise<number[]> {
+  const results = await embed([text], config);
+  const vec = results[0];
+  if (!vec) throw new Error("embed returned empty results");
+  return vec;
+}
+
+export type { EmbedFn };

package/src/context/embedder.ts

@@ -1,69 +1,9 @@
-import type { BotholomewConfig } from "../config/schemas.ts";
-
-type EmbedFn = (
-  texts: string[],
-  config: Required<BotholomewConfig>,
-) => Promise<number[][]>;
-
-interface OpenAIEmbeddingResponse {
-  data: { embedding: number[]; index: number }[];
-  usage: { total_tokens: number };
-}
-
-/**
- * Embed multiple texts using the OpenAI embeddings API.
- * Returns an array of float vectors with the configured dimension.
- */
-export async function embed(
-  texts: string[],
-  config: Required<BotholomewConfig>,
-): Promise<number[][]> {
-  if (texts.length === 0) return [];
-
-  if (!config.openai_api_key) {
-    throw new Error(
-      "OpenAI API key is required for embeddings. Set openai_api_key in config or OPENAI_API_KEY env var.",
-    );
-  }
-
-  const response = await fetch("https://api.openai.com/v1/embeddings", {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${config.openai_api_key}`,
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify({
-      input: texts,
-      model: config.embedding_model,
-      dimensions: config.embedding_dimension,
-    }),
-  });
-
-  if (!response.ok) {
-    const body = await response.text();
-    throw new Error(
-      `OpenAI embeddings API error (${response.status}): ${body}`,
-    );
-  }
-
-  const result = (await response.json()) as OpenAIEmbeddingResponse;
-
-  // Sort by index to ensure order matches input
-  const sorted = result.data.sort((a, b) => a.index - b.index);
-  return sorted.map((d) => d.embedding);
-}
-
-/**
- * Embed a single text string.
- */
-export async function embedSingle(
-  text: string,
-  config: Required<BotholomewConfig>,
-): Promise<number[]> {
-  const results = await embed([text], config);
-  const vec = results[0];
-  if (!vec) throw new Error("embed returned empty results");
-  return vec;
-}
-
-export type { EmbedFn };
+// Re-exports the real embedder implementation from `embedder-impl.ts`.
+//
+// Why the indirection: tests that touch code importing from this file (e.g.,
+// `src/chat/agent.ts`, `src/worker/prompt.ts`) use Bun's `mock.module()` to
+// stub the embedder so they don't hit OpenAI. Bun's module mocks are
+// process-wide and can leak into subsequent test files. By keeping the real
+// implementation in `embedder-impl.ts`, `test/context/embedder.test.ts` can
+// import the real embedder from a path that nothing mocks.
+export * from "./embedder-impl.ts";

package/src/db/context.ts

@@ -1,3 +1,4 @@
+import { resolve as resolvePath } from "node:path";
 import type { DbConnection } from "./connection.ts";
 import { buildSetClauses, buildWhereClause, sanitizeInt } from "./query.ts";
 import { isUuid, uuidv7 } from "./uuid.ts";
@@ -193,15 +194,26 @@ export async function getContextItemBySourcePath(
 }
 
 /**
- * Look up a context item by UUID (if the value looks like one) or by context_path.
+ * Look up a context item by UUID, `context_path`, or `source_path`.
+ *
+ * `source_path` fallbacks let users pass the same argument they used for
+ * `context add` (e.g. a bare `README.md`) to management commands like
+ * `context refresh` / `context chunks`. Relative file paths are resolved
+ * against `process.cwd()` to match the absolute `source_path` stored on add.
  */
 export async function resolveContextItem(
   db: DbConnection,
   pathOrId: string,
 ): Promise<ContextItem | null> {
-  return isUuid(pathOrId)
-    ? getContextItem(db, pathOrId)
-    : getContextItemByPath(db, pathOrId);
+  if (isUuid(pathOrId)) return getContextItem(db, pathOrId);
+
+  const byContextPath = await getContextItemByPath(db, pathOrId);
+  if (byContextPath) return byContextPath;
+
+  const byUrl = await getContextItemBySourcePath(db, pathOrId, "url");
+  if (byUrl) return byUrl;
+
+  return getContextItemBySourcePath(db, resolvePath(pathOrId), "file");
 }
 
 /**

package/src/tools/context/refresh.ts

@@ -59,7 +59,7 @@ const empty = {
 export const contextRefreshTool = {
   name: "context_refresh",
   description:
-    "Re-read source files from disk / re-fetch source URLs, update stored content if it changed, and re-embed only changed items. Use `path` for a single item or subtree, or `all: true` for every sourced item. Items without a source_path are skipped. URL fetches use the project's MCPX client when available and fall back to plain HTTP.",
+    "[[ bash equivalent command: curl ]] Re-read source files from disk / re-fetch source URLs, update stored content if it changed, and re-embed only changed items. Use `path` for a single item or subtree, or `all: true` for every sourced item. Items without a source_path are skipped. URL fetches use the project's MCPX client when available and fall back to plain HTTP.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/context/search.ts

@@ -24,7 +24,8 @@ const outputSchema = z.object({
 
 export const contextSearchTool = {
   name: "context_search",
-  description: "Search context by keyword.",
+  description:
+    "[[ bash equivalent command: grep -r ]] Search context by keyword.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/dir/create.ts

@@ -18,7 +18,8 @@ const outputSchema = z.object({
 
 export const contextCreateDirTool = {
   name: "context_create_dir",
-  description: "Create a directory in context.",
+  description:
+    "[[ bash equivalent command: mkdir -p ]] Create a directory in context.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/dir/list.ts

@@ -38,7 +38,8 @@ const outputSchema = z.object({
 
 export const contextListDirTool = {
   name: "context_list_dir",
-  description: "List directory contents in context.",
+  description:
+    "[[ bash equivalent command: ls ]] List directory contents in context.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/dir/size.ts

@@ -26,7 +26,8 @@ const outputSchema = z.object({
 
 export const contextDirSizeTool = {
   name: "context_dir_size",
-  description: "Get the total size of context items in a directory.",
+  description:
+    "[[ bash equivalent command: du -s ]] Get the total size of context items in a directory.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/dir/tree.ts

@@ -66,7 +66,7 @@ type TreeEntry = DirNode | FileNode;
 export const contextTreeTool = {
   name: "context_tree",
   description:
-    "Explore your context filesystem with a bird's-eye view — shows many paths across nested directories in one call. Reach for this first when you need to discover what content exists before reading a specific file (context_read) or running a keyword search (context_search). Returns a markdown-style tree; tune max_depth and items_per_dir to bound output, or pass a deeper path to drill into a subtree.",
+    "[[ bash equivalent command: tree ]] Explore your context filesystem with a bird's-eye view — shows many paths across nested directories in one call. Reach for this first when you need to discover what content exists before reading a specific file (context_read) or running a keyword search (context_search). Returns a markdown-style tree; tune max_depth and items_per_dir to bound output, or pass a deeper path to drill into a subtree.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/copy.ts

@@ -20,7 +20,7 @@ const outputSchema = z.object({
 
 export const contextCopyTool = {
   name: "context_copy",
-  description: "Copy a context item.",
+  description: "[[ bash equivalent command: cp ]] Copy a context item.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/count-lines.ts

@@ -13,7 +13,8 @@ const outputSchema = z.object({
 
 export const contextCountLinesTool = {
   name: "context_count_lines",
-  description: "Count the number of lines in a text context item.",
+  description:
+    "[[ bash equivalent command: wc -l ]] Count the number of lines in a text context item.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/delete.ts

@@ -24,7 +24,8 @@ const outputSchema = z.object({
 
 export const contextDeleteTool = {
   name: "context_delete",
-  description: "Delete a context item or directory.",
+  description:
+    "[[ bash equivalent command: rm -r ]] Delete a context item or directory.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/edit.ts

@@ -27,7 +27,7 @@ const outputSchema = z.object({
 export const contextEditTool = {
   name: "context_edit",
   description:
-    "Apply git-style patches to a context item. Each patch specifies a line range to replace.",
+    "[[ bash equivalent command: patch ]] Apply git-style patches to a context item. Each patch specifies a line range to replace.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/exists.ts

@@ -13,7 +13,8 @@ const outputSchema = z.object({
 
 export const contextExistsTool = {
   name: "context_exists",
-  description: "Check if a context item exists.",
+  description:
+    "[[ bash equivalent command: test -e ]] Check if a context item exists.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/info.ts

@@ -25,7 +25,7 @@ const outputSchema = z.object({
 export const contextInfoTool = {
   name: "context_info",
   description:
-    "Show context item metadata (size, MIME type, line count, etc.).",
+    "[[ bash equivalent command: stat ]] Show context item metadata: size, MIME type, line count, etc.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/move.ts

@@ -19,7 +19,8 @@ const outputSchema = z.object({
 
 export const contextMoveTool = {
   name: "context_move",
-  description: "Move or rename a context item.",
+  description:
+    "[[ bash equivalent command: mv ]] Move or rename a context item.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/read.ts

@@ -18,7 +18,8 @@ const outputSchema = z.object({
 
 export const contextReadTool = {
   name: "context_read",
-  description: "Read a context item's contents.",
+  description:
+    "[[ bash equivalent command: cat ]] Read a context item's contents.",
   group: "context",
   inputSchema,
   outputSchema,

package/src/tools/file/write.ts

@@ -54,7 +54,7 @@ const outputSchema = z.object({
 export const contextWriteTool = {
   name: "context_write",
   description:
-    "Write content to a context item. By default, fails if the path already exists — pass on_conflict='overwrite' to replace.",
+    "[[ bash equivalent command: tee ]] Write content to a context item. By default, fails if the path already exists — pass on_conflict='overwrite' to replace.",
   group: "context",
   inputSchema,
   outputSchema,