archrails-mcp 0.3.0__tar.gz

archrails_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: archrails-mcp
+Version: 0.3.0
+Summary: ArchRails MCP — thin local CLI that proxies the cloud handler. The cloud runs the validators; the CLI ships only transport, auth, git-diff capture, and architect-mode YAML editing.
+Author: ArchRails
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pyyaml

archrails_mcp-0.3.0/README.md

@@ -0,0 +1,299 @@
+# ArchRails AWS Backend
+
+Architecture governance for monorepos — enforces [FINOS CALM](https://calm.finos.org) specifications on every pull request using a deterministic rule engine combined with LLM-grounded explanations.
+
+---
+
+## What It Does
+
+ArchRails hooks into your PR workflow. When a developer opens or updates a pull request it:
+
+1. Fetches the diff and the repo's CALM architecture specification
+2. Runs a suite of deterministic preflight checks against declared nodes, edges, interfaces, and controls
+3. Calls AWS Bedrock (Claude) for grounded, plain-language explanations of any violations
+4. Posts the findings as a PR review comment with inline annotations and a blast-radius summary
+5. Approves or requests changes based on the deterministic verdict
+
+---
+
+## Supported Providers
+
+| Provider | Auth Method | Inline Comments |
+|---|---|---|
+| GitHub App | GitHub App installation (HMAC) | Yes |
+| GitHub Actions CI | Bearer token via workflow | Yes |
+| GitLab (SaaS + Self-Hosted) | Bearer token (Secrets Manager) | Summary only |
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- AWS account with DynamoDB, S3, Secrets Manager, Bedrock, Step Functions, Lambda, and ECR access
+- Python 3.11
+- Docker (for Lambda container builds)
+
+### 1. Configure Secrets Manager
+
+Create one secret per tenant with these keys:
+
+```json
+{
+  "GITHUB_TOKEN":        "<GitHub App installation token>",
+  "GITHUB_WEBHOOK_SECRET": "<webhook HMAC secret>",
+  "GITLAB_TOKEN":        "<GitLab personal/group access token>",
+  "GITLAB_WEBHOOK_SECRET": "<GitLab webhook secret token>"
+}
+```
+
+Secret ID pattern: `{PROVIDER_SECRET_ID_PREFIX}{tenant_pk}`
+
+### 2. Deploy DynamoDB Tables
+
+Create the following tables (see [Technical Design](TECH_DESIGN.md) for full schemas):
+
+| Table | PK | SK |
+|---|---|---|
+| `ArchRailsTenants` | `tenant_pk` | — |
+| `ArchRailsTenantsProvisioning` | `tenant_pk` | — |
+| `ArchRailsRepoLatestConfig` | `tenant_pk` | `repo_sk` |
+| `ArchRailsPRValidations` | `tenant_pk` | `repo_sk#{pr_number}` |
+| `ArchRailsMergedPRs` | `tenant_pk` | `repo_sk#{pr_number}` |
+| `ArchRailsNodeHistory` | `tenant_pk` | `node_id#{created_at}` |
+| `ArchRailsAccess` | `tenant_pk` | `repo_sk` |
+| `ArchRailsAuditResults` | `tenant_pk` | `repo_sk#{timestamp}` |
+
+### 3. Build and Push Lambda Images
+
+Each Lambda is packaged as a Docker container pushed to ECR:
+
+```bash
+ACCOUNT=353468317406
+REGION=us-east-2
+
+for lambda in webhook_router fetch_pr_diff fetch_archrails_config \
+              bootstrap_governance process_calm_config validate_architecture \
+              publish_review_result update_pr_status run_full_audit; do
+  docker buildx build --platform linux/amd64 \
+    -t ${ACCOUNT}.dkr.ecr.${REGION}.amazonaws.com/${lambda}:latest \
+    ./${lambda}
+  docker push ${ACCOUNT}.dkr.ecr.${REGION}.amazonaws.com/${lambda}:latest
+done
+```
+
+### 4. Deploy Step Functions State Machine
+
+Deploy `stepfunction.json` as an Express Workflow with the Lambda ARNs substituted in.
+
+### 5. Add `.archrails/config.yml` to Your Repo
+
+Open a PR with a config file — ArchRails will auto-generate the initial configuration:
+
+```yaml
+version: 1
+governance:
+  sources:
+    - id: api
+      file: services/api/architecture.json
+      provider: calm
+      owned_by: platform-team
+mapping:
+  - path: "services/api/**"
+    node: api
+  - path: "services/payments/**"
+    node: payments
+review:
+  enforce_governance: true
+  comment_mode: review
+```
+
+---
+
+## Architecture Overview
+
+```
+GitHub / GitLab Webhook
+         │
+         ▼
+  WebhookRouter Lambda
+  (verify signature, normalize event)
+         │
+         ▼
+  AWS Step Functions
+         │
+  ┌──────▼──────┐
+  │FetchPRDiff  │  → fetch diff, file list, detect config change
+  └──────┬──────┘
+         │ archrails_config_in_pr?
+         ├─ yes ──────────────────────────────────────┐
+         │                                            ▼
+         │                               FetchArchRailsConfig
+         │                               (fetch CALM sources,
+         │                                check bootstrap state)
+         │                                            │
+         │                              bootstrapped = false?
+         │                               ├─ yes → BootstrapGovernance
+         │                               │        (scan repo, infer
+         │                               │         node→path bindings,
+         │                               │         generate config.yml,
+         │                               │         commit to PR branch)
+         │                               │
+         │                               └─ no  → CalmParserLambda
+         │                                        (parse + merge CALM,
+         │                                         write to S3 staging)
+         │                                            │
+         └────────────────────────────────────────────┘
+                                                      │
+                                              ┌───────▼────────┐
+                                              │ValidateArch    │
+                                              │ · 8 preflight  │
+                                              │   checks       │
+                                              │ · Bedrock LLM  │
+                                              │ · blast radius │
+                                              └───────┬────────┘
+                                                      │
+                                              ┌───────▼────────┐
+                                              │PublishReview   │
+                                              │ · PR comment   │
+                                              │ · inline notes │
+                                              │ · APPROVE /    │
+                                              │   REQUEST CHGS │
+                                              └────────────────┘
+
+On PR merge / close:
+  UpdatePRStatus Lambda
+  (promote staging → live S3, archive record, activate tenant)
+```
+
+---
+
+## Validation Rules
+
+ArchRails enforces 19 deterministic rules across 6 categories:
+
+### Diff vs Baseline (`AR-DIFF-*`)
+
+| Rule | Severity | Trigger |
+|---|---|---|
+| AR-DIFF-001 | error | Diff calls a host:port not declared in CALM |
+| AR-DIFF-002 | error | Diff uses a port not matching the declared interface |
+| AR-DIFF-003 | error | Diff introduces a relationship not declared in CALM |
+| AR-DIFF-004 | error | Direct DB access from code without a declared connection |
+| AR-DIFF-005 | error | Source node not in CALM graph |
+| AR-DIFF-007 | error | All files for a CALM node are deleted but node remains |
+| AR-DIFF-008 | error | Hardcoded secret or high-entropy token detected in diff |
+
+### CALM Model Compliance (`AR-NODE-*`, `AR-REL-*`)
+
+| Rule | Severity | Trigger |
+|---|---|---|
+| AR-NODE-001 | warning | Node missing `data-classification` field |
+| AR-NODE-002 | warning | Node missing `controls` declaration |
+| AR-REL-001 | error | HTTPS declared but diff shows HTTP call |
+| AR-REL-002 | warning | Relationship missing `controls` declaration |
+| AR-REL-003 | warning | Declared CALM relationship has no diff evidence |
+| AR-REL-004 | error | SQL/DB access but relationship type is not `connects` |
+
+### Controls (`AR-CTRL-*`)
+
+| Rule | Severity | Trigger |
+|---|---|---|
+| AR-CTRL-001 | error | Control config violates requirement JSON schema |
+| AR-CTRL-002 | warning | Control requirement URL unreachable |
+| AR-CTRL-003 | warning | Control requirement has no URLs to validate |
+
+### Import Boundaries (`AR-IMPORT-*`)
+
+| Rule | Severity | Trigger |
+|---|---|---|
+| AR-IMPORT-001 | error | Import explicitly forbidden by CALM constraint |
+| AR-IMPORT-002 | error | Cross-boundary import not declared in CALM graph |
+| AR-IMPORT-003 | warning | Enforced import relationship not evidenced in diff |
+
+Supports 10 languages: Kotlin/Java, Python, TypeScript/JavaScript, Go, Swift, Ruby, C/C++, Rust, C#, Dart.
+
+---
+
+## Repository Structure
+
+```
+aws-backend/
+├── webhook_router/           # Entrypoint: normalize + dispatch webhooks
+├── fetch_pr_diff/            # Fetch PR diff and file list from SCM
+├── fetch_archrails_config/   # Fetch .archrails/config.yml, resolve bootstrap state
+├── bootstrap_governance/     # Auto-generate config.yml for new tenants
+├── process_calm_config/      # Parse + merge CALM, write to S3
+├── validate_architecture/    # Preflight checks + Bedrock LLM validation
+│   ├── core/
+│   │   ├── pattern.py                  # Path glob → node mapping
+│   │   ├── control_validator.py        # AR-CTRL-* rules
+│   │   ├── relationship_diff_validator.py  # AR-REL-003, AR-REL-004
+│   │   ├── preflight_imports.py        # AR-IMPORT-* rules (CALM-driven)
+│   │   ├── forbidding_imports.py       # AR-IMPORT-* rules (package-index-driven)
+│   │   ├── driver_patterns.py          # DB/queue/HTTP driver detection
+│   │   └── secret_scanner.py          # AR-DIFF-008 secret detection
+│   ├── use_cases/
+│   │   ├── system_prompt_use_case.py   # Bedrock system prompt builder
+│   │   ├── user_prompt_use_case.py     # Bedrock user prompt builder
+│   │   └── validation_use_case.py      # Bedrock orchestration + fallback
+│   └── test/                           # 210 unit tests
+├── publish_review_result/    # Post PR comment + inline annotations
+├── update_pr_status/         # Handle merge/close, promote S3 staging → live
+├── run_full_audit/           # On-demand repo coverage audit (dashboard API)
+└── shared/                   # Shared modules across all Lambdas
+    ├── aws/
+    │   ├── dynamo/            # DynamoDB helpers + record stores
+    │   ├── s3/                # S3 read/write helpers
+    │   └── secrets/           # Secrets Manager token resolution
+    ├── calm/
+    │   ├── archrails_config.py  # .archrails/config.yml parser + model
+    │   ├── mono/                # Monorepo merge logic
+    │   └── shared/              # CALM validators, errors, parsers
+    ├── http/                  # HTTP response helpers
+    ├── exception/             # Standardized error responses
+    ├── identifiers.py         # tenant_pk / repo_sk builders
+    └── storage_keys.py        # S3 path builders
+```
+
+---
+
+## Running Tests
+
+```bash
+# From repo root
+python3.11 -m pytest validate_architecture/test/test_calm_validator_edge_cases.py   # 65 tests
+python3.11 -m pytest validate_architecture/test/test_calm_enforcer_edge_cases.py    # 145 tests
+
+# Run both (validator file must come first)
+python3.11 -m pytest \
+  validate_architecture/test/test_calm_validator_edge_cases.py \
+  validate_architecture/test/test_calm_enforcer_edge_cases.py
+```
+
+---
+
+## Environment Variables
+
+| Variable | Lambda(s) | Description |
+|---|---|---|
+| `GITHUB_WEBHOOK_SECRET_ID` | WebhookRouter | Secrets Manager prefix for GitHub webhook secrets |
+| `GITLAB_WEBHOOK_SECRET_ID` | WebhookRouter, FetchPRDiff | Secrets Manager prefix for GitLab secrets |
+| `GITHUB_CI_WEBHOOK_SECRET_ID` | WebhookRouter | Secrets Manager prefix for GitHub CI secrets |
+| `GITHUB_TOKEN_SECRET_NAME` | FetchPRDiff, FetchArchRailsConfig | Secret key name for GitHub token |
+| `GITLAB_TOKEN_SECRET_NAME` | FetchPRDiff, FetchArchRailsConfig | Secret key name for GitLab token |
+| `GITLAB_TOKEN_BEARER` | FetchPRDiff | If `"true"`, use Bearer auth instead of PRIVATE-TOKEN |
+| `ARCHRAILS_REPO_LATEST_CONFIG` | BootstrapGovernance, FetchArchRailsConfig | DynamoDB table for repo configs |
+| `ARCHRAILS_TABLE` | CalmParser, ValidateArch | DynamoDB table for live tenant data |
+| `PR_VALIDATION_TABLE` | ValidateArch, UpdatePRStatus | DynamoDB table for PR validation records |
+| `TENANT_PROVISIONING_TABLE` | PublishReview | DynamoDB table for tenant provisioning |
+| `INLINE_MIN_SEVERITY` | PublishReview | Minimum severity for inline comments (default: `minor`) |
+| `MAX_INLINE_COMMENTS` | PublishReview | Max inline comments per PR (default: `50`) |
+| `USE_REVIEW_COMMENTS_API` | PublishReview | If `"true"`, batch inline+summary into single review |
+| `SCHEMA_VERSION` | ValidateArch | DynamoDB record schema version |
+
+---
+
+## License
+
+See [LICENSE](LICENSE).

archrails_mcp-0.3.0/archrails_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

archrails_mcp-0.3.0/archrails_mcp/_config.py

@@ -0,0 +1,107 @@
+"""Minimal archrails.yml schema + loader, inlined into the local CLI.
+
+The full config schema lives in `shared.calm.archrails_config` (server-
+side), but we don't ship `shared/` in the CLI wheel — it would leak
+validators, audit logic, and federation code. Architect-mode local
+tools (`bind_path`, `validate_architecture`) need *just enough* of the
+schema to read sources + mappings out of archrails.yml; that subset
+lives here.
+
+Kept tiny on purpose. If a field isn't accessed by `bind_path`,
+`validate_architecture`, or the local `graph_loader.load_graph`, it's
+not modelled here. Adding a field is cheap; bloating this with PR-time
+config knobs reverses the IP boundary we set up.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import yaml
+
+
+class ArchrailsConfigParseError(Exception):
+    """YAML syntax error or top-level shape error in archrails.yml."""
+
+
+@dataclass
+class MappingRule:
+    path: str
+    node: str
+
+
+@dataclass
+class MonorepoSource:
+    """One entry in governance.sources[] — maps to one CALM file."""
+    id: str
+    file: str
+    paths: list[str] = field(default_factory=list)
+
+
+@dataclass
+class MonorepoGovernanceConfig:
+    provider: str = "calm"
+    sources: list[MonorepoSource] = field(default_factory=list)
+
+
+@dataclass
+class MonorepoArchrailsConfig:
+    """Trimmed schema covering only the fields local architect-mode tools touch."""
+    version: int = 1
+    governance: MonorepoGovernanceConfig = field(default_factory=MonorepoGovernanceConfig)
+    mapping: list[MappingRule] = field(default_factory=list)
+
+
+def load_archrails_config(raw_yaml: str) -> MonorepoArchrailsConfig:
+    """Parse archrails.yml into the trimmed MonorepoArchrailsConfig.
+
+    Raises:
+        ArchrailsConfigParseError: YAML invalid or top-level not a mapping.
+    """
+    if not raw_yaml or not raw_yaml.strip():
+        raise ArchrailsConfigParseError("archrails.yml is empty")
+
+    try:
+        data = yaml.safe_load(raw_yaml)
+    except yaml.YAMLError as exc:
+        mark = getattr(exc, "problem_mark", None)
+        location = f" (line {mark.line + 1}, col {mark.column + 1})" if mark else ""
+        problem = getattr(exc, "problem", str(exc))
+        raise ArchrailsConfigParseError(
+            f"Invalid YAML in archrails.yml{location}: {problem}"
+        ) from exc
+
+    if not isinstance(data, dict):
+        raise ArchrailsConfigParseError(
+            "archrails.yml must be a YAML mapping at the top level"
+        )
+
+    gov_raw = data.get("governance") or {}
+    sources_raw = gov_raw.get("sources") or []
+    sources: list[MonorepoSource] = []
+    for s in sources_raw if isinstance(sources_raw, list) else []:
+        if not isinstance(s, dict):
+            continue
+        src_id = s.get("id") or ""
+        src_file = s.get("file") or ""
+        if not src_id or not src_file:
+            continue
+        sources.append(MonorepoSource(
+            id=src_id,
+            file=src_file,
+            paths=s.get("paths") or [],
+        ))
+
+    mapping: list[MappingRule] = []
+    for entry in (data.get("mapping") or []):
+        if isinstance(entry, dict) and "path" in entry and "node" in entry:
+            mapping.append(MappingRule(path=entry["path"], node=entry["node"]))
+
+    return MonorepoArchrailsConfig(
+        version=int(data.get("version", 1)),
+        governance=MonorepoGovernanceConfig(
+            provider=gov_raw.get("provider", "calm"),
+            sources=sources,
+        ),
+        mapping=mapping,
+    )

archrails_mcp-0.3.0/archrails_mcp/cli.py

@@ -0,0 +1,274 @@
+"""archrails CLI entry point.
+
+Usage:
+    archrails bootstrap                              # one-time setup for a new dev
+    archrails login                                  # cache credentials for cloud MCP
+    archrails logout                                 # clear cached credentials
+    archrails mcp start --repo /path/to/repo         # default code-mode server
+    archrails mcp start --repo . --mode architect    # architect mode (CALM-editing)
+    archrails arch init                              # drop FINOS Claude skill
+    archrails calm <subcommand>                      # wraps FINOS CALM CLI
+    archrails calm install                           # install pinned FINOS CALM CLI
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import sys
+from pathlib import Path
+
+# CRITICAL for MCP stdio: stdout is reserved for JSON-RPC. shared.logger
+# (and several other libraries) default to StreamHandler(sys.stdout),
+# which would corrupt the MCP framing. Patch StreamHandler so anything
+# that would target sys.stdout — or that defaults — lands on sys.stderr.
+# This must run before any module that creates loggers is imported.
+_orig_stream_handler_init = logging.StreamHandler.__init__
+
+
+def _stderr_default_init(self, stream=None):  # type: ignore[no-untyped-def]
+    if stream is None or stream is sys.stdout:
+        stream = sys.stderr
+    return _orig_stream_handler_init(self, stream)
+
+
+logging.StreamHandler.__init__ = _stderr_default_init  # type: ignore[assignment]
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="archrails",
+        description="ArchRails CLI — MCP server, FINOS CALM tooling, and developer auth.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    # bootstrap
+    boot = sub.add_parser(
+        "bootstrap",
+        help="One-time setup: install CALM CLI, sign in, wire IDE MCP config.",
+    )
+    boot.add_argument("--dashboard", default=None, help="Dashboard URL (default: env or built-in dev)")
+    boot.add_argument("--api-base", default=None, help="API Gateway base URL")
+    boot.add_argument("--mcp-url", default=None, help="Cloud MCP Function URL")
+    boot.add_argument("--force", action="store_true", help="Replace existing credentials")
+    boot.add_argument("--skip-login", action="store_true", help="Skip the sign-in step")
+    boot.add_argument(
+        "--no-calm-required",
+        action="store_true",
+        help="Continue bootstrap even if Node.js / CALM CLI install fails",
+    )
+
+    # login / logout
+    login = sub.add_parser("login", help="Sign in via the dashboard and cache credentials.")
+    login.add_argument("--dashboard", default=None)
+    login.add_argument("--api-base", default=None)
+    login.add_argument("--mcp-url", default=None)
+    login.add_argument(
+        "--paste",
+        action="store_true",
+        help="Use the manual paste flow instead of the browser callback.",
+    )
+    sub.add_parser("logout", help="Remove cached credentials.")
+
+    # demo — copies the sample-payments-platform to the user's machine
+    # and prints a refusal walk-through. No auth required.
+    demo = sub.add_parser(
+        "demo",
+        help=(
+            "Copy a tiny sample CALM architecture to your machine and "
+            "walk through what ArchRails does when an agent proposes a "
+            "forbidden change. No login required — kick the tires "
+            "before setting up your own repo."
+        ),
+    )
+    demo.add_argument(
+        "--dir",
+        default=None,
+        help="Where to copy the sample (default: ~/archrails-demo).",
+    )
+    demo.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite the destination if it already exists.",
+    )
+
+    # check — direct CLI verb for "validate my local diff"
+    check = sub.add_parser(
+        "check",
+        help=(
+            "Run the ArchRails validator suite against your local git diff. "
+            "Same brain as the merge gate — a clean response here means "
+            "the PR would pass; a blocked verdict means the merge will block."
+        ),
+    )
+    check.add_argument(
+        "--repo",
+        default=".",
+        help="Path to the workspace (default: current dir).",
+    )
+    check.add_argument(
+        "--against",
+        default="HEAD",
+        help=(
+            "Git ref to diff against. Default 'HEAD' captures uncommitted + "
+            "staged work. Use 'main' to compare working-tree vs main, or "
+            "'main..HEAD' for branch-only changes (closest to 'what would "
+            "land in a PR opened against main')."
+        ),
+    )
+    check.add_argument(
+        "--json",
+        action="store_true",
+        help=(
+            "Emit the full server response as JSON instead of a human-"
+            "readable report. Exit code is 0 iff allowed=true."
+        ),
+    )
+    check.add_argument(
+        "paths",
+        nargs="*",
+        help=(
+            "Optional git pathspecs to scope the diff (e.g. "
+            "'services/payment/**'). Useful for focusing on the file(s) "
+            "you just edited."
+        ),
+    )
+
+    # mcp start
+    mcp = sub.add_parser("mcp", help="MCP server commands.")
+    mcp_sub = mcp.add_subparsers(dest="mcp_cmd", required=True)
+    start = mcp_sub.add_parser("start", help="Run the MCP stdio server.")
+    start.add_argument(
+        "--repo",
+        default=".",
+        help="Path to the workspace repo (default: current directory).",
+    )
+    start.add_argument(
+        "--mode",
+        choices=["code", "architect"],
+        default="code",
+        help=(
+            "Server mode. `code` (default) — agent writes code, architecture "
+            "files are read-only. `architect` — agent may edit CALM files / "
+            "archrails.yml; mutation tools (validate_architecture, bind_path) "
+            "are exposed and the read-only prohibition is lifted. The two "
+            "modes are mutually exclusive — never run both in one session."
+        ),
+    )
+    start.add_argument(
+        "--repo-url",
+        default=None,
+        help=(
+            "Override the repo URL the cloud uses to pick a graph. By default "
+            "we read it from `git remote get-url origin` on --repo. Use this "
+            "when auto-detection picks the wrong remote (forks, mirrors, "
+            "multi-remote setups), when --repo doesn't have an `origin` "
+            "remote, or when you want to pin the URL in your IDE's MCP "
+            "config so it's immune to which folder Cursor inherits at "
+            "launch. Also overridable via the ARCHRAILS_REPO_URL env var."
+        ),
+    )
+
+    # arch — architecture-authoring helpers (architect-mode adjacent).
+    arch = sub.add_parser(
+        "arch",
+        help="Architecture authoring helpers (drops the FINOS Claude skill, etc.).",
+    )
+    arch_sub = arch.add_subparsers(dest="arch_cmd", required=True)
+    arch_init = arch_sub.add_parser(
+        "init",
+        help=(
+            "Drop the FINOS CALM Claude skill into this repo "
+            "(.claude/skills/calm/). Wraps `calm init-ai --provider claude`."
+        ),
+    )
+    arch_init.add_argument(
+        "--directory",
+        default=".",
+        help="Target directory (default: current working directory).",
+    )
+
+    # calm passthrough — argparse REMAINDER lets us forward arbitrary args
+    calm = sub.add_parser(
+        "calm",
+        help="Wraps the FINOS CALM CLI. `archrails calm install` installs it.",
+    )
+    calm.add_argument("calm_args", nargs=argparse.REMAINDER)
+
+    return parser
+
+
+def main() -> int:
+    # Special-case `archrails calm ...` so EVERYTHING after `calm` is
+    # passed through to the FINOS CALM CLI — including bare flags like
+    # `--version` that argparse would otherwise intercept.
+    if len(sys.argv) >= 2 and sys.argv[1] == "calm":
+        from archrails_mcp.cmd.calm import cmd_calm
+        return cmd_calm(sys.argv[2:])
+
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    if args.cmd == "mcp" and args.mcp_cmd == "start":
+        repo_path = Path(args.repo).resolve()
+        if not repo_path.is_dir():
+            print(f"[archrails] --repo not a directory: {repo_path}", file=sys.stderr)
+            return 2
+        # --repo-url override: explicit flag wins, then env var, then None
+        # (let server.py auto-detect via git remote).
+        import os as _os
+        repo_url_override = args.repo_url or _os.environ.get("ARCHRAILS_REPO_URL") or None
+        # Gate: unprovisioned machines cannot run the local MCP server.
+        # See archrails_mcp.credentials.require_credentials for the env-var
+        # escape hatch used by our own CI.
+        from archrails_mcp import credentials
+        try:
+            credentials.require_credentials()
+        except credentials.NotProvisioned as e:
+            print(str(e), file=sys.stderr)
+            return 2
+        from archrails_mcp.server import main_async
+        try:
+            asyncio.run(main_async(
+                repo_path,
+                mode=args.mode,
+                repo_url_override=repo_url_override,
+            ))
+        except KeyboardInterrupt:
+            return 0
+        return 0
+
+    if args.cmd == "arch" and args.arch_cmd == "init":
+        from archrails_mcp.cmd.arch import cmd_arch_init
+        return cmd_arch_init(args)
+
+    if args.cmd == "calm":
+        from archrails_mcp.cmd.calm import cmd_calm
+        return cmd_calm(args.calm_args or [])
+
+    if args.cmd == "login":
+        from archrails_mcp.cmd.login import cmd_login
+        return cmd_login(args)
+
+    if args.cmd == "logout":
+        from archrails_mcp.cmd.login import cmd_logout
+        return cmd_logout(args)
+
+    if args.cmd == "bootstrap":
+        from archrails_mcp.cmd.bootstrap import cmd_bootstrap
+        return cmd_bootstrap(args)
+
+    if args.cmd == "check":
+        from archrails_mcp.cmd.check import cmd_check
+        return cmd_check(args)
+
+    if args.cmd == "demo":
+        from archrails_mcp.cmd.demo import cmd_demo
+        return cmd_demo(args)
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())