Merge branch 'dev' into copilot/identify-key-areas-for-improvement

Author: Hexagon

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,38 @@
+name: "Copilot Setup Steps"
+
+# Automatically run the setup steps when they are changed to allow for easy validation, and
+# allow manual testing through the repository's "Actions" tab
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+
+    # Set the permissions to the lowest permissions possible needed for your steps.
+    # Copilot will be given its own token for its operations.
+    permissions:
+      # If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission. If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete.
+      contents: read
+
+    # You can define any steps you want, and they will run before the agent starts.
+    # If you do not check out your code, Copilot will do this for you.
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Setup Deno
+        uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+          cache: true
+
+      - name: Cache dependencies
+        run: deno install

.github/workflows/deno.yaml

@@ -12,7 +12,7 @@ jobs:
 
     strategy:
       matrix:
-        deno-version: [1.43.3, "v1.x", "v2.x"]
+        deno-version: ["v2.x"]
 
     steps:
       - name: Git Checkout

AGENTS.md

@@ -0,0 +1,103 @@
+# Agents Guide
+
+This document provides an overview of the Pup repository structure, tools, and development workflow for AI agents and contributors.
+
+## Repository Structure
+
+```
+pup/
+├── lib/                    # Core library code
+│   ├── cli/               # Command-line interface
+│   ├── common/            # Common utilities
+│   ├── core/              # Core process management logic
+│   ├── test/              # Test utilities
+│   ├── types/             # TypeScript type definitions
+│   └── workers/           # Worker scripts
+├── test/                  # Test files
+│   ├── cli/              # CLI tests
+│   └── core/             # Core functionality tests
+├── docs/                  # Documentation (Lume-based site)
+│   └── src/
+│       ├── examples/      # Usage examples
+│       ├── usage/         # Usage guides
+│       └── contributing/  # Contribution guides
+├── tools/                 # Build and development tools
+├── pup.ts                 # Main entry point
+├── mod.ts                 # Library export
+└── deno.json              # Deno configuration and tasks
+```
+
+## Development Tools
+
+Pup is built with Deno. Key commands are defined in `deno.json`:
+
+### Formatting and Linting
+
+```bash
+deno fmt                   # Format code
+deno fmt --check          # Check formatting
+deno lint                 # Lint code
+```
+
+### Testing
+
+```bash
+deno test --allow-read --allow-write --allow-env --allow-net --allow-sys --allow-run --coverage=cov_profile
+```
+
+### Build Tasks
+
+```bash
+deno task check           # Run format, lint, and tests
+deno task build-schema    # Generate JSON schema
+deno task build-versions  # Update version information
+deno task build           # Complete build process
+```
+
+## Pre-commit Checks
+
+The project uses GitHub Actions for CI (`.github/workflows/deno.yaml`):
+
+- Format checking (`deno fmt --check`)
+- Linting (`deno lint`)
+- Full test suite with coverage
+- Runs on: `main` and `dev` branches
+
+Before submitting PRs, run `deno task check` locally to ensure all checks pass.
+
+## Related Projects
+
+Pup is part of an ecosystem of packages available on JSR:
+
+### Core Dependencies
+
+- **[@pup/api-definitions](https://github.com/hexagon/pup-api-definitions)** - API type definitions shared across the ecosystem
+- **[@pup/api-client](https://github.com/hexagon/pup-api-client)** - REST API client for CLI, plugins, and telemetry
+- **[@pup/telemetry](https://github.com/hexagon/pup-telemetry)** - Runtime-agnostic library for process telemetry and IPC
+- **[@pup/common](https://github.com/hexagon/pup-common)** - Common utilities shared across Pup packages
+- **[@pup/plugin](https://github.com/hexagon/pup-plugin)** - Base library for creating Pup plugins
+
+### Official Plugins
+
+- **[pup-plugin-web-interface](https://github.com/hexagon/pup-plugin-web-interface)** - Web-based UI for managing Pup
+
+## Key Concepts
+
+- **Process Management**: Core functionality in `lib/core/`
+- **Configuration**: Uses `pup.json` files (see `docs/src/examples/`)
+- **Service Management**: Cross-platform service installation (sysvinit, systemd, upstart, macOS, Windows)
+- **Telemetry & IPC**: Process monitoring and inter-process communication
+- **Plugins**: Extensible architecture for adding functionality
+
+## Making Changes
+
+1. Fork and create a branch from `dev`
+2. Make minimal, focused changes
+3. Add/update tests in `test/` directory
+4. Run `deno task check` to validate
+5. Update documentation if needed
+6. Submit PR against `dev` branch
+
+## Documentation
+
+Full documentation is available at [pup.56k.guru](https://pup.56k.guru), built from `docs/src/` using Lume.

README.md

@@ -17,7 +17,7 @@ _For detailed documentation, visit [pup.56k.guru](https://pup.56k.guru)._
   your own plugins to add additional features and integrations tailored to your needs.
 - **Process Telemetry and IPC:** Gain deeper insights into managed processes by gathering telemetry data, such as memory usage, from Deno client processes. Supports inter-process communication for
   connected processes to interact with each other.
-- **Rest API:** Control and monitor Pup from third party solutions using the build in Rest API.
+- **Rest API:** Control and monitor Pup from third party solutions using the built-in Rest API.
 
 > **Note**: Programmatic usage, process telemetry, and IPC are currently available only when running Deno client processes.
 
@@ -57,11 +57,11 @@ used below:
 
 4. To make your instance run at boot, enable it using `pup enable-service`.
 
-   Will by default use the instance name for service name, which defaults to `pup`. You can override by passing `-n my-custom-name`.
+   Will by default use the instance name for service name, which defaults to `pup`. You can override by passing `--name my-custom-name`.
 
 5. To stream the logs from a running instance, use the command `pup monitor`. To show historic logs, use `pup logs`.
 
-   Will by default use the instance name for service name, which defaults to `pup`. You can override by passing `-n my-custom-name`.
+   Will by default use the instance name for service name, which defaults to `pup`. You can override by passing `--name my-custom-name`.
 
 For the full manual, see <https://pup.56k.guru>
 
@@ -87,7 +87,7 @@ Full examples available at [/docs/src/examples](/docs/src/examples)
 - `canary`: The canary channel provides the most up-to-date and cutting-edge versions of Pup. It includes the latest changes and may not be as stable as the other channels. It is primarily intended
   for developers and early adopters who want to stay on the bleeding edge of Pup's development. Based on the current state of the `dev` repo of the github repository.
 
-> **Note** Built-in plugins, such as splunk-hec and webinterace does not work with canary versions right now.
+> **Note** Built-in plugins, such as splunk-hec and webinterface do not work with canary versions right now.
 
 Each channel serves different purposes, so choose the one that best fits your needs and requirements.
 

application.meta.ts

@@ -21,12 +21,12 @@
 
 const Application = {
   name: "pup",
-  version: "1.0.4",
+  version: "1.0.5",
   url: "jsr:@pup/pup@$VERSION",
   description: "Powerful universal process manager, designed to keep your scripts, applications and services alive.",
   canary_url: "https://raw.githubusercontent.com/Hexagon/pup/refs/heads/dev/pup.ts",
-  deno: "1.44.0", /* Minimum stable version of Deno required to run Pup (without --unstable-* flags)  */
-  deno_unstable: "1.44.0", /* Minimum version of Deno required to run Pup (with --unstable-* flags) */
+  deno: "2.0.0", /* Minimum stable version of Deno required to run Pup (without --unstable-* flags)  */
+  deno_unstable: "2.0.0", /* Minimum version of Deno required to run Pup (with --unstable-* flags) */
   repository: "https://github.com/hexagon/pup",
   changelog: "https://hexagon.github.io/pup/changelog.html",
   permissions: [

deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@pup/pup",
-  "version": "1.0.4",
+  "version": "1.0.5-dev.0",
 
   "exports": {
     ".": "./pup.ts",
@@ -14,7 +14,7 @@
   },
 
   "lint": {
-    "exclude": ["cov_profile", "docs/_site"],
+    "exclude": ["cov_profile", "docs/_site", "docs/src/examples/**", "tools/"],
     "rules": {
       "exclude": ["verbatim-module-syntax", "no-node-globals"]
     }
@@ -37,28 +37,29 @@
 
   "imports": {
     "@cross/deepmerge": "jsr:@cross/deepmerge@~1.0.0",
-    "@cross/env": "jsr:@cross/env@~1.0.2",
-    "@cross/fs": "jsr:@cross/fs@~0.1.11",
-    "@cross/jwt": "jsr:@cross/jwt@~0.5.0",
-    "@cross/kv": "jsr:@cross/kv@~0.17.1",
-    "@cross/runtime": "jsr:@cross/runtime@~1.1.0",
-    "@cross/service": "jsr:@cross/service@^1.0.6",
-    "@cross/test": "jsr:@cross/test@~0.0.9",
+    "@cross/env": "jsr:@cross/env@~1.0.3",
+    "@cross/fs": "jsr:@cross/fs@~0.1.13",
+    "@cross/jwt": "jsr:@cross/jwt@~0.6.0",
+    "@cross/kv": "jsr:@cross/kv@~0.17.4",
+    "@cross/runtime": "jsr:@cross/runtime@~1.2.1",
+    "@cross/service": "jsr:@cross/service@^1.0.7",
+    "@cross/test": "jsr:@cross/test@~0.0.10",
     "@cross/utils": "jsr:@cross/utils@^0.16.0",
-    "@hexagon/croner": "jsr:@hexagon/croner@~9.0.0",
-    "@oak/oak": "jsr:@oak/oak@^17.0.0",
+    "@hexagon/croner": "jsr:@hexagon/croner@~9.1.0",
+    "@oak/oak": "jsr:@oak/oak@^17.1.6",
     "@pup/api-client": "jsr:@pup/api-client@~2.0.0",
     "@pup/api-definitions": "jsr:@pup/api-definitions@~2.0.0",
     "@pup/common": "jsr:@pup/common@~1.0.3",
     "@pup/plugin": "jsr:@pup/plugin@~1.0.1",
-    "@std/assert": "jsr:@std/assert@~1.0.0",
-    "@std/async": "jsr:@std/async@~1.0.0",
-    "@std/encoding": "jsr:@std/encoding@~1.0.0",
-    "@std/io": "jsr:@std/io@~0.224.0",
-    "@std/path": "jsr:@std/path@~1.0.1",
-    "@std/semver": "jsr:@std/semver@^1.0.3",
-    "dax-sh": "npm:dax-sh@~0.42.0",
-    "filesize": "npm:filesize@~10.1.1",
+    "@std/assert": "jsr:@std/assert@~1.0.15",
+    "@std/async": "jsr:@std/async@~1.0.15",
+    "@std/encoding": "jsr:@std/encoding@~1.0.10",
+    "@std/io": "jsr:@std/io@~0.225.2",
+    "@std/path": "jsr:@std/path@~1.1.2",
+    "@std/semver": "jsr:@std/semver@^1.0.6",
+    "@std/streams": "jsr:@std/streams@~1.0.12",
+    "dax-sh": "npm:dax-sh@~0.43.2",
+    "filesize": "npm:filesize@~11.0.13",
     "json5": "npm:json5@~2.2.3",
     "timeago.js": "npm:timeago.js@~4.0.2",
     "zod": "npm:zod@~3.23.6",

docs/deno.json

@@ -5,7 +5,7 @@
     "serve": "deno task lume -s --port=8000"
   },
   "imports": {
-    "lume/": "https://deno.land/x/lume@v1.19.1/",
-    "lumocs/": "https://deno.land/x/lumocs@0.0.25/"
+    "lume/": "https://deno.land/x/lume@v3.1.1/",
+    "lumocs/": "https://deno.land/x/lumocs@0.2.0/"
   }
 }

docs/src/changelog.md

@@ -9,6 +9,10 @@ nav_order: 13
 
 All notable changes to this project will be documented in this section.
 
+## [Unreleased]
+
+- feat(core): Add exponential backoff for process restarts via `restartBackoffMs` configuration option to prevent rapid restart loops
+
 ## [1.0.4] - 2024-11-19
 
 - fix(core): Fix service auto start after install on Windows by upgrading dependency @cross/service
@@ -44,7 +48,7 @@ This release marks the initial stable release of Pup - a powerful universal proc
   your own plugins to add additional features and integrations tailored to your needs.
 - **Process Telemetry and IPC:** Gain deeper insights into managed processes by gathering telemetry data, such as memory usage, from Deno client processes. Supports inter-process communication for
   connected processes to interact with each other.
-- **Rest API:** Control and monitor Pup from third party solutions using the build in Rest API.
+- **Rest API:** Control and monitor Pup from third party solutions using the built-in Rest API.
 
 _For detailed documentation, visit [pup.56k.guru](https://pup.56k.guru)._
 

docs/src/examples/max-restarts/README.md

@@ -0,0 +1,76 @@
+# Max Restarts and Exponential Backoff Example
+
+This example demonstrates how to configure restart limits and exponential backoff for processes that may fail.
+
+## Overview
+
+The configuration shows two processes:
+
+1. **max-3-times**: Uses a fixed restart delay of 3 seconds and allows up to 3 restarts
+2. **with-exponential-backoff**: Uses exponential backoff starting at 1 second and capping at 30 seconds, allowing up to 5 restarts
+
+## How Exponential Backoff Works
+
+When a process fails repeatedly, exponential backoff prevents rapid restart loops by increasing the delay between each restart attempt:
+
+- **1st restart**: 1 second delay (restartDelayMs)
+- **2nd restart**: 2 seconds delay (1s × 2¹)
+- **3rd restart**: 4 seconds delay (1s × 2²)
+- **4th restart**: 8 seconds delay (1s × 2³)
+- **5th restart**: 16 seconds delay (1s × 2⁴)
+- **Further restarts**: 30 seconds delay (capped at restartBackoffMs)
+
+This approach:
+
+- Gives transient issues time to resolve
+- Prevents resource exhaustion from rapid restart loops
+- Allows more restart attempts while being system-friendly
+
+## Running the Example
+
+```bash
+pup run
+```
+
+The `server.js` script exits immediately, so both processes will restart according to their configured policies until they reach their restart limits.
+
+## Configuration
+
+```jsonc
+{
+  "processes": [
+    {
+      "id": "max-3-times",
+      "cmd": "deno run server.js",
+      "autostart": true,
+      "restart": "always",
+      "restartLimit": 3,
+      "restartDelayMs": 3000
+    },
+    {
+      "id": "with-exponential-backoff",
+      "cmd": "deno run server.js",
+      "autostart": true,
+      "restart": "always",
+      "restartLimit": 5,
+      "restartDelayMs": 1000,
+      "restartBackoffMs": 30000
+    }
+  ]
+}
+```
+
+## When to Use Exponential Backoff
+
+Exponential backoff is particularly useful for:
+
+- Services that may experience temporary network issues
+- Processes that depend on external resources (databases, APIs)
+- Applications that might fail during deployment or updates
+- Any process where rapid restart loops could cause problems
+
+## Notes
+
+- If `restartBackoffMs` is not set, the process will use a fixed `restartDelayMs` between all restarts
+- The backoff resets when the process exits successfully (status: FINISHED) or is manually stopped
+- Combined with `restartLimit`, exponential backoff provides robust process recovery while preventing runaway restart loops

docs/src/examples/max-restarts/pup.jsonc

@@ -7,6 +7,15 @@
       "restart": "always",
       "restartLimit": 3,
       "restartDelayMs": 3000
+    },
+    {
+      "id": "with-exponential-backoff",
+      "cmd": "deno run server.js",
+      "autostart": true,
+      "restart": "always",
+      "restartLimit": 5,
+      "restartDelayMs": 1000,
+      "restartBackoffMs": 30000
     }
   ]
 }