omnara 0.6.0 → 1.0.0-beta.0

package/src/factory.ts

@@ -0,0 +1,396 @@
+import type { OmnaraClient } from '@omnara/sdk'
+import { type Command, InvalidArgumentError } from 'commander'
+import * as z from 'zod'
+
+import { type CliConfig, updateConfigFile } from './config.ts'
+import { deriveFlags, type FlagSpec, kebabCase } from './flags.ts'
+import type { OutputFormat } from './format.ts'
+import {
+  canPromptInteractively,
+  promptOrgSelection,
+  promptProjectSelection,
+} from './interactive.ts'
+import { CliInputError, renderResult, runCliAction } from './output.ts'
+import { createFlowReporter, type FlowReporter } from './reporter.ts'
+
+type SdkOperation = (options: never) => Promise<{ data?: unknown }>
+
+type ResponseOf<F extends SdkOperation> = F extends (options: never) => PromiseLike<infer R>
+  ? R extends { data?: infer D }
+    ? Exclude<D, undefined>
+    : never
+  : never
+
+export interface OperationSpec<Response = never, ParsedBody = never> {
+  type: 'op'
+  verb: string
+  summary: string
+  fn: SdkOperation
+  path?: z.ZodObject<z.ZodRawShape>
+  query?: z.ZodObject<z.ZodRawShape>
+  body?: z.ZodType
+  transformBody?: (body: ParsedBody) => unknown
+  positional?: string[]
+  format: OutputFormat<Response>
+}
+
+export interface FlowContext<Path, Body> {
+  client: OmnaraClient
+  path: Path
+  body: Body
+  report: FlowReporter
+}
+
+interface FlowInput {
+  client: OmnaraClient
+  path: Record<string, unknown>
+  body: unknown
+  report: FlowReporter
+}
+
+export interface FlowSpec {
+  type: 'flow'
+  verb: string
+  summary: string
+  aliases?: string[]
+  path: z.ZodObject<z.ZodRawShape>
+  body: z.ZodType
+  execute: (input: FlowInput) => Promise<void>
+}
+
+export type CommandSpec = OperationSpec | FlowSpec
+
+export interface CommandGroup {
+  name: string
+  summary: string
+  aliases?: string[]
+  operations?: CommandSpec[]
+  groups?: CommandGroup[]
+}
+
+export function op<F extends SdkOperation, B extends z.ZodType = z.ZodNever>(
+  spec: Omit<OperationSpec<ResponseOf<F>, z.output<B>>, 'type' | 'fn' | 'body'> & {
+    fn: F
+    body?: B
+  },
+): OperationSpec {
+  return { ...spec, type: 'op' }
+}
+
+export function flowOp<P extends z.ZodObject<z.ZodRawShape>, B extends z.ZodType>(spec: {
+  verb: string
+  summary: string
+  aliases?: string[]
+  path: P
+  body: B
+  run: (context: FlowContext<z.output<P>, z.output<B>>) => Promise<void>
+}): FlowSpec {
+  const { run, ...base } = spec
+  return {
+    ...base,
+    type: 'flow',
+    execute: (input) =>
+      run({
+        client: input.client,
+        path: parseWithSchema(spec.path, input.path, 'arguments'),
+        body: parseWithSchema(spec.body, input.body, 'flags'),
+        report: input.report,
+      }),
+  }
+}
+
+interface ConfigParam {
+  key: string
+  option: string
+  optionKey: string
+  configKey: 'org_id' | 'project_id'
+  describe: string
+  resolve: (config: CliConfig, path: Record<string, unknown>) => string | undefined
+  prompt: (client: OmnaraClient, path: Record<string, unknown>) => Promise<string>
+}
+
+const CONFIG_PARAMS: ConfigParam[] = [
+  {
+    key: 'orgID',
+    option: '--org <org-id>',
+    optionKey: 'org',
+    configKey: 'org_id',
+    describe: 'pass --org or set OMNARA_ORG_ID',
+    resolve: (config) => config.defaultOrgId,
+    prompt: (client) => promptOrgSelection(client),
+  },
+  {
+    key: 'projectID',
+    option: '--project <project-id>',
+    optionKey: 'project',
+    configKey: 'project_id',
+    describe: 'pass --project or set OMNARA_PROJECT_ID',
+    resolve: (config, path) =>
+      path.orgID === undefined || path.orgID === config.defaultOrgId
+        ? config.defaultProjectId
+        : undefined,
+    prompt: (client, path) => {
+      const orgId = path.orgID
+      if (typeof orgId !== 'string') {
+        throw new CliInputError('cannot select a project before an organization is set')
+      }
+      return promptProjectSelection(client, orgId)
+    },
+  },
+]
+
+function parseJsonFlag(raw: string): unknown {
+  try {
+    const parsed: unknown = JSON.parse(raw)
+    return parsed
+  } catch {
+    throw new InvalidArgumentError('expects valid JSON')
+  }
+}
+
+const NUMBER_PATTERN = /^-?\d+(\.\d+)?([eE][+-]?\d+)?$/
+
+function parseNumberFlag(raw: string): number {
+  if (!NUMBER_PATTERN.test(raw.trim())) {
+    throw new InvalidArgumentError('expects a number')
+  }
+  return Number(raw)
+}
+
+function registerFlag(command: Command, spec: FlagSpec): void {
+  const required = spec.required ? ' (required)' : ''
+  const description = `${spec.description}${required}`
+  switch (spec.kind) {
+    case 'boolean':
+      command.option(`--${spec.flag}`, description)
+      command.option(`--no-${spec.flag}`, `set ${spec.flag} to false`)
+      break
+    case 'number':
+      command.option(`--${spec.flag} <number>`, description, parseNumberFlag)
+      break
+    case 'stringArray':
+      command.option(
+        `--${spec.flag} <value>`,
+        description,
+        (value: string, previous: string[] | undefined) => [...(previous ?? []), value],
+      )
+      break
+    case 'json':
+      command.option(`--${spec.flag} <json>`, description, parseJsonFlag)
+      break
+    default:
+      command.option(`--${spec.flag} <value>`, description)
+  }
+}
+
+function collectFlagValues(
+  specs: FlagSpec[],
+  options: Record<string, unknown>,
+): Record<string, unknown> {
+  const root: Record<string, unknown> = {}
+  const containers = new Map<string, Record<string, unknown>>()
+  const containerFor = (path: readonly string[]): Record<string, unknown> => {
+    const name = path[path.length - 1]
+    if (name === undefined) return root
+    const pathKey = path.join('.')
+    let container = containers.get(pathKey)
+    if (container === undefined) {
+      container = {}
+      containers.set(pathKey, container)
+      containerFor(path.slice(0, -1))[name] = container
+    }
+    return container
+  }
+  for (const spec of specs) {
+    const value = options[spec.optionKey]
+    const name = spec.path[spec.path.length - 1]
+    if (value === undefined || name === undefined) continue
+    containerFor(spec.path.slice(0, -1))[name] = value
+  }
+  return root
+}
+
+function parseWithSchema<S extends z.ZodType>(
+  schema: S,
+  value: unknown,
+  label: string,
+): z.output<S> {
+  const result = schema.safeParse(value)
+  if (!result.success) {
+    throw new CliInputError(`invalid ${label}:\n${z.prettifyError(result.error)}`)
+  }
+  return result.data
+}
+
+interface CallInput {
+  client: OmnaraClient
+  path?: Record<string, unknown>
+  query?: Record<string, unknown>
+  body?: unknown
+}
+
+async function callOperation(spec: OperationSpec, input: CallInput): Promise<unknown> {
+  const result = await spec.fn(input as never)
+  return result.data
+}
+
+const zBodyObject = z.looseObject({})
+
+function deepMerge(
+  base: Record<string, unknown>,
+  patch: Record<string, unknown>,
+): Record<string, unknown> {
+  const merged = { ...base }
+  for (const [key, value] of Object.entries(patch)) {
+    const existing = zBodyObject.safeParse(merged[key])
+    const incoming = zBodyObject.safeParse(value)
+    merged[key] =
+      existing.success && incoming.success ? deepMerge(existing.data, incoming.data) : value
+  }
+  return merged
+}
+
+function saveConfigDefault(configKey: 'org_id' | 'project_id', value: string): void {
+  try {
+    updateConfigFile(
+      configKey === 'org_id' ? { org_id: value, project_id: undefined } : { [configKey]: value },
+    )
+    console.error(`saved ${configKey}=${value} as your default (change with omnara config)`)
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    console.error(`warning: could not save ${configKey} as your default: ${reason}`)
+  }
+}
+
+interface PathPlan {
+  positionalParams: string[]
+  configParams: ConfigParam[]
+}
+
+function planPathParams(
+  path: z.ZodObject<z.ZodRawShape> | undefined,
+  positional: string[],
+): PathPlan {
+  const pathParams = path ? Object.keys(path.shape) : []
+  const configParams = CONFIG_PARAMS.filter(
+    (param) => pathParams.includes(param.key) && !positional.includes(param.key),
+  )
+  return {
+    positionalParams: pathParams.filter((name) => !configParams.some((param) => param.key === name)),
+    configParams,
+  }
+}
+
+function registerPathParams(command: Command, plan: PathPlan): void {
+  for (const param of plan.positionalParams) command.argument(`<${kebabCase(param)}>`)
+  for (const param of plan.configParams) {
+    command.option(param.option, `defaults from config (${param.describe})`)
+  }
+}
+
+async function resolvePathValues(
+  plan: PathPlan,
+  args: string[],
+  options: Record<string, unknown>,
+  config: CliConfig,
+): Promise<Record<string, unknown>> {
+  const path: Record<string, unknown> = {}
+  plan.positionalParams.forEach((param, index) => {
+    path[param] = args[index]
+  })
+  let usedExplicitOverride = false
+  for (const param of plan.configParams) {
+    const explicitOption = options[param.optionKey]
+    const explicit = typeof explicitOption === 'string' ? explicitOption : undefined
+    usedExplicitOverride = usedExplicitOverride || explicit !== undefined
+    let value = explicit ?? param.resolve(config, path)
+    if (value === undefined && canPromptInteractively()) {
+      value = await param.prompt(config.client, path)
+      if (!usedExplicitOverride) saveConfigDefault(param.configKey, value)
+    }
+    if (value === undefined) {
+      throw new CliInputError(`missing ${param.optionKey}: ${param.describe}`)
+    }
+    path[param.key] = value
+  }
+  return path
+}
+
+export function registerOperation(parent: Command, config: CliConfig, spec: OperationSpec): void {
+  const command = parent.command(spec.verb).description(spec.summary)
+  const plan = planPathParams(spec.path, spec.positional ?? [])
+  registerPathParams(command, plan)
+  const queryFlags = spec.query ? deriveFlags(spec.query) : []
+  const bodyFlags = spec.body ? deriveFlags(spec.body) : []
+  for (const flag of [...queryFlags, ...bodyFlags]) registerFlag(command, flag)
+  if (spec.body) {
+    command.option(
+      '--body <json>',
+      'full request body as JSON; field flags override it',
+      parseJsonFlag,
+    )
+  }
+  command.option('--json', 'print the raw JSON response')
+  command.action(async (...args: string[]) => {
+    await runCliAction(async () => {
+      const options = command.opts<Record<string, unknown>>()
+      const input: CallInput = { client: config.client }
+      if (spec.path) {
+        const path = await resolvePathValues(plan, args, options, config)
+        input.path = parseWithSchema(spec.path, path, 'arguments')
+      }
+      if (spec.query) {
+        const query = collectFlagValues(queryFlags, options)
+        input.query = parseWithSchema(spec.query, query, 'query flags')
+      }
+      if (spec.body) {
+        const base =
+          options.body === undefined ? {} : parseWithSchema(zBodyObject, options.body, '--body')
+        const body = deepMerge(base, collectFlagValues(bodyFlags, options))
+        const parsed = parseWithSchema(spec.body, body, 'request body')
+        input.body = spec.transformBody ? await spec.transformBody(parsed as never) : parsed
+      }
+      const data = await callOperation(spec, input)
+      if (options.json === true) {
+        renderResult(data, true)
+        return
+      }
+      const formatted = spec.format(data as never)
+      renderResult(formatted.value, false, { columns: formatted.columns })
+    })
+  })
+}
+
+function registerFlow(parent: Command, config: CliConfig, spec: FlowSpec): void {
+  const command = parent
+    .command(spec.verb)
+    .aliases(spec.aliases ?? [])
+    .description(spec.summary)
+  const plan = planPathParams(spec.path, [])
+  registerPathParams(command, plan)
+  const bodyFlags = deriveFlags(spec.body)
+  for (const flag of bodyFlags) registerFlag(command, flag)
+  command.action(async (...args: string[]) => {
+    await runCliAction(async () => {
+      const options = command.opts<Record<string, unknown>>()
+      await spec.execute({
+        client: config.client,
+        path: await resolvePathValues(plan, args, options, config),
+        body: collectFlagValues(bodyFlags, options),
+        report: createFlowReporter(spec.summary),
+      })
+    })
+  })
+}
+
+export function registerGroup(program: Command, config: CliConfig, group: CommandGroup): void {
+  const groupCommand = program
+    .command(group.name)
+    .aliases(group.aliases ?? [])
+    .description(group.summary)
+  for (const spec of group.operations ?? []) {
+    if (spec.type === 'op') registerOperation(groupCommand, config, spec)
+    else registerFlow(groupCommand, config, spec)
+  }
+  for (const subgroup of group.groups ?? []) registerGroup(groupCommand, config, subgroup)
+}

package/src/flags.ts

@@ -0,0 +1,174 @@
+import * as z from 'zod'
+
+export type FlagValueKind = 'string' | 'number' | 'boolean' | 'json' | 'stringArray'
+
+export interface FlagSpec {
+  path: string[]
+  flag: string
+  optionKey: string
+  kind: FlagValueKind
+  required: boolean
+  description: string
+}
+
+type JsonSchema = z.core.JSONSchema.BaseSchema
+
+export function kebabCase(name: string): string {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replaceAll('_', '-')
+    .toLowerCase()
+}
+
+function camelCase(flag: string): string {
+  return flag.replace(/-(\w)/g, (_, letter: string) => letter.toUpperCase())
+}
+
+interface ObjectMember {
+  schema: JsonSchema
+  conditional: boolean
+}
+
+function objectMembers(schema: JsonSchema, conditional: boolean): ObjectMember[] {
+  const members: ObjectMember[] = []
+  if (schema.properties !== undefined) members.push({ schema, conditional })
+  for (const member of schema.allOf ?? []) {
+    members.push(...objectMembers(member, conditional))
+  }
+  for (const variants of [schema.anyOf, schema.oneOf]) {
+    for (const variant of variants ?? []) {
+      members.push(...objectMembers(variant, true))
+    }
+  }
+  return members
+}
+
+function nonNullVariants(property: JsonSchema): JsonSchema[] | undefined {
+  const variants = property.anyOf ?? property.oneOf
+  if (variants === undefined) return undefined
+  return variants.filter((variant) => variant.type !== 'null')
+}
+
+function flagKind(property: JsonSchema): FlagValueKind {
+  if (property.const !== undefined) {
+    const kind = typeof property.const
+    return kind === 'string' || kind === 'number' || kind === 'boolean' ? kind : 'json'
+  }
+  if (property.enum !== undefined) return 'string'
+  const variants = nonNullVariants(property)
+  if (variants !== undefined) {
+    const kinds = new Set(variants.map(flagKind))
+    const [first] = kinds
+    return kinds.size === 1 && first !== undefined ? first : 'json'
+  }
+  switch (property.type) {
+    case 'string':
+      return 'string'
+    case 'integer':
+    case 'number':
+      return 'number'
+    case 'boolean':
+      return 'boolean'
+    case 'array': {
+      const items = property.items
+      return typeof items === 'object' &&
+        !Array.isArray(items) &&
+        items.type === 'string' &&
+        items.enum === undefined
+        ? 'stringArray'
+        : 'json'
+    }
+    default:
+      return 'json'
+  }
+}
+
+function enumChoices(property: JsonSchema): (string | number)[] | undefined {
+  if (typeof property.const === 'string' || typeof property.const === 'number') {
+    return [property.const]
+  }
+  if (property.enum !== undefined) {
+    const choices = property.enum.filter(
+      (value) => typeof value === 'string' || typeof value === 'number',
+    )
+    return choices.length > 0 ? choices : undefined
+  }
+  const variants = nonNullVariants(property)
+  const only = variants?.length === 1 ? variants[0] : undefined
+  return only === undefined ? undefined : enumChoices(only)
+}
+
+interface FlagDraft {
+  path: string[]
+  kind: FlagValueKind
+  required: boolean
+  description: string | undefined
+  choices: (string | number)[] | undefined
+}
+
+function expandsToFlags(property: JsonSchema): boolean {
+  return objectMembers(property, false).length > 0
+}
+
+function collectDrafts(
+  drafts: Map<string, FlagDraft>,
+  schema: JsonSchema,
+  prefix: string[],
+  conditional: boolean,
+): void {
+  for (const member of objectMembers(schema, conditional)) {
+    const required = new Set(member.schema.required ?? [])
+    for (const [key, property] of Object.entries(member.schema.properties ?? {})) {
+      if (typeof property === 'boolean') continue
+      const path = [...prefix, key]
+      const propertyRequired = !member.conditional && required.has(key)
+      if (expandsToFlags(property)) {
+        collectDrafts(drafts, property, path, !propertyRequired)
+        continue
+      }
+      const choices = enumChoices(property)
+      const description = property.description?.split('\n')[0]
+      const existing = drafts.get(path.join('.'))
+      if (existing !== undefined) {
+        existing.required = existing.required || propertyRequired
+        existing.description ??= description
+        existing.choices =
+          existing.choices !== undefined && choices !== undefined
+            ? [...new Set([...existing.choices, ...choices])]
+            : undefined
+        continue
+      }
+      drafts.set(path.join('.'), {
+        path,
+        kind: flagKind(property),
+        required: propertyRequired,
+        description,
+        choices,
+      })
+    }
+  }
+}
+
+function finalizeFlag(draft: FlagDraft): FlagSpec {
+  const flag = draft.path.map(kebabCase).join('-')
+  const parts: string[] = []
+  if (draft.description !== undefined) parts.push(draft.description)
+  if (draft.choices !== undefined) parts.push(`choices: ${draft.choices.join(', ')}`)
+  if (draft.kind === 'json') parts.push('JSON value')
+  if (draft.kind === 'stringArray') parts.push('repeatable')
+  return {
+    path: draft.path,
+    flag,
+    optionKey: camelCase(flag),
+    kind: draft.kind,
+    required: draft.required,
+    description: parts.join(' — '),
+  }
+}
+
+export function deriveFlags(schema: z.ZodType): FlagSpec[] {
+  const jsonSchema: JsonSchema = z.toJSONSchema(schema, { io: 'input' })
+  const drafts = new Map<string, FlagDraft>()
+  collectDrafts(drafts, jsonSchema, [], false)
+  return [...drafts.values()].map(finalizeFlag)
+}

package/src/format.ts

@@ -0,0 +1,45 @@
+export interface FormattedOutput {
+  value: unknown
+  columns?: readonly string[]
+}
+
+export type OutputFormat<Response> = (data: Response) => FormattedOutput
+
+interface ListEnvelope<Item> {
+  data: Item[]
+  next_cursor: string | null
+}
+
+type FieldName<Value> = Extract<keyof Value, string>
+
+function pickFields<Value extends object>(
+  source: Value,
+  fields: readonly FieldName<Value>[],
+): Record<string, unknown> {
+  const picked: Record<string, unknown> = {}
+  for (const field of fields) {
+    const value = source[field]
+    if (value !== undefined) picked[field] = value
+  }
+  return picked
+}
+
+export function formatTable<Item extends object>(
+  columns: readonly FieldName<Item>[],
+): OutputFormat<ListEnvelope<Item>> {
+  return (response) => ({
+    value: {
+      data: response.data.map((item) => pickFields(item, columns)),
+      next_cursor: response.next_cursor,
+    },
+    columns,
+  })
+}
+
+export function formatRecord<Value extends object>(): OutputFormat<Value> {
+  return (data) => ({ value: data })
+}
+
+export function formatVoid(message = 'ok'): OutputFormat<void> {
+  return () => ({ value: message })
+}

package/src/interactive.ts

@@ -0,0 +1,56 @@
+import { isCancel, select } from '@clack/prompts'
+import { type OmnaraClient, sdk } from '@omnara/sdk'
+
+import { CliInputError } from './output.ts'
+
+export function canPromptInteractively(): boolean {
+  return process.stdin.isTTY && process.stdout.isTTY
+}
+
+interface Choice {
+  id: string
+  label: string
+}
+
+async function selectFrom(message: string, choices: Choice[]): Promise<string> {
+  const [only] = choices
+  if (choices.length === 1 && only !== undefined) {
+    console.log(`${message}: ${only.label} (only option)`)
+    return only.id
+  }
+  const picked = await select({
+    message,
+    options: choices.map((choice) => ({ value: choice.id, label: choice.label, hint: choice.id })),
+  })
+  if (isCancel(picked)) throw new CliInputError('selection cancelled')
+  return picked
+}
+
+export async function promptOrgSelection(client: OmnaraClient): Promise<string> {
+  const { data } = await sdk.getCurrentUser({ client })
+  if (data.orgs.length === 0) {
+    throw new CliInputError('this account has no organizations')
+  }
+  return selectFrom(
+    'Select an organization',
+    data.orgs.map((org) => ({ id: org.id, label: org.name })),
+  )
+}
+
+export async function promptProjectSelection(client: OmnaraClient, orgId: string): Promise<string> {
+  const projects: Choice[] = []
+  let cursor: string | undefined
+  do {
+    const { data } = await sdk.listVisibleProjects({
+      client,
+      path: { orgID: orgId },
+      query: cursor === undefined ? {} : { cursor },
+    })
+    projects.push(...data.data.map((project) => ({ id: project.id, label: project.name })))
+    cursor = data.next_cursor ?? undefined
+  } while (cursor !== undefined)
+  if (projects.length === 0) {
+    throw new CliInputError(`no projects visible in organization ${orgId}`)
+  }
+  return selectFrom('Select a project', projects)
+}