@robota-sdk/agent-command 3.0.0-beta.78 → 3.0.0-beta.81

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

@@ -0,0 +1,211 @@
+import type {
+  ICommandModule,
+  ISystemCommand,
+  TAppearanceSettingsPatch,
+} from '@robota-sdk/agent-framework';
+import type {
+  ICommand,
+  ICommandResult,
+  ICommandSource,
+  IThemeAppearanceState,
+  IThemeCatalogueEntry,
+  IThemeCataloguePort,
+} from '@robota-sdk/agent-interface-command';
+
+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.';
+
+function formatToggle(value: boolean): string {
+  return value ? 'on' : 'off';
+}
+
+function formatCatalogue(catalogue: IThemeCataloguePort): string {
+  const { settings, reducedMotionPin } = catalogue.getAppearance();
+  const rows = catalogue.listThemes().map((theme) => {
+    const marker = theme.id === settings.theme ? '* ' : '  ';
+    return `${marker}${theme.id} — ${theme.name} (${theme.appearance}, ${theme.source})`;
+  });
+  // Two facts, never one: what this run does, and what is saved. Reporting the SAVED value beside
+  // the tier reads as a contradiction on a `--no-reduced-motion` run over a `true` setting, and as
+  // an outright wrong answer to "is motion reduced right now".
+  const motion = reducedMotionPin
+    ? `${formatToggle(reducedMotionPin.reducedMotion)} for this run (pinned by ${reducedMotionPin.tier}; saved ${formatToggle(settings.reducedMotion)})`
+    : formatToggle(settings.reducedMotion);
+  return [
+    'Available themes:',
+    ...rows,
+    '',
+    `syntax highlighting: ${formatToggle(settings.syntaxHighlighting)}`,
+    `reduced motion: ${motion}`,
+  ].join('\n');
+}
+
+function listResult(catalogue: IThemeCataloguePort): ICommandResult {
+  return {
+    success: true,
+    message: formatCatalogue(catalogue),
+    data: {
+      themes: catalogue.listThemes().map((theme) => ({ ...theme })),
+      appearance: { ...catalogue.getAppearance().settings },
+    },
+  };
+}
+
+function unknownThemeResult(id: string, catalogue: IThemeCataloguePort): ICommandResult {
+  const known = catalogue
+    .listThemes()
+    .map((theme) => theme.id)
+    .join(', ');
+  return {
+    success: false,
+    message: `Unknown theme "${id}". Available: ${known || '(none)'}`,
+  };
+}
+
+/** `on` / `off`, and nothing else — a typo must not read as its opposite. */
+function parseToggle(word: string | undefined): boolean | undefined {
+  if (word === 'on') return true;
+  if (word === 'off') return false;
+  return undefined;
+}
+
+interface IParsedThemeArgs {
+  readonly patch?: TAppearanceSettingsPatch;
+  readonly themeId?: string;
+  readonly error?: string;
+}
+
+/**
+ * `/theme <id> [syntax on|off] [motion on|off]`, or a bare `syntax`/`motion` toggle. The theme id is
+ * NOT resolved here — parsing answers what was asked for, and the caller decides whether the
+ * catalogue holds it, so an unknown id is reported with the catalogue rather than as a parse error.
+ */
+function parseThemeArgs(tokens: readonly string[]): IParsedThemeArgs {
+  const patch: TAppearanceSettingsPatch = {};
+  let index = 0;
+  let themeId: string | undefined;
+  if (tokens[0] !== 'syntax' && tokens[0] !== 'motion') {
+    themeId = tokens[0];
+    index = 1;
+  }
+  while (index < tokens.length) {
+    const key = tokens[index];
+    const value = parseToggle(tokens[index + 1]);
+    if ((key !== 'syntax' && key !== 'motion') || value === undefined) {
+      return { error: `Usage: /theme ${THEME_ARGUMENT_HINT}` };
+    }
+    if (key === 'syntax') patch.syntaxHighlighting = value;
+    else patch.reducedMotion = !value;
+    index += 2;
+  }
+  return { patch, ...(themeId === undefined ? {} : { themeId }) };
+}
+
+/**
+ * `motion on` means "animate", which is `reducedMotion: false`. The inversion lives in one place
+ * precisely because reading it backwards is the easy mistake — a user asking for motion and getting
+ * stillness would look like the command doing nothing.
+ */
+function describeChange(
+  patch: TAppearanceSettingsPatch,
+  theme: IThemeCatalogueEntry | undefined,
+  state: IThemeAppearanceState,
+): string {
+  const parts: string[] = [];
+  if (theme) parts.push(`theme ${theme.name}`);
+  if (patch.syntaxHighlighting !== undefined) {
+    parts.push(`syntax highlighting ${formatToggle(patch.syntaxHighlighting)}`);
+  }
+  if (patch.reducedMotion !== undefined) {
+    parts.push(`motion ${formatToggle(!patch.reducedMotion)}`);
+  }
+  const applied = parts.length > 0 ? `Applied: ${parts.join(', ')}.` : 'Nothing to change.';
+  // The pin is reported, never silently obeyed or silently overridden: the setting IS persisted and
+  // takes effect next run, while this run keeps what pinned it.
+  if (patch.reducedMotion !== undefined && state.reducedMotionPin) {
+    return `${applied} Saved, but this run keeps reduced motion pinned by ${state.reducedMotionPin.tier}.`;
+  }
+  return applied;
+}
+
+export function executeThemeCommand(
+  catalogue: IThemeCataloguePort | undefined,
+  args: string,
+): ICommandResult {
+  if (!catalogue) return { success: false, message: THEME_UNAVAILABLE };
+
+  const tokens = args.trim().split(/\s+/u).filter(Boolean);
+  if (tokens.length === 0) {
+    return {
+      success: true,
+      message: 'Opening the theme picker...',
+      uiIntents: [{ type: 'show-theme-picker' }],
+    };
+  }
+  if (tokens.length === 1 && tokens[0] === 'list') return listResult(catalogue);
+
+  const parsed = parseThemeArgs(tokens);
+  if (parsed.error !== undefined || !parsed.patch) {
+    return { success: false, message: parsed.error ?? `Usage: /theme ${THEME_ARGUMENT_HINT}` };
+  }
+
+  const patch = { ...parsed.patch };
+  let theme: IThemeCatalogueEntry | undefined;
+  if (parsed.themeId !== undefined) {
+    theme = catalogue.getTheme(parsed.themeId);
+    // An unknown id writes NOTHING — not the theme, and not the toggles submitted beside it.
+    if (!theme) return unknownThemeResult(parsed.themeId, catalogue);
+    patch.theme = theme.id;
+  }
+
+  return {
+    success: true,
+    message: describeChange(patch, theme, catalogue.getAppearance()),
+    data: { appearance: { ...patch } },
+    hostActions: [{ type: 'appearance-settings-patch', patch }],
+  };
+}
+
+export function createThemeCommandEntry(): ICommand {
+  return {
+    name: 'theme',
+    displayName: 'Theme',
+    description: THEME_DESCRIPTION,
+    argumentHint: THEME_ARGUMENT_HINT,
+    source: 'theme',
+    userInvocable: true,
+    // User-only: UI preference.
+    modelInvocable: false,
+  };
+}
+
+export class ThemeCommandSource implements ICommandSource {
+  readonly name = 'theme';
+
+  getCommands(): ICommand[] {
+    return [createThemeCommandEntry()];
+  }
+}
+
+export function createThemeCommandModule(catalogue: IThemeCataloguePort): ICommandModule {
+  const entry = createThemeCommandEntry();
+  const command: ISystemCommand = {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    argumentHint: entry.argumentHint,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: (_context, args) => executeThemeCommand(catalogue, args),
+  };
+  return {
+    name: 'agent-command-theme',
+    commandSources: [new ThemeCommandSource()],
+    systemCommands: [command],
+  };
+}

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

@@ -1,8 +1,9 @@
 import { promises as fs } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { afterEach, describe, expect, it } from 'vitest';
-import { executeUserLocalDirectCommand } from '../user-local-command.js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { executeUserLocalCommand, executeUserLocalDirectCommand } from '../user-local-command.js';
+import { createUserLocalCommandModule } from '../user-local-command-module.js';
 
 const tempRoots: string[] = [];
 
@@ -13,50 +14,86 @@ async function createTempRoot(name: string): Promise<string> {
 }
 
 afterEach(async () => {
+  vi.unstubAllEnvs();
   await Promise.all(
     tempRoots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true })),
   );
 });
 
 describe('user-local command', () => {
+  it('does not advertise a specific product from the neutral command entry', () => {
+    const module = createUserLocalCommandModule('/tmp/selected-storage');
+    expect(module.commandSources?.[0]?.getCommands()[0]?.description).not.toMatch(/Robota/i);
+  });
+
+  it('fails closed when a direct caller omits the storage root', async () => {
+    const workspace = await createTempRoot('robota-user-local-missing-root-');
+    const repo = path.join(workspace, 'repo');
+    await fs.mkdir(repo);
+
+    const result = await executeUserLocalDirectCommand({
+      cwd: repo,
+      argv: ['storage', 'list'],
+    } as never);
+    expect(result).toMatchObject({ success: false });
+    expect(result.message).toContain('userLocalStorageRoot is required');
+  });
+
+  it('uses the explicit root for slash commands', async () => {
+    const workspace = await createTempRoot('robota-user-local-slash-root-');
+    const repo = path.join(workspace, 'repo');
+    const selectedRoot = path.join(workspace, 'selected', '.robota');
+    await fs.mkdir(repo);
+    vi.stubEnv('HOME', path.join(workspace, 'ambient-home'));
+
+    const directResult = await executeUserLocalCommand(
+      { getCwd: () => repo } as never,
+      'storage list --format=json',
+      selectedRoot,
+    );
+    expect(directResult.success).toBe(true);
+    expect(JSON.parse(directResult.message)).toMatchObject({ root: selectedRoot });
+
+    const slashCommand = createUserLocalCommandModule(selectedRoot).systemCommands?.[0];
+    expect(slashCommand).toBeDefined();
+    const result = await slashCommand!.execute(
+      { getCwd: () => repo } as never,
+      'storage list --format=json',
+    );
+    expect(result.success).toBe(true);
+    expect(JSON.parse(result.message)).toMatchObject({ root: selectedRoot });
+  });
+
   it('prints storage inspection JSON without provider configuration', async () => {
     const workspace = await createTempRoot('robota-user-local-command-');
     const repo = path.join(workspace, 'repo');
     const home = path.join(workspace, 'home');
     await fs.mkdir(repo);
     await fs.mkdir(home);
-    const originalHome = process.env.HOME;
-    process.env.HOME = home;
-
-    try {
-      const result = await executeUserLocalDirectCommand({
-        cwd: repo,
-        argv: ['storage', 'list'],
-        format: 'json',
-      });
-      const parsed = JSON.parse(result.message) as {
-        root: string;
-        categories: readonly { category: string; mayExecuteCommands: boolean }[];
-      };
-
-      expect(result.success).toBe(true);
-      expect(parsed.root).toBe(path.join(home, '.robota'));
-      expect(parsed.categories.map((item) => item.category)).toEqual([
-        'preferences',
-        'view-state',
-        'memory-projections',
-        'task-associations',
-        'workflow-metadata',
-        'inspection-index',
-      ]);
-      expect(parsed.categories.every((item) => item.mayExecuteCommands === false)).toBe(true);
-    } finally {
-      if (originalHome === undefined) {
-        delete process.env.HOME;
-      } else {
-        process.env.HOME = originalHome;
-      }
-    }
+    vi.stubEnv('HOME', path.join(workspace, 'ambient-home'));
+
+    const result = await executeUserLocalDirectCommand({
+      cwd: repo,
+      storageRoot: path.join(home, '.robota'),
+      argv: ['storage', 'list'],
+      format: 'json',
+    });
+    const parsed = JSON.parse(result.message) as {
+      root: string;
+      categories: readonly { category: string; mayExecuteCommands: boolean }[];
+    };
+
+    expect(result.success).toBe(true);
+    expect(parsed.root).toBe(path.join(home, '.robota'));
+    expect(parsed.categories.map((item) => item.category)).toEqual([
+      'preferences',
+      'view-state',
+      'memory-projections',
+      'task-associations',
+      'workflow-metadata',
+      'inspection-index',
+    ]);
+    expect(parsed.categories.every((item) => item.mayExecuteCommands === false)).toBe(true);
   });
 
   it('stores, lists, inspects, disables, and deletes user-local memory items', async () => {
@@ -65,81 +102,79 @@ describe('user-local command', () => {
     const home = path.join(workspace, 'home');
     await fs.mkdir(repo);
     await fs.mkdir(home);
-    const originalHome = process.env.HOME;
-    process.env.HOME = home;
-
-    try {
-      const setResult = await executeUserLocalDirectCommand({
-        cwd: repo,
-        argv: ['memory', 'set', 'view-preference', 'last-panel', 'background'],
-        summary: 'Open the background panel',
-        source: 'user-input',
-      });
-      expect(setResult.success).toBe(true);
-      expect(setResult.message).toContain('view-preference/last-panel');
-
-      const listResult = await executeUserLocalDirectCommand({
-        cwd: repo,
-        argv: ['memory', 'list'],
-        format: 'json',
-      });
-      const list = JSON.parse(listResult.message) as {
-        items: readonly { category: string; key: string; enabled: boolean }[];
-      };
-      expect(listResult.success).toBe(true);
-      expect(list.items).toHaveLength(1);
-      expect(list.items[0]).toMatchObject({
-        category: 'view-preference',
-        key: 'last-panel',
-        enabled: true,
-      });
-
-      const inspectResult = await executeUserLocalDirectCommand({
-        cwd: repo,
-        argv: ['memory', 'inspect', 'view-preference', 'last-panel'],
-        format: 'json',
-      });
-      const inspected = JSON.parse(inspectResult.message) as {
-        commandExecutionEffect: string;
-        displayNavigationRule: string;
-      };
-      expect(inspectResult.success).toBe(true);
-      expect(inspected.commandExecutionEffect).toBe('none');
-      expect(inspected.displayNavigationRule).toContain('display/navigation only');
-
-      const disableResult = await executeUserLocalDirectCommand({
-        cwd: repo,
-        argv: ['memory', 'disable', 'view-preference', 'last-panel'],
-      });
-      expect(disableResult.success).toBe(true);
-
-      const disabledInspectResult = await executeUserLocalDirectCommand({
-        cwd: repo,
-        argv: ['memory', 'inspect', 'view-preference', 'last-panel'],
-        format: 'json',
-      });
-      const disabled = JSON.parse(disabledInspectResult.message) as { enabled: boolean };
-      expect(disabled.enabled).toBe(false);
-
-      const deleteResult = await executeUserLocalDirectCommand({
-        cwd: repo,
-        argv: ['memory', 'delete', 'view-preference', 'last-panel'],
-      });
-      expect(deleteResult.success).toBe(true);
-
-      const missingResult = await executeUserLocalDirectCommand({
-        cwd: repo,
-        argv: ['memory', 'inspect', 'view-preference', 'last-panel'],
-        format: 'json',
-      });
-      expect(missingResult.success).toBe(false);
-      expect(missingResult.message).toBe('User-local memory item not found.');
-    } finally {
-      if (originalHome === undefined) {
-        delete process.env.HOME;
-      } else {
-        process.env.HOME = originalHome;
-      }
-    }
+    vi.stubEnv('HOME', path.join(workspace, 'ambient-home'));
+
+    const setResult = await executeUserLocalDirectCommand({
+      cwd: repo,
+      storageRoot: path.join(home, '.robota'),
+      argv: ['memory', 'set', 'view-preference', 'last-panel', 'background'],
+      summary: 'Open the background panel',
+      source: 'user-input',
+    });
+    expect(setResult.success).toBe(true);
+    expect(setResult.message).toContain('view-preference/last-panel');
+
+    const listResult = await executeUserLocalDirectCommand({
+      cwd: repo,
+      storageRoot: path.join(home, '.robota'),
+      argv: ['memory', 'list'],
+      format: 'json',
+    });
+    const list = JSON.parse(listResult.message) as {
+      items: readonly { category: string; key: string; enabled: boolean }[];
+    };
+    expect(listResult.success).toBe(true);
+    expect(list.items).toHaveLength(1);
+    expect(list.items[0]).toMatchObject({
+      category: 'view-preference',
+      key: 'last-panel',
+      enabled: true,
+    });
+
+    const inspectResult = await executeUserLocalDirectCommand({
+      cwd: repo,
+      storageRoot: path.join(home, '.robota'),
+      argv: ['memory', 'inspect', 'view-preference', 'last-panel'],
+      format: 'json',
+    });
+    const inspected = JSON.parse(inspectResult.message) as {
+      commandExecutionEffect: string;
+      displayNavigationRule: string;
+    };
+    expect(inspectResult.success).toBe(true);
+    expect(inspected.commandExecutionEffect).toBe('none');
+    expect(inspected.displayNavigationRule).toContain('display/navigation only');
+
+    const disableResult = await executeUserLocalDirectCommand({
+      cwd: repo,
+      storageRoot: path.join(home, '.robota'),
+      argv: ['memory', 'disable', 'view-preference', 'last-panel'],
+    });
+    expect(disableResult.success).toBe(true);
+
+    const disabledInspectResult = await executeUserLocalDirectCommand({
+      cwd: repo,
+      storageRoot: path.join(home, '.robota'),
+      argv: ['memory', 'inspect', 'view-preference', 'last-panel'],
+      format: 'json',
+    });
+    const disabled = JSON.parse(disabledInspectResult.message) as { enabled: boolean };
+    expect(disabled.enabled).toBe(false);
+
+    const deleteResult = await executeUserLocalDirectCommand({
+      cwd: repo,
+      storageRoot: path.join(home, '.robota'),
+      argv: ['memory', 'delete', 'view-preference', 'last-panel'],
+    });
+    expect(deleteResult.success).toBe(true);
+
+    const missingResult = await executeUserLocalDirectCommand({
+      cwd: repo,
+      storageRoot: path.join(home, '.robota'),
+      argv: ['memory', 'inspect', 'view-preference', 'last-panel'],
+      format: 'json',
+    });
+    expect(missingResult.success).toBe(false);
+    expect(missingResult.message).toBe('User-local memory item not found.');
   });
 });

package/src/user-local/user-local-command-constants.ts

@@ -1,4 +1,4 @@
-export const USER_LOCAL_COMMAND_DESCRIPTION = 'Inspect Robota user-local storage and memory state.';
+export const USER_LOCAL_COMMAND_DESCRIPTION = 'Inspect user-local storage and memory state.';
 export const USER_LOCAL_COMMAND_ARGUMENT_HINT =
   'storage list [--format json] | memory set/list/inspect/disable/delete';
 export const USER_LOCAL_COMMAND_USAGE =

package/src/user-local/user-local-command-module.ts

@@ -5,7 +5,7 @@ import {
 } from './user-local-command.js';
 
 import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
-import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
 
 export function createUserLocalCommandEntry(): ICommand {
   return {
@@ -14,6 +14,7 @@ export function createUserLocalCommandEntry(): ICommand {
     description: USER_LOCAL_COMMAND_DESCRIPTION,
     source: 'user-local',
     argumentHint: USER_LOCAL_COMMAND_ARGUMENT_HINT,
+    // User-only: the user's private cross-project storage.
     modelInvocable: false,
     safety: 'read-only',
     subcommands: [
@@ -31,7 +32,7 @@ export function createUserLocalCommandEntry(): ICommand {
   };
 }
 
-function createUserLocalSystemCommand(): ISystemCommand {
+function createUserLocalSystemCommand(storageRoot: string): ISystemCommand {
   const entry = createUserLocalCommandEntry();
   return {
     name: entry.name,
@@ -43,7 +44,7 @@ function createUserLocalSystemCommand(): ISystemCommand {
     argumentHint: entry.argumentHint,
     safety: entry.safety,
     subcommands: entry.subcommands,
-    execute: executeUserLocalCommand,
+    execute: (context, rawArgs) => executeUserLocalCommand(context, rawArgs, storageRoot),
   };
 }
 
@@ -55,10 +56,10 @@ export class UserLocalCommandSource implements ICommandSource {
   }
 }
 
-export function createUserLocalCommandModule(): ICommandModule {
+export function createUserLocalCommandModule(storageRoot: string): ICommandModule {
   return {
     name: 'agent-command-user-local',
     commandSources: [new UserLocalCommandSource()],
-    systemCommands: [createUserLocalSystemCommand()],
+    systemCommands: [createUserLocalSystemCommand(storageRoot)],
   };
 }

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

@@ -3,8 +3,8 @@ import { inspectUserLocalStorage } from '@robota-sdk/agent-framework';
 import { USER_LOCAL_COMMAND_USAGE } from './user-local-command-constants.js';
 import { executeMemoryCommand } from './user-local-memory-command.js';
 
-import type { ICommandHostContext } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+import type { ICommandHostWorkspace } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
 export {
   USER_LOCAL_COMMAND_ARGUMENT_HINT,
   USER_LOCAL_COMMAND_DESCRIPTION,
@@ -15,6 +15,7 @@ type TUserLocalOutputFormat = 'text' | 'json';
 
 export interface IUserLocalDirectCommandOptions {
   readonly cwd: string;
+  readonly storageRoot: string;
   readonly argv: readonly string[];
   readonly format?: string;
   readonly summary?: string;
@@ -123,6 +124,7 @@ function formatStorageInspectionText(
 
 async function executeStorageCommand(
   cwd: string,
+  storageRoot: string,
   parsed: IParsedUserLocalCommand,
 ): Promise<ICommandResult> {
   if ((parsed.action ?? 'list') !== 'list') {
@@ -132,7 +134,7 @@ async function executeStorageCommand(
     };
   }
 
-  const inspection = await inspectUserLocalStorage({ activeRepositoryRoot: cwd });
+  const inspection = await inspectUserLocalStorage({ activeRepositoryRoot: cwd, storageRoot });
   return {
     message:
       parsed.format === 'json'
@@ -149,13 +151,14 @@ async function executeStorageCommand(
 
 async function executeParsedUserLocalCommand(
   cwd: string,
+  storageRoot: string,
   parsed: IParsedUserLocalCommand,
 ): Promise<ICommandResult> {
   if (parsed.target === 'storage') {
-    return executeStorageCommand(cwd, parsed);
+    return executeStorageCommand(cwd, storageRoot, parsed);
   }
   if (parsed.target === 'memory') {
-    return executeMemoryCommand(cwd, parsed);
+    return executeMemoryCommand(cwd, storageRoot, parsed);
   }
   return {
     message: USER_LOCAL_COMMAND_USAGE,
@@ -176,6 +179,7 @@ export async function executeUserLocalDirectCommand(
   try {
     return await executeParsedUserLocalCommand(
       options.cwd,
+      options.storageRoot,
       parseUserLocalArgs(options.argv, {
         format: options.format,
         summary: options.summary,
@@ -191,12 +195,14 @@ export async function executeUserLocalDirectCommand(
 }
 
 export async function executeUserLocalCommand(
-  context: ICommandHostContext,
+  context: ICommandHostWorkspace,
   rawArgs: string,
+  storageRoot: string,
 ): Promise<ICommandResult> {
   try {
     return await executeParsedUserLocalCommand(
       context.getCwd(),
+      storageRoot,
       parseUserLocalArgs(splitRawArgs(rawArgs)),
     );
   } catch (error) {