flutter-dev 0.1.9__tar.gz → 0.1.11__tar.gz

{flutter_dev-0.1.9 → flutter_dev-0.1.11}/.env.example

@@ -1,26 +1,25 @@
 # AI API Keys Configuration
-# সব API keys এখানে secure ভাবে রাখুন
-# এই file টি .gitignore এ add করতে হবে
+# API keys secure রাখুন এবং কারও সঙ্গে share করবেন না
 
-# Groq API (Current - Active)
-GROQ_API_KEY=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
+# Groq API
+GROQ_API_KEY=
 GROQ_API_URL=https://api.groq.com/openai/v1/chat/completions
 GROQ_MODEL=llama-3.3-70b-versatile
 
 # Mistral AI API
-MISTRAL_API_KEY=irrmymmw43lvCcARy08R1TZhHuqMgXwa
+MISTRAL_API_KEY=
 MISTRAL_API_URL=https://api.mistral.ai/v1/chat/completions
-MISTRAL_MODEL=mistral-medium
+MISTRAL_MODEL=mistral-medium-latest
 
 # SambaNova API
-SAMBANOVA_API_KEY=c5c3f0dc-75db-4621-9d0c-7372efb4a04f
+SAMBANOVA_API_KEY=
 SAMBANOVA_API_URL=https://api.sambanova.ai/v1/chat/completions
 SAMBANOVA_MODEL=Meta-Llama-3.3-70B-Instruct
 
 # OpenRouter API
-OPENROUTER_API_KEY=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
+OPENROUTER_API_KEY=
 OPENROUTER_API_URL=https://openrouter.ai/api/v1/chat/completions
 OPENROUTER_MODEL=openai/gpt-3.5-turbo
 
 # Default AI Service (groq, mistral, sambanova, openrouter)
-DEFAULT_AI_SERVICE=groq
+DEFAULT_AI_SERVICE=groq

{flutter_dev-0.1.9 → flutter_dev-0.1.11}/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to this project are documented in this file.
 
+## 0.1.11 - 2026-07-22
+
+### Added
+
+- Added Python regression coverage for project-root and outside-project `fdev clear-data` behavior.
+
+### Changed
+
+- Changed `fdev clear-data` to target the current project's Android package without confirmation when run from a Flutter project root, matching `fdev uninstall`; outside a project it still confirms before clearing the foreground app.
+- Updated the PyPI publishing workflow to run on pushes to the `deployment` branch as well as manual dispatches.
+
+## 0.1.10 - 2026-07-16
+
+### Added
+
+- Added `fdev init` to create or repair persistent AI configuration with safe provider defaults and empty API-key fields.
+- Added interactive hidden API-key entry and default/custom model selection when AI configuration is incomplete.
+- Added `fdev ai <provider> <model>` for changing a provider's model without replacing its API key.
+- Added Python coverage for configuration precedence, dotenv parsing, atomic updates, cancellation, permissions, platform paths, and doctor status.
+
+### Changed
+
+- Unified `fdev ai`, `fdev doctor`, `gemini-api`, and `fdev commit` around the same persistent AI configuration resolver.
+- Updated the default Mistral model to `mistral-medium-latest`.
+- Limited build-output directory creation to commands that use those directories.
+
+### Fixed
+
+- Removed credentials from `.env.example` and replaced them with empty API-key values.
+- Made AI configuration writes atomic and restricted the generated file to the current user on Unix-like systems.
+- Cancelled AI setup without saving a partial key or sending a request when interrupted during key/model entry.
+- Prevented exported provider/model overrides from being reported as successfully replaced by file-only changes.
+
 ## 0.1.9 - 2026-07-14
 
 ### Added

{flutter_dev-0.1.9 → flutter_dev-0.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flutter-dev
-Version: 0.1.9
+Version: 0.1.11
 Summary: A cross-platform CLI toolkit for Flutter development workflows.
 Author: Royal Court BD
 License-Expression: MIT
@@ -42,14 +42,14 @@ The package is published on PyPI as `flutter-dev` and installs console commands
 python -m pip install flutter-dev
 ```
 
-Current package metadata declares version `0.1.9`, Python `>=3.8`, MIT license, and support for macOS, Linux, and Windows.
+Current package metadata declares version `0.1.11`, Python `>=3.8`, MIT license, and support for macOS, Linux, and Windows.
 
 ## Key Features
 
 - Flutter build automation for APK, split APK, AAB, IPA, release install, and Firebase web deploy.
 - Project maintenance helpers for `flutter clean`, dependency refresh, `build_runner`, localization generation, analysis, formatting, cache repair, and CocoaPods.
 - Localization CSV helpers for exporting ARB files to translator-friendly CSV files and generating ARB files back from CSV.
-- Android device helpers for APK install, app uninstall, foreground app data clearing, screen mirroring with `scrcpy`, wireless ADB setup, and Date & Time settings.
+- Android device helpers for APK install, app uninstall, project/foreground app data clearing, screen mirroring with `scrcpy`, wireless ADB setup, and Date & Time settings.
 - AI-assisted Git commits using Groq, Mistral, SambaNova, or OpenRouter-compatible chat completion APIs.
 - Git workflow helpers for version tags, branch sync, deployment branch merge, discard, and GitHub account management through `gh`.
 - Feature/page generator that creates a `lib/features/<name>` structure using the project's presenter/base-state pattern.
@@ -137,6 +137,9 @@ fdev upgrade
 # Check environment and optional tools
 fdev doctor
 
+# Initialize persistent AI configuration
+fdev init
+
 # Generate localization files
 fdev lang
 
@@ -198,7 +201,7 @@ Android APK/AAB build commands rename output files using the Android app label a
 | --- | --- |
 | `fdev install` | Installs a built APK from `build/app/outputs/flutter-apk`, prefers `arm64-v8a`, retries after uninstall on failure, then launches the app. |
 | `fdev uninstall` | In a Flutter project root, uninstalls by package/bundle id. Outside a project, detects the foreground app and asks for confirmation. |
-| `fdev clear-data` | Detects the foreground app and runs `adb shell pm clear <package>` on Android. Confirmation is skipped when it matches the current Flutter project; otherwise the default-Yes safety prompt is shown. iOS prints manual options. |
+| `fdev clear-data` | In a Flutter project root, clears the project's Android package data without confirmation. Outside a project, detects the foreground app and shows a default-Yes safety prompt. iOS prints manual options. |
 | `fdev install-scrcpy` | Installs `scrcpy` using the best supported package manager for the current platform. |
 | `fdev mirror` | Launches `scrcpy` for a selected Android device. |
 | `fdev mirror --wireless` | Guides wireless ADB setup using a USB-connected Android device. |
@@ -239,10 +242,12 @@ Switching GitHub accounts runs `gh auth switch` and `gh auth setup-git`, but it
 | `fdev` | Shows command help. |
 | `fdev help` | Shows command help. |
 | `fdev doctor` | Checks platform, Python, Flutter/Dart/Git, Python packages, Android/iOS tools, optional CLIs, `.env`, Flutter project detection, and global `fdev` availability. |
+| `fdev init` | Creates or repairs the persistent AI `.env` with safe provider defaults and empty API keys. |
 | `fdev upgrade` | Shows the current version, Python environment, package location, and PyPI source, then upgrades with `python -m pip install --upgrade flutter-dev` and reports the resulting version. |
 | `fdev delete` | Detects the OS, asks for confirmation, then uninstalls the active Python environment's `flutter-dev` package. Use `fdev delete --yes` to skip confirmation. |
 | `fdev ai` | Shows the current AI provider and opens an interactive provider switch prompt. |
 | `fdev ai <provider>` | Switches `DEFAULT_AI_SERVICE` to `groq`, `mistral`, `sambanova`, or `openrouter`. |
+| `fdev ai <provider> <model>` | Switches provider when needed and saves a custom model ID for that provider. |
 | `fdev brew` | Interactive Homebrew package manager for viewing packages, uninstalling with cleanup, clearing cache, and global cleanup. |
 | `fdev merge` | Reads paths from `paths.txt`, merges file contents into `path_merge_files.txt`, and opens the result when there are no failures. |
 | `gemini-api` | Tests the currently selected AI provider configuration. |
@@ -266,7 +271,7 @@ GROQ_MODEL=llama-3.3-70b-versatile
 
 MISTRAL_API_KEY=your_mistral_api_key_here
 MISTRAL_API_URL=https://api.mistral.ai/v1/chat/completions
-MISTRAL_MODEL=mistral-medium
+MISTRAL_MODEL=mistral-medium-latest
 
 SAMBANOVA_API_KEY=your_sambanova_api_key_here
 SAMBANOVA_API_URL=https://api.sambanova.ai/v1/chat/completions
@@ -283,26 +288,47 @@ The AI runtime searches for configuration in this order:
 
 1. `FLUTTER_DEV_ENV`
 2. `$XDG_CONFIG_HOME/flutter-dev/.env`
-3. `~/.config/flutter-dev/.env`
-4. `~/scripts/flutter-tools/.env`
-5. `.env` beside the installed module/source
-6. `.env` in the current working directory
+3. `%APPDATA%/flutter-dev/.env` on Windows, otherwise `~/.config/flutter-dev/.env`
+4. The legacy `~/.config/flutter-dev/.env` path on Windows
+5. `~/scripts/flutter-tools/.env`
 
 Recommended setup:
 
 ```bash
-mkdir -p ~/.config/flutter-dev
-nano ~/.config/flutter-dev/.env
+fdev init
 ```
 
-Then test:
+`fdev init` never writes real credentials. It creates all provider URL/model
+defaults with empty API-key fields, preserves existing values, and restricts the
+file to the current user on Unix-like systems. On macOS and Linux the default
+path is `~/.config/flutter-dev/.env`.
+
+Then select a provider and test:
 
 ```bash
-fdev ai
+fdev ai mistral
 gemini-api
 ```
 
-Note: the current `fdev doctor` `.env` check is more limited than the AI runtime lookup. If `doctor` reports a missing `.env` but `gemini-api` succeeds, the AI configuration is still usable.
+If the selected provider's key is missing, `fdev commit` or `gemini-api` asks
+for it using hidden terminal input and saves it to the active configuration.
+After a new key is entered, press Enter to use the displayed default model or
+enter another model ID for the same provider. Exported environment variables
+continue to take precedence over values stored in `.env`.
+
+Pressing `Ctrl+C` during key/model setup cancels the operation without saving a
+partial key or sending an AI request. If an exported variable conflicts with a
+provider/model change, `fdev` reports the override and asks you to unset it
+instead of claiming that the file change became active.
+
+Change the model later without replacing the API key:
+
+```bash
+fdev ai groq llama-3.1-8b-instant
+```
+
+`fdev doctor`, `fdev ai`, `gemini-api`, and `fdev commit` use the same persistent
+configuration lookup.
 
 ## Feature/Page Generation
 
@@ -364,7 +390,7 @@ core/constants.py       Shared regex patterns, paths, and build command constant
 core/state.py           Selected Android device state
 managers/build.py       APK/AAB/IPA/release-run build workflow
 managers/project.py     setup, cleanup, lang, db, pod, cache repair
-managers/app.py         install, uninstall, foreground app data clearing
+managers/app.py         install, uninstall, project/foreground app data clearing
 managers/device.py      ADB device detection and selection
 managers/mirror.py      scrcpy install, mirror, wireless ADB setup
 managers/git.py         commit, tag, discard, branch sync, deployment merge
@@ -387,7 +413,7 @@ The installed Python layout is top-level modules plus the `core` and `managers`
 - `fdev tag` updates `pubspec.yaml`, creates a commit, creates a Git tag, and pushes both.
 - `fdev discard` removes tracked changes and untracked files after confirmation.
 - `fdev cleanup` applies `dart fix`, formats the project, and runs a major-version dependency upgrade.
-- `fdev clear-data` skips confirmation only when the foreground Android app matches the current Flutter project's package ID; otherwise it uses a default-Yes `[Y/n]` confirmation.
+- `fdev clear-data` targets the current project's Android package without confirmation when run from a Flutter project root. Outside a project, it targets the foreground app after a default-Yes `[Y/n]` confirmation.
 - `fdev uninstall` may fall back to foreground app detection outside a Flutter project root.
 - `fdev upgrade` and `fdev delete` manage the local `flutter-dev` Python package, not the Flutter app on a device.
 - `fdev upgrade` reports the installed version and location before upgrading, then shows the before→after version when the active process can verify it immediately.

{flutter_dev-0.1.9 → flutter_dev-0.1.11}/README.md

@@ -8,14 +8,14 @@ The package is published on PyPI as `flutter-dev` and installs console commands
 python -m pip install flutter-dev
 ```
 
-Current package metadata declares version `0.1.9`, Python `>=3.8`, MIT license, and support for macOS, Linux, and Windows.
+Current package metadata declares version `0.1.11`, Python `>=3.8`, MIT license, and support for macOS, Linux, and Windows.
 
 ## Key Features
 
 - Flutter build automation for APK, split APK, AAB, IPA, release install, and Firebase web deploy.
 - Project maintenance helpers for `flutter clean`, dependency refresh, `build_runner`, localization generation, analysis, formatting, cache repair, and CocoaPods.
 - Localization CSV helpers for exporting ARB files to translator-friendly CSV files and generating ARB files back from CSV.
-- Android device helpers for APK install, app uninstall, foreground app data clearing, screen mirroring with `scrcpy`, wireless ADB setup, and Date & Time settings.
+- Android device helpers for APK install, app uninstall, project/foreground app data clearing, screen mirroring with `scrcpy`, wireless ADB setup, and Date & Time settings.
 - AI-assisted Git commits using Groq, Mistral, SambaNova, or OpenRouter-compatible chat completion APIs.
 - Git workflow helpers for version tags, branch sync, deployment branch merge, discard, and GitHub account management through `gh`.
 - Feature/page generator that creates a `lib/features/<name>` structure using the project's presenter/base-state pattern.
@@ -103,6 +103,9 @@ fdev upgrade
 # Check environment and optional tools
 fdev doctor
 
+# Initialize persistent AI configuration
+fdev init
+
 # Generate localization files
 fdev lang
 
@@ -164,7 +167,7 @@ Android APK/AAB build commands rename output files using the Android app label a
 | --- | --- |
 | `fdev install` | Installs a built APK from `build/app/outputs/flutter-apk`, prefers `arm64-v8a`, retries after uninstall on failure, then launches the app. |
 | `fdev uninstall` | In a Flutter project root, uninstalls by package/bundle id. Outside a project, detects the foreground app and asks for confirmation. |
-| `fdev clear-data` | Detects the foreground app and runs `adb shell pm clear <package>` on Android. Confirmation is skipped when it matches the current Flutter project; otherwise the default-Yes safety prompt is shown. iOS prints manual options. |
+| `fdev clear-data` | In a Flutter project root, clears the project's Android package data without confirmation. Outside a project, detects the foreground app and shows a default-Yes safety prompt. iOS prints manual options. |
 | `fdev install-scrcpy` | Installs `scrcpy` using the best supported package manager for the current platform. |
 | `fdev mirror` | Launches `scrcpy` for a selected Android device. |
 | `fdev mirror --wireless` | Guides wireless ADB setup using a USB-connected Android device. |
@@ -205,10 +208,12 @@ Switching GitHub accounts runs `gh auth switch` and `gh auth setup-git`, but it
 | `fdev` | Shows command help. |
 | `fdev help` | Shows command help. |
 | `fdev doctor` | Checks platform, Python, Flutter/Dart/Git, Python packages, Android/iOS tools, optional CLIs, `.env`, Flutter project detection, and global `fdev` availability. |
+| `fdev init` | Creates or repairs the persistent AI `.env` with safe provider defaults and empty API keys. |
 | `fdev upgrade` | Shows the current version, Python environment, package location, and PyPI source, then upgrades with `python -m pip install --upgrade flutter-dev` and reports the resulting version. |
 | `fdev delete` | Detects the OS, asks for confirmation, then uninstalls the active Python environment's `flutter-dev` package. Use `fdev delete --yes` to skip confirmation. |
 | `fdev ai` | Shows the current AI provider and opens an interactive provider switch prompt. |
 | `fdev ai <provider>` | Switches `DEFAULT_AI_SERVICE` to `groq`, `mistral`, `sambanova`, or `openrouter`. |
+| `fdev ai <provider> <model>` | Switches provider when needed and saves a custom model ID for that provider. |
 | `fdev brew` | Interactive Homebrew package manager for viewing packages, uninstalling with cleanup, clearing cache, and global cleanup. |
 | `fdev merge` | Reads paths from `paths.txt`, merges file contents into `path_merge_files.txt`, and opens the result when there are no failures. |
 | `gemini-api` | Tests the currently selected AI provider configuration. |
@@ -232,7 +237,7 @@ GROQ_MODEL=llama-3.3-70b-versatile
 
 MISTRAL_API_KEY=your_mistral_api_key_here
 MISTRAL_API_URL=https://api.mistral.ai/v1/chat/completions
-MISTRAL_MODEL=mistral-medium
+MISTRAL_MODEL=mistral-medium-latest
 
 SAMBANOVA_API_KEY=your_sambanova_api_key_here
 SAMBANOVA_API_URL=https://api.sambanova.ai/v1/chat/completions
@@ -249,26 +254,47 @@ The AI runtime searches for configuration in this order:
 
 1. `FLUTTER_DEV_ENV`
 2. `$XDG_CONFIG_HOME/flutter-dev/.env`
-3. `~/.config/flutter-dev/.env`
-4. `~/scripts/flutter-tools/.env`
-5. `.env` beside the installed module/source
-6. `.env` in the current working directory
+3. `%APPDATA%/flutter-dev/.env` on Windows, otherwise `~/.config/flutter-dev/.env`
+4. The legacy `~/.config/flutter-dev/.env` path on Windows
+5. `~/scripts/flutter-tools/.env`
 
 Recommended setup:
 
 ```bash
-mkdir -p ~/.config/flutter-dev
-nano ~/.config/flutter-dev/.env
+fdev init
 ```
 
-Then test:
+`fdev init` never writes real credentials. It creates all provider URL/model
+defaults with empty API-key fields, preserves existing values, and restricts the
+file to the current user on Unix-like systems. On macOS and Linux the default
+path is `~/.config/flutter-dev/.env`.
+
+Then select a provider and test:
 
 ```bash
-fdev ai
+fdev ai mistral
 gemini-api
 ```
 
-Note: the current `fdev doctor` `.env` check is more limited than the AI runtime lookup. If `doctor` reports a missing `.env` but `gemini-api` succeeds, the AI configuration is still usable.
+If the selected provider's key is missing, `fdev commit` or `gemini-api` asks
+for it using hidden terminal input and saves it to the active configuration.
+After a new key is entered, press Enter to use the displayed default model or
+enter another model ID for the same provider. Exported environment variables
+continue to take precedence over values stored in `.env`.
+
+Pressing `Ctrl+C` during key/model setup cancels the operation without saving a
+partial key or sending an AI request. If an exported variable conflicts with a
+provider/model change, `fdev` reports the override and asks you to unset it
+instead of claiming that the file change became active.
+
+Change the model later without replacing the API key:
+
+```bash
+fdev ai groq llama-3.1-8b-instant
+```
+
+`fdev doctor`, `fdev ai`, `gemini-api`, and `fdev commit` use the same persistent
+configuration lookup.
 
 ## Feature/Page Generation
 
@@ -330,7 +356,7 @@ core/constants.py       Shared regex patterns, paths, and build command constant
 core/state.py           Selected Android device state
 managers/build.py       APK/AAB/IPA/release-run build workflow
 managers/project.py     setup, cleanup, lang, db, pod, cache repair
-managers/app.py         install, uninstall, foreground app data clearing
+managers/app.py         install, uninstall, project/foreground app data clearing
 managers/device.py      ADB device detection and selection
 managers/mirror.py      scrcpy install, mirror, wireless ADB setup
 managers/git.py         commit, tag, discard, branch sync, deployment merge
@@ -353,7 +379,7 @@ The installed Python layout is top-level modules plus the `core` and `managers`
 - `fdev tag` updates `pubspec.yaml`, creates a commit, creates a Git tag, and pushes both.
 - `fdev discard` removes tracked changes and untracked files after confirmation.
 - `fdev cleanup` applies `dart fix`, formats the project, and runs a major-version dependency upgrade.
-- `fdev clear-data` skips confirmation only when the foreground Android app matches the current Flutter project's package ID; otherwise it uses a default-Yes `[Y/n]` confirmation.
+- `fdev clear-data` targets the current project's Android package without confirmation when run from a Flutter project root. Outside a project, it targets the foreground app after a default-Yes `[Y/n]` confirmation.
 - `fdev uninstall` may fall back to foreground app detection outside a Flutter project root.
 - `fdev upgrade` and `fdev delete` manage the local `flutter-dev` Python package, not the Flutter app on a device.
 - `fdev upgrade` reports the installed version and location before upgrading, then shows the before→after version when the active process can verify it immediately.

flutter_dev-0.1.11/core/ai_config.py

@@ -0,0 +1,297 @@
+"""Shared AI configuration paths, defaults, and persistence helpers."""
+
+import os
+import platform
+import re
+import tempfile
+from pathlib import Path
+
+from dotenv import dotenv_values
+
+
+VALID_AI_SERVICES = ("groq", "mistral", "sambanova", "openrouter")
+
+AI_SERVICE_DEFAULTS = {
+    "groq": {
+        "api_key_env": "GROQ_API_KEY",
+        "api_url_env": "GROQ_API_URL",
+        "model_env": "GROQ_MODEL",
+        "api_url": "https://api.groq.com/openai/v1/chat/completions",
+        "model": "llama-3.3-70b-versatile",
+    },
+    "mistral": {
+        "api_key_env": "MISTRAL_API_KEY",
+        "api_url_env": "MISTRAL_API_URL",
+        "model_env": "MISTRAL_MODEL",
+        "api_url": "https://api.mistral.ai/v1/chat/completions",
+        "model": "mistral-medium-latest",
+    },
+    "sambanova": {
+        "api_key_env": "SAMBANOVA_API_KEY",
+        "api_url_env": "SAMBANOVA_API_URL",
+        "model_env": "SAMBANOVA_MODEL",
+        "api_url": "https://api.sambanova.ai/v1/chat/completions",
+        "model": "Meta-Llama-3.3-70B-Instruct",
+    },
+    "openrouter": {
+        "api_key_env": "OPENROUTER_API_KEY",
+        "api_url_env": "OPENROUTER_API_URL",
+        "model_env": "OPENROUTER_MODEL",
+        "api_url": "https://openrouter.ai/api/v1/chat/completions",
+        "model": "openai/gpt-3.5-turbo",
+    },
+}
+
+
+def get_preferred_env_path():
+    """Return the user config path where fdev should create its .env file."""
+    explicit_path = os.getenv("FLUTTER_DEV_ENV")
+    if explicit_path:
+        return Path(explicit_path).expanduser()
+
+    xdg_config_home = os.getenv("XDG_CONFIG_HOME")
+    if xdg_config_home:
+        return Path(xdg_config_home).expanduser() / "flutter-dev" / ".env"
+
+    if platform.system() == "Windows" and os.getenv("APPDATA"):
+        return Path(os.environ["APPDATA"]).expanduser() / "flutter-dev" / ".env"
+
+    # Keep the established path on macOS and Linux for backward compatibility.
+    return Path.home() / ".config" / "flutter-dev" / ".env"
+
+
+def get_persistent_env_candidates():
+    """Return user-owned config candidates without project-local fallbacks."""
+    preferred_path = get_preferred_env_path()
+    candidates = [
+        preferred_path,
+        Path.home() / ".config" / "flutter-dev" / ".env",
+        Path.home() / "scripts" / "flutter-tools" / ".env",
+    ]
+    unique_candidates = []
+    seen = set()
+    for candidate in candidates:
+        normalized = str(candidate.expanduser())
+        if normalized not in seen:
+            seen.add(normalized)
+            unique_candidates.append(candidate.expanduser())
+    return unique_candidates
+
+
+def find_persistent_env_file():
+    """Return an existing user-owned config file, or None."""
+    # Explicit path controls must not silently fall back to another file.
+    if os.getenv("FLUTTER_DEV_ENV") or os.getenv("XDG_CONFIG_HOME"):
+        preferred_path = get_preferred_env_path()
+        return preferred_path if preferred_path.is_file() else None
+
+    for candidate in get_persistent_env_candidates():
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def get_active_env_path():
+    """Return the existing runtime config, or the preferred creation path."""
+    return find_persistent_env_file() or get_preferred_env_path()
+
+
+def build_env_template(default_service="groq"):
+    """Build a safe config template containing no API credentials."""
+    return f"""# AI API Keys Configuration
+# API keys secure রাখুন এবং কারও সঙ্গে share করবেন না
+
+# Groq API
+GROQ_API_KEY=
+GROQ_API_URL={AI_SERVICE_DEFAULTS['groq']['api_url']}
+GROQ_MODEL={AI_SERVICE_DEFAULTS['groq']['model']}
+
+# Mistral AI API
+MISTRAL_API_KEY=
+MISTRAL_API_URL={AI_SERVICE_DEFAULTS['mistral']['api_url']}
+MISTRAL_MODEL={AI_SERVICE_DEFAULTS['mistral']['model']}
+
+# SambaNova API
+SAMBANOVA_API_KEY=
+SAMBANOVA_API_URL={AI_SERVICE_DEFAULTS['sambanova']['api_url']}
+SAMBANOVA_MODEL={AI_SERVICE_DEFAULTS['sambanova']['model']}
+
+# OpenRouter API
+OPENROUTER_API_KEY=
+OPENROUTER_API_URL={AI_SERVICE_DEFAULTS['openrouter']['api_url']}
+OPENROUTER_MODEL={AI_SERVICE_DEFAULTS['openrouter']['model']}
+
+# Default AI Service (groq, mistral, sambanova, openrouter)
+DEFAULT_AI_SERVICE={default_service}
+"""
+
+
+def read_env_file(env_path):
+    """Read an env file with the same parser used by the AI runtime."""
+    env_path = Path(env_path)
+    if not env_path.is_file():
+        return {}
+
+    parsed = dotenv_values(env_path, interpolate=False, encoding="utf-8")
+    return {key: value or "" for key, value in parsed.items()}
+
+
+def resolve_ai_config(file_values, environ=None):
+    """Resolve one serializable AI configuration from file and process data."""
+    process_values = os.environ if environ is None else environ
+
+    def effective_value(key, fallback=""):
+        if key in process_values and process_values[key]:
+            return process_values[key]
+        return file_values.get(key, fallback)
+
+    providers = {}
+    relevant_environment_keys = {"DEFAULT_AI_SERVICE"}
+    for service in VALID_AI_SERVICES:
+        defaults = AI_SERVICE_DEFAULTS[service]
+        relevant_environment_keys.update(
+            {
+                defaults["api_key_env"],
+                defaults["api_url_env"],
+                defaults["model_env"],
+            }
+        )
+        providers[service] = {
+            "api_key": effective_value(defaults["api_key_env"]),
+            "api_url": effective_value(
+                defaults["api_url_env"], defaults["api_url"]
+            ),
+            "model": effective_value(defaults["model_env"], defaults["model"]),
+        }
+
+    service = effective_value("DEFAULT_AI_SERVICE", "groq").strip().lower()
+    return {
+        "service": service,
+        "providers": providers,
+        "environment_overrides": sorted(
+            key
+            for key in relevant_environment_keys
+            if process_values.get(key)
+        ),
+    }
+
+
+def load_resolved_ai_config(env_path, environ=None):
+    """Load and resolve configuration while retaining its source path."""
+    resolved = resolve_ai_config(read_env_file(env_path), environ=environ)
+    resolved["env_path"] = str(Path(env_path))
+    return resolved
+
+
+def update_env_file_value(env_path, key, value):
+    """Update one env value atomically."""
+    update_env_file_values(env_path, {key: value})
+
+
+def update_env_file_values(env_path, updates):
+    """Update env values in one atomic write, removing duplicate target keys."""
+    normalized_updates = {}
+    for key, value in updates.items():
+        value = str(value)
+        if "\n" in value or "\r" in value:
+            raise ValueError(f"Invalid newline in {key}")
+        normalized_updates[key] = value
+
+    env_path = Path(env_path)
+    env_path.parent.mkdir(parents=True, exist_ok=True)
+    content = env_path.read_text(encoding="utf-8") if env_path.exists() else ""
+    lines = content.splitlines()
+    output_lines = []
+    written_keys = set()
+    assignment_pattern = re.compile(
+        r"^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*="
+    )
+
+    for line in lines:
+        match = assignment_pattern.match(line)
+        key = match.group(1) if match else None
+        if key not in normalized_updates:
+            output_lines.append(line)
+            continue
+        if key in written_keys:
+            continue
+        output_lines.append(f"{key}={normalized_updates[key]}")
+        written_keys.add(key)
+
+    missing_keys = [
+        key for key in normalized_updates if key not in written_keys
+    ]
+    if missing_keys and output_lines and output_lines[-1].strip():
+        output_lines.append("")
+    output_lines.extend(
+        f"{key}={normalized_updates[key]}" for key in missing_keys
+    )
+
+    _atomic_write_env(env_path, "\n".join(output_lines) + "\n")
+
+
+def ensure_env_file(env_path=None):
+    """Create the config and add any missing default fields without overwriting."""
+    env_path = Path(env_path or get_preferred_env_path()).expanduser()
+    env_path.parent.mkdir(parents=True, exist_ok=True)
+    created = not env_path.exists()
+
+    if created:
+        _atomic_write_env(env_path, build_env_template())
+    else:
+        existing = read_env_file(env_path)
+        missing_values = {}
+        for service in VALID_AI_SERVICES:
+            defaults = AI_SERVICE_DEFAULTS[service]
+            missing_defaults = {
+                defaults["api_key_env"]: "",
+                defaults["api_url_env"]: defaults["api_url"],
+                defaults["model_env"]: defaults["model"],
+            }
+            for key, value in missing_defaults.items():
+                if key not in existing or (value and not existing[key]):
+                    missing_values[key] = value
+        if not existing.get("DEFAULT_AI_SERVICE"):
+            missing_values["DEFAULT_AI_SERVICE"] = "groq"
+        if missing_values:
+            update_env_file_values(env_path, missing_values)
+
+    _protect_env_file(env_path)
+    return env_path, created
+
+
+def _protect_env_file(env_path):
+    """Restrict config permissions to the current user on Unix-like systems."""
+    if os.name != "nt":
+        try:
+            Path(env_path).chmod(0o600)
+        except OSError:
+            pass
+
+
+def _atomic_write_env(env_path, content):
+    """Replace an env file atomically with owner-only Unix permissions."""
+    env_path = Path(env_path)
+    env_path.parent.mkdir(parents=True, exist_ok=True)
+    temp_path = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=env_path.parent,
+            prefix=f".{env_path.name}.",
+            delete=False,
+        ) as temp_file:
+            temp_path = Path(temp_file.name)
+            temp_file.write(content)
+            temp_file.flush()
+            os.fsync(temp_file.fileno())
+        _protect_env_file(temp_path)
+        os.replace(temp_path, env_path)
+        _protect_env_file(env_path)
+    finally:
+        if temp_path and temp_path.exists():
+            try:
+                temp_path.unlink()
+            except OSError:
+                pass