mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-09-14 20:16:53 +08:00
Tabish Bidiwale
fb7ff527a6
* proposal: add artifact workflow CLI commands (Slice 4) Add CLI commands for artifact workflow operations: - `openspec status --change <id>` - Show artifact completion state - `openspec next --change <id>` - Show ready artifacts - `openspec instructions <artifact> --change <id>` - Get enriched template - `openspec templates --change <id>` - Show template paths - `openspec new change <name>` - Create new change Commands are top-level for fluid UX and implemented in isolation for easy removal (experimental feature). * fix: remove --change from templates command Templates are schema-level, not change-level. The command now uses --schema instead of --change for consistency with how templates are actually resolved. * rename: cli-workflow -> cli-artifact-workflow More specific capability name that clarifies which workflow the CLI commands are for. * feat: implement artifact workflow CLI commands (Slice 4) Add experimental CLI commands for artifact-based workflow management: - `openspec status --change <id>` - display artifact completion status - `openspec next --change <id>` - show artifacts ready to create - `openspec instructions <artifact> --change <id>` - output enriched template - `openspec templates [--schema <name>]` - show resolved template paths - `openspec new change <name>` - create new change directory Features: - JSON output support (--json flag) for all commands - Color-coded status indicators (green/yellow/red) - Progress spinners during loading - --no-color and NO_COLOR env support - --schema option for custom schema selection - Comprehensive error handling with helpful messages All commands are isolated in src/commands/artifact-workflow.ts for easy removal if the feature doesn't work out. Help text marks them as experimental. * fix: update specs glob to match nested directory structure The schema used specs/*.md but specs are stored as specs/<capability>/spec.md. Updated to specs/**/*.md so openspec status/next correctly detect spec completion. * test: update test to match new specs glob pattern * chore: archive add-artifact-workflow-cli change - Move change to archive/2025-12-28-add-artifact-workflow-cli - Create cli-artifact-workflow spec * feat: unify change state model for scaffolded changes - Update artifact workflow commands to work with scaffolded changes - Add draft changes section to dashboard view - Fix completed changes to require tasks.total > 0 - Archive unify-change-state-model change * fix: validate change name format to prevent path traversal Add validation in validateChangeExists() to ensure --change parameter is a valid kebab-case ID before constructing file paths. This prevents path traversal attacks like --change "../foo" or --change "/etc/passwd". - Reuses existing validateChangeName() from change-utils.ts - Adds 3 tests for path traversal, absolute paths, and slashes
130 lines
4.5 KiB
Markdown
130 lines
4.5 KiB
Markdown
# cli-view Specification
|
|
|
|
## Purpose
|
|
|
|
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.
|
|
## Requirements
|
|
### Requirement: Dashboard Display
|
|
|
|
The system SHALL provide a `view` command that displays a dashboard overview of specs and changes.
|
|
|
|
#### Scenario: Basic dashboard display
|
|
|
|
- **WHEN** user runs `openspec view`
|
|
- **THEN** system displays a formatted dashboard with sections for summary, active changes, completed changes, and specifications
|
|
|
|
#### Scenario: No OpenSpec directory
|
|
|
|
- **WHEN** user runs `openspec view` in a directory without OpenSpec
|
|
- **THEN** system displays error message "✗ No openspec directory found"
|
|
|
|
### Requirement: Summary Section
|
|
|
|
The dashboard SHALL display a summary section with key project metrics, including draft change count.
|
|
|
|
#### Scenario: Complete summary display
|
|
|
|
- **WHEN** dashboard is rendered with specs and changes
|
|
- **THEN** system shows total number of specifications and requirements
|
|
- **AND** shows number of draft changes
|
|
- **AND** shows number of active changes in progress
|
|
- **AND** shows number of completed changes
|
|
- **AND** shows overall task progress percentage
|
|
|
|
#### Scenario: Empty project summary
|
|
|
|
- **WHEN** no specs or changes exist
|
|
- **THEN** summary shows zero counts for all metrics
|
|
|
|
### Requirement: Active Changes Display
|
|
The dashboard SHALL show active changes with visual progress indicators.
|
|
|
|
#### Scenario: Active changes ordered by completion percentage
|
|
- **WHEN** multiple active changes are displayed with progress information
|
|
- **THEN** list them sorted by completion percentage ascending so 0% items appear first
|
|
- **AND** treat missing progress values as 0% for ordering
|
|
- **AND** break ties by change identifier in ascending alphabetical order to keep output deterministic
|
|
|
|
### Requirement: Completed Changes Display
|
|
|
|
The dashboard SHALL list completed changes in a separate section, only showing changes with ALL tasks completed.
|
|
|
|
> **Fixes bug**: Previously, changes with `total === 0` were incorrectly shown as completed.
|
|
|
|
#### Scenario: Completed changes listing
|
|
|
|
- **WHEN** there are changes with `tasks.total > 0` AND `tasks.completed === tasks.total`
|
|
- **THEN** system shows them with checkmark indicators in a dedicated section
|
|
|
|
#### Scenario: Mixed completion states
|
|
|
|
- **WHEN** some changes are complete and others active
|
|
- **THEN** system separates them into appropriate sections
|
|
|
|
#### Scenario: Empty changes not completed
|
|
|
|
- **WHEN** a change has no tasks.md or zero tasks defined
|
|
- **THEN** system does NOT show it in "Completed Changes" section
|
|
- **AND** shows it in "Draft Changes" section instead
|
|
|
|
### Requirement: Specifications Display
|
|
|
|
The dashboard SHALL display specifications sorted by requirement count.
|
|
|
|
#### Scenario: Specs listing with counts
|
|
|
|
- **WHEN** specifications exist in the project
|
|
- **THEN** system shows specs sorted by requirement count (descending) with count labels
|
|
|
|
#### Scenario: Specs with parsing errors
|
|
|
|
- **WHEN** a spec file cannot be parsed
|
|
- **THEN** system includes it with 0 requirement count
|
|
|
|
### Requirement: Visual Formatting
|
|
|
|
The dashboard SHALL use consistent visual formatting with colors and symbols.
|
|
|
|
#### Scenario: Color coding
|
|
|
|
- **WHEN** dashboard elements are displayed
|
|
- **THEN** system uses cyan for specification items
|
|
- **AND** yellow for active changes
|
|
- **AND** green for completed items
|
|
- **AND** dim gray for supplementary text
|
|
|
|
#### Scenario: Progress bar rendering
|
|
|
|
- **WHEN** displaying progress bars
|
|
- **THEN** system uses filled blocks (█) for completed portions and light blocks (░) for remaining
|
|
|
|
### Requirement: Error Handling
|
|
|
|
The view command SHALL handle errors gracefully.
|
|
|
|
#### Scenario: File system errors
|
|
|
|
- **WHEN** file system operations fail
|
|
- **THEN** system continues with available data and omits inaccessible items
|
|
|
|
#### Scenario: Invalid data structures
|
|
|
|
- **WHEN** specs or changes have invalid format
|
|
- **THEN** system skips invalid items and continues rendering
|
|
|
|
### Requirement: Draft Changes Display
|
|
|
|
The dashboard SHALL display changes without tasks in a separate "Draft" section.
|
|
|
|
#### Scenario: Draft changes listing
|
|
|
|
- **WHEN** there are changes with no tasks.md or zero tasks defined
|
|
- **THEN** system shows them in a "Draft Changes" section
|
|
- **AND** uses a distinct indicator (e.g., `○`) to show draft status
|
|
|
|
#### Scenario: Draft section ordering
|
|
|
|
- **WHEN** multiple draft changes exist
|
|
- **THEN** system sorts them alphabetically by name
|
|
|