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

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

@@ -0,0 +1,145 @@
+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';
+
+const tempRoots: string[] = [];
+
+async function createTempRoot(name: string): Promise<string> {
+  const root = await fs.mkdtemp(path.join(tmpdir(), name));
+  tempRoots.push(root);
+  return root;
+}
+
+afterEach(async () => {
+  await Promise.all(
+    tempRoots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true })),
+  );
+});
+
+describe('user-local command', () => {
+  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;
+      }
+    }
+  });
+
+  it('stores, lists, inspects, disables, and deletes user-local memory items', async () => {
+    const workspace = await createTempRoot('robota-user-local-memory-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 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;
+      }
+    }
+  });
+});

package/src/user-local/index.ts

@@ -0,0 +1,13 @@
+export {
+  UserLocalCommandSource,
+  createUserLocalCommandEntry,
+  createUserLocalCommandModule,
+} from './user-local-command-module.js';
+export {
+  USER_LOCAL_COMMAND_ARGUMENT_HINT,
+  USER_LOCAL_COMMAND_DESCRIPTION,
+  USER_LOCAL_COMMAND_USAGE,
+  executeUserLocalCommand,
+  executeUserLocalDirectCommand,
+} from './user-local-command.js';
+export type { IUserLocalDirectCommandOptions } from './user-local-command.js';

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

@@ -0,0 +1,5 @@
+export const USER_LOCAL_COMMAND_DESCRIPTION = 'Inspect Robota 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 =
+  'Usage: user-local storage list [--format json] | user-local memory set <category> <key> <value> --summary <summary> --source <source> | user-local memory list [--format json] | user-local memory inspect <category> <key> [--format json] | user-local memory disable <category> <key> | user-local memory delete <category> <key>';

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

@@ -0,0 +1,67 @@
+import type {
+  ICommand,
+  ICommandModule,
+  ICommandSource,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import {
+  USER_LOCAL_COMMAND_ARGUMENT_HINT,
+  USER_LOCAL_COMMAND_DESCRIPTION,
+  executeUserLocalCommand,
+} from './user-local-command.js';
+
+export function createUserLocalCommandEntry(): ICommand {
+  return {
+    name: 'user-local',
+    displayName: 'User Config',
+    description: USER_LOCAL_COMMAND_DESCRIPTION,
+    source: 'user-local',
+    argumentHint: USER_LOCAL_COMMAND_ARGUMENT_HINT,
+    modelInvocable: false,
+    safety: 'read-only',
+    subcommands: [
+      {
+        name: 'storage',
+        description: 'Inspect user-local storage categories',
+        source: 'user-local',
+      },
+      {
+        name: 'memory',
+        description: 'Inspect and manage user-local memory items',
+        source: 'user-local',
+      },
+    ],
+  };
+}
+
+function createUserLocalSystemCommand(): ISystemCommand {
+  const entry = createUserLocalCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    argumentHint: entry.argumentHint,
+    safety: entry.safety,
+    subcommands: entry.subcommands,
+    execute: executeUserLocalCommand,
+  };
+}
+
+export class UserLocalCommandSource implements ICommandSource {
+  readonly name = 'user-local';
+
+  getCommands(): ICommand[] {
+    return [createUserLocalCommandEntry()];
+  }
+}
+
+export function createUserLocalCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-user-local',
+    commandSources: [new UserLocalCommandSource()],
+    systemCommands: [createUserLocalSystemCommand()],
+  };
+}

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

@@ -0,0 +1,205 @@
+import type { ICommandHostContext, ICommandResult } from '@robota-sdk/agent-framework';
+import { inspectUserLocalStorage } from '@robota-sdk/agent-framework';
+import { executeMemoryCommand } from './user-local-memory-command.js';
+import { USER_LOCAL_COMMAND_USAGE } from './user-local-command-constants.js';
+export {
+  USER_LOCAL_COMMAND_ARGUMENT_HINT,
+  USER_LOCAL_COMMAND_DESCRIPTION,
+  USER_LOCAL_COMMAND_USAGE,
+} from './user-local-command-constants.js';
+
+type TUserLocalOutputFormat = 'text' | 'json';
+
+export interface IUserLocalDirectCommandOptions {
+  readonly cwd: string;
+  readonly argv: readonly string[];
+  readonly format?: string;
+  readonly summary?: string;
+  readonly source?: string;
+}
+
+interface IParsedUserLocalCommand {
+  readonly target?: string;
+  readonly action?: string;
+  readonly positional: readonly string[];
+  readonly format: TUserLocalOutputFormat;
+  readonly summary?: string;
+  readonly source?: string;
+}
+
+interface IParsedUserLocalOption {
+  readonly format?: string;
+  readonly summary?: string;
+  readonly source?: string;
+  readonly nextIndex: number;
+}
+
+function parseOutputFormat(value: string | undefined): TUserLocalOutputFormat {
+  if (value === undefined || value === 'text') {
+    return 'text';
+  }
+  if (value === 'json') {
+    return 'json';
+  }
+  throw new Error(`Unsupported user-local output format: ${value}`);
+}
+
+function parseUserLocalOption(
+  arg: string,
+  argv: readonly string[],
+  index: number,
+): IParsedUserLocalOption | null {
+  if (arg === '--format') {
+    return { format: argv[index + 1], nextIndex: index + 1 };
+  }
+  if (arg.startsWith('--format=')) {
+    return { format: arg.slice('--format='.length), nextIndex: index };
+  }
+  if (arg === '--summary') {
+    return { summary: argv[index + 1], nextIndex: index + 1 };
+  }
+  if (arg.startsWith('--summary=')) {
+    return { summary: arg.slice('--summary='.length), nextIndex: index };
+  }
+  if (arg === '--source') {
+    return { source: argv[index + 1], nextIndex: index + 1 };
+  }
+  if (arg.startsWith('--source=')) {
+    return { source: arg.slice('--source='.length), nextIndex: index };
+  }
+  return null;
+}
+
+function parseUserLocalArgs(
+  argv: readonly string[],
+  directOptions: {
+    readonly format?: string;
+    readonly summary?: string;
+    readonly source?: string;
+  } = {},
+): IParsedUserLocalCommand {
+  let format = directOptions.format;
+  let summary = directOptions.summary;
+  let source = directOptions.source;
+  const positional: string[] = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const option = parseUserLocalOption(arg, argv, index);
+    if (option !== null) {
+      format = option.format ?? format;
+      summary = option.summary ?? summary;
+      source = option.source ?? source;
+      index = option.nextIndex;
+      continue;
+    }
+    positional.push(arg);
+  }
+
+  return {
+    target: positional[0],
+    action: positional[1],
+    positional: positional.slice(2),
+    format: parseOutputFormat(format),
+    summary,
+    source,
+  };
+}
+
+function splitRawArgs(rawArgs: string): readonly string[] {
+  return rawArgs.trim().split(/\s+/).filter(Boolean);
+}
+
+function formatStorageInspectionText(
+  root: string,
+  categories: readonly { category: string }[],
+): string {
+  const categoryLines = categories.map((item) => `- ${item.category}`);
+  return [`User-local storage root: ${root}`, 'Categories:', ...categoryLines].join('\n');
+}
+
+async function executeStorageCommand(
+  cwd: string,
+  parsed: IParsedUserLocalCommand,
+): Promise<ICommandResult> {
+  if ((parsed.action ?? 'list') !== 'list') {
+    return {
+      message: USER_LOCAL_COMMAND_USAGE,
+      success: false,
+    };
+  }
+
+  const inspection = await inspectUserLocalStorage({ activeRepositoryRoot: cwd });
+  return {
+    message:
+      parsed.format === 'json'
+        ? JSON.stringify(inspection, null, 2)
+        : formatStorageInspectionText(inspection.root, inspection.categories),
+    success: true,
+    data: {
+      root: inspection.root,
+      categories: inspection.categories,
+      inspection,
+    },
+  };
+}
+
+async function executeParsedUserLocalCommand(
+  cwd: string,
+  parsed: IParsedUserLocalCommand,
+): Promise<ICommandResult> {
+  if (parsed.target === 'storage') {
+    return executeStorageCommand(cwd, parsed);
+  }
+  if (parsed.target === 'memory') {
+    return executeMemoryCommand(cwd, parsed);
+  }
+  return {
+    message: USER_LOCAL_COMMAND_USAGE,
+    success: false,
+  };
+}
+
+function formatCommandErrorMessage(errorMessage: string): string {
+  if (errorMessage.includes('ENOENT')) {
+    return 'User-local memory item not found.';
+  }
+  return errorMessage;
+}
+
+export async function executeUserLocalDirectCommand(
+  options: IUserLocalDirectCommandOptions,
+): Promise<ICommandResult> {
+  try {
+    return await executeParsedUserLocalCommand(
+      options.cwd,
+      parseUserLocalArgs(options.argv, {
+        format: options.format,
+        summary: options.summary,
+        source: options.source,
+      }),
+    );
+  } catch (error) {
+    return {
+      message: formatCommandErrorMessage(error instanceof Error ? error.message : String(error)),
+      success: false,
+    };
+  }
+}
+
+export async function executeUserLocalCommand(
+  context: ICommandHostContext,
+  rawArgs: string,
+): Promise<ICommandResult> {
+  try {
+    return await executeParsedUserLocalCommand(
+      context.getCwd(),
+      parseUserLocalArgs(splitRawArgs(rawArgs)),
+    );
+  } catch (error) {
+    return {
+      message: formatCommandErrorMessage(error instanceof Error ? error.message : String(error)),
+      success: false,
+    };
+  }
+}

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

@@ -0,0 +1,147 @@
+import type { ICommandResult, TUserLocalMemoryCategory } from '@robota-sdk/agent-framework';
+import {
+  deleteUserLocalMemoryItem,
+  disableUserLocalMemoryItem,
+  inspectUserLocalMemoryItem,
+  listUserLocalMemoryItems,
+  setUserLocalMemoryItem,
+} from '@robota-sdk/agent-framework';
+import { USER_LOCAL_COMMAND_USAGE } from './user-local-command-constants.js';
+
+export interface IUserLocalMemoryCommandArgs {
+  readonly action?: string;
+  readonly positional: readonly string[];
+  readonly format: 'text' | 'json';
+  readonly summary?: string;
+  readonly source?: string;
+}
+
+function formatMemoryListText(
+  items: readonly { category: string; key: string; enabled: boolean }[],
+): string {
+  if (items.length === 0) {
+    return 'No user-local memory items.';
+  }
+  return items
+    .map((item) => `- ${item.category}/${item.key} (${item.enabled ? 'enabled' : 'disabled'})`)
+    .join('\n');
+}
+
+function parseMemoryCategory(value: string | undefined): TUserLocalMemoryCategory {
+  if (value === undefined) {
+    throw new Error('User-local memory category is required.');
+  }
+  return value as TUserLocalMemoryCategory;
+}
+
+async function executeMemoryListCommand(
+  activeRepositoryRoot: string,
+  parsed: IUserLocalMemoryCommandArgs,
+): Promise<ICommandResult> {
+  const list = await listUserLocalMemoryItems({ activeRepositoryRoot });
+  return {
+    message:
+      parsed.format === 'json' ? JSON.stringify(list, null, 2) : formatMemoryListText(list.items),
+    success: true,
+    data: { list },
+  };
+}
+
+async function executeMemorySetCommand(
+  activeRepositoryRoot: string,
+  parsed: IUserLocalMemoryCommandArgs,
+): Promise<ICommandResult> {
+  const [category, key, value] = parsed.positional;
+  const item = await setUserLocalMemoryItem({
+    activeRepositoryRoot,
+    category: parseMemoryCategory(category),
+    key: key ?? '',
+    value: value ?? '',
+    summary: parsed.summary ?? '',
+    source: parsed.source ?? '',
+  });
+  return {
+    message: `Stored user-local memory item ${item.category}/${item.key} at ${item.storageLocation}`,
+    success: true,
+    data: { item },
+  };
+}
+
+async function executeMemoryInspectCommand(
+  activeRepositoryRoot: string,
+  parsed: IUserLocalMemoryCommandArgs,
+): Promise<ICommandResult> {
+  const [category, key] = parsed.positional;
+  const item = await inspectUserLocalMemoryItem({
+    activeRepositoryRoot,
+    category: parseMemoryCategory(category),
+    key: key ?? '',
+  });
+  return {
+    message:
+      parsed.format === 'json'
+        ? JSON.stringify(item, null, 2)
+        : `${item.category}/${item.key}: ${item.summary}`,
+    success: true,
+    data: { item },
+  };
+}
+
+async function executeMemoryDisableCommand(
+  activeRepositoryRoot: string,
+  parsed: IUserLocalMemoryCommandArgs,
+): Promise<ICommandResult> {
+  const [category, key] = parsed.positional;
+  const item = await disableUserLocalMemoryItem({
+    activeRepositoryRoot,
+    category: parseMemoryCategory(category),
+    key: key ?? '',
+  });
+  return {
+    message: `Disabled user-local memory item ${item.category}/${item.key}`,
+    success: true,
+    data: { item },
+  };
+}
+
+async function executeMemoryDeleteCommand(
+  activeRepositoryRoot: string,
+  parsed: IUserLocalMemoryCommandArgs,
+): Promise<ICommandResult> {
+  const [category, key] = parsed.positional;
+  const result = await deleteUserLocalMemoryItem({
+    activeRepositoryRoot,
+    category: parseMemoryCategory(category),
+    key: key ?? '',
+  });
+  return {
+    message: `Deleted user-local memory item ${result.category}/${result.key}`,
+    success: true,
+    data: { result },
+  };
+}
+
+export async function executeMemoryCommand(
+  cwd: string,
+  parsed: IUserLocalMemoryCommandArgs,
+): Promise<ICommandResult> {
+  if ((parsed.action ?? 'list') === 'list') {
+    return executeMemoryListCommand(cwd, parsed);
+  }
+  if (parsed.action === 'set') {
+    return executeMemorySetCommand(cwd, parsed);
+  }
+  if (parsed.action === 'inspect') {
+    return executeMemoryInspectCommand(cwd, parsed);
+  }
+  if (parsed.action === 'disable') {
+    return executeMemoryDisableCommand(cwd, parsed);
+  }
+  if (parsed.action === 'delete') {
+    return executeMemoryDeleteCommand(cwd, parsed);
+  }
+  return {
+    message: USER_LOCAL_COMMAND_USAGE,
+    success: false,
+  };
+}