odoorun 0.1.1__tar.gz

odoorun-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish package
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

odoorun-0.1.1/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

odoorun-0.1.1/.python-version

@@ -0,0 +1 @@
+3.10

odoorun-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khalid A. Dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

odoorun-0.1.1/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: odoorun
+Version: 0.1.1
+Summary: A modern CLI for running and managing Odoo projects.
+Project-URL: Homepage, https://github.com/khalid99io/odoorun
+Project-URL: Repository, https://github.com/khalid99io/odoorun
+Project-URL: Issues, https://github.com/khalid99io/odoorun/issues
+Author-email: "Khalid A. Dev" <khalid.a.dev@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,odoo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.26.8
+Description-Content-Type: text/markdown
+
+# odoorun
+
+`odoorun` is a portable command-line launcher for Odoo. It finds an Odoo
+executable from the current project (or a parent directory), prepares the
+appropriate addons path, and forwards the remaining arguments unchanged.
+
+It does not require symlinks, shell aliases, a modified `.bashrc`, or a
+machine-specific configuration.
+
+## Requirements
+
+- Python 3.10 or newer
+- An Odoo installation or source checkout
+- `psql` is optional and is used only for database completion/diagnostics
+
+Odoo and PostgreSQL are external dependencies; `odoorun` does not install or
+configure them.
+
+## Installation
+
+### Recommended: install from PyPI
+
+Once published, install it on any supported machine with:
+
+```bash
+uv tool install odoorun
+```
+
+Or use pip:
+
+```bash
+python -m pip install odoorun
+```
+
+### Install directly from GitHub
+
+```bash
+uv tool install git+https://github.com/khalid99io/odoorun.git
+```
+
+### Install a local checkout (development)
+
+```bash
+uv tool install .
+```
+
+After changing the checkout, refresh the installed command:
+
+```bash
+uv tool install --force .
+```
+
+## Usage
+
+Run from an Odoo source checkout or any directory below it:
+
+```bash
+odoorun -d my_database --dev=all
+```
+
+The short command `o` is optional and is not installed by this package. If
+desired, add your own alias or shell function:
+
+```bash
+alias o=odoorun
+```
+
+### Virtual-environment projects
+
+For a project directory named `my-project`, `odoorun` looks for:
+
+```text
+~/venvs/my-project/bin/odoo
+```
+
+When found, it adds `--addons=odoo/addons` automatically. If the virtual
+environment has a different name, configure it without editing the package:
+
+```bash
+export ODOORUN_VENV_NAME=my-project-venv
+export ODOORUN_VENV_ROOT="$HOME/venvs"
+```
+
+The tool invokes the venv executable directly; sourcing `activate` is not
+required for the launched Odoo process. A subprocess cannot change the parent
+shell's prompt, so prompt decoration remains a shell responsibility.
+
+### Odoo source checkouts
+
+For a checkout containing an executable `odoo-bin`, the built-in `addons`
+directory is passed automatically. Additional addon directories can be listed
+with `-a` or `--addons-path`; relative paths are resolved from the checkout's
+parent directory:
+
+```bash
+odoorun -a custom-addons,enterprise -d my_database
+```
+
+Each directory must exist. Missing directories are reported before Odoo starts.
+
+## Diagnostics
+
+```bash
+odoorun doctor
+odoorun --help
+odoorun --version
+```
+
+## Development
+
+```bash
+uv run python -m unittest discover -s tests -v
+uv run python -m compileall -q src tests
+```
+
+## Publishing
+
+The source repository is hosted on GitHub:
+
+https://github.com/khalid99io/odoorun
+
+To publish releases on PyPI, create a PyPI account, configure a trusted
+publisher for this GitHub repository (recommended), build the package, and
+upload it with `twine` or a GitHub Actions release workflow. A GitHub account
+is required for the repository; a separate PyPI account is required to publish
+the `odoorun` package name.
+
+Before the first release, update the version in `pyproject.toml`, add release
+notes, and verify the package in a clean virtual environment.

odoorun-0.1.1/README.md

@@ -0,0 +1,129 @@
+# odoorun
+
+`odoorun` is a portable command-line launcher for Odoo. It finds an Odoo
+executable from the current project (or a parent directory), prepares the
+appropriate addons path, and forwards the remaining arguments unchanged.
+
+It does not require symlinks, shell aliases, a modified `.bashrc`, or a
+machine-specific configuration.
+
+## Requirements
+
+- Python 3.10 or newer
+- An Odoo installation or source checkout
+- `psql` is optional and is used only for database completion/diagnostics
+
+Odoo and PostgreSQL are external dependencies; `odoorun` does not install or
+configure them.
+
+## Installation
+
+### Recommended: install from PyPI
+
+Once published, install it on any supported machine with:
+
+```bash
+uv tool install odoorun
+```
+
+Or use pip:
+
+```bash
+python -m pip install odoorun
+```
+
+### Install directly from GitHub
+
+```bash
+uv tool install git+https://github.com/khalid99io/odoorun.git
+```
+
+### Install a local checkout (development)
+
+```bash
+uv tool install .
+```
+
+After changing the checkout, refresh the installed command:
+
+```bash
+uv tool install --force .
+```
+
+## Usage
+
+Run from an Odoo source checkout or any directory below it:
+
+```bash
+odoorun -d my_database --dev=all
+```
+
+The short command `o` is optional and is not installed by this package. If
+desired, add your own alias or shell function:
+
+```bash
+alias o=odoorun
+```
+
+### Virtual-environment projects
+
+For a project directory named `my-project`, `odoorun` looks for:
+
+```text
+~/venvs/my-project/bin/odoo
+```
+
+When found, it adds `--addons=odoo/addons` automatically. If the virtual
+environment has a different name, configure it without editing the package:
+
+```bash
+export ODOORUN_VENV_NAME=my-project-venv
+export ODOORUN_VENV_ROOT="$HOME/venvs"
+```
+
+The tool invokes the venv executable directly; sourcing `activate` is not
+required for the launched Odoo process. A subprocess cannot change the parent
+shell's prompt, so prompt decoration remains a shell responsibility.
+
+### Odoo source checkouts
+
+For a checkout containing an executable `odoo-bin`, the built-in `addons`
+directory is passed automatically. Additional addon directories can be listed
+with `-a` or `--addons-path`; relative paths are resolved from the checkout's
+parent directory:
+
+```bash
+odoorun -a custom-addons,enterprise -d my_database
+```
+
+Each directory must exist. Missing directories are reported before Odoo starts.
+
+## Diagnostics
+
+```bash
+odoorun doctor
+odoorun --help
+odoorun --version
+```
+
+## Development
+
+```bash
+uv run python -m unittest discover -s tests -v
+uv run python -m compileall -q src tests
+```
+
+## Publishing
+
+The source repository is hosted on GitHub:
+
+https://github.com/khalid99io/odoorun
+
+To publish releases on PyPI, create a PyPI account, configure a trusted
+publisher for this GitHub repository (recommended), build the package, and
+upload it with `twine` or a GitHub Actions release workflow. A GitHub account
+is required for the repository; a separate PyPI account is required to publish
+the `odoorun` package name.
+
+Before the first release, update the version in `pyproject.toml`, add release
+notes, and verify the package in a clean virtual environment.

odoorun-0.1.1/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "odoorun"
+version = "0.1.1"
+description = "A modern CLI for running and managing Odoo projects."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Khalid A. Dev", email = "khalid.a.dev@gmail.com" }]
+requires-python = ">=3.10"
+keywords = ["cli", "odoo"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "rich>=15.0.0",
+    "typer>=0.26.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/khalid99io/odoorun"
+Repository = "https://github.com/khalid99io/odoorun"
+Issues = "https://github.com/khalid99io/odoorun/issues"
+
+[project.scripts]
+odoorun = "odoorun.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "UP"]

odoorun-0.1.1/src/odoorun/__init__.py

@@ -0,0 +1,8 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("odoorun")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+__all__ = ["__version__"]

odoorun-0.1.1/src/odoorun/__main__.py

@@ -0,0 +1,81 @@
+import sys
+
+from rich.console import Console
+from rich.markup import escape
+
+from .cli import cli
+from .discovery import OdooExecutableNotFoundError
+from .runner import OdooArgumentError, OdooExecutionError, run_odoo
+
+ODOORUN_ARGUMENTS = {
+    "--help",
+    "--version",
+    "-h",
+    "doctor",
+}
+
+error_console = Console(stderr=True)
+
+
+def show_odoo_not_found(error: OdooExecutableNotFoundError) -> None:
+    error_console.print()
+    error_console.print("[bold red]Odoo executable not found[/bold red]")
+    error_console.print(
+        "odoorun looked for [bold]odoo-bin[/bold] in "
+        f"[cyan]{escape(str(error.directory))}[/cyan] or its parents, and "
+        "[bold]odoo[/bold] on your PATH."
+    )
+    error_console.print()
+    error_console.print("[bold]Try one of these:[/bold]")
+
+    if error.non_executable is not None:
+        candidate = escape(str(error.non_executable))
+        error_console.print(
+            f"  • Make [cyan]{candidate}[/cyan] executable with "
+            f"[bold]chmod +x {candidate}[/bold]."
+        )
+    else:
+        error_console.print(
+            "  • Run [bold]odoorun[/bold] from inside an Odoo source directory."
+        )
+
+    error_console.print("  • Install Odoo or add its executable to your PATH.")
+
+
+def show_execution_error(error: OdooExecutionError) -> None:
+    error_console.print()
+    error_console.print("[bold red]Odoo could not be started[/bold red]")
+    error_console.print(
+        f"[cyan]{escape(error.executable)}[/cyan]: {escape(error.reason)}"
+    )
+    error_console.print("Check the file permissions and try again.")
+
+
+def show_argument_error(error: OdooArgumentError) -> None:
+    error_console.print()
+    error_console.print("[bold red]Invalid Odoo addons configuration[/bold red]")
+    error_console.print(f"[yellow]{escape(str(error))}[/yellow]")
+
+
+def main() -> None:
+    argv = sys.argv[1:]
+
+    if argv and argv[0] in ODOORUN_ARGUMENTS:
+        cli(args=argv, prog_name="odoorun")
+        return
+
+    try:
+        run_odoo(argv)
+    except OdooExecutableNotFoundError as error:
+        show_odoo_not_found(error)
+        raise SystemExit(1) from None
+    except OdooExecutionError as error:
+        show_execution_error(error)
+        raise SystemExit(1) from None
+    except OdooArgumentError as error:
+        show_argument_error(error)
+        raise SystemExit(2) from None
+
+
+if __name__ == "__main__":
+    main()

odoorun-0.1.1/src/odoorun/cli.py

@@ -0,0 +1,88 @@
+import shutil
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+
+from . import __version__
+from .discovery import OdooExecutableNotFoundError, find_odoo_executable
+
+cli = typer.Typer(
+    add_completion=False,
+    help="Run Odoo from any directory inside an Odoo project.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+
+
+def show_version(value: bool) -> None:
+    if value:
+        typer.echo(f"odoorun {__version__}")
+        raise typer.Exit()
+
+
+@cli.callback()
+def root(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            callback=show_version,
+            is_eager=True,
+            help="Show the installed version and exit.",
+        ),
+    ] = False,
+) -> None:
+    """Inspect the environment or pass arguments directly to Odoo."""
+
+
+@cli.command()
+def doctor() -> None:
+    """Check whether odoorun can locate its external dependencies."""
+    console = Console()
+    current = Path.cwd().resolve()
+    psql = shutil.which("psql")
+
+    try:
+        executable = find_odoo_executable(current)
+        odoo_status = f"[green]found[/green] — {escape(executable)}"
+        healthy = True
+    except OdooExecutableNotFoundError as error:
+        if error.non_executable is not None:
+            detail = f"not executable — {escape(str(error.non_executable))}"
+        else:
+            detail = "not found"
+        odoo_status = f"[red]{detail}[/red]"
+        healthy = False
+
+    table = Table(title="odoorun doctor", show_header=False, box=None)
+    table.add_column(style="bold")
+    table.add_column()
+    table.add_row("Working directory", escape(str(current)))
+    table.add_row("Odoo", odoo_status)
+    table.add_row(
+        "PostgreSQL client",
+        (
+            f"[green]found[/green] — {escape(psql)}"
+            if psql
+            else "[yellow]not found[/yellow]"
+        ),
+    )
+    console.print(table)
+
+    if not healthy:
+        console.print(
+            "\n[red]Odoo is not ready.[/red] Run this command inside an Odoo "
+            "checkout or add [bold]odoo[/bold] to your PATH."
+        )
+        raise typer.Exit(1)
+
+    if psql is None:
+        console.print(
+            "\n[yellow]Odoo is ready, but database completion requires psql.[/yellow]"
+        )
+    else:
+        console.print("\n[green]Everything looks ready.[/green]")

odoorun-0.1.1/src/odoorun/completion/database.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import subprocess
+
+QUERY_TIMEOUT_SECONDS = 2
+
+
+def complete(prefix: str) -> list[str]:
+    """Return PostgreSQL databases matching ``prefix``.
+
+    Completion must stay responsive, so unavailable or slow PostgreSQL
+    connections are treated as having no suggestions.
+    """
+    command = [
+        "psql",
+        "-Atqc",
+        "SELECT datname FROM pg_database WHERE datistemplate = false;",
+    ]
+
+    try:
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=QUERY_TIMEOUT_SECONDS,
+        )
+    except (subprocess.SubprocessError, OSError, UnicodeError):
+        return []
+
+    return sorted(
+        {
+            database
+            for database in result.stdout.splitlines()
+            if database and database.startswith(prefix)
+        }
+    )

odoorun-0.1.1/src/odoorun/completion/engine.py

@@ -0,0 +1,15 @@
+from collections.abc import Callable
+
+from . import database
+
+Completer = Callable[[str], list[str]]
+
+COMPLETERS: dict[str, Completer] = {
+    "database": database.complete,
+}
+
+
+def complete(kind: str, prefix: str) -> list[str]:
+    """Return completion candidates for a registered completion kind."""
+    completer = COMPLETERS.get(kind)
+    return completer(prefix) if completer is not None else []

odoorun-0.1.1/src/odoorun/discovery.py

@@ -0,0 +1,89 @@
+import os
+import shutil
+from pathlib import Path
+
+
+class OdooExecutableNotFoundError(RuntimeError):
+    """Raised when no runnable Odoo executable can be discovered."""
+
+    def __init__(
+        self,
+        directory: Path,
+        non_executable: Path | None = None,
+    ) -> None:
+        self.directory = directory
+        self.non_executable = non_executable
+        super().__init__("Could not locate an Odoo executable.")
+
+
+def find_local_odoo_executable(
+    start_directory: Path,
+) -> tuple[Path | None, Path | None]:
+    """Find an executable ``odoo-bin`` in a directory or one of its parents.
+
+    The second item is the nearest non-executable candidate, when one exists.
+    """
+    non_executable: Path | None = None
+
+    for directory in (start_directory, *start_directory.parents):
+        candidate = directory / "odoo-bin"
+
+        if not candidate.is_file():
+            continue
+
+        if os.access(candidate, os.X_OK):
+            return candidate, non_executable
+
+        if non_executable is None:
+            non_executable = candidate
+
+    return None, non_executable
+
+
+def _venv_names(project_name: str) -> tuple[str, ...]:
+    """Return configured and conventional virtual-environment names."""
+    configured = os.environ.get("ODOORUN_VENV_NAME", "").strip()
+    return tuple(dict.fromkeys(name for name in (configured, project_name) if name))
+
+
+def find_venv_odoo_executable(start_directory: Path) -> str | None:
+    """Find ``odoo`` in the conventional ``~/venvs/<project>/bin`` location.
+
+    This is the process-local equivalent of sourcing an activation script:
+    invoking the executable from the venv gives Odoo the correct interpreter
+    and environment without attempting to modify the caller's shell.
+    """
+    venv_root = Path(
+        os.environ.get("ODOORUN_VENV_ROOT", str(Path.home() / "venvs"))
+    ).expanduser()
+    for directory in (start_directory, *start_directory.parents):
+        for name in _venv_names(directory.name):
+            candidate = venv_root / name / "bin" / "odoo"
+            if candidate.is_file() and os.access(candidate, os.X_OK):
+                return str(candidate)
+    return None
+
+
+def find_odoo_executable(start_directory: Path | None = None) -> str:
+    """Return the best available Odoo executable.
+
+    A project-local ``odoo-bin`` takes precedence over an ``odoo`` command on
+    ``PATH``. Parent directories are searched so the command also works from
+    inside an add-on or another nested project directory.
+    """
+    current = (start_directory or Path.cwd()).resolve()
+    local_executable, non_executable = find_local_odoo_executable(current)
+
+    if local_executable is not None:
+        return str(local_executable)
+
+    venv_executable = find_venv_odoo_executable(current)
+    if venv_executable is not None:
+        return venv_executable
+
+    path_executable = shutil.which("odoo")
+
+    if path_executable is not None:
+        return path_executable
+
+    raise OdooExecutableNotFoundError(current, non_executable)

odoorun-0.1.1/src/odoorun/runner.py

@@ -0,0 +1,88 @@
+import os
+from pathlib import Path
+from typing import NoReturn
+
+from .discovery import find_odoo_executable
+
+
+class OdooExecutionError(RuntimeError):
+    """Raised when a discovered Odoo executable cannot be started."""
+
+    def __init__(self, executable: str, reason: str) -> None:
+        self.executable = executable
+        self.reason = reason
+        super().__init__(f"Could not start {executable}: {reason}")
+
+
+class OdooArgumentError(RuntimeError):
+    """Raised when odoorun cannot construct a valid Odoo command."""
+
+
+def _is_venv_odoo(executable: str) -> bool:
+    """Identify an Odoo executable selected from the configured venv root."""
+    if Path(executable).name != "odoo":
+        return False
+    root = Path(
+        os.environ.get("ODOORUN_VENV_ROOT", str(Path.home() / "venvs"))
+    ).expanduser().resolve()
+    try:
+        relative = Path(executable).resolve().relative_to(root)
+    except ValueError:
+        return False
+    return len(relative.parts) == 3 and relative.parts[-2:] == ("bin", "odoo")
+
+
+def _custom_addons(args: list[str]) -> tuple[list[str], list[str]]:
+    """Remove odoorun's ``-a`` option and return its comma-separated values."""
+    forwarded: list[str] = []
+    custom: list[str] = []
+    index = 0
+    while index < len(args):
+        value = args[index]
+        if value in {"-a", "--addons-path"}:
+            index += 1
+            if index == len(args) or not args[index].strip():
+                raise OdooArgumentError(f"{value} requires a comma-separated path list")
+            custom.extend(part.strip() for part in args[index].split(",") if part.strip())
+        elif value.startswith("-a=") or value.startswith("--addons-path="):
+            custom.extend(part.strip() for part in value.split("=", 1)[1].split(",") if part.strip())
+        else:
+            forwarded.append(value)
+        index += 1
+    return forwarded, custom
+
+
+def build_odoo_args(executable: str, args: list[str]) -> list[str]:
+    """Add context-specific addon paths and validate custom addon folders."""
+    forwarded, custom = _custom_addons(args)
+    if Path(executable).name != "odoo-bin":
+        if not _is_venv_odoo(executable):
+            return forwarded
+        if not any(arg == "--addons" or arg.startswith("--addons=") for arg in forwarded):
+            forwarded.insert(0, "--addons=odoo/addons")
+        return forwarded
+
+    repo_root = Path(executable).parent
+    addons = repo_root / "addons"
+    if not addons.is_dir():
+        raise OdooArgumentError(f"Odoo addons directory not found: {addons}")
+    paths = [str(addons)]
+    for item in custom:
+        candidate = Path(item).expanduser()
+        if not candidate.is_absolute():
+            candidate = repo_root.parent / candidate
+        if not candidate.is_dir():
+            raise OdooArgumentError(f"Custom addons directory not found: {candidate}")
+        paths.append(str(candidate))
+    return ["--addons-path=" + ",".join(paths), *forwarded]
+
+
+def run_odoo(args: list[str]) -> NoReturn:
+    """Replace the current process with Odoo and forward all arguments."""
+    executable = find_odoo_executable()
+    command = [executable, *build_odoo_args(executable, args)]
+
+    try:
+        os.execv(executable, command)
+    except OSError as error:
+        raise OdooExecutionError(executable, error.strerror or str(error)) from error

odoorun-0.1.1/tests/test_cli.py

@@ -0,0 +1,39 @@
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from typer.testing import CliRunner
+
+from odoorun.cli import cli
+from odoorun.discovery import OdooExecutableNotFoundError
+
+
+class CliTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.runner = CliRunner()
+
+    def test_version_option(self) -> None:
+        result = self.runner.invoke(cli, ["--version"])
+
+        self.assertEqual(result.exit_code, 0)
+        self.assertRegex(result.stdout, r"^odoorun \d+\.\d+\.\d+\s*$")
+
+    @patch("odoorun.cli.shutil.which", return_value=None)
+    @patch("odoorun.cli.find_odoo_executable")
+    def test_doctor_fails_cleanly_when_odoo_is_missing(
+        self,
+        find_executable,
+        _which,
+    ) -> None:
+        find_executable.side_effect = OdooExecutableNotFoundError(
+            Path("/tmp/example-project")
+        )
+
+        result = self.runner.invoke(cli, ["doctor"])
+
+        self.assertEqual(result.exit_code, 1)
+        self.assertIn("Odoo is not ready", result.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()

odoorun-0.1.1/tests/test_completion.py

@@ -0,0 +1,34 @@
+import subprocess
+import unittest
+from unittest.mock import patch
+
+from odoorun.completion import database
+from odoorun.completion.engine import complete
+
+
+class DatabaseCompletionTests(unittest.TestCase):
+    @patch("odoorun.completion.database.subprocess.run")
+    def test_returns_sorted_unique_prefix_matches(self, run) -> None:
+        run.return_value.stdout = "test_z\nproduction\ntest_a\ntest_a\n"
+
+        result = database.complete("test_")
+
+        self.assertEqual(result, ["test_a", "test_z"])
+        self.assertEqual(
+            run.call_args.kwargs["timeout"],
+            database.QUERY_TIMEOUT_SECONDS,
+        )
+
+    @patch(
+        "odoorun.completion.database.subprocess.run",
+        side_effect=subprocess.TimeoutExpired("psql", 2),
+    )
+    def test_returns_no_results_when_psql_times_out(self, _run) -> None:
+        self.assertEqual(database.complete(""), [])
+
+    def test_unknown_completion_kind_returns_no_results(self) -> None:
+        self.assertEqual(complete("unknown", ""), [])
+
+
+if __name__ == "__main__":
+    unittest.main()

odoorun-0.1.1/tests/test_discovery.py

@@ -0,0 +1,94 @@
+import os
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from odoorun.discovery import (
+    OdooExecutableNotFoundError,
+    find_odoo_executable,
+)
+
+
+class FindOdooExecutableTests(unittest.TestCase):
+    def make_executable(self, path: Path) -> None:
+        path.write_text("#!/bin/sh\n", encoding="utf-8")
+        path.chmod(0o755)
+
+    def test_finds_odoo_bin_in_parent_directory(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary_directory:
+            root = Path(temporary_directory)
+            nested = root / "addons" / "custom"
+            nested.mkdir(parents=True)
+            executable = root / "odoo-bin"
+            self.make_executable(executable)
+
+            with patch.dict(os.environ, {"PATH": ""}):
+                result = find_odoo_executable(nested)
+
+            self.assertEqual(result, str(executable))
+
+    def test_local_odoo_bin_takes_precedence_over_path(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary_directory:
+            root = Path(temporary_directory)
+            local_executable = root / "odoo-bin"
+            path_executable = root / "odoo"
+            self.make_executable(local_executable)
+            self.make_executable(path_executable)
+
+            with patch.dict(os.environ, {"PATH": str(root)}):
+                result = find_odoo_executable(root)
+
+            self.assertEqual(result, str(local_executable))
+
+    def test_falls_back_to_odoo_on_path(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary_directory:
+            root = Path(temporary_directory)
+            executable = root / "odoo"
+            self.make_executable(executable)
+
+            with patch.dict(os.environ, {"PATH": str(root)}):
+                result = find_odoo_executable(root)
+
+            self.assertEqual(result, str(executable))
+
+    def test_finds_odoo_from_project_virtual_environment(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary_directory:
+            home = Path(temporary_directory)
+            project = home / "PycharmProjects" / "obusiness-2"
+            project.mkdir(parents=True)
+            executable = home / "venvs" / "obusiness-v2" / "bin" / "odoo"
+            executable.parent.mkdir(parents=True)
+            self.make_executable(executable)
+
+            with patch.dict(
+                os.environ,
+                {
+                    "PATH": "",
+                    "HOME": str(home),
+                    "ODOORUN_VENV_NAME": "obusiness-v2",
+                },
+            ):
+                result = find_odoo_executable(project)
+
+            self.assertEqual(result, str(executable))
+
+    def test_reports_nearest_non_executable_odoo_bin(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary_directory:
+            root = Path(temporary_directory)
+            nested = root / "addons"
+            nested.mkdir()
+            candidate = root / "odoo-bin"
+            candidate.write_text("#!/bin/sh\n", encoding="utf-8")
+            candidate.chmod(0o644)
+
+            with patch.dict(os.environ, {"PATH": ""}):
+                with self.assertRaises(OdooExecutableNotFoundError) as context:
+                    find_odoo_executable(nested)
+
+            self.assertEqual(context.exception.directory, nested.resolve())
+            self.assertEqual(context.exception.non_executable, candidate)
+
+
+if __name__ == "__main__":
+    unittest.main()

odoorun-0.1.1/tests/test_runner.py

@@ -0,0 +1,60 @@
+import unittest
+from unittest.mock import patch
+
+import tempfile
+from pathlib import Path
+
+from odoorun.runner import OdooArgumentError, OdooExecutionError, build_odoo_args, run_odoo
+
+
+class RunOdooTests(unittest.TestCase):
+    def test_adds_default_addons_for_venv_odoo(self) -> None:
+        self.assertEqual(
+            build_odoo_args("/home/khalid/venvs/obusiness-v2/bin/odoo", ["-d", "demo"]),
+            ["--addons=odoo/addons", "-d", "demo"],
+        )
+
+    def test_builds_and_validates_source_addons_paths(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary_directory:
+            repo = Path(temporary_directory) / "odoo"
+            (repo / "addons").mkdir(parents=True)
+            (repo.parent / "custom-addons").mkdir()
+            result = build_odoo_args(
+                str(repo / "odoo-bin"), ["-a", "custom-addons", "-d", "demo"]
+            )
+            self.assertEqual(result[0], f"--addons-path={repo / 'addons'},{repo.parent / 'custom-addons'}")
+            self.assertEqual(result[1:], ["-d", "demo"])
+
+    def test_rejects_missing_custom_addons_path(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary_directory:
+            repo = Path(temporary_directory) / "odoo"
+            (repo / "addons").mkdir(parents=True)
+            with self.assertRaises(OdooArgumentError):
+                build_odoo_args(str(repo / "odoo-bin"), ["-a", "missing"])
+
+    @patch("odoorun.runner.os.execv")
+    @patch("odoorun.runner.find_odoo_executable", return_value="/home/khalid/venvs/demo/bin/odoo")
+    def test_forwards_arguments_unchanged(self, find_executable, execv) -> None:
+        run_odoo(["--database", "example", "--dev=all"])
+
+        find_executable.assert_called_once_with()
+        execv.assert_called_once_with(
+            "/home/khalid/venvs/demo/bin/odoo",
+            ["/home/khalid/venvs/demo/bin/odoo", "--addons=odoo/addons", "--database", "example", "--dev=all"],
+        )
+
+    @patch(
+        "odoorun.runner.os.execv",
+        side_effect=PermissionError(13, "Permission denied"),
+    )
+    @patch("odoorun.runner.find_odoo_executable", return_value="/home/khalid/venvs/demo/bin/odoo")
+    def test_wraps_operating_system_errors(self, _find_executable, _execv) -> None:
+        with self.assertRaises(OdooExecutionError) as context:
+            run_odoo([])
+
+        self.assertEqual(context.exception.executable, "/home/khalid/venvs/demo/bin/odoo")
+        self.assertEqual(context.exception.reason, "Permission denied")
+
+
+if __name__ == "__main__":
+    unittest.main()

odoorun-0.1.1/uv.lock

@@ -0,0 +1,103 @@
+version = 1
+revision = 3
+requires-python = ">=3.10"
+
+[[package]]
+name = "annotated-doc"
+version = "0.0.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/57/ba/046ceea27344560984e26a590f90bc7f4a75b06701f653222458922b558c/annotated_doc-0.0.4.tar.gz", hash = "sha256:fbcda96e87e9c92ad167c2e53839e57503ecfda18804ea28102353485033faa4", size = 7288, upload-time = "2025-11-10T22:07:42.062Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1e/d3/26bf1008eb3d2daa8ef4cacc7f3bfdc11818d111f7e2d0201bc6e3b49d45/annotated_doc-0.0.4-py3-none-any.whl", hash = "sha256:571ac1dc6991c450b25a9c2d84a3705e2ae7a53467b5d111c24fa8baabbed320", size = 5303, upload-time = "2025-11-10T22:07:40.673Z" },
+]
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
+]
+
+[[package]]
+name = "markdown-it-py"
+version = "4.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "mdurl" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/ff/7841249c247aa650a76b9ee4bbaeae59370dc8bfd2f6c01f3630c35eb134/markdown_it_py-4.2.0.tar.gz", hash = "sha256:04a21681d6fbb623de53f6f364d352309d4094dd4194040a10fd51833e418d49", size = 82454, upload-time = "2026-05-07T12:08:28.36Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b3/81/4da04ced5a082363ecfa159c010d200ecbd959ae410c10c0264a38cac0f5/markdown_it_py-4.2.0-py3-none-any.whl", hash = "sha256:9f7ebbcd14fe59494226453aed97c1070d83f8d24b6fc3a3bcf9a38092641c4a", size = 91687, upload-time = "2026-05-07T12:08:27.182Z" },
+]
+
+[[package]]
+name = "mdurl"
+version = "0.1.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d6/54/cfe61301667036ec958cb99bd3efefba235e65cdeb9c84d24a8293ba1d90/mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba", size = 8729, upload-time = "2022-08-14T12:40:10.846Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" },
+]
+
+[[package]]
+name = "odoorun"
+version = "0.1.0"
+source = { editable = "." }
+dependencies = [
+    { name = "rich" },
+    { name = "typer" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "rich", specifier = ">=15.0.0" },
+    { name = "typer", specifier = ">=0.26.8" },
+]
+
+[[package]]
+name = "pygments"
+version = "2.20.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c3/b2/bc9c9196916376152d655522fdcebac55e66de6603a76a02bca1b6414f6c/pygments-2.20.0.tar.gz", hash = "sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f", size = 4955991, upload-time = "2026-03-29T13:29:33.898Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl", hash = "sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176", size = 1231151, upload-time = "2026-03-29T13:29:30.038Z" },
+]
+
+[[package]]
+name = "rich"
+version = "15.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markdown-it-py" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c0/8f/0722ca900cc807c13a6a0c696dacf35430f72e0ec571c4275d2371fca3e9/rich-15.0.0.tar.gz", hash = "sha256:edd07a4824c6b40189fb7ac9bc4c52536e9780fbbfbddf6f1e2502c31b068c36", size = 230680, upload-time = "2026-04-12T08:24:00.75Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/82/3b/64d4899d73f91ba49a8c18a8ff3f0ea8f1c1d75481760df8c68ef5235bf5/rich-15.0.0-py3-none-any.whl", hash = "sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb", size = 310654, upload-time = "2026-04-12T08:24:02.83Z" },
+]
+
+[[package]]
+name = "shellingham"
+version = "1.5.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/58/15/8b3609fd3830ef7b27b655beb4b4e9c62313a4e8da8c676e142cc210d58e/shellingham-1.5.4.tar.gz", hash = "sha256:8dbca0739d487e5bd35ab3ca4b36e11c4078f3a234bfce294b0a0291363404de", size = 10310, upload-time = "2023-10-24T04:13:40.426Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686", size = 9755, upload-time = "2023-10-24T04:13:38.866Z" },
+]
+
+[[package]]
+name = "typer"
+version = "0.26.8"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "annotated-doc" },
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "rich" },
+    { name = "shellingham" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7c/f7/68adc395201b20b872d68e975386832e8005ffeacedd43a1d837a32815be/typer-0.26.8.tar.gz", hash = "sha256:c244a6bd558886fe3f8780efb6bdd28bb9aff005a94eedebaa5cb32926fe2f7e", size = 202097, upload-time = "2026-06-26T09:22:45.705Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/80/87/b9fd69c92c6102a066e1b86a35243f53e70bd4c709f2a26d9f4fee4f4dc0/typer-0.26.8-py3-none-any.whl", hash = "sha256:3512ca79ac5c11113414b36e80281b872884477722440691c89d1112e321a49c", size = 122564, upload-time = "2026-06-26T09:22:44.72Z" },
+]