@seamapi/cli 0.11.0 → 0.12.0

package/src/lib/command-spec.ts

@@ -0,0 +1,400 @@
+import type { Blueprint } from '@seamapi/blueprint'
+
+type Endpoint = Blueprint['routes'][number]['endpoints'][number]
+type Parameter = Endpoint['request']['parameters'][number]
+
+export interface CommandFlag {
+  /** Long form without the leading `--`, or `null` for short-only flags. */
+  long: string | null
+  /** Short form without the leading `-`, or `null` when there is none. */
+  short: string | null
+  description: string
+  /** Known values for the flag, used to complete and document its argument. */
+  values: string[]
+  /** Whether the flag is followed by a value. */
+  takesValue: boolean
+  isRequired: boolean
+}
+
+/**
+ * Whether a command is part of the CLI itself or calls a Seam API endpoint.
+ */
+export type CommandKind = 'cli' | 'api'
+
+export interface CommandDefinition {
+  path: string[]
+  kind: CommandKind
+  /** One line naming what the command does. */
+  title: string
+  /** Longer prose about the command, empty when there is none to add. */
+  description: string
+  flags: CommandFlag[]
+}
+
+export interface Subcommand {
+  name: string
+  /** 'api' when the name holds any command that calls the Seam API. */
+  kind: CommandKind
+  description: string
+}
+
+export interface CommandGroup {
+  /** Command path completed by this group, empty for `seam` itself. */
+  path: string[]
+  subcommands: Subcommand[]
+}
+
+export interface CommandSpec {
+  /** Every invocable command, sorted by command path. */
+  commands: CommandDefinition[]
+  /** Every incomplete command path, sorted by command path. */
+  groups: CommandGroup[]
+  /** Flags accepted regardless of the command. */
+  globalFlags: CommandFlag[]
+}
+
+export const globalFlags: CommandFlag[] = [
+  {
+    long: 'help',
+    short: 'h',
+    description: 'Display this help guide.',
+    values: [],
+    takesValue: false,
+    isRequired: false,
+  },
+  {
+    long: 'interactive',
+    short: 'i',
+    description:
+      'Always prompt to review and edit properties, prefilled with the given arguments.',
+    values: [],
+    takesValue: false,
+    isRequired: false,
+  },
+  {
+    long: 'json',
+    short: null,
+    description:
+      'Write the response to stdout as JSON. Enabled automatically when stdout is not a terminal, disable with --no-json.',
+    values: [],
+    takesValue: false,
+    isRequired: false,
+  },
+  {
+    long: 'non-interactive',
+    short: 'y',
+    description:
+      'Never prompt: exit with an error if the command or any required property is missing.',
+    values: [],
+    takesValue: false,
+    isRequired: false,
+  },
+  {
+    long: 'remote-api-defs',
+    short: null,
+    description: 'Use the API definitions served by the Seam API.',
+    values: [],
+    takesValue: false,
+    isRequired: false,
+  },
+  {
+    long: 'update',
+    short: null,
+    description: 'Force an update of the cached Seam API definitions.',
+    values: [],
+    takesValue: false,
+    isRequired: false,
+  },
+  {
+    long: 'version',
+    short: null,
+    description: 'Print the CLI version.',
+    values: [],
+    takesValue: false,
+    isRequired: false,
+  },
+]
+
+export const flagTokens = (flag: CommandFlag): string[] => {
+  const tokens = []
+  if (flag.long != null) tokens.push(`--${flag.long}`)
+  if (flag.short != null) tokens.push(`-${flag.short}`)
+  return tokens
+}
+
+export const getCommandSpec = (blueprint: Blueprint): CommandSpec => {
+  const commands = sortByPath(
+    dedupeByPath([
+      ...blueprint.routes
+        .flatMap((route) => route.endpoints)
+        .map(toCommandDefinition)
+        // Command and flag names end up unquoted or single-quoted in shell
+        // scripts, so drop any the definitions should never contain rather
+        // than emit something a shell could read as syntax.
+        .filter((command) => command.path.every(isSafeToken)),
+      ...localCommands,
+    ]),
+  )
+
+  return { commands, groups: toCommandGroups(commands), globalFlags }
+}
+
+export const findCommand = (
+  spec: CommandSpec,
+  path: string[],
+): CommandDefinition | undefined =>
+  spec.commands.find((command) => isSamePath(command.path, path))
+
+export const findGroup = (
+  spec: CommandSpec,
+  path: string[],
+): CommandGroup | undefined =>
+  spec.groups.find((group) => isSamePath(group.path, path))
+
+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 => ({
+  long,
+  short: null,
+  description,
+  values: [],
+  takesValue: true,
+  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)
+
+  return {
+    path: toCommandPath(endpoint.path),
+    kind: 'api',
+    title:
+      endpoint.title === ''
+        ? firstSentence(description)
+        : toPlainText(endpoint.title),
+    description,
+    flags: [...endpoint.request.parameters]
+      .map(toCommandFlag)
+      .filter((flag) => flag.long == null || isSafeToken(flag.long))
+      .sort((a, b) => compare(a.long ?? a.short, b.long ?? b.short)),
+  }
+}
+
+const toCommandFlag = (parameter: Parameter): CommandFlag => ({
+  long: toFlagName(parameter.name),
+  short: null,
+  description: toPlainText(parameter.description),
+  values: toFlagValues(parameter),
+  takesValue: true,
+  isRequired: parameter.isRequired,
+})
+
+const toFlagValues = (parameter: Parameter): string[] => {
+  if (parameter.format === 'enum') {
+    return parameter.values.map(({ name }) => name).filter(isSafeToken)
+  }
+
+  if (parameter.format === 'list' && parameter.itemFormat === 'enum') {
+    return parameter.itemEnumValues.map(({ name }) => name).filter(isSafeToken)
+  }
+
+  // Nothing marks parameters as boolean-only flags, so minimist reads the next
+  // argument as the value.
+  if (parameter.format === 'boolean') return ['true', 'false']
+
+  return []
+}
+
+/**
+ * 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
+ * single-quoted in completion scripts, so never emit one that a shell could
+ * read as syntax.
+ */
+const isSafeToken = (token: string): boolean => /^[\w.:@/+-]+$/.test(token)
+
+interface GroupEntry {
+  isCommand: boolean
+  kind: CommandKind
+  description: string
+}
+
+const toCommandGroups = (commands: CommandDefinition[]): CommandGroup[] => {
+  const groups = new Map<string, Map<string, GroupEntry>>()
+
+  for (const command of commands) {
+    for (const [depth, name] of command.path.entries()) {
+      const key = command.path.slice(0, depth).join(' ')
+
+      const entries = groups.get(key) ?? new Map<string, GroupEntry>()
+      groups.set(key, entries)
+
+      // An entry is an API command if any command it holds calls the API.
+      const kind =
+        command.kind === 'api' ? 'api' : (entries.get(name)?.kind ?? 'cli')
+
+      // A command and a group may share a name, e.g., a hypothetical
+      // `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 })
+        continue
+      }
+
+      const entry = entries.get(name)
+      entries.set(name, {
+        isCommand: entry?.isCommand ?? false,
+        kind,
+        description: entry?.description ?? '',
+      })
+    }
+  }
+
+  // Groups have no description of their own in the API definitions, 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 =>
+    [...(groups.get(key)?.keys() ?? [])].join(', ')
+
+  return [...groups]
+    .map(([key, entries]) => ({
+      path: key === '' ? [] : key.split(' '),
+      subcommands: [...entries]
+        .map(([name, entry]) => ({
+          name,
+          kind: entry.kind,
+          description: entry.isCommand
+            ? entry.description
+            : summarizeGroup(key === '' ? name : `${key} ${name}`),
+        }))
+        .sort((a, b) => compare(a.name, b.name)),
+    }))
+    .sort((a, b) => compare(a.path.join(' '), b.path.join(' ')))
+}
+
+const dedupeByPath = (commands: CommandDefinition[]): CommandDefinition[] => {
+  const byPath = new Map<string, CommandDefinition>()
+  for (const command of commands) {
+    const key = command.path.join(' ')
+    if (byPath.has(key)) continue
+    byPath.set(key, command)
+  }
+  return [...byPath.values()]
+}
+
+const sortByPath = (commands: CommandDefinition[]): CommandDefinition[] =>
+  [...commands].sort((a, b) => compare(a.path.join(' '), b.path.join(' ')))
+
+const compare = (a: string | null, b: string | null): number =>
+  (a ?? '') < (b ?? '') ? -1 : (a ?? '') > (b ?? '') ? 1 : 0
+
+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/completion/describe.ts

@@ -0,0 +1,21 @@
+import { firstSentence } from '../command-spec.js'
+import { ellipsis } from '../util/ellipsis.js'
+
+const maxDescriptionLength = 72
+
+/**
+ * Reduce a description to one short line that is safe to embed in a
+ * single-quoted shell string.
+ *
+ * Completion menus give a description a single narrow column, and the shells
+ * offer no way to escape a quote inside the generated scripts, so drop any
+ * character that would end the string early. A colon goes too, since zsh reads
+ * it as the separator in a `_describe` entry.
+ */
+export const describeForShell = (description: string): string =>
+  ellipsis(
+    firstSentence(description)
+      .replace(/['"`$\\:]/g, '')
+      .trim(),
+    maxDescriptionLength,
+  )

package/src/lib/completion/index.ts

@@ -0,0 +1,82 @@
+import type { Blueprint } from '@seamapi/blueprint'
+
+import { type CommandSpec, getCommandSpec } from '../command-spec.js'
+import { renderBashCompletion } from './render-bash.js'
+import { renderFishCompletion } from './render-fish.js'
+import { renderZshCompletion } from './render-zsh.js'
+
+export const completionShells = ['bash', 'fish', 'zsh'] as const
+
+export type CompletionShell = (typeof completionShells)[number]
+
+export const isCompletionShell = (shell: unknown): shell is CompletionShell =>
+  completionShells.includes(shell as CompletionShell)
+
+/** File name to install the completion script for each shell as. */
+export const completionFileNames: Record<CompletionShell, string> = {
+  bash: 'seam.bash',
+  fish: 'seam.fish',
+  zsh: 'seam.zsh',
+}
+
+const renderers: Record<CompletionShell, (spec: CommandSpec) => string> = {
+  bash: renderBashCompletion,
+  fish: renderFishCompletion,
+  zsh: renderZshCompletion,
+}
+
+export const renderCompletion = (
+  shell: CompletionShell,
+  blueprint: Blueprint,
+): string => renderers[shell](getCommandSpec(blueprint))
+
+/**
+ * Render the completion loader installed by system packages.
+ *
+ * The loader runs 'seam completion' the first time the shell completes a seam
+ * command, so installed completions always match the CLI's current Seam API
+ * definitions instead of the definitions packaged at release time. Each shell
+ * loads its completion file on demand, so the CLI runs once per shell session
+ * at first completion, never at shell startup.
+ *
+ * The loader degrades to no completions when the seam command is missing or
+ * cannot produce a script, e.g., offline before the definitions are cached.
+ */
+export const renderCompletionStub = (shell: CompletionShell): string =>
+  stubs[shell]
+
+const stubHeader = (shell: CompletionShell): string =>
+  `# ${shell} completion loader for the seam command.
+#
+# Generated by @seamapi/cli. Loads completions from the CLI on first use, so
+# they always match the CLI's current Seam API definitions. Requires the seam
+# command on PATH. Print the underlying script with 'seam completion ${shell}'.`
+
+const stubs: Record<CompletionShell, string> = {
+  bash: `${stubHeader('bash')}
+#
+# Install to /usr/share/bash-completion/completions/seam
+
+if command -v seam > /dev/null 2>&1; then
+  eval "$(seam completion bash 2> /dev/null)"
+fi
+`,
+  fish: `${stubHeader('fish')}
+#
+# Install to /usr/share/fish/vendor_completions.d/seam.fish
+
+if command --query seam
+    seam completion fish 2> /dev/null | source
+end
+`,
+  zsh: `#compdef seam
+${stubHeader('zsh')}
+#
+# Install to a directory in fpath as _seam
+
+# The generated script ends by dispatching on funcstack, so evaluating it
+# while this autoloaded _seam runs both redefines _seam and completes the
+# in-flight request.
+eval "$(seam completion zsh 2> /dev/null)"
+`,
+}

package/src/lib/completion/render-bash.ts

@@ -0,0 +1,125 @@
+import {
+  type CommandFlag,
+  type CommandSpec,
+  flagTokens,
+} from '../command-spec.js'
+
+export const renderBashCompletion = (spec: CommandSpec): string => {
+  const globalTokens = spec.globalFlags.flatMap(flagTokens).sort()
+  const valuelessTokens = spec.globalFlags
+    .filter(({ takesValue }) => !takesValue)
+    .flatMap(flagTokens)
+    .sort()
+
+  return `${[
+    header,
+    `_seam_global_flags='${globalTokens.join(' ')}'`,
+    `_seam_valueless_flags=' ${valuelessTokens.join(' ')} '`,
+    renderCase('_seam_subcommands', subcommandBranches(spec)),
+    renderCase('_seam_flags', flagBranches(spec)),
+    renderCase('_seam_flag_values', flagValueBranches(spec)),
+    completionFunction,
+    'complete -F _seam_completion seam',
+  ].join('\n\n')}\n`
+}
+
+const header = `# bash completion for the seam command.
+#
+# Generated by @seamapi/cli from the Seam API definitions.
+# Do not edit: regenerate with 'seam completion bash'.
+#
+# Load it for the current shell with
+#
+#   source <(seam completion bash)
+#
+# or install it for every shell with
+#
+#   seam completion bash > /usr/share/bash-completion/completions/seam`
+
+const completionFunction = `_seam_completion() {
+  local current previous word command subcommands
+  local -i index
+
+  current="\${COMP_WORDS[COMP_CWORD]}"
+  previous=''
+  if (( COMP_CWORD > 0 )); then
+    previous="\${COMP_WORDS[COMP_CWORD - 1]}"
+  fi
+
+  # --flag=value splits into three words under the default word breaks.
+  if [[ "$previous" == '=' ]] && (( COMP_CWORD > 1 )); then
+    previous="\${COMP_WORDS[COMP_CWORD - 2]}"
+  fi
+
+  # The command path is the run of words before the first flag.
+  command=''
+  for (( index = 1; index < COMP_CWORD; index++ )); do
+    word="\${COMP_WORDS[index]}"
+    if [[ "$word" == -* ]]; then
+      break
+    fi
+    command="\${command:+$command }$word"
+  done
+
+  # Completing the value of a flag that takes one.
+  if [[ "$previous" == -* && "$_seam_valueless_flags" != *" $previous "* ]]; then
+    COMPREPLY=( $(compgen -W "$(_seam_flag_values "$command $previous")" -- "$current") )
+    return 0
+  fi
+
+  if [[ "$current" == -* ]]; then
+    COMPREPLY=( $(compgen -W "$(_seam_flags "$command") $_seam_global_flags" -- "$current") )
+    return 0
+  fi
+
+  subcommands="$(_seam_subcommands "$command")"
+  if [[ -z "$subcommands" ]]; then
+    COMPREPLY=( $(compgen -W "$(_seam_flags "$command") $_seam_global_flags" -- "$current") )
+    return 0
+  fi
+
+  COMPREPLY=( $(compgen -W "$subcommands" -- "$current") )
+  return 0
+}`
+
+interface Branch {
+  pattern: string
+  words: string[]
+}
+
+const subcommandBranches = (spec: CommandSpec): Branch[] =>
+  spec.groups.map((group) => ({
+    pattern: group.path.join(' '),
+    words: group.subcommands.map(({ name }) => name),
+  }))
+
+const flagBranches = (spec: CommandSpec): Branch[] =>
+  spec.commands
+    .filter(({ flags }) => flags.length > 0)
+    .map((command) => ({
+      pattern: command.path.join(' '),
+      words: command.flags.flatMap(flagTokens),
+    }))
+
+const flagValueBranches = (spec: CommandSpec): Branch[] =>
+  spec.commands.flatMap((command) =>
+    command.flags.filter(hasValues).flatMap((flag) =>
+      flagTokens(flag).map((token) => ({
+        pattern: `${command.path.join(' ')} ${token}`,
+        words: flag.values,
+      })),
+    ),
+  )
+
+const hasValues = (flag: CommandFlag): boolean => flag.values.length > 0
+
+const renderCase = (name: string, branches: Branch[]): string =>
+  [
+    `${name}() {`,
+    `  case "$1" in`,
+    ...branches.map(
+      ({ pattern, words }) => `    '${pattern}') echo '${words.join(' ')}' ;;`,
+    ),
+    `  esac`,
+    `}`,
+  ].join('\n')

package/src/lib/completion/render-fish.ts

@@ -0,0 +1,80 @@
+import type { CommandFlag, CommandSpec } from '../command-spec.js'
+import { describeForShell } from './describe.js'
+
+export const renderFishCompletion = (spec: CommandSpec): string =>
+  `${[
+    header,
+    helpers,
+    ['complete -c seam -f', ...subcommandCompletions(spec)].join('\n'),
+    flagCompletions(spec).join('\n'),
+    globalFlagCompletions(spec).join('\n'),
+  ].join('\n\n')}\n`
+
+const header = `# fish completion for the seam command.
+#
+# Generated by @seamapi/cli from the Seam API definitions.
+# Do not edit: regenerate with 'seam completion fish'.
+#
+# Install it with
+#
+#   seam completion fish > ~/.config/fish/completions/seam.fish`
+
+const helpers = `function __seam_command --description 'Print the seam command path on the command line'
+    set -l tokens (commandline -opc)
+    set -l command
+    if test (count $tokens) -gt 1
+        # The command path is the run of words before the first flag.
+        for token in $tokens[2..-1]
+            if string match -q -- '-*' $token
+                break
+            end
+            set -a command $token
+        end
+    end
+    string join ' ' -- $command
+end
+
+function __seam_using --description 'Test whether the command line names the given seam command'
+    set -l command (__seam_command)
+    test "$command" = "$argv[1]"
+end`
+
+const subcommandCompletions = (spec: CommandSpec): string[] =>
+  spec.groups.flatMap((group) =>
+    group.subcommands.map(({ name, description }) =>
+      complete([
+        `-n '__seam_using "${group.path.join(' ')}"'`,
+        `-a '${name}'`,
+        describe(description),
+      ]),
+    ),
+  )
+
+const flagCompletions = (spec: CommandSpec): string[] =>
+  spec.commands.flatMap((command) =>
+    command.flags.map((flag) =>
+      complete([
+        `-n '__seam_using "${command.path.join(' ')}"'`,
+        ...flagOptions(flag),
+      ]),
+    ),
+  )
+
+const globalFlagCompletions = (spec: CommandSpec): string[] =>
+  spec.globalFlags.map((flag) => complete(flagOptions(flag)))
+
+const flagOptions = (flag: CommandFlag): string[] => [
+  ...(flag.short == null ? [] : [`-s ${flag.short}`]),
+  ...(flag.long == null ? [] : [`-l ${flag.long}`]),
+  ...(flag.takesValue ? ['-r'] : []),
+  ...(flag.values.length === 0 ? [] : [`-a '${flag.values.join(' ')}'`]),
+  describe(flag.description),
+]
+
+const describe = (description: string): string => {
+  const summary = describeForShell(description)
+  return summary === '' ? '' : `-d '${summary}'`
+}
+
+const complete = (options: string[]): string =>
+  ['complete -c seam', ...options.filter((option) => option !== '')].join(' ')