@wonsukchoi/crondex 0.12.0 → 0.14.0

package/README.md

@@ -25,7 +25,7 @@ access.
 ```bash
 npx @wonsukchoi/crondex recommend "warn me before my SSL cert expires"
 npx @wonsukchoi/crondex show ssl-cert-expiry-check
-npx @wonsukchoi/crondex add ssl-cert-expiry-check --dest ./cron/ssl-cert-expiry-check.yaml
+npx @wonsukchoi/crondex deploy ssl-cert-expiry-check --var host=example.com
 ```
 
 - `recommend "<what you want>"` — find the closest matching job (zero
@@ -35,6 +35,14 @@ npx @wonsukchoi/crondex add ssl-cert-expiry-check --dest ./cron/ssl-cert-expiry-
 - `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 ...]`
+  — 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.
 
 Add `--json` to `list`/`categories`/`show`/`recommend` for machine-readable
 output — useful when an agent is parsing the result programmatically
@@ -91,54 +99,54 @@ tags, variables) use `crondex list`, `crondex recommend`, or browse
 `jobs/<category>/` directly.
 
 <!-- BEGIN JOB SUMMARY -->
-257 jobs across 44 categories:
-
-| category | jobs |
-|---|---|
-| `agriculture` | 5 |
-| `automotive` | 3 |
-| `childcare` | 3 |
-| `construction` | 5 |
-| `content` | 13 |
-| `creator` | 5 |
-| `crypto` | 5 |
-| `devops` | 26 |
-| `ecommerce` | 5 |
-| `education` | 5 |
-| `events` | 5 |
-| `finance` | 10 |
-| `fitness` | 3 |
-| `fleet` | 5 |
-| `gaming` | 5 |
-| `government` | 3 |
-| `growth` | 5 |
-| `healthcare` | 5 |
-| `hiring` | 5 |
-| `home` | 5 |
-| `hospitality` | 5 |
-| `hr` | 5 |
-| `insurance` | 5 |
-| `inventory` | 5 |
-| `investing` | 5 |
-| `learning` | 5 |
-| `legal` | 5 |
-| `logistics` | 5 |
-| `manufacturing` | 5 |
-| `marketing` | 5 |
-| `nonprofit` | 5 |
-| `personal` | 9 |
-| `podcast` | 5 |
-| `productivity` | 9 |
-| `realestate` | 5 |
-| `restaurant` | 5 |
-| `retail` | 3 |
-| `sales` | 5 |
-| `security` | 14 |
-| `support` | 5 |
-| `team` | 5 |
-| `travel` | 5 |
-| `veterinary` | 3 |
-| `warehousing` | 3 |
+271 jobs across 44 categories:
+
+| category | jobs | description |
+|---|---|---|
+| `agriculture` | 5 | Farm operations — weather risk, irrigation, equipment, market prices. |
+| `automotive` | 5 | Repair shop workflow — repair orders, parts, loaners. |
+| `childcare` | 5 | Daycare compliance and ops — ratios, immunizations, tuition. |
+| `construction` | 5 | Job site compliance — permits, inspections, change orders, rentals. |
+| `content` | 13 | Site/content health — SEO, broken links, freshness, repurposing. |
+| `creator` | 5 | Influencer/creator ops — content calendar, cross-posting, sponsorships. |
+| `crypto` | 5 | Wallets, gas prices, DeFi risk, and token unlock schedules. |
+| `devops` | 26 | Infra health — backups, deploys, dependencies, monitoring. |
+| `ecommerce` | 5 | Storefront ops — carts, stock, returns, reviews. |
+| `education` | 5 | Classroom ops — grading, attendance, deadlines, permission slips. |
+| `events` | 5 | Event planning — budget, RSVPs, staffing, vendors, day-of check-in. |
+| `finance` | 10 | Personal/business finance — budgets, invoices, taxes, subscriptions. |
+| `fitness` | 5 | Gym/studio ops — memberships, class utilization, equipment. |
+| `fleet` | 5 | Vehicle fleet compliance — maintenance, registration, licenses, fuel. |
+| `gaming` | 5 | Streaming and community server ops — schedules, patches, tournaments. |
+| `government` | 5 | Public-sector ops — records requests, permits, constituent casework. |
+| `growth` | 5 | Lifecycle marketing — churn, trials, onboarding, reviews. |
+| `healthcare` | 5 | Clinic ops — appointments, recalls, licenses, lab results. |
+| `hiring` | 5 | Recruiting pipeline — candidates, offers, interviews, reqs. |
+| `home` | 5 | Household reminders — maintenance, warranties, plants, safety. |
+| `hospitality` | 5 | Hotel ops — guest reviews, inspections, maintenance requests. |
+| `hr` | 5 | People ops — payroll, onboarding, benefits, reviews, offboarding. |
+| `insurance` | 5 | Policy tracking — renewals, claims, coverage, certificates. |
+| `inventory` | 5 | Stock accuracy — counts, shrinkage, expiry, overstock. |
+| `investing` | 5 | Portfolio tracking — prices, dividends, rebalancing, taxes. |
+| `learning` | 5 | Personal learning — certs, courses, flashcards, reading. |
+| `legal` | 5 | Contracts and deadlines — NDAs, trademarks, court, compliance filings. |
+| `logistics` | 5 | Shipping ops — customs, freight, delays, fees. |
+| `manufacturing` | 5 | Production ops — downtime, defects, maintenance, suppliers, materials. |
+| `marketing` | 5 | Campaign ops — ad spend, SEO rank, deliverability, competitors. |
+| `nonprofit` | 5 | Fundraising ops — grants, donors, volunteers, board follow-ups. |
+| `personal` | 9 | Daily life reminders — bills, habits, meals, screen time. |
+| `podcast` | 5 | Show ops — publish cadence, guests, sponsors, ratings. |
+| `productivity` | 9 | Work habits — inbox, standups, focus, meetings, reports. |
+| `realestate` | 5 | Property management — leases, rent, vacancy, inspections, tax. |
+| `restaurant` | 5 | Kitchen/FOH ops — food cost, labor cost, waste, inspections. |
+| `retail` | 5 | Store ops — till reconciliation, opening checklist, scheduling. |
+| `sales` | 5 | Pipeline ops — leads, deals, quota, CRM sync. |
+| `security` | 14 | Security posture — keys, certs, access, scans, firewalls. |
+| `support` | 5 | Helpdesk ops — SLA, backlog, CSAT, agent workload. |
+| `team` | 5 | Team ops — 1:1s, on-call, PTO, anniversaries. |
+| `travel` | 5 | Trip logistics — flights, passports, visas, insurance, miles. |
+| `veterinary` | 5 | Clinic ops for animals — vaccines, controlled substances, boarding. |
+| `warehousing` | 5 | Warehouse ops — dock scheduling, pick/pack errors, climate control. |
 <!-- END JOB SUMMARY -->
 
 ---
@@ -148,12 +156,12 @@ 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
-├── lib/recommend.js       recommend's scoring logic (unit tested in test/)
+├── bin/crondex.js         CLI: list / categories / show / add / recommend / init / deploy
+├── 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
 ├── jobs/                  one YAML per job, grouped by category subdirectory
-└── scripts/               build-catalog.js, validate-jobs.js, lint-shell.js
+└── scripts/               build-catalog.js, validate-jobs.js, lint-shell.js, check-duplicates.js, smoke-test.js
 ```
 
 ---

package/bin/crondex.js

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
 // CLI over catalog.json — browse jobs, read one, or pull one into your project.
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+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";
 
 const ROOT = new URL("..", import.meta.url).pathname;
 const CATALOG = JSON.parse(readFileSync(join(ROOT, "catalog.json"), "utf8"));
@@ -20,6 +23,19 @@ function hasFlag(name) {
   return args.includes(`--${name}`);
 }
 
+// Collects every `--var name=value` occurrence (the flag can repeat).
+function varOverrides() {
+  const overrides = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== "--var") continue;
+    const pair = args[i + 1] ?? "";
+    const eq = pair.indexOf("=");
+    if (eq === -1) continue;
+    overrides[pair.slice(0, eq)] = pair.slice(eq + 1);
+  }
+  return overrides;
+}
+
 function printJson(value) {
   console.log(JSON.stringify(value, null, 2));
 }
@@ -43,6 +59,8 @@ 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]
+                      [--var name=value ...] [--dest <path>] [--install]
 
 Examples:
   crondex list --category devops
@@ -51,10 +69,19 @@ 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 deploy ssl-cert-expiry-check --var host=example.com --var port=443
+  crondex deploy repo-health-check --target github-actions
 
 Add --json to list/categories/show/recommend for machine-readable output —
 useful when an agent is parsing crondex's output programmatically instead
 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.
 `);
 }
 
@@ -134,11 +161,16 @@ function categories() {
   const counts = {};
   for (const j of CATALOG.jobs) counts[j.category] = (counts[j.category] ?? 0) + 1;
   const sorted = Object.entries(counts).sort(([a], [b]) => a.localeCompare(b));
-  if (hasFlag("json")) return printJson(sorted.map(([category, count]) => ({ category, count })));
+  if (hasFlag("json")) {
+    return printJson(
+      sorted.map(([category, count]) => ({ category, count, description: CATEGORY_DESCRIPTIONS[category] ?? "" }))
+    );
+  }
   console.log(catalogInfoLine());
   console.log();
   for (const [cat, n] of sorted) {
     console.log(`${cat}  (${n})`);
+    if (CATEGORY_DESCRIPTIONS[cat]) console.log(`  ${CATEGORY_DESCRIPTIONS[cat]}`);
   }
 }
 
@@ -162,6 +194,66 @@ 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 = "";
+  try {
+    existing = execFileSync("crontab", ["-l"], { encoding: "utf8" });
+  } catch {
+    existing = "";
+  }
+  const marker = `# crondex:${id}`;
+  const kept = existing
+    .split("\n")
+    .filter((l) => l.trim().length > 0 && !l.includes(marker));
+  const updated = [...kept, line].join("\n") + "\n";
+  execFileSync("crontab", ["-"], { input: updated });
+}
+
+function deploy(id) {
+  const meta = findJob(id);
+  const doc = yaml.load(readFileSync(join(ROOT, meta.path), "utf8"));
+  doc.path = meta.path;
+  const target = flag("target") ?? "crontab";
+  const mode = pickMode(doc, flag("mode"));
+
+  if (mode === "prompt" && !doc.prompt) {
+    console.error(`"${id}" has no prompt to deploy (runner: ${doc.runner}). Try without --mode prompt.`);
+    process.exit(1);
+  }
+  if (mode === "script" && !doc.command) {
+    console.error(`"${id}" has no command to deploy (runner: ${doc.runner}). Try --mode prompt.`);
+    process.exit(1);
+  }
+
+  const values = resolveVariables(doc, varOverrides());
+  const command = doc.command ? substitutePlaceholders(doc.command, values) : undefined;
+  const prompt = doc.prompt ? substitutePlaceholders(doc.prompt, values) : undefined;
+
+  if (target === "crontab") {
+    const line = buildCrontabLine(doc, mode === "prompt" ? prompt : command, mode === "prompt");
+    if (hasFlag("install")) {
+      installCrontabLine(id, line);
+      console.log(`installed into your crontab (replacing any previous "${id}" entry):`);
+      console.log(line);
+    } else {
+      console.log(line);
+    }
+  } else if (target === "github-actions") {
+    const workflow = buildGithubActionsWorkflow(doc, { command, prompt, mode });
+    const dest = flag("dest") ?? join(".github/workflows", `${id}.yml`);
+    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, workflow);
+    console.log(`wrote ${dest}`);
+  } else {
+    console.error(`unknown --target "${target}" — use "crontab" or "github-actions".`);
+    process.exit(1);
+  }
+}
+
 function add(id) {
   const meta = findJob(id);
   const dest = flag("dest") ?? `./${id}.yaml`;
@@ -208,6 +300,13 @@ switch (cmd) {
     }
     recommend(args[0]);
     break;
+  case "deploy":
+    if (!args[0]) {
+      console.error("usage: crondex deploy <id> [--target crontab|github-actions] [--mode script|prompt] [--var name=value ...] [--dest <path>] [--install]");
+      process.exit(1);
+    }
+    deploy(args[0]);
+    break;
   default:
     printHelp();
 }