feat: migrate command format

packages/cli/src/services/command-migration-tool.test.ts

@@ -101,14 +101,20 @@ description = "Test description"`;
       expect(mdContent).toContain('description: Test description');
       expect(mdContent).toContain('Test prompt');
 
-      // Check backup was created
-      expect(result.backupDir).toBeDefined();
-      const backupPath = path.join(result.backupDir!, 'test.toml');
+      // Check backup was created (original renamed to .toml.backup)
+      const backupPath = path.join(tempDir, 'test.toml.backup');
       const backupExists = await fs
         .access(backupPath)
         .then(() => true)
         .catch(() => false);
       expect(backupExists).toBe(true);
+
+      // Original .toml file should not exist (renamed to .backup)
+      const tomlExists = await fs
+        .access(path.join(tempDir, 'test.toml'))
+        .then(() => true)
+        .catch(() => false);
+      expect(tomlExists).toBe(false);
     });
 
     it('should delete original TOML when deleteOriginal is true', async () => {
@@ -120,7 +126,7 @@ description = "Test description"`;
 
       await migrateTomlCommands({
         commandDir: tempDir,
-        createBackup: true,
+        createBackup: false,
         deleteOriginal: true,
       });
 
@@ -137,6 +143,13 @@ description = "Test description"`;
         .then(() => true)
         .catch(() => false);
       expect(mdExists).toBe(true);
+
+      // Backup should not exist (createBackup was false)
+      const backupExists = await fs
+        .access(path.join(tempDir, 'delete-me.toml.backup'))
+        .then(() => true)
+        .catch(() => false);
+      expect(backupExists).toBe(false);
     });
 
     it('should fail if Markdown file already exists', async () => {
@@ -172,10 +185,24 @@ description = "Test description"`;
       const result = await migrateTomlCommands({
         commandDir: tempDir,
         createBackup: false,
+        deleteOriginal: false,
       });
 
       expect(result.success).toBe(true);
-      expect(result.backupDir).toBeUndefined();
+
+      // Original TOML file should still exist (no backup, no delete)
+      const tomlExists = await fs
+        .access(path.join(tempDir, 'no-backup.toml'))
+        .then(() => true)
+        .catch(() => false);
+      expect(tomlExists).toBe(true);
+
+      // Backup should not exist
+      const backupExists = await fs
+        .access(path.join(tempDir, 'no-backup.toml.backup'))
+        .then(() => true)
+        .catch(() => false);
+      expect(backupExists).toBe(false);
     });
 
     it('should return success with empty results for no TOML files', async () => {

packages/cli/src/services/command-migration-tool.ts

@@ -17,7 +17,6 @@ export interface MigrationResult {
   success: boolean;
   convertedFiles: string[];
   failedFiles: Array<{ file: string; error: string }>;
-  backupDir?: string;
 }
 
 export interface MigrationOptions {
@@ -27,8 +26,6 @@ export interface MigrationOptions {
   createBackup?: boolean;
   /** Whether to delete original TOML files after migration (default: false) */
   deleteOriginal?: boolean;
-  /** Backup directory suffix (default: '.backup') */
-  backupSuffix?: string;
 }
 
 /**
@@ -63,12 +60,7 @@ export async function detectTomlCommands(
 export async function migrateTomlCommands(
   options: MigrationOptions,
 ): Promise<MigrationResult> {
-  const {
-    commandDir,
-    createBackup = true,
-    deleteOriginal = false,
-    backupSuffix = '.backup',
-  } = options;
+  const { commandDir, createBackup = true, deleteOriginal = false } = options;
 
   const result: MigrationResult = {
     success: true,
@@ -83,15 +75,6 @@ export async function migrateTomlCommands(
     return result;
   }
 
-  // Create backup directory if needed
-  let backupDir: string | undefined;
-  if (createBackup) {
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-    backupDir = path.join(commandDir, `${backupSuffix}-${timestamp}`);
-    await fs.mkdir(backupDir, { recursive: true });
-    result.backupDir = backupDir;
-  }
-
   // Process each TOML file
   for (const relativeFile of tomlFiles) {
     const tomlPath = path.join(commandDir, relativeFile);
@@ -122,15 +105,12 @@ export async function migrateTomlCommands(
       // Write Markdown file
       await fs.writeFile(markdownPath, markdownContent, 'utf-8');
 
-      // Backup original if requested
-      if (backupDir) {
-        const backupPath = path.join(backupDir, relativeFile);
-        await fs.mkdir(path.dirname(backupPath), { recursive: true });
-        await fs.copyFile(tomlPath, backupPath);
-      }
-
-      // Delete original if requested
-      if (deleteOriginal) {
+      // Backup original if requested (rename to .toml.backup)
+      if (createBackup) {
+        const backupPath = `${tomlPath}.backup`;
+        await fs.rename(tomlPath, backupPath);
+      } else if (deleteOriginal) {
+        // Delete original if requested and no backup
         await fs.unlink(tomlPath);
       }
 

packages/cli/src/ui/AppContainer.tsx

@@ -38,6 +38,7 @@ import {
   getErrorMessage,
   getAllGeminiMdFilenames,
   ShellExecutionService,
+  Storage,
 } from '@qwen-code/qwen-code-core';
 import { buildResumedHistoryItems } from './utils/resumeHistoryUtils.js';
 import { validateAuthMethod } from '../config/auth.js';
@@ -76,6 +77,9 @@ import { useLoadingIndicator } from './hooks/useLoadingIndicator.js';
 import { useFolderTrust } from './hooks/useFolderTrust.js';
 import { useIdeTrustListener } from './hooks/useIdeTrustListener.js';
 import { type IdeIntegrationNudgeResult } from './IdeIntegrationNudge.js';
+import { type CommandMigrationNudgeResult } from './CommandFormatMigrationNudge.js';
+import { useCommandMigration } from './hooks/useCommandMigration.js';
+import { migrateTomlCommands } from '../services/command-migration-tool.js';
 import { appEvents, AppEvent } from '../utils/events.js';
 import { type UpdateObject } from './utils/updateCheck.js';
 import { setUpdateHandler } from '../utils/handleAutoUpdate.js';
@@ -845,6 +849,13 @@ export const AppContainer = (props: AppContainerProps) => {
       !idePromptAnswered,
   );
 
+  // Command migration nudge
+  const {
+    showMigrationNudge: shouldShowCommandMigrationNudge,
+    tomlFiles: commandMigrationTomlFiles,
+    setShowMigrationNudge: setShowCommandMigrationNudge,
+  } = useCommandMigration(settings, config.storage);
+
   const [showErrorDetails, setShowErrorDetails] = useState<boolean>(false);
   const [showToolDescriptions, setShowToolDescriptions] =
     useState<boolean>(false);
@@ -935,6 +946,92 @@ export const AppContainer = (props: AppContainerProps) => {
     [handleSlashCommand, settings],
   );
 
+  const handleCommandMigrationComplete = useCallback(
+    async (result: CommandMigrationNudgeResult) => {
+      setShowCommandMigrationNudge(false);
+
+      if (result.userSelection === 'yes') {
+        // Perform migration for both workspace and user levels
+        try {
+          const results = [];
+
+          // Migrate workspace commands
+          const workspaceCommandsDir = config.storage.getProjectCommandsDir();
+          const workspaceResult = await migrateTomlCommands({
+            commandDir: workspaceCommandsDir,
+            createBackup: true,
+            deleteOriginal: false,
+          });
+          if (
+            workspaceResult.convertedFiles.length > 0 ||
+            workspaceResult.failedFiles.length > 0
+          ) {
+            results.push({ level: 'workspace', result: workspaceResult });
+          }
+
+          // Migrate user commands
+          const userCommandsDir = Storage.getUserCommandsDir();
+          const userResult = await migrateTomlCommands({
+            commandDir: userCommandsDir,
+            createBackup: true,
+            deleteOriginal: false,
+          });
+          if (
+            userResult.convertedFiles.length > 0 ||
+            userResult.failedFiles.length > 0
+          ) {
+            results.push({ level: 'user', result: userResult });
+          }
+
+          // Report results
+          for (const { level, result: migrationResult } of results) {
+            if (
+              migrationResult.success &&
+              migrationResult.convertedFiles.length > 0
+            ) {
+              historyManager.addItem(
+                {
+                  type: MessageType.INFO,
+                  text: `✅ [${level}] Successfully migrated ${migrationResult.convertedFiles.length} command file${migrationResult.convertedFiles.length > 1 ? 's' : ''} to Markdown format. Original files backed up as .toml.backup`,
+                },
+                Date.now(),
+              );
+            }
+
+            if (migrationResult.failedFiles.length > 0) {
+              historyManager.addItem(
+                {
+                  type: MessageType.ERROR,
+                  text: `⚠️  [${level}] Failed to migrate ${migrationResult.failedFiles.length} file${migrationResult.failedFiles.length > 1 ? 's' : ''}:\n${migrationResult.failedFiles.map((f) => `  • ${f.file}: ${f.error}`).join('\n')}`,
+                },
+                Date.now(),
+              );
+            }
+          }
+
+          if (results.length === 0) {
+            historyManager.addItem(
+              {
+                type: MessageType.INFO,
+                text: 'ℹ️  No TOML files found to migrate.',
+              },
+              Date.now(),
+            );
+          }
+        } catch (error) {
+          historyManager.addItem(
+            {
+              type: MessageType.ERROR,
+              text: `❌ Migration failed: ${getErrorMessage(error)}`,
+            },
+            Date.now(),
+          );
+        }
+      }
+    },
+    [historyManager, setShowCommandMigrationNudge, config.storage],
+  );
+
   const { elapsedTime, currentLoadingPhrase } = useLoadingIndicator(
     streamingState,
     settings.merged.ui?.customWittyPhrases,
@@ -1179,6 +1276,7 @@ export const AppContainer = (props: AppContainerProps) => {
     showWelcomeBackDialog ||
     showWorkspaceMigrationDialog ||
     shouldShowIdePrompt ||
+    shouldShowCommandMigrationNudge ||
     isFolderTrustDialogOpen ||
     !!shellConfirmationRequest ||
     !!confirmationRequest ||
@@ -1244,6 +1342,8 @@ export const AppContainer = (props: AppContainerProps) => {
       suggestionsWidth,
       isInputActive,
       shouldShowIdePrompt,
+      shouldShowCommandMigrationNudge,
+      commandMigrationTomlFiles,
       isFolderTrustDialogOpen: isFolderTrustDialogOpen ?? false,
       isTrustedFolder,
       constrainHeight,
@@ -1333,6 +1433,8 @@ export const AppContainer = (props: AppContainerProps) => {
       suggestionsWidth,
       isInputActive,
       shouldShowIdePrompt,
+      shouldShowCommandMigrationNudge,
+      commandMigrationTomlFiles,
       isFolderTrustDialogOpen,
       isTrustedFolder,
       constrainHeight,
@@ -1404,6 +1506,7 @@ export const AppContainer = (props: AppContainerProps) => {
       setShellModeActive,
       vimHandleInput,
       handleIdePromptComplete,
+      handleCommandMigrationComplete,
       handleFolderTrustSelect,
       setConstrainHeight,
       onEscapePromptChange: handleEscapePromptChange,
@@ -1441,6 +1544,7 @@ export const AppContainer = (props: AppContainerProps) => {
       setShellModeActive,
       vimHandleInput,
       handleIdePromptComplete,
+      handleCommandMigrationComplete,
       handleFolderTrustSelect,
       setConstrainHeight,
       handleEscapePromptChange,

packages/cli/src/ui/CommandFormatMigrationNudge.tsx

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Box, Text } from 'ink';
+import type { RadioSelectItem } from './components/shared/RadioButtonSelect.js';
+import { RadioButtonSelect } from './components/shared/RadioButtonSelect.js';
+import { useKeypress } from './hooks/useKeypress.js';
+import { theme } from './semantic-colors.js';
+
+export type CommandMigrationNudgeResult = {
+  userSelection: 'yes' | 'no';
+};
+
+interface CommandFormatMigrationNudgeProps {
+  tomlFiles: string[];
+  onComplete: (result: CommandMigrationNudgeResult) => void;
+}
+
+export function CommandFormatMigrationNudge({
+  tomlFiles,
+  onComplete,
+}: CommandFormatMigrationNudgeProps) {
+  useKeypress(
+    (key) => {
+      if (key.name === 'escape') {
+        onComplete({
+          userSelection: 'no',
+        });
+      }
+    },
+    { isActive: true },
+  );
+
+  const OPTIONS: Array<RadioSelectItem<CommandMigrationNudgeResult>> = [
+    {
+      label: 'Yes',
+      value: {
+        userSelection: 'yes',
+      },
+      key: 'Yes',
+    },
+    {
+      label: 'No (esc)',
+      value: {
+        userSelection: 'no',
+      },
+      key: 'No (esc)',
+    },
+  ];
+
+  const count = tomlFiles.length;
+  const fileList =
+    count <= 3
+      ? tomlFiles.map((f) => `  • ${f}`).join('\n')
+      : `  • ${tomlFiles.slice(0, 2).join('\n  • ')}\n  • ... and ${count - 2} more`;
+
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={theme.status.warning}
+      padding={1}
+      width="100%"
+      marginLeft={1}
+    >
+      <Box marginBottom={1} flexDirection="column">
+        <Text>
+          <Text color={theme.status.warning}>{'⚠️  '}</Text>
+          <Text bold>Command Format Migration</Text>
+        </Text>
+        <Text color={theme.text.secondary}>
+          {`Found ${count} TOML command file${count > 1 ? 's' : ''}:`}
+        </Text>
+        <Text color={theme.text.secondary}>{fileList}</Text>
+        <Text>{''}</Text>
+        <Text color={theme.text.secondary}>
+          The TOML format is deprecated. Would you like to migrate them to
+          Markdown format?
+        </Text>
+        <Text color={theme.text.secondary}>
+          (Backups will be created and original files will be preserved)
+        </Text>
+      </Box>
+      <RadioButtonSelect items={OPTIONS} onSelect={onComplete} />
+    </Box>
+  );
+}

packages/cli/src/ui/components/DialogManager.tsx

@@ -6,6 +6,7 @@
 
 import { Box, Text } from 'ink';
 import { IdeIntegrationNudge } from '../IdeIntegrationNudge.js';
+import { CommandFormatMigrationNudge } from '../CommandFormatMigrationNudge.js';
 import { LoopDetectionConfirmation } from './LoopDetectionConfirmation.js';
 import { FolderTrustDialog } from './FolderTrustDialog.js';
 import { ShellConfirmationDialog } from './ShellConfirmationDialog.js';
@@ -94,6 +95,14 @@ export const DialogManager = ({
       />
     );
   }
+  if (uiState.shouldShowCommandMigrationNudge) {
+    return (
+      <CommandFormatMigrationNudge
+        tomlFiles={uiState.commandMigrationTomlFiles}
+        onComplete={uiActions.handleCommandMigrationComplete}
+      />
+    );
+  }
   if (uiState.isFolderTrustDialogOpen) {
     return (
       <FolderTrustDialog

packages/cli/src/ui/contexts/UIActionsContext.tsx

@@ -7,6 +7,7 @@
 import { createContext, useContext } from 'react';
 import { type Key } from '../hooks/useKeypress.js';
 import { type IdeIntegrationNudgeResult } from '../IdeIntegrationNudge.js';
+import { type CommandMigrationNudgeResult } from '../CommandFormatMigrationNudge.js';
 import { type FolderTrustChoice } from '../components/FolderTrustDialog.js';
 import {
   type AuthType,
@@ -47,6 +48,7 @@ export interface UIActions {
   setShellModeActive: (value: boolean) => void;
   vimHandleInput: (key: Key) => boolean;
   handleIdePromptComplete: (result: IdeIntegrationNudgeResult) => void;
+  handleCommandMigrationComplete: (result: CommandMigrationNudgeResult) => void;
   handleFolderTrustSelect: (choice: FolderTrustChoice) => void;
   setConstrainHeight: (value: boolean) => void;
   onEscapePromptChange: (show: boolean) => void;

packages/cli/src/ui/contexts/UIStateContext.tsx

@@ -72,6 +72,8 @@ export interface UIState {
   suggestionsWidth: number;
   isInputActive: boolean;
   shouldShowIdePrompt: boolean;
+  shouldShowCommandMigrationNudge: boolean;
+  commandMigrationTomlFiles: string[];
   isFolderTrustDialogOpen: boolean;
   isTrustedFolder: boolean | undefined;
   constrainHeight: boolean;

packages/cli/src/ui/hooks/useCommandMigration.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useEffect, useState } from 'react';
+import { Storage } from '@qwen-code/qwen-code-core';
+import { detectTomlCommands } from '../../services/command-migration-tool.js';
+import type { LoadedSettings } from '../../config/settings.js';
+
+/**
+ * Hook to detect TOML command files and manage migration nudge visibility.
+ * Checks all command directories: workspace, user, and global levels.
+ */
+export function useCommandMigration(
+  settings: LoadedSettings,
+  storage: Storage,
+) {
+  const [showMigrationNudge, setShowMigrationNudge] = useState(false);
+  const [tomlFiles, setTomlFiles] = useState<string[]>([]);
+
+  useEffect(() => {
+    const checkTomlCommands = async () => {
+      const allFiles: string[] = [];
+
+      // Check workspace commands directory (.qwen/commands)
+      const workspaceCommandsDir = storage.getProjectCommandsDir();
+      const workspaceFiles = await detectTomlCommands(workspaceCommandsDir);
+      allFiles.push(...workspaceFiles.map((f) => `workspace: ${f}`));
+
+      // Check user commands directory (~/.qwen/commands)
+      const userCommandsDir = Storage.getUserCommandsDir();
+      const userFiles = await detectTomlCommands(userCommandsDir);
+      allFiles.push(...userFiles.map((f) => `user: ${f}`));
+
+      if (allFiles.length > 0) {
+        setTomlFiles(allFiles);
+        setShowMigrationNudge(true);
+      }
+    };
+
+    checkTomlCommands();
+  }, [storage]);
+
+  return {
+    showMigrationNudge,
+    tomlFiles,
+    setShowMigrationNudge,
+  };
+}