claude-usage-explorer 1.0.0 → 1.1.5

package/tests/tui.test.mjs

@@ -0,0 +1,104 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {createExplorer,describePeriod} from '../src/tui.mjs';
+const z={input:3,output:2,cacheRead:5,cacheWrite:1,model:'claude-sonnet-4-5',timestamp:Date.now()};
+const data={sessions:[{id:'s1',title:'Example session',cwd:'/tmp/demo',start:Date.now(),end:Date.now(),agents:new Map([['main',{id:'main',requests:[z]}]])}],files:1,malformed:0,roots:[]};
+test('TUI drills from project to session to agent to model without LLM',()=>{
+ const x=createExplorer(data,{period:'all',cwd:'/tmp/demo',settings:{}});
+ assert.equal(x.rows().length,1);
+ assert.match(x.render(115,30),/CLAUDE USAGE EXPLORER/);
+ x.open();assert.equal(x.view,'sessions');assert.equal(x.rows()[0].title,'Example session');
+ x.open();assert.equal(x.view,'agents');assert.equal(x.rows()[0].id,'main');
+ x.open();assert.equal(x.view,'models');assert.equal(x.rows()[0].name,'claude-sonnet-4-5');
+ x.restore();assert.equal(x.view,'agents');
+});
+test('TUI switches dates and shows model columns',()=>{
+ const x=createExplorer(data,{period:'all',settings:{}});
+ x.nav('periods');const i=x.rows().findIndex(x=>x.value==='today');x.selection=i;x.open();
+ assert.equal(x.currentPeriod,'today');assert.match(x.render(120,30),/C.READ/);
+});
+test('TUI shows models for selected project without drilling into sessions',()=>{
+ const x=createExplorer(data,{period:'all',settings:{}});
+ assert.match(x.render(130,32),/MODELS IN SELECTED ROW/);
+ assert.match(x.render(130,32),/claude-sonnet-4-5/);
+ x.setSort('output');assert.equal(x.sort,'output');
+});
+test('TUI displays unknown model pricing as N/A, never a misleading zero',()=>{
+ const unknown={...z,model:'claude-unknown-9-9'};
+ const d={...data,sessions:[{...data.sessions[0],agents:new Map([['main',{id:'main',requests:[unknown]}]])}]};
+ const x=createExplorer(d,{period:'all',settings:{}});
+ assert.match(x.render(130,32),/N\/A/);
+});
+test('TUI footer and model panel remain at fixed rows as selection changes',()=>{
+ const extra={...data.sessions[0],id:'s2',title:'Another session',cwd:'/tmp/other'};
+ const x=createExplorer({...data,sessions:[...data.sessions,extra]},{period:'all',settings:{}});
+ const a=x.render(120,32).split('\n');
+ x.selection=1;
+ const b=x.render(120,32).split('\n');
+ for(const label of ['MODELS IN SELECTED ROW','Billing/settings','PgUp/PgDn scroll']){
+  const index=lines=>lines.findIndex(line=>line.includes(label));
+  assert.equal(index(a),index(b),label);
+ }
+ assert.equal(a.length,b.length);
+});
+
+test('billing periods appear first and require configuration before selection',()=>{
+ const x=createExplorer(data,{period:'all',settings:{}});
+ x.nav('periods');
+ assert.equal(x.rows()[0].value,'cycle');
+ assert.equal(x.rows()[1].value,'previous-cycle');
+ assert.equal(x.open(),'billing-required:cycle');
+ assert.equal(x.currentPeriod,'all');
+ x.setBillingDay(5,'Europe/Athens',10,30);
+ assert.equal(x.open(),null);
+ assert.equal(x.currentPeriod,'cycle');
+});
+test('custom date selection requests input instead of navigating or quitting',()=>{
+ const x=createExplorer(data,{period:'all',settings:{}});
+ x.nav('periods');
+ x.selection=x.rows().findIndex(r=>r.value==='custom');
+ assert.equal(x.open(),'custom');
+ assert.equal(x.view,'periods');
+ x.setPeriod('2026-11-01:2026-11-05');
+ assert.equal(x.currentPeriod,'2026-11-01:2026-11-05');
+});
+
+test('billing date choices and header show descriptive date ranges',()=>{
+ const settings={billingDay:1,billingTimeZone:'UTC',billingHour:0,billingMinute:0};
+ assert.equal(describePeriod('cycle',settings,Date.UTC(2026,10,5)),'Current billing cycle · Nov 1, 2026 – Nov 30, 2026');
+ assert.equal(describePeriod('previous-cycle',settings,Date.UTC(2026,10,5)),'Previous billing cycle · Oct 1, 2026 – Oct 31, 2026');
+ assert.match(describePeriod('cycle',{},Date.UTC(2026,10,5)),/Set renewal date/);
+ const x=createExplorer(data,{settings,period:'cycle'});
+ assert.match(x.render(130,32),/Current billing cycle/);
+ x.nav('periods');
+ assert.match(x.rows()[0].label,/Nov/);
+});
+
+test('live refresh preserves project, session, sorting, and period',()=>{
+ const x=createExplorer(data,{cwd:'/tmp/demo',settings:{}});
+ x.open();x.open();
+ x.setSort('output');x.setPeriod('today');
+ // Date changes intentionally reset the view; navigate back into the session.
+ x.open();x.open();
+ assert.equal(x.view,'agents');
+ x.rescan([], {automatic:true});
+ assert.equal(x.currentPeriod,'today');
+ assert.equal(x.sort,'output');
+ assert.equal(x.view,'projects'); // source was removed by rescan
+ x.toggleLive();assert.equal(x.liveState.enabled,false);
+ x.toggleLive();assert.equal(x.liveState.enabled,true);
+});
+
+test('file signature changes only when JSONL metadata changes', async()=>{
+ const {historySignature}=await import('../src/tui.mjs');
+ const fs=await import('node:fs');
+ const os=await import('node:os');
+ const path=await import('node:path');
+ const root=fs.mkdtempSync(path.join(os.tmpdir(),'claude-live-'));
+ try{
+  const file=path.join(root,'a.jsonl');
+  fs.writeFileSync(file,'a');const a=historySignature([root]);
+  assert.equal(a,historySignature([root]));
+  fs.appendFileSync(file,'bc');assert.notEqual(a,historySignature([root]));
+ }finally{fs.rmSync(root,{recursive:true,force:true});}
+});

package/commands/tui.md

@@ -1,12 +0,0 @@
----
-description: Launch the interactive Claude Usage Explorer in a separate terminal window, without model calls for navigation
-allowed-tools: Bash
----
-
-Launch the local TUI sidecar once, without asking the user any questions. Use the following command via Bash, passing the current project directory as CLAUDE_PROJECT_DIR when available:
-
-```sh
-node "${CLAUDE_PLUGIN_ROOT}/bin/claude-usage.mjs" open
-```
-
-Do not run the `tui` command directly in the Bash tool (it needs an interactive terminal). The `open` command starts a separate terminal process and exits immediately. Report only whether the launch succeeded. This slash command requires one Claude invocation; subsequent navigation and refreshes use zero model calls. Do not pretend it embeds inside the Claude Code conversation. If a terminal emulator is unsupported, advise running `node "${CLAUDE_PLUGIN_ROOT}/bin/claude-usage.mjs" tui` in a separate terminal.

package/src/plan-usage.mjs

@@ -1,39 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
-// Claude Desktop's plan-usage-history.json is undocumented, optional cached data.
-// Read only known numeric utilization fields; never expose organization identifiers.
-export function planUsageFromSamples(samples, now=Date.now()) {
-  if (!Array.isArray(samples)) return null;
-  const valid=samples.filter(s=>s && Number.isFinite(s.t) && s.u &&
-    (Number.isFinite(s.u.fh)||Number.isFinite(s.u.sd)))
-    .map(s=>({timestamp:s.t<1e12?s.t*1000:s.t,
-      fiveHour:Number.isFinite(s.u.fh)?s.u.fh:null,
-      sevenDay:Number.isFinite(s.u.sd)?s.u.sd:null}))
-    .filter(s=>s.timestamp>0 && s.timestamp<=now+86400000)
-    .sort((a,b)=>a.timestamp-b.timestamp);
-  if (!valid.length)return null;
-  const latest=valid.at(-1);
-  return { ...latest, stale:now-latest.timestamp>15*60*1000,
-    samples:valid.slice(-100),source:'Claude Desktop cached history'};
-}
-export function readPlanUsage({platform=process.platform,localAppData=process.env.LOCALAPPDATA,home=process.env.HOME,now=Date.now()}={}){
-  const roots=[];
-  if(platform==='win32'&&localAppData)roots.push(path.join(localAppData,'Claude-Data'));
-  if(platform==='darwin'&&home){roots.push(path.join(home,'Library','Application Support','Claude-Data'));roots.push(path.join(home,'Library','Application Support','Claude'));}
-  let best=null;
-  for(const root of roots){
-    let folders=[];
-    try{folders=fs.readdirSync(root,{withFileTypes:true}).filter(x=>x.isDirectory()&&x.name.startsWith('claude_')).map(x=>path.join(root,x.name));}catch{continue;}
-    for(const folder of folders){
-      try{
-        const file=path.join(folder,'plan-usage-history.json');
-        if(fs.statSync(file).size>2_000_000)continue;
-        const data=JSON.parse(fs.readFileSync(file,'utf8'));
-        const result=planUsageFromSamples(data.samples,now);
-        if(result&&(!best||result.timestamp>best.timestamp))best=result;
-      }catch{}
-    }
-  }
-  return best;
-}