plan_status.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/scripts/plan_status.py
 
# OCT-LINT: disable=tests_exist reason="Wiring shim; covered by oc_chat/tests/registry/test_shim_plan_status.py, test_231_worker_report_helper.py and test_blocked_lane_event.py"
"""
``.PLAN_STATUS.md`` CLI — moved to :mod:`oc_orchestrator.plan_status`.
 
Purpose
-------
Plan 270 P4. The lifecycle helper and its CLI now live in the standalone
``oc_orchestrator`` package. This file keeps ``oc_chat.scripts.plan_status``
working — the path the launch brief, ``dispatch.ps1``, ``registry/migrate``
and every worker's STEP-0 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 observers.** The package announces lifecycle events and registers
  no listener; oc_chat mirrors every one of them into the orchestration
  registry, so this is where :class:`RegistryMirrorObserver` is registered.
 
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__`, so ``plan_status.read``,
``plan_status.Status`` and ``plan_status._split_frontmatter`` all resolve
to the moved module's own objects.
 
Responsibilities
----------------
- :func:`main` — the package's CLI with oc_chat's ``prog`` and observers.
- :func:`__getattr__` — every other name, delegated unchanged.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - lifecycle events (a command was run through this path)
    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 registry rows each one writes. That is the whole point:
  the split is invisible from here.
- The observer import is deferred into :func:`main` exactly as the
  pre-270 ``_resolve_observers`` deferred it, so importing this module
  costs no registry machinery.
- Retirement rule (plan 270 P8): this path stays until an explicit
  retirement plan retargets the brief, ``dispatch.ps1`` and the workflow
  doc. New code names ``oc_orchestrator.plan_status`` directly.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_orchestrator.plan_status (the moved module this path wraps)
- oc_chat.registry.mirror_observer (lazy; RegistryMirrorObserver, the observer this path registers)
"""
 
from __future__ import annotations
 
import sys
from typing import Any
 
from oc_diagnostics import _dbg
 
from oc_orchestrator import plan_status as _moved
 
#: The program name this path has always printed in ``--help``.
PROG = "python -m oc_chat.scripts.plan_status"
 
_dbg("OC_CHAT.MAIN", "module", "plan_status shim -> oc_orchestrator.plan_status", 4)
 
 
def __getattr__(name: str) -> Any:
    """Delegate every name this shim does not define to the moved module.
 
    PEP 562 module ``__getattr__``. It covers the private names two
    oc_chat callers reach — ``registry/migrate.py`` wants
    ``_split_frontmatter`` — as well as every public one, so no importer
    had to change when the code moved.
    """
    return getattr(_moved, name)
 
 
def main(argv: list[str] | None = None) -> int:
    """Run one sub-command with oc_chat's program name and observers."""
    func = "plan_status.main"
    from oc_chat.registry.mirror_observer import RegistryMirrorObserver
 
    _dbg("OC_CHAT.MAIN", func, "running with the registry mirror registered", 3)
    return _moved.main(argv, prog=PROG, observers=(RegistryMirrorObserver(),))
 
 
if __name__ == "__main__":
    sys.exit(main())