Metadata-Version: 2.4
Name: winstack
Version: 0.1.0
Summary: Windows-native process orchestrator — no Docker, no WSL required
Project-URL: Homepage, https://github.com/sunnymurali/winstack
Project-URL: Repository, https://github.com/sunnymurali/winstack
Project-URL: Bug Tracker, https://github.com/sunnymurali/winstack/issues
License: MIT
Keywords: devtools,local-dev,orchestrator,process,windows
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Requires-Dist: gitpython>=3.1.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=0.47.0
Requires-Dist: typer>=0.9.0
Description-Content-Type: text/markdown

# WinStack

**Windows-native process orchestrator — no Docker, no WSL required.**

Start, stop, and monitor your local development services from a single YAML file. Think `docker-compose up`, but for native Windows processes.

```
winstack bootstrap   # clone → install → start → health-check
winstack ui          # live split-pane dashboard
winstack down        # stop everything cleanly
```

---

## Features

- **Single YAML config** — define all your services, dependencies, and health checks in one place
- **Dependency ordering** — services start and stop in the correct order based on `depends_on`
- **Health checks** — HTTP and TCP checks with configurable retries before marking a service ready
- **Restart watchdog** — `on_failure` and `always` restart policies with max retry limits
- **Live TUI dashboard** — split-pane terminal UI with real-time logs, CPU/memory, uptime
- **Prerequisite checks** — verify tools, ports, env vars, and folders before starting
- **Git integration** — clone or pull repos as part of `bootstrap`
- **Group support** — start subsets of services with `--group`

---

## Installation

```bash
pip install winstack
```

Or install from source:

```bash
git clone https://github.com/sunnymurali/winstack.git
cd winstack
pip install -e .
```

**Requirements:** Python 3.9+, Windows 10/11

---

## Quick Start

**1. Create a config:**

```bash
winstack init
```

Or copy `example.winstack.yaml` and edit it.

**2. First-time setup (clone + install + start):**

```bash
winstack bootstrap
```

**3. Start services (after first run):**

```bash
winstack up
```

**4. Open the live dashboard:**

```bash
winstack ui
```

---

## Commands

| Command | Description |
|---|---|
| `winstack init` | Interactive wizard — creates `winstack.yaml` |
| `winstack check` | Run prerequisite checks only |
| `winstack clone` | Clone or pull repos for services with `repo:` set |
| `winstack bootstrap` | Full first-run: clone → install → start |
| `winstack up` | Start services (skips clone & install) |
| `winstack down` | Stop all running services |
| `winstack restart <name>` | Stop and restart a single service |
| `winstack status` | Table view of all service states |
| `winstack logs <name>` | Tail a service log in real time |
| `winstack ui` | Interactive split-pane TUI dashboard |

### Common flags

| Flag | Commands | Effect |
|---|---|---|
| `--config / -c <path>` | all | Use a different yaml file |
| `--group / -g <name>` | `up`, `down`, `bootstrap`, `clone` | Act on a named subset |
| `--skip-install` | `bootstrap` | Skip install step |
| `--skip-checks` | `bootstrap` | Skip prerequisite checks |
| `--lines / -n <N>` | `logs` | Lines to show before following (default 50) |

---

## Configuration Reference

```yaml
version: "1"

# Global env vars — merged into every service
env:
  PYTHONPATH: "."

# Checks run before any service starts
prerequisites:
  - type: command        # verify a CLI tool exists
    name: python
    version_flag: "--version"
    expected_contains: "Python 3"
    fix: "Install Python 3.9+"

  - type: port_free      # verify a port is available
    port: 8001
    fix: "Stop whatever is on 8001"

  - type: env_var        # verify an env var is set
    name: OPENAI_API_KEY
    fix: "Set OPENAI_API_KEY before running"

  - type: folder         # verify a directory exists
    path: C:/data/myapp
    fix: "mkdir C:/data/myapp"

# Named subsets — start with: winstack up --group <name>
groups:
  minimal: [api]
  full:    [api, worker, frontend]

services:
  api:
    dir: ./api                        # relative to winstack.yaml
    repo: https://github.com/…        # clone/pull with winstack clone
    install: pip install -r requirements.txt
    start: python start_server.py
    env_file: .env                    # loaded from service dir
    env:
      LOG_LEVEL: INFO                 # per-service env (overrides global)
    enabled: true                     # set false to skip without deleting

    health:
      type: http                      # http | tcp | none
      url: http://localhost:8001/docs
      host: localhost                 # tcp only
      port: 8001                      # tcp only
      interval: 3                     # seconds between retries
      retries: 20                     # total attempts
      timeout: 5                      # per-check timeout

    restart:
      policy: on_failure              # no | on_failure | always
      max_retries: 3                  # 0 = unlimited

    depends_on:
      other_service:
        condition: process_healthy    # process_started | process_healthy
```

---

## Live Dashboard (`winstack ui`)

```
┌ WinStack ──────────────────────────────── 10:42:31 ─┐
│  Service        Status       PID    CPU         Mem  │
│ ──────────────────────────────────────────────────── │
│ > sql_agent     ● RUNNING    1234   ███░░  2.3%  45MB│
│   vector_svc    ○ STOPPED    —      —             —  │
├────────────────────────────────────────────────────── │
│  LOGS  ──  sql_agent                                 │
│  10:42:28 Starting server...                         │
│  10:42:29 Loaded config                              │
│  10:42:30 ERROR: connection refused    ← bold red    │
└─────────────────────────────────────────────────────┘
│  q Quit  r Restart  s Start/Stop  c Clear Logs       │
```

**Keyboard shortcuts:**

| Key | Action |
|---|---|
| `↑` / `↓` | Navigate service list |
| `r` | Restart selected service |
| `s` | Toggle start/stop |
| `c` | Clear log panel |
| `g` / `G` | Jump to top / bottom of logs |
| `q` | Quit |

---

## Restart Watchdog

When `restart.policy` is `on_failure` or `always`, a background thread monitors the process every 2 seconds and restarts it automatically (up to `max_retries` times). A manual `winstack down` cancels the watchdog so it doesn't fight the stop.

---

## How `bootstrap` works

```
winstack bootstrap
  └─ prerequisite checks
  └─ for each service (dependency order):
       clone_or_pull   (if repo: is set)
       run install
       start process   → watchdog thread spawned
       wait for health check
```

---

## License

MIT
