kctl-odoo 0.4.0__tar.gz

kctl_odoo-0.4.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local

kctl_odoo-0.4.0/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: kctl-odoo
+Version: 0.4.0
+Summary: Kodemeio Odoo CLI - manage Odoo 18 ERP instances
+Author-email: Kodemeio <dev@kodeme.io>
+License-Expression: MIT
+Keywords: cli,erp,json-rpc,kodemeio,odoo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: kctl-lib>=0.4.0
+Requires-Dist: kodemeio-accurate>=0.5.0
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kctl-odoo
+
+Kodemeio Odoo CLI -- manage Odoo 18 ERP instances via JSON-RPC and Docker Compose.
+
+## Installation
+
+```bash
+uv tool install ./cli
+```
+
+To upgrade after code changes:
+
+```bash
+uv tool install --force --reinstall ./cli
+```
+
+## Quick Start
+
+```bash
+# Configure connection (interactive)
+kctl-odoo config init
+
+# Verify connectivity
+kctl-odoo config test
+
+# Dashboard overview
+kctl-odoo dashboard info
+
+# List installed modules
+kctl-odoo modules list --state installed
+
+# Health check
+kctl-odoo troubleshoot check
+```
+
+## Fast debugging — log tailing
+
+`kctl-odoo logs tail` is a unified streaming command for local + remote Odoo
+with structured filters. It auto-detects the transport from the current
+profile URL:
+
+- **local** (`localhost` / `127.0.0.1`) → streams `docker compose logs -f` in
+  the project directory.
+- **remote** → streams `docker logs -f` over SSH via `kctl-dokploy compose
+  service-logs --follow`. Requires `--compose-id` (find with `kctl-dokploy
+  compose list`).
+
+```bash
+# Local dev — stream everything
+kctl-odoo logs tail
+
+# Local dev — only warnings and above from the account.move module
+kctl-odoo logs tail --level WARNING --module account.move
+
+# Remote prod — stream tpp-odoo-erp
+kctl-odoo -p idtpp-tpp-odoo-erp logs tail \
+    --dokploy-profile idtpp \
+    --compose-id Qki8U2u4Ltstq0_6zW7UE
+
+# Narrow by worker PID or request id in the message
+kctl-odoo logs tail --worker 12 --grep "traceback"
+```
+
+Filter flags compose as AND: `--level`, `--module`, `--request`, `--worker`,
+`--grep`.
+
+**Full traceback capture.** Filters apply per *log record*, not per line. When
+a record's timestamped header matches, all of its continuation lines
+(`Traceback (most recent call last):`, `File "..."`, `^^^`, exception
+message) are emitted too — stack traces survive `--level ERROR` or any
+other filter. `--grep` can also match a continuation line directly (e.g.
+`--grep "fields.py"` to find tracebacks involving a specific file); when
+it does, the rest of that record's block is included.
+
+Other `logs` subcommands:
+
+- `logs follow` — legacy local-only streamer (kept for back-compat).
+- `logs errors --days N` — finite query against Odoo's `ir.logging` model.
+- `logs search <pattern>` — finite ilike search against `ir.logging`.
+
+## Command Groups
+
+| Group            | Description                                          |
+|------------------|------------------------------------------------------|
+| `accounting`     | Accounting transactional operations (invoices, payments, entries) |
+| `backup`         | Database backup and restore operations               |
+| `bundles`        | Module bundle management (install/list YAML bundles)  |
+| `cleanup`        | Stale data cleanup operations                         |
+| `companies`      | Company and multi-company management                  |
+| `config`         | CLI configuration (profiles, init, test)              |
+| `cron`           | Scheduled action (ir.cron) management                 |
+| `dashboard`      | Instance overview and statistics                      |
+| `databases`      | Database CRUD operations                              |
+| `deploy`         | Deployment and release management                     |
+| `dev`            | Developer tools (scaffold, aggregate, link-addons)    |
+| `diff`           | Compare module states across databases/snapshots      |
+| `export`         | Data export (CSV, JSON, XML)                          |
+| `generate`       | Code generation (module scaffold, models, views)      |
+| `history`        | Operation history tracking                            |
+| `hr`             | HR operations (employees, leaves, payslips, expenses) |
+| `import`         | Data import from files                                |
+| `integration`    | External integration management                       |
+| `inventory`      | Inventory operations (stock, transfers, adjustments)  |
+| `jobs`           | Background job / queue_job management                 |
+| `local`          | Docker Compose lifecycle (up, down, restart, logs)    |
+| `logs`           | Container log streaming and filtering                 |
+| `mail`           | Mail server and outgoing email management             |
+| `maintenance`    | Database maintenance (vacuum, reindex, cleanup)       |
+| `master-data`    | Master data configuration and seeding                 |
+| `migrate`        | Data migration tools and utilities                    |
+| `modules`        | Module install, upgrade, list, and info               |
+| `partners`       | Partner (res.partner) queries and bulk ops            |
+| `performance`    | Performance profiling and slow-query analysis         |
+| `profiles`       | Installation profile management                       |
+| `purchasing`     | Purchasing operations (POs, receipts, vendor bills)   |
+| `repl`           | Interactive Python REPL with Odoo connection          |
+| `report`         | Report template and PDF management                    |
+| `sales`          | Sales operations (SOs, deliveries, CRM pipeline)      |
+| `security`       | Access rights, record rules, and audit                |
+| `server`         | Server configuration, system parameters, and tuning   |
+| `sessions`       | User session inspection and cleanup                   |
+| `shell`          | Interactive Odoo shell (inside container)             |
+| `storage`        | Attachment and filestore management                   |
+| `tax`            | Indonesian tax operations (PPN/PPh summaries, faktur) |
+| `tenants`        | Multi-tenant / SaaS instance management               |
+| `test`           | Test runner with result parsing and summary           |
+| `troubleshoot`   | Diagnostic commands, health checks, and connectivity  |
+| `users`          | User CRUD, password reset, role management            |
+| `workers`        | Worker process inspection and scaling                 |
+
+## Command Aliases
+
+Hidden short aliases are available for common workflows:
+
+| Alias | Expands to               |
+|-------|--------------------------|
+| `mi`  | `modules install <name>` |
+| `mu`  | `modules upgrade <name>` |
+| `ml`  | `modules list`           |
+| `hc`  | `troubleshoot check`     |
+| `di`  | `dashboard info`         |
+| `bl`  | `bundles list`           |
+| `bi`  | `bundles install <name>` |
+| `pl`  | `profiles list`          |
+| `pi`  | `profiles install <name>`|
+| `tr`  | `test run <module>`      |
+
+Example:
+
+```bash
+kctl-odoo mi sale_management       # same as: kctl-odoo modules install sale_management
+kctl-odoo tr base_management       # same as: kctl-odoo test run base_management
+```
+
+## Global Options
+
+```
+--json            Output as JSON (machine-readable)
+--quiet, -q       Suppress informational messages
+--profile, -p     Use a named config profile
+--url             Odoo URL override
+--api-key         API key override
+--database, -d    Database override
+--username, -u    Username override
+--version, -V     Show version and exit
+```
+
+## Configuration
+
+### Profiles
+
+kctl-odoo supports named profiles for managing multiple Odoo instances:
+
+```bash
+# Create profiles
+kctl-odoo config add production --url https://erp.kodeme.io --database kodemeio --api-key $KEY
+kctl-odoo config add staging --url https://staging.kodeme.io --database staging --api-key $KEY
+
+# Switch default profile
+kctl-odoo config use production
+
+# Use per-command
+kctl-odoo --profile staging modules list
+
+# List all profiles
+kctl-odoo config list
+```
+
+### Config File
+
+Configuration is stored in `~/.config/kctl-odoo/config.toml` (XDG-compliant).
+
+## Shell Completions
+
+```bash
+# Install for your shell
+kctl-odoo --install-completion bash
+kctl-odoo --install-completion zsh
+kctl-odoo --install-completion fish
+```
+
+See [docs/completions.md](docs/completions.md) for manual installation and troubleshooting.
+
+## Plugin Development
+
+kctl-odoo supports extending the CLI via Python entry points. Create a package that
+registers a Typer app under the `kctl_odoo.plugins` entry point group:
+
+```toml
+# In your plugin's pyproject.toml
+[project.entry-points."kctl_odoo.plugins"]
+my_plugin = "my_plugin.cli:app"
+```
+
+The plugin's `app` (a `typer.Typer` instance) will be registered as a command group
+automatically on startup.
+
+## New in This Version
+
+- **SQLite history tracking** — All CLI operations are recorded locally. Use `kctl-odoo history` to query past commands, timings, and outcomes.
+- **Runner abstraction** — Subprocess management extracted into a reusable `Runner` class in `core/`, replacing ad-hoc `subprocess.run` calls.
+- **Command group consolidation** — Reduced from 58 to 53 groups. `biz` group eliminated; 22 business commands redistributed to `sales`, `purchasing`, `inventory`, `hr`, `accounting`, `dashboard`. `maintenance update-list` moved to `modules scan`. `maintenance accounting-close` / `inventory-close` moved to `accounting close-period` / `inventory close-period`. `maintenance run-autovacuum` renamed to `maintenance autovacuum`.
+- **Verb-first command names** — 52 commands renamed to verb-first pattern (e.g., `invoice-get` → `get-invoice`, `order-confirm` → `confirm-order`). 11 duplicate commands removed.
+
+## Development
+
+### Running Tests
+
+```bash
+cd cli
+uv run pytest tests/ -v
+```
+
+### Linting and Formatting
+
+```bash
+cd cli
+uv run ruff check src/
+uv run ruff format src/
+```
+
+### Type Checking
+
+```bash
+cd cli
+uv run mypy src/kctl_odoo/
+```
+
+### Project Structure
+
+```
+cli/
+  src/kctl_odoo/
+    cli.py              Main app + command registration
+    __init__.py         Version
+    core/
+      callbacks.py      Global option handling (AppContext)
+      client.py         JSON-RPC client for remote Odoo
+      local.py          Docker Compose client for local dev
+      config.py         Profile/config management
+      exceptions.py     Custom exception hierarchy
+      output.py         Output formatting (table, JSON, plain)
+    commands/
+      aliases.py        Short command aliases
+      modules.py        Module management
+      testing.py        Test runner with result parsing
+      ...               (50+ command modules)
+  tests/                pytest test suite
+  pyproject.toml        Package metadata and tool config
+  README.md             This file
+  docs/                 Additional documentation
+```

kctl_odoo-0.4.0/README.md

@@ -0,0 +1,272 @@
+# kctl-odoo
+
+Kodemeio Odoo CLI -- manage Odoo 18 ERP instances via JSON-RPC and Docker Compose.
+
+## Installation
+
+```bash
+uv tool install ./cli
+```
+
+To upgrade after code changes:
+
+```bash
+uv tool install --force --reinstall ./cli
+```
+
+## Quick Start
+
+```bash
+# Configure connection (interactive)
+kctl-odoo config init
+
+# Verify connectivity
+kctl-odoo config test
+
+# Dashboard overview
+kctl-odoo dashboard info
+
+# List installed modules
+kctl-odoo modules list --state installed
+
+# Health check
+kctl-odoo troubleshoot check
+```
+
+## Fast debugging — log tailing
+
+`kctl-odoo logs tail` is a unified streaming command for local + remote Odoo
+with structured filters. It auto-detects the transport from the current
+profile URL:
+
+- **local** (`localhost` / `127.0.0.1`) → streams `docker compose logs -f` in
+  the project directory.
+- **remote** → streams `docker logs -f` over SSH via `kctl-dokploy compose
+  service-logs --follow`. Requires `--compose-id` (find with `kctl-dokploy
+  compose list`).
+
+```bash
+# Local dev — stream everything
+kctl-odoo logs tail
+
+# Local dev — only warnings and above from the account.move module
+kctl-odoo logs tail --level WARNING --module account.move
+
+# Remote prod — stream tpp-odoo-erp
+kctl-odoo -p idtpp-tpp-odoo-erp logs tail \
+    --dokploy-profile idtpp \
+    --compose-id Qki8U2u4Ltstq0_6zW7UE
+
+# Narrow by worker PID or request id in the message
+kctl-odoo logs tail --worker 12 --grep "traceback"
+```
+
+Filter flags compose as AND: `--level`, `--module`, `--request`, `--worker`,
+`--grep`.
+
+**Full traceback capture.** Filters apply per *log record*, not per line. When
+a record's timestamped header matches, all of its continuation lines
+(`Traceback (most recent call last):`, `File "..."`, `^^^`, exception
+message) are emitted too — stack traces survive `--level ERROR` or any
+other filter. `--grep` can also match a continuation line directly (e.g.
+`--grep "fields.py"` to find tracebacks involving a specific file); when
+it does, the rest of that record's block is included.
+
+Other `logs` subcommands:
+
+- `logs follow` — legacy local-only streamer (kept for back-compat).
+- `logs errors --days N` — finite query against Odoo's `ir.logging` model.
+- `logs search <pattern>` — finite ilike search against `ir.logging`.
+
+## Command Groups
+
+| Group            | Description                                          |
+|------------------|------------------------------------------------------|
+| `accounting`     | Accounting transactional operations (invoices, payments, entries) |
+| `backup`         | Database backup and restore operations               |
+| `bundles`        | Module bundle management (install/list YAML bundles)  |
+| `cleanup`        | Stale data cleanup operations                         |
+| `companies`      | Company and multi-company management                  |
+| `config`         | CLI configuration (profiles, init, test)              |
+| `cron`           | Scheduled action (ir.cron) management                 |
+| `dashboard`      | Instance overview and statistics                      |
+| `databases`      | Database CRUD operations                              |
+| `deploy`         | Deployment and release management                     |
+| `dev`            | Developer tools (scaffold, aggregate, link-addons)    |
+| `diff`           | Compare module states across databases/snapshots      |
+| `export`         | Data export (CSV, JSON, XML)                          |
+| `generate`       | Code generation (module scaffold, models, views)      |
+| `history`        | Operation history tracking                            |
+| `hr`             | HR operations (employees, leaves, payslips, expenses) |
+| `import`         | Data import from files                                |
+| `integration`    | External integration management                       |
+| `inventory`      | Inventory operations (stock, transfers, adjustments)  |
+| `jobs`           | Background job / queue_job management                 |
+| `local`          | Docker Compose lifecycle (up, down, restart, logs)    |
+| `logs`           | Container log streaming and filtering                 |
+| `mail`           | Mail server and outgoing email management             |
+| `maintenance`    | Database maintenance (vacuum, reindex, cleanup)       |
+| `master-data`    | Master data configuration and seeding                 |
+| `migrate`        | Data migration tools and utilities                    |
+| `modules`        | Module install, upgrade, list, and info               |
+| `partners`       | Partner (res.partner) queries and bulk ops            |
+| `performance`    | Performance profiling and slow-query analysis         |
+| `profiles`       | Installation profile management                       |
+| `purchasing`     | Purchasing operations (POs, receipts, vendor bills)   |
+| `repl`           | Interactive Python REPL with Odoo connection          |
+| `report`         | Report template and PDF management                    |
+| `sales`          | Sales operations (SOs, deliveries, CRM pipeline)      |
+| `security`       | Access rights, record rules, and audit                |
+| `server`         | Server configuration, system parameters, and tuning   |
+| `sessions`       | User session inspection and cleanup                   |
+| `shell`          | Interactive Odoo shell (inside container)             |
+| `storage`        | Attachment and filestore management                   |
+| `tax`            | Indonesian tax operations (PPN/PPh summaries, faktur) |
+| `tenants`        | Multi-tenant / SaaS instance management               |
+| `test`           | Test runner with result parsing and summary           |
+| `troubleshoot`   | Diagnostic commands, health checks, and connectivity  |
+| `users`          | User CRUD, password reset, role management            |
+| `workers`        | Worker process inspection and scaling                 |
+
+## Command Aliases
+
+Hidden short aliases are available for common workflows:
+
+| Alias | Expands to               |
+|-------|--------------------------|
+| `mi`  | `modules install <name>` |
+| `mu`  | `modules upgrade <name>` |
+| `ml`  | `modules list`           |
+| `hc`  | `troubleshoot check`     |
+| `di`  | `dashboard info`         |
+| `bl`  | `bundles list`           |
+| `bi`  | `bundles install <name>` |
+| `pl`  | `profiles list`          |
+| `pi`  | `profiles install <name>`|
+| `tr`  | `test run <module>`      |
+
+Example:
+
+```bash
+kctl-odoo mi sale_management       # same as: kctl-odoo modules install sale_management
+kctl-odoo tr base_management       # same as: kctl-odoo test run base_management
+```
+
+## Global Options
+
+```
+--json            Output as JSON (machine-readable)
+--quiet, -q       Suppress informational messages
+--profile, -p     Use a named config profile
+--url             Odoo URL override
+--api-key         API key override
+--database, -d    Database override
+--username, -u    Username override
+--version, -V     Show version and exit
+```
+
+## Configuration
+
+### Profiles
+
+kctl-odoo supports named profiles for managing multiple Odoo instances:
+
+```bash
+# Create profiles
+kctl-odoo config add production --url https://erp.kodeme.io --database kodemeio --api-key $KEY
+kctl-odoo config add staging --url https://staging.kodeme.io --database staging --api-key $KEY
+
+# Switch default profile
+kctl-odoo config use production
+
+# Use per-command
+kctl-odoo --profile staging modules list
+
+# List all profiles
+kctl-odoo config list
+```
+
+### Config File
+
+Configuration is stored in `~/.config/kctl-odoo/config.toml` (XDG-compliant).
+
+## Shell Completions
+
+```bash
+# Install for your shell
+kctl-odoo --install-completion bash
+kctl-odoo --install-completion zsh
+kctl-odoo --install-completion fish
+```
+
+See [docs/completions.md](docs/completions.md) for manual installation and troubleshooting.
+
+## Plugin Development
+
+kctl-odoo supports extending the CLI via Python entry points. Create a package that
+registers a Typer app under the `kctl_odoo.plugins` entry point group:
+
+```toml
+# In your plugin's pyproject.toml
+[project.entry-points."kctl_odoo.plugins"]
+my_plugin = "my_plugin.cli:app"
+```
+
+The plugin's `app` (a `typer.Typer` instance) will be registered as a command group
+automatically on startup.
+
+## New in This Version
+
+- **SQLite history tracking** — All CLI operations are recorded locally. Use `kctl-odoo history` to query past commands, timings, and outcomes.
+- **Runner abstraction** — Subprocess management extracted into a reusable `Runner` class in `core/`, replacing ad-hoc `subprocess.run` calls.
+- **Command group consolidation** — Reduced from 58 to 53 groups. `biz` group eliminated; 22 business commands redistributed to `sales`, `purchasing`, `inventory`, `hr`, `accounting`, `dashboard`. `maintenance update-list` moved to `modules scan`. `maintenance accounting-close` / `inventory-close` moved to `accounting close-period` / `inventory close-period`. `maintenance run-autovacuum` renamed to `maintenance autovacuum`.
+- **Verb-first command names** — 52 commands renamed to verb-first pattern (e.g., `invoice-get` → `get-invoice`, `order-confirm` → `confirm-order`). 11 duplicate commands removed.
+
+## Development
+
+### Running Tests
+
+```bash
+cd cli
+uv run pytest tests/ -v
+```
+
+### Linting and Formatting
+
+```bash
+cd cli
+uv run ruff check src/
+uv run ruff format src/
+```
+
+### Type Checking
+
+```bash
+cd cli
+uv run mypy src/kctl_odoo/
+```
+
+### Project Structure
+
+```
+cli/
+  src/kctl_odoo/
+    cli.py              Main app + command registration
+    __init__.py         Version
+    core/
+      callbacks.py      Global option handling (AppContext)
+      client.py         JSON-RPC client for remote Odoo
+      local.py          Docker Compose client for local dev
+      config.py         Profile/config management
+      exceptions.py     Custom exception hierarchy
+      output.py         Output formatting (table, JSON, plain)
+    commands/
+      aliases.py        Short command aliases
+      modules.py        Module management
+      testing.py        Test runner with result parsing
+      ...               (50+ command modules)
+  tests/                pytest test suite
+  pyproject.toml        Package metadata and tool config
+  README.md             This file
+  docs/                 Additional documentation
+```

kctl_odoo-0.4.0/docs/completions.md

@@ -0,0 +1,69 @@
+# Shell Completions
+
+kctl-odoo uses Typer which provides automatic shell completion.
+
+## Installation
+
+### Bash
+
+```bash
+kctl-odoo --install-completion bash
+```
+
+### Zsh
+
+```bash
+kctl-odoo --install-completion zsh
+```
+
+### Fish
+
+```bash
+kctl-odoo --install-completion fish
+```
+
+## Manual Installation
+
+### Bash
+
+```bash
+eval "$(_KCTL_ODOO_COMPLETE=bash_source kctl-odoo)"
+
+# Or add to ~/.bashrc for persistence:
+echo 'eval "$(_KCTL_ODOO_COMPLETE=bash_source kctl-odoo)"' >> ~/.bashrc
+```
+
+### Zsh
+
+```bash
+eval "$(_KCTL_ODOO_COMPLETE=zsh_source kctl-odoo)"
+
+# Or add to ~/.zshrc for persistence:
+echo 'eval "$(_KCTL_ODOO_COMPLETE=zsh_source kctl-odoo)"' >> ~/.zshrc
+```
+
+### Fish
+
+```fish
+# Add to ~/.config/fish/completions/kctl-odoo.fish:
+eval (env _KCTL_ODOO_COMPLETE=fish_source kctl-odoo)
+```
+
+## Verify
+
+After installation, restart your shell and try:
+
+```bash
+kctl-odoo <TAB><TAB>     # Shows all command groups
+kctl-odoo modules <TAB>   # Shows subcommands (install, upgrade, list, info)
+kctl-odoo --<TAB>          # Shows global options (--json, --profile, etc.)
+```
+
+## Troubleshooting
+
+If completions are not working:
+
+1. Make sure `kctl-odoo` is on your `$PATH` (installed via `uv tool install`).
+2. Restart your shell or source your rc file (`source ~/.zshrc`).
+3. For Zsh, ensure `compinit` is called in your `~/.zshrc` before the completion eval.
+4. Try the manual installation method above if `--install-completion` does not work.

kctl_odoo-0.4.0/e2e/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+test-results/
+playwright-report/
+blob-report/
+dist/
+fixtures/.auth/
+screenshots/
+odoo-menu-registry.json