project-hub 0.1.0__tar.gz

project_hub-0.1.0/.gitlab-ci.yml

@@ -0,0 +1,24 @@
+image: python:3.12-slim
+
+stages:
+  - test
+  - publish
+
+test:
+  stage: test
+  before_script:
+    - apt-get update -qq && apt-get install -y -qq git >/dev/null
+    - pip install uv
+  script:
+    - uv sync
+    - uv run pytest tests/ -v
+
+publish:
+  stage: publish
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+/
+  before_script:
+    - pip install uv
+  script:
+    - uv build
+    - uv publish --token $PYPI_TOKEN

project_hub-0.1.0/CLAUDE.md

@@ -0,0 +1,118 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What is project-hub
+
+Multi-repo workspace manager that unifies local git state and GitLab forge data (MRs, pipelines, vulnerabilities) into a single MCP server + web dashboard. Designed for engineers managing many repos on GitLab from a single parent directory.
+
+Single Python process, dual interfaces: MCP (stdio for Claude Code) + HTTP (FastAPI/htmx dashboard). Background asyncio task refreshes git+forge data on a TTL cycle, diffs with SQLite cache to generate events.
+
+## Build & Run
+
+```bash
+uv sync                          # install deps
+uv run project-hub --help        # CLI help
+uv run project-hub               # standalone dashboard (opens browser)
+uv run project-hub --mcp         # MCP mode (stdio, embeds webui)
+uv run project-hub init          # bootstrap .project-hub/ workspace
+uv run project-hub auth login <instance>  # store PAT
+uv run project-hub auth status
+uv run project-hub exclude <repo>
+uv run project-hub include <repo>
+uv run project-hub sync-now      # force immediate refresh
+```
+
+## Testing
+
+```bash
+uv run pytest tests/ -v                    # full suite
+uv run pytest tests/test_events.py -v      # single file
+uv run pytest tests/test_cache.py -k "test_store_mrs" -v  # single test
+```
+
+`asyncio_mode = "auto"` is set in pyproject.toml — async tests run without explicit markers.
+
+## Architecture
+
+```
+project_hub/
+  cli.py                   # Click entry points (standalone / --mcp / auth / init / exclude / include)
+  core/
+    workspace.py           # Workspace orchestrator: start → discover → refresh loop → stop
+                           # Also: WorkspaceState enum + detect_state() for dormancy
+    cache.py               # SQLite (WAL mode, aiosqlite) — MRs, pipelines, vulns, events
+    config.py              # YAML config loading with defaults
+    discovery.py           # Scan CWD children for .git/, parse remotes, classify forges
+    models.py              # All dataclasses: Repo, MR, Pipeline, Vulnerability, Event, etc.
+    events.py              # Diff old vs new state → Event list + filter_events (mine/all/none)
+  gitlab/
+    client.py              # python-gitlab + gql wrapper (one instance per forge host)
+    auth.py                # PAT resolution: auth.json → GITLAB_TOKEN env → python-gitlab.cfg
+  git/
+    ops.py                 # fetch, status, pull_safe (conflict detection via git merge-tree)
+  mcp/
+    server.py              # FastMCP server: lifespan, tools, resources, notifications
+  web/
+    app.py                 # FastAPI app factory, routes, htmx fragments
+    templates/             # Jinja2: dashboard, MRs, vulns, pipelines, events
+    static/                # CSS + vendored htmx.min.js
+```
+
+### Key design decisions
+
+- **Core API is framework-agnostic.** `workspace.py`, `cache.py`, `events.py` have zero MCP/FastAPI imports. Both interfaces are thin adapters.
+- **stdout reserved for MCP protocol.** All logging goes to stderr (`logging.basicConfig(stream=sys.stderr)`). No transitive dependency may write to stdout.
+- **python-gitlab is synchronous.** All forge calls wrapped with `asyncio.to_thread()` and bounded by a semaphore (default 10 concurrent).
+- **Conflict detection is non-destructive.** Uses `git merge-tree --write-tree` (Git 2.38+ required) — in-memory merge, no worktree mutations.
+- **Event persistence.** Events stored in SQLite with `seen` boolean, survive across sessions. `AUTH_EXPIRED` events always bypass watch filters.
+
+### Dormancy (4 states)
+
+| Condition | State | MCP behavior |
+|---|---|---|
+| `.no-project-hub` in CWD | Disabled (opt-out) | Zero tools |
+| `.project-hub/` in CWD | Active | Full tools + refresh |
+| `.project-hub/` in parent only | Disabled (sub-repo) | Zero tools |
+| Neither | Dormant | Only `init` tool |
+
+`.no-project-hub` always wins. After `init`, the server sends `send_tool_list_changed()` so the client re-fetches tools.
+
+### Refresh cycle (Workspace._do_refresh)
+
+1. `git fetch --all` on all repos (parallel subprocess)
+2. Fetch MRs, pipelines, vulns per forge repo (parallel, semaphore-bounded)
+3. Diff new state against cache → generate events
+4. Filter events by `watch` config (mine/all/none)
+5. Atomic write to cache + emit MCP resource notifications
+
+### Workspace layout
+
+```
+.project-hub/
+  config.yaml      # auto-generated on init
+  cache.db         # SQLite (created on first refresh)
+  workspace.md     # manual business notes
+```
+
+Auth tokens: `~/.config/project-hub/auth.json` (global, keyed by forge host).
+
+## MCP tools
+
+`init`, `configure_forge`, `list_repos`, `repo_status`, `fetch_all`, `pull_safe`, `list_mrs`, `list_pipelines`, `get_pipeline_jobs`, `get_vulnerabilities`, `acknowledge_alerts`, `auth_status`, `auth_login`
+
+All tools accepting `repo?` use the **directory name** as identifier (e.g. `pa-services-gateway`).
+
+## MCP resources
+
+`workspace://topology`, `workspace://status`, `workspace://alerts`, `workspace://notes`, `workspace://dashboard`
+
+## Web UI routes
+
+Full pages: `/`, `/mrs`, `/vulns`, `/pipelines`, `/events`
+Fragments (htmx): `/fragment/{dashboard,mrs,vulns,pipelines,events}`
+Actions: `POST /action/fetch`, `POST /action/pull`, `POST /action/dismiss-event/{id}`
+
+## V1 scope boundaries
+
+GitLab only (no GitHub/Forgejo). Single workspace. PAT auth only. No MR actions (approve/merge/comment). No desktop notifications. V1.1 planned: DB maintenance, OAuth device flow, multi-workspace.

project_hub-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

project_hub-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: project-hub
+Version: 0.1.0
+Summary: Multi-repo workspace manager with MCP server + web dashboard
+Project-URL: Repository, https://gitlab.com/b.rajaut/project-hub
+Author-email: Baptiste Rajaut <baptiste@rajaut.fr>
+License-Expression: Unlicense
+License-File: LICENSE
+Keywords: dashboard,git,gitlab,mcp,workspace
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: click>=8.1
+Requires-Dist: fastapi>=0.115
+Requires-Dist: gql[requests]>=3.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: mcp<2,>=1.25
+Requires-Dist: python-gitlab>=8.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: uvicorn[standard]>=0.30
+Description-Content-Type: text/markdown
+
+# project-hub
+
+Multi-repo workspace manager that unifies local git state and GitLab forge data (MRs, pipelines, vulnerabilities) into a single **MCP server + web dashboard**.
+
+Designed for engineers managing many repos under one parent directory.
+
+## Features
+
+- **Unified view** of git status, merge requests, pipelines, and vulnerabilities across all repos
+- **MCP server** (stdio) for Claude Code integration — ask "fix all vulns" and the agent has everything it needs
+- **Web dashboard** (htmx) with real-time sync, sortable tables, persistent filters, event notifications
+- **Smart defaults** — MCP returns only actionable vulns (high/critical + detected) with scanner solutions
+- **Non-destructive** — conflict detection via `git merge-tree`, no worktree mutations
+- **Background refresh** — async TTL-based cycle, diffs against SQLite cache to generate events
+
+## Quick start
+
+```bash
+# Install
+uvx project-hub --help
+
+# Or from source
+uv sync
+uv run project-hub --help
+```
+
+### Bootstrap a workspace
+
+```bash
+cd ~/Projects                    # parent dir containing your repos
+project-hub init                 # creates .project-hub/
+project-hub auth login gitlab.com  # store your PAT
+project-hub                      # launch dashboard (opens browser)
+```
+
+### Use as MCP server (Claude Code)
+
+```bash
+claude mcp add project-hub -- uvx project-hub --mcp
+```
+
+Then in Claude Code, the agent can call tools like `list_repos`, `get_vulnerabilities`, `pull_safe`, etc.
+
+## MCP tools
+
+| Tool | Description |
+|------|-------------|
+| `init` | Bootstrap `.project-hub/` workspace |
+| `list_repos` | List discovered repos with forge info |
+| `repo_status` | Git status (branch, ahead/behind, dirty) |
+| `fetch_all` | Trigger full refresh cycle |
+| `pull_safe` | Pull with conflict detection |
+| `list_mrs` | Merge requests (substring repo filter) |
+| `list_pipelines` | Pipelines (substring repo filter) |
+| `get_vulnerabilities` | Vulns — defaults to high/critical + detected, includes solutions |
+| `get_pipeline_jobs` | Jobs for a specific pipeline |
+| `acknowledge_alerts` | Mark events as seen |
+| `auth_status` | Check forge authentication |
+| `auth_login` | Store PAT for a forge instance |
+| `configure_forge` | Configure forge host mapping |
+
+## Web dashboard
+
+| Route | Description |
+|-------|-------------|
+| `/` | Dashboard with repo cards, events panel |
+| `/mrs` | Merge requests table (mine/all filter) |
+| `/pipelines` | Pipelines table (failed only filter) |
+| `/vulns` | Vulnerabilities table (severity + state filters) |
+| `/settings` | Exclude/include repos, rescan workspace |
+
+All filters and table sort are persisted in localStorage.
+
+## Architecture
+
+Single Python process, dual interfaces: MCP (stdio) + HTTP (FastAPI/htmx). Background asyncio task refreshes git+forge data on a TTL cycle, diffs with SQLite cache to generate events.
+
+```
+project_hub/
+  cli.py              # Click entry points
+  core/
+    workspace.py       # Orchestrator: discover -> refresh loop -> stop
+    cache.py           # SQLite (WAL mode, aiosqlite)
+    config.py          # YAML config with defaults
+    discovery.py       # Scan for .git/ repos, classify forges
+    models.py          # Dataclasses: Repo, MR, Pipeline, Vulnerability, Event
+    events.py          # Diff old vs new state -> Event list
+  gitlab/
+    client.py          # python-gitlab + GraphQL (vulnerabilities)
+    auth.py            # PAT resolution chain
+  git/
+    ops.py             # fetch, status, pull_safe (merge-tree conflict detection)
+  mcp/
+    server.py          # FastMCP tools + resources
+  web/
+    app.py             # FastAPI factory, routes, htmx fragments
+    templates/         # Jinja2 templates
+    static/            # CSS + vendored JS
+```
+
+## Requirements
+
+- Python 3.10+
+- Git 2.38+ (for `git merge-tree --write-tree`)
+- GitLab PAT with `read_api` scope
+
+## Testing
+
+```bash
+uv run pytest tests/ -v
+```
+
+## License
+
+[Unlicense](https://unlicense.org/) — public domain.

project_hub-0.1.0/README.md

@@ -0,0 +1,115 @@
+# project-hub
+
+Multi-repo workspace manager that unifies local git state and GitLab forge data (MRs, pipelines, vulnerabilities) into a single **MCP server + web dashboard**.
+
+Designed for engineers managing many repos under one parent directory.
+
+## Features
+
+- **Unified view** of git status, merge requests, pipelines, and vulnerabilities across all repos
+- **MCP server** (stdio) for Claude Code integration — ask "fix all vulns" and the agent has everything it needs
+- **Web dashboard** (htmx) with real-time sync, sortable tables, persistent filters, event notifications
+- **Smart defaults** — MCP returns only actionable vulns (high/critical + detected) with scanner solutions
+- **Non-destructive** — conflict detection via `git merge-tree`, no worktree mutations
+- **Background refresh** — async TTL-based cycle, diffs against SQLite cache to generate events
+
+## Quick start
+
+```bash
+# Install
+uvx project-hub --help
+
+# Or from source
+uv sync
+uv run project-hub --help
+```
+
+### Bootstrap a workspace
+
+```bash
+cd ~/Projects                    # parent dir containing your repos
+project-hub init                 # creates .project-hub/
+project-hub auth login gitlab.com  # store your PAT
+project-hub                      # launch dashboard (opens browser)
+```
+
+### Use as MCP server (Claude Code)
+
+```bash
+claude mcp add project-hub -- uvx project-hub --mcp
+```
+
+Then in Claude Code, the agent can call tools like `list_repos`, `get_vulnerabilities`, `pull_safe`, etc.
+
+## MCP tools
+
+| Tool | Description |
+|------|-------------|
+| `init` | Bootstrap `.project-hub/` workspace |
+| `list_repos` | List discovered repos with forge info |
+| `repo_status` | Git status (branch, ahead/behind, dirty) |
+| `fetch_all` | Trigger full refresh cycle |
+| `pull_safe` | Pull with conflict detection |
+| `list_mrs` | Merge requests (substring repo filter) |
+| `list_pipelines` | Pipelines (substring repo filter) |
+| `get_vulnerabilities` | Vulns — defaults to high/critical + detected, includes solutions |
+| `get_pipeline_jobs` | Jobs for a specific pipeline |
+| `acknowledge_alerts` | Mark events as seen |
+| `auth_status` | Check forge authentication |
+| `auth_login` | Store PAT for a forge instance |
+| `configure_forge` | Configure forge host mapping |
+
+## Web dashboard
+
+| Route | Description |
+|-------|-------------|
+| `/` | Dashboard with repo cards, events panel |
+| `/mrs` | Merge requests table (mine/all filter) |
+| `/pipelines` | Pipelines table (failed only filter) |
+| `/vulns` | Vulnerabilities table (severity + state filters) |
+| `/settings` | Exclude/include repos, rescan workspace |
+
+All filters and table sort are persisted in localStorage.
+
+## Architecture
+
+Single Python process, dual interfaces: MCP (stdio) + HTTP (FastAPI/htmx). Background asyncio task refreshes git+forge data on a TTL cycle, diffs with SQLite cache to generate events.
+
+```
+project_hub/
+  cli.py              # Click entry points
+  core/
+    workspace.py       # Orchestrator: discover -> refresh loop -> stop
+    cache.py           # SQLite (WAL mode, aiosqlite)
+    config.py          # YAML config with defaults
+    discovery.py       # Scan for .git/ repos, classify forges
+    models.py          # Dataclasses: Repo, MR, Pipeline, Vulnerability, Event
+    events.py          # Diff old vs new state -> Event list
+  gitlab/
+    client.py          # python-gitlab + GraphQL (vulnerabilities)
+    auth.py            # PAT resolution chain
+  git/
+    ops.py             # fetch, status, pull_safe (merge-tree conflict detection)
+  mcp/
+    server.py          # FastMCP tools + resources
+  web/
+    app.py             # FastAPI factory, routes, htmx fragments
+    templates/         # Jinja2 templates
+    static/            # CSS + vendored JS
+```
+
+## Requirements
+
+- Python 3.10+
+- Git 2.38+ (for `git merge-tree --write-tree`)
+- GitLab PAT with `read_api` scope
+
+## Testing
+
+```bash
+uv run pytest tests/ -v
+```
+
+## License
+
+[Unlicense](https://unlicense.org/) — public domain.

project_hub-0.1.0/project_hub/__init__.py

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