@aidriftline/driftline 0.0.0-stage → 0.1.10

package/src/cli.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// Local use:
+//   driftline [directory]              scan and print the report (drift tests run when
+//                                      .driftline/prompts.yml, DRIFTLINE_LICENSE_KEY and provider keys exist)
+//   driftline activate <license-key>   register this GitHub account; prints the code to save as DRIFTLINE_LICENSE_KEY
+//   driftline deactivate <code>        free that account's slot (a key works on up to 3 accounts)
+//   driftline [directory] --json       same scan, machine-readable (for scripts and coding agents)
+//   driftline mcp                      MCP server on stdio for coding agents (Claude Code, Cursor, ...)
+//   driftline --help | --version
+import { resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { run } from "./run.js";
+import { activate, deactivate } from "./license.js";
+
+const JSON_OUT = process.argv.includes("--json");
+const [cmd, arg] = process.argv.slice(2).filter((a) => a !== "--json");
+const flag = (name) => { const i = process.argv.indexOf(`--${name}`); return i > 0 ? process.argv[i + 1] : ""; };
+
+// "git@github.com:acme/app.git" or "https://github.com/acme/app" -> "acme"
+function accountFromGit() {
+  try {
+    const url = execFileSync("git", ["remote", "get-url", "origin"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return url.match(/github\.com[:/]([^/]+)\//i)?.[1] || "";
+  } catch { return ""; }
+}
+
+const HELP = `Driftline: finds AI model IDs in your code and warns before they are retired.
+
+Usage:
+  npx github:AI-Driftline/driftline [directory]            scan and print the report
+  npx github:AI-Driftline/driftline activate <license-key>  register this GitHub account for Pro
+  npx github:AI-Driftline/driftline deactivate <code>       free that account's slot
+  npx github:AI-Driftline/driftline mcp                     MCP server for coding agents (stdio)
+
+Options:
+  --json             print the scan as JSON (for scripts and coding agents)
+  --account <name>   GitHub account to activate for (default: origin remote owner)
+  -h, --help         show this help
+  -v, --version      show the version
+
+Exit code: 1 if a retired model is used in code, 0 otherwise.
+Retirement dates for every model: https://aidriftline.com/models/
+Docs: https://github.com/AI-Driftline/driftline`;
+
+if (cmd === "-h" || cmd === "--help" || cmd === "help") {
+  console.log(HELP);
+} else if (cmd === "-v" || cmd === "--version") {
+  console.log(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version);
+} else if (cmd?.startsWith("-")) {
+  console.error(`Unknown option ${cmd}\n\n${HELP}`);
+  process.exitCode = 2;
+} else if (cmd === "mcp") {
+  const { startServer } = await import("./mcp.js");
+  startServer();
+} else if (cmd === "activate") {
+  const account = flag("account") || accountFromGit();
+  const r = await activate(arg, account);
+  if (!r.ok) { console.error(r.reason); process.exitCode = 1; }
+  else {
+    console.log(`Activated for GitHub account "${account}"${r.limit ? ` (${r.used} of ${r.limit} used)` : ""}.\n`);
+    console.log("Save this as a repository or organization secret named DRIFTLINE_LICENSE_KEY:\n");
+    console.log(`  ${r.code}\n`);
+  }
+} else if (cmd === "deactivate") {
+  const r = await deactivate(arg);
+  if (!r.ok) { console.error(r.reason); process.exitCode = 1; }
+  else console.log("Deactivated. That slot is free for another GitHub account.");
+} else {
+  const result = await run({
+    root: resolve(cmd || "."),
+    licenseKey: process.env.DRIFTLINE_LICENSE_KEY || "",
+    account: process.env.GITHUB_REPOSITORY_OWNER || accountFromGit(),
+    log: (m) => console.error(m),
+  });
+  if (JSON_OUT) {
+    const pick = (f) => ({
+      id: f.id, file: f.file, line: f.line, status: f.status, docOnly: !!f.doc,
+      provider: f.entry?.provider, retires: f.entry?.retires, qualifier: f.entry?.qualifier,
+      replacement: f.entry?.replacement, routes: !!f.entry?.routes, aliasOf: f.entry?.aliasOf,
+    });
+    console.log(JSON.stringify({ findings: result.findings.map(pick), drift: result.drift || [] }, null, 2));
+  } else console.log(result.markdown);
+  process.exitCode = result.findings.some((f) => f.status === "retired" && !f.doc) ? 1 : 0;
+}

package/src/compare.js

@@ -0,0 +1,92 @@
+// Compares the current model's answer with the replacement model's answer.
+// Scores run from 0 (nothing in common) to 1 (identical in substance).
+
+const SAME = 0.9;
+const CHANGED = 0.6;
+
+// Words, except in scripts written without spaces (Chinese, Japanese, Thai), where each character
+// is a token; the word-pair pass below then compares them as character pairs.
+const NO_SPACES = "\\p{sc=Han}\\p{sc=Hiragana}\\p{sc=Katakana}\\p{sc=Thai}";
+const TOKEN = new RegExp(`[${NO_SPACES}]|(?:(?![${NO_SPACES}])[\\p{L}\\p{N}])+`, "gu");
+
+function tokens(text) {
+  return text.toLowerCase().match(TOKEN) || [];
+}
+
+function vector(text) {
+  const t = tokens(text);
+  const v = new Map();
+  const add = (k) => v.set(k, (v.get(k) || 0) + 1);
+  t.forEach((w, i) => { add(w); if (i > 0) add(t[i - 1] + " " + w); });
+  return v;
+}
+
+export function textSimilarity(a, b) {
+  if (a.trim() === b.trim()) return 1;
+  const va = vector(a), vb = vector(b);
+  let dot = 0, na = 0, nb = 0;
+  for (const [k, x] of va) { na += x * x; if (vb.has(k)) dot += x * vb.get(k); }
+  for (const [, y] of vb) nb += y * y;
+  return na && nb ? dot / Math.sqrt(na * nb) : 0;
+}
+
+// Models often wrap JSON in ```json fences or a sentence; pull out the JSON part.
+export function extractJson(text) {
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidate = (fenced ? fenced[1] : text).trim();
+  try { return { ok: true, value: JSON.parse(candidate) }; } catch {}
+  // JSON after a sentence, which may itself contain braces: try each opening bracket in turn.
+  const end = Math.max(candidate.lastIndexOf("}"), candidate.lastIndexOf("]"));
+  let tries = 0;
+  for (let start = candidate.search(/[[{]/); start >= 0 && start < end && tries < 50; tries++) {
+    try { return { ok: true, value: JSON.parse(candidate.slice(start, end + 1)) }; } catch {}
+    const next = candidate.slice(start + 1).search(/[[{]/);
+    start = next < 0 ? -1 : start + 1 + next;
+  }
+  return { ok: false };
+}
+
+function paths(value, prefix = "", out = new Map()) {
+  if (value && typeof value === "object") {
+    const entries = Array.isArray(value) ? value.slice(0, 20).map((v, i) => [String(i), v]) : Object.entries(value);
+    if (!entries.length) out.set(prefix || "$", JSON.stringify(value));
+    for (const [k, v] of entries) paths(v, Array.isArray(value) ? `${prefix}[]` : `${prefix}.${k}`, out);
+  } else {
+    out.set(prefix || "$", String(value).trim().toLowerCase());
+  }
+  return out;
+}
+
+export function jsonSimilarity(a, b) {
+  const pa = paths(a), pb = paths(b);
+  const keys = new Set([...pa.keys(), ...pb.keys()]);
+  if (!keys.size) return 1;
+  let score = 0;
+  for (const k of keys) {
+    if (pa.has(k) && pb.has(k)) score += pa.get(k) === pb.get(k) ? 1 : 0.5; // same field, different value
+  }
+  return score / keys.size;
+}
+
+/**
+ * Returns { score, result, note } where result is: same | changed | broken
+ */
+export function compare(before, after, expect = "text") {
+  const emptyBefore = !String(before ?? "").trim(), emptyAfter = !String(after ?? "").trim();
+  if (emptyBefore && emptyAfter) return { score: 0, result: "error", note: "Both models returned an empty answer" };
+  if (emptyAfter) return { score: 0, result: "broken", note: "Replacement returned an empty answer" };
+  if (emptyBefore) return { score: 0, result: "changed", note: "Current model returned an empty answer; review the replacement's" };
+  if (expect === "json") {
+    const a = extractJson(before), b = extractJson(after);
+    if (!b.ok) return { score: 0, result: "broken", note: "Replacement did not return valid JSON" };
+    if (!a.ok) return { score: 0.5, result: "changed", note: "Current model did not return valid JSON; replacement did" };
+    const score = jsonSimilarity(a.value, b.value);
+    return { score, result: label(score), note: score < 1 ? "JSON fields or values differ" : "" };
+  }
+  const score = textSimilarity(before, after);
+  return { score, result: label(score), note: "" };
+}
+
+function label(score) {
+  return score >= SAME ? "same" : score >= CHANGED ? "changed" : "broken";
+}

package/src/github.js

@@ -0,0 +1,57 @@
+import { appendFileSync } from "node:fs";
+
+export function input(name, fallback = "") {
+  const v = process.env[`INPUT_${name.replace(/ /g, "_").toUpperCase()}`];
+  return v === undefined || v === "" ? fallback : v.trim();
+}
+
+export function setOutput(name, value) {
+  if (process.env.GITHUB_OUTPUT) appendFileSync(process.env.GITHUB_OUTPUT, `${name}=${value}\n`);
+}
+
+export function writeSummary(markdown) {
+  if (process.env.GITHUB_STEP_SUMMARY) appendFileSync(process.env.GITHUB_STEP_SUMMARY, markdown + "\n");
+}
+
+// GitHub workflow commands for annotations on the changed lines.
+const escProp = (v) => String(v).replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A").replace(/:/g, "%3A").replace(/,/g, "%2C");
+
+export function annotate(level, message, file, line) {
+  const loc = file ? ` file=${escProp(file)},line=${line}` : "";
+  console.log(`::${level}${loc}::${message.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A")}`);
+}
+
+const TITLE = "Driftline: AI model retirement report";
+
+async function failure(res, what) {
+  let detail = "";
+  try { detail = ((await res.json())?.message || "").slice(0, 200); } catch {}
+  const hint = res.status === 403 || res.status === 404 ? ' Does the workflow have "issues: write" permission?' : "";
+  return new Error(`Could not ${what}: HTTP ${res.status}${detail ? ` (${detail})` : ""}.${hint}`);
+}
+
+// Opens one issue labelled "driftline", or updates it if it is already open.
+// With close: true, an open report issue is updated with the all-clear and closed; none is opened.
+export async function upsertIssue(body, { token, repo = process.env.GITHUB_REPOSITORY, fetchImpl = fetch, close = false } = {}) {
+  if (!token || !repo) return { skipped: "No GitHub token or repository." };
+  const api = process.env.GITHUB_API_URL || "https://api.github.com";
+  const headers = {
+    authorization: `Bearer ${token}`,
+    accept: "application/vnd.github+json",
+    "x-github-api-version": "2022-11-28",
+    "content-type": "application/json",
+  };
+  const list = await fetchImpl(`${api}/repos/${repo}/issues?labels=driftline&state=open&per_page=100`, { headers });
+  if (!list.ok) throw await failure(list, "list issues");
+  const existing = (await list.json()).find((i) => i.title === TITLE && !i.pull_request);
+  if (close && !existing) return { skipped: "Nothing flagged and no open Driftline issue." };
+  const url = existing ? `${api}/repos/${repo}/issues/${existing.number}` : `${api}/repos/${repo}/issues`;
+  const res = await fetchImpl(url, {
+    method: existing ? "PATCH" : "POST",
+    headers,
+    body: JSON.stringify(existing ? { body, ...(close ? { state: "closed" } : {}) } : { title: TITLE, body, labels: ["driftline"] }),
+  });
+  if (!res.ok) throw await failure(res, `${existing ? "update" : "open"} issue`);
+  const issue = await res.json();
+  return { number: issue.number, url: issue.html_url, updated: Boolean(existing), closed: close };
+}

package/src/index.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// GitHub Action entry point.
+import { resolve } from "node:path";
+import { statSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { run } from "./run.js";
+import { input, setOutput, writeSummary, annotate, upsertIssue } from "./github.js";
+
+const STATUS_TEXT = {
+  retired: "is retired",
+  "at-risk": "retires soon",
+  deprecated: "is deprecated",
+};
+
+async function main() {
+  const workspace = process.env.GITHUB_WORKSPACE || process.cwd();
+  const root = resolve(workspace, input("path", "."));
+  let isDir = false;
+  try { isDir = statSync(root).isDirectory(); } catch {}
+  if (!isDir) throw new Error(`path "${input("path", ".")}" is not a folder in this repository`);
+  const wd = Number(input("warn-days", "90"));
+  const warnDays = Number.isFinite(wd) && wd >= 0 ? wd : 90;
+  let failOn = input("fail-on", "retired").toLowerCase();
+  if (!["retired", "at-risk", "never"].includes(failOn)) {
+    annotate("warning", `Unknown fail-on value "${failOn}". Use retired, at-risk or never. Using "retired".`);
+    failOn = "retired";
+  }
+
+  const result = await run({
+    root,
+    repoRoot: workspace,
+    warnDays,
+    promptsFile: input("prompts-file", ".driftline/prompts.yml"),
+    licenseKey: input("license-key"),
+    account: process.env.GITHUB_REPOSITORY_OWNER || "",
+    log: (m) => console.log(m),
+    answers: input("show-answers", "true") !== "false",
+  });
+
+  // GitHub shows only a handful of annotations per step; send the most urgent, point to the report for the rest.
+  const MAX_ANNOTATIONS = 50;
+  const rank = { retired: 0, "at-risk": 1, deprecated: 2 };
+  const toAnnotate = result.findings
+    .filter((f) => STATUS_TEXT[f.status])
+    .sort((a, b) => (a.doc - b.doc) || (rank[a.status] - rank[b.status]));
+  if (toAnnotate.length > MAX_ANNOTATIONS) {
+    annotate("notice", `${toAnnotate.length - MAX_ANNOTATIONS} more model references are listed in the job summary.`);
+  }
+  for (const f of toAnnotate.slice(0, MAX_ANNOTATIONS)) {
+    const level = f.status === "deprecated" || f.doc ? "notice" : "warning";
+    const repl = f.entry?.replacement && !f.entry.routes ? ` Replacement: ${f.entry.replacement}.` : "";
+    const text = f.entry.routes && f.entry.replacement
+      ? (f.days <= 0
+        ? `Since ${f.entry.retires}, requests to ${f.id} are answered by ${f.entry.replacement}. The call still works, but the model behind it changed.`
+        : `From ${f.entry.retires}, requests to ${f.id} will be answered by ${f.entry.replacement}. The call keeps working, but the model behind it changes.`)
+      : f.entry.qualifier === "earliest" && f.days <= 0
+      ? `${f.id} is past its earliest shutdown date (${f.entry.retires}) and may stop working at any time.`
+      : `${f.id} ${STATUS_TEXT[f.status]} (${f.entry.retires}).`;
+    annotate(level, text + repl, f.file, f.line);
+  }
+
+  // The report contains model answers; stop GitHub from reading any "::command::" lines inside it.
+  const token = `driftline-${randomUUID()}`;
+  console.log(`::stop-commands::${token}`);
+  console.log("\n" + result.markdown);
+  console.log(`::${token}::`);
+  writeSummary(result.markdown);
+  setOutput("findings", result.findings.length);
+  setOutput("at-risk", result.atRisk);
+
+  if (input("create-issue", "false") === "true") {
+    // Something flagged in code: open or update the issue. Nothing flagged: close it with the all-clear.
+    const flagged = result.findings.some((f) => STATUS_TEXT[f.status] && !f.doc);
+    const body = flagged ? result.issueMarkdown : `${result.issueMarkdown}\n\n✅ No retired or retiring models are left in the code. Closing this issue.`;
+    try {
+      const issue = await upsertIssue(body, { token: input("github-token"), close: !flagged });
+      if (issue.url) console.log(`${issue.closed ? "Closed" : issue.updated ? "Updated" : "Opened"} issue: ${issue.url}`);
+      else console.log(issue.skipped);
+    } catch (e) {
+      annotate("warning", `Driftline issue: ${e.message}`);
+    }
+  }
+
+  // Mentions in Markdown and text files are reported but never fail the build.
+  const inCode = result.findings.filter((f) => !f.doc);
+  const retired = inCode.some((f) => f.status === "retired");
+  const atRisk = inCode.some((f) => f.status === "at-risk");
+  if ((failOn === "retired" && retired) || (failOn === "at-risk" && (retired || atRisk))) {
+    console.log(`::error::Driftline found ${failOn === "retired" ? "retired" : "retired or soon-to-retire"} models (fail-on: ${failOn}).`);
+    process.exitCode = 1;
+  }
+}
+
+main().catch((e) => {
+  console.log(`::error::Driftline failed: ${e.message}`);
+  process.exitCode = 1;
+});

package/src/license.js

@@ -0,0 +1,133 @@
+// Pro features (drift tests) need a Lemon Squeezy license, activated once per GitHub account.
+// API: https://api.lemonsqueezy.com/v1/licenses/{activate,validate,deactivate} (form fields)
+//
+// A key works on up to 3 GitHub accounts or organizations (the activation limit set in Lemon Squeezy).
+// `driftline activate <key>` registers one account and prints a license code: "<key>:<instance id>".
+// The Action checks that code on every run and that it was activated for the account it runs in.
+
+// Only keys from Driftline's own store and product unlock Pro. A key bought in another store,
+// or for another product in this store, is rejected. (null / [] = no check; tests use that.)
+// Live product only. Never add the test-mode product (1428709): free test keys would unlock Pro.
+export const LICENSE = { storeId: 494524, productIds: [1432580] };
+
+const API = "https://api.lemonsqueezy.com/v1/licenses";
+const ACTIVATE_HELP = "Run `npx github:AI-Driftline/driftline activate <your-license-key>` once for this GitHub account and save the code it prints as DRIFTLINE_LICENSE_KEY.";
+
+// "expired": the subscription ended. "disabled": refunded or blocked.
+const ENDED = ["expired", "disabled"];
+const endedReason = (status) => `Driftline Pro has ended for this license key (${status}: the subscription ran out or was refunded). The scan still runs; drift tests are off. Renew at https://aidriftline.com.`;
+
+export const instanceName = (account) => `github:${String(account).trim().toLowerCase()}`;
+
+export function parseCode(code) {
+  const s = String(code || "").trim();
+  const i = s.lastIndexOf(":");
+  return i > 0 ? { key: s.slice(0, i), instanceId: s.slice(i + 1) } : { key: s, instanceId: "" };
+}
+
+// Lemon Squeezy license keys and instance ids are UUIDs (per its API docs).
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const looksReal = (key, instanceId) => UUID.test(key) && UUID.test(instanceId);
+
+async function call(fetchImpl, action, fields) {
+  return fetchImpl(`${API}/${action}`, {
+    method: "POST",
+    headers: { accept: "application/json", "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(fields).toString(),
+    signal: AbortSignal.timeout(15_000),
+  });
+}
+
+const productOk = (data) =>
+  (LICENSE.storeId == null || Number(data.meta?.store_id) === Number(LICENSE.storeId)) &&
+  (!LICENSE.productIds.length || LICENSE.productIds.map(Number).includes(Number(data.meta?.product_id)));
+
+/**
+ * Checks a license code on each run. `account` is the GitHub owner the code runs in
+ * (GITHUB_REPOSITORY_OWNER in CI, else the origin remote); Pro needs it, or one key would work everywhere.
+ */
+export async function checkLicense(code, { fetchImpl = fetch, account = "" } = {}) {
+  if (!code) return { ok: false, reason: "No license key. The scan ran; drift tests need Driftline Pro." };
+  const { key, instanceId } = parseCode(code);
+  if (!instanceId) return { ok: false, reason: `This license key is not activated yet. ${ACTIVATE_HELP}` };
+  if (!String(account).trim()) return { ok: false, reason: "Could not tell which GitHub account this runs in, so drift tests were skipped. Run inside a repository whose origin is on GitHub." };
+
+  // Do not punish paying users for a network blip: allow the run and say so. Only for codes shaped
+  // like a real one, so blocking api.lemonsqueezy.com with a made-up code like "a:b" unlocks nothing.
+  const outage = (why) => looksReal(key, instanceId)
+    ? { ok: true, reason: `License server ${why}; drift tests ran anyway.` }
+    : { ok: false, reason: `License server ${why}, and this is not a Driftline license code. ${ACTIVATE_HELP}` };
+  let res;
+  try {
+    res = await call(fetchImpl, "validate", { license_key: key, instance_id: instanceId });
+  } catch (e) {
+    return outage(`unreachable (${e.message})`);
+  }
+  if (res.status === 429 || res.status >= 500) return outage(`unavailable (HTTP ${res.status})`);
+  let data = null;
+  try { data = await res.json(); } catch {}
+  if (!data || typeof data !== "object") return { ok: false, reason: `License key could not be checked (HTTP ${res.status}).` };
+  if (!data.valid) {
+    const ended = await keyStatus(fetchImpl, key);
+    if (ENDED.includes(ended)) return { ok: false, reason: endedReason(ended) };
+    const why = data.error ? `: ${String(data.error).replace(/\.+$/, "")}` : "";
+    return { ok: false, reason: `License not valid${why}. ${ACTIVATE_HELP}` };
+  }
+  const status = data.license_key?.status;
+  if (ENDED.includes(status)) return { ok: false, reason: endedReason(status) };
+  if (status && !["active", "inactive"].includes(status)) return { ok: false, reason: `License key is ${status}.` };
+  if (!productOk(data)) return { ok: false, reason: "License key belongs to a different product." };
+  if (!data.instance) return { ok: false, reason: `This activation was removed. ${ACTIVATE_HELP}` };
+  if (data.instance.name !== instanceName(account)) {
+    const where = String(data.instance.name || "").replace(/^github:/, "");
+    return { ok: false, reason: `This license code was activated for "${where}", not "${account}". A key works on up to 3 GitHub accounts or organizations. ${ACTIVATE_HELP}` };
+  }
+  return { ok: true };
+}
+
+// When a key expires or is refunded, Lemon Squeezy deletes its activations, so a code check only says
+// "instance_id not found". Asking about the key alone tells that apart from a slot freed with `deactivate`.
+async function keyStatus(fetchImpl, key) {
+  try {
+    const data = await (await call(fetchImpl, "validate", { license_key: key })).json();
+    return data?.license_key?.status;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Registers one GitHub account. Returns { ok, code } or { ok: false, reason }. */
+export async function activate(key, account, { fetchImpl = fetch } = {}) {
+  if (!key) return { ok: false, reason: "Give your license key: driftline activate <license-key>" };
+  if (!account) return { ok: false, reason: "Could not tell which GitHub account this is for. Add --account <name>." };
+  let res, data = null;
+  try {
+    res = await call(fetchImpl, "activate", { license_key: key.trim(), instance_name: instanceName(account) });
+    data = await res.json();
+  } catch (e) {
+    return { ok: false, reason: `Could not reach Lemon Squeezy: ${e.message}` };
+  }
+  if (!data?.activated) {
+    const status = data?.license_key?.status;
+    if (ENDED.includes(status)) return { ok: false, reason: endedReason(status) };
+    const limit = /activation limit/i.test(data?.error || "")
+      ? " This key is already used on 3 GitHub accounts. Deactivate one with `npx github:AI-Driftline/driftline deactivate <code>`, or write to hello@aidriftline.com."
+      : "";
+    return { ok: false, reason: `Not activated: ${String(data?.error || `HTTP ${res?.status}`).replace(/\.+$/, "")}.${limit}` };
+  }
+  if (!productOk(data)) return { ok: false, reason: "This key belongs to a different product." };
+  return { ok: true, code: `${key.trim()}:${data.instance.id}`, used: data.license_key?.activation_usage, limit: data.license_key?.activation_limit };
+}
+
+/** Frees the slot used by a license code. */
+export async function deactivate(code, { fetchImpl = fetch } = {}) {
+  const { key, instanceId } = parseCode(code);
+  if (!instanceId) return { ok: false, reason: "Give the license code that `driftline activate` printed (it contains a colon)." };
+  let data = null;
+  try {
+    data = await (await call(fetchImpl, "deactivate", { license_key: key, instance_id: instanceId })).json();
+  } catch (e) {
+    return { ok: false, reason: `Could not reach Lemon Squeezy: ${e.message}` };
+  }
+  return data?.deactivated ? { ok: true } : { ok: false, reason: `Not deactivated: ${data?.error || "unknown error"}` };
+}

package/src/mcp.js

@@ -0,0 +1,150 @@
+// MCP server (stdio): lets coding agents ask Driftline about model retirements.
+//   npx -y github:AI-Driftline/driftline mcp
+// Speaks JSON-RPC 2.0, one message per line on stdin/stdout (the MCP stdio transport). No dependencies.
+// Data: the live registry at aidriftline.com/models.json (updated daily), or the copy bundled with this
+// version when the site can't be reached or is older. Set DRIFTLINE_OFFLINE=1 to never fetch.
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { REGISTRY_PATH, buildRegistry, classify, normalizeId } from "./registry.js";
+import { scanDirectory } from "./scan.js";
+
+const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const LIVE_URL = "https://aidriftline.com/models.json";
+const page = (id) => `https://aidriftline.com/models/${id}/`;
+const WHO = { openai: "OpenAI", anthropic: "Anthropic", google: "Google" };
+
+export async function loadBestRegistry({ fetchImpl = fetch, offline = process.env.DRIFTLINE_OFFLINE === "1" } = {}) {
+  const bundled = JSON.parse(readFileSync(REGISTRY_PATH, "utf8"));
+  if (offline) return { reg: buildRegistry(bundled), source: "bundled" };
+  try {
+    const res = await fetchImpl(LIVE_URL, { signal: AbortSignal.timeout(4000) });
+    const live = res.ok ? await res.json() : null;
+    if (live?.models?.length && live.checked >= bundled.checked) return { reg: buildRegistry(live), source: "live" };
+  } catch { /* offline or slow: use the bundled copy */ }
+  return { reg: buildRegistry(bundled), source: "bundled" };
+}
+
+// One plain sentence an agent can pass on to the user.
+function advice(c) {
+  const m = c.entry;
+  if (!m) return "Not in Driftline's registry: no retirement is announced for it on the OpenAI, Anthropic or Google deprecation pages (or it is not a model ID).";
+  const who = WHO[m.provider] || m.provider;
+  const repl = m.replacement ? ` Replacement: ${m.replacement}.` : "";
+  if (m.qualifier === "not-before") return `Active. ${who} says it will not be retired before ${m.retires}.`;
+  if (m.routes) return c.days <= 0
+    ? `Since ${m.retires}, ${who} answers requests for it with ${m.replacement}. No error, but answers come from a different model.`
+    : `From ${m.retires} (in ${c.days} days), ${who} will answer requests for it with ${m.replacement}.`;
+  if (m.qualifier === "earliest") return c.days <= 0
+    ? `${who} listed ${m.retires} as the earliest shutdown date; it can stop working at any time now.${repl}`
+    : `${who} may shut it down from ${m.retires} (in ${c.days} days).${repl}`;
+  return c.days <= 0 ? `Retired on ${m.retires}. Calls to it fail.${repl}` : `Retires on ${m.retires} (in ${c.days} days). Calls fail after that.${repl}`;
+}
+
+function describe(rawId, reg, today) {
+  const id = normalizeId(rawId);
+  const c = classify(id, reg, { today });
+  const m = c.entry;
+  return {
+    id: rawId, ...(id !== rawId ? { normalized: id } : {}),
+    status: c.status, ...(m ? {
+      provider: m.provider, retires: m.retires, qualifier: m.qualifier, days_left: c.days,
+      replacement: m.replacement || null, routes: !!m.routes, ...(m.aliasOf ? { alias_of: m.aliasOf } : {}), page: page(m.aliasOf || m.id),
+    } : {}),
+    advice: advice(c),
+  };
+}
+
+const TOOLS = [
+  {
+    name: "check_models",
+    description: "Check AI model IDs (OpenAI, Anthropic, Google) for retirement: status, retirement date, replacement. Use before writing or keeping a model ID in code. Accepts provider spellings such as models/gemini-2.5-pro, openai/gpt-4o or Bedrock IDs.",
+    inputSchema: { type: "object", properties: { ids: { type: "array", items: { type: "string" }, minItems: 1, description: "Model IDs, e.g. [\"gpt-4o\", \"claude-sonnet-4-5\"]" } }, required: ["ids"] },
+  },
+  {
+    name: "scan_project",
+    description: "Scan a project folder for AI model IDs in code and config and report the ones that are retired, retiring or being re-routed, with file and line. Pass the absolute path of the project if unsure what the current directory is.",
+    inputSchema: { type: "object", properties: {
+      path: { type: "string", description: "Folder to scan (default: the server's current directory)" },
+      include_ok: { type: "boolean", description: "Also list models with no retirement announced (default false)" },
+    } },
+  },
+  {
+    name: "upcoming_retirements",
+    description: "List AI models retiring or being re-routed in the next N days, soonest first. Optionally filter by provider.",
+    inputSchema: { type: "object", properties: {
+      days: { type: "number", description: "Look-ahead window in days (default 90)" },
+      provider: { type: "string", enum: ["openai", "anthropic", "google"] },
+    } },
+  },
+];
+
+export async function callTool(name, args = {}, { reg, source, today = new Date() }) {
+  const meta = { registry_checked: reg.checked, registry_source: source, all_dates: "https://aidriftline.com/models/" };
+  if (name === "check_models") {
+    const ids = Array.isArray(args.ids) ? args.ids.filter((x) => typeof x === "string").slice(0, 100) : [];
+    if (!ids.length) throw new Error("ids must be a non-empty array of model ID strings");
+    return { models: ids.map((id) => describe(id, reg, today)), ...meta };
+  }
+  if (name === "scan_project") {
+    const root = resolve(args.path || ".");
+    const hits = scanDirectory(root, { known: reg.byId });
+    const rows = hits.map((h) => ({ file: h.file.split("\\").join("/"), line: h.line, in_docs: h.doc, ...describe(h.id, reg, today) }))
+      .filter((r) => args.include_ok || !["active", "unknown"].includes(r.status));
+    const order = { retired: 0, "at-risk": 1, deprecated: 2, active: 3, unknown: 4 };
+    rows.sort((a, b) => order[a.status] - order[b.status] || (a.days_left ?? 1e9) - (b.days_left ?? 1e9));
+    return { scanned: root, model_references: hits.length, flagged: rows.length, findings: rows.slice(0, 200),
+      ...(rows.length > 200 ? { truncated: true } : {}), ...meta };
+  }
+  if (name === "upcoming_retirements") {
+    const days = Number.isFinite(args.days) && args.days > 0 ? Math.min(args.days, 3650) : 90;
+    const list = reg.models
+      .filter((m) => m.qualifier !== "not-before" && (!args.provider || m.provider === args.provider))
+      .map((m) => describe(m.id, reg, today))
+      .filter((r) => r.days_left > 0 && r.days_left <= days)
+      .sort((a, b) => a.days_left - b.days_left || a.id.localeCompare(b.id));
+    return { days, count: list.length, models: list, ...meta };
+  }
+  throw new Error(`Unknown tool: ${name}`);
+}
+
+export function startServer({ input = process.stdin, output = process.stdout, load = loadBestRegistry } = {}) {
+  let registry = null;
+  const getRegistry = () => (registry ||= load());
+  const send = (msg) => output.write(JSON.stringify({ jsonrpc: "2.0", ...msg }) + "\n");
+
+  async function handle(msg) {
+    const { id, method, params } = msg;
+    switch (method) {
+      case "initialize":
+        getRegistry(); // start the download early
+        return { protocolVersion: params?.protocolVersion || "2025-06-18", capabilities: { tools: {} },
+          serverInfo: { name: "driftline", version: VERSION },
+          instructions: "Driftline knows when OpenAI, Anthropic and Google retire their models (from their official deprecation pages, checked daily). Call check_models before adding or keeping a model ID in code, and scan_project to audit a codebase." };
+      case "ping": return {};
+      case "tools/list": return { tools: TOOLS };
+      case "tools/call": {
+        try {
+          const result = await callTool(params?.name, params?.arguments || {}, await getRegistry());
+          return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], structuredContent: result };
+        } catch (e) {
+          return { content: [{ type: "text", text: e.message }], isError: true };
+        }
+      }
+      default:
+        if (id === undefined) return undefined; // notifications need no answer
+        throw Object.assign(new Error(`Method not found: ${method}`), { code: -32601 });
+    }
+  }
+
+  const rl = createInterface({ input });
+  rl.on("line", async (line) => {
+    if (!line.trim()) return;
+    let msg;
+    try { msg = JSON.parse(line); } catch { return send({ id: null, error: { code: -32700, message: "Parse error" } }); }
+    if (msg.id === undefined) { handle(msg).catch(() => {}); return; }
+    try { send({ id: msg.id, result: await handle(msg) }); }
+    catch (e) { send({ id: msg.id, error: { code: e.code || -32603, message: e.message } }); }
+  });
+  return rl;
+}