@grifhinz/logics-manager 2.9.1 → 2.9.3

package/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.9.1-4C8BF5)
+![Version](https://img.shields.io/badge/version-v2.9.3-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-4.1.2-6E9F18?logo=vitest&logoColor=white)
@@ -51,7 +51,21 @@ The CLI owns the behavior. The extension and MCP server call into it instead of
 
 ## Quick Start
 
-Install the CLI from this repository:
+Install the CLI from PyPI:
+
+```bash
+python3.11 -m pip install logics-manager
+logics-manager --help
+```
+
+For an isolated user-level install, use `pipx`:
+
+```bash
+pipx install logics-manager
+logics-manager --help
+```
+
+Install the CLI from this repository when developing locally:
 
 ```bash
 python3.11 -m pip install .
@@ -67,7 +81,7 @@ pipx ensurepath
 pipx install logics-manager
 ```
 
-Or install the npm package:
+Or install the npm package from npm:
 
 ```bash
 npm install -g @grifhinz/logics-manager
@@ -151,6 +165,17 @@ logics-manager view --open
 
 The viewer starts a localhost-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.
 
+The topbar includes focused operational views:
+
+| View | Purpose |
+| --- | --- |
+| Explorer | Read-only repository tree with bounded previews for text, images, directories, oversized files, and unsupported binary files. |
+| Workshop | Local terminals and command runs. Terminals use the vendored xterm.js frontend; commands are discovered from `package.json` and `pyproject.toml` scripts and stream output over SSE. |
+| Git | Repository status, changed files, and diffs for review-oriented inspection. |
+| CI | Local/remote validation status surfaced for release and handoff checks. |
+| CDX | Guarded assistant workflows for audits, release reviews, corpus planning, and pre-release preparation. |
+| Settings | Viewer preferences, display controls, refresh behavior, and local UI state. |
+
 Viewer preferences are stored locally in the browser profile. Auto-refresh
 restores the interval chosen in the viewer unless the launch command explicitly
 sets `--refresh-interval`, in which case that launch value controls only the
@@ -161,6 +186,24 @@ When workspace inspection is available, the topbar shows an `Explorer` view
 before `Git`; it provides a read-only file tree and bounded previews for text,
 directories, images, oversized files, and unsupported binary files.
 
+The Workshop view is local-machine only. Terminal sessions and command runs are
+created on the machine running `logics-manager view`, appear with running-count
+badges in the topbar, and can be stopped from the UI. Terminal sessions are
+cleaned up after the browser disconnects, while quick reloads can reattach
+without leaving duplicate sessions behind.
+
+For phone or tablet inspection on the same trusted network, launch with `--lan`:
+
+```bash
+logics-manager view --lan --open
+```
+
+LAN mode binds to `0.0.0.0`, computes a reachable local-network URL, and adds a
+per-session bearer token for non-loopback requests. The browser receives a
+shareable URL and, when the optional `segno` package is installed, a QR code.
+LAN mode is still read-only at the HTTP layer; workflow mutations continue to go
+through canonical CLI commands.
+
 The CDX missions panel includes guarded workflows for audits, release reviews,
 turning a free-form wish into a structured Logics request, preparing a corpus
 plan, and preparing a guarded pre-release from an editable `vX.X.X` version.
@@ -177,6 +220,7 @@ Useful options:
 
 ```bash
 logics-manager view --port 0 --open
+logics-manager view --lan --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
@@ -284,6 +328,12 @@ npm list -g @grifhinz/logics-manager --depth=0
 
 If the direct npm binary shows the expected version, remove the older Python install or move the npm global `bin` directory earlier on `PATH`. In zsh, run `rehash` or open a new terminal after changing installs so the shell forgets any cached command location.
 
+When installed with `pipx` from a local path, `self-update` reports that original
+spec, for example `from spec '/path/to/logics-manager'`. That installation is
+updated from the local working tree, not from the PyPI artifact. Use
+`pipx uninstall logics-manager && pipx install logics-manager` when you want to
+switch back to the published PyPI package.
+
 ## VS Code Extension
 
 The VS Code extension is the human cockpit around the same runtime. It helps you:
@@ -377,6 +427,13 @@ python3 -m logics_manager mcp connect --repo-root . --public-url https://example
 
 The connector plan prints the bearer token when used, server command, tunnel target, assistant connector URL, auth mode, auth header, smoke checks, warnings, and cleanup steps.
 
+## Security
+
+See [SECURITY.md](SECURITY.md) for supported versions and vulnerability
+reporting guidance. Do not publish suspected vulnerabilities in public issues
+until they are triaged; use GitHub's private vulnerability reporting or a
+private security advisory draft for this repository.
+
 ## Assistant Model
 
 The project is local-first:

package/VERSION

@@ -1 +1 @@
-2.9.1
+2.9.3

package/logics_manager/sync.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import re
 from copy import deepcopy
 from dataclasses import dataclass
@@ -43,12 +44,28 @@ APPROVED_WORKFLOW_INDICATORS = ("Status", "Progress", "Understanding", "Confiden
 MAX_MUTATION_TEXT_CHARS = 2000
 
 
-def _read_text(path: Path) -> str:
-    return path.read_text(encoding="utf-8")
+def _read_text(repo_root: Path, path: Path) -> str:
+    root = os.path.realpath(repo_root)
+    absolute_name = os.path.realpath(path)
+    try:
+        common = os.path.commonpath([root, absolute_name])
+    except ValueError as exc:
+        raise SystemExit(f"Unsupported workflow doc path `{path}`.") from exc
+    if common != root:
+        raise SystemExit(f"Unsupported workflow doc path `{path}`.")
+    absolute = Path(absolute_name)
+    approved_dirs = {Path(os.path.realpath(repo_root / kind["directory"])) for kind in DOC_KINDS.values()}
+    if absolute.parent not in approved_dirs:
+        raise SystemExit(f"Unsupported workflow doc path `{path}`.")
+    return absolute.read_text(encoding="utf-8")
+
+
+def _read_lines(repo_root: Path, path: Path) -> list[str]:
+    return _read_text(repo_root, path).splitlines()
 
 
-def _read_lines(path: Path) -> list[str]:
-    return _read_text(path).splitlines()
+def _is_relative_path(path: Path) -> bool:
+    return not path.is_absolute() and ".." not in path.parts
 
 
 def _indicator_value(lines: list[str], key: str) -> str | None:
@@ -128,7 +145,7 @@ def _detect_workflow_kind(path: Path) -> str:
 
 
 def parse_workflow_doc(path: Path, *, repo_root: Path | None = None) -> WorkflowDocModel:
-    text = _read_text(path)
+    text = _read_text(repo_root or path.parent.parent.parent, path)
     lines = text.splitlines()
     sections = _extract_sections(text)
     indicators = {key: value for key in ("From version", "Schema version", "Status", "Understanding", "Confidence", "Progress", "Complexity", "Theme", "Date", "Drivers", "Related request", "Related backlog", "Related task", "Reminder") if (value := _indicator_value(lines, key)) is not None}
@@ -307,6 +324,7 @@ def _build_context_pack(
 
 
 def _resolve_target_docs(repo_root: Path, sources: list[str]) -> list[tuple[str, Path]]:
+    candidates: dict[str, tuple[str, Path]] = {}
     if not sources:
         targets: list[tuple[str, Path]] = []
         for kind_name, kind in DOC_KINDS.items():
@@ -317,25 +335,25 @@ def _resolve_target_docs(repo_root: Path, sources: list[str]) -> list[tuple[str,
                 targets.append((kind_name, path))
         return targets
 
+    for kind_name, kind in DOC_KINDS.items():
+        directory = repo_root / kind["directory"]
+        if not directory.is_dir():
+            continue
+        for path in sorted(directory.glob(f"{kind['prefix']}_*.md")):
+            candidates[path.relative_to(repo_root).as_posix()] = (kind_name, path)
+            candidates[path.stem] = (kind_name, path)
+
     resolved: list[tuple[str, Path]] = []
     for source in sources:
         raw_source = Path(source)
-        if raw_source.is_absolute() or any(part == ".." for part in raw_source.parts):
+        if not _is_relative_path(raw_source):
             raise SystemExit(f"Unsupported workflow doc target `{source}`.")
-        candidate = (repo_root / source).resolve()
-        if candidate.is_file():
-            for kind_name, kind in DOC_KINDS.items():
-                if candidate.parent == (repo_root / kind["directory"]).resolve():
-                    resolved.append((kind_name, candidate))
-                    break
+        normalized = raw_source.as_posix()
+        target = candidates.get(normalized) or candidates.get(Path(source).stem if "/" not in normalized else "")
+        if target is not None:
+            resolved.append(target)
             continue
-        for kind_name, kind in DOC_KINDS.items():
-            path = repo_root / kind["directory"] / f"{source}.md"
-            if path.is_file():
-                resolved.append((kind_name, path))
-                break
-        else:
-            raise SystemExit(f"Could not resolve workflow doc target `{source}`.")
+        raise SystemExit(f"Could not resolve workflow doc target `{source}`.")
     return resolved
 
 
@@ -385,7 +403,7 @@ def read_logics_doc_payload(repo_root: Path, source: str, *, max_chars: int = 40
         for heading in requested_sections
         if heading in doc.sections
     }
-    text = _read_text(path)
+    text = _read_text(repo_root, path)
     return {
         "ref": doc.ref,
         "kind": doc.kind,
@@ -464,7 +482,7 @@ def search_logics_docs_payload(
         doc = docs_by_ref.get(ref)
         if doc is None:
             continue
-        text = _strip_mermaid_blocks(_read_text(repo_root / doc.path))
+        text = _strip_mermaid_blocks(_read_text(repo_root, repo_root / doc.path))
         lines = text.splitlines()
         for idx, line in enumerate(lines):
             if normalized_query in line.lower():
@@ -531,7 +549,7 @@ def update_workflow_indicators_payload(repo_root: Path, source: str, indicators:
     if len(targets) != 1:
         raise SystemExit(f"Expected one workflow doc target for `{source}`.")
     kind, path = targets[0]
-    lines = _read_lines(path)
+    lines = _read_lines(repo_root, path)
     changed = False
     for key in APPROVED_WORKFLOW_INDICATORS:
         if key not in cleaned:
@@ -573,7 +591,7 @@ def append_workflow_note_payload(repo_root: Path, source: str, *, note_kind: str
     section = _section_for_note(kind, note_kind)
     cleaned = _clean_mutation_text(text, field="text")
     bullet = f"- {cleaned}"
-    lines = _read_lines(path)
+    lines = _read_lines(repo_root, path)
     insert_at = None
     for idx, line in enumerate(lines):
         if line.startswith("# ") and line[2:].strip().lower() == section.lower():
@@ -631,13 +649,13 @@ def _collect_docs_linking_ref(repo_root: Path, kind: str, ref: str) -> list[Path
     directory = repo_root / DOC_KINDS[kind]["directory"]
     linked: list[Path] = []
     for path in sorted(directory.glob("*.md")):
-        if ref in _read_text(path):
+        if ref in _read_text(repo_root, path):
             linked.append(path)
     return linked
 
 
-def _is_doc_done(path: Path, kind: str) -> bool:
-    lines = _read_lines(path)
+def _is_doc_done(repo_root: Path, path: Path, kind: str) -> bool:
+    lines = _read_lines(repo_root, path)
     status_value = _indicator_value(lines, "Status")
     if status_value is not None and " ".join(status_value.split()).lower() in {"done", "archived"}:
         return True
@@ -648,10 +666,10 @@ def _is_doc_done(path: Path, kind: str) -> bool:
     return False
 
 
-def _close_doc(path: Path, kind: str, dry_run: bool) -> None:
+def _close_doc(repo_root: Path, path: Path, kind: str, dry_run: bool) -> None:
     if dry_run:
         return
-    lines = _read_lines(path)
+    lines = _read_lines(repo_root, path)
     updated = []
     saw_status = False
     saw_progress = False
@@ -696,7 +714,7 @@ def _refresh_workflow_mermaid_signature_text(text: str, kind: str, *, repo_root:
 
 
 def refresh_workflow_mermaid_signature_file(path: Path, kind: str, dry_run: bool, *, repo_root: Path | None = None) -> bool:
-    original = _read_text(path)
+    original = _read_text(repo_root or path.parent.parent.parent, path)
     refreshed, changed = _refresh_workflow_mermaid_signature_text(original, kind, repo_root=repo_root, dry_run=dry_run)
     if not changed:
         return False
@@ -711,14 +729,14 @@ def _close_eligible_requests(repo_root: Path, dry_run: bool, *, quiet: bool = Fa
     scanned = 0
     for request_path in sorted(request_dir.glob("req_*.md")):
         scanned += 1
-        if _is_doc_done(request_path, "request"):
+        if _is_doc_done(repo_root, request_path, "request"):
             continue
         request_ref = request_path.stem
         linked_items = _collect_docs_linking_ref(repo_root, "backlog", request_ref)
         if not linked_items:
             continue
-        if all(_is_doc_done(item_path, "backlog") for item_path in linked_items):
-            _close_doc(request_path, "request", dry_run)
+        if all(_is_doc_done(repo_root, item_path, "backlog") for item_path in linked_items):
+            _close_doc(repo_root, request_path, "request", dry_run)
             if not quiet:
                 print(f"Auto-closed request {request_ref} (all linked backlog items are done).")
             closed += 1

package/logics_manager/viewer.py

@@ -692,8 +692,10 @@ def _resolve_repo_doc_path(repo_root: Path, rel_path: str) -> tuple[str, Path]:
 def edit_doc_payload(repo_root: Path, rel_path: str, *, launcher: Any | None = None) -> dict[str, str]:
     normalized, absolute = _resolve_repo_doc_path(repo_root, rel_path)
     command = _system_editor_command(absolute)
-    runner = launcher or subprocess.Popen
-    runner(command)
+    if launcher is not None:
+        launcher(command)
+    else:
+        webbrowser.open(absolute.as_uri())
     return {
         "path": normalized,
         "command": command[0],
@@ -701,13 +703,25 @@ def edit_doc_payload(repo_root: Path, rel_path: str, *, launcher: Any | None = N
 
 
 def _resolve_openable_file_path(repo_root: Path, file_path: str) -> Path:
-    raw_path = unquote(file_path).strip()
-    if not raw_path:
+    raw_value = unquote(file_path).strip()
+    if raw_value.startswith(("/", "\\")) or re.match(r"^[A-Za-z]:", raw_value):
+        raise ValueError("File path escapes repository root.")
+    normalized = raw_value.replace("\\", "/").lstrip("/")
+    if not normalized:
         raise ValueError("Missing file path.")
-    candidate = Path(raw_path).expanduser()
-    if not candidate.is_absolute():
-        candidate = repo_root / raw_path.lstrip("/\\")
-    absolute = candidate.resolve()
+    raw_parts = tuple(part for part in normalized.split("/") if part)
+    if any(part == ".." for part in raw_parts):
+        raise ValueError("File path escapes repository root.")
+    candidate = repo_root.joinpath(*raw_parts)
+    root = os.path.realpath(repo_root)
+    absolute_name = os.path.realpath(candidate)
+    try:
+        common = os.path.commonpath([root, absolute_name])
+    except ValueError as exc:
+        raise ValueError("File path escapes repository root.") from exc
+    if common != root:
+        raise ValueError("File path escapes repository root.")
+    absolute = Path(absolute_name)
     if not absolute.is_file():
         raise FileNotFoundError(str(candidate))
     return absolute
@@ -716,8 +730,10 @@ def _resolve_openable_file_path(repo_root: Path, file_path: str) -> Path:
 def open_file_payload(repo_root: Path, file_path: str, *, launcher: Any | None = None) -> dict[str, str]:
     absolute = _resolve_openable_file_path(repo_root, file_path)
     command = _system_editor_command(absolute)
-    runner = launcher or subprocess.Popen
-    runner(command)
+    if launcher is not None:
+        launcher(command)
+    else:
+        webbrowser.open(absolute.as_uri())
     return {
         "path": str(absolute),
         "command": command[0],
@@ -751,8 +767,10 @@ def file_preview_payload(
 def open_repo_folder_payload(repo_root: Path, *, launcher: Any | None = None) -> dict[str, str]:
     root = repo_root.resolve()
     command = _system_editor_command(root)
-    runner = launcher or subprocess.Popen
-    runner(command)
+    if launcher is not None:
+        launcher(command)
+    else:
+        webbrowser.open(root.as_uri())
     return {
         "path": str(root),
         "command": command[0],
@@ -763,10 +781,22 @@ def _system_editor_command(path: Path) -> list[str]:
     if sys.platform == "darwin":
         return ["open", str(path)]
     if os.name == "nt":
-        return ["cmd", "/c", "start", "", str(path)]
+        return ["explorer.exe", str(path)]
     return ["xdg-open", str(path)]
 
 
+STATIC_CONTENT_TYPES = {
+    ".css": "text/css; charset=utf-8",
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".map": "application/json; charset=utf-8",
+    ".png": "image/png",
+    ".svg": "image/svg+xml",
+    ".wasm": "application/wasm",
+}
+
+
 def _run_read_only_git(repo_root: Path, args: list[str], *, runner: Any | None = None) -> subprocess.CompletedProcess[str]:
     command = ["git", *args]
     git_runner = runner or subprocess.run
@@ -3074,14 +3104,23 @@ class LogicsViewerRequestHandler(BaseHTTPRequestHandler):
     def _send_error_json(self, status: HTTPStatus, message: str) -> None:
         self._send_json({"ok": False, "error": message}, status=status.value)
 
-    def _serve_file(self, path: Path) -> None:
-        if not path.is_file():
+    def _serve_file(self, path: Path, *, root: Path) -> None:
+        root_name = os.path.realpath(root)
+        absolute_name = os.path.realpath(path)
+        try:
+            common = os.path.commonpath([root_name, absolute_name])
+        except ValueError:
+            self._send_error_json(HTTPStatus.NOT_FOUND, "Not found")
+            return
+        if common != root_name:
+            self._send_error_json(HTTPStatus.NOT_FOUND, "Not found")
+            return
+        absolute = Path(absolute_name)
+        if not absolute.is_file():  # lgtm [py/path-injection]
             self._send_error_json(HTTPStatus.NOT_FOUND, "Not found")
             return
-        content_type = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
-        if content_type.startswith("text/") or path.suffix in {".js", ".css", ".html"}:
-            content_type = f"{content_type}; charset=utf-8"
-        self._send_bytes(path.read_bytes(), content_type=content_type)
+        content_type = STATIC_CONTENT_TYPES.get(absolute.suffix.lower(), "application/octet-stream")
+        self._send_bytes(absolute.read_bytes(), content_type=content_type)  # lgtm [py/path-injection]
 
     def _stream_workshop_terminal(self, session: "WorkshopTerminalSession", parsed: Any) -> None:
         import time as _time
@@ -3254,28 +3293,31 @@ class LogicsViewerRequestHandler(BaseHTTPRequestHandler):
             return
         route = parsed.path
         if route == "/":
-            self._serve_file(VIEWER_ROOT / "index.html")
+            self._serve_file(VIEWER_ROOT / "index.html", root=VIEWER_ROOT)
             return
         if route == "/browser-host.js":
-            self._serve_file(VIEWER_ROOT / "browser-host.js")
+            self._serve_file(VIEWER_ROOT / "browser-host.js", root=VIEWER_ROOT)
             return
         if route == "/viewer.css":
-            self._serve_file(VIEWER_ROOT / "viewer.css")
+            self._serve_file(VIEWER_ROOT / "viewer.css", root=VIEWER_ROOT)
             return
         if route == "/vendor/mermaid.min.js":
             vendor_path = DIST_VENDOR_ROOT / "mermaid.min.js"
+            vendor_root = DIST_VENDOR_ROOT
             if not vendor_path.is_file():
                 vendor_path = NODE_MERMAID_ROOT / "mermaid.min.js"
+                vendor_root = NODE_MERMAID_ROOT
             if not vendor_path.is_file():
                 vendor_path = PACKAGE_VENDOR_ROOT / "mermaid.min.js"
-            self._serve_file(vendor_path)
+                vendor_root = PACKAGE_VENDOR_ROOT
+            self._serve_file(vendor_path, root=vendor_root)
             return
         if route.startswith("/media/"):
             media_path = (SHARED_MEDIA_ROOT / route.removeprefix("/media/")).resolve()
             if SHARED_MEDIA_ROOT.resolve() != media_path and SHARED_MEDIA_ROOT.resolve() not in media_path.parents:
                 self._send_error_json(HTTPStatus.NOT_FOUND, "Not found")
                 return
-            self._serve_file(media_path)
+            self._serve_file(media_path, root=SHARED_MEDIA_ROOT)
             return
         if route == "/api/items":
             self._send_json(
@@ -3399,7 +3441,7 @@ class LogicsViewerRequestHandler(BaseHTTPRequestHandler):
                     self._send_error_json(HTTPStatus.BAD_REQUEST, "Workspace file is not an image preview.")
                     return
                 _normalized, absolute = _resolve_workspace_path(self.server.repo_root, rel_path)
-                self._serve_file(absolute)
+                self._serve_file(absolute, root=self.server.repo_root)
             except (FileNotFoundError, ValueError) as exc:
                 self._send_error_json(HTTPStatus.NOT_FOUND, str(exc))
             return

package/package.json

@@ -2,7 +2,7 @@
   "name": "@grifhinz/logics-manager",
   "displayName": "Logics Orchestrator",
   "description": "Visual orchestration for Logics workflows inside VS Code.",
-  "version": "2.9.1",
+  "version": "2.9.3",
   "publisher": "cdx-logics",
   "icon": "clients/shared-web/media/icon.png",
   "repository": {
@@ -159,7 +159,7 @@
     "@typescript-eslint/parser": "^8.58.1",
     "@vitest/coverage-v8": "^4.1.2",
     "@vscode/vsce": "^3.9.1",
-    "esbuild": "^0.25.10",
+    "esbuild": "^0.28.1",
     "eslint": "^10.2.0",
     "jsdom": "^25.0.1",
     "mermaid": "^11.14.0",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "logics-manager"
-version = "2.9.1"
+version = "2.9.3"
 description = "Canonical Logics CLI"
 requires-python = ">=3.10"