@encoredigitalgroup/opencode 0.2.3 → 0.2.5

package/README.md

@@ -2,8 +2,8 @@
 
 `@encoredigitalgroup/opencode` adds file pickers for OpenCode planning commands.
 
-The TUI provides `/plan-review`, `/plan-resync`, `/plan-split`, and `/plan-execute` commands. Each command opens a picker for plans in `docs/_planning` and inserts the
-selected plan into the prompt. The server entry attaches the matching installed skill to the prompt.
+The TUI provides `/plan-review`, `/plan-resync`, `/plan-split`, and `/plan-execute` commands. Each command opens a picker for plans in `docs/_planning` and
+inserts the selected plan into the prompt. The server entry attaches the matching installed skill to the prompt.
 
 ## Install
 
@@ -24,15 +24,17 @@ OpenCode v2 loads this package from the `plugins` array. Add an object entry wit
 }
 ```
 
-Restart OpenCode after changing the configuration. OpenCode downloads missing npm plugins that appear in the `plugins` array, so you do not need to install this package
-with Bun or npm yourself. This package supports OpenCode v2 only; replace the legacy `plugin` configuration entry when migrating from OpenCode v1.
+Restart OpenCode after changing the configuration. OpenCode downloads missing npm plugins that appear in the `plugins` array, so you do not need to install this
+package with Bun or npm yourself. This package supports OpenCode v2 only; replace the legacy `plugin` configuration entry when migrating from OpenCode v1.
 
 The plugin resolves the mapped skills through OpenCode, so those skills can live in any location that OpenCode discovers.
 
 ## Configuration
 
-Set `planDirectory` and `skillMappings` in the object's `options` field. `planDirectory` is a non-empty path relative to the workspace. `skillMappings` can override any
-supported command's installed skill name. Unspecified values use the defaults: `docs/_planning` and the command's existing skill name.
+Set `planDirectory` and `skillMappings` in the object's `options` field. `planDirectory` is a non-empty path relative to the workspace. `skillMappings` can override
+any supported command's installed skill name. `enforceTodoTracker` defaults to `true`; set it to `false` to disable tracker-refresh enforcement. `readOnlyTools`
+and `writeCapableTools` add custom tools to the built-in classifications. Unspecified values use the defaults: `docs/_planning`, the command's existing skill name,
+and no custom tool classifications.
 
 ```json
 {
@@ -42,17 +44,43 @@ supported command's installed skill name. Unspecified values use the defaults: `
       "package": "@encoredigitalgroup/opencode",
       "options": {
         "planDirectory": "plans",
+        "enforceTodoTracker": false,
+        "readOnlyTools": ["repository_status"],
         "skillMappings": {
           "plan-review": "custom-plan-review",
           "plan-execute": "custom-plan-execute"
-        }
+        },
+        "writeCapableTools": ["deploy"]
       }
     }
   ]
 }
 ```
 
-Launching a picker from an existing session submits to that session. Launching one from the home screen creates and displays a new session before submitting the selected plan.
+Launching a picker from an existing session submits to that session. Launching one from the home screen creates and displays a new session before submitting the
+selected plan.
+
+## Todo tracker
+
+The plugin registers the direct `todotracker` tool. Each call replaces the current session's complete ordered todo list. Pass an empty `todos` array to clear the
+list.
+Each todo requires:
+
+- `content`: a non-empty string containing at least one non-whitespace character.
+- `status`: `pending`, `in_progress`, `completed`, or `cancelled`.
+- `priority`: `high`, `medium`, or `low`.
+
+The checklist renders only in the OpenCode terminal TUI sidebar. After a restart, it appears only when the completed `todotracker` result is in the host's loaded
+message cache. That cache starts with the newest 20 messages, so older results are not shown until the host has loaded them.
+
+After a session's first successful `todotracker` call, the plugin requires another call before a later write-capable tool runs. OpenCode's built-in write-capable
+tools are `edit`, `patch`, `shell`, `subagent`, and `write`. Built-in read-only tools are `glob`, `grep`, `lsp`, `read`, `skill`, `webfetch`, and `websearch`; the
+eleventh read-only call requires a tracker update. Session and user-interaction tools, such as `question` and `todo`, are not enforced. `readOnlyTools` and
+`writeCapableTools` extend these lists for custom tools. If a tool appears in both lists, the write-capable classification takes precedence. The plugin also supports
+the `apply_patch` and `bash` compatibility aliases as write-capable tools. Enforcement is disabled for sessions that have never used `todotracker`, and can be
+disabled for all sessions with `"enforceTodoTracker": false`.
+
+When a session is idle, the sidebar renders pending and in-progress todos as completed. It restores their original statuses when work resumes.
 
 ## Development
 

package/dist/config/ConfigLoader.d.ts

@@ -4,6 +4,8 @@ import { type PluginConfig } from "./ConfigTypes.js";
 export declare class ConfigLoader {
     private static stringOption;
     private static planDirectoryOption;
+    private static booleanOption;
+    private static toolNamesOption;
     /** Get valid skill mappings from plugin options. */
     private static skillMappingsOption;
     /** Get the configured option values that can override the defaults. */

package/dist/config/ConfigTypes.d.ts

@@ -2,12 +2,18 @@ export declare const skillCommands: readonly ["feature-planning", "plan-execute"
 export type SkillCommand = (typeof skillCommands)[number];
 export type SkillMappings = Record<SkillCommand, string>;
 export type PluginConfig = {
+    enforceTodoTracker: boolean;
     planDirectory: string;
+    readOnlyTools: string[];
     skillMappings: SkillMappings;
+    writeCapableTools: string[];
 };
 export type UserPluginConfig = {
+    enforceTodoTracker?: boolean;
     planDirectory?: string;
+    readOnlyTools?: string[];
     skillMappings?: Partial<SkillMappings>;
+    writeCapableTools?: string[];
 };
 /** Configuration type utilities. */
 export declare class ConfigTypes {

package/dist/lib/TodoTracker.d.ts

@@ -0,0 +1,54 @@
+import type { SessionMessageInfo } from "@opencode/client";
+import type { Plugin as ServerPlugin } from "@opencode/plugin";
+import type { PluginConfig } from "../config";
+export type TodoStatus = "pending" | "in_progress" | "completed" | "cancelled";
+export type TodoPriority = "high" | "medium" | "low";
+export type Todo = {
+    content: string;
+    status: TodoStatus;
+    priority: TodoPriority;
+};
+export type TodoTrackerInput = {
+    todos: Todo[];
+};
+export type TodoTrackerResultMetadata = {
+    todos: Todo[];
+};
+export declare const todoTrackerInput: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["todos"];
+    readonly properties: {
+        readonly todos: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["content", "status", "priority"];
+                readonly properties: {
+                    readonly content: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly pattern: "\\S";
+                    };
+                    readonly status: {
+                        readonly enum: readonly ["pending", "in_progress", "completed", "cancelled"];
+                    };
+                    readonly priority: {
+                        readonly enum: readonly ["high", "medium", "low"];
+                    };
+                };
+            };
+        };
+    };
+};
+export declare const todoTrackerName = "todotracker";
+export declare const todoTrackerDescription: string;
+export declare function isTodoTrackerInput(value: unknown): value is TodoTrackerInput;
+export declare function isTodoResultMetadata(value: unknown): value is TodoTrackerResultMetadata;
+export declare function todosFromMessages(messages: readonly SessionMessageInfo[]): readonly Todo[];
+export declare class TodoTracker {
+    static marker(status: TodoStatus): string;
+    static sidebar(messages: readonly SessionMessageInfo[], completed?: boolean): readonly Todo[];
+    static register(context: ServerPlugin.Context, config: PluginConfig): Promise<import("@opencode/plugin/promise/registration").Registration>;
+}

package/dist/lib/TodoTracker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/index.js

@@ -15,8 +15,11 @@ class ConfigDefaults {
   }
   static getDefaultConfig() {
     return {
+      enforceTodoTracker: true,
       planDirectory: "docs/_planning",
-      skillMappings: this.getDefaultSkillMappings()
+      readOnlyTools: [],
+      skillMappings: this.getDefaultSkillMappings(),
+      writeCapableTools: []
     };
   }
 }
@@ -39,14 +42,23 @@ class ConfigTypes {
 class ConfigMerger {
   static merge(userConfig) {
     const config = ConfigDefaults.getDefaultConfig();
+    if (userConfig.enforceTodoTracker !== undefined) {
+      config.enforceTodoTracker = userConfig.enforceTodoTracker;
+    }
     if (userConfig.planDirectory !== undefined) {
       config.planDirectory = userConfig.planDirectory;
     }
+    if (userConfig.readOnlyTools !== undefined) {
+      config.readOnlyTools = userConfig.readOnlyTools;
+    }
     if (userConfig.skillMappings !== undefined) {
       for (const command of ConfigTypes.getSkillCommands()) {
         config.skillMappings[command] = userConfig.skillMappings[command] ?? config.skillMappings[command];
       }
     }
+    if (userConfig.writeCapableTools !== undefined) {
+      config.writeCapableTools = userConfig.writeCapableTools;
+    }
     return config;
   }
 }
@@ -58,6 +70,11 @@ class ConfigValidator {
     if (config.planDirectory.trim() === "") {
       errors.push("Invalid planDirectory: must be a non-empty string.");
     }
+    for (const [option, tools] of [["readOnlyTools", config.readOnlyTools], ["writeCapableTools", config.writeCapableTools]]) {
+      if (tools.some((tool) => tool.trim() === "")) {
+        errors.push(`Invalid ${option}: tool names must be non-empty strings.`);
+      }
+    }
     for (const command of ConfigTypes.getSkillCommands()) {
       if (config.skillMappings[command].trim() === "") {
         errors.push(`Invalid skillMappings.${command}: must be a non-empty string.`);
@@ -84,6 +101,23 @@ class ConfigLoader {
     const directory = this.stringOption(value)?.replace(/\/+$/, "");
     return directory === "" ? undefined : directory;
   }
+  static booleanOption(value) {
+    return typeof value === "boolean" ? value : undefined;
+  }
+  static toolNamesOption(value) {
+    if (!Array.isArray(value)) {
+      return;
+    }
+    const toolNames = [];
+    for (const valueTool of value) {
+      const tool = this.stringOption(valueTool);
+      if (tool === undefined) {
+        return;
+      }
+      toolNames.push(tool);
+    }
+    return toolNames;
+  }
   static skillMappingsOption(value) {
     if (typeof value !== "object" || value === null) {
       return;
@@ -99,11 +133,17 @@ class ConfigLoader {
     return skillMappings;
   }
   static getUserConfig(options) {
+    const enforceTodoTracker = this.booleanOption(options?.enforceTodoTracker);
     const planDirectory = this.planDirectoryOption(options?.planDirectory);
+    const readOnlyTools = this.toolNamesOption(options?.readOnlyTools);
     const skillMappings = this.skillMappingsOption(options?.skillMappings);
+    const writeCapableTools = this.toolNamesOption(options?.writeCapableTools);
     return {
+      ...enforceTodoTracker === undefined ? {} : { enforceTodoTracker },
       ...planDirectory === undefined ? {} : { planDirectory },
-      ...skillMappings === undefined ? {} : { skillMappings }
+      ...readOnlyTools === undefined ? {} : { readOnlyTools },
+      ...skillMappings === undefined ? {} : { skillMappings },
+      ...writeCapableTools === undefined ? {} : { writeCapableTools }
     };
   }
   static loadConfig(options) {
@@ -128,6 +168,297 @@ class SkillCommands {
   }
 }
 
+// src/lib/TodoTracker.ts
+var todoTrackerInput = {
+  type: "object",
+  additionalProperties: false,
+  required: ["todos"],
+  properties: {
+    todos: {
+      type: "array",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["content", "status", "priority"],
+        properties: {
+          content: { type: "string", minLength: 1, pattern: "\\S" },
+          status: { enum: ["pending", "in_progress", "completed", "cancelled"] },
+          priority: { enum: ["high", "medium", "low"] }
+        }
+      }
+    }
+  }
+};
+var todoTrackerName = "todotracker";
+var todoTrackerDescription = "Replace the current session's complete ordered todo list. " + "Pass every remaining todo on each call; pass an empty array to clear the list.";
+var trackerRefreshMessage = "Update todotracker with the complete current todo list, including newly discovered work and current statuses, before continuing tool work.";
+var todoStatuses = ["pending", "in_progress", "completed", "cancelled"];
+var todoPriorities = ["high", "medium", "low"];
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOnlyKeys(value, keys) {
+  const expected = new Set(keys);
+  return Object.keys(value).length === keys.length && Object.keys(value).every((key) => expected.has(key));
+}
+function isTodoStatus(value) {
+  return typeof value === "string" && todoStatuses.includes(value);
+}
+function isTodoPriority(value) {
+  return typeof value === "string" && todoPriorities.includes(value);
+}
+function isTodo(value) {
+  if (!isRecord(value) || !hasOnlyKeys(value, ["content", "status", "priority"])) {
+    return false;
+  }
+  return typeof value.content === "string" && value.content.length >= 1 && /\S/.test(value.content) && isTodoStatus(value.status) && isTodoPriority(value.priority);
+}
+function isTodoList(value) {
+  return Array.isArray(value) && value.every(isTodo);
+}
+function isTodoTrackerInput(value) {
+  return isRecord(value) && hasOnlyKeys(value, ["todos"]) && isTodoList(value.todos);
+}
+function isTodoResultMetadata(value) {
+  return isTodoTrackerInput(value);
+}
+function todosFromToolResult(metadata, content) {
+  if (isTodoResultMetadata(metadata)) {
+    return metadata.todos;
+  }
+  for (const item of content) {
+    if (item.type !== "text" || item.text === undefined) {
+      continue;
+    }
+    try {
+      const todos = JSON.parse(item.text);
+      if (isTodoList(todos)) {
+        return todos;
+      }
+    } catch {}
+  }
+  return [];
+}
+function todosFromMessages(messages) {
+  for (const message of messages.toReversed()) {
+    if (message.type !== "assistant")
+      continue;
+    for (const part of message.content.toReversed()) {
+      if (part.type === "tool" && part.name === todoTrackerName && part.state.status === "completed") {
+        return todosFromToolResult(part.state.metadata, part.state.content);
+      }
+    }
+  }
+  return [];
+}
+var builtInReadOnlyTools = new Set(["glob", "grep", "lsp", "read", "skill", "webfetch", "websearch"]);
+var builtInWriteCapableTools = new Set(["edit", "patch", "shell", "subagent", "write"]);
+var compatibilityWriteCapableTools = new Set(["apply_patch", "bash"]);
+var readToolsBeforeRefresh = 10;
+function refreshedTrackerState() {
+  return { kind: "tracked", readToolsSinceRefresh: 0, requiresRefreshBeforeWrite: false };
+}
+function isReadOnlyTool(tool, config) {
+  return builtInReadOnlyTools.has(tool) || config.readOnlyTools.includes(tool);
+}
+function isWriteCapableTool(tool, config) {
+  return builtInWriteCapableTools.has(tool) || compatibilityWriteCapableTools.has(tool) || config.writeCapableTools.includes(tool);
+}
+function requiresTrackerRefresh(state, tool, config) {
+  if (state.kind === "untracked" || tool === todoTrackerName) {
+    return false;
+  }
+  if (isWriteCapableTool(tool, config)) {
+    return state.requiresRefreshBeforeWrite;
+  }
+  if (isReadOnlyTool(tool, config)) {
+    return state.readToolsSinceRefresh >= readToolsBeforeRefresh;
+  }
+  return false;
+}
+function requiresTrackerRefreshBeforeMoreWork(state) {
+  return state.kind === "tracked" && (state.requiresRefreshBeforeWrite || state.readToolsSinceRefresh >= readToolsBeforeRefresh);
+}
+function trackerStateFromMessages(messages, config) {
+  let state = { kind: "untracked" };
+  for (const message of messages) {
+    if (message.type !== "assistant") {
+      continue;
+    }
+    for (const part of message.content) {
+      if (part.type !== "tool" || part.state.status !== "completed") {
+        continue;
+      }
+      if (part.name === todoTrackerName) {
+        state = refreshedTrackerState();
+      } else if (state.kind === "tracked") {
+        if (isWriteCapableTool(part.name, config)) {
+          state.requiresRefreshBeforeWrite = true;
+        } else if (isReadOnlyTool(part.name, config)) {
+          state.readToolsSinceRefresh += 1;
+        }
+      }
+    }
+  }
+  return state;
+}
+
+class TodoTrackerEnforcement {
+  context;
+  config;
+  states = new Map;
+  constructor(context, config) {
+    this.context = context;
+    this.config = config;
+  }
+  async stateFor(sessionID) {
+    const existing = this.states.get(sessionID);
+    if (existing !== undefined) {
+      return existing;
+    }
+    const state = trackerStateFromMessages(await this.context.session.context({ sessionID }), this.config);
+    this.states.set(sessionID, state);
+    return state;
+  }
+  async markWriteRequiresRefresh(sessionID) {
+    const state = await this.stateFor(sessionID);
+    if (state.kind === "tracked") {
+      state.requiresRefreshBeforeWrite = true;
+    }
+  }
+  async register() {
+    let before;
+    let after;
+    let context;
+    try {
+      before = await this.context.tool.hook("execute.before", async (event) => {
+        const state = await this.stateFor(event.sessionID);
+        if (requiresTrackerRefresh(state, event.tool, this.config)) {
+          throw new Error(trackerRefreshMessage);
+        }
+        if (state.kind === "tracked") {
+          if (isWriteCapableTool(event.tool, this.config)) {
+            state.requiresRefreshBeforeWrite = true;
+          } else if (isReadOnlyTool(event.tool, this.config)) {
+            state.readToolsSinceRefresh += 1;
+          }
+        }
+      });
+      after = await this.context.tool.hook("execute.after", async (event) => {
+        if (event.status !== "completed") {
+          return;
+        }
+        if (event.tool === todoTrackerName) {
+          this.states.set(event.sessionID, refreshedTrackerState());
+          return;
+        }
+        const state = await this.stateFor(event.sessionID);
+        if (state.kind !== "tracked") {
+          return;
+        }
+      });
+      context = await this.context.session.hook("context", async (event) => {
+        const state = await this.stateFor(event.sessionID);
+        if (requiresTrackerRefreshBeforeMoreWork(state)) {
+          event.system.push({ type: "text", text: trackerRefreshMessage });
+        }
+      });
+      const beforeRegistration = before;
+      const afterRegistration = after;
+      const contextRegistration = context;
+      const controller = new AbortController;
+      const observer = this.observeSubagentCompletion(controller.signal);
+      return {
+        dispose: async () => {
+          controller.abort();
+          await Promise.all([
+            beforeRegistration.dispose(),
+            afterRegistration.dispose(),
+            contextRegistration.dispose(),
+            observer
+          ]);
+        }
+      };
+    } catch (error) {
+      await Promise.all([before?.dispose(), after?.dispose(), context?.dispose()]);
+      throw error;
+    }
+  }
+  async observeSubagentCompletion(signal) {
+    try {
+      for await (const event of this.context.event.subscribe({ signal })) {
+        if (event.type !== "session.idle") {
+          continue;
+        }
+        const session = await this.context.session.get({ sessionID: event.data.sessionID });
+        if (session.parentID !== undefined) {
+          await this.markWriteRequiresRefresh(session.parentID);
+        }
+      }
+    } catch (error) {
+      if (!signal.aborted) {
+        console.error("Unable to watch subagent completion for todo enforcement.", error);
+      }
+    }
+  }
+}
+
+class TodoTracker {
+  static marker(status) {
+    switch (status) {
+      case "pending":
+        return "[ ]";
+      case "in_progress":
+        return "[~]";
+      case "completed":
+        return "[x]";
+      case "cancelled":
+        return "[-]";
+    }
+  }
+  static sidebar(messages, completed = false) {
+    const todos = todosFromMessages(messages);
+    if (!completed) {
+      return todos;
+    }
+    return todos.map((todo) => todo.status === "pending" || todo.status === "in_progress" ? { ...todo, status: "completed" } : todo);
+  }
+  static async register(context, config) {
+    const tool = await context.tool.transform((tools) => {
+      tools.add({
+        name: todoTrackerName,
+        description: todoTrackerDescription,
+        input: todoTrackerInput,
+        options: { codemode: false },
+        async execute(input) {
+          if (!isTodoTrackerInput(input)) {
+            throw new Error("Invalid todotracker input.");
+          }
+          return { content: JSON.stringify(input.todos), metadata: { todos: input.todos } };
+        }
+      });
+    });
+    if (!config.enforceTodoTracker) {
+      return tool;
+    }
+    try {
+      const enforcement = await new TodoTrackerEnforcement(context, config).register();
+      return {
+        dispose: async () => {
+          try {
+            await enforcement.dispose();
+          } finally {
+            await tool.dispose();
+          }
+        }
+      };
+    } catch (error) {
+      await tool.dispose();
+      throw error;
+    }
+  }
+}
+
 // src/server/index.ts
 var server_default = Plugin.define({
   id: "@encoredigitalgroup/opencode",
@@ -135,7 +466,7 @@ var server_default = Plugin.define({
     const pluginConfig = ConfigLoader.loadConfig(ctx.options);
     const command = "feature-planning";
     const route = SkillCommands.getCommands(pluginConfig)[command];
-    const registration = await ctx.command.transform((commands) => {
+    const commandRegistration = await ctx.command.transform((commands) => {
       commands.add({
         name: command,
         description: route.description,
@@ -154,7 +485,20 @@ var server_default = Plugin.define({
         }
       });
     });
-    return registration.dispose;
+    let toolRegistration;
+    try {
+      toolRegistration = await TodoTracker.register(ctx, pluginConfig);
+    } catch (error) {
+      await commandRegistration.dispose();
+      throw error;
+    }
+    return async () => {
+      try {
+        await toolRegistration.dispose();
+      } finally {
+        await commandRegistration.dispose();
+      }
+    };
   }
 });
 export {