@wonsukchoi/crondex 0.13.0 → 0.15.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,22 @@ 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
+- `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
+- `deploy <id> [--target crontab|github-actions|systemd|docker] [--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
+  scheduled GitHub Actions workflow file, writes a systemd
+  `<id>.service` + `<id>.timer` pair, or writes a Dockerfile + `/etc/cron.d`
+  entry that runs the job on its own schedule in a container. `--var`
+  overrides a variable's default (repeatable). `hybrid` jobs deploy their
+  `command` by default; pass `--mode prompt` to deploy the `prompt` side
+  instead — for crontab/systemd/docker targets that means wiring in your
+  own agent CLI via a `CRONDEX_AGENT_CLI` env var, since crondex can't
+  guess its syntax.
+- `deploy --list-installed` — show every crondex-managed line in your
+  crontab (the ones left by `--install`)
+- `uninstall <id>` — remove one of those installed crontab entries
 
 Add `--json` to `list`/`categories`/`show`/`recommend` for machine-readable
 output — useful when an agent is parsing the result programmatically
@@ -91,13 +107,13 @@ tags, variables) use `crondex list`, `crondex recommend`, or browse
 `jobs/<category>/` directly.
 
 <!-- BEGIN JOB SUMMARY -->
-257 jobs across 44 categories:
+271 jobs across 44 categories:
 
 | category | jobs | description |
 |---|---|---|
 | `agriculture` | 5 | Farm operations — weather risk, irrigation, equipment, market prices. |
-| `automotive` | 3 | Repair shop workflow — repair orders, parts, loaners. |
-| `childcare` | 3 | Daycare compliance and ops — ratios, immunizations, tuition. |
+| `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. |
@@ -107,10 +123,10 @@ tags, variables) use `crondex list`, `crondex recommend`, or browse
 | `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` | 3 | Gym/studio ops — memberships, class utilization, equipment. |
+| `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` | 3 | Public-sector ops — records requests, permits, constituent casework. |
+| `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. |
@@ -131,14 +147,14 @@ tags, variables) use `crondex list`, `crondex recommend`, or browse
 | `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` | 3 | Store ops — till reconciliation, opening checklist, scheduling. |
+| `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` | 3 | Clinic ops for animals — vaccines, controlled substances, boarding. |
-| `warehousing` | 3 | Warehouse ops — dock scheduling, pick/pack errors, climate control. |
+| `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 +164,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 / update / deploy / uninstall
+├── 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,10 +1,20 @@
 #!/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,
+  buildSystemdUnits,
+  buildDockerArtifacts,
+} from "../lib/deploy.js";
 
 const ROOT = new URL("..", import.meta.url).pathname;
 const CATALOG = JSON.parse(readFileSync(join(ROOT, "catalog.json"), "utf8"));
@@ -21,6 +31,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));
 }
@@ -44,6 +67,11 @@ 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 deploy <id> [--target crontab|github-actions|systemd|docker] [--mode script|prompt]
+                      [--var name=value ...] [--dest <path>] [--install]
+  crondex deploy --list-installed [--json]
+  crondex uninstall <id>
 
 Examples:
   crondex list --category devops
@@ -52,10 +80,34 @@ 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 update ./cron/backup-reminder.yaml
+  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
+  crondex deploy repo-health-check --target docker --dest ./docker/repo-health-check
+  crondex deploy --list-installed
+  crondex uninstall ssl-cert-expiry-check
 
 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); --target systemd
+writes a <id>.service + <id>.timer pair (default ./systemd/); --target
+docker writes a Dockerfile + crontab pair that runs the job on its own
+schedule in a container (default ./docker/<id>/). --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.
+
+deploy --list-installed shows every crondex-managed line in your crontab
+(the ones with a "# crondex:<id>" marker, as left by --install). uninstall
+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.
 `);
 }
 
@@ -168,6 +220,150 @@ function init(id) {
   console.log(`wrote ${dest} — fill in the fields, then \`npm run validate\` (see CONTRIBUTING.md to submit it upstream).`);
 }
 
+function readCrontab() {
+  try {
+    return execFileSync("crontab", ["-l"], { encoding: "utf8" });
+  } catch {
+    return "";
+  }
+}
+
+function installCrontabLine(id, line) {
+  const marker = `# crondex:${id}`;
+  const kept = readCrontab()
+    .split("\n")
+    .filter((l) => l.trim().length > 0 && !l.includes(marker));
+  const updated = [...kept, line].join("\n") + "\n";
+  execFileSync("crontab", ["-"], { input: updated });
+}
+
+function uninstall(id) {
+  const marker = `# crondex:${id}`;
+  const existing = readCrontab();
+  if (!existing.includes(marker)) {
+    console.error(`no installed crontab entry for "${id}" — run "crondex deploy --list-installed" to see what's there.`);
+    process.exit(1);
+  }
+  const kept = existing.split("\n").filter((l) => l.trim().length > 0 && !l.includes(marker));
+  execFileSync("crontab", ["-"], { input: kept.join("\n") + "\n" });
+  console.log(`removed "${id}" from your crontab.`);
+}
+
+function listInstalled() {
+  const managed = readCrontab()
+    .split("\n")
+    .filter((l) => l.includes("# crondex:"));
+  if (hasFlag("json")) {
+    return printJson(
+      managed.map((l) => ({ id: l.match(/# crondex:(\S+)/)?.[1], line: l }))
+    );
+  }
+  if (!managed.length) {
+    console.log("no crondex-managed crontab entries installed.");
+    return;
+  }
+  for (const l of managed) console.log(l);
+}
+
+function update(path) {
+  if (!existsSync(path)) {
+    console.error(`${path} does not exist.`);
+    process.exit(1);
+  }
+  const localRaw = readFileSync(path, "utf8");
+  let localDoc;
+  try {
+    localDoc = yaml.load(localRaw);
+  } catch (e) {
+    console.error(`${path} isn't valid YAML: ${e.message}`);
+    process.exit(1);
+  }
+  if (!localDoc?.id) {
+    console.error(`${path} has no "id" field — can't match it to a catalog job.`);
+    process.exit(1);
+  }
+  const meta = findJob(localDoc.id);
+  const latestRaw = readFileSync(join(ROOT, meta.path), "utf8");
+  if (latestRaw === localRaw) {
+    console.log(`${path} is already up to date with "${localDoc.id}".`);
+    return;
+  }
+  writeFileSync(path, latestRaw);
+  console.log(`updated ${path} to the latest "${localDoc.id}" from the catalog.`);
+}
+
+function deploy(id) {
+  if (id === undefined && hasFlag("list-installed")) return listInstalled();
+  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 if (target === "systemd") {
+    const { service, timer } = buildSystemdUnits(doc, mode === "prompt" ? prompt : command, mode === "prompt");
+    const destDir = flag("dest") ?? "./systemd";
+    const serviceDest = join(destDir, `${id}.service`);
+    const timerDest = join(destDir, `${id}.timer`);
+    if (existsSync(serviceDest) || existsSync(timerDest)) {
+      console.error(`${serviceDest} or ${timerDest} already exists — refusing to overwrite. Pass --dest to choose another directory.`);
+      process.exit(1);
+    }
+    mkdirSync(destDir, { recursive: true });
+    writeFileSync(serviceDest, service);
+    writeFileSync(timerDest, timer);
+    console.log(`wrote ${serviceDest} and ${timerDest} — enable with:\n  systemctl --user enable --now ${id}.timer`);
+  } else if (target === "docker") {
+    const { dockerfile, crontab } = buildDockerArtifacts(doc, mode === "prompt" ? prompt : command, mode === "prompt");
+    const destDir = flag("dest") ?? join("./docker", id);
+    const dockerfileDest = join(destDir, "Dockerfile");
+    const crontabDest = join(destDir, "crontab");
+    if (existsSync(dockerfileDest) || existsSync(crontabDest)) {
+      console.error(`${dockerfileDest} or ${crontabDest} already exists — refusing to overwrite. Pass --dest to choose another directory.`);
+      process.exit(1);
+    }
+    mkdirSync(destDir, { recursive: true });
+    writeFileSync(dockerfileDest, dockerfile);
+    writeFileSync(crontabDest, crontab);
+    console.log(`wrote ${dockerfileDest} and ${crontabDest} — build with:\n  docker build -t ${id} ${destDir}`);
+  } else {
+    console.error(`unknown --target "${target}" — use "crontab", "github-actions", "systemd", or "docker".`);
+    process.exit(1);
+  }
+}
+
 function add(id) {
   const meta = findJob(id);
   const dest = flag("dest") ?? `./${id}.yaml`;
@@ -214,6 +410,27 @@ switch (cmd) {
     }
     recommend(args[0]);
     break;
+  case "deploy":
+    if (!args[0] && !hasFlag("list-installed")) {
+      console.error("usage: crondex deploy <id> [--target crontab|github-actions|systemd|docker] [--mode script|prompt] [--var name=value ...] [--dest <path>] [--install]\n   or: crondex deploy --list-installed [--json]");
+      process.exit(1);
+    }
+    deploy(hasFlag("list-installed") ? undefined : args[0]);
+    break;
+  case "uninstall":
+    if (!args[0]) {
+      console.error("usage: crondex uninstall <id>");
+      process.exit(1);
+    }
+    uninstall(args[0]);
+    break;
+  case "update":
+    if (!args[0]) {
+      console.error("usage: crondex update <path>");
+      process.exit(1);
+    }
+    update(args[0]);
+    break;
   default:
     printHelp();
 }