@robota-sdk/agent-command 3.0.0-beta.82 → 3.0.0-beta.83

package/src/terminal-client/__tests__/terminal-client-commands.test.ts

@@ -0,0 +1,216 @@
+/**
+ * #3189 — the commands a terminal attached to a workspace daemon runs in its own process.
+ *
+ * The attached terminal routes by this set, not by the daemon's catalog, so the set must name exactly
+ * the commands the default assembly marks `runner: 'client'` — a command in one list and not the
+ * other would either run on the daemon or never run at all. And each client command must answer as
+ * the in-process command does, because it is the same command running somewhere else.
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, describe, expect, it, vi } from 'vitest';
+
+import { createDefaultCommandModules } from '../../default/index.js';
+import { createEditorCommandModule } from '../../editor/index.js';
+import { createKeybindingsCommandModule } from '../../keybindings/index.js';
+import { createShellCommandModule } from '../../shell/index.js';
+import { createThemeCommandModule } from '../../theme/index.js';
+import { createTerminalClientCommands } from '../terminal-client-commands.js';
+
+import type { ITerminalClientCommand } from '../terminal-client-commands.js';
+import type { IProviderDefinition } from '@robota-sdk/agent-core';
+import type {
+  ICommandHostContext,
+  ICommandHostTerminalHandoff,
+  ICommandHostWorkspace,
+  ICommandModule,
+  IProviderCommandSettingsAdapter,
+  TProviderSettingsDocument,
+} from '@robota-sdk/agent-framework';
+import type {
+  IThemeCatalogueEntry,
+  IThemeCataloguePort,
+} from '@robota-sdk/agent-interface-command';
+
+/** User-local storage lives in a private per-run directory, never a fixed name under /tmp. */
+const USER_LOCAL_STORAGE_ROOT = mkdtempSync(join(tmpdir(), 'robota-test-'));
+afterAll(() => rmSync(USER_LOCAL_STORAGE_ROOT, { recursive: true, force: true }));
+
+const providerDefinitions: readonly IProviderDefinition[] = [];
+const providerSettingsAdapter: IProviderCommandSettingsAdapter = {
+  readMergedSettings: () => ({}) as TProviderSettingsDocument,
+  readTargetSettings: () => ({}) as TProviderSettingsDocument,
+  writeTargetSettings: () => undefined,
+};
+
+const THEMES: IThemeCatalogueEntry[] = [
+  { id: 'dark', name: 'Dark', appearance: 'dark', source: 'built-in' },
+  { id: 'light', name: 'Light', appearance: 'light', source: 'built-in' },
+];
+const themeCatalogue: IThemeCataloguePort = {
+  listThemes: () => THEMES,
+  getTheme: (id) => THEMES.find((theme) => theme.id === id),
+  getAppearance: () => ({
+    settings: { theme: 'dark', syntaxHighlighting: true, reducedMotion: false },
+  }),
+};
+
+function allPortsGiven(): readonly ITerminalClientCommand[] {
+  return createTerminalClientCommands({
+    keybindingsFile: { ensureFile: async () => '/tmp/keybindings.json' },
+    themeCatalogue,
+  });
+}
+
+function find(commands: readonly ITerminalClientCommand[], name: string): ITerminalClientCommand {
+  const command = commands.find((candidate) => candidate.name === name);
+  if (!command) throw new Error(`no terminal client command "${name}"`);
+  return command;
+}
+
+/** A terminal the command cannot take over: a host with no interactive TTY. */
+function hostWithoutTerminal(): ICommandHostTerminalHandoff & ICommandHostWorkspace {
+  return {
+    canHandoffTerminal: () => false,
+    runWithTerminal: vi.fn(async () => {
+      throw new Error('a refused handoff must not be attempted');
+    }),
+    getCwd: () => '/tmp',
+    getCommandInvocationSource: () => 'user',
+  };
+}
+
+/** What the in-process command answers for the same host and arguments. */
+async function inProcess(module: ICommandModule, host: unknown, args: string) {
+  const command = module.systemCommands?.[0];
+  if (!command) throw new Error(`module ${module.name} has no command`);
+  return command.execute(host as ICommandHostContext, args);
+}
+
+describe('createTerminalClientCommands (#3189)', () => {
+  it('names exactly the commands the default assembly marks as client-run', () => {
+    const { modules } = createDefaultCommandModules({
+      cwd: '/tmp',
+      userLocalStorageRoot: USER_LOCAL_STORAGE_ROOT,
+      providerDefinitions,
+      providerSettingsAdapter,
+    });
+    const clientRun = modules
+      .flatMap((module) => module.systemCommands ?? [])
+      .filter((command) => command.runner === 'client')
+      .map((command) => command.name)
+      .sort();
+
+    expect(clientRun.length).toBeGreaterThan(0);
+    expect(
+      allPortsGiven()
+        .map((command) => command.name)
+        .sort(),
+    ).toEqual(clientRun);
+  });
+
+  it('leaves out a client command whose module the selection disables, as the default assembly does', () => {
+    const selection = { disabledCommandModules: ['agent-command-shell'] };
+    const { modules } = createDefaultCommandModules({
+      cwd: '/tmp',
+      userLocalStorageRoot: USER_LOCAL_STORAGE_ROOT,
+      providerDefinitions,
+      providerSettingsAdapter,
+      ...selection,
+    });
+    const clientRun = modules
+      .flatMap((module) => module.systemCommands ?? [])
+      .filter((command) => command.runner === 'client')
+      .map((command) => command.name)
+      .sort();
+
+    const names = createTerminalClientCommands({ themeCatalogue, ...selection })
+      .map((command) => command.name)
+      .sort();
+
+    expect(names).not.toContain('shell');
+    expect(names).toEqual(clientRun);
+  });
+
+  it('keeps only the enabled client modules, and a disabled name wins over an enabled one', () => {
+    const names = createTerminalClientCommands({
+      enabledCommandModules: ['agent-command-theme', 'agent-command-editor', 'agent-command-help'],
+      disabledCommandModules: ['agent-command-editor'],
+    }).map((command) => command.name);
+
+    expect(names).toEqual(['theme']);
+  });
+
+  it('with no selection, offers all four client commands', () => {
+    expect(
+      createTerminalClientCommands({})
+        .map((command) => command.name)
+        .sort(),
+    ).toEqual(['editor', 'keybindings', 'shell', 'theme']);
+  });
+
+  it('/shell refuses a host that cannot hand off the terminal exactly as the in-process command does', async () => {
+    const host = hostWithoutTerminal();
+
+    const client = await find(allPortsGiven(), 'shell').execute(host, 'ls');
+
+    expect(client).toEqual(await inProcess(createShellCommandModule(), host, 'ls'));
+    expect(client.success).toBe(false);
+    expect(host.runWithTerminal).not.toHaveBeenCalled();
+  });
+
+  it('/editor and /keybindings refuse a host without a terminal as their in-process commands do', async () => {
+    const keybindingsFile = { ensureFile: vi.fn(async () => '/tmp/keybindings.json') };
+    const commands = createTerminalClientCommands({ keybindingsFile, themeCatalogue });
+
+    const editorHost = hostWithoutTerminal();
+    const editor = await find(commands, 'editor').execute(editorHost, 'draft');
+    expect(editor).toEqual(await inProcess(createEditorCommandModule(), editorHost, 'draft'));
+    expect(editor.success).toBe(false);
+
+    const keybindingsHost = hostWithoutTerminal();
+    const keybindings = await find(commands, 'keybindings').execute(keybindingsHost, '');
+    expect(keybindings).toEqual(
+      await inProcess(createKeybindingsCommandModule(keybindingsFile), keybindingsHost, ''),
+    );
+    expect(keybindings.success).toBe(false);
+    expect(keybindingsFile.ensureFile).not.toHaveBeenCalled();
+  });
+
+  it('/theme with no arguments asks the terminal to open its theme picker', async () => {
+    const result = await find(allPortsGiven(), 'theme').execute(hostWithoutTerminal(), '');
+
+    expect(result).toMatchObject({ success: true, uiIntents: [{ type: 'show-theme-picker' }] });
+    expect(result.hostActions).toBeUndefined();
+  });
+
+  it('/theme with a known id returns one appearance settings patch for the terminal to write', async () => {
+    const result = await find(allPortsGiven(), 'theme').execute(hostWithoutTerminal(), 'light');
+
+    expect(result.success).toBe(true);
+    expect(result.hostActions).toEqual([
+      { type: 'appearance-settings-patch', patch: { theme: 'light' } },
+    ]);
+    expect(result).toEqual(await inProcess(createThemeCommandModule(themeCatalogue), {}, 'light'));
+  });
+
+  it('without their ports, /keybindings and /theme still run on the terminal and answer as in-process', async () => {
+    const commands = createTerminalClientCommands({});
+    // The set does not shrink: a command missing from it would be sent to the daemon instead.
+    expect(commands.map((command) => command.name).sort()).toEqual(
+      allPortsGiven()
+        .map((command) => command.name)
+        .sort(),
+    );
+
+    const host = hostWithoutTerminal();
+    expect(await find(commands, 'keybindings').execute(host, '')).toEqual(
+      await inProcess(createKeybindingsCommandModule(undefined), host, ''),
+    );
+    expect(await find(commands, 'theme').execute(host, 'light')).toEqual(
+      await inProcess(createThemeCommandModule(undefined), host, 'light'),
+    );
+  });
+});

package/src/terminal-client/index.ts

@@ -0,0 +1,5 @@
+export {
+  createTerminalClientCommands,
+  type ITerminalClientCommand,
+  type ITerminalClientCommandOptions,
+} from './terminal-client-commands.js';

package/src/terminal-client/terminal-client-commands.ts

@@ -0,0 +1,109 @@
+/**
+ * #3189: the commands that belong to the terminal the user sits at — the ones the default assembly
+ * marks `runner: 'client'`. A terminal attached to a workspace daemon runs these in its own process,
+ * on its own terminal and working directory, and sends nothing to the daemon.
+ *
+ * Each one is the in-process command's own execute function, so an attached terminal answers exactly
+ * as a standalone one does; only where it runs changes.
+ */
+import { selectCommandModules } from '@robota-sdk/agent-framework';
+
+import { createEditorCommandModule } from '../editor/editor-command-module.js';
+import { executeEditorCommand } from '../editor/editor-command.js';
+import {
+  createKeybindingsCommandModule,
+  executeKeybindingsCommand,
+} from '../keybindings/keybindings-command-module.js';
+import { createShellCommandModule } from '../shell/shell-command-module.js';
+import { executeShellCommand } from '../shell/shell-command.js';
+import { createThemeCommandModule, executeThemeCommand } from '../theme/theme-command-module.js';
+
+import type { IKeybindingsFilePort } from '../keybindings/keybindings-command-module.js';
+import type {
+  ICommandHostTerminalHandoff,
+  ICommandHostWorkspace,
+  ICommandModule,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult, IThemeCataloguePort } from '@robota-sdk/agent-interface-command';
+
+/** A command the terminal runs itself, with the terminal's own handoff and working directory. */
+export interface ITerminalClientCommand {
+  readonly name: string;
+  execute(
+    host: ICommandHostTerminalHandoff & ICommandHostWorkspace,
+    args: string,
+  ): ICommandResult | Promise<ICommandResult>;
+}
+
+/** The terminal's own capabilities — the same ones its in-process command modules are given. */
+export interface ITerminalClientCommandOptions {
+  /** The shell `/shell` runs; absent → the platform shell, as for the in-process command. */
+  readonly shellExecutable?: string;
+  /** Product-owned prefix for `/editor`'s temporary directory; absent → the command's default. */
+  readonly editorTemporaryDirectoryPrefix?: string;
+  /** Absent → `/keybindings` answers where key bindings live, as the in-process command does. */
+  readonly keybindingsFile?: IKeybindingsFilePort;
+  /** Absent → `/theme` answers where themes live, as the in-process command does. */
+  readonly themeCatalogue?: IThemeCataloguePort;
+  /**
+   * The same module selection the default assembly is given (`agent-command-shell`, …): a module it
+   * leaves out is left out here too, so an attached terminal offers no command a standalone one
+   * would not. Absent → every client-run module.
+   */
+  readonly enabledCommandModules?: readonly string[];
+  /** Applied after `enabledCommandModules`, as in the default assembly (deny > allow). */
+  readonly disabledCommandModules?: readonly string[];
+}
+
+type TClientExecute = ITerminalClientCommand['execute'];
+
+/**
+ * Every client-run command the module selection keeps, whether or not its port is given. The set
+ * shrinks only with the selection, never with a missing port: the attached terminal routes by it, so
+ * a selected command left out would run on the daemon instead — and without its port the command
+ * still answers as its in-process twin does.
+ */
+export function createTerminalClientCommands(
+  options: ITerminalClientCommandOptions,
+): readonly ITerminalClientCommand[] {
+  const {
+    shellExecutable,
+    editorTemporaryDirectoryPrefix,
+    keybindingsFile,
+    themeCatalogue,
+    enabledCommandModules,
+    disabledCommandModules,
+  } = options;
+  // Each client command is paired with its in-process module, so selection matches by the module's
+  // own name and the command keeps that module's command name.
+  const candidates: ReadonlyArray<readonly [ICommandModule, TClientExecute]> = [
+    [
+      createShellCommandModule(shellExecutable),
+      (host, args) => executeShellCommand(host, args, shellExecutable),
+    ],
+    [
+      createEditorCommandModule(editorTemporaryDirectoryPrefix),
+      (host, args) => executeEditorCommand(host, args, editorTemporaryDirectoryPrefix),
+    ],
+    [
+      createKeybindingsCommandModule(keybindingsFile),
+      (host) => executeKeybindingsCommand(keybindingsFile, host),
+    ],
+    [
+      createThemeCommandModule(themeCatalogue),
+      (_host, args) => executeThemeCommand(themeCatalogue, args),
+    ],
+  ];
+  const selected = new Set(
+    selectCommandModules(
+      candidates.map(([module]) => module),
+      enabledCommandModules,
+      disabledCommandModules,
+    ),
+  );
+  return candidates
+    .filter(([module]) => selected.has(module))
+    .flatMap(([module, execute]) =>
+      (module.systemCommands ?? []).map((command) => ({ name: command.name, execute })),
+    );
+}

package/src/theme/__tests__/theme-command.test.ts

@@ -73,7 +73,7 @@ describe('/theme without a catalogue (SCREEN-2002 TC-09)', () => {
     const result = executeThemeCommand(undefined, 'light');
 
     expect(result.success).toBe(false);
-    expect(result.message).toBe('Themes are not available in this environment.');
+    expect(result.message).toMatch(/Run \/theme in the robota terminal/);
     expect(result.hostActions).toBeUndefined();
   });
 });

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

@@ -16,7 +16,10 @@ const THEME_DESCRIPTION =
   'List, preview or switch the terminal colour theme, and toggle syntax highlighting and motion';
 const THEME_ARGUMENT_HINT = 'list | <theme-id> | syntax on|off | motion on|off';
 
-const THEME_UNAVAILABLE = 'Themes are not available in this environment.';
+// A host without a terminal (the desktop app's sidecar) still answers, so the command is never
+// "unknown" there — it says where themes live instead.
+const THEME_UNAVAILABLE =
+  'Themes belong to the robota terminal, and this surface has none. Run /theme in the robota terminal.';
 
 function formatToggle(value: boolean): string {
   return value ? 'on' : 'off';
@@ -179,6 +182,9 @@ export function createThemeCommandEntry(): ICommand {
     userInvocable: true,
     // User-only: UI preference.
     modelInvocable: false,
+    // Themes belong to the terminal the user sits at, so that terminal runs it, even when attached.
+    runner: 'client',
+    surfaces: ['terminal'],
   };
 }
 
@@ -190,7 +196,9 @@ export class ThemeCommandSource implements ICommandSource {
   }
 }
 
-export function createThemeCommandModule(catalogue: IThemeCataloguePort): ICommandModule {
+export function createThemeCommandModule(
+  catalogue: IThemeCataloguePort | undefined,
+): ICommandModule {
   const entry = createThemeCommandEntry();
   const command: ISystemCommand = {
     name: entry.name,
@@ -200,6 +208,8 @@ export function createThemeCommandModule(catalogue: IThemeCataloguePort): IComma
     requiresPermission: false,
     userInvocable: true,
     modelInvocable: false,
+    runner: entry.runner,
+    surfaces: entry.surfaces,
     lifecycle: 'inline',
     execute: (_context, args) => executeThemeCommand(catalogue, args),
   };

package/src/user-local/__tests__/user-local-command.test.ts

@@ -21,8 +21,8 @@ afterEach(async () => {
 });
 
 describe('user-local command', () => {
-  it('does not advertise a specific product from the neutral command entry', () => {
-    const module = createUserLocalCommandModule('/tmp/selected-storage');
+  it('does not advertise a specific product from the neutral command entry', async () => {
+    const module = createUserLocalCommandModule(await createTempRoot('robota-selected-storage-'));
     expect(module.commandSources?.[0]?.getCommands()[0]?.description).not.toMatch(/Robota/i);
   });