ralphception 0.1.0__tar.gz

ralphception-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ralphception
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ralphception-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.ralphception/
+.worktrees/
+src/ralphception/_version.py
+__pycache__/
+*.pyc

ralphception-0.1.0/.mise.toml

@@ -0,0 +1,14 @@
+[tools]
+python = "3.12"
+
+[tasks.install]
+run = "uv sync"
+
+[tasks.test]
+run = "uv run pytest -v"
+
+[tasks.typecheck]
+run = "uv run ty check src tests"
+
+[tasks.run]
+run = "uv run ralphception"

ralphception-0.1.0/PKG-INFO

@@ -0,0 +1,381 @@
+Metadata-Version: 2.4
+Name: ralphception
+Version: 0.1.0
+Summary: Codex-native orchestration runtime.
+Requires-Python: >=3.12
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: textual<1.0,>=0.61
+Requires-Dist: typer<1.0,>=0.12
+Description-Content-Type: text/markdown
+
+# Ralphception
+
+`ralphception` is a Codex-native agent orchestrator for "Ralph loops of Ralph loops":
+
+- one outer run per target repo
+- child runs for spec extraction, planning, execution, merge, and audit
+- parallel child work where it is safe
+- repeated audit/reopen cycles until blocking gaps are gone
+
+The core runtime is implemented and tested. The current repo is best understood as an alpha runtime with real storage, workflow, recovery, review, and dashboard layers, but not yet a fully polished one-command product UX.
+
+## Current Status
+
+What is implemented today:
+
+- repo-local `.ralphception/` runtime state and config
+- XDG-backed lease and resume state
+- workflow engine, approvals, bundles, recovery, verification, audit, worktrees, and merge coordination
+- one shared runtime supervisor with two frontends:
+  - a Textual TUI launched by `uv run ralphception`
+  - a traditional terminal frontend launched by `uv run ralphception terminal`
+- interactive startup and review screens backed by the same shared runtime supervisor
+- automatic first-child execution startup from the TUI launch path once an execution bundle is approved and a session backend is available
+- long-running terminal execution that uses the same durable mission loop as the TUI
+- end-to-end tests with deterministic fake Codex/session behavior
+
+What is not fully polished yet:
+
+- `ralphception resume` now resumes the current workspace root run in `read` or `repair` mode, but the top-level CLI still does not expose historical-run selection
+- release automation / PyPI publishing / final `uvx` polish are still follow-on work
+
+## How To Think About It
+
+There is one runtime and two frontends today:
+
+```mermaid
+flowchart TD
+    A["Shared runtime supervisor"] --> B["Textual frontend"]
+    A --> C["Terminal frontend"]
+    B --> D["Startup / review / dashboard surfaces"]
+    C --> E["Logs + focused prompts"]
+```
+
+The intended product flow is:
+
+```mermaid
+flowchart TD
+    A["Seed prompt + optional source repos"] --> B["Startup / intake"]
+    B --> C["Spec generation"]
+    C --> D["Spec review"]
+    D --> E["Plan / bundle generation"]
+    E --> F["Bundle review"]
+    F --> G["Execution child runs"]
+    G --> H["Merge + verification"]
+    H --> I["Audit loop"]
+    I --> J{"Open P0/P1/P2?"}
+    J -- yes --> E
+    J -- no --> K["Done"]
+```
+
+The important distinction is that the runtime loop is now shared. The Textual and terminal entrypoints are different surfaces over the same durable mission state and the same execution/audit/reopen cycle.
+
+## Quick Start
+
+Local development usage today:
+
+```bash
+mise run install
+mise run run
+```
+
+Equivalent `uv` commands:
+
+```bash
+uv sync
+uv run ralphception
+uv run ralphception terminal
+```
+
+Once the package is published, the intended entrypoint is:
+
+```bash
+uvx ralphception
+```
+
+## What Happens On Launch
+
+`uv run ralphception` resolves the current workspace and does one of three things in the TUI frontend:
+
+1. Startup mode if `.ralphception/runs/run-root/startup.json` does not exist.
+2. Review mode if spec approval, execution-bundle approval, or blocked-run recovery is pending.
+3. Dashboard mode otherwise.
+
+`uv run ralphception terminal` resolves the same runtime state, but renders it as logs and prompts instead of panes.
+
+The runtime always works inside the target repo and writes ephemeral runtime state under `.ralphception/`.
+That directory is intentionally disposable and should not be committed to git.
+When dashboard mode opens against an approved execution bundle with no existing child runs, the launch path still starts the first execution child run before rendering the dashboard.
+
+## How To Use It Today
+
+### 1. Bootstrap a workspace
+
+Run:
+
+```bash
+uv run ralphception
+```
+
+If the workspace has not been bootstrapped yet, the startup screen now prompts for:
+
+- a seed prompt for the outer run
+- optional source repository paths, one path per line
+
+Submitting the form persists `.ralphception/runs/run-root/startup.json`, writes the intake
+artifact, and then launches the resolved runtime view for the workspace.
+
+If you want the same top-level mission loop without opening Textual, use the terminal frontend:
+
+```bash
+uv run ralphception terminal \
+  --seed-prompt "port parser" \
+  --source-repo /path/to/source-repo \
+  --approve-all
+```
+
+`uv run ralphception headless ...` remains as a compatibility alias during the transition.
+
+Useful flags:
+
+- `--repo-root <path>` to operate on another workspace
+- `--approve-all` to auto-approve spec and execution-bundle review targets so the supervisor can run to terminal completion without a human
+- `--fake-session-manager` to inject the deterministic fake Codex backend used by the test suite when you want to verify the full loop without a live session backend
+
+Terminal execution requires either the `codex` CLI on your `PATH` or `--fake-session-manager`.
+`uv sync` only installs Ralphception's Python dependencies; the live session backend comes from the Codex CLI's `app-server`.
+If neither is available, `uv run ralphception terminal ...` now exits immediately with a backend error instead of falling back to dashboard mode.
+
+The terminal frontend behaves as a long-running mission supervisor:
+
+- bootstrap intake if needed
+- generate or reuse spec and plan artifacts
+- approve the spec and execution bundle when `--approve-all` is set
+- create child worktrees, execute, verify, merge, and audit
+- reopen execution automatically when audit leaves blocking `P0`/`P1`/`P2` findings open
+- exit only after terminal completion or failure
+
+While the mission is running, the terminal frontend now streams readable high-level progress such as stage changes, turn start/completion, approvals, child-run creation, verification outcomes, merges, audit reopen decisions, and mission completion.
+
+The durable mission-loop state for the root run lives at:
+
+```text
+.ralphception/runs/run-root/headless-state.json
+```
+
+The default stage artifacts are:
+
+```text
+.ralphception/specs/mission-spec.md
+.ralphception/plans/mission-plan.md
+.ralphception/plans/mission-plan.json
+.ralphception/runs/<child-run-id>/handoff.json
+.ralphception/runs/run-root/audit-findings.json
+```
+
+To monitor a running terminal mission, tail the root event log from another shell:
+
+```bash
+tail -f .ralphception/events/run-root.jsonl
+```
+
+### 1a. Bootstrap finisher helper
+
+When you are using Ralphception to finish Ralphception itself, the helper-only loop state lives under:
+
+```text
+.ralphception/bootstrapping/
+|- finish-criteria.md
+|- gaps.json
+|- gaps.md
+|- inputs.json
+|- prompt.txt
+`- iterations/
+```
+
+There is now a repo-root `ralph.sh` loop entrypoint. It repeatedly runs one bootstrap iteration at a time until the loop is done, stops for human review, or exits on failure:
+
+```bash
+./ralph.sh
+```
+
+It calls `uv run python -m ralphception.bootstrap.runner --loop-once`, refreshes the bootstrap prompt and command, launches a fresh `codex exec` iteration, and lets Python decide whether to continue, stop for review, or finish.
+
+### 2. Understand what the runtime wrote
+
+The workspace layout looks like this:
+
+```text
+.ralphception/
+|- config.toml
+|- approvals/
+|- events/
+|- findings/
+|- merge/
+|- plans/
+|- runs/
+|- skills/
+|- specs/
+|- todos/
+`- verification/
+```
+
+Important files early in the flow:
+
+- `.ralphception/config.toml`
+  The persisted runtime config.
+- `.ralphception/runs/run-root/startup.json`
+  The seed prompt and source repo capture.
+- `.ralphception/runs/run-root/intake.md`
+  The intake artifact written from the seed prompt.
+
+### 3. Use the dashboard when the runtime reaches dashboard mode
+
+The dashboard supports these slash commands:
+
+- `/help`
+- `/model <name>`
+- `/resume [repair]`
+- `/status`
+- `/artifacts`
+- `/approve`
+- `/retry`
+- `/restart`
+- `/replace`
+- `/abort`
+
+Right now the dashboard is the main interactive surface that is actually wired.
+It now launches with recovery configured, and if the workspace already has an approved execution bundle the initial execution child run is scheduled before the dashboard renders.
+
+### 4. Use review mode when review is pending
+
+When the workspace has a pending spec review, execution-bundle approval, or recovery-eligible blocked run, `uv run ralphception` now opens an interactive review screen. It shows:
+
+- the pending review and recovery targets for the workspace
+- a details pane for the selected target
+- a diff pane for spec or execution-bundle artifacts
+- approve, resume, retry, restart, and replace actions when they apply
+
+The Python controller surface still exists for scripting and tests. If you want to inspect the current target programmatically:
+
+```bash
+uv run python - <<'PY'
+from pathlib import Path
+from ralphception.app import resolve_runtime_view
+
+launch = resolve_runtime_view(Path.cwd())
+assert launch.review_controller is not None
+
+target = launch.review_controller.current_target()
+print(target)
+print()
+print(launch.review_controller.diff_current_target().rendered_text)
+PY
+```
+
+## Default Runtime Config
+
+By default, Ralphception writes `.ralphception/config.toml` with:
+
+- model: `gpt-5.4`
+- reasoning: `high`
+- latency profile: `fast`
+- sandbox: `danger-full-access`
+- approval policy: `never`
+- worktrees for edit runs: enabled
+- max parallel children: `4`
+- audit reopen priorities: `P0`, `P1`, `P2`
+
+The dashboard `/model` command updates the persisted config.
+
+## How Resume Works
+
+Repo-local state lives in `.ralphception/`, but authoritative lease state is stored in XDG state:
+
+```text
+$XDG_STATE_HOME/ralphception/<workspace-hash>/lease.json
+```
+
+The recovery layer can:
+
+- read durable event logs
+- reconcile checkpoints
+- refuse healthy foreign leases
+- steal stale leases in repair mode
+- retry, restart, or replace blocked runs
+
+The top-level CLI now exposes the current workspace root-run resume path:
+
+```bash
+uv run ralphception resume
+uv run ralphception resume repair
+uv run ralphception terminal --approve-all --fake-session-manager
+```
+
+The dashboard `/resume` command uses the same `read` or `repair` recovery flow. Explicit historical-run targeting is still a recovery-layer capability rather than a CLI surface.
+
+## The Mental Model For Porting
+
+If you are using Ralphception for porting, think about it as:
+
+1. Run it in the destination repo.
+2. Point it at one or more source repos elsewhere on disk.
+3. Reduce source behavior into specs under `.ralphception/specs/`.
+4. Turn approved specs into plans and execution bundles.
+5. Execute child runs against the target repo.
+6. Verify, merge, audit, and reopen until blocking gaps are gone.
+
+The source repo is input, not the place where Ralphception writes its state.
+
+## Development Commands
+
+```bash
+mise run install
+mise run run
+mise run test
+mise run typecheck
+```
+
+Equivalent:
+
+```bash
+uv sync
+uv run ralphception
+uv run pytest -v
+uv run ty check src tests
+```
+
+## What To Read In The Codebase
+
+If you want to understand the implementation, start here:
+
+- `src/ralphception/app.py`
+  Runtime mode resolution and app bootstrap.
+- `src/ralphception/ui/app.py`
+  Dashboard controller and slash commands.
+- `src/ralphception/ui/screens/startup.py`
+  First-run bootstrap capture.
+- `src/ralphception/ui/screens/review.py`
+  Approval and recovery review logic.
+- `src/ralphception/workflow/engine.py`
+  Core run/stage/bundle orchestration.
+- `src/ralphception/workflow/recovery.py`
+  Resume, retry, restart, replace, lease reconciliation.
+- `src/ralphception/git/worktrees.py`
+  Worktree lifecycle.
+- `src/ralphception/git/merge.py`
+  Merge coordination.
+- `src/ralphception/audit/service.py`
+  Audit findings and reopen behavior.
+- `src/ralphception/verification/service.py`
+  Verification task construction and result persistence.
+
+## Short Version
+
+If you want the practical answer:
+
+- today, use `uv run ralphception` locally
+- bootstrap the first run with the `StartupBootstrapController` snippet above
+- inspect `.ralphception/` to understand what the runtime has written
+- use the dashboard slash commands for the currently wired interactive surface
+- think of the project as a real core runtime that still needs a final layer of polished operator UX