bgo-cli 0.2.0__tar.gz

bgo_cli-0.2.0/.gitignore

@@ -0,0 +1,29 @@
+# Hindsight memory bank pointer (local)
+.bank
+
+# Serena MCP project state
+.serena/
+
+# PROJECT_INDEX (auto-generated)
+PROJECT_INDEX.json
+PROJECT_INDEX.md
+
+# Hindsight migration markers
+.hindsight-migrate-declined
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+src/*.egg-info/
+
+# Local virtualenvs
+.venv/
+venv/
+.env

bgo_cli-0.2.0/AGENTS.md

@@ -0,0 +1,191 @@
+# Agent Instructions
+
+<!-- TEAM_MODE:START -->
+## ⚡ Team Mode is ACTIVE
+IMPORTANT: Read `TEAM.md` in the project root IN FULL before processing any task.
+You are operating as Tech Lead of a multi-agent team, not as a solo developer.
+If you don't remember Team Mode being activated, re-read `TEAM.md` NOW — it contains all instructions.
+<!-- TEAM_MODE:END -->
+
+<!-- myc:agents-start v=3 -->
+## Project Management with Mycelium
+
+This project uses [Mycelium](https://github.com/tcsenpai/mycelium) (`myc`) for task and epic management.
+
+### Quick Reference
+
+```bash
+# Initialize mycelium in this project (creates .mycelium/ directory)
+myc init
+
+# Create an epic (a large body of work)
+myc epic create --title "Feature X" --description "Build feature X"
+
+# Create tasks within an epic
+myc task create --title "Implement Y" --description "Build the implementation for Y" --epic 1 --priority high --due 2025-12-31
+
+# Task priorities: low, medium, high, critical
+# Task status: open, closed
+
+# List tasks
+myc task list
+myc task list --epic 1
+myc task list --overdue
+myc task list --blocked
+
+# Manage dependencies (task 1 blocks task 2)
+myc task link blocks --task 1 2
+myc deps show 2
+
+# Close tasks (blocked tasks cannot be closed without --force)
+myc task close 1
+
+# Assign tasks
+myc assignee create --name "Alice" --github "alice"
+myc task assign 1 1
+
+# Link to external resources
+myc task link github-issue --task 1 "owner/repo#123"
+myc task link github-pr --task 1 "owner/repo#456"
+myc task link url --task 1 "https://example.com"
+
+# Project overview
+myc summary
+
+# Export data
+myc export json
+myc export csv
+```
+
+### Data Model
+
+- **Epic**: A large body of work with a title and optional description (e.g., a feature or milestone)
+- **Task**: A unit of work with a title and optional description, optionally linked to an epic
+- **Dependency**: Task A blocks Task B (B cannot close until A is closed)
+- **Assignee**: Person assigned to a task (can have GitHub username)
+- **External Ref**: Link to GitHub issues/PRs or URLs
+
+### Git Tracking
+
+The `.mycelium/` directory contains the SQLite database and should be committed to git:
+
+```bash
+git add .mycelium/
+git commit -m "Add mycelium project tracking"
+```
+
+### Follow-ups (`myc followup`, alias `myc fu`)
+
+Lightweight scratch table for non-blocking "oh-by-the-way" items
+captured mid-work — bugs, questions, ideas, things the user should look
+at later. **Separate from tasks** (no epic/priority/deps/assignee). Most
+follow-ups are resolved by the user, not the agent.
+
+```bash
+myc followup add "body text"                # capture (body required)
+myc followup add "body text" --title "tag"  # optional short title
+myc fu add "short form alias works too"
+
+myc followup list                           # all (default)
+myc followup list -o                        # only active (open + in_progress)
+myc followup list -c                        # only closed (done + wontfix)
+myc followup list --status done             # exact status
+
+myc followup show <id>                      # full detail
+myc followup next                           # lowest-ID active (agent loop)
+myc followup count                          # JSON: {open, in_progress, done, wontfix}
+
+myc followup start <id>                     # → in_progress
+myc followup done <id> [--reason "..."]     # → done
+myc followup wontfix <id> [--reason "..."]  # → wontfix
+myc followup reopen <id>                    # → open
+
+myc followup edit <id> --body "new body" [--title -|"new title"]
+myc followup append <id> "more context"     # timestamped, preserves existing
+myc followup rm <id> [--force]
+myc followup promote <id> [--epic N] [--priority high]  # convert to task
+```
+
+**Agent rule — end-of-task follow-up check** (MANDATORY)
+
+At the end of every mycelium-tracked unit of work (closing a task,
+finishing a user-requested change that touched myc state), the agent
+MUST:
+
+1. Run `myc followup list --format json` (or `myc followup count
+   --format json`).
+2. If `active > 0`, surface them to the user before wrapping:
+   > "Before we wrap — N open follow-up(s): [titles/bodies]. Want me to
+   > handle any now, or leave for later?"
+3. **Never silently process them.** Always ask.
+
+`myc task close` itself also prints a one-line reminder, but the agent
+should still proactively check.
+
+Use `myc followup add` during work to capture anything you notice but
+shouldn't act on right now.
+
+### For AI Agents
+
+When working on this project:
+
+1. Check existing tasks: `myc task list`
+2. Check blocked tasks: `myc task list --blocked`
+3. Create tasks for new work: `myc task create --title "..." --description "..." --epic N`
+4. Capture incidental observations as follow-ups: `myc followup add "..."`
+5. At end of task: `myc followup list` and surface open ones to the user
+6. Mark tasks complete when done: `myc task close N`
+7. Use `--format json` for machine-readable output: `myc task list --format json`
+
+## Mental Frameworks for Mycelium Usage
+
+### 1. INVEST — Task Quality Gate
+
+Before creating or updating any task, validate it against these criteria.
+A task that fails more than one is not ready to be written.
+
+| Criterion | Rule |
+|---|---|
+| **Independent** | Can be completed without unblocking other tasks first |
+| **Negotiable** | The *what* is fixed; the *how* remains open |
+| **Valuable** | Produces a verifiable, concrete outcome |
+| **Estimable** | If you cannot size it, it is too vague or too large |
+| **Small** | If it spans more than one work cycle, split it |
+| **Testable** | Has an explicit, binary done condition |
+
+> If a task fails **Estimable** or **Testable**, convert it to an Epic and decompose.
+
+---
+
+### 2. DAG — Dependency Graph Thinking
+
+Before scheduling or prioritizing, model the implicit dependency graph.
+
+**Rules:**
+- No task moves to `in_progress` if it has an unresolved upstream blocker
+- Priority is a function of both urgency **and fan-out** (how many tasks does completing this one unlock?)
+- Always work the **critical path** first — not the task that feels most urgent
+
+**Prioritization heuristic:**
+```
+score = urgency + (blocked_tasks_count × 1.5)
+```
+
+When creating a task, explicitly ask: *"What does this block, and what blocks this?"*
+Set dependency links in Mycelium before touching status.
+
+---
+
+### 3. Principle of Minimal Surprise (PMS)
+
+Mycelium's state must remain predictable and auditable at all times.
+
+**Rules:**
+- **Prefer idempotent operations** — update before you create; never duplicate
+- **Check before write** — search for an equivalent item before creating a new one
+- **Always annotate mutations** — every status change, priority shift, or reassignment must carry an explicit `reason` field
+- **No orphan tasks** — every task must be linked to an Epic; every Epic to a strategic goal
+- Deletions are a last resort; prefer `cancelled` status with a reason
+
+> The state of Mycelium after any operation must be explainable to another agent with zero context.
+<!-- myc:agents-end -->

bgo_cli-0.2.0/LICENSE

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

bgo_cli-0.2.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: bgo-cli
+Version: 0.2.0
+Summary: Lightweight, zero-dependency background process manager (pm2-style) with watch mode and auto-restart.
+Project-URL: Homepage, https://github.com/tcsenpai/bgo
+Project-URL: Repository, https://github.com/tcsenpai/bgo
+Project-URL: Issues, https://github.com/tcsenpai/bgo/issues
+Project-URL: Changelog, https://github.com/tcsenpai/bgo/commits/main
+Author-email: tcsenpai <tcsenpai@discus.sh>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: background,cli,daemon,pm2,process-manager,supervisor,watchdog
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine>=4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bgo - Background Go
+
+Lightweight, zero-dep background process manager inspired by pm2.
+Detach any binary or script from your shell with one command.
+
+## Features
+
+- 🚀 **Simple syntax** — `bgo <name> -- <command>`
+- 🐧 **Unix-style aliases** — `bgo open` / `kill` / `rm` / `ls`
+- 📊 **Status monitoring** — CPU, memory, uptime in plain / normal / fancy tables (auto-detect)
+- 📝 **Log management** — stdout / stderr / watcher logs with follow mode
+- 🔄 **Lifecycle** — start, stop, restart, restart-stopped, restart-last, resurrect
+- 👁 **Watch mode** — auto-restart crashed processes with fast-crash backoff
+- 🧹 **Auto-cleanup** — clean stopped procs; keep logs on delete if desired
+- 🤖 **Scriptable** — `--json` output for any pipeline
+- ⚡ **Zero runtime dependencies** — pure Python 3.9+
+
+## Installation
+
+```bash
+# Via PyPI
+pip install bgo-cli
+# or
+pipx install bgo-cli
+# or
+uv tool install bgo-cli
+
+# Via the install script (system-wide, needs sudo)
+./install.sh
+
+# User-local (~/.local/bin, no sudo)
+./install.sh --local
+
+# Or manually — bgo is a single file
+cp bgo ~/.local/bin/   # or /usr/local/bin/
+ln -s "$(pwd)/bgo" ~/.local/bin/bgo
+```
+
+Run `./install.sh --help` for `--force` and `--uninstall` options.
+
+## Quick Start
+
+```bash
+# Start a process
+bgo myserver -- python3 -m http.server 8080
+bgo open myserver -- python3 -m http.server 8080   # alias
+
+# Check status
+bgo status        # full alias chain: status / ls / list
+bgo ls
+
+# Status detail for one proc (or: bgo <registered-name>)
+bgo myserver
+
+# View logs
+bgo logs myserver
+bgo logs myserver -f        # follow (tail -f)
+bgo follow myserver         # alias for logs -f
+
+# Stop / restart / delete
+bgo stop myserver           # or: bgo kill myserver
+bgo restart myserver
+bgo delete myserver         # or: bgo rm myserver
+bgo rm myserver --keep-logs # preserve log files
+
+# Bare `bgo` prints help; `bgo <unknown>` errors out (never silently spawns)
+bgo
+```
+
+## Commands
+
+### Lifecycle
+
+| Command | Description |
+|---|---|
+| `bgo start <name> -- <cmd>` | Start a process (alias: `open`) |
+| `bgo <name> -- <cmd>` | Shorthand for start |
+| `bgo stop <name>` | Stop (SIGTERM, alias: `kill`) |
+| `bgo stop <name> -f` | Force kill (SIGKILL) |
+| `bgo restart <name>` | Restart; preserves watch state and counters |
+| `bgo restart <name> --reset-counters` | Also zero `watch.restarts` |
+| `bgo restart-stopped` | Pick stopped procs to restart (interactive) |
+| `bgo restart-stopped --all` | Restart every stopped proc |
+| `bgo restart-stopped <name>...` | Restart named stopped procs |
+| `bgo restart-last` | Menu sorted most-recent-first |
+| `bgo restart-last --all` | Restart all not-running procs in recent order |
+| `bgo resurrect` | Restart all procs that were running before shutdown |
+| `bgo delete <name>` | Remove proc + logs (alias: `rm`) |
+| `bgo delete <name> --keep-logs` | Remove proc, keep logs |
+| `bgo clean` | Drop all stopped procs from the list |
+
+### Inspection
+
+| Command | Description |
+|---|---|
+| `bgo status` | Process table (alias: `ls`, `list`) |
+| `bgo status <name>` | Detail view for one proc |
+| `bgo status -w` | Watch mode (auto-refresh every 2s) |
+| `bgo status -w --interval N` | Custom refresh interval |
+| `bgo status --json` | Machine-readable output |
+| `bgo status --plain` | ASCII-only output (no color, no glyphs) |
+| `bgo status --fancy` | Force Unicode box-drawing rendering |
+| `bgo <registered-name>` | Shorthand for `bgo status <name>` |
+| `bgo logs <name>` | Last 50 lines |
+| `bgo logs <name> -f` | Follow logs |
+| `bgo logs <name> -n 100` | Last 100 lines |
+| `bgo logs <name> --stderr` | Only stderr |
+| `bgo logs <name> --watcher` | Watcher event log |
+| `bgo follow <name>` | Alias for `logs -f` (also: `tail`) |
+
+### Watch mode
+
+| Command | Description |
+|---|---|
+| `bgo start -w <name> -- <cmd>` | Start with watcher attached |
+| `bgo -w <name> <cmd>` | Direct mode with watcher |
+| `bgo watch <name>` | Attach watcher to a running proc |
+| `bgo watch <name> --interval N --min-uptime N --on-fast-crash MODE` | Tune |
+| `bgo unwatch <name>` | Detach watcher, keep proc |
+
+## Examples
+
+```bash
+# Python HTTP server
+bgo web -- python3 -m http.server 8080
+
+# Node.js app with watcher
+bgo -w api -- npm start
+
+# Custom binary with working directory
+bgo start dashboard --cwd /opt/app -- node server.js
+
+# Inspect one proc
+bgo web
+
+# Scripted: stop every online proc via JSON
+bgo status --json | python3 -c '
+import json, sys, subprocess
+for p in json.load(sys.stdin):
+    if p["status"] == "online":
+        subprocess.run(["bgo", "stop", p["name"]])
+'
+```
+
+## Status Table
+
+The table auto-detects terminal capabilities and picks the best rendering:
+
+| Level | Trigger | What you get |
+|---|---|---|
+| `plain` | non-TTY (pipes, CI logs), `TERM=dumb`, or `--plain` | ASCII only, no color, no glyphs |
+| `normal` | TTY without UTF-8 locale | ANSI color + ASCII rules |
+| `fancy` | TTY + UTF-8 locale (default) | ANSI color + Unicode box-drawing |
+
+Override with `--plain` / `--fancy` or `BGO_TABLE=plain|normal|fancy`.
+
+Sample (fancy):
+```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ NAME         STATUS     PID      CPU    MEM    UPTIME    WATCH      COMMAND                    ┃
+┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+┃ web          ● online   12345    2.5    0.1    00:05     ✓ 0        python3 -m http.server 8080 ┃
+┃ api          ● online   12346    0.0    0.0    01:23     ✓ 3        node server.js              ┃
+┃ worker       ○ stopped  -        -      -      -         ⚠ errored  python3 worker.py           ┃
+┃ batch        ● online   12347    0.0    0.0    02:11     ·          ./batch                     ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+Total: 4 | ● online: 3 | ○ stopped: 1
+
+⚠ 1 errored:
+   worker — 4 consecutive fast-crashes
+     bgo logs worker --watcher   |   bgo restart worker
+```
+
+CPU / MEM / uptime are pulled in a single batched `ps` call regardless of how many procs are running.
+
+## Watch Mode
+
+Watch mode runs a sidecar process per watched proc that polls the
+target and restarts it on crash. State (restart count, error reason,
+last stderr tail) is recorded in the proc JSON and surfaced via
+`bgo status`.
+
+### Quick start
+
+```bash
+bgo start -w myapi -- node server.js          # start with watcher
+bgo -w myapi node server.js                   # direct-mode variant
+bgo watch myapi                               # attach to a running proc
+bgo watch myapi --interval 5 --min-uptime 3 --on-fast-crash backoff
+bgo unwatch myapi                             # detach, keep proc
+bgo logs myapi --watcher                      # inspect events
+```
+
+### Fast-crash policy
+
+If a process dies before `--min-uptime` (default 2s) it's a *fast crash*. Reaction depends on `--on-fast-crash`:
+
+| Mode | Behavior |
+|---|---|
+| `backoff` (default) | Wait 2s, retry. Then 4s, then 8s. After 4 consecutive fast-crashes, mark `errored` and exit watcher. |
+| `stop` | Mark `errored` on the first fast-crash. |
+| `retry` | Retry indefinitely, capped at 8s backoff. |
+
+When a proc enters `errored`:
+- WATCH column shows `⚠ errored` (or `[!] errored` in plain).
+- Status footer summarizes errored procs and hints at the recovery commands.
+- `bgo status <name>` detail shows the error reason and last stderr tail.
+- `bgo restart <name>` clears the errored flag and re-spawns the watcher. Restart counter is **preserved** by default — use `--reset-counters` to zero it.
+
+### Tunables
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--interval N` | 3 | Poll interval after the initial uptime window |
+| `--min-uptime N` | 2 | Crash threshold; sub-window polled at high frequency |
+| `--on-fast-crash MODE` | `backoff` | One of `backoff`, `stop`, `retry` |
+| `--reset` | off | `bgo watch` only — reset prior watch config to defaults |
+
+## Storage
+
+- State: `~/.bgo/procs/<name>.json` — one file per process, written atomically (tmp + `os.replace`)
+- Logs: `~/.bgo/logs/<name>.out.log`, `<name>.err.log`, `<name>.watcher.log`
+
+## Testing
+
+```bash
+python3 -m pytest tests/ -v
+```
+
+54 tests covering state I/O, atomic writes, command-shape detection, name derivation, liveness + zombie filtering, watch-config inheritance, and table rendering across all three levels.
+
+## Requirements
+
+- Python 3.9+
+- Linux or macOS (zombie detection is platform-aware: `/proc` on Linux, `ps -o stat=` on macOS)
+
+## License
+
+MIT