@vigent/cli 0.0.0-stage → 0.2.0

package/dist/cli.js

@@ -0,0 +1,429 @@
+#!/usr/bin/env node
+/** vigent — vim-native agent orchestrator on the pi engine. */
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ProcessTerminal, TUI } from "@mariozechner/pi-tui";
+import { loadAgentMeta, restorableAgents, saveAgentMeta, sessionDir } from "./agents.js";
+import { App } from "./app.js";
+import { staleBuild, VERSION_TEXT } from "./version.js";
+import { CliSession } from "./cli-engines.js";
+import { defaultEngine, detectEngines, ENGINE_BINS, isEngineId, onPath, piConnected, quickEngines } from "./engines.js";
+import { CONFIG_TEMPLATE, configPath, loadConfig } from "./config.js";
+import { createDemoSessions } from "./demo.js";
+import { buildKeymap, KEY_MODES } from "./keys.js";
+import { formatBytes, prepareViews, riftriBackends, riftriGc, riftriHealth, riftriStateDir } from "./riftri.js";
+import { DemoSession, PiSession } from "./session.js";
+import { BUILTIN_THEMES, listThemes, loadTheme, Painter, themesDir } from "./theme.js";
+import { themeNewTemplate } from "./theme-new.js";
+import { branchName, createWorktree, findWorktree, listWorktrees, removeWorktree, repoRoot, worktreesDir, } from "./worktree.js";
+const HELP = `vigent — vim-native agent orchestrator (pi engine)
+
+usage:
+  vigent --version                           which vigent this is (and the commit, from a clone)
+  vigent [--demo] [--theme <name>] [--model <id>] [--engine pi|claude|codex|opencode]
+
+engines (what runs new agents; :checkhealth shows which are signed in):
+  pi        built in, uses ANTHROPIC_API_KEY / OPENAI_API_KEY / ... or pi's login
+  claude    your installed Claude Code CLI, with its own login
+  codex     your installed Codex CLI, with its own login
+  opencode  your installed OpenCode CLI, with its own login
+
+themes:
+  vigent theme list                          built-in and installed themes
+  vigent theme import                        import the colorscheme your nvim/vim uses now
+  vigent theme import <name> [--as <name>]   import any colorscheme nvim/vim can load
+  vigent theme import ./theme.vim            import a colorscheme file (no editor needed)
+      --vim | --nvim      use this editor     --light | --dark   set 'background' first
+      --clean             skip your editor config
+  vigent theme new <name> [--from <theme>]   create a theme file to customize, pre-filled with that theme's colors
+      --palette           build it from a palette only     --transparent   use the terminal's background
+  vigent theme path                          show where themes and config live
+  vigent worktree list                       agent worktrees in this repo
+  vigent worktree remove <branch> [--force]  delete one (safe unless --force)
+  vigent worktree prune                      forget worktrees whose folder is gone
+  vigent worktree gc                         free riftri storage no worktree uses
+  vigent config init                         write a commented config.toml
+  vigent config check                        validate config.toml (theme, options, keys)
+
+keys (NORMAL mode):
+  i            prompt the focused agent        :new <task>     agent in its own worktree
+  j/k gg G     scroll transcript               :kill[!]        stop it (! removes worktree)
+  ctrl+d/u     half-page scroll                :colorscheme    pick a theme (live preview)
+  ]s [s 1-9    switch sessions                 :hi Group ...   change a highlight group
+  za zM zR     fold/unfold tool output         :set nonumber   toggle ui options
+  /pattern ?   search transcript               :diff           what the agent changed
+  V y  yy yib  select and copy, last reply     :merge  :pr     land the agent's work
+  {  }         previous / next message         :dash           all agents at a glance
+  dd           kill agent (asks first)         :queue <text>   follow-up after this run
+  :worktrees   list agent worktrees            :attach <branch> reopen a kept agent
+  :diff split  side-by-side diff               :tree           go back to any point and branch
+  <Space>u     the conversation tree           :nmap <lhs> <rhs> map keys (see :help)
+  :help        every key, including yours      :q              quit
+  :checkhealth engines: installed? signed in?  :new <task> --engine codex
+
+Runs in demo mode (scripted sessions, no network) when --demo is passed,
+or when pi has no API key and none of claude / codex / opencode is installed.
+Config: ~/.config/vigent/config.toml   Themes: ~/.config/vigent/themes/
+`;
+function flag(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+async function themeCommand(argv) {
+    const sub = argv[0];
+    if (sub === "list") {
+        const builtins = new Set(Object.keys(BUILTIN_THEMES));
+        for (const t of listThemes())
+            console.log(builtins.has(t) ? `${t}  (built-in)` : t);
+        return 0;
+    }
+    if (sub === "path") {
+        console.log(`themes: ${themesDir()}`);
+        console.log(`config: ${configPath()}`);
+        return 0;
+    }
+    if (sub === "new") {
+        const name = argv[1];
+        if (!name || name.startsWith("-")) {
+            console.error("usage: vigent theme new <name> [--from <theme>] [--palette] [--transparent | --no-transparent]");
+            return 1;
+        }
+        const from = flag(argv, "--from") ?? "default";
+        loadTheme(from); // fail early on a typo
+        const file = path.join(themesDir(), `${name}.toml`);
+        if (fs.existsSync(file)) {
+            console.error(`${file} already exists`);
+            return 1;
+        }
+        fs.mkdirSync(themesDir(), { recursive: true });
+        fs.writeFileSync(file, themeNewTemplate(name, from, {
+            palette: argv.includes("--palette"),
+            transparent: argv.includes("--transparent") ? true : argv.includes("--no-transparent") ? false : undefined,
+        }));
+        console.log(`created ${file}`);
+        console.log(`use it with: vigent --theme ${name}  (or :colorscheme ${name})`);
+        return 0;
+    }
+    if (sub === "import") {
+        const { importTheme } = await import("./import.js");
+        const rest = argv.slice(1);
+        const positional = rest.filter((a, i) => !a.startsWith("--") && rest[i - 1] !== "--as" && a !== "as");
+        const legacyAs = rest.indexOf("as");
+        const result = importTheme({
+            source: positional[0],
+            as: flag(rest, "--as") ?? (legacyAs >= 0 ? rest[legacyAs + 1] : undefined),
+            editor: rest.includes("--vim") ? "vim" : rest.includes("--nvim") ? "nvim" : undefined,
+            background: rest.includes("--light") ? "light" : rest.includes("--dark") ? "dark" : undefined,
+            clean: rest.includes("--clean"),
+        });
+        console.log(`imported '${result.name}' (${result.groups} highlight groups, via ${result.via})`);
+        console.log(`  -> ${result.file}`);
+        console.log(`use it with: vigent --theme ${result.name}  (or :colorscheme ${result.name})`);
+        return 0;
+    }
+    console.error("usage: vigent theme list | import [name|file] | new <name> | path");
+    return 1;
+}
+function worktreeCommand(argv) {
+    const root = repoRoot(process.cwd());
+    if (!root) {
+        console.error("vigent: not inside a git repository");
+        return 1;
+    }
+    const { config } = loadConfig();
+    const sub = argv[0];
+    if (sub === "list" || sub === undefined) {
+        const all = listWorktrees(root, config.worktree);
+        if (all.length === 0)
+            console.log(`no agent worktrees (they go in ${worktreesDir(root, config.worktree)})`);
+        const backends = riftriBackends(root, all.map((w) => w.path));
+        for (const w of all) {
+            const b = backends.get(w.path);
+            console.log(`${(w.branch ?? `(detached ${w.head})`).padEnd(36)} ${(b ? `riftri ${b}` : "git").padEnd(16)} ${w.path}`);
+        }
+        return 0;
+    }
+    if (sub === "remove" || sub === "rm") {
+        const query = argv[1];
+        if (!query) {
+            console.error("usage: vigent worktree remove <branch> [--force]");
+            return 1;
+        }
+        const w = findWorktree(root, query, config.worktree);
+        if (!w) {
+            console.error(`vigent: no agent worktree '${query}' (see: vigent worktree list)`);
+            return 1;
+        }
+        const r = removeWorktree(root, w, argv.includes("--force"));
+        console.log(r.message);
+        return r.removed ? 0 : 1;
+    }
+    if (sub === "prune") {
+        execFileSync("git", ["worktree", "prune", "-v"], { cwd: root, stdio: "inherit" });
+        return 0;
+    }
+    if (sub === "gc") {
+        if (!riftriStateDir(root)) {
+            console.log("no riftri storage in this repository");
+            return 0;
+        }
+        const r = riftriGc(root);
+        if (!r.ok) {
+            console.error(`vigent: riftri gc failed: ${r.message}`);
+            return 1;
+        }
+        console.log(`freed ${formatBytes(r.report?.removed_allocated_bytes ?? 0)}`);
+        return 0;
+    }
+    console.error("usage: vigent worktree list | remove <branch> [--force] | prune | gc");
+    return 1;
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.includes("--version") || argv.includes("-v") || argv[0] === "version") {
+        console.log(`vigent ${VERSION_TEXT}`);
+        const stale = staleBuild();
+        if (stale)
+            console.log(`warning: ${stale}`);
+        return 0;
+    }
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(HELP);
+        return 0;
+    }
+    if (argv[0] === "theme" || argv[0] === "themes")
+        return themeCommand(argv.slice(1));
+    if (argv[0] === "worktree" || argv[0] === "worktrees" || argv[0] === "wt")
+        return worktreeCommand(argv.slice(1));
+    if (argv[0] === "config" && argv[1] === "check") {
+        const file = configPath();
+        if (!fs.existsSync(file)) {
+            console.log(`no config at ${file} (defaults in use). Create one with: vigent config init`);
+            return 0;
+        }
+        const { config, warnings } = loadConfig(file);
+        const keys = buildKeymap(config.leader, config.keys);
+        warnings.push(...keys.warnings);
+        try {
+            if (config.theme)
+                loadTheme(config.theme);
+        }
+        catch (err) {
+            warnings.push(err.message);
+        }
+        const mappings = KEY_MODES.reduce((n, m) => n + keys.keymap.bindings(m).filter((b) => b.user).length, 0);
+        for (const w of warnings)
+            console.log(`warning: ${w}`);
+        console.log(`${file}: ${warnings.length === 0 ? "ok" : `${warnings.length} problem(s)`} · theme ${config.theme ?? "default"} · leader ${config.leader ?? "\\"} · ${mappings} mapping(s) · ${Object.keys(config.highlights).length} highlight override(s)`);
+        return warnings.length === 0 ? 0 : 1;
+    }
+    if (argv[0] === "config" && argv[1] === "init") {
+        const file = configPath();
+        if (fs.existsSync(file)) {
+            console.error(`${file} already exists`);
+            return 1;
+        }
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, CONFIG_TEMPLATE);
+        console.log(`created ${file}`);
+        return 0;
+    }
+    const { config, warnings } = loadConfig();
+    const stale = staleBuild();
+    if (stale)
+        warnings.push(stale);
+    const { keymap, warnings: keyWarnings } = buildKeymap(config.leader, config.keys);
+    warnings.push(...keyWarnings);
+    const engineArg = flag(argv, "--engine");
+    if (engineArg && !isEngineId(engineArg)) {
+        console.error(`vigent: unknown engine '${engineArg}' (pi, claude, codex or opencode)`);
+        return 1;
+    }
+    const chosenEngine = (engineArg ?? (config.engine === "auto" ? undefined : config.engine));
+    const anyCli = ["claude", "codex", "opencode"].some((id) => onPath(ENGINE_BINS[id]));
+    const demo = argv.includes("--demo") || (!chosenEngine && !piConnected() && !anyCli);
+    const modelArg = flag(argv, "--model");
+    const model = modelArg ?? config.model ?? "claude-sonnet-4-5";
+    const themeName = flag(argv, "--theme") ?? config.theme ?? "default";
+    let theme = BUILTIN_THEMES.default;
+    try {
+        theme = loadTheme(themeName);
+    }
+    catch (err) {
+        if (flag(argv, "--theme")) {
+            console.error(`vigent: ${err.message}`);
+            return 1;
+        }
+        warnings.push(`${err.message} (from config); using default`);
+    }
+    const terminal = new ProcessTerminal();
+    const tui = new TUI(terminal, false);
+    const root = repoRoot(process.cwd());
+    const app = new App(tui, terminal, new Painter(theme, config.highlights), config.ui, keymap, {
+        root,
+        config: config.worktree,
+    });
+    // can agent worktrees be copy-on-write here? (riftri; runs in the background)
+    app.checkStorage = () => riftriHealth(root, root ? worktreesDir(root, config.worktree) : undefined, config.worktree.backend);
+    if (!demo && root && config.worktree.enabled) {
+        app
+            .checkStorage()
+            .then((h) => {
+            app.storage = h;
+        })
+            .catch(() => { });
+    }
+    app.preferredEngine = chosenEngine ?? "auto";
+    app.defaultEngine = () => (app.preferredEngine === "auto" ? defaultEngine(app.engines) : app.preferredEngine);
+    app.detectEngines = () => detectEngines();
+    // installed? signed in? What's on PATH shows at once; the CLIs' sign-in checks take a moment
+    app.setEngines(quickEngines());
+    detectEngines()
+        .then((engines) => app.setEngines(engines))
+        .catch(() => { });
+    /** A Claude Code / Codex / OpenCode agent; its conversation id is saved so it survives a restart. */
+    const cliSession = (name, engine, requested, cwd, wt, resumeId, effort) => new CliSession(name, engine, requested, {
+        cwd,
+        worktree: wt,
+        resumeId,
+        effort,
+        extraArgs: config.engines[engine]?.args,
+        onResumeId: (id) => {
+            if (!wt?.path)
+                return;
+            const meta = loadAgentMeta(wt.path);
+            if (meta)
+                saveAgentMeta(wt.path, { ...meta, resumeId: id });
+        },
+    });
+    // model and effort for new agents, per engine, from [engines.<id>]
+    for (const [id, opts] of Object.entries(config.engines)) {
+        if (opts?.model)
+            app.newAgentModel[id] = opts.model;
+        if (opts?.effort)
+            app.newAgentEffort[id] = opts.effort;
+    }
+    // an agent's model and effort, changed with :model / :effort, survive a restart
+    app.persist = (s) => {
+        const wt = s.worktree?.path;
+        if (!wt)
+            return;
+        const meta = loadAgentMeta(wt);
+        if (!meta)
+            return;
+        const requested = s instanceof CliSession ? s.chosenModel : undefined;
+        saveAgentMeta(wt, {
+            ...meta,
+            model: s instanceof CliSession ? (requested ?? "") : s.model,
+            ...(s instanceof CliSession ? { requestedModel: requested } : {}),
+            effort: s.effort,
+        });
+    };
+    app.newSession = (name, { worktree, model: perAgent, engine = app.defaultEngine(), effort }) => {
+        if (demo) {
+            // demo mode never touches your repo: the worktree is only shown, not created
+            const shown = worktree ? { branch: branchName(name, config.worktree.branch) } : undefined;
+            return new DemoSession(name, perAgent ?? model, shown);
+        }
+        // a CLI uses its own default model unless one is asked for
+        const requested = engine === "pi" ? undefined : (perAgent ?? config.engines[engine]?.model ?? (modelArg && engineArg === engine ? modelArg : undefined));
+        const m = engine === "pi" ? (perAgent ?? model) : (requested ?? "");
+        const wt = worktree && root ? createWorktree(root, name, config.worktree) : undefined;
+        if (wt?.path) {
+            saveAgentMeta(wt.path, {
+                name,
+                model: m,
+                base: wt.base,
+                createdAt: new Date().toISOString(),
+                ...(engine === "pi" ? {} : { engine, ...(requested ? { requestedModel: requested } : {}) }),
+                ...(effort ? { effort } : {}),
+            });
+        }
+        const cwd = wt?.path ?? process.cwd();
+        if (engine !== "pi")
+            return cliSession(name, engine, requested, cwd, wt?.path ? wt : undefined, undefined, effort);
+        if (!wt?.path)
+            return new PiSession(name, m, { cwd, effort });
+        return new PiSession(name, m, { cwd, worktree: wt, sessionDir: sessionDir(wt.path), effort });
+    };
+    /** Reopen a saved agent with the engine it was started with. */
+    const reopen = (meta, worktree) => {
+        const engine = meta.engine && isEngineId(meta.engine) ? meta.engine : "pi";
+        if (engine !== "pi")
+            return cliSession(meta.name, engine, meta.requestedModel, worktree.path, worktree, meta.resumeId, meta.effort);
+        return new PiSession(meta.name, meta.model, { cwd: worktree.path, worktree, sessionDir: sessionDir(worktree.path), effort: meta.effort });
+    };
+    app.attachSession = (wt) => {
+        if (demo || !wt.path)
+            throw new Error("attaching needs a real agent (not --demo)");
+        const meta = loadAgentMeta(wt.path) ?? {
+            name: wt.branch.split("/").pop()?.replace(/-/g, " ") ?? wt.branch,
+            model,
+            createdAt: new Date().toISOString(),
+        };
+        const view = root ? prepareViews(root, [wt.path]).get(wt.path) : undefined;
+        if (view && !view.ready)
+            throw new Error(`can't reopen ${wt.branch}: ${view.reason}`);
+        saveAgentMeta(wt.path, { ...meta, detached: undefined }); // reopened at the next start again
+        return reopen(meta, { ...wt, base: wt.base ?? meta.base, riftri: view?.backend });
+    };
+    app.onQuit = () => {
+        app.stopTimers();
+        for (const s of app.sessions) {
+            s.abort();
+            s.dispose();
+        }
+        tui.stop();
+        process.exit(0);
+    };
+    if (demo) {
+        app.demo = true;
+        for (const s of createDemoSessions())
+            app.addSession(s, false);
+        app.focusIdx = 0;
+        if (!argv.includes("--demo")) {
+            warnings.unshift("demo mode: these agents are scripted. For real ones, install and sign in to Claude Code, Codex or OpenCode, or set ANTHROPIC_API_KEY, then restart (:checkhealth)");
+        }
+    }
+    else if (root && config.worktree.enabled) {
+        // reopen the agents that were running when vigent last quit
+        const agents = restorableAgents(root, config.worktree);
+        // riftri views on OverlayFS lose their mount on reboot: repair them before an agent runs there
+        const views = prepareViews(root, agents.map((a) => a.worktree.path));
+        for (const { meta, worktree } of agents) {
+            const view = views.get(worktree.path);
+            if (view && !view.ready) {
+                warnings.push(`couldn't reopen '${meta.name}': ${view.reason}`);
+                continue;
+            }
+            try {
+                app.addSession(reopen(meta, { ...worktree, riftri: view?.backend }), false);
+            }
+            catch (err) {
+                warnings.push(`couldn't reopen '${meta.name}': ${err.message}`);
+            }
+        }
+        if (app.sessions.length > 0) {
+            app.focusIdx = 0;
+            app.notify(`reopened ${app.sessions.length} agent${app.sessions.length === 1 ? "" : "s"} from last time`, "Comment");
+        }
+    }
+    tui.addChild(app);
+    tui.setFocus(app);
+    terminal.setTitle("vigent");
+    tui.start();
+    if (warnings.length > 0)
+        app.notify(warnings.join(" · "));
+    tui.requestRender(true);
+    return undefined;
+}
+main()
+    .then((code) => {
+    if (code !== undefined)
+        process.exitCode = code;
+})
+    .catch((err) => {
+    console.error(`vigent: ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+});

package/dist/clipboard.js

@@ -0,0 +1,56 @@
+/**
+ * Copy text to the system clipboard, like vim's "+ register.
+ *
+ * Always sends OSC 52 (the terminal sets the clipboard; works over SSH and in
+ * tmux with set-clipboard on), and also pipes to a local clipboard tool when
+ * one is installed.
+ */
+import { spawn, spawnSync } from "node:child_process";
+const TOOLS = [
+    ["pbcopy", []],
+    ["wl-copy", []],
+    ["xclip", ["-selection", "clipboard"]],
+    ["xsel", ["--clipboard", "--input"]],
+    ["clip.exe", []],
+];
+let cachedTool;
+function localTool() {
+    if (cachedTool !== undefined)
+        return cachedTool;
+    cachedTool = null;
+    for (const [cmd, args] of TOOLS) {
+        if (cmd === "wl-copy" && !process.env.WAYLAND_DISPLAY)
+            continue;
+        if ((cmd === "xclip" || cmd === "xsel") && !process.env.DISPLAY)
+            continue;
+        const which = spawnSync(process.platform === "win32" ? "where" : "which", [cmd], { stdio: "ignore" });
+        if (which.status === 0) {
+            cachedTool = [cmd, args];
+            break;
+        }
+    }
+    return cachedTool;
+}
+/** The OSC 52 escape sequence that asks the terminal to set its clipboard. */
+export function osc52(text) {
+    const seq = `\x1b]52;c;${Buffer.from(text, "utf8").toString("base64")}\x07`;
+    // inside tmux, wrap it so tmux passes it on to the outer terminal
+    return process.env.TMUX ? `\x1bPtmux;${seq.replace(/\x1b/g, "\x1b\x1b")}\x1b\\` : seq;
+}
+/** Copy `text`. `write` sends raw bytes to the terminal. Returns how it was copied. */
+export function copyToClipboard(text, write) {
+    write(osc52(text));
+    const tool = localTool();
+    if (tool) {
+        try {
+            const child = spawn(tool[0], tool[1], { stdio: ["pipe", "ignore", "ignore"] });
+            child.on("error", () => { });
+            child.stdin.end(text);
+            return tool[0];
+        }
+        catch {
+            // fall back to OSC 52 only
+        }
+    }
+    return "terminal";
+}

package/dist/color.js

@@ -0,0 +1,126 @@
+/** Color helpers: hex math, xterm-256 palette, and vim color names. */
+export function parseHex(hex) {
+    if (!hex)
+        return null;
+    const m = /^#?([0-9a-fA-F]{6})$/.exec(hex.trim());
+    if (!m)
+        return null;
+    const n = parseInt(m[1], 16);
+    return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
+}
+export function toHex([r, g, b]) {
+    const h = (v) => Math.round(Math.max(0, Math.min(255, v))).toString(16).padStart(2, "0");
+    return `#${h(r)}${h(g)}${h(b)}`;
+}
+/** Blend a toward b by t (0..1). Returns a unchanged if either color is invalid. */
+export function mix(a, b, t) {
+    const x = parseHex(a);
+    const y = parseHex(b);
+    if (!x || !y)
+        return a;
+    return toHex([x[0] + (y[0] - x[0]) * t, x[1] + (y[1] - x[1]) * t, x[2] + (y[2] - x[2]) * t]);
+}
+/** Relative luminance, 0 (black) .. 1 (white). */
+export function luminance(hex) {
+    const c = parseHex(hex);
+    if (!c)
+        return 0;
+    const [r, g, b] = c.map((v) => {
+        const s = v / 255;
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+export function isLight(hex) {
+    return hex ? luminance(hex) > 0.35 : false;
+}
+const XTERM_16 = [
+    "#000000", "#800000", "#008000", "#808000", "#000080", "#800080", "#008080", "#c0c0c0",
+    "#808080", "#ff0000", "#00ff00", "#ffff00", "#0000ff", "#ff00ff", "#00ffff", "#ffffff",
+];
+/** Convert an xterm-256 color index to hex. */
+export function xterm256(n) {
+    if (!Number.isInteger(n) || n < 0 || n > 255)
+        return undefined;
+    if (n < 16)
+        return XTERM_16[n];
+    if (n < 232) {
+        const levels = [0, 95, 135, 175, 215, 255];
+        const i = n - 16;
+        return toHex([levels[Math.floor(i / 36)], levels[Math.floor(i / 6) % 6], levels[i % 6]]);
+    }
+    const v = 8 + (n - 232) * 10;
+    return toHex([v, v, v]);
+}
+/** Vim's cterm color names (ctermfg=DarkBlue) -> xterm index. */
+const CTERM_NAMES = {
+    black: 0, darkred: 1, darkgreen: 2, brown: 3, darkyellow: 3, darkblue: 4, darkmagenta: 5,
+    darkcyan: 6, lightgray: 7, lightgrey: 7, gray: 7, grey: 7, darkgray: 8, darkgrey: 8,
+    red: 9, lightred: 9, green: 10, lightgreen: 10, yellow: 11, lightyellow: 11, blue: 12,
+    lightblue: 12, magenta: 13, lightmagenta: 13, cyan: 14, lightcyan: 14, white: 15,
+};
+/** Common GUI color names used by vim colorschemes (values from vim's rgb list). */
+const GUI_NAMES = {
+    black: "#000000", white: "#ffffff", red: "#ff0000", green: "#00ff00", blue: "#0000ff",
+    yellow: "#ffff00", cyan: "#00ffff", magenta: "#ff00ff", gray: "#bebebe", grey: "#bebebe",
+    darkgray: "#a9a9a9", darkgrey: "#a9a9a9", lightgray: "#d3d3d3", lightgrey: "#d3d3d3",
+    darkred: "#8b0000", darkgreen: "#006400", darkblue: "#00008b", darkcyan: "#008b8b",
+    darkmagenta: "#8b008b", darkyellow: "#bbbb00", brown: "#a52a2a", orange: "#ffa500",
+    purple: "#a020f0", lightblue: "#add8e6", lightgreen: "#90ee90", lightcyan: "#e0ffff",
+    lightred: "#ffbbbb", lightmagenta: "#ffbbff", lightyellow: "#ffffe0", seagreen: "#2e8b57",
+    slateblue: "#6a5acd", gold: "#ffd700", khaki: "#f0e68c", navy: "#000080", wheat: "#f5deb3",
+    peru: "#cd853f", salmon: "#fa8072", orangered: "#ff4500", skyblue: "#87ceeb",
+    violet: "#ee82ee", tan: "#d2b48c", olive: "#808000", teal: "#008080", maroon: "#800000",
+    silver: "#c0c0c0", pink: "#ffc0cb", indianred: "#cd5c5c", steelblue: "#4682b4",
+    darkslategray: "#2f4f4f", darkslategrey: "#2f4f4f", darkolivegreen: "#556b2f",
+    darkorange: "#ff8c00", lightslategray: "#778899", midnightblue: "#191970",
+};
+/**
+ * Resolve a vim color value to hex: "#rrggbb", "NONE", a GUI color name,
+ * grayN/greyN, or (for cterm) an xterm index or cterm name.
+ * Returns "NONE", a hex string, or undefined if unknown.
+ */
+export function resolveVimColor(value, cterm = false) {
+    const v = value.trim().replace(/^["']|["']$/g, "");
+    const lower = v.toLowerCase();
+    if (lower === "none")
+        return "NONE";
+    if (lower === "fg" || lower === "bg" || lower === "foreground" || lower === "background")
+        return undefined;
+    if (parseHex(v))
+        return `#${v.replace(/^#/, "").toLowerCase()}`;
+    if (cterm) {
+        if (/^\d+$/.test(v))
+            return xterm256(Number(v));
+        const idx = CTERM_NAMES[lower.replace(/\s+/g, "")];
+        return idx === undefined ? undefined : xterm256(idx);
+    }
+    const gray = /^gr[ae]y(\d{1,3})$/.exec(lower);
+    if (gray) {
+        const n = Math.round((Math.min(100, Number(gray[1])) * 255) / 100);
+        return toHex([n, n, n]);
+    }
+    return GUI_NAMES[lower.replace(/\s+/g, "")];
+}
+/** The xterm-256 index closest to a hex color (6x6x6 cube or grayscale ramp). */
+export function nearest256(hex) {
+    const c = parseHex(hex);
+    if (!c)
+        return 7;
+    const levels = [0, 95, 135, 175, 215, 255];
+    const idx = (v) => {
+        let best = 0;
+        for (let i = 1; i < 6; i++)
+            if (Math.abs(levels[i] - v) < Math.abs(levels[best] - v))
+                best = i;
+        return best;
+    };
+    const [r, g, b] = c.map(idx);
+    const cube = 16 + 36 * r + 6 * g + b;
+    const cubeRgb = [levels[r], levels[g], levels[b]];
+    const avg = (c[0] + c[1] + c[2]) / 3;
+    const grayIdx = Math.max(0, Math.min(23, Math.round((avg - 8) / 10)));
+    const grayV = 8 + grayIdx * 10;
+    const dist = (x) => (x[0] - c[0]) ** 2 + (x[1] - c[1]) ** 2 + (x[2] - c[2]) ** 2;
+    return dist([grayV, grayV, grayV]) < dist(cubeRgb) ? 232 + grayIdx : cube;
+}

package/dist/config-edit.js

@@ -0,0 +1,61 @@
+/**
+ * Edit config.toml in place for `:settings`: change one value and keep
+ * everything else (comments, order, other keys) as the user wrote it.
+ */
+/** A TOML value: strings quoted, booleans and numbers as they are. */
+export function tomlValue(v) {
+    return typeof v === "string" ? JSON.stringify(v) : String(v);
+}
+/** A TOML key: bare when it can be, quoted otherwise (`"<leader>n"`). */
+export function tomlKey(k) {
+    return /^[A-Za-z0-9_-]+$/.test(k) ? k : JSON.stringify(k);
+}
+const header = /^\s*\[([^\][]+)\]\s*(#.*)?$/;
+/**
+ * Set `key = value` in `[section]` (or at the top level when section is
+ * undefined). A commented-out line for the same key (`# key = …`) is replaced
+ * in place, so the setting stays where the template documents it.
+ */
+export function setTomlValue(text, section, key, value) {
+    const lines = text.length ? text.replace(/\n$/, "").split("\n") : [];
+    const line = `${tomlKey(key)} = ${value}`;
+    const keyRe = new RegExp(`^(\\s*)(#\\s*)?${escape(tomlKey(key))}\\s*=`);
+    // the range of lines that belong to the section
+    let start = 0;
+    let end = lines.findIndex((l) => header.test(l));
+    if (end < 0)
+        end = lines.length;
+    if (section) {
+        const at = lines.findIndex((l) => header.exec(l)?.[1].trim() === section);
+        if (at < 0) {
+            // a new section at the end
+            const out = [...lines];
+            if (out.length && out[out.length - 1].trim() !== "")
+                out.push("");
+            out.push(`[${section}]`, line);
+            return `${out.join("\n")}\n`;
+        }
+        start = at + 1;
+        end = lines.findIndex((l, i) => i >= start && header.test(l));
+        if (end < 0)
+            end = lines.length;
+    }
+    const live = lines.findIndex((l, i) => i >= start && i < end && keyRe.test(l) && !/^\s*#/.test(l));
+    const commented = lines.findIndex((l, i) => i >= start && i < end && keyRe.test(l) && /^\s*#/.test(l));
+    const out = [...lines];
+    const at = live >= 0 ? live : commented;
+    if (at >= 0) {
+        out[at] = line;
+    }
+    else {
+        // after the last non-blank line of the section
+        let insert = end;
+        while (insert > start && out[insert - 1].trim() === "")
+            insert--;
+        out.splice(insert, 0, line);
+    }
+    return `${out.join("\n")}\n`;
+}
+function escape(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}