rullama-framework: Instructions file for Codex

AGENTS.md

This file gives coding agents project-specific context. Keep it short and update it when workflows change.

Project Overview

• Primary app or package: the rullama Rust workspace (crates/) and its Deno/TypeScript port under deno/ — 27 JSR packages published as @rullama/* (deno/packages/*).
• Main entry points: each deno/packages/<name>/mod.ts (plus the subpath exports in that package's deno.json); Rust crates under crates/<name>/src/lib.rs.
• Important directories: deno/packages (the published packages), deno/tests (cross-package integration tests), deno/examples (deno run samples), deno/docs, deno/fixtures (Rust↔Deno wire goldens), crates/ (Rust).

Architecture Notes

• Module boundaries: @rullama/core is the zero-dependency type layer; every other package depends on it and never on a sibling except as declared in deno/README.md's dependency diagram. Sibling imports use the bare @rullama/<name> specifier and resolve to the local workspace member.
• Generated or vendored code: none in deno/; deno/fixtures/*.json are goldens read as text.
• Sensitive areas: deno/packages/tool-builtins (bash/file/git/web execution), deno/packages/permission (policy enforcement), deno/packages/provider (API keys, request signing), deno/packages/mcp-server and a2a (inbound protocol handling).

Commands (Deno, run from deno/)

• Install: nothing to install — deno resolves the import map; fallow must be on PATH (npm i -g fallow or cargo install fallow-cli).
• Build: no build step (JSR publishes TypeScript sources).
• Test: deno task test (packages/ + tests/); one package: deno test -A packages/<name>/.
• Typecheck or lint: deno task check = fmt --check + lint + type-check (packages, tests, examples) + deno task doc-lint (JSDoc on every export of the 74 published entrypoints)
  • tests — what CI runs; deno task check:fix auto-fixes formatting and fixable lint.
• Publishing (like denext, one package per tag): bump the changed package's deno.json version, commit, then cd deno && deno task publish:changes --push — it finds the packages whose version is not on JSR, tags them <package>-v<version> in dependency order and waits for each publish-deno.yml run (OIDC provenance). Without --push it only reports; --bump patch bumps packages that changed without a bump. deno/scripts/publish.sh [--package <name>] is the manual fallback. deno task jsr:scores refreshes deno/docs/jsr-scores.md.
• Coverage for fallow's CRAP score: deno task coverage:fallow (writes deno/coverage/coverage-final.json, which the pre-commit hook passes to fallow audit).