Codex Flutter Environment Script - KW & KDF SDK [v1.3.1]

AGENTS.md

Repository Guidelines for Agents

This repository is a Flutter project. The environment has all Dart and Flutter dependencies pre-fetched during setup, but network access is disabled afterwards. Use the commands below to work with the project.

Setup

flutter pub get --enforce-lockfile

If the above fails due to the offline environment, add the --offline flag:

flutter pub get --offline

Static Analysis and Formatting

Run analysis and formatting before committing code:

flutter analyze

dart format .

Running Tests

Some unit tests and integration tests may currently fail due to ongoing development. Follow these steps for validation:

1. Run static analysis first to catch issues:

   flutter analyze

2. If you need to run specific tests that you believe should work:

   flutter test test/path/to/test_file.dart

3. Perform a thorough code review focusing on:

   • Code correctness and logic
   • Adherence to existing patterns
   • Potential edge cases
   • Type safety

Additional Documentation

Code Styles/Standards

Ensure you follow the existing architecture and style of the codebase. The codebase uses BLoC where applicable and follows general OOP/SOLID coding guidelines. The BLoC conventions and Conventional Commits standards are documented in the sections at the end of this document.

Komodo Wallet

This section is only relevant if you are working in the komodo-wallet repository:

Detailed instructions for building and running the app can be found in docs/BUILD_RUN_APP.md and other files in the docs/ directory. See README.md for an overview of available documentation.

The majority of the crypto/API-related operations are abstracted out to the komodo_defi_sdk and its associated packages e.g. komodo_defi_types.

Komodo DeFi Flutter SDK

This section is only relevant if you are working in the komodo-defi-sdk-flutter repository:

The repository consists of a suite of packages (in the packages directory) which make up a Flutter SDK package komodo_defi_sdk used for implementing Komodo DeFi into Flutter apps.

The KDF API documentation can be found in the root folder at /KDF_API_DOCUMENTATION.md. For any features involving RPC requests, ensure you reference and understand all applicable RPCs, data structure and general notes needed to implement the feature in the SDK.

PR Guidance

Commit messages should be clear and descriptive. When opening a pull request, summarize the purpose of the change and reference related issues when appropriate. Ensure commit messages and the PR title follow the Conventional Commits standard as described in the standards section below.

komodo_flutter_codex_env_setup.sh

#!/bin/bash
set -e

# Start timing the script execution
SCRIPT_START_TIME=$(date +%s)
MAX_EXECUTION_TIME=300 # 5 minutes in seconds

# Script to set up Flutter environment on Codex.
# This script installs Flutter, sets up the environment, configures necessary dependencies, pulls relevant documentation,
# and populates `AGENTS.md`
# NB! Note that Codex cuts the internet after this script completes.

# Usage: "Environments" -> Create environment or select existing -> "Edit" -> "Advanced" -> "Setup script"
# -> Paste the contents of this script -> "Save environment"

# Version of this script
SCRIPT_VERSION="1.4.0"

# Auto-update the setup script if a new version is available
AUTO_UPDATE_SCRIPT=${AUTO_UPDATE_SCRIPT:-false}
# Flag to prevent recursive auto-update loops
SKIP_RECURSIVE_UPDATE=${SKIP_RECURSIVE_UPDATE:-false}

# Whether to run certain operations in parallel
PARALLEL_EXECUTION=${PARALLEL_EXECUTION:-true}
# Maximum number of parallel jobs based on CPU cores
MAX_PARALLEL_JOBS=$(($(nproc) / 2 > 0 ? $(nproc) / 2 : 1))

# URL of the script gist for auto-updating
GIST_URL=https://gist.githubusercontent.com/CharlVS/14233fff7e9b3d66a7268d578cc34b36/raw
SCRIPT_GIST_URL=${GIST_URL}/komodo_flutter_codex_env_setup.sh
AGENTS_GIST_URL=${GIST_URL}/AGENTS.md

# Dependency tracking mechanism
declare -A job_pids
job_count=0

# Function to execute commands with dependencies - compatible with all bash versions
run_with_deps() {
    local name="$1"
    local deps="$2"
    local cmd="$3"
    local dir="${4:-$(pwd)}"

    for dep in $deps; do
        if [[ -n "${job_pids[$dep]}" ]]; then
            echo "Waiting for dependency: $dep"
            wait "${job_pids[$dep]}" || {
                echo "Dependency $dep failed"
                return 1
            }
        fi
    done

    if [[ "$PARALLEL_EXECUTION" == "true" ]]; then
        if ((job_count >= MAX_PARALLEL_JOBS)); then
            for job_name in "${!job_pids[@]}"; do
                local job_pid=${job_pids[$job_name]}
                wait "$job_pid" || true
                unset job_pids[$job_name]
                job_count=$((job_count - 1))
                break
            done
        fi

        echo "Executing in parallel: $cmd (in directory: $dir)"
        (cd "$dir" && eval "$cmd") &
        job_pids[$name]=$!
        job_count=$((job_count + 1))
    else
        echo "Executing sequentially: $cmd (in directory: $dir)"
        (cd "$dir" && eval "$cmd") || return 1
    fi
}

run_parallel() {
    local cmd="$1"
    local dir="${2:-$(pwd)}"

    if [[ "$PARALLEL_EXECUTION" == "true" ]]; then
        if ((job_count >= MAX_PARALLEL_JOBS)); then
            for job_name in "${!job_pids[@]}"; do
                local job_pid=${job_pids[$job_name]}
                wait "$job_pid" || true
                unset job_pids[$job_name]
                job_count=$((job_count - 1))
                break
            done
        fi

        echo "Executing in parallel: $cmd (in directory: $dir)"
        (cd "$dir" && eval "$cmd") &
        local rand_key="job_$(date +%s%N)"
        job_pids[$rand_key]=$!
        job_count=$((job_count + 1))
    else
        echo "Executing sequentially: $cmd (in directory: $dir)"
        (cd "$dir" && eval "$cmd")
    fi
}

wait_if_parallel() {
    if [[ "$PARALLEL_EXECUTION" == "true" ]]; then
        echo "Waiting for parallel jobs to complete..."
        wait
        job_count=0
        for key in "${!job_pids[@]}"; do
            unset job_pids[$key]
        done
    fi
}

is_git_repo() {
    if git rev-parse --is-inside-work-tree >/dev/null 2>&1 && [[ "$(git rev-parse --show-toplevel)" == "$(pwd)" ]]; then
        return 0
    else
        return 1
    fi
}

INITIAL_DIR=$(pwd)
echo "Current directory: $INITIAL_DIR"

# Environment variables
FLUTTER_VERSION="3.41.4"

FLUTTER_INSTALL_METHOD=${FLUTTER_INSTALL_METHOD:-"precompiled"}

if [ -z "${PLATFORMS+x}" ]; then
    PLATFORMS=("web")
fi

FETCH_ALL_REMOTE_BRANCHES=${FETCH_ALL_REMOTE_BRANCHES:-true}

GIT_REMOTE_BASE_URL=${GIT_REMOTE_BASE_URL:-"https://github.com/KomodoPlatform"}

if is_git_repo; then
    GIT_REPO_NAME=$(basename "$(git rev-parse --show-toplevel)")
    GIT_REMOTE_URL="${GIT_REMOTE_BASE_URL}/${GIT_REPO_NAME}.git"
else
    echo "Warning: Not in a Git repository. Git operations will be skipped."
    GIT_REPO_NAME="unknown"
    GIT_REMOTE_URL=""
fi

# Embedded SDK (e.g. Gleec Wallet monorepo)
REPO_HAS_SDK=false
if [[ -f "$INITIAL_DIR/sdk/pubspec.yaml" ]]; then
    REPO_HAS_SDK=true
fi

SHOULD_FETCH_AGENTS_DOCS=${SHOULD_FETCH_AGENTS_DOCS:-true}

if [[ -n "${SHOULD_FETCH_KDF_API_DOCS+x}" ]]; then
    : # user set explicitly
else
    if [[ "$GIT_REPO_NAME" == "komodo-defi-sdk-flutter" || "$REPO_HAS_SDK" == "true" ]]; then
        SHOULD_FETCH_KDF_API_DOCS="true"
    else
        SHOULD_FETCH_KDF_API_DOCS="false"
    fi
fi

KDF_API_DOCS_URL="https://raw.githubusercontent.com/KomodoPlatform/komodo-docs-mdx/refs/heads/dev/data-for-gpts/komodefi-api/all-api-content.txt"

SHELL_PROFILE=""
if [[ "$SHELL" == */zsh ]]; then
    SHELL_PROFILE="$HOME/.zshrc"
    echo "Detected zsh shell"
elif [[ "$SHELL" == */bash ]]; then
    SHELL_PROFILE="$HOME/.bashrc"
    echo "Detected bash shell"
else
    SHELL_PROFILE="$HOME/.profile"
    echo "Shell could not be determined, using $SHELL_PROFILE"
fi

add_to_path() {
    local path_entry="$1"
    local profile="$2"

    path_entry=${path_entry%/}
    local escaped_entry=$(echo "$path_entry" | sed 's/[\/&]/\\&/g')

    if ! grep -q "PATH=.*${escaped_entry}.*" "$profile" && ! grep -q "export PATH=\".*${escaped_entry}.*" "$profile"; then
        echo "Adding $path_entry to PATH in $profile"
        echo "export PATH=\"\$PATH:$path_entry\"" >>"$profile"
        export PATH="$PATH:$path_entry"
        return 0
    else
        echo "$path_entry already in PATH configuration"
        export PATH="$PATH:$path_entry"
        return 1
    fi
}

echo "Checking required dependencies..."
MISSING_TOOLS=""
for tool in curl git unzip xz-utils zip; do
    if ! command -v "$tool" &>/dev/null && ! dpkg -l | grep -q " $tool "; then
        MISSING_TOOLS="$MISSING_TOOLS $tool"
    fi
done

if ! dpkg -l | grep -q " libglu1-mesa "; then
    MISSING_TOOLS="$MISSING_TOOLS libglu1-mesa"
fi

if [ ! -z "$MISSING_TOOLS" ]; then
    echo "Installing missing tools:$MISSING_TOOLS"
    sudo apt-get update -y
    sudo apt-get install -y $MISSING_TOOLS
else
    echo "All required dependencies are already installed."
fi

SCRIPT_CONTENT=$(curl -s $SCRIPT_GIST_URL)
if [[ $? -ne 0 ]]; then
    echo "Warning: Failed to check for script updates. Continuing with current version."
    LATEST_SCRIPT_VERSION=$SCRIPT_VERSION
else
    LATEST_SCRIPT_VERSION=$(echo "$SCRIPT_CONTENT" | grep "SCRIPT_VERSION=" | head -n 1 | cut -d'"' -f2)
    if [[ -z "$LATEST_SCRIPT_VERSION" ]]; then
        echo "Warning: Could not parse script version. Continuing with current version."
        LATEST_SCRIPT_VERSION=$SCRIPT_VERSION
    fi
fi

if [[ "$LATEST_SCRIPT_VERSION" != "$SCRIPT_VERSION" ]]; then
    echo "A new version of the setup script is available: $LATEST_SCRIPT_VERSION"

    if [[ "$AUTO_UPDATE_SCRIPT" == "true" && "$SKIP_RECURSIVE_UPDATE" != "true" ]]; then
        echo "Updating setup script..."
        curl -s $SCRIPT_GIST_URL -o $HOME/komodo_flutter_codex_env_setup.sh
        chmod +x $HOME/komodo_flutter_codex_env_setup.sh
        echo "Running the updated setup script..."
        SKIP_RECURSIVE_UPDATE=true bash $HOME/komodo_flutter_codex_env_setup.sh
        exit 0
    else
        echo "WARN: Auto-update is disabled or skipped to prevent recursion. Please update manually at $SCRIPT_GIST_URL"
    fi
else
    echo "Setup script is up to date: $SCRIPT_VERSION"
fi

if [[ "$FETCH_ALL_REMOTE_BRANCHES" == "true" && -n "$GIT_REMOTE_URL" ]]; then
    if is_git_repo; then
        echo "Fetching all remote branches..."

        if ! git remote | grep -q "^origin$"; then
            git remote add origin "$GIT_REMOTE_URL"
        else
            git remote set-url origin "$GIT_REMOTE_URL"
        fi

        if ! timeout 120 git fetch --all; then
            echo "ERROR: Git fetch failed or timed out. Repository may be incomplete."
        fi
    else
        echo "Not in a git repository, skipping git fetch operations."
    fi
fi

echo "Setting up directories..."
mkdir -p $HOME/flutter

echo "Setting up environment variables..."
add_to_path "$HOME/flutter/bin" "$SHELL_PROFILE"
add_to_path "$HOME/.pub-cache/bin" "$SHELL_PROFILE"

export PATH="$HOME/flutter/bin:$PATH:$HOME/.pub-cache/bin"

echo "Current PATH: $PATH"

FLUTTER_INSTALLED=false
if [ ! -d "$HOME/flutter/bin" ]; then
    echo "Downloading and installing Flutter ${FLUTTER_VERSION}..."

    REQUIRED_SPACE=1500000
    AVAILABLE_SPACE=$(df -k $HOME | awk 'NR==2 {print $4}')

    if [ $AVAILABLE_SPACE -lt $REQUIRED_SPACE ]; then
        echo "Error: Not enough disk space. Need at least 1.5GB, have $(($AVAILABLE_SPACE / 1024))MB"
        exit 1
    fi

    cd $HOME

    if [[ "$FLUTTER_INSTALL_METHOD" == "precompiled" ]]; then
        echo "Using pre-compiled Flutter SDK binaries for version ${FLUTTER_VERSION}..."

        FLUTTER_RELEASE_VERSION=$(echo "${FLUTTER_VERSION}" | sed -E 's/([0-9]+\.[0-9]+\.[0-9]+).*/\1/')
        FLUTTER_ARCHIVE="flutter_linux_${FLUTTER_RELEASE_VERSION}-stable.tar.xz"
        FLUTTER_URL="https://storage.googleapis.com/flutter_infra_release/releases/stable/linux/${FLUTTER_ARCHIVE}"

        echo "Downloading Flutter SDK from: ${FLUTTER_URL}"
        if ! curl -L -o "${FLUTTER_ARCHIVE}" "${FLUTTER_URL}"; then
            echo "Warning: Failed to download pre-compiled Flutter SDK. The specified version may not be available as a pre-built package."
            echo "Falling back to Git installation method..."
            FLUTTER_INSTALL_METHOD="git"
        else
            echo "Extracting Flutter SDK..."
            if ! tar xf "${FLUTTER_ARCHIVE}"; then
                echo "Error: Failed to extract Flutter SDK archive."
                echo "Falling back to Git installation method..."
                FLUTTER_INSTALL_METHOD="git"
                rm "${FLUTTER_ARCHIVE}"
            else
                rm "${FLUTTER_ARCHIVE}"

                EXTRACTED_VERSION=$(cat flutter/version)
                echo "Extracted Flutter version: ${EXTRACTED_VERSION}"

                if [[ "${EXTRACTED_VERSION}" != *"${FLUTTER_RELEASE_VERSION}"* ]]; then
                    echo "Warning: The extracted Flutter version (${EXTRACTED_VERSION}) does not match the requested version (${FLUTTER_VERSION})."
                    echo "Continuing with the downloaded version. If you need the exact version, use FLUTTER_INSTALL_METHOD=git."
                fi
            fi
        fi
    fi

    if [[ "$FLUTTER_INSTALL_METHOD" == "git" ]]; then
        echo "Installing Flutter from Git repository..."

        [ -d "flutter" ] && rm -rf flutter

        echo "Shallow cloning Flutter repository (branch: ${FLUTTER_VERSION})..."
        if ! git clone --depth 1 --branch ${FLUTTER_VERSION} https://github.com/flutter/flutter.git; then
            echo "Error: Failed to clone Flutter repository. Please check your internet connection and try again."
            cd $INITIAL_DIR
            exit 1
        fi
    fi

    cd flutter

    echo "Configuring Flutter..."
    sudo chown -R $(whoami):$(whoami) $HOME/flutter

    if [[ "$FLUTTER_INSTALL_METHOD" == "git" ]]; then
        git config --global --add safe.directory $HOME/flutter
    fi

    echo "Precaching Flutter assets for web..."
    if [ -f "bin/dart" ]; then
        echo "Pre-warming Dart compiler..."
        bin/dart --version >/dev/null 2>&1
    fi

    flutter config --no-analytics
    flutter precache --web --no-android --no-ios --no-fuchsia --no-linux --no-macos --no-windows

    if ! timeout 60 flutter doctor --no-analytics; then
        echo "ERROR: Flutter doctor failed. Flutter installation may be incomplete."
    fi

    if ! command -v flutter &>/dev/null; then
        echo "Error: Flutter installation failed or not available in PATH"
        cd $INITIAL_DIR
        exit 1
    fi

    FLUTTER_INSTALLED=true
    echo "Flutter installation completed successfully!"
else
    echo "Flutter already installed, skipping download"
fi

cd $INITIAL_DIR

for PLATFORM in "${PLATFORMS[@]}"; do
    echo "Setting up platform: $PLATFORM"
    case "$PLATFORM" in
    web)
        if ! command -v node &>/dev/null; then
            run_parallel "sudo apt-get update && sudo apt-get install -y nodejs npm"
        fi
        ;;
    esac
    echo "Platform $PLATFORM setup complete."
done

wait_if_parallel

echo "Environment setup complete!"
echo "Current directory: $(pwd)"

update_git_exclude() {
    if is_git_repo; then
        echo "Updating .git/info/exclude file to ignore downloaded documentation..." >&2
        mkdir -p "$INITIAL_DIR/.git/info"

        local patterns=(
            "AGENTS.md"
            "AGENTS_*.md"
            "KDF_API_DOCUMENTATION.md"
            "# Script-generated documentation files"
        )

        local EXCLUDE_FILE="$INITIAL_DIR/.git/info/exclude"

        for pattern in "${patterns[@]}"; do
            if [[ "$pattern" == \#* ]]; then
                if ! grep -Fq "$pattern" "$EXCLUDE_FILE" 2>/dev/null; then
                    echo "$pattern" >>"$EXCLUDE_FILE"
                fi
            else
                local escaped_pattern=$(echo "$pattern" | sed 's/[.*+?^${}()|[\]\\]/\\&/g')
                if ! grep -q "^$escaped_pattern$" "$EXCLUDE_FILE" 2>/dev/null; then
                    echo "$pattern" >>"$EXCLUDE_FILE"
                fi
            fi
        done
        echo "Git exclude file updated." >&2
    else
        echo "Not in a git repository, skipping git exclude file update." >&2
    fi
}

fetch_all_docs() {
    echo "Fetching documentation..." >&2

    local SCRIPT_MARKER="<!-- Generated by komodo_flutter_codex_env_setup.sh v${SCRIPT_VERSION} -->"

    local BASE_AGENTS_FILE="$INITIAL_DIR/AGENTS.md"
    local AGENTS_FILE="$BASE_AGENTS_FILE"
    local SHOULD_CREATE_FILE=true

    local TEMP_AGENTS_FILE="/tmp/agents_temp_$(date +%s).md"
    echo "Downloading AGENTS.md for content comparison..." >&2

    if curl -s "$AGENTS_GIST_URL" -o "$TEMP_AGENTS_FILE"; then
        local TEMP_WITH_MARKER="/tmp/agents_with_marker_$(date +%s).md"
        {
            echo "$SCRIPT_MARKER"
            echo ""
            cat "$TEMP_AGENTS_FILE"
        } >"$TEMP_WITH_MARKER"

        if [ -f "$BASE_AGENTS_FILE" ]; then
            echo "AGENTS.md already exists, checking if update is needed..." >&2

            if head -n 1 "$BASE_AGENTS_FILE" | grep -q "Generated by komodo_flutter_codex_env_setup.sh"; then
                echo "Existing AGENTS.md was generated by script, checking content..." >&2

                local EXISTING_CONTENT_HASH=$(tail -n +3 "$BASE_AGENTS_FILE" | sha256sum | cut -d' ' -f1)
                local NEW_CONTENT_HASH=$(cat "$TEMP_AGENTS_FILE" | sha256sum | cut -d' ' -f1)

                if [ "$EXISTING_CONTENT_HASH" = "$NEW_CONTENT_HASH" ]; then
                    echo "AGENTS.md content is identical, skipping download." >&2
                    SHOULD_CREATE_FILE=false
                    AGENTS_FILE="$BASE_AGENTS_FILE"
                else
                    echo "AGENTS.md content has changed, updating file..." >&2
                    AGENTS_FILE="$BASE_AGENTS_FILE"
                fi
            else
                echo "Existing AGENTS.md appears to be user-created, creating versioned file..." >&2
                local MAX_NUM=0
                for f in "$INITIAL_DIR"/AGENTS_*.md; do
                    if [ -f "$f" ]; then
                        local NUM=$(echo "$f" | sed -E 's/.*AGENTS_([0-9]+)\.md/\1/')
                        if [[ "$NUM" =~ ^[0-9]+$ ]] && [ "$NUM" -gt "$MAX_NUM" ]; then
                            MAX_NUM=$NUM
                        fi
                    fi
                done

                local NEXT_NUM=$((MAX_NUM + 1))
                AGENTS_FILE="$INITIAL_DIR/AGENTS_$NEXT_NUM.md"
                echo "User-created AGENTS.md detected, saving to $AGENTS_FILE" >&2
            fi
        fi

        if [ "$SHOULD_CREATE_FILE" = true ]; then
            echo "Creating/updating $(basename "$AGENTS_FILE")..." >&2
            cp "$TEMP_WITH_MARKER" "$AGENTS_FILE"
        fi

        rm -f "$TEMP_AGENTS_FILE" "$TEMP_WITH_MARKER"
    else
        echo "Failed to fetch AGENTS.md from remote" >&2
        if [ -f "$BASE_AGENTS_FILE" ]; then
            AGENTS_FILE="$BASE_AGENTS_FILE"
            SHOULD_CREATE_FILE=false
        else
            echo "No existing AGENTS.md found and remote fetch failed" >&2
            return 1
        fi
    fi

    if [ "$SHOULD_CREATE_FILE" = true ]; then
        echo "Fetching additional documentation for processing..." >&2

        run_with_deps "fetch_bloc" "" "curl -s https://raw.githubusercontent.com/felangel/bloc/refs/heads/master/docs/src/content/docs/naming-conventions.mdx > /tmp/bloc_conventions.txt || echo \"Failed to fetch Bloc conventions\"" "$INITIAL_DIR"
        run_with_deps "fetch_commit" "" "curl -s https://raw.githubusercontent.com/conventional-commits/conventionalcommits.org/refs/heads/master/content/v1.0.0/index.md > /tmp/commit_conventions.txt || echo \"Failed to fetch Commit conventions\"" "$INITIAL_DIR"
    else
        echo "Using existing AGENTS.md, skipping additional downloads." >&2
    fi

    if [[ "$SHOULD_FETCH_KDF_API_DOCS" == "true" ]]; then
        local KDF_FILE="$INITIAL_DIR/KDF_API_DOCUMENTATION.md"
        local KDF_MARKER="<!-- Generated by komodo_flutter_codex_env_setup.sh - KDF API Documentation -->"

        echo "Checking KDF API documentation..." >&2

        local SHOULD_CREATE_KDF=true
        if [ -f "$KDF_FILE" ]; then
            if head -n 1 "$KDF_FILE" | grep -q "Generated by komodo_flutter_codex_env_setup.sh"; then
                local FILE_AGE=$(($(date +%s) - $(stat -c %Y "$KDF_FILE" 2>/dev/null || echo 0)))
                if [ $FILE_AGE -lt 86400 ]; then
                    echo "KDF API documentation is recent (< 24h old), skipping download." >&2
                    SHOULD_CREATE_KDF=false
                fi
            fi
        fi

        if [ "$SHOULD_CREATE_KDF" = true ]; then
            echo "Updating KDF API documentation..." >&2
            run_with_deps "fetch_kdf_api" "" "
                echo '$KDF_MARKER' > '$KDF_FILE' && 
                echo '' >> '$KDF_FILE' && 
                curl -s '$KDF_API_DOCS_URL' >> '$KDF_FILE' || 
                echo 'Failed to fetch KDF API documentation'
            " "$INITIAL_DIR"
        fi
    fi

    echo "$AGENTS_FILE"
}

process_agents_docs() {
    local AGENTS_FILE=$1

    if grep -q "# Bloc and Commit Conventions" "$AGENTS_FILE" 2>/dev/null; then
        echo "AGENTS.md already contains appended content, skipping processing." >&2
        return 0
    fi

    echo "Processing AGENTS.md with additional content..." >&2

    run_with_deps "process_agents" "fetch_bloc fetch_commit" "
        echo \"Appending bloc and commit conventions to $(basename '$AGENTS_FILE')\"
        echo -e \"\n# Bloc and Commit Conventions\n\" >>'$AGENTS_FILE'
        cat /tmp/bloc_conventions.txt >>'$AGENTS_FILE'
        echo -e \"\n# Commit Conventions\n\" >>'$AGENTS_FILE'
        cat /tmp/commit_conventions.txt >>'$AGENTS_FILE'
        echo \"$(basename '$AGENTS_FILE') processed successfully.\"
    " "$INITIAL_DIR"
}

# Legacy Komodo Wallet repo (no embedded sdk/ melos workspace at repo root)
if [[ "$GIT_REPO_NAME" == "komodo-wallet" ]]; then
    echo "Detected Komodo Wallet repository, running agent documentation setup..."
    if [[ "$SHOULD_FETCH_AGENTS_DOCS" == "true" ]]; then
        AGENTS_FILE=$(fetch_all_docs)
        process_agents_docs "$AGENTS_FILE"
    fi
fi

# Resolve Melos root: standalone SDK repo or embedded sdk/
MELOS_DIR=""
if [[ "$GIT_REPO_NAME" == "komodo-defi-sdk-flutter" ]]; then
    echo "Detected KDF SDK repository (standalone), running SDK setup..."
    MELOS_DIR="$INITIAL_DIR"
elif [[ "$REPO_HAS_SDK" == "true" ]] && grep -qE '^[[:space:]]*melos:' "$INITIAL_DIR/sdk/pubspec.yaml" 2>/dev/null; then
    echo "Detected embedded SDK at sdk/, running melos bootstrap..."
    MELOS_DIR="$INITIAL_DIR/sdk"
fi

if [[ -n "$MELOS_DIR" ]]; then
    if ! command -v melos &>/dev/null; then
        echo "Downloading and installing melos..."
        if ! timeout 60 flutter pub global activate melos; then
            echo "ERROR: Melos installation failed. SDK setup may be incomplete."
        fi
    else
        echo "Melos already installed, skipping download"
    fi

    if [[ "$SHOULD_FETCH_AGENTS_DOCS" == "true" || "$SHOULD_FETCH_KDF_API_DOCS" == "true" ]]; then
        AGENTS_FILE=$(fetch_all_docs)
        if [[ "$SHOULD_FETCH_AGENTS_DOCS" == "true" ]]; then
            process_agents_docs "$AGENTS_FILE"
        fi
    fi

    echo "Running melos bootstrap in $MELOS_DIR..."
    if ! (cd "$MELOS_DIR" && timeout 180 melos bootstrap); then
        echo "ERROR: Melos bootstrap failed or timed out. SDK setup may be incomplete."
    fi

    if [ -d "$MELOS_DIR/packages/komodo_defi_sdk/example" ]; then
        cd "$MELOS_DIR/packages/komodo_defi_sdk/example"
    else
        echo "Warning: KDF example directory not found."
    fi
fi

cd "$INITIAL_DIR"

echo "Getting package dependencies..."
if ! flutter pub get; then
    echo "ERROR: Flutter pub get failed. Package dependencies may be incomplete."
    echo "Attempting offline mode..."
    if ! flutter pub get --offline; then
        echo "ERROR: Flutter pub get failed in offline mode as well. Setup incomplete."
    fi
fi

if grep -q "build_runner" pubspec.yaml; then
    echo "Building Flutter app to generate assets..."
    if ! dart run build_runner build --delete-conflicting-outputs; then
        echo "WARN: Dart build_runner failed. Some generated files may be missing."
        echo "This is expected on first run if there are code generation issues."
    fi
else
    echo "build_runner not found in pubspec.yaml, skipping code generation step."
fi

# --web-renderer removed in recent Flutter; default web build uses CanvasKit-class renderer.
echo "Building web app to fetch/generate assets..."
if ! timeout 240 flutter build web --profile; then
    echo "WARN: Flutter web build failed or timed out. This is expected for initial code generation."
fi

cd $INITIAL_DIR

wait_if_parallel

update_git_exclude

SCRIPT_END_TIME=$(date +%s)
EXECUTION_TIME=$((SCRIPT_END_TIME - SCRIPT_START_TIME))
EXECUTION_PERCENTAGE=$((EXECUTION_TIME * 100 / MAX_EXECUTION_TIME))

echo "------------------------------------------------------------"
echo "Script execution completed in ${EXECUTION_TIME} seconds"
echo "Used ${EXECUTION_PERCENTAGE}% of maximum allowed time (${MAX_EXECUTION_TIME} seconds)"
echo "------------------------------------------------------------"

exit 0