proscenium: Instructions file for Codex

AGENTS.md

This file provides guidance to coding agents (Claude Code, Codex and others) when working with code in this repository.

Project Overview

Proscenium is a Rails engine that provides real-time frontend asset bundling and minification using esbuild. It processes JavaScript, TypeScript, JSX, TSX, and CSS files on-demand with zero configuration and no build step.

Prerequisites

• Ruby >= 3.4.0 (project uses 3.4.12)
• Go 1.27.3+ (go.mod's go line, which the Rakefile's -go for xgo must match)
• Rails 8.0 to 8.x

Architecture

The project is a hybrid Ruby gem + Go shared library:

• Ruby (lib/proscenium/): Rails integration, middleware, helpers, side-loading logic
• Go (internal/): Core bundling/compilation via esbuild, exposed as a C shared library via FFI

Key Components

• lib/proscenium/builder.rb - FFI interface to Go binary, handles build/resolve/compile operations; the binding itself is builder/request.rb, autoloaded so the library opens on the first call
• lib/proscenium/railtie.rb - Rails engine configuration and middleware setup
• lib/proscenium/middleware.rb - Rack middleware that intercepts asset requests
• lib/proscenium/side_load.rb - Auto-loads JS/CSS alongside views, partials, layouts
• lib/proscenium/importer.rb - Tracks imported assets for inclusion in HTML
• lib/proscenium/monkey.rb - The ActionView hooks side loading runs through, prepended in railtie.rb: Base#_run, TemplateRenderer#render_template, PartialRenderer#render_partial_template and CollectionRenderer#render_collection
• lib/proscenium/helper.rb - View helpers included into ActionView: sideload_assets, include_assets/include_stylesheets/include_javascripts, css_module, and proscenium_render_block_partial, which monkey.rb calls for a partial rendered with a block
• main.go - C-exported functions (build_to_string, resolve, compile, free_cstr, reset_config) called from Ruby
• internal/builder/ - esbuild configuration and build orchestration
• internal/plugin/ - Custom esbuild plugins (CSS modules, SVG, i18n, RJS, etc.)
• exe/proscenium (and exe/psm, an alias that loads it) and lib/proscenium/cli/ - The proscenium CLI for gem dependency contexts (#154): install, install --frozen, inspect (also doctor) and gem check. Every error is a code with its text in contexts/messages.rb and its exit status in cli/error.rb, pinned by a golden in test/cli/golden/ (GOLDEN=update bin/test test/cli/errors_test.rb rewrites them); cli/reporter.rb lays out and colours human output, and --json keeps a stable event shape. The supported pnpm and Bun lines are cli/capabilities.json
• lib/proscenium/contexts/ (Proscenium::Contexts) - The model of #154 the engine and the CLI share, loading nothing of either: which gems map to a committed context under .proscenium/packages/ (Map), the contexts the bundle calls for (Plan), a gem's projection (Projection), the author rules (Rules), the refusal to build while one is stale (Stale), and the development-time check for files that changed (MappingGeneration)
• lib/proscenium/runtime/ - The bun test harness: a rails runner daemon (server.rb) over a Unix socket, plus the Bun plugin (bun.js) and its bootstrap (bootstrap.js)