codex-core 0.1.1__tar.gz → 0.2.0__tar.gz

{codex_core-0.1.1 → codex_core-0.2.0}/.github/workflows/ci.yml

@@ -36,15 +36,18 @@ jobs:
         run: pip install mypy && mypy src/codex_core/
 
   unit-tests:
-    name: Unit Tests
+    name: Unit Tests (Python ${{ matrix.python-version }})
     needs: quality-gate
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python 3.12
+      - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
           cache: 'pip'
 
       - name: Install All Dependencies

codex_core-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,72 @@
+name: Deploy Docs
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version alias to deploy (e.g. 0.x, 1.x)'
+        required: true
+      alias:
+        description: 'Alias (latest, stable, or leave empty)'
+        required: false
+        default: 'latest'
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    name: Build & Deploy Docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Resolve version alias (tag push)
+        if: github.event_name == 'push'
+        id: version
+        run: |
+          TAG="${GITHUB_REF_NAME}"           # e.g. v1.2.3
+          MAJOR=$(echo "$TAG" | sed 's/^v//' | cut -d. -f1)
+          MINOR=$(echo "$TAG" | sed 's/^v//' | cut -d. -f2)
+          echo "alias=${MAJOR}.x" >> "$GITHUB_OUTPUT"
+
+      - name: Deploy versioned docs (tag push)
+        if: github.event_name == 'push'
+        run: |
+          mike deploy --push --update-aliases "${{ steps.version.outputs.alias }}" latest
+          mike set-default --push latest
+
+      - name: Deploy versioned docs (manual)
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          if [ -n "${{ inputs.alias }}" ]; then
+            mike deploy --push --update-aliases "${{ inputs.version }}" "${{ inputs.alias }}"
+          else
+            mike deploy --push "${{ inputs.version }}"
+          fi
+          mike set-default --push latest

{codex_core-0.1.1 → codex_core-0.2.0}/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2025-02-13
+
+### Added
+- **Python 3.13 Support**: Added official support for Python 3.13 in `pyproject.toml` classifiers.
+- **Comprehensive Unit Tests**:
+  - New tests for `core/exceptions.py` covering base exception functionality.
+  - New tests for `common/log_context.py` covering `TaskLogContext` logging methods.
+  - New tests for `common/loguru_setup.py` covering `InterceptHandler`, `setup_universal_logging`, and `setup_logging` with and without `loguru` installed.
+
+### Changed
+- **Documentation Structure**:
+  - Renamed top-level language directories from `en_EN/` to `en/` and `ru_RU/` to `ru/`.
+  - Moved `api/` documentation into `en/api/` for better language-specific grouping.
+  - Renamed `guide/` directories to `tasks/` in both `en/` and `ru/` to align with `DocArchitect:StructurePolicy` for user-oriented guides.
+  - Updated `mkdocs.yml` navigation and all internal Markdown links to reflect the new documentation structure.
+  - Updated root `README.md` to strictly follow `DocArchitect:StructurePolicy` (Layer 5 - Root Landing), including a detailed `Modules` table (with `dev` module) and a comprehensive `Part of the Codex ecosystem` section.
+- **Test Coverage Configuration**:
+  - Configured `pytest-cov` in `pyproject.toml` to include `addopts`, `[tool.coverage.run]`, and `[tool.coverage.report]` sections.
+  - Excluded `src/codex_core/dev/*` from coverage reports as these are internal development tools.
+  - Added `exclude_lines` for `TYPE_CHECKING` and `ImportError` to achieve accurate coverage metrics.
+- **Test Isolation**: Implemented `autouse` fixture `reset_pii_registry` in `tests/conftest.py` to ensure `PIIRegistry` global state is reset between tests, guaranteeing test isolation.
+- **Test Markers**: Created `tests/unit/conftest.py` and `tests/integration/conftest.py` to automatically apply `pytest.mark.unit` and `pytest.mark.integration` markers to tests within their respective directories.
+
+### Fixed
+- **Mypy Errors**: Resolved missing type parameters for generic types in `src/codex_core/dev/static_compiler/compiler.py` and `src/codex_core/dev/static_compiler/css.py`.
+- **Ruff Errors**: Resolved `SIM118` (Use `key in dict` instead of `key in dict.keys()`) in `src/codex_core/core/pii.py`.
+- **Ruff Errors**: Resolved `SIM117` (Use a single `with` statement with multiple contexts) in `tests/unit/common/test_loguru_setup.py`.
+- **Test Coverage Gaps**:
+  - Covered `PIIRegistry` initialization logic and recursive list masking in `tests/unit/core/test_pii.py`.
+  - Covered falsy input handling in `transliterate` and `sanitize_for_sms` functions in `tests/unit/common/test_text.py`.
+
 ## [0.1.1] - 2025-02-12
 
 ### Added

{codex_core-0.1.1 → codex_core-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-core
-Version: 0.1.1
+Version: 0.2.0
 Summary: Core utilities, schemas and settings for Codex WaaS toolkit
 Project-URL: Homepage, https://github.com/codexdlc/codex-core
 Project-URL: Documentation, https://codexdlc.github.io/codex-core/
@@ -16,6 +16,7 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Requires-Python: >=3.10
 Requires-Dist: pydantic-settings>=2.0
@@ -31,6 +32,7 @@ Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Provides-Extra: docs
+Requires-Dist: mike>=2.0; extra == 'docs'
 Requires-Dist: mkdocs-include-markdown-plugin; extra == 'docs'
 Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
 Requires-Dist: mkdocs>=1.5; extra == 'docs'
@@ -39,41 +41,66 @@ Provides-Extra: loguru
 Requires-Dist: loguru>=0.7.0; extra == 'loguru'
 Description-Content-Type: text/markdown
 
+<!-- Type: LANDING -->
 # codex-core
 
-**Core utilities, schemas, and settings for the Codex WaaS toolkit.**
-
 [![PyPI](https://img.shields.io/pypi/v/codex-core)](https://pypi.org/project/codex-core/)
 [![Python](https://img.shields.io/pypi/pyversions/codex-core)](https://pypi.org/project/codex-core/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-green)](https://github.com/codexdlc/codex-core/blob/main/LICENSE)
 [![Documentation](https://img.shields.io/badge/docs-codexdlc.github.io-blue)](https://codexdlc.github.io/codex-core/)
 
-This library provides the foundational building blocks used by all other Codex tools. It focuses on Pydantic-based data models, structured logging, and configuration management.
-
-> **Documentation:**
-> [EN](https://codexdlc.github.io/codex-core/en_EN/) · [RU](https://codexdlc.github.io/codex-core/ru_RU/) · [API Reference](https://codexdlc.github.io/codex-core/api/) · [Changelog](https://codexdlc.github.io/codex-core/changelog/)
+Core utilities, immutable DTOs, and environment-driven settings for the Codex WaaS toolkit.
+Provides the foundational building blocks and PII masking used by all other Codex components.
 
-## 🚀 Key Features
-
-*   **Core Interfaces**: Base classes and protocols for Codex components.
-*   **Common Utilities**: Logger setup (Loguru), phone number validation, text processing, and caching.
-*   **Schemas**: Shared Pydantic models for cross-service communication.
-*   **Settings**: Modern configuration management using `pydantic-settings`.
+---
 
-## 📦 Installation
+## Install
 
 ```bash
+# Core only
 pip install codex-core
+
+# With Loguru support for advanced structured logging
+pip install "codex-core[loguru]"
 ```
 
-## 🛠️ Quick Start
+## Quick Start
 
 ```python
-from codex_tools.common.logger import setup_logger
+from codex_core.core.base_dto import BaseDTO
+
+# 1. Define an immutable, PII-aware data transfer object
+class UserDTO(BaseDTO):
+    id: int
+    email: str         # Automatically masked in logs
+    phone_number: str  # Automatically masked in logs
+
+user = UserDTO(id=42, email="user@example.com", phone_number="+491511234567")
 
-logger = setup_logger("my-app")
-logger.info("Codex Core is ready!")
+# 2. Safely log the DTO without leaking personal data
+print(user)
+# Output: UserDTO(id=42, email='***', phone_number='***')
 ```
 
----
-*Part of the [Codex WaaS](https://github.com/codexdlc) ecosystem. · [EN Docs](https://codexdlc.github.io/codex-core/en_EN/) · [RU Docs](https://codexdlc.github.io/codex-core/ru_RU/) · [API](https://codexdlc.github.io/codex-core/api/) · [Changelog](https://codexdlc.github.io/codex-core/changelog/) · [Source](https://github.com/codexdlc/codex-core)*
+## Modules
+
+| Module | Extra | Description |
+| :--- | :--- | :--- |
+| `codex_core.core` | - | Immutable `BaseDTO` and automated `PIIRegistry` for GDPR-safe logging. |
+| `codex_core.common` | `[loguru]` | Phone/name normalization and structured logging adapters (`TaskLogContext`). |
+| `codex_core.settings` | - | Environment-driven configuration via `BaseCommonSettings` (Pydantic Settings). |
+| `codex_core.dev` | `[dev]` | Internal developer tools (`BaseCheckRunner`, `StaticCompiler`, `ProjectTreeGenerator`). |
+
+## Documentation
+
+Full docs with architecture, API reference, and data flow diagrams:
+
+**[https://codexdlc.github.io/codex-core/](https://codexdlc.github.io/codex-core/)**
+
+## Part of the Codex ecosystem
+
+- **[codex-core](https://github.com/codexdlc/codex-core)**: Foundational utilities and DTOs.
+- **[codex-platform](https://github.com/codexdlc/codex-platform)**: Core platform components and HTTP APIs.
+- **[codex-bot](https://github.com/codexdlc/codex-bot)**: Telegram AI-agent infrastructure.
+- **[codex-services](https://github.com/codexdlc/codex-services)**: Business logic engines (Booking, CRM).
+- **[codex-ai](https://github.com/codexdlc/codex-ai)**: LLM abstraction layer.

codex_core-0.2.0/README.md

@@ -0,0 +1,63 @@
+<!-- Type: LANDING -->
+# codex-core
+
+[![PyPI](https://img.shields.io/pypi/v/codex-core)](https://pypi.org/project/codex-core/)
+[![Python](https://img.shields.io/pypi/pyversions/codex-core)](https://pypi.org/project/codex-core/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green)](https://github.com/codexdlc/codex-core/blob/main/LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-codexdlc.github.io-blue)](https://codexdlc.github.io/codex-core/)
+
+Core utilities, immutable DTOs, and environment-driven settings for the Codex WaaS toolkit.
+Provides the foundational building blocks and PII masking used by all other Codex components.
+
+---
+
+## Install
+
+```bash
+# Core only
+pip install codex-core
+
+# With Loguru support for advanced structured logging
+pip install "codex-core[loguru]"
+```
+
+## Quick Start
+
+```python
+from codex_core.core.base_dto import BaseDTO
+
+# 1. Define an immutable, PII-aware data transfer object
+class UserDTO(BaseDTO):
+    id: int
+    email: str         # Automatically masked in logs
+    phone_number: str  # Automatically masked in logs
+
+user = UserDTO(id=42, email="user@example.com", phone_number="+491511234567")
+
+# 2. Safely log the DTO without leaking personal data
+print(user)
+# Output: UserDTO(id=42, email='***', phone_number='***')
+```
+
+## Modules
+
+| Module | Extra | Description |
+| :--- | :--- | :--- |
+| `codex_core.core` | - | Immutable `BaseDTO` and automated `PIIRegistry` for GDPR-safe logging. |
+| `codex_core.common` | `[loguru]` | Phone/name normalization and structured logging adapters (`TaskLogContext`). |
+| `codex_core.settings` | - | Environment-driven configuration via `BaseCommonSettings` (Pydantic Settings). |
+| `codex_core.dev` | `[dev]` | Internal developer tools (`BaseCheckRunner`, `StaticCompiler`, `ProjectTreeGenerator`). |
+
+## Documentation
+
+Full docs with architecture, API reference, and data flow diagrams:
+
+**[https://codexdlc.github.io/codex-core/](https://codexdlc.github.io/codex-core/)**
+
+## Part of the Codex ecosystem
+
+- **[codex-core](https://github.com/codexdlc/codex-core)**: Foundational utilities and DTOs.
+- **[codex-platform](https://github.com/codexdlc/codex-platform)**: Core platform components and HTTP APIs.
+- **[codex-bot](https://github.com/codexdlc/codex-bot)**: Telegram AI-agent infrastructure.
+- **[codex-services](https://github.com/codexdlc/codex-services)**: Business logic engines (Booking, CRM).
+- **[codex-ai](https://github.com/codexdlc/codex-ai)**: LLM abstraction layer.

{codex_core-0.1.1/docs/en_EN → codex_core-0.2.0/docs/en}/README.md

@@ -1,4 +1,4 @@
-[🏠 Home](../index.md) | [🧭 Guide (EN)](README.md) | [⚙️ API Reference](../api/index.md)
+[🏠 Home](../index.md) | [🧭 Guide (EN)](README.md) | [⚙️ API Reference](api/index.md)
 
 # Guide: Overview (EN)
 
@@ -6,7 +6,7 @@ Welcome to the **codex-core** guide! This library serves as the shared foundatio
 
 ## Documentation Sections
 
-### 1. [Getting Started](guide/getting_started.md)
+### 1. [Getting Started](tasks/getting_started.md)
 How to install and integrate `codex-core` into your project.
 
 ### 2. [🛡️ Architecture & Platform](architecture/README.md)
@@ -19,5 +19,5 @@ Detailed breakdown of the core platform components:
 ### 3. [🗺 Evolution](../evolution/roadmap.md)
 Our core purpose and development philosophy.
 
-### 4. [⚙️ API Reference](../api/index.md)
+### 4. [⚙️ API Reference](api/index.md)
 Technical details for developers.

{codex_core-0.1.1/docs → codex_core-0.2.0/docs/en}/api/common.md

@@ -1,4 +1,4 @@
-[🏠 Home](../index.md) | [⚙️ API Reference](index.md) | [🛠️ Common API](common.md)
+[🏠 Home](../../index.md) | [⚙️ API Reference](index.md) | [🛠️ Common API](common.md)
 
 # 🛠️ Common API (Utilities)
 

{codex_core-0.1.1/docs → codex_core-0.2.0/docs/en}/api/core.md

@@ -1,4 +1,4 @@
-[🏠 Home](../index.md) | [⚙️ API Reference](index.md) | [🛡️ Core API](core.md)
+[🏠 Home](../../index.md) | [⚙️ API Reference](index.md) | [🛡️ Core API](core.md)
 
 # 🛡️ Core API (DTO & PII)
 

codex_core-0.2.0/docs/en/api/dev.md

@@ -0,0 +1,29 @@
+# Dev Tools — API Reference
+
+## BaseCheckRunner
+
+::: codex_core.dev.check_runner.BaseCheckRunner
+
+---
+
+## StaticCompiler
+
+::: codex_core.dev.static_compiler.compiler.StaticCompiler
+
+---
+
+## CSSCompiler
+
+::: codex_core.dev.static_compiler.css.CSSCompiler
+
+---
+
+## JSCompiler
+
+::: codex_core.dev.static_compiler.js.JSCompiler
+
+---
+
+## ProjectTreeGenerator
+
+::: codex_core.dev.project_tree.ProjectTreeGenerator

{codex_core-0.1.1/docs → codex_core-0.2.0/docs/en}/api/index.md

@@ -1,4 +1,4 @@
-[🏠 Home](../index.md) | [🧭 Guide (EN)](../en_EN/README.md) | [⚙️ API Reference](index.md)
+[🏠 Home](../../index.md) | [🧭 Guide (EN)](../README.md) | [⚙️ API Reference](index.md)
 
 # API Reference Overview
 
@@ -9,6 +9,7 @@ Welcome to the **codex-core** API Reference! This section provides detailed info
 - **[🛡️ Core (DTO & PII)](core.md)**: Base data models and PII protection utilities.
 - **[🛠️ Common (Utilities)](common.md)**: Phone, text, and logging helpers.
 - **[⚙️ Settings (Config)](settings.md)**: Base configuration patterns.
+- **[🛠️ Dev Tools](dev.md)**: Internal developer tools.
 
 ## Technical Details
 

{codex_core-0.1.1/docs → codex_core-0.2.0/docs/en}/api/settings.md

@@ -1,4 +1,4 @@
-[🏠 Home](../index.md) | [⚙️ API Reference](index.md) | [⚙️ Settings API](settings.md)
+[🏠 Home](../../index.md) | [⚙️ API Reference](index.md) | [⚙️ Settings API](settings.md)
 
 # ⚙️ Settings API (Base Configuration)
 

{codex_core-0.1.1/docs/en_EN → codex_core-0.2.0/docs/en}/architecture/README.md

@@ -1,4 +1,4 @@
-[🏠 Home](../../index.md) | [🧭 Guide (EN)](../README.md) | [🛡️ Architecture](../../api/index.md)
+[🏠 Home](../../index.md) | [🧭 Guide (EN)](../README.md) | [🛡️ Architecture](../api/index.md)
 
 # 🛡️ Architecture & Platform Overview (EN)
 

{codex_core-0.1.1/docs/en_EN → codex_core-0.2.0/docs/en}/architecture/platform/common.md

@@ -1,4 +1,4 @@
-[🏠 Home](../../../index.md) | [🧭 Guide (EN)](../../README.md) | [🛠️ Common API](../../../api/common.md)
+[🏠 Home](../../../index.md) | [🧭 Guide (EN)](../../README.md) | [🛠️ Common API](../../api/common.md)
 
 # 🛠️ Common: Utilities (Architecture)
 

{codex_core-0.1.1/docs/en_EN → codex_core-0.2.0/docs/en}/architecture/platform/core.md

@@ -1,4 +1,4 @@
-[🏠 Home](../../../index.md) | [🧭 Guide (EN)](../../README.md) | [🛡️ Core API](../../../api/core.md)
+[🏠 Home](../../../index.md) | [🧭 Guide (EN)](../../README.md) | [🛡️ Core API](../../api/core.md)
 
 # 🛡️ Core: PII & DTO (Architecture)
 

codex_core-0.2.0/docs/en/architecture/platform/dev.md

@@ -0,0 +1,225 @@
+[🏠 Home](../../../index.md) | [🧭 Guide (EN)](../../README.md) | [🛠️ Dev API](../../api/dev.md)
+
+# Dev Tools (Architecture)
+
+The `dev` module provides reusable development utilities shared across all **Codex** projects.
+All tools are **pure Python** (stdlib only) — no external dependencies required.
+
+---
+
+## 1. BaseCheckRunner — Quality Gate
+
+A base class for project-level quality gate scripts. Every Codex project has a `tools/dev/check.py`
+that inherits from `BaseCheckRunner` and overrides only what differs.
+
+### Standardized behavior (base class)
+
+| Check | Command |
+|-------|---------|
+| Quality | `pre-commit run --all-files` |
+| Types | `sys.executable -m mypy src/` |
+| Security | `pip-audit --skip-editable` |
+| Unit tests | `pytest -m unit -v --tb=short` |
+| Integration | `pytest -m integration -v --tb=short` |
+
+`--skip-editable` ensures pip-audit only scans real PyPI packages,
+not locally installed editable codex-* dependencies.
+
+### CLI interface
+
+```bash
+python tools/dev/check.py --lint        # pre-commit only
+python tools/dev/check.py --types       # mypy only
+python tools/dev/check.py --security    # pip-audit only
+python tools/dev/check.py --tests unit
+python tools/dev/check.py --tests integration
+python tools/dev/check.py --all         # lint + types + security + unit, asks about integration
+python tools/dev/check.py --ci          # everything non-interactively (GitHub Actions)
+```
+
+### Usage in a project
+
+```python
+# tools/dev/check.py
+from pathlib import Path
+from codex_core.dev.check_runner import BaseCheckRunner
+
+class CheckRunner(BaseCheckRunner):
+    PROJECT_NAME = "my-project"
+    INTEGRATION_REQUIRES = "Redis"
+
+if __name__ == "__main__":
+    CheckRunner(Path(__file__).parent.parent.parent).main()
+```
+
+### Extending for Docker or migrations
+
+Override `extra_checks()` to add project-specific gates:
+
+```python
+class CheckRunner(BaseCheckRunner):
+    PROJECT_NAME = "codex-django"
+    INTEGRATION_REQUIRES = "PostgreSQL + Redis"
+
+    def extra_checks(self) -> bool:
+        # manage.py check, migrate --check, etc.
+        return True
+```
+
+### CI-specific override (codex-ai pattern)
+
+When integration tests require API keys that may be absent, override `run_tests()`
+to add `--no-cov` so the coverage threshold gate does not fail on 0 collected tests:
+
+```python
+def run_tests(self, marker: str = "unit") -> bool:
+    if marker == "integration":
+        success, _ = self.run_command(
+            f'"{sys.executable}" -m pytest {self.tests_dir}'
+            f" -m integration -v --tb=short --no-cov"
+        )
+        return success
+    return super().run_tests(marker)
+```
+
+---
+
+## 2. ProjectTreeGenerator
+
+Generates a human-readable directory tree of any project and saves it to `project_structure.txt`.
+Useful for documentation, onboarding, and architecture reviews.
+
+### Features
+
+- Interactive menu — pick a single top-level folder or scan the full project
+- Pre-configured ignore lists (`.venv`, `__pycache__`, `node_modules`, etc.)
+- Extendable: pass custom `ignore_dirs` / `ignore_extensions` sets
+
+### Usage in a project
+
+```python
+# tools/dev/generate_project_tree.py
+from pathlib import Path
+from codex_core.dev.project_tree import ProjectTreeGenerator
+
+if __name__ == "__main__":
+    ProjectTreeGenerator(Path(__file__).parent.parent.parent).interactive()
+```
+
+### Programmatic usage
+
+```python
+gen = ProjectTreeGenerator(root=Path("/my/project"))
+
+# Full project → project_structure.txt
+gen.generate(target_dir=None, output=Path("project_structure.txt"))
+
+# Only the src/ folder
+gen.generate(target_dir="src", output=Path("src_structure.txt"))
+
+# Custom ignore list
+gen = ProjectTreeGenerator(
+    root=Path("/my/project"),
+    ignore_dirs=frozenset({".git", ".venv", "build"}),
+)
+```
+
+---
+
+## 3. StaticCompiler — CSS & JS Bundler
+
+A pure Python static asset compiler. Resolves CSS `@import` chains and concatenates
+JS source files into bundles. No Node.js, no external packages required.
+
+### Sub-modules
+
+| Module | Responsibility |
+|--------|---------------|
+| `css.py` | Resolve `@import url(...)`, remove comments, minify |
+| `js.py` | Concatenate sources, remove comments, minify |
+| `compiler.py` | Orchestration, config parsing, two modes |
+
+### Config format (`compiler_config.json`)
+
+```json
+{
+    "css": {
+        "base.css": "app.css"
+    },
+    "js": {
+        "app.js": ["vendor/alpine.js", "src/main.js", "src/ui.js"]
+    }
+}
+```
+
+Old CSS-only format is supported for backwards compatibility:
+```json
+{ "base.css": "app.css" }
+```
+
+### Mode 1 — Single project
+
+```python
+from pathlib import Path
+from codex_core.dev.static_compiler import StaticCompiler
+
+root = Path(__file__).parent.parent.parent
+static = root / "src" / "backend_django" / "static"
+
+StaticCompiler().compile_from_config(
+    config=static / "css" / "compiler_config.json",
+    css_dir=static / "css",
+    js_dir=static / "js",
+)
+```
+
+### Mode 2 — Multi-project (landings)
+
+Compile multiple sub-projects from a single master settings file:
+
+```json
+{
+    "projects": [
+        {
+            "name": "landing-ru",
+            "config": "src/landing_ru/static/css/compiler_config.json",
+            "css_dir": "src/landing_ru/static/css",
+            "js_dir":  "src/landing_ru/static/js"
+        },
+        {
+            "name": "landing-en",
+            "config": "src/landing_en/static/css/compiler_config.json"
+        }
+    ]
+}
+```
+
+```python
+StaticCompiler().compile_from_settings(Path("static_settings.json"))
+```
+
+### Flags
+
+```python
+StaticCompiler(css=True, js=False)               # CSS only
+StaticCompiler(js=True, css=False)               # JS only
+StaticCompiler(minify=True)                      # full minification
+StaticCompiler(remove_comments=False)            # keep comments
+```
+
+### Project-level entry point
+
+```python
+# tools/static/compile.py  (project-specific, ~10 lines)
+from pathlib import Path
+from codex_core.dev.static_compiler import StaticCompiler
+
+if __name__ == "__main__":
+    root = Path(__file__).parent.parent.parent
+    static = root / "src" / "backend_django" / "static"
+    StaticCompiler().compile_from_config(
+        config=static / "css" / "compiler_config.json",
+        css_dir=static / "css",
+        js_dir=static / "js",
+    )
+```

{codex_core-0.1.1/docs/en_EN → codex_core-0.2.0/docs/en}/architecture/platform/settings.md

@@ -1,4 +1,4 @@
-[🏠 Home](../../../index.md) | [🧭 Guide (EN)](../../README.md) | [⚙️ Settings API](../../../api/settings.md)
+[🏠 Home](../../../index.md) | [🧭 Guide (EN)](../../README.md) | [⚙️ Settings API](../../api/settings.md)
 
 # ⚙️ Settings: Config Architecture
 

{codex_core-0.1.1 → codex_core-0.2.0}/docs/evolution/roadmap.md

@@ -1,4 +1,4 @@
-[🏠 Home](../index.md) | [🧭 Guide (EN)](../en_EN/README.md) | [🗺 Roadmap](roadmap.md)
+[🏠 Home](../index.md) | [🧭 Guide (EN)](../en/README.md) | [🗺 Roadmap](roadmap.md)
 
 # Evolution & Philosophy