@wonsukchoi/crondex 0.12.0 → 0.14.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/catalog-summary.js

@@ -0,0 +1,47 @@
+// Catalog-building logic behind scripts/build-catalog.js — pulled out so it's unit
+// testable directly (see test/catalog-summary.test.js).
+
+export const MODES_BY_RUNNER = {
+  "agent-prompt": ["agent-prompt"],
+  shell: ["script"],
+  hybrid: ["script", "agent-prompt"],
+};
+
+export function modesForRunner(runner) {
+  return MODES_BY_RUNNER[runner] ?? [];
+}
+
+export function countByCategory(jobs) {
+  const counts = new Map();
+  for (const j of jobs) counts.set(j.category, (counts.get(j.category) ?? 0) + 1);
+  return counts;
+}
+
+export function findMissingDescriptions(categories, categoryDescriptions) {
+  return categories.filter((c) => !categoryDescriptions[c]);
+}
+
+// Builds the markdown lines that go between the BEGIN/END JOB SUMMARY markers.
+export function buildSummaryLines(jobs, categoryDescriptions) {
+  const byCategory = countByCategory(jobs);
+  const categories = [...byCategory.keys()].sort();
+  return [
+    `${jobs.length} jobs across ${categories.length} categories:`,
+    "",
+    "| category | jobs | description |",
+    "|---|---|---|",
+    ...categories.map((c) => `| \`${c}\` | ${byCategory.get(c)} | ${categoryDescriptions[c] ?? ""} |`),
+  ];
+}
+
+const BEGIN = "<!-- BEGIN JOB SUMMARY -->";
+const END = "<!-- END JOB SUMMARY -->";
+
+// Splices summaryLines between the BEGIN/END markers in readmeText. Returns null if
+// the markers aren't found (caller decides how to warn/handle that).
+export function spliceReadmeSummary(readmeText, summaryLines) {
+  const start = readmeText.indexOf(BEGIN);
+  const end = readmeText.indexOf(END);
+  if (start === -1 || end === -1) return null;
+  return readmeText.slice(0, start + BEGIN.length) + "\n" + summaryLines.join("\n") + "\n" + readmeText.slice(end);
+}

package/lib/category-descriptions.js

@@ -0,0 +1,50 @@
+// One-line description per job category, for the README table and `crondex categories`.
+// Keep entries short — this is a browsing aid, not a spec. Add a new entry whenever a
+// job introduces a category that isn't listed here (a missing entry is a soft warning
+// from scripts/build-catalog.js, not a hard failure).
+export const CATEGORY_DESCRIPTIONS = {
+  agriculture: "Farm operations — weather risk, irrigation, equipment, market prices.",
+  automotive: "Repair shop workflow — repair orders, parts, loaners.",
+  childcare: "Daycare compliance and ops — ratios, immunizations, tuition.",
+  construction: "Job site compliance — permits, inspections, change orders, rentals.",
+  content: "Site/content health — SEO, broken links, freshness, repurposing.",
+  creator: "Influencer/creator ops — content calendar, cross-posting, sponsorships.",
+  crypto: "Wallets, gas prices, DeFi risk, and token unlock schedules.",
+  devops: "Infra health — backups, deploys, dependencies, monitoring.",
+  ecommerce: "Storefront ops — carts, stock, returns, reviews.",
+  education: "Classroom ops — grading, attendance, deadlines, permission slips.",
+  events: "Event planning — budget, RSVPs, staffing, vendors, day-of check-in.",
+  finance: "Personal/business finance — budgets, invoices, taxes, subscriptions.",
+  fitness: "Gym/studio ops — memberships, class utilization, equipment.",
+  fleet: "Vehicle fleet compliance — maintenance, registration, licenses, fuel.",
+  gaming: "Streaming and community server ops — schedules, patches, tournaments.",
+  government: "Public-sector ops — records requests, permits, constituent casework.",
+  growth: "Lifecycle marketing — churn, trials, onboarding, reviews.",
+  healthcare: "Clinic ops — appointments, recalls, licenses, lab results.",
+  hiring: "Recruiting pipeline — candidates, offers, interviews, reqs.",
+  home: "Household reminders — maintenance, warranties, plants, safety.",
+  hospitality: "Hotel ops — guest reviews, inspections, maintenance requests.",
+  hr: "People ops — payroll, onboarding, benefits, reviews, offboarding.",
+  insurance: "Policy tracking — renewals, claims, coverage, certificates.",
+  inventory: "Stock accuracy — counts, shrinkage, expiry, overstock.",
+  investing: "Portfolio tracking — prices, dividends, rebalancing, taxes.",
+  learning: "Personal learning — certs, courses, flashcards, reading.",
+  legal: "Contracts and deadlines — NDAs, trademarks, court, compliance filings.",
+  logistics: "Shipping ops — customs, freight, delays, fees.",
+  manufacturing: "Production ops — downtime, defects, maintenance, suppliers, materials.",
+  marketing: "Campaign ops — ad spend, SEO rank, deliverability, competitors.",
+  nonprofit: "Fundraising ops — grants, donors, volunteers, board follow-ups.",
+  personal: "Daily life reminders — bills, habits, meals, screen time.",
+  podcast: "Show ops — publish cadence, guests, sponsors, ratings.",
+  productivity: "Work habits — inbox, standups, focus, meetings, reports.",
+  realestate: "Property management — leases, rent, vacancy, inspections, tax.",
+  restaurant: "Kitchen/FOH ops — food cost, labor cost, waste, inspections.",
+  retail: "Store ops — till reconciliation, opening checklist, scheduling.",
+  sales: "Pipeline ops — leads, deals, quota, CRM sync.",
+  security: "Security posture — keys, certs, access, scans, firewalls.",
+  support: "Helpdesk ops — SLA, backlog, CSAT, agent workload.",
+  team: "Team ops — 1:1s, on-call, PTO, anniversaries.",
+  travel: "Trip logistics — flights, passports, visas, insurance, miles.",
+  veterinary: "Clinic ops for animals — vaccines, controlled substances, boarding.",
+  warehousing: "Warehouse ops — dock scheduling, pick/pack errors, climate control.",
+};

package/lib/deploy.js

@@ -0,0 +1,84 @@
+// 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}`;
+}
+
+// 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/duplicates.js

@@ -0,0 +1,29 @@
+// Near-duplicate detection logic behind scripts/check-duplicates.js — pulled out so
+// it's unit testable directly (see test/duplicates.test.js).
+
+export function jaccard(a, b) {
+  if (a.size === 0 && b.size === 0) return 0;
+  let intersection = 0;
+  for (const x of a) if (b.has(x)) intersection++;
+  const union = a.size + b.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+// jobs: array of { id, tags: Set<string>, description: Set<string>, ...rest }.
+// A pair is flagged only when BOTH tag and description overlap clear their
+// threshold — tag overlap alone false-positives on jobs that just share a couple
+// of generic tags, and description overlap alone false-positives on jobs
+// following the same wording template for genuinely different systems.
+export function findDuplicates(jobs, { tagThreshold = 0.6, descThreshold = 0.5 } = {}) {
+  const flagged = [];
+  for (let i = 0; i < jobs.length; i++) {
+    for (let j = i + 1; j < jobs.length; j++) {
+      const a = jobs[i];
+      const b = jobs[j];
+      const tagSim = jaccard(a.tags, b.tags);
+      const descSim = jaccard(a.description, b.description);
+      if (tagSim >= tagThreshold && descSim >= descThreshold) flagged.push({ a, b, tagSim, descSim });
+    }
+  }
+  return flagged.sort((x, y) => y.tagSim + y.descSim - (x.tagSim + x.descSim));
+}

package/lib/shellcheck-prep.js

@@ -0,0 +1,20 @@
+// Turns a crondex `command` field (with {{placeholder}} templating) into a script
+// shellcheck can actually parse — pulled out of scripts/lint-shell.js so the
+// substitution itself is unit testable (see test/shellcheck-prep.test.js).
+//
+// crondex substitutes {{placeholders}} as literal text before bash ever sees the
+// script, so each placeholder is stood in as a real (braced) bash variable — braced
+// so a literal suffix right after it (e.g. "{{days}}d") doesn't get glued into the
+// variable name — just to let shellcheck catch actual quoting/syntax bugs.
+const PLACEHOLDER_RE = /\{\{\s*(\w+)\s*\}\}/g;
+
+export function extractPlaceholders(command) {
+  return [...new Set([...command.matchAll(PLACEHOLDER_RE)].map((m) => m[1]))];
+}
+
+export function buildShellcheckScript(command) {
+  const placeholders = extractPlaceholders(command);
+  const header = placeholders.map((name) => `${name}="42"`).join("\n");
+  const body = command.replace(PLACEHOLDER_RE, "$${$1}");
+  return `#!/usr/bin/env bash\n${header}\n${body}`;
+}

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.12.0",
+  "version": "0.14.0",
   "description": "A public directory of pre-made, agent-editable cron jobs.",
   "type": "module",
   "license": "MIT",
@@ -36,6 +36,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": {