cell/AGENTS.md

Agent Development Guide

Build Commands

• Debug build: make debug or meson setup build_dbg -Dbuildtype=debugoptimized && meson compile -C build_dbg
• Release build: make release or meson setup -Dbuildtype=release -Db_lto=true build_release && meson compile -C build_release
• Fast build: make fast or meson setup build_fast && meson compile -C build_fast
• Web build: make web or meson setup -Deditor=false -Dbuildtype=minsize build_web && meson compile -C build_web
• Cross-platform: make crosswin (Windows), make dockerlinux (Linux), make dockeremc (Emscripten)

Test Commands

• Run all tests: meson test -C build_dbg
• Run single test: ./cell tests/<test_name> (e.g., ./cell tests/send, ./cell tests/empty)
• Available tests: spawn_actor, empty, nota, wota, portalspawner, overling, send, delay
• Test examples: ./cell examples/nat, ./cell examples/http_download_actor

Code Style Guidelines

C Code Style (K&R)

• Indentation: 4 spaces, no tabs
• Naming: snake_case for identifiers
• Files: Small, focused C files with header guards required
• Formatting: Use .clang-format (GNU style, 2-space continuation, attach braces)
• Comments: Focus on "why", keep lines to ~100 columns

Cell Language Style (JavaScript-like)

• Language: Cell resembles JavaScript but has key differences - equality operators (==, !=) perform strict comparisons (equivalent to ===, !== in JavaScript, no type coercion)
• Indentation: 2 spaces
• Declarations: def for constants, var for block-scoped variables (like let)
• Equality: Use == only (strict equality, no coercion)
• Null checks: Use == null (no undefined in Cell)
• Imports: Use use('path') for modules (not ES6 import/export)
• Modules: *.cm files must return values, *.ce files are programs (don't return)
• Patterns: Prefer objects, prototypes, closures over classes
• Formatting: Use .prettierrc (semicolons, double quotes, trailing commas, 1000 char width)

File Organization

• Modules: *.cm (return objects, get frozen with stone())
• Programs: *.ce (execute top-to-bottom, register handlers)
• Naming: Lowercase paths with / separators
• Resolution: Engine appends .cm/.ce automatically when probing

Error Handling

• Use log.console() and log.error() for logging
• Actor system handles message timeouts automatically
• Check for circular imports (detected and reported)
• Validate module returns before freezing

Best Practices

• Keep modules small and composable
• Use actor messaging for communication (no shared objects)
• Follow hierarchical actor system (overlings/underlings)
• Prefer functional programming patterns
• Document with cell.DOC system