@seamapi/cli 0.8.0 → 0.10.0

package/src/lib/get-api-blueprint.ts

@@ -5,15 +5,19 @@ import { getServer } from './get-server.js'
 
 export type ApiBlueprint = Blueprint
 
+export interface GetApiBlueprintOptions {
+  update?: boolean
+}
+
 export const getApiBlueprint = async (
   useRemoteDefinitions: boolean,
+  options: GetApiBlueprintOptions = {},
 ): Promise<ApiBlueprint> => {
   // Remote definitions describe whatever the server is currently running, so
-  // build them directly from the server's OpenAPI document. This runtime path
-  // does not load @seamapi/types.
+  // build them directly from the server's OpenAPI document.
   if (useRemoteDefinitions) return await createRemoteBlueprint()
 
-  return await getBlueprint()
+  return await getBlueprint(options)
 }
 
 const createRemoteBlueprint = async (): Promise<Blueprint> => {

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

@@ -12,6 +12,7 @@ import { interactForDevice } from './interact-for-device.js'
 import { interactForTimestamp } from './interact-for-timestamp.js'
 import { interactForUserIdentity } from './interact-for-user-identity.js'
 import type { ContextHelpers } from './types.js'
+import { NonInteractiveError, toArgName } from './util/cli-args.js'
 import { ellipsis } from './util/ellipsis.js'
 
 const ergonomicPropOrder = [
@@ -47,12 +48,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,7 +78,6 @@ export const interactForBlueprintObject = async (
     return ergonomicPropOrder.indexOf(prop)
   }
 
-  const cmdPath = `/${args.command.join('/').replace(/-/g, '_')}`
   const parameterSelectionMessage = args.isSubProperty
     ? `Editing "${args.subPropertyPath}"`
     : `[${cmdPath}] Parameters`

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

@@ -3,6 +3,7 @@ import { isDeepStrictEqual as isEqual } from 'node:util'
 import prompts from 'prompts'
 
 import type { ContextHelpers } from './types.js'
+import { NonInteractiveError } from './util/cli-args.js'
 
 const uniqBy = <T>(items: T[], keyOf: (item: T) => unknown): T[] => {
   const seen = new Set<unknown>()
@@ -64,6 +65,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) {

package/src/lib/types.ts

@@ -1,6 +1,7 @@
 import type { ApiBlueprint } from './get-api-blueprint.js'
+import type { Interactivity } from './util/cli-args.js'
 
 export interface ContextHelpers {
   blueprint: ApiBlueprint
-  is_interactive: boolean
+  interactivity: Interactivity
 }

package/src/lib/util/cli-args.ts

@@ -0,0 +1,62 @@
+import parseArgs, { type ParsedArgs } from 'minimist'
+
+/**
+ * How the CLI should behave when properties are not given as arguments.
+ *
+ * - `auto`: make the request as soon as every required property is given,
+ *   otherwise prompt for what is missing. This is the default.
+ * - `interactive`: always prompt to review and edit properties, prefilled
+ *   with the given arguments. Selected with `--interactive` or `-i`.
+ * - `non-interactive`: never prompt: anything missing is an error.
+ *   Selected with `--non-interactive` or `-y`.
+ */
+export type Interactivity = 'auto' | 'interactive' | 'non-interactive'
+
+/**
+ * Argument keys that select the interactivity
+ * and are therefore not command parameters.
+ */
+export const interactivityFlags: string[] = [
+  'non_interactive',
+  'y',
+  'interactive',
+  'i',
+]
+
+/**
+ * Thrown when the CLI needs input it cannot prompt for.
+ */
+export class NonInteractiveError extends Error {
+  override name = 'NonInteractiveError'
+}
+
+export const parseCliArgs = (argv: string[]): ParsedArgs =>
+  parseArgs(argv, {
+    string: ['code'],
+    boolean: ['non-interactive', 'interactive'],
+    // Deliberately not aliased to -n, which is reserved for a future
+    // --dry-run flag.
+    alias: { 'non-interactive': 'y', interactive: 'i' },
+  })
+
+export const getInteractivity = (args: ParsedArgs): Interactivity => {
+  const isNonInteractive =
+    args['non_interactive'] === true || args['y'] === true
+  const isInteractive = args['interactive'] === true || args['i'] === true
+
+  if (isNonInteractive && isInteractive) {
+    throw new Error(
+      'The --interactive and --non-interactive flags cannot be used together',
+    )
+  }
+  if (isNonInteractive) return 'non-interactive'
+  if (isInteractive) return 'interactive'
+  return 'auto'
+}
+
+/**
+ * Render a parameter name as the argument used to set it,
+ * e.g., `device_id` as `--device-id`.
+ */
+export const toArgName = (parameterName: string): string =>
+  `--${parameterName.replace(/_/g, '-')}`

package/src/lib/version.ts

@@ -1,3 +1,6 @@
-const seamapiCliVersion = '0.8.0'
+// Versions are replaced with generated values when the package is packed.
+const seamapiCliVersion = '0.10.0'
+const seamapiBlueprintVersion = '1.2.0'
 
+export { seamapiBlueprintVersion }
 export default seamapiCliVersion