openings 0.1.59 → 0.1.61

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.59",
+  "version": "0.1.61",
   "description": "A free, candidate-safe job-search substrate for AI agents",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/abhay-avagama/hiring-agent.git" },

package/src/board-verification.ts

@@ -1,3 +1,4 @@
+import excludedData from "../data/excluded.json" with { type: "json" };
 import { atomicJson } from "./atomic-file.ts";
 import { readEnrichmentRegistry, mergeEnrichmentLeads, type EnrichmentLead, type LeadAttempt } from "./enrichment-registry.ts";
 import { withFileLock } from "./file-lock.ts";
@@ -7,6 +8,22 @@ import type { Ats, Company, SourceVerification } from "./types.ts";
 
 type Fetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
 
+/**
+ * Sources that must never be admitted, by provider and token.
+ *
+ * Deleting a row from the catalog does not hold: the lead stays in the registry and the next verification run
+ * puts it straight back, which is how two employers excluded on terms grounds could have quietly returned. The
+ * reason travels with the entry so a later reader does not have to guess why.
+ */
+const EXCLUDED: ReadonlySet<string> = new Set(
+  excludedData.entries.map((entry) => `${entry.ats}:${entry.token.toLowerCase()}`),
+);
+
+/** Why a given source is excluded, for reporting. */
+export function exclusionReason(ats: string, token: string): string | undefined {
+  return excludedData.entries.find((entry) => entry.ats === ats && entry.token.toLowerCase() === token.toLowerCase())?.reason;
+}
+
 /** Providers whose public board is accepted as identity on its own. Workday boards are identified by tenant; their crawls are heavier but they carry the large employers. */
 export const BOARD_TIER_PROVIDERS: ReadonlySet<Ats> = new Set(["greenhouse", "lever", "ashby", "recruitee", "smartrecruiters", "workable", "breezy", "workday", "freshteam", "keka", "zohorecruit"]);
 
@@ -24,7 +41,7 @@ export interface BoardVerificationReport {
   generatedAt: string;
   considered: number;
   selected: number;
-  skipped: { inCatalog: number; coolingDown: number; unsupported: number; deferred: number };
+  skipped: { inCatalog: number; coolingDown: number; unsupported: number; deferred: number; excluded: number };
   verified: number;
   added: string[];
   rejected: Array<{ sourceKey: string; reason: "unreachable" | "invalid_payload" | "empty_board" | "duplicate_slug"; detail: string }>;
@@ -50,10 +67,11 @@ export async function verifyBoards(registryPath: string, catalogPath: string, op
     const catalog = await readCatalog(catalogPath);
     const registry = await readEnrichmentRegistry(registryPath);
     const knownSources = new Set(Object.values(catalog).map((entry) => `${entry.ats}:${entry.token.toLowerCase()}`));
-    const skipped = { inCatalog: 0, coolingDown: 0, unsupported: 0, deferred: 0 };
+    const skipped = { inCatalog: 0, coolingDown: 0, unsupported: 0, deferred: 0, excluded: 0 };
     const eligible: EnrichmentLead[] = [];
     for (const lead of registry.leads) {
       if (!BOARD_TIER_PROVIDERS.has(lead.ats) || !resolveSource(lead.sourceUrl)) { skipped.unsupported += 1; continue; }
+      if (EXCLUDED.has(`${lead.ats}:${lead.token.toLowerCase()}`)) { skipped.excluded += 1; continue; }
       if (knownSources.has(`${lead.ats}:${lead.token.toLowerCase()}`)) { skipped.inCatalog += 1; continue; }
       // Keka tokens contain tenant/UUID; the provider-issued routing UUID is not a company name.
       const boardName = lead.ats === "keka" ? lead.token.split("/")[0]! : lead.token;

package/src/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { ALL_PROVIDERS, type Ats } from "./types.ts";
 import { readFile } from "node:fs/promises";
-import { relative, resolve } from "node:path";
+import { join, relative, resolve } from "node:path";
 import { createRuntime } from "./runtime.ts";
 import { atomicJson } from "./atomic-file.ts";
 import { verifyBoards } from "./board-verification.ts";
@@ -11,6 +11,9 @@ import { runSourceDiscovery, runYcSourceDiscovery } from "./source-discovery.ts"
 import { discoverAndPromote } from "./source-discovery-pipeline.ts";
 import { traceCareerSources } from "./career-tracing.ts";
 import { discoverCommonCrawlSources } from "./common-crawl-discovery.ts";
+import { createLocalWatches } from "./local-watches.ts";
+import { notifyDesktop } from "./desktop-notify.ts";
+import type { CandidateProfile } from "./candidate-profile.ts";
 import { discoverCatalog } from "./catalog-discovery.ts";
 import { parseArgs } from "node:util";
 import { generateYcCompanySeeds } from "./company-seeds.ts";
@@ -31,6 +34,9 @@ import { mergeAttemptedRoundLeads, prepareRecruiteeRoundArtifacts } from "./recr
 const HELP = `Openings — search public company job boards
 
 Usage:
+  openings watch add RESUME.txt [--label NAME] [--country IN,US]   watch for roles that fit, on this machine
+  openings watch list | check ID [--peek] | stop ID
+  openings watch run [--country IN,US] [--no-refresh]              what a scheduler calls: refresh, match, notify
   openings crawl [--workday-countries IN,US] [--country CODE | --companies FILE] [--concurrency N] [--source-cache-hours N] [--source-limit N] [--delay-ms N] [--workday-page-delay-ms N] [--timeout-ms N] [--data-dir PATH]
   openings snapshot export [--input FILE] [--output-dir PATH]
   openings coverage report --country CODE [--snapshot FILE] [--catalog FILE] [--candidates FILE] [--registry FILE] [--output FILE] [--as-of ISO]
@@ -110,6 +116,58 @@ export async function run(args: string[]): Promise<number> {
     return 0;
   }
 
+  if (command === "watch") {
+    const sub = rest[0];
+    /** The value after a flag, or undefined. Local to this command; the other commands parse their own. */
+    const argValue = (args: string[], flag: string) => {
+      const at = args.indexOf(flag);
+      return at >= 0 && args[at + 1] && !args[at + 1]!.startsWith("--") ? args[at + 1] : undefined;
+    };
+    const dataDir = argValue(rest, "--data-dir") ?? process.env.OPENINGS_DATA_DIR ?? join(process.cwd(), ".openings");
+    const runtime = createRuntime({ dataDir });
+    const watches = createLocalWatches({
+      dataDir,
+      // Whatever the local index already holds; a monitor never fetches on its own behalf.
+      jobs: async () => (await runtime.search({ maxAgeDays: 0, limit: 200_000 }, { offline: true, staleDays: 3650 })).jobs.map((job) => ({
+        id: job.id, title: job.title, company: job.company, location: job.location, remote: job.remote,
+        countries: job.eligibleCountries ?? [], skills: (job as { skills?: string }).skills ?? "",
+        ...(job.experience === undefined || job.experience === null ? {} : { experience: job.experience }),
+      })),
+      profileFromResume: async (input) => (await runtime.recommend({ ...(input as object), limit: 1 }) as { profile: CandidateProfile }).profile,
+      notify: async (title, body) => { await notifyDesktop(title, body); },
+    });
+    if (sub === "add") {
+      const file = rest[1];
+      if (!file || file.startsWith("--")) return fail("watch add needs a resume file: openings watch add RESUME.txt [--label NAME] [--country IN]");
+      const content = await Bun.file(file).text();
+      const countries = (argValue(rest, "--country") ?? "").split(",").map((c) => c.trim().toUpperCase()).filter(Boolean);
+      const result = await watches.create({ resume: { content, format: file.toLowerCase().endsWith(".md") ? "markdown" : "text" },
+        intent: countries.length ? { countries } : {}, label: argValue(rest, "--label") });
+      console.log(JSON.stringify(result, null, 2));
+      return 0;
+    }
+    if (sub === "list") { console.log(JSON.stringify(await watches.list(), null, 2)); return 0; }
+    if (sub === "check") {
+      const id = rest[1];
+      if (!id || id.startsWith("--")) return fail("watch check needs a monitor id; `openings watch list` shows them");
+      console.log(JSON.stringify(await watches.check({ id, peek: rest.includes("--peek") }), null, 2));
+      return 0;
+    }
+    if (sub === "stop") {
+      const id = rest[1];
+      if (!id) return fail("watch stop needs a monitor id");
+      console.log(JSON.stringify(await watches.stop({ id }), null, 2));
+      return 0;
+    }
+    if (sub === "run") {
+      // What a scheduler calls. Refresh first so the monitor is reading today's index, then tell the desktop.
+      if (!rest.includes("--no-refresh")) await runtime.prepareJobSearch({ countries: (argValue(rest, "--country") ?? "IN,US").split(",") }).catch(() => undefined);
+      console.log(JSON.stringify(await watches.sweep(), null, 2));
+      return 0;
+    }
+    return fail("watch takes add, list, check, stop or run");
+  }
+
   if (command === "coverage") {
     if (rest[0] !== "report") return fail("coverage requires the `report` subcommand");
     const parsed = parseCoverageReport(rest.slice(1));

package/src/desktop-notify.ts

@@ -0,0 +1,27 @@
+/**
+ * A desktop notification, using whatever the machine already has.
+ *
+ * No dependency and no daemon: each platform ships something that puts a line on screen, and a monitor that runs
+ * on your own machine should not need a package to tell you it found something. Failure is silent by design —
+ * a missing notifier must never stop a monitor from recording what it found.
+ */
+const QUOTE = /["\\]/g;
+
+export async function notifyDesktop(title: string, body: string): Promise<boolean> {
+  const safeTitle = title.replace(QUOTE, "").slice(0, 120);
+  const safeBody = body.replace(QUOTE, "").slice(0, 240);
+  const attempts: string[][] = process.platform === "darwin"
+    ? [["osascript", "-e", `display notification "${safeBody}" with title "${safeTitle}"`]]
+    : process.platform === "win32"
+      ? [["powershell", "-NoProfile", "-Command",
+          `[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime] > $null; ` +
+          `Write-Output "${safeTitle}: ${safeBody}"`]]
+      : [["notify-send", safeTitle, safeBody], ["kdialog", "--passivepopup", `${safeTitle}\n${safeBody}`, "10"]];
+  for (const command of attempts) {
+    try {
+      const proc = Bun.spawn(command, { stdout: "ignore", stderr: "ignore" });
+      if (await proc.exited === 0) return true;
+    } catch { /* try the next one, or give up quietly */ }
+  }
+  return false;
+}

package/src/local-watches.ts

@@ -0,0 +1,146 @@
+/**
+ * Monitors that live on the candidate's own machine.
+ *
+ * The hosted monitor stores a derived profile on our server and emails what it finds. This one stores the same
+ * profile in the user's data directory and tells their desktop instead, which means the resume, the profile and
+ * the record of what has been seen never leave the machine at all. There is no account, no email address, and
+ * nothing for us to lose.
+ *
+ * It satisfies the same interface the hosted monitors do, so the four MCP tools behave identically whether an
+ * assistant is talking to a local install or to the hosted server.
+ */
+import { join } from "node:path";
+import { atomicJson } from "./atomic-file.ts";
+import { describeWatchProfile, matchWatch, toWatchProfile, type WatchableJob, type WatchProfile } from "./watch-profile.ts";
+import type { CandidateProfile } from "./candidate-profile.ts";
+
+export interface StoredWatch {
+  id: string;
+  label?: string;
+  profile: WatchProfile;
+  createdAt: string;
+  lastCheckedAt?: string;
+  /** Job ids already reported. Kept so a monitor says "new" and means it. */
+  seen: string[];
+}
+
+interface WatchFile { version: 1; watches: StoredWatch[] }
+
+const CAP_SEEN = 4_000;
+
+export interface LocalWatchOptions {
+  dataDir: string;
+  /** Live roles to match against; the caller supplies them from whichever index it already holds. */
+  jobs(): Promise<WatchableJob[]>;
+  /** Parses a resume into facts. The same parser the one-off tools use. */
+  profileFromResume(input: unknown): Promise<CandidateProfile>;
+  notify?(title: string, body: string): Promise<void>;
+  now?: () => Date;
+}
+
+export function createLocalWatches(options: LocalWatchOptions) {
+  const now = options.now ?? (() => new Date());
+  const path = join(options.dataDir, "watches.json");
+
+  async function read(): Promise<WatchFile> {
+    try {
+      const file = await Bun.file(path).json() as WatchFile;
+      return file?.version === 1 && Array.isArray(file.watches) ? file : { version: 1, watches: [] };
+    } catch { return { version: 1, watches: [] }; }
+  }
+  const write = (file: WatchFile) => atomicJson(path, file);
+
+  return {
+    async create(input: unknown) {
+      const body = (input ?? {}) as { resume?: unknown; intent?: Record<string, unknown>; label?: string };
+      if (!body.resume) throw new Error("watch_jobs needs a resume to derive a profile from");
+      const parsed = await options.profileFromResume({ resume: body.resume });
+      const intent = (body.intent ?? {}) as { countries?: string[]; locations?: string[]; remote?: boolean; excludedTerms?: string[] };
+      const profile = toWatchProfile(parsed, intent);
+      const file = await read();
+      const watch: StoredWatch = {
+        id: `w_${now().getTime().toString(36)}${Math.random().toString(36).slice(2, 6)}`,
+        ...(body.label ? { label: String(body.label).slice(0, 60) } : {}),
+        profile, createdAt: now().toISOString(), seen: [],
+      };
+      // Everything live counts as already seen, or the first check would report the whole index as new.
+      const jobs = await options.jobs();
+      const matches = matchWatch(profile, jobs, 20);
+      watch.seen = matchWatch(profile, jobs, 100_000).map((m) => m.job.id).slice(0, CAP_SEEN);
+      watch.lastCheckedAt = now().toISOString();
+      file.watches.push(watch);
+      await write(file);
+      return {
+        id: watch.id, holding: describeWatchProfile(profile), profile,
+        matchesNow: matches.map((m) => ({ ...m.job, why: m.reasons })),
+        emailing: false,
+        storedAt: path,
+        note: "This monitor is on your machine. The resume was read once and discarded; what is kept is the profile shown above, in a file you can open or delete.",
+      };
+    },
+
+    async list() {
+      const file = await read();
+      return { watches: file.watches.map((w) => ({
+        id: w.id, label: w.label, holding: describeWatchProfile(w.profile),
+        createdAt: w.createdAt, lastCheckedAt: w.lastCheckedAt, reported: w.seen.length,
+      })), storedAt: path };
+    },
+
+    async check(input: unknown) {
+      const body = (input ?? {}) as { id?: string; limit?: number; peek?: boolean };
+      const file = await read();
+      const watch = file.watches.find((w) => w.id === body.id);
+      if (!watch) throw new Error(`No monitor with id ${body.id}. Call list_watches to see them.`);
+      const jobs = await options.jobs();
+      const seen = new Set(watch.seen);
+      const fresh = matchWatch(watch.profile, jobs, 100_000).filter((m) => !seen.has(m.job.id));
+      const limited = fresh.slice(0, Math.min(body.limit ?? 20, 50));
+      const checkedAt = now().toISOString();
+      if (!body.peek) {
+        // Everything found is marked seen, not only what was returned, or the rest would arrive again tomorrow.
+        watch.seen = [...fresh.map((m) => m.job.id), ...watch.seen].slice(0, CAP_SEEN);
+        watch.lastCheckedAt = checkedAt;
+        await write(file);
+      }
+      return {
+        matches: limited.map((m) => ({ ...m.job, why: m.reasons })),
+        totalNew: fresh.length, checkedAt, newSince: watch.lastCheckedAt ?? watch.createdAt,
+        holding: describeWatchProfile(watch.profile),
+      };
+    },
+
+    async stop(input: unknown) {
+      const id = ((input ?? {}) as { id?: string }).id;
+      const file = await read();
+      const before = file.watches.length;
+      file.watches = file.watches.filter((w) => w.id !== id);
+      await write(file);
+      return { stopped: before !== file.watches.length,
+        deleted: before !== file.watches.length ? "the monitor, its profile, and the record of what it had reported" : "nothing; no monitor had that id" };
+    },
+
+    /** Check every monitor and tell the desktop about anything new. This is what a scheduled run calls. */
+    async sweep() {
+      const file = await read();
+      const jobs = await options.jobs();
+      const results: Array<{ id: string; label?: string; found: number }> = [];
+      for (const watch of file.watches) {
+        const seen = new Set(watch.seen);
+        const fresh = matchWatch(watch.profile, jobs, 100_000).filter((m) => !seen.has(m.job.id));
+        if (fresh.length) {
+          watch.seen = [...fresh.map((m) => m.job.id), ...watch.seen].slice(0, CAP_SEEN);
+          const first = fresh[0]!;
+          await options.notify?.(
+            `${fresh.length} new role${fresh.length === 1 ? "" : "s"} for ${watch.label ?? "your monitor"}`,
+            `${first.job.title} at ${first.job.company}${fresh.length > 1 ? ` and ${fresh.length - 1} more` : ""}`,
+          ).catch(() => undefined);
+        }
+        watch.lastCheckedAt = now().toISOString();
+        results.push({ id: watch.id, label: watch.label, found: fresh.length });
+      }
+      await write(file);
+      return { checked: file.watches.length, results };
+    },
+  };
+}

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.1.59";
+export const VERSION = "0.1.61";