@gtrabanco/pi-nan-provider 0.5.2 → 0.6.1

package/AGENTS.md

@@ -115,7 +115,10 @@ Every PR that changes code MUST bump `package.json` version in the same PR; CI p
     "growing registry" — use tools/list to discover.
   - Community `nan-mcp-server` (https://github.com/luciferfran/nan-mcp-server):
     stdio MCP server, spawned per tool call (lazy), opt-in NAN_MEDIA_MCP=1,
-    version-pinned via NAN_MEDIA_MCP_VERSION (default 1.0.7) or a full command
+    version-pinned via NAN_MEDIA_MCP_VERSION (default 1.0.8) or a full command
     override via NAN_MEDIA_MCP_COMMAND. Tools: generate_image, edit_image,
     text_to_speech, list_voices, speech_to_text, embed, rerank, list_models
-    (we bridge the audio/image/transcription scope).
+    (we bridge the audio/image/transcription scope). An automated check
+    (scripts/check-nan-mcp-server.ts + .github/workflows/check-nan-mcp-server-update.yml)
+    compares the npm registry against the pin weekly and files a `dependencies` issue
+    with a breaking/safe verdict from the live server tool surface (unpkg).

package/README.es.md

@@ -98,8 +98,27 @@ Variables de entorno:
 | Variable | Por defecto | Significado |
 |---|---|---|
 | `NAN_MEDIA_MCP` | — | Override por sesión del puente de media: cualquier valor explícito (incl. `0`) gana al toggle persistido de `/nan-mcp`; sin definir → persistido/por defecto |
-| `NAN_MEDIA_MCP_VERSION` | `1.0.7` | Versión del servidor fijada para `npx -y nan-mcp-server@<v>` (recomendación de supply-chain del propio proyecto) |
-| `NAN_MEDIA_MCP_COMMAND` | — | Comando personalizado completo, p. ej. `bunx nan-mcp-server@1.0.7` |
+| `NAN_MEDIA_MCP_VERSION` | `1.0.8` | Versión del servidor fijada para `npx -y nan-mcp-server@<v>` (recomendación de supply-chain del propio proyecto) |
+| `NAN_MEDIA_MCP_COMMAND` | — | Comando personalizado completo, p. ej. `bunx nan-mcp-server@1.0.8` |
+
+#### Detección automatizada de actualizaciones
+
+Una nueva versión de `nan-mcp-server` no desviará silenciosamente el pin de esta conexión. El
+planificador (`.github/workflows/check-nan-mcp-server-update.yml`) ejecuta `bun run scripts/check-nan-mcp-server.ts`
+semanalmente y, cuando el registro npm muestra una versión más reciente, abre (o refresca) un único
+issue etiquetado `dependencies` que describe si el bump es **breaking** o **seguro**, más la lista de
+commits aguas arriba. Puedes ejecutarlo localmente en cualquier momento:
+
+```bash
+bun run check-nan-mcp-server            # informe legible
+bun run check-nan-mcp-server --json     # JSON para máquina
+bun run check-nan-mcp-server --issue    # crea/refresca el issue (requiere GITHUB_TOKEN)
+```
+
+La decisión se toma a partir de la *superficie de tools* en vivo (vía unpkg), no de docs obsoletos: si
+el último servidor sigue exponiendo todas las tools conectadas (`generate_image`, `edit_image`,
+`text_to_speech`, `list_voices`, `speech_to_text`), el bump se reporta como **no rompente**; si elimina
+o renombra alguna tool conectada, el issue se marca **breaking** para revisión manual antes de subir.
 | `NAN_MEDIA_MCP_TIMEOUT_MS` | `120000` | Timeout por llamada; el proceso se mata al expirar |
 | `NAN_MCP_TOOLS` | — | Override por sesión del puente oficial: `0`/`false`/`off` desactiva `nan_web_search`; sin definir → persistido/por defecto |
 

package/README.md

@@ -98,8 +98,27 @@ Environment variables:
 | Variable | Default | Meaning |
 |---|---|---|
 | `NAN_MEDIA_MCP` | — | Per-session override for the media bridge: any explicit value (incl. `0`) beats the `/nan-mcp` persisted toggle; unset → persisted/default |
-| `NAN_MEDIA_MCP_VERSION` | `1.0.7` | Pinned server version for `npx -y nan-mcp-server@<v>` (upstream's own supply-chain recommendation) |
-| `NAN_MEDIA_MCP_COMMAND` | — | Full custom command, e.g. `bunx nan-mcp-server@1.0.7` |
+| `NAN_MEDIA_MCP_VERSION` | `1.0.8` | Pinned server version for `npx -y nan-mcp-server@<v>` (upstream's own supply-chain recommendation) |
+| `NAN_MEDIA_MCP_COMMAND` | — | Full custom command, e.g. `bunx nan-mcp-server@1.0.8` |
+
+#### Automated update detection
+
+A newer `nan-mcp-server` release won't silently drift this bridge's pin. The scheduler
+(`.github/workflows/check-nan-mcp-server-update.yml`) runs `bun run scripts/check-nan-mcp-server.ts`
+weekly and, when the npm registry shows a newer version, opens (or refreshes) one
+`dependencies`-labelled issue describing whether the bump is **breaking** or **safe**, plus the
+upstream commit list. Run it locally any time:
+
+```bash
+bun run check-nan-mcp-server            # human-readable report
+bun run check-nan-mcp-server --json     # machine-readable JSON
+bun run check-nan-mcp-server --issue    # create/refresh the issue (needs GITHUB_TOKEN)
+```
+
+The decision is made from the *live* server tool surface (via unpkg), not from stale docs: if the
+latest server still exposes every bridged tool (`generate_image`, `edit_image`, `text_to_speech`,
+`list_voices`, `speech_to_text`), the bump is reported as **non-breaking**; if it drops or renames a
+bridged tool, the issue is flagged **breaking** for manual review before bumping.
 | `NAN_MEDIA_MCP_TIMEOUT_MS` | `120000` | Per-call timeout; the process is killed after it |
 | `NAN_MCP_TOOLS` | — | Per-session override for the official bridge: `0`/`false`/`off` disables `nan_web_search`; unset → persisted/default |
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gtrabanco/pi-nan-provider",
-	"version": "0.5.2",
+	"version": "0.6.1",
 	"description": "NaN Builders (api.nan.builders) model provider for pi - OpenAI-compatible registration with a models.dev-generated fallback, tier-aware live catalog, and MCP bridges (official web search + optional community media server)",
 	"keywords": [
 		"pi",
@@ -35,6 +35,7 @@
 	],
 	"scripts": {
 		"generate-models": "bun run scripts/generate-models.ts",
+		"check-nan-mcp-server": "bun run scripts/check-nan-mcp-server.ts",
 		"prepublishOnly": "bun run generate-models && bun test && bun run typecheck",
 		"test": "bun test",
 		"typecheck": "bunx tsc --noEmit"

package/scripts/check-nan-mcp-server.ts

@@ -0,0 +1,426 @@
+#!/usr/bin/env bun
+/**
+ * Detect whether an updated `nan-mcp-server` is available and, if so, decide
+ * whether it is safe to bump the pinned version this package bridges.
+ *
+ * This is the automated companion to the manual "should we update?" question
+ * for the community stdio MCP server (`nan-mcp-server`, the media bridge). It
+ * exists because pi implements NO MCP client — we bridge the server's tools as
+ * native pi tools, and the bridge is pinned to a version via
+ * `DEFAULT_NAN_MEDIA_MCP_VERSION`. When the upstream server ships a new
+ * version we want a signal, not a silent drift.
+ *
+ * What it checks (all live, no human guesswork):
+ *   1. Latest published `nan-mcp-server` version on the npm registry.
+ *   2. Whether the latest version is newer than the pinned version.
+ *   3. The *tool surface* of the latest server vs the tools we bridge: if the
+ *      latest server still exposes every bridged tool, the update is **safe**
+ *      (non-breaking) even if the implementation changed. If it dropped or
+ *      renamed a bridged tool, the bump is **breaking** and needs manual
+ *      review before proceeding — an agent check cannot auto-bump that.
+ *   4. The upstream commit list between the pinned and latest versions, so a
+ *      maintainer sees WHAT changed without re-deriving from stale docs.
+ *
+ * Output: a single structured `NanMcpServerCheckReport` (JSON). The script
+ * exits 0 when up-to-date or when the check cannot be completed (so a cron is
+ * quiet unless there is news), and it creates/updates a GitHub issue when an
+ * update is available and `GITHUB_TOKEN` is present.
+ *
+ * Usage:
+ *   bun run scripts/check-nan-mcp-server.ts            # report to stdout
+ *   bun run scripts/check-nan-mcp-server.ts --json     # machine-readable JSON
+ *   bun run scripts/check-nan-mcp-server.ts --issue    # create/update an issue (needs GITHUB_TOKEN)
+ *
+ * The pure decision logic (`parseVersion`, `compareVersions`, `extractServerTools`,
+ * `assessUpdate`, `buildReport`) is exported for unit tests so the whole verdict
+ * is verifiable without touching the network. The network fetchers accept an
+ * injected `fetch` so tests can stub the registry/unpkg/github sources.
+ *
+ * Exit codes: 0 always (a cron should be quiet unless a human acts). Use
+ * `--json` to consume the report and decide what to do with it.
+ */
+
+import {
+	DEFAULT_NAN_MEDIA_MCP_VERSION,
+	NAN_MEDIA_MCP_SERVER_TOOLS,
+} from "../src/mcp/nan-media.ts";
+
+/** npm package name of the community stdio MCP server we bridge. */
+export const NAN_MCP_SERVER_PACKAGE = "nan-mcp-server";
+/** npm registry endpoint for the package's latest release. */
+export const NAN_MCP_SERVER_REGISTRY_URL = "https://registry.npmjs.org/nan-mcp-server/latest";
+/** unpkg CDN path to the published server source, used to extract the tool surface. */
+export const NAN_MCP_SERVER_SOURCE_URL = (version: string) =>
+	`https://unpkg.com/nan-mcp-server@${version}/server.js`;
+/** GitHub compare API for the upstream commit list between two tags. */
+export const NAN_MCP_SERVER_COMPARE_URL = (from: string, to: string) =>
+	`https://api.github.com/repos/luciferfran/nan-mcp-server/compare/v${from.replace(/^v/, "")}...v${to.replace(/^v/, "")}`;
+
+/** GitHub search-issues endpoint used to dedupe the update issue. */
+const GITHUB_SEARCH_ISSUES_URL =
+	"https://api.github.com/search/issues?q=" +
+	"repo:gtrabanco/pi-nan-provider+is:issue+is:open+in:title" +
+	'+label:dependencies+type:issue+"nan-mcp-server update"';
+
+/** Label to attach to the auto-created update issue (dedupe key + visibility). */
+export const NAN_MCP_UPDATE_ISSUE_LABEL = "dependencies";
+/** Title template; the version pair is appended so each update is its own issue. */
+export const NAN_MCP_UPDATE_ISSUE_TITLE_PREFIX = "[auto] nan-mcp-server update available";
+
+export interface NanMcpServerCheckReport {
+	/** npm package scanned. */
+	package: string;
+	/** Version pinned in this package's bridge (source of truth: nan-media.ts). */
+	pinnedVersion: string;
+	/** Latest version published on npm; null when the registry could not be read. */
+	latestVersion: string | null;
+	/** true when latestVersion is strictly newer than pinnedVersion. */
+	updateAvailable: boolean;
+	/** How the verdict was reached: registry in reach, no drift, or an error. */
+	status: "up-to-date" | "update-available" | "check-failed";
+	/** true when a bridged tool is missing from the latest server surface. */
+	breaking: boolean;
+	/** Tools added by the latest server that we do NOT bridge (informational). */
+	addedTools: string[];
+	/** Bridged tools dropped/renamed by the latest server (breaking → manual). */
+	removedTools: string[];
+	/** Upstream commit subjects between pinned and latest (when reachable). */
+	changelog: string[];
+	/** Human-readable verdict sentence. */
+	reason: string;
+	/** When the check could not reach a source (registry/unpkg/github). */
+	error?: string;
+}
+
+/**
+ * Parse a semver-ish string (`1.0.8`, `v1.0.8`) into numeric major/minor/patch.
+ * Non-numeric release segments are clamped to 0 so `1.0.8` and `1.0.8-rc.1`
+ * compare sensibly; malformed input yields `[0, 0, 0]` (never throws).
+ */
+export function parseVersion(input: string): [number, number, number] {
+	const cleaned = String(input).trim().replace(/^v/, "").split(/[-+.]/);
+	const toNum = (segment: string | undefined) => {
+		const n = Number.parseInt(segment ?? "", 10);
+		return Number.isFinite(n) ? n : 0;
+	};
+	return [toNum(cleaned[0]), toNum(cleaned[1]), toNum(cleaned[2])];
+}
+
+/**
+ * Compare two version strings. Returns 1 when `a` is newer, -1 when older,
+ * 0 when equal. Comparable to a numeric semver compare for x.y.z inputs.
+ */
+export function compareVersions(a: string, b: string): number {
+	const [amaj, amin, apatch] = parseVersion(a);
+	const [bmaj, bmin, bpatch] = parseVersion(b);
+	if (amaj !== bmaj) return amaj > bmaj ? 1 : -1;
+	if (amin !== bmin) return amin > bmin ? 1 : -1;
+	if (apatch !== bpatch) return apatch > bpatch ? 1 : -1;
+	return 0;
+}
+
+/** Extract every `registerTool("NAME")` from a server.js source string. */
+export function extractServerTools(source: string): string[] {
+	const names = new Set<string>();
+	const re = /registerTool\(\s*["']([^"']+)["']/g;
+	let match: RegExpExecArray | null;
+	while ((match = re.exec(source)) !== null) {
+		names.add(match[1]!);
+	}
+	return [...names].sort();
+}
+
+/**
+ * Compare the latest server tool surface against the bridged tools and decide
+ * whether the update is safe to bump. The only hard break is a bridged tool
+ * disappearing (dropped or renamed); anything else — new tools, bug fixes,
+ * schema tightening (e.g. `edit_image` now rejects >4 images) — is safe for
+ * our bridge, because we forward the params the schema already documents.
+ */
+export function assessUpdate(latestTools: string[]): {
+	breaking: boolean;
+	addedTools: string[];
+	removedTools: string[];
+	reason: string;
+} {
+	const bridged: readonly string[] = [...NAN_MEDIA_MCP_SERVER_TOOLS];
+	const latest = new Set(latestTools.map((t) => t.trim()));
+
+	const removedTools = bridged.filter((tool) => !latest.has(tool));
+	const addedTools = latestTools.filter((tool) => !bridged.includes(tool));
+
+	const breaking = removedTools.length > 0;
+
+	let reason: string;
+	if (breaking) {
+		reason =
+			`BREAKING: the latest nan-mcp-server no longer exposes ${removedTools.join(", ")}. ` +
+			"Bumping the pin would break the bridged tool(s) — manual review required before deciding.";
+	} else if (addedTools.length > 0) {
+		reason = `Safe to bump (non-breaking): every bridged tool is still present. New upstream tool(s) ${addedTools.join(", ")} are NOT bridged by this package (optional future work).`;
+	} else {
+		reason = "Safe to bump (non-breaking): every bridged tool is still present, and no new upstream tools were added.";
+	}
+
+	return { breaking, addedTools, removedTools, reason };
+}
+
+/**
+ * Build the full report from already-fetched data. Pure — no network. Missing
+ * or stale inputs degrade to `check-failed`, and an update is only reported
+ * when the latest version is strictly newer than the pinned one.
+ */
+export function buildReport(input: {
+	pinnedVersion: string;
+	latestVersion: string | null;
+	latestTools: string[];
+	changelog: string[];
+	error?: string;
+}): NanMcpServerCheckReport {
+	const { pinnedVersion, latestVersion, latestTools, changelog, error } = input;
+
+	if (error) {
+		return {
+			package: NAN_MCP_SERVER_PACKAGE,
+			pinnedVersion,
+			latestVersion: null,
+			updateAvailable: false,
+			status: "check-failed",
+			breaking: false,
+			addedTools: [],
+			removedTools: [],
+			changelog: [],
+			reason: `Could not complete the check: ${error}`,
+			error,
+		};
+	}
+
+	if (latestVersion === null) {
+		return {
+			package: NAN_MCP_SERVER_PACKAGE,
+			pinnedVersion,
+			latestVersion: null,
+			updateAvailable: false,
+			status: "check-failed",
+			breaking: false,
+			addedTools: [],
+			removedTools: [],
+			changelog: [],
+			reason: "Could not read the npm registry for the latest version.",
+			error: "registry-unreachable",
+		};
+	}
+
+	const updateAvailable = compareVersions(latestVersion, pinnedVersion) > 0;
+	if (!updateAvailable) {
+		return {
+			package: NAN_MCP_SERVER_PACKAGE,
+			pinnedVersion,
+			latestVersion,
+			updateAvailable: false,
+			status: "up-to-date",
+			breaking: false,
+			addedTools: [],
+			removedTools: [],
+			changelog: [],
+			reason: `Up to date: pinned ${pinnedVersion} is not older than latest ${latestVersion}.`,
+		};
+	}
+
+	const verdict = assessUpdate(latestTools);
+	return {
+		package: NAN_MCP_SERVER_PACKAGE,
+		pinnedVersion,
+		latestVersion,
+		updateAvailable: true,
+		status: "update-available",
+		breaking: verdict.breaking,
+		addedTools: verdict.addedTools,
+		removedTools: verdict.removedTools,
+		changelog,
+		reason: verdict.reason,
+	};
+}
+
+/** A minimal fetch-compatible signature so tests can stub it without undici types. */
+export type FetchLike = (url: string, init?: { headers?: Record<string, string> }) => Promise<Response>;
+
+async function readJson<T>(url: string, fetchImpl: FetchLike, headers?: Record<string, string>): Promise<T> {
+	const res = await fetchImpl(url, { headers });
+	if (!res.ok) {
+		throw new Error(`HTTP ${res.status} from ${url}`);
+	}
+	return (await res.json()) as T;
+}
+
+/** Fetch the latest published version of the package from the npm registry. */
+export async function fetchLatestVersion(fetchImpl: FetchLike = fetch): Promise<string> {
+	const data = await readJson<{ version?: string; "dist-tags"?: { latest?: string } }>(
+		NAN_MCP_SERVER_REGISTRY_URL,
+		fetchImpl,
+	);
+	const version = data["dist-tags"]?.latest ?? data.version;
+	if (!version) throw new Error("npm registry response had no version");
+	return version;
+}
+
+/** Fetch the published server.js source and extract its tool surface. */
+export async function fetchServerTools(
+	version: string,
+	fetchImpl: FetchLike = fetch,
+): Promise<string[]> {
+	const res = await fetchImpl(NAN_MCP_SERVER_SOURCE_URL(version));
+	if (!res.ok) throw new Error(`HTTP ${res.status} from ${NAN_MCP_SERVER_SOURCE_URL(version)}`);
+	return extractServerTools(await res.text());
+}
+
+/** Fetch upstream commit subjects between two tags (best-effort; empty on failure). */
+export async function fetchChangelog(
+	from: string,
+	to: string,
+	fetchImpl: FetchLike = fetch,
+): Promise<string[]> {
+	try {
+		const data = await readJson<{ commits?: Array<{ commit?: { message?: string } }> }>(
+			NAN_MCP_SERVER_COMPARE_URL(from, to),
+			fetchImpl,
+		);
+		return (data.commits ?? [])
+			.map((c) => c.commit?.message?.split("\n")[0]?.trim() ?? "")
+			.filter(Boolean);
+	} catch {
+		return [];
+	}
+}
+
+const ARGS = process.argv.slice(2);
+/** Rendered issue body from a report — what a maintainer reads to decide. */
+export function renderIssueBody(report: NanMcpServerCheckReport): string {
+	const lines: string[] = [];
+	lines.push(`**Package**: \`${report.package}\``);
+	lines.push(`**Pinned by this package**: \`${report.pinnedVersion}\``);
+	lines.push(`**Latest on npm**: \`${report.latestVersion ?? "unknown"}\``);
+	lines.push(`**Verdict**: ${report.breaking ? "⚠️ BREAKING — manual review required" : "✅ Safe to bump (non-breaking)"}`);
+	lines.push("");
+	lines.push(`> ${report.reason}`);
+	lines.push("");
+	if (report.changelog.length > 0) {
+		lines.push("### Upstream changes");
+		lines.push("", ...report.changelog.map((c) => `- ${c}`), "");
+	}
+	lines.push("### To bump");
+	lines.push(
+		`1. Edit \`DEFAULT_NAN_MEDIA_MCP_VERSION\` in \`src/mcp/nan-media.ts\` from \`${report.pinnedVersion}\` to \`${report.latestVersion}\`.`,
+	);
+	lines.push("2. Run \`bun test && bun run typecheck\`.");
+	lines.push(
+		report.breaking
+			? "3. Investigate the removed tool(s) — decide whether to bridge an alternative or keep the older pin."
+			: "3. Commit the bump and close this issue (it was auto-created).",
+	);
+	return lines.join("\n");
+}
+
+/** GitHub API root for this repository's issues. */
+export const NAN_MCP_REPO_ISSUES_URL = "https://api.github.com/repos/gtrabanco/pi-nan-provider/issues";
+
+async function sendIssueRequest<T>(
+	url: string,
+	method: string,
+	body: object | undefined,
+	token: string,
+): Promise<T> {
+	const res = await fetch(url, {
+		method,
+		headers: {
+			Authorization: `Bearer ${token}`,
+			Accept: "application/vnd.github+json",
+			...(body ? { "Content-Type": "application/json" } : {}),
+		},
+		...(body ? { body: JSON.stringify(body) } : {}),
+	});
+	if (!res.ok) throw new Error(`GitHub API ${method} ${url} → HTTP ${res.status}`);
+	return (await res.json()) as T;
+}
+
+/**
+ * Create a pre-engineered update issue, or refresh an existing open one with
+ * the same title+label instead of stacking duplicates across cron runs.
+ * Returns the issue URL (web or API) so the caller can surface it.
+ */
+export async function createOrUpdateIssue(
+	report: NanMcpServerCheckReport,
+	token: string,
+): Promise<string> {
+	const title = `${NAN_MCP_UPDATE_ISSUE_TITLE_PREFIX}: ${report.pinnedVersion} → ${report.latestVersion ?? "?"}`;
+	const body = renderIssueBody(report);
+
+	// Dedupe key: an OPEN issue whose title matches AND carries the label.
+	const searchUrl = `${GITHUB_SEARCH_ISSUES_URL}+${encodeURIComponent(`"${title}"`)}`;
+	const search = await sendIssueRequest<{ items?: Array<{ number: number; html_url: string }> }>(
+		searchUrl,
+		"GET",
+		undefined,
+		token,
+	);
+	const existing = search.items?.[0];
+	if (existing) {
+		const patchUrl = `${NAN_MCP_REPO_ISSUES_URL}/${existing.number}`;
+		await sendIssueRequest(patchUrl, "PATCH", { body }, token);
+		return existing.html_url;
+	}
+
+	const created = await sendIssueRequest<{ html_url: string }>(
+		NAN_MCP_REPO_ISSUES_URL,
+		"POST",
+		{ title, body, labels: [NAN_MCP_UPDATE_ISSUE_LABEL] },
+		token,
+	);
+	return created.html_url;
+}
+
+/** Main entry point. */
+async function main(): Promise<void> {
+	let report: NanMcpServerCheckReport;
+	try {
+		const pinnedVersion = DEFAULT_NAN_MEDIA_MCP_VERSION;
+		const latestVersion = await fetchLatestVersion();
+		let latestTools: string[] = [];
+		let changelog: string[] = [];
+		if (compareVersions(latestVersion, pinnedVersion) > 0) {
+			latestTools = await fetchServerTools(latestVersion).catch(() => []);
+			changelog = await fetchChangelog(pinnedVersion, latestVersion);
+		}
+		report = buildReport({ pinnedVersion, latestVersion, latestTools, changelog });
+	} catch (error) {
+		report = buildReport({
+			pinnedVersion: DEFAULT_NAN_MEDIA_MCP_VERSION,
+			latestVersion: null,
+			latestTools: [],
+			changelog: [],
+			error: error instanceof Error ? error.message : String(error),
+		});
+	}
+
+	if (ARGS.includes("--json")) {
+		console.log(JSON.stringify(report, null, 2));
+	} else {
+		console.log(`nan-mcp-server: pinned ${report.pinnedVersion}, latest ${report.latestVersion ?? "unknown"}`);
+		console.log(`  status: ${report.status}  breaking: ${report.breaking}`);
+		console.log(`  ${report.reason}`);
+		if (report.changelog.length > 0) {
+			console.log("  upstream:");
+			for (const c of report.changelog) console.log(`    - ${c}`);
+		}
+	}
+
+	const token = process.env.GITHUB_TOKEN;
+	if (ARGS.includes("--issue") && report.status === "update-available" && token) {
+		const url = await createOrUpdateIssue(report, token);
+		console.log(`  issue: ${url}`);
+	} else if (ARGS.includes("--issue") && report.status === "update-available" && !token) {
+		console.log("  --issue requested but GITHUB_TOKEN is not set; issue NOT created.");
+	}
+}
+
+await main();

package/scripts/models.generated.ts

@@ -1,7 +1,7 @@
 // This file is auto-generated by scripts/generate-models.ts
 // Do not edit manually — run `bun run generate-models` to update.
 //
-// Source: https://models.dev/api.json (provider "nan"), fetched 2026-09-07T12:31:36.901Z
+// Source: https://models.dev/api.json (provider "nan"), fetched 2026-09-08T22:49:12.806Z
 // Provenance: every contextWindow/maxTokens/input/cost value traces to
 // models.dev or to the per-entry notes below. Nothing is invented; entries
 // models.dev documents incompletely are omitted and flagged instead.
@@ -180,7 +180,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 					"text"
 				]
 			},
-			"open_weights": false,
+			"open_weights": true,
 			"limit": {
 				"context": 1000000,
 				"output": 131072
@@ -375,7 +375,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 export const GENERATED_CATALOG_META = {
 	source: "https://models.dev/api.json",
 	modelsDevProvider: "nan",
-	fetchedAt: "2026-09-07T12:31:36.901Z",
+	fetchedAt: "2026-09-08T22:49:12.806Z",
 	modelCount: 6,
 	models: ["deepseek-v4-flash","gemma4","glm5.3-flash","mimo-v2.5","qwen3.6","qwen3.8-flash"],
 	notes: [

package/src/fetch-models.ts

@@ -12,12 +12,16 @@
  *     only model `id`s — no capability fields. It is used solely to confirm
  *     which model IDs are currently live.
  *
- * Merge: live IDs × generated capability data. A live ID with no generated
- * match is kept with conservative placeholder limits (the same defaults used
- * in custom-provider.md's dynamic-discovery example) and no reasoning
- * support — capabilities stay "unknown", nothing is fabricated. On fetch
- * failure, timeout, or an unusable response, callers fall back to the
- * generated catalog so startup is never blocked.
+ * Merge: live IDs × generated capability data — an allowlist, not an open
+ * ingest. Only allowlisted IDs surface: a live ID with generated data keeps
+ * its generated capabilities, and an allowlisted uncatalogued ID (premium
+ * live-only) gets conservative placeholder limits (the same defaults used in
+ * custom-provider.md's dynamic-discovery example) with no reasoning support -
+ * capabilities stay "unknown", nothing is fabricated. Every other live ID is
+ * dropped so undocumented models (and any model NaN starts serving later)
+ * and non-chat endpoints never surface. On fetch failure, timeout, or an
+ * unusable response, callers fall back to the generated catalog so startup
+ * is never blocked.
  */
 
 import type { Model, OpenAICompletionsCompat } from "@earendil-works/pi-ai";
@@ -60,6 +64,28 @@ export const NAN_COMPAT_API = "openai-completions" as const;
  */
 export const UNKNOWN_MODEL_LIMITS = { contextWindow: 128_000, maxTokens: 4_096 } as const;
 
+/**
+ * The allowlist of model ids this package may surface. Everything a live
+ * /models response returns that is NOT here is dropped — so models that are
+ * undocumented (and might become available later, e.g. one NaN starts
+ * serving after a release) can never leak through the package.
+ *
+ * Every current chat model is listed: the six models.dev-documented entries
+ * plus the premium live-only glm5.3 (which NaN serves via /models but that
+ * models.dev omits — see the "unemittable" note in scripts/generate-models.ts).
+ * Non-chat endpoints (flux-2-klein, kokoro, whisper, qwen3-embedding, rerank)
+ * are deliberately excluded: they are MCP-bridge territory, not chat models.
+ */
+const ALLOWED_MODEL_IDS = [
+	"deepseek-v4-flash",
+	"gemma4",
+	"glm5.3-flash",
+	"glm5.3",
+	"mimo-v2.5",
+	"qwen3.6",
+	"qwen3.8-flash",
+] as const;
+
 /** Timeout for the live /models fetch; matches the pi-synthetic-provider precedent (~3s). */
 export const DEFAULT_MODELS_TIMEOUT_MS = 3_000;
 
@@ -87,9 +113,10 @@ export function toModel(entry: GeneratedModelEntry, source: CatalogSource): Mode
 	};
 }
 
-/** The generated fallback catalog as pi-ai Models for the given provider. */
+/** The generated fallback catalog as pi-ai Models for the given provider (allowlisted entries only). */
 export function baselineModels(source: CatalogSource): Model<"openai-completions">[] {
-	return NAN_GENERATED_MODELS.map((entry) => toModel(entry, source));
+	const allowed = new Set<string>(ALLOWED_MODEL_IDS);
+	return NAN_GENERATED_MODELS.filter((entry) => allowed.has(entry.id)).map((entry) => toModel(entry, source));
 }
 
 export interface LiveModelListOptions {
@@ -142,15 +169,17 @@ export interface MergedCatalog {
 	models: Model<"openai-completions">[];
 	/** Live IDs resolved against generated capability data. */
 	matched: string[];
-	/** Live IDs kept with unknown capabilities (conservative limits). */
+	/** Allowlisted live IDs kept with unknown capabilities (conservative limits). */
 	unknown: string[];
 }
 
 /**
- * Merge live model IDs with the generated capability catalog.
- * Known IDs get generated data; unknown IDs get conservative placeholder
- * limits, `reasoning: false`, and zero cost — documented defaults, not
- * invented capabilities.
+ * Merge live model IDs with the generated capability catalog, gated by the
+ * allowlist. Only allowlisted IDs surface: live IDs with generated data keep
+ * their generated capabilities; allowlisted uncatalogued IDs (glm5.3) get
+ * conservative placeholder limits, `reasoning: false`, and zero cost
+ * (documented defaults, not invented capabilities). Every non-allowlisted
+ * live ID is dropped.
  */
 export function mergeLiveWithGenerated(
 	liveIds: readonly string[],
@@ -158,11 +187,13 @@ export function mergeLiveWithGenerated(
 	generated: readonly GeneratedModelEntry[] = NAN_GENERATED_MODELS,
 ): MergedCatalog {
 	const byId = new Map(generated.map((entry) => [entry.id, entry]));
+	const allowed = new Set<string>(ALLOWED_MODEL_IDS);
 	const models: Model<"openai-completions">[] = [];
 	const matched: string[] = [];
 	const unknown: string[] = [];
 
 	for (const id of liveIds) {
+		if (!allowed.has(id)) continue;
 		const entry = byId.get(id);
 		if (entry) {
 			models.push(toModel(entry, source));
@@ -205,7 +236,7 @@ export interface ResolvedCatalog {
 	 * when the live fetch failed and the generated fallback was used.
 	 */
 	liveIds: Set<string> | undefined;
-	/** Live IDs kept with unknown capabilities (present only when liveIds is set). */
+	/** Allowlisted live IDs kept with unknown capabilities (present only when liveIds is set). */
 	unknownIds: string[];
 }
 

package/src/mcp/nan-media.ts

@@ -14,8 +14,8 @@
  *   other env vars inherit from your environment (generated files land in
  *   ~/nan-mcp-output/ by default).
  * - Version pinning follows the upstream server's own supply-chain guidance:
- *   NAN_MEDIA_MCP_VERSION (default "1.0.7"), or pass a custom command with
- *   NAN_MEDIA_MCP_COMMAND (space-separated, e.g. "bunx nan-mcp-server@1.0.7").
+ *   NAN_MEDIA_MCP_VERSION (default "1.0.8"), or pass a custom command with
+ *   NAN_MEDIA_MCP_COMMAND (space-separated, e.g. "bunx nan-mcp-server@1.0.8").
  */
 
 import { Type, type TSchema } from "@earendil-works/pi-ai";
@@ -28,7 +28,21 @@ export const NAN_MEDIA_MCP_ENV = "NAN_MEDIA_MCP";
 export const NAN_MEDIA_MCP_VERSION_ENV = "NAN_MEDIA_MCP_VERSION";
 export const NAN_MEDIA_MCP_COMMAND_ENV = "NAN_MEDIA_MCP_COMMAND";
 export const NAN_MEDIA_MCP_TIMEOUT_ENV = "NAN_MEDIA_MCP_TIMEOUT_MS";
-export const DEFAULT_NAN_MEDIA_MCP_VERSION = "1.0.7";
+export const DEFAULT_NAN_MEDIA_MCP_VERSION = "1.0.8";
+
+/**
+ * The MCP tool names on the stdio nan-mcp-server that this package bridges as
+ * pi tools. Kept as the single source of truth for the check script
+ * (scripts/check-nan-mcp-server.ts) and to type each spec's `mcpTool` so the
+ * bridge cannot drift from the set it claims to expose.
+ */
+export const NAN_MEDIA_MCP_SERVER_TOOLS = [
+	"generate_image",
+	"edit_image",
+	"text_to_speech",
+	"list_voices",
+	"speech_to_text",
+] as const;
 export const DEFAULT_MEDIA_MCP_TIMEOUT_MS = 120_000;
 
 /** Media tools bridged from the stdio MCP server (audio/image/transcription scope). */
@@ -84,7 +98,7 @@ function mediaMcpTimeoutMs(): number {
 
 interface MediaToolSpec<TParams extends TSchema = TSchema> {
 	name: (typeof NAN_MEDIA_TOOLS)[number];
-	mcpTool: string;
+	mcpTool: (typeof NAN_MEDIA_MCP_SERVER_TOOLS)[number];
 	label: string;
 	description: string;
 	promptSnippet: string;
@@ -129,7 +143,7 @@ function defineMediaTool<TParams extends TSchema>(spec: MediaToolSpec<TParams>):
 /**
  * Build the media tool set. Registered only when NAN_MEDIA_MCP=1 and the
  * runtime supports registerTool; execution spawns the MCP server per call.
- * Schemas mirror nan-mcp-server's zod input schemas (v1.0.7).
+ * Schemas mirror nan-mcp-server's zod input schemas (v1.0.8).
  */
 export function createNanMediaTools(): ToolDefinition[] {
 	return [
@@ -160,6 +174,8 @@ export function createNanMediaTools(): ToolDefinition[] {
 				prompt: Type.String({ description: "Description of the edit or transformation to apply" }),
 				images: Type.Array(Type.String(), {
 					description: "Absolute paths to reference image files (PNG, JPEG, WebP; up to 4, each < 25MB)",
+					minItems: 1,
+					maxItems: 4,
 				}),
 				size: sizeProperty(),
 				n: Type.Optional(Type.Integer({ description: "Number of images to generate (1-4). Default 1", minimum: 1, maximum: 4 })),

package/src/mcp/stdio-client.ts

@@ -18,7 +18,7 @@ const PROTOCOL_VERSION = "2024-11-05";
 const CLIENT_INFO = { name: "pi-nan-provider", version: "0.2.0" };
 
 export interface StdioMcpCallOptions {
-	/** Command to spawn, e.g. ["npx", "-y", "nan-mcp-server@1.0.7"]. */
+	/** Command to spawn, e.g. ["npx", "-y", "nan-mcp-server@1.0.8"]. */
 	command: readonly string[];
 	/** Extra environment for the child (merged over process.env). */
 	env?: Record<string, string | undefined>;