pi-free 2.0.14 → 2.1.0

package/lib/logger.ts

@@ -8,8 +8,9 @@
  * - Disable file logging: PI_FREE_FILE_LOG=false
  */
 
-import { appendFileSync, existsSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { ensureDir, resolveSafeDataFile } from "./paths.ts";
 
 export type LogLevel = "debug" | "info" | "warn" | "error";
 
@@ -29,10 +30,23 @@ const LOG_LEVELS: Record<LogLevel, number> = {
 };
 
 // Console default: error-only. Set LOG_LEVEL=debug or LOG_LEVEL=info to see more.
-const currentLevel: LogLevel = (process.env.LOG_LEVEL as LogLevel) || "error";
 // File default: debug (so we can inspect full behavior in ~/.pi/free.log).
-const fileLevel: LogLevel =
-	(process.env.PI_FREE_LOG_LEVEL as LogLevel) || "debug";
+const VALID_LEVELS = new Set<LogLevel>(["debug", "info", "warn", "error"]);
+
+function parseLogLevel(
+	envValue: string | undefined,
+	defaultLevel: LogLevel,
+): LogLevel {
+	if (!envValue) return defaultLevel;
+	const normalized = envValue.toLowerCase() as LogLevel;
+	return VALID_LEVELS.has(normalized) ? normalized : defaultLevel;
+}
+
+const currentLevel: LogLevel = parseLogLevel(process.env.LOG_LEVEL, "error");
+const fileLevel: LogLevel = parseLogLevel(
+	process.env.PI_FREE_LOG_LEVEL,
+	"debug",
+);
 
 function shouldLog(level: LogLevel, minLevel: LogLevel): boolean {
 	return LOG_LEVELS[level] >= LOG_LEVELS[minLevel];
@@ -50,18 +64,13 @@ function formatMessage(entry: LogEntry): string {
 	return `[${entry.timestamp}] [${entry.level.toUpperCase()}] [${entry.namespace}] ${entry.message}${data}`;
 }
 
-const HOME_DIR = process.env.HOME || process.env.USERPROFILE || "";
-const DEFAULT_LOG_PATH = join(HOME_DIR, ".pi", "free.log");
-const LOG_PATH = process.env.PI_FREE_LOG_PATH || DEFAULT_LOG_PATH;
+const LOG_PATH = resolveSafeDataFile(process.env.PI_FREE_LOG_PATH, "free.log");
 const FILE_LOG_ENABLED = process.env.PI_FREE_FILE_LOG !== "false";
 
 function appendToFile(line: string): void {
 	if (!FILE_LOG_ENABLED) return;
 	try {
-		const dir = dirname(LOG_PATH);
-		if (!existsSync(dir)) {
-			mkdirSync(dir, { recursive: true });
-		}
+		ensureDir(join(LOG_PATH, ".."));
 		appendFileSync(LOG_PATH, `${line}\n`, "utf8");
 	} catch (err) {
 		console.error("Failed to write to log file:", err);

package/lib/model-detection.ts

@@ -22,16 +22,6 @@ export interface ModelFamily {
 	models: ModelInfo[]; // All models in this family
 }
 
-/**
- * Check if a model is free (zero input and output cost)
- */
-export function isModelFree(model: {
-	cost?: { input: number; output: number };
-}): boolean {
-	if (!model.cost) return true;
-	return model.cost.input === 0 && model.cost.output === 0;
-}
-
 /**
  * Convert Pi's Model type to ModelInfo for internal use
  */
@@ -40,7 +30,7 @@ export function toModelInfo(model: Model<any>): ModelInfo {
 		id: model.id,
 		name: model.name,
 		provider: model.provider,
-		isFree: isModelFree(model),
+		isFree: !model.cost || (model.cost.input === 0 && model.cost.output === 0),
 		inputCost: model.cost?.input ?? 0,
 		outputCost: model.cost?.output ?? 0,
 	};
@@ -54,7 +44,7 @@ export function toProviderModelInfo(model: ProviderModelConfig): ModelInfo {
 		id: model.id,
 		name: model.name,
 		provider: "", // Will be set by caller
-		isFree: isModelFree(model),
+		isFree: !model.cost || (model.cost.input === 0 && model.cost.output === 0),
 		inputCost: model.cost?.input ?? 0,
 		outputCost: model.cost?.output ?? 0,
 	};

package/lib/model-enhancer.ts

@@ -6,15 +6,24 @@
 import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
 import { enhanceModelNameWithCodingIndex } from "../provider-failover/benchmark-lookup.ts";
 
+interface ModelsDevEnrichedMetadata {
+	modelsDev?: Parameters<typeof enhanceModelNameWithCodingIndex>[3];
+}
+
 /**
  * Enhance model names with Coding Index scores
  * Use this before registering providers to show CI in /model list
  */
 export function enhanceModelsWithCodingIndex(
-	models: ProviderModelConfig[],
+	models: Array<ProviderModelConfig & ModelsDevEnrichedMetadata>,
 ): ProviderModelConfig[] {
 	return models.map((m) => ({
 		...m,
-		name: enhanceModelNameWithCodingIndex(m.name, m.id),
+		name: enhanceModelNameWithCodingIndex(
+			m.name,
+			m.id,
+			undefined,
+			m.modelsDev,
+		),
 	}));
 }

package/lib/model-metadata.ts

@@ -0,0 +1,387 @@
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_FETCH_TIMEOUT_MS, URL_MODELS_DEV } from "../constants.ts";
+import { createLogger } from "./logger.ts";
+import { getProxyModelCompat } from "./provider-compat.ts";
+import type {
+	CostConfig,
+	ModelIdentity,
+	ModelMatchHints,
+	ModelsDevEnrichedMetadata,
+	ModelsDevModel,
+	ModelsDevProvider,
+} from "./types.ts";
+
+const DEFAULT_CONTEXT_WINDOW = 128_000;
+const DEFAULT_MAX_TOKENS = 16_384;
+const MODELS_DEV_CACHE_TTL_MS = 5 * 60 * 1000;
+const MODELS_DEV_RETRIES = 3;
+const MODELS_DEV_RETRY_DELAY_MS = 250;
+const MODELS_DEV_PROVIDER_ALIASES: Record<string, string> = {
+	together: "togetherai",
+	novita: "novita-ai",
+};
+
+const _logger = createLogger("model-metadata");
+
+type ThinkingLevelMap = NonNullable<ProviderModelConfig["thinkingLevelMap"]>;
+type ModelCompat = NonNullable<ProviderModelConfig["compat"]>;
+
+let catalogCache:
+	| {
+			expiresAt: number;
+			promise: Promise<Record<string, ModelsDevProvider>>;
+	  }
+	| undefined;
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function clearModelsDevMetaCache(): void {
+	catalogCache = undefined;
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+async function fetchModelsDevCatalog(): Promise<Record<string, ModelsDevProvider>> {
+	let lastError: unknown;
+
+	for (let attempt = 1; attempt <= MODELS_DEV_RETRIES; attempt++) {
+		try {
+			const response = await fetch(URL_MODELS_DEV, {
+				headers: { "User-Agent": "pi-free-providers" },
+				signal: AbortSignal.timeout(DEFAULT_FETCH_TIMEOUT_MS),
+			});
+			if (response.ok) {
+				return (await response.json()) as Record<string, ModelsDevProvider>;
+			}
+
+			lastError = new Error(
+				`HTTP ${response.status} ${response.statusText}`.trim(),
+			);
+		} catch (error) {
+			lastError = error;
+		}
+
+		if (attempt < MODELS_DEV_RETRIES) {
+			await sleep(MODELS_DEV_RETRY_DELAY_MS);
+		}
+	}
+
+	_logger.warn("Failed to fetch models.dev metadata", {
+		error: errorMessage(lastError),
+	});
+	return {};
+}
+
+function getModelsDevCatalog(): Promise<Record<string, ModelsDevProvider>> {
+	const now = Date.now();
+	if (catalogCache && catalogCache.expiresAt > now) {
+		return catalogCache.promise;
+	}
+
+	const promise = fetchModelsDevCatalog().catch((error) => {
+		catalogCache = undefined;
+		_logger.warn("Failed to load models.dev metadata", {
+			error: errorMessage(error),
+		});
+		return {};
+	});
+	catalogCache = {
+		expiresAt: now + MODELS_DEV_CACHE_TTL_MS,
+		promise,
+	};
+	return promise;
+}
+
+function collectAllModels(
+	catalog: Record<string, ModelsDevProvider>,
+): Record<string, ModelsDevModel> {
+	const allModels: Record<string, ModelsDevModel> = {};
+	for (const [providerKey, provider] of Object.entries(catalog)) {
+		for (const [modelId, model] of Object.entries(provider.models ?? {})) {
+			allModels[`${provider.id ?? providerKey}/${modelId}`] = model;
+		}
+	}
+	return allModels;
+}
+
+function hasModels(
+	models: Record<string, ModelsDevModel> | undefined,
+): models is Record<string, ModelsDevModel> {
+	return models !== undefined && Object.keys(models).length > 0;
+}
+
+function findProviderModels(
+	catalog: Record<string, ModelsDevProvider>,
+	providerId: string,
+): Record<string, ModelsDevModel> | undefined {
+	const ids = new Set(
+		[providerId, MODELS_DEV_PROVIDER_ALIASES[providerId]].filter(
+			(id): id is string => Boolean(id),
+		),
+	);
+
+	for (const id of ids) {
+		const directModels = catalog[id]?.models;
+		if (hasModels(directModels)) return directModels;
+	}
+
+	for (const provider of Object.values(catalog)) {
+		if (provider?.id && ids.has(provider.id) && hasModels(provider.models)) {
+			return provider.models;
+		}
+	}
+
+	return undefined;
+}
+
+export async function fetchModelsDevMeta(
+	providerId?: string,
+): Promise<Record<string, ModelsDevModel>> {
+	const catalog = await getModelsDevCatalog();
+	if (providerId) {
+		const scopedModels = findProviderModels(catalog, providerId);
+		if (scopedModels) return scopedModels;
+	}
+
+	return collectAllModels(catalog);
+}
+
+function normalizeModelKey(id: string): string {
+	return id
+		.toLowerCase()
+		.replace(/^~/, "")
+		.replace(/:free$/, "")
+		.replace(/-free$/, "");
+}
+
+function buildModelMetaIndex(
+	meta: Record<string, ModelsDevModel>,
+): Map<string, ModelsDevModel> {
+	const index = new Map<string, ModelsDevModel>();
+	for (const [key, model] of Object.entries(meta)) {
+		for (const value of [key, model.id, key.split("/").pop()]) {
+			if (value) index.set(normalizeModelKey(value), model);
+		}
+	}
+	return index;
+}
+
+function findModelDevMeta(
+	index: Map<string, ModelsDevModel>,
+	modelId: string,
+): ModelsDevModel | undefined {
+	const id = normalizeModelKey(modelId);
+	return index.get(id) ?? index.get(id.split("/").pop() ?? id);
+}
+
+function isTextOnly(input: ProviderModelConfig["input"]): boolean {
+	return input.length === 1 && input[0] === "text";
+}
+
+function costLooksLikeFallback(cost: CostConfig): boolean {
+	return (
+		cost.input === 0 &&
+		cost.output === 0 &&
+		cost.cacheRead === 0 &&
+		cost.cacheWrite === 0
+	);
+}
+
+function costFromModelsDev(
+	cost: ModelsDevModel["cost"],
+): CostConfig | undefined {
+	if (!cost) return undefined;
+	return {
+		input: cost.input / 1_000_000,
+		output: cost.output / 1_000_000,
+		cacheRead: (cost.cache_read ?? 0) / 1_000_000,
+		cacheWrite: (cost.cache_write ?? 0) / 1_000_000,
+	};
+}
+
+function thinkingMapFromReasoningOptions(
+	options: ModelsDevModel["reasoning_options"],
+): ThinkingLevelMap | undefined {
+	const effort = options?.find((option) => option.type === "effort");
+	if (!effort?.values?.length) return undefined;
+
+	const values = new Set(effort.values);
+	return {
+		off: values.has("none") ? "none" : null,
+		minimal: values.has("minimal") ? "minimal" : null,
+		low: values.has("low") ? "low" : null,
+		medium: values.has("medium") ? "medium" : null,
+		high: values.has("high") ? "high" : null,
+		xhigh: values.has("xhigh") ? "xhigh" : values.has("max") ? "max" : null,
+	};
+}
+
+function identityFromMeta(
+	model: ProviderModelConfig,
+	meta: ModelsDevModel,
+): ModelIdentity {
+	return {
+		id: [model.id, meta.id, meta.family, meta.provider]
+			.filter(Boolean)
+			.join(" "),
+		name: [model.name, meta.name].filter(Boolean).join(" "),
+		family: meta.family,
+		provider: meta.provider,
+	};
+}
+
+function mergeCompat(
+	existing: ProviderModelConfig["compat"],
+	derived: ProviderModelConfig["compat"],
+): ProviderModelConfig["compat"] | undefined {
+	if (!existing) return derived;
+	if (!derived) return existing;
+	return { ...(derived as ModelCompat), ...(existing as ModelCompat) };
+}
+
+export interface ModelsDevEnrichmentOptions {
+	/** Provider id to scope models.dev lookup. Omit to search all providers. */
+	providerId?: string;
+	/** Values treated as provider defaults and safe to replace from models.dev. */
+	fallbackContextWindows?: number[];
+	fallbackMaxTokens?: number[];
+	/** Fill image modality when the provider exposed text-only fallback. */
+	enrichInput?: boolean;
+	/** Fill reasoning flag and effort map from models.dev. */
+	enrichReasoning?: boolean;
+	/** Fill cost only when explicitly enabled and current cost is all-zero fallback. */
+	enrichCost?: "never" | "fallback-only";
+	/** Add model/family compat without overwriting existing compat keys. */
+	enrichCompat?: boolean;
+}
+
+interface EnrichmentContext {
+	index: Map<string, ModelsDevModel>;
+	fallbackContextWindows: Set<number>;
+	fallbackMaxTokens: Set<number>;
+	enrichInput: boolean;
+	enrichReasoning: boolean;
+	enrichCost: "never" | "fallback-only";
+	enrichCompat: boolean;
+}
+
+function enrichModel<T extends ProviderModelConfig>(
+	model: T,
+	ctx: EnrichmentContext,
+): T & ModelsDevEnrichedMetadata {
+	const modelMeta = findModelDevMeta(ctx.index, model.id);
+	if (!modelMeta) return model;
+
+	const contextWindow =
+		modelMeta.limit && ctx.fallbackContextWindows.has(model.contextWindow)
+			? modelMeta.limit.context
+			: model.contextWindow;
+	const maxTokens =
+		modelMeta.limit && ctx.fallbackMaxTokens.has(model.maxTokens)
+			? modelMeta.limit.output
+			: model.maxTokens;
+	const input =
+		ctx.enrichInput &&
+		isTextOnly(model.input) &&
+		modelMeta.modalities?.input?.includes("image")
+			? (["text", "image"] as const)
+			: model.input;
+	const reasoning =
+		ctx.enrichReasoning && modelMeta.reasoning === true ? true : model.reasoning;
+	const thinkingLevelMap =
+		ctx.enrichReasoning && model.thinkingLevelMap === undefined
+			? thinkingMapFromReasoningOptions(modelMeta.reasoning_options)
+			: model.thinkingLevelMap;
+	const cost =
+		ctx.enrichCost === "fallback-only" && costLooksLikeFallback(model.cost)
+			? (costFromModelsDev(modelMeta.cost) ?? model.cost)
+			: model.cost;
+	const compat = ctx.enrichCompat
+		? mergeCompat(model.compat, getProxyModelCompat(identityFromMeta(model, modelMeta)))
+		: model.compat;
+
+	const modelsDevMetadata: ModelMatchHints = {
+		id: modelMeta.id,
+		name: modelMeta.name,
+		...(modelMeta.family ? { family: modelMeta.family } : {}),
+		...(modelMeta.provider ? { provider: modelMeta.provider } : {}),
+	};
+
+	return {
+		...model,
+		contextWindow,
+		maxTokens,
+		input,
+		reasoning,
+		...(thinkingLevelMap ? { thinkingLevelMap } : {}),
+		cost,
+		...(compat ? { compat } : {}),
+		modelsDev: modelsDevMetadata,
+	};
+}
+
+/**
+ * Fill Pi-usable model fields from models.dev when provider APIs only expose
+ * generic defaults. Fail-open: network/API failures leave models unchanged.
+ */
+export async function enrichModelsWithModelsDev<T extends ProviderModelConfig>(
+	models: T[],
+	options: ModelsDevEnrichmentOptions = {},
+): Promise<Array<T & ModelsDevEnrichedMetadata>> {
+	if (models.length === 0) return models;
+
+	let meta: Record<string, ModelsDevModel>;
+	try {
+		meta = await fetchModelsDevMeta(options.providerId);
+	} catch (error) {
+		_logger.warn("Failed to load models.dev metadata", {
+			providerId: options.providerId,
+			error: errorMessage(error),
+		});
+		return models;
+	}
+	if (Object.keys(meta).length === 0) return models;
+
+	const ctx: EnrichmentContext = {
+		index: buildModelMetaIndex(meta),
+		fallbackContextWindows: new Set(
+			options.fallbackContextWindows ?? [DEFAULT_CONTEXT_WINDOW, 4096],
+		),
+		fallbackMaxTokens: new Set(
+			options.fallbackMaxTokens ?? [DEFAULT_MAX_TOKENS, 4096],
+		),
+		enrichInput: options.enrichInput ?? true,
+		enrichReasoning: options.enrichReasoning ?? true,
+		enrichCost: options.enrichCost ?? "never",
+		enrichCompat: options.enrichCompat ?? true,
+	};
+
+	return models.map((model) => {
+		try {
+			return enrichModel(model, ctx);
+		} catch (error) {
+			_logger.warn("Failed to enrich model from models.dev metadata", {
+				modelId: model.id,
+				error: errorMessage(error),
+			});
+			return model;
+		}
+	});
+}
+
+export async function safeEnrichModelsWithModelsDev<
+	T extends ProviderModelConfig,
+>(
+	models: T[],
+	options: ModelsDevEnrichmentOptions = {},
+): Promise<Array<T & ModelsDevEnrichedMetadata>> {
+	try {
+		return await enrichModelsWithModelsDev(models, options);
+	} catch {
+		return models;
+	}
+}

package/lib/open-browser.ts

@@ -1,16 +1,59 @@
 /**
  * Cross-platform browser opener
  *
- * Opens a URL in the user's default browser. Handles URL-unsafe characters
- * on Windows by using PowerShell's Start-Process instead of cmd.exe.
+ * Opens a URL in the user's default browser.
+ *
+ * SECURITY:
+ * - On Windows, uses `rundll32 url.dll,FileProtocolHandler <url>` — this
+ *   bypasses cmd.exe's command parser entirely. cmd's `start` builtin
+ *   interprets shell metacharacters (`&`, `|`, `^`, etc.) BEFORE the URL
+ *   reaches its target, so `cmd /c start "" <url>` is exploitable even
+ *   with `shell: false` and discrete args (CodeQL js/uncontrolled-command-line).
+ *   rundll32 doesn't parse the command line, so the URL is handed to
+ *   ShellExecute as a literal.
+ * - On all platforms, URLs are strictly validated: only http/https, no
+ *   control characters. This is defense-in-depth.
+ * - The URL is always passed as a single argument to the underlying
+ *   launcher — never interpolated into a command string.
+ *
+ * Platforms:
+ * - Windows: `rundll32 url.dll,FileProtocolHandler` → ShellExecute
+ * - macOS:   `/usr/bin/open`
+ * - Linux:   `/usr/bin/xdg-open`
  */
 
 import { execFileSync, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
+import { createLogger } from "./logger.ts";
+
+const _logger = createLogger("open-browser");
 
 /**
- * Resolve an executable path, preferring the known absolute path if it exists,
- * falling back to PATH lookup. This avoids relying on an untrusted PATH variable.
+ * Validate that a URL is safe to open.
+ * Only http/https protocols are allowed. URLs with control characters
+ * are rejected.
+ */
+function isSafeUrl(url: string): boolean {
+	if (typeof url !== "string" || url.length === 0 || url.length > 2048) {
+		return false;
+	}
+	// Reject any control characters (NUL, CR, LF, etc.) — they have no
+	// place in a URL and can confuse shell parsers.
+	// eslint-disable-next-line no-control-regex
+	if (/[\x00-\x1f\x7f]/.test(url)) return false;
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return false;
+	}
+	return parsed.protocol === "http:" || parsed.protocol === "https:";
+}
+
+/**
+ * Resolve an executable path, preferring the known absolute path if it
+ * exists, falling back to PATH lookup. This avoids relying on an
+ * untrusted PATH variable.
  */
 function resolveExe(name: string, absolutePath: string): string {
 	if (absolutePath && existsSync(absolutePath)) {
@@ -31,29 +74,32 @@ function resolveExe(name: string, absolutePath: string): string {
 /**
  * Open a URL in the user's default browser.
  *
- * - Windows: uses PowerShell Start-Process (cmd.exe interprets & as command separator)
- * - macOS: uses `open`
- * - Linux/BSD: uses `xdg-open`
+ * Returns true if the URL was accepted and the launcher was spawned,
+ * false if the URL was rejected by validation.
  */
-export function openBrowser(url: string): void {
+export function openBrowser(url: string): boolean {
+	if (!isSafeUrl(url)) {
+		_logger.warn("openBrowser: rejected URL", { url });
+		return false;
+	}
+
 	try {
 		if (process.platform === "win32") {
-			// PowerShell's Start-Process treats the URL as a literal string,
-			// unlike cmd.exe which interprets & as a command separator.
-			const powershell = resolveExe(
-				"powershell.exe",
-				"C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
+			// rundll32 url.dll,FileProtocolHandler invokes ShellExecute
+			// with the URL, which opens it in the user's default browser.
+			// Unlike `cmd /c start "" <url>`, rundll32 does NOT parse the
+			// command line — the URL is handed to ShellExecute as a
+			// literal argument. This is the canonical safe pattern and
+			// addresses the CodeQL "Uncontrolled command line" finding.
+			const rundll32 = resolveExe(
+				"rundll32.exe",
+				"C:\\Windows\\System32\\rundll32.exe",
 			);
-			spawn(
-				powershell,
-				[
-					"-NoProfile",
-					"-NonInteractive",
-					"-Command",
-					`Start-Process "${url.replaceAll(/[\\"]/g, "\\$&")}"`,
-				],
-				{ detached: true, shell: false, windowsHide: true },
-			).unref();
+			spawn(rundll32, ["url.dll,FileProtocolHandler", url], {
+				detached: true,
+				shell: false,
+				windowsHide: true,
+			}).unref();
 		} else if (process.platform === "darwin") {
 			const open = resolveExe("open", "/usr/bin/open");
 			spawn(open, [url], { detached: true }).unref();
@@ -61,8 +107,12 @@ export function openBrowser(url: string): void {
 			const xdgOpen = resolveExe("xdg-open", "/usr/bin/xdg-open");
 			spawn(xdgOpen, [url], { detached: true }).unref();
 		}
+		return true;
 	} catch (err) {
 		// Best-effort — browser opening is non-critical
-		console.debug("Failed to open browser:", err);
+		_logger.warn("Failed to open browser", {
+			error: err instanceof Error ? err.message : String(err),
+		});
+		return false;
 	}
 }