Merge pull request #294 from bearsunday/cli

Add CLI documentation for BEAR.Sunday

manuals/1.0/en/325.cli.md

@@ -0,0 +1,337 @@
+---
+layout: docs-en
+title: Command Line Interface (CLI)
+category: Manual
+permalink: /manuals/1.0/en/cli.html
+---
+# Command Line Interface (CLI)
+
+BEAR.Sunday's Resource-Oriented Architecture (ROA) represents every functionality of the application as a URI-addressable resource. This approach allows access to resources in various ways, not limited to the web.
+
+```bash
+$ php page.php '/greeting?name=World&lang=ja'
+{
+    "greeting": "こんにちは, World",
+    "lang": "ja"
+}
+```
+
+BEAR.Cli is a tool that converts such resources into native CLI commands, making them distributable via Homebrew:
+
+```bash
+$ greet -n "World" -l ja
+Hello, World
+```
+
+Without writing additional code, you can reuse existing application resources as standard CLI tools. Distribution through Homebrew allows users to use them just like any general command-line tool, without knowing that they are running on PHP or BEAR.Sunday. 
+
+## Installation
+
+Install via Composer.
+
+```bash
+composer require bear/cli
+```
+
+## Basic Usage
+
+### Adding CLI Attributes to Resources
+
+Add CLI attributes to the resource class to define the command-line interface.
+
+```php
+use BEAR\Cli\Attribute\Cli;
+use BEAR\Cli\Attribute\Option;
+
+class Greeting extends ResourceObject
+{
+    #[Cli(
+        name: 'greet',
+        description: 'Say hello in multiple languages',
+        output: 'greeting'
+    )]
+    public function onGet(
+        #[Option(shortName: 'n', description: 'Name to greet')]
+        string $name,
+        #[Option(shortName: 'l', description: 'Language (en, ja, fr, es)')]
+        string $lang = 'en'
+    ): static {
+        $greeting = match ($lang) {
+            'ja' => 'こんにちは',
+            'fr' => 'Bonjour',
+            'es' => '¡Hola',
+            default => 'Hello',
+        };
+        $this->body = [
+            'greeting' => "{$greeting}, {$name}",
+            'lang' => $lang
+        ];
+
+        return $this;
+    }
+}
+```
+
+### Generating CLI Commands and Formula
+
+```bash
+$ vendor/bin/bear-cli-gen MyVendor.MyProject
+# Generated files:
+#   bin/cli/greet         # CLI command
+#   var/homebrew/greet.rb # Homebrew formula
+```
+
+## Using the Command
+
+The generated command provides standard CLI features as follows:
+
+### Displaying Help
+
+```bash
+$ greet --help
+Say hello in multiple languages
+
+Usage: greet [options]
+
+Options:
+  --name, -n     Name to greet (required)
+  --lang, -l     Language (en, ja, fr, es) (default: en)
+  --help, -h     Show this help message
+  --version, -v  Show version information
+  --format       Output format (text|json) (default: text)
+```
+
+### Displaying Version Information
+
+```bash
+$ greet --version
+greet version 0.1.0
+```
+
+### Basic Usage Examples
+
+```bash
+# Basic greeting
+$ greet -n "World"
+Hello, World
+
+# Specify language
+$ greet -n "World" -l ja
+こんにちは, World
+
+# Short options
+$ greet -n "World" -l fr
+Bonjour, World
+
+# Long options
+$ greet --name "World" --lang es
+¡Hola, World
+```
+
+### JSON Output
+
+```bash
+$ greet -n "World" -l ja --format json
+{
+    "greeting": "こんにちは, World",
+    "lang": "ja"
+}
+```
+
+### Output Behavior
+
+The CLI command output follows these specifications:
+
+- **Default Output**: Displays only the specified field's value
+- **`--format=json` option**: Shows the full JSON response like the API endpoint
+- **Error Messages**: Displayed in standard error (stderr)
+- **HTTP Status Code Mapping**: Maps to exit codes (0: success, 1: client error, 2: server error)
+
+## Distribution Methods
+
+Commands created with BEAR.Cli can be distributed via Homebrew in the following two ways:
+
+### 1. Distribution via Local Formula
+
+When testing a development version:
+
+```bash
+$ brew install --formula ./var/homebrew/greet.rb
+```
+
+This method is suitable in the following cases:
+- Private projects
+- Testing during development
+- Distribution of internal tools
+
+### 2. Distribution via Homebrew Tap
+
+A method to widely distribute using a public repository:
+
+```bash
+$ brew tap your-vendor/greet
+$ brew install your-vendor/greet
+```
+
+This method is suitable in the following cases:
+- Open-source projects
+- Distribution of public tools
+- Providing continuous updates
+
+#### Testing Development Version
+
+```bash
+$ brew install --HEAD ./var/homebrew/greet.rb
+```
+
+#### Stable Release
+
+1. Create a tag:
+
+```bash
+$ git tag -a v0.1.0 -m "Initial stable release"
+$ git push origin v0.1.0
+```
+
+2. Update the formula:
+
+```diff
+ class Greet < Formula
++  desc "Your CLI tool description"
++  homepage "https://github.com/your-vendor/your-project"
++  url "https://github.com/your-vendor/your-project/archive/refs/tags/v0.1.0.tar.gz"
++  sha256 "..." # Write the hash value obtained from the command below
++  version "0.1.0"
+-  head "https://github.com/your-vendor/your-project.git", branch: "main"
+
+   depends_on "[email protected]"
+   depends_on "composer"
+ end
+```
+
+You can add dependencies like databases to the formula as needed. However, it's recommended to handle environment setup like database initialization with a `bin/setup` script.
+
+3. Obtain SHA256 hash:
+
+```bash
+# Download tarball from GitHub and compute hash
+$ curl -sL https://github.com/your-vendor/your-project/archive/refs/tags/v0.1.0.tar.gz | shasum -a 256
+```
+
+4. Create a Homebrew Tap:
+
+Setup for GitHub CLI is required:
+- [Install GitHub CLI](https://docs.github.com/en/github-cli/github-cli/about-github-cli)
+- [Authenticate GitHub CLI](https://cli.github.com/manual/gh_auth_login)
+
+```bash
+# Authenticate with GitHub CLI
+$ gh auth login
+
+# The public repository name must start with homebrew-
+$ gh repo create your-vendor/homebrew-greet --public --clone
+$ cd homebrew-greet
+```
+
+5. Place and Publish the Formula:
+
+```bash
+$ cp /path/to/project/var/homebrew/greet.rb .
+$ git add greet.rb
+$ git commit -m "Add formula for greet command"
+$ git push
+```
+
+6. Installation and Distribution:
+
+End users can start using the tool with just the following commands. Since PHP environments and dependency packages are installed automatically, users don't need to worry about environment setup:
+
+```bash
+$ brew tap your-vendor/greet    # The homebrew- prefix is omitted
+$ brew install your-vendor/greet
+
+# Ready to use immediately
+$ greet --version
+greet version 0.1.0
+```
+
+## Customizing the Formula
+
+If necessary, you can edit the formula using the `brew edit` command:
+
+```bash
+$ brew edit your-vendor/greet
+```
+
+```ruby
+class Greet < Formula
+  desc "Your CLI tool description"
+  homepage "https://github.com/your-vendor/your-project"
+  url "https://github.com/your-vendor/your-project/archive/refs/tags/v0.1.0.tar.gz"
+  sha256 "..." # SHA256 of the tgz
+  version "0.1.0"
+
+  depends_on "[email protected]"  # Specify PHP version
+  depends_on "composer"
+
+  # Add if your application requires
+  # depends_on "mysql"
+  # depends_on "redis"
+end
+```
+
+## Version Management
+
+To pin to a specific version:
+
+```bash
+# Pin version
+$ brew pin your-vendor/greet
+
+# Unpin
+$ brew unpin your-vendor/greet
+```
+
+## Deployment
+
+For continuous deployment, the following steps are recommended:
+
+1. Verification in Development Environment
+
+```bash
+$ brew install --HEAD ./var/homebrew/greet.rb
+$ greet --version  # Check version
+$ greet --help     # Check help
+```
+
+2. Release and Deployment
+
+```bash
+# Create version tag
+$ git tag -a v0.1.0 -m "Initial stable release"
+$ git push origin v0.1.0
+
+# Update Homebrew tap
+$ cp var/homebrew/greet.rb /path/to/homebrew-tap/Formula/
+$ cd /path/to/homebrew-tap
+$ git add Formula/greet.rb
+$ git commit -m "Release greet v0.1.0"
+$ git push origin main
+```
+
+3. Verify Installation
+
+```bash
+$ brew update
+$ brew install your-vendor/greet
+$ greet --version  # Confirm the new version
+```
+
+## Clean Architecture
+
+BEAR.Cli demonstrates the strengths of Resource-Oriented Architecture (ROA) and Clean Architecture. In line with the Clean Architecture principle that "UI is a detail," you can add a new adapter, CLI, to the same resource in addition to the web interface.
+
+Furthermore, BEAR.Cli not only supports the creation of commands but also supports distribution and updates via Homebrew. This allows end-users to start using the tool with just one command, utilizing it like a native UNIX command without being aware of the existence of PHP or BEAR.Sunday.
+
+Also, the CLI tool can be version-managed and updated independently from the application repository. This enables you to maintain stability and continuous updates as a command-line tool without being affected by the evolution of the API. This is a new form of API provision realized through the combination of Resource-Oriented Architecture and Clean Architecture.
+