@seamapi/cli 0.10.0 → 0.12.0

package/src/lib/output/create-output.ts

@@ -0,0 +1,104 @@
+import { inspect } from 'node:util'
+
+/**
+ * Minimal writable surface needed by {@link Output}.
+ *
+ * Both `process.stdout` and an in-memory buffer satisfy this,
+ * which is what makes output testable.
+ */
+export interface OutputStream {
+  write: (chunk: string) => unknown
+}
+
+/**
+ * `json` is machine readable: only {@link Output.data} produces output.
+ * `text` is human readable: data is pretty printed and may be colorized.
+ */
+export type OutputFormat = 'json' | 'text'
+
+export interface Output {
+  readonly format: OutputFormat
+
+  /**
+   * The result of a command, e.g., an API response.
+   *
+   * This is the only thing ever written to stdout,
+   * so it is safe to pipe into another program.
+   */
+  data: (value: unknown) => void
+
+  /**
+   * A plain text command result, e.g., the version or the help guide.
+   *
+   * Written to stdout verbatim in every format: these results are already
+   * a single value, so encoding them as JSON would only make them harder
+   * to consume from a pipe.
+   */
+  text: (value: string) => void
+
+  /**
+   * Human facing progress, context, and confirmations.
+   *
+   * Written to stderr and suppressed entirely in the json format.
+   */
+  info: (message?: string) => void
+
+  /** Human facing warning. Written to stderr in every format. */
+  warn: (message: string) => void
+
+  /** Human facing error. Written to stderr in every format. */
+  error: (message: string) => void
+}
+
+export interface CreateOutputOptions {
+  format?: OutputFormat
+  stdout?: OutputStream
+  stderr?: OutputStream
+  /** Colorize pretty printed data. Never applied to the json format. */
+  colors?: boolean
+}
+
+export const createOutput = ({
+  format = 'text',
+  stdout = process.stdout,
+  stderr = process.stderr,
+  colors = false,
+}: CreateOutputOptions = {}): Output => {
+  const isJson = format === 'json'
+
+  return {
+    format,
+
+    data: (value: unknown): void => {
+      if (value === undefined) return
+      stdout.write(`${formatData(value, format, colors)}\n`)
+    },
+
+    text: (value: string): void => {
+      stdout.write(`${value}\n`)
+    },
+
+    info: (message = ''): void => {
+      if (isJson) return
+      stderr.write(`${message}\n`)
+    },
+
+    warn: (message: string): void => {
+      stderr.write(`${message}\n`)
+    },
+
+    error: (message: string): void => {
+      stderr.write(`${message}\n`)
+    },
+  }
+}
+
+const formatData = (
+  value: unknown,
+  format: OutputFormat,
+  colors: boolean,
+): string => {
+  if (format === 'json') return JSON.stringify(value, null, 2)
+  if (typeof value === 'string') return value
+  return inspect(value, { depth: null, colors })
+}

package/src/lib/output/get-output.ts

@@ -0,0 +1,24 @@
+import { createOutput, type Output } from './create-output.js'
+
+let output: Output | null = null
+
+/**
+ * The output used by the CLI.
+ *
+ * Defaults to a `text` output bound to the real process streams,
+ * so importing modules never write to stdout by accident.
+ */
+export const getOutput = (): Output => {
+  output ??= createOutput()
+  return output
+}
+
+/** Replace the output, e.g., once flags are parsed, or from a test. */
+export const setOutput = (nextOutput: Output): void => {
+  output = nextOutput
+}
+
+/** Restore the default output. Intended for tests. */
+export const resetOutput = (): void => {
+  output = null
+}

package/src/lib/output/resolve-output-format.ts

@@ -0,0 +1,33 @@
+import type { OutputFormat } from './create-output.js'
+
+export interface ResolveOutputFormatOptions {
+  /** Whether stdout is a terminal. */
+  isTty?: boolean
+}
+
+/**
+ * Whether to write machine readable output.
+ *
+ * An explicit `--json` or `--no-json` wins, otherwise the CLI writes JSON
+ * whenever stdout is piped or redirected, and pretty output at a terminal.
+ *
+ * This reads the arguments rather than the parsed args because `--json` is
+ * declared as a boolean flag, so that it never consumes the argument after
+ * it, and a boolean cannot tell `--no-json` apart from not passing anything.
+ */
+export const resolveOutputFormat = (
+  argv: string[],
+  { isTty = false }: ResolveOutputFormatOptions = {},
+): OutputFormat => {
+  const flag = argv.filter((arg) => arg === '--json' || arg === '--no-json')
+
+  // The last one wins, matching how the argument parser resolves repeats.
+  switch (flag[flag.length - 1]) {
+    case '--json':
+      return 'json'
+    case '--no-json':
+      return 'text'
+    default:
+      return isTty ? 'text' : 'json'
+  }
+}

package/src/lib/output/select-response-payload.ts

@@ -0,0 +1,56 @@
+/**
+ * Top level response fields that are transport details,
+ * not part of the result the CLI reports.
+ */
+const metaKeys = new Set(['ok'])
+
+const paginationKey = 'pagination'
+const errorKey = 'error'
+
+export interface SelectResponsePayloadOptions {
+  /**
+   * The response key for the endpoint, e.g., `devices` for `/devices/list`,
+   * usually taken from the API blueprint.
+   *
+   * When omitted, every top level field except {@link metaKeys} is kept.
+   */
+  responseKey?: string | null | undefined
+}
+
+/**
+ * Reduce an API response body to the response key and pagination.
+ *
+ * The CLI never reports other top level fields: they are details of the
+ * transport, so including them would leak into anything parsing stdout.
+ */
+export const selectResponsePayload = (
+  data: unknown,
+  { responseKey }: SelectResponsePayloadOptions = {},
+): unknown => {
+  if (!isRecord(data)) return data
+
+  if (errorKey in data) {
+    return { [errorKey]: data[errorKey] }
+  }
+
+  const keys =
+    responseKey != null && responseKey in data
+      ? [responseKey]
+      : Object.keys(data).filter(
+          (key) => !metaKeys.has(key) && key !== paginationKey,
+        )
+
+  const payload: Record<string, unknown> = {}
+  for (const key of keys) {
+    payload[key] = data[key]
+  }
+
+  if (paginationKey in data) {
+    payload[paginationKey] = data[paginationKey]
+  }
+
+  return payload
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)

package/src/lib/render-help.ts

@@ -0,0 +1,197 @@
+import commandLineUsage, { type Section } from 'command-line-usage'
+
+import {
+  type CommandDefinition,
+  type CommandFlag,
+  type CommandGroup,
+  type CommandSpec,
+  findCommand,
+  findGroup,
+} from './command-spec.js'
+
+/**
+ * Render the help guide for a command path, or `null` when no command or
+ * group goes by that path.
+ *
+ * An empty path is the guide for `seam` itself.
+ */
+export const renderHelp = (
+  path: string[],
+  spec: CommandSpec,
+): string | null => {
+  const group = findGroup(spec, path)
+  if (group != null) return commandLineUsage(groupSections(group, spec))
+
+  const command = findCommand(spec, path)
+  if (command != null) return commandLineUsage(commandSections(command, spec))
+
+  return null
+}
+
+const overview =
+  'Every seam command runs as soon as every required property is given, and otherwise prompts you for what is missing with helpful suggestions. Pass -i to always review properties first, or -y to never be prompted.'
+
+const outputSection = {
+  header: 'Output',
+  content: [
+    'Only the response is written to stdout, so it is safe to pipe. Prompts, progress, and other information are written to stderr.',
+    'The response is trimmed to the response key and pagination.',
+    'Request params may be piped or redirected in as a JSON object. Params given as arguments win over params read from stdin.',
+  ],
+}
+
+const examples = [
+  { name: 'seam', summary: 'Interactively select commands to execute.' },
+  { name: 'seam login', summary: 'Login to Seam.' },
+  { name: 'seam wizard', summary: 'Set up Seam in the current project.' },
+  { name: 'seam select workspace', summary: 'Select your workspace.' },
+  {
+    name: 'seam connect-webviews create',
+    summary: 'Create a connect webview to connect devices.',
+  },
+  { name: 'seam devices list', summary: 'List devices in your workspace.' },
+  {
+    name: 'seam devices list {bold --interactive}',
+    summary: 'Review and edit filters before listing devices.',
+  },
+  {
+    name: 'seam devices list {bold --non-interactive}',
+    summary: 'List devices, failing instead of prompting.',
+  },
+  {
+    name: 'seam locks unlock-door {bold --device-id} $MY_DOOR',
+    summary: 'Unlock a lock.',
+  },
+  {
+    name: "seam access-codes create {bold --code} '1234' {bold --name} 'My Code'",
+    summary: 'Create an access code.',
+  },
+  {
+    name: 'seam devices list > devices.json',
+    summary: 'Write the response to a file as JSON.',
+  },
+  {
+    name: 'cat params.json | seam locks unlock-door',
+    summary: 'Pipe request params in as JSON.',
+  },
+  {
+    name: 'seam completion bash',
+    summary: 'Print a shell completion script for bash, fish, or zsh.',
+  },
+]
+
+const groupSections = (group: CommandGroup, spec: CommandSpec): Section[] => {
+  const isRoot = group.path.length === 0
+  const name = ['seam', ...group.path].join(' ')
+
+  return [
+    isRoot
+      ? { header: 'Seam CLI', content: overview }
+      : { header: name, content: `Commands under ${name}.` },
+    { header: 'Usage', content: `${name} <command> [options]` },
+    ...commandSectionsForGroup(group, isRoot),
+    optionSection(spec.globalFlags),
+    ...(isRoot
+      ? [outputSection, { header: 'Command List Examples', content: examples }]
+      : []),
+    { content: `Run '${name} <command> --help' to see a command in detail.` },
+  ]
+}
+
+const commandSectionsForGroup = (
+  group: CommandGroup,
+  isRoot: boolean,
+): Section[] => {
+  const content = (subcommands: CommandGroup['subcommands']) =>
+    subcommands.map(({ name, description }) => ({ name, summary: description }))
+
+  // The root guide separates the commands of the CLI itself from the commands
+  // that call the Seam API. Anywhere deeper the split adds nothing: a group
+  // holds commands of one kind.
+  if (!isRoot) {
+    return [{ header: 'Commands', content: content(group.subcommands) }]
+  }
+
+  const cli = group.subcommands.filter(({ kind }) => kind === 'cli')
+  const api = group.subcommands.filter(({ kind }) => kind === 'api')
+
+  return [
+    { header: 'Commands', content: content(cli) },
+    { header: 'API Commands', content: content(api) },
+  ].filter((section) => section.content.length > 0)
+}
+
+const commandSections = (
+  command: CommandDefinition,
+  spec: CommandSpec,
+): Section[] => {
+  const name = ['seam', ...command.path].join(' ')
+  const hasFlags = command.flags.length > 0
+
+  return [
+    {
+      header: name,
+      content: [command.title, command.description].filter(
+        (line) => line !== '',
+      ),
+    },
+    { header: 'Usage', content: `${name} [options]` },
+    // The command's own parameters are what the request is made of, so keep
+    // them apart from the options every seam command takes.
+    ...(hasFlags ? [optionSection(command.flags, 'Parameters')] : []),
+    optionSection(spec.globalFlags),
+    ...(hasFlags
+      ? [
+          {
+            content:
+              'Any required parameter left out is prompted for interactively.',
+          },
+        ]
+      : []),
+  ]
+}
+
+const optionSection = (flags: CommandFlag[], header = 'Options'): Section => ({
+  header,
+  optionList: flags.map(toOptionDefinition),
+})
+
+const maxDocumentedValues = 8
+
+interface OptionDefinition {
+  name: string
+  alias?: string
+  description: string
+  type: typeof Boolean | typeof String
+  typeLabel?: string
+}
+
+const toOptionDefinition = (flag: CommandFlag): OptionDefinition => {
+  const description = [
+    flag.isRequired ? '{bold [required]}' : '',
+    flag.description,
+    describeValues(flag),
+  ]
+    .filter((part) => part !== '')
+    .join(' ')
+
+  return {
+    // command-line-usage renders a nameless option as the short form alone.
+    name: flag.long ?? '',
+    ...(flag.short == null ? {} : { alias: flag.short }),
+    // A flag with no value must be typed as a boolean, or the guide labels it
+    // as taking a string.
+    type: flag.takesValue ? String : Boolean,
+    ...(flag.takesValue ? { typeLabel: '{underline value}' } : {}),
+    description,
+  }
+}
+
+const describeValues = (flag: CommandFlag): string => {
+  if (flag.values.length === 0) return ''
+
+  const shown = flag.values.slice(0, maxDocumentedValues).join(', ')
+  const rest = flag.values.length - maxDocumentedValues
+
+  return rest > 0 ? `One of: ${shown}, and ${rest} more.` : `One of: ${shown}.`
+}

package/src/lib/util/cli-args.ts

@@ -23,6 +23,20 @@ export const interactivityFlags: string[] = [
   'i',
 ]
 
+/**
+ * Argument keys that configure the CLI itself
+ * and are therefore never sent as command parameters.
+ */
+export const cliFlags: string[] = [
+  ...interactivityFlags,
+  'h',
+  'help',
+  'json',
+  'remote_api_defs',
+  'update',
+  'version',
+]
+
 /**
  * Thrown when the CLI needs input it cannot prompt for.
  */
@@ -33,13 +47,27 @@ export class NonInteractiveError extends Error {
 export const parseCliArgs = (argv: string[]): ParsedArgs =>
   parseArgs(argv, {
     string: ['code'],
-    boolean: ['non-interactive', 'interactive'],
+    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' },
   })
 
-export const getInteractivity = (args: ParsedArgs): Interactivity => {
+export interface GetInteractivityOptions {
+  /**
+   * Whether there is a terminal to prompt on.
+   *
+   * When there is not, the CLI cannot ask for anything, so it behaves as
+   * though `--non-interactive` was given rather than waiting on a prompt
+   * nobody can answer.
+   */
+  canPrompt?: boolean
+}
+
+export const getInteractivity = (
+  args: ParsedArgs,
+  { canPrompt = true }: GetInteractivityOptions = {},
+): Interactivity => {
   const isNonInteractive =
     args['non_interactive'] === true || args['y'] === true
   const isInteractive = args['interactive'] === true || args['i'] === true
@@ -50,7 +78,9 @@ export const getInteractivity = (args: ParsedArgs): Interactivity => {
     )
   }
   if (isNonInteractive) return 'non-interactive'
+  // An explicit --interactive still asks, and fails loudly if it cannot.
   if (isInteractive) return 'interactive'
+  if (!canPrompt) return 'non-interactive'
   return 'auto'
 }
 

package/src/lib/util/prompt.ts

@@ -0,0 +1,38 @@
+import prompts, { type Answers, type Options, type PromptObject } from 'prompts'
+
+import { NonInteractiveError } from './cli-args.js'
+
+/**
+ * Whether the CLI can ask the user a question.
+ *
+ * Prompts read raw keypresses and render an interface, so they need a
+ * terminal on both ends: when stdin is a pipe or a file it holds request
+ * params, not answers, and when stderr is redirected nobody sees the
+ * question.
+ */
+export const canPrompt = (): boolean =>
+  process.stdin.isTTY === true && process.stderr.isTTY === true
+
+/**
+ * Ask the user a question.
+ *
+ * Prompts are rendered to stderr: a selection is not a command result,
+ * so it must not end up in stdout when the CLI is piped.
+ */
+export const prompt = async <T extends string = string>(
+  questions: PromptObject<T> | Array<PromptObject<T>>,
+  options?: Options,
+): Promise<Answers<T>> => {
+  if (!canPrompt()) {
+    throw new NonInteractiveError(
+      'Cannot prompt without a terminal: pass the missing arguments, or pipe them in as JSON',
+    )
+  }
+
+  const questionList = Array.isArray(questions) ? questions : [questions]
+
+  return await prompts(
+    questionList.map((question) => ({ ...question, stdout: process.stderr })),
+    options,
+  )
+}

package/src/lib/util/read-stdin-json.ts

@@ -0,0 +1,59 @@
+import type { Readable } from 'node:stream'
+
+export interface StdinLike extends AsyncIterable<string | Buffer> {
+  isTTY?: boolean | undefined
+}
+
+/**
+ * Read request params piped into the CLI, e.g.,
+ *
+ * ```
+ * $ echo '{"device_id": "..."}' | seam locks unlock-door --json
+ * $ seam locks unlock-door --json < params.json
+ * ```
+ *
+ * Returns null when stdin is a terminal or is empty,
+ * so an interactive session is never blocked waiting for input.
+ */
+export const readStdinJson = async (
+  stdin: StdinLike | Readable = process.stdin,
+): Promise<Record<string, unknown> | null> => {
+  if ((stdin as StdinLike).isTTY ?? false) return null
+
+  let raw = ''
+  for await (const chunk of stdin) {
+    raw += typeof chunk === 'string' ? chunk : chunk.toString('utf8')
+  }
+
+  return parseJsonParams(raw, 'stdin')
+}
+
+/**
+ * Parse JSON request params, e.g., from stdin or `--json '{"limit": 2}'`.
+ *
+ * Returns null when there is nothing to parse.
+ */
+export const parseJsonParams = (
+  raw: string,
+  source: string,
+): Record<string, unknown> | null => {
+  const trimmed = raw.trim()
+  if (trimmed === '') return null
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(trimmed)
+  } catch (error) {
+    throw new Error(
+      `Could not parse JSON from ${source}: ${(error as Error).message}`,
+    )
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(
+      `Expected a JSON object of request params from ${source}, got ${Array.isArray(parsed) ? 'an array' : typeof parsed}`,
+    )
+  }
+
+  return parsed as Record<string, unknown>
+}

package/src/lib/util/request-seam-api.ts

@@ -1,19 +1,29 @@
 import chalk from 'chalk'
 
 import { getSeam } from 'lib/get-seam.js'
+import { getOutput } from 'lib/output/get-output.js'
+import { selectResponsePayload } from 'lib/output/select-response-payload.js'
 
 import { withLoading } from './with-loading.js'
 
+export interface RequestSeamApiOptions {
+  path: string
+  params: Record<string, any>
+  /** Response key for the endpoint, used to trim the reported payload. */
+  responseKey?: string | null | undefined
+}
+
 export const RequestSeamApi = async ({
   path,
   params,
-}: {
-  path: string
-  params: Record<string, any>
-}) => {
+  responseKey,
+}: RequestSeamApiOptions) => {
   const seam = await getSeam()
+  const output = getOutput()
 
-  logRequest(path, params)
+  output.info(`\n${chalk.green(path)}`)
+  output.info(`Request Params:`)
+  output.info(formatParams(params))
 
   const response = await withLoading('Making request...', () =>
     seam.client.post(path, params, {
@@ -21,23 +31,17 @@ export const RequestSeamApi = async ({
     }),
   )
 
-  logResponse(response)
-
-  return response
-}
-
-const logResponse = (response: { status: number; data: unknown }) => {
   if (response.status >= 400) {
-    console.log(chalk.red(`\n\n[${response.status}]\n`))
+    output.warn(chalk.red(`[${response.status}]`))
+    process.exitCode = 1
   } else {
-    console.log(chalk.green(`\n\n[${response.status}]`))
+    output.info(chalk.green(`[${response.status}]`))
   }
-  console.dir(response.data, { depth: null })
-  console.log('\n')
-}
 
-const logRequest = (apiPath: string, params: Record<string, any>) => {
-  console.log(`\n\n${chalk.green(apiPath)}`)
-  console.log(`Request Params:`)
-  console.log(params)
+  output.data(selectResponsePayload(response.data, { responseKey }))
+
+  return response
 }
+
+const formatParams = (params: Record<string, any>): string =>
+  JSON.stringify(params, null, 2)

package/src/lib/util/with-loading.ts

@@ -1,10 +1,15 @@
 import { createSpinner } from 'nanospinner'
 
+import { getOutput } from 'lib/output/get-output.js'
+
 export const withLoading = async <T>(
   message: string,
   fn: () => Promise<T>,
 ): Promise<T> => {
-  const spinner = createSpinner(message).start()
+  if (!shouldSpin()) return await fn()
+
+  // Progress is not a command result, so it is rendered to stderr.
+  const spinner = createSpinner(message, { stream: process.stderr }).start()
   try {
     const result = await fn()
     spinner.success()
@@ -14,3 +19,6 @@ export const withLoading = async <T>(
     throw error
   }
 }
+
+const shouldSpin = (): boolean =>
+  getOutput().format === 'text' && process.stderr.isTTY === true

package/src/lib/version.ts

@@ -1,5 +1,5 @@
 // Versions are replaced with generated values when the package is packed.
-const seamapiCliVersion = '0.10.0'
+const seamapiCliVersion = '0.12.0'
 const seamapiBlueprintVersion = '1.2.0'
 
 export { seamapiBlueprintVersion }