feat: add --describe flag to strategy-builder CLI by hardyjosh · Pull Request #2548 · rainlanguage/raindex

hardyjosh · 2026-04-14T15:53:14Z

Caution

Stacks on #2551. Merge that first.

The registry-side companion work that uses the template-fallback operator (#2551) to produce readable --describe output for existing strategies is in ST0x-Technology/st0x.registry#9 — describe works fine without it, but strategy field names will contain raw ${...} placeholders until that PR lands.

Motivation

CLI users and AI agents need a way to learn a registry's full configuration without reading the underlying .rain YAML files or running the interactive wizard. That discovery loop is currently: curl the registry file → resolve the settings URL → curl each strategy → parse the YAML by hand. Every agent we tested (6/6) burned 4+ tool calls just discovering token addresses.

Solution

Add --describe — emits a full markdown dump of the registry: every strategy, its deployments, required/optional fields (with presets and defaults), select-tokens, deposits, plus usage documentation and the address:calldata output format.

Intended as a self-generating skill. An agent can run once against a registry and have everything it needs to construct non-interactive deploy commands from a natural-language request. Each deployment includes an Example command with the exact flags and placeholders pre-filled.

Also bundled in this PR (small polish items):

Each field tagged (required) or (optional, default: X) so it is obvious which flags are mandatory
strategy-builder stdout lines are now labelled with # comment headers describing what each transaction does (approve / deploy / meta emission). Safe for cast send pipelines (with a one-line skip) and for stox submit (updated in feat: skip # comment lines in cli submit input ST0x-Technology/st0x.liquidity#578)
Usage section documents the # comment convention, the --tokens companion, the cast-send pipe idiom (with comment-skip), the units convention (human-readable decimal), and the build-once guidance for running the binary directly without nix develop noise

Checks

made this PR as small as possible
unit-tested any new functionality
linked any relevant issues or PRs
included screenshots (if this involves a front-end change)

Summary by CodeRabbit

New Features
- Added strategy-builder CLI command with interactive, describe, and tokens modes for deploying order strategies from registry configurations.
Bug Fixes
- Made token logoURI field optional in remote token configurations.
Documentation
- Updated YAML configuration: replaced gui: sections with builder: throughout codebase.
- Renamed public APIs from GUI-centric to builder-centric terminology across CLI, SDK, and UI components.

coderabbitai · 2026-04-14T15:53:21Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: fecb064a-e21d-4fc6-8884-69cf52dc592e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

Walkthrough

This PR rebrands the orderbook's "GUI" architecture to an "order builder" architecture, moving core builder logic from the WASM-only js_api crate into a shared raindex_order_builder module in crates/common. It adds a new CLI strategy_builder command with interactive, descriptive, and token-listing modes, and systematically renames all GUI-related types, methods, configuration sections, and documentation references to builder equivalents.

Changes

Cohort / File(s)	Summary
Documentation & Architecture Updates `ai_commands/sdk-documentation-update.md`, `crates/bindings/ARCHITECTURE.md`, `crates/js_api/ARCHITECTURE.md`, `crates/settings/ARCHITECTURE.md`, `packages/orderbook/ARCHITECTURE.md`, `packages/ui-components/ARCHITECTURE.md`	Updated guidance and architecture docs to reference "order builder" instead of "GUI" or "gui" naming, including example component names, module names, method names, and terminology throughout descriptions.
Core Builder Logic Library `crates/common/src/lib.rs`, `crates/common/src/raindex_order_builder/...`	Extracted and reorganized builder-related logic into a shared `raindex_order_builder` module in common. Added comprehensive field values, deposits, select tokens, order operations, state management, and validation submodules with corresponding public APIs and error types.
Common Crate Refactoring `crates/common/src/add_order.rs`, `crates/common/src/dotrain_order.rs`, `crates/common/src/parsed_meta.rs`, `crates/common/src/raindex_client/orders.rs`, `crates/common/src/test_helpers.rs`, `crates/common/Cargo.toml`	Switched metadata state handling and imports from `DotrainGuiStateV1` to `OrderBuilderStateV1`, renamed helper functions from "gui" to "builder" terminology, and added new dependencies (base64, bincode, sha2).
CLI Strategy Builder Command `crates/cli/src/commands/strategy_builder/...`, `crates/cli/src/commands/mod.rs`, `crates/cli/src/lib.rs`, `crates/cli/Cargo.toml`	Added new interactive CLI wizard for order builder workflows. Includes interactive mode with terminal UI helpers, describe mode for registry documentation generation, tokens mode for token listing, and default mode for deployment calldata generation. Added dependencies for terminal UI (crossterm, dialoguer, console) and HTTP client (reqwest).
Settings Module Refactoring `crates/settings/src/lib.rs`, `crates/settings/src/order_builder.rs`, `crates/settings/src/deployment.rs`, `crates/settings/src/order.rs`, `crates/settings/src/yaml/...`	Renamed configuration module from `gui` to `order_builder`, updated all config struct/enum names from `Gui` to `OrderBuilder`, changed YAML root key parsing from `"gui"` to `"builder"`, added fallback interpolation support in context variables, and updated context profile from `ContextProfile::Gui` to `ContextProfile::Builder`.
Remote Token Config `crates/settings/src/remote/tokens.rs`	Made `logoURI` field optional with default serde handling.
JS/WASM API Reorganization `crates/js_api/src/lib.rs`, `crates/js_api/src/raindex_order_builder/...`	Replaced `gui` module with `raindex_order_builder` module. Removed WASM-only implementations; created new thin wrapper `RaindexOrderBuilder { inner, state_update_callback }` that delegates to common builder logic. Re-exported all builder APIs (deposits, field values, select tokens, order operations, state management) with corresponding struct/method name updates.
JS/WASM API Deletions `crates/js_api/src/gui/...` (deleted)	Removed the entire `gui` module including all `DotrainOrderGui` WASM exports and their associated types/tests.
Registry WASM Integration `crates/js_api/src/registry.rs`	Updated WASM registry API from `getGui(...)` to `getOrderBuilder(...)`, switched error types from `GuiError` to builder error variants, and retargeted order metadata accessors to use builder configuration types.
SDK Package Documentation & Tests `packages/orderbook/README.md`, `packages/orderbook/ARCHITECTURE.md`, `packages/orderbook/test/js_api/...`, `packages/ui-components/...`	Updated all documentation examples and test suite from GUI to builder terminology, including YAML sections, API calls, type assertions, and provider/hook naming in UI components.
Submodule Update `lib/rain.interpreter`	Updated interpreter submodule commit hash.

Sequence Diagram(s)

The changes do not introduce new feature flows that would benefit from sequence diagram visualization. The primary modifications are architectural refactoring (moving logic between crates, renaming types) and terminology updates (GUI→builder), rather than changes to control flow or inter-component interaction patterns. The new CLI interactive wizard is a straightforward user-input loop that exists within a single module boundary.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related issues

Extraction of builder logic from WASM-only layer into shared common library, enabling both CLI and web consumption of the same builder API surface.

Poem

🐰 From GUI to Builder, the logic takes flight,
Shared in the commons, extracted just right!
Interactive wizards and tokens galore,
Terminal charms with style at the core.
One builder to rule them, CLI and web—
Hop on, let's deploy from the registry ebb! 🌾

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'feat: add --describe flag to strategy-builder' accurately describes the primary change: adding a new --describe flag to the strategy-builder CLI command. It is specific, concise, and reflects the main feature introduced.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch describe-registry

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

hardyjosh · 2026-04-14T15:53:27Z

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

feat: add --describe flag to strategy-builder CLI #2548 👈 (View in Graphite)
feat: template fallback operator ${expr || 'default'} #2551 : 1 other dependent PR (#2552 )
feat: add --tokens flag to list deployment-specific tokens #2549
feat: add interactive mode to strategy-builder CLI #2546
feat: add strategy-builder CLI subcommand #2544
Consolidate JS API gui module into common crate and rename GUI to OrderBuilder #2479
main

This stack of pull requests is managed by Graphite. Learn more about stacking.

hardyjosh · 2026-04-15T20:30:31Z

@coderabbitai review

coderabbitai · 2026-04-15T20:30:37Z

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Guided deployment flow mirroring the webapp: 1. Fuzzy-select strategy from registry (shows name + description) 2. Pick deployment (shows name + description) 3. Select tokens with search across available token lists 4. Fill required fields with preset selection or custom input 5. Optional deposits with preset amounts 6. Enter owner address 7. Generate calldata — print to stdout or save to .calldata file Usage: raindex strategy-builder -i --registry <url> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…ments - Add bold/dim/underlined styling via console crate - Structured headings and separators between sections - Ask for owner address first (needed for balance display) - Show token symbol/name instead of raw key in deposit prompts - Show token balance when prompting for deposits - Remove stox-specific language from output hints — describe the format (address:calldata lines) so any submitter can consume it - Improve preset display with bold labels and dim values Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add max_length(10) to all Select/FuzzySelect prompts so they scroll within a fixed window instead of reprinting the full list on every keystroke. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Long descriptions were wrapping to multiple lines, making each list item 2-3 rows tall and causing the display to scroll erratically. Now truncates all display strings to fit within the terminal width. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The core issue was dialoguer redrawing the list on every keystroke, wiping lines printed above it. Fix: keep list items short (just keys or names), then show the full name + description AFTER the user makes their choice. This way dialoguer only redraws its own compact list. Also: "Generating Calldata" is now a status message, not a heading. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

FuzzySelect redraws on every keystroke, which with long token lists causes severe terminal corruption. Replace with a printed list of all available tokens, then a text input that matches by symbol, name substring, or raw address. Shows disambiguation when multiple tokens match a partial query. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

coderabbitai · 2026-04-15T21:37:35Z

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

- RAII TerminalGuard restores raw mode/alt screen/cursor on panic - Explicit 0 => arm + unreachable! for output_choice match - saturating_sub for cursor position u16 cast to avoid underflow

`raindex strategy-builder --tokens --strategy <key> --deployment <key> --registry <url>` emits a markdown table of all tokens registered for that specific deployment (symbol, name, address, decimals). This avoids bloating --describe output with potentially hundreds of tokens per deployment. --describe will reference this command so an agent only fetches the token list for the deployment it actually needs.

When a template path resolves to a missing token field (select-token not yet selected) and a fallback literal is supplied, substitute the literal instead of leaving the placeholder raw or erroring. Syntax: ${path} — current behaviour ${path || 'fallback'} — new: substitute literal on missing token ${path || "fallback"} — double quotes also accepted Backwards-compatible: existing templates without `||` behave identically. The fallback only kicks in on PropertyNotFound("token") (i.e. unresolved select-token), not on other resolution errors. This unblocks --describe emitting readable field names/descriptions when no token has been selected yet.

Emits a full markdown dump of a registry: strategies, their deployments, fields (with presets and defaults), select-tokens, deposits, plus usage documentation and the address:calldata output format. Intended use: an AI agent or human can run once to learn everything needed to construct a non-interactive deploy command for the registry. The output includes example commands for each deployment with all required flags filled in as placeholders.

Extend the usage section with: - cast send pipe example for signing without the stox CLI - Explicit note that approvals only appear when depositing - Explanation of how to pick token addresses (block explorer / token list) since these are not in the registry itself - Clarification that --owner must be a signing address Goal: minimize the upfront context a calling agent needs before running --describe. Most of what a user would otherwise need to explain in the prompt is now emitted by the tool itself.

Each deployment with select-tokens now includes a code block showing how to fetch the actual valid token addresses for that deployment via raindex strategy-builder --tokens. Avoids inlining hundreds of token entries in describe output.

- Mark each field as (required) or (optional, default: X) - Add a units convention note to the usage section - Add a build-once guidance section (run binary directly, avoid the npm install noise from the nix develop shellHook) - Label calldata stdout lines with # comment headers describing each tx - Update the cast-send pipe example to skip # comment lines and blank lines - Document the # comment convention in the output format section The # comment lines are safe for any submitter that skips lines not matching <address>:<hex> — cast-loop example shows the idiom. The stox submit parser will be updated in a follow-up PR to do the same.

hardyjosh · 2026-04-15T23:25:56Z

closing to retrigger CI

hardyjosh · 2026-04-16T00:53:46Z

Superseded by #2552 (GitHub stopped firing pull_request events on this branch after excessive force-pushes — recreated with identical commits on a fresh branch).

This was referenced Apr 14, 2026

feat: add interactive mode to strategy-builder CLI #2546

Open

feat: add strategy-builder CLI subcommand #2544

Open

Consolidate JS API gui module into common crate and rename GUI to OrderBuilder #2479

Open

hardyjosh changed the base branch from interactive-strategy-builder to graphite-base/2548 April 14, 2026 16:53

hardyjosh force-pushed the describe-registry branch from dc1130d to 0e03e5d Compare April 14, 2026 16:53

hardyjosh changed the base branch from graphite-base/2548 to list-tokens April 14, 2026 16:53

hardyjosh mentioned this pull request Apr 14, 2026

feat: add --tokens flag to list deployment-specific tokens #2549

Open

4 tasks

hardyjosh changed the base branch from list-tokens to graphite-base/2548 April 15, 2026 12:37

hardyjosh force-pushed the describe-registry branch from 0e03e5d to d4ce402 Compare April 15, 2026 12:37

hardyjosh changed the base branch from graphite-base/2548 to template-fallback April 15, 2026 12:38

This was referenced Apr 15, 2026

feat: template fallback operator ${expr || 'default'} #2551

Open

feat: skip # comment lines in cli submit input ST0x-Technology/st0x.liquidity#578

Open

hardyjosh marked this pull request as ready for review April 15, 2026 12:48

hardyjosh force-pushed the template-fallback branch from 042f0ae to c36d2a8 Compare April 15, 2026 13:04

hardyjosh force-pushed the describe-registry branch from d4ce402 to 9b601f8 Compare April 15, 2026 13:04

hardyjosh changed the base branch from template-fallback to graphite-base/2548 April 15, 2026 15:42

hardyjosh force-pushed the describe-registry branch from 9b601f8 to a5aa217 Compare April 15, 2026 15:43

feat: reject empty KEY in KEY=VALUE parsing

875877e

hardyjosh force-pushed the describe-registry branch from a5aa217 to d7e2d0f Compare April 15, 2026 15:48

Josh Hardy and others added 7 commits April 15, 2026 20:49

chore: sort registry keys in error message for deterministic output

72e5a29

fix: cap list height to prevent terminal scroll wipe

7009015

Add max_length(10) to all Select/FuzzySelect prompts so they scroll within a fixed window instead of reprinting the full list on every keystroke. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Josh Hardy added 8 commits April 15, 2026 22:06

feat: address CodeRabbit review on interactive wizard

3188bcf

- RAII TerminalGuard restores raw mode/alt screen/cursor on panic - Explicit 0 => arm + unreachable! for output_choice match - saturating_sub for cursor position u16 cast to avoid underflow

fmt: wrap long assert in context.rs tests

988ae03

hardyjosh force-pushed the describe-registry branch from 20e9783 to b525203 Compare April 15, 2026 22:06

hardyjosh closed this Apr 15, 2026

hardyjosh reopened this Apr 15, 2026

chore: retrigger CI

992edb4

hardyjosh closed this Apr 16, 2026

hardyjosh reopened this Apr 16, 2026

chore: touch describe.rs to force CI

7b5564d

hardyjosh changed the base branch from graphite-base/2548 to main April 16, 2026 00:20

chore: retrigger CI after base change

163c989

hardyjosh changed the base branch from main to graphite-base/2548 April 16, 2026 00:21

hardyjosh closed this Apr 16, 2026

hardyjosh deleted the describe-registry branch April 16, 2026 00:52

hardyjosh restored the describe-registry branch April 16, 2026 00:52

hardyjosh reopened this Apr 16, 2026

hardyjosh changed the title ~~feat: add --describe flag to strategy-builder~~ feat: add --describe flag to strategy-builder CLI Apr 16, 2026

trigger

3f8a26e

hardyjosh closed this Apr 16, 2026

hardyjosh deleted the describe-registry branch April 16, 2026 00:53

hardyjosh mentioned this pull request Apr 16, 2026

feat: add --describe flag to strategy-builder CLI #2552

Open

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add --describe flag to strategy-builder CLI#2548

feat: add --describe flag to strategy-builder CLI#2548
hardyjosh wants to merge 32 commits intographite-base/2548from
describe-registry

hardyjosh commented Apr 14, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Apr 14, 2026 •

edited

Loading

Review skipped

Uh oh!

hardyjosh commented Apr 14, 2026 •

edited

Loading

Uh oh!

hardyjosh commented Apr 15, 2026

Uh oh!

coderabbitai bot commented Apr 15, 2026

Uh oh!

coderabbitai bot commented Apr 15, 2026

Uh oh!

hardyjosh commented Apr 15, 2026

Uh oh!

hardyjosh commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

hardyjosh commented Apr 14, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Solution

Checks

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related issues

Poem

Uh oh!

hardyjosh commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hardyjosh commented Apr 15, 2026

Uh oh!

coderabbitai bot commented Apr 15, 2026

Uh oh!

coderabbitai bot commented Apr 15, 2026

Uh oh!

hardyjosh commented Apr 15, 2026

Uh oh!

hardyjosh commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

hardyjosh commented Apr 14, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Apr 14, 2026 •

edited

Loading

hardyjosh commented Apr 14, 2026 •

edited

Loading