@seamapi/cli 0.10.0 → 0.12.0

package/src/lib/completion/render-zsh.ts

@@ -0,0 +1,157 @@
+import {
+  type CommandFlag,
+  type CommandSpec,
+  flagTokens,
+} from '../command-spec.js'
+import { describeForShell } from './describe.js'
+
+export const renderZshCompletion = (spec: CommandSpec): string => {
+  const valuelessTokens = spec.globalFlags
+    .filter(({ takesValue }) => !takesValue)
+    .flatMap(flagTokens)
+    .sort()
+
+  return `${[
+    header,
+    renderCase('_seam_subcommands', subcommandBranches(spec)),
+    renderCase('_seam_flags', flagBranches(spec)),
+    renderCase('_seam_flag_values', flagValueBranches(spec)),
+    `_seam_global_flags() {\n  _seam_reply+=(${describeFlags(spec.globalFlags)})\n}`,
+    completionFunction(valuelessTokens),
+    dispatch,
+  ].join('\n\n')}\n`
+}
+
+const header = `#compdef seam
+
+# zsh completion for the seam command.
+#
+# Generated by @seamapi/cli from the Seam API definitions.
+# Do not edit: regenerate with 'seam completion zsh'.
+#
+# Load it for the current shell with
+#
+#   source <(seam completion zsh)
+#
+# or install it for every shell with
+#
+#   seam completion zsh > "\${fpath[1]}/_seam"`
+
+const completionFunction = (valuelessTokens: string[]): string =>
+  `_seam() {
+  local -a _seam_reply
+  local -a valueless
+  local command previous word
+  local -i index
+
+  valueless=(${valuelessTokens.join(' ')})
+
+  # The command path is the run of words before the first flag.
+  command=''
+  for (( index = 2; index < CURRENT; index++ )); do
+    word="\${words[index]}"
+    if [[ "$word" == -* ]]; then
+      break
+    fi
+    command="\${command:+$command }$word"
+  done
+
+  previous=''
+  if (( CURRENT > 1 )); then
+    previous="\${words[CURRENT - 1]}"
+  fi
+
+  # Completing the value of a flag that takes one.
+  if [[ "$previous" == -* ]] && (( \${valueless[(Ie)$previous]} == 0 )); then
+    _seam_flag_values "$command $previous"
+    if (( \${#_seam_reply} )); then
+      _describe -t values 'value' _seam_reply
+    fi
+    return
+  fi
+
+  if [[ "\${words[CURRENT]}" == -* ]]; then
+    _seam_flags "$command"
+    _seam_global_flags
+    _describe -t options 'option' _seam_reply
+    return
+  fi
+
+  _seam_subcommands "$command"
+  if (( \${#_seam_reply} )); then
+    _describe -t commands 'command' _seam_reply
+    return
+  fi
+
+  _seam_flags "$command"
+  _seam_global_flags
+  _describe -t options 'option' _seam_reply
+}`
+
+// The script runs in three ways. Autoloaded from fpath as _seam, it must
+// complete the in-flight request: funcstack holds _seam. Evaluated by the
+// loader stub inside the autoloaded _seam, the same applies, but eval pushes
+// '(eval)' onto funcstack, so search the whole stack rather than the top.
+// Sourced into a shell, funcstack holds no _seam: register with compdef.
+const dispatch = `if (( \${funcstack[(I)_seam]} )); then
+  _seam "$@"
+else
+  compdef _seam seam
+fi`
+
+interface Branch {
+  pattern: string
+  entries: string[]
+}
+
+const subcommandBranches = (spec: CommandSpec): Branch[] =>
+  spec.groups.map((group) => ({
+    pattern: group.path.join(' '),
+    entries: group.subcommands.map(({ name, description }) =>
+      describe(name, description),
+    ),
+  }))
+
+const flagBranches = (spec: CommandSpec): Branch[] =>
+  spec.commands
+    .filter(({ flags }) => flags.length > 0)
+    .map((command) => ({
+      pattern: command.path.join(' '),
+      entries: [describeFlags(command.flags)],
+    }))
+
+const flagValueBranches = (spec: CommandSpec): Branch[] =>
+  spec.commands.flatMap((command) =>
+    command.flags
+      .filter(({ values }) => values.length > 0)
+      .flatMap((flag) =>
+        flagTokens(flag).map((token) => ({
+          pattern: `${command.path.join(' ')} ${token}`,
+          entries: flag.values.map((value) => `'${value}'`),
+        })),
+      ),
+  )
+
+const describeFlags = (flags: CommandFlag[]): string =>
+  flags
+    .flatMap((flag) =>
+      flagTokens(flag).map((token) => describe(token, flag.description)),
+    )
+    .join(' ')
+
+const describe = (value: string, description: string): string => {
+  const summary = describeForShell(description)
+  return summary === '' ? `'${value}'` : `'${value}:${summary}'`
+}
+
+const renderCase = (name: string, branches: Branch[]): string =>
+  [
+    `${name}() {`,
+    `  case "$1" in`,
+    ...branches.map(
+      ({ pattern, entries }) =>
+        `    ('${pattern}') _seam_reply+=(${entries.join(' ')}) ;;`,
+    ),
+    `  esac`,
+    `}`,
+  ].join('\n')

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,9 +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',
@@ -82,8 +83,8 @@ export const interactForBlueprintObject = async (
     ? `Editing "${args.subPropertyPath}"`
     : `[${cmdPath}] Parameters`
 
-  console.log('')
-  const { paramToEdit } = await prompts({
+  getOutput().info()
+  const { paramToEdit } = await prompt({
     name: 'paramToEdit',
     message: parameterSelectionMessage,
     type: 'autocomplete',
@@ -203,7 +204,7 @@ export const interactForBlueprintObject = async (
         value = await interactForTimestamp()
       } else {
         value = (
-          await prompts({
+          await prompt({
             name: 'value',
             message: `${paramToEdit}:`,
             type: 'text',
@@ -214,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',
@@ -227,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',
@@ -241,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',
@@ -272,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,9 +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>()
@@ -93,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!`)
 }

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