@seamapi/cli 0.24.1 → 0.26.0

package/src/lib/interactions/blueprint-object.ts

@@ -207,32 +207,47 @@ export const interactForBlueprintObject = async (
       }
     }
 
+    const current = args.params[paramToEdit]
+
     if (paramToEdit === 'device_id') {
-      args.params[paramToEdit] = await interactForDevice()
+      args.params[paramToEdit] = await interactForDevice(toText(current))
       return interactForBlueprintObject(args, ctx)
     } else if (paramToEdit === 'access_code_id') {
-      args.params[paramToEdit] = await interactForAccessCode(args.params as any)
+      args.params[paramToEdit] = await interactForAccessCode(
+        args.params as any,
+        toText(current),
+      )
       return interactForBlueprintObject(args, ctx)
     } else if (paramToEdit === 'connected_account_id') {
-      const connectedAccountId = await interactForConnectedAccount()
+      const connectedAccountId = await interactForConnectedAccount(
+        toText(current),
+      )
       args.params[paramToEdit] = connectedAccountId
       return interactForBlueprintObject(args, ctx)
     } else if (
       paramToEdit === 'user_identity_id' ||
       paramToEdit === 'user_identity_ids'
     ) {
-      const userIdentityId = await interactForUserIdentity()
+      const userIdentityId = await interactForUserIdentity(
+        paramToEdit === 'user_identity_ids'
+          ? toTextList(current)[0]
+          : toText(current),
+      )
       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()
+      args.params[paramToEdit] = await interactForAcsSystem({
+        initialValue: toText(current),
+      })
       return interactForBlueprintObject(args, ctx)
     } else if (paramToEdit.endsWith('acs_user_id')) {
-      args.params[paramToEdit] = await interactForAcsUser()
+      args.params[paramToEdit] = await interactForAcsUser(toText(current))
       return interactForBlueprintObject(args, ctx)
     } else if (paramToEdit.endsWith('acs_entrance_id')) {
-      args.params['acs_entrance_id'] = await interactForAcsEntrance()
+      args.params['acs_entrance_id'] = await interactForAcsEntrance(
+        toText(args.params['acs_entrance_id']),
+      )
       return interactForBlueprintObject(args, ctx)
     } else if (
       paramToEdit.endsWith('_at') ||
@@ -240,14 +255,14 @@ export const interactForBlueprintObject = async (
       paramToEdit.endsWith('_before') ||
       paramToEdit.endsWith('_after')
     ) {
-      args.params[paramToEdit] = await interactForTimestamp()
+      args.params[paramToEdit] = await interactForTimestamp(toText(current))
       return interactForBlueprintObject(args, ctx)
     } else if (
       paramToEdit === 'custom_metadata' ||
       paramToEdit === 'custom_metadata_has'
     ) {
       args.params[paramToEdit] = await interactForCustomMetadata(
-        args.params[paramToEdit] || {},
+        toRecord(current),
       )
       return interactForBlueprintObject(args, ctx)
     }
@@ -256,10 +271,11 @@ export const interactForBlueprintObject = async (
       if (['string', 'id', 'datetime'].includes(prop.format)) {
         let value
         if (prop.format === 'datetime') {
-          value = await interactForTimestamp()
+          value = await interactForTimestamp(toText(current))
         } else {
           value = await promptText({
             message: withBackHint(`${paramToEdit}:`),
+            initialValue: toText(current),
           })
         }
         args.params[paramToEdit] = value
@@ -271,13 +287,14 @@ export const interactForBlueprintObject = async (
             label: v.name,
             value: v.name,
           })),
+          initialValue: toText(current),
         })
         args.params[paramToEdit] = value
         return interactForBlueprintObject(args, ctx)
       } else if (prop.format === 'boolean') {
         const value = await promptConfirm({
           message: withBackHint(`${paramToEdit}:`),
-          initialValue: true,
+          initialValue: toBoolean(current) ?? true,
           active: 'true',
           inactive: 'false',
         })
@@ -292,12 +309,13 @@ export const interactForBlueprintObject = async (
             label: v.name,
             value: v.name,
           })),
+          initialValues: toTextList(current),
         })
         args.params[paramToEdit] = value
         return interactForBlueprintObject(args, ctx)
       } else if (prop.format === 'list') {
         args.params[paramToEdit] = await interactForArray(
-          args.params[paramToEdit] || [],
+          toTextList(current),
           `Edit the list for ${paramToEdit}`,
         )
         return interactForBlueprintObject(args, ctx)
@@ -305,7 +323,7 @@ export const interactForBlueprintObject = async (
         args.params[paramToEdit] = await interactForBlueprintObject(
           {
             command: args.command,
-            params: {},
+            params: toRecord(current),
             parameters: prop.parameters,
             isSubProperty: true,
             subPropertyPath: paramToEdit,
@@ -316,6 +334,7 @@ export const interactForBlueprintObject = async (
       } else if (prop.format === 'number') {
         const value = await promptNumber({
           message: withBackHint(`${paramToEdit}:`),
+          initialValue: toNumber(current),
         })
 
         args.params[paramToEdit] = value
@@ -332,3 +351,33 @@ export const interactForBlueprintObject = async (
     `Didn't know how to handle Blueprint parameter for property: "${paramToEdit}"`,
   )
 }
+
+/*
+ * A parameter's current value in the shape its editor starts from, so that
+ * editing a parameter that already has a value continues from that value
+ * instead of from nothing — whether it came from an argument, from the JSON
+ * piped in, or from an earlier trip through this menu.
+ *
+ * Params are passed through as given, so a value need not match the format
+ * its parameter documents: the JSON piped in is arbitrary, and a schema can
+ * change under a script. A value the editor cannot start from is left out of
+ * it, which opens the editor as an unset parameter does, rather than
+ * rendering a value of the wrong type as text to edit.
+ */
+
+const toText = (value: unknown): string | undefined =>
+  typeof value === 'string' ? value : undefined
+
+const toNumber = (value: unknown): number | undefined =>
+  typeof value === 'number' ? value : undefined
+
+const toBoolean = (value: unknown): boolean | undefined =>
+  typeof value === 'boolean' ? value : undefined
+
+const toTextList = (value: unknown): string[] =>
+  Array.isArray(value) ? value.filter((item) => typeof item === 'string') : []
+
+const toRecord = (value: unknown): Record<string, any> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, any>)
+    : {}

package/src/lib/interactions/connected-account.ts

@@ -1,12 +1,13 @@
 import { getSeam } from 'lib/http/client.js'
 
 import { interactForResource } from './resource.js'
-export const interactForConnectedAccount = async () => {
+export const interactForConnectedAccount = async (initialValue?: string) => {
   const seam = await getSeam()
 
   return interactForResource({
     resourceName: 'connected_account',
     fetchResources: () => seam.connectedAccounts.list(),
+    initialValue,
     toChoice: (connectedAccount) => {
       const identifiers = Object.values(
         connectedAccount.user_identifier ?? {},

package/src/lib/interactions/custom-metadata.ts

@@ -53,10 +53,16 @@ export const interactForCustomMetadata = async (
           message: withBackHint('Enter a key to add or edit:'),
         })
 
+        // Editing an existing key continues from the value it has, so a value
+        // is corrected rather than retyped.
+        const currentValue = updatedCustomMetadata[newKey]
+
         let newValue: string | boolean = await promptText({
           message: withBackHint(
             'Enter the new value to add or edit (or null to delete):',
           ),
+          initialValue:
+            currentValue == null ? undefined : currentValue.toString(),
         })
         if (newKey) {
           if (newValue === 'false' || newValue === 'true') {

package/src/lib/interactions/device.ts

@@ -1,12 +1,13 @@
 import { getSeam } from 'lib/http/client.js'
 
 import { interactForResource } from './resource.js'
-export const interactForDevice = async () => {
+export const interactForDevice = async (initialValue?: string) => {
   const seam = await getSeam()
 
   return interactForResource({
     resourceName: 'device',
     fetchResources: () => seam.devices.list(),
+    initialValue,
     toChoice: (device) => ({
       title: device.properties.name ?? '<No Name>',
       value: device.device_id,

package/src/lib/interactions/login.ts

@@ -1,4 +1,4 @@
-import { isApiKey, isPersonalAccessToken } from '@seamapi/http/connect'
+import { isApiKey, isPersonalAccessToken } from '@seamapi/http'
 import chalk from 'chalk'
 
 import { assertMutable, storeToken } from 'lib/auth/operations.js'

package/src/lib/interactions/resource.ts

@@ -12,11 +12,14 @@ export const interactForResource = async <Resource>({
   fetchResources,
   toChoice,
   message = `Select a ${resourceName}:`,
+  initialValue,
 }: {
   resourceName: string
   fetchResources: () => Promise<Resource[]>
   toChoice: (resource: Resource) => ResourceChoice
   message?: string | undefined
+  /** The resource already chosen, for the list to open on. */
+  initialValue?: string | undefined
 }) => {
   const resources = await withLoading(
     `Fetching ${resourceName.replace(/_/g, ' ')}s...`,
@@ -30,5 +33,6 @@ export const interactForResource = async <Resource>({
       const { title, value, description } = toChoice(resource)
       return { label: title, value, hint: description }
     }),
+    initialValue,
   })
 }

package/src/lib/interactions/timestamp.ts

@@ -1,11 +1,14 @@
 import { promptText, withBackHint } from 'lib/prompt.js'
 
-export const interactForTimestamp = async () => {
+export const interactForTimestamp = async (currentValue?: string) => {
   const now = new Date().toISOString()
   const timestamp = await promptText({
     message: withBackHint('Enter a timestamp:'),
     placeholder: now,
     defaultValue: now,
+    // A timestamp already given is offered for editing, rather than making
+    // the user type it out again to shift it by an hour.
+    initialValue: currentValue,
     validate: (value) => {
       if (value == null || value === '') return undefined
       if (Number.isNaN(new Date(value).getTime())) {

package/src/lib/interactions/user-identity.ts

@@ -2,12 +2,13 @@ import { getSeam } from 'lib/http/client.js'
 
 import { interactForResource } from './resource.js'
 
-export const interactForUserIdentity = async () => {
+export const interactForUserIdentity = async (initialValue?: string) => {
   const seam = await getSeam()
 
   return interactForResource({
     resourceName: 'user_identity',
     fetchResources: () => seam.userIdentities.list(),
+    initialValue,
     toChoice: (userIdentity) => ({
       title: `${userIdentity.email_address} "${userIdentity.full_name}: ${userIdentity.user_identity_key}`,
       value: userIdentity.user_identity_id,

package/src/lib/interactions/workspace-id.ts

@@ -1,4 +1,4 @@
-import { SeamHttpWithoutWorkspace } from '@seamapi/http/connect'
+import { SeamHttpWithoutWorkspace } from '@seamapi/http'
 
 import { assertMutable, selectWorkspace } from 'lib/auth/operations.js'
 import { getConfig } from 'lib/config/index.js'

package/src/lib/memory-prompt.ts

@@ -3,6 +3,7 @@ import type {
   PromptChoice,
   PromptClient,
   PromptConfirmOptions,
+  PromptMultiselectOptions,
   PromptNumberOptions,
   PromptSelectOptions,
   PromptTextOptions,
@@ -19,6 +20,9 @@ export interface PromptQuestion {
     | 'autocompleteMultiselect'
   message: string
   choices?: Array<PromptChoice<unknown>>
+  /** What the question was seeded with — what the user sees to edit. */
+  initialValue?: unknown
+  initialValues?: unknown[] | undefined
 }
 
 /** Scripted in place of an answer to dismiss that prompt. */
@@ -44,35 +48,53 @@ export class MemoryPromptClient implements PromptClient {
 
   canPrompt = (): boolean => true
 
-  text = async ({ message }: PromptTextOptions): Promise<string> =>
-    this.answer({ kind: 'text', message }) as string
+  text = async ({
+    message,
+    initialValue,
+  }: PromptTextOptions): Promise<string> =>
+    this.answer({ kind: 'text', message, initialValue }) as string
 
-  number = async ({ message }: PromptNumberOptions): Promise<number> =>
-    this.answer({ kind: 'number', message }) as number
+  number = async ({
+    message,
+    initialValue,
+  }: PromptNumberOptions): Promise<number> =>
+    this.answer({ kind: 'number', message, initialValue }) as number
 
-  confirm = async ({ message }: PromptConfirmOptions): Promise<boolean> =>
-    this.answer({ kind: 'confirm', message }) as boolean
+  confirm = async ({
+    message,
+    initialValue,
+  }: PromptConfirmOptions): Promise<boolean> =>
+    this.answer({ kind: 'confirm', message, initialValue }) as boolean
 
   select = async <Value>({
     message,
     choices,
+    initialValue,
   }: PromptSelectOptions<Value>): Promise<Value> =>
-    this.answer({ kind: 'select', message, choices }) as Value
+    this.answer({ kind: 'select', message, choices, initialValue }) as Value
 
   autocomplete = async <Value>({
     message,
     choices,
+    initialValue,
   }: PromptSelectOptions<Value>): Promise<Value> =>
-    this.answer({ kind: 'autocomplete', message, choices }) as Value
+    this.answer({
+      kind: 'autocomplete',
+      message,
+      choices,
+      initialValue,
+    }) as Value
 
   autocompleteMultiselect = async <Value>({
     message,
     choices,
-  }: PromptSelectOptions<Value>): Promise<Value[]> =>
+    initialValues,
+  }: PromptMultiselectOptions<Value>): Promise<Value[]> =>
     this.answer({
       kind: 'autocompleteMultiselect',
       message,
       choices,
+      initialValues,
     }) as Value[]
 
   private answer(question: PromptQuestion): unknown {

package/src/lib/prompt.ts

@@ -24,11 +24,15 @@ export interface PromptTextOptions {
   message: string
   placeholder?: string
   defaultValue?: string
+  /** Editable text the prompt opens with, for editing a value in place. */
+  initialValue?: string | undefined
   validate?: (value: string | undefined) => string | undefined
 }
 
 export interface PromptNumberOptions {
   message: string
+  /** Editable text the prompt opens with, for editing a value in place. */
+  initialValue?: number | undefined
   validate?: (value: number) => string | undefined
 }
 
@@ -42,6 +46,15 @@ export interface PromptConfirmOptions {
 export interface PromptSelectOptions<Value> {
   message: string
   choices: Array<PromptChoice<Value>>
+  /** The choice to open on, for editing a value in place. */
+  initialValue?: Value | undefined
+}
+
+export interface PromptMultiselectOptions<Value> {
+  message: string
+  choices: Array<PromptChoice<Value>>
+  /** The choices to open selected, for editing a value in place. */
+  initialValues?: Value[] | undefined
 }
 
 /**
@@ -60,7 +73,7 @@ export interface PromptClient {
   select: <Value>(options: PromptSelectOptions<Value>) => Promise<Value>
   autocomplete: <Value>(options: PromptSelectOptions<Value>) => Promise<Value>
   autocompleteMultiselect: <Value>(
-    options: PromptSelectOptions<Value>,
+    options: PromptMultiselectOptions<Value>,
   ) => Promise<Value[]>
 }
 
@@ -133,6 +146,37 @@ const toOptions = <Value>(
         : { label, value, hint }) as Option<Value>,
   )
 
+/**
+ * A value as the choice a list prompt opens on: the value when the list
+ * offers it, and otherwise nothing.
+ *
+ * A value the list does not offer, such as an id passed as an argument that
+ * is not among the resources fetched, would leave clack holding a selection
+ * with no choice behind it — so the prompt opens on its first choice, the
+ * same as one with no value to start from.
+ */
+export const offeredValue = <Value>(
+  choices: Array<PromptChoice<Value>>,
+  value: Value | undefined,
+): Value | undefined =>
+  choices.some((choice) => choice.value === value) ? value : undefined
+
+/** Every one of the values a list prompt offers, in the order given. */
+export const offeredValues = <Value>(
+  choices: Array<PromptChoice<Value>>,
+  values: Value[] | undefined,
+): Value[] =>
+  (values ?? []).filter((value) => offeredValue(choices, value) !== undefined)
+
+// Options a clack prompt is given cannot carry an explicit undefined: it
+// declares each optional field without it, and the CLI type-checks with
+// exactOptionalPropertyTypes.
+const optional = <Key extends string, Value>(
+  key: Key,
+  value: Value | undefined,
+): Partial<Record<Key, Value>> =>
+  value === undefined ? {} : ({ [key]: value } as Record<Key, Value>)
+
 export class TerminalPromptClient implements PromptClient {
   /**
    * Prompts read raw keypresses and render an interface, so they need a
@@ -145,7 +189,14 @@ export class TerminalPromptClient implements PromptClient {
 
   text = async (options: PromptTextOptions): Promise<string> => {
     installArrowKeyAliases()
-    return unwrap(await text({ ...options, output }))
+    const { initialValue, ...rest } = options
+    return unwrap(
+      await text({
+        ...rest,
+        ...optional('initialValue', initialValue),
+        output,
+      }),
+    )
   }
 
   number = async (options: PromptNumberOptions): Promise<number> => {
@@ -153,6 +204,7 @@ export class TerminalPromptClient implements PromptClient {
     const value = unwrap(
       await text({
         message: options.message,
+        ...optional('initialValue', options.initialValue?.toString()),
         validate: (value) => {
           if (value == null || value.trim() === '') return 'Enter a number'
           const parsed = Number(value)
@@ -178,6 +230,10 @@ export class TerminalPromptClient implements PromptClient {
       await select<Value>({
         message: options.message,
         options: toOptions(options.choices),
+        ...optional(
+          'initialValue',
+          offeredValue(options.choices, options.initialValue),
+        ),
         output,
       }),
     )
@@ -191,6 +247,10 @@ export class TerminalPromptClient implements PromptClient {
       await autocomplete<Value>({
         message: options.message,
         options: toOptions(options.choices),
+        ...optional(
+          'initialValue',
+          offeredValue(options.choices, options.initialValue),
+        ),
         // 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,
@@ -200,13 +260,14 @@ export class TerminalPromptClient implements PromptClient {
   }
 
   autocompleteMultiselect = async <Value>(
-    options: PromptSelectOptions<Value>,
+    options: PromptMultiselectOptions<Value>,
   ): Promise<Value[]> => {
     installArrowKeyAliases()
     return unwrap(
       await autocompleteMultiselect<Value>({
         message: options.message,
         options: toOptions(options.choices),
+        initialValues: offeredValues(options.choices, options.initialValues),
         filter: searchChoices,
         output,
       }),
@@ -273,7 +334,7 @@ export const promptAutocomplete = async <Value>(
 }
 
 export const promptAutocompleteMultiselect = async <Value>(
-  options: PromptSelectOptions<Value>,
+  options: PromptMultiselectOptions<Value>,
 ): Promise<Value[]> => {
   ensureInteractive()
   return await client.autocompleteMultiselect(options)

package/src/lib/render/help.ts

@@ -36,7 +36,7 @@ const outputSection = {
   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.',
+    'Request params may be piped or redirected in as a JSON object, or passed inline with --raw. Params given as arguments win over raw or stdin params.',
   ],
 }
 

package/src/lib/version.ts

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