archsteer 0.4.0__tar.gz → 0.4.2__tar.gz

{archsteer-0.4.0 → archsteer-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: archsteer
-Version: 0.4.0
+Version: 0.4.2
 Summary: Living Architecture Control Plane for the AI-Dev Era
 Author-email: ArchSteer <founders@archsteer.io>
 License: MIT
@@ -20,6 +20,7 @@ Requires-Dist: pydantic>=2.7.0
 Requires-Dist: ruamel.yaml>=0.18.0
 Requires-Dist: jinja2>=3.1.0
 Requires-Dist: rich>=13.7.0
+Requires-Dist: mcp>=1.2.0
 Provides-Extra: treesitter
 Requires-Dist: tree-sitter<0.22.0,>=0.21.0; extra == "treesitter"
 Requires-Dist: tree-sitter-languages>=1.10.0; extra == "treesitter"
@@ -31,8 +32,14 @@ Requires-Dist: black>=24.0.0; extra == "dev"
 Requires-Dist: isort>=5.13.0; extra == "dev"
 Dynamic: license-file
 
+<!-- mcp-name: io.github.einvoice-dev1/archsteer -->
+
 # ArchSteer
 
+[![ArchSteer conformance](https://img.shields.io/endpoint?url=https%3A%2F%2Fwww.archsteer.com%2Fapi%2Fbadge%2Farchsteer)](https://www.archsteer.com)
+[![PyPI](https://img.shields.io/pypi/v/archsteer)](https://pypi.org/project/archsteer/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
 **Living Architecture Control Plane for the AI-Dev Era.**
 
 AI agents now write code faster than any architect can review, document, or govern it.
@@ -57,11 +64,13 @@ Everything is a projection of one code-derived model — `.archsteer/model.json`
 ## Install
 
 ```bash
-pip install archsteer                 # regex engine, zero native deps
+pip install archsteer                 # regex engine + the local MCP server, zero native deps
 pip install "archsteer[treesitter]"   # optional native acceleration
-pip install "archsteer[mcp]"          # optional: the local MCP server (below)
 ```
 
+(Since 0.4.1 the MCP server ships in the base install; `pip install "archsteer[mcp]"` still
+works as a no-op alias.)
+
 ## Quickstart
 
 ```bash
@@ -83,9 +92,9 @@ archsteer report    # self-contained .archsteer/report.html
 2. **Conservative, architect-in-the-loop ADRs.** Only external-boundary changes (new
    dependency, new datastore, new layer) draft an ADR — never internal reshuffles, never
    auto-committed.
-3. **Sharp agent steering.** Guardrails injected into `CLAUDE.md` / `AGENTS.md` are scoped to
-   the files in play and point at the governing ADR — they don't dump the whole model into the
-   context window.
+3. **Sharp agent steering.** Guardrails injected into `CLAUDE.md`, `AGENTS.md`, and
+   `.cursor/rules/archsteer.mdc` (an always-on Cursor rule) are scoped to the files in play and
+   point at the governing ADR — they don't dump the whole model into the context window.
 
 ## Declaring intent — `.archsteer/architecture.yaml`
 
@@ -121,18 +130,37 @@ Add it to Claude Code:
 claude mcp add archsteer -- archsteer mcp
 ```
 
-Or to any MCP-compatible client's config (Cursor, etc.):
+Add it to Cursor with one click:
+[**Install in Cursor →**](cursor://anysphere.cursor-deeplink/mcp/install?name=archsteer&config=eyJjb21tYW5kIjoiYXJjaHN0ZWVyIiwiYXJncyI6WyJtY3AiXX0%3D)
+
+Or to any MCP-compatible client's config:
 
 ```json
 { "mcpServers": { "archsteer": { "command": "archsteer", "args": ["mcp"] } } }
 ```
 
+Also published to the [official MCP registry](https://registry.modelcontextprotocol.io) as
+`io.github.einvoice-dev1/archsteer` (runnable via `uvx archsteer mcp`).
+
 ## CI / pre-commit
 
 - GitHub Action: `.github/workflows/archsteer.yml` (maps, drafts ADRs, runs the net-new gate,
   uploads `report.html`).
 - Git hook: `cp hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit`.
 
+## Conformance badge
+
+If your repo pushes snapshots to the situation room (`archsteer push`), its latest
+conformance score is a live badge — the one at the top of this README is this repo
+governing itself:
+
+```markdown
+[![ArchSteer conformance](https://img.shields.io/endpoint?url=https%3A%2F%2Fwww.archsteer.com%2Fapi%2Fbadge%2FYOUR-REPO)](https://www.archsteer.com)
+```
+
+Replace `YOUR-REPO` with the repo name `archsteer push` reports. Green at ≥90%, grey while
+you're still x-ray-only (no `architecture.yaml` declared yet).
+
 ## Try the demo
 
 ```bash
@@ -144,10 +172,9 @@ archsteer init && archsteer map && archsteer report   # open .archsteer/report.h
 
 - **Shipped** — cloud control plane (Next.js + Supabase): multi-repo situation room with
   drift/decision time-series. `archsteer mcp`: a local MCP server so agents query the live
-  model + intent mid-edit.
-- **Next** — an org-wide, hosted MCP server (Team tier) so agents can ask cross-repo questions
-  against the situation room — "what's our drift index," "which repos have pending ADRs" —
-  the same data as the dashboard, over MCP.
+  model + intent mid-edit. An org-wide, hosted MCP server (Team tier) so agents can ask
+  cross-repo questions against the situation room — "what's our drift index," "which repos
+  have pending ADRs" — the same data as the dashboard, over MCP.
 - **Later** — auth, org/repo model, billing.
 
 ## Development

{archsteer-0.4.0 → archsteer-0.4.2}/README.md

@@ -1,5 +1,11 @@
+<!-- mcp-name: io.github.einvoice-dev1/archsteer -->
+
 # ArchSteer
 
+[![ArchSteer conformance](https://img.shields.io/endpoint?url=https%3A%2F%2Fwww.archsteer.com%2Fapi%2Fbadge%2Farchsteer)](https://www.archsteer.com)
+[![PyPI](https://img.shields.io/pypi/v/archsteer)](https://pypi.org/project/archsteer/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
 **Living Architecture Control Plane for the AI-Dev Era.**
 
 AI agents now write code faster than any architect can review, document, or govern it.
@@ -24,11 +30,13 @@ Everything is a projection of one code-derived model — `.archsteer/model.json`
 ## Install
 
 ```bash
-pip install archsteer                 # regex engine, zero native deps
+pip install archsteer                 # regex engine + the local MCP server, zero native deps
 pip install "archsteer[treesitter]"   # optional native acceleration
-pip install "archsteer[mcp]"          # optional: the local MCP server (below)
 ```
 
+(Since 0.4.1 the MCP server ships in the base install; `pip install "archsteer[mcp]"` still
+works as a no-op alias.)
+
 ## Quickstart
 
 ```bash
@@ -50,9 +58,9 @@ archsteer report    # self-contained .archsteer/report.html
 2. **Conservative, architect-in-the-loop ADRs.** Only external-boundary changes (new
    dependency, new datastore, new layer) draft an ADR — never internal reshuffles, never
    auto-committed.
-3. **Sharp agent steering.** Guardrails injected into `CLAUDE.md` / `AGENTS.md` are scoped to
-   the files in play and point at the governing ADR — they don't dump the whole model into the
-   context window.
+3. **Sharp agent steering.** Guardrails injected into `CLAUDE.md`, `AGENTS.md`, and
+   `.cursor/rules/archsteer.mdc` (an always-on Cursor rule) are scoped to the files in play and
+   point at the governing ADR — they don't dump the whole model into the context window.
 
 ## Declaring intent — `.archsteer/architecture.yaml`
 
@@ -88,18 +96,37 @@ Add it to Claude Code:
 claude mcp add archsteer -- archsteer mcp
 ```
 
-Or to any MCP-compatible client's config (Cursor, etc.):
+Add it to Cursor with one click:
+[**Install in Cursor →**](cursor://anysphere.cursor-deeplink/mcp/install?name=archsteer&config=eyJjb21tYW5kIjoiYXJjaHN0ZWVyIiwiYXJncyI6WyJtY3AiXX0%3D)
+
+Or to any MCP-compatible client's config:
 
 ```json
 { "mcpServers": { "archsteer": { "command": "archsteer", "args": ["mcp"] } } }
 ```
 
+Also published to the [official MCP registry](https://registry.modelcontextprotocol.io) as
+`io.github.einvoice-dev1/archsteer` (runnable via `uvx archsteer mcp`).
+
 ## CI / pre-commit
 
 - GitHub Action: `.github/workflows/archsteer.yml` (maps, drafts ADRs, runs the net-new gate,
   uploads `report.html`).
 - Git hook: `cp hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit`.
 
+## Conformance badge
+
+If your repo pushes snapshots to the situation room (`archsteer push`), its latest
+conformance score is a live badge — the one at the top of this README is this repo
+governing itself:
+
+```markdown
+[![ArchSteer conformance](https://img.shields.io/endpoint?url=https%3A%2F%2Fwww.archsteer.com%2Fapi%2Fbadge%2FYOUR-REPO)](https://www.archsteer.com)
+```
+
+Replace `YOUR-REPO` with the repo name `archsteer push` reports. Green at ≥90%, grey while
+you're still x-ray-only (no `architecture.yaml` declared yet).
+
 ## Try the demo
 
 ```bash
@@ -111,10 +138,9 @@ archsteer init && archsteer map && archsteer report   # open .archsteer/report.h
 
 - **Shipped** — cloud control plane (Next.js + Supabase): multi-repo situation room with
   drift/decision time-series. `archsteer mcp`: a local MCP server so agents query the live
-  model + intent mid-edit.
-- **Next** — an org-wide, hosted MCP server (Team tier) so agents can ask cross-repo questions
-  against the situation room — "what's our drift index," "which repos have pending ADRs" —
-  the same data as the dashboard, over MCP.
+  model + intent mid-edit. An org-wide, hosted MCP server (Team tier) so agents can ask
+  cross-repo questions against the situation room — "what's our drift index," "which repos
+  have pending ADRs" — the same data as the dashboard, over MCP.
 - **Later** — auth, org/repo model, billing.
 
 ## Development

{archsteer-0.4.0 → archsteer-0.4.2}/archsteer/__init__.py

@@ -4,4 +4,4 @@ One code-derived model (``model.json``) powers every pillar:
 MAP, DOCUMENT, GOVERN, STEER, EVOLVE.
 """
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"

archsteer-0.4.2/archsteer/engine/mapper.py

@@ -0,0 +1,217 @@
+"""Walks a repo and assembles the :class:`ArchitectureModel` from parsed files.
+
+Resolves relative imports to internal component keys, infers a layer per
+component from path conventions (overridable by intent later), and records the
+declared third-party manifest dependencies that ADR decision detection watches.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import List, Optional
+
+from archsteer.engine.model import ArchitectureModel, DependencyEdge
+from archsteer.engine.parser import CodeParserFacade
+
+try:  # stdlib on 3.11+; on 3.10 we fall back to a scoped regex
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python 3.10 only
+    tomllib = None  # type: ignore[assignment]
+
+IGNORE_DIRS = {
+    ".git", ".archsteer", ".venv", "venv", "node_modules", "__pycache__",
+    "dist", "build", ".next", ".turbo", "coverage", ".pytest_cache", ".mypy_cache",
+}
+SOURCE_EXTS = {".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py"}
+
+# Path-segment -> layer. First match wins. Architects refine this in intent.
+LAYER_HINTS = [
+    ("repositories", "repository"),
+    ("repository", "repository"),
+    ("controllers", "controller"),
+    ("controller", "controller"),
+    ("routes", "route"),
+    ("routers", "route"),
+    ("services", "service"),
+    ("service", "service"),
+    ("models", "model"),
+    ("entities", "model"),
+    ("middleware", "middleware"),
+    ("handlers", "handler"),
+    ("api", "api"),
+    ("lib", "lib"),
+    ("utils", "util"),
+    ("components", "ui"),
+]
+_CANDIDATE_EXTS = ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py"]
+
+
+def _infer_layer(rel_path: str) -> Optional[str]:
+    segments = {s.lower() for s in Path(rel_path).parts}
+    for hint, layer in LAYER_HINTS:
+        if hint in segments:
+            return layer
+    return None
+
+
+def _git_sha(root: Path) -> Optional[str]:
+    try:
+        out = subprocess.run(
+            ["git", "-C", str(root), "rev-parse", "--short", "HEAD"],
+            capture_output=True, text=True, timeout=5,
+        )
+        return out.stdout.strip() or None if out.returncode == 0 else None
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _read_manifest_deps(root: Path) -> List[str]:
+    """Declared RUNTIME dependency names from package.json / pyproject.toml.
+
+    devDependencies and dev extras are deliberately excluded — tooling churn
+    (linters, test runners) would flood ADR decision detection with
+    meaningless "new dependency" entries.
+    """
+    deps: set[str] = set()
+    pkg = root / "package.json"
+    if pkg.exists():
+        try:
+            data = json.loads(pkg.read_text(encoding="utf-8"))
+            for key in ("dependencies", "peerDependencies"):
+                deps.update((data.get(key) or {}).keys())
+        except (json.JSONDecodeError, OSError):
+            pass
+    pyproject = root / "pyproject.toml"
+    if pyproject.exists():
+        text = pyproject.read_text(encoding="utf-8")
+        specs: List[str] = []
+        if tomllib is not None:
+            try:
+                specs = list((tomllib.loads(text).get("project") or {}).get("dependencies") or [])
+            except tomllib.TOMLDecodeError:
+                pass
+        else:  # Python 3.10: no stdlib TOML parser; scope the regex to dep arrays
+            for block in re.finditer(r"^dependencies\s*=\s*\[(.*?)\]", text, re.DOTALL | re.MULTILINE):
+                specs += re.findall(r"""["']([^"']+)["']""", block.group(1))
+        for spec in specs:  # PEP 508: name is the leading token
+            m = re.match(r"\s*([A-Za-z0-9_.\-]+)", spec)
+            if m:
+                deps.add(m.group(1))
+    return sorted(deps)
+
+
+def _resolve_internal(importer_rel: str, target: str, components: dict) -> Optional[str]:
+    """Resolve a relative JS/TS import (``./x``) to a component key, or None."""
+    if not target.startswith("."):
+        return None
+    raw = (Path(importer_rel).parent / target).as_posix()
+    base_posix = os.path.normpath(raw).replace(os.sep, "/")  # collapse ../ segments
+    for ext in _CANDIDATE_EXTS:
+        cand = f"{base_posix}{ext}"
+        if cand in components:
+            return cand
+        idx = f"{base_posix}/index{ext}" if ext else None
+        if idx and idx in components:
+            return idx
+    return None
+
+
+def _resolve_python(
+    importer_rel: str, target: str, symbols: List[str], components: dict, root_name: str
+) -> List[str]:
+    """Resolve a Python import to component keys (possibly several).
+
+    Handles the shapes the JS resolver can't:
+    - relative imports: ``from .utils import x`` / ``from ..pkg.mod import y``
+      (dotted prefix = directory levels up from the importer)
+    - same-package absolute imports: ``from fastapi import routing`` resolves
+      whether the x-ray root is the repo (components keyed ``fastapi/...``) or
+      the package dir itself (components keyed ``routing.py`` — first segment
+      matches the root dir name and is stripped).
+    - submodule imports through a package: ``from pkg import mod_a, mod_b``
+      resolves to each symbol that is itself a module file, so the real edges
+      aren't collapsed onto ``pkg/__init__.py``.
+
+    A stdlib/third-party name shadowed by a local module resolves to the local
+    file, mirroring how Python's own import system can shadow.
+    """
+    def probe(mod_path: str) -> Optional[str]:
+        mod_path = os.path.normpath(mod_path).replace(os.sep, "/")
+        if mod_path in (".", ""):
+            mod_path = "__init__"  # `from . import x` in a root-level module
+        for cand in (f"{mod_path}.py", f"{mod_path}/__init__.py"):
+            if cand in components:
+                return cand
+        return None
+
+    if target.startswith("."):
+        dots = len(target) - len(target.lstrip("."))
+        rest = target.lstrip(".")
+        base = Path(importer_rel).parent
+        for _ in range(dots - 1):
+            base = base.parent
+        base_path = (base / rest.replace(".", "/")).as_posix() if rest else base.as_posix()
+    else:
+        parts = target.split(".")
+        if probe("/".join(parts)) is None and parts[0] == root_name:
+            parts = parts[1:]
+        base_path = "/".join(parts)
+
+    hit = probe(base_path)
+    if hit is None:
+        return []
+    if not hit.endswith("__init__.py"):
+        return [hit]
+    # Package import: symbols may be submodules — resolve each that is one.
+    pkg_dir = hit[: -len("__init__.py")]
+    sub_hits = [h for s in symbols if (h := probe(f"{pkg_dir}{s}"))]
+    return sub_hits or [hit]
+
+
+def build_model(root_dir: str | Path) -> ArchitectureModel:
+    root = Path(root_dir).resolve()
+    parser = CodeParserFacade()
+    model = ArchitectureModel(
+        repo_name=root.name,
+        commit_sha=_git_sha(root),
+        manifest_dependencies=_read_manifest_deps(root),
+    )
+
+    for path in sorted(root.rglob("*")):
+        if not path.is_file() or path.suffix not in SOURCE_EXTS:
+            continue
+        if any(part in IGNORE_DIRS for part in path.relative_to(root).parts):
+            continue
+        comp = parser.parse_file(path, root)
+        comp.layer = _infer_layer(comp.file_path)
+        model.components[comp.file_path] = comp
+
+    # Second pass: resolve internal edges now that all components are known.
+    # Python deps are probed even when the parser flagged them external:
+    # `from mypkg import mod` is textually indistinguishable from a third-party
+    # import, so resolution against the actual component set is the arbiter.
+    for rel, comp in model.components.items():
+        extra: List[DependencyEdge] = []
+        for dep in comp.dependencies:
+            if comp.language == "python":
+                hits = _resolve_python(rel, dep.target, dep.symbols, model.components, root.name)
+            elif dep.external:
+                continue
+            else:
+                one = _resolve_internal(rel, dep.target, model.components)
+                hits = [one] if one else []
+            if hits:
+                dep.target = hits[0]
+                dep.external = False
+                # `from pkg import mod_a, mod_b`: one statement, several real edges.
+                extra += [
+                    dep.model_copy(update={"target": h, "symbols": []}) for h in hits[1:]
+                ]
+            # else: keep as-is (unresolved relative imports stay internal,
+            # unresolved absolute imports stay external)
+        comp.dependencies.extend(extra)
+    return model

{archsteer-0.4.0 → archsteer-0.4.2}/archsteer/steer.py

@@ -20,7 +20,10 @@ from archsteer.engine.model import ArchitectureModel
 START_MARKER = "<!-- BEGIN ARCHSTEER GUARDRAILS (auto-generated; do not edit) -->"
 END_MARKER = "<!-- END ARCHSTEER GUARDRAILS -->"
 
-DEFAULT_TARGETS = ["CLAUDE.md", "AGENTS.md", ".cursor/rules"]
+DEFAULT_TARGETS = ["CLAUDE.md", "AGENTS.md", ".cursor/rules/archsteer.mdc"]
+# Files ArchSteer owns outright and will create on first run. AGENTS.md is a
+# shared multi-tool convention we only append to if the project already has one.
+_AUTO_CREATE = ("CLAUDE.md", ".cursor/rules/archsteer.mdc")
 
 
 def _rule_applies_to_files(rule: Rule, files: List[str], model: ArchitectureModel) -> bool:
@@ -83,8 +86,9 @@ class AgentSteeringEngine:
         written: List[Path] = []
         for target in (targets or DEFAULT_TARGETS):
             path = self.root / target
-            if not path.exists() and target not in ("CLAUDE.md",):
-                # Only auto-create the canonical CLAUDE.md; respect existing others.
+            if not path.exists() and target not in _AUTO_CREATE:
+                # Respect files/dirs the project doesn't already use, except
+                # for the files ArchSteer owns outright (see _AUTO_CREATE).
                 if not path.parent.exists():
                     continue
             written.append(self._inject(path, payload))
@@ -92,14 +96,23 @@ class AgentSteeringEngine:
 
     @staticmethod
     def _inject(path: Path, payload: str) -> Path:
+        # `.cursor/rules` is a directory by Cursor convention (may already
+        # exist as one in real repos) — never write to it directly. We only
+        # ever target a specific file inside it (see DEFAULT_TARGETS).
+        if path.is_dir():
+            raise ValueError(f"steer target must be a file, not a directory: {path}")
         content = path.read_text(encoding="utf-8") if path.exists() else ""
+        if path.suffix == ".mdc" and not content.lstrip().startswith("---"):
+            # Cursor rule frontmatter: alwaysApply=true keeps architecture
+            # guardrails in every agent session, matching CLAUDE.md/AGENTS.md.
+            content = f"---\nalwaysApply: true\n---\n\n{content}" if content else "---\nalwaysApply: true\n---\n"
         pattern = re.compile(
             re.escape(START_MARKER) + r".*?" + re.escape(END_MARKER), re.DOTALL
         )
         if pattern.search(content):
             updated = pattern.sub(payload, content)
         else:
-            updated = f"{content.rstrip()}\n\n{payload}\n" if content else payload + "\n"
+            updated = f"{content.rstrip()}\n\n{payload}\n" if content.strip() else f"{content}{payload}\n"
         path.parent.mkdir(parents=True, exist_ok=True)
         path.write_text(updated.strip() + "\n", encoding="utf-8")
         return path

{archsteer-0.4.0 → archsteer-0.4.2}/archsteer.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: archsteer
-Version: 0.4.0
+Version: 0.4.2
 Summary: Living Architecture Control Plane for the AI-Dev Era
 Author-email: ArchSteer <founders@archsteer.io>
 License: MIT
@@ -20,6 +20,7 @@ Requires-Dist: pydantic>=2.7.0
 Requires-Dist: ruamel.yaml>=0.18.0
 Requires-Dist: jinja2>=3.1.0
 Requires-Dist: rich>=13.7.0
+Requires-Dist: mcp>=1.2.0
 Provides-Extra: treesitter
 Requires-Dist: tree-sitter<0.22.0,>=0.21.0; extra == "treesitter"
 Requires-Dist: tree-sitter-languages>=1.10.0; extra == "treesitter"
@@ -31,8 +32,14 @@ Requires-Dist: black>=24.0.0; extra == "dev"
 Requires-Dist: isort>=5.13.0; extra == "dev"
 Dynamic: license-file
 
+<!-- mcp-name: io.github.einvoice-dev1/archsteer -->
+
 # ArchSteer
 
+[![ArchSteer conformance](https://img.shields.io/endpoint?url=https%3A%2F%2Fwww.archsteer.com%2Fapi%2Fbadge%2Farchsteer)](https://www.archsteer.com)
+[![PyPI](https://img.shields.io/pypi/v/archsteer)](https://pypi.org/project/archsteer/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
 **Living Architecture Control Plane for the AI-Dev Era.**
 
 AI agents now write code faster than any architect can review, document, or govern it.
@@ -57,11 +64,13 @@ Everything is a projection of one code-derived model — `.archsteer/model.json`
 ## Install
 
 ```bash
-pip install archsteer                 # regex engine, zero native deps
+pip install archsteer                 # regex engine + the local MCP server, zero native deps
 pip install "archsteer[treesitter]"   # optional native acceleration
-pip install "archsteer[mcp]"          # optional: the local MCP server (below)
 ```
 
+(Since 0.4.1 the MCP server ships in the base install; `pip install "archsteer[mcp]"` still
+works as a no-op alias.)
+
 ## Quickstart
 
 ```bash
@@ -83,9 +92,9 @@ archsteer report    # self-contained .archsteer/report.html
 2. **Conservative, architect-in-the-loop ADRs.** Only external-boundary changes (new
    dependency, new datastore, new layer) draft an ADR — never internal reshuffles, never
    auto-committed.
-3. **Sharp agent steering.** Guardrails injected into `CLAUDE.md` / `AGENTS.md` are scoped to
-   the files in play and point at the governing ADR — they don't dump the whole model into the
-   context window.
+3. **Sharp agent steering.** Guardrails injected into `CLAUDE.md`, `AGENTS.md`, and
+   `.cursor/rules/archsteer.mdc` (an always-on Cursor rule) are scoped to the files in play and
+   point at the governing ADR — they don't dump the whole model into the context window.
 
 ## Declaring intent — `.archsteer/architecture.yaml`
 
@@ -121,18 +130,37 @@ Add it to Claude Code:
 claude mcp add archsteer -- archsteer mcp
 ```
 
-Or to any MCP-compatible client's config (Cursor, etc.):
+Add it to Cursor with one click:
+[**Install in Cursor →**](cursor://anysphere.cursor-deeplink/mcp/install?name=archsteer&config=eyJjb21tYW5kIjoiYXJjaHN0ZWVyIiwiYXJncyI6WyJtY3AiXX0%3D)
+
+Or to any MCP-compatible client's config:
 
 ```json
 { "mcpServers": { "archsteer": { "command": "archsteer", "args": ["mcp"] } } }
 ```
 
+Also published to the [official MCP registry](https://registry.modelcontextprotocol.io) as
+`io.github.einvoice-dev1/archsteer` (runnable via `uvx archsteer mcp`).
+
 ## CI / pre-commit
 
 - GitHub Action: `.github/workflows/archsteer.yml` (maps, drafts ADRs, runs the net-new gate,
   uploads `report.html`).
 - Git hook: `cp hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit`.
 
+## Conformance badge
+
+If your repo pushes snapshots to the situation room (`archsteer push`), its latest
+conformance score is a live badge — the one at the top of this README is this repo
+governing itself:
+
+```markdown
+[![ArchSteer conformance](https://img.shields.io/endpoint?url=https%3A%2F%2Fwww.archsteer.com%2Fapi%2Fbadge%2FYOUR-REPO)](https://www.archsteer.com)
+```
+
+Replace `YOUR-REPO` with the repo name `archsteer push` reports. Green at ≥90%, grey while
+you're still x-ray-only (no `architecture.yaml` declared yet).
+
 ## Try the demo
 
 ```bash
@@ -144,10 +172,9 @@ archsteer init && archsteer map && archsteer report   # open .archsteer/report.h
 
 - **Shipped** — cloud control plane (Next.js + Supabase): multi-repo situation room with
   drift/decision time-series. `archsteer mcp`: a local MCP server so agents query the live
-  model + intent mid-edit.
-- **Next** — an org-wide, hosted MCP server (Team tier) so agents can ask cross-repo questions
-  against the situation room — "what's our drift index," "which repos have pending ADRs" —
-  the same data as the dashboard, over MCP.
+  model + intent mid-edit. An org-wide, hosted MCP server (Team tier) so agents can ask
+  cross-repo questions against the situation room — "what's our drift index," "which repos
+  have pending ADRs" — the same data as the dashboard, over MCP.
 - **Later** — auth, org/repo model, billing.
 
 ## Development

{archsteer-0.4.0 → archsteer-0.4.2}/archsteer.egg-info/requires.txt

@@ -3,6 +3,7 @@ pydantic>=2.7.0
 ruamel.yaml>=0.18.0
 jinja2>=3.1.0
 rich>=13.7.0
+mcp>=1.2.0
 
 [dev]
 pytest>=8.0.0

{archsteer-0.4.0 → archsteer-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "archsteer"
-version = "0.4.0"
+version = "0.4.2"
 description = "Living Architecture Control Plane for the AI-Dev Era"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -21,6 +21,11 @@ dependencies = [
     "ruamel.yaml>=0.18.0",
     "jinja2>=3.1.0",
     "rich>=13.7.0",
+    # mcp moved from an extra to a base dep in 0.4.1: MCP registries and
+    # runners (`uvx archsteer`) can't express extras, and `archsteer mcp`
+    # failing after a plain install was a broken first-run for exactly the
+    # AI-agent users the command exists for.
+    "mcp>=1.2.0",
 ]
 
 [project.optional-dependencies]
@@ -31,8 +36,9 @@ treesitter = [
     "tree-sitter>=0.21.0,<0.22.0",
     "tree-sitter-languages>=1.10.0",
 ]
-# `archsteer mcp` — a local MCP server for AI agents. Optional so the base
-# install stays dependency-light; only pulled in by people who use it.
+# Kept as a no-op alias for compatibility: docs published before 0.4.1 say
+# `pip install "archsteer[mcp]"` and that must keep working. The mcp
+# dependency itself is in the base install now (see dependencies above).
 mcp = [
     "mcp>=1.2.0",
 ]

{archsteer-0.4.0 → archsteer-0.4.2}/tests/test_engine.py

@@ -118,6 +118,27 @@ def test_steer_is_idempotent(tmp_path: Path):
     assert target.read_text().count(START_MARKER) == 1
 
 
+def test_steer_writes_cursor_mdc_with_frontmatter(tmp_path: Path):
+    # Real repos already have .cursor/rules as a directory (Cursor's own
+    # convention) — writing must target a file inside it, not the dir itself.
+    (tmp_path / ".cursor" / "rules").mkdir(parents=True)
+    _legacy_repo(tmp_path)
+    model = build_model(tmp_path)
+    engine = AgentSteeringEngine(tmp_path)
+    payload = engine.synthesize(_intent(), model, files=["src/controllers/payment_controller.js"])
+    written = engine.write(payload)
+    mdc = tmp_path / ".cursor" / "rules" / "archsteer.mdc"
+    assert mdc in written
+    text = mdc.read_text()
+    assert text.startswith("---\nalwaysApply: true\n---")
+    assert START_MARKER in text
+    # Idempotent: re-running doesn't duplicate the marker or the frontmatter.
+    engine.write(engine.synthesize(_intent(), model, files=["src/controllers/payment_controller.js"]))
+    text2 = mdc.read_text()
+    assert text2.count(START_MARKER) == 1
+    assert text2.count("alwaysApply: true") == 1
+
+
 def test_docs_render_is_deterministic(tmp_path: Path):
     _legacy_repo(tmp_path)
     model = build_model(tmp_path)
@@ -160,3 +181,43 @@ def test_first_feed_is_baseline(tmp_path: Path):
     _legacy_repo(tmp_path)
     feed = compute_feed(None, build_model(tmp_path))
     assert feed.is_first and feed.changes == []
+
+
+def test_python_import_resolution(tmp_path: Path) -> None:
+    """Relative and same-package absolute Python imports resolve to internal edges."""
+    _write(tmp_path, "mypkg/__init__.py", "")
+    _write(tmp_path, "mypkg/routing.py", "from .utils import helper\nclass Router: pass\n")
+    _write(tmp_path, "mypkg/utils.py", "import json\ndef helper(): pass\n")
+    _write(tmp_path, "mypkg/sub/deep.py", "from ..routing import Router\nfrom mypkg import utils\n")
+    model = build_model(tmp_path)
+    edges = set(model.internal_edges())
+    assert ("mypkg/routing.py", "mypkg/utils.py") in edges          # relative .utils
+    assert ("mypkg/sub/deep.py", "mypkg/routing.py") in edges       # relative ..routing
+    assert ("mypkg/sub/deep.py", "mypkg/utils.py") in edges         # absolute mypkg.utils
+    # stdlib import stays external
+    utils = model.components["mypkg/utils.py"]
+    assert all(d.external for d in utils.dependencies if d.target == "json")
+
+
+def test_python_resolution_at_package_root(tmp_path: Path) -> None:
+    """X-raying the package dir itself resolves pkg-prefixed absolute imports."""
+    pkg = tmp_path / "mypkg"
+    _write(tmp_path, "mypkg/__init__.py", "")
+    _write(tmp_path, "mypkg/a.py", "from mypkg.b import thing\n")
+    _write(tmp_path, "mypkg/b.py", "def thing(): pass\n")
+    model = build_model(pkg)
+    assert ("a.py", "b.py") in set(model.internal_edges())
+
+
+def test_manifest_deps_runtime_only(tmp_path: Path) -> None:
+    """Manifest reader takes runtime deps only, not dev tooling or stray strings."""
+    _write(tmp_path, "package.json",
+           '{"dependencies":{"express":"^4"},"devDependencies":{"eslint":"^9"},"peerDependencies":{"react":"^19"}}')
+    _write(tmp_path, "pyproject.toml",
+           '[project]\nname = "x"\nlicense = "BSD-3-Clause"\n'
+           'dependencies = ["pydantic>=2.7.0", "rich>=13"]\n'
+           '[project.optional-dependencies]\ndev = ["pytest>=8"]\n'
+           '[tool.pytest.ini_options]\naddopts = "--strict-markers"\n')
+    deps = set(build_model(tmp_path).manifest_dependencies)
+    assert {"express", "react", "pydantic", "rich"} <= deps
+    assert not {"eslint", "pytest", "BSD-3-Clause", "--strict-markers"} & deps

archsteer-0.4.0/archsteer/engine/mapper.py

@@ -1,133 +0,0 @@
-"""Walks a repo and assembles the :class:`ArchitectureModel` from parsed files.
-
-Resolves relative imports to internal component keys, infers a layer per
-component from path conventions (overridable by intent later), and records the
-declared third-party manifest dependencies that ADR decision detection watches.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import re
-import subprocess
-from pathlib import Path
-from typing import List, Optional
-
-from archsteer.engine.model import ArchitectureModel
-from archsteer.engine.parser import CodeParserFacade
-
-IGNORE_DIRS = {
-    ".git", ".archsteer", ".venv", "venv", "node_modules", "__pycache__",
-    "dist", "build", ".next", ".turbo", "coverage", ".pytest_cache", ".mypy_cache",
-}
-SOURCE_EXTS = {".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py"}
-
-# Path-segment -> layer. First match wins. Architects refine this in intent.
-LAYER_HINTS = [
-    ("repositories", "repository"),
-    ("repository", "repository"),
-    ("controllers", "controller"),
-    ("controller", "controller"),
-    ("routes", "route"),
-    ("routers", "route"),
-    ("services", "service"),
-    ("service", "service"),
-    ("models", "model"),
-    ("entities", "model"),
-    ("middleware", "middleware"),
-    ("handlers", "handler"),
-    ("api", "api"),
-    ("lib", "lib"),
-    ("utils", "util"),
-    ("components", "ui"),
-]
-_CANDIDATE_EXTS = ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py"]
-
-
-def _infer_layer(rel_path: str) -> Optional[str]:
-    segments = {s.lower() for s in Path(rel_path).parts}
-    for hint, layer in LAYER_HINTS:
-        if hint in segments:
-            return layer
-    return None
-
-
-def _git_sha(root: Path) -> Optional[str]:
-    try:
-        out = subprocess.run(
-            ["git", "-C", str(root), "rev-parse", "--short", "HEAD"],
-            capture_output=True, text=True, timeout=5,
-        )
-        return out.stdout.strip() or None if out.returncode == 0 else None
-    except Exception:  # noqa: BLE001
-        return None
-
-
-def _read_manifest_deps(root: Path) -> List[str]:
-    deps: set[str] = set()
-    pkg = root / "package.json"
-    if pkg.exists():
-        try:
-            data = json.loads(pkg.read_text(encoding="utf-8"))
-            for key in ("dependencies", "devDependencies", "peerDependencies"):
-                deps.update((data.get(key) or {}).keys())
-        except (json.JSONDecodeError, OSError):
-            pass
-    pyproject = root / "pyproject.toml"
-    if pyproject.exists():
-        # Lightweight extraction; avoids a hard tomli dependency on 3.10.
-        text = pyproject.read_text(encoding="utf-8")
-        for m in re.finditer(r"""["']([A-Za-z0-9_.\-]+)\s*(?:[><=!~]|["'])""", text):
-            name = m.group(1)
-            if name and not name.startswith("."):
-                deps.add(name)
-    return sorted(deps)
-
-
-def _resolve_internal(importer_rel: str, target: str, components: dict) -> Optional[str]:
-    """Resolve a relative JS/TS import (``./x``) to a component key, or None."""
-    if not target.startswith("."):
-        return None
-    raw = (Path(importer_rel).parent / target).as_posix()
-    base_posix = os.path.normpath(raw).replace(os.sep, "/")  # collapse ../ segments
-    for ext in _CANDIDATE_EXTS:
-        cand = f"{base_posix}{ext}"
-        if cand in components:
-            return cand
-        idx = f"{base_posix}/index{ext}" if ext else None
-        if idx and idx in components:
-            return idx
-    return None
-
-
-def build_model(root_dir: str | Path) -> ArchitectureModel:
-    root = Path(root_dir).resolve()
-    parser = CodeParserFacade()
-    model = ArchitectureModel(
-        repo_name=root.name,
-        commit_sha=_git_sha(root),
-        manifest_dependencies=_read_manifest_deps(root),
-    )
-
-    for path in sorted(root.rglob("*")):
-        if not path.is_file() or path.suffix not in SOURCE_EXTS:
-            continue
-        if any(part in IGNORE_DIRS for part in path.relative_to(root).parts):
-            continue
-        comp = parser.parse_file(path, root)
-        comp.layer = _infer_layer(comp.file_path)
-        model.components[comp.file_path] = comp
-
-    # Second pass: resolve internal edges now that all components are known.
-    for rel, comp in model.components.items():
-        for dep in comp.dependencies:
-            if dep.external:
-                continue
-            resolved = _resolve_internal(rel, dep.target, model.components)
-            if resolved:
-                dep.target = resolved
-            else:
-                # relative import we couldn't resolve to a file: keep as-is, internal
-                pass
-    return model