14 KiB
14 KiB
\n┌─────────────────────────────────────────────────────────────┐\n│ User Command │\n└────────────────────────────────┬──────────────────────────────┘\n │\n ┌────────────▼─────────────┐\n │ CLI Dispatcher │\n │ (main_provisioning) │\n └────────────┬─────────────┘\n │\n ┌────────────▼─────────────┐\n │ Metadata Loading │\n │ (cached via traits.nu) │\n └────────────┬─────────────┘\n │\n ┌────────────▼─────────────────────┐\n │ Pre-Execution Validation │\n │ - Auth checks │\n │ - Permission validation │\n │ - Operation type mapping │\n └────────────┬─────────────────────┘\n │\n ┌────────────▼─────────────────────┐\n │ Command Handler Execution │\n │ - infrastructure.nu │\n │ - orchestration.nu │\n │ - workspace.nu │\n └────────────┬─────────────────────┘\n │\n ┌────────────▼─────────────┐\n │ Result/Response │\n └─────────────────────────┘\n\n\n### Data Flow\n\n1. User Command → CLI Dispatcher\n2. Dispatcher → Load cached metadata (or parse Nickel)\n3. Validate → Check auth, operation type, permissions\n4. Execute → Call appropriate handler\n5. Return → Result to user\n\n### Metadata Caching\n\n- Location: ~/.cache/provisioning/command_metadata.json\n- Format: Serialized JSON (pre-parsed for speed)\n- TTL: 1 hour (configurable via PROVISIONING_METADATA_TTL)\n- Invalidation: Automatic on main.ncl modification\n- Performance: 40-100x faster than Nickel parsing\n\n## Installation\n\n### Prerequisites\n\n- Nushell 0.109.0+\n- Nickel 1.15.0+\n- SOPS 3.10.2 (for encrypted configs)\n- Age 1.2.1 (for encryption)\n\n### Installation Steps\n\n\n# 1. Clone or update repository\ngit clone https://github.com/your-org/project-provisioning.git\ncd project-provisioning\n\n# 2. Initialize workspace\n./provisioning/core/cli/provisioning workspace init\n\n# 3. Validate system\n./provisioning/core/cli/provisioning validate config\n\n# 4. Run system checks\n./provisioning/core/cli/provisioning health\n\n# 5. Run test suites\nnu tests/test-fase5-e2e.nu\nnu tests/test-security-audit-day20.nu\nnu tests/test-metadata-cache-benchmark.nu\n\n\n## Usage Guide\n\n### Basic Commands\n\n\n# Initialize authentication\nprovisioning login\n\n# Enroll in MFA\nprovisioning mfa totp enroll\n\n# Create infrastructure\nprovisioning server create --name web-01 --plan 1xCPU-2 GB\n\n# Deploy with orchestrator\nprovisioning workflow submit workflows/deployment.ncl --orchestrated\n\n# Batch operations\nprovisioning batch submit workflows/batch-deploy.ncl\n\n# Check without executing\nprovisioning server create --name test --check\n\n\n### Authentication Flow\n\n\n# 1. Login (required for production operations)\n$ provisioning login\nUsername: alice@example.com\nPassword: ****\n\n# 2. Optional: Setup MFA\n$ provisioning mfa totp enroll\nScan QR code with authenticator app\nVerify code: 123456\n\n# 3. Use commands (auth checks happen automatically)\n$ provisioning server delete --name old-server --infra production\nAuth check: Check auth for production (delete operation)\nAre you sure? [yes/no] yes\n✓ Server deleted\n\n# 4. All destructive operations require auth\n$ provisioning taskserv delete postgres web-01\nAuth check: Check auth for destructive operation\n✓ Taskserv deleted\n\n\n### Check Mode (Bypass Auth for Testing)\n\n\n# Dry-run without auth checks\nprovisioning server create --name test --check\n\n# Output: Shows what would happen, no auth checks\nDry-run mode - no changes will be made\n✓ Would create server: test\n✓ Would deploy taskservs: []\n\n\n### Non-Interactive CI/CD Mode\n\n\n# Automated mode - skip confirmations\nprovisioning server create --name web-01 --yes\n\n# Batch operations\nprovisioning batch submit workflows/batch.ncl --yes --check\n\n# With environment variable\nPROVISIONING_NON_INTERACTIVE=1 provisioning server create --name web-02 --yes\n\n\n## Migration Path\n\n### Phase 1: From Old input to Metadata\n\nOld Pattern (Before Fase 5):\n\n\n# Hardcoded auth check\nlet response = (input "Delete server? (yes/no): ")\nif $response != "yes" { exit 1 }\n\n# No metadata - auth unknown\nexport def delete-server [name: string, --yes] {\n if not $yes { ... manual confirmation ... }\n # ... deletion logic ...\n}\n\n\nNew Pattern (After Fase 5):\n\n\n# Metadata header\n# [command]\n# name = "server delete"\n# group = "infrastructure"\n# tags = ["server", "delete", "destructive"]\n# version = "1.0.0"\n\n# Automatic auth check from metadata\nexport def delete-server [name: string, --yes] {\n # Pre-execution check happens in dispatcher\n # Auth enforcement via metadata\n # Operation type: "delete" automatically detected\n # ... deletion logic ...\n}\n\n\n### Phase 2: Adding Metadata Headers\n\nFor each script that was migrated:\n\n1. Add metadata header after shebang:\n\n\n#!/usr/bin/env nu\n# [command]\n# name = "server create"\n# group = "infrastructure"\n# tags = ["server", "create", "interactive"]\n# version = "1.0.0"\n\nexport def create-server [name: string] {\n # Logic here\n}\n\n\n1. Register in provisioning/schemas/main.ncl:\n\n\nlet server_create = {\n name = "server create",\n domain = "infrastructure",\n description = "Create a new server",\n requirements = {\n interactive = false,\n requires_auth = true,\n auth_type = "jwt",\n side_effect_type = "create",\n min_permission = "write",\n },\n} in\nserver_create\n\n\n1. Handler integration (happens in dispatcher):\n\n\n# Dispatcher automatically:\n# 1. Loads metadata for "server create"\n# 2. Validates auth based on requirements\n# 3. Checks permission levels\n# 4. Calls handler if validation passes\n\n\n### Phase 3: Validating Migration\n\n\n# Validate metadata headers\nnu utils/validate-metadata-headers.nu\n\n# Find scripts by tag\nnu utils/search-scripts.nu by-tag destructive\n\n# Find all scripts in group\nnu utils/search-scripts.nu by-group infrastructure\n\n# Find scripts with multiple tags\nnu utils/search-scripts.nu by-tags server delete\n\n# List all migrated scripts\nnu utils/search-scripts.nu list\n\n\n## Developer Guide\n\n### Adding New Commands with Metadata\n\nStep 1: Create metadata in main.ncl\n\n\nlet new_feature_command = {\n name = "feature command",\n domain = "infrastructure",\n description = "My new feature",\n requirements = {\n interactive = false,\n requires_auth = true,\n auth_type = "jwt",\n side_effect_type = "create",\n min_permission = "write",\n },\n} in\nnew_feature_command\n\n\nStep 2: Add metadata header to script\n\n\n#!/usr/bin/env nu\n# [command]\n# name = "feature command"\n# group = "infrastructure"\n# tags = ["feature", "create"]\n# version = "1.0.0"\n\nexport def feature-command [param: string] {\n # Implementation\n}\n\n\nStep 3: Implement handler function\n\n\n# Handler registered in dispatcher\nexport def handle-feature-command [\n action: string\n --flags\n]: nothing -> nothing {\n # Dispatcher handles:\n # 1. Metadata validation\n # 2. Auth checks\n # 3. Permission validation\n\n # Your logic here\n}\n\n\nStep 4: Test with check mode\n\n\n# Dry-run without auth\nprovisioning feature command --check\n\n# Full execution\nprovisioning feature command --yes\n\n\n### Metadata Field Reference\n\n| Field | Type | Required | Description |\n| ------- | ------ | ---------- | ------------- |\n| name | string | Yes | Command canonical name |\n| domain | string | Yes | Command category (infrastructure, orchestration, etc.) |\n| description | string | Yes | Human-readable description |\n| requires_auth | bool | Yes | Whether auth is required |\n| auth_type | enum | Yes | "none", "jwt", "mfa", "cedar" |\n| side_effect_type | enum | Yes | "none", "create", "update", "delete", "deploy" |\n| min_permission | enum | Yes | "read", "write", "admin", "superadmin" |\n| interactive | bool | No | Whether command requires user input |\n| slow_operation | bool | No | Whether operation takes >60 seconds |\n\n### Standard Tags\n\nGroups:\n\n- infrastructure - Server, taskserv, cluster operations\n- orchestration - Workflow, batch operations\n- workspace - Workspace management\n- authentication - Auth, MFA, tokens\n- utilities - Helper commands\n\nOperations:\n\n- create, read, update, delete - CRUD operations\n- destructive - Irreversible operations\n- interactive - Requires user input\n\nPerformance:\n\n- slow - Operation >60 seconds\n- optimizable - Candidate for optimization\n\n### Performance Optimization Patterns\n\nPattern 1: For Long Operations\n\n\n# Use orchestrator for operations >2 seconds\nif (get-operation-duration "my-operation") > 2000 {\n submit-to-orchestrator $operation\n return "Operation submitted in background"\n}\n\n\nPattern 2: For Batch Operations\n\n\n# Use batch workflows for multiple operations\nnu -c "\nuse core/nulib/workflows/batch.nu *\nbatch submit workflows/batch-deploy.ncl --parallel-limit 5\n"\n\n\nPattern 3: For Metadata Overhead\n\n\n# Cache hit rate optimization\n# Current: 40-100x faster with warm cache\n# Target: >95% cache hit rate\n# Achieved: Metadata stays in cache for 1 hour (TTL)\n\n\n## Testing\n\n### Running Tests\n\n\n# End-to-End Integration Tests\nnu tests/test-fase5-e2e.nu\n\n# Security Audit\nnu tests/test-security-audit-day20.nu\n\n# Performance Benchmarks\nnu tests/test-metadata-cache-benchmark.nu\n\n# Run all tests\nfor test in tests/test-*.nu { nu $test }\n\n\n### Test Coverage\n\n| Test Suite | Category | Coverage |\n| ----------- | ---------- | ---------- |\n| E2E Tests | Integration | 7 test groups, 40+ checks |\n| Security Audit | Auth | 5 audit categories, 100% pass |\n| Benchmarks | Performance | 6 benchmark categories |\n\n### Expected Results\n\n✅ All tests pass\n✅ No Nushell syntax violations\n✅ Cache hit rate >95%\n✅ Auth enforcement 100%\n✅ Performance baselines met\n\n## Troubleshooting\n\n### Issue: Command not found\n\nSolution: Ensure metadata is registered in main.ncl\n\n\n# Check if command is in metadata\ngrep "command_name" provisioning/schemas/main.ncl\n\n\n### Issue: Auth check failing\n\nSolution: Verify user has required permission level\n\n\n# Check current user permissions\nprovisioning auth whoami\n\n# Check command requirements\nnu -c "\nuse core/nulib/lib_provisioning/commands/traits.nu *\nget-command-metadata 'server create'\n"\n\n\n### Issue: Slow command execution\n\nSolution: Check cache status\n\n\n# Force cache reload\nrm ~/.cache/provisioning/command_metadata.json\n\n# Check cache hit rate\nnu tests/test-metadata-cache-benchmark.nu\n\n\n### Issue: Nushell syntax error\n\nSolution: Run compliance check\n\n\n# Validate Nushell compliance\nnu --ide-check 100 <file.nu>\n\n# Check for common issues\ngrep "try {" <file.nu> # Should be empty\ngrep "let mut" <file.nu> # Should be empty\n\n\n## Performance Characteristics\n\n### Baseline Metrics\n\n| Operation | Cold | Warm | Improvement |\n| ----------- | ------ | ------ | ------------- |\n| Metadata Load | 200 ms | 2-5 ms | 40-100x |\n| Auth Check | <5 ms | <5 ms | Same |\n| Command Dispatch | <10 ms | <10 ms | Same |\n| Total Command | ~210 ms | ~10 ms | 21x |\n\n### Real-World Impact\n\n\nScenario: 20 sequential commands\n Without cache: 20 × 200 ms = 4 seconds\n With cache: 1 × 200 ms + 19 × 5 ms = 295 ms\n Speedup: ~13.5x faster\n\n\n## Next Steps\n\n1. Deploy: Use installer to deploy to production\n2. Monitor: Watch cache hit rates (target >95%)\n3. Extend: Add new commands following migration pattern\n4. Optimize: Use profiling to identify slow operations\n5. Maintain: Run validation scripts regularly\n\n---\n\nFor Support: See docs/troubleshooting-guide.md\nFor Architecture: See docs/architecture/\nFor User Guide: See docs/user/AUTHENTICATION_LAYER_GUIDE.md