@wonsukchoi/crondex 0.15.0 → 0.17.0

package/README.md

@@ -35,19 +35,26 @@ 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
-- `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 ...]`
+- `update <path> [--dry-run]` — re-pull a job you already `add`ed/`init`ed
+  (matched by its `id` field) against the current catalog, print a diff of
+  what changed, and overwrite it in place. `--dry-run` shows the diff
+  without applying it.
+- `deploy <id> [--target crontab|github-actions|systemd|docker|k8s-cronjob|eventbridge|cloud-scheduler] [--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`), 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.
+  `<id>.service` + `<id>.timer` pair, writes a Dockerfile + `/etc/cron.d`
+  entry that runs the job on its own schedule in a container, or writes a
+  self-contained `batch/v1` CronJob manifest (`k8s-cronjob`). `eventbridge`
+  and `cloud-scheduler` print a ready `aws`/`gcloud` CLI command instead —
+  those services invoke a target (Lambda/ECS/HTTP endpoint) rather than
+  running a shell command directly, so the command leaves that target as a
+  TODO for you to wire up. `--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/k8s 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
@@ -165,7 +172,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 / update / deploy / uninstall
-├── lib/                   recommend, deploy, and catalog-building logic (unit tested in test/)
+├── lib/                   recommend, deploy, diff, 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
 ├── jobs/                  one YAML per job, grouped by category subdirectory

package/bin/crondex.js

@@ -14,7 +14,11 @@ import {
   buildGithubActionsWorkflow,
   buildSystemdUnits,
   buildDockerArtifacts,
+  buildK8sCronJob,
+  buildEventBridgeCommand,
+  buildCloudSchedulerCommand,
 } from "../lib/deploy.js";
+import { formatDiff } from "../lib/diff.js";
 
 const ROOT = new URL("..", import.meta.url).pathname;
 const CATALOG = JSON.parse(readFileSync(join(ROOT, "catalog.json"), "utf8"));
@@ -67,8 +71,9 @@ Usage:
   crondex add <id> [--dest <path>]
   crondex recommend "<what you want done>" [--limit <n>] [--json]
   crondex init <id> [--category <name>] [--dest <path>]
-  crondex update <path>
-  crondex deploy <id> [--target crontab|github-actions|systemd|docker] [--mode script|prompt]
+  crondex update <path> [--dry-run]
+  crondex deploy <id> [--target crontab|github-actions|systemd|docker|k8s-cronjob|
+                                 eventbridge|cloud-scheduler] [--mode script|prompt]
                       [--var name=value ...] [--dest <path>] [--install]
   crondex deploy --list-installed [--json]
   crondex uninstall <id>
@@ -81,10 +86,14 @@ Examples:
   crondex recommend "warn me before my SSL cert expires"
   crondex init ssl-cert-expiry-check --category security
   crondex update ./cron/backup-reminder.yaml
+  crondex update ./cron/backup-reminder.yaml --dry-run
   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 repo-health-check --target k8s-cronjob --dest ./k8s/repo-health-check.yaml
+  crondex deploy repo-health-check --target eventbridge
+  crondex deploy repo-health-check --target cloud-scheduler
   crondex deploy --list-installed
   crondex uninstall ssl-cert-expiry-check
 
@@ -98,16 +107,23 @@ crontab with --install; --target github-actions writes a scheduled
 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.
+schedule in a container (default ./docker/<id>/); --target k8s-cronjob
+writes a self-contained batch/v1 CronJob manifest (default
+./k8s/<id>.cronjob.yaml). --target eventbridge and --target
+cloud-scheduler print a ready aws/gcloud CLI command instead — those
+services invoke a target (Lambda/ECS/HTTP endpoint) rather than running a
+shell command directly, so the command leaves that target as a TODO for
+you to wire up. --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.
+against the current catalog, prints a diff of what changed, and overwrites
+the local file in place. Pass --dry-run to see the diff without applying it.
 `);
 }
 
@@ -284,10 +300,17 @@ function update(path) {
   }
   const meta = findJob(localDoc.id);
   const latestRaw = readFileSync(join(ROOT, meta.path), "utf8");
-  if (latestRaw === localRaw) {
+  const diff = formatDiff(localRaw, latestRaw);
+  if (!diff) {
     console.log(`${path} is already up to date with "${localDoc.id}".`);
     return;
   }
+  console.log(diff);
+  console.log();
+  if (hasFlag("dry-run")) {
+    console.log(`${path} differs from the catalog (shown above) — rerun without --dry-run to apply.`);
+    return;
+  }
   writeFileSync(path, latestRaw);
   console.log(`updated ${path} to the latest "${localDoc.id}" from the catalog.`);
 }
@@ -345,6 +368,20 @@ function deploy(id) {
     writeFileSync(serviceDest, service);
     writeFileSync(timerDest, timer);
     console.log(`wrote ${serviceDest} and ${timerDest} — enable with:\n  systemctl --user enable --now ${id}.timer`);
+  } else if (target === "k8s-cronjob") {
+    const manifest = buildK8sCronJob(doc, mode === "prompt" ? prompt : command, mode === "prompt");
+    const dest = flag("dest") ?? join("./k8s", `${id}.cronjob.yaml`);
+    if (existsSync(dest)) {
+      console.error(`${dest} already exists — refusing to overwrite. Pass --dest to choose another path.`);
+      process.exit(1);
+    }
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, manifest);
+    console.log(`wrote ${dest} — apply with:\n  kubectl apply -f ${dest}`);
+  } else if (target === "eventbridge") {
+    console.log(buildEventBridgeCommand(doc, mode === "prompt" ? prompt : command, mode === "prompt"));
+  } else if (target === "cloud-scheduler") {
+    console.log(buildCloudSchedulerCommand(doc, mode === "prompt" ? prompt : command, mode === "prompt"));
   } else if (target === "docker") {
     const { dockerfile, crontab } = buildDockerArtifacts(doc, mode === "prompt" ? prompt : command, mode === "prompt");
     const destDir = flag("dest") ?? join("./docker", id);
@@ -359,7 +396,7 @@ function deploy(id) {
     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", "github-actions", "systemd", or "docker".`);
+    console.error(`unknown --target "${target}" — use "crontab", "github-actions", "systemd", "docker", "k8s-cronjob", "eventbridge", or "cloud-scheduler".`);
     process.exit(1);
   }
 }

package/lib/deploy.js

@@ -30,17 +30,27 @@ function escapeSingleQuotes(text) {
   return text.replace(/'/g, `'"'"'`);
 }
 
-// Flattens a (possibly multi-line) resolved command/prompt into one crontab line.
-// isPrompt jobs can't assume any particular agent CLI syntax, so the line defers to
-// a CRONDEX_AGENT_CLI env var the user sets themselves (e.g. `export
-// CRONDEX_AGENT_CLI="claude -p"`) rather than guessing wrong.
-export function buildCrontabLine(job, resolvedText, isPrompt) {
-  const flat = resolvedText.trim().replace(/\s*\n\s*/g, " ");
-  const escaped = escapeSingleQuotes(flat);
-  const body = isPrompt
+// Collapses a (possibly multi-line) resolved command/prompt onto one line.
+function flattenScript(resolvedText) {
+  return resolvedText.trim().replace(/\s*\n\s*/g, " ");
+}
+
+// Builds a single-quoted shell invocation from a flattened script. isPrompt jobs can't
+// assume any particular agent CLI syntax, so the body defers to a CRONDEX_AGENT_CLI env
+// var the user sets themselves (e.g. `export CRONDEX_AGENT_CLI="claude -p"`) rather than
+// guessing wrong. Shared by every deploy target that embeds the job as a single-quoted
+// string inside a larger shell line (crontab, systemd, docker) — targets that build
+// their own command array (k8s) flatten/quote the script directly instead.
+function buildShellBody(resolvedText, isPrompt) {
+  const escaped = escapeSingleQuotes(flattenScript(resolvedText));
+  return isPrompt
     ? `\${CRONDEX_AGENT_CLI:?set CRONDEX_AGENT_CLI to your agent CLI invocation, e.g. "claude -p"} '${escaped}'`
     : `bash -lc '${escaped}'`;
-  return `${job.schedule} ${body} # crondex:${job.id}`;
+}
+
+// Flattens a (possibly multi-line) resolved command/prompt into one crontab line.
+export function buildCrontabLine(job, resolvedText, isPrompt) {
+  return `${job.schedule} ${buildShellBody(resolvedText, isPrompt)} # crondex:${job.id}`;
 }
 
 const DOW = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
@@ -80,11 +90,7 @@ export function cronToSystemdCalendar(schedule) {
 // 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 body = buildShellBody(resolvedText, isPrompt);
   const service = `[Unit]
 Description=${job.name} (crondex:${job.id})
 
@@ -109,11 +115,7 @@ WantedBy=timers.target
 // 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 body = buildShellBody(resolvedText, isPrompt);
   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
@@ -126,6 +128,106 @@ ${isPrompt ? "# NOTE: prompt-mode job — pass CRONDEX_AGENT_CLI via `docker run
   return { dockerfile, crontab };
 }
 
+// YAML double-quoted scalars only need backslash and the quote itself escaped —
+// used for embedding an arbitrary shell body inside a k8s manifest's command array.
+function yamlDoubleQuote(text) {
+  return `"${text.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+// Builds a self-contained batch/v1 CronJob manifest — the one target here that
+// actually runs the job (crontab/systemd/docker's sibling), rather than just
+// scheduling an invocation of something else the user still has to build (see
+// buildEventBridgeCommand/buildCloudSchedulerCommand below).
+export function buildK8sCronJob(job, resolvedText, isPrompt) {
+  const flat = flattenScript(resolvedText);
+  const shell = isPrompt ? "sh" : "bash";
+  const command = isPrompt
+    ? `\${CRONDEX_AGENT_CLI:?set CRONDEX_AGENT_CLI to your agent CLI invocation, e.g. "claude -p"} '${escapeSingleQuotes(flat)}'`
+    : flat;
+  return `# Generated by \`crondex deploy ${job.id} --target k8s-cronjob\` from ${job.path}.
+apiVersion: batch/v1
+kind: CronJob
+metadata:
+  name: ${job.id}
+  labels:
+    app.kubernetes.io/managed-by: crondex
+spec:
+  schedule: "${job.schedule}"
+  jobTemplate:
+    spec:
+      template:
+        spec:
+          restartPolicy: OnFailure
+          containers:
+            - name: ${job.id}
+              image: bash:5
+${isPrompt ? `              env:
+                - name: CRONDEX_AGENT_CLI
+                  value: "REPLACE_ME"  # e.g. "claude -p"
+` : ""}              command: ["${shell}", "-lc", ${yamlDoubleQuote(command)}]
+`;
+}
+
+const AWS_DOW = ["SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"];
+
+// AWS's cron() requires exactly one of day-of-month/day-of-week to be "?" — the other
+// carries the restriction. Cron's day-of-week is numeric (0-6 or 7, both Sun); AWS
+// wants day names. Minute/hour/month pass through unchanged except `*/n` -> `0/n`
+// (same systemd gotcha — a bare `*` can't carry a step).
+export function cronToAwsCron(schedule) {
+  const [minute, hour, dom, month, dow] = schedule.trim().split(/\s+/);
+  const min = translateNumericField(minute);
+  const hr = translateNumericField(hour);
+  const mon = translateNumericField(month);
+  if (dow === "*") {
+    return `cron(${min} ${hr} ${translateNumericField(dom)} ${mon} ? *)`;
+  }
+  const awsDow = dow
+    .split(",")
+    .map((part) => {
+      const range = part.match(/^(\d)-(\d)$/);
+      if (range) return `${AWS_DOW[Number(range[1]) % 7]}-${AWS_DOW[Number(range[2]) % 7]}`;
+      return AWS_DOW[Number(part) % 7];
+    })
+    .join(",");
+  return `cron(${min} ${hr} ? ${mon} ${awsDow} *)`;
+}
+
+// EventBridge Scheduler (unlike crontab/systemd/docker/k8s) can't run a shell command
+// directly — it invokes a target ARN (Lambda/ECS/Step Functions). So this only gets
+// the schedule right and leaves the target as a TODO, same spirit as the GitHub
+// Actions prompt-mode TODO: get the user unstuck, don't guess their infra for them.
+export function buildEventBridgeCommand(job, resolvedText, isPrompt) {
+  const body = buildShellBody(resolvedText, isPrompt);
+  return `# Generated by \`crondex deploy ${job.id} --target eventbridge\` from ${job.path}.
+# EventBridge Scheduler invokes a target (Lambda/ECS/Step Functions) — it can't run a
+# shell command directly. Point TODO_TARGET_ARN/TODO_ROLE_ARN at something that runs:
+#   ${body}
+aws scheduler create-schedule \\
+  --name "${job.id}" \\
+  --schedule-expression "${cronToAwsCron(job.schedule)}" \\
+  --flexible-time-window '{"Mode":"OFF"}' \\
+  --target '{"Arn":"TODO_TARGET_ARN","RoleArn":"TODO_ROLE_ARN"}'
+`;
+}
+
+// Cloud Scheduler accepts standard unix-cron directly (no conversion needed) but, like
+// EventBridge, invokes an HTTP/Pub/Sub/App Engine target rather than running a shell
+// command itself — --uri is left as a TODO for whatever endpoint actually runs it.
+export function buildCloudSchedulerCommand(job, resolvedText, isPrompt) {
+  const body = buildShellBody(resolvedText, isPrompt);
+  return `# Generated by \`crondex deploy ${job.id} --target cloud-scheduler\` from ${job.path}.
+# Cloud Scheduler invokes an HTTP endpoint (e.g. a Cloud Run job) — it can't run a
+# shell command directly. Point TODO_HTTPS_ENDPOINT at something that runs:
+#   ${body}
+gcloud scheduler jobs create http "${job.id}" \\
+  --schedule="${job.schedule}" \\
+  --uri="TODO_HTTPS_ENDPOINT" \\
+  --http-method=POST \\
+  --time-zone="${job.timezone ?? "UTC"}"
+`;
+}
+
 // 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/lib/diff.js

@@ -0,0 +1,66 @@
+// Dependency-free line diff — used by `crondex update` to show what actually changed
+// in a catalog job instead of just "it changed". Job files are small (tens of lines),
+// so a plain O(n*m) LCS table is plenty fast; no need for a real Myers-diff package.
+
+// Returns the line-by-line edit script as {type: "context"|"add"|"remove", line}.
+export function diffLines(oldText, newText) {
+  const a = oldText.split("\n");
+  const b = newText.split("\n");
+  const n = a.length;
+  const m = b.length;
+  const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+    }
+  }
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      ops.push({ type: "context", line: a[i] });
+      i++;
+      j++;
+    } else if (dp[i + 1][j] >= dp[i][j + 1]) {
+      ops.push({ type: "remove", line: a[i] });
+      i++;
+    } else {
+      ops.push({ type: "add", line: b[j] });
+      j++;
+    }
+  }
+  while (i < n) ops.push({ type: "remove", line: a[i++] });
+  while (j < m) ops.push({ type: "add", line: b[j++] });
+  return ops;
+}
+
+// Renders the edit script as a compact +/-/context diff, collapsing unchanged runs
+// longer than 2*context into a single "..." marker so a one-line change in a
+// 100-line job doesn't dump the whole file. Returns "" when the texts are identical.
+export function formatDiff(oldText, newText, { context = 2 } = {}) {
+  const ops = diffLines(oldText, newText);
+  const added = ops.filter((o) => o.type === "add").length;
+  const removed = ops.filter((o) => o.type === "remove").length;
+  if (!added && !removed) return "";
+
+  const keep = new Array(ops.length).fill(false);
+  ops.forEach((op, idx) => {
+    if (op.type === "context") return;
+    for (let k = Math.max(0, idx - context); k <= Math.min(ops.length - 1, idx + context); k++) keep[k] = true;
+  });
+
+  const lines = [`${added} added, ${removed} removed`];
+  let skipping = false;
+  ops.forEach((op, idx) => {
+    if (!keep[idx]) {
+      if (!skipping) lines.push("  ...");
+      skipping = true;
+      return;
+    }
+    skipping = false;
+    const prefix = op.type === "add" ? "+ " : op.type === "remove" ? "- " : "  ";
+    lines.push(prefix + op.line);
+  });
+  return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wonsukchoi/crondex",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "A public directory of pre-made, agent-editable cron jobs.",
   "type": "module",
   "license": "MIT",