mohdel 0.124.0 → 1.0.0

package/src/cli/complete.js

@@ -0,0 +1,130 @@
+import providerDefs from '../lib/providers.js'
+import { fieldDefs } from '../lib/schema.js'
+import { getCuratedModels, catalogEntries } from '../lib/common.js'
+import { ALIASES } from './aliases.js'
+
+// Completion must never import the factory (`src/lib/index.js`), which pulls
+// every adapter, provider SDK and the OTel stack — 350ms that would be paid on
+// every press of the tab key. Reading the catalog costs about 30ms.
+
+const NOUNS = ['model', 'provider', 'creator', 'tag', 'ratelimit', 'ask', 'transcribe', 'default', 'doctor']
+
+const VERBS = {
+  model: ['list', 'search', 'stats', 'show', 'get', 'set', 'rm', 'add', 'instructions',
+    'check', 'apply', 'rank', 'bench', 'curate', 'backup'],
+  provider: ['list', 'show', 'models', 'setup', 'rm'],
+  creator: ['list', 'show'],
+  tag: ['list', 'show', 'add', 'rm'],
+  ratelimit: ['show', 'set', 'rm', 'provider']
+}
+
+// What the argument at a given offset after `<noun> <verb>` names. `model` is
+// an id already in the catalog, so `model add` — which takes a new one — is
+// deliberately absent.
+const ARGUMENT = {
+  ask: ['model'],
+  transcribe: ['model'],
+  'model show': ['model'],
+  'model get': ['model', 'field'],
+  'model set': ['model', 'field'],
+  'model rm': ['model', 'field'],
+  'model bench': ['model'],
+  'model curate': ['provider'],
+  'model instructions': ['provider'],
+  'provider list': ['provider'],
+  'provider show': ['provider'],
+  'provider models': ['provider'],
+  'provider setup': ['provider'],
+  'provider rm': ['provider'],
+  'creator show': ['creator'],
+  'tag list': ['model'],
+  'tag show': ['tag'],
+  'tag add': ['model', 'tag'],
+  'tag rm': ['model', 'tag'],
+  'ratelimit show': ['model'],
+  'ratelimit set': ['model'],
+  'ratelimit rm': ['model']
+}
+
+const fromCatalog = async (pick) => {
+  const catalog = await getCuratedModels()
+  const out = new Set()
+  for (const [key, spec] of catalogEntries(catalog)) {
+    if (spec.deprecated) continue
+    pick(key, spec, out)
+  }
+  return [...out]
+}
+
+const kinds = {
+  model: () => fromCatalog((key, _spec, out) => out.add(key)),
+  creator: () => fromCatalog((_key, spec, out) => spec.creator && out.add(spec.creator)),
+  tag: () => fromCatalog((_key, spec, out) => (spec.tags || []).forEach(t => out.add(t))),
+  provider: async () => Object.keys(providerDefs),
+  field: async () => Object.keys(fieldDefs)
+}
+
+/**
+ * @param {number} cword  Index of the word being completed (bash COMP_CWORD).
+ * @param {string[]} words  The full command line, split (bash COMP_WORDS).
+ * @returns {Promise<string[]>}
+ */
+export const candidates = async (cword, words) => {
+  const current = words[cword] ?? ''
+  const before = words.slice(1, cword).filter(w => !w.startsWith('-'))
+
+  const offer = (list) => list.filter(c => c.startsWith(current)).sort()
+
+  if (!before.length) {
+    return offer([...NOUNS, ...Object.keys(ALIASES)])
+  }
+
+  // Resolve the alias exactly as the router does, so completion and dispatch
+  // never disagree about what a word means.
+  const alias = ALIASES[before[0]]
+  const chain = alias ? [alias.noun, ...alias.inject, ...before.slice(1)] : before
+  const [noun, verb, ...rest] = chain
+
+  if (chain.length === 1 && VERBS[noun]) return offer(VERBS[noun])
+
+  // `model show <id>` keys on two words; `ask <id>` on one. Whichever matched
+  // decides where the argument list starts.
+  const paired = ARGUMENT[`${noun} ${verb}`]
+  const shape = paired ?? ARGUMENT[noun]
+  if (!shape) return []
+  const typed = paired ? rest : [verb, ...rest].filter(Boolean)
+
+  const kind = shape[typed.length]
+  if (!kind || !kinds[kind]) return []
+  return offer(await kinds[kind]())
+}
+
+export const BASH_SCRIPT = `# mohdel completion for bash.  Add to ~/.bashrc:
+#   source <(mo completion bash)
+_mo_completion() {
+  local IFS=$'\\n'
+  COMPREPLY=($(mo __complete "$COMP_CWORD" "\${COMP_WORDS[@]}" 2>/dev/null))
+}
+complete -o default -F _mo_completion mo
+`
+
+export async function runComplete (args) {
+  // A crash here would break the user's tab key, so an unreadable or corrupt
+  // catalog offers nothing rather than an error.
+  try {
+    const cword = Number.parseInt(args[0], 10)
+    if (!Number.isFinite(cword)) return
+    const list = await candidates(cword, args.slice(1))
+    if (list.length) process.stdout.write(`${list.join('\n')}\n`)
+  } catch {}
+}
+
+export function runCompletionScript (args) {
+  const shell = args[0]
+  if (shell === 'bash') {
+    process.stdout.write(BASH_SCRIPT)
+    return
+  }
+  console.error(`Usage: mo completion bash${shell ? `  (got "${shell}")` : ''}`)
+  process.exit(1)
+}

package/src/cli/default.js

@@ -1,11 +1,37 @@
 import { intro, outro, select, isCancel, cancel } from '@clack/prompts'
-import { getCuratedModels, CONFIG_PATH, saveConfig, catalogEntries } from '../lib/common.js'
-import providers from '../lib/providers.js'
+import { getConfig, getCuratedModels, saveConfig, catalogEntries } from '../lib/common.js'
 
-export async function runDefault () {
-  intro('Mohdel — Set Default Model')
+// CLI-only. The default model is a convenience for someone typing `mo ask`;
+// the library and the gate never read it. A program picks a model by id or by
+// tag, where the choice is explicit and reviewable — a machine inheriting a
+// human's terminal preference is how a call ends up on a model nobody chose.
+export async function runDefault (args = []) {
+  if (args.includes('-h') || args.includes('--help')) {
+    console.log(`mohdel default — the model "mo ask" uses when you name none
+
+Usage:
+  default                Pick one from your catalog (interactive)
+  default <model>        Set it directly
+
+Stored in ~/.config/mohdel/default.json. The library and the gate never
+read it: a program names its model, or selects one by tag.`)
+    process.exit(0)
+  }
 
   const curated = await getCuratedModels()
+
+  const named = args.find(a => !a.startsWith('-'))
+  if (named) {
+    if (!curated[named] || curated[named].deprecated) {
+      console.error(`'${named}' is not a model in your catalog. "mo ls" lists them.`)
+      process.exit(1)
+    }
+    await saveConfig({ ...(await getConfig()), defaultModel: named })
+    console.log(`Default set to ${named} — "mo ask" uses it when you give no model.`)
+    return
+  }
+
+  intro('mohdel — set the default model')
   const modelOptions = catalogEntries(curated).map(([modelId, info]) => ({
     value: modelId,
     label: `${info.label} (${modelId})`
@@ -22,16 +48,11 @@ export async function runDefault () {
     process.exit(0)
   }
 
-  const [providerName] = selectedModelId.split('/')
-
   try {
-    const config = { defaultModel: selectedModelId }
-    const apiKeyEnv = providers[providerName]?.apiKeyEnv
-    if (apiKeyEnv) {
-      config.apiKeyInfo = `Set ${apiKeyEnv} environment variable for this provider`
-    }
-    await saveConfig(config)
-    outro(`Default set to ${selectedModelId} — saved to ${CONFIG_PATH}`)
+    // Merge: the file also holds the chosen coding agent, and replacing the
+    // object wholesale would drop it.
+    await saveConfig({ ...(await getConfig()), defaultModel: selectedModelId })
+    outro(`Default set to ${selectedModelId} — "mo ask" uses it when you give no model.`)
   } catch (err) {
     cancel(`Error: ${err.message}`)
     process.exit(1)

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}`)
+}