Skip to content

AGENTS.md

Latest commit

 

History

History
109 lines (77 loc) · 4.1 KB

AGENTS.md

File metadata and controls

109 lines (77 loc) · 4.1 KB

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.3 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)

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