@wonsukchoi/crondex 0.13.0 → 0.15.0

package/jobs/fitness/trainer-session-package-expiry-check.yaml

@@ -0,0 +1,35 @@
+id: trainer-session-package-expiry-check
+version: 1
+name: Trainer Session Package Expiry Check
+description: >
+  Flags members with a paid personal-training session package that's
+  expiring soon with sessions still unused. Use this if a client has ever
+  paid for ten sessions, used three, and let the rest expire because
+  nobody nudged them to book before the window closed.
+category: fitness
+tags: [fitness, personal-training, sessions, expiry]
+schedule: "0 9 * * 1"
+timezone: "UTC"
+runner: shell
+command: >
+  awk -F',' -v days="{{warn_days_before}}" '
+    NR==1 {next}
+    $4 > 0 {
+      cmd = "date -d \"" $3 "\" +%s 2>/dev/null || date -j -f %Y-%m-%d \"" $3 "\" +%s 2>/dev/null";
+      cmd | getline expiry_epoch; close(cmd);
+      "date +%s" | getline now_epoch; close("date +%s");
+      diff_days = (expiry_epoch - now_epoch) / 86400;
+      if (diff_days <= days && diff_days >= 0) {
+        printf "EXPIRING: %s — %d session(s) left, expires %s (%d days)\n", $1, $4, $3, diff_days;
+      }
+    }
+  ' "{{packages_csv_path}}"
+variables:
+  packages_csv_path:
+    default: "./training-packages.csv"
+    description: "Path to a CSV with columns: member_name,package_size,expiry_date (YYYY-MM-DD),sessions_remaining."
+  warn_days_before:
+    default: 14
+    description: How many days before expiry to start warning, while there's still time to book remaining sessions.
+compatible_agents: [generic, claude, codex]
+notes: An expiring package with several sessions left is also a good moment to offer an extension or renewal, not just a "use it or lose it" notice.

package/jobs/government/budget-appropriation-deadline-check.yaml

@@ -0,0 +1,35 @@
+id: budget-appropriation-deadline-check
+version: 1
+name: Budget Appropriation Submission Deadline Check
+description: >
+  Warns you before an agency's budget appropriation submission is due.
+  Use this if a department has ever missed its window to request funding
+  for the next cycle because the internal deadline snuck up during budget
+  season chaos.
+category: government
+tags: [government, budget, appropriation, deadline]
+schedule: "0 8 * * *"
+timezone: "UTC"
+runner: shell
+command: >
+  awk -F',' -v days="{{warn_days_before}}" '
+    NR==1 {next}
+    {
+      cmd = "date -d \"" $2 "\" +%s 2>/dev/null || date -j -f %Y-%m-%d \"" $2 "\" +%s 2>/dev/null";
+      cmd | getline due_epoch; close(cmd);
+      "date +%s" | getline now_epoch; close("date +%s");
+      diff_days = (due_epoch - now_epoch) / 86400;
+      if (diff_days <= days && diff_days >= 0) {
+        printf "SUBMISSION DUE: %s — due %s (%d days)\n", $1, $2, diff_days;
+      }
+    }
+  ' "{{budget_deadlines_csv_path}}"
+variables:
+  budget_deadlines_csv_path:
+    default: "./budget-deadlines.csv"
+    description: "Path to a CSV with columns: department_name,submission_due_date (YYYY-MM-DD)."
+  warn_days_before:
+    default: 21
+    description: How many days before the submission deadline to start warning.
+compatible_agents: [generic, claude, codex]
+notes: Keep department names distinct if you're tracking multiple agencies' cycles in one CSV — otherwise run one instance of this job per department.

package/jobs/government/public-meeting-notice-compliance-check.yaml

@@ -0,0 +1,39 @@
+id: public-meeting-notice-compliance-check
+version: 1
+name: Public Meeting Notice Compliance Check
+description: >
+  Checks that an upcoming public meeting's notice was posted with enough
+  lead time to meet open-meetings law requirements. Use this if a meeting
+  has ever gotten challenged, or had to be redone, because notice went out
+  a day late.
+category: government
+tags: [government, open-meetings, notice, compliance]
+schedule: "0 8 * * *"
+timezone: "UTC"
+runner: shell
+command: >
+  meeting_epoch=$(date -d "{{meeting_date}}" +%s 2>/dev/null || date -jf "%Y-%m-%d" "{{meeting_date}}" +%s);
+  now_epoch=$(date +%s);
+  days_until=$(( (meeting_epoch - now_epoch) / 86400 ));
+  if [ ! -f "{{notice_posted_marker}}" ]; then
+    if [ "$days_until" -le "{{required_notice_days}}" ]; then
+      echo "COMPLIANCE RISK: meeting on {{meeting_date}} is in $days_until days with no notice-posted marker found (requires {{required_notice_days}} days notice)";
+      exit 1;
+    else
+      echo "OK: meeting is $days_until days out, still within the notice window";
+    fi
+  else
+    echo "OK: notice marker found for meeting on {{meeting_date}}";
+  fi
+variables:
+  meeting_date:
+    default: "YYYY-MM-DD"
+    description: Date of the upcoming public meeting.
+  required_notice_days:
+    default: 3
+    description: Minimum days of advance notice required by your jurisdiction's open-meetings law.
+  notice_posted_marker:
+    default: "./notice-posted.marker"
+    description: Path to a file you create once notice has actually been posted (physically and/or online) — its existence is the "done" signal.
+compatible_agents: [generic, claude, codex]
+notes: Required notice periods and posting locations vary significantly by state/locality — confirm your specific statute rather than relying on the example default.

package/jobs/retail/gift-card-liability-reconciliation-check.yaml

@@ -0,0 +1,36 @@
+id: gift-card-liability-reconciliation-check
+version: 1
+name: Gift Card Liability Reconciliation Check
+description: >
+  Compares your POS's outstanding gift card balance against your
+  accounting ledger and flags a mismatch. Use this if outstanding gift
+  card liability has ever drifted out of sync with your books for months
+  before anyone reconciled it at year-end and found a gap.
+category: retail
+tags: [retail, gift-cards, reconciliation, finance]
+schedule: "0 7 1 * *"
+timezone: "UTC"
+runner: shell
+command: >
+  pos="{{pos_outstanding_balance_usd}}";
+  ledger="{{ledger_outstanding_balance_usd}}";
+  tolerance="{{tolerance_usd}}";
+  diff=$(awk -v p="$pos" -v l="$ledger" 'BEGIN{d=p-l; if (d<0) d=-d; printf "%.2f", d}');
+  if awk -v d="$diff" -v t="$tolerance" 'BEGIN{exit !(d > t)}'; then
+    echo "MISMATCH: POS shows \$$pos outstanding, ledger shows \$$ledger (diff \$$diff)";
+    exit 1;
+  else
+    echo "OK: POS and ledger outstanding gift card balances match within tolerance";
+  fi
+variables:
+  pos_outstanding_balance_usd:
+    default: 0
+    description: Total outstanding gift card balance per your POS system's report.
+  ledger_outstanding_balance_usd:
+    default: 0
+    description: Total outstanding gift card liability per your accounting ledger.
+  tolerance_usd:
+    default: 25.00
+    description: Acceptable discrepancy in dollars before flagging.
+compatible_agents: [generic, claude, codex]
+notes: A growing gap over several months usually points at a systemic sync issue between POS and accounting, not a one-time error — worth escalating rather than just re-running this each month.

package/jobs/retail/return-fraud-pattern-check.yaml

@@ -0,0 +1,39 @@
+id: return-fraud-pattern-check
+version: 1
+name: Return Fraud Pattern Check
+description: >
+  Checks recent returns for patterns that look like abuse — the same
+  customer returning unusually often, or a spike in receiptless returns —
+  instead of treating every return as an isolated, no-questions-asked
+  event. Use this if return fraud has ever quietly eaten margin for
+  months because nobody was looking at returns in aggregate.
+category: retail
+tags: [retail, returns, fraud, loss-prevention]
+schedule: "0 7 * * 1"
+timezone: "UTC"
+runner: shell
+command: >
+  awk -F',' -v max_returns="{{max_returns_per_customer}}" '
+    NR==1 {next}
+    { count[$2]++; if ($3 == "no-receipt") noreceipt++; total++ }
+    END {
+      for (cust in count) {
+        if (count[cust] >= max_returns) {
+          printf "FREQUENT RETURNER: %s — %d returns in the period\n", cust, count[cust];
+        }
+      }
+      if (total > 0) {
+        pct = (noreceipt / total) * 100;
+        printf "no-receipt returns: %.0f%% of %d total\n", pct, total;
+      }
+    }
+  ' "{{returns_csv_path}}"
+variables:
+  returns_csv_path:
+    default: "./returns-log.csv"
+    description: "Path to a CSV with columns: return_id,customer_identifier,receipt_status (receipt/no-receipt) — one row per return in the period."
+  max_returns_per_customer:
+    default: 5
+    description: Number of returns from the same customer in the period that counts as worth a closer look.
+compatible_agents: [generic, claude, codex]
+notes: A flagged pattern is a prompt to look closer, not proof of fraud — plenty of frequent returners are just picky shoppers, not scammers.

package/jobs/veterinary/diagnostic-equipment-calibration-check.yaml

@@ -0,0 +1,35 @@
+id: diagnostic-equipment-calibration-check
+version: 1
+name: Diagnostic Equipment Calibration Check
+description: >
+  Tracks calibration due dates for in-house diagnostic equipment (x-ray,
+  in-house lab analyzers, ultrasound) and warns before any lapse. Use this
+  if a lab result has ever been called into question because equipment
+  calibration had quietly lapsed and nobody noticed until an audit.
+category: veterinary
+tags: [veterinary, equipment, calibration, compliance]
+schedule: "0 7 * * 1"
+timezone: "UTC"
+runner: shell
+command: >
+  awk -F',' -v days="{{warn_days_before}}" '
+    NR==1 {next}
+    {
+      cmd = "date -d \"" $2 "\" +%s 2>/dev/null || date -j -f %Y-%m-%d \"" $2 "\" +%s 2>/dev/null";
+      cmd | getline due_epoch; close(cmd);
+      "date +%s" | getline now_epoch; close("date +%s");
+      diff_days = (due_epoch - now_epoch) / 86400;
+      if (diff_days <= days) {
+        printf "CALIBRATION DUE: %s — due %s (%d days)\n", $1, $2, diff_days;
+      }
+    }
+  ' "{{equipment_csv_path}}"
+variables:
+  equipment_csv_path:
+    default: "./diagnostic-equipment-calibration.csv"
+    description: "Path to a CSV with columns: equipment_name,calibration_due_date (YYYY-MM-DD)."
+  warn_days_before:
+    default: 14
+    description: How many days before calibration is due to start warning.
+compatible_agents: [generic, claude, codex]
+notes: Take equipment out of clinical use once calibration lapses rather than continuing to trust its readings until the service tech arrives.

package/jobs/veterinary/surgery-prep-check.yaml

@@ -0,0 +1,30 @@
+id: surgery-prep-check
+version: 1
+name: Surgery Prep Check
+description: >
+  Checks tomorrow's scheduled surgeries for missing pre-op bloodwork or
+  signed consent forms. Use this if a surgery has ever had to be
+  rescheduled the morning of because consent wasn't signed or bloodwork
+  hadn't been run, and nobody checked the night before.
+category: veterinary
+tags: [veterinary, surgery, pre-op, consent]
+schedule: "0 17 * * *"
+timezone: "UTC"
+runner: shell
+command: >
+  tomorrow=$(date -d "+1 day" +%Y-%m-%d 2>/dev/null || date -v+1d +%Y-%m-%d);
+  awk -F',' -v tomorrow="$tomorrow" '
+    NR==1 {next}
+    $2 == tomorrow {
+      missing = "";
+      if ($3 != "done") missing = missing " bloodwork";
+      if ($4 != "signed") missing = missing " consent";
+      if (missing != "") printf "NOT READY: %s (%s) — missing:%s\n", $1, $5, missing;
+    }
+  ' "{{surgery_schedule_csv_path}}"
+variables:
+  surgery_schedule_csv_path:
+    default: "./surgery-schedule.csv"
+    description: "Path to a CSV with columns: pet_name,surgery_date (YYYY-MM-DD),bloodwork_status (done/pending),consent_status (signed/pending),owner_name."
+compatible_agents: [generic, claude, codex]
+notes: Run this the evening before so there's still time to call the owner and get bloodwork done or consent signed before the surgery slot.

package/jobs/warehousing/cycle-count-schedule-check.yaml

@@ -0,0 +1,35 @@
+id: cycle-count-schedule-check
+version: 1
+name: Cycle Count Schedule Adherence Check
+description: >
+  Checks whether scheduled cycle counts actually happened on time, zone by
+  zone. Use this if a cycle count program has ever quietly stopped
+  happening for a whole section of the warehouse because nobody was
+  tracking adherence to the schedule itself, only the count results.
+category: warehousing
+tags: [warehousing, cycle-count, schedule, inventory]
+schedule: "0 8 * * 1"
+timezone: "UTC"
+runner: shell
+command: >
+  today=$(date +%s);
+  awk -F',' -v days="{{overdue_after_days}}" -v today="$today" '
+    NR==1 {next}
+    {
+      cmd = "date -d \"" $2 "\" +%s 2>/dev/null || date -j -f %Y-%m-%d \"" $2 "\" +%s 2>/dev/null";
+      cmd | getline last_count_epoch; close(cmd);
+      age_days = (today - last_count_epoch) / 86400;
+      if (age_days >= days) {
+        printf "OVERDUE: zone %s — last counted %s (%d days ago)\n", $1, $2, age_days;
+      }
+    }
+  ' "{{cycle_count_log_csv_path}}"
+variables:
+  cycle_count_log_csv_path:
+    default: "./cycle-count-log.csv"
+    description: "Path to a CSV with columns: zone_name,last_count_date (YYYY-MM-DD)."
+  overdue_after_days:
+    default: 30
+    description: Days since the last cycle count before a zone counts as overdue for its next one.
+compatible_agents: [generic, claude, codex]
+notes: This checks schedule adherence only — pair with `inventory-count-discrepancy-check` for what the counts themselves turn up.

package/jobs/warehousing/forklift-inspection-check.yaml

@@ -0,0 +1,36 @@
+id: forklift-inspection-check
+version: 1
+name: Forklift Daily Safety Inspection Check
+description: >
+  Checks that each forklift's required daily pre-use inspection was
+  actually logged today. Use this if a forklift has ever been operated
+  on a shift with no inspection logged, which is exactly what an OSHA
+  audit will ask to see records of.
+category: warehousing
+tags: [warehousing, forklift, safety, compliance]
+schedule: "0 10 * * *"
+timezone: "UTC"
+runner: shell
+command: >
+  today=$(date +%Y-%m-%d);
+  missing=$(awk -F',' -v today="$today" -v fleet="{{forklift_ids}}" '
+    BEGIN { n = split(fleet, ids, ","); }
+    $2 == today { logged[$1] = 1 }
+    END {
+      for (i = 1; i <= n; i++) {
+        id = ids[i];
+        gsub(/^ +| +$/, "", id);
+        if (!(id in logged)) print "NOT INSPECTED TODAY: " id;
+      }
+    }
+  ' "{{inspection_log_csv_path}}");
+  if [ -n "$missing" ]; then echo "$missing"; exit 1; else echo "OK: all forklifts inspected today"; fi
+variables:
+  inspection_log_csv_path:
+    default: "./forklift-inspection-log.csv"
+    description: "Path to a CSV with columns: forklift_id,inspection_date (YYYY-MM-DD)."
+  forklift_ids:
+    default: "FL-1,FL-2"
+    description: Comma-separated list of forklift IDs that must each have a logged inspection today.
+compatible_agents: [generic, claude, codex]
+notes: A forklift with a failed inspection item should be pulled from service immediately — this job only checks that the inspection was logged, not what it found.

package/lib/deploy.js

@@ -0,0 +1,167 @@
+// Turns a resolved crondex job into a deployment artifact — pulled out of
+// bin/crondex.js's `deploy` command so it's unit testable (see test/deploy.test.js).
+
+const PLACEHOLDER_RE = /\{\{\s*(\w+)\s*\}\}/g;
+
+// Merges a job's `variables` defaults with any user-supplied overrides.
+export function resolveVariables(job, overrides = {}) {
+  const values = {};
+  for (const [name, spec] of Object.entries(job.variables ?? {})) {
+    values[name] = name in overrides ? overrides[name] : spec.default;
+  }
+  return values;
+}
+
+// crondex substitutes {{placeholders}} as literal text — this mirrors that exactly,
+// leaving a placeholder untouched if no value was resolved for it (rather than
+// silently dropping it, which would produce a broken script with no warning).
+export function substitutePlaceholders(text, values) {
+  return text.replace(PLACEHOLDER_RE, (match, name) => (name in values ? String(values[name]) : match));
+}
+
+// hybrid jobs support both — shell/agent-prompt jobs only support their one mode.
+export function pickMode(job, requestedMode) {
+  if (job.runner === "shell") return "script";
+  if (job.runner === "agent-prompt") return "prompt";
+  return requestedMode === "prompt" ? "prompt" : "script";
+}
+
+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
+    ? `\${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}`;
+}
+
+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
+// wrong hour.
+export function buildGithubActionsWorkflow(job, { command, prompt, mode }) {
+  const lines = [];
+  lines.push(`name: ${job.name}`);
+  lines.push(`# Generated by \`crondex deploy ${job.id} --target github-actions\` from ${job.path}.`);
+  if (job.timezone && job.timezone !== "UTC") {
+    lines.push(`# NOTE: this job's schedule ("${job.schedule}") is defined in ${job.timezone}, but GitHub`);
+    lines.push(`# Actions cron always runs in UTC — adjust the hour field(s) below if timing matters.`);
+  }
+  lines.push("");
+  lines.push("on:");
+  lines.push("  schedule:");
+  lines.push(`    - cron: "${job.schedule}"`);
+  lines.push("  workflow_dispatch: {}");
+  lines.push("");
+  lines.push("jobs:");
+  lines.push("  run:");
+  lines.push("    runs-on: ubuntu-latest");
+  lines.push("    steps:");
+  lines.push("      - uses: actions/checkout@v4");
+  if (mode === "script") {
+    lines.push("      - name: run job");
+    lines.push("        run: |");
+    for (const l of command.trimEnd().split("\n")) lines.push(`          ${l}`);
+  } else {
+    lines.push("      - name: run job (agent-prompt)");
+    lines.push(
+      "        # TODO: wire up your agent CLI/action here — this step only prints the resolved prompt."
+    );
+    lines.push("        run: |");
+    lines.push("          cat <<'CRONDEX_PROMPT'");
+    for (const l of prompt.trimEnd().split("\n")) lines.push(`          ${l}`);
+    lines.push("          CRONDEX_PROMPT");
+  }
+  return lines.join("\n") + "\n";
+}

package/lib/duplicates-allowlist.js

@@ -0,0 +1,18 @@
+// Job pairs that score above the near-duplicate thresholds but were reviewed and
+// confirmed genuinely distinct — recorded here so scripts/check-duplicates.js stops
+// re-flagging (and CI stops failing on) the same reviewed pair every run. Order of
+// ids within a pair doesn't matter.
+//
+// Add an entry only after actually comparing the two jobs — this is a record of a
+// human decision, not a way to silence the check.
+export const ALLOWED_DUPLICATE_PAIRS = [
+  [
+    "food-cost-percentage-watch",
+    "labor-cost-percentage-watch",
+    "Same benchmark-against-sales pattern, different cost categories (food vs. labor) — intentionally parallel jobs, not a copy-paste duplicate.",
+  ],
+];
+
+export function isAllowedPair(idA, idB) {
+  return ALLOWED_DUPLICATE_PAIRS.some(([x, y]) => (x === idA && y === idB) || (x === idB && y === idA));
+}

package/lib/smoke-test.js

@@ -0,0 +1,32 @@
+// Pure logic behind scripts/smoke-test.js: resolving a job's command with its real
+// default variable values, and wrapping it for sandboxed execution. Split out so the
+// resolution step is unit testable without actually spawning a shell.
+import { substitutePlaceholders } from "./deploy.js";
+
+// Unlike lint-shell.js (which stands placeholders in as bash variables to run
+// shellcheck's static analysis), this resolves them exactly like a real deployment
+// would — using each variable's actual `default` — so the smoke test exercises the
+// real behavior a user would get, not a synthetic stand-in.
+export function resolveJobCommand(job) {
+  const values = {};
+  for (const [name, spec] of Object.entries(job.variables ?? {})) values[name] = spec.default;
+  return substitutePlaceholders(job.command, values);
+}
+
+// Wraps a resolved command for sandboxed execution:
+//  - `set -u` so an unbound variable (a real bug) aborts instead of silently
+//    expanding to empty string.
+//  - HOME repointed into the sandbox dir, so a job whose default touches
+//    "$HOME/..." (e.g. downloads-folder-auto-organize) can't reach the real user's
+//    home directory.
+//  - a `command_not_found_handle` fallback so any external tool not installed on
+//    this machine (aws, gh, kubectl, redis-cli, ...) resolves to a harmless no-op
+//    instead of a hard "command not found" — this lets the job's own control flow
+//    run for real without requiring every possible external tool to be present.
+export function buildSandboxScript(resolvedCommand) {
+  return [
+    "set -u",
+    "command_not_found_handle() { return 0; }",
+    resolvedCommand,
+  ].join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wonsukchoi/crondex",
-  "version": "0.13.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": {
@@ -36,6 +37,7 @@
     "validate": "node scripts/validate-jobs.js",
     "lint-shell": "node scripts/lint-shell.js",
     "check-duplicates": "node scripts/check-duplicates.js",
+    "smoke-test": "node scripts/smoke-test.js",
     "test": "node --test"
   },
   "dependencies": {

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).