Skip to content

Commit ccaa5ad

Browse files
TabishBTabishB
committed
feat: add openspec view dashboard command
1 parent be395d9 commit ccaa5ad

File tree

6 files changed

+503
-0
lines changed

6 files changed

+503
-0
lines changed

‎openspec/changes/archive/2025-09-12-add-view-dashboard-command/proposal.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Change: Add View Dashboard Command
2+
3+
## Why
4+
5+
Users need a quick, at-a-glance overview of their OpenSpec project status without running multiple commands. Currently, users must run `openspec list --changes` and `openspec list --specs` separately to understand the project state. A unified dashboard view would improve developer experience and provide immediate insight into project progress.
6+
7+
## What Changes
8+
9+
### Added `openspec view` Command
10+
11+
The new command provides an interactive dashboard displaying:
12+
- Summary metrics (total specs, requirements, changes, task progress)
13+
- Active changes with visual progress bars
14+
- Completed changes
15+
- Specifications with requirement counts
16+
17+
### Specifications Affected
18+
19+
- **cli-view** (NEW): Complete specification for the view dashboard command
20+
21+
## Implementation Details
22+
23+
### File Structure
24+
- Created `/src/core/view.ts` implementing the `ViewCommand` class
25+
- Registered command in `/src/cli/index.ts`
26+
- Reuses existing utilities from `task-progress.ts` and `MarkdownParser`
27+
28+
### Visual Design
29+
- Uses Unicode box drawing characters for borders
30+
- Color coding: cyan for specs, yellow for active, green for completed
31+
- Progress bars using filled (█) and empty (░) blocks
32+
- Clean alignment with proper padding
33+
34+
### Technical Approach
35+
- Async data fetching from changes and specs directories
36+
- Parallel processing of specs and changes
37+
- Error handling for missing or invalid data
38+
- Maintains consistency with existing list command output

‎openspec/changes/archive/2025-09-12-add-view-dashboard-command/specs/cli-view/spec.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# CLI View Command - Changes
2+
3+
## ADDED Requirements
4+
5+
### Requirement: Dashboard Display
6+
7+
The system SHALL provide a `view` command that displays a dashboard overview of specs and changes.
8+
9+
#### Scenario: Basic dashboard display
10+
11+
- **WHEN** user runs `openspec view`
12+
- **THEN** system displays a formatted dashboard with sections for summary, active changes, completed changes, and specifications
13+
14+
#### Scenario: No OpenSpec directory
15+
16+
- **WHEN** user runs `openspec view` in a directory without OpenSpec
17+
- **THEN** system displays error message "✗ No openspec directory found"
18+
19+
### Requirement: Summary Section
20+
21+
The dashboard SHALL display a summary section with key project metrics.
22+
23+
#### Scenario: Complete summary display
24+
25+
- **WHEN** dashboard is rendered with specs and changes
26+
- **THEN** system shows total number of specifications and requirements
27+
- **AND** shows number of active changes in progress
28+
- **AND** shows number of completed changes
29+
- **AND** shows overall task progress percentage
30+
31+
#### Scenario: Empty project summary
32+
33+
- **WHEN** no specs or changes exist
34+
- **THEN** summary shows zero counts for all metrics
35+
36+
### Requirement: Active Changes Display
37+
38+
The dashboard SHALL show active changes with visual progress indicators.
39+
40+
#### Scenario: Active changes with progress bars
41+
42+
- **WHEN** there are in-progress changes with tasks
43+
- **THEN** system displays each change with change name left-aligned
44+
- **AND** visual progress bar using Unicode characters
45+
- **AND** percentage completion on the right
46+
47+
#### Scenario: No active changes
48+
49+
- **WHEN** all changes are completed or no changes exist
50+
- **THEN** active changes section is omitted from display
51+
52+
### Requirement: Completed Changes Display
53+
54+
The dashboard SHALL list completed changes in a separate section.
55+
56+
#### Scenario: Completed changes listing
57+
58+
- **WHEN** there are completed changes (all tasks done)
59+
- **THEN** system shows them with checkmark indicators in a dedicated section
60+
61+
#### Scenario: Mixed completion states
62+
63+
- **WHEN** some changes are complete and others active
64+
- **THEN** system separates them into appropriate sections
65+
66+
### Requirement: Specifications Display
67+
68+
The dashboard SHALL display specifications sorted by requirement count.
69+
70+
#### Scenario: Specs listing with counts
71+
72+
- **WHEN** specifications exist in the project
73+
- **THEN** system shows specs sorted by requirement count (descending) with count labels
74+
75+
#### Scenario: Specs with parsing errors
76+
77+
- **WHEN** a spec file cannot be parsed
78+
- **THEN** system includes it with 0 requirement count
79+
80+
### Requirement: Visual Formatting
81+
82+
The dashboard SHALL use consistent visual formatting with colors and symbols.
83+
84+
#### Scenario: Color coding
85+
86+
- **WHEN** dashboard elements are displayed
87+
- **THEN** system uses cyan for specification items
88+
- **AND** yellow for active changes
89+
- **AND** green for completed items
90+
- **AND** dim gray for supplementary text
91+
92+
#### Scenario: Progress bar rendering
93+
94+
- **WHEN** displaying progress bars
95+
- **THEN** system uses filled blocks (█) for completed portions and light blocks (░) for remaining
96+
97+
### Requirement: Error Handling
98+
99+
The view command SHALL handle errors gracefully.
100+
101+
#### Scenario: File system errors
102+
103+
- **WHEN** file system operations fail
104+
- **THEN** system continues with available data and omits inaccessible items
105+
106+
#### Scenario: Invalid data structures
107+
108+
- **WHEN** specs or changes have invalid format
109+
- **THEN** system skips invalid items and continues rendering

‎openspec/changes/archive/2025-09-12-add-view-dashboard-command/tasks.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Implementation Tasks
2+
3+
## Design Phase
4+
- [x] Research existing list command implementation
5+
- [x] Design dashboard layout and information architecture
6+
- [x] Choose appropriate command verb (`view`)
7+
- [x] Define visual elements (progress bars, colors, layout)
8+
9+
## Core Implementation
10+
- [x] Create ViewCommand class in `/src/core/view.ts`
11+
- [x] Implement getChangesData method for fetching change information
12+
- [x] Implement getSpecsData method for fetching spec information
13+
- [x] Implement displaySummary method for summary metrics
14+
- [x] Add progress bar visualization with Unicode characters
15+
- [x] Implement color coding using chalk
16+
17+
## Integration
18+
- [x] Import ViewCommand in CLI index
19+
- [x] Register `openspec view` command with commander
20+
- [x] Add proper error handling and ora spinner integration
21+
- [x] Ensure command appears in help documentation
22+
23+
## Data Processing
24+
- [x] Reuse TaskProgress utilities for change progress
25+
- [x] Integrate MarkdownParser for spec requirement counting
26+
- [x] Handle async operations for file system access
27+
- [x] Sort specifications by requirement count
28+
29+
## Testing and Validation
30+
- [x] Build project successfully with new command
31+
- [x] Test command with sample data
32+
- [x] Verify correct requirement counts match list --specs
33+
- [x] Test progress bar display for various completion states
34+
- [x] Run existing test suite to ensure no regressions
35+
- [x] Verify TypeScript compilation with no errors
36+
37+
## Documentation
38+
- [x] Add command description in CLI help
39+
- [x] Create change proposal documentation
40+
- [x] Update README with view command example (if needed)
41+
- [x] Add view command to user documentation (if exists)
42+
43+
## Polish
44+
- [x] Ensure consistent formatting and alignment
45+
- [x] Add helpful footer text referencing list commands
46+
- [x] Optimize for terminal width considerations
47+
- [x] Review and refine color choices for accessibility

‎openspec/specs/cli-view/spec.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# cli-view Specification
2+
3+
## Purpose
4+
5+
The `openspec view` command provides a comprehensive dashboard view of the OpenSpec project state, displaying specifications, changes, and progress metrics in a unified, visually appealing format to help developers quickly understand project status.
6+
## Requirements
7+
### Requirement: Dashboard Display
8+
9+
The system SHALL provide a `view` command that displays a dashboard overview of specs and changes.
10+
11+
#### Scenario: Basic dashboard display
12+
13+
- **WHEN** user runs `openspec view`
14+
- **THEN** system displays a formatted dashboard with sections for summary, active changes, completed changes, and specifications
15+
16+
#### Scenario: No OpenSpec directory
17+
18+
- **WHEN** user runs `openspec view` in a directory without OpenSpec
19+
- **THEN** system displays error message "✗ No openspec directory found"
20+
21+
### Requirement: Summary Section
22+
23+
The dashboard SHALL display a summary section with key project metrics.
24+
25+
#### Scenario: Complete summary display
26+
27+
- **WHEN** dashboard is rendered with specs and changes
28+
- **THEN** system shows total number of specifications and requirements
29+
- **AND** shows number of active changes in progress
30+
- **AND** shows number of completed changes
31+
- **AND** shows overall task progress percentage
32+
33+
#### Scenario: Empty project summary
34+
35+
- **WHEN** no specs or changes exist
36+
- **THEN** summary shows zero counts for all metrics
37+
38+
### Requirement: Active Changes Display
39+
40+
The dashboard SHALL show active changes with visual progress indicators.
41+
42+
#### Scenario: Active changes with progress bars
43+
44+
- **WHEN** there are in-progress changes with tasks
45+
- **THEN** system displays each change with change name left-aligned
46+
- **AND** visual progress bar using Unicode characters
47+
- **AND** percentage completion on the right
48+
49+
#### Scenario: No active changes
50+
51+
- **WHEN** all changes are completed or no changes exist
52+
- **THEN** active changes section is omitted from display
53+
54+
### Requirement: Completed Changes Display
55+
56+
The dashboard SHALL list completed changes in a separate section.
57+
58+
#### Scenario: Completed changes listing
59+
60+
- **WHEN** there are completed changes (all tasks done)
61+
- **THEN** system shows them with checkmark indicators in a dedicated section
62+
63+
#### Scenario: Mixed completion states
64+
65+
- **WHEN** some changes are complete and others active
66+
- **THEN** system separates them into appropriate sections
67+
68+
### Requirement: Specifications Display
69+
70+
The dashboard SHALL display specifications sorted by requirement count.
71+
72+
#### Scenario: Specs listing with counts
73+
74+
- **WHEN** specifications exist in the project
75+
- **THEN** system shows specs sorted by requirement count (descending) with count labels
76+
77+
#### Scenario: Specs with parsing errors
78+
79+
- **WHEN** a spec file cannot be parsed
80+
- **THEN** system includes it with 0 requirement count
81+
82+
### Requirement: Visual Formatting
83+
84+
The dashboard SHALL use consistent visual formatting with colors and symbols.
85+
86+
#### Scenario: Color coding
87+
88+
- **WHEN** dashboard elements are displayed
89+
- **THEN** system uses cyan for specification items
90+
- **AND** yellow for active changes
91+
- **AND** green for completed items
92+
- **AND** dim gray for supplementary text
93+
94+
#### Scenario: Progress bar rendering
95+
96+
- **WHEN** displaying progress bars
97+
- **THEN** system uses filled blocks (█) for completed portions and light blocks (░) for remaining
98+
99+
### Requirement: Error Handling
100+
101+
The view command SHALL handle errors gracefully.
102+
103+
#### Scenario: File system errors
104+
105+
- **WHEN** file system operations fail
106+
- **THEN** system continues with available data and omits inaccessible items
107+
108+
#### Scenario: Invalid data structures
109+
110+
- **WHEN** specs or changes have invalid format
111+
- **THEN** system skips invalid items and continues rendering
112+

‎src/cli/index.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import { InitCommand } from '../core/init.js';
77
import { UpdateCommand } from '../core/update.js';
88
import { ListCommand } from '../core/list.js';
99
import { ArchiveCommand } from '../core/archive.js';
10+
import { ViewCommand } from '../core/view.js';
1011
import { registerSpecCommand } from '../commands/spec.js';
1112
import { ChangeCommand } from '../commands/change.js';
1213
import { ValidateCommand } from '../commands/validate.js';
@@ -97,6 +98,20 @@ program
9798
}
9899
});
99100

101+
program
102+
.command('view')
103+
.description('Display an interactive dashboard of specs and changes')
104+
.action(async () => {
105+
try {
106+
const viewCommand = new ViewCommand();
107+
await viewCommand.execute('.');
108+
} catch (error) {
109+
console.log(); // Empty line for spacing
110+
ora().fail(`Error: ${(error as Error).message}`);
111+
process.exit(1);
112+
}
113+
});
114+
100115
// Change command with subcommands
101116
const changeCmd = program
102117
.command('change')

0 commit comments

Comments
 (0)