unitup 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unitup contributors
+
+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 A PARTICULAR PURPOSE AND 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.

package/README.md

@@ -0,0 +1,387 @@
+# unitup
+
+> Minimal, zero-dependency Node.js CLI & library to run Node.js scripts as `systemd` user services.
+
+`unitup` provides a thin, user-level layer over Linux `systemd`. It does **not** create a custom daemon, manage process trees, or act as a PM2 alternative. Instead, it generates and manages native systemd user units (`~/.config/systemd/user/unitup-<name>.service`), letting systemd handle process supervision, auto-restarts, logging, and OS boot startup without requiring `sudo` privileges.
+
+---
+
+## `unitup` vs PM2: Key Differences and Core Promises
+
+`unitup` is **not** a PM2 replacement or an independent process manager. While PM2 runs its own master daemon, `unitup` is strictly a thin and transparent CLI layer on top of Linux `systemd`.
+
+### Comparison Table
+
+| Feature | `unitup` | PM2 |
+| :--- | :--- | :--- |
+| **Background Process (Daemon)** | **None** (0 MB RAM). Systemd directly supervises processes. | **Yes** (PM2 master daemon consumes ~50-100 MB RAM in background). |
+| **System Integration** | Native Linux OS `systemd` user service (`~/.config/systemd/user/`). | Custom process monitoring via PM2's internal daemon. |
+| **Privileges Required** | Does **not** require `sudo`. | Requires `sudo` / `pm2 startup` for boot startup configuration. |
+| **Dependencies** | **0 Runtime Dependencies** (Uses Node.js standard modules only). | Dozens of 3rd party npm packages. |
+| **Log Management** | Delegates to native Linux `journald` system (`journalctl`). | Manages `.pm2/logs` files (requires `pm2-logrotate` for rotation). |
+| **Boot Startup** | Native systemd lingering (`loginctl enable-linger`). | Custom startup script launching PM2 daemon. |
+
+---
+
+### What `unitup` Promises (Core Promises)
+
+1. ⚡ **Zero Memory & CPU Waste**: After running `unitup` commands to add or manage a service, `unitup` exits immediately. No extra Node.js master process stays running in the background.
+2. 🔒 **100% Transparency & Safety**: No hidden background tasks. Generated `.service` files are saved as standard text at `~/.config/systemd/user/` for easy inspection. 100% safe against shell injection.
+3. 🛠️ **Automatic Path & Environment Resolution**: Automatically detects `PATH` issues common with NVM, FNM, or custom Node.js installations and injects the resolved `PATH` environment into the unit file.
+4. 🪶 **Ultra Lightweight Footprint**: Zero bloat for your project or server; installs instantly and runs with minimal overhead.
+
+### What `unitup` Does NOT Do (Non-Goals)
+
+- ❌ Does not write a custom daemon or process watcher system (does not attempt to behave like PM2).
+- ❌ No PM2 Cluster Mode (internal load balancing). Use Nginx, HAProxy, or Node.js native `cluster` module instead.
+- ❌ No web dashboard, metrics panel, or telemetry.
+- ❌ Does not manage or rotate log files directly; delegates 100% of logging to OS-level `journald`.
+
+---
+
+## Features
+
+- ⚡ **Zero runtime dependencies** — ultra lightweight native ESM Node 20+ package.
+- 🔒 **No root / sudo required** — operates entirely within systemd user scope (`~/.config/systemd/user/`).
+- 🛡️ **Secure by design** — systemd escaping, strict service name sanitization, and shell-injection safe command execution (`execFile`/`spawn` with `shell: false`).
+- 🩺 **System readiness check** — `unitup doctor` verifies OS, systemd PID 1, systemctl user bus, and user lingering state.
+- 📋 **Compact status & logs** — clean summary output from `systemctl show` and live `journalctl` streaming.
+- 📦 **Programmatic API** — imported directly into JavaScript applications.
+
+---
+
+## Requirements
+
+- **OS:** Linux with `systemd`
+- **Node.js:** `>= 20.0.0`
+- **Permissions:** Standard non-root user session
+
+---
+
+## Installation
+
+```bash
+npm install -g unitup
+```
+
+Or install locally in your project:
+
+```bash
+npm install unitup
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Verify system readiness
+unitup doctor
+
+# 2. Add your Node.js script as a user service and start it immediately
+unitup add server.js --name api --env-file .env --start
+
+# 3. Check service status
+unitup status api
+
+# 4. Stream real-time journalctl logs
+unitup logs api --follow
+
+# 5. Stop or remove service when no longer needed
+unitup stop api
+unitup remove api
+```
+
+---
+
+## CLI Commands
+
+### `unitup doctor`
+
+Performs comprehensive system and Node.js runtime diagnostic checks:
+- OS check (Linux)
+- `systemctl` executable availability
+- PID 1 systemd verification
+- Systemd user bus accessibility
+- Node.js executable PATH resolution (`which node`, `command -v`, `process.execPath`)
+- Node.js binary execution capability (`node -v`)
+- Unit directory write permissions (`~/.config/systemd/user/`)
+- User lingering state (`loginctl enable-linger`)
+
+Example output:
+```text
+unitup doctor
+
+✓ Linux detected
+✓ systemctl available
+✓ systemd is running
+✓ systemd user services available
+✓ Node.js: /usr/bin/node
+✓ Node version: v20.11.0
+✓ PATH includes node
+! User lingering is disabled
+
+User lingering is disabled.
+The service may stop after logout.
+
+Enable it manually:
+  loginctl enable-linger username
+```
+
+---
+
+### Diagnosing Node.js Runtime & Path Problems
+
+`unitup` automatically detects and diagnoses Node.js installation issues before creating services.
+
+#### 1. Node.js not found in PATH
+```text
+✗ Node.js not found in PATH
+
+Install Node.js:
+  https://nodejs.org
+or via package manager:
+  sudo apt install nodejs
+```
+
+#### 2. Node.js binary exists but is not executable
+```text
+✗ Node.js binary exists but is not executable
+
+Check permissions:
+  chmod +x $(which node)
+```
+
+#### 3. Resolving custom or nvm Node.js executable paths
+Systemd services execute in a minimal environment. To ensure systemd finds `node` regardless of user PATH setup (nvm, fnm, etc.), `unitup` resolves absolute paths and automatically injects a `PATH` environment directive into every generated unit file:
+
+```ini
+[Service]
+Type=simple
+WorkingDirectory=/home/user/projects/app
+Environment=PATH="/home/user/.nvm/versions/node/v20.11.0/bin:/usr/local/bin:/usr/bin:/bin"
+ExecStart=/home/user/.nvm/versions/node/v20.11.0/bin/node /home/user/projects/app/server.js
+```
+
+You can also specify an explicit Node.js binary path when creating a service:
+
+```bash
+unitup add app.js --node /usr/bin/node
+```
+
+If Node.js cannot be resolved, `unitup add` will safely abort and request that you run `unitup doctor`.
+
+---
+
+### `unitup add <script>`
+
+Creates a new systemd user service unit file at `~/.config/systemd/user/unitup-<name>.service`.
+
+```bash
+unitup add app.js
+unitup add server.js --name api --env NODE_ENV=production --env PORT=3000 --start
+```
+
+**Options:**
+- `--name <name>`: Custom service name (defaults to script file name without extension).
+- `--node <path>`: Explicit Node.js executable path.
+- `--cwd <path>`: Working directory (defaults to script directory).
+- `--env KEY=value`: Pass environment variable (can be specified multiple times).
+- `--env-file <file>`: Absolute or relative path to environment file (adds `EnvironmentFile=...`).
+- `--restart <policy>`: Systemd restart policy (`on-failure`, `always`, `no`, `on-abnormal`, etc. Default: `on-failure`).
+- `--arg <value>`: Script positional arguments (can be specified multiple times).
+- `--start`: Automatically enables and starts the service immediately (`systemctl --user enable --now`).
+
+Generated unit file example (`~/.config/systemd/user/unitup-api.service`):
+
+```ini
+[Unit]
+Description=unitup service: api
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=/home/user/projects/app
+ExecStart=/usr/bin/node /home/user/projects/app/server.js
+Restart=on-failure
+RestartSec=3
+EnvironmentFile=/home/user/projects/app/.env
+Environment=PATH="/usr/bin:/usr/local/bin:/bin"
+Environment=NODE_ENV="production"
+Environment=PORT="3000"
+
+[Install]
+WantedBy=default.target
+```
+
+---
+
+### `unitup start <name>`
+
+Starts an existing service unit.
+
+```bash
+unitup start api
+```
+
+Pass `--enable` to enable the service to start automatically on system boot:
+
+```bash
+unitup start api --enable
+```
+
+---
+
+### `unitup stop <name>`
+
+Stops a running service:
+
+```bash
+unitup stop api
+```
+
+---
+
+### `unitup restart <name>`
+
+Restarts a service:
+
+```bash
+unitup restart api
+```
+
+---
+
+### `unitup status <name>`
+
+Shows a compact status summary for the service:
+
+```text
+api
+
+Status: running
+PID: 14220
+Started: 12 minutes ago
+Restarts: 0
+Script: /home/user/projects/app/server.js
+Working directory: /home/user/projects/app
+```
+
+To view systemctl's raw output, pass `--raw`:
+
+```bash
+unitup status api --raw
+```
+
+---
+
+### `unitup logs <name>`
+
+Displays logs collected by systemd's `journalctl`.
+
+```bash
+# View last 100 log lines (default)
+unitup logs api
+
+# Specify number of lines
+unitup logs api --lines 30
+
+# Live follow/stream mode
+unitup logs api --follow
+```
+
+---
+
+### `unitup list`
+
+Lists all user services managed by `unitup` (`unitup-*.service`):
+
+```text
+NAME       STATUS     ENABLED
+api        running    yes
+worker     stopped    yes
+cleanup    failed     no
+```
+
+---
+
+### `unitup remove <name>`
+
+Stops, disables, and deletes the unit file, then reloads systemd:
+
+```bash
+unitup remove api
+```
+
+Equivalent systemctl commands executed:
+1. `systemctl --user disable --now unitup-api.service`
+2. Remove `~/.config/systemd/user/unitup-api.service`
+3. `systemctl --user daemon-reload`
+4. `systemctl --user reset-failed`
+
+---
+
+## User Lingering & Persistence Across Logout
+
+By default, Linux systemd terminates user processes when a user logs out. To allow your Node.js services to run continuously in the background after logout or system startup, enable **user lingering**:
+
+```bash
+loginctl enable-linger $USER
+```
+
+`unitup` checks this state in `unitup doctor` and warns if lingering is disabled. `unitup` will never attempt to run `loginctl` or `sudo` automatically on your behalf.
+
+---
+
+## Programmatic JavaScript & TypeScript API
+
+`unitup` includes full TypeScript declaration files (`index.d.ts`). You can import `unitup` directly into JavaScript or TypeScript applications:
+
+```ts
+import {
+  createService,
+  startService,
+  stopService,
+  restartService,
+  removeService,
+  getServiceStatus,
+  listServices,
+  isSystemdAvailable,
+  CreateServiceOptions,
+  ServiceStatus
+} from "unitup";
+
+// Check if systemd user services are available
+if (await isSystemdAvailable()) {
+  const options: CreateServiceOptions = {
+    name: "api",
+    script: "./server.js",
+    cwd: process.cwd(),
+    env: {
+      NODE_ENV: "production",
+      PORT: "3000"
+    },
+    restart: "on-failure"
+  };
+
+  // Add a service
+  await createService(options);
+
+  // Start the service
+  await startService("api");
+
+  // Get compact status
+  const status: ServiceStatus = await getServiceStatus("api");
+  console.log(`Service PID: ${status.pid}, Status: ${status.status}`);
+
+  // List all unitup services
+  const services = await listServices();
+  console.log(services);
+}
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

package/bin/unitup.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli.js';
+
+runCli();