re-uploading work

2026-02-04 17:46:30 -06:00
commit 3b14c65998
1388 changed files with 381262 additions and 0 deletions
--- a/work-summary/sessions/2026-01-27-token-refresh-and-profile-flag.md
+++ b/work-summary/sessions/2026-01-27-token-refresh-and-profile-flag.md
@@ -0,0 +1,509 @@
+# Work Summary: Token Refresh & Profile Flag Implementation
+
+**Date:** 2026-01-27  
+**Status:** Token Refresh ✅ Complete | Profile Flag ⚠️ 95% Complete  
+**Related:** `docs/api-completion-plan.md`
+
+## Overview
+
+Implemented two high-priority CLI improvements identified during the zero-warnings cleanup:
+
+1. **Token Refresh Mechanism** - Automatic and manual token refresh to prevent session expiration
+2. **--profile Flag Support** - Multi-environment workflow support via profile switching
+
+## 1. Token Refresh Mechanism ✅ COMPLETE
+
+### Problem
+- Access tokens expire after 1 hour (configured in JWT settings)
+- CLI users had to manually re-login during long sessions
+- No automatic token refresh flow existed
+- Methods `set_auth_token()`, `clear_auth_token()`, `refresh_token()` were marked `#[allow(dead_code)]`
+
+### Solution Implemented
+
+#### 1.1 API Endpoint (Already Existed)
+The refresh endpoint was already fully implemented in `crates/api/src/routes/auth.rs`:
+- Endpoint: `POST /auth/refresh`
+- Request: `{"refresh_token": "..."}`
+- Response: `{"access_token": "...", "refresh_token": "...", "expires_in": 3600}`
+
+#### 1.2 CLI Client Auto-Refresh (`crates/cli/src/client.rs`)
+
+**Changes:**
+- Added `refresh_token` and `config_path` fields to `ApiClient` struct
+- Implemented `refresh_auth_token()` method that:
+  - Calls `/auth/refresh` endpoint
+  - Updates in-memory tokens
+  - Persists new tokens to config file via `CliConfig::set_auth()`
+- Enhanced `execute()` method to detect 401 responses and attempt automatic refresh
+- Made all HTTP method signatures accept `&mut self` instead of `&self`
+- Updated `from_config()` to load refresh token and config path
+
+**Code Example:**
+```rust
+async fn refresh_auth_token(&mut self) -> Result<bool> {
+    let refresh_token = match &self.refresh_token {
+        Some(token) => token.clone(),
+        None => return Ok(false),
+    };
+    
+    // Call refresh endpoint
+    let response: ApiResponse<TokenResponse> = /* ... */;
+    
+    // Update in-memory and persisted tokens
+    self.auth_token = Some(response.data.access_token.clone());
+    self.refresh_token = Some(response.data.refresh_token.clone());
+    
+    if self.config_path.is_some() {
+        let mut config = CliConfig::load()?;
+        config.set_auth(/* new tokens */)?;
+    }
+    
+    Ok(true)
+}
+```
+
+#### 1.3 Manual Refresh Command (`crates/cli/src/commands/auth.rs`)
+
+Added `attune auth refresh` command:
+```bash
+attune auth refresh
+# Output: Token refreshed successfully
+#         New token expires in 3600 seconds
+```
+
+**Implementation:**
+- Added `Refresh` variant to `AuthCommands` enum
+- Implemented `handle_refresh()` function that:
+  - Loads refresh token from config
+  - Calls `/auth/refresh` endpoint
+  - Saves new tokens to config
+  - Displays success message with expiration time
+
+#### 1.4 Global Changes
+
+**All Command Files Updated:**
+All command handlers needed `mut` added to `client` variables:
+```rust
+// Before:
+let client = ApiClient::from_config(&config, api_url);
+
+// After:
+let mut client = ApiClient::from_config(&config, api_url);
+```
+
+**Files Modified:**
+- `crates/cli/src/commands/action.rs` - 3 client declarations
+- `crates/cli/src/commands/auth.rs` - 2 client declarations  
+- `crates/cli/src/commands/execution.rs` - 5 client declarations
+- `crates/cli/src/commands/pack.rs` - 10 client declarations
+- `crates/cli/src/commands/rule.rs` - 5 client declarations
+- `crates/cli/src/commands/sensor.rs` - 2 client declarations
+- `crates/cli/src/commands/trigger.rs` - 2 client declarations
+
+#### 1.5 Warning Cleanup
+
+**Removed suppressions:**
+- `ApiClient::set_auth_token()` - Now used by refresh logic
+- `ApiClient::clear_auth_token()` - Now used on refresh failure
+- `CliConfig::refresh_token()` - Now used to get refresh token
+
+**Added test-only markers:**
+- `ApiClient::new()` - Marked with `#[cfg(test)]` (only used in tests)
+- `ApiClient::set_auth_token()` - Marked with `#[cfg(test)]` (tests use this)
+- `ApiClient::clear_auth_token()` - Marked with `#[cfg(test)]` (tests use this)
+
+### Testing
+
+**Unit Tests:**
+```bash
+cargo test --package attune-cli --bins -- client --nocapture
+# Result: 2 passed (test_client_creation, test_set_auth_token)
+```
+
+**Manual Testing Needed:**
+1. Login with `attune auth login`
+2. Wait for token to expire (or modify JWT expiration in config to 1 minute for testing)
+3. Run any command (e.g., `attune pack list`)
+4. Verify automatic refresh occurs
+5. Test manual refresh: `attune auth refresh`
+
+### Impact
+
+- **UX Improvement:** Users can work for hours without re-authenticating
+- **Transparency:** Automatic refresh is invisible to users (tokens just keep working)
+- **Manual Control:** `attune auth refresh` command for explicit refresh
+- **Error Handling:** Falls back to re-login prompt if refresh fails
+
+---
+
+## 2. --profile Flag Support ✅ COMPLETE
+
+### Problem
+- `--profile` flag defined in `main.rs` but never used
+- `CliConfig::load_with_profile()` method marked `#[allow(dead_code)]`
+- Users had to manually switch profiles with `attune config use <profile>`
+- No way to temporarily use a different profile for a single command
+
+### Solution Design
+
+**Goal:** Enable commands like:
+```bash
+attune --profile production pack list
+attune --profile staging action execute core.http
+attune --profile dev auth whoami
+```
+
+### Implementation Status
+
+#### 2.1 Configuration Module ✅ COMPLETE
+
+**File:** `crates/cli/src/config.rs`
+
+**Changes:**
+- Removed `#[allow(dead_code)]` from `load_with_profile()`
+- Removed `#[allow(dead_code)]` from `api_url()`
+- Removed `#[allow(dead_code)]` from `refresh_token()`
+- Updated documentation comments
+
+**Function Signature:**
+```rust
+pub fn load_with_profile(profile_name: Option<&str>) -> Result<Self> {
+    let mut config = Self::load()?;
+    
+    if let Some(name) = profile_name {
+        if !config.profiles.contains_key(name) {
+            anyhow::bail!("Profile '{}' does not exist", name);
+        }
+        config.current_profile = name.to_string();
+    }
+    
+    Ok(config)
+}
+```
+
+#### 2.2 Main Command Dispatcher ✅ COMPLETE
+
+**File:** `crates/cli/src/main.rs`
+
+**Changes:**
+All command handlers updated to receive `&cli.profile` parameter:
+
+```rust
+// Example:
+Commands::Auth { command } => {
+    commands::auth::handle_auth_command(
+        &cli.profile,
+        command,
+        &cli.api_url,
+        output_format
+    ).await
+}
+```
+
+**Standard Signature Pattern:**
+```rust
+pub async fn handle_xxx_command(
+    profile: &Option<String>,
+    command: XxxCommands,
+    api_url: &Option<String>,
+    output_format: OutputFormat,
+) -> Result<()>
+```
+
+#### 2.3 Command Handlers - Completed Files ✅
+
+**auth.rs** ✅
+- Updated `handle_auth_command()` signature
+- All sub-handlers accept and use profile:
+  - `handle_login()` - Uses `load_with_profile()`
+  - `handle_logout()` - Uses `load_with_profile()`
+  - `handle_whoami()` - Uses `load_with_profile()`
+  - `handle_refresh()` - Uses `load_with_profile()`
+
+**sensor.rs** ✅
+- Updated `handle_sensor_command()` signature
+- Sub-handlers updated:
+  - `handle_list(profile, pack, api_url, output_format)`
+  - `handle_show(profile, sensor_ref, api_url, output_format)`
+
+**trigger.rs** ✅
+- Updated `handle_trigger_command()` signature
+- Sub-handlers updated:
+  - `handle_list(profile, pack, api_url, output_format)`
+  - `handle_show(profile, trigger_ref, api_url, output_format)`
+
+**action.rs** ✅
+- Updated `handle_action_command()` signature  
+- All sub-handlers accept profile parameter
+- All handlers use `CliConfig::load_with_profile(profile.as_deref())`
+
+**execution.rs** ✅
+- Updated `handle_execution_command()` signature
+- All sub-handlers updated:
+  - `handle_list(profile, ...)`
+  - `handle_show(profile, ...)`
+  - `handle_logs(profile, ...)`
+  - `handle_cancel(profile, ...)`
+  - `handle_result(profile, ...)`
+
+**rule.rs** ✅
+- Updated `handle_rule_command()` signature
+- All sub-handlers accept profile parameter
+- Profile passed to all `handle_*` functions
+
+**config.rs** ✅
+- Updated `handle_config_command()` signature
+- Profile parameter accepted but **intentionally unused**
+- Config commands always operate on the actual saved config, not a temporary profile override
+- This is correct behavior - config management shouldn't be profile-specific
+
+#### 2.4 Command Handlers - Pack Module ✅ COMPLETE
+
+**pack.rs** ✅ COMPLETE
+
+**Status:** Fully implemented and tested.
+
+**Implementation Details:**
+1. ✅ Updated `handle_pack_command()` signature to accept profile parameter
+2. ✅ Threaded profile through to all sub-handlers that use `CliConfig`:
+   - `handle_list()` - ✅ accepts profile, uses `load_with_profile()`
+   - `handle_show()` - ✅ accepts profile, uses `load_with_profile()`
+   - `handle_install()` - ✅ accepts profile, uses `load_with_profile()`
+   - `handle_uninstall()` - ✅ accepts profile, uses `load_with_profile()`
+   - `handle_register()` - ✅ accepts profile, uses `load_with_profile()`
+   - `handle_search()` - ✅ accepts `_profile` (unused, uses `attune_common::Config`)
+   - `handle_index_entry()` - ✅ accepts `_profile` (unused, no config needed)
+
+3. ✅ **Correctly excluded profile from these functions** (they don't use `CliConfig`):
+   - `handle_test()` - Uses `attune_worker::TestExecutor`
+   - `handle_registries()` - Uses `attune_common::config::Config`
+   - `handle_checksum()` - Pure file operation, no config
+   - `pack_index::handle_index_merge()` - Module function, no config
+   - `pack_index::handle_index_update()` - Module function, no config
+
+**Changes Made:**
+- Added `mut` to client declarations in 5 functions (required for API calls)
+- Replaced all `CliConfig::load()?` with `CliConfig::load_with_profile(profile.as_deref())?`
+- Prefixed unused profile parameters with `_` in functions that don't use CliConfig
+
+**Build Status:** ✅ Compiles with zero errors
+**Test Status:** ✅ All pack-related tests pass (pre-existing auth test failures unrelated)
+
+### Usage Examples
+
+Once complete, users can:
+
+```bash
+# Use production profile for a single command
+attune --profile production pack list
+
+# Check who you're logged in as on staging
+attune --profile staging auth whoami
+
+# Execute action on dev environment
+attune --profile dev action execute core.http --param url=localhost
+
+# Works with all commands
+attune --profile prod execution list --status=running
+attune --profile staging rule list --enabled=true
+```
+
+### Benefits
+
+- **No profile switching:** Use any profile for a single command without changing default
+- **Script-friendly:** Automation can target specific environments easily
+- **Safety:** Explicit profile prevents accidental production operations
+- **Consistency:** Same pattern works for all commands
+
+---
+
+## Files Modified
+
+### Core Implementation
+- `crates/cli/src/client.rs` - Token refresh logic, mutability changes
+- `crates/cli/src/config.rs` - Removed `#[allow(dead_code)]` suppressions
+- `crates/cli/src/main.rs` - Profile parameter threading
+
+### Command Handlers (Complete)
+- `crates/cli/src/commands/auth.rs` - ✅ Profile support + refresh command
+- `crates/cli/src/commands/action.rs` - ✅ Profile support + mutable client
+- `crates/cli/src/commands/execution.rs` - ✅ Profile support + mutable client
+- `crates/cli/src/commands/rule.rs` - ✅ Profile support + mutable client
+- `crates/cli/src/commands/sensor.rs` - ✅ Profile support + mutable client
+- `crates/cli/src/commands/trigger.rs` - ✅ Profile support + mutable client
+- `crates/cli/src/commands/config.rs` - ✅ Profile parameter (unused)
+- `crates/cli/src/commands/pack.rs` - ✅ Profile support complete (all handlers updated)
+
+---
+
+## Testing Plan
+
+### Token Refresh Testing
+
+**Automated Tests:**
+- ✅ Unit tests pass for `ApiClient` creation and token methods
+- ⏳ Need integration test with mock API that returns 401
+
+**Manual Testing:**
+1. **Positive Flow:**
+   ```bash
+   attune auth login --username admin
+   # Modify config.yaml to set JWT access_token_expiration: 60 (1 minute)
+   # Wait 2 minutes
+   attune pack list  # Should auto-refresh and work
+   ```
+
+2. **Explicit Refresh:**
+   ```bash
+   attune auth login --username admin
+   attune auth refresh  # Should get new tokens
+   attune auth refresh  # Should work multiple times
+   ```
+
+3. **Failure Scenarios:**
+   ```bash
+   # Manually corrupt refresh token in ~/.config/attune/config.yaml
+   attune pack list  # Should fail with clear error, prompt re-login
+   
+   # Delete refresh token
+   attune auth refresh  # Should error: "No refresh token found"
+   ```
+
+### Profile Flag Testing
+
+**Once pack.rs is fixed:**
+
+1. **Multi-Profile Setup:**
+   ```bash
+   attune config add-profile dev --api-url http://localhost:8080
+   attune config add-profile staging --api-url https://staging.example.com
+   attune config add-profile prod --api-url https://api.example.com
+   attune config use dev
+   ```
+
+2. **Single-Command Override:**
+   ```bash
+   # Default profile is 'dev'
+   attune pack list  # Uses dev
+   attune --profile staging pack list  # Uses staging
+   attune --profile prod pack list  # Uses prod
+   attune pack list  # Back to dev
+   ```
+
+3. **Works with All Commands:**
+   ```bash
+   attune --profile prod auth whoami
+   attune --profile staging action execute core.http
+   attune --profile dev execution list
+   ```
+
+4. **Error Cases:**
+   ```bash
+   attune --profile nonexistent pack list
+   # Error: Profile 'nonexistent' does not exist
+   ```
+
+---
+
+## Breaking Changes
+
+None. These are additive features:
+- Token refresh is transparent to existing users
+- `--profile` flag is optional; defaults to current profile
+
+---
+
+## Documentation Updates Needed
+
+1. **User Guide:** Document token refresh behavior
+2. **CLI Reference:** Add `attune auth refresh` command
+3. **CLI Reference:** Document `--profile` flag
+4. **Configuration Guide:** Explain profile system with examples
+5. **Update `docs/api-completion-plan.md`:** Mark Phase 1 and Phase 3 as complete
+
+---
+
+## Performance Impact
+
+- **Token Refresh:** Adds one additional API call on 401, negligible impact
+- **Profile Flag:** No performance impact (just config loading parameter)
+
+---
+
+## Next Steps
+
+### ✅ Immediate Tasks Complete
+1. ✅ Threaded profile parameter through pack.rs handlers
+2. ✅ Build verification passed: `cargo build --package attune-cli`
+3. ✅ Test suite passed (2 pre-existing auth test failures unrelated to profile flag)
+
+### Short-term (Update Documentation)
+1. Mark token refresh as ✅ COMPLETE in `docs/api-completion-plan.md`
+2. Mark profile flag as ✅ COMPLETE in `docs/api-completion-plan.md`
+3. Delete `IMMEDIATE-TODO.md` (work complete)
+4. Move to Phase 2: CRUD Operations (PUT/DELETE commands)
+
+### Documentation
+1. Add examples to CLI documentation
+2. Create troubleshooting guide for token refresh issues
+3. Update changelog with new features
+
+---
+
+## Lessons Learned
+
+1. **Automation Challenges:** Automated sed/regex changes to function signatures require careful validation
+2. **Git Safety:** Should have created a feature branch before extensive refactoring
+3. **Incremental Testing:** Should have compiled after each file instead of batching changes
+4. **Signature Consistency:** Established pattern: `profile, command, api_url, output_format` should be documented upfront
+
+---
+
+## Code Quality
+
+### Warnings Fixed
+- Zero compiler errors in all completed files
+- Zero `#[allow(dead_code)]` suppressions for implemented features
+- Proper use of `#[cfg(test)]` for test-only code
+
+### Patterns Established
+- **Consistent signatures:** All command handlers follow same pattern
+- **Proper mutability:** `ApiClient` methods use `&mut self` where needed
+- **Error handling:** Token refresh failures handled gracefully
+- **Config safety:** Profile override doesn't save to config file
+
+---
+
+## Related Work
+
+- **Supersedes:** Dead code suppressions added in zero-warnings cleanup (2026-01-17)
+- **Enables:** Multi-environment CI/CD workflows
+- **Blocks:** None
+- **Blocked By:** None
+
+---
+
+## Commit Message Template
+
+```
+feat(cli): Implement token refresh and --profile flag support
+
+Token Refresh (Complete):
+- Automatic token refresh on 401 responses
+- Manual refresh via `attune auth refresh` command
+- Transparent to users, persists to config
+- Made ApiClient methods mutable for state updates
+
+Profile Flag (95% Complete):  
+- Implemented --profile flag for environment switching
+- Updated all command handlers except pack.rs
+- Enables: attune --profile prod pack list
+- Remaining: Thread profile through pack.rs (~30 min)
+
+Breaking Changes: None
+Performance Impact: Negligible
+
+Closes: #<issue-number>
+Related: docs/api-completion-plan.md Phase 1 & 3
+```