amicus 4.9.8 → 4.10.0

package/src/sidecar/aliases.js

@@ -0,0 +1,279 @@
+/**
+ * @module sidecar/aliases
+ * `amicus aliases` (#238 D4) — the user's alias map as a standing command.
+ *
+ *   amicus aliases            list: following / pinned, grouped by vendor
+ *   amicus aliases --review   picker over every proposal (aliases-review.js)
+ *   amicus aliases --json     versioned document: rows + proposals
+ *
+ * The LIST reads the catalog CACHE at any age and never networks (§5 display
+ * gate); the picker refreshes inline when the cache is stale (write gate).
+ * Every form normalizes the config on entry (D6), best-effort.
+ *
+ * #249 r2 C4: `renderAliasList`'s alias names, ids and vendor-group labels
+ * (an unmapped vendor's label is `titleCaseVendor` of a config VALUE's
+ * segment — still third-party, per review F1), and the typed name in
+ * `handleUnpin`'s messages, are quoted onto a terminal and ride `safeFragment`
+ * (the house sanitizer, `utils/text-sanitize.js`) — the fragment, never the
+ * composed line, per `alias-shadow.js :: formatAliasShadow`'s rule. A caught
+ * `err.message` is a sentence, not an id, so it rides `collapseExcerpt` at
+ * the house default cap instead (the `describeThrown` precedent).
+ */
+
+'use strict';
+
+const { SCHEMA_VERSION } = require('../utils/result-schema-version');
+const { DEFAULT_MAX_AGE_MS } = require('../utils/model-catalog');
+const { stripGatewayPrefix } = require('../utils/curated-models');
+const { safeFragment, collapseExcerpt } = require('../utils/text-sanitize');
+
+/** @returns {object} this module's collaborators, gathered so a caller can override them in tests */
+function loadDeps() {
+  const config = require('../utils/config');
+  return {
+    config,
+    normalizeAliases: require('../utils/alias-state').normalizeAliases,
+    listAliasRows: require('../utils/alias-state').listAliasRows,
+    buildAliasProposals: require('../utils/alias-proposals').buildAliasProposals,
+    readDismissals: require('../utils/alias-store').readDismissals,
+    getCatalogInfo: require('../utils/model-catalog').getCatalogInfo,
+    readCache: require('../utils/model-catalog').readCache,
+    groupAliases: require('../utils/alias-groups').groupAliases,
+  };
+}
+
+/** @returns {boolean} true when an own value of `aliases` is not a non-empty string -- saveConfig's own stripper would remove it */
+function hasStrippableAliasValue(aliases) {
+  return Object.keys(aliases).some(k => typeof aliases[k] !== 'string' || aliases[k].length === 0);
+}
+
+/**
+ * Normalize on entry (D6), best-effort: a read-only config dir never blocks a
+ * listing — the in-memory normalized view is used and the failure announced.
+ * Also fires on a non-string value (#249 r1 R8a): `normalizeAliases` only
+ * drops a value equal to the shipped default, so a garbage value would
+ * otherwise sit on disk forever -- `saveConfig`'s own stripper removes it,
+ * with its own Notice.
+ * @returns {object} the user alias map after normalization
+ */
+function normalizeOnEntry(d) {
+  const cfg = d.config.loadConfig();
+  const defaults = d.config.getDefaultAliases();
+  if (!cfg || !cfg.aliases || typeof cfg.aliases !== 'object') { return {}; }
+  const probe = d.normalizeAliases(cfg.aliases, defaults);
+  if (probe.removed.length > 0 || hasStrippableAliasValue(cfg.aliases)) {
+    try { d.config.saveConfig(cfg); }                              // saveConfig prints the Notices
+    catch (err) { process.stderr.write(`Notice: could not normalize aliases (${collapseExcerpt(err.message)}) — keys left on disk; every alias still resolves to the same id\n`); }
+  }
+  return probe.aliases;
+}
+
+/**
+ * @param {{maxAgeMs?: number}} [opts] `Number.POSITIVE_INFINITY` = cache only
+ * @returns {Promise<{rows: Array, proposals: Array, catalogInfo: object, catalogAvailable: boolean}>}
+ */
+async function collectAliasView(opts = {}, d = loadDeps()) {
+  const userAliases = normalizeOnEntry(d);
+  const defaults = d.config.getDefaultAliases();
+  let catalogInfo = { models: [], fetchedAt: null, providerFailures: [] };
+  try {
+    if (opts.maxAgeMs === Number.POSITIVE_INFINITY) {
+      // Display gate (§5): the LIST never networks, even to fill an empty or
+      // v1 cache — read whatever is on disk, verbatim, with no freshness
+      // check at all. `getCatalogInfo` cannot be reused here: it always
+      // calls `getCatalog`, which refreshes (a real fetch) the moment
+      // `readCache()` returns null, regardless of `maxAgeMs`.
+      const c = d.readCache();
+      catalogInfo = {
+        models: (c && Array.isArray(c.models)) ? c.models : [],
+        fetchedAt: c && typeof c.fetchedAt === 'number' ? c.fetchedAt : null,
+        providerFailures: (c && Array.isArray(c.providerFailures)) ? c.providerFailures : [],
+      };
+    } else {
+      // The picker's default-age path (Task 8): a stale cache refreshes inline.
+      catalogInfo = await d.getCatalogInfo(opts.maxAgeMs === undefined ? {} : { maxAgeMs: opts.maxAgeMs });
+    }
+  } catch (err) { process.stderr.write(`Notice: catalog unavailable (${collapseExcerpt(err.message)}) — no proposals\n`); }
+  const rows = d.listAliasRows(userAliases, defaults);
+  const proposals = d.buildAliasProposals({ userAliases, defaults, catalogInfo, dismissed: d.readDismissals() });
+  return { rows, proposals, catalogInfo, catalogAvailable: (catalogInfo.models || []).length > 0 };
+}
+
+/**
+ * F2: the per-row flag names the SPECIFIC reason a proposal exists, instead
+ * of a blanket "newer available" that was wrong for two of the three kinds —
+ * an ahead-of-shipped pin with no sibling only differs from the shipped pin,
+ * and a stale pin with no catalog match at all is gone from the catalog
+ * outright, neither of which is "newer available".
+ * @param {string[]} reasons a proposal's `reasons` array
+ * @returns {string} the row suffix, or '' when called with no reasons
+ */
+function rowFlag(reasons) {
+  if (!reasons || reasons.length === 0) { return ''; }
+  if (reasons.includes('newer-sibling')) { return '   ⚠ newer available'; }
+  if (reasons.includes('stale')) { return '   ⚠ gone from catalog'; }
+  return '   differs from shipped';
+}
+
+/**
+ * R4 (#249 r1 C1): a pinned curated row that names the shipped model under a
+ * DIFFERENT gateway form gets no proposal at all -- alias-proposals.js's own
+ * `sameModel` already treats it as identical to the shipped pin, so it is
+ * neither stale nor "differing". Without this note it renders identically
+ * to an arbitrary custom pin, losing the fact that it is the shipped
+ * recommendation in a different form. Truthful transparency, not a warning.
+ * @param {{state:string, curated:boolean, id:string, shipped:string|null}} r
+ * @returns {string} the row suffix, or '' when the note does not apply
+ */
+function sameGatewayNote(r) {
+  if (r.state !== 'pinned' || !r.curated || typeof r.id !== 'string' || typeof r.shipped !== 'string') { return ''; }
+  if (r.id === r.shipped) { return ''; }
+  return stripGatewayPrefix(r.id) === stripGatewayPrefix(r.shipped) ? '   same model as shipped, other gateway' : '';
+}
+
+/** @param {{rows: Array, proposals: Array}} view @param {Function} [groupAliases] injectable for tests; defaults to loadDeps().groupAliases so the published `(view) => string` signature works standalone @returns {string} */
+function renderAliasList(view, groupAliases = loadDeps().groupAliases) {
+  const byAlias = new Map(view.rows.map(r => [r.alias, r]));
+  const proposalByAlias = new Map(view.proposals.map(p => [p.alias, p]));
+  const map = { __proto__: null };
+  for (const r of view.rows) { map[r.alias] = r.id; }
+  // #249 r2 C4: width is computed from the SANITIZED name -- a bidi/ANSI
+  // fragment stripped at render time must not skew the column alignment of
+  // every other row's padding.
+  const width = Math.max(6, ...view.rows.map(r => safeFragment(r.alias).length));
+  const lines = [];
+  for (const g of groupAliases(map)) {
+    // F1 (#249 r2 review, C4 residual): for a vendor NOT in ALIAS_VENDOR_LABELS,
+    // `alias-groups.js :: vendorLabel` title-cases the raw vendor segment of a
+    // config VALUE (`aliasVendorOf`) rather than mapping it to house text --
+    // that is still third-party data, unlike the ~30 mapped labels. Sanitized
+    // HERE, not inside `vendorLabel`: that helper also renders into the
+    // Electron setup UI's HTML context (`electron/setup-ui-alias-groups.js`),
+    // out of scope for this terminal-only house rule.
+    lines.push(`  ${safeFragment(g.label)}`);
+    for (const key of g.keys) {
+      const r = byAlias.get(key);
+      const p = proposalByAlias.get(key);
+      const flag = p ? rowFlag(p.reasons) : sameGatewayNote(r);
+      lines.push(`    ${safeFragment(key).padEnd(width)}  → ${safeFragment(r.id).padEnd(44)} ${r.state}${flag}`);
+    }
+  }
+  lines.push('');
+  // F1: an unavailable catalog cannot be checked for updates at all -- that is
+  // a different fact from "checked, nothing found" and must not print the
+  // reassuring "nothing to review" line.
+  if (!view.catalogAvailable) {
+    lines.push('  catalog unavailable — cannot check for updates (amicus models --refresh)');
+    return lines.join('\n') + '\n';
+  }
+  const n = view.proposals.length;
+  lines.push(n === 0
+    ? '  nothing to review — amicus aliases --review'
+    : `  ${n} to review — amicus aliases --review`);
+  // F1: the catalog is available but stale -- name its age so a user who
+  // never runs --review still learns the background refresh isn't keeping up.
+  const fetchedAt = view.catalogInfo && view.catalogInfo.fetchedAt;
+  if (typeof fetchedAt === 'number' && (Date.now() - fetchedAt) > DEFAULT_MAX_AGE_MS) {
+    const days = Math.floor((Date.now() - fetchedAt) / DEFAULT_MAX_AGE_MS);
+    lines.push(`  (catalog is ${days} day${days === 1 ? '' : 's'} old — amicus models --refresh)`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+/** @returns {object} the `--json` document (fields only ever ADDED within SCHEMA_VERSION) */
+function buildAliasesDoc(view) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    type: 'aliases',
+    catalogAvailable: view.catalogAvailable,
+    catalogFetchedAt: view.catalogInfo.fetchedAt || null,
+    aliasCount: view.rows.length,
+    aliases: view.rows,
+    proposalCount: view.proposals.length,
+    proposals: view.proposals,
+  };
+}
+
+/**
+ * `amicus aliases --unpin <name>` (#238 F6, R1): "unpin" and "delete" are one
+ * operation -- remove the key -- whose meaning is decided by whether the
+ * name is curated (D1). The name is trimmed before every use -- for the
+ * `removeAlias` lookup, the `isCurated` check and both success messages --
+ * so a padded name neither crashes nor mis-reports which branch fired
+ * (#249 r1 R1). Blank/whitespace/literal-'null' names are refused here, and
+ * `removeAlias` is called under try/catch so any other throw (its own name
+ * guard included) becomes a clean exit 1, never an uncaught crash.
+ *
+ * R4 (#249 r2 D2): refused BEFORE any write when `name` is also
+ * `config.default` and NOT curated -- deleting it would leave the default
+ * dangling on a key that no longer resolves (`resolveModel` throws), and
+ * silently doing that fails the product principle (never a silent dangling
+ * default) as hard as a crash. Precedent: `cli-handlers-provider.js ::
+ * doRemove` re-points `config.default` when a provider goes away; here the
+ * user is deleting one alias on purpose, so refusing and naming the fix is
+ * the transparent choice instead. A CURATED default is unaffected -- it
+ * keeps resolving from the shipped table after the unpin, same as any other
+ * curated unpin. `config.default` may also be a bare model id rather than
+ * an alias name (`start-helpers.js` resolves either); the guard compares
+ * against the literal `name` argument, so a default that merely happens to
+ * RESOLVE to the same id as this alias is not what it's checking.
+ * @param {*} rawName whatever `args.unpin` parsed to
+ * @returns {number} exit code
+ */
+function handleUnpin(rawName) {
+  const name = typeof rawName === 'string' ? rawName.trim() : '';
+  if (!name || name === 'null') {
+    process.stderr.write('Error: --unpin requires an alias name\n');
+    return 1;
+  }
+  const { removeAlias } = require('../utils/alias-store');
+  const { isCurated } = require('../utils/alias-state');
+  const config = require('../utils/config');
+  const defaults = config.getDefaultAliases();
+  const cfg = config.loadConfig();
+  if (cfg && cfg.default === name && !isCurated(name, defaults)) {
+    process.stderr.write(`Error: '${safeFragment(name)}' is your default model (config.default) — pick another default first (amicus setup)\n`);
+    return 1;
+  }
+  let removed;
+  try {
+    removed = removeAlias(name);
+  } catch (err) {
+    process.stderr.write(`Error: ${collapseExcerpt(err.message)}\n`);
+    return 1;
+  }
+  if (!removed) {
+    process.stderr.write(`Error: '${safeFragment(name)}' is not pinned (see: amicus aliases)\n`);
+    return 1;
+  }
+  process.stdout.write(isCurated(name, defaults)
+    ? `✓ ${safeFragment(name)} now follows the shipped recommendation (${defaults[name]})\n`
+    : `✓ ${safeFragment(name)} removed\n`);
+  return 0;
+}
+
+/** @param {object} args parsed CLI args @returns {Promise<number>} exit code */
+async function handleAliases(args) {
+  if (args.review && (args.json || args.quiet)) {
+    process.stderr.write('Error: --review is interactive; use `amicus aliases --json` for machine output\n');
+    return 1;
+  }
+  if (args.unpin !== undefined) {
+    if (args.review || args.json) {
+      process.stderr.write('Error: --unpin cannot be combined with --review or --json\n');
+      return 1;
+    }
+    return handleUnpin(args.unpin);           // handleUnpin trims/validates (R1): true, 42, '', '  ', 'null' all land the same error
+  }
+  if (args.review) { return require('./aliases-review').runReview(args); }
+  const d = loadDeps();
+  const view = await collectAliasView({ maxAgeMs: Number.POSITIVE_INFINITY }, d);
+  if (args.json) {
+    process.stdout.write(JSON.stringify(buildAliasesDoc(view), null, 2) + '\n');
+    return 0;
+  }
+  process.stdout.write(renderAliasList(view, d.groupAliases));
+  return 0;
+}
+
+module.exports = { handleAliases, collectAliasView, renderAliasList, buildAliasesDoc, loadDeps };

package/src/sidecar/models.js

@@ -194,7 +194,7 @@ async function runCheck(args) {
   // empty namespace explains stale/absent aliases downstream, and staying
   // silent about it is the original defect.
   for (const f of providerFailures) { process.stdout.write(fmtProviderFailure(f) + '\n'); }
-  const driftLines = buildFallbackDriftReport(catalog);
+  const driftLines = buildFallbackDriftReport(catalogInfo);
   if (stale.length === 0 && drifted.length === 0) {
     process.stdout.write(`All aliases resolve to catalog models (${sources.length} checked).\n`);
   } else if (stale.length > 0) {
@@ -202,7 +202,11 @@ async function runCheck(args) {
       process.stdout.write(`STALE: ${s.alias} -> ${s.model} (${s.source})\n`);
       if (s.suggestions.length > 0) {
         process.stdout.write(`  candidates: ${s.suggestions.join(', ')}\n`);
-        process.stdout.write(`  fix: amicus setup --add-alias ${s.alias}=${s.suggestions[0]}\n`);
+        // #238 D4: a user-config row is reviewable in the picker; a shipped pin
+        // that went stale can only be pinned OVER until the next release.
+        process.stdout.write(s.source === 'user-config'
+          ? '  fix: amicus aliases --review\n'
+          : `  fix: amicus setup --add-alias ${s.alias}=${s.suggestions[0]}  (pins over the stale shipped default)\n`);
       } else {
         process.stdout.write('  no same-vendor candidates in catalog\n');
       }
@@ -210,7 +214,7 @@ async function runCheck(args) {
   }
   for (const dr of drifted) {
     process.stdout.write(`DRIFTED: ${dr.alias} -> ${dr.stored} (stored; current resolution: ${dr.current})\n`);
-    process.stdout.write(`  stored aliases don't follow catalog updates — refresh: amicus setup --add-alias ${dr.alias}=${dr.current}\n`);
+    process.stdout.write('  stored aliases don\'t follow catalog updates — review: amicus aliases --review\n');
   }
   if (driftLines.length > 0) {
     process.stdout.write('Pinned fallback drift:\n');
@@ -233,12 +237,21 @@ async function runCheck(args) {
 
 /**
  * Non-blocking drift report: pinned family fallbacks vs live resolution.
- * Empty catalog → [] (cannot check). Never affects the exit code.
- * @param {Array<{id:string}>} catalog
+ * Accepts a catalogInfo (`{models, providerFailures}`) or a bare models array
+ * (older callers). Empty catalog → [] (cannot check). #238 §5: when the
+ * openrouter namespace itself was REJECTED this run, the catalog is missing the
+ * rows that make a pin look current, and a drift line computed from it would
+ * propose a downgrade — so the report is empty for that catalog. Never affects
+ * the exit code.
+ * @param {{models: Array<{id:string}>, providerFailures?: Array<{provider:string}>}|Array<{id:string}>} catalogOrInfo
  * @returns {string[]} human-readable warning lines
  */
-function buildFallbackDriftReport(catalog) {
-  if (!catalog || catalog.length === 0) { return []; }
+function buildFallbackDriftReport(catalogOrInfo) {
+  const info = Array.isArray(catalogOrInfo) ? { models: catalogOrInfo } : (catalogOrInfo || { models: [] });
+  const catalog = info.models || [];
+  if (catalog.length === 0) { return []; }
+  const failures = Array.isArray(info.providerFailures) ? info.providerFailures : [];
+  if (failures.some(f => f && f.provider === 'openrouter')) { return []; }
   const lines = [];
   for (const f of getFamilies()) {
     const live = pickCurrent(catalog, 'openrouter/', f.vendorPath, f.idPattern);

package/src/sidecar/setup.js

@@ -42,7 +42,7 @@ function addAlias(name, modelString) {
 /**
  * Ensure a config exists with the chosen default model. Read-modify-write:
  * preserves every pre-existing top-level key (aliases, councils, …) and only
- * fills in the default + any missing default aliases. Never clobbers.
+ * fills in the default — aliases are left untouched (absence follows, #238 Q9).
  * @param {string} defaultModel - Default model alias or full model string
  * @returns {object} The resulting config object
  */
@@ -51,17 +51,12 @@ function createDefaultConfig(defaultModel) {
   const cfg = {
     ...existing,
     default: existing.default || defaultModel,
-    // Same restatement as the readline gate below (fix round 3, G-2): a spread
-    // into `{}` re-materialises Object.prototype. `saveConfig` rebuilds this
-    // into its own literal anyway, so this one is defense in depth rather than
-    // a measured hole — recorded as such rather than claimed as a fix.
-    aliases: { __proto__: null, ...getDefaultAliases(), ...(existing.aliases || {}) },
+    // #238 Q9: no seeding. A curated alias FOLLOWS the shipped pin by being
+    // ABSENT from config.aliases (D1); only what the user chose is written.
+    aliases: { __proto__: null, ...(existing.aliases || {}) },
   };
   saveConfig(cfg);
-  logger.info('Default config ensured', {
-    default: cfg.default,
-    aliasCount: Object.keys(cfg.aliases).length,
-  });
+  logger.info('Default config ensured', { default: cfg.default, aliasCount: Object.keys(cfg.aliases).length });
   return cfg;
 }
 
@@ -524,7 +519,8 @@ async function runReadlineSetup() {
       return;
     }
 
-    const { resolveQuickPicks, toLiveSeedAliases, toStorableRoute } = require('../utils/quick-picks');
+    const { resolveQuickPicks, toStorableRoute } = require('../utils/quick-picks');
+    const { stripGatewayPrefix } = require('../utils/curated-models');
     const picks = resolveQuickPicks(catalog);
 
     console.log('Choose your default model:');
@@ -545,7 +541,7 @@ async function runReadlineSetup() {
     }
 
     // Read-modify-write — never rebuild the alias table (no-clobber rule).
-    const cfg = loadConfig() || { aliases: toLiveSeedAliases({ models: catalog, providerFailures }) };
+    const cfg = loadConfig() || { aliases: {} };
     if (!cfg.aliases) { cfg.aliases = {}; }
     if (chosen.alias) {
       cfg.default = chosen.alias;
@@ -555,11 +551,16 @@ async function runReadlineSetup() {
       // pointing at that alias name is fine (the user's explicit overall-default
       // choice), but the alias's VALUE must stay the vendor phase's tier choice --
       // skip the curated-flagship upgrade so it isn't discarded.
+      // #238 Q9: write the chosen default's LIVE pick only when it differs
+      // from the shipped pin, and say so — a pin the user was told about.
+      // Otherwise leave the key alone: absent = follows (D1).
       if (pick && !chosen.noUpgrade && !vendorAliasesWritten.has(chosen.alias)) {
-        cfg.aliases[chosen.alias] = toStorableRoute(pick, { models: catalog, providerFailures });
-      } else if (cfg.aliases[chosen.alias] === undefined) {
-        const fallback = getDefaultAliases()[chosen.alias];
-        if (fallback !== undefined) { cfg.aliases[chosen.alias] = fallback; }
+        const live = toStorableRoute(pick, { models: catalog, providerFailures });
+        const shipped = getDefaultAliases()[chosen.alias];
+        if (live && stripGatewayPrefix(live) !== stripGatewayPrefix(shipped)) {
+          cfg.aliases[chosen.alias] = live;
+          console.log(`${chosen.alias} → ${live} (live flagship differs from the shipped ${shipped} — pinned)`);
+        }
       }
 
       // #138: offer the family -> model second level. `pick.vendorPath` is
@@ -608,7 +609,7 @@ async function runReadlineSetup() {
           const shortlist = buildModelShortlist(pick.vendorPath, {
             catalog,
             providerFailures,
-            recommendedId: cfg.aliases[chosen.alias],
+            recommendedId: cfg.aliases[chosen.alias] || getDefaultAliases()[chosen.alias],
           });
           const specific = await promptForVendorModel(
             askQuestion.bind(null, rl), console.log, shortlist, pick.vendorPath
@@ -626,7 +627,8 @@ async function runReadlineSetup() {
 
     console.log('');
     console.log(`Default model set to: ${cfg.default}`);
-    console.log(`Config saved (${Object.keys(cfg.aliases).length} aliases).`);
+    const pinned = Object.keys(cfg.aliases).length;
+    console.log(`Config saved (${pinned} pinned alias${pinned === 1 ? '' : 'es'}; the rest follow the shipped recommendations — amicus aliases).`);
     console.log(`Config path: ${path.join(getConfigDir(), 'config.json')}`);
 
     // C8: compact doctor summary, best-effort (see printDoctorFinale).

package/src/utils/alias-groups.js

@@ -0,0 +1,128 @@
+/**
+ * @module utils/alias-groups
+ * Vendor-derived alias grouping (issue 213). Moved VERBATIM out of
+ * `electron/setup-ui-alias-groups.js` (#238 PR1 fix wave F5): `src/` code
+ * (src/sidecar/aliases.js — the CLI `amicus aliases` list) must not require
+ * from `electron/`, a layering violation the whole-branch review caught.
+ * `electron/setup-ui-alias-groups.js` re-exports every symbol here so its
+ * own callers (setup-ui-aliases.js, setup-ui.js) and their tests keep
+ * working untouched.
+ *
+ * REUSE NOTE: the vendor parse is `vendorOf` from src/sidecar/fallback-chains.js
+ * — the existing primitive, imported, not re-implemented. It PARSES a vendor
+ * segment (it never emits an id that gets called), which is the same
+ * ban-exempt category as the other allowlisted `vendorOf` callers in
+ * .eslintrc.js. `groupModelsByFamily` (src/utils/model-fetcher.js) is
+ * deliberately NOT reused: it keys on `id.split('/')[0]`, so every
+ * `openrouter/...` alias would collapse into a single "OpenRouter" bucket —
+ * exactly the grouping this file exists to avoid. Its DISPLAY half
+ * (PROVIDER_FAMILY_NAMES) is reused below.
+ */
+
+'use strict';
+
+const { vendorOf } = require('../sidecar/fallback-chains');
+const { PROVIDER_FAMILY_NAMES, listDirectProviders } = require('./provider-registry');
+
+/**
+ * Display names for vendors seen in alias routes.
+ *
+ * DISPLAY ONLY — deliberately not folded into provider-registry's PROVIDERS,
+ * which is a *capability* registry (env var, direct-vs-gateway, live fetch).
+ * KNOWN_PROVIDERS / PROVIDER_ENV_MAP are derived from that list, so adding
+ * `z-ai` there would claim Amicus can hold a z-ai API key. The five real
+ * providers keep their single source of truth via PROVIDER_FAMILY_NAMES.
+ * Module-private: nothing outside this file requires it directly.
+ */
+const ALIAS_VENDOR_LABELS = {
+  ...PROVIDER_FAMILY_NAMES,
+  // Vendors reachable through the gateway (curated + commonly pinned)
+  'qwen': 'Qwen',
+  'mistralai': 'Mistral AI',
+  'z-ai': 'Z.AI',
+  'minimax': 'MiniMax',
+  'x-ai': 'xAI',
+  'moonshotai': 'Moonshot AI',
+  'bytedance-seed': 'ByteDance Seed',
+  'thinkingmachines': 'Thinking Machines',
+  'cognitivecomputations': 'Cognitive Computations',
+  'inclusionai': 'InclusionAI',
+  'nvidia': 'NVIDIA',
+  'cohere': 'Cohere',
+  'meta-llama': 'Meta Llama',
+  'nousresearch': 'Nous Research',
+  'perplexity': 'Perplexity',
+  'microsoft': 'Microsoft',
+  'ai21': 'AI21',
+  'amazon': 'Amazon',
+  // Local providers (src/utils/local-providers.js PRESETS / VALID_FLAVORS)
+  'ollama': 'Ollama',
+  'lmstudio': 'LM Studio',
+  'vllm': 'vLLM',
+};
+
+/**
+ * `some-new-vendor` -> `Some New Vendor`, so an unmapped vendor is not a raw slug.
+ * @param {string} vendor
+ * @returns {string}
+ */
+function titleCaseVendor(vendor) {
+  return String(vendor).split(/[-_]/).filter(Boolean)
+    .map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+
+/**
+ * Vendor key for an alias route. Wraps the shared `vendorOf` with the two
+ * normalisations issue 213 flagged: case, and the leading `~` of a floating
+ * OpenRouter id (`openrouter/~z-ai/glm-latest` must not form a second group
+ * next to `z-ai`).
+ * @param {string} route @returns {string} '' when there is no usable route
+ */
+function aliasVendorOf(route) {
+  const v = vendorOf(route).toLowerCase();
+  return v.charAt(0) === '~' ? v.slice(1) : v;
+}
+
+/**
+ * Display label for a vendor key.
+ * hasOwnProperty, not a bare lookup: vendor is derived from a user-editable
+ * route, and `__proto__`/`constructor` would otherwise return prototype junk.
+ * @param {string} vendor @returns {string}
+ */
+function vendorLabel(vendor) {
+  if (!vendor) { return 'Other'; }
+  const hit = Object.prototype.hasOwnProperty.call(ALIAS_VENDOR_LABELS, vendor)
+    ? ALIAS_VENDOR_LABELS[vendor] : null;
+  return hit || titleCaseVendor(vendor);
+}
+
+/** Direct-route vendors render first; everything else sorts by label. @type {string[]} */
+const PREFERRED_VENDOR_ORDER = listDirectProviders();
+
+/**
+ * Bucket an alias map by route vendor.
+ * INVARIANT: every own key of `aliases` lands in exactly one returned group —
+ * there is no whitelist to miss, and the empty vendor is a real catch-all.
+ * Order within a group follows the config's own key order.
+ * @param {Object<string,string>} aliases
+ * @returns {Array<{vendor: string, label: string, keys: string[]}>}
+ */
+function groupAliases(aliases) {
+  const byVendor = new Map();
+  for (const key of Object.keys(aliases || {})) {
+    const vendor = aliasVendorOf(aliases[key]);
+    if (!byVendor.has(vendor)) { byVendor.set(vendor, []); }
+    byVendor.get(vendor).push(key);
+  }
+  const rank = (vendor) => {
+    if (!vendor) { return Number.MAX_SAFE_INTEGER; } // catch-all group last
+    const i = PREFERRED_VENDOR_ORDER.indexOf(vendor);
+    return i === -1 ? PREFERRED_VENDOR_ORDER.length : i;
+  };
+  return Array.from(byVendor.entries())
+    .map(([vendor, keys]) => ({ vendor, label: vendorLabel(vendor), keys }))
+    .sort((a, b) => rank(a.vendor) - rank(b.vendor) ||
+      a.label.toLowerCase().localeCompare(b.label.toLowerCase()));
+}
+
+module.exports = { groupAliases, aliasVendorOf, vendorLabel, titleCaseVendor, PREFERRED_VENDOR_ORDER };