@seamapi/cli 0.10.0 → 0.11.0

package/src/lib/interact-for-custom-metadata.ts

@@ -1,4 +1,5 @@
-import prompts from 'prompts'
+import { getOutput } from './output/get-output.js'
+import { prompt } from './util/prompt.js'
 
 // Structurally the CustomMetadata of @seamapi/types, spelled out here so the
 // published declarations do not depend on a development-only package.
@@ -12,15 +13,16 @@ export const interactForCustomMetadata = async (
   custom_metadata: CustomMetadata,
 ) => {
   const updated_custom_metadata: UpdatedCustomMetadata = { ...custom_metadata }
+  const output = getOutput()
 
   const displayCurrentCustomMetadata = () => {
-    console.log('custom_metadata:')
+    output.info('custom_metadata:')
     if (Object.keys(updated_custom_metadata).length > 0) {
       Object.keys(updated_custom_metadata).forEach((key, index) => {
-        console.log(`${index + 1}: ${key}: ${updated_custom_metadata[key]}`)
+        output.info(`${index + 1}: ${key}: ${updated_custom_metadata[key]}`)
       })
     } else {
-      console.log('The custom metadata param is empty.')
+      output.info('The custom metadata param is empty.')
     }
   }
 
@@ -29,7 +31,7 @@ export const interactForCustomMetadata = async (
   do {
     displayCurrentCustomMetadata()
 
-    const response = await prompts({
+    const response = await prompt({
       type: 'select',
       name: 'action',
       message: 'Choose an action:',
@@ -43,13 +45,13 @@ export const interactForCustomMetadata = async (
     action = response.action
 
     if (action === 'add') {
-      const { newKey } = await prompts({
+      const { newKey } = await prompt({
         type: 'text',
         name: 'newKey',
         message: 'Enter a key to add or edit:',
       })
 
-      let { newValue } = await prompts({
+      let { newValue } = await prompt({
         type: 'text',
         name: 'newValue',
         message: 'Enter the new value to add or edit (or null to delete):',
@@ -65,7 +67,7 @@ export const interactForCustomMetadata = async (
         }
       }
     } else if (action === 'remove') {
-      const { custom_key_to_remove } = await prompts({
+      const { custom_key_to_remove } = await prompt({
         type: 'select',
         name: 'custom_key_to_remove',
         message: 'Choose a key-value pair to remove from params:',

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

@@ -1,33 +1,35 @@
 import { isApiKey, isPersonalAccessToken } from '@seamapi/http/connect'
 import chalk from 'chalk'
-import prompts from 'prompts'
 
 import { getConfigStore } from './config/index.js'
 import { getServer } from './get-server.js'
 import { interactForWorkspaceId } from './interact-for-workspace-id.js'
+import { getOutput } from './output/get-output.js'
+import { prompt } from './util/prompt.js'
 import { withLoading } from './util/with-loading.js'
 import { validateToken } from './validate-token.js'
 
 export const interactForLogin = async () => {
   const config = await getConfigStore()
+  const output = getOutput()
 
   if (getServer().includes('localhost')) {
-    console.log(
+    output.info(
       `You're using a local Seam Connect instance, you can enter the API Key to your local user, you can create a new user from:\n\n${getServer()}/admin/create_user_with_api_key`,
     )
   } else {
-    console.log(
+    output.info(
       `To login, navigate to the URL below and create a new Personal Access Token (PAT) and paste the PAT in the provided box:\n\nhttps://console.seam.co/settings/access-tokens\n\n`,
     )
   }
 
-  console.log(
+  output.info(
     chalk.gray(
       '> Note: You can enter an API Key here for single-workspace access',
     ),
   )
 
-  const { pat } = await prompts({
+  const { pat } = await prompt({
     name: 'pat',
     type: 'text',
     message: 'Personal Access Token:',
@@ -49,5 +51,5 @@ export const interactForLogin = async () => {
   }
 
   config.set(`${getServer()}.pat`, token)
-  console.log(`Token saved! You may begin using the CLI!`)
+  output.info(`Token saved! You may begin using the CLI!`)
 }

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/util/cli-args.ts

@@ -23,6 +23,20 @@ export const interactivityFlags: string[] = [
   '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.
  */
@@ -33,13 +47,27 @@ export class NonInteractiveError extends Error {
 export const parseCliArgs = (argv: string[]): ParsedArgs =>
   parseArgs(argv, {
     string: ['code'],
-    boolean: ['non-interactive', 'interactive'],
+    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 const getInteractivity = (args: ParsedArgs): Interactivity => {
+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
@@ -50,7 +78,9 @@ export const getInteractivity = (args: ParsedArgs): Interactivity => {
     )
   }
   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'
 }
 

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