botholomew 0.1.0

package/src/tools/task/create.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { createTask, TASK_PRIORITIES } from "../../db/tasks.ts";
+import { logger } from "../../utils/logger.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  name: z.string().describe("Task name"),
+  description: z.string().optional().describe("Task description"),
+  priority: z.enum(TASK_PRIORITIES).optional().describe("Task priority"),
+  blocked_by: z
+    .array(z.string())
+    .optional()
+    .describe("IDs of tasks that must complete first"),
+});
+
+const outputSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  message: z.string(),
+});
+
+export const createTaskTool = {
+  name: "create_task",
+  description: "Create a new task to be worked on later.",
+  group: "task",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    const newTask = await createTask(ctx.conn, {
+      name: input.name,
+      description: input.description,
+      priority: input.priority,
+      blocked_by: input.blocked_by,
+    });
+    logger.info(`Created subtask: ${newTask.name} (${newTask.id})`);
+    return {
+      id: newTask.id,
+      name: newTask.name,
+      message: `Created task "${newTask.name}" with ID ${newTask.id}`,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/task/fail.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  reason: z.string().describe("Why the task failed"),
+});
+
+const outputSchema = z.object({
+  message: z.string(),
+});
+
+export const failTaskTool = {
+  name: "fail_task",
+  description: "Mark the current task as failed with a reason.",
+  group: "task",
+  terminal: true,
+  inputSchema,
+  outputSchema,
+  execute: async (input) => ({
+    message: `Task failed: ${input.reason}`,
+  }),
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/task/wait.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  reason: z.string().describe("Why the task is waiting"),
+});
+
+const outputSchema = z.object({
+  message: z.string(),
+});
+
+export const waitTaskTool = {
+  name: "wait_task",
+  description:
+    "Put the task in waiting status (e.g., needs human input, rate limited).",
+  group: "task",
+  terminal: true,
+  inputSchema,
+  outputSchema,
+  execute: async (input) => ({
+    message: `Task waiting: ${input.reason}`,
+  }),
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/tool.ts

@@ -0,0 +1,73 @@
+import type { Tool as AnthropicTool } from "@anthropic-ai/sdk/resources/messages";
+import { z } from "zod";
+import type { BotholomewConfig } from "../config/schemas.ts";
+import type { DbConnection } from "../db/connection.ts";
+
+export interface ToolContext {
+  conn: DbConnection;
+  projectDir: string;
+  config: Required<BotholomewConfig>;
+}
+
+export interface ToolDefinition<
+  TInput extends z.ZodObject<z.ZodRawShape>,
+  TOutput extends z.ZodType,
+> {
+  name: string;
+  description: string;
+  group: string;
+  terminal?: boolean;
+  inputSchema: TInput;
+  outputSchema: TOutput;
+  execute: (
+    input: z.infer<TInput>,
+    ctx: ToolContext,
+  ) => Promise<z.infer<TOutput>>;
+}
+
+// --- Registry ---
+
+export type AnyToolDefinition = ToolDefinition<
+  z.ZodObject<z.ZodRawShape>,
+  z.ZodType
+>;
+
+const tools = new Map<string, AnyToolDefinition>();
+
+export function registerTool<
+  TInput extends z.ZodObject<z.ZodRawShape>,
+  TOutput extends z.ZodType,
+>(tool: ToolDefinition<TInput, TOutput>): void {
+  tools.set(tool.name, tool as unknown as AnyToolDefinition);
+}
+
+export function getTool(name: string): AnyToolDefinition | undefined {
+  return tools.get(name);
+}
+
+export function getAllTools(): AnyToolDefinition[] {
+  return Array.from(tools.values());
+}
+
+export function getToolsByGroup(group: string): AnyToolDefinition[] {
+  return getAllTools().filter((t) => t.group === group);
+}
+
+// --- Anthropic adapter ---
+
+export function toAnthropicTool(tool: AnyToolDefinition): AnthropicTool {
+  const jsonSchema = z.toJSONSchema(tool.inputSchema);
+  return {
+    name: tool.name,
+    description: tool.description,
+    input_schema: {
+      type: "object" as const,
+      properties: jsonSchema.properties ?? {},
+      required: jsonSchema.required as string[] | undefined,
+    },
+  };
+}
+
+export function toAnthropicTools(): AnthropicTool[] {
+  return getAllTools().map(toAnthropicTool);
+}

package/src/tui/App.tsx

@@ -0,0 +1,14 @@
+import { Box, Text } from "ink";
+
+export function App() {
+  return (
+    <Box flexDirection="column" padding={1}>
+      <Text bold color="blue">
+        Botholomew Chat
+      </Text>
+      <Text dimColor>
+        Chat TUI coming soon. Use the daemon and task commands for now.
+      </Text>
+    </Box>
+  );
+}

package/src/types/istextorbinary.d.ts

@@ -0,0 +1,10 @@
+declare module "istextorbinary" {
+  export function isText(
+    filename?: string | null,
+    buffer?: Buffer | null,
+  ): boolean | null;
+  export function isBinary(
+    filename?: string | null,
+    buffer?: Buffer | null,
+  ): boolean | null;
+}

package/src/update/background.ts

@@ -0,0 +1,89 @@
+import { cyan, dim, yellow } from "ansis";
+import { DEFAULTS, ENV } from "../constants.ts";
+import { loadUpdateCache, saveUpdateCache } from "./cache.ts";
+import { checkForUpdate, needsCheck, type UpdateCache } from "./checker.ts";
+
+const pkg = await Bun.file(
+  new URL("../../package.json", import.meta.url),
+).json();
+
+/** Format an update notice for stderr output. */
+function formatNotice(
+  currentVersion: string,
+  latestVersion: string,
+  changelog?: string,
+): string {
+  const lines: string[] = [
+    "",
+    yellow(`Update available: ${currentVersion} → ${latestVersion}`),
+  ];
+
+  if (changelog) {
+    lines.push("");
+    lines.push(dim(changelog));
+  }
+
+  lines.push("");
+  lines.push(cyan("Run `botholomew upgrade` to update"));
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Non-blocking background update check. Returns a formatted notice string
+ * if an update is available, or null otherwise. Never throws.
+ */
+export async function maybeCheckForUpdate(): Promise<string | null> {
+  try {
+    // Opt-out via env var
+    if (process.env[ENV.NO_UPDATE_CHECK] === "1") return null;
+
+    // Skip if this is the check-update or upgrade command
+    const args = process.argv.slice(2);
+    const command = args.find((a) => !a.startsWith("-"));
+    if (command === "check-update" || command === "upgrade") return null;
+
+    // Only show in TTY
+    if (!(process.stderr.isTTY ?? false)) return null;
+
+    const cache = await loadUpdateCache();
+
+    if (!needsCheck(cache)) {
+      // Cache is fresh — use cached result
+      if (cache?.hasUpdate) {
+        return formatNotice(pkg.version, cache.latestVersion, cache.changelog);
+      }
+      return null;
+    }
+
+    // Cache is stale or missing — check with timeout
+    const controller = new AbortController();
+    const timeout = setTimeout(
+      () => controller.abort(),
+      DEFAULTS.UPDATE_CHECK_TIMEOUT_MS,
+    );
+
+    try {
+      const info = await checkForUpdate(pkg.version, controller.signal);
+
+      const newCache: UpdateCache = {
+        lastCheckAt: new Date().toISOString(),
+        latestVersion: info.latestVersion,
+        hasUpdate: info.hasUpdate,
+        changelog: info.changelog,
+      };
+      await saveUpdateCache(newCache);
+
+      if (info.hasUpdate) {
+        return formatNotice(pkg.version, info.latestVersion, info.changelog);
+      }
+    } finally {
+      clearTimeout(timeout);
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/update/cache.ts

@@ -0,0 +1,40 @@
+import { join } from "node:path";
+import { HOME_CONFIG_DIR } from "../constants.ts";
+import type { UpdateCache } from "./checker.ts";
+
+const UPDATE_CACHE_PATH = join(HOME_CONFIG_DIR, "update.json");
+
+/** Load the cached update check result, if it exists. */
+export async function loadUpdateCache(): Promise<UpdateCache | undefined> {
+  try {
+    const file = Bun.file(UPDATE_CACHE_PATH);
+    if (!(await file.exists())) return undefined;
+    return JSON.parse(await file.text()) as UpdateCache;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Save update check result to the cache file. */
+export async function saveUpdateCache(cache: UpdateCache): Promise<void> {
+  try {
+    const { mkdir } = await import("node:fs/promises");
+    await mkdir(HOME_CONFIG_DIR, { recursive: true });
+    await Bun.write(UPDATE_CACHE_PATH, `${JSON.stringify(cache, null, 2)}\n`);
+  } catch {
+    // Ignore write failures (e.g. permissions)
+  }
+}
+
+/** Remove the cached update check result. */
+export async function clearUpdateCache(): Promise<void> {
+  try {
+    const file = Bun.file(UPDATE_CACHE_PATH);
+    if (await file.exists()) {
+      const { unlink } = await import("node:fs/promises");
+      await unlink(UPDATE_CACHE_PATH);
+    }
+  } catch {
+    // Ignore
+  }
+}

package/src/update/checker.ts

@@ -0,0 +1,133 @@
+import { DEFAULTS } from "../constants.ts";
+
+const pkg = await Bun.file(
+  new URL("../../package.json", import.meta.url),
+).json();
+
+const NPM_REGISTRY_URL = `https://registry.npmjs.org/${pkg.name}/latest`;
+const GITHUB_REPO = (pkg.repository.url as string)
+  .replace(/^https:\/\/github\.com\//, "")
+  .replace(/\.git$/, "");
+
+export interface UpdateInfo {
+  currentVersion: string;
+  latestVersion: string;
+  hasUpdate: boolean;
+  aheadOfLatest: boolean;
+  changelog?: string;
+}
+
+export interface UpdateCache {
+  lastCheckAt: string;
+  latestVersion: string;
+  hasUpdate: boolean;
+  changelog?: string;
+}
+
+export type InstallMethod = "npm" | "bun" | "binary" | "local-dev";
+
+/** Compare two semver strings. Returns true if latest > current. */
+export function isNewerVersion(current: string, latest: string): boolean {
+  return Bun.semver.order(current, latest) === -1;
+}
+
+/** Fetch the latest version from the npm registry. */
+export async function fetchLatestVersion(
+  signal?: AbortSignal,
+): Promise<string> {
+  try {
+    const res = await fetch(NPM_REGISTRY_URL, { signal });
+    if (!res.ok) return pkg.version;
+    const data = (await res.json()) as { version: string };
+    return data.version;
+  } catch {
+    return pkg.version;
+  }
+}
+
+/** Fetch changelog from GitHub releases between two versions. */
+export async function fetchChangelog(
+  fromVersion: string,
+  toVersion: string,
+  signal?: AbortSignal,
+): Promise<string | undefined> {
+  try {
+    const res = await fetch(
+      `https://api.github.com/repos/${GITHUB_REPO}/releases?per_page=20`,
+      {
+        signal,
+        headers: { Accept: "application/vnd.github.v3+json" },
+      },
+    );
+    if (!res.ok) return undefined;
+
+    const releases = (await res.json()) as Array<{
+      tag_name: string;
+      body: string | null;
+    }>;
+
+    const relevant = releases.filter((r) => {
+      const v = r.tag_name.replace(/^v/, "");
+      return isNewerVersion(fromVersion, v) && !isNewerVersion(toVersion, v);
+    });
+
+    if (relevant.length === 0) return undefined;
+
+    return relevant
+      .map((r) => `## ${r.tag_name}\n${r.body ?? ""}`)
+      .join("\n\n")
+      .trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/** Check npm for a newer version and fetch changelog if available. */
+export async function checkForUpdate(
+  currentVersion: string,
+  signal?: AbortSignal,
+): Promise<UpdateInfo> {
+  const latestVersion = await fetchLatestVersion(signal);
+  const hasUpdate = isNewerVersion(currentVersion, latestVersion);
+  const aheadOfLatest = isNewerVersion(latestVersion, currentVersion);
+
+  let changelog: string | undefined;
+  if (hasUpdate) {
+    changelog = await fetchChangelog(currentVersion, latestVersion, signal);
+  }
+
+  return { currentVersion, latestVersion, hasUpdate, aheadOfLatest, changelog };
+}
+
+/** Returns true if the cache is missing or older than 24 hours. */
+export function needsCheck(cache?: UpdateCache): boolean {
+  if (!cache?.lastCheckAt) return true;
+  return (
+    Date.now() - new Date(cache.lastCheckAt).getTime() >
+    DEFAULTS.UPDATE_CHECK_INTERVAL_MS
+  );
+}
+
+/** Detect how botholomew was installed. */
+export function detectInstallMethod(): InstallMethod {
+  const script = process.argv[1] ?? "";
+  const execPath = process.execPath;
+
+  // Local dev: running src/cli.ts directly outside node_modules
+  if (script.includes("src/cli.ts") && !script.includes("node_modules")) {
+    return "local-dev";
+  }
+
+  // Compiled binary: execPath is the binary itself (not bun/node)
+  if (!execPath.includes("bun") && !execPath.includes("node")) {
+    return "binary";
+  }
+
+  // Bun global install: path contains .bun/install
+  if (script.includes(".bun/install") || script.includes(".bun/bin")) {
+    return "bun";
+  }
+
+  // npm global install: fallback for node_modules paths
+  return "npm";
+}

package/src/utils/frontmatter.ts

@@ -0,0 +1,24 @@
+import matter from "gray-matter";
+
+export interface ContextFileMeta {
+  loading: "always" | "contextual";
+  "agent-modification": boolean;
+}
+
+export function parseContextFile(raw: string): {
+  meta: ContextFileMeta;
+  content: string;
+} {
+  const { data, content } = matter(raw);
+  return {
+    meta: data as ContextFileMeta,
+    content: content.trim(),
+  };
+}
+
+export function serializeContextFile(
+  meta: ContextFileMeta,
+  content: string,
+): string {
+  return matter.stringify(`\n${content}\n`, meta);
+}

package/src/utils/logger.ts

@@ -0,0 +1,29 @@
+import ansis from "ansis";
+
+export const logger = {
+  info(msg: string) {
+    console.log(ansis.blue("ℹ"), msg);
+  },
+
+  success(msg: string) {
+    console.log(ansis.green("✓"), msg);
+  },
+
+  warn(msg: string) {
+    console.log(ansis.yellow("⚠"), msg);
+  },
+
+  error(msg: string) {
+    console.error(ansis.red("✗"), msg);
+  },
+
+  debug(msg: string) {
+    if (process.env.BOTHOLOMEW_DEBUG) {
+      console.log(ansis.gray("·"), ansis.gray(msg));
+    }
+  },
+
+  dim(msg: string) {
+    console.log(ansis.dim(msg));
+  },
+};

package/src/utils/pid.ts

@@ -0,0 +1,55 @@
+import { unlink } from "node:fs/promises";
+import { getPidPath } from "../constants.ts";
+
+export function writePidFile(projectDir: string, pid: number): void {
+  Bun.write(getPidPath(projectDir), String(pid));
+}
+
+export async function readPidFile(projectDir: string): Promise<number | null> {
+  const file = Bun.file(getPidPath(projectDir));
+  if (!(await file.exists())) return null;
+  const text = await file.text();
+  const pid = parseInt(text.trim(), 10);
+  return Number.isNaN(pid) ? null : pid;
+}
+
+export async function removePidFile(projectDir: string): Promise<void> {
+  try {
+    await unlink(getPidPath(projectDir));
+  } catch {
+    // ignore if file doesn't exist
+  }
+}
+
+export function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function getDaemonStatus(
+  projectDir: string,
+): Promise<{ pid: number } | null> {
+  const pid = await readPidFile(projectDir);
+  if (pid === null) return null;
+  if (!isProcessAlive(pid)) {
+    await removePidFile(projectDir);
+    return null;
+  }
+  return { pid };
+}
+
+export async function stopDaemon(projectDir: string): Promise<boolean> {
+  const pid = await readPidFile(projectDir);
+  if (pid === null) return false;
+  if (!isProcessAlive(pid)) {
+    await removePidFile(projectDir);
+    return false;
+  }
+  process.kill(pid, "SIGTERM");
+  await removePidFile(projectDir);
+  return true;
+}