@seamapi/cli 0.21.0 → 0.22.0

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/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.21.0'
+const seamapiCliVersion = '0.22.0'
 const seamapiBlueprintVersion = '1.5.0'
 
 export { seamapiBlueprintVersion }