unitup 0.0.1

package/index.d.ts

@@ -0,0 +1,378 @@
+/**
+ * unitup - Minimal systemd user service wrapper for Node.js scripts
+ */
+
+import { ChildProcess } from 'node:child_process';
+
+/**
+ * Options for creating/adding a Node.js systemd user service.
+ */
+export interface CreateServiceOptions {
+  /**
+   * Name of the service (e.g., 'api' or 'my-app').
+   * Safe characters: lowercase letters, numbers, hyphens, underscores.
+   */
+  name: string;
+
+  /**
+   * Absolute or relative path to the target Node.js script.
+   */
+  script: string;
+
+  /**
+   * Working directory path for the service execution (defaults to script directory).
+   */
+  cwd?: string;
+
+  /**
+   * Absolute path to explicit Node.js executable binary (defaults to process.execPath).
+   */
+  nodePath?: string;
+
+  /**
+   * Key-value map of environment variables to inject into the systemd unit.
+   */
+  env?: Record<string, string>;
+
+  /**
+   * Path to an environment file (adds EnvironmentFile=... directive).
+   */
+  envFile?: string;
+
+  /**
+   * Systemd restart policy directive (e.g., 'on-failure', 'always', 'no', 'on-abnormal').
+   * @default 'on-failure'
+   */
+  restart?: string;
+
+  /**
+   * Positional arguments to pass to the script execution line.
+   */
+  args?: string[];
+
+  /**
+   * Automatically enables and starts the service immediately upon creation.
+   * @default false
+   */
+  start?: boolean;
+}
+
+/**
+ * Options for retrieving journalctl log output.
+ */
+export interface LogOptions {
+  /**
+   * Live streaming follow mode (-f).
+   * @default false
+   */
+  follow?: boolean;
+
+  /**
+   * Number of journal log lines to return (-n).
+   * @default 100
+   */
+  lines?: number;
+}
+
+/**
+ * Parsed compact service status summary.
+ */
+export interface ServiceStatus {
+  /**
+   * Clean service name (e.g. 'api').
+   */
+  name: string;
+
+  /**
+   * Full systemd unit filename (e.g. 'unitup-api.service').
+   */
+  unitFile: string;
+
+  /**
+   * Status overview ('running', 'stopped', 'failed', 'exited', etc.).
+   */
+  status: string;
+
+  /**
+   * Raw ActiveState string from systemctl show.
+   */
+  activeState: string;
+
+  /**
+   * Raw SubState string from systemctl show.
+   */
+  subState: string;
+
+  /**
+   * Main Process ID (PID) of the service, or '-' if stopped.
+   */
+  pid: string;
+
+  /**
+   * Total number of restarts recorded by systemd.
+   */
+  restarts: string;
+
+  /**
+   * Relative formatted uptime/started string (e.g. '12 minutes ago').
+   */
+  started: string;
+
+  /**
+   * Raw timestamp from systemctl show.
+   */
+  startedRaw?: string;
+
+  /**
+   * Path to target script parsed from unit file.
+   */
+  script: string;
+
+  /**
+   * Working directory parsed from unit file.
+   */
+  cwd: string;
+}
+
+/**
+ * Service item in list overview.
+ */
+export interface ListServiceItem {
+  /**
+   * Service name.
+   */
+  name: string;
+
+  /**
+   * Status overview ('running', 'stopped', 'failed', etc.).
+   */
+  status: string;
+
+  /**
+   * Enabled status ('yes' or 'no').
+   */
+  enabled: string;
+}
+
+/**
+ * Diagnostic results for Node.js runtime environment.
+ */
+export interface NodeDiagnostics {
+  /**
+   * True if Node.js binary was found.
+   */
+  found: boolean;
+
+  /**
+   * True if Node.js binary is executable and runs -v.
+   */
+  executable: boolean;
+
+  /**
+   * Resolved Node.js executable path.
+   */
+  execPath: string;
+
+  /**
+   * Path returned by which/where node.
+   */
+  whichPath: string;
+
+  /**
+   * Node.js version string (e.g. 'v20.11.0').
+   */
+  version: string;
+
+  /**
+   * True if node binary is in system PATH environment.
+   */
+  inPath: boolean;
+
+  /**
+   * Diagnostic error message if check failed.
+   */
+  error: string | null;
+
+  /**
+   * Troubleshooting solution recommendation.
+   */
+  solution: string | null;
+}
+
+/**
+ * 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.
+   */
+  nodeDiag: NodeDiagnostics;
+
+  /**
+   * Resolved Node.js executable path.
+   */
+  nodePath: string;
+
+  /**
+   * Node.js version string.
+   */
+  nodeVersion: string;
+
+  /**
+   * Systemd user unit directory path.
+   */
+  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;
+}
+
+/**
+ * Result returned when creating/adding a new unitup service.
+ */
+export interface AddServiceResult {
+  /**
+   * Cleaned service name.
+   */
+  name: string;
+
+  /**
+   * Path to created unit file.
+   */
+  unitPath: string;
+}
+
+/**
+ * Parsed systemd unit file content metadata.
+ */
+export interface ParsedUnitContent {
+  script?: string;
+  cwd?: string;
+  restart?: string;
+}
+
+/**
+ * Command runner function definition used for internal mocking.
+ */
+export type CommandRunnerFn = (
+  cmd: string,
+  args: string[],
+  opts?: Record<string, unknown>
+) => Promise<{ stdout: string; stderr: string; code: number }>;
+
+// ---------------------------------------------------------------------------
+// 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 getServiceLogs(name: string, options?: LogOptions): Promise<string | ChildProcess>;
+
+// ---------------------------------------------------------------------------
+// System Diagnostics & Doctor
+// ---------------------------------------------------------------------------
+
+export function isSystemdAvailable(): Promise<boolean>;
+export function isSystemctlAvailable(): Promise<boolean>;
+export function isLinux(): boolean;
+export function isSystemdPID1(): Promise<boolean>;
+export function isUserSystemdAvailable(): Promise<boolean>;
+export function checkUserLinger(): Promise<boolean>;
+export function checkNodeDiagnostics(customNodePath?: string): Promise<NodeDiagnostics>;
+export function findNodeExecutable(customPath?: string): Promise<string | null>;
+export function getDoctorInfo(): Promise<DoctorInfo>;
+
+// ---------------------------------------------------------------------------
+// Unit File & Path Helpers
+// ---------------------------------------------------------------------------
+
+export function getUserUnitDir(): string;
+export function getUnitPath(name: string): string;
+export function unitFileExists(name: string): boolean;
+export function parseUnitContent(content: string): ParsedUnitContent;
+export function sanitizeServiceName(name: string): string;
+export function getUnitFilename(name: string): string;
+export function getServiceNameFromUnit(unitFilename: string): string;
+
+// ---------------------------------------------------------------------------
+// Runner Override Helpers for Testing
+// ---------------------------------------------------------------------------
+
+export function setCommandRunner(runner: CommandRunnerFn): void;
+export function resetCommandRunner(): void;

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "unitup",
+  "version": "0.0.1",
+  "description": "Minimal systemd user service wrapper for Node.js scripts",
+  "main": "src/index.js",
+  "types": "./index.d.ts",
+  "type": "module",
+  "bin": {
+    "unitup": "./bin/unitup.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "systemd",
+    "service",
+    "user-service",
+    "systemctl",
+    "node",
+    "cli",
+    "process-manager"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}