mohdel 0.125.0 → 1.0.0

package/src/cli/doctor.js

@@ -3,7 +3,7 @@ import { label, meta, ok, warn, err, inactive } from './colors.js'
 import providers from '../lib/providers.js'
 import { validate, isValidTag } from '../lib/schema.js'
 import {
-  CONFIG_DIR, CURATED_PATH, CONFIG_PATH, ENV_PATH,
+  CONFIG_DIR, CURATED_PATH, CONFIG_PATH, ENV_PATH, tildePath,
   getCuratedModels, getConfig, loadDefaultEnv, getAPIKey, catalogEntries
 } from '../lib/common.js'
 
@@ -11,11 +11,15 @@ const row = (status, name, detail = '') =>
   `  ${status}  ${name.padEnd(20)} ${meta(detail)}`
 
 export async function runDoctor (args) {
+  const all = args.includes('--all')
   if (args.includes('-h') || args.includes('--help')) {
     console.log(`mohdel doctor — check that your install is wired up
 
 Usage:
-  mo doctor [--json]
+  mo doctor [--all] [--json]
+
+Options:
+  --all      List every provider's API key variable, set or not
 
 What it checks:
   - Config directory and environment file exist
@@ -45,9 +49,10 @@ Exit code:
 
   // 1. Config dir + env file
   report.configDir.ok = existsSync(CONFIG_DIR)
+  report.assistant = (await getConfig()).assistant || null
   report.envFile.ok = existsSync(ENV_PATH)
   if (!report.configDir.ok) report.warnings.push('config directory does not exist (will be created on first save)')
-  if (!report.envFile.ok) report.warnings.push(`no ${ENV_PATH} — set API keys there or via shell env`)
+  if (!report.envFile.ok) report.warnings.push(`no ${tildePath(ENV_PATH)} — set API keys there or via shell env`)
 
   // 2. API keys per provider
   for (const [name, def] of Object.entries(providers)) {
@@ -70,6 +75,9 @@ Exit code:
     const entries = catalogEntries(curated)
     report.curatedFile.active = entries.filter(([, s]) => !s.deprecated).length
     report.curatedFile.deprecated = entries.length - report.curatedFile.active
+    if (report.curatedFile.active === 0) {
+      report.warnings.push('catalog is empty — "mo curate <provider>" adds a provider\'s models, then "mo model instructions <provider>" fills in the prices')
+    }
 
     // Schema validation (same logic as 'mo check', condensed)
     const knownProviders = new Set(Object.keys(providers))
@@ -126,13 +134,15 @@ Exit code:
   }
 
   // Pretty output
-  console.log(label('Mohdel doctor\n'))
+  console.log(label('mohdel doctor\n'))
 
   console.log(label('Configuration'))
-  console.log(row(report.configDir.ok ? ok('✓') : warn('!'), 'Config dir', report.configDir.path))
-  console.log(row(report.envFile.ok ? ok('✓') : warn('!'), 'Env file', report.envFile.ok ? report.envFile.path : `${report.envFile.path} (missing)`))
+  console.log(row(report.configDir.ok ? ok('✓') : warn('!'), 'Config dir', tildePath(report.configDir.path)))
+  if (report.assistant) console.log(row(ok('✓'), 'Coding agent', report.assistant))
+  console.log(row(report.envFile.ok ? ok('✓') : warn('!'), 'Env file', report.envFile.ok ? tildePath(report.envFile.path) : `${tildePath(report.envFile.path)} (missing)`))
   if (report.curatedFile.ok) {
-    console.log(row(ok('✓'), 'curated.json', `${report.curatedFile.active} active, ${report.curatedFile.deprecated} deprecated`))
+    const mark = report.curatedFile.active === 0 ? warn('!') : ok('✓')
+    console.log(row(mark, 'curated.json', `${report.curatedFile.active} active, ${report.curatedFile.deprecated} deprecated`))
   } else {
     console.log(row(err('✗'), 'curated.json', 'failed to load'))
   }
@@ -142,13 +152,22 @@ Exit code:
   for (const k of report.keys.configured) {
     console.log(row(ok('✓'), k.provider, k.envVar))
   }
-  for (const k of report.keys.missing) {
-    console.log(row(inactive('○'), k.provider, `${k.envVar} (unset)`))
+  // A row per unset provider is a dozen lines of nothing on a fresh install,
+  // but the variable names are what you came for when a key isn't picked up.
+  if (all) {
+    for (const k of report.keys.missing) {
+      console.log(row(inactive('○'), k.provider, `${k.envVar} (unset)`))
+    }
+  } else if (report.keys.missing.length) {
+    console.log(row(inactive('○'), `${report.keys.missing.length} unset`,
+      meta('"mo providers" lists them, "mo doctor --all" their variables')))
   }
 
   console.log()
   console.log(label('Catalog validation'))
-  if (report.schema.errors.length) {
+  if (report.curatedFile.ok && report.curatedFile.active === 0 && report.curatedFile.deprecated === 0) {
+    console.log(`  ${inactive('○')} nothing to validate`)
+  } else if (report.schema.errors.length) {
     console.log(`  ${err('✗')} ${report.schema.errors.length} error(s) ${meta('— run "mo check" for details')}`)
   } else {
     console.log(`  ${ok('✓')} no errors`)
@@ -171,11 +190,11 @@ Exit code:
   if (report.errors.length) {
     console.log(`${err('✗')} ${report.errors.length} error(s):`)
     for (const e of report.errors) console.log(`  ${err('✗')} ${e}`)
-    process.exit(1)
-  } else if (report.warnings.length) {
+  }
+  if (report.warnings.length) {
     console.log(`${warn('!')} ${report.warnings.length} warning(s) — install is usable but not fully configured`)
     for (const w of report.warnings) console.log(`  ${warn('!')} ${w}`)
-  } else {
-    console.log(`${ok('✓')} ready`)
   }
+  if (report.errors.length) process.exit(1)
+  if (!report.warnings.length) console.log(`${ok('✓')} ready`)
 }

package/src/cli/entry.js

@@ -0,0 +1,173 @@
+import { readFile, rm } from 'node:fs/promises'
+import { CURATED_PATH, getCuratedModels, saveCuratedModels, tildePath } from '../lib/common.js'
+import { parseCandidates, reviewCandidates } from '../lib/catalog-review.js'
+import { localConventionsOrExit } from './local.js'
+import { id, label, meta, err, warn, ok } from './colors.js'
+
+const readStdin = async () => {
+  const chunks = []
+  for await (const chunk of process.stdin) chunks.push(chunk)
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+const readCandidateFile = async (path) => {
+  if (path === '-') return readStdin()
+  return readFile(path, 'utf8')
+}
+
+const show = (value) => JSON.stringify(value)
+
+const renderChange = ({ field, from, to }) => {
+  const name = field.padEnd(22)
+  if (from === undefined) return `  ${ok('+')} ${name} ${show(to)}`
+  if (to === undefined) return `  ${err('-')} ${name} ${show(from)} ${meta('→ (removed)')}`
+  return `  ${warn('~')} ${name} ${show(from)} ${meta('→')} ${show(to)}`
+}
+
+export const printReview = (reviews, ignored) => {
+  for (const key of ignored) {
+    console.log(meta(`skipping meta key ${key}`))
+  }
+  for (const review of reviews) {
+    console.log(`\n${id(review.key)}  ${label(review.status)}`)
+    for (const change of review.changes) console.log(renderChange(change))
+    for (const e of review.errors) console.log(`  ${err('✗')} ${e}`)
+    for (const w of review.warnings) console.log(`  ${warn('!')} ${w}`)
+  }
+}
+
+export const summarize = (reviews) => ({
+  candidates: reviews.length,
+  new: reviews.filter(r => r.status === 'new').length,
+  changed: reviews.filter(r => r.status === 'changed').length,
+  unchanged: reviews.filter(r => r.status === 'unchanged').length,
+  errors: reviews.reduce((n, r) => n + r.errors.length, 0),
+  warnings: reviews.reduce((n, r) => n + r.warnings.length, 0)
+})
+
+const printSummary = (counts) => {
+  const parts = [`${counts.new} new`, `${counts.changed} changed`, `${counts.unchanged} unchanged`]
+  console.log(`\n${label(`${counts.candidates} candidate(s):`)} ${parts.join(', ')}  ${meta('│')}  ` +
+    `${counts.errors ? err(`${counts.errors} error(s)`) : ok('0 errors')}, ${counts.warnings} warning(s)`)
+}
+
+const loadReview = async (path) => {
+  const { entries, ignored } = parseCandidates(await readCandidateFile(path))
+  const curated = await getCuratedModels()
+  const local = await localConventionsOrExit()
+  return { curated, entries, ignored, reviews: reviewCandidates(curated, entries, { local }) }
+}
+
+export async function runCheckEntry (args) {
+  const path = args[args.indexOf('--entry') + 1]
+  if (!path) {
+    console.error('Usage: mo model check --entry <file|->')
+    process.exit(1)
+  }
+  const json = args.includes('--json')
+
+  let review
+  try {
+    review = await loadReview(path)
+  } catch (e) {
+    if (json) console.log(JSON.stringify({ error: e.message }, null, 2))
+    else console.error(err(e.message))
+    process.exit(1)
+  }
+
+  const counts = summarize(review.reviews)
+  if (json) {
+    console.log(JSON.stringify({ counts, ignored: review.ignored, candidates: review.reviews }, null, 2))
+  } else {
+    printReview(review.reviews, review.ignored)
+    printSummary(counts)
+    if (!counts.errors) {
+      console.log(`${meta('Next:')}  mo model apply ${path === '-' ? '<file>' : path}`)
+    }
+  }
+  if (counts.errors) process.exit(1)
+}
+
+export async function runApply (args) {
+  if (args.includes('-h') || args.includes('--help')) {
+    console.log(`mohdel model apply — write reviewed catalog entries
+
+Usage:
+  model apply <file|-> [--yes] [--rm]
+
+Reads entries in curated.json shape, validates them, prints the diff
+against ${tildePath(CURATED_PATH)}, and writes after confirmation. Nothing is
+written when validation reports an error.
+
+The candidate file is left alone unless you say otherwise — at a terminal
+it asks, and --rm removes it without asking. Undo uses the catalog's own
+backups, not the candidate.
+
+Options:
+  --yes    Skip the confirmation prompt
+  --rm     Delete the candidate file once it has been applied
+
+Write an entry with your coding agent: mo model instructions <provider>`)
+    process.exit(0)
+  }
+
+  const path = args.find(a => !a.startsWith('--'))
+  if (!path) {
+    console.error('Usage: mo model apply <file|-> [--yes] [--rm]')
+    process.exit(1)
+  }
+
+  let review
+  try {
+    review = await loadReview(path)
+  } catch (e) {
+    console.error(err(e.message))
+    process.exit(1)
+  }
+
+  const counts = summarize(review.reviews)
+  printReview(review.reviews, review.ignored)
+  printSummary(counts)
+
+  if (counts.errors) {
+    console.error(`\n${err('Not written')} — fix the errors above and run again.`)
+    process.exit(1)
+  }
+  const nothingToDo = !counts.new && !counts.changed
+  if (nothingToDo) console.log(`\n${ok('Nothing to write')} — the catalog already matches.`)
+
+  if (!nothingToDo && !args.includes('--yes')) {
+    if (!process.stdout.isTTY || path === '-') {
+      console.error(`\n${err('Not written')} — no terminal to confirm on. Re-run in a terminal, or pass --yes.`)
+      process.exit(1)
+    }
+    const { confirm, isCancel } = await import('@clack/prompts')
+    const go = await confirm({ message: `Write ${counts.new + counts.changed} entry(ies) to ${tildePath(CURATED_PATH)}?` })
+    if (isCancel(go) || !go) {
+      console.log(meta('Not written.'))
+      return
+    }
+  }
+
+  if (!nothingToDo) {
+    await saveCuratedModels({ ...review.curated, ...review.entries })
+    console.log(`${ok('✓')} ${counts.new + counts.changed} entry(ies) written to ${tildePath(CURATED_PATH)}`)
+    console.log(`${meta('Undo:')}  mo model backup diff prev  ${meta('│')}  mo model backup restore prev`)
+  }
+
+  // The candidate was written by the agent, not by mohdel, so it is never
+  // removed unasked. It has served its purpose though, and the catalog's own
+  // backups are what an undo uses — not this file.
+  if (path === '-') return
+  if (args.includes('--rm')) {
+    await rm(path, { force: true })
+    console.log(`${ok('✓')} removed ${path}`)
+    return
+  }
+  if (!process.stdout.isTTY) return
+  const { confirm, isCancel } = await import('@clack/prompts')
+  const drop = await confirm({ message: `Delete ${path}?`, initialValue: false })
+  if (isCancel(drop) || !drop) return
+  await rm(path, { force: true })
+  console.log(`${ok('✓')} removed ${path}`)
+}

package/src/cli/index.js

@@ -9,6 +9,10 @@
  * Aliases: ls → model list, rl → ratelimit
  */
 
+import { detectAssistants, launchLines } from '../lib/assistants.js'
+import { getConfig } from '../lib/common.js'
+import { ALIASES } from './aliases.js'
+
 const [command, ...args] = process.argv.slice(2)
 
 if (!command) {
@@ -17,38 +21,65 @@ if (!command) {
   process.exit(0)
 }
 
+// Before anything else: a tab press must not pay for the factory import.
+if (command === '__complete') {
+  const { runComplete } = await import('./complete.js')
+  await runComplete(args)
+  process.exit(0)
+}
+
+if (command === 'completion') {
+  const { runCompletionScript } = await import('./complete.js')
+  runCompletionScript(args)
+  process.exit(0)
+}
+
 if (command === '-h' || command === '--help') {
-  console.log(`mohdel — model catalog management
+  const assistant = (await getConfig()).assistant || null
+  const { default: PROVIDER_INFO } = await import('../lib/provider-info.js')
+  const { default: providerDefs } = await import('../lib/providers.js')
+  const keyRows = Object.keys(PROVIDER_INFO)
+    .map(name => [providerDefs[name].apiKeyEnv, `${PROVIDER_INFO[name].label} API key`])
+    .concat([['MOHDEL_LOCAL_API_SK', 'Bearer token for a local server, if it wants one']])
+  const keyWidth = Math.max(...keyRows.map(([k]) => k.length))
+  const keys = keyRows.map(([k, d]) => `  ${k.padEnd(keyWidth + 2)}${d}`).join('\n')
+  console.log(`mohdel — self-hosted LLM gateway and SDK for Node
+
+Run a model, see what the call cost, and curate the catalog those prices
+come from. Your keys, your infra, no SaaS in the path.
 
 Commands:
-  model list [--sort price|context|name]  List all curated models
-  model search <term>                     Filter models by name/label
-  model stats                             Catalog summary
-  model show <model>                      Show model details
+  model list [--sort price|context|name]  List all curated models                 (mo ls, mo models)
+  model search <term>                     Filter models by name/label             (mo search)
+  model stats                             Catalog summary                         (mo stats)
+  model show <model>                      Show model details                      (mo show)
   model get <model> <key>                 Get a field value
   model set <model> <key> <value>         Set a field
   model rm <model> <key>                  Remove a field
   model add <provider>/<model-id>         Add a model manually
-  model check [--local]                   Validate catalog
-  model rank [--use-case <name>]          Rank models by benchmarks
-  model bench <model>                     Benchmark with live inference
-  model curate [provider]                 Add upstream models to catalog
-
-  provider list                           List all providers
-  provider list <provider>                List models from a provider
-  provider setup <provider>               Configure API key (interactive)
+  model instructions [provider]           Brief for your coding agent             (mo instructions)
+  model check [--entry <file|->]          Validate catalog, or candidate entries  (mo check)
+  model apply <file|->                    Write reviewed entries to the catalog   (mo apply)
+  model rank [--use-case <name>]          Rank models by benchmarks               (mo rank)
+  model bench <model>                     Benchmark with live inference           (mo bench)
+  model curate [provider]                 Add upstream models to catalog          (mo curate)
+
+  provider list                           List all providers                      (mo providers)
+  provider list <provider>                List curated models for a provider
+  provider models <provider>              List models the key can reach upstream
+  provider setup <provider>               Configure API key (interactive)         (mo setup)
   provider rm <provider>                  Remove API key
 
-  creator list                            List all creators
+  creator list                            List all creators                       (mo creators)
   creator list <creator>                  List models by a creator
 
-  tag list                                List all unique tags
+  tag list                                List all unique tags                    (mo tags)
   tag list <model>                        Show tags on a model
   tag show <tag>                          List models with a tag
   tag add <model> <tag>                   Add a tag
   tag rm <model> <tag>                    Remove a tag
 
-  ratelimit show <model|provider>         Show effective limits
+  ratelimit show <model|provider>         Show effective limits                   (mo rl show)
   ratelimit set <model> [rpm] [tpm]       Set model-level limits
   ratelimit rm <model>                    Remove model-level limits
   ratelimit provider set <p> [rpm] [tpm]  Set provider-level limits
@@ -57,24 +88,30 @@ Commands:
   ask <provider/model> [prompt]           One-shot inference (pipeable)
   transcribe <provider/model> <file>      Speech → text from an audio file
 
-  default                                 Set default model (interactive)
+  default [model]                         Set the model "mo ask" uses by default
   doctor                                  Check that your install is wired up
+  completion bash                         Shell completion — source <(mo completion bash)
+
+Catalog work with a coding agent:
+  Prices, context limits and cache rates are in no provider API — they live on
+  docs pages. Put the brief in front of the coding agent you already use:
 
-Aliases:
-  models                model list
-  providers             provider list
-  creators              creator list
-  tags                  tag list
-  ls                    model list
-  show <model>          model show <model>
-  search <term>         model search <term>
-  stats                 model stats
-  check                 model check
-  setup <provider>      provider setup <provider>
-  rank                  model rank
-  bench <model>         model bench <model>
-  curate [provider]     model curate [provider]
-  rl                    ratelimit
+    mo model instructions openai > mohdel-brief.md
+
+  then start it on <prompt>:
+
+     read mohdel-brief.md, then add gpt-5.6 to my mohdel catalog
+
+${launchLines(detectAssistants(), assistant).join('\n')}
+
+  The agent needs to be able to fetch a web page — that is where the prices
+  are. It drafts mohdel-candidate.json and checks it; you apply it:
+
+    mo model check --entry mohdel-candidate.json
+    mo model apply mohdel-candidate.json     ← prints the diff first
+
+Aliases appear in brackets above. "mo rl" stands in for "mo ratelimit" on
+every subcommand, not only its list form.
 
 Global flags:
   --json [fields]       Output as JSON (omit fields to list available)
@@ -83,51 +120,25 @@ Environment:
   API keys are loaded from ~/.config/mohdel/environment (KEY=value format).
   Run "mo" with no arguments to configure interactively.
 
-  ANTHROPIC_API_SK      Anthropic API key
-  OPENAI_API_SK         OpenAI API key
-  GEMINI_API_SK         Google Gemini API key
-  GROQ_API_SK           Groq API key
-  CEREBRAS_API_SK       Cerebras API key
-  XAI_API_SK            xAI API key
-  MISTRAL_API_SK        Mistral API key
-  DEEPSEEK_API_SK       DeepSeek API key
-  FIREWORKS_API_SK      Fireworks API key
-  OPENROUTER_API_SK     OpenRouter API key
-  NOVITA_API_SK         Novita API key
+${keys}
 
 Configuration:
-  ~/.config/mohdel/environment      API keys (loaded automatically)
-  ~/.config/mohdel/curated.json     Model catalog
-  ~/.config/mohdel/providers.json   Provider-level rate limits
-  ~/.config/mohdel/default.json     Default model selection`)
+  ~/.config/mohdel/environment        API keys (loaded automatically)
+  ~/.config/mohdel/curated.json       Model catalog
+  ~/.config/mohdel/catalog.local.json This installation's own fields and tags
+  ~/.config/mohdel/providers.json     Provider-level rate limits
+  ~/.config/mohdel/excluded.json      Models to hide from list and curate
+  ~/.config/mohdel/default.json       Default model, and your coding agent`)
   process.exit(0)
 }
 
-// Alias resolution: short commands → noun + verb
-const ALIASES = {
-  models: { noun: 'model', inject: ['list'] },
-  providers: { noun: 'provider', inject: ['list'] },
-  creators: { noun: 'creator', inject: ['list'] },
-  tags: { noun: 'tag', inject: ['list'] },
-  ls: { noun: 'model', inject: ['list'] },
-  show: { noun: 'model', inject: ['show'] },
-  search: { noun: 'model', inject: ['search'] },
-  stats: { noun: 'model', inject: ['stats'] },
-  check: { noun: 'model', inject: ['check'] },
-  setup: { noun: 'provider', inject: ['setup'] },
-  rank: { noun: 'model', inject: ['rank'] },
-  bench: { noun: 'model', inject: ['bench'] },
-  curate: { noun: 'model', inject: ['curate'] },
-  rl: { noun: 'ratelimit', inject: [] }
-}
-
 const alias = ALIASES[command]
 const resolved = alias ? alias.noun : command
 const resolvedArgs = alias ? [...alias.inject, ...args] : args
 
 if (resolved === 'default') {
   const { runDefault } = await import('./default.js')
-  await runDefault()
+  await runDefault(resolvedArgs)
 } else if (resolved === 'doctor') {
   const { runDoctor } = await import('./doctor.js')
   await runDoctor(resolvedArgs)