sauron-cli 1.1.3 → 1.3.0

package/OpenSpec-main/openspec/specs/ci-nix-validation/spec.md

@@ -0,0 +1,107 @@
+# ci-nix-validation Specification
+
+## Purpose
+
+Validates Nix flake builds and maintenance scripts in CI to ensure Nix users can reliably install and use OpenSpec. Prevents regressions in Nix support by testing builds and the update-flake.sh script on every pull request and push to main.
+## Requirements
+### Requirement: Nix Flake Build Validation
+
+The CI system SHALL validate that the Nix flake builds successfully on every pull request and push to main.
+
+#### Scenario: Successful flake build
+
+- **WHEN** a pull request or push to main is made
+- **THEN** the CI SHALL execute `nix build` and verify it completes with exit code 0
+- **AND** the build output SHALL contain the openspec binary
+
+#### Scenario: Flake build failure
+
+- **WHEN** the Nix flake configuration is broken
+- **THEN** the CI job SHALL fail with a non-zero exit code
+- **AND** the CI SHALL prevent merging of the pull request
+
+#### Scenario: Multi-platform support check
+
+- **WHEN** the flake declares support for multiple systems
+- **THEN** the CI SHALL validate the flake builds on at least Linux (x86_64-linux)
+
+### Requirement: Update Script Validation
+
+The CI system SHALL validate that the update-flake.sh script executes successfully and produces valid output.
+
+#### Scenario: Update script execution
+
+- **WHEN** the CI runs the update script validation
+- **THEN** the script SHALL execute without errors
+- **AND** the script SHALL correctly read the version from package.json
+- **AND** the script SHALL validate that flake.nix uses dynamic version from package.json
+
+#### Scenario: Update script with mock hash
+
+- **WHEN** validating the update script in CI
+- **THEN** the script SHALL be able to detect and extract the correct pnpm dependency hash
+- **AND** the flake.nix SHALL be updated with a valid sha256 hash
+
+### Requirement: CI Job Integration
+
+The Nix validation jobs SHALL be integrated into the existing GitHub Actions workflow and required for merge.
+
+#### Scenario: PR merge requirements
+
+- **WHEN** a pull request is created
+- **THEN** the Nix validation job SHALL be included in required checks
+- **AND** the PR SHALL NOT be mergeable until Nix validation passes
+
+#### Scenario: Job execution triggers
+
+- **WHEN** code is pushed to a pull request OR pushed to main OR manually triggered
+- **THEN** the Nix validation job SHALL execute automatically
+
+### Requirement: Local Testing Support
+
+The CI workflow SHALL be testable locally using the `act` tool to enable rapid iteration.
+
+#### Scenario: Local CI execution with act
+
+- **WHEN** a developer runs `act` with the Nix validation workflow
+- **THEN** the workflow SHALL execute in the local Docker environment
+- **AND** the developer SHALL receive feedback on Nix build status without pushing to GitHub
+
+#### Scenario: Act configuration compatibility
+
+- **WHEN** the workflow is designed
+- **THEN** it SHALL use standard GitHub Actions syntax compatible with `act`
+- **AND** any Nix-specific setup SHALL work in the act Docker environment
+
+### Requirement: Nix Installation in CI
+
+The CI environment SHALL have Nix properly installed and configured before running validation.
+
+#### Scenario: Nix installation step
+
+- **WHEN** the Nix validation job starts
+- **THEN** Nix SHALL be installed using the official Nix installer or determinatesystems/nix-installer-action
+- **AND** the Nix installation SHALL be cached for subsequent runs to improve performance
+
+#### Scenario: Nix configuration for CI
+
+- **WHEN** Nix is installed in CI
+- **THEN** it SHALL be configured to work in the GitHub Actions environment
+- **AND** experimental features (flakes, nix-command) SHALL be enabled
+
+### Requirement: CI Performance Optimization
+
+The Nix validation SHALL be optimized to minimize CI runtime impact.
+
+#### Scenario: Acceptable runtime
+
+- **WHEN** the Nix validation job runs
+- **THEN** it SHALL complete in under 5 minutes on a clean run
+- **AND** with caching, it SHALL complete in under 3 minutes on subsequent runs
+
+#### Scenario: Parallel execution
+
+- **WHEN** multiple CI jobs are running
+- **THEN** the Nix validation job SHALL run in parallel with other validation jobs (tests, lint)
+- **AND** SHALL NOT block other independent checks
+

package/OpenSpec-main/openspec/specs/cli-archive/spec.md

@@ -0,0 +1,210 @@
+# CLI Archive Command Specification
+
+## Purpose
+The archive command moves completed changes from the active changes directory to the archive folder with date-based naming, following OpenSpec conventions.
+
+## Command Syntax
+```bash
+openspec archive [change-name] [--yes|-y]
+```
+
+Options:
+- `--yes`, `-y`: Skip confirmation prompts (for automation)
+## Requirements
+### Requirement: Change Selection
+
+The command SHALL support both interactive and direct change selection methods.
+
+#### Scenario: Interactive selection
+
+- **WHEN** no change-name is provided
+- **THEN** display interactive list of available changes (excluding archive/)
+- **AND** allow user to select one
+
+#### Scenario: Direct selection
+
+- **WHEN** change-name is provided
+- **THEN** use that change directly
+- **AND** validate it exists
+
+### Requirement: Task Completion Check
+
+The command SHALL verify task completion status before archiving to prevent premature archival.
+
+#### Scenario: Incomplete tasks found
+
+- **WHEN** incomplete tasks are found (marked with `- [ ]`)
+- **THEN** display all incomplete tasks to the user
+- **AND** prompt for confirmation to continue
+- **AND** default to "No" for safety
+
+#### Scenario: All tasks complete
+
+- **WHEN** all tasks are complete OR no tasks.md exists
+- **THEN** proceed with archiving without prompting
+
+### Requirement: Archive Process
+
+The archive operation SHALL follow a structured process to safely move changes to the archive.
+
+#### Scenario: Performing archive
+
+- **WHEN** archiving a change
+- **THEN** execute these steps:
+  1. Create archive/ directory if it doesn't exist
+  2. Generate target name as `YYYY-MM-DD-[change-name]` using current date
+  3. Check if target directory already exists
+  4. Update main specs from the change's future state specs (see Spec Update Process below)
+  5. Move the entire change directory to the archive location
+
+#### Scenario: Archive already exists
+
+- **WHEN** target archive already exists
+- **THEN** fail with error message
+- **AND** do not overwrite existing archive
+
+#### Scenario: Successful archive
+
+- **WHEN** move succeeds
+- **THEN** display success message with archived name and list of updated specs
+
+### Requirement: Spec Update Process
+
+Before moving the change to archive, the command SHALL apply delta changes to main specs to reflect the deployed reality.
+
+#### Scenario: Applying delta changes
+
+- **WHEN** archiving a change with delta-based specs
+- **THEN** parse and apply delta changes as defined in openspec-conventions
+- **AND** validate all operations before applying
+
+#### Scenario: Validating delta changes
+
+- **WHEN** processing delta changes
+- **THEN** perform validations as specified in openspec-conventions
+- **AND** if validation fails, show specific errors and abort
+
+#### Scenario: Conflict detection
+
+- **WHEN** applying deltas would create duplicate requirement headers
+- **THEN** abort with error message showing the conflict
+- **AND** suggest manual resolution
+
+### Requirement: Confirmation Behavior
+
+The spec update confirmation SHALL provide clear visibility into changes before they are applied.
+
+#### Scenario: Displaying confirmation
+
+- **WHEN** prompting for confirmation
+- **THEN** display a clear summary showing:
+  - Which specs will be created (new capabilities)
+  - Which specs will be updated (existing capabilities)
+  - The source path for each spec
+- **AND** format the confirmation prompt as:
+  ```
+  The following specs will be updated:
+  
+  NEW specs to be created:
+    - cli-archive (from changes/add-archive-command/specs/cli-archive/spec.md)
+  
+  EXISTING specs to be updated:
+    - cli-init (from changes/update-init-command/specs/cli-init/spec.md)
+  
+  Update 2 specs and archive 'add-archive-command'? [y/N]:
+  ```
+#### Scenario: Handling confirmation response
+
+- **WHEN** waiting for user confirmation
+- **THEN** default to "No" for safety (require explicit "y" or "yes")
+- **AND** skip confirmation when `--yes` or `-y` flag is provided
+
+#### Scenario: User declines confirmation
+
+- **WHEN** user declines the confirmation
+- **THEN** abort the entire archive operation
+- **AND** display message: "Archive cancelled. No changes were made."
+- **AND** exit with non-zero status code
+
+### Requirement: Error Conditions
+
+The command SHALL handle various error conditions gracefully.
+
+#### Scenario: Handling errors
+
+- **WHEN** errors occur
+- **THEN** handle the following conditions:
+  - Missing openspec/changes/ directory
+  - Change not found
+  - Archive target already exists
+  - File system permissions issues
+
+### Requirement: Skip Specs Option
+
+The archive command SHALL support a `--skip-specs` flag that skips all spec update operations and proceeds directly to archiving.
+
+#### Scenario: Skipping spec updates with flag
+
+- **WHEN** executing `openspec archive <change> --skip-specs`
+- **THEN** skip spec discovery and update confirmation
+- **AND** proceed directly to moving the change to archive
+- **AND** display a message indicating specs were skipped
+
+### Requirement: Non-blocking confirmation
+
+The archive operation SHALL proceed when the user declines spec updates instead of cancelling the entire operation.
+
+#### Scenario: User declines spec update confirmation
+
+- **WHEN** the user declines spec update confirmation
+- **THEN** skip spec updates
+- **AND** continue with the archive operation
+- **AND** display a success message indicating specs were not updated
+
+### Requirement: Display Output
+
+The command SHALL provide clear feedback about delta operations.
+
+#### Scenario: Showing delta application
+
+- **WHEN** applying delta changes
+- **THEN** display for each spec:
+  - Number of requirements added
+  - Number of requirements modified
+  - Number of requirements removed
+  - Number of requirements renamed
+- **AND** use standard output symbols (+ ~ - →) as defined in openspec-conventions:
+  ```
+  Applying changes to specs/user-auth/spec.md:
+    + 2 added
+    ~ 3 modified
+    - 1 removed
+    → 1 renamed
+  ```
+
+### Requirement: Archive Validation
+
+The archive command SHALL validate changes before applying them to ensure data integrity.
+
+#### Scenario: Pre-archive validation
+
+- **WHEN** executing `openspec archive change-name`
+- **THEN** validate the change structure first
+- **AND** only proceed if validation passes
+- **AND** show validation errors if it fails
+
+#### Scenario: Force archive without validation
+
+- **WHEN** executing `openspec archive change-name --no-validate`
+- **THEN** skip validation (unsafe mode)
+- **AND** show warning about skipping validation
+
+## Why These Decisions
+
+**Interactive selection**: Reduces typing and helps users see available changes
+**Task checking**: Prevents accidental archiving of incomplete work
+**Date prefixing**: Maintains chronological order and prevents naming conflicts
+**No overwrite**: Preserves historical archives and prevents data loss
+**Spec updates before archiving**: Specs in the main directory represent current reality; when a change is deployed and archived, its future state specs become the new reality and must replace the main specs
+**Confirmation for spec updates**: Provides visibility into what will change, prevents accidental overwrites, and ensures users understand the impact before specs are modified
+**--yes flag for automation**: Allows CI/CD pipelines to archive without interactive prompts while maintaining safety by default for manual use