@seamapi/cli 0.22.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamapi/cli",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "A command-line interface (CLI) for interacting with the Seam API.",
   "type": "module",
   "main": "index.js",
@@ -95,7 +95,7 @@
     "@clack/prompts": "^1.7.0",
     "@seamapi/blueprint": "1.5.0",
     "@seamapi/http": "2.2.0",
-    "@seamapi/wizard": "0.5.2",
+    "@seamapi/wizard": "0.7.0",
     "chalk": "^6.0.0",
     "command-line-usage": "^7.0.4",
     "configstore": "^8.0.0",

package/src/bin/cli.ts

@@ -21,7 +21,7 @@ import {
   findLocalCommand,
   findLocalCommandTakingPositional,
 } from 'lib/commands/registry.js'
-import { getConfigStore } from 'lib/config/index.js'
+import { getConfig } from 'lib/config/index.js'
 import { type CliContext, resolveAuth } from 'lib/context.js'
 import { tokenEnvVar } from 'lib/env.js'
 import { reportErrorAndExit } from 'lib/errors.js'
@@ -41,7 +41,7 @@ import { renderHelp } from 'lib/render/help.js'
 import seamapiCliVersion from 'lib/version.js'
 
 async function cli(args: ParsedArgs, argv: string[]) {
-  const config = getConfigStore()
+  const config = getConfig()
   const output = getOutput()
 
   // Scoped to this one command, and read wherever auth resolves, so they are
@@ -63,7 +63,7 @@ async function cli(args: ParsedArgs, argv: string[]) {
 
   const helpFlag = args['help'] ?? args['h']
   if (helpFlag != null) {
-    // Help comes from the cached API definitions so that it works without
+    // Help comes from the cached API schema so that it works without
     // logging in, and offline once the cache is warm.
     const cachedBlueprint = await getApiBlueprint({ update })
     const { spec } = buildRegistry(cachedBlueprint)
@@ -157,11 +157,10 @@ async function cli(args: ParsedArgs, argv: string[]) {
     return
   }
 
-  const useRemoteApiDefs =
-    args['remote_api_defs'] ?? config.get('use_remote_api_defs')
+  const useRemoteSchema = args['remote_schema'] ?? config.getUseRemoteSchema()
 
   const blueprint = await getApiBlueprint({
-    useRemoteDefinitions: useRemoteApiDefs ?? false,
+    useRemoteSchema: useRemoteSchema ?? false,
     update,
   })
 

package/src/lib/args/parse.ts

@@ -35,7 +35,7 @@ export const cliFlags: string[] = [
   'h',
   'help',
   'json',
-  'remote_api_defs',
+  'remote_schema',
   'update',
   'version',
   'workspace_id',

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,
@@ -57,7 +57,7 @@ export const assertMutable = (
  */
 export const login = async (
   token: string,
-  config: ConfigStore = getConfigStore(),
+  config: CliConfig = getConfig(),
   validate: typeof validateToken = validateToken,
 ): Promise<void> => {
   const auth = resolveAuth(config)
@@ -68,30 +68,27 @@ export const login = async (
 
   await validate(token, auth.workspaceId ?? undefined)
 
-  config.set(`${auth.endpoint}.pat`, token)
+  config.setToken(auth.endpoint, token)
   // The selection belongs to whoever was logged in before.
-  config.delete('current_workspace_id')
+  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()
 }
 
 /**
@@ -101,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(),
+/** Store whether the API schema comes from the endpoint instead of npm. */
+export const setUseRemoteSchema = (
+  useRemoteSchema: boolean,
+  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.setUseRemoteSchema(useRemoteSchema)
 }

package/src/lib/blueprint/index.ts

@@ -10,18 +10,18 @@ export interface GetApiBlueprintOptions {
    * Build from the OpenAPI document the configured endpoint is currently
    * running, instead of the published npm types.
    */
-  useRemoteDefinitions?: boolean
-  /** Force an update of the cached Seam API definitions. */
+  useRemoteSchema?: boolean
+  /** Force an update of the cached Seam API schema. */
   update?: boolean
 }
 
 export const getApiBlueprint = async ({
-  useRemoteDefinitions = false,
+  useRemoteSchema = false,
   update = false,
 }: GetApiBlueprintOptions = {}): Promise<ApiBlueprint> => {
-  // Remote definitions describe whatever the endpoint is currently running, so
-  // build them directly from that endpoint's OpenAPI document.
-  if (useRemoteDefinitions) return await createRemoteBlueprint()
+  // The remote schema describes whatever the endpoint is currently running, so
+  // build it directly from that endpoint's OpenAPI document.
+  if (useRemoteSchema) return await createRemoteBlueprint()
 
   return await getBlueprint({ update })
 }

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()
 
@@ -59,7 +58,7 @@ export const getBlueprint = async (
     // over failing, unless an update was explicitly requested.
     if (cache != null && !update) return cache.blueprint
     throw new Error(
-      `Could not check for Seam API definition updates: ${toErrorMessage(error)}`,
+      `Could not check for Seam API schema updates: ${toErrorMessage(error)}`,
     )
   }
 
@@ -74,13 +73,13 @@ export const getBlueprint = async (
   let blueprint: Blueprint
   try {
     blueprint = await withLoading(
-      `Downloading Seam API definitions (${typesPackageName}@${manifest.version})`,
+      `Downloading Seam API schema (${typesPackageName}@${manifest.version})`,
       async () => await generateBlueprint(manifest, cacheDirectory),
     )
   } catch (error) {
     if (cache != null && !update) return cache.blueprint
     throw new Error(
-      `Could not update Seam API definitions: ${toErrorMessage(error)}`,
+      `Could not update Seam API schema: ${toErrorMessage(error)}`,
     )
   }
 

package/src/lib/commands/api-command.ts

@@ -94,7 +94,7 @@ export const executeApiCommand = async (
 
 /**
  * Per-endpoint request policy that is not derivable from the API
- * definitions. Keep this table small and explicit.
+ * schema. Keep this table small and explicit.
  */
 const applyEndpointDefaults = (
   path: string[],

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

@@ -10,9 +10,9 @@ import {
 /**
  * Print the completion script for a 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.
+ * Completions always come from the cached API schema so that they can
+ * be generated without logging in. They may lag the schema served by
+ * Seam when config use-remote-schema is enabled.
  *
  * Called by the entry before any auth or blueprint context exists, and by
  * the registered command's executor — one implementation for both.

package/src/lib/commands/local/{config-use-remote-api-defs.ts → config-use-remote-schema.ts}

@@ -1,12 +1,12 @@
 import type { Command } from 'lib/commands/registry.js'
 import { NonInteractiveError } from 'lib/errors.js'
-import { interactForUseRemoteApiDefs } from 'lib/interactions/index.js'
+import { interactForUseRemoteSchema } from 'lib/interactions/index.js'
 
-export const configUseRemoteApiDefsCommand: Command = {
+export const configUseRemoteSchemaCommand: Command = {
   definition: {
-    path: ['config', 'use-remote-api-defs'],
+    path: ['config', 'use-remote-schema'],
     kind: 'cli',
-    title: 'Choose whether to use the API definitions served by Seam.',
+    title: 'Choose whether to use the schema served by Seam.',
     description: '',
     flags: [],
   },
@@ -14,10 +14,10 @@ export const configUseRemoteApiDefsCommand: Command = {
   execute: async (_invocation, ctx) => {
     if (ctx.interactivity === 'non-interactive') {
       throw new NonInteractiveError(
-        'Cannot select whether to use remote API definitions in non-interactive mode',
+        'Cannot select whether to use the remote schema in non-interactive mode',
       )
     }
-    await interactForUseRemoteApiDefs()
+    await interactForUseRemoteSchema()
     return { kind: 'done' }
   },
 }

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

@@ -7,7 +7,7 @@ import type { CliContext } from 'lib/context.js'
 import { executeApiCommand } from './api-command.js'
 import { createCompletionCommands } from './local/completion.js'
 import { configRevealLocationCommand } from './local/config-reveal-location.js'
-import { configUseRemoteApiDefsCommand } from './local/config-use-remote-api-defs.js'
+import { configUseRemoteSchemaCommand } from './local/config-use-remote-schema.js'
 import { healthCommand } from './local/health.js'
 import { loginCommand } from './local/login.js'
 import { logoutCommand } from './local/logout.js'
@@ -73,7 +73,7 @@ const completionCommands = createCompletionCommands(
 export const localCommands: Command[] = [
   ...completionCommands,
   configRevealLocationCommand,
-  configUseRemoteApiDefsCommand,
+  configUseRemoteSchemaCommand,
   healthCommand,
   loginCommand,
   logoutCommand,

package/src/lib/commands/spec.ts

@@ -114,9 +114,9 @@ export const globalFlags: CommandFlag[] = [
     isRequired: false,
   },
   {
-    long: 'remote-api-defs',
+    long: 'remote-schema',
     short: null,
-    description: 'Use the API definitions served by the Seam API.',
+    description: 'Use the schema served by the Seam API.',
     values: [],
     takesValue: false,
     isRequired: false,
@@ -124,7 +124,7 @@ export const globalFlags: CommandFlag[] = [
   {
     long: 'update',
     short: null,
-    description: 'Force an update of the cached Seam API definitions.',
+    description: 'Force an update of the cached Seam API schema.',
     values: [],
     takesValue: false,
     isRequired: false,
@@ -156,7 +156,7 @@ export const flagTokens = (flag: CommandFlag): string[] => {
 }
 
 /**
- * Derive the command spec from the API definitions, merged with the commands
+ * Derive the command spec from the API schema, merged with the commands
  * the CLI declares itself (see `commands/registry.ts`, the single source of
  * those declarations).
  */
@@ -251,7 +251,7 @@ const toFlagValues = (parameter: Parameter): string[] => {
 
 /**
  * Whether a word is safe to write into a shell script. Command, flag, and
- * enum names come from the API definitions and are embedded unquoted or
+ * enum names come from the API schema and are embedded unquoted or
  * single-quoted in completion scripts, so never emit one that a shell could
  * read as syntax.
  */
@@ -298,7 +298,7 @@ const toCommandGroups = (commands: CommandDefinition[]): CommandGroup[] => {
     }
   }
 
-  // Groups have no description of their own in the API definitions, so name
+  // Groups have no description of their own in the API schema, so name
   // the commands they hold instead. Leave the list whole: help wraps it, and
   // completion shortens it to fit a menu column.
   const summarizeGroup = (key: string): string =>

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

@@ -0,0 +1,87 @@
+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
+  getUseRemoteSchema: () => boolean | null
+  setUseRemoteSchema: (useRemoteSchema: 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')
+  },
+
+  getUseRemoteSchema: () => {
+    // `use_remote_api_defs` is what an older CLI called the same setting.
+    const useRemoteSchema =
+      store.get('use_remote_schema') ?? store.get('use_remote_api_defs')
+    return typeof useRemoteSchema === 'boolean' ? useRemoteSchema : null
+  },
+
+  /** Store the setting, dropping any value left under the legacy key. */
+  setUseRemoteSchema: (useRemoteSchema) => {
+    store.set('use_remote_schema', useRemoteSchema)
+    store.delete('use_remote_api_defs')
+  },
+})
+
+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))