@seamapi/cli 0.9.0 → 0.11.0

package/src/lib/interact-for-resource.ts

@@ -1,5 +1,4 @@
-import prompts from 'prompts'
-
+import { prompt } from './util/prompt.js'
 import { withLoading } from './util/with-loading.js'
 
 export interface ResourceChoice {
@@ -23,7 +22,7 @@ export const interactForResource = async <Resource>({
     `Fetching ${resourceName.replace(/_/g, ' ')}s...`,
     fetchResources,
   )
-  const { resourceId } = await prompts({
+  const { resourceId } = await prompt({
     name: 'resourceId',
     type: 'autocomplete',
     message,

package/src/lib/interact-for-server-selection.ts

@@ -1,9 +1,9 @@
 import { randomBytes } from 'node:crypto'
 
-import prompts from 'prompts'
-
 import { getConfigStore } from './config/index.js'
 import { getServer } from './get-server.js'
+import { getOutput } from './output/get-output.js'
+import { prompt } from './util/prompt.js'
 
 export async function interactForServerSelection() {
   const servers = [
@@ -12,7 +12,7 @@ export async function interactForServerSelection() {
     'https://fakeseamconnect.seam.vc',
   ]
 
-  const { server } = await prompts([
+  const { server } = await prompt([
     {
       type: 'select',
       name: 'server',
@@ -22,8 +22,9 @@ export async function interactForServerSelection() {
   ])
 
   const config = getConfigStore()
+  const output = getOutput()
   if (server === servers[2]) {
-    let { userUrlSeed } = await prompts([
+    let { userUrlSeed } = await prompt([
       {
         type: 'text',
         name: 'userUrlSeed',
@@ -37,10 +38,10 @@ export async function interactForServerSelection() {
     }
     config.set('server', `https://${userUrlSeed}.fakeseamconnect.seam.vc`)
     config.set(`${getServer()}.pat`, `seam_apikey1_token`)
-    console.log(`PAT set to use fakeseamconnect with "seam_apikey1_token"`)
+    output.info(`PAT set to use fakeseamconnect with "seam_apikey1_token"`)
   } else {
     config.set('server', server)
   }
   config.delete('current_workspace_id')
-  console.log(`Server set to ${server}`)
+  output.info(`Server set to ${server}`)
 }

package/src/lib/interact-for-timestamp.ts

@@ -1,6 +1,6 @@
-import prompts from 'prompts'
+import { prompt } from './util/prompt.js'
 export const interactForTimestamp = async () => {
-  const { timestamp } = await prompts({
+  const { timestamp } = await prompt({
     name: 'timestamp',
     type: 'date',
     message: 'Enter a timestamp:',

package/src/lib/interact-for-use-remote-api-defs.ts

@@ -1,9 +1,9 @@
-import prompts from 'prompts'
-
 import { getConfigStore } from './config/index.js'
+import { getOutput } from './output/get-output.js'
+import { prompt } from './util/prompt.js'
 
 export async function interactForUseRemoteApiDefs() {
-  const { use_remote_api_defs } = await prompts([
+  const { use_remote_api_defs } = await prompt([
     {
       type: 'select',
       name: 'use_remote_api_defs',
@@ -23,5 +23,5 @@ export async function interactForUseRemoteApiDefs() {
 
   const config = getConfigStore()
   config.set('use_remote_api_defs', use_remote_api_defs)
-  console.log(`Use remote API Definitions: ${use_remote_api_defs}`)
+  getOutput().info(`Use remote API Definitions: ${use_remote_api_defs}`)
 }

package/src/lib/interact-for-workspace-id.ts

@@ -1,9 +1,9 @@
 import { SeamHttpWithoutWorkspace } from '@seamapi/http/connect'
-import prompts from 'prompts'
 
 import { getConfigStore } from './config/index.js'
 import { getSeamMultiWorkspace } from './get-seam.js'
 import { getServer } from './get-server.js'
+import { prompt } from './util/prompt.js'
 import { withLoading } from './util/with-loading.js'
 
 export const interactForWorkspaceId = async (personalAccessToken?: string) => {
@@ -17,7 +17,7 @@ export const interactForWorkspaceId = async (personalAccessToken?: string) => {
   const workspaces = await withLoading('Fetching workspaces...', () =>
     seam.workspaces.list(),
   )
-  const { workspaceId } = await prompts({
+  const { workspaceId } = await prompt({
     name: 'workspaceId',
     type: 'select',
     message: 'Select a workspace:',

package/src/lib/output/create-memory-output.ts

@@ -0,0 +1,39 @@
+import {
+  createOutput,
+  type CreateOutputOptions,
+  type Output,
+  type OutputStream,
+} from './create-output.js'
+
+export interface MemoryOutput {
+  output: Output
+  /** Everything written to stdout so far. */
+  stdout: () => string
+  /** Everything written to stderr so far. */
+  stderr: () => string
+}
+
+const createMemoryStream = (): OutputStream & { read: () => string } => {
+  const chunks: string[] = []
+  return {
+    write: (chunk: string) => chunks.push(chunk),
+    read: () => chunks.join(''),
+  }
+}
+
+/**
+ * An {@link Output} that captures writes in memory instead of
+ * touching the process streams, for asserting on CLI output.
+ */
+export const createMemoryOutput = (
+  options: Omit<CreateOutputOptions, 'stdout' | 'stderr'> = {},
+): MemoryOutput => {
+  const stdout = createMemoryStream()
+  const stderr = createMemoryStream()
+
+  return {
+    output: createOutput({ ...options, stdout, stderr }),
+    stdout: stdout.read,
+    stderr: stderr.read,
+  }
+}

package/src/lib/output/create-output.ts

@@ -0,0 +1,104 @@
+import { inspect } from 'node:util'
+
+/**
+ * Minimal writable surface needed by {@link Output}.
+ *
+ * Both `process.stdout` and an in-memory buffer satisfy this,
+ * which is what makes output testable.
+ */
+export interface OutputStream {
+  write: (chunk: string) => unknown
+}
+
+/**
+ * `json` is machine readable: only {@link Output.data} produces output.
+ * `text` is human readable: data is pretty printed and may be colorized.
+ */
+export type OutputFormat = 'json' | 'text'
+
+export interface Output {
+  readonly format: OutputFormat
+
+  /**
+   * The result of a command, e.g., an API response.
+   *
+   * This is the only thing ever written to stdout,
+   * so it is safe to pipe into another program.
+   */
+  data: (value: unknown) => void
+
+  /**
+   * A plain text command result, e.g., the version or the help guide.
+   *
+   * Written to stdout verbatim in every format: these results are already
+   * a single value, so encoding them as JSON would only make them harder
+   * to consume from a pipe.
+   */
+  text: (value: string) => void
+
+  /**
+   * Human facing progress, context, and confirmations.
+   *
+   * Written to stderr and suppressed entirely in the json format.
+   */
+  info: (message?: string) => void
+
+  /** Human facing warning. Written to stderr in every format. */
+  warn: (message: string) => void
+
+  /** Human facing error. Written to stderr in every format. */
+  error: (message: string) => void
+}
+
+export interface CreateOutputOptions {
+  format?: OutputFormat
+  stdout?: OutputStream
+  stderr?: OutputStream
+  /** Colorize pretty printed data. Never applied to the json format. */
+  colors?: boolean
+}
+
+export const createOutput = ({
+  format = 'text',
+  stdout = process.stdout,
+  stderr = process.stderr,
+  colors = false,
+}: CreateOutputOptions = {}): Output => {
+  const isJson = format === 'json'
+
+  return {
+    format,
+
+    data: (value: unknown): void => {
+      if (value === undefined) return
+      stdout.write(`${formatData(value, format, colors)}\n`)
+    },
+
+    text: (value: string): void => {
+      stdout.write(`${value}\n`)
+    },
+
+    info: (message = ''): void => {
+      if (isJson) return
+      stderr.write(`${message}\n`)
+    },
+
+    warn: (message: string): void => {
+      stderr.write(`${message}\n`)
+    },
+
+    error: (message: string): void => {
+      stderr.write(`${message}\n`)
+    },
+  }
+}
+
+const formatData = (
+  value: unknown,
+  format: OutputFormat,
+  colors: boolean,
+): string => {
+  if (format === 'json') return JSON.stringify(value, null, 2)
+  if (typeof value === 'string') return value
+  return inspect(value, { depth: null, colors })
+}

package/src/lib/output/get-output.ts

@@ -0,0 +1,24 @@
+import { createOutput, type Output } from './create-output.js'
+
+let output: Output | null = null
+
+/**
+ * The output used by the CLI.
+ *
+ * Defaults to a `text` output bound to the real process streams,
+ * so importing modules never write to stdout by accident.
+ */
+export const getOutput = (): Output => {
+  output ??= createOutput()
+  return output
+}
+
+/** Replace the output, e.g., once flags are parsed, or from a test. */
+export const setOutput = (nextOutput: Output): void => {
+  output = nextOutput
+}
+
+/** Restore the default output. Intended for tests. */
+export const resetOutput = (): void => {
+  output = null
+}

package/src/lib/output/resolve-output-format.ts

@@ -0,0 +1,33 @@
+import type { OutputFormat } from './create-output.js'
+
+export interface ResolveOutputFormatOptions {
+  /** Whether stdout is a terminal. */
+  isTty?: boolean
+}
+
+/**
+ * Whether to write machine readable output.
+ *
+ * An explicit `--json` or `--no-json` wins, otherwise the CLI writes JSON
+ * whenever stdout is piped or redirected, and pretty output at a terminal.
+ *
+ * This reads the arguments rather than the parsed args because `--json` is
+ * declared as a boolean flag, so that it never consumes the argument after
+ * it, and a boolean cannot tell `--no-json` apart from not passing anything.
+ */
+export const resolveOutputFormat = (
+  argv: string[],
+  { isTty = false }: ResolveOutputFormatOptions = {},
+): OutputFormat => {
+  const flag = argv.filter((arg) => arg === '--json' || arg === '--no-json')
+
+  // The last one wins, matching how the argument parser resolves repeats.
+  switch (flag[flag.length - 1]) {
+    case '--json':
+      return 'json'
+    case '--no-json':
+      return 'text'
+    default:
+      return isTty ? 'text' : 'json'
+  }
+}

package/src/lib/output/select-response-payload.ts

@@ -0,0 +1,56 @@
+/**
+ * Top level response fields that are transport details,
+ * not part of the result the CLI reports.
+ */
+const metaKeys = new Set(['ok'])
+
+const paginationKey = 'pagination'
+const errorKey = 'error'
+
+export interface SelectResponsePayloadOptions {
+  /**
+   * The response key for the endpoint, e.g., `devices` for `/devices/list`,
+   * usually taken from the API blueprint.
+   *
+   * When omitted, every top level field except {@link metaKeys} is kept.
+   */
+  responseKey?: string | null | undefined
+}
+
+/**
+ * Reduce an API response body to the response key and pagination.
+ *
+ * The CLI never reports other top level fields: they are details of the
+ * transport, so including them would leak into anything parsing stdout.
+ */
+export const selectResponsePayload = (
+  data: unknown,
+  { responseKey }: SelectResponsePayloadOptions = {},
+): unknown => {
+  if (!isRecord(data)) return data
+
+  if (errorKey in data) {
+    return { [errorKey]: data[errorKey] }
+  }
+
+  const keys =
+    responseKey != null && responseKey in data
+      ? [responseKey]
+      : Object.keys(data).filter(
+          (key) => !metaKeys.has(key) && key !== paginationKey,
+        )
+
+  const payload: Record<string, unknown> = {}
+  for (const key of keys) {
+    payload[key] = data[key]
+  }
+
+  if (paginationKey in data) {
+    payload[paginationKey] = data[paginationKey]
+  }
+
+  return payload
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)

package/src/lib/types.ts

@@ -1,6 +1,7 @@
 import type { ApiBlueprint } from './get-api-blueprint.js'
+import type { Interactivity } from './util/cli-args.js'
 
 export interface ContextHelpers {
   blueprint: ApiBlueprint
-  is_interactive: boolean
+  interactivity: Interactivity
 }

package/src/lib/util/cli-args.ts

@@ -0,0 +1,92 @@
+import parseArgs, { type ParsedArgs } from 'minimist'
+
+/**
+ * How the CLI should behave when properties are not given as arguments.
+ *
+ * - `auto`: make the request as soon as every required property is given,
+ *   otherwise prompt for what is missing. This is the default.
+ * - `interactive`: always prompt to review and edit properties, prefilled
+ *   with the given arguments. Selected with `--interactive` or `-i`.
+ * - `non-interactive`: never prompt: anything missing is an error.
+ *   Selected with `--non-interactive` or `-y`.
+ */
+export type Interactivity = 'auto' | 'interactive' | 'non-interactive'
+
+/**
+ * Argument keys that select the interactivity
+ * and are therefore not command parameters.
+ */
+export const interactivityFlags: string[] = [
+  'non_interactive',
+  'y',
+  'interactive',
+  'i',
+]
+
+/**
+ * Argument keys that configure the CLI itself
+ * and are therefore never sent as command parameters.
+ */
+export const cliFlags: string[] = [
+  ...interactivityFlags,
+  'h',
+  'help',
+  'json',
+  'remote_api_defs',
+  'update',
+  'version',
+]
+
+/**
+ * Thrown when the CLI needs input it cannot prompt for.
+ */
+export class NonInteractiveError extends Error {
+  override name = 'NonInteractiveError'
+}
+
+export const parseCliArgs = (argv: string[]): ParsedArgs =>
+  parseArgs(argv, {
+    string: ['code'],
+    boolean: ['non-interactive', 'interactive', 'json'],
+    // Deliberately not aliased to -n, which is reserved for a future
+    // --dry-run flag.
+    alias: { 'non-interactive': 'y', interactive: 'i' },
+  })
+
+export interface GetInteractivityOptions {
+  /**
+   * Whether there is a terminal to prompt on.
+   *
+   * When there is not, the CLI cannot ask for anything, so it behaves as
+   * though `--non-interactive` was given rather than waiting on a prompt
+   * nobody can answer.
+   */
+  canPrompt?: boolean
+}
+
+export const getInteractivity = (
+  args: ParsedArgs,
+  { canPrompt = true }: GetInteractivityOptions = {},
+): Interactivity => {
+  const isNonInteractive =
+    args['non_interactive'] === true || args['y'] === true
+  const isInteractive = args['interactive'] === true || args['i'] === true
+
+  if (isNonInteractive && isInteractive) {
+    throw new Error(
+      'The --interactive and --non-interactive flags cannot be used together',
+    )
+  }
+  if (isNonInteractive) return 'non-interactive'
+  // An explicit --interactive still asks, and fails loudly if it cannot.
+  if (isInteractive) return 'interactive'
+  if (!canPrompt) return 'non-interactive'
+  return 'auto'
+}
+
+/**
+ * Render a parameter name as the argument used to set it,
+ * e.g., `device_id` as `--device-id`.
+ */
+export const toArgName = (parameterName: string): string =>
+  `--${parameterName.replace(/_/g, '-')}`

package/src/lib/util/prompt.ts

@@ -0,0 +1,38 @@
+import prompts, { type Answers, type Options, type PromptObject } from 'prompts'
+
+import { NonInteractiveError } from './cli-args.js'
+
+/**
+ * Whether the CLI can ask the user a question.
+ *
+ * Prompts read raw keypresses and render an interface, so they need a
+ * terminal on both ends: when stdin is a pipe or a file it holds request
+ * params, not answers, and when stderr is redirected nobody sees the
+ * question.
+ */
+export const canPrompt = (): boolean =>
+  process.stdin.isTTY === true && process.stderr.isTTY === true
+
+/**
+ * Ask the user a question.
+ *
+ * Prompts are rendered to stderr: a selection is not a command result,
+ * so it must not end up in stdout when the CLI is piped.
+ */
+export const prompt = async <T extends string = string>(
+  questions: PromptObject<T> | Array<PromptObject<T>>,
+  options?: Options,
+): Promise<Answers<T>> => {
+  if (!canPrompt()) {
+    throw new NonInteractiveError(
+      'Cannot prompt without a terminal: pass the missing arguments, or pipe them in as JSON',
+    )
+  }
+
+  const questionList = Array.isArray(questions) ? questions : [questions]
+
+  return await prompts(
+    questionList.map((question) => ({ ...question, stdout: process.stderr })),
+    options,
+  )
+}

package/src/lib/util/read-stdin-json.ts

@@ -0,0 +1,59 @@
+import type { Readable } from 'node:stream'
+
+export interface StdinLike extends AsyncIterable<string | Buffer> {
+  isTTY?: boolean | undefined
+}
+
+/**
+ * Read request params piped into the CLI, e.g.,
+ *
+ * ```
+ * $ echo '{"device_id": "..."}' | seam locks unlock-door --json
+ * $ seam locks unlock-door --json < params.json
+ * ```
+ *
+ * Returns null when stdin is a terminal or is empty,
+ * so an interactive session is never blocked waiting for input.
+ */
+export const readStdinJson = async (
+  stdin: StdinLike | Readable = process.stdin,
+): Promise<Record<string, unknown> | null> => {
+  if ((stdin as StdinLike).isTTY ?? false) return null
+
+  let raw = ''
+  for await (const chunk of stdin) {
+    raw += typeof chunk === 'string' ? chunk : chunk.toString('utf8')
+  }
+
+  return parseJsonParams(raw, 'stdin')
+}
+
+/**
+ * Parse JSON request params, e.g., from stdin or `--json '{"limit": 2}'`.
+ *
+ * Returns null when there is nothing to parse.
+ */
+export const parseJsonParams = (
+  raw: string,
+  source: string,
+): Record<string, unknown> | null => {
+  const trimmed = raw.trim()
+  if (trimmed === '') return null
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(trimmed)
+  } catch (error) {
+    throw new Error(
+      `Could not parse JSON from ${source}: ${(error as Error).message}`,
+    )
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(
+      `Expected a JSON object of request params from ${source}, got ${Array.isArray(parsed) ? 'an array' : typeof parsed}`,
+    )
+  }
+
+  return parsed as Record<string, unknown>
+}

package/src/lib/util/request-seam-api.ts

@@ -1,19 +1,29 @@
 import chalk from 'chalk'
 
 import { getSeam } from 'lib/get-seam.js'
+import { getOutput } from 'lib/output/get-output.js'
+import { selectResponsePayload } from 'lib/output/select-response-payload.js'
 
 import { withLoading } from './with-loading.js'
 
+export interface RequestSeamApiOptions {
+  path: string
+  params: Record<string, any>
+  /** Response key for the endpoint, used to trim the reported payload. */
+  responseKey?: string | null | undefined
+}
+
 export const RequestSeamApi = async ({
   path,
   params,
-}: {
-  path: string
-  params: Record<string, any>
-}) => {
+  responseKey,
+}: RequestSeamApiOptions) => {
   const seam = await getSeam()
+  const output = getOutput()
 
-  logRequest(path, params)
+  output.info(`\n${chalk.green(path)}`)
+  output.info(`Request Params:`)
+  output.info(formatParams(params))
 
   const response = await withLoading('Making request...', () =>
     seam.client.post(path, params, {
@@ -21,23 +31,17 @@ export const RequestSeamApi = async ({
     }),
   )
 
-  logResponse(response)
-
-  return response
-}
-
-const logResponse = (response: { status: number; data: unknown }) => {
   if (response.status >= 400) {
-    console.log(chalk.red(`\n\n[${response.status}]\n`))
+    output.warn(chalk.red(`[${response.status}]`))
+    process.exitCode = 1
   } else {
-    console.log(chalk.green(`\n\n[${response.status}]`))
+    output.info(chalk.green(`[${response.status}]`))
   }
-  console.dir(response.data, { depth: null })
-  console.log('\n')
-}
 
-const logRequest = (apiPath: string, params: Record<string, any>) => {
-  console.log(`\n\n${chalk.green(apiPath)}`)
-  console.log(`Request Params:`)
-  console.log(params)
+  output.data(selectResponsePayload(response.data, { responseKey }))
+
+  return response
 }
+
+const formatParams = (params: Record<string, any>): string =>
+  JSON.stringify(params, null, 2)

package/src/lib/util/with-loading.ts

@@ -1,10 +1,15 @@
 import { createSpinner } from 'nanospinner'
 
+import { getOutput } from 'lib/output/get-output.js'
+
 export const withLoading = async <T>(
   message: string,
   fn: () => Promise<T>,
 ): Promise<T> => {
-  const spinner = createSpinner(message).start()
+  if (!shouldSpin()) return await fn()
+
+  // Progress is not a command result, so it is rendered to stderr.
+  const spinner = createSpinner(message, { stream: process.stderr }).start()
   try {
     const result = await fn()
     spinner.success()
@@ -14,3 +19,6 @@ export const withLoading = async <T>(
     throw error
   }
 }
+
+const shouldSpin = (): boolean =>
+  getOutput().format === 'text' && process.stderr.isTTY === true

package/src/lib/version.ts

@@ -1,5 +1,5 @@
 // Versions are replaced with generated values when the package is packed.
-const seamapiCliVersion = '0.9.0'
+const seamapiCliVersion = '0.11.0'
 const seamapiBlueprintVersion = '1.2.0'
 
 export { seamapiBlueprintVersion }