unitup 0.0.9 → 0.0.10

package/README.md

@@ -1,12 +1,25 @@
 # unitup
 
-> Minimal, zero-dependency Node.js CLI & library to run Node.js scripts as `systemd` user services.
+> Minimal, zero-dependency CLI & library to run Node.js, Python, Ruby, PHP, Bun, Deno, Go, Elixir, Shell scripts, and native binaries 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.
 
+```bash
+# Quick Start
+npm install -g unitup
+
+unitup add server.js --start
+unitup status server
+unitup logs server --follow
+
+# Multi-runtime & Native Executables
+unitup add worker.py --runtime python --start
+unitup add ./server --runtime native --name api --start
+```
+
 ---
 
-## `unitup` vs PM2: Key Differences and Core Promises
+## unitup vs PM2
 
 `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`.
 
@@ -14,39 +27,109 @@
 
 | 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). |
+| **Background Process (Daemon)** | **No resident unitup daemon**. Systemd directly supervises processes. | **Runs a persistent process-management daemon**. |
 | **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. |
+| **Multi-Runtime & Executable Support** | **Node.js, Python, Ruby, PHP, Bun, Deno, Go, Elixir, Shell, and native binaries** out of the box. | **Node.js-focused process manager with support for running other commands**. |
+| **Privileges Required** | Does **not** require `sudo`. | Boot integration commonly requires running the PM2 startup setup command with elevated privileges. |
 | **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)
+### Core Architecture
+
+At its core, `unitup` generates systemd service unit files directly from a generic `command + args` model rather than being hardcoded to Node.js:
+
+```js
+{
+  command: "/usr/bin/python3",
+  args: ["/home/user/apps/worker.py"],
+  cwd: "/home/user/apps",
+  env: {
+    APP_ENV: "production"
+  }
+}
+```
+
+### 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.
+1. ⚡ **No persistent unitup CPU or memory overhead**: After running `unitup` commands, `unitup` exits immediately. No extra master process stays running in the background.
+2. 🌐 **Language-Agnostic & Executable Ready**: Works out of the box with Node.js, Python, Ruby, PHP, Bun, Deno, Go, Elixir, Shell scripts, or compiled native binaries.
+3. 🔒 **Transparent systemd-native configuration**: Avoids shell execution and validates generated unit arguments (`shell: false`). Generated `.service` files are saved as standard text at `~/.config/systemd/user/`.
+4. 🛠️ **Automatic Absolute Path & PATH Resolution**: Resolves absolute binary and script paths, automatically injecting proper `PATH` environment into unit files.
+5. 🔄 **Backward Compatible**: Full support for existing Node.js projects, legacy CLI parameters, and old metadata formats (`{ node, script }`).
 
-### 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`.
+## Supported Runtimes
+
+- **Node.js**: `.js`, `.mjs`, `.cjs`
+- **Python**: `.py` (resolves `python3` then `python`)
+- **Ruby**: `.rb` (`ruby`)
+- **PHP**: `.php` (`php`)
+- **Bun**: `bun`
+- **Deno**: `deno` (default command: `deno run <script>`)
+- **Go**: `.go` (`go run <script>`)
+- **Elixir**: `.ex`, `.exs` (`elixir <script>`)
+- **Shell Scripts**: `.sh` (`bash`, `sh`)
+- **Native Executables**: `./server` (compiled Go, Rust, C/C++, etc.)
 
 ---
 
 ## 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.
+- ⚡ **Zero runtime dependencies** — lightweight, ESM-first package with CommonJS support.
+- 🔒 **No sudo required for normal service creation and management** — operates entirely within systemd user scope (`~/.config/systemd/user/`).
+- 🛡️ **Secure by design** — avoids shell-based command execution, validates service names, escapes systemd arguments, and sanitizes input to prevent shell injection.
+- 🧠 **Systemd-Native Memory Limits** — Configure `MemoryHigh`, `MemoryMax`, and `MemorySwapMax` per service without extra monitoring daemons.
+- 📜 **Journald Log Maintenance** — Advanced log streaming with filters (`--since`, `--until`, `--priority`, `--grep`, `--boot`, `--json`) and journal maintenance (`disk-usage`, `rotate`, `vacuum`).
+- 🩺 **System readiness & runtime check** — `unitup doctor` verifies OS, systemd PID 1, systemctl user bus, cgroup v2 memory controller support, user lingering, and detected runtimes.
 - 📋 **Compact status & logs** — clean summary output from `systemctl show` and live `journalctl` streaming.
-- 📦 **Programmatic API** — imported directly into JavaScript applications.
+- 📦 **Programmatic API** — imported directly into JavaScript and TypeScript applications.
+
+---
+
+## CLI Usage
+
+### Memory Limits
+
+`unitup` allows you to set native systemd memory limits for your services without running background monitoring daemons:
+
+```bash
+# Add a service with memory limits
+unitup add server.js \
+  --memory-high 400M \
+  --memory-max 512M \
+  --swap-max 256M
+
+# Update limits on an existing service
+unitup limits api --memory-high 400M --memory-max 512M
+
+# Reset memory limits back to system defaults
+unitup limits api --reset-memory
+```
+
+*Supported size units:* `128K`, `256M`, `1G`, `infinity`, `max`, or raw byte integers.
+
+### Journald Log Maintenance
+
+```bash
+# Filter logs by time, priority, grep keyword, boot, or JSON output
+unitup logs api --since 1h --until now
+unitup logs api --priority err --grep "timeout"
+unitup logs api --boot --json
+
+# Journal storage maintenance
+unitup journal disk-usage
+unitup journal rotate
+unitup journal vacuum --size 500M
+unitup journal vacuum --time 14d
+unitup journal vacuum --files 10 --yes
+```
+
+> [!NOTE]
+> `unitup journal vacuum` prompts for user confirmation before executing system-wide log cleanup unless `--yes` / `-y` or `--dry-run` is provided. If permissions are insufficient, `unitup` handles it gracefully without executing `sudo`.
 
 ---
 
@@ -72,155 +155,195 @@ npm install unitup
 
 ---
 
-## Quick Start
+## CLI Usage
+
+### Multi-Runtime Examples
 
 ```bash
-# 1. Verify system readiness
-unitup doctor
+# Node.js
+unitup add server.js --runtime node
 
-# 2. Add Node.js scripts and assign to groups
-unitup add server.js --name api --group myproject --env-file .env --start
-unitup add worker.js --name worker --group myproject --start
+# Python
+unitup add worker.py --runtime python
 
-# 3. List all services with status, PID, uptime, restarts
-unitup list
-# or alias
-unitup ls --group myproject
+# Ruby
+unitup add app.rb --runtime ruby
 
-# 4. Perform batch control operations on a group using @group syntax
-unitup restart @myproject
-unitup stop @myproject
+# PHP (with runtime flags)
+unitup add index.php --runtime php --runtime-arg -S --runtime-arg 0.0.0.0:8080
 
-# 5. Inspect application configuration and status (excluding secrets)
-unitup inspect api
+# Bun
+unitup add server.ts --runtime bun
 
-# 6. Check for failed services
-unitup failures
+# Deno (with runtime permission flags)
+unitup add server.ts --runtime deno --runtime-arg --allow-net --runtime-arg --allow-env
+
+# Go
+unitup add main.go --runtime go
+
+# Elixir
+unitup add app.exs --runtime elixir
 
-# 7. Stream logs or view clean console output
-unitup logs api -c --follow
+# Native Executable
+unitup add ./server --runtime native --name api
 
-# 8. Remove a service or an entire group
-unitup remove @myproject
+# Generic Command Line Usage (bypasses runtime detection)
+unitup add \
+  --name worker \
+  --command /usr/bin/python3 \
+  --arg /home/user/apps/worker.py \
+  --arg --port \
+  --arg 3000
 ```
 
+> *Note: For production deployments, compiling the Go application and registering the resulting native binary is recommended.*
+
 ---
 
-## CLI Commands
+## Automatic Runtime & Shebang Detection
 
-### `unitup doctor`
+`unitup` automatically detects the runtime based on file extension and shebang headers:
 
-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
+.js, .mjs, .cjs → node
+.py             → python
+.rb             → ruby
+.php            → php
+.sh             → shell
+.go             → go
+.ex, .exs       → elixir
+```
 
-✓ 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
+Shebang examples detected automatically:
 
-User lingering is disabled.
-The service may stop after logout.
+```text
+#!/usr/bin/env python3
+#!/usr/bin/env node
+#!/usr/bin/env ruby
+#!/bin/bash
+```
 
-Enable it manually:
-  loginctl enable-linger username
+For ambiguous extensions such as `.ts`, `unitup` requires explicit runtime selection:
+
+```text
+Could not determine runtime for server.ts.
+
+Specify one:
+  unitup add server.ts --runtime bun
+  unitup add server.ts --runtime deno
+  unitup add server.ts --runtime node
 ```
 
 ---
 
-### Diagnosing Node.js Runtime & Path Problems
+## Native Executable Support
 
-`unitup` automatically detects and diagnoses Node.js installation issues before creating services.
+When adding a native executable:
+
+```bash
+unitup add ./server --runtime native --name api
+```
+
+`unitup` checks that the file:
+1. Exists
+2. Is a regular file
+3. Has execute permission (`chmod +x`)
+
+If execute permission is missing, `unitup` does **not** modify permissions automatically; it provides a helpful command suggestion:
 
-#### 1. Node.js not found in PATH
 ```text
-✗ Node.js not found in PATH
+The executable is not runnable.
 
-Install Node.js:
-  https://nodejs.org
-or via package manager:
-  sudo apt install nodejs
+Run:
+  chmod +x /home/user/apps/server
 ```
 
-#### 2. Node.js binary exists but is not executable
+---
+
+## CLI Commands Reference
+
+### `unitup doctor`
+
+Performs comprehensive system readiness and runtime diagnostic checks:
+
 ```text
-✗ Node.js binary exists but is not executable
+unitup doctor
 
-Check permissions:
-  chmod +x $(which node)
-```
+✓ Linux detected
+✓ systemctl available
+✓ systemd is running
+✓ systemd user services available
 
-#### 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:
+Detected runtimes:
+✓ Node.js: /usr/bin/node
+✓ Python: /usr/bin/python3
+✓ Ruby: /usr/bin/ruby
+✓ Go: /usr/local/go/bin/go
+- Bun: not found
+- Deno: not found
+- Elixir: not found
+
+✓ Unit directory writable
+! User lingering is disabled
 
-```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
+Enable it manually:
+  loginctl enable-linger username
 ```
 
-You can also specify an explicit Node.js binary path when creating a service:
+*Note: Missing optional runtimes do not cause `unitup doctor` to exit with an error.*
 
-```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`.
+### Missing Runtime Handling
+
+If a requested runtime is not installed on the system, `unitup` provides clear installation guidance:
+
+```text
+Python runtime could not be found.
+
+Install Python or specify its path:
+  unitup add worker.py --command /usr/bin/python3
+```
 
 ---
 
-### `unitup add <script>`
+### `unitup add`
 
 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
+unitup add worker.py --name worker --group backend --start
 ```
 
 **Options:**
 - `--name <name>`: Custom service name (defaults to script file name without extension).
-- `--node <path>`: Explicit Node.js executable path.
+- `--runtime <name>`: Specify runtime (`node`, `python`, `ruby`, `php`, `bun`, `deno`, `shell`, `go`, `elixir`, `native`).
+- `--runtime-arg <val>`: Pass flag/argument to runtime binary (can be specified multiple times).
+- `--command <path>`: Explicit binary executable path (bypasses auto-detection).
+- `--arg <value>`: Script/command argument (can be specified multiple times).
+- `--group <group>`: Assign service to a group (default: `default`).
 - `--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).
+- `--env-file <file>`: Path to environment file (adds `EnvironmentFile=...`).
+- `--restart <policy>`: Systemd restart policy (`on-failure`, `always`, `no`, `on-abnormal`. Default: `on-failure`).
 - `--start`: Automatically enables and starts the service immediately (`systemctl --user enable --now`).
 
-Generated unit file example (`~/.config/systemd/user/unitup-api.service`):
+Generated unit file example (`~/.config/systemd/user/unitup-worker.service`):
 
 ```ini
 [Unit]
-Description=unitup service: api
+Description=unitup service: worker
 After=network.target
 
 [Service]
 Type=simple
-WorkingDirectory=/home/user/projects/app
-ExecStart=/usr/bin/node /home/user/projects/app/server.js
+SyslogIdentifier=unitup-worker
+WorkingDirectory=/home/user/apps
+ExecStart=/usr/bin/python3 /home/user/apps/worker.py
 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"
+Environment=APP_ENV="production"
 
 [Install]
 WantedBy=default.target
@@ -228,138 +351,188 @@ WantedBy=default.target
 
 ---
 
-### `unitup start <name>`
+### `unitup list` / `unitup ls`
 
-Starts an existing service unit.
+Lists all user services managed by `unitup`:
 
 ```bash
-unitup start api
+unitup list
+```
+
+```text
+NAME      RUNTIME    STATUS     PID      COMMAND
+api       node       running    14220    node server.js
+worker    python     running    14302    python3 worker.py
+server    native     stopped    -        ./server
 ```
 
-Pass `--enable` to enable the service to start automatically on system boot:
+Filter by group:
+
+```bash
+unitup list --group backend
+```
+
+---
+
+### `unitup inspect <name>`
+
+View detailed configuration and status overview for a service (without revealing secrets or environment variables):
+
+```bash
+unitup inspect worker
+```
+
+```text
+Name: worker
+Runtime: python
+Group: backend
+Status: running
+Command: /usr/bin/python3
+Arguments: /home/user/apps/worker.py
+Working directory: /home/user/apps
+Unit: unitup-worker.service
+```
+
+---
+
+### `unitup start <name|@group>`
+
+Starts a service or an entire group:
 
 ```bash
-unitup start api --enable
+unitup start worker
+unitup start @backend --enable
 ```
 
 ---
 
-### `unitup stop <name>`
+### `unitup stop <name|@group>`
 
-Stops a running service:
+Stops a service or an entire group:
 
 ```bash
-unitup stop api
+unitup stop @backend
 ```
 
 ---
 
-### `unitup restart <name>`
+### `unitup restart <name|@group>`
 
-Restarts a service:
+Restarts a service or an entire group:
 
 ```bash
-unitup restart api
+unitup restart worker
+unitup restart @backend
 ```
 
 ---
 
 ### `unitup status <name>`
 
-Shows a compact status summary for the service:
+Shows compact status summary for the service:
 
 ```text
-api
+worker
 
 Status: running
-PID: 14220
-Started: 12 minutes ago
+PID: 14302
+Started: 15 minutes ago
 Restarts: 0
-Script: /home/user/projects/app/server.js
-Working directory: /home/user/projects/app
+Command: /usr/bin/python3
+Arguments: /home/user/apps/worker.py
+Working directory: /home/user/apps
 ```
 
-To view systemctl's raw output, pass `--raw`:
+Pass `--raw` for raw `systemctl status` output:
 
 ```bash
-unitup status api --raw
+unitup status worker --raw
 ```
 
 ---
 
 ### `unitup logs <name>`
 
-View or stream systemd journalctl logs for a service.
+View or stream systemd journalctl logs for a service:
 
 ```bash
-# View last 100 log lines (default)
-unitup logs app
-
 # Stream logs in real-time
-unitup logs app --follow
-
-# View last 50 lines of clean raw console output without systemd metadata prefix
-unitup logs app -c --lines 50
-# or
-unitup logs app --cat --lines 50
+unitup logs worker --follow
 
-# Specify custom journalctl output format
-unitup logs app --output=json
+# Clean raw console output without systemd timestamp/hostname metadata prefix
+unitup logs worker -c --lines 50
 ```
 
-**Options:**
-- `-f`, `--follow`: Stream logs in real time.
-- `-n`, `--lines <N>`: Specify number of log lines to show (default: 100).
-- `-c`, `--cat`: Format log output cleanly without systemd timestamp/hostname metadata prefix (`journalctl -o cat`).
-- `--output <format>`: Custom journalctl output mode (e.g. `cat`, `short`, `json`).
-
 ---
 
-### `unitup list`
+### `unitup failures`
 
-Lists all user services managed by `unitup` (`unitup-*.service`):
+Lists all currently failed services with exit codes and restart counts:
 
-```text
-NAME       STATUS     ENABLED
-api        running    yes
-worker     stopped    yes
-cleanup    failed     no
+```bash
+unitup failures
 ```
 
 ---
 
-### `unitup remove <name>`
+### `unitup remove <name|@group>`
 
 Stops, disables, and deletes the unit file, then reloads systemd:
 
 ```bash
-unitup remove api
+unitup remove worker
+unitup remove @backend
 ```
 
-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**:
+Depending on the Linux distribution and systemd-logind configuration, user services may stop after logout. Enable lingering to allow them to continue running without an active login session:
 
 ```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:
 
+### Generic `command + args` Example (Language-Agnostic)
+
+```ts
+import { createService } from "unitup";
+
+await createService({
+  name: "worker",
+  command: "/usr/bin/python3",
+  args: ["/home/user/apps/worker.py"],
+  cwd: "/home/user/apps",
+  restart: "on-failure",
+  start: true
+});
+```
+
+### CommonJS Support
+
+```js
+const {
+  createService,
+  startService,
+  getServiceStatus
+} = require("unitup");
+
+await createService({
+  name: "api",
+  script: "./server.js",
+  start: true
+});
+```
+
+### Script & Runtime Example
+
 ```ts
 import {
   createService,
@@ -369,33 +542,32 @@ import {
   removeService,
   getServiceStatus,
   listServices,
-  isSystemdAvailable,
+  inspectService,
+  detectRuntime,
+  resolveRuntimeConfig,
+  isSystemdAvailable
+} from "unitup";
+
+import type {
   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(),
+  // Add a Python worker service via script path
+  await createService({
+    name: "worker",
+    script: "./worker.py",
+    runtime: "python",
     env: {
-      NODE_ENV: "production",
-      PORT: "3000"
+      APP_ENV: "production"
     },
-    restart: "on-failure"
-  };
-
-  // Add a service
-  await createService(options);
+    start: true
+  });
 
-  // Start the service
-  await startService("api");
-
-  // Get compact status
-  const status: ServiceStatus = await getServiceStatus("api");
-  console.log(`Service PID: ${status.pid}, Status: ${status.status}`);
+  // Inspect service configuration
+  const info = await inspectService("worker");
+  console.log(`Command: ${info.command}, Status: ${info.status}`);
 
   // List all unitup services
   const services = await listServices();
@@ -405,6 +577,49 @@ if (await isSystemdAvailable()) {
 
 ---
 
+## Declarative Project Configuration (Roadmap Preview)
+
+Define your application stack declaratively using `unitup.yml` or `unitup.json` and sync it with systemd user services:
+
+```yaml
+# unitup.yml
+apps:
+  api:
+    runtime: node
+    script: ./server.js
+    env:
+      NODE_ENV: production
+      PORT: 3000
+    start: true
+
+  worker:
+    runtime: python
+    script: ./worker.py
+    env:
+      APP_ENV: production
+
+  native-service:
+    runtime: native
+    command: ./server
+```
+
+> *Note: Relative script, command, cwd, and env-file paths are resolved relative to the configuration file.*
+
+### Planned Declarative Commands:
+
+```bash
+# Preview differences between unitup.yml and active systemd units
+unitup diff
+
+# Apply unitup.yml configuration and create/update systemd user services
+unitup apply
+
+# Perform batch operations on group
+unitup restart @default
+```
+
+---
+
 ## License
 
 [MIT](LICENSE)