@xeno-js/cli 0.1.2 → 0.1.4

package/README.md

@@ -1,236 +1,461 @@
-<div align="center">
-  <img src="logo/logo.png" alt="Xeno CLI Logo" width="140" />
-
-  <h1>Xeno CLI</h1>
-
-  <p><em>Enterprise-grade scaffolding and CLI toolkit for Xeno projects</em></p>
-
-  <p>
-    <a href="https://github.com/xeno-js/xeno-js">
-      <img src="https://img.shields.io/badge/Powered%20by-Xeno-blueviolet?style=flat-square" alt="Powered by Xeno" />
-    </a>
-    <a href="https://github.com/xeno-js/xeno-cli/blob/main/LICENSE">
-      <img src="https://img.shields.io/npm/l/@xeno-js/cli?style=flat-square" alt="License: ISC" />
-    </a>
-    <a href="https://www.npmjs.com/package/@xeno-js/cli">
-      <img src="https://img.shields.io/npm/v/@xeno-js/cli?style=flat-square" alt="NPM Version" />
-    </a>
-    <a href="https://buymeacoffee.com/xenojs">
-      <img src="https://img.shields.io/badge/Buy%20Me%20A%20Coffee-Support-FFdd00?style=flat-square&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me A Coffee" />
-    </a>
-  </p>
-</div>
-
----
-
-## What is Xeno CLI?
-
-**Xeno CLI** (`@xeno-js/cli`) is the official command-line interface designed to
-initialize, configure, and manage projects based on the Xeno framework. It
-automates infrastructural scaffolding to enforce **Domain-Driven Design (DDD)**
-and **Command Query Responsibility Segregation (CQRS)** patterns seamlessly,
-eliminating boilerplate for both Node.js backend environments (`@xeno-js/core`)
-and frontend applications (`@xeno-js/vue`).
-
----
-
-## 💡 Why Choose Xeno CLI?
-
-- **Interactive Configuration**: Launch your project creation through guided
-  prompts that automatically install essential dependencies tailored to your
-  choices (e.g., Zod, Supabase, Drizzle ORM, Pino, Sentry, Pinia, and Tailwind
-  CSS).
-- **CQRS Architectural Scaffolding**: With a single command, dynamically
-  generate Controllers, Handlers, Commands/Queries, dedicated modules, Vue
-  composables, and interconnected Zod or DB schemas.
-- **Target Agnosticism**: Natively handles project structures for both Backend
-  (pure TypeScript) and Frontend (Vue.js), autonomously setting up key files
-  like `tsconfig.json`, `vite.config.ts`, `.env`, and infrastructure
-  bootstrappers.
-- **CI/CD & Git Ready**: Instantly initializes Git repositories and triggers NPM
-  installations, providing a "ready-to-code" ecosystem from the very first
-  second.
-
----
-
-## 📖 Documentation & Getting Started
-
-The CLI interacts directly with Xeno's explicit Inversion of Control (IoC)
-container. To explore the architecture and programmatic configurations, read the
-full technical manuals:
-
-- **[Framework Documentation Repository](https://www.xeno-js.it/cli/overview)**
-
----
-
-## 📦 Installation
-
-Install the CLI globally via npm or run it on-demand using `npx`:
-
-```bash
-# Global installation
-npm install -g @xeno-js/cli
-
-# On-demand execution
-npx xeno-js new my-xeno-app
-
-```
-
----
-
-## 🚀 Usage Guide & Commands
-
-### 1. Create a New Project
-
-Bootstrap the complete architecture:
-
-```bash
-xeno-js new <name> [--vue | --core]
-
-```
-
-- `<name>`: The name of your target project directory.
-
-- `[--vue | --core]`: Select the target environment. If omitted, it defaults to
-  `--core`.
-
-- `--core`: Initializes a Backend project (Node.js/TS).
-
-- `--vue`: Initializes a Frontend project (Vue.js).
-
-### 2. Generate CQRS Components
-
-Dynamically generate folders and infrastructural files for read or write
-operations:
-
-```bash
-xeno-js generate <type> <Name> [--vue | --core] [--output <path>]
-
-# Recommended alias:
-xeno-js g <type> <Name> [-o <path>]
-
-```
-
-- `<type>`: Component type to generate (`command` or `query`).
-
-- `<Name>`: The name of the domain or entity in PascalCase or camelCase (e.g.,
-  `UserCreate`).
-
-- `[--vue | --core]`: Target context. Defaults to `--core`.
-
-- `--core`: Generates Controller, Handler, Command/Query, Module, Zod schemas,
-  and DB schema.
-
-- `--vue`: Generates frontend-specific files like abstract Commands/Queries,
-  Models, and Presentation Composables.
-
-- `[--output | -o | --o]`: Custom destination path inside the `src/` directory.
-  Defaults to `src/<name-in-lowercase>`.
-
-### 3. Help & Guide
-
-Display the quick command guide and supported aliases directly in your terminal:
-
-```bash
-xeno-js --help
-
-# Alias:
-xeno-js -h
-xeno-js --h
-```
-
----
-
-## 🤝 For Contributors
-
-We welcome contributions to Xeno CLI! To maintain the highest code quality and
-stability for the generated scaffolding, **direct pushes to the `main` and
-`develop` branches are strictly prohibited**. Please follow the same Git Flow as
-the core framework:
-
-1. **Branch off from `develop**`:
-
-```bash
-git checkout develop
-git pull origin develop
-git checkout -b feat/add-new-generator
-
-```
-
-2. **Local Development**: Ensure your scaffolding changes do not break tests or
-   builds:
-
-```bash
-npm run check
-
-```
-
-3. **Commit Standards**: We enforce
-   [Conventional Commits](https://www.conventionalcommits.org/?utm_source=gemini).
-   Husky will automatically verify your commit message format:
-
-```bash
-feat(cli): add interactive prompt for Drizzle setup
-fix(generator): resolve output path bug in Vue scaffold
-
-```
-
-4. **Submit a Pull Request (PR)**: Push your branch to GitHub and open a Pull
-   Request targeting the **`develop`** branch.
-
-### Maintenance Scripts
-
-| Command                       | Description                                                         |
-| ----------------------------- | ------------------------------------------------------------------- |
-| `npm run build`               | Compiles the TypeScript CLI source code into the `dist/` directory. |
-| `npm run dev`                 | Runs the CLI in development mode using `tsx`.                       |
-| `npm run typecheck`           | Checks types without emitting files (`tsc`).                        |
-| `npm run lint`                | Runs ESLint to ensure no blocking formatting defects exist.         |
-| `npm run format`              | Automatically formats codebase files using Prettier.                |
-| `npm run test`                | Executes the Vitest test suite.                                     |
-| `npm run test:coverage`       | Runs tests and generates a detailed coverage                        |
-| report using the v8 provider. |
-
----
-
-## 🌱 Support & Appreciation
-
-Designing, integrating, and maintaining a CLI toolkit like Xeno requires massive
-engineering effort. If the decoupled patterns generated by this CLI save you
-countless hours of initial setup, please consider supporting its open-source
-development.
-
-**[Read our support guidelines and find out how to help](https://www.xeno-js.it/support-us)**
-
-Thank you for being part of this decoupled open-source journey!
-
-<amp-bounce>
-</amp-bounce>
-<a href="https://www.buymeacoffee.com/xenojs" target="_blank">
-<img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="42" style="height: 42px !important;" />
-</a>
-
----
-
-## 🛡️ Powered by Xeno
-
-If you scaffolded your architecture using this CLI, let the world know by adding
-our badge to your repository:
-
-```html
-<a
-  href="[https://github.com/xeno-js/xeno-js](https://github.com/xeno-js/xeno-js)"
-  target="_blank"
->
-  <img
-    src="[https://img.shields.io/badge/Powered%20by-Xeno-black?style=flat-square](https://img.shields.io/badge/Powered%20by-Xeno-black?style=flat-square)"
-    alt="Powered by Xeno"
-    height="20"
-  />
-</a>
-```
-
-## 📄 License
-
-Copyright (c) 2026 Xeno. Licensed under the
-[ISC License](https://www.google.com/search?q=LICENSE&utm_source=gemini).
+<div align="center">
+  <img src="logo/logo.png" alt="Xeno CLI Logo" width="140" />
+
+  <h1>Xeno CLI</h1>
+
+  <p><strong>Start with the architecture. Not the scaffolding.</strong></p>
+
+  <p>
+    Scaffold and generate TypeScript applications around explicit
+    application boundaries, CQRS, dependency injection, and Xeno's
+    application architecture.
+  </p>
+
+  <p>
+    <a href="https://www.npmjs.com/package/@xeno-js/cli">
+      <img src="https://img.shields.io/npm/v/@xeno-js/cli?style=flat-square" alt="npm version" />
+    </a>
+    <a href="https://github.com/xeno-js/xeno-cli">
+      <img src="https://img.shields.io/github/stars/xeno-js/xeno-cli?style=flat-square" alt="GitHub stars" />
+    </a>
+    <a href="https://github.com/xeno-js/xeno-cli/blob/develop/LICENSE">
+      <img src="https://img.shields.io/npm/l/@xeno-js/cli?style=flat-square" alt="License: MIT" />
+    </a>
+    <a href="https://buymeacoffee.com/xenojs">
+      <img src="https://img.shields.io/badge/Buy%20Me%20A%20Coffee-Support-FFdd00?style=flat-square&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me A Coffee" />
+    </a>    
+  </p>
+</div>
+
+---
+
+## What is Xeno CLI?
+
+**Xeno CLI** (`@xeno-js/cli`) is the command-line entry point for creating and
+generating Xeno projects.
+
+It helps you start with an explicit application structure instead of rebuilding
+the same architecture by hand.
+
+Use it to:
+
+- create a new Xeno backend project;
+- create a Xeno Vue project;
+- generate commands and queries;
+- choose the infrastructure modules your project needs;
+- generate the initial configuration and composition files.
+
+The goal is simple:
+
+> **Start coding the application, not the scaffolding.**
+
+---
+
+# Start in seconds
+
+Create a Xeno backend project:
+
+```bash
+npx @xeno-js/cli new my-app --core
+```
+
+Create a Vue project:
+
+```bash
+npx @xeno-js/cli new my-app --vue
+```
+
+The CLI guides you through the project options and generates the initial
+structure for you.
+
+---
+
+# Generate a use case
+
+Once your project exists, generate application components without manually
+rebuilding the same structure.
+
+```bash
+npx @xeno-js/cli g command CreateUser --core
+```
+
+or:
+
+```bash
+npx @xeno-js/cli g query FindUser --core
+```
+
+For Vue:
+
+```bash
+npx @xeno-js/cli g command CreateUser --vue
+```
+
+The `g` alias is available for faster iteration:
+
+```bash
+xeno-js g command CreateUser --core
+```
+
+---
+
+# What the CLI creates
+
+Xeno CLI is built around the architecture used by the Xeno ecosystem.
+
+A new project starts from explicit building blocks such as:
+
+```text
+Application
+├── composition root
+├── configuration
+├── registry
+├── CQRS
+├── domain contracts
+└── infrastructure boundaries
+```
+
+The exact generated files depend on the project type and the modules you select.
+
+The important part is the boundary:
+
+```text
+Transport
+    ↓
+Application
+    ↓
+Domain
+    ↓
+Infrastructure
+```
+
+The CLI gives you the starting structure.
+
+Your application defines the business behavior.
+
+---
+
+# Backend projects
+
+The Core scaffold can configure modules for areas such as:
+
+- database access;
+- Redis;
+- authentication;
+- HTTP clients;
+- resilience;
+- logging;
+- validation;
+- application pipelines.
+
+The generated project uses `@xeno-js/core` as its application runtime.
+
+Example:
+
+```text
+my-app/
+├── src/
+│   ├── bootstrap.ts
+│   ├── main.ts
+│   └── registry.ts
+├── package.json
+├── tsconfig.json
+└── .env
+```
+
+The purpose is not to hide the architecture.
+
+The purpose is to give you a clear place to continue building it.
+
+---
+
+# Vue projects
+
+Xeno CLI can also scaffold Vue applications around `@xeno-js/vue`.
+
+```bash
+npx @xeno-js/cli new my-app --vue
+```
+
+The generated project can include the pieces you choose for your application,
+such as:
+
+- Xeno frontend bootstrap;
+- Vue configuration;
+- application registry;
+- routing;
+- Pinia;
+- authentication;
+- HTTP data sources;
+- validation;
+- logging;
+- styling.
+
+The UI remains the presentation layer.
+
+Application behavior remains outside the component whenever the architecture
+requires it.
+
+---
+
+# Why use the CLI?
+
+Starting an application usually creates the same decisions again:
+
+Where should the application bootstrap live?
+
+Where should dependencies be registered?
+
+Where do commands and queries belong?
+
+How should infrastructure connect to the application?
+
+How should the project evolve without putting everything into controllers,
+routes, or components?
+
+Xeno CLI turns those decisions into a repeatable starting structure.
+
+> **You still design the application. You do not have to rebuild its
+> foundation** **every time.**
+
+---
+
+# CLI and Xeno
+
+The CLI is one part of the Xeno ecosystem.
+
+```text
+@xeno-js/shared
+    defines domain primitives
+    and application contracts
+
+          ↓
+
+@xeno-js/core
+    executes the application architecture
+
+          ↓
+
+@xeno-js/vue
+    brings the model to the browser
+
+          ↓
+
+@xeno-js/cli
+    creates the starting structure
+```
+
+A useful mental model is:
+
+> **Shared defines the language.** **Core executes the architecture.** **Vue
+> hosts the architecture in the browser.** **CLI gets you started.**
+
+---
+
+# Use it on new projects
+
+The CLI is designed to make the first project setup explicit and repeatable.
+
+```bash
+npx @xeno-js/cli new my-app --core
+```
+
+Then:
+
+```bash
+cd my-app
+npm install
+```
+
+The generated application can then be extended with the components and
+infrastructure your project actually needs.
+
+---
+
+# Generate inside an existing project
+
+The generator can also be used after the project already exists.
+
+For example:
+
+```bash
+npx @xeno-js/cli g command CreateOrder --core
+```
+
+This is useful when a project already has its application structure and you want
+to add another command or query without rebuilding the surrounding files
+manually.
+
+---
+
+# Commands
+
+## Create a project
+
+```bash
+xeno-js new <name> [--core | --vue]
+```
+
+### Options
+
+- `--core` — create a backend project using `@xeno-js/core`
+- `--vue` — create a frontend project using `@xeno-js/vue`
+
+---
+
+## Generate a command or query
+
+```bash
+xeno-js generate <command | query> <Name> [--core | --vue]
+```
+
+Alias:
+
+```bash
+xeno-js g <command | query> <Name> [--core | --vue]
+```
+
+Optional output path:
+
+```bash
+xeno-js g command CreateUser --core --output src/features/users
+```
+
+---
+
+## Help
+
+```bash
+xeno-js --help
+```
+
+Aliases:
+
+```bash
+xeno-js -h
+xeno-js --h
+```
+
+---
+
+# Installation
+
+You can run the CLI on demand:
+
+```bash
+npx @xeno-js/cli --help
+```
+
+Or install it globally:
+
+```bash
+npm install -g @xeno-js/cli
+```
+
+Then:
+
+```bash
+xeno-js --help
+```
+
+---
+
+# Node.js
+
+Xeno CLI currently targets:
+
+```text
+Node.js 20+
+```
+
+---
+
+# Relationship with the Xeno architecture
+
+Xeno CLI does not replace your transport framework.
+
+It does not try to own HTTP routing.
+
+It does not define your business rules.
+
+It gives you a consistent starting point for the application layer that sits
+between transport and infrastructure.
+
+```text
+HTTP / CLI / Worker
+        ↓
+   Application
+        ↓
+      Domain
+        ↓
+  Infrastructure
+```
+
+That boundary is what the rest of Xeno is designed to execute.
+
+---
+
+# Read the architecture
+
+The CLI is easier to understand when you see the architecture it generates.
+
+Start with:
+
+- Xeno Core
+- Xeno Shared
+- Xeno Vue
+- Xeno architecture documentation
+
+Documentation:
+
+https://www.xeno-js.it/docs/introduction
+
+Core:
+
+https://github.com/xeno-js/xeno-js
+
+Shared:
+
+https://github.com/xeno-js/xeno-shared
+
+Vue:
+
+https://github.com/xeno-js/xeno-fe
+
+---
+
+# Contributing
+
+Contributions are welcome.
+
+Development happens from feature branches targeting `develop`.
+
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b feat/your-feature
+
+npm install
+npm run check
+```
+
+Before opening a pull request:
+
+```bash
+npm run check
+```
+
+We use Conventional Commits:
+
+```text
+feat(cli): add generator
+fix(generator): correct scaffold output
+refactor(dispatcher): simplify command dispatch
+docs(readme): improve getting started
+```
+
+---
+
+# License
+
+MIT License. See `LICENSE`.