@seamapi/cli 0.21.0 → 0.23.0

package/src/lib/auth/operations.ts

@@ -1,4 +1,4 @@
-import { type ConfigStore, getConfigStore } from 'lib/config/index.js'
+import { type CliConfig, getConfig } from 'lib/config/index.js'
 import { type AuthContext, resolveAuth } from 'lib/context.js'
 import {
   assertEnvVarUnset,
@@ -44,70 +44,51 @@ 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,
-  config: ConfigStore = getConfigStore(),
+  token: string,
+  config: CliConfig = getConfig(),
   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)
-  }
 
-  if (token != null) {
-    await validate(token, workspaceId)
-    config.set(`${auth.endpoint}.pat`, token)
-    config.delete('current_workspace_id')
-  }
+  await validate(token, auth.workspaceId ?? undefined)
 
-  if (workspaceId != null) {
-    config.set('current_workspace_id', workspaceId)
-  }
+  config.setToken(auth.endpoint, token)
+  // The selection belongs to whoever was logged in before.
+  config.unsetWorkspace()
 }
 
 /** Store the token for the current endpoint, e.g., one just prompted for. */
 export const storeToken = (
   token: string,
-  config: ConfigStore = getConfigStore(),
+  config: CliConfig = getConfig(),
 ): void => {
   const auth = resolveAuth(config)
   assertMutable(auth, 'token', 'log in')
-  config.set(`${auth.endpoint}.pat`, token)
+  config.setToken(auth.endpoint, token)
 }
 
 /** Remove the stored token and workspace selection. */
-export const logout = (config: ConfigStore = getConfigStore()): void => {
+export const logout = (config: CliConfig = getConfig()): void => {
   const auth = resolveAuth(config)
   assertMutable(auth, 'token', 'log out')
-  config.delete(`${auth.endpoint}.pat`)
-  // Configs written before tokens were stored per endpoint may still hold an
-  // un-namespaced token, so drop that too.
-  config.delete('pat')
-  config.delete('current_workspace_id')
+  config.unsetToken(auth.endpoint)
+  config.unsetWorkspace()
 }
 
 /**
@@ -117,36 +98,25 @@ export const logout = (config: ConfigStore = getConfigStore()): void => {
  */
 export const selectEndpoint = (
   endpoint: string,
-  config: ConfigStore = getConfigStore(),
+  config: CliConfig = getConfig(),
 ): void => {
   assertMutable(resolveAuth(config), 'endpoint', 'select an endpoint')
-  storeEndpoint(endpoint, config)
+  config.setEndpoint(endpoint)
 }
 
 /** Store the workspace requests are made against. */
 export const selectWorkspace = (
   workspaceId: string,
-  config: ConfigStore = getConfigStore(),
+  config: CliConfig = getConfig(),
 ): void => {
   assertMutable(resolveAuth(config), 'workspaceId', 'select a workspace')
-  config.set('current_workspace_id', workspaceId)
+  config.setWorkspace(workspaceId)
 }
 
 /** Store whether API definitions come from the endpoint instead of npm. */
 export const setUseRemoteApiDefs = (
   useRemoteApiDefs: boolean,
-  config: ConfigStore = getConfigStore(),
+  config: CliConfig = getConfig(),
 ): void => {
-  config.set('use_remote_api_defs', useRemoteApiDefs)
-}
-
-/**
- * Write the endpoint, dropping what belonged to the previous one: the
- * workspace selection, and any value left under the legacy `server` key that
- * {@link resolveAuth} would otherwise still fall back to.
- */
-const storeEndpoint = (endpoint: string, config: ConfigStore): void => {
-  config.set('endpoint', endpoint)
-  config.delete('server')
-  config.delete('current_workspace_id')
+  config.setUseRemoteApiDefs(useRemoteApiDefs)
 }

package/src/lib/blueprint/source-npm.ts

@@ -3,9 +3,9 @@ import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
 import type { Blueprint, TypesModuleInput } from '@seamapi/blueprint'
-import envPaths from 'env-paths'
 import { extract } from 'tar'
 
+import { rootPaths } from 'lib/config/index.js'
 import { withLoading } from 'lib/output/with-loading.js'
 
 import {
@@ -38,8 +38,7 @@ export const getBlueprint = async (
   options: GetBlueprintOptions = {},
 ): Promise<Blueprint> => {
   const update = options.update ?? false
-  const cacheDirectory =
-    options.cacheDirectory ?? envPaths('seam', { suffix: '' }).cache
+  const cacheDirectory = options.cacheDirectory ?? rootPaths.cache
   const cacheFile = getCacheFile(cacheDirectory)
   const blueprintVersion = await getBlueprintVersion()
 

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/local/wizard.ts

@@ -1,4 +1,12 @@
+import { join } from 'node:path'
+
+import { isApiKey } from '@seamapi/http/connect'
+import type { StorageAdapter, WizardAdapter, WizardAuth } from '@seamapi/wizard'
+import Configstore from 'configstore'
+
 import type { Command } from 'lib/commands/registry.js'
+import { type CliConfig, getConfig, rootPaths } from 'lib/config/index.js'
+import { resolveAuth } from 'lib/context.js'
 
 /**
  * Run the Seam setup wizard.
@@ -11,6 +19,7 @@ export const runWizard = async (argv: string[]): Promise<void> => {
   await wizard({
     argv,
     commandName: 'seam wizard',
+    adapter: createWizardAdapter(),
   })
 }
 
@@ -29,3 +38,42 @@ export const wizardCommand: Command = {
     return { kind: 'done' }
   },
 }
+
+const wizardFileName = 'wizard.json'
+
+export const createWizardAdapter = ({
+  cliConfig = getConfig(),
+  configPath = join(rootPaths.config, wizardFileName),
+  statePath = join(rootPaths.log, wizardFileName),
+}: {
+  cliConfig?: CliConfig
+  configPath?: string
+  statePath?: string
+} = {}): WizardAdapter => ({
+  getAuth: async () => toWizardAuth(cliConfig),
+  config: createStorage(configPath),
+  state: createStorage(statePath),
+})
+
+// Only a workspace-scoped key may go in a project, so a personal access
+// token is not handed over at all.
+const toWizardAuth = (cliConfig: CliConfig): WizardAuth => {
+  const { endpoint, token, workspaceId } = resolveAuth(cliConfig)
+
+  return {
+    endpoint,
+    apiKey: token != null && isApiKey(token) ? token : null,
+    workspaceId,
+  }
+}
+
+const createStorage = (path: string): StorageAdapter => {
+  const store = new Configstore('seam-cli', undefined, { configPath: path })
+
+  return {
+    get: async (key) => store.get(key),
+    set: async (key, value) => {
+      store.set(key, value)
+    },
+  }
+}

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/config/cli-config.ts

@@ -0,0 +1,83 @@
+import type { ConfigStore } from './config-store.js'
+
+/** Tokens are stored per endpoint, e.g. `https://connect.getseam.com.pat`. */
+const tokenKey = (endpoint: string): `${string}.pat` => `${endpoint}.pat`
+
+/**
+ * The CLI's configuration, in the terms the CLI thinks in. Keys are named
+ * here alone: a caller says what it wants stored, not where it goes.
+ */
+export interface CliConfig {
+  readonly path: string
+  getEndpoint: () => string | null
+  setEndpoint: (endpoint: string) => void
+  getToken: (endpoint: string) => string | null
+  setToken: (endpoint: string, token: string) => void
+  unsetToken: (endpoint: string) => void
+  getWorkspace: () => string | null
+  setWorkspace: (workspaceId: string) => void
+  unsetWorkspace: () => void
+  getUseRemoteApiDefs: () => boolean | null
+  setUseRemoteApiDefs: (useRemoteApiDefs: boolean) => void
+}
+
+export const createCliConfig = (store: ConfigStore): CliConfig => ({
+  get path() {
+    return store.path
+  },
+
+  getEndpoint: () =>
+    // `server` is what an older CLI called the endpoint.
+    readString(store.get('endpoint')) ?? readString(store.get('server')),
+
+  /**
+   * Store the endpoint, dropping what belonged to the previous one: the
+   * workspace selection, and any value left under the legacy key that
+   * {@link CliConfig.getEndpoint} would otherwise still fall back to.
+   */
+  setEndpoint: (endpoint) => {
+    store.set('endpoint', endpoint)
+    store.delete('server')
+    store.delete('current_workspace_id')
+  },
+
+  getToken: (endpoint) => readString(store.get(tokenKey(endpoint))),
+
+  setToken: (endpoint, token) => {
+    store.set(tokenKey(endpoint), token)
+  },
+
+  unsetToken: (endpoint) => {
+    store.delete(tokenKey(endpoint))
+    // Configs written before tokens were stored per endpoint may still hold
+    // an un-namespaced one.
+    store.delete('pat')
+  },
+
+  getWorkspace: () => readString(store.get('current_workspace_id')),
+
+  setWorkspace: (workspaceId) => {
+    store.set('current_workspace_id', workspaceId)
+  },
+
+  unsetWorkspace: () => {
+    store.delete('current_workspace_id')
+  },
+
+  getUseRemoteApiDefs: () => {
+    const useRemoteApiDefs = store.get('use_remote_api_defs')
+    return typeof useRemoteApiDefs === 'boolean' ? useRemoteApiDefs : null
+  },
+
+  setUseRemoteApiDefs: (useRemoteApiDefs) => {
+    store.set('use_remote_api_defs', useRemoteApiDefs)
+  },
+})
+
+const readString = (value: unknown): string | null => {
+  if (typeof value !== 'string') return null
+
+  const trimmedValue = value.trim()
+
+  return trimmedValue === '' ? null : trimmedValue
+}

package/src/lib/config/config-store.ts

@@ -3,12 +3,15 @@ import { join } from 'node:path'
 import Configstore from 'configstore'
 import envPaths from 'env-paths'
 
+import { type CliConfig, createCliConfig } from './cli-config.js'
 import { migrateConfigStore } from './migrate.js'
 import { isStateKey, mergeConfig, splitConfig } from './values.js'
 
 const configFileName = 'cli.json'
 const legacyConfigStoreId = 'seam-cli'
-const paths = envPaths('seam', { suffix: '' })
+
+/** Every directory the CLI keeps files in, and what it mounts keeps its own. */
+export const rootPaths = envPaths('seam', { suffix: '' })
 
 /**
  * What a config store can do, regardless of where it keeps the values.
@@ -28,21 +31,21 @@ export interface ConfigStore {
   clear: () => void
 }
 
-let configStore: ConfigStore | null = null
+let config: CliConfig | null = null
 
-export const getConfigStore = (): ConfigStore => {
-  configStore ??= createConfigStore()
-  return configStore
+export const getConfig = (): CliConfig => {
+  config ??= createCliConfig(createConfigStore())
+  return config
 }
 
-/** Replace the store, e.g., with an in-memory one for a test. */
-export const setConfigStore = (store: ConfigStore): void => {
-  configStore = store
+/** Replace the config, e.g., with an in-memory one for a test. */
+export const setConfig = (nextConfig: CliConfig): void => {
+  config = nextConfig
 }
 
-/** Drop the current store so the next read builds the real one. */
-export const resetConfigStore = (): void => {
-  configStore = null
+/** Drop the current config so the next read builds the real one. */
+export const resetConfig = (): void => {
+  config = null
 }
 
 const createConfigStore = (): PersistentConfigStore => {
@@ -121,11 +124,11 @@ export class PersistentConfigStore implements ConfigStore {
 }
 
 const getConfigPath = (): string => {
-  return join(paths.config, configFileName)
+  return join(rootPaths.config, configFileName)
 }
 
 const getStateConfigPath = (): string => {
-  return join(paths.log, configFileName)
+  return join(rootPaths.log, configFileName)
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> => {

package/src/lib/config/index.ts

@@ -1,8 +1,13 @@
+export { type CliConfig, createCliConfig } from './cli-config.js'
 export {
   type ConfigStore,
-  getConfigStore,
+  getConfig,
   type PersistentConfigStore,
-  resetConfigStore,
-  setConfigStore,
+  resetConfig,
+  rootPaths,
+  setConfig,
 } from './config-store.js'
-export { createMemoryConfigStore } from './memory-config-store.js'
+export {
+  createMemoryConfig,
+  createMemoryConfigStore,
+} from './memory-config-store.js'

package/src/lib/config/memory-config-store.ts

@@ -1,3 +1,4 @@
+import { type CliConfig, createCliConfig } from './cli-config.js'
 import type { ConfigStore } from './config-store.js'
 
 /**
@@ -60,3 +61,11 @@ export class MemoryConfigStore implements ConfigStore {
 export const createMemoryConfigStore = (
   initialValues: Record<string, unknown> = {},
 ): ConfigStore => new MemoryConfigStore(initialValues)
+
+/**
+ * A config held in memory, for tests. Values may be seeded by key, e.g., to
+ * stand for a config an older CLI wrote.
+ */
+export const createMemoryConfig = (
+  initialValues: Record<string, unknown> = {},
+): CliConfig => createCliConfig(createMemoryConfigStore(initialValues))