@ariane-emory/must-have-plugin 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ariane Emory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# A MUST-have plugin
+
+Automatically replaces text patterns in your prompts before they're sent to the LLM.
+
+## Installation
+
+### From npm
+
+Add the published package to your OpenCode config:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@ariane-emory/must-have-plugin"]
+}
+```
+
+OpenCode installs npm plugins automatically at startup.
+
+### From Source
+
+```bash
+npm install
+npm run build
+```
+
+Then copy the built file into your OpenCode plugins directory:
+
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp dist/index.js ~/.config/opencode/plugins/MUST-have-plugin.js
+```
+
+## What It Does
+
+Performs case-insensitive string replacements on user-typed prompts. The primary use case is auto-capitalizing RFC2119 keywords (MUST, SHOULD, MAY, etc.) in technical specifications.
+
+**Example**: Typing `"the system must validate input"` becomes `"the system MUST validate input"`.
+
+### Features
+
+- **Case-insensitive matching**: `must`, `Must`, and `MUST` all match
+- **Word boundary aware**: Won't replace `may` inside `maybe`
+- **Multi-word phrases**: `must not` is matched as a unit (before `must` alone)
+- **Hot reload**: Config changes take effect immediately (no restart needed)
+- **JSONC support**: Comments and trailing commas allowed in config file
+
+### Scope
+
+- Only replaces text in user-typed prompts
+- Does NOT modify file content attached via `@` mentions
+- Does NOT modify slash command output
+
+## Configuration
+
+**Config file**: `~/.config/opencode/MUST-have-plugin.jsonc`
+
+If the config file doesn't exist, it's automatically created with RFC2119 defaults.
+
+### Default Configuration
+
+```jsonc
+{
+  // Uncomment to enable debug logging (logs appear in OpenCode's log file)
+  // "debug": true,
+
+  "replacements": {
+    "must": "MUST",
+    "must not": "MUST NOT",
+    "required": "REQUIRED",
+    "shall": "SHALL",
+    "shall not": "SHALL NOT",
+    "should": "SHOULD",
+    "should not": "SHOULD NOT",
+    "recommended": "RECOMMENDED",
+    "not recommended": "NOT RECOMMENDED",
+    "may": "MAY",
+    "optional": "OPTIONAL"
+  }
+}
+```
+
+### Custom Replacements
+
+Add your own replacement pairs to the `replacements` object:
+
+```jsonc
+{
+  // Uncomment to enable debug logging (view with: tail -f /tmp/opencode-replacer-debug.log)
+  // "debug": true,
+
+  "replacements": {
+    "bl.md": "~/.config/opencode/supplemental/md/branch-list.md",
+    "dfp": "Diagnose and fix this problem: ",
+    "mnm": "Make no mistakes!",
+    "rfc!": "The key words \"**MUST**\", \"**MUST NOT**\", \"**REQUIRED**\", \"**SHALL**\", \"**SHALL NOT**\", \"**SHOULD**\", \"**SHOULD NOT**\", \"**RECOMMENDED**\", \"**MAY**\", and \"**OPTIONAL**\" in this message are to be interpreted as described in RFC2119.\n\n",
+
+    "pto": "push that to origin,",
+    "mb": "return to the initial branch and merge the new branch back in.",
+
+    "always": "**ALWAYS**",
+    "ever": "**EVER**",
+    "head": "HEAD",
+    "may not": "**MAY NOT**",
+    "may": "**MAY**",
+    "must always": "**MUST ALWAYS**",
+    "must never" : "**MUST NEVER**",
+    "must not" : "**MUST NOT**",
+    "must": "**MUST**",
+    "mustn't" : "**MUST NOT**",
+    "never": "**NEVER**",
+    "not recommended": "**NOT RECOMMENDED**",
+    "nothing": "**NOTHING**",
+    "not": "**NOT**",
+    "optional": "**OPTIONAL**",
+    "ought": "**SHOULD**",
+    "oughtn't": "**SHOULD NOT**",
+    "recommended": "**RECOMMENDED**",
+    "required": "**REQUIRED**",
+    "shall not": "**SHALL NOT**",
+    "shan't": "**SHALL NOT**",
+    "shall": "**SHALL**",
+    "should not": "**SHOULD NOT**",
+    "shouldn't": "**SHOULD NOT**",
+    "should": "**SHOULD**",
+  }
+}
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `debug` | boolean | `false` | Enable debug logging to OpenCode's log file |
+| `replacements` | object | RFC2119 keywords | Key-value pairs for text replacement |
+
+## Debug Logging
+
+Logs are written to OpenCode's unified log file using the SDK logging system.
+
+**Log location**: `~/.local/share/opencode/log/dev.log`
+
+Enable debug mode to see what replacements are being made:
+
+1. Edit `~/.config/opencode/MUST-have-plugin.jsonc`
+2. Uncomment or add `"debug": true`
+3. View logs in real-time (filtering by this plugin):
+
+```bash
+tail -f ~/.local/share/opencode/log/dev.log | grep "MUST-have-plugin"
+```
+
+Or view all recent plugin logs:
+
+```bash
+grep "MUST-have-plugin" ~/.local/share/opencode/log/dev.log | tail -20
+```
+
+### Log Format
+
+Logs use OpenCode's standard format with structured metadata:
+
+```
+INFO  2026-01-20T15:30:42 +2ms service=MUST-have-plugin Plugin loaded
+INFO  2026-01-20T15:31:05 +5ms service=MUST-have-plugin Applied 3 replacement(s) replacements={"must":{"value":"MUST","count":2},"should":{"value":"SHOULD","count":1}}
+```
+
+## RFC2119 Keywords
+
+The default configuration includes all keywords from [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119), which defines requirement levels for use in technical specifications:
+
+| Keyword | Meaning |
+|---------|---------|
+| MUST / REQUIRED / SHALL | Absolute requirement |
+| MUST NOT / SHALL NOT | Absolute prohibition |
+| SHOULD / RECOMMENDED | Recommended, but valid reasons may exist to ignore |
+| SHOULD NOT / NOT RECOMMENDED | Not recommended, but may be acceptable in some cases |
+| MAY / OPTIONAL | Truly optional |
+
+## Troubleshooting
+
+### Replacements not working
+
+1. Check that the config file exists: `cat ~/.config/opencode/MUST-have-plugin.jsonc`
+2. Verify JSONC syntax is valid (comments and trailing commas are allowed)
+3. Enable debug mode and check the log file
+
+### Unexpected replacements
+
+- Replacements use word boundaries, so `must` won't match inside `customer`
+- Multi-word phrases are matched first, so `must not` won't become `MUST not`
+- Check for typos in your replacement keys
+
+### Config changes not taking effect
+
+The plugin re-reads the config on every message, so changes should be immediate. If not:
+
+1. Verify you saved the config file
+2. Check for JSONC syntax errors
+3. Restart OpenCode as a last resort
+
+## Publishing
+
+```bash
+npm install
+npm login
+npm run build
+npm publish --access public
+```
+
+`npm publish` does not install dev dependencies for you. Run `npm install` first in a fresh checkout so `typescript` and `@types/node` are available for the `prepublishOnly` build.
+
+For a preflight check before publishing, run `npm publish --dry-run`.

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * MUST-have-plugin (Replacer Plugin)
+ *
+ * Performs case-insensitive string replacements on user-typed prompts
+ * before they're sent to the LLM.
+ *
+ * Config: ~/.config/opencode/MUST-have-plugin.jsonc (JSONC format)
+ * Logs: ~/.local/share/opencode/log/dev.log (filter by service=MUST-have-plugin)
+ *
+ * Features:
+ * - Case-insensitive matching with word boundaries
+ * - Multi-word phrase support (longest-first matching)
+ * - Hot reload: config re-read on every message
+ * - Auto-generates RFC2119 defaults if no config exists
+ * - JSONC support (comments and trailing commas allowed in config)
+ *
+ * Scope:
+ * - Only replaces in user-typed prompts
+ * - Does NOT modify file content attached via @ mentions
+ * - Does NOT modify slash command output
+ */
+import type { Plugin } from "@opencode-ai/plugin";
+/**
+ * MUST-have-plugin (Replacer Plugin)
+ */
+export declare const MustHavePlugin: Plugin;
+export default MustHavePlugin;

package/dist/index.js

@@ -0,0 +1,270 @@
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { resolve } from "path";
+const CONFIG_PATH = resolve(process.env.HOME || "", ".config", "opencode", "MUST-have-plugin.jsonc");
+const SERVICE_NAME = "MUST-have-plugin";
+// Track debug state (loaded from config)
+let debugEnabled = false;
+// SDK client reference for logging (set during plugin init)
+let sdkClient = null;
+// Track sessions that just executed a slash command (to skip replacement)
+const sessionsWithCommand = new Set();
+/**
+ * RFC2119 default replacements
+ * These keywords are used in technical specifications to indicate requirement levels.
+ * See: https://datatracker.ietf.org/doc/html/rfc2119
+ */
+const RFC2119_DEFAULTS = {
+    "must": "MUST",
+    "must not": "MUST NOT",
+    "required": "REQUIRED",
+    "shall": "SHALL",
+    "shall not": "SHALL NOT",
+    "should": "SHOULD",
+    "should not": "SHOULD NOT",
+    "recommended": "RECOMMENDED",
+    "not recommended": "NOT RECOMMENDED",
+    "may": "MAY",
+    "optional": "OPTIONAL",
+};
+/**
+ * Default config file content (JSONC format)
+ */
+const DEFAULT_CONFIG = `{
+  // Uncomment to enable debug logging (view in: ~/.local/share/opencode/log/dev.log)
+  // Filter with: grep "service=${SERVICE_NAME}" ~/.local/share/opencode/log/dev.log
+  // "debug": true,
+
+  "replacements": {
+    "must": "MUST",
+    "must not": "MUST NOT",
+    "required": "REQUIRED",
+    "shall": "SHALL",
+    "shall not": "SHALL NOT",
+    "should": "SHOULD",
+    "should not": "SHOULD NOT",
+    "recommended": "RECOMMENDED",
+    "not recommended": "NOT RECOMMENDED",
+    "may": "MAY",
+    "optional": "OPTIONAL"
+  }
+}
+`;
+/**
+ * Log a message using the OpenCode SDK logging system
+ * Logs appear in ~/.local/share/opencode/log/dev.log
+ */
+async function log(level, message, extra) {
+    if (!debugEnabled && level === "debug")
+        return;
+    if (!sdkClient)
+        return;
+    try {
+        await sdkClient.app.log({
+            body: {
+                service: SERVICE_NAME,
+                level,
+                message,
+                extra,
+            },
+        });
+    }
+    catch {
+        // Silently fail - logging should never break the plugin
+    }
+}
+/**
+ * Parse JSONC (JSON with Comments) by stripping comments before parsing
+ */
+function parseJSONC(content) {
+    // Strip single-line comments (// ...) - but not inside strings
+    // This is a simplified approach that works for typical config files
+    const lines = content.split("\n");
+    const strippedLines = lines.map((line) => {
+        // Find // that's not inside a string
+        let inString = false;
+        let escapeNext = false;
+        for (let i = 0; i < line.length; i++) {
+            const char = line[i];
+            if (escapeNext) {
+                escapeNext = false;
+                continue;
+            }
+            if (char === "\\") {
+                escapeNext = true;
+                continue;
+            }
+            if (char === '"') {
+                inString = !inString;
+                continue;
+            }
+            if (!inString && char === "/" && line[i + 1] === "/") {
+                return line.substring(0, i);
+            }
+        }
+        return line;
+    });
+    const stripped = strippedLines.join("\n");
+    // Also strip multi-line comments /* ... */
+    const noMultiLine = stripped.replace(/\/\*[\s\S]*?\*\//g, "");
+    // Strip trailing commas before ] or } (for JSONC compatibility)
+    const noTrailingCommas = noMultiLine.replace(/,(\s*[}\]])/g, "$1");
+    return JSON.parse(noTrailingCommas);
+}
+/**
+ * Create default config file with RFC2119 keywords if it doesn't exist
+ */
+function ensureConfigExists() {
+    if (!existsSync(CONFIG_PATH)) {
+        try {
+            writeFileSync(CONFIG_PATH, DEFAULT_CONFIG, "utf-8");
+            // Fire-and-forget log - don't block init
+            log("info", "Created default config", { path: CONFIG_PATH });
+        }
+        catch (error) {
+            // Fire-and-forget log - don't block init
+            log("error", "Failed to create default config", { error: String(error) });
+        }
+    }
+}
+/**
+ * Load and parse the config file
+ * Returns debug flag and replacements map
+ */
+function loadConfig() {
+    const defaultConfig = {
+        debug: false,
+        replacements: RFC2119_DEFAULTS,
+    };
+    try {
+        if (!existsSync(CONFIG_PATH)) {
+            return defaultConfig;
+        }
+        const content = readFileSync(CONFIG_PATH, "utf-8");
+        const parsed = parseJSONC(content);
+        return {
+            debug: parsed.debug === true,
+            replacements: parsed.replacements || {},
+        };
+    }
+    catch (error) {
+        // Log to stderr since SDK client might not be ready yet
+        process.stderr.write(`MUST-have-plugin: [WARN] Failed to parse config: ${error}\n`);
+        return defaultConfig;
+    }
+}
+/**
+ * Escape special regex characters in a string
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Apply all replacements to the given text
+ * - Case-insensitive matching
+ * - Word boundary aware (won't replace "must" inside "customer")
+ * - Won't match inside markdown formatting (won't replace MUST inside **MUST**)
+ * - Single-pass: all patterns matched at once to prevent re-replacement
+ */
+function applyReplacements(text, replacements) {
+    if (Object.keys(replacements).length === 0) {
+        return { result: text, counts: new Map() };
+    }
+    // Sort keys by length descending (longest first) for proper matching priority
+    const sortedKeys = Object.keys(replacements).sort((a, b) => b.length - a.length);
+    // Build a single regex that matches any of the patterns
+    // Uses negative lookbehind/lookahead to exclude matches inside markdown formatting
+    // (?<![a-zA-Z*_'']) = not preceded by letter, asterisk, underscore, or apostrophe
+    // (?![a-zA-Z*_'']) = not followed by letter, asterisk, underscore, or apostrophe
+    const patternStrings = sortedKeys.map((key) => `(?<![a-zA-Z*_''])${escapeRegex(key)}(?![a-zA-Z*_''])`);
+    const combinedPattern = new RegExp(`(${patternStrings.join("|")})`, "gi");
+    // Build a case-insensitive lookup map
+    const lookup = new Map();
+    for (const key of sortedKeys) {
+        lookup.set(key.toLowerCase(), replacements[key]);
+    }
+    const counts = new Map();
+    // Single-pass replacement: each match is replaced exactly once
+    let lastIndex = 0;
+    let result = "";
+    let match;
+    while ((match = combinedPattern.exec(text)) !== null) {
+        const replacement = lookup.get(match[0].toLowerCase());
+        if (replacement) {
+            counts.set(match[0].toLowerCase(), (counts.get(match[0].toLowerCase()) || 0) + 1);
+            result += text.slice(lastIndex, match.index) + replacement;
+            lastIndex = match.index + match[0].length;
+            // If replacement ends with whitespace, consume trailing space from original text
+            if (/\s$/.test(replacement) && text[lastIndex] === " ") {
+                lastIndex++;
+            }
+        }
+        else {
+            result += text.slice(lastIndex, match.index) + match[0];
+            lastIndex = match.index + match[0].length;
+        }
+    }
+    result += text.slice(lastIndex);
+    return { result, counts };
+}
+/**
+ * MUST-have-plugin (Replacer Plugin)
+ */
+export const MustHavePlugin = async ({ client }) => {
+    // Store SDK client for logging
+    sdkClient = client;
+    // Ensure default config exists (synchronous)
+    ensureConfigExists();
+    // Initial config load to get debug state
+    const initialConfig = loadConfig();
+    debugEnabled = initialConfig.debug;
+    // Fire-and-forget log during init - don't await to avoid blocking startup
+    log("info", "Plugin loaded", {
+        configPath: CONFIG_PATH,
+        replacementCount: Object.keys(initialConfig.replacements).length,
+    });
+    return {
+        "command.execute.before": async (input) => {
+            sessionsWithCommand.add(input.sessionID);
+            await log("debug", "Tracking command execution", { sessionID: input.sessionID, command: input.command });
+        },
+        "chat.message": async (input, output) => {
+            // Skip processing if this message came from a slash command execution
+            if (sessionsWithCommand.has(input.sessionID)) {
+                sessionsWithCommand.delete(input.sessionID);
+                await log("debug", "Skipping replacements - message from slash command", { sessionID: input.sessionID });
+                return;
+            }
+            // Hot reload: re-read config on every message
+            const config = loadConfig();
+            debugEnabled = config.debug;
+            if (Object.keys(config.replacements).length === 0) {
+                await log("debug", "No replacements configured, skipping");
+                return;
+            }
+            let totalReplacements = 0;
+            const allCounts = new Map();
+            // Apply to user-typed text only (not file content, not slash command output, not synthetic)
+            // User-typed content: type === "text" && synthetic !== true
+            for (const part of output.parts) {
+                if (part.type === "text" && "text" in part && typeof part.text === "string" && !part.synthetic) {
+                    const { result, counts } = applyReplacements(part.text, config.replacements);
+                    part.text = result;
+                    // Merge counts
+                    for (const [key, count] of counts) {
+                        allCounts.set(key, (allCounts.get(key) || 0) + count);
+                        totalReplacements += count;
+                    }
+                }
+            }
+            // Log replacements made
+            if (totalReplacements > 0) {
+                const replacements = {};
+                for (const [key, count] of allCounts) {
+                    replacements[key] = { value: config.replacements[key], count };
+                }
+                await log("info", `Applied ${totalReplacements} replacement(s)`, { replacements });
+            }
+        },
+    };
+};
+export default MustHavePlugin;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@ariane-emory/must-have-plugin",
+  "version": "1.0.0",
+  "description": "OpenCode plugin that applies configurable prompt text replacements, including RFC2119 keyword capitalization.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "rfc2119",
+    "text-replacement"
+  ],
+  "author": "Ariane Emory",
+  "license": "MIT",
+  "homepage": "https://github.com/ariane-emory/MUST-have-plugin#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ariane-emory/MUST-have-plugin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ariane-emory/MUST-have-plugin/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.4.3",
+    "@types/node": "^22.13.9",
+    "typescript": "^5.8.2"
+  }
+}