[Cleanup]: Consolidate samoyed and samoyed-hook binaries into unified command architecture

[behrangsa]

Summary

Consolidate the current dual-binary architecture (samoyed + samoyed-hook) into a single binary with subcommands (samoyed init + samoyed hook), preserving essential architectural boundaries through the Command Pattern while achieving deployment simplicity and conceptual unity.

Type of Technical Debt

🏗️ Architecture - Architectural improvements or simplification

Problem Description

Current issues:

• Code Duplication: Both binaries share substantial infrastructure (environment abstractions, logging, dependency injection patterns)
• Deployment Complexity: Two binaries must be distributed, versioned, and maintained in lockstep
• Conceptual Fragmentation: Users must understand two distinct execution contexts and binary deployment
• Maintenance Overhead: Separate binaries require coordinated testing, versioning, and release processes

Why it's problematic:

• Violates DRY principle with duplicated environment abstraction code
• Increases cognitive load for both developers and users
• Complicates distribution and packaging workflows
• Creates unnecessary conceptual boundaries where logical unity would be clearer

Proposed Solution

Cleanup approach:

• Step 1: Extend src/main.rs to accept a new Hook subcommand alongside the existing Init subcommand
• Step 2: Move hook_runner.rs logic into a new hook submodule/command handler within the main binary
• Step 3: Update hook file generation to call samoyed hook instead of samoyed-hook
• Step 4: Consolidate shared infrastructure (environment traits, logging) into single implementation
• Step 5: Update Cargo.toml to build single binary instead of dual binaries
• Step 6: Update tests to work with unified command structure
• Final state: Single samoyed binary that handles both samoyed init and samoyed hook subcommands

Justification

Benefits of cleanup:

• Reduced Complexity: Single binary eliminates deployment and versioning coordination overhead
• Improved Maintainability: Shared infrastructure reduces code duplication and testing surface area
• Enhanced User Experience: Single command provides clearer mental model and simpler installation
• Alignment with Unix Philosophy: Tools should be unified when they share significant infrastructure
• Deployment Simplification: Single artifact simplifies packaging, distribution, and CI/CD processes

Cleanup Scope

✔ Source code
✔ Documentation
✔ Tests
✔ Build configuration
✗ CI/CD workflows
✗ Dependencies
✗ Configuration files
✔ .samoyed/_/* scripts
✔ Examples/samples

Priority

⚡ High - Must be done before adoption by a large group of users.

Estimated Effort (Story Points)

8 - Could break many tests.

Breaking Changes

✗ No. We will keep the samoyed-hook until September 1, 2025. However it will work as a shim and perform 2 tasks:

• Print a warning message that samoyed-hook will be removed by September 1, 2025 and that they have to run samoyed init -f _, to force re-init the scripts under the .samoyed/_/* to changes their contents from:

  #!/usr/bin/env sh
  exec samoyed-hook "$(basename "$0")" "$@"

  to:

  #!/usr/bin/env sh
  exec samoyed hook "$(basename "$0")" "$@"

• Redirect calls to samoyed hook ...

Migration Plan

Migration steps for users:

• Step 1: Users with existing .samoyed/_/ hook files will need to regenerate them with samoyed init -f _ (hooks will call samoyed hook instead of samoyed-hook)
• Deprecation timeline: The samoyed-hook binary will be removed not earlier than Septmber 1, 2025 (and not later than October 1, 2025).

Acceptance Criteria

Each sub-issue in an AC.

Dependencies

• Relates to: Build system and release workflows will need updates for single binary
• Blocks: Future feature development will benefit from simplified architecture

Risks & Considerations

Potential risks:

• Risk 1: Hook execution performance regression due to CLI parsing overhead → Mitigation: Profile and optimize subcommand parsing; CLI parsing is negligible compared to process spawn overhead
• Risk 2: Breaking changes require careful user migration → Mitigation: Provide clear migration guide and provide auto-migration using samoyed init -f _
• Risk 3: Testing complexity during transition period → Mitigation: Implement changes with a methodical approach, and in small chunks.

Technical Implementation

The implementation will follow the Command Pattern:

#[derive(Subcommand)]
enum Commands {
    /// Initialize samoyed in the current repository  
    Init {
        #[arg(short, long)]
        project_type: Option<String>,
        /// NEW `-f/--force _` flag to be added
    },
    /// Execute git hook (internal command)
    Hook {
        /// Name of the hook being executed
        hook_name: String,
        /// Arguments passed from git
        #[arg(trailing_var_arg = true)]
        args: Vec<String>,
    },
}

Key architectural preservation:

• Dependency injection patterns maintained for both commands
• Security boundaries preserved (hook execution context isolated)
• Error handling and exit codes consistent with current implementation
• Environment variable processing (SAMOYED=0/1/2) unchanged

Philosophical Justification

This change achieves Hegelian Aufhebung (sublation):

• Preserves: Essential functional separation between installation and execution logic
• Negates: Artificial binary boundary that creates deployment and maintenance overhead
• Elevates: Achieves conceptual unity while maintaining architectural clarity

Following Ockham's Razor: Entities should not be multiplied beyond necessity. The functional separation does not require binary separation.

Conway's Law Inversion: Instead of letting organizational structure (two binaries) dictate architecture, let logical structure (unified tool) drive organization.