@grifhinz/logics-manager 2.1.1 → 2.2.0

package/logics_manager/mcp.py

@@ -8,8 +8,10 @@ import json
 import os
 import re
 import secrets
+import signal
 import subprocess
 import sys
+import time
 from pathlib import Path
 from typing import Any
 from urllib.error import URLError
@@ -19,6 +21,7 @@ from urllib.request import Request, urlopen
 from .audit import audit_payload
 from .config import ConfigError, find_repo_root
 from .flow import flow_list_payload
+from .insights import followups_payload, health_payload, product_consistency_payload, status_payload
 from .lint import expected_workflow_mermaid_signature, lint_payload
 from .sync import append_workflow_note_payload, build_context_pack_payload, list_logics_docs_payload, read_logics_doc_payload, search_logics_docs_payload, update_workflow_indicators_payload
 
@@ -115,6 +118,17 @@ TOOL_DEFINITIONS: list[dict[str, Any]] = [
         ),
         "annotations": {"readOnlyHint": False, "idempotentHint": False, "destructiveHint": False},
     },
+    {
+        "name": "list_companion_docs",
+        "description": "List Logics companion documents such as product briefs and architecture decisions.",
+        "inputSchema": _tool_schema(
+            {
+                "kind": {"type": "string", "enum": ["all", "product", "architecture"]},
+                "limit": {"type": "integer"},
+            }
+        ),
+        "annotations": {"readOnlyHint": True, "idempotentHint": True, "destructiveHint": False},
+    },
     {
         "name": "list_active_work",
         "description": "List active Logics request, backlog, and task documents.",
@@ -175,6 +189,37 @@ TOOL_DEFINITIONS: list[dict[str, Any]] = [
         ),
         "annotations": {"readOnlyHint": True, "idempotentHint": True, "destructiveHint": False},
     },
+    {
+        "name": "get_logics_status",
+        "description": "Summarize open Logics workflow docs and next actions.",
+        "inputSchema": _tool_schema({"limit": {"type": "integer"}}),
+        "annotations": {"readOnlyHint": True, "idempotentHint": True, "destructiveHint": False},
+    },
+    {
+        "name": "get_logics_health",
+        "description": "Show Logics workflow health counts and issue signals.",
+        "inputSchema": _tool_schema({"limit": {"type": "integer"}}),
+        "annotations": {"readOnlyHint": True, "idempotentHint": True, "destructiveHint": False},
+    },
+    {
+        "name": "list_logics_followups",
+        "description": "List actionable Logics follow-up areas with request creation commands.",
+        "inputSchema": _tool_schema(
+            {
+                "source_kind": {"type": "string", "enum": ["all", "request", "backlog", "task", "product", "architecture"]},
+                "include_closed": {"type": "boolean"},
+                "closed_only": {"type": "boolean"},
+                "limit": {"type": "integer"},
+            }
+        ),
+        "annotations": {"readOnlyHint": True, "idempotentHint": True, "destructiveHint": False},
+    },
+    {
+        "name": "check_product_consistency",
+        "description": "Check product brief lineage links for active and validated product docs.",
+        "inputSchema": _tool_schema({"limit": {"type": "integer"}}),
+        "annotations": {"readOnlyHint": True, "idempotentHint": True, "destructiveHint": False},
+    },
     {
         "name": "finish_task",
         "description": "Finish a Logics task through the canonical flow finish task command.",
@@ -277,6 +322,25 @@ TOOL_DEFINITIONS: list[dict[str, Any]] = [
         "inputSchema": _tool_schema({"paths": {"type": "array", "items": {"type": "string"}}}),
         "annotations": {"readOnlyHint": True, "idempotentHint": True, "destructiveHint": False},
     },
+    {
+        "name": "delete_logics_file",
+        "description": "Delete one bounded Logics Markdown file from an approved Logics directory.",
+        "inputSchema": _tool_schema({"path": {"type": "string"}, "dry_run": {"type": "boolean"}}, ["path"]),
+        "annotations": {"readOnlyHint": False, "idempotentHint": False, "destructiveHint": True},
+    },
+    {
+        "name": "rename_logics_file",
+        "description": "Rename one bounded Logics Markdown file within approved Logics directories.",
+        "inputSchema": _tool_schema(
+            {
+                "source_path": {"type": "string"},
+                "destination_path": {"type": "string"},
+                "dry_run": {"type": "boolean"},
+            },
+            ["source_path", "destination_path"],
+        ),
+        "annotations": {"readOnlyHint": False, "idempotentHint": False, "destructiveHint": False},
+    },
 ]
 TOOLS_BY_NAME = {str(tool["name"]): tool for tool in TOOL_DEFINITIONS}
 
@@ -354,6 +418,13 @@ def _relative_path(repo_root: Path, raw_path: str, allowed_dirs: tuple[str, ...]
     return normalized
 
 
+def _markdown_file_path(repo_root: Path, raw_path: str, allowed_dirs: tuple[str, ...] = ALLOWED_WRITE_DIRS) -> Path:
+    rel_path = _relative_path(repo_root, raw_path, allowed_dirs)
+    if rel_path.suffix != ".md":
+        raise McpToolError("invalid_path", "Only Markdown files are accepted.", details={"path": raw_path, "extension": rel_path.suffix})
+    return rel_path
+
+
 def _run_command(repo_root: Path, args: list[str]) -> subprocess.CompletedProcess[str]:
     command = [sys.executable, "-m", "logics_manager", *args]
     result = subprocess.run(command, cwd=repo_root, check=False, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
@@ -511,8 +582,16 @@ def _audit_status(repo_root: Path) -> dict[str, Any]:
     payload = audit_payload(repo_root, legacy_cutoff_version="1.1.0", group_by_doc=True)
     return {
         "ok": bool(payload.get("ok")),
+        "can_continue": bool(payload.get("can_continue", payload.get("ok"))),
+        "release_ready": bool(payload.get("release_ready", payload.get("ok"))),
         "issue_count": payload.get("issue_count", 0),
+        "warning_count": payload.get("warning_count", 0),
+        "strict_count": payload.get("strict_count", 0),
+        "finding_count": payload.get("finding_count", payload.get("issue_count", 0)),
         "issues": payload.get("issues", []),
+        "warnings": payload.get("warnings", []),
+        "strict": payload.get("strict", []),
+        "findings": payload.get("findings", payload.get("issues", [])),
         "issues_by_doc": payload.get("issues_by_doc", {}),
     }
 
@@ -597,6 +676,74 @@ def _document_preview(repo_root: Path, rel_path: str, *, max_chars: int = 1600)
     }
 
 
+def _indicator_from_lines(lines: list[str], key: str) -> str | None:
+    prefix = f"> {key}:"
+    for line in lines:
+        if line.startswith(prefix):
+            return line.split(":", 1)[1].strip()
+    return None
+
+
+def _title_from_heading(lines: list[str], fallback: str) -> str:
+    for line in lines:
+        if not line.startswith("## "):
+            continue
+        heading = line[3:].strip()
+        if " - " in heading:
+            return heading.split(" - ", 1)[1].strip()
+        return heading
+    return fallback
+
+
+def _parse_companion_refs(value: str | None) -> list[str]:
+    if not value or value == "(none yet)":
+        return []
+    refs = re.findall(r"`([^`]+)`", value)
+    if refs:
+        return [ref for ref in refs if ref not in {"(none)", "(none yet)"}]
+    return [part.strip() for part in value.split(",") if part.strip() and part.strip() not in {"(none)", "(none yet)"}]
+
+
+def _companion_doc_entry(repo_root: Path, rel_path: Path, kind: str) -> dict[str, Any]:
+    path = repo_root / rel_path
+    lines = path.read_text(encoding="utf-8").splitlines()
+    related = {
+        "request": _parse_companion_refs(_indicator_from_lines(lines, "Related request")),
+        "backlog": _parse_companion_refs(_indicator_from_lines(lines, "Related backlog")),
+        "task": _parse_companion_refs(_indicator_from_lines(lines, "Related task")),
+        "architecture": _parse_companion_refs(_indicator_from_lines(lines, "Related architecture")),
+    }
+    return {
+        "kind": kind,
+        "ref": rel_path.stem,
+        "path": rel_path.as_posix(),
+        "title": _title_from_heading(lines, rel_path.stem),
+        "status": _indicator_from_lines(lines, "Status") or "Unknown",
+        "related": {key: refs for key, refs in related.items() if refs},
+    }
+
+
+def _list_companion_docs(repo_root: Path, *, kind: str = "all", limit: int = 50) -> dict[str, Any]:
+    if kind not in {"all", "product", "architecture"}:
+        raise McpToolError("invalid_argument_value", "Unsupported companion document kind.", details={"kind": kind, "allowed": ["all", "product", "architecture"]})
+    targets = []
+    if kind in {"all", "product"}:
+        targets.append(("product", Path("logics/product"), "prod_*.md"))
+    if kind in {"all", "architecture"}:
+        targets.append(("architecture", Path("logics/architecture"), "adr_*.md"))
+    items: list[dict[str, Any]] = []
+    for doc_kind, directory, pattern in targets:
+        root = repo_root / directory
+        if not root.is_dir():
+            continue
+        for path in sorted(root.glob(pattern)):
+            if path.is_file() and not path.is_symlink():
+                items.append(_companion_doc_entry(repo_root, path.relative_to(repo_root), doc_kind))
+    items.sort(key=lambda item: str(item["path"]))
+    bounded_items = items[:limit]
+    return {"kind": kind, "limit": limit, "count": len(bounded_items), "total_count": len(items), "items": bounded_items}
+
+
 def _bounded_int(value: Any, *, default: int, maximum: int) -> int:
     if not isinstance(value, int) or isinstance(value, bool):
         return default
@@ -659,6 +806,9 @@ def call_tool(name: str, arguments: dict[str, Any] | None = None, *, repo_root:
         if kind not in {"all", "request", "backlog", "task"}:
             raise McpToolError("invalid_argument_value", "Unsupported list kind.", details={"kind": kind, "allowed": ["all", "request", "backlog", "task"]})
         return {"ok": True, "items": flow_list_payload(root, kind=kind)["entries"]}
+    if name == "list_companion_docs":
+        payload = _list_companion_docs(root, kind=str(args.get("kind") or "all"), limit=_bounded_int(args.get("limit"), default=50, maximum=200))
+        return {"ok": True, **payload}
     if name == "read_logics_doc":
         try:
             payload = read_logics_doc_payload(root, str(args.get("source") or ""), max_chars=_bounded_int(args.get("max_chars"), default=4000, maximum=12000), sections=args.get("sections") if isinstance(args.get("sections"), list) else None)
@@ -693,6 +843,24 @@ def call_tool(name: str, arguments: dict[str, Any] | None = None, *, repo_root:
         except SystemExit as exc:
             raise _mcp_read_error(exc) from exc
         return {"ok": True, **payload}
+    if name == "get_logics_status":
+        return status_payload(root, limit=_bounded_int(args.get("limit"), default=10, maximum=100))
+    if name == "get_logics_health":
+        return health_payload(root, limit=_bounded_int(args.get("limit"), default=10, maximum=100))
+    if name == "list_logics_followups":
+        include_closed = bool(args.get("include_closed", False))
+        closed_only = bool(args.get("closed_only", False))
+        if include_closed and closed_only:
+            raise McpToolError("invalid_argument_value", "include_closed and closed_only are mutually exclusive.", details={"arguments": ["include_closed", "closed_only"]})
+        return followups_payload(
+            root,
+            limit=_bounded_int(args.get("limit"), default=50, maximum=200),
+            source_kind=str(args.get("source_kind") or "all"),
+            include_closed=include_closed,
+            closed_only=closed_only,
+        )
+    if name == "check_product_consistency":
+        return product_consistency_payload(root, limit=_bounded_int(args.get("limit"), default=50, maximum=200))
     if name == "finish_task":
         rel_path = _relative_path(root, str(args.get("task_path") or ""), ("logics/tasks",))
         dry_run = bool(args.get("dry_run", False))
@@ -813,6 +981,58 @@ def call_tool(name: str, arguments: dict[str, Any] | None = None, *, repo_root:
         raw_paths = args.get("paths")
         paths = [str(path) for path in raw_paths] if isinstance(raw_paths, list) else None
         return _show_git_diff(root, paths)
+    if name == "delete_logics_file":
+        rel_path = _markdown_file_path(root, str(args.get("path") or ""))
+        target = root / rel_path
+        dry_run = bool(args.get("dry_run", False))
+        if not target.exists():
+            raise McpToolError("not_found", "Logics file not found.", details={"path": rel_path.as_posix()})
+        if not target.is_file() or target.is_symlink():
+            raise McpToolError("invalid_path", "Only regular Markdown files can be deleted.", details={"path": rel_path.as_posix()})
+        if not dry_run:
+            _ensure_no_dirty_conflict(root, [rel_path.as_posix()])
+            target.unlink()
+        return _workflow_write_result(
+            root,
+            {
+                "path": rel_path.as_posix(),
+                "dry_run": dry_run,
+                "deleted": not dry_run,
+                "would_delete": dry_run,
+                "summary": f"{'Would delete' if dry_run else 'Deleted'} {rel_path.as_posix()}",
+            },
+            paths=[rel_path.as_posix()],
+        )
+    if name == "rename_logics_file":
+        source_rel = _markdown_file_path(root, str(args.get("source_path") or ""))
+        destination_rel = _markdown_file_path(root, str(args.get("destination_path") or ""))
+        source = root / source_rel
+        destination = root / destination_rel
+        dry_run = bool(args.get("dry_run", False))
+        if source_rel == destination_rel:
+            raise McpToolError("invalid_path", "Source and destination paths must differ.", details={"source_path": source_rel.as_posix(), "destination_path": destination_rel.as_posix()})
+        if not source.exists():
+            raise McpToolError("not_found", "Source Logics file not found.", details={"source_path": source_rel.as_posix()})
+        if not source.is_file() or source.is_symlink():
+            raise McpToolError("invalid_path", "Only regular Markdown files can be renamed.", details={"source_path": source_rel.as_posix()})
+        if destination.exists():
+            raise McpToolError("already_exists", "Destination already exists.", details={"destination_path": destination_rel.as_posix()})
+        if not dry_run:
+            _ensure_no_dirty_conflict(root, [source_rel.as_posix(), destination_rel.as_posix()])
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            source.rename(destination)
+        return _workflow_write_result(
+            root,
+            {
+                "source_path": source_rel.as_posix(),
+                "destination_path": destination_rel.as_posix(),
+                "dry_run": dry_run,
+                "renamed": not dry_run,
+                "would_rename": dry_run,
+                "summary": f"{'Would rename' if dry_run else 'Renamed'} {source_rel.as_posix()} to {destination_rel.as_posix()}",
+            },
+            paths=[source_rel.as_posix(), destination_rel.as_posix()],
+        )
 
     if name == "create_request":
         title = str(args.get("title") or "").strip()
@@ -969,11 +1189,48 @@ def make_http_handler(repo_root: Path, *, bearer_token: str | None = None) -> ty
             self.end_headers()
             self.wfile.write(encoded)
 
+        def _authorized(self) -> bool:
+            if not bearer_token:
+                return True
+            expected = f"Bearer {bearer_token}"
+            actual = self.headers.get("Authorization", "")
+            if secrets.compare_digest(actual, expected):
+                return True
+            self.send_response(401)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("WWW-Authenticate", 'Bearer realm="logics-mcp"')
+            encoded = json.dumps({"ok": False, "error": "unauthorized", "message": "Missing or invalid bearer token."}, separators=(",", ":")).encode("utf-8")
+            self.send_header("Content-Length", str(len(encoded)))
+            self.end_headers()
+            self.wfile.write(encoded)
+            return False
+
+        def _send_sse_stream(self) -> None:
+            self.send_response(200)
+            self.send_header("Content-Type", "text/event-stream")
+            self.send_header("Cache-Control", "no-cache")
+            self.send_header("Connection", "keep-alive")
+            self.end_headers()
+            self.wfile.write(b": logics-manager-mcp ready\n\n")
+            self.wfile.flush()
+            while True:
+                time.sleep(15)
+                self.wfile.write(b": keepalive\n\n")
+                self.wfile.flush()
+
         def do_GET(self) -> None:
             parsed = urlparse(self.path)
             if parsed.path == "/health":
                 self._send_json(200, {"ok": True, "server": "logics-manager-mcp", "version": _server_version()})
                 return
+            if parsed.path == "/mcp":
+                if not self._authorized():
+                    return
+                try:
+                    self._send_sse_stream()
+                except (BrokenPipeError, ConnectionResetError):
+                    return
+                return
             self._send_json(404, {"ok": False, "error": "not_found", "message": "Use POST /mcp for JSON-RPC."})
 
         def do_POST(self) -> None:
@@ -981,18 +1238,8 @@ def make_http_handler(repo_root: Path, *, bearer_token: str | None = None) -> ty
             if parsed.path != "/mcp":
                 self._send_json(404, {"ok": False, "error": "not_found", "message": "Use POST /mcp for JSON-RPC."})
                 return
-            if bearer_token:
-                expected = f"Bearer {bearer_token}"
-                actual = self.headers.get("Authorization", "")
-                if not secrets.compare_digest(actual, expected):
-                    self.send_response(401)
-                    self.send_header("Content-Type", "application/json")
-                    self.send_header("WWW-Authenticate", 'Bearer realm="logics-mcp"')
-                    encoded = json.dumps({"ok": False, "error": "unauthorized", "message": "Missing or invalid bearer token."}, separators=(",", ":")).encode("utf-8")
-                    self.send_header("Content-Length", str(len(encoded)))
-                    self.end_headers()
-                    self.wfile.write(encoded)
-                    return
+            if not self._authorized():
+                return
             try:
                 length = int(self.headers.get("Content-Length", "0"))
             except ValueError:
@@ -1051,17 +1298,29 @@ def _connector_urls(public_url: str | None) -> dict[str, str]:
     return {"public_url": base, "mcp_url": mcp_url, "health_url": health_url}
 
 
-def connector_plan(*, repo_root: Path, host: str, port: int, bearer_token: str | None = None, public_url: str | None = None) -> dict[str, Any]:
-    token = bearer_token or secrets.token_urlsafe(32)
+def connector_plan(*, repo_root: Path, host: str, port: int, bearer_token: str | None = None, public_url: str | None = None, no_bearer: bool = False, project_binary: str | None = None) -> dict[str, Any]:
+    token = None if no_bearer else bearer_token or secrets.token_urlsafe(32)
     urls = _connector_urls(public_url)
     local_mcp_url = f"http://{host}:{port}/mcp"
     local_health_url = f"http://{host}:{port}/health"
-    server_command = f'{AUTH_ENV_VAR}="{token}" python3 -m logics_manager mcp serve-http --repo-root {repo_root.as_posix()} --host {host} --port {port}'
+    launcher = project_binary or "python3 -m logics_manager"
+    auth_args = "" if no_bearer else f'{AUTH_ENV_VAR}="{token}" '
+    server_command = f"{auth_args}{launcher} mcp serve-http --repo-root {repo_root.as_posix()} --host {host} --port {port}"
+    auth_header = None if no_bearer else f"Authorization: Bearer {token}"
+    cleanup = [
+        "Stop the HTTPS tunnel process.",
+        "Stop the local mcp serve-http process with Ctrl-C.",
+    ]
+    if token:
+        cleanup.append("Treat the bearer token as expired once the local session is stopped.")
+    else:
+        cleanup.append("Treat the public tunnel URL as exposed until both processes are stopped.")
     return {
         "ok": True,
         "repo_root": repo_root.as_posix(),
         "bearer_token": token,
-        "auth_header": f"Authorization: Bearer {token}",
+        "auth_mode": "none" if no_bearer else "bearer",
+        "auth_header": auth_header,
         "local_mcp_url": local_mcp_url,
         "local_health_url": local_health_url,
         "server_command": server_command,
@@ -1069,23 +1328,20 @@ def connector_plan(*, repo_root: Path, host: str, port: int, bearer_token: str |
         "chatgpt": {
             "developer_mode": True,
             "mcp_url": urls.get("mcp_url", "<your HTTPS tunnel URL>/mcp"),
-            "auth_type": "Bearer token",
+            "auth_type": "None" if no_bearer else "Bearer token",
             "auth_value": token,
         },
         "smoke_checks": {
             "health": urls.get("health_url", f"<your HTTPS tunnel URL>/health"),
             "mcp_tools_list": urls.get("mcp_url", "<your HTTPS tunnel URL>/mcp"),
         },
-        "cleanup": [
-            "Stop the HTTPS tunnel process.",
-            "Stop the local mcp serve-http process with Ctrl-C.",
-            "Treat the bearer token as expired once the local session is stopped.",
-        ],
+        "warnings": ["No-bearer mode is unauthenticated. Use only for short-lived local debugging."] if no_bearer else [],
+        "cleanup": cleanup,
         **urls,
     }
 
 
-def connector_smoke_check(public_url: str, bearer_token: str, *, timeout: float = 5.0) -> dict[str, Any]:
+def connector_smoke_check(public_url: str, bearer_token: str | None = None, *, timeout: float = 5.0) -> dict[str, Any]:
     urls = _connector_urls(public_url)
     health_ok = False
     mcp_ok = False
@@ -1097,7 +1353,10 @@ def connector_smoke_check(public_url: str, bearer_token: str, *, timeout: float
         errors.append(f"health: {exc}")
     try:
         body = json.dumps({"jsonrpc": JSONRPC_VERSION, "id": 1, "method": "tools/list", "params": {}}).encode("utf-8")
-        request = Request(urls["mcp_url"], data=body, headers={"Content-Type": "application/json", "Authorization": f"Bearer {bearer_token}"}, method="POST")
+        headers = {"Content-Type": "application/json"}
+        if bearer_token:
+            headers["Authorization"] = f"Bearer {bearer_token}"
+        request = Request(urls["mcp_url"], data=body, headers=headers, method="POST")
         with urlopen(request, timeout=timeout) as response:
             payload = json.loads(response.read().decode("utf-8"))
             mcp_ok = response.status == 200 and "result" in payload
@@ -1108,10 +1367,13 @@ def connector_smoke_check(public_url: str, bearer_token: str, *, timeout: float
 
 def _print_connector_plan(plan: dict[str, Any]) -> None:
     print("Logics MCP Connector")
+    for warning in plan.get("warnings", []):
+        print(f"WARNING: {warning}")
     print(f"Server command:\n  {plan['server_command']}")
     print(f"Tunnel target: {plan['tunnel_target']}")
     print(f"ChatGPT developer-mode MCP URL: {plan['chatgpt']['mcp_url']}")
-    print(f"Authorization header: {plan['auth_header']}")
+    print(f"Auth mode: {plan['auth_mode']}")
+    print(f"Authorization header: {plan['auth_header'] or '(none)'}")
     print("Smoke checks:")
     print(f"  health: {plan['smoke_checks']['health']}")
     print(f"  mcp tools/list: {plan['smoke_checks']['mcp_tools_list']}")
@@ -1120,6 +1382,88 @@ def _print_connector_plan(plan: dict[str, Any]) -> None:
         print(f"  - {item}")
 
 
+def _project_binary_path(repo_root: Path) -> str:
+    candidate = repo_root / "scripts" / "npm" / "logics-manager.mjs"
+    if candidate.is_file():
+        return f"node {candidate.as_posix()}"
+    return "python3 -m logics_manager"
+
+
+def _terminate_process(process: subprocess.Popen[str]) -> None:
+    if process.poll() is not None:
+        return
+    process.terminate()
+    try:
+        process.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        process.kill()
+
+
+def launch_tunnel(
+    *,
+    repo_root: Path,
+    host: str,
+    port: int,
+    bearer_token: str | None = None,
+    no_bearer: bool = False,
+    tunnel_command: list[str] | None = None,
+) -> int:
+    token = None if no_bearer else bearer_token or secrets.token_urlsafe(32)
+    server_command = [sys.executable, "-m", "logics_manager", "mcp", "serve-http", "--repo-root", repo_root.as_posix(), "--host", host, "--port", str(port)]
+    env = os.environ.copy()
+    if token:
+        env[AUTH_ENV_VAR] = token
+    tunnel_command = tunnel_command or ["npx", "localtunnel", "--port", str(port)]
+    server = subprocess.Popen(server_command, cwd=repo_root, env=env, text=True)
+    tunnel: subprocess.Popen[str] | None = None
+    previous_sigint = signal.getsignal(signal.SIGINT)
+    previous_sigterm = signal.getsignal(signal.SIGTERM)
+
+    def stop(_signum: int | None = None, _frame: Any | None = None) -> None:
+        if tunnel is not None:
+            _terminate_process(tunnel)
+        _terminate_process(server)
+
+    signal.signal(signal.SIGINT, stop)
+    signal.signal(signal.SIGTERM, stop)
+    try:
+        time.sleep(0.8)
+        if server.poll() is not None:
+            return server.returncode or 1
+        tunnel = subprocess.Popen(tunnel_command, cwd=repo_root, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
+        public_url = None
+        start = time.monotonic()
+        while time.monotonic() - start < 30:
+            if tunnel.poll() is not None:
+                return tunnel.returncode or 1
+            line = tunnel.stdout.readline() if tunnel.stdout else ""
+            if not line:
+                time.sleep(0.1)
+                continue
+            print(line.rstrip())
+            match = re.search(r"https://\S+", line)
+            if match:
+                public_url = match.group(0).rstrip("/")
+                break
+        if not public_url:
+            raise McpToolError("command_failed", "Tunnel command did not print a public HTTPS URL within 30 seconds.", details={"command": tunnel_command})
+        plan = connector_plan(repo_root=repo_root, host=host, port=port, bearer_token=token, public_url=public_url, no_bearer=no_bearer, project_binary=_project_binary_path(repo_root))
+        _print_connector_plan(plan)
+        print("Processes are running. Press Ctrl-C to stop server and tunnel.")
+        while True:
+            if server.poll() is not None:
+                return server.returncode or 1
+            if tunnel.poll() is not None:
+                return tunnel.returncode or 1
+            time.sleep(1)
+    except KeyboardInterrupt:
+        return 130
+    finally:
+        stop()
+        signal.signal(signal.SIGINT, previous_sigint)
+        signal.signal(signal.SIGTERM, previous_sigterm)
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="logics-manager mcp", description="Run or inspect the Logics MCP server.")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -1141,9 +1485,16 @@ def main(argv: list[str] | None = None) -> int:
     connect.add_argument("--host", default="127.0.0.1")
     connect.add_argument("--port", type=int, default=8765)
     connect.add_argument("--bearer-token", default=None)
+    connect.add_argument("--no-bearer", action="store_true", help="Print a no-auth connector plan for short-lived local debugging.")
     connect.add_argument("--public-url", default=None, help="Optional HTTPS tunnel URL used for copyable ChatGPT setup and smoke checks.")
     connect.add_argument("--check", action="store_true", help="Run /health and authenticated /mcp smoke checks against --public-url.")
     connect.add_argument("--format", choices=("text", "json"), default="text")
+    tunnel = sub.add_parser("tunnel", help="Start the local MCP HTTP server plus an HTTPS localtunnel session.")
+    tunnel.add_argument("--repo-root", default=None)
+    tunnel.add_argument("--host", default="127.0.0.1")
+    tunnel.add_argument("--port", type=int, default=8765)
+    tunnel.add_argument("--bearer-token", default=None)
+    tunnel.add_argument("--no-bearer", action="store_true", help="Run without bearer auth for short-lived local debugging.")
     parsed = parser.parse_args(argv)
 
     if parsed.command == "tools":
@@ -1170,11 +1521,13 @@ def main(argv: list[str] | None = None) -> int:
         return 0
     if parsed.command == "connect":
         root = _repo_root(Path(parsed.repo_root) if parsed.repo_root else None)
-        plan = connector_plan(repo_root=root, host=parsed.host, port=parsed.port, bearer_token=parsed.bearer_token, public_url=parsed.public_url)
+        if parsed.no_bearer and parsed.bearer_token:
+            raise SystemExit("--no-bearer cannot be combined with --bearer-token.")
+        plan = connector_plan(repo_root=root, host=parsed.host, port=parsed.port, bearer_token=parsed.bearer_token, public_url=parsed.public_url, no_bearer=parsed.no_bearer, project_binary=_project_binary_path(root))
         if parsed.check:
             if not parsed.public_url:
                 raise SystemExit("--check requires --public-url.")
-            plan["check"] = connector_smoke_check(parsed.public_url, str(plan["bearer_token"]))
+            plan["check"] = connector_smoke_check(parsed.public_url, str(plan["bearer_token"]) if plan["bearer_token"] else None)
             plan["ok"] = bool(plan["check"]["ok"])
         if parsed.format == "json":
             print(json.dumps(plan, indent=2, sort_keys=True))
@@ -1185,4 +1538,9 @@ def main(argv: list[str] | None = None) -> int:
                 for error in plan["check"]["errors"]:
                     print(f"  - {error}")
         return 0 if plan["ok"] else 1
+    if parsed.command == "tunnel":
+        if parsed.no_bearer and parsed.bearer_token:
+            raise SystemExit("--no-bearer cannot be combined with --bearer-token.")
+        root = _repo_root(Path(parsed.repo_root) if parsed.repo_root else None)
+        return launch_tunnel(repo_root=root, host=parsed.host, port=parsed.port, bearer_token=parsed.bearer_token, no_bearer=parsed.no_bearer)
     return 1

package/logics_manager/path_utils.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def ensure_relative_to(path: Path, root: Path, *, label: str = "path") -> Path:
+    try:
+        return path.resolve().relative_to(root.resolve())
+    except ValueError as exc:
+        raise SystemExit(f"Unsupported {label}: `{path}` is outside the repository.") from exc
+
+
+def resolve_repo_output_path(repo_root: Path, raw_path: str, *, label: str = "--out") -> tuple[Path, str]:
+    candidate = Path(raw_path)
+    if candidate.is_absolute() or any(part == ".." for part in candidate.parts):
+        raise SystemExit(f"Unsupported {label} path `{raw_path}`. Use a repo-relative path inside the repository.")
+    resolved = (repo_root / candidate).resolve()
+    relative = ensure_relative_to(resolved, repo_root, label=label)
+    return resolved, relative.as_posix()
+
+
+def resolve_repo_config_path(repo_root: Path, raw_path: str, *, label: str = "configured path") -> tuple[Path, str]:
+    candidate = Path(raw_path)
+    if any(part == ".." for part in candidate.parts):
+        raise SystemExit(f"Unsupported {label} path `{raw_path}`. Use a repo-relative path or absolute path inside the repository.")
+    resolved = candidate.resolve() if candidate.is_absolute() else (repo_root / candidate).resolve()
+    try:
+        relative = ensure_relative_to(resolved, repo_root, label=label)
+    except SystemExit as exc:
+        raise SystemExit(f"Unsupported {label} path `{raw_path}`. Use a repo-relative path or absolute path inside the repository.") from exc
+    return resolved, relative.as_posix()