fix(waybar): omit alt/percentage sem dados + clamp 100

Author: othavi0

docs/waybar-contract.md

@@ -132,11 +132,13 @@ and adds provider-scoped classes such as `claude-ok`, `codex-warn`, or
 Single-provider modules (`--provider <id>`) emit, in addition to `text`,
 `tooltip`, and `class`:
 
-- `alt` — the health state (`ok` / `low` / `warn` / `critical` / `disconnected`),
-  for `format-icons` keyed by state.
+- `alt` — the health state (`ok` / `low` / `warn` / `critical`), or
+  `disconnected`, for `format-icons` keyed by state. **Omitted** when the
+  provider is available but has no quota data (so a missing window never reports
+  `ok`).
 - `percentage` — the displayMode-aware quota value (the same number shown in
-  `text`), for `{percentage}` in `format` or `format-icons` arrays. **Omitted**
-  when there is no data or the provider is disconnected.
+  `text`), clamped to `0..100`, for `{percentage}` in `format` or `format-icons`
+  arrays. **Omitted** when there is no data or the provider is disconnected.
 
 The aggregate module (no `--provider`) does **not** emit `alt`/`percentage`.
 

src/formatters/waybar.ts

@@ -1,5 +1,5 @@
 import { APP_BASE_CLASS } from '../app-identity';
-import { getStatusForPercent } from '../config';
+import { getStatusForPercent, type HealthStatus } from '../config';
 import type { AllQuotas, ProviderQuota } from '../providers/types';
 import { type DisplayMode, loadSettingsSync } from '../settings';
 import { ONE_DARK } from '../theme';
@@ -59,9 +59,9 @@ interface WaybarOutput {
   text: string;
   tooltip: string;
   class: string;
-  /** Health state for `format-icons` (single-provider only): ok/low/warn/critical/disconnected. */
-  alt?: string;
-  /** displayMode-aware quota value (single-provider only), omitted when no data. */
+  /** Health state for `format-icons` (single-provider only). Omitted when available but no data. */
+  alt?: HealthStatus | 'disconnected';
+  /** displayMode-aware quota value (single-provider only), clamped 0..100, omitted when no data. */
   percentage?: number;
 }
 
@@ -229,7 +229,8 @@ export function formatProviderForWaybar(quota: ProviderQuota, mode: DisplayMode
     text: pctColored(disp, mode),
     tooltip: buildProviderTooltip(quota, undefined, mode),
     class: `${APP_BASE_CLASS}-${quota.provider} ${status}`,
-    alt: status,
-    ...(disp !== null ? { percentage: Math.round(disp) } : {}),
+    // alt/percentage only when there is real data: a missing window must not
+    // report 'ok' (class keeps its pre-existing fallback for CSS).
+    ...(disp !== null ? { alt: status, percentage: Math.min(100, Math.round(disp)) } : {}),
   };
 }

src/waybar-contract.ts

@@ -73,7 +73,7 @@ function copyDir(src: string, dest: string): void {
   }
 }
 
-interface WaybarModuleConfig {
+export interface WaybarModuleConfig {
   exec: string;
   'return-type': 'json';
   interval: number;

tests/formatters.test.ts

@@ -251,6 +251,24 @@ describe('formatProviderForWaybar', () => {
     expect('alt' in result).toBe(false);
     expect('percentage' in result).toBe(false);
   });
+
+  it('omits alt and percentage when available but has no window data', () => {
+    const quota: ProviderQuota = { provider: 'claude', displayName: 'Claude', available: true } as ProviderQuota;
+    const out = formatProviderForWaybar(quota);
+    expect('alt' in out).toBe(false);
+    expect('percentage' in out).toBe(false);
+  });
+
+  it('clamps percentage to 100 on overage (used > 100)', () => {
+    const quota: ProviderQuota = {
+      provider: 'codex',
+      displayName: 'Codex',
+      available: true,
+      primary: { remaining: -7, used: 107, resetsAt: null },
+    } as ProviderQuota;
+    const out = formatProviderForWaybar(quota, 'used');
+    expect(out.percentage).toBe(100);
+  });
 });
 
 describe('formatForTerminal displayMode=used', () => {

tests/settings.test.ts

@@ -142,22 +142,22 @@ describe('settings', () => {
       expect(s.waybar.signal).toBeUndefined();
     });
 
-    it('preserves a valid signal (1..30)', async () => {
+    it('preserves valid signals at the range boundaries (1, 8, 30)', async () => {
       const settingsDir = join(testRoot, 'agent-bar');
       await mkdir(settingsDir, { recursive: true });
-      await writeFile(
-        join(settingsDir, 'settings.json'),
-        JSON.stringify({ version: 2, waybar: { providers: ['claude'], signal: 8 } }),
-      );
-      const s = await loadSettings();
-      expect(s.waybar.signal).toBe(8);
+      const settingsFile = join(settingsDir, 'settings.json');
+      for (const ok of [1, 8, 30]) {
+        await writeFile(settingsFile, JSON.stringify({ version: 2, waybar: { providers: ['claude'], signal: ok } }));
+        const s = await loadSettings();
+        expect(s.waybar.signal).toBe(ok);
+      }
     });
 
-    it('drops an invalid signal (0, negative, non-integer, out of range, wrong type)', async () => {
+    it('drops an invalid signal (0, negative, non-integer, above range, wrong type)', async () => {
       const settingsDir = join(testRoot, 'agent-bar');
       await mkdir(settingsDir, { recursive: true });
       const settingsFile = join(settingsDir, 'settings.json');
-      for (const bad of [0, -1, 3.5, 99, 'x']) {
+      for (const bad of [0, -1, 3.5, 31, 99, 'x']) {
         await writeFile(settingsFile, JSON.stringify({ version: 2, waybar: { providers: ['claude'], signal: bad } }));
         const s = await loadSettings();
         expect(s.waybar.signal).toBeUndefined();