Ruvyxa: Instructions file for Codex

Ruvyxa Monorepo Agent Guide

You are working in the Ruvyxa framework monorepo. Treat this file as the source of truth for agent work in the repository.

Repository Shape

• crates/ contains the Rust workspace.
• crates/ruvyxa_cli owns the Ruvyxa CLI commands: dev, build, check, start, preview, routes, analyze, adds, doctor, clean, trace, bench, and test:parity. The Command enum in crates/ruvyxa_cli/src/main.rs is the list; nothing else enumerates them.
• crates/ruvyxa_bundler owns TypeScript/JSX compilation, module resolution, linking, minification, source maps, and server/client boundary checks.
• crates/ruvyxa_dev_server owns Axum serving, HMR, render cache, router, worker pool, style collection, and action/API/client endpoints. Its lib.rs is the crate root — configuration, serve, the router table, and the request path for project pages and API routes. Handlers for the reserved /__ruvyxa/* paths live in framework_endpoints.rs, the WebSockets in realtime_endpoints.rs, and the development file watcher in watcher.rs. Add a new framework endpoint to framework_endpoints.rs and its route to the table in lib.rs, not to lib.rs alone; the conformance test there checks the two agree.
• crates/ruvyxa_graph owns file-system route discovery, validation, rendering strategy detection, and route manifests. It depends on ruvyxa_bundler for one reason: route validation reuses the bundler's source scanner rather than running a second text scan that could disagree.
• crates/ruvyxa_middleware owns the Tower layer stack — CORS, rate limiting, request logging, response timing, custom headers, client-IP resolution — the route-rule evaluator behind headers()/redirects()/rewrites()/proxy.matcher, and the project worker host. Its crate docs carry the contract shared by every rate limiter in the workspace; read it before adding a fifth.
• crates/ruvyxa_diagnostics owns error codes, Result, and the path helpers every other crate agrees on (normalized_canonical_path in particular — see the Windows note under Change Guidance). crates/ruvyxa_tui owns terminal layout, spinners, progress, the mascot, the command header and success banner, the colour roles, and the decorative gradients. cargo run -p ruvyxa_tui --example preview draws every one of those surfaces in one screen, which is the only way to see the animated ones without rebuilding an application.
• crates/ruvyxa_axum (ruvyxa-axum on crates.io) serves the static target's publish directory from an axum::Router — _headers, 404.html, the shared content-type table — so a Rust application and its Ruvyxa front end ship as one binary. It is the only published crate and depends on nothing else in crates/; that is a constraint, because a workspace crate pulled in would have to be published with its whole dependency closure. Its example, examples/axum_host.rs, is byte-for-byte the src/main.rs that ruvyxa adds axum writes, so cargo test --workspace compiles the scaffold and the axum lane of scripts/smoke-runtime-adapter.mjs serves a real build through it. The crate does not render: SSR, ISR, PPR, and API routes are refused by the static adapter at build time.
• packages/ contains the npm packages:
  • ruvyxa — the framework package. runtime/*.mjs are the modules the Rust CLI resolves by path and spawns or imports; src/content-engine/ is the content engine behind ruvyxa/content-engine; packages/ruvyxa/scripts/sync-shared-runtime.mjs regenerates the committed copies of shared modules.
  • create-ruvyxa — the scaffolder. Its template/ directory holds a generated copy of every starter, not just minimal.
  • @ruvyxa/core — primitives both the Rust host and a deployed build need: route-match, origin-policy, the standalone server, shared server utilities.
  • @ruvyxa/react — the client router, not-found, and the React-facing surface.
  • @ruvyxa/auth, @ruvyxa/database, @ruvyxa/realtime, @ruvyxa/testing — optional integrations.
  • @ruvyxa/adapter-* — eleven deploy adapters; @ruvyxa/cli-* — five prebuilt CLI binaries.
• examples/demo/ is the broad integration fixture, and it is deployable — RUV2213 is gone, along with the refusal of a dynamic server-components route. A failure there is usually a question about the feature rather than about the emitted server, which is what the smoke fixture is for.
• examples/deploy-smoke/ is the smallest application every self-hosted adapter can deploy, and is what CI builds and then launches on real Node, Bun, and Deno through scripts/smoke-runtime-adapter.mjs. Keep it deployable: a route or feature no adapter supports belongs in the demo instead. /rsc there is a dynamic server-components route on purpose — a pre-rendered one proves nothing about a deployment, because its payload is already in the file the adapter copies and no renderer runs.
• templates/ holds four scaffolds — minimal, blog, crud, api. templates/minimal/ is what create-ruvyxa copies into a new project. packages/create-ruvyxa/template/ is generated, not committed: it is gitignored, and packages/create-ruvyxa/scripts/prepare-template.mjs deletes and rebuilds it from templates/* on prepack, renaming .gitignore to gitignore because npm strips a packaged dotfile. Edit templates/; never that copy, and never add a second mechanism to keep the two in step — this file used to say scripts/check-template-mirrors.mjs did, and it does not. That script holds one genuinely hand-maintained pair: ruvyxa-runner.tsx in the template and in examples/demo, so the fixture exercises what a scaffolded project ships with. pnpm release:validate fails on drift there.