unitup 0.0.12 → 0.1.1

package/README.md

@@ -85,7 +85,7 @@ At its core, `unitup` generates systemd service unit files directly from a gener
 - 🧠 **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.
+- ⏰ **Systemd Timer-Based Scheduling** — Create native `.timer` systemd units (`unitup schedule`) with interval (`--every 30m`), calendar (`--calendar daily`), boot delay (`--on-boot`), random delay jitter (`--random-delay`), and missed execution persistence (`--persistent`) without background cron daemons or continuously running worker processes.
 - 📦 **Programmatic API** — imported directly into JavaScript and TypeScript applications.
 
 ---
@@ -112,6 +112,32 @@ unitup limits api --reset-memory
 
 *Supported size units:* `128K`, `256M`, `1G`, `infinity`, `max`, or raw byte integers.
 
+### Memory Usage Overview (`unitup memory` / `unitup top`)
+
+```bash
+# View memory usage overview for all running services & schedules
+unitup top
+
+# Alias: unitup memory or unitup mem
+unitup memory
+
+# Filter memory overview by group
+unitup top --group backend
+
+# View detailed memory breakdown for a specific app
+unitup memory api
+```
+
+Example Output:
+```text
+NAME       GROUP      TYPE       STATUS     PID      MEMORY     PEAK       LIMIT (MAX)
+api        backend    service    running    14220    284 MB     361 MB     512 MB
+worker     backend    service    running    14302    120 MB     150 MB     1 GB
+cleanup    backend    timer      waiting    -        0 MB       unavailable 1 GB
+
+Total Memory Usage across 2 active app(s): 404 MB
+```
+
 ### Journald Log Maintenance
 
 ```bash
@@ -131,6 +157,52 @@ 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`.
 
+### Systemd Timer Schedules (`unitup schedule`)
+
+`unitup` allows you to schedule tasks completely via native systemd `.timer` units without running background daemons, cron services, or continuous worker loops.
+
+Each schedule creates a paired service (`~/.config/systemd/user/unitup-<name>.service`) with `Type=oneshot` and timer (`~/.config/systemd/user/unitup-<name>.timer`).
+
+```bash
+# Interval schedule (--every)
+unitup schedule cleanup.js --every 30m --persistent --start
+
+# Calendar schedule (--calendar)
+unitup schedule backup.py --calendar daily --random-delay 10m --persistent --start
+
+# Complex calendar expression
+unitup schedule report.js --calendar "Mon..Fri 09:00" --start
+
+# List all active schedule timers
+unitup schedules   # or unitup timers
+
+# Detailed schedule status
+unitup schedule-status cleanup   # or unitup timer-status cleanup
+
+# Manually run the schedule service once (leaves timer schedule unchanged)
+unitup schedule-run cleanup
+
+# Enable or disable schedule timers
+unitup schedule-enable cleanup
+unitup schedule-disable cleanup
+
+# Remove schedule timer, service unit, and metadata
+unitup schedule-remove cleanup [--force]
+
+# Read scheduled task logs
+unitup schedule-logs cleanup
+```
+
+#### Schedule Options
+
+- `--every <duration>`: Execution interval (e.g., `30s`, `10m`, `2h`, `1d`). Generates `OnActiveSec` and `OnUnitActiveSec`.
+- `--calendar <expression>`: Systemd calendar expression (e.g., `daily`, `weekly`, `"Mon..Fri 09:00"`). Validated via `systemd-analyze calendar`.
+- `--on-boot <duration>`: Delay execution relative to system boot (e.g., `5m`).
+- `--on-active <duration>`: Delay execution relative to timer activation.
+- `--random-delay <duration>`: Adds a randomized delay jitter to prevent simultaneous job stampedes (e.g., `10m`).
+- `--persistent`: Sets `Persistent=true` so systemd executes missed schedules immediately after system boot or wake.
+- `--start`: Automatically enables and starts the timer unit after creation (`systemctl --user enable --now`).
+
 ---
 
 ## Requirements
@@ -525,15 +597,62 @@ await createService({
 ```js
 const {
   createService,
-  startService,
-  getServiceStatus
+  createSchedule,
+  listSchedules
 } = require("unitup");
 
-await createService({
-  name: "api",
-  script: "./server.js",
+await createSchedule({
+  name: "cleanup",
+  script: "./cleanup.js",
+  every: "30m",
+  start: true
+});
+```
+
+### Programmatic Schedule API Example
+
+```ts
+import {
+  createSchedule,
+  listSchedules,
+  getScheduleStatus,
+  runSchedule,
+  enableSchedule,
+  disableSchedule,
+  removeSchedule
+} from "unitup";
+
+// Create an interval schedule
+await createSchedule({
+  name: "cleanup",
+  script: "./cleanup.js",
+  runtime: "node",
+  every: "30m",
+  persistent: true,
   start: true
 });
+
+// Create a calendar schedule with random delay jitter
+await createSchedule({
+  name: "backup",
+  script: "./backup.py",
+  runtime: "python",
+  calendar: "daily",
+  randomDelay: "10m",
+  persistent: true,
+  start: true
+});
+
+// List all active schedules
+const schedules = await listSchedules();
+console.log(schedules);
+
+// Manually trigger a schedule run
+await runSchedule("cleanup");
+
+// Disable and remove schedule
+await disableSchedule("cleanup");
+await removeSchedule("cleanup");
 ```
 
 ### Script & Runtime Example

package/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+Use this section to tell people about which versions of your project are
+currently being supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 5.1.x   | :white_check_mark: |
+| 5.0.x   | :x:                |
+| 4.0.x   | :white_check_mark: |
+| < 4.0   | :x:                |
+
+## Reporting a Vulnerability
+
+Use this section to tell people how to report a vulnerability.
+
+Tell them where to go, how often they can expect to get an update on a
+reported vulnerability, what to expect if the vulnerability is accepted or
+declined, etc.

package/docs/index.html

@@ -25,6 +25,8 @@
   <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/yaml.min.js"></script>
   <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/ini.min.js"></script>
   <style>
+    body { overflow-x: hidden; }
+    .grid > * { min-width: 0; }
     html { scroll-behavior: smooth; }
     pre { tab-size: 2; margin: 0; overflow-x: auto; max-width: 100%; }
     pre code { padding: 1rem; background: #0f172a; border-radius: 0.75rem; font-size: 0.85rem; display: block; overflow-x: auto; white-space: pre; }
@@ -67,6 +69,7 @@
         <a href="#architecture" class="text-slate-600 hover:text-cyan-600 dark:text-slate-400 dark:hover:text-cyan-400 py-1">Architecture</a>
         <a href="#runtimes" class="text-slate-600 hover:text-cyan-600 dark:text-slate-400 dark:hover:text-cyan-400 py-1">Runtimes</a>
         <a href="#cli" class="text-slate-600 hover:text-cyan-600 dark:text-slate-400 dark:hover:text-cyan-400 py-1">CLI Reference</a>
+        <a href="#schedules" class="text-slate-600 hover:text-cyan-600 dark:text-slate-400 dark:hover:text-cyan-400 py-1">Schedules</a>
         <a href="#api" class="text-slate-600 hover:text-cyan-600 dark:text-slate-400 dark:hover:text-cyan-400 py-1">API</a>
         <a href="#declarative" class="text-slate-600 hover:text-cyan-600 dark:text-slate-400 dark:hover:text-cyan-400 py-1">Roadmap</a>
         <a href="#troubleshooting" class="text-slate-600 hover:text-cyan-600 dark:text-slate-400 dark:hover:text-cyan-400 py-1">Lingering</a>
@@ -212,8 +215,8 @@ unitup add ./server --runtime native --name api --start</code></pre>
         At its core, unitup generates systemd service unit files directly from a generic <code class="text-cyan-600 dark:text-cyan-400">command + args</code> model rather than being hardcoded to Node.js:
       </p>
 
-      <div class="grid md:grid-cols-2 gap-6">
-        <div>
+      <div class="grid grid-cols-1 md:grid-cols-2 gap-6">
+        <div class="min-w-0">
           <h3 class="text-sm font-semibold uppercase tracking-wider text-cyan-600 dark:text-cyan-400 mb-2">JSON Execution Model</h3>
           <pre><code class="language-json">{
   "command": "/usr/bin/python3",
@@ -224,8 +227,8 @@ unitup add ./server --runtime native --name api --start</code></pre>
   }
 }</code></pre>
         </div>
-        <div>
-          <h3 class="text-sm font-semibold uppercase tracking-wider text-cyan-600 dark:text-cyan-400 mb-2">Generated Unit File (<code class="text-xs">unitup-worker.service</code>)</h3>
+        <div class="min-w-0">
+          <h3 class="text-sm font-semibold uppercase tracking-wider text-cyan-600 dark:text-cyan-400 mb-2 flex flex-wrap items-center gap-1">Generated Unit File <span class="lowercase font-mono text-xs normal-case opacity-90 break-all">(unitup-worker.service)</span></h3>
           <pre><code class="language-ini">[Unit]
 Description=unitup service: worker
 After=network.target
@@ -381,6 +384,15 @@ unitup stop @backend</code></pre>
 unitup limits api --reset-memory</code></pre>
         </div>
 
+        <!-- memory / top -->
+        <div class="p-5 rounded-xl border border-slate-200 dark:border-slate-800 bg-white/70 dark:bg-slate-900/50">
+          <h3 class="text-lg font-bold text-cyan-600 dark:text-cyan-400 mb-2"><code class="text-base">unitup memory</code> / <code class="text-base">unitup top</code></h3>
+          <p class="text-sm text-slate-600 dark:text-slate-400 mb-3">Displays memory usage overview across all running apps and schedules, with aggregated total memory consumption summary.</p>
+          <pre><code class="language-bash">unitup top
+unitup memory api
+unitup mem --group backend</code></pre>
+        </div>
+
         <!-- status & logs -->
         <div class="p-5 rounded-xl border border-slate-200 dark:border-slate-800 bg-white/70 dark:bg-slate-900/50">
           <h3 class="text-lg font-bold text-cyan-600 dark:text-cyan-400 mb-2"><code class="text-base">unitup status / logs &lt;name&gt;</code></h3>
@@ -409,6 +421,58 @@ unitup remove @backend --force</code></pre>
       </div>
     </section>
 
+    <!-- Section: Schedules -->
+    <section id="schedules" class="doc-section mb-14">
+      <h2 class="text-2xl font-bold text-slate-900 dark:text-white mb-4">Systemd Timer Schedules</h2>
+      <p class="text-slate-600 dark:text-slate-400 mb-6 leading-relaxed">
+        <strong class="text-slate-800 dark:text-slate-200">unitup</strong> supports native systemd timer scheduling without running continuous worker processes or cron daemons. Each schedule generates a paired oneshot service (<code class="text-cyan-700 dark:text-cyan-400">~/.config/systemd/user/unitup-&lt;name&gt;.service</code>) and timer unit (<code class="text-cyan-700 dark:text-cyan-400">~/.config/systemd/user/unitup-&lt;name&gt;.timer</code>).
+      </p>
+
+      <div class="space-y-6">
+        <div class="p-5 rounded-xl border border-slate-200 dark:border-slate-800 bg-white/70 dark:bg-slate-900/50">
+          <h3 class="text-lg font-bold text-cyan-600 dark:text-cyan-400 mb-2">CLI Schedule Commands</h3>
+          <pre><code class="language-bash"># Create interval schedule (--every 30m)
+unitup schedule cleanup.js --every 30m --persistent --start
+
+# Create calendar schedule (--calendar daily with random delay jitter)
+unitup schedule backup.py --calendar daily --random-delay 10m --persistent --start
+
+# Specific calendar expression
+unitup schedule report.js --calendar "Mon..Fri 09:00" --start
+
+# List all schedule timers
+unitup schedules   # or unitup timers
+
+# Detailed schedule status
+unitup schedule-status cleanup
+
+# Manually trigger schedule service unit once
+unitup schedule-run cleanup
+
+# Enable / Disable / Remove schedule
+unitup schedule-enable cleanup
+unitup schedule-disable cleanup
+unitup schedule-remove cleanup [--force]
+
+# Read schedule logs
+unitup schedule-logs cleanup</code></pre>
+        </div>
+
+        <div class="p-5 rounded-xl border border-slate-200 dark:border-slate-800 bg-white/70 dark:bg-slate-900/50">
+          <h3 class="text-lg font-bold text-cyan-600 dark:text-cyan-400 mb-2">Schedule Options</h3>
+          <ul class="list-disc list-inside space-y-1.5 text-sm text-slate-600 dark:text-slate-400">
+            <li><code class="text-xs font-bold text-slate-800 dark:text-slate-200">--every &lt;duration&gt;</code>: Execution interval (e.g., <code class="text-xs">30s</code>, <code class="text-xs">10m</code>, <code class="text-xs">2h</code>, <code class="text-xs">1d</code>). Sets <code class="text-xs">OnActiveSec</code> and <code class="text-xs">OnUnitActiveSec</code>.</li>
+            <li><code class="text-xs font-bold text-slate-800 dark:text-slate-200">--calendar &lt;expression&gt;</code>: Systemd calendar expression (e.g., <code class="text-xs">daily</code>, <code class="text-xs">"Mon..Fri 09:00"</code>). Validated via <code class="text-xs">systemd-analyze calendar</code>.</li>
+            <li><code class="text-xs font-bold text-slate-800 dark:text-slate-200">--on-boot &lt;duration&gt;</code>: Delay execution relative to system boot (e.g., <code class="text-xs">5m</code>).</li>
+            <li><code class="text-xs font-bold text-slate-800 dark:text-slate-200">--on-active &lt;duration&gt;</code>: Delay execution relative to timer activation.</li>
+            <li><code class="text-xs font-bold text-slate-800 dark:text-slate-200">--random-delay &lt;duration&gt;</code>: Adds randomized delay jitter (<code class="text-xs">RandomizedDelaySec</code>).</li>
+            <li><code class="text-xs font-bold text-slate-800 dark:text-slate-200">--persistent</code>: Sets <code class="text-xs">Persistent=true</code> to execute missed schedules immediately after system wake/boot.</li>
+            <li><code class="text-xs font-bold text-slate-800 dark:text-slate-200">--start</code>: Enables and starts the timer unit immediately after creation.</li>
+          </ul>
+        </div>
+      </div>
+    </section>
+
     <!-- Section: API -->
     <section id="api" class="doc-section mb-14">
       <h2 class="text-2xl font-bold text-slate-900 dark:text-white mb-4">Programmatic API</h2>

package/index.d.ts

@@ -97,6 +97,11 @@ export interface CreateServiceOptions {
    * Swap memory limit directive (e.g. '256M').
    */
   memorySwapMax?: string;
+
+  /**
+   * Default memory limit fallback or request marker (defaults to '1G').
+   */
+  defaultMemory?: string | boolean;
 }
 
 /**
@@ -420,6 +425,36 @@ export function inspectService(name: string): Promise<InspectInfo>;
 export function getServiceFailures(): Promise<FailureItem[]>;
 export function getServicesByGroup(groupName: string): Promise<string[]>;
 export function setServiceLimits(name: string, options?: ServiceLimitsOptions): Promise<InspectInfo>;
+export function getServiceMemoryUsage(name: string): Promise<{
+  name: string;
+  group: string;
+  type: string;
+  status: string;
+  pid: string;
+  memoryBytes: number;
+  memory: string;
+  memoryPeak: string;
+  memoryHigh: string;
+  memoryMax: string;
+  memorySwapMax: string;
+}>;
+export function getAllServicesMemoryUsage(options?: { group?: string }): Promise<{
+  items: Array<{
+    name: string;
+    group: string;
+    type: string;
+    status: string;
+    pid: string;
+    memory: string;
+    memoryPeak: string;
+    memoryMax: string;
+    memoryHigh: string;
+    memoryBytes: number;
+  }>;
+  totalBytes: number;
+  totalMemory: string;
+  runningCount: number;
+}>;
 export function executeJournalctlMaintenance(action: string, options?: Record<string, unknown>): Promise<string>;
 export function getServiceLogs(name: string, options?: LogOptions): Promise<string | ChildProcess>;
 
@@ -463,3 +498,105 @@ export function getUnitupDir(): string;
 // Testing Mock Helpers
 export function setCommandRunner(runner: CommandRunnerFn): void;
 export function resetCommandRunner(): void;
+
+// ---------------------------------------------------------------------------
+// Schedule Management API
+// ---------------------------------------------------------------------------
+
+export interface CreateScheduleOptions {
+  name?: string;
+  script?: string;
+  command?: string;
+  runtime?: string;
+  args?: string[];
+  runtimeArgs?: string[];
+  cwd?: string;
+  env?: Record<string, string> | string[];
+  envFile?: string;
+  group?: string;
+  memoryHigh?: string;
+  memoryMax?: string;
+  memorySwapMax?: string;
+  defaultMemory?: string | boolean;
+  every?: string;
+  calendar?: string;
+  onBoot?: string;
+  onActive?: string;
+  randomDelay?: string;
+  persistent?: boolean;
+  start?: boolean;
+  enable?: boolean;
+}
+
+export interface ScheduleMetadata {
+  name: string;
+  group: string;
+  type: string;
+  runtime: string;
+  command: string;
+  args: string[];
+  cwd: string;
+  schedule: {
+    every: string | null;
+    calendar: string | null;
+    onBoot: string | null;
+    onActive: string | null;
+    persistent: boolean;
+    randomDelay: string | null;
+  };
+  serviceUnit: string;
+  timerUnit: string;
+}
+
+export interface ScheduleStatus {
+  name: string;
+  group: string;
+  schedule: string;
+  nextRun: string;
+  lastRun: string;
+  status: string;
+  activeState: string;
+  subState: string;
+  unitFileState: string;
+  serviceActiveState: string;
+  metadata?: ScheduleMetadata | null;
+  serviceUnit: string;
+  timerUnit: string;
+}
+
+export interface CreateScheduleResult {
+  name: string;
+  group: string;
+  type: string;
+  runtime: string;
+  command: string;
+  args: string[];
+  cwd: string;
+  schedule: Record<string, unknown>;
+  serviceUnit: string;
+  timerUnit: string;
+  servicePath: string;
+  timerPath: string;
+}
+
+export function createSchedule(options: CreateScheduleOptions): Promise<CreateScheduleResult>;
+export function listSchedules(group?: string): Promise<ScheduleStatus[]>;
+export function getScheduleStatus(name: string): Promise<ScheduleStatus>;
+export function runSchedule(name: string): Promise<boolean>;
+export function enableSchedule(name: string): Promise<boolean>;
+export function disableSchedule(name: string): Promise<boolean>;
+export function removeSchedule(name: string, options?: { force?: boolean }): Promise<boolean>;
+export function validateCalendar(expression: string): Promise<{ valid: boolean; error?: string; warning?: string }>;
+export function validateDuration(val: string | number, paramName?: string): string;
+export function getTimerFilename(name: string): string;
+export function getTimerPath(name: string): string;
+export function timerFileExists(name: string): boolean;
+export function readScheduleMetadata(name: string): ScheduleMetadata | null;
+export function getScheduleMetadataPath(name: string): string;
+export function getSchedulesDir(): string;
+export function readGlobalConfig(): Record<string, unknown>;
+export function saveGlobalConfig(config: Record<string, unknown>): Record<string, unknown>;
+export function getConfigFilepath(): string;
+export function resolveEffectiveMemoryLimits(opts?: Record<string, unknown>): { memoryHigh?: string; memoryMax?: string; memorySwapMax?: string };
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitup",
-  "version": "0.0.12",
+  "version": "0.1.1",
   "description": "Minimal, zero-dependency systemd-native service manager for any runtime, script, or executable",
   "main": "src/index.js",
   "types": "./index.d.ts",