botholomew 0.15.6 → 0.16.2

package/src/tools/prompt/delete.ts

@@ -0,0 +1,103 @@
+import { unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { getPromptsDir } from "../../constants.ts";
+import {
+  PromptValidationError,
+  parsePromptFile,
+} from "../../utils/frontmatter.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  name: z
+    .string()
+    .describe("Prompt name without extension. Resolves to prompts/<name>.md."),
+});
+
+const outputSchema = z.object({
+  name: z.string(),
+  path: z.string().nullable(),
+  deleted: z.boolean(),
+  is_error: z.boolean(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+  next_action_hint: z.string().optional(),
+});
+
+export const promptDeleteTool = {
+  name: "prompt_delete",
+  description:
+    "[[ bash equivalent command: rm ]] Delete a prompt file under prompts/. Files marked `agent-modification: false` are protected and will not be removed.",
+  group: "context",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    if (input.name.includes("/") || input.name.includes("..")) {
+      return {
+        name: input.name,
+        path: null,
+        deleted: false,
+        is_error: true,
+        error_type: "invalid_name",
+        message: `Invalid prompt name: ${input.name}`,
+      };
+    }
+
+    const filePath = join(getPromptsDir(ctx.projectDir), `${input.name}.md`);
+    const file = Bun.file(filePath);
+    if (!(await file.exists())) {
+      return {
+        name: input.name,
+        path: null,
+        deleted: false,
+        is_error: true,
+        error_type: "not_found",
+        message: `Prompt not found: prompts/${input.name}.md`,
+        next_action_hint: "Use prompt_list to see available prompts.",
+      };
+    }
+
+    const raw = await file.text();
+    try {
+      const { meta } = parsePromptFile(filePath, raw);
+      if (!meta["agent-modification"]) {
+        return {
+          name: input.name,
+          path: filePath,
+          deleted: false,
+          is_error: true,
+          error_type: "agent_modification_disabled",
+          message: `Agent deletion not allowed for prompts/${input.name}.md`,
+          next_action_hint:
+            "Edit the file manually with `botholomew prompts delete` or your editor.",
+        };
+      }
+    } catch (err) {
+      // A malformed prompt is still a valid target for deletion — the agent
+      // shouldn't be locked out of cleaning up an unparseable file. Surface
+      // the parse error in the message but allow the unlink.
+      const reason =
+        err instanceof PromptValidationError
+          ? err.reason
+          : err instanceof Error
+            ? err.message
+            : String(err);
+      await unlink(filePath);
+      return {
+        name: input.name,
+        path: filePath,
+        deleted: true,
+        is_error: false,
+        message: `Deleted unparseable prompt (${reason})`,
+      };
+    }
+
+    await unlink(filePath);
+    return {
+      name: input.name,
+      path: filePath,
+      deleted: true,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/prompt/edit.ts

@@ -8,8 +8,9 @@ import {
 } from "../../fs/atomic.ts";
 import { applyLinePatches, LinePatchSchema } from "../../fs/patches.ts";
 import {
-  parseContextFile,
-  serializeContextFile,
+  PromptValidationError,
+  parsePromptFile,
+  serializePromptFile,
 } from "../../utils/frontmatter.ts";
 import type { ToolDefinition } from "../tool.ts";
 
@@ -17,7 +18,7 @@ const inputSchema = z.object({
   name: z
     .string()
     .describe(
-      "Prompt name without extension (e.g. 'beliefs', 'goals', 'capabilities'). Resolves to prompts/<name>.md.",
+      "Prompt name without extension (e.g. 'beliefs', 'goals'). Resolves to prompts/<name>.md.",
     ),
   patches: z.array(LinePatchSchema).describe("Patches to apply"),
 });
@@ -36,7 +37,7 @@ const outputSchema = z.object({
 export const promptEditTool = {
   name: "prompt_edit",
   description:
-    "[[ bash equivalent command: patch ]] Apply git-style line-range patches to a prompt file under prompts/. Operates on the whole file (frontmatter + body). Files marked `agent-modification: false` (e.g. soul.md) are protected. Use prompt_read first to inspect current line numbers.",
+    "[[ bash equivalent command: patch ]] Apply git-style line-range patches to a prompt file under prompts/. Operates on the whole file (frontmatter + body). Files marked `agent-modification: false` are protected. Use prompt_read first to inspect current line numbers.",
   group: "context",
   inputSchema,
   outputSchema,
@@ -65,11 +66,31 @@ export const promptEditTool = {
         is_error: true,
         error_type: "not_found",
         message: `Prompt not found: prompts/${input.name}.md`,
+        next_action_hint:
+          "Use prompt_list to see available prompts, or prompt_create to add a new one.",
       };
     }
 
     const original = file.content;
-    const preParsed = parseContextFile(original);
+    let preParsed: ReturnType<typeof parsePromptFile>;
+    try {
+      preParsed = parsePromptFile(filePath, original);
+    } catch (err) {
+      return {
+        name: input.name,
+        path: filePath,
+        applied: 0,
+        content: original,
+        is_error: true,
+        error_type: "invalid_frontmatter",
+        message:
+          err instanceof PromptValidationError
+            ? err.message
+            : `Existing prompt failed to parse: ${err instanceof Error ? err.message : String(err)}`,
+        next_action_hint:
+          "Fix the file's frontmatter directly before patching. Required keys: title, loading, agent-modification.",
+      };
+    }
     if (!preParsed.meta["agent-modification"]) {
       return {
         name: input.name,
@@ -83,9 +104,9 @@ export const promptEditTool = {
     }
 
     const updated = applyLinePatches(original, input.patches);
-    let postParsed: { meta: Record<string, unknown>; content: string };
+    let postParsed: ReturnType<typeof parsePromptFile>;
     try {
-      postParsed = parseContextFile(updated);
+      postParsed = parsePromptFile(filePath, updated);
     } catch (err) {
       return {
         name: input.name,
@@ -94,9 +115,12 @@ export const promptEditTool = {
         content: original,
         is_error: true,
         error_type: "invalid_frontmatter",
-        message: `Patched content failed to parse: ${err instanceof Error ? err.message : String(err)}`,
+        message:
+          err instanceof PromptValidationError
+            ? `Patched content failed to parse — ${err.reason}`
+            : `Patched content failed to parse: ${err instanceof Error ? err.message : String(err)}`,
         next_action_hint:
-          "Check that the frontmatter delimiters and YAML stay valid.",
+          "Check that the frontmatter delimiters and YAML stay valid (title, loading, agent-modification all required).",
       };
     }
     if (!postParsed.meta["agent-modification"]) {
@@ -113,10 +137,7 @@ export const promptEditTool = {
       };
     }
 
-    const serialized = serializeContextFile(
-      postParsed.meta,
-      postParsed.content,
-    );
+    const serialized = serializePromptFile(postParsed.meta, postParsed.content);
 
     try {
       await atomicWriteIfUnchanged(filePath, serialized, file.mtimeMs);

package/src/tools/prompt/list.ts

@@ -0,0 +1,109 @@
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { getPromptsDir } from "../../constants.ts";
+import {
+  PromptValidationError,
+  parsePromptFile,
+} from "../../utils/frontmatter.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  limit: z
+    .number()
+    .optional()
+    .default(100)
+    .describe("Max number of prompts to return (default 100)"),
+  offset: z
+    .number()
+    .optional()
+    .default(0)
+    .describe("Skip the first N prompts (default 0)"),
+});
+
+const outputSchema = z.object({
+  prompts: z.array(
+    z.object({
+      name: z.string(),
+      title: z.string().nullable(),
+      loading: z.string().nullable(),
+      agent_modification: z.boolean(),
+      size_bytes: z.number(),
+      path: z.string(),
+      valid: z.boolean(),
+      error: z.string().nullable(),
+    }),
+  ),
+  total: z.number(),
+  is_error: z.boolean(),
+});
+
+export const promptListTool = {
+  name: "prompt_list",
+  description:
+    "[[ bash equivalent command: ls ]] List prompt files under prompts/. Returns name, title, loading mode, agent_modification flag, file size, and a valid/error pair per file (so you can see at a glance which prompts have broken frontmatter).",
+  group: "context",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    const dir = getPromptsDir(ctx.projectDir);
+    let entries: string[];
+    try {
+      entries = await readdir(dir);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return { prompts: [], total: 0, is_error: false };
+      }
+      throw err;
+    }
+
+    const mdFiles = entries.filter((f) => f.endsWith(".md")).sort();
+    const total = mdFiles.length;
+    const offset = input.offset ?? 0;
+    const limit = input.limit ?? 100;
+    const page = mdFiles.slice(offset, offset + limit);
+
+    const rows = await Promise.all(
+      page.map(async (filename) => {
+        const filePath = join(dir, filename);
+        const name = filename.replace(/\.md$/, "");
+        const [raw, st] = await Promise.all([
+          Bun.file(filePath).text(),
+          stat(filePath),
+        ]);
+        try {
+          const { meta } = parsePromptFile(filePath, raw);
+          return {
+            name,
+            title: meta.title,
+            loading: meta.loading,
+            agent_modification: meta["agent-modification"],
+            size_bytes: st.size,
+            path: filePath,
+            valid: true,
+            error: null,
+          };
+        } catch (err) {
+          const reason =
+            err instanceof PromptValidationError
+              ? err.reason
+              : err instanceof Error
+                ? err.message
+                : String(err);
+          return {
+            name,
+            title: null,
+            loading: null,
+            agent_modification: false,
+            size_bytes: st.size,
+            path: filePath,
+            valid: false,
+            error: reason,
+          };
+        }
+      }),
+    );
+
+    return { prompts: rows, total, is_error: false };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/prompt/read.ts

@@ -1,13 +1,17 @@
 import { join } from "node:path";
 import { z } from "zod";
 import { getPromptsDir } from "../../constants.ts";
+import {
+  PromptValidationError,
+  parsePromptFile,
+} from "../../utils/frontmatter.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
   name: z
     .string()
     .describe(
-      "Prompt name without extension (e.g. 'beliefs', 'goals', 'capabilities'). Resolves to prompts/<name>.md.",
+      "Prompt name without extension (e.g. 'beliefs', 'goals'). Resolves to prompts/<name>.md.",
     ),
 });
 
@@ -15,16 +19,19 @@ const outputSchema = z.object({
   name: z.string(),
   path: z.string().nullable(),
   content: z.string(),
+  title: z.string().nullable(),
+  loading: z.string().nullable(),
   agent_modification: z.boolean(),
   is_error: z.boolean(),
   error_type: z.string().optional(),
   message: z.string().optional(),
+  next_action_hint: z.string().optional(),
 });
 
 export const promptReadTool = {
   name: "prompt_read",
   description:
-    "[[ bash equivalent command: cat ]] Read a prompt file under prompts/ (e.g. beliefs, goals, capabilities, soul). Returns the whole file (frontmatter + body) for use with prompt_edit.",
+    "[[ bash equivalent command: cat ]] Read a prompt file under prompts/. Returns the whole file (frontmatter + body) plus the parsed title / loading / agent_modification flags so you can decide whether prompt_edit will be accepted.",
   group: "context",
   inputSchema,
   outputSchema,
@@ -34,6 +41,8 @@ export const promptReadTool = {
         name: input.name,
         path: null,
         content: "",
+        title: null,
+        loading: null,
         agent_modification: false,
         is_error: true,
         error_type: "invalid_name",
@@ -47,24 +56,47 @@ export const promptReadTool = {
         name: input.name,
         path: null,
         content: "",
+        title: null,
+        loading: null,
         agent_modification: false,
         is_error: true,
         error_type: "not_found",
         message: `Prompt not found: prompts/${input.name}.md`,
+        next_action_hint: "Use prompt_list to see available prompts.",
       };
     }
     const content = await file.text();
-    // Cheap header sniff so the agent knows whether prompt_edit will be
-    // accepted before it constructs patches.
-    const agent_modification = /agent-modification:\s*true/.test(
-      content.split("---", 3).slice(0, 3).join("---"),
-    );
-    return {
-      name: input.name,
-      path: filePath,
-      content,
-      agent_modification,
-      is_error: false,
-    };
+    try {
+      const { meta } = parsePromptFile(filePath, content);
+      return {
+        name: input.name,
+        path: filePath,
+        content,
+        title: meta.title,
+        loading: meta.loading,
+        agent_modification: meta["agent-modification"],
+        is_error: false,
+      };
+    } catch (err) {
+      const message =
+        err instanceof PromptValidationError
+          ? err.message
+          : err instanceof Error
+            ? err.message
+            : String(err);
+      return {
+        name: input.name,
+        path: filePath,
+        content,
+        title: null,
+        loading: null,
+        agent_modification: false,
+        is_error: true,
+        error_type: "invalid_frontmatter",
+        message,
+        next_action_hint:
+          "Fix the file's frontmatter (required: title, loading, agent-modification). The raw content is returned for inspection.",
+      };
+    }
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/registry.ts

@@ -23,7 +23,10 @@ import { mcpInfoTool } from "./mcp/info.ts";
 import { mcpListToolsTool } from "./mcp/list-tools.ts";
 import { mcpSearchTool } from "./mcp/search.ts";
 // Prompt tools
+import { promptCreateTool } from "./prompt/create.ts";
+import { promptDeleteTool } from "./prompt/delete.ts";
 import { promptEditTool } from "./prompt/edit.ts";
+import { promptListTool } from "./prompt/list.ts";
 import { promptReadTool } from "./prompt/read.ts";
 // Schedule tools
 import { createScheduleTool } from "./schedule/create.ts";
@@ -83,8 +86,11 @@ export function registerAllTools(): void {
   registerTool(contextInfoTool);
   registerTool(contextExistsTool);
   registerTool(contextCountLinesTool);
+  registerTool(promptListTool);
   registerTool(promptReadTool);
+  registerTool(promptCreateTool);
   registerTool(promptEditTool);
+  registerTool(promptDeleteTool);
   registerTool(readLargeResultTool);
   registerTool(pipeToContextTool);