@xynogen/pix-optimizer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xynogen
+
+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,106 @@
+# pix-optimizer
+
+Token-optimization suite for Pi Coding Agent. Three tools wired into one
+extension via `src/index.ts`, fronted by a single `/opt` command and one
+shared status-bar cell:
+
+- **Caveman** (`⛏`) — terse-output system prompt
+- **RTK** (`⚔`) — prefixes shell commands with `rtk` + injects RTK prompt
+- **TOON** (`✂`) — jq + TOON guidance for dense JSON (+ bundled skill)
+
+## Command
+
+One command routes to every tool:
+
+```text
+/opt                  → status + help
+/opt caveman <level>  → set caveman level (1/2/3/lite/full/ultra/micro/off/config)
+/opt rtk [on|off]     → toggle RTK rewriting
+/opt toon [on|off]    → toggle jq+TOON guidance
+```
+
+## Status bar
+
+A single cell always shows all three icons in a fixed order (`⛏ ⚔ ✂`), color-
+coded by state: **accent** when the tool is enabled, **dim** when disabled.
+
+## Features
+
+### Caveman Mode (`⛏`)
+
+Cuts ~75% of output tokens while keeping full technical accuracy.
+
+| # | Name  | Description                  |
+|---|-------|------------------------------|
+| 1 | lite  | Professional, no fluff       |
+| 2 | full  | Classic caveman              |
+| 3 | ultra | Maximum compression          |
+| – | micro | Experimental prompt-minimized |
+
+`/opt caveman config` opens a settings dialog. Default level for new sessions
+and status-bar visibility are saved to `~/.pi/agent/caveman.json`.
+
+### RTK Tool Rewriting (`⚔`)
+
+Two layers, both active automatically:
+
+1. **Prompt layer** — injects the RTK system prompt (tells the model to
+   prefix commands with `rtk`).
+2. **Execute layer** — rewrites `bash` tool calls, prefixing known commands
+   (`git`, `gh`, `cargo`, `npm`, `pnpm`, `docker`, `kubectl`, `ls`, `grep`, …)
+   with `rtk` when the model forgets. **Command chains are split on `&&`,
+   `||`, `;` and `|`, and every known segment is prefixed** — e.g.
+   `git add . && git push` becomes `rtk git add . && rtk git push`.
+   Operators inside quotes are ignored, and unparseable commands are left
+   untouched. Falls back gracefully when the `rtk` binary is missing
+   (warns once).
+
+**Requirement:** the `rtk` binary must be on `PATH`.
+
+```bash
+cargo install rtk-ai
+```
+
+### TOON / JSON Compression (`✂`)
+
+Guidance + a bundled `toon-json` skill for handling information-dense JSON via
+`jq` (query/reshape) and `toon` (compress). The system-prompt nudge is injected
+**only when the user prompt mentions JSON** (`json`/`jsonl`/`jq`/`toon`/
+`openapi`/…). TOON shines on uniform/tabular arrays; deeply nested or
+array-of-arrays data and API contracts stay as JSON.
+
+**Requirement:** `jq` and `toon` on `PATH`.
+
+```bash
+npm i -g @toon-format/cli
+```
+
+## Installation
+
+```bash
+pi install git:github.com/xynogen/pix-optimizer
+```
+
+## Architecture
+
+| File              | Role                                                      |
+|-------------------|-----------------------------------------------------------|
+| `src/index.ts`    | Wires the three tools + shared status, registers `/opt`   |
+| `src/opt.ts`      | The `/opt` router: parse, complete, dispatch              |
+| `src/status.ts`   | Shared status-bar cell + `OptimizerHandle` contract       |
+| `src/caveman.ts`  | Caveman logic, levels, prompt, settings dialog            |
+| `src/rtk.ts`      | RTK prompt + bash command rewriting                       |
+| `src/json.ts`     | jq+TOON guidance, heuristics, bundled skill registration  |
+
+Each tool registers its own lifecycle hooks and exposes an `OptimizerHandle`
+that `/opt` dispatches to. All three share one `OptimizerStatus`.
+
+## Development
+
+```bash
+bun test
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@xynogen/pix-optimizer",
+  "version": "1.0.0",
+  "description": "Performance optimization suite for Pi Coding Agent - caveman mode + RTK tool rewriting + jq/TOON JSON compression",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "test": "bun test"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": ["./src/index.ts"]
+  },
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "optimizer",
+    "caveman",
+    "rtk",
+    "toon",
+    "jq",
+    "json",
+    "performance"
+  ],
+  "author": "xynogen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xynogen/pix-mono.git",
+    "directory": "packages/pix-optimizer"
+  },
+  "homepage": "https://github.com/xynogen/pix-mono/tree/main/packages/pix-optimizer#readme",
+  "bugs": {
+    "url": "https://github.com/xynogen/pix-mono/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  }
+}

package/src/caveman.test.ts

@@ -0,0 +1,239 @@
+import { describe, it, expect } from "bun:test";
+import {
+	LEVELS,
+	LEVEL_NUMBERS,
+	STOP_ALIASES,
+	STATUS_LABELS,
+	buildPrompt,
+	buildHelp,
+	resolveLevel,
+	toggleLevel,
+	parseConfig,
+	DEFAULT_CONFIG,
+	type Level,
+} from "./caveman.ts";
+
+// ── LEVELS ────────────────────────────────────────────────────────────────────
+
+describe("LEVELS", () => {
+	it("contains off as first entry", () => {
+		expect(LEVELS[0]).toBe("off");
+	});
+
+	it("contains all expected levels", () => {
+		const expected = ["off", "lite", "full", "ultra", "micro"];
+		for (const l of expected) expect(LEVELS).toContain(l);
+	});
+});
+
+// ── STOP_ALIASES ──────────────────────────────────────────────────────────────
+
+describe("STOP_ALIASES", () => {
+	it("includes off, stop, quit", () => {
+		expect(STOP_ALIASES.has("off")).toBe(true);
+		expect(STOP_ALIASES.has("stop")).toBe(true);
+		expect(STOP_ALIASES.has("quit")).toBe(true);
+	});
+
+	it("does not include active levels", () => {
+		expect(STOP_ALIASES.has("full")).toBe(false);
+		expect(STOP_ALIASES.has("ultra")).toBe(false);
+	});
+});
+
+// ── STATUS_LABELS ─────────────────────────────────────────────────────────────
+
+describe("STATUS_LABELS", () => {
+	it("has a label for every non-off level", () => {
+		const nonOff = LEVELS.filter((l) => l !== "off") as Exclude<Level, "off">[];
+		for (const l of nonOff) {
+			expect(STATUS_LABELS[l]).toBeTruthy();
+		}
+	});
+
+	it("latin levels are uppercase", () => {
+		expect(STATUS_LABELS["lite"]).toBe("LITE");
+		expect(STATUS_LABELS["full"]).toBe("FULL");
+		expect(STATUS_LABELS["ultra"]).toBe("ULTRA");
+		expect(STATUS_LABELS["micro"]).toBe("MICRO");
+	});
+});
+
+// ── resolveLevel ──────────────────────────────────────────────────────────────
+
+describe("resolveLevel", () => {
+	it("resolves valid levels", () => {
+		expect(resolveLevel("lite")).toBe("lite");
+		expect(resolveLevel("full")).toBe("full");
+		expect(resolveLevel("ultra")).toBe("ultra");
+		expect(resolveLevel("micro")).toBe("micro");
+		expect(resolveLevel("off")).toBe("off");
+	});
+
+	it("maps stop aliases to off", () => {
+		expect(resolveLevel("stop")).toBe("off");
+		expect(resolveLevel("quit")).toBe("off");
+	});
+
+	it("is case-insensitive", () => {
+		expect(resolveLevel("FULL")).toBe("full");
+		expect(resolveLevel("Ultra")).toBe("ultra");
+		expect(resolveLevel("STOP")).toBe("off");
+	});
+
+	it("trims whitespace", () => {
+		expect(resolveLevel("  full  ")).toBe("full");
+	});
+
+	it("returns null for unknown input", () => {
+		expect(resolveLevel("unknown")).toBeNull();
+		expect(resolveLevel("")).toBeNull();
+		expect(resolveLevel("config")).toBeNull(); // config handled separately
+	});
+});
+
+// ── numeric levels ────────────────────────────────────────────────────────────
+
+describe("numeric levels", () => {
+	it("maps 1/2/3 to lite/full/ultra", () => {
+		expect(resolveLevel("1")).toBe("lite");
+		expect(resolveLevel("2")).toBe("full");
+		expect(resolveLevel("3")).toBe("ultra");
+	});
+
+	it("maps 0 to off", () => {
+		expect(resolveLevel("0")).toBe("off");
+	});
+
+	it("LEVEL_NUMBERS only covers 1-3", () => {
+		expect(Object.keys(LEVEL_NUMBERS).sort()).toEqual(["1", "2", "3"]);
+	});
+
+	it("rejects out-of-range numbers", () => {
+		expect(resolveLevel("4")).toBeNull();
+		expect(resolveLevel("9")).toBeNull();
+	});
+
+	it("trims whitespace around numbers", () => {
+		expect(resolveLevel("  2  ")).toBe("full");
+	});
+});
+
+// ── buildHelp ─────────────────────────────────────────────────────────────────
+
+describe("buildHelp", () => {
+	it("lists numeric shortcuts", () => {
+		const help = buildHelp("off");
+		expect(help).toContain("1");
+		expect(help).toContain("lite");
+		expect(help).toContain("2");
+		expect(help).toContain("full");
+		expect(help).toContain("3");
+		expect(help).toContain("ultra");
+	});
+
+	it("shows current level when active", () => {
+		expect(buildHelp("ultra")).toContain("ULTRA");
+	});
+
+	it("shows off when disabled", () => {
+		expect(buildHelp("off")).toContain("off");
+	});
+
+	it("mentions config", () => {
+		expect(buildHelp("off")).toContain("config");
+	});
+
+	it("does not mention wenyan", () => {
+		expect(buildHelp("off").toLowerCase()).not.toContain("wenyan");
+	});
+});
+
+// ── toggleLevel ───────────────────────────────────────────────────────────────
+
+describe("toggleLevel", () => {
+	it("off → full", () => {
+		expect(toggleLevel("off")).toBe("full");
+	});
+
+	it("full → off", () => {
+		expect(toggleLevel("full")).toBe("off");
+	});
+
+	it("any non-off level → off", () => {
+		const nonOff = LEVELS.filter((l) => l !== "off") as Level[];
+		for (const l of nonOff) {
+			expect(toggleLevel(l)).toBe("off");
+		}
+	});
+});
+
+// ── buildPrompt ───────────────────────────────────────────────────────────────
+
+describe("buildPrompt", () => {
+	it("returns empty string for off", () => {
+		expect(buildPrompt("off")).toBe("");
+	});
+
+	it("returns MICRO_PROMPT for micro (no BASE)", () => {
+		const p = buildPrompt("micro");
+		expect(p).toContain("Token efficiency");
+		expect(p).not.toContain("CAVEMAN MODE");
+	});
+
+	it("includes BASE for all standard levels", () => {
+		const standard = ["lite", "full", "ultra"] as Level[];
+		for (const l of standard) {
+			expect(buildPrompt(l)).toContain("CAVEMAN MODE");
+		}
+	});
+
+	it("includes SAFETY clause for all standard levels", () => {
+		const standard = ["lite", "full", "ultra"] as Level[];
+		for (const l of standard) {
+			expect(buildPrompt(l)).toContain("Auto-clarity");
+		}
+	});
+
+	it("each level has distinct intensity instructions", () => {
+		const lite = buildPrompt("lite");
+		const ultra = buildPrompt("ultra");
+		expect(lite).toContain("Keep articles");
+		expect(ultra).toContain("Abbreviate");
+		expect(lite).not.toContain("Abbreviate");
+	});
+
+});
+
+// ── parseConfig ───────────────────────────────────────────────────────────────
+
+describe("parseConfig", () => {
+	it("parses valid config", () => {
+		const cfg = parseConfig({ defaultLevel: "ultra", showStatus: false });
+		expect(cfg.defaultLevel).toBe("ultra");
+		expect(cfg.showStatus).toBe(false);
+	});
+
+	it("falls back to defaults for invalid defaultLevel", () => {
+		const cfg = parseConfig({ defaultLevel: "invalid", showStatus: true });
+		expect(cfg.defaultLevel).toBe(DEFAULT_CONFIG.defaultLevel);
+	});
+
+	it("falls back to defaults for missing fields", () => {
+		const cfg = parseConfig({});
+		expect(cfg.defaultLevel).toBe(DEFAULT_CONFIG.defaultLevel);
+		expect(cfg.showStatus).toBe(DEFAULT_CONFIG.showStatus);
+	});
+
+	it("falls back to defaults for null/undefined", () => {
+		const cfg = parseConfig(null);
+		expect(cfg.defaultLevel).toBe(DEFAULT_CONFIG.defaultLevel);
+		expect(cfg.showStatus).toBe(DEFAULT_CONFIG.showStatus);
+	});
+
+	it("accepts all valid levels as defaultLevel", () => {
+		for (const l of LEVELS) {
+			expect(parseConfig({ defaultLevel: l, showStatus: true }).defaultLevel).toBe(l);
+		}
+	});
+});