kPong

Portable latency monitor TUI built with Bun + Ink.

Codebase Summary

• src/main.tsx: Ink entrypoint.
• src/ui/views/App.tsx: stateful controller for setup, config reloads, theme reloads, scheduler lifecycle, and keyboard modes.
• src/ui/views/MainView.tsx: terminal layout composition.
• src/ui/components/: reusable cards, table, settings, feedback, and layout primitives.
• src/core/: config I/O, ping execution, scheduling, alerts, notifications, exports, and theme file loading.
• tests/: Bun unit coverage for config, alerts, scheduler, ping parsing, exports, notifications, and theme loading.
• config/kpong.yaml: reference config template.
• example/themes/: sample theme files for ui.themeFile.
• vendor/react-devtools-core-shim/: optional Ink peer shim kept out of app source analysis.

The current architecture is straightforward: App loads config, starts SchedulerService, folds samples into TargetState, evaluates spikes through AlertService, and renders the composed TUI with theme-driven presentation.

Commands

bun install
bun run dev
bun run check     # typecheck + lint + format check + knip + tests
bun run format    # apply formatting
bun run lint:fix  # apply lint autofixes
bun run audit
bun run build

bun run build compiles for the host platform; on Windows the output is dist/kpong.exe. Building overwrites its own output and deletes nothing else. A binary keeps its kpong.yaml, database and exports/ in its own directory, and storage.sqlite.path and ui.themeFile can name any file there, so no cleanup step can tell build output from live data by name. Remove old binaries yourself if you want a tidy dist/.

Cross-platform builds:

bun run build:windows-x64
bun run build:linux-x64
bun run build:linux-arm64
bun run build:macos-x64
bun run build:macos-arm64
bun run build:all

build:windows-x64-icon produces the same Windows binary with .images/kpong.ico embedded. It is separate because Bun's Windows metadata flags depend on Windows APIs and are rejected when cross-compiling, so it only works on a Windows host — build:all uses the icon-free build to stay portable.

bun run check runs the full gate in one command.

Runtime Behavior

• First launch opens a setup wizard and writes a runtime kpong.yaml in the app directory.
• r reloads config from disk.
• ui.themeFile can point to a YAML theme file, which is watched and auto-reloaded.
• Snapshot exports write CSV and JSON files to the configured export directory.

Keyboard controls:

• Up/Down or j/k: select target
• a: add target
• e: edit selected target host
• n: rename selected target
• d: remove selected target
• t: enable or disable selected target
• m: mute or unmute selected target alerts
• x: export snapshot
• r: reload YAML config
• s: open settings
• ?: toggle help
• q or Esc: quit

Settings controls:

• Up/Down or j/k: move field
• Enter: edit or toggle
• Left/Right: cycle enum values
• Space: toggle booleans
• w: save
• Esc or s: close or discard

Config And Themes

Use config/kpong.yaml as the source template. Theme examples live in example/themes/README.md.

Custom notification sound:

defaults:
  notifications:
    sound: true
    soundFile: "C:/path/to/sound.wav"

Theme snippet:

ui:
  themeFile: ./example/themes/ocean-contrast.yaml

Repo Hygiene

• dist/, exports/, and the repo-root runtime kpong.yaml are generated artifacts and should not be committed.
• knip is installed for unused file/export checks.
• The vendored react-devtools-core shim is intentional. Ink imports the package unconditionally from its devtools module, and bun build --compile statically follows that import, so without the shim the compile fails with Could not resolve "react-devtools-core" — and with the real package, every standalone binary would carry it. Ink only calls into it when DEV=true.