@seamapi/cli 0.17.1 → 0.18.1

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

@@ -17,10 +17,12 @@ import { ellipsis } from './util/ellipsis.js'
 import {
   promptAutocomplete,
   promptAutocompleteMultiselect,
+  PromptCancelledError,
   promptConfirm,
   promptNumber,
   promptSelect,
   promptText,
+  withBackHint,
 } from './util/prompt.js'
 
 const ergonomicPropOrder = [
@@ -88,58 +90,67 @@ export const interactForBlueprintObject = async (
     return ergonomicPropOrder.indexOf(prop)
   }
 
-  const parameterSelectionMessage = args.isSubProperty
-    ? `Editing "${args.subPropertyPath}"`
-    : `[${cmdPath}] Parameters`
+  const parameterSelectionMessage = withBackHint(
+    args.isSubProperty
+      ? `Editing "${args.subPropertyPath}"`
+      : `[${cmdPath}] Parameters`,
+  )
 
   getOutput().info()
-  const paramToEdit = await promptAutocomplete({
-    message: parameterSelectionMessage,
-    choices: [
-      ...(haveAllRequiredParams && !args.isSubProperty
-        ? [
-            {
-              value: 'done',
-              label: `[Make API Call] ${cmdPath}`,
-            },
-          ]
-        : []),
-      ...(haveAllRequiredParams && args.isSubProperty
-        ? [
-            {
-              label: `[Save]`,
-              value: 'done',
-            },
-          ]
-        : []),
-      ...Object.keys(properties)
-        .map((k) => {
-          return {
-            label: k + (required.includes(k) ? '*' : ''),
-            value: k,
-            hint:
-              args.params[k] !== undefined
-                ? typeof args.params[k] === 'object'
-                  ? ellipsis(JSON.stringify(args.params[k]), 60)
-                  : `[${args.params[k]}]`
-                : undefined,
-          }
-        })
-        .sort((a, b) => propSortScore(b.value) - propSortScore(a.value)),
-      ...(args.isSubProperty
-        ? [
-            {
-              label: `[Leave Empty]`,
-              value: 'empty',
-            },
-          ]
-        : []),
-      {
-        label: `[Back]`,
-        value: 'back',
-      },
-    ],
-  })
+  let paramToEdit: string
+  try {
+    paramToEdit = await promptAutocomplete({
+      message: parameterSelectionMessage,
+      choices: [
+        ...(haveAllRequiredParams && !args.isSubProperty
+          ? [
+              {
+                value: 'done',
+                label: `[Make API Call] ${cmdPath}`,
+              },
+            ]
+          : []),
+        ...(haveAllRequiredParams && args.isSubProperty
+          ? [
+              {
+                label: `[Save]`,
+                value: 'done',
+              },
+            ]
+          : []),
+        ...Object.keys(properties)
+          .map((k) => {
+            return {
+              label: k + (required.includes(k) ? '*' : ''),
+              value: k,
+              hint:
+                args.params[k] !== undefined
+                  ? typeof args.params[k] === 'object'
+                    ? ellipsis(JSON.stringify(args.params[k]), 60)
+                    : `[${args.params[k]}]`
+                  : undefined,
+            }
+          })
+          .sort((a, b) => propSortScore(b.value) - propSortScore(a.value)),
+        ...(args.isSubProperty
+          ? [
+              {
+                label: `[Leave Empty]`,
+                value: 'empty',
+              },
+            ]
+          : []),
+        {
+          label: `[Back]`,
+          value: 'back',
+        },
+      ],
+    })
+  } catch (error) {
+    // Dismissing the menu means the same as choosing to go back.
+    if (!(error instanceof PromptCancelledError)) throw error
+    paramToEdit = 'back'
+  }
 
   if (paramToEdit === 'empty') {
     return undefined
@@ -160,121 +171,128 @@ export const interactForBlueprintObject = async (
 
   const prop = properties[paramToEdit]
 
-  if (paramToEdit === 'device_id') {
-    args.params[paramToEdit] = await interactForDevice()
-    return interactForBlueprintObject(args, ctx)
-  } else if (paramToEdit === 'access_code_id') {
-    args.params[paramToEdit] = await interactForAccessCode(args.params as any)
-    return interactForBlueprintObject(args, ctx)
-  } else if (paramToEdit === 'connected_account_id') {
-    const connectedAccountId = await interactForConnectedAccount()
-    args.params[paramToEdit] = connectedAccountId
-    return interactForBlueprintObject(args, ctx)
-  } else if (
-    paramToEdit === 'user_identity_id' ||
-    paramToEdit === 'user_identity_ids'
-  ) {
-    const userIdentityId = await interactForUserIdentity()
-    args.params[paramToEdit] =
-      paramToEdit === 'user_identity_ids' ? [userIdentityId] : userIdentityId
-    return interactForBlueprintObject(args, ctx)
-  } else if (paramToEdit.endsWith('acs_system_id')) {
-    args.params[paramToEdit] = await interactForAcsSystem()
-    return interactForBlueprintObject(args, ctx)
-  } else if (paramToEdit.endsWith('acs_user_id')) {
-    args.params[paramToEdit] = await interactForAcsUser()
-    return interactForBlueprintObject(args, ctx)
-  } else if (paramToEdit.endsWith('acs_entrance_id')) {
-    args.params['acs_entrance_id'] = await interactForAcsEntrance()
-    return interactForBlueprintObject(args, ctx)
-  } else if (
-    paramToEdit.endsWith('_at') ||
-    paramToEdit === 'since' ||
-    paramToEdit.endsWith('_before') ||
-    paramToEdit.endsWith('_after')
-  ) {
-    args.params[paramToEdit] = await interactForTimestamp()
-    return interactForBlueprintObject(args, ctx)
-  } else if (
-    paramToEdit === 'custom_metadata' ||
-    paramToEdit === 'custom_metadata_has'
-  ) {
-    args.params[paramToEdit] = await interactForCustomMetadata(
-      args.params[paramToEdit] || {},
-    )
-    return interactForBlueprintObject(args, ctx)
-  }
-
-  if (prop) {
-    if (['string', 'id', 'datetime'].includes(prop.format)) {
-      let value
-      if (prop.format === 'datetime') {
-        value = await interactForTimestamp()
-      } else {
-        value = await promptText({
-          message: `${paramToEdit}:`,
-        })
-      }
-      args.params[paramToEdit] = value
+  // Dismissing any prompt below returns to the parameter menu with the
+  // parameter left as it was, rather than ending the whole command.
+  try {
+    if (paramToEdit === 'device_id') {
+      args.params[paramToEdit] = await interactForDevice()
       return interactForBlueprintObject(args, ctx)
-    } else if (prop.format === 'enum') {
-      const value = await promptSelect({
-        message: `${paramToEdit}:`,
-        choices: prop.values.map((v) => ({
-          label: v.name,
-          value: v.name,
-        })),
-      })
-      args.params[paramToEdit] = value
+    } else if (paramToEdit === 'access_code_id') {
+      args.params[paramToEdit] = await interactForAccessCode(args.params as any)
       return interactForBlueprintObject(args, ctx)
-    } else if (prop.format === 'boolean') {
-      const value = await promptConfirm({
-        message: `${paramToEdit}:`,
-        initialValue: true,
-        active: 'true',
-        inactive: 'false',
-      })
-
-      args.params[paramToEdit] = value
-
+    } else if (paramToEdit === 'connected_account_id') {
+      const connectedAccountId = await interactForConnectedAccount()
+      args.params[paramToEdit] = connectedAccountId
       return interactForBlueprintObject(args, ctx)
-    } else if (prop.format === 'list' && prop.itemFormat === 'enum') {
-      const value = await promptAutocompleteMultiselect({
-        message: `${paramToEdit}:`,
-        choices: prop.itemEnumValues.map((v) => ({
-          label: v.name,
-          value: v.name,
-        })),
-      })
-      args.params[paramToEdit] = value
+    } else if (
+      paramToEdit === 'user_identity_id' ||
+      paramToEdit === 'user_identity_ids'
+    ) {
+      const userIdentityId = await interactForUserIdentity()
+      args.params[paramToEdit] =
+        paramToEdit === 'user_identity_ids' ? [userIdentityId] : userIdentityId
       return interactForBlueprintObject(args, ctx)
-    } else if (prop.format === 'list') {
-      args.params[paramToEdit] = await interactForArray(
-        args.params[paramToEdit] || [],
-        `Edit the list for ${paramToEdit}`,
-      )
+    } else if (paramToEdit.endsWith('acs_system_id')) {
+      args.params[paramToEdit] = await interactForAcsSystem()
       return interactForBlueprintObject(args, ctx)
-    } else if (prop.format === 'object') {
-      args.params[paramToEdit] = await interactForBlueprintObject(
-        {
-          command: args.command,
-          params: {},
-          parameters: prop.parameters,
-          isSubProperty: true,
-          subPropertyPath: paramToEdit,
-        },
-        ctx,
+    } else if (paramToEdit.endsWith('acs_user_id')) {
+      args.params[paramToEdit] = await interactForAcsUser()
+      return interactForBlueprintObject(args, ctx)
+    } else if (paramToEdit.endsWith('acs_entrance_id')) {
+      args.params['acs_entrance_id'] = await interactForAcsEntrance()
+      return interactForBlueprintObject(args, ctx)
+    } else if (
+      paramToEdit.endsWith('_at') ||
+      paramToEdit === 'since' ||
+      paramToEdit.endsWith('_before') ||
+      paramToEdit.endsWith('_after')
+    ) {
+      args.params[paramToEdit] = await interactForTimestamp()
+      return interactForBlueprintObject(args, ctx)
+    } else if (
+      paramToEdit === 'custom_metadata' ||
+      paramToEdit === 'custom_metadata_has'
+    ) {
+      args.params[paramToEdit] = await interactForCustomMetadata(
+        args.params[paramToEdit] || {},
       )
       return interactForBlueprintObject(args, ctx)
-    } else if (prop.format === 'number') {
-      const value = await promptNumber({
-        message: `${paramToEdit}:`,
-      })
+    }
 
-      args.params[paramToEdit] = value
+    if (prop) {
+      if (['string', 'id', 'datetime'].includes(prop.format)) {
+        let value
+        if (prop.format === 'datetime') {
+          value = await interactForTimestamp()
+        } else {
+          value = await promptText({
+            message: withBackHint(`${paramToEdit}:`),
+          })
+        }
+        args.params[paramToEdit] = value
+        return interactForBlueprintObject(args, ctx)
+      } else if (prop.format === 'enum') {
+        const value = await promptSelect({
+          message: withBackHint(`${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 promptConfirm({
+          message: withBackHint(`${paramToEdit}:`),
+          initialValue: true,
+          active: 'true',
+          inactive: 'false',
+        })
 
-      return interactForBlueprintObject(args, ctx)
+        args.params[paramToEdit] = value
+
+        return interactForBlueprintObject(args, ctx)
+      } else if (prop.format === 'list' && prop.itemFormat === 'enum') {
+        const value = await promptAutocompleteMultiselect({
+          message: withBackHint(`${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') {
+        args.params[paramToEdit] = await interactForArray(
+          args.params[paramToEdit] || [],
+          `Edit the list for ${paramToEdit}`,
+        )
+        return interactForBlueprintObject(args, ctx)
+      } else if (prop.format === 'object') {
+        args.params[paramToEdit] = await interactForBlueprintObject(
+          {
+            command: args.command,
+            params: {},
+            parameters: prop.parameters,
+            isSubProperty: true,
+            subPropertyPath: paramToEdit,
+          },
+          ctx,
+        )
+        return interactForBlueprintObject(args, ctx)
+      } else if (prop.format === 'number') {
+        const value = await promptNumber({
+          message: withBackHint(`${paramToEdit}:`),
+        })
+
+        args.params[paramToEdit] = value
+
+        return interactForBlueprintObject(args, ctx)
+      }
     }
+  } catch (error) {
+    if (!(error instanceof PromptCancelledError)) throw error
+    return interactForBlueprintObject(args, ctx)
   }
 
   throw new Error(

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

@@ -2,7 +2,11 @@ import { isDeepStrictEqual as isEqual } from 'node:util'
 
 import type { ContextHelpers } from './types.js'
 import { NonInteractiveError } from './util/cli-args.js'
-import { promptAutocomplete } from './util/prompt.js'
+import {
+  promptAutocomplete,
+  PromptCancelledError,
+  withBackHint,
+} from './util/prompt.js'
 
 const uniqBy = <T>(items: T[], keyOf: (item: T) => unknown): T[] => {
   const seen = new Set<unknown>()
@@ -92,16 +96,30 @@ export async function interactForCommandSelection(
 
   const commandPathStr = commandPath.join('/').replace(/-/g, '_')
 
-  const selectedCommand = await promptAutocomplete({
-    message: `Select a command: /${commandPathStr}`,
-    choices: [
-      ...possibleCommands.map((cmd) => ({
-        label:
-          cmd?.[commandPath.length] ?? `[Call /${commandPathStr} Directly]`,
-        value: cmd?.[commandPath.length] ?? '<none>',
-      })),
-    ].sort((a, b) => ergonomicSort(a.value, b.value)),
-  })
+  // Only a sub-command menu has a level to go back to, so only it says so.
+  const selectMessage = `Select a command: /${commandPathStr}`
+
+  let selectedCommand: string
+  try {
+    selectedCommand = await promptAutocomplete({
+      message:
+        commandPath.length > 0 ? withBackHint(selectMessage) : selectMessage,
+      choices: [
+        ...possibleCommands.map((cmd) => ({
+          label:
+            cmd?.[commandPath.length] ?? `[Call /${commandPathStr} Directly]`,
+          value: cmd?.[commandPath.length] ?? '<none>',
+        })),
+      ].sort((a, b) => ergonomicSort(a.value, b.value)),
+    })
+  } catch (error) {
+    if (!(error instanceof PromptCancelledError)) throw error
+    // Dismissing the menu means the same as its [Back] entry, which is only
+    // offered when there is a level to go back to. At the top there is none,
+    // so dismissing it stops the CLI as it always has.
+    if (commandPath.length === 0) throw error
+    selectedCommand = '[Back]'
+  }
 
   if (selectedCommand === '<none>') {
     return commandPath

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

@@ -1,5 +1,10 @@
 import { getOutput } from './output/get-output.js'
-import { promptSelect, promptText } from './util/prompt.js'
+import {
+  PromptCancelledError,
+  promptSelect,
+  promptText,
+  withBackHint,
+} 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,45 +36,62 @@ export const interactForCustomMetadata = async (
   do {
     displayCurrentCustomMetadata()
 
-    action = await promptSelect({
-      message: 'Choose an action:',
-      choices: [
-        { label: 'Add an item to params', value: 'add' },
-        { label: 'Remove an item from params', value: 'remove' },
-        { label: 'Finish editing params', value: 'done' },
-      ],
-    })
-
-    if (action === 'add') {
-      const newKey = await promptText({
-        message: 'Enter a key to add or edit:',
+    try {
+      action = await promptSelect({
+        message: withBackHint('Choose an action:'),
+        choices: [
+          { label: 'Add an item to params', value: 'add' },
+          { label: 'Remove an item from params', value: 'remove' },
+          { label: 'Finish editing params', value: 'done' },
+        ],
       })
+    } catch (error) {
+      if (!(error instanceof PromptCancelledError)) throw error
+      // Dismissing the action menu finishes editing, keeping the changes.
+      break
+    }
 
-      let newValue: string | boolean = await promptText({
-        message: 'Enter the new value to add or edit (or null to delete):',
-      })
-      if (newKey) {
-        if (newValue === 'false' || newValue === 'true') {
-          newValue = newValue === 'true'
-        }
-        if (newValue === 'null') {
-          updatedCustomMetadata[newKey] = null
-        } else {
-          updatedCustomMetadata[newKey] = newValue
-        }
-      }
-    } else if (action === 'remove') {
-      const customKeyToRemove = await promptSelect({
-        message: 'Choose a key-value pair to remove from params:',
-        choices: Object.keys(updatedCustomMetadata).map((customMetadataKey) => {
-          return {
-            label: `${customMetadataKey}: ${updatedCustomMetadata[customMetadataKey]}`,
-            value: customMetadataKey,
+    try {
+      if (action === 'add') {
+        const newKey = await promptText({
+          message: withBackHint('Enter a key to add or edit:'),
+        })
+
+        let newValue: string | boolean = await promptText({
+          message: withBackHint(
+            'Enter the new value to add or edit (or null to delete):',
+          ),
+        })
+        if (newKey) {
+          if (newValue === 'false' || newValue === 'true') {
+            newValue = newValue === 'true'
           }
-        }),
-      })
+          if (newValue === 'null') {
+            updatedCustomMetadata[newKey] = null
+          } else {
+            updatedCustomMetadata[newKey] = newValue
+          }
+        }
+      } else if (action === 'remove') {
+        const customKeyToRemove = await promptSelect({
+          message: withBackHint(
+            'Choose a key-value pair to remove from params:',
+          ),
+          choices: Object.keys(updatedCustomMetadata).map(
+            (customMetadataKey) => {
+              return {
+                label: `${customMetadataKey}: ${updatedCustomMetadata[customMetadataKey]}`,
+                value: customMetadataKey,
+              }
+            },
+          ),
+        })
 
-      delete updatedCustomMetadata[customKeyToRemove]
+        delete updatedCustomMetadata[customKeyToRemove]
+      }
+    } catch (error) {
+      if (!(error instanceof PromptCancelledError)) throw error
+      // Dismissing an inner prompt returns to the action menu.
     }
   } while (action !== 'done')
 

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

@@ -1,4 +1,4 @@
-import { promptAutocomplete } from './util/prompt.js'
+import { promptAutocomplete, withBackHint } from './util/prompt.js'
 import { withLoading } from './util/with-loading.js'
 
 export interface ResourceChoice {
@@ -23,7 +23,9 @@ export const interactForResource = async <Resource>({
     fetchResources,
   )
   return await promptAutocomplete({
-    message,
+    // Resource pickers are only reached from the parameter flow, which
+    // returns to its menu when one is dismissed.
+    message: withBackHint(message),
     choices: resources.map((resource) => {
       const { title, value, description } = toChoice(resource)
       return { label: title, value, hint: description }

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

@@ -1,9 +1,9 @@
-import { promptText } from './util/prompt.js'
+import { promptText, withBackHint } from './util/prompt.js'
 
 export const interactForTimestamp = async () => {
   const now = new Date().toISOString()
   const timestamp = await promptText({
-    message: 'Enter a timestamp:',
+    message: withBackHint('Enter a timestamp:'),
     placeholder: now,
     defaultValue: now,
     validate: (value) => {

package/src/lib/util/prompt.ts

@@ -1,3 +1,6 @@
+import type { EventEmitter } from 'node:events'
+import type { Key } from 'node:readline'
+
 import {
   autocomplete,
   autocompleteMultiselect,
@@ -7,6 +10,7 @@ import {
   select,
   text,
 } from '@clack/prompts'
+import chalk from 'chalk'
 
 import { NonInteractiveError } from './cli-args.js'
 
@@ -34,12 +38,63 @@ export interface PromptChoice<Value> {
   hint?: string | undefined
 }
 
+/**
+ * Note on a prompt message that dismissing it returns to the previous step.
+ *
+ * Only for prompts whose caller catches the dismissal: elsewhere it still
+ * stops the CLI, and saying otherwise would mislead. The note goes in the
+ * message because clack renders its own keyboard hints from a hardcoded list
+ * that a caller cannot add to.
+ */
+export const withBackHint = (message: string): string =>
+  `${message} ${chalk.dim('· Esc: go back')}`
+
 const ensureInteractive = (): void => {
   if (!canPrompt()) {
     throw new NonInteractiveError(
       'Cannot prompt without a terminal: pass the missing arguments, or pipe them in as JSON',
     )
   }
+  installArrowKeyAliases()
+}
+
+/**
+ * The arrow keypress an Emacs-style control keypress stands for, or
+ * undefined for any other key: ctrl-p is up and ctrl-n is down.
+ */
+export const arrowKeyFor = (key: Key | undefined): Key | undefined => {
+  if (key?.ctrl !== true || key.meta === true || key.shift === true) {
+    return undefined
+  }
+  const base = { ctrl: false, meta: false, shift: false }
+  if (key.name === 'p') return { ...base, name: 'up', sequence: '\x1B[A' }
+  if (key.name === 'n') return { ...base, name: 'down', sequence: '\x1B[B' }
+  return undefined
+}
+
+/**
+ * Re-emit Emacs-style control keypresses as the arrow keys they stand for.
+ *
+ * Clack navigates on the readline key name, so a synthetic arrow keypress
+ * moves the cursor in every prompt kind. Its own alias table cannot express
+ * this: aliases match bare key names, unaware of ctrl, and are ignored by
+ * prompts that track typed input, such as autocomplete.
+ */
+export const emitArrowKeyAliases = (input: EventEmitter): void => {
+  input.on('keypress', (_char, key: Key | undefined) => {
+    const arrowKey = arrowKeyFor(key)
+    if (arrowKey !== undefined) input.emit('keypress', undefined, arrowKey)
+  })
+}
+
+let arrowKeyAliasesInstalled = false
+
+// Keypress events only flow while a prompt has stdin in raw mode, so the
+// listener is inert the rest of the time and never holds the process open.
+const installArrowKeyAliases = (): void => {
+  if (arrowKeyAliasesInstalled) return
+  arrowKeyAliasesInstalled = true
+  emitArrowKeyAliases(process.stdin)
 }
 
 const unwrap = <Value>(value: Value | symbol): Value => {

package/src/lib/version.ts

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