jhumanj§opnform

Imported from gencau/test-practices-agent-configurations (dataset/repos/jhumanj§opnform/AGENTS.md). Install upstream with npx skills add gencau/test-practices-agent-configurations --skill jhumanj§opnform. Copyright stays with the author.

AGENTS.md

Instructions for AI coding agents working in this repository.

Scope

• This file applies to the full repository.
• If a deeper AGENTS.md exists in a subdirectory, follow the deeper file for files in that subtree.

Repository Overview

• Monorepo with:
• api/: Laravel 11+ / PHP 8.2 backend.
• client/: Nuxt 3 / Vue frontend (JavaScript, not TypeScript by default).
• docs/: Mintlify documentation.

Working Style

• Make focused changes that directly solve the request.
• Prefer editing existing patterns over introducing new architecture.
• Keep diffs small and avoid unrelated refactors.
• Preserve existing conventions and file organization.

Setup And Commands

• Frontend (client/):
• Install: npm install
• Dev server: npm run dev
• Lint: npm run lint
• Tests: npm run test
• Backend (api/):
• Install: composer install
• Tests: php artisan test

Validation Before Handoff

• Run targeted checks for changed areas first.
• If frontend code changed, run npm run lint (in client/) and relevant tests.
• If backend code changed, run relevant php artisan test --filter=... and broaden only if needed.
• Report what was run and what could not be run.

Project Conventions

• Frontend:
• Use Nuxt UI v3 + Tailwind patterns already used in the codebase.
• Prefer Composition API and existing composables.
• Use Promise chaining style (.then().catch().finally()) where this project already enforces it.
• Backend:
• Follow Laravel conventions, Form Requests, Eloquent relationships, and Pest tests.
• Keep controllers thin and place business logic in services when appropriate.

Cursor Rules (Source Of Truth)

• For detailed conventions, read and follow:
• .cursor/rules/opnform-overview.mdc
• .cursor/rules/front-end.mdc
• .cursor/rules/api-query.mdc
• .cursor/rules/front-end-testing.mdc
• .cursor/rules/back-end.mdc
• .cursor/rules/back-end-testing.mdc
• .cursor/rules/forms.mdc
• .cursor/rules/formula-engine.mdc
• .cursor/rules/docs.mdc

Documentation Changes

• When behavior, configuration, or workflows change, update docs in README.md, docs/, or both.

Safety

• Do not commit secrets or tokens.
• Do not change licensing files or enterprise-only code boundaries unless explicitly requested.

Cursor Cloud specific instructions

Project overview

OpnForm is a no-code form builder with two main services: a Laravel 11 API (api/) and a Nuxt 3 client (client/). Development uses Docker Compose (docker-compose.dev.yml) which runs PostgreSQL, the API (PHP-FPM), the client (Nuxt dev server), and an Nginx ingress.

Starting the dev environment

# Docker must be running first (see Docker gotcha below)
cd /workspace && docker compose -f docker-compose.dev.yml up -d

Wait ~60s for the client container to finish npm install + Nuxt build on first start. The app is then available at http://localhost:3000 (client) and http://localhost (API via Nginx).

On first run, navigate to http://localhost:3000/setup to create the admin account.

Docker gotcha (nested containers)

This cloud environment runs inside a container, so Docker requires fuse-overlayfs storage driver and iptables-legacy. The daemon config at /etc/docker/daemon.json is already set. To start dockerd:

sudo dockerd &>/tmp/dockerd.log &
sleep 3
sudo chmod 666 /var/run/docker.sock

Stale Docker API image

The published jhumanj/opnform-api:dev image may lag behind the repo's composer.json. If the API container fails with missing class errors (e.g. TwoFactorServiceProvider not found), run:

docker exec opnform-api sh -c "curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer"
docker exec opnform-api composer install --no-interaction --optimize-autoloader
docker restart opnform-api