@wonsukchoi/crondex 0.16.0 → 0.18.0

package/README.md

@@ -30,13 +30,18 @@ npx @wonsukchoi/crondex deploy ssl-cert-expiry-check --var host=example.com
 
 - `recommend "<what you want>"` — find the closest matching job (zero
   tokens, no network call, so an agent can check before writing one from
-  scratch)
+  scratch). Matching handles plurals, a small catalog-grounded synonym set
+  (e.g. "notify"/"warn"/"remind" all match jobs tagged `reminder`), and
+  falls back to fuzzy (edit-distance) matching on typos when nothing
+  matches exactly.
 - `list [--category x] [--tag y]` / `categories` — browse everything
 - `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
+- `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
@@ -170,7 +175,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

@@ -18,6 +18,7 @@ import {
   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"));
@@ -70,7 +71,7 @@ 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 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]
@@ -85,6 +86,7 @@ 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
@@ -120,7 +122,8 @@ deploy --list-installed shows every crondex-managed line in your crontab
 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.
 `);
 }
 
@@ -297,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.`);
 }

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/lib/recommend.js

@@ -16,13 +16,81 @@ export function stem(word) {
   return word;
 }
 
+// Groups of interchangeable words, grounded in the catalog's actual vocabulary (its
+// most common tags/description verbs) rather than a generic thesaurus — this closes
+// the gap where a query uses a reasonable synonym the job authors didn't happen to
+// write (e.g. "notify" vs. a job tagged "reminder"). Every word in a group maps to
+// the group's first entry, applied on both the query and the job's own fields so
+// either side using a different synonym still lines up.
+const SYNONYM_GROUPS = [
+  ["alert", "warn", "notify", "notification", "remind", "reminder"],
+  ["check", "monitor", "watch", "scan", "inspect", "verify"],
+  ["audit", "review", "compliance"],
+  ["expire", "expiry", "expiration"],
+  ["backup", "snapshot"],
+  ["cost", "spend", "spending", "budget", "expense", "billing"],
+  ["fail", "failure", "error", "crash", "outage"],
+  ["delete", "remove", "cleanup", "purge", "clear"],
+  ["update", "upgrade", "refresh", "sync"],
+  ["duplicate", "dedupe", "dup"],
+  ["deadline", "due"],
+  ["schedule", "scheduling", "calendar", "planning"],
+  ["drift", "diff", "change", "changed"],
+  ["renew", "renewal"],
+  ["followup", "follow-up"],
+  ["invoice", "billing", "payment"],
+  ["stale", "outdated", "old"],
+];
+
+const SYNONYM_MAP = new Map();
+for (const group of SYNONYM_GROUPS) {
+  for (const word of group) SYNONYM_MAP.set(word, group[0]);
+}
+
+export function canonicalize(word) {
+  return SYNONYM_MAP.get(word) ?? word;
+}
+
 export function tokenize(text) {
   return text
     .toLowerCase()
     .replace(/[^a-z0-9\s-]/g, " ")
     .split(/[\s-]+/)
     .filter((w) => w.length > 1 && !STOPWORDS.has(w))
-    .map(stem);
+    .map(stem)
+    .map(canonicalize);
+}
+
+// Bounded edit distance — used only as a fallback when no exact token match exists,
+// to catch typos/near-misses (e.g. "expiery" vs "expiry") without embeddings or a
+// spellcheck dependency. Short-circuits past `max` so it stays cheap across a whole
+// catalog scan.
+export function editDistance(a, b, max = 2) {
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  const prev = new Array(b.length + 1);
+  const curr = new Array(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    let rowMin = curr[0];
+    for (let j = 1; j <= b.length; j++) {
+      curr[j] = a[i - 1] === b[j - 1] ? prev[j - 1] : 1 + Math.min(prev[j - 1], prev[j], curr[j - 1]);
+      rowMin = Math.min(rowMin, curr[j]);
+    }
+    if (rowMin > max) return max + 1;
+    for (let j = 0; j <= b.length; j++) prev[j] = curr[j];
+  }
+  return prev[b.length];
+}
+
+// A query token counts as a fuzzy hit against a field token if they're a short edit
+// distance apart — only tried once no exact match exists (see scoreJob), and only for
+// words long enough that a 1-2 character slip is plausibly a typo rather than a
+// genuinely different short word ("ssl" vs "sql" would otherwise false-positive).
+function isFuzzyMatch(queryToken, fieldToken) {
+  if (queryToken.length < 5 || fieldToken.length < 5) return false;
+  const maxDistance = queryToken.length >= 8 ? 2 : 1;
+  return editDistance(queryToken, fieldToken, maxDistance) <= maxDistance;
 }
 
 // id and name are near-duplicates of each other (id is just the slugified
@@ -33,7 +101,7 @@ export const RECOMMEND_WEIGHTS = { tags: 4, title: 3, category: 2, description:
 
 export function scoreJob(queryTokens, job) {
   const fields = {
-    tags: job.tags.map((t) => stem(t.toLowerCase())),
+    tags: job.tags.map((t) => canonicalize(stem(t.toLowerCase()))),
     title: [...new Set([...tokenize(job.name), ...tokenize(job.id.replace(/-/g, " "))])],
     category: tokenize(job.category ?? ""),
     description: tokenize(job.description ?? ""),
@@ -45,6 +113,11 @@ export function scoreJob(queryTokens, job) {
       if (fields[field].includes(qt)) {
         score += weight;
         matched.add(qt);
+      } else if (fields[field].some((ft) => isFuzzyMatch(qt, ft))) {
+        // Fuzzy hits count for half weight (rounded up) — a real match still
+        // outranks a typo-distance one for the same field.
+        score += Math.ceil(weight / 2);
+        matched.add(qt);
       }
     }
   }

package/package.json

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