@wevion/cli 1.0.2

package/src/index.mjs

@@ -0,0 +1,524 @@
+#!/usr/bin/env node
+// Wevion CLI — a generic, spec-driven driver over the public OpenAPI spec.
+// It ships a frozen openapi.json snapshot (refreshed by CI on every prod
+// release) and turns every operation into a subcommand at runtime. No codegen.
+//
+//   wevion <command> [--param value ...]
+//   wevion list                 # list all commands
+//   wevion help <command>       # show a command's params
+//
+// Auth: WEVION_API_KEY (x-api-key). Base URL: WEVION_BASE_URL or --base-url.
+
+import { parseArgs } from 'node:util'
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { homedir } from 'node:os'
+import { createInterface } from 'node:readline/promises'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete']
+const JSON_CONTENT_TYPE = 'application/json'
+const SUPPORTED_AUTH_SCHEMES = new Set(['apiKeyAuth'])
+// ponytail: hardcoded prod default; stage via --base-url / WEVION_BASE_URL / config.
+const DEFAULT_BASE_URL = 'https://api.wevion.ai'
+const DEFAULT_TIMEOUT_MS = 30_000
+
+// ~/.config/wevion/config.json (honours XDG_CONFIG_HOME). Stores { apiKey, baseUrl }.
+export function configPath(env = process.env, platform = process.platform) {
+  if (platform === 'win32') {
+    const base = env.APPDATA || join(env.USERPROFILE || env.HOME || homedir(), 'AppData', 'Roaming')
+    return join(base, 'Wevion', 'config.json')
+  }
+  const base = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), '.config')
+  return join(base, 'wevion', 'config.json')
+}
+
+function readConfig() {
+  const p = configPath()
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'))
+  } catch (err) {
+    if (err?.code === 'ENOENT') {
+      return {}
+    }
+    throw new Error(`cannot read ${p}: ${err.message}`)
+  }
+}
+
+function writeConfig(config) {
+  const p = configPath()
+  const dir = dirname(p)
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  try {
+    chmodSync(dir, 0o700)
+  } catch {
+    /* best effort on platforms without POSIX modes */
+  }
+  const tmp = `${p}.${process.pid}.tmp`
+  try {
+    writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 })
+    renameSync(tmp, p)
+    try {
+      chmodSync(p, 0o600)
+    } catch {
+      /* best effort on platforms without POSIX modes */
+    }
+  } catch (err) {
+    try {
+      rmSync(tmp, { force: true })
+    } catch {
+      /* ignore cleanup failure */
+    }
+    throw err
+  }
+  return p
+}
+
+async function readHiddenLine(prompt) {
+  if (!process.stdin.isTTY || !process.stdin.setRawMode) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr })
+    try {
+      return await rl.question(prompt)
+    } finally {
+      rl.close()
+    }
+  }
+
+  process.stderr.write(prompt)
+  process.stdin.setRawMode(true)
+  process.stdin.resume()
+  process.stdin.setEncoding('utf8')
+  let value = ''
+  try {
+    for await (const chunk of process.stdin) {
+      for (const ch of chunk) {
+        if (ch === '\u0003') {
+          throw new Error('cancelled')
+        }
+        if (ch === '\r' || ch === '\n') {
+          process.stderr.write('\n')
+          return value
+        }
+        if (ch === '\u007f' || ch === '\b') {
+          value = value.slice(0, -1)
+          continue
+        }
+        value += ch
+      }
+    }
+    return value
+  } finally {
+    process.stdin.setRawMode(false)
+    process.stdin.pause()
+  }
+}
+
+export function resolveApiKey(env, config) {
+  return env.WEVION_API_KEY || config.apiKey || null
+}
+
+async function login(rest) {
+  const { values } = parseArgs({
+    args: rest,
+    options: { 'api-key': { type: 'string' }, 'base-url': { type: 'string' } },
+    allowPositionals: false,
+  })
+  let apiKey = values['api-key']
+  if (!apiKey && !process.stdin.isTTY) apiKey = readFileSync(0, 'utf8').trim() // piped in
+  if (!apiKey) {
+    apiKey = (await readHiddenLine('Wevion API key: ')).trim()
+  }
+  if (!apiKey) return fail('no API key provided')
+  const cfg = readConfig()
+  cfg.apiKey = apiKey
+  if (values['base-url']) cfg.baseUrl = values['base-url']
+  const p = writeConfig(cfg)
+  process.stderr.write(`saved credentials to ${p}\n`)
+  return 0
+}
+
+function logout() {
+  const p = configPath()
+  try {
+    rmSync(p)
+  } catch (err) {
+    if (err?.code !== 'ENOENT') {
+      return fail(`cannot remove ${p}: ${err.message}`)
+    }
+  }
+  if (process.env.WEVION_API_KEY) {
+    process.stderr.write('warning: WEVION_API_KEY is still set in the environment\n')
+  }
+  process.stderr.write('logged out\n')
+  return 0
+}
+
+export function kebab(s) {
+  return s
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[_\s]+/g, '-')
+    .toLowerCase()
+}
+
+function resolveRef(spec, schema, seen = new Set()) {
+  if (!schema?.$ref) return schema
+  if (!schema.$ref.startsWith('#/')) return schema
+  if (seen.has(schema.$ref)) return schema
+  seen.add(schema.$ref)
+  const resolved = schema.$ref
+    .slice(2)
+    .split('/')
+    .reduce((node, part) => node?.[part.replace(/~1/g, '/').replace(/~0/g, '~')], spec)
+  return resolveRef(spec, resolved || schema, seen)
+}
+
+function mergeObjectSchemas(spec, schema) {
+  const resolved = resolveRef(spec, schema)
+  if (!resolved) return undefined
+  if (Array.isArray(resolved.allOf)) {
+    const parts = resolved.allOf.map((item) => mergeObjectSchemas(spec, item)).filter(Boolean)
+    return {
+      ...resolved,
+      properties: Object.assign({}, ...parts.map((part) => part.properties || {}), resolved.properties || {}),
+      required: [...new Set(parts.flatMap((part) => part.required || []).concat(resolved.required || []))],
+    }
+  }
+  return resolved
+}
+
+function jsonBodySchema(spec, requestBody) {
+  return mergeObjectSchemas(spec, requestBody?.content?.[JSON_CONTENT_TYPE]?.schema)
+}
+
+function supportedAuth(security) {
+  if (!Array.isArray(security) || security.length === 0) return false
+  return security.some((requirement) =>
+    Object.keys(requirement || {}).some((scheme) => SUPPORTED_AUTH_SCHEMES.has(scheme)),
+  )
+}
+
+function bodyFieldsFor(bodyProps, params) {
+  const used = new Set(['base-url', 'json'])
+  for (const p of params) {
+    if (p.in === 'path' || p.in === 'query' || p.in === 'header') used.add(p.name)
+  }
+  return Object.entries(bodyProps).map(([name, schema]) => {
+    let flag = name
+    if (used.has(flag)) flag = `body-${name}`
+    while (used.has(flag)) flag = `body-${flag}`
+    used.add(flag)
+    return { name, flag, schema }
+  })
+}
+
+// Flatten an OpenAPI spec into a map of command-id -> operation descriptor.
+export function listOperations(spec) {
+  const ops = new Map()
+  for (const [path, item] of Object.entries(spec.paths || {})) {
+    for (const method of HTTP_METHODS) {
+      const op = item?.[method]
+      if (!op) continue
+      const id = kebab(op.operationId || `${method}-${path}`)
+      const bodySchema = jsonBodySchema(spec, op.requestBody)
+      const params = op.parameters || []
+      const bodyProps = bodySchema?.properties || {}
+      const hasUnsupportedBody = Boolean(op.requestBody && !op.requestBody.content?.[JSON_CONTENT_TYPE])
+      const security = op.security ?? spec.security ?? []
+      if (!supportedAuth(security)) continue
+      ops.set(id, {
+        id,
+        method: method.toUpperCase(),
+        path,
+        summary: op.summary || '',
+        tags: op.tags || [],
+        security,
+        supportedAuth: true,
+        unsupported: hasUnsupportedBody ? 'request body media type is not supported; use a JSON endpoint' : null,
+        params, // {name, in: path|query|header, required, schema}
+        bodyProps,
+        bodyFields: bodyFieldsFor(bodyProps, params),
+        bodyRequired: bodySchema?.required || [],
+      })
+    }
+  }
+  return ops
+}
+
+// Build a parseArgs `options` config from an operation's inputs. Everything is
+// a string flag; the backend validates types and reports 400 on mismatch.
+function buildParseOptions(op) {
+  const options = { 'base-url': { type: 'string' }, json: { type: 'string' } }
+  for (const p of op.params) {
+    if (p.in === 'path' || p.in === 'query' || p.in === 'header') {
+      options[p.name] = { type: 'string', multiple: p.schema?.type === 'array' }
+    }
+  }
+  for (const field of op.bodyFields) options[field.flag] = { type: 'string' }
+  return options
+}
+
+function valuesForSchema(value, schema) {
+  if (value == null) return []
+  const values = Array.isArray(value) ? value : [value]
+  if (schema?.type === 'array') {
+    return values.flatMap((item) => {
+      const trimmed = String(item).trim()
+      if (trimmed.startsWith('[')) {
+        const parsed = JSON.parse(trimmed)
+        if (!Array.isArray(parsed)) throw new Error('expected a JSON array')
+        return parsed.map(String)
+      }
+      return String(item)
+        .split(',')
+        .map((part) => part.trim())
+        .filter(Boolean)
+    })
+  }
+  return values.map(String)
+}
+
+function coerceValue(value, schema) {
+  const type = schema?.type
+  if (type === 'array' || type === 'object') {
+    return JSON.parse(value)
+  }
+  if (type === 'integer' || type === 'number') {
+    const n = Number(value)
+    if (!Number.isFinite(n)) throw new Error(`expected ${type}`)
+    if (type === 'integer' && !Number.isInteger(n)) throw new Error('expected integer')
+    return n
+  }
+  if (type === 'boolean') {
+    if (value === 'true') return true
+    if (value === 'false') return false
+    throw new Error('expected boolean true or false')
+  }
+  if (!type && /^[\[{]|^-?\d+(?:\.\d+)?$|^(?:true|false|null)$/.test(String(value).trim())) {
+    return JSON.parse(value)
+  }
+  return value
+}
+
+// Assemble the HTTP request from parsed flag values. Throws on missing required inputs.
+export function buildRequest(op, values, baseUrl) {
+  if (op.unsupported) throw new Error(op.unsupported)
+  if (!op.supportedAuth) throw new Error('operation uses an unsupported auth scheme')
+  let path = op.path
+  const query = new URLSearchParams()
+  const headers = {}
+  for (const p of op.params) {
+    const v = values[p.name]
+    if (p.in === 'path') {
+      if (v == null) throw new Error(`missing required path param --${p.name}`)
+      path = path.replace(`{${p.name}}`, encodeURIComponent(v))
+    } else if (p.in === 'query' && v != null) {
+      for (const item of valuesForSchema(v, p.schema)) query.append(p.name, item)
+    } else if (p.in === 'header' && v != null) {
+      headers[p.name] = valuesForSchema(v, p.schema).join(',')
+    } else if (p.required && v == null && (p.in === 'query' || p.in === 'header')) {
+      throw new Error(`missing required ${p.in} param --${p.name}`)
+    }
+  }
+  const qs = query.toString()
+  const url = `${baseUrl.replace(/\/$/, '')}${path}${qs ? `?${qs}` : ''}`
+
+  let body
+  if (values.json != null) {
+    const parsed = JSON.parse(values.json)
+    for (const name of op.bodyRequired) {
+      if (!parsed || typeof parsed !== 'object' || !(name in parsed)) {
+        throw new Error(`missing required body field --${name}`)
+      }
+    }
+    body = values.json // raw JSON passthrough for the whole body
+  } else if (op.bodyFields.length) {
+    const obj = {}
+    for (const field of op.bodyFields) {
+      if (op.bodyRequired.includes(field.name) && values[field.flag] == null) {
+        throw new Error(`missing required body field --${field.flag}`)
+      }
+    }
+    for (const field of op.bodyFields) {
+      if (values[field.flag] != null) {
+        try {
+          obj[field.name] = coerceValue(values[field.flag], field.schema)
+        } catch (err) {
+          throw new Error(`invalid --${field.flag}: ${err.message}`)
+        }
+      }
+    }
+    if (Object.keys(obj).length) body = JSON.stringify(obj)
+  }
+  return { url, method: op.method, headers, body }
+}
+
+function validateSpec(spec, source) {
+  if (!spec || typeof spec !== 'object' || !/^3\./.test(String(spec.openapi || '')) || !spec.paths) {
+    throw new Error(`${source} is not a valid OpenAPI 3 spec`)
+  }
+  return spec
+}
+
+function loadSpec(baseUrl) {
+  // Prefer the bundled snapshot (offline help, reproducible per release).
+  const bundled = join(dirname(fileURLToPath(import.meta.url)), '..', 'openapi.json')
+  try {
+    return { spec: validateSpec(JSON.parse(readFileSync(bundled, 'utf8')), bundled), source: 'bundled' }
+  } catch (err) {
+    if (existsSync(bundled)) throw err
+    return { source: 'remote', url: `${baseUrl.replace(/\/$/, '')}/docs/json` }
+  }
+}
+
+function timeoutMs(env = process.env) {
+  const parsed = Number(env.WEVION_TIMEOUT_MS)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_TIMEOUT_MS
+}
+
+function signalFromEnv(env = process.env) {
+  return AbortSignal.timeout(timeoutMs(env))
+}
+
+function resolveBaseUrl(argv, config, env = process.env) {
+  const globalOptions = { 'base-url': { type: 'string' } }
+  try {
+    const { values } = parseArgs({
+      args: argv,
+      options: globalOptions,
+      allowPositionals: true,
+      strict: false,
+    })
+    return values['base-url'] || env.WEVION_BASE_URL || config.baseUrl || DEFAULT_BASE_URL
+  } catch {
+    return env.WEVION_BASE_URL || config.baseUrl || DEFAULT_BASE_URL
+  }
+}
+
+function printList(ops) {
+  const byTag = new Map()
+  for (const op of ops.values()) {
+    const tag = op.tags[0] || 'other'
+    if (!byTag.has(tag)) byTag.set(tag, [])
+    byTag.get(tag).push(op)
+  }
+  for (const [tag, list] of [...byTag].sort()) {
+    process.stdout.write(`\n${tag}\n`)
+    for (const op of list.sort((a, b) => a.id.localeCompare(b.id))) {
+      process.stdout.write(`  ${op.id.padEnd(40)} ${op.summary}\n`)
+    }
+  }
+}
+
+function printHelp(op) {
+  if (op.unsupported) process.stdout.write(`Unsupported: ${op.unsupported}\n\n`)
+  process.stdout.write(`${op.method} ${op.path}\n${op.summary}\n\nFlags:\n`)
+  for (const p of op.params) {
+    if (p.in === 'path' || p.in === 'query' || p.in === 'header') {
+      const repeats = p.schema?.type === 'array' ? '  repeat or comma-list' : ''
+      process.stdout.write(`  --${p.name}${p.required ? ' (required)' : ''}${repeats}\n`)
+    }
+  }
+  for (const field of op.bodyFields) {
+    const source = field.flag === field.name ? '' : `  [body: ${field.name}]`
+    process.stdout.write(`  --${field.flag}${op.bodyRequired.includes(field.name) ? ' (required)' : ''}  [body]${source}\n`)
+  }
+  process.stdout.write(`  --json '<raw json>'  send raw request body\n`)
+}
+
+async function main(argv) {
+  const [cmd, ...rest] = argv
+
+  if (cmd === 'login') return login(rest)
+  if (cmd === 'logout') return logout()
+
+  const config = readConfig()
+  const baseUrl = resolveBaseUrl(argv, config)
+
+  const loaded = loadSpec(baseUrl)
+  const spec =
+    loaded.spec ||
+    (await fetch(loaded.url, { signal: signalFromEnv() }).then((r) => {
+      if (!r.ok) throw new Error(`cannot fetch spec from ${loaded.url}: ${r.status}`)
+      return r.json().then((json) => validateSpec(json, loaded.url))
+    }))
+  const ops = listOperations(spec)
+
+  if (!cmd || cmd === 'list' || cmd === '--help' || cmd === '-h') {
+    process.stdout.write(`Wevion CLI — ${ops.size} commands (${loaded.source} spec)\n`)
+    printList(ops)
+    process.stdout.write(`\nUsage: wevion <command> [--param value ...]\n`)
+    process.stdout.write(`       wevion login | logout | help <command>\n`)
+    return 0
+  }
+  if (cmd === 'help') {
+    const op = ops.get(rest[0])
+    if (!op) return fail(`unknown command: ${rest[0] || '(none)'}`)
+    printHelp(op)
+    return 0
+  }
+
+  const op = ops.get(cmd)
+  if (!op) return fail(`unknown command: ${cmd} (try "wevion list")`)
+
+  const { values } = parseArgs({
+    args: rest,
+    options: buildParseOptions(op),
+    allowPositionals: false,
+  })
+
+  const apiKey = resolveApiKey(process.env, config)
+  if (!apiKey) return fail('no API key — run "wevion login" or set WEVION_API_KEY')
+
+  const req = buildRequest(op, values, values['base-url'] || baseUrl)
+  const res = await fetch(req.url, {
+    method: req.method,
+    headers: {
+      ...req.headers,
+      'x-api-key': apiKey,
+      ...(req.body ? { 'content-type': 'application/json' } : {}),
+    },
+    body: req.body,
+    signal: signalFromEnv(),
+  })
+  const text = await res.text()
+  if (!res.ok) {
+    process.stderr.write(`${req.method} ${req.url} -> ${res.status}\n`)
+    if (text) process.stderr.write(text.endsWith('\n') ? text : text + '\n')
+    return 1
+  }
+  process.stdout.write(text.endsWith('\n') ? text : text + '\n')
+  return 0
+}
+
+function fail(msg) {
+  process.stderr.write(`error: ${msg}\n`)
+  return 2
+}
+
+function isExecutedAsBin() {
+  if (!process.argv[1]) return false
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(process.argv[1])
+  } catch {
+    return false
+  }
+}
+
+// Run only when executed as a bin, not when imported by selftest.
+if (isExecutedAsBin()) {
+  main(process.argv.slice(2))
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      process.stderr.write(`error: ${err.message}\n`)
+      process.exit(1)
+    })
+}