@wonsukchoi/crondex 0.6.0 → 0.8.0

package/README.md

@@ -27,8 +27,16 @@ npx @wonsukchoi/crondex list                          # browse everything
 npx @wonsukchoi/crondex list --category devops        # filter by category or --tag
 npx @wonsukchoi/crondex show backup-reminder          # print one job's YAML
 npx @wonsukchoi/crondex add backup-reminder --dest ./cron/backup-reminder.yaml
+npx @wonsukchoi/crondex recommend "warn me before my SSL cert expires"
 ```
 
+`recommend` takes a free-text description of what you want and ranks the
+catalog against it (weighted keyword match over tags/name/id/category/
+description, zero tokens, no network call) — handy for an agent that just
+got asked "can you set up something for X" and needs to check whether a
+ready-made job already covers it before writing one from scratch. Add
+`--limit <n>` to control how many results come back (default 5).
+
 Or install once and drop the scope prefix on every call:
 
 ```bash
@@ -52,142 +60,58 @@ node bin/crondex.js list
 
 ```
 crondex/
-├── bin/crondex.js         CLI: list / show / add
+├── bin/crondex.js         CLI: list / show / add / recommend
 ├── catalog.json           generated index of every job — read this first
 ├── schema/job.schema.json spec every job file follows
-├── jobs/
-│   ├── devops/
-│   ├── productivity/
-│   ├── personal/
-│   ├── content/
-│   ├── finance/
-│   ├── security/
-│   ├── learning/
-│   ├── team/
-│   ├── home/
-│   ├── travel/
-│   └── growth/
+├── jobs/                  one YAML per job, grouped by category subdirectory
 └── scripts/
-    ├── build-catalog.js   regenerates catalog.json from jobs/**/*.yaml
+    ├── build-catalog.js   regenerates catalog.json + the summary below from jobs/**/*.yaml
     └── validate-jobs.js   validates every job against the schema
 ```
 
 ## Available jobs
 
-56 jobs across 11 categories. Full details (description, tags, variables)
-live in `catalog.json` and each job's YAML file — run `crondex list` or
-browse `jobs/<category>/` for the plain-language rundown of each.
-
-**devops**
-
-| id | schedule | modes |
-|---|---|---|
-| `dependency-audit` | `0 8 * * 1` | script + agent-prompt |
-| `log-cleanup` | `30 3 * * *` | script |
-| `repo-health-check` | `0 9 * * 1-5` | script + agent-prompt |
-| `backup-reminder` | `0 9 * * *` | script |
-| `ssl-cert-expiry-check` | `0 6 * * *` | script |
-| `uptime-ping-check` | `*/15 * * * *` | script |
-| `cost-alert` | `0 7 * * *` | script + agent-prompt |
-| `disk-space-check` | `0 */6 * * *` | script |
-| `docker-image-prune` | `0 4 * * *` | script |
-| `env-drift-check` | `0 8 * * *` | script |
-| `stale-dependency-pr-nudge` | `0 9 * * 1-5` | script |
-| `db-backup-verify` | `0 5 * * *` | script |
-| `license-compliance-check` | `0 8 * * 1` | script |
-| `orphaned-branch-cleanup` | `0 9 * * 1` | script |
-| `dns-record-check` | `0 */6 * * *` | script |
-| `queue-depth-check` | `*/10 * * * *` | script |
-| `api-rate-limit-check` | `*/15 * * * *` | script |
-
-**productivity**
-
-| id | schedule | modes |
-|---|---|---|
-| `daily-standup-summary` | `0 8 * * 1-5` | script + agent-prompt |
-| `inbox-triage` | `0 7,13 * * 1-5` | agent-prompt only |
-| `weekly-report` | `0 16 * * 5` | script + agent-prompt |
-| `focus-block-reminder` | `0 9,14 * * 1-5` | script |
-
-**personal**
-
-| id | schedule | modes |
-|---|---|---|
-| `bill-due-reminder` | `0 9 * * *` | script |
-| `habit-checkin` | `0 20 * * *` | script |
-| `meal-plan-reminder` | `0 9 * * 0` | script + agent-prompt |
-| `water-intake-reminder` | `0 9,12,15,18 * * *` | script |
-| `screen-time-check` | `0 20 * * *` | agent-prompt only |
-
-**content**
-
-| id | schedule | modes |
-|---|---|---|
-| `changelog-digest` | `0 10 * * 5` | script + agent-prompt |
-| `broken-link-check` | `0 7 * * 1` | script |
-| `social-mentions-watch` | `0 9 * * *` | agent-prompt only |
-| `seo-meta-check` | `0 7 * * 1` | script |
-| `rss-feed-validate` | `0 8 * * *` | script |
-| `robots-txt-check` | `0 8 * * *` | script |
-
-**finance**
-
-| id | schedule | modes |
-|---|---|---|
-| `subscription-audit` | `0 9 1 * *` | script |
-| `net-worth-snapshot` | `0 9 1 * *` | script |
-| `saas-seat-audit` | `0 9 1 * *` | script |
-| `invoice-overdue-check` | `0 9 * * *` | script |
-| `tax-deadline-reminder` | `0 9 * * *` | script |
-
-**security**
-
-| id | schedule | modes |
-|---|---|---|
-| `secrets-scan` | `0 3 * * *` | script |
-| `open-port-check` | `0 */4 * * *` | script |
-| `failed-login-watch` | `*/15 * * * *` | script |
-| `sudo-usage-audit` | `0 * * * *` | script |
-| `firewall-rule-diff` | `0 6 * * *` | script |
-| `certificate-transparency-watch` | `0 */12 * * *` | script |
-
-**learning**
-
-| id | schedule | modes |
-|---|---|---|
-| `daily-flashcard-review` | `0 8 * * *` | script |
-| `reading-list-nudge` | `0 9 * * 6` | script |
-| `course-progress-checkin` | `0 9 * * 1` | script |
-
-**team**
-
-| id | schedule | modes |
-|---|---|---|
-| `1on1-prep-reminder` | `0 9 * * 3` | script |
-| `pto-balance-check` | `0 9 1 * *` | script |
-
-**home**
-
-| id | schedule | modes |
-|---|---|---|
-| `hvac-filter-reminder` | `0 9 1 * *` | script |
-| `smoke-detector-battery-check` | `0 9 1 * *` | script |
-| `plant-watering-reminder` | `0 9 * * *` | script |
-
-**travel**
-
-| id | schedule | modes |
-|---|---|---|
-| `passport-expiry-check` | `0 9 1 * *` | script |
-| `visa-expiry-check` | `0 9 1 * *` | script |
-| `flight-checkin-reminder` | `0 * * * *` | script |
-
-**growth**
-
-| id | schedule | modes |
-|---|---|---|
-| `review-request-nudge` | `0 9 * * *` | script |
-| `cart-abandonment-followup` | `0 10 * * *` | script + agent-prompt |
+Full details (description, tags, variables) live in `catalog.json` and each
+job's YAML file — run `crondex list`, `crondex recommend "<what you want>"`,
+or browse `jobs/<category>/` for the plain-language rundown of each. The
+counts below are regenerated by `npm run build-catalog`, so they never drift
+from what's actually in `jobs/`.
+
+<!-- BEGIN JOB SUMMARY -->
+150 jobs across 29 categories:
+
+| category | jobs |
+|---|---|
+| `construction` | 3 |
+| `content` | 12 |
+| `creator` | 3 |
+| `devops` | 25 |
+| `education` | 3 |
+| `events` | 3 |
+| `finance` | 9 |
+| `fleet` | 3 |
+| `growth` | 4 |
+| `hiring` | 3 |
+| `home` | 5 |
+| `hospitality` | 3 |
+| `inventory` | 3 |
+| `investing` | 3 |
+| `learning` | 5 |
+| `legal` | 3 |
+| `logistics` | 3 |
+| `manufacturing` | 3 |
+| `marketing` | 3 |
+| `nonprofit` | 3 |
+| `personal` | 6 |
+| `podcast` | 3 |
+| `productivity` | 7 |
+| `realestate` | 3 |
+| `sales` | 3 |
+| `security` | 14 |
+| `support` | 3 |
+| `team` | 4 |
+| `travel` | 5 |
+<!-- END JOB SUMMARY -->
 
 ## How a job works
 

package/bin/crondex.js

@@ -30,14 +30,92 @@ Usage:
   crondex list [--category <name>] [--tag <name>]
   crondex show <id>
   crondex add <id> [--dest <path>]
+  crondex recommend "<what you want done>" [--limit <n>]
 
 Examples:
   crondex list --category devops
   crondex show dependency-audit
   crondex add backup-reminder --dest ./cron/backup-reminder.yaml
+  crondex recommend "warn me before my SSL cert expires"
 `);
 }
 
+const STOPWORDS = new Set([
+  "a", "an", "the", "to", "for", "of", "in", "on", "at", "by", "and", "or", "my", "me", "i",
+  "can", "you", "do", "does", "this", "that", "these", "those", "please", "want", "wants",
+  "wanted", "need", "needs", "help", "with", "is", "are", "be", "it", "so", "when", "should",
+  "could", "would", "how", "what", "which", "up", "down", "get", "make", "set", "just", "really",
+  "some", "something", "any", "want", "us", "our", "your", "yours", "if", "then", "than",
+]);
+
+function stem(word) {
+  if (word.length > 4 && word.endsWith("ies")) return word.slice(0, -3) + "y";
+  if (word.length > 4 && word.endsWith("es") && !word.endsWith("ses")) return word.slice(0, -2);
+  if (word.length > 3 && word.endsWith("s") && !word.endsWith("ss")) return word.slice(0, -1);
+  return word;
+}
+
+function tokenize(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, " ")
+    .split(/[\s-]+/)
+    .filter((w) => w.length > 1 && !STOPWORDS.has(w))
+    .map(stem);
+}
+
+// id and name are near-duplicates of each other (id is just the slugified
+// name), so they're merged into one "title" field — otherwise a match on a
+// shared word like "water" gets weighted 3+3 instead of 3, which can outrank
+// a more specific job that only matches once via tags.
+const RECOMMEND_WEIGHTS = { tags: 4, title: 3, category: 2, description: 1 };
+
+function scoreJob(queryTokens, job) {
+  const fields = {
+    tags: job.tags.map((t) => stem(t.toLowerCase())),
+    title: [...new Set([...tokenize(job.name), ...tokenize(job.id.replace(/-/g, " "))])],
+    category: tokenize(job.category ?? ""),
+    description: tokenize(job.description ?? ""),
+  };
+  let score = 0;
+  const matched = new Set();
+  for (const qt of queryTokens) {
+    for (const [field, weight] of Object.entries(RECOMMEND_WEIGHTS)) {
+      if (fields[field].includes(qt)) {
+        score += weight;
+        matched.add(qt);
+      }
+    }
+  }
+  return { score, matchedTerms: [...matched] };
+}
+
+function recommend(queryText) {
+  const limit = Number(flag("limit")) || 5;
+  const queryTokens = tokenize(queryText);
+  if (!queryTokens.length) {
+    console.log("query too vague to match on — describe what you want the job to check or remind you about.");
+    return;
+  }
+  const ranked = CATALOG.jobs
+    .map((job) => ({ job, ...scoreJob(queryTokens, job) }))
+    .filter((r) => r.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit);
+  if (!ranked.length) {
+    console.log(`no confident match for "${queryText}". Run "crondex list" to browse everything.`);
+    return;
+  }
+  console.log(`top match${ranked.length > 1 ? "es" : ""} for "${queryText}":`);
+  console.log();
+  for (const r of ranked) {
+    console.log(`${r.job.id}  [${r.job.category}]  score ${r.score}  (${r.job.modes.join(", ")})`);
+    console.log(`  ${r.job.description}`);
+    console.log(`  matched: ${r.matchedTerms.join(", ")}`);
+    console.log();
+  }
+}
+
 function catalogInfoLine() {
   const viaNpx = process.env.npm_command === "exec";
   const freshness = viaNpx
@@ -98,6 +176,13 @@ switch (cmd) {
     }
     add(args[0]);
     break;
+  case "recommend":
+    if (!args[0]) {
+      console.error('usage: crondex recommend "<what you want done>" [--limit <n>]');
+      process.exit(1);
+    }
+    recommend(args[0]);
+    break;
   default:
     printHelp();
 }