plan_manage.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/scripts/plan_manage.py
 
# OCT-LINT: disable=tests_exist reason="Wiring shim; covered by oc_chat/tests/unit/test_plan_manage_manifest.py and test_259_dispatch_hooks.py"
"""
Plan-inventory and dispatch CLI — moved to :mod:`oc_orchestrator.plan_manage`.
 
Purpose
-------
Plan 270 P4. The CLI now lives in the standalone ``oc_orchestrator``
package. This file keeps ``oc_chat.scripts.plan_manage`` working — the
path ``scripts/dispatch.ps1`` and every orchestrator command have always
named — 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 dispatch hooks.** The package declares a ``DispatchHooks``
  Protocol and announces to nobody; oc_chat has a hub and a work queue,
  so this is where :func:`hooks_for_dispatch` is built — a dispatch still
  records its ``dispatch`` message and, for a plan that really was
  pending, its ``dequeue``.
 
Unlike the eight ``core/`` 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__`.
 
Responsibilities
----------------
- :func:`main` — the package's CLI with oc_chat's ``prog`` and hooks.
- :func:`_dispatch_hooks` — the live hub listener, verbatim from the
  pre-270 module, including its fail-soft refusal.
- :func:`__getattr__` — every other name, delegated unchanged.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - lifecycle events (hub hooks unavailable)
    L3 - semantic details
    L4 - deep tracing (delegated name lookups)
 
Contracts
---------
- Output is byte-identical to the pre-270 module for every sub-command,
  and so are the hub entries and queue transitions a dispatch produces.
- A hub that cannot be built is never allowed to block a dispatch: the
  refusal is logged and ``NO_HOOKS`` is returned, exactly as before.
- Importing this module registers oc_chat's ``oct`` timing hook, through
  the ``core/worktree_env`` import below. Without it the engine timing
  ledger would silently stop filling on the dispatch path, because the
  moved package treats ``oct`` as absent by default.
- Retirement rule (plan 270 P8): this path stays until an explicit
  retirement plan retargets ``dispatch.ps1`` and the workflow doc. New
  code names ``oc_orchestrator.plan_manage`` directly.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_orchestrator.plan_manage (the moved module this path wraps)
- oc_chat.core.worktree_env (imported for its side effect: the oct hook)
- oc_orchestrator.hub_manage (lazy; hooks_for_dispatch, the hooks this path registers; moved there by plan 272, which is why this one names the package and not the shim)
- oc_orchestrator.dispatch (lazy; NO_HOOKS, returned when the hub hooks cannot be built)
"""
 
from __future__ import annotations
 
from pathlib import Path
import sys
from typing import Any
 
from oc_diagnostics import _dbg
 
from oc_orchestrator import plan_manage as _moved
 
# Imported for its SIDE EFFECT and nothing else: the shim registers
# oc_chat's oct timing hook on the moved worktree_env module. The
# dispatch path reaches worktree_env through the package, never through
# oc_chat, so without this import the engine.dispatch / engine.prepare /
# engine.teardown rows would quietly stop being written.
from oc_chat.core import worktree_env as _worktree_env  # noqa: F401
 
#: The program name this path has always printed in ``--help``.
PROG = "python -m oc_chat.scripts.plan_manage"
 
_dbg("OC_CHAT.MAIN", "module", "plan_manage shim -> oc_orchestrator.plan_manage", 4)
 
 
def __getattr__(name: str) -> Any:
    """Delegate every name this shim does not define to the moved module."""
    return getattr(_moved, name)
 
 
def _dispatch_hooks(repo_root: Path) -> Any:
    """The live hub listener for one dispatch (plan 259 P6).
 
    Registered by the CALLER, which is this function: the package
    declares a Protocol and a ``NO_HOOKS`` default and names neither the
    hub nor the queue, exactly as it declares nothing about the registry.
    A dispatch becomes a ``dispatch`` message and, for an item that was
    actually PENDING, one ``dequeue`` with ``reason="dispatched"``.
 
    Returns ``NO_HOOKS`` when the hub cannot be built, so a dispatch is
    never blocked by the thing that only watches it.
    """
    func = "plan_manage._dispatch_hooks"
    from oc_orchestrator.dispatch import NO_HOOKS
 
    try:
        from oc_orchestrator.hub_manage import hooks_for_dispatch
 
        return hooks_for_dispatch(
            queue_dir=repo_root / "oc_chat" / ".option_c" / "orchestration",
            comms_root=repo_root / "oc_chat" / ".option_c" / "comms",
        )
    except Exception as exc:  # noqa: BLE001 - EXTERNAL_ERROR (L2); watching is optional
        _dbg("OC_CHAT.MAIN", func,
             f"EXTERNAL_ERROR: hub hooks unavailable ({type(exc).__name__}: "
             f"{exc}); dispatching without them", 2)
        return NO_HOOKS
 
 
def main(argv: list[str] | None = None) -> int:
    """Run one sub-command with oc_chat's program name and hub hooks."""
    return _moved.main(argv, prog=PROG, dispatch_hooks=_dispatch_hooks)
 
 
if __name__ == "__main__":
    sys.exit(main())