@seamapi/cli 0.13.1 → 0.15.0

package/lib/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamapi/cli",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "A command-line interface (CLI) for interacting with the Seam API.",
   "type": "module",
   "main": "index.js",

package/src/bin/cli.ts

@@ -5,14 +5,26 @@ import { isDeepStrictEqual as isEqual } from 'node:util'
 import chalk from 'chalk'
 import type { ParsedArgs } from 'minimist'
 
-import { getCommandSpec } from 'lib/command-spec.js'
+import { findLocalCommand, getCommandSpec } from 'lib/command-spec.js'
 import {
   completionShells,
   isCompletionShell,
   renderCompletion,
 } from 'lib/completion/index.js'
 import { getConfigStore } from 'lib/config/index.js'
+import {
+  assertEnvVarUnset,
+  endpointEnvVar,
+  EnvVarOverrideError,
+  getEndpointFromEnv,
+  getTokenFromEnv,
+  getWorkspaceIdFromEnv,
+  tokenEnvVar,
+  workspaceIdEnvVar,
+} from 'lib/env.js'
 import { getApiBlueprint } from 'lib/get-api-blueprint.js'
+import { getCommandBlueprintDef } from 'lib/get-command-blueprint-def.js'
+import { getToken } from 'lib/get-credentials.js'
 import { getResponseKey } from 'lib/get-response-key.js'
 import { getServer } from 'lib/get-server.js'
 import { interactForActionAttemptPoll } from 'lib/interact-for-action-attempt-poll.js'
@@ -33,6 +45,9 @@ import {
   type Interactivity,
   NonInteractiveError,
   parseCliArgs,
+  toGivenArgName,
+  toParameterName,
+  UsageError,
 } from 'lib/util/cli-args.js'
 import { canPrompt, prompt } from 'lib/util/prompt.js'
 import { readStdinJson } from 'lib/util/read-stdin-json.js'
@@ -77,6 +92,29 @@ async function cli(args: ParsedArgs) {
     return
   }
 
+  args._ = args._.map(toCommandWord)
+
+  // Argument keys name parameters however they are written, so normalize each
+  // one to the name the API gives it. Replace the key rather than adding the
+  // normalized form alongside it, or an argument would be sent twice: once as
+  // written and once as the API names it.
+  for (const key of Object.keys(args)) {
+    if (key === '_') continue
+    const name = toParameterName(key)
+    if (name === key) continue
+    args[name] = args[key]
+    delete args[key]
+  }
+
+  // Params given as arguments, kept apart from the params read from stdin so
+  // that only the arguments are held to what the command accepts.
+  const argParams: Record<string, any> = {}
+  for (const [key, value] of Object.entries(args)) {
+    if (key === '_') continue
+    if (cliFlags.includes(key)) continue
+    argParams[key] = value
+  }
+
   if (args._[0] === 'completion') {
     const shell = args._[1]
 
@@ -86,6 +124,8 @@ async function cli(args: ParsedArgs) {
       return
     }
 
+    assertKnownArgs(argParams, ['completion', shell])
+
     // Completions always come from the cached API definitions so that they
     // can be generated without logging in. They may lag the definitions
     // served by Seam when config use-remote-api-defs is enabled.
@@ -100,6 +140,9 @@ async function cli(args: ParsedArgs) {
     args._[1] === 'set' &&
     args._[2] === 'fake-server'
   ) {
+    assertEnvVarUnset(endpointEnvVar, getEndpointFromEnv(), 'select a server')
+    assertEnvVarUnset(tokenEnvVar, getTokenFromEnv(), 'log in')
+
     const randomstring = randomBytes(5).toString('hex')
     const fakeApiUrl = `https://${randomstring}.fakeseamconnect.seam.vc`
 
@@ -112,24 +155,19 @@ async function cli(args: ParsedArgs) {
   }
 
   if (
-    !config.get(`${getServer()}.pat`) &&
+    getToken() == null &&
     args._[0] !== 'login' &&
     !isEqual(args._, ['select', 'server'])
   ) {
-    output.error(`Not logged in. Please run "seam login"`)
+    output.error(`Not logged in. Please run "seam login" or set ${tokenEnvVar}`)
     process.exitCode = 1
     return
   }
 
-  args._ = args._.map(toCommandWord)
-  for (const k in args) {
-    args[k.toLowerCase().replace(/-/g, '_')] = args[k]
-  }
-
-  const use_remote_api_defs =
+  const useRemoteApiDefs =
     args['remote_api_defs'] ?? config.get('use_remote_api_defs')
 
-  const blueprint = await getApiBlueprint(use_remote_api_defs ?? false, {
+  const blueprint = await getApiBlueprint(useRemoteApiDefs ?? false, {
     update,
   })
 
@@ -144,18 +182,36 @@ async function cli(args: ParsedArgs) {
 
   const isNonInteractive = ctx.interactivity === 'non-interactive'
 
-  for (const k in args) {
-    if (k === '_') continue
-    const v = args[k]
-    delete args[k]
-    const key = k.replace(/-/g, '_')
-    args[key] = v
-    if (cliFlags.includes(key)) continue
-    commandParams[key] = v
-  }
+  Object.assign(commandParams, argParams)
 
   const selectedCommand = await interactForCommandSelection(args._, ctx)
+
+  // Hit 'back' on a top-level command path, so we start again
+  if (selectedCommand.slice(-1)[0] === '[Back]') {
+    return await cli({
+      ...args,
+      _: [],
+    })
+  }
+
+  // Check the arguments before the command acts on any of them, so a mistake
+  // is reported rather than half applied.
+  assertKnownArgs(argParams, selectedCommand, ctx)
+
   if (isEqual(selectedCommand, ['login'])) {
+    // Nothing is stored while the environment overrides it, so refuse before
+    // storing anything rather than part way through.
+    assertEnvVarUnset(tokenEnvVar, getTokenFromEnv(), 'log in')
+    if (args['server']) {
+      assertEnvVarUnset(endpointEnvVar, getEndpointFromEnv(), 'select a server')
+    }
+    if (args['workspace_id']) {
+      assertEnvVarUnset(
+        workspaceIdEnvVar,
+        getWorkspaceIdFromEnv(),
+        'select a workspace',
+      )
+    }
     if (args['server']) {
       config.set('server', args['server'])
       config.delete('current_workspace_id')
@@ -180,6 +236,7 @@ async function cli(args: ParsedArgs) {
     await interactForLogin()
     return
   } else if (isEqual(selectedCommand, ['logout'])) {
+    assertEnvVarUnset(tokenEnvVar, getTokenFromEnv(), 'log out')
     config.delete('pat')
     output.info('Logged out!')
     return
@@ -195,6 +252,11 @@ async function cli(args: ParsedArgs) {
     await interactForUseRemoteApiDefs()
     return
   } else if (isEqual(selectedCommand, ['select', 'workspace'])) {
+    assertEnvVarUnset(
+      workspaceIdEnvVar,
+      getWorkspaceIdFromEnv(),
+      'select a workspace',
+    )
     if (isNonInteractive) {
       throw new NonInteractiveError(
         'Cannot select a workspace in non-interactive mode: pass --workspace-id to "seam login"',
@@ -209,6 +271,7 @@ async function cli(args: ParsedArgs) {
       commandParams['since'] = date.toISOString()
     }
   } else if (isEqual(selectedCommand, ['select', 'server'])) {
+    assertEnvVarUnset(endpointEnvVar, getEndpointFromEnv(), 'select a server')
     if (args['server']) {
       config.set('server', args['server'])
       config.delete('current_workspace_id')
@@ -236,14 +299,7 @@ async function cli(args: ParsedArgs) {
       commandParams['accepted_providers'].split(',')
   }
 
-  // Hit 'back' on a top-level command path, so we start again
-  const lastCommandPath = selectedCommand.slice(-1)[0]
-  if (lastCommandPath === '[Back]') {
-    return await cli({
-      ...args,
-      _: [],
-    })
-  }
+  const apiPath = `/${selectedCommand.join('/').replace(/-/g, '_')}`
 
   const params = await interactForCommandParams(
     { command: selectedCommand, params: commandParams },
@@ -259,8 +315,6 @@ async function cli(args: ParsedArgs) {
     })
   }
 
-  const apiPath = `/${selectedCommand.join('/').replace(/-/g, '_')}`
-
   if (apiPath.includes('/events/list') && params.between) {
     delete params.since
   }
@@ -286,11 +340,67 @@ async function cli(args: ParsedArgs) {
 const toCommandWord = (arg: string): string =>
   arg.toLowerCase().replace(/_/g, '-')
 
+/**
+ * Report any argument the command does not accept, rather than acting on it.
+ * An unrecognized argument is a mistake: forwarded to the API it would fail
+ * somewhere less obvious or be quietly ignored, and on a command the CLI
+ * handles itself it would go nowhere at all.
+ *
+ * Only arguments are checked. Params read from stdin are passed through as
+ * given, so a caller may send whatever the API itself accepts.
+ *
+ * `ctx` is only needed to look up an endpoint's parameters, so commands the
+ * CLI declares itself can be checked before any blueprint is loaded.
+ */
+const assertKnownArgs = (
+  argParams: Record<string, any>,
+  command: string[],
+  ctx?: ContextHelpers,
+): void => {
+  const local = findLocalCommand(command)
+
+  let accepted: Set<string>
+  if (local != null) {
+    accepted = new Set(
+      local.flags.flatMap(({ long }) =>
+        long == null ? [] : [toParameterName(long)],
+      ),
+    )
+  } else if (ctx != null) {
+    accepted = new Set(
+      getCommandBlueprintDef(command, ctx).request.parameters.map(
+        ({ name }) => name,
+      ),
+    )
+  } else {
+    throw new Error(`No definition for command seam ${command.join(' ')}`)
+  }
+
+  const unknown = Object.keys(argParams).filter((key) => !accepted.has(key))
+  if (unknown.length === 0) return
+
+  // Name an endpoint command by its path, as missing params are named, and a
+  // command the CLI handles itself by the words that run it.
+  const target =
+    local == null
+      ? `/${command.join('/').replace(/-/g, '_')}`
+      : command.join(' ')
+
+  throw new UsageError(
+    `Unknown ${
+      unknown.length === 1 ? 'parameter' : 'parameters'
+    } for ${target}: ${unknown.map(toGivenArgName).join(' ')}`,
+    {
+      hint: `Run 'seam ${command.join(' ')} --help' to see what it accepts.`,
+    },
+  )
+}
+
 const handleConnectWebviewResponse = async (
-  connect_webview: any,
+  connectWebview: any,
   interactivity: Interactivity,
 ) => {
-  const url = connect_webview.url
+  const url = connectWebview.url
 
   if (
     interactivity !== 'non-interactive' &&
@@ -337,7 +447,13 @@ run(process.argv.slice(2)).catch((e: unknown) => {
   const output = getOutput()
   process.exitCode = 1
 
-  if (e instanceof NonInteractiveError) {
+  if (e instanceof UsageError) {
+    output.error(chalk.red(e.message))
+    if (e.hint !== '') output.error(e.hint)
+    return
+  }
+
+  if (e instanceof NonInteractiveError || e instanceof EnvVarOverrideError) {
     output.error(chalk.red(e.message))
     return
   }

package/src/lib/command-spec.ts

@@ -151,6 +151,18 @@ export const findGroup = (
 ): CommandGroup | undefined =>
   spec.groups.find((group) => isSamePath(group.path, path))
 
+/**
+ * The definition of a command the CLI handles itself, or `undefined` when the
+ * path is an endpoint or no command at all.
+ *
+ * Unlike {@link findCommand} this needs no blueprint, since these commands are
+ * declared by the CLI rather than derived from the API definitions.
+ */
+export const findLocalCommand = (
+  path: string[],
+): CommandDefinition | undefined =>
+  localCommands.find((command) => isSamePath(command.path, path))
+
 const isSamePath = (a: string[], b: string[]): boolean =>
   a.length === b.length && a.every((word, index) => word === b[index])
 

package/src/lib/env.d.ts

@@ -0,0 +1,12 @@
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv {
+      INSIDE_WEB_BROWSER?: string
+      SEAM_CLI_ENDPOINT?: string
+      SEAM_CLI_TOKEN?: string
+      SEAM_CLI_WORKSPACE_ID?: string
+    }
+  }
+}
+
+export {}

package/src/lib/env.ts

@@ -0,0 +1,63 @@
+/**
+ * Credentials and the server may be given in the environment.
+ *
+ * Each variable overrides the corresponding stored value for as long as it
+ * is set, so any of them may be used per command or per shell. Commands that
+ * would store an overridden value fail instead: see {@link assertEnvVarUnset}.
+ */
+
+/** Overrides the token stored by `seam login`. */
+export const tokenEnvVar = 'SEAM_CLI_TOKEN'
+
+/** Overrides the workspace stored by `seam select workspace`. */
+export const workspaceIdEnvVar = 'SEAM_CLI_WORKSPACE_ID'
+
+/** Overrides the server stored by `seam select server`. */
+export const endpointEnvVar = 'SEAM_CLI_ENDPOINT'
+
+/** Every variable read here is declared on `ProcessEnv` in `env.d.ts`. */
+type SeamCliEnvVar =
+  typeof endpointEnvVar | typeof tokenEnvVar | typeof workspaceIdEnvVar
+
+export const getTokenFromEnv = (): string | null => readEnvVar(tokenEnvVar)
+
+export const getWorkspaceIdFromEnv = (): string | null =>
+  readEnvVar(workspaceIdEnvVar)
+
+export const getEndpointFromEnv = (): string | null =>
+  readEnvVar(endpointEnvVar)
+
+/** Reported without a stack trace: the environment is at fault, not the CLI. */
+export class EnvVarOverrideError extends Error {
+  override name = 'EnvVarOverrideError'
+}
+
+/**
+ * Refuse to store a value the environment overrides.
+ *
+ * Storing it would have no effect while the variable is set, so a command
+ * that appears to succeed would leave the CLI using something else.
+ *
+ * @param action What the command does, e.g., `log in`.
+ */
+export const assertEnvVarUnset = (
+  envVar: string,
+  envValue: string | null,
+  action: string,
+): void => {
+  if (envValue == null) return
+
+  throw new EnvVarOverrideError(
+    `Cannot ${action} while ${envVar} is set: it overrides what would be stored. Unset ${envVar} to ${action}.`,
+  )
+}
+
+const readEnvVar = (envVar: SeamCliEnvVar): string | null => {
+  const value = process.env[envVar]
+
+  if (value == null) return null
+
+  const trimmedValue = value.trim()
+
+  return trimmedValue === '' ? null : trimmedValue
+}

package/src/lib/get-credentials.ts

@@ -0,0 +1,38 @@
+import { getConfigStore } from './config/index.js'
+import { getTokenFromEnv, getWorkspaceIdFromEnv } from './env.js'
+import { getServer } from './get-server.js'
+
+/**
+ * The token used to authenticate requests.
+ *
+ * `SEAM_CLI_TOKEN` wins over the token stored by `seam login`,
+ * so a token may be given per command or per shell without logging in.
+ */
+export const getToken = (): string | null => {
+  const token = getTokenFromEnv()
+  if (token != null) return token
+
+  return readString(getConfigStore().get(`${getServer()}.pat`))
+}
+
+/**
+ * The workspace requests are made against.
+ *
+ * `SEAM_CLI_WORKSPACE_ID` wins over the workspace stored by
+ * `seam select workspace`. Returns `null` when neither is set: a token
+ * scoped to a single workspace does not need one.
+ */
+export const getWorkspaceId = (): string | null => {
+  const workspaceId = getWorkspaceIdFromEnv()
+  if (workspaceId != null) return workspaceId
+
+  return readString(getConfigStore().get('current_workspace_id'))
+}
+
+const readString = (value: unknown): string | null => {
+  if (typeof value !== 'string') return null
+
+  const trimmedValue = value.trim()
+
+  return trimmedValue === '' ? null : trimmedValue
+}

package/src/lib/get-current-workspace-id.ts

@@ -1,11 +1,9 @@
-import { getConfigStore } from './config/index.js'
+import { getWorkspaceId } from './get-credentials.js'
 import { interactForWorkspaceId } from './interact-for-workspace-id.js'
 
 export const getCurrentWorkspaceId = async (): Promise<string> => {
-  const configStore = getConfigStore()
-
-  const currentWorkspaceId = configStore.get('current_workspace_id')
-  if (typeof currentWorkspaceId === 'string') return currentWorkspaceId
+  const currentWorkspaceId = getWorkspaceId()
+  if (currentWorkspaceId != null) return currentWorkspaceId
 
   return await interactForWorkspaceId()
 }

package/src/lib/get-seam.ts

@@ -5,24 +5,29 @@ import {
   SeamHttpWithoutWorkspace,
 } from '@seamapi/http/connect'
 
-import { getConfigStore } from './config/index.js'
+import { tokenEnvVar, workspaceIdEnvVar } from './env.js'
+import { getToken, getWorkspaceId } from './get-credentials.js'
 import { getServer } from './get-server.js'
 
 export const getSeam = async (): Promise<SeamHttp> => {
-  const config = getConfigStore()
-
-  const token = config.get(`${getServer()}.pat`) as string
-
-  const workspaceId = config.get('current_workspace_id') as string
+  const token = getRequiredToken()
 
   const options = { endpoint: getServer() }
 
   if (isPersonalAccessToken(token)) {
-    return SeamHttp.fromPersonalAccessToken(token, workspaceId, options)
+    return SeamHttp.fromPersonalAccessToken(
+      token,
+      getRequiredWorkspaceId(),
+      options,
+    )
   }
 
   if (isConsoleSessionToken(token)) {
-    return SeamHttp.fromConsoleSessionToken(token, workspaceId, options)
+    return SeamHttp.fromConsoleSessionToken(
+      token,
+      getRequiredWorkspaceId(),
+      options,
+    )
   }
 
   return SeamHttp.fromApiKey(token, options)
@@ -31,13 +36,36 @@ export const getSeam = async (): Promise<SeamHttp> => {
 export const getSeamMultiWorkspace = async (): Promise<
   SeamHttpWithoutWorkspace | SeamHttp
 > => {
-  const config = getConfigStore()
-  const token = config.get(`${getServer()}.pat`) as string
+  const token = getRequiredToken()
   const options = { endpoint: getServer() }
 
   if (isPersonalAccessToken(token)) {
     return SeamHttpWithoutWorkspace.fromPersonalAccessToken(token, options)
   }
 
-  return getSeam()
+  return await getSeam()
+}
+
+const getRequiredToken = (): string => {
+  const token = getToken()
+
+  if (token == null) {
+    throw new Error(
+      `Not logged in: run "seam login" or set the ${tokenEnvVar} environment variable`,
+    )
+  }
+
+  return token
+}
+
+const getRequiredWorkspaceId = (): string => {
+  const workspaceId = getWorkspaceId()
+
+  if (workspaceId == null) {
+    throw new Error(
+      `No workspace selected: run "seam select workspace" or set the ${workspaceIdEnvVar} environment variable`,
+    )
+  }
+
+  return workspaceId
 }

package/src/lib/get-server.ts

@@ -1,9 +1,20 @@
 import { getConfigStore } from './config/index.js'
+import { getEndpointFromEnv } from './env.js'
 
+const defaultServer = 'https://connect.getseam.com'
+
+/**
+ * The Seam API server requests are made against.
+ *
+ * `SEAM_CLI_ENDPOINT` wins over the server stored by `seam select server`.
+ */
 export const getServer = (): string => {
+  const endpoint = getEndpointFromEnv()
+  if (endpoint != null) return endpoint
+
   const config = getConfigStore()
 
   const server = config.get('server')
 
-  return typeof server === 'string' ? server : 'https://connect.getseam.com'
+  return typeof server === 'string' ? server : defaultServer
 }

package/src/lib/interact-for-access-code.ts

@@ -3,19 +3,21 @@ import { interactForDevice } from './interact-for-device.js'
 import { interactForResource } from './interact-for-resource.js'
 
 export const interactForAccessCode = async ({
-  device_id,
+  // The key is a Seam API parameter name: callers pass the blueprint params
+  // bag through as-is, so only the binding may be camelCase.
+  device_id: deviceId,
 }: {
   device_id?: string
 }) => {
   const seam = await getSeam()
 
-  if (!device_id) {
-    device_id = await interactForDevice()
+  if (!deviceId) {
+    deviceId = await interactForDevice()
   }
 
   return interactForResource({
     resourceName: 'access_code',
-    fetchResources: () => seam.accessCodes.list({ device_id }),
+    fetchResources: () => seam.accessCodes.list({ device_id: deviceId }),
     toChoice: (accessCode) => ({
       title: accessCode.name ?? '<No Name>',
       value: accessCode.access_code_id,

package/src/lib/interact-for-acs-user.ts

@@ -5,13 +5,13 @@ import { interactForResource } from './interact-for-resource.js'
 export const interactForAcsUser = async () => {
   const seam = await getSeam()
 
-  const acs_system_id = await interactForAcsSystem(
+  const acsSystemId = await interactForAcsSystem(
     'What acs_system does the acs_user belong to?',
   )
 
   return interactForResource({
     resourceName: 'ACS user',
-    fetchResources: () => seam.acs.users.list({ acs_system_id }),
+    fetchResources: () => seam.acs.users.list({ acs_system_id: acsSystemId }),
     toChoice: (user) => ({
       title: `${user.display_name} ${user.email_address}`,
       value: user.acs_user_id,

package/src/lib/interact-for-action-attempt-poll.ts

@@ -6,11 +6,11 @@ import { prompt } from './util/prompt.js'
 import { withLoading } from './util/with-loading.js'
 
 export const interactForActionAttemptPoll = async (
-  action_attempt: ActionAttemptsGetResponse['action_attempt'],
+  actionAttempt: ActionAttemptsGetResponse['action_attempt'],
 ) => {
-  if (action_attempt.status === 'pending') {
-    const { poll_for_action_attempt } = await prompt({
-      name: 'poll_for_action_attempt',
+  if (actionAttempt.status === 'pending') {
+    const { pollForActionAttempt } = await prompt({
+      name: 'pollForActionAttempt',
       message: "Would you like to poll the action attempt until it's ready?",
       type: 'toggle',
       initial: true,
@@ -18,19 +18,19 @@ export const interactForActionAttemptPoll = async (
       inactive: 'no',
     })
 
-    if (poll_for_action_attempt) {
+    if (pollForActionAttempt) {
       const seam = await getSeam()
-      const { action_attempt_id } = action_attempt
+      const { action_attempt_id: actionAttemptId } = actionAttempt
 
-      const updated_action_attempt = await withLoading(
+      const updatedActionAttempt = await withLoading(
         'Polling action attempt...',
         () =>
           seam.actionAttempts.get(
-            { action_attempt_id },
+            { action_attempt_id: actionAttemptId },
             { waitForActionAttempt: { pollingInterval: 240, timeout: 10_000 } },
           ),
       )
-      getOutput().data({ action_attempt: updated_action_attempt })
+      getOutput().data({ action_attempt: updatedActionAttempt })
     }
   }
 }