Skip to content

CHANGELOG.md

Latest commit

 

History

History
428 lines (331 loc) · 26.8 KB

CHANGELOG.md

File metadata and controls

428 lines (331 loc) · 26.8 KB

Changelog

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

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Roadmap

For a comprehensive roadmap with detailed status, priorities, and implementation plans, see ROADMAP.md.

0.2.4 - 2026-03-29

Changed

  • Dependencies - Bumped @modelcontextprotocol/sdk and dev dependencies (package.json / package-lock.json). No MCP tool or runtime behavior changes intended. patch release for supply-chain and compatibility maintenance. (#43)

0.2.3 - 2026-03-26

  • Documentation links aligned with CLI structure (#41)

0.2.2 - 2026-03-24

Changed

  • Canonical documentation links match logicstamp-context docs/ layout (#38)
    • Updated logicstamp_read_logicstamp_docs GitHub fallbacks to current paths (docs/guides/usage.md, docs/reference/uif-contracts.md, docs/reference/schema.md, docs/reference/limitations.md; CLI pages unchanged under docs/cli/)
    • Set limitations primary URL to https://logicstamp.dev/docs/reference/limitations
    • Refreshed docs/logicstamp-for-llms.md, docs/commands/read-logicstamp-docs.md, README, and docs/getting-started.md (including CLI repo docs/ layout note and fixed external links)

0.2.1 - 2026-03-06

Added

  • Watch Mode Retry Logic (#35) - Added automatic retry mechanism with exponential backoff for reading files when watch mode is active
    • Initial delay before reading files: 200ms for regular watch mode, 500ms for strict watch mode
    • Automatic retry up to 3 times with exponential backoff (100ms, 200ms, 400ms) if JSON parsing fails
    • Prevents race conditions when watch mode is actively writing context files
    • Worst case total wait: ~900ms for regular watch, ~1.1s for strict watch
    • Only applies when watch mode is active - no performance impact otherwise
    • Updated logicstamp_read_bundle and logicstamp_list_bundles to use retry logic
      • Documentation Warnings Against External sleep() - Added explicit, prominent warnings in tool descriptions and outputs to prevent AI assistants from using unnecessary sleep() calls
      • Tool Descriptions - Added "⚠️ CRITICAL: Do NOT use sleep() delays" as the FIRST line in all relevant tool descriptions (logicstamp_watch_status, logicstamp_list_bundles, logicstamp_read_bundle, logicstamp_refresh_snapshot) to ensure AI assistants see the warning immediately
      • Tool Output Warnings - Added warning field to logicstamp_read_bundle and logicstamp_list_bundles outputs when watch mode is active, ensuring warnings appear in every response
      • Watch Status Messages - Enhanced logicstamp_watch_status messages to explicitly state "DO NOT use sleep() delays" when watch mode is active
      • Documentation - Added comprehensive section in docs/logicstamp-for-llms.md explaining why sleep() is unnecessary
      • Command Documentation - Updated command documentation (docs/commands/read-bundle.md, docs/commands/list-bundles.md) with warnings that delays are internal
      • Emphasizes that watch mode keeps bundles fresh automatically - AI assistants should read bundles directly without waiting
      • Explains that internal retry logic handles all race conditions (200-500ms delays + exponential backoff built-in)
      • Multiple warning touchpoints (descriptions, outputs, messages) ensure AI assistants cannot miss the guidance
      • Prevents unnecessary delays that slow down AI assistant workflows when watch mode is active
    • Branch Testing Improvements (#36) - Added comprehensive branch coverage tests for read-logicstamp-docs.ts and compare-snapshot.ts
      • Added tests for filesystem root check in findPackageRoot function
      • Added test for invalid docPath validation branch by exporting readDocFile for testing purposes
      • Added depth validation tests (invalid, negative, non-integer values)
      • Added baseline path resolution tests (snapshot, disk, custom path baselines)
      • Added profile-specific command building tests for different profiles and depth combinations
      • Added bundle hash comparison tests (hash changes, bundle addition/removal scenarios)
      • Added tests for missing contracts, loadBundles error handling, and token delta fallback calculation
      • Added cache cleanup tests for corruption detection scenarios
      • Improves branch coverage for error handling paths and edge cases
      • Exported readDocFile function for testing to enable coverage of defensive validation branch (line 93)

Fixed

  • TypeScript File Validation (#35) - Fixed issue where TypeScript file validation errors were masked by JSON parse errors in retry logic
    • Retry logic now checks for TypeScript files (starting with import or export) before attempting JSON parsing
    • Ensures proper error messages when users accidentally point to TypeScript source files instead of JSON bundle files

0.2.0 - 2026-03-03

⚠️ Breaking Changes

  • Minimum Node.js version is now >= 20.
    • logicstamp-mcp now requires Node.js 20 or higher.
    • This aligns MCP with the logicstamp-context CLI runtime requirements.
    • Users on Node.js 18 must upgrade to continue using MCP.

Changed

  • Enhanced Watch Mode Functionality and Documentation (#26) - Improved watch mode detection and documentation clarity

    • Improved descriptions in server tools to clarify the distinction between ROOT components and DEPENDENCIES
    • Added cleanup of stale watch status files when the process is no longer running across multiple tools
    • Updated watch status handling to include strict watch mode detection, enhancing user awareness of breaking change detection
    • Enhanced tests to verify strict watch mode functionality and its reporting in various scenarios
    • Updated schemas to reflect the new strict watch mode field in watch status outputs

  • Documentation Updates and Node.js Requirement (#27) - Updated Node.js requirement and enhanced documentation clarity

    • Updated Node.js version requirement to >= 20 across various documentation files for consistency
    • Improved clarity in documentation regarding the distinction between ROOT components and DEPENDENCIES
    • Enhanced descriptions in multiple guides to reflect the latest tool capabilities and usage patterns
    • Adjusted default behavior notes for skipIfWatchActive in the refresh_snapshot command

  • Documentation Improvements (#28) - Updated README and roadmap for clarity and consistency

    • Revised Node.js version requirement to >= 20 across documentation
    • Enhanced README with a new Table of Contents and improved descriptions for better navigation and understanding
    • Updated roadmap with the correct last updated date format
    • Adjusted various sections for clarity, including prerequisites and features, to reflect the latest tool capabilities

  • Test Coverage Improvements (#29) - Enhanced test coverage for better code quality assurance

    • Added comprehensive tests for watch mode detection and direct projectPath access in list-bundles.ts and read-bundle.ts
    • Added tests for TypeScript file validation and LogicStampIndex type validation in read-bundle.ts
    • Added tests for error paths in read-logicstamp-docs.ts including package root detection and fallback strategies
    • Added tests for server parameter validation edge cases
    • Improved branch coverage for error handling paths and edge cases
    • All new tests passing with improved confidence in error handling and watch mode functionality

0.1.6 - 2026-02-09

Changed

  • Tool Description Optimization - Optimized all 7 MCP tool descriptions for better LLM comprehension

    • Reduced description length by ~40-50% while preserving all critical information
    • Removed redundancy (duplicate "WHAT IT DOES" sections, repeated watch mode explanations)
    • Consolidated related information into more scannable formats
    • Improved structure: Warning → What → Returns → When → Next → Options → Docs
    • All implementation details preserved - no functional changes
    • Watch mode workflows now clearly documented in all relevant tools
    • Makes it easier for LLMs to understand and use LogicStamp correctly

  • Code Refactoring - Extracted duplicated isProcessRunning function into shared utility

    • Created src/mcp/utils/process-utils.ts with shared process checking logic
    • Removed duplicate implementations from watch-status.ts, read-bundle.ts, refresh-snapshot.ts, and list-bundles.ts
    • Improves code maintainability and makes future platform-specific fixes easier
    • No functional changes - behavior remains identical

0.1.5 - 2026-01-21

Added

  • Watch Mode Awareness - MCP server now detects and integrates with stamp context --watch incremental rebuild mode

    • New Tool: logicstamp_watch_status - Check if watch mode is active for a project
      • Returns watch status including PID, start time, and whether context is being kept fresh
      • Optionally includes recent watch logs showing what files changed and what contracts/bundles were modified
      • Helps AI assistants decide whether to skip regeneration
    • New Parameter: skipIfWatchActive - Added to logicstamp_refresh_snapshot
      • When true and watch mode is running, skips expensive regeneration and just reads existing context files
      • Returns watchMode info in response indicating context is already fresh
      • Recommended approach when watch mode is keeping context up-to-date via incremental rebuilds
    • Watch Mode Detection - logicstamp_refresh_snapshot now detects active watch mode and includes status in response
      • Reports watchMode.active, watchMode.pid, watchMode.startedAt, and helpful message
      • Guides AI assistants to skip future regeneration calls when watch mode is active

  • New Types - Added TypeScript types for watch mode integration

    • WatchStatus - Structure of .logicstamp/context_watch-status.json
    • WatchLogEntry - Structure of watch log entries
    • WatchStatusInput / WatchStatusOutput - Input/output types for the new tool

  • Watch Mode Direct Access - logicstamp_list_bundles and logicstamp_read_bundle now support direct disk access without a snapshotId

    • New Parameter: projectPath - Provide project path instead of snapshotId for instant access when watch mode is active
    • snapshotId Now Optional - When watch mode is active, LLMs can skip refresh_snapshot entirely and go directly to list_bundles/read_bundle with just projectPath
    • Zero-Cost Context Access - When watch mode keeps context fresh, no regeneration or snapshot creation needed
    • Automatic Watch Mode Detection - Tools detect watch mode status and indicate it in response with watchMode: true
    • This enables the optimal workflow: watch_status → list_bundles(projectPath) → read_bundle(projectPath) without any regeneration step

Changed

  • Tool Count - Increased from 6 to 7 tools with addition of logicstamp_watch_status
  • skipIfWatchActive Default Changed to true - When watch mode is active, logicstamp_refresh_snapshot now automatically skips regeneration by default
    • Previously defaulted to false, requiring explicit opt-in
    • Now defaults to true for zero-cost instant context access when watch mode is running
    • Set skipIfWatchActive: false to force regeneration even when watch mode is active
  • Tool Descriptions Rewritten for Watch Mode Workflow - All tool descriptions now prominently guide LLMs to check watch status first
    • logicstamp_watch_status - Now marked as "⚠️ CALL THIS FIRST before any other LogicStamp tool!" with clear decision tree
    • logicstamp_refresh_snapshot - Now warns "⚠️ FIRST: Call logicstamp_watch_status" and lists when to skip this tool
    • logicstamp_list_bundles and logicstamp_read_bundle - Updated with unified workflow showing watch_status decision point
    • All tools now show the optimal flow: watch_status → (if active) list_bundles → read_bundle | (if inactive) refresh_snapshot → list_bundles → read_bundle
  • Documentation - Updated README with watch mode features and new tool reference

0.1.4 - 2026-01-14

Added

  • Comprehensive Test Coverage - Added 26 new tests significantly improving code coverage

    • Coverage Improvements: Overall coverage increased from ~78% to ~86% (statements, branches, lines)
    • Cache Cleanup Tests (10 tests) - Added tests for cache corruption detection, stale path detection, and cleanup logic
      • Tests for corrupted cache detection (invalid JSON in context_main.json)
      • Tests for stale cache detection (mismatched project paths in config files)
      • Tests for valid cache preservation and explicit cleanup
    • Parameter Validation Tests (7 tests) - Added comprehensive validation tests for depth parameter
      • Invalid depth values (non-integer, zero, negative)
      • Valid depth values (1, 3, default 2)
      • String-to-number conversion handling
    • Error Code Preservation Tests (4 tests) - Added tests ensuring error information is properly preserved
      • Error code preservation from exec errors
      • stdout/stderr preservation in error objects
      • ENOENT error handling for missing files
    • Server Error Handling Tests (4 tests) - Added tests for server-level error handling
      • Tool execution error wrapping in MCP format
      • Non-Error exception handling
      • Graceful error handling for all tools
    • Documentation Error Handling Tests (2 tests) - Added tests for error message structure and consistency
    • File Coverage Improvements:
      • compare-modes.ts: 60% → ~95% statements (+35%)
      • refresh-snapshot.ts: ~67% → ~96% statements (+29%)
    • Total test count: 163 → 189 tests (+26 tests)
    • All tests passing with improved confidence in error handling and edge cases

  • Enhanced Error Messages - Improved error messages throughout all MCP tools to be more actionable and helpful

    • All error messages now include context about what was attempted and why it failed
    • Added suggestions for common errors (e.g., "Run logicstamp_refresh_snapshot first" when snapshot is missing)
    • Included relevant file paths and next steps in error messages
    • Error messages now guide users toward solutions instead of just reporting failures
    • Enhanced messages in: logicstamp_refresh_snapshot, logicstamp_list_bundles, logicstamp_read_bundle, logicstamp_compare_snapshot, logicstamp_compare_modes, logicstamp_read_logicstamp_docs
    • Example improvement: "context_main.json not found" → "context_main.json not found in /path/to/project. This file is required for comparison but hasn't been generated yet. Options: (1) Run logicstamp_refresh_snapshot first to generate context files, (2) Use forceRegenerate: true in this call to regenerate automatically before comparing, (3) Run 'stamp context' manually from the project directory."

  • Code of Conduct - Added Contributor Covenant Code of Conduct to establish community standards and promote a respectful, inclusive environment

  • Roadmap - Added roadmap document outlining planned enhancements and future features to guide project development

Fixed

  • Version Consistency - Fixed version mismatches across codebase to ensure all version references match package.json
    • README.md - Updated version badge from 0.1.2 to 0.1.4
    • src/mcp/server.ts - Updated server version from 0.1.2 to 0.1.4 (was incorrectly 0.1.2 for version 0.1.3)
    • docs/mcp_integration.md - Updated example config version from 0.1.2 to 0.1.4
    • All version references now consistently match package.json version 0.1.4
    • Prevents confusion when users check version information across different sources

0.1.3 - 2026-01-13

Changed

  • Default Depth Parameter - Changed default dependency traversal depth from 1 to 2 across all tools
    • Default depth now includes nested components (e.g., App → Hero → Button) instead of only direct dependencies
    • Applies to logicstamp_refresh_snapshot, logicstamp_compare_snapshot, and all analysis profiles (llm-chat, llm-safe, ci-strict)
    • Ensures full component trees are captured by default, including contracts and styles for nested components
    • Set depth: 1 explicitly if you only need direct dependencies
    • Updated all documentation, tool descriptions, and examples to reflect the new default
    • This change ensures React projects with component hierarchies get complete dependency graphs without requiring explicit depth configuration

Fixed

  • logicstamp_read_bundle context_main.json Support - Fixed issue where reading context_main.json returned incomplete data
    • Now correctly detects and parses context_main.json as LogicStampIndex instead of LogicStampBundle[]
    • Returns full index content including summary, folders array, and all metadata
    • Updated output schema to support both bundle (for bundle files) and index (for context_main.json)
    • Updated documentation to clarify the difference between reading index files vs bundle files
    • Added test coverage for reading context_main.json

0.1.2 - 2025-12-30

Changed

  • Node.js Requirement Update - Updated minimum Node.js version requirement from >=18.0.0 to >=18.18.0 to align with logicstamp-context CLI requirements
    • Node 20+ is now recommended for best performance and features
    • Updated all documentation, prerequisites, and integration guides
    • Updated package.json engines field

Added

  • Depth Parameter Documentation - Added comprehensive recommendations for using depth: 2 with React/TypeScript projects
    • README.md - Added depth parameter guidance emphasizing depth: 2 recommendation for React projects (line 121)
      • Clarifies that LLM does NOT automatically detect when depth=2 is needed
      • Explains that default depth=1 only includes direct dependencies
    • docs/mcp_integration.md - Enhanced depth parameter documentation with React-specific recommendations (lines 76, 85)
      • Added RECOMMENDED guidance to start with depth: 2 for React/TypeScript projects
      • Included example usage: { "projectPath": "...", "depth": 2 }
      • Explained that depth=2 captures nested components (e.g., App → Hero → Button)
      • Added note that LLM must explicitly request depth=2 upfront
    • docs/logicstamp-for-llms.md - Added critical depth parameter guidance (lines 44, 158-179)
      • Added CRITICAL section recommending depth: 2 for React/TypeScript projects
      • Explained when depth=1 is insufficient (missing components, incomplete graphs)
      • Added example code showing recommended usage pattern
      • Clarified that LLM does NOT automatically detect when depth=2 is needed
    • docs/startup-ritual.md - Updated startup ritual with depth=2 recommendations (lines 12-14, 51-55)
      • Added RECOMMENDED guidance in startup workflow
      • Included examples and when to use depth=2
      • Explained difference between depth=1 (direct dependencies) and depth=2 (nested components)
    • src/mcp/server.ts - Enhanced tool descriptions with depth=2 recommendations (lines 61-63, 88)
      • Updated logicstamp_refresh_snapshot description to recommend depth=2 for React projects
      • Added guidance about nested component hierarchies
      • Clarified that depth=2 ensures nested components are included with contracts and styles

Fixed

  • Version Consistency - Fixed version mismatches across codebase to ensure all version references match package.json
    • README.md - Updated version badge from 0.1.1 to 0.1.2 (line 13)
      • Badge now correctly displays current package version
    • src/mcp/server.ts - Updated server version from 0.1.0 to 0.1.2 (line 30)
      • MCP server now reports correct version to clients
      • Fixes discrepancy where server reported older version than package
    • docs/mcp_integration.md - Updated example config version from 0.1.0 to 0.1.2 (line 852)
      • Example MCP server configuration now shows correct version
      • Ensures documentation examples match actual implementation
    • All version references now consistently match package.json version 0.1.2
    • Prevents confusion when users check version information across different sources

0.1.1 - 2025-12-14

Fixed

  • Documentation Fix - Corrected projectPath parameter documentation for logicstamp_refresh_snapshot
    • Updated docs to correctly mark projectPath as required (was incorrectly marked as optional)
    • Added explanation of why projectPath is required (prevents hangs when stamp init has been run)
    • Updated all examples to include projectPath parameter
    • Fixes issue where users following documentation would encounter errors when omitting projectPath

0.1.0 - 2025-12-13

Added

Core Features

  • MCP Server Implementation - Full Model Context Protocol server for LogicStamp Context
  • Snapshot Management - In-memory snapshot state management with automatic cleanup (1-hour TTL)
  • 7 MCP Tools - Complete tool suite for codebase analysis:
    • logicstamp_refresh_snapshot - Create snapshots of codebase state
    • logicstamp_list_bundles - List available component bundles
    • logicstamp_read_bundle - Read full component contracts and dependency graphs
    • logicstamp_compare_snapshot - Detect changes after edits (drift detection)
    • logicstamp_compare_modes - Generate token cost comparisons across modes
    • logicstamp_read_logicstamp_docs - Access LogicStamp documentation
    • logicstamp_watch_status - Check if watch mode is active

Analysis Capabilities

  • Component Contract Extraction - Extract props, state, hooks, and dependencies
  • Style Metadata Support - Extract Tailwind classes, SCSS modules, framer-motion animations, color palettes, layout patterns
  • Dependency Graph Analysis - Understand component relationships
  • Token Optimization - Configurable code inclusion modes (none/header/full)
  • Multiple Analysis Profiles - Support for llm-chat, llm-safe, and ci-strict profiles

Developer Experience

  • Comprehensive Documentation - README, quick start guide, integration guides, API reference
  • Integration Guides - Setup instructions for Claude CLI, Claude Desktop, and Cursor IDE
  • Example Configurations - .claude.json.example and .mcp.json.example files
  • TypeScript Support - Full type safety with comprehensive type definitions
  • Error Handling - Proper MCP error codes and descriptive error messages

Testing & Quality

  • Test Suite - 150 tests covering unit, integration, and E2E scenarios
  • CI/CD Pipeline - GitHub Actions workflow testing on Ubuntu, Windows, and macOS
  • Multi-Node Testing - CI tests on Node.js 18.x and 20.x
  • Type Checking - TypeScript compilation verification in CI

Documentation

  • Quick Start Guide - Get up and running in minutes
  • Startup Ritual - Recommended workflow for AI assistants
  • MCP Integration Guide - Complete API reference and architecture documentation
  • Tool Descriptions - Detailed documentation for each MCP tool
  • Troubleshooting Guide - Common issues and solutions
  • Contributing Guidelines - Guide for contributors
  • Security Policy - Security reporting and best practices

Configuration

  • Example Config Files - Ready-to-use configuration templates
  • Flexible Project Paths - Support for custom project paths
  • Baseline Comparison - Compare against disk or snapshot baselines
  • Smart Cache Cleanup - Automatic detection and cleanup of corrupted .logicstamp cache directories
    • Detects invalid JSON in context_main.json
    • Detects stale project paths in cache metadata files
    • Preserves cache when healthy for improved performance
  • forceRegenerate Parameter - Added to logicstamp_compare_snapshot tool
    • When false (default): Fast comparison using existing context_main.json from disk
    • When true: Regenerates context before comparing to ensure fresh data
  • cleanCache Parameter - Added to logicstamp_refresh_snapshot, logicstamp_compare_snapshot, and logicstamp_compare_modes tools
    • Manual override to force cache cleanup
    • Works alongside automatic corruption detection

Changed

  • Improved Error Handling - Better error messages for missing context_main.json files
    • Clear guidance when context files are missing
    • Suggests using forceRegenerate: true or running logicstamp_refresh_snapshot first
  • Enhanced logicstamp_compare_snapshot Tool - More flexible regeneration control
    • Independent control over regeneration (forceRegenerate) and style inclusion (includeStyle)
    • Better documentation of when each parameter takes effect

Fixed

  • Cache corruption issues that could cause analysis failures
  • Path mismatch detection for projects moved or renamed

Technical Details

  • Dependencies: @modelcontextprotocol/sdk@^1.24.0
  • Node.js Support: >=18.18.0 (Node 20+ recommended)
  • License: MIT
  • Read-Only Design: Server never modifies project files directly

Notes

  • This is the initial public release
  • Requires logicstamp-context CLI to be installed globally (npm install -g logicstamp-context)
  • All tools are read-only - they analyze but never modify your codebase