unlegacy-cli 0.1.0__py3-none-any.whl

unlegacy_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Unlegacy CLI package."""
+
+__version__ = "0.1.0"

unlegacy_cli/__main__.py

@@ -0,0 +1,5 @@
+from unlegacy_cli.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

unlegacy_cli/adapters/client_configs.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+
+from unlegacy_cli.domain.models import ClientId, McpServerConfig
+
+
+def _json_object(existing: str) -> dict[str, object]:
+    if not existing.strip():
+        return {}
+    try:
+        parsed = json.loads(existing)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"existing JSON config is invalid: {exc}") from exc
+    if not isinstance(parsed, dict):
+        raise ValueError("existing JSON config must be an object")
+    return parsed
+
+
+def _dump_json(data: dict[str, object]) -> str:
+    return json.dumps(data, indent=2, sort_keys=True) + "\n"
+
+
+def _merge_mcp_servers(existing: str, config: McpServerConfig, *, key: str, include_type: bool) -> str:
+    data = _json_object(existing)
+    servers = data.setdefault(key, {})
+    if not isinstance(servers, dict):
+        raise ValueError(f"existing {key} must be an object")
+    server: dict[str, object] = {
+        "url": config.normalized_endpoint(),
+        "headers": {"Authorization": config.authorization_header()},
+    }
+    if include_type:
+        server["type"] = "http"
+    servers["unlegacy"] = server
+    return _dump_json(data)
+
+
+def build_claude_mcp_json(existing: str, config: McpServerConfig) -> str:
+    return _merge_mcp_servers(existing, config, key="mcpServers", include_type=True)
+
+
+def build_cursor_mcp_json(existing: str, config: McpServerConfig) -> str:
+    return _merge_mcp_servers(existing, config, key="mcpServers", include_type=False)
+
+
+def build_vscode_mcp_json(existing: str, config: McpServerConfig) -> str:
+    return _merge_mcp_servers(existing, config, key="servers", include_type=True)
+
+
+def build_opencode_mcp_json(existing: str, config: McpServerConfig) -> str:
+    return _merge_mcp_servers(existing, config, key="mcpServers", include_type=True)
+
+
+def _toml_quote(value: str) -> str:
+    return json.dumps(value)
+
+
+def _codex_unlegacy_block(config: McpServerConfig) -> str:
+    auth = f"Bearer {config.token}"
+    return (
+        "[mcp_servers.unlegacy]\n"
+        f"url = {_toml_quote(config.normalized_endpoint())}\n"
+        f"http_headers = {{ Authorization = {_toml_quote(auth)} }}\n"
+        "startup_timeout_sec = 20\n"
+        "tool_timeout_sec = 60\n"
+        "enabled = true\n"
+    )
+
+
+def build_codex_config_toml(existing: str, config: McpServerConfig) -> str:
+    cleaned = re.sub(
+        r"(?ms)^# BEGIN UNLEGACY MCP\n.*?^# END UNLEGACY MCP\n?",
+        "",
+        existing,
+    )
+    cleaned = re.sub(
+        r"(?ms)^\[mcp_servers\.unlegacy\]\n(?:(?!^\[).*\n?)*",
+        "",
+        cleaned,
+    )
+    prefix = cleaned.rstrip()
+    block = f"# BEGIN UNLEGACY MCP\n{_codex_unlegacy_block(config)}# END UNLEGACY MCP\n"
+    return f"{prefix}\n\n{block}" if prefix else block
+
+
+def read_text(path: Path) -> str:
+    if not path.exists():
+        return ""
+    return path.read_text(encoding="utf-8")
+
+
+def atomic_write(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temp = path.with_suffix(f"{path.suffix}.tmp")
+    temp.write_text(content, encoding="utf-8")
+    os.replace(temp, path)
+
+
+class FileSystemClientConfigStore:
+    def __init__(self, *, home: Path | None = None, project_dir: Path | None = None) -> None:
+        self._home = home or Path.home()
+        self._project_dir = project_dir or Path.cwd()
+
+    def configure(self, client: ClientId, config: McpServerConfig, *, dry_run: bool) -> str:
+        path, builder = self._target(client)
+        existing = read_text(path)
+        content = builder(existing, config)
+        if not dry_run:
+            if path.exists():
+                backup = path.with_suffix(f"{path.suffix}.bak")
+                backup.write_text(existing, encoding="utf-8")
+            atomic_write(path, content)
+        action = "would write" if dry_run else "wrote"
+        return f"{client.label}: {action} {path}. {reload_instruction(client)}"
+
+    def has_config(self, client: ClientId, config: McpServerConfig) -> bool:
+        path, _ = self._target(client)
+        existing = read_text(path)
+        if not existing:
+            return False
+        marker = config.normalized_endpoint()
+        return "unlegacy" in existing and marker in existing
+
+    def _target(self, client: ClientId):
+        if client == ClientId.CLAUDE_CODE:
+            return self._project_dir / ".mcp.json", build_claude_mcp_json
+        if client == ClientId.CODEX:
+            return self._home / ".codex" / "config.toml", build_codex_config_toml
+        if client == ClientId.CURSOR:
+            return self._project_dir / ".cursor" / "mcp.json", build_cursor_mcp_json
+        if client == ClientId.VSCODE_COPILOT:
+            return self._project_dir / ".vscode" / "mcp.json", build_vscode_mcp_json
+        if client == ClientId.OPENCODE:
+            return self._project_dir / ".opencode" / "mcp.json", build_opencode_mcp_json
+        raise ValueError(f"unsupported client: {client}")
+
+
+def reload_instruction(client: ClientId) -> str:
+    if client == ClientId.CLAUDE_CODE:
+        return "Restart Claude Code to load the MCP server."
+    if client == ClientId.CODEX:
+        return "Restart Codex or open a new Codex session, then use /mcp to inspect the server."
+    if client == ClientId.CURSOR:
+        return "Reload the Cursor window to activate the MCP server."
+    if client == ClientId.VSCODE_COPILOT:
+        return "Reload VS Code or restart the Extension Host to activate the MCP server."
+    if client == ClientId.OPENCODE:
+        return "Restart OpenCode to activate the MCP server."
+    return "Restart the client to activate the MCP server."

unlegacy_cli/adapters/mcp_http.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import itertools
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+from unlegacy_cli.domain.models import McpServerConfig
+
+PROTOCOL_VERSION = "2025-06-18"
+
+
+class HttpMcpGateway:
+    def __init__(self, *, timeout_seconds: float = 20.0) -> None:
+        self._timeout_seconds = timeout_seconds
+
+    def validate(self, config: McpServerConfig) -> None:
+        self.list_tools(config)
+
+    def list_tools(self, config: McpServerConfig) -> list[str]:
+        session = _JsonRpcSession(config, timeout_seconds=self._timeout_seconds)
+        init = session.request(
+            "initialize",
+            {
+                "protocolVersion": PROTOCOL_VERSION,
+                "capabilities": {"tools": {}},
+                "clientInfo": {"name": "unlegacy-cli", "version": "0.1.0"},
+            },
+        )
+        server_version = init.get("protocolVersion")
+        if server_version != PROTOCOL_VERSION:
+            raise ValueError(
+                f"MCP protocol mismatch: server speaks {server_version!r}, CLI speaks {PROTOCOL_VERSION!r}"
+            )
+        session.notify("notifications/initialized", {})
+        result = session.request("tools/list", {})
+        tools = result.get("tools", [])
+        if not isinstance(tools, list):
+            raise ValueError("MCP tools/list returned an invalid response")
+        return [str(tool.get("name")) for tool in tools if isinstance(tool, dict)]
+
+    def list_repos(self, config: McpServerConfig) -> list[dict[str, object]]:
+        session = _JsonRpcSession(config, timeout_seconds=self._timeout_seconds)
+        session.request(
+            "initialize",
+            {
+                "protocolVersion": PROTOCOL_VERSION,
+                "capabilities": {"tools": {}},
+                "clientInfo": {"name": "unlegacy-cli", "version": "0.1.0"},
+            },
+        )
+        session.notify("notifications/initialized", {})
+        result = session.request("tools/call", {"name": "list_repos", "arguments": {}})
+        text = _tool_text(result)
+        try:
+            rows = json.loads(text)
+        except json.JSONDecodeError:
+            return []
+        return rows if isinstance(rows, list) else []
+
+
+class _JsonRpcSession:
+    def __init__(self, config: McpServerConfig, *, timeout_seconds: float) -> None:
+        self._config = config
+        self._timeout_seconds = timeout_seconds
+        self._ids = itertools.count(1)
+        self._session_id: str | None = None
+
+    def request(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
+        rid = next(self._ids)
+        body = {"jsonrpc": "2.0", "id": rid, "method": method, "params": params}
+        response = self._post(body)
+        if "error" in response:
+            error = response["error"]
+            if isinstance(error, dict):
+                raise ValueError(f"{method}: {error.get('message', 'MCP error')}")
+            raise ValueError(f"{method}: MCP error")
+        result = response.get("result", {})
+        return result if isinstance(result, dict) else {}
+
+    def notify(self, method: str, params: dict[str, Any]) -> None:
+        self._post({"jsonrpc": "2.0", "method": method, "params": params}, expect_response=False)
+
+    def _post(self, body: dict[str, Any], *, expect_response: bool = True) -> dict[str, Any]:
+        headers = {
+            "Accept": "application/json, text/event-stream",
+            "Content-Type": "application/json",
+            "Authorization": self._config.authorization_header(),
+        }
+        if self._session_id:
+            headers["Mcp-Session-Id"] = self._session_id
+        request = urllib.request.Request(
+            self._config.normalized_endpoint(),
+            data=json.dumps(body).encode("utf-8"),
+            headers=headers,
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self._timeout_seconds) as response:
+                self._session_id = response.headers.get("Mcp-Session-Id") or self._session_id
+                payload = response.read().decode("utf-8")
+                content_type = response.headers.get("content-type", "")
+        except urllib.error.HTTPError as exc:
+            if exc.code == 401:
+                raise ValueError("invalid or expired MCP token") from exc
+            raise ValueError(f"MCP request failed with HTTP {exc.code}") from exc
+        except urllib.error.URLError as exc:
+            raise ValueError(f"MCP server is unreachable: {exc.reason}") from exc
+        if not expect_response or not payload.strip():
+            return {}
+        return _decode_payload(payload, content_type)
+
+
+def _decode_payload(payload: str, content_type: str) -> dict[str, Any]:
+    if "text/event-stream" in content_type:
+        for line in payload.splitlines():
+            if line.startswith("data:"):
+                data = line.removeprefix("data:").strip()
+                if data:
+                    parsed = json.loads(data)
+                    return parsed if isinstance(parsed, dict) else {}
+        return {}
+    parsed = json.loads(payload)
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _tool_text(result: dict[str, Any]) -> str:
+    parts = result.get("content", [])
+    if not isinstance(parts, list):
+        return ""
+    return "\n".join(
+        str(part.get("text", ""))
+        for part in parts
+        if isinstance(part, dict) and part.get("type") == "text"
+    )

unlegacy_cli/adapters/skills.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import re
+import shutil
+from importlib import resources
+from pathlib import Path
+
+from unlegacy_cli.domain.models import ClientId, SkillPackage
+
+
+class PackagedSkillRepository:
+    def load(self) -> SkillPackage:
+        resource = resources.files("unlegacy_cli").joinpath("assets/skills/unlegacy/SKILL.md")
+        content = resource.read_text(encoding="utf-8")
+        name = _frontmatter_value(content, "name")
+        version = _frontmatter_value(content, "version")
+        for required in ["list_repos", "repo_info", "read_doc", "Do not guess"]:
+            if required.lower() not in content.lower():
+                raise ValueError(f"packaged skill missing required guidance: {required}")
+        return SkillPackage(name=name, version=version, content=content)
+
+
+def _frontmatter_value(content: str, key: str) -> str:
+    match = re.search(rf"^{re.escape(key)}:\s*(.+)$", content, re.MULTILINE)
+    if not match:
+        raise ValueError(f"packaged skill missing {key} frontmatter")
+    return match.group(1).strip().strip("\"'")
+
+
+class FileSystemSkillInstaller:
+    def __init__(self, *, repository: PackagedSkillRepository | None = None, home: Path | None = None) -> None:
+        self._repository = repository or PackagedSkillRepository()
+        self._home = home or Path.home()
+
+    def install(self, client: ClientId, *, dry_run: bool) -> str:
+        skill = self._repository.load()
+        target = self._target(client, skill.name)
+        if not dry_run:
+            target.mkdir(parents=True, exist_ok=True)
+            (target / "SKILL.md").write_text(skill.content, encoding="utf-8")
+        return f"{client.label}: {'would install' if dry_run else 'installed'} skill {skill.name}@{skill.version} to {target}"
+
+    def is_installed(self, client: ClientId) -> bool:
+        skill = self._repository.load()
+        path = self._target(client, skill.name) / "SKILL.md"
+        if not path.exists():
+            return False
+        try:
+            content = path.read_text(encoding="utf-8")
+        except OSError:
+            return False
+        return f"version: {skill.version}" in content and "name: unlegacy" in content
+
+    def version(self) -> str:
+        return self._repository.load().version
+
+    def _target(self, client: ClientId, name: str) -> Path:
+        if client == ClientId.CLAUDE_CODE:
+            return self._home / ".claude" / "skills" / name
+        if client == ClientId.CODEX:
+            return self._home / ".codex" / "skills" / name
+        if client == ClientId.CURSOR:
+            return self._home / ".cursor" / "skills" / name
+        if client == ClientId.VSCODE_COPILOT:
+            return self._home / ".vscode" / "extensions" / "unlegacy" / "skills" / name
+        if client == ClientId.OPENCODE:
+            return self._home / ".config" / "opencode" / "skills" / name
+        raise ValueError(f"unsupported client: {client}")
+
+
+def copy_packaged_skill_to(path: Path) -> None:
+    resource_dir = resources.files("unlegacy_cli").joinpath("assets/skills/unlegacy")
+    if path.exists():
+        shutil.rmtree(path)
+    path.mkdir(parents=True)
+    for item in resource_dir.iterdir():
+        if item.is_file():
+            (path / item.name).write_text(item.read_text(encoding="utf-8"), encoding="utf-8")

unlegacy_cli/application/setup.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from unlegacy_cli.domain.models import (
+    ClientId,
+    DoctorReport,
+    McpServerConfig,
+    SetupResult,
+    mask_token,
+)
+from unlegacy_cli.domain.ports import ClientConfigStore, McpGateway, SkillInstaller
+
+REQUIRED_TOOLS = {"list_repos"}
+
+
+@dataclass(frozen=True)
+class SetupCommand:
+    token: str
+    endpoint: str
+    clients: list[ClientId]
+    dry_run: bool = False
+
+
+@dataclass(frozen=True)
+class DoctorCommand:
+    token: str | None
+    endpoint: str
+    clients: list[ClientId]
+
+
+class DoctorService:
+    def __init__(
+        self,
+        *,
+        mcp_gateway: McpGateway,
+        client_configs: ClientConfigStore,
+        skills: SkillInstaller,
+    ) -> None:
+        self._mcp_gateway = mcp_gateway
+        self._client_configs = client_configs
+        self._skills = skills
+
+    def run(self, command: DoctorCommand) -> DoctorReport:
+        token = (command.token or "").strip()
+        if not token:
+            return DoctorReport(
+                ok=False,
+                token_present=False,
+                mcp_initialized=False,
+                required_tools_present=False,
+                repo_count=0,
+                message="missing MCP token; pass --token or set UNLEGACY_MCP_TOKEN",
+            )
+
+        config = McpServerConfig(endpoint=command.endpoint, token=token)
+        try:
+            tools = set(self._mcp_gateway.list_tools(config))
+            repos = self._mcp_gateway.list_repos(config)
+        except ValueError as exc:
+            return DoctorReport(
+                ok=False,
+                token_present=True,
+                mcp_initialized=False,
+                required_tools_present=False,
+                repo_count=0,
+                message=str(exc),
+            )
+
+        missing_tools = REQUIRED_TOOLS - tools
+        configured = [
+            client for client in command.clients if self._client_configs.has_config(client, config)
+        ]
+        missing_config = [client for client in command.clients if client not in configured]
+        missing_skill = [
+            client for client in command.clients if not self._skills.is_installed(client)
+        ]
+        ok = not missing_tools and not missing_config and not missing_skill
+        message = "Unlegacy MCP is ready" if ok else "Unlegacy setup needs attention"
+        return DoctorReport(
+            ok=ok,
+            token_present=True,
+            mcp_initialized=True,
+            required_tools_present=not missing_tools,
+            repo_count=len(repos),
+            configured_clients=configured,
+            missing_config_clients=missing_config,
+            missing_skill_clients=missing_skill,
+            message=message,
+        )
+
+
+class SetupService:
+    def __init__(
+        self,
+        *,
+        mcp_gateway: McpGateway,
+        client_configs: ClientConfigStore,
+        skills: SkillInstaller,
+    ) -> None:
+        self._mcp_gateway = mcp_gateway
+        self._client_configs = client_configs
+        self._skills = skills
+        self._doctor = DoctorService(
+            mcp_gateway=mcp_gateway,
+            client_configs=client_configs,
+            skills=skills,
+        )
+
+    def setup(self, command: SetupCommand) -> SetupResult:
+        config = McpServerConfig(endpoint=command.endpoint, token=command.token.strip())
+        masked = mask_token(config.token)
+        try:
+            self._mcp_gateway.validate(config)
+        except ValueError as exc:
+            return SetupResult(
+                ok=False,
+                config=config,
+                masked_token=masked,
+                skill_version=self._skills.version(),
+                configured_clients=[],
+                config_messages=[],
+                skill_messages=[],
+                doctor=DoctorReport(
+                    ok=False,
+                    token_present=bool(config.token),
+                    mcp_initialized=False,
+                    required_tools_present=False,
+                    repo_count=0,
+                    message=str(exc),
+                ),
+                message=f"Setup stopped: {exc}",
+            )
+
+        config_messages: list[str] = []
+        skill_messages: list[str] = []
+        configured_clients: list[ClientId] = []
+        for client in command.clients:
+            config_messages.append(
+                self._client_configs.configure(client, config, dry_run=command.dry_run)
+            )
+            skill_messages.append(self._skills.install(client, dry_run=command.dry_run))
+            configured_clients.append(client)
+
+        doctor = self._doctor.run(
+            DoctorCommand(token=config.token, endpoint=config.endpoint, clients=command.clients)
+        )
+        return SetupResult(
+            ok=doctor.ok,
+            config=config,
+            masked_token=masked,
+            skill_version=self._skills.version(),
+            configured_clients=configured_clients,
+            config_messages=config_messages,
+            skill_messages=skill_messages,
+            doctor=doctor,
+            message="Setup complete" if doctor.ok else doctor.message,
+        )

unlegacy_cli/assets/skills/unlegacy/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: unlegacy
+version: 0.1.0
+description: Use Unlegacy MCP before changing or explaining repositories that have platform-generated docs or a knowledge graph.
+---
+
+# Unlegacy
+
+Use this skill when the user asks about a repository, feature, bug, business process, migration, impact analysis, or implementation spec that may be represented in Unlegacy.
+
+Unlegacy is the hosted repo memory layer. The Unlegacy platform already generated documentation and knowledge graph data. The local CLI only connects your coding agent to that MCP surface.
+
+## Default Workflow
+
+1. Call `list_repos` first unless the user gave an exact repo id or full name.
+2. Choose the most likely repository by name and description. If there is ambiguity, say which repos are plausible and ask a short question.
+3. Call `repo_info` for the selected repo to understand indexed status and recommended context.
+4. Prefer generated docs before source when the question is about behavior, architecture, onboarding, business rules, or implementation intent.
+5. Use `read_doc` when you know the doc path. If docs discovery tools are unavailable, use `repo_info` and code/search evidence to identify likely docs.
+6. Use `search`, `symbol_context`, `impact`, `cypher`, and `get_code` when you need graph or source verification.
+7. Do not guess. If Unlegacy lacks docs, KG data, or source evidence for a claim, say what is missing and verify through the repository.
+
+## Answer Pattern
+
+For explanations:
+- Start with the direct answer.
+- Cite the repo, docs path, symbols, or files that support it.
+- Separate confirmed facts from inference.
+
+For implementation specs:
+- State the target repo and why it was selected.
+- Summarize the relevant docs and KG/source evidence.
+- List implementation slices, affected files/modules, risks, and verification commands.
+- Include open questions only when the evidence is genuinely insufficient.
+
+## Tool Guidance
+
+- `list_repos`: discover available repositories and pick the right one.
+- `repo_info`: get a compact summary of the selected repository and indexed version.
+- `read_doc`: read generated documentation by path.
+- `search`: find code graph nodes related to a query.
+- `symbol_context`: inspect a symbol neighborhood.
+- `impact`: inspect likely blast radius before changing code.
+- `get_code`: read source only after selecting a repo and path.

unlegacy_cli/cli.py

@@ -0,0 +1,404 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from unlegacy_cli.adapters.client_configs import FileSystemClientConfigStore
+from unlegacy_cli.adapters.mcp_http import HttpMcpGateway
+from unlegacy_cli.adapters.skills import FileSystemSkillInstaller
+from unlegacy_cli.application.setup import DoctorCommand, DoctorService, SetupCommand, SetupService
+from unlegacy_cli.domain.models import ClientId, SUPPORTED_CLIENTS
+
+DEFAULT_ENDPOINT = "https://app.unlegacy.ai/ai/mcp"
+LOCAL_ENDPOINT = "http://localhost:5173/ai/mcp"
+
+RESET = "\033[0m"
+DIM = "\033[2m"
+CYAN = "\033[96m"
+MINT = "\033[38;2;145;245;247m"
+TEAL = "\033[36m"
+LIME = "\033[92m"
+YELLOW = "\033[93m"
+CORAL = "\033[91m"
+BOLD = "\033[1m"
+
+LOGO_PIXEL_MAP = [
+    "...........lllllllllllyyy......",
+    "..........llllllllllllllyy.yyyy",
+    ".........llllllllllllllllly.yyy",
+    "........llllllllllllllllllly.yy",
+    "........lllccccccccclllllllly..",
+    "........lcccccccccccccllllllly.",
+    "........cccccccccccccccllllllyy",
+    "........ccccccccc.....cclllllly",
+    "..lll...cccccccc.cccc..ccllllly",
+    ".llllc..cccccmm.mmcccc..cclllll",
+    "lllllcc.ccccmmm.mmmcccc.cclllll",
+    "llllccc.cccmmmm.mmmmccc.cccllll",
+    "llllccc.ccmmmmm.mmmmmcc.cccllll",
+    "llllccc.cmmmmmm.mmmmmmc.cccllll",
+    "llllccc.cmmmmmm.mmmmmmc.cccllll",
+    "llllccc.cmmmmmm.mmmmmmc.cccllll",
+    "llllccc.cmmmmmm.mmmmmmc.cccllll",
+    "llllccc.cmmmmmm.mmmmmmc.cccllll",
+    "llllccc.ccmmmmm.mmmmmcc.cccllll",
+    "llllccc.cccmmmm.mmmmccc.cccllll",
+    "lllllcc..cccmmm.mmmcccc.cclllll",
+    "lllllcc..ccccm..mmccccc..cllll.",
+    "ylllllcc.......cccccccc...lll..",
+    "yllllllcc.....ccccccccc........",
+    ".yllllllccccccccccccccc........",
+    ".ylllllllcccccccccccccl........",
+    "..yllllllllccccccccclll........",
+    "....llllllllllllllllll.........",
+    ".....lllllllllllllllll.........",
+    "......yllllllllllllll..........",
+    ".......yyllllllllll............",
+]
+
+LOGO_PIXEL_COLORS = {
+    "c": CYAN,
+    "m": MINT,
+    "l": LIME,
+    "y": YELLOW,
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 0
+    try:
+        return int(args.func(args))
+    except KeyboardInterrupt:
+        print("\nCanceled.")
+        return 130
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="unlegacy", description="Connect coding agents to Unlegacy MCP.")
+    sub = parser.add_subparsers(dest="command")
+
+    setup = sub.add_parser(
+        "setup",
+        usage="unlegacy setup [--token TOKEN] [--client CLIENT] [--endpoint URL]",
+        help="Configure MCP and install the Unlegacy skill.",
+    )
+    add_common_options(setup)
+    setup.add_argument("--dry-run", action="store_true", help="Print planned writes without changing files.")
+    setup.set_defaults(func=run_setup)
+
+    doctor = sub.add_parser("doctor", help="Validate token, MCP tools, config, and skills.")
+    add_common_options(doctor, token_required=False)
+    doctor.set_defaults(func=run_doctor)
+
+    install_skills = sub.add_parser("install-skills", help="Install only the packaged Unlegacy skill.")
+    install_skills.add_argument(
+        "--client",
+        action="append",
+        choices=[c.value for c in SUPPORTED_CLIENTS] + ["all"],
+        help="Client to install into. Repeat or use all.",
+    )
+    install_skills.add_argument("--dry-run", action="store_true", help="Print planned writes without changing files.")
+    install_skills.set_defaults(func=run_install_skills)
+
+    status = sub.add_parser("status", help="Show local Unlegacy CLI setup targets.")
+    status.set_defaults(func=run_status)
+    return parser
+
+
+def add_common_options(parser: argparse.ArgumentParser, *, token_required: bool = True) -> None:
+    parser.add_argument("--token", help="Unlegacy MCP token. Defaults to UNLEGACY_MCP_TOKEN.")
+    parser.add_argument(
+        "--endpoint",
+        help=(
+            "Unlegacy MCP endpoint. Defaults to UNLEGACY_MCP_ENDPOINT, "
+            f"or prompts during setup. Production default: {DEFAULT_ENDPOINT}"
+        ),
+    )
+    parser.add_argument(
+        "--client",
+        action="append",
+        choices=[c.value for c in SUPPORTED_CLIENTS] + ["all"],
+        help="Client to configure. Repeat for multiple clients or use all.",
+    )
+    if token_required:
+        parser.epilog = "The setup flow will prompt for the token when --token and UNLEGACY_MCP_TOKEN are absent."
+
+
+def run_setup(args: argparse.Namespace) -> int:
+    color = color_enabled()
+    print(render_title("setup", color=color))
+    print(render_logo(color=color))
+    print(
+        paint("Unlegacy setup", LIME, color)
+        + " connects local coding agents to docs and KG already generated in Unlegacy."
+    )
+    print()
+    token_will_prompt = not (args.token or os.environ.get("UNLEGACY_MCP_TOKEN") or "").strip()
+    endpoint_will_prompt = not (args.endpoint or os.environ.get("UNLEGACY_MCP_ENDPOINT") or "").strip()
+    clients_will_prompt = not args.client and sys.stdin.isatty()
+    token = token_from_args(args, prompt=True)
+    if token_will_prompt:
+        print()
+    endpoint = endpoint_from_args(args, prompt=True)
+    if endpoint_will_prompt:
+        print()
+    clients = clients_from_args(args.client, interactive=True)
+    if clients_will_prompt:
+        print()
+    print()
+    service = _setup_service()
+    result = service.setup(
+        SetupCommand(
+            token=token,
+            endpoint=endpoint,
+            clients=clients,
+            dry_run=bool(args.dry_run),
+        )
+    )
+    print(f"Token: {result.masked_token}")
+    messages = result.config_messages + result.skill_messages
+    if messages:
+        print()
+    for message in messages:
+        print(f"- {message}")
+    print()
+    print_doctor(result.doctor)
+    if result.ok:
+        print()
+        print("Open your agent and ask: 'Using Unlegacy, which repo owns this process and what docs should I read first?'")
+    return 0 if result.ok else 1
+
+
+def run_doctor(args: argparse.Namespace) -> int:
+    token = token_from_args(args, prompt=False)
+    endpoint = endpoint_from_args(args, prompt=False)
+    clients = clients_from_args(args.client, interactive=False)
+    service = _doctor_service()
+    report = service.run(DoctorCommand(token=token, endpoint=endpoint, clients=clients))
+    print_doctor(report)
+    return 0 if report.ok else 1
+
+
+def run_install_skills(args: argparse.Namespace) -> int:
+    clients = clients_from_args(args.client, interactive=False)
+    installer = FileSystemSkillInstaller()
+    for client in clients:
+        print(installer.install(client, dry_run=bool(args.dry_run)))
+    return 0
+
+
+def run_status(args: argparse.Namespace) -> int:
+    del args
+    print("Unlegacy setup targets:")
+    print(f"- Project config directory: {Path.cwd()}")
+    print(f"- User home: {Path.home()}")
+    print("- Supported clients: " + ", ".join(client.value for client in SUPPORTED_CLIENTS))
+    return 0
+
+
+def token_from_args(args: argparse.Namespace, *, prompt: bool) -> str:
+    token = (args.token or os.environ.get("UNLEGACY_MCP_TOKEN") or "").strip()
+    if token or not prompt:
+        return token
+    print("Paste your Unlegacy MCP token from Settings -> MCP tokens.")
+    return input("Unlegacy MCP token: ").strip()
+
+
+def endpoint_from_args(args: argparse.Namespace, *, prompt: bool) -> str:
+    endpoint = (args.endpoint or os.environ.get("UNLEGACY_MCP_ENDPOINT") or "").strip()
+    if endpoint:
+        return endpoint
+    if not prompt:
+        return DEFAULT_ENDPOINT
+    return input(f"Unlegacy MCP endpoint [{LOCAL_ENDPOINT}]: ").strip() or LOCAL_ENDPOINT
+
+
+def clients_from_args(values: list[str] | None, *, interactive: bool) -> list[ClientId]:
+    if values:
+        if "all" in values:
+            return list(SUPPORTED_CLIENTS)
+        return [ClientId(value) for value in values]
+    if not interactive or not sys.stdin.isatty():
+        return [ClientId.CLAUDE_CODE, ClientId.CODEX]
+    return interactive_client_selector(
+        clients=SUPPORTED_CLIENTS,
+        default_selected={ClientId.CLAUDE_CODE, ClientId.CODEX},
+        read_key=read_terminal_key,
+        write=sys.stdout.write,
+        color=color_enabled(),
+        redraw=True,
+    )
+
+
+def print_doctor(report) -> None:
+    status = "PASS" if report.ok else "FAIL"
+    print(f"Doctor: {status} - {report.message}")
+    print(f"- Token present: {'yes' if report.token_present else 'no'}")
+    print(f"- MCP initialized: {'yes' if report.mcp_initialized else 'no'}")
+    print(f"- Required tools present: {'yes' if report.required_tools_present else 'no'}")
+    print(f"- Repositories visible: {report.repo_count}")
+    if report.configured_clients:
+        print("- Configured clients: " + ", ".join(client.label for client in report.configured_clients))
+    if report.missing_config_clients:
+        print("- Missing config: " + ", ".join(client.label for client in report.missing_config_clients))
+    if report.missing_skill_clients:
+        print("- Missing skills: " + ", ".join(client.label for client in report.missing_skill_clients))
+
+
+def color_enabled() -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("UNLEGACY_FORCE_COLOR") or os.environ.get("FORCE_COLOR"):
+        return True
+    return sys.stdout.isatty()
+
+
+def paint(text: str, color_code: str, enabled: bool) -> str:
+    if not enabled:
+        return text
+    return f"{color_code}{text}{RESET}"
+
+
+def render_title(command: str, *, color: bool) -> str:
+    return f"{paint('➜', CORAL, color)}  {paint('unlegacy', LIME, color)} {paint(command, BOLD, color)}"
+
+
+def render_logo(*, color: bool) -> str:
+    mark = render_logo_mark(color=color)
+    wordmark = (
+        f"{paint('UN', CYAN + BOLD, color)}"
+        f"{paint('LEG', LIME + BOLD, color)}"
+        f"{paint('ACY', YELLOW + BOLD, color)}"
+        f" {paint('0.1.0', TEAL, color)}"
+    )
+    return f"\n{mark}\n{wordmark}\n"
+
+
+def render_logo_mark(*, color: bool) -> str:
+    lines: list[str] = []
+    for row in LOGO_PIXEL_MAP:
+        rendered = []
+        for cell in row:
+            if cell == ".":
+                rendered.append("  ")
+            else:
+                rendered.append(paint("◢", LOGO_PIXEL_COLORS[cell], color) + " ")
+        lines.append("".join(rendered).rstrip())
+    return "\n".join(lines)
+
+
+def render_client_selector(
+    clients: list[ClientId],
+    *,
+    cursor: int,
+    selected: set[ClientId],
+    color: bool,
+) -> str:
+    lines = [
+        paint("Select clients to configure:", LIME + BOLD, color),
+        paint("Use ↑/↓ to move, Space to select, Enter to continue.", TEAL, color),
+    ]
+    for index, client in enumerate(clients):
+        pointer = "›" if index == cursor else " "
+        box = "[x]" if client in selected else "[ ]"
+        label = client.label
+        line = f"{pointer} {box} {label}"
+        if index == cursor:
+            line = paint(line, YELLOW + BOLD, color)
+        elif client in selected:
+            line = paint(line, CYAN, color)
+        lines.append(line)
+    return "\n".join(lines)
+
+
+def interactive_client_selector(
+    *,
+    clients: list[ClientId],
+    default_selected: set[ClientId],
+    read_key,
+    write,
+    color: bool,
+    redraw: bool,
+) -> list[ClientId]:
+    cursor = 0
+    selected = set(default_selected)
+    previous_lines = 0
+
+    if redraw:
+        write("\033[?25l")
+    try:
+        while True:
+            rendered = render_client_selector(
+                clients, cursor=cursor, selected=selected, color=color
+            )
+            if redraw and previous_lines:
+                write(f"\033[{previous_lines}F\033[J")
+            write(rendered)
+            write("\n")
+            previous_lines = rendered.count("\n") + 1
+
+            key = read_key()
+            if key == "up":
+                cursor = (cursor - 1) % len(clients)
+            elif key == "down":
+                cursor = (cursor + 1) % len(clients)
+            elif key == " ":
+                client = clients[cursor]
+                if client in selected:
+                    selected.remove(client)
+                else:
+                    selected.add(client)
+            elif key == "enter":
+                if not selected:
+                    selected.add(clients[cursor])
+                return [client for client in clients if client in selected]
+            elif key == "\x03":
+                raise KeyboardInterrupt
+    finally:
+        if redraw:
+            write("\033[?25h")
+
+
+def read_terminal_key() -> str:
+    import termios
+    import tty
+
+    fd = sys.stdin.fileno()
+    old_settings = termios.tcgetattr(fd)
+    try:
+        tty.setraw(fd)
+        char = sys.stdin.read(1)
+        if char == "\x1b":
+            sequence = sys.stdin.read(2)
+            if sequence == "[A":
+                return "up"
+            if sequence == "[B":
+                return "down"
+            return char + sequence
+        if char in {"\r", "\n"}:
+            return "enter"
+        return char
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+
+
+def _setup_service() -> SetupService:
+    return SetupService(
+        mcp_gateway=HttpMcpGateway(),
+        client_configs=FileSystemClientConfigStore(),
+        skills=FileSystemSkillInstaller(),
+    )
+
+
+def _doctor_service() -> DoctorService:
+    return DoctorService(
+        mcp_gateway=HttpMcpGateway(),
+        client_configs=FileSystemClientConfigStore(),
+        skills=FileSystemSkillInstaller(),
+    )

unlegacy_cli/domain/models.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class ClientId(str, Enum):
+    CLAUDE_CODE = "claude-code"
+    CODEX = "codex"
+    CURSOR = "cursor"
+    VSCODE_COPILOT = "vscode-copilot"
+    OPENCODE = "opencode"
+
+    @property
+    def label(self) -> str:
+        return {
+            ClientId.CLAUDE_CODE: "Claude Code",
+            ClientId.CODEX: "Codex",
+            ClientId.CURSOR: "Cursor",
+            ClientId.VSCODE_COPILOT: "VS Code Copilot",
+            ClientId.OPENCODE: "OpenCode",
+        }[self]
+
+
+SUPPORTED_CLIENTS = [
+    ClientId.CLAUDE_CODE,
+    ClientId.CODEX,
+    ClientId.CURSOR,
+    ClientId.VSCODE_COPILOT,
+    ClientId.OPENCODE,
+]
+
+
+@dataclass(frozen=True)
+class McpServerConfig:
+    endpoint: str
+    token: str
+
+    def normalized_endpoint(self) -> str:
+        endpoint = self.endpoint.strip()
+        if endpoint.endswith("/"):
+            return endpoint
+        return f"{endpoint}/"
+
+    def authorization_header(self) -> str:
+        return f"Bearer {self.token}"
+
+
+@dataclass(frozen=True)
+class SkillPackage:
+    name: str
+    version: str
+    content: str
+
+
+@dataclass(frozen=True)
+class DoctorReport:
+    ok: bool
+    token_present: bool
+    mcp_initialized: bool
+    required_tools_present: bool
+    repo_count: int
+    configured_clients: list[ClientId] = field(default_factory=list)
+    missing_config_clients: list[ClientId] = field(default_factory=list)
+    missing_skill_clients: list[ClientId] = field(default_factory=list)
+    message: str = ""
+
+
+@dataclass(frozen=True)
+class SetupResult:
+    ok: bool
+    config: McpServerConfig
+    masked_token: str
+    skill_version: str
+    configured_clients: list[ClientId]
+    config_messages: list[str]
+    skill_messages: list[str]
+    doctor: DoctorReport
+    message: str
+
+
+def mask_token(token: str) -> str:
+    if len(token) <= 8:
+        return "****"
+    return f"{token[:4]}...{token[-4:]}"

unlegacy_cli/domain/ports.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from unlegacy_cli.domain.models import ClientId, McpServerConfig, SkillPackage
+
+
+class McpGateway(Protocol):
+    def validate(self, config: McpServerConfig) -> None:
+        """Raise a ValueError with a user-facing message when auth fails."""
+
+    def list_tools(self, config: McpServerConfig) -> list[str]:
+        """Return the MCP tool names advertised by the server."""
+
+    def list_repos(self, config: McpServerConfig) -> list[dict[str, object]]:
+        """Call the Unlegacy list_repos tool and return parsed repo rows."""
+
+
+class ClientConfigStore(Protocol):
+    def configure(self, client: ClientId, config: McpServerConfig, *, dry_run: bool) -> str:
+        """Write or print the MCP config for one selected client."""
+
+    def has_config(self, client: ClientId, config: McpServerConfig) -> bool:
+        """Return whether the selected client appears configured."""
+
+
+class SkillInstaller(Protocol):
+    def install(self, client: ClientId, *, dry_run: bool) -> str:
+        """Install the packaged Unlegacy skill or instruction file."""
+
+    def is_installed(self, client: ClientId) -> bool:
+        """Return whether the Unlegacy skill is detectable for the client."""
+
+    def version(self) -> str:
+        """Return the packaged skill version."""
+
+
+class SkillRepository(Protocol):
+    def load(self) -> SkillPackage:
+        """Load and validate the packaged skill."""

unlegacy_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: unlegacy-cli
+Version: 0.1.0
+Summary: Unlegacy setup CLI for external coding agents
+Author: Unlegacy
+Project-URL: Homepage, https://app.unlegacy.ai
+Project-URL: Repository, https://github.com/unlegacy-ai/unlegacy-core
+Keywords: unlegacy,mcp,cli,coding-agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# unlegacy-cli
+
+Installable CLI for connecting local coding agents to Unlegacy MCP.
+
+Unlegacy generates repository documentation and knowledge graph data in the
+platform. This CLI configures external coding agents so they can consume that
+MCP surface.
+
+## Install
+
+Published package:
+
+```sh
+uv tool install unlegacy-cli
+```
+
+or:
+
+```sh
+pip install unlegacy-cli
+```
+
+After install, the command is saved on the user's machine as:
+
+```sh
+unlegacy --help
+```
+
+From a checkout:
+
+```sh
+pip install .
+```
+
+or:
+
+```sh
+uv tool install .
+```
+
+One-shot setup without preinstalling:
+
+```sh
+uv tool run --from unlegacy-cli unlegacy setup --token mcp_live_xxx --endpoint https://app.unlegacy.ai/ai/mcp
+```
+
+## Distribution
+
+Build the package artifacts:
+
+```sh
+uv build
+```
+
+The build creates `dist/unlegacy_cli-<version>.tar.gz` and
+`dist/unlegacy_cli-<version>-py3-none-any.whl`. Publish those artifacts to the
+Python package index used by Unlegacy clients.
+
+## Setup
+
+```sh
+unlegacy setup
+```
+
+The flow:
+
+1. Shows the Unlegacy logo.
+2. Prompts for the MCP token from the Unlegacy frontend.
+3. Prompts for the MCP endpoint. Press Enter to use the local app endpoint: `http://localhost:5173/ai/mcp`.
+4. Lets the user select supported clients.
+5. Writes or merges MCP config.
+6. Installs the packaged `unlegacy` skill.
+7. Runs `unlegacy doctor`.
+
+Non-interactive usage:
+
+```sh
+UNLEGACY_MCP_TOKEN=mcp_live_xxx \
+unlegacy setup --client claude-code --client codex --endpoint https://app.unlegacy.ai/ai/mcp
+```
+
+For local development:
+
+```sh
+UNLEGACY_MCP_TOKEN=mcp_live_xxx \
+unlegacy setup --client claude-code --client codex --endpoint http://localhost:5173/ai/mcp
+```
+
+Supported client values:
+
+- `claude-code`
+- `codex`
+- `cursor`
+- `vscode-copilot`
+- `opencode`
+- `all`
+
+## Commands
+
+```sh
+unlegacy setup
+unlegacy doctor
+unlegacy install-skills --client codex
+unlegacy status
+```
+
+## Development
+
+```sh
+uv run pytest
+```

unlegacy_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+unlegacy_cli/__init__.py,sha256=VZTECcVMa5oztTgkvmv1gA4YywfEq6v1GYamDspoByM,51
+unlegacy_cli/__main__.py,sha256=Ul2QTFxgrWJYi4cJ7AxPkUTDlGURvTR9HKGLMvYGUKA,92
+unlegacy_cli/cli.py,sha256=dTkexk2-KMhXbw5_kjSdpPlwTeND6cTtQzQkL6c1Z58,13608
+unlegacy_cli/adapters/client_configs.py,sha256=IuVoTL__L5lpb1NwKstNx3nKORoQsH_ceBuwp12yq3g,5650
+unlegacy_cli/adapters/mcp_http.py,sha256=UOznmFQOnik0q8FDhHM1ScXBjfbWrilNcQz_MuSnDR8,5454
+unlegacy_cli/adapters/skills.py,sha256=cRzU2WLjdhiqcHV6v8qWd3AbaEI9wPU2CMkPWjnt2vE,3301
+unlegacy_cli/application/setup.py,sha256=zBC6qgZ2wAeAbFzW1BqMvj_HPEBPbwURBkZCSo3542s,5148
+unlegacy_cli/assets/skills/unlegacy/SKILL.md,sha256=wjeeRR33K51hdhKbKvlivcFAIHdS7sazkRP8-my8uy8,2358
+unlegacy_cli/domain/models.py,sha256=OGh6mntHcmituEiZKKOZIj0Jlaw5FcNsiWZ8CZaeOIM,1941
+unlegacy_cli/domain/ports.py,sha256=awn6HFerRFPS78zZGcInkToIAqr9Xp4-NeRfMpTBCTM,1448
+unlegacy_cli-0.1.0.dist-info/METADATA,sha256=8jHyibs4ZDIMajZRk_ZfoX5VIDVNXKIeqh-aPYbX68k,2586
+unlegacy_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+unlegacy_cli-0.1.0.dist-info/entry_points.txt,sha256=6LAlPNIf1RpGLZobqzoKvWiO_HUzrVR4UH2RZ42kz7w,51
+unlegacy_cli-0.1.0.dist-info/top_level.txt,sha256=3TqLUiM7lDviz2q5SfAPMTpbMn76uKWHoIigXK9sOnU,13
+unlegacy_cli-0.1.0.dist-info/RECORD,,

unlegacy_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

unlegacy_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+unlegacy = unlegacy_cli.cli:main

unlegacy_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+unlegacy_cli