Ruvyxa AGENTS.md

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, test:parity, and plugin create. 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 — and the TypeScript plugin 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.
• 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/plugins/ is the first-party plugin API behind the plugins.ts barrel; 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 five scaffolds — minimal, blog, crud, api, plugin. 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.