opencode-agent-modes 0.1.1 → 0.2.0

package/README.md

@@ -147,7 +147,38 @@ To add a custom preset (e.g., "premium"):
 
 3. Restart opencode to apply changes.
 
-## Notes
+> [!INFO]
+> - Changes require an opencode restart to take effect
+> - Custom mode presets can be added by editing the configuration file
 
-- Changes require an opencode restart to take effect
-- Custom mode presets can be added by editing the configuration file
+## Development
+
+This project uses [Bun](https://bun.sh/) as the runtime and package manager.
+
+### Prerequisites
+
+- [Bun](https://bun.sh/) v1.0 or later
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/j4rviscmd/opencode-agent-modes.git
+cd opencode-agent-modes
+
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Type check
+bun run typecheck
+
+# Lint & format
+bun run lint
+bun run format
+
+# Build
+bun run build
+```

package/dist/config/command-installer.d.ts

@@ -1,9 +1,34 @@
+/**
+ * @fileoverview Command file installer for OpenCode slash commands.
+ *
+ * This module handles copying slash command markdown files from the plugin's
+ * commands directory to OpenCode's configuration directory during plugin
+ * initialization. This ensures command files are available without requiring
+ * manual postinstall script execution.
+ *
+ * @module config/command-installer
+ */
 /**
  * Copies slash command markdown files to OpenCode's command directory.
  *
  * This function is called during plugin initialization to ensure
  * command files are available without manual postinstall execution.
+ * It creates the destination directory if it doesn't exist and copies
+ * all `.md` files from the source commands directory.
+ *
+ * The function is designed to be non-fatal: if copying fails (e.g., due to
+ * permission issues), it logs a warning but doesn't throw an error,
+ * allowing the plugin to continue initializing.
+ *
+ * @returns Number of files successfully copied, or -1 if source directory
+ *          not found or an error occurred during copying
  *
- * @returns Number of files copied, or -1 if source directory not found
+ * @example
+ * ```typescript
+ * const copied = copyCommandFiles();
+ * if (copied > 0) {
+ *   console.log(`Copied ${copied} command files`);
+ * }
+ * ```
  */
 export declare function copyCommandFiles(): number;

package/dist/config/initializer.d.ts

@@ -1,10 +1,46 @@
 import type { ModeSwitcherConfig } from './types.ts';
 /**
- * Initialize the plugin configuration if it doesn't exist
- * @returns The configuration (existing or newly created)
+ * Initializes the plugin configuration if it doesn't exist.
+ *
+ * This function performs the following steps:
+ * 1. Checks if a configuration file already exists
+ * 2. If exists, loads and returns it
+ * 3. If not, creates a new configuration by:
+ *    - Building a performance preset from current settings
+ *    - Building an economy preset with free models
+ *    - Setting default mode to "performance"
+ *    - Saving the configuration to disk
+ *
+ * This is called on plugin startup to ensure a valid configuration
+ * is always available.
+ *
+ * @returns Promise resolving to the configuration (existing or newly created)
+ * @throws {Error} If configuration creation or file I/O fails
+ * @example
+ * ```typescript
+ * const config = await initializeConfig();
+ * console.log(config.currentMode); // "performance"
+ * ```
  */
 export declare function initializeConfig(): Promise<ModeSwitcherConfig>;
 /**
- * Ensure configuration is valid and has required presets
+ * Validates that a configuration object is well-formed and has required presets.
+ *
+ * This function performs the following checks:
+ * - `currentMode` field is present and non-empty
+ * - `presets` object exists and contains at least one preset
+ * - A preset exists for the current mode
+ *
+ * @param config - The configuration object to validate
+ * @returns True if configuration is valid, false otherwise
+ * @example
+ * ```typescript
+ * const config = await loadPluginConfig();
+ * if (validateConfig(config)) {
+ *   console.log('Configuration is valid');
+ * } else {
+ *   console.error('Invalid configuration detected');
+ * }
+ * ```
  */
 export declare function validateConfig(config: ModeSwitcherConfig): boolean;

package/dist/config/loader.d.ts

@@ -1,4 +1,4 @@
-import type { ModeSwitcherConfig, OpencodeConfig, OhMyOpencodeConfig } from './types.ts';
+import type { ModeSwitcherConfig, OhMyOpencodeConfig, OpencodeConfig } from './types.ts';
 /**
  * Expands tilde (~) notation to the user's home directory path.
  *

package/dist/index.d.ts

@@ -1,9 +1,34 @@
-import type { Plugin } from "@opencode-ai/plugin";
 /**
- * OpenCode Agent Mode Switcher Plugin
+ * @fileoverview OpenCode Agent Mode Switcher Plugin.
  *
- * Allows switching between different agent mode presets (e.g., performance vs economy)
- * that configure which AI models are used for each agent type.
+ * This plugin provides tools for managing agent mode presets in OpenCode.
+ * It allows users to switch between different configurations (e.g., performance
+ * vs economy modes) that determine which AI models are used for each agent type.
+ *
+ * @module index
+ */
+import type { Plugin } from '@opencode-ai/plugin';
+/**
+ * OpenCode Agent Mode Switcher Plugin.
+ *
+ * Provides tools for switching between agent mode presets (e.g., performance
+ * vs economy) that configure which AI models are used for each agent type.
+ * The plugin initializes on startup by loading configurations and copying
+ * slash command files to the OpenCode command directory.
+ *
+ * @param params - Plugin initialization parameters
+ * @param params.client - OpenCode client for SDK interactions
+ * @returns Plugin object containing mode management tools
+ *
+ * @example
+ * ```typescript
+ * // Plugin is automatically loaded by OpenCode
+ * // Users can then use slash commands:
+ * // /mode-performance
+ * // /mode-economy
+ * // /mode-status
+ * // /mode-list
+ * ```
  */
 declare const modeSwitcherPlugin: Plugin;
 export default modeSwitcherPlugin;

package/dist/index.js

@@ -12330,6 +12330,8 @@ function tool(input) {
   return input;
 }
 tool.schema = exports_external;
+// src/config/types.ts
+var DEFAULT_ECONOMY_MODEL = "opencode/glm-4.7-free";
 // src/config/loader.ts
 import { homedir } from "os";
 import { join } from "path";
@@ -13790,13 +13792,8 @@ async function saveOhMyOpencodeConfig(config2) {
   await saveJsonFile(getOhMyOpencodeConfigPath(), config2);
 }
 async function pluginConfigExists() {
-  const file2 = Bun.file(getPluginConfigPath());
-  return await file2.exists();
+  return Bun.file(getPluginConfigPath()).exists();
 }
-
-// src/config/types.ts
-var DEFAULT_ECONOMY_MODEL = "opencode/glm-4.7-free";
-
 // src/config/initializer.ts
 var OPENCODE_AGENTS = [
   "build",
@@ -13882,7 +13879,37 @@ async function initializeConfig() {
   await savePluginConfig(config2);
   return config2;
 }
-
+// src/config/command-installer.ts
+import { copyFileSync, existsSync, mkdirSync, readdirSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { dirname, join as join2 } from "path";
+import { fileURLToPath } from "url";
+var COMMANDS_DEST = join2(homedir2(), ".config", "opencode", "command");
+function findCommandsDir() {
+  const __dirname2 = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join2(__dirname2, "..", "commands"),
+    join2(__dirname2, "..", "..", "commands")
+  ];
+  return candidates.find(existsSync) ?? null;
+}
+function copyCommandFiles() {
+  const commandsSrc = findCommandsDir();
+  if (!commandsSrc) {
+    return -1;
+  }
+  try {
+    mkdirSync(COMMANDS_DEST, { recursive: true });
+    const files = readdirSync(commandsSrc).filter((f) => f.endsWith(".md"));
+    for (const file2 of files) {
+      copyFileSync(join2(commandsSrc, file2), join2(COMMANDS_DEST, file2));
+    }
+    return files.length;
+  } catch (error45) {
+    console.warn("[agent-mode-switcher] Warning: Could not copy command files:", error45 instanceof Error ? error45.message : String(error45));
+    return -1;
+  }
+}
 // src/modes/manager.ts
 class ModeManager {
   client;
@@ -13892,6 +13919,7 @@ class ModeManager {
   }
   async initialize() {
     this.config = await initializeConfig();
+    await this.applyCurrentModeIfNeeded();
   }
   async ensureConfig() {
     if (!this.config) {
@@ -13899,6 +13927,55 @@ class ModeManager {
     }
     return this.config;
   }
+  async applyCurrentModeIfNeeded() {
+    if (!this.config) {
+      return;
+    }
+    const preset = this.config.presets[this.config.currentMode];
+    if (!preset) {
+      return;
+    }
+    const drifted = await this.hasConfigDrift(preset);
+    if (!drifted) {
+      return;
+    }
+    await this.updateOpencodeConfig(preset.model, preset.opencode);
+    await this.updateOhMyOpencodeConfig(preset["oh-my-opencode"]);
+    this.client.tui.showToast({
+      body: {
+        title: "Mode Applied",
+        message: `Applied "${this.config.currentMode}" mode. Restart opencode to take effect.`,
+        variant: "warning",
+        duration: 5000
+      }
+    }).catch(() => {});
+  }
+  async hasConfigDrift(preset) {
+    const opencodeConfig = await loadOpencodeConfig();
+    const ohMyConfig = await loadOhMyOpencodeConfig();
+    if (preset.model && opencodeConfig) {
+      if (opencodeConfig.model !== preset.model) {
+        return true;
+      }
+    }
+    if (opencodeConfig?.agent) {
+      for (const [agentName, agentPreset] of Object.entries(preset.opencode)) {
+        const actual = opencodeConfig.agent[agentName];
+        if (actual?.model !== agentPreset.model) {
+          return true;
+        }
+      }
+    }
+    if (ohMyConfig?.agents) {
+      for (const [agentName, agentPreset] of Object.entries(preset["oh-my-opencode"])) {
+        const actual = ohMyConfig.agents[agentName];
+        if (actual?.model !== agentPreset.model) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
   async getCurrentMode() {
     const config2 = await this.ensureConfig();
     return config2.currentMode;
@@ -13989,14 +14066,12 @@ ${modes}`;
       if (globalModel) {
         opencodeConfig.model = globalModel;
       }
-      if (Object.keys(agentPresets).length > 0) {
-        opencodeConfig.agent = opencodeConfig.agent || {};
-        for (const [agentName, preset] of Object.entries(agentPresets)) {
-          opencodeConfig.agent[agentName] = {
-            ...opencodeConfig.agent[agentName],
-            model: preset.model
-          };
-        }
+      opencodeConfig.agent = opencodeConfig.agent || {};
+      for (const [agentName, preset] of Object.entries(agentPresets)) {
+        opencodeConfig.agent[agentName] = {
+          ...opencodeConfig.agent[agentName],
+          model: preset.model
+        };
       }
       await saveOpencodeConfig(opencodeConfig);
       return "updated";
@@ -14027,31 +14102,6 @@ ${modes}`;
     return config2.showToastOnStartup;
   }
 }
-// src/config/command-installer.ts
-import { copyFileSync, mkdirSync, readdirSync, existsSync } from "fs";
-import { homedir as homedir2 } from "os";
-import { dirname, join as join2 } from "path";
-import { fileURLToPath } from "url";
-var COMMANDS_DEST = join2(homedir2(), ".config", "opencode", "command");
-function copyCommandFiles() {
-  const __dirname2 = dirname(fileURLToPath(import.meta.url));
-  const commandsSrc = join2(__dirname2, "..", "..", "commands");
-  if (!existsSync(commandsSrc)) {
-    console.warn("[agent-mode-switcher] Commands directory not found:", commandsSrc);
-    return -1;
-  }
-  try {
-    mkdirSync(COMMANDS_DEST, { recursive: true });
-    const files = readdirSync(commandsSrc).filter((f) => f.endsWith(".md"));
-    for (const file2 of files) {
-      copyFileSync(join2(commandsSrc, file2), join2(COMMANDS_DEST, file2));
-    }
-    return files.length;
-  } catch (error45) {
-    console.warn("[agent-mode-switcher] Warning: Could not copy command files:", error45 instanceof Error ? error45.message : String(error45));
-    return -1;
-  }
-}
 // src/index.ts
 var modeSwitcherPlugin = async ({ client }) => {
   const modeManager = new ModeManager(client);

package/dist/modes/manager.d.ts

@@ -1,54 +1,233 @@
 import type { OpencodeClient } from '@opencode-ai/sdk';
 import type { ModePreset } from '../config/types.ts';
 /**
- * Manages agent mode switching between different presets
+ * Manages agent mode switching between different presets.
+ *
+ * This class provides the core functionality for switching between
+ * performance and economy modes (or custom presets). It handles:
+ * - Loading and managing plugin configuration
+ * - Switching between different model presets
+ * - Updating OpenCode configuration files
+ * - Providing status and listing available modes
+ *
+ * The manager updates three configuration files when switching modes:
+ * - `~/.config/opencode/agent-mode-switcher.json` (plugin state)
+ * - `~/.config/opencode/opencode.json` (OpenCode agents)
+ * - `~/.config/opencode/oh-my-opencode.json` (oh-my-opencode agents)
+ *
+ * @example
+ * ```typescript
+ * const manager = new ModeManager(client);
+ * await manager.initialize();
+ *
+ * // Switch to economy mode
+ * const result = await manager.switchMode('economy');
+ * console.log(result);
+ *
+ * // Get current status
+ * const status = await manager.getStatus();
+ * console.log(status);
+ * ```
  */
 export declare class ModeManager {
     private readonly client;
     private config;
     constructor(client: OpencodeClient);
     /**
-     * Initialize the mode manager and load configuration
+     * Initializes the mode manager and loads configuration.
+     *
+     * This method should be called before using any other manager methods.
+     * It loads or creates the plugin configuration file, ensuring all
+     * required presets are available.
+     *
+     * @throws {Error} If configuration initialization fails
+     * @example
+     * ```typescript
+     * const manager = new ModeManager(client);
+     * await manager.initialize();
+     * ```
      */
     initialize(): Promise<void>;
     /**
-     * Ensure configuration is loaded
+     * Ensures configuration is loaded before any operation.
+     *
+     * This internal method is called by all public methods to lazily
+     * initialize the configuration if it hasn't been loaded yet.
+     *
+     * @returns Promise resolving to the loaded configuration
+     * @throws {Error} If configuration loading fails
+     * @private
      */
     private ensureConfig;
     /**
-     * Get the current mode name
+     * Checks if actual config files have drifted from the current
+     * mode preset and applies the preset if needed.
+     *
+     * This handles the case where a user manually edits
+     * `agent-mode-switcher.json` to change `currentMode` while
+     * OpenCode is not running. On next startup, the actual config
+     * files are updated to match the expected preset values,
+     * and a toast notification prompts the user to restart.
+     *
+     * @private
+     */
+    private applyCurrentModeIfNeeded;
+    /**
+     * Compares a mode preset against the actual opencode.json and
+     * oh-my-opencode.json files to detect configuration drift.
+     *
+     * Checks global model and per-agent model values. Returns true
+     * if any expected value differs from the actual file content.
+     *
+     * @param preset - The mode preset to compare against
+     * @returns True if actual configs differ from the preset
+     * @private
+     */
+    private hasConfigDrift;
+    /**
+     * Gets the name of the currently active mode.
+     *
+     * @returns Promise resolving to the current mode name (e.g., "performance", "economy")
+     * @example
+     * ```typescript
+     * const currentMode = await manager.getCurrentMode();
+     * console.log(`Current mode: ${currentMode}`);
+     * ```
      */
     getCurrentMode(): Promise<string>;
     /**
-     * Get a specific preset by name
+     * Gets a specific mode preset by name.
+     *
+     * @param modeName - The name of the mode to retrieve (e.g., "performance", "economy")
+     * @returns Promise resolving to the preset configuration, or undefined if not found
+     * @example
+     * ```typescript
+     * const preset = await manager.getPreset('economy');
+     * if (preset) {
+     *   console.log(preset.description);
+     *   console.log(preset.model);
+     * }
+     * ```
      */
     getPreset(modeName: string): Promise<ModePreset | undefined>;
     /**
-     * Get all available mode names
+     * Gets a formatted list of all available modes.
+     *
+     * Returns a multi-line string listing each mode with its description,
+     * marking the currently active mode with "(current)".
+     *
+     * @returns Promise resolving to formatted string listing all available modes
+     * @example
+     * ```typescript
+     * const list = await manager.listModes();
+     * console.log(list);
+     * // Output:
+     * // Available modes:
+     * // - performance (current): High-performance models for complex tasks
+     * // - economy: Cost-efficient free model for routine tasks
+     * ```
      */
     listModes(): Promise<string>;
     /**
-     * Get current status including mode and agent configurations
+     * Gets detailed status information for the current mode.
+     *
+     * Returns a formatted multi-line string showing:
+     * - Current mode name and description
+     * - Global model setting (if configured)
+     * - All OpenCode agents and their assigned models
+     * - All oh-my-opencode agents and their assigned models
+     *
+     * @returns Promise resolving to formatted status string
+     * @example
+     * ```typescript
+     * const status = await manager.getStatus();
+     * console.log(status);
+     * // Output:
+     * // Current mode: performance
+     * // Description: High-performance models for complex tasks
+     * // Global model: (not set)
+     * //
+     * // OpenCode agents:
+     * //   - build: anthropic/claude-sonnet-4
+     * //   - plan: anthropic/claude-sonnet-4
+     * // ...
+     * ```
      */
     getStatus(): Promise<string>;
     /**
-     * Switch to a different mode
+     * Switches to a different mode by updating all configuration files.
+     *
+     * This method performs the following operations:
+     * 1. Validates that the requested mode exists
+     * 2. Updates `opencode.json` with new global model and agent settings
+     * 3. Updates `oh-my-opencode.json` with new agent settings
+     * 4. Updates `agent-mode-switcher.json` with the new current mode
+     * 5. Shows a toast notification (if available)
+     *
+     * Configuration files that don't exist are skipped with a warning.
+     * Changes take effect after restarting OpenCode.
+     *
+     * @param modeName - The name of the mode to switch to
+     * @returns Promise resolving to a formatted result message with status of each config update
+     * @example
+     * ```typescript
+     * const result = await manager.switchMode('economy');
+     * console.log(result);
+     * // Output:
+     * // Switched to economy mode
+     * // Cost-efficient free model for routine tasks
+     * //
+     * // Results:
+     * //   - opencode.json: updated
+     * //   - oh-my-opencode.json: updated
+     * //   - agent-mode-switcher.json: updated
+     * //
+     * // Note: Restart opencode to apply changes.
+     * ```
      */
     switchMode(modeName: string): Promise<string>;
     /**
-     * Update opencode.json with global model and agent section
-     * @param globalModel - Global model setting (optional)
-     * @param agentPresets - Agent-specific model settings
-     * @returns Result status: "updated", "skipped (not found)", or "error: ..."
+     * Updates opencode.json with global model and agent section.
+     *
+     * This internal method modifies the OpenCode configuration file to apply
+     * the new preset's settings. It preserves other configuration properties
+     * and only updates model-related fields.
+     *
+     * @param globalModel - Global model setting (optional). If provided, sets the top-level "model" field
+     * @param agentPresets - Agent-specific model settings. Keys are agent names, values contain model strings
+     * @returns Promise resolving to result status: "updated", "skipped (not found)", or "error: ..."
+     * @private
      */
     private updateOpencodeConfig;
     /**
-     * Update oh-my-opencode.json agents section with preset values
-     * @returns Result status: "updated", "skipped (not found)", or "error: ..."
+     * Updates oh-my-opencode.json agents section with preset values.
+     *
+     * This internal method modifies the oh-my-opencode configuration file
+     * to apply the new preset's agent settings. Unlike opencode.json, this
+     * only updates the agents section and doesn't set a global model.
+     *
+     * @param agentPresets - Agent-specific model settings. Keys are agent names, values contain model strings
+     * @returns Promise resolving to result status: "updated", "skipped (not found)", or "error: ..."
+     * @private
      */
     private updateOhMyOpencodeConfig;
     /**
-     * Check if toast should be shown on startup
+     * Checks if a toast notification should be shown on plugin startup.
+     *
+     * This is controlled by the `showToastOnStartup` configuration flag,
+     * which can be useful for reminding users of the current mode when
+     * OpenCode starts.
+     *
+     * @returns Promise resolving to true if toast should be shown, false otherwise
+     * @example
+     * ```typescript
+     * if (await manager.shouldShowToastOnStartup()) {
+     *   const mode = await manager.getCurrentMode();
+     *   await client.tui.showToast({
+     *     body: { message: `Current mode: ${mode}` }
+     *   });
+     * }
+     * ```
      */
     shouldShowToastOnStartup(): Promise<boolean>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-agent-modes",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "OpenCode plugin to switch agent modes between performance and economy presets",
   "module": "src/index.ts",
   "main": "dist/index.js",
@@ -25,29 +25,23 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun build src/index.ts --outdir dist --format esm --target bun && tsc -p tsconfig.build.json",
-    "lint": "bunx biome check src/",
-    "format": "prettier --write 'src/**/*.ts'",
-    "format:check": "prettier --check 'src/**/*.ts'",
+    "lint": "bunx biome check .",
+    "format": "bunx biome format --write .",
+    "format:check": "bunx biome format .",
     "test": "bun test",
     "test:watch": "bun test --watch",
     "test:coverage": "bun test --coverage",
     "prepublishOnly": "bun run build"
   },
-  "keywords": [
-    "opencode",
-    "plugin",
-    "agent",
-    "mode",
-    "switcher"
-  ],
+  "keywords": ["opencode", "plugin", "agent", "mode", "switcher"],
   "author": "j4rviscmd",
   "license": "MIT",
   "engines": {
     "node": ">=18"
   },
   "devDependencies": {
-    "@types/bun": "latest",
-    "prettier": "^3.8.0"
+    "@biomejs/biome": "^1.9.4",
+    "@types/bun": "latest"
   },
   "peerDependencies": {
     "typescript": "^5"