flaude 0.1.0__tar.gz

flaude-0.1.0/.env.example

@@ -0,0 +1,15 @@
+# Required for E2E tests (flaude/tests/test_e2e.py)
+# Copy to .env: cp .env.example .env
+
+# Fly.io API token — https://fly.io/user/personal_access_tokens
+FLY_API_TOKEN=
+
+# Claude Code OAuth token for authenticating Claude Code on Fly machines
+CLAUDE_CODE_OAUTH_TOKEN=
+
+# GitHub credentials (only needed if cloning private repos)
+GITHUB_USERNAME=
+GITHUB_TOKEN=
+
+# Fly.io app name to use for E2E tests
+FLY_APP_NAME=flaude-e2e

flaude-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,49 @@
+name: Bug Report
+description: Report a bug in flaude
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug! Please fill out the details below.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: Minimal code to reproduce the issue.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: flaude version
+      placeholder: "e.g. 0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "e.g. 3.11.8"
+    validations:
+      required: true

flaude-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,25 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the use case or limitation you're hitting.
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How would you like this to work?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you've thought about.

flaude-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## Summary
+
+<!-- What does this PR do? Why? -->
+
+## Changes
+
+-
+-
+
+## Testing
+
+- [ ] Unit tests pass (`make test`)
+- [ ] Linting passes (`make check`)
+- [ ] Added tests for new behavior (if applicable)
+
+## Related issues
+
+Closes #

flaude-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-caching: true
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Run tests with coverage
+        run: uv run pytest --cov=flaude --cov-report=xml --cov-fail-under=90
+
+  lint:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-caching: true
+      - run: uv sync --extra dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy flaude/ tests/
+      - run: uv run bandit -r flaude/ -ll

flaude-0.1.0/.github/workflows/docker.yml

@@ -0,0 +1,49 @@
+name: Docker
+
+on:
+  push:
+    branches: [main]
+  release:
+    types: [published]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push:
+    name: Build and push Docker image
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=sha,prefix=sha-
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: flaude
+          file: flaude/Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

flaude-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,20 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install ".[docs]"
+      - run: mkdocs gh-deploy --force

flaude-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

flaude-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+.env
+*.pyc
+.pytest_cache
+.coverage
+.DS_Store
+.ruff_cache
+.mypy_cache
+.venv
+dist
+site/
+__pycache__/
+*.egg-info/
+build/
+htmlcov/
+*.pyo
+.tox/

flaude-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.7
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.9.0
+    hooks:
+      - id: mypy
+        args: [--ignore-missing-imports]
+        additional_dependencies:
+          - pytest
+          - pytest-asyncio
+          - respx
+          - httpx

flaude-0.1.0/AGENTS.md

@@ -0,0 +1,117 @@
+# AGENTS.md — AI-optimized reference for flaude
+
+## Identity
+
+- **Package name**: `flaude`
+- **Purpose**: Python library for executing Claude Code prompts on ephemeral Fly.io machines
+- **Language**: Python 3.11+
+- **Single dependency**: httpx (async HTTP)
+- **No CLI** — library-only, all async
+
+## Architecture
+
+```
+flaude/
+├── __init__.py          # Public API (re-exports everything)
+├── app.py               # Fly.io app CRUD: ensure_app, create_app, get_app
+├── runner.py            # Core execution: run, run_and_destroy, wait_for_machine_exit
+├── executor.py          # Concurrent batch: ConcurrentExecutor, run_batch, run_one
+├── lifecycle.py         # Log-streaming execution: run_with_logs → StreamingRun
+├── machine.py           # Machine CRUD: create_machine, stop_machine, destroy_machine
+├── machine_config.py    # Config dataclasses: MachineConfig, RepoSpec, build_machine_config
+├── fly_client.py        # Low-level HTTP: fly_get, fly_post, fly_delete, fetch_machine_logs, FlyAPIError
+├── log_drain.py         # Log infrastructure: LogDrainServer, LogCollector, LogStream
+├── image.py             # Docker: docker_build, docker_push, ensure_image
+├── Dockerfile           # Container: Node.js 22 + Claude Code + git + gh CLI
+└── entrypoint.sh        # Container startup: clone repos → run claude -p → write exit marker
+```
+
+## Execution modes
+
+### 1. Fire-and-forget (`run_and_destroy`)
+Create machine → wait for exit → destroy. Returns `RunResult`. Raises `MachineExitError` on non-zero exit.
+
+### 2. Streaming (`run_with_logs`)
+Creates `LogDrainServer` before machine → subscribes to logs → returns `StreamingRun` (async iterator + context manager). Background task waits for exit, signals collector, destroys machine.
+
+### 3. Concurrent (`ConcurrentExecutor.run_batch`)
+Dispatches multiple `ExecutionRequest` objects via `asyncio.gather` with optional semaphore. Returns `BatchResult` with per-request `ExecutionResult`.
+
+## Key types
+
+```python
+# Configuration
+MachineConfig(image, claude_code_oauth_token, github_username, github_token, prompt, repos, region, vm_size, vm_cpus, vm_memory_mb, auto_destroy, env, metadata)
+RepoSpec(url, branch="", target_dir="")
+
+# Results
+RunResult(machine_id, exit_code, state, destroyed)        # frozen dataclass
+MachineExitError(machine_id, exit_code, state, logs)      # exception
+BatchResult(results, total, succeeded, failed)             # frozen dataclass
+ExecutionResult(tag, run_result, error)                    # .success property
+
+# Execution
+ExecutionRequest(config, name=None, tag="")
+ConcurrentExecutor(app_name, token=None, max_concurrency=None, wait_timeout=3600.0)
+StreamingRun  # async iterator + context manager, .result(), .cleanup(), .machine_id
+
+# Infrastructure
+FlyApp(name, org, region)
+FlyMachine(id, name, state, region, instance_id, app_name)
+LogDrainServer(collector, host="0.0.0.0", port=0, include_stderr=False)
+LogCollector()  # machine_id → asyncio.Queue routing
+LogStream(queue, item_timeout=None, total_timeout=None)    # async iterator
+```
+
+## Critical invariants
+
+1. **Guaranteed cleanup**: Every machine is destroyed in a `try/finally` block — exceptions, cancellations, and timeouts all trigger destruction.
+2. **Log drain before machine**: `LogDrainServer` starts before `create_machine` so no early log lines are lost.
+3. **Exit code fallback**: If Fly API doesn't report exit code, `entrypoint.sh` writes `[flaude:exit:N]` marker parsed by `extract_exit_code_from_logs`.
+4. **Never raises in batch**: `ConcurrentExecutor._execute_one` catches all exceptions into `ExecutionResult.error`.
+5. **Restart policy is "no"**: Machines run once and stop. `auto_destroy=True` by default.
+
+## Container image
+
+- **Base**: `node:22-bookworm-slim`
+- **Pre-installed**: git, jq, gh (GitHub CLI), `@anthropic-ai/claude-code` (npm global)
+- **Entrypoint flow**: validate `CLAUDE_CODE_OAUTH_TOKEN` → configure git credentials → clone repos from `FLAUDE_REPOS` JSON → `cd` to workspace → `claude -p -- "$FLAUDE_PROMPT"` → write exit marker → exit
+
+## Environment variables
+
+**Host-side** (your process):
+- `FLY_API_TOKEN` — Fly.io API authentication
+
+**Machine-side** (set automatically by `build_machine_config`):
+- `CLAUDE_CODE_OAUTH_TOKEN` — Claude Code auth
+- `FLAUDE_PROMPT` — The prompt string
+- `FLAUDE_REPOS` — JSON array of `{url, branch?, target_dir?}`
+- `GITHUB_USERNAME` / `GITHUB_TOKEN` — Git credentials (optional)
+
+## Fly.io API interaction
+
+All API calls go through `fly_client.py` which wraps httpx:
+- **Machines API**: `https://api.machines.dev/v1` — auth via `Bearer {FLY_API_TOKEN}`
+- **Platform API**: `https://api.fly.io` — auth via raw token as `Authorization` header (no `Bearer` prefix)
+- Machine wait: `GET /apps/{app}/machines/{id}/wait?state=stopped` (long-poll), with polling fallback
+- Log retrieval: `GET https://api.fly.io/api/v1/apps/{app}/logs?instance={machine_id}` — historical logs (~15 day retention), works after machine exit/destroy
+- Terminal states: `stopped`, `destroyed`, `failed`
+- Exit code extraction: `event["request"]["exit_event"]["exit_code"]` (or via `monitor_event` wrapper)
+
+## Testing
+
+- **Framework**: pytest + pytest-asyncio (auto mode)
+- **HTTP mocking**: respx
+- **18 test files** covering: app, machine, config, runner, executor, lifecycle, log drain, log stream, log parsing, entrypoint, exit codes, cleanup guarantees, concurrent integration, failure logs, image, startup env, prompt execution
+- **Run unit tests**: `pytest` (E2E excluded by default via `addopts = "-m 'not e2e'"`)
+- **Run E2E tests**: `source .env && pytest -m e2e -v`
+- **E2E requires**: `FLY_API_TOKEN` + `CLAUDE_CODE_OAUTH_TOKEN` (both in `.env`) + Docker image pushed
+- **E2E test files**: `tests/conftest.py` (fixtures), `tests/test_e2e.py` (5 tests)
+- **E2E validates**: machine lifecycle, log retrieval via platform API, public/private repo clone, cleanup guarantee
+- **Docker image**: Built with `--platform linux/amd64` (required by Fly.io, even on ARM hosts)
+
+## Default machine spec
+
+- VM size: `performance-2x` (2 shared CPUs, 4 GB RAM)
+- Region: `iad` (US East)
+- Image: `registry.fly.io/flaude:latest`

flaude-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to flaude will be documented here.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versions follow [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-25
+
+### Added
+- Initial release
+- `MachineConfig` for configuring Fly.io machine execution parameters
+- `run_and_destroy()` for fire-and-forget prompt execution
+- `run_with_logs()` for streaming log output
+- `ensure_app()` for idempotent Fly.io app creation
+- Automatic machine cleanup via `try/finally` guarantee
+- Support for cloning multiple repos into `/workspace`
+- Concurrent execution support
+
+[Unreleased]: https://github.com/ravi-hq/flaude/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ravi-hq/flaude/releases/tag/v0.1.0

flaude-0.1.0/CLAUDE.md

@@ -0,0 +1,46 @@
+<!-- ooo:START -->
+<!-- ooo:VERSION:0.14.0 -->
+# Ouroboros — Specification-First AI Development
+
+> Before telling AI what to build, define what should be built.
+> As Socrates asked 2,500 years ago — "What do you truly know?"
+> Ouroboros turns that question into an evolutionary AI workflow engine.
+
+Most AI coding fails at the input, not the output. Ouroboros fixes this by
+**exposing hidden assumptions before any code is written**.
+
+1. **Socratic Clarity** — Question until ambiguity ≤ 0.2
+2. **Ontological Precision** — Solve the root problem, not symptoms
+3. **Evolutionary Loops** — Each evaluation cycle feeds back into better specs
+
+```
+Interview → Seed → Execute → Evaluate
+    ↑                           ↓
+    └─── Evolutionary Loop ─────┘
+```
+
+## ooo Commands
+
+Each command loads its agent/MCP on-demand. Details in each skill file.
+
+| Command | Loads |
+|---------|-------|
+| `ooo` | — |
+| `ooo interview` | `ouroboros:socratic-interviewer` |
+| `ooo seed` | `ouroboros:seed-architect` |
+| `ooo run` | MCP required |
+| `ooo evolve` | MCP: `evolve_step` |
+| `ooo evaluate` | `ouroboros:evaluator` |
+| `ooo unstuck` | `ouroboros:{persona}` |
+| `ooo status` | MCP: `session_status` |
+| `ooo setup` | — |
+| `ooo help` | — |
+
+## Agents
+
+Loaded on-demand — not preloaded.
+
+**Core**: socratic-interviewer, ontologist, seed-architect, evaluator,
+wonder, reflect, advocate, contrarian, judge
+**Support**: hacker, simplifier, researcher, architect
+<!-- ooo:END -->

flaude-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to flaude
+
+Thank you for your interest in contributing!
+
+## Development setup
+
+**Prerequisites**: Python 3.11+, [uv](https://docs.astral.sh/uv/), a Fly.io account (for E2E tests only).
+
+```bash
+git clone https://github.com/ravi-hq/flaude.git
+cd flaude
+uv sync --extra dev
+```
+
+## Running tests
+
+```bash
+# Unit tests (no external dependencies)
+uv run pytest
+
+# With coverage
+uv run pytest --cov=flaude
+
+# E2E tests (requires FLY_API_TOKEN and CLAUDE_CODE_OAUTH_TOKEN in .env)
+cp .env.example .env   # fill in your credentials
+uv run pytest -m e2e
+```
+
+## Linting and type checking
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy flaude
+```
+
+## Submitting a pull request
+
+1. Fork the repo and create a branch from `main`.
+2. Make your changes with tests for any new behaviour.
+3. Run the linter and tests locally — CI must pass.
+4. Open a PR against `main` with a clear description of what and why.
+5. A maintainer will review and merge.
+
+## Reporting bugs
+
+Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.yml).
+
+## Requesting features
+
+Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.yml).
+
+## Code style
+
+- Black-compatible formatting enforced by `ruff format`.
+- Type annotations required on all public functions.
+- Async-first: use `httpx.AsyncClient` and `asyncio`; avoid blocking calls.
+
+## License
+
+By contributing you agree that your contributions will be licensed under the [MIT License](LICENSE).

flaude-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 flaude contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.