Skip to content
Source
Sign inSign up
TanStack/schemas
Open History to see the last commit

index.ts

536 lines16.1 KB

1#!/usr/bin/env bun
2/**
3 * modelschemas CLI (PLAN.md task 7.5) — thin command layer over
4 * @modelschemas/client. `--json` everywhere (default when stdout is not a
5 * TTY) so the CLI is itself agent-friendly.
6 */
7import { readFileSync } from 'node:fs'
8import { parseArgs } from 'node:util'
9import {
10 createModelschemasClient,
11 estimateCost,
12 getModel,
13 getSchema,
14 listChanges,
15 listModels,
16 listProviderSchemas,
17 validatePayload,
18} from '@modelschemas/client'
19​
20import {
21 pull,
22 readManifest,
23 verify,
24 verifyIntegrity,
25} from '@modelschemas/codegen'
26import type { OptionalStyle, PullConfig } from '@modelschemas/codegen'
27​
28import { mintAgentJwt, registerAgent, waitForActivation } from './agent-auth.ts'
29import {
30 credentialsPath,
31 loadCredentials,
32 saveCredentials,
33} from './credentials.ts'
34import type { Credentials } from './credentials.ts'
35​
36const HELP = `modelschemas — live AI model schemas
37​
38Usage: modelschemas <command> [options]
39​
40Commands:
41 login [--name <n>] [--delegated] [--api-key] register this machine
42 whoami show identity, grants, usage
43 models list [--activity a] [--provider p] [--q text]
44 models get <provider> <modelId>
45 schema get <provider> <endpointId> [--kind input|output]
46 validate <provider/endpointId> <file> [--kind input|output]
47 estimate <provider> <model> [body.json] {request?,usage?} or usage object
48 changes [--since <epoch>] [--provider p] [--type t]
49 subscribe <url> [--events e1,e2] [--provider p]
50 pull <selection...> [--out dir] [--no-types] [--optional exact|undefined]
51 generate schema/type modules
52 (e.g. anthropic/v1/messages#request, gemini/*)
53 update [--out dir] refresh pulled modules (selection
54 comes from the manifest)
55 verify [--out dir] verify pulled modules: files match
56 the manifest AND the service still
57 serves bytes matching each pinned
58 content hash (reports provenance)
59​
60Options:
61 --base-url <url> service origin (default: $MODELSCHEMAS_URL or https://modelschemas.com)
62 --json force JSON output (default when piped)
63 -h, --help this help
65​
66interface Ctx {
67 baseUrl: string
68 json: boolean
69 values: Record<string, string | boolean | undefined>
70 positionals: Array<string>
72​
73function output(ctx: Ctx, value: unknown): void {
74 const pretty = !ctx.json && process.stdout.isTTY
75 console.log(JSON.stringify(value, null, pretty ? 2 : 0))
77​
78function fail(message: string): never {
79 console.error(`error: ${message}`)
80 process.exit(1)
82​
83async function authHeader(
84 credentials: Credentials | null,
85): Promise<string | undefined> {
86 if (!credentials) return undefined
87 if (credentials.type === 'api-key') return `Bearer ${credentials.apiKey}`
88 return `Bearer ${await mintAgentJwt(credentials)}`
90​
91function makeClient(ctx: Ctx) {
92 return createModelschemasClient({ baseUrl: ctx.baseUrl })
94​
95async function authedFetch(
96 ctx: Ctx,
97 path: string,
98 init?: RequestInit,
99): Promise<Response> {
100 const header = await authHeader(loadCredentials())
101 return fetch(`${ctx.baseUrl}${path}`, {
102 ...init,
103 headers: {
104 ...(init?.headers ?? {}),
105 ...(header ? { Authorization: header } : {}),
106 ...(init?.body ? { 'Content-Type': 'application/json' } : {}),
107 },
108 })
110​
111async function cmdLogin(ctx: Ctx): Promise<void> {
112 const name = String(ctx.values.name ?? 'modelschemas-cli')
113 if (ctx.values['api-key']) {
114 const response = await fetch(`${ctx.baseUrl}/v1/agents/register-key`, {
115 method: 'POST',
116 headers: { 'Content-Type': 'application/json' },
117 body: JSON.stringify({ name }),
118 })
119 if (!response.ok) fail(`register-key failed: ${await response.text()}`)
120 const body = (await response.json()) as { key: string }
121 const path = saveCredentials({
122 type: 'api-key',
123 baseUrl: ctx.baseUrl,
124 apiKey: body.key,
125 })
126 output(ctx, { ok: true, type: 'api-key', credentials: path })
127 return
128 }
129​
130 const mode = ctx.values.delegated ? 'delegated' : 'autonomous'
131 const registered = await registerAgent(ctx.baseUrl, { name, mode })
132 const credentials: Credentials = {
133 type: 'agent',
134 baseUrl: ctx.baseUrl,
135 ...registered.credentials,
136 }
137 const path = saveCredentials(credentials)
138​
139 if (mode === 'delegated' && registered.status !== 'active') {
140 console.error(
141 `approve this agent: ${registered.approval?.verificationUri ?? 'see your dashboard'}` +
142 (registered.approval?.userCode
143 ? ` (code: ${registered.approval.userCode})`
144 : ''),
145 )
146 const activated = await waitForActivation(
147 ctx.baseUrl,
148 registered.credentials,
149 )
150 if (!activated) fail('approval timed out — re-run login once approved')
151 }
152 output(ctx, {
153 ok: true,
154 type: 'agent',
155 mode,
156 agentId: registered.credentials.agentId,
157 status: registered.status,
158 credentials: path,
159 })
161​
162async function cmdWhoami(ctx: Ctx): Promise<void> {
163 const credentials = loadCredentials()
164 if (!credentials) fail("not logged in — run 'modelschemas login' first")
165 const response = await authedFetch(ctx, '/v1/agents/me')
166 if (!response.ok) fail(`whoami failed: ${await response.text()}`)
167 output(ctx, await response.json())
169​
170async function cmdModels(ctx: Ctx): Promise<void> {
171 const [sub, provider, modelId] = ctx.positionals
172 const client = makeClient(ctx)
173 if (sub === 'get') {
174 if (!provider || !modelId) fail('usage: models get <provider> <modelId>')
175 const result = await getModel({
176 client,
177 path: { provider, modelId },
178 })
179 if (result.error !== undefined) fail(JSON.stringify(result.error))
180 output(ctx, result.data)
181 return
182 }
183 const result = await listModels({
184 client,
185 query: {
186 activity: ctx.values.activity as never,
187 provider: ctx.values.provider as string | undefined,
188 capability: ctx.values.capability as string | undefined,
189 q: ctx.values.q as string | undefined,
190 },
191 })
192 if (result.error !== undefined) fail(JSON.stringify(result.error))
193 output(ctx, result.data)
195​
196async function resolveActivity(
197 ctx: Ctx,
198 provider: string,
199 endpointId: string,
200): Promise<string> {
201 const client = makeClient(ctx)
202 const index = await listProviderSchemas({ client, path: { provider } })
203 if (index.error !== undefined) fail(JSON.stringify(index.error))
204 const activities = (
205 index.data as { activities: Record<string, Array<string>> }
206 ).activities
207 for (const [activity, ids] of Object.entries(activities)) {
208 if (ids.includes(endpointId)) return activity
209 }
210 fail(
211 `endpoint '${endpointId}' not found for ${provider}. Known: ${Object.values(activities).flat().join(', ')}`,
212 )
214​
215async function cmdSchema(ctx: Ctx): Promise<void> {
216 const [sub, provider, endpointId] = ctx.positionals
217 if (sub !== 'get' || !provider || !endpointId) {
218 fail('usage: schema get <provider> <endpointId> [--kind input|output]')
219 }
220 const activity = await resolveActivity(ctx, provider, endpointId)
221 const result = await getSchema({
222 client: makeClient(ctx),
223 path: { provider, activity: activity as never, endpointId },
224 query: { kind: (ctx.values.kind ?? 'input') as never },
225 })
226 if (result.error !== undefined) fail(JSON.stringify(result.error))
227 output(ctx, result.data)
229​
230const isRecord = (value: unknown): value is Record<string, unknown> =>
231 typeof value === 'object' && value !== null && !Array.isArray(value)
232​
233/** `{ request?, usage? }` wrapper, or a bare usage object (SKILL.md). */
234export function estimateBodyFromFile(parsed: unknown): {
235 request?: Record<string, unknown>
236 usage?: Record<string, unknown>
237} | null {
238 if (!isRecord(parsed)) return null
239 if ('request' in parsed || 'usage' in parsed) {
240 if (parsed.request !== undefined && !isRecord(parsed.request)) return null
241 if (parsed.usage !== undefined && !isRecord(parsed.usage)) return null
242 return {
243 request: parsed.request,
244 usage: parsed.usage,
245 }
246 }
247 return { usage: parsed }
249​
250async function cmdEstimate(ctx: Ctx): Promise<void> {
251 const [provider, model, file] = ctx.positionals
252 if (!provider || !model) {
253 fail('usage: estimate <provider> <model> [body.json]')
254 }
255 let extra: {
256 request?: Record<string, unknown>
257 usage?: Record<string, unknown>
258 } = {}
259 if (file) {
260 let parsed: unknown
261 try {
262 parsed = JSON.parse(readFileSync(file, 'utf8'))
263 } catch (error) {
264 fail(`could not read body file: ${String(error)}`)
265 }
266 const body = estimateBodyFromFile(parsed)
267 if (!body) {
268 fail(
269 'body file must be a JSON object { request?, usage? } or a usage object',
270 )
271 }
272 extra = body
273 }
274 const result = await estimateCost({
275 client: makeClient(ctx),
276 body: {
277 provider,
278 model,
279 request: extra.request,
280 usage: extra.usage,
281 },
282 })
283 if (result.error !== undefined) fail(JSON.stringify(result.error))
284 output(ctx, result.data)
286​
287async function cmdValidate(ctx: Ctx): Promise<void> {
288 const [target, file] = ctx.positionals
289 if (!target?.includes('/') || !file) {
290 fail('usage: validate <provider/endpointId> <payload.json>')
291 }
292 const slash = target.indexOf('/')
293 const provider = target.slice(0, slash)
294 const endpointId = target.slice(slash + 1)
295 let payload: unknown
296 try {
297 payload = JSON.parse(readFileSync(file, 'utf8'))
298 } catch (error) {
299 fail(`could not read payload file: ${String(error)}`)
300 }
301 const result = await validatePayload({
302 client: makeClient(ctx),
303 body: {
304 provider,
305 endpointId,
306 kind: ctx.values.kind as never,
307 payload,
308 },
309 })
310 if (result.error !== undefined) fail(JSON.stringify(result.error))
311 const verdict = result.data as { valid: boolean }
312 output(ctx, result.data)
313 // Agent-friendly: invalid payloads exit non-zero.
314 if (!verdict.valid) process.exit(2)
316​
317async function cmdChanges(ctx: Ctx): Promise<void> {
318 const result = await listChanges({
319 client: makeClient(ctx),
320 query: {
321 since: ctx.values.since ? Number(ctx.values.since) : undefined,
322 provider: ctx.values.provider as string | undefined,
323 type: ctx.values.type as never,
324 },
325 })
326 if (result.error !== undefined) fail(JSON.stringify(result.error))
327 output(ctx, result.data)
329​
330async function cmdSubscribe(ctx: Ctx): Promise<void> {
331 const [url] = ctx.positionals
332 if (!url) fail('usage: subscribe <url> [--events e1,e2] [--provider p]')
333 const events = String(ctx.values.events ?? 'model.added,model.removed')
334 .split(',')
335 .map((event) => event.trim())
336 const response = await authedFetch(ctx, '/v1/subscriptions', {
337 method: 'POST',
338 body: JSON.stringify({
339 url,
340 events,
341 provider: ctx.values.provider as string | undefined,
342 }),
343 })
344 if (!response.ok) fail(`subscribe failed: ${await response.text()}`)
345 output(ctx, await response.json())
347​
348export interface PullFlags {
349 outDir: string
350 types: boolean
351 optionalStyle: OptionalStyle | undefined
353​
354/** Shared flag parsing for `pull`/`update` — exported for tests. */
355export function parsePullFlags(
356 values: Record<string, string | boolean | undefined>,
357): PullFlags {
358 const optional = values.optional
359 if (
360 optional !== undefined &&
361 optional !== 'exact' &&
362 optional !== 'undefined'
363 ) {
364 fail(`invalid --optional '${String(optional)}' — use exact or undefined`)
365 }
366 return {
367 outDir: typeof values.out === 'string' ? values.out : 'src/modelschemas',
368 types: values['no-types'] !== true,
369 optionalStyle: optional,
370 }
372​
373function pullApiKey(): string | undefined {
374 if (process.env.MODELSCHEMAS_API_KEY !== undefined) {
375 return process.env.MODELSCHEMAS_API_KEY
376 }
377 const credentials = loadCredentials()
378 return credentials?.type === 'api-key' ? credentials.apiKey : undefined
380​
381async function runPull(ctx: Ctx, config: PullConfig): Promise<void> {
382 const summary = await pull(config)
383 output(ctx, summary)
384 if (summary.failed.length > 0) process.exit(1)
386​
387async function cmdPull(ctx: Ctx): Promise<void> {
388 if (ctx.positionals.length === 0) {
389 fail(
390 'usage: pull <selection...> [--out dir] [--no-types] [--optional exact|undefined]',
391 )
392 }
393 const flags = parsePullFlags(ctx.values)
394 await runPull(ctx, {
395 baseUrl: ctx.baseUrl,
396 apiKey: pullApiKey(),
397 outDir: flags.outDir,
398 selections: ctx.positionals,
399 types: flags.types,
400 optionalStyle: flags.optionalStyle,
401 log: (message) => console.error(message),
402 })
404​
405async function cmdUpdate(ctx: Ctx): Promise<void> {
406 const flags = parsePullFlags(ctx.values)
407 const manifest = await readManifest(flags.outDir)
408 if (manifest === null) {
409 fail(
410 `no ${flags.outDir}/.manifest.json — run 'modelschemas pull <selection...>' first`,
411 )
412 }
413 await runPull(ctx, {
414 // Explicit --base-url wins; otherwise refresh from where we pulled.
415 baseUrl:
416 typeof ctx.values['base-url'] === 'string'
417 ? ctx.baseUrl
418 : manifest.baseUrl,
419 apiKey: pullApiKey(),
420 outDir: flags.outDir,
421 selections: manifest.selections,
422 types: manifest.types,
423 optionalStyle: manifest.optionalStyle,
424 log: (message) => console.error(message),
425 })
427​
428async function cmdVerify(ctx: Ctx): Promise<void> {
429 const flags = parsePullFlags(ctx.values)
430 const manifest = await readManifest(flags.outDir)
431 if (manifest === null) {
432 fail(
433 `no ${flags.outDir}/.manifest.json — run 'modelschemas pull <selection...>' first`,
434 )
435 }
436 const config = {
437 // Explicit --base-url wins; otherwise verify against where we pulled.
438 baseUrl:
439 typeof ctx.values['base-url'] === 'string'
440 ? ctx.baseUrl
441 : manifest.baseUrl,
442 apiKey: pullApiKey(),
443 outDir: flags.outDir,
444 selections: manifest.selections,
445 log: (message: string) => console.error(message),
446 }
447 const files = await verify(config)
448 const integrity = await verifyIntegrity(config)
449 const ok = files.ok && integrity.ok
450 output(ctx, { ok, files, integrity })
451 if (!ok) process.exit(2)
453​
454async function main(): Promise<void> {
455 const { values, positionals } = parseArgs({
456 args: process.argv.slice(2),
457 allowPositionals: true,
458 options: {
459 'base-url': { type: 'string' },
460 json: { type: 'boolean' },
461 help: { type: 'boolean', short: 'h' },
462 name: { type: 'string' },
463 delegated: { type: 'boolean' },
464 'api-key': { type: 'boolean' },
465 activity: { type: 'string' },
466 provider: { type: 'string' },
467 capability: { type: 'string' },
468 q: { type: 'string' },
469 kind: { type: 'string' },
470 since: { type: 'string' },
471 type: { type: 'string' },
472 events: { type: 'string' },
473 out: { type: 'string' },
474 'no-types': { type: 'boolean' },
475 optional: { type: 'string' },
476 },
477 })
478​
479 const [command, ...rest] = positionals
480 if (values.help || !command) {
481 console.log(HELP)
482 process.exit(command ? 0 : 1)
483 }
484​
485 const stored = loadCredentials()
486 const ctx: Ctx = {
487 baseUrl:
488 values['base-url'] ??
489 process.env.MODELSCHEMAS_URL ??
490 stored?.baseUrl ??
491 'https://modelschemas.com',
492 json: values.json ?? !process.stdout.isTTY,
493 values,
494 positionals: rest,
495 }
496​
497 switch (command) {
498 case 'login':
499 return cmdLogin(ctx)
500 case 'whoami':
501 return cmdWhoami(ctx)
502 case 'models':
503 return cmdModels(ctx)
504 case 'schema':
505 return cmdSchema(ctx)
506 case 'validate':
507 return cmdValidate(ctx)
508 case 'estimate':
509 return cmdEstimate(ctx)
510 case 'changes':
511 return cmdChanges(ctx)
512 case 'subscribe':
513 return cmdSubscribe(ctx)
514 case 'pull':
515 return cmdPull(ctx)
516 case 'update':
517 return cmdUpdate(ctx)
518 case 'verify':
519 return cmdVerify(ctx)
520 default:
521 fail(`unknown command '${command}'.\n${HELP}`)
522 }
524​
525// Only run when executed as the bin — not when imported (e.g. by tests).
526if (import.meta.main) {
527 main().catch((error: unknown) => {
528 console.error(
529 `error: ${error instanceof Error ? error.message : String(error)}`,
530 )
531 process.exit(1)
532 })
534​
535// Referenced for help/tests; credentialsPath is part of the public surface.
536export { credentialsPath, HELP }