gOdoo-cli 1.0.3__tar.gz → 1.0.4__tar.gz

{godoo_cli-1.0.3 → godoo_cli-1.0.4}/.agents/skills/godoo-editor-validation/SKILL.md

@@ -8,10 +8,9 @@ description:
 
 Read `docs/workspace.md`, then open the generated `<project>.code-workspace`.
 
-gOdoo sets `python.languageServer` to `None` so the installed Odoo IDE extension provides Python and Odoo analysis
-without a competing Pylance server. Keep the Python extension for interpreter selection and debugging. The generated
-`python.analysis.extraPaths` covers the resolved project, Odoo, third-party, and archive addon roots. The supported
-source mapping is the generated multi-root workspace plus its generated extra paths.
+Keep the Python extension for interpreter selection and debugging. The generated `python.analysis.extraPaths` covers the
+resolved project, Odoo, third-party, and archive addon roots. The supported source mapping is the generated multi-root
+workspace plus its generated extra paths.
 
 Reload the window after generation, save representative project, Odoo, and addon files, then inspect VS Code Problems.
 Confirm each diagnostic refers to the intended selected host worktree. Problems validate editor analysis, not execution.

{godoo_cli-1.0.3 → godoo_cli-1.0.4}/.vscode/settings.json

@@ -2,7 +2,7 @@
   "python.testing.unittestEnabled": false,
   "python.testing.pytestEnabled": false,
   "xml.symbols.enabled": false,
-  "python.languageServer": "Pylance",
+  "python.languageServer": "None",
   "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
   "ruff.path": ["${workspaceFolder}/.venv/bin/ruff"],
   "ruff.configurationPreference": "filesystemFirst",

{godoo_cli-1.0.3 → godoo_cli-1.0.4}/AGENTS.md

@@ -14,6 +14,24 @@ coherent change.
   whole-changeset reviews.
 - Keep shared Docker validation sequential.
 
+## Branches and releases
+
+- Start each independent change on a short-lived `codex/<topic>` branch from freshly fetched `origin/main`. Do not reuse
+  a merged branch for new work. Keep implementation, tests, and documentation for one behavior together.
+- Before switching or creating a branch, inspect staged, unstaged, and untracked work. Preserve existing changes and
+  verify the resulting diff against `origin/main`; use a separate Git worktree for concurrent independent work.
+- Open topic PRs into `main` and check Quality results before merging. Topic-branch pushes alone do not trigger Quality.
+  Follow the existing merge strategy and commit conventions. Push and merge only within explicit authorization.
+- After merge, return to an updated `main` or start the next topic branch from current `origin/main`. Prune stale remote
+  references and remove merged branches only after checking ancestry and worktree ownership; preserve unfinished work.
+- Leave package version changes to `.github/workflows/version-bump.yml`, dispatched against `main` with the chosen bump
+  type. It creates `release/<version>` and the release PR; keep that PR limited to preparing the release.
+- Review the release PR description and available Quality results before merging: its description becomes the release
+  notes. The release-labeled PR must target `main` and match the title, branch, and version identities documented in
+  `.github/workflows/README.md`. Publication uses the release merge commit for PyPI, the tag, and the GitHub Release.
+- Keep release PRs short-lived and coordinate other merges to preserve the intended release scope. Do not use a
+  long-lived `release` or `develop` branch for this workflow, or move an existing release tag to repair publication.
+
 ## Code and CLI
 
 - Every shell script under `scripts/` has a purpose comment immediately below its shebang.

{godoo_cli-1.0.3 → godoo_cli-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gOdoo-cli
-Version: 1.0.3
+Version: 1.0.4
 Summary: Odoo lifecycle, Python dependency preflight, and shared Git workspaces.
 Project-URL: repository, https://github.com/OpenJKSoftware/gOdoo
 Author-email: Joshua Kreuder <Joshua_Kreuder@outlook.com>
@@ -10,6 +10,7 @@ Keywords: docker,godoo,odoo,worktree
 Requires-Python: >=3.11
 Requires-Dist: gitpython>=3.1.27
 Requires-Dist: godoo-rpc>=0.1.4
+Requires-Dist: json-with-comments>=1.3.0
 Requires-Dist: packaging>=21.0
 Requires-Dist: passlib>=1.7.3
 Requires-Dist: psycopg2-binary>=2.7.7; sys_platform != 'linux'

{godoo_cli-1.0.3 → godoo_cli-1.0.4}/docs/lifecycle.md

@@ -8,6 +8,39 @@ hooks, then launch Odoo. Runtime commands require Odoo 16 or newer.
 Stop ordinary Odoo writers before initialization, restore, clone, or replacement. gOdoo locks coordinate gOdoo
 operations; they do not stop ordinary Odoo writes.
 
+## Back up a live runtime
+
+```bash
+# Default: one combined ZIP, including attachments.
+godoo db backup /backups/runtime.zip --db-name odoo
+
+# PostgreSQL custom format plus a separate filestore, copied with rsync.
+godoo db backup /backups/current --db-name odoo --format dump
+```
+
+`--format` accepts `zip` (default) or `dump`; `GODOO_BACKUP_FORMAT` supplies the environment default. Both formats
+capture the database first, then the filestore. The `dump` destination contains `odoo.dump` and
+`odoo_filestore/filestore/<database>/`, directly usable by `godoo runtime init --dump-path` or
+`godoo db restore <directory> --force`. It requires `pg_dump` and `rsync` in the execution environment. The destination
+must be outside Odoo's data directory. Borg or another backup system owns history; each successful run replaces the
+selected destination.
+
+During capture, gOdoo holds a row lock on `base.autovacuum_job`. Odoo's scheduler skips that internal cleanup job;
+users, attachment writes, integrations, and other background jobs continue. No app restart or attachment-table write
+lock is needed. The lock is released on completion or connection closure. If cleanup is already running, backup fails
+immediately so it can be retried afterward. The backup fails if the guard connection is lost before publication.
+
+This protects standard Odoo filestore storage and scheduled cleanup on Odoo 16 and newer, including Odoo 19's manual
+scheduled-action trigger. Do not run private cleanup methods, custom file deletion, attachment storage migration, or
+Odoo 16–18 manual autovacuum during backup. External attachment backends need their own backup procedure. Files added
+after the database snapshot may also be copied; they are harmless extra files, not additional database records.
+
+Backups are staged before replacing the previous result. Directory destinations must be dedicated child directories
+inside a mounted backup volume, not the mount root itself. Replacing a directory briefly renames the previous pair to
+`.<destination-name>.previous`; failed promotion restores it. After an abrupt termination, inspect that directory and
+the destination before retrying. gOdoo refuses to overwrite a retained previous pair. Start Borg only after this command
+succeeds, and keep other backup readers out of the brief directory promotion window.
+
 ## Initialize and launch
 
 Run in the configured downstream runtime environment. CLI values override exported environment values, then the project

{godoo_cli-1.0.3 → godoo_cli-1.0.4}/docs/workspace.md

@@ -90,18 +90,23 @@ make typecheck
 ```
 
 Open `godoo.code-workspace` for this repository, or the generated `<project>.code-workspace` downstream. Opening the
-same files in another project's window does not load their workspace settings.
+same files in another project's window does not load their workspace settings. The generated workspace copies settings
+from the project's `.vscode/settings.json`, including JSON comments and trailing commas. Set fixed editor preferences
+there, including the interpreter, language server, and test discovery. gOdoo generates `python.analysis.extraPaths` from
+the selected sources and takes precedence for that setting in the generated workspace. Run `workspace configure` after
+changing project settings; `workspace check` reports the workspace as stale until it is regenerated. Projects without
+those fixed settings inherit their VS Code defaults or other configured values.
 
 | Generated setting    | Contract                                                                                                   |
 | -------------------- | ---------------------------------------------------------------------------------------------------------- |
 | Workspace folder     | Fixed name `gOdoo`; project-relative paths use `${workspaceFolder:gOdoo}`.                                 |
 | Selected sources     | Odoo, addon, and archive paths remain absolute host paths.                                                 |
-| Python analysis      | The Python extension's language server is disabled so Odoo IDE can provide Python and Odoo analysis.       |
-| Python extension     | Keep it installed for interpreter selection and debugging.                                                 |
 | Extra paths          | `python.analysis.extraPaths` includes the selected sources.                                                |
 | `gOdoo: attach`      | Maps the project to `/odoo/godoo_workspace` and the selected sources to their development-container paths. |
 | `pyrightconfig.json` | Ignored project-root file covering `src/`, `addons/`, `scripts/`, project addons, and resolved sources.    |
 
+Keep the Python extension for interpreter selection and debugging.
+
 Python uses Ruff for formatting and safe fixes on save, with lint rules from `pyproject.toml`, including C901. Supported
 text formats use Prettier and `.prettierrc.yml`.
 

{godoo_cli-1.0.3 → godoo_cli-1.0.4}/pyproject.toml

@@ -27,6 +27,7 @@ dependencies = [
     "packaging>=21.0",
     "typer-common-functions>=0.1.0",
     "typer>=0.9.0",
+    "json-with-comments>=1.3.0",
 ]
 
 [project.optional-dependencies]

{godoo_cli-1.0.3 → godoo_cli-1.0.4}/src/godoo_cli/__about__.py

@@ -1,3 +1,3 @@
 """Version information."""
 
-__version__ = "1.0.3"
+__version__ = "1.0.4"

{godoo_cli-1.0.3 → godoo_cli-1.0.4}/src/godoo_cli/commands/db/archive.py

@@ -15,6 +15,7 @@ from ...runtime.archive import (
     load_runtime_archive,
     prepare_archive_with_original_filestore,
 )
+from ...runtime.backup import BackupFormat
 from ...runtime.odoo import SUPPORTED_ODOO_VERSION_SPECIFIER
 from ..common import CommonCLI
 from ..configuration import require_cli_odoo_version, resolve_development_odoo_main_path
@@ -29,25 +30,33 @@ def dump_database(
     odoo_main_path: Annotated[Path, CLI.odoo_paths.bin_path],
     odoo_conf_path: Annotated[Path | None, CLI.odoo_paths.conf_path] = None,
     data_dir: Annotated[Path, CLI.odoo_paths.data_dir] = Path("/var/lib/odoo"),
+    backup_format: Annotated[
+        BackupFormat,
+        typer.Option(
+            "--format",
+            envvar="GODOO_BACKUP_FORMAT",
+            help="zip: combined archive; dump: custom PostgreSQL dump and rsync filestore directory.",
+        ),
+    ] = BackupFormat.ZIP,
 ) -> int:
-    """Create an Odoo runtime archive."""
+    """Back up a live Odoo database and its filestore in the selected format."""
     try:
         odoo_main_path = resolve_development_odoo_main_path(odoo_main_path)
         version = require_cli_odoo_version(odoo_main_path, SUPPORTED_ODOO_VERSION_SPECIFIER)
-        return CLI.returner(
-            dump_runtime_archive(
-                db_name=db_name,
-                archive_path=archive_path,
-                odoo_bin_path=odoo_main_path / "odoo-bin",
-                odoo_conf_path=odoo_conf_path,
-                data_dir=data_dir,
-                odoo_version=version.major,
-                connection=DBConnection.from_odoo_config(db_name, odoo_conf_path),
-            )
+        result = dump_runtime_archive(
+            db_name=db_name,
+            backup_format=backup_format,
+            archive_path=archive_path,
+            odoo_bin_path=odoo_main_path / "odoo-bin",
+            odoo_conf_path=odoo_conf_path,
+            data_dir=data_dir,
+            odoo_version=version.major,
+            connection=DBConnection.from_odoo_config(db_name, odoo_conf_path),
         )
-    except OSError:
+    except (OSError, RuntimeError, ValueError, psycopg2.Error):
         LOGGER.exception("Archive creation failed")
         return CLI.returner(1)
+    return CLI.returner(result)
 
 
 # Typer declares each archive-restore option in this public callback signature.

{godoo_cli-1.0.3 → godoo_cli-1.0.4}/src/godoo_cli/runtime/archive.py

@@ -24,6 +24,7 @@ from ..database.connection import DBConnection
 from ..database.postgres import postgres_argv, postgres_environment
 from ..database.state import base_module_major, database_exists
 from ..helpers.progress import ProgressPhase as _ProgressPhase
+from .backup import BackupFormat, publish_backup_directory, retain_attachment_files
 from .baseline import baseline_database_name, save_runtime_baseline
 from .filestore import copy_filestore
 from .locks import begin_runtime_restore, runtime_data_directory, runtime_locks
@@ -273,7 +274,9 @@ def _stream_sql_input(command: Sequence[str], dump_path: Path, environment: dict
     return 0
 
 
-def dump_runtime_archive(
+# Keep capture, retention, and promotion together, with Odoo and PostgreSQL targets supplied explicitly.
+# pylint: disable-next=too-many-arguments
+def dump_runtime_archive(  # noqa: C901
     *,
     db_name: str,
     archive_path: Path,
@@ -283,54 +286,98 @@ def dump_runtime_archive(
     runner: CommandRunner | None = None,
     odoo_version: int | None = None,
     connection: DBConnection | None = None,
+    backup_format: BackupFormat = BackupFormat.ZIP,
 ) -> int:
-    """Create an archive atomically, retaining any prior destination on failure."""
+    """Capture the database before attachments, then publish the complete backup.
+
+    Returns:
+        Zero on success, otherwise the failing subprocess exit status.
+
+    Raises:
+        ValueError: If the destination overlaps runtime storage or has the wrong type.
+    """
     with runtime_locks(data_dir, db_name, odoo_conf_path=odoo_conf_path):
+        target_connection = connection or _archive_connection(db_name, odoo_conf_path)
+        runtime_data = runtime_data_directory(data_dir, odoo_conf_path)
+        archive_path = archive_path.resolve()
+        if archive_path == runtime_data or archive_path in runtime_data.parents or runtime_data in archive_path.parents:
+            message = "The backup destination must be outside Odoo's data directory."
+            raise ValueError(message)
+        if backup_format == BackupFormat.DUMP and archive_path.exists() and not archive_path.is_dir():
+            message = "The dump backup destination must be a directory."
+            raise ValueError(message)
         archive_path.parent.mkdir(parents=True, exist_ok=True)
         temporary = archive_path.with_name(f".{archive_path.name}.{uuid.uuid4().hex}.tmp")
         sql_temporary = temporary.with_suffix(".sql")
         try:
-            target_connection = connection or _archive_connection(db_name, odoo_conf_path)
-            runtime_data = runtime_data_directory(data_dir, odoo_conf_path)
             native = _uses_native_db_commands(odoo_version, odoo_bin_path)
-            if native:
+            separate = backup_format == BackupFormat.DUMP
+            if separate:
+                temporary.mkdir()
+            if native and not separate:
                 command = odoo_db_command(
                     odoo_bin_path=odoo_bin_path,
                     odoo_conf_path=odoo_conf_path,
                     data_dir=data_dir,
-                    arguments=["dump", db_name, str(temporary)],
+                    arguments=["dump", "--no-filestore", db_name, str(temporary)],
                 )
             else:
                 command = [
                     "pg_dump",
                     "--no-owner",
-                    "--format=plain",
+                    "--format=custom" if separate else "--format=plain",
                     "--file",
-                    str(sql_temporary),
+                    str(temporary / LEGACY_DUMP_FILENAME if separate else sql_temporary),
                     *postgres_argv(target_connection),
                 ]
-            with _ProgressPhase("Dumping runtime database", logger=LOGGER) as progress:
-                if runner is not None:
-                    result = runner(command)
-                elif native:
-                    result = _run_odoo_db(command)
-                else:
-                    result = _run_postgres_command(command, target_connection)
-                progress.failed = result != 0
-            if result:
-                return result
-            if not native:
+            with retain_attachment_files(target_connection):
+                with _ProgressPhase("Dumping runtime database", logger=LOGGER) as progress:
+                    if runner is not None:
+                        result = runner(command)
+                    else:
+                        with postgres_environment(target_connection) as environment:
+                            if native and not separate:
+                                # Odoo 19 reads these before its config file, including empty overrides.
+                                environment.update(
+                                    PGHOST=target_connection.hostname,
+                                    PGPORT=str(target_connection.port or 5432),
+                                    PGUSER=target_connection.username,
+                                    PGPASSWORD=target_connection.password,
+                                    PGSSLMODE=target_connection.sslmode or "prefer",
+                                )
+                            result = run_odoo_command(command, env=environment).returncode
+                    progress.failed = result != 0
+                if result:
+                    return result
                 filestore = runtime_filestore_path(runtime_data, db_name)
-                with zipfile.ZipFile(temporary, "w", zipfile.ZIP_DEFLATED) as archive:
-                    archive.write(sql_temporary, "dump.sql")
-                    if filestore.is_dir():
-                        for path in sorted(filestore.rglob("*")):
-                            if path.is_file():
-                                archive.write(path, Path("filestore") / path.relative_to(filestore))
-            os.replace(temporary, archive_path)
+                with _ProgressPhase("Copying backup filestore", logger=LOGGER) as progress:
+                    if separate:
+                        destination = temporary / LEGACY_FILESTORE_DIRECTORY / "filestore" / db_name
+                        destination.mkdir(parents=True)
+                        if filestore.is_dir():
+                            command = ["rsync", "-rLpt", f"{filestore}/", f"{destination}/"]
+                            result = runner(command) if runner is not None else run_odoo_command(command).returncode
+                            progress.failed = result != 0
+                            if result:
+                                return result
+                    else:
+                        with zipfile.ZipFile(temporary, "a" if native else "w", zipfile.ZIP_DEFLATED) as archive:
+                            if not native:
+                                archive.write(sql_temporary, "dump.sql")
+                            if filestore.is_dir():
+                                for path in sorted(filestore.rglob("*")):
+                                    if path.is_file():
+                                        archive.write(path, Path("filestore") / path.relative_to(filestore))
+            if separate:
+                publish_backup_directory(temporary, archive_path)
+            else:
+                os.replace(temporary, archive_path)
             return 0
         finally:
-            temporary.unlink(missing_ok=True)
+            if temporary.is_dir():
+                shutil.rmtree(temporary)
+            else:
+                temporary.unlink(missing_ok=True)
             sql_temporary.unlink(missing_ok=True)
 
 

godoo_cli-1.0.4/src/godoo_cli/runtime/backup.py

@@ -0,0 +1,80 @@
+"""Coordinate online attachment retention and backup publication."""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+from collections.abc import Iterator
+from contextlib import contextmanager
+from enum import StrEnum
+from pathlib import Path
+
+import psycopg2
+
+from ..database.connection import DBConnection
+
+LOGGER = logging.getLogger(__name__)
+
+
+class BackupFormat(StrEnum):
+    """Select a combined Odoo ZIP or a separate custom dump and filestore."""
+
+    ZIP = "zip"
+    DUMP = "dump"
+
+
+@contextmanager
+def retain_attachment_files(connection: DBConnection) -> Iterator[None]:
+    """Defer the standard autovacuum job without locking attachment writes.
+
+    Raises:
+        RuntimeError: If the standard cleanup job is missing or already running.
+    """
+    with connection.connect() as cursor:
+        try:
+            cursor.execute(
+                "SELECT cron.id FROM ir_cron AS cron "
+                "JOIN ir_model_data AS data ON data.res_id = cron.id AND data.model = 'ir.cron' "
+                "WHERE data.module = 'base' AND data.name = 'autovacuum_job' "
+                "FOR NO KEY UPDATE OF cron NOWAIT"
+            )
+        except psycopg2.errors.LockNotAvailable as error:
+            message = "Odoo attachment cleanup is running; retry the backup after it finishes."
+            raise RuntimeError(message) from error
+        if len(cursor.fetchall()) != 1:
+            message = "Cannot retain attachment files: Odoo's base.autovacuum_job is missing."
+            raise RuntimeError(message)
+        LOGGER.info("Deferring Odoo's internal autovacuum job during backup")
+        yield
+        # A server timeout or lost connection must fail before publication.
+        cursor.execute("SELECT 1")
+    LOGGER.info("Released Odoo's internal autovacuum job after backup")
+
+
+def publish_backup_directory(staged: Path, destination: Path) -> None:
+    """Promote a complete pair, restoring the previous pair on rename failure.
+
+    Raises:
+        RuntimeError: If a previous promotion needs recovery.
+        OSError: If promotion fails, after attempting to restore the previous pair.
+    """
+    previous = destination.with_name(f".{destination.name}.previous")
+    if previous.exists():
+        message = f"Backup recovery is required: inspect {previous} and {destination} before retrying."
+        raise RuntimeError(message)
+    had_previous = destination.exists()
+    if had_previous:
+        os.replace(destination, previous)
+    try:
+        os.replace(staged, destination)
+    except OSError:
+        if had_previous:
+            LOGGER.warning("Restoring previous backup from %s", previous)
+            os.replace(previous, destination)
+        raise
+    if had_previous:
+        try:
+            shutil.rmtree(previous)
+        except OSError:
+            LOGGER.warning("Backup completed, but previous backup remains at %s", previous, exc_info=True)

{godoo_cli-1.0.3 → godoo_cli-1.0.4}/src/godoo_cli/workspace/editor.py

@@ -5,7 +5,9 @@ from __future__ import annotations
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
-from .types import ResolvedSource
+import jsonc
+
+from .types import ResolvedSource, WorkspaceError
 
 if TYPE_CHECKING:
     from .types import WorkspaceSettings
@@ -16,6 +18,27 @@ PROJECT_FOLDER_NAME = "gOdoo"
 PROJECT_WORKSPACE_FOLDER = f"${{workspaceFolder:{PROJECT_FOLDER_NAME}}}"
 
 
+def _project_settings(project_root: Path) -> dict[str, Any]:
+    """Read project editor settings in VS Code's JSON-with-comments format."""
+    path = project_root / ".vscode" / "settings.json"
+    try:
+        content = path.read_text(encoding="utf-8-sig")
+    except FileNotFoundError:
+        return {}
+    except (OSError, UnicodeError) as error:
+        message = f"Unable to read VS Code settings {path}: {error}"
+        raise WorkspaceError(message) from error
+    try:
+        data = jsonc.loads(content)
+    except jsonc.JSONDecodeError as error:
+        message = f"Invalid VS Code settings {path}: {error}"
+        raise WorkspaceError(message) from error
+    if not isinstance(data, dict):
+        message = f"VS Code settings must be an object: {path}"
+        raise WorkspaceError(message)
+    return data
+
+
 def workspace_data(
     settings: WorkspaceSettings,
     sources: list[ResolvedSource],
@@ -50,11 +73,8 @@ def workspace_data(
     return {
         "folders": folders,
         "settings": {
-            "python.defaultInterpreterPath": f"{PROJECT_WORKSPACE_FOLDER}/.venv/bin/python",
-            "python.languageServer": "None",
+            **_project_settings(settings.project_root),
             "python.analysis.extraPaths": python_extra_paths,
-            "python.testing.pytestEnabled": False,
-            "python.testing.unittestEnabled": False,
         },
         "launch": {
             "version": "0.2.0",