python-dmon 0.4.0__tar.gz → 0.5.0__tar.gz

python_dmon-0.5.0/LICENSE

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

python_dmon-0.5.0/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: python-dmon
+Version: 0.5.0
+Summary: A lightweight, cross-platform process manager for background tasks, local service stacks, and partial recovery.
+Keywords: dmon,process manager,daemon,background,supervisor,local development,readiness,service management,coding agents
+Author: Atomie CHEN
+Author-email: Atomie CHEN <atomic_cwh@163.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: psutil>=7.1.0
+Requires-Dist: python-dotenv>=1.0.1,<1.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: termcolor>=2.4.0
+Requires-Dist: tomli>=2.2.1 ; python_full_version < '3.11'
+Requires-Python: >=3.8
+Project-URL: Bug Tracker, https://github.com/atomiechen/dmon/issues
+Project-URL: Changelog, https://github.com/atomiechen/dmon/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/atomiechen/dmon
+Description-Content-Type: text/markdown
+
+# dmon
+
+![dmon — The local process manager for developers and coding agents.](https://raw.githubusercontent.com/atomiechen/dmon/main/assets/banner.svg)
+
+
+[![GitHub](https://img.shields.io/badge/github-dmon-blue?logo=github)](https://github.com/atomiechen/dmon)
+[![PyPI](https://img.shields.io/pypi/v/python--dmon?logo=pypi&logoColor=white)](https://pypi.org/project/python-dmon/)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/atomiechen/dmon)
+
+
+A lightweight, cross-platform process manager for local services and development workflows.
+Run any command as a background *task*, or supervise a stack with readiness checks
+and repair failed members while healthy services keep running. Logging and log
+rotation are built in.
+
+For developers and coding agents, dmon records process identities and exposes
+JSON status so later sessions can inspect and reuse existing services.
+See [coding-agent setup](https://github.com/atomiechen/dmon/blob/main/docs/agent-setup.md).
+
+Shipped as the CLI tool `dmon`.
+
+
+## Features
+
+- 🖥️ **Cross-platform:** Works on Linux, macOS, and Windows.
+- ⚡ **Lightweight:** No daemon service or container runtime required.
+- 🧩 **Flexible tasks:** Tasks can be configured in `pyproject.toml` or `dmon.yaml`; or run ad-hoc commands directly.
+- 🔗 **Supervised stacks:** Start dependent tasks in order, wait for HTTP, TCP,
+  or command readiness, and report runtime degradation.
+- 🌙 **Foreground or detached:** Keep a stack attached for development, or run
+  it under a recoverable background supervisor with `dmon stack up -d` and
+  `dmon stack down`.
+- ⏱️ **Reusable readiness:** Wait for configured tasks or direct HTTP, TCP, and
+  command probes from scripts and deployment workflows.
+- 🪵 **Logging & log rotation:** Keep active log files manageable, with optional archive retention limits.
+
+
+## Demos
+
+The demos below cover everyday task management and supervised stacks. Both use this `dmon.yaml` and a small [heartbeat program](https://github.com/atomiechen/dmon/blob/main/scripts/recording/service.py):
+
+```yaml
+tasks:
+  api: [python, -u, service.py, api]
+  worker: [python, -u, service.py, worker]
+stacks:
+  dev: [api, worker]
+```
+
+**Everyday tasks.** Run a command directly with `run` (no configuration needed),
+then use `start`, `status`, and `stop` for a configured task. `exec` runs a
+configured task in the foreground; Ctrl-C ends it. In this clip, `stop --all`
+stops the sole ad-hoc task before the configured API is started.
+
+![Run an ad-hoc command, manage a configured task, and execute a task in the foreground](https://github.com/user-attachments/assets/2b60acab-d56d-43c0-a44b-f602243c7105)
+
+
+**Keep healthy services running.** Start a stack, deliberately stop its worker,
+and repair that member. The API keeps the same PID and its counter continues;
+`stack down` stops both members. The lower panes show real files and live logs.
+
+![Start a stack, repair only its stopped worker, and clean up both members](https://github.com/user-attachments/assets/58d1a9f9-91d8-4096-9dca-ac53815194c8)
+
+
+
+## Installation
+
+`dmon` requires Python 3.8+ and is available as [`python-dmon`](https://pypi.org/project/python-dmon/) on PyPI.
+Managed commands can use any language.
+
+```sh
+pip install python-dmon
+```
+
+We recommend installing into an isolated environment, e.g., with `uv` / `pipx`:
+
+```sh
+# Install globally with uv tool
+uv tool install python-dmon
+
+# Or with pipx
+pipx install python-dmon
+
+# Add as a dev dependency in your project
+uv add --dev python-dmon
+```
+
+You can also run dmon without installing it permanently:
+
+```sh
+# With uvx (uv tool run)
+uvx python-dmon
+
+# Or with pipx
+pipx run python-dmon
+```
+
+To get the latest features, install from source:
+
+```sh
+pip install git+https://github.com/atomiechen/dmon.git
+```
+
+For coding agents, see the [setup instructions](https://github.com/atomiechen/dmon/blob/main/docs/agent-setup.md) and the
+[portable skill](https://github.com/atomiechen/dmon/blob/main/skills/dmon/SKILL.md). The skill is installed separately from the CLI.
+
+## Getting Started
+
+### Prepare Configuration
+
+Create a `dmon.yaml` file:
+
+```yaml
+tasks:
+  app: ["python", "-u", "server.py"]  # exec form
+  # app: "python -u server.py"        # or a shell string
+```
+
+Without `--config`, dmon searches the current directory and its parents for
+`dmon.yaml`, `dmon.yml`, or `pyproject.toml`. See the
+[configuration reference](https://github.com/atomiechen/dmon/blob/main/docs/configuration.md)
+for TOML, environments, paths, defaults, and log rotation.
+
+### Run tasks
+
+```sh
+dmon start app      # Start in the background
+dmon stop app      # Stop the recorded process tree
+dmon restart app
+dmon status app
+dmon exec app      # Run in this terminal; Ctrl-C ends it
+```
+
+`exec` runs one configured command directly, without registering a managed
+background task. Use `start` to keep it discoverable through `status` and `list`.
+You can pass multiple names to the other task commands. Multi-task `start` is
+best-effort: successful tasks stay running if another fails. For related
+services with ordered startup and rollback, use a stack.
+
+### Run a stack
+
+```yaml
+tasks:
+  api:
+    cmd: [python, api.py]
+    ready:
+      http: http://127.0.0.1:8000/health
+  worker:
+    cmd: [python, worker.py]
+    depends_on: [api]
+stacks:
+  dev: [api, worker]
+```
+
+```sh
+dmon stack up dev          # Foreground; Ctrl-C stops the stack
+# Or keep it running under a background supervisor:
+dmon stack up -d dev
+dmon stack status dev
+dmon stack logs --tail 100 dev
+dmon stack repair dev worker --format json  # Replace an exited member
+dmon stack down dev
+```
+
+Stack startup waits for readiness and rolls back tasks it started if startup
+fails. After startup, an exited member degrades the stack while healthy peers
+keep running. `repair` replaces that member through its live supervisor, so
+later `down` includes the replacement. It reuses the supervisor's launch
+configuration and environment; separately running `dmon start worker` does not
+repair stack membership.
+
+See [task and stack lifecycle](https://github.com/atomiechen/dmon/blob/main/docs/ownership.md)
+for fail-fast behavior, detached restart, recovery, and ownership limits. Docker
+Compose is still appropriate when container behavior itself must be tested.
+
+### Wait for readiness
+
+`dmon wait` checks readiness without starting or stopping anything. Configured
+tasks need a `ready` probe and must already be managed by `start` or a stack:
+
+```sh
+dmon wait api
+dmon wait api --timeout 60 --interval 0.5
+
+# Direct probes need no configuration
+dmon wait --http http://127.0.0.1:8000/health
+dmon wait --tcp 127.0.0.1:5432
+dmon wait --timeout 30 --command -- python healthcheck.py --verbose
+```
+
+Put dmon options before `--command`; the optional second `--` marks the child
+command. See [readiness configuration](https://github.com/atomiechen/dmon/blob/main/docs/configuration.md#readiness)
+for probe options, listener ownership checks, and wait results.
+
+### Run an ad-hoc command
+
+```sh
+dmon run --name myserver python -u server.py
+dmon run --name timer -- python -c 'import time; time.sleep(30)'
+dmon run --shell echo "Hello World"
+dmon run --cwd /path/to/script bash myscript.sh
+```
+
+No configuration is needed. Without `--name`, dmon uses the fixed name
+`default_run` to prevent duplicate runs.
+
+### List recorded tasks and their status
+
+```sh
+dmon list
+dmon status app --format json
+dmon list --format json
+dmon stack status dev --format json
+dmon stack list --format json
+dmon wait api --format json
+```
+
+JSON is written only to stdout; actionable diagnostics remain on stderr. The
+payload has a top-level `ok` field and a `tasks`, `stacks`, or `waits` array.
+Inspection results contain `name`, `ok`, `error`, and an optional `snapshot`;
+wait results contain the target, outcome, reason, elapsed time, and attempt
+count. Existing exit-code semantics are unchanged. Interactive and streaming
+commands do not offer JSON output.
+
+### Python API
+
+The same task lifecycle and inspection logic is available without parsing CLI
+output:
+
+```python
+from dmon import Dmon
+
+client = Dmon(config="dmon.yaml")
+started = client.start("app")
+task = client.status("app")
+stacks = client.list_stacks()
+client.stop("app")
+```
+
+`client.wait("app", timeout=30)` also checks readiness when `app` has a
+configured `ready` probe. API calls are synchronous and silent.
+`start`, `stop`, and `restart` return an immutable `BatchResult`; `status`
+and `stack_status` return `TaskResult` and `StackResult`. List and wait methods
+return tuples of their corresponding result types. Expected runtime states such
+as missing or exited metadata are results, while invalid configuration raises
+`DmonConfigError`. The initial API intentionally does not start a supervised
+stack or create implicit background threads.
+
+## Documentation
+
+Start with the [documentation index](https://github.com/atomiechen/dmon/blob/main/docs/README.md):
+
+- [Configuration](https://github.com/atomiechen/dmon/blob/main/docs/configuration.md): task selection, YAML/TOML, environments, readiness, and logs.
+- [Task and stack lifecycle](https://github.com/atomiechen/dmon/blob/main/docs/ownership.md): startup, repair, recovery, and process ownership.
+- [Coding-agent setup](https://github.com/atomiechen/dmon/blob/main/docs/agent-setup.md): install the workflow and continue across sessions.
+
+## Development
+
+See [CONTRIBUTING.md](https://github.com/atomiechen/dmon/blob/main/CONTRIBUTING.md) for architecture, behavioral contracts,
+validation, and the release workflow. Process, signal, log-rotation, and stack
+changes must also pass the reproducible [manual test lab](https://github.com/atomiechen/dmon/blob/main/tests/manual/README.md).
+
+
+## License
+
+[dmon](https://github.com/atomiechen/dmon) © 2025 by [Atomie CHEN](https://github.com/atomiechen) is licensed under the [MIT License](https://github.com/atomiechen/dmon/blob/main/LICENSE).

python_dmon-0.5.0/README.md

@@ -0,0 +1,266 @@
+# dmon
+
+![dmon — The local process manager for developers and coding agents.](https://raw.githubusercontent.com/atomiechen/dmon/main/assets/banner.svg)
+
+
+[![GitHub](https://img.shields.io/badge/github-dmon-blue?logo=github)](https://github.com/atomiechen/dmon)
+[![PyPI](https://img.shields.io/pypi/v/python--dmon?logo=pypi&logoColor=white)](https://pypi.org/project/python-dmon/)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/atomiechen/dmon)
+
+
+A lightweight, cross-platform process manager for local services and development workflows.
+Run any command as a background *task*, or supervise a stack with readiness checks
+and repair failed members while healthy services keep running. Logging and log
+rotation are built in.
+
+For developers and coding agents, dmon records process identities and exposes
+JSON status so later sessions can inspect and reuse existing services.
+See [coding-agent setup](https://github.com/atomiechen/dmon/blob/main/docs/agent-setup.md).
+
+Shipped as the CLI tool `dmon`.
+
+
+## Features
+
+- 🖥️ **Cross-platform:** Works on Linux, macOS, and Windows.
+- ⚡ **Lightweight:** No daemon service or container runtime required.
+- 🧩 **Flexible tasks:** Tasks can be configured in `pyproject.toml` or `dmon.yaml`; or run ad-hoc commands directly.
+- 🔗 **Supervised stacks:** Start dependent tasks in order, wait for HTTP, TCP,
+  or command readiness, and report runtime degradation.
+- 🌙 **Foreground or detached:** Keep a stack attached for development, or run
+  it under a recoverable background supervisor with `dmon stack up -d` and
+  `dmon stack down`.
+- ⏱️ **Reusable readiness:** Wait for configured tasks or direct HTTP, TCP, and
+  command probes from scripts and deployment workflows.
+- 🪵 **Logging & log rotation:** Keep active log files manageable, with optional archive retention limits.
+
+
+## Demos
+
+The demos below cover everyday task management and supervised stacks. Both use this `dmon.yaml` and a small [heartbeat program](https://github.com/atomiechen/dmon/blob/main/scripts/recording/service.py):
+
+```yaml
+tasks:
+  api: [python, -u, service.py, api]
+  worker: [python, -u, service.py, worker]
+stacks:
+  dev: [api, worker]
+```
+
+**Everyday tasks.** Run a command directly with `run` (no configuration needed),
+then use `start`, `status`, and `stop` for a configured task. `exec` runs a
+configured task in the foreground; Ctrl-C ends it. In this clip, `stop --all`
+stops the sole ad-hoc task before the configured API is started.
+
+![Run an ad-hoc command, manage a configured task, and execute a task in the foreground](https://github.com/user-attachments/assets/2b60acab-d56d-43c0-a44b-f602243c7105)
+
+
+**Keep healthy services running.** Start a stack, deliberately stop its worker,
+and repair that member. The API keeps the same PID and its counter continues;
+`stack down` stops both members. The lower panes show real files and live logs.
+
+![Start a stack, repair only its stopped worker, and clean up both members](https://github.com/user-attachments/assets/58d1a9f9-91d8-4096-9dca-ac53815194c8)
+
+
+
+## Installation
+
+`dmon` requires Python 3.8+ and is available as [`python-dmon`](https://pypi.org/project/python-dmon/) on PyPI.
+Managed commands can use any language.
+
+```sh
+pip install python-dmon
+```
+
+We recommend installing into an isolated environment, e.g., with `uv` / `pipx`:
+
+```sh
+# Install globally with uv tool
+uv tool install python-dmon
+
+# Or with pipx
+pipx install python-dmon
+
+# Add as a dev dependency in your project
+uv add --dev python-dmon
+```
+
+You can also run dmon without installing it permanently:
+
+```sh
+# With uvx (uv tool run)
+uvx python-dmon
+
+# Or with pipx
+pipx run python-dmon
+```
+
+To get the latest features, install from source:
+
+```sh
+pip install git+https://github.com/atomiechen/dmon.git
+```
+
+For coding agents, see the [setup instructions](https://github.com/atomiechen/dmon/blob/main/docs/agent-setup.md) and the
+[portable skill](https://github.com/atomiechen/dmon/blob/main/skills/dmon/SKILL.md). The skill is installed separately from the CLI.
+
+## Getting Started
+
+### Prepare Configuration
+
+Create a `dmon.yaml` file:
+
+```yaml
+tasks:
+  app: ["python", "-u", "server.py"]  # exec form
+  # app: "python -u server.py"        # or a shell string
+```
+
+Without `--config`, dmon searches the current directory and its parents for
+`dmon.yaml`, `dmon.yml`, or `pyproject.toml`. See the
+[configuration reference](https://github.com/atomiechen/dmon/blob/main/docs/configuration.md)
+for TOML, environments, paths, defaults, and log rotation.
+
+### Run tasks
+
+```sh
+dmon start app      # Start in the background
+dmon stop app      # Stop the recorded process tree
+dmon restart app
+dmon status app
+dmon exec app      # Run in this terminal; Ctrl-C ends it
+```
+
+`exec` runs one configured command directly, without registering a managed
+background task. Use `start` to keep it discoverable through `status` and `list`.
+You can pass multiple names to the other task commands. Multi-task `start` is
+best-effort: successful tasks stay running if another fails. For related
+services with ordered startup and rollback, use a stack.
+
+### Run a stack
+
+```yaml
+tasks:
+  api:
+    cmd: [python, api.py]
+    ready:
+      http: http://127.0.0.1:8000/health
+  worker:
+    cmd: [python, worker.py]
+    depends_on: [api]
+stacks:
+  dev: [api, worker]
+```
+
+```sh
+dmon stack up dev          # Foreground; Ctrl-C stops the stack
+# Or keep it running under a background supervisor:
+dmon stack up -d dev
+dmon stack status dev
+dmon stack logs --tail 100 dev
+dmon stack repair dev worker --format json  # Replace an exited member
+dmon stack down dev
+```
+
+Stack startup waits for readiness and rolls back tasks it started if startup
+fails. After startup, an exited member degrades the stack while healthy peers
+keep running. `repair` replaces that member through its live supervisor, so
+later `down` includes the replacement. It reuses the supervisor's launch
+configuration and environment; separately running `dmon start worker` does not
+repair stack membership.
+
+See [task and stack lifecycle](https://github.com/atomiechen/dmon/blob/main/docs/ownership.md)
+for fail-fast behavior, detached restart, recovery, and ownership limits. Docker
+Compose is still appropriate when container behavior itself must be tested.
+
+### Wait for readiness
+
+`dmon wait` checks readiness without starting or stopping anything. Configured
+tasks need a `ready` probe and must already be managed by `start` or a stack:
+
+```sh
+dmon wait api
+dmon wait api --timeout 60 --interval 0.5
+
+# Direct probes need no configuration
+dmon wait --http http://127.0.0.1:8000/health
+dmon wait --tcp 127.0.0.1:5432
+dmon wait --timeout 30 --command -- python healthcheck.py --verbose
+```
+
+Put dmon options before `--command`; the optional second `--` marks the child
+command. See [readiness configuration](https://github.com/atomiechen/dmon/blob/main/docs/configuration.md#readiness)
+for probe options, listener ownership checks, and wait results.
+
+### Run an ad-hoc command
+
+```sh
+dmon run --name myserver python -u server.py
+dmon run --name timer -- python -c 'import time; time.sleep(30)'
+dmon run --shell echo "Hello World"
+dmon run --cwd /path/to/script bash myscript.sh
+```
+
+No configuration is needed. Without `--name`, dmon uses the fixed name
+`default_run` to prevent duplicate runs.
+
+### List recorded tasks and their status
+
+```sh
+dmon list
+dmon status app --format json
+dmon list --format json
+dmon stack status dev --format json
+dmon stack list --format json
+dmon wait api --format json
+```
+
+JSON is written only to stdout; actionable diagnostics remain on stderr. The
+payload has a top-level `ok` field and a `tasks`, `stacks`, or `waits` array.
+Inspection results contain `name`, `ok`, `error`, and an optional `snapshot`;
+wait results contain the target, outcome, reason, elapsed time, and attempt
+count. Existing exit-code semantics are unchanged. Interactive and streaming
+commands do not offer JSON output.
+
+### Python API
+
+The same task lifecycle and inspection logic is available without parsing CLI
+output:
+
+```python
+from dmon import Dmon
+
+client = Dmon(config="dmon.yaml")
+started = client.start("app")
+task = client.status("app")
+stacks = client.list_stacks()
+client.stop("app")
+```
+
+`client.wait("app", timeout=30)` also checks readiness when `app` has a
+configured `ready` probe. API calls are synchronous and silent.
+`start`, `stop`, and `restart` return an immutable `BatchResult`; `status`
+and `stack_status` return `TaskResult` and `StackResult`. List and wait methods
+return tuples of their corresponding result types. Expected runtime states such
+as missing or exited metadata are results, while invalid configuration raises
+`DmonConfigError`. The initial API intentionally does not start a supervised
+stack or create implicit background threads.
+
+## Documentation
+
+Start with the [documentation index](https://github.com/atomiechen/dmon/blob/main/docs/README.md):
+
+- [Configuration](https://github.com/atomiechen/dmon/blob/main/docs/configuration.md): task selection, YAML/TOML, environments, readiness, and logs.
+- [Task and stack lifecycle](https://github.com/atomiechen/dmon/blob/main/docs/ownership.md): startup, repair, recovery, and process ownership.
+- [Coding-agent setup](https://github.com/atomiechen/dmon/blob/main/docs/agent-setup.md): install the workflow and continue across sessions.
+
+## Development
+
+See [CONTRIBUTING.md](https://github.com/atomiechen/dmon/blob/main/CONTRIBUTING.md) for architecture, behavioral contracts,
+validation, and the release workflow. Process, signal, log-rotation, and stack
+changes must also pass the reproducible [manual test lab](https://github.com/atomiechen/dmon/blob/main/tests/manual/README.md).
+
+
+## License
+
+[dmon](https://github.com/atomiechen/dmon) © 2025 by [Atomie CHEN](https://github.com/atomiechen) is licensed under the [MIT License](https://github.com/atomiechen/dmon/blob/main/LICENSE).

{python_dmon-0.4.0 → python_dmon-0.5.0}/pyproject.toml

@@ -1,8 +1,10 @@
 [project]
 name = "python-dmon"
-version = "0.4.0"
-description = "A lightweight, cross-platform daemon manager that runs any command as a background process."
+version = "0.5.0"
+description = "A lightweight, cross-platform process manager for background tasks, local service stacks, and partial recovery."
 readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
 authors = [
     { name = "Atomie CHEN", email = "atomic_cwh@163.com" }
 ]
@@ -15,12 +17,12 @@ dependencies = [
     "termcolor>=2.4.0",
     "tomli>=2.2.1 ; python_full_version < '3.11'",
 ]
-keywords = ["python-dmon", "dmon", "daemon", "background", "detach", "process management"]
+keywords = ["dmon", "process manager", "daemon", "background", "supervisor", "local development", "readiness", "service management", "coding agents"]
 
 [project.urls]
-"Homepage" = "https://github.com/atomiechen/python-dmon"
-"Bug Tracker" = "https://github.com/atomiechen/python-dmon/issues"
-Changelog = "https://github.com/atomiechen/python-dmon/blob/main/CHANGELOG.md"
+"Homepage" = "https://github.com/atomiechen/dmon"
+"Bug Tracker" = "https://github.com/atomiechen/dmon/issues"
+Changelog = "https://github.com/atomiechen/dmon/blob/main/CHANGELOG.md"
 
 [project.scripts]
 dmon = "dmon.__main__:main"