@dohmmit/rtk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,51 @@
+# @dohmmit/rtk
+
+OpenCode plugin that integrates [rtk](https://github.com/rtk-ai/rtk) to transparently rewrite bash commands for 60-90% token savings.
+
+## Install
+
+```bash
+npm install @dohmmit/rtk
+```
+
+Then add to your `opencode.json`:
+
+```json
+{
+  "plugin": ["@dohmmit/rtk"]
+}
+```
+
+**Prerequisite:** [rtk](https://github.com/rtk-ai/rtk) must be installed (>= 0.23.0).
+
+## Configuration
+
+Config file at `~/.config/opencode/rtk-wrapper-config.json` (auto-created on first load):
+
+```json
+{
+  "version": 1,
+  "excludeCommands": ["rtk", "cd"],
+  "settings": {
+    "ultraCompact": false
+  }
+}
+```
+
+- **excludeCommands:** Commands that pass through unrewritten. Default: `["rtk", "cd"]`
+- **settings.ultraCompact:** Append `--ultra-compact` to all rewritten commands
+
+## Example
+
+```bash
+# Without rtk plugin: raw git output (50+ lines)
+git status
+
+# With rtk plugin: automatically becomes
+rtk git status
+# Output: "3 modified, 1 untracked" (one line)
+```
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,29 @@
+/** Config shape contract per D-01. Changing this is a file-format migration. */
+export interface RtkConfig {
+    version: number;
+    excludeCommands: string[];
+    settings: Record<string, unknown>;
+}
+/** D-02: Sensible defaults — zero-config for 90% of users. */
+export declare const DEFAULTS: RtkConfig;
+/** Cross-platform config path via Node.js built-ins (PLAT-02). */
+export declare function getConfigPath(): string;
+/**
+ * Validate and sanitize parsed JSON into an RtkConfig.
+ * Forward-compat: ignores unknown top-level keys.
+ * open question #1 resolution: trims excludeCommands entries.
+ */
+export declare function validateConfig(raw: unknown, _configPath: string): RtkConfig;
+/**
+ * Load the config file or create it with sensible defaults.
+ *
+ * CONF-04: Resolves ~/.config/opencode/rtk-wrapper-config.json via
+ * os.homedir() + path.join(). Auto-creates parent directories and file
+ * on first access (QUAL-02 — zero-config works out of the box).
+ *
+ * D-03: On ANY error (malformed JSON, permissions, etc.), log a single
+ * warning, overwrite with fresh defaults, and continue. No partial-salvage.
+ *
+ * PLAT-02: Uses only Node.js built-ins — no bash, jq, or shell calls.
+ */
+export declare function loadOrCreateConfig(): RtkConfig;

package/dist/config.js

@@ -0,0 +1,85 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+/** D-02: Sensible defaults — zero-config for 90% of users. */
+export const DEFAULTS = {
+    version: 1,
+    excludeCommands: ["rtk", "cd"],
+    settings: {},
+};
+/** Cross-platform config path via Node.js built-ins (PLAT-02). */
+export function getConfigPath() {
+    return join(homedir(), ".config", "opencode", "rtk-wrapper-config.json");
+}
+/**
+ * Validate and sanitize parsed JSON into an RtkConfig.
+ * Forward-compat: ignores unknown top-level keys.
+ * open question #1 resolution: trims excludeCommands entries.
+ */
+export function validateConfig(raw, _configPath) {
+    if (!raw || typeof raw !== "object") {
+        throw new SyntaxError("Config must be a JSON object");
+    }
+    const obj = raw;
+    const version = typeof obj.version === "number" ? obj.version : 1;
+    const excludeCommands = [];
+    if (Array.isArray(obj.excludeCommands)) {
+        for (const item of obj.excludeCommands) {
+            if (typeof item === "string") {
+                const trimmed = item.trim();
+                if (trimmed.length > 0) {
+                    excludeCommands.push(trimmed);
+                }
+            }
+        }
+    }
+    const settings = obj.settings && typeof obj.settings === "object"
+        ? { ...obj.settings }
+        : {};
+    return { version, excludeCommands, settings };
+}
+/**
+ * Load the config file or create it with sensible defaults.
+ *
+ * CONF-04: Resolves ~/.config/opencode/rtk-wrapper-config.json via
+ * os.homedir() + path.join(). Auto-creates parent directories and file
+ * on first access (QUAL-02 — zero-config works out of the box).
+ *
+ * D-03: On ANY error (malformed JSON, permissions, etc.), log a single
+ * warning, overwrite with fresh defaults, and continue. No partial-salvage.
+ *
+ * PLAT-02: Uses only Node.js built-ins — no bash, jq, or shell calls.
+ */
+export function loadOrCreateConfig() {
+    const configPath = getConfigPath();
+    if (!existsSync(configPath)) {
+        mkdirSync(dirname(configPath), { recursive: true });
+        writeFileSync(configPath, JSON.stringify(DEFAULTS, null, 2), "utf-8");
+        return { ...DEFAULTS };
+    }
+    try {
+        const raw = readFileSync(configPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        return validateConfig(parsed, configPath);
+    }
+    catch (err) {
+        // Distinguish parse failures from I/O failures in the log message
+        // (RESEARCH.md Pitfall 1: catch both SyntaxError and EACCES/EISDIR).
+        if (err instanceof SyntaxError) {
+            console.warn(`[rtk] Malformed config at ${configPath}: ${err.message}. ` +
+                "Recreating with defaults.");
+        }
+        else {
+            console.warn(`[rtk] Cannot read config at ${configPath}: ` +
+                `${err.message}. Using defaults.`);
+        }
+        try {
+            mkdirSync(dirname(configPath), { recursive: true });
+            writeFileSync(configPath, JSON.stringify(DEFAULTS, null, 2), "utf-8");
+        }
+        catch {
+            // Recovery failed — still return defaults (e.g., config path is a directory)
+        }
+        return { ...DEFAULTS };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { type Plugin } from "@opencode-ai/plugin";
+export declare const RtkPlugin: Plugin;

package/dist/index.js

@@ -0,0 +1,231 @@
+import { tool } from "@opencode-ai/plugin";
+import { loadOrCreateConfig } from "./config.js";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { StatsTracker, formatSessionStats, formatCompactionSummary } from "./stats.js";
+export const RtkPlugin = async ({ $, client }) => {
+    // Load config BEFORE init-time rtk check (D-04).
+    // Auto-creates at ~/.config/opencode/rtk-wrapper-config.json on first load.
+    const config = loadOrCreateConfig();
+    const excludeSet = new Set(config.excludeCommands);
+    // Init-time rtk availability and version check.
+    // Uses `rtk rewrite --help` rather than `rtk --version` — this verifies
+    // both that rtk is installed AND that it supports the `rewrite` subcommand
+    // (requires rtk >= 0.23.0). If rtk is absent, too old, or the subprocess
+    // fails, return {} (empty hooks) — the plugin is a no-op and other plugins
+    // continue to load.
+    const rtkCheck = await $ `rtk rewrite --help`.quiet().nothrow();
+    if (rtkCheck.exitCode !== 0) {
+        const configPath = join(homedir(), ".config", "opencode", "rtk-wrapper-config.json");
+        console.warn("[rtk] rtk binary not found or too old (requires rtk >= 0.23.0 for rewrite support). " +
+            "Commands will pass through unchanged. " +
+            `Config: ${configPath} — add excluded commands here. ` +
+            "Install: cargo install rtk or visit https://github.com/rtk-ai/rtk");
+        return {};
+    }
+    // Per-command result cache — prevents redundant subprocess spawns for
+    // repeated commands. QUAL-01: <1ms on cache hit.
+    // Scoped inside the plugin function so the cache is only allocated when
+    // rtk is confirmed available.
+    const cache = new Map();
+    // D-01: Stats tracker — closure-scoped, only allocated when rtk is
+    // confirmed available. Tracks per-command rewrite counts and cumulative
+    // token savings.
+    const stats = new StatsTracker();
+    // D-03: Gain pre-snapshot map — stores rtk gain total_saved before
+    // command execution, keyed by input.callID. Cleaned up after every
+    // after-hook lookup to prevent unbounded growth.
+    const gainPreSnapshots = new Map();
+    // D-05: Gain failure counter — incremented when rtk gain subprocess
+    // fails (non-zero exit or exception). Tracked for observability but
+    // never blocks execution.
+    const gainFailures = { count: 0 };
+    // D-04: Debug-level log helper. Uses client.app.log() when client is
+    // available; falls back to console.debug() otherwise.
+    const logDebug = (msg) => {
+        if (client) {
+            client.app.log({
+                body: { service: "rtk", level: "debug", message: msg },
+            });
+        }
+        else {
+            console.debug(msg);
+        }
+    };
+    return {
+        "tool.execute.before": async (input, output) => {
+            // Guard 1 — tool type. Only intercept bash/shell tool calls.
+            // All other tool types (read, write, grep, glob, edit, etc.)
+            // pass through unchanged.
+            const tool = String(input?.tool ?? "").toLowerCase();
+            if (tool !== "bash" && tool !== "shell") {
+                // FEED-01: Debug-level passthrough log for non-bash tools
+                logDebug(`[rtk] passthrough: '${tool}' (non-bash tool)`);
+                return;
+            }
+            // Guard 2 — args existence. Defensive: output.args should always
+            // exist for bash tool calls, but guard against undefined/null/non-object.
+            const args = output?.args;
+            if (!args || typeof args !== "object")
+                return;
+            // Guard 3 — command presence. Extract the command string.
+            // Empty/absent commands pass through — nothing to rewrite.
+            const command = args.command;
+            if (typeof command !== "string" || !command) {
+                // FEED-01: Debug-level passthrough log for empty commands
+                logDebug("[rtk] passthrough: empty command");
+                return;
+            }
+            // Guard 4 — config exclusion list. Commands matching the user's
+            // excludeCommands skip rewriting entirely (no cache lookup, no
+            // subprocess spawn). D-02: defaults are ["rtk", "cd"]. rtk prevents
+            // double-prefixing at config level (cheaper than reaching subprocess).
+            // cd is a pure shell builtin that rtk has no filter for.
+            if (excludeSet.has(command)) {
+                // FEED-01: Debug-level passthrough log for excluded commands
+                logDebug(`[rtk] passthrough: '${command}' (excluded)`);
+                return;
+            }
+            // Cache hit — use cached result, skip subprocess spawn.
+            // Only successful rewrites are cached (cache.set is after the
+            // mutation guard below), so a cache hit means a known rewrite.
+            const cached = cache.get(command);
+            if (cached !== undefined) {
+                ;
+                args.command = cached;
+                return;
+            }
+            // Call rtk rewrite as a subprocess. Use Bun's $ shell API
+            // with .quiet() (suppress stdout passthrough) and .nothrow()
+            // (never throw on non-zero exit). Wrap in try/catch for any
+            // unexpected failures — pass command through unchanged.
+            // The catch block is deliberately silent — logging in the hot
+            // path is noise. The init-time detection above already warns
+            // once at startup.
+            try {
+                const result = await $ `rtk rewrite ${command}`.quiet().nothrow();
+                const rewritten = String(result.stdout).trim();
+                // Exit code non-zero OR empty output means no rewrite
+                // available — pass command through unchanged.
+                // Empty output guard: never set args.command to an empty
+                // string (PITFALLS.md security section: undefined behavior).
+                if (result.exitCode !== 0 || !rewritten || rewritten.length === 0)
+                    return;
+                // PITFALLS.md Pitfall 4: mutate args.command in-place only.
+                // Never replace the entire args object — that would drop
+                // timeout, workdir, and description fields.
+                // PITFALLS.md Pitfall 2: compare before mutating — the
+                // rewritten !== command guard prevents double-wrapping.
+                if (rewritten !== command) {
+                    // D-08: Ultra-compact mode (CONF-03).
+                    // Append BEFORE cache.set() and BEFORE args.command mutation
+                    // (Pitfall 5: cache MUST store the full rewritten command
+                    // including the ultra-compact modifier).
+                    const ultraCompact = Boolean(config.settings.ultraCompact);
+                    const finalCommand = ultraCompact
+                        ? rewritten + " --ultra-compact"
+                        : rewritten;
+                    args.command = finalCommand;
+                    // Cache ONLY on successful rewrite. If rtk rewrite returned
+                    // empty or exit code 1, do not cache (future calls may
+                    // succeed if rtk is updated or the command context changes).
+                    cache.set(command, finalCommand);
+                    // FEED-02 / D-03: Capture pre-execution gain snapshot.
+                    // Uses rtk gain --format json (NOT --bytes — RESEARCH.md Pitfall 1).
+                    // Stored keyed by input.callID for delta computation in after hook.
+                    try {
+                        const preResult = await $ `rtk gain --format json`.quiet().nothrow();
+                        if (preResult.exitCode === 0) {
+                            const pre = JSON.parse(String(preResult.stdout)).summary.total_saved;
+                            gainPreSnapshots.set(input.callID, pre);
+                        }
+                    }
+                    catch {
+                        // Gain subprocess failure → no pre-snapshot stored.
+                        // Delta will be 0 for this call. Never block tool execution.
+                    }
+                    // FEED-01: Structured logging at info level.
+                    // D-04: null-guarded — if client is absent, silently skip.
+                    // info-level has no console fallback.
+                    client?.app.log({
+                        body: {
+                            service: "rtk",
+                            level: "info",
+                            message: `[rtk] rewrote '${command}' → '${finalCommand}'`,
+                        },
+                    });
+                }
+            }
+            catch {
+                // rtk rewrite subprocess failed (crash, timeout, missing
+                // binary). Pass command through unchanged — never block
+                // tool execution because of a failed rewrite. No logging
+                // in hot path — the init-time check already warned at startup.
+            }
+        },
+        // D-03: tool.execute.after — full pre/post gain delta pipeline.
+        // Replaces the tracer's simple stats.record(command, 0) with real
+        // gain measurements from rtk gain --format json snapshots.
+        // FEED-02: Accumulates accurate token savings per command.
+        "tool.execute.after": async (input, _output) => {
+            const tool = String(input?.tool ?? "").toLowerCase();
+            if (tool !== "bash" && tool !== "shell")
+                return;
+            const args = input?.args;
+            if (!args || typeof args !== "object")
+                return;
+            const command = args.command;
+            if (typeof command !== "string" || !command)
+                return;
+            // Look up pre-snapshot and clean up regardless of outcome
+            const preTotal = gainPreSnapshots.get(input.callID);
+            gainPreSnapshots.delete(input.callID);
+            let delta = 0;
+            try {
+                const postResult = await $ `rtk gain --format json`.quiet().nothrow();
+                if (postResult.exitCode === 0) {
+                    const post = JSON.parse(String(postResult.stdout)).summary.total_saved;
+                    if (preTotal !== undefined) {
+                        // D-03 Pitfall 3: clamp negative deltas to 0
+                        // (pre/post mismatch where post < pre — e.g., gain reset)
+                        delta = Math.max(0, post - preTotal);
+                    }
+                }
+                else {
+                    gainFailures.count++;
+                }
+            }
+            catch {
+                gainFailures.count++;
+            }
+            // Extract the base command (first word) for aggregation.
+            // "rtk git status" → "rtk", "git status" → "git"
+            const baseCommand = command.split(" ")[0];
+            if (preTotal !== undefined) {
+                // Rewrite was attempted — record with real delta
+                stats.record(baseCommand, delta);
+            }
+        },
+        // FEED-03: rtk_gain custom LLM tool (D-06, D-07).
+        // Stateless — reads from closure-scoped stats, no side effects.
+        tool: {
+            rtk_gain: tool({
+                description: "Show cumulative rtk token savings for the current session. " +
+                    "Returns a formatted table of per-command rewrite counts and tokens saved.",
+                args: {},
+                async execute(_args, _ctx) {
+                    return formatSessionStats(stats);
+                },
+            }),
+        },
+        // FEED-04: Session compaction savings summary (D-09).
+        // If the hook is never called at runtime (API may not fire in all
+        // OpenCode versions), rtk_gain remains the primary interface.
+        "experimental.session.compacting": async (_input, output) => {
+            const summary = formatCompactionSummary(stats);
+            if (summary) {
+                output.context.push(summary);
+            }
+        },
+    };
+};

package/dist/stats.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Closure-scoped stats tracking for the rtk plugin.
+ *
+ * D-01: Allocated inside the plugin function closure, only when rtk is
+ * confirmed available at init. Never exposed to module-level globals.
+ *
+ * D-02: Track two metrics per command — `count` (times rewritten) and
+ * `tokensSaved` (cumulative rtk gain delta). Both are positive integers.
+ */
+export declare class StatsTracker {
+    private data;
+    /**
+     * Record a command rewrite.
+     * Multiple calls for the same command aggregate count and tokensSaved.
+     */
+    record(command: string, tokensSaved: number): void;
+    /** Yield all tracked entries for read-only iteration. */
+    entries(): IterableIterator<[string, {
+        count: number;
+        tokensSaved: number;
+    }]>;
+}
+/**
+ * D-07: Format session stats as a Markdown table.
+ *
+ * Columns: Command, Rewrites, Tokens Saved.
+ * Rows sorted by tokensSaved descending. Total row at bottom.
+ *
+ * Returns "No commands rewritten this session." if stats is empty.
+ */
+export declare function formatSessionStats(stats: StatsTracker): string;
+/**
+ * One-line session compaction summary.
+ *
+ * Format: "[rtk] This session: N commands rewritten, N tokens saved (~N bytes)"
+ * Returns "" if no rewrites recorded.
+ */
+export declare function formatCompactionSummary(stats: StatsTracker): string;

package/dist/stats.js

@@ -0,0 +1,76 @@
+/**
+ * Closure-scoped stats tracking for the rtk plugin.
+ *
+ * D-01: Allocated inside the plugin function closure, only when rtk is
+ * confirmed available at init. Never exposed to module-level globals.
+ *
+ * D-02: Track two metrics per command — `count` (times rewritten) and
+ * `tokensSaved` (cumulative rtk gain delta). Both are positive integers.
+ */
+export class StatsTracker {
+    data = new Map();
+    /**
+     * Record a command rewrite.
+     * Multiple calls for the same command aggregate count and tokensSaved.
+     */
+    record(command, tokensSaved) {
+        const existing = this.data.get(command);
+        if (existing) {
+            existing.count++;
+            existing.tokensSaved += tokensSaved;
+        }
+        else {
+            this.data.set(command, { count: 1, tokensSaved });
+        }
+    }
+    /** Yield all tracked entries for read-only iteration. */
+    entries() {
+        return this.data.entries();
+    }
+}
+/**
+ * D-07: Format session stats as a Markdown table.
+ *
+ * Columns: Command, Rewrites, Tokens Saved.
+ * Rows sorted by tokensSaved descending. Total row at bottom.
+ *
+ * Returns "No commands rewritten this session." if stats is empty.
+ */
+export function formatSessionStats(stats) {
+    const entries = Array.from(stats.entries())
+        .filter(([_, v]) => v.count > 0)
+        .sort((a, b) => b[1].tokensSaved - a[1].tokensSaved);
+    if (entries.length === 0)
+        return "No commands rewritten this session.";
+    let totalRewrites = 0;
+    let totalTokens = 0;
+    const rows = entries.map(([cmd, { count, tokensSaved }]) => {
+        totalRewrites += count;
+        totalTokens += tokensSaved;
+        return `| ${cmd} | ${count.toLocaleString()} | ${tokensSaved.toLocaleString()} |`;
+    });
+    return [
+        "| Command | Rewrites | Tokens Saved |",
+        "|---------|---------|-------------|",
+        ...rows,
+        `| **Total** | **${totalRewrites.toLocaleString()}** | **${totalTokens.toLocaleString()}** |`,
+    ].join("\n");
+}
+/**
+ * One-line session compaction summary.
+ *
+ * Format: "[rtk] This session: N commands rewritten, N tokens saved (~N bytes)"
+ * Returns "" if no rewrites recorded.
+ */
+export function formatCompactionSummary(stats) {
+    let totalRewrites = 0;
+    let totalTokens = 0;
+    for (const [, { count, tokensSaved }] of stats.entries()) {
+        totalRewrites += count;
+        totalTokens += tokensSaved;
+    }
+    if (totalRewrites === 0)
+        return "";
+    return (`[rtk] This session: ${totalRewrites.toLocaleString()} commands rewritten, ` +
+        `${totalTokens.toLocaleString()} tokens saved (~${Math.round(totalTokens / 4).toLocaleString()} bytes)`);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@dohmmit/rtk",
+  "version": "0.1.0",
+  "description": "OpenCode plugin that integrates rtk to transparently rewrite bash commands for token savings",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/user/opencode-rtk.git"
+  },
+  "keywords": ["opencode", "rtk", "plugin", "tokens"],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test tests/*.test.ts",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.18.4",
+    "@types/node": "^26.1.1",
+    "typescript": "^5.9.3"
+  }
+}