@grifhinz/logics-manager 2.2.0 → 2.3.1

package/logics_manager/assist.py

@@ -11,6 +11,8 @@ import subprocess
 from shutil import which
 from typing import Any
 
+from .assist_handoff import build_handoff as _build_handoff
+from .assist_surface import build_changed_surface_summary as _build_changed_surface_summary
 from .config import ConfigError, find_repo_root, load_repo_config
 from .doctor import doctor_payload
 from .lint import lint_payload
@@ -643,35 +645,6 @@ def _git_changed_paths(repo_root: Path) -> list[str]:
     return [line.strip() for line in completed.stdout.splitlines() if line.strip()]
 
 
-def _git_lines(repo_root: Path, args: list[str]) -> list[str]:
-    try:
-        completed = subprocess.run(
-            ["git", *args],
-            cwd=repo_root,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.DEVNULL,
-            text=True,
-            check=False,
-        )
-    except OSError:
-        return []
-    if completed.returncode != 0:
-        return []
-    return [line.strip() for line in completed.stdout.splitlines() if line.strip()]
-
-
-def _git_range_changed_paths(repo_root: Path, since: str) -> list[str]:
-    return sorted(set(_git_lines(repo_root, ["diff", "--name-only", "--relative=.", f"{since}..HEAD"])))
-
-
-def _git_range_commits(repo_root: Path, since: str) -> list[dict[str, str]]:
-    commits: list[dict[str, str]] = []
-    for line in _git_lines(repo_root, ["log", "--oneline", f"{since}..HEAD"]):
-        commit, _, subject = line.partition(" ")
-        commits.append({"commit": commit, "subject": subject})
-    return commits
-
-
 def _is_low_risk_generated_path(path: str) -> bool:
     normalized = path.strip().replace("\\", "/")
     filename = normalized.rsplit("/", 1)[-1]
@@ -754,7 +727,7 @@ def _render_diff_risk_text(payload: dict[str, object]) -> str:
 def _summarize_commit_scope(changed_paths: list[str]) -> tuple[str, str]:
     if not changed_paths:
         return "root", "No changes detected; nothing to commit."
-    if any(path.startswith("src/") for path in changed_paths):
+    if any(path.startswith("clients/vscode/src/") or path.startswith("clients/shared-web/media/") for path in changed_paths):
         return "plugin", "Plugin surface changes detected."
     if any(path.startswith("logics_manager/") for path in changed_paths):
         return "python-runtime", "Native Logics manager changes detected."
@@ -796,55 +769,20 @@ def _build_commit_plan(changed_paths: list[str]) -> dict[str, object]:
     }
 
 
-def _build_changed_surface_summary(changed_paths: list[str]) -> dict[str, object]:
-    category_counter: Counter[str] = Counter()
-    for path in changed_paths:
-        normalized = path.replace("\\", "/")
-        if normalized.startswith("src/"):
-            category_counter["plugin"] += 1
-        elif normalized.startswith("logics_manager/"):
-            category_counter["python-runtime"] += 1
-        elif normalized.startswith("logics/"):
-            category_counter["workflow-docs"] += 1
-        elif normalized.startswith("tests/") or "/tests/" in normalized or normalized.startswith("python_tests/"):
-            category_counter["tests"] += 1
-        elif normalized.endswith(".md"):
-            category_counter["docs"] += 1
-        else:
-            category_counter["other"] += 1
-    primary = category_counter.most_common(1)[0][0] if category_counter else "clean"
-    summary = {
-        "clean": "No changed surface was detected.",
-        "plugin": "The plugin surface is the dominant change area.",
-        "python-runtime": "The native Python runtime is the dominant change area.",
-        "workflow-docs": "Workflow documentation is the dominant change area.",
-        "tests": "Tests are the dominant change area.",
-        "docs": "Markdown documentation is the dominant change area.",
-        "other": "Mixed repository changes are present.",
-    }.get(primary, "Mixed repository changes are present.")
-    return {
-        "summary": summary,
-        "primary_category": primary,
-        "counts": dict(sorted(category_counter.items())),
-        "changed_paths": changed_paths,
-        "review_recommended": primary not in {"clean", "docs"} and bool(changed_paths),
-    }
-
-
 def _build_validation_checklist(changed_paths: list[str]) -> dict[str, object]:
     surface = _build_changed_surface_summary(changed_paths)
     checks: list[str] = [
-        "Run `python3 -m pytest python_tests/test_logics_manager_cli.py -q`.",
+        "Run `python3 -m pytest tests/python/test_logics_manager_cli.py -q`.",
         "Run `python3 -m compileall logics_manager`.",
         "Run `npm run lint:logics`.",
     ]
-    if any(path.startswith("src/") for path in changed_paths):
+    if any(path.startswith("clients/vscode/src/") or path.startswith("clients/shared-web/media/") for path in changed_paths):
         checks.append("Run the plugin test suite that exercises the VS Code entrypoints.")
     if any(path.startswith("logics_manager/") for path in changed_paths):
         checks.append("Smoke-test `python3 -m logics_manager --help` and the affected native subcommands.")
     if any(path.startswith("logics/") for path in changed_paths):
         checks.append("Run `python3 -m logics_manager lint --require-status` and inspect the workflow docs manually.")
-    if any(path.startswith("tests/") or path.startswith("python_tests/") for path in changed_paths):
+    if any(path.startswith("tests/") or path.startswith("tests/python/") for path in changed_paths):
         checks.append("Run the focused affected tests before broad regression sweeps.")
     if not changed_paths:
         checks.append("No validation needed beyond a clean smoke check; there are no tracked changes.")
@@ -860,15 +798,15 @@ def _build_test_impact_summary(changed_paths: list[str]) -> dict[str, object]:
     categories = _build_changed_surface_summary(changed_paths)["counts"]
     recommended: list[str] = []
     if "python-runtime" in categories:
-        recommended.append("python3 -m pytest python_tests/test_logics_manager_cli.py -q")
+        recommended.append("python3 -m pytest tests/python/test_logics_manager_cli.py -q")
     if "plugin" in categories:
         recommended.append("npm run lint")
     if "workflow-docs" in categories:
         recommended.append("npm run lint:logics")
     if "tests" in categories:
-        recommended.append("python3 -m pytest python_tests/test_logics_manager_cli.py -q")
+        recommended.append("python3 -m pytest tests/python/test_logics_manager_cli.py -q")
     if not recommended:
-        recommended.append("python3 -m pytest python_tests/test_logics_manager_cli.py -q")
+        recommended.append("python3 -m pytest tests/python/test_logics_manager_cli.py -q")
     return {
         "summary": "Recommended test order derived from the current change surface.",
         "categories": categories,
@@ -2079,77 +2017,6 @@ def _build_closure_summary(repo_root: Path, ref: str | None) -> dict[str, object
     }
 
 
-def _doc_title_from_path(path: Path) -> str:
-    try:
-        lines = path.read_text(encoding="utf-8").splitlines()
-    except OSError:
-        return path.stem
-    for line in lines:
-        if line.startswith("## "):
-            payload = line.removeprefix("## ").strip()
-            if " - " in payload:
-                return payload.split(" - ", 1)[1].strip()
-            return payload
-    return path.stem
-
-
-def _validation_lines_from_task(path: Path) -> list[str]:
-    try:
-        lines = path.read_text(encoding="utf-8").splitlines()
-    except OSError:
-        return []
-    values: list[str] = []
-    for line in _section_lines(lines, "Validation"):
-        stripped = line.strip()
-        if not stripped.startswith("- "):
-            continue
-        value = stripped[2:].strip()
-        if value and not value.lower().startswith("run `") and not value.lower().startswith("run the "):
-            values.append(value)
-    return values
-
-
-def _build_handoff(repo_root: Path, since: str) -> dict[str, object]:
-    changed_paths = _git_range_changed_paths(repo_root, since)
-    commits = _git_range_commits(repo_root, since)
-    surface = _build_changed_surface_summary(changed_paths)
-    logics_docs: list[dict[str, object]] = []
-    validations: list[str] = []
-    for rel_path in changed_paths:
-        if not rel_path.startswith("logics/") or not rel_path.endswith(".md"):
-            continue
-        path = repo_root / rel_path
-        kind = path.parent.name
-        entry = {
-            "path": rel_path,
-            "ref": path.stem,
-            "kind": kind,
-            "title": _doc_title_from_path(path),
-            "status": _doc_status(path) if path.is_file() else "Unknown",
-        }
-        logics_docs.append(entry)
-        if kind == "tasks":
-            validations.extend(_validation_lines_from_task(path))
-    next_actions = [
-        "Run lint/audit if not already included in validation evidence.",
-        "Review changed files before committing or handing off.",
-    ]
-    if any(path.startswith("logics_manager/") for path in changed_paths):
-        next_actions.append("Run `PYTHONPATH=\"$PWD\" pytest python_tests -q` for Python CLI changes.")
-    if any(path.startswith("src/") for path in changed_paths):
-        next_actions.append("Run the TypeScript/vitest checks for extension changes.")
-    return {
-        "since": since,
-        "commit_count": len(commits),
-        "commits": commits,
-        "changed_paths": changed_paths,
-        "surface": surface,
-        "logics_docs": logics_docs,
-        "validations": sorted(set(validations)),
-        "next_actions": next_actions,
-    }
-
-
 def _build_context_pack(repo_root: Path, seed_ref: str, *, mode: str, profile: str) -> dict[str, object]:
     docs = _workflow_docs(repo_root)
     selected: list[Path] = []

package/logics_manager/assist_handoff.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from pathlib import Path
+import subprocess
+
+from .assist_surface import build_changed_surface_summary
+
+
+def _git_lines(repo_root: Path, args: list[str]) -> list[str]:
+    try:
+        completed = subprocess.run(
+            ["git", *args],
+            cwd=repo_root,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return []
+    if completed.returncode != 0:
+        return []
+    return [line.strip() for line in completed.stdout.splitlines() if line.strip()]
+
+
+def _git_range_changed_paths(repo_root: Path, since: str) -> list[str]:
+    return sorted(set(_git_lines(repo_root, ["diff", "--name-only", f"{since}..HEAD"])))
+
+
+def _git_range_commits(repo_root: Path, since: str) -> list[dict[str, str]]:
+    commits: list[dict[str, str]] = []
+    for line in _git_lines(repo_root, ["log", "--oneline", f"{since}..HEAD"]):
+        commit, _, subject = line.partition(" ")
+        commits.append({"commit": commit, "subject": subject})
+    return commits
+
+
+def _section_lines(lines: list[str], heading: str) -> list[str]:
+    start_idx = None
+    target = heading.strip().lower()
+    for idx, line in enumerate(lines):
+        if line.startswith("# ") and line[2:].strip().lower() == target:
+            start_idx = idx + 1
+            break
+    if start_idx is None:
+        return []
+    out: list[str] = []
+    for idx in range(start_idx, len(lines)):
+        line = lines[idx]
+        if line.startswith("# "):
+            break
+        out.append(line)
+    return out
+
+
+def _doc_status(path: Path) -> str:
+    for line in path.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if stripped.startswith("> Status:"):
+            return stripped.split(":", 1)[1].strip()
+    return "Unknown"
+
+
+def _doc_title_from_path(path: Path) -> str:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return path.stem
+    for line in lines:
+        if line.startswith("## "):
+            payload = line.removeprefix("## ").strip()
+            if " - " in payload:
+                return payload.split(" - ", 1)[1].strip()
+            return payload
+    return path.stem
+
+
+def _validation_lines_from_task(path: Path) -> list[str]:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return []
+    values: list[str] = []
+    for line in _section_lines(lines, "Validation"):
+        stripped = line.strip()
+        if not stripped.startswith("- "):
+            continue
+        value = stripped[2:].strip()
+        if value and not value.lower().startswith("run `") and not value.lower().startswith("run the "):
+            values.append(value)
+    return values
+
+
+def build_handoff(repo_root: Path, since: str) -> dict[str, object]:
+    changed_paths = _git_range_changed_paths(repo_root, since)
+    commits = _git_range_commits(repo_root, since)
+    surface = build_changed_surface_summary(changed_paths)
+    logics_docs: list[dict[str, object]] = []
+    validations: list[str] = []
+    for rel_path in changed_paths:
+        if not rel_path.startswith("logics/") or not rel_path.endswith(".md"):
+            continue
+        path = repo_root / rel_path
+        kind = path.parent.name
+        entry = {
+            "path": rel_path,
+            "ref": path.stem,
+            "kind": kind,
+            "title": _doc_title_from_path(path),
+            "status": _doc_status(path) if path.is_file() else "Unknown",
+        }
+        logics_docs.append(entry)
+        if kind == "tasks":
+            validations.extend(_validation_lines_from_task(path))
+    next_actions = [
+        "Run lint/audit if not already included in validation evidence.",
+        "Review changed files before committing or handing off.",
+    ]
+    if any(path.startswith("logics_manager/") for path in changed_paths):
+        next_actions.append("Run `PYTHONPATH=\"$PWD\" pytest tests/python -q` for Python CLI changes.")
+    if any(path.startswith("clients/vscode/src/") or path.startswith("clients/shared-web/media/") for path in changed_paths):
+        next_actions.append("Run the TypeScript/vitest checks for extension changes.")
+    return {
+        "since": since,
+        "commit_count": len(commits),
+        "commits": commits,
+        "changed_paths": changed_paths,
+        "surface": surface,
+        "logics_docs": logics_docs,
+        "validations": sorted(set(validations)),
+        "next_actions": next_actions,
+    }

package/logics_manager/assist_surface.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from collections import Counter
+
+
+def build_changed_surface_summary(changed_paths: list[str]) -> dict[str, object]:
+    category_counter: Counter[str] = Counter()
+    for path in changed_paths:
+        normalized = path.replace("\\", "/")
+        if normalized.startswith("clients/vscode/src/") or normalized.startswith("clients/shared-web/media/"):
+            category_counter["plugin"] += 1
+        elif normalized.startswith("logics_manager/"):
+            category_counter["python-runtime"] += 1
+        elif normalized.startswith("logics/"):
+            category_counter["workflow-docs"] += 1
+        elif normalized.startswith("tests/") or "/tests/" in normalized or normalized.startswith("tests/python/"):
+            category_counter["tests"] += 1
+        elif normalized.endswith(".md"):
+            category_counter["docs"] += 1
+        else:
+            category_counter["other"] += 1
+    primary = category_counter.most_common(1)[0][0] if category_counter else "clean"
+    summary = {
+        "clean": "No changed surface was detected.",
+        "plugin": "The plugin surface is the dominant change area.",
+        "python-runtime": "The native Python runtime is the dominant change area.",
+        "workflow-docs": "Workflow documentation is the dominant change area.",
+        "tests": "Tests are the dominant change area.",
+        "docs": "Markdown documentation is the dominant change area.",
+        "other": "Mixed repository changes are present.",
+    }.get(primary, "Mixed repository changes are present.")
+    return {
+        "summary": summary,
+        "primary_category": primary,
+        "counts": dict(sorted(category_counter.items())),
+        "changed_paths": changed_paths,
+        "review_recommended": primary not in {"clean", "docs"} and bool(changed_paths),
+    }

package/logics_manager/cli.py

@@ -1,9 +1,11 @@
 from __future__ import annotations
 
 import argparse
+import json
 from importlib import metadata
 import subprocess
 import sys
+import sysconfig
 from shutil import which
 from pathlib import Path
 
@@ -20,6 +22,7 @@ from .lint import lint_payload, render_lint
 from .sync import search_logics_docs_payload
 from .doctor import render_doctor
 from .termstyle import colorize_help
+from .update_check import get_update_notice
 
 
 DEFAULT_SELF_UPDATE_PY_PACKAGE = "logics-manager"
@@ -37,6 +40,7 @@ ROOT_COMMANDS = (
     "product-consistency",
     "status",
     "lint",
+    "view",
     "config",
     "doctor",
     "mcp",
@@ -88,6 +92,7 @@ def _build_root_help() -> str:
         "  product-consistency  Check product brief lineage links.",
         "  status     Summarize open workflow docs and next actions.",
         "  search     Search workflow docs directly.",
+        "  view       Start a local read-only browser viewer for the Logics corpus.",
         "",
         "Validation:",
         "  lint       Check filenames, headings, indicators, and changed-doc hygiene.",
@@ -130,6 +135,60 @@ def get_cli_version() -> str:
     return "0.0.0"
 
 
+def _is_running_inside_venv() -> bool:
+    return sys.prefix != getattr(sys, "base_prefix", sys.prefix)
+
+
+def _is_externally_managed_python() -> bool:
+    if _is_running_inside_venv():
+        return False
+    stdlib = sysconfig.get_path("stdlib")
+    return bool(stdlib and (Path(stdlib) / "EXTERNALLY-MANAGED").exists())
+
+
+def _is_running_from_npm_package() -> bool:
+    package_json = Path(__file__).resolve().parents[1] / "package.json"
+    try:
+        payload = json.loads(package_json.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    return payload.get("name") == DEFAULT_SELF_UPDATE_PACKAGE
+
+
+def _print_externally_managed_update_guidance(package_name: str) -> None:
+    print(
+        "\n".join(
+            [
+                "This Python installation is externally managed, so pip cannot safely update logics-manager in the system environment.",
+                "",
+                "Recommended fix:",
+                "  sudo apt update",
+                "  sudo apt install pipx python3-venv",
+                "  pipx ensurepath",
+                f"  pipx install --force {package_name}",
+                "",
+                "If you installed the npm package instead, run:",
+                f"  npm install -g {DEFAULT_SELF_UPDATE_PACKAGE}@latest",
+                "",
+                "Advanced override, at your own risk:",
+                f"  logics-manager self-update --manager pip --break-system-packages",
+            ]
+        )
+    )
+
+
+def _is_json_mode(argv: list[str]) -> bool:
+    return "--json" in argv or any(argv[index] == "--format" and index + 1 < len(argv) and argv[index + 1] == "json" for index in range(len(argv)))
+
+
+def _maybe_print_update_notice(command: str, argv: list[str]) -> None:
+    if command in {"self-update", "mcp", "view"} or _is_json_mode(argv) or not sys.stdout.isatty():
+        return
+    notice = get_update_notice(get_cli_version())
+    if notice:
+        print(notice, file=sys.stderr)
+
+
 def main(argv: list[str] | None = None) -> int:
     if argv is None:
         argv = sys.argv[1:]
@@ -147,6 +206,7 @@ def main(argv: list[str] | None = None) -> int:
     command = argv[0]
     if command not in ROOT_COMMANDS:
         raise SystemExit(f"Unsupported command: {command}")
+    _maybe_print_update_notice(command, argv)
 
     rest = argv[1:]
     if command == "config":
@@ -192,20 +252,29 @@ def main(argv: list[str] | None = None) -> int:
         parser.add_argument("--manager", choices=("auto", "pip", "npm"), default="auto")
         parser.add_argument("--package", default=DEFAULT_SELF_UPDATE_PACKAGE)
         parser.add_argument("--python-package", default=DEFAULT_SELF_UPDATE_PY_PACKAGE)
+        parser.add_argument("--break-system-packages", action="store_true")
         parser.add_argument("--dry-run", action="store_true")
         parsed = parser.parse_args(rest)
 
         manager = parsed.manager
         if manager == "auto":
-            try:
-                metadata.version(parsed.python_package)
-            except metadata.PackageNotFoundError:
-                manager = "npm" if which("npm") else "pip"
+            if _is_running_from_npm_package() and which("npm"):
+                manager = "npm"
             else:
-                manager = "pip"
+                try:
+                    metadata.version(parsed.python_package)
+                except metadata.PackageNotFoundError:
+                    manager = "npm" if which("npm") else "pip"
+                else:
+                    manager = "pip"
 
         if manager == "pip":
+            if _is_externally_managed_python() and not parsed.break_system_packages:
+                _print_externally_managed_update_guidance(parsed.python_package)
+                return 1
             command = [sys.executable, "-m", "pip", "install", "--upgrade", parsed.python_package]
+            if parsed.break_system_packages:
+                command.append("--break-system-packages")
         else:
             npm = which("npm")
             if not npm:
@@ -240,6 +309,10 @@ def main(argv: list[str] | None = None) -> int:
         from .mcp import main as mcp_main
 
         return mcp_main(rest)
+    if command == "view":
+        from .viewer import main as viewer_main
+
+        return viewer_main(rest)
     if command == "audit":
         audit_parser = build_audit_parser()
         parsed = audit_parser.parse_args(rest)