README.md
1 # Scripts Reference 2 3 Comprehensive documentation for all 53 automation scripts in the Radicle infrastructure. 4 5 --- 6 7 ## 📚 Quick Navigation 8 9 | Category | Scripts | Description | 10 |----------|---------|-------------| 11 | [🔄 Workflow](#-workflow) | 10 scripts | Radicle workflow automation (patches, sync) | 12 | [📊 Monitoring](#-monitoring) | 11 scripts | Health checks, metrics, DORA tracking | 13 | [🔒 Security](#-security) | 6 scripts | Vulnerability scanning, key backup | 14 | [⚙️ Setup](#️-setup) | 11 scripts | Installation, configuration, deployment | 15 | [🚀 CI/CD](#-cicd) | 3 scripts | Continuous integration setup | 16 | [🧪 Testing](#-testing) | 3 scripts | Test suites and validation | 17 | [🎯 Onboarding](#-onboarding) | 3 scripts | Developer onboarding and mesh joining | 18 | [🤖 Automation](#-automation) | 2 scripts | Deployment automation and mesh monitoring | 19 | [💾 Backup](#-backup) | 1 script | Seed data backup | 20 | [⚡ CLI](#-cli) | 1 script | Enhanced Radicle CLI wrapper | 21 | [🔧 Config](#-config) | 1 script | Configuration optimization | 22 | [🔌 Integration](#-integration) | 1 script | API wrappers | 23 24 **Total**: 53 shell scripts 25 26 --- 27 28 ## 🎯 Getting Started 29 30 ### Quick Usage 31 32 Most scripts follow standard conventions: 33 34 ```bash 35 # Get help 36 ./script-name.sh --help 37 38 # Run with options 39 ./script-name.sh [options] [arguments] 40 41 # Example 42 ./scripts/workflow/sync-status.sh 43 ./scripts/monitoring/health-check.sh 44 ./scripts/security/run-trivy.sh filesystem . 45 ``` 46 47 ### Prerequisites 48 49 All scripts require: 50 - **bash** (4.0+) 51 - **Radicle CLI** (`rad`) 52 - **macOS** (primary support) 53 54 Additional dependencies documented per script below. 55 56 ### Common Patterns 57 58 All scripts follow these standards: 59 - ✅ Shebang: `#!/bin/bash` 60 - ✅ Error handling: `set -euo pipefail` 61 - ✅ Usage documentation in header 62 - ✅ Color-coded output 63 - ✅ Exit codes: 0 (success), 1+ (error) 64 65 --- 66 67 ## 🔄 Workflow 68 69 Radicle patch-based workflow automation scripts. 70 71 ### Core Workflow Scripts 72 73 #### `create-patch.sh` ⭐⭐⭐ 74 Create a new patch from current branch. 75 76 **Usage:** 77 ```bash 78 ./scripts/workflow/create-patch.sh "Fix: description" 79 ``` 80 81 **Dependencies:** `rad` 82 83 **Example:** 84 ```bash 85 git checkout -b feature/my-feature 86 # ... make changes ... 87 ./scripts/workflow/create-patch.sh "feat: Add new feature" 88 ``` 89 90 --- 91 92 #### `update-patch.sh` ⭐⭐ 93 Update an existing patch with new changes. 94 95 **Usage:** 96 ```bash 97 ./scripts/workflow/update-patch.sh [patch-id] "Update: description" 98 ``` 99 100 **Dependencies:** `rad` 101 102 **Example:** 103 ```bash 104 # Make additional changes 105 git add . 106 git commit -m "address: Review feedback" 107 ./scripts/workflow/update-patch.sh --latest "Updated based on review" 108 ``` 109 110 --- 111 112 #### `merge-patch.sh` ⭐⭐ 113 Merge an approved patch into main branch. 114 115 **Usage:** 116 ```bash 117 ./scripts/workflow/merge-patch.sh <patch-id> 118 ``` 119 120 **Dependencies:** `rad`, `git` 121 122 **Example:** 123 ```bash 124 ./scripts/workflow/merge-patch.sh abc123 125 ``` 126 127 --- 128 129 #### `list-patches.sh` ⭐ 130 List all patches for the current repository. 131 132 **Usage:** 133 ```bash 134 ./scripts/workflow/list-patches.sh [--open|--merged|--all] 135 ``` 136 137 **Dependencies:** `rad` 138 139 **Options:** 140 - `--open` - Show only open patches (default) 141 - `--merged` - Show only merged patches 142 - `--all` - Show all patches 143 144 --- 145 146 #### `review-patch.sh` 147 Review a patch and add comments. 148 149 **Usage:** 150 ```bash 151 ./scripts/workflow/review-patch.sh <patch-id> 152 ``` 153 154 **Dependencies:** `rad` 155 156 --- 157 158 #### `push-patch.sh` 159 Push patch to remote seeds. 160 161 **Usage:** 162 ```bash 163 ./scripts/workflow/push-patch.sh <patch-id> 164 ``` 165 166 **Dependencies:** `rad` 167 168 --- 169 170 #### `sync-status.sh` ⭐⭐⭐ 171 Check synchronization status with seeds. 172 173 **Usage:** 174 ```bash 175 ./scripts/workflow/sync-status.sh [--verbose] 176 ``` 177 178 **Dependencies:** `rad` 179 180 **Example Output:** 181 ``` 182 Repository Sync Status 183 ───────────────────── 184 ✓ macstudio: Synced (2 seconds ago) 185 ✓ macbook2: Synced (5 seconds ago) 186 ⚠ laptop: Behind (1 commit) 187 ``` 188 189 --- 190 191 #### `ci-status.sh` 192 Check CI job status for patches. 193 194 **Usage:** 195 ```bash 196 ./scripts/workflow/ci-status.sh [patch-id] 197 ``` 198 199 **Dependencies:** CI/CD system 200 201 --- 202 203 #### `clean-branches.sh` 204 Clean up merged/stale branches. 205 206 **Usage:** 207 ```bash 208 ./scripts/workflow/clean-branches.sh [--dry-run] 209 ``` 210 211 **Dependencies:** `git` 212 213 **Options:** 214 - `--dry-run` - Show what would be deleted without deleting 215 216 --- 217 218 ## 📊 Monitoring 219 220 Health checks, metrics collection, and DORA tracking. 221 222 ### Health Monitoring 223 224 #### `health-check.sh` ⭐⭐⭐ 225 Comprehensive infrastructure health check. 226 227 **Usage:** 228 ```bash 229 ./scripts/monitoring/health-check.sh [--format json|text] 230 ``` 231 232 **Dependencies:** `rad`, `curl`, `nc` 233 234 **Checks:** 235 - Radicle node status 236 - Package registries (Verdaccio, devpi, Docker) 237 - Monitoring services (Prometheus, Grafana) 238 - Disk space and system resources 239 240 **Example:** 241 ```bash 242 # Human-readable output 243 ./scripts/monitoring/health-check.sh 244 245 # JSON output for automation 246 ./scripts/monitoring/health-check.sh --format json 247 ``` 248 249 --- 250 251 #### `simple-health-check.sh` 252 Quick health check for essential services. 253 254 **Usage:** 255 ```bash 256 ./scripts/monitoring/simple-health-check.sh 257 ``` 258 259 **Dependencies:** `rad`, `curl` 260 261 **Checks:** Radicle node, registries (basic) 262 263 --- 264 265 #### `daily-health-check.sh` ⭐ 266 Daily automated health check with notifications. 267 268 **Usage:** 269 ```bash 270 ./scripts/monitoring/daily-health-check.sh 271 ``` 272 273 **Dependencies:** `health-check.sh`, Telegram notifications 274 275 **Schedule:** Runs automatically via cron (8:00 AM) 276 277 --- 278 279 #### `setup-daily-health-cron.sh` 280 Install daily health check cron job. 281 282 **Usage:** 283 ```bash 284 ./scripts/monitoring/setup-daily-health-cron.sh 285 ``` 286 287 **Dependencies:** `cron` or `launchd` 288 289 --- 290 291 ### Node Monitoring 292 293 #### `node-health.sh` 294 Monitor Radicle node health and connectivity. 295 296 **Usage:** 297 ```bash 298 ./scripts/monitoring/node-health.sh [--watch] 299 ``` 300 301 **Dependencies:** `rad` 302 303 **Options:** 304 - `--watch` - Continuous monitoring mode 305 306 **Checks:** 307 - Node status and version 308 - Peer connections 309 - Sync status 310 - Resource usage 311 312 --- 313 314 #### `monitor-seeds.sh` 315 Monitor all configured seed nodes. 316 317 **Usage:** 318 ```bash 319 ./scripts/monitoring/monitor-seeds.sh [--interval seconds] 320 ``` 321 322 **Dependencies:** `rad`, seed node list 323 324 **Options:** 325 - `--interval N` - Check every N seconds (default: 60) 326 327 --- 328 329 #### `mesh-health-monitor.sh` ⭐ 330 Monitor Tailscale mesh network health. 331 332 **Usage:** 333 ```bash 334 ./scripts/monitoring/mesh-health-monitor.sh [--verbose] 335 ``` 336 337 **Dependencies:** `tailscale`, `rad` 338 339 **Checks:** 340 - Tailscale connectivity 341 - Seed reachability via mesh 342 - Network latency 343 - Sync status across mesh 344 345 --- 346 347 #### `repo-health.sh` 348 Monitor repository health metrics. 349 350 **Usage:** 351 ```bash 352 ./scripts/monitoring/repo-health.sh [repo-id] 353 ``` 354 355 **Dependencies:** `rad`, `git` 356 357 **Metrics:** 358 - Repository size 359 - Commit activity 360 - Patch activity 361 - Sync status 362 363 --- 364 365 ### Metrics Collection 366 367 #### `dora-metrics.sh` ⭐⭐⭐ 368 Calculate DORA metrics for the infrastructure. 369 370 **Usage:** 371 ```bash 372 ./scripts/monitoring/dora-metrics.sh [--days N] [--format json|text] 373 ``` 374 375 **Dependencies:** `git`, CI logs, incident logs 376 377 **Metrics:** 378 - Deployment Frequency 379 - Lead Time for Changes 380 - Time to Restore Service 381 - Change Failure Rate 382 - Overall DORA Score 383 384 **Example:** 385 ```bash 386 # Last 30 days 387 ./scripts/monitoring/dora-metrics.sh --days 30 388 389 # JSON for Prometheus 390 ./scripts/monitoring/dora-metrics.sh --format json 391 ``` 392 393 **Current Performance:** Elite 4.0/4.0 394 395 --- 396 397 #### `ci-metrics.sh` 398 Collect CI/CD pipeline metrics. 399 400 **Usage:** 401 ```bash 402 ./scripts/monitoring/ci-metrics.sh [--since date] 403 ``` 404 405 **Dependencies:** CI logs 406 407 **Metrics:** 408 - Job success rate 409 - Average execution time 410 - Queue depth 411 - Failure patterns 412 413 --- 414 415 #### `security-metrics.sh` ⭐⭐ 416 Display security scan results and trends. 417 418 **Usage:** 419 ```bash 420 ./scripts/monitoring/security-metrics.sh [--days N] [--json] 421 ``` 422 423 **Dependencies:** Trivy, Semgrep scan reports 424 425 **Options:** 426 - `--days N` - Show last N days (default: 30) 427 - `--json` - Output as JSON 428 429 **Displays:** 430 - Vulnerability counts (Critical/High/Medium/Low) 431 - Security health score 432 - Scan trends 433 - Recent findings 434 435 --- 436 437 #### `prometheus-exporter.sh` ⭐⭐ 438 Export custom metrics to Prometheus. 439 440 **Usage:** 441 ```bash 442 ./scripts/monitoring/prometheus-exporter.sh [--port N] 443 ``` 444 445 **Dependencies:** `prometheus`, Python or simple HTTP server 446 447 **Metrics Exported:** 448 - Infrastructure health 449 - DORA metrics 450 - Security posture 451 - Service status 452 453 **Port:** 8000 (default) 454 455 **Auto-start:** Yes (launchd) 456 457 --- 458 459 ## 🔒 Security 460 461 Vulnerability scanning, security checks, and key management. 462 463 ### Vulnerability Scanning 464 465 #### `run-trivy.sh` ⭐⭐⭐ 466 Run Trivy vulnerability scanner. 467 468 **Usage:** 469 ```bash 470 ./scripts/security/run-trivy.sh [options] [path] 471 ``` 472 473 **Dependencies:** `trivy` 474 475 **Options:** 476 - `--fs` - Scan filesystem/dependencies (default) 477 - `--image` - Scan container image 478 - `--severity CRITICAL,HIGH` - Filter by severity 479 - `--format json` - Output as JSON 480 481 **Examples:** 482 ```bash 483 # Scan current directory 484 ./scripts/security/run-trivy.sh filesystem . 485 486 # Scan Docker image 487 ./scripts/security/run-trivy.sh --image localhost:5000/my-image 488 489 # Only critical vulnerabilities 490 ./scripts/security/run-trivy.sh --severity CRITICAL filesystem . 491 ``` 492 493 --- 494 495 #### `run-semgrep.sh` ⭐⭐⭐ 496 Run Semgrep SAST scanner. 497 498 **Usage:** 499 ```bash 500 ./scripts/security/run-semgrep.sh [options] 501 ``` 502 503 **Dependencies:** `semgrep` 504 505 **Options:** 506 - `--severity ERROR` - Only show errors 507 - `--config auto` - Auto-detect rulesets 508 - `--json` - Output as JSON 509 510 **Examples:** 511 ```bash 512 # Full scan 513 ./scripts/security/run-semgrep.sh 514 515 # Only errors 516 ./scripts/security/run-semgrep.sh --severity ERROR 517 518 # Custom config 519 ./scripts/security/run-semgrep.sh --config p/owasp-top-ten 520 ``` 521 522 --- 523 524 #### `scheduled-scan.sh` ⭐⭐ 525 Run daily security scans (Trivy + Semgrep). 526 527 **Usage:** 528 ```bash 529 ./scripts/security/scheduled-scan.sh 530 ``` 531 532 **Dependencies:** `run-trivy.sh`, `run-semgrep.sh` 533 534 **Schedule:** Runs automatically at 2:00 AM daily (launchd) 535 536 **Output:** `~/radicle-ci/security-reports/YYYY-MM-DD-scan.txt` 537 538 --- 539 540 #### `weekly-security-summary.sh` 541 Generate weekly security summary report. 542 543 **Usage:** 544 ```bash 545 ./scripts/security/weekly-security-summary.sh 546 ``` 547 548 **Dependencies:** Security scan reports 549 550 **Output:** Email or Slack summary of week's security findings 551 552 --- 553 554 ### Security Checks 555 556 #### `mesh-security-check.sh` ⭐ 557 Validate security of Tailscale mesh network. 558 559 **Usage:** 560 ```bash 561 ./scripts/security/mesh-security-check.sh [--verbose] 562 ``` 563 564 **Dependencies:** `tailscale`, `rad` 565 566 **Checks:** 567 - Tailscale ACLs 568 - MagicDNS configuration 569 - Key expiry 570 - Unauthorized devices 571 - Firewall rules 572 573 --- 574 575 #### `backup-keys.sh` 576 Backup Radicle keys and identity. 577 578 **Usage:** 579 ```bash 580 ./scripts/security/backup-keys.sh [--destination path] 581 ``` 582 583 **Dependencies:** `rad`, encryption tools 584 585 **Backs up:** 586 - Radicle identity (`~/.radicle/keys`) 587 - Node configuration 588 - SSH keys (optional) 589 590 **Encryption:** AES-256 591 592 --- 593 594 ## ⚙️ Setup 595 596 Installation, configuration, and initial setup scripts. 597 598 ### Installation 599 600 #### `install-radicle.sh` ⭐⭐⭐ 601 Install Radicle CLI and dependencies. 602 603 **Usage:** 604 ```bash 605 ./scripts/setup/install-radicle.sh [--version X.Y.Z] 606 ``` 607 608 **Dependencies:** `brew` (macOS) 609 610 **Installs:** 611 - Radicle CLI 612 - Git (if not present) 613 - Required system libraries 614 615 **Platforms:** macOS (primary), Linux (limited) 616 617 --- 618 619 #### `configure-node.sh` ⭐⭐ 620 Configure Radicle node settings. 621 622 **Usage:** 623 ```bash 624 ./scripts/setup/configure-node.sh [--listen ADDRESS:PORT] 625 ``` 626 627 **Dependencies:** `rad` 628 629 **Configures:** 630 - Node listen address 631 - Peer discovery 632 - Storage settings 633 - Logging 634 635 --- 636 637 #### `create-identity.sh` ⭐⭐ 638 Create new Radicle identity. 639 640 **Usage:** 641 ```bash 642 ./scripts/setup/create-identity.sh [--name "Your Name"] 643 ``` 644 645 **Dependencies:** `rad` 646 647 **Interactive:** Prompts for name, email if not provided 648 649 --- 650 651 ### Repository Setup 652 653 #### `init-repository.sh` 654 Initialize a new Radicle repository. 655 656 **Usage:** 657 ```bash 658 ./scripts/setup/init-repository.sh [--name repo-name] [--description "..."] 659 ``` 660 661 **Dependencies:** `rad`, `git` 662 663 **Steps:** 664 1. Initialize git repository (if needed) 665 2. Initialize Radicle tracking 666 3. Configure default branch 667 4. Add initial commit 668 669 --- 670 671 ### Seed Node Setup 672 673 #### `deploy-seed.sh` ⭐⭐ 674 Deploy a new seed node. 675 676 **Usage:** 677 ```bash 678 ./scripts/setup/deploy-seed.sh [--listen 0.0.0.0:8776] 679 ``` 680 681 **Dependencies:** `rad`, system services 682 683 **Configures:** 684 - Radicle node as seed 685 - Auto-start via launchd 686 - Firewall rules (if needed) 687 - Monitoring 688 689 --- 690 691 #### `setup-macbook-seed.sh` ⭐ 692 Set up MacBook as seed node (Tailscale mesh). 693 694 **Usage:** 695 ```bash 696 ./scripts/setup/setup-macbook-seed.sh 697 ``` 698 699 **Dependencies:** `tailscale`, `rad` 700 701 **Steps:** 702 1. Install/configure Radicle 703 2. Set up Tailscale 704 3. Configure seed node 705 4. Test connectivity 706 707 **See also:** [MacBook Seed Setup Guide](../docs/setup/macbook-seed-setup.md) 708 709 --- 710 711 #### `fix-macbook2-connectivity.sh` 712 Fix connectivity issues on macbook2. 713 714 **Usage:** 715 ```bash 716 ./scripts/setup/fix-macbook2-connectivity.sh 717 ``` 718 719 **Dependencies:** `rad`, `tailscale` 720 721 **Fixes:** 722 - Seed connectivity 723 - Tailscale routing 724 - DNS resolution 725 - Sync issues 726 727 --- 728 729 #### `macbook2-diagnostic.sh` 730 Diagnose macbook2 connectivity issues. 731 732 **Usage:** 733 ```bash 734 ./scripts/setup/macbook2-diagnostic.sh 735 ``` 736 737 **Dependencies:** `rad`, `tailscale`, `dig`, `nc` 738 739 **Checks:** 740 - Radicle node status 741 - Tailscale status 742 - Network connectivity 743 - DNS resolution 744 - Seed reachability 745 746 --- 747 748 #### `test-connectivity.sh` 749 Test connectivity to seeds and peers. 750 751 **Usage:** 752 ```bash 753 ./scripts/setup/test-connectivity.sh [--seed SEED_ID] 754 ``` 755 756 **Dependencies:** `rad`, `nc` 757 758 **Tests:** 759 - Seed reachability 760 - Port availability 761 - Sync capability 762 - Network latency 763 764 --- 765 766 ### Pre-commit Hooks 767 768 #### `install-pre-commit-hook.sh` 769 Install Git pre-commit hook for validation. 770 771 **Usage:** 772 ```bash 773 ./scripts/setup/install-pre-commit-hook.sh 774 ``` 775 776 **Dependencies:** `git` 777 778 **Hook Checks:** 779 - Bash syntax validation 780 - Shellcheck linting (if available) 781 - Secret detection 782 - Debug statement detection 783 - File permissions 784 785 --- 786 787 #### `pre-commit-hook-template.sh` 788 Template for pre-commit hook (reference). 789 790 **Usage:** Not executable (template only) 791 792 **See:** `install-pre-commit-hook.sh` for installation 793 794 --- 795 796 ## 🚀 CI/CD 797 798 Continuous integration and deployment setup scripts. 799 800 #### `setup-radicle-ci.sh` ⭐⭐⭐ 801 Set up complete Radicle CI/CD system. 802 803 **Usage:** 804 ```bash 805 ./scripts/ci-cd/setup-radicle-ci.sh 806 ``` 807 808 **Dependencies:** Docker, CI runner 809 810 **Installs:** 811 - CI/CD runner 812 - Docker environment 813 - Notification server 814 - Job scheduler 815 816 **Components:** 817 - Woodpecker CI or custom runner 818 - Telegram notifications 819 - Prometheus metrics 820 - Job history 821 822 **Time:** ~30 minutes 823 824 --- 825 826 #### `configure-ci-project.sh` 827 Configure CI for a specific project. 828 829 **Usage:** 830 ```bash 831 ./scripts/ci-cd/configure-ci-project.sh [--repo REPO_ID] 832 ``` 833 834 **Dependencies:** CI system 835 836 **Configures:** 837 - Project-specific CI jobs 838 - Notification webhooks 839 - Test environments 840 - Deployment pipelines 841 842 --- 843 844 #### `setup-ci-docker.sh` 845 Set up Docker environment for CI. 846 847 **Usage:** 848 ```bash 849 ./scripts/ci-cd/setup-ci-docker.sh 850 ``` 851 852 **Dependencies:** Docker 853 854 **Sets up:** 855 - Docker network 856 - CI containers 857 - Volume mounts 858 - Registry access 859 860 --- 861 862 ## 🧪 Testing 863 864 Test suites and validation scripts. 865 866 #### `test-suite.sh` ⭐⭐ 867 Comprehensive test suite for infrastructure. 868 869 **Usage:** 870 ```bash 871 ./scripts/testing/test-suite.sh [category] [--verbose] 872 ``` 873 874 **Dependencies:** Various (per test) 875 876 **Test Categories:** 877 - `unit` - Unit tests 878 - `integration` - Integration tests 879 - `e2e` - End-to-end tests 880 - `all` - All tests (default) 881 882 **Example:** 883 ```bash 884 # Run all tests 885 ./scripts/testing/test-suite.sh 886 887 # Run only integration tests 888 ./scripts/testing/test-suite.sh integration 889 890 # Verbose output 891 ./scripts/testing/test-suite.sh --verbose 892 ``` 893 894 --- 895 896 #### `ci-validation-test.sh` 897 Validate CI/CD pipeline configuration. 898 899 **Usage:** 900 ```bash 901 ./scripts/testing/ci-validation-test.sh 902 ``` 903 904 **Dependencies:** CI system 905 906 **Validates:** 907 - Pipeline syntax 908 - Job dependencies 909 - Environment variables 910 - Notification configuration 911 912 --- 913 914 #### `failing-test.sh` 915 Intentionally failing test (for CI testing). 916 917 **Usage:** 918 ```bash 919 ./scripts/testing/failing-test.sh 920 ``` 921 922 **Dependencies:** None 923 924 **Purpose:** Test CI failure detection and notifications 925 926 --- 927 928 ## 🎯 Onboarding 929 930 Developer onboarding and mesh network joining. 931 932 #### `developer-onboarding.sh` ⭐⭐ 933 Complete developer onboarding script. 934 935 **Usage:** 936 ```bash 937 ./scripts/onboarding/developer-onboarding.sh 938 ``` 939 940 **Dependencies:** `rad`, `git`, `tailscale` 941 942 **Steps:** 943 1. Install Radicle CLI 944 2. Create identity 945 3. Join Tailscale mesh (if applicable) 946 4. Connect to seeds 947 5. Clone first repository 948 6. Configure tools 949 950 **Interactive:** Guides user through each step 951 952 **Time:** ~15 minutes 953 954 --- 955 956 #### `join-mesh.sh` ⭐ 957 Join Tailscale mesh network. 958 959 **Usage:** 960 ```bash 961 ./scripts/onboarding/join-mesh.sh [--key AUTH_KEY] 962 ``` 963 964 **Dependencies:** `tailscale` 965 966 **Steps:** 967 1. Install Tailscale (if needed) 968 2. Authenticate 969 3. Configure routing 970 4. Verify connectivity 971 972 --- 973 974 #### `verify-mesh-connection.sh` 975 Verify mesh network connectivity. 976 977 **Usage:** 978 ```bash 979 ./scripts/onboarding/verify-mesh-connection.sh 980 ``` 981 982 **Dependencies:** `tailscale`, `rad` 983 984 **Verifies:** 985 - Tailscale connection 986 - Seed reachability 987 - DNS resolution 988 - Sync capability 989 990 --- 991 992 ## 🤖 Automation 993 994 Deployment automation and mesh monitoring. 995 996 #### `deploy-automation.sh` ⭐⭐ 997 Automated deployment with rollback. 998 999 **Usage:** 1000 ```bash 1001 ./scripts/automation/deploy-automation.sh [environment] [options] 1002 ``` 1003 1004 **Dependencies:** Various (per deployment) 1005 1006 **Environments:** 1007 - `development` 1008 - `staging` 1009 - `production` 1010 1011 **Features:** 1012 - Health checks 1013 - Automatic rollback on failure 1014 - Notifications 1015 - Deployment history 1016 1017 **Example:** 1018 ```bash 1019 # Deploy to production 1020 ./scripts/automation/deploy-automation.sh production 1021 1022 # Deploy with specific version 1023 ./scripts/automation/deploy-automation.sh production --version v2.0.0 1024 1025 # Dry run 1026 ./scripts/automation/deploy-automation.sh production --dry-run 1027 ``` 1028 1029 --- 1030 1031 #### `setup-mesh-monitoring.sh` 1032 Set up automated mesh network monitoring. 1033 1034 **Usage:** 1035 ```bash 1036 ./scripts/automation/setup-mesh-monitoring.sh 1037 ``` 1038 1039 **Dependencies:** `cron` or `launchd`, monitoring scripts 1040 1041 **Sets up:** 1042 - Periodic mesh health checks 1043 - Alert notifications 1044 - Metrics collection 1045 - Dashboard updates 1046 1047 --- 1048 1049 ## 💾 Backup 1050 1051 Data backup and recovery scripts. 1052 1053 #### `backup-seed.sh` ⭐⭐ 1054 Backup seed node data. 1055 1056 **Usage:** 1057 ```bash 1058 ./scripts/backup/backup-seed.sh [--destination PATH] 1059 ``` 1060 1061 **Dependencies:** `tar`, `gzip` 1062 1063 **Backs up:** 1064 - Repository data 1065 - Node configuration 1066 - Identity keys 1067 - Metadata 1068 1069 **Schedule:** Can be automated via cron/launchd 1070 1071 **See also:** [Disaster Recovery Guide](../docs/operations/disaster-recovery.md) 1072 1073 --- 1074 1075 ## ⚡ CLI 1076 1077 Enhanced CLI wrappers. 1078 1079 #### `rad-cli.sh` 1080 Enhanced Radicle CLI wrapper with shortcuts. 1081 1082 **Usage:** 1083 ```bash 1084 ./scripts/cli/rad-cli.sh [command] [options] 1085 ``` 1086 1087 **Dependencies:** `rad` 1088 1089 **Enhancements:** 1090 - Command aliases 1091 - Auto-completion 1092 - Output formatting 1093 - Common workflows 1094 1095 **Example:** 1096 ```bash 1097 # Shortcut for sync status 1098 ./scripts/cli/rad-cli.sh status 1099 1100 # Shortcut for creating patch 1101 ./scripts/cli/rad-cli.sh patch "Fix: description" 1102 ``` 1103 1104 --- 1105 1106 ## 🔧 Config 1107 1108 Configuration management. 1109 1110 #### `config-optimizer.sh` 1111 Optimize Radicle and system configuration. 1112 1113 **Usage:** 1114 ```bash 1115 ./scripts/config/config-optimizer.sh [--profile PROFILE] 1116 ``` 1117 1118 **Dependencies:** System utilities 1119 1120 **Profiles:** 1121 - `development` - Development machine 1122 - `seed` - Seed node 1123 - `ci` - CI/CD machine 1124 1125 **Optimizes:** 1126 - Resource allocation 1127 - Network settings 1128 - Storage configuration 1129 - Logging levels 1130 1131 --- 1132 1133 ## 🔌 Integration 1134 1135 API wrappers and integrations. 1136 1137 #### `radicle-api-wrapper.sh` 1138 API wrapper for Radicle operations. 1139 1140 **Usage:** 1141 ```bash 1142 ./scripts/integration/radicle-api-wrapper.sh [endpoint] [method] [data] 1143 ``` 1144 1145 **Dependencies:** `curl`, `jq` 1146 1147 **Endpoints:** 1148 - `repos` - Repository operations 1149 - `patches` - Patch operations 1150 - `issues` - Issue operations 1151 - `identities` - Identity operations 1152 1153 **Example:** 1154 ```bash 1155 # List repositories 1156 ./scripts/integration/radicle-api-wrapper.sh repos GET 1157 1158 # Get patch details 1159 ./scripts/integration/radicle-api-wrapper.sh patches/<id> GET 1160 ``` 1161 1162 --- 1163 1164 ## 📋 Script Dependencies 1165 1166 ### System Requirements 1167 1168 All scripts require: 1169 - **Operating System**: macOS 13+ (Ventura or later) or Linux 1170 - **Shell**: bash 4.0+ 1171 - **Radicle CLI**: Latest version (`brew install radicle`) 1172 - **Git**: 2.30+ 1173 1174 ### Optional Dependencies 1175 1176 Install as needed: 1177 1178 **Security:** 1179 ```bash 1180 brew install trivy semgrep 1181 ``` 1182 1183 **Monitoring:** 1184 ```bash 1185 brew install prometheus grafana 1186 ``` 1187 1188 **Networking:** 1189 ```bash 1190 brew install tailscale 1191 ``` 1192 1193 **Development:** 1194 ```bash 1195 brew install shellcheck jq 1196 ``` 1197 1198 --- 1199 1200 ## 🎯 Common Workflows 1201 1202 ### Daily Development 1203 1204 ```bash 1205 # 1. Check sync status 1206 ./scripts/workflow/sync-status.sh 1207 1208 # 2. Create feature branch and work 1209 git checkout -b feature/my-feature 1210 # ... make changes ... 1211 1212 # 3. Create patch 1213 ./scripts/workflow/create-patch.sh "feat: Add new feature" 1214 1215 # 4. Check health 1216 ./scripts/monitoring/health-check.sh 1217 ``` 1218 1219 ### Weekly Maintenance 1220 1221 ```bash 1222 # 1. Run security scans 1223 ./scripts/security/run-trivy.sh filesystem . 1224 ./scripts/security/run-semgrep.sh 1225 1226 # 2. Check metrics 1227 ./scripts/monitoring/dora-metrics.sh --days 7 1228 ./scripts/monitoring/security-metrics.sh --days 7 1229 1230 # 3. Clean up 1231 ./scripts/workflow/clean-branches.sh --dry-run 1232 ``` 1233 1234 ### New Developer Onboarding 1235 1236 ```bash 1237 # 1. Run onboarding script 1238 ./scripts/onboarding/developer-onboarding.sh 1239 1240 # 2. Verify setup 1241 ./scripts/monitoring/health-check.sh 1242 ./scripts/workflow/sync-status.sh 1243 ``` 1244 1245 --- 1246 1247 ## 🔍 Finding Scripts 1248 1249 ### By Function 1250 1251 **Want to...** 1252 - **Create a patch**: `workflow/create-patch.sh` 1253 - **Check system health**: `monitoring/health-check.sh` 1254 - **Run security scan**: `security/run-trivy.sh`, `security/run-semgrep.sh` 1255 - **Set up new seed**: `setup/deploy-seed.sh` 1256 - **Join mesh network**: `onboarding/join-mesh.sh` 1257 - **View metrics**: `monitoring/dora-metrics.sh` 1258 - **Back up data**: `backup/backup-seed.sh` 1259 1260 ### By Automation Level 1261 1262 **Manual (run as needed):** 1263 - Most workflow scripts 1264 - Testing scripts 1265 - Setup scripts 1266 1267 **Automated (scheduled):** 1268 - `security/scheduled-scan.sh` - Daily (2:00 AM) 1269 - `monitoring/daily-health-check.sh` - Daily (8:00 AM) 1270 - Registry backups - Daily (2:00 AM) via launchd 1271 1272 --- 1273 1274 ## 💡 Best Practices 1275 1276 ### Running Scripts 1277 1278 1. **Always check help first**: `./script.sh --help` 1279 2. **Use dry-run when available**: `./script.sh --dry-run` 1280 3. **Check exit codes**: `echo $?` after execution 1281 4. **Review output**: Scripts use color coding for clarity 1282 5. **Test in development first**: Before running in production 1283 1284 ### Writing Scripts 1285 1286 If you create new scripts, follow these conventions: 1287 1288 ```bash 1289 #!/bin/bash 1290 # 1291 # Script Name - Brief description 1292 # Usage: ./script-name.sh [options] [arguments] 1293 # 1294 # Options: 1295 # --option1 Description 1296 # --option2 Description 1297 # --help Show this help 1298 # 1299 1300 set -euo pipefail 1301 1302 # Colors 1303 RED='\033[0;31m' 1304 GREEN='\033[0;32m' 1305 YELLOW='\033[1;33m' 1306 NC='\033[0m' # No Color 1307 1308 # Your script logic here 1309 ``` 1310 1311 **See also:** [CONTRIBUTING.md](../CONTRIBUTING.md#bash-scripts) 1312 1313 --- 1314 1315 ## 🆘 Troubleshooting 1316 1317 ### Common Issues 1318 1319 **Script not found:** 1320 ```bash 1321 # Use relative or absolute paths 1322 ./scripts/workflow/sync-status.sh 1323 ~/Projects/radicle/scripts/workflow/sync-status.sh 1324 ``` 1325 1326 **Permission denied:** 1327 ```bash 1328 # Make script executable 1329 chmod +x scripts/workflow/script-name.sh 1330 ``` 1331 1332 **Command not found (rad, trivy, etc.):** 1333 ```bash 1334 # Install missing dependencies 1335 brew install radicle trivy semgrep 1336 ``` 1337 1338 **Script fails with errors:** 1339 ```bash 1340 # Run with bash debugging 1341 bash -x ./scripts/script-name.sh 1342 1343 # Check script syntax 1344 bash -n ./scripts/script-name.sh 1345 ``` 1346 1347 --- 1348 1349 ## 📊 Statistics 1350 1351 - **Total Scripts**: 53 1352 - **Total Categories**: 12 1353 - **Lines of Code**: ~8,000+ 1354 - **Most Used Category**: Workflow (10 scripts) 1355 - **Automated Scripts**: 8 1356 - **Interactive Scripts**: 6 1357 1358 --- 1359 1360 ## 🔗 Related Documentation 1361 1362 - **[Main README](../README.md)** - Project overview 1363 - **[CONTRIBUTING.md](../CONTRIBUTING.md)** - Contribution guidelines 1364 - **[Documentation Index](../docs/README.md)** - All documentation 1365 - **[Operations Guides](../docs/operations/)** - Operational procedures 1366 - **[Security Policy](../SECURITY.md)** - Security guidelines 1367 1368 --- 1369 1370 ## 📝 Maintenance 1371 1372 ### Adding New Scripts 1373 1374 1. Create script in appropriate category directory 1375 2. Follow naming convention: `action-subject.sh` 1376 3. Add proper header with usage information 1377 4. Update this README.md 1378 5. Test thoroughly 1379 6. Submit patch for review 1380 1381 ### Updating Scripts 1382 1383 1. Maintain backward compatibility when possible 1384 2. Update version number if applicable 1385 3. Update header documentation 1386 4. Test changes 1387 5. Update this README if behavior changes 1388 1389 --- 1390 1391 **Last Updated**: November 12, 2025 1392 **Version**: 2.0.0 1393 **Maintainer**: Project Auxo Inc.