Roblox pure Luau modules checked outside Studio

# AGENTS.md: Roblox game with pure Luau modules checked outside Studio

Game rules (prices, inventory, damage, cooldown maths, matchmaking) live in **pure modules** in `src/shared/pure/`.
A pure module never touches the DataModel, so the plain `luau` CLI can type-check and test it in seconds, with no
Studio open. Scripts in `src/server/` and `src/client/` are the **edge**: they get services, read and write
Instances, handle remotes, then call the pure modules with plain values.

## Layout (Rojo)
```
src/shared/pure/   → ReplicatedStorage.Shared.pure   pure ModuleScripts, --!strict, no Roblox APIs
src/shared/        → ReplicatedStorage.Shared        other shared modules and Remotes
src/server/        → ServerScriptService.Server      server edge scripts (*.server.luau)
src/client/        → StarterPlayerScripts            client edge scripts (*.client.luau)
tests/             (not synced)                      *.spec.luau and run.luau, for the luau CLI
```

## Rules for pure modules
- First line `--!strict`. Export the types callers need (`export type State = {...}`).
- No `game`, `workspace`, `script`, `Instance`, services, `task.*`, `wait`/`spawn`/`delay`, `tick()`, or Roblox
  datatypes (`Vector3`, `CFrame`, `Color3`, `Enum`, `Random`). Take what you need as parameters.
- Require other pure modules by string: `require("./Money")`. Roblox (require-by-string) and the luau CLI both
  resolve it relative to the file. Never `require(script.Parent.Money)` inside `pure/`.
- No `print`/`warn`, no `math.random` or `os.time` inside rules. Return values and errors, and take an rng or the
  current time as a parameter, so tests are repeatable.
- Validate inputs in the pure function too (whole numbers, ranges, NaN). The edge script checks types from remotes;
  the rules decide what's allowed.

## Rules for edge scripts
- Keep them thin: read Instances and remote arguments, call the pure module, apply the result.
- Use `task.wait` / `task.spawn` / `task.delay`, never the deprecated `wait` / `spawn` / `delay`.
- The server decides: remotes carry intent, and the server runs the pure rules before changing any state.

## Before you say "done"
1. `python3 .agents/skills/luau-pure-tests/scripts/pure_luau_guard.py src/shared/pure` reports `0 error(s)`.
2. `luau-analyze --mode=strict src/shared/pure tests` reports nothing.
3. `luau tests/run.luau` ends with `0 failed`. Add a test for every rule you change.
4. List what the human should play-test in Studio for the edge scripts. If Roblox Studio's built-in MCP server is
   connected, you can run that play-test through it, but the pure tests above still come first.

# CLAUDE.md

@AGENTS.md

## Claude Code notes

- Skills from this loadout live in `.claude/skills/`: `luau-pure-tests`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From SetupBay "Roblox pure Luau modules checked outside Studio" v1.0.0 — https://setupbay.com/loadouts/roblox-luau-pure-modules/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes

- Skills from this loadout live in `.agents/skills/`: `luau-pure-tests`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From SetupBay "Roblox pure Luau modules checked outside Studio" v1.0.0 — https://setupbay.com/loadouts/roblox-luau-pure-modules/ -->

---
description: Pure Luau modules in src/shared/pure must run outside Studio
globs: "src/shared/pure/**/*.luau,tests/**/*.luau"
alwaysApply: false
---

Files in `src/shared/pure/` are pure: the luau CLI must be able to run them with no Roblox engine.

| Never in `pure/` | Instead |
|---|---|
| `game:GetService(...)`, `workspace`, `script.Parent` | pass the values in from the edge script |
| `require(script.Parent.Money)` | `require("./Money")` |
| `Instance.new`, `Vector3`, `CFrame`, `Enum`, `Random` | plain numbers and tables |
| `task.wait`, `wait`, `spawn`, `delay`, `tick()` | return a value; the edge script schedules |
| `math.random()`, `os.time()` | take `rng` / `now` as parameters |
| `print`, `warn` | return `false, "reason"` |

- `--!strict` on the first line, with exported types.
- Every change gets a case in `tests/*.spec.luau`. Then run the `luau-pure-tests` skill's checks.

---
name: luau-pure-tests
description: Keep a Roblox game's rules in pure Luau modules and run their tests outside Studio with the luau CLI, checking purity with a scanner and types with luau-analyze in strict mode. Use when writing or changing game logic (prices, inventory, damage, cooldowns), when asked to add tests to a Roblox project, or when a module can't run in a test because it calls Roblox APIs.
---

# Pure Luau modules, checked outside Studio

Roblox logic is usually tried out by pressing Play. Rules that don't touch the DataModel can be checked by the
standalone Luau tools instead: `luau-analyze` type-checks them, and `luau` runs their tests in milliseconds.
That's something an agent can run after every change.

## Tools
The Luau release (https://github.com/luau-lang/luau/releases) ships `luau` (runs scripts) and
`luau-analyze` (type-checks and lints) for Linux, macOS and Windows. Rokit or Aftman can install them per project;
otherwise download the release zip. Check with `luau-analyze --help`.

## 1. Check purity
```bash
python3 .agents/skills/luau-pure-tests/scripts/pure_luau_guard.py src/shared/pure
```
(Use the path the skill was installed to: `.claude/skills/...` for Claude Code, `.agents/skills/...` for the others.)

Run it on the pure folders only; edge scripts are meant to use Roblox APIs. Each `error` is a Roblox-only call that
stops the module running outside Studio. Move that call into the edge script and pass the value in. `warn` lines
(`math.random`, `os.time`, `print`) make tests unrepeatable; take an rng or the time as a parameter.

## 2. Type-check in strict mode
```bash
luau-analyze --mode=strict src/shared/pure tests
```
It must print nothing. `Unknown global 'game'` or `Unknown require: unsupported path` means a Roblox API or an
Instance-path require got into a pure module.

## 3. Run the tests
Copy `references/run.luau` to `tests/run.luau` once and list each spec file in it. A spec returns a list of cases:
```luau
--!strict
local Inventory = require("../src/shared/pure/Inventory")
return {
	{ name = "Inventory: the stack limit holds", run = function()
		local s = Inventory.new(500)
		assert(Inventory.buy(s, { id = "sword", price = 150, stack = 1 }, 1))
		assert(not Inventory.buy(s, { id = "sword", price = 150, stack = 1 }, 1))
	end },
}
```
```bash
luau tests/run.luau
```
It prints `PASS`/`FAIL` per case and `N passed, M failed`, and exits non-zero on any failure.

## 4. Report
Say which rules changed, which tests you added, and that the scanner, `luau-analyze --mode=strict` and
`luau tests/run.luau` were clean. Then list what still needs a Studio play-test: the edge scripts, remotes and
anything that touches Instances.

#!/usr/bin/env python3
"""Find Roblox-only calls in Luau modules meant to be pure (no DataModel), so they run and test outside Studio. Run it on the pure folders only, such as src/shared.

Usage: python3 pure_luau_guard.py [PATH ...]        (default: the current folder)
       python3 pure_luau_guard.py --list            (print every rule)

A "guard: ok" comment on a line silences its warnings (never its errors).
Prints one line per finding:  path:line: level [rule] what is wrong -> what to use
Exit 0 when nothing at "error" level is found, 1 when something is, 2 on bad usage.
Standard library only. Read-only: it never edits a file and makes no network calls.
"""
import fnmatch
import os
import re
import sys

# (rule id, level, regex, message, file patterns). Patterns run against each line with comments removed.
RULES = [
    ('datamodel', 'error', '\\b(game|plugin)\\b\\s*[:.]|\\bworkspace\\b|\\bscript\\.(Parent|Name)\\b|\\bInstance\\.new\\(',
     "pure modules can't touch the DataModel (game, workspace, script, Instance) -> pass plain values in from the server or client script", []),
    ('instance-require', 'error', '\\brequire\\(\\s*(script|game)\\b',
     'Instance-path require only works in Studio -> require("./Sibling") or require("../Folder/Module"), which Roblox and the luau CLI both resolve', []),
    ('roblox-services', 'error', '\\b(Players|ReplicatedStorage|ServerStorage|RunService|DataStoreService|HttpService|TweenService|UserInputService|MarketplaceService|MemoryStoreService)\\b\\s*[:.]',
     'a Roblox service in a pure module -> keep services in the edge script and pass what you need in', []),
    ('task-library', 'error', '\\btask\\.(wait|spawn|delay|defer|cancel)\\(',
     'the task library is Roblox-only -> keep scheduling in the edge script; pure functions return values', []),
    ('deprecated-scheduler', 'error', '(?<![\\w.:])(wait|spawn|delay)\\(',
     'wait/spawn/delay are deprecated in Roblox and missing in the luau CLI -> task.wait/task.spawn/task.delay in edge scripts only', []),
    ('roblox-types', 'error', '\\b(Vector3|CFrame|Color3|UDim2|BrickColor|TweenInfo|Enum|Random|DateTime)\\b\\s*[.(]',
     'a Roblox datatype in a pure module -> use plain numbers and tables, or pass the value in', []),
    ('tick', 'error', '(?<![\\w.:])tick\\(\\)',
     'tick() is deprecated -> os.clock() for timing, or pass the time in', []),
    ('connect-lowercase', 'error', ':connect\\(',
     ':connect is deprecated -> :Connect, and only in edge scripts', []),
    ('math-random', 'warn', '\\bmath\\.random\\(',
     'random numbers make pure functions hard to test -> take an rng function or a seed as a parameter', []),
    ('os-time', 'warn', '\\bos\\.(time|clock)\\(',
     'reading the clock makes pure functions hard to test -> take the time as a parameter', []),
    ('print-in-module', 'warn', '(?<![\\w.:])(print|warn)\\(',
     'printing from a pure module -> return the value or an error and let the caller log', []),
]
FILES = ['*.luau', '*.lua']
COMMENT = '--'
SKIP_DIRS = {".git", ".venv", "venv", "node_modules", "__pycache__", ".agents", ".claude", ".cursor", "dist", "build", "target", ".godot"}
COMPILED = [(rid, lvl, re.compile(rx), msg, globs) for rid, lvl, rx, msg, globs in RULES]


def strip_comment(line):
    """Drop a trailing comment, leaving string literals alone."""
    q = None
    i = 0
    while i < len(line):
        c = line[i]
        if q:
            if c == "\\":
                i += 2
                continue
            if c == q:
                q = None
        elif c in "\"'`":
            q = c
        elif line.startswith(COMMENT, i):
            return line[:i]
        i += 1
    return line


def wanted(name):
    return any(fnmatch.fnmatch(name, g) for g in FILES)


def walk(paths):
    for p in paths:
        if os.path.isfile(p):
            yield p
            continue
        for root, dirs, files in os.walk(p):
            dirs[:] = sorted(d for d in dirs if d not in SKIP_DIRS)
            for f in sorted(files):
                if wanted(f):
                    yield os.path.join(root, f)


def scan(path):
    out = []
    name = os.path.basename(path)
    try:
        with open(path, encoding="utf-8", errors="replace") as fh:
            lines = fh.read().splitlines()
    except OSError as e:
        return [(path, 0, "error", "unreadable", str(e))]
    for n, raw in enumerate(lines, 1):
        code = strip_comment(raw)
        if not code.strip():
            continue
        accepted = "guard: ok" in raw  # a person accepted the warnings on this line
        for rid, lvl, rx, msg, globs in COMPILED:
            if accepted and lvl == "warn":
                continue
            if globs and not any(fnmatch.fnmatch(name, g) for g in globs):
                continue
            if rx.search(code):
                out.append((path, n, lvl, rid, msg))
    return out


def main(argv):
    if "--list" in argv:
        for rid, lvl, _, msg, globs in RULES:
            print(f"{lvl:5} [{rid}] {msg}" + (f"  (only {', '.join(globs)})" if globs else ""))
        return 0
    if any(a.startswith("-") for a in argv):
        print(__doc__)
        return 2
    paths = argv or ["."]
    for p in paths:
        if not os.path.exists(p):
            print(f"no such path: {p}", file=sys.stderr)
            return 2
    files = list(walk(paths))
    findings = []
    for f in files:
        findings.extend(scan(f))
    for path, n, lvl, rid, msg in findings:
        print(f"{os.path.relpath(path)}:{n}: {lvl} [{rid}] {msg}")
    errors = sum(1 for x in findings if x[2] == "error")
    warns = sum(1 for x in findings if x[2] == "warn")
    print(f"pure_luau_guard: {len(files)} file(s), {errors} error(s), {warns} warning(s)")
    return 1 if errors else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

--!strict
-- Minimal test runner for the luau CLI: luau tests/run.luau
local specs = { require("./Inventory.spec"), require("./Money.spec") }

local passed, failed = 0, 0
for _, spec in specs do
	for _, case in spec do
		local ok, err = pcall(case.run)
		if ok then
			passed += 1
			print(`PASS {case.name}`)
		else
			failed += 1
			print(`FAIL {case.name}: {err}`)
		end
	end
end
print(`{passed} passed, {failed} failed`)
if failed > 0 then
	error(`{failed} test(s) failed`, 0)
end

-- A Studio-coupled inventory module, used to check the guard. It only runs inside Roblox.
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Money = require(script.Parent.Money)
local Config = require(game.ReplicatedStorage.Shared.Config)

local Inventory = {}

function Inventory.buy(player, item, quantity)
	local stats = player:FindFirstChild("leaderstats")
	if stats.Coins.Value < item.price * quantity then
		warn("not enough coins")
		return false
	end
	stats.Coins.Value -= item.price * quantity
	local drop = Instance.new("Part")
	drop.Position = Vector3.new(0, 10, 0)
	drop.Parent = workspace
	if math.random() < Config.bonusChance then
		spawn(function()
			wait(2)
			stats.Coins.Value += 5
		end)
	end
	player:SetAttribute("lastBuy", tick())
	ReplicatedStorage.Remotes.Bought:FireClient(player, item.id)
	return true
end

return Inventory