casting-cli 0.4.0

# Casting

[![Crates.io](https://img.shields.io/crates/v/casting-cli.svg)](https://crates.io/crates/casting-cli)
[![Documentation](https://docs.rs/casting-cli/badge.svg)](https://docs.rs/casting-cli)
[![License](https://img.shields.io/crates/l/casting-cli.svg)](https://github.com/ynishi/casting#license)
[![Downloads](https://img.shields.io/crates/d/casting-cli.svg)](https://crates.io/crates/casting-cli)

**Cast a Persona onto your CLI** 🎭

Casting is a wrapper tool that gives existing CLI tools an AI-driven "personality". Transform mundane command-line tools into friendly characters that assist you.

## ✨ Features

- **Easy Setup**: Automatically generate system prompts from existing tool's `--help` output or OpenAPI specs
- **Customizable Personas**: Specify personality with keywords like `akarui` (cheerful), `teineina` (polite)
- **Claude Code Integration**: Launch Claude Code with generated prompts for interactive REPL dialogue
- **API Support**: Create personas for REST APIs using OpenAPI v3 specifications
- **Backward Compatible**: Automatic migration of old configurations to new format

## 🚀 Quick Start

### Installation

#### Option 1: Install from crates.io (Recommended)

```bash
cargo install casting-cli
```

#### Option 2: Install from source

```bash
git clone https://github.com/ynishi/casting.git
cd casting
cargo install --path crates/casting-cli
```

After installation, the `casting` command will be available in your PATH.

**Shell Completion (Optional)**

To enable shell completion for zsh, run:

```bash
casting completion zsh > ~/.zsh/completions/_casting
```

Then add the following to your `~/.zshrc` if not already present:

```bash
fpath=(~/.zsh/completion $fpath)
autoload -Uz compinit && compinit
```

For other shells (bash, fish, powershell, elvish), replace `zsh` with the appropriate shell name.

#### Option 2: Build without installing

```bash
git clone https://github.com/yourusername/casting.git
cd casting
cargo build --release
```

Use `./target/release/casting` to run the tool.

### Basic Usage

#### 1. Create Tool Configuration

**For CLI Tools:**
```bash
# Configure git with a "polite" persona
casting make git --persona teineina

# Configure ls with a "cheerful" persona
casting make ls --persona akarui
```

**For APIs (OpenAPI v3):**
```bash
# Configure Petstore API with a "cheerful" persona
casting make petstore \
  --spec https://petstore3.swagger.io/api/v3/openapi.json \
  --base-url https://petstore3.swagger.io/api/v3 \
  --persona akarui
```

#### 2. List Configured Tools

```bash
casting list
```

Example output:
```
📁 Configured Tools:

  petstore
    🎭 Persona: akarui
    🌐 Type: API
    📍 Base URL: https://petstore3.swagger.io/api/v3
    📄 Spec: https://petstore3.swagger.io/api/v3/openapi.json
    📅 Created: 2025-11-28 03:02:26

  git
    🎭 Persona: teineina
    📍 Type: CLI
    📍 Binary: /opt/homebrew/bin/git
    📅 Created: 2025-11-23 13:17:03

  ls
    🎭 Persona: akarui
    📍 Type: CLI
    📍 Binary: /bin/ls
    📅 Created: 2025-11-23 13:16:10

💡 Use with: casting repl <TOOL>
```

#### 3. Start REPL

**For CLI Tools:**
```bash
casting repl git
```

Claude Code launches and behaves as the `git` persona:

```
> Introduce yourself!

⏺ Hello! I'm Git 🌿

  I'm a version control system here to support
  your code development with utmost care.

  ...
```

**For APIs:**
```bash
casting repl petstore
```

Claude Code launches with the Petstore API persona and can make API calls on your behalf:

```
> Show me all available pets!

⏺ Let me fetch all the pets for you! ✨

  [Makes API call via Bash tool...]
  curl -X GET "https://petstore3.swagger.io/api/v3/pet/findByStatus?status=available"

  Found 3 available pets! 🐾
  ...
```

## 🎭 Persona Examples

| Keyword | Personality | Speech Example |
|---------|------------|----------------|
| `akarui` | Cheerful, energetic | "~だよ!" "超~" "💪✨" |
| `teineina` | Polite, calm | "~と申します" "させていただきます" |
| `yukai` | Humorous, fun | "~だぜ!" "ふふふ" "🎉" |
| `shinsetsu` | Kind, gentle | "大丈夫ですよ" "ゆっくりで" "😊" |

**※ Can be created without persona** - defaults to standard support tone

## 🌐 API Support

Casting supports OpenAPI v3 specifications, allowing you to create personas for REST APIs.

### Requirements

- **OpenAPI v3 only**: Swagger v2 is not supported
- **Spec URL**: Must be accessible via HTTP/HTTPS
- **Base URL**: The API's base endpoint

### Features

- **Automatic Documentation**: Parses OpenAPI spec and generates human-readable endpoint documentation
- **Persona Integration**: APIs can have personalities just like CLI tools
- **Claude-Powered Interactions**: Claude Code uses the Bash tool to make curl requests on your behalf

### Example: Creating an API Persona

```bash
# Public OpenAPI v3 APIs
casting make petstore \
  --spec https://petstore3.swagger.io/api/v3/openapi.json \
  --base-url https://petstore3.swagger.io/api/v3 \
  --persona akarui

# Your own API
casting make myapi \
  --spec https://api.example.com/openapi.json \
  --base-url https://api.example.com/v1 \
  --persona teineina
```

## 📂 Project Structure

```
casting/
├── crates/
│   ├── casting-cli/    # Main CLI tool
├── docs/
│   └── design/         # Design documents
│       └── overview.md
└── README.md
```

## 🛣️ Roadmap

- [x] **MVP Implementation**
  - [x] `casting make` - Create tool configuration
  - [x] `casting list` - List configured tools
  - [x] `casting repl` - Launch Claude Code
- [x] **API Support**
  - [x] OpenAPI v3 spec parsing
  - [x] API endpoint documentation generation
  - [x] API personas with curl integration
  - [x] Backward-compatible config migration (v1 → v2)

## 📝 Design Documents

For detailed design philosophy and architecture, refer to:

- [Design Overview](./docs/design/overview.md) - Architecture and implementation approach

## 🤝 Contributing

Issues and Pull Requests are welcome!

## 📄 License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.