feat: implement Git-style node references and progressive IDs

[bwl]

Inspired by Git's approach to commit hashes, Forest now uses progressive abbreviation for node IDs and supports multiple reference patterns for maximum flexibility and ergonomics.

Key Features

1. Progressive Abbreviation (Git-style)

• Display: Shows shortest unique prefix (4-7 chars typically)
• Acceptance: Any length prefix works (4, 8, 12, or full UUID)
• Backward compatible: All existing 8-char IDs continue working
• Auto-expanding: Prefixes grow as needed to avoid collisions

2. Multiple Reference Types

• UUID prefixes: 7fa7acb2 (case-insensitive, works with/without dashes)
• Recency refs: @ (last updated), @1 (second last), @2, etc.
• Tag search: #typescript (finds node tagged 'typescript')
• Title search: "API design" (substring match in titles)

3. Rich Disambiguation

• Shows all matches with context (ID, title, date)
• Sorted by recency
• Clear actionable guidance
• Inspired by Git's "short SHA is ambiguous" messages

4. Case-Insensitive Matching

• All ID resolution is case-insensitive
• Works with or without UUID dashes
• Matches Git's SHA behavior

5. Shell Tab Completion

• Bash completion script (completions/forest.bash)
• Zsh completion script (completions/forest.zsh)
• Supports commands, flags, and recency references (@, @1, etc.)

Implementation

Core Changes:

• src/lib/progressive-id.ts: Added node ID progressive abbreviation

  • normalizeNodeId(): Remove dashes, lowercase UUIDs
  • getNodePrefix(): Compute minimal unique prefix
  • buildNodePrefixMap(): Bulk prefix computation
  • Case-insensitive findHashesByPrefix()

• src/cli/shared/utils.ts: Unified reference resolution

  • formatNodeIdProgressive(): Display minimal prefixes
  • resolveNodeReference(): Unified resolver for all patterns
  • resolveRecencyReference(): Handle @, @1, @2, etc.
  • resolveByIdPrefix(): Rich disambiguation UI

• src/cli/shared/explore.ts: Progressive display

  • Updated printNodeOverview() to use progressive IDs
  • Updated printMatches() to use progressive IDs
  • Made functions async to fetch node list for prefix computation

• src/cli/commands/search.ts: Progressive display + --longIds flag

  • Added --longIds flag for full UUIDs
  • Updated printTextResults() to use progressive IDs

Documentation:

• CLAUDE.md: New "Git-Style Node References" section

  • Display vs. Acceptance explanation
  • Reference types with examples
  • Disambiguation behavior
  • Backward compatibility guarantees
  • Tab completion instructions

• GIT_STYLE_REFERENCES.md: Comprehensive feature guide

  • Philosophy and principles learned from Git
  • Implementation details
  • Testing approach
  • Migration guide
  • Future enhancements

Shell Completion:

• completions/forest.bash: Bash completion support
• completions/forest.zsh: Zsh completion support
• completions/README.md: Installation instructions

Testing

All progressive ID functions validated:
✅ normalizeNodeId removes dashes and lowercases
✅ Unique IDs get minimal 4-char prefixes
✅ Colliding prefixes auto-expand to 5+ chars
✅ Case-insensitive matching works
✅ Backward compatibility - 8-char prefixes still resolve

Backward Compatibility

Zero breaking changes:

• All existing 8-char references continue working
• Full UUIDs continue working
• External docs/scripts/bookmarks unaffected
• API responses can use any length (8 chars or full UUID recommended)

Benefits

1. Screen space - Shows 4-7 chars instead of 8
2. Typing efficiency - Type less to reference nodes
3. Mental models - Multiple ways to reference nodes (@, #tag, "title")
4. Git familiarity - Developers already know this UX
5. Scalability - Auto-adjusts to graph size
6. Rich errors - Helpful disambiguation with context

🤖 Generated with Claude Code