@vicoa/cli 0.1.3 → 0.1.4-darwin-arm64

package/bin/_internal/integrations/github/claude-code-action/docs/configuration.md

@@ -0,0 +1,345 @@
+# Advanced Configuration
+
+## Using Custom MCP Configuration
+
+You can add custom MCP (Model Context Protocol) servers to extend Claude's capabilities using the `--mcp-config` flag in `claude_args`. These servers merge with the built-in GitHub MCP servers.
+
+### Basic Example: Adding a Sequential Thinking Server
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+    claude_args: |
+      --mcp-config '{"mcpServers": {"sequential-thinking": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]}}}'
+      --allowedTools mcp__sequential-thinking__sequentialthinking
+    # ... other inputs
+```
+
+### Passing Secrets to MCP Servers
+
+For MCP servers that require sensitive information like API keys or tokens, you can create a configuration file with GitHub Secrets:
+
+```yaml
+- name: Create MCP Config
+  run: |
+    cat > /tmp/mcp-config.json << 'EOF'
+    {
+      "mcpServers": {
+        "custom-api-server": {
+          "command": "npx",
+          "args": ["-y", "@example/api-server"],
+          "env": {
+            "API_KEY": "${{ secrets.CUSTOM_API_KEY }}",
+            "BASE_URL": "https://api.example.com"
+          }
+        }
+      }
+    }
+    EOF
+
+- uses: anthropics/claude-code-action@v1
+  with:
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+    claude_args: |
+      --mcp-config /tmp/mcp-config.json
+    # ... other inputs
+```
+
+### Using Python MCP Servers with uv
+
+For Python-based MCP servers managed with `uv`, you need to specify the directory containing your server:
+
+```yaml
+- name: Create MCP Config for Python Server
+  run: |
+    cat > /tmp/mcp-config.json << 'EOF'
+    {
+      "mcpServers": {
+        "my-python-server": {
+          "type": "stdio",
+          "command": "uv",
+          "args": [
+            "--directory",
+            "${{ github.workspace }}/path/to/server/",
+            "run",
+            "server_file.py"
+          ]
+        }
+      }
+    }
+    EOF
+
+- uses: anthropics/claude-code-action@v1
+  with:
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+    claude_args: |
+      --mcp-config /tmp/mcp-config.json
+      --allowedTools my-python-server__<tool_name>  # Replace <tool_name> with your server's tool names
+    # ... other inputs
+```
+
+For example, if your Python MCP server is at `mcp_servers/weather.py`, you would use:
+
+```yaml
+"args":
+  ["--directory", "${{ github.workspace }}/mcp_servers/", "run", "weather.py"]
+```
+
+### Multiple MCP Servers
+
+You can add multiple MCP servers by using multiple `--mcp-config` flags:
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+    claude_args: |
+      --mcp-config /tmp/config1.json
+      --mcp-config /tmp/config2.json
+      --mcp-config '{"mcpServers": {"inline-server": {"command": "npx", "args": ["@example/server"]}}}'
+    # ... other inputs
+```
+
+**Important**:
+
+- Always use GitHub Secrets (`${{ secrets.SECRET_NAME }}`) for sensitive values like API keys, tokens, or passwords. Never hardcode secrets directly in the workflow file.
+- Your custom servers will override any built-in servers with the same name.
+- The `claude_args` supports multiple `--mcp-config` flags that will be merged together.
+
+## Additional Permissions for CI/CD Integration
+
+The `additional_permissions` input allows Claude to access GitHub Actions workflow information when you grant the necessary permissions. This is particularly useful for analyzing CI/CD failures and debugging workflow issues.
+
+### Enabling GitHub Actions Access
+
+To allow Claude to view workflow run results, job logs, and CI status:
+
+1. **Grant the necessary permission to your GitHub token**:
+
+   - When using the default `GITHUB_TOKEN`, add the `actions: read` permission to your workflow:
+
+   ```yaml
+   permissions:
+     contents: write
+     pull-requests: write
+     issues: write
+     actions: read # Add this line
+   ```
+
+2. **Configure the action with additional permissions**:
+
+   ```yaml
+   - uses: anthropics/claude-code-action@beta
+     with:
+       anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+       additional_permissions: |
+         actions: read
+       # ... other inputs
+   ```
+
+3. **Claude will automatically get access to CI/CD tools**:
+   When you enable `actions: read`, Claude can use the following MCP tools:
+   - `mcp__github_ci__get_ci_status` - View workflow run statuses
+   - `mcp__github_ci__get_workflow_run_details` - Get detailed workflow information
+   - `mcp__github_ci__download_job_log` - Download and analyze job logs
+
+### Example: Debugging Failed CI Runs
+
+```yaml
+name: Claude CI Helper
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+  actions: read # Required for CI access
+
+jobs:
+  claude-ci-helper:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: anthropics/claude-code-action@beta
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          additional_permissions: |
+            actions: read
+          # Now Claude can respond to "@claude why did the CI fail?"
+```
+
+**Important Notes**:
+
+- The GitHub token must have the `actions: read` permission in your workflow
+- If the permission is missing, Claude will warn you and suggest adding it
+- Currently, only `actions: read` is supported, but the format allows for future extensions
+
+## Custom Environment Variables
+
+You can pass custom environment variables to Claude Code execution using the `settings` input. This is useful for CI/test setups that require specific environment variables:
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    settings: |
+      {
+        "env": {
+          "NODE_ENV": "test",
+          "CI": "true",
+          "DATABASE_URL": "postgres://test:test@localhost:5432/test_db"
+        }
+      }
+    # ... other inputs
+```
+
+These environment variables will be available to Claude Code during execution, allowing it to run tests, build processes, or other commands that depend on specific environment configurations.
+
+## Limiting Conversation Turns
+
+You can limit the number of back-and-forth exchanges Claude can have during task execution using the `claude_args` input. This is useful for:
+
+- Controlling costs by preventing runaway conversations
+- Setting time boundaries for automated workflows
+- Ensuring predictable behavior in CI/CD pipelines
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+    claude_args: |
+      --max-turns 5  # Limit to 5 conversation turns
+    # ... other inputs
+```
+
+When the turn limit is reached, Claude will stop execution gracefully. Choose a value that gives Claude enough turns to complete typical tasks while preventing excessive usage.
+
+## Custom Tools
+
+By default, Claude only has access to:
+
+- File operations (reading, committing, editing files, read-only git commands)
+- Comment management (creating/updating comments)
+- Basic GitHub operations
+
+Claude does **not** have access to execute arbitrary Bash commands by default. If you want Claude to run specific commands (e.g., npm install, npm test), you must explicitly allow them using the `claude_args` configuration:
+
+**Note**: If your repository has a `.mcp.json` file in the root directory, Claude will automatically detect and use the MCP server tools defined there. However, these tools still need to be explicitly allowed.
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    claude_args: |
+      --allowedTools "Bash(npm install),Bash(npm run test),Edit,Replace,NotebookEditCell"
+      --disallowedTools "TaskOutput,KillTask"
+    # ... other inputs
+```
+
+**Note**: The base GitHub tools are always included. Use `--allowedTools` to add additional tools (including specific Bash commands), and `--disallowedTools` to prevent specific tools from being used.
+
+## Custom Model
+
+Specify a Claude model using `claude_args`:
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    claude_args: |
+      --model claude-4-0-sonnet-20250805
+    # ... other inputs
+```
+
+For provider-specific models:
+
+```yaml
+# AWS Bedrock
+- uses: anthropics/claude-code-action@v1
+  with:
+    use_bedrock: "true"
+    claude_args: |
+      --model anthropic.claude-4-0-sonnet-20250805-v1:0
+    # ... other inputs
+
+# Google Vertex AI
+- uses: anthropics/claude-code-action@v1
+  with:
+    use_vertex: "true"
+    claude_args: |
+      --model claude-4-0-sonnet@20250805
+    # ... other inputs
+```
+
+## Claude Code Settings
+
+You can provide Claude Code settings to customize behavior such as model selection, environment variables, permissions, and hooks. Settings can be provided either as a JSON string or a path to a settings file.
+
+### Option 1: Settings File
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    settings: "path/to/settings.json"
+    # ... other inputs
+```
+
+### Option 2: Inline Settings
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    settings: |
+      {
+        "model": "claude-opus-4-1-20250805",
+        "env": {
+          "DEBUG": "true",
+          "API_URL": "https://api.example.com"
+        },
+        "permissions": {
+          "allow": ["Bash", "Read"],
+          "deny": ["WebFetch"]
+        },
+        "hooks": {
+          "PreToolUse": [{
+            "matcher": "Bash",
+            "hooks": [{
+              "type": "command",
+              "command": "echo Running bash command..."
+            }]
+          }]
+        }
+      }
+    # ... other inputs
+```
+
+The settings support all Claude Code settings options including:
+
+- `model`: Override the default model
+- `env`: Environment variables for the session
+- `permissions`: Tool usage permissions
+- `hooks`: Pre/post tool execution hooks
+- And more...
+
+For a complete list of available settings and their descriptions, see the [Claude Code settings documentation](https://docs.anthropic.com/en/docs/claude-code/settings).
+
+**Notes**:
+
+- The `enableAllProjectMcpServers` setting is always set to `true` by this action to ensure MCP servers work correctly.
+- The `claude_args` input provides direct access to Claude Code CLI arguments and takes precedence over settings.
+- We recommend using `claude_args` for simple configurations and `settings` for complex configurations with hooks and environment variables.
+
+## Migration from Deprecated Inputs
+
+Many individual input parameters have been consolidated into `claude_args` or `settings`. Here's how to migrate:
+
+| Old Input             | New Approach                                             |
+| --------------------- | -------------------------------------------------------- |
+| `allowed_tools`       | Use `claude_args: "--allowedTools Tool1,Tool2"`          |
+| `disallowed_tools`    | Use `claude_args: "--disallowedTools Tool1,Tool2"`       |
+| `max_turns`           | Use `claude_args: "--max-turns 10"`                      |
+| `model`               | Use `claude_args: "--model claude-4-0-sonnet-20250805"`  |
+| `claude_env`          | Use `settings` with `"env"` object                       |
+| `custom_instructions` | Use `claude_args: "--system-prompt 'Your instructions'"` |
+| `mcp_config`          | Use `claude_args: "--mcp-config '{...}'"`                |
+| `direct_prompt`       | Use `prompt` input instead                               |
+| `override_prompt`     | Use `prompt` with GitHub context variables               |

package/bin/_internal/integrations/github/claude-code-action/docs/custom-automations.md

@@ -0,0 +1,113 @@
+# Custom Automations
+
+These examples show how to configure Claude to act automatically based on GitHub events. When you provide a `prompt` input, the action automatically runs in agent mode without requiring manual @mentions. Without a `prompt`, it runs in interactive mode, responding to @claude mentions.
+
+## Supported GitHub Events
+
+This action supports the following GitHub events ([learn more GitHub event triggers](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows)):
+
+- `pull_request` - When PRs are opened or synchronized
+- `issue_comment` - When comments are created on issues or PRs
+- `pull_request_comment` - When comments are made on PR diffs
+- `issues` - When issues are opened or assigned
+- `pull_request_review` - When PR reviews are submitted
+- `pull_request_review_comment` - When comments are made on PR reviews
+- `repository_dispatch` - Custom events triggered via API (coming soon)
+- `workflow_dispatch` - Manual workflow triggers (coming soon)
+
+## Automated Documentation Updates
+
+Automatically update documentation when specific files change (see [`examples/claude-pr-path-specific.yml`](../examples/claude-pr-path-specific.yml)):
+
+```yaml
+on:
+  pull_request:
+    paths:
+      - "src/api/**/*.ts"
+
+steps:
+  - uses: anthropics/claude-code-action@v1
+    with:
+      prompt: |
+        Update the API documentation in README.md to reflect
+        the changes made to the API endpoints in this PR.
+      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+When API files are modified, the action automatically detects that a `prompt` is provided and runs in agent mode. Claude updates your README with the latest endpoint documentation and pushes the changes back to the PR, keeping your docs in sync with your code.
+
+## Author-Specific Code Reviews
+
+Automatically review PRs from specific authors or external contributors (see [`examples/claude-review-from-author.yml`](../examples/claude-review-from-author.yml)):
+
+```yaml
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  review-by-author:
+    if: |
+      github.event.pull_request.user.login == 'developer1' ||
+      github.event.pull_request.user.login == 'external-contributor'
+    steps:
+      - uses: anthropics/claude-code-action@v1
+        with:
+          prompt: |
+            Please provide a thorough review of this pull request.
+            Pay extra attention to coding standards, security practices,
+            and test coverage since this is from an external contributor.
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+Perfect for automatically reviewing PRs from new team members, external contributors, or specific developers who need extra guidance. The action automatically runs in agent mode when a `prompt` is provided.
+
+## Custom Prompt Templates
+
+Use the `prompt` input with GitHub context variables for dynamic automation:
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    prompt: |
+      Analyze PR #${{ github.event.pull_request.number }} in ${{ github.repository }} for security vulnerabilities.
+
+      Focus on:
+      - SQL injection risks
+      - XSS vulnerabilities
+      - Authentication bypasses
+      - Exposed secrets or credentials
+
+      Provide severity ratings (Critical/High/Medium/Low) for any issues found.
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+You can access any GitHub context variable using the standard GitHub Actions syntax:
+
+- `${{ github.repository }}` - The repository name
+- `${{ github.event.pull_request.number }}` - PR number
+- `${{ github.event.issue.number }}` - Issue number
+- `${{ github.event.pull_request.title }}` - PR title
+- `${{ github.event.pull_request.body }}` - PR description
+- `${{ github.event.comment.body }}` - Comment text
+- `${{ github.actor }}` - User who triggered the workflow
+- `${{ github.base_ref }}` - Base branch for PRs
+- `${{ github.head_ref }}` - Head branch for PRs
+
+## Advanced Configuration with claude_args
+
+For more control over Claude's behavior, use the `claude_args` input to pass CLI arguments directly:
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    prompt: "Review this PR for performance issues"
+    claude_args: |
+      --max-turns 15
+      --model claude-4-0-sonnet-20250805
+      --allowedTools Edit,Read,Write,Bash
+      --system-prompt "You are a performance optimization expert. Focus on identifying bottlenecks and suggesting improvements."
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+This provides full access to Claude Code CLI capabilities while maintaining the simplified action interface.

package/bin/_internal/integrations/github/claude-code-action/docs/experimental.md

@@ -0,0 +1,128 @@
+# Experimental Features
+
+**Note:** Experimental features are considered unstable and not supported for production use. They may change or be removed at any time.
+
+## Automatic Mode Detection
+
+The action intelligently detects the appropriate execution mode based on your workflow context, eliminating the need for manual mode configuration.
+
+### Interactive Mode (Tag Mode)
+
+Activated when Claude detects @mentions, issue assignments, or labels—without an explicit `prompt`.
+
+- **Triggers**: `@claude` mentions in comments, issue assignment to claude user, label application
+- **Features**: Creates tracking comments with progress checkboxes, full implementation capabilities
+- **Use case**: Interactive code assistance, Q&A, and implementation requests
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+    # No prompt needed - responds to @claude mentions
+```
+
+### Automation Mode (Agent Mode)
+
+Automatically activated when you provide a `prompt` input.
+
+- **Triggers**: Any GitHub event when `prompt` input is provided
+- **Features**: Direct execution without requiring @claude mentions, streamlined for automation
+- **Use case**: Automated PR reviews, scheduled tasks, workflow automation
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+    prompt: |
+      Check for outdated dependencies and create an issue if any are found.
+    # Automatically runs in agent mode when prompt is provided
+```
+
+### How It Works
+
+The action uses this logic to determine the mode:
+
+1. **If `prompt` is provided** → Runs in **agent mode** for automation
+2. **If no `prompt` but @claude is mentioned** → Runs in **tag mode** for interaction
+3. **If neither** → No action is taken
+
+This automatic detection ensures your workflows are simpler and more intuitive, without needing to understand or configure different modes.
+
+### Advanced Mode Control
+
+For specialized use cases, you can fine-tune behavior using `claude_args`:
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    prompt: "Review this PR"
+    claude_args: |
+      --max-turns 20
+      --system-prompt "You are a code review specialist"
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+## Network Restrictions
+
+For enhanced security, you can restrict Claude's network access to specific domains only. This feature is particularly useful for:
+
+- Enterprise environments with strict security policies
+- Preventing access to external services
+- Limiting Claude to only your internal APIs and services
+
+When `experimental_allowed_domains` is set, Claude can only access the domains you explicitly list. You'll need to include the appropriate provider domains based on your authentication method.
+
+### Provider-Specific Examples
+
+#### If using Anthropic API or subscription
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+    # Or: claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+    experimental_allowed_domains: |
+      .anthropic.com
+```
+
+#### If using AWS Bedrock
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    use_bedrock: "true"
+    experimental_allowed_domains: |
+      bedrock.*.amazonaws.com
+      bedrock-runtime.*.amazonaws.com
+```
+
+#### If using Google Vertex AI
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    use_vertex: "true"
+    experimental_allowed_domains: |
+      *.googleapis.com
+      vertexai.googleapis.com
+```
+
+### Common GitHub Domains
+
+In addition to your provider domains, you may need to include GitHub-related domains. For GitHub.com users, common domains include:
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+    experimental_allowed_domains: |
+      .anthropic.com  # For Anthropic API
+      .github.com
+      .githubusercontent.com
+      ghcr.io
+      .blob.core.windows.net
+```
+
+For GitHub Enterprise users, replace the GitHub.com domains above with your enterprise domains (e.g., `.github.company.com`, `packages.company.com`, etc.).
+
+To determine which domains your workflow needs, you can temporarily run without restrictions and monitor the network requests, or check your GitHub Enterprise configuration for the specific services you use.