From 606e7960ddc9ff857c536edd9fb83d64e0e40dbf Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 12 Aug 2026 05:03:06 +0000 Subject: [PATCH] Rename "API defs" to "schema" in CLI naming Rename the use-remote-api-defs idea to use-remote-schema throughout: - `seam config use-remote-api-defs` -> `seam config use-remote-schema` - `--remote-api-defs` -> `--remote-schema` - config key `use_remote_api_defs` -> `use_remote_schema`, read with a fallback to the legacy key so existing configs keep their setting - `getUseRemoteApiDefs`/`setUseRemoteApiDefs` -> `getUseRemoteSchema`/ `setUseRemoteSchema`, `interactForUseRemoteApiDefs` -> `interactForUseRemoteSchema`, `useRemoteDefinitions` -> `useRemoteSchema` Also say "Seam API schema" instead of "Seam API definitions" in the help text, prompts, download messages, completion headers, and README. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_017bpiHstA7SLhudByn1Mog7 --- README.md | 8 +++---- src/bin/cli.ts | 7 +++--- src/lib/args/parse.ts | 2 +- src/lib/auth/operations.ts | 8 +++---- src/lib/blueprint/index.ts | 12 +++++----- src/lib/blueprint/source-npm.test.ts | 4 ++-- src/lib/blueprint/source-npm.ts | 6 ++--- src/lib/commands/api-command.ts | 2 +- src/lib/commands/local/completion.ts | 6 ++--- ...pi-defs.ts => config-use-remote-schema.ts} | 12 +++++----- src/lib/commands/registry.ts | 4 ++-- src/lib/commands/spec.ts | 12 +++++----- src/lib/config/cli-config.ts | 18 +++++++++------ src/lib/interactions/index.ts | 2 +- src/lib/interactions/use-remote-api-defs.ts | 22 ------------------- src/lib/interactions/use-remote-schema.ts | 22 +++++++++++++++++++ src/lib/render/completion/index.ts | 4 ++-- src/lib/render/completion/render-bash.ts | 2 +- src/lib/render/completion/render-fish.ts | 2 +- src/lib/render/completion/render-zsh.ts | 2 +- test/cli.test.ts | 2 +- test/fixtures/blueprint.ts | 2 +- 22 files changed, 82 insertions(+), 79 deletions(-) rename src/lib/commands/local/{config-use-remote-api-defs.ts => config-use-remote-schema.ts} (50%) delete mode 100644 src/lib/interactions/use-remote-api-defs.ts create mode 100644 src/lib/interactions/use-remote-schema.ts diff --git a/README.md b/README.md index 456e815a..2229ab4b 100644 --- a/README.md +++ b/README.md @@ -306,14 +306,14 @@ System packages install completion loaders instead: small scripts packaged under `completions/` in the published package, and released as `seam-completions-v.tar.gz` on each [GitHub release]. A 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 and +installed completions always match the CLI's current Seam API schema and never go stale between package updates. The `seam-bin` AUR package installs the loaders for all three shells. -Completions are generated from the cached Seam API definitions, so they may +Completions are generated from the cached Seam API schema, so they may briefly lag a newly released API. Pass `--update` to refresh the cache first, -e.g., `seam completion bash --update`. They do not reflect definitions served -by another Seam API endpoint when `seam config use-remote-api-defs` is enabled. +e.g., `seam completion bash --update`. They do not reflect the schema served +by another Seam API endpoint when `seam config use-remote-schema` is enabled. If completions do not appear after installing them system wide: diff --git a/src/bin/cli.ts b/src/bin/cli.ts index c3154be3..55899a8c 100644 --- a/src/bin/cli.ts +++ b/src/bin/cli.ts @@ -63,7 +63,7 @@ async function cli(args: ParsedArgs, argv: string[]) { const helpFlag = args['help'] ?? args['h'] if (helpFlag != null) { - // Help comes from the cached API definitions so that it works without + // Help comes from the cached API schema so that it works without // logging in, and offline once the cache is warm. const cachedBlueprint = await getApiBlueprint({ update }) const { spec } = buildRegistry(cachedBlueprint) @@ -157,11 +157,10 @@ async function cli(args: ParsedArgs, argv: string[]) { return } - const useRemoteApiDefs = - args['remote_api_defs'] ?? config.getUseRemoteApiDefs() + const useRemoteSchema = args['remote_schema'] ?? config.getUseRemoteSchema() const blueprint = await getApiBlueprint({ - useRemoteDefinitions: useRemoteApiDefs ?? false, + useRemoteSchema: useRemoteSchema ?? false, update, }) diff --git a/src/lib/args/parse.ts b/src/lib/args/parse.ts index eb818acc..7144d2be 100644 --- a/src/lib/args/parse.ts +++ b/src/lib/args/parse.ts @@ -35,7 +35,7 @@ export const cliFlags: string[] = [ 'h', 'help', 'json', - 'remote_api_defs', + 'remote_schema', 'update', 'version', 'workspace_id', diff --git a/src/lib/auth/operations.ts b/src/lib/auth/operations.ts index d3b06f00..9ec2a978 100644 --- a/src/lib/auth/operations.ts +++ b/src/lib/auth/operations.ts @@ -113,10 +113,10 @@ export const selectWorkspace = ( config.setWorkspace(workspaceId) } -/** Store whether API definitions come from the endpoint instead of npm. */ -export const setUseRemoteApiDefs = ( - useRemoteApiDefs: boolean, +/** Store whether the API schema comes from the endpoint instead of npm. */ +export const setUseRemoteSchema = ( + useRemoteSchema: boolean, config: CliConfig = getConfig(), ): void => { - config.setUseRemoteApiDefs(useRemoteApiDefs) + config.setUseRemoteSchema(useRemoteSchema) } diff --git a/src/lib/blueprint/index.ts b/src/lib/blueprint/index.ts index f60570ee..942936e1 100644 --- a/src/lib/blueprint/index.ts +++ b/src/lib/blueprint/index.ts @@ -10,18 +10,18 @@ export interface GetApiBlueprintOptions { * Build from the OpenAPI document the configured endpoint is currently * running, instead of the published npm types. */ - useRemoteDefinitions?: boolean - /** Force an update of the cached Seam API definitions. */ + useRemoteSchema?: boolean + /** Force an update of the cached Seam API schema. */ update?: boolean } export const getApiBlueprint = async ({ - useRemoteDefinitions = false, + useRemoteSchema = false, update = false, }: GetApiBlueprintOptions = {}): Promise => { - // Remote definitions describe whatever the endpoint is currently running, so - // build them directly from that endpoint's OpenAPI document. - if (useRemoteDefinitions) return await createRemoteBlueprint() + // The remote schema describes whatever the endpoint is currently running, so + // build it directly from that endpoint's OpenAPI document. + if (useRemoteSchema) return await createRemoteBlueprint() return await getBlueprint({ update }) } diff --git a/src/lib/blueprint/source-npm.test.ts b/src/lib/blueprint/source-npm.test.ts index 0eec3421..aeb0745c 100644 --- a/src/lib/blueprint/source-npm.test.ts +++ b/src/lib/blueprint/source-npm.test.ts @@ -218,7 +218,7 @@ describe('getBlueprint', () => { stubOfflineRegistry() await expect(getBlueprint({ cacheDirectory })).rejects.toThrow( - /could not check for seam api definition updates/i, + /could not check for seam api schema updates/i, ) }) @@ -228,6 +228,6 @@ describe('getBlueprint', () => { await expect( getBlueprint({ cacheDirectory, update: true }), - ).rejects.toThrow(/could not check for seam api definition updates/i) + ).rejects.toThrow(/could not check for seam api schema updates/i) }) }) diff --git a/src/lib/blueprint/source-npm.ts b/src/lib/blueprint/source-npm.ts index f3096fef..35ffd2bc 100644 --- a/src/lib/blueprint/source-npm.ts +++ b/src/lib/blueprint/source-npm.ts @@ -58,7 +58,7 @@ export const getBlueprint = async ( // over failing, unless an update was explicitly requested. if (cache != null && !update) return cache.blueprint throw new Error( - `Could not check for Seam API definition updates: ${toErrorMessage(error)}`, + `Could not check for Seam API schema updates: ${toErrorMessage(error)}`, ) } @@ -73,13 +73,13 @@ export const getBlueprint = async ( let blueprint: Blueprint try { blueprint = await withLoading( - `Downloading Seam API definitions (${typesPackageName}@${manifest.version})`, + `Downloading Seam API schema (${typesPackageName}@${manifest.version})`, async () => await generateBlueprint(manifest, cacheDirectory), ) } catch (error) { if (cache != null && !update) return cache.blueprint throw new Error( - `Could not update Seam API definitions: ${toErrorMessage(error)}`, + `Could not update Seam API schema: ${toErrorMessage(error)}`, ) } diff --git a/src/lib/commands/api-command.ts b/src/lib/commands/api-command.ts index d87913e6..51b0633d 100644 --- a/src/lib/commands/api-command.ts +++ b/src/lib/commands/api-command.ts @@ -94,7 +94,7 @@ export const executeApiCommand = async ( /** * Per-endpoint request policy that is not derivable from the API - * definitions. Keep this table small and explicit. + * schema. Keep this table small and explicit. */ const applyEndpointDefaults = ( path: string[], diff --git a/src/lib/commands/local/completion.ts b/src/lib/commands/local/completion.ts index 1ca51042..9154057f 100644 --- a/src/lib/commands/local/completion.ts +++ b/src/lib/commands/local/completion.ts @@ -10,9 +10,9 @@ import { /** * 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. + * Completions always come from the cached API schema so that they can + * be generated without logging in. They may lag the schema served by + * Seam when config use-remote-schema is enabled. * * Called by the entry before any auth or blueprint context exists, and by * the registered command's executor — one implementation for both. diff --git a/src/lib/commands/local/config-use-remote-api-defs.ts b/src/lib/commands/local/config-use-remote-schema.ts similarity index 50% rename from src/lib/commands/local/config-use-remote-api-defs.ts rename to src/lib/commands/local/config-use-remote-schema.ts index 1c401a5b..4ce89404 100644 --- a/src/lib/commands/local/config-use-remote-api-defs.ts +++ b/src/lib/commands/local/config-use-remote-schema.ts @@ -1,12 +1,12 @@ import type { Command } from 'lib/commands/registry.js' import { NonInteractiveError } from 'lib/errors.js' -import { interactForUseRemoteApiDefs } from 'lib/interactions/index.js' +import { interactForUseRemoteSchema } from 'lib/interactions/index.js' -export const configUseRemoteApiDefsCommand: Command = { +export const configUseRemoteSchemaCommand: Command = { definition: { - path: ['config', 'use-remote-api-defs'], + path: ['config', 'use-remote-schema'], kind: 'cli', - title: 'Choose whether to use the API definitions served by Seam.', + title: 'Choose whether to use the schema served by Seam.', description: '', flags: [], }, @@ -14,10 +14,10 @@ export const configUseRemoteApiDefsCommand: Command = { execute: async (_invocation, ctx) => { if (ctx.interactivity === 'non-interactive') { throw new NonInteractiveError( - 'Cannot select whether to use remote API definitions in non-interactive mode', + 'Cannot select whether to use the remote schema in non-interactive mode', ) } - await interactForUseRemoteApiDefs() + await interactForUseRemoteSchema() return { kind: 'done' } }, } diff --git a/src/lib/commands/registry.ts b/src/lib/commands/registry.ts index 30899396..87ee25b3 100644 --- a/src/lib/commands/registry.ts +++ b/src/lib/commands/registry.ts @@ -7,7 +7,7 @@ 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 { configUseRemoteApiDefsCommand } from './local/config-use-remote-api-defs.js' +import { configUseRemoteSchemaCommand } from './local/config-use-remote-schema.js' import { healthCommand } from './local/health.js' import { loginCommand } from './local/login.js' import { logoutCommand } from './local/logout.js' @@ -73,7 +73,7 @@ const completionCommands = createCompletionCommands( export const localCommands: Command[] = [ ...completionCommands, configRevealLocationCommand, - configUseRemoteApiDefsCommand, + configUseRemoteSchemaCommand, healthCommand, loginCommand, logoutCommand, diff --git a/src/lib/commands/spec.ts b/src/lib/commands/spec.ts index 2aa0f949..4f5a2ca0 100644 --- a/src/lib/commands/spec.ts +++ b/src/lib/commands/spec.ts @@ -114,9 +114,9 @@ export const globalFlags: CommandFlag[] = [ isRequired: false, }, { - long: 'remote-api-defs', + long: 'remote-schema', short: null, - description: 'Use the API definitions served by the Seam API.', + description: 'Use the schema served by the Seam API.', values: [], takesValue: false, isRequired: false, @@ -124,7 +124,7 @@ export const globalFlags: CommandFlag[] = [ { long: 'update', short: null, - description: 'Force an update of the cached Seam API definitions.', + description: 'Force an update of the cached Seam API schema.', values: [], takesValue: false, isRequired: false, @@ -156,7 +156,7 @@ export const flagTokens = (flag: CommandFlag): string[] => { } /** - * Derive the command spec from the API definitions, merged with the commands + * Derive the command spec from the API schema, merged with the commands * the CLI declares itself (see `commands/registry.ts`, the single source of * those declarations). */ @@ -251,7 +251,7 @@ const toFlagValues = (parameter: Parameter): string[] => { /** * 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 + * enum names come from the API schema and are embedded unquoted or * single-quoted in completion scripts, so never emit one that a shell could * read as syntax. */ @@ -298,7 +298,7 @@ const toCommandGroups = (commands: CommandDefinition[]): CommandGroup[] => { } } - // Groups have no description of their own in the API definitions, so name + // Groups have no description of their own in the API schema, 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 => diff --git a/src/lib/config/cli-config.ts b/src/lib/config/cli-config.ts index 88acc271..439194cd 100644 --- a/src/lib/config/cli-config.ts +++ b/src/lib/config/cli-config.ts @@ -17,8 +17,8 @@ export interface CliConfig { getWorkspace: () => string | null setWorkspace: (workspaceId: string) => void unsetWorkspace: () => void - getUseRemoteApiDefs: () => boolean | null - setUseRemoteApiDefs: (useRemoteApiDefs: boolean) => void + getUseRemoteSchema: () => boolean | null + setUseRemoteSchema: (useRemoteSchema: boolean) => void } export const createCliConfig = (store: ConfigStore): CliConfig => ({ @@ -64,13 +64,17 @@ export const createCliConfig = (store: ConfigStore): CliConfig => ({ store.delete('current_workspace_id') }, - getUseRemoteApiDefs: () => { - const useRemoteApiDefs = store.get('use_remote_api_defs') - return typeof useRemoteApiDefs === 'boolean' ? useRemoteApiDefs : null + getUseRemoteSchema: () => { + // `use_remote_api_defs` is what an older CLI called the same setting. + const useRemoteSchema = + store.get('use_remote_schema') ?? store.get('use_remote_api_defs') + return typeof useRemoteSchema === 'boolean' ? useRemoteSchema : null }, - setUseRemoteApiDefs: (useRemoteApiDefs) => { - store.set('use_remote_api_defs', useRemoteApiDefs) + /** Store the setting, dropping any value left under the legacy key. */ + setUseRemoteSchema: (useRemoteSchema) => { + store.set('use_remote_schema', useRemoteSchema) + store.delete('use_remote_api_defs') }, }) diff --git a/src/lib/interactions/index.ts b/src/lib/interactions/index.ts index 88753e39..cc671f21 100644 --- a/src/lib/interactions/index.ts +++ b/src/lib/interactions/index.ts @@ -14,6 +14,6 @@ export * from './endpoint-selection.js' export * from './login.js' export * from './resource.js' export * from './timestamp.js' -export * from './use-remote-api-defs.js' +export * from './use-remote-schema.js' export * from './user-identity.js' export * from './workspace-id.js' diff --git a/src/lib/interactions/use-remote-api-defs.ts b/src/lib/interactions/use-remote-api-defs.ts deleted file mode 100644 index 59f006b6..00000000 --- a/src/lib/interactions/use-remote-api-defs.ts +++ /dev/null @@ -1,22 +0,0 @@ -import { setUseRemoteApiDefs } from 'lib/auth/operations.js' -import { getOutput } from 'lib/output/get-output.js' -import { promptSelect } from 'lib/prompt.js' - -export async function interactForUseRemoteApiDefs() { - const useRemoteApiDefs = await promptSelect({ - message: 'Always use remote API Definitions?', - choices: [ - { - label: 'Yes', - value: true, - }, - { - label: 'No', - value: false, - }, - ], - }) - - setUseRemoteApiDefs(useRemoteApiDefs) - getOutput().info(`Use remote API Definitions: ${useRemoteApiDefs}`) -} diff --git a/src/lib/interactions/use-remote-schema.ts b/src/lib/interactions/use-remote-schema.ts new file mode 100644 index 00000000..fb0b0f7f --- /dev/null +++ b/src/lib/interactions/use-remote-schema.ts @@ -0,0 +1,22 @@ +import { setUseRemoteSchema } from 'lib/auth/operations.js' +import { getOutput } from 'lib/output/get-output.js' +import { promptSelect } from 'lib/prompt.js' + +export async function interactForUseRemoteSchema() { + const useRemoteSchema = await promptSelect({ + message: 'Always use the remote schema?', + choices: [ + { + label: 'Yes', + value: true, + }, + { + label: 'No', + value: false, + }, + ], + }) + + setUseRemoteSchema(useRemoteSchema) + getOutput().info(`Use remote schema: ${useRemoteSchema}`) +} diff --git a/src/lib/render/completion/index.ts b/src/lib/render/completion/index.ts index c032f6d7..d397f69a 100644 --- a/src/lib/render/completion/index.ts +++ b/src/lib/render/completion/index.ts @@ -34,7 +34,7 @@ export const renderCompletion = ( * * 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 + * schema instead of the schema 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. * @@ -61,7 +61,7 @@ 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 +# they always match the CLI's current Seam API schema. Requires the seam # command on PATH. Print the underlying script with 'seam completion ${shell}'.` const stubs: Record = { diff --git a/src/lib/render/completion/render-bash.ts b/src/lib/render/completion/render-bash.ts index fcabd6e7..c7cc0255 100644 --- a/src/lib/render/completion/render-bash.ts +++ b/src/lib/render/completion/render-bash.ts @@ -25,7 +25,7 @@ export const renderBashCompletion = (spec: CommandSpec): string => { const header = `# bash completion for the seam command. # -# Generated by @seamapi/cli from the Seam API definitions. +# Generated by @seamapi/cli from the Seam API schema. # Do not edit: regenerate with 'seam completion bash'. # # Load it for the current shell with diff --git a/src/lib/render/completion/render-fish.ts b/src/lib/render/completion/render-fish.ts index a76ab079..3f35ab36 100644 --- a/src/lib/render/completion/render-fish.ts +++ b/src/lib/render/completion/render-fish.ts @@ -13,7 +13,7 @@ export const renderFishCompletion = (spec: CommandSpec): string => const header = `# fish completion for the seam command. # -# Generated by @seamapi/cli from the Seam API definitions. +# Generated by @seamapi/cli from the Seam API schema. # Do not edit: regenerate with 'seam completion fish'. # # Install it with diff --git a/src/lib/render/completion/render-zsh.ts b/src/lib/render/completion/render-zsh.ts index f7474ff9..b1155bd8 100644 --- a/src/lib/render/completion/render-zsh.ts +++ b/src/lib/render/completion/render-zsh.ts @@ -27,7 +27,7 @@ const header = `#compdef seam # zsh completion for the seam command. # -# Generated by @seamapi/cli from the Seam API definitions. +# Generated by @seamapi/cli from the Seam API schema. # Do not edit: regenerate with 'seam completion zsh'. # # Load it for the current shell with diff --git a/test/cli.test.ts b/test/cli.test.ts index d6bc24da..ace7608b 100644 --- a/test/cli.test.ts +++ b/test/cli.test.ts @@ -97,7 +97,7 @@ beforeAll(async () => { ) // A pre-seeded blueprint cache holding the fixture blueprint, so tests - // that pin parameter handling run against known API definitions and + // that pin parameter handling run against a known API schema and // never touch the npm registry. const packageJson = await readFile(join(projectRoot, 'package.json'), 'utf8') const pkg = JSON.parse(packageJson) as { diff --git a/test/fixtures/blueprint.ts b/test/fixtures/blueprint.ts index 0439520e..24c44f10 100644 --- a/test/fixtures/blueprint.ts +++ b/test/fixtures/blueprint.ts @@ -2,7 +2,7 @@ import type { Blueprint } from '@seamapi/blueprint' /** * A blueprint with just enough shape to derive a command spec from, standing - * in for the API definitions bundled with the CLI. + * in for the API schema bundled with the CLI. */ export const testBlueprint = { routes: [