@elontools/runner 3.1.0

package/README.md

@@ -0,0 +1,444 @@
+# Runner v3 — Node.js/TypeScript Core
+
+Ejecutor de comandos e agente autônomo para Elon Tools. Executa jobs enviados pelo backend e reporta resultados em tempo real.
+
+## 📋 Overview
+
+- **Language:** TypeScript (Node.js)
+- **Runtime:** Node.js 18+
+- **Modes:** `headless` (CLI), `ui` (screen control)
+- **Platforms:** macOS, Linux, Windows
+
+## 🚀 Quick Start
+
+### Local Development
+
+```bash
+# Install dependencies
+npm install
+
+# Compile TypeScript
+npm run build
+
+# Run locally
+npm start -- --server-url=https://elontools.com --pairing-token=PT_xxx
+
+# Or with all flags
+npm start -- \
+  --server-url=https://elontools.com \
+  --pairing-token=PT_xxx \
+  --mode=headless
+```
+
+### macOS App Bundle
+
+O runner v3 é empacotado dentro de `Elon Runner.app` para macOS.
+
+```bash
+# Build for current architecture (arm64 or x86_64)
+bash build-mac.sh
+
+# Build specific architecture
+bash build-mac.sh arm64
+bash build-mac.sh x86_64
+
+# Build universal binary (both architectures)
+bash build-mac-universal.sh
+```
+
+**Resultado:** Binary instalado em `ElonRunner.app/Contents/MacOS/runner-v3`
+
+## 📁 Structure
+
+```
+runner-v3/
+├── src/
+│   └── index.ts              # Main entry point
+├── dist/                     # Compiled JavaScript (generated)
+├── build/                    # Build artifacts (generated)
+│   ├── arm64/
+│   ├── x86_64/
+│   └── runner-v3-universal   # Universal binary (optional)
+├── mac-app/                  # macOS Xcode project
+│   └── ElonRunnerApp/
+│       └── ElonRunnerApp.app/
+│           ├── Contents/
+│           │   ├── MacOS/
+│           │   │   └── runner-v3        # Executable (copied by build script)
+│           │   └── Resources/
+│           │       └── runner-v3/       # Source files
+├── package.json
+├── tsconfig.json
+├── build-mac.sh              # Build script (single arch)
+├── build-mac-universal.sh    # Build script (universal)
+└── README.md                 # This file
+```
+
+## 🔧 Configuration
+
+### Command-Line Arguments
+
+```bash
+runner-v3 \
+  --server-url=https://elontools.com \
+  --pairing-token=PT_xxx \
+  --runner-id=abc123 \
+  --mode=headless
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `--server-url` | Yes | Backend server URL (default: https://elontools.com) |
+| `--pairing-token` | No* | Pairing token (PT_xxx) - required for first registration |
+| `--runner-id` | No | Runner ID (set after registration) |
+| `--mode` | No | `headless` or `ui` (default: headless) |
+| `--config-path` | No | Path to config file (optional) |
+
+*Required on first run for registration
+
+### Environment
+
+```bash
+# Optional: set NODE_BIN for wrapper scripts
+export NODE_BIN=/usr/local/bin/node
+```
+
+## 🔄 Lifecycle
+
+### 1. Registration (First Run)
+
+```
+runner-v3 --server-url=... --pairing-token=PT_xxx
+
+↓ (POST /api/v1/runner-v3/register)
+
+← Response: { runner_id, runner_token }
+
+↓ (stored in config)
+
+✅ Registered
+```
+
+### 2. Heartbeat Loop
+
+```
+Every 30 seconds:
+  POST /api/v1/runner-v3/:id/heartbeat
+  ← { status: "online", uptime: ... }
+```
+
+### 3. Job Polling
+
+```
+Every 5 seconds:
+  GET /api/v1/runner-v3/:id/pull
+  ← { jobs: [...] }
+
+For each job:
+  - Execute command
+  - Capture stdout/stderr
+  - POST /api/v1/runner-v3/:id/report
+```
+
+### 4. Shutdown
+
+```
+Ctrl+C or SIGTERM
+
+→ Graceful shutdown
+  - Stop polling
+  - Send final heartbeat
+  - Exit with code 0
+```
+
+## 📤 API Integration
+
+### Registration
+
+**POST** `/api/v1/runner-v3/register`
+
+```bash
+curl -X POST https://elontools.com/api/v1/runner-v3/register \
+  -H "Authorization: Bearer PT_xxx" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "mode": "headless",
+    "platform": "darwin",
+    "arch": "arm64"
+  }'
+
+# Response:
+{
+  "runner_id": "run_abc123...",
+  "runner_token": "rt3_xyz789..."
+}
+```
+
+### Heartbeat
+
+**POST** `/api/v1/runner-v3/:id/heartbeat`
+
+```bash
+curl -X POST https://elontools.com/api/v1/runner-v3/run_abc123/heartbeat \
+  -H "Authorization: Bearer rt3_xyz789" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "runner_id": "run_abc123",
+    "status": "online",
+    "mode": "headless",
+    "uptime": 3600
+  }'
+```
+
+### Pull Jobs
+
+**GET** `/api/v1/runner-v3/:id/pull`
+
+```bash
+curl https://elontools.com/api/v1/runner-v3/run_abc123/pull \
+  -H "Authorization: Bearer rt3_xyz789"
+
+# Response:
+{
+  "jobs": [
+    {
+      "id": "job_123",
+      "command": "ls",
+      "args": ["-la", "/tmp"]
+    }
+  ]
+}
+```
+
+### Report Job Result
+
+**POST** `/api/v1/runner-v3/:id/report`
+
+```bash
+curl -X POST https://elontools.com/api/v1/runner-v3/run_abc123/report \
+  -H "Authorization: Bearer rt3_xyz789" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "job_id": "job_123",
+    "status": "completed",
+    "output": "total 0\ndrwxr-xr-x  ...",
+    "error": null
+  }'
+```
+
+## 📊 Logging
+
+Logs are printed to stdout/stderr with timestamps:
+
+```
+[2026-02-18T10:30:00.000Z] ℹ️  Runner v3 iniciado
+[2026-02-18T10:30:01.234Z] 📝 Registrando runner com API...
+[2026-02-18T10:30:02.456Z] ✅ Runner registrado
+[2026-02-18T10:30:05.789Z] 💓 Heartbeat enviado
+[2026-02-18T10:30:10.234Z] 🚀 Executando job
+[2026-02-18T10:30:15.678Z] 📤 Job result reportado
+```
+
+### Log Prefixes
+
+| Prefix | Meaning |
+|--------|---------|
+| ℹ️ | Info message |
+| ✅ | Success |
+| ⚠️ | Warning |
+| ❌ | Error |
+| 💓 | Heartbeat |
+| 🚀 | Job execution |
+| 📝 | API call (register) |
+| 📤 | Report result |
+
+## 🏗️ macOS Build Process
+
+### Step 1: TypeScript Compilation
+
+```bash
+npm run build
+# Creates: dist/index.js + source maps
+```
+
+### Step 2: Create Wrapper
+
+Wrapper script that:
+- Finds Node.js binary
+- Executes dist/index.js with all arguments
+- Handles errors gracefully
+
+### Step 3: Create Binary
+
+Combines wrapper + runner files into single executable:
+- `build/arm64/runner-v3` (arm64 only)
+- `build/x86_64/runner-v3` (x86_64 only)
+- `build/runner-v3-universal` (both, via lipo)
+
+### Step 4: Copy to App Bundle
+
+```
+ElonRunnerApp.app/
+├── Contents/
+│   ├── MacOS/
+│   │   └── runner-v3 ← Binary installed here
+│   └── Resources/
+│       └── runner-v3/ ← Source files for reference
+```
+
+## 🔍 Debugging
+
+### Run with detailed logging
+
+```bash
+# Set Node.js debug flag
+DEBUG=* npm start -- --server-url=... --pairing-token=...
+
+# Or redirect to file
+npm start -- ... 2>&1 | tee runner.log
+```
+
+### Test binary directly
+
+```bash
+# From macOS app:
+./ElonRunnerApp.app/Contents/MacOS/runner-v3 \
+  --server-url=https://elontools.com \
+  --pairing-token=PT_test_xxx
+
+# Expected output:
+# [timestamp] ℹ️  Runner v3 iniciado
+# [timestamp] 📝 Registrando runner com API...
+# [timestamp] ✅ Runner registrado
+```
+
+### Monitor heartbeat (macOS log)
+
+```bash
+# From app bundle logs
+tail -f ~/Library/Logs/ElonRunner/stdout.log
+```
+
+## 🚨 Common Issues
+
+### "Node.js not found in PATH"
+
+**Solution:** Install Node.js via Homebrew
+
+```bash
+brew install node
+```
+
+Or set `NODE_BIN` environment variable:
+
+```bash
+export NODE_BIN=/usr/local/bin/node
+./runner-v3 --server-url=...
+```
+
+### "Binary not found in app bundle"
+
+**Solution:** Run build script
+
+```bash
+bash build-mac.sh
+```
+
+### "Permission denied"
+
+**Solution:** Make binary executable
+
+```bash
+chmod +x ElonRunnerApp.app/Contents/MacOS/runner-v3
+```
+
+## 🎯 Development Workflow
+
+### 1. Make changes to `src/index.ts`
+
+```bash
+# Auto-compile on save
+npm run dev
+```
+
+### 2. Test locally
+
+```bash
+npm start -- --server-url=... --pairing-token=... --mode=headless
+```
+
+### 3. Build for macOS app
+
+```bash
+bash build-mac.sh
+```
+
+### 4. Test in app (Xcode)
+
+```bash
+# Open Xcode project
+open mac-app/ElonRunnerApp/ElonRunnerApp.xcodeproj
+
+# Cmd+R to build & run
+```
+
+## 📦 Distribution
+
+### macOS App (.app)
+
+```bash
+# Build universal binary
+bash build-mac-universal.sh
+
+# Copy app to /Applications
+cp -r ElonRunnerApp.app /Applications/
+
+# Run
+/Applications/ElonRunnerApp.app/Contents/MacOS/Elon\ Runner
+```
+
+### Standalone Binary
+
+```bash
+# Build universal
+bash build-mac-universal.sh
+
+# Copy to PATH
+cp build/runner-v3-universal /usr/local/bin/runner-v3
+chmod +x /usr/local/bin/runner-v3
+
+# Run
+runner-v3 --server-url=...
+```
+
+## 🔐 Security
+
+- ✅ **Token Hashing:** Pairing tokens are hashed (SHA-256) server-side
+- ✅ **Bearer Auth:** Runner tokens are Bearer tokens (not exposed in logs)
+- ✅ **HTTPS only:** All API calls use HTTPS
+- ✅ **Process Isolation:** Each job runs in isolated process
+- ✅ **No Plaintext Storage:** Tokens removed from disk after registration
+
+## 📚 References
+
+- Backend: `apps/api/src/services/runner-v3.service.ts`
+- API: `apps/api/src/routes/runner-v3.handler.ts`
+- macOS App: `runner-v3/mac-app/ElonRunnerApp/`
+
+## 🤝 Contributing
+
+1. Make changes to `src/`
+2. Test locally (`npm run dev` + `npm start`)
+3. Build for macOS (`bash build-mac.sh`)
+4. Test in app (Xcode)
+5. Commit & push
+
+## 📄 License
+
+Copyright © 2026 ElonTools. All rights reserved.
+
+---
+
+**Last Updated:** 2026-02-18  
+**Version:** 3.0.0  
+**Status:** MVP (ready for macOS app integration)

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Runner v3 - Core Entry Point (Node.js/TypeScript)
+ * Executa comandos enviados pelo backend via API
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG"}