────────────────────────────────────────────────────────────
 Auto1Cloud / IAM → Laravel App Synchronization Script
────────────────────────────────────────────────────────────
File: cloudsync.py
Purpose: Synchronize the current Laravel application instance
         with the Auto1Cloud IAM (core) environment.

This script ensures that every Laravel sub-application remains
up-to-date with the Auto1Cloud IAM (core) server by automatically
syncing shared models, assets, helper files, environment variables,
and UI components — while also enforcing production safety controls.

────────────────────────────────────────────────────────────
 WHAT IT DOES
────────────────────────────────────────────────────────────

✔ Syncs critical .env variables (Linode keys, SSO secrets, etc.)
✔ Syncs global models and their associated database tables
✔ Syncs global helper functions and support files
✔ Syncs Filament app-name sidebar component and render hook
✔ Copies utility scripts (backup.py, nuke.py)
✔ Ensures banned Artisan commands cannot be run
✔ Uploads pending translation data to the IAM translation API
✔ Maintains error logs in ./sync/errors/

────────────────────────────────────────────────────────────
 EXECUTION FLOW
────────────────────────────────────────────────────────────

1. Detect Laravel Root
   ───────────────────
   • Walks upward from the current file until both “artisan” and
     “composer.json” are found to confirm the Laravel base directory.

2. Abort if IAM Server
   ───────────────────
   • Reads .env and checks for IS_IAM=true.
   • Aborts immediately if true, to prevent overwriting IAM data.

3. Sync Critical .env Variables
   ────────────────────────────
   • Connects to the IAM host via SFTP using CLOUD_FTP credentials.
   • Reads the IAM’s .env file and extracts:

       FILESYSTEM_DISK
       LINODE_ACCESS_KEY_ID
       LINODE_SECRET_ACCESS_KEY
       LINODE_DEFAULT_REGION
       LINODE_BUCKET
       LINODE_ENDPOINT
       LINODE_URL
       SSO_SECRET

   • Merges or adds those keys in the local .env file.

4. Sync Global Models & Database Tables
   ─────────────────────────────────────
   • Downloads all PHP model files from:
       /var/www/html/app/app/Models/Global
     →  saved to:
       ./app/Models/Global

   • For each model:
       - Reads its `$table` property (or infers from class name).
       - Connects to IAM MySQL (CLOUD_SQL).
       - Drops and recreates the local table schema.
       - Copies all rows from IAM → local.

   • Uses `mysql-connector-python` for accurate structure replication.

5. Copy Utility Scripts (backup.py, nuke.py)
   ─────────────────────────────────────────
   • Downloads:
       /var/www/html/app/backup.py
       /var/www/html/app/nuke.py
     →  saved in the Laravel root directory.
   • Provides quick local backup/reset utilities.

6. Sync Global Helper Files
   ─────────────────────────
   • Downloads:
       /var/www/html/app/app/Support/global-helpers.php
       /var/www/html/app/app/Support/global/*.php
     →  saved to:
       ./app/Support/global-helpers.php
       ./app/Support/global/
   • Ensures shared helper functions remain consistent across apps.

7. Sync Filament “App Name” Sidebar Component
   ───────────────────────────────────────────
   • Downloads:
       /var/www/html/app/resources/views/filament/components/app-name.blade.php
     →  saved to:
       ./resources/views/filament/components/app-name.blade.php
   • Displays the current app name + favicon at the top of Filament’s sidebar.

8. Ensure Render Hook in AdminPanelProvider
   ─────────────────────────────────────────
   • Opens:
       ./app/Providers/Filament/AdminPanelProvider.php
   • Verifies or injects:

       ->renderHook(
           PanelsRenderHook::SIDEBAR_NAV_START,
           fn () => view('filament.components.app-name')
       )

   • Ensures the app-name component renders at the top of the sidebar.
   • Skips injection if already present.

9. Ensure Banned Artisan Command Protection
   ─────────────────────────────────────────
   • Opens:
       ./app/Providers/AppServiceProvider.php
   • Checks for a `$this->app->booted()` block containing:

       ['migrate:fresh', 'migrate:refresh', 'migrate:reset', 'db:wipe']

   • Injects this logic if missing, preventing accidental destructive
     Artisan operations on production.

10. Sync Pending Translation Data
    ──────────────────────────────
    • Ensures ./sync/files/ exists and is writable (chmod 775).
    • If ./sync/files/translation_pending.json exists and is non-empty:
        - Uploads contents via POST to:
          https://cloudrt.auto1cloud.com/var/translation/upload-json.php
        - Clears the file on success.
    • Logs any network or server errors to ./sync/errors/.

11. Logging & Error Handling
    ─────────────────────────
    • All exceptions or connection failures are logged as:
        ./sync/errors/YYYYMMDD-HHMMSS.log
    • Continues processing unaffected steps where possible.

12. Completion Message
    ───────────────────
    • Displays:
        ✅ Full cloud sync completed successfully.
      when all stages finish without critical errors.

────────────────────────────────────────────────────────────
 CONFIGURATION CONSTANTS
────────────────────────────────────────────────────────────

CLOUD_SQL
    Remote IAM database credentials used to copy table schemas/data.

CLOUD_FTP
    Remote IAM SFTP credentials + absolute paths to:
      - Global models
      - Helper files
      - Utility scripts
      - Blade component (app-name.blade.php)

TRANSLATION_API
    Cloud endpoint for pushing pending translations.

────────────────────────────────────────────────────────────
 RUNNING THE SCRIPT
────────────────────────────────────────────────────────────

1. Place `cloudsync.py` in the root of your Laravel project.
2. Execute manually or via cron:

       /usr/bin/python3 cloudsync.py

3. The script auto-detects paths and dependencies:
   - dotenv
   - paramiko
   - mysql-connector-python
   - requests
   - inflection

────────────────────────────────────────────────────────────
 SAFETY NOTES
────────────────────────────────────────────────────────────

• The script **never runs** on the IAM host (`IS_IAM=true` check).
• Database sync **drops and recreates** tables locally — any local-only
  changes will be lost.
• The `$this->app->booted()` safety block prevents destructive Artisan
  migrations in production.
• Every error is logged under `./sync/errors/` with a timestamp.

────────────────────────────────────────────────────────────
 LINE-BY-LINE SUMMARY
────────────────────────────────────────────────────────────
1–18   →  Imports and header  
21–45  →  Configuration constants  
48–81  →  log_error(), find_laravel_root(), get_local_env() helpers  
84–96  →  abort_if_iam() safety check  
99–161 →  sync_env_from_cloud() (.env merge)  
164–226 → copy_global_models_and_tables() (models + DB sync)  
229–248 → copy_utility_scripts() (backup.py, nuke.py)  
251–289 → sync_global_helpers() (helper PHP files)  
292–321 → sync_app_name_component() (Filament component)  
324–374 → ensure_app_name_render_hook() (inject render hook)  
377–428 → ensure_banned_artisan_block() (safety patch)  
431–466 → copy_table_data() (MySQL schema/data replication)  
471–526 → sync_translation_pending() (translation upload)  
530–559 → main() orchestrator  

────────────────────────────────────────────────────────────
 AUTHOR / CONTEXT
────────────────────────────────────────────────────────────
Developed for Auto1Cloud’s modular architecture.
This script keeps all Laravel-based satellite apps synchronized
with the IAM (core) system — ensuring code, configuration, and
branding remain consistent across environments.

────────────────────────────────────────────────────────────
 END OF DOCUMENTATION
────────────────────────────────────────────────────────────