@seamapi/cli 0.18.1 → 0.19.0

package/src/lib/{blueprint.ts → blueprint/source-npm.ts}

@@ -1,52 +1,46 @@
-import {
-  access,
-  mkdir,
-  readFile,
-  rename,
-  rm,
-  writeFile,
-} from 'node:fs/promises'
-import { dirname, join } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
+import { access, mkdir, rm, writeFile } from 'node:fs/promises'
+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 { withLoading } from './util/with-loading.js'
-import { seamapiBlueprintVersion } from './version.js'
+import { withLoading } from 'lib/output/with-loading.js'
+
+import {
+  getBlueprintVersion,
+  getCacheFile,
+  isUpdateCheckDue,
+  readCache,
+  writeCache,
+} from './cache.js'
 
 const typesPackageName = '@seamapi/types'
 const openapiTarEntryName = 'package/lib/seam/connect/openapi.js'
 const registryUrl = 'https://registry.npmjs.org'
-const updateCheckInterval = 24 * 60 * 60 * 1000
-
-const cacheFileName = 'blueprint.json'
-
-interface BlueprintCache {
-  blueprintVersion: string
-  typesVersion: string
-  checkedAt: string
-  blueprint: Blueprint
-}
 
 interface TypesPackageManifest {
   version: string
   dist: { tarball: string }
 }
 
-interface GetBlueprintOptions {
+export interface GetBlueprintOptions {
   update?: boolean
   cacheDirectory?: string
 }
 
-const getBlueprint = async (
+/**
+ * Build a blueprint from the latest published Seam API types on npm,
+ * using the on-disk cache unless it is stale or an update is forced.
+ */
+export const getBlueprint = async (
   options: GetBlueprintOptions = {},
 ): Promise<Blueprint> => {
   const update = options.update ?? false
   const cacheDirectory =
     options.cacheDirectory ?? envPaths('seam', { suffix: '' }).cache
-  const cacheFile = join(cacheDirectory, cacheFileName)
+  const cacheFile = getCacheFile(cacheDirectory)
   const blueprintVersion = await getBlueprintVersion()
 
   const cache = await readCache(cacheFile)
@@ -100,41 +94,6 @@ const getBlueprint = async (
   return blueprint
 }
 
-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 pkg = JSON.parse(
-        await readFile(join(directory, 'package.json'), 'utf8'),
-      ) 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 isUpdateCheckDue = (checkedAt: string): boolean => {
-  const checkedAtTime = Date.parse(checkedAt)
-  if (Number.isNaN(checkedAtTime)) return true
-  return Date.now() - checkedAtTime > updateCheckInterval
-}
-
 const fetchLatestTypesPackageManifest =
   async (): Promise<TypesPackageManifest> => {
     const res = await fetch(`${registryUrl}/${typesPackageName}/latest`, {
@@ -144,7 +103,8 @@ const fetchLatestTypesPackageManifest =
     if (!res.ok) {
       throw new Error(`npm registry responded with status ${res.status}`)
     }
-    const manifest = (await res.json()) as Partial<TypesPackageManifest>
+    const body = await res.json()
+    const manifest = body as Partial<TypesPackageManifest>
     if (
       typeof manifest.version !== 'string' ||
       typeof manifest.dist?.tarball !== 'string'
@@ -181,21 +141,24 @@ const downloadOpenapi = async (
   await rm(extractDirectory, { recursive: true, force: true })
   await mkdir(extractDirectory, { recursive: true })
   try {
-    await writeFile(tarballFile, Buffer.from(await res.arrayBuffer()))
+    const tarball = await res.arrayBuffer()
+    await writeFile(tarballFile, Buffer.from(tarball))
     await extract({ file: tarballFile, cwd: extractDirectory }, [
       openapiTarEntryName,
     ])
 
     const moduleFile = join(extractDirectory, openapiTarEntryName)
-    if (!(await exists(moduleFile))) {
+    const moduleFileExists = await exists(moduleFile)
+    if (!moduleFileExists) {
       throw new Error(`Missing ${openapiTarEntryName} in package tarball`)
     }
 
     // The OpenAPI document is published as a JavaScript module, so import it.
     const openapiModuleUrl = pathToFileURL(moduleFile).href
-    const { default: openapi } = (await import(openapiModuleUrl)) as {
+    const openapiModule = (await import(openapiModuleUrl)) as {
       default: unknown
     }
+    const { default: openapi } = openapiModule
     if (openapi == null) {
       throw new Error(`Missing default export in ${openapiTarEntryName}`)
     }
@@ -214,40 +177,5 @@ const exists = async (file: string): Promise<boolean> => {
   }
 }
 
-const readCache = async (file: string): Promise<BlueprintCache | null> => {
-  try {
-    const cache = JSON.parse(await readFile(file, 'utf8')) as unknown
-    if (!isBlueprintCache(cache)) return null
-    return cache
-  } catch {
-    return null
-  }
-}
-
-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)
-}
-
-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'
-  )
-}
-
 const toErrorMessage = (error: unknown): string =>
   error instanceof Error ? error.message : String(error)
-
-export default getBlueprint

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

@@ -0,0 +1,17 @@
+import type { Blueprint } from '@seamapi/blueprint'
+
+import { resolveAuth } from 'lib/context.js'
+
+/**
+ * Build a blueprint from the OpenAPI document the current server is running,
+ * describing exactly what that server accepts rather than what is published.
+ */
+export const createRemoteBlueprint = async (): Promise<Blueprint> => {
+  const [{ createBlueprint }, { getOpenapiSchema }] = await Promise.all([
+    import('@seamapi/blueprint'),
+    import('@seamapi/http/connect'),
+  ])
+  const openapi = await getOpenapiSchema(resolveAuth().server)
+
+  return await createBlueprint({ openapi }, { omitUndocumented: true })
+}

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

@@ -0,0 +1,109 @@
+import { isDeepStrictEqual as isEqual } from 'node:util'
+
+import { coerceArgParams } from 'lib/args/coerce.js'
+import { parseCliArgs, toArgName, toArgParams } from 'lib/args/parse.js'
+import { assertRequiredParams } from 'lib/args/validate.js'
+import {
+  getCommandBlueprintDef,
+  getResponseKey,
+} from 'lib/blueprint/endpoint.js'
+import type { CliContext } from 'lib/context.js'
+import { UsageError } from 'lib/errors.js'
+import { runResponseFollowUps } from 'lib/http/follow-ups.js'
+import { requestSeamApi } from 'lib/http/request.js'
+import { interactForCommandParams } from 'lib/interactions/index.js'
+
+import type { CommandResult, Invocation } from './registry.js'
+
+/**
+ * Run a command that calls a Seam API endpoint: assemble the params,
+ * prompt for what is missing, make the request, and run any follow-ups
+ * the response calls for.
+ */
+export const executeApiCommand = async (
+  invocation: Invocation,
+  ctx: CliContext,
+): Promise<CommandResult> => {
+  const { path } = invocation
+  const isNonInteractive = ctx.interactivity === 'non-interactive'
+  const apiPath = `/${path.join('/').replace(/-/g, '_')}`
+
+  const parameters = getCommandBlueprintDef(path, ctx).request.parameters
+
+  // Re-read the arguments knowing the endpoint's own parameter types — the
+  // generic first parse guessed, mangling opaque values like access codes —
+  // then coerce each value to the JSON type its parameter documents.
+  const stringKeys = parameters
+    .filter(({ format }) => format !== 'boolean' && format !== 'number')
+    .flatMap(({ name }) => [name, name.replace(/_/g, '-')])
+  const { params: argParams, issues } = coerceArgParams(
+    parameters,
+    toArgParams(parseCliArgs(invocation.argv, { stringKeys })),
+  )
+
+  if (issues.length > 0) {
+    throw new UsageError(
+      `Invalid ${
+        issues.length === 1 ? 'value' : 'values'
+      } for ${apiPath}: ${issues
+        .map(({ name, expected }) => `${toArgName(name)} expects ${expected}`)
+        .join('; ')}`,
+      {
+        hint: `Run 'seam ${path.join(' ')} --help' to see what it accepts.`,
+      },
+    )
+  }
+
+  // Params given as arguments win over params piped in.
+  const commandParams: Record<string, any> = { ...invocation.stdinParams }
+  Object.assign(commandParams, argParams)
+
+  applyEndpointDefaults(path, commandParams)
+
+  // Non-interactive runs never prompt: validate and send what was given.
+  let params: Record<string, any>
+  if (isNonInteractive) {
+    assertRequiredParams(parameters, commandParams, apiPath)
+    params = commandParams
+  } else {
+    const edited = await interactForCommandParams(
+      { command: path, params: commandParams },
+      ctx,
+    )
+
+    if (edited === '[Back]') {
+      return { kind: 'back', toPath: path.slice(0, -1) }
+    }
+    params = edited
+  }
+
+  if (apiPath.includes('/events/list') && params['between']) {
+    delete params['since']
+  }
+
+  const api = await ctx.api()
+  const body = await requestSeamApi(
+    { path: apiPath, params, responseKey: getResponseKey(path, ctx) },
+    { api, output: ctx.output },
+  )
+
+  await runResponseFollowUps(body, ctx)
+
+  return { kind: 'done' }
+}
+
+/**
+ * Per-endpoint request policy that is not derivable from the API
+ * definitions. Keep this table small and explicit.
+ */
+const applyEndpointDefaults = (
+  path: string[],
+  params: Record<string, any>,
+): void => {
+  // Unbounded event lists are never wanted, so default to the last month.
+  if (isEqual(path, ['events', 'list']) && !params['since']) {
+    const date = new Date()
+    date.setMonth(date.getMonth() - 1)
+    params['since'] = date.toISOString()
+  }
+}

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

@@ -0,0 +1,51 @@
+import type { ApiBlueprint } from 'lib/blueprint/index.js'
+import type { Command } from 'lib/commands/registry.js'
+import type { CommandSpec } from 'lib/commands/spec.js'
+import { getOutput } from 'lib/output/get-output.js'
+import {
+  type CompletionShell,
+  renderCompletion,
+} from 'lib/render/completion/index.js'
+
+/**
+ * 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.
+ *
+ * Called by the entry before any auth or blueprint context exists, and by
+ * the registered command's executor — one implementation for both.
+ */
+export const printCompletion = (
+  shell: CompletionShell,
+  spec: CommandSpec,
+): void => {
+  getOutput().text(renderCompletion(shell, spec))
+}
+
+type BuildSpec = (blueprint: ApiBlueprint) => CommandSpec
+
+const completionCommand = (
+  shell: CompletionShell,
+  buildSpec: BuildSpec,
+): Command => ({
+  definition: {
+    path: ['completion', shell],
+    kind: 'cli',
+    title: `Print the ${shell} completion script.`,
+    description: '',
+    flags: [],
+  },
+  requiresAuth: false,
+  execute: async (_invocation, ctx) => {
+    printCompletion(shell, buildSpec(ctx.blueprint))
+    return { kind: 'done' }
+  },
+})
+
+export const createCompletionCommands = (buildSpec: BuildSpec): Command[] => [
+  completionCommand('bash', buildSpec),
+  completionCommand('fish', buildSpec),
+  completionCommand('zsh', buildSpec),
+]

package/src/lib/commands/local/config-reveal-location.ts

@@ -0,0 +1,16 @@
+import type { Command } from 'lib/commands/registry.js'
+
+export const configRevealLocationCommand: Command = {
+  definition: {
+    path: ['config', 'reveal-location'],
+    kind: 'cli',
+    title: 'Print the path to the CLI configuration file.',
+    description: '',
+    flags: [],
+  },
+  requiresAuth: true,
+  execute: async (_invocation, ctx) => {
+    ctx.output.text(ctx.config.path)
+    return { kind: 'done' }
+  },
+}

package/src/lib/commands/local/config-set-fake-server.ts

@@ -0,0 +1,21 @@
+import { selectFakeServer } from 'lib/auth/operations.js'
+import type { Command } from 'lib/commands/registry.js'
+
+/** Hidden: a development shortcut, kept out of help and completion. */
+export const configSetFakeServerCommand: Command = {
+  definition: {
+    path: ['config', 'set', 'fake-server'],
+    kind: 'cli',
+    title: 'Point the CLI at a fake Seam Connect server.',
+    description: '',
+    flags: [],
+  },
+  requiresAuth: false,
+  hidden: true,
+  execute: async (_invocation, ctx) => {
+    const { server } = selectFakeServer({ config: ctx.config })
+    ctx.output.info(`Server URL set to ${server}`)
+    ctx.output.info(`PAT set to use fakeseamconnect with "seam_apikey1_token"`)
+    return { kind: 'done' }
+  },
+}

package/src/lib/commands/local/config-use-remote-api-defs.ts

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

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

@@ -0,0 +1,22 @@
+import type { Command } from 'lib/commands/registry.js'
+import { requestSeamApi } from 'lib/http/request.js'
+
+export const healthCommand: Command = {
+  definition: {
+    path: ['health', 'get-health'],
+    // Handled by the CLI itself, but calls the Seam API.
+    kind: 'api',
+    title: 'Report the health of the Seam API.',
+    description: '',
+    flags: [],
+  },
+  requiresAuth: true,
+  execute: async (_invocation, ctx) => {
+    const api = await ctx.api()
+    await requestSeamApi(
+      { path: '/health/get_health', params: {} },
+      { api, output: ctx.output },
+    )
+    return { kind: 'done' }
+  },
+}

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

@@ -0,0 +1,42 @@
+import { assertMutable, login } 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 { interactForLogin } from 'lib/interactions/index.js'
+
+export const loginCommand: Command = {
+  definition: {
+    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.'),
+    ],
+  },
+  requiresAuth: false,
+  execute: async ({ args }, ctx) => {
+    if (args['token'] || args['workspace_id'] || args['server']) {
+      await login(
+        {
+          server: args['server'] ? args['server'] : undefined,
+          token: args['token'] ? String(args['token']).trim() : undefined,
+          workspaceId: args['workspace_id'] ? args['workspace_id'] : undefined,
+        },
+        ctx.config,
+      )
+      return { kind: 'done' }
+    }
+    assertMutable(ctx.auth, 'token', 'log in')
+    if (ctx.interactivity === 'non-interactive') {
+      throw new NonInteractiveError(
+        'Missing required parameter for login: --token',
+      )
+    }
+    await interactForLogin()
+    return { kind: 'done' }
+  },
+}

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

@@ -0,0 +1,18 @@
+import { logout } from 'lib/auth/operations.js'
+import type { Command } from 'lib/commands/registry.js'
+
+export const logoutCommand: Command = {
+  definition: {
+    path: ['logout'],
+    kind: 'cli',
+    title: 'Log out of Seam.',
+    description: '',
+    flags: [],
+  },
+  requiresAuth: true,
+  execute: async (_invocation, ctx) => {
+    logout(ctx.config)
+    ctx.output.info('Logged out!')
+    return { kind: 'done' }
+  },
+}

package/src/lib/commands/local/select-server.ts

@@ -0,0 +1,30 @@
+import { assertMutable, selectServer } 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 { interactForServerSelection } from 'lib/interactions/index.js'
+
+export const selectServerCommand: Command = {
+  definition: {
+    path: ['select', 'server'],
+    kind: 'cli',
+    title: 'Select the Seam API server.',
+    description: '',
+    flags: [stringFlag('server', 'Seam API server to select.')],
+  },
+  requiresAuth: false,
+  execute: async ({ args }, ctx) => {
+    assertMutable(ctx.auth, 'server', 'select a server')
+    if (args['server']) {
+      selectServer(args['server'], ctx.config)
+      return { kind: 'done' }
+    }
+    if (ctx.interactivity === 'non-interactive') {
+      throw new NonInteractiveError(
+        'Missing required parameter for select server: --server',
+      )
+    }
+    await interactForServerSelection()
+    return { kind: 'done' }
+  },
+}

package/src/lib/commands/local/select-workspace.ts

@@ -0,0 +1,25 @@
+import { assertMutable } 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'
+
+export const selectWorkspaceCommand: Command = {
+  definition: {
+    path: ['select', 'workspace'],
+    kind: 'cli',
+    title: 'Select the current workspace.',
+    description: '',
+    flags: [],
+  },
+  requiresAuth: true,
+  execute: async (_invocation, ctx) => {
+    assertMutable(ctx.auth, 'workspaceId', 'select a workspace')
+    if (ctx.interactivity === 'non-interactive') {
+      throw new NonInteractiveError(
+        'Cannot select a workspace in non-interactive mode: pass --workspace-id to "seam login"',
+      )
+    }
+    await interactForWorkspaceId()
+    return { kind: 'done' }
+  },
+}

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

@@ -0,0 +1,31 @@
+import type { Command } from 'lib/commands/registry.js'
+
+/**
+ * Run the Seam setup wizard.
+ *
+ * Intercepted by the entry before argument parsing so the wizard owns its
+ * own argv; the registered executor covers selecting it interactively.
+ */
+export const runWizard = async (argv: string[]): Promise<void> => {
+  const { default: wizard } = await import('@seamapi/wizard')
+  await wizard({
+    argv,
+    commandName: 'seam wizard',
+  })
+}
+
+export const wizardCommand: Command = {
+  definition: {
+    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: [],
+  },
+  requiresAuth: false,
+  execute: async () => {
+    await runWizard([])
+    return { kind: 'done' }
+  },
+}