CmdForge/CHANGELOG.md

# Changelog

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

## [Unreleased]

### Added

#### 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.