estela 0.2.3 → 0.2.4

package/README.md

@@ -306,6 +306,16 @@ won't overwrite it: `--force` replaces it, `--append` shows yours after
 Estela's. `estela statusline uninstall` removes it (and puts yours back if
 you used `--append`).
 
+The status line only runs in Claude Code in the terminal: the VS Code
+extension doesn't show it.
+
+Since 0.2.4, the status line stores your 5-hour and weekly percentages locally
+(`~/.estela/rate-limits.jsonl`) so `estela plan` can analyse them. Nothing leaves
+your machine. Only what Claude Code sends is kept — each percentage, its reset
+time and the Claude Code version — at most every 5 minutes unless a figure moves,
+and for 120 days. Transcripts don't carry these percentages, so the history
+starts the day you install 0.2.4.
+
 ## Hours no import will infer
 
 Meetings, travel, research, and development without an agent that didn't leave

package/dist/cli.js

@@ -2134,6 +2134,7 @@ function cmdStatuslineInstall(args) {
     }
     if (plan.status === "already") {
         console.log((0, index_js_1.tr) `La status line de Estela ya está instalada en ${path}.`);
+        console.log((0, index_js_1.tr) `Solo en Claude Code en la terminal: la extensión de VS Code no enseña la status line.`);
         return;
     }
     if (plan.status === "conflict") {
@@ -2158,6 +2159,9 @@ function cmdStatuslineInstall(args) {
             ? (0, index_js_1.tr) `Status line de Estela instalada en lugar de: ${plan.previous ?? ""}`
             : (0, index_js_1.tr) `Status line de Estela instalada en ${path}.`);
     console.log((0, index_js_1.tr) `Se verá en la próxima sesión de Claude Code (o al reiniciar la actual).`);
+    // Comprobado: la extensión de VS Code no ejecuta la status line. Sin este
+    // aviso, quien trabaja ahí cree que está instalada y no la ve nunca.
+    console.log((0, index_js_1.tr) `Solo en Claude Code en la terminal: la extensión de VS Code no enseña la status line.`);
     if (!(0, statusline_install_js_1.estelaOnPath)()) {
         console.log((0, index_js_1.tr) `\nAviso: "estela" no está en tu PATH, así que Claude Code no podrá ejecutarla.`);
         console.log((0, index_js_1.tr) `Instálala de forma global: npm install -g estela`);

package/dist/i18n/en.js

@@ -577,5 +577,7 @@ exports.EN = {
     "No hay ningún panel publicado de \"{0}\". Míralos con: estela unpublish": "There's no published dashboard for \"{0}\". See them with: estela unpublish",
     // ── ESTELA_OFFLINE ──
     "ESTELA_OFFLINE=1: Estela no se conecta a la red. Quita la variable para usar tu cuenta.": "ESTELA_OFFLINE=1: Estela doesn't connect to the network. Unset it to use your account.",
+    // ── statusline install: VS Code ──
+    "Solo en Claude Code en la terminal: la extensión de VS Code no enseña la status line.": "Only in Claude Code in the terminal: the VS Code extension doesn't show the status line.",
 };
 //# sourceMappingURL=en.js.map

package/dist/rate-history.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `~/.estela/rate-limits.jsonl`: el historial de los porcentajes de límite que
+ * Claude Code manda a la status line. Es lo que analiza `estela plan`.
+ *
+ * Solo se guarda lo que manda Claude Code, tal cual: el porcentaje usado y el
+ * reinicio de cada ventana, y su versión. Ni sesión, ni rutas, ni proyectos.
+ * Estela no estima ningún límite: sin `rate_limits` en la entrada (API key, o
+ * la primera respuesta de la sesión aún no llegó), no se guarda nada.
+ *
+ * Los transcripts no traen estos porcentajes, así que no hay forma de
+ * recuperar el pasado: el historial empieza el día que se instala la 0.2.4. Y
+ * solo se recoge con Claude Code en la terminal; la extensión de VS Code no
+ * ejecuta la status line.
+ *
+ * Va por el camino rápido de la status line (100 ms): sin `node:sqlite`, una
+ * línea por `appendFileSync`, y cualquier error se ignora.
+ */
+export interface RateSample {
+    /** Epoch en ms de la muestra. */
+    readonly ts: number;
+    readonly src: "claude-code";
+    readonly w5?: number;
+    /** `resets_at` tal cual (epoch en s). */
+    readonly w5_reset?: number;
+    readonly w7?: number;
+    readonly w7_reset?: number;
+    /** Versión de Claude Code, si viene. */
+    readonly cc?: string;
+}
+export declare const KEEP_DAYS = 120;
+export declare function historyPath(dbPath: string): string;
+/**
+ * La muestra que sale del JSON de la status line, o null si no trae ningún
+ * porcentaje. Cada ventana que falte se omite: nunca se escribe un 0.
+ */
+export declare function sampleOf(raw: unknown, now: Date): RateSample | null;
+/**
+ * Si vale la pena guardar la muestra: han pasado 5 minutos desde la última,
+ * algún porcentaje cambió al menos un punto, o empezó una ventana nueva.
+ */
+export declare function shouldWrite(last: RateSample | undefined, s: RateSample): boolean;
+/**
+ * Lo que hace la status line en cada evento. Nunca lanza: es un historial, y
+ * la línea tiene que salir igual aunque no se pueda escribir.
+ *
+ * Solo escribe si ya existe el directorio de Estela: la status line no es
+ * quien empieza a guardar datos.
+ */
+export declare function recordSample(dbPath: string, raw: unknown, now: Date): void;
+/** Lee el historial. Las líneas rotas se saltan. */
+export declare function readSamples(file: string): RateSample[];
+/**
+ * Quita las muestras de hace más de 120 días. Reescribe en un fichero aparte y
+ * lo renombra encima: un corte a mitad no deja el historial a medias.
+ * Devuelve cuántas quitó.
+ *
+ * Corre desde la status line una vez al día, así que lo normal (nada que
+ * quitar) tiene que costar casi nada: el fichero se escribe en orden, y si la
+ * primera muestra no ha caducado, ninguna lo ha hecho. Solo entonces se lee
+ * entero, y el `ts` se saca del principio de cada línea sin parsear el JSON.
+ */
+export declare function pruneSamples(file: string, now: Date, keepDays?: number): number;
+//# sourceMappingURL=rate-history.d.ts.map

package/dist/rate-history.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEEP_DAYS = void 0;
+exports.historyPath = historyPath;
+exports.sampleOf = sampleOf;
+exports.shouldWrite = shouldWrite;
+exports.recordSample = recordSample;
+exports.readSamples = readSamples;
+exports.pruneSamples = pruneSamples;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const statusline_cache_js_1 = require("./statusline-cache.js");
+const MIN_GAP_MS = 5 * 60_000;
+const MIN_DELTA = 1;
+exports.KEEP_DAYS = 120;
+const PRUNE_EVERY_MS = 24 * 60 * 60_000;
+/** Cada cuánto se reescribe en la caché "se vio una sesión sin rate_limits". */
+const NO_LIMITS_EVERY_MS = 60 * 60_000;
+function historyPath(dbPath) {
+    return (0, node_path_1.join)((0, node_path_1.dirname)(dbPath), "rate-limits.jsonl");
+}
+/**
+ * La muestra que sale del JSON de la status line, o null si no trae ningún
+ * porcentaje. Cada ventana que falte se omite: nunca se escribe un 0.
+ */
+function sampleOf(raw, now) {
+    const o = obj(raw);
+    const limits = obj(o["rate_limits"]);
+    const five = obj(limits["five_hour"]);
+    const seven = obj(limits["seven_day"]);
+    const w5 = num(five["used_percentage"]);
+    const w7 = num(seven["used_percentage"]);
+    if (w5 === undefined && w7 === undefined)
+        return null;
+    const w5Reset = num(five["resets_at"]);
+    const w7Reset = num(seven["resets_at"]);
+    const cc = typeof o["version"] === "string" && o["version"] ? o["version"] : undefined;
+    return {
+        ts: now.getTime(), src: "claude-code",
+        ...(w5 !== undefined ? { w5 } : {}),
+        ...(w5Reset !== undefined ? { w5_reset: w5Reset } : {}),
+        ...(w7 !== undefined ? { w7 } : {}),
+        ...(w7Reset !== undefined ? { w7_reset: w7Reset } : {}),
+        ...(cc ? { cc } : {}),
+    };
+}
+/**
+ * Si vale la pena guardar la muestra: han pasado 5 minutos desde la última,
+ * algún porcentaje cambió al menos un punto, o empezó una ventana nueva.
+ */
+function shouldWrite(last, s) {
+    if (!last)
+        return true;
+    if (s.ts - last.ts >= MIN_GAP_MS)
+        return true;
+    if (moved(last.w5, s.w5) || moved(last.w7, s.w7))
+        return true;
+    return last.w5_reset !== s.w5_reset || last.w7_reset !== s.w7_reset;
+}
+function moved(a, b) {
+    if (a === undefined || b === undefined)
+        return a !== b;
+    return Math.abs(a - b) >= MIN_DELTA;
+}
+/**
+ * Lo que hace la status line en cada evento. Nunca lanza: es un historial, y
+ * la línea tiene que salir igual aunque no se pueda escribir.
+ *
+ * Solo escribe si ya existe el directorio de Estela: la status line no es
+ * quien empieza a guardar datos.
+ */
+function recordSample(dbPath, raw, now) {
+    try {
+        if (!(0, node_fs_1.existsSync)((0, node_path_1.dirname)(dbPath)))
+            return;
+        const cache = (0, statusline_cache_js_1.loadCache)(dbPath);
+        let changed = false;
+        const sample = sampleOf(raw, now);
+        if (!sample) {
+            // Para que `estela plan` distinga "sin datos" de "esto es una API key".
+            if (obj(raw)["rate_limits"] === undefined && stale(cache.noLimitsAt, now, NO_LIMITS_EVERY_MS)) {
+                cache.noLimitsAt = now.toISOString();
+                changed = true;
+            }
+        }
+        else if (shouldWrite(cache.lastSample, sample)) {
+            (0, node_fs_1.appendFileSync)(historyPath(dbPath), JSON.stringify(sample) + "\n");
+            cache.lastSample = sample;
+            changed = true;
+        }
+        if (sample && stale(cache.prunedAt, now, PRUNE_EVERY_MS)) {
+            pruneSamples(historyPath(dbPath), now);
+            cache.prunedAt = now.toISOString();
+            changed = true;
+        }
+        if (changed)
+            (0, statusline_cache_js_1.saveCache)(dbPath, cache);
+    }
+    catch { /* sin historial esta vez; la línea sale igual */ }
+}
+function stale(iso, now, ms) {
+    if (!iso)
+        return true;
+    const t = Date.parse(iso);
+    return Number.isNaN(t) || now.getTime() - t >= ms;
+}
+/** Lee el historial. Las líneas rotas se saltan. */
+function readSamples(file) {
+    let text;
+    try {
+        text = (0, node_fs_1.readFileSync)(file, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of text.split("\n")) {
+        if (!line)
+            continue;
+        try {
+            const s = JSON.parse(line);
+            if (s && typeof s.ts === "number")
+                out.push(s);
+        }
+        catch { /* línea a medias: se ignora */ }
+    }
+    return out;
+}
+/**
+ * Quita las muestras de hace más de 120 días. Reescribe en un fichero aparte y
+ * lo renombra encima: un corte a mitad no deja el historial a medias.
+ * Devuelve cuántas quitó.
+ *
+ * Corre desde la status line una vez al día, así que lo normal (nada que
+ * quitar) tiene que costar casi nada: el fichero se escribe en orden, y si la
+ * primera muestra no ha caducado, ninguna lo ha hecho. Solo entonces se lee
+ * entero, y el `ts` se saca del principio de cada línea sin parsear el JSON.
+ */
+function pruneSamples(file, now, keepDays = exports.KEEP_DAYS) {
+    const cutoff = now.getTime() - keepDays * 24 * 60 * 60_000;
+    const first = firstLine(file);
+    if (first === null)
+        return 0;
+    const firstTs = tsOf(first);
+    if (firstTs !== null && firstTs >= cutoff)
+        return 0;
+    const lines = (0, node_fs_1.readFileSync)(file, "utf8").split("\n").filter(Boolean);
+    const kept = lines.filter((line) => {
+        const ts = tsOf(line);
+        return ts !== null && ts >= cutoff;
+    });
+    if (kept.length === lines.length)
+        return 0;
+    const tmp = `${file}.tmp`;
+    (0, node_fs_1.writeFileSync)(tmp, kept.map((l) => l + "\n").join(""));
+    (0, node_fs_1.renameSync)(tmp, file);
+    return lines.length - kept.length;
+}
+/** El `ts` de una línea: siempre es el primer campo, porque así la escribe `sampleOf`. Null si está rota. */
+function tsOf(line) {
+    const m = /^\{"ts":(\d+),/.exec(line);
+    if (!m || !line.endsWith("}"))
+        return null;
+    return Number(m[1]);
+}
+function firstLine(file) {
+    let fd;
+    try {
+        fd = (0, node_fs_1.openSync)(file, "r");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const buf = Buffer.alloc(512);
+        const n = (0, node_fs_1.readSync)(fd, buf, 0, buf.length, 0);
+        if (n === 0)
+            return null;
+        const text = buf.subarray(0, n).toString("utf8");
+        const nl = text.indexOf("\n");
+        return nl >= 0 ? text.slice(0, nl) : text;
+    }
+    finally {
+        (0, node_fs_1.closeSync)(fd);
+    }
+}
+function obj(v) {
+    return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+}
+function num(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+//# sourceMappingURL=rate-history.js.map

package/dist/statusline-cache.d.ts

@@ -1,3 +1,4 @@
+import type { RateSample } from "./rate-history.js";
 /**
  * `statusline.json`, junto a la base: lo que la status line recuerda entre
  * llamadas.
@@ -7,6 +8,9 @@
  *    (porcentaje y reinicio) y cuándo se vio. La status line lo enseña al
  *    arrancar una sesión, antes de que lleguen datos nuevos, y `estela quota`
  *    usa el reinicio de la 5 h para saber dónde empieza de verdad la ventana.
+ *  - `lastSample`, `prunedAt`, `noLimitsAt`: del historial de
+ *    `rate-limits.jsonl` (ver rate-history.ts), para decidir si se guarda una
+ *    muestra sin tener que leer el fichero.
  *
  * Es una caché: si se pierde o se corrompe, todo sigue funcionando, solo que
  * relee más o vuelve a estimar.
@@ -25,6 +29,12 @@ export interface StatuslineCache {
     }>;
     fiveHour?: SeenLimit;
     sevenDay?: SeenLimit;
+    /** La última muestra guardada en rate-limits.jsonl. */
+    lastSample?: RateSample;
+    /** Cuándo se quitaron por última vez las muestras de más de 120 días. */
+    prunedAt?: string;
+    /** La última vez que llegó una entrada sin rate_limits (API key, o sesión recién abierta). */
+    noLimitsAt?: string;
 }
 export declare function cachePath(dbPath: string): string;
 export declare function loadCache(dbPath: string): StatuslineCache;

package/dist/statusline-run.js

@@ -43,6 +43,7 @@ const store = __importStar(require("./db/store.js"));
 const quota_js_1 = require("./metrics/quota.js");
 const paths_js_1 = require("./paths.js");
 const project_of_js_1 = require("./project-of.js");
+const rate_history_js_1 = require("./rate-history.js");
 const statusline_cache_js_1 = require("./statusline-cache.js");
 const statusline_js_1 = require("./statusline.js");
 const claude_js_1 = require("./watchers/claude.js");
@@ -65,6 +66,13 @@ async function runStatusline(argv) {
             }, now);
         }
         catch { /* es una caché: sin ella, la línea sale con lo que llegó */ }
+        // El historial de porcentajes para `estela plan`. No lanza nunca.
+        if (text.trim()) {
+            try {
+                (0, rate_history_js_1.recordSample)(flags.db, JSON.parse(text), now);
+            }
+            catch { /* entrada rota: ya lo cubre lo de abajo */ }
+        }
         const data = computeStatus({ ...input, ...limits }, flags.db, now);
         const ours = (0, statusline_js_1.renderStatus)(data, { columns, color: flags.color, reserved });
         process.stdout.write((extra ? `${ours}${flags.color ? "\x1b[90m | \x1b[0m" : " | "}${extra}` : ours) + "\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "estela",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Time tracking you never fill in: rebuilds your billable hours from Claude Code, Codex and GitHub Copilot sessions and your Git history, and splits what the AI cost per project.",
   "keywords": [
     "time-tracking",