Skip to main content

Development and testing

Clone, run, test — and read the guidelines before changing code.

Read GUIDELINES.md before changing code. It defines module boundaries, security requirements, naming, and project-specific constraints.

🧰 Setup​

git clone https://github.com/NeoLabs-Systems/NeoAgent.git
cd NeoAgent
npm ci
npm run dev:backend

Use a separate NEOAGENT_HOME when development data must not share the normal installation.

Run the backend and Flutter web development client with:

npm run dev:stack
Do not build the web client in development

Do not run a Flutter web release build during normal development. The release pipeline and maintainer own that artifact.

📐 Server conventions​

  • Keep Express routes limited to request parsing and response handling.
  • Put business logic in domain services.
  • Use CommonJS and start new server files with 'use strict';.
  • Route all database access through the shared database module.
  • Route all model calls through the AI engine and provider layer.
  • Use runtime path helpers and the shared logger.
  • Validate external and user-supplied data at system boundaries.

🧪 Tests​

Run the smallest relevant suite while working:

npm run test:unit
npm run test:integration
npm run test:security
npm run test:contract
npm run test:e2e
npm run test:ws

Run the complete backend suite before submitting:

npm run test:backend

Flutter changes use:

cd flutter_app
flutter analyze --no-pub
cd ..
npm run flutter:test

Documentation changes use:

npm run docs:build
npm run docs:dev

The Docusaurus build treats broken routes as errors. Check both desktop and narrow layouts after changing navigation, tables, or images.

🤝 Contributions​

Contributor pull requests target beta. Keep changes focused, include tests for behavior changes, document new commands and settings, and never commit runtime data or credentials. See CONTRIBUTING.md.