tapflow 0.0.1 → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tapflow 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.

package/README.md

@@ -0,0 +1,192 @@
+<div align="center">
+  <img src="docs/public/logo-hero.svg" height="72" alt="tapflow" />
+
+  <h3>Self-hosted iOS & Android simulator streaming for QA teams</h3>
+
+  <p>
+    Run simulators in the browser — no Appetize, no BrowserStack, no monthly fees.<br />
+    App data never leaves your network.
+  </p>
+
+  <p>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License" /></a>
+    <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node.js ≥ 20" /></a>
+    <img src="https://img.shields.io/badge/platform-macOS-lightgrey" alt="macOS Agent" />
+    <a href="https://github.com/jo-duchan/tapflow/blob/main/CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs welcome" /></a>
+  </p>
+</div>
+
+---
+
+## Demo
+
+<!--
+  Demo video placeholder.
+  When the recording is ready, replace this block with:
+
+  [![tapflow demo](docs/public/demo-thumbnail.png)](https://YOUR_VIDEO_URL)
+
+  Recommended thumbnail size: 1280×720, saved to docs/public/demo-thumbnail.png
+-->
+
+<div align="center">
+  <strong>🎬 Demo video coming soon</strong>
+</div>
+
+---
+
+## Why tapflow?
+
+| Solution | Problem |
+|----------|---------|
+| Appetize / BrowserStack | Expensive — app data leaves your network |
+| Physical devices | Cost, loss, management overhead |
+| Xcode / Android Studio | Every QA member needs their own Mac + full toolchain setup |
+| **tapflow** | Use the Mac you already own — data stays on-prem, QA team uses a browser |
+
+## Features
+
+- **Browser-based** — QA team needs no installation. Any modern browser works.
+- **iOS Simulator** — JPEG frame streaming at ~30 fps via SimulatorKit IOSurface. No WebDriverAgent required.
+- **Android Emulator** — H.264 streaming via [scrcpy](https://github.com/Genymobile/scrcpy) at ~30 fps.
+- **Touch, swipe & pinch** — real-time input forwarded to the simulator.
+- **App Center** — upload `.app.zip` (iOS) or `.apk` (Android), manage builds by status (Backlog / In Progress / Done / Rejected).
+- **Session Recordings** — record QA sessions, share with your team. Retained for 72 hours.
+- **Mac Resources** — CPU & RAM monitoring per agent. Spot overloaded hosts before assigning sessions.
+- **Team management** — invite links, roles (Admin / Developer / QA / Viewer), Personal Access Tokens for CI/CD.
+- **Self-hosted** — deploy anywhere. No cloud dependency.
+
+## How it works
+
+```
+Browser (QA team)  ←—WebSocket—→  Relay Server  ←—WebSocket (outbound)—→  Mac Agent
+                                  (Linux / Mac)                           (iOS · Android)
+```
+
+1. The **Mac Agent** connects *outbound* to the relay — no inbound firewall rules needed.
+2. QA opens the **dashboard** in any browser and sees all available devices.
+3. Touch events are forwarded in real time; the screen streams back to the browser.
+4. The **relay** also serves the dashboard SPA on the same port — no separate web server needed.
+
+## Quick Start
+
+### 1. Install
+
+```sh
+npm install -g tapflow
+# or: yarn global add tapflow  |  pnpm add -g tapflow
+```
+
+### 2. Start relay + agent
+
+```sh
+tapflow start
+# ✓ Relay started on http://localhost:4000
+# ✓ iOS Agent connected (3 simulators available)
+```
+
+This starts both the relay and the agent on the same Mac (local mode).
+
+### 3. Create the first admin account
+
+```sh
+tapflow init
+# ? Admin email: admin@yourteam.com
+# ? Password: ********
+# ✓ Admin account created
+```
+
+### 4. Open the dashboard
+
+Navigate to `http://localhost:4000` and sign in with the account you just created.
+
+> **Having issues?** Run `tapflow doctor` to auto-diagnose Node.js, Xcode, `adb`, and other prerequisites.
+
+## Requirements
+
+| Component | Requirements |
+|-----------|-------------|
+| **Relay server** | Node.js ≥ 20, any OS (Linux/macOS), ~512 MB RAM |
+| **iOS Agent** | macOS, Xcode with iOS Simulator Runtime, Node.js ≥ 20 |
+| **Android Agent** | macOS, Android SDK (`adb` in `$PATH` or `$ANDROID_HOME` set), AVD with `google_apis/arm64-v8a` (android-34), Node.js ≥ 20 |
+| **Browser (QA)** | Any modern browser — Chrome, Firefox, Safari, Edge |
+
+## Self-Hosting
+
+### Local (single Mac)
+
+Relay and agent on the same machine — ideal for a single developer or small team.
+
+```sh
+tapflow start
+```
+
+### Team (separate relay server)
+
+Run the relay on a Linux server or dedicated Mac. Each Mac with simulators runs the agent.
+
+**Relay server:**
+
+```sh
+# Recommended: PM2 for automatic restarts
+npm install -g pm2 tapflow
+JWT_SECRET=$(openssl rand -hex 32) pm2 start tapflow --name relay -- relay start
+pm2 save && pm2 startup
+```
+
+**Each Mac agent:**
+
+```sh
+tapflow agent start --relay wss://your-relay-url
+```
+
+> For nginx / Caddy reverse proxy setup and external access, see [Self-Hosting the Relay](https://jo-duchan.github.io/tapflow/guide/self-hosting).
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `tapflow start` | Start relay + agent together (local mode) |
+| `tapflow relay start` | Start relay only |
+| `tapflow agent start --relay <url>` | Start agent and connect to a relay |
+| `tapflow init` | Create the first admin account |
+| `tapflow doctor` | Diagnose environment (Node, Xcode, adb…) |
+| `tapflow devices` | List available simulators and emulators |
+| `tapflow boot <name\|udid>` | Boot a simulator or emulator |
+| `tapflow status` | Show connected agents, devices, active sessions |
+| `tapflow reset` | Shut down all simulators and emulators |
+| `tapflow logs` | Show recent relay log entries |
+
+Full reference → [CLI docs](https://jo-duchan.github.io/tapflow/reference/cli)
+
+## Documentation
+
+**[jo-duchan.github.io/tapflow](https://jo-duchan.github.io/tapflow)**
+
+- [Introduction](https://jo-duchan.github.io/tapflow/guide/introduction)
+- [Quick Start](https://jo-duchan.github.io/tapflow/guide/getting-started)
+- [Self-Hosting the Relay](https://jo-duchan.github.io/tapflow/guide/self-hosting)
+- [iOS Agent Setup](https://jo-duchan.github.io/tapflow/guide/ios-agent)
+- [Android Agent Setup](https://jo-duchan.github.io/tapflow/guide/android-agent)
+- [Uploading Builds (CI/CD)](https://jo-duchan.github.io/tapflow/guide/upload-builds)
+- [CLI Reference](https://jo-duchan.github.io/tapflow/reference/cli)
+- [Troubleshooting](https://jo-duchan.github.io/tapflow/guide/troubleshooting)
+
+## Development
+
+**Requirements**: Node.js ≥ 20, pnpm ≥ 9
+
+```sh
+git clone https://github.com/jo-duchan/tapflow.git
+cd tapflow
+pnpm install
+pnpm dev
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for branch strategy, commit conventions, and architecture overview.
+
+## License
+
+[MIT](LICENSE) — Copyright © 2025-present tapflow contributors
+
+> tapflow bundles [scrcpy-server](https://github.com/Genymobile/scrcpy) (Apache-2.0) for Android screen streaming. See [NOTICE](NOTICE) for full attribution.

package/bin/tapflow.js

@@ -1 +1,2 @@
-console.log('Tapflow is coming soon.');
+#!/usr/bin/env node
+import '../dist/index.js'

package/package.json

@@ -1,15 +1,66 @@
 {
   "name": "tapflow",
-  "version": "0.0.1",
-  "description": "Self-hosted QA device streaming and remote control toolkit.",
+  "version": "0.1.0-alpha.1",
+  "description": "Self-hosted iOS/Android simulator streaming for QA teams",
+  "keywords": [
+    "ios",
+    "android",
+    "simulator",
+    "emulator",
+    "qa",
+    "testing",
+    "streaming",
+    "self-hosted"
+  ],
+  "homepage": "https://github.com/jo-duchan/tapflow",
+  "bugs": "https://github.com/jo-duchan/tapflow/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jo-duchan/tapflow.git"
+  },
   "license": "MIT",
-  "private": false,
   "bin": {
     "tapflow": "./bin/tapflow.js"
   },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
     "bin",
+    "dist",
     "README.md",
     "LICENSE"
-  ]
-}
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "tsx": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "cac": "^6.7.14",
+    "ws": "^8.0.0",
+    "@tapflow/agent-core": "0.1.0-alpha.1",
+    "@tapflow/ios-agent": "0.1.0-alpha.1",
+    "@tapflow/android-agent": "0.1.0-alpha.1",
+    "@tapflow/relay": "0.1.0-alpha.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "lint": "eslint src"
+  }
+}