@equinor/fusion-framework-cli-plugin-ai-base 4.0.5 → 4.0.6

package/dist/types/configure-fusion-ai.d.ts

@@ -0,0 +1,21 @@
+import type { FusionAIConfig } from './fusion-ai-config.js';
+/**
+ * Configuration factory function for Fusion AI operations.
+ *
+ * This helper function provides type safety and consistency for creating AI configuration
+ * functions. It accepts a function that returns configuration (either synchronously or
+ * asynchronously) and returns it unchanged, providing a typed interface for consumers.
+ *
+ * @param fn - Function that returns Fusion AI configuration (sync or async)
+ * @returns The same configuration function, typed for use with loadFusionAIConfig
+ *
+ * @example
+ * ```ts
+ * // fusion-ai.config.ts
+ * export default configureFusionAI(async () => ({
+ *   apiKey: process.env.OPENAI_API_KEY,
+ *   deployment: 'gpt-4',
+ * }));
+ * ```
+ */
+export declare const configureFusionAI: <T extends FusionAIConfig>(fn: () => Promise<T> | T) => () => Promise<T> | T;

package/dist/types/fusion-ai-config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Base configuration interface for Fusion AI operations.
+ *
+ * This interface serves as the base type for all Fusion AI configuration objects.
+ * Implementations should extend this interface with specific configuration properties
+ * relevant to their use case. The configuration is typically created using
+ * `configureFusionAI` and loaded via `loadFusionAIConfig`.
+ */
+export interface FusionAIConfig {
+    [key: string]: unknown;
+}

package/dist/types/index.d.ts

@@ -8,6 +8,8 @@
  *
  * @packageDocumentation
  */
-export { type FusionAIConfig, type LoadFusionAIConfigOptions, configureFusionAI, loadFusionAIConfig, } from './config.js';
+export type { FusionAIConfig } from './fusion-ai-config.js';
+export { configureFusionAI } from './configure-fusion-ai.js';
+export { type LoadFusionAIConfigOptions, loadFusionAIConfig } from './load-fusion-ai-config.js';
 export { setupFramework, type FrameworkInstance } from './setup-framework.js';
-export { registerAiPlugin } from './register.js';
+export { registerAiPlugin } from './register-ai-plugin.js';

package/dist/types/{config.d.ts → load-fusion-ai-config.d.ts}

@@ -1,34 +1,4 @@
-/**
- * Base configuration interface for Fusion AI operations.
- *
- * This interface serves as the base type for all Fusion AI configuration objects.
- * Implementations should extend this interface with specific configuration properties
- * relevant to their use case. The configuration is typically created using
- * `configureFusionAI` and loaded via `loadFusionAIConfig`.
- */
-export interface FusionAIConfig {
-    [key: string]: unknown;
-}
-/**
- * Configuration factory function for Fusion AI operations.
- *
- * This helper function provides type safety and consistency for creating AI configuration
- * functions. It accepts a function that returns configuration (either synchronously or
- * asynchronously) and returns it unchanged, providing a typed interface for consumers.
- *
- * @param fn - Function that returns Fusion AI configuration (sync or async)
- * @returns The same configuration function, typed for use with loadFusionAIConfig
- *
- * @example
- * ```ts
- * // fusion-ai.config.ts
- * export default configureFusionAI(async () => ({
- *   apiKey: process.env.OPENAI_API_KEY,
- *   deployment: 'gpt-4',
- * }));
- * ```
- */
-export declare const configureFusionAI: <T extends FusionAIConfig>(fn: () => Promise<T> | T) => () => Promise<T> | T;
+import type { FusionAIConfig } from './fusion-ai-config.js';
 /**
  * Options controlling how {@link loadFusionAIConfig} resolves and imports the
  * Fusion AI configuration file.
@@ -53,6 +23,7 @@ export interface LoadFusionAIConfigOptions {
  * The config file should export a function (via `configureFusionAI`) that returns
  * the configuration object. The function can be synchronous or asynchronous.
  *
+ * @template T - Shape of the resolved Fusion AI configuration object.
  * @param configPath - Path to the config file without extension (default: 'fusion-ai.config')
  * @param options - Optional parameters for loading the configuration
  * @returns Promise resolving to the loaded and executed configuration

package/dist/types/options/{schema.d.ts → ai-options-schema.d.ts}

@@ -19,6 +19,6 @@ export declare const AiOptionsSchema: z.ZodObject<{
     chatModel: z.ZodOptional<z.ZodString>;
     embedModel: z.ZodOptional<z.ZodString>;
     indexName: z.ZodOptional<z.ZodString>;
-    debug: z.ZodDefault<z.z.ZodCoercedBoolean<unknown>>;
-}, z.z.core.$strip>;
+    debug: z.ZodDefault<z.ZodCoercedBoolean<unknown>>;
+}, z.core.$strip>;
 export type AiOptionsType = z.infer<typeof AiOptionsSchema>;

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

@@ -11,5 +11,5 @@
  */
 export { default as options } from './options.js';
 export { withOptions } from './with-options.js';
-export { AiOptionsSchema, type AiOptionsType } from './schema.js';
+export { AiOptionsSchema, type AiOptionsType } from './ai-options-schema.js';
 export type { AiOptions } from './types.js';

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

@@ -14,6 +14,13 @@ export declare const embedModelOption: import("node_modules/commander/typings/in
 export declare const indexNameOption: import("node_modules/commander/typings/index.js").Option;
 /** `-d, --debug` | `RUNNER_DEBUG` — enable verbose logging */
 export declare const debugOption: import("node_modules/commander/typings/index.js").Option;
+/**
+ * Aggregated Commander option definitions for Fusion AI CLI commands.
+ *
+ * @remarks
+ * Individual options are defined above and re-exported here for convenient
+ * access as a single object.
+ */
 declare const _default: {
     envOption: import("node_modules/commander/typings/index.js").Option;
     tokenOption: import("node_modules/commander/typings/index.js").Option;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "4.0.5";
+export declare const version = "4.0.6";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-cli-plugin-ai-base",
-  "version": "4.0.5",
+  "version": "4.0.6",
   "description": "Base AI plugin package for Fusion Framework CLI",
   "type": "module",
   "main": "dist/esm/index.js",
@@ -45,17 +45,17 @@
   "dependencies": {
     "commander": "^15.0.0",
     "zod": "^4.4.3",
-    "@equinor/fusion-framework-module": "6.1.0",
-    "@equinor/fusion-framework-module-ai": "6.0.1",
-    "@equinor/fusion-imports": "2.0.0"
+    "@equinor/fusion-framework-module": "6.1.1",
+    "@equinor/fusion-framework-module-ai": "6.0.2",
+    "@equinor/fusion-imports": "2.0.1"
   },
   "peerDependencies": {
-    "@equinor/fusion-framework-cli": "^15.1.8"
+    "@equinor/fusion-framework-cli": "^15.2.1"
   },
   "devDependencies": {
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.0",
-    "@equinor/fusion-framework-cli": "^15.1.8"
+    "@equinor/fusion-framework-cli": "^15.2.1"
   },
   "scripts": {
     "build": "tsc -b",

package/src/configure-fusion-ai.ts

@@ -0,0 +1,22 @@
+import type { FusionAIConfig } from './fusion-ai-config.js';
+
+/**
+ * Configuration factory function for Fusion AI operations.
+ *
+ * This helper function provides type safety and consistency for creating AI configuration
+ * functions. It accepts a function that returns configuration (either synchronously or
+ * asynchronously) and returns it unchanged, providing a typed interface for consumers.
+ *
+ * @param fn - Function that returns Fusion AI configuration (sync or async)
+ * @returns The same configuration function, typed for use with loadFusionAIConfig
+ *
+ * @example
+ * ```ts
+ * // fusion-ai.config.ts
+ * export default configureFusionAI(async () => ({
+ *   apiKey: process.env.OPENAI_API_KEY,
+ *   deployment: 'gpt-4',
+ * }));
+ * ```
+ */
+export const configureFusionAI = <T extends FusionAIConfig>(fn: () => Promise<T> | T) => fn;

package/src/fusion-ai-config.ts

@@ -0,0 +1,11 @@
+/**
+ * Base configuration interface for Fusion AI operations.
+ *
+ * This interface serves as the base type for all Fusion AI configuration objects.
+ * Implementations should extend this interface with specific configuration properties
+ * relevant to their use case. The configuration is typically created using
+ * `configureFusionAI` and loaded via `loadFusionAIConfig`.
+ */
+export interface FusionAIConfig {
+  [key: string]: unknown;
+}

package/src/index.ts

@@ -9,11 +9,8 @@
  * @packageDocumentation
  */
 
-export {
-  type FusionAIConfig,
-  type LoadFusionAIConfigOptions,
-  configureFusionAI,
-  loadFusionAIConfig,
-} from './config.js';
+export type { FusionAIConfig } from './fusion-ai-config.js';
+export { configureFusionAI } from './configure-fusion-ai.js';
+export { type LoadFusionAIConfigOptions, loadFusionAIConfig } from './load-fusion-ai-config.js';
 export { setupFramework, type FrameworkInstance } from './setup-framework.js';
-export { registerAiPlugin } from './register.js';
+export { registerAiPlugin } from './register-ai-plugin.js';

package/src/{config.ts → load-fusion-ai-config.ts}

@@ -1,37 +1,5 @@
 import { importConfig } from '@equinor/fusion-imports';
-
-/**
- * Base configuration interface for Fusion AI operations.
- *
- * This interface serves as the base type for all Fusion AI configuration objects.
- * Implementations should extend this interface with specific configuration properties
- * relevant to their use case. The configuration is typically created using
- * `configureFusionAI` and loaded via `loadFusionAIConfig`.
- */
-export interface FusionAIConfig {
-  [key: string]: unknown;
-}
-
-/**
- * Configuration factory function for Fusion AI operations.
- *
- * This helper function provides type safety and consistency for creating AI configuration
- * functions. It accepts a function that returns configuration (either synchronously or
- * asynchronously) and returns it unchanged, providing a typed interface for consumers.
- *
- * @param fn - Function that returns Fusion AI configuration (sync or async)
- * @returns The same configuration function, typed for use with loadFusionAIConfig
- *
- * @example
- * ```ts
- * // fusion-ai.config.ts
- * export default configureFusionAI(async () => ({
- *   apiKey: process.env.OPENAI_API_KEY,
- *   deployment: 'gpt-4',
- * }));
- * ```
- */
-export const configureFusionAI = <T extends FusionAIConfig>(fn: () => Promise<T> | T) => fn;
+import type { FusionAIConfig } from './fusion-ai-config.js';
 
 /**
  * Options controlling how {@link loadFusionAIConfig} resolves and imports the
@@ -58,6 +26,7 @@ export interface LoadFusionAIConfigOptions {
  * The config file should export a function (via `configureFusionAI`) that returns
  * the configuration object. The function can be synchronous or asynchronous.
  *
+ * @template T - Shape of the resolved Fusion AI configuration object.
  * @param configPath - Path to the config file without extension (default: 'fusion-ai.config')
  * @param options - Optional parameters for loading the configuration
  * @returns Promise resolving to the loaded and executed configuration
@@ -86,6 +55,7 @@ export async function loadFusionAIConfig<T extends FusionAIConfig = FusionAIConf
 
   // Execute the configuration function (handles both sync and async)
   const configFn = result.config;
+  // Config files export a function via configureFusionAI; execute it to resolve the value.
   if (typeof configFn === 'function') {
     return await configFn();
   }

package/src/options/index.ts

@@ -12,5 +12,5 @@
 
 export { default as options } from './options.js';
 export { withOptions } from './with-options.js';
-export { AiOptionsSchema, type AiOptionsType } from './schema.js';
+export { AiOptionsSchema, type AiOptionsType } from './ai-options-schema.js';
 export type { AiOptions } from './types.js';

package/src/options/options.ts

@@ -1,8 +1,11 @@
 import { createOption } from 'commander';
 
-// Default Fusion AAD identifiers (same defaults as the CLI's auth options)
+// Default Fusion AAD tenant ID (same default as the CLI's auth options)
 const DEFAULT_TENANT_ID = '3aa4a235-b6e2-48d5-9195-7fcf05b459b0' as const;
+
+// Default Fusion AAD client ID (same default as the CLI's auth options)
 const DEFAULT_CLIENT_ID = 'a318b8e1-0295-4e17-98d5-35f67dfeba14' as const;
+
 const DEFAULT_MODEL_CHAT = 'gpt-5.1-chat' as const;
 const DEFAULT_MODEL_EMBED = 'text-embedding-3-large' as const;
 
@@ -56,6 +59,13 @@ export const debugOption = createOption('-d, --debug', 'Enable debug mode for ve
   .env('RUNNER_DEBUG')
   .default(false);
 
+/**
+ * Aggregated Commander option definitions for Fusion AI CLI commands.
+ *
+ * @remarks
+ * Individual options are defined above and re-exported here for convenient
+ * access as a single object.
+ */
 export default {
   envOption,
   tokenOption,

package/src/options/with-options.ts

@@ -41,23 +41,29 @@ export const withOptions = (
   command.addOption(clientIdOption);
   command.addOption(debugOption);
 
+  // Optional options are only added when the corresponding feature flag is set.
   if (args?.includeChat) command.addOption(chatModelOption);
+  // Embed option is opt-in via includeEmbedding.
   if (args?.includeEmbedding) command.addOption(embedModelOption);
+  // Search option is opt-in via includeSearch.
   if (args?.includeSearch) command.addOption(indexNameOption);
 
   command.hook('preAction', (thisCommand) => {
     const opts = thisCommand.opts();
 
+    // Enforce chat model presence when the chat option was requested.
     if (args?.includeChat && !opts.chatModel?.trim()) {
       throw new InvalidOptionArgumentError(
         'Chat model name is required. Provide --chat-model or set FUSION_AI_CHAT_MODEL.',
       );
     }
+    // Enforce embed model presence when the embedding option was requested.
     if (args?.includeEmbedding && !opts.embedModel?.trim()) {
       throw new InvalidOptionArgumentError(
         'Embedding model name is required. Provide --embed-model or set FUSION_AI_EMBED_MODEL.',
       );
     }
+    // Enforce index name presence when the search option was requested.
     if (args?.includeSearch && !opts.indexName?.trim()) {
       throw new InvalidOptionArgumentError(
         'Index name is required. Provide --index-name or set FUSION_AI_INDEX_NAME.',

package/src/{register.ts → register-ai-plugin.ts}

@@ -23,8 +23,9 @@ import { createCommand } from 'commander';
  * ```
  */
 export function registerAiPlugin(program: Command, command: Command): void {
-  // Create 'ai' command group if it doesn't exist
+  // Look up an existing 'ai' command group before creating a new one.
   let aiCommand = program.commands.find((cmd) => cmd.name() === 'ai');
+  // Create 'ai' command group if it doesn't exist
   if (!aiCommand) {
     aiCommand = createCommand('ai').description(
       'Commands for interacting with AI models and Azure OpenAI services',

package/src/setup-framework.ts

@@ -32,6 +32,7 @@ export const setupFramework = async (options: AiOptions): Promise<FusionFramewor
 
   const env = (options.env as FusionEnv) ?? FusionEnv.ContinuesIntegration;
 
+  // Surface resolved environment and auth mode when debug logging is enabled.
   if (debug) {
     console.debug('[debug] Environment:', env);
     console.debug('[debug] Auth mode:', options.token ? 'static-token' : 'azure-identity');
@@ -39,6 +40,7 @@ export const setupFramework = async (options: AiOptions): Promise<FusionFramewor
 
   /** Initialise the framework, resolve the AI service, and pre-cache tokens. */
   const initAndSetup = async (): Promise<FusionFramework<[AIModule]>> => {
+    // Trace framework initialization start when debug logging is enabled.
     if (debug) console.debug('[debug] Initializing framework with AI module…');
 
     const framework = await initializeFramework<[AIModule]>({ env, auth }, (configurator) => {
@@ -50,6 +52,7 @@ export const setupFramework = async (options: AiOptions): Promise<FusionFramewor
     const service = await framework.serviceDiscovery.resolveService('ai');
     const scopes = service.scopes ?? service.defaultScopes ?? [];
 
+    // Surface resolved service URL and scopes when debug logging is enabled.
     if (debug) {
       console.debug('[debug] AI service URL:', service.uri);
       console.debug('[debug] AI service scopes:', scopes);
@@ -58,8 +61,10 @@ export const setupFramework = async (options: AiOptions): Promise<FusionFramewor
     // Pre-cache a token for the AI service scopes so strategy callbacks
     // don't attempt (and fail) a silent acquisition later.
     const token = await framework.auth.acquireAccessToken({ request: { scopes } });
+    // Guard: acquireAccessToken can resolve falsy when the token cache is empty.
     if (!token) throw new Error('Failed to acquire access token for the AI service.');
 
+    // Trace successful token acquisition when debug logging is enabled.
     if (debug) console.debug('[debug] Token acquired successfully');
 
     return framework;

package/src/version.ts

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

package/dist/esm/config.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAcvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAA2B,EAAwB,EAAE,EAAE,CAAC,EAAE,CAAC;AAqB5F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,aAAqB,kBAAkB,EACvC,UAAqC,EAAE;IAEvC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAExD,gFAAgF;IAChF,MAAM,MAAM,GAAG,MAAM,YAAY,CAAuB,UAAU,EAAE;QAClE,OAAO;QACP,UAAU;KACX,CAAC,CAAC;IAEH,mEAAmE;IACnE,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/B,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;QACnC,OAAO,MAAM,QAAQ,EAAE,CAAC;IAC1B,CAAC;IACD,sEAAsE;IACtE,OAAO,QAAa,CAAC;AACvB,CAAC;AAED,eAAe,kBAAkB,CAAC"}

package/dist/esm/options/schema.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/options/schema.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,KAAK,CAAC;AAEpB;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC;KAC7B,MAAM,CAAC;IACN,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC1B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACvC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACxC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACvC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;CACzC,CAAC;KACD,QAAQ,CAAC,gCAAgC,CAAC,CAAC"}

package/dist/esm/register.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/register.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB,EAAE,OAAgB;IACjE,gDAAgD;IAChD,IAAI,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,IAAI,CAAC,CAAC;IACpE,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,WAAW,CACzC,mEAAmE,CACpE,CAAC;QACF,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC;IAED,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAED,eAAe,gBAAgB,CAAC"}