@partoska/dpal 0.0.0-stage → 1.3.0

package/README.md

@@ -1,3 +1,161 @@
-# Temporary Holding Version
+# @partoska/dpal
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Daemon Pal — a compact user-space tool for process management. Supervise,
+restart, and persist long-running processes from your terminal.
+
+[![npm version](https://img.shields.io/npm/v/@partoska/dpal.svg)](https://www.npmjs.com/package/@partoska/dpal)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/partoska/dpal/blob/main/LICENSE.txt)
+
+## What is this?
+
+`dpal` runs in two modes:
+
+- **Control process** (`dpal -C`) — a small daemon that owns and supervises
+  your processes, restarting them as configured.
+- **Command executor** (default) — a short-lived client that tells a running
+  control process what to do: add, start, stop, restart, list, delete,
+  import/export, or persist processes.
+
+**Key features:**
+
+- Process lifecycle management with automatic startup and restarts.
+- Process persistence across control process restarts.
+- Individual and batch (`-a`) process control.
+- Import/export of process lists via INI files.
+- Per-process memory limits, log rotation, and restart intervals.
+- Isolated working directories, so multiple control processes can coexist.
+- Works on macOS and Linux, including Raspberry Pi (arm64 and armhf).
+
+## Install
+
+```bash
+npm install -g @partoska/dpal
+```
+
+This installs a small launcher plus the prebuilt native binary for your
+platform, selected automatically. No compiler or build tools are required — see
+[How this package works](#how-this-package-works) for the details.
+
+### Supported platforms
+
+| OS    | Architectures                                 |
+| ----- | --------------------------------------------- |
+| macOS | Intel & Apple Silicon                         |
+| Linux | x64, arm64, armhf (ARMv6+, e.g. Raspberry Pi) |
+
+Windows is not supported (dpal relies on POSIX process control and SysV IPC).
+
+## Quick Start
+
+```bash
+dpal -C -a &                              # Start the control process.
+dpal -c /usr/bin/python3 -m http.server   # Add a process.
+dpal -l -a                                # List all processes.
+dpal -s python3                           # Start it by name.
+dpal -p                                   # Persist the list for next time.
+dpal -k                                   # Shut the control process down.
+```
+
+Run `dpal -h` at any time for full usage.
+
+## Usage
+
+### Control process mode
+
+```bash
+dpal -C [-D workdir] [-f] [-i procs.ini] [-a]
+```
+
+| Flag | Long           | Meaning                                                |
+| ---- | -------------- | ------------------------------------------------------ |
+| `-C` | `--control`    | Start the control process.                             |
+| `-D` | `--dir`        | Working directory for this control process.            |
+| `-f` | `--force`      | Start even if another one holds the workdir (recovery).|
+| `-i` | `--ini`        | Load a process list from an INI file at startup.       |
+| `-a` | `--auto-start` | Automatically start every process in the list.         |
+
+### Command executor mode
+
+```bash
+dpal [-D workdir] [-f] COMMAND [NAME|ID ...|-a]
+```
+
+| Flag | Long        | Meaning                                              |
+| ---- | ----------- | ---------------------------------------------------- |
+| `-l` | `--list`    | List processes.                                      |
+| `-s` | `--start`   | Start process(es).                                   |
+| `-t` | `--stop`    | Stop process(es) (SIGTERM).                          |
+| `-r` | `--restart` | Stop and start process(es).                          |
+| `-c` | `--create`  | Add a process from `EXEC [args...]`.                 |
+| `-d` | `--delete`  | Remove process(es) from the list.                    |
+| `-i` | `--import`  | Import a process list from an INI file.              |
+| `-e` | `--export`  | Export the process list to an INI file.              |
+| `-p` | `--persist` | Save the current list so it reloads on next start.   |
+| `-k` | `--kill`    | Shut down the control process and all its processes. |
+
+## Configuration
+
+The working directory is resolved in this order: `-D/--dir`, `$DPAL_HOME`,
+`$HOME/.dpal`, then the current directory. Use the same `-D` for the control
+process and every command aimed at it.
+
+Process lists use a simple INI format:
+
+```ini
+[web]
+App=/usr/bin/python3
+Dir=/srv/www
+Arg=python3
+Arg=-m
+Arg=http.server
+; Restart 5 seconds after the process exits.
+RestartSec=5
+; Rotate logs at 1 MiB, keeping 3 rotated files.
+LogMaxSize=1048576
+LogRotation=3
+```
+
+## How this package works
+
+`@partoska/dpal` follows the per-platform `optionalDependencies` model. The
+package you install ships only a tiny Node launcher; the actual native binary
+comes from one of these platform packages, and npm installs only the one
+matching your OS and CPU:
+
+- `@partoska/dpal-darwin` — macOS universal (Intel + Apple Silicon)
+- `@partoska/dpal-linux-x64`
+- `@partoska/dpal-linux-arm64`
+- `@partoska/dpal-linux-arm` — armhf (ARMv6+), e.g. 32-bit Raspberry Pi OS
+
+When you run `dpal`, the launcher resolves the matching binary and, on Node
+22.15 or newer, replaces itself with it (`execve`), so the control process
+owns its PID and receives signals directly. On older Node versions it runs
+the binary as a child, forwarding signals and the exit status.
+
+## Troubleshooting
+
+### "Unsupported platform" or "could not find the native binary"
+
+This usually means optional dependencies were skipped during install (for
+example with `npm install --omit=optional`, or behind a strict CI mirror).
+Reinstall with optional dependencies enabled:
+
+```bash
+npm install -g @partoska/dpal
+```
+
+### "No control process is running"
+
+Executor commands talk to the control process bound to the working directory.
+Make sure one is running (`dpal -C &`) and that both use the same `-D` or
+`$DPAL_HOME`.
+
+## License
+
+MIT. Copyright (C) 2024 Fabrika Charvat s.r.o. Developed by the
+[Partoska Laboratory](https://lab.partoska.com) team.
+
+## Links
+
+- **Project website:** <https://lab.partoska.com/dpal>
+- **Source & issues:** <https://github.com/partoska/dpal>

package/bin/dpal.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+/*
+ * Daemon Pal - Compact user-space tool/library for process management.
+ * Copyright (C) 2024 Fabrika Charvat s.r.o. All rights reserved.
+ * Developed by Partoska Laboratory team, <https://lab.partoska.com>
+ *
+ * MIT License
+ *
+ * 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.
+ *
+ * You can contact the author(s) via email at ask <at> partoska.com.
+ */
+
+"use strict";
+
+const { spawn } = require("child_process");
+
+// Map `${process.platform}-${process.arch}` to the package + relative binary.
+const TARGETS = {
+  "darwin-x64": ["@partoska/dpal-darwin", "bin/dpal"],
+  "darwin-arm64": ["@partoska/dpal-darwin", "bin/dpal"],
+  "linux-x64": ["@partoska/dpal-linux-x64", "bin/dpal"],
+  "linux-arm64": ["@partoska/dpal-linux-arm64", "bin/dpal"],
+  "linux-arm": ["@partoska/dpal-linux-arm", "bin/dpal"],
+};
+
+const key = `${process.platform}-${process.arch}`;
+const target = TARGETS[key];
+if (!target) {
+  console.error(
+    `dpal: unsupported platform/architecture "${key}".\n` +
+      `Supported: ${Object.keys(TARGETS).join(", ")}.`,
+  );
+  process.exit(1);
+}
+
+const [pkg, relPath] = target;
+let binary;
+try {
+  binary = require.resolve(`${pkg}/${relPath}`);
+} catch {
+  console.error(
+    `dpal: could not find the native binary for "${key}".\n` +
+      `The optional dependency "${pkg}" does not seem to be installed.\n` +
+      `Try reinstalling dpal (e.g. "npm install -g @partoska/dpal"), and make\n` +
+      `sure optional dependencies are not disabled.`,
+  );
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+
+// Prefer replacing this Node process with the native binary (Node >= 22.15).
+// The control process (`dpal -C`) is long-lived, so it should own the PID and
+// receive signals directly rather than sit behind a Node wrapper.
+if (typeof process.execve === "function") {
+  try {
+    process.execve(binary, [binary, ...args], process.env);
+  } catch (err) {
+    // Fall through to the spawn-based launcher below.
+  }
+}
+
+const child = spawn(binary, args, { stdio: "inherit" });
+
+// Forward termination signals so the wrapper behaves like the binary itself.
+for (const sig of ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT", "SIGUSR1", "SIGUSR2"]) {
+  process.on(sig, () => {
+    if (child.exitCode === null && child.signalCode === null) {
+      child.kill(sig);
+    }
+  });
+}
+
+child.on("error", (err) => {
+  console.error(`dpal: failed to launch native binary: ${err.message}`);
+  process.exit(1);
+});
+
+// Mirror the child's exit.
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.removeAllListeners(signal);
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code === null ? 1 : code);
+  }
+});

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@partoska/dpal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.3.0",
+  "description": "Compact user-space tool for process management — supervise, restart, and persist long-running processes.",
+  "bin": {
+    "dpal": "bin/dpal.js"
+  },
+  "files": [
+    "bin/",
+    "README.md"
+  ],
+  "optionalDependencies": {
+    "@partoska/dpal-darwin": "1.3.0",
+    "@partoska/dpal-linux-x64": "1.3.0",
+    "@partoska/dpal-linux-arm64": "1.3.0",
+    "@partoska/dpal-linux-arm": "1.3.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/partoska/dpal.git"
+  },
+  "homepage": "https://lab.partoska.com/dpal",
+  "bugs": {
+    "url": "https://github.com/partoska/dpal/issues"
+  },
+  "license": "MIT",
+  "keywords": [
+    "process",
+    "supervisor",
+    "daemon",
+    "process-manager",
+    "cli",
+    "raspberry-pi"
+  ]
+}