botholomew 0.12.3 → 0.13.0

package/src/init/index.ts

@@ -2,14 +2,30 @@ import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { loadConfig } from "../config/loader.ts";
 import {
-  getBotholomewDir,
+  CONFIG_DIR,
+  CONFIG_FILENAME,
+  CONTEXT_DIR,
+  getConfigPath,
   getDbPath,
   getMcpxDir,
+  getPromptsDir,
+  getSchedulesDir,
+  getSchedulesLockDir,
   getSkillsDir,
+  getTasksDir,
+  getTasksLockDir,
+  getThreadsDir,
+  getWorkersDir,
+  LOCKS_SUBDIR,
+  LOGS_DIR,
+  MCPX_SERVERS_FILENAME,
+  SCHEDULES_DIR,
+  TASKS_DIR,
 } from "../constants.ts";
 import { writeCapabilitiesFile } from "../context/capabilities.ts";
 import { getConnection } from "../db/connection.ts";
 import { migrate } from "../db/schema.ts";
+import { assertCompatibleFilesystem } from "../fs/compat.ts";
 import { createMcpxClient } from "../mcpx/client.ts";
 import { registerAllTools } from "../tools/registry.ts";
 import { logger } from "../utils/logger.ts";
@@ -29,56 +45,62 @@ export async function initProject(
   projectDir: string,
   opts: { force?: boolean } = {},
 ): Promise<void> {
-  const dotDir = getBotholomewDir(projectDir);
-  const mcpxDir = getMcpxDir(projectDir);
-  const skillsDir = getSkillsDir(projectDir);
+  // Refuse to operate inside iCloud/Dropbox/etc unless --force is passed.
+  // Sync overlays break atomic rename / O_EXCL semantics that tasks and
+  // schedules depend on.
+  assertCompatibleFilesystem(projectDir, !!opts.force);
 
-  // Check if already initialized
-  const dirExists = await Bun.file(join(dotDir, "soul.md")).exists();
-  if (dirExists && !opts.force) {
+  const configPath = getConfigPath(projectDir);
+  const alreadyInitialized = await Bun.file(configPath).exists();
+  if (alreadyInitialized && !opts.force) {
     throw new Error(
-      `.botholomew already initialized in ${projectDir}. Use --force to reinitialize.`,
+      `Botholomew project already initialized in ${projectDir} (found ${CONFIG_DIR}/${CONFIG_FILENAME}). Use --force to reinitialize.`,
     );
   }
 
-  // Create directories
-  await mkdir(dotDir, { recursive: true });
-  await mkdir(mcpxDir, { recursive: true });
-  await mkdir(skillsDir, { recursive: true });
+  // Top-level directories
+  await mkdir(join(projectDir, CONFIG_DIR), { recursive: true });
+  await mkdir(getPromptsDir(projectDir), { recursive: true });
+  await mkdir(getSkillsDir(projectDir), { recursive: true });
+  await mkdir(getMcpxDir(projectDir), { recursive: true });
+  await mkdir(join(projectDir, CONTEXT_DIR), { recursive: true });
+  await mkdir(getTasksDir(projectDir), { recursive: true });
+  await mkdir(getTasksLockDir(projectDir), { recursive: true });
+  await mkdir(getSchedulesDir(projectDir), { recursive: true });
+  await mkdir(getSchedulesLockDir(projectDir), { recursive: true });
+  await mkdir(getWorkersDir(projectDir), { recursive: true });
+  await mkdir(getThreadsDir(projectDir), { recursive: true });
+  await mkdir(join(projectDir, LOGS_DIR), { recursive: true });
 
-  // Write template files
-  await Bun.write(join(dotDir, "soul.md"), SOUL_MD);
-  await Bun.write(join(dotDir, "beliefs.md"), BELIEFS_MD);
-  await Bun.write(join(dotDir, "goals.md"), GOALS_MD);
-  await Bun.write(join(dotDir, "capabilities.md"), CAPABILITIES_MD);
+  // Persistent-context template files
+  const pcDir = getPromptsDir(projectDir);
+  await Bun.write(join(pcDir, "soul.md"), SOUL_MD);
+  await Bun.write(join(pcDir, "beliefs.md"), BELIEFS_MD);
+  await Bun.write(join(pcDir, "goals.md"), GOALS_MD);
+  await Bun.write(join(pcDir, "capabilities.md"), CAPABILITIES_MD);
 
-  // Write default skills
+  // Default skills
+  const skillsDir = getSkillsDir(projectDir);
   await Bun.write(join(skillsDir, "summarize.md"), SUMMARIZE_SKILL);
   await Bun.write(join(skillsDir, "standup.md"), STANDUP_SKILL);
   await Bun.write(join(skillsDir, "capabilities.md"), CAPABILITIES_SKILL);
 
-  // Write config (with placeholder API key)
-  await Bun.write(
-    join(dotDir, "config.json"),
-    `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`,
-  );
+  // Config
+  await Bun.write(configPath, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`);
 
-  // Write mcpx servers config
+  // mcpx servers config
   await Bun.write(
-    join(mcpxDir, "servers.json"),
+    join(getMcpxDir(projectDir), MCPX_SERVERS_FILENAME),
     `${JSON.stringify(DEFAULT_MCPX_SERVERS, null, 2)}\n`,
   );
 
-  // Initialize database
+  // Initialize the index database (search index sidecar; rebuildable).
   const dbPath = getDbPath(projectDir);
   const conn = await getConnection(dbPath);
   await migrate(conn);
   conn.close();
 
-  // Populate capabilities.md with the real tool inventory. Seeded mcpx
-  // servers.json has no entries on first init, so this lists only the
-  // built-in tools; running `botholomew capabilities` later after
-  // adding MCPX servers picks those up.
+  // Populate capabilities.md with the real tool inventory.
   registerAllTools();
   const config = await loadConfig(projectDir);
   const mcpxClient = await createMcpxClient(projectDir);
@@ -88,33 +110,28 @@ export async function initProject(
     await mcpxClient?.close();
   }
 
-  // Update .gitignore
-  await updateGitignore(projectDir);
-
   logger.success("Initialized Botholomew project");
-  logger.dim(`  Directory: ${dotDir}`);
-  logger.dim(`  Database: ${dbPath}`);
+  logger.dim(`  Project root: ${projectDir}`);
+  logger.dim(`  Config:       ${CONFIG_DIR}/${CONFIG_FILENAME}`);
+  logger.dim(`  Index DB:     ${dbPath}`);
+  logger.dim("");
+  logger.dim("Layout:");
+  logger.dim(`  ${CONFIG_DIR}/         settings`);
+  logger.dim(`  prompts/   soul, beliefs, goals, capabilities`);
+  logger.dim(`  ${CONTEXT_DIR}/        agent-writable knowledge tree`);
+  logger.dim(`  ${TASKS_DIR}/          one markdown file per task`);
+  logger.dim(`    ${LOCKS_SUBDIR}/        worker claim lockfiles`);
+  logger.dim(`  ${SCHEDULES_DIR}/      one markdown file per schedule`);
+  logger.dim(`  threads/         one CSV per conversation, by UTC date`);
+  logger.dim(`  workers/         one JSON pidfile per worker (heartbeats)`);
+  logger.dim(`  skills/, mcpx/, models/, logs/`);
   logger.dim("");
   logger.dim("Next steps:");
-  logger.dim("  1. Set ANTHROPIC_API_KEY or add it to .botholomew/config.json");
+  logger.dim(
+    `  1. Set ANTHROPIC_API_KEY or add it to ${CONFIG_DIR}/${CONFIG_FILENAME}`,
+  );
   logger.dim("  2. Run 'botholomew task add' to create your first task");
   logger.dim(
     "  3. Run 'botholomew worker start --persist' to start a background worker",
   );
 }
-
-async function updateGitignore(projectDir: string): Promise<void> {
-  const gitignorePath = join(projectDir, ".gitignore");
-  const file = Bun.file(gitignorePath);
-
-  let content = "";
-  if (await file.exists()) {
-    content = await file.text();
-  }
-
-  const entry = ".botholomew/";
-  if (content.includes(entry)) return;
-
-  const section = `\n# Botholomew (auto-generated)\n${entry}\n`;
-  await Bun.write(gitignorePath, `${content.trimEnd()}\n${section}`);
-}

package/src/init/templates.ts

@@ -60,7 +60,7 @@ description: "Refresh capabilities.md — rescan internal and MCPX tools"
 arguments: []
 ---
 
-Call \`capabilities_refresh\` to rescan every available tool (built-in and MCPX) and rewrite \`.botholomew/capabilities.md\`. After it finishes, give me a one-line summary of the counts.
+Call \`capabilities_refresh\` to rescan every available tool (built-in and MCPX) and rewrite \`prompts/capabilities.md\`. After it finishes, give me a one-line summary of the counts.
 `;
 
 export const SUMMARIZE_SKILL = `---

package/src/mcpx/client.ts

@@ -4,7 +4,7 @@ import { type CallToolResult, McpxClient } from "@evantahler/mcpx";
 import { getMcpxDir, MCPX_SERVERS_FILENAME } from "../constants.ts";
 
 /**
- * Create an McpxClient from the project's .botholomew/mcpx/servers.json.
+ * Create an McpxClient from the project's mcpx/servers.json.
  * Returns null if the file is missing or has no servers configured.
  */
 export async function createMcpxClient(

package/src/schedules/schema.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+
+export const ScheduleFrontmatterSchema = z.object({
+  id: z.string().min(1),
+  name: z.string(),
+  description: z.string().default(""),
+  frequency: z.string(),
+  enabled: z.boolean().default(true),
+  last_run_at: z.string().nullable().default(null),
+  created_at: z.string(),
+  updated_at: z.string(),
+});
+
+export type ScheduleFrontmatter = z.infer<typeof ScheduleFrontmatterSchema>;
+
+export interface Schedule extends ScheduleFrontmatter {
+  mtimeMs: number;
+  body: string;
+}

package/src/schedules/store.ts

@@ -0,0 +1,296 @@
+import { readdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import matter from "gray-matter";
+import { getSchedulesDir, getSchedulesLockDir } from "../constants.ts";
+import { uuidv7 } from "../db/uuid.ts";
+import {
+  acquireLock,
+  atomicWrite,
+  atomicWriteIfUnchanged,
+  LockHeldError,
+  readLockHolder,
+  readWithMtime,
+  releaseLock,
+} from "../fs/atomic.ts";
+import { logger } from "../utils/logger.ts";
+import {
+  type Schedule,
+  type ScheduleFrontmatter,
+  ScheduleFrontmatterSchema,
+} from "./schema.ts";
+
+function scheduleFilePath(projectDir: string, id: string): string {
+  return join(getSchedulesDir(projectDir), `${id}.md`);
+}
+
+function scheduleLockPath(projectDir: string, id: string): string {
+  return join(getSchedulesLockDir(projectDir), `${id}.lock`);
+}
+
+function serializeSchedule(fm: ScheduleFrontmatter, body: string): string {
+  return matter.stringify(`\n${body.trim()}\n`, fm as Record<string, unknown>);
+}
+
+interface ParseOk {
+  ok: true;
+  schedule: Schedule;
+}
+interface ParseFail {
+  ok: false;
+  reason: string;
+}
+
+function parseScheduleFile(raw: string, mtimeMs: number): ParseOk | ParseFail {
+  let parsed: matter.GrayMatterFile<string>;
+  try {
+    parsed = matter(raw);
+  } catch (err) {
+    return { ok: false, reason: `frontmatter parse error: ${err}` };
+  }
+  const result = ScheduleFrontmatterSchema.safeParse(parsed.data);
+  if (!result.success) {
+    return {
+      ok: false,
+      reason: `frontmatter validation failed: ${result.error.message}`,
+    };
+  }
+  return {
+    ok: true,
+    schedule: {
+      ...result.data,
+      mtimeMs,
+      body: parsed.content.trim(),
+    },
+  };
+}
+
+export async function listScheduleFiles(projectDir: string): Promise<string[]> {
+  const dir = getSchedulesDir(projectDir);
+  try {
+    const names = await readdir(dir);
+    return names.filter((n) => n.endsWith(".md")).map((n) => n.slice(0, -3));
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+export async function getSchedule(
+  projectDir: string,
+  id: string,
+): Promise<Schedule | null> {
+  const file = await readWithMtime(scheduleFilePath(projectDir, id));
+  if (!file) return null;
+  const parsed = parseScheduleFile(file.content, file.mtimeMs);
+  if (!parsed.ok) {
+    logger.warn(`Schedule ${id} is malformed: ${parsed.reason}`);
+    return null;
+  }
+  return parsed.schedule;
+}
+
+export async function listSchedules(
+  projectDir: string,
+  filters?: { enabled?: boolean; limit?: number; offset?: number },
+): Promise<Schedule[]> {
+  const ids = await listScheduleFiles(projectDir);
+  const out: Schedule[] = [];
+  for (const id of ids) {
+    const s = await getSchedule(projectDir, id);
+    if (!s) continue;
+    if (filters?.enabled !== undefined && s.enabled !== filters.enabled)
+      continue;
+    out.push(s);
+  }
+  out.sort((a, b) => (a.created_at < b.created_at ? -1 : 1));
+  const offset = filters?.offset ?? 0;
+  const limit = filters?.limit ?? out.length;
+  return out.slice(offset, offset + limit);
+}
+
+export async function createSchedule(
+  projectDir: string,
+  params: {
+    name: string;
+    description?: string;
+    frequency: string;
+    enabled?: boolean;
+  },
+): Promise<Schedule> {
+  const id = uuidv7();
+  const now = new Date().toISOString();
+  const fm: ScheduleFrontmatter = {
+    id,
+    name: params.name,
+    description: params.description ?? "",
+    frequency: params.frequency,
+    enabled: params.enabled ?? true,
+    last_run_at: null,
+    created_at: now,
+    updated_at: now,
+  };
+  await atomicWrite(
+    scheduleFilePath(projectDir, id),
+    serializeSchedule(fm, params.description ?? ""),
+  );
+  const fresh = await getSchedule(projectDir, id);
+  if (!fresh) throw new Error(`Failed to read freshly created schedule ${id}`);
+  return fresh;
+}
+
+export async function updateSchedule(
+  projectDir: string,
+  id: string,
+  updates: Partial<
+    Pick<ScheduleFrontmatter, "name" | "description" | "frequency" | "enabled">
+  >,
+): Promise<Schedule | null> {
+  const s = await getSchedule(projectDir, id);
+  if (!s) return null;
+  // Drop undefined keys so an omitted field doesn't overwrite the on-disk
+  // value with `undefined` (YAML can't serialize undefined).
+  const definedUpdates = Object.fromEntries(
+    Object.entries(updates).filter(([, v]) => v !== undefined),
+  );
+  const fm: ScheduleFrontmatter = {
+    ...s,
+    ...definedUpdates,
+    updated_at: new Date().toISOString(),
+  };
+  await atomicWriteIfUnchanged(
+    scheduleFilePath(projectDir, id),
+    serializeSchedule(fm, s.body),
+    s.mtimeMs,
+  );
+  return getSchedule(projectDir, id);
+}
+
+export async function deleteSchedule(
+  projectDir: string,
+  id: string,
+): Promise<boolean> {
+  try {
+    await unlink(scheduleFilePath(projectDir, id));
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw err;
+  }
+  await releaseLock(scheduleLockPath(projectDir, id));
+  return true;
+}
+
+export async function deleteAllSchedules(projectDir: string): Promise<number> {
+  const ids = await listScheduleFiles(projectDir);
+  let n = 0;
+  for (const id of ids) {
+    if (await deleteSchedule(projectDir, id)) n++;
+  }
+  return n;
+}
+
+export interface ClaimOptions {
+  /** Minimum gap (seconds) between schedule runs; protects against double-fire. */
+  minIntervalSeconds: number;
+}
+
+/**
+ * Acquire a schedule's lockfile, verify min-interval, and call `fn` with the
+ * locked Schedule. The caller mutates last_run_at via `markScheduleRun`
+ * before the lock is dropped. If another worker holds the lock or the
+ * schedule ran too recently, returns null without calling `fn`.
+ *
+ * Important: enabled and last_run_at are checked BOTH before and after lock
+ * acquisition. The pre-lock read is a cheap fast-fail; the post-lock read
+ * is what `fn` actually receives, so a schedule that gets disabled, deleted,
+ * or just-fired between the cheap-check and the lock acquisition does not
+ * leak through.
+ */
+export async function withScheduleLock<T>(
+  projectDir: string,
+  id: string,
+  workerId: string,
+  opts: ClaimOptions,
+  fn: (s: Schedule) => Promise<T>,
+): Promise<T | null> {
+  // Pre-lock fast path: skip work if obviously not eligible.
+  const pre = await getSchedule(projectDir, id);
+  if (!pre?.enabled) return null;
+  if (pre.last_run_at) {
+    const last = Date.parse(pre.last_run_at);
+    if (Date.now() - last < opts.minIntervalSeconds * 1000) return null;
+  }
+
+  const lockPath = scheduleLockPath(projectDir, id);
+  try {
+    await acquireLock(lockPath, workerId);
+  } catch (err) {
+    if (err instanceof LockHeldError) return null;
+    throw err;
+  }
+  try {
+    // Re-read under the lock. The schedule may have been disabled, deleted,
+    // or fired by another worker between the pre-check and the lock.
+    const fresh = await getSchedule(projectDir, id);
+    if (!fresh?.enabled) return null;
+    if (fresh.last_run_at) {
+      const last = Date.parse(fresh.last_run_at);
+      if (Date.now() - last < opts.minIntervalSeconds * 1000) return null;
+    }
+    return await fn(fresh);
+  } finally {
+    await releaseLock(lockPath);
+  }
+}
+
+/**
+ * Update last_run_at on a schedule. Uses atomic-write-if-unchanged so a
+ * concurrent edit aborts the run instead of clobbering it.
+ */
+export async function markScheduleRun(
+  projectDir: string,
+  id: string,
+): Promise<void> {
+  const s = await getSchedule(projectDir, id);
+  if (!s) return;
+  const fm: ScheduleFrontmatter = {
+    ...s,
+    last_run_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+  };
+  await atomicWriteIfUnchanged(
+    scheduleFilePath(projectDir, id),
+    serializeSchedule(fm, s.body),
+    s.mtimeMs,
+  );
+}
+
+export async function reapOrphanScheduleLocks(
+  projectDir: string,
+  isWorkerAlive: (workerId: string) => Promise<boolean>,
+): Promise<string[]> {
+  const dir = getSchedulesLockDir(projectDir);
+  let names: string[];
+  try {
+    names = await readdir(dir);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw err;
+  }
+  const released: string[] = [];
+  for (const name of names) {
+    if (!name.endsWith(".lock")) continue;
+    const id = name.slice(0, -".lock".length);
+    const lockPath = join(dir, name);
+    const holder = await readLockHolder(lockPath);
+    if (!holder) {
+      await releaseLock(lockPath);
+      released.push(id);
+      continue;
+    }
+    if (!(await isWorkerAlive(holder))) {
+      await releaseLock(lockPath);
+      released.push(id);
+    }
+  }
+  return released;
+}

package/src/skills/commands.ts

@@ -122,9 +122,7 @@ export function handleSlashCommand(
 
   if (name === "skills") {
     if (ctx.skills.size === 0) {
-      ctx.addSystemMessage(
-        "No skills loaded. Add .md files to .botholomew/skills/",
-      );
+      ctx.addSystemMessage("No skills loaded. Add .md files to skills/");
     } else {
       const lines = ["Available skills:"];
       for (const [skillName, skill] of ctx.skills) {

package/src/tasks/schema.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+
+export const TASK_PRIORITIES = ["low", "medium", "high"] as const;
+export const TASK_STATUSES = [
+  "pending",
+  "in_progress",
+  "failed",
+  "complete",
+  "waiting",
+] as const;
+
+export type TaskPriority = (typeof TASK_PRIORITIES)[number];
+export type TaskStatus = (typeof TASK_STATUSES)[number];
+
+/**
+ * Frontmatter validator for `tasks/<id>.md`. Strict so a hand-edited or stale
+ * file doesn't silently round-trip with bad data; a parse failure quarantines
+ * the file (skip claim, log) per the doctor policy.
+ */
+export const TaskFrontmatterSchema = z.object({
+  id: z.string().min(1),
+  name: z.string(),
+  description: z.string().default(""),
+  priority: z.enum(TASK_PRIORITIES).default("medium"),
+  status: z.enum(TASK_STATUSES).default("pending"),
+  blocked_by: z.array(z.string()).default([]),
+  context_paths: z.array(z.string()).default([]),
+  output: z.string().nullable().default(null),
+  waiting_reason: z.string().nullable().default(null),
+  claimed_by: z.string().nullable().default(null),
+  claimed_at: z.string().nullable().default(null),
+  created_at: z.string(),
+  updated_at: z.string(),
+});
+
+export type TaskFrontmatter = z.infer<typeof TaskFrontmatterSchema>;
+
+/**
+ * In-memory task representation: frontmatter parsed + filesystem mtime so
+ * callers can detect concurrent edits before committing a write.
+ */
+export interface Task extends TaskFrontmatter {
+  /** Filesystem mtime in epoch ms, used for atomic-write-if-unchanged. */
+  mtimeMs: number;
+  /** Markdown body (everything after the frontmatter). */
+  body: string;
+}