unitup 0.0.8 → 0.0.10

package/index.d.ts

@@ -1,23 +1,44 @@
 /**
- * unitup - Minimal systemd user service wrapper for Node.js scripts
+ * unitup - Systemd user service manager for any executable & runtime
  */
 
 import { ChildProcess } from 'node:child_process';
 
 /**
- * Options for creating/adding a Node.js systemd user service.
+ * Options for creating/adding a systemd user service.
  */
 export interface CreateServiceOptions {
   /**
-   * Name of the service (e.g., 'api' or 'my-app').
+   * Name of the service (e.g., 'api' or 'worker').
    * Safe characters: lowercase letters, numbers, hyphens, underscores.
    */
   name: string;
 
   /**
-   * Absolute or relative path to the target Node.js script.
+   * Optional group name (e.g. 'myproject').
+   * @default 'default'
    */
-  script: string;
+  group?: string;
+
+  /**
+   * Target runtime name (e.g. 'node', 'python', 'ruby', 'php', 'bun', 'deno', 'shell', 'go', 'elixir', 'native').
+   */
+  runtime?: string;
+
+  /**
+   * Runtime-specific flags/arguments passed before script (e.g. ['--allow-net'] for Deno or ['-S', '0.0.0.0:8080'] for PHP).
+   */
+  runtimeArgs?: string[];
+
+  /**
+   * Explicit executable command binary path (bypasses runtime auto-detection).
+   */
+  command?: string;
+
+  /**
+   * Absolute or relative path to the target script file.
+   */
+  script?: string;
 
   /**
    * Working directory path for the service execution (defaults to script directory).
@@ -25,7 +46,7 @@ export interface CreateServiceOptions {
   cwd?: string;
 
   /**
-   * Absolute path to explicit Node.js executable binary (defaults to process.execPath).
+   * Absolute path to explicit Node.js executable binary (legacy support).
    */
   nodePath?: string;
 
@@ -46,7 +67,7 @@ export interface CreateServiceOptions {
   restart?: string;
 
   /**
-   * Positional arguments to pass to the script execution line.
+   * Positional arguments to pass to the script/command execution line.
    */
   args?: string[];
 
@@ -55,6 +76,47 @@ export interface CreateServiceOptions {
    * @default false
    */
   start?: boolean;
+
+  /**
+   * Soft memory limit directive (e.g. '400M').
+   */
+  memoryHigh?: string;
+
+  /**
+   * Hard memory limit directive (e.g. '512M').
+   */
+  memoryMax?: string;
+
+  /**
+   * Swap memory limit directive (e.g. '256M').
+   */
+  memorySwapMax?: string;
+}
+
+/**
+ * Options for setting or resetting service memory limits.
+ */
+export interface ServiceLimitsOptions {
+  /**
+   * Soft memory limit directive (e.g. '400M').
+   */
+  memoryHigh?: string;
+
+  /**
+   * Hard memory limit directive (e.g. '512M').
+   */
+  memoryMax?: string;
+
+  /**
+   * Swap memory limit directive (e.g. '256M').
+   */
+  memorySwapMax?: string;
+
+  /**
+   * Resets all memory limits back to defaults/infinity.
+   * @default false
+   */
+  resetMemory?: boolean;
 }
 
 /**
@@ -134,6 +196,21 @@ export interface ServiceStatus {
    */
   startedRaw?: string;
 
+  /**
+   * Executable command path.
+   */
+  command: string;
+
+  /**
+   * Command arguments string.
+   */
+  arguments: string;
+
+  /**
+   * Array of command arguments.
+   */
+  args: string[];
+
   /**
    * Path to target script parsed from unit file.
    */
@@ -155,58 +232,115 @@ export interface ListServiceItem {
   name: string;
 
   /**
-   * Status overview ('running', 'stopped', 'failed', etc.).
+   * Runtime name.
    */
-  status: string;
+  runtime: string;
 
   /**
-   * Enabled status ('yes' or 'no').
+   * Group name.
    */
-  enabled: string;
-}
+  group: string;
 
-/**
- * Diagnostic results for Node.js runtime environment.
- */
-export interface NodeDiagnostics {
   /**
-   * True if Node.js binary was found.
+   * Status overview ('running', 'stopped', 'failed', etc.).
    */
-  found: boolean;
+  status: string;
 
   /**
-   * True if Node.js binary is executable and runs -v.
+   * Enabled status ('yes' or 'no').
    */
-  executable: boolean;
+  enabled: string;
 
   /**
-   * Resolved Node.js executable path.
+   * Main PID or '-'.
    */
-  execPath: string;
+  pid: string;
 
   /**
-   * Path returned by which/where node.
+   * Command summary (e.g. 'node server.js' or 'python3 worker.py').
    */
-  whichPath: string;
+  command: string;
 
   /**
-   * Node.js version string (e.g. 'v20.11.0').
+   * Formatted uptime string.
    */
-  version: string;
+  uptime: string;
 
   /**
-   * True if node binary is in system PATH environment.
+   * Restart count.
    */
-  inPath: boolean;
+  restarts: string;
+}
 
-  /**
-   * Diagnostic error message if check failed.
-   */
-  error: string | null;
+/**
+ * App metadata saved in ~/.config/unitup/apps/<name>.json.
+ */
+export interface AppMetadata {
+  name: string;
+  unit: string;
+  runtime?: string;
+  command?: string;
+  args?: string[];
+  group: string;
+  script: string;
+  cwd: string;
+  node: string;
+}
 
-  /**
-   * Troubleshooting solution recommendation.
-   */
+/**
+ * Detailed application inspection summary (unitup inspect).
+ */
+export interface InspectInfo {
+  name: string;
+  runtime: string;
+  unit: string;
+  unitPath: string;
+  group: string;
+  status: string;
+  activeState: string;
+  subState: string;
+  command: string;
+  arguments: string;
+  args: string[];
+  cwd: string;
+  pid: string;
+  restarts: string;
+  started: string;
+
+  memory?: string;
+  memoryPeak?: string;
+  memoryHigh?: string;
+  memoryMax?: string;
+  memorySwapMax?: string;
+
+  // Legacy compatibility fields
+  script?: string;
+  node?: string;
+}
+
+/**
+ * Failed service failure report item (unitup failures).
+ */
+export interface FailureItem {
+  name: string;
+  group: string;
+  status: string;
+  exitCode: string;
+  restarts: string;
+  uptime: string;
+}
+
+/**
+ * Diagnostic results for Node.js runtime environment.
+ */
+export interface NodeDiagnostics {
+  found: boolean;
+  executable: boolean;
+  execPath: string;
+  whichPath: string;
+  version: string;
+  inPath: boolean;
+  error: string | null;
   solution: string | null;
 }
 
@@ -214,59 +348,21 @@ export interface NodeDiagnostics {
  * Diagnostic report object from unitup doctor.
  */
 export interface DoctorInfo {
-  /**
-   * True if OS is Linux.
-   */
   linux: boolean;
-
-  /**
-   * True if systemctl binary is found in PATH.
-   */
   systemctl: boolean;
-
-  /**
-   * True if systemd is running as PID 1.
-   */
   systemdRunning: boolean;
-
-  /**
-   * True if systemd user session bus is accessible.
-   */
   userSystemdAvailable: boolean;
-
-  /**
-   * Node.js runtime diagnostics.
-   */
+  cgroupV2?: boolean;
+  memoryController?: boolean;
+  memoryMaxSupported?: boolean;
+  memorySwapMaxSupported?: boolean;
   nodeDiag: NodeDiagnostics;
-
-  /**
-   * Resolved Node.js executable path.
-   */
   nodePath: string;
-
-  /**
-   * Node.js version string.
-   */
   nodeVersion: string;
-
-  /**
-   * Systemd user unit directory path.
-   */
+  runtimes: Record<string, string | null>;
   unitDir: string;
-
-  /**
-   * True if unit directory is writable.
-   */
   unitDirWritable: boolean;
-
-  /**
-   * True if user lingering is enabled (loginctl enable-linger).
-   */
   lingering: boolean;
-
-  /**
-   * Current OS username.
-   */
   username: string;
 }
 
@@ -274,14 +370,7 @@ export interface DoctorInfo {
  * Result returned when creating/adding a new unitup service.
  */
 export interface AddServiceResult {
-  /**
-   * Cleaned service name.
-   */
   name: string;
-
-  /**
-   * Path to created unit file.
-   */
   unitPath: string;
 }
 
@@ -289,9 +378,14 @@ export interface AddServiceResult {
  * Parsed systemd unit file content metadata.
  */
 export interface ParsedUnitContent {
+  command?: string;
+  args?: string[];
   script?: string;
   cwd?: string;
   restart?: string;
+  memoryHigh?: string;
+  memoryMax?: string;
+  memorySwapMax?: string;
 }
 
 /**
@@ -307,58 +401,36 @@ export type CommandRunnerFn = (
 // Programmatic API Function Declarations
 // ---------------------------------------------------------------------------
 
-/**
- * Creates and writes a systemd user service unit file, then reloads the systemd daemon.
- */
 export function createService(options: CreateServiceOptions): Promise<AddServiceResult>;
 export function addService(options: CreateServiceOptions): Promise<AddServiceResult>;
-
-/**
- * Starts a systemd user service unit.
- * @param name Service name (e.g. 'api')
- * @param enable If true, enables the service on boot (--enable)
- */
 export function startService(name: string, enable?: boolean): Promise<boolean>;
-
-/**
- * Stops a running systemd user service unit.
- */
 export function stopService(name: string): Promise<boolean>;
-
-/**
- * Restarts a systemd user service unit.
- */
 export function restartService(name: string): Promise<boolean>;
-
-/**
- * Stops, disables, and deletes a systemd user service unit file, then reloads daemon.
- */
 export function removeService(name: string): Promise<boolean>;
-
-/**
- * Retrieves compact parsed status information for a service.
- */
 export function getServiceStatus(name: string): Promise<ServiceStatus>;
-
-/**
- * Retrieves raw string output of systemctl --user status.
- */
 export function getServiceStatusRaw(name: string): Promise<string>;
-
-/**
- * Lists all unitup-*.service user units.
- */
-export function listServices(): Promise<ListServiceItem[]>;
-
-/**
- * Fetches or streams journalctl logs for a service.
- */
+export function listServices(options?: { group?: string }): Promise<ListServiceItem[]>;
+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 executeJournalctlMaintenance(action: string, options?: Record<string, unknown>): Promise<string>;
 export function getServiceLogs(name: string, options?: LogOptions): Promise<string | ChildProcess>;
 
-// ---------------------------------------------------------------------------
-// System Diagnostics & Doctor
-// ---------------------------------------------------------------------------
+// Validation & Formatting Helpers
+export function validateMemorySize(val: string | number, paramName?: string): string;
+export function formatMemoryBytes(bytes: number | string): string;
 
+// Runtime Helpers
+export function detectRuntime(filepath: string): string;
+export function resolveRuntimeConfig(options: CreateServiceOptions): Promise<{
+  command: string;
+  args: string[];
+  runtime: string;
+  version: string;
+}>;
+
+// Diagnostics & Doctor
 export function isSystemdAvailable(): Promise<boolean>;
 export function isSystemctlAvailable(): Promise<boolean>;
 export function isLinux(): boolean;
@@ -369,10 +441,7 @@ export function checkNodeDiagnostics(customNodePath?: string): Promise<NodeDiagn
 export function findNodeExecutable(customPath?: string): Promise<string | null>;
 export function getDoctorInfo(): Promise<DoctorInfo>;
 
-// ---------------------------------------------------------------------------
-// Unit File & Path Helpers
-// ---------------------------------------------------------------------------
-
+// Path & Unit Helpers
 export function getUserUnitDir(): string;
 export function getUnitPath(name: string): string;
 export function unitFileExists(name: string): boolean;
@@ -380,10 +449,11 @@ export function parseUnitContent(content: string): ParsedUnitContent;
 export function sanitizeServiceName(name: string): string;
 export function getUnitFilename(name: string): string;
 export function getServiceNameFromUnit(unitFilename: string): string;
+export function readAppMetadata(name: string): AppMetadata | null;
+export function getAppMetadataPath(name: string): string;
+export function getAppsDir(): string;
+export function getUnitupDir(): string;
 
-// ---------------------------------------------------------------------------
-// Runner Override Helpers for Testing
-// ---------------------------------------------------------------------------
-
+// Testing Mock Helpers
 export function setCommandRunner(runner: CommandRunnerFn): void;
 export function resetCommandRunner(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitup",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "Minimal systemd user service wrapper for Node.js scripts",
   "main": "src/index.js",
   "types": "./index.d.ts",
@@ -11,6 +11,9 @@
   "scripts": {
     "test": "node --test test/*.test.js"
   },
+  "devDependencies": {
+    "typescript": "^5.7.3"
+  },
   "keywords": [
     "systemd",
     "service",