refactor: use @inquirer/prompts for consistent UX in archive command

- Replace readline with @inquirer/prompts for all user interactions
- Add arrow key navigation for change selection (consistent with diff command)
- Use confirm() for yes/no prompts with better UX
- Remove manual readline interface management (no longer needed)
- Update tests to mock @inquirer/prompts instead of readline
- Add new test cases for interactive mode behavior

This change provides a consistent user experience across all OpenSpec commands,
where users can navigate options with arrow keys rather than typing numbers.

openspec/changes/add-list-command/tasks.md

@@ -1,26 +0,0 @@
-# Implementation Tasks
-
-## 1. Core Implementation
-- [ ] 1.1 Create `src/core/list.ts` with list logic
-  - [ ] 1.1.1 Implement directory scanning (exclude archive/)
-  - [ ] 1.1.2 Implement task counting from tasks.md files
-  - [ ] 1.1.3 Format output as simple table
-- [ ] 1.2 Add list command to CLI in `src/cli/index.ts`
-  - [ ] 1.2.1 Register `openspec list` command
-  - [ ] 1.2.2 Connect to list.ts implementation
-
-## 2. Error Handling
-- [ ] 2.1 Handle missing openspec/changes/ directory
-- [ ] 2.2 Handle changes without tasks.md files
-- [ ] 2.3 Handle empty changes directory
-
-## 3. Testing
-- [ ] 3.1 Add tests for list functionality
-  - [ ] 3.1.1 Test with multiple changes
-  - [ ] 3.1.2 Test with completed changes
-  - [ ] 3.1.3 Test with no changes
-  - [ ] 3.1.4 Test error conditions
-
-## 4. Documentation
-- [ ] 4.1 Update CLI help text with list command
-- [ ] 4.2 Add list command to README if applicable

openspec/changes/archive/2025-01-13-add-list-command/tasks.md

@@ -0,0 +1,26 @@
+# Implementation Tasks
+
+## 1. Core Implementation
+- [x] 1.1 Create `src/core/list.ts` with list logic
+  - [x] 1.1.1 Implement directory scanning (exclude archive/)
+  - [x] 1.1.2 Implement task counting from tasks.md files
+  - [x] 1.1.3 Format output as simple table
+- [x] 1.2 Add list command to CLI in `src/cli/index.ts`
+  - [x] 1.2.1 Register `openspec list` command
+  - [x] 1.2.2 Connect to list.ts implementation
+
+## 2. Error Handling
+- [x] 2.1 Handle missing openspec/changes/ directory
+- [x] 2.2 Handle changes without tasks.md files
+- [x] 2.3 Handle empty changes directory
+
+## 3. Testing
+- [x] 3.1 Add tests for list functionality
+  - [x] 3.1.1 Test with multiple changes
+  - [x] 3.1.2 Test with completed changes
+  - [x] 3.1.3 Test with no changes
+  - [x] 3.1.4 Test error conditions
+
+## 4. Documentation
+- [x] 4.1 Update CLI help text with list command
+- [x] 4.2 Add list command to README if applicable

openspec/specs/cli-list/spec.md

@@ -0,0 +1,69 @@
+# List Command Specification
+
+## Purpose
+
+The `openspec list` command SHALL provide developers with a quick overview of all active changes in the project, showing their names and task completion status.
+
+## Behavior
+
+### Command Execution
+
+WHEN `openspec list` is executed
+THEN scan the `openspec/changes/` directory for change directories
+AND exclude the `archive/` subdirectory from results
+AND parse each change's `tasks.md` file to count task completion
+
+### Task Counting
+
+WHEN parsing a `tasks.md` file
+THEN count tasks matching these patterns:
+- Completed: Lines containing `- [x]`
+- Incomplete: Lines containing `- [ ]`
+AND calculate total tasks as the sum of completed and incomplete
+
+### Output Format
+
+WHEN displaying the list
+THEN show a table with columns:
+- Change name (directory name)
+- Task progress (e.g., "3/5 tasks" or "✓ Complete")
+- Status indicator:
+  - `✓` for fully completed changes (all tasks done)
+  - Progress fraction for partial completion
+
+Example output:
+```
+Changes:
+  add-auth-feature     3/5 tasks
+  update-api-docs      ✓ Complete
+  fix-validation       0/2 tasks
+  add-list-command     1/4 tasks
+```
+
+### Empty State
+
+WHEN no active changes exist (only archive/ or empty changes/)
+THEN display: "No active changes found."
+
+### Error Handling
+
+IF a change directory has no `tasks.md` file
+THEN display the change with "No tasks" status
+
+IF `openspec/changes/` directory doesn't exist
+THEN display error: "No OpenSpec changes directory found. Run 'openspec init' first."
+AND exit with code 1
+
+### Sorting
+
+Changes SHALL be displayed in alphabetical order by change name for consistency.
+
+## Why
+
+Developers need a quick way to:
+- See what changes are in progress
+- Identify which changes are ready to archive
+- Understand the overall project evolution status
+- Get a bird's-eye view without opening multiple files
+
+This command provides that visibility with minimal effort, following OpenSpec's philosophy of simplicity and clarity.

src/cli/index.ts

@@ -6,6 +6,7 @@ import { InitCommand } from '../core/init.js';
 import { UpdateCommand } from '../core/update.js';
 import { DiffCommand } from '../core/diff.js';
 import { ListCommand } from '../core/list.js';
+import { ArchiveCommand } from '../core/archive.js';
 
 const program = new Command();
 
@@ -90,4 +91,19 @@ program
     }
   });
 
+program
+  .command('archive [change-name]')
+  .description('Archive a completed change and update main specs')
+  .option('-y, --yes', 'Skip confirmation prompts')
+  .action(async (changeName?: string, options?: { yes?: boolean }) => {
+    try {
+      const archiveCommand = new ArchiveCommand();
+      await archiveCommand.execute(changeName, options);
+    } catch (error) {
+      console.log(); // Empty line for spacing
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
 program.parse();

src/core/archive.ts

@@ -0,0 +1,224 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { select, confirm } from '@inquirer/prompts';
+import { FileSystemUtils } from '../utils/file-system.js';
+
+interface SpecUpdate {
+  source: string;
+  target: string;
+  exists: boolean;
+}
+
+export class ArchiveCommand {
+  async execute(changeName?: string, options: { yes?: boolean } = {}): Promise<void> {
+    const targetPath = '.';
+    const changesDir = path.join(targetPath, 'openspec', 'changes');
+    const archiveDir = path.join(changesDir, 'archive');
+    const mainSpecsDir = path.join(targetPath, 'openspec', 'specs');
+
+    // Check if changes directory exists
+    try {
+      await fs.access(changesDir);
+    } catch {
+      throw new Error("No OpenSpec changes directory found. Run 'openspec init' first.");
+    }
+
+    // Get change name interactively if not provided
+    if (!changeName) {
+      const selectedChange = await this.selectChange(changesDir);
+      if (!selectedChange) {
+        console.log('No change selected. Aborting.');
+        return;
+      }
+      changeName = selectedChange;
+    }
+
+    const changeDir = path.join(changesDir, changeName);
+
+    // Verify change exists
+    try {
+      const stat = await fs.stat(changeDir);
+      if (!stat.isDirectory()) {
+        throw new Error(`Change '${changeName}' not found.`);
+      }
+    } catch {
+      throw new Error(`Change '${changeName}' not found.`);
+    }
+
+    // Check for incomplete tasks
+    const tasksPath = path.join(changeDir, 'tasks.md');
+    const incompleteTasks = await this.checkIncompleteTasks(tasksPath);
+    
+    if (incompleteTasks > 0) {
+      if (!options.yes) {
+        const proceed = await confirm({
+          message: `Warning: ${incompleteTasks} incomplete task(s) found. Continue?`,
+          default: false
+        });
+        if (!proceed) {
+          console.log('Archive cancelled.');
+          return;
+        }
+      } else {
+        console.log(`Warning: ${incompleteTasks} incomplete task(s) found. Continuing due to --yes flag.`);
+      }
+    }
+
+    // Find specs to update
+    const specUpdates = await this.findSpecUpdates(changeDir, mainSpecsDir);
+    
+    if (specUpdates.length > 0) {
+      console.log('\nSpecs to update:');
+      for (const update of specUpdates) {
+        const status = update.exists ? 'update' : 'create';
+        const capability = path.basename(path.dirname(update.target));
+        console.log(`  ${capability}: ${status}`);
+      }
+
+      if (!options.yes) {
+        const proceed = await confirm({
+          message: 'Proceed with spec updates?',
+          default: true
+        });
+        if (!proceed) {
+          console.log('Archive cancelled.');
+          return;
+        }
+      }
+
+      // Update specs
+      for (const update of specUpdates) {
+        await this.updateSpec(update);
+      }
+      console.log('Specs updated successfully.');
+    }
+
+    // Create archive directory with date prefix
+    const archiveName = `${this.getArchiveDate()}-${changeName}`;
+    const archivePath = path.join(archiveDir, archiveName);
+
+    // Check if archive already exists
+    try {
+      await fs.access(archivePath);
+      throw new Error(`Archive '${archiveName}' already exists.`);
+    } catch (error: any) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+    }
+
+    // Create archive directory if needed
+    await fs.mkdir(archiveDir, { recursive: true });
+
+    // Move change to archive
+    await fs.rename(changeDir, archivePath);
+    
+    console.log(`Change '${changeName}' archived as '${archiveName}'.`);
+  }
+
+  private async selectChange(changesDir: string): Promise<string | null> {
+    // Get all directories in changes (excluding archive)
+    const entries = await fs.readdir(changesDir, { withFileTypes: true });
+    const changeDirs = entries
+      .filter(entry => entry.isDirectory() && entry.name !== 'archive')
+      .map(entry => entry.name)
+      .sort();
+
+    if (changeDirs.length === 0) {
+      console.log('No active changes found.');
+      return null;
+    }
+
+    console.log('Available changes:');
+    const choices = changeDirs.map(name => ({
+      name: name,
+      value: name
+    }));
+
+    try {
+      const answer = await select({
+        message: 'Select a change to archive',
+        choices
+      });
+      return answer;
+    } catch (error) {
+      // User cancelled (Ctrl+C)
+      return null;
+    }
+  }
+
+  private async checkIncompleteTasks(tasksPath: string): Promise<number> {
+    try {
+      const content = await fs.readFile(tasksPath, 'utf-8');
+      const lines = content.split('\n');
+      let incompleteTasks = 0;
+      
+      for (const line of lines) {
+        if (line.includes('- [ ]')) {
+          incompleteTasks++;
+        }
+      }
+      
+      return incompleteTasks;
+    } catch {
+      // No tasks.md file or error reading it
+      return 0;
+    }
+  }
+
+  private async findSpecUpdates(changeDir: string, mainSpecsDir: string): Promise<SpecUpdate[]> {
+    const updates: SpecUpdate[] = [];
+    const changeSpecsDir = path.join(changeDir, 'specs');
+
+    try {
+      const entries = await fs.readdir(changeSpecsDir, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const specFile = path.join(changeSpecsDir, entry.name, 'spec.md');
+          const targetFile = path.join(mainSpecsDir, entry.name, 'spec.md');
+          
+          try {
+            await fs.access(specFile);
+            
+            // Check if target exists
+            let exists = false;
+            try {
+              await fs.access(targetFile);
+              exists = true;
+            } catch {
+              exists = false;
+            }
+
+            updates.push({
+              source: specFile,
+              target: targetFile,
+              exists
+            });
+          } catch {
+            // Source spec doesn't exist, skip
+          }
+        }
+      }
+    } catch {
+      // No specs directory in change
+    }
+
+    return updates;
+  }
+
+  private async updateSpec(update: SpecUpdate): Promise<void> {
+    // Create target directory if needed
+    const targetDir = path.dirname(update.target);
+    await fs.mkdir(targetDir, { recursive: true });
+
+    // Copy spec file
+    const content = await fs.readFile(update.source, 'utf-8');
+    await fs.writeFile(update.target, content);
+  }
+
+  private getArchiveDate(): string {
+    // Returns date in YYYY-MM-DD format
+    return new Date().toISOString().split('T')[0];
+  }
+}

src/core/diff.ts

@@ -82,7 +82,7 @@ export class DiffCommand {
       choices
     });
 
-    return answer;
+    return answer as string;
   }
 
   private async showDiffs(changeSpecsDir: string): Promise<void> {

src/core/init.ts

@@ -64,7 +64,7 @@ export class InitCommand {
       }))
     });
     
-    config.aiTools = [selectedTool];
+    config.aiTools = [selectedTool as string];
 
     return config;
   }

test/core/archive.test.ts

@@ -0,0 +1,269 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { ArchiveCommand } from '../../src/core/archive.js';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+
+// Mock @inquirer/prompts
+vi.mock('@inquirer/prompts', () => ({
+  select: vi.fn(),
+  confirm: vi.fn()
+}));
+
+describe('ArchiveCommand', () => {
+  let tempDir: string;
+  let archiveCommand: ArchiveCommand;
+  const originalConsoleLog = console.log;
+
+  beforeEach(async () => {
+    // Create temp directory
+    tempDir = path.join(os.tmpdir(), `openspec-archive-test-${Date.now()}`);
+    await fs.mkdir(tempDir, { recursive: true });
+    
+    // Change to temp directory
+    process.chdir(tempDir);
+    
+    // Create OpenSpec structure
+    const openspecDir = path.join(tempDir, 'openspec');
+    await fs.mkdir(path.join(openspecDir, 'changes'), { recursive: true });
+    await fs.mkdir(path.join(openspecDir, 'specs'), { recursive: true });
+    await fs.mkdir(path.join(openspecDir, 'changes', 'archive'), { recursive: true });
+    
+    // Suppress console.log during tests
+    console.log = vi.fn();
+    
+    archiveCommand = new ArchiveCommand();
+  });
+
+  afterEach(async () => {
+    // Restore console.log
+    console.log = originalConsoleLog;
+    
+    // Clear mocks
+    vi.clearAllMocks();
+    
+    // Clean up temp directory
+    try {
+      await fs.rm(tempDir, { recursive: true, force: true });
+    } catch (error) {
+      // Ignore cleanup errors
+    }
+  });
+
+  describe('execute', () => {
+    it('should archive a change successfully', async () => {
+      // Create a test change
+      const changeName = 'test-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Create tasks.md with completed tasks
+      const tasksContent = '- [x] Task 1\n- [x] Task 2';
+      await fs.writeFile(path.join(changeDir, 'tasks.md'), tasksContent);
+      
+      // Execute archive with --yes flag
+      await archiveCommand.execute(changeName, { yes: true });
+      
+      // Check that change was moved to archive
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      
+      expect(archives.length).toBe(1);
+      expect(archives[0]).toMatch(new RegExp(`\\d{4}-\\d{2}-\\d{2}-${changeName}`));
+      
+      // Verify original change directory no longer exists
+      await expect(fs.access(changeDir)).rejects.toThrow();
+    });
+
+    it('should warn about incomplete tasks', async () => {
+      const changeName = 'incomplete-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Create tasks.md with incomplete tasks
+      const tasksContent = '- [x] Task 1\n- [ ] Task 2\n- [ ] Task 3';
+      await fs.writeFile(path.join(changeDir, 'tasks.md'), tasksContent);
+      
+      // Execute archive with --yes flag
+      await archiveCommand.execute(changeName, { yes: true });
+      
+      // Verify warning was logged
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringContaining('Warning: 2 incomplete task(s) found')
+      );
+    });
+
+    it('should update specs when archiving', async () => {
+      const changeName = 'spec-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      const changeSpecDir = path.join(changeDir, 'specs', 'test-capability');
+      await fs.mkdir(changeSpecDir, { recursive: true });
+      
+      // Create spec in change
+      const specContent = '# Test Capability Spec\n\nTest content';
+      await fs.writeFile(path.join(changeSpecDir, 'spec.md'), specContent);
+      
+      // Execute archive with --yes flag
+      await archiveCommand.execute(changeName, { yes: true });
+      
+      // Verify spec was copied to main specs
+      const mainSpecPath = path.join(tempDir, 'openspec', 'specs', 'test-capability', 'spec.md');
+      const copiedContent = await fs.readFile(mainSpecPath, 'utf-8');
+      expect(copiedContent).toBe(specContent);
+    });
+
+    it('should throw error if change does not exist', async () => {
+      await expect(
+        archiveCommand.execute('non-existent-change', { yes: true })
+      ).rejects.toThrow("Change 'non-existent-change' not found.");
+    });
+
+    it('should throw error if archive already exists', async () => {
+      const changeName = 'duplicate-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Create existing archive with same date
+      const date = new Date().toISOString().split('T')[0];
+      const archivePath = path.join(tempDir, 'openspec', 'changes', 'archive', `${date}-${changeName}`);
+      await fs.mkdir(archivePath, { recursive: true });
+      
+      // Try to archive
+      await expect(
+        archiveCommand.execute(changeName, { yes: true })
+      ).rejects.toThrow(`Archive '${date}-${changeName}' already exists.`);
+    });
+
+    it('should handle changes without tasks.md', async () => {
+      const changeName = 'no-tasks-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Execute archive without tasks.md
+      await archiveCommand.execute(changeName, { yes: true });
+      
+      // Should complete without warnings
+      expect(console.log).not.toHaveBeenCalledWith(
+        expect.stringContaining('incomplete task(s)')
+      );
+      
+      // Verify change was archived
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      expect(archives.length).toBe(1);
+    });
+
+    it('should handle changes without specs', async () => {
+      const changeName = 'no-specs-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Execute archive without specs
+      await archiveCommand.execute(changeName, { yes: true });
+      
+      // Should complete without spec updates
+      expect(console.log).not.toHaveBeenCalledWith(
+        expect.stringContaining('Specs to update')
+      );
+      
+      // Verify change was archived
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      expect(archives.length).toBe(1);
+    });
+  });
+
+  describe('error handling', () => {
+    it('should throw error when openspec directory does not exist', async () => {
+      // Remove openspec directory
+      await fs.rm(path.join(tempDir, 'openspec'), { recursive: true });
+      
+      await expect(
+        archiveCommand.execute('any-change', { yes: true })
+      ).rejects.toThrow("No OpenSpec changes directory found. Run 'openspec init' first.");
+    });
+  });
+
+  describe('interactive mode', () => {
+    it('should use select prompt for change selection', async () => {
+      const { select } = await import('@inquirer/prompts');
+      const mockSelect = select as unknown as ReturnType<typeof vi.fn>;
+      
+      // Create test changes
+      const change1 = 'feature-a';
+      const change2 = 'feature-b';
+      await fs.mkdir(path.join(tempDir, 'openspec', 'changes', change1), { recursive: true });
+      await fs.mkdir(path.join(tempDir, 'openspec', 'changes', change2), { recursive: true });
+      
+      // Mock select to return first change
+      mockSelect.mockResolvedValueOnce(change1);
+      
+      // Execute without change name
+      await archiveCommand.execute(undefined, { yes: true });
+      
+      // Verify select was called with correct options
+      expect(mockSelect).toHaveBeenCalledWith({
+        message: 'Select a change to archive',
+        choices: [
+          { name: change1, value: change1 },
+          { name: change2, value: change2 }
+        ]
+      });
+      
+      // Verify the selected change was archived
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      expect(archives[0]).toContain(change1);
+    });
+
+    it('should use confirm prompt for task warnings', async () => {
+      const { confirm } = await import('@inquirer/prompts');
+      const mockConfirm = confirm as unknown as ReturnType<typeof vi.fn>;
+      
+      const changeName = 'incomplete-interactive';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Create tasks.md with incomplete tasks
+      const tasksContent = '- [ ] Task 1';
+      await fs.writeFile(path.join(changeDir, 'tasks.md'), tasksContent);
+      
+      // Mock confirm to return true (proceed)
+      mockConfirm.mockResolvedValueOnce(true);
+      
+      // Execute without --yes flag
+      await archiveCommand.execute(changeName);
+      
+      // Verify confirm was called
+      expect(mockConfirm).toHaveBeenCalledWith({
+        message: 'Warning: 1 incomplete task(s) found. Continue?',
+        default: false
+      });
+    });
+
+    it('should cancel when user declines task warning', async () => {
+      const { confirm } = await import('@inquirer/prompts');
+      const mockConfirm = confirm as unknown as ReturnType<typeof vi.fn>;
+      
+      const changeName = 'cancel-test';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Create tasks.md with incomplete tasks
+      const tasksContent = '- [ ] Task 1';
+      await fs.writeFile(path.join(changeDir, 'tasks.md'), tasksContent);
+      
+      // Mock confirm to return false (cancel)
+      mockConfirm.mockResolvedValueOnce(false);
+      
+      // Execute without --yes flag
+      await archiveCommand.execute(changeName);
+      
+      // Verify archive was cancelled
+      expect(console.log).toHaveBeenCalledWith('Archive cancelled.');
+      
+      // Verify change was not archived
+      await expect(fs.access(changeDir)).resolves.not.toThrow();
+    });
+  });
+});