feat(hzforge): implement upgrade-trac subcommand + _upgrade_trac_env

Real implementation of the per-env upgrade orchestrator stubbed in the
earlier "stub _upgrade_trac_env" commit.  Scope today: items 1 & 2 from
the stub's docstring (legacy macro cleanup + trac.ini sanity).  Items 3
& 4 (Trac 1.6 DB schema walk db29 -> db45 + Py2-plugin quarantine across
that walk) still gate on a Py3.11 + Trac 1.6 install.

New helpers:
  - _macros_universal_installed():  probes `python2 -c 'import hubzero_macros'`
    and python3 likewise; True iff either succeeds.
  - _upgrade_trac_env(env_path):  for each `<env>/plugins/{image,link}.py`,
    move to `.disabled` via _rename() if the universal hubzero_macros is
    installed (otherwise warn and leave in place).  Parses <env>/conf/trac.ini
    and warns on any `[components]` entry starting with `image.` or `link.`
    (case preserved via optionxform=str -- the [components] keys are
    module/class paths and are case-sensitive).
  - cmd_upgrade_trac():  enumerates envs (positional ENV args or default
    = all envs with conf/trac.ini), runs _upgrade_trac_env per env, and
    lets apply_changes() do a graceful httpd reload if anything moved.

New CLI:  `hzforge upgrade-trac [ENV ...]`  -- runs the per-env upgrade.
main() collects args.envs (comma-joined supported like services).

7 new pytest cases (now 32 total).  Discovered while testing on the live
host: ALL 66 trac envs carry the legacy image.py/link.py copies (the
hubzero-forge installtool's drop-in template fired for every env, not
just the 5 the earlier ls sample showed).

The Stage 2 work, when it lands, will append DB-schema-walk + plugin-
quarantine logic to _upgrade_trac_env -- the docstring of the today-
implemented portion sketches the planned shape.

Author: nkissebe

hzforge.py

@@ -38,6 +38,7 @@
 """
 
 import argparse
+import configparser
 import grp
 import os
 import pwd
@@ -1305,36 +1306,96 @@ def repair():
     doctor()
 
 
+def _macros_universal_installed():
+    """True iff the universal `hubzero_macros` plugin is importable by some
+    Python available on this host (Py2 today; Py3 after Stage 2).  When yes,
+    per-env legacy `image.py`/`link.py` copies are safe to disable because
+    the universal plugin keeps serving the same `[[image …]]` / `[[link …]]`
+    macros."""
+    for py in ("python2", "python3"):
+        if _ok([py, "-c", "import hubzero_macros"]):
+            return True
+    return False
+
+
 def _upgrade_trac_env(env_path):
-    """STUB -- per-env Trac upgrade tasks (not yet implemented).
-
-    When this lands it will own bringing a single Trac env up to current
-    expectations.  Planned scope:
-
-      1. **Legacy macro cleanup.**  Remove the stale per-env macros at
-         `<env>/plugins/{image,link}.py` (forge dropped these into envs at
-         tool-create time; the universal `hubzero_macros` plugin replaces them
-         system-wide and the per-env copies become redundant once it is
-         pip-installed).
-      2. **Plugin installation/config verification.**  Confirm the expected
-         universal Trac plugins (`hubzeroplugin` from `hubzero-trac-mysqlauthz`,
-         `hubzero_macros`) are discoverable via `pkg_resources.iter_entry_points`
-         at the current pinned versions, and that `<env>/conf/trac.ini` does
-         not have stale `[components]` enable/disable lines pointing at removed
-         per-env modules.
-      3. **(Stage 2) DB schema walk** db29 -> db45 against the per-env SQLite
-         via a headless Py3 Trac 1.6 (`Environment(env_path).needs_upgrade()`
-         then `DatabaseManager(env).upgrade(45)`, then `WikiAdmin._do_upgrade()`),
-         with a `cp -a <env> <env>.bak-<ts>` backup beforehand.
-      4. **(Stage 2) Plugin quarantine across the schema walk** -- move
-         Py2-only eggs aside before Trac 1.6 boots over the env (component
-         discovery would otherwise crash on `import ConfigParser`/`<>`), then
-         restore the Py3-ported wheels afterwards.
-
-    Today this function is a no-op placeholder; it will be wired to a
-    `hzforge upgrade-trac` subcommand when the scope above is implemented.
-    """
-    pass  # TODO: implement per the docstring above
+    """Per-env Trac upgrade: legacy macro cleanup + trac.ini sanity.
+
+    Today (items 1 & 2 of the original scope):
+      * Move any `<env>/plugins/{image,link}.py` left over from forge's
+        `installtool` to `<file>.disabled` -- BUT only when the universal
+        `hubzero_macros` plugin is installed (a Python on the host can
+        `import hubzero_macros`), so the env keeps serving those macros.
+        Otherwise just warn and leave them in place.
+      * Read `<env>/conf/trac.ini` and warn on any `[components]` entry
+        starting with `image.` or `link.` -- those mask the universal
+        plugin's `hubzero_macros.image`/`.link` modules and want cleanup.
+
+    Stage 2 (DB schema walk db29 -> db45, Py2-plugin quarantine across the
+    walk) is still pending; it gates on a Py3.11 + Trac 1.6 install."""
+    name = os.path.basename(env_path)
+    step(f"Upgrade trac env: {name}")
+    if not os.path.isdir(env_path):
+        warn(f"  {env_path}: not a directory")
+        return
+
+    universal_ok = _macros_universal_installed()
+    plugins_dir = os.path.join(env_path, "plugins")
+    if os.path.isdir(plugins_dir):
+        for legacy in ("image.py", "link.py"):
+            src = os.path.join(plugins_dir, legacy)
+            if not os.path.isfile(src):
+                continue
+            if universal_ok:
+                _rename(src, src + ".disabled")
+            else:
+                warn(f"  legacy {plugins_dir}/{legacy} present; install "
+                     "hubzero-trac-macros first, then re-run upgrade-trac")
+
+    trac_ini = os.path.join(env_path, "conf", "trac.ini")
+    if os.path.isfile(trac_ini):
+        try:
+            cp = configparser.RawConfigParser()
+            cp.optionxform = str   # `[components]` keys are case-sensitive
+            cp.read(trac_ini)
+            if cp.has_section("components"):
+                for opt, val in cp.items("components"):
+                    if opt.startswith(("image.", "link.")):
+                        warn(f"  {trac_ini} [components] {opt} = {val}  "
+                             "(legacy per-env macro reference; safe to remove)")
+        except (configparser.Error, OSError) as e:
+            warn(f"  could not read {trac_ini}: {e}")
+    log("  done")
+
+
+def cmd_upgrade_trac():
+    """`hzforge upgrade-trac [env ...]` -- run _upgrade_trac_env() per env.
+    With no positional ENV args, runs across every env under /opt/trac/tools/
+    (a subdir containing conf/trac.ini)."""
+    tools_dir = OPT["trac_tools"][0]
+    if not os.path.isdir(tools_dir):
+        die(f"trac not configured (no {tools_dir})")
+    all_envs = sorted(
+        d for d in os.listdir(tools_dir)
+        if os.path.isdir(os.path.join(tools_dir, d))
+        and os.path.isfile(os.path.join(tools_dir, d, "conf", "trac.ini"))
+    )
+    requested = list(getattr(ARGS, "envs", None) or [])
+    if requested:
+        bad = [e for e in requested if e not in all_envs]
+        if bad:
+            die(f"unknown env(s): {', '.join(bad)}  "
+                f"(have: {', '.join(all_envs) or '(none)'})")
+        targets = requested
+    else:
+        targets = all_envs
+    step(f"Upgrade {len(targets)} trac env(s): {','.join(targets) or '(none)'}")
+    for env_name in targets:
+        _upgrade_trac_env(os.path.join(tools_dir, env_name))
+    # Anything _rename()d set CTX.config_changed; apply_changes() does the
+    # graceful httpd reload so the mod_wsgi daemon picks up the per-env
+    # plugin changes.  (No-op if nothing was actually moved.)
+    apply_changes()
 
 
 # ---------------------------------------------------------------------------- #
@@ -1383,6 +1444,10 @@ def build_parser():
                         help="create throwaway projects and verify each service serves")
     pt.add_argument("services", nargs="*", metavar="SERVICE",
                     help=svc_help + " to test; default: all configured")
+    pug = sub.add_parser("upgrade-trac", parents=[common],
+                         help="per-env Trac upgrade (legacy macro cleanup + trac.ini sanity)")
+    pug.add_argument("envs", nargs="*", metavar="ENV",
+                     help="trac envs to upgrade (under /opt/trac/tools); default: all configured")
     return p
 
 
@@ -1417,6 +1482,13 @@ def main():
     if args.command == "uninstall" and not services:
         die("uninstall needs at least one service: " + " ".join(ALL_SERVICES))
     args.services = services
+    # envs (positional on upgrade-trac); allow comma-joined like services.
+    # Not validated against ALL_SERVICES -- envs are arbitrary subdirs of
+    # /opt/trac/tools/ and the existence check happens in cmd_upgrade_trac().
+    envs = []
+    for tok in (getattr(args, "envs", None) or []):
+        envs += [e for e in tok.split(",") if e]
+    args.envs = envs
     ARGS = args
 
     print("=" * 72)
@@ -1437,6 +1509,8 @@ def main():
         repair()
     elif args.command == "test":
         cmd_test()
+    elif args.command == "upgrade-trac":
+        cmd_upgrade_trac()
 
     step("Done")
     for n in CTX.notes:

tests/test_hzforge.py

@@ -179,3 +179,88 @@ def test_ldap_bindpw_inline_warns(monkeypatch):
 def test_trac_spec_exact_version(spec, expected, monkeypatch):
     monkeypatch.setattr(hz, "ARGS", make_args(trac_spec=spec), raising=False)
     assert hz._trac_spec_exact_version() == expected
+
+
+# --- upgrade-trac: _macros_universal_installed + _upgrade_trac_env ---
+
+def test_macros_universal_installed_true_if_any_python_can_import(monkeypatch):
+    monkeypatch.setattr(hz, "_ok", lambda cmd: cmd[0] == "python2")
+    assert hz._macros_universal_installed() is True
+
+
+def test_macros_universal_installed_false_when_neither_python_can_import(monkeypatch):
+    monkeypatch.setattr(hz, "_ok", lambda cmd: False)
+    assert hz._macros_universal_installed() is False
+
+
+def test_upgrade_trac_env_warns_about_legacy_macros_when_universal_missing(tmp_path, monkeypatch):
+    monkeypatch.setattr(hz, "CTX", hz.Ctx(False), raising=False)
+    monkeypatch.setattr(hz, "_macros_universal_installed", lambda: False)
+    env = tmp_path / "histogram"
+    plugins = env / "plugins"
+    plugins.mkdir(parents=True)
+    (plugins / "image.py").write_text("# legacy image macro")
+    (plugins / "link.py").write_text("# legacy link macro")
+    hz._upgrade_trac_env(str(env))
+    # universal missing -> files NOT moved
+    assert (plugins / "image.py").is_file()
+    assert (plugins / "link.py").is_file()
+    # ... but warnings name both, and reference the hubzero-trac-macros install:
+    notes_text = "\n".join(hz.CTX.notes)
+    assert "image.py" in notes_text
+    assert "link.py"  in notes_text
+    assert "install hubzero-trac-macros" in notes_text
+
+
+def test_upgrade_trac_env_disables_legacy_macros_when_universal_present(tmp_path, monkeypatch):
+    monkeypatch.setattr(hz, "CTX", hz.Ctx(False), raising=False)
+    monkeypatch.setattr(hz, "_macros_universal_installed", lambda: True)
+    env = tmp_path / "wiki"
+    plugins = env / "plugins"
+    plugins.mkdir(parents=True)
+    (plugins / "image.py").write_text("# legacy image macro")
+    (plugins / "link.py").write_text("# legacy link macro")
+    hz._upgrade_trac_env(str(env))
+    # originals moved aside -> .disabled siblings remain
+    assert not (plugins / "image.py").exists()
+    assert     (plugins / "image.py.disabled").is_file()
+    assert not (plugins / "link.py").exists()
+    assert     (plugins / "link.py.disabled").is_file()
+
+
+def test_upgrade_trac_env_dry_run_does_not_move_files(tmp_path, monkeypatch):
+    monkeypatch.setattr(hz, "CTX", hz.Ctx(True), raising=False)   # dry=True
+    monkeypatch.setattr(hz, "_macros_universal_installed", lambda: True)
+    env = tmp_path / "x"
+    plugins = env / "plugins"
+    plugins.mkdir(parents=True)
+    (plugins / "image.py").write_text("# legacy")
+    hz._upgrade_trac_env(str(env))
+    assert (plugins / "image.py").is_file()                 # still here
+    assert not (plugins / "image.py.disabled").exists()     # not moved
+
+
+def test_upgrade_trac_env_warns_about_stale_components_in_trac_ini(tmp_path, monkeypatch):
+    monkeypatch.setattr(hz, "CTX", hz.Ctx(False), raising=False)
+    monkeypatch.setattr(hz, "_macros_universal_installed", lambda: True)
+    env = tmp_path / "histogram"
+    conf = env / "conf"
+    conf.mkdir(parents=True)
+    (conf / "trac.ini").write_text(
+        "[components]\n"
+        "image.* = enabled\n"
+        "link.linkMacro = enabled\n"
+        "trac.* = enabled\n"
+    )
+    hz._upgrade_trac_env(str(env))
+    notes_text = "\n".join(hz.CTX.notes)
+    assert "image.*"        in notes_text
+    assert "link.linkMacro" in notes_text
+    assert "trac.*"     not in notes_text    # non-legacy entry not flagged
+
+
+def test_upgrade_trac_env_handles_missing_dir(tmp_path, monkeypatch):
+    monkeypatch.setattr(hz, "CTX", hz.Ctx(False), raising=False)
+    monkeypatch.setattr(hz, "_macros_universal_installed", lambda: False)
+    hz._upgrade_trac_env(str(tmp_path / "nonexistent"))
+    assert any("not a directory" in n for n in hz.CTX.notes)