@krtclcdy/tersio 2.4.1 → 2.6.0

package/README.md

@@ -33,10 +33,10 @@ omp plugin features @krtclcdy/tersio --disable rtk
 Then restart OMP and enable a preset:
 
 ```text
-/combo medium
+/tersio combo medium
 ```
 
-Individual toggles: `/caveman full` · `/rtk on` · `/ponytail full`. Everything starts off until you enable it.
+Individual toggles: `/tersio caveman full` · `/tersio rtk on` · `/tersio ponytail full`. Everything starts off until you enable it.
 
 Session-start defaults (prompted during `install`, or flags):
 
@@ -44,7 +44,7 @@ Session-start defaults (prompted during `install`, or flags):
 tersio install --combo-default balanced --caveman-default lite --rtk-default on
 ```
 
-Defaults apply to fresh sessions only — anything persisted with `/combo`, `/caveman`, or `/rtk` wins. Stored as plugin settings (`omp plugin config get @krtclcdy/tersio comboDefault`).
+Defaults apply to fresh sessions only — anything persisted with `/tersio combo`, `/tersio caveman`, or `/tersio rtk` wins. Stored as plugin settings (`omp plugin config get @krtclcdy/tersio comboDefault`).
 
 ## What it installs
 
@@ -54,7 +54,7 @@ Defaults apply to fresh sessions only — anything persisted with `/combo`, `/ca
 | **RTK** | Routes noisy shell commands through the RTK binary for compact output |
 | **Ponytail** | Minimal, YAGNI-oriented code decisions |
 | **Combo** | Toggles all three at once. Presets: `off`, `medium`, `balanced`, `max` |
-| **Updater** | `/ai-addons` checks and updates Ponytail, RTK, and Caveman in-session, with dry-run and backups |
+| **Updater** | `/tersio check` and `/tersio update` cover Ponytail, RTK, and Caveman in-session, with dry-run and backups |
 
 User-level installs also register the package in `~/.omp/plugins` (visible in OMP **Settings → Plugins**), directly through the plugin manifest. Active modes reassert after Ponytail's prompt block on every top-level turn, including after history compaction.
 
@@ -81,6 +81,8 @@ Break-even math, balanced preset (caveman full + rtk + ponytail): `⌈overhead
 | `tersio update` | Refresh the CLI, extensions, and add-ons (RTK binary, Caveman rule, Ponytail) |
 | `tersio reinstall` | Fresh install, preserving the Ponytail package |
 | `tersio doctor` | Check OMP, extension, Ponytail, and RTK health |
+| `tersio usage` | Ledger-backed usage + savings report |
+| `tersio dashboard` | Serve the gain dashboard on localhost (`--open`, `--export <file>`, `--port <n>`) |
 | `tersio uninstall` | Remove extensions, registration, and the Ponytail plugin (`--keep-ponytail` keeps Ponytail; `--remove-rtk` also removes the RTK binary) |
 | `tersio version` | Print version |
 
@@ -88,63 +90,44 @@ Flags: `--dry-run`, `--yes`/`-y`, `--verbose`, `--scope`, `--combo-default`/`--c
 
 ## Commands reference
 
-### Caveman — terse replies
+Everything runs under one root. Bare `/tersio` prints status.
 
-```text
-/caveman lite         concise, drops pleasantries
-/caveman full         terse caveman style
-/caveman ultra        maximum terse, fragments only
-/caveman wenyan       classical-Chinese-style where clear
-/caveman off          normal mode
-/caveman status       show current mode
-```
+| Command | Purpose |
+|---|---|
+| `/tersio combo off\|medium\|balanced\|max\|status` | preset for all three modes (start here) |
+| `/tersio caveman lite\|full\|ultra\|wenyan\|off\|status` | terse-reply mode |
+| `/tersio rtk on\|off\|status` | compact shell-output toggle |
+| `/tersio ponytail off\|lite\|full\|ultra\|review\|status` | minimal-code level |
+| `/tersio status` | active modes + combo level |
+| `/tersio check` | add-on version check (same as old `/ai-addons check`) |
+| `/tersio update <ponytail\|rtk\|caveman\|all> [--dry-run]` | update add-ons, preview with dry-run |
+| `/tersio gain` | savings summary + dashboard hint |
+| `/tersio usage` | ledger report for this machine |
+| `/tersio help` | this table |
 
-`caveman off`, `stop caveman`, and `normal mode` also work.
+### Combo — one preset for all three
 
-### RTK — compact shell output
+Start here: one setting drives all three modes (`medium` = lite/lite/on, `balanced` = full/full/on, `max` = ultra/ultra/on, `off` = normal). Tweaking a mode individually drops to a `custom` mix.
 
-```text
-/rtk on               enable compact RTK output
-/rtk off              disable
-/rtk status           show current state
-```
+### Caveman — terse replies
 
-Covers noisy commands (`git status`, `git diff`, `read`, `grep`, test, `tsc`, lint).
+Pleasantries and restatements go; substance stays. Ladder: `lite`, `full`, `ultra` (fragments only), `wenyan` (compressed classical-Chinese-inspired register).
 
-### Ponytail — minimal code
+### RTK — compact shell output
 
-```text
-/ponytail lite        light guidance
-/ponytail full        full YAGNI enforcement
-/ponytail ultra       aggressive simplification
-/ponytail off         disable
-/ponytail status      show current state
-```
+A real binary, not a prompt trick: `rtk git status|diff|grep|test|tsc|lint` strips noise before output reaches the model. Exact bytes (checksums, patches) bypass it by policy.
 
-### Updater — check and update add-ons
+### Ponytail — minimal code (YAGNI)
 
-```text
-/ai-addons check                          check all add-on versions
-/ai-addons status                         same as check
-/ai-addons update ponytail                update Ponytail
-/ai-addons update rtk                     update the RTK binary
-/ai-addons update caveman                 update the Caveman rule
-/ai-addons update all                     update all three
-/ai-addons update all --dry-run           preview without changes
-```
+You Aren't Gonna Need It: smallest working change, no speculative abstractions, no new deps for stdlib jobs. `lite` nudges, `full` enforces, `ultra` challenges the requirement, `review` audits for over-engineering.
 
-### Combo — toggle all three
+`/tersio` persists state and reloads OMP without emitting separate command messages. Presets propagate to task subagents and light the Combo footer indicator; mixed individual settings report via `/tersio status`.
 
-```text
-/combo off            all three off (default)
-/combo medium         caveman=lite, rtk=on, ponytail=lite
-/combo balanced       caveman=full, rtk=on, ponytail=full
-/combo max            caveman=ultra, rtk=on, ponytail=ultra
-/combo status         show the level and underlying modes
-/combo help           show available levels
-```
+### Legacy aliases (still work)
+
+The pre-`/tersio` commands remain registered: `/caveman`, `/rtk`, `/combo`, `/ai-addons`. Prefer `/tersio` in new muscle memory; help output lists the aliases as deprecated-but-working.
 
-`/combo` persists state and reloads OMP without emitting separate command messages. Presets propagate to task subagents and light the Combo footer indicator; individual commands leave Combo inactive (`/combo status` still reports the mixed state).
+Usage rows land in `~/.omp/plugins/tersio-usage.jsonl` (local only); `tersio dashboard` serves them as a plain-HTML page on 127.0.0.1.
 
 ## Files and backups
 
@@ -176,7 +159,7 @@ npm exec --yes --prefer-online --package=@krtclcdy/tersio@latest -- tersio insta
 
 **RTK missing or not executable:** run `tersio reinstall`, then `tersio doctor`. On Linux/macOS: `chmod +x ~/.bun/bin/rtk`.
 
-**Checksum warning or failure:** the installer aborts on RTK checksum mismatch but warns and continues when checksum metadata is unavailable; `/ai-addons update rtk` aborts when metadata is missing.
+**Checksum warning or failure:** the installer aborts on RTK checksum mismatch but warns and continues when checksum metadata is unavailable; `/tersio update rtk` aborts when metadata is missing.
 
 ## License
 

package/cli/common.js

@@ -0,0 +1,257 @@
+// cli/common.ts — shared foundation: CLI flags, paths, exec, file/config helpers.
+import { execFile } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { createRequire } from 'node:module';
+import { readTextIfExists } from '../extensions/lib/utils.js';
+const IS_WINDOWS = process.platform === 'win32';
+const RTK_BINARY_NAME = IS_WINDOWS ? 'rtk.exe' : 'rtk';
+const HOME = process.env.HOME || process.env.USERPROFILE || '';
+const OMP_AGENT_DIR = path.join(HOME, '.omp', 'agent');
+const OMP_PLUGINS_DIR = path.join(HOME, '.omp', 'plugins');
+const BUN_BIN_DIR = path.join(HOME, '.bun', 'bin');
+const OMP_BIN = IS_WINDOWS ? 'omp.cmd' : 'omp';
+const PACKAGE_NAME = '@krtclcdy/tersio';
+const PACKAGE_BIN = 'tersio';
+const { version: PACKAGE_VERSION } = createRequire(import.meta.url)('../package.json');
+// Session-start mode defaults for fresh installs.
+const CAVEMAN_DEFAULTS = new Set(['off', 'lite', 'full', 'ultra', 'wenyan']);
+const PONYTAIL_DEFAULTS = new Set(['off', 'lite', 'full', 'ultra', 'review']);
+const RTK_DEFAULTS = new Set(['on', 'off']);
+// ponytail: Combo preset implies all three modes. Mirrors COMBO_LEVELS in
+// extensions/shared/session-state.ts (rtk as boolean here). Single source.
+const COMBO_PRESET_MODES = {
+    off: { caveman: 'off', rtk: false, ponytail: 'off' },
+    medium: { caveman: 'lite', rtk: true, ponytail: 'lite' },
+    balanced: { caveman: 'full', rtk: true, ponytail: 'full' },
+    max: { caveman: 'ultra', rtk: true, ponytail: 'ultra' },
+};
+const COMBO_DEFAULTS = new Set(Object.keys(COMBO_PRESET_MODES));
+function parseEnum(value, valid, flag) {
+    if (value === undefined)
+        return undefined;
+    const v = value.trim().toLowerCase();
+    if (!valid.has(v)) {
+        console.error(`[fail] Invalid ${flag}: ${value}. Valid: ${[...valid].join(', ')}`);
+        process.exit(1);
+    }
+    return v;
+}
+function flagValue(name) {
+    const i = args.indexOf(name);
+    if (i !== -1)
+        return args[i + 1];
+    const prefix = `${name}=`;
+    return args.find((arg) => arg.startsWith(prefix))?.slice(prefix.length);
+}
+// --- CLI flags ---
+const COMMANDS = new Set(['install', 'update', 'reinstall', 'doctor', 'uninstall', 'usage', 'dashboard', 'version', 'help']);
+const args = process.argv.slice(2);
+const commandArg = args.find((arg, index) => !arg.startsWith('-') && args[index - 1] !== '--scope');
+const command = commandArg?.toLowerCase() || null;
+const unknownCommand = command !== null && !COMMANDS.has(command);
+const install = command === 'install';
+const update = command === 'update';
+const reinstall = command === 'reinstall';
+const showVersion = command === 'version' || args.includes('--version') || args.includes('-v');
+const showHelp = command === 'help' || args.includes('--help') || args.includes('-h');
+const applyUpdate = args.includes('--apply-update');
+const dryRun = args.includes('--dry-run');
+const yes = args.includes('--yes') || args.includes('-y') || install || update || reinstall || applyUpdate;
+const verbose = args.includes('--verbose');
+const doctor = command === 'doctor' || args.includes('--doctor');
+const usage = command === 'usage' || args.includes('--usage');
+const dashboard = command === 'dashboard' || args.includes('--dashboard');
+const dashboardPort = Number.parseInt(flagValue('--port') ?? '', 10) || 0;
+const dashboardOpen = args.includes('--open');
+const dashboardExport = flagValue('--export') ?? null;
+const uninstall = command === 'uninstall' || args.includes('--uninstall');
+const removePonytail = args.includes('--remove-ponytail');
+const keepPonytail = args.includes('--keep-ponytail');
+const removeRtk = args.includes('--remove-rtk');
+const scopeFlag = flagValue('--scope')?.toLowerCase() ?? null;
+// --- Profile selection (session-start mode defaults) ---
+const comboDefaultFlag = parseEnum(flagValue('--combo-default'), COMBO_DEFAULTS, '--combo-default');
+const cavemanDefaultFlag = parseEnum(flagValue('--caveman-default'), CAVEMAN_DEFAULTS, '--caveman-default');
+const ponytailDefaultFlag = parseEnum(flagValue('--ponytail-default'), PONYTAIL_DEFAULTS, '--ponytail-default');
+const rtkDefaultFlag = parseEnum(flagValue('--rtk-default'), RTK_DEFAULTS, '--rtk-default');
+const profileFlagsGiven = [comboDefaultFlag, cavemanDefaultFlag, rtkDefaultFlag, ponytailDefaultFlag]
+    .some((flag) => flag !== undefined);
+function debug(...a) {
+    if (verbose)
+        console.log('  [debug]', ...a);
+}
+const execFileP = promisify(execFile);
+async function execP(cmd, args, opts = {}) {
+    return execFileP(cmd, args, {
+        timeout: opts.timeout || 120000,
+        encoding: 'utf8',
+        ...opts,
+    });
+}
+async function writeIfChanged(dest, content, options = {}) {
+    const existing = await readTextIfExists(dest);
+    if (existing === content) {
+        debug(`${dest} already up to date`);
+        return false;
+    }
+    if (options.dryRun) {
+        console.log(`  [dry-run] would write ${dest}`);
+        return true;
+    }
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    if (existing !== null) {
+        await fs.copyFile(dest, `${dest}.bak`);
+        debug(`${path.basename(dest)} → ${path.basename(dest)}.bak`);
+    }
+    await fs.writeFile(dest, content, 'utf8');
+    console.log(`  [write] ${dest}`);
+    return true;
+}
+// omp ships 'extensions: null'; appending list items under a null scalar breaks
+// YAML parsing. Normalize null/~/[]/empty to a mapping key first.
+const EXTENSIONS_KEY_RE = /^\s*extensions\s*:/i;
+const EXTENSIONS_NULL_RE = /^\s*extensions\s*:\s*(?:\[\s*\]|null|~)?\s*$/i;
+function normalizeExtensionsKey(lines) {
+    const idx = lines.findIndex((l) => EXTENSIONS_NULL_RE.test(l));
+    if (idx === -1)
+        return false;
+    lines[idx] = 'extensions:';
+    return true;
+}
+async function writeConfigLines(configPath, lines, logMsg) {
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    await fs.copyFile(configPath, `${configPath}.bak`).catch(() => { });
+    await fs.writeFile(configPath, lines.join('\n'), 'utf8');
+    console.log(logMsg);
+}
+async function ensureExtensionInConfig(configPath, extensionPath, label, options = {}) {
+    const normalizedPath = extensionPath.replace(/\\/g, '/');
+    const line = `  - ${normalizedPath}`;
+    const raw = await readTextIfExists(configPath);
+    let lines = (raw || '').split('\n');
+    if (lines.some((l) => l.includes(normalizedPath))) {
+        debug(`${label} already in config.yml`);
+        return false;
+    }
+    const extLineIdx = lines.findIndex((l) => EXTENSIONS_KEY_RE.test(l));
+    if (options.dryRun) {
+        console.log(`  [dry-run] would add ${label} to config.yml: ${normalizedPath}`);
+        return true;
+    }
+    if (normalizeExtensionsKey(lines)) {
+        lines.splice(extLineIdx + 1, 0, line, '');
+    }
+    else if (extLineIdx === -1) {
+        lines.push('extensions:');
+        lines.push(line);
+        lines.push('');
+    }
+    else {
+        lines.splice(extLineIdx + 1, 0, line);
+    }
+    await writeConfigLines(configPath, lines, `  [write] Added ${label} to config.yml`);
+    return true;
+}
+async function ensureExtensionAfterConfigEntry(configPath, extensionPath, afterPath, label, options = {}) {
+    const normalizedPath = extensionPath.replace(/\\/g, '/');
+    const normalizedAfterPath = afterPath.replace(/\\/g, '/');
+    const line = `  - ${normalizedPath}`;
+    const raw = await readTextIfExists(configPath);
+    const lines = (raw || '').split('\n');
+    const existingIndex = lines.findIndex((entry) => entry.includes(normalizedPath));
+    const afterIndex = lines.findIndex((entry) => entry.includes(normalizedAfterPath));
+    if (existingIndex !== -1 && afterIndex !== -1 && existingIndex === afterIndex + 1)
+        return false;
+    if (options.dryRun) {
+        console.log(`  [dry-run] would place ${label} after Ponytail in config.yml: ${normalizedPath}`);
+        return true;
+    }
+    if (existingIndex !== -1)
+        lines.splice(existingIndex, 1);
+    const refreshedAfterIndex = lines.findIndex((entry) => entry.includes(normalizedAfterPath));
+    if (refreshedAfterIndex !== -1) {
+        lines.splice(refreshedAfterIndex + 1, 0, line);
+    }
+    else {
+        const extensionsIndex = lines.findIndex((entry) => EXTENSIONS_KEY_RE.test(entry));
+        if (extensionsIndex === -1) {
+            lines.push('extensions:', line, '');
+        }
+        else {
+            normalizeExtensionsKey(lines);
+            lines.splice(extensionsIndex + 1, 0, line);
+        }
+    }
+    await writeConfigLines(configPath, lines, `  [write] Placed ${label} after Ponytail in config.yml`);
+    return true;
+}
+function readPonytailConfig() {
+    const dir = process.env.XDG_CONFIG_HOME
+        ? path.join(process.env.XDG_CONFIG_HOME, 'ponytail')
+        : path.join(HOME, '.config', 'ponytail');
+    return { dir, path: path.join(dir, 'config.json') };
+}
+function parseJsonObject(text) {
+    if (!text)
+        return null;
+    try {
+        const parsed = JSON.parse(text.replace(/^\uFEFF/, ''));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function parsePonytailConfig(existing) {
+    return parseJsonObject(existing) ?? {};
+}
+async function patchPonytailConfig(apply, dryRunNote, writeNote, options = {}) {
+    const config = readPonytailConfig();
+    if (options.dryRun) {
+        console.log(`  [dry-run] ${dryRunNote} in ${config.path}`);
+        return;
+    }
+    const cfg = parsePonytailConfig(await readTextIfExists(config.path));
+    if (!apply(cfg)) {
+        debug('Ponytail config already up to date');
+        return;
+    }
+    await fs.mkdir(config.dir, { recursive: true });
+    await fs.writeFile(config.path, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+    console.log(`  [write] ${writeNote} in ${config.path}`);
+}
+async function ensurePonytailConfigValue(key, value, options = {}) {
+    await patchPonytailConfig((cfg) => {
+        if (cfg[key] === value)
+            return false;
+        cfg[key] = value;
+        return true;
+    }, `would set Ponytail ${key}=${value}`, `Set Ponytail ${key}=${value}`, options);
+}
+// Read plugins/package.json tolerantly; corrupt or missing files start fresh
+// with installer-managed defaults.
+async function readPluginsPackage(pkgPath) {
+    const pkg = parseJsonObject(await readTextIfExists(pkgPath)) ?? {};
+    return { ...pkg, name: pkg.name || 'omp-plugins', private: true, dependencies: pkg.dependencies || {} };
+}
+const SCOPE_MAP = { user: '1', project: '2', both: '3' };
+function relTime(ageMs) {
+    const mins = Math.floor(ageMs / 60000);
+    if (mins < 1)
+        return 'just now';
+    if (mins < 60)
+        return `${mins} min${mins === 1 ? '' : 's'} ago`;
+    const hours = Math.floor(mins / 60);
+    if (hours < 24)
+        return `${hours} hour${hours === 1 ? '' : 's'} ago`;
+    const days = Math.floor(hours / 24);
+    if (days < 14)
+        return `${days} day${days === 1 ? '' : 's'} ago`;
+    const weeks = Math.floor(days / 7);
+    return `${weeks} week${weeks === 1 ? '' : 's'} ago`;
+}
+export { IS_WINDOWS, RTK_BINARY_NAME, HOME, OMP_AGENT_DIR, OMP_PLUGINS_DIR, BUN_BIN_DIR, OMP_BIN, PACKAGE_NAME, PACKAGE_BIN, PACKAGE_VERSION, CAVEMAN_DEFAULTS, PONYTAIL_DEFAULTS, RTK_DEFAULTS, COMBO_PRESET_MODES, COMBO_DEFAULTS, parseEnum, flagValue, COMMANDS, commandArg, command, unknownCommand, install, update, reinstall, showVersion, showHelp, applyUpdate, dryRun, yes, verbose, doctor, uninstall, usage, dashboard, dashboardPort, dashboardOpen, dashboardExport, removePonytail, keepPonytail, removeRtk, scopeFlag, comboDefaultFlag, cavemanDefaultFlag, ponytailDefaultFlag, rtkDefaultFlag, profileFlagsGiven, debug, execFileP, execP, writeIfChanged, normalizeExtensionsKey, EXTENSIONS_KEY_RE, writeConfigLines, ensureExtensionInConfig, ensureExtensionAfterConfigEntry, readPonytailConfig, parseJsonObject, parsePonytailConfig, patchPonytailConfig, ensurePonytailConfigValue, readPluginsPackage, SCOPE_MAP, relTime, };