@jv-k/claude-gauge 0.0.1 → 1.1.0

package/dist/launcher.js

@@ -0,0 +1,78 @@
+"use strict";
+// The plugin route's launcher: runs a script from the newest installed
+// version of the claude-gauge plugin.
+//
+// Claude Code keeps each installed plugin version in its own folder,
+// <plugins>/cache/<marketplace>/<plugin>/<version>/, and deletes an old one
+// some days after an update. Settings that named a version folder would run
+// an old version after an update, and nothing once it is deleted. So setup,
+// run from the plugin, copies this file into the state folder as
+// launcher/launch.js, beside a statusline.js and a tokenline.js that each
+// call launch() with the folder that holds the versions, and points the
+// settings at those two. A plugin update then needs no setup.
+//
+// The launcher never changes, so it reads nothing of the plugin but the
+// script it runs, and it prints nothing when no version is installed: a
+// status line that has lost its plugin goes blank rather than showing an
+// error on every refresh.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newest = newest;
+exports.launch = launch;
+const node_child_process_1 = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+const VERSION = /^v?(\d+)\.(\d+)\.(\d+)/;
+// Newest first: a version with a version number, by that number, then the
+// most recently installed folder.
+function compare(a, b) {
+    if (!a.version !== !b.version)
+        return a.version ? -1 : 1;
+    if (a.version && b.version) {
+        for (let i = 0; i < a.version.length; i++) {
+            if (a.version[i] !== b.version[i])
+                return b.version[i] - a.version[i];
+        }
+    }
+    return b.time - a.time;
+}
+// The path of `script` in the newest version under `versions`, or undefined
+// when no installed version holds it. Claude Code writes .orphaned_at into
+// the folder of a version that an update or an uninstall replaced, and
+// deletes the folder some days later, so a marked folder is not installed.
+function newest(versions, script) {
+    let names;
+    try {
+        names = fs.readdirSync(versions);
+    }
+    catch {
+        return undefined;
+    }
+    const found = [];
+    for (const name of names) {
+        const folder = path.join(versions, name);
+        const file = path.join(folder, 'dist', script);
+        try {
+            if (!fs.statSync(file).isFile() || fs.existsSync(path.join(folder, '.orphaned_at')))
+                continue;
+            const m = VERSION.exec(name);
+            found.push({
+                file,
+                version: m ? m.slice(1).map(Number) : undefined,
+                time: fs.statSync(folder).mtimeMs,
+            });
+        }
+        catch {
+            // A version folder that cannot be read is skipped.
+        }
+    }
+    return found.sort(compare)[0]?.file;
+}
+// Runs `script` from the newest version with this process's switches, input
+// and output, and exits as it does.
+function launch(versions, script) {
+    const file = newest(versions, script);
+    if (!file)
+        return;
+    const r = (0, node_child_process_1.spawnSync)(process.execPath, [file, ...process.argv.slice(2)], { stdio: 'inherit' });
+    process.exitCode = r.status ?? 1;
+}

package/dist/settings-file.js

@@ -0,0 +1,137 @@
+"use strict";
+// The settings writer's file half: reads settings.json, and writes it back
+// atomically, through a symlink to its target, after a timestamped backup.
+// What to write is plan()'s job, in settings.ts.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSettings = readSettings;
+exports.writeSettings = writeSettings;
+exports.writeAtomic = writeAtomic;
+const fs = require("node:fs");
+const path = require("node:path");
+// Reads settings.json. A missing or empty file reads as {}. A file that is
+// not a JSON object stops the write: claude-gauge never guesses at a file it
+// cannot read.
+function readSettings(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { settings: {}, text: null };
+        throw err;
+    }
+    if (!text.trim())
+        return { settings: {}, text };
+    let settings;
+    try {
+        settings = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`${file} is not valid JSON (${err.message}), so claude-gauge leaves it alone. Fix it by hand.`);
+    }
+    if (typeof settings !== 'object' || settings === null || Array.isArray(settings)) {
+        throw new Error(`${file} does not hold a JSON object, so claude-gauge leaves it alone. Fix it by hand.`);
+    }
+    return { settings: settings, text };
+}
+// The file a write to `file` should replace: the target of a symlink, even
+// one whose target does not exist yet, or the file itself. Replacing the
+// link instead would cut it from a dotfiles repository.
+function targetOf(file) {
+    try {
+        return fs.realpathSync(file);
+    }
+    catch {
+        try {
+            return path.resolve(path.dirname(file), fs.readlinkSync(file));
+        }
+        catch {
+            return file;
+        }
+    }
+}
+// Windows refuses a rename over a file that another program has open for a
+// moment, so a rename there gets a few short retries.
+const BUSY = new Set(['EPERM', 'EACCES', 'EBUSY']);
+const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+function renameWithRetry(from, to) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            fs.renameSync(from, to);
+            return;
+        }
+        catch (err) {
+            if (process.platform !== 'win32' || attempt >= 5 || !BUSY.has(err.code ?? ''))
+                throw err;
+            pause(50 * attempt);
+        }
+    }
+}
+// Writes `text` to `file` so that a reader sees the old file or the new one,
+// never part of either: a temporary file beside the target, flushed, then
+// renamed over it. The target keeps its permissions.
+function writeAtomic(file, text) {
+    const target = targetOf(file);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const tmp = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.${Date.now()}.tmp`);
+    let mode;
+    try {
+        mode = fs.statSync(target).mode & 0o777;
+    }
+    catch {
+        /* a new file takes the default permissions */
+    }
+    try {
+        const fd = fs.openSync(tmp, 'wx', mode ?? 0o666);
+        try {
+            fs.writeFileSync(fd, text);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        if (mode !== undefined)
+            fs.chmodSync(tmp, mode);
+        renameWithRetry(tmp, target);
+    }
+    catch (err) {
+        fs.rmSync(tmp, { force: true });
+        throw err;
+    }
+}
+// 2026-10-09T00-07-18-123Z: an ISO time with no colons, which Windows
+// forbids in file names.
+const stamp = (d) => d.toISOString().replace(/:/g, '-').replace('.', '-');
+// Copies `file` to a timestamped backup beside it, beside the link when it is
+// one, and returns the backup's path; null when there is no file to back up.
+function backUp(file, now = new Date()) {
+    if (!fs.existsSync(file))
+        return null;
+    const base = `${file}.claude-gauge-${stamp(now)}`;
+    for (let n = 0;; n++) {
+        const backup = n ? `${base}-${n}.bak` : `${base}.bak`;
+        try {
+            fs.copyFileSync(file, backup, fs.constants.COPYFILE_EXCL);
+            return backup;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+        }
+    }
+}
+// The new file's text in the old file's layout: its indent and line ends,
+// else two spaces and \n.
+function format(settings, previous) {
+    const indent = (previous && /^[ \t]+(?=")/m.exec(previous)?.[0]) || 2;
+    const text = JSON.stringify(settings, null, indent) + '\n';
+    return previous?.includes('\r\n') ? text.replace(/\n/g, '\r\n') : text;
+}
+// Backs settings.json up, then writes `settings` over it. Returns the
+// backup's path, or null when there was no file before.
+function writeSettings(file, settings, previous) {
+    const backup = backUp(file);
+    writeAtomic(file, format(settings, previous));
+    return backup;
+}

package/dist/settings.js

@@ -0,0 +1,257 @@
+"use strict";
+// The settings writer's pure half: plan() takes the settings Claude Code
+// reads and the user's choices, and returns the next settings, the status
+// line to save for uninstall, and what it found. It reads no file and writes
+// none; settings-file.ts and the CLI do that.
+//
+// claude-gauge owns at most three things in settings.json: `statusLine` when
+// it runs claude-gauge's status line, its token line entry in `hooks.Stop`,
+// and the `--instruct` entries in `hooks.SessionStart`. plan() changes only
+// those, and keeps every other key, including the status line's
+// `refreshInterval`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isForeign = exports.scriptOf = void 0;
+exports.plan = plan;
+exports.commandFor = commandFor;
+exports.switchesOf = switchesOf;
+exports.installed = installed;
+exports.installedSwitches = installedSwitches;
+exports.ownerOf = ownerOf;
+// A command that runs one of claude-gauge's scripts, wherever the copy lives:
+// ~/.claude/claude-gauge/dist/, its runtime/ copy, the scripts from before
+// they moved into dist/, or a Windows path to any of them. The folder name
+// must be a whole path component and the script name must end the word, so
+// not-claude-gauge/ or statusline.js.old is someone else's.
+const SCRIPT = /(?<![^\s'"\\/])claude-gauge[\\/](?:[^\s'"]*[\\/])?(statusline|tokenline)\.js(?![^\s'"])/;
+const scriptOf = (command) => (typeof command === 'string' ? SCRIPT.exec(command)?.[1] : undefined);
+exports.scriptOf = scriptOf;
+const isInstruct = (command) => typeof command === 'string' && /(?:^|\s)--instruct\b/.test(command);
+// The token line's Stop hook, as opposed to its --instruct SessionStart one.
+const isTokenLine = (h) => scriptOf(h.command) === 'tokenline' && !isInstruct(h.command);
+const isOurs = (h) => scriptOf(h.command) !== undefined;
+// Whether writing claude-gauge's status line over this owner's replaces
+// someone else's, which needs the user's consent.
+const isForeign = (owner) => owner === 'other' || owner === 'claude-hud';
+exports.isForeign = isForeign;
+function ownerOf(statusLine) {
+    if (statusLine === undefined || statusLine === null)
+        return 'none';
+    const command = statusLine.command;
+    if (scriptOf(command) === 'statusline')
+        return 'claude-gauge';
+    if (typeof command === 'string' && /claude-hud/i.test(command))
+        return 'claude-hud';
+    return 'other';
+}
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+// The settings' hooks, checked as far as plan() reads them. A shape it does
+// not know stops the plan, because writing over it would lose the user's
+// hooks.
+function readHooks(settings) {
+    const hooks = settings.hooks;
+    if (hooks === undefined)
+        return undefined;
+    if (!isObject(hooks))
+        throw new Error('settings.json: hooks is not an object, so claude-gauge leaves it alone. Fix it by hand.');
+    for (const [event, entries] of Object.entries(hooks)) {
+        const readable = (e) => isObject(e) && (e.hooks === undefined || (Array.isArray(e.hooks) && e.hooks.every(isObject)));
+        if (!Array.isArray(entries) || !entries.every(readable)) {
+            throw new Error(`settings.json: hooks.${event} is not a list of hook entries, so claude-gauge leaves it alone. Fix it by hand.`);
+        }
+    }
+    return hooks;
+}
+// Takes the hook commands that `drop` matches out of `event`, then any entry
+// and event that this left empty. Lists that were empty before stay.
+function removeHooks(hooks, event, drop) {
+    const entries = hooks[event];
+    if (!entries)
+        return;
+    let removed = false;
+    const kept = [];
+    for (const e of entries) {
+        const commands = e.hooks ?? [];
+        const left = commands.filter((h) => !drop(h));
+        if (left.length === commands.length) {
+            kept.push(e);
+            continue;
+        }
+        removed = true;
+        if (left.length)
+            kept.push({ ...e, hooks: left });
+    }
+    if (!removed)
+        return;
+    if (kept.length)
+        hooks[event] = kept;
+    else
+        delete hooks[event];
+}
+// Points the token line's Stop hook at `command`: the first existing one is
+// updated in place, any others are removed, and with none an entry is added
+// at the end.
+function setTokenLine(hooks, command) {
+    const stop = hooks.Stop ?? [];
+    let done = false;
+    const next = [];
+    for (const e of stop) {
+        const commands = e.hooks ?? [];
+        if (!commands.some(isTokenLine)) {
+            next.push(e);
+            continue;
+        }
+        const left = [];
+        for (const h of commands) {
+            if (!isTokenLine(h))
+                left.push(h);
+            else if (!done) {
+                left.push({ ...h, type: 'command', command });
+                done = true;
+            }
+        }
+        if (left.length)
+            next.push({ ...e, hooks: left });
+    }
+    if (!done)
+        next.push({ hooks: [{ type: 'command', command }] });
+    hooks.Stop = next;
+}
+function plan(current, choices) {
+    const settings = JSON.parse(JSON.stringify(current ?? {}));
+    const found = ownerOf(settings.statusLine);
+    if (settings.statusLine === null)
+        delete settings.statusLine;
+    if (settings.statusLine !== undefined && !isObject(settings.statusLine)) {
+        throw new Error('settings.json: statusLine is not an object, so claude-gauge leaves it alone. Fix it by hand.');
+    }
+    const hooks = readHooks(settings);
+    const statusChoice = choices.uninstall ? null : choices.statusLine;
+    const tokenChoice = choices.uninstall ? null : choices.tokenLine;
+    const takeOver = typeof statusChoice === 'string' && isForeign(found);
+    if (takeOver && !choices.replace) {
+        return { settings, dropBackup: false, found, blocked: true, changed: false };
+    }
+    let backup;
+    if (typeof statusChoice === 'string') {
+        if (found !== 'claude-gauge') {
+            backup = { statusLine: settings.statusLine ?? null };
+        }
+        settings.statusLine = { ...settings.statusLine, type: 'command', command: statusChoice };
+    }
+    else if (statusChoice === null && found === 'claude-gauge') {
+        if (choices.previous)
+            settings.statusLine = choices.previous;
+        else
+            delete settings.statusLine;
+    }
+    if (tokenChoice !== undefined || choices.uninstall) {
+        const next = hooks ?? {};
+        if (typeof tokenChoice === 'string')
+            setTokenLine(next, tokenChoice);
+        else if (choices.uninstall)
+            for (const event of Object.keys(next))
+                removeHooks(next, event, isOurs);
+        else
+            removeHooks(next, 'Stop', isTokenLine);
+        // A hooks object that held only claude-gauge's entries goes with them.
+        // One that was absent, or empty already, stays as it was.
+        const hadHooks = isObject(current?.hooks) && Object.keys(current.hooks).length > 0;
+        if (Object.keys(next).length)
+            settings.hooks = next;
+        else if (hadHooks)
+            delete settings.hooks;
+    }
+    return {
+        settings,
+        ...(backup ? { backup } : {}),
+        dropBackup: statusChoice === null,
+        found,
+        blocked: false,
+        changed: JSON.stringify(settings) !== JSON.stringify(current ?? {}),
+    };
+}
+// claude-gauge's commands in the settings: the status line, the token
+// line's Stop hook, and whether any hook in any event runs one of its
+// scripts. Hooks it cannot read stop it, as they stop plan().
+function installed(settings) {
+    const statusLine = ownerOf(settings.statusLine) === 'claude-gauge' ? settings.statusLine.command : undefined;
+    const hooks = readHooks(settings) ?? {};
+    const commandsIn = (entries) => entries.flatMap((e) => e.hooks ?? []);
+    const tokenLine = commandsIn(hooks.Stop ?? []).find(isTokenLine)?.command;
+    const anyHook = Object.values(hooks).some((entries) => commandsIn(entries).some(isOurs));
+    return { statusLine, tokenLine, any: statusLine !== undefined || anyHook };
+}
+function installedSwitches(settings) {
+    const { statusLine, tokenLine } = installed(settings);
+    return {
+        ...(statusLine === undefined ? {} : { statusLine: switchesOf(statusLine) }),
+        ...(tokenLine === undefined ? {} : { tokenLine: switchesOf(tokenLine) }),
+    };
+}
+// A shell word for a settings command: as is when plain, in double quotes
+// when it holds only spaces or other characters both bash and cmd.exe read
+// literally there, else in single quotes. Claude Code runs the command
+// through a shell on every OS.
+const shellWord = (s) => /^[\w@%+=:,./~-]+$/.test(s) ? s : /^[^"$`\\!']*$/.test(s) ? `"${s}"` : `'${s.replace(/'/g, `'\\''`)}'`;
+// The command that runs `script` with the switches the user chose: one
+// string split at spaces, `--show ctx,5h,7d --segments 10`, or the words
+// themselves, which keeps a value that holds a space. Each word is quoted on
+// its own, so nothing in it can run as a second command.
+function commandFor(script, switches = '') {
+    const words = typeof switches === 'string' ? switches.split(/\s+/).filter(Boolean) : switches;
+    return ['node', script.replace(/\\/g, '/'), ...words].map(shellWord).join(' ');
+}
+// The words of a command as the shell splits them, which undoes shellWord:
+// single quotes keep everything, double quotes keep all but an escaped " \ $
+// or `, and a backslash outside quotes keeps the next character. Each word
+// keeps its text as written too, `raw`, where a Windows path still has its
+// backslashes.
+function shellWords(command) {
+    const words = [];
+    let value = '';
+    let start = -1;
+    let quote = null;
+    for (let i = 0; i < command.length; i++) {
+        const c = command[i];
+        if (quote === "'") {
+            if (c === "'")
+                quote = null;
+            else
+                value += c;
+        }
+        else if (quote === '"') {
+            if (c === '"')
+                quote = null;
+            else if (c === '\\' && i + 1 < command.length && '"\\$`'.includes(command[i + 1]))
+                value += command[++i];
+            else
+                value += c;
+        }
+        else if (/\s/.test(c)) {
+            if (start >= 0)
+                words.push({ value, raw: command.slice(start, i) });
+            value = '';
+            start = -1;
+        }
+        else {
+            if (start < 0)
+                start = i;
+            if (c === "'" || c === '"')
+                quote = c;
+            else if (c === '\\' && i + 1 < command.length)
+                value += command[++i];
+            else
+                value += c;
+        }
+    }
+    if (start >= 0)
+        words.push({ value, raw: command.slice(start) });
+    return words;
+}
+// The switches a claude-gauge command runs its script with, as words: the
+// inverse of commandFor. None when the command runs no claude-gauge script.
+function switchesOf(command) {
+    const words = shellWords(command);
+    const at = words.findIndex((w) => scriptOf(w.raw) !== undefined);
+    return at < 0 ? [] : words.slice(at + 1).map((w) => w.value);
+}