expressive-mvc: Instructions file for Codex

AGENTS.md

Contributor guide for AI agents working in this repository.

Overview

Expressive MVC - class-based reactive state management library. Use skills/SKILL.md and linked references to establish the intended public contract and conventions. When working on the library itself, inspect the relevant source and tests before designing or implementing changes; use the skill docs as orientation rather than as a substitute for implementation evidence.

Monorepo: bun workspaces + changesets. Install, scripts, and builds run under bun (bun install, bun run build); tests run on vitest, which executes on node (bun run test invokes it - you never call node directly). Node otherwise appears only in release.yml, where changeset publish shells to npm for the OIDC-authenticated publish.

Structure

packages/mvc    - Core primitives (@expressive/mvc)
packages/react  - React adapter (@expressive/react)
packages/preact - Preact adapter (@expressive/preact)
packages/router - Router built on Component (@expressive/router)
packages/inspect - In-page inspector for agents and devtools (@expressive/inspect)
skills/         - API reference docs (also published as skills.sh skill)
examples/       - Playground of crawlable example pages (see examples/AGENTS.md)
website/        - Docs site

Commands

bun install              # Install deps
bun run test             # Run package test scripts (typecheck + coverage)
bun run typecheck        # tsc --noEmit --incremental in every package
bun run coverage         # vitest with coverage gates in every package
bun run build            # Build all packages in workspace dependency order

Per-package: test runs typecheck (tsc --noEmit --incremental) then coverage (vitest run --coverage). A root vitest run covers every package's suite at once (workspace projects).

Testing

Runner: vitest with istanbul coverage. Test config is centralized in root vitest.config.ts, which defines the workspace projects and exports suite() - per-package vitest.config.ts files are two-liners calling suite() (or suite(true) for DOM packages, which run in vitest's happy-dom environment). Coverage: every package gates statements, branches, functions, and lines at 100% via the shared coverage.thresholds - a conditional arm is either exercised by a test or deleted as dead code. The PR workflow blocks merges on these thresholds; the README badge is generated by .github/workflows/coverage.yml from measured lcov on pushes to main.