@mtakla/cronops 0.1.1-rc7 → 0.1.1

package/README.md

@@ -1,15 +1,16 @@
 # CronOps
 
-[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://github.com/mtakla/cronops/blob/master/LICENSE)
-[![Coverage Status](https://img.shields.io/badge/coverage-95%25-green)](https://img.shields.io/badge/coverage-95%25-green)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://github.com/mtakla/cronops/blob/main/LICENSE)
+[![Coverage Status](https://img.shields.io/badge/Coverage-95%25-green)](https://img.shields.io/badge/coverage-95%25-green)
+[![Docs](https://img.shields.io/badge/TypeDoc-docs-blue)](https://mtakla.github.io/cronops/)
 [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-Donate-orange.svg)](https://www.buymeacoffee.com/nevereven)
 
 **CronOps** is a lightweight, cron-based file management and system task scheduler for containerized environments. It automates copying, moving, archiving, and cleaning up files across mounted volumes — keeping your storage tidy, enabling seamless file exchange between containerized services, and triggering regular tasks in your development, integration or production environments.
 
-> [!WARNING]
-> This project is in early BETA. Production use is not yet recommened!
+⚠ **WARNING**  
+> This project is under active development. Production use is not yet recommended.
 
-## 💡 Why CronOps?
+## Why CronOps?
 
 In containerized workflows, files often accumulate in volumes: downloads, logs, temporary exports, backups. CronOps acts as your **digital janitor**, running scheduled jobs that:
 
@@ -47,6 +48,7 @@ CronOps is built and optimized to run as a Docker container itself.
 
 ```sh
 docker run \
+  --name cronops \
   -p 8083:8083 \
   -v ./config:/config \
   -v ./data:/io/source \
@@ -83,8 +85,8 @@ target:
 
 Now you can add more job configuration files to `./config/jobs`. For detailes, see [job configuration](#job-configuration) section below.
 
-> [!NOTE]
-> You do not need to restart the server after changing job files. The server identifies any changes and will hot reload the configuration. If a job configuration is invalid, an appropriate message will appear in the docker logs and the specific job will not be scheduled.
+🛈 **Note**  
+> You don't need to restart the server after changing job files. The server identifies any changes and will hot reload the configuration. If a job configuration is invalid, an appropriate message will appear in the docker logs and the specific job will not be scheduled.
 
 ### Using Docker Compose
 
@@ -128,28 +130,37 @@ To enable **admin Web-API**, just set `CROPS_API_KEY` environment variable. Deta
 
 This requires [Node.js](https://nodejs.org/) (>= v24) to be installed on your server. 
 
-First step is to create an empty CronOps app directory with a `.env` file that contains your configuration settings, e.g.:
+To install & start CronOps, type:
+
 
-```ini
-CROPS_SOURCE_ROOT=./data                    # change as you like
-CROPS_TARGET_ROOT=./data                    # change as you like
-CROPS_CONFIG_DIR=./config                   # default is ~/.cronops/config
-CROPS_LOG_DIR=./logs                        # default is ~/.cronops/logs
+```sh
+npx @mtakla/cronops
 ```
 
-To install & start CronOps, type:
+For configuration, create an empty folder with an `.env` file that contains your config settings (see [Configuration](#configuration) section below).
+
+```dotenv
+CROPS_CONFIG_DIR=./config
+CROPS_TARGET_ROOT=./data
+CROPS_SOURCE_ROOT=./data
+```
+
+To start CronOps with 
 
-```bash
+```sh
 npx @dotenvx/dotenvx run -- npx @mtakla/cronops
 ```
 
 This will ...
 
-- download the latest version of dotenvx & cronops 
-- load the environment settings defined in the `.env` file
-- start the CronOps service with the loaded environment settings 
-- create config directory in `./config` if it doesn't exist
-- create logs directory in `./logs` if it doesn't exist
+- download the latest version of **dotenvx** and **cronops** 
+- load environment settings defined in the `.env` file
+- create job config directory in `./config` with some example jobs
+- starts the CronOps service
+- the **example job** `[example job]` is active by default and scheduled to run every 5 seconds: 
+  - the job will move files found in `./data/inbox` to `./data/outbox`
+  - in addition, all files moved to `./data/outbox` will be automatically deleted after 30 seconds
+
 
 You can now add job configuration files to `./config/jobs` directory. Each YAML file in this directory defines a job. The server will hot reload when job files are added, modified, or removed.
 
@@ -202,28 +213,30 @@ runner.onError((err) => {
 runner.schedule();
 ```
 
+For more details, see the [TypeDoc documentation](https://mtakla.github.io/cronops/)
+
 
 ## Configuration 
 
 The CronOps service can be configured with the following environment variables:
 
-| ENV                   | Description                                                                                                            | Docker defaults |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------- |
-| `CROPS_SOURCE_ROOT`   | Path to primary source directory                                                                                       | `/io/source`    |
-| `CROPS_TARGET_ROOT`   | Path to primary target directory                                                                                       | `/io/target`    |
-| `CROPS_SOURCE_2_ROOT` | Path to secondary source directory                                                                                     | `/io/source2`   |
-| `CROPS_TARGET_2_ROOT` | Path to secondary target directory                                                                                     | `/io/target2`   |
-| `CROPS_SOURCE_3_ROOT` | Path to tertiary source directory                                                                                      | `/io/source3`   |
-| `CROPS_TARGET_3_ROOT` | Path to tertiary target directory                                                                                      | `/io/target3`   |
-| `CROPS_CONFIG_DIR`    | Path to the config directory where job files are located                                                               | `/config`       |
-| `CROPS_TEMP_DIR`      | Path to temporary folder used for dry-run mode                                                                         | `/data/temp`    |
-| `CROPS_LOG_DIR`       | Path to directory where job logs and file history are stored                                                           | `/data/logs`    |
-| `CROPS_HOST`          | Host address for the Admin API server                                                                                  | `0.0.0.0`       |
-| `CROPS_PORT`          | Port for the Admin API server                                                                                          | `8083`          |
-| `CROPS_EXEC_SHELL`    | (*Optional*) Default shell for `exec` actions. Can be `false`, `true`, or path                                         | `false`         |
-| `CROPS_API_KEY`       | (*Optional*) API key to secure admin API endpoints. Must be a hex‑encoded 256‑bit secret (e.g. 'openssl rand -hex 32') | -               |
-| `CROPS_BASE_URL`      | (*Optional*) Base URL for admin API and OpenAPI docs                                                                   | -               |
-| `TZ`                  | (*Optional*) Timezone for cron scheduling (standard timezone format)                                                   | `UTC`           |
+| ENV                   | Description                                                                                                                | Docker defaults |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------- |
+| `CROPS_SOURCE_ROOT`   | Path to primary source directory                                                                                           | `/io/source`    |
+| `CROPS_TARGET_ROOT`   | Path to primary target directory                                                                                           | `/io/target`    |
+| `CROPS_SOURCE_2_ROOT` | Path to secondary source directory                                                                                         | `/io/source2`   |
+| `CROPS_TARGET_2_ROOT` | Path to secondary target directory                                                                                         | `/io/target2`   |
+| `CROPS_SOURCE_3_ROOT` | Path to tertiary source directory                                                                                          | `/io/source3`   |
+| `CROPS_TARGET_3_ROOT` | Path to tertiary target directory                                                                                          | `/io/target3`   |
+| `CROPS_CONFIG_DIR`    | Path to the config directory where job files are located                                                                   | `/config`       |
+| `CROPS_TEMP_DIR`      | Path to temporary folder used for dry-run mode                                                                             | `/data/temp`    |
+| `CROPS_LOG_DIR`       | Path to directory where job logs and file history are stored                                                               | `/data/logs`    |
+| `CROPS_HOST`          | Host address for the admin API server                                                                                      | `0.0.0.0`       |
+| `CROPS_PORT`          | Port for the admin API server                                                                                              | `8083`          |
+| `CROPS_EXEC_SHELL`    | (*Optional*) Default shell for `exec` actions. Can be `false` (no shell), `true` (default shell), or path like `/bin/bash` | `false`         |
+| `CROPS_API_KEY`       | (*Optional*) API key to secure admin API endpoints. Must be a hex‑encoded 256‑bit secret (e.g. 'openssl rand -hex 32')     | -               |
+| `CROPS_BASE_URL`      | (*Optional*) Base URL for admin API and OpenAPI docs                                                                       | -               |
+| `TZ`                  | (*Optional*) Timezone for cron scheduling (standard timezone format)                                                       | `UTC`           |
 
 
 ## Job Configuration
@@ -249,9 +262,8 @@ dry_run: true
 enabled: false
 ```
 
-> [!NOTE]
-You can change the job configuration at any time and the server will hot reload and schedule the new job configuration.  
-Be aware that once the job config has been changed, active running tasks will be terminated and the job will be rescheduled
+🛈 **Note**
+> You can change the job configuration at any time and the server will hot reload and schedule the new job  configuration. Be aware that once the job config has been changed, active running tasks will be (gracefully) terminated and the job will be rescheduled
 
 ### Job Actions
 
@@ -268,10 +280,10 @@ CronOps supports 5 different job actions:
 
 - **`exec`** - Execute a command or script. Use with `command`, `args`, `shell`, and `env` properties
 
-> [!TIP]
-> **Path References**: Use `$1`, `$2`, or `$3` in job paths to reference configured root directories. 
-> For source paths, these map to `CROPS_SOURCE_ROOT`, `CROPS_SOURCE_2_ROOT`, and `CROPS_SOURCE_3_ROOT`. 
-> For target paths, they map to `CROPS_TARGET_ROOT`, `CROPS_TARGET_2_ROOT`, and `CROPS_TARGET_3_ROOT`.
+💡 **Tip**  
+> Use `$1`, `$2`, or `$3` in job paths to refer to the configured roots.  
+> - **Source:** `$1` → `CROPS_SOURCE_ROOT`, `$2` → `CROPS_SOURCE_2_ROOT`, `$3` → `CROPS_SOURCE_3_ROOT`  
+> - **Target:** `$1` → `CROPS_TARGET_ROOT`, `$2` → `CROPS_TARGET_2_ROOT`, `$3` → `CROPS_TARGET_3_ROOT`
 
 ### Job Configuration examples
 
@@ -403,16 +415,16 @@ If the exec action is configured to run on selected `source` files:
 
 
 
-## Security considerations & Trouble shooting
+## Security considerations 
 
-> [!NOTE]
+🛈 **Note**
 > It is strongly advised against accessing or modifying the data directly on the host system within Docker's internal volume storage path (typically `/var/lib/docker/volumes/`). 
 
-> [!WARNING]
+⚠ **WARNING**
 > **Hazardous Misconfiguration**
 > 
-> By default, CronOps runs as user/group **1000:1000** to follow a security‑first principle.  
-> You *can* run it as root by setting `PUID=0` and `PGID=0`, but **this is dangerous**.
+> By default, the CronOps docker container runs as user/group **1000:1000** to follow a security‑first principle.  
+> You *can* run it as root by setting `PUID=0` and `PGID=0`, but **this is not recommended and can be dangerous**.
 > 
 > When running as root, bind‑mounted host volumes (source/target directories) may map to critical system paths on the host (e.g. `/etc`, `/var`).  
 > This creates a **high‑risk security scenario**:

package/dist/api/openapi.d.ts

@@ -47,7 +47,7 @@ export declare const openapi: {
                     shell: {
                         anyOf: ({
                             type: string;
-                            minLength?: never;
+                            minLength?: undefined;
                         } | {
                             type: string;
                             minLength: number;

package/dist/handlers/ExecHandler.js

@@ -17,7 +17,6 @@ export class ExecHandler extends AbstractHandler {
         await super.cleanup(ctx, fileHistory);
     }
     async exec(ctx, entry) {
-        const { targetDir } = ctx;
         const verbose = ctx.job.verbose === true;
         await new Promise((resolve, reject) => {
             const { vars, env } = this.createVars(ctx, entry);
@@ -42,7 +41,6 @@ export class ExecHandler extends AbstractHandler {
                 stdio: ["ignore", verbose ? logFd : "ignore", verbose ? logFd : "ignore"],
                 shell: ctx.job.shell ?? this.setup.shell,
                 env: { ...process.env, ...env },
-                cwd: targetDir,
             });
             pid = child.pid;
             ctx.writeLog(`◉ Subprocess started (pid:${pid}) ➜ ${cmd} [${args}]`);

package/dist/models/JobRunnerSetup.js

@@ -27,14 +27,14 @@ export class JobRunnerSetup {
     targetRootDirs;
     handlerMap = new Map();
     constructor(options = {}) {
-        this.sourceRoot = resolve(options.sourceRoot ?? process.env[ENV.SOURCE_ROOT] ?? "./");
-        this.targetRoot = resolve(options.targetRoot ?? process.env[ENV.TARGET_ROOT] ?? "./");
-        this.source2Root = resolve(options.source2Root ?? process.env[ENV.SOURCE_2_ROOT] ?? "./");
-        this.target2Root = resolve(options.target2Root ?? process.env[ENV.TARGET_2_ROOT] ?? "./");
-        this.source3Root = resolve(options.source3Root ?? process.env[ENV.SOURCE_3_ROOT] ?? "./");
-        this.target3Root = resolve(options.target3Root ?? process.env[ENV.TARGET_3_ROOT] ?? "./");
-        this.configDir = resolve(options.configDir ?? process.env[ENV.CONFIG_DIR] ?? join(os.homedir(), ".cronops", "config"));
-        this.logDir = resolve(options.logDir ?? process.env[ENV.LOG_DIR] ?? join(os.homedir(), ".cronops", "logs"));
+        this.sourceRoot = resolve(options.sourceRoot ?? process.env[ENV.SOURCE_ROOT] ?? "./data");
+        this.targetRoot = resolve(options.targetRoot ?? process.env[ENV.TARGET_ROOT] ?? "./data");
+        this.source2Root = resolve(options.source2Root ?? process.env[ENV.SOURCE_2_ROOT] ?? "./data");
+        this.target2Root = resolve(options.target2Root ?? process.env[ENV.TARGET_2_ROOT] ?? "./data");
+        this.source3Root = resolve(options.source3Root ?? process.env[ENV.SOURCE_3_ROOT] ?? "./data");
+        this.target3Root = resolve(options.target3Root ?? process.env[ENV.TARGET_3_ROOT] ?? "./data");
+        this.configDir = resolve(options.configDir ?? process.env[ENV.CONFIG_DIR] ?? "./config");
+        this.logDir = resolve(options.logDir ?? process.env[ENV.LOG_DIR] ?? "./logs");
         this.tempDir = resolve(options.tempDir ?? process.env[ENV.TEMP_DIR] ?? join(os.tmpdir(), "cronops"));
         this.uid = options.uid ?? process.env[ENV.PUID] ?? `${process.getuid?.() ?? "0"}`;
         this.gid = options.gid ?? process.env[ENV.PGID] ?? `${process.getgid?.() ?? "0"}`;

package/dist/tasks/AbstractTask.js

@@ -1,4 +1,4 @@
-import cron, {} from "node-cron";
+import cron from "node-cron";
 import { setTimeout } from "node:timers/promises";
 import { EventEmitter } from "node:events";
 import { ENV } from "../types/Options.types.js";

package/dist/types/Config.types.d.ts

@@ -3,11 +3,11 @@ export declare const JobSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     cron: z.ZodOptional<z.ZodString>;
     action: z.ZodEnum<{
+        copy: "copy";
+        delete: "delete";
         exec: "exec";
         call: "call";
-        copy: "copy";
         move: "move";
-        delete: "delete";
         archive: "archive";
     }>;
     command: z.ZodOptional<z.ZodString>;

package/package.json

@@ -1,6 +1,6 @@
 {
    "name": "@mtakla/cronops",
-   "version": "0.1.1-rc7",
+   "version": "0.1.1",
    "description": "Automated cross-container file lifecycle management with cron scheduling",
    "type": "module",
    "author": "mtakla@nevereven",
@@ -66,27 +66,26 @@
       "zod": "4.3.6"
    },
    "devDependencies": {
-      "@biomejs/biome": "^2.3.6",
+      "@biomejs/biome": "^2.4.4",
       "@types/fs-extra": "^11.0.4",
-      "@types/node": "^25.0.3",
+      "@types/node": "^25.3.0",
       "@types/shell-quote": "^1.7.5",
       "@types/tar-fs": "2.0.4",
-      "@vitest/coverage-v8": "^4.0.14",
-      "typedoc": "^0.28.16",
+      "@vitest/coverage-v8": "^4.0.18",
+      "typedoc": "^0.28.17",
       "typescript": "^5.9.3",
-      "vitest": "^4.0.14"
+      "vitest": "^4.0.18"
    },
    "scripts": {
       "check": "biome check",
       "check:fix": "biome check --write",
       "test": "vitest run",
-      "docs": "typedoc",
       "coverage": "vitest run --coverage",
       "loadtest": "tsc && node ./dist/tests/loadtest.js",
-      "clean": "rm -rf dist",
-      "dev": "tsc && node ./dist/server.js",
+      "docs": "typedoc",
       "build": "tsc",
       "build:types": "tsc --declaration",
+      "dev": "tsc --sourceMap --inlineSources && node --env-file=.env.local ./dist/server.js",
       "docker": "docker build --load --target app -t cronops-dev:local .",
       "docker:docs": "docker build --load --target docs -t cronops-docs:local ."
    }