@wonsukchoi/crondex 0.14.0 → 0.16.0

package/README.md

@@ -35,14 +35,27 @@ 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|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`), 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, 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
 
 Add `--json` to `list`/`categories`/`show`/`recommend` for machine-readable
 output — useful when an agent is parsing the result programmatically
@@ -156,7 +169,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,18 @@ 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,
+  buildK8sCronJob,
+  buildEventBridgeCommand,
+  buildCloudSchedulerCommand,
+} from "../lib/deploy.js";
 
 const ROOT = new URL("..", import.meta.url).pathname;
 const CATALOG = JSON.parse(readFileSync(join(ROOT, "catalog.json"), "utf8"));
@@ -59,8 +70,12 @@ 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|k8s-cronjob|
+                                 eventbridge|cloud-scheduler] [--mode script|prompt]
                       [--var name=value ...] [--dest <path>] [--install]
+  crondex deploy --list-installed [--json]
+  crondex uninstall <id>
 
 Examples:
   crondex list --category devops
@@ -69,8 +84,16 @@ 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 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
 
 Add --json to list/categories/show/recommend for machine-readable output —
 useful when an agent is parsing crondex's output programmatically instead
@@ -79,9 +102,25 @@ 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>/); --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.
 `);
 }
 
@@ -194,22 +233,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 +345,48 @@ 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 === "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);
+    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", "docker", "k8s-cronjob", "eventbridge", or "cloud-scheduler".`);
     process.exit(1);
   }
 }
@@ -301,11 +438,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

@@ -30,17 +30,202 @@ 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"];
+
+// 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 body = buildShellBody(resolvedText, isPrompt);
+  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 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
+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 };
+}
+
+// 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wonsukchoi/crondex",
-  "version": "0.14.0",
+  "version": "0.16.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).