@seamapi/cli 0.18.1 → 0.19.0

package/src/lib/commands/registry.ts

@@ -0,0 +1,127 @@
+import type { ParsedArgs } from 'minimist'
+
+import { toParameterName } from 'lib/args/parse.js'
+import type { ApiBlueprint } from 'lib/blueprint/index.js'
+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 { configSetFakeServerCommand } from './local/config-set-fake-server.js'
+import { configUseRemoteApiDefsCommand } from './local/config-use-remote-api-defs.js'
+import { healthCommand } from './local/health.js'
+import { loginCommand } from './local/login.js'
+import { logoutCommand } from './local/logout.js'
+import { selectServerCommand } from './local/select-server.js'
+import { selectWorkspaceCommand } from './local/select-workspace.js'
+import { wizardCommand } from './local/wizard.js'
+import {
+  type CommandDefinition,
+  type CommandSpec,
+  getCommandSpec,
+  isSamePath,
+} from './spec.js'
+
+/**
+ * One invocable command: what it looks like to help, completion, and the
+ * interactive picker, whether it needs a login, and how to run it. Declaring
+ * the metadata and the executor together is what keeps them from drifting.
+ */
+export interface Command {
+  definition: CommandDefinition
+  /** Whether the command needs a token before it can do anything. */
+  requiresAuth: boolean
+  /** Kept out of the spec, so out of help, completion, and the picker. */
+  hidden?: boolean
+  execute: (invocation: Invocation, ctx: CliContext) => Promise<CommandResult>
+}
+
+/** Everything a single run of a command was given. */
+export interface Invocation {
+  path: string[]
+  /** Params given as arguments, held to what the command accepts. */
+  argParams: Record<string, unknown>
+  /** Params piped in as JSON, passed through as given. */
+  stdinParams: Record<string, unknown>
+  /** The full parsed arguments, for commands that read their own flags. */
+  args: ParsedArgs
+  /** The raw argv, for commands that re-read arguments with their own types. */
+  argv: string[]
+}
+
+export type CommandResult =
+  | { kind: 'done' }
+  /** Navigate back to selecting a command under `toPath`. */
+  | { kind: 'back'; toPath: string[] }
+
+export interface CommandRegistry {
+  /** The spec help, completion, and the interactive picker render. */
+  spec: CommandSpec
+  find: (path: string[]) => Command | undefined
+}
+
+/**
+ * Commands handled by the CLI itself, which have no endpoint in the
+ * blueprint. The single source of truth: the spec, the picker, and the
+ * dispatcher all consume this list.
+ */
+const completionCommands = createCompletionCommands(
+  (blueprint) => buildRegistry(blueprint).spec,
+)
+
+export const localCommands: Command[] = [
+  ...completionCommands,
+  configRevealLocationCommand,
+  configSetFakeServerCommand,
+  configUseRemoteApiDefsCommand,
+  healthCommand,
+  loginCommand,
+  logoutCommand,
+  selectServerCommand,
+  selectWorkspaceCommand,
+  wizardCommand,
+]
+
+/** Definitions shown in help, completion, and the picker. */
+export const localCommandDefinitions: CommandDefinition[] = localCommands
+  .filter((command) => command.hidden !== true)
+  .map((command) => command.definition)
+
+/**
+ * The local command going by a path, or `undefined` when the path is an
+ * endpoint or no command at all. Needs no blueprint, so the entry may check
+ * commands before any definitions are loaded.
+ */
+export const findLocalCommand = (path: string[]): Command | undefined =>
+  localCommands.find((command) => isSamePath(command.definition.path, path))
+
+/** Parameter names a command accepts as arguments. */
+export const acceptedParamsOf = (definition: CommandDefinition): Set<string> =>
+  new Set(
+    definition.flags.flatMap(({ long }) =>
+      long == null ? [] : [toParameterName(long)],
+    ),
+  )
+
+export const buildRegistry = (blueprint: ApiBlueprint): CommandRegistry => {
+  const spec = getCommandSpec(blueprint, localCommandDefinitions)
+
+  const commands = new Map<string, Command>()
+  for (const definition of spec.commands) {
+    commands.set(definition.path.join(' '), {
+      definition,
+      requiresAuth: true,
+      execute: executeApiCommand,
+    })
+  }
+  // Local commands win over a same-named endpoint, as the spec's dedupe does,
+  // and hidden ones are findable without being in the spec.
+  for (const command of localCommands) {
+    commands.set(command.definition.path.join(' '), command)
+  }
+
+  return {
+    spec,
+    find: (path) => commands.get(path.join(' ')),
+  }
+}

package/src/lib/{command-spec.ts → commands/spec.ts}

@@ -1,5 +1,7 @@
 import type { Blueprint } from '@seamapi/blueprint'
 
+import { firstSentence, toPlainText } from 'lib/render/text.js'
+
 type Endpoint = Blueprint['routes'][number]['endpoints'][number]
 type Parameter = Endpoint['request']['parameters'][number]
 
@@ -122,7 +124,15 @@ export const flagTokens = (flag: CommandFlag): string[] => {
   return tokens
 }
 
-export const getCommandSpec = (blueprint: Blueprint): CommandSpec => {
+/**
+ * Derive the command spec from the API definitions, merged with the commands
+ * the CLI declares itself (see `commands/registry.ts`, the single source of
+ * those declarations).
+ */
+export const getCommandSpec = (
+  blueprint: Blueprint,
+  localCommands: CommandDefinition[] = [],
+): CommandSpec => {
   const commands = sortByPath(
     dedupeByPath([
       ...blueprint.routes
@@ -151,22 +161,10 @@ 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 =>
+export const isSamePath = (a: string[], b: string[]): boolean =>
   a.length === b.length && a.every((word, index) => word === b[index])
 
-const stringFlag = (long: string, description: string): CommandFlag => ({
+export const stringFlag = (long: string, description: string): CommandFlag => ({
   long,
   short: null,
   description,
@@ -175,98 +173,6 @@ const stringFlag = (long: string, description: string): CommandFlag => ({
   isRequired: false,
 })
 
-/**
- * Commands handled by the CLI itself, which have no endpoint in the blueprint.
- *
- * Keep in sync with the command handling in `src/bin/cli.ts` and the extra
- * commands offered by `interactForCommandSelection`.
- */
-const localCommands: CommandDefinition[] = [
-  {
-    path: ['completion', 'bash'],
-    kind: 'cli',
-    title: 'Print the bash completion script.',
-    description: '',
-    flags: [],
-  },
-  {
-    path: ['completion', 'fish'],
-    kind: 'cli',
-    title: 'Print the fish completion script.',
-    description: '',
-    flags: [],
-  },
-  {
-    path: ['completion', 'zsh'],
-    kind: 'cli',
-    title: 'Print the zsh completion script.',
-    description: '',
-    flags: [],
-  },
-  {
-    path: ['config', 'reveal-location'],
-    kind: 'cli',
-    title: 'Print the path to the CLI configuration file.',
-    description: '',
-    flags: [],
-  },
-  {
-    path: ['config', 'use-remote-api-defs'],
-    kind: 'cli',
-    title: 'Choose whether to use the API definitions served by Seam.',
-    description: '',
-    flags: [],
-  },
-  {
-    path: ['health', 'get-health'],
-    kind: 'api',
-    title: 'Report the health of the Seam API.',
-    description: '',
-    flags: [],
-  },
-  {
-    path: ['login'],
-    kind: 'cli',
-    title: 'Log in to Seam.',
-    description:
-      'Prompts for a personal access token unless one is passed with --token.',
-    flags: [
-      stringFlag('server', 'Seam API server to log in to.'),
-      stringFlag('token', 'Personal access token to log in with.'),
-      stringFlag('workspace-id', 'Workspace to select after logging in.'),
-    ],
-  },
-  {
-    path: ['logout'],
-    kind: 'cli',
-    title: 'Log out of Seam.',
-    description: '',
-    flags: [],
-  },
-  {
-    path: ['select', 'server'],
-    kind: 'cli',
-    title: 'Select the Seam API server.',
-    description: '',
-    flags: [stringFlag('server', 'Seam API server to select.')],
-  },
-  {
-    path: ['select', 'workspace'],
-    kind: 'cli',
-    title: 'Select the current workspace.',
-    description: '',
-    flags: [],
-  },
-  {
-    path: ['wizard'],
-    kind: 'cli',
-    title: 'Set up Seam in the current project.',
-    description:
-      'Takes a project from zero to a working Seam integration. Run seam wizard --help for its own options.',
-    flags: [],
-  },
-]
-
 const toCommandDefinition = (endpoint: Endpoint): CommandDefinition => {
   const description = toPlainText(endpoint.description)
 
@@ -295,19 +201,21 @@ const toCommandFlag = (parameter: Parameter): CommandFlag => ({
 })
 
 const toFlagValues = (parameter: Parameter): string[] => {
-  if (parameter.format === 'enum') {
-    return parameter.values.map(({ name }) => name).filter(isSafeToken)
-  }
+  let values: string[] = []
 
-  if (parameter.format === 'list' && parameter.itemFormat === 'enum') {
-    return parameter.itemEnumValues.map(({ name }) => name).filter(isSafeToken)
+  if (parameter.format === 'enum') {
+    values = parameter.values.map(({ name }) => name).filter(isSafeToken)
+  } else if (parameter.format === 'list' && parameter.itemFormat === 'enum') {
+    values = parameter.itemEnumValues
+      .map(({ name }) => name)
+      .filter(isSafeToken)
+  } else if (parameter.format === 'boolean') {
+    // Nothing marks parameters as boolean-only flags, so minimist reads the
+    // next argument as the value.
+    values = ['true', 'false']
   }
 
-  // Nothing marks parameters as boolean-only flags, so minimist reads the next
-  // argument as the value.
-  if (parameter.format === 'boolean') return ['true', 'false']
-
-  return []
+  return parameter.isNullable ? [...values, 'null'] : values
 }
 
 /**
@@ -342,7 +250,11 @@ const toCommandGroups = (commands: CommandDefinition[]): CommandGroup[] => {
       // `seam devices` alongside `seam devices list`. Prefer the command
       // title, since it describes what running the name does.
       if (depth === command.path.length - 1) {
-        entries.set(name, { isCommand: true, kind, description: command.title })
+        entries.set(name, {
+          isCommand: true,
+          kind,
+          description: command.title,
+        })
         continue
       }
 
@@ -397,16 +309,3 @@ const toCommandPath = (path: string): string[] =>
   path.replace(/^\//, '').split('/').map(toFlagName)
 
 const toFlagName = (name: string): string => name.replace(/_/g, '-')
-
-/** Reduce documentation markdown to a single line of prose. */
-export const toPlainText = (markdown: string): string =>
-  markdown
-    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
-    .replace(/[`*]/g, '')
-    .replace(/\s+/g, ' ')
-    .trim()
-
-export const firstSentence = (text: string): string => {
-  const [sentence] = text.split(/(?<=\.)\s/)
-  return sentence ?? text
-}

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

@@ -4,14 +4,48 @@ import Configstore from 'configstore'
 import envPaths from 'env-paths'
 
 import { migrateConfigStore } from './migrate.js'
+import { isStateKey, mergeConfig, splitConfig } from './values.js'
 
 const configFileName = 'cli.json'
 const legacyConfigStoreId = 'seam-cli'
-const currentWorkspaceIdKey = 'current_workspace_id'
-const patKey = 'pat'
 const paths = envPaths('seam', { suffix: '' })
 
-export const getConfigStore = () => {
+/**
+ * What a config store can do, regardless of where it keeps the values.
+ *
+ * The CLI reads and writes through this interface so a test may hand code an
+ * in-memory store (see `memory-config-store.ts`) instead of the real
+ * file-backed one.
+ */
+export interface ConfigStore {
+  readonly path: string
+  all: Record<string, unknown>
+  readonly size: number
+  get: (key: string) => unknown
+  set: (key: string | Record<string, unknown>, value?: unknown) => void
+  has: (key: string) => boolean
+  delete: (key: string) => void
+  clear: () => void
+}
+
+let configStore: ConfigStore | null = null
+
+export const getConfigStore = (): ConfigStore => {
+  configStore ??= createConfigStore()
+  return configStore
+}
+
+/** Replace the store, e.g., with an in-memory one for a test. */
+export const setConfigStore = (store: ConfigStore): void => {
+  configStore = store
+}
+
+/** Drop the current store so the next read builds the real one. */
+export const resetConfigStore = (): void => {
+  configStore = null
+}
+
+const createConfigStore = (): PersistentConfigStore => {
   const settingsStore = new Configstore(legacyConfigStoreId, undefined, {
     configPath: getConfigPath(),
   })
@@ -25,61 +59,10 @@ export const getConfigStore = () => {
     new Configstore(legacyConfigStoreId),
   )
 
-  return new SeamConfigStore(settingsStore, stateStore)
+  return new PersistentConfigStore(settingsStore, stateStore)
 }
 
-export const mergeConfig = (
-  baseConfig: Record<string, unknown>,
-  overrideConfig: Record<string, unknown>,
-): Record<string, unknown> => {
-  const mergedConfig = { ...baseConfig }
-
-  for (const [key, value] of Object.entries(overrideConfig)) {
-    const baseValue = mergedConfig[key]
-    mergedConfig[key] =
-      isRecord(baseValue) && isRecord(value)
-        ? mergeConfig(baseValue, value)
-        : value
-  }
-
-  return mergedConfig
-}
-
-export const splitConfig = (
-  config: Record<string, unknown>,
-): {
-  settings: Record<string, unknown>
-  state: Record<string, unknown>
-} => {
-  const settings: Record<string, unknown> = {}
-  const state: Record<string, unknown> = {}
-
-  for (const [key, value] of Object.entries(config)) {
-    if (isStateKey(key)) {
-      state[key] = value
-      continue
-    }
-
-    if (isRecord(value)) {
-      const splitValue = splitConfig(value)
-      if (Object.keys(splitValue.settings).length > 0) {
-        settings[key] = splitValue.settings
-      }
-
-      if (Object.keys(splitValue.state).length > 0) {
-        state[key] = splitValue.state
-      }
-
-      continue
-    }
-
-    settings[key] = value
-  }
-
-  return { settings, state }
-}
-
-class SeamConfigStore {
+export class PersistentConfigStore implements ConfigStore {
   readonly path: string
 
   constructor(
@@ -145,14 +128,6 @@ const getStateConfigPath = (): string => {
   return join(paths.log, configFileName)
 }
 
-const isStateKey = (key: string): boolean => {
-  return (
-    key === currentWorkspaceIdKey ||
-    key === patKey ||
-    key.endsWith(`.${patKey}`)
-  )
-}
-
 const isRecord = (value: unknown): value is Record<string, unknown> => {
   return value != null && typeof value === 'object' && !Array.isArray(value)
 }

package/src/lib/config/index.ts

@@ -1 +1,8 @@
-export { getConfigStore } from './config-store.js'
+export {
+  type ConfigStore,
+  getConfigStore,
+  type PersistentConfigStore,
+  resetConfigStore,
+  setConfigStore,
+} from './config-store.js'
+export { createMemoryConfigStore } from './memory-config-store.js'

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

@@ -0,0 +1,62 @@
+import type { ConfigStore } from './config-store.js'
+
+/**
+ * A real {@link ConfigStore} held in memory, for tests.
+ *
+ * Keys are flat: the file-backed store nests dotted keys, but nothing reads
+ * a value back by a different spelling than it was written with.
+ */
+export class MemoryConfigStore implements ConfigStore {
+  readonly path = '/memory/cli.json'
+
+  private readonly values: Map<string, unknown>
+
+  constructor(initialValues: Record<string, unknown> = {}) {
+    this.values = new Map(Object.entries(initialValues))
+  }
+
+  get all(): Record<string, unknown> {
+    return Object.fromEntries(this.values)
+  }
+
+  set all(newValues: Record<string, unknown>) {
+    this.values.clear()
+    for (const [key, value] of Object.entries(newValues)) {
+      this.values.set(key, value)
+    }
+  }
+
+  get size(): number {
+    return this.values.size
+  }
+
+  get(key: string): unknown {
+    return this.values.get(key)
+  }
+
+  set(key: string | Record<string, unknown>, value?: unknown): void {
+    if (typeof key === 'string') {
+      this.values.set(key, value)
+      return
+    }
+    for (const [configKey, configValue] of Object.entries(key)) {
+      this.values.set(configKey, configValue)
+    }
+  }
+
+  has(key: string): boolean {
+    return this.values.has(key)
+  }
+
+  delete(key: string): void {
+    this.values.delete(key)
+  }
+
+  clear(): void {
+    this.values.clear()
+  }
+}
+
+export const createMemoryConfigStore = (
+  initialValues: Record<string, unknown> = {},
+): ConfigStore => new MemoryConfigStore(initialValues)

package/src/lib/config/migrate.ts

@@ -2,7 +2,7 @@ import { existsSync, rmSync } from 'node:fs'
 
 import type Configstore from 'configstore'
 
-import { mergeConfig, splitConfig } from './config-store.js'
+import { mergeConfig, splitConfig } from './values.js'
 
 export const migrateConfigStore = (
   settingsStore: Configstore,

package/src/lib/config/values.ts

@@ -0,0 +1,72 @@
+/**
+ * Config values as whole trees: merging two trees into one view, and
+ * splitting one tree into the settings file and the state file by key.
+ * Pure transforms shared by the persistent store and the legacy migration.
+ */
+
+const currentWorkspaceIdKey = 'current_workspace_id'
+const patKey = 'pat'
+
+/** Whether a key holds auth state rather than a setting. */
+export const isStateKey = (key: string): boolean => {
+  return (
+    key === currentWorkspaceIdKey ||
+    key === patKey ||
+    key.endsWith(`.${patKey}`)
+  )
+}
+
+export const mergeConfig = (
+  baseConfig: Record<string, unknown>,
+  overrideConfig: Record<string, unknown>,
+): Record<string, unknown> => {
+  const mergedConfig = { ...baseConfig }
+
+  for (const [key, value] of Object.entries(overrideConfig)) {
+    const baseValue = mergedConfig[key]
+    mergedConfig[key] =
+      isRecord(baseValue) && isRecord(value)
+        ? mergeConfig(baseValue, value)
+        : value
+  }
+
+  return mergedConfig
+}
+
+export const splitConfig = (
+  config: Record<string, unknown>,
+): {
+  settings: Record<string, unknown>
+  state: Record<string, unknown>
+} => {
+  const settings: Record<string, unknown> = {}
+  const state: Record<string, unknown> = {}
+
+  for (const [key, value] of Object.entries(config)) {
+    if (isStateKey(key)) {
+      state[key] = value
+      continue
+    }
+
+    if (isRecord(value)) {
+      const splitValue = splitConfig(value)
+      if (Object.keys(splitValue.settings).length > 0) {
+        settings[key] = splitValue.settings
+      }
+
+      if (Object.keys(splitValue.state).length > 0) {
+        state[key] = splitValue.state
+      }
+
+      continue
+    }
+
+    settings[key] = value
+  }
+
+  return { settings, state }
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => {
+  return value != null && typeof value === 'object' && !Array.isArray(value)
+}