sauron-cli 1.1.3 → 1.3.0

package/OpenSpec-main/openspec/changes/archive/2025-01-13-add-list-command/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.

package/OpenSpec-main/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

package/OpenSpec-main/openspec/changes/archive/2025-08-05-initialize-typescript-project/design.md

@@ -0,0 +1,64 @@
+# Technical Design
+
+## Technology Choices
+
+### TypeScript Configuration
+- **Strict mode**: Enable all strict type checking for better AI understanding
+- **Target**: ES2022 for modern JavaScript features
+- **Module**: ES2022 for modern ESM support
+- **Module Resolution**: Node for proper package resolution
+- **Output**: dist/ directory for compiled JavaScript
+- **Source Maps**: Enable for debugging TypeScript directly
+- **Declaration Files**: Generate .d.ts files for type definitions
+- **ES Module Interop**: true for better CommonJS compatibility
+- **Skip Lib Check**: false to ensure all types are validated
+
+### Package Structure
+```
+openspec
+├── bin/            # CLI entry point
+├── dist/           # Compiled JavaScript
+├── src/            # TypeScript source
+│   ├── cli/        # Command implementations
+│   ├── core/       # Core OpenSpec logic
+│   └── utils/      # Shared utilities
+├── package.json
+├── tsconfig.json
+└── build.js        # Build script
+```
+
+### Dependency Strategy
+- **Minimal dependencies**: Only essential packages
+- **commander**: Industry-standard CLI framework
+- **@inquirer/prompts**: Modern prompting library
+- **No heavy frameworks**: Direct, readable implementation
+
+### Build Approach
+- Native TypeScript compilation via tsc
+- Simple build.js script for packaging
+- No complex build toolchain needed
+- ESM output with proper .js extensions in imports
+
+### Development Workflow
+1. `pnpm install` - Install dependencies
+2. `pnpm run build` - Compile TypeScript
+3. `pnpm run dev` - Development mode
+4. `pnpm link` - Test CLI locally
+
+### Node.js Requirements
+- **Minimum version**: Node.js 20.19.0
+- **Recommended**: Node.js 22 LTS
+- **Rationale**: Full ESM support without flags, modern JavaScript features
+
+### ESM Configuration
+- **Package type**: `"type": "module"` in package.json
+- **File extensions**: Use .js extensions in TypeScript imports (compiles correctly)
+- **Top-level await**: Available for cleaner async initialization
+- **Future-proof**: Aligns with JavaScript standards
+
+### TypeScript Best Practices
+- **All code in TypeScript**: No .js files in src/, only .ts
+- **Explicit types**: Prefer explicit typing over inference where it adds clarity
+- **Interfaces over types**: Use interfaces for object shapes, types for unions/aliases
+- **No any**: Strict mode prevents implicit any, use unknown when needed
+- **Async/await**: Modern async patterns throughout

package/OpenSpec-main/openspec/changes/archive/2025-08-05-initialize-typescript-project/proposal.md

@@ -0,0 +1,18 @@
+# Initialize TypeScript Project
+
+## Why
+The OpenSpec project needs a proper TypeScript foundation to build the minimal CLI that helps developers set up OpenSpec file structures and keep AI instructions updated.
+
+## What Changes
+- Create TypeScript project configuration with ESM modules (package.json, tsconfig.json)
+- Set up the base directory structure for the CLI implementation
+- Configure build scripts and development tooling
+- Add essential dependencies for CLI development
+- Create .gitignore for Node.js/TypeScript projects
+- Set minimum Node.js version to 20.19.0 for native ESM support
+
+## Impact
+- Affected specs: None (initial project setup)
+- Affected code: None (greenfield project)
+- New directories: src/, dist/, node_modules/
+- New files: package.json, tsconfig.json, .gitignore, build.js

package/OpenSpec-main/openspec/changes/archive/2025-08-05-initialize-typescript-project/tasks.md

@@ -0,0 +1,25 @@
+# Tasks
+
+## 1. Project Configuration
+- [x] 1.1 Create package.json with project metadata, scripts, and ESM configuration
+- [x] 1.2 Configure TypeScript with tsconfig.json for ESM output
+- [x] 1.3 Add .gitignore for Node.js/TypeScript projects
+- [x] 1.4 Set Node.js engine requirement to >=20.19.0
+
+## 2. Directory Structure
+- [x] 2.1 Create src/ directory for source code
+- [x] 2.2 Create src/cli/ for CLI commands
+- [x] 2.3 Create src/core/ for core OpenSpec logic
+- [x] 2.4 Create src/utils/ for shared utilities
+
+## 3. Build Configuration
+- [x] 3.1 Create build.js for native TypeScript compilation
+- [x] 3.2 Configure development scripts (build, dev)
+- [x] 3.3 Set up package entry points with ESM exports
+- [x] 3.4 Configure proper file extensions handling for ESM
+
+## 4. Initial Dependencies
+- [x] 4.1 Add TypeScript as dev dependency
+- [x] 4.2 Add commander for CLI framework
+- [x] 4.3 Add @inquirer/prompts for user interaction
+- [x] 4.4 Add necessary type definitions

package/OpenSpec-main/openspec/changes/archive/2025-08-06-add-init-command/design.md

@@ -0,0 +1,104 @@
+# Technical Design for Init Command
+
+## Architecture Overview
+
+The init command follows a modular architecture with clear separation of concerns:
+
+```
+CLI Layer (src/cli/index.ts)
+    ↓
+Core Logic (src/core/init.ts)
+    ↓
+Templates (src/core/templates/)
+    ↓
+File System Utils (src/utils/file-system.ts)
+```
+
+## Key Design Decisions
+
+### 1. Template Management
+
+**Decision**: Store templates as TypeScript modules rather than separate files
+**Rationale**: 
+- Ensures templates are bundled with the compiled code
+- Allows for dynamic content insertion
+- Type-safe template handling
+- No need for complex file path resolution
+
+### 2. Interactive vs Non-Interactive Mode
+
+**Decision**: Support both interactive (default) and non-interactive modes
+**Rationale**:
+- Interactive mode for developer experience
+- Non-interactive for CI/CD and automation
+- Flags: `--yes` to accept defaults, `--no-input` for full automation
+
+### 3. Directory Structure Creation
+
+**Decision**: Create all directories upfront, then populate files
+**Rationale**:
+- Fail fast if permissions issues
+- Clear transaction boundary
+- Easier to clean up on failure
+
+### 4. Error Handling Strategy
+
+**Decision**: Implement rollback on failure
+**Rationale**:
+- Prevent partial installations
+- Clear error states
+- Better user experience
+
+## Implementation Details
+
+### File System Operations
+
+```typescript
+// Atomic directory creation with rollback
+interface InitTransaction {
+  createdPaths: string[];
+  rollback(): Promise<void>;
+  commit(): Promise<void>;
+}
+```
+
+### Template System
+
+```typescript
+interface Template {
+  path: string;
+  content: string | ((context: ProjectContext) => string);
+}
+
+interface ProjectContext {
+  projectName: string;
+  description: string;
+  techStack: string[];
+  conventions: string;
+}
+```
+
+### CLI Command Structure
+
+```bash
+openspec init [path]           # Initialize in specified path (default: current directory)
+  --yes                       # Accept all defaults
+  --no-input                  # Skip all prompts
+  --force                     # Overwrite existing OpenSpec directory
+  --dry-run                   # Show what would be created
+```
+
+## Security Considerations
+
+1. **Path Traversal**: Sanitize all user-provided paths
+2. **File Permissions**: Check write permissions before starting
+3. **Existing Files**: Never overwrite without explicit --force flag
+4. **Template Injection**: Sanitize user inputs in templates
+
+## Future Extensibility
+
+The design supports future enhancements:
+- Custom template sources
+- Project type presets (API, web app, library)
+- Migration from other documentation systems
+- Integration with version control systems

package/OpenSpec-main/openspec/changes/archive/2025-08-06-add-init-command/proposal.md

@@ -0,0 +1,30 @@
+# Add Init Command for OpenSpec
+
+## Why
+
+Projects need a simple way to adopt OpenSpec conventions. Currently, users must manually create the directory structure and understand all the conventions, which creates friction for adoption. An init command would enable instant OpenSpec setup with proper structure and guidance.
+
+## What Changes
+
+- Add `openspec init` CLI command that creates the complete OpenSpec directory structure
+- Generate template files (README.md with AI instructions, project.md template)
+- Interactive prompt to select which AI tools to configure (Claude Code initially, others marked as "coming soon")
+- Support for multiple AI coding assistants with extensible plugin architecture
+- Smart file updates using content markers to preserve existing configurations
+- Custom directory naming with `--dir` flag
+- Validation to prevent overwriting existing OpenSpec structures
+- Clear error messages with helpful guidance (e.g., suggesting 'openspec update' for existing structures)
+- Display actionable next steps after successful initialization
+
+### Breaking Changes
+- None - this is a new feature
+
+## Impact
+
+- Affected specs: None (new feature)
+- Affected code: 
+  - src/cli/index.ts (add init command)
+  - src/core/init.ts (new - initialization logic)
+  - src/core/templates/ (new - template files)
+  - src/core/configurators/ (new - AI tool plugins)
+  - src/utils/file-system.ts (new - file operations)

package/OpenSpec-main/openspec/changes/archive/2025-08-06-add-init-command/specs/cli-init/spec.md

@@ -0,0 +1,148 @@
+# CLI Init Specification
+
+## Purpose
+
+The `openspec init` command SHALL create a complete OpenSpec directory structure in any project, enabling immediate adoption of OpenSpec conventions with support for multiple AI coding assistants.
+
+## Behavior
+
+### Progress Indicators
+
+WHEN executing initialization steps
+THEN validate environment silently in background (no output unless error)
+AND display progress with ora spinners:
+- Show spinner: "⠋ Creating OpenSpec structure..."
+- Then success: "✔ OpenSpec structure created"
+- Show spinner: "⠋ Configuring AI tools..."
+- Then success: "✔ AI tools configured"
+
+### Directory Creation
+
+WHEN `openspec init` is executed
+THEN create the following directory structure:
+```
+openspec/
+├── project.md
+├── README.md
+├── specs/
+└── changes/
+    └── archive/
+```
+
+### File Generation
+
+The command SHALL generate:
+- `README.md` containing complete OpenSpec instructions for AI assistants
+- `project.md` with project context template
+
+### AI Tool Configuration
+
+WHEN run interactively
+THEN prompt user to select AI tools to configure:
+- Claude Code (updates/creates CLAUDE.md with OpenSpec markers)
+- Cursor (future)
+- Aider (future)
+
+### AI Tool Configuration Details
+
+WHEN Claude Code is selected
+THEN create or update `CLAUDE.md` in the project root directory (not inside openspec/)
+
+WHEN CLAUDE.md does not exist
+THEN create new file with OpenSpec content wrapped in markers:
+```markdown
+<!-- OPENSPEC:START -->
+# OpenSpec Project
+
+This document provides instructions for AI coding assistants on how to use OpenSpec conventions for spec-driven development. Follow these rules precisely when working on OpenSpec-enabled projects.
+
+This project uses OpenSpec for spec-driven development. Specifications are the source of truth.
+
+See @openspec/README.md for detailed conventions and guidelines.
+<!-- OPENSPEC:END -->
+```
+
+WHEN CLAUDE.md already exists
+THEN preserve all existing content
+AND insert OpenSpec content at the beginning of the file using markers
+AND ensure markers don't duplicate if they already exist
+
+The marker system SHALL:
+- Use `<!-- OPENSPEC:START -->` to mark the beginning of managed content
+- Use `<!-- OPENSPEC:END -->` to mark the end of managed content
+- Allow OpenSpec to update its content without affecting user customizations
+- Preserve all content outside the markers intact
+
+WHY use markers:
+- Users may have existing CLAUDE.md instructions they want to keep
+- OpenSpec can update its instructions in future versions
+- Clear boundary between OpenSpec-managed and user-managed content
+
+### Interactive Mode
+
+WHEN run
+THEN prompt user with: "Which AI tool do you use?"
+AND show single-select menu with available tools:
+- Claude Code
+AND show disabled options as "coming soon" (not selectable):
+- Cursor (coming soon)
+- Aider (coming soon)  
+- Continue (coming soon)
+
+User navigation:
+- Use arrow keys to move between options
+- Press Enter to select the highlighted option
+
+### Safety Checks
+
+WHEN `openspec/` directory already exists
+THEN display error with ora fail indicator:
+"✖ Error: OpenSpec seems to already be initialized. Use 'openspec update' to update the structure."
+
+WHEN checking initialization feasibility
+THEN verify write permissions in the target directory silently
+AND only display error if permissions are insufficient
+
+### Success Output
+
+WHEN initialization completes successfully
+THEN display actionable prompts for AI-driven workflow:
+```
+✔ OpenSpec initialized successfully!
+
+Next steps - Copy these prompts to Claude:
+
+────────────────────────────────────────────────────────────
+1. Populate your project context:
+   "Please read openspec/project.md and help me fill it out
+    with details about my project, tech stack, and conventions"
+
+2. Create your first change proposal:
+   "I want to add [YOUR FEATURE HERE]. Please create an
+    OpenSpec change proposal for this feature"
+
+3. Learn the OpenSpec workflow:
+   "Please explain the OpenSpec workflow from openspec/README.md
+    and how I should work with you on this project"
+────────────────────────────────────────────────────────────
+```
+
+The prompts SHALL:
+- Be copy-pasteable for immediate use with AI tools
+- Guide users through the AI-driven workflow
+- Replace placeholder text ([YOUR FEATURE HERE]) with actual features
+
+### Exit Codes
+
+- 0: Success
+- 1: General error (including when OpenSpec directory already exists)
+- 2: Insufficient permissions (reserved for future use)
+- 3: User cancelled operation (reserved for future use)
+
+## Why
+
+Manual creation of OpenSpec structure is error-prone and creates adoption friction. A standardized init command ensures:
+- Consistent structure across all projects
+- Proper AI instruction files are always included
+- Quick onboarding for new projects
+- Clear conventions from the start

package/OpenSpec-main/openspec/changes/archive/2025-08-06-add-init-command/tasks.md

@@ -0,0 +1,38 @@
+# Implementation Tasks for Init Command
+
+## 1. Core Infrastructure
+- [x] 1.1 Create src/utils/file-system.ts with directory/file creation utilities
+- [x] 1.2 Create src/core/templates/index.ts for template management
+- [x] 1.3 Create src/core/init.ts with main initialization logic
+- [x] 1.4 Create src/core/config.ts for configuration management
+
+## 2. Template Files
+- [x] 2.1 Create src/core/templates/readme-template.ts with OpenSpec README content
+- [x] 2.2 Create src/core/templates/project-template.ts with customizable project.md
+- [x] 2.3 Create src/core/templates/claude-template.ts for CLAUDE.md content with markers
+
+## 3. AI Tool Configurators
+- [x] 3.1 Create src/core/configurators/base.ts with ToolConfigurator interface
+- [x] 3.2 Create src/core/configurators/claude.ts for Claude Code configuration
+- [x] 3.3 Create src/core/configurators/registry.ts for tool registration
+- [x] 3.4 Implement marker-based file updates for existing configurations
+
+## 4. Init Command Implementation
+- [x] 4.1 Add init command to src/cli/index.ts using Commander
+- [x] 4.2 Implement AI tool selection with multi-select prompt (Claude Code available, others "coming soon") - requires at least one selection
+- [x] 4.3 Add validation for existing OpenSpec directories with helpful error message
+- [x] 4.4 Implement directory structure creation
+- [x] 4.5 Implement file generation with templates and markers
+
+## 5. User Experience
+- [x] 5.1 Add colorful console output for better UX
+- [x] 5.2 Implement progress indicators (Step 1/3, 2/3, 3/3)
+- [x] 5.3 Add success message with actionable next steps (edit project.md, create first change)
+- [x] 5.4 Add error handling with helpful messages
+
+## 6. Testing and Documentation
+- [x] 6.1 Add unit tests for file system utilities
+- [x] 6.2 Add unit tests for marker-based file updates
+- [x] 6.3 Add integration tests for init command
+- [x] 6.4 Update package.json with proper bin configuration
+- [x] 6.5 Test the built CLI command end-to-end

package/OpenSpec-main/openspec/changes/archive/2025-08-06-adopt-future-state-storage/proposal.md

@@ -0,0 +1,24 @@
+# Adopt Future State Storage for OpenSpec Changes
+
+## Why
+
+The current approach of storing spec changes as diff files (`.spec.md.diff`) creates friction for both humans and AI. Diff syntax with `+` and `-` prefixes makes specs hard to read, AI tools struggle with the format when understanding future state, and GitHub can't show nice comparisons between current and proposed specs in different folders.
+
+## What Changes
+
+- Change from storing diffs (`patches/[capability]/spec.md.diff`) to storing complete future state (`specs/[capability]/spec.md`)
+- Update all documentation to reflect new storage format
+- Migrate existing `add-init-command` change to new format
+- Add new `openspec-conventions` capability to document these conventions
+
+
+
+## Impact
+
+- Affected specs: New `openspec-conventions` capability
+- Affected code: 
+  - openspec/README.md (lines 85-108)
+  - docs/PRD.md (lines 376-382, 778-783)
+  - docs/openspec-walkthrough.md (lines 58-62, 112-126)
+  - openspec/changes/add-init-command/ (migration needed)
+

package/OpenSpec-main/openspec/changes/archive/2025-08-06-adopt-future-state-storage/specs/openspec-conventions/spec.md

@@ -0,0 +1,120 @@
+# OpenSpec Conventions Specification
+
+## Purpose
+
+OpenSpec conventions SHALL define how system capabilities are documented, how changes are proposed and tracked, and how specifications evolve over time. This meta-specification serves as the source of truth for OpenSpec's own conventions.
+
+## Core Principles
+
+The system SHALL follow these principles:
+- Specs reflect what IS currently built and deployed
+- Changes contain proposals for what SHOULD be changed
+- AI drives the documentation process
+- Specs are living documentation kept in sync with deployed code
+
+## Directory Structure
+
+WHEN an OpenSpec project is initialized
+THEN it SHALL have this structure:
+```
+openspec/
+├── project.md              # Project-specific context
+├── README.md               # AI assistant instructions
+├── specs/                  # Current deployed capabilities
+│   └── [capability]/       # Single, focused capability
+│       ├── spec.md         # WHAT and WHY
+│       └── design.md       # HOW (optional, for established patterns)
+└── changes/                # Proposed changes
+    ├── [change-name]/      # Descriptive change identifier
+    │   ├── proposal.md     # Why, what, and impact
+    │   ├── tasks.md        # Implementation checklist
+    │   ├── design.md       # Technical decisions (optional)
+    │   └── specs/          # Complete future state
+    │       └── [capability]/
+    │           └── spec.md # Clean markdown (no diff syntax)
+    └── archive/            # Completed changes
+        └── YYYY-MM-DD-[name]/
+```
+
+## Change Storage Convention
+
+### Future State Storage
+
+WHEN creating a change proposal
+THEN store the complete future state of affected specs
+AND use clean markdown without diff syntax
+
+The `changes/[name]/specs/` directory SHALL contain:
+- Complete spec files as they will exist after the change
+- Clean markdown without `+` or `-` prefixes
+- All formatting and structure of the final intended state
+
+### Proposal Format
+
+WHEN documenting what changes
+THEN the proposal SHALL explicitly describe each change:
+
+```markdown
+**[Section or Behavior Name]**
+- From: [current state/requirement]
+- To: [future state/requirement]
+- Reason: [why this change is needed]
+- Impact: [breaking/non-breaking, who's affected]
+```
+
+This explicit format compensates for not having inline diffs and ensures reviewers understand exactly what will change.
+
+## Change Lifecycle
+
+The change process SHALL follow these states:
+
+1. **Propose**: AI creates change with future state specs and explicit proposal
+2. **Review**: Humans review proposal and future state
+3. **Approve**: Change is approved for implementation
+4. **Implement**: Follow tasks.md checklist (can span multiple PRs)
+5. **Deploy**: Changes are deployed to production
+6. **Update**: Specs in `specs/` are updated to match deployed reality
+7. **Archive**: Change is moved to `archive/YYYY-MM-DD-[name]/`
+
+## Viewing Changes
+
+WHEN reviewing proposed changes
+THEN reviewers can compare using:
+- GitHub PR diff view when changes are committed
+- Command line: `diff -u specs/[capability]/spec.md changes/[name]/specs/[capability]/spec.md`
+- Any visual diff tool comparing current vs future state
+
+The system relies on tools to generate diffs rather than storing them.
+
+## Capability Naming
+
+Capabilities SHALL use:
+- Verb-noun patterns (e.g., `user-auth`, `payment-capture`)
+- Hyphenated lowercase names
+- Singular focus (one responsibility per capability)
+- No nesting (flat structure under `specs/`)
+
+## When Changes Require Proposals
+
+A proposal SHALL be created for:
+- New features or capabilities
+- Breaking changes to existing behavior
+- Architecture or pattern changes
+- Performance optimizations that change behavior
+- Security updates affecting access patterns
+
+A proposal is NOT required for:
+- Bug fixes restoring intended behavior
+- Typos or formatting fixes
+- Non-breaking dependency updates
+- Adding tests for existing behavior
+- Documentation clarifications
+
+## Why This Approach
+
+Clean future state storage provides:
+- **Readability**: No diff syntax pollution
+- **AI-compatibility**: Standard markdown that AI tools understand
+- **Simplicity**: No special parsing or processing needed
+- **Tool-agnostic**: Any diff tool can show changes
+- **Clear intent**: Explicit proposals document reasoning