@moxxy/plugin-provider-admin 0.26.0

package/src/key-name.test.ts

@@ -0,0 +1,61 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { providerApiKeyName, storedProviderApiKeyName } from './key-name.js';
+import { upsertStoredProvider } from './store.js';
+import type { StoredProvider } from './types.js';
+
+describe('providerApiKeyName', () => {
+  it('upper-snakes the slug and appends _API_KEY', () => {
+    expect(providerApiKeyName('deepseek')).toBe('DEEPSEEK_API_KEY');
+  });
+
+  it('maps hyphens to underscores so the result is a valid env-var name', () => {
+    // The CLI's old derivation kept the hyphen (`Z-AI_API_KEY`), which is
+    // not a valid POSIX env-var name and diverged from the desktop's.
+    expect(providerApiKeyName('z-ai')).toBe('Z_AI_API_KEY');
+    expect(providerApiKeyName({ name: 'z-ai' })).toBe('Z_AI_API_KEY');
+  });
+
+  it('honors a stored envVar override over the derived name', () => {
+    expect(providerApiKeyName({ name: 'zai', envVar: 'ZHIPU_KEY' })).toBe('ZHIPU_KEY');
+  });
+});
+
+describe('storedProviderApiKeyName', () => {
+  let tmpDir: string;
+  let cfgPath: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-key-name-'));
+    cfgPath = path.join(tmpDir, 'providers.json');
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  const entry = (over: Partial<StoredProvider> = {}): StoredProvider => ({
+    kind: 'openai-compat',
+    name: 'my-vendor',
+    baseURL: 'https://api.example.com/v1',
+    defaultModel: 'm1',
+    models: [{ id: 'm1', contextWindow: 100_000, supportsTools: true, supportsStreaming: true }],
+    ...over,
+  });
+
+  it('returns the envVar override for a stored provider', async () => {
+    await upsertStoredProvider(entry({ envVar: 'CUSTOM_KEY' }), cfgPath);
+    await expect(storedProviderApiKeyName('my-vendor', cfgPath)).resolves.toBe('CUSTOM_KEY');
+  });
+
+  it('falls back to the canonical derivation when no override is stored', async () => {
+    await upsertStoredProvider(entry(), cfgPath);
+    await expect(storedProviderApiKeyName('my-vendor', cfgPath)).resolves.toBe('MY_VENDOR_API_KEY');
+  });
+
+  it('returns null for providers not in providers.json (built-ins)', async () => {
+    await expect(storedProviderApiKeyName('anthropic', cfgPath)).resolves.toBeNull();
+  });
+});

package/src/key-name.ts

@@ -0,0 +1,39 @@
+import { readProvidersConfig } from './store.js';
+
+/**
+ * THE canonical derivation of the vault/env key name that holds a
+ * provider's API key. Every consumer (provider-admin tools, the CLI's
+ * credential resolution, the desktop's provider discovery) must agree on
+ * this name or keys stored by one surface become invisible to another —
+ * previously the CLI, the admin tools and the desktop each derived it
+ * slightly differently (the CLI didn't map `-` → `_` and ignored the
+ * stored `envVar` override).
+ *
+ * Rules:
+ *  - a stored `envVar` override always wins;
+ *  - otherwise the provider slug is upper-snaked and suffixed with
+ *    `_API_KEY` (`z-ai` → `Z_AI_API_KEY`) — hyphens become underscores
+ *    so the result is a valid POSIX env-var name.
+ */
+export function providerApiKeyName(
+  provider: string | { readonly name: string; readonly envVar?: string },
+): string {
+  if (typeof provider !== 'string' && provider.envVar) return provider.envVar;
+  const name = typeof provider === 'string' ? provider : provider.name;
+  return `${name.toUpperCase().replace(/-/g, '_')}_API_KEY`;
+}
+
+/**
+ * Key name for a provider honoring any `envVar` override persisted in
+ * ~/.moxxy/providers.json. Returns `null` when the provider isn't a
+ * stored (runtime-registered) one — callers fall back to
+ * `providerApiKeyName(name)` for built-ins.
+ */
+export async function storedProviderApiKeyName(
+  providerName: string,
+  configPath?: string,
+): Promise<string | null> {
+  const cfg = await readProvidersConfig(configPath);
+  const entry = cfg.providers.find((p) => p.name === providerName);
+  return entry ? providerApiKeyName(entry) : null;
+}

package/src/store.test.ts

@@ -0,0 +1,115 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {
+  readProvidersConfig,
+  removeStoredProvider,
+  upsertStoredProvider,
+  writeProvidersConfig,
+} from './store.js';
+import type { StoredProvider } from './types.js';
+
+const sampleEntry: StoredProvider = {
+  kind: 'openai-compat',
+  name: 'zai',
+  baseURL: 'https://api.z.ai/api/coding/paas/v4',
+  defaultModel: 'glm-4.6',
+  models: [{ id: 'glm-4.6', contextWindow: 200_000, supportsTools: true, supportsStreaming: true }],
+};
+
+let tmpDir: string;
+let cfgPath: string;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-provider-admin-'));
+  cfgPath = path.join(tmpDir, 'providers.json');
+});
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+describe('providers.json store', () => {
+  it('returns an empty list when the file is missing', async () => {
+    const cfg = await readProvidersConfig(cfgPath);
+    expect(cfg.providers).toEqual([]);
+  });
+
+  it('round-trips a single provider through write/read', async () => {
+    await writeProvidersConfig({ providers: [sampleEntry] }, cfgPath);
+    const cfg = await readProvidersConfig(cfgPath);
+    expect(cfg.providers).toHaveLength(1);
+    expect(cfg.providers[0]).toMatchObject({ name: 'zai', defaultModel: 'glm-4.6' });
+  });
+
+  it('upsert replaces an entry with the same name (no duplicates)', async () => {
+    await upsertStoredProvider(sampleEntry, cfgPath);
+    const updated: StoredProvider = { ...sampleEntry, defaultModel: 'glm-4.5-air' };
+    const next = await upsertStoredProvider(updated, cfgPath);
+    expect(next.providers).toHaveLength(1);
+    expect(next.providers[0]!.defaultModel).toBe('glm-4.5-air');
+  });
+
+  it('upsert appends distinct entries', async () => {
+    await upsertStoredProvider(sampleEntry, cfgPath);
+    const second: StoredProvider = { ...sampleEntry, name: 'deepseek', baseURL: 'https://api.deepseek.com' };
+    const next = await upsertStoredProvider(second, cfgPath);
+    expect(next.providers).toHaveLength(2);
+    expect(next.providers.map((p) => p.name).sort()).toEqual(['deepseek', 'zai']);
+  });
+
+  it('remove returns false when the entry was not present', async () => {
+    expect(await removeStoredProvider('nonexistent', cfgPath)).toBe(false);
+  });
+
+  it('remove drops the entry and returns true', async () => {
+    await upsertStoredProvider(sampleEntry, cfgPath);
+    expect(await removeStoredProvider('zai', cfgPath)).toBe(true);
+    const cfg = await readProvidersConfig(cfgPath);
+    expect(cfg.providers).toEqual([]);
+  });
+
+  it('treats malformed JSON as empty', async () => {
+    await fs.writeFile(cfgPath, '{ not json', 'utf8');
+    const cfg = await readProvidersConfig(cfgPath);
+    expect(cfg.providers).toEqual([]);
+  });
+
+  it('rethrows a genuine IO error instead of collapsing it to an empty catalog', async () => {
+    // A read failure that is NOT "file missing" (here: the path resolves to a
+    // DIRECTORY → EISDIR) must surface as a real error, not silently become an
+    // empty catalog the next write would then CLOBBER.
+    const dirAsFile = path.join(tmpDir, 'a-directory');
+    await fs.mkdir(dirAsFile);
+    await expect(readProvidersConfig(dirAsFile)).rejects.toBeTruthy();
+  });
+
+  it('defaults supportsTools/supportsStreaming on a legacy on-disk model', async () => {
+    // A hand-edited / legacy entry with only {id, contextWindow} must round-trip
+    // into a complete ModelDescriptor (required booleans defaulted true), not
+    // reach buildProviderDef with `undefined` flags.
+    await fs.writeFile(
+      cfgPath,
+      JSON.stringify({
+        providers: [
+          {
+            kind: 'openai-compat',
+            name: 'legacy',
+            baseURL: 'https://api.legacy.com/v1',
+            defaultModel: 'm',
+            models: [{ id: 'm', contextWindow: 1000 }],
+          },
+        ],
+      }),
+      'utf8',
+    );
+    const cfg = await readProvidersConfig(cfgPath);
+    expect(cfg.providers[0]!.models[0]).toMatchObject({
+      id: 'm',
+      contextWindow: 1000,
+      supportsTools: true,
+      supportsStreaming: true,
+    });
+  });
+});

package/src/store.ts

@@ -0,0 +1,123 @@
+import { promises as fs } from 'node:fs';
+import { createMutex, z } from '@moxxy/sdk';
+import { moxxyPath, writeFileAtomic } from '@moxxy/sdk/server';
+import type { StoredProvider, StoredProvidersConfig } from './types.js';
+
+/**
+ * User-level provider catalog. Mirrors the MCP admin storage pattern:
+ * a JSON file in ~/.moxxy/ that the admin tools mutate and the plugin's
+ * onInit hook reads back on every boot to repopulate the registry.
+ */
+export function providersConfigPath(): string {
+  return moxxyPath('providers.json');
+}
+
+/**
+ * Schema for the on-disk providers.json. Kept loose on the model
+ * descriptor (passthrough) so a richer descriptor written by a newer
+ * build round-trips through an older one without losing fields, but
+ * strict enough to discard a structurally-bogus file.
+ */
+const storedModelSchema = z
+  .object({
+    id: z.string().min(1),
+    contextWindow: z.number(),
+    // ModelDescriptor declares these as REQUIRED booleans; default them here so
+    // a hand-edited / legacy providers.json round-trips into a complete
+    // descriptor instead of reaching buildProviderDef with `undefined` (which
+    // channels treat differently from `false` for tool/streaming gating).
+    supportsTools: z.boolean().default(true),
+    supportsStreaming: z.boolean().default(true),
+  })
+  .passthrough();
+
+const storedProviderSchema = z
+  .object({
+    kind: z.literal('openai-compat'),
+    name: z.string().min(1),
+    baseURL: z.string().min(1),
+    defaultModel: z.string().min(1),
+    models: z.array(storedModelSchema),
+    envVar: z.string().optional(),
+    createdAt: z.string().optional(),
+  })
+  .passthrough();
+
+const storedProvidersConfigSchema = z.object({
+  providers: z.array(storedProviderSchema),
+});
+
+export async function readProvidersConfig(filePath: string = providersConfigPath()): Promise<StoredProvidersConfig> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(filePath, 'utf8');
+  } catch (err) {
+    // A MISSING file means "no providers yet" — start fresh. But a genuine IO /
+    // permission error (EACCES, EBUSY, EMFILE, …) must NOT be collapsed into an
+    // empty catalog: doing so makes the plugin behave as if zero providers are
+    // registered and the next read-modify-write would CLOBBER the real file.
+    // Rethrow so callers (onInit's try/catch, the admin tools) see the failure.
+    if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') return { providers: [] };
+    throw err;
+  }
+  // Malformed JSON / structurally-bogus content is intentionally treated as an
+  // empty catalog (start fresh) rather than a hard failure.
+  const parsed = storedProvidersConfigSchema.safeParse(parseJsonSafe(raw));
+  if (parsed.success) {
+    // The schema is intentionally looser than StoredProvidersConfig (model
+    // descriptors are validated as id+contextWindow + passthrough, not the
+    // full ModelDescriptor) so newer/older builds round-trip without losing
+    // fields. Assert the domain type after the structural check.
+    return parsed.data as unknown as StoredProvidersConfig;
+  }
+  return { providers: [] };
+}
+
+function parseJsonSafe(raw: string): unknown {
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function writeProvidersConfig(
+  cfg: StoredProvidersConfig,
+  filePath: string = providersConfigPath(),
+): Promise<void> {
+  await writeFileAtomic(filePath, JSON.stringify(cfg, null, 2) + '\n');
+}
+
+/**
+ * Serializes the read-modify-write mutators below. Without this, two
+ * concurrent upsert/remove calls could both read the same baseline and
+ * the second write would clobber the first.
+ */
+const writeMutex = createMutex();
+
+export async function upsertStoredProvider(
+  entry: StoredProvider,
+  filePath: string = providersConfigPath(),
+): Promise<StoredProvidersConfig> {
+  return writeMutex.run(async () => {
+    const cfg = await readProvidersConfig(filePath);
+    const next = cfg.providers.filter((p) => p.name !== entry.name);
+    next.push(entry);
+    const updated: StoredProvidersConfig = { providers: next };
+    await writeProvidersConfig(updated, filePath);
+    return updated;
+  });
+}
+
+export async function removeStoredProvider(
+  name: string,
+  filePath: string = providersConfigPath(),
+): Promise<boolean> {
+  return writeMutex.run(async () => {
+    const cfg = await readProvidersConfig(filePath);
+    const next = cfg.providers.filter((p) => p.name !== name);
+    if (next.length === cfg.providers.length) return false;
+    await writeProvidersConfig({ providers: next }, filePath);
+    return true;
+  });
+}

package/src/types.ts

@@ -0,0 +1,38 @@
+import type { ModelDescriptor } from '@moxxy/sdk';
+
+/**
+ * Persisted entry for a user-registered LLM provider. Lives in
+ * ~/.moxxy/providers.json and is re-read on every boot to re-register
+ * the provider against the in-process registry.
+ *
+ * Phase 1 only supports `openai-compat` — i.e. vendors that speak the
+ * OpenAI Chat Completions wire protocol (z.ai, deepseek, groq,
+ * openrouter, fireworks, together, mistral, …). The host wraps the
+ * shared `@moxxy/plugin-provider-openai` client with the vendor's
+ * `baseURL`, so we don't reimplement streaming for each new vendor.
+ *
+ * Future kinds (e.g. `anthropic-compat`, native vendor SDKs) extend the
+ * discriminated union; the rest of the pipeline (store + onInit) is
+ * agnostic so they slot in without touching the persistence layer.
+ */
+export interface StoredProviderOpenAICompat {
+  readonly kind: 'openai-compat';
+  /** Provider name (slug). Becomes the registry key + canonical vault entry stem. */
+  readonly name: string;
+  /** Vendor base URL, e.g. `https://api.z.ai/api/coding/paas/v4`. */
+  readonly baseURL: string;
+  /** Model id used when the request didn't pin one explicitly. */
+  readonly defaultModel: string;
+  /** Models the vendor exposes. Powers `/model` autocomplete + the setup wizard. */
+  readonly models: ReadonlyArray<ModelDescriptor>;
+  /** Optional vendor-supplied env var name for the API key (defaults to `<NAME>_API_KEY`). */
+  readonly envVar?: string;
+  /** ISO timestamp the entry was written. Informational only. */
+  readonly createdAt?: string;
+}
+
+export type StoredProvider = StoredProviderOpenAICompat;
+
+export interface StoredProvidersConfig {
+  readonly providers: ReadonlyArray<StoredProvider>;
+}