gorig-cli 1.0.24 → 1.0.26

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 jom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,58 +1,134 @@
-# Gorig CLI
+# Gorig CLI: Project Generator and AI Skill Installer
 
-Gorig CLI is a scaffolding tool based on Node.js, used for quickly creating the project structure and modules based on the Gorig framework for Go.
+`gorig-cli` is the command-line entry point for Gorig backend development. It creates runnable Gorig projects, generates feature modules, builds persistence-backed CRUD services, produces API documentation, and installs the `gorig-backend` skill for Codex and Claude.
+
+Use it when you want generated code to follow the same Gorig structure and framework conventions instead of starting from ad hoc scaffolding.
+
+Main Gorig framework repository: [https://github.com/jom-io/gorig](https://github.com/jom-io/gorig)
+
+## What It Does
+
+| Capability | Description |
+|---|---|
+| Project bootstrap | Create a locally runnable Gorig service with `_cmd`, environment configs, domain registration, example routes, and tests. |
+| Module generation | Add flat feature modules under `domain/<module>/` using Router -> Controller -> Service -> Model boundaries. |
+| Persistent CRUD | Generate MySQL or MongoDB CRUD modules backed by Gorig `domainx/dx`, with tests, docs, and non-secret config skeletons. |
+| API documentation | Generate OpenAPI/Redoc documentation for generated HTTP modules. |
+| AI skill installation | Install the bundled `gorig-backend` skill so Codex or Claude can work with Gorig projects using framework-aware rules. |
+| Framework development | Generate projects against a local Gorig checkout with `--gorig-replace` when developing the framework itself. |
 
 ## Installation
 
-Install globally using npm:
+Run without installing globally:
+
+```sh
+npx gorig-cli@latest <command>
+```
+
+Or install globally:
 
 ```sh
 npm install -g gorig-cli
+gorig-cli <command>
 ```
 
-Or run directly using npx:
+## Create a New Backend
 
 ```sh
-npx gorig-cli@latest <command>
+npx gorig-cli@latest init my-new-project --no-start
 ```
 
-## Quick Start
+Or with a global install:
 
-### Initialize a New Project
+```sh
+gorig-cli init my-new-project --no-start
+```
 
-Use the `init` command to create a new project:
+The generated project includes:
+
+- one `_cmd` entry point
+- `local`, `dev`, and `prod` configuration
+- `domain/init.go` registration
+- an example `domain/hello` module
+- tests under `test/`
+- no required MySQL, MongoDB, or Redis dependency in the basic profile
+
+Useful automation options:
 
 ```sh
-gorig-cli init my-new-project
+gorig-cli init my-new-project \
+  --module example.com/my-new-project \
+  --gorig-version latest \
+  --port 9527 \
+  --no-start
 ```
 
-Or use npx:
+For framework development against a local checkout:
 
 ```sh
-npx gorig-cli@latest init my-new-project
+gorig-cli init my-new-project \
+  --gorig-replace ../gorig \
+  --no-start \
+  --no-git
 ```
 
-This will create a new project in the current directory, including basic files and directories like `_cmd/main.go`, `domain/init.go`, `cron/cron.go`, etc.
+Use `--force` only when an existing non-empty destination may be replaced. Use `--start` to start immediately; otherwise initialization is non-interactive and does not start the service.
 
-### Create a New Module
+## Add a Module
 
-Use the `create` command in the project root directory to create a new module:
+Run from the generated project root:
+
+```sh
+npx gorig-cli@latest create user
+```
+
+Or with a global install:
 
 ```sh
 gorig-cli create user
 ```
 
-Or use npx:
+This creates:
+
+```text
+domain/user/
+├── router.go
+├── controller.go
+├── service.go
+├── dto.go
+└── model/
+    └── user.go
+```
+
+The generated basic routes are `GET /user/info` and `POST /user/echo`.
+
+## Generate Persistent CRUD
+
+Choose the storage backend explicitly:
 
 ```sh
-npx gorig-cli@latest create user
+# MySQL CRUD module, with HTTP routes enabled by default
+gorig-cli create order --crud --db mysql --db-name Main
+
+# MongoDB CRUD module
+gorig-cli create order --crud --db mongo --db-name main
+
+# Service/model CRUD only, without router/controller/doc HTTP adapter
+gorig-cli create order --crud --db mysql --no-http
 ```
 
-This will create a module named `user` in the project, including folders like `api/`, `internal/`, `model/`, and necessary code.
+Persistent CRUD generation currently supports MySQL and MongoDB. The generated code compiles without a live database, but effect-level create/list/page/update/delete verification requires a matching development database configuration.
 
-### Generate API Documentation
+The CRUD generator preserves existing named connections and adds non-secret configuration skeletons to `_bin/local.yaml`, `_bin/dev.yaml`, `_bin/prod.yaml`, and `test/_bin/local.yaml`.
 
-Use the `doc` command to generate OpenAPI documentation:
+After filling local values or exporting the documented `GORIG_...` variables, run:
+
+```sh
+go test -tags=integration,mysql ./test/... -v
+go test -tags=integration,mongo ./test/... -v
+```
+
+## Generate API Documentation
 
 ```sh
 # Generate documentation for all modules
@@ -69,47 +145,60 @@ npx gorig-cli@latest doc
 npx gorig-cli@latest doc user
 ```
 
-After generating the documentation, you can access it through:
+After generating documentation, access it through:
+
+```text
 http://127.0.0.1:8080/redoc.html
+```
 
-### Install Gorig Skill
+## Install Gorig Backend Skill
 
-Use the `skill` command to install the bundled `gorig-backend` skill for Codex or Claude:
+The CLI bundles the `gorig-backend` skill for Codex and Claude. Install it when you want AI agents to implement, review, test, or troubleshoot Gorig projects with framework-aware rules.
 
 ```sh
-# Install both Codex and Claude user-level skills
-gorig-cli skill install all
-
-# Install only the Codex skill
+# Codex global skill
 gorig-cli skill install codex
 
-# Install Claude user-level skill
-gorig-cli skill install claude user
+# Codex and Claude global skills
+gorig-cli skill install all
 
-# Install Claude project-level skill into the current repository
-gorig-cli skill install claude project
+# Codex skill stored in the current repository
+gorig-cli skill install codex project
 ```
 
-Or use npx:
+The install scope defaults to `user`. Use `project` only when the skill should be stored in the current repository.
 
-```sh
-npx gorig-cli@latest skill install all
-npx gorig-cli@latest skill install codex
-npx gorig-cli@latest skill install claude user
-npx gorig-cli@latest skill install claude project
+Example prompts:
+
+```text
+Use the gorig-backend skill to add a MySQL order CRUD module with tests and API docs.
 ```
 
-### Run the Project
+```text
+Use the gorig-backend skill to review startup, routing, config, and middleware usage.
+```
+
+```text
+Use the gorig-backend skill to add login, protected routes, logout, and security tests.
+```
 
-After entering the project directory, you can run the project using the following commands:
+## Run the Project
 
 ```sh
 cd my-new-project
-go run _cmd/main.go
+GORIG_SYS_MODE=local go run ./_cmd
 ```
 
 Or run it after building:
 
 ```sh
-go build -o my-new-project _cmd/main.go && ./my-new-project
+go build -o my-new-project _cmd/main.go
+GORIG_SYS_MODE=local ./my-new-project
 ```
+
+## Verification Notes
+
+- Basic project generation is dependency-light and should build without MySQL, MongoDB, or Redis.
+- Persistent CRUD is generated for MySQL and MongoDB.
+- Database and Redis behavior should be verified against configured development infrastructure.
+- Remote deployment or production mutation should be performed only after explicit authorization.