sauron-cli 1.3.0 → 1.4.0

package/OpenSpec-main/openspec/changes/archive/2025-01-11-add-update-command/design.md

@@ -1,86 +0,0 @@
-# Technical Design
-
-## Architecture Decisions
-
-### Simplicity First
-- No version tracking - always update when commanded
-- Full replacement for OpenSpec-managed files only (e.g., `openspec/README.md`)
-- Marker-based updates for user-owned files (e.g., `CLAUDE.md`)
-- Templates bundled with package - no network required
-- Minimal error handling - only check prerequisites
-
-### Template Strategy
-- Use existing template utilities
-  - `readmeTemplate` from `src/core/templates/readme-template.ts` for `openspec/README.md`
-  - `TemplateManager.getClaudeTemplate()` for `CLAUDE.md`
-- Directory name is fixed to `openspec` (from `OPENSPEC_DIR_NAME`)
-
-### File Operations
-- Use async utilities for consistency
-  - `FileSystemUtils.writeFile` for `openspec/README.md`
-  - `FileSystemUtils.updateFileWithMarkers` for `CLAUDE.md`
-- No atomic operations needed - users have git
-- Check directory existence before proceeding
-
-## Implementation
-
-### Update Command (`src/core/update.ts`)
-```typescript
-export class UpdateCommand {
-  async execute(projectPath: string): Promise<void> {
-    const openspecDirName = OPENSPEC_DIR_NAME;
-    const openspecPath = path.join(projectPath, openspecDirName);
-
-    // 1. Check openspec directory exists
-    if (!await FileSystemUtils.directoryExists(openspecPath)) {
-      throw new Error(`No OpenSpec directory found. Run 'openspec init' first.`);
-    }
-
-    // 2. Update README.md (full replacement)
-    const readmePath = path.join(openspecPath, 'README.md');
-    await FileSystemUtils.writeFile(readmePath, readmeTemplate);
-
-    // 3. Update CLAUDE.md (marker-based)
-    const claudePath = path.join(projectPath, 'CLAUDE.md');
-    const claudeContent = TemplateManager.getClaudeTemplate();
-    await FileSystemUtils.updateFileWithMarkers(
-      claudePath,
-      claudeContent,
-      OPENSPEC_MARKERS.start,
-      OPENSPEC_MARKERS.end
-    );
-
-    // 4. Success message (ASCII-safe, checkmark optional by terminal)
-    console.log('Updated OpenSpec instructions');
-  }
-}
-```
-
-## Why This Approach
-
-### Benefits
-- **Dead simple**: ~40 lines of code total
-- **Fast**: No version checks, minimal parsing
-- **Predictable**: Same result every time; idempotent
-- **Maintainable**: Reuses existing utilities
-
-### Trade-offs Accepted
-- No version tracking (unnecessary complexity)
-- Full overwrite only for OpenSpec-managed files
-- Marker-managed updates for user-owned files
-
-## Error Handling
-
-Only handle critical errors:
-- Missing `openspec` directory → throw error handled by CLI to present a friendly message
-- File write failures → let errors bubble up to CLI
-
-## Testing Strategy
-
-Manual smoke tests are sufficient initially:
-1. Run `openspec init` in a test project
-2. Modify both files (including custom content around markers in `CLAUDE.md`)
-3. Run `openspec update`
-4. Verify `openspec/README.md` fully replaced; `CLAUDE.md` OpenSpec block updated without altering user content outside markers
-5. Run the command twice to verify idempotency and no duplicate markers
-6. Test with missing `openspec` directory (expect failure)

package/OpenSpec-main/openspec/changes/archive/2025-01-11-add-update-command/proposal.md

@@ -1,29 +0,0 @@
-# Add Update Command
-
-## Why
-
-Users need a way to update their local OpenSpec instructions (README.md and CLAUDE.md) when the OpenSpec package releases new versions with improved AI agent instructions or structural conventions.
-
-## What Changes
-
-- Add new `openspec update` CLI command that updates OpenSpec instructions
-- Replace `openspec/README.md` with the latest template
-  - Safe because this file is fully OpenSpec-managed
-- Update only the OpenSpec-managed block in `CLAUDE.md` using markers
-  - Preserve all user content outside markers
-  - If `CLAUDE.md` is missing, create it with the managed block
-- Display success message after update (ASCII-safe): "Updated OpenSpec instructions"
-  - A leading checkmark MAY be shown when the terminal supports it
-  - Operation is idempotent (re-running yields identical results)
-
-## Impact
-
-- Affected specs: `cli-update` (new capability)
-- Affected code:
-  - `src/core/update.ts` (new command class, mirrors `InitCommand` placement)
-  - `src/cli/index.ts` (register new command)
-  - Uses existing templates via `TemplateManager` and `readmeTemplate`
-
-## Out of Scope
-
-- No `.openspec/config.json` is introduced by this change. The default directory name `openspec` is used.

package/OpenSpec-main/openspec/changes/archive/2025-01-11-add-update-command/specs/cli-update/spec.md

@@ -1,59 +0,0 @@
-# Update Command Specification
-
-## Purpose
-
-As a developer using OpenSpec, I want to update the OpenSpec instructions in my project when new versions are released, so that I can benefit from improvements to AI agent instructions.
-
-## Core Requirements
-
-### Update Behavior
-
-The update command SHALL update OpenSpec instruction files to the latest templates.
-
-WHEN a user runs `openspec update` THEN the command SHALL:
-- Check if the `openspec` directory exists
-- Replace `openspec/README.md` with the latest template (complete replacement)
-- Update the OpenSpec-managed block in `CLAUDE.md` using markers
-  - Preserve user content outside markers
-  - Create `CLAUDE.md` if missing
-- Display ASCII-safe success message: "Updated OpenSpec instructions"
-
-### Prerequisites
-
-The command SHALL require:
-- An existing `openspec` directory (created by `openspec init`)
-
-IF the `openspec` directory does not exist THEN:
-- Display error: "No OpenSpec directory found. Run 'openspec init' first."
-- Exit with code 1
-
-### File Handling
-
-The update command SHALL:
-- Completely replace `openspec/README.md` with the latest template
-- Update only the OpenSpec-managed block in `CLAUDE.md` using markers
-- Use the default directory name `openspec`
-- Be idempotent (repeated runs have no additional effect)
-
-## Edge Cases
-
-### File Permissions
-IF file write fails THEN let the error bubble up naturally with file path.
-
-### Missing CLAUDE.md
-IF CLAUDE.md doesn't exist THEN create it with the template content.
-
-### Custom Directory Name
-Not supported in this change. The default directory name `openspec` SHALL be used.
-
-## Success Criteria
-
-Users SHALL be able to:
-- Update OpenSpec instructions with a single command
-- Get the latest AI agent instructions
-- See clear confirmation of the update
-
-The update process SHALL be:
-- Simple and fast (no version checking)
-- Predictable (same result every time)
-- Self-contained (no network required)

package/OpenSpec-main/openspec/changes/archive/2025-01-11-add-update-command/tasks.md

@@ -1,20 +0,0 @@
-# Implementation Tasks
-
-## 1. Update Command Implementation
-- [x] 1.1 Create `src/core/update.ts` with `UpdateCommand` class
-- [x] 1.2 Check if `openspec` directory exists (use `FileSystemUtils.directoryExists`)
-- [x] 1.3 Write `readmeTemplate` to `openspec/README.md` using `FileSystemUtils.writeFile`
-- [x] 1.4 Update `CLAUDE.md` using markers via `FileSystemUtils.updateFileWithMarkers` and `TemplateManager.getClaudeTemplate()`
-- [x] 1.5 Display ASCII-safe success message: `Updated OpenSpec instructions`
-
-## 2. CLI Integration
-- [x] 2.1 Register `update` command in `src/cli/index.ts`
-- [x] 2.2 Add command description: `Update OpenSpec instruction files`
-- [x] 2.3 Handle errors with `ora().fail(...)` and exit code 1 (missing `openspec` directory, file write errors)
-
-## 3. Testing
-- [x] 3.1 Verify `openspec/README.md` is fully replaced with latest template
-- [x] 3.2 Verify `CLAUDE.md` OpenSpec block updates without altering user content outside markers
-- [x] 3.3 Verify idempotency (running twice yields identical files, no duplicate markers)
-- [x] 3.4 Verify error when `openspec` directory is missing with friendly message
-- [x] 3.5 Verify success message displays properly in ASCII-only terminals

package/OpenSpec-main/openspec/changes/archive/2025-01-13-add-list-command/proposal.md

@@ -1,20 +0,0 @@
-# Add List Command to OpenSpec CLI
-
-## Why
-
-Developers need visibility into available changes and their status to understand the project's evolution and pending work.
-
-## What Changes
-
-- Add `openspec list` command that displays all changes in the changes/ directory
-- Show each change name with task completion count (e.g., "add-auth: 3/5 tasks")
-- Display completion status indicator (✓ for fully complete, progress for partial)
-- Skip the archive/ subdirectory to focus on active changes
-- Simple table output for easy scanning
-
-## Impact
-
-- Affected specs: New capability `cli-list` will be added
-- Affected code:
-  - `src/cli/index.ts` - Add list command
-  - `src/core/list.ts` - New file with directory scanning and task parsing (~60 lines)

package/OpenSpec-main/openspec/changes/archive/2025-01-13-add-list-command/specs/cli-list/spec.md

@@ -1,69 +0,0 @@
-# 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

@@ -1,26 +0,0 @@
-# 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

@@ -1,64 +0,0 @@
-# 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

@@ -1,18 +0,0 @@
-# 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

@@ -1,25 +0,0 @@
-# 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

@@ -1,104 +0,0 @@
-# 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

@@ -1,30 +0,0 @@
-# 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)