create-next-pro-cli 0.1.26 → 0.1.28

package/README.md

@@ -1,373 +1,363 @@
-<img src="./public/cnp-banner.svg" alt="create-next-pro logo" style="width:100%;" />
-
-## Runtime Support
-
-[![Bun](https://img.shields.io/badge/Bun-%23000000?logo=bun&logoColor=white&style=for-the-badge)](https://bun.sh)
-[![Node.js](https://img.shields.io/badge/Node.js-%23339933?logo=node.js&logoColor=white&style=for-the-badge)](https://nodejs.org)
-
-<!-- [![Deno](https://img.shields.io/badge/Deno-%23000000?logo=deno&logoColor=white&style=for-the-badge)](https://deno.land) -->
-
-![npm](https://img.shields.io/npm/v/create-next-pro-cli?logo=npm&color=orange)
-![npm dependencies](https://img.shields.io/librariesio/release/npm/create-next-pro-cli?logo=npm)
-![npm downloads](https://img.shields.io/npm/dw/create-next-pro-cli?logo=npm)
-
-![GitHub](https://img.shields.io/github/stars/Rising-Corporation/create-next-pro-cli?style=social&logo=github)
-![GitHub forks](https://img.shields.io/github/forks/Rising-Corporation/create-next-pro-cli?style=social&logo=github)
-![GitHub issues](https://img.shields.io/github/issues/Rising-Corporation/create-next-pro-cli?logo=github)
-![CI](https://github.com/Rising-Corporation/typed-sse/actions/workflows/ci.yml/badge.svg)
-
-![status](https://img.shields.io/badge/status-beta-orange)
-![license](https://img.shields.io/github/license/Rising-Corporation/create-next-pro-cli?logo=open-source-initiative&logoColor=white)
-[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-blue.svg?logo=conventionalcommits)](https://www.conventionalcommits.org/en/v1.0.0/)
-
-> ⚠️ This project is under active development and currently in beta testing. You may encounter bugs or crashes until the first release. Not all features are implemented yet, and contributions are welcome!
-
-Initially, changes will be accepted or rejected by the creator, but in a few weeks, contributions will be submitted to a community vote.
+<img src="./public/cnp-banner.svg" alt="create-next-pro" width="100%" />
 
 # create-next-pro-cli
 
-> 🚀 An advanced CLI scaffolder to create professional Next.js projects instantly.
+[![Bun](https://img.shields.io/badge/Bun-1.3%2B-000000?logo=bun&logoColor=white)](https://bun.sh)
+[![Node.js](https://img.shields.io/badge/Node.js-24%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org)
+[![npm](https://img.shields.io/npm/v/create-next-pro-cli?logo=npm&color=CB3837)](https://www.npmjs.com/package/create-next-pro-cli)
+[![npm downloads](https://img.shields.io/npm/dw/create-next-pro-cli?logo=npm)](https://www.npmjs.com/package/create-next-pro-cli)
+[![CI](https://github.com/Rising-Corporation/create-next-pro-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Rising-Corporation/create-next-pro-cli/actions/workflows/ci.yml)
+[![GitHub stars](https://img.shields.io/github/stars/Rising-Corporation/create-next-pro-cli?style=social)](https://github.com/Rising-Corporation/create-next-pro-cli)
+[![GitHub issues](https://img.shields.io/github/issues/Rising-Corporation/create-next-pro-cli?logo=github)](https://github.com/Rising-Corporation/create-next-pro-cli/issues)
+[![License](https://img.shields.io/github/license/Rising-Corporation/create-next-pro-cli?logo=open-source-initiative&logoColor=white)](./LICENSE)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-FE5196?logo=conventionalcommits&logoColor=white)](https://www.conventionalcommits.org/en/v1.0.0/)
 
----
+`create-next-pro` generates and evolves Next.js 16 projects with TypeScript, App Router, React 19, Tailwind CSS 4, `next-intl`, and Auth.js.
 
-> 🤩 Can't wait and too excited to read more? Just want to try it now?
->
-> ℹ️ To enable autocompletion automatically, add the `--trust` option when installing globally with Bun:
->
-> ```bash
-> bun install -g create-next-pro-cli --trust
-> ```
+The launcher uses Bun when available and automatically falls back to Node.js. No runtime selection is persisted. Generated projects are validated with Bun, npm, and pnpm.
 
----
+## Purpose
 
-## 🎯 Purpose
+`create-next-pro` provides a reproducible, production-oriented Next.js foundation and commands to evolve it without manually relocating files. The scaffolder separates App Router routes, interfaces under `src/ui`, translated messages, and application libraries to keep the structure clear as the application grows.
 
-Create an enhanced alternative to `bun create next-app` with an interactive interface to generate Next.js projects tailored to real-world professional needs.
+The CLI is built around a runtime-independent core, injectable terminal and file-system adapters, and generators confined to the project root. The distributed template includes internationalization, authentication, a CSP policy, environment validation, and automated quality checks.
 
-This open-source, community-driven project aims to gather and share best practices to help standardize Next.js project structures. It includes many other features to facilitate modern development workflows and encourage collaboration.
+## Main features
 
-The CLI also enables you to instantly create pages and components, automatically placing them in the correct location within your project’s architecture for seamless organization and scalability.
+- direct or interactive Next.js 16 project creation;
+- Bun-first CLI execution with an automatic Node.js fallback;
+- generated projects compatible with Bun, npm, and pnpm;
+- generation of pages, components, libraries, and API routes;
+- addition of `next-intl` locales and messages;
+- direct or interactive page removal with a tree-based selector;
+- nested routes and interfaces using `Parent.Child` notation;
+- customizable import aliases such as `@/*` or `@core/*`;
+- dedicated Bash and Zsh completion;
+- confined file operations and allowlist-based template copying;
+- Auth.js, CSP, environment validation, Vitest, and Playwright in the template.
 
-You can also customize the templates used for pages and components to fit your own needs.
+## Requirements
 
----
+- Node.js 24 or later, or Bun 1.3 or later, to run the CLI.
+- Bun 1.3+, the npm version bundled with Node.js 24+, or pnpm 11+ for generated projects.
 
-## 🛠️ Commands & Examples
-
-### Create a new project
+## Installation
 
 ```bash
-create-next-pro MyProjectName
+bun install --global create-next-pro-cli
+# or
+npm install --global create-next-pro-cli
+# or
+pnpm add --global create-next-pro-cli
 ```
 
-> ⚠️ The interactive prompt for features and customization is not yet implemented, but will be available very soon!
-
-### Create a page
+Without a global installation:
 
 ```bash
-create-next-pro addpage MyPage
+bunx create-next-pro-cli my-app
+npx create-next-pro-cli my-app
+pnpm dlx create-next-pro-cli my-app
 ```
 
-### Create a nested page
+On first launch, the onboarding assistant offers to install Bash or Zsh completion. Run `create-next-pro --reconfigure` to start the assistant again without duplicating the shell configuration.
+
+## Create a project
 
 ```bash
-create-next-pro addpage ParentPage.ChildPage
+create-next-pro my-app
+cd my-app
 ```
 
-### Create a component (global)
+Then install dependencies with your preferred package manager:
 
 ```bash
-create-next-pro addcomponent MyComponent
+bun install && bun run dev
+# or
+npm install && npm run dev
+# or
+pnpm install && pnpm run dev
 ```
 
-### Create a component in a page
+An existing destination is rejected by default. `--force` only permits replacement of the requested child destination:
 
 ```bash
-create-next-pro addcomponent MyComponent -P MyPage
+create-next-pro my-app --force
 ```
 
-### Create a component in a nested page
+Without a project name, the CLI opens the interactive assistant. The import alias must follow the `<prefix>/*` form, such as `@/*` or `@core/*`. It is written to `tsconfig.json` and `cnp.config.json`, then reused by the generators.
 
-```bash
-create-next-pro addcomponent MyComponent -P ParentPage.ChildPage
-```
+## Project evolution commands
 
-### Create a library
+Run the following commands from the root of a generated project.
 
 ```bash
-create-next-pro addlib mylib
-```
+# Simple or nested pages
+create-next-pro addpage profile
+create-next-pro addpage account.security
 
-### Add a file to a library
+# Global components or components attached to a page
+create-next-pro addcomponent Alert
+create-next-pro addcomponent PasswordForm --page account.security
 
-```bash
-create-next-pro addlib mylib.foo
-```
+# Libraries and modules
+create-next-pro addlib analytics
+create-next-pro addlib analytics.trackEvent
 
-### Create an API route
+# Routes API
+create-next-pro addapi health
 
-```bash
-create-next-pro addapi hello
-```
+# Locales and translations
+create-next-pro addlanguage de
+create-next-pro addtext dashboard.welcome "Welcome"
 
-### Remove a page
+# Direct removal
+create-next-pro rmpage account.security
 
-```bash
-create-next-pro rmpage MyPage
+# Tree-based autocomplete menu with confirmation
+create-next-pro rmpage
 ```
 
-### Remove a nested page
+`addlanguage` copies every message file from the configured default locale. The command reports each copied path and emits a required `translate` next step: the copied source-language text must be translated before the locale is ready to ship.
 
-```bash
-create-next-pro rmpage ParentPage.ChildPage
-```
+`addpage` creates `layout`, `page`, and `loading` files by default. Available long options are `--layout`, `--page`, `--loading`, `--not-found`, `--error`, `--global-error`, `--route`, `--template`, and `--default`. The historical short forms remain available.
+
+`rmpage` only lists routes that contain an actual `page.tsx`. Next.js route groups and technical directories are hidden. Removal is confined to the project and preserves shared parent directories and unrelated files.
 
----
+## Generated project architecture
 
-## 📁 Expected Structure of a Generated Project
+The Next.js route and its interface are separate: `src/app` owns routing while `src/ui` owns page components. Translations remain organized by locale and domain.
 
-```plaintext
-my-next-app/
-.
-├── eslint.config.mjs
-├── messages
-│   ├── en
-│   │   ├── Dashboard.json
+```text
+my-app/
+├── .env.example
+├── cnp.config.json
+├── messages/
+│   ├── en/
 │   │   ├── _global_ui.json
 │   │   ├── _home.json
-│   │   ├── Login.json
-│   │   ├── Register.json
-│   │   ├── Settings.json
-│   │   └── UserInfo.json
+│   │   ├── dashboard.json
+│   │   ├── login.json
+│   │   ├── register.json
+│   │   ├── settings.json
+│   │   └── userInfo.json
 │   ├── en.ts
-│   ├── fr
-│   │   ├── Dashboard.json
-│   │   ├── _global_ui.json
-│   │   ├── _home.json
-│   │   ├── Login.json
-│   │   ├── Register.json
-│   │   ├── Settings.json
-│   │   └── UserInfo.json
-│   ├── fr.ts
-│   └── getMergedMessages.ts
-├── middleware.ts
-├── next.config.ts
-├── next-env.d.ts
-├── package.json
-├── postcss.config.mjs
-├── public
-│   ├── cnp-logo.png
-│   └── cnp-logo.svg
-├── README.md
-├── src
-│   ├── app
-│   │   ├── api
-│   │   │   └── auth
-│   │   │       ├── [...nextauth]
-│   │   │       │   └── route.ts
-│   │   │       └── post-login
-│   │   │           └── route.ts
-│   │   ├── favicon.ico
-│   │   ├── layout.tsx
-│   │   ├── [locale]
+│   ├── fr/
+│   │   └── ...
+│   └── fr.ts
+├── public/
+│   ├── logo.png
+│   └── logo.svg
+├── src/
+│   ├── app/
+│   │   ├── [locale]/
+│   │   │   ├── (public)/
+│   │   │   │   ├── _home/
+│   │   │   │   ├── login/
+│   │   │   │   └── register/
+│   │   │   ├── (user)/
+│   │   │   │   ├── dashboard/
+│   │   │   │   ├── settings/
+│   │   │   │   └── userInfo/
 │   │   │   ├── layout.tsx
-│   │   │   ├── loading.tsx
-│   │   │   ├── not-found.tsx
-│   │   │   ├── page.tsx
-│   │   │   ├── (public)
-│   │   │   │   ├── _home
-│   │   │   │   │   ├── loading.tsx
-│   │   │   │   │   └── page.tsx
-│   │   │   │   ├── layout.tsx
-│   │   │   │   ├── Login
-│   │   │   │   │   └── page.tsx
-│   │   │   │   └── Register
-│   │   │   │       └── page.tsx
-│   │   │   └── (user)
-│   │   │       ├── Dashboard
-│   │   │       │   ├── error.tsx
-│   │   │       │   ├── loading.tsx
-│   │   │       │   └── page.tsx
-│   │   │       ├── layout.tsx
-│   │   │       ├── Settings
-│   │   │       │   ├── loading.tsx
-│   │   │       │   └── page.tsx
-│   │   │       └── UserInfo
-│   │   │           ├── loading.tsx
-│   │   │           └── page.tsx
-│   │   ├── not-found.tsx
-│   │   ├── page.tsx
-│   │   ├── sitemap.ts
-│   │   └── styles
-│   │       └── globals.css
-│   ├── auth.config.ts
-│   ├── config.ts
-│   ├── lib
-│   │   ├── auth
-│   │   │   ├── disconnect.ts
-│   │   │   └── isConnected.ts
-│   │   ├── i18n
-│   │   │   ├── navigation.ts
-│   │   │   ├── request.ts
-│   │   │   └── routing.ts
+│   │   │   └── page.tsx
+│   │   ├── api/auth/[...nextauth]/route.ts
+│   │   └── styles/globals.css
+│   ├── lib/
+│   │   ├── i18n/
+│   │   ├── security/csp.ts
 │   │   └── utils.ts
-│   └── ui
-│       ├── Dashboard
-│       │   ├── LogoutButton.tsx
-│       │   ├── page-ui.tsx
-│       │   ├── StatsCard.tsx
-│       │   └── WelcomeCard.tsx
-│       ├── _global
-│       │   ├── BackButton.tsx
-│       │   ├── Button.tsx
-│       │   ├── GlobalHeader.tsx
-│       │   ├── GlobalMain.tsx
-│       │   ├── Loading.tsx
-│       │   ├── LocaleSwitcher.tsx
-│       │   ├── PublicNav.tsx
-│       │   ├── ThemeToggle.tsx
-│       │   └── UserNav.tsx
-│       ├── _home
-│       │   └── page-ui.tsx
-│       ├── Login
-│       │   └── page-ui.tsx
-│       ├── Register
-│       │   └── page-ui.tsx
-│       ├── Settings
-│       │   └── page-ui.tsx
-│       └── UserInfo
-│           └── page-ui.tsx
-├── tailwind.config.ts
+│   ├── ui/
+│   │   ├── _global/
+│   │   ├── _home/
+│   │   ├── dashboard/
+│   │   ├── login/
+│   │   ├── register/
+│   │   ├── settings/
+│   │   └── userInfo/
+│   ├── auth.ts
+│   ├── config.ts
+│   ├── env.ts
+│   └── proxy.ts
+├── tests/
+│   ├── consumer/
+│   ├── e2e/
+│   ├── rendering/
+│   └── unit/
+├── next.config.ts
+├── package.json
+├── playwright.config.ts
+├── pnpm-workspace.yaml
 └── tsconfig.json
 ```
 
----
-
-## ✅ Main Features
-
-- Interactive CLI available for Bun, Node.js, or Deno
-- Multi-runtime support: Bun, Node.js, Deno
-- Features:
-  - TypeScript integration
-  - ESLint configuration
-  - Tailwind CSS setup
-  - App Router support (with or without `src/` directory)
-  - Internationalization using `next-intl`
-  - Turbopack or Webpack support
-  - Custom path aliases (e.g., `@/*`, `@core/*`)
-  - Next-auth with custom cookies
-  - Automatic generation of pages and components
-  - Clean i18n structure: `/messages/en/*.json`, `/lib/i18n/`
-  - Add or remove pages and components via CLI
-  - Bash and Zsh autocompletion
-  - Interactive installation and runtime detection
-
----
-
-## 📁 CLI Structure
-
-```plaintext
-create-next-pro/
-.
-├── bin.ts
-├── create-next-pro-completion.sh
-├── install.sh
-├── package.json
-├── public
-│   ├── cnp-banner.svg
-│   └── logo.svg
-├── src
-│   ├── index.ts
-│   ├── lib
+Template working files (`.env`, the nested Git repository, caches, screenshots, and test results) are not copied into generated projects. The CLI creates `cnp.config.json` with the project name and selected alias.
+
+## CLI architecture
+
+```text
+create-next-pro-cli/
+├── bin.bun.ts
+├── bin.node.ts
+├── src/
+│   ├── cli/
+│   │   ├── completion.ts
+│   │   ├── onboarding.ts
+│   │   ├── output.ts
+│   │   └── registry.ts
+│   ├── core/
+│   │   ├── contracts.ts
+│   │   ├── operations.ts
+│   │   ├── page-catalog.ts
+│   │   ├── project-paths.ts
+│   │   └── template-manifest.ts
+│   ├── lib/
+│   │   ├── addApi.ts
 │   │   ├── addComponent.ts
+│   │   ├── addLanguage.ts
+│   │   ├── addLib.ts
 │   │   ├── addPage.ts
+│   │   ├── addText.ts
 │   │   ├── createProject.ts
-│   │   ├── createProjectWithPrompt.ts
-│   │   ├── rmPage.ts
-│   │   ├── utils.test.ts
-│   │   └── utils.ts
-│   ├── scaffold-dev.ts
+│   │   └── rmPage.ts
+│   ├── release/
+│   │   └── model.ts
+│   ├── runtime/
+│   │   └── node-context.ts
+│   ├── index.ts
 │   └── scaffold.ts
-└── tsconfig.json
+├── templates/
+│   ├── Component/
+│   ├── Page/
+│   ├── Projects/default/
+│   ├── Api/
+│   └── Lib/
+├── create-next-pro-completion.sh
+├── create-next-pro-completion.zsh
+├── package.json
+└── tsup.config.ts
+```
+
+The CLI registry resolves commands to a shared asynchronous interface. The core defines contracts, the page catalog, and path boundaries; runtime adapters provide prompts, console access, and file-system operations. Bun and Node.js bundles are built separately and selected by the `dist/create-next-pro` launcher.
+
+## Global options
+
+```text
+--help          Show help
+--version, -v   Show the version
+--json          Emit one deterministic JSON document
+--reconfigure   Run CLI configuration again
+--force         Replace an existing project destination
+```
+
+`--json` can appear before or after a command. It disables prompts, colors, banners, and incidental logs. Standard output contains exactly one JSON document followed by a newline, while standard error remains empty even when the command fails. Internal shell completion continues to use its separate line-based protocol.
 
+## Human and agent output
+
+Human output names every created, copied, updated, deleted, unchanged, or skipped resource with an absolute path. It ends with a summary and only the next steps that are still required. For example, adding a locale clearly reports that its messages were copied from the source locale:
+
+```text
+COPIED translation-messages: /workspace/my-app/messages/de/dashboard.json from /workspace/my-app/messages/en/dashboard.json (locale="de", sourceLocale="en")
+UPDATED messages-registry: /workspace/my-app/src/lib/i18n/messages.ts
+SUCCESS: Added locale "de" by copying 7 files from "en".
+NEXT [translate]: Translate every copied message from en to de; the copied text is not ready for delivery.
+  /workspace/my-app/messages/de/dashboard.json
+```
+
+Agentic usage adds `--json`:
+
+```bash
+create-next-pro addapi health --json
+```
+
+The versioned document has stable status, event, next-step, and error fields:
+
+```json
+{
+  "schemaVersion": 1,
+  "command": "addapi",
+  "status": "success",
+  "exitCode": 0,
+  "summary": "Added API route \"health\".",
+  "projectRoot": "/workspace/my-app",
+  "events": [
+    {
+      "sequence": 1,
+      "action": "created",
+      "resource": "directory",
+      "role": "api-directory",
+      "scope": "project",
+      "path": "src/app/api/health"
+    },
+    {
+      "sequence": 2,
+      "action": "created",
+      "resource": "file",
+      "role": "api-route",
+      "scope": "project",
+      "path": "src/app/api/health/route.ts"
+    }
+  ],
+  "nextSteps": [
+    {
+      "kind": "review",
+      "required": true,
+      "message": "Replace the example response and review validation and authentication.",
+      "paths": [
+        {
+          "scope": "project",
+          "path": "src/app/api/health/route.ts"
+        }
+      ]
+    }
+  ],
+  "error": null
+}
 ```
 
----
+Paths inside events and next steps are relative to their named scope. Applicable absolute roots are exposed as `projectRoot`, `configRoot`, and `homeRoot`. Events never contain file contents, environment values, credentials, or secrets.
 
-## 🚀 Install & Usage
+Command statuses are `success`, `unchanged`, `cancelled`, and `failed`. Successful mutations, idempotent no-op results, and user cancellations exit with code `0`; only `failed` exits with code `1`. Stable error codes include `INVALID_ARGUMENT`, `CONFIG_NOT_FOUND`, `I18N_DISABLED`, `TARGET_EXISTS`, `TARGET_NOT_FOUND`, `TEMPLATE_MISSING`, `UNSAFE_PATH`, `INCONSISTENT_LOCALE`, `FILESYSTEM_ERROR`, `INTERACTIVE_INPUT_REQUIRED`, and `ONBOARDING_REQUIRED`.
 
-### Local from git ( dev & bun only )
+Interactive input is never attempted in JSON mode. Pass every required argument explicitly. On a new machine, run the CLI once without `--json` to complete onboarding; `--reconfigure --json` is intentionally rejected.
+
+## Environment and security
+
+Generated projects contain `.env.example`, never the template's local `.env`. Copy it before configuring Auth.js:
 
 ```bash
-git clone https://github.com/Rising-Corporation/create-next-pro-cli.git
-bun install
-bun dev
+cp .env.example .env.local
 ```
 
-- then Global ( on your machine )
+OAuth credentials, nested Git repositories, caches, installed dependencies, Playwright artifacts, and agent context are excluded from generated projects and the npm package. For deployments without authentication, use `AUTH_DISABLED=true`.
+
+## Quality
+
+In the CLI repository:
 
 ```bash
-bun link create-next-pro-cli
-create-next-pro my-next-project
+bun install --frozen-lockfile
+bun run check
 ```
 
-### From npm (via bunx , npx ... or global install)
+In a generated project, the same scripts work with all three package managers:
 
 ```bash
-bunx create-next-pro-cli # to try without install
+bun run check
+npm run check
+pnpm run check
 ```
 
-- or
+Validation covers formatting, linting, TypeScript, Vitest, the Next.js build, and the rendering contract. Use `npm pack --dry-run --json` to inspect the CLI's distributable contents.
+
+## Development
 
 ```bash
-bun install -g create-next-pro-cli #ℹ️
+git clone https://github.com/Rising-Corporation/create-next-pro-cli.git
+cd create-next-pro-cli
+bun install --frozen-lockfile
+bun run build
+bun link
+create-next-pro --help
 ```
 
-> ℹ️ To enable autocompletion automatically, add the `--trust` option when installing globally with Bun:
->
-> ```bash
-> bun install -g create-next-pro-cli --trust
-> ```
-
-> Otherwise, run the autocompletion install script from binary manually:
->
-> ```bash
-> bash install.sh
-> ```
-
-> Or add the autocompletion line to your `.bashrc`/`.zshrc` :
->
-> ```bash
-> source ~/.bun/install/global/node_modules/create-next-pro-cli/create-next-pro-completion.sh
-> ```
->
-> Then restart your terminal or run
->
-> ```bash
-> source ~/.bashrc
-> ```
->
-> ||
->
-> ```bash
-> source ~/.zshrc
-> ```
-
----
-
-## 🛣️ Roadmap in coming for beta v0.2.0
-
-- [ ] Implementation of interactive prompts
-- [ ] Create library features
-- [ ] Create API features
-- [ ] Generation of `.env.*`
-- [ ] Multi-platform testing (`bunx`, `link`, `npm`, etc.)
-- [ ] Additional Components templates (admin panel, landing page, etc.)
-- [ ] Auto deployment to Vercel
-
----
-
-## 👨‍💻 Author
-
-MrRise@RisingCorporation  
-Made with ❤️ and Bun 🐇
+MIT licensed. Contribution guidelines are available in [CONTRIBUTING.md](./CONTRIBUTING.md).