unitup 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to the `unitup` project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.4] - 2026-07-31
+
+### Added
+- Local project configuration file support (`unitup.config.json` and `.unitup.json`).
+- `unitup init` CLI command to create and initialize `unitup.config.json` in any directory with custom script, runtime, name, env, group, memory limits, and runtime arguments.
+- `--config <path>` flag for specifying custom configuration files in `unitup add` and `unitup init`.
+- Biome (`@biomejs/biome`) developer tool integration for code linting and formatting (`npm run check`, `npm run format`, `npm run lint`).
+- `CHANGELOG.md` tracking project release history and changes.
+
+## [0.1.3] - 2026-07-31
+
+### Added
+- Native systemd timer-based task scheduler (`unitup schedule`).
+- Systemd-native memory limits per service (`--memory-high`, `--memory-max`, `--memory-swap-max`, `--default-memory`).
+- System memory overview command (`unitup memory` / `unitup top`).
+- Extended multi-runtime support for Node.js, Python, Ruby, PHP, Bun, Deno, Go, Elixir, Shell scripts, and compiled native executables.
+- Advanced `journald` log streaming filters and maintenance commands (`disk-usage`, `rotate`, `vacuum`).
+- Readiness diagnostics CLI tool (`unitup doctor`).
+- Service grouping support (`@group`).
+
+## [0.1.0] - 2026-07-01
+
+### Added
+- Initial release of `unitup` — minimal, zero-dependency systemd user service wrapper.
+- Basic CLI commands: `add`, `start`, `stop`, `restart`, `status`, `logs`, `remove`, `list`.

package/README.md

@@ -92,6 +92,40 @@ At its core, `unitup` generates systemd service unit files directly from a gener
 
 ## CLI Usage
 
+### Project Configuration (`unitup.config.json`)
+
+You can create a local configuration file in any project directory to define default service settings:
+
+```bash
+# Initialize a unitup.config.json file in the current folder
+unitup init app.js --name my-app --memory-max 512M --env PORT=3000
+
+# Add service using settings from unitup.config.json
+unitup add
+
+# Explicit CLI flags override settings in unitup.config.json
+unitup add --memory-max 1G
+```
+
+Example `unitup.config.json`:
+```json
+{
+  "name": "my-app",
+  "group": "backend",
+  "script": "app.js",
+  "runtime": "node",
+  "env": {
+    "NODE_ENV": "production",
+    "PORT": "3000"
+  },
+  "resources": {
+    "memoryMax": "512M",
+    "memoryHigh": "400M"
+  },
+  "restart": "on-failure"
+}
+```
+
 ### Memory Limits
 
 `unitup` allows you to set native systemd memory limits for your services without running background monitoring daemons:

package/biome.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "ignore": ["node_modules", "dist", "coverage"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 120
+  },
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "style": {
+        "useConstStruct": "off",
+        "noUnusedTemplateLiteral": "off"
+      },
+      "complexity": {
+        "noForEach": "off"
+      },
+      "suspicious": {
+        "noEmptyBlockStatements": "off"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "jsxQuoteStyle": "double",
+      "trailingCommas": "none",
+      "semicolons": "always"
+    }
+  }
+}

package/index.d.ts

@@ -482,6 +482,31 @@ export function checkNodeDiagnostics(customNodePath?: string): Promise<NodeDiagn
 export function findNodeExecutable(customPath?: string): Promise<string | null>;
 export function getDoctorInfo(): Promise<DoctorInfo>;
 
+export interface ProjectConfig {
+  name?: string;
+  group?: string;
+  script?: string;
+  command?: string;
+  runtime?: string;
+  runtimeArgs?: string[];
+  args?: string[];
+  env?: Record<string, string>;
+  envFile?: string;
+  restart?: string;
+  resources?: {
+    memoryHigh?: string;
+    memoryMax?: string;
+    memorySwapMax?: string;
+  };
+  memoryHigh?: string;
+  memoryMax?: string;
+  memorySwapMax?: string;
+}
+
+export function findProjectConfig(dirPath?: string): string | null;
+export function readProjectConfig(filePathOrDir?: string): ProjectConfig | null;
+export function saveProjectConfig(dirPathOrFile?: string, config?: ProjectConfig): string;
+
 // Path & Unit Helpers
 export function getUserUnitDir(): string;
 export function getUnitPath(name: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitup",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Minimal, zero-dependency systemd-native service manager for any runtime, script, or executable",
   "main": "src/index.js",
   "types": "./index.d.ts",
@@ -9,9 +9,13 @@
     "unitup": "bin/unitup.js"
   },
   "scripts": {
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*.test.js",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "check": "biome check ."
   },
   "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
     "typescript": "^5.7.3"
   },
   "keywords": [

package/src/cli.js

@@ -32,7 +32,16 @@ import {
   disableSchedule,
   removeSchedule
 } from './schedule.js';
-import { sanitizeServiceName, formatTable, readGlobalConfig, saveGlobalConfig, validateMemorySize } from './utils.js';
+import {
+  sanitizeServiceName,
+  formatTable,
+  readGlobalConfig,
+  saveGlobalConfig,
+  validateMemorySize,
+  findProjectConfig,
+  readProjectConfig,
+  saveProjectConfig
+} from './utils.js';
 
 /**
  * Custom light CLI argument parser without runtime dependencies.
@@ -51,6 +60,7 @@ export function parseArgs(argv) {
       command: '',
       node: '',
       cwd: '',
+      config: '',
       env: [],
       envFile: '',
       restart: 'on-failure',
@@ -108,12 +118,15 @@ export function parseArgs(argv) {
     } else if (arg.startsWith('--runtime=')) {
       result.flags.runtime = arg.slice(10);
       i++;
-    } else if (arg === '--runtime-arg') {
+    } else if (arg === '--runtime-arg' || arg === '--runtime-args') {
       if (argv[i + 1]) result.flags.runtimeArgs.push(argv[i + 1]);
       i += 2;
     } else if (arg.startsWith('--runtime-arg=')) {
       result.flags.runtimeArgs.push(arg.slice(14));
       i++;
+    } else if (arg.startsWith('--runtime-args=')) {
+      result.flags.runtimeArgs.push(arg.slice(15));
+      i++;
     } else if (arg === '--command') {
       result.flags.command = argv[i + 1] || '';
       i += 2;
@@ -144,6 +157,12 @@ export function parseArgs(argv) {
     } else if (arg.startsWith('--cwd=')) {
       result.flags.cwd = arg.slice(6);
       i++;
+    } else if (arg === '--config') {
+      result.flags.config = argv[i + 1] || '';
+      i += 2;
+    } else if (arg.startsWith('--config=')) {
+      result.flags.config = arg.slice(9);
+      i++;
     } else if (arg === '--env') {
       if (argv[i + 1]) result.flags.env.push(argv[i + 1]);
       i += 2;
@@ -162,12 +181,15 @@ export function parseArgs(argv) {
     } else if (arg.startsWith('--restart=')) {
       result.flags.restart = arg.slice(10);
       i++;
-    } else if (arg === '--arg') {
+    } else if (arg === '--arg' || arg === '--args') {
       if (argv[i + 1]) result.flags.args.push(argv[i + 1]);
       i += 2;
     } else if (arg.startsWith('--arg=')) {
       result.flags.args.push(arg.slice(6));
       i++;
+    } else if (arg.startsWith('--args=')) {
+      result.flags.args.push(arg.slice(7));
+      i++;
     } else if (arg === '--lines' || arg === '-n') {
       result.flags.lines = parseInt(argv[i + 1] || '100', 10);
       i += 2;
@@ -344,6 +366,7 @@ unitup - Minimal systemd user service wrapper for any executable & runtime
 
 Usage:
   unitup doctor                 Run system readiness and runtime check
+  unitup init [script]          Create local project config file (unitup.config.json)
   unitup add <script> [options] Add script or executable as systemd user service
   unitup start <name|@group>    Start a service (--enable to enable on boot)
   unitup stop <name|@group>     Stop a service
@@ -357,6 +380,9 @@ Usage:
   unitup memory / unitup top    Show memory usage for all apps or a specific app
   unitup config                 Manage global configuration (--default-memory 1G)
 
+Config Options:
+  --config <path>        Path to custom project config file (defaults to unitup.config.json)
+
 Schedule Commands:
   unitup schedule <script> [options] Create a systemd timer schedule
   unitup schedules / unitup timers    List all schedule timers
@@ -434,10 +460,86 @@ export async function runCli(argv = process.argv.slice(2)) {
         break;
       }
 
-      case 'add': {
+      case 'init': {
+        const targetCwd = flags.cwd ? path.resolve(process.cwd(), flags.cwd) : process.cwd();
+        const configFilename = flags.config || 'unitup.config.json';
+        const targetConfigPath = path.resolve(targetCwd, configFilename);
+
+        if (fs.existsSync(targetConfigPath) && !flags.force) {
+          throw new Error(
+            `Configuration file "${path.basename(targetConfigPath)}" already exists at ${targetConfigPath}.\n` +
+            `Use --force (-f) to overwrite.`
+          );
+        }
+
         const scriptArg = positionals[0];
+        let scriptPath = scriptArg || '';
         let name = flags.name;
-        let absScriptPath = scriptArg ? path.resolve(process.cwd(), scriptArg) : undefined;
+        if (!name) {
+          if (scriptPath) {
+            const baseName = path.basename(scriptPath);
+            const ext = path.extname(baseName);
+            name = ext ? baseName.slice(0, -ext.length) : baseName;
+          } else {
+            name = path.basename(targetCwd);
+          }
+        }
+
+        const envObj = {};
+        for (const e of flags.env) {
+          const idx = e.indexOf('=');
+          if (idx !== -1) {
+            envObj[e.slice(0, idx)] = e.slice(idx + 1);
+          } else {
+            envObj[e] = '';
+          }
+        }
+
+        const projectCfg = {
+          name,
+          ...(scriptPath ? { script: scriptPath } : {}),
+          ...(flags.command ? { command: flags.command } : {}),
+          ...(flags.runtime ? { runtime: flags.runtime } : {}),
+          ...(flags.runtimeArgs && flags.runtimeArgs.length > 0 ? { runtimeArgs: flags.runtimeArgs } : {}),
+          group: flags.group || 'default',
+          ...(Object.keys(envObj).length > 0 ? { env: envObj } : {}),
+          ...(flags.envFile ? { envFile: flags.envFile } : {}),
+          ...(flags.restart ? { restart: flags.restart } : { restart: 'on-failure' }),
+          ...(flags.args && flags.args.length > 0 ? { args: flags.args } : {})
+        };
+
+        if (flags.memoryMax || flags.memoryHigh || flags.memorySwapMax) {
+          projectCfg.resources = {};
+          if (flags.memoryHigh) projectCfg.resources.memoryHigh = flags.memoryHigh;
+          if (flags.memoryMax) projectCfg.resources.memoryMax = flags.memoryMax;
+          if (flags.memorySwapMax) projectCfg.resources.memorySwapMax = flags.memorySwapMax;
+        }
+
+        const writtenPath = saveProjectConfig(targetConfigPath, projectCfg);
+        console.log(`✓ Project configuration created at ${writtenPath}`);
+        console.log(`Run "unitup add" to register service from configuration.`);
+        break;
+      }
+
+      case 'add': {
+        const targetCwd = flags.cwd ? path.resolve(process.cwd(), flags.cwd) : process.cwd();
+        const configPath = flags.config ? path.resolve(targetCwd, flags.config) : findProjectConfig(targetCwd);
+        const projectCfg = configPath ? readProjectConfig(configPath) : null;
+
+        const scriptArg = positionals[0] || (projectCfg ? projectCfg.script : undefined);
+        let name = flags.name || (projectCfg ? projectCfg.name : undefined);
+        let cmdFlag = flags.command || (projectCfg ? projectCfg.command : undefined);
+        let runtimeFlag = flags.runtime || (projectCfg ? projectCfg.runtime : undefined);
+        let groupFlag = flags.group || (projectCfg ? projectCfg.group : undefined) || 'default';
+        let restartFlag = flags.restart !== 'on-failure' ? flags.restart : ((projectCfg && projectCfg.restart) || 'on-failure');
+        let envFileFlag = flags.envFile || (projectCfg ? projectCfg.envFile : undefined);
+        let argsFlag = (flags.args && flags.args.length > 0) ? flags.args : ((projectCfg && projectCfg.args) || []);
+        let runtimeArgsFlag = (flags.runtimeArgs && flags.runtimeArgs.length > 0) ? flags.runtimeArgs : ((projectCfg && projectCfg.runtimeArgs) || []);
+        let memoryHighFlag = flags.memoryHigh || (projectCfg?.resources?.memoryHigh || projectCfg?.memoryHigh || '');
+        let memoryMaxFlag = flags.memoryMax || (projectCfg?.resources?.memoryMax || projectCfg?.memoryMax || '');
+        let memorySwapMaxFlag = flags.memorySwapMax || (projectCfg?.resources?.memorySwapMax || projectCfg?.memorySwapMax || '');
+
+        let absScriptPath = scriptArg ? path.resolve(targetCwd, scriptArg) : undefined;
 
         if (flags.node) {
           const resolvedNode = await findNodeExecutable(flags.node);
@@ -446,14 +548,14 @@ export async function runCli(argv = process.argv.slice(2)) {
           }
         }
 
-        if (flags.command) {
+        if (cmdFlag) {
           if (!name) {
             if (scriptArg) {
               const baseName = path.basename(scriptArg);
               const ext = path.extname(baseName);
               name = ext ? baseName.slice(0, -ext.length) : baseName;
             } else {
-              const baseCmd = path.basename(flags.command);
+              const baseCmd = path.basename(cmdFlag);
               name = baseCmd;
             }
           }
@@ -471,7 +573,7 @@ export async function runCli(argv = process.argv.slice(2)) {
           }
         }
 
-        const envObj = {};
+        const envObj = (projectCfg && projectCfg.env && typeof projectCfg.env === 'object') ? { ...projectCfg.env } : {};
         for (const e of flags.env) {
           const idx = e.indexOf('=');
           if (idx !== -1) {
@@ -483,21 +585,21 @@ export async function runCli(argv = process.argv.slice(2)) {
 
         const res = await addService({
           name,
-          group: flags.group || 'default',
+          group: groupFlag,
           script: absScriptPath,
-          command: flags.command,
-          runtime: flags.runtime,
-          runtimeArgs: flags.runtimeArgs,
+          command: cmdFlag,
+          runtime: runtimeFlag,
+          runtimeArgs: runtimeArgsFlag,
           nodePath: flags.node,
-          cwd: flags.cwd ? path.resolve(process.cwd(), flags.cwd) : (absScriptPath ? path.dirname(absScriptPath) : process.cwd()),
+          cwd: targetCwd,
           env: envObj,
-          envFile: flags.envFile ? path.resolve(process.cwd(), flags.envFile) : undefined,
-          restart: flags.restart,
-          args: flags.args,
+          envFile: envFileFlag ? path.resolve(targetCwd, envFileFlag) : undefined,
+          restart: restartFlag,
+          args: argsFlag,
           start: flags.start,
-          memoryHigh: flags.memoryHigh,
-          memoryMax: flags.memoryMax,
-          memorySwapMax: flags.memorySwapMax,
+          memoryHigh: memoryHighFlag,
+          memoryMax: memoryMaxFlag,
+          memorySwapMax: memorySwapMaxFlag,
           defaultMemory: flags.defaultMemory,
           force: flags.force
         });

package/src/index.js

@@ -58,6 +58,9 @@ import {
   readGlobalConfig,
   saveGlobalConfig,
   getConfigFilepath,
+  findProjectConfig,
+  readProjectConfig,
+  saveProjectConfig,
   resolveEffectiveMemoryLimits,
   getSchedulesDir,
   getAppsDir,
@@ -115,6 +118,9 @@ export {
   readGlobalConfig,
   saveGlobalConfig,
   getConfigFilepath,
+  findProjectConfig,
+  readProjectConfig,
+  saveProjectConfig,
   resolveEffectiveMemoryLimits,
   getSchedulesDir,
   getAppsDir,

package/src/systemd.js

@@ -5,8 +5,10 @@ import path from 'node:path';
 import {
   sanitizeServiceName,
   getUnitFilename,
+  getTimerFilename,
   formatRelativeTime,
-  readAppMetadata
+  readAppMetadata,
+  readScheduleMetadata
 } from './utils.js';
 import {
   getUserUnitDir,
@@ -516,7 +518,7 @@ export async function getServiceStatus(name) {
     ? formatRelativeTime(startedRaw)
     : 'never';
 
-  const meta = readAppMetadata(safeName);
+  const meta = readAppMetadata(safeName) || readScheduleMetadata(safeName);
   const command = meta?.command || parsed.command || meta?.node || process.execPath;
   const argsList = meta?.args || (parsed.script ? [parsed.script] : []);
 
@@ -555,7 +557,7 @@ export async function getServicesByGroup(groupName) {
   const units = listUnitFiles();
   const matched = [];
   for (const unit of units) {
-    const meta = readAppMetadata(unit.name);
+    const meta = readAppMetadata(unit.name) || readScheduleMetadata(unit.name);
     const itemGroup = meta?.group || 'default';
     if (itemGroup.toLowerCase() === cleanGroup.toLowerCase()) {
       matched.push(unit.name);
@@ -572,7 +574,7 @@ export async function listServices(filterOpts = {}) {
     : null;
 
   for (const unit of units) {
-    const meta = readAppMetadata(unit.name);
+    const meta = readAppMetadata(unit.name) || readScheduleMetadata(unit.name);
     const group = meta?.group || 'default';
     const runtime = meta?.runtime || 'node';
 
@@ -604,14 +606,35 @@ export async function listServices(filterOpts = {}) {
       const unitFileState = show.UnitFileState || 'unknown';
 
       let status = 'stopped';
-      if (activeState === 'active' && subState === 'running') {
-        status = 'running';
-      } else if (activeState === 'failed') {
-        status = 'failed';
-      } else if (activeState === 'active') {
-        status = subState;
+      if (meta?.type === 'timer' || meta?.schedule) {
+        if (activeState === 'active' && subState === 'running') {
+          status = 'running';
+        } else if (activeState === 'failed') {
+          status = 'failed';
+        } else {
+          try {
+            const timerShow = await getServiceShow(getTimerFilename(unit.name));
+            if (timerShow.ActiveState === 'active') {
+              status = 'scheduled';
+            } else if (timerShow.UnitFileState === 'disabled' || timerShow.ActiveState === 'inactive') {
+              status = 'disabled';
+            } else {
+              status = 'scheduled';
+            }
+          } catch {
+            status = 'scheduled';
+          }
+        }
       } else {
-        status = 'stopped';
+        if (activeState === 'active' && subState === 'running') {
+          status = 'running';
+        } else if (activeState === 'failed') {
+          status = 'failed';
+        } else if (activeState === 'active') {
+          status = subState;
+        } else {
+          status = 'stopped';
+        }
       }
 
       const enabled = unitFileState.startsWith('enabled') ? 'yes' : 'no';
@@ -657,16 +680,32 @@ export async function inspectService(name) {
     throw new Error(`Service "${safeName}" does not exist.`);
   }
 
-  const meta = readAppMetadata(safeName);
+  const meta = readAppMetadata(safeName) || readScheduleMetadata(safeName);
   const statusObj = await getServiceStatus(safeName);
 
+  let inspectStatus = statusObj.status;
+  if ((meta?.type === 'timer' || meta?.schedule) && inspectStatus === 'stopped') {
+    try {
+      const timerShow = await getServiceShow(getTimerFilename(safeName));
+      if (timerShow.ActiveState === 'active') {
+        inspectStatus = 'scheduled';
+      } else if (timerShow.UnitFileState === 'disabled' || timerShow.ActiveState === 'inactive') {
+        inspectStatus = 'disabled';
+      } else {
+        inspectStatus = 'scheduled';
+      }
+    } catch {
+      inspectStatus = 'scheduled';
+    }
+  }
+
   const command = meta?.command || statusObj.command || statusObj.node || process.execPath;
   const argsList = meta?.args || (statusObj.script ? [statusObj.script] : []);
 
   return {
     name: safeName,
     runtime: meta?.runtime || 'node',
-    status: statusObj.status,
+    status: inspectStatus,
     activeState: statusObj.activeState,
     subState: statusObj.subState,
     command,

package/src/utils.js

@@ -174,16 +174,26 @@ export function saveAppMetadata(meta) {
  */
 export function readAppMetadata(name) {
   try {
-    const filePath = getAppMetadataPath(name);
+    let filePath = getAppMetadataPath(name);
+    if (!fs.existsSync(filePath)) {
+      filePath = getScheduleMetadataPath(name);
+    }
     if (!fs.existsSync(filePath)) return null;
     const content = fs.readFileSync(filePath, 'utf8');
     const data = JSON.parse(content);
     if (!data) return null;
 
-    // Normalization for legacy metadata format
     const command = data.command || data.node || process.execPath;
     const args = data.args || (data.script ? [data.script] : []);
-    const runtime = data.runtime || 'node';
+    let runtime = data.runtime;
+    if (!runtime || (runtime === 'node' && data.command)) {
+      const baseCmd = path.basename(command).toLowerCase();
+      if (baseCmd !== 'node' && baseCmd !== 'nodejs') {
+        runtime = 'custom';
+      } else {
+        runtime = 'node';
+      }
+    }
     const script = data.script || args[0] || command;
     const cwd = data.cwd || (script ? path.dirname(script) : process.cwd());
 
@@ -472,7 +482,7 @@ export function saveScheduleMetadata(meta) {
     name: safeName,
     group: meta.group || 'default',
     type: 'timer',
-    runtime: meta.runtime || 'node',
+    runtime: meta.runtime || (meta.command ? 'custom' : 'node'),
     command,
     args,
     cwd: meta.cwd ? resolveAbsolutePath(meta.cwd) : process.cwd(),
@@ -502,7 +512,17 @@ export function readScheduleMetadata(name) {
     const filePath = getScheduleMetadataPath(name);
     if (!fs.existsSync(filePath)) return null;
     const content = fs.readFileSync(filePath, 'utf8');
-    return JSON.parse(content);
+    const meta = JSON.parse(content);
+    if (!meta) return null;
+
+    // Normalization for legacy metadata format where runtime defaulted to 'node' for custom commands
+    if (meta.runtime === 'node' && meta.command) {
+      const baseCmd = path.basename(meta.command).toLowerCase();
+      if (baseCmd !== 'node' && baseCmd !== 'nodejs') {
+        meta.runtime = 'custom';
+      }
+    }
+    return meta;
   } catch {
     return null;
   }
@@ -679,4 +699,64 @@ export function resolveEffectiveMemoryLimits(opts = {}) {
   return {};
 }
 
+/**
+ * Finds the project configuration file path if it exists in the target directory.
+ * Standard names checked: unitup.config.json, .unitup.json
+ *
+ * @param {string} [dirPath=process.cwd()]
+ * @returns {string|null}
+ */
+export function findProjectConfig(dirPath = process.cwd()) {
+  const dir = path.resolve(dirPath);
+  const candidates = ['unitup.config.json', '.unitup.json'];
+  for (const file of candidates) {
+    const full = path.join(dir, file);
+    if (fs.existsSync(full)) {
+      return full;
+    }
+  }
+  return null;
+}
+
+/**
+ * Reads a project configuration file.
+ *
+ * @param {string} [filePathOrDir=process.cwd()]
+ * @returns {object|null}
+ */
+export function readProjectConfig(filePathOrDir = process.cwd()) {
+  try {
+    let filePath = filePathOrDir;
+    if (fs.existsSync(filePath) && fs.statSync(filePath).isDirectory()) {
+      filePath = findProjectConfig(filePath);
+    }
+    if (!filePath || !fs.existsSync(filePath)) return null;
+    const content = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(content) || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Saves a project configuration file (`unitup.config.json`).
+ *
+ * @param {string} [dirPathOrFile=process.cwd()]
+ * @param {object} config
+ * @returns {string} File path written to
+ */
+export function saveProjectConfig(dirPathOrFile = process.cwd(), config = {}) {
+  let filePath = dirPathOrFile;
+  if (!filePath.endsWith('.json')) {
+    filePath = path.join(filePath, 'unitup.config.json');
+  }
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(filePath, JSON.stringify(config, null, 2), 'utf8');
+  return filePath;
+}
+
+