botholomew 0.1.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "botholomew",
+  "version": "0.1.0",
+  "description": "An AI agent for knowledge work",
+  "type": "module",
+  "bin": {
+    "botholomew": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/evantahler/botholomew.git"
+  },
+  "scripts": {
+    "dev": "bun run src/cli.ts",
+    "test": "bun test",
+    "build": "bun build --compile --minify --sourcemap ./src/cli.ts --outfile dist/botholomew",
+    "lint": "tsc --noEmit && biome check ."
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.88.0",
+    "ansis": "^4.2.0",
+    "commander": "^14.0.0",
+    "gray-matter": "^4.0.3",
+    "ink": "^6.0.0",
+    "istextorbinary": "^9.5.0",
+    "react": "^19.1.0",
+    "uuid": "^13.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.11",
+    "@types/bun": "latest",
+    "@types/react": "^19.1.0",
+    "@types/uuid": "^11.0.0",
+    "typescript": "^6.0.2"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,45 @@
+#!/usr/bin/env bun
+
+import { program } from "commander";
+import { registerChatCommand } from "./commands/chat.ts";
+import { registerCheckUpdateCommand } from "./commands/check-update.ts";
+import { registerContextCommand } from "./commands/context.ts";
+import { registerDaemonCommand } from "./commands/daemon.ts";
+import { registerInitCommand } from "./commands/init.ts";
+import { registerMcpxCommand } from "./commands/mcpx.ts";
+import { registerTaskCommand } from "./commands/task.ts";
+import { registerToolCommands } from "./commands/tools.ts";
+import { registerUpgradeCommand } from "./commands/upgrade.ts";
+import { maybeCheckForUpdate } from "./update/background.ts";
+
+const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
+
+program
+  .name("botholomew")
+  .description("An AI agent for knowledge work")
+  .version(pkg.version)
+  .option("-d, --dir <path>", "project directory", process.cwd());
+
+registerInitCommand(program);
+registerDaemonCommand(program);
+registerTaskCommand(program);
+registerChatCommand(program);
+registerContextCommand(program);
+registerMcpxCommand(program);
+registerToolCommands(program);
+registerCheckUpdateCommand(program);
+registerUpgradeCommand(program);
+
+program.action(() => {
+  program.help();
+});
+
+// Start background update check before parsing (non-blocking)
+const updateNotice = maybeCheckForUpdate();
+
+program.parse();
+
+// Print update notice to stderr after command completes
+updateNotice.then((notice) => {
+  if (notice) process.stderr.write(notice);
+});

package/src/commands/chat.ts

@@ -0,0 +1,11 @@
+import type { Command } from "commander";
+import { logger } from "../utils/logger.ts";
+
+export function registerChatCommand(program: Command) {
+  program
+    .command("chat")
+    .description("Open the interactive chat TUI")
+    .action(async () => {
+      logger.warn("Chat TUI not yet implemented. Coming soon.");
+    });
+}

package/src/commands/check-update.ts

@@ -0,0 +1,62 @@
+import { cyan, dim, green, yellow } from "ansis";
+import type { Command } from "commander";
+import { saveUpdateCache } from "../update/cache.ts";
+import type { UpdateCache } from "../update/checker.ts";
+import { checkForUpdate } from "../update/checker.ts";
+
+const pkg = await Bun.file(
+  new URL("../../package.json", import.meta.url),
+).json();
+
+export function registerCheckUpdateCommand(program: Command) {
+  program
+    .command("check-update")
+    .description("Check for a newer version of botholomew")
+    .action(async () => {
+      try {
+        const info = await checkForUpdate(pkg.version);
+
+        // Save to cache
+        const cache: UpdateCache = {
+          lastCheckAt: new Date().toISOString(),
+          latestVersion: info.latestVersion,
+          hasUpdate: info.hasUpdate,
+          changelog: info.changelog,
+        };
+        await saveUpdateCache(cache);
+
+        if (!info.hasUpdate) {
+          if (info.aheadOfLatest) {
+            console.log(
+              yellow(
+                `botholomew v${info.currentVersion} is ahead of latest published release (v${info.latestVersion})`,
+              ),
+            );
+          } else {
+            console.log(
+              green(`botholomew 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 `botholomew upgrade` to update"));
+      } catch (err) {
+        console.error("Failed to check for updates");
+        console.error(String(err));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/context.ts

@@ -0,0 +1,27 @@
+import type { Command } from "commander";
+import { logger } from "../utils/logger.ts";
+
+export function registerContextCommand(program: Command) {
+  const ctx = program.command("context").description("Manage context items");
+
+  ctx
+    .command("list")
+    .description("List context items")
+    .action(async () => {
+      logger.warn("Not yet implemented. Coming soon.");
+    });
+
+  ctx
+    .command("add <path>")
+    .description("Add a file or directory to context")
+    .action(async () => {
+      logger.warn("Not yet implemented. Coming soon.");
+    });
+
+  ctx
+    .command("search <query>")
+    .description("Search context items")
+    .action(async () => {
+      logger.warn("Not yet implemented. Coming soon.");
+    });
+}

package/src/commands/daemon.ts

@@ -0,0 +1,61 @@
+import type { Command } from "commander";
+import { logger } from "../utils/logger.ts";
+
+export function registerDaemonCommand(program: Command) {
+  const daemon = program
+    .command("daemon")
+    .description("Manage the Botholomew daemon");
+
+  daemon
+    .command("start")
+    .description("Start the daemon for this project")
+    .option("--foreground", "run in the foreground (don't detach)")
+    .action(async (opts) => {
+      const dir = program.opts().dir;
+
+      if (opts.foreground) {
+        // Import dynamically to avoid loading daemon code for other commands
+        const { startDaemon } = await import("../daemon/index.ts");
+        await startDaemon(dir);
+      } else {
+        // Spawn detached child process
+        const { spawnDaemon } = await import("../daemon/spawn.ts");
+        await spawnDaemon(dir);
+      }
+    });
+
+  daemon
+    .command("stop")
+    .description("Stop the daemon for this project")
+    .action(async () => {
+      const dir = program.opts().dir;
+      const { stopDaemon } = await import("../utils/pid.ts");
+      const stopped = await stopDaemon(dir);
+      if (stopped) {
+        logger.success("Daemon stopped.");
+      } else {
+        logger.warn("No running daemon found.");
+      }
+    });
+
+  daemon
+    .command("status")
+    .description("Check if the daemon is running")
+    .action(async () => {
+      const dir = program.opts().dir;
+      const { getDaemonStatus } = await import("../utils/pid.ts");
+      const status = await getDaemonStatus(dir);
+      if (status) {
+        logger.success(`Daemon running (PID ${status.pid})`);
+      } else {
+        logger.dim("Daemon is not running.");
+      }
+    });
+
+  daemon
+    .command("install")
+    .description("Install OS-level watchdog (launchd/systemd)")
+    .action(async () => {
+      logger.warn("Not yet implemented. Coming soon.");
+    });
+}

package/src/commands/init.ts

@@ -0,0 +1,19 @@
+import type { Command } from "commander";
+import { initProject } from "../init/index.ts";
+import { logger } from "../utils/logger.ts";
+
+export function registerInitCommand(program: Command) {
+  program
+    .command("init")
+    .description("Initialize a new Botholomew project in the current directory")
+    .option("--force", "overwrite existing .botholomew directory")
+    .action(async (opts) => {
+      const dir = program.opts().dir;
+      try {
+        await initProject(dir, { force: opts.force });
+      } catch (err) {
+        logger.error(String(err instanceof Error ? err.message : err));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/mcpx.ts

@@ -0,0 +1,29 @@
+import type { Command } from "commander";
+import { logger } from "../utils/logger.ts";
+
+export function registerMcpxCommand(program: Command) {
+  const mcpx = program
+    .command("mcpx")
+    .description("Manage MCP servers via MCPX");
+
+  mcpx
+    .command("list")
+    .description("List configured MCP servers")
+    .action(async () => {
+      logger.warn("Not yet implemented. Coming soon.");
+    });
+
+  mcpx
+    .command("add <server>")
+    .description("Add an MCP server")
+    .action(async () => {
+      logger.warn("Not yet implemented. Coming soon.");
+    });
+
+  mcpx
+    .command("test <tool>")
+    .description("Test a tool call")
+    .action(async () => {
+      logger.warn("Not yet implemented. Coming soon.");
+    });
+}

package/src/commands/task.ts

@@ -0,0 +1,126 @@
+import ansis from "ansis";
+import type { Command } from "commander";
+import { getDbPath } from "../constants.ts";
+import { getConnection } from "../db/connection.ts";
+import { migrate } from "../db/schema.ts";
+import type { Task } from "../db/tasks.ts";
+import { createTask, getTask, listTasks } from "../db/tasks.ts";
+import { logger } from "../utils/logger.ts";
+
+export function registerTaskCommand(program: Command) {
+  const task = program.command("task").description("Manage tasks");
+
+  task
+    .command("list")
+    .description("List all tasks")
+    .option("-s, --status <status>", "filter by status")
+    .option("-p, --priority <priority>", "filter by priority")
+    .option("-l, --limit <n>", "max number of tasks", parseInt)
+    .action(async (opts) => {
+      const dir = program.opts().dir;
+      const conn = getConnection(getDbPath(dir));
+      migrate(conn);
+
+      const tasks = await listTasks(conn, {
+        status: opts.status,
+        priority: opts.priority,
+        limit: opts.limit,
+      });
+
+      if (tasks.length === 0) {
+        logger.dim("No tasks found.");
+        return;
+      }
+
+      for (const t of tasks) {
+        printTask(t);
+      }
+
+      conn.close();
+    });
+
+  task
+    .command("add <name>")
+    .description("Create a new task")
+    .option("--description <text>", "task description", "")
+    .option("-p, --priority <priority>", "low, medium, or high", "medium")
+    .action(async (name, opts) => {
+      const dir = program.opts().dir;
+      const conn = getConnection(getDbPath(dir));
+      migrate(conn);
+
+      const t = await createTask(conn, {
+        name,
+        description: opts.description,
+        priority: opts.priority,
+      });
+
+      logger.success(`Created task: ${t.name} (${t.id})`);
+      conn.close();
+    });
+
+  task
+    .command("view <id>")
+    .description("View task details")
+    .action(async (id) => {
+      const dir = program.opts().dir;
+      const conn = getConnection(getDbPath(dir));
+      migrate(conn);
+
+      const t = await getTask(conn, id);
+      if (!t) {
+        logger.error(`Task not found: ${id}`);
+        process.exit(1);
+      }
+
+      printTaskDetail(t);
+      conn.close();
+    });
+}
+
+function statusColor(status: Task["status"]): string {
+  switch (status) {
+    case "pending":
+      return ansis.yellow(status);
+    case "in_progress":
+      return ansis.blue(status);
+    case "complete":
+      return ansis.green(status);
+    case "failed":
+      return ansis.red(status);
+    case "waiting":
+      return ansis.magenta(status);
+  }
+}
+
+function priorityColor(priority: Task["priority"]): string {
+  switch (priority) {
+    case "high":
+      return ansis.red(priority);
+    case "medium":
+      return ansis.yellow(priority);
+    case "low":
+      return ansis.dim(priority);
+  }
+}
+
+function printTask(t: Task) {
+  const id = ansis.dim(t.id.slice(0, 8));
+  console.log(
+    `  ${id}  ${statusColor(t.status)}  ${priorityColor(t.priority)}  ${t.name}`,
+  );
+}
+
+function printTaskDetail(t: Task) {
+  console.log(ansis.bold(t.name));
+  console.log(`  ID:          ${t.id}`);
+  console.log(`  Status:      ${statusColor(t.status)}`);
+  console.log(`  Priority:    ${priorityColor(t.priority)}`);
+  if (t.description) console.log(`  Description: ${t.description}`);
+  if (t.waiting_reason) console.log(`  Waiting:     ${t.waiting_reason}`);
+  if (t.claimed_by) console.log(`  Claimed by:  ${t.claimed_by}`);
+  if (t.blocked_by.length > 0)
+    console.log(`  Blocked by:  ${t.blocked_by.join(", ")}`);
+  console.log(`  Created:     ${t.created_at.toISOString()}`);
+  console.log(`  Updated:     ${t.updated_at.toISOString()}`);
+}

package/src/commands/tools.ts

@@ -0,0 +1,257 @@
+import type { Command } from "commander";
+import { z } from "zod";
+import type { BotholomewConfig } from "../config/schemas.ts";
+import { DEFAULT_CONFIG } from "../config/schemas.ts";
+import { getDbPath } from "../constants.ts";
+import { getConnection } from "../db/connection.ts";
+import { migrate } from "../db/schema.ts";
+import { registerAllTools } from "../tools/registry.ts";
+import {
+  type AnyToolDefinition,
+  getToolsByGroup,
+  type ToolContext,
+} from "../tools/tool.ts";
+import { logger } from "../utils/logger.ts";
+
+registerAllTools();
+
+const GROUP_DESCRIPTIONS: Record<string, string> = {
+  dir: "Directory operations on the virtual filesystem",
+  file: "File operations on the virtual filesystem",
+  search: "Search the virtual filesystem",
+};
+
+export function registerToolCommands(program: Command) {
+  for (const group of ["dir", "file", "search"]) {
+    const groupCmd = program
+      .command(group)
+      .description(GROUP_DESCRIPTIONS[group] ?? `${group} tools`);
+
+    for (const tool of getToolsByGroup(group)) {
+      registerToolAsCLI(groupCmd, tool, program);
+    }
+  }
+}
+
+function registerToolAsCLI(
+  parent: Command,
+  tool: AnyToolDefinition,
+  program: Command,
+) {
+  // Derive subcommand name: "file_read" → "read", "file_count_lines" → "count-lines"
+  const subName = tool.name.replace(/^[^_]+_/, "").replace(/_/g, "-");
+
+  // Inspect zod schema to determine positional args and options
+  const shape = tool.inputSchema.shape as Record<string, z.ZodType>;
+  const positionals: string[] = [];
+  const options: {
+    key: string;
+    flag: string;
+    description: string;
+    isArray: boolean;
+  }[] = [];
+
+  for (const [key, schema] of Object.entries(shape)) {
+    const desc = schema.description ?? key;
+    const isOptional = schema.isOptional();
+    const unwrapped = unwrapOptional(schema);
+
+    if (isPositionalArg(key, tool.name)) {
+      positionals.push(isOptional ? `[${key}]` : `<${key}>`);
+    } else if (unwrapped instanceof z.ZodBoolean) {
+      options.push({
+        key,
+        flag: `--${key.replace(/_/g, "-")}`,
+        description: desc,
+        isArray: false,
+      });
+    } else if (unwrapped instanceof z.ZodArray) {
+      options.push({
+        key,
+        flag: `--${key.replace(/_/g, "-")} <json>`,
+        description: desc,
+        isArray: true,
+      });
+    } else {
+      options.push({
+        key,
+        flag: `--${key.replace(/_/g, "-")} <value>`,
+        description: desc,
+        isArray: false,
+      });
+    }
+  }
+
+  const cmd = parent
+    .command(`${subName} ${positionals.join(" ")}`.trim())
+    .description(tool.description);
+
+  for (const opt of options) {
+    if (opt.isArray) {
+      cmd.option(opt.flag, opt.description);
+    } else {
+      cmd.option(opt.flag, opt.description);
+    }
+  }
+
+  cmd.action(async (...args: unknown[]) => {
+    const dir = program.opts().dir;
+    const conn = getConnection(getDbPath(dir));
+    migrate(conn);
+
+    try {
+      const input = buildInput(tool, positionals, options, shape, args);
+
+      const ctx: ToolContext = {
+        conn,
+        projectDir: dir,
+        config: DEFAULT_CONFIG as Required<BotholomewConfig>,
+      };
+
+      const result = await tool.execute(input, ctx);
+      formatOutput(result, tool.name);
+    } catch (err) {
+      logger.error(String(err));
+      process.exit(1);
+    } finally {
+      conn.close();
+    }
+  });
+}
+
+function buildInput(
+  tool: AnyToolDefinition,
+  positionals: string[],
+  options: {
+    key: string;
+    flag: string;
+    description: string;
+    isArray: boolean;
+  }[],
+  shape: Record<string, z.ZodType>,
+  args: unknown[],
+): Record<string, unknown> {
+  const input: Record<string, unknown> = {};
+
+  // Positional args come first in Commander's action callback
+  for (let i = 0; i < positionals.length; i++) {
+    const key = positionals[i]?.replace(/[<>[\]]/g, "");
+    const value = args[i];
+    if (key !== undefined && value !== undefined) input[key] = value;
+  }
+
+  // Options object is the last argument before the Command object
+  const optsObj = (args[positionals.length] ?? {}) as Record<string, unknown>;
+
+  for (const opt of options) {
+    const cliKey = opt.key.replace(/_/g, "-");
+    // Commander converts --foo-bar to fooBar
+    const camelKey = cliKey.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    let value = optsObj[camelKey] ?? optsObj[opt.key];
+
+    if (value === undefined) continue;
+
+    const schemaForKey = shape[opt.key];
+    if (!schemaForKey) continue;
+    const unwrapped = unwrapOptional(schemaForKey);
+
+    // Parse JSON for array types
+    if (opt.isArray && typeof value === "string") {
+      value = JSON.parse(value);
+    }
+    // Parse numbers
+    else if (unwrapped instanceof z.ZodNumber && typeof value === "string") {
+      value = Number(value);
+    }
+
+    input[opt.key] = value;
+  }
+
+  // Validate with zod
+  const parsed = tool.inputSchema.safeParse(input);
+  if (!parsed.success) {
+    throw new Error(`Invalid arguments: ${JSON.stringify(parsed.error)}`);
+  }
+
+  return parsed.data;
+}
+
+function formatOutput(result: unknown, _toolName: string) {
+  if (result == null) return;
+
+  if (typeof result === "object") {
+    const obj = result as Record<string, unknown>;
+
+    // Special formatting for known output shapes
+    if ("tree" in obj && typeof obj.tree === "string") {
+      console.log(obj.tree);
+      return;
+    }
+
+    if ("content" in obj && typeof obj.content === "string") {
+      console.log(obj.content);
+      return;
+    }
+
+    if ("exists" in obj && typeof obj.exists === "boolean") {
+      if (!obj.exists) process.exit(1);
+      return;
+    }
+
+    if ("entries" in obj && Array.isArray(obj.entries)) {
+      for (const entry of obj.entries) {
+        const e = entry as { name: string; type: string; size: number };
+        const suffix = e.type === "directory" ? "/" : "";
+        console.log(`  ${e.name}${suffix}`);
+      }
+      return;
+    }
+
+    if ("matches" in obj && Array.isArray(obj.matches)) {
+      for (const match of obj.matches) {
+        if (typeof match === "string") {
+          console.log(match);
+        } else {
+          const m = match as { path: string; line: number; content: string };
+          console.log(`${m.path}:${m.line}: ${m.content}`);
+        }
+      }
+      return;
+    }
+
+    // Default: print as JSON
+    console.log(JSON.stringify(obj, null, 2));
+  } else {
+    console.log(result);
+  }
+}
+
+function isPositionalArg(key: string, toolName: string): boolean {
+  // These keys are treated as positional arguments
+  const positionalKeys: Record<string, string[]> = {
+    dir_create: ["path"],
+    dir_list: ["path"],
+    dir_tree: ["path"],
+    dir_size: ["path"],
+    file_read: ["path"],
+    file_write: ["path"],
+    file_edit: ["path"],
+    file_delete: ["path"],
+    file_copy: ["src", "dst"],
+    file_move: ["src", "dst"],
+    file_info: ["path"],
+    file_exists: ["path"],
+    file_count_lines: ["path"],
+    search_find: ["pattern"],
+    search_grep: ["pattern"],
+    search_semantic: ["query"],
+  };
+  return positionalKeys[toolName]?.includes(key) ?? false;
+}
+
+function unwrapOptional(schema: z.ZodType): z.ZodType {
+  if (schema instanceof z.ZodOptional) {
+    return schema.unwrap() as z.ZodType;
+  }
+  return schema;
+}