openings 0.1.17 → 0.1.18

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Find evidence-grounded jobs, including relevant roles you may not have searched for, without accounts or API keys.",
   "author": { "name": "Openings contributors" },
   "license": "MIT",

package/README.md

@@ -95,6 +95,8 @@ The packaged server reports each source you crawl to the shared Openings aggrega
 
 The server also sends anonymous usage events so we can see what people search for and improve coverage. Each install gets a random ID on first run, stored in the data directory. An event records the tool that ran, the countries, the intent fields you passed (roles, seniority, skills, remote, query text), the IDs of jobs you opened, and the skill and title values the parser extracted from a resume. It never includes the resume text, the quoted evidence, your name, or contact details, and no IP address is stored with it. Set `OPENINGS_USAGE=off` to stop usage events while keeping the shared index, or set `OPENINGS_AGGREGATOR_URL` to an empty string to keep everything local. The source entrypoint reports only when the aggregator variable is set.
 
+On startup the server makes one request to the npm registry to learn the latest version. If yours is older, every tool result carries an `updateAvailable` note so your AI app can tell you to run `bun add --global openings`. Nothing on your machine is changed automatically. Set `OPENINGS_UPDATE_CHECK=off` to skip the check.
+
 ## Privacy
 
 Job data comes straight from public ATS endpoints and is stored only on your machine. Your MCP client reads the resume file and passes its content to a tool; Openings never sees the path and never persists the content or anything derived from it. Every proposed change stays subject to your review.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openings",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "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/mcp.ts

@@ -3,6 +3,7 @@ import { createRuntime } from "./runtime.ts";
 import { createToolHandler } from "./tools.ts";
 import { usageEventFor } from "./usage.ts";
 import { VERSION } from "./version.ts";
+import { startUpdateCheck, type UpdateNotice } from "./update-check.ts";
 
 interface RpcRequest {
   jsonrpc: "2.0";
@@ -16,7 +17,9 @@ interface ToolHandler {
   call(name: string, input: Record<string, unknown>): Promise<unknown>;
 }
 
-export function createMcpHandler(tools: ToolHandler) {
+export function createMcpHandler(tools: ToolHandler, options: { update?: () => UpdateNotice | null } = {}) {
+  /** A pending update rides on every tool result so the AI app can prompt the person; nothing is changed on their machine. */
+  const withUpdate = (payload: unknown) => { const update = options.update?.(); return update && isRecord(payload) ? { ...payload, updateAvailable: update } : payload; };
   return async (value: unknown) => {
     if (!isRpcRequest(value)) return { jsonrpc: "2.0" as const, id: invalidRequestId(value), error: { code: -32600, message: "Invalid Request" } };
     const request = value;
@@ -24,7 +27,8 @@ export function createMcpHandler(tools: ToolHandler) {
     const base = { jsonrpc: "2.0" as const, id: request.id ?? null };
     try {
       if (request.method === "initialize") {
-        return { ...base, result: { protocolVersion: "2025-06-18", capabilities: { tools: {} }, serverInfo: { name: "openings", version: VERSION } } };
+        const update = options.update?.();
+        return { ...base, result: { protocolVersion: "2025-06-18", capabilities: { tools: {} }, serverInfo: { name: "openings", version: VERSION }, ...(update ? { instructions: update.message } : {}) } };
       }
       if (request.method === "ping") return { ...base, result: {} };
       if (request.method === "tools/list") return { ...base, result: { tools: tools.list() } };
@@ -36,11 +40,11 @@ export function createMcpHandler(tools: ToolHandler) {
         if (args !== undefined && !isRecord(args)) throw new Error("tools/call arguments must be an object");
         try {
           const result = await tools.call(name, args ?? {});
-          return { ...base, result: { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], isError: false } };
+          return { ...base, result: { content: [{ type: "text", text: JSON.stringify(withUpdate(result), null, 2) }], isError: false } };
         } catch (error) {
           const details = errorDetails(error);
           const payload = { error: { message: error instanceof Error ? error.message : String(error), ...(details ?? {}) } };
-          return { ...base, result: { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], isError: true } };
+          return { ...base, result: { content: [{ type: "text", text: JSON.stringify(withUpdate(payload), null, 2) }], isError: true } };
         }
       }
       if (request.method.startsWith("notifications/")) return null;
@@ -78,7 +82,8 @@ export async function serve() {
     search: async (query: import("./types.ts").SearchQuery) => (await runtime.search(query, { offline: false, staleDays: 14 })).jobs,
     get: async (id: string) => (await runtime.get(id, { offline: false, staleDays: 14 })).job,
   };
-  const handle = createMcpHandler(createToolHandler(catalog, runtime, { onCall: (name, input, result) => runtime.usage?.record(usageEventFor(name, input, result)) }));
+  const updates = startUpdateCheck({ enabled: (process.env.OPENINGS_UPDATE_CHECK ?? "on").toLowerCase() !== "off" });
+  const handle = createMcpHandler(createToolHandler(catalog, runtime, { onCall: (name, input, result) => runtime.usage?.record(usageEventFor(name, input, result)) }), { update: updates.get });
   const decoder = new TextDecoder();
   let buffer = "";
   for await (const chunk of Bun.stdin.stream()) {

package/src/update-check.ts

@@ -0,0 +1,39 @@
+import { VERSION } from "./version.ts";
+
+export interface UpdateNotice { installed: string; latest: string; run: string; message: string }
+type Fetch = (input: string, init?: RequestInit) => Promise<Response>;
+
+export const UPDATE_COMMAND = "bun add --global openings";
+
+/**
+ * One small request to the npm registry at startup, never blocking a tool call. The result rides on every tool
+ * response so the AI app can prompt the person to update; the server itself never modifies the install.
+ */
+export function startUpdateCheck(options: { current?: string; fetcher?: Fetch; timeoutMs?: number; enabled?: boolean } = {}): { get(): UpdateNotice | null; ready: Promise<void> } {
+  const current = options.current ?? VERSION;
+  let notice: UpdateNotice | null = null;
+  const ready = options.enabled === false ? Promise.resolve() : (async () => {
+    try {
+      const response = await (options.fetcher ?? globalThis.fetch)("https://registry.npmjs.org/openings/latest", { signal: AbortSignal.timeout(options.timeoutMs ?? 5_000), headers: { accept: "application/json" } });
+      if (!response.ok) return;
+      const body = await response.json() as { version?: unknown };
+      if (typeof body.version === "string" && isNewer(body.version, current)) notice = updateNotice(current, body.version);
+    } catch { /* offline or blocked: no notice */ }
+  })();
+  return { get: () => notice, ready };
+}
+
+export function updateNotice(installed: string, latest: string): UpdateNotice {
+  return { installed, latest, run: UPDATE_COMMAND, message: `Openings ${latest} is available; ${installed} is installed. Tell the person to run "${UPDATE_COMMAND}" and restart their AI app to get fixes and new coverage.` };
+}
+
+/** Numeric dot-version comparison; pre-release suffixes are ignored. */
+export function isNewer(candidate: string, current: string): boolean {
+  const parse = (value: string) => value.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const [left, right] = [parse(candidate), parse(current)];
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const difference = (left[index] ?? 0) - (right[index] ?? 0);
+    if (difference !== 0) return difference > 0;
+  }
+  return false;
+}

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.1.17";
+export const VERSION = "0.1.18";