Hexagonizer

CLI tool for scaffolding Node.js projects with a clean hexagonal architecture — domain, application, infrastructure, HTTP interfaces, and automated tests.

Designed for both humans (interactive menu) and AI agents (headless CLI commands) to rapidly bootstrap production-ready projects with DDD principles.

Installation

npm install -g hexagonizer

Usage — Human mode

Run without arguments for an interactive menu:

hexagonizer

Select options with arrow keys: Init project, Generate entity, Server commands, Stats.

Usage — AI / Headless mode

All commands work non-interactively with flags. Perfect for AI agents (opencode, claudecode) and automation.

Initialize a project

hexagonizer init <name> [--middlewares] [--docker]

Creates a directory with the project inside.

| Flag | Description | |------|-------------| | --middlewares | Include auth, roles, error handler | | --docker | Add Dockerfile + docker-compose | | -y, --yes | Auto-confirm all |

Example:

hexagonizer init my-api --middlewares --docker

Generate an entity

Run inside the generated project directory.

hexagonizer entity <name> [-y] [--json [path]]

Creates: Domain class, Factory, Validation, Repository, Use cases (CRUD), Controller, Routes, Tests.

| Flag | Description | |------|-------------| | -y, --yes | Quick mode (auto-approve default fields) | | --json [path] | Define fields from a JSON schema file |

Examples:

cd my-api
hexagonizer entity user -y
hexagonizer entity product --json ./product-schema.json

Help

hexagonizer --help

Typical AI workflow

# 1. Install
npm install -g hexagonizer

# 2. Scaffold project with middlewares and docker
hexagonizer init my-store-api --middlewares --docker

# 3. Generate entities
cd my-store-api
hexagonizer entity user -y
hexagonizer entity product -y
hexagonizer entity order -y

# 4. Start developing
npm run dev

The generated project comes with Express preconfigured, routes wired, tests ready, and everything connected.

Generated project structure

my-project/
├── src/
│   ├── domain/
│   │   └── <entity>/
│   │       ├── <Entity>.js
│   │       ├── <entity>-factory.js
│   │       ├── <entity>-validation.js
│   │       └── <entity>-constants.js
│   ├── application/
│   │   └── <entity>/
│   │       └── use-cases/
│   │           ├── create-<entity>.js
│   │           ├── get-<entity>.js
│   │           ├── update-<entity>.js
│   │           ├── delete-<entity>.js
│   │           └── list-<entity>.js
│   ├── infrastructure/
│   │   └── <entity>/
│   │       ├── in-memory-<entity>-repository.js
│   │       └── database-<entity>-repository.js
│   ├── interfaces/http/
│   │   ├── <entity>/
│   │   │   ├── <entity>.controller.js
│   │   │   └── <entity>.routes.js
│   │   └── middlewares/
│   │       ├── auth.js
│   │       ├── error-handler.js
│   │       └── role.js
│   ├── config/
│   └── index.js
├── tests/
│   └── application/<entity>/
└── package.json

AI integration

Hexagonizer ships with an opencode skill that teaches AI agents how to use it. When working with opencode inside a project, the AI can load the skill:

skill({ name: "hexagonizer" })

This gives the AI full context on commands, flags, and the generated project structure. The skill is auto-detected when opencode scans .opencode/skills/.

Built with

| Dependency | Purpose | |---|---| | Inquirer | Interactive CLI prompts and menus | | Chalk | Terminal text styling and colors | | Express | HTTP server (generated projects) |

Feature status

| Feature | Status | |---|---| | Interactive CLI (human mode) | Complete | | Headless CLI (AI / automation mode) | Complete | | Base project initialization | Complete | | Generic entity generation | Complete | | Dynamic validations | Complete | | Query middlewares (q, etc.) | Complete | | Automated tests per entity | Complete | | JSON schema entity generation | Partial | | AI skill for opencode | Complete | | Global npm installation | Complete |

Requirements

• bash (Linux, macOS, WSL on Windows, or Git Bash)
• Node.js 18+ (for generated projects)
• npm (for dependency installation)

Contributing

Contributions, ideas, and bug reports are welcome. Open an issue or submit a pull request.

License

MIT — 2025 Franco Toledo