Dotfiles
C 62 completed
Cli Tool
unknown / json · small
85
Files
3,193
LOC
0
Frameworks
6
Languages
Pipeline State
completedRun ID
#407155Phase
doneProgress
1%Started
Finished
2026-04-13 01:31:02LLM tokens
0Pipeline Metadata
Stage
SkippedDecision
skip_scaffold_dupNovelty
18.30Framework unique
—Isolation
—Last stage change
2026-04-16 18:15:42Deduplication group #47302
Member of a group with 3,095 similar repo(s) — canonical #186014 view group →
Top concepts (5)
Architecture DescriptionConfigurationFile ManagementTestingUser Management
Repobility · code-quality intelligence platform · https://repobility.com
AI Prompt
Create a comprehensive dotfiles management system using a structure that supports multiple shells and tools. I need it to handle configurations for Fish shell, Starship, TMUX, Neovim, and various development CLIs like Claude, Gemini, and Codex. The setup should include an `install.sh` script to manage the installation process, and it should use `just` commands to allow users to easily install, check, or restore backups for individual components. Please structure the repository to manage symlinks and configurations for these tools.
dotfiles shell bash fish tmux neovim configuration scripting macos linux
Generated by gemma4:latest
Catalog Information
Create a comprehensive dotfiles management system using a structure that supports multiple shells and tools. I need it to handle configurations for Fish shell, Starship, TMUX, Neovim, and various development CLIs like Claude, Gemini, and Codex. The setup should include an install.sh script to manage the installation process, and it should use just commands to allow users to easily install, check, or restore backups for individual components. Please structure the repository to manage symlinks
Tags
dotfiles shell bash fish tmux neovim configuration scripting macos linux
Quality Score
C
62.1/100
Structure
43
Code Quality
94
Documentation
55
Testing
0
Practices
78
Security
100
Dependencies
50
Strengths
- Consistent naming conventions (snake_case)
- Low average code complexity — well-structured code
- Good security practices — no major issues detected
Weaknesses
- No LICENSE file — legal ambiguity for contributors
- No tests found — high risk of regressions
- No CI/CD configuration — manual testing and deployment
Recommendations
- Add a test suite — start with critical path integration tests
- Set up CI/CD (GitHub Actions recommended) to automate testing and deployment
- Add a linter configuration to enforce code style consistency
- Add a LICENSE file (MIT recommended for open source)
Security & Health
11.1h
Tech Debt (D)
High
DORA Rating
A
OWASP (100%)
PASS
Quality Gate
Open data scored by Repobility · https://repobility.com
6.1%
Duplication
Languages
Frameworks
None detected
Concepts (5)
| Category | Name | Description | Confidence | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Repobility's GitHub App fixes findings like these · https://github.com/apps/repobility-bot | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ai_architecture | Architecture Description | # Architecture Overview: miltonparedes__dotfiles ## 1. Executive Summary This repository is not a traditional application but rather a collection of configuration files, scripts, and templates designed to manage and synchronize a user's entire development environment across various operating systems and applications. It serves a single user (the owner) by providing a highly customized, reproducible "dotfiles" setup. The primary architecture style is **Configuration Management** combined with **Procedural Scripting**. Its maturity level is high for a personal setup, demonstrating deep customization but low for general reusability. A key strength is its comprehensive nature, covering shell environments (Fish, Zsh/Bash via dotfiles), editors (Neovim), and tooling (LazyGit, Starship). A key risk is the extreme coupling to the owner's specific workflow and the lack of formal dependency management for the configurations themselves. ## 2. System Architecture Diagram The system architecture is highly decentralized, relying on the execution of scripts (`install.sh`, `Justfile`) to populate various configuration directories (`home/`, `nvim/`). The flow is primarily sequential execution followed by application initialization. ```mermaid graph TD A[User Execution: install.sh / Justfile] --> B{Setup Scripts}; B --> C[Shell Configs: .bashrc, .zshrc, fish]; B --> D[Editor Configs: nvim/init.lua]; B --> E[Tooling Configs: starship.toml, lazygit/]; B --> F[System Templates: .chezmoi.toml.tmpl]; C --> G(Shell Environment); D --> H(Neovim Editor); E --> I(CLI Tools); F --> J(Dotfiles Source of Truth); G --> K[User Shell Session]; H --> K; I --> K; subgraph Configuration Sources J C D E end K --> L(Running Applications); ``` ## 3. Architectural Layers Given that this repository is a collection of configuration artifacts rather than a compiled application, traditional layered architecture models (like N-Tier) do not strictly apply. Instead, we analyze it based on **Concern/Scope**. ### Presentation Layer (User Interaction) - **Responsibility**: Defining the user experience across various terminals and applications. This includes shell prompts, keybindings, and editor settings. - **Key files/directories**: `home/`, `nvim/`, `dot_tmux.conf`, `starship.toml`. - **Boundary enforcement**: Weak. The "presentation" is achieved by placing files in specific locations that applications *expect* to find them (e.g., `~/.config/nvim/init.lua`). - **Dependencies**: Depends on the underlying shell (Fish, Zsh) and the target application (Neovim). ### Application/Service Layer (Automation & Setup) - **Responsibility**: Orchestrating the setup, installation, and modification of the environment. This layer contains the logic to make the configuration persistent. - **Key files/directories**: `install.sh`, `Justfile`, `devcontainers/install.sh`, `run_onchange_after_*.sh`. - **Boundary enforcement**: Moderate. The scripts enforce a sequence of operations, but they are procedural rather than encapsulated services. - **Dependencies**: Depends on the operating system's package manager (implied by `brewfile`) and the shell environment itself. ### Domain Layer (Core Configuration Artifacts) - **Responsibility**: Storing the actual, desired state of the user's settings for specific tools. This is the "source of truth" for configurations. - **Key files/directories**: `home/.chezmoi.toml.tmpl`, `nvim/lua/`, `dot_codex/`, `dot_config/`. - **Boundary enforcement**: Strong (within the context of dotfiles). Each subdirectory represents a distinct, self-contained domain configuration (e.g., `dot_config/fish/`, `nvim/lua/`). - **Dependencies**: Minimal; components within this layer are generally independent, relying only on the structure defined by the tool they configure. ### Infrastructure Layer (System Integration) - **Responsibility**: Handling system-level concerns like package management, environment variable setup, and initial bootstrapping. - **Key files/directories**: `cli.Brewfile`, `devcontainers/`, `Justfile`. - **Boundary enforcement**: Moderate. These files interact directly with the host OS/shell environment. - **Dependencies**: Depends heavily on external tools like Homebrew, Chezmoi, and the host OS shell. ## 4. Component Catalog ### Component: `install.sh` / `Justfile` - **Location**: Root directory - **Responsibility**: The primary entry point for setting up the entire environment. It orchestrates the execution of setup scripts and ensures necessary prerequisites are met. - **Public interface**: Execution (runs setup logic). - **Dependencies**: Relies on the existence and correct execution order of other scripts (e.g., `devcontainers/install.sh`). - **Dependents**: None (It is the root process). ### Component: `home/` Directory Structure (Chezmoi Integration) - **Location**: `home/` - **Responsibility**: Acts as the primary template repository for dotfiles managed by Chezmoi. It contains templates (`.tmpl`) and data files (`.yaml`, `.json`). - **Public interface**: Template rendering and data provision. - **Dependencies**: Depends on the `chezmoi` tool being installed and configured. - **Dependents**: The system shell upon initialization. ### Component: Neovim Configuration (`nvim/`) - **Location**: `nvim/` - **Responsibility**: Defines the entire editor experience, including keymaps, plugin management, and core options. - **Public interface**: `init.lua` (the main entry point). - **Dependencies**: Depends on Lua scripting capabilities and the `lazy.nvim` plugin manager structure. - **Dependents**: The Neovim editor itself. ### Component: Shell Configuration (e.g., `home/dot_config/fish/`) - **Location**: `home/dot_config/` - **Responsibility**: Providing shell-specific customizations (e.g., `config.fish.tmpl`, `functions/`). - **Public interface**: Template files that are sourced by the shell startup files. - **Dependencies**: Depends on the specific shell (Fish, Zsh, etc.) being active. - **Dependents**: The user's active shell session. ### Component: `devcontainers/` Scripts - **Location**: `devcontainers/` - **Responsibility**: Managing environment setup specific to development containers (e.g., VS Code Dev Containers). - **Public interface**: `install.sh`, `packages.sh`. - **Dependencies**: Depends on containerization tooling (Docker/Podman) and shell scripting. - **Dependents**: The development workflow initiated by the user. ## 5. Component Interactions Communication is overwhelmingly **Procedural/Sequential** (script execution) or **Configuration Injection** (template rendering). There are no observed asynchronous message queues or explicit API calls between major components. The most important flow is the **Initial Environment Setup**. ```mermaid sequenceDiagram actor User participant Installer as install.sh / Justfile participant Chezmoi as Chezmoi Engine participant Shell as Shell Startup (e.g., fish) participant Editor as Neovim User->>Installer: Execute Setup Script Installer->>Chezmoi: Process Templates (.tmpl) Chezmoi->>Chezmoi: Render Files to Target Location Chezmoi->>Shell: Write/Update Shell Configs (e.g., ~/.config/fish/config.fish) Shell->>Shell: Source Configs (Initialization) Shell->>Editor: Set Environment Variables Editor->>Editor: Load init.lua (Reads from ~/.config/nvim) Editor->>Editor: Initialize Plugins (lazy.nvim) ``` ## 6. Data Flow The data flow is highly directional and primarily involves **Template Rendering** and **File Overwriting/Creation**. - **Input sources**: 1. **Source Templates**: Files ending in `.tmpl` (e.g., `home/.chezmoi.toml.tmpl`, `dot_config/fish/config.fish.tmpl`). 2. **Data Context**: Data files (e.g., `home/.chezmoidata.yaml`, `dot_codex/create_config.toml`). 3. **Execution Context**: Environment variables and arguments passed to `install.sh`. - **Transformation steps**: 1. **Templating**: The `chezmoi` tool (or similar logic within scripts) reads the template and substitutes placeholders (e.g., `{{ .Username }}`) using the provided context data. 2. **Script Execution**: Shell scripts execute logic (e.g., `executable_tmux-border.sh`) which performs actions like creating directories or writing specific commands. - **Storage mechanisms**: 1. **Target Dotfiles**: The final, rendered configuration files placed in the user's home directory (e.g., `~/.config/nvim/init.lua`). 2. **State Files**: JSON/YAML files used by specific tools (e.g., `nvim/lazy-lock.json`, `home/.chezmoidata.yaml`). - **Output destinations**: 1. The active shell session (via sourcing). 2. The Neovim editor instance. 3. The operating system filesystem (for persistent configuration). ## 7. Technology Decisions & Rationale | Technology | Choice | Likely Rationale | Alternatives | Risks | | :--- | :--- | :--- | :--- | :--- | | **Configuration Management** | Chezmoi (Implied) | Provides robust, cross-platform templating and secret management for dotfiles. | Ansible, SaltStack, dedicated Git hooks. | Over-reliance on a single tool for state management; complexity if templates become too complex. | | **Shell Scripting** | Bash/Shell Scripts (`.sh`) | Universal compatibility for system setup and execution logic. | Python, Rust. | Poor error handling, difficult to manage state across multiple scripts, lack of strong typing. | | **Editor Configuration** | Lua (Neovim) | Lua is idiomatic for Neovim configuration and offers a balance of power and readability. | Vimscript, Python. | Lua syntax can be niche; requires the user to maintain Lua knowledge for the editor. | | **Data Serialization** | YAML, JSON, TOML | Standard, human-readable formats for configuration data. | INI files, specialized database formats. | Schema validation is manual; inconsistencies in structure can break rendering. | | **Package Management** | Homebrew (Implied by `cli.Brewfile`) | Standard, widely adopted package manager on macOS/Linux for developer tools. | `apt`/`dnf` (OS native), `conda`. | Vendor lock-in to Homebrew ecosystem; requires manual adaptation if switching OS base. | ## 8. Scalability Considerations This repository is fundamentally **non-scalable** in the traditional sense because it is designed for a single user's local machine state. - **Current bottlenecks**: The primary bottleneck is the **initial setup time** and the **complexity of the setup scripts** (`install.sh`). As more tools are added, the setup script becomes a monolithic, hard-to-debug sequence. - **Horizontal vs vertical scaling**: Not applicable. It is a single-user configuration artifact. - **Stateful vs stateless components**: The *system* is stateful (it modifies the user's home directory), but the *components* (the templates) are designed to be stateless, relying on the rendering engine to provide the current state. - **Caching strategy**: No explicit caching strategy is visible. The reliance on Chezmoi implies some level of internal state tracking, but the user must manually manage cache invalidation if templates change unexpectedly. ## 9. Security Considerations The security posture is **High Risk** due to the nature of executing arbitrary scripts and configuration files that write to the user's root directory. - **Authentication/authorization mechanisms**: None visible. The system assumes the user running `install.sh` has full root/user write access to their home directory. - **Input validation practices**: Minimal. Scripts execute commands based on template content or hardcoded logic. If a template were compromised, it could execute arbitrary shell commands. - **Secret management**: Secrets are managed via templates (e.g., `{{ .SecretKey }}`), implying the use of a secret vault mechanism (like Chezmoi's built-in encryption), which is a strength. However, the *mechanism* for injecting these secrets must be rigorously audited. - **Known security risks from code inspection**: 1. **Arbitrary Code Execution**: Any script executed by `install.sh` runs with the permissions of the caller. 2. **Template Injection**: If a template source is untrusted, it can lead to command injection via shell interpolation. ## 10. Testing Strategy Assessment - **Test types present**: None explicitly visible. The repository contains setup scripts, not test suites. - **Test framework(s)**: None. - **Estimated coverage level**: 0.0 (for functional testing). - **Testing gaps**: Critical gap. There is no mechanism to verify that the *resulting* configuration files are valid or that the setup process completes without side effects. Unit testing the *logic* within the scripts (e.g., validating a function in `functions/`) would be necessary, but integration testing (running the whole setup) is required but non-existent. ## 11. Technical Debt Assessment | Category | Description | Severity | Effort to Fix | | :--- | :--- | :--- | :--- | | **Procedural Coupling** | The entire setup relies on a linear, sequential execution flow (`install.sh` $\rightarrow$ `Justfile` $\rightarrow$ Scripts). Changes in one script can have cascading, undocumented failures. | High | Medium | | **Lack of Testability** | No unit or integration tests exist for the setup logic or the configuration templates. | High | High | | **Implicit Dependencies** | Dependencies are inferred (e.g., "This requires Neovim v0.9+," "This requires Fish shell"). These are not documented in a formal dependency manifest. | Medium | Low | | **Configuration Sprawl** | Configurations are spread across multiple, semi-independent directories (`dot_config/`, `nvim/`, `home/`). A single tool's configuration might need updates in three different places. | Medium | Medium | ## 12. Recommendations for Improvement 1. **Implement Configuration Validation Layer (Highest Priority)**: Introduce a dedicated validation step *after* the configuration is rendered but *before* the user session starts. This could involve running a linter/schema validator against the generated files (e.g., using a JSON Schema validator for `settings.json` files) to catch structural errors early. *Rationale: Addresses the critical lack of testing and validation.* 2. **Modularize Setup Logic (High Priority)**: Refactor `install.sh` and `Justfile` to use a plugin/module loading pattern instead of sequential execution. Each major component (e.g., "Setup Neovim," "Setup Fish") should be a self-contained, idempotent function/module that can be run independently. *Rationale: Reduces procedural coupling and improves debugging.* 3. **Formalize Dependency Manifest**: Create a top-level `requirements.yaml` or `dependencies.toml` file that explicitly lists required versions for external tools (e.g., `nvim >= 0.9.0`, `fish >= 3.5.0`, `chezmoi >= 0.4.0`). This moves implicit knowledge into an explicit contract. *Rationale: Improves reproducibility and auditability.* 4. **Isolate Template Rendering Context**: For complex templates, consider passing a structured context object rather than relying on global environment variables, making the template rendering process more predictable and testable. *Rationale: Improves robustness against environment variable pollution.* | 85% | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| business_logic | Configuration | Detected from 53 related files | 50% | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| business_logic | File Management | Detected from 2 related files | 50% | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| business_logic | Testing | Detected from 2 related files | 50% | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| business_logic | User Management | Detected from 3 related files | 50% | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Embed Badge
Add to your README:
