flock-core 0.3.20__tar.gz → 0.3.22__tar.gz

flock_core-0.3.22/.cursorignore

@@ -0,0 +1,4 @@
+# Add directories or file patterns to ignore during indexing (e.g. foo/ or *.csv)
+src/flock/themes/
+
+

{flock_core-0.3.20 → flock_core-0.3.22}/.gitignore

@@ -6,6 +6,11 @@ __pycache__/
 # C extensions
 *.so
 
+# ignore all .env* files except .env_template
+*.env*
+!*.env_template
+
+
 # Distribution / packaging
 .Python
 build/
@@ -33,6 +38,9 @@ news/
 .chroma/
 hierarchical_memory/
 .repomix-output.txt
+output/
+!src/flock/modules/output/output_module.py
+.env.*
 
 # PyInstaller
 #  Usually these files are written by a python script from a template

{flock_core-0.3.20 → flock_core-0.3.22}/.project/SPECS.md

@@ -53,6 +53,12 @@ Flock is a declarative agent framework that focuses on simplifying the creation
    - Defines context propagation requirements
    - Specifies context access patterns
 
+9. [**CLI System**](specs/09_cli_system.md)
+   - Defines the command-line interface architecture
+   - Specifies modules like the Settings Editor and Theme Builder
+   - Documents environment profile management
+   - Outlines UI components and navigation patterns
+
 ## Design Principles
 
 These specifications reveal several core design principles that guided the development of Flock:
@@ -62,6 +68,7 @@ These specifications reveal several core design principles that guided the devel
 3. **Declarative Over Imperative** - Focus on what agents do, not how they do it
 4. **Production Readiness** - Support for distributed execution, observability, and error handling
 5. **Developer Experience** - Simplified API with sensible defaults and clear patterns
+6. **User-Friendly Interface** - Intuitive CLI with clear navigation and helpful feedback
 
 ## Implementation Status
 
@@ -75,4 +82,5 @@ Based on the specifications, potential future enhancements could include:
 2. Enhanced observability and debugging tools
 3. Additional module types for common agent patterns
 4. Expanded router capabilities for complex workflows
-5. Integration with additional execution engines beyond Temporal 
+5. Integration with additional execution engines beyond Temporal
+6. Extended CLI functionality for agent management and monitoring 

flock_core-0.3.22/.project/TASKS.md

@@ -0,0 +1,47 @@
+# Project Tasks
+
+## Environment Settings Editor
+
+The settings editor is a key feature of the Flock CLI that allows users to view, edit, add, and delete environment variables in the `.env` file.
+
+### Implementation Tasks
+
+| ID | Task | Priority | Status | Description |
+|----|------|----------|--------|-------------|
+| 001 | [Settings Editor Implementation](tasks/done/001-env-settings-editor.md) | High | Completed | Implement the core settings editor functionality |
+| 002 | [Settings Editor UI Components](tasks/done/002-env-settings-ui-components.md) | High | Completed | Design and implement UI components for the settings editor |
+| 003 | [Environment File Operations](tasks/done/003-env-settings-file-operations.md) | High | Completed | Implement robust file operations for the .env file |
+| 004 | [Settings Security Features](tasks/done/004-settings-security-features.md) | High | Completed | Implement security features for protecting sensitive information |
+| 005 | [Environment Profile Switching](tasks/done/005-env-profile-switching.md) | High | Completed | Implement feature to switch between multiple environment profiles (.env configurations) |
+
+## Implementation Approach
+
+The settings editor was implemented in stages:
+
+1. **Core Functionality**: Parse and manipulate .env files, implement the main settings editor menu
+2. **UI Components**: Create a user-friendly interface with proper formatting and navigation
+3. **File Operations**: Ensure robust reading and writing of .env files with proper error handling
+4. **Security Features**: Add protection for sensitive information like API keys and tokens
+5. **Profile Management**: Implement ability to create and switch between different environment profiles
+
+## Definition of Done
+
+The implementation is considered complete as:
+
+- Users can access the settings editor from the main CLI menu
+- All core functionality (view, edit, add, delete) works correctly
+- Users can switch between different environment profiles (dev, test, prod)
+- The UI is intuitive and provides clear feedback
+- File operations are robust and prevent data loss
+- Sensitive information is properly protected
+- Code is well-documented and follows project conventions
+
+## Next Steps
+
+After completing the settings editor, potential future enhancements could include:
+
+- Settings groups/categories for better organization
+- Import/export functionality for settings
+- Presets for common configurations
+- Integration with cloud-based secrets management
+- Command history and autocomplete features 

flock_core-0.3.22/.project/USERSTORIES.md

@@ -0,0 +1,21 @@
+# User Stories
+
+This document provides an index of all user stories for the Flock project.
+
+## Current User Stories
+
+No active user stories.
+
+## Completed User Stories
+
+| ID | Title | Priority | Status | Description |
+|----|-------|----------|--------|-------------|
+| [US001](userstories/done/US001-Settings-Editor.md) | Environment Settings Editor with Profile Management | High | Completed | Implement a settings editor with profile switching capability |
+
+## User Story Status Explanation
+
+- **Not Started**: The user story has been defined but no work has been done
+- **In Progress**: Work has started on the user story
+- **Completed**: All tasks associated with the user story have been completed
+- **On Hold**: The user story is temporarily paused
+- **Blocked**: The user story cannot proceed due to external dependencies 

flock_core-0.3.22/.project/planning_prompt.md

@@ -0,0 +1,184 @@
+# Planning Prompt Template
+
+Use this prompt template when you want to create a new user story and related tasks for a feature in the Flock project.
+
+## Prompt Template
+
+```
+I need to implement a new feature in my Flock CLI application. The feature is [BRIEF DESCRIPTION OF FEATURE].
+
+Please help me plan this implementation by:
+
+1. Creating a detailed user story that describes:
+   - The current state of the system related to this feature
+   - The desired state after implementation
+   - Technical details about the project structure and relevant files
+   - Clear acceptance criteria
+   - UI mockups (if applicable)
+   - Any edge cases or special considerations
+
+2. Breaking down the implementation into specific tasks, where each task:
+   - Has a clear focus and scope
+   - Includes technical requirements
+   - Has a step-by-step implementation plan
+   - Defines "done" criteria
+   - Lists dependencies and related tasks
+   - Estimates effort required
+
+3. Creating a task index that organizes all tasks with their priorities and statuses
+
+Follow the structure and format used in the Settings Editor feature:
+- Create files in `.project/userstories/` for the user story
+- Create files in `.project/tasks/` for each task
+- Update `.project/USERSTORIES.md` to include the new user story
+- Update `.project/TASKS.md` to include the new tasks
+
+Additional context about my project:
+[PROVIDE ANY RELEVANT CONTEXT ABOUT YOUR PROJECT, SUCH AS CURRENT STRUCTURE, LIBRARIES USED, OR SPECIFIC REQUIREMENTS]
+
+Before continuing with implementing the code, please let me review the user story and tasks first.
+```
+
+## Example Use
+
+Here's an example of how to use this template for a specific feature:
+
+```
+I need to implement a new feature in my Flock CLI application. The feature is a command-line plugin system that allows users to create, install, and manage custom plugins to extend the functionality of the CLI.
+
+Please help me plan this implementation by:
+
+1. Creating a detailed user story that describes:
+   - The current state of the system related to this feature
+   - The desired state after implementation
+   - Technical details about the project structure and relevant files
+   - Clear acceptance criteria
+   - UI mockups (if applicable)
+   - Any edge cases or special considerations
+
+2. Breaking down the implementation into specific tasks, where each task:
+   - Has a clear focus and scope
+   - Includes technical requirements
+   - Has a step-by-step implementation plan
+   - Defines "done" criteria
+   - Lists dependencies and related tasks
+   - Estimates effort required
+
+3. Creating a task index that organizes all tasks with their priorities and statuses
+
+Follow the structure and format used in the Settings Editor feature:
+- Create files in `.project/userstories/` for the user story
+- Create files in `.project/tasks/` for each task
+- Update `.project/USERSTORIES.md` to include the new user story
+- Update `.project/TASKS.md` to include the new tasks
+
+Additional context about my project:
+- The CLI is built in Python using Rich for UI and Questionary for input
+- We use a plugin architecture similar to the one in Poetry/Pip
+- Plugins should be installable from Git repositories or local directories
+- The CLI currently has a modular structure in src/flock/cli/
+
+Before continuing with implementing the code, please let me review the user story and tasks first.
+```
+
+## Tips for Getting the Best Results
+
+1. **Be specific** about the feature you want to implement
+2. **Provide context** about your project's structure and current state
+3. **Mention any libraries or technologies** that should be used
+4. **Include any specific requirements** or constraints
+5. **Share examples** of similar features if available
+6. **Identify potential edge cases** or challenges
+7. **Specify the target audience** of the feature
+8. **Indicate priority level** if relevant
+
+## Template for User Story Structure
+
+Your user story should typically follow this structure:
+
+```markdown
+# User Story: [Feature Name]
+
+## ID
+[ID Number]
+
+## Title
+[Concise Title]
+
+## Description
+As a [type of user], I want to [goal/action] so that [benefit/reason].
+
+## Current State
+[Description of how things currently work or the absence of functionality]
+
+## Desired State
+[Description of how things should work after implementation]
+
+## Technical Details
+[Technical information about implementation, including project structure and technologies]
+
+## Related Tasks
+[Links to related task files]
+
+## Acceptance Criteria
+[List of specific criteria that must be met for the feature to be considered complete]
+
+## UI Mockups
+[Text-based mockups if the feature has a UI component]
+
+## Notes
+[Any additional information, cautions, or special considerations]
+
+## Stakeholders
+[Who will be affected by or interested in this feature]
+
+## Priority
+[Priority level]
+
+## Story Points / Effort
+[Estimated effort required]
+```
+
+## Template for Task Structure
+
+Your tasks should typically follow this structure:
+
+```markdown
+# [Task Name]
+
+## Summary
+[Brief description of the task]
+
+## Description
+[More detailed explanation of what this task entails]
+
+## User Story
+[Link to the related user story]
+
+## Technical Requirements
+[Specific technical requirements for this task]
+
+## Implementation Plan
+[Step-by-step plan for implementing this task]
+
+## Definition of Done
+[Specific criteria that must be met for this task to be considered complete]
+
+## Dependencies
+[Libraries, tools, or other tasks that this task depends on]
+
+## Related Tasks
+[Links to related task files]
+
+## Estimated Effort
+[Estimated time or complexity]
+
+## Priority
+[Priority level]
+
+## Assignee
+[Who is assigned to this task]
+
+## Status
+[Current status of the task]
+``` 

flock_core-0.3.22/.project/specs/09_cli_system.md

@@ -0,0 +1,119 @@
+# CLI System Specification
+
+## Overview
+
+The Command Line Interface (CLI) system provides an interactive terminal-based user interface for the Flock framework. It allows users to manage agents, flocks, settings, and other aspects of the framework through a console application.
+
+## Components
+
+### 1. Main CLI Application
+
+- **Entry Point**: `src/flock/__init__.py`
+- **Purpose**: Provides the main menu and dispatches to specific CLI modules
+- **Implementation**: Uses Rich for formatting and Questionary for interactive prompts
+- **Main Menu Options**:
+  - Load a flock file
+  - Theme builder
+  - Settings editor
+  - Advanced mode (future)
+  - Web server (future)
+  - Release notes
+  - Exit
+
+### 2. Settings Editor
+
+- **Module**: `src/flock/cli/settings.py`
+- **Purpose**: View, edit, add, and delete environment variables in the `.env` file
+- **Features**:
+  - Pagination of environment variables
+  - Masking of sensitive values (API keys, tokens, etc.)
+  - Environment profile management (dev, test, prod, etc.)
+  - Configurable variables per page
+
+#### 2.1 Environment Variables Management
+
+- View all environment variables with pagination
+- Edit existing variables with proper validation
+- Add new variables
+- Delete existing variables
+- Masking sensitive values (API keys, passwords, tokens)
+- Toggle visibility of sensitive values
+
+#### 2.2 Environment Profile System
+
+- Multiple environment profiles (.env_dev, .env_prod, etc.)
+- Active profile stored as .env
+- Profile name stored as comment in first line: `# Profile: name`
+- Profile operations:
+  - Switch between profiles
+  - Create new profiles
+  - Rename existing profiles
+  - Delete profiles
+  - Safe backup system before profile operations
+
+#### 2.3 Settings Configuration
+
+- Configurable settings stored in the .env file:
+  - `SHOW_SECRETS`: Controls visibility of sensitive values
+  - `VARS_PER_PAGE`: Controls pagination size (5-100 variables)
+
+### 3. Theme Builder
+
+- **Module**: `flock/core/logging/formatters/theme_builder`
+- **Purpose**: Customize the visual appearance of the CLI
+- **Features**: [To be expanded]
+
+### 4. Flock Loader
+
+- **Module**: `src/flock/cli/load_flock.py`
+- **Purpose**: Load and execute .flock files
+- **Features**: [To be expanded]
+
+## Design Principles
+
+1. **User-Friendly Interface**: Clear navigation, intuitive controls, and helpful feedback
+2. **Data Safety**: Backup operations before destructive actions, confirmation prompts
+3. **Efficient Workflow**: Keyboard shortcuts, pagination, customizable settings
+4. **Security Conscious**: Masking of sensitive values, confirmation for showing secrets
+5. **Consistent UI**: Using Rich for formatted output, Questionary for inputs
+
+## UI Components
+
+### Panels and Tables
+
+- **Rich Panels**: Used for section headers and menus
+- **Rich Tables**: Used for displaying structured data
+- **Color Coding**: Green for success, yellow for warnings, red for errors
+
+### Interactive Elements
+
+- **Selection Menus**: Using Questionary.select for menu navigation
+- **Text Inputs**: Using Questionary.text for data entry
+- **Confirmations**: Using Questionary.confirm for destructive actions
+
+## Navigation System
+
+- **Main Menu**: Select from multiple modules
+- **Module Menus**: Select operations within a module
+- **Keyboard Shortcuts**: Single-key commands for common operations
+- **Back Button**: Return to previous screen
+- **Cancel Option**: Abort current operation
+
+## File Operations
+
+- **Load Operations**: Reading from the .env file and profile files
+- **Save Operations**: Writing to the .env file with proper backup
+- **Backup System**: Creating .env.bak before destructive operations
+- **Profile Files**: Managing .env_[profile_name] files
+
+## Future Enhancements
+
+1. **Command History**: Remember previous commands and inputs
+2. **Autocomplete**: Tab completion for variable names and commands
+3. **Search/Filter**: Find specific variables by name or value
+4. **Import/Export**: Support for importing/exporting profiles
+5. **Template System**: Pre-defined templates for common setups
+
+## Implementation Status
+
+The CLI system is currently being implemented with the Settings Editor being the first major component completed. Additional components will be developed according to the project roadmap. 

flock_core-0.3.22/.project/tasks/done/001-env-settings-editor.md

@@ -0,0 +1,82 @@
+# Settings Editor Implementation
+
+## Summary
+Implement a settings editor for the Flock CLI that allows users to view, edit, add, and delete variables in the `.env` file.
+
+## Description
+The Flock CLI has a "Settings" menu item that needs to load a settings editor when selected. This editor will allow users to:
+1. View all current environment variables in the `.env` file
+2. Edit existing environment variable values
+3. Add new environment variables
+4. Delete existing environment variables
+5. Create and switch between different environment profiles (dev, test, prod)
+
+The implementation should provide a smooth and elegant user experience, leveraging the existing libraries used in the project (Rich and Questionary).
+
+## User Story
+[US001 - Environment Settings Editor](../userstories/done/US001-Settings-Editor.md)
+
+## Technical Requirements
+- Create a new module in `src/flock/cli/settings.py` that implements the settings editor
+- Use Rich for display and formatting of environment variables
+- Use Questionary for interactive input and selection
+- Handle edge cases such as:
+  - Missing `.env` file
+  - Invalid format in `.env` file
+  - Special characters in variable names or values
+  - Multi-line values
+- Preserve comments and formatting in the `.env` file when possible
+- Provide clear feedback after operations
+- Implement confirmation for destructive operations (like deletion)
+- Support managing multiple environment profiles
+
+## Implementation Plan
+1. Create a function to parse and load the `.env` file
+2. Create a function to save the `.env` file
+3. Implement a main menu for the settings editor
+4. Implement view functionality with pagination
+5. Implement edit functionality
+6. Implement add functionality
+7. Implement delete functionality
+8. Implement profile switching and management
+9. Connect the settings editor to the CLI main menu
+
+## Definition of Done
+- The settings editor can be accessed from the main CLI menu
+- Users can view, edit, add, and delete environment variables
+- Users can create, switch between, and manage different environment profiles
+- The UI is responsive and provides clear feedback
+- Edge cases are handled gracefully
+- Code is well-documented and follows project conventions
+- Changes to the `.env` file are properly preserved
+
+## Dependencies
+- Rich library
+- Questionary library
+- Python's os and dotenv modules
+
+## Related Tasks
+- [002-env-settings-ui-components.md](002-env-settings-ui-components.md)
+- [003-env-settings-file-operations.md](003-env-settings-file-operations.md)
+- [005-env-profile-switching.md](005-env-profile-switching.md)
+
+## Estimated Effort
+Medium - Approximately 4-6 hours of development time
+
+## Priority
+High - This is a core functionality for the CLI
+
+## Assignee
+TBD
+
+## Status
+Completed - May 21, 2024
+
+## Implementation Notes
+- Created settings_editor() function as the main entry point
+- Implemented view_env_variables() with pagination and masking of sensitive values
+- Added edit_env_variable(), add_env_variable(), and delete_env_variable() with proper validation
+- Implemented profile management (switch_profile, create_profile, rename_profile, delete_profile)
+- Added settings for show_secrets and vars_per_page control
+- Ensured proper error handling and backups before destructive operations
+- Connected the settings editor to the main CLI menu in src/flock/__init__.py 

flock_core-0.3.22/.project/tasks/done/002-env-settings-ui-components.md

@@ -0,0 +1,67 @@
+# Settings Editor UI Components
+
+## Summary
+Design and implement the user interface components for the environment settings editor in the Flock CLI.
+
+## Description
+This task focuses on creating a well-designed, intuitive UI for the settings editor using Rich and Questionary. The UI should make it easy for users to navigate through settings, understand what they're editing, and get visual feedback on their actions.
+
+## User Story
+[US001 - Environment Settings Editor](../userstories/done/US001-Settings-Editor.md)
+
+## Technical Requirements
+- Create a consistent visual layout for the settings editor
+- Implement color coding for different types of environment variables (secrets, URLs, paths, etc.)
+- Design navigation elements for moving through settings
+- Create input components for editing values with appropriate validation
+- Implement status messages and confirmation dialogs
+- Ensure the UI is responsive and works well in different terminal sizes
+- Provide visual cues for required vs optional settings
+
+## Implementation Plan
+1. Design the main settings list view with pagination
+2. Create a settings detail/edit view
+3. Design confirmation dialogs for destructive actions
+4. Implement status/feedback messages
+5. Create a help/legend component to explain UI elements
+6. Design the "add new setting" form
+7. Ensure consistent styling across all components
+
+## Definition of Done
+- All UI components render correctly in different terminal environments
+- Navigation is intuitive and efficient
+- Visual feedback is clear and helpful
+- Layout adapts to different terminal sizes
+- Consistent styling throughout the application
+- Input validation provides clear error messages
+
+## Dependencies
+- Rich library for formatted output
+- Questionary for interactive input
+- Task 001 (Settings Editor Implementation)
+
+## Related Tasks
+- [001-env-settings-editor.md](../tasks/done/001-env-settings-editor.md)
+- [003-env-settings-file-operations.md](003-env-settings-file-operations.md)
+
+## Estimated Effort
+Medium - Approximately 3-4 hours of development time
+
+## Priority
+High - This is essential for user experience
+
+## Assignee
+TBD
+
+## Status
+Completed - May 21, 2024
+
+## Implementation Notes
+- Implemented UI components using Rich for formatted output
+- Created Rich tables for variable display with proper column styling
+- Added color-coded feedback messages (green for success, yellow for warnings, red for errors)
+- Implemented intuitive navigation with clear options and keyboard shortcuts
+- Added confirmation dialogs for destructive operations
+- Created visual status indicators (e.g., for the show secrets setting)
+- Added helpful hints and instructions for user operations
+- Ensured consistent style and layout throughout the application 

flock_core-0.3.22/.project/tasks/done/003-env-settings-file-operations.md

@@ -0,0 +1,66 @@
+# Environment File Operations
+
+## Summary
+Implement robust file operations for reading, parsing, and writing the .env file in the settings editor.
+
+## Description
+This task focuses on the backend functionality for safely manipulating the .env file, ensuring that changes are properly saved and the file format is preserved.
+
+## User Story
+[US001 - Environment Settings Editor](../userstories/done/US001-Settings-Editor.md)
+
+## Technical Requirements
+- Create a parser for .env files that preserves comments and formatting
+- Implement a safe writing mechanism that prevents data loss
+- Create backup functionality before making changes
+- Handle missing or malformed .env files gracefully
+- Support validation of key-value pairs
+- Handle special characters and multi-line values correctly
+- Implement error handling for file operations
+
+## Implementation Plan
+1. Create a function to parse .env files into a structured format
+2. Implement a function to write changes back to the .env file
+3. Add validation for environment variable names and values
+4. Create backup functionality
+5. Implement error handling for file operations
+6. Add support for creating a new .env file if none exists
+7. Add support for templates based on .env_template
+
+## Definition of Done
+- .env files can be loaded and parsed correctly
+- Comments and formatting are preserved when saving
+- Backups are created before destructive operations
+- Error handling prevents data loss
+- Special characters and multi-line values are handled correctly
+- Missing .env files are handled gracefully
+
+## Dependencies
+- Python's os, io, and shutil modules
+- Optional: python-dotenv library (if appropriate)
+
+## Related Tasks
+- [001-env-settings-editor.md](../tasks/done/001-env-settings-editor.md)
+- [002-env-settings-ui-components.md](002-env-settings-ui-components.md)
+
+## Estimated Effort
+Medium - Approximately 3-4 hours of development time
+
+## Priority
+High - This is critical for data integrity
+
+## Assignee
+TBD
+
+## Status
+Completed - May 21, 2024
+
+## Implementation Notes
+- Created load_env_file() function to parse .env files preserving comments and empty lines
+- Implemented save_env_file() function with proper error handling
+- Added backup_env_file() function to create backups before changes
+- Implemented graceful handling of missing or malformed .env files
+- Added proper validation for variable names and values
+- Ensured correct handling of special characters
+- Implemented support for using .env_template when creating new profiles
+- Added comprehensive error handling throughout file operations