Brummel/Aura
1
0
Fork 0
Code Issues 31 Pull Requests Actions Packages Projects Releases Wiki Activity

Web frontend that drives the aura CLI binary and renders results (discussion idea) #72

New Issue
Closed
opened 2026-06-15 10:03:16 +02:00 by Brummel · 3 comments
Brummel commented 2026-06-15 10:03:16 +02:00
Owner
Copy Link
Copy Source

Status: discussion idea — NOT for automatic dispatch. This captures a design conversation; do not let the autonomous pipeline pick it up. Decide direction first.

Goal

A web interface that makes the existing aura CLI operations interactively invocable and renders each operation result in its natural visual form — the graph as the interactive graph, a run as a metric card, a sweep/runs as a sortable comparison table. Not a terminal that pipes stdout to the browser.

Shape — decoupled frontend, zero CLI changes

A standalone crates/aura-web crate (binary aura-web) that shells out to the aura binary as a subprocess and renders captured stdout/stderr/exit. No refactor of aura-cli; the existing cli_run.rs suite stays untouched. The only edit to an existing file is one members line in the root Cargo.toml.

  • Server: tiny_http, localhost-only. aura-web [--port N] [--aura-bin PATH] [--workdir DIR].
  • GET /api/commands serves a declarative command catalog (data file in the crate). POST /api/run {path,args} validates against the catalog, spawns aura <path> <args>, returns {output_kind, stdout, stderr, exit}.
  • Frontend builds forms from the catalog and renders by output_kind: Graph -> iframe srcdoc over the existing self-contained aura graph HTML; Run -> metric card; Sweep/RunsTable -> sortable table; Text/error -> pre / red pane.

Maintainability under CLI drift

The catalog (data, not code) is the single place a command is described. A guard test checks the catalog against aura --help and fails CI when the surfaces diverge. Adding a command = one catalog entry; no code change.

Ledger fit

  • Third face under C14 (engine stays UI-agnostic); distinct from the C22 egui playground (no shared scope/code).
  • Read-only: no topology authoring/wiring in the browser (C17/C22). Forms only fill arguments existing commands already accept; the graph renders read-only.
  • Determinism untouched (C1/C6): shelling out to aura run is just running the CLI.
  • Dependency policy: aura-web is a dev-tool crate; the frozen deploy bot never depends on it, so tiny_http enters no artifact (no feature-gate needed).

Open questions to discuss

  • In-workspace crate vs a separate repo.
  • Catalog format: Rust const vs catalog.toml.
  • Sequencing: worth doing now, or after the "World, part II" milestone?

(Full design notes drafted locally; not committed.)

**Status: discussion idea — NOT for automatic dispatch.** This captures a design conversation; do not let the autonomous pipeline pick it up. Decide direction first. ## Goal A web interface that makes the existing `aura` CLI operations interactively invocable and renders each operation result in its **natural visual form** — the graph as the interactive graph, a run as a metric card, a sweep/`runs` as a sortable comparison table. Not a terminal that pipes stdout to the browser. ## Shape — decoupled frontend, zero CLI changes A standalone `crates/aura-web` crate (binary `aura-web`) that shells out to the `aura` binary as a subprocess and renders captured stdout/stderr/exit. No refactor of `aura-cli`; the existing `cli_run.rs` suite stays untouched. The only edit to an existing file is one `members` line in the root `Cargo.toml`. - Server: `tiny_http`, localhost-only. `aura-web [--port N] [--aura-bin PATH] [--workdir DIR]`. - `GET /api/commands` serves a declarative command catalog (data file in the crate). `POST /api/run {path,args}` validates against the catalog, spawns `aura <path> <args>`, returns `{output_kind, stdout, stderr, exit}`. - Frontend builds forms from the catalog and renders by `output_kind`: Graph -> iframe srcdoc over the existing self-contained `aura graph` HTML; Run -> metric card; Sweep/RunsTable -> sortable table; Text/error -> pre / red pane. ## Maintainability under CLI drift The catalog (data, not code) is the single place a command is described. A **guard test** checks the catalog against `aura --help` and fails CI when the surfaces diverge. Adding a command = one catalog entry; no code change. ## Ledger fit - Third face under C14 (engine stays UI-agnostic); distinct from the C22 egui playground (no shared scope/code). - Read-only: no topology authoring/wiring in the browser (C17/C22). Forms only fill arguments existing commands already accept; the graph renders read-only. - Determinism untouched (C1/C6): shelling out to `aura run` is just running the CLI. - Dependency policy: `aura-web` is a dev-tool crate; the frozen deploy bot never depends on it, so `tiny_http` enters no artifact (no feature-gate needed). ## Open questions to discuss - In-workspace crate vs a separate repo. - Catalog format: Rust const vs `catalog.toml`. - Sequencing: worth doing now, or after the "World, part II" milestone? (Full design notes drafted locally; not committed.)
Brummel added the idea label 2026-06-15 10:03:16 +02:00
Brummel commented 2026-07-09 17:31:52 +02:00
Author
Owner
Copy Link
Copy Source

Triage 2026-07-09 (tree at 68317ec) — reconciliation note: the body's design predates three landings and would describe a dead CLI if executed as written:

  • The argv surface was rebuilt twice since 2026-06-15: clap with the usage/runtime exit-code partition (#175), then the verb dissolution (#210/#220 — sweep/mc/walkforward/generalize are blueprint-generic sugar over content-addressed campaign documents, stop defaults via #217). A shell-out command catalog guard-tested against aura --help would bind to none of today's shapes.
  • The render-results half shipped differently: the web-from-disk face (aura chart / aura graph emitting self-contained static HTML) — no server. The "local server + run/replay clock controls" thread remains open in the design ledger's open-threads section (docs/design/INDEX.md).
  • Any future page is bound by the shared-stylesheet rule (crates/aura-cli/assets/aura.css, #209).

Still a valid idea-anchor for the drive-operations half; a fresh design over the document-driven CLI (campaign/process vocabularies) replaces the 2026-06-15 catalog shape whenever this is picked up.

Triage 2026-07-09 (tree at 68317ec) — reconciliation note: the body's design predates three landings and would describe a dead CLI if executed as written: - The argv surface was rebuilt twice since 2026-06-15: clap with the usage/runtime exit-code partition (#175), then the verb dissolution (#210/#220 — sweep/mc/walkforward/generalize are blueprint-generic sugar over content-addressed campaign documents, stop defaults via #217). A shell-out command catalog guard-tested against `aura --help` would bind to none of today's shapes. - The render-results half shipped differently: the web-from-disk face (`aura chart` / `aura graph` emitting self-contained static HTML) — no server. The "local server + run/replay clock controls" thread remains open in the design ledger's open-threads section (docs/design/INDEX.md). - Any future page is bound by the shared-stylesheet rule (crates/aura-cli/assets/aura.css, #209). Still a valid idea-anchor for the drive-operations half; a fresh design over the document-driven CLI (campaign/process vocabularies) replaces the 2026-06-15 catalog shape whenever this is picked up.
claude commented 2026-07-21 10:36:44 +02:00
Collaborator
Copy Link
Copy Source

Re-anchoring after #295/#300 (2026-07-21): the goal — a web face that renders each operation's result in its natural visual form — stands, but the Shape section has drifted architecturally.

The C25 amendment (docs/design/INDEX.md, 'control surfaces are projections', 2026-07-20, #295) fixes the layering this issue predates: the text artifact vocabulary (blueprints, process/campaign documents, registry records) is the canonical layer, and every control surface is a projection/executor over those artifacts — not a wrapper assembling argv strings for the binary. The decided document-first completion (#300) additionally shrinks the CLI toward a small executor verb set, so a declarative catalog mirroring aura --help (this issue's maintainability mechanism) would be built against a deliberately shrinking flag surface.

A future web face would author/read documents and drive the library surface (crates/aura-runner, extracted by #295) or the executor verbs — closer to 'render the registry and the documents' than 'form-fill the flags'. Related: rendering/presentation deliberately stayed in the shell until this face exists (#295 design triage: extraction deferred to the cycle that builds the C22 web face; this issue and #150 are its tracked consumers).

Still a discussion idea per its own header — direction is the owner's call; not dispatch-ready.

Re-anchoring after #295/#300 (2026-07-21): the goal — a web face that renders each operation's result in its natural visual form — stands, but the Shape section has drifted architecturally. The C25 amendment (docs/design/INDEX.md, 'control surfaces are projections', 2026-07-20, #295) fixes the layering this issue predates: the text artifact vocabulary (blueprints, process/campaign documents, registry records) is the canonical layer, and every control surface is a projection/executor over those artifacts — not a wrapper assembling argv strings for the binary. The decided document-first completion (#300) additionally shrinks the CLI toward a small executor verb set, so a declarative catalog mirroring `aura --help` (this issue's maintainability mechanism) would be built against a deliberately shrinking flag surface. A future web face would author/read documents and drive the library surface (crates/aura-runner, extracted by #295) or the executor verbs — closer to 'render the registry and the documents' than 'form-fill the flags'. Related: rendering/presentation deliberately stayed in the shell until this face exists (#295 design triage: extraction deferred to the cycle that builds the C22 web face; this issue and #150 are its tracked consumers). Still a discussion idea per its own header — direction is the owner's call; not dispatch-ready.
claude commented 2026-07-21 15:11:22 +02:00
Collaborator
Copy Link
Copy Source

Closed as ratified drop (owner decision, 2026-07-21, idea-cull round): the core premise (wrap the aura argv surface, catalog mirrors --help) is superseded by the C25 amendment — control surfaces are projections over the text-artifact vocabulary. A future web face would be brainstormed fresh against the aura-runner/document layer; this body carries nothing C25 does not already state.

Closed as ratified drop (owner decision, 2026-07-21, idea-cull round): the core premise (wrap the aura argv surface, catalog mirrors --help) is superseded by the C25 amendment — control surfaces are projections over the text-artifact vocabulary. A future web face would be brainstormed fresh against the aura-runner/document layer; this body carries nothing C25 does not already state.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
BLOCKER
Core functionality blocked; preempts other selection
 bug
Observable misbehaviour
 feature
Substantial extension; no full spec required
 idea
Droppable; no commitment
No Label idea
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
claude (Claude) Brummel
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Brummel/Aura#72
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?