# Changelog

All notable changes to CmdForge will be documented in this file.

## [Unreleased]

### Added

#### System Dependencies
- **System package dependencies for tools**: Tools can now declare system-level package dependencies (apt, brew, pacman, dnf)
  - `system_dependencies` field in tool config.yaml
  - Short form: just package name (e.g., `ffmpeg`)
  - Long form: detailed spec with description, binaries to check, and per-manager package names
  - Automatic platform detection (Linux/macOS/Windows)
  - Package manager detection (apt, brew, pacman, dnf)

- **New dataclass**: `SystemDependency` in tool.py
  - `name` - Package identifier
  - `description` - Why this dependency is needed
  - `binaries` - List of executables to check (defaults to [name])
  - `packages` - Package names per manager (defaults to name for all)
  - Round-trip serialization preserves short/long form

- **New module**: `src/cmdforge/system_deps.py`
  - `detect_os()` - Returns 'linux', 'darwin', or 'windows'
  - `detect_package_manager()` - Returns 'apt', 'brew', 'pacman', 'dnf', or None
  - `check_system_dep()` - Check if dependency is satisfied (any binary found)
  - `install_system_dep()` - Install via system package manager
  - `prompt_install_missing()` - Interactive prompt for installing missing packages

- **New CLI command**: `cmdforge system-deps <tool> [install]`
  - `cmdforge system-deps <tool>` - Show system dependency status
  - `cmdforge system-deps <tool> install` - Install missing system packages
  - `--yes` flag for non-interactive installation

- **Enhanced CLI commands**:
  - `cmdforge check <tool>` - Now shows both CmdForge and system dependencies
  - `cmdforge registry install` - Prompts to install system deps after tool install
    - `--yes` flag to auto-install without prompting
    - `--no-system-deps` flag to skip system dependency handling
  - `cmdforge install` (project) - Handles system deps for manifest and lock-based installs

- **GUI support**:
  - Tool Builder: New "System Dependencies" section
  - Add/Edit/Remove system dependency dialog
  - Shows name and description in list

- **Runtime integration**:
  - Runner warns about missing system dependencies before execution
  - Uses qualified tool refs (owner/name) for registry-installed tools

#### Tool Settings Files
- **Configurable tool settings**: Tools can now ship with default settings that users can customize
  - `defaults.yaml` - Default settings published with the tool (immutable)
  - `settings.yaml` - User's local overrides (auto-created from defaults on first use)
  - Settings available in templates as `{settings.key}` (top-level scalars only)
  - Settings available in code steps as `settings['key']` (full dict access)

- **New CLI commands**:
  - `cmdforge settings <tool> show` - View current settings
  - `cmdforge settings <tool> edit` - Edit settings in $EDITOR
  - `cmdforge settings <tool> reset` - Reset settings to defaults
  - `cmdforge settings <tool> diff` - Show differences from defaults

- **GUI support**:
  - Tool Builder: New "Defaults (Optional)" collapsible section for defining default settings
  - Tools Page: "Configure" button for tools with settings
  - Settings Dialog: Edit tool settings with defaults reference panel

- **Registry integration**:
  - `defaults.yaml` is published alongside `config.yaml` and `README.md`
  - `defaults` field added to registry API (publish, download, info endpoints)
  - Size limit: 64KB for defaults content
  - Secret detection warning on publish (warns about api_key, password, token, etc.)

- **Automatic settings creation**:
  - `ensure_settings()` helper copies defaults.yaml to settings.yaml when missing
  - Called on tool load, save, and registry install for consistency
  - Fully backward compatible - tools without defaults work unchanged

#### Transitive Dependency Resolution
- **Full transitive dependency resolution**: When installing dependencies, CmdForge now resolves and installs the complete dependency tree
  - `DependencyGraph` and `DependencyNode` dataclasses for structured dependency tracking
  - `DependencyGraphBuilder` class for recursive resolution with cycle detection
  - Topological sorting ensures dependencies are installed before dependents (Kahn's algorithm)
  - Version conflict detection with provenance tracking (which package requested each version)
  - Registry config caching during resolution to avoid duplicate fetches

- **Semver version constraint matching**: Full semantic versioning support
  - Caret constraints: `^1.2.3` (>=1.2.3 <2.0.0), `^0.2.3` (>=0.2.3 <0.3.0), `^0.0.3` (exact match)
  - Tilde constraints: `~1.2.3` (>=1.2.3 <1.3.0)
  - Comparison operators: `>=`, `<=`, `>`, `<`, `=`
  - Wildcards: `*`, `latest`
  - Prerelease version handling per semver spec

- **New CLI commands**:
  - `cmdforge deps tree` - Show full dependency tree with transitive dependencies
  - `cmdforge deps tree --verbose` - Show detailed resolution info

- **Enhanced install command**:
  - `--dry-run` - Show what would be installed without installing
  - `--force` - Install despite version conflicts (first constraint wins)
  - `--verbose` - Show detailed resolution info

#### Lock File Support
- **Lock file for reproducible installs**: `cmdforge.lock` records exact versions of all dependencies
  - `Lockfile`, `LockedPackage`, `LockfileMetadata` dataclasses
  - Records direct and transitive dependencies with provenance (`required_by`)
  - Integrity verification via SHA256 hashes (uses registry `config_hash`)
  - Normalized YAML hashing via `hash_utils.compute_yaml_hash()` for consistent integrity checks
  - Platform and Python version metadata for debugging

- **New CLI commands**:
  - `cmdforge lock` - Generate or update `cmdforge.lock`
  - `cmdforge lock --force` - Force regenerate even if up to date
  - `cmdforge verify` - Verify installed tools match lock file

- **Lock-aware install**:
  - `cmdforge install` - Uses lock file when present for reproducible installs
  - `--frozen` - Fail if lock file is missing (for CI)
  - `--strict-frozen` - Fail if lock file is stale (manifest changed)
  - `--ignore-lock` - Ignore lock file and resolve fresh from manifest

#### Local Collections Support
- **Local collection definitions**: Create and manage collections locally before publishing
  - Collections stored as YAML files in `~/.cmdforge/collections/`
  - `Collection` dataclass with name, display_name, description, tools, pinned versions, tags
  - `published`, `registry_name`, `pending_approval`, `pending_tools` fields for tracking state

- **CLI commands for local collections**:
  - `cmdforge collections list --local` - List local collections
  - `cmdforge collections create <name>` - Create new local collection
  - `cmdforge collections show <name>` - View collection details
  - `cmdforge collections add <name> <tool>` - Add tool to collection
  - `cmdforge collections remove <name> <tool>` - Remove tool from collection
  - `cmdforge collections delete <name>` - Delete local collection
  - `cmdforge collections publish <name>` - Publish collection to registry
  - `cmdforge collections status <name>` - Check tool visibility and approval status
  - Flags: `--dry-run`, `--force`, `--continue` for publish workflow

- **GUI Collections page**: New page for managing collections
  - Local collections tab: Create, edit, delete local collections
  - Registry collections tab: Browse and install from registry
  - Publish workflow with tool resolution analysis
  - Background workers for non-blocking install/publish operations

- **Collection publishing workflow**:
  - `resolve_tool_references()` function to transform local tool names to registry refs
  - Visibility checking (tools must be public)
  - Approval status checking (tools must have approved version)
  - Options: publish tools first, skip unpublished, or cancel
  - `ToolResolutionResult` dataclass for structured resolution data

- **New API endpoints**:
  - `GET /api/v1/me` - Get current authenticated user info
  - `GET /api/v1/tools/<owner>/<name>/approved` - Check if tool has approved public version
  - `POST /api/v1/collections` - Publish/update collection (authenticated)

- **New RegistryClient methods**:
  - `get_me()` - Get current user info
  - `has_approved_public_tool(owner, name)` - Check tool approval status
  - `publish_collection(data)` - Publish collection to registry

#### Registry Features
- **Fork tracking and display**: Tools now track their fork origin with `forked_from` and `forked_version` metadata
  - Forked tools show a "Forked from" notice on the tool detail page
  - Original tools display a "Forks" section listing all forks
  - Fork count displayed in tool stats
  - API endpoint: `GET /api/v1/tools/<owner>/<name>/forks`

- **Version selector for installs**: Users can select specific versions when installing tools from the registry
  - Version dropdown in registry page populated via `GET /api/v1/tools/<owner>/<name>/versions`
  - "Latest" option plus all available versions listed
  - Selected version passed to install worker

- **Auto-cleanup rejected versions**: Admin maintenance feature to purge rejected tool submissions
  - API endpoint: `POST /api/v1/admin/cleanup/rejected`
  - Parameters:
    - `days` (default: 7) - grace period before deletion
    - `dry_run` (default: false) - preview mode without actual deletion
  - Admin dashboard UI with "Dry Run" and "Run Cleanup" buttons
  - Shows count of rejected versions pending cleanup

#### GUI Improvements
- Version display and bump buttons in publish dialog
- Auto-fetch registry version when opening publish dialog
- Fork detection during publish workflow
- Always refresh tools page after publish dialog closes
- **Startup connection validation**: GUI validates registry token on startup
  - Automatically clears invalid/revoked tokens
  - Shows status bar message when connection is cleared
  - Prevents confusing errors when trying to publish with stale credentials
- **Help menu and quick guides**: Added Help menu with documentation guides
  - Getting Started guide with quick start steps and keyboard shortcuts
  - How to Create a Tool guide with step-by-step instructions
  - How to Install Tools guide for registry browsing
  - How to Publish Tools guide for sharing tools
  - Keyboard Shortcuts reference
  - About CmdForge dialog
  - F1 shortcut opens Getting Started guide
- **Enhanced tooltips**: Added contextual tooltips throughout the GUI
  - Section headings in Tool Builder (Arguments, Steps, Output Template)
  - Registry page controls (search, filters, pagination, install)
  - Sidebar navigation items with keyboard shortcuts

#### CLI Features
- `cmdforge config disconnect` - Clear registry token from local configuration

#### Admin Features
- Maintenance section in admin dashboard
- Rejected version count display
- Cleanup result modal with detailed output

#### Fabric Sync Improvements
- **AI review logging**: Added comprehensive logging to `run_ai_scrutiny_review()` function
  - Logs tool path checks, warning counts, timing, success/failure states
  - Logs timeout events, JSON parse errors, and all exception types
  - Previously failures were silently swallowed with `return None`
- **`--skip-ai-review` flag**: Skip AI secondary review for large bulk imports
  - Prevents rate limiting and timeouts during initial large imports
  - Usage: `python fabric_sync.py --sync --skip-ai-review`
  - Logs when AI review is skipped with reason

### Fixed
- **Registry search partial matching**: Search now supports prefix matching (e.g., "summ" matches "summarize")
- VERSION_EXISTS error showing after successful publish (made endpoint idempotent by checking config_hash)
- My Tools page listing every version separately (now consolidated by tool name)
- GUI not refreshing after publish dialog closes

### Changed
- Publish endpoint now returns success if same config_hash already exists (idempotent)
- My Tools page groups versions by tool name, showing version count and list

---

## Previous Changes

See git history for changes prior to this changelog.