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

package/src/default/__tests__/org-policy-forwarding.test.ts

@@ -0,0 +1,106 @@
+/**
+ * CLI-083 (issue #2287) — the default command modules forward the org policy.
+ *
+ * `createDefaultCommandModules` used to accept `orgPolicy` and hand it to the provider command
+ * module; `92596bc6f` removed the parameter along with its only caller. The consumer never changed:
+ * `provider-command-profile-operations.ts` still destructures `orgPolicy` and enforces
+ * `allowedProviders` on it.
+ *
+ * `org-policy.test.ts` already covers that enforcement — by constructing the provider module
+ * DIRECTLY with a policy. That test is green whether or not anything upstream forwards one, which
+ * is why the cut survived three months. This drives the same enforcement through the factory that
+ * lost the parameter, so it fails exactly when the forwarding is missing.
+ *
+ * There is deliberately no "the factory accepts an orgPolicy" case. At runtime JavaScript accepts an
+ * undeclared extra property silently, so that assertion passes whether or not the parameter exists —
+ * it was written, it passed against the broken tree, and it proved nothing. The signature is the
+ * type checker's job.
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, describe, expect, it } from 'vitest';
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+import { createDefaultCommandModules } from '../default-command-modules.js';
+
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import type {
+  IOrgPolicy,
+  IProviderCommandSettingsAdapter,
+  TProviderSettingsDocument,
+} from '@robota-sdk/agent-framework';
+
+const providerDefinitions: readonly IProviderDefinition[] = ['anthropic', 'openai'].map((type) => ({
+  type,
+  displayName: type,
+  defaults: { model: 'm', apiKey: `$ENV:${type.toUpperCase()}_API_KEY` },
+  setupSteps: [],
+  requiresApiKey: true,
+  createProvider: () => {
+    throw new Error('not used');
+  },
+}));
+
+const SETTINGS: TProviderSettingsDocument = {
+  currentProvider: 'anthropic',
+  providers: {
+    anthropic: { type: 'anthropic', model: 'm' },
+    openai: { type: 'openai', model: 'm' },
+  },
+};
+
+const adapter: IProviderCommandSettingsAdapter = {
+  readMergedSettings: () => SETTINGS,
+  readTargetSettings: () => ({}),
+  writeTargetSettings: () => undefined,
+};
+
+/** User-local storage lives in a private per-run directory, never a fixed name under /tmp. */
+const USER_LOCAL_STORAGE_ROOT = mkdtempSync(join(tmpdir(), 'agent-test-test-'));
+afterAll(() => rmSync(USER_LOCAL_STORAGE_ROOT, { recursive: true, force: true }));
+
+const POLICY: IOrgPolicy = { allowedProviders: ['anthropic'], adminContact: 'ops@example.com' };
+
+/** Build the provider executor the way the PRODUCT does — through the default-modules factory. */
+function executorThroughFactory(orgPolicy?: IOrgPolicy): SystemCommandExecutor {
+  const { modules } = createDefaultCommandModules({
+    cwd: '/work',
+    userLocalStorageRoot: USER_LOCAL_STORAGE_ROOT,
+    providerDefinitions,
+    providerSettingsAdapter: adapter,
+    ...(orgPolicy === undefined ? {} : { orgPolicy }),
+  });
+  const provider = modules.find((module) => module.name === 'agent-command-provider');
+  if (provider === undefined) throw new Error('the provider command module was not built');
+  return new SystemCommandExecutor([...(provider.systemCommands ?? [])]);
+}
+
+describe('CLI-083: the default command modules forward the org policy', () => {
+  it('blocks a disallowed provider switch when a policy is supplied to the FACTORY', async () => {
+    const result = await executorThroughFactory(POLICY).execute(
+      'provider',
+      createTestCommandHost(),
+      'switch openai',
+    );
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toContain('"openai" is not allowed');
+    expect(result?.message).toContain('ops@example.com');
+  });
+
+  it('does not block when no policy is supplied — absence stays distinguishable', async () => {
+    // The control. A factory that attached a policy of its own would satisfy the case above and
+    // change behaviour for every user who has no org policy at all.
+    const result = await executorThroughFactory().execute(
+      'provider',
+      createTestCommandHost(),
+      'switch openai',
+    );
+
+    expect(result?.message ?? '').not.toContain('is not allowed');
+  });
+});

package/src/default/__tests__/provider-environment-forwarding.test.ts

@@ -0,0 +1,98 @@
+/**
+ * #3459 — the default command modules hand `/provider` and `/model` the host's environment snapshot.
+ *
+ * A host that withholds its own credentials from `process.env` passes the snapshot it took first as
+ * `providerEnvironment`. This drives both commands through the factory, with the key gone from the
+ * live env, so it fails exactly when the factory stops forwarding the snapshot.
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, describe, expect, it } from 'vitest';
+import { SystemCommandExecutor } from '@robota-sdk/agent-framework';
+import { createTestCommandHost } from '@robota-sdk/agent-framework/testing';
+
+import { createDefaultCommandModules } from '../default-command-modules.js';
+
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import type { IProviderCommandSettingsAdapter, TProviderSettingsDocument } from '@robota-sdk/agent-framework';
+
+const KEY = 'OPENAI_API_KEY';
+const providerDefinitions: readonly IProviderDefinition[] = [
+  {
+    type: 'anthropic',
+    displayName: 'anthropic',
+    defaults: { model: 'm' },
+    modelCatalog: { status: 'live', entries: [{ id: 'm', displayName: 'm' }] },
+    createProvider: () => {
+      throw new Error('not used');
+    },
+  },
+  {
+    type: 'openai',
+    displayName: 'openai',
+    defaults: { apiKey: `$ENV:${KEY}` },
+    modelCatalog: { status: 'unavailable' },
+    requiresApiKey: true,
+    createProvider: () => {
+      throw new Error('not used');
+    },
+  },
+];
+
+const SETTINGS: TProviderSettingsDocument = {
+  currentProvider: 'anthropic',
+  providers: { anthropic: { type: 'anthropic', model: 'm' }, openai: { type: 'openai', model: 'gpt-x' } },
+};
+const adapter: IProviderCommandSettingsAdapter = {
+  readMergedSettings: () => SETTINGS,
+  readTargetSettings: () => ({}),
+  writeTargetSettings: () => undefined,
+};
+
+const USER_LOCAL_STORAGE_ROOT = mkdtempSync(join(tmpdir(), 'agent-test-provider-env-'));
+afterAll(() => rmSync(USER_LOCAL_STORAGE_ROOT, { recursive: true, force: true }));
+
+function executorThroughFactory(moduleName: string): SystemCommandExecutor {
+  const { modules } = createDefaultCommandModules({
+    cwd: '/work',
+    userLocalStorageRoot: USER_LOCAL_STORAGE_ROOT,
+    providerDefinitions,
+    providerSettingsAdapter: adapter,
+    providerEnvironment: { [KEY]: 'snapshot-key' },
+  });
+  const found = modules.find((module) => module.name === moduleName);
+  if (found === undefined) throw new Error(`${moduleName} was not built`);
+  return new SystemCommandExecutor([...(found.systemCommands ?? [])]);
+}
+
+async function withoutLiveKey<T>(run: () => Promise<T>): Promise<T> {
+  const live = process.env[KEY];
+  delete process.env[KEY];
+  try {
+    return await run();
+  } finally {
+    if (live !== undefined) process.env[KEY] = live;
+  }
+}
+
+describe('#3459: the default command modules forward the provider environment', () => {
+  it('/provider switch checks the key against the snapshot', async () => {
+    const result = await withoutLiveKey(() =>
+      executorThroughFactory('agent-command-provider').execute('provider', createTestCommandHost(), 'switch openai'),
+    );
+
+    expect(result?.success).toBe(true);
+  });
+
+  it('a cross-profile /model checks the key against the snapshot', async () => {
+    const host = createTestCommandHost({ session: { getModelId: () => 'm' } });
+    const result = await withoutLiveKey(() =>
+      executorThroughFactory('agent-command-model').execute('model', host, 'gpt-x'),
+    );
+
+    expect(result?.success).toBe(true);
+  });
+});

package/src/default/default-command-modules.ts

@@ -0,0 +1,247 @@
+import { findUnknownModuleNames, selectCommandModules } from '@robota-sdk/agent-framework';
+
+import { createAgentCommandModule } from '../agent/index.js';
+import { createBackgroundCommandModule } from '../background/index.js';
+import { createCompactCommandModule } from '../compact/index.js';
+import { createContextCommandModule } from '../context/index.js';
+import { createDevicesCommandModule } from '../devices/index.js';
+import { createDoctorCommandModule } from '../doctor/index.js';
+import { createEditorCommandModule } from '../editor/index.js';
+import { createAdvisorCommandModule } from '../advisor/index.js';
+import { createEffortCommandModule } from '../effort/index.js';
+import { createExitCommandModule } from '../exit/index.js';
+import { createForkCommandModule } from '../fork/index.js';
+import { createGitCommandModule } from '../git/index.js';
+import { createGoalCommandModule } from '../goal/index.js';
+import { createHandoffCommandModule } from '../handoff/index.js';
+import { createHelpCommandModule } from '../help/index.js';
+import { createKeybindingsCommandModule } from '../keybindings/index.js';
+import { createLanguageCommandModule } from '../language/index.js';
+import { createMCPActivationCommandModule } from '../mcp-activation/index.js';
+import { createMemoryCommandModule } from '../memory/index.js';
+import { createModeCommandModule } from '../mode/index.js';
+import { createModelCommandModule } from '../model/index.js';
+import { createSandboxCommandModule } from '../sandbox/index.js';
+import { createOutputStyleCommandModule } from '../output-style/index.js';
+import { createEventsCommandModule } from '../events/index.js';
+import { createPeersCommandModule } from '../peers/index.js';
+import { createPermissionsCommandModule } from '../permissions/index.js';
+import { createPlanCommandModule } from '../plan/index.js';
+import { createPluginCommandModule } from '../plugin/index.js';
+import { createPresetCommandModule } from '../preset/index.js';
+import { createProviderCommandModule } from '../provider/index.js';
+import { createRemoteControlCommandModule } from '../remote-control/index.js';
+import { createResetCommandModule } from '../reset/index.js';
+import { createRewindCommandModule } from '../rewind/index.js';
+import { createScheduleCommandModule } from '../schedule/index.js';
+import { createSessionCommandModule } from '../session/index.js';
+import { createSettingsCommandModule } from '../settings/index.js';
+import { createShellCommandModule } from '../shell/index.js';
+import { createSkillsCommandModule } from '../skills/index.js';
+import { createStatusLineCommandModule } from '../statusline/index.js';
+import { createThemeCommandModule } from '../theme/index.js';
+import { createUserLocalCommandModule } from '../user-local/index.js';
+
+import type { IDevicesCommandPort } from '../devices/index.js';
+import type { IDoctorDisplayVocabulary, IDoctorInputs } from '../doctor/index.js';
+import type { IKeybindingsFilePort } from '../keybindings/index.js';
+import type { IProviderDefinition, TProviderCredentialResolver } from '@robota-sdk/agent-core';
+import type {
+  IOrgPolicy,
+  IContributionSource,
+  ISkillRootDescriptor,
+  ICommandModule,
+  IProviderCommandSettingsAdapter,
+  IProviderConnectionHost,
+  IUnknownCommandModuleName,
+} from '@robota-sdk/agent-framework';
+import type { IThemeCataloguePort } from '@robota-sdk/agent-interface-command';
+
+export interface IDefaultCommandModulesOptions {
+  cwd: string;
+  userLocalStorageRoot: string;
+  /** Product-owned prefix for the interactive editor's temporary directory. */
+  editorTemporaryDirectoryPrefix?: string;
+  contributionSources?: readonly IContributionSource[];
+  skillRoots?: readonly ISkillRootDescriptor[];
+  providerDefinitions: readonly IProviderDefinition[];
+  providerSettingsAdapter: IProviderCommandSettingsAdapter;
+  /**
+   * CLI-083 (issue #2287) — the org policy, so `allowedProviders` and `requireApiKeyFromEnv` are
+   * reachable. This parameter existed, was removed by `92596bc6f` along with its only caller, and
+   * the consumer never stopped reading it: `provider-command-profile-operations.ts` still
+   * destructures `orgPolicy` from its options and enforces on it. Optional, so its absence stays
+   * distinguishable from a policy that allows everything — and that optionality is why nothing went
+   * red when the producer dropped it.
+   */
+  orgPolicy?: IOrgPolicy;
+  /**
+   * Where `/provider` and `/model` check a `$ENV:` or default credential variable: the host's startup
+   * snapshot when it withholds its own credentials from `process.env`. Absent, `process.env` is read.
+   */
+  providerEnvironment?: Readonly<Record<string, string | undefined>>;
+  /** Host-owned connection acquisition and transactional credential persistence. */
+  providerConnectionHost?: IProviderConnectionHost;
+  /** Host-owned resolution of an opaque saved credential reference. */
+  providerCredentialResolver?: TProviderCredentialResolver;
+  /** Optional TUI-owned file capability; absent, `/keybindings` says it belongs to an interactive terminal. */
+  keybindingsFilePort?: IKeybindingsFilePort;
+  /**
+   * SCREEN-2002: the surface's theme catalogue. Absent (print mode, `--serve`), `/theme` is still
+   * listed and says it belongs to an interactive terminal, which runs it when attached.
+   */
+  themeCataloguePort?: IThemeCataloguePort;
+  /**
+   * The host that keeps this device's identity (its terminal, credential store and state files).
+   * Absence means `/devices` is not registered: without it the command could do nothing.
+   */
+  devicesPort?: IDevicesCommandPort;
+  /** OBSERVABILITY-1991: host-composed doctor inputs; absence means `/doctor` is not registered. */
+  doctorInputs?: IDoctorInputs;
+  /** Product-owned diagnostic wording; absent keeps `/doctor` product-neutral. */
+  doctorDisplay?: IDoctorDisplayVocabulary;
+  /** Product-owned command to resume a saved fork; absent yields neutral host guidance. */
+  formatForkResumeCommand?: (sessionId: string) => string;
+  /** Host-owned fallback text and kill switch for session-local repeat. */
+  loopOptions?: { defaultPrompt?: string; resolveDefaultPrompt?: () => string; disabled?: boolean };
+  /**
+   * Whitelist of module `name`s to keep. When provided, only modules whose `name`
+   * appears here survive. Omitted → all modules kept (no-regression).
+   */
+  enabledCommandModules?: readonly string[];
+  /**
+   * Blacklist of module `name`s to remove. Applied after the whitelist, so a name
+   * present in both is removed (deny > allow). Omitted → no modules removed.
+   */
+  disabledCommandModules?: readonly string[];
+}
+
+/**
+ * Apply the preset module-selection delta to the default module set.
+ *
+ * Rules: if `enabled` is provided, keep only modules whose `name` is in it; then
+ * remove any module whose `name` is in `disabled` (deny > allow). Neither given →
+ * the full default set is returned unchanged (no-regression).
+ *
+ * INFRA-032: delegates to agent-framework's `selectCommandModules` (the allowed command→framework
+ * edge) so the filter body exists once — the previously byte-identical copy here is collapsed.
+ */
+function applyModuleSelection(
+  modules: readonly ICommandModule[],
+  enabled: readonly string[] | undefined,
+  disabled: readonly string[] | undefined,
+): readonly ICommandModule[] {
+  return selectCommandModules(modules, enabled, disabled);
+}
+
+/**
+ * Result of {@link createDefaultCommandModules} (INFRA-032): the selected `modules` plus any preset
+ * `enabledCommandModules`/`disabledCommandModules` names that matched no built module. Unknown names
+ * are returned as data (not dropped silently) so the CLI startup path can surface a non-fatal notice.
+ */
+export interface IDefaultCommandModulesResult {
+  readonly modules: readonly ICommandModule[];
+  readonly unknownModuleNames: readonly IUnknownCommandModuleName[];
+}
+
+export function createDefaultCommandModules({
+  cwd: _cwd,
+  userLocalStorageRoot,
+  editorTemporaryDirectoryPrefix,
+  contributionSources,
+  skillRoots,
+  providerDefinitions,
+  providerSettingsAdapter,
+  orgPolicy,
+  keybindingsFilePort,
+  themeCataloguePort,
+  devicesPort,
+  doctorInputs,
+  doctorDisplay,
+  formatForkResumeCommand,
+  loopOptions,
+  enabledCommandModules,
+  disabledCommandModules,
+  providerEnvironment,
+  providerConnectionHost,
+  providerCredentialResolver,
+}: IDefaultCommandModulesOptions): IDefaultCommandModulesResult {
+  const modules: readonly ICommandModule[] = [
+    createSkillsCommandModule({ contributionSources: contributionSources ?? [], skillRoots }),
+    createHelpCommandModule(),
+    createAgentCommandModule(),
+    createEffortCommandModule(),
+    createAdvisorCommandModule(),
+    createPermissionsCommandModule(),
+    createModeCommandModule(),
+    createSandboxCommandModule(),
+    createPresetCommandModule(),
+    createOutputStyleCommandModule(),
+    createLanguageCommandModule(),
+    createBackgroundCommandModule(),
+    // CLI-1994: beside `/background`, because a fork IS a background job — the one it starts is
+    // listed, peeked at, stopped and attached to through that command and its panel.
+    createForkCommandModule(formatForkResumeCommand),
+    createGoalCommandModule(),
+    createPlanCommandModule(),
+    createShellCommandModule(),
+    createEditorCommandModule(editorTemporaryDirectoryPrefix),
+    createGitCommandModule(),
+    createKeybindingsCommandModule(keybindingsFilePort),
+    createThemeCommandModule(themeCataloguePort),
+    ...(doctorInputs === undefined
+      ? []
+      : [createDoctorCommandModule(doctorInputs, undefined, doctorDisplay)]),
+    createMemoryCommandModule(),
+    createMCPActivationCommandModule(),
+    createUserLocalCommandModule(userLocalStorageRoot),
+    createCompactCommandModule(),
+    createContextCommandModule(),
+    createExitCommandModule(),
+    createSessionCommandModule(),
+    createResetCommandModule(),
+    createRewindCommandModule(),
+    createScheduleCommandModule(loopOptions),
+    createStatusLineCommandModule(),
+    createPluginCommandModule(),
+    createSettingsCommandModule(),
+    createPeersCommandModule(),
+    createEventsCommandModule(),
+    // HANDOFF-001 (issue #1864). Registered even though no product wires the carrier adapter yet:
+    // the command's own answer to a host without one is to say so, which is a better state than a
+    // capability nobody can see. It is also what makes the carrier's arrival observable.
+    createHandoffCommandModule(),
+    createRemoteControlCommandModule(),
+    ...(devicesPort === undefined ? [] : [createDevicesCommandModule(devicesPort)]),
+    createProviderCommandModule({
+      providerDefinitions,
+      settings: providerSettingsAdapter,
+      ...(orgPolicy === undefined ? {} : { orgPolicy }),
+      ...(providerEnvironment === undefined ? {} : { env: providerEnvironment }),
+      ...(providerConnectionHost === undefined ? {} : { connectionHost: providerConnectionHost }),
+      ...(providerCredentialResolver === undefined
+        ? {}
+        : { resolveCredential: providerCredentialResolver }),
+    }),
+    // #3282 §2: shares the provider command's settings adapter and definitions — one settings write
+    // owner, never a second copy that could drift from what `/provider switch` reads and writes.
+    createModelCommandModule({
+      providerDefinitions,
+      settings: providerSettingsAdapter,
+      ...(orgPolicy === undefined ? {} : { orgPolicy }),
+      ...(providerEnvironment === undefined ? {} : { env: providerEnvironment }),
+      ...(providerCredentialResolver === undefined
+        ? {}
+        : { resolveCredential: providerCredentialResolver }),
+    }),
+  ];
+  const builtModuleNames = modules.map((module) => module.name);
+  return {
+    modules: applyModuleSelection(modules, enabledCommandModules, disabledCommandModules),
+    unknownModuleNames: findUnknownModuleNames(
+      builtModuleNames,
+      enabledCommandModules,
+      disabledCommandModules,
+    ),
+  };
+}

package/src/default/index.ts

@@ -0,0 +1,5 @@
+export type {
+  IDefaultCommandModulesOptions,
+  IDefaultCommandModulesResult,
+} from './default-command-modules.js';
+export { createDefaultCommandModules } from './default-command-modules.js';