mirror of https://github.com/Fission-AI/OpenSpec.git synced 2026-09-14 20:16:53 +08:00

Files

T

Tabish Bidiwale fb7ff527a6 proposal: add artifact workflow CLI commands (Slice 4) (#415 )

* 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

2025-12-29 16:55:56 +11:00

4.5 KiB

Raw Permalink Blame History

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

4.5 KiB Raw Permalink Blame History