cronpipe 0.1.0

package/README.md

@@ -0,0 +1,220 @@
+# cronpipe
+
+Run scripts on a schedule with optional gate and finalise pipeline control.
+
+- **Simple intervals** — `10m`, `2h`, `1d` or full cron syntax
+- **Gate scripts** — conditionally skip a run based on exit code
+- **Finalise scripts** — run cleanup or reporting after the main script
+- **Overlap-safe** — if a run is still in progress at the next tick, the tick is skipped
+- **Logging** — timestamped, labelled output to console and/or log file
+- **Cross-platform** — Windows and Linux/Mac
+- **Multi-script support** — `.js`, `.ps1`, and `.sh` scripts
+
+## Usage
+
+### Single job — `cronpipe`
+
+```bash
+npx cronpipe --run <script> [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--run <script>` | **(required)** Script to run |
+| `--gate <script>` | Run only if this exits `0` |
+| `--post-gate <script>` | Run finalise only if this exits `0` |
+| `--finalise <script>` | Script to run after the agent |
+| `--schedule <expr>` | Interval or cron expression (omit to run once) |
+| `--name <label>` | Label shown in log output |
+| `--log <file>` | Append all output to a log file |
+
+```bash
+# Run once
+npx cronpipe --run ./script.js
+
+# Run every 10 minutes
+npx cronpipe --run ./script.js --schedule 10m
+
+# Full pipeline, hourly, with logging
+npx cronpipe \
+  --name my-job \
+  --gate ./gate.sh \
+  --run ./script.js \
+  --post-gate ./post-gate.js \
+  --finalise ./finalise.ps1 \
+  --schedule 1h \
+  --log ./my-job.log
+
+# Cron syntax — every day at midnight
+npx cronpipe --run ./script.js --schedule "0 0 * * *"
+```
+
+### Multiple jobs — `cronpipe-ctl`
+
+Define all jobs in a config file and run them together in a single process:
+
+```bash
+npx cronpipe-ctl <config-file>
+```
+
+## Schedule expressions
+
+| Format | Example | Description |
+|--------|---------|-------------|
+| Milliseconds | `500ms` | Every 500 milliseconds |
+| Seconds | `30s` | Every 30 seconds |
+| Minutes | `10m` | Every 10 minutes |
+| Hours | `2h` | Every 2 hours |
+| Days | `1d` | Every day |
+| Cron | `0 9 * * 1-5` | 9am on weekdays |
+
+Simple intervals run immediately on startup, then repeat. Cron expressions follow standard 5-field syntax.
+
+## Pipeline
+
+Each job runs four steps in order. Optional steps are skipped when not provided.
+
+```
+gate? ──► run ──► post-gate? ──► finalise?
+```
+
+- **gate** — if provided and exits non-zero, the entire run is skipped
+- **run** — always runs if gate passes (or no gate is provided)
+- **post-gate** — if provided and exits non-zero, finalise is skipped
+- **finalise** — runs after agent if post-gate passes (or no post-gate is provided)
+
+### Overlap protection
+
+If a run is still in progress when the next tick fires, the tick is silently skipped. The running job is never interrupted and no backlog builds up — execution simply resumes at the following tick.
+
+```
+[cronpipe] previous run still in progress — skipping tick
+```
+
+## Logging
+
+All script output is timestamped and prefixed with `[name:step]` so output from different jobs and pipeline steps stays identifiable.
+
+```
+2026-04-08 09:00:01 [my-job:gate] checking conditions...
+2026-04-08 09:00:01 [my-job:run] starting task
+2026-04-08 09:00:03 [my-job:run] task complete
+2026-04-08 09:00:03 [my-job:finalise] sending report
+```
+
+Use `--log <file>` to append the same output to a file alongside the console. The file is appended to, not overwritten, so logs accumulate across restarts.
+
+## Script types
+
+The runner detects the script type from the file extension:
+
+| Extension | Runner |
+|-----------|--------|
+| `.js` `.mjs` `.cjs` | `node` |
+| `.ps1` | `powershell.exe` (Windows) / `pwsh` (Linux/Mac) |
+| `.sh` | `bash` |
+| *(none)* | `powershell.exe` (Windows) / `bash` (Linux/Mac) |
+
+Scripts communicate pass/fail via exit code — `0` means pass, anything else means fail.
+
+**Node.js example (gate):**
+```js
+// gate.js — allow run only between 9am–5pm
+const hour = new Date().getHours();
+process.exit(hour >= 9 && hour < 17 ? 0 : 1);
+```
+
+**Bash example (gate):**
+```bash
+#!/bin/bash
+# gate.sh — skip if a lock file exists
+[ -f /tmp/task.lock ] && exit 1
+exit 0
+```
+
+**PowerShell example (gate):**
+```powershell
+# gate.ps1 — skip on weekends
+$day = (Get-Date).DayOfWeek
+if ($day -eq 'Saturday' -or $day -eq 'Sunday') { exit 1 }
+exit 0
+```
+
+## Config file format (`cronpipe-ctl`)
+
+Pipe-delimited, one job per line. Use `-` for optional fields you need to skip over.
+
+```
+# schedule | gate | run | post-gate | finalise | log-file
+```
+
+```
+# Just schedule and run script
+10m | ./script.js
+
+# Gate + run (no finalise)
+1h | ./gate.sh | ./script.js
+
+# Skip gate, run finalise (- holds the gate position)
+1h | - | ./script.js | - | ./finalise.js
+
+# Full pipeline with log file
+0 9 * * 1-5 | ./gate.ps1 | ./script.ps1 | ./post-gate.ps1 | ./finalise.ps1 | ./logs/job.log
+
+# Mix of script types
+30m | ./gate.js | ./script.sh | - | ./finalise.ps1
+```
+
+- Trailing optional fields can be omitted entirely
+- `-` is only needed to skip an earlier field when a later one is specified
+- Lines starting with `#` are comments
+
+See [`example.agentctl`](example.agentctl) for a complete annotated example.
+
+## Long-running processes
+
+`npx` is best suited for one-off runs. For persistent scheduled jobs, install globally and manage with a process manager:
+
+```bash
+npm install -g cronpipe
+```
+
+**Linux (pm2):**
+```bash
+pm2 start "cronpipe-ctl jobs.agentctl" --name cronpipe
+pm2 save
+pm2 startup
+```
+
+**Windows (pm2):**
+```powershell
+pm2 start "cronpipe-ctl jobs.agentctl" --name cronpipe
+pm2 save
+pm2 startup
+```
+
+**Linux (systemd):** create `/etc/systemd/system/cronpipe.service`:
+```ini
+[Unit]
+Description=cronpipe
+
+[Service]
+ExecStart=/usr/bin/cronpipe-ctl /path/to/jobs.agentctl
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+```bash
+systemctl enable --now cronpipe
+```
+
+## Requirements
+
+- Node.js 18 or later
+- `bash` for `.sh` scripts (pre-installed on Linux/Mac; use Git Bash or WSL on Windows)
+- `pwsh` for `.ps1` scripts on Linux/Mac ([PowerShell Core](https://github.com/PowerShell/PowerShell))
+
+## License
+
+MIT

package/bin/cronpipe-ctl.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const { program } = require('commander');
+const { parseConfig } = require('../src/config-parser');
+const { runPipeline } = require('../src/runner');
+const { schedule } = require('../src/scheduler');
+const { version } = require('../package.json');
+
+program
+  .name('cronpipe-ctl')
+  .description('Run multiple cronpipe jobs defined in a config file')
+  .version(version)
+  .argument('<config>', 'Path to cronpipe-ctl config file')
+  .parse();
+
+const [configFile] = program.args;
+
+let jobs;
+try {
+  jobs = parseConfig(configFile);
+} catch (err) {
+  console.error(`[cronpipe-ctl] Failed to read config: ${err.message}`);
+  process.exit(1);
+}
+
+if (jobs.length === 0) {
+  console.error('[cronpipe-ctl] No valid jobs found in config file');
+  process.exit(1);
+}
+
+console.log(`[cronpipe-ctl] Loaded ${jobs.length} job(s) from ${configFile}`);
+
+for (const job of jobs) {
+  const label = job.name ?? job.run;
+  const logStream = job.logFile
+    ? fs.createWriteStream(job.logFile, { flags: 'a' })
+    : null;
+
+  try {
+    schedule(job.schedule, () => runPipeline({ ...job, logStream }));
+    const logNote = job.logFile ? ` → ${job.logFile}` : '';
+    console.log(`[cronpipe-ctl] Scheduled "${label}" — ${job.schedule}${logNote}`);
+  } catch (err) {
+    console.error(`[cronpipe-ctl] Failed to schedule "${label}": ${err.message}`);
+  }
+}

package/bin/cronpipe.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const { program } = require('commander');
+const { runPipeline } = require('../src/runner');
+const { schedule } = require('../src/scheduler');
+const { version } = require('../package.json');
+
+program
+  .name('cronpipe')
+  .description('Run a script with optional gate and finalise pipeline control')
+  .version(version)
+  .requiredOption('--run <script>',      'Script to run (.js, .sh, .ps1)')
+  .option('--gate <script>',               'Gate script — script runs only if this exits 0')
+  .option('--post-gate <script>',          'Post-gate script — finalise runs only if this exits 0')
+  .option('--finalise <script>',           'Finalise script to run after the main script')
+  .option('--schedule <expr>',             'Run on a schedule: simple interval (10m, 1h, 1d) or cron syntax')
+  .option('--name <label>',                'Label shown in log output')
+  .option('--log <file>',                  'Append all script output to a log file')
+  .parse();
+
+const opts = program.opts();
+
+const logStream = opts.log
+  ? fs.createWriteStream(opts.log, { flags: 'a' })
+  : null;
+
+const config = {
+  gate:      opts.gate     ?? null,
+  run:     opts.run,
+  postGate:  opts.postGate ?? null,
+  finalise:  opts.finalise ?? null,
+  name:      opts.name     ?? '',
+  logStream,
+};
+
+if (opts.schedule) {
+  try {
+    schedule(opts.schedule, () => runPipeline(config));
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+} else {
+  runPipeline(config).catch((err) => {
+    console.error('[cronpipe] fatal:', err.message);
+    process.exit(1);
+  });
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "cronpipe",
+  "version": "0.1.0",
+  "description": "Run agent scripts on a schedule with gate/finalise pipeline control",
+  "files": ["bin", "src"],
+  "bin": {
+    "cronpipe": "./bin/cronpipe.js",
+    "cronpipe-ctl": "./bin/cronpipe-ctl.js"
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.js",
+    "lint": "eslint src bin"
+  },
+  "keywords": ["agent", "cron", "scheduler", "automation"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "node-cron": "^3.0.3"
+  }
+}

package/src/config-parser.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const fs = require('fs');
+
+/**
+ * Parses an cronpipe-ctl config file.
+ *
+ * Format (pipe-delimited, one job per line):
+ *
+ *   # comment
+ *   schedule | run
+ *   schedule | gate | run | post-gate | finalise | log-file
+ *
+ * All fields except schedule and run are optional — use "-" or leave empty.
+ *
+ * Examples:
+ *   10m | ./run.js                                                    (agent only)
+ *   1h  | ./gate.sh | ./run.js                                        (gate + agent)
+ *   1h  | - | ./run.js | - | ./finalise.ps1                           (- holds position)
+ *   0 * * * * | ./gate.sh | ./run.js | ./post.js | ./done.js          (full pipeline)
+ *   10m | - | ./run.js | - | - | ./logs/agent.log                     (with log file)
+ *
+ * @param {string} filePath - Path to the config file
+ * @returns {Array<{schedule, gate, run, postGate, finalise}>}
+ */
+function parseConfig(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const jobs = [];
+
+  const lines = content.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line || line.startsWith('#')) continue;
+
+    const parts = line.split('|').map((p) => p.trim());
+    const norm = (v) => (!v || v === '-' ? null : v);
+
+    let schedule, gate, run, postGate, finalise, logFile;
+
+    if (parts.length === 2) {
+      // schedule | run  (no gate)
+      [schedule, run] = parts;
+    } else if (parts.length >= 3) {
+      // schedule | gate | run | [post-gate] | [finalise] | [log-file]
+      [schedule, gate, run, postGate, finalise, logFile] = parts;
+    } else {
+      console.warn(`[cronpipe-ctl] line ${i + 1}: skipping — needs at least "schedule | run"`);
+      continue;
+    }
+
+    if (!norm(run)) {
+      console.warn(`[cronpipe-ctl] line ${i + 1}: skipping — run script is required`);
+      continue;
+    }
+
+    jobs.push({
+      schedule: schedule.trim(),
+      gate: norm(gate),
+      run: norm(run),
+      postGate: norm(postGate),
+      finalise: norm(finalise),
+      logFile: norm(logFile),
+    });
+  }
+
+  return jobs;
+}
+
+module.exports = { parseConfig };

package/src/runner.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const { runScript } = require('./script-runner');
+
+/**
+ * Executes the agent pipeline:
+ *
+ *   gate? → run → post-gate? → finalise?
+ *
+ * @param {object} opts
+ * @param {string|null} opts.gate       - Path to gate script (optional)
+ * @param {string}      opts.run      - Path to agent script (required)
+ * @param {string|null} opts.postGate   - Path to post-gate script (optional)
+ * @param {string|null} opts.finalise   - Path to finalise script (optional)
+ * @param {string}      [opts.name]     - Label prefix used in log output
+ * @param {import('fs').WriteStream} [opts.logStream] - Optional file log stream
+ */
+async function runPipeline({ gate, run, postGate, finalise, name = '', logStream = null }) {
+  const label = (step) => name ? `${name}:${step}` : step;
+  const log = (msg) => {
+    console.log(msg);
+    logStream?.write(msg + '\n');
+  };
+
+  if (gate) {
+    log(`[cronpipe] gate: ${gate}`);
+    const code = await runScript(gate, { label: label('gate'), logStream });
+    if (code !== 0) {
+      log(`[cronpipe] gate exited ${code} — skipping run`);
+      return;
+    }
+  }
+
+  log(`[cronpipe] run: ${run}`);
+  await runScript(run, { label: label('run'), logStream });
+
+  if (postGate) {
+    log(`[cronpipe] post-gate: ${postGate}`);
+    const code = await runScript(postGate, { label: label('post-gate'), logStream });
+    if (code !== 0) {
+      log(`[cronpipe] post-gate exited ${code} — skipping finalise`);
+      return;
+    }
+  }
+
+  if (finalise) {
+    log(`[cronpipe] finalise: ${finalise}`);
+    await runScript(finalise, { label: label('finalise'), logStream });
+  }
+}
+
+module.exports = { runPipeline };

package/src/scheduler.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const cron = require('node-cron');
+
+// Matches simple interval expressions: 500ms, 30s, 10m, 2h, 1d
+const INTERVAL_RE = /^(\d+)(ms|s|m|h|d)$/;
+const MULTIPLIERS = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+
+/**
+ * Parses a simple interval string (e.g. "10m", "1h") into milliseconds.
+ * Returns null if the string is not a simple interval.
+ */
+function parseInterval(expr) {
+  const match = expr.match(INTERVAL_RE);
+  if (!match) return null;
+  return parseInt(match[1], 10) * MULTIPLIERS[match[2]];
+}
+
+/**
+ * Schedules a function to run on a given expression.
+ *
+ * Expression can be:
+ *   - Simple interval: "30s", "10m", "2h", "1d"  (runs immediately, then repeats)
+ *   - Cron syntax:     "0 * * * *"               (standard 5-field cron)
+ *
+ * Returns an object with a `stop()` method to cancel the schedule.
+ *
+ * @param {string}   expr  - Schedule expression
+ * @param {function} fn    - Async-safe callback (errors are caught and logged)
+ * @returns {{ stop: function }}
+ */
+function schedule(expr, fn) {
+  let running = false;
+
+  const safeRun = () => {
+    if (running) {
+      console.log('[cronpipe] previous run still in progress — skipping tick');
+      return;
+    }
+    running = true;
+    Promise.resolve(fn())
+      .catch((err) => console.error('[cronpipe] pipeline error:', err.message))
+      .finally(() => { running = false; });
+  };
+
+  const ms = parseInterval(expr);
+  if (ms !== null) {
+    safeRun(); // run immediately on first tick
+    const timer = setInterval(safeRun, ms);
+    return { stop: () => clearInterval(timer) };
+  }
+
+  if (cron.validate(expr)) {
+    const task = cron.schedule(expr, safeRun);
+    return { stop: () => task.stop() };
+  }
+
+  throw new Error(
+    `Invalid schedule expression: "${expr}".\n` +
+    'Use a simple interval (30s, 10m, 2h, 1d) or standard cron syntax (e.g. "0 * * * *").'
+  );
+}
+
+module.exports = { schedule, parseInterval };

package/src/script-runner.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const { spawn } = require('child_process');
+const path = require('path');
+const os = require('os');
+
+const isWindows = os.platform() === 'win32';
+
+function resolveScriptCommand(scriptPath) {
+  const ext = path.extname(scriptPath).toLowerCase();
+
+  switch (ext) {
+    case '.js':
+    case '.mjs':
+    case '.cjs':
+      return { cmd: process.execPath, args: [scriptPath] };
+
+    case '.ps1':
+      return isWindows
+        ? { cmd: 'powershell.exe', args: ['-NonInteractive', '-File', scriptPath] }
+        : { cmd: 'pwsh', args: ['-NonInteractive', '-File', scriptPath] };
+
+    case '.sh':
+      return { cmd: 'bash', args: [scriptPath] };
+
+    default:
+      return isWindows
+        ? { cmd: 'powershell.exe', args: ['-NonInteractive', '-File', scriptPath] }
+        : { cmd: 'bash', args: [scriptPath] };
+  }
+}
+
+function timestamp() {
+  return new Date().toISOString().replace('T', ' ').slice(0, 19);
+}
+
+/**
+ * Pipes a readable stream line-by-line, prefixing each line and optionally
+ * writing to a log file stream alongside the given output stream.
+ */
+function forwardLines(source, output, prefix, logStream) {
+  let buf = '';
+  source.on('data', (chunk) => {
+    buf += chunk.toString();
+    const lines = buf.split('\n');
+    buf = lines.pop(); // hold incomplete last line
+    for (const line of lines) {
+      const formatted = `${timestamp()} ${prefix} ${line}\n`;
+      output.write(formatted);
+      logStream?.write(formatted);
+    }
+  });
+  source.on('end', () => {
+    if (buf) {
+      const formatted = `${timestamp()} ${prefix} ${buf}\n`;
+      output.write(formatted);
+      logStream?.write(formatted);
+      buf = '';
+    }
+  });
+}
+
+/**
+ * Runs a script and resolves with its exit code.
+ *
+ * @param {string} scriptPath
+ * @param {object} [opts]
+ * @param {string} [opts.label]      - Prefix label for all output lines
+ * @param {import('fs').WriteStream} [opts.logStream] - Optional file log stream
+ */
+function runScript(scriptPath, { label = '', logStream = null } = {}) {
+  const { cmd, args } = resolveScriptCommand(scriptPath);
+  const prefix = label ? `[${label}]` : '';
+
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, { stdio: ['inherit', 'pipe', 'pipe'] });
+
+    forwardLines(proc.stdout, process.stdout, prefix, logStream);
+    forwardLines(proc.stderr, process.stderr, prefix, logStream);
+
+    proc.on('close', (code) => resolve(code ?? 0));
+    proc.on('error', reject);
+  });
+}
+
+module.exports = { runScript, resolveScriptCommand };