hub_manage.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/scripts/hub_manage.py
 
# OCT-LINT: disable=tests_exist reason="Wiring shim; covered by oc_chat/tests/unit/test_272_hub_shims.py"
"""
The hub's operator surface — moved to :mod:`oc_orchestrator.hub_manage`.
 
Purpose
-------
Plan 272 P4. The CLI now lives in the standalone ``oc_orchestrator``
package. This file keeps ``oc_chat.scripts.hub_manage`` working — the
path the rendered launch brief names at every worker's STEP-0, and the
one ``MULTI_AGENT_WORKFLOW.md`` and every orchestrator command have
always spelled — and supplies the two defaults that are oc_chat's and
not the package's:
 
- **the program name.** ``--help`` must print exactly what it printed
  before the split, and ``prog`` is the only line in it that could differ.
- **the registry log.** The package declares ``--backend registry`` as a
  plugin point and holds no registry to fill it; oc_chat has one, so this
  is where the factory is built. ``--backend registry`` therefore behaves
  byte for byte as it did before the split, and the four lazy registry
  imports that used to sit inside the package's ``_build_log`` sit here
  instead — which is precisely the seam the plan-259 receipt modelled as
  a named ``--cut``.
 
Unlike the two ``core/`` hub shims this module is NOT a rebinding,
because it has behaviour of its own: those two defaults. Every other name
is delegated by :func:`__getattr__`, which is what keeps
``from oc_chat.scripts.hub_manage import default_hooks`` working for
``tests/unit/test_259_dispatch_hooks.py`` unedited.
 
Responsibilities
----------------
- :func:`main` — the package's CLI with oc_chat's ``prog`` and factory.
- :func:`_registry_log` — the registry arm, verbatim from the pre-272
  module's ``_build_log``.
- :func:`__getattr__` — every other name, delegated unchanged.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - lifecycle events (which log was built)
    L3 - semantic details
    L4 - deep tracing (delegated name lookups)
 
Contracts
---------
- Output is byte-identical to the pre-272 module for every sub-command,
  and so are the rows a registry-mode round trip lands in the registry.
- The registry imports stay LAZY, inside the factory: the file backend is
  the default, and a ``hub_manage asks`` against it must not drag the
  registry's auth, signing and checkpoint stack into the process.
- The refusal the registry arm raises is the package's own
  :class:`~oc_orchestrator.hub_file.CorruptHubLogError`, so ``main``'s
  handler gives it the same ``backend refused:`` line and exit code 2 it
  gave before the split.
- Retirement rule (plan 272 P4): this path stays until an explicit
  retirement plan retargets the launch brief and the workflow doc. New
  code names ``oc_orchestrator.hub_manage`` directly.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_orchestrator.hub_manage (the moved module this path wraps)
- oc_orchestrator.hub_file (the refusal class the factory raises)
- oc_chat.registry (lazy; Registry, which wraps the storage the registry hub log writes to)
- oc_chat.registry.backends.sqlite (lazy; SQLiteBackend, the registry storage and its active operator slot)
- oc_chat.registry.discovery (lazy; discover_registry_location, which finds the registry file)
- oc_chat.registry.hub_log (lazy; RegistryHubLog, the registry-backed hub log the factory returns)
"""
 
from __future__ import annotations
 
import argparse
import sys
from typing import Any
 
from oc_diagnostics import _dbg
 
from oc_orchestrator import hub_manage as _moved
from oc_orchestrator.hub_file import CorruptHubLogError
 
#: The program name this path has always printed in ``--help``.
PROG = "python -m oc_chat.scripts.hub_manage"
 
_dbg("OC_CHAT.MAIN", "module", "hub_manage shim -> oc_orchestrator.hub_manage", 4)
 
 
def __getattr__(name: str) -> Any:
    """Delegate every name this shim does not define to the moved module."""
    return getattr(_moved, name)
 
 
def _registry_log(args: argparse.Namespace) -> Any:
    """Build the registry-backed hub log (plan 272 P2's consumer factory).
 
    Lifted verbatim from the registry arm of the pre-272
    ``hub_manage._build_log``. The package declares the seam and names no
    registry; this is the consumer that fills it, so the four imports the
    plan-259 receipt cut as a named edge now live on oc_chat's side of
    the split, where they always belonged.
 
    Raises:
        CorruptHubLogError: SYSTEM_ERROR (L1 for the caller) — the
            registry could not be opened, or it holds no active operator
            slot, so there is no actor to attribute the messages to.
    """
    func = "_registry_log"
    # Imported here, not at module scope: the file backend is the
    # default, and a `hub_manage asks` against it must not drag the
    # registry's auth, signing and checkpoint stack into the process.
    from oc_chat.registry import Registry
    from oc_chat.registry.backends.sqlite import SQLiteBackend
    from oc_chat.registry.discovery import discover_registry_location
    from oc_chat.registry.hub_log import RegistryHubLog
 
    try:
        location = discover_registry_location(registry_path=args.registry)
        storage = SQLiteBackend(location.registry_path)
        actor_slot = args.actor_slot or storage.active_operator_slot()
    except Exception as exc:  # noqa: BLE001 - the foreign storage stack, one arm
        # Building the registry log can fail in that package's OWN
        # exception vocabulary -- a sqlite3.OperationalError for an absent
        # file, a discovery error for an unmarked tree. Every one of them
        # means the same thing to this CLI, "the backend refused", and it
        # gets the backend exit code with the original message kept.
        raise CorruptHubLogError(
            f"the registry backend could not be opened: {type(exc).__name__}: {exc}"
        ) from exc
    if actor_slot is None:
        raise CorruptHubLogError("no active operator slot found in the registry")
    _dbg("OC_CHAT.MAIN", func, f"registry log as {actor_slot}", 2)
    return RegistryHubLog(Registry(storage), actor_slot=actor_slot)
 
 
def main(argv: list[str] | None = None) -> int:
    """Run one sub-command with oc_chat's program name and registry log."""
    return _moved.main(argv, prog=PROG, log_factory=_registry_log)
 
 
if __name__ == "__main__":
    sys.exit(main())