26 KiB
26 KiB
/workspace/\nMain Tool: workspace/tools/workspace.nu\n\n## Workspace Architecture\n\n### Directory Structure\n\n\nworkspace/\n├── config/ # Development configuration\n│ ├── dev-defaults.toml # Development environment defaults\n│ ├── test-defaults.toml # Testing environment configuration\n│ ├── local-overrides.toml.example # User customization template\n│ └── {user}.toml # User-specific configurations\n├── extensions/ # Extension development\n│ ├── providers/ # Custom provider extensions\n│ │ ├── template/ # Provider development template\n│ │ └── {user}/ # User-specific providers\n│ ├── taskservs/ # Custom task service extensions\n│ │ ├── template/ # Task service template\n│ │ └── {user}/ # User-specific task services\n│ └── clusters/ # Custom cluster extensions\n│ ├── template/ # Cluster template\n│ └── {user}/ # User-specific clusters\n├── infra/ # Development infrastructure\n│ ├── examples/ # Example infrastructures\n│ │ ├── minimal/ # Minimal learning setup\n│ │ ├── development/ # Full development environment\n│ │ └── testing/ # Testing infrastructure\n│ ├── local/ # Local development setups\n│ └── {user}/ # User-specific infrastructures\n├── lib/ # Workspace libraries\n│ └── path-resolver.nu # Path resolution system\n├── runtime/ # Runtime data (per-user isolation)\n│ ├── workspaces/{user}/ # User workspace data\n│ ├── cache/{user}/ # User-specific cache\n│ ├── state/{user}/ # User state management\n│ ├── logs/{user}/ # User application logs\n│ └── data/{user}/ # User database files\n└── tools/ # Workspace management tools\n ├── workspace.nu # Main workspace interface\n ├── init-workspace.nu # Workspace initialization\n ├── workspace-health.nu # Health monitoring\n ├── backup-workspace.nu # Backup management\n ├── restore-workspace.nu # Restore functionality\n ├── reset-workspace.nu # Workspace reset\n └── runtime-manager.nu # Runtime data management\n\n\n### Component Integration\n\nWorkspace → Core Integration:\n\n- Workspace paths take priority over core paths\n- Extensions discovered automatically from workspace\n- Configuration cascades from workspace to core defaults\n- Runtime data completely isolated per user\n\nDevelopment Workflow:\n\n1. Initialize personal workspace\n2. Configure development environment\n3. Develop extensions and infrastructure\n4. Test locally with isolated environment\n5. Deploy to shared infrastructure\n\n## Setup and Initialization\n\n### Quick Start\n\n\n# Navigate to workspace\ncd workspace/tools\n\n# Initialize workspace with defaults\nnu workspace.nu init\n\n# Initialize with specific options\nnu workspace.nu init --user-name developer --infra-name my-dev-infra\n\n\n### Complete Initialization\n\n\n# Full initialization with all options\nnu workspace.nu init \\n --user-name developer \\n --infra-name development-env \\n --workspace-type development \\n --template full \\n --overwrite \\n --create-examples\n\n\nInitialization Parameters:\n\n- --user-name: User identifier (defaults to $env.USER)\n- --infra-name: Infrastructure name for this workspace\n- --workspace-type: Type (development, testing, production)\n- --template: Template to use (minimal, full, custom)\n- --overwrite: Overwrite existing workspace\n- --create-examples: Create example configurations and infrastructure\n\n### Post-Initialization Setup\n\nVerify Installation:\n\n\n# Check workspace health\nnu workspace.nu health --detailed\n\n# Show workspace status\nnu workspace.nu status --detailed\n\n# List workspace contents\nnu workspace.nu list\n\n\nConfigure Development Environment:\n\n\n# Create user-specific configuration\ncp workspace/config/local-overrides.toml.example workspace/config/$USER.toml\n\n# Edit configuration\n$EDITOR workspace/config/$USER.toml\n\n\n## Path Resolution System\n\nThe workspace implements a sophisticated path resolution system that prioritizes workspace paths while providing fallbacks to core system paths.\n\n### Resolution Hierarchy\n\nResolution Order:\n\n1. Workspace User Paths: workspace/{type}/{user}/{name}\n2. Workspace Shared Paths: workspace/{type}/{name}\n3. Workspace Templates: workspace/{type}/template/{name}\n4. Core System Paths: core/{type}/{name} (fallback)\n\n### Using Path Resolution\n\n\n# Import path resolver\nuse workspace/lib/path-resolver.nu\n\n# Resolve configuration with workspace awareness\nlet config_path = (path-resolver resolve_path "config" "user" --workspace-user "developer")\n\n# Resolve with automatic fallback to core\nlet extension_path = (path-resolver resolve_path "extensions" "custom-provider" --fallback-to-core)\n\n# Create missing directories during resolution\nlet new_path = (path-resolver resolve_path "infra" "my-infra" --create-missing)\n\n\n### Configuration Resolution\n\nHierarchical Configuration Loading:\n\n\n# Resolve configuration with full hierarchy\nlet config = (path-resolver resolve_config "user" --workspace-user "developer")\n\n# Load environment-specific configuration\nlet dev_config = (path-resolver resolve_config "development" --workspace-user "developer")\n\n# Get merged configuration with all overrides\nlet merged = (path-resolver resolve_config "merged" --workspace-user "developer" --include-overrides)\n\n\n### Extension Discovery\n\nAutomatic Extension Discovery:\n\n\n# Find custom provider extension\nlet provider = (path-resolver resolve_extension "providers" "my-aws-provider")\n\n# Discover all available task services\nlet taskservs = (path-resolver list_extensions "taskservs" --include-core)\n\n# Find cluster definition\nlet cluster = (path-resolver resolve_extension "clusters" "development-cluster")\n\n\n### Health Checking\n\nWorkspace Health Validation:\n\n\n# Check workspace health with automatic fixes\nlet health = (path-resolver check_workspace_health --workspace-user "developer" --fix-issues)\n\n# Validate path resolution chain\nlet validation = (path-resolver validate_paths --workspace-user "developer" --repair-broken)\n\n# Check runtime directories\nlet runtime_status = (path-resolver check_runtime_health --workspace-user "developer")\n\n\n## Configuration Management\n\n### Configuration Hierarchy\n\nConfiguration Cascade:\n\n1. User Configuration: workspace/config/{user}.toml\n2. Environment Defaults: workspace/config/{env}-defaults.toml\n3. Workspace Defaults: workspace/config/dev-defaults.toml\n4. Core System Defaults: config.defaults.toml\n\n### Environment-Specific Configuration\n\nDevelopment Environment (workspace/config/dev-defaults.toml):\n\n\n[core]\nname = "provisioning-dev"\nversion = "dev-${git.branch}"\n\n[development]\nauto_reload = true\nverbose_logging = true\nexperimental_features = true\nhot_reload_templates = true\n\n[http]\nuse_curl = false\ntimeout = 30\nretry_count = 3\n\n[cache]\nenabled = true\nttl = 300\nrefresh_interval = 60\n\n[logging]\nlevel = "debug"\nfile_rotation = true\nmax_size = "10 MB"\n\n\nTesting Environment (workspace/config/test-defaults.toml):\n\n\n[core]\nname = "provisioning-test"\nversion = "test-${build.timestamp}"\n\n[testing]\nmock_providers = true\nephemeral_resources = true\nparallel_tests = true\ncleanup_after_test = true\n\n[http]\nuse_curl = true\ntimeout = 10\nretry_count = 1\n\n[cache]\nenabled = false\nmock_responses = true\n\n[logging]\nlevel = "info"\ntest_output = true\n\n\n### User Configuration Example\n\nUser-Specific Configuration (workspace/config/{user}.toml):\n\n\n[core]\nname = "provisioning-${workspace.user}"\nversion = "1.0.0-dev"\n\n[infra]\ncurrent = "${workspace.user}-development"\ndefault_provider = "upcloud"\n\n[workspace]\nuser = "developer"\ntype = "development"\ninfra_name = "developer-dev"\n\n[development]\npreferred_editor = "code"\nauto_backup = true\nbackup_interval = "1h"\n\n[paths]\n# Custom paths for this user\ntemplates = "~/custom-templates"\nextensions = "~/my-extensions"\n\n[git]\nauto_commit = false\ncommit_message_template = "[${workspace.user}] ${change.type}: ${change.description}"\n\n[notifications]\nslack_webhook = "https://hooks.slack.com/..."\nemail = "developer@company.com"\n\n\n### Configuration Commands\n\nWorkspace Configuration Management:\n\n\n# Show current configuration\nnu workspace.nu config show\n\n# Validate configuration\nnu workspace.nu config validate --user-name developer\n\n# Edit user configuration\nnu workspace.nu config edit --user-name developer\n\n# Show configuration hierarchy\nnu workspace.nu config hierarchy --user-name developer\n\n# Merge configurations for debugging\nnu workspace.nu config merge --user-name developer --output merged-config.toml\n\n\n## Extension Development\n\n### Extension Types\n\nThe workspace provides templates and tools for developing three types of extensions:\n\n1. Providers: Cloud provider implementations\n2. Task Services: Infrastructure service components\n3. Clusters: Complete deployment solutions\n\n### Provider Extension Development\n\nCreate New Provider:\n\n\n# Copy template\ncp -r workspace/extensions/providers/template workspace/extensions/providers/my-provider\n\n# Initialize provider\ncd workspace/extensions/providers/my-provider\nnu init.nu --provider-name my-provider --author developer\n\n\nProvider Structure:\n\n\nworkspace/extensions/providers/my-provider/\n├── kcl/\n│ ├── provider.ncl # Provider configuration schema\n│ ├── server.ncl # Server configuration\n│ └── version.ncl # Version management\n├── nulib/\n│ ├── provider.nu # Main provider implementation\n│ ├── servers.nu # Server management\n│ └── auth.nu # Authentication handling\n├── templates/\n│ ├── server.j2 # Server configuration template\n│ └── network.j2 # Network configuration template\n├── tests/\n│ ├── unit/ # Unit tests\n│ └── integration/ # Integration tests\n└── README.md\n\n\nTest Provider:\n\n\n# Run provider tests\nnu workspace/extensions/providers/my-provider/nulib/provider.nu test\n\n# Test with dry-run\nnu workspace/extensions/providers/my-provider/nulib/provider.nu create-server --dry-run\n\n# Integration test\nnu workspace/extensions/providers/my-provider/tests/integration/basic-test.nu\n\n\n### Task Service Extension Development\n\nCreate New Task Service:\n\n\n# Copy template\ncp -r workspace/extensions/taskservs/template workspace/extensions/taskservs/my-service\n\n# Initialize service\ncd workspace/extensions/taskservs/my-service\nnu init.nu --service-name my-service --service-type database\n\n\nTask Service Structure:\n\n\nworkspace/extensions/taskservs/my-service/\n├── kcl/\n│ ├── taskserv.ncl # Service configuration schema\n│ ├── version.ncl # Version configuration with GitHub integration\n│ └── kcl.mod # KCL module dependencies\n├── nushell/\n│ ├── taskserv.nu # Main service implementation\n│ ├── install.nu # Installation logic\n│ ├── uninstall.nu # Removal logic\n│ └── check-updates.nu # Version checking\n├── templates/\n│ ├── config.j2 # Service configuration template\n│ ├── systemd.j2 # Systemd service template\n│ └── compose.j2 # Docker Compose template\n└── manifests/\n ├── deployment.yaml # Kubernetes deployment\n └── service.yaml # Kubernetes service\n\n\n### Cluster Extension Development\n\nCreate New Cluster:\n\n\n# Copy template\ncp -r workspace/extensions/clusters/template workspace/extensions/clusters/my-cluster\n\n# Initialize cluster\ncd workspace/extensions/clusters/my-cluster\nnu init.nu --cluster-name my-cluster --cluster-type web-stack\n\n\nTesting Extensions:\n\n\n# Test extension syntax\nnu workspace.nu tools validate-extension providers/my-provider\n\n# Run extension tests\nnu workspace.nu tools test-extension taskservs/my-service\n\n# Integration test with infrastructure\nnu workspace.nu tools deploy-test clusters/my-cluster --infra test-env\n\n\n## Runtime Management\n\n### Runtime Data Organization\n\nPer-User Isolation:\n\n\nruntime/\n├── workspaces/\n│ ├── developer/ # Developer's workspace data\n│ │ ├── current-infra # Current infrastructure context\n│ │ ├── settings.toml # Runtime settings\n│ │ └── extensions/ # Extension runtime data\n│ └── tester/ # Tester's workspace data\n├── cache/\n│ ├── developer/ # Developer's cache\n│ │ ├── providers/ # Provider API cache\n│ │ ├── images/ # Container image cache\n│ │ └── downloads/ # Downloaded artifacts\n│ └── tester/ # Tester's cache\n├── state/\n│ ├── developer/ # Developer's state\n│ │ ├── deployments/ # Deployment state\n│ │ └── workflows/ # Workflow state\n│ └── tester/ # Tester's state\n├── logs/\n│ ├── developer/ # Developer's logs\n│ │ ├── provisioning.log\n│ │ ├── orchestrator.log\n│ │ └── extensions/\n│ └── tester/ # Tester's logs\n└── data/\n ├── developer/ # Developer's data\n │ ├── database.db # Local database\n │ └── backups/ # Local backups\n └── tester/ # Tester's data\n\n\n### Runtime Management Commands\n\nInitialize Runtime Environment:\n\n\n# Initialize for current user\nnu workspace/tools/runtime-manager.nu init\n\n# Initialize for specific user\nnu workspace/tools/runtime-manager.nu init --user-name developer\n\n\nRuntime Cleanup:\n\n\n# Clean cache older than 30 days\nnu workspace/tools/runtime-manager.nu cleanup --type cache --age 30d\n\n# Clean logs with rotation\nnu workspace/tools/runtime-manager.nu cleanup --type logs --rotate\n\n# Clean temporary files\nnu workspace/tools/runtime-manager.nu cleanup --type temp --force\n\n\nLog Management:\n\n\n# View recent logs\nnu workspace/tools/runtime-manager.nu logs --action tail --lines 100\n\n# Follow logs in real-time\nnu workspace/tools/runtime-manager.nu logs --action tail --follow\n\n# Rotate large log files\nnu workspace/tools/runtime-manager.nu logs --action rotate\n\n# Archive old logs\nnu workspace/tools/runtime-manager.nu logs --action archive --older-than 7d\n\n\nCache Management:\n\n\n# Show cache statistics\nnu workspace/tools/runtime-manager.nu cache --action stats\n\n# Optimize cache\nnu workspace/tools/runtime-manager.nu cache --action optimize\n\n# Clear specific cache\nnu workspace/tools/runtime-manager.nu cache --action clear --type providers\n\n# Refresh cache\nnu workspace/tools/runtime-manager.nu cache --action refresh --selective\n\n\nMonitoring:\n\n\n# Monitor runtime usage\nnu workspace/tools/runtime-manager.nu monitor --duration 5m --interval 30s\n\n# Check disk usage\nnu workspace/tools/runtime-manager.nu monitor --type disk\n\n# Monitor active processes\nnu workspace/tools/runtime-manager.nu monitor --type processes --workspace-user developer\n\n\n## Health Monitoring\n\n### Health Check System\n\nThe workspace provides comprehensive health monitoring with automatic repair capabilities.\n\nHealth Check Components:\n\n- Directory Structure: Validates workspace directory integrity\n- Configuration Files: Checks configuration syntax and completeness\n- Runtime Environment: Validates runtime data and permissions\n- Extension Status: Checks extension functionality\n- Resource Usage: Monitors disk space and memory usage\n- Integration Status: Tests integration with core system\n\n### Health Commands\n\nBasic Health Check:\n\n\n# Quick health check\nnu workspace.nu health\n\n# Detailed health check with all components\nnu workspace.nu health --detailed\n\n# Health check with automatic fixes\nnu workspace.nu health --fix-issues\n\n# Export health report\nnu workspace.nu health --report-format json > health-report.json\n\n\nComponent-Specific Health Checks:\n\n\n# Check directory structure\nnu workspace/tools/workspace-health.nu check-directories --workspace-user developer\n\n# Validate configuration files\nnu workspace/tools/workspace-health.nu check-config --workspace-user developer\n\n# Check runtime environment\nnu workspace/tools/workspace-health.nu check-runtime --workspace-user developer\n\n# Test extension functionality\nnu workspace/tools/workspace-health.nu check-extensions --workspace-user developer\n\n\n### Health Monitoring Output\n\nExample Health Report:\n\n\n{\n "workspace_health": {\n "user": "developer",\n "timestamp": "2025-09-25T14:30:22Z",\n "overall_status": "healthy",\n "checks": {\n "directories": {\n "status": "healthy",\n "issues": [],\n "auto_fixed": []\n },\n "configuration": {\n "status": "warning",\n "issues": [\n "User configuration missing default provider"\n ],\n "auto_fixed": [\n "Created missing user configuration file"\n ]\n },\n "runtime": {\n "status": "healthy",\n "disk_usage": "1.2 GB",\n "cache_size": "450 MB",\n "log_size": "120 MB"\n },\n "extensions": {\n "status": "healthy",\n "providers": 2,\n "taskservs": 5,\n "clusters": 1\n }\n },\n "recommendations": [\n "Consider cleaning cache (>400 MB)",\n "Rotate logs (>100 MB)"\n ]\n }\n}\n\n\n### Automatic Fixes\n\nAuto-Fix Capabilities:\n\n- Missing Directories: Creates missing workspace directories\n- Broken Symlinks: Repairs or removes broken symbolic links\n- Configuration Issues: Creates missing configuration files with defaults\n- Permission Problems: Fixes file and directory permissions\n- Corrupted Cache: Clears and rebuilds corrupted cache entries\n- Log Rotation: Rotates large log files automatically\n\n## Backup and Restore\n\n### Backup System\n\nBackup Components:\n\n- Configuration: All workspace configuration files\n- Extensions: Custom extensions and templates\n- Runtime Data: User-specific runtime data (optional)\n- Logs: Application logs (optional)\n- Cache: Cache data (optional)\n\n### Backup Commands\n\nCreate Backup:\n\n\n# Basic backup\nnu workspace.nu backup\n\n# Backup with auto-generated name\nnu workspace.nu backup --auto-name\n\n# Comprehensive backup including logs and cache\nnu workspace.nu backup --auto-name --include-logs --include-cache\n\n# Backup specific components\nnu workspace.nu backup --components config,extensions --name my-backup\n\n\nBackup Options:\n\n- --auto-name: Generate timestamp-based backup name\n- --include-logs: Include application logs\n- --include-cache: Include cache data\n- --components: Specify components to backup\n- --compress: Create compressed backup archive\n- --encrypt: Encrypt backup with age/sops\n- --remote: Upload to remote storage (S3, etc.)\n\n### Restore System\n\nList Available Backups:\n\n\n# List all backups\nnu workspace.nu restore --list-backups\n\n# List backups with details\nnu workspace.nu restore --list-backups --detailed\n\n# Show backup contents\nnu workspace.nu restore --show-contents --backup-name workspace-developer-20250925_143022\n\n\nRestore Operations:\n\n\n# Restore latest backup\nnu workspace.nu restore --latest\n\n# Restore specific backup\nnu workspace.nu restore --backup-name workspace-developer-20250925_143022\n\n# Selective restore\nnu workspace.nu restore --selective --backup-name my-backup\n\n# Restore to different user\nnu workspace.nu restore --backup-name my-backup --restore-to different-user\n\n\nAdvanced Restore Options:\n\n- --selective: Choose components to restore interactively\n- --restore-to: Restore to different user workspace\n- --merge: Merge with existing workspace (don't overwrite)\n- --dry-run: Show what would be restored without doing it\n- --verify: Verify backup integrity before restore\n\n### Reset and Cleanup\n\nWorkspace Reset:\n\n\n# Reset with backup\nnu workspace.nu reset --backup-first\n\n# Reset keeping configuration\nnu workspace.nu reset --backup-first --keep-config\n\n# Complete reset (dangerous)\nnu workspace.nu reset --force --no-backup\n\n\nCleanup Operations:\n\n\n# Clean old data with dry-run\nnu workspace.nu cleanup --type old --age 14d --dry-run\n\n# Clean cache forcefully\nnu workspace.nu cleanup --type cache --force\n\n# Clean specific user data\nnu workspace.nu cleanup --user-name old-user --type all\n\n\n## Troubleshooting\n\n### Common Issues\n\n#### Workspace Not Found\n\nError: Workspace for user 'developer' not found\n\n\n# Solution: Initialize workspace\nnu workspace.nu init --user-name developer\n\n\n#### Path Resolution Errors\n\nError: Path resolution failed for config/user\n\n\n# Solution: Fix with health check\nnu workspace.nu health --fix-issues\n\n# Manual fix\nnu workspace/lib/path-resolver.nu resolve_path "config" "user" --create-missing\n\n\n#### Configuration Errors\n\nError: Invalid configuration syntax in user.toml\n\n\n# Solution: Validate and fix configuration\nnu workspace.nu config validate --user-name developer\n\n# Reset to defaults\ncp workspace/config/local-overrides.toml.example workspace/config/developer.toml\n\n\n#### Runtime Issues\n\nError: Runtime directory permissions error\n\n\n# Solution: Reinitialize runtime\nnu workspace/tools/runtime-manager.nu init --user-name developer --force\n\n# Fix permissions manually\nchmod -R 755 workspace/runtime/workspaces/developer\n\n\n#### Extension Issues\n\nError: Extension 'my-provider' not found or invalid\n\n\n# Solution: Validate extension\nnu workspace.nu tools validate-extension providers/my-provider\n\n# Reinitialize extension from template\ncp -r workspace/extensions/providers/template workspace/extensions/providers/my-provider\n\n\n### Debug Mode\n\nEnable Debug Logging:\n\n\n# Set debug environment\nexport PROVISIONING_DEBUG=true\nexport PROVISIONING_LOG_LEVEL=debug\nexport PROVISIONING_WORKSPACE_USER=developer\n\n# Run with debug\nnu workspace.nu health --detailed\n\n\n### Performance Issues\n\nSlow Operations:\n\n\n# Check disk space\ndf -h workspace/\n\n# Check runtime data size\ndu -h workspace/runtime/workspaces/developer/\n\n# Optimize workspace\nnu workspace.nu cleanup --type cache\nnu workspace/tools/runtime-manager.nu cache --action optimize\n\n\n### Recovery Procedures\n\nCorrupted Workspace:\n\n\n# 1. Backup current state\nnu workspace.nu backup --name corrupted-backup --force\n\n# 2. Reset workspace\nnu workspace.nu reset --backup-first\n\n# 3. Restore from known good backup\nnu workspace.nu restore --latest-known-good\n\n# 4. Validate health\nnu workspace.nu health --detailed --fix-issues\n\n\nData Loss Prevention:\n\n- Enable automatic backups: backup_interval = "1h" in user config\n- Use version control for custom extensions\n- Regular health checks: nu workspace.nu health\n- Monitor disk space and set up alerts\n\nThis workspace management system provides a robust foundation for development while maintaining isolation and providing comprehensive tools for\nmaintenance and troubleshooting.