salvetron 0.1.0

package/README.md

@@ -0,0 +1,333 @@
+<p align="center">
+  <img src="assets/banner.png" alt="Salvetron Logo" width="1280" height="720" style="border-radius: 20px;">
+</p>
+
+<h1 align="center">Salvetron</h1>
+
+<p align="center">
+  <strong>Real-time terminal UI debugger for React Native</strong>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/React%20Native-0.73+-61dafb?style=flat-square&logo=react" alt="React Native">
+  <img src="https://img.shields.io/badge/runtime-Node%2018+-339933?style=flat-square&logo=node.js" alt="Node">
+  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License">
+</p>
+
+---
+
+Salvetron is a real-time debugging tool for React Native developers, delivered as a terminal UI (TUI). The Salvetron CLI runs a WebSocket server in your terminal and renders incoming telemetry — JS logs, native logs, network traffic, and live performance metrics — from your running app. Your app streams that telemetry using the companion SDK, `@salve-software/salvetron-react-native`.
+
+## Features
+
+- **Dashboard** - Live performance overview: UI/JS FPS, memory and CPU usage, with sparkline history
+- **JS Logs** - Stream JavaScript console logs with level filtering (debug, info, warn, error) and an expandable detail panel for metadata
+- **Network Inspector** - Inspect HTTP requests and responses: method, status, duration, headers, and pretty-printed bodies
+- **Native Logs** - View iOS and Android platform logs in real-time, with source tags
+- **Keyboard-driven TUI** - Navigate panels and lists entirely from the keyboard; no GUI required
+- **Zero-config WebSocket server** - Starts on port 8765 by default (override with `SALVETRON_PORT`)
+
+## Screenshots
+
+<!-- Add your screenshots here -->
+
+<p align="center">
+  <em>Screenshots coming soon...</em>
+</p>
+
+<!--
+Example:
+<p align="center">
+  <img src="assets/screenshots/main-view.png" alt="Main View" width="800">
+</p>
+-->
+
+## Architecture
+
+Salvetron has two parts:
+
+```
+┌──────────────────────────┐        WebSocket          ┌──────────────────────────┐
+│     React Native App      │ ───────────────────────▶ │       Salvetron CLI      │
+│ @salve-software/          │        port 8765          │  (terminal UI debugger)  │
+│   salvetron-react-native  │                           │                          │
+└──────────────────────────┘                            └──────────────────────────┘
+         │                                                        │
+         ├── JS Console Logs                                      ├── Dashboard (FPS/CPU/memory)
+         ├── Native Logs (iOS/Android)                            ├── JS Logs viewer
+         ├── Network Requests/Responses                           ├── Network Inspector
+         └── Performance Metrics                                  └── Native Logs viewer
+```
+
+1. **Salvetron CLI** (`salvetron`): an Ink-based terminal UI that runs a WebSocket server and renders telemetry from connected apps.
+
+2. **salvetron-react-native** (SDK): A React Native package built with Nitro Modules that captures logs, network activity, and performance metrics and streams them to the CLI.
+
+## Installation
+
+### Requirements
+
+| Component | Requirement |
+|-----------|-------------|
+| Salvetron CLI | Node.js 18+ |
+| React Native SDK | React Native 0.73+ |
+| Xcode | 15+ (for iOS development) |
+| Android Studio | Latest (for Android development) |
+
+### Running the Salvetron CLI
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/Salve-Software/salvetron.git
+   cd salvetron
+   yarn install
+   ```
+
+2. Start the CLI:
+   ```bash
+   yarn dev          # starts the Salvetron CLI (Ink TUI) on port 8765
+   ```
+
+   Or, once published:
+   ```bash
+   npx salvetron
+   ```
+
+   Override the port with the `SALVETRON_PORT` environment variable:
+   ```bash
+   SALVETRON_PORT=9000 yarn dev
+   ```
+
+### Installing React Native SDK
+
+1. Install the package in your React Native project:
+
+   ```bash
+   # Using npm
+   npm install @salve-software/salvetron-react-native
+
+   # Using yarn
+   yarn add @salve-software/salvetron-react-native
+   ```
+
+2. For iOS, install pods:
+   ```bash
+   cd ios && pod install && cd ..
+   ```
+
+3. For Android, the package will auto-link. Run a gradle sync if needed.
+
+## Usage
+
+### Starting the Salvetron CLI
+
+Run `yarn dev` (or `npx salvetron`) in your terminal. The CLI starts a WebSocket server on port **8765** and shows the Dashboard. Use the tab bar / keyboard shortcuts shown in the status bar to switch between Dashboard, JS Logs, Network, and Native Logs. Connected device info appears in the header once your app connects.
+
+### Connecting from React Native
+
+Add the following code to your React Native app's entry point (e.g., `App.tsx` or `index.js`):
+
+```typescript
+import Salvetron from '@salve-software/salvetron-react-native';
+
+// Connect only in development mode
+if (__DEV__) {
+  Salvetron.connect({
+    host: '192.168.1.100', // Your Mac's IP address
+    port: 8765,
+    enableNetworkCapture: true,
+    onConnect: () => console.log('Connected to Salvetron!'),
+    onDisconnect: () => console.log('Disconnected from Salvetron'),
+    onError: (error) => console.error('Salvetron error:', error),
+  });
+}
+```
+
+> **Tip**: Use `localhost` when running on iOS Simulator, or your Mac's local IP address for physical devices.
+
+### API Reference
+
+#### `Salvetron.connect(config?)`
+
+Establishes a WebSocket connection to the Salvetron CLI.
+
+```typescript
+interface SalvetronConfig {
+  host?: string;              // Default: 'localhost'
+  port?: number;              // Default: 8765
+  enableNetworkCapture?: boolean;  // Default: true
+  ignoredUrls?: RegExp[];     // URL patterns to ignore
+  onConnect?: () => void;
+  onDisconnect?: () => void;
+  onError?: (error: Error) => void;
+}
+```
+
+#### `Salvetron.disconnect()`
+
+Closes the WebSocket connection.
+
+```typescript
+Salvetron.disconnect();
+```
+
+#### `Salvetron.isConnected()`
+
+Returns the current connection status.
+
+```typescript
+const connected = Salvetron.isConnected(); // boolean
+```
+
+#### Logging Methods
+
+```typescript
+// Send logs with different levels
+Salvetron.log('General log message');
+Salvetron.debug('Debug information', { userId: 123 });
+Salvetron.info('Informational message');
+Salvetron.warn('Warning message');
+Salvetron.error('Error message', { stack: error.stack });
+```
+
+All logging methods accept an optional metadata object as the second parameter.
+
+## Troubleshooting
+
+### Connection Issues
+
+**Problem**: App can't connect to the Salvetron CLI
+
+**Solutions**:
+1. Ensure the Salvetron CLI is running (`yarn dev` / `npx salvetron`)
+2. Check that both devices are on the same network
+3. Verify the IP address is correct (use `ifconfig` to find your machine's IP)
+4. Check if port 8765 is not blocked by firewall
+5. For iOS Simulator, use `localhost` instead of IP address
+
+### Network Requests Not Showing
+
+**Problem**: HTTP requests are not appearing in the Network tab
+
+**Solutions**:
+1. Ensure `enableNetworkCapture: true` is set in the config
+2. Check if the URL isn't in the `ignoredUrls` list
+3. Default ignored URLs include Metro bundler (port 8081) and hot reload endpoints
+
+### Logs Not Appearing
+
+**Problem**: Console logs are not showing in the Salvetron CLI
+
+**Solutions**:
+1. Verify the connection is established (`Salvetron.isConnected()`)
+2. Ensure you're running in development mode (`__DEV__ === true`)
+3. Confirm the CLI shows your device in the header
+
+### High Memory Usage
+
+**Problem**: The Salvetron CLI process using too much memory
+
+**Solutions**:
+1. Clear logs periodically from the JS Logs / Native Logs panels
+2. Reduce the number of connected devices
+3. Filter out verbose logs at the source
+
+## Contributing
+
+We welcome contributions! Here's how you can help:
+
+### Getting Started
+
+1. Fork the repository
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/your-username/salvetron.git
+   ```
+3. Create a new branch:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+### Branch Naming Convention
+
+- `feature/` - New features
+- `fix/` - Bug fixes
+- `docs/` - Documentation updates
+- `refactor/` - Code refactoring
+- `test/` - Adding or updating tests
+
+### Commit Message Format
+
+Follow conventional commits:
+```
+type(scope): description
+
+Examples:
+feat(sdk): add custom log levels support
+fix(app): resolve memory leak in log viewer
+docs(readme): update installation instructions
+```
+
+### Pull Request Process
+
+1. Ensure your code follows the existing style
+2. Update documentation if needed
+3. Test your changes thoroughly:
+   - For Salvetron CLI: run `yarn dev` and verify with the simulator (`yarn sim`)
+   - For SDK: Test with the example app
+4. Create a Pull Request with a clear description
+
+### Code Style Guidelines
+
+**salvetron (CLI, TypeScript / Ink)**:
+- Use TypeScript for all source files
+- Keep modules organized under `src/modules/<feature>` and shared UI under `src/shared`
+- Run `yarn typecheck` before opening a PR
+
+**salvetron-react-native (SDK, TypeScript)**:
+- Use TypeScript for all source files
+- Follow existing patterns in the codebase
+- Document public APIs with JSDoc comments
+
+### Running the Example App
+
+```bash
+cd packages/salvetron-react-native/example
+yarn install
+cd ios && pod install && cd ..
+yarn ios  # or yarn android
+```
+
+## License
+
+This project is licensed under the MIT License - see below for details:
+
+```
+MIT License
+
+Copyright (c) 2024 Salvetron Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+---
+
+<p align="center">
+  Made by Salve Software
+</p>

package/bin/salvetron.tsx

@@ -0,0 +1,9 @@
+#!/usr/bin/env -S tsx
+import { render } from 'ink'
+import { App } from '../src/app.js'
+import { startWsServer } from '../src/server/ws-server.js'
+
+const PORT = Number(process.env.SALVETRON_PORT ?? 8765)
+
+startWsServer(PORT)
+render(<App />, { patchConsole: false })

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "salvetron",
+  "description": "Terminal UI debugger for React Native",
+  "version": "0.1.0",
+  "type": "module",
+  "packageManager": "yarn@4.9.1",
+  "workspaces": [
+    "packages/salvetron-types"
+  ],
+  "bin": "./bin/salvetron.tsx",
+  "files": [
+    "bin",
+    "src",
+    "scripts"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "dev": "tsx bin/salvetron.tsx",
+    "start": "tsx bin/salvetron.tsx",
+    "sim": "node scripts/salvetron-sim.mjs",
+    "typecheck": "yarn build && tsc --noEmit",
+    "build": "yarn workspace @salve-software/salvetron-types build",
+    "test": "yarn workspaces foreach -Apt run test"
+  },
+  "dependencies": {
+    "@salve-software/salvetron-types": "^1.0.0",
+    "figlet": "^1.11.0",
+    "ink": "^7.0.6",
+    "json-colorizer": "^3.0.1",
+    "react": "^19.1.0",
+    "ws": "^8.18.0",
+    "zustand": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/figlet": "^1.7.0",
+    "@types/react": "^19.0.0",
+    "@types/ws": "^8.5.0",
+    "tsx": "^4.0.0",
+    "typescript": "~5.8.3"
+  }
+}

package/scripts/salvetron-sim.mjs

@@ -0,0 +1,75 @@
+import WebSocket from 'ws'
+
+const PORT = Number(process.env.SALVETRON_PORT ?? 8765)
+const ws = new WebSocket(`ws://localhost:${PORT}`)
+
+ws.on('open', () => {
+  const send = (e) => ws.send(JSON.stringify(e))
+
+  send({ type: 'device_info', deviceName: 'iPhone 15 Sim', platform: 'ios' })
+
+  for (let i = 0; i < 12; i++) {
+    send({
+      type: 'log',
+      timestamp: Date.now(),
+      level: ['info', 'warn', 'error', 'debug', 'log'][i % 5],
+      source: 'js',
+      message: `JS log message number ${i} - something happened in the app that produced a fairly long message to test truncation`,
+      metadata: { index: i, nested: { a: 1, b: 'test' } },
+    })
+  }
+
+  for (let i = 0; i < 8; i++) {
+    const requestId = `req-${i}`
+    send({
+      type: 'network',
+      stage: 'request',
+      timestamp: Date.now(),
+      requestId,
+      method: ['GET', 'POST', 'PUT', 'DELETE'][i % 4],
+      url: `https://api.example.com/v1/resource/${i}?foo=bar&long=query-param-to-test-truncation`,
+      headers: { 'Content-Type': 'application/json' },
+      body: i % 2 === 0 ? JSON.stringify({ hello: 'world' }) : undefined,
+    })
+    send({
+      type: 'network',
+      stage: 'response',
+      timestamp: Date.now(),
+      requestId,
+      method: ['GET', 'POST', 'PUT', 'DELETE'][i % 4],
+      url: `https://api.example.com/v1/resource/${i}`,
+      statusCode: [200, 201, 404, 500][i % 4],
+      duration: 50 + i * 10,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ result: 'ok', index: i, items: [1, 2, 3] }),
+    })
+  }
+
+  for (let i = 0; i < 10; i++) {
+    send({
+      type: 'native',
+      timestamp: Date.now(),
+      level: ['info', 'warn', 'error'][i % 3],
+      source: i % 2 === 0 ? 'ios' : 'android',
+      tag: 'AppLifecycle',
+      message: `Native event ${i} fired with some descriptive text to check wrapping behavior in the panel`,
+      metadata: { i },
+    })
+  }
+
+  let tick = 0
+  const perfInterval = setInterval(() => {
+    tick++
+    send({
+      type: 'performance_metrics',
+      timestamp: Date.now(),
+      uiFps: 55 + Math.round(Math.sin(tick) * 4),
+      jsFps: 50 + Math.round(Math.cos(tick) * 5),
+      memoryUsage: 180 + tick * 3,
+      cpuUsage: 20 + (tick % 30),
+    })
+    if (tick > 30) clearInterval(perfInterval)
+  }, 200)
+})
+
+ws.on('error', (e) => console.error('ws error', e))

package/src/app.tsx

@@ -0,0 +1,62 @@
+import { Box, useInput } from 'ink'
+import { useMemo, useState } from 'react'
+import { AsciiLogo, pickRandomColor } from './shared/components/ascii-logo/index.js'
+import { TabBar } from './shared/components/tab-bar/index.js'
+import { StatusBar } from './shared/components/status-bar/index.js'
+import { useProject } from './shared/store/device.store.js'
+import { DashboardContainer } from './modules/dashboard/ui/containers/dashboard-container/index.js'
+import { JsLogsContainer } from './modules/js-logs/ui/containers/js-logs-container/index.js'
+import { NetworkContainer } from './modules/network/ui/containers/network-container/index.js'
+import { NativeLogsContainer } from './modules/native-logs/ui/containers/native-logs-container/index.js'
+
+export type Tab = 'dashboard' | 'js-logs' | 'network' | 'native'
+
+const TABS: Tab[] = ['dashboard', 'js-logs', 'network', 'native']
+const DEFAULT_LOGO_COLOR = '#61DAFB'
+
+export function App() {
+  const [activeTab, setActiveTab] = useState<Tab>('dashboard')
+  const appName = useProject()?.appName
+
+  const logoColor = useMemo(
+    () => (appName ? pickRandomColor() : DEFAULT_LOGO_COLOR),
+    [appName],
+  )
+
+  useInput((input, key) => {
+    if (input === '1') setActiveTab('dashboard')
+    if (input === '2') setActiveTab('js-logs')
+    if (input === '3') setActiveTab('network')
+    if (input === '4') setActiveTab('native')
+    if (key.tab) {
+      const i = TABS.indexOf(activeTab)
+      setActiveTab(TABS[(i + 1) % TABS.length])
+    }
+  })
+
+  return (
+    <Box flexDirection="column" height="100%" paddingTop={1}>
+      <AsciiLogo text={appName} color={logoColor} />
+      <TabBar active={activeTab} />
+      <Box flexGrow={1} flexDirection="column" paddingX={1}>
+        {activeTab === 'dashboard'
+          ? <DashboardContainer />
+          : null
+        }
+        {activeTab === 'js-logs'
+          ? <JsLogsContainer />
+          : null
+        }
+        {activeTab === 'network'
+          ? <NetworkContainer />
+          : null
+        }
+        {activeTab === 'native'
+          ? <NativeLogsContainer />
+          : null
+        }
+      </Box>
+      <StatusBar />
+    </Box>
+  )
+}

package/src/modules/dashboard/store/dashboard.store.ts

@@ -0,0 +1,19 @@
+import { create } from 'zustand'
+import type { PerformanceMetricsEvent } from '@salve-software/salvetron-types'
+
+interface DashboardStore {
+  snapshots: PerformanceMetricsEvent[]
+  addSnapshot: (snapshot: PerformanceMetricsEvent) => void
+}
+
+const MAX = 60
+
+export const useDashboardStore = create<DashboardStore>((set) => ({
+  snapshots: [],
+  addSnapshot: (snapshot) =>
+    set((s) => ({ snapshots: [...s.snapshots, snapshot].slice(-MAX) })),
+}))
+
+export const useDashboardSnapshots = () => useDashboardStore((s) => s.snapshots)
+export const useLatestSnapshot = () =>
+  useDashboardStore((s) => s.snapshots[s.snapshots.length - 1] ?? null)

package/src/modules/dashboard/ui/components/metric-row/index.ts

@@ -0,0 +1 @@
+export { MetricRow } from './metric-row'

package/src/modules/dashboard/ui/components/metric-row/metric-row.tsx

@@ -0,0 +1,25 @@
+import { Box, Text } from 'ink'
+import { Gauge } from '../../../../../shared/components/gauge/index.js'
+import { Sparkline } from '../../../../../shared/components/sparkline/index.js'
+
+interface MetricRowProps {
+  label: string
+  value: number
+  max: number
+  unit: string
+  values: number[]
+  sparkWidth: number
+  warnAt?: number
+  critAt?: number
+}
+
+export function MetricRow({ label, value, max, unit, values, sparkWidth, warnAt, critAt }: MetricRowProps) {
+  return (
+    <Box gap={1}>
+      <Text color="gray">{label}</Text>
+      <Gauge value={value} max={max} width={12} warnAt={warnAt} critAt={critAt} />
+      <Sparkline values={values} max={max} width={sparkWidth} />
+      <Text>{String(Math.round(value)).padStart(4)}{unit}</Text>
+    </Box>
+  )
+}

package/src/modules/dashboard/ui/components/performance-panel/index.ts

@@ -0,0 +1 @@
+export { PerformancePanel } from './performance-panel'

package/src/modules/dashboard/ui/components/performance-panel/performance-panel.tsx

@@ -0,0 +1,67 @@
+import { Text } from "ink";
+import type { PerformanceMetricsEvent } from "@salve-software/salvetron-types";
+import { Panel } from "../../../../../shared/components/panel/index.js";
+import { MetricRow } from "../metric-row/index.js";
+
+interface PerformancePanelProps {
+  latest: PerformanceMetricsEvent | null;
+  snapshots: PerformanceMetricsEvent[];
+  sparkWidth: number;
+  height: number;
+}
+
+export function PerformancePanel({
+  latest,
+  snapshots,
+  sparkWidth,
+  height,
+}: PerformancePanelProps) {
+  return (
+    <Panel title="Performance" height={height}>
+      {latest ? (
+        <>
+          <MetricRow
+            label="UI FPS"
+            value={latest.uiFps}
+            max={60}
+            unit="fps"
+            values={snapshots.map((s) => s.uiFps)}
+            sparkWidth={sparkWidth}
+          />
+          <MetricRow
+            label="JS FPS"
+            value={latest.jsFps}
+            max={60}
+            unit="fps"
+            values={snapshots.map((s) => s.jsFps)}
+            sparkWidth={sparkWidth}
+          />
+          <MetricRow
+            label="RAM   "
+            value={latest.memoryUsage}
+            max={512}
+            unit="MB"
+            values={snapshots.map((s) => s.memoryUsage)}
+            sparkWidth={sparkWidth}
+            warnAt={0.6}
+            critAt={0.85}
+          />
+          <MetricRow
+            label="CPU   "
+            value={latest.cpuUsage}
+            max={100}
+            unit="%"
+            values={snapshots.map((s) => s.cpuUsage)}
+            sparkWidth={sparkWidth}
+            warnAt={0.6}
+            critAt={0.8}
+          />
+        </>
+      ) : (
+        <Text color="gray" dimColor>
+          Waiting for performance data...
+        </Text>
+      )}
+    </Panel>
+  );
+}