@seamapi/cli 0.20.0 → 0.22.0

package/src/lib/args/validate.ts

@@ -1,6 +1,8 @@
 import type { Parameter } from '@seamapi/blueprint'
 
+import type { CommandDefinition } from 'lib/commands/spec.js'
 import { NonInteractiveError, UsageError } from 'lib/errors.js'
+import type { AuthOverrides } from 'lib/overrides.js'
 
 import { toArgName, toGivenArgName } from './parse.js'
 
@@ -40,6 +42,41 @@ export const assertRequiredParams = (
  * Only arguments are checked. Params read from stdin are passed through as
  * given, so a caller may send whatever the API itself accepts.
  */
+/**
+ * Refuse the auth overrides on a command that selects what they override.
+ *
+ * `--endpoint` and `--workspace-id` scope one command and are never stored,
+ * so on `seam select ...` they would read as the value to store and quietly
+ * do nothing of the kind. The positional is what stores.
+ */
+export const assertNoAuthOverrides = (
+  { path, positional }: CommandDefinition,
+  overrides: AuthOverrides,
+): void => {
+  if (path[0] !== 'select') return
+
+  const given = [
+    overrides.endpoint == null ? null : '--endpoint',
+    overrides.workspaceId == null ? null : '--workspace-id',
+  ].filter((flag) => flag != null)
+
+  if (given.length === 0) return
+
+  const command = `seam ${path.join(' ')}`
+
+  throw new UsageError(
+    `${given.join(' and ')} cannot be used with ${command}: ${
+      given.length === 1 ? 'it overrides' : 'they override'
+    } a single command rather than changing what is selected.`,
+    {
+      hint:
+        positional == null
+          ? `Run '${command}' to change what is selected.`
+          : `Run '${command} <${positional.name}>' to change what is selected.`,
+    },
+  )
+}
+
 export const assertKnownArgs = (
   argParams: Record<string, unknown>,
   command: string[],

package/src/lib/auth/operations.ts

@@ -1,5 +1,3 @@
-import { randomBytes } from 'node:crypto'
-
 import { type ConfigStore, getConfigStore } from 'lib/config/index.js'
 import { type AuthContext, resolveAuth } from 'lib/context.js'
 import {
@@ -46,49 +44,33 @@ export const assertMutable = (
   assertEnvVarUnset(envVar, value, action)
 }
 
-export interface LoginOptions {
-  endpoint?: string | undefined
-  token?: string | undefined
-  workspaceId?: string | undefined
-}
-
 /**
- * Store the given credentials, validating the token first.
+ * Store a token, validating it first.
  *
- * The token is stored under the endpoint it will be used with, so a given
- * endpoint is stored and re-resolved before the token key is derived.
+ * The token is stored under the endpoint it will be used with, which
+ * `--endpoint` or the environment may have pointed elsewhere for this one
+ * command: logging in to another endpoint stores a token for it without
+ * selecting it. The workspace is only what the token is validated against,
+ * as a Personal Access Token is meaningless without one.
  *
  * Validation reaches the network, so a test may inject its own `validate`.
  */
 export const login = async (
-  { endpoint, token, workspaceId }: LoginOptions,
+  token: string,
   config: ConfigStore = getConfigStore(),
   validate: typeof validateToken = validateToken,
 ): Promise<void> => {
-  let auth = resolveAuth(config)
+  const auth = resolveAuth(config)
 
   // Nothing is stored while the environment overrides it, so refuse before
-  // storing anything rather than part way through.
+  // validating rather than after reaching the network.
   assertMutable(auth, 'token', 'log in')
-  if (endpoint != null) assertMutable(auth, 'endpoint', 'select an endpoint')
-  if (workspaceId != null) {
-    assertMutable(auth, 'workspaceId', 'select a workspace')
-  }
 
-  if (endpoint != null) {
-    storeEndpoint(endpoint, config)
-    auth = resolveAuth(config)
-  }
+  await validate(token, auth.workspaceId ?? undefined)
 
-  if (token != null) {
-    await validate(token, workspaceId)
-    config.set(`${auth.endpoint}.pat`, token)
-    config.delete('current_workspace_id')
-  }
-
-  if (workspaceId != null) {
-    config.set('current_workspace_id', workspaceId)
-  }
+  config.set(`${auth.endpoint}.pat`, token)
+  // The selection belongs to whoever was logged in before.
+  config.delete('current_workspace_id')
 }
 
 /** Store the token for the current endpoint, e.g., one just prompted for. */
@@ -134,29 +116,6 @@ export const selectWorkspace = (
   config.set('current_workspace_id', workspaceId)
 }
 
-/**
- * Point the CLI at a fake Seam Connect endpoint and store the well-known
- * token it accepts. Returns the generated endpoint URL for reporting.
- */
-export const selectFakeEndpoint = ({
-  urlSeed = randomBytes(5).toString('hex'),
-  config = getConfigStore(),
-}: {
-  urlSeed?: string
-  config?: ConfigStore
-} = {}): { endpoint: string; token: string } => {
-  const auth = resolveAuth(config)
-  assertMutable(auth, 'endpoint', 'select an endpoint')
-  assertMutable(auth, 'token', 'log in')
-
-  const endpoint = `https://${urlSeed}.fakeseamconnect.seam.vc`
-  const token = 'seam_apikey1_token'
-  storeEndpoint(endpoint, config)
-  config.set(`${endpoint}.pat`, token)
-
-  return { endpoint, token }
-}
-
 /** Store whether API definitions come from the endpoint instead of npm. */
 export const setUseRemoteApiDefs = (
   useRemoteApiDefs: boolean,

package/src/lib/commands/local/login.ts

@@ -10,24 +10,13 @@ export const loginCommand: Command = {
     kind: 'cli',
     title: 'Log in to Seam.',
     description:
-      'Prompts for a personal access token unless one is passed with --token.',
-    flags: [
-      stringFlag('endpoint', 'Seam API endpoint to log in to.'),
-      stringFlag('token', 'Personal access token to log in with.'),
-      stringFlag('workspace-id', 'Workspace to select after logging in.'),
-    ],
+      'Prompts for a personal access token unless one is passed with --token. The token is stored for the selected endpoint, or for the one --endpoint names.',
+    flags: [stringFlag('token', 'Personal access token to log in with.')],
   },
   requiresAuth: false,
   execute: async ({ args }, ctx) => {
-    if (args['token'] || args['workspace_id'] || args['endpoint']) {
-      await login(
-        {
-          endpoint: args['endpoint'] ? args['endpoint'] : undefined,
-          token: args['token'] ? String(args['token']).trim() : undefined,
-          workspaceId: args['workspace_id'] ? args['workspace_id'] : undefined,
-        },
-        ctx.config,
-      )
+    if (args['token']) {
+      await login(String(args['token']).trim(), ctx.config)
       return { kind: 'done' }
     }
     assertMutable(ctx.auth, 'token', 'log in')

package/src/lib/commands/local/select-endpoint.ts

@@ -1,6 +1,5 @@
 import { assertMutable, selectEndpoint } from 'lib/auth/operations.js'
 import type { Command } from 'lib/commands/registry.js'
-import { stringFlag } from 'lib/commands/spec.js'
 import { NonInteractiveError } from 'lib/errors.js'
 import { interactForEndpointSelection } from 'lib/interactions/index.js'
 
@@ -9,19 +8,24 @@ export const selectEndpointCommand: Command = {
     path: ['select', 'endpoint'],
     kind: 'cli',
     title: 'Select the Seam API endpoint.',
-    description: '',
-    flags: [stringFlag('endpoint', 'Seam API endpoint to select.')],
+    description:
+      'Stores the endpoint every later command runs against. To use one for a single command instead, pass --endpoint to that command.',
+    flags: [],
+    positional: {
+      name: 'url',
+      description: 'Seam API endpoint to select.',
+    },
   },
   requiresAuth: false,
-  execute: async ({ args }, ctx) => {
+  execute: async ({ positional }, ctx) => {
     assertMutable(ctx.auth, 'endpoint', 'select an endpoint')
-    if (args['endpoint']) {
-      selectEndpoint(args['endpoint'], ctx.config)
+    if (positional != null) {
+      selectEndpoint(positional, ctx.config)
       return { kind: 'done' }
     }
     if (ctx.interactivity === 'non-interactive') {
       throw new NonInteractiveError(
-        'Missing required parameter for select endpoint: --endpoint',
+        'Missing required argument for select endpoint: <url>',
       )
     }
     await interactForEndpointSelection()

package/src/lib/commands/local/select-workspace.ts

@@ -1,4 +1,4 @@
-import { assertMutable } from 'lib/auth/operations.js'
+import { assertMutable, selectWorkspace } from 'lib/auth/operations.js'
 import type { Command } from 'lib/commands/registry.js'
 import { NonInteractiveError } from 'lib/errors.js'
 import { interactForWorkspaceId } from 'lib/interactions/index.js'
@@ -8,15 +8,24 @@ export const selectWorkspaceCommand: Command = {
     path: ['select', 'workspace'],
     kind: 'cli',
     title: 'Select the current workspace.',
-    description: '',
+    description:
+      'Stores the workspace every later command runs against. To use one for a single command instead, pass --workspace-id to that command.',
     flags: [],
+    positional: {
+      name: 'workspace-id',
+      description: 'Workspace to select.',
+    },
   },
   requiresAuth: true,
-  execute: async (_invocation, ctx) => {
+  execute: async ({ positional }, ctx) => {
     assertMutable(ctx.auth, 'workspaceId', 'select a workspace')
+    if (positional != null) {
+      selectWorkspace(positional, ctx.config)
+      return { kind: 'done' }
+    }
     if (ctx.interactivity === 'non-interactive') {
       throw new NonInteractiveError(
-        'Cannot select a workspace in non-interactive mode: pass --workspace-id to "seam login"',
+        'Missing required argument for select workspace: <workspace-id>',
       )
     }
     await interactForWorkspaceId()

package/src/lib/commands/registry.ts

@@ -38,6 +38,8 @@ export interface Command {
 /** Everything a single run of a command was given. */
 export interface Invocation {
   path: string[]
+  /** The value written after the command path, when the command takes one. */
+  positional?: string | undefined
   /** Params given as arguments, held to what the command accepts. */
   argParams: Record<string, unknown>
   /** Params piped in as JSON, passed through as given. */
@@ -93,6 +95,24 @@ export const localCommandDefinitions: CommandDefinition[] = localCommands
 export const findLocalCommand = (path: string[]): Command | undefined =>
   localCommands.find((command) => isSamePath(command.definition.path, path))
 
+/**
+ * The local command the given words invoke with a value after its path, e.g.,
+ * `select endpoint` for `select endpoint https://connect.getseam.com`, or
+ * `undefined` when the words are not a command taking one.
+ *
+ * Only commands declaring a positional match, so a stray word after any other
+ * command stays what it has always been: no command at all.
+ */
+export const findLocalCommandTakingPositional = (
+  words: string[],
+): Command | undefined =>
+  localCommands.find(
+    ({ definition }) =>
+      definition.positional != null &&
+      words.length === definition.path.length + 1 &&
+      isSamePath(definition.path, words.slice(0, -1)),
+  )
+
 /** Parameter names a command accepts as arguments. */
 export const acceptedParamsOf = (definition: CommandDefinition): Set<string> =>
   new Set(

package/src/lib/commands/spec.ts

@@ -23,6 +23,17 @@ export interface CommandFlag {
  */
 export type CommandKind = 'cli' | 'api'
 
+/**
+ * A value written after the command rather than behind a flag, e.g., the URL
+ * in `seam select endpoint <url>`. At most one, always required: it is the
+ * one thing the command is about.
+ */
+export interface CommandPositional {
+  /** Name shown in the usage line, without the angle brackets. */
+  name: string
+  description: string
+}
+
 export interface CommandDefinition {
   path: string[]
   kind: CommandKind
@@ -31,6 +42,8 @@ export interface CommandDefinition {
   /** Longer prose about the command, empty when there is none to add. */
   description: string
   flags: CommandFlag[]
+  /** The value the command takes after its path, when it takes one. */
+  positional?: CommandPositional
 }
 
 export interface Subcommand {
@@ -56,6 +69,15 @@ export interface CommandSpec {
 }
 
 export const globalFlags: CommandFlag[] = [
+  {
+    long: 'endpoint',
+    short: null,
+    description:
+      'Seam API endpoint to run this one command against, instead of the selected one.',
+    values: [],
+    takesValue: true,
+    isRequired: false,
+  },
   {
     long: 'help',
     short: 'h',
@@ -115,6 +137,15 @@ export const globalFlags: CommandFlag[] = [
     takesValue: false,
     isRequired: false,
   },
+  {
+    long: 'workspace-id',
+    short: null,
+    description:
+      'Workspace to run this one command against, instead of the selected one.',
+    values: [],
+    takesValue: true,
+    isRequired: false,
+  },
 ]
 
 export const flagTokens = (flag: CommandFlag): string[] => {

package/src/lib/context.ts

@@ -8,18 +8,20 @@ import {
 } from './env.js'
 import type { SeamApi } from './http/api.js'
 import type { Output } from './output/output.js'
+import { getAuthOverrides } from './overrides.js'
 
 export const defaultEndpoint = 'https://connect.getseam.com'
 
 /** Where a resolved value came from, e.g., to refuse writes the env shadows. */
-export type ValueSource = 'env' | 'config' | 'default'
+export type ValueSource = 'flag' | 'env' | 'config' | 'default'
 
 /**
  * The endpoint, token, and workspace requests are made with.
  *
- * Resolved in one place so the precedence rule exists once: an environment
- * variable wins over the stored value, and the endpoint falls back to Seam.
- * The source tags say where each value came from.
+ * Resolved in one place so the precedence rule exists once: a flag given for
+ * the one command wins over an environment variable, which wins over the
+ * stored value, and the endpoint falls back to Seam. The source tags say
+ * where each value came from.
  */
 export interface AuthContext {
   endpoint: string
@@ -33,35 +35,51 @@ export interface AuthContext {
 export const resolveAuth = (
   config: ConfigStore = getConfigStore(),
 ): AuthContext => {
+  const { endpoint: flagEndpoint, workspaceId: flagWorkspaceId } =
+    getAuthOverrides()
+
   const envEndpoint = getEndpointFromEnv()
   // Configs written before the endpoint was called one still hold it under
   // `server`, so fall back to that key rather than silently resetting them.
   const storedEndpoint = config.get('endpoint') ?? config.get('server')
   const endpoint =
-    envEndpoint ?? (typeof storedEndpoint === 'string' ? storedEndpoint : null)
+    flagEndpoint ??
+    envEndpoint ??
+    (typeof storedEndpoint === 'string' ? storedEndpoint : null)
 
   const envToken = getTokenFromEnv()
+  // The token is stored per endpoint, so an overridden endpoint is read with
+  // the token belonging to it rather than the one it replaced.
   const storedToken = readString(
     config.get(`${endpoint ?? defaultEndpoint}.pat`),
   )
 
   const envWorkspaceId = getWorkspaceIdFromEnv()
   const storedWorkspaceId = readString(config.get('current_workspace_id'))
+  const workspaceId = flagWorkspaceId ?? envWorkspaceId ?? storedWorkspaceId
 
   return {
     endpoint: endpoint ?? defaultEndpoint,
     endpointSource:
-      envEndpoint != null ? 'env' : endpoint != null ? 'config' : 'default',
+      flagEndpoint != null
+        ? 'flag'
+        : envEndpoint != null
+          ? 'env'
+          : endpoint != null
+            ? 'config'
+            : 'default',
     token: envToken ?? storedToken,
     tokenSource:
       envToken != null ? 'env' : storedToken != null ? 'config' : null,
-    workspaceId: envWorkspaceId ?? storedWorkspaceId,
+    workspaceId,
     workspaceIdSource:
-      envWorkspaceId != null
-        ? 'env'
-        : storedWorkspaceId != null
-          ? 'config'
-          : null,
+      flagWorkspaceId != null
+        ? 'flag'
+        : envWorkspaceId != null
+          ? 'env'
+          : storedWorkspaceId != null
+            ? 'config'
+            : null,
   }
 }
 

package/src/lib/interactions/endpoint-selection.ts

@@ -1,24 +1,14 @@
-import { randomBytes } from 'node:crypto'
-
-import {
-  assertMutable,
-  selectEndpoint,
-  selectFakeEndpoint,
-} from 'lib/auth/operations.js'
+import { assertMutable, selectEndpoint } from 'lib/auth/operations.js'
 import { getConfigStore } from 'lib/config/index.js'
 import { resolveAuth } from 'lib/context.js'
 import { getOutput } from 'lib/output/get-output.js'
-import { promptAutocomplete, promptText } from 'lib/prompt.js'
+import { promptAutocomplete } from 'lib/prompt.js'
 
 export async function interactForEndpointSelection() {
   const config = getConfigStore()
   assertMutable(resolveAuth(config), 'endpoint', 'select an endpoint')
 
-  const endpoints = [
-    'http://localhost:3020',
-    'https://connect.getseam.com',
-    'https://fakeseamconnect.seam.vc',
-  ]
+  const endpoints = ['http://localhost:3020', 'https://connect.getseam.com']
 
   // Searchable, as selecting a device or a command is.
   const endpoint = await promptAutocomplete({
@@ -29,20 +19,6 @@ export async function interactForEndpointSelection() {
     })),
   })
 
-  const output = getOutput()
-  if (endpoint === endpoints[2]) {
-    let userUrlSeed = await promptText({
-      message:
-        'You can input a custom endpoint URL or leave this field empty to use a new fakeserver.',
-    })
-
-    if (userUrlSeed.trim().length === 0) {
-      userUrlSeed = randomBytes(5).toString('hex')
-    }
-    selectFakeEndpoint({ urlSeed: userUrlSeed, config })
-    output.info(`PAT set to use fakeseamconnect with "seam_apikey1_token"`)
-  } else {
-    selectEndpoint(endpoint, config)
-  }
-  output.info(`Endpoint set to ${endpoint}`)
+  selectEndpoint(endpoint, config)
+  getOutput().info(`Endpoint set to ${endpoint}`)
 }

package/src/lib/overrides.ts

@@ -0,0 +1,32 @@
+/**
+ * The endpoint and workspace may be overridden for a single command.
+ *
+ * `--endpoint` and `--workspace-id` change what one invocation resolves to
+ * and are never stored: only `seam select endpoint` and `seam select
+ * workspace` write those settings. They are held here rather than threaded
+ * through every call because auth resolves ambiently, exactly as the
+ * environment variables they shadow do (see `env.ts`).
+ *
+ * Set once from the parsed arguments before anything resolves auth, and
+ * reset between tests.
+ */
+
+export interface AuthOverrides {
+  endpoint: string | null
+  workspaceId: string | null
+}
+
+const noOverrides: AuthOverrides = { endpoint: null, workspaceId: null }
+
+let overrides: AuthOverrides = noOverrides
+
+export const getAuthOverrides = (): AuthOverrides => overrides
+
+export const setAuthOverrides = (next: AuthOverrides): void => {
+  overrides = next
+}
+
+/** Drop the overrides, e.g., between tests sharing a process. */
+export const resetAuthOverrides = (): void => {
+  overrides = noOverrides
+}

package/src/lib/render/help.ts

@@ -131,6 +131,7 @@ const commandSections = (
 ): Section[] => {
   const name = ['seam', ...command.path].join(' ')
   const hasFlags = command.flags.length > 0
+  const { positional } = command
 
   return [
     {
@@ -139,7 +140,26 @@ const commandSections = (
         (line) => line !== '',
       ),
     },
-    { header: 'Usage', content: `${name} [options]` },
+    {
+      header: 'Usage',
+      content:
+        positional == null
+          ? `${name} [options]`
+          : `${name} <${positional.name}> [options]`,
+    },
+    ...(positional == null
+      ? []
+      : [
+          {
+            header: 'Arguments',
+            content: [
+              {
+                name: `{underline <${positional.name}>}`,
+                summary: positional.description,
+              },
+            ],
+          },
+        ]),
     // The command's own parameters are what the request is made of, so keep
     // them apart from the options every seam command takes.
     ...(hasFlags ? [optionSection(command.flags, 'Parameters')] : []),

package/src/lib/version.ts

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