npm package: @productioneer/devctl
Description: Fast, permission-free service manager for development workflows
Author: Productioneer
Latest version: 0.1.0

# DevCtl - Development Service Manager

> Fast, permission-free service manager for development workflows

[![npm version](https://img.shields.io/npm/v/@productioneer/devctl.svg)](https://www.npmjs.com/package/@productioneer/devctl)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

DevCtl eliminates workflow interruptions by managing long-running processes in the background without permission prompts. Start your services once and let DevCtl handle the rest.

## Features

- **Fast execution** (~1s per command)
- **No permission prompts** - runs silently in background
- **Smart service naming** - use short names when unambiguous
- **Log buffering** - captures up to 10,000 lines per service
- **Automatic daemon management** - starts on demand
- **Support for npm/bun projects** and arbitrary commands
- **Path-based service organization**
- **Automatic Python venv activation** - detects and activates virtual environments

## Installation

### From npm (recommended)

```bash
npm install -g @productioneer/devctl
# or
bun add -g @productioneer/devctl
```

### From source

```bash
git clone https://github.com/productioneer/devctl.git
cd devctl
npm install
npm run build
npm link
```

## Quick Start

```bash
# Start a service from package.json
devctl start dev
devctl start backend/dev
devctl start ./frontend/dev

# Run arbitrary commands
devctl run myserver -- python server.py
devctl run watcher -- npm run watch
devctl run backend -d ./api -- python -m uvicorn app:app

# Check status and logs
devctl status
devctl logs dev
devctl list

# Stop services
devctl stop dev
devctl restart dev
devctl killall
```

## Commands

### `devctl start <service>`

Starts a script from package.json. Supports path/service format:

- `devctl start dev` - starts 'dev' script in current directory
- `devctl start backend/dev` - starts 'dev' script in backend directory
- `devctl start ./project/test` - relative path support

### `devctl run <name> [options] -- <command...>`

Runs any command as a managed service:

- `devctl run server -- python app.py`
- `devctl run watcher -d ./src -- nodemon index.js`

**Important**: Use `--` before the command to prevent option parsing issues.

Options:

- `-d, --dir <path>` - Set working directory (default: current directory)

### `devctl stop <service>`

Stops a running service. Uses SIGTERM with SIGKILL fallback after 5 seconds.

### `devctl restart <service>`

Restarts a service with minimal downtime.

### `devctl logs <service>`

Returns buffered logs since last read. Logs are cleared after reading.

### `devctl status [service]`

Shows status of all services or a specific service with PID and uptime.

### `devctl list`

Lists all running service names.

### `devctl killall`

Kills all services started from current directory and subdirectories. Also cleans up daemon files.

## Architecture

DevCtl uses a client-daemon architecture:

1. **CLI Client** (`devctl`) - Lightweight command interface
2. **Daemon Process** - Manages services, buffers logs, handles IPC
3. **Unix Socket IPC** - Fast communication between client and daemon

The daemon starts automatically on first command and runs in the background. State is stored in `~/.devctl/`.

## Service Naming

DevCtl supports flexible service naming:

```bash
# Full path/name format
devctl start frontend/dev
devctl stop frontend/dev

# Short name (when unambiguous)
devctl logs dev
devctl restart dev

# Handles ambiguity
devctl start project1/test
devctl start project2/test
devctl logs test  # Error: ambiguous
devctl logs project1/test  # Works
```

## Python Virtual Environment Support

DevCtl automatically detects and activates Python virtual environments when running Python-related commands:

```bash
# Automatically activates .venv, venv, or other virtual environments
devctl run server -- python app.py
devctl run tests -- pytest
devctl run install -- pip install -r requirements.txt

# Works with any Python tool
devctl run format -- black .
devctl run lint -- flake8
devctl run notebook -- jupyter notebook
```

### How it works

1. When running Python commands (python, pip, pytest, etc.), DevCtl checks for virtual environments
2. Looks for common venv directories: `.venv`, `venv`, `env`, `.env`, `virtualenv`
3. If using `uv`, it will detect the virtual environment via `uv venv --status`
4. Automatically sets `VIRTUAL_ENV` and updates `PATH` before running the command
5. The activation is logged in the service output

### Supported Python Commands

DevCtl recognizes these as Python commands:
- Core: `python`, `python3`, `python2`, `py`, `pip`, `pip3`, `pip2`
- Package managers: `pipenv`, `poetry`, `pdm`
- Web frameworks: `uvicorn`, `gunicorn`, `flask`, `django`, `django-admin`
- Testing: `pytest`, `py.test`, `unittest`
- Linting/Formatting: `mypy`, `pylint`, `flake8`, `black`, `isort`, `ruff`
- Interactive: `jupyter`, `ipython`, `notebook`
- Others: `streamlit`, `gradio`, `fastapi`

## Performance

All commands complete in ~1 second, including daemon startup if needed.

## Python Virtual Environment Support

DevCtl automatically detects and activates Python virtual environments when running Python commands.

### How it works

1. When running a Python-related command, DevCtl checks for virtual environments in:
   - `.venv/`
   - `venv/`
   - `env/`
   - `.env/`
   - `virtualenv/`
   - Or any directory detected by `uv` (if installed)

2. If found, it automatically activates the environment before running your command

3. Works with all Python tools:
   ```
   python, python3, pip, pip3, pytest, uvicorn, flask, django,
   gunicorn, celery, jupyter, ipython, mypy, black, flake8, pylint,
   isort, poetry, pipenv, conda, mamba, pdm, hatch, ruff, and more
   ```

### Examples

```bash
# Automatically uses .venv/bin/python if .venv exists
devctl run api -- python app.py

# Works with any Python tool
devctl run server -- uvicorn main:app --reload
devctl run tests -- pytest -v

# Also works with npm scripts that use Python
devctl start dev  # If dev script runs Python, venv is activated
```

### Notes

- No manual activation needed - it's completely automatic
- Supports both Unix-like systems and Windows
- Prefers `uv` for virtual environment detection when available
- Logs show when a venv is activated for debugging

## Testing

Run the comprehensive test suite:

```bash
npm test
```

Tests cover all features including service lifecycle, logging, path resolution, and error handling.

## Development

```bash
# Build TypeScript
npm run build

# Run tests
npm test

# Clean build
npm run clean
```

## Troubleshooting

**Service won't start**: Check if script exists in package.json or command is valid.

**Logs are empty**: Some commands complete too quickly. Logs are buffered line-by-line.

**Permission denied**: Ensure you have execute permissions for the commands you're running.

**Daemon issues**: Use `devctl killall` to clean up and restart fresh.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT © Productioneer