refactor(typings): pf-4119 rename, deprecate cli options (#199)

* index, deprecate, rename CliOptions towards PfMcpCliOptions, alias updates
* options, move DefaultOptionsOverrides to ProgrammaticOptions
* server, agent, replace alias JSDoc with copy, guidance on when to use
* e2e, align annotation with PfMcpCliOptions

Author: cdcabrera

guidelines/agent_coding.md

@@ -194,14 +194,24 @@ While the codebase emphasizes pragmatism, **public APIs require comprehensive JS
 
 - **`@param`**, **`@returns`**, **`@throws`**: Standard documentation for function signature.
 - **`@property`**: Document properties for interfaces or classes.
-- **`@alias`**: Used for stable aliased typings exposed to consumers.
+- **Type aliases (do not use `@alias`)**:
+  - **Don't** use the `@alias` JSDoc tag on type aliases. Documentation generators may apply unwanted side effects (e.g. remaining symbols in the generated output).
+  - **Do** document aliases with prose: `Alias of {@link InternalType} (Internal type).` for stable aliased typings exposed to consumers in `src/index.ts`.
+  - **Do** use the simplified `Alias of {@link InternalType}.` for internal-only aliases to reduce redundancy.
 - **`@template`**: Document generic type parameters.
 - **`@example`**: Provide usage examples for complex functions.
 - **`@note`**: Important implementation details or gotchas.
 
 ### 4.2 JSDoc Format Examples
 
 ```typescript
+/**
+ * Exposed options for CLI use. A focused options interface.
+ *
+ * Alias of {@link CliOptions} (Internal type).
+ */
+type PfMcpCliOptions = CliOptions;
+
 /**
  * Fetches documentation for a PatternFly component.
  * 

src/__tests__/index.test.ts

@@ -1,4 +1,4 @@
-import { main, start, type PfMcpOptions, type CliOptions } from '../index';
+import { main, start, type PfMcpOptions, type PfMcpCliOptions } from '../index';
 import { parseCliOptions, type GlobalOptions } from '../options';
 import { DEFAULT_OPTIONS } from '../options.defaults';
 import { getSessionOptions, runWithSession, setOptions } from '../options.context';
@@ -36,7 +36,7 @@ describe('main', () => {
     mockParseCliOptions.mockImplementation(() => {
       callOrder.push('parse');
 
-      return { logging: defaultLogging } as CliOptions;
+      return { logging: defaultLogging } as PfMcpCliOptions;
     });
 
     mockSetOptions.mockImplementation(options => {
@@ -150,9 +150,23 @@ describe('main', () => {
 });
 
 describe('type exports', () => {
-  it('should export PfMcpOptions type', () => {
+  it.each([
+    {
+      description: 'PfMcpOptions',
+      checkType: (): PfMcpOptions => ({})
+    },
+    {
+      description: 'PfMcpCliOptions',
+      checkType: (): PfMcpCliOptions => ({
+        isHttp: false,
+        logging: {},
+        toolModules: [],
+        pluginIsolation: undefined
+      })
+    }
+  ])('should export type, $description', ({ checkType }) => {
     // TypeScript compilation will fail if the type is unavailable
-    const options: PfMcpOptions = {};
+    const options = checkType();
 
     expect(options).toBeDefined();
   });

src/index.ts

@@ -1,4 +1,4 @@
-import { parseCliOptions, type CliOptions, type DefaultOptionsOverrides } from './options';
+import { parseCliOptions, type CliOptions, type ProgrammaticOptions } from './options';
 import { getSessionOptions, setOptions, runWithSession } from './options.context';
 import {
   runServer,
@@ -23,9 +23,25 @@ import {
 } from './server.toolsUser';
 
 /**
- * Options for "programmatic" use. Extends the `DefaultOptions` interface.
+ * Exposed options for CLI use. A focused options interface.
+ *
+ * Alias of {@link CliOptions} (Internal type).
+ */
+type PfMcpCliOptions = CliOptions;
+
+/**
+ * `CliOptions` renamed to `PfMcpCliOptions` to avoid conflicts with internal naming.
+ *
+ * @deprecated Use {@link PfMcpCliOptions} instead.
+ */
+type DeprecatedCliOptions = PfMcpCliOptions;
+
+/**
+ * Exposed options for programmatic use. A limited `DefaultOptions` interface.
+ *
+ * Alias of {@link ProgrammaticOptions} (Internal type).
  */
-type PfMcpOptions = DefaultOptionsOverrides;
+type PfMcpOptions = ProgrammaticOptions;
 
 /**
  * Additional settings for programmatic control.
@@ -41,49 +57,49 @@ type PfMcpSettings = Pick<ServerSettings, 'allowProcessExit'>;
 /**
  * Server instance with shutdown capability
  *
- * @alias ServerInstance
+ * Alias of {@link ServerInstance} (Internal type).
  */
 type PfMcpInstance = ServerInstance;
 
 /**
  * Subscribes a handler function, `PfMcpOnLogHandler`, to server logs. Automatically unsubscribed on server shutdown.
  *
- * @alias ServerOnLog
+ * Alias of {@link ServerOnLog} (Internal type).
  */
 type PfMcpOnLog = ServerOnLog;
 
 /**
  * The handler function passed by `onLog`, `PfMcpOnLog`, to subscribe to server logs. Automatically unsubscribed on server shutdown.
  *
- * @alias ServerOnLogHandler
+ * Alias of {@link ServerOnLogHandler} (Internal type).
  */
 type PfMcpOnLogHandler = ServerOnLogHandler;
 
 /**
  * The log event passed to the `onLog` handler, `PfMcpOnLogHandler`.
  *
- * @alias ServerLogEvent
+ * Alias of {@link ServerLogEvent} (Internal type).
  */
 type PfMcpLogEvent = ServerLogEvent;
 
 /**
  * Get statistics about the server.
  *
- * @alias ServerGetStats
+ * Alias of {@link ServerGetStats} (Internal type).
  */
 type PfMcpGetStats = ServerGetStats;
 
 /**
  * Statistics about the server.
  *
- * @alias ServerStats
+ * Alias of {@link ServerStats} (Internal type).
  */
 type PfMcpStats = ServerStats;
 
 /**
  * Statistics report about the server.
  *
- * @alias ServerStatReport
+ * Alias of {@link ServerStatReport} (Internal type).
  */
 type PfMcpStatReport = ServerStatReport;
 
@@ -199,7 +215,8 @@ export {
   createMcpTool,
   main,
   main as start,
-  type CliOptions,
+  type DeprecatedCliOptions as CliOptions,
+  type PfMcpCliOptions,
   type PfMcpOptions,
   type PfMcpSettings,
   type PfMcpInstance,

src/options.context.ts

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
-import { type AppSession, type GlobalOptions, type DefaultOptionsOverrides } from './options';
+import { type AppSession, type GlobalOptions, type ProgrammaticOptions } from './options';
 import {
   DEFAULT_OPTIONS,
   LOG_BASENAME,
@@ -98,10 +98,10 @@ const optionsContext = new AsyncLocalStorage<GlobalOptions>();
  * @note In the future, look at adding a re-validation helper here, and potentially in `runWithOptions`,
  * that aligns with CLI options parsing. We need to account for both CLI and programmatic use.
  *
- * @param {DefaultOptionsOverrides} [options] - Optional overrides merged with DEFAULT_OPTIONS.
+ * @param {ProgrammaticOptions} [options] - Optional overrides merged with DEFAULT_OPTIONS.
  * @returns {GlobalOptions} Cloned frozen default options object with session.
  */
-const setOptions = (options?: DefaultOptionsOverrides): GlobalOptions => {
+const setOptions = (options?: ProgrammaticOptions): GlobalOptions => {
   const base = mergeObjects(DEFAULT_OPTIONS, options, { allowNullValues: false, allowUndefinedValues: false });
 
   assertProtocol(base.patternflyOptions.urlWhitelist, base.patternflyOptions.urlWhitelistProtocols);

src/options.defaults.ts

@@ -81,20 +81,6 @@ interface DefaultOptions<TLogOptions = LoggingOptions> {
   xhrFetch: XhrFetchOptions;
 }
 
-/**
- * Overrides for default options. Exposed to the consumer/user.
- */
-type DefaultOptionsOverrides = Partial<
-  Omit<DefaultOptions, 'mode' | 'modeOptions' | 'http' | 'logging' | 'pluginIsolation' | 'toolModules'>
-> & {
-  mode?: DefaultOptions['mode'] | undefined;
-  modeOptions?: Partial<ModeOptions> | undefined;
-  http?: Partial<HttpOptions>;
-  logging?: Partial<LoggingOptions>;
-  pluginIsolation?: 'none' | 'strict' | undefined;
-  toolModules?: ToolModule | ToolModule[] | undefined;
-};
-
 /**
  * HTTP server options.
  *
@@ -549,7 +535,6 @@ export {
   MODE_LEVELS,
   PLUGIN_ISOLATION,
   type DefaultOptions,
-  type DefaultOptionsOverrides,
   type HttpOptions,
   type LoggingOptions,
   type LoggingSession,
@@ -560,6 +545,7 @@ export {
   type RepoResources,
   type ServerInstanceOptions,
   type StatsSession,
+  type ToolModule,
   type WhitelistUrl,
   type XhrFetchOptions
 };

src/options.ts

@@ -3,10 +3,10 @@ import {
   MODE_LEVELS,
   PLUGIN_ISOLATION,
   type DefaultOptions,
-  type DefaultOptionsOverrides,
   type LoggingOptions,
   type HttpOptions,
-  type ModeOptions
+  type ModeOptions,
+  type ToolModule
 } from './options.defaults';
 import { type LogLevel, logSeverity } from './logger';
 import { isUrl, portValid } from './server.helpers';
@@ -26,7 +26,21 @@ type AppSession = {
 type GlobalOptions = DefaultOptions;
 
 /**
- * Options parsed from CLI arguments
+ * Option overrides parsed from programmatic use. Exposed to the consumer/user.
+ */
+type ProgrammaticOptions = Partial<
+  Omit<DefaultOptions, 'mode' | 'modeOptions' | 'http' | 'logging' | 'pluginIsolation' | 'toolModules'>
+> & {
+  mode?: DefaultOptions['mode'] | undefined;
+  modeOptions?: Partial<ModeOptions> | undefined;
+  http?: Partial<HttpOptions>;
+  logging?: Partial<LoggingOptions>;
+  pluginIsolation?: DefaultOptions['pluginIsolation'] | undefined;
+  toolModules?: ToolModule | ToolModule[] | undefined;
+};
+
+/**
+ * Options parsed from CLI arguments. Exposed to the consumer/user.
  *
  * @note `pluginIsolation` preset for external plugins (CLI-provided). If omitted, defaults
  * to 'strict' when external tools are requested, otherwise 'none'.
@@ -241,8 +255,8 @@ export {
   type AppSession,
   type CliOptions,
   type DefaultOptions,
-  type DefaultOptionsOverrides,
   type GlobalOptions,
   type HttpOptions,
-  type LoggingOptions
+  type LoggingOptions,
+  type ProgrammaticOptions
 };

src/server.assertions.ts

@@ -26,7 +26,7 @@ const mcpAssert = (condition: unknown, message: string | (() => string), code: E
 /**
  * General purpose input assert/validation function.
  *
- * @alias mcpAssert
+ * Alias of {@link mcpAssert}.
  *
  * @param condition - Function or condition to be validated.
  * @param message - Thrown error message, or function, that returns the error message.

src/server.toolsUser.ts

@@ -12,15 +12,17 @@ import { normalizeInputSchema } from './server.schema';
 /**
  * Inline tool options.
  *
- * @alias GlobalOptions
+ * Alias of {@link GlobalOptions}.
+ *
  * @note Author-facing configuration.
  */
 type ToolInternalOptions = GlobalOptions;
 
 /**
  * External tool options.
  *
- * @alias ToolOptions
+ * Alias of {@link ToolOptions}.
+ *
  * @note Author-facing configuration.
  */
 type ToolExternalOptions = ToolOptions;
@@ -67,7 +69,8 @@ type CreatorEntry = Pick<NormalizedToolEntry, 'type' | 'original' | 'value' | 't
 /**
  * An MCP tool. A tool config tuple. The handler may be async or sync.
  *
- * @alias McpTool
+ * Alias of {@link McpTool}.
+ *
  * @note Author-facing configuration.
  * @example A tool config tuple. The handler may be async or sync.
  * [

src/server.ts

@@ -53,14 +53,14 @@ interface ServerSettings {
 /**
  * Server stats.
  *
- * @alias Stats
+ * Alias of {@link Stats}.
  */
 type ServerStats = Stats;
 
 /**
  * Server stats report.
  *
- * @alias StatReport
+ * Alias of {@link StatReport}.
  */
 type ServerStatReport = StatReport;
 

tests/e2e/utils/stdioTransportClient.ts

@@ -44,7 +44,7 @@ export interface StdioTransportClient {
  * @param options - Server configuration options
  * @param options.command - Node command to run (default: 'node')
  * @param options.serverPath - Path to built server (default: 'dist/cli.js')
- * @param options.args - Additional args to pass to server, see app `CliOptions` for the full list
+ * @param options.args - Additional args to pass to server, see `PfMcpCliOptions` for the full list
  * @param options.env - Environment variables for the child process
  */
 export const startServer = async ({