jinexus-framework-skeleton: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents (and humans) working in the jinexus-framework/jinexus-framework-skeleton package. Read this before making changes.

What this package is

The official skeleton application for the JiNexus Framework. It provides a ready-to-go project structure for building MVC applications using the JiNexus Framework components (mvc, http, route, config, module-manager).

The skeleton wires up a single Application module that registers routes, controllers, view templates, and error pages. It includes a PHP built-in server script for development, a preconfigured PHPUnit test suite, and the full directory layout (config/, module/, public/, data/, test/) expected by a JiNexus application.

Build & test commands

Run everything from the package root (the directory containing composer.json).

# Install dependencies
composer install

# Regenerate autoloader after adding/moving/renaming classes or namespaces
composer dump-autoload

# Run the full test suite (auto-discovers phpunit.dist.xml)
./vendor/bin/phpunit

# Equivalent via Composer scripts
composer test
composer test:coverage        # sets XDEBUG_MODE=coverage and prints a text report

# Silence the local Xdebug "could not connect" notice
XDEBUG_MODE=off ./vendor/bin/phpunit

# Readable, per-test output
XDEBUG_MODE=off ./vendor/bin/phpunit --testdox

# Run a single file
XDEBUG_MODE=off ./vendor/bin/phpunit test/Application/ModuleTest.php

# Run a single test by name (regex against method names)
XDEBUG_MODE=off ./vendor/bin/phpunit --filter index_action_returns_a_view_model_with_hello_world

# Start the development server via Composer
composer run --timeout=0 serve

# Start the development server directly
php -S localhost:8000 -t public

There is no build step — this is a project skeleton consumed via composer create-project.

Project architecture

config/
  application.config.php          Module list for the application
  modules.config.php              Enabled module namespaces (e.g. 'Application')
module/
  Application/
    config/
      module.config.php           Route table + view-manager settings
    src/
      Module.php                  Application\Module — extends AbstractModule, returns config
      Controller/
        IndexController.php       Application\Controller\IndexController — indexAction()
    view/
      application/
        index/
          index.phtml             Default index view template
      error/
        404.phtml                 404 error page
      layout/
        layout.phtml              Master layout template
public/
  index.php                       Front controller (entry point)
  .htaccess                       Apache rewrite rules
  asset/                          Static assets (CSS, JS, images)
test/
  Application/
    ModuleTest.php                Covers Module::VERSION and getConfig()
    Controller/
      IndexControllerTest.php     Covers IndexController::indexAction()
    Fixture/
      ApplicationDouble.php       Test double for ApplicationInterface
data/
  cache/                          Cache directory (writable at runtime)