feat: Rename "remote API definitions" to "remote schema" throughout

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<version>.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:
 

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,
   })
 

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',

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)
 }

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<ApiBlueprint> => {
-  // 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 })
 }

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)
   })
 })

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)}`,
     )
   }
 

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[],

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.

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

@@ -1,23 +1,23 @@
 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: [],
   },
   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',
+        'Cannot select whether to use the remote schema in non-interactive mode',
       )
     }
-    await interactForUseRemoteApiDefs()
+    await interactForUseRemoteSchema()
     return { kind: 'done' }
   },
 }

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,

src/lib/commands/spec.ts

@@ -114,17 +114,17 @@ 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,
   },
   {
     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 =>

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')
   },
 })
 

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'

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}`)
+}

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<CompletionShell, string> = {

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

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

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

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 {