@seamapi/cli 0.9.0 → 0.11.0

package/src/bin/cli.ts

@@ -4,11 +4,11 @@ import { isDeepStrictEqual as isEqual } from 'node:util'
 
 import chalk from 'chalk'
 import commandLineUsage from 'command-line-usage'
-import parseArgs, { type ParsedArgs } from 'minimist'
-import prompts from 'prompts'
+import type { ParsedArgs } from 'minimist'
 
 import { getConfigStore } from 'lib/config/index.js'
 import { getApiBlueprint } from 'lib/get-api-blueprint.js'
+import { getResponseKey } from 'lib/get-response-key.js'
 import { getServer } from 'lib/get-server.js'
 import { interactForActionAttemptPoll } from 'lib/interact-for-action-attempt-poll.js'
 import { interactForCommandParams } from 'lib/interact-for-command-params.js'
@@ -17,7 +17,19 @@ import { interactForLogin } from 'lib/interact-for-login.js'
 import { interactForServerSelection } from 'lib/interact-for-server-selection.js'
 import { interactForUseRemoteApiDefs } from 'lib/interact-for-use-remote-api-defs.js'
 import { interactForWorkspaceId } from 'lib/interact-for-workspace-id.js'
+import { createOutput } from 'lib/output/create-output.js'
+import { getOutput, setOutput } from 'lib/output/get-output.js'
+import { resolveOutputFormat } from 'lib/output/resolve-output-format.js'
 import type { ContextHelpers } from 'lib/types.js'
+import {
+  cliFlags,
+  getInteractivity,
+  type Interactivity,
+  NonInteractiveError,
+  parseCliArgs,
+} from 'lib/util/cli-args.js'
+import { canPrompt, prompt } from 'lib/util/prompt.js'
+import { readStdinJson } from 'lib/util/read-stdin-json.js'
 import { RequestSeamApi } from 'lib/util/request-seam-api.js'
 import { validateToken } from 'lib/validate-token.js'
 import seamapiCliVersion from 'lib/version.js'
@@ -26,7 +38,7 @@ const sections = [
   {
     header: 'Seam CLI',
     content:
-      'Every seam command is interactive and will prompt you for any missing required properties with helpful suggestions. To avoid automatic behavior, pass -y ',
+      'Every seam command runs as soon as every required property is given, and otherwise prompts you for what is missing with helpful suggestions. Pass -i to always review properties first, or -y to never be prompted. ',
   },
   {
     header: 'Options',
@@ -37,6 +49,26 @@ const sections = [
         alias: 'h',
         type: Boolean,
       },
+      {
+        name: 'interactive',
+        description:
+          'Always prompt to review and edit properties, prefilled with the given arguments.',
+        alias: 'i',
+        type: Boolean,
+      },
+      {
+        name: 'non-interactive',
+        description:
+          'Never prompt: exit with an error if the command or any required property is missing.',
+        alias: 'y',
+        type: Boolean,
+      },
+      {
+        name: 'json',
+        description:
+          'Write the response to stdout as JSON. Enabled automatically when stdout is not a terminal, disable with {bold --no-json}.',
+        type: Boolean,
+      },
       {
         name: 'update',
         description: 'Force an update of the cached Seam API definitions.',
@@ -44,6 +76,14 @@ const sections = [
       },
     ],
   },
+  {
+    header: 'Output',
+    content: [
+      'Only the response is written to stdout, so it is safe to pipe. Prompts, progress, and other information are written to stderr.',
+      'The response is trimmed to the response key and pagination.',
+      'Request params may be piped or redirected in as a JSON object. Params given as arguments win over params read from stdin.',
+    ],
+  },
   {
     header: 'Command List Examples',
     content: [
@@ -59,6 +99,14 @@ const sections = [
         summary: 'Create a connect webview to connect devices.',
       },
       { name: 'seam devices list', summary: 'List devices in your workspace.' },
+      {
+        name: 'seam devices list {bold --interactive}',
+        summary: 'Review and edit filters before listing devices.',
+      },
+      {
+        name: 'seam devices list {bold --non-interactive}',
+        summary: 'List devices, failing instead of prompting.',
+      },
       {
         name: 'seam locks unlock-door {bold --device-id} $MY_DOOR',
         summary: 'Unlock a lock.',
@@ -71,22 +119,30 @@ const sections = [
         name: 'seam access-codes list {bold --device-id} $MY_DOOR',
         summary: 'List you access codes.',
       },
+      {
+        name: 'seam devices list > devices.json',
+        summary: 'Write the response to a file as JSON.',
+      },
+      {
+        name: 'cat params.json | seam locks unlock-door',
+        summary: 'Pipe request params in as JSON.',
+      },
     ],
   },
 ]
 
 async function cli(args: ParsedArgs) {
   const config = getConfigStore()
+  const output = getOutput()
 
   if (args['help'] || args['h']) {
-    const usage = commandLineUsage(sections)
-    console.log(usage)
+    output.text(commandLineUsage(sections))
     return
   }
 
   if (args['version']) {
-    console.log(seamapiCliVersion)
-    process.exit(0)
+    output.text(seamapiCliVersion)
+    return
   }
 
   if (
@@ -98,10 +154,10 @@ async function cli(args: ParsedArgs) {
     const fakeApiUrl = `https://${randomstring}.fakeseamconnect.seam.vc`
 
     config.set('server', fakeApiUrl)
-    console.log(`Server URL set to ${fakeApiUrl}`)
+    output.info(`Server URL set to ${fakeApiUrl}`)
 
     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"`)
     return
   }
 
@@ -110,8 +166,9 @@ async function cli(args: ParsedArgs) {
     args._[0] !== 'login' &&
     !isEqual(args._, ['select', 'server'])
   ) {
-    console.log(`Not logged in. Please run "seam login"`)
-    process.exit(1)
+    output.error(`Not logged in. Please run "seam login"`)
+    process.exitCode = 1
+    return
   }
 
   args._ = args._.map((arg) => arg.toLowerCase().replace(/_/g, '-'))
@@ -129,24 +186,25 @@ async function cli(args: ParsedArgs) {
     update,
   })
 
-  const commandParams: Record<string, any> = {}
-
-  /**
-   * Whether or not to auto-select first option
-   */
-  const is_interactive = args['y'] !== true
+  // Params piped or redirected in, e.g., `seam devices list < params.json`.
+  // Params given as arguments take precedence over these.
+  const commandParams: Record<string, any> = { ...(await readStdinJson()) }
 
   const ctx: ContextHelpers = {
     blueprint,
-    is_interactive,
+    interactivity: getInteractivity(args, { canPrompt: canPrompt() }),
   }
 
+  const isNonInteractive = ctx.interactivity === 'non-interactive'
+
   for (const k in args) {
     if (k === '_') continue
     const v = args[k]
     delete args[k]
-    args[k.replace(/-/g, '_')] = v
-    commandParams[k.replace(/-/g, '_')] = v
+    const key = k.replace(/-/g, '_')
+    args[key] = v
+    if (cliFlags.includes(key)) continue
+    commandParams[key] = v
   }
 
   const selectedCommand = await interactForCommandSelection(args._, ctx)
@@ -167,19 +225,34 @@ async function cli(args: ParsedArgs) {
     if (args['token'] || args['workspace_id'] || args['server']) {
       return
     }
+    if (isNonInteractive) {
+      throw new NonInteractiveError(
+        'Missing required parameter for login: --token',
+      )
+    }
     await interactForLogin()
     return
   } else if (isEqual(selectedCommand, ['logout'])) {
     config.delete('pat')
-    console.log('Logged out!')
+    output.info('Logged out!')
     return
   } else if (isEqual(selectedCommand, ['config', 'reveal-location'])) {
-    console.log(config.path)
+    output.text(config.path)
     return
   } else if (isEqual(selectedCommand, ['config', 'use-remote-api-defs'])) {
+    if (isNonInteractive) {
+      throw new NonInteractiveError(
+        'Cannot select whether to use remote API definitions in non-interactive mode',
+      )
+    }
     await interactForUseRemoteApiDefs()
     return
   } else if (isEqual(selectedCommand, ['select', 'workspace'])) {
+    if (isNonInteractive) {
+      throw new NonInteractiveError(
+        'Cannot select a workspace in non-interactive mode: pass --workspace-id to "seam login"',
+      )
+    }
     await interactForWorkspaceId()
     return
   } else if (isEqual(selectedCommand, ['events', 'list'])) {
@@ -194,6 +267,11 @@ async function cli(args: ParsedArgs) {
       config.delete('current_workspace_id')
       return
     }
+    if (isNonInteractive) {
+      throw new NonInteractiveError(
+        'Missing required parameter for select server: --server',
+      )
+    }
     await interactForServerSelection()
     return
   } else if (isEqual(selectedCommand, ['health', 'get-health'])) {
@@ -243,22 +321,32 @@ async function cli(args: ParsedArgs) {
   const response = await RequestSeamApi({
     path: apiPath,
     params,
+    responseKey: getResponseKey(selectedCommand, ctx),
   })
 
   if (response.data?.connect_webview) {
-    await handleConnectWebviewResponse(response.data.connect_webview)
+    await handleConnectWebviewResponse(
+      response.data.connect_webview,
+      ctx.interactivity,
+    )
   }
 
-  if (response.data?.action_attempt) {
-    interactForActionAttemptPoll(response.data.action_attempt)
+  if (response.data?.action_attempt && !isNonInteractive) {
+    await interactForActionAttemptPoll(response.data.action_attempt)
   }
 }
 
-const handleConnectWebviewResponse = async (connect_webview: any) => {
+const handleConnectWebviewResponse = async (
+  connect_webview: any,
+  interactivity: Interactivity,
+) => {
   const url = connect_webview.url
 
-  if (process.env['INSIDE_WEB_BROWSER'] !== '1') {
-    const { action } = await prompts({
+  if (
+    interactivity !== 'non-interactive' &&
+    process.env['INSIDE_WEB_BROWSER'] !== '1'
+  ) {
+    const { action } = await prompt({
       type: 'confirm',
       name: 'action',
       message: 'Would you like to open the webview in your browser?',
@@ -281,12 +369,30 @@ const run = async (argv: string[]) => {
     return
   }
 
-  await cli(parseArgs(argv, { string: ['code'] }))
+  const args = parseCliArgs(argv)
+
+  const isTty = process.stdout.isTTY === true
+
+  setOutput(
+    createOutput({
+      format: resolveOutputFormat(argv, { isTty }),
+      colors: isTty,
+    }),
+  )
+
+  await cli(args)
 }
 
-run(process.argv.slice(2)).catch((e) => {
-  console.log(chalk.red(`CLI Error: ${e.toString()}\n${e.stack}`))
-  if (e.toString().includes('object Object')) {
-    console.log(e)
+run(process.argv.slice(2)).catch((e: unknown) => {
+  const output = getOutput()
+  process.exitCode = 1
+
+  if (e instanceof NonInteractiveError) {
+    output.error(chalk.red(e.message))
+    return
   }
+
+  const error = e instanceof Error ? e : new Error(String(e))
+  output.error(chalk.red(`CLI Error: ${error.message}`))
+  if (error.stack != null) output.error(chalk.gray(error.stack))
 })

package/src/lib/get-response-key.ts

@@ -0,0 +1,25 @@
+import { getCommandBlueprintDef } from './get-command-blueprint-def.js'
+import type { ContextHelpers } from './types.js'
+
+/**
+ * The top level response key documented for a command,
+ * e.g., `devices` for `seam devices list`.
+ *
+ * Returns null when the command is not in the blueprint,
+ * or when it does not respond with a resource.
+ */
+export const getResponseKey = (
+  command: string[],
+  ctx: ContextHelpers,
+): string | null => {
+  let endpoint
+  try {
+    endpoint = getCommandBlueprintDef(command, ctx)
+  } catch {
+    return null
+  }
+
+  if (endpoint.response.responseType === 'void') return null
+
+  return endpoint.response.responseKey
+}

package/src/lib/interact-for-action-attempt-poll.ts

@@ -1,14 +1,15 @@
 import type { ActionAttemptsGetResponse } from '@seamapi/http/connect'
-import prompts from 'prompts'
 
 import { getSeam } from './get-seam.js'
+import { getOutput } from './output/get-output.js'
+import { prompt } from './util/prompt.js'
 import { withLoading } from './util/with-loading.js'
 
 export const interactForActionAttemptPoll = async (
   action_attempt: ActionAttemptsGetResponse['action_attempt'],
 ) => {
   if (action_attempt.status === 'pending') {
-    const { poll_for_action_attempt } = await prompts({
+    const { poll_for_action_attempt } = await prompt({
       name: 'poll_for_action_attempt',
       message: "Would you like to poll the action attempt until it's ready?",
       type: 'toggle',
@@ -29,7 +30,7 @@ export const interactForActionAttemptPoll = async (
             { waitForActionAttempt: { pollingInterval: 240, timeout: 10_000 } },
           ),
       )
-      console.dir(updated_action_attempt, { depth: null })
+      getOutput().data({ action_attempt: updated_action_attempt })
     }
   }
 }

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

@@ -1,19 +1,21 @@
-import prompts from 'prompts'
+import { getOutput } from './output/get-output.js'
+import { prompt } from './util/prompt.js'
 
 export const interactForArray = async (
   array: string[],
   message: string,
 ): Promise<string[]> => {
   const updatedArray = [...array]
+  const output = getOutput()
 
   const displayList = () => {
-    console.log(`${message} Current list:`)
+    output.info(`${message} Current list:`)
     if (updatedArray.length > 0) {
       updatedArray.forEach((item, index) => {
-        console.log(`${index + 1}: ${item}`)
+        output.info(`${index + 1}: ${item}`)
       })
     } else {
-      console.log('The list is currently empty.')
+      output.info('The list is currently empty.')
     }
   }
 
@@ -21,7 +23,7 @@ export const interactForArray = async (
   do {
     displayList()
 
-    const response = await prompts({
+    const response = await prompt({
       type: 'select',
       name: 'action',
       message: 'Choose an action:',
@@ -35,7 +37,7 @@ export const interactForArray = async (
     action = response.action
 
     if (action === 'add') {
-      const { newItem } = await prompts({
+      const { newItem } = await prompt({
         type: 'text',
         name: 'newItem',
         message: 'Enter the new item:',
@@ -44,7 +46,7 @@ export const interactForArray = async (
         updatedArray.push(newItem)
       }
     } else if (action === 'remove') {
-      const { index } = await prompts({
+      const { index } = await prompt({
         type: 'number',
         name: 'index',
         message: 'Enter the index of the item to remove:',

package/src/lib/interact-for-blueprint-object.ts

@@ -1,5 +1,4 @@
 import type { Parameter } from '@seamapi/blueprint'
-import prompts from 'prompts'
 
 import { interactForAccessCode } from './interact-for-access-code.js'
 import { interactForAcsEntrance } from './interact-for-acs-entrance.js'
@@ -11,8 +10,11 @@ import { interactForCustomMetadata } from './interact-for-custom-metadata.js'
 import { interactForDevice } from './interact-for-device.js'
 import { interactForTimestamp } from './interact-for-timestamp.js'
 import { interactForUserIdentity } from './interact-for-user-identity.js'
+import { getOutput } from './output/get-output.js'
 import type { ContextHelpers } from './types.js'
+import { NonInteractiveError, toArgName } from './util/cli-args.js'
 import { ellipsis } from './util/ellipsis.js'
+import { prompt } from './util/prompt.js'
 
 const ergonomicPropOrder = [
   'name',
@@ -47,12 +49,28 @@ export const interactForBlueprintObject = async (
 
   const haveAllRequiredParams = required.every((k) => args.params[k])
 
+  const cmdPath = `/${args.command.join('/').replace(/-/g, '_')}`
+
   const should_auto_submit =
-    !ctx.is_interactive && haveAllRequiredParams && !args.isSubProperty
+    ctx.interactivity !== 'interactive' &&
+    haveAllRequiredParams &&
+    !args.isSubProperty
   if (should_auto_submit) {
     return args.params
   }
 
+  if (ctx.interactivity === 'non-interactive') {
+    const missing = required.filter((k) => !args.params[k])
+    const target = args.isSubProperty ? `"${args.subPropertyPath}"` : cmdPath
+    throw new NonInteractiveError(
+      missing.length > 0
+        ? `Missing required ${
+            missing.length === 1 ? 'parameter' : 'parameters'
+          } for ${target}: ${missing.map(toArgName).join(' ')}`
+        : `Cannot prompt for ${target} in non-interactive mode`,
+    )
+  }
+
   const propSortScore = (prop: string) => {
     if (required.includes(prop)) return 100 - ergonomicPropOrder.indexOf(prop)
     if (args.params[prop] !== undefined) {
@@ -61,13 +79,12 @@ export const interactForBlueprintObject = async (
     return ergonomicPropOrder.indexOf(prop)
   }
 
-  const cmdPath = `/${args.command.join('/').replace(/-/g, '_')}`
   const parameterSelectionMessage = args.isSubProperty
     ? `Editing "${args.subPropertyPath}"`
     : `[${cmdPath}] Parameters`
 
-  console.log('')
-  const { paramToEdit } = await prompts({
+  getOutput().info()
+  const { paramToEdit } = await prompt({
     name: 'paramToEdit',
     message: parameterSelectionMessage,
     type: 'autocomplete',
@@ -187,7 +204,7 @@ export const interactForBlueprintObject = async (
         value = await interactForTimestamp()
       } else {
         value = (
-          await prompts({
+          await prompt({
             name: 'value',
             message: `${paramToEdit}:`,
             type: 'text',
@@ -198,7 +215,7 @@ export const interactForBlueprintObject = async (
       return interactForBlueprintObject(args, ctx)
     } else if (prop.format === 'enum') {
       const value = (
-        await prompts({
+        await prompt({
           name: 'value',
           message: `${paramToEdit}:`,
           type: 'select',
@@ -211,7 +228,7 @@ export const interactForBlueprintObject = async (
       args.params[paramToEdit] = value
       return interactForBlueprintObject(args, ctx)
     } else if (prop.format === 'boolean') {
-      const { value } = await prompts({
+      const { value } = await prompt({
         name: 'value',
         message: `${paramToEdit}:`,
         type: 'toggle',
@@ -225,7 +242,7 @@ export const interactForBlueprintObject = async (
       return interactForBlueprintObject(args, ctx)
     } else if (prop.format === 'list' && prop.itemFormat === 'enum') {
       const value = (
-        await prompts({
+        await prompt({
           name: 'value',
           message: `${paramToEdit}:`,
           type: 'autocompleteMultiselect',
@@ -256,7 +273,7 @@ export const interactForBlueprintObject = async (
       )
       return interactForBlueprintObject(args, ctx)
     } else if (prop.format === 'number') {
-      const { value } = await prompts({
+      const { value } = await prompt({
         name: 'value',
         message: `${paramToEdit}:`,
         type: 'number',

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

@@ -1,8 +1,8 @@
 import { isDeepStrictEqual as isEqual } from 'node:util'
 
-import prompts from 'prompts'
-
 import type { ContextHelpers } from './types.js'
+import { NonInteractiveError } from './util/cli-args.js'
+import { prompt } from './util/prompt.js'
 
 const uniqBy = <T>(items: T[], keyOf: (item: T) => unknown): T[] => {
   const seen = new Set<unknown>()
@@ -64,6 +64,26 @@ export async function interactForCommandSelection(
     return commandPath
   }
 
+  if (helpers.interactivity === 'non-interactive') {
+    // The command path is itself a command, so call it directly rather than
+    // prompting to select one of its sub-commands.
+    if (possibleCommands.some((cmd) => cmd.length === commandPath.length)) {
+      return commandPath
+    }
+
+    const subcommands = possibleCommands
+      .map((cmd) => cmd[commandPath.length])
+      .filter((subcommand) => subcommand != null)
+      .sort(ergonomicSort)
+    throw new NonInteractiveError(
+      `${
+        commandPath.length === 0
+          ? 'Missing command'
+          : `Incomplete command "seam ${commandPath.join(' ')}"`
+      }: expected one of ${subcommands.join(', ')}`,
+    )
+  }
+
   // Add dynamic 'back' command for sub-commands to allow returning
   // to previous level.
   if (commandPath.length > 0) {
@@ -72,7 +92,7 @@ export async function interactForCommandSelection(
 
   const commandPathStr = commandPath.join('/').replace(/-/g, '_')
 
-  const res = await prompts({
+  const res = await prompt({
     name: 'Command',
     type: 'autocomplete',
     choices: [

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!`)
 }