pi-odoo-develop

Version-aware Odoo development for the Pi coding agent.

Guarantees the Odoo version is known before any line of Odoo code is written.

A version-aware Odoo development extension for the Pi coding agent.

It guarantees that the Odoo version is known before any Odoo code is written, then redirects the agent to the official Odoo docs, ORM changelog, and OCA migration guide for the confirmed major (it does not try to maintain a hand-curated change list — Odoo changes too much per release). Supports Odoo 14–19.

This complements Odoo knowledge skills (odoo-19, odoo-code-review, …): those provide knowledge, this extension enforces runtime version awareness.

Why

Writing Odoo code without confirming the major version leads to subtle bugs — Odoo changes a lot between releases (view tags, removed fields, ORM API shifts, security model changes, …). Rather than hardcoding a partial change list, this extension makes the agent stop and confirm the version first, then point at the official changelog and docs for that major.

What it does

• Strict gate (two steps): blocks write/edit on Odoo code files (module files with .py/.xml/.csv/.po/.pot and .js/.ts/.scss extensions, inside a module with a __manifest__.py) until BOTH conditions hold: (1) a version is confirmed, AND (2) the agent has researched the official sources for that major in the current session (via odoo_changelog or odoo_version with detect). This guarantees every proposed change is grounded in the version's official changelog/docs before it is written.
• Docker lifecycle commands: manage your Odoo instance directly from Pi.
  • /odoo-status: Show Odoo project status, version gate state, and active Docker service.
  • /odoo-restart: Restart the Odoo service.
  • /odoo-update <modules>: Update Odoo modules (-u).
  • /odoo-logs: Tail the Odoo service logs.
• Auto-detection of the Odoo version from multiple sources, in priority order: manual override (.pi/odoo.json) → Docker Compose runtime probe (odoo.release.version inside the container) → Compose image tag via docker compose config → static docker-compose.yml read (works even when Docker is not running) → local odoo-bin --version / odoo/release.py → base module manifest. A manual override is never overwritten by automatic detection.
• Official-sources router: once a version is known, the system prompt gets the official docs, ORM changelog, and OCA migration-guide URLs for that major.
• No-op outside Odoo projects: safe to load anywhere.

How the gate works

For write/edit on an Odoo code file (per session):

1. No version confirmed → blocked. Run /odoo-version (or /odoo-version set <major>) or call odoo_version.
2. Version confirmed, but not researched this session → blocked. Call odoo_changelog (recommended) or odoo_version { action: "detect" } so the change is grounded in the version's official changelog.
3. Version confirmed AND researched → writes allowed (for the rest of the session; re-detection after /odoo-version clear re-arms the gate).

The .pi/ directory is always exempt, so /odoo-version set can always write its config.

Install

# From npm (shows up in the pi.dev gallery)
pi install npm:pi-odoo-develop

# From GitHub
pi install git:github.com/vigbe/pi-odoo-develop

# Try it in the current project only (no install)
pi -e ./src/index.ts

It is distributed as a Pi package — see package.json (pi manifest key).

Usage

/odoo-version command

/odoo-version            # show the detected version + source
/odoo-version detect     # force re-detection
/odoo-version set 17     # manual override (saved to .pi/odoo.json)
/odoo-version clear      # remove the override

Docker lifecycle & status commands

Manage your Odoo instance directly from the Pi console:

/odoo-status           # Show gate state, version, and Docker status
/odoo-restart          # Restart the Odoo service
/odoo-update all       # Update all modules
/odoo-update sale,stock # Update specific modules (-d dbname optional)
/odoo-test my_module -d db --tags /my_module  # Run module tests
/odoo-scaffold my_module  # Scaffold a version-aware module skeleton
/odoo-logs --tail=50   # Show the last 50 lines of logs

The extension automatically finds your Odoo service in docker-compose.yml (prioritizing services named odoo or web).

/odoo-scaffold — version-aware module skeleton

Scaffolds a new OCA-style module (__manifest__.py, __init__.py, models/, security/ir.model.access.csv, tests/) into the first conventional addon root (custom_addons/, src/addons/, addons/, …). The manifest version is generated from the confirmed major (e.g. 17.0.1.0.0), so it honours the same two-step version gate: no scaffolding until the version is confirmed AND researched.

/odoo-test — run module tests

Runs odoo -i <modules> --test-enable --stop-after-init inside the Odoo service and reports the tail of the test output:

/odoo-test my_module -d mydb           # install + run all tests
/odoo-test my_module --tags /my_module # only that tag

/odoo-shell — evaluate Python in the Odoo shell

Boots odoo shell inside the Odoo service and evaluates a Python snippet (non-interactive: the REPL reads your code from stdin, prints the result, exits):

/odoo-shell -d mydb env["res.partner"].search_count([])
/odoo-shell env["res.partner"].browse(1).name   # db taken from rpc.db

Database resolution: -d <db> argument, else the rpc.db value in .pi/odoo.json. Booting the shell starts the full Odoo runtime, so allow up to ~a minute.

Edition detection (enterprise vs community)

Alongside the version, the extension detects the edition when possible:

1. Runtime probe (deterministic): if a Docker Odoo service answers, import odoo.addons.web_enterprise succeeding ⇒ Enterprise, failing ⇒ Community.
2. Filesystem markers (fallback): odoo/addons/web_enterprise, enterprise/web_enterprise, or web_enterprise inside any conventional addon root.

The edition is cached in .pi/odoo.json, shown by /odoo-status, included in odoo_version output, and added to the system-prompt banner (Enterprise ⇒ enterprise-only APIs available; Community ⇒ not).

odoo_version tool (for the agent)

The agent should call this before writing or reviewing Odoo code:

odoo_version { action: "detect" }   # auto-detect
odoo_version { action: "show" }     # read cached
odoo_version { action: "set", version: "17" }   # manual override

Returns the confirmed major and the official docs, ORM changelog, and OCA migration-guide URLs for it.

odoo_changelog tool (for the agent)

Fetches the official Odoo ORM changelog for the confirmed major on demand, so the agent can apply version-correct APIs straight from the source of truth (no manual change list to maintain):

odoo_changelog {}              # changelog for the detected major
odoo_changelog { major: 17 }   # changelog for a specific major

For Odoo 14/15 (which have no dedicated changelog page), it falls back to the OCA migration guide for that major, with a note explaining the fallback.

Live introspection tools (optional): odoo_models & odoo_fields

Read-only XML-RPC introspection of your running Odoo instance, so the agent can ground its code in the REAL schema instead of guessing:

odoo_models { filter: "sale" }        # exact technical model names, live
odoo_fields { model: "res.partner" }  # real fields: types, relations, flags

odoo_fields returns the actual field names, types (char, many2one, …), relation targets, and required/readonly flags — the strongest grounding for instance-correct code.

Configuration (env vars override the file):

export ODOO_URL=http://localhost:8069
export ODOO_DB=mydb
export ODOO_USERNAME=admin
export ODOO_PASSWORD=<api-key>   # Odoo API key preferred over a password

or add an rpc block to .pi/odoo.json:

{
  "version": "17",
  "source": "manual",
  "rpc": {
    "url": "http://localhost:8069",
    "db": "mydb",
    "username": "admin",
    "password": "<api-key>"
  }
}

Strictly read-only: the extension only calls search_read on ir.model / ir.model.fields through Odoo's own XML-RPC layer, so it can never bypass the permissions of the authenticated user. Without configuration the tools degrade gracefully and explain how to configure them.

How version detection works

Sources are tried in priority order; the first success is cached to .pi/odoo.json:

1. Manual override (.pi/odoo.json with source: "manual") — always honoured.
2. Docker Compose runtime: docker compose exec <odoo-service> python3 -c "import odoo.release; print(odoo.release.version)" (falls back to python on slim images).
3. Docker image tag: image: odoo:17.0 parsed from docker compose config.
4. Static compose file: the image tag read directly from docker-compose.yml/compose.yml (works even when the Docker daemon is not running).
5. Repo source: ./odoo-bin --version or odoo/release.py.
6. base manifest: version field in base/__manifest__.py.

Detection runs automatically once per session when the agent starts in an Odoo project. A manual override is never overwritten by automatic detection.

Supported majors

14, 15, 16, 17, 18, 19. Unknown/future majors degrade gracefully: detection still works and the gate lifts, but no version-specific banner is injected.

Configuration

| File | Purpose | |------|---------| | .pi/odoo.json | Cached/manual version override + optional rpc connection block, written by the extension. | | ODOO_URL/ODOO_DB/ODOO_USERNAME/ODOO_PASSWORD env vars | Live introspection connection (overrides the rpc block). |

CI & Publishing

Two GitHub Actions workflows keep the package honest:

• ci.yml — on every push to main and PR: npm ci + typecheck + full test suite.
• publish.yml — on pushing an annotated tag v<semver>: runs the full verification, checks that the tag matches package.json, then publishes to npm via trusted publishing (OIDC, no tokens) with provenance.

One-time setup for trusted publishing (no NPM token ever stored in GitHub):

1. On npmjs.com: Account → Publishing access → add a trusted publisher for pi-odoo-develop with repository vigbe/pi-odoo-develop, workflow filename publish.yml, environment npm.
2. On GitHub: Settings → Environments → create the npm environment.

Releasing then is just:

npm version patch   # or minor/major
# …commit, push to main, then:
git tag -a v0.8.0 <main-sha> -m "pi-odoo-develop v0.8.0"
git push origin refs/tags/v0.8.0   # Actions verifies + publishes
gh release create v0.8.0 --verify-tag --title "…" --notes "…"

Development & Testing

Run unit tests locally using the Node.js test runner:

npm test

Typecheck:

npm run typecheck

License

LGPL-3.0-or-later