cli: Fix test hygiene and remove unused imports

Author: davidabram

cli/README.md

@@ -0,0 +1,374 @@
+# sce - Shared Context Engineering CLI
+
+A Rust CLI for Shared Context Engineering workflows, including WorkOS SSO authentication and local Agent Trace attribution.
+
+## Overview
+
+The `sce` CLI provides:
+- **Authentication**: WorkOS SSO/OIDC via OAuth 2.0 Device Authorization Flow
+- **Setup**: Install OpenCode and Claude configuration files and git hooks
+- **Doctor**: Validate local git-hook installation readiness
+- **Agent Trace**: Git hooks for local attribution tracking
+- **Config**: Inspect and validate runtime configuration
+
+Some commands remain in placeholder state (`mcp`, `sync`) and are under active development.
+
+## Installation
+
+### Local Cargo Install
+
+```bash
+cargo install --path cli --locked
+```
+
+### Nix Flake
+
+Build the release package:
+```bash
+nix build ./cli#default
+```
+
+Run directly:
+```bash
+nix run ./cli#sce -- --help
+```
+
+## Quick Start
+
+```bash
+# View available commands
+sce --help
+
+# Configure WorkOS (required for auth commands)
+export WORKOS_CLIENT_ID="client_your_client_id"
+
+# Authenticate with WorkOS
+sce login
+
+# Check authentication status
+sce auth status
+
+# Set up local repository
+sce setup
+
+# Validate hook installation
+sce doctor
+
+# Log out when done
+sce logout
+```
+
+## Authentication
+
+The CLI uses WorkOS SSO/OIDC authentication via the OAuth 2.0 Device Authorization Flow (RFC 8628). Authentication is required for the `sync` command.
+
+### Configuration
+
+Set your WorkOS client ID via environment variable or config file:
+
+**Environment Variable (recommended):**
+```bash
+export WORKOS_CLIENT_ID="client_your_client_id"
+```
+
+**Config File:**
+
+Create `.sce/config.json` in your repository or `${XDG_STATE_HOME:-~/.local/state}/sce/config.json` for global config:
+
+```json
+{
+  "workos_client_id": "client_your_client_id"
+}
+```
+
+### Login
+
+Start the device authorization flow:
+
+```bash
+sce login
+```
+
+The CLI will:
+1. Request a device code from WorkOS
+2. Display a verification URL and user code
+3. Poll WorkOS until you complete authentication in your browser
+4. Store the access token and refresh token locally
+
+Example output:
+```
+WorkOS login required
+Open this URL: https://workos.com/device?user_code=ABCD-EFGH
+User code: ABCD-EFGH
+Waiting for authorization... (polling every 5s)
+Authentication successful. Stored WorkOS credentials at '/home/user/.local/state/sce/auth/tokens.json' and issued access token lifetime is 3600s.
+```
+
+### Check Authentication Status
+
+```bash
+# Text output (default)
+sce auth status
+
+# JSON output
+sce auth status --format json
+```
+
+Example output:
+```
+Authenticated. Token expires in 1 hours.
+```
+
+JSON output includes:
+```json
+{
+  "status": "ok",
+  "command": "auth status",
+  "authenticated": true,
+  "token_status": "valid",
+  "expires_at": "2024-01-15T12:00:00+00:00",
+  "expires_in_seconds": 3600
+}
+```
+
+### Logout
+
+Remove stored credentials:
+
+```bash
+sce logout
+```
+
+Example output:
+```
+Logged out successfully. Removed stored WorkOS credentials at '/home/user/.local/state/sce/auth/tokens.json'.
+```
+
+### Token Storage
+
+Tokens are stored locally with restricted file permissions:
+
+| Platform | Path | Permissions |
+|----------|------|-------------|
+| Linux | `${XDG_STATE_HOME:-~/.local/state}/sce/auth/tokens.json` | 0600 (owner read/write) |
+| macOS | `~/Library/Application Support/sce/auth/tokens.json` | User-only |
+| Windows | `%APPDATA%\sce\auth\tokens.json` | User-only ACL |
+
+**Security Notes:**
+- Tokens are stored unencrypted (filesystem permissions provide protection)
+- For production use, consider OS keychain integration (future enhancement)
+- Access tokens typically expire after 1 hour
+- Refresh tokens are used to automatically obtain new access tokens
+- If both tokens expire, re-authentication is required
+
+### Token Refresh
+
+The CLI automatically refreshes expired access tokens using the refresh token when:
+- Running `sce sync` (authentication is checked before execution)
+- The access token has expired but the refresh token is still valid
+
+If the refresh token expires, you'll need to run `sce login` again.
+
+## Command Reference
+
+### Implemented Commands
+
+| Command | Description |
+|---------|-------------|
+| `sce --help` | Show available commands |
+| `sce login` | Authenticate with WorkOS via device flow |
+| `sce logout` | Clear stored WorkOS credentials |
+| `sce auth status` | Show authentication state |
+| `sce config show` | Display resolved configuration |
+| `sce config validate` | Validate configuration settings |
+| `sce setup` | Install config files and git hooks |
+| `sce doctor` | Validate git-hook installation |
+| `sce hooks <subcommand>` | Run git-hook entrypoints |
+| `sce version` | Print version information |
+| `sce completion --shell <bash\|zsh\|fish>` | Generate shell completion |
+
+### Placeholder Commands
+
+| Command | Description |
+|---------|-------------|
+| `sce mcp` | MCP file-cache tooling (planned) |
+| `sce sync` | Cloud sync workflows (requires auth) |
+
+## Setup Command
+
+Install OpenCode/Claude configuration and required git hooks:
+
+```bash
+# Interactive setup (default)
+sce setup
+
+# Non-interactive with target selection
+sce setup --opencode --non-interactive
+sce setup --claude --non-interactive
+sce setup --both --non-interactive
+
+# Install hooks only
+sce setup --hooks
+
+# Install hooks for a specific repository
+sce setup --hooks --repo /path/to/repo
+
+# Combined: config + hooks
+sce setup --opencode --hooks
+```
+
+## Configuration
+
+### Configuration Precedence
+
+Values are resolved in this order (later overrides earlier):
+1. Defaults
+2. Config file (global then local)
+3. Environment variables
+4. Command-line flags
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `WORKOS_CLIENT_ID` | WorkOS client ID for authentication |
+| `SCE_CONFIG_FILE` | Path to config file |
+| `SCE_LOG_LEVEL` | Log threshold: `error`, `warn`, `info`, `debug` |
+| `SCE_LOG_FORMAT` | Log format: `text`, `json` |
+| `SCE_LOG_FILE` | Optional log file path |
+| `SCE_LOG_FILE_MODE` | File mode: `truncate` (default), `append` |
+| `SCE_OTEL_ENABLED` | Enable OpenTelemetry: `true`, `false` |
+
+### Config File Schema
+
+```json
+{
+  "log_level": "info",
+  "timeout_ms": 30000,
+  "workos_client_id": "client_your_client_id"
+}
+```
+
+## Troubleshooting
+
+### "WorkOS client ID is not configured"
+
+**Cause**: `WORKOS_CLIENT_ID` environment variable is not set and no config file contains `workos_client_id`.
+
+**Solution**:
+```bash
+export WORKOS_CLIENT_ID="client_your_client_id"
+sce login
+```
+
+### "Not authenticated. Run 'sce login' to authenticate."
+
+**Cause**: No stored tokens found.
+
+**Solution**:
+```bash
+sce login
+```
+
+### "Token has expired. Run 'sce login' to re-authenticate."
+
+**Cause**: Both access token and refresh token have expired.
+
+**Solution**:
+```bash
+sce login
+```
+
+### "Stored authentication tokens are invalid"
+
+**Cause**: Token file is corrupted or malformed.
+
+**Solution**:
+```bash
+sce logout
+sce login
+```
+
+### "Failed to resolve token storage path"
+
+**Cause**: Home directory or state directory cannot be resolved.
+
+**Solution**:
+- Ensure `HOME` environment variable is set (Linux/macOS)
+- Ensure `USERPROFILE` environment variable is set (Windows)
+- On Linux, ensure XDG directories are accessible
+
+### Device Authorization Timeout
+
+**Cause**: Device code expired before authentication was completed (typically 10-30 minutes).
+
+**Solution**:
+```bash
+sce login
+# Complete authentication in browser within the time limit
+```
+
+### Permission Denied on Token File
+
+**Cause**: Token file permissions are incorrect or directory is not writable.
+
+**Solution**:
+```bash
+# Check permissions
+ls -la ~/.local/state/sce/auth/
+
+# Remove and re-authenticate
+sce logout
+sce login
+```
+
+### "Run 'sce login' first" when running sync
+
+**Cause**: The `sync` command requires valid authentication.
+
+**Solution**:
+```bash
+# Check current auth status
+sce auth status
+
+# If not authenticated, log in
+sce login
+
+# Then run sync
+sce sync
+```
+
+## Exit Codes
+
+| Code | Class | Description |
+|------|-------|-------------|
+| 0 | Success | Command completed successfully |
+| 2 | Parse | Invalid command syntax or unknown options |
+| 3 | Validation | Invalid arguments or configuration |
+| 4 | Runtime | Command execution failed |
+| 5 | Dependency | Required runtime dependencies unavailable |
+
+## Development
+
+### Build
+
+```bash
+cargo build --manifest-path cli/Cargo.toml
+```
+
+### Test
+
+```bash
+cargo test --manifest-path cli/Cargo.toml
+```
+
+### Run Checks
+
+```bash
+cargo fmt --check --manifest-path cli/Cargo.toml
+cargo clippy --manifest-path cli/Cargo.toml
+```
+
+## License
+
+See repository root for license information.

cli/src/services/setup/tests.rs

@@ -526,9 +526,15 @@ fn required_hook_install_updates_noncanonical_hook_in_custom_hooks_path() -> Res
     let temp = TestTempDir::new("sce-setup-hook-install-tests")?;
     init_git_repo(temp.path())?;
 
-    run_git_in_repo(temp.path(), &["config", "core.hooksPath", ".githooks"])?;
-
     let custom_hooks_directory = temp.path().join(".githooks");
+    run_git_in_repo(
+        temp.path(),
+        &[
+            "config",
+            "core.hooksPath",
+            custom_hooks_directory.to_str().unwrap(),
+        ],
+    )?;
     fs::create_dir_all(&custom_hooks_directory)?;
     let commit_msg_path = custom_hooks_directory.join("commit-msg");
     fs::write(&commit_msg_path, b"#!/bin/sh\necho legacy\n")?;