# Repository Restructuring - Implementation Guide\n\n**Status:** Ready for Implementation\n**Estimated Time:** 12-16 days\n**Priority:** High\n**Related:** [Architecture Analysis](../architecture/repo-dist-analysis.md)\n\n## Overview\n\nThis guide provides step-by-step instructions for implementing the repository restructuring and distribution system improvements. Each phase includes\nspecific commands, validation steps, and rollback procedures.\n\n---\n\n## Prerequisites\n\n### Required Tools\n\n- Nushell 0.107.1+\n- Rust toolchain (for platform builds)\n- Git\n- tar/gzip\n- curl or wget\n\n### Recommended Tools\n\n- Just (task runner)\n- ripgrep (for code searches)\n- fd (for file finding)\n\n### Before Starting\n\n1. **Create full backup**\n2. **Notify team members**\n3. **Create implementation branch**\n4. **Set aside dedicated time**\n\n---\n\n## Phase 1: Repository Restructuring (Days 1-4)\n\n### Day 1: Backup and Analysis\n\n#### Step 1.1: Create Complete Backup\n\n```\n# Create timestamped backup\nBACKUP_DIR="/Users/Akasha/project-provisioning-backup-$(date +%Y%m%d)"\ncp -r /Users/Akasha/project-provisioning "$BACKUP_DIR"\n\n# Verify backup\nls -lh "$BACKUP_DIR"\ndu -sh "$BACKUP_DIR"\n\n# Create backup manifest\nfind "$BACKUP_DIR" -type f > "$BACKUP_DIR/manifest.txt"\necho "✅ Backup created: $BACKUP_DIR"\n```\n\n#### Step 1.2: Analyze Current State\n\n```\ncd /Users/Akasha/project-provisioning\n\n# Count workspace directories\necho "=== Workspace Directories ==="\nfd workspace -t d\n\n# Analyze workspace contents\necho "=== Active Workspace ==="\ndu -sh workspace/\n\necho "=== Backup Workspaces ==="\ndu -sh _workspace/ backup-workspace/ workspace-librecloud/\n\n# Find obsolete directories\necho "=== Build Artifacts ==="\ndu -sh target/ wrks/ NO/\n\n# Save analysis\n{\n    echo "# Current State Analysis - $(date)"\n    echo ""\n    echo "## Workspace Directories"\n    fd workspace -t d\n    echo ""\n    echo "## Directory Sizes"\n    du -sh workspace/ _workspace/ backup-workspace/ workspace-librecloud/ 2>/dev/null\n    echo ""\n    echo "## Build Artifacts"\n    du -sh target/ wrks/ NO/ 2>/dev/null\n} > docs/development/current-state-analysis.txt\n\necho "✅ Analysis complete: docs/development/current-state-analysis.txt"\n```\n\n#### Step 1.3: Identify Dependencies\n\n```\n# Find all hardcoded paths\necho "=== Hardcoded Paths in Nushell Scripts ==="\nrg -t nu "workspace/|_workspace/|backup-workspace/" provisioning/core/nulib/ | tee hardcoded-paths.txt\n\n# Find ENV references (legacy)\necho "=== ENV References ==="\nrg "PROVISIONING_" provisioning/core/nulib/ | wc -l\n\n# Find workspace references in configs\necho "=== Config References ==="\nrg "workspace" provisioning/config/\n\necho "✅ Dependencies mapped"\n```\n\n#### Step 1.4: Create Implementation Branch\n\n```\n# Create and switch to implementation branch\ngit checkout -b feat/repo-restructure\n\n# Commit analysis\ngit add docs/development/current-state-analysis.txt\ngit commit -m "docs: add current state analysis for restructuring"\n\necho "✅ Implementation branch created: feat/repo-restructure"\n```\n\n**Validation:**\n\n- ✅ Backup exists and is complete\n- ✅ Analysis document created\n- ✅ Dependencies mapped\n- ✅ Implementation branch ready\n\n---\n\n### Day 2: Directory Restructuring\n\n#### Step 2.1: Create New Directory Structure\n\n```\ncd /Users/Akasha/project-provisioning\n\n# Create distribution directory structure\nmkdir -p distribution/{packages,installers,registry}\necho "✅ Created distribution/"\n\n# Create workspace structure (keep tracked templates)\nmkdir -p workspace/{infra,config,extensions,runtime}/{.gitkeep}\nmkdir -p workspace/templates/{minimal,kubernetes,multi-cloud}\necho "✅ Created workspace/"\n\n# Verify\ntree -L 2 distribution/ workspace/\n```\n\n#### Step 2.2: Move Build Artifacts\n\n```\n# Move Rust build artifacts\nif [ -d "target" ]; then\n    mv target distribution/target\n    echo "✅ Moved target/ to distribution/"\nfi\n\n# Move KCL packages\nif [ -d "provisioning/tools/dist" ]; then\n    mv provisioning/tools/dist/* distribution/packages/ 2>/dev/null || true\n    echo "✅ Moved packages to distribution/"\nfi\n\n# Move any existing packages\nfind . -name "*.tar.gz" -o -name "*.zip" | grep -v node_modules | while read pkg; do\n    mv "$pkg" distribution/packages/\n    echo "  Moved: $pkg"\ndone\n```\n\n#### Step 2.3: Consolidate Workspaces\n\n```\n# Identify active workspace\necho "=== Current Workspace Status ==="\nls -la workspace/ _workspace/ backup-workspace/ 2>/dev/null\n\n# Interactive workspace consolidation\nread -p "Which workspace is currently active? (workspace/_workspace/backup-workspace): " ACTIVE_WS\n\nif [ "$ACTIVE_WS" != "workspace" ]; then\n    echo "Consolidating $ACTIVE_WS to workspace/"\n\n    # Merge infra configs\n    if [ -d "$ACTIVE_WS/infra" ]; then\n        cp -r "$ACTIVE_WS/infra/"* workspace/infra/\n    fi\n\n    # Merge configs\n    if [ -d "$ACTIVE_WS/config" ]; then\n        cp -r "$ACTIVE_WS/config/"* workspace/config/\n    fi\n\n    # Merge extensions\n    if [ -d "$ACTIVE_WS/extensions" ]; then\n        cp -r "$ACTIVE_WS/extensions/"* workspace/extensions/\n    fi\n\n    echo "✅ Consolidated workspace"\nfi\n\n# Archive old workspace directories\nmkdir -p .archived-workspaces\nfor ws in _workspace backup-workspace workspace-librecloud; do\n    if [ -d "$ws" ] && [ "$ws" != "$ACTIVE_WS" ]; then\n        mv "$ws" ".archived-workspaces/$(basename $ws)-$(date +%Y%m%d)"\n        echo "  Archived: $ws"\n    fi\ndone\n\necho "✅ Workspaces consolidated"\n```\n\n#### Step 2.4: Remove Obsolete Directories\n\n```\n# Remove build artifacts (already moved)\nrm -rf wrks/\necho "✅ Removed wrks/"\n\n# Remove test/scratch directories\nrm -rf NO/\necho "✅ Removed NO/"\n\n# Archive presentations (optional)\nif [ -d "presentations" ]; then\n    read -p "Archive presentations directory? (y/N): " ARCHIVE_PRES\n    if [ "$ARCHIVE_PRES" = "y" ]; then\n        tar czf presentations-archive-$(date +%Y%m%d).tar.gz presentations/\n        rm -rf presentations/\n        echo "✅ Archived and removed presentations/"\n    fi\nfi\n\n# Remove empty directories\nfind . -type d -empty -delete 2>/dev/null || true\n\necho "✅ Cleanup complete"\n```\n\n#### Step 2.5: Update .gitignore\n\n```\n# Backup existing .gitignore\ncp .gitignore .gitignore.backup\n\n# Update .gitignore\ncat >> .gitignore << 'EOF'\n\n# ============================================================================\n# Repository Restructure (2025-10-01)\n# ============================================================================\n\n# Workspace runtime data (user-specific)\n/workspace/infra/\n/workspace/config/\n/workspace/extensions/\n/workspace/runtime/\n\n# Distribution artifacts\n/distribution/packages/\n/distribution/target/\n\n# Build artifacts\n/target/\n/provisioning/platform/target/\n/provisioning/platform/*/target/\n\n# Rust artifacts\n**/*.rs.bk\nCargo.lock\n\n# Archived directories\n/.archived-workspaces/\n\n# Temporary files\n*.tmp\n*.temp\n/tmp/\n/wrks/\n/NO/\n\n# Logs\n*.log\n/workspace/runtime/logs/\n\n# Cache\n.cache/\n/workspace/runtime/cache/\n\n# IDE\n.vscode/\n.idea/\n*.swp\n*.swo\n*~\n\n# OS\n.DS_Store\nThumbs.db\n\n# Backup files\n*.backup\n*.bak\n\nEOF\n\necho "✅ Updated .gitignore"\n```\n\n#### Step 2.6: Commit Restructuring\n\n```\n# Stage changes\ngit add -A\n\n# Show what's being committed\ngit status\n\n# Commit\ngit commit -m "refactor: restructure repository for clean distribution\n\n- Consolidate workspace directories to single workspace/\n- Move build artifacts to distribution/\n- Remove obsolete directories (wrks/, NO/)\n- Update .gitignore for new structure\n- Archive old workspace variants\n\nThis is part of Phase 1 of the repository restructuring plan.\n\nRelated: docs/architecture/repo-dist-analysis.md"\n\necho "✅ Restructuring committed"\n```\n\n**Validation:**\n\n- ✅ Single `workspace/` directory exists\n- ✅ Build artifacts in `distribution/`\n- ✅ No `wrks/`, `NO/` directories\n- ✅ `.gitignore` updated\n- ✅ Changes committed\n\n---\n\n### Day 3: Update Path References\n\n#### Step 3.1: Create Path Update Script\n\n```\n# Create migration script\ncat > provisioning/tools/migration/update-paths.nu << 'EOF'\n#!/usr/bin/env nu\n# Path update script for repository restructuring\n\n# Find and replace path references\nexport def main [] {\n    print "🔧 Updating path references..."\n\n    let replacements = [\n        ["_workspace/" "workspace/"]\n        ["backup-workspace/" "workspace/"]\n        ["workspace-librecloud/" "workspace/"]\n        ["wrks/" "distribution/"]\n        ["NO/" "distribution/"]\n    ]\n\n    let files = (fd -e nu -e toml -e md . provisioning/)\n\n    mut updated_count = 0\n\n    for file in $files {\n        mut content = (open $file)\n        mut modified = false\n\n        for replacement in $replacements {\n            let old = $replacement.0\n            let new = $replacement.1\n\n            if ($content | str contains $old) {\n                $content = ($content | str replace -a $old $new)\n                $modified = true\n            }\n        }\n\n        if $modified {\n            $content | save -f $file\n            $updated_count = $updated_count + 1\n            print $"  ✓ Updated: ($file)"\n        }\n    }\n\n    print $"✅ Updated ($updated_count) files"\n}\nEOF\n\nchmod +x provisioning/tools/migration/update-paths.nu\n```\n\n#### Step 3.2: Run Path Updates\n\n```\n# Create backup before updates\ngit stash\ngit checkout -b feat/path-updates\n\n# Run update script\nnu provisioning/tools/migration/update-paths.nu\n\n# Review changes\ngit diff\n\n# Test a sample file\nnu -c "use provisioning/core/nulib/servers/create.nu; print 'OK'"\n```\n\n#### Step 3.3: Update CLAUDE.md\n\n```\n# Update CLAUDE.md with new paths\ncat > CLAUDE.md.new << 'EOF'\n# CLAUDE.md\n\n[Keep existing content, update paths section...]\n\n## Updated Path Structure (2025-10-01)\n\n### Core System\n- **Main CLI**: `provisioning/core/cli/provisioning`\n- **Libraries**: `provisioning/core/nulib/`\n- **Extensions**: `provisioning/extensions/`\n- **Platform**: `provisioning/platform/`\n\n### User Workspace\n- **Active Workspace**: `workspace/` (gitignored runtime data)\n- **Templates**: `workspace/templates/` (tracked)\n- **Infrastructure**: `workspace/infra/` (user configs, gitignored)\n\n### Build System\n- **Distribution**: `distribution/` (gitignored artifacts)\n- **Packages**: `distribution/packages/`\n- **Installers**: `distribution/installers/`\n\n[Continue with rest of content...]\nEOF\n\n# Review changes\ndiff CLAUDE.md CLAUDE.md.new\n\n# Apply if satisfied\nmv CLAUDE.md.new CLAUDE.md\n```\n\n#### Step 3.4: Update Documentation\n\n```\n# Find all documentation files\nfd -e md . docs/\n\n# Update each doc with new paths\n# This is semi-automated - review each file\n\n# Create list of docs to update\nfd -e md . docs/ > docs-to-update.txt\n\n# Manual review and update\necho "Review and update each documentation file with new paths"\necho "Files listed in: docs-to-update.txt"\n```\n\n#### Step 3.5: Commit Path Updates\n\n```\ngit add -A\ngit commit -m "refactor: update all path references for new structure\n\n- Update Nushell scripts to use workspace/ instead of variants\n- Update CLAUDE.md with new path structure\n- Update documentation references\n- Add migration script for future path changes\n\nPhase 1.3 of repository restructuring."\n\necho "✅ Path updates committed"\n```\n\n**Validation:**\n\n- ✅ All Nushell scripts reference correct paths\n- ✅ CLAUDE.md updated\n- ✅ Documentation updated\n- ✅ No references to old paths remain\n\n---\n\n### Day 4: Validation and Testing\n\n#### Step 4.1: Automated Validation\n\n```\n# Create validation script\ncat > provisioning/tools/validation/validate-structure.nu << 'EOF'\n#!/usr/bin/env nu\n# Repository structure validation\n\nexport def main [] {\n    print "🔍 Validating repository structure..."\n\n    mut passed = 0\n    mut failed = 0\n\n    # Check required directories exist\n    let required_dirs = [\n        "provisioning/core"\n        "provisioning/extensions"\n        "provisioning/platform"\n        "provisioning/schemas"\n        "workspace"\n        "workspace/templates"\n        "distribution"\n        "docs"\n        "tests"\n    ]\n\n    for dir in $required_dirs {\n        if ($dir | path exists) {\n            print $"  ✓ ($dir)"\n            $passed = $passed + 1\n        } else {\n            print $"  ✗ ($dir) MISSING"\n            $failed = $failed + 1\n        }\n    }\n\n    # Check obsolete directories don't exist\n    let obsolete_dirs = [\n        "_workspace"\n        "backup-workspace"\n        "workspace-librecloud"\n        "wrks"\n        "NO"\n    ]\n\n    for dir in $obsolete_dirs {\n        if not ($dir | path exists) {\n            print $"  ✓ ($dir) removed"\n            $passed = $passed + 1\n        } else {\n            print $"  ✗ ($dir) still exists"\n            $failed = $failed + 1\n        }\n    }\n\n    # Check no old path references\n    let old_paths = ["_workspace/" "backup-workspace/" "wrks/"]\n    for path in $old_paths {\n        let results = (rg -l $path provisioning/ --iglob "!*.md" 2>/dev/null | lines)\n        if ($results | is-empty) {\n            print $"  ✓ No references to ($path)"\n            $passed = $passed + 1\n        } else {\n            print $"  ✗ Found references to ($path):"\n            $results | each { |f| print $"    - ($f)" }\n            $failed = $failed + 1\n        }\n    }\n\n    print ""\n    print $"Results: ($passed) passed, ($failed) failed"\n\n    if $failed > 0 {\n        error make { msg: "Validation failed" }\n    }\n\n    print "✅ Validation passed"\n}\nEOF\n\nchmod +x provisioning/tools/validation/validate-structure.nu\n\n# Run validation\nnu provisioning/tools/validation/validate-structure.nu\n```\n\n#### Step 4.2: Functional Testing\n\n```\n# Test core commands\necho "=== Testing Core Commands ==="\n\n# Version\nprovisioning/core/cli/provisioning version\necho "✓ version command"\n\n# Help\nprovisioning/core/cli/provisioning help\necho "✓ help command"\n\n# List\nprovisioning/core/cli/provisioning list servers\necho "✓ list command"\n\n# Environment\nprovisioning/core/cli/provisioning env\necho "✓ env command"\n\n# Validate config\nprovisioning/core/cli/provisioning validate config\necho "✓ validate command"\n\necho "✅ Functional tests passed"\n```\n\n#### Step 4.3: Integration Testing\n\n```\n# Test workflow system\necho "=== Testing Workflow System ==="\n\n# List workflows\nnu -c "use provisioning/core/nulib/workflows/management.nu *; workflow list"\necho "✓ workflow list"\n\n# Test workspace commands\necho "=== Testing Workspace Commands ==="\n\n# Workspace info\nprovisioning/core/cli/provisioning workspace info\necho "✓ workspace info"\n\necho "✅ Integration tests passed"\n```\n\n#### Step 4.4: Create Test Report\n\n```\n{\n    echo "# Repository Restructuring - Validation Report"\n    echo "Date: $(date)"\n    echo ""\n    echo "## Structure Validation"\n    nu provisioning/tools/validation/validate-structure.nu 2>&1\n    echo ""\n    echo "## Functional Tests"\n    echo "✓ version command"\n    echo "✓ help command"\n    echo "✓ list command"\n    echo "✓ env command"\n    echo "✓ validate command"\n    echo ""\n    echo "## Integration Tests"\n    echo "✓ workflow list"\n    echo "✓ workspace info"\n    echo ""\n    echo "## Conclusion"\n    echo "✅ Phase 1 validation complete"\n} > docs/development/phase1-validation-report.md\n\necho "✅ Test report created: docs/development/phase1-validation-report.md"\n```\n\n#### Step 4.5: Update README\n\n```\n# Update main README with new structure\n# This is manual - review and update README.md\n\necho "📝 Please review and update README.md with new structure"\necho "   - Update directory structure diagram"\necho "   - Update installation instructions"\necho "   - Update quick start guide"\n```\n\n#### Step 4.6: Finalize Phase 1\n\n```\n# Commit validation and reports\ngit add -A\ngit commit -m "test: add validation for repository restructuring\n\n- Add structure validation script\n- Add functional tests\n- Add integration tests\n- Create validation report\n- Document Phase 1 completion\n\nPhase 1 complete: Repository restructuring validated."\n\n# Merge to implementation branch\ngit checkout feat/repo-restructure\ngit merge feat/path-updates\n\necho "✅ Phase 1 complete and merged"\n```\n\n**Validation:**\n\n- ✅ All validation tests pass\n- ✅ Functional tests pass\n- ✅ Integration tests pass\n- ✅ Validation report created\n- ✅ README updated\n- ✅ Phase 1 changes merged\n\n---\n\n## Phase 2: Build System Implementation (Days 5-8)\n\n### Day 5: Build System Core\n\n#### Step 5.1: Create Build Tools Directory\n\n```\nmkdir -p provisioning/tools/build\ncd provisioning/tools/build\n\n# Create directory structure\nmkdir -p {core,platform,extensions,validation,distribution}\n\necho "✅ Build tools directory created"\n```\n\n#### Step 5.2: Implement Core Build System\n\n```\n# Create main build orchestrator\n# See full implementation in repo-dist-analysis.md\n# Copy build-system.nu from the analysis document\n\n# Test build system\nnu build-system.nu status\n```\n\n#### Step 5.3: Implement Core Packaging\n\n```\n# Create package-core.nu\n# This packages Nushell libraries, KCL schemas, templates\n\n# Test core packaging\nnu build-system.nu build-core --version dev\n```\n\n#### Step 5.4: Create Justfile\n\n```\n# Create Justfile in project root\n# See full Justfile in repo-dist-analysis.md\n\n# Test Justfile\njust --list\njust status\n```\n\n**Validation:**\n\n- ✅ Build system structure exists\n- ✅ Core build orchestrator works\n- ✅ Core packaging works\n- ✅ Justfile functional\n\n### Day 6-8: Continue with Platform, Extensions, and Validation\n\n[Follow similar pattern for remaining build system components]\n\n---\n\n## Phase 3: Installation System (Days 9-11)\n\n### Day 9: Nushell Installer\n\n#### Step 9.1: Create install.nu\n\n```\nmkdir -p distribution/installers\n\n# Create install.nu\n# See full implementation in repo-dist-analysis.md\n```\n\n#### Step 9.2: Test Installation\n\n```\n# Test installation to /tmp\nnu distribution/installers/install.nu --prefix /tmp/provisioning-test\n\n# Verify\nls -lh /tmp/provisioning-test/\n\n# Test uninstallation\nnu distribution/installers/install.nu uninstall --prefix /tmp/provisioning-test\n```\n\n**Validation:**\n\n- ✅ Installer works\n- ✅ Files installed to correct locations\n- ✅ Uninstaller works\n- ✅ No files left after uninstall\n\n---\n\n## Rollback Procedures\n\n### If Phase 1 Fails\n\n```\n# Restore from backup\nrm -rf /Users/Akasha/project-provisioning\ncp -r "$BACKUP_DIR" /Users/Akasha/project-provisioning\n\n# Return to main branch\ncd /Users/Akasha/project-provisioning\ngit checkout main\ngit branch -D feat/repo-restructure\n```\n\n### If Build System Fails\n\n```\n# Revert build system commits\ngit checkout feat/repo-restructure\ngit revert <commit-hash>\n```\n\n### If Installation Fails\n\n```\n# Clean up test installation\nrm -rf /tmp/provisioning-test\nsudo rm -rf /usr/local/lib/provisioning\nsudo rm -rf /usr/local/share/provisioning\n```\n\n---\n\n## Checklist\n\n### Phase 1: Repository Restructuring\n\n- [ ] Day 1: Backup and analysis complete\n- [ ] Day 2: Directory restructuring complete\n- [ ] Day 3: Path references updated\n- [ ] Day 4: Validation passed\n\n### Phase 2: Build System\n\n- [ ] Day 5: Core build system implemented\n- [ ] Day 6: Platform/extensions packaging\n- [ ] Day 7: Package validation\n- [ ] Day 8: Build system tested\n\n### Phase 3: Installation\n\n- [ ] Day 9: Nushell installer created\n- [ ] Day 10: Bash installer and CLI\n- [ ] Day 11: Multi-OS testing\n\n### Phase 4: Registry (Optional)\n\n- [ ] Day 12: Registry system\n- [ ] Day 13: Registry commands\n- [ ] Day 14: Registry hosting\n\n### Phase 5: Documentation\n\n- [ ] Day 15: Documentation updated\n- [ ] Day 16: Release prepared\n\n---\n\n## Notes\n\n- **Take breaks between phases** - Don't rush\n- **Test thoroughly** - Each phase builds on previous\n- **Commit frequently** - Small, atomic commits\n- **Document issues** - Track any problems encountered\n- **Ask for review** - Get feedback at phase boundaries\n\n---\n\n## Support\n\nIf you encounter issues:\n\n1. Check the validation reports\n2. Review the rollback procedures\n3. Consult the architecture analysis\n4. Create an issue in the tracker
