Metadata-Version: 2.4
Name: ripple-board
Version: 0.1.3
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 start
```

For development from this repository:

```bash
python -m pip install -e .
ripple-board start
```

The web console is then available at `http://127.0.0.1:8010`.

`ripple-board start` detects the operating system and chooses the local launcher automatically:

- Linux: user-level `systemd` service when available.
- macOS: per-user LaunchAgent.
- Windows: per-user Task Scheduler task.
- Fallback: foreground server in the current terminal.

Use `ripple-board start --foreground` when you explicitly want to keep the server attached to the terminal.

## Run 24/7 On The Local Machine

On Linux systems with user-level systemd, the explicit service command is still available:

```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.
