Project catalog database and shell integration

The Durable Project Catalog is a pragmatic system for discovering and cataloging software projects within deeply nested directory structures. It provides a reliable way to identify, organize, and manage software projects across complex file trees, prioritizing sustainability, clarity, and long-term maintainability.

In large codebases or extensive directory hierarchies, keeping track of individual software projects can be challenging. The Durable Project Catalog addresses this by implementing a set of clear, consistent rules for project identification and exclusion, ensuring that developers and teams can efficiently navigate and manage their software ecosystems.

A directory is considered a software project if it contains any of the following indicators:

• .git directory (Git repository)
• package.json (Node.js project)
• Gemfile (Ruby project)
• .gemspec (Ruby gem specification)
• Other common project markers (configurable)

The following directories are automatically excluded from project scanning:

• node_modules/ (Node.js dependencies)
• vendor/ (Ruby/vendor dependencies)
• Other common dependency directories (configurable)

• Deep Tree Scanning: Efficiently traverses deeply nested directory structures
• Configurable Rules: Customize project identification and exclusion criteria
• Modular Design: Composable components for flexibility and maintainability
• Performance Optimized: Fast scanning with minimal resource usage
• SQLite Database Storage: Persists project catalog data in a local SQLite database
• Terminal User Interface (TUI): Provides a TUI with fuzzy finder for quick directory access
• Clear Documentation: Comprehensive guides and examples
• Open Standards: Interoperable with existing tools and workflows

The system stores project catalog data in a SQLite database located at ~/.local/durable/durable-project-catalog. This ensures persistent storage of discovered projects and their metadata. The database tracks various "hints" indicating the type of project, such as the presence of:

• .git directory (Git repository)
• Cargo.toml (Rust project)
• package.json (Node.js project)
• devenv.nix (Nix development environment)
• And other configurable project indicators.

One-line installation for your platform:

Or download and run manually:

PowerShell (recommended):

Or with PATH modification:

Verify installation:

x86_64:

ARM64:

Static build (musl, no dependencies):

Intel Macs:

Apple Silicon (M1/M2/M3):

If you encounter Gatekeeper warnings:

x64: Download dpc-windows-x86_64.exe

ARM64: Download dpc-windows-aarch64.exe

Installation steps:

1. Create folder: C:\Tools\dpc
2. Move downloaded file to C:\Tools\dpc\dpc.exe
3. Add to PATH:
   • Open System Properties (Win + Pause)
   • Click "Environment Variables"
   • Under "User variables", select "Path"
   • Click "Edit" → "New"
   • Add: C:\Tools\dpc
   • Click OK and restart terminal

Prerequisites:

• Rust toolchain (1.70 or later)
• SQLite3 development libraries

See Docker documentation for detailed usage.

For development or customization:

Development with devenv:

The Durable Project Catalog includes powerful shell integration for quick navigation to cataloged projects, similar to tools like zoxide or autojump.

1. First, scan your directories to populate the project catalog:

   dpc scan ~/projects ~/work

2. Generate the shell integration script for your shell:

   For Bash:

   # Add to ~/.bashrc eval "$(dpc shell init bash)"

   For Zsh:

   # Add to ~/.zshrc eval "$(dpc shell init zsh)"

   For Fish:

   # Add to ~/.config/fish/config.fish dpc shell init fish | source

3. Reload your shell configuration:

   # Bash source ~/.bashrc # Zsh source ~/.zshrc # Fish source ~/.config/fish/config.fish

Once installed, you have access to these commands:

• j <pattern> - Jump to a project matching the pattern

  j myproject # Jump to project containing "myproject" j durable/catalog # Jump to project matching path pattern

• ji - Interactive project selector (launches TUI)

  ji # Opens fuzzy finder to select and navigate to a project

• dpc-cd <pattern> - Explicit version of the j command

  dpc-cd webapp # Same as 'j webapp'

The shell integration automatically tracks your directory access patterns using a "frecency" algorithm (frequency + recency). This means:

• Projects you visit often appear higher in search results
• Recently accessed projects are prioritized
• The ranking improves over time as you use the tool

For Zsh and Fish, automatic tracking is enabled via shell hooks. For Bash, tracking happens when you use the j command.

Create a config.yaml file to customize scanning behavior:

We welcome contributions that align with our philosophy of pragmatic, sustainable software development. Please see our Contributing Guide for details.

This project uses devenv for development environment management. To get started:

Linux: Permission Denied

macOS: "dpc cannot be opened because the developer cannot be verified"

Windows: "dpc is not recognized as an internal or external command" Ensure the installation directory is in your PATH (see Windows installation instructions above).

Database Errors

Performance Issues For large directory trees, consider:

• Excluding unnecessary directories
• Adjusting max_depth in configuration
• Using the --exclude flag

To update to the latest version:

Standalone Binary:

Cargo:

Docker:

Dual-licensed under MIT OR Apache-2.0

For questions, issues, or contributions, please:

• Open an issue on GitHub
• Check our documentation
• Contact our support team

Built with a focus on durability, clarity, and practical value.