dynamicalsystem.com
homelab infrastructure services
1# CLI Forward Refactor - COMPLETED ✅
2
3## Issues Resolved
4
5The tinsnip codebase refactor has been completed, resolving the scattered code structure:
6
7- ✅ Code consolidated from `./machine`, `./scripts`, `./bin`, `./service/station/`, and root into organized structure
8- ✅ CLI commands now implemented as `tin` with subcommands in organized `./cmd/` structure
9- ✅ Core functionality consolidated in focused `./lib/` modules
10- ✅ Clear boundaries: CLI commands in `./cmd/`, shared libraries in `./lib/`, validation in `./validation/`
11- ✅ Legacy `./scripts/` directory removed
12- ✅ Service definitions cleanly separated in `./service/` with platform code organized
13- ✅ Consistent patterns: All CLI functionality follows `./cmd/{command}/` structure
14
15The refactor successfully implemented the CLI-forward organization:
16
17## Current Organization (Implemented)
18
19```
20tinsnip/
21├── install.sh # Keep at root (installation entry point)
22├── setup.sh # Keep at root (legacy compatibility)
23├── bin/
24│ └── tin # Main CLI entry point only
25├── cmd/ # CLI command implementations
26│ ├── sheet/
27│ │ ├── create.sh
28│ │ ├── list.sh
29│ │ └── show.sh
30│ ├── machine/
31│ │ ├── create.sh
32│ │ ├── list.sh
33│ │ ├── status.sh
34│ │ └── teardown.sh
35│ ├── service/
36│ │ ├── deploy.sh
37│ │ ├── list.sh
38│ │ ├── logs.sh
39│ │ └── status.sh
40│ ├── registry/
41│ │ ├── service.sh
42│ │ └── nas.sh
43│ │ └── sheet.sh # Sheet registry
44│ ├── key/
45│ │ ├── generate.sh # From service/station/scripts/nas-key-manager.sh
46│ │ ├── list.sh
47│ │ └── status.sh
48│ └── status/
49│ └── show.sh
50├── lib/ # Shared libraries and functions
51│ ├── core.sh # Core SMEP utilities (from machine/scripts/lib.sh)
52│ ├── uid.sh # UID/port calculations
53│ ├── registry.sh # Registry operations
54|. ├── nas.sh # NAS interaction functions
55│ ├── nfs.sh # NFS mounting logic
56│ └── docker.sh # Docker installation/management
57# Note: ./service/station/ contains only management scripts, not a containerized service
58# These scripts will be distributed to appropriate cmd/ and lib/ locations
59└── tests/ # Keep existing test structure
60│ ├── test-registry-approach.sh
61│ └── ...
62└── validation/ # Collect validation scripts
63 ├── functions.sh
64 ├── ports.sh
65 └── dry-run.sh
66```
67
68## Key Changes
69
70### 1. CLI Forward Organization
71Commands in cmd/ mirror tin subcommands
72- Move `tin-*` executables from `./bin/` to `./cmd/{command}/` structure
73- Each CLI command maps to a directory with focused functionality
74- `./bin/tin` becomes a simple router to `./cmd/` implementations
75
76### 2. Shared Libraries
77- Consolidate `./machine/scripts/lib.sh` and related utilities into `./lib/`
78- Create focused library modules by responsibility
79- Remove duplication between `./scripts/` and `./machine/scripts/`
80
81### 3. Service Separation
82- Distribute station management scripts to appropriate `./cmd/` and `./lib/` locations
83- Remove user service definitions from platform repository
84- Clear separation between platform code and service catalog
85
86### 4. Validation isolation:
87Collect all validation in dedicated directory
88
89### 5. Implementation Benefits
90- **Predictable**: CLI command `tin sheet list` → `./cmd/sheet/list.sh`
91- **Focused**: Each command implementation handles one concern
92- **Reusable**: Shared functionality in focused library modules
93- **Extensible**: Easy to add new commands following pattern
94- **Testable**: Each command can be unit tested independently
95- **Maintainable**: Clear ownership boundaries between components
96- **Clear boundaries**: Platform vs service vs CLI vs validation
97- **Clear separation of concerns**: Each command handles focused functionality
98
99## CLI Command Mapping
100
101| Current Location | CLI Command | New Location |
102|------------------|-------------|--------------|
103| `./bin/tin-sheet` | `tin sheet` | `./cmd/sheet/` |
104| `./bin/tin-machine` | `tin machine` | `./cmd/machine/` |
105| `./bin/tin-service` | `tin service` | `./cmd/service/` |
106| `./bin/tin-registry` | `tin registry` | `./cmd/registry/` |
107| `./bin/tin-key` | `tin key` | `./cmd/key/` |
108| `./bin/tin-status` | `tin status` | `./cmd/status/` |
109
110## Library Consolidation
111
112| Current Location | Responsibility | New Location |
113|------------------|----------------|--------------|
114| `./machine/scripts/lib.sh` | Core utilities, UID calculations | `./lib/core.sh`, `./lib/uid.sh` |
115| `./machine/scripts/mount_nas.sh` | NFS mounting logic | `./lib/nfs.sh` |
116| `./machine/scripts/install_docker.sh` | Docker installation | `./lib/docker.sh` |
117| `./machine/scripts/validate_*.sh` | Validation functions | `./lib/validation.sh` |
118| `./scripts/register_service.sh` | Registry operations | `./lib/registry.sh` |
119| `./service/station/scripts/registry-functions.sh` | Registry operations | `./lib/registry.sh` |
120| `./service/station/scripts/nas-key-manager.sh` | Key management | `./cmd/key/` |
121
122## Migration Strategy
123
1241. **Create new structure alongside existing code**
125 - Create `./cmd/` and `./lib/` directories
126 - Begin moving functionality incrementally
127
1282. **Consolidate shared code into `./lib/`**
129 - Extract common functions from `./machine/scripts/lib.sh`
130 - Remove duplication between `./scripts/` and `./machine/scripts/`
131 - Create focused library modules by responsibility
132 - Update imports
133
1343. **Migrate CLI commands one at a time**
135 - Start with `tin sheet` as it's self-contained
136 - Extract shared code to appropriate `./lib/` modules
137 - Update `./bin/tin` routing as commands are migrated
138
1394. **Distribute station scripts**
140 - Move `./service/station/scripts/nas-key-manager.sh` to `./cmd/key/`
141 - Move `./service/station/scripts/registry-functions.sh` to `./lib/registry.sh`
142 - Remove user service definitions from platform repository
143
1445. **Remove old structure once migration complete**
145 - Remove `./machine/scripts/` after functionality moved to `./lib/`
146 - Remove legacy `./scripts/` directory
147 - Clean up obsolete `./bin/tin-*` files
148
1496. **Update install.sh and setup.sh**
150
1516. **Update documentation to reflect new organization**
152 - Update README.md with new structure
153 - Update CLAUDE.md with new conventions
154 - Update deployment guides with new paths
155
156## Implementation Status - COMPLETED ✅
157
1581. **✅ Phase 1**: Core library consolidation - COMPLETED
159 - ✅ Created `./lib/core.sh` from `./machine/scripts/lib.sh`
160 - ✅ Created `./lib/uid.sh` for UID/port calculations
161 - ✅ Updated existing commands to use new library locations
162
1632. **✅ Phase 2**: Command structure migration - COMPLETED
164 - ✅ Migrated `tin sheet` command to `./cmd/sheet/`
165 - ✅ Migrated `tin machine` command to `./cmd/machine/`
166 - ✅ Updated `./bin/tin` routing
167
1683. **✅ Phase 3**: All commands and cleanup - COMPLETED
169 - ✅ Migrated all CLI commands (23 implementations across 7 command groups)
170 - ✅ Added bonus `./cmd/nas/` functionality
171 - ✅ Removed obsolete directories and files
172
173## Final Status
174
175**🎉 CLI Forward Refactor is COMPLETE**
176
177- **23 command implementations** across 7 command groups
178- **6 focused library modules** replacing scattered utilities
179- **Complete CLI routing** through unified `bin/tin`
180- **Clean separation** between CLI, libraries, validation, and services
181- **All legacy references** updated to new structure
182
183The codebase now follows predictable CLI-forward patterns where `tin {command} {action}` maps directly to `./cmd/{command}/{action}.sh`.