@robota-sdk/agent-command 3.0.0-beta.100

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

@@ -0,0 +1,326 @@
+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 type { IProviderSetupInput } from '@robota-sdk/agent-framework';
+
+export type TProviderSetupType = string;
+export type TPromptInput = (
+  label: string,
+  masked?: boolean,
+  options?: { signal?: AbortSignal },
+) => Promise<string>;
+
+export interface IProviderSetupPromptStep extends IProviderSetupStepDefinition {
+  key: TProviderSetupField;
+}
+
+export interface IProviderSetupFlowState {
+  type: TProviderSetupType;
+  steps: readonly IProviderSetupPromptStep[];
+  setupHelpLinks: readonly IProviderSetupHelpLink[];
+  stepIndex: number;
+  values: Partial<Record<TProviderSetupField, string>>;
+  existingProfileNames: readonly string[];
+  profileName?: string;
+  setCurrent?: boolean;
+}
+
+export interface IProviderSetupFlowOptions {
+  includeEditOnlySteps?: boolean;
+  existingProfileNames?: readonly string[];
+  initialValues?: Partial<Record<TProviderSetupField, string>>;
+  profileName?: string;
+  setCurrent?: boolean;
+}
+
+export type TProviderSetupFlowSubmitResult =
+  | {
+      status: 'next';
+      state: IProviderSetupFlowState;
+    }
+  | {
+      status: 'complete';
+      input: IProviderSetupInput;
+    }
+  | {
+      status: 'error';
+      state: IProviderSetupFlowState;
+      message: string;
+    };
+
+export function createProviderSetupFlow(
+  type: TProviderSetupType,
+  providerDefinitions: readonly IProviderDefinition[],
+  options: IProviderSetupFlowOptions = {},
+): IProviderSetupFlowState {
+  const definition = getProviderSetupDefinition(type, providerDefinitions);
+  return {
+    type,
+    steps: applyProviderSetupInitialValues(
+      getProviderSetupSteps(definition).filter(
+        (step) => step.editOnly !== true || options.includeEditOnlySteps === true,
+      ),
+      options.initialValues,
+    ),
+    setupHelpLinks: definition.setupHelpLinks ?? [],
+    stepIndex: 0,
+    values: {},
+    existingProfileNames: options.existingProfileNames ?? [],
+    ...(options.profileName !== undefined ? { profileName: options.profileName } : {}),
+    ...(options.setCurrent !== undefined ? { setCurrent: options.setCurrent } : {}),
+  };
+}
+
+export function formatProviderSetupSelectionPrompt(
+  providerDefinitions: readonly IProviderDefinition[],
+): string {
+  if (providerDefinitions.length === 0) {
+    return '  No providers are available.';
+  }
+  const lines = [
+    '  Select provider:',
+    ...providerDefinitions.map(
+      (definition, index) => `    ${index + 1}. ${formatProviderSetupChoiceLabel(definition)}`,
+    ),
+    `  Provider [1-${providerDefinitions.length}] (default: 1): `,
+  ];
+  return lines.join('\n');
+}
+
+export function resolveProviderSetupSelection(
+  rawValue: string,
+  providerDefinitions: readonly IProviderDefinition[],
+): TProviderSetupType {
+  const value = rawValue.trim();
+  const selectedValue = value.length > 0 ? value : '1';
+  const index = parseProviderSelectionIndex(selectedValue);
+  if (index !== undefined) {
+    const definition = providerDefinitions[index];
+    if (definition !== undefined) {
+      return definition.type;
+    }
+    throw new Error(
+      `Provider selection ${selectedValue} is out of range. Currently supported: ${formatSupportedProviderTypes(providerDefinitions)}`,
+    );
+  }
+  const definition = findProviderDefinition(providerDefinitions, selectedValue);
+  if (definition === undefined) {
+    throw new Error(
+      `Unknown provider: ${selectedValue}. Currently supported: ${formatSupportedProviderTypes(providerDefinitions)}`,
+    );
+  }
+  return definition.type;
+}
+
+export function getProviderSetupStep(state: IProviderSetupFlowState): IProviderSetupPromptStep {
+  const step = state.steps[state.stepIndex];
+  if (step === undefined) {
+    throw new Error(`Provider setup step ${state.stepIndex} is out of range`);
+  }
+  return step;
+}
+
+export function submitProviderSetupValue(
+  state: IProviderSetupFlowState,
+  rawValue: string,
+): TProviderSetupFlowSubmitResult {
+  const step = getProviderSetupStep(state);
+  const value = rawValue.trim() || step.defaultValue || '';
+  const validationMessage = validateProviderSetupValue(step, value);
+  if (validationMessage !== undefined) {
+    return { status: 'error', state, message: validationMessage };
+  }
+
+  const nextState = {
+    ...state,
+    stepIndex: state.stepIndex + 1,
+    values: { ...state.values, [step.key]: value },
+  };
+  if (nextState.stepIndex < state.steps.length) {
+    return { status: 'next', state: nextState };
+  }
+  return { status: 'complete', input: buildProviderSetupInput(nextState) };
+}
+
+export async function runProviderSetupPromptFlow(
+  type: TProviderSetupType,
+  promptInput: TPromptInput,
+  providerDefinitions: readonly IProviderDefinition[],
+  options: IProviderSetupFlowOptions = {},
+): Promise<IProviderSetupInput> {
+  let state = createProviderSetupFlow(type, providerDefinitions, options);
+  const stepCount = state.steps.length;
+  while (state.stepIndex < stepCount) {
+    const step = getProviderSetupStep(state);
+    const value = await promptInput(
+      formatProviderSetupPromptLabel(step, state.setupHelpLinks),
+      step.masked === true,
+    );
+    const result = submitProviderSetupValue(state, value);
+    if (result.status === 'complete') {
+      return result.input;
+    }
+    if (result.status === 'error') {
+      throw new Error(result.message);
+    }
+    state = result.state;
+  }
+  throw new Error('Provider setup flow ended without completion');
+}
+
+export function formatProviderSetupPromptLabel(
+  step: IProviderSetupPromptStep,
+  setupHelpLinks: readonly IProviderSetupHelpLink[] = [],
+): string {
+  const suffix = step.defaultValue !== undefined ? ` (default: ${step.defaultValue})` : '';
+  const setupHelp = formatProviderSetupHelpLinks(setupHelpLinks);
+  const prefix = setupHelp.length > 0 ? `${setupHelp}\n` : '';
+  return `${prefix}  ${step.title}${suffix}: `;
+}
+
+const CATEGORY_BADGES: Record<string, string> = {
+  'cloud-paid': '[Cloud/Paid]',
+  'cloud-free': '[Cloud/Free]',
+  'local-free': '[Local/Free]',
+};
+
+export function formatProviderSetupChoiceLabel(definition: IProviderDefinition): string {
+  const badge =
+    definition.category !== undefined ? `${CATEGORY_BADGES[definition.category] ?? ''} ` : '';
+  const name =
+    definition.displayName !== undefined
+      ? `${definition.displayName} (${definition.type})`
+      : definition.type;
+  const label = `${badge}${name}`;
+  return definition.description !== undefined ? `${label} — ${definition.description}` : label;
+}
+
+export function formatProviderSetupHelpLinks(
+  setupHelpLinks: readonly IProviderSetupHelpLink[] = [],
+): string {
+  if (setupHelpLinks.length === 0) {
+    return '';
+  }
+  return setupHelpLinks
+    .map(
+      (link) =>
+        `  Setup help: ${formatProviderSetupHelpLinkKind(link.kind)}: ${link.label} - ${link.url}`,
+    )
+    .join('\n');
+}
+
+function parseProviderSelectionIndex(value: string): number | undefined {
+  if (!/^\d+$/.test(value)) {
+    return undefined;
+  }
+  return Number(value) - 1;
+}
+
+export function validateProviderSetupValue(
+  step: IProviderSetupPromptStep,
+  value: string,
+): string | undefined {
+  if (step.required === true && value.length === 0) {
+    return 'Required';
+  }
+  return undefined;
+}
+
+function getProviderSetupDefinition(
+  type: TProviderSetupType,
+  providerDefinitions: readonly IProviderDefinition[],
+): IProviderDefinition {
+  const definition = findProviderDefinition(providerDefinitions, type);
+  if (definition === undefined) {
+    throw new Error(
+      `Unknown provider: ${type}. Currently supported: ${formatSupportedProviderTypes(providerDefinitions)}`,
+    );
+  }
+  return definition;
+}
+
+function getProviderSetupSteps(definition: IProviderDefinition): IProviderSetupPromptStep[] {
+  if (definition.setupSteps !== undefined) {
+    return [...definition.setupSteps];
+  }
+
+  const steps: IProviderSetupPromptStep[] = [
+    {
+      key: 'model',
+      title: `${definition.type} model`,
+      defaultValue: definition.defaults?.model,
+      required: definition.defaults?.model === undefined,
+    },
+  ];
+  if (definition.defaults?.baseURL !== undefined) {
+    steps.unshift({
+      key: 'baseURL',
+      title: `${definition.type} base URL`,
+      defaultValue: definition.defaults.baseURL,
+    });
+  }
+  if (definition.requiresApiKey === true) {
+    steps.push({
+      key: 'apiKey',
+      title: `${definition.type} API key`,
+      defaultValue: definition.defaults?.apiKey,
+      required: definition.defaults?.apiKey === undefined,
+      masked: true,
+    });
+  }
+  return steps;
+}
+
+function formatProviderSetupHelpLinkKind(kind: IProviderSetupHelpLink['kind']): string {
+  if (kind === 'api-key') {
+    return 'API key';
+  }
+  if (kind === 'console') {
+    return 'Console';
+  }
+  return 'Official';
+}
+
+function applyProviderSetupInitialValues(
+  steps: readonly IProviderSetupPromptStep[],
+  initialValues: Partial<Record<TProviderSetupField, string>> | undefined,
+): IProviderSetupPromptStep[] {
+  if (initialValues === undefined) {
+    return [...steps];
+  }
+  return steps.map((step) => {
+    const initialValue = initialValues[step.key];
+    if (initialValue === undefined) {
+      return step;
+    }
+    return {
+      ...step,
+      defaultValue: initialValue,
+      required: false,
+    };
+  });
+}
+
+function buildProviderSetupInput(state: IProviderSetupFlowState): IProviderSetupInput {
+  const profile =
+    state.profileName ??
+    suggestProviderProfileName(
+      { type: state.type },
+      { existingProfileNames: state.existingProfileNames },
+    );
+  const apiKey = state.values.apiKey;
+  return {
+    profile,
+    type: state.type,
+    model: state.values.model,
+    ...(apiKey !== undefined && apiKey.length > 0 && { apiKey }),
+    ...(state.values.baseURL !== undefined && { baseURL: state.values.baseURL }),
+    setCurrent: state.setCurrent ?? true,
+  };
+}

package/src/provider/provider-startup.ts

@@ -0,0 +1,225 @@
+import {
+  checkSettingsDocument,
+  ProviderConfigError,
+  readMergedProviderSettings,
+  resolveEnvDefaultProvider,
+  applyProviderConfiguration,
+  resolveProviderSettingsWriteTarget,
+  WorkspaceAuthorityRequiredError,
+} from '@robota-sdk/agent-framework';
+
+import { runOnboardingBranch } from './provider-onboarding.js';
+import { createProviderSetupFlow } from './provider-setup-flow.js';
+import {
+  hasProviderConnectionMethods,
+  runProviderConnectionSetup,
+} from './provider-connection-setup.js';
+import { createProviderPromptInteraction } from './provider-prompt-interaction.js';
+import {
+  formatProviderSetupSelectionPrompt,
+  resolveProviderSetupSelection,
+  runProviderSetupPromptFlow,
+  type TPromptInput,
+} from './provider-setup-flow.js';
+
+import type { IProviderDefinition, IUserInteraction } from '@robota-sdk/agent-core';
+import type { ITerminalOutput } from '@robota-sdk/agent-core';
+import type {
+  ISettingsDocumentStore,
+  TSettingsScope,
+  TSettingsSource,
+  IProviderConnectionHost,
+  IOrgPolicy,
+  TProviderSettingsDocument,
+} from '@robota-sdk/agent-framework';
+
+export interface IProviderStartupContext {
+  provider?: string;
+  settingsScope?: TSettingsScope;
+  settingsSources: readonly TSettingsSource[];
+  settingsStores: readonly ISettingsDocumentStore[];
+  /** Selected host snapshot for configure-time credential reference checks. */
+  env?: Record<string, string | undefined>;
+  connectionHost?: IProviderConnectionHost;
+  orgPolicy?: IOrgPolicy;
+  interaction?: IUserInteraction;
+}
+
+export interface IEnsureProviderConfigOptions {
+  formatError: (defs: readonly IProviderDefinition[]) => string;
+  isInteractive?: () => boolean;
+  /** Environment map for env-default synthesis (test seam, default: process.env). */
+  env?: Record<string, string | undefined>;
+}
+
+export async function runProviderStartupSetup(
+  cwd: string,
+  ctx: IProviderStartupContext,
+  promptInput: TPromptInput,
+  terminal: ITerminalOutput,
+  providerDefinitions: readonly IProviderDefinition[],
+): Promise<void> {
+  const onboarding = await runOnboardingBranch(
+    promptInput,
+    terminal,
+    providerDefinitions.some((definition) => definition.type === 'openrouter'),
+  );
+  const access = resolveSettingsAccess(ctx);
+  const existingProfileNames = Object.keys(
+    readMergedProviderSettings(access.sources).providers ?? {},
+  );
+  const settingsStore = selectSettingsStore(access.stores, ctx.settingsScope);
+
+  let type: string;
+  if (onboarding.preselectedType !== undefined) {
+    type = onboarding.preselectedType;
+  } else {
+    const providerChoice = await promptInput(
+      formatProviderSetupSelectionPrompt(providerDefinitions),
+    );
+    type = resolveProviderSetupSelection(providerChoice, providerDefinitions);
+  }
+
+  const setupOptions = {
+    providerDefinitions,
+    env: ctx.env,
+    connectionHost: ctx.connectionHost,
+    orgPolicy: ctx.orgPolicy,
+    settings: {
+      readMergedSettings: () => readMergedProviderSettings(access.sources),
+      readTargetSettings: () => settingsStore.read() as TProviderSettingsDocument,
+      writeTargetSettings: (settings: TProviderSettingsDocument) => settingsStore.write(settings),
+    },
+  };
+  if (hasProviderConnectionMethods(type, setupOptions)) {
+    const definitions =
+      ctx.interaction === undefined
+        ? providerDefinitions.map((definition) => ({
+            ...definition,
+            connectionMethods: definition.connectionMethods?.filter(
+              (method) => method !== 'browser',
+            ),
+          }))
+        : providerDefinitions;
+    if (ctx.interaction === undefined)
+      terminal.writeLine(
+        'Browser connection is unavailable here. API key setup remains available.',
+      );
+    const result = await runProviderConnectionSetup(
+      ctx.interaction ?? createProviderPromptInteraction(promptInput),
+      createProviderSetupFlow(type, definitions, { existingProfileNames }),
+      { ...setupOptions, providerDefinitions: definitions },
+      false,
+    );
+    if (!result.success) throw new ProviderConfigError(result.message);
+    if (result.hostActions === undefined) return;
+  } else {
+    const input = await runProviderSetupPromptFlow(type, promptInput, providerDefinitions, {
+      existingProfileNames,
+    });
+    applyProviderConfiguration(settingsStore, input, { providerDefinitions, env: ctx.env });
+  }
+  const language = await promptInput('  Response language (ko/en/ja/zh, default: en): ');
+  if (language) {
+    const settings = settingsStore.read();
+    settings.language = language;
+    settingsStore.write(settings);
+  }
+  terminal.writeLine(`\n  Config saved to ${settingsStore.displayName}\n`);
+}
+
+export async function ensureProviderConfig(
+  cwd: string,
+  ctx: IProviderStartupContext,
+  promptInput: TPromptInput,
+  terminal: ITerminalOutput,
+  providerDefinitions: readonly IProviderDefinition[],
+  options: IEnsureProviderConfigOptions,
+): Promise<void> {
+  const access = resolveSettingsAccess(ctx);
+  const merged = readMergedProviderSettings(access.sources);
+  const selectedSettings =
+    ctx.provider !== undefined ? { ...merged, currentProvider: ctx.provider } : merged;
+  if (
+    checkSettingsDocument(selectedSettings, providerDefinitions, ctx.env ?? options.env) === 'valid'
+  ) {
+    return;
+  }
+  // Zero-config startup: a recognized provider env key with complete definition defaults
+  // makes setup unnecessary — resolution will synthesize an env-default config.
+  if (
+    ctx.provider === undefined &&
+    resolveEnvDefaultProvider(providerDefinitions, options.env) !== undefined
+  ) {
+    return;
+  }
+  const checkInteractive = options.isInteractive ?? (() => false);
+  if (!checkInteractive()) {
+    throw new ProviderConfigError(options.formatError(providerDefinitions));
+  }
+  await runProviderStartupSetup(
+    cwd,
+    selectStartupContext({ ...ctx, env: ctx.env ?? options.env }, access.stores),
+    promptInput,
+    terminal,
+    providerDefinitions,
+  );
+  const updated = readMergedProviderSettings(access.sources);
+  const updatedSettings =
+    ctx.provider !== undefined ? { ...updated, currentProvider: ctx.provider } : updated;
+  if (
+    checkSettingsDocument(updatedSettings, providerDefinitions, ctx.env ?? options.env) !== 'valid'
+  ) {
+    throw new ProviderConfigError(options.formatError(providerDefinitions));
+  }
+}
+
+function resolveSettingsAccess(ctx: IProviderStartupContext): {
+  sources: readonly TSettingsSource[];
+  stores: readonly ISettingsDocumentStore[];
+} {
+  if (ctx.settingsSources === undefined || ctx.settingsStores === undefined) {
+    throw new Error('Provider startup requires host settings sources and stores.');
+  }
+  return {
+    sources: ctx.settingsSources,
+    stores: ctx.settingsStores,
+  };
+}
+
+function selectSettingsStore(
+  stores: readonly ISettingsDocumentStore[],
+  scope: TSettingsScope | undefined,
+): ISettingsDocumentStore {
+  if (scope === undefined) return resolveProviderSettingsWriteTarget(stores);
+  const targetScope = scope === 'user' ? 'user' : 'project-local';
+  const store = stores.findLast((candidate) => candidate.scope === targetScope);
+  if (store !== undefined) return store;
+  throw new WorkspaceAuthorityRequiredError(
+    `No authorized ${targetScope} settings store is available.`,
+  );
+}
+
+function selectStartupContext(
+  ctx: IProviderStartupContext,
+  stores: readonly ISettingsDocumentStore[],
+): IProviderStartupContext {
+  if (ctx.settingsScope !== undefined || ctx.provider !== undefined) return ctx;
+  const currentProviderStore = findHighestPriorityCurrentProviderStore(stores);
+  if (currentProviderStore?.kind === 'project') return { ...ctx, settingsScope: 'project-local' };
+  return ctx;
+}
+
+function findHighestPriorityCurrentProviderStore(
+  stores: readonly ISettingsDocumentStore[],
+): ISettingsDocumentStore | undefined {
+  for (let index = stores.length - 1; index >= 0; index -= 1) {
+    const store = stores[index];
+    if (store === undefined) continue;
+    const settings = store.read();
+    if (typeof settings.currentProvider === 'string') {
+      return store;
+    }
+  }
+  return undefined;
+}

package/src/remote-control/__tests__/remote-control-command-module.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+import { createRemoteControlCommandModule } from '../remote-control-command-module.js';
+
+describe('createRemoteControlCommandModule metadata', () => {
+  it('keeps palette metadata aligned with the executable command and status as the safe default', async () => {
+    const module = createRemoteControlCommandModule();
+    const palette = module.commandSources?.[0]?.getCommands()[0];
+    const executable = module.systemCommands?.[0];
+
+    expect(palette).toBeDefined();
+    expect(executable).toBeDefined();
+    expect(palette?.argumentHint).toBe('[enable|stop|status|devices|revoke <device-id>]');
+    expect(palette?.description).toBe(executable?.description);
+    expect(palette?.modelInvocable).toBe(executable?.modelInvocable);
+    expect(palette?.argumentHint).toBe(executable?.argumentHint);
+    expect(palette?.userInvocable).toBe(executable?.userInvocable);
+    expect(palette?.subcommands?.map(({ name }) => name)).toEqual([
+      'status',
+      'devices',
+      'enable',
+      'stop',
+      'revoke',
+    ]);
+    expect(palette?.subcommands).toEqual(executable?.subcommands);
+    expect(executable?.requiresPermission).toBe(false);
+    expect(executable?.modelInvocable).toBe(false);
+    expect(executable?.userInvocable).toBe(true);
+
+    const result = await executable!.execute(createTestCommandHost(), 'status');
+    expect(result.message).toContain('not available');
+    expect(result.hostActions).toBeUndefined();
+  });
+});