MVP 1A by flyingrobots · Pull Request #2 · flyingrobots/git-mind

flyingrobots · 2025-06-12T11:28:19Z

Summary

This PR completes the Phase 1a Minimal Viable Product (MVP) for gitmind, implementing all five essential commands needed for a functional Git-based knowledge graph.

The implementation follows Test-Driven Development (TDD) principles and introduces a robust CommandResult<T> pattern that eliminates brittle stdout/stderr testing.

What's Included

Core Commands (5/5 Complete)

✅ gitmind init - Initialize knowledge graph in Git repository
✅ gitmind link - Create semantic links between files
✅ gitmind list - View and filter existing links
✅ gitmind unlink - Remove specific links with flexible options
✅ gitmind check - Find and optionally fix broken links

Key Features

Link Storage: Human-readable format in .gitmind/links/ directory
SHA-based Deduplication: Content-addressed storage prevents duplicates
Git Integration: All operations tracked with semantic commit messages
Link Types: Support for CROSS_REF, DEPENDS_ON, IMPLEMENTS, etc.
Link Hygiene: Full support for removing and validating links
Robust Testing: 100% behavior-driven tests, no stdout/stderr testing

Technical Highlights

Architecture Improvements

Introduced CommandResult<T> pattern for clean error handling
Modular command structure with single responsibility principle
Dependency injection ready design for future enhancements
Exit codes with semantic meaning (0=success, 2=NotAGitRepo, 3=NotInitialized, etc.)

Testing Strategy

Unit Tests: Test individual components in isolation
Integration Tests: Test commands working together
End-to-End Tests: Test complete user workflows
All tests use real Git repos in temporary directories
Zero stdout/stderr testing - tests verify behavior, not output (Claude is a naughty boy)

Link Format

LINK_TYPE: source -> target  # ts:timestamp

Example:

CROSS_REF: notes/idea.md -> specs/refactor.md  # ts:1736637876

Changes Overview

27 files changed, 3,202 insertions(+), 33 deletions(-)
25 commits implementing features incrementally with TDD
Complete test coverage for all commands
Comprehensive documentation updates

Testing

All tests pass in Docker environment:

make test  # Runs format check, clippy, and full test suite

Breaking Changes

None - this is the initial implementation.

Documentation

Updated CLAUDE.md with testing principles and CommandResult pattern
Added F016 Link Hygiene feature specification
Created comprehensive developer journal in lore/CLAUDE_DEV_THOUGHTS.md
Updated TASKLIST.md to reflect completed Phase 1a

Closes

Implements F001 (Git Object Storage)
Implements F013 (CLI Tools)
Implements F016 (Link Hygiene)
Completes Phase 1a MVP milestone

- Set up Rust CLI structure with clap framework - Add integration tests for init command behavior - Implement init to create .gitmind/links/ directory - Check for git repository existence before init - Handle already initialized case - All tests run in isolated temporary directories Tests pass: init creates directory structure and fails appropriately when not in a git repo or already initialized.

- Add git commit format instructions to CLAUDE.md - Mark CLI structure setup as complete in TASKLIST.md - Mark init command implementation as complete - Update Phase 1a progress indicators

- Add F001 requirements: metadata support, bidirectional lookups, deduplication - Add F002 extraction patterns: all Markdown link types, metadata capture - Add F002 performance requirements: <1s for 100 files, <100MB memory - Add F013 CLI features: query languages, time travel, import/export - Add shell integration: git aliases, completions, REPL mode - Add developer tools: pipeline integration, JSON output, batch mode - Add configuration management and optimization commands TASKLIST now comprehensively reflects all requirements from design/features/ ensuring nothing is missed during implementation.

- Link TASKLIST.md items to corresponding feature docs - Create ADR-001 documenting Option B storage choice - Update F001 status to 'In Progress' with completion checklist - Update F013 status to 'In Progress' with CLI progress - Add feature references throughout TASKLIST phases Following new practice: document decisions in design/decisions and update feature status as implementation progresses.

- Add .obsidian/ to ignore Obsidian workspace settings - Keep CLAUDE.md tracked for shared AI assistant instructions - Obsidian settings remain local to each developer

- Add git commit format instructions for better collaboration - Specify to suggest commits after completing TASKLIST items - Add reminder to keep TASKLIST.md up-to-date - Include requirement to document decisions in design/decisions/ - Add instruction to update feature status upon completion These practices ensure consistent documentation and commit history across all contributors and AI assistants.

- Always test behavior, not implementation - One file = one thing (struct/enum/trait) - One test file per component - Single Responsibility Principle for modules

- Set COMPOSE_BAKE=true in docker-build target - Improves build performance through better parallelization

- Add commands/mod.rs to organize command modules - Add commands/init.rs with InitCommand implementation - Add commands/link.rs with LinkCommand implementation - Each command has single responsibility with execute() method

- Move Link representation to link.rs - Add canonical string format methods - Add SHA calculation methods - Add parsing from canonical string - Include unit tests for Link behavior

- Remove inline command logic from lib.rs - Delegate init() to InitCommand - Delegate link() to LinkCommand - Maintain clean API surface

reorganize tests by component responsibility - Create init_command.rs for init behavior tests - Create link_command.rs for link behavior tests - Remove monolithic cli_integration.rs - Each test file focuses on one component's behavior

- Update TASKLIST.md to show link command implementation done - Update F013 feature status for link command - Ready to implement list command next

- Lessons learned from single responsibility refactor - Benefits of component-specific test files - Command pattern observations - Docker Bake performance improvements

dependencies - Add sha1 and chrono dependencies for link content hashing - Add error types for link command validation - Add --type flag to link command with CROSS_REF default - Wire up link command in main.rs with error handling

Adds the ability to list all semantic links in the repository with filtering: - List all links: gitmind list - Filter by source: gitmind list --source file.md - Filter by target: gitmind list --target file.md Shows link type, source, target, and timestamp for each link.

Adds tests and other things I forgot to include in the last commit. My bad.

Adds the ability to remove semantic links between files: - Remove specific link: gitmind unlink source target - Remove by type: gitmind unlink source target --type - Remove all from source: gitmind unlink source --all - Remove all to target: gitmind unlink --to target Includes link parsing from canonical string format.

Git removes empty directories, which was causing 'gitmind not initialized' errors after removing all links. Now, we create a .gitkeep file during inint.

Documents the need for link cleanup and broken link management. Defines unlink and check commands for maintaining graph integrity.

- Add three-level testing strategy to CLAUDE.md - Define 'Definition of Done' tied to acceptance critieria - Update F013 progress with completed commands

Add unlink and check commands to Phase 1a MVP based on realization that link cleanup is essential for a viable product.

Captures the realization that forgetting is as vital as remembering in cognitive systems, leading to inclusion of hygiene commands in MVP.

- Introduce CommandResult<T> type with exit codes and optional values - Refactor all App methods to return CommandResult instead of Result - Update all tests to use App API directly instead of spawning processes - Tests now verify behavior through exit codes and return values - Fix bug where duplicate links returned success instead of error - Add Debug and PartialEq derives to Link struct for testability This eliminates brittle stdout/stderr string matching in tests, making them more maintainable and focused on behavior rather than implementation details.

- Implement check command to find and fix broken links - Add --fix flag to remove broken links automatically - Add --dry-run flag to preview what would be fixed - Support detection of missing source or target files - Auto-commit removed links with semantic message - Add Clone derive to Link struct for check implementation - Update TASKLIST.md to mark Phase 1a as complete This completes the MVP with all five essential commands: init, link, list, unlink, and check. The knowledge graph now has full link hygiene capabilities."

- Replace map_or with is_none_or to fix clippy unnecessary-map-or warnings - Update Dockerfile.dev from Rust 1.78 to latest for compatibility with CI - Ensures tests pass on GitHub Actions which uses Rust 1.87

flyingrobots added 27 commits June 12, 2025 01:58

docs: update CLAUDE.md and TASKLIST.md for completed init command

21fc9cf

- Add git commit format instructions to CLAUDE.md - Mark CLI structure setup as complete in TASKLIST.md - Mark init command implementation as complete - Update Phase 1a progress indicators

chore: gitignore .obsidian directory

876573c

- Add .obsidian/ to ignore Obsidian workspace settings - Keep CLAUDE.md tracked for shared AI assistant instructions - Obsidian settings remain local to each developer

docs: add testing and code organization principles to CLAUDE.md

9cbe1b2

- Always test behavior, not implementation - One file = one thing (struct/enum/trait) - One test file per component - Single Responsibility Principle for modules

build: enable Docker Bake for parallel builds

599530e

- Set COMPOSE_BAKE=true in docker-build target - Improves build performance through better parallelization

refactor(cli): create modular command structure

00783ee

- Add commands/mod.rs to organize command modules - Add commands/init.rs with InitCommand implementation - Add commands/link.rs with LinkCommand implementation - Each command has single responsibility with execute() method

refactor(cli): extract Link struct to dedicated module

45652fd

- Move Link representation to link.rs - Add canonical string format methods - Add SHA calculation methods - Add parsing from canonical string - Include unit tests for Link behavior

refactor(cli): update App to delegate to command modules

b413b60

- Remove inline command logic from lib.rs - Delegate init() to InitCommand - Delegate link() to LinkCommand - Maintain clean API surface

test:

dafe22f

reorganize tests by component responsibility - Create init_command.rs for init behavior tests - Create link_command.rs for link behavior tests - Remove monolithic cli_integration.rs - Each test file focuses on one component's behavior

docs: mark link command as completed

10f2d85

- Update TASKLIST.md to show link command implementation done - Update F013 feature status for link command - Ready to implement list command next

docs: document refactoring insights in dev journal

e139f46

- Lessons learned from single responsibility refactor - Benefits of component-specific test files - Command pattern observations - Docker Bake performance improvements

feat(cli): add link command CLI interface and

c415b56

dependencies - Add sha1 and chrono dependencies for link content hashing - Add error types for link command validation - Add --type flag to link command with CROSS_REF default - Wire up link command in main.rs with error handling

feat(F013): implement gitmind list command (part 2)

738f1dc

Adds tests and other things I forgot to include in the last commit. My bad.

fix: add .gitkeep to prevent .gitmind directory removal

027cb33

Git removes empty directories, which was causing 'gitmind not initialized' errors after removing all links. Now, we create a .gitkeep file during inint.

docs: add F016 link hygiene feature spec

06df5a5

Documents the need for link cleanup and broken link management. Defines unlink and check commands for maintaining graph integrity.

docs: update testing strategy and implementation progress

4c1270e

- Add three-level testing strategy to CLAUDE.md - Define 'Definition of Done' tied to acceptance critieria - Update F013 progress with completed commands

chore: update TASKLIST with link hygiene commands

dff70fb

Add unlink and check commands to Phase 1a MVP based on realization that link cleanup is essential for a viable product.

docs: add session notes on link hygiene design

53d6087

Captures the realization that forgetting is as vital as remembering in cognitive systems, leading to inclusion of hygiene commands in MVP.

fix(cli): resolve clippy warnings and update Rust version

e33d78b

- Replace map_or with is_none_or to fix clippy unnecessary-map-or warnings - Update Dockerfile.dev from Rust 1.78 to latest for compatibility with CI - Ensures tests pass on GitHub Actions which uses Rust 1.87

Merge remote-tracking branch 'origin/main' into fix-github-actions

6545dc8

flyingrobots merged commit e47dd8b into main Jun 12, 2025

flyingrobots deleted the fix-github-actions branch June 12, 2025 11:38

Navigation Menu

Repository navigation

MVP 1A - #2

MVP 1A#2
flyingrobots merged 27 commits into
mainfrom
fix-github-actions

flyingrobots commented Jun 12, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

flyingrobots commented Jun 12, 2025

Summary

What's Included

Core Commands (5/5 Complete)

Key Features

Technical Highlights

Architecture Improvements

Testing Strategy

Link Format

Changes Overview

Testing

Breaking Changes

Documentation

Closes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant