unitup 0.0.8 → 0.0.9

package/README.md

@@ -78,18 +78,30 @@ npm install unitup
 # 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
+# 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
 
-# 3. Check service status
-unitup status api
+# 3. List all services with status, PID, uptime, restarts
+unitup list
+# or alias
+unitup ls --group myproject
 
-# 4. Stream real-time journalctl logs
-unitup logs api --follow
+# 4. Perform batch control operations on a group using @group syntax
+unitup restart @myproject
+unitup stop @myproject
 
-# 5. Stop or remove service when no longer needed
-unitup stop api
-unitup remove api
+# 5. Inspect application configuration and status (excluding secrets)
+unitup inspect api
+
+# 6. Check for failed services
+unitup failures
+
+# 7. Stream logs or view clean console output
+unitup logs api -c --follow
+
+# 8. Remove a service or an entire group
+unitup remove @myproject
 ```
 
 ---

package/index.d.ts

@@ -14,6 +14,12 @@ export interface CreateServiceOptions {
    */
   name: string;
 
+  /**
+   * Optional group name (e.g. 'myproject').
+   * @default 'default'
+   */
+  group?: string;
+
   /**
    * Absolute or relative path to the target Node.js script.
    */
@@ -154,6 +160,11 @@ export interface ListServiceItem {
    */
   name: string;
 
+  /**
+   * Group name.
+   */
+  group: string;
+
   /**
    * Status overview ('running', 'stopped', 'failed', etc.).
    */
@@ -163,6 +174,64 @@ export interface ListServiceItem {
    * Enabled status ('yes' or 'no').
    */
   enabled: string;
+
+  /**
+   * Main PID or '-'.
+   */
+  pid: string;
+
+  /**
+   * Formatted uptime string.
+   */
+  uptime: string;
+
+  /**
+   * Restart count.
+   */
+  restarts: string;
+}
+
+/**
+ * App metadata saved in ~/.config/unitup/apps/<name>.json.
+ */
+export interface AppMetadata {
+  name: string;
+  unit: string;
+  group: string;
+  script: string;
+  cwd: string;
+  node: string;
+}
+
+/**
+ * Detailed application inspection summary (unitup inspect).
+ */
+export interface InspectInfo {
+  name: string;
+  unit: string;
+  unitPath: string;
+  group: string;
+  script: string;
+  cwd: string;
+  node: string;
+  status: string;
+  activeState: string;
+  subState: string;
+  pid: string;
+  restarts: string;
+  started: string;
+}
+
+/**
+ * Failed service failure report item (unitup failures).
+ */
+export interface FailureItem {
+  name: string;
+  group: string;
+  status: string;
+  exitCode: string;
+  restarts: string;
+  uptime: string;
 }
 
 /**
@@ -347,8 +416,24 @@ export function getServiceStatusRaw(name: string): Promise<string>;
 
 /**
  * Lists all unitup-*.service user units.
+ * Optionally filter by group name.
+ */
+export function listServices(options?: { group?: string }): Promise<ListServiceItem[]>;
+
+/**
+ * Inspects a service's configuration and status (unitup inspect).
+ */
+export function inspectService(name: string): Promise<InspectInfo>;
+
+/**
+ * Retrieves all currently failed services (unitup failures).
+ */
+export function getServiceFailures(): Promise<FailureItem[]>;
+
+/**
+ * Returns array of service names belonging to a group (@groupName).
  */
-export function listServices(): Promise<ListServiceItem[]>;
+export function getServicesByGroup(groupName: string): Promise<string[]>;
 
 /**
  * Fetches or streams journalctl logs for a service.
@@ -380,6 +465,10 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitup",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "Minimal systemd user service wrapper for Node.js scripts",
   "main": "src/index.js",
   "types": "./index.d.ts",

package/src/cli.js

@@ -13,7 +13,10 @@ import {
   runJournalctlLogs,
   isLinux,
   isSystemctlAvailable,
-  findNodeExecutable
+  findNodeExecutable,
+  getServicesByGroup,
+  inspectService,
+  getServiceFailures
 } from './systemd.js';
 import { sanitizeServiceName, formatTable } from './utils.js';
 
@@ -28,6 +31,7 @@ export function parseArgs(argv) {
     positionals: [],
     flags: {
       name: '',
+      group: '',
       node: '',
       cwd: '',
       env: [],
@@ -68,6 +72,12 @@ export function parseArgs(argv) {
     } else if (arg.startsWith('--name=')) {
       result.flags.name = arg.slice(7);
       i++;
+    } else if (arg === '--group') {
+      result.flags.group = argv[i + 1] || '';
+      i += 2;
+    } else if (arg.startsWith('--group=')) {
+      result.flags.group = arg.slice(8);
+      i++;
     } else if (arg === '--cwd') {
       result.flags.cwd = argv[i + 1] || '';
       i += 2;
@@ -148,16 +158,20 @@ unitup - Minimal systemd user service wrapper for Node.js scripts
 Usage:
   unitup doctor                 Run system readiness check
   unitup add <script> [options] Add script as systemd user service
-  unitup start <name>           Start a service (--enable to enable on boot)
-  unitup stop <name>            Stop a service
-  unitup restart <name>         Restart a service
-  unitup status <name>          Show status summary (--raw for full status)
-  unitup logs <name>            Show journalctl logs (--follow, --lines N)
-  unitup remove <name>          Stop, disable and delete a service
-  unitup list                   List all unitup user services
+  unitup start <name|@group>    Start a service (--enable to enable on boot)
+  unitup stop <name|@group>     Stop a service
+  unitup restart <name|@group>  Restart a service
+  unitup status <name|@group>   Show status summary (--raw for full status)
+  unitup logs <name|@group>     Show journalctl logs (-f/--follow, -n/--lines N, -c/--cat)
+  unitup inspect <name>         View detailed app configuration and status
+  unitup failures               List all failed services with exit code & restarts
+  unitup remove <name|@group>   Stop, disable and delete a service
+  unitup list / unitup ls       List all services (--group <group>)
 
 Add Options:
   --name <name>       Service name (default: script name)
+  --group <group>     Assign service to a group (default: default)
+  --node <path>       Custom Node.js executable path
   --cwd <path>        Working directory
   --restart <policy>  Restart policy (on-failure, always, etc. Default: on-failure)
   --env KEY=value     Environment variable (can be specified multiple times)
@@ -166,13 +180,26 @@ Add Options:
   --start             Enable and start service immediately after creation
 
 Examples:
-  unitup add server.js --name api --env NODE_ENV=production --start
-  unitup status api
-  unitup logs api --follow
-  unitup remove api
+  unitup add server.js --name api --group myproject --start
+  unitup list --group myproject
+  unitup start @myproject
+  unitup inspect api
+  unitup failures
+  unitup remove @myproject
 `);
 }
 
+async function resolveTargetNames(target) {
+  if (target && target.startsWith('@')) {
+    const list = await getServicesByGroup(target);
+    if (list.length === 0) {
+      throw new Error(`No services found in group "${target}".`);
+    }
+    return list;
+  }
+  return [target];
+}
+
 /**
  * Main CLI runner entrypoint.
  *
@@ -241,6 +268,7 @@ export async function runCli(argv = process.argv.slice(2)) {
 
         const res = await addService({
           name,
+          group: flags.group || 'default',
           script: absScriptPath,
           nodePath: resolvedNode,
           cwd: flags.cwd ? path.resolve(process.cwd(), flags.cwd) : path.dirname(absScriptPath),
@@ -261,90 +289,164 @@ export async function runCli(argv = process.argv.slice(2)) {
       }
 
       case 'start': {
-        const name = positionals[0];
-        if (!name) {
-          throw new Error('Service name is required.\nExample: unitup start api');
+        const nameArg = positionals[0];
+        if (!nameArg) {
+          throw new Error('Service name or @group is required.\nExample: unitup start api or unitup start @myproject');
+        }
+        const targetNames = await resolveTargetNames(nameArg);
+        for (const name of targetNames) {
+          await startService(name, flags.enable);
+          console.log(`✓ Service "${sanitizeServiceName(name)}" ${flags.enable ? 'enabled & ' : ''}started.`);
         }
-        await startService(name, flags.enable);
-        console.log(`✓ Service "${sanitizeServiceName(name)}" ${flags.enable ? 'enabled & ' : ''}started.`);
         break;
       }
 
       case 'stop': {
-        const name = positionals[0];
-        if (!name) {
-          throw new Error('Service name is required.\nExample: unitup stop api');
+        const nameArg = positionals[0];
+        if (!nameArg) {
+          throw new Error('Service name or @group is required.\nExample: unitup stop api or unitup stop @myproject');
+        }
+        const targetNames = await resolveTargetNames(nameArg);
+        for (const name of targetNames) {
+          await stopService(name);
+          console.log(`✓ Service "${sanitizeServiceName(name)}" stopped.`);
         }
-        await stopService(name);
-        console.log(`✓ Service "${sanitizeServiceName(name)}" stopped.`);
         break;
       }
 
       case 'restart': {
-        const name = positionals[0];
-        if (!name) {
-          throw new Error('Service name is required.\nExample: unitup restart api');
+        const nameArg = positionals[0];
+        if (!nameArg) {
+          throw new Error('Service name or @group is required.\nExample: unitup restart api or unitup restart @myproject');
+        }
+        const targetNames = await resolveTargetNames(nameArg);
+        for (const name of targetNames) {
+          await restartService(name);
+          console.log(`✓ Service "${sanitizeServiceName(name)}" restarted.`);
         }
-        await restartService(name);
-        console.log(`✓ Service "${sanitizeServiceName(name)}" restarted.`);
         break;
       }
 
       case 'status': {
-        const name = positionals[0];
-        if (!name) {
-          throw new Error('Service name is required.\nExample: unitup status api');
+        const nameArg = positionals[0];
+        if (!nameArg) {
+          throw new Error('Service name or @group is required.\nExample: unitup status api or unitup status @myproject');
         }
 
-        if (flags.raw) {
-          const raw = await getServiceStatusRaw(name);
-          console.log(raw);
-        } else {
-          const status = await getServiceStatus(name);
-          console.log(`${status.name}\n`);
-          console.log(`Status: ${status.status}`);
-          console.log(`PID: ${status.pid}`);
-          console.log(`Started: ${status.started}`);
-          console.log(`Restarts: ${status.restarts}`);
-          console.log(`Script: ${status.script}`);
-          console.log(`Working directory: ${status.cwd}`);
+        const targetNames = await resolveTargetNames(nameArg);
+        for (const name of targetNames) {
+          if (flags.raw) {
+            const raw = await getServiceStatusRaw(name);
+            console.log(raw);
+          } else {
+            const status = await getServiceStatus(name);
+            console.log(`${status.name}\n`);
+            console.log(`Status: ${status.status}`);
+            console.log(`PID: ${status.pid}`);
+            console.log(`Started: ${status.started}`);
+            console.log(`Restarts: ${status.restarts}`);
+            console.log(`Script: ${status.script}`);
+            console.log(`Working directory: ${status.cwd}`);
+          }
         }
         break;
       }
 
       case 'logs': {
-        const name = positionals[0];
-        if (!name) {
-          throw new Error('Service name is required.\nExample: unitup logs api');
+        const nameArg = positionals[0];
+        if (!nameArg) {
+          throw new Error('Service name or @group is required.\nExample: unitup logs api or unitup logs @myproject');
         }
-        const output = await runJournalctlLogs(name, {
-          follow: flags.follow,
-          lines: flags.lines,
-          cat: flags.cat,
-          output: flags.output
-        });
-        if (typeof output === 'string') {
-          console.log(output);
+
+        const targetNames = await resolveTargetNames(nameArg);
+        for (const name of targetNames) {
+          if (targetNames.length > 1) {
+            console.log(`=== Logs for ${name} ===`);
+          }
+          const output = await runJournalctlLogs(name, {
+            follow: flags.follow,
+            lines: flags.lines,
+            cat: flags.cat,
+            output: flags.output
+          });
+          if (typeof output === 'string') {
+            console.log(output);
+          }
         }
         break;
       }
 
       case 'remove': {
-        const name = positionals[0];
-        if (!name) {
-          throw new Error('Service name is required.\nExample: unitup remove api');
+        const nameArg = positionals[0];
+        if (!nameArg) {
+          throw new Error('Service name or @group is required.\nExample: unitup remove api or unitup remove @myproject');
+        }
+        const targetNames = await resolveTargetNames(nameArg);
+        for (const name of targetNames) {
+          await removeService(name);
+          console.log(`✓ Service "${sanitizeServiceName(name)}" removed.`);
         }
-        await removeService(name);
-        console.log(`✓ Service "${sanitizeServiceName(name)}" removed.`);
         break;
       }
 
+      case 'ls':
       case 'list': {
-        const services = await listServices();
+        const services = await listServices({ group: flags.group });
+        if (services.length === 0) {
+          if (flags.group) {
+            console.log(`No services found in group "${flags.group}".`);
+          } else {
+            console.log('No unitup user services found.');
+          }
+          break;
+        }
+
         const table = formatTable(services, [
           { key: 'name', label: 'NAME' },
+          { key: 'group', label: 'GROUP' },
+          { key: 'status', label: 'STATUS' },
+          { key: 'pid', label: 'PID' },
+          { key: 'uptime', label: 'UPTIME' },
+          { key: 'restarts', label: 'RESTARTS' }
+        ]);
+        console.log(table);
+        break;
+      }
+
+      case 'inspect': {
+        const nameArg = positionals[0];
+        if (!nameArg) {
+          throw new Error('Service name is required.\nExample: unitup inspect api');
+        }
+        const info = await inspectService(nameArg);
+        console.log(`App: ${info.name}`);
+        console.log(`Group: ${info.group}`);
+        console.log(`Status: ${info.status} (${info.activeState}/${info.subState})`);
+        console.log(`PID: ${info.pid}`);
+        console.log(`Restarts: ${info.restarts}`);
+        console.log(`Uptime: ${info.started}`);
+        console.log(`Script: ${info.script}`);
+        console.log(`Working directory: ${info.cwd}`);
+        console.log(`Node path: ${info.node}`);
+        console.log(`Unit file: ${info.unit}`);
+        console.log(`Unit path: ${info.unitPath}`);
+        break;
+      }
+
+      case 'failures': {
+        const failures = await getServiceFailures();
+        if (failures.length === 0) {
+          console.log('✓ No failed services.');
+          break;
+        }
+
+        const table = formatTable(failures, [
+          { key: 'name', label: 'NAME' },
+          { key: 'group', label: 'GROUP' },
           { key: 'status', label: 'STATUS' },
-          { key: 'enabled', label: 'ENABLED' }
+          { key: 'exitCode', label: 'EXIT_CODE' },
+          { key: 'restarts', label: 'RESTARTS' },
+          { key: 'uptime', label: 'UPTIME' }
         ]);
         console.log(table);
         break;

package/src/index.js

@@ -7,6 +7,9 @@ import {
   getServiceStatus,
   getServiceStatusRaw,
   listServices,
+  inspectService,
+  getServiceFailures,
+  getServicesByGroup,
   runJournalctlLogs,
   isLinux,
   isSystemctlAvailable,
@@ -28,7 +31,11 @@ import {
 import {
   sanitizeServiceName,
   getUnitFilename,
-  getServiceNameFromUnit
+  getServiceNameFromUnit,
+  readAppMetadata,
+  getAppMetadataPath,
+  getAppsDir,
+  getUnitupDir
 } from './utils.js';
 
 export {
@@ -42,8 +49,17 @@ export {
   getServiceStatus,
   getServiceStatusRaw,
   listServices,
+  inspectService,
+  getServiceFailures,
+  getServicesByGroup,
   runJournalctlLogs as getServiceLogs,
 
+  // Metadata helpers
+  readAppMetadata,
+  getAppMetadataPath,
+  getAppsDir,
+  getUnitupDir,
+
   // System & Doctor checks
   isSystemctlAvailable as isSystemdAvailable,
   isSystemctlAvailable,

package/src/systemd.js

@@ -5,7 +5,8 @@ import path from 'node:path';
 import {
   sanitizeServiceName,
   getUnitFilename,
-  formatRelativeTime
+  formatRelativeTime,
+  readAppMetadata
 } from './utils.js';
 import {
   getUserUnitDir,
@@ -289,6 +290,17 @@ export async function addService(opts) {
 }
 
 export async function startService(name, enable = false) {
+  if (name && typeof name === 'string' && name.startsWith('@')) {
+    const list = await getServicesByGroup(name);
+    if (list.length === 0) {
+      throw new Error(`No services found in group "${name}".`);
+    }
+    for (const s of list) {
+      await startService(s, enable);
+    }
+    return true;
+  }
+
   const safeName = sanitizeServiceName(name);
   if (!unitFileExists(safeName)) {
     throw new Error(`Service "${safeName}" does not exist.\nCreate it with: unitup add <script> --name ${safeName}`);
@@ -306,6 +318,17 @@ export async function startService(name, enable = false) {
 }
 
 export async function stopService(name) {
+  if (name && typeof name === 'string' && name.startsWith('@')) {
+    const list = await getServicesByGroup(name);
+    if (list.length === 0) {
+      throw new Error(`No services found in group "${name}".`);
+    }
+    for (const s of list) {
+      await stopService(s);
+    }
+    return true;
+  }
+
   const safeName = sanitizeServiceName(name);
   if (!unitFileExists(safeName)) {
     throw new Error(`Service "${safeName}" does not exist.`);
@@ -319,6 +342,17 @@ export async function stopService(name) {
 }
 
 export async function restartService(name) {
+  if (name && typeof name === 'string' && name.startsWith('@')) {
+    const list = await getServicesByGroup(name);
+    if (list.length === 0) {
+      throw new Error(`No services found in group "${name}".`);
+    }
+    for (const s of list) {
+      await restartService(s);
+    }
+    return true;
+  }
+
   const safeName = sanitizeServiceName(name);
   if (!unitFileExists(safeName)) {
     throw new Error(`Service "${safeName}" does not exist.`);
@@ -332,6 +366,17 @@ export async function restartService(name) {
 }
 
 export async function removeService(name) {
+  if (name && typeof name === 'string' && name.startsWith('@')) {
+    const list = await getServicesByGroup(name);
+    if (list.length === 0) {
+      throw new Error(`No services found in group "${name}".`);
+    }
+    for (const s of list) {
+      await removeService(s);
+    }
+    return true;
+  }
+
   const safeName = sanitizeServiceName(name);
   if (!unitFileExists(safeName)) {
     throw new Error(`Service "${safeName}" does not exist.`);
@@ -435,11 +480,35 @@ export async function getServiceStatus(name) {
   };
 }
 
-export async function listServices() {
+export async function getServicesByGroup(groupName) {
+  const cleanGroup = groupName.startsWith('@') ? groupName.slice(1) : groupName;
+  const units = listUnitFiles();
+  const matched = [];
+  for (const unit of units) {
+    const meta = readAppMetadata(unit.name);
+    const itemGroup = meta?.group || 'default';
+    if (itemGroup.toLowerCase() === cleanGroup.toLowerCase()) {
+      matched.push(unit.name);
+    }
+  }
+  return matched;
+}
+
+export async function listServices(filterOpts = {}) {
   const units = listUnitFiles();
   const result = [];
+  const targetGroup = filterOpts.group
+    ? (filterOpts.group.startsWith('@') ? filterOpts.group.slice(1) : filterOpts.group).toLowerCase()
+    : null;
 
   for (const unit of units) {
+    const meta = readAppMetadata(unit.name);
+    const group = meta?.group || 'default';
+
+    if (targetGroup && group.toLowerCase() !== targetGroup) {
+      continue;
+    }
+
     try {
       const show = await getServiceShow(unit.name);
       const activeState = show.ActiveState || 'inactive';
@@ -458,17 +527,31 @@ export async function listServices() {
       }
 
       const enabled = unitFileState.startsWith('enabled') ? 'yes' : 'no';
+      const pid = show.MainPID && show.MainPID !== '0' ? show.MainPID : '-';
+      const restarts = show.NRestarts ?? '0';
+      const startedRaw = show.ActiveEnterTimestamp;
+      const uptime = startedRaw && startedRaw !== '0' && startedRaw !== 'n/a'
+        ? formatRelativeTime(startedRaw)
+        : 'never';
 
       result.push({
         name: unit.name,
+        group,
         status,
-        enabled
+        enabled,
+        pid,
+        uptime,
+        restarts
       });
     } catch {
       result.push({
         name: unit.name,
+        group,
         status: 'unknown',
-        enabled: 'unknown'
+        enabled: 'unknown',
+        pid: '-',
+        uptime: 'never',
+        restarts: '0'
       });
     }
   }
@@ -476,6 +559,54 @@ export async function listServices() {
   return result;
 }
 
+export async function inspectService(name) {
+  const safeName = sanitizeServiceName(name);
+  if (!unitFileExists(safeName)) {
+    throw new Error(`Service "${safeName}" does not exist.`);
+  }
+
+  const meta = readAppMetadata(safeName);
+  const statusObj = await getServiceStatus(safeName);
+
+  return {
+    name: safeName,
+    unit: getUnitFilename(safeName),
+    unitPath: getUnitPath(safeName),
+    group: meta?.group || 'default',
+    script: meta?.script || statusObj.script,
+    cwd: meta?.cwd || statusObj.cwd,
+    node: meta?.node || process.execPath,
+    status: statusObj.status,
+    activeState: statusObj.activeState,
+    subState: statusObj.subState,
+    pid: statusObj.pid,
+    restarts: statusObj.restarts,
+    started: statusObj.started
+  };
+}
+
+export async function getServiceFailures() {
+  const allServices = await listServices();
+  const failures = [];
+
+  for (const item of allServices) {
+    if (item.status === 'failed') {
+      const show = await getServiceShow(item.name);
+      const exitCode = show.ExecMainStatus || show.ExecMainCode || '1';
+      failures.push({
+        name: item.name,
+        group: item.group,
+        status: 'failed',
+        exitCode: String(exitCode),
+        restarts: item.restarts,
+        uptime: item.uptime
+      });
+    }
+  }
+
+  return failures;
+}
+
 export async function runJournalctlLogs(name, opts = {}) {
   const safeName = sanitizeServiceName(name);
   const unitFilename = getUnitFilename(safeName);

package/src/unit.js

@@ -4,9 +4,12 @@ import os from 'node:os';
 import {
   sanitizeServiceName,
   getUnitFilename,
+  getServiceNameFromUnit,
   formatSystemdEnv,
   escapeExecArg,
-  resolveAbsolutePath
+  resolveAbsolutePath,
+  saveAppMetadata,
+  deleteAppMetadata
 } from './utils.js';
 
 /**
@@ -130,6 +133,13 @@ export function writeUnitFile(opts) {
   const content = generateUnitContent({ ...opts, name: safeName });
 
   fs.writeFileSync(unitPath, content, 'utf8');
+  saveAppMetadata({
+    name: safeName,
+    group: opts.group || 'default',
+    script: opts.script,
+    cwd: opts.cwd,
+    node: opts.nodePath
+  });
 
   return { path: unitPath, content };
 }
@@ -141,7 +151,9 @@ export function writeUnitFile(opts) {
  * @returns {boolean} True if file existed and was removed
  */
 export function deleteUnitFile(name) {
-  const unitPath = getUnitPath(name);
+  const safeName = sanitizeServiceName(name);
+  deleteAppMetadata(safeName);
+  const unitPath = getUnitPath(safeName);
   if (fs.existsSync(unitPath)) {
     fs.unlinkSync(unitPath);
     return true;

package/src/utils.js

@@ -1,5 +1,90 @@
 import path from 'node:path';
 import os from 'node:os';
+import fs from 'node:fs';
+
+/**
+ * Returns the base unitup config directory (~/.config/unitup).
+ * @returns {string}
+ */
+export function getUnitupDir() {
+  const configHome = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(configHome, 'unitup');
+}
+
+/**
+ * Returns the directory for app metadata (~/.config/unitup/apps).
+ * @returns {string}
+ */
+export function getAppsDir() {
+  return path.join(getUnitupDir(), 'apps');
+}
+
+/**
+ * Returns the filepath for a specific service's metadata JSON file.
+ * @param {string} name
+ * @returns {string}
+ */
+export function getAppMetadataPath(name) {
+  const safeName = sanitizeServiceName(name);
+  return path.join(getAppsDir(), `${safeName}.json`);
+}
+
+/**
+ * Saves metadata JSON for a service.
+ * @param {object} meta
+ * @returns {object}
+ */
+export function saveAppMetadata(meta) {
+  const safeName = sanitizeServiceName(meta.name);
+  const dir = getAppsDir();
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const filePath = getAppMetadataPath(safeName);
+  const scriptPath = resolveAbsolutePath(meta.script);
+  const payload = {
+    name: safeName,
+    unit: getUnitFilename(safeName),
+    group: meta.group || 'default',
+    script: scriptPath,
+    cwd: meta.cwd ? resolveAbsolutePath(meta.cwd) : path.dirname(scriptPath),
+    node: meta.node ? resolveAbsolutePath(meta.node) : process.execPath
+  };
+  fs.writeFileSync(filePath, JSON.stringify(payload, null, 2), 'utf8');
+  return payload;
+}
+
+/**
+ * Reads metadata JSON for a service.
+ * @param {string} name
+ * @returns {object|null}
+ */
+export function readAppMetadata(name) {
+  try {
+    const filePath = getAppMetadataPath(name);
+    if (!fs.existsSync(filePath)) return null;
+    const content = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Deletes metadata JSON for a service if it exists.
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function deleteAppMetadata(name) {
+  try {
+    const filePath = getAppMetadataPath(name);
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+      return true;
+    }
+  } catch {}
+  return false;
+}
 
 /**
  * Sanitizes a service name to ensure it is safe for systemd unit filenames.