@equinor/fusion-framework-cli-plugin-ai-base 1.0.5 → 2.0.0

package/dist/types/config.d.ts

@@ -30,12 +30,21 @@ export interface FusionAIConfig {
  */
 export declare const configureFusionAI: <T extends FusionAIConfig>(fn: () => Promise<T> | T) => () => Promise<T> | T;
 /**
- * Options for loading Fusion AI configuration
+ * Options controlling how {@link loadFusionAIConfig} resolves and imports the
+ * Fusion AI configuration file.
  */
 export interface LoadFusionAIConfigOptions {
-    /** Base directory to resolve the config file from (default: process.cwd()) */
+    /**
+     * Base directory used to resolve the config file path.
+     *
+     * @defaultValue `process.cwd()`
+     */
     baseDir?: string;
-    /** File extensions to consider when resolving the config file (default: ['.ts', '.mjs', '.js', '.json']) */
+    /**
+     * File extensions tried (in order) when locating the config file.
+     *
+     * @defaultValue `['.ts', '.mjs', '.js', '.json']`
+     */
     extensions?: string[];
 }
 /**

package/dist/types/options/index.d.ts

@@ -1,3 +1,14 @@
+/**
+ * AI command-option utilities for Fusion Framework CLI plugins.
+ *
+ * @remarks
+ * This entry point provides Commander option definitions, a Zod validation schema,
+ * and the {@link withOptions} helper that wires options and pre-action validation
+ * into any Commander command. Import from
+ * `@equinor/fusion-framework-cli-plugin-ai-base/command-options`.
+ *
+ * @packageDocumentation
+ */
 export { default as options } from './options.js';
 export { withOptions } from './with-options.js';
 export { AiOptionsSchema, type AiOptionsType } from './schema.js';

package/dist/types/options/options.d.ts

@@ -1,48 +1,78 @@
 /**
- * Option for specifying the Azure OpenAI API key.
- * Required for authentication with Azure OpenAI services.
+ * Commander option for the Azure OpenAI API key (`--openai-api-key`).
+ *
+ * @remarks
+ * Required for all Azure OpenAI operations. Falls back to the
+ * `AZURE_OPENAI_API_KEY` environment variable when the flag is omitted.
  */
 export declare const apiKeyOption: import("commander").Option;
 /**
- * Option for specifying the Azure OpenAI API version.
- * Defaults to the latest stable version if not provided.
+ * Commander option for the Azure OpenAI API version (`--openai-api-version`).
+ *
+ * @remarks
+ * Defaults to `2024-02-15-preview`. Falls back to the
+ * `AZURE_OPENAI_API_VERSION` environment variable when the flag is omitted.
  */
 export declare const apiVersionOption: import("commander").Option;
 /**
- * Option for specifying the Azure OpenAI instance name.
- * Required for Azure OpenAI service endpoint construction.
+ * Commander option for the Azure OpenAI instance name (`--openai-instance`).
+ *
+ * @remarks
+ * Required for constructing the Azure OpenAI service endpoint. Falls back to
+ * the `AZURE_OPENAI_INSTANCE_NAME` environment variable when the flag is omitted.
  */
 export declare const apiInstanceOption: import("commander").Option;
 /**
- * Option for specifying the Azure OpenAI deployment name for chat models.
- * Required for chat completions API calls.
+ * Commander option for the Azure OpenAI chat deployment (`--openai-chat-deployment`).
+ *
+ * @remarks
+ * Required for chat-completion operations. Falls back to the
+ * `AZURE_OPENAI_CHAT_DEPLOYMENT_NAME` environment variable when the flag is omitted.
+ * Only added to a command when `withOptions` is called with `includeChat: true`.
  */
 export declare const chatDeploymentOption: import("commander").Option;
 /**
- * Option for specifying the Azure OpenAI deployment name for embedding models.
- * Required for embeddings API calls.
+ * Commander option for the Azure OpenAI embedding deployment (`--openai-embedding-deployment`).
+ *
+ * @remarks
+ * Required for embedding and vector-search operations. Falls back to the
+ * `AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME` environment variable when the flag is omitted.
+ * Only added to a command when `withOptions` is called with `includeEmbedding: true`.
  */
 export declare const embeddingDeploymentOption: import("commander").Option;
 /**
- * Option for specifying the Azure Search endpoint URL.
- * Required for Azure Cognitive Search operations.
+ * Commander option for the Azure Cognitive Search endpoint (`--azure-search-endpoint`).
+ *
+ * @remarks
+ * Required for vector-search operations. Falls back to the
+ * `AZURE_SEARCH_ENDPOINT` environment variable when the flag is omitted.
+ * Only added to a command when `withOptions` is called with `includeSearch: true`.
  */
 export declare const azureSearchEndpointOption: import("commander").Option;
 /**
- * Option for specifying the Azure Search API key.
- * Required for authentication with Azure Cognitive Search.
+ * Commander option for the Azure Cognitive Search API key (`--azure-search-api-key`).
+ *
+ * @remarks
+ * Required for authenticating with Azure Cognitive Search. Falls back to the
+ * `AZURE_SEARCH_API_KEY` environment variable when the flag is omitted.
+ * Only added to a command when `withOptions` is called with `includeSearch: true`.
  */
 export declare const azureSearchApiKeyOption: import("commander").Option;
 /**
- * Option for specifying the Azure Search index name.
- * Required for search operations on a specific index.
+ * Commander option for the Azure Cognitive Search index name (`--azure-search-index-name`).
+ *
+ * @remarks
+ * Identifies the target search index to query or write to. Falls back to the
+ * `AZURE_SEARCH_INDEX_NAME` environment variable when the flag is omitted.
+ * Only added to a command when `withOptions` is called with `includeSearch: true`.
  */
 export declare const azureSearchIndexNameOption: import("commander").Option;
 /**
- * Default export containing all AI-related command options.
+ * All AI-related Commander option definitions as a single object.
  *
- * Provides convenient access to all option definitions for use in CLI commands.
- * Each option can also be imported individually for more granular control.
+ * @remarks
+ * Use this default export for convenient bulk access when you need every option.
+ * For selective inclusion prefer importing the named constants directly.
  */
 declare const _default: {
     apiKeyOption: import("commander").Option;

package/dist/types/options/schema.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Zod validation schema and inferred type for AI command options.
+ *
+ * @packageDocumentation
+ */
 import z from 'zod';
 /**
  * Base Zod schema for AI-related command options.

package/dist/types/options/types.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Hand-authored TypeScript interface for AI CLI command options.
+ *
+ * @remarks
+ * Use {@link AiOptions} when you need a lightweight type without pulling in Zod.
+ * For runtime validation prefer {@link AiOptionsSchema} from the schema module.
+ *
+ * @packageDocumentation
+ */
 /**
  * Configuration options for AI-related CLI commands.
  *

package/dist/types/register.d.ts

@@ -2,23 +2,22 @@ import type { Command } from 'commander';
 /**
  * Registers an AI plugin command with the CLI program.
  *
- * This function ensures the 'ai' command group exists in the CLI program and adds
- * the provided command as a subcommand. If the 'ai' group doesn't exist, it creates
- * it with a standard description. This allows multiple AI-related plugins to register
- * their commands under a common namespace.
+ * Ensures the `ai` command group exists and attaches the provided command
+ * as a direct subcommand. Each plugin is responsible for structuring its
+ * own subcommands internally.
  *
- * @param program - The Commander program instance to register commands with
- * @param command - The command to add to the 'ai' command group
- * @returns void
+ * @param program - The Commander program instance to register commands with.
+ * @param command - The command to add under the `ai` command group.
  *
  * @example
  * ```ts
- * const myAiCommand = createCommand('chat')
- *   .description('Start an AI chat session')
- *   .action(() => { ... });
+ * // Register a command under `ai`:
+ * registerAiPlugin(program, chatCommand);
+ * // Results in: ffc ai chat
  *
- * registerAiPlugin(program, myAiCommand);
- * // Results in: fusion-cli ai chat
+ * // Register a command that has its own subcommands:
+ * registerAiPlugin(program, indexCommand);
+ * // Results in: ffc ai index embeddings, ffc ai index delete, etc.
  * ```
  */
 export declare function registerAiPlugin(program: Command, command: Command): void;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "1.0.5";
+export declare const version = "2.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-cli-plugin-ai-base",
-  "version": "1.0.5",
+  "version": "2.0.0",
   "description": "Base AI plugin package for Fusion Framework CLI",
   "type": "module",
   "main": "dist/esm/index.js",
@@ -44,17 +44,18 @@
   },
   "dependencies": {
     "commander": "^14.0.1",
-    "zod": "^4.3.5",
-    "@equinor/fusion-framework-module": "5.0.6",
-    "@equinor/fusion-imports": "1.1.11",
-    "@equinor/fusion-framework-module-ai": "2.0.2"
+    "zod": "^4.3.6",
+    "@equinor/fusion-framework-module": "6.0.0",
+    "@equinor/fusion-framework-module-ai": "3.0.0",
+    "@equinor/fusion-imports": "2.0.0"
   },
   "peerDependencies": {
-    "@equinor/fusion-framework-cli": "^13.3.16"
+    "@equinor/fusion-framework-cli": "^14.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.8.2",
-    "vitest": "^3.2.4"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0",
+    "@equinor/fusion-framework-cli": "^14.0.0"
   },
   "scripts": {
     "build": "tsc -b",

package/src/config.ts

@@ -34,12 +34,21 @@ export interface FusionAIConfig {
 export const configureFusionAI = <T extends FusionAIConfig>(fn: () => Promise<T> | T) => fn;
 
 /**
- * Options for loading Fusion AI configuration
+ * Options controlling how {@link loadFusionAIConfig} resolves and imports the
+ * Fusion AI configuration file.
  */
 export interface LoadFusionAIConfigOptions {
-  /** Base directory to resolve the config file from (default: process.cwd()) */
+  /**
+   * Base directory used to resolve the config file path.
+   *
+   * @defaultValue `process.cwd()`
+   */
   baseDir?: string;
-  /** File extensions to consider when resolving the config file (default: ['.ts', '.mjs', '.js', '.json']) */
+  /**
+   * File extensions tried (in order) when locating the config file.
+   *
+   * @defaultValue `['.ts', '.mjs', '.js', '.json']`
+   */
   extensions?: string[];
 }
 

package/src/options/index.ts

@@ -1,3 +1,15 @@
+/**
+ * AI command-option utilities for Fusion Framework CLI plugins.
+ *
+ * @remarks
+ * This entry point provides Commander option definitions, a Zod validation schema,
+ * and the {@link withOptions} helper that wires options and pre-action validation
+ * into any Commander command. Import from
+ * `@equinor/fusion-framework-cli-plugin-ai-base/command-options`.
+ *
+ * @packageDocumentation
+ */
+
 export { default as options } from './options.js';
 export { withOptions } from './with-options.js';
 export { AiOptionsSchema, type AiOptionsType } from './schema.js';

package/src/options/options.ts

@@ -1,8 +1,11 @@
 import { createOption } from 'commander';
 
 /**
- * Option for specifying the Azure OpenAI API key.
- * Required for authentication with Azure OpenAI services.
+ * Commander option for the Azure OpenAI API key (`--openai-api-key`).
+ *
+ * @remarks
+ * Required for all Azure OpenAI operations. Falls back to the
+ * `AZURE_OPENAI_API_KEY` environment variable when the flag is omitted.
  */
 export const apiKeyOption = createOption(
   '--openai-api-key <key>',
@@ -10,8 +13,11 @@ export const apiKeyOption = createOption(
 ).env('AZURE_OPENAI_API_KEY');
 
 /**
- * Option for specifying the Azure OpenAI API version.
- * Defaults to the latest stable version if not provided.
+ * Commander option for the Azure OpenAI API version (`--openai-api-version`).
+ *
+ * @remarks
+ * Defaults to `2024-02-15-preview`. Falls back to the
+ * `AZURE_OPENAI_API_VERSION` environment variable when the flag is omitted.
  */
 export const apiVersionOption = createOption(
   '--openai-api-version <version>',
@@ -21,8 +27,11 @@ export const apiVersionOption = createOption(
   .default('2024-02-15-preview');
 
 /**
- * Option for specifying the Azure OpenAI instance name.
- * Required for Azure OpenAI service endpoint construction.
+ * Commander option for the Azure OpenAI instance name (`--openai-instance`).
+ *
+ * @remarks
+ * Required for constructing the Azure OpenAI service endpoint. Falls back to
+ * the `AZURE_OPENAI_INSTANCE_NAME` environment variable when the flag is omitted.
  */
 export const apiInstanceOption = createOption(
   '--openai-instance <name>',
@@ -30,8 +39,12 @@ export const apiInstanceOption = createOption(
 ).env('AZURE_OPENAI_INSTANCE_NAME');
 
 /**
- * Option for specifying the Azure OpenAI deployment name for chat models.
- * Required for chat completions API calls.
+ * Commander option for the Azure OpenAI chat deployment (`--openai-chat-deployment`).
+ *
+ * @remarks
+ * Required for chat-completion operations. Falls back to the
+ * `AZURE_OPENAI_CHAT_DEPLOYMENT_NAME` environment variable when the flag is omitted.
+ * Only added to a command when `withOptions` is called with `includeChat: true`.
  */
 export const chatDeploymentOption = createOption(
   '--openai-chat-deployment <name>',
@@ -39,8 +52,12 @@ export const chatDeploymentOption = createOption(
 ).env('AZURE_OPENAI_CHAT_DEPLOYMENT_NAME');
 
 /**
- * Option for specifying the Azure OpenAI deployment name for embedding models.
- * Required for embeddings API calls.
+ * Commander option for the Azure OpenAI embedding deployment (`--openai-embedding-deployment`).
+ *
+ * @remarks
+ * Required for embedding and vector-search operations. Falls back to the
+ * `AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME` environment variable when the flag is omitted.
+ * Only added to a command when `withOptions` is called with `includeEmbedding: true`.
  */
 export const embeddingDeploymentOption = createOption(
   '--openai-embedding-deployment <name>',
@@ -48,8 +65,12 @@ export const embeddingDeploymentOption = createOption(
 ).env('AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME');
 
 /**
- * Option for specifying the Azure Search endpoint URL.
- * Required for Azure Cognitive Search operations.
+ * Commander option for the Azure Cognitive Search endpoint (`--azure-search-endpoint`).
+ *
+ * @remarks
+ * Required for vector-search operations. Falls back to the
+ * `AZURE_SEARCH_ENDPOINT` environment variable when the flag is omitted.
+ * Only added to a command when `withOptions` is called with `includeSearch: true`.
  */
 export const azureSearchEndpointOption = createOption(
   '--azure-search-endpoint <url>',
@@ -57,8 +78,12 @@ export const azureSearchEndpointOption = createOption(
 ).env('AZURE_SEARCH_ENDPOINT');
 
 /**
- * Option for specifying the Azure Search API key.
- * Required for authentication with Azure Cognitive Search.
+ * Commander option for the Azure Cognitive Search API key (`--azure-search-api-key`).
+ *
+ * @remarks
+ * Required for authenticating with Azure Cognitive Search. Falls back to the
+ * `AZURE_SEARCH_API_KEY` environment variable when the flag is omitted.
+ * Only added to a command when `withOptions` is called with `includeSearch: true`.
  */
 export const azureSearchApiKeyOption = createOption(
   '--azure-search-api-key <key>',
@@ -66,8 +91,12 @@ export const azureSearchApiKeyOption = createOption(
 ).env('AZURE_SEARCH_API_KEY');
 
 /**
- * Option for specifying the Azure Search index name.
- * Required for search operations on a specific index.
+ * Commander option for the Azure Cognitive Search index name (`--azure-search-index-name`).
+ *
+ * @remarks
+ * Identifies the target search index to query or write to. Falls back to the
+ * `AZURE_SEARCH_INDEX_NAME` environment variable when the flag is omitted.
+ * Only added to a command when `withOptions` is called with `includeSearch: true`.
  */
 export const azureSearchIndexNameOption = createOption(
   '--azure-search-index-name <name>',
@@ -75,10 +104,11 @@ export const azureSearchIndexNameOption = createOption(
 ).env('AZURE_SEARCH_INDEX_NAME');
 
 /**
- * Default export containing all AI-related command options.
+ * All AI-related Commander option definitions as a single object.
  *
- * Provides convenient access to all option definitions for use in CLI commands.
- * Each option can also be imported individually for more granular control.
+ * @remarks
+ * Use this default export for convenient bulk access when you need every option.
+ * For selective inclusion prefer importing the named constants directly.
  */
 export default {
   apiKeyOption,

package/src/options/schema.ts

@@ -1,3 +1,9 @@
+/**
+ * Zod validation schema and inferred type for AI command options.
+ *
+ * @packageDocumentation
+ */
+
 import z from 'zod';
 
 /**

package/src/options/types.ts

@@ -1,3 +1,13 @@
+/**
+ * Hand-authored TypeScript interface for AI CLI command options.
+ *
+ * @remarks
+ * Use {@link AiOptions} when you need a lightweight type without pulling in Zod.
+ * For runtime validation prefer {@link AiOptionsSchema} from the schema module.
+ *
+ * @packageDocumentation
+ */
+
 /**
  * Configuration options for AI-related CLI commands.
  *

package/src/options/with-options.ts

@@ -79,7 +79,9 @@ export const withOptions = (
       typeof options.openaiApiKey !== 'string' ||
       options.openaiApiKey.trim() === ''
     ) {
-      throw new InvalidOptionArgumentError('API key is required and must be a non-empty string.');
+      throw new InvalidOptionArgumentError(
+        'Azure OpenAI API key is required. Provide it via --openai-api-key option or AZURE_OPENAI_API_KEY environment variable.',
+      );
     }
 
     // Validate API version
@@ -94,7 +96,7 @@ export const withOptions = (
       options.openaiInstance.trim() === ''
     ) {
       throw new InvalidOptionArgumentError(
-        'API instance name is required and must be a non-empty string.',
+        'Azure OpenAI instance name is required. Provide it via --openai-instance option or AZURE_OPENAI_INSTANCE_NAME environment variable.',
       );
     }
 
@@ -117,7 +119,7 @@ export const withOptions = (
         options.openaiEmbeddingDeployment.trim() === ''
       ) {
         throw new InvalidOptionArgumentError(
-          'Embedding deployment name is required and must be a non-empty string.',
+          'Azure OpenAI embedding deployment name is required. Provide it via --openai-embedding-deployment option or AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME environment variable.',
         );
       }
     }
@@ -139,7 +141,7 @@ export const withOptions = (
         options.azureSearchApiKey.trim() === ''
       ) {
         throw new InvalidOptionArgumentError(
-          'Azure Search API key is required and must be a non-empty string.',
+          'Azure Search API key is required. Provide it via --azure-search-api-key option or AZURE_SEARCH_API_KEY environment variable.',
         );
       }
 

package/src/register.ts

@@ -4,23 +4,22 @@ import { createCommand } from 'commander';
 /**
  * Registers an AI plugin command with the CLI program.
  *
- * This function ensures the 'ai' command group exists in the CLI program and adds
- * the provided command as a subcommand. If the 'ai' group doesn't exist, it creates
- * it with a standard description. This allows multiple AI-related plugins to register
- * their commands under a common namespace.
+ * Ensures the `ai` command group exists and attaches the provided command
+ * as a direct subcommand. Each plugin is responsible for structuring its
+ * own subcommands internally.
  *
- * @param program - The Commander program instance to register commands with
- * @param command - The command to add to the 'ai' command group
- * @returns void
+ * @param program - The Commander program instance to register commands with.
+ * @param command - The command to add under the `ai` command group.
  *
  * @example
  * ```ts
- * const myAiCommand = createCommand('chat')
- *   .description('Start an AI chat session')
- *   .action(() => { ... });
+ * // Register a command under `ai`:
+ * registerAiPlugin(program, chatCommand);
+ * // Results in: ffc ai chat
  *
- * registerAiPlugin(program, myAiCommand);
- * // Results in: fusion-cli ai chat
+ * // Register a command that has its own subcommands:
+ * registerAiPlugin(program, indexCommand);
+ * // Results in: ffc ai index embeddings, ffc ai index delete, etc.
  * ```
  */
 export function registerAiPlugin(program: Command, command: Command): void {
@@ -32,6 +31,7 @@ export function registerAiPlugin(program: Command, command: Command): void {
     );
     program.addCommand(aiCommand);
   }
+
   aiCommand.addCommand(command);
 }
 

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '1.0.5';
+export const version = '2.0.0';

package/tsconfig.json

@@ -14,6 +14,9 @@
     },
     {
       "path": "../../modules/module"
+    },
+    {
+      "path": "../../utils/imports"
     }
   ],
   "include": ["src/**/*"],