@wonsukchoi/crondex 0.14.0 → 0.15.0

package/README.md

@@ -35,14 +35,22 @@ npx @wonsukchoi/crondex deploy ssl-cert-expiry-check --var host=example.com
 - `show <id>` — print a job's full YAML
 - `add <id> [--dest path]` — copy it into your project to edit
 - `init <id> [--category x]` — scaffold a brand-new job from the template
-- `deploy <id> [--target crontab|github-actions] [--var name=value ...]`
+- `update <path>` — re-pull a job you already `add`ed/`init`ed (matched by
+  its `id` field) against the current catalog and overwrite it in place
+- `deploy <id> [--target crontab|github-actions|systemd|docker] [--var name=value ...]`
   — turn a job into something that actually runs: prints a ready crontab
-  line (or installs it into your own crontab with `--install`), or writes
-  a scheduled GitHub Actions workflow file. `--var` overrides a variable's
-  default (repeatable). `hybrid` jobs deploy their `command` by default;
-  pass `--mode prompt` to deploy the `prompt` side instead — for a
-  crontab target that means wiring in your own agent CLI via a
-  `CRONDEX_AGENT_CLI` env var, since crondex can't guess its syntax.
+  line (or installs it into your own crontab with `--install`), writes a
+  scheduled GitHub Actions workflow file, writes a systemd
+  `<id>.service` + `<id>.timer` pair, or writes a Dockerfile + `/etc/cron.d`
+  entry that runs the job on its own schedule in a container. `--var`
+  overrides a variable's default (repeatable). `hybrid` jobs deploy their
+  `command` by default; pass `--mode prompt` to deploy the `prompt` side
+  instead — for crontab/systemd/docker targets that means wiring in your
+  own agent CLI via a `CRONDEX_AGENT_CLI` env var, since crondex can't
+  guess its syntax.
+- `deploy --list-installed` — show every crondex-managed line in your
+  crontab (the ones left by `--install`)
+- `uninstall <id>` — remove one of those installed crontab entries
 
 Add `--json` to `list`/`categories`/`show`/`recommend` for machine-readable
 output — useful when an agent is parsing the result programmatically
@@ -156,7 +164,7 @@ tags, variables) use `crondex list`, `crondex recommend`, or browse
 ```
 crondex/
 ├── llms.txt               agent-discovery manifest (llms.txt convention)
-├── bin/crondex.js         CLI: list / categories / show / add / recommend / init / deploy
+├── bin/crondex.js         CLI: list / categories / show / add / recommend / init / update / deploy / uninstall
 ├── lib/                   recommend, deploy, and catalog-building logic (unit tested in test/)
 ├── catalog.json           generated index of every job — read this first
 ├── schema/job.schema.json spec every job file follows

package/bin/crondex.js

@@ -6,7 +6,15 @@ import { execFileSync } from "node:child_process";
 import yaml from "js-yaml";
 import { tokenize, rankJobs } from "../lib/recommend.js";
 import { CATEGORY_DESCRIPTIONS } from "../lib/category-descriptions.js";
-import { resolveVariables, substitutePlaceholders, pickMode, buildCrontabLine, buildGithubActionsWorkflow } from "../lib/deploy.js";
+import {
+  resolveVariables,
+  substitutePlaceholders,
+  pickMode,
+  buildCrontabLine,
+  buildGithubActionsWorkflow,
+  buildSystemdUnits,
+  buildDockerArtifacts,
+} from "../lib/deploy.js";
 
 const ROOT = new URL("..", import.meta.url).pathname;
 const CATALOG = JSON.parse(readFileSync(join(ROOT, "catalog.json"), "utf8"));
@@ -59,8 +67,11 @@ Usage:
   crondex add <id> [--dest <path>]
   crondex recommend "<what you want done>" [--limit <n>] [--json]
   crondex init <id> [--category <name>] [--dest <path>]
-  crondex deploy <id> [--target crontab|github-actions] [--mode script|prompt]
+  crondex update <path>
+  crondex deploy <id> [--target crontab|github-actions|systemd|docker] [--mode script|prompt]
                       [--var name=value ...] [--dest <path>] [--install]
+  crondex deploy --list-installed [--json]
+  crondex uninstall <id>
 
 Examples:
   crondex list --category devops
@@ -69,8 +80,13 @@ Examples:
   crondex add backup-reminder --dest ./cron/backup-reminder.yaml
   crondex recommend "warn me before my SSL cert expires"
   crondex init ssl-cert-expiry-check --category security
+  crondex update ./cron/backup-reminder.yaml
   crondex deploy ssl-cert-expiry-check --var host=example.com --var port=443
   crondex deploy repo-health-check --target github-actions
+  crondex deploy repo-health-check --target systemd --dest ./systemd
+  crondex deploy repo-health-check --target docker --dest ./docker/repo-health-check
+  crondex deploy --list-installed
+  crondex uninstall ssl-cert-expiry-check
 
 Add --json to list/categories/show/recommend for machine-readable output —
 useful when an agent is parsing crondex's output programmatically instead
@@ -79,9 +95,19 @@ of a human reading it.
 deploy turns a job into something you can actually run: --target crontab
 (default) prints a ready crontab line, or installs it into your own
 crontab with --install; --target github-actions writes a scheduled
-workflow file (default .github/workflows/<id>.yml). --var overrides a
-job's variable defaults (repeatable). hybrid jobs default to --mode script
-(zero tokens); pass --mode prompt to deploy the agent-prompt side instead.
+workflow file (default .github/workflows/<id>.yml); --target systemd
+writes a <id>.service + <id>.timer pair (default ./systemd/); --target
+docker writes a Dockerfile + crontab pair that runs the job on its own
+schedule in a container (default ./docker/<id>/). --var overrides a job's
+variable defaults (repeatable). hybrid jobs default to --mode script (zero
+tokens); pass --mode prompt to deploy the agent-prompt side instead.
+
+deploy --list-installed shows every crondex-managed line in your crontab
+(the ones with a "# crondex:<id>" marker, as left by --install). uninstall
+removes one of those by id.
+
+update re-pulls a job you already added/inited (matched by its "id" field)
+against the current catalog and overwrites the local file in place.
 `);
 }
 
@@ -194,22 +220,80 @@ function init(id) {
   console.log(`wrote ${dest} — fill in the fields, then \`npm run validate\` (see CONTRIBUTING.md to submit it upstream).`);
 }
 
-function installCrontabLine(id, line) {
-  let existing = "";
+function readCrontab() {
   try {
-    existing = execFileSync("crontab", ["-l"], { encoding: "utf8" });
+    return execFileSync("crontab", ["-l"], { encoding: "utf8" });
   } catch {
-    existing = "";
+    return "";
   }
+}
+
+function installCrontabLine(id, line) {
   const marker = `# crondex:${id}`;
-  const kept = existing
+  const kept = readCrontab()
     .split("\n")
     .filter((l) => l.trim().length > 0 && !l.includes(marker));
   const updated = [...kept, line].join("\n") + "\n";
   execFileSync("crontab", ["-"], { input: updated });
 }
 
+function uninstall(id) {
+  const marker = `# crondex:${id}`;
+  const existing = readCrontab();
+  if (!existing.includes(marker)) {
+    console.error(`no installed crontab entry for "${id}" — run "crondex deploy --list-installed" to see what's there.`);
+    process.exit(1);
+  }
+  const kept = existing.split("\n").filter((l) => l.trim().length > 0 && !l.includes(marker));
+  execFileSync("crontab", ["-"], { input: kept.join("\n") + "\n" });
+  console.log(`removed "${id}" from your crontab.`);
+}
+
+function listInstalled() {
+  const managed = readCrontab()
+    .split("\n")
+    .filter((l) => l.includes("# crondex:"));
+  if (hasFlag("json")) {
+    return printJson(
+      managed.map((l) => ({ id: l.match(/# crondex:(\S+)/)?.[1], line: l }))
+    );
+  }
+  if (!managed.length) {
+    console.log("no crondex-managed crontab entries installed.");
+    return;
+  }
+  for (const l of managed) console.log(l);
+}
+
+function update(path) {
+  if (!existsSync(path)) {
+    console.error(`${path} does not exist.`);
+    process.exit(1);
+  }
+  const localRaw = readFileSync(path, "utf8");
+  let localDoc;
+  try {
+    localDoc = yaml.load(localRaw);
+  } catch (e) {
+    console.error(`${path} isn't valid YAML: ${e.message}`);
+    process.exit(1);
+  }
+  if (!localDoc?.id) {
+    console.error(`${path} has no "id" field — can't match it to a catalog job.`);
+    process.exit(1);
+  }
+  const meta = findJob(localDoc.id);
+  const latestRaw = readFileSync(join(ROOT, meta.path), "utf8");
+  if (latestRaw === localRaw) {
+    console.log(`${path} is already up to date with "${localDoc.id}".`);
+    return;
+  }
+  writeFileSync(path, latestRaw);
+  console.log(`updated ${path} to the latest "${localDoc.id}" from the catalog.`);
+}
+
 function deploy(id) {
+  if (id === undefined && hasFlag("list-installed")) return listInstalled();
   const meta = findJob(id);
   const doc = yaml.load(readFileSync(join(ROOT, meta.path), "utf8"));
   doc.path = meta.path;
@@ -248,8 +332,34 @@ function deploy(id) {
     mkdirSync(dirname(dest), { recursive: true });
     writeFileSync(dest, workflow);
     console.log(`wrote ${dest}`);
+  } else if (target === "systemd") {
+    const { service, timer } = buildSystemdUnits(doc, mode === "prompt" ? prompt : command, mode === "prompt");
+    const destDir = flag("dest") ?? "./systemd";
+    const serviceDest = join(destDir, `${id}.service`);
+    const timerDest = join(destDir, `${id}.timer`);
+    if (existsSync(serviceDest) || existsSync(timerDest)) {
+      console.error(`${serviceDest} or ${timerDest} already exists — refusing to overwrite. Pass --dest to choose another directory.`);
+      process.exit(1);
+    }
+    mkdirSync(destDir, { recursive: true });
+    writeFileSync(serviceDest, service);
+    writeFileSync(timerDest, timer);
+    console.log(`wrote ${serviceDest} and ${timerDest} — enable with:\n  systemctl --user enable --now ${id}.timer`);
+  } else if (target === "docker") {
+    const { dockerfile, crontab } = buildDockerArtifacts(doc, mode === "prompt" ? prompt : command, mode === "prompt");
+    const destDir = flag("dest") ?? join("./docker", id);
+    const dockerfileDest = join(destDir, "Dockerfile");
+    const crontabDest = join(destDir, "crontab");
+    if (existsSync(dockerfileDest) || existsSync(crontabDest)) {
+      console.error(`${dockerfileDest} or ${crontabDest} already exists — refusing to overwrite. Pass --dest to choose another directory.`);
+      process.exit(1);
+    }
+    mkdirSync(destDir, { recursive: true });
+    writeFileSync(dockerfileDest, dockerfile);
+    writeFileSync(crontabDest, crontab);
+    console.log(`wrote ${dockerfileDest} and ${crontabDest} — build with:\n  docker build -t ${id} ${destDir}`);
   } else {
-    console.error(`unknown --target "${target}" — use "crontab" or "github-actions".`);
+    console.error(`unknown --target "${target}" — use "crontab", "github-actions", "systemd", or "docker".`);
     process.exit(1);
   }
 }
@@ -301,11 +411,25 @@ switch (cmd) {
     recommend(args[0]);
     break;
   case "deploy":
+    if (!args[0] && !hasFlag("list-installed")) {
+      console.error("usage: crondex deploy <id> [--target crontab|github-actions|systemd|docker] [--mode script|prompt] [--var name=value ...] [--dest <path>] [--install]\n   or: crondex deploy --list-installed [--json]");
+      process.exit(1);
+    }
+    deploy(hasFlag("list-installed") ? undefined : args[0]);
+    break;
+  case "uninstall":
+    if (!args[0]) {
+      console.error("usage: crondex uninstall <id>");
+      process.exit(1);
+    }
+    uninstall(args[0]);
+    break;
+  case "update":
     if (!args[0]) {
-      console.error("usage: crondex deploy <id> [--target crontab|github-actions] [--mode script|prompt] [--var name=value ...] [--dest <path>] [--install]");
+      console.error("usage: crondex update <path>");
       process.exit(1);
     }
-    deploy(args[0]);
+    update(args[0]);
     break;
   default:
     printHelp();

package/lib/deploy.js

@@ -43,6 +43,89 @@ export function buildCrontabLine(job, resolvedText, isPrompt) {
   return `${job.schedule} ${body} # crondex:${job.id}`;
 }
 
+const DOW = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+
+// Numeric cron fields (minute/hour/day-of-month/month) map onto systemd calendar
+// syntax almost unchanged — the one gotcha is `*/n`, which systemd requires written
+// as `0/n` (a bare `*` can't carry a step). Comma lists and `a-b` ranges pass through.
+function translateNumericField(field) {
+  return field.replace(/^\*\/(\d+)$/, "0/$1");
+}
+
+// Cron's day-of-week field is numeric (0-6 or 7, both Sun); systemd wants weekday
+// names. Only handles the shapes crondex jobs actually use (digit, list, a-b range) —
+// not the rarer `a-b/n` step-in-range cron syntax.
+function translateWeekdayField(field) {
+  if (field === "*") return null;
+  return field
+    .split(",")
+    .map((part) => {
+      const range = part.match(/^(\d)-(\d)$/);
+      if (range) return `${DOW[Number(range[1]) % 7]}-${DOW[Number(range[2]) % 7]}`;
+      return DOW[Number(part) % 7];
+    })
+    .join(",");
+}
+
+// Converts a standard 5-field cron schedule into a systemd OnCalendar= expression.
+export function cronToSystemdCalendar(schedule) {
+  const [minute, hour, dom, month, dow] = schedule.trim().split(/\s+/);
+  const weekday = translateWeekdayField(dow);
+  const date = `*-${translateNumericField(month)}-${translateNumericField(dom)}`;
+  const time = `${translateNumericField(hour)}:${translateNumericField(minute)}:00`;
+  return weekday ? `${weekday} ${date} ${time}` : `${date} ${time}`;
+}
+
+// Builds a systemd service+timer unit pair for the job. Prompt-mode jobs still defer
+// to CRONDEX_AGENT_CLI (see buildCrontabLine) — systemd services run with a minimal
+// environment, so the unit points at EnvironmentFile as the place to set it.
+export function buildSystemdUnits(job, resolvedText, isPrompt) {
+  const flat = resolvedText.trim().replace(/\s*\n\s*/g, " ");
+  const escaped = escapeSingleQuotes(flat);
+  const body = isPrompt
+    ? `\${CRONDEX_AGENT_CLI:?set CRONDEX_AGENT_CLI to your agent CLI invocation, e.g. "claude -p"} '${escaped}'`
+    : `bash -lc '${escaped}'`;
+  const service = `[Unit]
+Description=${job.name} (crondex:${job.id})
+
+[Service]
+Type=oneshot
+${isPrompt ? "# prompt-mode job — set CRONDEX_AGENT_CLI, e.g. via EnvironmentFile=/etc/crondex/${job.id}.env\n" : ""}ExecStart=/bin/bash -c '${body.replace(/'/g, `'"'"'`)}'
+`;
+  const timer = `[Unit]
+Description=${job.name} timer (crondex:${job.id})
+
+[Timer]
+OnCalendar=${cronToSystemdCalendar(job.schedule)}
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+`;
+  return { service, timer };
+}
+
+// Builds a Dockerfile + /etc/cron.d entry that runs the job on its own schedule
+// inside a container — for teams that want the job shipped as an image rather than
+// installed on a host crontab or run via CI.
+export function buildDockerArtifacts(job, resolvedText, isPrompt) {
+  const flat = resolvedText.trim().replace(/\s*\n\s*/g, " ");
+  const escaped = escapeSingleQuotes(flat);
+  const body = isPrompt
+    ? `\${CRONDEX_AGENT_CLI:?set CRONDEX_AGENT_CLI to your agent CLI invocation, e.g. "claude -p"} '${escaped}'`
+    : `bash -lc '${escaped}'`;
+  const crontab = `${job.schedule} root ${body} # crondex:${job.id}\n`;
+  const dockerfile = `# Generated by \`crondex deploy ${job.id} --target docker\` from ${job.path}.
+FROM debian:bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends cron bash ca-certificates \\
+    && rm -rf /var/lib/apt/lists/*
+COPY crontab /etc/cron.d/crondex-job
+RUN chmod 0644 /etc/cron.d/crondex-job && crontab /etc/cron.d/crondex-job && touch /var/log/cron.log
+${isPrompt ? "# NOTE: prompt-mode job — pass CRONDEX_AGENT_CLI via `docker run -e` so cron's environment has it.\n" : ""}CMD ["sh", "-c", "cron && tail -f /var/log/cron.log"]
+`;
+  return { dockerfile, crontab };
+}
+
 // Builds a ready-to-commit GitHub Actions workflow file for the job. GitHub Actions
 // schedules always run in UTC regardless of the `cron:` string's intent, so a
 // non-UTC job gets a visible warning comment rather than silently firing at the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wonsukchoi/crondex",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "A public directory of pre-made, agent-editable cron jobs.",
   "type": "module",
   "license": "MIT",
@@ -26,6 +26,7 @@
     "lib",
     "jobs",
     "schema",
+    "templates",
     "catalog.json"
   ],
   "engines": {

package/templates/job.template.yaml

@@ -0,0 +1,49 @@
+# Copy this file to jobs/<category>/<id>.yaml and fill it in.
+# Full field spec: ../schema/job.schema.json
+# Delete any comment lines before submitting.
+
+id: your-job-id                 # slug, matches filename without extension: ^[a-z0-9]+(-[a-z0-9]+)*$
+version: 1                       # bump when prompt/command behavior changes; not for wording-only edits
+name: Human-Readable Job Name
+description: >
+  Plain language, no jargon: what this does in one sentence, then
+  "Use this if you ..." in a second sentence. Write for someone who's
+  never seen a cron expression, not for another agent.
+category: devops                # or productivity, or a new folder name
+tags: [tag-one, tag-two]
+schedule: "0 9 * * *"            # standard 5-field cron
+timezone: "UTC"                  # IANA tz, e.g. America/Los_Angeles
+
+# runner: pick one
+#   shell        — command only, zero tokens, deterministic. Use when the
+#                  check/action is fully scriptable and needs no judgment.
+#   agent-prompt — prompt only, costs tokens. Use when the job needs
+#                  synthesis, prioritization, drafting, or varies too much
+#                  by connector/provider for a generic script.
+#   hybrid       — both. Use when a raw-data script exists but an LLM pass
+#                  adds real value (interpretation, narrative, judgment).
+#                  Hybrid REQUIRES script_note explaining the tradeoff.
+runner: shell
+
+command: >
+  echo "replace with your shell command; supports {{variable}} placeholders"
+
+# prompt: |
+#   Only for runner: agent-prompt or hybrid.
+#   Task text handed to an LLM agent each run. Supports {{variable}}
+#   placeholders resolved from `variables` below.
+
+# script_note: >
+#   Only for runner: hybrid. One or two sentences: what `command` gives you
+#   for free vs. what only `prompt` adds (e.g. "no narrative synthesis").
+
+variables:
+  example_var:
+    default: "some-default"
+    description: What this variable controls.
+
+compatible_agents: [claude, codex, hermes, openclaw, generic]
+
+notes: >
+  Optional: caveats, prerequisites (e.g. requires `gh` CLI), safety notes
+  (e.g. destructive, draft-only, read-only).