logics-manager 2.2.0__tar.gz → 2.3.0__tar.gz

{logics_manager-2.2.0 → logics_manager-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logics-manager
-Version: 2.2.0
+Version: 2.3.0
 Summary: Canonical Logics CLI
 Requires-Python: >=3.10
 License-File: LICENSE

{logics_manager-2.2.0 → logics_manager-2.3.0}/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/AlexAgo83/logics-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/AlexAgo83/logics-manager/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/AlexAgo83/logics-manager)](LICENSE)
-![Version](https://img.shields.io/badge/version-v2.2.0-4C8BF5)
+![Version](https://img.shields.io/badge/version-v2.3.0-4C8BF5)
 ![VS Code](https://img.shields.io/badge/VS%20Code-1.86.0-007ACC?logo=visualstudiocode&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.3.3-3178C6?logo=typescript&logoColor=white)
 ![Vitest](https://img.shields.io/badge/Vitest-2.1.8-6E9F18?logo=vitest&logoColor=white)
@@ -95,6 +95,7 @@ The CLI is the stable contract for Logics. It supports:
 - closing tasks, backlog items, and requests with consistency checks;
 - linting and auditing workflow traceability;
 - exporting indexes, context packs, and graph data;
+- serving a read-only local browser viewer for the Logics corpus;
 - serving the bounded MCP tool surface.
 
 Useful commands:
@@ -105,8 +106,48 @@ logics-manager flow promote request-to-backlog req_001_example
 logics-manager flow promote backlog-to-task item_001_example
 logics-manager flow finish task task_001_example
 logics-manager sync context-pack req_001_example --format json
+logics-manager view --open
+logics-manager view --focus req_001_example --read --open
 ```
 
+### Local Browser Viewer
+
+Use the CLI viewer when you want to inspect the Logics corpus outside VS Code:
+
+```bash
+logics-manager view --open
+```
+
+The viewer starts a localhost-only, read-only browser UI on `127.0.0.1:8765` by default. It shows the same workflow board/list experience as the extension, with search, filters, document previews, corpus insights, lint/audit health, Mermaid rendering, auto-refresh, and an edit shortcut that opens the selected Markdown file in the system editor.
+
+Useful options:
+
+```bash
+logics-manager view --port 0 --open
+logics-manager view --host 127.0.0.1 --port 9876
+logics-manager view --focus req_001_example --open
+logics-manager view --focus logics/tasks/task_001_example.md --read --open
+logics-manager view --no-open
+```
+
+Use `--port 0` when the default port is already taken. The viewer is intentionally read-only; use the canonical CLI commands such as `flow promote`, `flow finish`, `lint`, and `audit` for workflow mutations.
+
+Focused viewer links can point directly at a corpus item:
+
+```text
+http://127.0.0.1:8765/?focus=logics/request/req_001_example.md
+http://127.0.0.1:8765/?focus=logics/request/req_001_example.md&read=1
+```
+
+If the viewer server is not already running, start it with the equivalent fallback command:
+
+```bash
+logics-manager view --focus logics/request/req_001_example.md --open
+logics-manager view --focus req_001_example --read --open
+```
+
+This is the recommended assistant handoff pattern: provide the local viewer link for an already-running viewer and the CLI fallback command for a stopped server. Focus targets accept workflow refs such as `req_001_example`, `item_001_example`, or `task_001_example`, plus repo-relative Logics Markdown paths. Traversal and non-Logics paths are rejected.
+
 ### CLI Contracts
 
 Workflow target arguments accept these forms:
@@ -347,6 +388,7 @@ Windows notes:
 - Create a fixture request with `logics-manager flow new request --title "Smoke test"` and confirm the compact synthetic request shape is generated.
 - Create a backlog item and a task from the UI and confirm markdown is generated.
 - Open `Read` on a Mermaid-bearing doc and confirm the graph is rendered.
+- Run `logics-manager view --port 0 --open`, confirm the browser viewer loads repository docs, then stop it with `Ctrl+C`.
 - Promote request -> backlog and confirm links are updated.
 - Confirm request/backlog/task generation fails fast if a Mermaid signature or traceability block is stale instead of waiting for audit to find it later.
 - Promote backlog -> task and confirm task document is generated.
@@ -391,6 +433,22 @@ npm run dev
 
 `npm run dev` requires the `code` CLI on PATH, so the F5 path above remains the safest cross-platform dev entrypoint.
 
+### Browser UI Debugging
+
+Use the real local viewer for repository data:
+
+```bash
+logics-manager view --open
+```
+
+Use the mock webview harness only when developing the shared browser/webview UI without VS Code:
+
+```bash
+npm run debug:webview
+```
+
+The harness runs at `http://localhost:4173/` and supports mock scenarios such as `/?scenario=empty` and `/?scenario=error`. It does not execute real VS Code commands or workflow writes.
+
 ## Deploy / Release (VSIX)
 
 1. Bump the version in `package.json`, `pyproject.toml`, and root `VERSION` when preparing a release manually.
@@ -446,6 +504,7 @@ If the current plugin version is already published, `logics-manager assist next-
 - Logics docs lint: `npm run lint:logics`
 - Logics workflow audit + docs lint: `npm run audit:logics`
 - Strict Logics governance audit: `npm run audit:logics:strict`
+- Local browser viewer smoke: `logics-manager view --port 0 --open`
 - Fast extension-focused local check: `npm run ci:fast`
 - Full CI-equivalent local check: `npm run ci:check`
 - Security audit policy gate: `npm run audit:ci`

{logics_manager-2.2.0 → logics_manager-2.3.0}/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] = []

logics_manager-2.3.0/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,
+    }

logics_manager-2.3.0/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),
+    }

{logics_manager-2.2.0 → logics_manager-2.3.0}/logics_manager/cli.py

@@ -20,6 +20,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 +38,7 @@ ROOT_COMMANDS = (
     "product-consistency",
     "status",
     "lint",
+    "view",
     "config",
     "doctor",
     "mcp",
@@ -88,6 +90,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 +133,18 @@ def get_cli_version() -> str:
     return "0.0.0"
 
 
+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 +162,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":
@@ -240,6 +256,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)