dynamicalsystem.com / tinsnip
homelab infrastructure services
fork atom
tinsnip / docs / cli_forward_refactor.md
at main 8.1 kB view raw view code
dynamicalsystem.com Fix all remaining SSEP references in documentation
cd555451

CLI Forward Refactor - COMPLETED ✅#

Issues Resolved#

The tinsnip codebase refactor has been completed, resolving the scattered code structure:

  • ✅ Code consolidated from ./machine, ./scripts, ./bin, ./service/station/, and root into organized structure
  • ✅ CLI commands now implemented as tin with subcommands in organized ./cmd/ structure
  • ✅ Core functionality consolidated in focused ./lib/ modules
  • ✅ Clear boundaries: CLI commands in ./cmd/, shared libraries in ./lib/, validation in ./validation/
  • ✅ Legacy ./scripts/ directory removed
  • ✅ Service definitions cleanly separated in ./service/ with platform code organized
  • ✅ Consistent patterns: All CLI functionality follows ./cmd/{command}/ structure

The refactor successfully implemented the CLI-forward organization:

Current Organization (Implemented)#

tinsnip/
├── install.sh                    # Keep at root (installation entry point)
├── setup.sh                      # Keep at root (legacy compatibility)
├── bin/
│   └── tin                       # Main CLI entry point only
├── cmd/                          # CLI command implementations
│   ├── sheet/
│   │   ├── create.sh
│   │   ├── list.sh
│   │   └── show.sh
│   ├── machine/
│   │   ├── create.sh
│   │   ├── list.sh
│   │   ├── status.sh
│   │   └── teardown.sh
│   ├── service/
│   │   ├── deploy.sh
│   │   ├── list.sh
│   │   ├── logs.sh
│   │   └── status.sh
│   ├── registry/
│   │   ├── service.sh
│   │   └── nas.sh
│   │   └── sheet.sh             # Sheet registry
│   ├── key/
│   │   ├── generate.sh           # From service/station/scripts/nas-key-manager.sh
│   │   ├── list.sh
│   │   └── status.sh
│   └── status/
│       └── show.sh
├── lib/                          # Shared libraries and functions
│   ├── core.sh                   # Core SMEP utilities (from machine/scripts/lib.sh)
│   ├── uid.sh                    # UID/port calculations
│   ├── registry.sh               # Registry operations
|.  ├── nas.sh                    # NAS interaction functions
│   ├── nfs.sh                    # NFS mounting logic
│   └── docker.sh                 # Docker installation/management
# Note: ./service/station/ contains only management scripts, not a containerized service
# These scripts will be distributed to appropriate cmd/ and lib/ locations
└── tests/                        # Keep existing test structure
│   ├── test-registry-approach.sh
│   └── ...
└── validation/                   # Collect validation scripts
    ├── functions.sh
    ├── ports.sh
    └── dry-run.sh

Key Changes#

1. CLI Forward Organization#

Commands in cmd/ mirror tin subcommands

  • Move tin-* executables from ./bin/ to ./cmd/{command}/ structure
  • Each CLI command maps to a directory with focused functionality
  • ./bin/tin becomes a simple router to ./cmd/ implementations

2. Shared Libraries#

  • Consolidate ./machine/scripts/lib.sh and related utilities into ./lib/
  • Create focused library modules by responsibility
  • Remove duplication between ./scripts/ and ./machine/scripts/

3. Service Separation#

  • Distribute station management scripts to appropriate ./cmd/ and ./lib/ locations
  • Remove user service definitions from platform repository
  • Clear separation between platform code and service catalog

4. Validation isolation:#

Collect all validation in dedicated directory

5. Implementation Benefits#

  • Predictable: CLI command tin sheet list → ./cmd/sheet/list.sh
  • Focused: Each command implementation handles one concern
  • Reusable: Shared functionality in focused library modules
  • Extensible: Easy to add new commands following pattern
  • Testable: Each command can be unit tested independently
  • Maintainable: Clear ownership boundaries between components
  • Clear boundaries: Platform vs service vs CLI vs validation
  • Clear separation of concerns: Each command handles focused functionality

CLI Command Mapping#

Current Location CLI Command New Location
./bin/tin-sheet tin sheet ./cmd/sheet/
./bin/tin-machine tin machine ./cmd/machine/
./bin/tin-service tin service ./cmd/service/
./bin/tin-registry tin registry ./cmd/registry/
./bin/tin-key tin key ./cmd/key/
./bin/tin-status tin status ./cmd/status/

Library Consolidation#

Current Location Responsibility New Location
./machine/scripts/lib.sh Core utilities, UID calculations ./lib/core.sh, ./lib/uid.sh
./machine/scripts/mount_nas.sh NFS mounting logic ./lib/nfs.sh
./machine/scripts/install_docker.sh Docker installation ./lib/docker.sh
./machine/scripts/validate_*.sh Validation functions ./lib/validation.sh
./scripts/register_service.sh Registry operations ./lib/registry.sh
./service/station/scripts/registry-functions.sh Registry operations ./lib/registry.sh
./service/station/scripts/nas-key-manager.sh Key management ./cmd/key/

Migration Strategy#

  1. Create new structure alongside existing code

    • Create ./cmd/ and ./lib/ directories
    • Begin moving functionality incrementally

  2. Consolidate shared code into ./lib/

    • Extract common functions from ./machine/scripts/lib.sh
    • Remove duplication between ./scripts/ and ./machine/scripts/
    • Create focused library modules by responsibility
    • Update imports

  3. Migrate CLI commands one at a time

    • Start with tin sheet as it's self-contained
    • Extract shared code to appropriate ./lib/ modules
    • Update ./bin/tin routing as commands are migrated

  4. Distribute station scripts

    • Move ./service/station/scripts/nas-key-manager.sh to ./cmd/key/
    • Move ./service/station/scripts/registry-functions.sh to ./lib/registry.sh
    • Remove user service definitions from platform repository

  5. Remove old structure once migration complete

    • Remove ./machine/scripts/ after functionality moved to ./lib/
    • Remove legacy ./scripts/ directory
    • Clean up obsolete ./bin/tin-* files

  6. Update install.sh and setup.sh

  7. Update documentation to reflect new organization

    • Update README.md with new structure
    • Update CLAUDE.md with new conventions
    • Update deployment guides with new paths

Implementation Status - COMPLETED ✅#

  1. ✅ Phase 1: Core library consolidation - COMPLETED

    • ✅ Created ./lib/core.sh from ./machine/scripts/lib.sh
    • ✅ Created ./lib/uid.sh for UID/port calculations
    • ✅ Updated existing commands to use new library locations

  2. ✅ Phase 2: Command structure migration - COMPLETED

    • ✅ Migrated tin sheet command to ./cmd/sheet/
    • ✅ Migrated tin machine command to ./cmd/machine/
    • ✅ Updated ./bin/tin routing

  3. ✅ Phase 3: All commands and cleanup - COMPLETED

    • ✅ Migrated all CLI commands (23 implementations across 7 command groups)
    • ✅ Added bonus ./cmd/nas/ functionality
    • ✅ Removed obsolete directories and files

Final Status#

🎉 CLI Forward Refactor is COMPLETE

  • 23 command implementations across 7 command groups
  • 6 focused library modules replacing scattered utilities
  • Complete CLI routing through unified bin/tin
  • Clean separation between CLI, libraries, validation, and services
  • All legacy references updated to new structure

The codebase now follows predictable CLI-forward patterns where tin {command} {action} maps directly to ./cmd/{command}/{action}.sh.