gdc_cmod/AGENTS.md

AGENTS.md

Guidance for coding agents working in D:\data\www\gdc_cmod.

1) Repository Summary

• Stack: CodeIgniter 4 + PHP 8.1+.
• Package manager: Composer.
• Test framework: PHPUnit 10 (phpunit.xml.dist).
• App domain: laboratory workflow (requests, samples, validation, reporting).
• Auth: session-based, route filters (role, guest).
• Data sources: SQL Server (GDC_CMOD.dbo) + legacy Firebird integration.
• Frontend: PHP views with Tailwind/DaisyUI/Alpine assets from public/.

2) Rule Files Check

• Cursor rules: not found (.cursor/rules/ and .cursorrules absent).
• Copilot rules: not found (.github/copilot-instructions.md absent).
• If these files are later added, treat them as high-priority instructions.

2.1) Codebase-Memory MCP Workflow (Default)

• This repository is indexed in codebase-memory-mcp (session project D-data-www-gdc_cmod).
• Before broad architecture analysis, run:
  • index_status (confirm graph is ready)
  • get_architecture for languages, packages, layers, file_tree
• Prefer search_graph + get_code_snippet + trace_call_path for impact/call-chain questions.
• For change impact before commits, use detect_changes(scope='all'|'branch').
• Important: results can be noisy due to minified vendor assets in public/js/*.min.js.
• When querying routes/hotspots, scope to app PHP files (file_pattern='app/**/*.php') where possible.

3) Core Commands

# install deps
composer install

# run dev server
php spark serve

# list spark commands
php spark

# list routes (preferred)
php spark routes

# alternate command used in this repo
php spark list

4) Test Commands (Use These)

# full suite
composer test

# full suite (direct)
./vendor/bin/phpunit

# windows direct
vendor\bin\phpunit

# single test file
./vendor/bin/phpunit tests/unit/ReportTest.php

# single test class
./vendor/bin/phpunit --filter ReportTest

# single test method
./vendor/bin/phpunit tests/unit/HealthTest.php --filter testIsDefinedAppPath

# single test directory
./vendor/bin/phpunit tests/unit

5) Lint / Static Analysis

• No dedicated linter/formatter configs were found (phpcs, php-cs-fixer, pint).
• No static analysis configs were found (phpstan, psalm).
• Use syntax lint for changed PHP files:

php -l app/Controllers/RequestsController.php
php -l app/Config/Routes.php

• If you add QA tooling, update this file with exact commands.

6) Code Organization

• Controllers: app/Controllers and app/Controllers/Pages.
• Filters: app/Filters, aliases in app/Config/Filters.php.
• Routes: app/Config/Routes.php.
• Views: app/Views/....
• Tests: tests/unit, tests/database, tests/session, tests/_support.
• Most DB access uses raw SQL (\Config\Database::connect()), not CI models.

7) Style Rules (PHP)

Imports and namespaces

• Keep valid namespace per folder.
• Use use imports for frequently referenced classes.
• Remove unused imports.
• Keep one class per file.

Formatting

• Prefer 4 spaces in new/edited code.
• Existing files may contain mixed tabs/spaces; avoid full-file reformat churn.
• Keep methods small; extract helpers for complex branching.
• Keep comments sparse; only explain non-obvious logic.

Types

• Add parameter and return types in new/modified methods when practical.
• Prefer explicit casts for session/DB values used in role or numeric logic.
• Prefer strict comparisons (===, !==) over loose comparisons.

Naming

• Classes: PascalCase.
• Methods/variables: camelCase.
• Constants: UPPER_SNAKE_CASE (ROLE_NAMES).
• SQL identifiers follow existing DB naming (often uppercase).
• Views use existing naming conventions (lowercase/underscores).

8) Imports, Responses, and Controller Patterns

• API endpoints commonly use CodeIgniter\API\ResponseTrait.
• JSON responses: $this->response->setJSON([...]) or $this->respond([...]).
• HTML responses: return view('path/to/view', $data);.
• Inputs: getGet(), getPost(), getJSON(true) based on content type.
• Validate required inputs early and return errors promptly.

9) SQL and Data Safety

• Prefer parameterized queries for all user/session-controlled values.
  • Good: $db->query('... WHERE ACCESSNUMBER = ?', [$accessNumber]);
  • Avoid: SQL string interpolation with raw request/session data.
• Use transactions for multi-step writes that must be atomic.
• Preserve dual-validation behavior (ISVAL1/ISVAL2, two distinct users).
• Keep audit logging writes (AUDIT_EVENTS, AUDIT_REQUESTS) intact when changing flows.

10) Error Handling and Logging

• Return consistent JSON shape for API failures (status, message).
• For external HTTP/cURL calls, check HTTP code and handle failures explicitly.
• Use log_message('error', ...) for operational failures.
• Do not expose secrets, stack traces, or sensitive internals to clients.

11) Security Requirements

• Escape user-facing output in views with esc().
• Enforce auth + role checks through route filters and session state.
• Use password_hash() and password_verify() for credentials.
• Never commit .env or secrets.

12) Role and Routing Conventions

• Role IDs:
  • 0 Superuser
  • 1 Admin
  • 2 Lab
  • 3 Phlebo
  • 4 CS
• Route filter examples:
  • Single role: ['filter' => 'role:1']
  • Multiple roles: ['filter' => 'role:0,1,2']

13) Agent Change Checklist

• Make minimal, targeted changes.
• Do not revert unrelated local modifications.
• Keep backward compatibility for response payloads unless asked otherwise.
• Run at least one relevant test file after code changes.
• If no tests exist for a changed behavior, add focused tests when feasible.
• Update this file when commands/conventions/tooling change.