@seamapi/cli 0.18.1 → 0.19.0

package/src/lib/args/coerce.ts

@@ -0,0 +1,164 @@
+import type { Parameter } from '@seamapi/blueprint'
+
+/** An argument whose value does not fit the parameter's documented format. */
+export interface CoercionIssue {
+  name: string
+  given: unknown
+  /** What the parameter takes, e.g., `a number`. */
+  expected: string
+}
+
+type Coerced = { value: unknown } | { issue: string }
+
+/**
+ * Read each argument as the JSON value its parameter documents: booleans and
+ * numbers become real booleans and numbers, lists split on commas, objects
+ * parse as JSON. The request body is then the same whether a value arrived
+ * as an argument, over stdin, or interactively.
+ *
+ * An argument naming no parameter passes through unchanged: unknown
+ * arguments are reported by `assertKnownArgs`, not silently dropped here.
+ */
+export const coerceArgParams = (
+  parameters: Parameter[],
+  argParams: Record<string, unknown>,
+): { params: Record<string, unknown>; issues: CoercionIssue[] } => {
+  const byName = new Map(
+    parameters.map((parameter) => [parameter.name, parameter]),
+  )
+
+  const params: Record<string, unknown> = {}
+  const issues: CoercionIssue[] = []
+
+  for (const [name, given] of Object.entries(argParams)) {
+    const parameter = byName.get(name)
+    if (parameter == null) {
+      params[name] = given
+      continue
+    }
+
+    const coerced = coerceParam(parameter, given)
+    if ('issue' in coerced) {
+      issues.push({ name, given, expected: coerced.issue })
+      continue
+    }
+    params[name] = coerced.value
+  }
+
+  return { params, issues }
+}
+
+export const coerceParam = (parameter: Parameter, given: unknown): Coerced => {
+  // `null` is an explicit JSON value for nullable parameters, not the string
+  // "null" (or a one-item list containing it).
+  if (parameter.isNullable && (given === null || given === 'null')) {
+    return { value: null }
+  }
+
+  if (parameter.format === 'list') return coerceList(parameter, given)
+
+  // A repeated argument parses as an array, which only a list accepts.
+  if (Array.isArray(given)) return { issue: 'a single value' }
+
+  switch (parameter.format) {
+    case 'boolean':
+      return coerceBoolean(given)
+    case 'number':
+      return coerceNumber(given)
+    case 'enum':
+      return coerceEnum(parameter, given)
+    case 'object':
+      return coerceObject(given)
+    default:
+      return { value: String(given) }
+  }
+}
+
+const coerceBoolean = (given: unknown): Coerced => {
+  if (given === true || given === 'true' || given === '1' || given === 1) {
+    return { value: true }
+  }
+  if (given === false || given === 'false' || given === '0' || given === 0) {
+    return { value: false }
+  }
+  return { issue: 'true or false' }
+}
+
+const coerceNumber = (given: unknown): Coerced => {
+  if (typeof given === 'number') return { value: given }
+  if (typeof given === 'string' && given.trim() !== '') {
+    const value = Number(given)
+    if (!Number.isNaN(value)) return { value }
+  }
+  return { issue: 'a number' }
+}
+
+const coerceEnum = (
+  parameter: Parameter & { format: 'enum' },
+  given: unknown,
+): Coerced => {
+  const value = String(given)
+  const names = parameter.values.map(({ name }) => name)
+  if (!names.includes(value)) return { issue: `one of ${names.join(', ')}` }
+  return { value }
+}
+
+const coerceObject = (given: unknown): Coerced => {
+  if (typeof given !== 'string') return { issue: 'a JSON object' }
+  try {
+    const value: unknown = JSON.parse(given)
+    if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+      return { issue: 'a JSON object' }
+    }
+    return { value }
+  } catch {
+    return { issue: 'a JSON object' }
+  }
+}
+
+const coerceList = (
+  parameter: Parameter & { format: 'list' },
+  given: unknown,
+): Coerced => {
+  const items = Array.isArray(given)
+    ? given
+    : typeof given === 'string'
+      ? given.split(',')
+      : [given]
+
+  const values: unknown[] = []
+  for (const item of items) {
+    const coerced = coerceListItem(parameter, item)
+    if ('issue' in coerced) return coerced
+    values.push(coerced.value)
+  }
+  return { value: values }
+}
+
+const coerceListItem = (
+  parameter: Parameter & { format: 'list' },
+  item: unknown,
+): Coerced => {
+  if (parameter.itemFormat === 'number') {
+    const coerced = coerceNumber(item)
+    if ('issue' in coerced) return { issue: 'a list of numbers' }
+    return coerced
+  }
+
+  if (parameter.itemFormat === 'boolean') {
+    const coerced = coerceBoolean(item)
+    if ('issue' in coerced) return { issue: 'a list of true or false' }
+    return coerced
+  }
+
+  if (parameter.itemFormat === 'enum') {
+    const value = String(item)
+    const names = parameter.itemEnumValues.map(({ name }) => name)
+    if (!names.includes(value)) {
+      return { issue: `a list of ${names.join(', ')}` }
+    }
+    return { value }
+  }
+
+  return { value: String(item) }
+}

package/src/lib/{util/cli-args.ts → args/parse.ts}

@@ -37,40 +37,45 @@ export const cliFlags: string[] = [
   'version',
 ]
 
-/**
- * Thrown when the CLI needs input it cannot prompt for.
- */
-export class NonInteractiveError extends Error {
-  override name = 'NonInteractiveError'
-}
-
-/**
- * Thrown when the arguments do not name something the CLI can run.
- */
-export class UsageError extends Error {
-  override name = 'UsageError'
-
-  /** What to run instead, reported after the message. */
-  readonly hint: string
-
-  constructor(message: string, { hint = '' }: { hint?: string } = {}) {
-    super(message)
-    this.hint = hint
-  }
+export interface ParseCliArgsOptions {
+  /**
+   * Argument keys read exactly as given rather than by guessing at a type,
+   * e.g., every parameter of an endpoint that does not take a number or a
+   * boolean. Read as a number, an opaque value like an access code would
+   * lose leading zeroes or turn exponent notation into a digit string.
+   */
+  stringKeys?: string[]
 }
 
-export const parseCliArgs = (argv: string[]): ParsedArgs =>
+export const parseCliArgs = (
+  argv: string[],
+  { stringKeys = [] }: ParseCliArgsOptions = {},
+): ParsedArgs =>
   parseArgs(argv, {
-    // A page cursor is opaque, so keep it exactly as given: read as a number
-    // it would lose leading zeroes and turn exponent notation into a digit
-    // string, naming a page the API never issued.
-    string: ['code', 'page-cursor', 'page_cursor'],
+    // A page cursor and a code are opaque even before the endpoint's own
+    // parameter types are known, so always keep them exactly as given.
+    string: ['code', 'page-cursor', 'page_cursor', ...stringKeys],
     boolean: ['non-interactive', 'interactive', 'json'],
     // Deliberately not aliased to -n, which is reserved for a future
     // --dry-run flag.
     alias: { 'non-interactive': 'y', interactive: 'i' },
   })
 
+/**
+ * The request params among the parsed arguments: every key normalized to
+ * the parameter it names, minus the flags that configure the CLI itself.
+ */
+export const toArgParams = (args: ParsedArgs): Record<string, unknown> => {
+  const argParams: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(args)) {
+    if (key === '_') continue
+    const name = toParameterName(key)
+    if (cliFlags.includes(name)) continue
+    argParams[name] = value
+  }
+  return argParams
+}
+
 export interface GetInteractivityOptions {
   /**
    * Whether there is a terminal to prompt on.

package/src/lib/args/validate.ts

@@ -0,0 +1,73 @@
+import type { Parameter } from '@seamapi/blueprint'
+
+import { NonInteractiveError, UsageError } from 'lib/errors.js'
+
+import { toArgName, toGivenArgName } from './parse.js'
+
+/**
+ * Report every required parameter still missing from the params, rather
+ * than prompting for it.
+ *
+ * @param target What the params are for, e.g., `/devices/list`.
+ */
+export const assertRequiredParams = (
+  parameters: Parameter[],
+  params: Record<string, unknown>,
+  target: string,
+): void => {
+  // A required parameter is satisfied by being present, not by being
+  // truthy: `false`, `0` and `''` are values a caller can supply.
+  const missing = parameters
+    .filter((parameter) => parameter.isRequired)
+    .map((parameter) => parameter.name)
+    .filter((name) => params[name] === undefined)
+
+  if (missing.length === 0) return
+
+  throw new NonInteractiveError(
+    `Missing required ${
+      missing.length === 1 ? 'parameter' : 'parameters'
+    } for ${target}: ${missing.map(toArgName).join(' ')}`,
+  )
+}
+
+/**
+ * Report any argument the command does not accept, rather than acting on it.
+ * An unrecognized argument is a mistake: forwarded to the API it would fail
+ * somewhere less obvious or be quietly ignored, and on a command the CLI
+ * handles itself it would go nowhere at all.
+ *
+ * Only arguments are checked. Params read from stdin are passed through as
+ * given, so a caller may send whatever the API itself accepts.
+ */
+export const assertKnownArgs = (
+  argParams: Record<string, unknown>,
+  command: string[],
+  {
+    accepted,
+    isLocal,
+  }: {
+    /** Parameter names the command accepts. */
+    accepted: Set<string>
+    /** Whether the CLI handles the command itself. */
+    isLocal: boolean
+  },
+): void => {
+  const unknown = Object.keys(argParams).filter((key) => !accepted.has(key))
+  if (unknown.length === 0) return
+
+  // Name an endpoint command by its path, as missing params are named, and a
+  // command the CLI handles itself by the words that run it.
+  const target = isLocal
+    ? command.join(' ')
+    : `/${command.join('/').replace(/-/g, '_')}`
+
+  throw new UsageError(
+    `Unknown ${
+      unknown.length === 1 ? 'parameter' : 'parameters'
+    } for ${target}: ${unknown.map(toGivenArgName).join(' ')}`,
+    {
+      hint: `Run 'seam ${command.join(' ')} --help' to see what it accepts.`,
+    },
+  )
+}

package/src/lib/auth/operations.ts

@@ -0,0 +1,169 @@
+import { randomBytes } from 'node:crypto'
+
+import { type ConfigStore, getConfigStore } from 'lib/config/index.js'
+import { type AuthContext, resolveAuth } from 'lib/context.js'
+import {
+  assertEnvVarUnset,
+  endpointEnvVar,
+  tokenEnvVar,
+  workspaceIdEnvVar,
+} from 'lib/env.js'
+
+import { validateToken } from './validate-token.js'
+
+/** A stored auth setting an environment variable may override. */
+export type AuthSetting = 'server' | 'token' | 'workspaceId'
+
+/**
+ * Refuse to store a setting the environment overrides.
+ *
+ * The env-override policy lives here alone: every auth mutation asserts
+ * through this before writing, so a command that appears to succeed cannot
+ * leave the CLI using something else.
+ *
+ * @param action What the command does, e.g., `log in`.
+ */
+export const assertMutable = (
+  auth: AuthContext,
+  setting: AuthSetting,
+  action: string,
+): void => {
+  const { envVar, source, value } = {
+    server: {
+      envVar: endpointEnvVar,
+      source: auth.serverSource,
+      value: auth.server,
+    },
+    token: { envVar: tokenEnvVar, source: auth.tokenSource, value: auth.token },
+    workspaceId: {
+      envVar: workspaceIdEnvVar,
+      source: auth.workspaceIdSource,
+      value: auth.workspaceId,
+    },
+  }[setting]
+
+  if (source !== 'env') return
+  assertEnvVarUnset(envVar, value, action)
+}
+
+export interface LoginOptions {
+  server?: string | undefined
+  token?: string | undefined
+  workspaceId?: string | undefined
+}
+
+/**
+ * Store the given credentials, validating the token first.
+ *
+ * The token is stored under the server it will be used with, so a given
+ * server is stored and re-resolved before the token key is derived.
+ *
+ * Validation reaches the network, so a test may inject its own `validate`.
+ */
+export const login = async (
+  { server, token, workspaceId }: LoginOptions,
+  config: ConfigStore = getConfigStore(),
+  validate: typeof validateToken = validateToken,
+): Promise<void> => {
+  let auth = resolveAuth(config)
+
+  // Nothing is stored while the environment overrides it, so refuse before
+  // storing anything rather than part way through.
+  assertMutable(auth, 'token', 'log in')
+  if (server != null) assertMutable(auth, 'server', 'select a server')
+  if (workspaceId != null) {
+    assertMutable(auth, 'workspaceId', 'select a workspace')
+  }
+
+  if (server != null) {
+    config.set('server', server)
+    config.delete('current_workspace_id')
+    auth = resolveAuth(config)
+  }
+
+  if (token != null) {
+    await validate(token, workspaceId)
+    config.set(`${auth.server}.pat`, token)
+    config.delete('current_workspace_id')
+  }
+
+  if (workspaceId != null) {
+    config.set('current_workspace_id', workspaceId)
+  }
+}
+
+/** Store the token for the current server, e.g., one just prompted for. */
+export const storeToken = (
+  token: string,
+  config: ConfigStore = getConfigStore(),
+): void => {
+  const auth = resolveAuth(config)
+  assertMutable(auth, 'token', 'log in')
+  config.set(`${auth.server}.pat`, token)
+}
+
+/** Remove the stored token and workspace selection. */
+export const logout = (config: ConfigStore = getConfigStore()): void => {
+  const auth = resolveAuth(config)
+  assertMutable(auth, 'token', 'log out')
+  config.delete(`${auth.server}.pat`)
+  // Configs written before tokens were stored per server may still hold an
+  // un-namespaced token, so drop that too.
+  config.delete('pat')
+  config.delete('current_workspace_id')
+}
+
+/**
+ * Store the server to make requests against.
+ *
+ * The workspace selection belongs to the previous server, so it is cleared.
+ */
+export const selectServer = (
+  server: string,
+  config: ConfigStore = getConfigStore(),
+): void => {
+  assertMutable(resolveAuth(config), 'server', 'select a server')
+  config.set('server', server)
+  config.delete('current_workspace_id')
+}
+
+/** Store the workspace requests are made against. */
+export const selectWorkspace = (
+  workspaceId: string,
+  config: ConfigStore = getConfigStore(),
+): void => {
+  assertMutable(resolveAuth(config), 'workspaceId', 'select a workspace')
+  config.set('current_workspace_id', workspaceId)
+}
+
+/**
+ * Point the CLI at a fake Seam Connect server and store the well-known
+ * token it accepts. Returns the generated server URL for reporting.
+ */
+export const selectFakeServer = ({
+  urlSeed = randomBytes(5).toString('hex'),
+  config = getConfigStore(),
+}: {
+  urlSeed?: string
+  config?: ConfigStore
+} = {}): { server: string; token: string } => {
+  const auth = resolveAuth(config)
+  assertMutable(auth, 'server', 'select a server')
+  assertMutable(auth, 'token', 'log in')
+
+  const server = `https://${urlSeed}.fakeseamconnect.seam.vc`
+  const token = 'seam_apikey1_token'
+  config.set('server', server)
+  config.set(`${server}.pat`, token)
+  config.delete('current_workspace_id')
+
+  return { server, token }
+}
+
+/** Store whether API definitions come from the server instead of npm. */
+export const setUseRemoteApiDefs = (
+  useRemoteApiDefs: boolean,
+  config: ConfigStore = getConfigStore(),
+): void => {
+  config.set('use_remote_api_defs', useRemoteApiDefs)
+}

package/src/lib/{validate-token.ts → auth/validate-token.ts}

@@ -5,10 +5,10 @@ import {
   SeamHttpWithoutWorkspace,
 } from '@seamapi/http/connect'
 
-import { getServer } from './get-server.js'
+import { resolveAuth } from 'lib/context.js'
 
 export const validateToken = async (token: string, workspaceId?: string) => {
-  const options = { endpoint: getServer() }
+  const options = { endpoint: resolveAuth().server }
 
   if (isPersonalAccessToken(token)) {
     const seam = workspaceId

package/src/lib/blueprint/cache.ts

@@ -0,0 +1,97 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import type { Blueprint } from '@seamapi/blueprint'
+
+import { seamapiBlueprintVersion } from 'lib/version.js'
+
+const cacheFileName = 'blueprint.json'
+const updateCheckInterval = 24 * 60 * 60 * 1000
+
+export interface BlueprintCache {
+  blueprintVersion: string
+  typesVersion: string
+  checkedAt: string
+  blueprint: Blueprint
+}
+
+export const getCacheFile = (cacheDirectory: string): string =>
+  join(cacheDirectory, cacheFileName)
+
+export const readCache = async (
+  file: string,
+): Promise<BlueprintCache | null> => {
+  try {
+    const contents = await readFile(file, 'utf8')
+    const cache = JSON.parse(contents) as unknown
+    if (!isBlueprintCache(cache)) return null
+    return cache
+  } catch {
+    return null
+  }
+}
+
+export const writeCache = async (
+  file: string,
+  cache: BlueprintCache,
+): Promise<void> => {
+  const temporaryFile = `${file}.tmp`
+  await mkdir(dirname(file), { recursive: true })
+  await writeFile(temporaryFile, `${JSON.stringify(cache)}\n`, 'utf8')
+  await rename(temporaryFile, file)
+}
+
+export const isUpdateCheckDue = (checkedAt: string): boolean => {
+  const checkedAtTime = Date.parse(checkedAt)
+  if (Number.isNaN(checkedAtTime)) return true
+  return Date.now() - checkedAtTime > updateCheckInterval
+}
+
+/**
+ * The blueprint version the cache is keyed on: a cached blueprint built by a
+ * different @seamapi/blueprint version is stale even for the same types.
+ */
+export const getBlueprintVersion = async (): Promise<string> => {
+  if (seamapiBlueprintVersion !== '0.0.0') return seamapiBlueprintVersion
+
+  // The version is only injected when the package is packed, so a
+  // development checkout reads the pinned version from package.json
+  // to keep invalidating the cache on version changes as expected.
+  const pkg = await findOwnPackageJson()
+  return pkg?.dependencies?.['@seamapi/blueprint'] ?? seamapiBlueprintVersion
+}
+
+const findOwnPackageJson = async (): Promise<{
+  dependencies?: Record<string, string>
+} | null> => {
+  let directory = dirname(fileURLToPath(import.meta.url))
+  while (true) {
+    try {
+      const contents = await readFile(join(directory, 'package.json'), 'utf8')
+      const pkg = JSON.parse(contents) as {
+        name?: string
+        dependencies?: Record<string, string>
+      }
+      if (pkg.name === '@seamapi/cli') return pkg
+    } catch {
+      // Keep walking up until a package.json for this package is found.
+    }
+    const parent = dirname(directory)
+    if (parent === directory) return null
+    directory = parent
+  }
+}
+
+const isBlueprintCache = (cache: unknown): cache is BlueprintCache => {
+  if (cache == null || typeof cache !== 'object') return false
+  const { blueprintVersion, typesVersion, checkedAt, blueprint } =
+    cache as Record<string, unknown>
+  return (
+    typeof blueprintVersion === 'string' &&
+    typeof typesVersion === 'string' &&
+    typeof checkedAt === 'string' &&
+    blueprint != null &&
+    typeof blueprint === 'object'
+  )
+}

package/src/lib/{get-response-key.ts → blueprint/endpoint.ts}

@@ -1,5 +1,19 @@
-import { getCommandBlueprintDef } from './get-command-blueprint-def.js'
-import type { ContextHelpers } from './types.js'
+import type { ApiBlueprint } from './index.js'
+
+export const getCommandBlueprintDef = (
+  cmd: string[],
+  helpers: { blueprint: ApiBlueprint },
+) => {
+  const path = `/${cmd.join('/').replace(/-/g, '_')}`
+  const def = helpers.blueprint.routes
+    .flatMap((route) => route.endpoints)
+    .find((endpoint) => endpoint.path === path)
+  if (!def) {
+    throw new Error(`No definition for path ${path}`)
+  }
+
+  return def
+}
 
 /**
  * The top level response key documented for a command,
@@ -10,7 +24,7 @@ import type { ContextHelpers } from './types.js'
  */
 export const getResponseKey = (
   command: string[],
-  ctx: ContextHelpers,
+  ctx: { blueprint: ApiBlueprint },
 ): string | null => {
   let endpoint
   try {

package/src/lib/blueprint/index.ts

@@ -0,0 +1,27 @@
+import type { Blueprint } from '@seamapi/blueprint'
+
+import { getBlueprint } from './source-npm.js'
+import { createRemoteBlueprint } from './source-remote.js'
+
+export type ApiBlueprint = Blueprint
+
+export interface GetApiBlueprintOptions {
+  /**
+   * Build from the OpenAPI document the configured server is currently
+   * running, instead of the published npm types.
+   */
+  useRemoteDefinitions?: boolean
+  /** Force an update of the cached Seam API definitions. */
+  update?: boolean
+}
+
+export const getApiBlueprint = async ({
+  useRemoteDefinitions = false,
+  update = false,
+}: GetApiBlueprintOptions = {}): Promise<ApiBlueprint> => {
+  // Remote definitions describe whatever the server is currently running, so
+  // build them directly from the server's OpenAPI document.
+  if (useRemoteDefinitions) return await createRemoteBlueprint()
+
+  return await getBlueprint({ update })
+}