@fonlan/dsh-model-parameters 0.1.7 → 0.2.0

package/lib/types/server/catalog.d.ts

@@ -1,4 +1,5 @@
 import { type ModelParametersConfig } from '../shared/config.js';
+import { type CatalogFetch, type CatalogTransport } from './system-proxy.js';
 /** Structural logger subset satisfied by cordis' LoggerService. */
 export interface CatalogLogger {
     info(format: any, ...param: any[]): void;
@@ -30,16 +31,23 @@ export interface CatalogSnapshot {
     providers: number;
     /** Epoch ms the cache was last fetched (0 = never fetched). */
     fetchedAt: number;
+    /** Route the last download attempt took; undefined until an attempt runs. */
+    transport?: CatalogTransport;
+    /** Message of the last failed download; undefined when the last attempt succeeded. */
+    error?: string;
 }
 export declare class CatalogManager {
     private readonly logger;
     private snapshot;
     private loaded;
     private inflight;
+    private transport;
+    private fetchError;
     private readonly dir;
     private readonly cachePath;
-    constructor(logger: CatalogLogger, dataDir?: string);
-    /** The current snapshot (empty until the first load/fetch completes). */
+    private readonly fetchJson;
+    constructor(logger: CatalogLogger, dataDir?: string, fetchJson?: CatalogFetch);
+    /** The current snapshot, including the route and error of the last download attempt. */
     snapshotOf(): CatalogSnapshot;
     /**
      * Load the disk cache once, then fetch when stale (or `force`). A failed

package/lib/types/server/system-proxy.d.ts

@@ -0,0 +1,112 @@
+/** Structural logger subset satisfied by cordis' LoggerService. */
+export interface ProxyLogger {
+    info(format: any, ...param: any[]): void;
+    warn(format: any, ...param: any[]): void;
+}
+/** Where a detected proxy configuration came from. */
+export type ProxySource = 'env' | 'windows' | 'macos' | 'none';
+/** One proxy configuration read from the operating system. */
+export interface SystemProxyConfig {
+    /** Proxy URL for `http:` targets. */
+    http?: string;
+    /** Proxy URL for `https:` targets. */
+    https?: string;
+    /** The OS bypass/exceptions list, comma separated. */
+    noProxy?: string;
+    source: 'windows' | 'macos';
+    /** Notes about settings this module cannot honor (PAC, SOCKS, malformed entries). */
+    diagnostics: string[];
+}
+/** What the catalog download will do for one URL. */
+export interface CatalogRoute {
+    /** True when this plugin must tunnel the request itself. */
+    tunnel: boolean;
+    /** Proxy URL, present only when {@link CatalogRoute.tunnel} is true. */
+    proxy?: string;
+    source: ProxySource;
+    /** Effective bypass list (OS exceptions; loopback is always bypassed). */
+    noProxy: string;
+    diagnostics: string[];
+}
+/** Structured routing outcome, safe to cross the settings API (credentials stripped). */
+export interface CatalogTransport {
+    kind: 'direct' | 'env' | 'macos' | 'windows';
+    /** Masked proxy URL (no credentials), when a proxy is actually used. */
+    proxy?: string;
+}
+/** A downloaded and parsed catalog document plus the route it took. */
+export interface CatalogFetchResult {
+    body: unknown;
+    transport: CatalogTransport;
+}
+/** Download one JSON document; {@link CatalogManager} takes one for tests. */
+export type CatalogFetch = (url: string, timeoutMs: number) => Promise<CatalogFetchResult>;
+/** Runs one detection command; injectable so the OS parsers stay testable. */
+export type CommandRunner = (command: string, args: string[], timeoutMs: number) => Promise<string>;
+/** Detection inputs; every field exists so tests can pin a platform and its probes. */
+export interface DetectOptions {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    run?: CommandRunner;
+    timeoutMs?: number;
+}
+/**
+ * Parse the value table `reg query <key>` prints. Value names and the
+ * `REG_*` type tokens are not localized, so the same table parses under every
+ * Windows display language. Binary values (the `DefaultConnectionSettings`
+ * blob) are read as empty — nothing in this module consumes them.
+ */
+export declare function parseRegistryQuery(output: string): Map<string, string>;
+/**
+ * Turn the Internet Settings values into a proxy configuration.
+ * `ProxyServer` is either `host:port` (both schemes) or a
+ * `http=host:port;https=host:port` list.
+ * @returns the configuration, or undefined when the OS names no proxy at all.
+ */
+export declare function windowsProxyFromRegistry(values: Map<string, string>): SystemProxyConfig | undefined;
+/** macOS `scutil --proxy` prints a flat key/value dictionary with nested arrays. */
+export declare function parseScutilProxyOutput(output: string): SystemProxyConfig | undefined;
+/**
+ * Read the operating system's proxy configuration (never the environment).
+ * Linux has no portable API for this; its users configure the environment,
+ * which the harness routes.
+ * @param options - platform, probe runner and timeout (tests pin all three).
+ * @returns the detected configuration, or undefined when the OS names none.
+ */
+export declare function detectSystemProxy(options?: DetectOptions): Promise<SystemProxyConfig | undefined>;
+/** A host this machine owns: a proxy cannot reach it, so it always goes direct. */
+export declare function isLoopbackHost(hostname: string): boolean;
+/**
+ * Decide whether a bypass list exempts one URL. Semantics follow the harness's
+ * own matcher — an entry covers its subdomains, a leading `.`/`*.` means the
+ * same, an entry may carry a `:port`, `*` bypasses everything — plus the two
+ * forms OS lists add: `host*` wildcards and `<local>` (a dotless hostname).
+ * Loopback is always bypassed. CIDR notation is not matched.
+ */
+export declare function shouldBypassProxy(noProxy: string, url: URL): boolean;
+/**
+ * Decide how the catalog download for `target` is routed: defer to the harness
+ * for environment proxies, tunnel a detected OS proxy, or go direct. The OS is
+ * consulted only when the environment names no proxy, so an exported variable
+ * keeps winning exactly as it does for the rest of the harness.
+ */
+export declare function resolveCatalogRoute(target: URL | string, options?: DetectOptions): Promise<CatalogRoute>;
+/** Strip any proxy credentials before the route crosses the settings API or logs. */
+export declare function maskProxyUrl(proxy: string): string | undefined;
+/** Describe a route for the settings page. */
+export declare function transportOf(route: CatalogRoute): CatalogTransport;
+/**
+ * Download and parse one HTTPS JSON document through an `http(s)://` proxy,
+ * following redirects. Throws on a non-2xx answer, a malformed body, or a
+ * transport timeout so callers keep the previously cached catalog.
+ */
+export declare function fetchJsonViaProxy(url: string, proxy: string, timeoutMs: number): Promise<unknown>;
+/**
+ * Download the catalog for the settings page: defer to the harness when the
+ * environment names a proxy, otherwise tunnel a detected OS proxy, otherwise
+ * fetch directly. Never throws for routing reasons — transport failures do
+ * throw, and the caller keeps its cached copy.
+ * @param options - detection overrides; production passes nothing, tests pin
+ *   the platform and its OS probes.
+ */
+export declare function fetchJsonWithSystemProxy(url: string, timeoutMs: number, logger?: ProxyLogger, options?: DetectOptions): Promise<CatalogFetchResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fonlan/dsh-model-parameters",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "DSH plugin: when a provider's model sync returns only ids, automatically fill display name, context window, max output tokens, reasoning efforts, and input modalities from the models.dev catalog (cached, TTL-refreshed), and surface a settings page with toggles, refresh, and a fill report.",
   "license": "MIT",
   "repository": {
@@ -49,6 +49,7 @@
     "build": "rm -rf lib && tsc -p tsconfig.build.json && tsdown",
     "prepare": "npm run build",
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.client.json",
+    "test": "pnpm build && node scripts/verify-proxy.mjs",
     "watch": "tsdown --watch",
     "release:patch": "npm version patch && git push && git push --tags",
     "release:minor": "npm version minor && git push && git push --tags",
@@ -70,12 +71,12 @@
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/schemastery": "^3.18.4",
-    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.2 || ^0.2.0-rc.1 || ^0.2.1-alpha.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.2-alpha.2 || ^0.2.0-rc.1 || ^0.2.1-alpha.1",
-    "@deepseek-ai/dsh-llm-pi-ai": "^0.1.2-alpha.2 || ^0.2.0-rc.1 || ^0.2.1-alpha.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.2-alpha.2 || ^0.2.0-rc.1 || ^0.2.1-alpha.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-alpha.2 || ^0.2.0-rc.1 || ^0.2.1-alpha.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-alpha.2 || ^0.2.0-rc.1 || ^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.2 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.2 || ^0.2.1-rc.3",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.2-alpha.2 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.2 || ^0.2.1-rc.3",
+    "@deepseek-ai/dsh-llm-pi-ai": "^0.1.2-alpha.2 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.2 || ^0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-locale": "^0.1.2-alpha.2 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.2 || ^0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-alpha.2 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.2 || ^0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-alpha.2 || ^0.2.0-rc.1 || ^0.2.1-alpha.1 || ^0.2.1-rc.2 || ^0.2.1-rc.3",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
@@ -85,14 +86,14 @@
     "@types/react-dom": "~18.3.0",
     "tsdown": "^0.22.14",
     "typescript": "^5.9.0",
-    "@deepseek-ai/cordis": "4.0.5-alpha.1",
-    "@deepseek-ai/schemastery": "3.18.5-alpha.1",
-    "@deepseek-ai/dsh-settings": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-host-webserver": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-llm-pi-ai": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-client-locale": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-client-ui-slots": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-client-ui-settings": "0.2.1-alpha.1"
+    "@deepseek-ai/cordis": "4.0.5",
+    "@deepseek-ai/schemastery": "3.18.5",
+    "@deepseek-ai/dsh-settings": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-host-webserver": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-llm-pi-ai": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-locale": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.1-rc.3",
+    "@deepseek-ai/dsh-client-ui-settings": "0.2.1-rc.3"
   },
   "packageManager": "pnpm@11.21.0"
 }

package/src/client/api.ts

@@ -1,12 +1,22 @@
 /** Client transport for the model-parameters settings API. */
 import type { ModelParametersConfig } from '../shared/config.js'
 
+export interface CatalogTransportView {
+  kind: 'direct' | 'env' | 'macos' | 'windows'
+  /** Masked proxy URL (no credentials), present when a proxy is actually used. */
+  proxy?: string
+}
+
 export interface CatalogView {
   entries: number
   providers: number
   fetchedAt: number
   fresh: boolean
   ttlDays: number
+  /** Route the last download attempt took (null until one runs). */
+  transport: CatalogTransportView | null
+  /** Message of the last failed download (cleared on success). */
+  error: string | null
 }
 
 export interface FillReportView {

package/src/client/locales.ts

@@ -33,6 +33,12 @@ export const zh = {
   catalogFresh: '新鲜',
   catalogStale: '已过期',
   catalogNever: '尚未获取',
+  catalogRoute: '下载经由',
+  routeDirect: '直连',
+  routeEnv: '环境变量代理',
+  routeMacos: 'macOS 系统代理',
+  routeWindows: 'Windows 系统代理',
+  catalogDownloadFailed: '上次下载失败',
   refresh: '立即更新目录并补全',
   refreshBusy: '更新中…',
   reconcileNow: '立即补全一次',
@@ -78,6 +84,12 @@ export const en: Record<keyof typeof zh, string> = {
   catalogFresh: 'fresh',
   catalogStale: 'stale',
   catalogNever: 'not fetched yet',
+  catalogRoute: 'Download route',
+  routeDirect: 'direct',
+  routeEnv: 'environment proxy',
+  routeMacos: 'macOS system proxy',
+  routeWindows: 'Windows system proxy',
+  catalogDownloadFailed: 'Last download failed',
   refresh: 'Update catalog & fill now',
   refreshBusy: 'Updating…',
   reconcileNow: 'Fill now',

package/src/client/settings-section.tsx

@@ -16,7 +16,7 @@ import type { Context } from '@deepseek-ai/cordis'
 type ClientContext = Context
 import type { Translate } from '@deepseek-ai/dsh-client-ui-slots'
 import { LOCALE_NS } from './locales'
-import { api, type PluginState } from './api'
+import { api, type CatalogTransportView, type PluginState } from './api'
 import type { ModelParametersConfig } from '../shared/config.js'
 import './settings-section.css'
 
@@ -49,6 +49,20 @@ function formatTime(epochMs: number): string {
   }
 }
 
+/** Localized label for the route the last catalog download took. */
+function routeLabel(t: Translate, transport: CatalogTransportView): string {
+  switch (transport.kind) {
+    case 'env':
+      return t('routeEnv')
+    case 'macos':
+      return t('routeMacos')
+    case 'windows':
+      return t('routeWindows')
+    default:
+      return t('routeDirect')
+  }
+}
+
 export function makeSettingsSection(ctx: ClientContext): () => JSX.Element {
   const t: Translate = (() => {
     try {
@@ -267,7 +281,17 @@ function ModelParametersBody(props: {
               }}
             />
           </label>
+          {catalog.transport != null && (
+            <span>
+              {t('catalogRoute')}:{' '}
+              <strong>{routeLabel(t, catalog.transport)}</strong>
+              {catalog.transport.proxy !== undefined && <> <code className="mp-code">{catalog.transport.proxy}</code></>}
+            </span>
+          )}
         </div>
+        {catalog.error != null && (
+          <p className="mp-error">{t('catalogDownloadFailed')}: {catalog.error}</p>
+        )}
         <div className="mp-actions">
           <button className="mp-button" disabled={busy} onClick={() => void onRefresh()}>
             {busy ? t('refreshBusy') : t('refresh')}

package/src/index.ts

@@ -20,6 +20,26 @@ import {
   type CatalogEntry,
   type CatalogSnapshot,
 } from './server/catalog.js'
+import {
+  detectSystemProxy,
+  fetchJsonViaProxy,
+  fetchJsonWithSystemProxy,
+  isLoopbackHost,
+  maskProxyUrl,
+  parseRegistryQuery,
+  parseScutilProxyOutput,
+  resolveCatalogRoute,
+  shouldBypassProxy,
+  transportOf,
+  windowsProxyFromRegistry,
+  type CatalogFetch,
+  type CatalogFetchResult,
+  type CatalogRoute,
+  type CatalogTransport,
+  type CommandRunner,
+  type DetectOptions,
+  type SystemProxyConfig,
+} from './server/system-proxy.js'
 
 export const name = '@fonlan/dsh-model-parameters'
 
@@ -31,6 +51,28 @@ export const inject: string[] = []
 export { Config }
 export { CatalogManager, acceptedInputModalities, identityReasoningEfforts }
 export type { CatalogEntry, CatalogSnapshot }
+export {
+  detectSystemProxy,
+  fetchJsonViaProxy,
+  fetchJsonWithSystemProxy,
+  isLoopbackHost,
+  maskProxyUrl,
+  parseRegistryQuery,
+  parseScutilProxyOutput,
+  resolveCatalogRoute,
+  shouldBypassProxy,
+  transportOf,
+  windowsProxyFromRegistry,
+}
+export type {
+  CatalogFetch,
+  CatalogFetchResult,
+  CatalogRoute,
+  CatalogTransport,
+  CommandRunner,
+  DetectOptions,
+  SystemProxyConfig,
+}
 
 export function apply(ctx: Context, config: ModelParametersLiveConfig = {}): void {
   const service = new ModelParametersService(ctx, config)

package/src/server/catalog.ts

@@ -1,6 +1,10 @@
 /**
  * models.dev catalog: fetch, disk cache, lazy TTL refresh, and id matching.
  *
+ * The download goes through {@link fetchJsonWithSystemProxy}, so it follows the
+ * proxy environment the harness already routes (unchanged) and, when no proxy
+ * variable is set, the operating system's proxy — see system-proxy.ts.
+ *
  * The catalog is flattened into a list of entries keyed by provider, then
  * indexed by the last path segment of the model id (case-insensitive) so a
  * synced bare id like `qwen3.7-max` can resolve `Qwen/Qwen3.7-Max` wherever
@@ -24,6 +28,11 @@ import {
   REASONING_LEVELS,
   type ModelParametersConfig,
 } from '../shared/config.js'
+import {
+  fetchJsonWithSystemProxy,
+  type CatalogFetch,
+  type CatalogTransport,
+} from './system-proxy.js'
 
 /** Structural logger subset satisfied by cordis' LoggerService. */
 export interface CatalogLogger {
@@ -58,6 +67,10 @@ export interface CatalogSnapshot {
   providers: number
   /** Epoch ms the cache was last fetched (0 = never fetched). */
   fetchedAt: number
+  /** Route the last download attempt took; undefined until an attempt runs. */
+  transport?: CatalogTransport
+  /** Message of the last failed download; undefined when the last attempt succeeded. */
+  error?: string
 }
 
 const DAY_MS = 24 * 60 * 60 * 1000
@@ -87,20 +100,25 @@ export class CatalogManager {
   private snapshot: CatalogSnapshot = { entries: [], providers: 0, fetchedAt: 0 }
   private loaded = false
   private inflight: Promise<void> | null = null
+  private transport: CatalogTransport | undefined
+  private fetchError: string | undefined
   private readonly dir: string
   private readonly cachePath: string
+  private readonly fetchJson: CatalogFetch
 
   constructor(
     private readonly logger: CatalogLogger,
     dataDir?: string,
+    fetchJson?: CatalogFetch,
   ) {
     this.dir = dataDir ?? join(homedir(), '.dsh', 'model-parameters')
     this.cachePath = join(this.dir, 'catalog.json')
+    this.fetchJson = fetchJson ?? ((url, timeoutMs) => fetchJsonWithSystemProxy(url, timeoutMs, logger))
   }
 
-  /** The current snapshot (empty until the first load/fetch completes). */
+  /** The current snapshot, including the route and error of the last download attempt. */
   snapshotOf(): CatalogSnapshot {
-    return this.snapshot
+    return { ...this.snapshot, transport: this.transport, error: this.fetchError }
   }
 
   /**
@@ -122,10 +140,14 @@ export class CatalogManager {
       return true
     }
     this.inflight = this.fetchAndPersist()
+      .then(() => {
+        this.fetchError = undefined
+      })
       .catch((error) => {
-        this.logger.warn(
-          `model-parameters: catalog fetch failed (${error instanceof Error ? error.message : String(error)}); using cached copy`,
-        )
+        this.fetchError = error instanceof Error ? error.message : String(error)
+        const attempted = (error as { transport?: CatalogTransport }).transport
+        if (attempted !== undefined) this.transport = attempted
+        this.logger.warn(`model-parameters: catalog fetch failed (${this.fetchError}); using cached copy`)
       })
       .finally(() => {
         this.inflight = null
@@ -208,23 +230,17 @@ export class CatalogManager {
   }
 
   private async fetchAndPersist(): Promise<void> {
-    const controller = new AbortController()
-    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
-    let response: Response
-    try {
-      response = await fetch(CATALOG_URL, { signal: controller.signal, headers: { accept: 'application/json' } })
-    } finally {
-      clearTimeout(timer)
-    }
-    if (!response.ok) {
-      throw new Error(`HTTP ${response.status} ${response.statusText}`)
+    const { body, transport } = await this.fetchJson(CATALOG_URL, FETCH_TIMEOUT_MS)
+    if (typeof body !== 'object' || body === null) {
+      throw new Error('catalog response is not a JSON object')
     }
-    const body = (await response.json()) as Record<string, unknown>
+    const document = body as Record<string, unknown>
     const fetchedAt = Date.now()
-    this.snapshot = this.buildSnapshot(body, fetchedAt)
+    this.snapshot = this.buildSnapshot(document, fetchedAt)
     await mkdir(this.dir, { recursive: true })
-    const doc: CacheDocument = { fetchedAt, body }
+    const doc: CacheDocument = { fetchedAt, body: document }
     await writeFile(this.cachePath, JSON.stringify(doc), 'utf8')
+    this.transport = transport
     this.logger.info(
       `model-parameters: catalog refreshed from models.dev (${this.snapshot.providers} providers, ${this.snapshot.entries.length} models)`,
     )

package/src/server/rpc.ts

@@ -156,6 +156,8 @@ function stateOf(service: ModelParametersService): unknown {
       fresh: snapshot.fetchedAt > 0
         && Date.now() - snapshot.fetchedAt < config.ttlDays * 24 * 60 * 60 * 1000,
       ttlDays: config.ttlDays,
+      transport: snapshot.transport ?? null,
+      error: snapshot.error ?? null,
     },
     report: service.report(),
   }