opencode-ascii 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 db
+
+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,132 @@
+# opencode-ascii
+
+An [OpenCode](https://opencode.ai) plugin that automatically substitutes unicode characters with ASCII equivalents in AI responses and file edits.
+
+## Why?
+
+LLMs love to reach for typographic characters — em-dashes, curly quotes, arrows, emoji — that look great in a browser but cause friction in terminals, code, config files, and plain-text tooling. This plugin intercepts output at two points:
+
+- **AI text responses** (`experimental.text.complete`) — rewrites text parts before they are stored.
+- **File write/edit tool calls** (`tool.execute.before`) — rewrites `write`, `edit`, and `patch` tool arguments before execution.
+
+## Installation
+
+Add the package to your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-ascii"]
+}
+```
+
+OpenCode will install the package automatically via Bun at startup.
+
+## Configuration
+
+All four substitution categories are **enabled by default**. Disable any category by passing options:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["opencode-ascii", {
+      "punctuation": true,
+      "arrows": true,
+      "math": true,
+      "emojis": false
+    }]
+  ]
+}
+```
+
+| Option        | Type    | Default | Description                                  |
+|---------------|---------|---------|----------------------------------------------|
+| `punctuation` | boolean | `true`  | Em/en dashes, ellipsis, curly/smart quotes   |
+| `arrows`      | boolean | `true`  | `→` → `->`, `←` → `<-`, `⇒` → `=>`, etc.  |
+| `math`        | boolean | `true`  | `≠` → `!=`, `≤` → `<=`, `×` → `*`, etc.   |
+| `emojis`      | boolean | `true`  | Common emoji → short ASCII labels            |
+
+## Substitution reference
+
+### Punctuation
+
+| Unicode | Character | ASCII |
+|---------|-----------|-------|
+| U+2014  | — | `--` |
+| U+2013  | – | `-` |
+| U+2026  | … | `...` |
+| U+201C  | " | `"` |
+| U+201D  | " | `"` |
+| U+2018  | ' | `'` |
+| U+2019  | ' | `'` |
+| U+00AB  | « | `"` |
+| U+00BB  | » | `"` |
+| U+2022  | • | `-` |
+
+### Arrows
+
+| Unicode | Character | ASCII |
+|---------|-----------|-------|
+| U+2192  | → | `->` |
+| U+2190  | ← | `<-` |
+| U+2191  | ↑ | `^` |
+| U+2193  | ↓ | `v` |
+| U+21D2  | ⇒ | `=>` |
+| U+21D0  | ⇐ | `<=` |
+| U+21D4  | ⇔ | `<=>` |
+| U+2194  |  | `<->` |
+
+### Math operators
+
+| Unicode | Character | ASCII |
+|---------|-----------|-------|
+| U+2260  | ≠ | `!=` |
+| U+2264  | ≤ | `<=` |
+| U+2265  | ≥ | `>=` |
+| U+00D7  | × | `*` |
+| U+00F7  | ÷ | `/` |
+| U+00B1  | ± | `+/-` |
+| U+2212  | − | `-` |
+| U+221E  | ∞ | `inf` |
+| U+2248  | ≈ | `~=` |
+| U+221A  | √ | `sqrt` |
+
+### Emojis
+
+| Unicode | Character | ASCII |
+|---------|-----------|-------|
+| U+2713  | ✓ | `[x]` |
+| U+274C  |  | `[!]` |
+| U+26A0  |  | `[!]` |
+| U+2139  |  | `[i]` |
+| U+2B50  |  | `[*]` |
+| U+1F525 |  | `[fire]` |
+| U+1F680 |  | `[>>]` |
+| U+1F41B |  | `[bug]` |
+| U+1F4DD |  | `[note]` |
+| U+1F512 |  | `[lock]` |
+| U+1F513 |  | `[open]` |
+| U+1F4C1 |  | `[dir]` |
+| U+1F4C4 |  | `[file]` |
+| U+1F44D |  | `[+1]` |
+| U+1F44E |  | `[-1]` |
+
+See [`src/substitutions.ts`](src/substitutions.ts) for the full list.
+
+## How it works
+
+The plugin uses two hooks:
+
+1. **`experimental.text.complete`** — fired by OpenCode after each AI text part finishes streaming. The plugin rewrites `output.text` in place before it is persisted.
+
+2. **`tool.execute.before`** — fired before any tool executes. The plugin rewrites:
+   - `output.args.content` for the `write` tool
+   - `output.args.newString` for the `edit` tool (never `oldString` — it must match existing file content exactly)
+   - `output.args.patch` for the `patch` tool
+
+Substitution uses a single compiled regex built from all active mappings, so there is no O(n) string-replace loop per character.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import { type SubstitutionConfig } from "./substitutions.js";
+/**
+ * Options accepted by AsciiPlugin.
+ *
+ * All categories default to `true` (enabled).
+ * Set a category to `false` to skip substitution for it.
+ *
+ * @example
+ * // opencode.json — disable emoji and math substitutions
+ * {
+ *   "plugin": [["opencode-ascii", { "emojis": false, "math": false }]]
+ * }
+ */
+export type AsciiPluginOptions = SubstitutionConfig;
+/**
+ * AsciiPlugin — substitutes unicode characters with ASCII equivalents
+ * in AI responses and file write/edit operations.
+ *
+ * Covered hooks:
+ *  - `experimental.text.complete` : rewrites completed AI text parts
+ *  - `tool.execute.before`        : rewrites `write` and `edit` tool arguments
+ */
+export declare const AsciiPlugin: Plugin;

package/dist/index.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsciiPlugin = void 0;
+const substitutions_js_1 = require("./substitutions.js");
+function resolveConfig(options) {
+    if (!options)
+        return {};
+    const config = {};
+    if (typeof options["punctuation"] === "boolean")
+        config.punctuation = options["punctuation"];
+    if (typeof options["arrows"] === "boolean")
+        config.arrows = options["arrows"];
+    if (typeof options["math"] === "boolean")
+        config.math = options["math"];
+    if (typeof options["emojis"] === "boolean")
+        config.emojis = options["emojis"];
+    return config;
+}
+/**
+ * AsciiPlugin — substitutes unicode characters with ASCII equivalents
+ * in AI responses and file write/edit operations.
+ *
+ * Covered hooks:
+ *  - `experimental.text.complete` : rewrites completed AI text parts
+ *  - `tool.execute.before`        : rewrites `write` and `edit` tool arguments
+ */
+const AsciiPlugin = async (_ctx, options) => {
+    const config = resolveConfig(options);
+    const substitutions = (0, substitutions_js_1.buildSubstitutions)(config);
+    if (substitutions.length === 0) {
+        // All categories disabled — nothing to do.
+        return {};
+    }
+    const map = new Map(substitutions);
+    // Reset regex lastIndex before reuse by always using a fresh call to
+    // buildRegex; the 'g' flag is stateful so we rebuild per call or use
+    // a factory. We build once and rely on String.prototype.replace resetting it.
+    const regex = (0, substitutions_js_1.buildRegex)(substitutions);
+    function substitute(text) {
+        // Reset the regex state (stateful with /g flag)
+        regex.lastIndex = 0;
+        return (0, substitutions_js_1.applySubstitutions)(text, regex, map);
+    }
+    return {
+        /**
+         * Rewrite completed AI text parts before they are stored.
+         * `experimental.text.complete` fires once per text part after the
+         * streaming is done, giving us `output.text` to modify in place.
+         */
+        "experimental.text.complete": async (_input, output) => {
+            if (typeof output.text === "string") {
+                output.text = substitute(output.text);
+            }
+        },
+        /**
+         * Rewrite file-writing tool arguments before execution.
+         *
+         * Tools handled:
+         *  - `write`  : `args.content`
+         *  - `edit`   : `args.newString` (NOT `oldString` — it must match existing file content)
+         *  - `patch`  : `args.patch` (unified diff content)
+         */
+        "tool.execute.before": async (input, output) => {
+            switch (input.tool) {
+                case "write": {
+                    if (typeof output.args?.content === "string") {
+                        output.args.content = substitute(output.args.content);
+                    }
+                    break;
+                }
+                case "edit": {
+                    if (typeof output.args?.newString === "string") {
+                        output.args.newString = substitute(output.args.newString);
+                    }
+                    break;
+                }
+                case "patch": {
+                    if (typeof output.args?.patch === "string") {
+                        output.args.patch = substitute(output.args.patch);
+                    }
+                    break;
+                }
+            }
+        },
+    };
+};
+exports.AsciiPlugin = AsciiPlugin;

package/dist/substitutions.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Unicode → ASCII substitution mappings, organised by category.
+ * Each entry is a tuple of [unicode, ascii].
+ */
+export type Category = "punctuation" | "arrows" | "math" | "emojis";
+export declare const PUNCTUATION: Array<[string, string]>;
+export declare const ARROWS: Array<[string, string]>;
+export declare const MATH: Array<[string, string]>;
+export declare const EMOJIS: Array<[string, string]>;
+export type SubstitutionConfig = {
+    punctuation?: boolean;
+    arrows?: boolean;
+    math?: boolean;
+    emojis?: boolean;
+};
+/**
+ * Build a combined substitution map from enabled categories.
+ */
+export declare function buildSubstitutions(config?: SubstitutionConfig): Array<[string, string]>;
+/**
+ * Build a compiled RegExp that matches all active unicode characters at once.
+ * This is much faster than running replace() N times.
+ */
+export declare function buildRegex(substitutions: Array<[string, string]>): RegExp;
+/**
+ * Apply substitutions to a string using a pre-built map and regex.
+ */
+export declare function applySubstitutions(text: string, regex: RegExp, map: Map<string, string>): string;

package/dist/substitutions.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * Unicode → ASCII substitution mappings, organised by category.
+ * Each entry is a tuple of [unicode, ascii].
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMOJIS = exports.MATH = exports.ARROWS = exports.PUNCTUATION = void 0;
+exports.buildSubstitutions = buildSubstitutions;
+exports.buildRegex = buildRegex;
+exports.applySubstitutions = applySubstitutions;
+exports.PUNCTUATION = [
+    // Dashes
+    ["\u2014", "--"], // em dash (—)
+    ["\u2013", "-"], // en dash (–)
+    ["\u2012", "-"], // figure dash (‒)
+    ["\u2015", "--"], // horizontal bar (―)
+    // Ellipsis
+    ["\u2026", "..."], // horizontal ellipsis (…)
+    // Curly / smart quotes — double
+    ["\u201C", '"'], // left double quotation mark (")
+    ["\u201D", '"'], // right double quotation mark (")
+    ["\u201E", '"'], // double low-9 quotation mark („)
+    ["\u201F", '"'], // double high-reversed-9 quotation mark (‟)
+    ["\u00AB", '"'], // left-pointing double angle quotation mark («)
+    ["\u00BB", '"'], // right-pointing double angle quotation mark (»)
+    // Curly / smart quotes — single
+    ["\u2018", "'"], // left single quotation mark (')
+    ["\u2019", "'"], // right single quotation mark (')
+    ["\u201A", "'"], // single low-9 quotation mark (‚)
+    ["\u201B", "'"], // single high-reversed-9 quotation mark (‛)
+    ["\u2039", "'"], // single left-pointing angle quotation mark (‹)
+    ["\u203A", "'"], // single right-pointing angle quotation mark (›)
+    // Miscellaneous punctuation
+    ["\u2022", "-"], // bullet (•)
+    ["\u2023", ">"], // triangular bullet (‣)
+    ["\u2043", "-"], // hyphen bullet (⁃)
+    ["\u00B7", "."], // middle dot (·)
+    ["\u2027", "."], // hyphenation point (‧)
+    ["\u2032", "'"], // prime (′)
+    ["\u2033", '"'], // double prime (″)
+];
+exports.ARROWS = [
+    ["\u2192", "->"], // rightwards arrow (→)
+    ["\u2190", "<-"], // leftwards arrow (←)
+    ["\u2191", "^"], // upwards arrow (↑)
+    ["\u2193", "v"], // downwards arrow (↓)
+    ["\u21D2", "=>"], // rightwards double arrow (⇒)
+    ["\u21D0", "<="], // leftwards double arrow (⇐)
+    ["\u21D4", "<=>"], // left right double arrow (⇔)
+    ["\u2194", "<->"], // left right arrow (↔)
+    ["\u21A6", "->"], // rightwards arrow from bar (↦)
+    ["\u21A4", "<-"], // leftwards arrow from bar (↤)
+    ["\u21E8", "->"], // rightwards white arrow (⇨)
+    ["\u21E6", "<-"], // leftwards white arrow (⇦)
+    ["\u2B9E", "->"], // black rightwards arrowhead (⮞) – U+2B9E
+    ["\u27A1", "->"], // black rightwards arrow (➡)
+    ["\u2B05", "<-"], // leftwards black arrow (⬅)
+    ["\u2B06", "^"], // upwards black arrow (⬆)
+    ["\u2B07", "v"], // downwards black arrow (⬇)
+];
+exports.MATH = [
+    ["\u2260", "!="], // not equal to (≠)
+    ["\u2264", "<="], // less-than or equal to (≤)
+    ["\u2265", ">="], // greater-than or equal to (≥)
+    ["\u00D7", "*"], // multiplication sign (×)
+    ["\u00F7", "/"], // division sign (÷)
+    ["\u00B1", "+/-"], // plus-minus sign (±)
+    ["\u2212", "-"], // minus sign (−)
+    ["\u221E", "inf"], // infinity (∞)
+    ["\u2248", "~="], // almost equal to (≈)
+    ["\u223C", "~"], // tilde operator (∼)
+    ["\u221A", "sqrt"], // square root (√)
+    ["\u2211", "sum"], // n-ary summation (∑)
+    ["\u220F", "prod"], // n-ary product (∏)
+    ["\u2202", "d"], // partial differential (∂)
+    ["\u2207", "nabla"], // nabla (∇)
+    ["\u2208", "in"], // element of (∈)
+    ["\u2209", "not in"], // not an element of (∉)
+    ["\u2229", "&"], // intersection (∩)
+    ["\u222A", "|"], // union (∪)
+    ["\u2282", "<="], // subset of (⊂)
+    ["\u2283", ">="], // superset of (⊃)
+    ["\u2227", "&&"], // logical and (∧)
+    ["\u2228", "||"], // logical or (∨)
+    ["\u00AC", "!"], // not sign (¬)
+    ["\u2234", ":."], // therefore (∴)
+    ["\u2235", ":'"], // because (∵)
+];
+exports.EMOJIS = [
+    // Checkmarks / cross marks
+    ["\u2713", "[x]"], // check mark (✓)
+    ["\u2714", "[x]"], // heavy check mark (✔)
+    ["\u2611", "[x]"], // ballot box with check (☑)
+    ["\u2705", "[x]"], // white heavy check mark (✅)
+    ["\u2717", "[!]"], // ballot x (✗)
+    ["\u2718", "[!]"], // heavy ballot x (✘)
+    ["\u274C", "[!]"], // cross mark (❌)
+    ["\u274E", "[!]"], // cross mark button (❎)
+    // Warnings / alerts
+    ["\u26A0", "[!]"], // warning sign (⚠)
+    ["\u2757", "[!]"], // heavy exclamation mark ornament (❗)
+    ["\u2755", "[!]"], // white exclamation mark ornament (❕)
+    ["\u26A1", "[!]"], // high voltage sign (⚡)
+    // Info / ideas
+    ["\u2139", "[i]"], // information source (ℹ)
+    ["\u1F4A1", "[i]"], // light bulb (💡)
+    // Stars / rating
+    ["\u2B50", "[*]"], // white medium star (⭐)
+    ["\u1F31F", "[*]"], // glowing star (🌟)
+    ["\u2605", "[*]"], // black star (★)
+    ["\u2606", "[*]"], // white star (☆)
+    // Common emoji sequences
+    ["\u1F525", "[fire]"], // fire (🔥)
+    ["\u1F680", "[>>]"], // rocket (🚀)
+    ["\u1F41B", "[bug]"], // bug (🐛)
+    ["\u1F41E", "[bug]"], // lady beetle (🐞)
+    ["\u1F4DD", "[note]"], // memo (📝)
+    ["\u270F", "[note]"], // pencil (✏)
+    ["\u1F512", "[lock]"], // lock (🔒)
+    ["\u1F513", "[open]"], // open lock (🔓)
+    ["\u1F4C1", "[dir]"], // file folder (📁)
+    ["\u1F4C2", "[dir]"], // open file folder (📂)
+    ["\u1F4C4", "[file]"], // page facing up (📄)
+    ["\u1F4C3", "[file]"], // page with curl (📃)
+    ["\u1F44D", "[+1]"], // thumbs up (👍)
+    ["\u1F44E", "[-1]"], // thumbs down (👎)
+    ["\u1F4AC", "[comment]"], // speech balloon (💬)
+    ["\u1F4E6", "[pkg]"], // package (📦)
+    ["\u1F517", "[link]"], // link (🔗)
+    ["\u1F6A7", "[wip]"], // construction sign (🚧)
+    ["\u2699", "[config]"], // gear (⚙)
+    ["\u1F527", "[fix]"], // wrench (🔧)
+    ["\u1F5D1", "[del]"], // wastebasket (🗑)
+    ["\u1F310", "[web]"], // globe with meridians (🌐)
+    ["\u1F4BB", "[pc]"], // personal computer (💻)
+    ["\u1F4F1", "[phone]"], // mobile phone (📱)
+    ["\u1F4E7", "[email]"], // e-mail (📧)
+    ["\u1F4CA", "[chart]"], // bar chart (📊)
+    ["\u1F4C8", "[up]"], // chart with upwards trend (📈)
+    ["\u1F4C9", "[down]"], // chart with downwards trend (📉)
+    ["\u2764", "[<3]"], // heavy black heart (❤)
+    ["\u1F4AF", "[100]"], // hundred points (💯)
+    ["\u1F44B", "[wave]"], // waving hand (👋)
+    ["\u1F91D", "[deal]"], // handshake (🤝)
+    ["\u1F4AA", "[strong]"], // flexed biceps (💪)
+    ["\u1F914", "[?]"], // thinking face (🤔)
+    ["\u1F644", "[eye-roll]"], // face with rolling eyes (🙄)
+    ["\u1F4A5", "[boom]"], // collision (💥)
+    ["\u1F389", "[party]"], // party popper (🎉)
+    ["\u1F3C6", "[trophy]"], // trophy (🏆)
+    ["\u1F4B0", "[money]"], // money bag (💰)
+    ["\u231B", "[wait]"], // hourglass (⌛)
+    ["\u23F3", "[wait]"], // hourglass with flowing sand (⏳)
+    ["\u1F504", "[refresh]"], // counterclockwise arrows button (🔄)
+    ["\u2705", "[done]"], // white heavy check mark (✅) — already above, kept for completeness
+];
+const DEFAULT_CONFIG = {
+    punctuation: true,
+    arrows: true,
+    math: true,
+    emojis: true,
+};
+/**
+ * Build a combined substitution map from enabled categories.
+ */
+function buildSubstitutions(config = {}) {
+    const resolved = { ...DEFAULT_CONFIG, ...config };
+    const entries = [];
+    if (resolved.punctuation)
+        entries.push(...exports.PUNCTUATION);
+    if (resolved.arrows)
+        entries.push(...exports.ARROWS);
+    if (resolved.math)
+        entries.push(...exports.MATH);
+    if (resolved.emojis)
+        entries.push(...exports.EMOJIS);
+    return entries;
+}
+/**
+ * Build a compiled RegExp that matches all active unicode characters at once.
+ * This is much faster than running replace() N times.
+ */
+function buildRegex(substitutions) {
+    const pattern = substitutions
+        .map(([ch]) => ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+        .join("|");
+    return new RegExp(pattern, "gu");
+}
+/**
+ * Apply substitutions to a string using a pre-built map and regex.
+ */
+function applySubstitutions(text, regex, map) {
+    return text.replace(regex, (match) => map.get(match) ?? match);
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "opencode-ascii",
+  "version": "0.1.0",
+  "description": "OpenCode plugin that substitutes unicode characters with ASCII equivalents in AI responses and file edits",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "latest",
+    "typescript": "^5"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "ascii",
+    "unicode"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/d3vv3/opencode-ascii.git"
+  }
+}