@seamapi/cli 0.16.0 → 0.17.0

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

@@ -14,7 +14,14 @@ 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'
+import {
+  promptAutocomplete,
+  promptAutocompleteMultiselect,
+  promptConfirm,
+  promptNumber,
+  promptSelect,
+  promptText,
+} from './util/prompt.js'
 
 const ergonomicPropOrder = [
   'name',
@@ -84,23 +91,21 @@ export const interactForBlueprintObject = async (
     : `[${cmdPath}] Parameters`
 
   getOutput().info()
-  const { paramToEdit } = await prompt({
-    name: 'paramToEdit',
+  const paramToEdit = await promptAutocomplete({
     message: parameterSelectionMessage,
-    type: 'autocomplete',
     choices: [
       ...(haveAllRequiredParams && !args.isSubProperty
         ? [
             {
               value: 'done',
-              title: `[Make API Call] ${cmdPath}`,
+              label: `[Make API Call] ${cmdPath}`,
             },
           ]
         : []),
       ...(haveAllRequiredParams && args.isSubProperty
         ? [
             {
-              title: `[Save]`,
+              label: `[Save]`,
               value: 'done',
             },
           ]
@@ -108,9 +113,9 @@ export const interactForBlueprintObject = async (
       ...Object.keys(properties)
         .map((k) => {
           return {
-            title: k + (required.includes(k) ? '*' : ''),
+            label: k + (required.includes(k) ? '*' : ''),
             value: k,
-            description:
+            hint:
               args.params[k] !== undefined
                 ? typeof args.params[k] === 'object'
                   ? ellipsis(JSON.stringify(args.params[k]), 60)
@@ -122,13 +127,13 @@ export const interactForBlueprintObject = async (
       ...(args.isSubProperty
         ? [
             {
-              title: `[Leave Empty]`,
+              label: `[Leave Empty]`,
               value: 'empty',
             },
           ]
         : []),
       {
-        title: `[Back]`,
+        label: `[Back]`,
         value: 'back',
       },
     ],
@@ -201,36 +206,26 @@ export const interactForBlueprintObject = async (
       if (prop.format === 'datetime') {
         value = await interactForTimestamp()
       } else {
-        value = (
-          await prompt({
-            name: 'value',
-            message: `${paramToEdit}:`,
-            type: 'text',
-          })
-        ).value
+        value = await promptText({
+          message: `${paramToEdit}:`,
+        })
       }
       args.params[paramToEdit] = value
       return interactForBlueprintObject(args, ctx)
     } else if (prop.format === 'enum') {
-      const value = (
-        await prompt({
-          name: 'value',
-          message: `${paramToEdit}:`,
-          type: 'select',
-          choices: prop.values.map((v) => ({
-            title: v.name,
-            value: v.name,
-          })),
-        })
-      ).value
+      const value = await promptSelect({
+        message: `${paramToEdit}:`,
+        choices: prop.values.map((v) => ({
+          label: v.name,
+          value: v.name,
+        })),
+      })
       args.params[paramToEdit] = value
       return interactForBlueprintObject(args, ctx)
     } else if (prop.format === 'boolean') {
-      const { value } = await prompt({
-        name: 'value',
+      const value = await promptConfirm({
         message: `${paramToEdit}:`,
-        type: 'toggle',
-        initial: true,
+        initialValue: true,
         active: 'true',
         inactive: 'false',
       })
@@ -239,17 +234,13 @@ export const interactForBlueprintObject = async (
 
       return interactForBlueprintObject(args, ctx)
     } else if (prop.format === 'list' && prop.itemFormat === 'enum') {
-      const value = (
-        await prompt({
-          name: 'value',
-          message: `${paramToEdit}:`,
-          type: 'autocompleteMultiselect',
-          choices: prop.itemEnumValues.map((v) => ({
-            title: v.name,
-            value: v.name,
-          })),
-        })
-      ).value
+      const value = await promptAutocompleteMultiselect({
+        message: `${paramToEdit}:`,
+        choices: prop.itemEnumValues.map((v) => ({
+          label: v.name,
+          value: v.name,
+        })),
+      })
       args.params[paramToEdit] = value
       return interactForBlueprintObject(args, ctx)
     } else if (prop.format === 'list') {
@@ -271,10 +262,8 @@ export const interactForBlueprintObject = async (
       )
       return interactForBlueprintObject(args, ctx)
     } else if (prop.format === 'number') {
-      const { value } = await prompt({
-        name: 'value',
+      const value = await promptNumber({
         message: `${paramToEdit}:`,
-        type: 'number',
       })
 
       args.params[paramToEdit] = value

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

@@ -2,7 +2,7 @@ import { isDeepStrictEqual as isEqual } from 'node:util'
 
 import type { ContextHelpers } from './types.js'
 import { NonInteractiveError } from './util/cli-args.js'
-import { prompt } from './util/prompt.js'
+import { promptAutocomplete } from './util/prompt.js'
 
 const uniqBy = <T>(items: T[], keyOf: (item: T) => unknown): T[] => {
   const seen = new Set<unknown>()
@@ -92,28 +92,22 @@ export async function interactForCommandSelection(
 
   const commandPathStr = commandPath.join('/').replace(/-/g, '_')
 
-  const res = await prompt({
-    name: 'Command',
-    type: 'autocomplete',
+  const selectedCommand = await promptAutocomplete({
+    message: `Select a command: /${commandPathStr}`,
     choices: [
       ...possibleCommands.map((cmd) => ({
-        title:
+        label:
           cmd?.[commandPath.length] ?? `[Call /${commandPathStr} Directly]`,
         value: cmd?.[commandPath.length] ?? '<none>',
       })),
     ].sort((a, b) => ergonomicSort(a.value, b.value)),
-    message: `Select a command: /${commandPathStr}`,
   })
 
-  if (res?.Command === undefined) {
-    throw new Error('Bailed')
-  }
-
-  if (res?.Command === '<none>') {
+  if (selectedCommand === '<none>') {
     return commandPath
   }
 
-  const newCommandPath = [...commandPath, res.Command]
+  const newCommandPath = [...commandPath, selectedCommand]
 
   const fullCommand = possibleCommands.find((cmd) =>
     isEqual(newCommandPath, cmd),

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

@@ -1,5 +1,5 @@
 import { getOutput } from './output/get-output.js'
-import { prompt } from './util/prompt.js'
+import { promptSelect, promptText } 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.
@@ -31,29 +31,21 @@ export const interactForCustomMetadata = async (
   do {
     displayCurrentCustomMetadata()
 
-    const response = await prompt({
-      type: 'select',
-      name: 'action',
+    action = await promptSelect({
       message: 'Choose an action:',
       choices: [
-        { title: 'Add an item to params', value: 'add' },
-        { title: 'Remove an item from params', value: 'remove' },
-        { title: 'Finish editing params', value: 'done' },
+        { label: 'Add an item to params', value: 'add' },
+        { label: 'Remove an item from params', value: 'remove' },
+        { label: 'Finish editing params', value: 'done' },
       ],
     })
 
-    action = response.action
-
     if (action === 'add') {
-      const { newKey } = await prompt({
-        type: 'text',
-        name: 'newKey',
+      const newKey = await promptText({
         message: 'Enter a key to add or edit:',
       })
 
-      let { newValue } = await prompt({
-        type: 'text',
-        name: 'newValue',
+      let newValue: string | boolean = await promptText({
         message: 'Enter the new value to add or edit (or null to delete):',
       })
       if (newKey) {
@@ -67,21 +59,17 @@ export const interactForCustomMetadata = async (
         }
       }
     } else if (action === 'remove') {
-      const { customKeyToRemove } = await prompt({
-        type: 'select',
-        name: 'customKeyToRemove',
+      const customKeyToRemove = await promptSelect({
         message: 'Choose a key-value pair to remove from params:',
         choices: Object.keys(updatedCustomMetadata).map((customMetadataKey) => {
           return {
-            title: `${customMetadataKey}: ${updatedCustomMetadata[customMetadataKey]}`,
+            label: `${customMetadataKey}: ${updatedCustomMetadata[customMetadataKey]}`,
             value: customMetadataKey,
           }
         }),
       })
 
-      if (customKeyToRemove) {
-        delete customMetadata[customKeyToRemove]
-      }
+      delete customMetadata[customKeyToRemove]
     }
   } while (action !== 'done')
 

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

@@ -6,7 +6,7 @@ import { assertEnvVarUnset, getTokenFromEnv, tokenEnvVar } from './env.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 { promptText } from './util/prompt.js'
 import { withLoading } from './util/with-loading.js'
 import { validateToken } from './validate-token.js'
 
@@ -32,12 +32,10 @@ export const interactForLogin = async () => {
     ),
   )
 
-  const { pat } = await prompt({
-    name: 'pat',
-    type: 'text',
+  const pat = await promptText({
     message: 'Personal Access Token:',
   })
-  const token = pat?.trim()
+  const token = pat.trim()
 
   if (!token) {
     throw new Error('No token provided')

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

@@ -1,4 +1,4 @@
-import { prompt } from './util/prompt.js'
+import { promptAutocomplete } from './util/prompt.js'
 import { withLoading } from './util/with-loading.js'
 
 export interface ResourceChoice {
@@ -22,12 +22,11 @@ export const interactForResource = async <Resource>({
     `Fetching ${resourceName.replace(/_/g, ' ')}s...`,
     fetchResources,
   )
-  const { resourceId } = await prompt({
-    name: 'resourceId',
-    type: 'autocomplete',
+  return await promptAutocomplete({
     message,
-    choices: resources.map(toChoice),
+    choices: resources.map((resource) => {
+      const { title, value, description } = toChoice(resource)
+      return { label: title, value, hint: description }
+    }),
   })
-
-  return resourceId as string
 }

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

@@ -10,7 +10,7 @@ import {
 } from './env.js'
 import { getServer } from './get-server.js'
 import { getOutput } from './output/get-output.js'
-import { prompt } from './util/prompt.js'
+import { promptAutocomplete, promptText } from './util/prompt.js'
 
 export async function interactForServerSelection() {
   assertEnvVarUnset(endpointEnvVar, getEndpointFromEnv(), 'select a server')
@@ -21,27 +21,19 @@ export async function interactForServerSelection() {
     'https://fakeseamconnect.seam.vc',
   ]
 
-  const { server } = await prompt([
-    {
-      // Searchable, as selecting a device or a command is.
-      type: 'autocomplete',
-      name: 'server',
-      message: 'Select a server:',
-      choices: servers.map((server) => ({ title: server, value: server })),
-    },
-  ])
+  // Searchable, as selecting a device or a command is.
+  const server = await promptAutocomplete({
+    message: 'Select a server:',
+    choices: servers.map((server) => ({ label: server, value: server })),
+  })
 
   const config = getConfigStore()
   const output = getOutput()
   if (server === servers[2]) {
-    let { userUrlSeed } = await prompt([
-      {
-        type: 'text',
-        name: 'userUrlSeed',
-        message:
-          'You can input a custom server URL or leave this field empty to use a new fakeserver.',
-      },
-    ])
+    let userUrlSeed = await promptText({
+      message:
+        'You can input a custom server URL or leave this field empty to use a new fakeserver.',
+    })
 
     if (userUrlSeed.trim().length === 0) {
       userUrlSeed = randomBytes(5).toString('hex')

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

@@ -1,10 +1,19 @@
-import { prompt } from './util/prompt.js'
+import { promptText } from './util/prompt.js'
+
 export const interactForTimestamp = async () => {
-  const { timestamp } = await prompt({
-    name: 'timestamp',
-    type: 'date',
+  const now = new Date().toISOString()
+  const timestamp = await promptText({
     message: 'Enter a timestamp:',
+    placeholder: now,
+    defaultValue: now,
+    validate: (value) => {
+      if (value == null || value === '') return undefined
+      if (Number.isNaN(new Date(value).getTime())) {
+        return `Enter a valid timestamp, e.g. ${now}`
+      }
+      return undefined
+    },
   })
 
-  return timestamp.toISOString()
+  return new Date(timestamp).toISOString()
 }

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

@@ -1,25 +1,21 @@
 import { getConfigStore } from './config/index.js'
 import { getOutput } from './output/get-output.js'
-import { prompt } from './util/prompt.js'
+import { promptSelect } from './util/prompt.js'
 
 export async function interactForUseRemoteApiDefs() {
-  const { useRemoteApiDefs } = await prompt([
-    {
-      type: 'select',
-      name: 'useRemoteApiDefs',
-      message: 'Always use remote API Definitions?',
-      choices: [
-        {
-          title: 'Yes',
-          value: true,
-        },
-        {
-          title: 'No',
-          value: false,
-        },
-      ],
-    },
-  ])
+  const useRemoteApiDefs = await promptSelect({
+    message: 'Always use remote API Definitions?',
+    choices: [
+      {
+        label: 'Yes',
+        value: true,
+      },
+      {
+        label: 'No',
+        value: false,
+      },
+    ],
+  })
 
   const config = getConfigStore()
   config.set('use_remote_api_defs', useRemoteApiDefs)

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

@@ -8,7 +8,7 @@ import {
 } from './env.js'
 import { getSeamMultiWorkspace } from './get-seam.js'
 import { getServer } from './get-server.js'
-import { prompt } from './util/prompt.js'
+import { promptAutocomplete } from './util/prompt.js'
 import { withLoading } from './util/with-loading.js'
 
 export const interactForWorkspaceId = async (personalAccessToken?: string) => {
@@ -29,23 +29,17 @@ export const interactForWorkspaceId = async (personalAccessToken?: string) => {
   const workspaces = await withLoading('Fetching workspaces...', () =>
     seam.workspaces.list(),
   )
-  const { workspaceId } = await prompt({
-    name: 'workspaceId',
-    // Searchable, as selecting a device or a command is: an account may have
-    // more workspaces than fit on a screen.
-    type: 'autocomplete',
+  // Searchable, as selecting a device or a command is: an account may have
+  // more workspaces than fit on a screen.
+  const workspaceId = await promptAutocomplete<string>({
     message: 'Select a workspace:',
     choices: workspaces.map((workspace: any) => ({
-      title: workspace.name,
+      label: workspace.name,
       value: workspace.workspace_id,
-      description: workspace.workspace_id,
+      hint: workspace.workspace_id,
     })),
   })
 
-  if (workspaceId) {
-    config.set('current_workspace_id', workspaceId)
-    return workspaceId
-  }
-
-  throw new Error('Bailed')
+  config.set('current_workspace_id', workspaceId)
+  return workspaceId
 }

package/src/lib/util/prompt.ts

@@ -1,4 +1,12 @@
-import prompts, { type Answers, type Options, type PromptObject } from 'prompts'
+import {
+  autocomplete,
+  autocompleteMultiselect,
+  confirm,
+  isCancel,
+  type Option,
+  select,
+  text,
+} from '@clack/prompts'
 
 import { NonInteractiveError } from './cli-args.js'
 
@@ -13,62 +21,154 @@ import { NonInteractiveError } from './cli-args.js'
 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>> => {
+/** The user dismissed a prompt with ctrl-c or escape instead of answering. */
+export class PromptCancelledError extends Error {
+  constructor() {
+    super('Cancelled')
+  }
+}
+
+export interface PromptChoice<Value> {
+  label: string
+  value: Value
+  hint?: string | undefined
+}
+
+const ensureInteractive = (): void => {
   if (!canPrompt()) {
     throw new NonInteractiveError(
       'Cannot prompt without a terminal: pass the missing arguments, or pipe them in as JSON',
     )
   }
+}
+
+const unwrap = <Value>(value: Value | symbol): Value => {
+  if (isCancel(value)) throw new PromptCancelledError()
+  return value as Value
+}
+
+// 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.
+const output = process.stderr
+
+const toOptions = <Value>(
+  choices: Array<PromptChoice<Value>>,
+): Array<Option<Value>> =>
+  choices.map(
+    ({ label, value, hint }) =>
+      (hint === undefined
+        ? { label, value }
+        : { label, value, hint }) as Option<Value>,
+  )
 
-  const questionList = Array.isArray(questions) ? questions : [questions]
-
-  return await prompts(
-    questionList.map((question) => ({
-      ...question,
-      // Search a list by any part of a name, rather than only by what it
-      // starts with, which is all prompts does for itself.
-      ...(question.type === 'autocomplete' && question.suggest == null
-        ? { suggest: searchChoices }
-        : {}),
-      stdout: process.stderr,
-    })),
-    options,
+export const promptText = async (options: {
+  message: string
+  placeholder?: string
+  defaultValue?: string
+  validate?: (value: string | undefined) => string | undefined
+}): Promise<string> => {
+  ensureInteractive()
+  return unwrap(await text({ ...options, output }))
+}
+
+export const promptNumber = async (options: {
+  message: string
+  validate?: (value: number) => string | undefined
+}): Promise<number> => {
+  ensureInteractive()
+  const value = unwrap(
+    await text({
+      message: options.message,
+      validate: (value) => {
+        if (value == null || value.trim() === '') return 'Enter a number'
+        const parsed = Number(value)
+        if (Number.isNaN(parsed)) return 'Enter a number'
+        return options.validate?.(parsed)
+      },
+      output,
+    }),
+  )
+  return Number(value)
+}
+
+export const promptConfirm = async (options: {
+  message: string
+  initialValue?: boolean
+  active?: string
+  inactive?: string
+}): Promise<boolean> => {
+  ensureInteractive()
+  return unwrap(await confirm({ ...options, output }))
+}
+
+export const promptSelect = async <Value>(options: {
+  message: string
+  choices: Array<PromptChoice<Value>>
+}): Promise<Value> => {
+  ensureInteractive()
+  return unwrap(
+    await select<Value>({
+      message: options.message,
+      options: toOptions(options.choices),
+      output,
+    }),
+  )
+}
+
+export const promptAutocomplete = async <Value>(options: {
+  message: string
+  choices: Array<PromptChoice<Value>>
+}): Promise<Value> => {
+  ensureInteractive()
+  return unwrap(
+    await autocomplete<Value>({
+      message: options.message,
+      options: toOptions(options.choices),
+      // Search a list by any part of a name or hint, rather than only by
+      // the label, which is all clack matches for itself.
+      filter: searchChoices,
+      output,
+    }),
+  )
+}
+
+export const promptAutocompleteMultiselect = async <Value>(options: {
+  message: string
+  choices: Array<PromptChoice<Value>>
+}): Promise<Value[]> => {
+  ensureInteractive()
+  return unwrap(
+    await autocompleteMultiselect<Value>({
+      message: options.message,
+      options: toOptions(options.choices),
+      filter: searchChoices,
+      output,
+    }),
   )
 }
 
 export interface SearchableChoice {
-  title?: string | undefined
-  description?: string | undefined
+  label?: string | undefined
+  hint?: string | undefined
 }
 
 /**
- * Filter choices by every whitespace separated term of the input, matched
- * case insensitively against the title and the description.
+ * Match a choice by every whitespace separated term of the input, matched
+ * case insensitively against the label and the hint.
  */
-export const searchChoices = async <Choice extends SearchableChoice>(
+export const searchChoices = (
   input: string,
-  choices: Choice[],
-): Promise<Choice[]> => {
+  choice: SearchableChoice,
+): boolean => {
   const terms = input
     .toLowerCase()
     .split(/\s+/)
     .filter((term) => term.length > 0)
 
-  if (terms.length === 0) return choices
+  if (terms.length === 0) return true
 
-  return choices.filter((choice) => {
-    const searchable = `${choice.title ?? ''} ${choice.description ?? ''}`
-      .toLowerCase()
-      .trim()
-    return terms.every((term) => searchable.includes(term))
-  })
+  const searchable = `${choice.label ?? ''} ${choice.hint ?? ''}`
+    .toLowerCase()
+    .trim()
+  return terms.every((term) => searchable.includes(term))
 }