omnara 0.6.1 → 1.0.0-beta.0

package/package.json

@@ -1,38 +1,26 @@
 {
   "name": "omnara",
-  "version": "0.6.1",
-  "description": "Deprecated npm redirect for Omnara. Install the current CLI with curl -fsSL https://omnara.com/install.sh | bash.",
+  "version": "1.0.0-beta.0",
+  "type": "module",
   "bin": {
-    "omnara": "./bin/omnara.js"
-  },
-  "files": [
-    "bin",
-    "README.md"
-  ],
-  "keywords": [
-    "omnara",
-    "cli",
-    "deprecated",
-    "installer",
-    "ai",
-    "agents"
-  ],
-  "author": "Omnara <contact@omnara.com>",
-  "license": "Apache-2.0",
-  "homepage": "https://omnara.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/omnara/omnara-voice.git",
-    "directory": "packaging/deprecated-npm-omnara"
-  },
-  "bugs": {
-    "url": "https://github.com/omnara/omnara-voice/issues"
+    "omnara": "./src/bin.ts"
   },
   "scripts": {
-    "test": "node tests/redirect.test.js",
-    "pack:check": "npm pack --dry-run"
+    "omnara": "tsx src/bin.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "@omnara/sdk": "workspace:*",
+    "commander": "^14.0.0",
+    "tar": "^7.5.22",
+    "zod": "^4.4.3"
   },
-  "engines": {
-    "node": ">=16"
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "4.1.9"
   }
 }

package/src/bin.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env tsx
+import { Command } from 'commander'
+
+import { loadConfig, registerConfigCommand } from './config.ts'
+import { registerGroup, registerOperation } from './factory.ts'
+import { registerLoginCommand } from './login.ts'
+import { commandGroups, topLevelOperations } from './manifest.ts'
+
+process.stdout.on('error', (error: NodeJS.ErrnoException) => {
+  if (error.code === 'EPIPE') process.exit(0)
+  throw error
+})
+
+const program = new Command('omnara').description('Interact with the Omnara API')
+program.configureHelp({
+  subcommandTerm: (cmd) => {
+    const args = cmd.registeredArguments
+      .map((arg) =>
+        arg.required
+          ? `<${arg.name()}${arg.variadic ? '...' : ''}>`
+          : `[${arg.name()}${arg.variadic ? '...' : ''}]`,
+      )
+      .join(' ')
+    return [cmd.name(), cmd.options.length > 0 ? '[options]' : '', args]
+      .filter((part) => part !== '')
+      .join(' ')
+  },
+})
+const config = loadConfig()
+for (const group of commandGroups) registerGroup(program, config, group)
+for (const operation of topLevelOperations) registerOperation(program, config, operation)
+registerLoginCommand(program, config)
+registerConfigCommand(program, config)
+await program.parseAsync()

package/src/browser.ts

@@ -0,0 +1,16 @@
+import { spawn } from 'node:child_process'
+
+function browserCommand(url: string): { command: string; args: string[] } {
+  if (process.platform === 'darwin') return { command: 'open', args: [url] }
+  if (process.platform === 'win32') return { command: 'cmd', args: ['/c', 'start', '', url] }
+  return { command: 'xdg-open', args: [url] }
+}
+
+export function openInBrowser(url: string, onError: (message: string) => void): void {
+  const { command, args } = browserCommand(url)
+  const child = spawn(command, args, { stdio: 'ignore', detached: true })
+  child.once('error', () => {
+    onError('could not open a browser; use the URL above')
+  })
+  child.unref()
+}

package/src/config.ts

@@ -0,0 +1,185 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { bearerToken, createOmnaraClient, type OmnaraClient } from '@omnara/sdk'
+import { zOrganizationId, zProjectId } from '@omnara/sdk/zod'
+import type { Command } from 'commander'
+import * as z from 'zod'
+
+import {
+  canPromptInteractively,
+  promptOrgSelection,
+  promptProjectSelection,
+} from './interactive.ts'
+import { CliInputError, runCliAction } from './output.ts'
+
+export const DEFAULT_BASE_URL = 'https://app.omnara.com'
+
+const zConfigFile = z.looseObject({
+  base_url: z.url().optional(),
+  token: z.string().min(1).optional(),
+  org_id: zOrganizationId.optional(),
+  project_id: zProjectId.optional(),
+})
+
+export type ConfigFile = z.infer<typeof zConfigFile>
+
+export interface CliConfig {
+  client: OmnaraClient
+  baseUrl: string
+  defaultOrgId?: string
+  defaultProjectId?: string
+}
+
+export function configFilePath(): string {
+  return join(homedir(), '.config', 'omnara', 'config.json')
+}
+
+let warnedAboutConfig = false
+
+function warnConfigIgnored(message: string): void {
+  if (warnedAboutConfig) return
+  warnedAboutConfig = true
+  console.error(message)
+}
+
+const zConfigContents = z
+  .string()
+  .transform((raw, ctx): unknown => {
+    try {
+      return JSON.parse(raw)
+    } catch (error) {
+      ctx.addIssue(error instanceof Error ? error.message : String(error))
+      return z.NEVER
+    }
+  })
+  .pipe(zConfigFile)
+
+function loadConfigFile(): z.ZodSafeParseResult<ConfigFile> {
+  const path = configFilePath()
+  if (!existsSync(path)) return { success: true, data: {} }
+  return zConfigContents.safeParse(readFileSync(path, 'utf8'))
+}
+
+export function readConfigFile(): ConfigFile {
+  const result = loadConfigFile()
+  if (result.success) return result.data
+  warnConfigIgnored(
+    `warning: ignoring unreadable config at ${configFilePath()}: ${z.prettifyError(result.error)}`,
+  )
+  return {}
+}
+
+export function readConfigFileForUpdate(): ConfigFile {
+  const result = loadConfigFile()
+  if (result.success) return result.data
+  throw new CliInputError(
+    `refusing to modify unreadable config at ${configFilePath()} (fix or delete it first): ${z.prettifyError(result.error)}`,
+  )
+}
+
+export function updateConfigFile(patch: Partial<ConfigFile>): ConfigFile {
+  const merged = Object.fromEntries(
+    Object.entries({ ...readConfigFileForUpdate(), ...patch }).filter(
+      ([, value]) => value !== undefined,
+    ),
+  )
+  const result = zConfigFile.safeParse(merged)
+  if (!result.success) {
+    throw new CliInputError(`refusing to save invalid config:\n${z.prettifyError(result.error)}`)
+  }
+  mkdirSync(dirname(configFilePath()), { recursive: true, mode: 0o700 })
+  writeFileSync(configFilePath(), `${JSON.stringify(result.data, null, 2)}\n`, { mode: 0o600 })
+  chmodSync(configFilePath(), 0o600)
+  return result.data
+}
+
+export function loadConfig(): CliConfig {
+  const file = readConfigFile()
+  const baseUrl = process.env.OMNARA_BASE_URL ?? file.base_url ?? DEFAULT_BASE_URL
+  const token = process.env.OMNARA_API_KEY ?? file.token
+  const client = createOmnaraClient({
+    baseUrl,
+    auth: token ? bearerToken(token) : undefined,
+  })
+  return {
+    client,
+    baseUrl,
+    defaultOrgId: process.env.OMNARA_ORG_ID ?? file.org_id,
+    defaultProjectId: process.env.OMNARA_PROJECT_ID ?? file.project_id,
+  }
+}
+
+interface ConfigOptions {
+  org?: string
+  project?: string
+  baseUrl?: string
+}
+
+function describeValue(
+  envName: string,
+  fileValue: string | undefined,
+  defaultValue?: string,
+): string {
+  const envValue = process.env[envName]
+  if (envValue !== undefined) {
+    const shadowed = fileValue !== undefined ? ` (config has ${fileValue})` : ''
+    return `${envValue}  [from ${envName}${shadowed}]`
+  }
+  if (fileValue !== undefined) return `${fileValue}  [from config file]`
+  if (defaultValue !== undefined) return `${defaultValue}  [default]`
+  return '(not set)'
+}
+
+function printConfig(): void {
+  const file = readConfigFile()
+  console.log(`config file  ${configFilePath()}`)
+  console.log(`org_id       ${describeValue('OMNARA_ORG_ID', file.org_id)}`)
+  console.log(`project_id   ${describeValue('OMNARA_PROJECT_ID', file.project_id)}`)
+  console.log(`base_url     ${describeValue('OMNARA_BASE_URL', file.base_url, DEFAULT_BASE_URL)}`)
+}
+
+export function registerConfigCommand(program: Command, cli: CliConfig): void {
+  const config = program
+    .command('config')
+    .description('Show or set the default organization and project')
+    .option('--org <org-id>', 'save this organization ID as the default')
+    .option('--project <project-id>', 'save this project ID as the default')
+    .option('--base-url <url>', 'save this API base URL as the default')
+    .action(async (options: ConfigOptions) => {
+      await runCliAction(() => {
+        if (
+          options.org !== undefined ||
+          options.project !== undefined ||
+          options.baseUrl !== undefined
+        ) {
+          const clearStaleProject = options.org !== undefined && options.project === undefined
+          updateConfigFile({
+            ...(options.org !== undefined ? { org_id: options.org } : {}),
+            ...(clearStaleProject
+              ? { project_id: undefined }
+              : options.project !== undefined
+                ? { project_id: options.project }
+                : {}),
+            ...(options.baseUrl !== undefined ? { base_url: options.baseUrl } : {}),
+          })
+        }
+        printConfig()
+      })
+    })
+  config
+    .command('select')
+    .description('Interactively choose the default organization and project')
+    .action(async () => {
+      await runCliAction(async () => {
+        if (!canPromptInteractively()) {
+          throw new CliInputError('interactive selection needs a terminal')
+        }
+        const orgId = await promptOrgSelection(cli.client)
+        const projectId = await promptProjectSelection(cli.client, orgId)
+        updateConfigFile({ org_id: orgId, project_id: projectId })
+        printConfig()
+      })
+    })
+}

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