ripple-board 0.1.0__tar.gz

ripple_board-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md
+recursive-include ripple/web *.html *.js *.css
+recursive-include ripple/config *.json
+global-exclude *.py[cod]
+global-exclude __pycache__
+recursive-exclude * __pycache__
+recursive-exclude .ripple *
+recursive-exclude tests *
+exclude .env
+exclude .env.*
+exclude config/ripple.config.json

ripple_board-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: ripple-board
+Version: 0.1.0
+Summary: Architecture-aware autonomous engineering control plane for Java/Spring microservices.
+Author: Ripple
+Project-URL: Homepage, https://github.com/ripple-board/ripple-board
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110
+Requires-Dist: javalang>=0.13.0
+Requires-Dist: tree-sitter>=0.22.0
+Requires-Dist: tree-sitter-java>=0.21.0
+Requires-Dist: uvicorn>=0.27
+Provides-Extra: api
+Requires-Dist: fastapi>=0.110; extra == "api"
+Requires-Dist: uvicorn>=0.27; extra == "api"
+Provides-Extra: ast
+Requires-Dist: javalang>=0.13.0; extra == "ast"
+Requires-Dist: tree-sitter>=0.22.0; extra == "ast"
+Requires-Dist: tree-sitter-java>=0.21.0; extra == "ast"
+Provides-Extra: monetization
+Requires-Dist: pymongo[srv]>=4.6; extra == "monetization"
+
+# Ripple
+
+Ripple is an architecture-aware engineering control plane for enterprise microservices. This starter implements the first V1 slice from the product blueprint:
+
+- Discover Java/Spring repositories from a local group directory.
+- Extract structured architecture facts into nodes and edges.
+- Analyze a requirement against the architecture graph.
+- Calculate bounded blast radius with evidence and risk.
+- Generate a structured ChangePlan.
+- Expose the same flow through a small CLI and optional FastAPI app.
+
+The implementation keeps optional enterprise integrations separate, but a normal install includes the local web/API server and Java indexing support.
+
+## Quick Start
+
+```bash
+python3 -m ripple.cli index examples --out .ripple/graph.json
+python3 -m ripple.cli analyze "Add riskCategory to RiskResponse and include it in audit findings" --graph .ripple/graph.json
+python3 -m ripple.cli plan "Add riskCategory to RiskResponse and include it in audit findings" --graph .ripple/graph.json
+python3 -m ripple.cli verify "Add riskCategory to RiskResponse and include it in audit findings" --graph .ripple/graph.json --workspace examples
+python3 -m ripple.cli changeset "Add riskCategory to RiskResponse and include it in audit findings" --graph .ripple/graph.json
+python3 -m unittest discover -s tests
+```
+
+## Real Jira and GitLab Configuration
+
+Put secrets in environment variables or a local `.env` file. Do not commit `.env`; it is ignored.
+
+```bash
+cp .env.example .env
+cp config/ripple.config.example.json config/ripple.config.json
+ripple-board config
+ripple-board jira GRC-4721
+ripple-board gitlab-projects your/gitlab/group
+```
+
+`ripple-board config` redacts tokens before printing configuration.
+
+## API Development
+
+Run the FastAPI app directly during local development:
+
+```bash
+pip install -e .
+uvicorn ripple.api.app:app --reload
+```
+
+## Installable Local Product
+
+Ripple can be installed on a user's workstation and run locally:
+
+```bash
+python -m pip install ripple-board
+ripple-board server --host 127.0.0.1 --port 8010
+```
+
+For development from this repository:
+
+```bash
+python -m pip install -e .
+ripple-board server --host 127.0.0.1 --port 8010
+```
+
+The web console is then available at `http://127.0.0.1:8010`.
+
+## Run 24/7 On The Local Machine
+
+On Linux systems with user-level systemd, install Ripple as a background service:
+
+```bash
+ripple-board service install --host 127.0.0.1 --port 8010 --working-directory "$PWD"
+```
+
+Manage it with:
+
+```bash
+ripple-board service status
+ripple-board service uninstall
+```
+
+The service is installed at `~/.config/systemd/user/ripple-board.service`, starts immediately, restarts on failure, and starts again when the user's systemd session starts. For true boot-time availability before login, the machine owner can enable lingering with `loginctl enable-linger "$USER"`.
+
+## Publishing
+
+Build and validate the package before uploading:
+
+```bash
+python -m pip install build twine
+python -m build
+python -m twine check dist/*
+```
+
+Publish to TestPyPI first, install into a fresh virtual environment, then publish the same release to PyPI:
+
+```bash
+python -m twine upload --repository testpypi dist/*
+python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple ripple-board
+ripple-board --help
+ripple-board-server --help
+```
+
+## Current Scope
+
+This is the foundation, not the full platform. It starts the PDF roadmap at phase 1 and phase 3:
+
+- Structured architecture graph emitted from source.
+- Local service discovery.
+- Requirement routing.
+- Relation-aware impact traversal.
+- Transparent risk scoring.
+- Reviewable change planning.
+
+Next major steps are GitLab/Jira adapters, persistent PostgreSQL storage, stronger Java parsing, verification gates, and ChangeSet/MR delivery.
+
+## Implemented Product Layers
+
+- Architecture graph: JSON and SQLite persistence.
+- Indexing: Java/Spring route, Feign, entity, DTO, Kafka listener, and config fact extraction.
+- Requirement analysis: local text and file-backed Jira ingestion.
+- Blast radius: relation-aware bounded traversal with risk levels and evidence.
+- Planning: structured ChangePlan with approval requirements and verification evidence.
+- Policy: approval gates for medium/high risk changes.
+- Verification: per-service command planning and execution.
+- Compatibility: REST contract snapshot and diff primitives.
+- Delivery: ChangeSet persistence and planned MR records.
+- Worker adapter: dry-run worker behind the same interface intended for Claude/Codex/Gemini.
+- Workspace manager: isolated local workspace copies.
+- Incident path: OpenTelemetry-style JSON normalization.
+- Audit: JSONL audit trail for major CLI actions.
+- Web/API: optional FastAPI endpoints and a static console shell.
+
+Production GitLab/Jira/LLM integrations still need real credentials and network access. PostgreSQL/pgvector can replace the SQLite store behind the same graph persistence boundary.

ripple_board-0.1.0/README.md

@@ -0,0 +1,132 @@
+# Ripple
+
+Ripple is an architecture-aware engineering control plane for enterprise microservices. This starter implements the first V1 slice from the product blueprint:
+
+- Discover Java/Spring repositories from a local group directory.
+- Extract structured architecture facts into nodes and edges.
+- Analyze a requirement against the architecture graph.
+- Calculate bounded blast radius with evidence and risk.
+- Generate a structured ChangePlan.
+- Expose the same flow through a small CLI and optional FastAPI app.
+
+The implementation keeps optional enterprise integrations separate, but a normal install includes the local web/API server and Java indexing support.
+
+## Quick Start
+
+```bash
+python3 -m ripple.cli index examples --out .ripple/graph.json
+python3 -m ripple.cli analyze "Add riskCategory to RiskResponse and include it in audit findings" --graph .ripple/graph.json
+python3 -m ripple.cli plan "Add riskCategory to RiskResponse and include it in audit findings" --graph .ripple/graph.json
+python3 -m ripple.cli verify "Add riskCategory to RiskResponse and include it in audit findings" --graph .ripple/graph.json --workspace examples
+python3 -m ripple.cli changeset "Add riskCategory to RiskResponse and include it in audit findings" --graph .ripple/graph.json
+python3 -m unittest discover -s tests
+```
+
+## Real Jira and GitLab Configuration
+
+Put secrets in environment variables or a local `.env` file. Do not commit `.env`; it is ignored.
+
+```bash
+cp .env.example .env
+cp config/ripple.config.example.json config/ripple.config.json
+ripple-board config
+ripple-board jira GRC-4721
+ripple-board gitlab-projects your/gitlab/group
+```
+
+`ripple-board config` redacts tokens before printing configuration.
+
+## API Development
+
+Run the FastAPI app directly during local development:
+
+```bash
+pip install -e .
+uvicorn ripple.api.app:app --reload
+```
+
+## Installable Local Product
+
+Ripple can be installed on a user's workstation and run locally:
+
+```bash
+python -m pip install ripple-board
+ripple-board server --host 127.0.0.1 --port 8010
+```
+
+For development from this repository:
+
+```bash
+python -m pip install -e .
+ripple-board server --host 127.0.0.1 --port 8010
+```
+
+The web console is then available at `http://127.0.0.1:8010`.
+
+## Run 24/7 On The Local Machine
+
+On Linux systems with user-level systemd, install Ripple as a background service:
+
+```bash
+ripple-board service install --host 127.0.0.1 --port 8010 --working-directory "$PWD"
+```
+
+Manage it with:
+
+```bash
+ripple-board service status
+ripple-board service uninstall
+```
+
+The service is installed at `~/.config/systemd/user/ripple-board.service`, starts immediately, restarts on failure, and starts again when the user's systemd session starts. For true boot-time availability before login, the machine owner can enable lingering with `loginctl enable-linger "$USER"`.
+
+## Publishing
+
+Build and validate the package before uploading:
+
+```bash
+python -m pip install build twine
+python -m build
+python -m twine check dist/*
+```
+
+Publish to TestPyPI first, install into a fresh virtual environment, then publish the same release to PyPI:
+
+```bash
+python -m twine upload --repository testpypi dist/*
+python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple ripple-board
+ripple-board --help
+ripple-board-server --help
+```
+
+## Current Scope
+
+This is the foundation, not the full platform. It starts the PDF roadmap at phase 1 and phase 3:
+
+- Structured architecture graph emitted from source.
+- Local service discovery.
+- Requirement routing.
+- Relation-aware impact traversal.
+- Transparent risk scoring.
+- Reviewable change planning.
+
+Next major steps are GitLab/Jira adapters, persistent PostgreSQL storage, stronger Java parsing, verification gates, and ChangeSet/MR delivery.
+
+## Implemented Product Layers
+
+- Architecture graph: JSON and SQLite persistence.
+- Indexing: Java/Spring route, Feign, entity, DTO, Kafka listener, and config fact extraction.
+- Requirement analysis: local text and file-backed Jira ingestion.
+- Blast radius: relation-aware bounded traversal with risk levels and evidence.
+- Planning: structured ChangePlan with approval requirements and verification evidence.
+- Policy: approval gates for medium/high risk changes.
+- Verification: per-service command planning and execution.
+- Compatibility: REST contract snapshot and diff primitives.
+- Delivery: ChangeSet persistence and planned MR records.
+- Worker adapter: dry-run worker behind the same interface intended for Claude/Codex/Gemini.
+- Workspace manager: isolated local workspace copies.
+- Incident path: OpenTelemetry-style JSON normalization.
+- Audit: JSONL audit trail for major CLI actions.
+- Web/API: optional FastAPI endpoints and a static console shell.
+
+Production GitLab/Jira/LLM integrations still need real credentials and network access. PostgreSQL/pgvector can replace the SQLite store behind the same graph persistence boundary.

ripple_board-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ripple-board"
+version = "0.1.0"
+description = "Architecture-aware autonomous engineering control plane for Java/Spring microservices."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{name = "Ripple"}]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development",
+]
+dependencies = [
+    "fastapi>=0.110",
+    "javalang>=0.13.0",
+    "tree-sitter>=0.22.0",
+    "tree-sitter-java>=0.21.0",
+    "uvicorn>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/ripple-board/ripple-board"
+
+[project.optional-dependencies]
+api = ["fastapi>=0.110", "uvicorn>=0.27"]
+ast = ["javalang>=0.13.0", "tree-sitter>=0.22.0", "tree-sitter-java>=0.21.0"]
+monetization = ["pymongo[srv]>=4.6"]
+
+[project.scripts]
+ripple-board = "ripple.cli:main"
+ripple-board-server = "ripple.server:main"
+ripple = "ripple.cli:main"
+ripple-server = "ripple.server:main"
+
+[tool.setuptools.packages.find]
+include = ["ripple*"]
+exclude = ["config*", "examples*", "tests*"]
+
+[tool.setuptools.package-data]
+"ripple.config" = ["*.json"]
+"ripple.web" = ["*.html", "*.js", "*.css"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ripple_board-0.1.0/ripple/__init__.py

@@ -0,0 +1,5 @@
+"""Ripple architecture intelligence starter package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

ripple_board-0.1.0/ripple/adapters/__init__.py

@@ -0,0 +1 @@
+"""External integration boundaries for GitLab, Jira, coding agents, and verification."""

ripple_board-0.1.0/ripple/adapters/bitbucket.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import base64
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from ripple.adapters.gitlab import GitLabAdapter, GitLabProject
+from ripple.config.settings import BitbucketSettings
+
+
+class BitbucketAdapter(GitLabAdapter):
+    def __init__(self, settings: BitbucketSettings) -> None:
+        self.settings = settings
+
+    def list_projects(self, group: str = "") -> list[GitLabProject]:
+        workspace = group.strip()
+        if not workspace:
+            raise RuntimeError("Bitbucket workspace is required to list repositories.")
+        path = f"/2.0/repositories/{urllib.parse.quote(workspace)}?pagelen=100"
+        projects = []
+        while path:
+            data = self._request("GET", path)
+            for raw in data.get("values", []):
+                if raw.get("is_private") is None and raw.get("type") != "repository":
+                    continue
+                links = raw.get("links", {})
+                clone_url = _clone_url(links.get("clone", []))
+                main_branch = raw.get("mainbranch") or {}
+                projects.append(
+                    GitLabProject(
+                        id=str(raw.get("full_name") or raw.get("uuid") or raw.get("slug")),
+                        name=str(raw.get("slug") or raw.get("name") or ""),
+                        clone_url=clone_url,
+                        default_branch=main_branch.get("name") or "master",
+                    )
+                )
+            path = _relative_next(data.get("next", ""), _api_base(self.settings.base_url))
+        return projects
+
+    def create_merge_request(self, project: GitLabProject, source_branch: str, target_branch: str, title: str, description: str = "") -> str:
+        data = self._request(
+            "POST",
+            f"/2.0/repositories/{urllib.parse.quote(project.id, safe='/')}/pullrequests",
+            {
+                "title": title,
+                "description": description,
+                "source": {"branch": {"name": source_branch}},
+                "destination": {"branch": {"name": target_branch}},
+                "close_source_branch": True,
+            },
+        )
+        return data.get("links", {}).get("html", {}).get("href", "")
+
+    def authenticated_url(self, url: str) -> str:
+        if not self.settings.username or not self.settings.app_password or not url.startswith(("http://", "https://")):
+            return ""
+        parsed = urllib.parse.urlsplit(url)
+        username = urllib.parse.quote(self.settings.username, safe="")
+        password = urllib.parse.quote(self.settings.app_password, safe="")
+        netloc = f"{username}:{password}@{parsed.hostname or ''}"
+        if parsed.port:
+            netloc = f"{netloc}:{parsed.port}"
+        return urllib.parse.urlunsplit((parsed.scheme, netloc, parsed.path, parsed.query, parsed.fragment))
+
+    def _request(self, method: str, path: str, body: dict | None = None) -> dict:
+        url = f"{_api_base(self.settings.base_url)}{path}" if path.startswith("/") else path
+        payload = json.dumps(body).encode() if body is not None else None
+        request = urllib.request.Request(url, data=payload, method=method)
+        token = base64.b64encode(f"{self.settings.username}:{self.settings.app_password}".encode()).decode()
+        request.add_header("Authorization", f"Basic {token}")
+        request.add_header("Accept", "application/json")
+        request.add_header("Content-Type", "application/json")
+        try:
+            with urllib.request.urlopen(request, timeout=30) as response:
+                text = response.read().decode()
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode(errors="ignore")[:500]
+            raise RuntimeError(f"Bitbucket API {method} {path} failed with HTTP {exc.code}: {detail}") from exc
+        except urllib.error.URLError as exc:
+            raise RuntimeError(f"Bitbucket API {method} {path} failed: {exc.reason}") from exc
+        return json.loads(text) if text else {}
+
+
+def _clone_url(clones: list[dict]) -> str:
+    https = next((item.get("href", "") for item in clones if item.get("name") == "https"), "")
+    return https or next((item.get("href", "") for item in clones if item.get("href")), "")
+
+
+def _relative_next(url: str, base_url: str) -> str:
+    if not url:
+        return ""
+    parsed = urllib.parse.urlsplit(url)
+    base = urllib.parse.urlsplit(base_url)
+    if parsed.netloc and parsed.netloc != base.netloc:
+        return ""
+    return f"{parsed.path}?{parsed.query}" if parsed.query else parsed.path
+
+
+def _api_base(base_url: str) -> str:
+    normalized = base_url.strip().strip("/")
+    if normalized in {"https://bitbucket.org", "http://bitbucket.org", "bitbucket.org"}:
+        return "https://api.bitbucket.org"
+    return normalized

ripple_board-0.1.0/ripple/adapters/github.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from ripple.adapters.gitlab import GitLabAdapter, GitLabProject
+from ripple.config.settings import GitHubSettings
+
+
+class GitHubAdapter(GitLabAdapter):
+    def __init__(self, settings: GitHubSettings) -> None:
+        self.settings = settings
+
+    def list_projects(self, group: str = "") -> list[GitLabProject]:
+        path = f"/orgs/{urllib.parse.quote(group)}/repos?per_page=100&type=all" if group else "/user/repos?per_page=100&type=all"
+        projects = []
+        while path:
+            data, headers = self._request("GET", path, with_headers=True)
+            for raw in data:
+                if raw.get("archived") or raw.get("disabled"):
+                    continue
+                projects.append(
+                    GitLabProject(
+                        id=str(raw.get("full_name") or raw.get("id")),
+                        name=str(raw.get("name") or raw.get("full_name") or ""),
+                        clone_url=raw.get("clone_url") or raw.get("html_url") or "",
+                        default_branch=raw.get("default_branch") or "master",
+                    )
+                )
+            path = _next_link(headers.get("Link", ""))
+        return projects
+
+    def create_merge_request(self, project: GitLabProject, source_branch: str, target_branch: str, title: str, description: str = "") -> str:
+        data, _headers = self._request(
+            "POST",
+            f"/repos/{urllib.parse.quote(project.id, safe='/')}/pulls",
+            {
+                "title": title,
+                "head": source_branch,
+                "base": target_branch,
+                "body": description,
+                "maintainer_can_modify": True,
+            },
+            with_headers=True,
+        )
+        return data.get("html_url", "")
+
+    def authenticated_url(self, url: str) -> str:
+        if not self.settings.token or not url.startswith(("http://", "https://")):
+            return ""
+        parsed = urllib.parse.urlsplit(url)
+        username = urllib.parse.quote("x-access-token", safe="")
+        password = urllib.parse.quote(self.settings.token, safe="")
+        netloc = f"{username}:{password}@{parsed.hostname or ''}"
+        if parsed.port:
+            netloc = f"{netloc}:{parsed.port}"
+        return urllib.parse.urlunsplit((parsed.scheme, netloc, parsed.path, parsed.query, parsed.fragment))
+
+    def _request(self, method: str, path: str, body: dict | None = None, with_headers: bool = False):
+        url = f"{_api_base(self.settings.base_url)}{path}"
+        payload = json.dumps(body).encode() if body is not None else None
+        request = urllib.request.Request(url, data=payload, method=method)
+        request.add_header("Authorization", f"Bearer {self.settings.token}")
+        request.add_header("Accept", "application/vnd.github+json")
+        request.add_header("Content-Type", "application/json")
+        request.add_header("X-GitHub-Api-Version", "2022-11-28")
+        try:
+            with urllib.request.urlopen(request, timeout=30) as response:
+                text = response.read().decode()
+                data = json.loads(text) if text else {}
+                headers = dict(response.headers.items())
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode(errors="ignore")[:500]
+            raise RuntimeError(f"GitHub API {method} {path} failed with HTTP {exc.code}: {detail}") from exc
+        except urllib.error.URLError as exc:
+            raise RuntimeError(f"GitHub API {method} {path} failed: {exc.reason}") from exc
+        return (data, headers) if with_headers else data
+
+
+def _api_base(base_url: str) -> str:
+    normalized = base_url.strip().strip("/")
+    if normalized in {"https://github.com", "http://github.com", "github.com"}:
+        return "https://api.github.com"
+    if normalized.endswith("/api/v3"):
+        return normalized
+    return f"{normalized}/api/v3"
+
+
+def _next_link(header: str) -> str:
+    for part in header.split(","):
+        if 'rel="next"' not in part:
+            continue
+        start = part.find("<")
+        end = part.find(">")
+        if start >= 0 and end > start:
+            url = part[start + 1 : end]
+            parsed = urllib.parse.urlsplit(url)
+            return f"{parsed.path}?{parsed.query}" if parsed.query else parsed.path
+    return ""