feat(doctor): add health check command for environment diagnostics

README.md

@@ -13,10 +13,12 @@ A developer tool for automating setup and management of local Odoo development e
 
 - **Environment Initialization** (`init`): Creates standardized directory structure (default: `~/code/`)
 - **Repository Management** (`pull-repos`): Clones/updates Odoo and OCA repos in parallel
-- **Tool Installation** (`install-tools`): Installs from four sources: scripts, system packages, NPM, and UV tools
+- **Tool Installation** (`install-tools`): Installs from five sources: PostgreSQL repo, scripts, system packages, NPM, and UV tools
 - **Virtual Environments** (`create-venvs`): Creates Odoo venvs for each configured version
+- **Database Setup** (`ensure-db-user`): Verifies/creates PostgreSQL user for development
+- **Health Checks** (`doctor`): Validates environment health (config, SSH, tools, venvs)
 - **Interactive Mode**: Newcomer mode with confirmations and guidance
-- **Security**: HTTPS enforcement for all downloads
+- **Security**: HTTPS enforcement, SQL injection prevention, subprocess safety
 - **Custom Directory**: Use `TLC_CODE_DIR` env var to override default `~/code` location
 
 ## Installation
@@ -74,6 +76,8 @@ tlc install-tools    # Install tools
 | `tlc pull-repos` | Clone or update Odoo/OCA repositories |
 | `tlc create-venvs` | Create Python virtual environments |
 | `tlc install-tools` | Install scripts, packages, and tools |
+| `tlc ensure-db-user` | Verify or create PostgreSQL user for development |
+| `tlc doctor` | Check environment health (config, SSH, tools, venvs) |
 
 Use `--newcomer=false` to skip confirmation prompts. Use `--help` on any command for options.
 
@@ -111,6 +115,10 @@ The config file will be created at `{TLC_CODE_DIR}/config.toml`.
 
 See [Configuration Schema](./docs/project-overview-pdr.md#configuration-schema) for all options and validation rules.
 
+## System Packages
+
+When `install-tools` installs system packages, it uses a curated list that goes beyond what Odoo itself requires. The goal is to pre-install all system-level dependencies needed to compile and run any OCA module out of the box — things like `libcups2-dev` (for `pycups`), `libgeos-dev` (for `shapely`), `libxmlsec1-dev` (for `pysaml2`), `libzbar-dev` (for `pyzbar`), and more. This avoids compilation errors when installing OCA module requirements, without needing to know in advance which modules will be used.
+
 ## System Requirements
 
 - Python 3.10+

assets/oca_contributor.toml

@@ -0,0 +1,207 @@
+# Exhaustive config to contribute to OCA
+# Place this file at ~/code/config.toml (or set TLC_CODE_DIR)
+
+versions = ["18.0", "19.0"]
+
+[tools]
+uv = [
+  "copier",
+  "oca-port",
+  "odooly",
+  "odoo-venv",
+  "odoo-addons-path"
+]
+system_packages = ["postgresql"]
+
+[repos]
+odoo = ["odoo"]
+oca = [
+  # addons repositories
+  "account-analytic",
+  "account-budgeting",
+  "account-closing",
+  "account-consolidation",
+  "account-financial-reporting",
+  "account-financial-tools",
+  "account-fiscal-rule",
+  "account-invoice-reporting",
+  "account-invoicing",
+  "account-payment",
+  "account-reconcile",
+  "agreement",
+  "ai",
+  "apps-store",
+  "automation",
+  "bank-payment",
+  "bank-payment-alternative",
+  "bank-statement-import",
+  "brand",
+  "business-requirement",
+  "calendar",
+  "cim",
+  "commission",
+  "community-data-files",
+  "connector",
+  "connector-accountedge",
+  "connector-cmis",
+  "connector-ecommerce",
+  "connector-infor",
+  "connector-interfaces",
+  "connector-jira",
+  "connector-lengow",
+  "connector-lims",
+  "connector-magento",
+  "connector-odoo2odoo",
+  "connector-prestashop",
+  "connector-redmine",
+  "connector-sage",
+  "connector-salesforce",
+  "connector-spscommerce",
+  "connector-telephony",
+  "connector-woocommerce",
+  "contract",
+  "cooperative",
+  "credit-control",
+  "crm",
+  "crowdfunding",
+  "currency",
+  "data-protection",
+  "ddmrp",
+  "delivery-carrier",
+  "department",
+  "dms",
+  "donation",
+  "dotnet",
+  "e-commerce",
+  "e-learning",
+  "edi",
+  "edi-ediversa",
+  "edi-framework",
+  "edi-voxel",
+  "event",
+  "field-service",
+  "fleet",
+  "geospatial",
+  "helpdesk",
+  "hr",
+  "hr-attendance",
+  "hr-expense",
+  "hr-holidays",
+  "infrastructure",
+  "interface-github",
+  "intrastat-extrastat",
+  "iot",
+  "knowledge",
+  "l10n-brazil",
+  "l10n-france",
+  "l10n-usa",
+  "mail",
+  "maintenance",
+  "management-system",
+  "manufacture",
+  "manufacture-reporting",
+  "margin-analysis",
+  "mass-mailing",
+  "mis-builder",
+  "mis-builder-contrib",
+  "multi-company",
+  "odoo-pim",
+  "operating-unit",
+  "partner-contact",
+  "payroll",
+  "pms",
+  "pos",
+  "product-attribute",
+  "product-configurator",
+  "product-kitting",
+  "product-pack",
+  "product-variant",
+  "program",
+  "project",
+  "project-agile",
+  "project-reporting",
+  "purchase-reporting",
+  "purchase-workflow",
+  "pwa-builder",
+  "queue",
+  "repair",
+  "report-print-send",
+  "reporting-engine",
+  "resource",
+  "rest-api",
+  "rest-framework",
+  "rma",
+  "role-policy",
+  "sale-blanket",
+  "sale-channel",
+  "sale-financial",
+  "sale-prebook",
+  "sale-promotion",
+  "sale-reporting",
+  "sale-workflow",
+  "search-engine",
+  "server-auth",
+  "server-backend",
+  "server-brand",
+  "server-env",
+  "server-tools",
+  "server-ux",
+  "shift-planning",
+  "shopfloor-app",
+  "sign",
+  "social",
+  "spreadsheet",
+  "stock-logistics-availability",
+  "stock-logistics-barcode",
+  "stock-logistics-interfaces",
+  "stock-logistics-orderpoint",
+  "stock-logistics-putaway",
+  "stock-logistics-release-channel",
+  "stock-logistics-reporting",
+  "stock-logistics-request",
+  "stock-logistics-reservation",
+  "stock-logistics-shopfloor",
+  "stock-logistics-tracking",
+  "stock-logistics-transport",
+  "stock-logistics-warehouse",
+  "stock-logistics-workflow",
+  "stock-weighing",
+  "storage",
+  "survey",
+  "timesheet",
+  "vertical-abbey",
+  "vertical-agriculture",
+  "vertical-association",
+  "vertical-community",
+  "vertical-construction",
+  "vertical-cooperative-supermarket",
+  "vertical-edition",
+  "vertical-education",
+  "vertical-hotel",
+  "vertical-isp",
+  "vertical-medical",
+  "vertical-ngo",
+  "vertical-realestate",
+  "vertical-rental",
+  "vertical-travel",
+  "wallet",
+  "web",
+  "web-api",
+  "web-api-contrib",
+  "webhook",
+  "webkit-tools",
+  "website",
+  "website-cms",
+  "website-themes",
+  "wms",
+  # exceptions, new repositories
+  ["oca-custom", ["18.0"]],
+  ["tier-validation", ["19.0"]],
+  # tooling
+  ["oca-ci", ["master"]],
+  ["oca-github-bot", ["master"]],
+  ["oca-port", ["main"]],
+  ["odoo-module-migrator", ["master"]],
+]
+camptocamp = ["odoo-cloud-platform"]
+forgeflow = ["stock-rma"]

docs/code-standards.md

@@ -4,11 +4,12 @@ Development guidelines, architectural patterns, and best practices for `trobz_lo
 
 ## Project Architecture
 
-Four-layer modular design with clear separation of concerns:
+Five-layer modular design with clear separation of concerns:
 
 | Layer | Module(s) | Responsibility |
 |---|---|---|
 | **CLI Layer** | `main.py` | Command routing, user interaction, newcomer mode |
+| **Diagnostics** | `doctor.py` | Environment health checks, status enums, check result dataclasses |
 | **Implementation** | `installers.py`, `postgres.py` | Installation strategies (script, system, npm, uv); PostgreSQL user management |
 | **Utility Layer** | `utils.py` | Config validation, platform detection, helpers |
 | **Infrastructure** | `concurrency.py`, `exceptions.py` | Parallel execution, custom exceptions |
@@ -57,7 +58,10 @@ System state defined in TOML. Tool reconciles local environment with definition.
 ### 4. Observer Pattern
 `GitProgress` and `run_tasks()`: Real-time progress callbacks to Rich UI. Decoupled from execution logic.
 
-### 5. Fail-Fast Validation
+### 5. Diagnostic Pattern
+`doctor.py`: Grouped health checks returning `CheckResult` objects with `CheckStatus` enum. Enables modular diagnostics that can be combined or reused independently.
+
+### 6. Fail-Fast Validation
 Config validated at startup. Early detection prevents side effects on invalid input.
 
 ---
@@ -171,14 +175,15 @@ Follow [Conventional Commits](https://www.conventionalcommits.org/):
 
 ## File Structure
 
-**Target file size**: 500 LOC; main.py at 523 LOC is exception due to command density.
-- `main.py`: CLI commands and orchestration (523 LOC - consolidates 5 command implementations)
-- `installers.py`: Installation strategies (389 LOC - 5 installation strategies)
-- `postgres.py`: PostgreSQL user management (173 LOC)
-- `utils.py`: Config, platform detection, helpers (277 LOC)
-- `concurrency.py`: Task runner with progress (60 LOC)
-- `exceptions.py`: Custom exception classes (38 LOC)
-- `tests/`: pytest unit tests for all modules
+**Target file size**: 500 LOC; main.py at 592 LOC is exception due to command density (6 command implementations + orchestration).
+- `main.py`: CLI commands and orchestration (592 LOC - 6 commands: init, pull-repos, create-venvs, install-tools, ensure-db-user, doctor)
+- `doctor.py`: Environment health checks (~200 LOC - CheckStatus enum, CheckResult dataclass, check_* functions, run_doctor orchestrator)
+- `installers.py`: Installation strategies (391 LOC - 5 installation strategies: PostgreSQL repo, scripts, system packages, NPM, UV)
+- `postgres.py`: PostgreSQL user management (173 LOC - user validation, creation, testing)
+- `utils.py`: Config, platform detection, helpers (246 LOC - Pydantic models, OS detection, utilities)
+- `concurrency.py`: Task runner with progress (60 LOC - ThreadPoolExecutor wrapper, TaskResult dataclass)
+- `exceptions.py`: Custom exception classes (38 LOC - installer exceptions)
+- `tests/`: pytest unit tests for all modules (1006 LOC total - 6 test files)
 
 **Imports in each module**:
 - No circular imports

docs/codebase-summary.md

@@ -6,18 +6,18 @@ Technical overview of the `trobz_local` codebase structure, implementation patte
 
 | Metric | Value |
 |---|---|
-| **Version** | 0.2.0 |
+| **Version** | 0.6.0 |
 | **Language** | Python 3.10+ |
-| **Total LOC** | ~1,460 lines (core logic) + tests |
-| **Core Modules** | 7 files (main, installers, utils, postgres, concurrency, exceptions, \__init\_\_) |
-| **Test Modules** | tests/ directory with pytest unit tests |
+| **Total LOC** | 1,452 lines (core) + 982 lines (tests) |
+| **Core Modules** | 7 files (main.py 544, installers.py 391, utils.py 246, postgres.py 173, concurrency.py 60, exceptions.py 38, \__init\_\_.py) |
+| **Test Modules** | 5 test files with pytest, 982 total LOC |
 | **Primary Frameworks** | Typer (CLI), Pydantic (validation), Rich (UI), GitPython (git) |
 | **Concurrency Model** | ThreadPoolExecutor, max 4 workers, I/O-bound tasks |
 | **License** | AGPL-3.0 |
 
 ## Module Breakdown
 
-### `main.py` (523 LOC)
+### `main.py` (544 LOC)
 **Purpose**: CLI entry point and command orchestration
 
 **Responsibilities**:
@@ -45,7 +45,7 @@ Technical overview of the `trobz_local` codebase structure, implementation patte
 
 ---
 
-### `installers.py` (389 LOC)
+### `installers.py` (391 LOC)
 **Purpose**: Multi-source tool installation strategies
 
 **Strategies**:
@@ -70,7 +70,7 @@ Technical overview of the `trobz_local` codebase structure, implementation patte
 
 ---
 
-### `utils.py` (277 LOC)
+### `utils.py` (246 LOC)
 **Purpose**: Configuration validation, platform detection, utilities
 
 **Pydantic Models**:
@@ -98,7 +98,7 @@ Technical overview of the `trobz_local` codebase structure, implementation patte
 
 ---
 
-### `concurrency.py` (61 LOC)
+### `concurrency.py` (60 LOC)
 **Purpose**: Generic parallel task execution with progress tracking
 
 **TaskResult Dataclass**:
@@ -120,7 +120,7 @@ class TaskResult:
 
 ---
 
-### `exceptions.py` (39 LOC)
+### `exceptions.py` (38 LOC)
 **Purpose**: Custom exception hierarchy for granular error handling
 
 **Exception Classes**:

docs/project-overview-pdr.md

@@ -63,7 +63,7 @@ Clones or updates Odoo and OCA repositories:
 - **Operations**: Clone new repos, fetch and hard-reset existing ones
 
 ### 3. Tool Installation (`install-tools`)
-Five-stage installation pipeline:
+**Five-stage installation pipeline**:
 1. **PostgreSQL Repository** (Debian/Ubuntu only): Setup PGDG APT repository with GPG verification (idempotent)
 2. **Shell Scripts**: Download and execute scripts (e.g., uv installer)
 3. **System Packages**: OS-aware installation via apt/pacman/brew (runs after PostgreSQL repo setup on Debian/Ubuntu)
@@ -107,7 +107,7 @@ Verify or create PostgreSQL user for Odoo development:
 | **FR-1: Directory Structure** | Create `{CODE_ROOT}/` (default: `~/code/`) with `venvs/`, `oca/`, `odoo/`, `trobz/` subdirectories and version-specific folders |
 | **FR-2: Repository Operations** | Clone repos with `depth=1`, update via fetch+reset, support parallelization, allow name filtering |
 | **FR-3: Virtual Environments** | Create venvs for each Odoo version using `odoo-venv`, support parallel creation |
-| **FR-4: Tool Installation** | Four-stage pipeline: scripts → system packages → npm → uv tools; OS-aware package managers |
+| **FR-4: Tool Installation** | Five-stage pipeline: PostgreSQL repo → scripts → system packages → npm → uv tools; OS-aware package managers |
 | **FR-5: PostgreSQL User** | Verify/create PostgreSQL "odoo" user with CREATEDB permission; OS-aware execution (Linux sudo, macOS direct); connection validation |
 | **FR-6: Configuration** | TOML config at `{CODE_ROOT}/config.toml` (default: `~/code/config.toml`), strict Pydantic validation, clear error messages with examples |
 | **FR-7: User Interaction** | Interactive "newcomer mode", dry-run preview, rich console UI (progress bars, trees, colors) |