autofirmer-expanded/README.md

# AutoFirmer

Automated futures trading dashboard for prop firm accounts via Tradovate.

---

## VPS Setup (Windows Server 2019 / 2022)

All commands are run in **PowerShell** (run as Administrator).

### 1. Install Git

Download and install from https://git-scm.com/download/win, or via winget:

```powershell
winget install --id Git.Git -e --source winget
```

Restart PowerShell after installing so `git` is on the PATH.

### 2. Install Node.js 22+

```powershell
winget install --id OpenJS.NodeJS.LTS -e --source winget
```

Restart PowerShell, then verify:

```powershell
node --version   # should be v22.x or higher
npm --version
```

### 3. Install Windows Build Tools (required for better-sqlite3)

`better-sqlite3` compiles a native C++ module and needs the Visual Studio build tools:

```powershell
npm install -g windows-build-tools
```

If that fails on newer Node, install manually:
- Download **Build Tools for Visual Studio** from https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022
- During install, select **"Desktop development with C++"**

### 4. Clone the repo

```powershell
git clone https://github.com/Senofy/autofirmer.git
cd autofirmer
```

### 5. Install dependencies

```powershell
npm install
```

### 6. Build

```powershell
npm run build
```

### 7. Run

**Development (with hot reload):**
```powershell
npm run dev
```

**Production:**
```powershell
npm start
```

The app runs on **port 3000**. Access it at `http://<your-vps-ip>:3000`.

---

## First-time setup

On first run, the SQLite database (`autotrader.sqlite`) is created automatically in the project root. No migrations need to be run manually.

Open the app in your browser and add your firms through the UI:

1. Click **+ Add Firm** on the main page
2. Enter the firm name, Tradovate username, and password
3. Go to the firm's **Settings** page to configure account types (prefix, profit target, consistency %, etc.)
4. Return to the main page — accounts will populate once the firm connects to Tradovate

---

## AutoBuyer (browser automation)

The AutoBuyer page drives a real browser to buy and reset prop-firm accounts. It
is three pieces, and all three must be running:

| Piece | What it does |
|---|---|
| the dashboard | Defines automations, queues runs, shows progress |
| `extension/` | A Chromium extension that reads the broker page and measures elements |
| `clicker/runner.py` | A desktop process that moves the real mouse and keyboard |

Automations are declared in `lib/automations.ts` — one entry per firm, with the
steps inside. Adding a button means editing that file; the page and the runner
pick it up from the server.

### 1. Load the extension

`chrome://extensions` → enable **Developer mode** → **Load unpacked** →
select the `extension` folder.

Chrome does **not** reload an unpacked extension when its files change. After
pulling updates, click the reload icon on its card — the dashboard shows the
version it sees, and a mismatch means the reload did not take.

Adding a new firm also means adding its host to `host_permissions` in
`extension/manifest.json` and reloading. Without it the extension cannot read
that site, and every step fails to locate.

### 2. Install the clicker

```powershell
cd clicker
pip install -r requirements.txt
```

See `clicker/README.md` for the per-platform notes — display scaling and
foreground lock both matter on Windows — and for the verification sequence to
run before letting it click anything on a new machine.

### 3. Start the runner

```powershell
python clicker\runner.py
```

Leave it running. It reports in every two seconds, and the dashboard greys out
the automation buttons when it is not there. A running Python process does not
reload when the source changes, so restart it after pulling updates; the
dashboard warns when its version is behind.

### Running it

Turn **Page capture** on from the AutoBuyer page, then press an automation's
button. Progress appears per step, and **Stop** halts a run between steps.

The browser must be visible and frontmost while a run is in flight — the clicks
are real OS-level input, so the machine cannot be used for anything else, and a
dialog stealing focus fails the step. That makes an RDP session a poor host:
disconnecting can suspend the desktop and break clicks in ways that are hard to
diagnose.

## Keeping it running (PM2)

Install PM2 globally:

```powershell
npm install -g pm2
npm install -g pm2-windows-startup
```

Start the app and save the process list:

```powershell
cd C:\path\to\autofirmer
pm2 start "npm start" --name autofirmer
pm2 save
pm2-startup install
```

To restart after pulling updates:

```powershell
cd C:\path\to\autofirmer
git pull
npm install
npm run build
pm2 restart autofirmer
```

If the update touched the AutoBuyer, two things do **not** reload themselves:

- **The extension** — click reload on its card in `chrome://extensions`.
- **The runner** — stop it with Ctrl-C and start it again.

The dashboard reports the version it sees from each, and warns when either is
behind. Most AutoBuyer bugs that look mysterious are one of these two still
running the previous code.

---

## Firewall

To restrict port 3000 to a specific trusted IP only:

```powershell
New-NetFirewallRule -DisplayName "AutoFirmer" -Direction Inbound -Protocol TCP -LocalPort 3000 -RemoteAddress <your-ip> -Action Allow
```

Or open it to all inbound (less secure):

```powershell
New-NetFirewallRule -DisplayName "AutoFirmer" -Direction Inbound -Protocol TCP -LocalPort 3000 -Action Allow
```

---

## Updating

```powershell
cd C:\path\to\autofirmer
git pull
npm install       # only needed if dependencies changed
npm run build
pm2 restart autofirmer
```

If the update touched the AutoBuyer, two things do **not** reload themselves:

- **The extension** — click reload on its card in `chrome://extensions`.
- **The runner** — stop it with Ctrl-C and start it again.

The dashboard reports the version it sees from each, and warns when either is
behind. Most AutoBuyer bugs that look mysterious are one of these two still
running the previous code.