Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation for BEAR.Cli command usage and distribution #296

Merged
merged 1 commit into from
Nov 14, 2024
Merged

Update documentation for BEAR.Cli command usage and distribution #296

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
173 changes: 58 additions & 115 deletions manuals/1.0/en/325.cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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;
Expand Down Expand Up @@ -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

Expand All @@ -101,7 +105,7 @@ Options:
--format Output format (text|json) (default: text)
```

### Displaying Version Information
### Showing Version Information

```bash
$ greet --version
Expand Down Expand Up @@ -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"

Expand All @@ -209,55 +211,44 @@ $ 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
$ 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
Expand All @@ -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
koriym marked this conversation as resolved.
Show resolved Hide resolved
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.
Loading