flow5ctl 0.1.0__tar.gz

flow5ctl-0.1.0/.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,json,toml}]
+indent_size = 2
+
+[*.md]
+# trailing whitespace is significant for markdown line breaks
+trim_trailing_whitespace = false
+
+[*.{dat,csv,stl}]
+# solver data files — leave exactly as produced
+trim_trailing_whitespace = false
+insert_final_newline = false

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

@@ -0,0 +1,43 @@
+name: Bug report
+description: flow5ctl crashed, failed, or did something unexpected
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction
+      description: Commands or MCP calls, plus the smallest `design.yaml` that shows it.
+    validations:
+      required: true
+  - type: input
+    id: flow5-version
+    attributes:
+      label: flow5 version (`flow5 --version`)
+      placeholder: flow5 v7.57
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+    validations:
+      required: true
+  - type: dropdown
+    id: frontend
+    attributes:
+      label: How were you using it?
+      options: ["MCP (Claude Desktop or other)", "CLI", "Both", "Neither / library"]
+    validations:
+      required: true

flow5ctl-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: flow5 itself (the solver)
+    url: https://github.com/techwinder/flow5/issues
+    about: Bugs in flow5 belong upstream. Please also tell us, so we can record it in the compatibility matrix.
+  - name: Discuss the design
+    url: https://github.com/97kuek/flow5ctl/blob/main/docs/ARCHITECTURE.md
+    about: The project is in its design phase. If a decision looks wrong, open a normal issue and say why.

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

@@ -0,0 +1,28 @@
+name: Feature request
+description: Something flow5ctl should be able to do
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: workflow
+    attributes:
+      label: What are you trying to do?
+      description: |
+        Describe the design task, not the feature. What is the loop you repeat by
+        hand today? That is what this project is trying to remove.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would you like flow5ctl to do?
+  - type: dropdown
+    id: aircraft
+    attributes:
+      label: What do you design?
+      options:
+        - Human-powered aircraft (Birdman Rally / HPA)
+        - RC glider (F3B / F3F / F5J / DLG)
+        - Small UAV
+        - Other / several
+    validations:
+      required: true

flow5ctl-0.1.0/.github/ISSUE_TEMPLATE/physics_issue.yml

@@ -0,0 +1,47 @@
+name: Physics / wrong result
+description: A number flow5ctl produced is aerodynamically wrong or misleading
+labels: ["physics"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **These are our most serious bugs.** People build aircraft from this, and some
+        of those aircraft carry a pilot. A plausible wrong number is worse than a crash.
+  - type: textarea
+    id: what
+    attributes:
+      label: What was reported, and what should it be?
+      placeholder: |
+        flow5ctl reported a static margin of 29.8 %.
+        Hand calculation from the neutral point gives 8.2 %.
+    validations:
+      required: true
+  - type: textarea
+    id: how-you-know
+    attributes:
+      label: How do you know the correct value?
+      description: Hand calculation, a second solver, wind-tunnel or flight data, published results.
+    validations:
+      required: true
+  - type: textarea
+    id: setup
+    attributes:
+      label: Design and analysis setup
+      description: Your `design.yaml` (or the smallest version that reproduces it) and the analysis conditions.
+      render: yaml
+    validations:
+      required: true
+  - type: input
+    id: flow5-version
+    attributes:
+      label: flow5 version
+      description: Output of `flow5 --version` — not the version shown by the app bundle.
+      placeholder: flow5 v7.57
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+    validations:
+      required: true

flow5ctl-0.1.0/.github/ISSUE_TEMPLATE/platform_report.yml

@@ -0,0 +1,54 @@
+name: Platform report
+description: Tell us whether flow5ctl works on your OS and flow5 version
+labels: ["platform"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Everything in [docs/FLOW5-INTERFACE.md](../blob/main/docs/FLOW5-INTERFACE.md)
+        was verified on macOS with flow5 7.57. Linux and Windows are untested, and
+        reports are how we find out what we cannot check ourselves.
+
+        The quickest useful report is one command:
+
+        ```
+        python3 poc/verify_platform.py
+        ```
+
+        It runs flow5 a few times, checks each documented behaviour, and prints a
+        report to paste below. It needs only the standard library and an installed
+        flow5, and writes nothing outside a temporary directory.
+  - type: input
+    id: os
+    attributes:
+      label: Operating system and version
+    validations:
+      required: true
+  - type: input
+    id: flow5-version
+    attributes:
+      label: flow5 version (`flow5 --version`)
+    validations:
+      required: true
+  - type: input
+    id: install
+    attributes:
+      label: How did you install flow5?
+      placeholder: Homebrew cask / .deb / installer / built from source
+  - type: textarea
+    id: results
+    attributes:
+      label: Output of `python3 poc/verify_platform.py`
+      description: Paste it whole, including the header lines.
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: differences
+    attributes:
+      label: Anything else worth knowing?
+      description: |
+        Where flow5 installed itself, whether it needed a display, and anything the
+        script did not cover. A `[ info ]` line saying this platform does NOT crash on
+        a combined script is especially interesting — it would mean flow5ctl's two-pass
+        design is unnecessary there.

flow5ctl-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+## What and why
+
+<!-- What does this change, and what problem does it solve? Link the issue if there is one. -->
+
+## Evidence
+
+<!-- Required for any claim about flow5's behaviour or about a physical result. -->
+
+- [ ] I verified this by **running** it (say which flow5 version and OS)
+- [ ] I verified this by **reading upstream source** (cite the file)
+- [ ] Not applicable — this change makes no claim about flow5 or about physics
+
+flow5 version used: <!-- `flow5 --version` output -->
+OS: <!-- -->
+
+## Checklist
+
+- [ ] No flow5 source code is copied into this repository
+      ([ADR-0006](../docs/adr/0006-licensing-and-the-gpl-boundary.md))
+- [ ] No solver output or generated artifacts are committed (`poc/work/`, `build/`)
+- [ ] Any new fact in `docs/FLOW5-INTERFACE.md` is marked **[run]** or **[src]** and cited
+- [ ] If this changes an accepted decision, a new ADR supersedes the old one
+- [ ] If this touches geometry or the result parser, golden tests were updated
+      deliberately — and the PR says why the old values were wrong
+- [ ] Both front-ends are in step (MCP and CLI), with `--json` matching the MCP payload
+
+## Physics
+
+<!-- Delete if this change cannot affect a number a user might act on. -->
+
+- [ ] I have stated the limits that apply to any result this produces
+- [ ] This does not let a stability figure come from a non-T7 polar
+- [ ] This does not present a non-finite value as a result

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

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    name: Repository checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      # Runs without flow5 installed.
+      - name: Docs, licence and artifact hygiene
+        run: python3 tools/check_docs.py
+
+  test:
+    name: Tests (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Install
+        run: uv sync --group dev --extra plot
+
+      - name: Lint
+        run: uv run ruff check src tests tools poc
+
+      # flow5 is not available on CI runners, so the solver-dependent tests are
+      # deselected. They run against a real flow5 on a developer machine — see
+      # poc/README.md. The rest of the suite must pass without it, which is what
+      # keeps the domain layer independent of the adapter (ADR-0002).
+      - name: Tests
+        run: uv run pytest -q -m "not needs_flow5"

flow5ctl-0.1.0/.github/workflows/release.yaml

@@ -0,0 +1,96 @@
+name: Release
+
+# Publishing is deliberately tag-triggered rather than automatic on main: a release
+# is a decision, not a side effect of merging. See docs/RELEASING.md.
+on:
+  push:
+    tags: ["v*"]
+  # Validate everything a release runs, without cutting a tag. The publish and
+  # release jobs below are guarded to tags, so a dispatch builds and checks only.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      # The tag and the packaged version must agree. Getting this wrong publishes
+      # something no tag points at, and PyPI will not let the filename be reused.
+      - name: Tag matches the packaged version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(uv run --no-project --with hatchling python -c \
+            'import tomllib,pathlib;print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"])')"
+          echo "tag=$tag  pyproject=$version"
+          [ "$tag" = "$version" ] || { echo "::error::tag $tag does not match version $version"; exit 1; }
+
+      - name: Install
+        run: uv sync --group dev --extra plot
+
+      - name: Lint
+        run: uv run ruff check src tests tools poc
+
+      # flow5 is not on CI runners, so the solver tests are deselected here exactly
+      # as in ci.yml. A release must not be cut on a red tree.
+      - name: Tests
+        run: uv run pytest -q -m "not needs_flow5"
+
+      - name: Repository checks
+        run: python3 tools/check_docs.py
+
+      - name: Build
+        run: uv build
+
+      # Catches a malformed README before PyPI rejects the upload.
+      - name: Check metadata
+        run: uvx twine check dist/*
+
+      - uses: actions/upload-artifact@v5
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # PyPI trusted publishing; no API token is stored anywhere
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github_release:
+    name: GitHub release
+    needs: publish
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/download-artifact@v5
+        with:
+          name: dist
+          path: dist/
+      - name: Create the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/* \
+            --title "$GITHUB_REF_NAME" \
+            --notes "See [CHANGELOG.md](https://github.com/${GITHUB_REPOSITORY}/blob/main/CHANGELOG.md)."

flow5ctl-0.1.0/.gitignore

@@ -0,0 +1,60 @@
+# ── flow5ctl generated artifacts ────────────────────────────────────
+# design.yaml is the source of truth; everything below is regenerable.
+build/
+results/
+.flow5ctl/
+*.fl5
+*.stl
+
+# ── PoC verification workspace ──────────────────────────────────────
+# poc/lib and poc/case_*.py are the reproducible harness and ARE tracked.
+# Everything they produce is not.
+poc/work/
+poc/out/
+poc/*_run.log
+
+# ── Validation against real aircraft ────────────────────────────────
+# Reconstructions of other teams' aircraft, and the logs comparing flow5ctl
+# against their published data, stay out of the public repository. They are
+# someone else's design work; publishing them is not ours to decide.
+# Findings about flow5's own behaviour DO belong in docs/ — anonymised.
+validation/
+examples/*-real-*.yaml
+
+# Real flow5 project files kept as references for what a practitioner's own model
+# contains — mesh density, surface counts, airfoil choices. Reading one is how the
+# Reynolds ladder default got fixed. They are someone's actual aircraft, so they
+# stay local; what is learned from them goes into docs/ as a finding.
+*.xfl
+*.fl5
+
+# Upstream flow5 source fetched for reference only.
+# flow5 is GPL-3.0 and must never be committed here — see
+# docs/adr/0006-licensing-and-the-gpl-boundary.md
+poc/ref/
+
+# ── Python ──────────────────────────────────────────────────────────
+# uv.lock IS committed: it makes CI and a contributor's environment reproducible,
+# and flow5ctl is installed as a tool more often than depended on as a library.
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.env
+dist/
+build-py/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# ── Editors / OS ────────────────────────────────────────────────────
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/*
+!.vscode/extensions.json
+*.swp
+*~

flow5ctl-0.1.0/AGENTS.md

@@ -0,0 +1,191 @@
+# AGENTS.md
+
+Instructions for AI agents working **on** this repository.
+
+> If you are an agent **using** flow5ctl to design an aircraft, this is the wrong
+> file. Read [docs/DESIGN-GUIDE.md](docs/DESIGN-GUIDE.md) instead.
+
+## What this project is
+
+`flow5ctl` lets AI agents design low-Reynolds-number aircraft by driving
+[flow5](https://flow5.tech), a potential-flow solver, in its headless batch mode.
+It ships as an MCP server and a CLI over one shared core.
+
+The core, the CLI and the MCP server all work. See
+[the roadmap](docs/ROADMAP.md) for what is left.
+
+## Layout
+
+```
+src/flow5ctl/
+  model/         design.yaml schema, presets
+  geometry/      areas, span, MAC, mass properties       ← no flow5 knowledge
+  advisor/       guardrails and thresholds               ← no flow5 knowledge
+  viz/           chart rendering and the validated palette
+  flow5/         probe, xmlgen, runner, results, summary ← the ONLY flow5-aware package
+  usecases/      define, edit, analyze, trim, sweep, plot, gui  ← the only orchestrators
+  presets/       *.yaml — data, so a new aircraft class needs no code
+  cli.py         a thin adapter over the use cases
+  mcp_server.py  the second thin adapter; no domain logic, no flow5 knowledge
+poc/             the verification harness that produced the measured claims in docs/
+examples/        worked designs and a study, used as documentation
+tests/           golden values and real flow5 output; fixtures/ pins the parser traps
+```
+
+The dependency rule is one way: `cli / mcp_server → usecases → geometry/advisor/model`,
+with `flow5/` reachable only from `usecases/`. Nothing in `geometry/`, `advisor/` or
+`model/` may import `flow5/`, so the aerodynamic model stays testable with flow5
+absent — and CI relies on that.
+
+The two front-ends must stay in step. A capability added to one and not the other is
+an incomplete change ([ADR-0002](docs/adr/0002-one-core-two-frontends.md)).
+
+## Working on it
+
+```bash
+uv sync --group dev --extra plot    # the extra is what chart tests need
+uv run pytest -q                    # everything, including the real flow5 runs
+uv run pytest -q -m "not needs_flow5"   # what CI runs
+uv run ruff check src tests tools poc
+python3 tools/check_docs.py
+```
+
+The MCP server has two test layers, and they check different things:
+`tests/test_mcp_server.py` runs it in process for the adapter's own contract, while
+`tests/test_mcp_stdio.py` launches `flow5ctl mcp` as a subprocess and talks the
+protocol — that is the only place a PNG surviving base64 transport, or a rejected
+request coming back as an error result instead of killing the server, is actually
+verified.
+
+## Read before you change anything
+
+In this order:
+
+1. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — the layering and why it is that way
+2. [docs/adr/](docs/adr/) — decisions already made, with their reasoning
+3. [docs/FLOW5-INTERFACE.md](docs/FLOW5-INTERFACE.md) — verified facts about flow5
+4. [docs/DOMAIN-MODEL.md](docs/DOMAIN-MODEL.md) — the vocabulary; use these words
+
+## Rules
+
+### Never invent facts about flow5
+
+[docs/FLOW5-INTERFACE.md](docs/FLOW5-INTERFACE.md) marks every claim **[run]**
+(verified by executing flow5) or **[src]** (read from a named upstream source file).
+Anything not marked either way is not established.
+
+If you need a fact that is not there:
+
+- read it from the upstream source at [techwinder/flow5](https://github.com/techwinder/flow5), or
+- verify it by running flow5, then
+- add it to the reference with its marker and citation.
+
+Do not guess an XML tag name. Unknown tags are silently ignored by flow5, so a
+guess produces a subtly wrong analysis rather than an error.
+
+### Never copy flow5 source code into this repository
+
+flow5 is GPL-3.0; flow5ctl is Apache-2.0. Read the source to learn the interface and
+describe it in your own words with a citation. See
+[ADR-0006](docs/adr/0006-licensing-and-the-gpl-boundary.md).
+
+### Physics correctness outranks everything
+
+A crash is recoverable. A plausible wrong number that someone builds an aircraft
+around is not. Specifically:
+
+- Never let a code path produce stability results from a non-T7 polar. A T1 polar
+  will happily return an eigenvalue of `5.995e+51`.
+- Never emit `PLANFORM` or `PROJECTED` reference dimensions
+  ([ADR-0005](docs/adr/0005-compute-reference-dimensions-ourselves.md)).
+- Never report an L/D from an inviscid run without labelling it. Measured: an
+  inviscid run omitted 93 % of the drag at α=0°.
+- Never mix the two viscous methods inside one comparison; they disagree by 10–25 %.
+- Never report Dutch-roll or short-period figures from flow5 7.57 — they are wrong.
+- Never present a non-finite cell (`inf`, `nan`) as a result.
+- Never treat `Static margin` from a flow5 file as a fraction; it is a percentage.
+- Never attribute an operating-point file by its directory — flow5 duplicates those
+  files across every polar's directory with the wrong contents.
+- Never widen an α sweep past the airfoil's stall to "get more data".
+
+If you are unsure whether something is physically sound, say so in the PR rather than
+guessing.
+
+### Check both flow5's exit code and its stdout
+
+`0` means nothing — flow5 exits 0 for a rejected script and for a run that failed
+every operating point. Non-zero means it **crashed** (exit 139, SIGSEGV, observed
+reproducibly). Success needs the stdout markers in
+[docs/FLOW5-INTERFACE.md §6](docs/FLOW5-INTERFACE.md); crash detection needs the exit
+code. Use both.
+
+Scope marker matches carefully: `Made 0 valid analysis pairs (boat, polar) to run`
+is printed on **every** run, so matching on `analysis pairs` alone reports failure on
+every success.
+
+### Never emit both script sections in one file
+
+A script containing both `<foil_analysis>` and `<Plane_analysis>` segfaults flow5.
+Two invocations, always — [ADR-0009](docs/adr/0009-two-pass-solver-invocation.md).
+The generator must make the single-file form impossible to express.
+
+### Never write a new output parser
+
+flow5's output has at least seven traps that produce plausible wrong numbers rather
+than errors ([docs/FLOW5-INTERFACE.md §5](docs/FLOW5-INTERFACE.md)). Extend
+[poc/lib/parse.py](poc/lib/parse.py), keep its self-checks — especially validating
+the row count against the file's own `Nbr. of data points` — and do not "simplify"
+its oddities away. Every one of them is load-bearing
+([ADR-0010](docs/adr/0010-treat-solver-output-as-hostile.md)).
+
+### Respect the layering
+
+`front-ends → use cases → domain → flow5 adapter`, one way only. Nothing in
+`domain/` may import the adapter; the aerodynamic model must be testable with flow5
+absent. Do not add flow5-specific knowledge outside the adapter, and do not add
+domain logic to a front-end — see [ADR-0002](docs/adr/0002-one-core-two-frontends.md).
+
+### Keep the two front-ends in step
+
+Every capability appears in both the MCP server and the CLI, and
+`flow5ctl <verb> --json` emits exactly the MCP tool payload. A change to one without
+the other is incomplete.
+
+### Changing a decision means writing an ADR
+
+The ADRs record *why*. If you conclude one is wrong, add a new ADR that supersedes
+it, with the new reasoning. Do not silently contradict an accepted decision in code.
+
+## Conventions
+
+- Use the vocabulary in [docs/DOMAIN-MODEL.md](docs/DOMAIN-MODEL.md). Say *section*,
+  *analysis*, *operating point*, *design*. Do not introduce synonyms.
+- SI internally, always. Unit conversion happens at the edges only.
+- Angles are degrees in `design.yaml` and in every user-facing value, radians inside
+  geometry code. Name variables accordingly (`twist_deg`, `alpha_rad`).
+- `design.yaml` is the source of truth; XML is a build artifact. Never hand-author
+  XML in a fixture unless it is deliberately testing the parser.
+- Prose in documentation is English. User-facing Japanese lives in `README.ja.md`
+  and `docs/ja/`.
+
+## Testing
+
+- Geometry has golden tests against hand-computed values. Changing geometry code
+  means changing them deliberately, never to make a failure go away.
+- Solver-facing tests use recorded flow5 output where possible so the suite runs
+  without flow5 installed. Tests that need the real binary are marked and skipped
+  when it is absent.
+- The spike design in [docs/log/2026-09-03-feasibility-spike.md](docs/log/2026-09-03-feasibility-spike.md)
+  is the canonical end-to-end fixture.
+- [`poc/`](poc/) holds the verification harness that produced every measured claim in
+  the docs. If you change something the docs assert, re-run the relevant case and
+  update both. `poc/work/` and `poc/ref/` are gitignored — never commit solver output,
+  and never commit upstream flow5 source.
+
+## When you finish
+
+- Say what you verified by running versus what you reasoned about.
+- If you changed anything in `docs/FLOW5-INTERFACE.md`, state which flow5 version you
+  verified against.
+- If a task turned out to be blocked, finish everything else and say plainly what you
+  left and why.