ginxsom/.roo/rules-code/AGENTS.md

AGENTS.md

This file provides guidance to agents when working with code in this repository.

Critical Coding Rules (Non-Obvious Only)

• nostr_core_lib Integration: Must use nostr_sha256() and nostr_bytes_to_hex() from nostr_core, NOT standard crypto libs
• Database Connection Pattern: Always use sqlite3_open_v2() with SQLITE_OPEN_READONLY or SQLITE_OPEN_READWRITE flags
• Memory Management: File data buffers must be freed after use - common pattern is malloc() for upload data, free() on all paths
• Error Handling: FastCGI responses must use printf("Status: XXX\r\n") format, NOT standard HTTP response format
• String Safety: Always null-terminate strings from SQLite results - use strncpy() with size-1 and explicit null termination
• Hash Validation: SHA-256 hashes must be exactly 64 hex chars - validate with custom validate_sha256_format() function
• MIME Type Mapping: Use centralized mime_to_extension() function - never hardcode file extensions
• Authentication: Nostr event parsing uses cJSON - always call cJSON_Delete() after use to prevent memory leaks
• Configuration Loading: File config takes priority over database - check XDG paths first, fallback to database
• Blob Metadata: Database is single source of truth - use get_blob_metadata(), not filesystem checks
• nostr_core_lib Build: Uses build.sh script, NOT make - run ./build.sh to compile the library
• Server Testing: Use ./restart-all.sh to properly restart and test ginxsom server, NOT direct binary execution
• spawn-fcgi Parameters: Must use -M 666 -u "$USER" -g "$USER" for socket permissions and ownership
• Admin Event Structure: Admin auth uses kind 24242 with "t" tag containing HTTP method, expiration typically 1 hour
• Key File Permissions: .admin_keys file must be chmod 600 or auth tests will fail
• Development Environment: Set GINX_DEBUG=1 for pubkey extraction diagnostics during development