devpilot-ai 0.1.0__tar.gz

devpilot_ai-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.devpilot/state.json
+.devpilot/state.json.lock
+.env

devpilot_ai-0.1.0/LICENSE

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

devpilot_ai-0.1.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: devpilot-ai
+Version: 0.1.0
+Summary: Dev server supervisor for AI coders
+Project-URL: Homepage, https://github.com/benzsevern/devpilot
+Project-URL: Repository, https://github.com/benzsevern/devpilot
+Project-URL: Issues, https://github.com/benzsevern/devpilot/issues
+Author-email: Ben Severn <benzsevern@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,copilot,cursor,dev-server,hot-reload,process-manager,supervisor
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: filelock>=3.13
+Requires-Dist: httpx>=0.27
+Requires-Dist: psutil>=5.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: watchdog>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest-timeout>=2.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# devpilot
+
+Dev server supervisor for AI coders.
+
+AI coding agents (Claude Code, Cursor, Copilot) break dev servers constantly — editing files mid-reload, causing port conflicts, spawning zombie processes. Then they panic: kill random PIDs, rotate ports, nuke all Python processes. It gets worse.
+
+**devpilot** gives AI coders structured, reliable process awareness. It manages dev server lifecycles, detects reloads, checks health, and returns JSON that AI can parse and act on — so the panic cycle never starts.
+
+## Install
+
+```bash
+pip install devpilot
+```
+
+Or with pipx for global CLI use:
+
+```bash
+pipx install devpilot
+```
+
+## Quick Start
+
+### Auto-detect and configure your project
+
+```bash
+devpilot init
+```
+
+Scans for `pyproject.toml`, `requirements.txt`, `package.json` and generates `.devpilot.yaml` with the right framework profiles.
+
+### Start your dev server under devpilot
+
+```bash
+devpilot run api "uvicorn main:app --reload --port 8000"
+```
+
+### Or attach to an already-running server
+
+```bash
+devpilot attach api --port 8000
+```
+
+### Check what happened after editing a file
+
+```bash
+devpilot changed src/main.py
+```
+
+Returns structured JSON:
+
+```json
+[{
+  "service": "api",
+  "reload": "reloaded",
+  "reload_time_ms": 340,
+  "healthy": true,
+  "response_time_ms": 12
+}]
+```
+
+### Manage everything at once
+
+```bash
+devpilot up      # start all services from .devpilot.yaml
+devpilot down    # stop all services
+devpilot status  # health check everything
+```
+
+## Why This Exists
+
+When an AI coder edits your code, the dev server reloads. But the AI has no way to know:
+
+- Did the reload succeed or crash?
+- Is the server healthy?
+- Which service was affected by that file change?
+- Should it wait, retry, or escalate?
+
+Without answers, AI coders guess. They kill processes they shouldn't, rotate ports randomly, and create cascading failures. devpilot closes this feedback loop with structured, reliable signals.
+
+## How It Works
+
+**Two modes:**
+
+- **Managed** (`devpilot run`) — devpilot spawns the process, captures stdout, detects reload patterns, owns the full lifecycle
+- **Attached** (`devpilot attach`) — devpilot monitors an existing process by port, health-check only, never kills what it didn't start
+
+**Three recovery tiers:**
+
+| Tier | Action | Example |
+|------|--------|---------|
+| Silent | Auto-restart with backoff | Process crashed, retry up to 3x |
+| Report | Auto-recover + notify | Repeated crashes, port reassignment |
+| Escalate | Report only, never act | Unknown process on port, code errors |
+
+**Core principle:** devpilot never rotates ports randomly, never kills processes it didn't start, never nukes all Python tasks.
+
+## Built-in Framework Profiles
+
+| Framework | Detection | Default Port |
+|-----------|-----------|-------------|
+| FastAPI/Uvicorn | `uvicorn` in command | 8000 |
+| Flask | `flask` in command | 5000 |
+| Django | `manage.py runserver` | 8000 |
+| Vite | `vite` in command | 5173 |
+| Next.js | `next dev` in command | 3000 |
+| Create React App | `react-scripts start` | 3000 |
+
+Custom frameworks can be added in `.devpilot.yaml`.
+
+## Configuration
+
+`.devpilot.yaml` (generated by `devpilot init` or written manually):
+
+```yaml
+services:
+  api:
+    cmd: "uvicorn main:app --reload --port 8000"
+    port: 8000
+    health: /health
+    file_patterns:
+      - "src/**/*.py"
+    reload_patterns:
+      - "Started reloading"
+      - "Application startup complete"
+
+  frontend:
+    cmd: "npm run dev"
+    port: 3000
+    file_patterns:
+      - "src/**/*.tsx"
+      - "src/**/*.css"
+
+recovery:
+  max_retries: 3
+  backoff_seconds: [1, 3, 5]
+  auto_port_reassign: true
+```
+
+## All Commands
+
+| Command | Description |
+|---------|-------------|
+| `devpilot init` | Auto-detect project and generate `.devpilot.yaml` |
+| `devpilot run <name> <cmd>` | Start a managed service |
+| `devpilot attach <name> --port N` | Monitor an existing service |
+| `devpilot status [name]` | Health check one or all services |
+| `devpilot changed <filepath>` | Report file change, get reload/health result |
+| `devpilot stop [name] [--all]` | Stop managed services |
+| `devpilot restart <name>` | Restart a managed service |
+| `devpilot log [name]` | Show recent events |
+| `devpilot cleanup` | Remove stale state and dead PIDs |
+| `devpilot up` | Start all services from config |
+| `devpilot down` | Stop all services |
+
+Every command returns structured JSON to stdout with exit codes 0 (success), 1 (all failed), or 2 (partial).
+
+## For AI Tool Authors
+
+devpilot is designed to be called programmatically. The JSON output and deterministic exit codes make it straightforward to integrate into any AI coding workflow:
+
+```python
+import subprocess, json
+
+result = subprocess.run(
+    ["devpilot", "changed", "src/main.py"],
+    capture_output=True, text=True
+)
+changes = json.loads(result.stdout)
+
+for svc in changes:
+    if not svc["healthy"]:
+        # check the reload status before panicking
+        if svc["reload"] == "reload_failed":
+            print(f"Code error in {svc['service']}: {svc.get('error')}")
+        elif svc["reload"] == "timeout":
+            print(f"Reload slow for {svc['service']}, waiting...")
+```
+
+## Requirements
+
+- Python 3.10+
+- Works on Windows, macOS, and Linux
+
+## License
+
+MIT

devpilot_ai-0.1.0/README.md

@@ -0,0 +1,186 @@
+# devpilot
+
+Dev server supervisor for AI coders.
+
+AI coding agents (Claude Code, Cursor, Copilot) break dev servers constantly — editing files mid-reload, causing port conflicts, spawning zombie processes. Then they panic: kill random PIDs, rotate ports, nuke all Python processes. It gets worse.
+
+**devpilot** gives AI coders structured, reliable process awareness. It manages dev server lifecycles, detects reloads, checks health, and returns JSON that AI can parse and act on — so the panic cycle never starts.
+
+## Install
+
+```bash
+pip install devpilot
+```
+
+Or with pipx for global CLI use:
+
+```bash
+pipx install devpilot
+```
+
+## Quick Start
+
+### Auto-detect and configure your project
+
+```bash
+devpilot init
+```
+
+Scans for `pyproject.toml`, `requirements.txt`, `package.json` and generates `.devpilot.yaml` with the right framework profiles.
+
+### Start your dev server under devpilot
+
+```bash
+devpilot run api "uvicorn main:app --reload --port 8000"
+```
+
+### Or attach to an already-running server
+
+```bash
+devpilot attach api --port 8000
+```
+
+### Check what happened after editing a file
+
+```bash
+devpilot changed src/main.py
+```
+
+Returns structured JSON:
+
+```json
+[{
+  "service": "api",
+  "reload": "reloaded",
+  "reload_time_ms": 340,
+  "healthy": true,
+  "response_time_ms": 12
+}]
+```
+
+### Manage everything at once
+
+```bash
+devpilot up      # start all services from .devpilot.yaml
+devpilot down    # stop all services
+devpilot status  # health check everything
+```
+
+## Why This Exists
+
+When an AI coder edits your code, the dev server reloads. But the AI has no way to know:
+
+- Did the reload succeed or crash?
+- Is the server healthy?
+- Which service was affected by that file change?
+- Should it wait, retry, or escalate?
+
+Without answers, AI coders guess. They kill processes they shouldn't, rotate ports randomly, and create cascading failures. devpilot closes this feedback loop with structured, reliable signals.
+
+## How It Works
+
+**Two modes:**
+
+- **Managed** (`devpilot run`) — devpilot spawns the process, captures stdout, detects reload patterns, owns the full lifecycle
+- **Attached** (`devpilot attach`) — devpilot monitors an existing process by port, health-check only, never kills what it didn't start
+
+**Three recovery tiers:**
+
+| Tier | Action | Example |
+|------|--------|---------|
+| Silent | Auto-restart with backoff | Process crashed, retry up to 3x |
+| Report | Auto-recover + notify | Repeated crashes, port reassignment |
+| Escalate | Report only, never act | Unknown process on port, code errors |
+
+**Core principle:** devpilot never rotates ports randomly, never kills processes it didn't start, never nukes all Python tasks.
+
+## Built-in Framework Profiles
+
+| Framework | Detection | Default Port |
+|-----------|-----------|-------------|
+| FastAPI/Uvicorn | `uvicorn` in command | 8000 |
+| Flask | `flask` in command | 5000 |
+| Django | `manage.py runserver` | 8000 |
+| Vite | `vite` in command | 5173 |
+| Next.js | `next dev` in command | 3000 |
+| Create React App | `react-scripts start` | 3000 |
+
+Custom frameworks can be added in `.devpilot.yaml`.
+
+## Configuration
+
+`.devpilot.yaml` (generated by `devpilot init` or written manually):
+
+```yaml
+services:
+  api:
+    cmd: "uvicorn main:app --reload --port 8000"
+    port: 8000
+    health: /health
+    file_patterns:
+      - "src/**/*.py"
+    reload_patterns:
+      - "Started reloading"
+      - "Application startup complete"
+
+  frontend:
+    cmd: "npm run dev"
+    port: 3000
+    file_patterns:
+      - "src/**/*.tsx"
+      - "src/**/*.css"
+
+recovery:
+  max_retries: 3
+  backoff_seconds: [1, 3, 5]
+  auto_port_reassign: true
+```
+
+## All Commands
+
+| Command | Description |
+|---------|-------------|
+| `devpilot init` | Auto-detect project and generate `.devpilot.yaml` |
+| `devpilot run <name> <cmd>` | Start a managed service |
+| `devpilot attach <name> --port N` | Monitor an existing service |
+| `devpilot status [name]` | Health check one or all services |
+| `devpilot changed <filepath>` | Report file change, get reload/health result |
+| `devpilot stop [name] [--all]` | Stop managed services |
+| `devpilot restart <name>` | Restart a managed service |
+| `devpilot log [name]` | Show recent events |
+| `devpilot cleanup` | Remove stale state and dead PIDs |
+| `devpilot up` | Start all services from config |
+| `devpilot down` | Stop all services |
+
+Every command returns structured JSON to stdout with exit codes 0 (success), 1 (all failed), or 2 (partial).
+
+## For AI Tool Authors
+
+devpilot is designed to be called programmatically. The JSON output and deterministic exit codes make it straightforward to integrate into any AI coding workflow:
+
+```python
+import subprocess, json
+
+result = subprocess.run(
+    ["devpilot", "changed", "src/main.py"],
+    capture_output=True, text=True
+)
+changes = json.loads(result.stdout)
+
+for svc in changes:
+    if not svc["healthy"]:
+        # check the reload status before panicking
+        if svc["reload"] == "reload_failed":
+            print(f"Code error in {svc['service']}: {svc.get('error')}")
+        elif svc["reload"] == "timeout":
+            print(f"Reload slow for {svc['service']}, waiting...")
+```
+
+## Requirements
+
+- Python 3.10+
+- Works on Windows, macOS, and Linux
+
+## License
+
+MIT

devpilot_ai-0.1.0/claude-plugin/hooks/detect-devserver-pain.mjs

@@ -0,0 +1,89 @@
+/**
+ * UserPromptSubmit hook — detects dev server pain signals in user messages
+ * and suggests the devpilot skill when relevant.
+ *
+ * Reads the user's prompt from stdin (JSON with `prompt` field) and checks
+ * for frustration patterns related to dev server management.
+ */
+
+const PAIN_PATTERNS = [
+  // Direct crashes and failures
+  /dev\s*server.*(?:crash|die|stop|kill|broke|broken|down|fail)/i,
+  /server.*(?:crash|die|stop|kill|broke|broken|down|fail)/i,
+  /(?:crash|die|stop|kill|broke|broken|down|fail).*(?:dev\s*server|server)/i,
+
+  // Hot reload issues
+  /(?:hot\s*)?reload.*(?:fail|stuck|broken|not\s*work|slow|hang)/i,
+  /(?:hmr|hot\s*module).*(?:fail|stuck|broken|not\s*work)/i,
+  /changes.*(?:not\s*show|not\s*reflect|not\s*pick|not\s*appear|not\s*updat)/i,
+
+  // Port conflicts
+  /(?:port|address).*(?:already\s*in\s*use|conflict|taken|busy)/i,
+  /eaddrinuse/i,
+
+  // Zombie / orphan processes
+  /zombie\s*process/i,
+  /orphan\s*process/i,
+  /process.*(?:won't\s*die|stuck|hang|stale)/i,
+  /kill.*(?:all|every).*(?:python|node|process)/i,
+
+  // Restart loops
+  /(?:keep|keeps|constantly|always).*(?:restart|crash|die|fail)/i,
+  /restart.*loop/i,
+  /can't.*(?:start|restart|run).*(?:server|dev)/i,
+
+  // Panic signals
+  /(?:kill|taskkill|pkill).*(?:python|node|uvicorn|next|vite|flask)/i,
+  /kill\s*-9/i,
+  /taskkill\s*\/f/i,
+  /lsof.*(?:kill|port)/i,
+  /netstat.*(?:kill|port)/i,
+
+  // Direct asks
+  /devpilot/i,
+  /dev\s*server\s*supervisor/i,
+  /supervise.*(?:dev|server|process)/i,
+];
+
+async function main() {
+  let input = "";
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  let prompt;
+  try {
+    const data = JSON.parse(input);
+    prompt = data.prompt || "";
+  } catch {
+    // Not JSON, treat the raw input as the prompt
+    prompt = input;
+  }
+
+  if (!prompt) {
+    console.log(JSON.stringify({ result: "approve" }));
+    return;
+  }
+
+  const matched = PAIN_PATTERNS.some((pattern) => pattern.test(prompt));
+
+  if (matched) {
+    console.log(
+      JSON.stringify({
+        result: "approve",
+        additionalContext: [
+          "**Dev server pain detected.** The `devpilot` skill can help here.",
+          "If devpilot is not installed, suggest: `pip install devpilot`",
+          "Then use devpilot to manage the dev server instead of killing processes manually.",
+          "Run `Skill(devpilot)` for full guidance.",
+        ].join("\n"),
+      })
+    );
+  } else {
+    console.log(JSON.stringify({ result: "approve" }));
+  }
+}
+
+main().catch(() => {
+  console.log(JSON.stringify({ result: "approve" }));
+});

devpilot_ai-0.1.0/claude-plugin/plugin.json

@@ -0,0 +1,41 @@
+{
+  "name": "devpilot",
+  "version": "0.1.0",
+  "description": "Dev server supervisor for AI coders — detects dev server pain and provides structured process management",
+  "skills": [
+    {
+      "name": "devpilot",
+      "path": "skills/devpilot/SKILL.md",
+      "description": "Dev server supervisor guidance — install, configure, and use devpilot to manage dev server lifecycles, detect reloads, and recover from crashes. Use when: dev server crashes, hot reload fails, port conflicts, zombie processes, AI coder is stuck in a restart loop, or user asks about devpilot.",
+      "metadata": {
+        "filePattern": [
+          ".devpilot.yaml",
+          ".devpilot.yml",
+          ".devpilot/**"
+        ],
+        "bashPattern": [
+          "devpilot\\b",
+          "uvicorn.*--reload",
+          "next\\s+dev",
+          "npm\\s+run\\s+dev",
+          "vite",
+          "flask\\s+run",
+          "manage\\.py\\s+runserver"
+        ]
+      }
+    }
+  ],
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/detect-devserver-pain.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}