@robota-sdk/agent-command 3.0.0-beta.64 → 3.0.0-beta.66

package/src/plugins/default-plugin-command-adapter.ts

@@ -0,0 +1,164 @@
+import { execSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  BundlePluginInstaller,
+  BundlePluginLoader,
+  MarketplaceClient,
+  PluginSettingsStore,
+} from '@robota-sdk/agent-framework';
+
+import type {
+  ICommandAvailablePlugin,
+  ICommandInstalledPlugin,
+  ICommandMarketplaceSource,
+  ICommandPluginAdapter,
+  IMarketplaceManifest,
+  TPluginInstallScope,
+} from '@robota-sdk/agent-framework';
+
+interface IPluginServices {
+  cwd: string;
+  marketplace: MarketplaceClient;
+  installer: BundlePluginInstaller;
+  loader: BundlePluginLoader;
+  settingsStore: PluginSettingsStore;
+}
+
+function createPluginServices(cwd: string): IPluginServices {
+  const home = homedir();
+  const pluginsDir = join(home, '.robota', 'plugins');
+  const userSettingsPath = join(home, '.robota', 'settings.json');
+
+  const exec = (command: string, options: { timeout: number; stdio?: string }): Buffer =>
+    execSync(command, {
+      timeout: options.timeout,
+      stdio: (options.stdio ?? 'pipe') as 'pipe' | 'inherit' | 'ignore',
+    });
+
+  const settingsStore = new PluginSettingsStore(userSettingsPath);
+  const marketplace = new MarketplaceClient({ pluginsDir, exec });
+  const installer = new BundlePluginInstaller({
+    pluginsDir,
+    settingsStore,
+    marketplaceClient: marketplace,
+    exec,
+  });
+  const loader = new BundlePluginLoader(pluginsDir);
+
+  return {
+    cwd,
+    marketplace,
+    installer,
+    loader,
+    settingsStore,
+  };
+}
+
+async function listInstalledPlugins(
+  services: IPluginServices,
+): Promise<readonly ICommandInstalledPlugin[]> {
+  const plugins = await services.loader.loadAll();
+  const enabledMap = services.settingsStore.getEnabledPlugins();
+  return plugins.map((plugin) => {
+    const parts = plugin.pluginDir.split('/');
+    const cacheIdx = parts.indexOf('cache');
+    const marketplaceName = cacheIdx >= 0 ? (parts[cacheIdx + 1] ?? '') : '';
+    const fullId = marketplaceName
+      ? `${plugin.manifest.name}@${marketplaceName}`
+      : plugin.manifest.name;
+    return {
+      name: fullId,
+      description: plugin.manifest.description,
+      enabled: enabledMap[fullId] !== false && enabledMap[plugin.manifest.name] !== false,
+    };
+  });
+}
+
+async function listAvailablePlugins(
+  services: IPluginServices,
+  marketplaceName: string,
+): Promise<readonly ICommandAvailablePlugin[]> {
+  let manifest: IMarketplaceManifest;
+  try {
+    manifest = services.marketplace.fetchManifest(marketplaceName);
+  } catch {
+    // allow-fallback: marketplace manifest fetch failure is non-fatal — return empty list
+    return [];
+  }
+  const installed = services.installer.getInstalledPlugins();
+  const installedNames = new Set(Object.values(installed).map((record) => record.pluginName));
+  return manifest.plugins.map((plugin) => ({
+    name: plugin.name,
+    description: plugin.description,
+    installed: installedNames.has(plugin.name),
+  }));
+}
+
+async function installPlugin(
+  services: IPluginServices,
+  pluginId: string,
+  scope?: TPluginInstallScope,
+): Promise<void> {
+  const [name, marketplaceName] = pluginId.split('@');
+  if (!name || !marketplaceName) {
+    throw new Error('Plugin ID must be in format: name@marketplace');
+  }
+  if (scope === 'project') {
+    const projectPluginsDir = join(services.cwd, '.robota', 'plugins');
+    const projectExec = (command: string, options: { timeout: number; stdio?: string }): Buffer =>
+      execSync(command, {
+        timeout: options.timeout,
+        stdio: (options.stdio ?? 'pipe') as 'pipe' | 'inherit' | 'ignore',
+      });
+    const projectInstaller = new BundlePluginInstaller({
+      pluginsDir: projectPluginsDir,
+      settingsStore: services.settingsStore,
+      marketplaceClient: services.marketplace,
+      exec: projectExec,
+    });
+    await projectInstaller.install(name, marketplaceName);
+    return;
+  }
+  await services.installer.install(name, marketplaceName);
+}
+
+async function removeMarketplace(services: IPluginServices, name: string): Promise<void> {
+  const installedFromMarketplace = services.installer.getPluginsByMarketplace(name);
+  for (const record of installedFromMarketplace) {
+    await services.installer.uninstall(`${record.pluginName}@${record.marketplace}`);
+  }
+  services.marketplace.removeMarketplace(name);
+}
+
+function listMarketplaces(services: IPluginServices): readonly ICommandMarketplaceSource[] {
+  return services.marketplace.listMarketplaces().map((marketplaceEntry) => ({
+    name: marketplaceEntry.name,
+    type: marketplaceEntry.source.type,
+  }));
+}
+
+export function createDefaultPluginCommandAdapter(cwd: string): ICommandPluginAdapter {
+  const services = createPluginServices(cwd);
+  return {
+    listInstalled: () => listInstalledPlugins(services),
+    listAvailablePlugins: (marketplaceName) => listAvailablePlugins(services, marketplaceName),
+    install: (pluginId, scope) => installPlugin(services, pluginId, scope),
+    uninstall: async (pluginId) => services.installer.uninstall(pluginId),
+    enable: async (pluginId) => services.installer.enable(pluginId),
+    disable: async (pluginId) => services.installer.disable(pluginId),
+    marketplaceAdd: async (source) => {
+      if (source.includes('/') && !source.includes(':')) {
+        return services.marketplace.addMarketplace({ type: 'github', repo: source });
+      }
+      return services.marketplace.addMarketplace({ type: 'git', url: source });
+    },
+    marketplaceRemove: (name) => removeMarketplace(services, name),
+    marketplaceUpdate: async (name) => services.marketplace.updateMarketplace(name),
+    marketplaceList: async () => listMarketplaces(services),
+    reloadPlugins: async () => ({
+      loadedPluginCount: (await services.loader.loadAll()).length,
+    }),
+  };
+}

package/src/plugins/default-plugin-command-source-loader.ts

@@ -0,0 +1,31 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { BundlePluginLoader, PluginCommandSource } from '@robota-sdk/agent-framework';
+
+import type { CommandRegistry } from '@robota-sdk/agent-framework';
+
+const PLUGIN_SOURCE_NAME = 'plugin';
+
+function getHomeDir(): string {
+  return process.env.HOME ?? homedir();
+}
+
+export function reloadPluginCommandSource(registry: CommandRegistry): number {
+  const pluginsDir = join(getHomeDir(), '.robota', 'plugins');
+  const loader = new BundlePluginLoader(pluginsDir);
+  try {
+    // allow-fallback: plugin load failure is non-fatal — clear source and return empty
+    const plugins = loader.loadPluginsSync();
+    if (plugins.length === 0) {
+      registry.replaceSource(PLUGIN_SOURCE_NAME);
+      return 0;
+    }
+    registry.replaceSource(PLUGIN_SOURCE_NAME, new PluginCommandSource(plugins));
+    return plugins.length;
+  } catch {
+    // allow-fallback: plugin load failure is non-fatal — clear source and return empty
+    registry.replaceSource(PLUGIN_SOURCE_NAME);
+    return 0;
+  }
+}

package/src/provider/__tests__/provider-setup-flow.test.ts

@@ -1,15 +1,26 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import type { IProviderDefinition } from '@robota-sdk/agent-core';
 import {
   createProviderSetupFlow,
   formatProviderSetupHelpLinks,
   formatProviderSetupPromptLabel,
+  formatProviderSetupSelectionPrompt,
   getProviderSetupStep,
+  resolveProviderSetupSelection,
+  runProviderSetupPromptFlow,
+  submitProviderSetupValue,
 } from '../provider-setup-flow.js';
 
+const openaiDefaults = {
+  apiKey: '$ENV:OPENAI_API_KEY',
+};
+
 const providerDefinitions: readonly IProviderDefinition[] = [
   {
     type: 'openai',
+    displayName: 'OpenAI',
+    description: 'Use OpenAI Responses API',
+    defaults: openaiDefaults,
     setupHelpLinks: [
       {
         kind: 'api-key',
@@ -17,7 +28,33 @@ const providerDefinitions: readonly IProviderDefinition[] = [
         url: 'https://platform.openai.com/api-keys',
       },
     ],
-    setupSteps: [{ key: 'apiKey', title: 'OpenAI API key', masked: true }],
+    setupSteps: [
+      {
+        key: 'model',
+        title: 'OpenAI model',
+        required: true,
+      },
+      {
+        key: 'apiKey',
+        title: 'OpenAI API key',
+        defaultValue: openaiDefaults.apiKey,
+        masked: true,
+      },
+    ],
+    requiresApiKey: true,
+    createProvider: () => {
+      throw new Error('not used');
+    },
+  },
+  {
+    type: 'anthropic',
+    displayName: 'Anthropic',
+    description: 'Use Claude models through Anthropic',
+    defaults: { model: 'claude-sonnet-4-6' },
+    setupSteps: [
+      { key: 'apiKey', title: 'Anthropic API key', required: true, masked: true },
+      { key: 'model', title: 'Anthropic model', defaultValue: 'claude-sonnet-4-6' },
+    ],
     requiresApiKey: true,
     createProvider: () => {
       throw new Error('not used');
@@ -36,8 +73,172 @@ describe('provider setup flow', () => {
     expect(formatProviderSetupPromptLabel(getProviderSetupStep(state), state.setupHelpLinks)).toBe(
       [
         '  Setup help: API key: OpenAI API keys - https://platform.openai.com/api-keys',
-        '  OpenAI API key: ',
+        '  OpenAI model: ',
       ].join('\n'),
     );
   });
+
+  it('formats provider selection prompts from injected provider definitions', () => {
+    expect(formatProviderSetupSelectionPrompt(providerDefinitions)).toBe(
+      [
+        '  Select provider:',
+        '    1. OpenAI (openai) - Use OpenAI Responses API',
+        '    2. Anthropic (anthropic) - Use Claude models through Anthropic',
+        '  Provider [1-2] (default: 1): ',
+      ].join('\n'),
+    );
+  });
+
+  it('resolves provider selection by index or type without provider-specific branches', () => {
+    expect(resolveProviderSetupSelection('2', providerDefinitions)).toBe('anthropic');
+    expect(resolveProviderSetupSelection('openai', providerDefinitions)).toBe('openai');
+    expect(resolveProviderSetupSelection('', providerDefinitions)).toBe('openai');
+    expect(() => resolveProviderSetupSelection('gemma', providerDefinitions)).toThrow(
+      'Unknown provider: gemma',
+    );
+  });
+
+  it('builds OpenAI setup input from model and default API key submissions', () => {
+    let state = createProviderSetupFlow('openai', providerDefinitions);
+    expect(state.setupHelpLinks).toEqual([
+      {
+        kind: 'api-key',
+        label: 'OpenAI API keys',
+        url: 'https://platform.openai.com/api-keys',
+      },
+    ]);
+    expect(getProviderSetupStep(state)).toMatchObject({
+      key: 'model',
+      required: true,
+    });
+
+    const emptyModelResult = submitProviderSetupValue(state, '');
+    expect(emptyModelResult.status).toBe('error');
+
+    const modelResult = submitProviderSetupValue(state, 'gpt-4o');
+    expect(modelResult.status).toBe('next');
+    if (modelResult.status !== 'next') throw new Error('expected next');
+    state = modelResult.state;
+
+    const apiKeyResult = submitProviderSetupValue(state, '');
+    expect(apiKeyResult).toEqual({
+      status: 'complete',
+      input: {
+        profile: 'openai',
+        type: 'openai',
+        model: 'gpt-4o',
+        apiKey: openaiDefaults.apiKey,
+        setCurrent: true,
+      },
+    });
+  });
+
+  it('keeps Anthropic API key validation outside the TUI component', () => {
+    const state = createProviderSetupFlow('anthropic', providerDefinitions);
+
+    expect(submitProviderSetupValue(state, '')).toEqual({
+      status: 'error',
+      state,
+      message: 'Required',
+    });
+  });
+
+  it('suggests unique profile names from type and disambiguates duplicates', () => {
+    let state = createProviderSetupFlow('anthropic', providerDefinitions, {
+      existingProfileNames: ['anthropic'],
+    });
+    const apiKeyResult = submitProviderSetupValue(state, 'sk-ant-test');
+    expect(apiKeyResult.status).toBe('next');
+    if (apiKeyResult.status !== 'next') throw new Error('expected next');
+    state = apiKeyResult.state;
+
+    const modelResult = submitProviderSetupValue(state, '');
+
+    expect(modelResult).toEqual({
+      status: 'complete',
+      input: {
+        profile: 'anthropic-2',
+        type: 'anthropic',
+        model: 'claude-sonnet-4-6',
+        apiKey: 'sk-ant-test',
+        setCurrent: true,
+      },
+    });
+  });
+
+  it('builds edit input for a fixed profile from current profile values', () => {
+    let state = createProviderSetupFlow('anthropic', providerDefinitions, {
+      profileName: 'work-claude',
+      setCurrent: false,
+      initialValues: {
+        apiKey: '$ENV:ANTHROPIC_API_KEY',
+        model: 'claude-sonnet-4-6',
+      },
+    });
+
+    expect(getProviderSetupStep(state)).toMatchObject({
+      key: 'apiKey',
+      defaultValue: '$ENV:ANTHROPIC_API_KEY',
+      required: false,
+    });
+
+    const apiKeyResult = submitProviderSetupValue(state, '');
+    expect(apiKeyResult.status).toBe('next');
+    if (apiKeyResult.status !== 'next') throw new Error('expected next');
+    state = apiKeyResult.state;
+
+    const modelResult = submitProviderSetupValue(state, 'claude-opus-4-5');
+
+    expect(modelResult).toEqual({
+      status: 'complete',
+      input: {
+        profile: 'work-claude',
+        type: 'anthropic',
+        model: 'claude-opus-4-5',
+        apiKey: '$ENV:ANTHROPIC_API_KEY',
+        setCurrent: false,
+      },
+    });
+  });
+
+  it('runs prompt input with masked API key steps', async () => {
+    const promptInput = vi.fn(async (label: string) => (label.includes('model') ? 'gpt-4o' : ''));
+
+    const input = await runProviderSetupPromptFlow('openai', promptInput, providerDefinitions);
+
+    expect(input.model).toBe('gpt-4o');
+    expect(input.profile).toBe('openai');
+    expect(input.apiKey).toBe(openaiDefaults.apiKey);
+    expect(promptInput).toHaveBeenNthCalledWith(
+      1,
+      formatProviderSetupPromptLabel(
+        {
+          key: 'model',
+          title: 'OpenAI model',
+          required: true,
+        },
+        providerDefinitions[0]?.setupHelpLinks,
+      ),
+      false,
+    );
+    expect(promptInput).toHaveBeenNthCalledWith(
+      2,
+      formatProviderSetupPromptLabel(
+        {
+          key: 'apiKey',
+          title: 'OpenAI API key',
+          defaultValue: openaiDefaults.apiKey,
+          masked: true,
+        },
+        providerDefinitions[0]?.setupHelpLinks,
+      ),
+      true,
+    );
+  });
+
+  it('formats provider setup help links for generic setup descriptions', () => {
+    expect(formatProviderSetupHelpLinks(providerDefinitions[0]?.setupHelpLinks)).toBe(
+      '  Setup help: API key: OpenAI API keys - https://platform.openai.com/api-keys',
+    );
+  });
 });

package/src/provider/index.ts

@@ -28,3 +28,5 @@ export type {
   IProviderCommandModuleOptions,
   IProviderCommandSettingsAdapter,
 } from '@robota-sdk/agent-framework';
+export { ensureProviderConfig, runProviderStartupSetup } from './provider-startup.js';
+export type { IProviderStartupContext, IEnsureProviderConfigOptions } from './provider-startup.js';

package/src/provider/provider-command-execution.ts

@@ -1,14 +1,17 @@
 import { findProviderDefinition, formatSupportedProviderTypes } from '@robota-sdk/agent-core';
+import { testProviderProfileCommand } from '@robota-sdk/agent-framework';
+
+import { buildProviderSwitch } from './provider-command-profile-operations.js';
+import { createProviderProfileSelectionInteraction } from './provider-command-profile.js';
+import { createSetupFlow, createProviderSetupInteraction } from './provider-command-setup.js';
+import { formatProviderSetupChoiceLabel } from './provider-setup-flow.js';
+
 import type {
+  ICommandInteraction,
   ICommandResult,
   IProviderCommandModuleOptions,
   IProviderProfileSettings,
 } from '@robota-sdk/agent-framework';
-import { testProviderProfileCommand } from '@robota-sdk/agent-framework';
-import { formatProviderSetupChoiceLabel } from './provider-setup-flow.js';
-import { createSetupFlow, createProviderSetupInteraction } from './provider-command-setup.js';
-import { buildProviderSwitch } from './provider-command-profile-operations.js';
-import { createProviderProfileSelectionInteraction } from './provider-command-profile.js';
 
 export async function executeProviderCommand(
   args: string,
@@ -126,7 +129,9 @@ function buildProviderSetup(
   };
 }
 
-function createProviderSelectionInteraction(options: IProviderCommandModuleOptions) {
+function createProviderSelectionInteraction(
+  options: IProviderCommandModuleOptions,
+): ICommandInteraction {
   return {
     prompt: {
       kind: 'choice' as const,

package/src/provider/provider-command-module.ts

@@ -1,3 +1,5 @@
+import { executeProviderCommand } from './provider-command-execution.js';
+
 import type {
   ICommand,
   ICommandModule as TCommandModule,
@@ -6,7 +8,6 @@ import type {
   IProviderCommandSettingsAdapter,
   ISystemCommand as TSystemCommand,
 } from '@robota-sdk/agent-framework';
-import { executeProviderCommand } from './provider-command-execution.js';
 export type { IProviderCommandModuleOptions, IProviderCommandSettingsAdapter };
 
 function buildProviderSubcommands(): ICommand[] {

package/src/provider/provider-command-profile-lifecycle.ts

@@ -1,15 +1,17 @@
-import type {
-  ICommandInteraction,
-  ICommandResult,
-  IProviderCommandModuleOptions,
-} from '@robota-sdk/agent-framework';
 import {
   deleteProviderProfile,
   sanitizeProviderProfileName,
   upsertProviderProfile,
 } from '@robota-sdk/agent-framework';
+
 import { formatProviderChoiceLabel } from './provider-command-profile-operations.js';
 
+import type {
+  ICommandInteraction,
+  ICommandResult,
+  IProviderCommandModuleOptions,
+} from '@robota-sdk/agent-framework';
+
 const YES = 'yes';
 const MAX_DUPLICATE_PROFILE_SUFFIX = 1000;
 const PROVIDER_RESTART_EFFECT = {
@@ -191,7 +193,10 @@ function completeActiveProviderDelete(
   };
 }
 
-function suggestDuplicateProfileName(profileName: string, existingProfileNames: readonly string[]) {
+function suggestDuplicateProfileName(
+  profileName: string,
+  existingProfileNames: readonly string[],
+): string {
   const base = sanitizeProviderProfileName(`${profileName}-copy`) ?? 'provider-copy';
   if (!existingProfileNames.includes(base)) {
     return base;

package/src/provider/provider-command-profile-operations.ts

@@ -1,21 +1,23 @@
-import type {
-  ICommandInteraction,
-  ICommandResult,
-  IProviderCommandModuleOptions,
-  IProviderProfileSettings,
-  IProviderSetupInput,
-} from '@robota-sdk/agent-framework';
 import {
   buildProviderSetupPatch,
   setCurrentProvider,
   upsertProviderProfile,
 } from '@robota-sdk/agent-framework';
-import { createProviderSetupFlow, submitProviderSetupValue } from './provider-setup-flow.js';
-import type { IProviderSetupFlowState } from './provider-setup-flow.js';
+
 import {
   createProviderSetupInteraction,
   toProviderSetupStepPrompt,
 } from './provider-command-setup.js';
+import { createProviderSetupFlow, submitProviderSetupValue } from './provider-setup-flow.js';
+
+import type { IProviderSetupFlowState } from './provider-setup-flow.js';
+import type {
+  ICommandInteraction,
+  ICommandResult,
+  IProviderCommandModuleOptions,
+  IProviderProfileSettings,
+  IProviderSetupInput,
+} from '@robota-sdk/agent-framework';
 
 const YES = 'yes';
 const PROVIDER_RESTART_EFFECT = {

package/src/provider/provider-command-profile.ts

@@ -1,19 +1,21 @@
-import type {
-  ICommandInteraction,
-  ICommandResult,
-  IProviderCommandModuleOptions,
-  IProviderProfileSettings,
-} from '@robota-sdk/agent-framework';
 import { testProviderProfileCommand } from '@robota-sdk/agent-framework';
+
+import {
+  buildProviderDelete,
+  buildProviderDuplicate,
+} from './provider-command-profile-lifecycle.js';
 import {
   buildProviderEdit,
   buildProviderSwitch,
   formatProviderChoiceLabel,
 } from './provider-command-profile-operations.js';
-import {
-  buildProviderDelete,
-  buildProviderDuplicate,
-} from './provider-command-profile-lifecycle.js';
+
+import type {
+  ICommandInteraction,
+  ICommandResult,
+  IProviderCommandModuleOptions,
+  IProviderProfileSettings,
+} from '@robota-sdk/agent-framework';
 
 const ACTION_SWITCH = 'switch';
 const ACTION_EDIT = 'edit';

package/src/provider/provider-command-setup.ts

@@ -1,12 +1,5 @@
-import type {
-  ICommandInteraction,
-  ICommandResult,
-  IProviderCommandModuleOptions,
-  IProviderSetupInput,
-  TCommandInteractionPrompt,
-} from '@robota-sdk/agent-framework';
 import { buildProviderSetupPatch, mergeProviderPatch } from '@robota-sdk/agent-framework';
-import type { IProviderSetupFlowState } from './provider-setup-flow.js';
+
 import {
   createProviderSetupFlow,
   formatProviderSetupHelpLinks,
@@ -15,6 +8,15 @@ import {
   validateProviderSetupValue,
 } from './provider-setup-flow.js';
 
+import type { IProviderSetupFlowState } from './provider-setup-flow.js';
+import type {
+  ICommandInteraction,
+  ICommandResult,
+  IProviderCommandModuleOptions,
+  IProviderSetupInput,
+  TCommandInteractionPrompt,
+} from '@robota-sdk/agent-framework';
+
 const PROVIDER_RESTART_EFFECT = {
   type: 'session-restart-requested',
   reason: 'other',

package/src/provider/provider-setup-flow.ts

@@ -1,12 +1,13 @@
+import { findProviderDefinition, formatSupportedProviderTypes } from '@robota-sdk/agent-core';
+import { suggestProviderProfileName } from '@robota-sdk/agent-framework';
+
 import type {
   IProviderDefinition,
   IProviderSetupHelpLink,
   IProviderSetupStepDefinition,
   TProviderSetupField,
 } from '@robota-sdk/agent-core';
-import { findProviderDefinition, formatSupportedProviderTypes } from '@robota-sdk/agent-core';
 import type { IProviderSetupInput } from '@robota-sdk/agent-framework';
-import { suggestProviderProfileName } from '@robota-sdk/agent-framework';
 
 export type TProviderSetupType = string;
 export type TPromptInput = (label: string, masked?: boolean) => Promise<string>;