monorepoly 0.2.0__tar.gz

monorepoly-0.2.0/LICENSE

@@ -0,0 +1,22 @@
+monorepoly license
+
+Copyright (c) 2026 Kimmo Parviainen-Jalanko. All rights reserved.
+
+1. Free use. You may install and run this software (the "Software") free of charge to index
+   and search repositories, and their issues, merge requests and discussions, that are
+   publicly accessible, such as open-source projects.
+
+2. Commercial use. Any other use requires a commercial license from the copyright holder, in
+   particular:
+   a. indexing or searching private or internal repositories, and
+   b. using the Software in, or to provide, a commercial product or service.
+   A commercial license is a license file issued by the copyright holder; the Software reads it
+   from MONOREPOLY_LICENSE. Ask for one through https://monorepoly.com.
+
+3. Restrictions. You may not remove, disable or circumvent the Software's license checks, and
+   you may not redistribute the Software, modified or not, except as part of using it under
+   section 1 or 2.
+
+4. No warranty. The Software is provided "as is", without warranty of any kind, express or
+   implied. In no event shall the copyright holder be liable for any claim, damages or other
+   liability arising from the Software or its use.

monorepoly-0.2.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: monorepoly
+Version: 0.2.0
+Summary: Org-wide code and activity index for LLM agents
+License-Expression: LicenseRef-Monorepoly
+License-File: LICENSE
+Requires-Dist: fire>=0.7.1
+Requires-Dist: rich>=15.0.0
+Requires-Dist: cryptography>=50.0.2 ; extra == 'indexer'
+Requires-Dist: google-genai>=2.28.0 ; extra == 'indexer'
+Requires-Dist: pymongo>=4.18.2 ; extra == 'indexer'
+Requires-Dist: python-gitlab>=8.6.0 ; extra == 'indexer'
+Requires-Dist: pyyaml>=6.0.3 ; extra == 'indexer'
+Requires-Dist: requests>=2.34.2 ; extra == 'indexer'
+Requires-Dist: tenacity>=9.1.4 ; extra == 'indexer'
+Requires-Dist: typesafe-sdk>=0.7.2 ; extra == 'indexer'
+Requires-Dist: google-genai>=2.28.0 ; extra == 'server'
+Requires-Dist: mcp>=2.2.0 ; extra == 'server'
+Requires-Dist: pymongo>=4.18.2 ; extra == 'server'
+Requires-Dist: python-gitlab>=8.6.0 ; extra == 'server'
+Requires-Dist: requests>=2.34.2 ; extra == 'server'
+Requires-Dist: typesafe-sdk>=0.7.2 ; extra == 'server'
+Requires-Python: >=3.14
+Provides-Extra: indexer
+Provides-Extra: server
+Description-Content-Type: text/markdown
+
+# monorepoly
+
+Org-wide index of code and engineering activity for LLM agents.
+
+## Install
+
+- Users of a hosted server: `uv tool install monorepoly` (or `pip install monorepoly`), then
+  `monorepoly setup --server_url <url> --client_id <id>`. Nothing else is installed.
+- Running the server yourself: `monorepoly[server]`; running the indexer: `monorepoly[indexer]`.
+  A command whose extra is missing says which one to install.
+- Images: the Dockerfile's `server` target runs `serve_http`, its `indexer` target (the
+  default) the indexing commands.
+
+## Setup
+
+1. `docker compose up -d` (Atlas Local, for tests and local runs)
+2. Set `GITLAB_GROUP_ID` (a group path or numeric id), `GITLAB_TOKEN`, `GITLAB_URL`,
+   `GOOGLE_CLOUD_PROJECT`, `MONGODB_DB`, `MONGODB_URI`, `TYPESAFE_API_KEY`
+3. `gcloud auth application-default login`
+
+## Use
+
+- Index every project in the group: `uv run monorepoly index_org`
+  (archived projects are skipped; add `--include_archived` to index them too)
+- Index one project's code, commits and branches:
+  `uv run monorepoly index_project group/project`
+- Sync one project's issues, merge requests and discussions:
+  `uv run monorepoly sync_activity group/project`
+- `--debug` skips every database write, but still makes the paid Vertex AI and Jev calls.
+- Set up Claude Code: `monorepoly setup` prompts for the settings, checks GitLab, MongoDB and
+  Google credentials, installs the skill and registers the server (`--debug` changes nothing
+  and prints the `claude mcp add` command with secrets masked)
+- Or register by hand with your own GitLab token, passing every setting with `-e` (see
+  Security model):
+
+  ```
+  claude mcp add monorepoly -e GITLAB_GROUP_ID=... -e GITLAB_TOKEN=... -e GITLAB_URL=... \
+    -e GOOGLE_CLOUD_PROJECT=... -e MONGODB_DB=... -e MONGODB_URI=... -e TYPESAFE_API_KEY=... \
+    -- uv run --directory <this repo> monorepoly serve
+  ```
+
+- Skill: `monorepoly install-skill` copies it to `~/.claude/skills/`; rerun after upgrading
+- Connect to a hosted server (see Self-host on Google Cloud):
+  `monorepoly setup --server_url <url> --client_id <GitLab OAuth application id>`; Claude Code
+  opens GitLab in the browser on first use
+
+## Index from CI
+
+The image runs the CLI; its entrypoint is the `monorepoly` command.
+
+```
+docker build --target indexer -t registry.gitlab.com/<group>/monorepoly:latest .
+docker push registry.gitlab.com/<group>/monorepoly:latest
+```
+
+The job authenticates to Vertex AI with Workload Identity Federation: GitLab issues the job an
+OIDC token, and GCP exchanges it for a service account. No key is stored anywhere.
+
+One-time GCP setup:
+
+1. Create a workload identity pool and an OIDC provider for `https://gitlab.com`, with the
+   attribute mapping `google.subject=assertion.sub,attribute.namespace_path=assertion.namespace_path`
+   and the attribute condition `assertion.namespace_path.startsWith('<group>')`, so only your
+   group's pipelines can use it.
+2. Grant a service account `roles/aiplatform.user`, and grant the pool's principals
+   `roles/iam.workloadIdentityUser` on that service account.
+3. Generate the credential config (it holds no secret):
+
+   ```
+   gcloud iam workload-identity-pools create-cred-config \
+     projects/<number>/locations/global/workloadIdentityPools/<pool>/providers/<provider> \
+     --service-account=<sa>@<project>.iam.gserviceaccount.com \
+     --credential-source-file=/tmp/gcp-id-token --output-file=gcp-credentials.json
+   ```
+
+   and store its content in the CI variable `GCP_CREDENTIAL_CONFIG`.
+
+CI variables (masked): `GITLAB_GROUP_ID`, `GITLAB_TOKEN` (a group access token with
+`read_api` and `read_repository`), `GITLAB_URL`, `GOOGLE_CLOUD_PROJECT`, `MONGODB_DB`,
+`MONGODB_URI`, `TYPESAFE_API_KEY`.
+
+```yaml
+monorepoly:
+  image:
+    name: registry.gitlab.com/<group>/monorepoly:latest
+    entrypoint: [""]
+  id_tokens:
+    GCP_ID_TOKEN:
+      aud: https://iam.googleapis.com/projects/<number>/locations/global/workloadIdentityPools/<pool>/providers/<provider>
+  variables:
+    GOOGLE_APPLICATION_CREDENTIALS: /tmp/gcp-credentials.json
+  script:
+    - echo "$GCP_ID_TOKEN" > /tmp/gcp-id-token
+    - echo "$GCP_CREDENTIAL_CONFIG" > "$GOOGLE_APPLICATION_CREDENTIALS"
+    - monorepoly index_project "$CI_PROJECT_PATH"
+    - monorepoly sync_activity "$CI_PROJECT_PATH"
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```
+
+A CI runner keeps no clone cache, so every run clones the repository again; only commits new
+since the last run reach Jev and Vertex AI.
+
+## Self-host on Google Cloud
+
+`deploy/` is a Pulumi program that runs the MCP server as a Cloud Run service and `index_org` as
+a Cloud Run job, with every credential in Secret Manager. Engineers connect over HTTP and log in
+with GitLab; their laptops hold no MongoDB, Vertex AI or TypeSafe credentials.
+
+You need: a GCP project, `gcloud auth application-default login`, Pulumi and an Atlas cluster.
+The images come from ghcr.io, built by GitHub Actions on every push to `master` and tagged with
+the commit; a deploy runs the images of the checkout's `HEAD`, so push and wait for the
+`images` workflow before `pulumi up`.
+
+1. In GitLab, create an OAuth application (group or instance level): scope `read_api`,
+   redirect URI `http://localhost:41593/callback`, **Confidential** unchecked (Claude Code uses
+   PKCE, so there is no secret). Its application id is public; you hand it to users.
+2. In Atlas, create two database users for the index database: read-only for the server,
+   read-write for the indexer.
+3. Create a group access token with `read_api` and `read_repository` for the indexer.
+4. Configure and deploy, keeping the state in your own project:
+
+   ```
+   cd deploy
+   pulumi login gs://<state bucket>
+   pulumi stack init prod
+   pulumi config set gcp:project <project>
+   pulumi config set gcp:region <region>
+   pulumi config set gitlabGroupId <group path or id>
+   pulumi config set mongodbDb <database>
+   pulumi config set --secret gitlabToken <group access token>
+   pulumi config set --secret mongodbUriReadonly <read-only URI>
+   pulumi config set --secret mongodbUriReadwrite <read-write URI>
+   pulumi config set --secret typesafeApiKey <key>
+   pulumi up
+   ```
+
+   Optional: `gitlabUrl` (default `https://gitlab.com`), `schedule` (default hourly,
+   `0 * * * *`), `indexerTimeout` (default `3300s`; keep it below the schedule's interval, so runs
+   never overlap), `indexerMemory` (default `4Gi`; every run clones all repositories into memory),
+   `license` (see License), `egressSubnetwork` (sends all traffic through that subnet, e.g. one
+   whose Cloud NAT has a static IP on the Atlas IP access list), `schedulerRegion` (default
+   `gcp:region`; Cloud Scheduler is missing from some regions, e.g. `europe-north1`),
+   `imageTag` (default the checkout's commit), `imageRepository` (default `kimvais/monorepoly`).
+5. Run the first full index by hand; it can take hours:
+   `gcloud run jobs execute monorepoly-index --region <region> --task-timeout=24h --wait`
+6. Start the schedule: `pulumi config set scheduleEnabled true && pulumi up`
+7. Give users the `setup_command` output; set `oauthClientId` to your OAuth application id to
+   have it filled in.
+
+Every user sees only what their own GitLab account can see, as with a local server.
+
+## License
+
+Free for public repositories and open-source projects; private repositories and commercial
+use need a commercial license (terms: [LICENSE](LICENSE)).
+
+Public projects are indexed without a license. Private and internal projects need a license
+file covering their group; without one the indexer skips them and stores nothing about them,
+not even their names.
+
+Give the indexer the file's content in `MONOREPOLY_LICENSE`. On Google Cloud:
+`pulumi config set --secret license -- "$(cat monorepoly.license)" && pulumi up`.
+
+A license file is TOML followed by an SSH signature over exactly the bytes above it. To issue
+one, write the payload, with `key` set to the fingerprint `ssh-keygen -l -f <key>.pub` prints:
+
+```toml
+licensee = "Acme Oy"
+gitlab_url = "https://gitlab.com"
+groups = ["acme"]
+expires = 2027-10-16
+key = "SHA256:L2Z9F/e49TkoYH8+dWjsfpjJvuyJgDnkFLOOVlJDtpQ"
+```
+
+then sign it with a key whose `.pub` file is in `monorepoly/trusted_keys/`, and append the
+signature:
+
+```
+ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n monorepoly-license acme.toml
+cat acme.toml acme.toml.sig > monorepoly.license
+```
+
+The file must keep LF line endings: any changed byte breaks the signature. `groups` are full
+paths and include their subgroups; `expires` is the last valid day.
+
+## Security model
+
+- The server filters every query by what your GitLab token can see: projects, per-feature access
+  (repository, merge requests, issues) and confidential items. This protects against accidental
+  exposure, not against anyone holding `MONGODB_URI`: the database holds the whole group's index,
+  and the URI reads all of it directly.
+- Give the server a read-only Atlas database user; only the indexer needs write access.
+- The hosted server is public at the network level on purpose: it checks every request's GitLab
+  token with GitLab, and accepts any of the user's tokens with `read_api`, which already reads
+  everything the index would show them.
+- Distribute the server settings only to people entitled to read the whole group.
+- Register the settings with `claude mcp add -e KEY=VALUE ...` rather than in your shell profile,
+  so an agent's shell commands cannot read them.
+
+## Test
+
+`uv run pytest` (needs Atlas Local). Live checks: `uv run pytest -m live`.

monorepoly-0.2.0/README.md

@@ -0,0 +1,203 @@
+# monorepoly
+
+Org-wide index of code and engineering activity for LLM agents.
+
+## Install
+
+- Users of a hosted server: `uv tool install monorepoly` (or `pip install monorepoly`), then
+  `monorepoly setup --server_url <url> --client_id <id>`. Nothing else is installed.
+- Running the server yourself: `monorepoly[server]`; running the indexer: `monorepoly[indexer]`.
+  A command whose extra is missing says which one to install.
+- Images: the Dockerfile's `server` target runs `serve_http`, its `indexer` target (the
+  default) the indexing commands.
+
+## Setup
+
+1. `docker compose up -d` (Atlas Local, for tests and local runs)
+2. Set `GITLAB_GROUP_ID` (a group path or numeric id), `GITLAB_TOKEN`, `GITLAB_URL`,
+   `GOOGLE_CLOUD_PROJECT`, `MONGODB_DB`, `MONGODB_URI`, `TYPESAFE_API_KEY`
+3. `gcloud auth application-default login`
+
+## Use
+
+- Index every project in the group: `uv run monorepoly index_org`
+  (archived projects are skipped; add `--include_archived` to index them too)
+- Index one project's code, commits and branches:
+  `uv run monorepoly index_project group/project`
+- Sync one project's issues, merge requests and discussions:
+  `uv run monorepoly sync_activity group/project`
+- `--debug` skips every database write, but still makes the paid Vertex AI and Jev calls.
+- Set up Claude Code: `monorepoly setup` prompts for the settings, checks GitLab, MongoDB and
+  Google credentials, installs the skill and registers the server (`--debug` changes nothing
+  and prints the `claude mcp add` command with secrets masked)
+- Or register by hand with your own GitLab token, passing every setting with `-e` (see
+  Security model):
+
+  ```
+  claude mcp add monorepoly -e GITLAB_GROUP_ID=... -e GITLAB_TOKEN=... -e GITLAB_URL=... \
+    -e GOOGLE_CLOUD_PROJECT=... -e MONGODB_DB=... -e MONGODB_URI=... -e TYPESAFE_API_KEY=... \
+    -- uv run --directory <this repo> monorepoly serve
+  ```
+
+- Skill: `monorepoly install-skill` copies it to `~/.claude/skills/`; rerun after upgrading
+- Connect to a hosted server (see Self-host on Google Cloud):
+  `monorepoly setup --server_url <url> --client_id <GitLab OAuth application id>`; Claude Code
+  opens GitLab in the browser on first use
+
+## Index from CI
+
+The image runs the CLI; its entrypoint is the `monorepoly` command.
+
+```
+docker build --target indexer -t registry.gitlab.com/<group>/monorepoly:latest .
+docker push registry.gitlab.com/<group>/monorepoly:latest
+```
+
+The job authenticates to Vertex AI with Workload Identity Federation: GitLab issues the job an
+OIDC token, and GCP exchanges it for a service account. No key is stored anywhere.
+
+One-time GCP setup:
+
+1. Create a workload identity pool and an OIDC provider for `https://gitlab.com`, with the
+   attribute mapping `google.subject=assertion.sub,attribute.namespace_path=assertion.namespace_path`
+   and the attribute condition `assertion.namespace_path.startsWith('<group>')`, so only your
+   group's pipelines can use it.
+2. Grant a service account `roles/aiplatform.user`, and grant the pool's principals
+   `roles/iam.workloadIdentityUser` on that service account.
+3. Generate the credential config (it holds no secret):
+
+   ```
+   gcloud iam workload-identity-pools create-cred-config \
+     projects/<number>/locations/global/workloadIdentityPools/<pool>/providers/<provider> \
+     --service-account=<sa>@<project>.iam.gserviceaccount.com \
+     --credential-source-file=/tmp/gcp-id-token --output-file=gcp-credentials.json
+   ```
+
+   and store its content in the CI variable `GCP_CREDENTIAL_CONFIG`.
+
+CI variables (masked): `GITLAB_GROUP_ID`, `GITLAB_TOKEN` (a group access token with
+`read_api` and `read_repository`), `GITLAB_URL`, `GOOGLE_CLOUD_PROJECT`, `MONGODB_DB`,
+`MONGODB_URI`, `TYPESAFE_API_KEY`.
+
+```yaml
+monorepoly:
+  image:
+    name: registry.gitlab.com/<group>/monorepoly:latest
+    entrypoint: [""]
+  id_tokens:
+    GCP_ID_TOKEN:
+      aud: https://iam.googleapis.com/projects/<number>/locations/global/workloadIdentityPools/<pool>/providers/<provider>
+  variables:
+    GOOGLE_APPLICATION_CREDENTIALS: /tmp/gcp-credentials.json
+  script:
+    - echo "$GCP_ID_TOKEN" > /tmp/gcp-id-token
+    - echo "$GCP_CREDENTIAL_CONFIG" > "$GOOGLE_APPLICATION_CREDENTIALS"
+    - monorepoly index_project "$CI_PROJECT_PATH"
+    - monorepoly sync_activity "$CI_PROJECT_PATH"
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```
+
+A CI runner keeps no clone cache, so every run clones the repository again; only commits new
+since the last run reach Jev and Vertex AI.
+
+## Self-host on Google Cloud
+
+`deploy/` is a Pulumi program that runs the MCP server as a Cloud Run service and `index_org` as
+a Cloud Run job, with every credential in Secret Manager. Engineers connect over HTTP and log in
+with GitLab; their laptops hold no MongoDB, Vertex AI or TypeSafe credentials.
+
+You need: a GCP project, `gcloud auth application-default login`, Pulumi and an Atlas cluster.
+The images come from ghcr.io, built by GitHub Actions on every push to `master` and tagged with
+the commit; a deploy runs the images of the checkout's `HEAD`, so push and wait for the
+`images` workflow before `pulumi up`.
+
+1. In GitLab, create an OAuth application (group or instance level): scope `read_api`,
+   redirect URI `http://localhost:41593/callback`, **Confidential** unchecked (Claude Code uses
+   PKCE, so there is no secret). Its application id is public; you hand it to users.
+2. In Atlas, create two database users for the index database: read-only for the server,
+   read-write for the indexer.
+3. Create a group access token with `read_api` and `read_repository` for the indexer.
+4. Configure and deploy, keeping the state in your own project:
+
+   ```
+   cd deploy
+   pulumi login gs://<state bucket>
+   pulumi stack init prod
+   pulumi config set gcp:project <project>
+   pulumi config set gcp:region <region>
+   pulumi config set gitlabGroupId <group path or id>
+   pulumi config set mongodbDb <database>
+   pulumi config set --secret gitlabToken <group access token>
+   pulumi config set --secret mongodbUriReadonly <read-only URI>
+   pulumi config set --secret mongodbUriReadwrite <read-write URI>
+   pulumi config set --secret typesafeApiKey <key>
+   pulumi up
+   ```
+
+   Optional: `gitlabUrl` (default `https://gitlab.com`), `schedule` (default hourly,
+   `0 * * * *`), `indexerTimeout` (default `3300s`; keep it below the schedule's interval, so runs
+   never overlap), `indexerMemory` (default `4Gi`; every run clones all repositories into memory),
+   `license` (see License), `egressSubnetwork` (sends all traffic through that subnet, e.g. one
+   whose Cloud NAT has a static IP on the Atlas IP access list), `schedulerRegion` (default
+   `gcp:region`; Cloud Scheduler is missing from some regions, e.g. `europe-north1`),
+   `imageTag` (default the checkout's commit), `imageRepository` (default `kimvais/monorepoly`).
+5. Run the first full index by hand; it can take hours:
+   `gcloud run jobs execute monorepoly-index --region <region> --task-timeout=24h --wait`
+6. Start the schedule: `pulumi config set scheduleEnabled true && pulumi up`
+7. Give users the `setup_command` output; set `oauthClientId` to your OAuth application id to
+   have it filled in.
+
+Every user sees only what their own GitLab account can see, as with a local server.
+
+## License
+
+Free for public repositories and open-source projects; private repositories and commercial
+use need a commercial license (terms: [LICENSE](LICENSE)).
+
+Public projects are indexed without a license. Private and internal projects need a license
+file covering their group; without one the indexer skips them and stores nothing about them,
+not even their names.
+
+Give the indexer the file's content in `MONOREPOLY_LICENSE`. On Google Cloud:
+`pulumi config set --secret license -- "$(cat monorepoly.license)" && pulumi up`.
+
+A license file is TOML followed by an SSH signature over exactly the bytes above it. To issue
+one, write the payload, with `key` set to the fingerprint `ssh-keygen -l -f <key>.pub` prints:
+
+```toml
+licensee = "Acme Oy"
+gitlab_url = "https://gitlab.com"
+groups = ["acme"]
+expires = 2027-10-16
+key = "SHA256:L2Z9F/e49TkoYH8+dWjsfpjJvuyJgDnkFLOOVlJDtpQ"
+```
+
+then sign it with a key whose `.pub` file is in `monorepoly/trusted_keys/`, and append the
+signature:
+
+```
+ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n monorepoly-license acme.toml
+cat acme.toml acme.toml.sig > monorepoly.license
+```
+
+The file must keep LF line endings: any changed byte breaks the signature. `groups` are full
+paths and include their subgroups; `expires` is the last valid day.
+
+## Security model
+
+- The server filters every query by what your GitLab token can see: projects, per-feature access
+  (repository, merge requests, issues) and confidential items. This protects against accidental
+  exposure, not against anyone holding `MONGODB_URI`: the database holds the whole group's index,
+  and the URI reads all of it directly.
+- Give the server a read-only Atlas database user; only the indexer needs write access.
+- The hosted server is public at the network level on purpose: it checks every request's GitLab
+  token with GitLab, and accepts any of the user's tokens with `read_api`, which already reads
+  everything the index would show them.
+- Distribute the server settings only to people entitled to read the whole group.
+- Register the settings with `claude mcp add -e KEY=VALUE ...` rather than in your shell profile,
+  so an agent's shell commands cannot read them.
+
+## Test
+
+`uv run pytest` (needs Atlas Local). Live checks: `uv run pytest -m live`.

monorepoly-0.2.0/monorepoly/__init__.py

@@ -0,0 +1 @@
+"""Org-wide code and activity index for LLM agents."""

monorepoly-0.2.0/monorepoly/__main__.py

@@ -0,0 +1,161 @@
+"""Command line entry point: `monorepoly <command> [--debug]`."""
+
+import functools
+import importlib
+import logging
+import os
+import re
+from pathlib import Path
+from types import ModuleType
+from typing import TYPE_CHECKING
+
+from monorepoly import config, skill, wizard
+from monorepoly.exceptions import MonorepolyConfigError
+
+if TYPE_CHECKING:
+    from monorepoly.indexer import IndexContext
+
+_LOGGER = logging.getLogger(__name__)
+
+_CACHE_DIR = Path.home() / '.cache' / 'monorepoly'
+_DEFAULT_PORT = '8080'
+_BACKTICKED = re.compile(r'`([^`]*)`')
+_FALSE_WORDS = frozenset({'0', 'false', 'no'})
+_TRUE_WORDS = frozenset({'1', 'true', 'yes'})
+
+
+class _BacktickMarkupFormatter(logging.Formatter):
+    """Renders backticked log values as highlighted rich markup in the terminal."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        from rich.markup import escape
+
+        # Escape first, so values cannot inject markup; escaping never touches backticks.
+        return _BACKTICKED.sub(r'[bold cyan]\1[/]', escape(super().format(record)))
+
+
+def _parse_flag(value: object) -> bool:
+    """Returns `value` as a bool, raising on anything but a bool or a known true/false word."""
+    # Fire turns `--flag=false` into the truthy string 'false'; only 'False' becomes a bool.
+    if isinstance(value, bool):
+        return value
+    word = value.lower() if isinstance(value, str) else None
+    if word in _TRUE_WORDS:
+        return True
+    if word in _FALSE_WORDS:
+        return False
+    raise MonorepolyConfigError(f"Expected a boolean flag value, got '{value}'!")
+
+
+class _Commands:
+    """Indexes the GitLab group and serves the index to agents."""
+
+    def __init__(self, debug: bool = False) -> None:
+        self._debug = debug
+
+    @functools.cached_property
+    def _settings(self) -> config.Settings:
+        # Lazy, so `install_skill` works before the indexer is configured.
+        return config.load_settings()
+
+    def install_skill(self, skills_dir: str = str(skill.SKILLS_DIR)) -> None:
+        """Installs the bundled Claude Code skill, replacing an older copy."""
+        skill.install_skill(dry_run=self._debug, skills_dir=Path(skills_dir))
+
+    def setup(self, server_url: str = '', client_id: str = '') -> None:
+        """Registers the server in Claude Code: hosted with `--server_url`, else prompts locally."""
+        from rich.console import Console
+
+        if server_url:
+            wizard.run_hosted(
+                client_id=client_id, console=Console(), dry_run=self._debug, server_url=server_url
+            )
+            return
+        # A local setup checks MongoDB, GitLab and Google credentials, and registers `serve`.
+        _load('mcp_server', extra='server')
+        wizard.run(console=Console(), dry_run=self._debug)
+
+    def index_org(self, include_archived: bool | str = False) -> None:
+        """Indexes every project in GITLAB_GROUP_ID, archived ones only if asked."""
+        indexer = _load('indexer', extra='indexer')
+        indexer.index_org(
+            ctx=self._index_context(),
+            group_id=self._settings.gitlab_group_id,
+            include_archived=_parse_flag(include_archived),
+        )
+
+    def index_project(self, path: str) -> None:
+        """Indexes the code and history of one `group/project`."""
+        indexer = _load('indexer', extra='indexer')
+        ctx = self._index_context()
+        ctx.store.ensure_indexes()
+        indexer.index_project(ctx=ctx, project=ctx.gitlab.project(path))
+
+    def sync_activity(self, path: str) -> None:
+        """Syncs issues, merge requests and discussions of one `group/project`."""
+        indexer = _load('indexer', extra='indexer')
+        ctx = self._index_context()
+        ctx.store.ensure_indexes()
+        indexer.sync_activity(ctx=ctx, project=ctx.gitlab.project(path))
+
+    def serve(self) -> None:
+        """Runs the MCP server on stdio."""
+        _load('mcp_server', extra='server').serve(self._settings)
+
+    def serve_http(self) -> None:
+        """Runs the hosted MCP server on HTTP for GitLab OAuth users, on port PORT."""
+        # Cloud Run tells the container its port in PORT.
+        port = int(os.environ.get('PORT', _DEFAULT_PORT))
+        hosted = _load('hosted', extra='server')
+        hosted.serve_http(port=port, settings=config.load_server_settings())
+
+    def _index_context(self) -> IndexContext:
+        settings = self._settings
+        modules = ('embed', 'gitlab', 'indexer', 'judge', 'licensing', 'store')
+        embed, gitlab, indexer, judge, licensing, store = (
+            _load(name, extra='indexer') for name in modules
+        )
+        return indexer.IndexContext(
+            cache_dir=_CACHE_DIR,
+            embedder=embed.make_embedder(project=settings.google_cloud_project),
+            gitlab=gitlab.make_gitlab(token=settings.gitlab_token, url=settings.gitlab_url),
+            gitlab_token=settings.gitlab_token,
+            judge=judge.make_judge(),
+            license=licensing.from_environ(os.environ),
+            # `debug` is a dry run: everything is computed, nothing is written.
+            store=store.Store(
+                db=store.connect(db=settings.mongodb_db, uri=settings.mongodb_uri),
+                dry_run=self._debug,
+            ),
+        )
+
+
+def _load(module: str, *, extra: str) -> ModuleType:
+    """Returns `monorepoly.<module>`, or says which extra installs what it is missing."""
+    try:
+        return importlib.import_module(f'monorepoly.{module}')
+    except ModuleNotFoundError as err:
+        if (err.name or '').startswith('monorepoly'):
+            raise
+        raise MonorepolyConfigError(
+            f'`{err.name}` is missing, install the `{extra}` extra:'
+            f" pip install 'monorepoly[{extra}]'"
+        ) from err
+
+
+def main() -> None:
+    import fire
+    from rich.console import Console
+    from rich.logging import RichHandler
+
+    # stdout carries the MCP protocol in `serve`, so all logging goes to stderr.
+    handler = RichHandler(console=Console(stderr=True), markup=True)
+    handler.setFormatter(_BacktickMarkupFormatter())
+    logging.basicConfig(handlers=[handler], level=logging.WARNING)
+    # Only our own progress at INFO: the SDKs and their HTTP clients log every request there.
+    logging.getLogger('monorepoly').setLevel(logging.INFO)
+    fire.Fire(_Commands)
+
+
+if __name__ == '__main__':
+    main()