diff --git a/manuals/1.0/en/325.cli.md b/manuals/1.0/en/325.cli.md index 1deca72f..4ef9609f 100644 --- a/manuals/1.0/en/325.cli.md +++ b/manuals/1.0/en/325.cli.md @@ -6,28 +6,28 @@ 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. +BEAR.Sunday's Resource Oriented Architecture (ROA) represents all application functionality as URI-addressable resources. This approach allows resources to be accessed through various means, not just through the web. ```bash -$ php page.php '/greeting?name=World&lang=ja' +$ php page.php '/greeting?name=World&lang=fr' { - "greeting": "こんにちは, World", - "lang": "ja" + "greeting": "Bonjour, World", + "lang": "fr" } ``` -BEAR.Cli is a tool that converts such resources into native CLI commands, making them distributable via Homebrew: +BEAR.Cli is a tool that converts these resources into native CLI commands and makes them distributable via Homebrew: ```bash -$ greet -n "World" -l ja -Hello, World +$ greet -n "World" -l fr +Bonjour, 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. +You can reuse existing application resources as standard CLI tools without writing additional code. Through Homebrew distribution, users can utilize these tools like any other command-line tool, without needing to know they're powered by PHP or BEAR.Sunday. ## Installation -Install via Composer. +Install using Composer: ```bash composer require bear/cli @@ -37,7 +37,7 @@ composer require bear/cli ### Adding CLI Attributes to Resources -Add CLI attributes to the resource class to define the command-line interface. +Add CLI attributes to your resource class to define the command-line interface: ```php use BEAR\Cli\Attribute\Cli; @@ -74,16 +74,20 @@ class Greeting extends ResourceObject ### Generating CLI Commands and Formula +To convert a resource into a command, run the following command with your application name (vendor name and project name): + ```bash -$ vendor/bin/bear-cli-gen MyVendor.MyProject +$ vendor/bin/bear-cli-gen 'MyVendor\MyProject' # Generated files: # bin/cli/greet # CLI command # var/homebrew/greet.rb # Homebrew formula ``` -## Using the Command +Note: Homebrew formula is generated only when a GitHub repository is configured. -The generated command provides standard CLI features as follows: +## Command Usage + +The generated command provides standard CLI features such as: ### Displaying Help @@ -101,7 +105,7 @@ Options: --format Output format (text|json) (default: text) ``` -### Displaying Version Information +### Showing Version Information ```bash $ greet --version @@ -140,67 +144,65 @@ $ greet -n "World" -l ja --format json ### Output Behavior -The CLI command output follows these specifications: +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) +- **Default output**: Displays only the specified field value +- **`--format=json` option**: Displays full JSON response similar to API endpoint +- **Error messages**: Output to standard error (stderr) +- **HTTP status code mapping**: Maps to exit codes (0: success, 1: client error, 2: server error) -## Distribution Methods +## Distribution -Commands created with BEAR.Cli can be distributed via Homebrew in the following two ways: +Commands created with BEAR.Cli can be distributed via Homebrew. +Formula generation requires the application to be published on GitHub: -### 1. Distribution via Local Formula +### 1. Local Formula Distribution -When testing a development version: +For testing development versions: ```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 +### 2. Homebrew Tap Distribution -A method to widely distribute using a public repository: +Method for wide distribution 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 +This method is particularly suitable for: + +- Open source projects +- Continuous updates provision #### Testing Development Version ```bash $ brew install --HEAD ./var/homebrew/greet.rb ``` +```bash +$ greet --version +greet version 0.1.0 +``` #### 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: - +2. Update 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 ++ sha256 "..." # Add hash value obtained from the command below + version "0.1.0" - head "https://github.com/your-vendor/your-project.git", branch: "main" @@ -209,32 +211,24 @@ $ git push origin v0.1.0 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: +You can add dependencies like databases to the formula as needed. However, it's recommended to handle database setup and other environment configuration in the `bin/setup` script. +3. Get SHA256 hash: ```bash -# Download tarball from GitHub and compute hash +# Download tarball from GitHub and calculate 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) - +4. Create Homebrew tap: + Create a repository using [GitHub CLI(gh)](https://cli.github.com/) or [github.com/new](https://github.com/new). The public repository name must start with `homebrew-`, for example `homebrew-greet`: ```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 +# Or create and clone repository using the web interface $ cd homebrew-greet ``` -5. Place and Publish the Formula: - +5. Place and publish formula: ```bash $ cp /path/to/project/var/homebrew/greet.rb . $ git add greet.rb @@ -242,22 +236,19 @@ $ 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: - +6. Installation and distribution: + End users can start using the tool with just these commands. PHP environment and dependency package installation are handled automatically, so users don't need to worry about environment setup: ```bash -$ brew tap your-vendor/greet # The homebrew- prefix is omitted +$ brew tap your-vendor/greet # homebrew- prefix can be omitted $ brew install your-vendor/greet - # Ready to use immediately $ greet --version greet version 0.1.0 ``` -## Customizing the Formula +## Formula Customization -If necessary, you can edit the formula using the `brew edit` command: +You can edit the formula using the `brew edit` command as needed: ```bash $ brew edit your-vendor/greet @@ -268,70 +259,22 @@ 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 + sha256 "..." # tgz SHA256 version "0.1.0" - depends_on "php@8.1" # Specify PHP version + depends_on "php@8.4" # Specify PHP version depends_on "composer" - # Add if your application requires + # Add if required by the application # 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. +BEAR.Cli demonstrates the strengths of both Resource Oriented Architecture (ROA) and Clean Architecture. Following Clean Architecture's principle that "UI is a detail," you can add CLI as a new adapter alongside the web interface for the same resource. -Also, the CLI tool can be version-managed and updated independently of 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. +Furthermore, BEAR.Cli supports not only command creation but also distribution and updates through Homebrew. This allows end users to start using tools with a single command, treating them as native UNIX commands without awareness of PHP or BEAR.Sunday. +Additionally, CLI tools can be version-controlled and updated independently from the application repository. This means they can maintain stability and continuous updates as command-line tools without being affected by API evolution. This represents a new form of API delivery, realized through the combination of Resource Oriented Architecture and Clean Architecture. diff --git a/manuals/1.0/ja/325.cli.md b/manuals/1.0/ja/325.cli.md index 413eb387..d1dd86ee 100644 --- a/manuals/1.0/ja/325.cli.md +++ b/manuals/1.0/ja/325.cli.md @@ -18,7 +18,6 @@ $ php page.php '/greeting?name=World&lang=ja' BEAR.Cliは、このようなリソースをネイティブなCLIコマンドに変換し、Homebrewで配布可能にするツールです: - ```bash $ greet -n "World" -l ja こんにちは, World @@ -75,13 +74,17 @@ class Greeting extends ResourceObject ### CLIコマンドとフォーミュラの生成 +リソースをコマンドにするには、以下のようにアプリケーション名(ベンダー名とプロジェクト名)を指定してコマンドを実行します: + ```bash -$ vendor/bin/bear-cli-gen MyVendor.MyProject +$ vendor/bin/bear-cli-gen 'MyVendor\MyProject' # 生成されたファイル: -# bin/cli/greet   # CLIコマンド -# var/homebrew/greet.rb # Homebrewフォーミュラ +# bin/cli/greet # CLIコマンド +# var/homebrew/greet.rb # Homebrewフォーミュラ ``` +Homebrewフォーミュラが生成されるのはGitHubでリポジトリが設定されている場合のみです。 + ## コマンドの使用方法 生成されたコマンドは以下のような標準的なCLI機能を提供します: @@ -150,7 +153,8 @@ CLIコマンドの出力は以下の仕様に基づきます: ## 配布方法 -BEAR.Cliで作成したコマンドは、以下の2つの方法でHomebrewを通じて配布できます: +BEAR.Cliで作成したコマンドは、Homebrewを通じて配布できます。 +フォーミュラの生成にはアプリケーションがGitHubで公開されていることが必要です: ### 1. ローカルフォーミュラによる配布 @@ -160,11 +164,6 @@ BEAR.Cliで作成したコマンドは、以下の2つの方法でHomebrewを通 $ brew install --formula ./var/homebrew/greet.rb ``` -この方法は以下の場合に適しています: -- プライベートプロジェクト -- 開発中のテスト -- 社内ツールの配布 - ### 2. Homebrewタップによる配布 公開リポジトリを使用して広く配布する方法です: @@ -174,9 +173,9 @@ $ brew tap your-vendor/greet $ brew install your-vendor/greet ``` -この方法は以下の場合に適しています: +この方法は特に以下の場合に適しています: + - オープンソースプロジェクト -- 公開ツールの配布 - 継続的なアップデートの提供 #### 開発版のテスト @@ -184,6 +183,10 @@ $ brew install your-vendor/greet ```bash $ brew install --HEAD ./var/homebrew/greet.rb ``` +```bash +$ greet --version +greet version 0.1.0 +``` #### 安定版のリリース @@ -207,7 +210,6 @@ $ git push origin v0.1.0 depends_on "composer" end ``` - フォーミュラには必要に応じてデータベースなどの依存関係を追加できます。ただし、データベースのセットアップなどの環境構築は `bin/setup` スクリプトで行うことを推奨します。 3. SHA256ハッシュの取得: @@ -217,17 +219,11 @@ $ curl -sL https://github.com/your-vendor/your-project/archive/refs/tags/v0.1.0. ``` 4. Homebrewタップの作成: - -GitHub CLIのセットアップが必要です: -- [GitHub CLI のインストール](https://docs.github.com/ja/github-cli/github-cli/about-github-cli) -- [GitHub CLI の認証](https://cli.github.com/manual/gh_auth_login) - + [GitHub CLI(gh)](https://cli.github.com/)または[github.com/new](https://github.com/new)でリポジトリを作成してください。公開リポジトリ名は`homebrew-`で始める必要があります。たとえば`homebrew-greet`です: ```bash -# GitHub CLIで認証 $ gh auth login - -# 公開リポジトリ名はhomebrew-で始める必要があります $ gh repo create your-vendor/homebrew-greet --public --clone +# または、Webインターフェースを使用してリポジトリを作成してcloneしてください $ cd homebrew-greet ``` @@ -240,13 +236,10 @@ $ git push ``` 6. インストールと配布: - -エンドユーザーは以下のコマンドだけでツールを使い始めることができます。PHP環境や依存パッケージのインストールは自動的に行われるため、ユーザーが環境構築について心配する必要はありません: - + エンドユーザーは以下のコマンドだけでツールを使い始めることができます。PHP環境や依存パッケージのインストールは自動的に行われるため、ユーザーが環境構築について心配する必要はありません: ```bash -$ brew tap your-vendor/greet # homebrew-プレフィックスは省略 +$ brew tap your-vendor/greet # homebrew-プレフィックスは省略可能 $ brew install your-vendor/greet - # すぐに使用可能 $ greet --version greet version 0.1.0 @@ -268,7 +261,7 @@ class Greet < Formula sha256 "..." # tgzのSHA256 version "0.1.0" - depends_on "php@8.1" # PHPバージョンの指定 + depends_on "php@8.4" # PHPバージョンの指定 depends_on "composer" # アプリケーションが必要とする場合は追加 @@ -277,54 +270,6 @@ class Greet < Formula end ``` -## バージョン管理 - -特定のバージョンに固定する場合: - -```bash - -# バージョンの固定 -$ brew pin your-vendor/greet - -# 固定解除 -$ brew unpin your-vendor/greet -``` - -## デプロイ - -継続的デプロイメントのために、以下のような手順が推奨されます: - -1. 開発環境での確認 - -```bash -$ brew install --HEAD ./var/homebrew/greet.rb -$ greet --version # バージョン確認 -$ greet --help # ヘルプの確認 -``` - -2. リリースとデプロイ - -```bash -# バージョンタグの作成 -$ git tag -a v0.1.0 -m "Initial stable release" -$ git push origin v0.1.0 - -# Homebrewタップの更新 -$ 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. インストールの確認 - -```bash -$ brew update -$ brew install your-vendor/greet -$ greet --version # 新しいバージョンの確認 -``` - ## クリーンアーキテクチャ BEAR.Cliは、リソース指向アーキテクチャ(ROA)とクリーンアーキテクチャの強みを実証しています。クリーンアーキテクチャが目指す「UIは詳細である」という原則に従い、同じリソースに対してWebインターフェースだけでなく、CLIという新しいアダプターを追加できます。