This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Lapis is a web framework for Lua and MoonScript supporting OpenResty and lua-http servers. It provides a full-featured web application framework with database models, routing, HTML generation, validation, sessions, and more.

• make build - Compiles all MoonScript (.moon) files to Lua (.lua)
• moonc lapis - Compile only the lapis directory
• make local - Build and install locally

• make test - Run all test suites (requires databases)
• busted spec - Run basic Lua tests
• busted spec_postgres - Run PostgreSQL integration tests
• busted spec_mysql - Run MySQL integration tests
• busted spec_openresty - Run OpenResty integration tests
• busted spec_cqueues - Run cqueues/lua-http tests

• make test_db - Create PostgreSQL test database
• make mysql_test_db - Create MySQL test database

• make lint - Run MoonScript linter on all .moon files
• moonc -l <file> - Lint specific MoonScript file

• make clean - Remove all compiled .lua files

Application Layer (lapis/application.moon):

• Main application class and request handling
• Route definition and dispatching
• Before/after filters and middleware
• Action loading and execution

Router (lapis/router.moon):

• URL pattern matching and route compilation
• Parameter extraction from URLs
• Route precedence handling

Database Layer (lapis/db/):

• Database-agnostic model system
• Support for PostgreSQL, MySQL, and SQLite
• Schema management and migrations
• Model relations and preloading

HTML Generation (lapis/html.moon):

• DSL for generating HTML in Lua/MoonScript
• Widget system for reusable components
• HTML escaping and security

Configuration (lapis/config.moon):

• Environment-based configuration
• Database connection settings
• Server and application settings

Validation (lapis/validate.moon):

• Input validation functions
• Form validation patterns
• Type checking and sanitization

Validation Types (lapis/validate/types.moon):

• Extended type system built on tableshape for parameter validation
• Specialized types for web applications (db_id, db_enum, file_upload)
• Text validation with UTF-8 support (cleaned_text, valid_text, trimmed_text)
• Complex parameter validation (params_shape, params_array, params_map)
• Error aggregation and transformation utilities

Session Management (lapis/session.moon):

• Cookie-based session handling
• Session encoding/decoding
• CSRF protection

Flow System (lapis/flow.moon):

• Object wrapper that forwards method calls to wrapped objects
• Encapsulates functionality within Flow class scope
• Provides memoization utilities for caching method results
• Supports extensible flow objects with property assignment control

• lapis/ - Core framework code
• lapis/cmd/ - Command-line tools and templates
• lapis/db/ - Database abstraction and models
• lapis/nginx/ - OpenResty/Nginx integration
• lapis/util/ - Utility functions
• lapis/spec/ - Testing utilities
• spec/ - Test suites
• docs/ - Documentation files

This codebase uses MoonScript (.moon files) as the primary language, which compiles to Lua (.lua files). The compiled Lua code is checked into the repository so that the framework can be installed without requiring a MoonScript compiler. When working with the code:

• Always edit .moon files, not .lua files
• Run make build after editing .moon files to compile MoonScript to Lua
• The .lua files are generated and should not be edited directly
• Both .moon and .lua files are committed to the repository

The framework supports multiple databases through a unified model interface:

• Models automatically detect database type from config
• lapis/db/model.moon acts as a dispatcher to specific database implementations
• Database-specific models in lapis/db/postgres/, lapis/db/mysql/, lapis/db/sqlite/
• Relations system supports belongs_to, has_many, has_one patterns

Lapis supports multiple server backends:

• OpenResty (default) - High performance Nginx + LuaJIT
• lua-http with cqueues - Pure Lua HTTP server
• Configuration determines which backend to use

The project uses LuaRocks for dependency management. Key dependencies include:

• MoonScript (for compilation)
• Busted (for testing)
• lua-cjson (JSON handling)
• pgmoon (PostgreSQL driver)
• Various Lua utilities

The lapis-dev-1.rockspec file defines the LuaRocks package specification for Lapis. This file contains:

• Dependencies: External Lua packages required by Lapis
• Build modules: Complete mapping of all Lua modules in the framework
• Install configuration: Binary files and installation settings

When to update the rockspec:

• Adding new .lua files to the lapis/ directory structure
• Removing existing .lua files from the framework
• Adding new external dependencies to the project
• Changing the binary installation configuration

The build.modules section must be manually maintained to include all .lua files that should be installed with the package. When adding new MoonScript files that compile to Lua, the corresponding .lua file path must be added to this section.

When making changes, ensure all test suites pass before committing.

When adding type annotations to the codebase, follow these conventions consistent with the existing patterns in lapis/util.moon:

Function Annotations:

• Use --- prefix for all annotation lines
• Place annotations directly above the function definition
• Include brief function description on first line
• Use @param for parameters with type and description
• Use @return for return values with type and optional description
• Mark unused return values with @nodiscard if appropriate

---URL decode a string
---@param str string
---@return string
unescape = (str) -> url.unescape str

Parameter Types:

• Use basic Lua types: string, number, boolean, table, function, nil
• Use string|number for union types
• Use string? for optional parameters
• Use table[] for arrays
• Use any for untyped values
• Use userdata for external objects (like date objects)

Table Parameters:

• For complex table parameters, document fields with nested @param entries
• Use descriptive field names in the format @param parts.field type description

---Build a URL from component parts
---@param parts table URL components table
---@param parts.path? string URL path
---@param parts.query? string Query string
---@param parts.fragment? string URL fragment
---@param parts.host? string Host name
---@param parts.port? string|number Port number
---@param parts.scheme? string URL scheme (http, https, etc.)
---@return string
build_url = (parts) ->

Return Values:

• Document all return values, including success/failure booleans
• Use table|nil for functions that may return nil
• For multiple return values, document each on separate @return lines

---Calculate the difference between two dates
---@param later userdata|string Later date object or string
---@param sooner userdata|string Earlier date object or string
---@return table time_diff Time units (years, days, hours, minutes, seconds)
---@return boolean success Always true
date_diff = (later, sooner) ->

Style Guidelines:

• Keep descriptions concise but informative
• Use consistent terminology throughout the codebase
• Include units or formats in descriptions when relevant
• Document default values in parameter descriptions
• Use present tense for function descriptions
• Avoid redundant information in descriptions